feat: add install-info command and buildInstallSnippet API (#18)

* refactor: migrate cursor to the target registry (no behavior change)

Re-checking the originally planned Cursor "fixes" against the vendored
plugin.schema.json / marketplace.schema.json (this repo's own
conformance oracle, already passing against the current shape) showed
they were wrong:

- displayName/category/tags ARE valid plugin.json fields per the
  schema (additionalProperties: false, and they're explicitly listed)
  — not marketplace-entry-only fields as previously assumed.
- Marketplace `owner` is genuinely optional (required: ["name",
  "plugins"] does not include it) — not required as previously
  assumed. Moving category/tags to the marketplace entry would have
  been actively wrong: entries only allow name/source/description
  (additionalProperties: false).

None of that is changed here. What this commit actually does:

- Migrates cursor onto PluginTargetDefinition, preserving every
  existing field and behavior (verified by the vendored-schema
  conformance test staying green).
- Fixes one genuine, low-risk issue: the manifest builder's own
  hardcoded default-components list could diverge from this target's
  actual defaultComponents (components.ts). Replaced both with one
  list of schema-valid pointer fields, checked directly against the
  plugin's real resolved componentDirs — eliminates the divergence
  risk with no observable behavior change (confirmed via a new test
  exercising the one case that could have differed: an explicit
  `components: [...]` override).
- Ports update-check's hook-injection into the new shared engine
  (src/targets/engine.ts), which previously only existed in the
  legacy emitCursor/emitClaude path — migrating cursor without this
  would have silently dropped update-check support.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix: apply the per-plugin version override in cursor's manifest

buildPluginManifest used the target-level `version` param directly
instead of `pluginConfig.version ?? version`, silently dropping a
per-plugin version override — a real regression from the pre-migration
behavior, caught by porting the equivalent test from the claude
migration (no test previously covered this for cursor specifically).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: migrate claude to the target registry (no behavior change)

Ports emitClaude/validateClaude into src/targets/claude.ts as a
PluginTargetDefinition, verified directly against `claude plugin
validate --strict`: a minimal manifest with only `name` fails that
check, confirming the existing version/description/author.name
requirements already match the real CLI rather than over-constraining
it.

Applies the per-plugin version override in buildPluginManifest
(pluginConfig.version ?? version) up front, matching the identical fix
just made to cursor's copy of this pattern.

* fix: correct Codex plugin output for the target registry

Ports emitCodex/validateCodex into src/targets/codex.ts as a
PluginTargetDefinition, correcting the plugin format's real shape —
re-verified directly against developers.openai.com/codex/plugins/build
(fetched twice, independently, for consistency) since Codex has no
CLI validator or vendored schema to check against:

- plugin.json requires only "name"; version/description/author etc.
  are optional. The previous validator wrongly required version and
  description.
- Every marketplace entry needs policy.installation,
  policy.authentication, and category — previously unvalidated, so an
  incomplete entry shipped silently. pluginpack can't infer these, so
  the base entry stays guess-free and validateOutput now errors
  clearly when an author never supplies them via the per-plugin
  `entry` passthrough (already how the existing conformance fixture
  supplies them).
- A marketplace entry's source is a bare string only for local
  plugins (the only shape pluginpack itself ever emits); url/git-subdir/npm
  sources are structured objects with an inner "source" discriminator.
  validateMarketplaceEntry now accepts either shape instead of the
  previously shared, string-only validator.
- plugin.json now declares a `hooks` pointer when hooks/ is present,
  matching skills/mcpServers (previously only skills/mcpServers were
  declared, so hooks were emitted but never referenced).

Updates CONFORMANCE.md's Codex section, which had pinned a stale,
bare-string-only shape from an earlier doc retrieval.

* fix: restore deeper hooks.json validation dropped during target migration

Every migrated target's validateOutput calls validateHooksShape (added
in the registry scaffold), which only checked that hooks.json has a
"hooks" object — narrower than the legacy per-target validateHooks it
replaced, which also required each event's entries to be an array,
rejected empty "command" strings, and errored if a command referenced
the generated update-check script without that script actually being
present. None of that depth had a regression test, so the narrowing
was silent.

Ports the full check into validateHooksShape once, so every target
that already calls it (all 5, post-migration) regains it for free
instead of needing the fix repeated per target file.

* refactor: delete legacy per-target emitters/validators now that all targets are migrated

All 5 targets (copilot, antigravity, cursor, claude, codex) now have a
PluginTargetDefinition in src/targets/registry.ts, so the legacy
fallback path adapters.ts existed for is dead:

- Deletes src/targets.ts and src/validate.ts entirely (their only
  consumer was adapters.ts's legacyAdapters map).
- Moves withRootFiles into src/targets/engine.ts, next to the artifact
  helper it depends on.
- Tightens the registry's type from Partial<Record<TargetName, ...>>
  to Record<TargetName, ...> now that every target has an entry — a
  new TargetName won't build until it has a registry entry, the same
  exhaustiveness guarantee the deleted legacyAdapters map used to
  provide.
- Simplifies adapters.ts to a thin emitTarget/validateOutput wrapper
  around the registry + engine, dropping the now-pointless
  TargetAdapter/adapters indirection that existed only to switch
  between legacy and registry per target.
- Removes targetDefaultComponents/resolveTargetComponents from
  components.ts (superseded by each target's own defaultComponents).
- Updates CLAUDE.md's Architecture/Targets sections and a couple of
  stale doc-comment references to match.

* docs: note the shared hooks validation depth in CONFORMANCE.md

Cross-references the validateHooksShape fix from the prior commit —
what it checks and where it's shared from, for the conformance doc's
own "what's actually verified and how" mandate.

* feat: add install-info command and buildInstallSnippet API

Adds the install-snippet feature designed alongside the target
registry migration: every PluginTargetDefinition already carries an
installSnippet (populated as each target migrated), so this wires it
up to a public API and CLI command rather than introducing new
per-target data.

- src/install-snippet.ts: buildInstallSnippet, getInstallSnippetCitation,
  getSupportedInstallTargets, getUnsupportedInstallTargets — thin
  wrappers around each target's registry entry.
- New `pluginpack install-info [--target <t>] [--json]` CLI command,
  defaulting to every configured target (matching `build`'s pattern).
  Resolves each plugin's path via that target's own resolvePluginPath
  for accuracy (antigravity's snippet is the one that consumes it).
- targets.<name>.repository config field (falls back to
  metadata.repository, mirroring updateCheck.repository's existing
  fallback) — "which repo does this target's output live in."
- Exported from the package entry for programmatic use.
- README: new "Install Snippet" section + Configuration Reference row
  + Programmatic API table rows. CONFORMANCE.md: "Install-snippet
  facts" table with per-target doc citations.

Tests: tests/install-snippet.test.ts locks in the exact snippet text
per target; tests/conformance.test.ts adds CLI end-to-end coverage
(default/--target/--json/missing-repository error) via the real built
binary.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: steve-calvert-glean

CONFORMANCE.md

@@ -96,6 +96,33 @@ target-agnostic: each event's entries must be an array, no `command` string
 may be empty, and any command referencing the generated update-check script
 (`scripts/pluginpack-update-check.sh`) must ship that script.
 
+## Install-snippet facts
+
+`pluginpack install-info` (and the `buildInstallSnippet` library function)
+prints the real command or URL a user needs to add a pluginpack-built
+marketplace. Each target's snippet and citation live on its own
+`PluginTargetDefinition.installSnippet` in `src/targets/<name>.ts`, verified
+directly against product docs:
+
+| Target        | Snippet                                                                                                                  | Source                                                                                                | Verified   |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ---------- |
+| `claude`      | `/plugin marketplace add <repo>` then `/plugin install <name>@<marketplace>` (slash-only)                                | <https://code.claude.com/docs/en/plugins-reference#cli-commands-reference>                            | 2026-07-25 |
+| `codex`       | `codex plugin marketplace add <repo>`                                                                                    | <https://learn.chatgpt.com/codex/developer-commands>                                                  | 2026-07-25 |
+| `copilot`     | `copilot plugin marketplace add <repo>` then `copilot plugin install <name>@<marketplace>`                               | <https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing> | 2026-07-25 |
+| `antigravity` | `git clone <repo> plugin-source && cd plugin-source && agy plugin install <pluginPath>`                                  | <https://antigravity.google/docs/cli/plugins>                                                         | 2026-07-25 |
+| `cursor`      | No CLI equivalent exists. Prints the repo URL, pasted into Dashboard → Plugins → Team Marketplaces → "Import from Repo." | <https://cursor.com/docs/plugins>                                                                     | 2026-07-25 |
+
+`claude`'s two-step sequence is not symmetric with `codex`/`copilot`'s shell
+commands: `/plugin marketplace add` is slash-only inside an active Claude Code
+session, with no shell equivalent — but once a marketplace is already added,
+`claude plugin install <name>@<marketplace>` does work as a standalone shell
+command, surfaced as a secondary `note`.
+
+Every target resolves to `userConfigurable: true` today;
+`getUnsupportedInstallTargets()` returns `[]`. The `false` branch of the
+`InstallSnippet` union exists for forward-compatibility, not because any
+target needs it now.
+
 ## Refreshing vendored schemas
 
 The Cursor schemas are pinned copies. To update them, re-fetch from the source

README.md

@@ -317,6 +317,17 @@ Disable for a single plugin with `updateCheck: false` on that plugin. Configurin
 
 Like MCP config, the generated hook is wired in regardless of a plugin's `components` selection: on `cursor`, the manifest's `hooks` field is set even if `components` doesn't include `"hooks"`, since the check itself is a separate opt-in from which source-authored component dirs get emitted.
 
+## Install Snippet
+
+Once a target's output is pushed to a repo, `pluginpack install-info` prints the real, doc-verified command or URL a user needs to add that marketplace — one per configured target:
+
+```bash
+pluginpack install-info
+pluginpack install-info --target claude
+```
+
+The repo comes from `targets.<name>.repository`, defaulting to `metadata.repository` (an error if neither is set) — the same fallback `updateCheck.repository` uses. Every target today resolves to a real command except `cursor`, which has no CLI equivalent: it prints the repo URL and a note to paste it into Cursor's Dashboard under Team Marketplaces. See `CONFORMANCE.md`'s "Install-snippet facts" section for the doc citation behind each target's snippet.
+
 ## Target Overrides
 
 Skill files are not always perfectly portable. When one app needs different frontmatter or content, add a target override next to the base file:
@@ -395,17 +406,18 @@ To publish a repo-root file (for example a README authored once in the source re
 
 **`targets.<name>`** — `<name>` is one of `cursor`, `claude`, `antigravity`, `copilot`, `codex`.
 
-| Field              | Type                   | Required | Meaning                                                                                    |
-| ------------------ | ---------------------- | -------- | ------------------------------------------------------------------------------------------ |
-| `outDir`           | string                 | yes      | Output directory for this target, relative to the config root.                             |
-| `plugins`          | record                 | yes      | Emitted plugins, keyed by emitted plugin name (see **`targets.<name>.plugins.<name>`**).   |
-| `marketplaceDir`   | string (safe relative) | no       | Override the marketplace dir (defaults: `.cursor-plugin` / `.claude-plugin`).              |
-| `pluginRoot`       | string (safe relative) | no       | Override the plugin root dir (`claude`; defaults to `plugins`).                            |
-| `version`          | string                 | no       | Override the version for this target (defaults to top-level `version`).                    |
-| `manifest`         | object                 | no       | Deep-merged into the generated marketplace manifest.                                       |
-| `ignoredDiffPaths` | string[]               | no       | Output-relative paths `diff` ignores (a dir entry ignores everything below it).            |
-| `rootFiles`        | record (safe relative) | no       | Map of output path → source path emitted verbatim at the output root.                      |
-| `updateCheck`      | `{ repository? }`      | no       | Generate a session-start update-check hook (`claude`/`cursor` only; see **Update Check**). |
+| Field              | Type                   | Required | Meaning                                                                                     |
+| ------------------ | ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `outDir`           | string                 | yes      | Output directory for this target, relative to the config root.                              |
+| `plugins`          | record                 | yes      | Emitted plugins, keyed by emitted plugin name (see **`targets.<name>.plugins.<name>`**).    |
+| `marketplaceDir`   | string (safe relative) | no       | Override the marketplace dir (defaults: `.cursor-plugin` / `.claude-plugin`).               |
+| `pluginRoot`       | string (safe relative) | no       | Override the plugin root dir (`claude`; defaults to `plugins`).                             |
+| `version`          | string                 | no       | Override the version for this target (defaults to top-level `version`).                     |
+| `manifest`         | object                 | no       | Deep-merged into the generated marketplace manifest.                                        |
+| `ignoredDiffPaths` | string[]               | no       | Output-relative paths `diff` ignores (a dir entry ignores everything below it).             |
+| `rootFiles`        | record (safe relative) | no       | Map of output path → source path emitted verbatim at the output root.                       |
+| `updateCheck`      | `{ repository? }`      | no       | Generate a session-start update-check hook (`claude`/`cursor` only; see **Update Check**).  |
+| `repository`       | string                 | no       | Repo this target's output lives in, for `install-info` (defaults to `metadata.repository`). |
 
 **`targets.<name>.plugins.<name>`**
 
@@ -434,18 +446,24 @@ import {
   validateOutput,
   prune,
   clean,
+  buildInstallSnippet,
+  getSupportedInstallTargets,
+  getUnsupportedInstallTargets,
 } from "@gleanwork/pluginpack";
 ```
 
-| Function                        | Returns                     | Purpose                                                          |
-| ------------------------------- | --------------------------- | ---------------------------------------------------------------- |
-| `defineConfig(config)`          | `PluginpackConfig`          | Identity helper that types `pluginpack.config.ts`.               |
-| `loadConfig(cwd?, configPath?)` | `Promise<ResolvedProject>`  | Resolve config and discover source plugins.                      |
-| `build(options?)`               | `Promise<Artifact[]>`       | Emit configured targets; writes to disk unless `options.dryRun`. |
-| `diffTarget(options)`           | `Promise<DiffResult>`       | Build into a temp dir and compare against an existing repo.      |
-| `validateOutput(target, dir)`   | `Promise<ValidationResult>` | Validate an existing target output directory.                    |
-| `prune(options?)`               | `Promise<CleanupResult[]>`  | Remove stale managed files no longer emitted by the config.      |
-| `clean(options?)`               | `Promise<CleanupResult[]>`  | Remove all managed files for configured targets.                 |
+| Function                              | Returns                     | Purpose                                                           |
+| ------------------------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `defineConfig(config)`                | `PluginpackConfig`          | Identity helper that types `pluginpack.config.ts`.                |
+| `loadConfig(cwd?, configPath?)`       | `Promise<ResolvedProject>`  | Resolve config and discover source plugins.                       |
+| `build(options?)`                     | `Promise<Artifact[]>`       | Emit configured targets; writes to disk unless `options.dryRun`.  |
+| `diffTarget(options)`                 | `Promise<DiffResult>`       | Build into a temp dir and compare against an existing repo.       |
+| `validateOutput(target, dir)`         | `Promise<ValidationResult>` | Validate an existing target output directory.                     |
+| `prune(options?)`                     | `Promise<CleanupResult[]>`  | Remove stale managed files no longer emitted by the config.       |
+| `clean(options?)`                     | `Promise<CleanupResult[]>`  | Remove all managed files for configured targets.                  |
+| `buildInstallSnippet(target, params)` | `InstallSnippet`            | The install command/URL for one target (see **Install Snippet**). |
+| `getSupportedInstallTargets()`        | `TargetName[]`              | Targets with a real install snippet today.                        |
+| `getUnsupportedInstallTargets()`      | `TargetName[]`              | Targets with none (empty today, kept for forward-compatibility).  |
 
 Option objects:
 
@@ -593,6 +611,30 @@ Exit codes:
 - 0 when managed files are removed or listed
 - 1 when config, manifest loading, or cleanup fails
 
+### `install-info`
+
+Print the real install command or URL for a target's built marketplace.
+
+```bash
+pluginpack install-info [--target copilot|antigravity|cursor|claude|codex] [--json]
+```
+
+Options:
+
+- `--target <target>`: Print only one configured target's install info.
+- `--json`: Print machine-readable JSON instead of text.
+
+Examples:
+
+- `pluginpack install-info`
+- `pluginpack install-info --target claude`
+- `pluginpack install-info --json`
+
+Exit codes:
+
+- 0 when install info is printed
+- 1 when config loading fails or a target has no repository configured
+
 ### `docs`
 
 Generate the README CLI reference section from command metadata.

src/cli.ts

@@ -5,7 +5,9 @@ import { build } from "./build.js";
 import { clean, prune } from "./cleanup.js";
 import { loadConfig } from "./config.js";
 import { diffTarget } from "./diff.js";
+import { buildInstallSnippet } from "./install-snippet.js";
 import { targetNames, validateOutput } from "./adapters.js";
+import { targets as targetRegistry } from "./targets/registry.js";
 import type { TargetName } from "./types.js";
 
 /** CLI entry point. */
@@ -198,6 +200,71 @@ function createProgram(): Command {
       },
     );
 
+  program
+    .command("install-info")
+    .description(
+      "Print the real install command or URL for a target's built marketplace.",
+    )
+    .usage(`[--target ${targetList}] [--json]`)
+    .addOption(
+      new Option(
+        "--target <target>",
+        "Print only one configured target's install info.",
+      ).choices([...targetNames]),
+    )
+    .option("--json", "Print machine-readable JSON instead of text.")
+    .action(async (options: { target?: TargetName; json?: boolean }) => {
+      const project = await loadConfig();
+      const targets = options.target
+        ? [options.target]
+        : targetNames.filter((target) => project.config.targets[target]);
+      const entries = targets.flatMap((target) => {
+        const targetConfig = project.config.targets[target];
+        if (!targetConfig) {
+          throw new Error(`Target "${target}" is not configured.`);
+        }
+        const repository =
+          targetConfig.repository ?? project.config.metadata?.repository;
+        if (!repository) {
+          throw new Error(
+            `Target "${target}" has no repository configured ` +
+              `(set targets.${target}.repository or metadata.repository).`,
+          );
+        }
+        return Object.entries(targetConfig.plugins).map(
+          ([pluginName, pluginConfig]) => ({
+            target,
+            plugin: pluginName,
+            snippet: buildInstallSnippet(target, {
+              repository,
+              marketplaceName: project.config.name,
+              pluginName,
+              pluginPath: targetRegistry[target].resolvePluginPath(
+                pluginName,
+                pluginConfig,
+                targetConfig,
+              ),
+            }),
+          }),
+        );
+      });
+      if (options.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+      }
+      for (const entry of entries) {
+        console.log(`${entry.target} / ${entry.plugin}`);
+        if (entry.snippet.userConfigurable) {
+          console.log(`  ${entry.snippet.snippet.replaceAll("\n", "\n  ")}`);
+          if (entry.snippet.note) {
+            console.log(`  note: ${entry.snippet.note}`);
+          }
+        } else {
+          console.log(`  unsupported: ${entry.snippet.reason}`);
+        }
+      }
+    });
+
   program
     .command("docs")
     .description(
@@ -383,6 +450,12 @@ function commandExamples(commandName: string): string[] {
       return ["pluginpack prune", "pluginpack prune --target claude --dry-run"];
     case "clean":
       return ["pluginpack clean", "pluginpack clean --target cursor --dry-run"];
+    case "install-info":
+      return [
+        "pluginpack install-info",
+        "pluginpack install-info --target claude",
+        "pluginpack install-info --json",
+      ];
     case "docs":
       return ["pluginpack docs", "pluginpack docs --check"];
     default:
@@ -420,6 +493,11 @@ function commandExitCodes(commandName: string): string[] {
         "0 when managed files are removed or listed",
         "1 when config, manifest loading, or cleanup fails",
       ];
+    case "install-info":
+      return [
+        "0 when install info is printed",
+        "1 when config loading fails or a target has no repository configured",
+      ];
     case "docs":
       return [
         "0 when docs are current or updated",

src/index.ts

@@ -4,6 +4,17 @@ export { build } from "./build.js";
 export { clean, prune } from "./cleanup.js";
 export { diffTarget } from "./diff.js";
 export { validateOutput } from "./adapters.js";
+export {
+  buildInstallSnippet,
+  getInstallSnippetCitation,
+  getSupportedInstallTargets,
+  getUnsupportedInstallTargets,
+} from "./install-snippet.js";
+export type {
+  Citation,
+  InstallParams,
+  InstallSnippet,
+} from "./install-snippet.js";
 export type {
   Artifact,
   Author,

src/install-snippet.ts

@@ -0,0 +1,54 @@
+import { targets as registry } from "./targets/registry.js";
+import type {
+  Citation,
+  InstallParams,
+  InstallSnippet,
+} from "./targets/types.js";
+import type { TargetName } from "./types.js";
+
+export type {
+  Citation,
+  InstallParams,
+  InstallSnippet,
+} from "./targets/types.js";
+
+/**
+ * Builds the real, doc-verified command or URL a user needs to add a
+ * pluginpack-built marketplace for `target`. See each target's
+ * `installSnippet.citation` (and `getInstallSnippetCitation`) for the source
+ * this is based on.
+ */
+export function buildInstallSnippet(
+  target: TargetName,
+  params: InstallParams,
+): InstallSnippet {
+  const definition = registry[target].installSnippet;
+  if (!definition.userConfigurable || !definition.build) {
+    return {
+      userConfigurable: false,
+      reason:
+        definition.unsupportedReason ??
+        `${target} has no install command or URL.`,
+    };
+  }
+  return { userConfigurable: true, ...definition.build(params) };
+}
+
+/** The citation backing `target`'s install snippet. */
+export function getInstallSnippetCitation(target: TargetName): Citation {
+  return registry[target].installSnippet.citation;
+}
+
+/** Targets with a real, user-configurable install snippet today. */
+export function getSupportedInstallTargets(): TargetName[] {
+  return (Object.keys(registry) as TargetName[]).filter(
+    (target) => registry[target].installSnippet.userConfigurable,
+  );
+}
+
+/** Targets with no install snippet — empty today, kept for forward-compatibility. */
+export function getUnsupportedInstallTargets(): TargetName[] {
+  return (Object.keys(registry) as TargetName[]).filter(
+    (target) => !registry[target].installSnippet.userConfigurable,
+  );
+}

src/schema.ts

@@ -75,6 +75,10 @@ const targetSchema = z.object({
   marketplaceDir: safeRelativePath.optional(),
   pluginRoot: safeRelativePath.optional(),
   version: z.string().optional(),
+  // The repo this target's output lives in, for install-snippet generation
+  // (falls back to metadata.repository) — the same "which repo" question
+  // updateCheck.repository answers, asked by a different feature.
+  repository: z.string().min(1).optional(),
   plugins: z.record(z.string(), emittedPluginSchema),
   manifest: z.record(z.string(), z.unknown()).optional(),
   ignoredDiffPaths: z.array(z.string()).optional(),