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

package/src/index.ts

@@ -30,6 +30,8 @@ import { registerFilesCommand } from "./commands/files.js";
 import { registerMembersCommand } from "./commands/members.js";
 import { registerFeedbackCommand } from "./commands/feedback.js";
 import { registerMeetingsCommand } from "./commands/meetings.js";
+import { registerSourcesCommand } from "./commands/sources.js";
+import { registerSignalsCommand } from "./commands/signals.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import {
   maybeWarnNewVersion,
@@ -134,6 +136,12 @@ registerFeedbackCommand(program);
 // Meetings (subcommand group — hq meetings list|get|search|transcript|notes)
 registerMeetingsCommand(program);
 
+// Sources read surface (subcommand group — hq sources list|get|channels|entities)
+registerSourcesCommand(program);
+
+// Signals read surface (subcommand group — hq signals list|get|types|entities)
+registerSignalsCommand(program);
+
 (async () => {
   try {
     Sentry.addBreadcrumb({

package/src/utils/cognito-session.test.ts

@@ -8,7 +8,12 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { resolveDefaultHqRoot } from "./cognito-session.js";
+import {
+  CLI_CLIENT_INFO,
+  buildVaultConfig,
+  resolveDefaultHqRoot,
+} from "./cognito-session.js";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 
 describe("resolveDefaultHqRoot", () => {
   let tmpRoot: string;
@@ -110,3 +115,21 @@ describe("resolveDefaultHqRoot", () => {
     expect(resolveDefaultHqRoot()).toBe(explicit);
   });
 });
+
+describe("CLI_CLIENT_INFO + buildVaultConfig", () => {
+  it("exposes the CLI's package name and version", () => {
+    expect(CLI_CLIENT_INFO.name).toBe(CLI_NAME);
+    expect(CLI_CLIENT_INFO.version).toBe(CLI_VERSION);
+    // Name should always be the @indigoai-us scoped slug — guard against accidental
+    // renames that would silently break server-side traffic attribution.
+    expect(CLI_NAME).toBe("@indigoai-us/hq-cli");
+    expect(CLI_VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("buildVaultConfig stamps clientInfo onto the returned config", () => {
+    const cfg = buildVaultConfig("dummy-token");
+    expect(cfg.clientInfo).toBe(CLI_CLIENT_INFO);
+    expect(cfg.clientInfo?.name).toBe("@indigoai-us/hq-cli");
+    expect(cfg.clientInfo?.version).toBe(CLI_VERSION);
+  });
+});

package/src/utils/cognito-session.ts

@@ -28,9 +28,12 @@ import {
   isExpiring,
   refreshTokens,
   browserLogin,
+  detectHqCoreVersion,
   type CognitoAuthConfig,
+  type ClientInfo,
   type VaultServiceConfig,
 } from "@indigoai-us/hq-cloud";
+import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 
 export const DEFAULT_COGNITO: CognitoAuthConfig = {
   region: process.env.AWS_REGION ?? "us-east-1",
@@ -146,12 +149,27 @@ export async function ensureCognitoToken(options: {
   return tokens.accessToken;
 }
 
+/**
+ * The CLI's own ClientInfo. Resolved once at module load so every VaultClient
+ * built in this process stamps the same name/version onto its requests.
+ *
+ * `hqCoreVersion` is filled in lazily by walking up from cwd to find
+ * `core/core.yaml` — present only when the CLI is invoked from inside an
+ * hq-core checkout, so the server can see scaffold-generation skew.
+ */
+export const CLI_CLIENT_INFO: ClientInfo = {
+  name: CLI_NAME,
+  version: CLI_VERSION,
+  hqCoreVersion: detectHqCoreVersion(),
+};
+
 /** Build a VaultServiceConfig with the given access token. */
 export function buildVaultConfig(authToken: string): VaultServiceConfig {
   return {
     apiUrl: DEFAULT_VAULT_API_URL,
     authToken,
     region: DEFAULT_COGNITO.region,
+    clientInfo: CLI_CLIENT_INFO,
   };
 }
 

package/test/commands/signals.test.ts

@@ -0,0 +1,200 @@
+/**
+ * signals.test.ts — E2E tests for `hq signals` (US-007).
+ *
+ * Drives the full CLI through `runCli` with `globalThis.fetch` stubbed
+ * (vault-service) and the hq-cloud signals S3 factory swapped to an
+ * in-memory stub. Covers the three e2e cases defined in the PRD:
+ *
+ *   1. `hq signals list --entity indigo --type action_item --format json`
+ *      → exit 0, JSON entry with signalId='xyz'.
+ *   2. `hq signals list --entity indigo --type ramble`
+ *      → exit 1, stderr lists the six canonical signal types.
+ *   3. `hq signals types`
+ *      → exit 0, stdout equals "action_item\ncommitment\ndecision\nkey_point\nrisk\nsummary\n".
+ *
+ * HQ_ACCESS_TOKEN is set per-test so resolveAccessToken() short-circuits
+ * away from the interactive Cognito flow.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  _setSignalsS3Factory,
+  _resetSignalsS3Factory,
+} from "@indigoai-us/hq-cloud";
+import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
+import { mockVaultService } from "../helpers/vault-service-mock.js";
+import { runCli } from "../helpers/cli-runner.js";
+
+// ---------------------------------------------------------------------------
+// Fixture — action_item signal matching sources-pipeline output shape
+// ---------------------------------------------------------------------------
+
+const ACTION_ITEM_MD = `---
+signal_id: xyz
+signal_type: action_item
+source_ref: abc-meeting-001
+citations:
+  - "Stefan to review the sources pipeline implementation by end of week"
+entity_refs:
+  - stefan@indigoai.us
+created_at: "2026-03-15T15:00:00Z"
+---
+
+Stefan will review the sources pipeline implementation and provide feedback by Friday.
+`;
+
+const BODY_SENTINEL = "Stefan will review the sources pipeline implementation";
+
+// ---------------------------------------------------------------------------
+// Per-test setup — vault + S3 mocks + isolated --hq-root
+// ---------------------------------------------------------------------------
+
+let restoreFetch: (() => void) | undefined;
+let tmpHqRoot: string;
+let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
+
+beforeEach(() => {
+  savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
+  process.env.HQ_ACCESS_TOKEN = "test-access-token";
+
+  tmpHqRoot = mkdtempSync(join(tmpdir(), "hq-signals-test-"));
+
+  const s3 = mockS3WithEntries({
+    entries: [
+      {
+        key: "signals/action_item/xyz.md",
+        content: ACTION_ITEM_MD,
+        lastModified: new Date("2026-03-15T15:00:00Z"),
+      },
+    ],
+  });
+  _setSignalsS3Factory(() => s3);
+
+  restoreFetch = mockVaultService({
+    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+  });
+});
+
+afterEach(() => {
+  _resetSignalsS3Factory();
+  restoreFetch?.();
+  restoreFetch = undefined;
+  rmSync(tmpHqRoot, { recursive: true, force: true });
+
+  if (savedEnv.HQ_ACCESS_TOKEN === undefined) {
+    delete process.env.HQ_ACCESS_TOKEN;
+  } else {
+    process.env.HQ_ACCESS_TOKEN = savedEnv.HQ_ACCESS_TOKEN;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tests — PRD e2e cases
+// ---------------------------------------------------------------------------
+
+describe("hq signals (e2e)", () => {
+  it("list --entity indigo --type action_item --format json — exit 0 + signalId='xyz'", async () => {
+    const result = await runCli([
+      "hq",
+      "signals",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "action_item",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode, `stderr=${result.stderr}`).toBe(0);
+    expect(result.stderr).toBe("");
+
+    const parsed = JSON.parse(result.stdout) as {
+      entries: Array<{ signalId: string; signalType: string; key: string }>;
+      nextToken?: string;
+    };
+    expect(parsed.entries).toHaveLength(1);
+    expect(parsed.entries[0].signalId).toBe("xyz");
+    expect(parsed.entries[0].signalType).toBe("action_item");
+    expect(parsed.entries[0].key).toBe("signals/action_item/xyz.md");
+  });
+
+  it("list --entity indigo --type ramble — exit 1 + stderr lists six canonical types", async () => {
+    const result = await runCli([
+      "hq",
+      "signals",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "ramble",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    // Every canonical signal type must appear in the error message.
+    for (const t of [
+      "action_item",
+      "commitment",
+      "decision",
+      "key_point",
+      "risk",
+      "summary",
+    ]) {
+      expect(result.stderr).toContain(t);
+    }
+  });
+
+  it("types — exit 0 + stdout equals the sorted six types, one per line", async () => {
+    const result = await runCli(["hq", "signals", "types"]);
+    expect(result.exitCode).toBe(0);
+    // Sorted alphabetically — happens to match SIGNAL_TYPES insertion order.
+    expect(result.stdout).toBe(
+      "action_item\ncommitment\ndecision\nkey_point\nrisk\nsummary\n",
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bonus coverage — get + wiring
+// ---------------------------------------------------------------------------
+
+describe("hq signals get", () => {
+  it("get --entity indigo --type action_item --id xyz --format markdown — body present", async () => {
+    const result = await runCli([
+      "hq",
+      "signals",
+      "get",
+      "--entity",
+      "indigo",
+      "--type",
+      "action_item",
+      "--id",
+      "xyz",
+      "--format",
+      "markdown",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode, `stderr=${result.stderr}`).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout).toContain(BODY_SENTINEL);
+  });
+});
+
+describe("hq --help wiring", () => {
+  it("mentions the signals subcommand", async () => {
+    const result = await runCli(["hq", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("signals");
+  });
+});

package/test/commands/sources.test.ts

@@ -0,0 +1,225 @@
+/**
+ * sources.test.ts — E2E tests for `hq sources` (US-006).
+ *
+ * Drives the full CLI through `runCli` with `globalThis.fetch` stubbed
+ * (vault-service) and the hq-cloud sources S3 factory swapped to an
+ * in-memory stub. Tests the four e2e cases defined in the PRD:
+ *
+ *   1. `hq sources list --entity indigo --type meeting --format json`
+ *      → exit 0, JSON entry with sourceId='abc'.
+ *   2. `hq sources get --entity indigo --type meeting --id abc`
+ *      → exit 0, body text present in stdout.
+ *   3. `hq sources list --type meeting` (no --entity, no config)
+ *      → exit 1, stderr mentions --entity.
+ *   4. `hq sources list --entity indigo --type pigeon`
+ *      → exit 1, stderr lists valid channels.
+ *
+ * HQ_ACCESS_TOKEN is set per-test so resolveAccessToken() short-circuits
+ * away from the interactive Cognito flow.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  _setSourcesS3Factory,
+  _resetSourcesS3Factory,
+} from "@indigoai-us/hq-cloud";
+import { mockS3WithEntries } from "../helpers/s3-list-mock.js";
+import { mockVaultService } from "../helpers/vault-service-mock.js";
+import { runCli } from "../helpers/cli-runner.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/**
+ * Markdown source matching sources-pipeline output shape.
+ * NOTE: stored at `sources/meeting/abc.md` (singular `meeting/`) because
+ * listSources prefixes with `sources/${channel}/` and channel is the
+ * singular SOURCE_CHANNELS member.
+ */
+const MEETING_MD = `---
+source_id: abc
+source_type: meeting
+channel: meeting
+title: Q1 Planning Meeting
+---
+
+[Stefan 00:00:05]: Body text goes here for the e2e test.
+[Corey 00:00:12]: Acknowledged.
+`;
+
+// Sentinel string used to assert body presence in `hq sources get` output.
+const BODY_SENTINEL = "Body text goes here for the e2e test.";
+
+// ---------------------------------------------------------------------------
+// Per-test setup — vault + S3 mocks + isolated --hq-root
+// ---------------------------------------------------------------------------
+
+let restoreFetch: (() => void) | undefined;
+let tmpHqRoot: string;
+let savedEnv: { HQ_ACCESS_TOKEN: string | undefined };
+
+beforeEach(() => {
+  // Sidestep Cognito interactive flow.
+  savedEnv = { HQ_ACCESS_TOKEN: process.env.HQ_ACCESS_TOKEN };
+  process.env.HQ_ACCESS_TOKEN = "test-access-token";
+
+  // Empty .hq tree so `readActiveCompanySlug` returns undefined unless a
+  // test writes config.json into it.
+  tmpHqRoot = mkdtempSync(join(tmpdir(), "hq-sources-test-"));
+
+  // Default S3 stub returns the one meeting source.
+  const s3 = mockS3WithEntries({
+    entries: [
+      {
+        key: "sources/meeting/abc.md",
+        content: MEETING_MD,
+        lastModified: new Date("2026-03-15T14:00:00Z"),
+      },
+    ],
+  });
+  _setSourcesS3Factory(() => s3);
+
+  // Default vault-service mock with one entity 'indigo'.
+  restoreFetch = mockVaultService({
+    entities: [{ uid: "cmp_indigo_001", slug: "indigo", bucketName: "hq-indigo-bucket" }],
+  });
+});
+
+afterEach(() => {
+  _resetSourcesS3Factory();
+  restoreFetch?.();
+  restoreFetch = undefined;
+  rmSync(tmpHqRoot, { recursive: true, force: true });
+
+  if (savedEnv.HQ_ACCESS_TOKEN === undefined) {
+    delete process.env.HQ_ACCESS_TOKEN;
+  } else {
+    process.env.HQ_ACCESS_TOKEN = savedEnv.HQ_ACCESS_TOKEN;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Tests — PRD e2e cases
+// ---------------------------------------------------------------------------
+
+describe("hq sources (e2e)", () => {
+  it("list --entity indigo --type meeting --format json — exit 0 + JSON with sourceId='abc'", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "meeting",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode, `stderr=${result.stderr}`).toBe(0);
+    expect(result.stderr).toBe("");
+
+    const parsed = JSON.parse(result.stdout) as {
+      entries: Array<{ sourceId: string; channel: string; key: string }>;
+      nextToken?: string;
+    };
+    expect(parsed.entries).toHaveLength(1);
+    expect(parsed.entries[0].sourceId).toBe("abc");
+    expect(parsed.entries[0].channel).toBe("meeting");
+    expect(parsed.entries[0].key).toBe("sources/meeting/abc.md");
+  });
+
+  it("get --entity indigo --type meeting --id abc — exit 0 + stdout contains body text", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "get",
+      "--entity",
+      "indigo",
+      "--type",
+      "meeting",
+      "--id",
+      "abc",
+      "--format",
+      "markdown",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout).toContain(BODY_SENTINEL);
+  });
+
+  it("list --type meeting (no --entity, no config) — exit 1 + stderr mentions --entity", async () => {
+    // tmpHqRoot has no .hq/config.json, so readActiveCompanySlug returns undefined.
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--type",
+      "meeting",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toMatch(/--entity/);
+    // Also surfaces the discovery affordance.
+    expect(result.stderr).toMatch(/hq sources entities/);
+  });
+
+  it("list --entity indigo --type pigeon — exit 1 + stderr lists valid channels", async () => {
+    const result = await runCli([
+      "hq",
+      "sources",
+      "list",
+      "--entity",
+      "indigo",
+      "--type",
+      "pigeon",
+      "--format",
+      "json",
+      "--hq-root",
+      tmpHqRoot,
+    ]);
+
+    expect(result.exitCode).toBe(1);
+    // Every canonical channel must appear in the error message.
+    expect(result.stderr).toContain("meeting");
+    expect(result.stderr).toContain("email");
+    expect(result.stderr).toContain("slack");
+    expect(result.stderr).toContain("linear");
+    expect(result.stderr).toContain("notion");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bonus coverage — channels + wiring
+// ---------------------------------------------------------------------------
+
+describe("hq sources channels", () => {
+  it("prints SOURCE_CHANNELS sorted, one per line, exit 0", async () => {
+    const result = await runCli(["hq", "sources", "channels"]);
+    expect(result.exitCode).toBe(0);
+    const lines = result.stdout.trim().split("\n");
+    // Sorted alphabetically: email, linear, meeting, notion, slack
+    expect(lines).toEqual(["email", "linear", "meeting", "notion", "slack"]);
+  });
+});
+
+describe("hq --help wiring", () => {
+  it("mentions the sources subcommand", async () => {
+    const result = await runCli(["hq", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("sources");
+  });
+});

package/test/fixtures/signals/action_item/sample.md

@@ -0,0 +1,16 @@
+---
+signal_id: sig_action_001
+signal_type: action_item
+source_ref: abc-meeting-001
+citations:
+  - "Stefan to review the sources pipeline implementation by end of week"
+  - "Corey to prepare roadmap slides for the next planning session"
+entity_refs:
+  - stefan@indigoai.us
+  - corey@indigoai.us
+created_at: "2026-03-15T15:00:00Z"
+---
+
+Stefan will review the sources pipeline implementation and provide feedback by Friday 2026-03-20.
+
+Corey will prepare updated roadmap slides covering the CLI read surface and signal type validation for the follow-up planning session.

package/test/fixtures/signals/summary/sample.md

@@ -0,0 +1,12 @@
+---
+signal_id: sig_summary_001
+signal_type: summary
+source_ref: abc-meeting-001
+citations: []
+entity_refs:
+  - stefan@indigoai.us
+  - corey@indigoai.us
+created_at: "2026-03-15T15:00:00Z"
+---
+
+The Q1 planning meeting covered roadmap priorities for the sources pipeline and CLI tooling. Key decisions included implementing the `hq sources` and `hq signals` commands in hq-cli, enforcing a closed signal-type enum to prevent agents from inventing new types, and using STS-scoped credentials via vault-service for tenant isolation. The team agreed to ship a read-only CLI surface first before tackling S3 Vectors search in Phase 2.

package/test/fixtures/sources/meetings/sample.md

@@ -0,0 +1,25 @@
+---
+source_id: abc-meeting-001
+source_type: meeting
+channel: meeting
+title: Q1 Planning Meeting
+date: "2026-03-15"
+participants:
+  - name: Stefan Johnson
+    email: stefan@indigoai.us
+  - name: Corey Smith
+    email: corey@indigoai.us
+duration_seconds: 3600
+entity_ref: cmp_indigo_001
+created_at: "2026-03-15T14:00:00Z"
+---
+
+[Stefan Johnson 00:00:05]: Good morning everyone. Let's get started with the Q1 planning session.
+
+[Corey Smith 00:00:12]: Morning! I have the roadmap slides ready to share.
+
+[Stefan Johnson 00:00:18]: Perfect. First item on the agenda is the sources pipeline work. We need to add a read surface to the CLI so agents and users can browse sources and signals without writing AWS code.
+
+[Corey Smith 00:00:35]: Makes sense. The S3 layout is already defined by the pipeline — sources/{channel}/{sourceId}.md. We just need the listing and fetch commands.
+
+[Stefan Johnson 00:00:48]: Exactly. And we should enforce signal type validation at the CLI layer too. No invented signal types from agents.