@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/utils/pack-contributions.test.ts

@@ -16,24 +16,42 @@ import {
   contributionLinks,
   linkStatus,
   listInstalledPacks,
+  findDependentPacks,
   unwirePack,
+  unwirePackMcp,
   packagesDir,
   readHqVersion,
   type WiredLink,
+  type InstalledPack,
 } from './pack-contributions.js';
+import { parse as parseToml } from 'smol-toml';
+import {
+  registerClaudeServer,
+  registerServer,
+  claudeConfigPath,
+  codexConfigPath,
+  codexHome,
+} from '../commands/mcp-registration.js';
+import {
+  CONTRIBUTION_TABLE,
+  CONTRIBUTION_KEYS,
+  SYMLINK_KEYS,
+  payloadFor,
+  type ContributionKey,
+} from './contribution-table.js';
 import type { PackContributeKey } from '../types.js';
 
-// The canonical mapping, encoded once here as the test oracle. Host paths are
-// relative to hqRoot; src paths relative to the pack dir.
-const EXPECTED: Record<PackContributeKey, { src: string; dst: string }> = {
-  workers: { src: 'workers/X', dst: 'core/workers/public/X' },
-  knowledge: { src: 'knowledge/X', dst: 'core/knowledge/public/X' },
-  skills: { src: 'skills/X', dst: '.claude/skills/X' },
-  commands: { src: 'commands/X.md', dst: '.claude/commands/X.md' },
-  hooks: { src: 'hooks/X.sh', dst: '.claude/hooks/X.sh' },
-  policies: { src: 'policies/X.md', dst: 'core/policies/X.md' },
-  scripts: { src: 'scripts/X', dst: 'core/scripts/X' },
-};
+// The canonical mapping is DERIVED from the single-source CONTRIBUTION_TABLE
+// (US-003) -- the oracle is no longer a hand-restated copy. For each SYMLINK
+// key, src = the payload expanded for item "X"; dst = <host-dir>/<basename>.
+const EXPECTED: Record<ContributionKey, { src: string; dst: string }> =
+  Object.fromEntries(
+    SYMLINK_KEYS.map((k) => {
+      const src = payloadFor(k, 'X');
+      const dst = `${CONTRIBUTION_TABLE[k].host}/${src.split('/').pop()}`;
+      return [k, { src, dst }];
+    }),
+  ) as Record<ContributionKey, { src: string; dst: string }>;
 
 function mkTmp(prefix: string): string {
   // realpathSync so macOS /tmp -> /private/tmp doesn't break path equality.
@@ -41,10 +59,10 @@ function mkTmp(prefix: string): string {
 }
 
 describe('contributionLinks: mapping', () => {
-  it('maps every contributes key to the canonical src/dst', () => {
+  it('maps every SYMLINK contributes key to the canonical src/dst', () => {
     const hqRoot = '/hq';
     const packDir = '/hq/core/packages/hq-pack-x';
-    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
+    for (const key of SYMLINK_KEYS) {
       const [link] = contributionLinks(hqRoot, packDir, { [key]: ['X'] });
       expect(link.key).toBe(key);
       expect(link.src).toBe(path.join(packDir, EXPECTED[key].src));
@@ -52,6 +70,19 @@ describe('contributionLinks: mapping', () => {
     }
   });
 
+  it('produces NO symlink for wire:merge keys (mcp)', () => {
+    // The mcp row is wire:merge — declared as data (US-003) but never wired as a
+    // symlink here; its host effect is a config merge (US-004/US-005).
+    const mergeKeys = CONTRIBUTION_KEYS.filter(
+      (k) => CONTRIBUTION_TABLE[k].wire === 'merge',
+    );
+    expect(mergeKeys).toContain('mcp'); // guards the row exists
+    for (const key of mergeKeys) {
+      const links = contributionLinks('/hq', '/p', { [key]: ['X'] });
+      expect(links).toEqual([]);
+    }
+  });
+
   it('ignores empty / non-array contributes subfields', () => {
     const links = contributionLinks('/hq', '/p', {
       skills: [],
@@ -63,21 +94,118 @@ describe('contributionLinks: mapping', () => {
   });
 });
 
-describe('contributionLinks: parity with scan-packages.sh', () => {
-  // Best-effort drift guard: if the bash wirer is reachable, confirm each
-  // case arm's dst suffix matches our TS mapping. Skips cleanly off-tree.
-  const candidates = [
+// ---------------------------------------------------------------------------
+// US-003 single-source parity: FULL key-set + payload-suffix + wire-mode
+// equivalence across every surface (table, derived union, validateManifest's
+// payload reader, and the generated scan-packages.sh block). Replaces the old
+// substring-only `toContain` check, which passed even if a key was MISSING, had
+// the WRONG payload suffix, or the WRONG wire mode.
+// ---------------------------------------------------------------------------
+describe('US-003 parity: contribution table is the single source', () => {
+  // Resolve the HQ root so we can read the GENERATED scan-packages.sh block.
+  const scanCandidates = [
     path.resolve(process.cwd(), '../../../core/scripts/scan-packages.sh'),
     path.resolve(process.cwd(), '../../../../core/scripts/scan-packages.sh'),
   ];
-  const scanPath = candidates.find((p) => fs.existsSync(p));
-
-  (scanPath ? it : it.skip)('dst suffixes match the bash case arms', () => {
-    const bash = fs.readFileSync(scanPath as string, 'utf-8');
-    for (const key of Object.keys(EXPECTED) as PackContributeKey[]) {
-      // dst host-path suffix, with the trailing /$item or /$item.md stripped.
-      const suffix = EXPECTED[key].dst.replace(/\/X(\.\w+)?$/, '');
-      expect(bash).toContain(suffix); // e.g. core/workers/public, .claude/skills
+  const scanPath = scanCandidates.find((p) => fs.existsSync(p));
+
+  // Parse the generated `contrib_row` case arms back into {key:{payload,host,wire}}.
+  function parseBashTable(bash: string): Record<
+    string,
+    { payload: string; host: string; wire: string }
+  > {
+    const out: Record<string, { payload: string; host: string; wire: string }> = {};
+    const re =
+      /^\s*([a-z]+)\)\s*printf\s+'%s'\s+'([^|]+)\|([^|]+)\|([^']+)'\s*;;/gm;
+    let m;
+    while ((m = re.exec(bash)) !== null) {
+      out[m[1]] = { payload: m[2], host: m[3], wire: m[4] };
+    }
+    return out;
+  }
+
+  it('the derived PackContributeKey union == the table keys (8 keys incl. mcp)', () => {
+    // CONTRIBUTION_KEYS IS PackContributeKey's source (types.ts derives the
+    // union from it). Assert the full expected set is present, no more, no less.
+    expect([...CONTRIBUTION_KEYS].sort()).toEqual(
+      [
+        'commands',
+        'hooks',
+        'knowledge',
+        'mcp',
+        'policies',
+        'scripts',
+        'skills',
+        'workers',
+      ].sort(),
+    );
+    // Type-level: every key is assignable to PackContributeKey.
+    const asUnion: PackContributeKey[] = [...CONTRIBUTION_KEYS];
+    expect(asUnion.length).toBe(8);
+  });
+
+  it('every key has a wire mode of exactly symlink|merge, mcp is the merge row', () => {
+    for (const k of CONTRIBUTION_KEYS) {
+      expect(['symlink', 'merge']).toContain(CONTRIBUTION_TABLE[k].wire);
+    }
+    expect(CONTRIBUTION_TABLE.mcp.wire).toBe('merge');
+    expect(CONTRIBUTION_TABLE.mcp.payload).toBe('mcp/{item}.json');
+    expect(CONTRIBUTION_TABLE.mcp.host).toBe('merge:claude+codex');
+    // All non-mcp rows are symlink in this milestone.
+    for (const k of CONTRIBUTION_KEYS) {
+      if (k !== 'mcp') expect(CONTRIBUTION_TABLE[k].wire).toBe('symlink');
+    }
+  });
+
+  it('payload suffixes are pinned per key (suffix is load-bearing)', () => {
+    const suffix = (p: string) => {
+      const base = p.split('/').pop() as string;
+      const dot = base.indexOf('.', base.indexOf('}'));
+      return dot >= 0 ? base.slice(dot) : '';
+    };
+    expect(suffix(CONTRIBUTION_TABLE.commands.payload)).toBe('.md');
+    expect(suffix(CONTRIBUTION_TABLE.policies.payload)).toBe('.md');
+    expect(suffix(CONTRIBUTION_TABLE.hooks.payload)).toBe('.sh');
+    expect(suffix(CONTRIBUTION_TABLE.mcp.payload)).toBe('.json');
+    expect(suffix(CONTRIBUTION_TABLE.workers.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.knowledge.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.skills.payload)).toBe('');
+    expect(suffix(CONTRIBUTION_TABLE.scripts.payload)).toBe('');
+  });
+
+  (scanPath ? it : it.skip)(
+    'scan-packages.sh generated block matches the table on key-set + payload + host + wire',
+    () => {
+      const bash = fs.readFileSync(scanPath as string, 'utf-8');
+      const bashTable = parseBashTable(bash);
+
+      // FULL key-set equivalence (fails if a surface is MISSING a key or has an
+      // EXTRA one — not just a substring presence check).
+      expect(Object.keys(bashTable).sort()).toEqual([...CONTRIBUTION_KEYS].sort());
+
+      // Per-key payload + host + wire-mode equivalence.
+      for (const k of CONTRIBUTION_KEYS) {
+        expect(bashTable[k], `scan-packages.sh missing row for "${k}"`).toBeDefined();
+        expect(bashTable[k].payload).toBe(CONTRIBUTION_TABLE[k].payload);
+        expect(bashTable[k].host).toBe(CONTRIBUTION_TABLE[k].host);
+        expect(bashTable[k].wire).toBe(CONTRIBUTION_TABLE[k].wire);
+      }
+
+      // The CONTRIB_KEYS array in the script also lists every key.
+      const keysLine = bash.match(/CONTRIB_KEYS=\(([^)]*)\)/);
+      expect(keysLine).not.toBeNull();
+      const bashKeys = (keysLine as RegExpMatchArray)[1].trim().split(/\s+/).sort();
+      expect(bashKeys).toEqual([...CONTRIBUTION_KEYS].sort());
+    },
+  );
+
+  it('validateManifest payload reader (payloadFor) agrees with the table for every key', () => {
+    for (const k of CONTRIBUTION_KEYS) {
+      // payloadFor is exactly what validateManifest now uses for the
+      // payload-existence check, so this pins that surface to the table.
+      expect(payloadFor(k, 'demo')).toBe(
+        CONTRIBUTION_TABLE[k].payload.replace('{item}', 'demo'),
+      );
     }
   });
 });
@@ -257,3 +385,160 @@ describe('readHqVersion: v15 layout awareness (feedback_57d7edcf, symptom b)', (
     expect(readHqVersion(hqRoot)).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// US-009: unwirePackMcp — the wire:merge (MCP) un-registration parallel to the
+// symlink unwirePack. Runs against an ISOLATED tmpdir home (env.home) so the
+// developer's real ~/.claude.json / ~/.codex are NEVER touched.
+// ---------------------------------------------------------------------------
+
+describe('US-009: unwirePackMcp (mcp un-registration parallel to symlink unwire)', () => {
+  let mcpHome: string;
+
+  beforeEach(() => {
+    mcpHome = mkTmp('hq-unwire-mcp-');
+  });
+  afterEach(() => {
+    fs.rmSync(mcpHome, { recursive: true, force: true });
+  });
+
+  it('un-registers ONLY this pack\'s provenance-stamped mcp servers from ~/.claude.json', () => {
+    const env = { home: mcpHome };
+    // The user owns `figma`; our pack installs `vyg`.
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { figma: { type: 'http', url: 'https://figma' } } }, null, 2) + '\n',
+    );
+    registerClaudeServer({ name: 'vyg', manifest: { type: 'http', url: 'https://vyg' }, pack: 'hq-pack-vyg', env });
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers).toHaveLength(1);
+    expect(result.servers[0]!.claude.outcome).toBe('removed');
+
+    const after = JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8'));
+    expect(after.mcpServers.vyg).toBeUndefined(); // ours removed
+    expect(after.mcpServers.figma.url).toBe('https://figma'); // user sibling preserved
+  });
+
+  it('no-ops cleanly when the pack declares no mcp (merge) keys', () => {
+    const result = unwirePackMcp('hq-pack-x', { commands: ['foo'], skills: ['bar'] }, { env: { home: mcpHome } });
+    expect(result.servers).toEqual([]);
+  });
+
+  it('skip-and-warns (does not delete) a foreign/unstamped same-named entry', () => {
+    const env = { home: mcpHome };
+    // The user has their OWN `vyg` (no _hqPack stamp).
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { vyg: { type: 'http', url: 'https://user-vyg' } } }, null, 2) + '\n',
+    );
+    const before = fs.readFileSync(claudeConfigPath(env), 'utf-8');
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers[0]!.claude.outcome).toBe('skipped-foreign');
+    // The user's server is left byte-for-byte intact.
+    expect(fs.readFileSync(claudeConfigPath(env), 'utf-8')).toBe(before);
+  });
+
+  it('is a clean no-op on a Codex-less host with no ~/.claude.json (never fabricates)', () => {
+    const env = { home: mcpHome };
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers[0]!.claude.outcome).toBe('absent');
+    expect('skipped' in result.servers[0]!.codex && (result.servers[0]!.codex as any).skipped).toBe(true);
+    expect(fs.existsSync(path.join(mcpHome, '.claude.json'))).toBe(false);
+    expect(fs.existsSync(path.join(mcpHome, '.codex'))).toBe(false);
+  });
+
+  it('delegates to unregisterMcpServers across BOTH surfaces when ~/.codex exists', () => {
+    // The unwire-hook must un-register from Claude AND Codex (not just Claude) — i.e.
+    // it really delegates to unregisterMcpServers, which fans out over both surfaces.
+    const env = { home: mcpHome };
+    fs.mkdirSync(codexHome(env), { recursive: true }); // make Codex a real runtime
+    // Install our vyg into BOTH surfaces, alongside a user-owned figma on Claude.
+    fs.writeFileSync(
+      claudeConfigPath(env),
+      JSON.stringify({ mcpServers: { figma: { type: 'http', url: 'https://figma' } } }, null, 2) + '\n',
+    );
+    registerServer({ name: 'vyg', manifest: { type: 'http', url: 'https://vyg' }, pack: 'hq-pack-vyg', env });
+    // Both surfaces carry vyg before uninstall.
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.vyg).toBeDefined();
+    expect((parseToml(fs.readFileSync(codexConfigPath(env), 'utf-8')) as any).mcp_servers.vyg).toBeDefined();
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect(result.servers).toHaveLength(1);
+    expect(result.servers[0]!.claude.outcome).toBe('removed');
+    expect('skipped' in result.servers[0]!.codex).toBe(false);
+    expect((result.servers[0]!.codex as any).outcome).toBe('removed');
+
+    // Both surfaces no longer carry vyg; the user's Claude figma sibling survives.
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.vyg).toBeUndefined();
+    expect(JSON.parse(fs.readFileSync(claudeConfigPath(env), 'utf-8')).mcpServers.figma).toBeDefined();
+    expect((parseToml(fs.readFileSync(codexConfigPath(env), 'utf-8')) as any).mcp_servers.vyg).toBeUndefined();
+  });
+
+  it('skip-and-warns a foreign Codex table too (does not delete another pack\'s server)', () => {
+    // The Codex parallel of the foreign skip: a vyg table stamped by ANOTHER pack must
+    // be left in place when uninstalling OUR pack — provenance scope, not name match.
+    const env = { home: mcpHome };
+    fs.mkdirSync(codexHome(env), { recursive: true });
+    const original =
+      '# keep me\n[mcp_servers.vyg]\ntype = "http"\nurl = "https://vyg"\n_hqPack = "hq-pack-OTHER"\n';
+    fs.writeFileSync(codexConfigPath(env), original);
+
+    const result = unwirePackMcp('hq-pack-vyg', { mcp: ['vyg'] }, { env });
+    expect((result.servers[0]!.codex as any).outcome).toBe('skipped-foreign');
+    // Byte-for-byte preserved (comment intact — no write on a foreign skip).
+    expect(fs.readFileSync(codexConfigPath(env), 'utf-8')).toBe(original);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findDependentPacks — uninstall dependents guard (M0)
+// ---------------------------------------------------------------------------
+
+describe('findDependentPacks (M0)', () => {
+  function ip(
+    name: string,
+    requiresPacks?: Array<{ name: string; version?: string }>,
+  ): InstalledPack {
+    return {
+      name,
+      dir: `/tmp/nope/${name}`,
+      manifest: {
+        name,
+        version: '1.0.0',
+        publisher: '@indigoai-us',
+        access: 'public',
+        requires: { hqCore: '>=15.0.0', packs: requiresPacks },
+        contributes: { skills: ['x'] },
+      },
+    } as InstalledPack;
+  }
+
+  it('returns the packs that require the named pack', () => {
+    const installed = [
+      ip('hq-pack-crm'),
+      ip('hq-pack-accounting', [{ name: 'hq-pack-crm', version: '>=1.0.0' }]),
+      ip('hq-pack-unrelated'),
+    ];
+    const deps = findDependentPacks(installed, 'hq-pack-crm');
+    expect(deps.map((p) => p.name)).toEqual(['hq-pack-accounting']);
+  });
+
+  it('returns empty when no installed pack requires it', () => {
+    const installed = [ip('hq-pack-crm'), ip('hq-pack-unrelated')];
+    expect(findDependentPacks(installed, 'hq-pack-crm')).toEqual([]);
+  });
+
+  it('never counts a pack that lists itself as its own dependent', () => {
+    // Defensive: a self-referencing manifest (rejected at install) must not make
+    // a pack un-removable.
+    const installed = [ip('hq-pack-weird', [{ name: 'hq-pack-weird' }])];
+    expect(findDependentPacks(installed, 'hq-pack-weird')).toEqual([]);
+  });
+
+  it('tolerates an unreadable manifest (manifest === null)', () => {
+    const broken: InstalledPack = { name: 'hq-pack-broken', dir: '/tmp/nope', manifest: null };
+    expect(findDependentPacks([broken], 'hq-pack-crm')).toEqual([]);
+  });
+});