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

package/src/commands/members.ts

@@ -41,7 +41,7 @@ export interface InviteOptions {
 export interface InviteResult {
   inviteToken: string;
   magicLink: string;
-  membership: { role: string; status: string };
+  membership: { role: string; status: string; inviteToken?: string };
 }
 
 export interface DetectedTarget {
@@ -132,30 +132,53 @@ export async function inviteMember(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
 
   const data = (await res.json()) as {
-    membership: { role: string; status: string };
-    inviteToken: string;
+    membership?: { role: string; status: string; inviteToken?: string };
+    inviteToken?: string;
   };
+  // The token may arrive at the response root OR nested on the membership row,
+  // depending on vault-service version. Resolve from either; never emit
+  // `hq://accept/undefined` (a broken link that looks like success).
+  const inviteToken = data.inviteToken ?? data.membership?.inviteToken;
+  if (!inviteToken) {
+    const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
+    throw new Error(
+      `Invite was created but the server response did not include an invite token (response keys: ${keys}). ` +
+        "Run `hq members list` to retrieve the pending invite, or upgrade hq.",
+    );
+  }
   return {
-    inviteToken: data.inviteToken,
-    magicLink: `hq://accept/${data.inviteToken}`,
-    membership: data.membership,
+    inviteToken,
+    magicLink: `hq://accept/${inviteToken}`,
+    membership: data.membership ?? { role: options.role, status: "pending" },
   };
 }
 
 export class InviteHttpError extends Error {
-  constructor(public status: number, message: string) {
+  constructor(
+    public status: number,
+    message: string,
+    public code?: string,
+  ) {
     super(message);
     this.name = "InviteHttpError";
   }
 }
 
-export function formatInviteHttpError(status: number, fallback: string): string {
+export function formatInviteHttpError(
+  status: number,
+  fallback: string,
+  code?: string,
+): string {
   if (status === 401) return "Not authenticated — please run `hq login`";
   if (status === 403) {
+    if (code === "ADMIN_ROLE_TARGET_RESTRICTED") {
+      return "Admin can only invite at role=member; ask an owner to invite at this role";
+    }
     return "Not authorized — only admins and owners can invite members";
   }
   if (status === 409) {
@@ -178,10 +201,11 @@ export async function listPendingInvites(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
-  const data = (await res.json()) as { invites: PendingInvite[] };
-  return data.invites;
+  const data = (await res.json()) as { invites?: PendingInvite[] | null };
+  return data?.invites ?? [];
 }
 
 export async function revokeInvite(
@@ -200,6 +224,7 @@ export async function revokeInvite(
     throw new InviteHttpError(
       res.status,
       err.message ?? err.error ?? res.statusText,
+      err.code,
     );
   }
 }
@@ -260,7 +285,11 @@ export function registerMembersCommand(program: Command): void {
           );
         } catch (err) {
           if (err instanceof InviteHttpError) {
-            console.error(chalk.red(formatInviteHttpError(err.status, err.message)));
+            console.error(
+              chalk.red(
+                formatInviteHttpError(err.status, err.message, err.code),
+              ),
+            );
             process.exit(1);
           }
           console.error(
@@ -350,10 +379,12 @@ export function registerMembersCommand(program: Command): void {
         if (err instanceof InviteHttpError) {
           const msg =
             err.status === 403
-              ? "Not authorized — only admins and owners can revoke invites"
+              ? err.code === "ADMIN_ROLE_TARGET_RESTRICTED"
+                ? "Admin can only revoke role=member; ask an owner to revoke this membership"
+                : "Not authorized — only admins and owners can revoke invites"
               : err.status === 404
                 ? "Invite not found — it may have already been accepted or revoked"
-                : formatInviteHttpError(err.status, err.message);
+                : formatInviteHttpError(err.status, err.message, err.code);
           console.error(chalk.red(msg));
           process.exit(1);
         }

package/src/commands/signals.ts

@@ -0,0 +1,345 @@
+/**
+ * `hq signals` subcommand group (US-007).
+ *
+ * Read-side surface over the signals written by sources-pipeline (and any
+ * future signal producer). 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
+ * listSignals/getSignal primitives.
+ *
+ * Subcommands:
+ *   hq signals list      List signals of a given type for an entity.
+ *   hq signals get       Fetch one signal by id.
+ *   hq signals types     Print the canonical SIGNAL_TYPES enum.
+ *   hq signals entities  List entities the caller has access to.
+ *
+ * Mirrors `hq sources` exactly — same flags, same TTY-aware defaults,
+ * same error/Sentry plumbing. Defense-in-depth signal-type validation
+ * (assertSignalType) runs at the CLI layer as well as in hq-cloud, so
+ * agents can't fabricate a signal type even if they bypass the CLI's
+ * --type flag parsing.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Command } from "commander";
+import chalk from "chalk";
+import {
+  SIGNAL_TYPES,
+  assertSignalType,
+  resolveEntity,
+  listAvailableEntities,
+  listSignals,
+  getSignal,
+  type SignalType,
+  type SignalSummary,
+  type SignalDocument,
+  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
+// ---------------------------------------------------------------------------
+
+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
+// ---------------------------------------------------------------------------
+
+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 signals 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: SignalSummary[], includeFrontmatter: boolean): string {
+  if (entries.length === 0) return "(no signals)";
+  // sourceRef column is only meaningful when --include-frontmatter was passed;
+  // omit it otherwise so the table doesn't lie with empty cells.
+  const rows = entries.map((e) => ({
+    signalId: e.signalId,
+    ...(includeFrontmatter ? { sourceRef: e.sourceRef ?? "" } : {}),
+    lastModified: e.lastModified.toISOString(),
+    size: String(e.size),
+  }));
+  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 <signalType> is required. Valid types: ${SIGNAL_TYPES.join(", ")}`,
+    );
+  }
+  // Throws InvalidSignalTypeError with the list of valid types if not in enum.
+  assertSignalType(options.type);
+  const signalType: SignalType = 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 listSignals({
+    entity,
+    signalType,
+    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;
+  hqRoot: string;
+}
+
+async function runGet(options: GetOptions): Promise<void> {
+  if (!options.type) {
+    throw new Error(
+      `--type <signalType> is required. Valid types: ${SIGNAL_TYPES.join(", ")}`,
+    );
+  }
+  if (!options.id) {
+    throw new Error("--id <signalId> is required.");
+  }
+  assertSignalType(options.type);
+  const signalType: SignalType = 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: SignalDocument = await getSignal({
+    entity,
+    signalType,
+    signalId: options.id,
+  });
+
+  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: types
+// ---------------------------------------------------------------------------
+
+function runTypes(): void {
+  const sorted = [...SIGNAL_TYPES].sort();
+  process.stdout.write(sorted.join("\n") + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Subcommand: entities (alias — identical to `hq sources 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 registerSignalsCommand(program: Command): void {
+  const signals = program
+    .command("signals")
+    .description("Read signals (action_items, decisions, etc.) from a vault entity");
+
+  signals
+    .command("list")
+    .description("List signals of a given type for an entity")
+    .option("--entity <slug>", "Entity slug (defaults to .hq/config.json activeCompany)")
+    .option("--type <signalType>", `Signal type: ${SIGNAL_TYPES.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)));
+
+  signals
+    .command("get")
+    .description("Fetch a single signal by id")
+    .option("--entity <slug>", "Entity slug (defaults to .hq/config.json activeCompany)")
+    .option("--type <signalType>", `Signal type: ${SIGNAL_TYPES.join(" | ")}`)
+    .option("--id <signalId>", "Signal id (filename minus .md)")
+    .option("--format <fmt>", "Output format: markdown | json (default: markdown for TTY, json piped)")
+    .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)));
+
+  signals
+    .command("types")
+    .description("Print the canonical signal types (one per line)")
+    .action(withErrorHandling(() => runTypes()));
+
+  signals
+    .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)));
+}