@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/commands/pack-install.test.ts

@@ -26,14 +26,24 @@ import {
   runScanPackages,
   stampInstallSource,
   validateManifest,
+  assertPackDependencies,
   getStartedLine,
   toMarketplaceListing,
   fetchMarketplace,
   computeArtifactHash,
   ArtifactVerificationError,
+  validateMcpManifest,
+  renderMcpServerLine,
+  confirmMcp,
 } from './pack-install.js';
 import type { MarketplaceDeps } from './pack-install.js';
 import type { PackManifest } from '../types.js';
+import { registerMcpServers, McpManifestError } from './mcp-registration.js';
+import {
+  routeContribution,
+  mergeKeys,
+  contributionLinks,
+} from '../utils/pack-contributions.js';
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -357,6 +367,71 @@ describe('pack-install: install path layout', () => {
     });
   });
 
+  // ---- 7b. MCP-bearing pack version FLOOR (US-012, M1 platform-GA) ----------
+  // The `contributes.mcp` capability is carried by hqCore >=15.1.0. An MCP-bearing
+  // pack therefore declares `requires.hqCore '>=15.1.0'` (or '>15.0.19'). On an
+  // OLDER host (15.0.19) the installer must REFUSE the pack with a clear version-
+  // floor message naming the host version + the requirement — the MCP wiring is
+  // never silently dropped. On the floor host (15.1.0) the same pack PASSES.
+  // Enforcement lives in validateManifest at the `does not satisfy` throw site.
+  describe('US-012: MCP-bearing pack version floor (>=15.1.0)', () => {
+    // A real-shaped MCP pack: declares `contributes.mcp` (one server, manifest
+    // present) and a `requires.hqCore` range. The only variable is the range, so
+    // the floor check is what's under test.
+    function writeMcpPackRequiring(range: string): string {
+      const dir = mkFakePackPayload({
+        'mcp/vyg.json': JSON.stringify({
+          type: 'http',
+          url: 'https://mcp.vyg.app',
+          headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+        }),
+      });
+      fs.writeFileSync(
+        path.join(dir, 'package.yaml'),
+        [
+          'name: hq-pack-vyg-shopify',
+          'version: 1.0.0',
+          "publisher: '@indigoai-us'",
+          'access: public',
+          'requires:',
+          `  hqCore: '${range}'`,
+          'contributes:',
+          '  mcp:',
+          '    - vyg',
+          '',
+        ].join('\n'),
+      );
+      return dir;
+    }
+
+    it('REFUSES an MCP pack (>=15.1.0) on an older host (15.0.19) with a clear floor message', () => {
+      const dir = writeMcpPackRequiring('>=15.1.0');
+      // Refused, and the message NAMES both the host version and the requirement.
+      expect(() => validateManifest(dir, '15.0.19')).toThrow(
+        /does not satisfy pack requirement/,
+      );
+      expect(() => validateManifest(dir, '15.0.19')).toThrow(/15\.0\.19/);
+      expect(() => validateManifest(dir, '15.0.19')).toThrow(/>=15\.1\.0/);
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('REFUSES the same pack expressed as `>15.0.19` on a 15.0.19 host', () => {
+      const dir = writeMcpPackRequiring('>15.0.19');
+      expect(() => validateManifest(dir, '15.0.19')).toThrow(
+        /does not satisfy pack requirement/,
+      );
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+
+    it('PASSES the same MCP pack on the floor host (15.1.0)', () => {
+      const dir = writeMcpPackRequiring('>=15.1.0');
+      const m = validateManifest(dir, '15.1.0');
+      expect(m.name).toBe('hq-pack-vyg-shopify');
+      expect(m.contributes?.mcp).toEqual(['vyg']);
+      fs.rmSync(dir, { recursive: true, force: true });
+    });
+  });
+
   // ---- 8. initialization.entrypoint validation (US-004) -------------------
   // A pack may declare an `initialization` block whose `entrypoint` MUST resolve
   // to a declared contributes skill/command. The block is OPTIONAL and
@@ -608,6 +683,521 @@ describe('pack-install: install path layout', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// contributes.mcp — shape-validate manifest + route wire:merge (US-005)
+//
+// Acceptance: "Given a pack with contributes.mcp, when validateManifest runs,
+// then the manifest is shape-validated and routed as wire:merge (not
+// symlinked)." Mirrors the bash validate_mcp_manifest arm in scan-packages.sh.
+// ---------------------------------------------------------------------------
+
+describe('pack-install: contributes.mcp shape-validation + routing (US-005)', () => {
+  // Build a pack whose package.yaml declares one mcp server (`vyg`) and whose
+  // mcp/vyg.json holds `manifest`. The only variable across tests is the
+  // manifest JSON body, so the shape/secret rules are what's under test.
+  function writeMcpPack(manifest: unknown): string {
+    const dir = mkFakePackPayload({
+      'mcp/vyg.json':
+        typeof manifest === 'string' ? manifest : JSON.stringify(manifest),
+    });
+    fs.writeFileSync(
+      path.join(dir, 'package.yaml'),
+      [
+        'name: hq-pack-test',
+        'version: 1.0.0',
+        "publisher: '@indigoai-us'",
+        'access: public',
+        'requires:',
+        "  hqCore: '>=12.0.0'",
+        'contributes:',
+        '  mcp:',
+        '    - vyg',
+        '',
+      ].join('\n'),
+    );
+    return dir;
+  }
+
+  it('a valid http mcp manifest (secret-ref Bearer) passes validateManifest', () => {
+    const dir = writeMcpPack({
+      type: 'http',
+      url: 'https://mcp.vyg.app',
+      headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+    });
+    const m = validateManifest(dir, '12.0.0');
+    expect(m.name).toBe('hq-pack-test');
+    expect(m.contributes.mcp).toEqual(['vyg']);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an inline literal Bearer secret (no ${secret:} reference)', () => {
+    const dir = writeMcpPack({
+      type: 'http',
+      url: 'https://mcp.vyg.app',
+      headers: { Authorization: 'Bearer abc123' },
+    });
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/Bearer/);
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/secret/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects a malformed (non-JSON) mcp manifest, naming the file', () => {
+    const dir = writeMcpPack('{ this is not json ]');
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/mcp\/vyg\.json/);
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/not valid JSON/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an http manifest missing url', () => {
+    const dir = writeMcpPack({ type: 'http' });
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/requires a url/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an http manifest carrying a forbidden command', () => {
+    const dir = writeMcpPack({
+      type: 'http',
+      url: 'https://mcp.vyg.app',
+      command: 'run-me',
+    });
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/forbids: command/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an unknown type and unknown top-level keys', () => {
+    expect(() => validateManifest(writeMcpPack({ type: 'grpc' }), '12.0.0')).toThrow(
+      /type must be one of http\|stdio\|sse/,
+    );
+    expect(() =>
+      validateManifest(
+        writeMcpPack({ type: 'http', url: 'https://x.app', bogus: 1 }),
+        '12.0.0',
+      ),
+    ).toThrow(/unknown top-level key: bogus/);
+  });
+
+  it('validates stdio transport rules (command required; url/headers forbidden)', () => {
+    // stdio is validated now even though EMIT is Phase-2 deferred.
+    const ok = writeMcpPack({ type: 'stdio', command: 'my-server' });
+    expect(validateManifest(ok, '12.0.0').name).toBe('hq-pack-test');
+    fs.rmSync(ok, { recursive: true, force: true });
+
+    expect(() =>
+      validateManifest(writeMcpPack({ type: 'stdio' }), '12.0.0'),
+    ).toThrow(/requires a non-empty command/);
+    expect(() =>
+      validateManifest(
+        writeMcpPack({ type: 'stdio', command: 'x', url: 'https://x.app' }),
+        '12.0.0',
+      ),
+    ).toThrow(/stdio transport forbids: url/);
+  });
+
+  it('rejects non-string header values', () => {
+    const dir = writeMcpPack({
+      type: 'http',
+      url: 'https://mcp.vyg.app',
+      headers: { Authorization: 42 },
+    });
+    expect(() => validateManifest(dir, '12.0.0')).toThrow(/headers "Authorization" value must be a string/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('validateMcpManifest can be called directly (the US-006 registration seam reuses it)', () => {
+    const dir = writeMcpPack({ type: 'http', url: 'https://mcp.vyg.app' });
+    expect(() => validateMcpManifest(dir, 'vyg')).not.toThrow();
+    // The pack-relative payload path it reads is mcp/{item}.json.
+    expect(fs.existsSync(path.join(dir, 'mcp', 'vyg.json'))).toBe(true);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  // -- Routing: wire:merge keys go to registerMcpServers, NEVER the symlink path
+  it('the mcp key routes to wire:merge in the single-source table', () => {
+    expect(routeContribution('mcp')).toBe('merge');
+    expect(mergeKeys({ mcp: ['vyg'] })).toEqual(['mcp']);
+    // A symlink key is NOT a merge key.
+    expect(routeContribution('commands')).toBe('symlink');
+    expect(mergeKeys({ commands: ['triage'] })).toEqual([]);
+  });
+
+  it('an mcp-only contributes block produces NO symlink (provably excluded)', () => {
+    const dir = writeMcpPack({ type: 'http', url: 'https://mcp.vyg.app' });
+    // contributionLinks is the symlink enumerator; merge keys must be skipped.
+    expect(contributionLinks('/fake/hq', dir, { mcp: ['vyg'] })).toEqual([]);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('registerMcpServers requires a manifest loader (US-007 wired the Claude emit — no silent no-op)', () => {
+    // US-007 replaced the US-006 NotImplemented seam with a real Claude/JSON
+    // emitter. Called without a manifest loader (no payload context), it fails
+    // loudly with a named McpManifestError rather than throwing NotImplemented or
+    // silently doing nothing — and it does NOT touch any real config (no IO before
+    // the loader check).
+    expect(() => registerMcpServers('hq-pack-test', ['vyg'])).toThrow(McpManifestError);
+    try {
+      registerMcpServers('hq-pack-test', ['vyg']);
+      throw new Error('should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(McpManifestError);
+      expect((e as McpManifestError).code).toBe('McpManifestError');
+      expect((e as Error).message).toMatch(/loadManifest/);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Install-time MCP trust prompt (US-010) — confirmMcp / renderMcpServerLine.
+// Sanity coverage for the production helpers (the full acceptance matrix lands
+// in a later phase). All fixtures use isolated tmpdirs; confirmMcp itself writes
+// NO config — it only renders + (deny/allow) returns a boolean.
+// ---------------------------------------------------------------------------
+
+describe('pack-install: confirmMcp / renderMcpServerLine (US-010)', () => {
+  it('renderMcpServerLine discloses the FULL url and redacts header values (http)', () => {
+    const dir = mkFakePackPayload({
+      'mcp/vyg.json': JSON.stringify({
+        type: 'http',
+        url: 'https://mcp.vyg.app/sse',
+        headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+      }),
+    });
+    const line = renderMcpServerLine(dir, 'vyg');
+    // FULL url verbatim (typosquat disclosure).
+    expect(line).toContain('https://mcp.vyg.app/sse');
+    expect(line).toContain('[http]');
+    // Header KEY shown, but NEVER the raw Bearer/secret-ref value.
+    expect(line).toContain('Authorization');
+    expect(line).not.toContain('Bearer');
+    expect(line).not.toContain('secret:');
+    expect(line).not.toContain('VYG_API_KEY');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('renderMcpServerLine shows command+args and stdio shell-permission warning', () => {
+    const dir = mkFakePackPayload({
+      'mcp/local.json': JSON.stringify({
+        type: 'stdio',
+        command: '/usr/local/bin/foo',
+        args: ['--serve'],
+      }),
+    });
+    const line = renderMcpServerLine(dir, 'local');
+    expect(line).toContain('[stdio]');
+    expect(line).toContain('/usr/local/bin/foo');
+    expect(line).toContain('--serve');
+    expect(line).toMatch(/runs a local binary with your shell permissions/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('renderMcpServerLine fails SAFE on an unreadable manifest (no crash, flagged)', () => {
+    const dir = mkFakePackPayload({ 'mcp/broken.json': '{ not json ]' });
+    const line = renderMcpServerLine(dir, 'broken');
+    expect(line).toContain('broken');
+    expect(line).toContain('[manifest unreadable]');
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('confirmMcp returns true with NO prompt when contributes.mcp is empty', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const ok = await confirmMcp(fakeManifest({ contributes: {} }), '/nope', false);
+    expect(ok).toBe(true);
+    expect(logSpy).not.toHaveBeenCalled();
+    logSpy.mockRestore();
+  });
+
+  it('confirmMcp does NOT gate on the advisory capabilities field (only contributes.mcp)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    // capabilities lists "mcp" but contributes.mcp is empty -> no prompt, true.
+    const ok = await confirmMcp(
+      fakeManifest({ contributes: {}, capabilities: ['mcp', 'network'] }),
+      '/nope',
+      false,
+    );
+    expect(ok).toBe(true);
+    expect(logSpy).not.toHaveBeenCalled();
+    logSpy.mockRestore();
+  });
+
+  it('confirmMcp with --allow-mcp bypasses the prompt and returns true (CI path)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const dir = mkFakePackPayload({
+      'mcp/vyg.json': JSON.stringify({
+        type: 'http',
+        url: 'https://mcp.vyg.app',
+        headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+      }),
+    });
+    const ok = await confirmMcp(
+      fakeManifest({ publisher: '@vyg', contributes: { mcp: ['vyg'] } }),
+      dir,
+      true,
+    );
+    expect(ok).toBe(true);
+    const out = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(out).toMatch(/--allow-mcp set; registering 1 MCP server\(s\) without prompting/);
+    // Bypass notice must never leak a secret either.
+    expect(out).not.toContain('VYG_API_KEY');
+    logSpy.mockRestore();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('confirmMcp denies in a non-TTY shell and prints the --allow-mcp hint (no hang)', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    const prevTty = process.stdin.isTTY;
+    // Force non-interactive — confirmMcp must NOT call rl.question (would hang).
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true });
+    const dir = mkFakePackPayload({
+      'mcp/vyg.json': JSON.stringify({
+        type: 'http',
+        url: 'https://mcp.vyg.app',
+        headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+      }),
+    });
+    try {
+      const ok = await confirmMcp(
+        fakeManifest({ publisher: '@vyg', contributes: { mcp: ['vyg'] } }),
+        dir,
+        false,
+      );
+      expect(ok).toBe(false);
+      const out = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+      expect(out).toMatch(/Re-run with --allow-mcp/);
+      // Rendered prompt must never echo a secret/Bearer substring.
+      expect(out).not.toContain('Bearer');
+      expect(out).not.toContain('VYG_API_KEY');
+      expect(out).not.toContain('secret:');
+      // FULL url still disclosed for the operator.
+      expect(out).toContain('https://mcp.vyg.app');
+    } finally {
+      Object.defineProperty(process.stdin, 'isTTY', { value: prevTty, configurable: true });
+      logSpy.mockRestore();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// US-010: install-time MCP trust prompt — acceptance tests
+//
+// Three story-level acceptance criteria:
+//   1. URL disclosed verbatim; LITERAL sentinel secret never leaks (redaction).
+//   2. Gate is on contributes.mcp, NOT the advisory capabilities field.
+//   3. Non-TTY without --allow-mcp: prints --allow-mcp hint, resolves false,
+//      does NOT hang (rl.question is never called).
+// ---------------------------------------------------------------------------
+
+describe('US-010: install-time MCP trust prompt', () => {
+  let payloadDir: string;
+  let origIsTTY: boolean | undefined;
+
+  beforeEach(() => {
+    // Isolated tmpdir — never touches ~/.claude.json, ~/.mcp.json, or any real
+    // config. confirmMcp/renderMcpServerLine write NO config so this is the
+    // natural safety boundary; we just make sure the dir lives in os.tmpdir().
+    payloadDir = fs.mkdtempSync(path.join(os.tmpdir(), 'us010-'));
+    origIsTTY = process.stdin.isTTY;
+  });
+
+  afterEach(() => {
+    // Restore isTTY regardless of how the test exited.
+    Object.defineProperty(process.stdin, 'isTTY', {
+      value: origIsTTY,
+      configurable: true,
+    });
+    fs.rmSync(payloadDir, { recursive: true, force: true });
+  });
+
+  // ---- US-010 AC-1: URL disclosed, LITERAL secret never leaks ----------------
+  //
+  // The security requirement is that a LITERAL secret value in a header (e.g.
+  // a manifest that slipped past the shape-validator, or any future transport
+  // that carries the secret inline) is STILL redacted by renderMcpServerLine.
+  // We prove this by putting an unambiguous sentinel (`SENTINEL_SECRET_zzz123`)
+  // directly in the header value and asserting it is absent from the output,
+  // while the FULL url IS present.
+  //
+  // Two sub-assertions:
+  //   (a) renderMcpServerLine — pure render assertion without a prompt.
+  //   (b) confirmMcp (stdout capture) — full-prompt assertion; confirms the
+  //       "declares N MCP server(s)" header + url appear, sentinel does not.
+  it(
+    'AC-1: http manifest — FULL url appears, LITERAL sentinel secret is redacted',
+    async () => {
+      // Write the http manifest with a LITERAL sentinel (not a ${secret:} ref)
+      // so the redaction-self-test is airtight: if redactSecrets had a bug the
+      // sentinel would appear verbatim in the output.
+      fs.mkdirSync(path.join(payloadDir, 'mcp'), { recursive: true });
+      fs.writeFileSync(
+        path.join(payloadDir, 'mcp', 'vyg-shopify.json'),
+        JSON.stringify({
+          type: 'http',
+          url: 'https://mcp.vyg.app',
+          headers: { Authorization: 'Bearer SENTINEL_SECRET_zzz123' },
+        }),
+      );
+
+      // (a) Pure render assertion — renderMcpServerLine directly.
+      const line = renderMcpServerLine(payloadDir, 'vyg-shopify');
+
+      // Full url MUST appear (typosquat disclosure is the whole point).
+      expect(line).toContain('https://mcp.vyg.app');
+      expect(line).toContain('[http]');
+      // The header KEY must appear so the operator knows what was registered.
+      expect(line).toContain('Authorization');
+      // LITERAL sentinel value MUST NOT appear — this is the redaction self-test.
+      expect(line).not.toContain('SENTINEL_SECRET_zzz123');
+      // The Bearer prefix itself should not appear either.
+      expect(line).not.toContain('Bearer SENTINEL');
+      // The known redaction marker should replace it.
+      expect(line).toContain('«redacted»');
+
+      // (b) Full-prompt assertion — confirmMcp with isTTY=false (no-hang path).
+      // We use non-TTY so we get stdout without needing a readline mock.
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        const pkg = fakeManifest({
+          publisher: '@vyg',
+          contributes: { mcp: ['vyg-shopify'] },
+        });
+        const ok = await confirmMcp(pkg, payloadDir, false);
+        // Non-TTY deny.
+        expect(ok).toBe(false);
+        const out = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+        // URL is disclosed in the rendered server line.
+        expect(out).toContain('https://mcp.vyg.app');
+        // "declares N MCP server(s)" header must appear.
+        expect(out).toMatch(/declares 1 MCP server\(s\)/);
+        // Sentinel MUST NOT appear anywhere in output.
+        expect(out).not.toContain('SENTINEL_SECRET_zzz123');
+        expect(out).not.toContain('Bearer SENTINEL');
+        expect(out).not.toContain('Bearer ');
+      } finally {
+        logSpy.mockRestore();
+      }
+    },
+  );
+
+  // ---- US-010 AC-2: gate is on contributes.mcp, NOT capabilities ------------
+  //
+  // Positive: capabilities omits 'mcp' (or is empty) but contributes.mcp is
+  //   non-empty → prompt FIRES (server line / "declares N" header in output).
+  // Negative: capabilities includes 'mcp' but contributes.mcp is EMPTY → prompt
+  //   does NOT fire (confirmMcp returns true, console.log never called).
+  it(
+    'AC-2a (positive): prompt fires when contributes.mcp is set, regardless of capabilities',
+    async () => {
+      fs.mkdirSync(path.join(payloadDir, 'mcp'), { recursive: true });
+      fs.writeFileSync(
+        path.join(payloadDir, 'mcp', 'vyg-shopify.json'),
+        JSON.stringify({
+          type: 'http',
+          url: 'https://mcp.vyg.app',
+          headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+        }),
+      );
+      // capabilities is empty / does not include 'mcp' — gating MUST NOT rely on it.
+      const pkg = fakeManifest({
+        publisher: '@vyg',
+        capabilities: [],
+        contributes: { mcp: ['vyg-shopify'] },
+      });
+      // Non-TTY so we get the prompt output synchronously without readline.
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        const ok = await confirmMcp(pkg, payloadDir, false);
+        // Non-TTY deny (prompt fired but was denied).
+        expect(ok).toBe(false);
+        const out = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+        // The prompt DID fire: the "declares N MCP server(s)" header appears.
+        expect(out).toMatch(/declares 1 MCP server\(s\)/);
+        // The server line appeared (url disclosed).
+        expect(out).toContain('https://mcp.vyg.app');
+      } finally {
+        logSpy.mockRestore();
+      }
+    },
+  );
+
+  it(
+    'AC-2b (negative): prompt does NOT fire when contributes.mcp is empty, even if capabilities includes "mcp"',
+    async () => {
+      // capabilities lists 'mcp' — but gating must be on contributes.mcp only.
+      const pkg = fakeManifest({
+        publisher: '@vyg',
+        capabilities: ['mcp', 'network'],
+        contributes: {},
+      });
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        const ok = await confirmMcp(pkg, payloadDir, false);
+        // Empty contributes.mcp → pass-through, no prompt, returns true.
+        expect(ok).toBe(true);
+        // console.log must NEVER have been called — no prompt output.
+        expect(logSpy).not.toHaveBeenCalled();
+      } finally {
+        logSpy.mockRestore();
+      }
+    },
+  );
+
+  // ---- US-010 AC-3: non-TTY shell — hint printed, returns false, no hang ----
+  //
+  // If confirmMcp called rl.question in a non-TTY context it would hang forever
+  // (the test would never resolve and vitest's per-test timeout would fire as a
+  // failure). The no-hang proof IS that the await resolves within the timeout.
+  // We then assert: returns false (deny), and stdout contains the --allow-mcp
+  // hint.
+  it(
+    'AC-3: non-TTY without --allow-mcp — resolves false, prints --allow-mcp hint, does NOT hang',
+    async () => {
+      fs.mkdirSync(path.join(payloadDir, 'mcp'), { recursive: true });
+      fs.writeFileSync(
+        path.join(payloadDir, 'mcp', 'vyg-shopify.json'),
+        JSON.stringify({
+          type: 'http',
+          url: 'https://mcp.vyg.app',
+          headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+        }),
+      );
+      const pkg = fakeManifest({
+        publisher: '@vyg',
+        contributes: { mcp: ['vyg-shopify'] },
+      });
+
+      Object.defineProperty(process.stdin, 'isTTY', {
+        value: false,
+        configurable: true,
+      });
+      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+      try {
+        // This MUST resolve (not hang). The implementation guards on
+        // `!process.stdin.isTTY` and returns false before ever calling
+        // rl.question. If that guard were missing, the question callback would
+        // never fire and this await would stall until vitest times out the test
+        // — which itself counts as a failure, proving the no-hang property.
+        const ok = await confirmMcp(pkg, payloadDir, false);
+
+        // Returns false in non-TTY (deny without partial state).
+        expect(ok).toBe(false);
+
+        // The --allow-mcp hint must appear in stdout.
+        const out = logSpy.mock.calls.map((c) => String(c[0])).join('\n');
+        expect(out).toMatch(/--allow-mcp/);
+      } finally {
+        logSpy.mockRestore();
+      }
+    },
+  );
+});
+
 // ---------------------------------------------------------------------------
 // GET /v1/listings/{id} detail-envelope mapping (Bug 1: contract/envelope)
 // ---------------------------------------------------------------------------
@@ -730,3 +1320,146 @@ describe('pack-install: fetchMarketplace honors the envelope-mapped contentHash'
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// requires.packs — pack-to-pack dependencies (M0)
+// ---------------------------------------------------------------------------
+
+describe('requires.packs validation (M0)', () => {
+  // Mirrors the author/capabilities helper: a minimal otherwise-valid payload
+  // whose only variable is the `requires.packs` block under test.
+  function writePackWithRequires(extraYaml: string): string {
+    const dir = mkFakePackPayload({ 'knowledge/demo/README.md': '# demo' });
+    fs.writeFileSync(
+      path.join(dir, 'package.yaml'),
+      [
+        'name: hq-pack-accounting',
+        'version: 1.0.0',
+        "publisher: '@indigoai-us'",
+        'access: public',
+        'requires:',
+        "  hqCore: '>=15.1.0'",
+        extraYaml,
+        'contributes:',
+        '  knowledge:',
+        '    - demo',
+        '',
+      ].join('\n'),
+    );
+    return dir;
+  }
+
+  it('a manifest WITHOUT requires.packs validates (backwards-compatible)', () => {
+    const dir = writePackWithRequires('');
+    const m = validateManifest(dir, '15.1.0');
+    expect(m.requires.packs).toBeUndefined();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('a well-formed requires.packs (with and without version) is accepted', () => {
+    const dir = writePackWithRequires(
+      [
+        '  packs:',
+        '    - name: hq-pack-crm',
+        "      version: '>=1.0.0'",
+        '    - name: hq-pack-other',
+      ].join('\n'),
+    );
+    const m = validateManifest(dir, '15.1.0');
+    expect(m.requires.packs).toEqual([
+      { name: 'hq-pack-crm', version: '>=1.0.0' },
+      { name: 'hq-pack-other' },
+    ]);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects requires.packs that is not a list', () => {
+    const dir = writePackWithRequires('  packs: hq-pack-crm');
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/requires\.packs must be a list/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an entry with an invalid pack name', () => {
+    const dir = writePackWithRequires(['  packs:', '    - name: not-an-hq-pack'].join('\n'));
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/requires\.packs\[\]\.name/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('rejects an entry with an invalid version range', () => {
+    const dir = writePackWithRequires(
+      ['  packs:', '    - name: hq-pack-crm', '      version: not-a-range'].join('\n'),
+    );
+    expect(() => validateManifest(dir, '15.1.0')).toThrow(/invalid version range/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe('assertPackDependencies (M0)', () => {
+  let hqRoot: string;
+  beforeEach(() => {
+    hqRoot = mkFakeHq();
+  });
+  afterEach(() => {
+    fs.rmSync(hqRoot, { recursive: true, force: true });
+  });
+
+  // Seed an installed pack by writing core/packages/<name>/package.yaml — the
+  // filesystem-presence source of truth listInstalledPacks reads (NOT modules.yaml).
+  function seedInstalledPack(name: string, version?: string): void {
+    const dir = path.join(hqRoot, 'core', 'packages', name);
+    fs.mkdirSync(dir, { recursive: true });
+    const lines = [`name: ${name}`];
+    if (version) lines.push(`version: ${version}`);
+    fs.writeFileSync(path.join(dir, 'package.yaml'), lines.join('\n') + '\n');
+  }
+
+  it('is a no-op when the pack declares no requires.packs', () => {
+    const pkg = fakeManifest({ requires: { hqCore: '>=15.1.0' } });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('passes when every required pack is installed (no version constraint)', () => {
+    seedInstalledPack('hq-pack-crm', '1.2.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('throws a clear, actionable error when a required pack is missing', () => {
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(
+      /requires hq-pack-crm, which is not installed/,
+    );
+  });
+
+  it('passes when the installed version satisfies the required range', () => {
+    seedInstalledPack('hq-pack-crm', '1.2.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm', version: '>=1.0.0' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).not.toThrow();
+  });
+
+  it('throws when the installed version does NOT satisfy the required range', () => {
+    seedInstalledPack('hq-pack-crm', '0.9.0');
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-crm', version: '>=1.0.0' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(/requires hq-pack-crm >=1\.0\.0/);
+  });
+
+  it('rejects a pack that lists itself as a dependency', () => {
+    const pkg = fakeManifest({
+      name: 'hq-pack-accounting',
+      requires: { hqCore: '>=15.1.0', packs: [{ name: 'hq-pack-accounting' }] },
+    });
+    expect(() => assertPackDependencies(hqRoot, pkg)).toThrow(/cannot list itself/);
+  });
+});