@indigoai-us/hq-cli 5.49.0 → 5.50.1

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.49.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.11.14",
+    "@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": {

package/scripts/generate-scan-packages-table.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * generate-scan-packages-table.mjs (US-003)
+ *
+ * Emits the bash data block that `core/scripts/scan-packages.sh` reads, from the
+ * single-source `src/utils/contribution-table.ts`. This keeps the bash wirer
+ * GENERATED FROM the table rather than restating the mapping -- the US-003
+ * single-source-of-truth invariant.
+ *
+ * The TS table is the authority; this script transcribes it to bash. It does
+ * NOT parse TypeScript -- it imports the same literal data by re-declaring the
+ * rows is avoided by reading the table via a tiny regex extraction of the
+ * `CONTRIBUTION_TABLE` object literal, so the table file stays the only place
+ * the rows live.
+ *
+ * Output: a bash snippet (to stdout, or written in place into scan-packages.sh
+ * between the BEGIN/END GENERATED markers when --write <path> is passed).
+ *
+ * Usage:
+ *   node scripts/generate-scan-packages-table.mjs                 # print block
+ *   node scripts/generate-scan-packages-table.mjs --check <path>  # verify in-sync
+ *   node scripts/generate-scan-packages-table.mjs --write <path>  # rewrite in place
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TABLE_TS = path.resolve(__dirname, '../src/utils/contribution-table.ts');
+
+const BEGIN = '# >>> BEGIN GENERATED contribution table (US-003) — do not edit by hand';
+const END = '# <<< END GENERATED contribution table';
+
+/**
+ * Extract the rows from the `CONTRIBUTION_TABLE` object literal in the TS file.
+ * Each row line looks like:
+ *   key: { payload: 'p/{item}', host: 'h', wire: 'symlink' },
+ */
+function readTable() {
+  const ts = fs.readFileSync(TABLE_TS, 'utf-8');
+  const open = ts.indexOf('export const CONTRIBUTION_TABLE');
+  if (open < 0) throw new Error('CONTRIBUTION_TABLE not found in ' + TABLE_TS);
+  const body = ts.slice(open, ts.indexOf('} as const', open));
+  const rowRe =
+    /^\s*([A-Za-z_][A-Za-z0-9_]*):\s*\{\s*payload:\s*'([^']+)'\s*,\s*host:\s*'([^']+)'\s*,\s*wire:\s*'([^']+)'\s*\}/gm;
+  const rows = [];
+  let m;
+  while ((m = rowRe.exec(body)) !== null) {
+    rows.push({ key: m[1], payload: m[2], host: m[3], wire: m[4] });
+  }
+  if (rows.length === 0) throw new Error('No rows parsed from CONTRIBUTION_TABLE');
+  return rows;
+}
+
+function renderBlock(rows) {
+  const lines = [];
+  lines.push(BEGIN);
+  lines.push('# Generated from hq-cli/src/utils/contribution-table.ts by');
+  lines.push('# hq-cli/scripts/generate-scan-packages-table.mjs. Regenerate with:');
+  lines.push('#   node scripts/generate-scan-packages-table.mjs --write core/scripts/scan-packages.sh');
+  lines.push('# Each row is "payload|host|wire" (payload uses {item} for the name).');
+  lines.push('# bash 3.2-compatible (macOS default bash has no associative arrays):');
+  lines.push('# a plain indexed key list + a generated case-lookup function.');
+  lines.push('CONTRIB_KEYS=(' + rows.map((r) => r.key).join(' ') + ')');
+  lines.push('# contrib_row <key> -> echoes "payload|host|wire", empty if unknown.');
+  lines.push('contrib_row() {');
+  lines.push('  case "$1" in');
+  for (const r of rows) {
+    lines.push(`    ${r.key}) printf '%s' '${r.payload}|${r.host}|${r.wire}' ;;`);
+  }
+  lines.push("    *) return 0 ;;");
+  lines.push('  esac');
+  lines.push('}');
+  lines.push(END);
+  return lines.join('\n');
+}
+
+function splice(scriptText, block) {
+  const b = scriptText.indexOf(BEGIN);
+  const e = scriptText.indexOf(END);
+  if (b < 0 || e < 0) {
+    throw new Error('BEGIN/END GENERATED markers not found in target script');
+  }
+  const before = scriptText.slice(0, b);
+  const after = scriptText.slice(e + END.length);
+  return before + block + after;
+}
+
+const rows = readTable();
+const block = renderBlock(rows);
+
+const arg = process.argv[2];
+const target = process.argv[3];
+
+if (arg === '--write') {
+  const text = fs.readFileSync(target, 'utf-8');
+  fs.writeFileSync(target, splice(text, block));
+  console.error(`Wrote generated contribution table into ${target}`);
+} else if (arg === '--check') {
+  const text = fs.readFileSync(target, 'utf-8');
+  const expected = splice(text, block);
+  if (expected !== text) {
+    console.error(
+      `OUT OF SYNC: ${target} differs from contribution-table.ts. ` +
+        `Run: node scripts/generate-scan-packages-table.mjs --write ${target}`,
+    );
+    process.exit(1);
+  }
+  console.error(`${target} is in sync with the contribution table.`);
+} else {
+  process.stdout.write(block + '\n');
+}