@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/cli/tombstones.ts

@@ -1,106 +0,0 @@
-/**
- * Shared FILE_TOMBSTONE fetch used by BOTH the pull planner (`sync.ts`) and the
- * push planner (`share.ts`).
- *
- * A FILE_TOMBSTONE is the authoritative record of an intentional, scoped delete
- * (`hq files delete <prefix>` → `POST /v1/files/delete` → `recordDeletions`).
- * Both sync legs consult it so a deleted key is neither re-downloaded (pull) nor
- * re-uploaded (push) and therefore cannot be resurrected by a behind peer.
- *
- * Lives in its own module so `share.ts` can use the fetch without importing from
- * `sync.ts` — `sync.ts` already imports values from `share.ts`
- * (`isEphemeralPath`, `isMalformedVaultKey`), so the reverse value-import would
- * create a runtime ESM cycle.
- */
-
-import type { VaultServiceConfig } from "../types.js";
-import { toPosixKey } from "../s3.js";
-
-/** Timeout for the best-effort FILE_TOMBSTONE fetch (GET /v1/files/tombstones). */
-export const FETCH_TOMBSTONES_TIMEOUT_MS = 5000;
-
-/**
- * A FILE_TOMBSTONE as the planners need it: the deleted key + when it was
- * deleted. The `deletedAt` timestamp is the decisive precedence signal on the
- * pull side — a remote object newer than it is a genuine re-create (sync it), an
- * object at or older than it is a stale resurrection of a deleted key (suppress
- * it).
- */
-export interface CompanyTombstone {
-  deletedAt: string;
-}
-
-/**
- * Fetch the company's FILE_TOMBSTONE rows from hq-pro (GET /v1/files/tombstones)
- * and return them as a POSIX-keyed map the planners consult to avoid
- * resurrecting an intentionally-deleted object (delete-resync). The endpoint is
- * ACL-filtered server-side, so the map only ever contains keys this caller can
- * read — exactly the keys that can appear in the (STS-scoped) remote LIST.
- *
- * Best-effort and bounded by a 5s timeout: a tombstone read that fails, times
- * out, or returns non-2xx degrades to an EMPTY map — i.e. to the pre-fix
- * behavior (no suppression). That is the safe failure direction: a missed
- * tombstone re-pulls/re-pushes a deleted file (a known, recoverable annoyance),
- * whereas a spurious tombstone would HIDE a file the user wants. The failure is
- * logged (never silently swallowed) so a persistently-degraded read is visible.
- */
-export async function fetchCompanyTombstones(
-  vaultConfig: VaultServiceConfig,
-  companyUid: string,
-): Promise<Map<string, CompanyTombstone>> {
-  const out = new Map<string, CompanyTombstone>();
-  try {
-    const token =
-      typeof vaultConfig.authToken === "function"
-        ? await vaultConfig.authToken()
-        : vaultConfig.authToken;
-    const base = vaultConfig.apiUrl.replace(/\/+$/, "");
-    const url = `${base}/v1/files/tombstones?company=${encodeURIComponent(
-      companyUid,
-    )}`;
-    const controller = new AbortController();
-    const timer = setTimeout(
-      () => controller.abort(),
-      FETCH_TOMBSTONES_TIMEOUT_MS,
-    );
-    try {
-      const res = await fetch(url, {
-        method: "GET",
-        headers: { Authorization: `Bearer ${token}` },
-        signal: controller.signal,
-      });
-      if (!res.ok) {
-        // Non-2xx is non-fatal: log and degrade to no-suppression. A 404 means
-        // the endpoint is not deployed yet (hq-pro release lag) — the sync
-        // proceeds with the legacy behavior until it lands.
-        console.error(
-          `[hq-sync] tombstone fetch returned ${res.status} (degrading to no-suppression)`,
-        );
-        return out;
-      }
-      const body = (await res.json()) as {
-        tombstones?: Array<{ key?: string; deletedAt?: string }>;
-      };
-      for (const t of body.tombstones ?? []) {
-        if (typeof t.key === "string" && typeof t.deletedAt === "string") {
-          out.set(toPosixKey(t.key), { deletedAt: t.deletedAt });
-        }
-      }
-    } finally {
-      clearTimeout(timer);
-    }
-  } catch (err) {
-    // Best-effort: a failed tombstone read must never break the sync. Log
-    // (policy: never silently swallow) and degrade to no-suppression.
-    try {
-      console.error(
-        `[hq-sync] tombstone fetch failed (non-fatal, degrading to no-suppression): ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    } catch {
-      // swallow — logging must never break sync
-    }
-  }
-  return out;
-}

package/src/cli/watch-event-push-conflict.test.ts

@@ -1,234 +0,0 @@
-/**
- * Regression guard: the watch + event-push path must NOT mint phantom
- * `.conflict-*` mirrors for an ordinary single-writer local edit.
- *
- * Background (feedback_ef2b7c8c): a user editing files under
- * `companies/{slug}/` saw the menubar's watch/event-push runner mint a
- * `.conflict-<ts>-<machine>` mirror on EVERY ordinary local Edit/Write —
- * thousands of phantom files in a single session. The watch/event-push runner
- * reacts to a local change by running a targeted `--direction push` pass, i.e.
- * `share()` over the changed company subtree, so the conflict-minting logic is
- * share()'s push-side conflict gate. The original gate flagged a conflict on
- * `localChanged` alone (`journalEntry.hash !== localHash`), which fires for
- * every edit of any already-synced file. The gate now requires
- * `(localChanged && remoteChanged) || isFreshCollision`: a single writer never
- * has `remoteChanged` (the live S3 ETag still equals the journal's recorded
- * baseline), so an ordinary edit is uploaded, not mirrored.
- *
- * This test pins that contract end-to-end through `share()` using the same
- * mocked-S3 harness as `share.test.ts`, modelling a single-writer remote whose
- * ETag is always exactly what THIS device last uploaded. A positive control
- * (a genuine out-of-band peer write) proves the guard is not trivially
- * always-zero: real divergence is still detected.
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { clearContextCache } from "../context.js";
-import type { VaultServiceConfig } from "../types.js";
-
-vi.mock("../s3.js", () => ({
-  toPosixKey: (key: string) => key.split("\\").join("/"),
-  uploadFile: vi.fn(),
-  uploadSymlink: vi.fn().mockResolvedValue({ etag: '"upload-symlink-etag"' }),
-  downloadFile: vi.fn().mockResolvedValue(undefined),
-  listRemoteFiles: vi.fn().mockResolvedValue([]),
-  deleteRemoteFile: vi.fn().mockResolvedValue(undefined),
-  headRemoteFile: vi.fn(),
-  primeObjectTransport: vi.fn().mockResolvedValue(undefined),
-  primeUploads: vi.fn().mockResolvedValue(undefined),
-}));
-
-vi.mock("readline", () => ({
-  createInterface: vi.fn(() => ({ question: vi.fn(), close: vi.fn() })),
-}));
-
-import { share } from "./share.js";
-import { downloadFile, headRemoteFile, uploadFile } from "../s3.js";
-
-const mockConfig: VaultServiceConfig = {
-  apiUrl: "https://vault-api.test",
-  authToken: "test-jwt-token",
-  region: "us-east-1",
-};
-
-const mockEntity = {
-  uid: "cmp_01ABCDEF",
-  slug: "acme",
-  bucketName: "hq-vault-acme-123",
-  status: "active",
-};
-
-function setupFetchMock() {
-  vi.stubGlobal(
-    "fetch",
-    vi.fn().mockImplementation(async (url: string) => {
-      const u = String(url);
-      if (u.includes("/entity/check-slug/me"))
-        return {
-          ok: true,
-          status: 200,
-          json: async () => ({ available: false, conflictingCompanyUid: mockEntity.uid }),
-          text: async () => "",
-        };
-      if (u.includes("/entity/by-slug/") || /\/entity\/cmp_/.test(u))
-        return { ok: true, status: 200, json: async () => ({ entity: mockEntity }), text: async () => "" };
-      if (u.includes("/sts/vend"))
-        return {
-          ok: true,
-          status: 200,
-          json: async () => ({
-            credentials: {
-              accessKeyId: "ASIA_TEST",
-              secretAccessKey: "s",
-              sessionToken: "t",
-              expiration: new Date(Date.now() + 9e5).toISOString(),
-            },
-            expiresAt: new Date(Date.now() + 9e5).toISOString(),
-          }),
-          text: async () => "",
-        };
-      return { ok: false, status: 404, text: async () => "Not found" };
-    }),
-  );
-}
-
-/** Every `.conflict-<ts>-*` mirror file anywhere under `root`. */
-function countConflictMirrors(root: string): string[] {
-  const out: string[] = [];
-  const walk = (d: string) => {
-    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
-      const p = path.join(d, e.name);
-      if (e.isDirectory()) walk(p);
-      else if (/\.conflict-/.test(e.name)) out.push(p);
-    }
-  };
-  walk(root);
-  return out;
-}
-
-/**
- * In-memory single-writer S3: the object's ETag is always exactly what THIS
- * device last uploaded (no peer ever writes). `lastModified` advances on each
- * PUT to model S3 stamping it server-side. The S3-module signatures are
- * `uploadFile(ctx, localPath, key)`, `headRemoteFile(ctx, key)`,
- * `downloadFile(ctx, key, dest)` — wire the mocks to match exactly.
- */
-function wireSingleWriterRemote() {
-  const remote = new Map<string, { etag: string; lastModified: Date; size: number }>();
-  let clock = Date.now();
-  let seq = 0;
-  vi.mocked(uploadFile).mockImplementation(async (_ctx: unknown, localPath: string, key: string) => {
-    const etag = `"etag-${seq++}"`;
-    clock += 1000;
-    remote.set(key, { etag, lastModified: new Date(clock), size: fs.statSync(localPath).size });
-    return { etag };
-  });
-  vi.mocked(headRemoteFile).mockImplementation(async (_ctx: unknown, key: string) => {
-    const r = remote.get(key);
-    return r ? { lastModified: r.lastModified, etag: r.etag, size: r.size } : null;
-  });
-  vi.mocked(downloadFile).mockImplementation(async (_ctx: unknown, _key: string, dest: string) => {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.writeFileSync(dest, "remote-bytes\n");
-    return {};
-  });
-  return remote;
-}
-
-describe("watch + event-push conflict regression (feedback_ef2b7c8c)", () => {
-  let tmpDir: string;
-  let stateDir: string;
-
-  beforeEach(() => {
-    clearContextCache();
-    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-conflict-"));
-    stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-watch-state-"));
-    process.env.HQ_STATE_DIR = stateDir;
-    setupFetchMock();
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    vi.clearAllMocks();
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-    fs.rmSync(stateDir, { recursive: true, force: true });
-    delete process.env.HQ_STATE_DIR;
-  });
-
-  it("a single writer's repeated local edits mint ZERO .conflict-* files", async () => {
-    const companyRoot = path.join(tmpDir, "companies", "acme");
-    fs.mkdirSync(companyRoot, { recursive: true });
-    const files = ["notes.md", "plan.md", "ideas.md"].map((n) => path.join(companyRoot, n));
-    for (const f of files) fs.writeFileSync(f, "v0\n");
-
-    wireSingleWriterRemote();
-
-    const conflictPathsSeen: string[] = [];
-    // The event-push runner pushes the changed company subtree. Mirror that:
-    // share() over the company root on every settled change.
-    const eventPush = async () => {
-      const r = await share({
-        paths: [companyRoot],
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        onConflict: "keep",
-        onEvent: () => {},
-      });
-      conflictPathsSeen.push(...r.conflictPaths);
-    };
-
-    // Initial sync establishes the journal baseline (first upload of each file).
-    await eventPush();
-
-    // An editing session: 30 ordinary local edits, round-robin across the
-    // files, each followed by its targeted event-push.
-    for (let i = 0; i < 30; i++) {
-      fs.writeFileSync(files[i % files.length], `v${i + 1}\n`);
-      await eventPush();
-    }
-
-    expect(countConflictMirrors(tmpDir)).toEqual([]);
-    expect(conflictPathsSeen).toEqual([]);
-  });
-
-  it("positive control: a genuine peer write is still detected as a conflict", async () => {
-    const companyRoot = path.join(tmpDir, "companies", "acme");
-    fs.mkdirSync(companyRoot, { recursive: true });
-    const file = path.join(companyRoot, "contested.md");
-    fs.writeFileSync(file, "v0\n");
-
-    const remote = wireSingleWriterRemote();
-
-    const conflictPathsSeen: string[] = [];
-    const eventPush = async () => {
-      const r = await share({
-        paths: [companyRoot],
-        company: "acme",
-        vaultConfig: mockConfig,
-        hqRoot: tmpDir,
-        onConflict: "keep",
-        onEvent: () => {},
-      });
-      conflictPathsSeen.push(...r.conflictPaths);
-    };
-
-    await eventPush(); // baseline
-
-    // A peer advances the remote object out-of-band to DIFFERENT bytes. Journal
-    // keys are company-relative, so the key is "contested.md".
-    remote.set("contested.md", { etag: '"peer-etag"', lastModified: new Date(Date.now() + 60_000), size: 99 });
-    // ...and we also edit locally → both sides moved → a genuine conflict.
-    fs.writeFileSync(file, "v1-local\n");
-    await eventPush();
-
-    // Existing-entry push conflicts surface via conflictPaths (the inspection
-    // mirror is written by the pull leg). The contract under test: a REAL
-    // divergence is still flagged — the single-writer guard above did not
-    // over-correct into swallowing true conflicts.
-    expect(conflictPathsSeen).toContain("contested.md");
-  });
-});

package/src/client-info.test.ts

@@ -1,214 +0,0 @@
-/**
- * Tests for the client-info helpers and header injection.
- *
- * Two layers are exercised here:
- *   1. The pure functions in `client-info.ts` — buildClientHeaders,
- *      clientInfoFromPackage, detectHqCoreVersion.
- *   2. End-to-end injection into VaultClient.request, since "the headers
- *      actually land on outbound fetch" is the property consumers care about.
- */
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  buildClientHeaders,
-  clientInfoFromPackage,
-  detectHqCoreVersion,
-  HEADER_CLIENT_NAME,
-  HEADER_CLIENT_VERSION,
-  HEADER_HQ_CORE_VERSION,
-} from "./client-info.js";
-import { VaultClient } from "./vault-client.js";
-
-describe("buildClientHeaders", () => {
-  it("returns empty object when info is undefined", () => {
-    expect(buildClientHeaders(undefined)).toEqual({});
-  });
-
-  it("emits User-Agent + x-hq-client-{name,version} from name/version", () => {
-    const headers = buildClientHeaders({
-      name: "@indigoai-us/hq-cli",
-      version: "5.15.0",
-    });
-    expect(headers["User-Agent"]).toBe("@indigoai-us/hq-cli/5.15.0");
-    expect(headers[HEADER_CLIENT_NAME]).toBe("@indigoai-us/hq-cli");
-    expect(headers[HEADER_CLIENT_VERSION]).toBe("5.15.0");
-    expect(headers[HEADER_HQ_CORE_VERSION]).toBeUndefined();
-  });
-
-  it("includes x-hq-core-version only when hqCoreVersion is set", () => {
-    const headers = buildClientHeaders({
-      name: "@indigoai-us/hq-cli",
-      version: "5.15.0",
-      hqCoreVersion: "14.1.0",
-    });
-    expect(headers[HEADER_HQ_CORE_VERSION]).toBe("14.1.0");
-  });
-
-  it("emits arbitrary extra fields as x-hq-client-<key> headers", () => {
-    const headers = buildClientHeaders({
-      name: "x",
-      version: "1.0.0",
-      extra: { machine: "ec2-bot-7", channel: "stable" },
-    });
-    expect(headers["x-hq-client-machine"]).toBe("ec2-bot-7");
-    expect(headers["x-hq-client-channel"]).toBe("stable");
-  });
-});
-
-describe("clientInfoFromPackage", () => {
-  it("extracts name and version from a parsed package.json", () => {
-    expect(clientInfoFromPackage({ name: "foo", version: "1.2.3" })).toEqual({
-      name: "foo",
-      version: "1.2.3",
-    });
-  });
-
-  it("throws when name is missing", () => {
-    expect(() => clientInfoFromPackage({ version: "1.0.0" })).toThrow(/name/);
-  });
-
-  it("throws when version is missing", () => {
-    expect(() => clientInfoFromPackage({ name: "foo" })).toThrow(/version/);
-  });
-
-  it("throws on non-string fields", () => {
-    expect(() =>
-      clientInfoFromPackage({ name: 42 as unknown as string, version: "1.0.0" }),
-    ).toThrow();
-  });
-});
-
-describe("detectHqCoreVersion", () => {
-  let tmpRoot: string;
-  const origHqHome = process.env.HQ_HOME;
-  const origHqRoot = process.env.HQ_ROOT;
-
-  beforeEach(() => {
-    tmpRoot = mkdtempSync(join(tmpdir(), "hq-core-detect-"));
-    delete process.env.HQ_HOME;
-    delete process.env.HQ_ROOT;
-  });
-
-  afterEach(() => {
-    rmSync(tmpRoot, { recursive: true, force: true });
-    if (origHqHome !== undefined) process.env.HQ_HOME = origHqHome;
-    if (origHqRoot !== undefined) process.env.HQ_ROOT = origHqRoot;
-  });
-
-  function seedHqCore(root: string, version: string): void {
-    mkdirSync(join(root, "core"), { recursive: true });
-    mkdirSync(join(root, "companies"), { recursive: true });
-    writeFileSync(
-      join(root, "core", "core.yaml"),
-      `version: 1\nhqVersion: "${version}"\nupdatedAt: "2026-05-13T00:00:00Z"\n`,
-    );
-  }
-
-  it("returns undefined when nothing on the walk-up has core.yaml", () => {
-    expect(detectHqCoreVersion(tmpRoot)).toBeUndefined();
-  });
-
-  it("returns hqVersion when startDir is the hq-core root", () => {
-    seedHqCore(tmpRoot, "14.1.0");
-    expect(detectHqCoreVersion(tmpRoot)).toBe("14.1.0");
-  });
-
-  it("walks upward to find core.yaml from a nested cwd", () => {
-    seedHqCore(tmpRoot, "14.2.0");
-    const nested = join(tmpRoot, "companies", "acme", "projects", "p1");
-    mkdirSync(nested, { recursive: true });
-    expect(detectHqCoreVersion(nested)).toBe("14.2.0");
-  });
-
-  it("ignores directories that have core.yaml but no companies/ — disambiguates fixtures", () => {
-    mkdirSync(join(tmpRoot, "core"), { recursive: true });
-    writeFileSync(
-      join(tmpRoot, "core", "core.yaml"),
-      `version: 1\nhqVersion: "99.0.0"\n`,
-    );
-    // No companies/ at this level → not an hq-core root.
-    expect(detectHqCoreVersion(tmpRoot)).toBeUndefined();
-  });
-
-  it("honors HQ_HOME env override before walking cwd", () => {
-    seedHqCore(tmpRoot, "14.3.0");
-    process.env.HQ_HOME = tmpRoot;
-    // startDir intentionally points elsewhere — env should win.
-    const elsewhere = mkdtempSync(join(tmpdir(), "elsewhere-"));
-    try {
-      expect(detectHqCoreVersion(elsewhere)).toBe("14.3.0");
-    } finally {
-      rmSync(elsewhere, { recursive: true, force: true });
-    }
-  });
-
-  it("parses unquoted hqVersion values too", () => {
-    mkdirSync(join(tmpRoot, "core"), { recursive: true });
-    mkdirSync(join(tmpRoot, "companies"), { recursive: true });
-    writeFileSync(
-      join(tmpRoot, "core", "core.yaml"),
-      `version: 1\nhqVersion: 14.4.0\n`,
-    );
-    expect(detectHqCoreVersion(tmpRoot)).toBe("14.4.0");
-  });
-});
-
-describe("VaultClient stamps client headers on outbound requests", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("includes x-hq-client-name + x-hq-client-version when clientInfo is set", async () => {
-    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify({ memberships: [] }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-
-    const client = new VaultClient({
-      apiUrl: "https://vault.test.example.com",
-      authToken: "tok",
-      clientInfo: {
-        name: "@indigoai-us/hq-cli",
-        version: "5.15.0",
-        hqCoreVersion: "14.1.0",
-      },
-    });
-
-    await client.listMyMemberships();
-
-    expect(fetchSpy).toHaveBeenCalledOnce();
-    const init = fetchSpy.mock.calls[0]?.[1] as RequestInit;
-    const headers = init.headers as Record<string, string>;
-    expect(headers[HEADER_CLIENT_NAME]).toBe("@indigoai-us/hq-cli");
-    expect(headers[HEADER_CLIENT_VERSION]).toBe("5.15.0");
-    expect(headers[HEADER_HQ_CORE_VERSION]).toBe("14.1.0");
-    expect(headers["User-Agent"]).toBe("@indigoai-us/hq-cli/5.15.0");
-  });
-
-  it("omits client headers when clientInfo is not set — back-compat", async () => {
-    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify({ memberships: [] }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-
-    const client = new VaultClient({
-      apiUrl: "https://vault.test.example.com",
-      authToken: "tok",
-    });
-
-    await client.listMyMemberships();
-
-    const headers = (fetchSpy.mock.calls[0]?.[1] as RequestInit)
-      .headers as Record<string, string>;
-    expect(headers[HEADER_CLIENT_NAME]).toBeUndefined();
-    expect(headers[HEADER_CLIENT_VERSION]).toBeUndefined();
-    expect(headers["User-Agent"]).toBeUndefined();
-  });
-});

package/src/client-info.ts

@@ -1,121 +0,0 @@
-/**
- * Client identification — every HQ client that talks to hq-cloud-api should
- * stamp its name and version on outbound requests so the server can attribute
- * traffic, gate on minimum versions, and surface deprecation warnings.
- *
- * The CLI in particular sends a third header (`x-hq-core-version`) when it's
- * invoked from inside an hq-core checkout, so the server sees which scaffold
- * generation the user is running against.
- */
-
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import type { ClientInfo } from "./types.js";
-
-export const HEADER_CLIENT_NAME = "x-hq-client-name";
-export const HEADER_CLIENT_VERSION = "x-hq-client-version";
-export const HEADER_HQ_CORE_VERSION = "x-hq-core-version";
-
-/**
- * Build the set of `x-hq-*` headers (plus a derived `User-Agent`) for a
- * ClientInfo. Returns an empty object when info is undefined so callers can
- * spread the result unconditionally.
- */
-export function buildClientHeaders(
-  info: ClientInfo | undefined,
-): Record<string, string> {
-  if (!info) return {};
-
-  const headers: Record<string, string> = {
-    "User-Agent": `${info.name}/${info.version}`,
-    [HEADER_CLIENT_NAME]: info.name,
-    [HEADER_CLIENT_VERSION]: info.version,
-  };
-
-  if (info.hqCoreVersion) {
-    headers[HEADER_HQ_CORE_VERSION] = info.hqCoreVersion;
-  }
-
-  if (info.extra) {
-    for (const [k, v] of Object.entries(info.extra)) {
-      headers[`x-hq-client-${k}`] = v;
-    }
-  }
-
-  return headers;
-}
-
-/**
- * Build a ClientInfo from a parsed package.json. Most consumers will call this
- * once at startup and pass the result into every VaultServiceConfig.
- */
-export function clientInfoFromPackage(pkg: {
-  name?: unknown;
-  version?: unknown;
-}): ClientInfo {
-  if (typeof pkg.name !== "string" || pkg.name.length === 0) {
-    throw new Error("clientInfoFromPackage: package.json is missing a name");
-  }
-  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
-    throw new Error("clientInfoFromPackage: package.json is missing a version");
-  }
-  return { name: pkg.name, version: pkg.version };
-}
-
-/**
- * Walk upward from `startDir` looking for `core/core.yaml`. When found, parse
- * out the `hqVersion` field and return it. Returns undefined if we never find
- * an hq-core checkout — i.e. the caller is running from a plain user dir.
- *
- * Honors `HQ_HOME` env var as an explicit override so multi-checkout setups
- * (e.g. CI bots, the menubar app pointing at a non-cwd HQ root) can pin the
- * detection without relying on cwd.
- *
- * Why a regex instead of a YAML parser: `core.yaml` lives at the very top of
- * the file and the field has a stable shape — adding a YAML dep just to read
- * one string would balloon every consumer's bundle. The current shape is
- * `hqVersion: "X.Y.Z"` (quoted) per the canonical seed; we tolerate unquoted
- * too.
- */
-export function detectHqCoreVersion(startDir?: string): string | undefined {
-  const fromEnv = process.env.HQ_HOME ?? process.env.HQ_ROOT;
-  if (fromEnv) {
-    const v = readCoreVersionAt(fromEnv);
-    if (v) return v;
-  }
-
-  let dir = resolve(startDir ?? process.cwd());
-  while (true) {
-    const v = readCoreVersionAt(dir);
-    if (v) return v;
-    const parent = dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
-
-function readCoreVersionAt(hqRoot: string): string | undefined {
-  // hq-core identity requires BOTH core/core.yaml AND companies/ — matches the
-  // CLI's own detection (commit bc827d0). Without this guard, any directory
-  // containing a stray `core/core.yaml` (e.g. a test fixture) would be
-  // misidentified as an hq-core root.
-  const yamlPath = join(hqRoot, "core", "core.yaml");
-  const companiesPath = join(hqRoot, "companies");
-  let content: string;
-  try {
-    content = readFileSync(yamlPath, "utf8");
-  } catch {
-    return undefined;
-  }
-  try {
-    // statSync would be marginally cleaner, but readdirSync of a nonexistent
-    // path throws synchronously which is what we want.
-    readFileSync(companiesPath, { flag: "r" });
-  } catch (err) {
-    const e = err as NodeJS.ErrnoException;
-    // EISDIR is the success case — companies/ exists and is a directory.
-    if (e.code !== "EISDIR") return undefined;
-  }
-  const match = /^hqVersion:\s*["']?([^"'\s]+)/m.exec(content);
-  return match ? match[1] : undefined;
-}