feat(plugins): expose install source facts

[vincentkoc]

Summary

• add normalized install-source facts for provider and channel install catalog entries
• classify npm specs by selector type, exact-version status, integrity presence, and pin state
• surface warnings for floating npm specs, missing integrity pins, and invalid npm specs
• document Phase 1 source-plane behavior and the preferred exact spec + integrity shape for official external npm entries

Validation

• pnpm test src/plugins/install-source-info.test.ts src/plugins/provider-install-catalog.test.ts src/channels/plugins/contracts/plugins-core.catalog.entries.contract.test.ts
• pnpm format:check src/plugins/install-source-info.ts src/plugins/install-source-info.test.ts src/plugins/provider-install-catalog.ts src/plugins/provider-install-catalog.test.ts src/channels/plugins/catalog.ts test/helpers/channels/channel-plugin-catalog-contract-suites.ts docs/plugins/architecture-internals.md docs/plugins/manifest.md
• pnpm test:contracts:channels
• pnpm test:contracts:plugins
• filtered pnpm tsgo:core check found no touched-file errors

Known failures

• pnpm check:changed fails in src/agents/openai-transport-stream.ts / src/plugin-sdk/provider-tools.ts on existing OpenAI compat type errors
• pnpm build reaches build:plugin-sdk:dts and fails on the same unrelated OpenAI compat type errors

Notes

• AI-assisted: yes

[greptile-apps]

Greptile Summary

This PR adds a describePluginInstallSource utility that normalizes npm install-source metadata into a structured PluginInstallSourceInfo fact object, and surfaces it on both ChannelPluginCatalogEntry and ProviderInstallCatalogEntry. The implementation, type definitions, and tests are clean and well-scoped.

Confidence Score: 5/5

Safe to merge — all findings are minor P2 style/coverage observations with no impact on correctness in realistic inputs.

Both remaining comments are P2: one is an edge-case inconsistency only reachable with a whitespace-only integrity string (not a realistic catalog value), and the other is a missing test quadrant. No logic errors, data-loss risk, or broken contracts were found.

No files require special attention.

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/plugins/install-source-info.ts
Line: 58-72

Comment:
**Whitespace-only `expectedIntegrity` produces inconsistent output**

`hasIntegrity` uses `.trim()` to guard against whitespace strings, but the spread that writes `expectedIntegrity` onto the `npm` object checks the raw value — a whitespace-only string passes the truthy guard and ends up in the output while `pinState` says `"exact-without-integrity"` and `"npm-spec-missing-integrity"` is in `warnings`. All three fields would disagree about whether integrity is present.

```ts
const trimmedIntegrity = install.expectedIntegrity?.trim();
const hasIntegrity = Boolean(trimmedIntegrity);
// ...
npm = {
  // ...
  ...(trimmedIntegrity ? { expectedIntegrity: trimmedIntegrity } : {}),
};
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/plugins/install-source-info.test.ts
Line: 1-58

Comment:
**Missing coverage for `exact-without-integrity` pin state**

The three existing tests cover `exact-with-integrity`, `floating-without-integrity`, and `invalid-npm-spec`. The fourth combination — an exact semver spec that omits `expectedIntegrity` — is never exercised. That case emits only `"npm-spec-missing-integrity"` and produces `pinState: "exact-without-integrity"`, which is a meaningful operational scenario (pinned version, no integrity hash). Adding a test for it would complete the four-quadrant coverage of the `PluginInstallNpmPinState` union.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "feat(plugins): expose install source fac..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4579a9304a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cf28e0a8d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".