@indigoai-us/hq-cli 5.49.0 → 5.50.1

package/src/utils/pack-contributions.ts

@@ -1,26 +1,97 @@
 /**
- * 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 * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import type { PackManifest, PackContributeKey } from '../types.js';
+import { CONTRIBUTION_TABLE, payloadFor, type WireMode } from './contribution-table.js';
+import {
+  unregisterMcpServers,
+  type UnregisterServerResult,
+  type SafeWriteEnv,
+  type AcquireLockOptions,
+} 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 };
+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 function routeContribution(key: PackContributeKey): WireMode {
+  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: Partial<Record<PackContributeKey, string[]>>,
+): PackContributeKey[] {
+  const out: PackContributeKey[] = [];
+  for (const [key, items] of Object.entries(contributes) as [
+    PackContributeKey,
+    unknown,
+  ][]) {
+    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;
+}
 
 /** A single symlink a pack contributes: dst (host path) -> src (inside pack). */
 export interface WiredLink {
@@ -37,58 +108,40 @@ export type LinkStatus =
   | 'foreign'; // dst exists but points elsewhere or is a real file (collision)
 
 /**
- * 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.
+ * 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: string,
   packDir: string,
   key: PackContributeKey,
   item: string,
-): WiredLink {
-  let srcRel: string;
-  let dstRel: string;
-  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;
-  }
+): WiredLink | null {
+  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: string,
@@ -100,10 +153,17 @@ export function contributionLinks(
     PackContributeKey,
     unknown,
   ][]) {
+    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;
@@ -256,6 +316,76 @@ export function unwirePack(
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// MCP un-wiring (US-009) — the `wire: 'merge'` parallel to symlink un-wiring.
+//
+// `unwirePack` above only removes SYMLINKS: it iterates `contributionLinks`, which
+// SKIPS every `wire: 'merge'` key (e.g. `mcp`). So a pack's MCP servers — registered
+// into ~/.claude.json + ~/.codex/config.toml, NOT symlinked — are INVISIBLE to the
+// symlink unwire and would leak after uninstall. `unwirePackMcp` is the parallel
+// path: for each name in `contributes.mcp` it calls `unregisterMcpServers` (US-009),
+// which removes ONLY entries whose `_hqPack` provenance matches THIS pack and
+// skip-and-warns on any foreign/unstamped same-named entry.
+//
+// Kept as a SEPARATE, composable call from `unwirePack` (not folded into it) so the
+// existing `unwirePack` signature + tests stay intact and each path is testable in
+// isolation. The uninstall command composes both (symlink unwire + MCP unwire).
+// ---------------------------------------------------------------------------
+
+/** 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 function unwirePackMcp(
+  packName: string,
+  contributes: Partial<Record<PackContributeKey, string[]>>,
+  options?: UnwirePackMcpOptions,
+): UnwireMcpResult {
+  const servers: UnregisterServerResult[] = [];
+  for (const key of mergeKeys(contributes)) {
+    const names = (contributes[key] ?? []).filter(
+      (n): n is string => 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
 // ---------------------------------------------------------------------------

package/src/utils/secrets-cache.ts

@@ -142,6 +142,28 @@ export function writeCache(
   }
 }
 
+/**
+ * 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(): string[] {
+  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: string, name: string): void {
   if (!validateInputs(companyUid, name)) return;
   const filePath = path.join(CACHE_DIR, companyUid, name);

package/test/e2e/smoke-install-mcp.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# smoke-install-mcp.sh — TRUE end-to-end smoke test of `hq install` for
+# MCP-bearing packs, in a fully isolated sandbox.
+#
+# Unlike the vitest suite (which unit-tests mcp-registration.ts against an
+# injected $HOME), this drives the REAL built `hq` CLI through a REAL
+# `hq install` against REAL packs, so it catches WIRING gaps unit tests miss —
+# e.g. "registerMcpServers is implemented + tested but installPack never calls
+# it" (the exact bug this harness first caught).
+#
+# It NEVER touches the developer's real ~/.claude.json, ~/.mcp.json, or
+# ~/.codex/config.toml — everything lives under a mktemp sandbox HOME, and the
+# install targets a sandbox HQ root.
+#
+# Two packs, two paths:
+#   A) hq-pack-smoke-mcp  (no-secret fixture) → MUST register into both configs
+#   B) vyg-shopify-hq-pack (needs ${secret:VYG_API_KEY}) → MUST defer gracefully
+#      (install succeeds, server NOT registered, "connect first" warning shown)
+#
+# Usage:   bash test/e2e/smoke-install-mcp.sh [--keep]
+# Exit 0 = all checks pass.   Exit 1 = at least one failed.
+# ---------------------------------------------------------------------------
+set -uo pipefail
+
+CLI_REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+HQ_ROOT_REAL="$(cd "$CLI_REPO/../../.." && pwd)"             # …/HQ
+CLI="$CLI_REPO/dist/index.js"
+FIXTURE="$CLI_REPO/test/fixtures/hq-pack-smoke-mcp"          # no-secret pack
+VYG="$HQ_ROOT_REAL/repos/private/vyg-shopify-hq-pack"        # secret-bearing pack
+KEEP=0; [ "${1:-}" = "--keep" ] && KEEP=1
+
+pass=0; fail=0
+ok()  { echo "  ✓ $1"; pass=$((pass+1)); }
+bad() { echo "  ✗ $1"; fail=$((fail+1)); }
+
+[ -f "$CLI" ]     || { echo "FATAL: build first (npm run build) — missing $CLI"; exit 2; }
+[ -d "$FIXTURE" ] || { echo "FATAL: fixture pack missing at $FIXTURE"; exit 2; }
+command -v node >/dev/null || { echo "FATAL: node not on PATH"; exit 2; }
+
+SBX="$(mktemp -d -t hq-smoke-mcp.XXXXXX)"
+SBX_HOME="$SBX/home"; SBX_HQ="$SBX/hq"
+cleanup() { [ "$KEEP" = 1 ] && { echo "sandbox kept: $SBX"; return; }; rm -rf "$SBX"; }
+trap cleanup EXIT
+
+mkdir -p "$SBX_HOME/.codex" "$SBX_HQ/core/packages" "$SBX_HQ/core/workers/public" \
+         "$SBX_HQ/core/knowledge/public/hq-core" "$SBX_HQ/core/policies" \
+         "$SBX_HQ/core/hooks" "$SBX_HQ/.claude/skills" "$SBX_HQ/.claude/commands" \
+         "$SBX_HQ/companies"
+cp -R "$HQ_ROOT_REAL/core/scripts" "$SBX_HQ/core/scripts"
+# Pin the sandbox host version at the M1 floor (>=15.1.0). Copying the live
+# core.yaml is unreliable — hq-sync can reset it below the floor (e.g. 15.0.24),
+# which makes the floor check CORRECTLY refuse the test packs (they require
+# >=15.1.0). This harness exercises the install path; floor-refusal has its own
+# unit test. Pin a satisfying version so the install path is what's under test.
+printf 'hqVersion: "15.1.0"\n' > "$SBX_HQ/core/core.yaml"
+cp "$HQ_ROOT_REAL/core/knowledge/public/hq-core/mcp-manifest.schema.json" \
+   "$SBX_HQ/core/knowledge/public/hq-core/mcp-manifest.schema.json"
+printf 'companies: {}\n' > "$SBX_HQ/companies/manifest.yaml"
+
+# pre-existing non-HQ servers that MUST survive every install/uninstall
+echo '{ "mcpServers": { "figma": { "type": "http", "url": "https://figma.example.test/mcp" } } }' > "$SBX_HOME/.claude.json"
+printf '# user existing codex config\n[mcp_servers.node_repl]\ncommand = "node"\nargs = ["--repl"]\n' > "$SBX_HOME/.codex/config.toml"
+
+# Always run from inside the sandbox HQ root. The CLI resolves the HQ root by
+# walking up from cwd (utils/manifest.js findHqRoot), NOT from $HQ_ROOT — so the
+# cwd is what actually scopes install/uninstall. (We still export HQ_ROOT for the
+# code paths that DO honor it, e.g. scan-packages.) Without the cd, `packs
+# uninstall` resolves the developer's real HQ root and silently no-ops.
+run_hq() { ( cd "$SBX_HQ" && HOME="$SBX_HOME" HQ_ROOT="$SBX_HQ" node "$CLI" "$@" ); }
+claude_has() { node -e "try{const j=require('$SBX_HOME/.claude.json');process.stdout.write(j.mcpServers&&j.mcpServers['$1']?'1':'0')}catch(e){process.stdout.write('0')}"; }
+codex_has()  { c=$(grep -c "\[mcp_servers.$1\]" "$SBX_HOME/.codex/config.toml" 2>/dev/null); echo "${c:-0}"; }
+
+echo "=== HQ MCP install smoke test ==="
+echo "sandbox: $SBX"; echo
+
+# ---- A) NO-SECRET FIXTURE → must register ---------------------------------
+echo "[A] install no-secret fixture (hq-pack-smoke-mcp) — must REGISTER"
+OUT="$(cd "$SBX_HQ" && run_hq install "$FIXTURE" --allow-mcp --allow-hooks 2>&1)"; rc=$?
+echo "$OUT" | sed 's/^/      /'
+[ $rc -eq 0 ] && ok "install exited 0" || bad "install exited $rc"
+[ "$(claude_has smoke-http)" = "1" ] && ok "smoke-http registered in ~/.claude.json" || bad "smoke-http MISSING from ~/.claude.json"
+[ "$(codex_has smoke-http)" -ge 1 ] && ok "smoke-http registered in ~/.codex/config.toml" || bad "smoke-http MISSING from ~/.codex/config.toml"
+[ "$(claude_has figma)" = "1" ]     && ok "figma preserved" || bad "figma LOST"
+[ "$(codex_has node_repl)" -ge 1 ]  && ok "node_repl table preserved" || bad "node_repl LOST"
+if grep -rqiE 'X-Smoke.*static-not-a-secret' "$SBX_HOME/.claude.json"; then ok "static header written (http client usable)"; else bad "static header missing from registered server"; fi
+
+echo "[A.2] hq mcp status --json reports it"
+ST="$(run_hq mcp status --json 2>&1)"
+echo "$ST" | grep -q 'smoke-http' && ok "mcp status reports smoke-http" || bad "mcp status missing smoke-http"
+
+echo "[A.3] uninstall round-trip"
+run_hq packs uninstall hq-pack-smoke-mcp --yes >/dev/null 2>&1 || run_hq packs uninstall hq-pack-smoke-mcp >/dev/null 2>&1
+[ "$(claude_has smoke-http)" = "0" ] && ok "smoke-http removed on uninstall" || bad "smoke-http still present after uninstall"
+[ "$(claude_has figma)" = "1" ]     && ok "figma still preserved after uninstall" || bad "figma lost during uninstall"
+
+# ---- B) VYG PACK (needs a vault secret) → must DEFER gracefully -----------
+echo
+echo "[B] install vyg pack (needs \${secret:VYG_API_KEY}, not in vault) — must DEFER gracefully"
+if [ -d "$VYG" ]; then
+  OUT="$(cd "$SBX_HQ" && run_hq install "$VYG" --allow-mcp --allow-hooks 2>&1)"; rc=$?
+  echo "$OUT" | sed 's/^/      /'
+  [ $rc -eq 0 ] && ok "install exited 0 (did not abort on the missing secret)" || bad "install aborted (rc=$rc) on missing secret"
+  [ "$(claude_has vyg-shopify)" = "0" ] && ok "vyg-shopify correctly DEFERRED (not registered without its key)" || bad "vyg-shopify registered despite missing secret"
+  echo "$OUT" | grep -qiE "VYG_API_KEY|connect-shopify|needs secret" && ok "clear 'provision the key' guidance shown" || bad "no deferral guidance shown to the user"
+  [ "$(claude_has figma)" = "1" ] && ok "figma still preserved through the deferred install" || bad "figma LOST during deferred install"
+else
+  echo "  · vyg pack not present — skipping deferral checks"
+fi
+
+echo
+echo "=== RESULT: $pass passed · $fail failed ==="
+[ $fail -eq 0 ] && exit 0 || exit 1

package/test/fixtures/hq-pack-smoke-mcp/mcp/smoke-http.json

@@ -0,0 +1 @@
+{ "type": "http", "url": "https://smoke.example.test/mcp", "headers": { "X-Smoke": "static-not-a-secret" } }

package/test/fixtures/hq-pack-smoke-mcp/package.yaml

@@ -0,0 +1,11 @@
+name: hq-pack-smoke-mcp
+version: 0.0.1
+publisher: '@indigoai-us'
+access: public
+description: 'No-secret MCP pack — e2e smoke fixture for install registration.'
+requires:
+  hqCore: '>=15.1.0'
+capabilities: [network]
+contributes:
+  mcp:
+    - smoke-http