@indigoai-us/hq-cli 5.77.13 → 5.78.0

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

@@ -1,112 +0,0 @@
-/**
- * Unit tests for local vault DB path helpers (vault-databases US-002).
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import { afterEach, describe, expect, it } from "vitest";
-
-import {
-  LOCAL_DB_IGNORE_PATTERNS,
-  LOCAL_VAULT_DB_FILENAME,
-  describeLocalDbIgnoreRules,
-  ensureLocalDbDir,
-  normalizeCompanySlugForLocalDb,
-  resolveLocalDbDir,
-  resolveLocalDbPath,
-  resolveLocalDbRoot,
-} from "./paths.js";
-
-const tempHomes: string[] = [];
-
-function makeTempHome(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-db-paths-"));
-  tempHomes.push(dir);
-  return dir;
-}
-
-afterEach(() => {
-  while (tempHomes.length > 0) {
-    const dir = tempHomes.pop();
-    if (dir) {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  }
-});
-
-describe("resolveLocalDbPath", () => {
-  it("resolves indigo under documented root ending with vault.db", () => {
-    const home = makeTempHome();
-    const p = resolveLocalDbPath("indigo", { home });
-    expect(p).toBe(path.join(home, ".hq", "db", "indigo", LOCAL_VAULT_DB_FILENAME));
-    expect(p.endsWith(path.join("indigo", "vault.db"))).toBe(true);
-    expect(p.startsWith(resolveLocalDbRoot({ home }))).toBe(true);
-  });
-
-  it("resolves a second company slug (acme) distinctly", () => {
-    const home = makeTempHome();
-    const indigo = resolveLocalDbPath("indigo", { home });
-    const acme = resolveLocalDbPath("acme", { home });
-    expect(acme).toBe(path.join(home, ".hq", "db", "acme", "vault.db"));
-    expect(indigo).not.toBe(acme);
-    expect(path.dirname(indigo)).not.toBe(path.dirname(acme));
-  });
-
-  it("normalizes slug casing to lowercase", () => {
-    const home = makeTempHome();
-    expect(resolveLocalDbPath("Indigo", { home })).toBe(
-      resolveLocalDbPath("indigo", { home }),
-    );
-  });
-});
-
-describe("normalizeCompanySlugForLocalDb", () => {
-  it("rejects empty and path-traversal slugs", () => {
-    expect(() => normalizeCompanySlugForLocalDb("")).toThrow(/required/i);
-    expect(() => normalizeCompanySlugForLocalDb("../etc")).toThrow(/invalid/i);
-    expect(() => normalizeCompanySlugForLocalDb("a/b")).toThrow(/invalid/i);
-  });
-});
-
-describe("ensureLocalDbDir", () => {
-  it("creates parent directories for a new company slug and is writable", () => {
-    const home = makeTempHome();
-    const dir = ensureLocalDbDir("newco", { home });
-    expect(fs.existsSync(dir)).toBe(true);
-    expect(fs.statSync(dir).isDirectory()).toBe(true);
-    // Writable: can create a probe file then remove it (no secrets left).
-    const probe = path.join(dir, ".write-probe");
-    fs.writeFileSync(probe, "ok", { mode: 0o600 });
-    expect(fs.readFileSync(probe, "utf8")).toBe("ok");
-    fs.unlinkSync(probe);
-    // Does not create the .db file itself.
-    expect(fs.existsSync(resolveLocalDbPath("newco", { home }))).toBe(false);
-  });
-
-  it("is idempotent when the directory already exists", () => {
-    const home = makeTempHome();
-    const first = ensureLocalDbDir("acme", { home });
-    const second = ensureLocalDbDir("acme", { home });
-    expect(first).toBe(second);
-    expect(fs.existsSync(first)).toBe(true);
-  });
-});
-
-describe("resolveLocalDbDir / ignore docs", () => {
-  it("dir is parent of vault.db path", () => {
-    const home = makeTempHome();
-    expect(resolveLocalDbDir("indigo", { home })).toBe(
-      path.dirname(resolveLocalDbPath("indigo", { home })),
-    );
-  });
-
-  it("documents *.db and .data ignore patterns", () => {
-    expect(LOCAL_DB_IGNORE_PATTERNS.some((p) => p.includes("*.db"))).toBe(true);
-    expect(LOCAL_DB_IGNORE_PATTERNS.some((p) => p.includes(".data"))).toBe(true);
-    const docs = describeLocalDbIgnoreRules();
-    expect(docs).toMatch(/\.hq\/db/);
-    expect(docs).toMatch(/\*\.db/);
-  });
-});

package/src/lib/db/paths.ts

@@ -1,128 +0,0 @@
-/**
- * Vault database path conventions (C1 local tier).
- *
- * Canonical layout (locked by vault-databases PRD):
- *   ~/.hq/db/{companySlug}/vault.db
- *
- * Binary DB files are machine-local. They must never live under companies/
- * so hq-sync / git cannot treat them as vault text. Migrations remain vault
- * text at companies/{co}/db/migrations/*.sql (handled by migrate stories).
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-/** Default filename for the per-company local vault SQLite file. */
-export const LOCAL_VAULT_DB_FILENAME = "vault.db";
-
-/**
- * Glob-style ignore patterns for binary / local DB artifacts.
- * Apply in gitignore and hq-sync ignore configuration for any tree that
- * might accidentally host these files. Primary storage is under ~/.hq/db/
- * (outside the vault), but skills must still ignore stray `*.db` / `.data/`.
- */
-export const LOCAL_DB_IGNORE_PATTERNS: readonly string[] = [
-  "**/*.db",
-  "**/*.db-wal",
-  "**/*.db-shm",
-  "**/*.db-journal",
-  "**/.data/**",
-  // Explicit machine-local root (if a tool ever materializes a relative copy)
-  "**/.hq/db/**",
-];
-
-export interface LocalDbPathEnv {
-  /** Override home directory (tests inject temp dirs). Defaults to os.homedir(). */
-  home?: string;
-}
-
-/**
- * Resolve the machine-local root that holds all company vault DBs:
- * `{home}/.hq/db`.
- */
-export function resolveLocalDbRoot(env?: LocalDbPathEnv): string {
-  const home = (env?.home ?? os.homedir()).trim();
-  if (!home) {
-    throw new Error(
-      "cannot resolve local DB root: home directory is empty (set home or os.homedir())",
-    );
-  }
-  return path.join(home, ".hq", "db");
-}
-
-/**
- * Normalize and validate a company slug used in the local path.
- * Tenant isolation still requires HQ identity/membership at the command layer;
- * this only rejects empty / path-traversal slugs so we never open arbitrary paths.
- */
-export function normalizeCompanySlugForLocalDb(companySlug: string): string {
-  const slug = companySlug.trim().toLowerCase();
-  if (!slug) {
-    throw new Error("company slug is required for local DB path resolution");
-  }
-  if (
-    slug.includes("/") ||
-    slug.includes("\\") ||
-    slug.includes("..") ||
-    slug === "." ||
-    slug.includes("\0")
-  ) {
-    throw new Error(
-      `invalid company slug for local DB path: ${JSON.stringify(companySlug)}`,
-    );
-  }
-  return slug;
-}
-
-/**
- * Canonical path for a company's local vault SQLite file:
- * `~/.hq/db/{companySlug}/vault.db`.
- */
-export function resolveLocalDbPath(
-  companySlug: string,
-  env?: LocalDbPathEnv,
-): string {
-  const slug = normalizeCompanySlugForLocalDb(companySlug);
-  return path.join(resolveLocalDbRoot(env), slug, LOCAL_VAULT_DB_FILENAME);
-}
-
-/**
- * Directory that contains the company's vault.db (and WAL side files).
- */
-export function resolveLocalDbDir(
-  companySlug: string,
-  env?: LocalDbPathEnv,
-): string {
-  return path.dirname(resolveLocalDbPath(companySlug, env));
-}
-
-/**
- * Ensure the company local DB directory exists and is writable.
- * Creates parent directories recursively. Does not create the .db file
- * and does not write secrets into the tree.
- *
- * @returns absolute path of the directory
- */
-export function ensureLocalDbDir(
-  companySlug: string,
-  env?: LocalDbPathEnv,
-): string {
-  const dir = resolveLocalDbDir(companySlug, env);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  // Verify writable without leaving secrets or DB content behind.
-  fs.accessSync(dir, fs.constants.W_OK);
-  return dir;
-}
-
-/**
- * Human-readable documentation of ignore rules for operators and agents.
- */
-export function describeLocalDbIgnoreRules(): string {
-  return [
-    "Local vault databases live at ~/.hq/db/{company}/vault.db (outside the vault tree).",
-    "Never place *.db under companies/ — binary DB state is not vault-synced.",
-    "Ignore patterns:",
-    ...LOCAL_DB_IGNORE_PATTERNS.map((p) => `  - ${p}`),
-  ].join("\n");
-}

package/src/lib/db/remote-engine.test.ts

@@ -1,44 +0,0 @@
-/**
- * Remote engine registry + mock (vault-databases US-007).
- */
-
-import { beforeEach, describe, expect, it } from "vitest";
-
-import {
-  _resetRemoteEngineRegistryForTests,
-  createMockRemoteEngine,
-  getRemoteEngine,
-  registerRemoteEngine,
-} from "./remote-engine.js";
-
-beforeEach(() => {
-  _resetRemoteEngineRegistryForTests();
-});
-
-describe("RemoteDbEngine mock", () => {
-  it("provision and healthCheck work without AWS", async () => {
-    const mock = createMockRemoteEngine("mock");
-    registerRemoteEngine(mock);
-
-    const engine = getRemoteEngine("mock");
-    const first = await engine.provision({
-      companyUid: "cmp_x",
-      companySlug: "x",
-    });
-    expect(first.status).toBe("ready");
-    expect(first.resourceArn).toContain("cmp_x");
-
-    const second = await engine.provision({
-      companyUid: "cmp_x",
-      companySlug: "x",
-    });
-    expect(second.status).toBe("existing");
-    expect(second.resourceArn).toBe(first.resourceArn);
-
-    const health = await engine.healthCheck(first.resourceArn);
-    expect(health.healthy).toBe(true);
-
-    // Secret payload must not be a printable postgres URL in mock either
-    expect(JSON.stringify(first.connectionSecret)).not.toMatch(/postgres:\/\//i);
-  });
-});

package/src/lib/db/remote-engine.ts

@@ -1,148 +0,0 @@
-/**
- * Pluggable remote vault DB engine interface (vault-databases US-007).
- *
- * Default shipped adapter id: aurora-dsql.
- * This module is interface + registry only — no production AWS provision here.
- */
-
-/** Connection material written only to secrets stores — never CLI stdout. */
-export interface RemoteConnectionSecretPayload {
-  /** Opaque secret body (e.g. JSON with host/user/password or IAM token recipe). */
-  payload: Record<string, unknown>;
-  /** Suggested vault/Secrets Manager key suffix (namespaced by company elsewhere). */
-  secretNameHint: string;
-}
-
-export interface RemoteProvisionRequest {
-  companyUid: string;
-  companySlug: string;
-  region?: string;
-  /** Engine-specific options (cluster params, etc.). */
-  options?: Record<string, unknown>;
-}
-
-export interface RemoteProvisionResult {
-  engineId: string;
-  resourceArn: string;
-  region: string;
-  status: "ready" | "provisioning" | "failed" | "existing";
-  /** Secret payload to store — callers must not print. */
-  connectionSecret: RemoteConnectionSecretPayload;
-}
-
-export interface RemoteHealth {
-  engineId: string;
-  resourceArn: string;
-  healthy: boolean;
-  status: string;
-  checkedAt: string;
-}
-
-/**
- * Remote Postgres-class engine adapter.
- * Implementations live in control plane (hq-pro) for real AWS; CLI may mock.
- */
-export interface RemoteDbEngine {
-  readonly id: string;
-  provision(req: RemoteProvisionRequest): Promise<RemoteProvisionResult>;
-  deprovision(companyUid: string, resourceArn: string): Promise<void>;
-  connectionSecretPayload(
-    companyUid: string,
-    resourceArn: string,
-  ): Promise<RemoteConnectionSecretPayload>;
-  healthCheck(resourceArn: string): Promise<RemoteHealth>;
-}
-
-/** Default engine selection (PRD decision). */
-export const DEFAULT_REMOTE_ENGINE_ID = "aurora-dsql";
-
-const registry = new Map<string, RemoteDbEngine>();
-
-export function registerRemoteEngine(engine: RemoteDbEngine): void {
-  registry.set(engine.id, engine);
-}
-
-export function getRemoteEngine(id: string = DEFAULT_REMOTE_ENGINE_ID): RemoteDbEngine {
-  const engine = registry.get(id);
-  if (!engine) {
-    throw new Error(
-      `remote DB engine not registered: ${id} (available: ${[...registry.keys()].join(", ") || "none"})`,
-    );
-  }
-  return engine;
-}
-
-export function listRemoteEngineIds(): string[] {
-  return [...registry.keys()];
-}
-
-/** Clear registry (tests only). */
-export function _resetRemoteEngineRegistryForTests(): void {
-  registry.clear();
-}
-
-/**
- * In-memory mock engine for unit tests — no AWS.
- */
-export function createMockRemoteEngine(
-  id = "mock",
-): RemoteDbEngine {
-  const resources = new Map<string, { companyUid: string; region: string }>();
-
-  return {
-    id,
-    async provision(req) {
-      const existing = [...resources.entries()].find(
-        ([, v]) => v.companyUid === req.companyUid,
-      );
-      if (existing) {
-        const [arn, meta] = existing;
-        return {
-          engineId: id,
-          resourceArn: arn,
-          region: meta.region,
-          status: "existing",
-          connectionSecret: {
-            payload: { mock: true, companyUid: req.companyUid },
-            secretNameHint: `db/remote/${req.companySlug}`,
-          },
-        };
-      }
-      const arn = `arn:mock:db:${req.companyUid}`;
-      const region = req.region ?? "us-east-1";
-      resources.set(arn, { companyUid: req.companyUid, region });
-      return {
-        engineId: id,
-        resourceArn: arn,
-        region,
-        status: "ready",
-        connectionSecret: {
-          payload: { mock: true, companyUid: req.companyUid },
-          secretNameHint: `db/remote/${req.companySlug}`,
-        },
-      };
-    },
-    async deprovision(companyUid, resourceArn) {
-      const meta = resources.get(resourceArn);
-      if (meta && meta.companyUid === companyUid) {
-        resources.delete(resourceArn);
-      }
-    },
-    async connectionSecretPayload(companyUid, resourceArn) {
-      return {
-        payload: { mock: true, companyUid, resourceArn },
-        secretNameHint: `db/remote/${companyUid}`,
-      };
-    },
-    async healthCheck(resourceArn) {
-      const ok = resources.has(resourceArn);
-      return {
-        engineId: id,
-        resourceArn,
-        healthy: ok,
-        status: ok ? "ready" : "missing",
-        checkedAt: new Date().toISOString(),
-      };
-    },
-  };
-}

package/src/lib/db/remote-sql.test.ts

@@ -1,32 +0,0 @@
-/**
- * Remote SQL helper tests (US-010).
- */
-
-import { describe, expect, it } from "vitest";
-
-import { runRemoteSql } from "./remote-sql.js";
-
-describe("runRemoteSql", () => {
-  it("returns rows without connection string in output", async () => {
-    const result = await runRemoteSql({
-      company: "indigo",
-      sql: "SELECT 1 AS n",
-      getConnectionConfig: async () => ({ host: "mock", mock: true }),
-      execute: async () => [{ n: 1 }],
-    });
-    expect(result.rows).toEqual([{ n: 1 }]);
-    expect(JSON.stringify(result)).not.toMatch(/postgres:\/\//i);
-  });
-
-  it("clear error when no remote binding", async () => {
-    await expect(
-      runRemoteSql({
-        company: "indigo",
-        sql: "SELECT 1",
-        getConnectionConfig: async () => {
-          throw new Error("no remote binding");
-        },
-      }),
-    ).rejects.toThrow(/provision/i);
-  });
-});

package/src/lib/db/remote-sql.ts

@@ -1,62 +0,0 @@
-/**
- * Remote SQL via secrets-exec style injection (US-010).
- *
- * Connection string never appears in argv, logs, or stdout.
- * Local remains default when --remote is absent (handled by command layer).
- */
-
-export interface RemoteSqlOptions {
-  company: string;
-  sql: string;
-  /** Injected secret material — never log. */
-  getConnectionConfig: () => Promise<Record<string, unknown>>;
-  /** Execute against remote; tests inject mock. */
-  execute?: (
-    config: Record<string, unknown>,
-    sql: string,
-  ) => Promise<Record<string, unknown>[]>;
-}
-
-export interface RemoteSqlResult {
-  rows: Record<string, unknown>[];
-}
-
-function assertNoLeak(label: string, value: unknown): void {
-  const s = typeof value === "string" ? value : JSON.stringify(value);
-  if (/postgres:\/\//i.test(s) || /postgresql:\/\//i.test(s)) {
-    throw new Error(`${label}: connection string leak blocked`);
-  }
-}
-
-/**
- * Run SQL on remote tier using vault-bound credentials.
- */
-export async function runRemoteSql(
-  opts: RemoteSqlOptions,
-): Promise<RemoteSqlResult> {
-  if (!opts.sql?.trim()) {
-    throw new Error("SQL statement is required");
-  }
-
-  let config: Record<string, unknown>;
-  try {
-    config = await opts.getConnectionConfig();
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : "no remote binding";
-    throw new Error(
-      `remote SQL unavailable: ${msg}. Run \`hq db provision --company ${opts.company}\` first.`,
-    );
-  }
-
-  assertNoLeak("connection config", config);
-
-  if (!opts.execute) {
-    throw new Error(
-      "remote SQL executor not configured in this build (adapter pending live DSQL wire-up)",
-    );
-  }
-
-  const rows = await opts.execute(config, opts.sql);
-  assertNoLeak("remote sql rows", rows);
-  return { rows };
-}

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

@@ -1,106 +0,0 @@
-/**
- * Local SQL execution tests (vault-databases US-004).
- */
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import { afterEach, describe, expect, it } from "vitest";
-
-import { openLocalDb } from "./local.js";
-import { resolveLocalDbPath } from "./paths.js";
-import {
-  formatSqlResult,
-  resolveSqlDbPath,
-  runLocalSql,
-} from "./sql.js";
-
-const tempHomes: string[] = [];
-
-function makeTempHome(): string {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-db-sql-"));
-  tempHomes.push(dir);
-  return dir;
-}
-
-afterEach(() => {
-  while (tempHomes.length > 0) {
-    const dir = tempHomes.pop();
-    if (dir) fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
-
-describe("runLocalSql", () => {
-  it("SELECT happy path returns rows as jsonl-friendly records", () => {
-    const home = makeTempHome();
-    const db = openLocalDb("alpha", { home });
-    db.exec("CREATE TABLE smoke (id INTEGER PRIMARY KEY, name TEXT)");
-    db.prepare("INSERT INTO smoke (name) VALUES (?)").run("hello");
-    db.close();
-
-    const result = runLocalSql({
-      company: "alpha",
-      home,
-      sql: "SELECT id, name FROM smoke ORDER BY id",
-    });
-
-    expect(result.rows).toEqual([{ id: 1, name: "hello" }]);
-    expect(formatSqlResult(result, "jsonl")).toContain('"name":"hello"');
-    expect(JSON.stringify(result)).not.toMatch(/postgres:\/\//i);
-  });
-
-  it("blocks write SQL without --write", () => {
-    const home = makeTempHome();
-    openLocalDb("alpha", { home }).close();
-
-    expect(() =>
-      runLocalSql({
-        company: "alpha",
-        home,
-        sql: "CREATE TABLE t (id INTEGER)",
-      }),
-    ).toThrow(/read-only/i);
-  });
-
-  it("denies cross-company path override by default", () => {
-    const home = makeTempHome();
-    openLocalDb("alpha", { home }).close();
-    openLocalDb("beta", { home }).close();
-
-    const betaPath = resolveLocalDbPath("beta", { home });
-
-    expect(() =>
-      resolveSqlDbPath({
-        company: "alpha",
-        home,
-        sql: "SELECT 1",
-        dbPathOverride: betaPath,
-      }),
-    ).toThrow(/denied/i);
-
-    expect(() =>
-      runLocalSql({
-        company: "alpha",
-        home,
-        sql: "SELECT 1",
-        dbPathOverride: betaPath,
-      }),
-    ).toThrow(/denied/i);
-  });
-
-  it("rejects ATTACH even with --write (tenant isolation)", () => {
-    const home = makeTempHome();
-    openLocalDb("alpha", { home }).close();
-    const betaPath = resolveLocalDbPath("beta", { home });
-
-    expect(() =>
-      runLocalSql({
-        company: "alpha",
-        home,
-        write: true,
-        sql: `ATTACH DATABASE '${betaPath}' AS other`,
-      }),
-    ).toThrow(/ATTACH|tenant isolation/i);
-  });
-});