@indigoai-us/hq-cli 5.50.0 → 5.50.1

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  *                            (new in hq-core v12.0.0; see
  *                            knowledge/public/hq-core/package-yaml-spec.md)
  */
+import type { ContributionKey } from './utils/contribution-table.js';
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
 export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
@@ -56,7 +57,13 @@ export interface SyncResult {
     message?: string;
     filesChanged?: number;
 }
-export type PackContributeKey = 'workers' | 'knowledge' | 'skills' | 'commands' | 'hooks' | 'policies' | 'scripts';
+/**
+ * The `contributes.*` keys a pack may declare. DERIVED (US-003) from the single
+ * declarative contribution registry in `utils/contribution-table.ts` -- adding
+ * a contribution type is one row there, and this union updates automatically.
+ * Do NOT restate the keys here.
+ */
+export type PackContributeKey = ContributionKey;
 /**
  * Pack authorship attribution (US-001). OPTIONAL and backwards-compatible —
  * packs published before this field still validate. When present, install can

package/dist/utils/contribution-table.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+export type WireMode = 'symlink' | 'merge';
+export interface ContributionRow {
+    /** Path inside the pack, with `{item}` substituted for the declared name. */
+    payload: string;
+    /**
+     * `wire: 'symlink'` -> host directory the symlink lives under (HQ-root
+     * relative). `wire: 'merge'` -> a non-path sentinel for the merge target.
+     */
+    host: string;
+    wire: WireMode;
+}
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+export declare const CONTRIBUTION_TABLE: {
+    readonly workers: {
+        readonly payload: "workers/{item}";
+        readonly host: "core/workers/public";
+        readonly wire: "symlink";
+    };
+    readonly knowledge: {
+        readonly payload: "knowledge/{item}";
+        readonly host: "core/knowledge/public";
+        readonly wire: "symlink";
+    };
+    readonly skills: {
+        readonly payload: "skills/{item}";
+        readonly host: ".claude/skills";
+        readonly wire: "symlink";
+    };
+    readonly commands: {
+        readonly payload: "commands/{item}.md";
+        readonly host: ".claude/commands";
+        readonly wire: "symlink";
+    };
+    readonly hooks: {
+        readonly payload: "hooks/{item}.sh";
+        readonly host: ".claude/hooks";
+        readonly wire: "symlink";
+    };
+    readonly policies: {
+        readonly payload: "policies/{item}.md";
+        readonly host: "core/policies";
+        readonly wire: "symlink";
+    };
+    readonly scripts: {
+        readonly payload: "scripts/{item}";
+        readonly host: "core/scripts";
+        readonly wire: "symlink";
+    };
+    readonly mcp: {
+        readonly payload: "mcp/{item}.json";
+        readonly host: "merge:claude+codex";
+        readonly wire: "merge";
+    };
+};
+/** The declared contribution keys, derived once from the table. */
+export type ContributionKey = keyof typeof CONTRIBUTION_TABLE;
+/** All contribution keys, in declaration order. */
+export declare const CONTRIBUTION_KEYS: ContributionKey[];
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export declare function payloadFor(key: ContributionKey, item: string): string;
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export declare const SYMLINK_KEYS: ("workers" | "knowledge" | "skills" | "commands" | "hooks" | "policies" | "scripts" | "mcp")[];
+//# sourceMappingURL=contribution-table.d.ts.map

package/dist/utils/contribution-table.js

@@ -0,0 +1,65 @@
+/**
+ * The contribution registry -- the SINGLE declarative source of truth (US-003)
+ * for the `contributes.* -> host` mapping. Every other surface DERIVES from
+ * this table:
+ *
+ *   - `PackContributeKey` (types.ts)              = `keyof typeof CONTRIBUTION_TABLE`
+ *   - `linkFor` / `contributionLinks`             read `payload` + `host`
+ *   - `validateManifest`'s payload check          reads `payload`
+ *   - `core/scripts/scan-packages.sh`             reads a data block GENERATED
+ *                                                 from this table
+ *                                                 (scripts/generate-scan-packages-table.mjs)
+ *
+ * Adding a contribution type is ONE row here, not a five-site edit. The parity
+ * test (`pack-contributions.test.ts`) asserts every surface agrees on the full
+ * key-set, the payload suffix, and the wire mode.
+ *
+ * Row fields:
+ *   - `payload`: path INSIDE the pack, with the literal token `{item}` for the
+ *     declared name. The suffix after `{item}` (e.g. `.md`, `.json`, or none)
+ *     IS the load-bearing per-key shape.
+ *   - `host`: for `wire: 'symlink'`, the host DIRECTORY (relative to the HQ
+ *     root) the symlink is created under -- the symlink dst is
+ *     `<host>/<expanded-item-basename>`. For `wire: 'merge'`, a non-path
+ *     SENTINEL describing the merge target (e.g. `merge:claude+codex`); it is
+ *     NEVER used as a filesystem path.
+ *   - `wire`: `symlink` (a single `ln -s` into `host`) or `merge` (merged into
+ *     a shared host config; see US-004/US-005). Symlink-only readers MUST skip
+ *     `merge` rows.
+ *
+ * NOTE: the `mcp` row is DECLARED here as data only. US-003 does NOT wire any
+ * MCP behavior -- the merge engine lands in US-004/US-005. Declaring it now
+ * makes the table the single source so adding the merge wiring is a code change
+ * against an already-present row, and the parity test guards it from day one.
+ */
+/**
+ * The 8-key contribution registry. `as const` so `keyof typeof` yields the
+ * exact literal key union consumed by `PackContributeKey`.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="154fb78d-60ba-508f-b6e7-6889858f1841")}catch(e){}}();
+export const CONTRIBUTION_TABLE = {
+    workers: { payload: 'workers/{item}', host: 'core/workers/public', wire: 'symlink' },
+    knowledge: { payload: 'knowledge/{item}', host: 'core/knowledge/public', wire: 'symlink' },
+    skills: { payload: 'skills/{item}', host: '.claude/skills', wire: 'symlink' },
+    commands: { payload: 'commands/{item}.md', host: '.claude/commands', wire: 'symlink' },
+    hooks: { payload: 'hooks/{item}.sh', host: '.claude/hooks', wire: 'symlink' },
+    policies: { payload: 'policies/{item}.md', host: 'core/policies', wire: 'symlink' },
+    scripts: { payload: 'scripts/{item}', host: 'core/scripts', wire: 'symlink' },
+    // wire:merge -- DECLARED as data (US-003); the merge engine ships in
+    // US-004/US-005. Symlink readers skip this row.
+    mcp: { payload: 'mcp/{item}.json', host: 'merge:claude+codex', wire: 'merge' },
+};
+/** All contribution keys, in declaration order. */
+export const CONTRIBUTION_KEYS = Object.keys(CONTRIBUTION_TABLE);
+/**
+ * Expand a row's `payload` template for a concrete item name. Returns the
+ * pack-relative path of the contribution's payload (e.g. `commands/foo.md`).
+ */
+export function payloadFor(key, item) {
+    return CONTRIBUTION_TABLE[key].payload.replace('{item}', item);
+}
+/** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
+export const SYMLINK_KEYS = CONTRIBUTION_KEYS.filter((k) => CONTRIBUTION_TABLE[k].wire === 'symlink');
+//# sourceMappingURL=contribution-table.js.map
+//# debugId=154fb78d-60ba-508f-b6e7-6889858f1841

package/dist/utils/pack-contributions.d.ts

@@ -1,22 +1,65 @@
 /**
- * Content-pack contribution helpers -- the single source of truth (in TS) for
- * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * Content-pack contribution helpers -- the SINGLE SOURCE OF TRUTH (US-003) for
+ * the `contributes.* -> host` mapping that `hq install` wires via
  * `core/scripts/scan-packages.sh`.
  *
  * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
  * tracked by filesystem presence -- there is no registry file). The list /
  * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
  * SAME mapping so it can report link health and cleanly un-wire a pack without
- * leaving dangling symlinks. That mapping is duplicated today in two places:
+ * leaving dangling symlinks.
  *
- *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
- *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ * Historically that mapping was RESTATED in five places (the scan-packages.sh
+ * bash `case`, pack-install.ts:validateManifest's `subpaths` record,
+ * `linkFor`'s switch, `contributionLinks`, and the `PackContributeKey` union),
+ * drift-guarded only by a substring check. US-003 collapses it to ONE
+ * declarative table -- `CONTRIBUTION_TABLE` below -- with a row per key
+ * `{ payload, host, wire }`:
  *
- * This module re-encodes it once for TS callers. A parity test
- * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
- * arms so the three copies cannot drift.
+ *   - `PackContributeKey` is DERIVED from the table keys (see types.ts).
+ *   - `linkFor` / `contributionLinks` / the `subpaths` validator READ the table.
+ *   - `core/scripts/scan-packages.sh` reads a generated data block emitted from
+ *     this same table (regenerate via `scripts/generate-scan-packages-table.mjs`).
+ *
+ * A parity test (`pack-contributions.test.ts`) asserts FULL key-set +
+ * payload-suffix + wire-mode equivalence across every surface, so the copies
+ * cannot drift.
+ *
+ * `wire` discriminates HOW a contribution reaches the host:
+ *   - `symlink`: a single `ln -s` into a well-known host directory (every
+ *     contribution type that shipped before MCP).
+ *   - `merge`: the contribution is MERGED into a shared host config rather than
+ *     symlinked (the `mcp` row -- registered into the Claude + Codex agent
+ *     configs). The merge WIRING is delivered in US-004/US-005; US-003 only
+ *     DECLARES the row as data so the table is the single source and the parity
+ *     test guards the real invariant. `symlink`-only readers (linkFor,
+ *     contributionLinks, the symlink validator, scan-packages) must SKIP
+ *     `merge` rows -- they never produce a symlink.
  */
 import type { PackManifest, PackContributeKey } from '../types.js';
+import { CONTRIBUTION_TABLE, type WireMode } from './contribution-table.js';
+import { type UnregisterServerResult, type SafeWriteEnv, type AcquireLockOptions } from '../commands/mcp-registration.js';
+export { CONTRIBUTION_TABLE };
+export type { WireMode };
+/**
+ * Where a contributes key is ROUTED (US-005). Reads the single-source table's
+ * `wire` field — `'symlink'` keys go through `linkFor`/`contributionLinks` (a
+ * host `ln -s`); `'merge'` keys (e.g. `mcp`) go through the `registerMcpServers`
+ * seam in `commands/mcp-registration.ts` and are NEVER symlinked.
+ *
+ * This is the explicit, code-enforced discriminator behind the invariant that
+ * merge keys never reach the symlink path: callers fan out on the return value
+ * rather than relying on `linkFor` happening to return `null`.
+ */
+export declare function routeContribution(key: PackContributeKey): WireMode;
+/**
+ * The subset of a pack's declared `contributes` keys that are `wire: 'merge'`
+ * (e.g. `mcp`) — the keys that MUST be routed to `registerMcpServers` (US-006)
+ * and MUST NOT be symlinked. Unknown keys and non-array/empty values are
+ * ignored, mirroring `contributionLinks`. Returned in `contributes` iteration
+ * order, de-duplicated.
+ */
+export declare function mergeKeys(contributes: Partial<Record<PackContributeKey, string[]>>): PackContributeKey[];
 /** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
 export interface WiredLink {
     key: PackContributeKey;
@@ -26,8 +69,10 @@ export interface WiredLink {
 }
 export type LinkStatus = 'live' | 'broken' | 'missing' | 'foreign';
 /**
- * Every symlink a pack's `contributes` block declares. Empty subfields and
- * non-array values are ignored, mirroring scan-packages.sh.
+ * Every SYMLINK a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh. `wire: 'merge'`
+ * keys (e.g. `mcp`) produce no symlink and are skipped here -- their host
+ * effect (a config merge) is handled separately (US-004/US-005).
  */
 export declare function contributionLinks(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): WiredLink[];
 /** Classify a host path against the link that should own it. */
@@ -75,6 +120,37 @@ export interface UnwireResult {
  * uninstall from leaving dangling symlinks behind.
  */
 export declare function unwirePack(hqRoot: string, packDir: string, contributes: Partial<Record<PackContributeKey, string[]>>): UnwireResult;
+/** The result of {@link unwirePackMcp}: the per-server un-registration outcomes (empty when no `mcp` keys). */
+export interface UnwireMcpResult {
+    /** One {@link UnregisterServerResult} per declared `contributes.mcp` server, in declaration order. */
+    servers: UnregisterServerResult[];
+}
+/** Tuning passthrough for {@link unwirePackMcp} (tests inject a tmpdir `env.home` + tiny lock timeouts). */
+export interface UnwirePackMcpOptions {
+    /** Injectable env — tests MUST pass a tmpdir `home` so the real ~/.claude.json / ~/.codex are untouched. */
+    env?: Partial<SafeWriteEnv>;
+    /** Lock tuning (tests use tiny timeouts). */
+    lock?: AcquireLockOptions;
+    /** Backup timestamp override (deterministic tests). */
+    stamp?: string;
+}
+/**
+ * Un-register the `wire: 'merge'` (MCP) servers a pack declares — the parallel to
+ * {@link unwirePack}'s symlink removal. For each name in `mergeKeys(contributes)` →
+ * `contributes.<mergeKey>` (today only `mcp`), this delegates to
+ * {@link unregisterMcpServers}, which removes ONLY entries stamped with THIS pack's
+ * `_hqPack` provenance and SKIPS-AND-WARNS on a foreign/unstamped same-named entry.
+ *
+ * No-ops cleanly when the pack declares no merge keys (returns `{ servers: [] }`),
+ * when the runtime config is absent (Codex-less host → first-class skip; missing
+ * ~/.claude.json → `absent`), and on a re-run (already-removed → `absent`). It does
+ * NOT throw on a foreign entry — uninstall of one pack must not abort on a server
+ * another pack (or the user) owns.
+ *
+ * @param packName    the pack being uninstalled — the provenance to match
+ * @param contributes the pack's `contributes` block (its `mcp` list drives removal)
+ */
+export declare function unwirePackMcp(packName: string, contributes: Partial<Record<PackContributeKey, string[]>>, options?: UnwirePackMcpOptions): UnwireMcpResult;
 export declare function readHqVersion(hqRoot: string): string | null;
 export interface CatalogEntry {
     source: string;

package/dist/utils/pack-contributions.js

@@ -1,83 +1,135 @@
 /**
- * Content-pack contribution helpers -- the single source of truth (in TS) for
- * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * Content-pack contribution helpers -- the SINGLE SOURCE OF TRUTH (US-003) for
+ * the `contributes.* -> host` mapping that `hq install` wires via
  * `core/scripts/scan-packages.sh`.
  *
  * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
  * tracked by filesystem presence -- there is no registry file). The list /
  * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
  * SAME mapping so it can report link health and cleanly un-wire a pack without
- * leaving dangling symlinks. That mapping is duplicated today in two places:
+ * leaving dangling symlinks.
  *
- *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
- *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ * Historically that mapping was RESTATED in five places (the scan-packages.sh
+ * bash `case`, pack-install.ts:validateManifest's `subpaths` record,
+ * `linkFor`'s switch, `contributionLinks`, and the `PackContributeKey` union),
+ * drift-guarded only by a substring check. US-003 collapses it to ONE
+ * declarative table -- `CONTRIBUTION_TABLE` below -- with a row per key
+ * `{ payload, host, wire }`:
  *
- * This module re-encodes it once for TS callers. A parity test
- * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
- * arms so the three copies cannot drift.
+ *   - `PackContributeKey` is DERIVED from the table keys (see types.ts).
+ *   - `linkFor` / `contributionLinks` / the `subpaths` validator READ the table.
+ *   - `core/scripts/scan-packages.sh` reads a generated data block emitted from
+ *     this same table (regenerate via `scripts/generate-scan-packages-table.mjs`).
+ *
+ * A parity test (`pack-contributions.test.ts`) asserts FULL key-set +
+ * payload-suffix + wire-mode equivalence across every surface, so the copies
+ * cannot drift.
+ *
+ * `wire` discriminates HOW a contribution reaches the host:
+ *   - `symlink`: a single `ln -s` into a well-known host directory (every
+ *     contribution type that shipped before MCP).
+ *   - `merge`: the contribution is MERGED into a shared host config rather than
+ *     symlinked (the `mcp` row -- registered into the Claude + Codex agent
+ *     configs). The merge WIRING is delivered in US-004/US-005; US-003 only
+ *     DECLARES the row as data so the table is the single source and the parity
+ *     test guards the real invariant. `symlink`-only readers (linkFor,
+ *     contributionLinks, the symlink validator, scan-packages) must SKIP
+ *     `merge` rows -- they never produce a symlink.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f5492359-fdf3-5e85-9a81-699c4cd68f6a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6cc0fc56-5a1c-5ce8-96d4-652805e508f8")}catch(e){}}();
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
+import { CONTRIBUTION_TABLE, payloadFor } from './contribution-table.js';
+import { unregisterMcpServers, } from '../commands/mcp-registration.js';
+// NOTE on dependency direction: this module imports from ../commands/mcp-registration.js
+// to un-register `wire:merge` (mcp) servers on uninstall. mcp-registration.ts imports
+// ONLY fs/os/path/smol-toml (it does NOT import from pack-contributions.ts), so there
+// is NO import cycle. If that ever changes, invert via a callback injected by packs.ts.
+export { CONTRIBUTION_TABLE };
 /**
- * Map one contributes entry to its source/host paths. MUST stay in lockstep
- * with scan-packages.sh:wire_one_package and pack-install.ts:validateManifest.
+ * Where a contributes key is ROUTED (US-005). Reads the single-source table's
+ * `wire` field — `'symlink'` keys go through `linkFor`/`contributionLinks` (a
+ * host `ln -s`); `'merge'` keys (e.g. `mcp`) go through the `registerMcpServers`
+ * seam in `commands/mcp-registration.ts` and are NEVER symlinked.
+ *
+ * This is the explicit, code-enforced discriminator behind the invariant that
+ * merge keys never reach the symlink path: callers fan out on the return value
+ * rather than relying on `linkFor` happening to return `null`.
  */
-function linkFor(hqRoot, packDir, key, item) {
-    let srcRel;
-    let dstRel;
-    switch (key) {
-        case 'workers':
-            srcRel = path.join('workers', item);
-            dstRel = path.join('core', 'workers', 'public', item);
-            break;
-        case 'knowledge':
-            srcRel = path.join('knowledge', item);
-            dstRel = path.join('core', 'knowledge', 'public', item);
-            break;
-        case 'skills':
-            srcRel = path.join('skills', item);
-            dstRel = path.join('.claude', 'skills', item);
-            break;
-        case 'commands':
-            srcRel = path.join('commands', `${item}.md`);
-            dstRel = path.join('.claude', 'commands', `${item}.md`);
-            break;
-        case 'hooks':
-            srcRel = path.join('hooks', `${item}.sh`);
-            dstRel = path.join('.claude', 'hooks', `${item}.sh`);
-            break;
-        case 'policies':
-            srcRel = path.join('policies', `${item}.md`);
-            dstRel = path.join('core', 'policies', `${item}.md`);
-            break;
-        case 'scripts':
-            srcRel = path.join('scripts', item);
-            dstRel = path.join('core', 'scripts', item);
-            break;
+export function routeContribution(key) {
+    return CONTRIBUTION_TABLE[key].wire;
+}
+/**
+ * The subset of a pack's declared `contributes` keys that are `wire: 'merge'`
+ * (e.g. `mcp`) — the keys that MUST be routed to `registerMcpServers` (US-006)
+ * and MUST NOT be symlinked. Unknown keys and non-array/empty values are
+ * ignored, mirroring `contributionLinks`. Returned in `contributes` iteration
+ * order, de-duplicated.
+ */
+export function mergeKeys(contributes) {
+    const out = [];
+    for (const [key, items] of Object.entries(contributes)) {
+        if (!(key in CONTRIBUTION_TABLE))
+            continue; // unknown key -> ignore
+        if (!Array.isArray(items) || items.length === 0)
+            continue;
+        if (routeContribution(key) === 'merge' && !out.includes(key))
+            out.push(key);
     }
+    return out;
+}
+/**
+ * Map one SYMLINK contributes entry to its source/host paths, READING the
+ * single-source `CONTRIBUTION_TABLE` (US-003). The src is the expanded pack
+ * payload; the dst is `<host-dir>/<payload-basename>` so per-key suffixes
+ * (`.md`, `.sh`, none) carry through.
+ *
+ * Returns `null` for a `wire: 'merge'` key (e.g. `mcp`): a merge contribution
+ * is not a symlink and has no `WiredLink`. Callers that only handle symlinks
+ * (contributionLinks/unwirePack) skip those keys.
+ */
+function linkFor(hqRoot, packDir, key, item) {
+    const row = CONTRIBUTION_TABLE[key];
+    if (row.wire !== 'symlink')
+        return null;
+    const payloadRel = payloadFor(key, item); // e.g. commands/foo.md
+    // dst keeps the payload's basename (so the suffix carries through) under the
+    // host directory declared in the table.
+    const dstRel = path.join(row.host, path.basename(payloadRel));
     return {
         key,
         item,
-        src: path.join(packDir, srcRel),
+        src: path.join(packDir, payloadRel),
         dst: path.join(hqRoot, dstRel),
     };
 }
 /**
- * Every symlink a pack's `contributes` block declares. Empty subfields and
- * non-array values are ignored, mirroring scan-packages.sh.
+ * Every SYMLINK a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh. `wire: 'merge'`
+ * keys (e.g. `mcp`) produce no symlink and are skipped here -- their host
+ * effect (a config merge) is handled separately (US-004/US-005).
  */
 export function contributionLinks(hqRoot, packDir, contributes) {
     const links = [];
     for (const [key, items] of Object.entries(contributes)) {
+        if (!(key in CONTRIBUTION_TABLE))
+            continue; // unknown key -> ignore
         if (!Array.isArray(items))
             continue;
+        // INVARIANT (US-005): merge keys are NEVER symlinked. They route to
+        // registerMcpServers (commands/mcp-registration.ts) instead. Skip them
+        // explicitly here -- not just via linkFor returning null -- so the symlink
+        // path provably excludes them.
+        if (routeContribution(key) === 'merge')
+            continue;
         for (const item of items) {
             if (typeof item !== 'string' || item.length === 0)
                 continue;
-            links.push(linkFor(hqRoot, packDir, key, item));
+            const link = linkFor(hqRoot, packDir, key, item);
+            if (link)
+                links.push(link); // null for merge keys -- skip
         }
     }
     return links;
@@ -196,6 +248,36 @@ export function unwirePack(hqRoot, packDir, contributes) {
     }
     return result;
 }
+/**
+ * Un-register the `wire: 'merge'` (MCP) servers a pack declares — the parallel to
+ * {@link unwirePack}'s symlink removal. For each name in `mergeKeys(contributes)` →
+ * `contributes.<mergeKey>` (today only `mcp`), this delegates to
+ * {@link unregisterMcpServers}, which removes ONLY entries stamped with THIS pack's
+ * `_hqPack` provenance and SKIPS-AND-WARNS on a foreign/unstamped same-named entry.
+ *
+ * No-ops cleanly when the pack declares no merge keys (returns `{ servers: [] }`),
+ * when the runtime config is absent (Codex-less host → first-class skip; missing
+ * ~/.claude.json → `absent`), and on a re-run (already-removed → `absent`). It does
+ * NOT throw on a foreign entry — uninstall of one pack must not abort on a server
+ * another pack (or the user) owns.
+ *
+ * @param packName    the pack being uninstalled — the provenance to match
+ * @param contributes the pack's `contributes` block (its `mcp` list drives removal)
+ */
+export function unwirePackMcp(packName, contributes, options) {
+    const servers = [];
+    for (const key of mergeKeys(contributes)) {
+        const names = (contributes[key] ?? []).filter((n) => typeof n === 'string' && n.length > 0);
+        if (names.length === 0)
+            continue;
+        servers.push(...unregisterMcpServers(packName, names, {
+            env: options?.env,
+            lock: options?.lock,
+            stamp: options?.stamp,
+        }));
+    }
+    return { servers };
+}
 // ---------------------------------------------------------------------------
 // Host introspection: hqVersion + recommended_packages catalog
 // ---------------------------------------------------------------------------
@@ -236,4 +318,4 @@ export function readRecommendedPackages(hqRoot) {
     }
 }
 //# sourceMappingURL=pack-contributions.js.map
-//# debugId=f5492359-fdf3-5e85-9a81-699c4cd68f6a
+//# debugId=6cc0fc56-5a1c-5ce8-96d4-652805e508f8

package/dist/utils/secrets-cache.d.ts

@@ -1,6 +1,15 @@
 export declare const DEFAULT_SECRETS_CACHE_TTL_MS: number;
 export declare function readCache(companyUid: string, name: string): string | null;
 export declare function writeCache(companyUid: string, name: string, value: string, ttlMs?: number): void;
+/**
+ * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
+ * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
+ * registration) that have no `--company` flag and no network token and so cannot
+ * resolve a single active company UID up front: they instead probe every cached
+ * scope for a given secret name. Returns `[]` when the cache root is absent or
+ * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ */
+export declare function listSecretCacheScopes(): string[];
 export declare function removeCacheEntry(companyUid: string, name: string): void;
 export declare function clearAllCache(): {
     removed: number;

package/dist/utils/secrets-cache.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fd3738da-3061-5784-bb7c-02021291aecc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="68c3f1d3-dac4-57d6-8e2b-650c10a807ba")}catch(e){}}();
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -140,6 +140,28 @@ export function writeCache(companyUid, name, value, ttlMs = DEFAULT_SECRETS_CACH
         // Cache write failure is non-fatal
     }
 }
+/**
+ * List the scope UIDs (`cmp_*` / `prs_*` subdirectories) that currently have a
+ * secrets-cache directory on disk. Used by offline callers (e.g. install-time MCP
+ * registration) that have no `--company` flag and no network token and so cannot
+ * resolve a single active company UID up front: they instead probe every cached
+ * scope for a given secret name. Returns `[]` when the cache root is absent or
+ * unreadable (the desired graceful-deferral behavior — no scopes, no hits).
+ */
+export function listSecretCacheScopes() {
+    try {
+        return fs
+            .readdirSync(CACHE_DIR, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            // Only real entity scopes (cmp_*/prs_*); validateInputs in readCache also
+            // rejects anything with `/` or `..`, so this is belt-and-suspenders.
+            .filter((name) => !name.startsWith("."));
+    }
+    catch {
+        return [];
+    }
+}
 export function removeCacheEntry(companyUid, name) {
     if (!validateInputs(companyUid, name))
         return;
@@ -163,4 +185,4 @@ export function clearAllCache() {
     return { removed };
 }
 //# sourceMappingURL=secrets-cache.js.map
-//# debugId=fd3738da-3061-5784-bb7c-02021291aecc
+//# debugId=68c3f1d3-dac4-57d6-8e2b-650c10a807ba

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.50.0",
+  "version": "5.50.1",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -18,7 +18,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.12.0",
+    "@indigoai-us/hq-cloud": "^6.12.1",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",
@@ -27,6 +27,7 @@
     "open": "^10.1.0",
     "semver": "^7.6.3",
     "simple-git": "^3.27.0",
+    "smol-toml": "1.6.1",
     "varlock": "1.0.0"
   },
   "devDependencies": {