@indigoai-us/hq-cli 5.51.0 → 5.53.0

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

package/src/commands/files.test.ts

@@ -501,6 +501,136 @@ describe("hq files share — direct-grant fork (with --with)", () => {
     expect(errs).toMatch(/--permission is required/);
     expect(fetchSpy).not.toHaveBeenCalled();
   });
+
+  it("--full --with email grants the '*' wildcard at the default write permission (no glob to quote)", async () => {
+    // 1) /membership/me for company resolution
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          {
+            membershipKey: "k1",
+            companyUid: "cmp_acme",
+            role: "member",
+            status: "active",
+          },
+        ],
+      }),
+    );
+    // 2) POST /files/cmp_acme/acl/grant
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { acl: { path: "*" } }),
+    );
+
+    const program = buildProgram();
+    // No positional path, no --permission — --full supplies prefix '*' and
+    // defaults permission to write.
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com"],
+      { from: "user" },
+    );
+
+    const mintCalls = fetchSpy.mock.calls.filter((c) =>
+      String(c[0]).includes("/share-session"),
+    );
+    expect(mintCalls).toHaveLength(0);
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    expect(grantCall).toBeDefined();
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "write",
+    });
+
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toMatch(/ENTIRE vault/);
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it("--full honors an explicit --permission read (read-only full vault)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "user@example.com", "--permission", "read"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "email",
+      granteeId: "user@example.com",
+      permission: "read",
+    });
+  });
+
+  it("--full composes with @all (whole vault for the whole company → company-wide '*')", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        memberships: [
+          { membershipKey: "k1", companyUid: "cmp_acme", role: "member", status: "active" },
+        ],
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { acl: { path: "*" } }));
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["files", "share", "--full", "--with", "@all"],
+      { from: "user" },
+    );
+
+    const grantCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/acl/grant"),
+    );
+    const body = JSON.parse((grantCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      prefix: "*",
+      granteeType: "company-wide",
+      granteeId: "",
+      permission: "write",
+    });
+  });
+
+  it("rejects --full without --with (and never calls the network)", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["files", "share", "--full"], { from: "user" }),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/--full.*requires --with/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects --full when file paths are also passed", async () => {
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(
+        ["files", "share", "somePath", "--full", "--with", "user@example.com"],
+        { from: "user" },
+      ),
+    ).rejects.toThrow(/__EXIT__:1/);
+
+    const errs = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(errs).toMatch(/entire vault; do not also pass file paths/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/commands/files.ts

@@ -135,6 +135,10 @@ export function registerFilesCommand(program: Command): Command {
       "Email address, group id, or '@all' to share with every active company member",
     )
     .option("--permission <level>", "Permission level (only with --with): read | write")
+    .option(
+      "--full",
+      "Grant access to the ENTIRE vault (the '*' wildcard prefix) — no need to quote a glob. Requires --with; defaults to write permission.",
+    )
     .option(
       "--expires <duration>",
       "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.",
@@ -146,11 +150,45 @@ export function registerFilesCommand(program: Command): Command {
         opts: {
           with?: string;
           permission?: string;
+          full?: boolean;
           expires?: string;
           open: boolean;
         },
       ) => {
         try {
+          // Full-vault grant: a glob-safe affordance for "give this person the
+          // whole vault" so admins never have to quote a `*` (an unquoted glob
+          // expands to local filenames and instantly fails the one-prefix
+          // check). Maps to the single `*` wildcard grant, which the server
+          // coalesces to one policy entry — sidestepping the per-prefix STS
+          // session-policy budget. Defaults to write permission.
+          if (opts.full) {
+            if (opts.with === undefined) {
+              console.error(
+                chalk.red(
+                  "--full grants whole-vault access to a principal and requires --with <principal>.",
+                ),
+              );
+              process.exit(1);
+            }
+            if (paths && paths.length > 0) {
+              console.error(
+                chalk.red(
+                  "--full grants the entire vault; do not also pass file paths.",
+                ),
+              );
+              process.exit(1);
+            }
+            await runDirectGrant({
+              prefix: "*",
+              principal: opts.with,
+              permission: opts.permission ?? "write",
+              companySlug: files.opts().company as string | undefined,
+              fullVault: true,
+            });
+            return;
+          }
+
           if (!paths || paths.length === 0) {
             console.error(
               chalk.red("usage: hq files share <paths...> [--with <principal>]"),
@@ -430,21 +468,39 @@ export function registerFilesCommand(program: Command): Command {
   files
     .command("delete <prefix>")
     .description(
-      "Delete vault objects under a prefix (bounded + scoped). Always previews the exact count first; prompts for confirmation unless --yes.",
+      "Delete vault objects under a prefix (bounded + scoped). Always previews the exact count first; prompts for confirmation unless --yes. Use --personal to target your own personal vault instead of a company.",
     )
     .option(
       "--dry-run",
       "List what WOULD be deleted without deleting anything",
     )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
     .option("-y, --yes", "Skip the confirmation prompt (for scripts)")
     .action(
-      async (prefix: string, opts: { dryRun?: boolean; yes?: boolean }) => {
+      async (
+        prefix: string,
+        opts: { dryRun?: boolean; yes?: boolean; personal?: boolean },
+      ) => {
         try {
+          const companySlug = files.opts().company as string | undefined;
+          const personal = opts.personal === true;
+          if (personal && companySlug) {
+            console.error(
+              chalk.red(
+                "Pass either --personal or --company, not both.",
+              ),
+            );
+            process.exit(1);
+          }
           await runFilesDelete({
             prefix,
             dryRun: opts.dryRun === true,
             yes: opts.yes === true,
-            companySlug: files.opts().company as string | undefined,
+            personal,
+            companySlug,
           });
         } catch (err) {
           console.error(
@@ -472,6 +528,12 @@ interface DirectGrantParams {
   principal: string;
   permission: string | undefined;
   companySlug: string | undefined;
+  /**
+   * Set by the `--full` affordance: the grant targets the whole vault (the
+   * `*` wildcard prefix). Only affects the success message wording — the
+   * request shape is identical to any other prefix grant.
+   */
+  fullVault?: boolean;
 }
 
 async function runDirectGrant(params: DirectGrantParams): Promise<void> {
@@ -572,9 +634,17 @@ async function runDirectGrant(params: DirectGrantParams): Promise<void> {
   };
   const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
   const verb = autoCreated ? "Created ACL and granted" : "Granted";
-  console.log(
-    chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
-  );
+  if (params.fullVault) {
+    console.log(
+      chalk.green(
+        `${verb} ${params.permission} on the ENTIRE vault to ${principalLabel}`,
+      ),
+    );
+  } else {
+    console.log(
+      chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`),
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -731,10 +801,16 @@ function realConfirm(message: string): Promise<boolean> {
 /**
  * POST /v1/files/delete. Throws FilesDeleteHttpError on any non-2xx so the one
  * caller renders a single consistent error path.
+ *
+ * Scope is EITHER a company vault (`companyUid` set) OR the caller's personal
+ * vault (`personal: true`). For the personal case the server resolves the target
+ * person + bucket from the authenticated caller — we send NO uid, just the
+ * `personal` flag — so there is nothing for the client to get wrong or spoof.
  */
 async function callDeleteEndpoint(params: {
   token: string;
-  companyUid: string;
+  companyUid?: string;
+  personal?: boolean;
   prefix: string;
   dryRun: boolean;
 }): Promise<FilesDeleteResponse> {
@@ -742,11 +818,17 @@ async function callDeleteEndpoint(params: {
     token: params.token,
     path: "/v1/files/delete",
     method: "POST",
-    body: {
-      company: params.companyUid,
-      prefix: params.prefix,
-      dryRun: params.dryRun,
-    },
+    body: params.personal
+      ? {
+          personal: true,
+          prefix: params.prefix,
+          dryRun: params.dryRun,
+        }
+      : {
+          company: params.companyUid,
+          prefix: params.prefix,
+          dryRun: params.dryRun,
+        },
   });
   if (!res.ok) {
     const body = (await res.json().catch(() => ({}))) as Record<string, string>;
@@ -763,6 +845,8 @@ interface RunFilesDeleteParams {
   prefix: string;
   dryRun: boolean;
   yes: boolean;
+  /** Target the caller's personal vault instead of a company vault. */
+  personal?: boolean;
   companySlug: string | undefined;
 }
 
@@ -844,7 +928,14 @@ export async function runFilesDelete(
   }
 
   const token = await ensureCognitoToken();
-  const companyUid = await getCompanyUid(token, params.companySlug);
+  // Personal scope resolves the vault server-side from the caller's identity —
+  // no company to look up. Company scope resolves the companyUid as before.
+  const companyUid = params.personal
+    ? undefined
+    : await getCompanyUid(token, params.companySlug);
+  const scopeArgs = params.personal
+    ? { personal: true as const }
+    : { companyUid };
 
   // 1. Always preview first — this is how we print the EXACT key count before
   //    deleting anything (and the whole behavior of --dry-run).
@@ -852,7 +943,7 @@ export async function runFilesDelete(
   try {
     preview = await callDeleteEndpoint({
       token,
-      companyUid,
+      ...scopeArgs,
       prefix: normalized,
       dryRun: true,
     });
@@ -904,7 +995,9 @@ export async function runFilesDelete(
 
   if (!params.yes) {
     const ok = await confirm(
-      `Delete ${preview.matched} ${noun}? This removes them from the shared vault for everyone.`,
+      params.personal
+        ? `Delete ${preview.matched} ${noun}? This removes them from your personal vault.`
+        : `Delete ${preview.matched} ${noun}? This removes them from the shared vault for everyone.`,
     );
     if (!ok) {
       console.log(chalk.dim("Aborted — nothing was deleted."));
@@ -917,7 +1010,7 @@ export async function runFilesDelete(
   try {
     result = await callDeleteEndpoint({
       token,
-      companyUid,
+      ...scopeArgs,
       prefix: normalized,
       dryRun: false,
     });