@vibe-agent-toolkit/cli 0.1.42 → 0.2.0-rc.2

package/dist/commands/cache/clear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAeH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAcrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkBrF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYtF"}

package/dist/commands/cache/clear.js

@@ -0,0 +1,162 @@
+/**
+ * `vat cache clear` — delete VAT's shared temp-directory cache tree.
+ *
+ * "Recovery is rescan" was true but had no user-invocable form: a corrupt or
+ * merely stale cache could only be cleared by hand-deleting a path the docs
+ * described in prose. This is that path, named once.
+ *
+ * Scope is the WHOLE `<tmpdir>/.vat-cache/` tree, not just the parse tenant.
+ * That directory is shared — `external-links.json`, `auth-<user>/` and `parse/`
+ * all live under it — and "clear the cache" cannot honestly mean "clear one of
+ * the three". All of them are disposable by construction.
+ */
+import { promises as fs } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { parseCacheDirectory } from '@vibe-agent-toolkit/resources';
+import { safePath } from '@vibe-agent-toolkit/utils';
+import { handleCommandError } from '../../utils/command-error.js';
+import { createLogger } from '../../utils/logger.js';
+import { writeYamlOutput } from '../../utils/output.js';
+/** The one name the shared cache root is allowed to have. See {@link vatCacheRoot}. */
+const VAT_CACHE_DIR_NAME = '.vat-cache';
+const EMPTY_USAGE = { entries: 0, bytes: 0 };
+/**
+ * The shared cache root, `<tmpdir>/.vat-cache`.
+ *
+ * Derived from `parseCacheDirectory()` rather than re-joining `normalizedTmpdir()`
+ * with a third copy of the `.vat-cache` literal — one authority for where the
+ * tree lives, and the CLI stays out of the path-resolution business.
+ *
+ * The name check is not decoration: this function's return value is handed
+ * straight to a recursive delete, so if `parseCacheDirectory()` ever stopped
+ * carrying a `parse/` leaf, the naive parent would be the system temp directory
+ * itself. Refusing an unexpected shape turns that into an error instead of an
+ * `rm -rf /tmp`.
+ *
+ * ⚠ `@vibe-agent-toolkit/resources` now also exports a `vatCacheRoot()`, and
+ * `parseCacheDirectory()` is built from it — so on paper this derivation is a
+ * round trip. It is kept deliberately: the guard's job is to notice if that
+ * relationship ever changes, and importing the root directly would retire the
+ * only check standing between a shape change and a recursive delete of
+ * `<tmpdir>` itself. Deriving-then-verifying is the point.
+ *
+ * ✅ **It has now earned that keep.** When the cache gained a per-build
+ * namespace, the layout went from `.vat-cache/parse` to
+ * `.vat-cache/<namespace>/parse` and the old single-`dirname` derivation
+ * started returning `.vat-cache/<namespace>`. The name check turned a silent
+ * change of delete target into a loud refusal. Anyone tempted to simplify this
+ * into an import should read that sentence twice.
+ *
+ * @returns Absolute path to the cache root
+ * @throws {Error} If the derived ancestor is not named `.vat-cache`
+ */
+export function vatCacheRoot() {
+    const parseDir = parseCacheDirectory();
+    // Up two: `<root>/<namespace>/parse` → `<root>`. The namespace level is what
+    // makes this two rather than one; see the note above about why it is still
+    // derived and verified rather than imported.
+    const root = dirname(dirname(parseDir));
+    if (basename(root) !== VAT_CACHE_DIR_NAME) {
+        throw new Error(`Refusing to clear ${root}: expected a directory named ${VAT_CACHE_DIR_NAME} (derived from ${parseDir}).`);
+    }
+    return root;
+}
+/**
+ * Measure, then delete, an entire cache tree.
+ *
+ * Measured BEFORE the delete, because afterwards there is nothing left to count
+ * and a report of "removed: unknown" would make the command unverifiable.
+ *
+ * Deliberately reads no environment: `vat cache clear` runs whether or not
+ * caching is enabled for this process. A `VAT_CACHE=0` that also disarmed the
+ * cleanup would leave an operator with a cache they can neither use nor remove.
+ *
+ * @param cacheDir - Directory to remove, in full
+ * @returns What was removed
+ */
+export async function clearCacheDirectory(cacheDir) {
+    const entries = await readdirOrNull(cacheDir);
+    if (entries === null) {
+        return { status: 'success', cacheDir, existed: false, removed: [], entriesRemoved: 0, bytesRemoved: 0 };
+    }
+    const usage = await measureEntries(cacheDir, entries);
+    await fs.rm(cacheDir, { recursive: true, force: true });
+    return {
+        status: 'success',
+        cacheDir,
+        existed: true,
+        removed: entries.map((entry) => entry.name).sort((a, b) => a.localeCompare(b)),
+        entriesRemoved: usage.entries,
+        bytesRemoved: usage.bytes,
+    };
+}
+/**
+ * Command entry point: clear the real cache root and publish the report.
+ *
+ * @param options - Command options (only `--debug`, inherited from the root)
+ */
+export async function cacheClearCommand(options = {}) {
+    const startTime = Date.now();
+    const logger = createLogger(options.debug ? { debug: true } : {});
+    try {
+        const report = await clearCacheDirectory(vatCacheRoot());
+        logger.debug(`Cleared ${String(report.entriesRemoved)} cache entries from ${report.cacheDir}`);
+        writeYamlOutput(report);
+        process.exit(0);
+    }
+    catch (error) {
+        handleCommandError(error, logger, startTime, 'CacheClear');
+    }
+}
+/**
+ * `readdir` that reports a missing directory as `null` rather than throwing.
+ *
+ * Only ENOENT is absorbed. EACCES on a directory that exists is a genuine
+ * failure — reporting it as "nothing to clear" would tell the operator their
+ * cache is gone when it is still on disk.
+ */
+async function readdirOrNull(dir) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is the derived cache root or a caller-injected test directory
+        return await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** Sum file count and bytes over already-listed directory entries. */
+async function measureEntries(dir, entries) {
+    const usages = await Promise.all(entries.map(async (entry) => {
+        const child = safePath.join(dir, entry.name);
+        // Not `isFile()`: a symlink or socket is still an entry that is about to
+        // be removed, and counting only regular files would under-report it.
+        return entry.isDirectory() ? measureTree(child) : { entries: 1, bytes: await sizeOf(child) };
+    }));
+    return usages.reduce((total, usage) => ({ entries: total.entries + usage.entries, bytes: total.bytes + usage.bytes }), EMPTY_USAGE);
+}
+/** Recursive measure. A directory that vanished mid-walk contributes nothing. */
+async function measureTree(dir) {
+    const entries = await readdirOrNull(dir);
+    return entries === null ? EMPTY_USAGE : measureEntries(dir, entries);
+}
+/**
+ * Size of one entry, without following symlinks.
+ *
+ * A file that disappears between the listing and the stat contributes 0 rather
+ * than failing the clear — the whole tree is about to be deleted anyway, and a
+ * concurrent vat run pruning its own temp file must not turn cleanup into an
+ * error.
+ */
+async function sizeOf(target) {
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- path is inside the cache root being measured
+        const stats = await fs.lstat(target);
+        return stats.size;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=clear.js.map

package/dist/commands/cache/clear.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../../src/commands/cache/clear.ts"],"names":[],"mappings":"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"}

package/dist/commands/cache/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cache command group, plus the root-level `--no-cache` control surface.
+ *
+ * Both live here so the flag and the command that cleans up after it stay in one
+ * place: `--no-cache` decides whether this run *writes* to the caches, `vat cache
+ * clear` decides whether the caches *survive*.
+ */
+import { Command } from 'commander';
+/**
+ * Root options this module reads. Commander represents `--no-cache` as the
+ * POSITIVE key `cache` — `true` by default, `false` only when the negated flag
+ * is passed. It NEVER produces `noCache`; reading that key is the exact bug that
+ * made three flags in this package silent no-ops (see
+ * `test/commands/commander-option-keys.test.ts`).
+ */
+export interface CacheControlOptions {
+    cache?: boolean;
+}
+/**
+ * Register the root-level `--no-cache` flag and the hook that gives it effect.
+ *
+ * ## Why this sets an environment variable instead of plumbing a flag
+ *
+ * `vat validate`, `vat verify` and `vat build` enumerate nothing in their own
+ * process: each `spawnSync`s the vat binary once per phase, and the child is
+ * what parses the corpus. A flag parsed in the parent therefore never reaches
+ * the process whose caching it is supposed to control, whereas `process.env` is
+ * inherited by every child for free. `bin.ts` already leans on exactly that for
+ * `VAT_CONTEXT` / `VAT_CONTEXT_PATH`.
+ *
+ * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
+ * per construction, never at module load, so setting it from a `preAction` hook
+ * — after Commander has parsed, before any command body runs — is observed.
+ *
+ * ## The collision with `vat resources validate --no-cache`
+ *
+ * This root program does NOT use `enablePositionalOptions()`, so Commander scans
+ * the WHOLE argv for root options, including everything after the subcommand
+ * name. That is the same mechanism that let a root `-v` shadow the subcommands'
+ * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
+ * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
+ * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
+ * identically-named flag is swallowed before it ever sees it, which would have
+ * silently re-enabled the external-URL cache the flag exists to bypass.
+ *
+ * Rather than break a shipped flag, the hook hands the value back down to
+ * whichever action command declares a `cache` option of its own. `--no-cache` is
+ * a superset — every cache off — so the handoff is a strengthening, never a
+ * reversal.
+ *
+ * @param program - The root program to register the flag and hook on
+ */
+export declare function registerCacheControl(program: Command): void;
+/**
+ * Apply the root `--no-cache` decision: export it to child processes, and hand
+ * it down to an action command that declares its own `cache` option.
+ *
+ * Exported so a test can drive it from real parsed options rather than from a
+ * hand-built bag. Deliberately does nothing when the flag was not passed — a
+ * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
+ * one that is always on.
+ *
+ * @param rootOptions - Options bag from the ROOT program
+ * @param actionCommand - The command whose action is about to run
+ */
+export declare function applyCacheControl(rootOptions: CacheControlOptions, actionCommand: Command): void;
+export declare function createCacheCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI,CAWhG;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CA6D5C"}

package/dist/commands/cache/index.js

@@ -0,0 +1,126 @@
+/**
+ * Cache command group, plus the root-level `--no-cache` control surface.
+ *
+ * Both live here so the flag and the command that cleans up after it stay in one
+ * place: `--no-cache` decides whether this run *writes* to the caches, `vat cache
+ * clear` decides whether the caches *survive*.
+ */
+import { Command } from 'commander';
+import { cacheClearCommand } from './clear.js';
+/**
+ * Register the root-level `--no-cache` flag and the hook that gives it effect.
+ *
+ * ## Why this sets an environment variable instead of plumbing a flag
+ *
+ * `vat validate`, `vat verify` and `vat build` enumerate nothing in their own
+ * process: each `spawnSync`s the vat binary once per phase, and the child is
+ * what parses the corpus. A flag parsed in the parent therefore never reaches
+ * the process whose caching it is supposed to control, whereas `process.env` is
+ * inherited by every child for free. `bin.ts` already leans on exactly that for
+ * `VAT_CONTEXT` / `VAT_CONTEXT_PATH`.
+ *
+ * `VAT_CACHE=0` is read by `ParseCache` (packages/resources/src/parse-cache.ts)
+ * per construction, never at module load, so setting it from a `preAction` hook
+ * — after Commander has parsed, before any command body runs — is observed.
+ *
+ * ## The collision with `vat resources validate --no-cache`
+ *
+ * This root program does NOT use `enablePositionalOptions()`, so Commander scans
+ * the WHOLE argv for root options, including everything after the subcommand
+ * name. That is the same mechanism that let a root `-v` shadow the subcommands'
+ * own `-v, --verbose` (see the incident recorded in `bin.ts`). Measured against
+ * commander 12: `vat resources validate docs --no-cache` leaves the ROOT with
+ * `cache: false` and the SUBCOMMAND with `cache: true` — the subcommand's
+ * identically-named flag is swallowed before it ever sees it, which would have
+ * silently re-enabled the external-URL cache the flag exists to bypass.
+ *
+ * Rather than break a shipped flag, the hook hands the value back down to
+ * whichever action command declares a `cache` option of its own. `--no-cache` is
+ * a superset — every cache off — so the handoff is a strengthening, never a
+ * reversal.
+ *
+ * @param program - The root program to register the flag and hook on
+ */
+export function registerCacheControl(program) {
+    program.option('--no-cache', "Disable VAT's disk caches for this run (also applies to spawned phases)");
+    program.hook('preAction', (_thisCommand, actionCommand) => {
+        applyCacheControl(program.opts(), actionCommand);
+    });
+}
+/**
+ * Apply the root `--no-cache` decision: export it to child processes, and hand
+ * it down to an action command that declares its own `cache` option.
+ *
+ * Exported so a test can drive it from real parsed options rather than from a
+ * hand-built bag. Deliberately does nothing when the flag was not passed — a
+ * toggle that writes `VAT_CACHE=1` by default would be indistinguishable from
+ * one that is always on.
+ *
+ * @param rootOptions - Options bag from the ROOT program
+ * @param actionCommand - The command whose action is about to run
+ */
+export function applyCacheControl(rootOptions, actionCommand) {
+    if (rootOptions.cache !== false)
+        return;
+    process.env['VAT_CACHE'] = '0';
+    // `attributeName()`, not `name()`: for `--no-cache` the latter returns
+    // 'no-cache', so a check written against it never matches and the handoff
+    // above becomes a no-op that looks like it works.
+    if (actionCommand.options.some((option) => option.attributeName() === 'cache')) {
+        actionCommand.setOptionValue('cache', false);
+    }
+}
+export function createCacheCommand() {
+    const cache = new Command('cache');
+    cache
+        .description("Manage VAT's shared on-disk caches in the system temp directory")
+        .helpCommand(false)
+        .addHelpText('after', `
+Description:
+  VAT keeps three disposable caches under <tmpdir>/.vat-cache: parse facts
+  keyed by file content, external-URL validation results, and per-OS-user
+  authenticated-link content. None of them is durable — recovery is always
+  "rescan", and the OS temp purge is the eviction policy.
+
+  To run WITHOUT the caches rather than remove them, use --no-cache on any
+  command (or VAT_CACHE=0), which also applies to spawned phases.
+
+Example:
+  $ vat cache clear                    # Reclaim the temp-directory cache tree
+`);
+    cache
+        .command('clear')
+        .description('Delete the whole VAT cache tree from the system temp directory')
+        .action(async function () {
+        await cacheClearCommand(this.optsWithGlobals());
+    })
+        .addHelpText('after', `
+Description:
+  Removes <tmpdir>/.vat-cache in its entirety — the parse cache, the
+  external-URL validation cache, and the per-OS-user authenticated-link cache.
+  Every one of them is disposable by design: the next run repopulates what it
+  needs, so the only cost of clearing is one cold pass.
+
+  Runs regardless of --no-cache / VAT_CACHE=0. Turning caching off must not
+  disarm the one command that reclaims the space.
+
+  A cache directory that does not exist is not an error — nothing to remove is
+  a successful clear.
+
+Output:
+  - cacheDir: absolute path that was targeted
+  - existed: whether the directory was there at all
+  - removed: top-level entries that were deleted
+  - entriesRemoved / bytesRemoved: file count and total size, measured before
+    deletion
+
+Exit Codes:
+  0 - Cache cleared (or already absent)
+  2 - Could not remove the cache (permissions, busy file)
+
+Example:
+  $ vat cache clear                    # Reclaim the temp-directory cache tree
+`);
+    return cache;
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAavE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,yEAAyE,CAAC,CAAC;IAExG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,EAAE;QACxD,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAuB,EAAE,aAAa,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAgC,EAAE,aAAsB;IACxF,IAAI,WAAW,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO;IAExC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC;IAE/B,uEAAuE;IACvE,0EAA0E;IAC1E,kDAAkD;IAClD,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC;QAC/E,aAAa,CAAC,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnC,KAAK;SACF,WAAW,CAAC,iEAAiE,CAAC;SAC9E,WAAW,CAAC,KAAK,CAAC;SAClB,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;CAYL,CACI,CAAC;IAEJ,KAAK;SACF,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK;QACX,MAAM,iBAAiB,CAAC,IAAI,CAAC,eAAe,EAAuB,CAAC,CAAC;IACvE,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BL,CACI,CAAC;IAEJ,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/claude/plugin/build.d.ts

@@ -8,7 +8,7 @@
  */
 import { type SeverityCounts } from '@vibe-agent-toolkit/agent-schema';
 import { type DeclaredEvalSuite, type PackageSkillResult } from '@vibe-agent-toolkit/agent-skills';
-import type { ResourceRegistry, SkillsConfig } from '@vibe-agent-toolkit/resources';
+import type { ExternalPluginSource, ResourceRegistry, SkillsConfig } from '@vibe-agent-toolkit/resources';
 import { Command } from 'commander';
 import { createLogger } from '../../../utils/logger.js';
 export interface PluginBuildCommandOptions {
@@ -52,11 +52,25 @@ interface PluginBuildResult {
      */
     issueCounts: SeverityCounts;
 }
+/**
+ * A plugin entry that references another marketplace/repo's plugin instead of
+ * being built locally (`pluginDef.externalSource` is set). VAT never creates a
+ * directory or writes a plugin.json for it — the empty-plugin guard, tree-copy,
+ * skills packaging, and files[] mapping in {@link buildPlugin} all assume local
+ * content, none of which applies here.
+ */
+export interface ExternalPluginBuildResult {
+    pluginName: string;
+    pluginVersion: string | undefined;
+    source: ExternalPluginSource;
+}
 export interface MarketplaceBuildResult {
     name: string;
     status: 'built' | 'error';
     reason?: string;
     plugins: PluginBuildResult[];
+    /** Plugins referenced via `externalSource` — see {@link ExternalPluginBuildResult}. */
+    externalPlugins: ExternalPluginBuildResult[];
 }
 export declare function createPluginBuildCommand(): Command;
 /**

package/dist/commands/claude/plugin/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../../src/commands/claude/plugin/build.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../../src/commands/claude/plugin/build.ts"],"names":[],"mappings":"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"}

package/dist/commands/claude/plugin/build.js

@@ -53,6 +53,12 @@ Description:
   - Merges plugin.json with author, description, and VAT-supplied metadata
   - Generates marketplace.json with plugin registry and relative source paths
 
+  A plugin entry with externalSource is REFERENCED, not built: no local dir,
+  tree-copy, or skills packaging — its externalSource object (github/url/npm/pip)
+  is emitted verbatim as that entry's marketplace.json source, so it resolves to
+  wherever the other marketplace/repo actually publishes it. Use this to
+  cherry-pick a plugin from one marketplace into another without vendoring it.
+
 Output structure:
   dist/.claude/plugins/marketplaces/<marketplace>/
     .claude-plugin/marketplace.json
@@ -214,6 +220,7 @@ async function pluginBuildCommand(options) {
         });
         const duration = Date.now() - startTime;
         const totalPlugins = results.flatMap((r) => r.plugins).length;
+        const totalExternalPlugins = results.flatMap((r) => r.externalPlugins).length;
         const totalSkills = results.flatMap((r) => r.plugins).flatMap((p) => p.skillsCopied).length;
         const allPlugins = results.flatMap((r) => r.plugins);
         // KNOWN, DELIBERATELY NOT FIXED — this lane NAMES NOTHING. Every level of this
@@ -235,6 +242,7 @@ async function pluginBuildCommand(options) {
             issueCounts: sumSeverityCounts(allPlugins.map((p) => p.issueCounts)),
             marketplacesBuilt: results.filter((r) => r.status === 'built').length,
             pluginsBuilt: totalPlugins,
+            pluginsReferenced: totalExternalPlugins,
             skillsPackaged: totalSkills,
             marketplaces: results.map((r) => ({
                 name: r.name,
@@ -263,6 +271,14 @@ async function pluginBuildCommand(options) {
                     localSkillsPackaged: p.localSkillsPackaged,
                     issueCounts: p.issueCounts,
                 })),
+                // Referenced, not built — no dir, no counts to report. `source` is the
+                // same object emitted verbatim into marketplace.json, so the report and
+                // the artifact can never disagree about what a reference points at.
+                externalPlugins: r.externalPlugins.map((p) => ({
+                    name: p.pluginName,
+                    ...(p.pluginVersion ? { version: p.pluginVersion } : {}),
+                    source: p.source,
+                })),
             })),
             duration: `${duration}ms`,
         });
@@ -299,6 +315,7 @@ async function copyDistributionFiles(marketplaceDir, configDir, config, logger)
 async function buildMarketplace(input) {
     const { name, config, availableSkills, configDir, skillsConfig, rootVersion, registry, projectSkills, logger, verbose } = input;
     const plugins = [];
+    const externalPlugins = [];
     // Clean stale marketplace directory before rebuilding — removes orphaned plugins
     const marketplaceBaseDir = safePath.join(configDir, 'dist', '.claude', 'plugins', 'marketplaces', name);
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved from config
@@ -308,6 +325,23 @@ async function buildMarketplace(input) {
     // Marketplace-level skills filter restricts pool available to plugins that use "*"
     const marketplaceAvailable = resolveMarketplaceAvailableSkills(config, availableSkills);
     for (const pluginDef of config.plugins) {
+        // externalSource plugins are never built or copied — they route straight
+        // to a marketplace.json entry referencing the other repo. Every phase
+        // buildPlugin runs (empty-plugin guard, tree-copy, skills packaging,
+        // plugin.json merge) assumes local content, none of which exists here.
+        if (pluginDef.externalSource) {
+            logger.info(`      Referencing external plugin: ${pluginDef.name} (${pluginDef.externalSource.source})`);
+            // No rootVersion fallback here (unlike a built plugin): this marketplace
+            // does not own or build the referenced plugin, so tagging it with THIS
+            // repo's package.json version would misrepresent what version the other
+            // repo actually publishes. Only an explicit config version applies.
+            externalPlugins.push({
+                pluginName: pluginDef.name,
+                pluginVersion: pluginDef.version,
+                source: pluginDef.externalSource,
+            });
+            continue;
+        }
         const pluginResult = await buildPlugin({
             marketplaceName: name,
             pluginDef,
@@ -328,23 +362,34 @@ async function buildMarketplace(input) {
     const claudePluginDir = safePath.join(marketplaceDir, CLAUDE_PLUGIN_DIRNAME);
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved paths
     await mkdir(claudePluginDir, { recursive: true });
-    // Each entry's author is the plugin's own MERGED author (see marketplace-json.ts),
-    // so marketplace.json and that plugin's plugin.json cannot disagree.
+    // Each BUILT entry's author is the plugin's own MERGED author (see
+    // marketplace-json.ts), so marketplace.json and that plugin's plugin.json
+    // cannot disagree. External entries carry no author — see marketplace-json.ts.
     const marketplaceJson = buildMarketplaceJson({
         name,
         owner: config.owner,
-        plugins: plugins.map((p) => ({
-            name: p.pluginName,
-            description: config.plugins.find((pd) => pd.name === p.pluginName)?.description,
-            version: p.pluginVersion,
-            author: p.pluginAuthor,
-        })),
+        plugins: [
+            ...plugins.map((p) => ({
+                kind: 'built',
+                name: p.pluginName,
+                description: config.plugins.find((pd) => pd.name === p.pluginName)?.description,
+                version: p.pluginVersion,
+                author: p.pluginAuthor,
+            })),
+            ...externalPlugins.map((p) => ({
+                kind: 'external',
+                name: p.pluginName,
+                description: config.plugins.find((pd) => pd.name === p.pluginName)?.description,
+                version: p.pluginVersion,
+                source: p.source,
+            })),
+        ],
     });
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolved paths
     await writeFile(safePath.join(claudePluginDir, 'marketplace.json'), JSON.stringify(marketplaceJson, null, 2));
     logger.info(`   .claude-plugin/marketplace.json`);
     await copyDistributionFiles(marketplaceDir, configDir, config, logger);
-    return { name, status: 'built', plugins };
+    return { name, status: 'built', plugins, externalPlugins };
 }
 /**
  * Resolve which pool skills are available to plugins in this marketplace.