@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/crm.ts

@@ -1,236 +0,0 @@
-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/db-migrate.ts

@@ -1,55 +0,0 @@
-/**
- * hq db migrate — apply vault text migrations to local SQLite (US-005).
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import path from "node:path";
-
-import { migrateLocalDb } from "../lib/db/migrate.js";
-
-const DEFAULT_HQ_ROOT = process.env.HQ_ROOT || path.resolve(process.cwd());
-
-export function registerDbMigrateCommand(db: Command): void {
-  db.command("migrate")
-    .description(
-      "Apply pending vault text migrations (companies/{co}/db/migrations/*.sql) to the local DB",
-    )
-    .requiredOption("--company <slug>", "Company slug (tenant scope; required)")
-    .option(
-      "--hq-root <path>",
-      "HQ tree root containing companies/ (default: cwd or HQ_ROOT)",
-      DEFAULT_HQ_ROOT,
-    )
-    .option("--home <path>", "Override home for local DB root (tests)")
-    .action(
-      (opts: { company: string; hqRoot?: string; home?: string }) => {
-        try {
-          const company = String(opts.company ?? "").trim();
-          if (!company) {
-            console.error(chalk.red("Error: --company is required"));
-            process.exitCode = 1;
-            return;
-          }
-
-          const result = migrateLocalDb({
-            company,
-            hqRoot: opts.hqRoot || DEFAULT_HQ_ROOT,
-            ...(opts.home ? { home: opts.home } : {}),
-          });
-
-          console.log(`company: ${result.company}`);
-          console.log(`migrationsDir: ${result.migrationsDir}`);
-          console.log(`applied: ${result.applied.length ? result.applied.join(", ") : "(none)"}`);
-          console.log(`skipped: ${result.skipped.length ? result.skipped.join(", ") : "(none)"}`);
-          console.log(`schemaVersion: ${result.head ?? "(none)"}`);
-        } catch (error) {
-          console.error(
-            chalk.red("Error:"),
-            error instanceof Error ? error.message : "Unknown error",
-          );
-          process.exitCode = 1;
-        }
-      },
-    );
-}

package/src/commands/db-provision.ts

@@ -1,114 +0,0 @@
-/**
- * hq db provision — request remote vault DB binding (US-009).
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-
-import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
-import {
-  DEFAULT_VAULT_API_URL,
-  ensureCognitoToken,
-} from "../utils/cognito-session.js";
-import { getCompanyUid } from "../utils/vault-api.js";
-
-export interface DbProvisionCommandDeps {
-  resolveCompany: (slug: string) => Promise<{ companyUid: string; companySlug: string }>;
-  getAccessToken: () => Promise<string>;
-  apiBaseUrl: string;
-  fetchImpl?: typeof fetch;
-}
-
-const defaultDeps = (): DbProvisionCommandDeps => ({
-  async resolveCompany(slug) {
-    if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-      return { companyUid: `cmp_${slug}`, companySlug: slug };
-    }
-    const token = await ensureCognitoToken({ interactive: false });
-    const companyUid = await getCompanyUid(token, slug);
-    return { companyUid, companySlug: slug.trim().toLowerCase() };
-  },
-  async getAccessToken() {
-    if (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1") {
-      return "mock-token";
-    }
-    return ensureCognitoToken({ interactive: false });
-  },
-  apiBaseUrl:
-    process.env.HQ_VAULT_API_URL ||
-    process.env.HQ_API_BASE_URL ||
-    process.env.HQ_CLOUD_API_URL ||
-    DEFAULT_VAULT_API_URL,
-});
-
-export function registerDbProvisionCommand(
-  db: Command,
-  depsFactory: () => DbProvisionCommandDeps = defaultDeps,
-): void {
-  db.command("provision")
-    .description(
-      "Provision (or re-bind) the company remote vault DB via HQ control plane (Team plan)",
-    )
-    .requiredOption("--company <slug>", "Company slug")
-    .option("--region <region>", "AWS region", "us-east-1")
-    .action(async (opts: { company: string; region?: string }) => {
-      try {
-        const deps = depsFactory();
-        const company = String(opts.company ?? "").trim();
-        if (!company) {
-          console.error(chalk.red("Error: --company is required"));
-          process.exitCode = 1;
-          return;
-        }
-
-        const resolved = await deps.resolveCompany(company);
-        const client = new ControlPlaneDbClient({
-          baseUrl: deps.apiBaseUrl,
-          getAccessToken: deps.getAccessToken,
-          fetchImpl: deps.fetchImpl,
-        });
-
-        const result = await client.provision({
-          companyUid: resolved.companyUid,
-          companySlug: resolved.companySlug,
-          region: opts.region,
-        });
-
-        console.log(`company: ${result.companySlug}`);
-        console.log(`remote: ${result.status}`);
-        console.log(`engine: ${result.engineId}`);
-        console.log(`region: ${result.region}`);
-        console.log(`resourceArn: ${result.resourceArn}`);
-        console.log(`secretRef: ${result.secretRef}`);
-        console.log(`idempotent: ${result.idempotent ? "yes" : "no"}`);
-      } catch (error) {
-        const msg = error instanceof Error ? error.message : "Unknown error";
-        const status = (error as { status?: number }).status;
-        if (status === 402 || /PLAN_REQUIRED|Team plan|\$500/i.test(msg)) {
-          console.error(
-            chalk.red("Error:"),
-            "Remote vault DB requires the HQ Team plan ($500/mo).",
-          );
-          console.error(
-            chalk.dim(
-              "Local databases still work: hq db status|sql|migrate — no Team plan required.",
-            ),
-          );
-        } else if (status === 404 || /Unknown route|Not Found/i.test(msg)) {
-          console.error(
-            chalk.red("Error:"),
-            "Remote DB control plane is not available yet (routes not deployed).",
-          );
-          console.error(
-            chalk.dim("Local hq db status|sql|migrate still work offline."),
-          );
-        } else {
-          console.error(chalk.red("Error:"), msg);
-        }
-        if (/postgres:\/\//i.test(msg)) {
-          console.error(chalk.red("Error: refused to print secret material"));
-        }
-        process.exitCode = 1;
-      }
-    });
-}

package/src/commands/db-sql.ts

@@ -1,124 +0,0 @@
-/**
- * hq db sql — run SQL against the company local vault DB (US-004).
- *
- * Default is read-only. Prefer `hq db migrate` for schema changes.
- * Never prints remote connection strings.
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import fs from "node:fs";
-
-import { runRemoteSql } from "../lib/db/remote-sql.js";
-import { formatSqlResult, runLocalSql } from "../lib/db/sql.js";
-
-function readSqlArg(sqlArgs: string[], stdinFlag: boolean): string {
-  if (stdinFlag || sqlArgs.length === 0) {
-    if (process.stdin.isTTY && sqlArgs.length === 0) {
-      throw new Error(
-        "SQL required: pass as arguments after -- or pipe via stdin",
-      );
-    }
-    return fs.readFileSync(0, "utf8");
-  }
-  return sqlArgs.join(" ");
-}
-
-export function registerDbSqlCommand(db: Command): void {
-  db.command("sql")
-    .description(
-      "Run SQL against the company vault DB (local default; --remote for secrets-injected remote; read-only by default)",
-    )
-    .requiredOption("--company <slug>", "Company slug (tenant scope; required)")
-    .option("--write", "Allow write/DDL statements (discouraged for ad-hoc DDL)", false)
-    .option(
-      "--remote",
-      "Use remote tier via vault-bound credentials (not auto-replicated with local)",
-      false,
-    )
-    .option(
-      "--db-path <path>",
-      "Dangerous: open a non-canonical DB path (denied unless --allow-cross-company-path)",
-    )
-    .option(
-      "--allow-cross-company-path",
-      "Dangerous: permit --db-path outside this company's canonical local DB",
-      false,
-    )
-    .option("--format <fmt>", "Output format: jsonl | table", "jsonl")
-    .option("--home <path>", "Override home for local DB root (tests)")
-    .option("--stdin", "Read SQL from stdin", false)
-    .argument("[sql...]", "SQL statement (or use --stdin / pipe)")
-    .action(
-      async (
-        sqlParts: string[],
-        opts: {
-          company: string;
-          write?: boolean;
-          remote?: boolean;
-          dbPath?: string;
-          allowCrossCompanyPath?: boolean;
-          format?: string;
-          home?: string;
-          stdin?: boolean;
-        },
-      ) => {
-        try {
-          const company = String(opts.company ?? "").trim();
-          if (!company) {
-            console.error(chalk.red("Error: --company is required"));
-            process.exitCode = 1;
-            return;
-          }
-
-          const sql = readSqlArg(sqlParts, !!opts.stdin).trim();
-          const format =
-            opts.format === "table" ? ("table" as const) : ("jsonl" as const);
-
-          if (opts.remote) {
-            // Local and remote are not auto-replicated (v1 limitation).
-            const remoteResult = await runRemoteSql({
-              company,
-              sql,
-              getConnectionConfig: async () => {
-                throw new Error("no remote binding");
-              },
-            });
-            console.log(
-              formatSqlResult(
-                {
-                  columns:
-                    remoteResult.rows[0]
-                      ? Object.keys(remoteResult.rows[0])
-                      : [],
-                  rows: remoteResult.rows,
-                  changes: 0,
-                  readonly: true,
-                },
-                format,
-              ),
-            );
-            return;
-          }
-
-          const result = runLocalSql({
-            company,
-            sql,
-            write: !!opts.write,
-            dbPathOverride: opts.dbPath,
-            allowCrossCompanyPath: !!opts.allowCrossCompanyPath,
-            format,
-            ...(opts.home ? { home: opts.home } : {}),
-          });
-
-          console.log(formatSqlResult(result, format));
-        } catch (error) {
-          console.error(
-            chalk.red("Error:"),
-            error instanceof Error ? error.message : "Unknown error",
-          );
-          process.exitCode = 1;
-        }
-      },
-    );
-}

package/src/commands/db-status.ts

@@ -1,108 +0,0 @@
-/**
- * hq db status — ensure local vault DB exists and report health.
- * Optionally reports remote tier when control plane returns a binding (US-009).
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-
-import { ControlPlaneDbClient } from "../lib/db/control-plane.js";
-import {
-  ensureAndStatusLocalDb,
-  formatLocalDbStatus,
-} from "../lib/db/local.js";
-
-export function registerDbStatusCommand(db: Command): void {
-  db.command("status")
-    .description(
-      "Show local (and remote when bound) vault DB status; auto-creates local SQLite if missing",
-    )
-    .requiredOption(
-      "--company <slug>",
-      "Company slug (tenant scope; required)",
-    )
-    .option(
-      "--home <path>",
-      "Override home directory for local DB root (tests / advanced only)",
-    )
-    .option(
-      "--remote",
-      "Also query control plane for remote tier status (requires auth)",
-      false,
-    )
-    .option("--company-uid <uid>", "Company uid for remote status (with --remote)")
-    .action(
-      async (opts: {
-        company: string;
-        home?: string;
-        remote?: boolean;
-        companyUid?: string;
-      }) => {
-        try {
-          const company = String(opts.company ?? "").trim();
-          if (!company) {
-            console.error(chalk.red("Error: --company is required"));
-            process.exitCode = 1;
-            return;
-          }
-
-          const status = ensureAndStatusLocalDb(
-            company,
-            opts.home ? { home: opts.home } : undefined,
-          );
-
-          // Never print remote connection material.
-          console.log(formatLocalDbStatus(status));
-
-          if (opts.remote) {
-            const { DEFAULT_VAULT_API_URL, ensureCognitoToken } = await import(
-              "../utils/cognito-session.js"
-            );
-            const { getCompanyUid } = await import("../utils/vault-api.js");
-            try {
-              const token =
-                process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
-                  ? "mock-token"
-                  : await ensureCognitoToken({ interactive: false });
-              const companyUid =
-                opts.companyUid ||
-                (process.env.HQ_DB_MOCK_CONTROL_PLANE === "1"
-                  ? `cmp_${company}`
-                  : await getCompanyUid(token, company));
-              const baseUrl =
-                process.env.HQ_VAULT_API_URL ||
-                process.env.HQ_API_BASE_URL ||
-                process.env.HQ_CLOUD_API_URL ||
-                DEFAULT_VAULT_API_URL;
-              const client = new ControlPlaneDbClient({
-                baseUrl,
-                getAccessToken: async () => token,
-              });
-              const remote = await client.status(companyUid);
-              if (!remote.remote) {
-                console.log("remote: (none)");
-              } else {
-                console.log(`remote: ${remote.remote.status}`);
-                console.log(`remoteEngine: ${remote.remote.engineId}`);
-                console.log(`remoteRegion: ${remote.remote.region}`);
-                console.log(`remoteResourceArn: ${remote.remote.resourceArn}`);
-              }
-            } catch (e) {
-              const msg = e instanceof Error ? e.message : "remote status failed";
-              console.log(`remote: error (${msg})`);
-            }
-          }
-
-          if (!status.healthy) {
-            process.exitCode = 1;
-          }
-        } catch (error) {
-          console.error(
-            chalk.red("Error:"),
-            error instanceof Error ? error.message : "Unknown error",
-          );
-          process.exitCode = 1;
-        }
-      },
-    );
-}

package/src/commands/db.ts

@@ -1,26 +0,0 @@
-/**
- * hq db — vault database commands (local + remote tiers).
- */
-
-import { Command } from "commander";
-
-import { registerDbMigrateCommand } from "./db-migrate.js";
-import { registerDbProvisionCommand } from "./db-provision.js";
-import { registerDbSqlCommand } from "./db-sql.js";
-import { registerDbStatusCommand } from "./db-status.js";
-
-/**
- * Register the `hq db` command group and its subcommands.
- */
-export function registerDbCommand(program: Command): void {
-  const db = program
-    .command("db")
-    .description(
-      "Vault databases — local SQLite per company and HQ-managed remote Postgres-class DBs",
-    );
-
-  registerDbStatusCommand(db);
-  registerDbSqlCommand(db);
-  registerDbMigrateCommand(db);
-  registerDbProvisionCommand(db);
-}