@indigoai-us/hq-cli 5.15.0 → 5.17.0-sources-rc.0

package/test/helpers/cli-runner.ts

@@ -0,0 +1,150 @@
+/**
+ * cli-runner.ts — in-process Commander test harness.
+ *
+ * Builds a minimal Commander program and runs it with the given argv,
+ * capturing stdout/stderr without forking a child process.
+ *
+ * The program starts with only the core hq metadata (name, description,
+ * version). As new top-level command registrars are added to the CLI
+ * (US-006: sources, US-007: signals, etc.), import and register them here
+ * so tests that need the full command tree can use the same runner.
+ *
+ * NOTE: Some existing commands (pkg-install, pack-install) use semver deep
+ * subpath imports (semver/functions/satisfies.js) that are not resolvable in
+ * the pnpm test context. Those commands are excluded from the test program;
+ * add them here only if/when the semver resolution is fixed in devDeps.
+ *
+ * Usage:
+ *   const { exitCode, stdout, stderr } = await runCli(['hq', '--help']);
+ */
+
+import { Command } from "commander";
+import { registerLoginCommand } from "../../src/commands/login.js";
+import { registerLogoutCommand } from "../../src/commands/logout.js";
+import { registerWhoamiCommand } from "../../src/commands/whoami.js";
+import { registerSecretsCommand } from "../../src/commands/secrets.js";
+import { registerGroupsCommand } from "../../src/commands/groups.js";
+import { registerSourcesCommand } from "../../src/commands/sources.js";
+import { registerSignalsCommand } from "../../src/commands/signals.js";
+
+export interface CliRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Builds a test-only Commander program using exitOverride() so Commander
+ * throws CommanderError instead of calling process.exit().
+ */
+function buildProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("hq")
+    .description("HQ management CLI — modules, packages, and cloud sync")
+    .version("0.0.0-test")
+    .exitOverride();
+
+  // Auth commands (no semver deep imports)
+  registerLoginCommand(program);
+  registerLogoutCommand(program);
+  registerWhoamiCommand(program);
+
+  // Secrets / groups (no semver deep imports)
+  registerSecretsCommand(program);
+  registerGroupsCommand(program);
+
+  // Sources read surface (US-006)
+  registerSourcesCommand(program);
+
+  // Signals read surface (US-007)
+  registerSignalsCommand(program);
+
+  return program;
+}
+
+/**
+ * Runs the hq CLI in-process with the given argv.
+ *
+ * stdout/stderr are intercepted for the duration of the call and restored
+ * afterward. Not safe to call concurrently (share process streams).
+ */
+export async function runCli(argv: string[]): Promise<CliRunResult> {
+  const stdoutChunks: string[] = [];
+  const stderrChunks: string[] = [];
+  let exitCode = 0;
+
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  const origStderrWrite = process.stderr.write.bind(process.stderr);
+  const origExit = process.exit.bind(process);
+
+  const captureWrite =
+    (chunks: string[]) =>
+    (
+      chunk: string | Uint8Array,
+      encodingOrCb?: unknown,
+      cb?: unknown,
+    ): boolean => {
+      chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"));
+      if (typeof encodingOrCb === "function") (encodingOrCb as () => void)();
+      else if (typeof cb === "function") (cb as () => void)();
+      return true;
+    };
+
+  (process.stdout as { write: unknown }).write = captureWrite(stdoutChunks);
+  (process.stderr as { write: unknown }).write = captureWrite(stderrChunks);
+
+  // Stub process.exit so action-handler exit(code) becomes a thrown error
+  // caught by parseAsync(). Otherwise it would tear down the vitest worker.
+  class ProcessExitError extends Error {
+    code: number;
+    constructor(code: number) {
+      super(`process.exit(${code})`);
+      this.name = "ProcessExitError";
+      this.code = code;
+    }
+  }
+  (process as { exit: unknown }).exit = ((code?: number) => {
+    throw new ProcessExitError(code ?? 0);
+  }) as typeof process.exit;
+
+  try {
+    const program = buildProgram();
+    // Commander's default strips 2 elements (node + script).
+    // Our argv convention is ['hq', ...userArgs], so strip the program name
+    // and use { from: 'user' } so Commander treats the rest as user args.
+    const userArgs = argv[0] === "hq" ? argv.slice(1) : argv;
+    await program.parseAsync(userArgs, { from: "user" });
+    exitCode = 0;
+  } catch (err: unknown) {
+    if (err instanceof ProcessExitError) {
+      // hq command threw via stubbed process.exit (withErrorHandling pattern).
+      // stderr was already written by the action handler.
+      exitCode = err.code;
+    } else if (err && typeof err === "object" && "code" in err) {
+      // Commander error from exitOverride()
+      const ce = err as { code: string; exitCode?: number };
+      if (ce.code === "commander.helpDisplayed" || ce.code === "commander.version") {
+        exitCode = 0;
+      } else {
+        exitCode = ce.exitCode ?? 1;
+      }
+    } else if (err instanceof Error) {
+      stderrChunks.push(err.message + "\n");
+      exitCode = 1;
+    } else {
+      exitCode = 1;
+    }
+  } finally {
+    process.stdout.write = origStdoutWrite;
+    process.stderr.write = origStderrWrite;
+    (process as { exit: unknown }).exit = origExit;
+  }
+
+  return {
+    exitCode,
+    stdout: stdoutChunks.join(""),
+    stderr: stderrChunks.join(""),
+  };
+}

package/test/helpers/s3-list-mock.ts

@@ -0,0 +1,79 @@
+/**
+ * s3-list-mock.ts — in-memory stub for @aws-sdk/client-s3 S3Client.
+ *
+ * Used by sources/signals tests that need ListObjectsV2 and GetObject behaviour
+ * without real AWS credentials or network I/O.
+ */
+
+import type { S3Client } from "@aws-sdk/client-s3";
+// NOTE: We intentionally do NOT use `instanceof ListObjectsV2Command` for
+// dispatch. When this stub is consumed by code in a sibling package
+// (@indigoai-us/hq-cloud's compiled dist), that code's @aws-sdk/client-s3
+// resolution can produce a distinct constructor instance from the one we
+// import here, breaking instanceof. Dispatching on `command.constructor.name`
+// is identity-free and works across package boundaries.
+
+export interface MockEntry {
+  /** S3 object key (e.g. "sources/meetings/abc.md") */
+  key: string;
+  /** Full file content as UTF-8 string */
+  content: string;
+  /** Optional override; defaults to 2026-01-01T00:00:00Z */
+  lastModified?: Date;
+}
+
+export interface MockS3Options {
+  entries: MockEntry[];
+}
+
+/**
+ * Returns a stub S3Client whose `send` method handles:
+ *   - ListObjectsV2Command — filters entries by Prefix, no pagination
+ *   - GetObjectCommand     — returns a streaming Body for the matching entry
+ *
+ * Throws `NoSuchKey` (matching AWS SDK error shape) for GetObject misses.
+ */
+export function mockS3WithEntries(opts: MockS3Options): S3Client {
+  const { entries } = opts;
+  const defaultDate = new Date("2026-01-01T00:00:00Z");
+
+  async function send(command: unknown): Promise<unknown> {
+    const cmdName = (command as { constructor?: { name?: string } }).constructor?.name ?? "";
+
+    if (cmdName === "ListObjectsV2Command") {
+      const { Prefix } = (command as { input: { Bucket: string; Prefix?: string } }).input;
+      const prefix = Prefix ?? "";
+      const filtered = entries.filter((e) => e.key.startsWith(prefix));
+      return {
+        Contents: filtered.map((e) => ({
+          Key: e.key,
+          Size: Buffer.byteLength(e.content, "utf-8"),
+          LastModified: e.lastModified ?? defaultDate,
+          ETag: `"mock-etag"`,
+        })),
+        IsTruncated: false,
+        NextContinuationToken: undefined,
+        $metadata: {},
+      };
+    }
+
+    if (cmdName === "GetObjectCommand") {
+      const { Key } = (command as { input: { Bucket: string; Key: string } }).input;
+      const entry = entries.find((e) => e.key === Key);
+      if (!entry) {
+        const err = new Error(`The specified key does not exist: ${Key}`);
+        (err as NodeJS.ErrnoException).name = "NoSuchKey";
+        throw err;
+      }
+      const content = entry.content;
+      async function* bodyStream(): AsyncIterable<Uint8Array> {
+        yield Buffer.from(content, "utf-8");
+      }
+      return { Body: bodyStream(), $metadata: {} };
+    }
+
+    throw new Error(`mockS3WithEntries: unhandled command type "${cmdName || "unknown"}"`);
+  }
+
+  return { send } as unknown as S3Client;
+}

package/test/helpers/vault-service-mock.ts

@@ -0,0 +1,160 @@
+/**
+ * vault-service-mock.ts — fetch stub for vault-service HTTP endpoints.
+ *
+ * Intercepts globalThis.fetch and handles the subset of vault-service routes
+ * needed by entity-resolver and STS tests. Returns the original fetch restore
+ * function so callers can clean up in afterEach/finally.
+ *
+ * Handled endpoints (URL path suffixes):
+ *   GET  .../membership/me                  returns { memberships: [...] }
+ *   GET  .../entity/by-slug/{type}/{slug}   returns { entity: {...} }
+ *   POST .../entities/{uid}/sts             returns { credentials, expiresAt, bucketName, region }
+ */
+
+import type { Membership, EntityInfo } from "@indigoai-us/hq-cloud";
+
+export interface MockEntity {
+  /** Entity UID (e.g. "cmp_indigo_001") */
+  uid: string;
+  /** Human-readable stable slug (e.g. "indigo", "personal") */
+  slug: string;
+  /** S3 bucket name for this entity */
+  bucketName: string;
+  /** AWS region; defaults to "us-east-1" */
+  region?: string;
+  /** Entity role in this membership; defaults to "owner" */
+  role?: "owner" | "admin" | "member" | "guest";
+}
+
+export interface MockStsCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken: string;
+}
+
+export interface MockVaultOptions {
+  entities: MockEntity[];
+  /** STS credentials returned for every POST /entities/{uid}/sts; defaults to test creds */
+  stsCredentials?: MockStsCredentials;
+}
+
+const DEFAULT_STS: MockStsCredentials = {
+  accessKeyId: "ASIAMOCK000000000001",
+  secretAccessKey: "mockSecretAccessKey",
+  sessionToken: "mockSessionToken",
+};
+
+/**
+ * Installs a fetch stub for vault-service endpoints.
+ *
+ * @returns A restore function — call it in afterEach to un-install the stub.
+ */
+export function mockVaultService(opts: MockVaultOptions): () => void {
+  const { entities, stsCredentials = DEFAULT_STS } = opts;
+  const originalFetch = globalThis.fetch as typeof fetch | undefined;
+
+  globalThis.fetch = async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : (input as Request).url;
+    const method =
+      (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+
+    // GET /membership/me
+    if (method === "GET" && /\/membership\/me(\?.*)?$/.test(url)) {
+      const memberships: Partial<Membership>[] = entities.map((e) => ({
+        membershipKey: `mbr_${e.uid}`,
+        personUid: "prs_test_person_001",
+        companyUid: e.uid,
+        role: e.role ?? "owner",
+        status: "active",
+        invitedBy: "system",
+        invitedAt: "2026-01-01T00:00:00Z",
+        createdAt: "2026-01-01T00:00:00Z",
+        updatedAt: "2026-01-01T00:00:00Z",
+      }));
+      return json({ memberships });
+    }
+
+    // GET /entity/by-slug/{type}/{slug}
+    const bySlugMatch = /\/entity\/by-slug\/[^/]+\/([^/?]+)/.exec(url);
+    if (method === "GET" && bySlugMatch) {
+      const slug = decodeURIComponent(bySlugMatch[1]);
+      const entity = entities.find((e) => e.slug === slug);
+      if (!entity) {
+        return json({ error: "Not found" }, 404);
+      }
+      const info: Partial<EntityInfo> = {
+        uid: entity.uid,
+        slug: entity.slug,
+        type: "company",
+        name: entity.slug,
+        bucketName: entity.bucketName,
+        status: "active",
+      };
+      return json({ entity: info });
+    }
+
+    // GET /entity/{uid} (direct UID lookup — used by entity-resolver)
+    const entityUidMatch = /\/entity\/([^/?]+)$/.exec(url);
+    if (method === "GET" && entityUidMatch) {
+      const uid = decodeURIComponent(entityUidMatch[1]);
+      const entity = entities.find((e) => e.uid === uid);
+      if (!entity) {
+        return json({ error: `Entity '${uid}' not found` }, 404);
+      }
+      const info: Partial<EntityInfo> = {
+        uid: entity.uid,
+        slug: entity.slug,
+        type: "company",
+        name: entity.slug,
+        bucketName: entity.bucketName,
+        status: "active",
+      };
+      return json({ entity: info });
+    }
+
+    // POST /entities/{uid}/sts
+    const entityStsMatch = /\/entities\/([^/]+)\/sts/.exec(url);
+    if (method === "POST" && entityStsMatch) {
+      const uid = decodeURIComponent(entityStsMatch[1]);
+      const entity = entities.find((e) => e.uid === uid);
+      if (!entity) {
+        return json({ error: `Entity '${uid}' not found` }, 404);
+      }
+      return json({
+        credentials: stsCredentials,
+        expiresAt: new Date(Date.now() + 3600 * 1000).toISOString(),
+        bucketName: entity.bucketName,
+        region: entity.region ?? "us-east-1",
+      });
+    }
+
+    // Unhandled — pass through if original fetch exists, else 500
+    if (originalFetch) {
+      return originalFetch(input, init);
+    }
+    return json({ error: `mockVaultService: unhandled request ${method} ${url}` }, 500);
+  };
+
+  return () => {
+    if (originalFetch) {
+      globalThis.fetch = originalFetch;
+    } else {
+      delete (globalThis as Record<string, unknown>).fetch;
+    }
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}

package/test/sources-signals/smoke.test.ts

@@ -0,0 +1,226 @@
+/**
+ * smoke.test.ts — Phase 0 infrastructure smoke test (US-001).
+ *
+ * Validates that:
+ *   1. The fixture files exist and have the expected frontmatter shape.
+ *   2. mockS3WithEntries lists and retrieves entries with full round-trip fidelity.
+ *   3. mockVaultService intercepts /membership/me and /entities/{uid}/sts correctly.
+ *   4. runCli(['hq', '--help']) exits 0 (basic wiring check).
+ *
+ * Note: assertions about 'sources'/'signals' appearing in `hq --help` are
+ * intentionally absent here — those land when US-006/US-007 register the
+ * commands and add them to buildProgram() in cli-runner.ts.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { afterEach, describe, expect, it } from "vitest";
+import { GetObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";
+import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
+import { mockVaultService } from "../helpers/vault-service-mock.js";
+import { runCli } from "../helpers/cli-runner.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const FIXTURES = join(__dirname, "../fixtures");
+const SOURCE_PATH = join(FIXTURES, "sources/meetings/sample.md");
+const SIGNAL_ACTION_PATH = join(FIXTURES, "signals/action_item/sample.md");
+const SIGNAL_SUMMARY_PATH = join(FIXTURES, "signals/summary/sample.md");
+
+// ---------------------------------------------------------------------------
+// Fixture shape tests
+// ---------------------------------------------------------------------------
+
+describe("fixtures — file shape", () => {
+  it("source fixture has expected frontmatter fields", () => {
+    const content = readFileSync(SOURCE_PATH, "utf-8");
+    expect(content).toContain("source_id:");
+    expect(content).toContain("channel: meeting");
+    expect(content).toContain("participants:");
+    expect(content).toContain("created_at:");
+  });
+
+  it("action_item signal fixture has required signal fields", () => {
+    const content = readFileSync(SIGNAL_ACTION_PATH, "utf-8");
+    expect(content).toContain("signal_id:");
+    expect(content).toContain("signal_type: action_item");
+    expect(content).toContain("source_ref:");
+    expect(content).toContain("citations:");
+    expect(content).toContain("entity_refs:");
+  });
+
+  it("summary signal fixture has required signal fields", () => {
+    const content = readFileSync(SIGNAL_SUMMARY_PATH, "utf-8");
+    expect(content).toContain("signal_type: summary");
+    expect(content).toContain("source_ref:");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// S3 mock round-trip tests
+// ---------------------------------------------------------------------------
+
+describe("mockS3WithEntries — listing", () => {
+  it("lists all entries when no prefix filter is applied", async () => {
+    const sourceContent = readFileSync(SOURCE_PATH, "utf-8");
+    const signalContent = readFileSync(SIGNAL_ACTION_PATH, "utf-8");
+
+    const client = mockS3WithEntries({
+      entries: [
+        { key: "sources/meetings/abc.md", content: sourceContent },
+        { key: "signals/action_item/xyz.md", content: signalContent },
+      ],
+    });
+
+    const result = await client.send(
+      new ListObjectsV2Command({ Bucket: "mock-bucket" }),
+    ) as { Contents: Array<{ Key: string; Size: number }> };
+
+    expect(result.Contents).toHaveLength(2);
+    const keys = result.Contents.map((c) => c.Key);
+    expect(keys).toContain("sources/meetings/abc.md");
+    expect(keys).toContain("signals/action_item/xyz.md");
+  });
+
+  it("filters by prefix — returns only matching entries", async () => {
+    const sourceContent = readFileSync(SOURCE_PATH, "utf-8");
+    const signalContent = readFileSync(SIGNAL_ACTION_PATH, "utf-8");
+
+    const client = mockS3WithEntries({
+      entries: [
+        { key: "sources/meetings/abc.md", content: sourceContent },
+        { key: "signals/action_item/xyz.md", content: signalContent },
+      ],
+    });
+
+    const sourceList = await client.send(
+      new ListObjectsV2Command({ Bucket: "mock-bucket", Prefix: "sources/meetings/" }),
+    ) as { Contents: Array<{ Key: string }> };
+
+    expect(sourceList.Contents).toHaveLength(1);
+    expect(sourceList.Contents[0].Key).toBe("sources/meetings/abc.md");
+
+    const signalList = await client.send(
+      new ListObjectsV2Command({ Bucket: "mock-bucket", Prefix: "signals/action_item/" }),
+    ) as { Contents: Array<{ Key: string }> };
+
+    expect(signalList.Contents).toHaveLength(1);
+    expect(signalList.Contents[0].Key).toBe("signals/action_item/xyz.md");
+  });
+});
+
+describe("mockS3WithEntries — get round-trip", () => {
+  it("retrieves source content and preserves exact bytes", async () => {
+    const sourceContent = readFileSync(SOURCE_PATH, "utf-8");
+
+    const client = mockS3WithEntries({
+      entries: [{ key: "sources/meetings/abc.md", content: sourceContent }],
+    });
+
+    const result = await client.send(
+      new GetObjectCommand({ Bucket: "mock-bucket", Key: "sources/meetings/abc.md" }),
+    ) as { Body: AsyncIterable<Uint8Array> };
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of result.Body) {
+      chunks.push(Buffer.from(chunk));
+    }
+    const retrieved = Buffer.concat(chunks).toString("utf-8");
+
+    expect(retrieved).toBe(sourceContent);
+    // Spot-check frontmatter field survives round-trip
+    expect(retrieved).toContain("source_id: abc-meeting-001");
+  });
+
+  it("retrieves signal content and preserves exact bytes", async () => {
+    const signalContent = readFileSync(SIGNAL_ACTION_PATH, "utf-8");
+
+    const client = mockS3WithEntries({
+      entries: [{ key: "signals/action_item/xyz.md", content: signalContent }],
+    });
+
+    const result = await client.send(
+      new GetObjectCommand({ Bucket: "mock-bucket", Key: "signals/action_item/xyz.md" }),
+    ) as { Body: AsyncIterable<Uint8Array> };
+
+    const chunks: Buffer[] = [];
+    for await (const chunk of result.Body) {
+      chunks.push(Buffer.from(chunk));
+    }
+    const retrieved = Buffer.concat(chunks).toString("utf-8");
+
+    expect(retrieved).toBe(signalContent);
+    expect(retrieved).toContain("signal_type: action_item");
+  });
+
+  it("throws NoSuchKey for missing entry", async () => {
+    const client = mockS3WithEntries({ entries: [] });
+
+    await expect(
+      client.send(new GetObjectCommand({ Bucket: "mock-bucket", Key: "does/not/exist.md" })),
+    ).rejects.toMatchObject({ name: "NoSuchKey" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Vault-service mock tests
+// ---------------------------------------------------------------------------
+
+describe("mockVaultService — membership endpoint", () => {
+  let restore: (() => void) | undefined;
+
+  afterEach(() => {
+    restore?.();
+    restore = undefined;
+  });
+
+  it("GET /membership/me returns memberships for all configured entities", async () => {
+    restore = mockVaultService({
+      entities: [
+        { uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" },
+        { uid: "prs_personal_001", slug: "personal", bucketName: "hq-personal-bucket" },
+      ],
+    });
+
+    const res = await fetch("https://vault-api.example.com/membership/me");
+    const body = (await res.json()) as { memberships: Array<{ companyUid: string }> };
+
+    expect(res.status).toBe(200);
+    expect(body.memberships).toHaveLength(2);
+    const uids = body.memberships.map((m) => m.companyUid);
+    expect(uids).toContain("cmp_indigo_001");
+    expect(uids).toContain("prs_personal_001");
+  });
+
+  it("POST /entities/{uid}/sts returns credentials", async () => {
+    restore = mockVaultService({
+      entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+    });
+
+    const res = await fetch("https://vault-api.example.com/entities/cmp_indigo_001/sts", {
+      method: "POST",
+    });
+    const body = (await res.json()) as {
+      credentials: { accessKeyId: string };
+      bucketName: string;
+    };
+
+    expect(res.status).toBe(200);
+    expect(body.credentials.accessKeyId).toBe("ASIAMOCK000000000001");
+    expect(body.bucketName).toBe("hq-indigo-bucket");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CLI runner
+// ---------------------------------------------------------------------------
+
+describe("runCli — basic wiring", () => {
+  it("runCli(['hq', '--help']) exits 0 and emits non-empty stdout", async () => {
+    const result = await runCli(["hq", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.length).toBeGreaterThan(0);
+    expect(result.stdout).toContain("hq");
+  });
+});

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: [
+      "src/**/*.test.ts",
+      "test/sources-signals/**/*.test.ts",
+      "test/commands/**/*.test.ts",
+    ],
+  },
+});