@indigoai-us/hq-cli 5.16.0 → 5.17.0-sources-rc.1

package/src/commands/sources.ts

@@ -0,0 +1,356 @@
+/**
+ * `hq sources` subcommand group (US-006).
+ *
+ * Read-side surface over the sources written by sources-pipeline. Each
+ * invocation resolves a Cognito access token (or honors HQ_ACCESS_TOKEN),
+ * vends STS-scoped credentials via vault-service for the requested entity,
+ * and delegates to hq-cloud's listSources/getSource primitives.
+ *
+ * Subcommands:
+ *   hq sources list      List sources of a given channel for an entity.
+ *   hq sources get       Fetch one source by id.
+ *   hq sources channels  Print the canonical SOURCE_CHANNELS enum.
+ *   hq sources entities  List entities the caller has access to.
+ *
+ * Defaults:
+ *   --entity   falls back to .hq/config.json activeCompany (per sync.ts).
+ *   --format   'table' when stdout is a TTY, 'json' when piped.
+ *   --limit    50.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Command } from "commander";
+import chalk from "chalk";
+import {
+  SOURCE_CHANNELS,
+  assertSourceChannel,
+  resolveEntity,
+  listAvailableEntities,
+  listSources,
+  getSource,
+  type SourceChannel,
+  type SourceSummary,
+  type SourceDocument,
+  type AvailableEntity,
+  type EntityContext,
+} from "@indigoai-us/hq-cloud";
+import {
+  ensureCognitoToken,
+  buildVaultConfig,
+  DEFAULT_HQ_ROOT,
+} from "../utils/cognito-session.js";
+import { Sentry } from "../sentry.js";
+
+// ---------------------------------------------------------------------------
+// Access token resolution — honors HQ_ACCESS_TOKEN for tests + CI smoke
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a usable access token. Tests and CI smoke scripts can set
+ * HQ_ACCESS_TOKEN to bypass the interactive Cognito flow; otherwise we fall
+ * back to the cached/refresh/browser-login pipeline in cognito-session.ts.
+ */
+async function resolveAccessToken(): Promise<string> {
+  if (process.env.HQ_ACCESS_TOKEN) return process.env.HQ_ACCESS_TOKEN;
+  return ensureCognitoToken();
+}
+
+// ---------------------------------------------------------------------------
+// Entity resolution — flag → .hq/config.json activeCompany fallback
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the active company slug from .hq/config.json (mirrors sync.ts /
+ * cloud.ts behaviour). Returns undefined when the file is missing or the
+ * key isn't set; never throws.
+ */
+function readActiveCompanySlug(hqRoot: string): string | undefined {
+  const configPath = path.join(hqRoot, ".hq", "config.json");
+  if (!fs.existsSync(configPath)) return undefined;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    const slug = (cfg as { activeCompany?: unknown }).activeCompany;
+    return typeof slug === "string" && slug.length > 0 ? slug : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function requireEntitySlug(flag: string | undefined, hqRoot: string): string {
+  const slug = flag ?? readActiveCompanySlug(hqRoot);
+  if (!slug) {
+    throw new Error(
+      "No entity specified. Pass --entity <slug> or run `hq sources entities` to see your options.",
+    );
+  }
+  return slug;
+}
+
+// ---------------------------------------------------------------------------
+// Format defaults — TTY-aware (humans get table, agents get JSON)
+// ---------------------------------------------------------------------------
+
+type ListFormat = "table" | "json";
+type GetFormat = "markdown" | "json";
+
+function defaultListFormat(): ListFormat {
+  return process.stdout.isTTY ? "table" : "json";
+}
+
+function defaultGetFormat(): GetFormat {
+  return process.stdout.isTTY ? "markdown" : "json";
+}
+
+// ---------------------------------------------------------------------------
+// Rendering helpers
+// ---------------------------------------------------------------------------
+
+function renderListTable(entries: SourceSummary[], includeFrontmatter: boolean): string {
+  if (entries.length === 0) return "(no sources)";
+  const rows = entries.map((e) => ({
+    sourceId: e.sourceId,
+    lastModified: e.lastModified.toISOString(),
+    size: String(e.size),
+    ...(includeFrontmatter
+      ? { title: typeof e.frontmatter?.title === "string" ? e.frontmatter.title : "" }
+      : {}),
+  }));
+  const headers = Object.keys(rows[0]);
+  const widths = headers.map((h) =>
+    Math.max(h.length, ...rows.map((r) => String((r as Record<string, string>)[h]).length)),
+  );
+  const pad = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length));
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = rows
+    .map((r) =>
+      headers.map((h, i) => pad(String((r as Record<string, string>)[h]), widths[i])).join("  "),
+    )
+    .join("\n");
+  return [headerLine, sep, body].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: list
+// ---------------------------------------------------------------------------
+
+interface ListOptions {
+  entity?: string;
+  type?: string;
+  limit?: string;
+  pageToken?: string;
+  format?: ListFormat;
+  includeFrontmatter?: boolean;
+  hqRoot: string;
+}
+
+async function runList(options: ListOptions): Promise<void> {
+  if (!options.type) {
+    throw new Error(
+      `--type <channel> is required. Valid channels: ${SOURCE_CHANNELS.join(", ")}`,
+    );
+  }
+  // Throws InvalidSourceChannelError with the list of valid channels if not in enum.
+  assertSourceChannel(options.type);
+  const channel: SourceChannel = options.type;
+
+  const slug = requireEntitySlug(options.entity, options.hqRoot);
+  const limit = options.limit ? Number.parseInt(options.limit, 10) : 50;
+  if (!Number.isFinite(limit) || limit <= 0) {
+    throw new Error(`--limit must be a positive integer (got '${options.limit}')`);
+  }
+  const format = options.format ?? defaultListFormat();
+
+  const accessToken = await resolveAccessToken();
+  const vaultConfig = buildVaultConfig(accessToken);
+  const entity: EntityContext = await resolveEntity({ slug, vaultConfig });
+
+  const result = await listSources({
+    entity,
+    channel,
+    limit,
+    continuationToken: options.pageToken,
+    includeFrontmatter: options.includeFrontmatter,
+  });
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return;
+  }
+
+  process.stdout.write(renderListTable(result.entries, !!options.includeFrontmatter) + "\n");
+  if (result.nextToken) {
+    process.stdout.write(`\nNext page token: ${result.nextToken}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: get
+// ---------------------------------------------------------------------------
+
+interface GetOptions {
+  entity?: string;
+  type?: string;
+  id?: string;
+  format?: GetFormat;
+  includeRaw?: boolean;
+  hqRoot: string;
+}
+
+async function runGet(options: GetOptions): Promise<void> {
+  if (!options.type) {
+    throw new Error(
+      `--type <channel> is required. Valid channels: ${SOURCE_CHANNELS.join(", ")}`,
+    );
+  }
+  if (!options.id) {
+    throw new Error("--id <sourceId> is required.");
+  }
+  assertSourceChannel(options.type);
+  const channel: SourceChannel = options.type;
+
+  const slug = requireEntitySlug(options.entity, options.hqRoot);
+  const format = options.format ?? defaultGetFormat();
+
+  const accessToken = await resolveAccessToken();
+  const vaultConfig = buildVaultConfig(accessToken);
+  const entity: EntityContext = await resolveEntity({ slug, vaultConfig });
+
+  const doc: SourceDocument = await getSource({
+    entity,
+    channel,
+    sourceId: options.id,
+    includeRaw: options.includeRaw,
+  });
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(doc, null, 2) + "\n");
+    return;
+  }
+
+  // markdown: reconstruct frontmatter block + body so the output round-trips.
+  if (doc.frontmatter) {
+    const yamlLines = Object.entries(doc.frontmatter).map(
+      ([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`,
+    );
+    process.stdout.write(`---\n${yamlLines.join("\n")}\n---\n\n${doc.body}\n`);
+  } else {
+    process.stdout.write(doc.body + "\n");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: channels
+// ---------------------------------------------------------------------------
+
+function runChannels(): void {
+  const sorted = [...SOURCE_CHANNELS].sort();
+  process.stdout.write(sorted.join("\n") + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: entities
+// ---------------------------------------------------------------------------
+
+async function runEntities(options: { format?: ListFormat }): Promise<void> {
+  const format = options.format ?? defaultListFormat();
+  const accessToken = await resolveAccessToken();
+  const vaultConfig = buildVaultConfig(accessToken);
+  const entities: AvailableEntity[] = await listAvailableEntities({ vaultConfig });
+
+  if (format === "json") {
+    process.stdout.write(JSON.stringify(entities, null, 2) + "\n");
+    return;
+  }
+
+  if (entities.length === 0) {
+    process.stdout.write("(no entities — your account has no active memberships)\n");
+    return;
+  }
+
+  const headers = ["slug", "role", "uid"];
+  const widths = headers.map((h, i) =>
+    Math.max(
+      h.length,
+      ...entities.map((e) => String([e.slug, e.role, e.uid][i]).length),
+    ),
+  );
+  const pad = (s: string, w: number): string => s + " ".repeat(Math.max(0, w - s.length));
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join("  ");
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  const body = entities
+    .map((e) =>
+      [e.slug, e.role, e.uid].map((cell, i) => pad(cell, widths[i])).join("  "),
+    )
+    .join("\n");
+  process.stdout.write([headerLine, sep, body].join("\n") + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/** Wrap an action so caught errors print red + capture to Sentry + exit 1. */
+function withErrorHandling<T extends unknown[]>(
+  fn: (...args: T) => Promise<void> | void,
+): (...args: T) => Promise<void> {
+  return async (...args: T) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(chalk.red(`✗ ${message}\n`));
+      Sentry.captureException(err);
+      process.exit(1);
+    }
+  };
+}
+
+export function registerSourcesCommand(program: Command): void {
+  const sources = program
+    .command("sources")
+    .description("Read sources (meetings, emails, etc.) from a vault entity");
+
+  sources
+    .command("list")
+    .description("List sources of a given channel for an entity")
+    .option("--entity <slug>", "Entity slug (defaults to .hq/config.json activeCompany)")
+    .option("--type <channel>", `Source channel: ${SOURCE_CHANNELS.join(" | ")}`)
+    .option("--limit <n>", "Max entries per page (default 50)")
+    .option("--page-token <token>", "Continuation token from a prior page")
+    .option("--format <fmt>", "Output format: table | json (default: table for TTY, json piped)")
+    .option("--include-frontmatter", "Fetch + parse each entry's frontmatter (extra GETs)")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (for .hq/config.json lookup; default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(withErrorHandling(async (options: ListOptions) => runList(options)));
+
+  sources
+    .command("get")
+    .description("Fetch a single source by id")
+    .option("--entity <slug>", "Entity slug (defaults to .hq/config.json activeCompany)")
+    .option("--type <channel>", `Source channel: ${SOURCE_CHANNELS.join(" | ")}`)
+    .option("--id <sourceId>", "Source id (filename minus .md)")
+    .option("--format <fmt>", "Output format: markdown | json (default: markdown for TTY, json piped)")
+    .option("--include-raw", "Also fetch the .raw.json sibling")
+    .option(
+      "--hq-root <path>",
+      `Local HQ tree root (for .hq/config.json lookup; default: ${DEFAULT_HQ_ROOT})`,
+      DEFAULT_HQ_ROOT,
+    )
+    .action(withErrorHandling(async (options: GetOptions) => runGet(options)));
+
+  sources
+    .command("channels")
+    .description("Print the canonical source channels (one per line)")
+    .action(withErrorHandling(() => runChannels()));
+
+  sources
+    .command("entities")
+    .description("List entities (companies/personal) your account has access to")
+    .option("--format <fmt>", "Output format: table | json (default: table for TTY, json piped)")
+    .action(withErrorHandling(async (options: { format?: ListFormat }) => runEntities(options)));
+}

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");
+  });
+});