@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/commands/mcp-status.us011.test.ts

@@ -0,0 +1,243 @@
+/**
+ * PRD acceptance tests for US-011 — "hq mcp status + append-only audit log".
+ *
+ * These are E2E acceptance tests (from the PRD ACs), not unit tests. They
+ * exercise real module behaviour end-to-end without mocking the implementation.
+ *
+ * TEST SAFETY (hard requirement): EVERY test injects `env: { home }` = a fresh
+ * tmpdir (realpathSync'd so macOS /tmp -> /private/tmp does not break path
+ * equality) and cleans it in afterEach. NOTHING here reads or writes the
+ * developer's real ~/.claude.json, ~/.mcp.json, ~/.codex, or ~/.hq.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { computeMcpStatus } from './mcp-status.js';
+import {
+  registerServer,
+  unregisterServer,
+  mcpRegistryLogPath,
+  type McpManifest,
+  type SafeWriteEnv,
+  type AuditLogEntry,
+} from './mcp-registration.js';
+
+// ---------------------------------------------------------------------------
+// The sentinel resolved secret — it must NEVER appear in the audit log or any
+// output surface. Distinctive enough to grep unambiguously.
+// ---------------------------------------------------------------------------
+const SENTINEL_SECRET = 'SUPER_SECRET_BEARER_VALUE_do_not_log_123';
+
+// A manifest whose header carries a ${secret:} ref so the resolver is exercised.
+const HTTP_MANIFEST_WITH_SECRET: McpManifest = {
+  type: 'http',
+  url: 'https://mcp.example.com/vyg-api',
+  headers: { Authorization: 'Bearer ${secret:VYG_API_KEY}' },
+};
+
+// ---------------------------------------------------------------------------
+// Isolated-home sandbox (one per test — no shared state).
+// ---------------------------------------------------------------------------
+
+let home: string;
+let env: SafeWriteEnv;
+
+function mkFakeHome(): string {
+  // realpathSync so macOS /tmp -> /private/tmp doesn't break path equality.
+  return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'hq-us011-test-')));
+}
+
+afterEach(() => {
+  // Clean up the tmpdir after every test. Nothing touches the real ~/.
+  fs.rmSync(home, { recursive: true, force: true });
+});
+
+// Helper to set up a fresh sandbox before each individual test.
+function setupSandbox(): void {
+  home = mkFakeHome();
+  env = { home };
+}
+
+// ---------------------------------------------------------------------------
+// Audit-log helpers (self-contained so this file reads on its own).
+// ---------------------------------------------------------------------------
+
+/** Read every JSONL line from the audit log under env.home, or [] when absent. */
+function readAuditLines(): AuditLogEntry[] {
+  const p = mcpRegistryLogPath(env);
+  if (!fs.existsSync(p)) return [];
+  return fs
+    .readFileSync(p, 'utf-8')
+    .split('\n')
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l) as AuditLogEntry);
+}
+
+/** Raw audit-log file text (for sentinel grepping). */
+function rawAuditText(): string {
+  const p = mcpRegistryLogPath(env);
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : '';
+}
+
+// ===========================================================================
+// US-011 PRD acceptance test 1:
+//   "Given a pack registered in Claude but NOT Codex (PARTIAL), when
+//    `hq mcp status` runs, then it reports the server as PARTIAL with the
+//    MISSING RUNTIME NAMED."
+//
+//   Setup: register into a sandbox home that has NO ~/.codex (Codex is not
+//   installed → Claude-only → PARTIAL). Then call computeMcpStatus(env) and
+//   assert the server's partial === true AND that the partial-reason field
+//   mentions "Codex" (case-insensitively), AND that Claude shows present while
+//   Codex shows not-installed/absent.
+// ===========================================================================
+
+describe('US-011: PRD acceptance test 1 — PARTIAL status with missing runtime named', () => {
+  it(
+    'Given a pack registered in Claude but NOT Codex (PARTIAL), ' +
+      'when hq mcp status runs, ' +
+      'then it reports the server as PARTIAL with the missing runtime (Codex) named',
+    () => {
+      setupSandbox();
+
+      // ARRANGE: register into a home with NO ~/.codex (Codex not installed).
+      // The absence of ~/.codex is the first-class signal — never created by the substrate.
+      registerServer({
+        name: 'vyg-shopify',
+        manifest: HTTP_MANIFEST_WITH_SECRET,
+        pack: 'hq-pack-vyg-shopify',
+        resolveSecret: () => SENTINEL_SECRET,
+        env,
+      });
+
+      // Confirm ~/.codex was NOT fabricated by the register operation.
+      expect(fs.existsSync(path.join(home, '.codex'))).toBe(false);
+
+      // ACT: run the status computation (the pure, testable core of `hq mcp status`).
+      const report = computeMcpStatus(env);
+
+      // ASSERT: exactly one server in the report.
+      expect(report.servers).toHaveLength(1);
+      const s = report.servers[0]!;
+
+      // Server identity.
+      expect(s.server).toBe('vyg-shopify');
+      expect(s.pack).toBe('hq-pack-vyg-shopify');
+      expect(s.transport).toBe('http');
+
+      // Claude surface: present.
+      expect(s.claude.presence).toBe('present');
+
+      // Codex surface: not-installed (the runtime itself is missing, not just the server).
+      expect(s.codex.presence).toBe('not-installed');
+
+      // PARTIAL flag: must be true — registered in EXACTLY ONE runtime.
+      expect(s.partial).toBe(true);
+
+      // partialReason must name the missing runtime (Codex), case-insensitively.
+      expect(s.partialReason).toBeDefined();
+      expect(s.partialReason!.toLowerCase()).toContain('codex');
+
+      // Not drifted (only one runtime has data).
+      expect(s.drifted).toBe(false);
+
+      // Runtime-level flags agree.
+      expect(report.runtimes.claude.installed).toBe(true);
+      expect(report.runtimes.claude.parses).toBe(true);
+      expect(report.runtimes.codex.installed).toBe(false);
+    },
+  );
+});
+
+// ===========================================================================
+// US-011 PRD acceptance test 2:
+//   "Given an install then uninstall, when the audit log is read, then BOTH
+//    actions appear with hashes and NO secret value."
+//
+//   Setup: a manifest whose header carries a ${secret:} ref resolved to
+//   SENTINEL_SECRET. Register (install) then unregister (uninstall) the server
+//   into a sandbox home. Read the audit log at mcpRegistryLogPath(env).
+//
+//   Assertions:
+//   - At least one line with action:'register' AND at least one with action:'unregister'.
+//   - Each config-mutating line carries prevHash/newHash (sha256 hex strings).
+//   - For the register line the prevHash !== newHash (a real write happened).
+//   - CRITICALLY: the raw audit-log text NEVER contains the SENTINEL secret value.
+// ===========================================================================
+
+describe('US-011: PRD acceptance test 2 — audit log shows install+uninstall with hashes, no secret', () => {
+  it(
+    'Given an install then uninstall, ' +
+      'when the audit log is read, ' +
+      'then BOTH actions appear with hashes and NO secret value anywhere in the log',
+    () => {
+      setupSandbox();
+
+      const SHA256_RE = /^[0-9a-f]{64}$/;
+
+      // ARRANGE + ACT: register (install) then unregister (uninstall).
+      registerServer({
+        name: 'vyg-shopify',
+        manifest: HTTP_MANIFEST_WITH_SECRET,
+        pack: 'hq-pack-vyg-shopify',
+        resolveSecret: () => SENTINEL_SECRET,
+        env,
+      });
+
+      unregisterServer({
+        name: 'vyg-shopify',
+        pack: 'hq-pack-vyg-shopify',
+        env,
+      });
+
+      // Confirm the audit log is at the injected-env path (inside tmpdir, NOT in ~/.hq).
+      const logPath = mcpRegistryLogPath(env);
+      expect(logPath.startsWith(home)).toBe(true);
+      expect(fs.existsSync(logPath)).toBe(true);
+
+      const lines = readAuditLines();
+
+      // ASSERT: at least one 'register' line and at least one 'unregister' line.
+      const registerLines = lines.filter((l) => l.action === 'register');
+      const unregisterLines = lines.filter((l) => l.action === 'unregister');
+      expect(registerLines.length).toBeGreaterThanOrEqual(1);
+      expect(unregisterLines.length).toBeGreaterThanOrEqual(1);
+
+      // The register line that actually changed the Claude config (result:'registered').
+      const regLine = registerLines.find((l) => l.result === 'registered');
+      expect(regLine).toBeDefined();
+      expect(regLine!.server).toBe('vyg-shopify');
+      expect(regLine!.pack).toBe('hq-pack-vyg-shopify');
+
+      // prevHash and newHash must be sha256 hex strings on the config-mutating register line.
+      // prevHash should be '' (file absent before first write) OR a valid sha256.
+      // newHash must be a valid sha256 (file was written).
+      // Most importantly: prevHash !== newHash (the write changed the file).
+      expect(regLine!.newHash).toMatch(SHA256_RE);
+      expect(regLine!.prevHash).not.toBe(regLine!.newHash);
+
+      // The unregister line that actually changed the Claude config (result:'unregistered').
+      const unregLine = unregisterLines.find((l) => l.result === 'unregistered');
+      expect(unregLine).toBeDefined();
+      expect(unregLine!.server).toBe('vyg-shopify');
+      expect(unregLine!.pack).toBe('hq-pack-vyg-shopify');
+
+      // Unregister hashes: prevHash is the post-register sha256, newHash differs (entry removed).
+      expect(unregLine!.prevHash).toMatch(SHA256_RE);
+      expect(unregLine!.newHash).toMatch(SHA256_RE);
+      expect(unregLine!.prevHash).not.toBe(unregLine!.newHash);
+
+      // CRITICAL SAFETY CHECK: the raw audit-log text must NEVER contain the sentinel
+      // secret value ANYWHERE — grep the whole file as a string.
+      const rawText = rawAuditText();
+      expect(rawText.includes(SENTINEL_SECRET)).toBe(false);
+
+      // The URL (not a secret) may appear in the log — that's fine.
+      // The Bearer secret value (SENTINEL_SECRET) must NOT.
+      expect(rawText).toContain('https://mcp.example.com/vyg-api');
+      expect(rawText).not.toContain(SENTINEL_SECRET);
+    },
+  );
+});

package/src/commands/onboard-warning.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
+
+describe("buildCreateCompanyWarning", () => {
+  it("documents the warning shown on the create-company path", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("NEW company");
+    expect(warning).toMatch(/does NOT join an existing one/i);
+  });
+
+  it("advises existing-company users to ask an admin or owner for an invite", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/ask your admin or owner.*invite/i);
+  });
+
+  it("tells invitees to run hq sync after accepting", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toContain("accept it and run `hq sync`");
+  });
+
+  it("warns that duplicate creation leaves the user alone in a separate company", () => {
+    const warning = buildCreateCompanyWarning();
+    expect(warning).toMatch(/separate one you'd be alone in/i);
+  });
+});

package/src/commands/onboard-warning.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds the static create-time warning surfaced by both `create-company` and
+ * `dry-run`, because users may accidentally create duplicate companies instead
+ * of joining the existing company they were invited to.
+ */
+export function buildCreateCompanyWarning(): string {
+  return (
+    "  This creates a NEW company that you own — it does NOT join an existing one.\n" +
+    "  If your company already uses HQ, do NOT create it again: ask your admin or owner to send you an invite, then accept it and run `hq sync` to pull the existing company.\n" +
+    "  Creating a same-named company makes a separate one you'd be alone in.\n"
+  );
+}

package/src/commands/onboard.ts

@@ -32,6 +32,7 @@ import {
 import { createDefaultVaultClient } from "./cloud-provision.js";
 import { detectOnboardingIdentityMismatch } from "./onboard-identity-guard.js";
 import { planOnboardJoin } from "./onboard-join.js";
+import { buildCreateCompanyWarning } from "./onboard-warning.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -70,13 +71,7 @@ export function registerOnboardCommand(program: Command): void {
         console.log(`  Company:  ${options.name} (${options.slug})`);
         console.log(`  Person:   ${options.personName} <${options.email}>`);
         console.log(`  HQ root:  ${options.hqRoot}\n`);
-        console.log(
-          chalk.gray(
-            "  This creates a NEW company you own. Joining a teammate's existing\n" +
-              "  company? Stop — accept your invite, then run `hq sync` to pull it.\n" +
-              "  Creating a same-named company leaves you alone in a separate one.\n",
-          ),
-        );
+        console.log(chalk.gray(buildCreateCompanyWarning()));
 
         const accessToken = await ensureCognitoToken();
         const result = await runOnboardCli({
@@ -248,6 +243,8 @@ export function registerOnboardCommand(program: Command): void {
     )
     .action(async (options: { hqRoot: string }) => {
       try {
+        console.log(chalk.gray(buildCreateCompanyWarning()));
+
         // No auth needed for dry-run — runOnboardCli handles this branch
         // without touching the vault-service.
         const result = await runOnboardCli({