@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/src/lib/db/sql.ts

@@ -1,192 +0,0 @@
-/**
- * Local SQL execution helpers (vault-databases US-004).
- *
- * Company scope is path-bound via resolveLocalDbPath — callers must pass the
- * resolved company slug from HQ session/flags. Path overrides that open
- * another company's DB are denied unless an explicit dangerous flag is set.
- */
-
-import Database from "better-sqlite3";
-
-import type { LocalDb } from "./local.js";
-import { openLocalDb } from "./local.js";
-import {
-  normalizeCompanySlugForLocalDb,
-  resolveLocalDbDir,
-  resolveLocalDbPath,
-  type LocalDbPathEnv,
-} from "./paths.js";
-
-export interface SqlRunOptions extends LocalDbPathEnv {
-  company: string;
-  sql: string;
-  /** Allow INSERT/UPDATE/DELETE/DDL. Default false (read-only). */
-  write?: boolean;
-  /**
-   * Dangerous: open an absolute DB path instead of the company canonical path.
-   * Denied unless allowCrossCompanyPath is true.
-   */
-  dbPathOverride?: string;
-  /** Explicit dangerous flag to open a non-canonical local DB path. Default false. */
-  allowCrossCompanyPath?: boolean;
-  /** Output format */
-  format?: "jsonl" | "table";
-}
-
-export interface SqlRunResult {
-  columns: string[];
-  rows: Record<string, unknown>[];
-  changes: number;
-  readonly: boolean;
-}
-
-const WRITE_PATTERN =
-  /^\s*(INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|ALTER|TRUNCATE|REINDEX|VACUUM|BEGIN|COMMIT|ROLLBACK)\b/i;
-
-/** Always forbidden — opens other files/DBs and breaks company path isolation. */
-const FORBIDDEN_SQL_PATTERN =
-  /\b(ATTACH|DETACH|LOAD_EXTENSION)\b/i;
-
-export function stripSqlNoise(sql: string): string {
-  return sql
-    .replace(/^\s*--[^\n]*\n/gm, "")
-    .replace(/^\s*\/\*[\s\S]*?\*\//gm, "")
-    .trim();
-}
-
-export function isWriteSql(sql: string): boolean {
-  return WRITE_PATTERN.test(stripSqlNoise(sql));
-}
-
-/**
- * Statements that must never run via `hq db sql`, even with --write.
- * ATTACH/DETACH would let a company-scoped session open another company's
- * vault.db by absolute path (category-1 isolation).
- */
-export function assertSqlAllowed(sql: string): void {
-  const stripped = stripSqlNoise(sql);
-  if (FORBIDDEN_SQL_PATTERN.test(stripped)) {
-    throw new Error(
-      "ATTACH/DETACH/LOAD_EXTENSION are not allowed via hq db sql (tenant isolation); use the company-canonical local path only",
-    );
-  }
-}
-
-/**
- * Resolve which file path to open, enforcing company isolation by default.
- */
-export function resolveSqlDbPath(opts: SqlRunOptions): string {
-  const company = normalizeCompanySlugForLocalDb(opts.company);
-  const canonical = resolveLocalDbPath(company, opts);
-
-  if (!opts.dbPathOverride) {
-    return canonical;
-  }
-
-  if (opts.dbPathOverride === canonical) {
-    return canonical;
-  }
-
-  if (!opts.allowCrossCompanyPath) {
-    throw new Error(
-      "cross-company or path override denied: refusing to open a non-canonical local DB path without --allow-cross-company-path (dangerous)",
-    );
-  }
-
-  return opts.dbPathOverride;
-}
-
-function openByPath(dbPath: string): LocalDb {
-  const db = new Database(dbPath);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
-  return db;
-}
-
-/**
- * Execute SQL against the company local vault DB.
- */
-export function runLocalSql(opts: SqlRunOptions): SqlRunResult {
-  const sql = opts.sql?.trim();
-  if (!sql) {
-    throw new Error("SQL statement is required");
-  }
-
-  assertSqlAllowed(sql);
-
-  const writeRequested = !!opts.write;
-  if (isWriteSql(sql) && !writeRequested) {
-    throw new Error(
-      "write/DDL statement blocked in read-only mode; pass --write to allow (prefer hq db migrate for schema changes)",
-    );
-  }
-
-  const dbPath = resolveSqlDbPath(opts);
-  const usingCanonical =
-    !opts.dbPathOverride || opts.dbPathOverride === resolveLocalDbPath(opts.company, opts);
-
-  const db: LocalDb = usingCanonical
-    ? openLocalDb(opts.company, opts)
-    : openByPath(dbPath);
-
-  try {
-    if (!writeRequested) {
-      db.pragma("query_only = ON");
-    }
-
-    const stmt = db.prepare(sql);
-    if (stmt.reader) {
-      const rows = stmt.all() as Record<string, unknown>[];
-      const columns =
-        rows.length > 0
-          ? Object.keys(rows[0] as object)
-          : stmt.columns().map((c) => c.name);
-      return {
-        columns,
-        rows,
-        changes: 0,
-        readonly: !writeRequested,
-      };
-    }
-
-    const info = stmt.run();
-    return {
-      columns: ["changes", "lastInsertRowid"],
-      rows: [
-        {
-          changes: info.changes,
-          lastInsertRowid: Number(info.lastInsertRowid),
-        },
-      ],
-      changes: info.changes,
-      readonly: !writeRequested,
-    };
-  } finally {
-    db.close();
-  }
-}
-
-export function formatSqlResult(
-  result: SqlRunResult,
-  format: "jsonl" | "table" = "jsonl",
-): string {
-  if (format === "jsonl") {
-    if (result.rows.length === 0) {
-      return JSON.stringify({ columns: result.columns, rows: 0 });
-    }
-    return result.rows.map((r) => JSON.stringify(r)).join("\n");
-  }
-
-  const cols = result.columns;
-  if (cols.length === 0) return "(no columns)";
-  const header = cols.join("\t");
-  const body = result.rows
-    .map((r) => cols.map((c) => String(r[c] ?? "")).join("\t"))
-    .join("\n");
-  return body ? `${header}\n${body}` : header;
-}
-
-/** Test helper: company dir for isolation assertions. */
-export function companyLocalDbDir(company: string, env?: LocalDbPathEnv): string {
-  return resolveLocalDbDir(company, env);
-}

package/src/lib/hq-cloud-dep.smoke.test.ts

@@ -1,75 +0,0 @@
-/**
- * Dependency-bump smoke for @indigoai-us/hq-cloud.
- *
- * After moving from `file:../hq-cloud` to the published `^5.23.0`, this
- * test pins the contract: the SDK methods + types that hq-cli's
- * sync-mode / sync-narrow / files-browse / narrow-hint-banner commands
- * depend on must keep resolving from the npm-published package.
- *
- * If a future major bump on hq-cloud removes or renames any of these, the
- * matching hq-cli command would only fail at runtime (or at the call site's
- * own test). Locking it here catches the regression at install time in CI.
- */
-
-import { describe, it, expect } from "vitest";
-import * as cloud from "@indigoai-us/hq-cloud";
-
-describe("@indigoai-us/hq-cloud — pinned methods used by hq-cli", () => {
-  it("US-004 + US-008 prep — VaultClient carries the sync-browse methods", () => {
-    const proto = cloud.VaultClient.prototype as unknown as Record<
-      string,
-      unknown
-    >;
-    expect(typeof proto.listMyExplicitGrants).toBe("function");
-    expect(typeof proto.getMembershipSyncConfig).toBe("function");
-    expect(typeof proto.setMembershipSyncConfig).toBe("function");
-    expect(typeof proto.vend).toBe("function");
-  });
-
-  it("US-004 type aliases used by sync-mode + sync-narrow + files-browse compile-link", () => {
-    const _grant: cloud.ExplicitGrant = {
-      companyUid: "cmp_x",
-      path: "companies/x/",
-      permission: "read",
-      source: "person",
-    };
-    const _config: cloud.MembershipSyncConfig = {
-      membershipId: "mbr_x",
-      syncMode: "shared",
-      isDefault: false,
-      updatedAt: "2026-05-20T00:00:00Z",
-      updatedBy: "prs_x",
-    };
-    const _input: cloud.SetMembershipSyncConfigInput = { syncMode: "all" };
-    expect(_grant.source).toBe("person");
-    expect(_config.syncMode).toBe("shared");
-    expect(_input.syncMode).toBe("all");
-  });
-
-  it("US-008 prep — VendPurpose + VendInput keep purpose='browse' typecheckable", () => {
-    const _vendInput: cloud.VendInput = {
-      paths: ["companies/x/"],
-      operations: "read-only",
-      purpose: "browse",
-    };
-    expect(_vendInput.purpose).toBe("browse");
-  });
-
-  it("dep is the published @indigoai-us/hq-cloud, not a local file: link", async () => {
-    // The package.json of the loaded module must be the npm-published one
-    // (not file:../hq-cloud which was the dev wiring during US-006 onwards).
-    // We resolve the package.json path via Node's require resolver and read
-    // its `_resolved` (pnpm) or `version` field — both confirm origin.
-    const pkgPath = require.resolve(
-      "@indigoai-us/hq-cloud/package.json",
-    );
-    const pkg = await import(pkgPath, { with: { type: "json" } });
-    expect(pkg.default.name).toBe("@indigoai-us/hq-cloud");
-    // Must be ≥ 5.23.0 — the first published version carrying the sync-
-    // browse SDK + raw vend with purpose. A lower version means the bump
-    // never made it into the lockfile / pnpm-store.
-    const [maj, min] = pkg.default.version.split(".").map(Number);
-    expect(maj).toBeGreaterThanOrEqual(5);
-    if (maj === 5) expect(min).toBeGreaterThanOrEqual(23);
-  });
-});

package/src/lib/local-tree-diff.test.ts

@@ -1,301 +0,0 @@
-/**
- * Unit tests for `buildNarrowPlan` (local-tree-diff.ts).
- *
- * Uses a tmpdir fixture (same pattern as cloud-demote.test.ts) — vitest +
- * real fs — so the symmetric-diff + dirty-classification logic is exercised
- * end-to-end against an actual journal + filesystem.
- *
- * NAMESPACE CONTRACT (the bug these tests previously encoded): files are
- * written on disk at their hq-root-relative path (`companies/<slug>/...`),
- * but `buildNarrowPlan` emits — and the journal + grants endpoint use —
- * COMPANY-RELATIVE keys (`meetings/a.md`). The `key()` helper derives the
- * company-relative form from the on-disk path so journals, prefix sets, and
- * expectations all speak the same namespace the real server does.
- */
-
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import * as crypto from "node:crypto";
-
-import {
-  buildNarrowPlan,
-  toPosixKey,
-  formatBytes,
-  formatNarrowPlanSummary,
-} from "./local-tree-diff.js";
-import type { SyncJournal } from "@indigoai-us/hq-cloud";
-
-// ── Fixture helpers ─────────────────────────────────────────────────────────
-
-let tmpRoot: string;
-
-function writeFile(rel: string, contents: string): { abs: string; rel: string } {
-  const abs = path.join(tmpRoot, rel);
-  fs.mkdirSync(path.dirname(abs), { recursive: true });
-  fs.writeFileSync(abs, contents);
-  return { abs, rel };
-}
-
-/**
- * Strip the `companies/<slug>/` prefix from an on-disk hq-root-relative path
- * to get the COMPANY-RELATIVE key — the namespace `buildNarrowPlan` emits and
- * the journal + grants endpoint use.
- */
-function key(rel: string): string {
-  return rel.replace(/^companies\/[^/]+\//, "");
-}
-
-function sha256(s: string): string {
-  return crypto.createHash("sha256").update(s).digest("hex");
-}
-
-/**
- * Build a journal that "knows about" the given files at their current hash +
- * mtime. Journal keys are COMPANY-RELATIVE (via `key()`), matching the engine.
- */
-function journalFromFiles(
-  files: Array<{ rel: string; contents: string; syncedAt?: string }>,
-): SyncJournal {
-  const j: SyncJournal = {
-    version: "2",
-    lastSync: new Date().toISOString(),
-    files: {},
-    pulls: [],
-  };
-  for (const f of files) {
-    j.files[key(f.rel)] = {
-      hash: sha256(f.contents),
-      size: Buffer.byteLength(f.contents),
-      // Stamp syncedAt slightly in the future so on-disk mtime <= syncedAt
-      // (the clean path needs `mtime <= syncedAt + 1s` and mkdtemp file
-      // mtimes are essentially "now").
-      syncedAt: f.syncedAt ?? new Date(Date.now() + 5000).toISOString(),
-      direction: "down",
-    };
-  }
-  return j;
-}
-
-beforeEach(() => {
-  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-narrow-plan-"));
-});
-
-afterEach(() => {
-  fs.rmSync(tmpRoot, { recursive: true, force: true });
-});
-
-// ── Happy-path partitioning ─────────────────────────────────────────────────
-
-describe("toPosixKey — POSIX key normalization (Windows client regression)", () => {
-  // Regression: on a non-POSIX (Windows) client, path.relative() yields
-  // "\\"-separated paths. Emitted verbatim as a vault key, `knowledge\books-eoi.md`
-  // has no "/", so the server's listing (which splits on "/") renders it flat at
-  // the root. The narrow-plan must emit POSIX keys regardless of client OS.
-  it("converts a Windows-style nested path to a POSIX key", () => {
-    expect(toPosixKey("knowledge\\books-eoi.md")).toBe("knowledge/books-eoi.md");
-    expect(toPosixKey("data\\sub\\boots-accounts.json")).toBe(
-      "data/sub/boots-accounts.json",
-    );
-  });
-
-  it("leaves an already-POSIX key unchanged (idempotent)", () => {
-    expect(toPosixKey("meetings/2026/notes.md")).toBe("meetings/2026/notes.md");
-    expect(toPosixKey("flat.md")).toBe("flat.md");
-  });
-});
-
-describe("buildNarrowPlan — partition by prefix coverage", () => {
-  it("separates files into staying / clean / dirty buckets", () => {
-    // Staying — covered by prospective prefix.
-    const staying = writeFile(
-      "companies/acme/meetings/2026/notes.md",
-      "stays here",
-    );
-    // Clean orphan — outside prospective, matches journal.
-    const cleanOrphan = writeFile(
-      "companies/acme/scratch/old.md",
-      "clean content",
-    );
-    // Dirty orphan — outside prospective, hash mismatch.
-    const dirtyOrphan = writeFile(
-      "companies/acme/scratch/dirty.md",
-      "current local content",
-    );
-
-    const journal = journalFromFiles([
-      { rel: staying.rel, contents: "stays here" },
-      { rel: cleanOrphan.rel, contents: "clean content" },
-      // Journal saw an earlier version → hash mismatch with the on-disk
-      // "current local content" → dirty.
-      { rel: dirtyOrphan.rel, contents: "JOURNAL VERSION DIFFERENT" },
-    ]);
-
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: ["meetings/"],
-      journal,
-    });
-
-    expect(plan.staying.map((f) => f.relPath)).toEqual([key(staying.rel)]);
-    expect(plan.clean.map((f) => f.relPath)).toEqual([key(cleanOrphan.rel)]);
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(dirtyOrphan.rel)]);
-    expect(plan.dirty[0].reason).toBe("hash-mismatch");
-
-    expect(plan.totalStayingCount).toBe(1);
-    expect(plan.totalCleanCount).toBe(1);
-    expect(plan.totalDirtyCount).toBe(1);
-    expect(plan.totalCleanBytes).toBe(Buffer.byteLength("clean content"));
-  });
-
-  it("classifies files with no journal entry as dirty (not-in-journal)", () => {
-    const orphan = writeFile("companies/acme/scratch/local-draft.md", "never synced");
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: ["meetings/"],
-      journal: journalFromFiles([]),
-    });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
-    expect(plan.dirty[0].reason).toBe("not-in-journal");
-  });
-
-  it("treats tombstoned journal entries as not-in-journal (dirty)", () => {
-    const orphan = writeFile("companies/acme/scratch/tombstoned.md", "still here");
-    const journal = journalFromFiles([
-      { rel: orphan.rel, contents: "still here" },
-    ]);
-    // Mark the entry tombstoned post-hoc.
-    journal.files[key(orphan.rel)]!.removedAt = new Date().toISOString();
-    journal.files[key(orphan.rel)]!.removedReason = "scope_shrink";
-
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: ["meetings/"],
-      journal,
-    });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
-    expect(plan.dirty[0].reason).toBe("not-in-journal");
-  });
-
-  it("flags modified-after-sync via mtime past syncedAt", () => {
-    const orphan = writeFile("companies/acme/scratch/touched.md", "v1");
-    const journal = journalFromFiles([
-      { rel: orphan.rel, contents: "v1", syncedAt: new Date(0).toISOString() },
-    ]);
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: ["meetings/"],
-      journal,
-    });
-    expect(plan.dirty.map((f) => f.relPath)).toEqual([key(orphan.rel)]);
-    expect(plan.dirty[0].reason).toBe("modified-after-sync");
-  });
-
-  it("handles nested prefixes (broader covers narrower) by trusting the caller-coalesced set", () => {
-    const a = writeFile("companies/acme/meetings/a.md", "a");
-    const b = writeFile("companies/acme/meetings/2026/b.md", "b");
-    const c = writeFile("companies/acme/scratch/c.md", "c");
-
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: ["meetings/"],
-      journal: journalFromFiles([
-        { rel: a.rel, contents: "a" },
-        { rel: b.rel, contents: "b" },
-        { rel: c.rel, contents: "c" },
-      ]),
-    });
-
-    const stayingPaths = plan.staying.map((f) => f.relPath).sort();
-    expect(stayingPaths).toEqual([key(a.rel), key(b.rel)].sort());
-    expect(plan.clean.map((f) => f.relPath)).toEqual([key(c.rel)]);
-  });
-
-  it("returns an empty plan when the company folder is missing", () => {
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "ghost",
-      prospectivePrefixSet: [""],
-      journal: journalFromFiles([]),
-    });
-    expect(plan.totalStayingCount).toBe(0);
-    expect(plan.totalCleanCount).toBe(0);
-    expect(plan.totalDirtyCount).toBe(0);
-  });
-
-  it("everything is clean when the prefix set is empty (entire tree is orphan)", () => {
-    const a = writeFile("companies/acme/a.md", "aa");
-    const b = writeFile("companies/acme/sub/b.md", "bb");
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      prospectivePrefixSet: [],
-      journal: journalFromFiles([
-        { rel: a.rel, contents: "aa" },
-        { rel: b.rel, contents: "bb" },
-      ]),
-    });
-    expect(plan.totalStayingCount).toBe(0);
-    expect(plan.totalCleanCount).toBe(2);
-    expect(plan.totalDirtyCount).toBe(0);
-  });
-
-  it("everything stays when the prospective prefix covers the whole company folder", () => {
-    const a = writeFile("companies/acme/a.md", "aa");
-    const b = writeFile("companies/acme/sub/b.md", "bb");
-    const plan = buildNarrowPlan({
-      hqRoot: tmpRoot,
-      companySlug: "acme",
-      // Empty-string prefix = "covers everything" per isCoveredByAny.
-      prospectivePrefixSet: [""],
-      journal: journalFromFiles([]),
-    });
-    expect(plan.totalStayingCount).toBe(2);
-    expect(plan.totalCleanCount).toBe(0);
-    expect(plan.totalDirtyCount).toBe(0);
-    // both are staying, regardless of journal state
-    expect(
-      plan.staying.map((f) => f.relPath).sort(),
-    ).toEqual([key(a.rel), key(b.rel)].sort());
-  });
-});
-
-// ── Formatters ──────────────────────────────────────────────────────────────
-
-describe("formatBytes", () => {
-  it("formats bytes in a fixed unit ladder", () => {
-    expect(formatBytes(0)).toBe("0 B");
-    expect(formatBytes(512)).toBe("512 B");
-    expect(formatBytes(2048)).toBe("2.00 KB");
-    expect(formatBytes(5 * 1024 * 1024)).toBe("5.00 MB");
-  });
-
-  it("clamps negative + non-finite to 0 B", () => {
-    expect(formatBytes(-1)).toBe("0 B");
-    expect(formatBytes(Number.NaN)).toBe("0 B");
-  });
-});
-
-describe("formatNarrowPlanSummary", () => {
-  it("renders staying / clean / dirty counts with byte totals", () => {
-    const out = formatNarrowPlanSummary({
-      staying: [],
-      clean: [],
-      dirty: [],
-      totalStayingCount: 5,
-      totalCleanCount: 3,
-      totalCleanBytes: 2048,
-      totalDirtyCount: 1,
-      totalDirtyBytes: 1024,
-    });
-    expect(out).toContain("files staying:  5");
-    expect(out).toContain("clean orphans:  3 (2.00 KB)");
-    expect(out).toContain("dirty orphans:  1 (1.00 KB)");
-  });
-});