@indigoai-us/hq-cli 5.60.0 → 5.62.0

package/src/index.ts

@@ -1,283 +1,20 @@
 #!/usr/bin/env node
 
-/**
- * HQ CLI - Module management, package management, and cloud sync for HQ
- */
-
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
-import { Command } from "commander";
-import { initSentry, Sentry } from "./sentry.js";
-import { registerAddCommand } from "./commands/add.js";
-import { registerSyncCommand } from "./commands/sync.js";
-import { registerListCommand } from "./commands/list.js";
-import { registerUpdateCommand } from "./commands/update.js";
-import { registerCloudCommands } from "./commands/cloud.js";
-import { registerSyncModeCommand } from "./commands/sync-mode.js";
-import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
-import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
-import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
-import { registerLoginCommand } from "./commands/login.js";
-import { registerLogoutCommand } from "./commands/logout.js";
-import { registerWhoamiCommand } from "./commands/whoami.js";
-import { registerOnboardCommand } from "./commands/onboard.js";
-import { registerPackageInstallCommand } from "./commands/pkg-install.js";
-import { registerPackageRemoveCommand } from "./commands/pkg-remove.js";
-import { registerPackageUpdateCommand } from "./commands/pkg-update.js";
-import { registerPackageListCommand } from "./commands/pkg-list.js";
-import { registerPacksCommand } from "./commands/packs.js";
-import { registerPublishCommand } from "./commands/publish.js";
-import { registerCreatorsCommand } from "./commands/creators.js";
-import { registerTeamSyncCommand } from "./commands/team-sync.js";
-import { registerAuthCommands } from "./commands/auth.js";
-import { registerApiKeysCommand } from "./commands/api-keys.js";
-import { registerSecretsCommand } from "./commands/secrets.js";
-import { registerRunCommand } from "./commands/run.js";
-import { registerGroupsCommand } from "./commands/groups.js";
-import { registerGroupGrantsCommand } from "./commands/group-grants.js";
-import { registerFilesCommand } from "./commands/files.js";
-import { registerFilesBrowseCommands } from "./commands/files-browse.js";
-import { registerMembersCommand } from "./commands/members.js";
-import { registerPeopleCommand } from "./commands/people.js";
-import { registerDmCommand } from "./commands/dm.js";
-import { registerChannelsCommand } from "./commands/channels.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 { registerReindexCommand } from "./commands/reindex.js";
-import { registerRescueCommand } from "./commands/rescue.js";
-import { registerMcpCommand } from "./commands/mcp-status.js";
-import { registerCrmCommand } from "./commands/crm.js";
-import { registerCompanyCommand } from "./commands/company.js";
-import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
-import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
-import { isEpipe } from "./utils/epipe.js";
-import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
-import {
-  maybeWarnNewVersion,
-  refreshVersionCache,
-} from "./utils/version-check.js";
-import {
-  enforceVersionGate,
-  shouldSkipGate,
-} from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 
-// Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
-// the pipe early. This covers the ASYNC path — an 'error' event emitted on the
-// stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
-// console.log inside a command) is handled in the top-level catch below; both
-// share `isEpipe` (HQ-6B).
-const onPipeError = (err: NodeJS.ErrnoException): void => {
-  if (isEpipe(err)) {
-    process.exit(0);
-  }
-  throw err;
-};
-process.stdout.on("error", onPipeError);
-process.stderr.on("error", onPipeError);
-
-initSentry();
-maybeWarnNewVersion();
-
-const program = new Command();
-
-program
-  .name("hq")
-  .description("HQ management CLI — modules, packages, and cloud sync")
-  .version(CLI_VERSION);
-
-// Module management subcommand group
-const modulesCmd = program
-  .command("modules")
-  .description("Module management commands");
-
-registerAddCommand(modulesCmd);
-registerSyncCommand(modulesCmd);
-registerListCommand(modulesCmd);
-registerUpdateCommand(modulesCmd);
-
-// Package management subcommand group
-const packagesCmd = program
-  .command("packages")
-  .description("Package management commands");
-
-registerPackageInstallCommand(packagesCmd);
-registerPackageRemoveCommand(packagesCmd);
-registerPackageUpdateCommand(packagesCmd);
-registerPackageListCommand(packagesCmd);
-
-// Content-pack lifecycle (core/packages/hq-pack-*). Distinct from the registry
-// `packages` system above. Available as both `hq packages packs …` (grouped)
-// and `hq packs …` (top-level convenience).
-registerPacksCommand(packagesCmd);
-registerPacksCommand(program);
-
-// Top-level shortcuts for package commands
-// "hq install <slug>" = "hq packages install <slug>"
-// "hq remove <slug>"  = "hq packages remove <slug>"
-registerPackageInstallCommand(program);
-registerPackageRemoveCommand(program);
-
-// Marketplace publish (top-level — packer + authenticated upload, US-004)
-// "hq publish <skill-or-worker-path>" packages and submits a pack to the
-// marketplace via POST /v1/listings.
-registerPublishCommand(program);
-// `hq creators apply` — request verified-creator access (required to publish).
-registerCreatorsCommand(program);
-
-// Cloud sync subcommand group
-const syncCmd = program
-  .command("sync")
-  .description("Cloud sync commands — sync HQ to S3 for mobile access");
-
-registerCloudCommands(syncCmd);
-registerSyncModeCommand(syncCmd);
-registerSyncNarrowCommand(syncCmd);
-
-// Cloud provisioning subcommand group (entity + bucket + initial sync)
-// Distinct from `hq sync` which assumes provisioning has already happened.
-const cloudCmd = program
-  .command("cloud")
-  .description(
-    "Cloud commands — provision entities and manage cloud-backed companies",
-  );
-
-registerCloudProvisionCommands(cloudCmd);
-registerCloudDemoteCommands(cloudCmd);
-
-// Team commands (top-level)
-registerTeamSyncCommand(program);
-
-// Auth commands (top-level — Cognito OAuth)
-registerLoginCommand(program);
-registerLogoutCommand(program);
-registerWhoamiCommand(program);
-registerAuthCommands(program);
-
-// Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
-registerSecretsCommand(program);
-
-// API key management (subcommand group — hq api-keys create|list|revoke)
-registerApiKeysCommand(program);
-
-// Schema-driven dev runner — hq run [options] -- <cmd>
-registerRunCommand(program);
-
-// Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
-registerGroupsCommand(program);
-
-// Cross-company group grants (subcommand group —
-// hq group-grants grant|revoke|outbound|inbound)
-registerGroupGrantsCommand(program);
-
-// Files ACL management (subcommand group — hq files share|unshare|acl)
-// `registerFilesCommand` returns the `files` group so we can attach the
-// browse-vs-sync subcommands (`hq files browse`/`cat`) onto the same group.
-const filesCmd = registerFilesCommand(program);
-registerFilesBrowseCommands(filesCmd);
-
-// Membership management (subcommand group — hq members invite|list|revoke)
-registerMembersCommand(program);
-// People directory (subcommand group — hq people list|search|resolve), reading
-// the local companies/<co>/people store scoped to one company.
-registerPeopleCommand(program);
-registerDmCommand(program);
-registerChannelsCommand(program);
-
-// Onboarding (top-level — Cognito + vault-service provisioning)
-registerOnboardCommand(program);
-
-// Feedback (subcommand group — hq feedback bug|feature)
-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);
-
-// Skill/personal-overlay mirroring + workers-registry regen. Invoked by the
-// hq-core reindex hook shim (Stop / PostToolUse) and by sync()/rescue() after
-// they change on-disk sources. Keeps a `master-sync` alias for one release.
-// Implementation lives in @indigoai-us/hq-cloud.
-registerReindexCommand(program);
-
-// Drift-preserving HQ-core re-sync (top-level — `hq rescue`). CLI sibling of
-// the HQ Sync app's "Update / Restore" pill; drives the same replace-rescue.sh
-// shipped from @indigoai-us/hq-cloud.
-registerRescueCommand(program);
-
-// MCP pack observability (subcommand group — `hq mcp status`). Read-only
-// provenance-based status across BOTH Claude + Codex runtimes (reads `_hqPack`
-// off the configs, NOT linkStatus), with secret-redacted output + `--json`.
-registerMcpCommand(program);
-
-// Native CRM entity upsert (subcommand group — `hq crm entity upsert`). Wraps
-// POST /crm/entities (the ontology write gate) so an authenticated company
-// member can create/update canonical CRM entities in the company vault.
-registerCrmCommand(program);
+function isVersionRequest(argv: readonly string[]): boolean {
+  const args = argv.slice(2);
+  return args.length === 1 && (args[0] === "--version" || args[0] === "-V" || args[0] === "-v");
+}
 
-// Company settings (subcommand group — `hq company settings set`). Owner-only
-// toggles for crmEnabled / ontologyEnabled via PUT /company-settings.
-registerCompanyCommand(program);
+if (isVersionRequest(process.argv)) {
+  process.stdout.write(`${CLI_VERSION}\n`);
+} else {
+  const { runCli } = await import("./main.js");
+  await runCli();
+}
 
-(async () => {
-  try {
-    Sentry.addBreadcrumb({
-      category: "command",
-      message: sanitizeArgv(process.argv.slice(2)).join(" "),
-      level: "info",
-    });
-    // Hard version gate: ask hq-pro whether this CLI is below the floor and
-    // auto-update if so (exits the process on update). Skipped for inspection
-    // flags (`--version`, `--help`) so users debugging a broken install can
-    // still introspect what they have. Silent on any failure — never blocks
-    // the CLI on a flaky network or hq-pro hiccup. See `utils/version-gate.ts`.
-    if (!shouldSkipGate(process.argv)) {
-      await enforceVersionGate();
-    }
-    await program.parseAsync();
-  } catch (err) {
-    // A broken pipe (EPIPE) means the reader of `hq`'s output closed it early
-    // (`hq … | head`, `source <(hq …)`, a parent that exited). That is normal
-    // Unix behavior with no user-facing degradation — exit cleanly (0) and
-    // skip Sentry capture instead of shipping a fatal (HQ-6B). A synchronous
-    // `write EPIPE` thrown out of console.log lands here rather than on the
-    // stream 'error' listener above.
-    if (isEpipe(err)) {
-      process.exitCode = 0;
-    } else if (isInterceptedProcessExit(err)) {
-      // A security/audit FUZZ harness replaced `process.exit` with a throw so it
-      // can keep exercising the binary. Commander calling `process.exit` for
-      // normal CLI control flow (e.g. an unknown command → exit 1) then surfaces
-      // here as that synthetic marker. It is a test-harness artifact, NOT an
-      // hq-cli defect — a real user's `process.exit` just exits, so nothing is
-      // thrown or captured. Skip Sentry capture (no signal, no user-facing
-      // degradation) and preserve the intended non-zero exit (HQ-CLI-3).
-      process.exitCode = 1;
-    } else {
-      // A full disk / exhausted quota / read-only filesystem is the user's
-      // machine, not an HQ code defect. Surface a clear, actionable message and
-      // skip Sentry capture so one full disk doesn't flood the tracker with
-      // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
-      // to Sentry and still exit 1.
-      const envMsg = environmentalFsErrorMessage(err);
-      if (envMsg) {
-        process.stderr.write(`hq: ${envMsg}\n`);
-      } else {
-        Sentry.captureException(err);
-      }
-      process.exitCode = 1;
-    }
-  } finally {
-    // Release health: finalize the per-run session before the flush.
-    Sentry.endSession();
-    await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
-  }
-})();
+export const __test__ = { isVersionRequest };

package/src/lib/db/control-plane.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Control-plane client tests (US-009).
+ */
+
+import { describe, expect, it, vi } from "vitest";
+
+import { ControlPlaneDbClient } from "./control-plane.js";
+
+describe("ControlPlaneDbClient", () => {
+  it("provision success returns remote status without connection string", async () => {
+    const fetchImpl = vi.fn(async () => {
+      return new Response(
+        JSON.stringify({
+          ok: true,
+          companyUid: "cmp_x",
+          companySlug: "x",
+          engineId: "aurora-dsql",
+          resourceArn: "arn:aws:dsql:us-east-1:1:cluster/x",
+          region: "us-east-1",
+          status: "ready",
+          secretRef: "ssm:/hq/cmp_x/secrets/DB/REMOTE/X",
+          idempotent: false,
+        }),
+        { status: 200 },
+      );
+    }) as unknown as typeof fetch;
+
+    const client = new ControlPlaneDbClient({
+      baseUrl: "https://api.example",
+      getAccessToken: async () => "tok",
+      fetchImpl,
+    });
+
+    const result = await client.provision({
+      companyUid: "cmp_x",
+      companySlug: "x",
+    });
+    expect(result.status).toBe("ready");
+    expect(JSON.stringify(result)).not.toMatch(/postgres:\/\//i);
+  });
+
+  it("403 surfaces actionable error without secret", async () => {
+    const fetchImpl = vi.fn(async () => {
+      return new Response(JSON.stringify({ error: "Forbidden" }), {
+        status: 403,
+      });
+    }) as unknown as typeof fetch;
+
+    const client = new ControlPlaneDbClient({
+      baseUrl: "https://api.example",
+      getAccessToken: async () => "tok",
+      fetchImpl,
+    });
+
+    await expect(
+      client.provision({ companyUid: "cmp_x", companySlug: "x" }),
+    ).rejects.toThrow(/Forbidden|403/);
+  });
+});

package/src/lib/db/control-plane.ts

@@ -0,0 +1,113 @@
+/**
+ * Control-plane client for remote vault DB (US-009).
+ * Injectable fetch for tests — never logs response bodies that might hold secrets.
+ */
+
+export interface RemoteProvisionResponse {
+  ok: boolean;
+  companyUid: string;
+  companySlug: string;
+  engineId: string;
+  resourceArn: string;
+  region: string;
+  status: string;
+  secretRef: string;
+  idempotent: boolean;
+}
+
+export interface RemoteStatusResponse {
+  companyUid: string;
+  companySlug?: string;
+  remote: {
+    engineId: string;
+    resourceArn: string;
+    region: string;
+    status: string;
+    secretRef: string;
+  } | null;
+}
+
+export interface ControlPlaneClientOptions {
+  baseUrl: string;
+  /** Bearer access token */
+  getAccessToken: () => Promise<string>;
+  fetchImpl?: typeof fetch;
+}
+
+function assertNoPostgresUrl(label: string, text: string): void {
+  if (/postgres:\/\//i.test(text) || /postgresql:\/\//i.test(text)) {
+    throw new Error(
+      `${label}: control plane returned a connection string (refusing to surface)`,
+    );
+  }
+}
+
+export class ControlPlaneDbClient {
+  private readonly baseUrl: string;
+  private readonly getAccessToken: () => Promise<string>;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ControlPlaneClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.getAccessToken = opts.getAccessToken;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  async provision(input: {
+    companyUid: string;
+    companySlug: string;
+    region?: string;
+  }): Promise<RemoteProvisionResponse> {
+    const token = await this.getAccessToken();
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/db/provision`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(input),
+    });
+    const text = await res.text();
+    assertNoPostgresUrl("provision", text);
+    if (!res.ok) {
+      let msg = `provision failed (${res.status})`;
+      let code: string | undefined;
+      try {
+        const j = JSON.parse(text) as { error?: string; code?: string };
+        if (j.error) msg = j.error;
+        if (j.code) code = j.code;
+      } catch {
+        /* keep */
+      }
+      const err = new Error(msg) as Error & { status?: number; code?: string };
+      err.status = res.status;
+      if (code) err.code = code;
+      throw err;
+    }
+    return JSON.parse(text) as RemoteProvisionResponse;
+  }
+
+  async status(companyUid: string): Promise<RemoteStatusResponse> {
+    const token = await this.getAccessToken();
+    const url = `${this.baseUrl}/v1/db/status?companyUid=${encodeURIComponent(companyUid)}`;
+    const res = await this.fetchImpl(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const text = await res.text();
+    assertNoPostgresUrl("status", text);
+    if (!res.ok) {
+      let msg = `status failed (${res.status})`;
+      try {
+        const j = JSON.parse(text) as { error?: string };
+        if (j.error) msg = j.error;
+      } catch {
+        /* keep */
+      }
+      const err = new Error(msg) as Error & { status?: number };
+      err.status = res.status;
+      throw err;
+    }
+    return JSON.parse(text) as RemoteStatusResponse;
+  }
+}

package/src/lib/db/local.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Local vault SQLite open/status tests (vault-databases US-003).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  ensureAndStatusLocalDb,
+  openLocalDb,
+  readMigrationHead,
+} from "./local.js";
+import { resolveLocalDbPath } from "./paths.js";
+
+const tempHomes: string[] = [];
+
+function makeTempHome(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-db-local-"));
+  tempHomes.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempHomes.length > 0) {
+    const dir = tempHomes.pop();
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("openLocalDb / ensureAndStatusLocalDb", () => {
+  it("creates SQLite at canonical path with WAL on first open", () => {
+    const home = makeTempHome();
+    const status = ensureAndStatusLocalDb("fixture-co", { home });
+    const dbPath = resolveLocalDbPath("fixture-co", { home });
+
+    expect(status.healthy).toBe(true);
+    expect(status.tier).toBe("local");
+    expect(status.company).toBe("fixture-co");
+    expect(status.path).toBe(dbPath);
+    expect(status.journalMode?.toLowerCase()).toBe("wal");
+    expect(fs.existsSync(dbPath)).toBe(true);
+    expect(status.schemaVersion).toBeNull();
+    // Never a remote URL
+    expect(JSON.stringify(status)).not.toMatch(/postgres:\/\//i);
+  });
+
+  it("second open is idempotent (file survives, no wipe)", () => {
+    const home = makeTempHome();
+    const dbPath = resolveLocalDbPath("idem", { home });
+
+    const db1 = openLocalDb("idem", { home });
+    db1.exec("CREATE TABLE smoke (id INTEGER PRIMARY KEY, v TEXT)");
+    db1.prepare("INSERT INTO smoke (v) VALUES (?)").run("keep-me");
+    db1.close();
+
+    const stat1 = fs.statSync(dbPath);
+    const status2 = ensureAndStatusLocalDb("idem", { home });
+    expect(status2.healthy).toBe(true);
+
+    const db2 = openLocalDb("idem", { home });
+    const row = db2.prepare("SELECT v FROM smoke WHERE id = 1").get() as {
+      v: string;
+    };
+    expect(row.v).toBe("keep-me");
+    db2.close();
+
+    const stat2 = fs.statSync(dbPath);
+    // Size should not collapse (recreate would lose data / shrink oddly)
+    expect(stat2.size).toBeGreaterThanOrEqual(stat1.size);
+  });
+
+  it("readMigrationHead returns null without ledger table", () => {
+    const home = makeTempHome();
+    const db = openLocalDb("noleger", { home });
+    expect(readMigrationHead(db)).toBeNull();
+    db.close();
+  });
+});

package/src/lib/db/local.ts

@@ -0,0 +1,148 @@
+/**
+ * Local vault SQLite open/create (C1).
+ *
+ * File lives at ~/.hq/db/{company}/vault.db with WAL journal mode.
+ * Never returns or logs remote connection strings.
+ */
+
+import fs from "node:fs";
+
+import Database from "better-sqlite3";
+
+import {
+  ensureLocalDbDir,
+  resolveLocalDbPath,
+  type LocalDbPathEnv,
+} from "./paths.js";
+
+export type LocalDb = Database.Database;
+
+export interface OpenLocalDbOptions extends LocalDbPathEnv {
+  /** When true, do not create the file if missing (throws). Default false. */
+  readonly?: boolean;
+}
+
+export interface LocalDbStatus {
+  company: string;
+  tier: "local";
+  path: string;
+  exists: boolean;
+  healthy: boolean;
+  journalMode: string | null;
+  /** Migration ledger head when present; null if ledger not initialized. */
+  schemaVersion: string | null;
+  /** Fingerprint of path for logs that prefer not to echo full home paths. */
+  pathFingerprint: string;
+}
+
+const MIGRATIONS_TABLE = "hq_schema_migrations";
+
+/**
+ * Short non-reversible fingerprint of a path (for status display).
+ * Not a secret — just avoids dumping full home paths when preferred.
+ */
+export function fingerprintPath(filePath: string): string {
+  let h = 2166136261;
+  for (let i = 0; i < filePath.length; i++) {
+    h ^= filePath.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return `fp_${(h >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+/**
+ * Open (and create if missing) the company local vault DB with WAL mode.
+ * Idempotent: reopening an existing file does not recreate or wipe it.
+ */
+export function openLocalDb(
+  companySlug: string,
+  opts?: OpenLocalDbOptions,
+): LocalDb {
+  const dbPath = resolveLocalDbPath(companySlug, opts);
+  const exists = fs.existsSync(dbPath);
+
+  if (!exists) {
+    if (opts?.readonly) {
+      throw new Error(
+        `local vault DB not found for company ${JSON.stringify(companySlug)} at ${dbPath}`,
+      );
+    }
+    ensureLocalDbDir(companySlug, opts);
+  }
+
+  const db = new Database(dbPath);
+  // WAL for concurrent readers; safe for agent/CLI workloads.
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  return db;
+}
+
+/**
+ * Read migration head from platform ledger if the table exists.
+ */
+export function readMigrationHead(db: LocalDb): string | null {
+  try {
+    const row = db
+      .prepare(
+        `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
+      )
+      .get(MIGRATIONS_TABLE) as { name?: string } | undefined;
+    if (!row?.name) return null;
+
+    const head = db
+      .prepare(
+        `SELECT version FROM ${MIGRATIONS_TABLE} ORDER BY version DESC LIMIT 1`,
+      )
+      .get() as { version?: string } | undefined;
+    return head?.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure local DB exists (create if needed), report status, close handle.
+ * Safe for CLI status: never includes connection strings.
+ */
+export function ensureAndStatusLocalDb(
+  companySlug: string,
+  opts?: LocalDbPathEnv,
+): LocalDbStatus {
+  const dbPath = resolveLocalDbPath(companySlug, opts);
+  const db = openLocalDb(companySlug, opts);
+  try {
+    const journalMode = String(db.pragma("journal_mode", { simple: true }));
+    const schemaVersion = readMigrationHead(db);
+    // Touch a trivial query to prove the handle is healthy.
+    db.prepare("SELECT 1 AS ok").get();
+
+    return {
+      company: companySlug.trim().toLowerCase(),
+      tier: "local",
+      path: dbPath,
+      exists: true,
+      healthy: true,
+      journalMode,
+      schemaVersion,
+      pathFingerprint: fingerprintPath(dbPath),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Format status for CLI stdout (no secrets).
+ */
+export function formatLocalDbStatus(status: LocalDbStatus): string {
+  const lines = [
+    `company: ${status.company}`,
+    `tier: ${status.tier}`,
+    `healthy: ${status.healthy ? "yes" : "no"}`,
+    `path: ${status.path}`,
+    `pathFingerprint: ${status.pathFingerprint}`,
+    `journalMode: ${status.journalMode ?? "unknown"}`,
+    `schemaVersion: ${status.schemaVersion ?? "(none)"}`,
+  ];
+  return lines.join("\n");
+}