@indigoai-us/hq-cli 5.52.0 → 5.53.1

package/src/commands/company.ts

@@ -0,0 +1,132 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getEntityUid } from "../utils/vault-api.js";
+
+/**
+ * `hq company settings set` — owner-only per-company settings toggles
+ * (agency group-grants US-007 / hq-native-crm US-003). Wraps
+ * `PUT /company-settings`, setting the runtime-flippable `crmEnabled` /
+ * `ontologyEnabled` flags so an owner can enable the native CRM (and the
+ * ontology gardener) for a company without a redeploy.
+ *
+ * Conventions mirror `secrets.ts`: ensureCognitoToken() → getEntityUid() →
+ * vaultApiFetch() → error-check → chalk output.
+ */
+
+interface SettingsSetFlags {
+  crmEnabled?: string;
+  ontologyEnabled?: string;
+}
+
+/**
+ * Parse a `--flag <true|false>` string into a boolean, or throw. Commander
+ * passes the raw string; we validate strictly so a typo never silently writes
+ * the wrong value.
+ */
+function parseBoolFlag(value: string, flag: string): boolean {
+  const v = value.trim().toLowerCase();
+  if (v === "true") return true;
+  if (v === "false") return false;
+  throw new Error(`${flag} must be 'true' or 'false' (got '${value}')`);
+}
+
+export function registerCompanyCommand(program: Command): void {
+  const company = program
+    .command("company")
+    .description("Company-level settings")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  const settings = company
+    .command("settings")
+    .description("Per-company settings (owner-only)");
+
+  settings
+    .command("set")
+    .description(
+      "Set per-company settings (PUT /company-settings). Require at least one " +
+        "of --crm-enabled / --ontology-enabled.",
+    )
+    .option(
+      "--crm-enabled <true|false>",
+      "Enable/disable the native CRM for this company",
+    )
+    .option(
+      "--ontology-enabled <true|false>",
+      "Enable/disable the ontology gardener for this company",
+    )
+    .action(async (opts: SettingsSetFlags) => {
+      try {
+        const companySlug = company.opts().company as string | undefined;
+        if (!companySlug) {
+          console.error(chalk.red("Error: --company <slug> is required."));
+          process.exit(1);
+        }
+        if (opts.crmEnabled === undefined && opts.ontologyEnabled === undefined) {
+          console.error(
+            chalk.red(
+              "Error: provide at least one of --crm-enabled / --ontology-enabled.",
+            ),
+          );
+          process.exit(1);
+        }
+
+        const body: Record<string, unknown> = {};
+        if (opts.crmEnabled !== undefined) {
+          body.crmEnabled = parseBoolFlag(opts.crmEnabled, "--crm-enabled");
+        }
+        if (opts.ontologyEnabled !== undefined) {
+          body.ontologyEnabled = parseBoolFlag(
+            opts.ontologyEnabled,
+            "--ontology-enabled",
+          );
+        }
+
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(token, { companySlug });
+        body.companyUid = companyUid;
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/company-settings",
+          method: "PUT",
+          body,
+        });
+
+        if (!res.ok) {
+          const errBody = (await res.json().catch(() => ({}))) as Record<
+            string,
+            unknown
+          >;
+          if (res.status === 403) {
+            console.error(
+              chalk.red(
+                "Requires owner role on this company to change its settings.",
+              ),
+            );
+            process.exit(1);
+          }
+          console.error(
+            chalk.red(
+              `Failed to update company settings: ${(errBody.error as string) ?? res.statusText}`,
+            ),
+          );
+          process.exit(1);
+        }
+
+        const applied = Object.entries(body)
+          .filter(([k]) => k !== "companyUid")
+          .map(([k, v]) => `${k}=${v}`)
+          .join(", ");
+        console.log(
+          chalk.green(`Company settings updated for ${companySlug}: ${applied}`),
+        );
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/commands/crm.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Unit tests for `hq crm entity upsert` (crm.ts).
+ *
+ * Mirrors members.test.ts: mock ensureCognitoToken + getEntityUid, spy on
+ * global fetch (vaultApiFetch's transport), drive the command through a
+ * Commander program, and assert the request shape + output / exit behavior.
+ */
+
+import { Command } from "commander";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("../utils/cognito-session.js")>();
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+vi.mock("../utils/vault-api.js", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../utils/vault-api.js")>();
+  return {
+    ...original,
+    getEntityUid: vi.fn(async () => "cmp_acme"),
+  };
+});
+
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getEntityUid } from "../utils/vault-api.js";
+import { registerCrmCommand } from "./crm.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+let exitSpy: MockInstance<typeof process.exit>;
+const mockEnsureCognitoToken = vi.mocked(ensureCognitoToken);
+const mockGetEntityUid = vi.mocked(getEntityUid);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+  mockEnsureCognitoToken.mockResolvedValue("test-token");
+  mockGetEntityUid.mockResolvedValue("cmp_acme");
+  // process.exit(1) on the error paths — throw so the test can assert instead
+  // of tearing down the worker.
+  exitSpy = vi
+    .spyOn(process, "exit")
+    .mockImplementation((code?: number) => {
+      throw new Error(`process.exit(${code})`);
+    }) as unknown as MockInstance<typeof process.exit>;
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.name("hq").exitOverride();
+  registerCrmCommand(program);
+  return program;
+}
+
+async function run(args: string[]): Promise<void> {
+  await buildProgram().parseAsync(["node", "hq", ...args]);
+}
+
+describe("hq crm entity upsert", () => {
+  it("flag form: POSTs a single entity to /crm/entities with external_ids", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        status: "written",
+        created: 1,
+        updated: 0,
+        skipped: 0,
+        errors: [],
+      }),
+    );
+
+    await run([
+      "crm",
+      "entity",
+      "upsert",
+      "--company",
+      "acme",
+      "--type",
+      "contact",
+      "--name",
+      "Jane Prospect",
+      "--attio-id",
+      "rec_jane",
+    ]);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/crm/entities");
+    expect(init?.method).toBe("POST");
+    const sent = JSON.parse(init?.body as string);
+    expect(sent.companyUid).toBe("cmp_acme");
+    expect(sent.entities).toHaveLength(1);
+    expect(sent.entities[0]).toMatchObject({
+      type: "contact",
+      canonical_name: "Jane Prospect",
+      external_ids: { attio: "rec_jane" },
+    });
+  });
+
+  it("exits 1 with a helpful message on 403 CRM_DISABLED", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, {
+        error: "the native CRM is not enabled for this company",
+        code: "CRM_DISABLED",
+      }),
+    );
+
+    await expect(
+      run([
+        "crm",
+        "entity",
+        "upsert",
+        "--company",
+        "acme",
+        "--type",
+        "contact",
+        "--name",
+        "Jane",
+      ]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("requires --company", async () => {
+    await expect(
+      run(["crm", "entity", "upsert", "--type", "contact", "--name", "Jane"]),
+    ).rejects.toThrow("process.exit(1)");
+    // Never made the request — failed before token resolution.
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("requires --type when no --json is given", async () => {
+    await expect(
+      run(["crm", "entity", "upsert", "--company", "acme", "--name", "Jane"]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects an unknown --type", async () => {
+    await expect(
+      run([
+        "crm",
+        "entity",
+        "upsert",
+        "--company",
+        "acme",
+        "--type",
+        "widget",
+        "--name",
+        "Jane",
+      ]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/crm.ts

@@ -0,0 +1,236 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { readFileSync } from "node:fs";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getEntityUid } from "../utils/vault-api.js";
+
+/**
+ * `hq crm entity upsert` — agent-facing controlled entity upsert
+ * (hq-native-crm US-002). Wraps `POST /crm/entities`, which fronts the ontology
+ * write gate so an authenticated company MEMBER (or higher) can create/update
+ * canonical CRM entities in their company's vault.
+ *
+ * Conventions mirror `secrets.ts`: ensureCognitoToken() → getEntityUid() →
+ * vaultApiFetch() → error-check → chalk output.
+ */
+
+/** The CRM/ontology entity types the upsert route accepts via `--type`. */
+const CRM_ENTITY_TYPES = [
+  "contact",
+  "deal",
+  "contract",
+  "invoice",
+  "company",
+] as const;
+type CrmEntityType = (typeof CRM_ENTITY_TYPES)[number];
+
+/** A minimal entity payload in the write-gate ExtractedEntity shape. */
+interface CrmEntityInput {
+  type: string;
+  canonical_name: string;
+  aliases?: string[];
+  confidence?: number;
+  domain?: string[];
+  relationships?: unknown[];
+  external_ids?: Record<string, string>;
+  web_domains?: string[];
+}
+
+interface UpsertFlags {
+  type?: string;
+  name?: string;
+  attioId?: string;
+  stripeId?: string;
+  pandadocId?: string;
+  neonId?: string;
+  json?: string;
+}
+
+/**
+ * Read the `--json <file|->` payload: a single entity object or an array of
+ * entities. `-` reads from stdin. Returns the entities array (always
+ * normalized to an array) or throws a descriptive Error.
+ */
+function readJsonEntities(source: string): CrmEntityInput[] {
+  const raw =
+    source === "-"
+      ? readFileSync(0, "utf8") // fd 0 = stdin
+      : readFileSync(source, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `--json payload is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const entities = Array.isArray(parsed) ? parsed : [parsed];
+  if (entities.length === 0) {
+    throw new Error("--json payload contained no entities");
+  }
+  for (const e of entities) {
+    if (!e || typeof e !== "object") {
+      throw new Error("--json entities must be objects");
+    }
+    const obj = e as Record<string, unknown>;
+    if (typeof obj.type !== "string" || typeof obj.canonical_name !== "string") {
+      throw new Error(
+        "each --json entity needs a string `type` and `canonical_name`",
+      );
+    }
+  }
+  return entities as CrmEntityInput[];
+}
+
+/**
+ * Build a single entity from the flag form (`--type` + `--name` + optional
+ * external-id flags). The route fills the additive defaults (aliases/domain/
+ * relationships/confidence) when omitted, but we send a complete minimal shape.
+ */
+function buildEntityFromFlags(opts: UpsertFlags): CrmEntityInput {
+  const externalIds: Record<string, string> = {};
+  if (opts.attioId) externalIds.attio = opts.attioId;
+  if (opts.stripeId) externalIds.stripe = opts.stripeId;
+  if (opts.pandadocId) externalIds.pandadoc = opts.pandadocId;
+  if (opts.neonId) externalIds.neon = opts.neonId;
+
+  const entity: CrmEntityInput = {
+    type: opts.type as CrmEntityType,
+    canonical_name: opts.name as string,
+    aliases: [],
+    confidence: 1,
+    domain: [],
+    relationships: [],
+  };
+  if (Object.keys(externalIds).length > 0) {
+    entity.external_ids = externalIds;
+  }
+  return entity;
+}
+
+export function registerCrmCommand(program: Command): void {
+  const crm = program
+    .command("crm")
+    .description("Native CRM — upsert canonical entities into a company vault")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  const entity = crm
+    .command("entity")
+    .description("CRM entity operations");
+
+  entity
+    .command("upsert")
+    .description(
+      "Create or update a canonical CRM entity (POST /crm/entities). " +
+        "Use --type/--name (+ optional external-id flags) or --json <file|-> " +
+        "to pass a full entity/array.",
+    )
+    .option(
+      "--type <type>",
+      `Entity type: ${CRM_ENTITY_TYPES.join(" | ")}`,
+    )
+    .option("--name <canonical_name>", "Canonical entity name")
+    .option("--attio-id <id>", "Attio record id → external_ids.attio")
+    .option("--stripe-id <id>", "Stripe object id → external_ids.stripe")
+    .option("--pandadoc-id <id>", "PandaDoc document id → external_ids.pandadoc")
+    .option("--neon-id <id>", "Neon row id → external_ids.neon")
+    .option(
+      "--json <file|->",
+      "Path to a JSON file (or '-' for stdin) with a full entity object or array",
+    )
+    .action(async (opts: UpsertFlags) => {
+      try {
+        const companySlug = crm.opts().company as string | undefined;
+        if (!companySlug) {
+          console.error(
+            chalk.red("Error: --company <slug> is required."),
+          );
+          process.exit(1);
+        }
+
+        // Resolve the entity payload: --json is the alternative to flags.
+        let entities: CrmEntityInput[];
+        if (opts.json) {
+          entities = readJsonEntities(opts.json);
+        } else {
+          if (!opts.type) {
+            console.error(
+              chalk.red(
+                `Error: --type <${CRM_ENTITY_TYPES.join("|")}> is required (or pass --json).`,
+              ),
+            );
+            process.exit(1);
+          }
+          if (!CRM_ENTITY_TYPES.includes(opts.type as CrmEntityType)) {
+            console.error(
+              chalk.red(
+                `Error: --type must be one of ${CRM_ENTITY_TYPES.join(", ")}.`,
+              ),
+            );
+            process.exit(1);
+          }
+          if (!opts.name) {
+            console.error(
+              chalk.red("Error: --name <canonical_name> is required (or pass --json)."),
+            );
+            process.exit(1);
+          }
+          entities = [buildEntityFromFlags(opts)];
+        }
+
+        const token = await ensureCognitoToken();
+        const companyUid = await getEntityUid(token, { companySlug });
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/crm/entities",
+          method: "POST",
+          body: { companyUid, entities },
+        });
+
+        if (!res.ok) {
+          const body = (await res.json().catch(() => ({}))) as Record<
+            string,
+            unknown
+          >;
+          // CrmDisabledError surfaces as a 403 with a helpful message.
+          if (res.status === 403 && body.code === "CRM_DISABLED") {
+            console.error(
+              chalk.red(
+                "CRM is not enabled for this company. Enable it first: " +
+                  `hq company settings set --company ${companySlug} --crm-enabled true`,
+              ),
+            );
+            process.exit(1);
+          }
+          console.error(
+            chalk.red(
+              `Failed to upsert entities: ${(body.error as string) ?? res.statusText}`,
+            ),
+          );
+          process.exit(1);
+        }
+
+        const result = (await res.json().catch(() => ({}))) as {
+          created?: number;
+          updated?: number;
+          skipped?: number;
+          status?: string;
+        };
+        console.log(
+          chalk.green(
+            `Upsert ${result.status ?? "ok"}: ` +
+              `${result.created ?? 0} created, ` +
+              `${result.updated ?? 0} updated, ` +
+              `${result.skipped ?? 0} skipped.`,
+          ),
+        );
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}

package/src/commands/files-delete.test.ts

@@ -398,3 +398,87 @@ describe("hq files delete — server error mapping", () => {
     expect(formatFilesDeleteError(new FilesDeleteHttpError(500, "boom"), "p")).toMatch(/Server error: boom/);
   });
 });
+
+describe("hq files delete — --personal (personal vault scope)", () => {
+  // Body parser tolerant of both scope shapes (company vs personal).
+  function bodies(): Array<Record<string, unknown>> {
+    return deleteCalls().map((c) => JSON.parse((c[1]?.body as string) ?? "{}"));
+  }
+
+  it("--dry-run sends { personal: true } with NO company membership lookup", async () => {
+    // First (and only) fetch is the delete preview — getCompanyUid is skipped.
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({
+        dryRun: true,
+        matched: 2,
+        keys: ["installer/a.txt", "installer/b.txt"],
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "delete", "installer/", "--personal", "--dry-run"],
+      { from: "user" },
+    );
+
+    const b = bodies();
+    expect(b).toHaveLength(1);
+    expect(b[0]).toEqual({ personal: true, prefix: "installer/*", dryRun: true });
+    expect(b[0]).not.toHaveProperty("company");
+    expect(printed()).toContain("[dry-run]");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("real delete with --yes previews then deletes, both bodies personal-scoped", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 2, keys: ["installer/a.txt", "installer/b.txt"] }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: false, matched: 2, deleted: 2, tombstoned: 2 }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "delete", "installer/*", "--personal", "--yes"],
+      { from: "user" },
+    );
+
+    const b = bodies();
+    expect(b).toHaveLength(2);
+    expect(b[0]).toEqual({ personal: true, prefix: "installer/*", dryRun: true });
+    expect(b[1]).toEqual({ personal: true, prefix: "installer/*", dryRun: false });
+    expect(printed()).toContain("Deleted 2 objects");
+  });
+
+  it("confirmation copy says 'your personal vault' (not the shared-vault wording)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      deleteResponse({ dryRun: true, matched: 1, keys: ["installer/a.txt"] }),
+    );
+    let prompt = "";
+    await runFilesDelete(
+      { prefix: "installer/*", dryRun: false, yes: false, personal: true, companySlug: undefined },
+      {
+        confirm: async (m) => {
+          prompt = m;
+          return false;
+        },
+      },
+    );
+    expect(prompt).toContain("your personal vault");
+    expect(prompt).not.toContain("shared vault");
+    // Declined → no real delete (only the preview fetch happened).
+    expect(bodies()).toHaveLength(1);
+  });
+
+  it("rejects --personal combined with --company before any network call", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "--company", "acme", "delete", "installer/*", "--personal"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+    expect(printedErr()).toContain("Pass either --personal or --company");
+    expect(deleteCalls()).toHaveLength(0);
+  });
+});