@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/cloud-provision.ts

@@ -1,942 +0,0 @@
-/**
- * `hq cloud provision company <slug>` — canonical cloud-promotion subcommand.
- *
- * Promotes a local company directory (`companies/<slug>/`) to a cloud-backed
- * entity by:
- *   1. Validating the slug, manifest membership, and local company directory
- *   2. Resolving a Cognito access token (refresh as needed)
- *   3. Idempotently provisioning the vault entity:
- *        GET /v1/entities/by-slug/company/<slug> → 200 reuse, 404 → POST /v1/entities
- *   4. Atomically patching `companies/manifest.yaml` with `cloud_uid` + `bucket_name`
- *   5. Atomically writing `companies/<slug>/.hq/config.json`
- *   6. Triggering an initial sync via `share()` from `@indigoai-us/hq-cloud`
- *   7. Emitting one structured JSON line to stdout (machine-readable result)
- *
- * Replaces three ad-hoc implementations:
- *   - `designate-team` bash script (hq-core-staging)
- *   - AppBar `provision.rs` (hq-sync, auto-provision on first sync)
- *   - AppBar `workspaces.rs` Connect flow (hq-sync, manual Connect)
- *
- * Exit codes:
- *   0 — success (and `initial_sync.ok=true`)
- *   1 — vault auth/network/API error (no entity provisioned)
- *   2 — invalid slug, company dir missing, or company is status=archived.
- *       Folder-only states (companies/<slug>/ exists on disk but no manifest
- *       entry) self-heal via ensureManifestEntryForProvision before
- *       validation runs, so a missing manifest entry alone is NOT an exit-2.
- *   3 — sync failure after entity provisioned (cloud_uid in JSON;
- *       `initial_sync.ok=false`). Manifest + config may have been written.
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as yaml from "js-yaml";
-import { parseUserYaml } from "../utils/user-yaml-error.js";
-
-import { share } from "@indigoai-us/hq-cloud";
-
-import {
-  DEFAULT_HQ_ROOT,
-  DEFAULT_VAULT_API_URL,
-  ensureCognitoToken,
-  buildVaultConfig,
-} from "../utils/cognito-session.js";
-
-// ── Types ────────────────────────────────────────────────────────────────────
-
-/** Vault entity shape (subset we consume). Mirrors hq-pro entity types. */
-export interface VaultEntity {
-  uid: string;
-  type: string;
-  slug: string;
-  name: string;
-  bucketName?: string;
-  kmsKeyId?: string | null;
-  status?: string;
-  ownerUid?: string;
-}
-
-/** Per-company `.hq/config.json` schema (matches AppBar `provision.rs::CompanyConfig`). */
-export interface CompanyConfig {
-  companyUid: string;
-  companySlug: string;
-  bucketName: string;
-  vaultApiUrl: string;
-}
-
-/** Final stdout JSON shape. Consumers (designate-team, AppBar) parse this. */
-export interface ProvisionResult {
-  ok: boolean;
-  company_slug: string;
-  cloud_uid: string;
-  bucket_name: string;
-  vault_api_url: string;
-  kms_key_id: string | null;
-  created_entity: boolean;
-  manifest_patched: boolean;
-  config_written: boolean;
-  initial_sync: {
-    ok?: boolean;
-    files_uploaded?: number;
-    bytes_uploaded?: number;
-    error?: string;
-    /** True if the caller passed --skip-initial-sync; ok/files/bytes will be absent. */
-    skipped?: boolean;
-  };
-}
-
-/** Options for the high-level `provisionCompany` orchestrator. */
-export interface ProvisionCompanyOptions {
-  slug: string;
-  name?: string;
-  ownerUid?: string;
-  hqRoot: string;
-  vaultApiUrl: string;
-  /**
-   * Skip the initial-sync step. The vault entity, manifest patch, and
-   * `.hq/config.json` write still happen; the post-provision `share()` call
-   * is no-op'd. Use this when the caller has its own upload pipeline (e.g.
-   * AppBar HQ Sync's `first_push_company` with STS-vended credentials and
-   * Tauri progress events) and would otherwise double-upload the same files.
-   * When true, `initial_sync` in the result is `{ skipped: true }`.
-   */
-  skipInitialSync?: boolean;
-  /** Injected vault HTTP client (override for tests). */
-  vaultClient?: VaultClient;
-  /** Injected access-token resolver (override for tests). */
-  resolveAccessToken?: () => Promise<string>;
-  /** Injected sync runner (override for tests). */
-  runInitialSync?: (args: InitialSyncArgs) => Promise<{
-    filesUploaded: number;
-    bytesUploaded: number;
-  }>;
-  /** Optional progress logger; defaults to stderr-prefixed `[hq cloud provision]`. */
-  log?: (msg: string) => void;
-}
-
-interface InitialSyncArgs {
-  slug: string;
-  hqRoot: string;
-  accessToken: string;
-  vaultApiUrl: string;
-}
-
-/** Vault HTTP client interface — minimal surface for entity ops. */
-export interface VaultClient {
-  /**
-   * List every person entity visible to the caller (scoped server-side by the
-   * caller's Cognito identity). Used by `provisionCompany` as a pre-flight
-   * to verify the caller has been onboarded before mutating any cloud-side
-   * resources — the initial-sync step at the end of provision needs to vend
-   * STS credentials, which the server only does for callers with a person
-   * entity.
-   */
-  listMyPersonEntities(): Promise<VaultEntity[]>;
-  /**
-   * Legacy global-uniqueness lookup. Under the per-user-namespace model
-   * (hq-pro 2026-05-15) this can return any tenant's entity when more
-   * than one user holds the same slug, OR `null` when the caller doesn't
-   * have it but a different user does. Kept on the interface for any
-   * remaining callers, but `provisionCompany` now uses
-   * `checkSlugInMyNamespace` instead — same-slug-different-owner is
-   * legitimate and should NOT trigger reuse of the stranger's entity.
-   */
-  findCompanyBySlug(slug: string): Promise<VaultEntity | null>;
-  /**
-   * Caller-scoped slug availability check via
-   * `GET /entity/check-slug/me?type=company&slug=...`. Returns
-   * `{available: true}` when the caller's namespace
-   * (owned ∪ active-member-of, soft-deleted excluded) doesn't hold the
-   * slug, or `{available: false, conflictingCompanyUid}` when it does
-   * — `provisionCompany` reuses the `conflictingCompanyUid` as the
-   * idempotent entity instead of creating a duplicate.
-   */
-  checkSlugInMyNamespace(slug: string): Promise<{
-    available: boolean;
-    conflictingCompanyUid?: string;
-  }>;
-  /** Fetch a company entity by uid. Used to materialize the entity
-   * after `checkSlugInMyNamespace` reports a same-namespace collision. */
-  getCompanyByUid(uid: string): Promise<VaultEntity>;
-  createCompanyEntity(input: {
-    slug: string;
-    name: string;
-    ownerUid?: string;
-  }): Promise<VaultEntity>;
-}
-
-/** Custom error class so the CLI runner can map to exit codes. */
-export class ProvisionError extends Error {
-  constructor(
-    public readonly code: 1 | 2 | 3,
-    message: string,
-    public readonly partial?: Partial<ProvisionResult>,
-  ) {
-    super(message);
-    this.name = "ProvisionError";
-  }
-}
-
-// ── Validation ───────────────────────────────────────────────────────────────
-
-const SLUG_REGEX = /^[A-Za-z0-9._-]+$/;
-const FORBIDDEN_SLUGS = new Set(["personal", ".", ".."]);
-
-/**
- * Validate a company slug per the contract: alphanumeric / dot / dash / underscore,
- * non-empty, never `"."` or `".."` (path-traversal — would resolve to
- * `companies/` itself or `<hqRoot>` and write outside the intended company
- * directory), and never `"personal"` (auto-provisioned per-user, not promoted
- * via this subcommand).
- *
- * Throws ProvisionError with code=2 on failure.
- */
-export function validateSlug(slug: string): void {
-  if (!slug || slug.trim() === "") {
-    throw new ProvisionError(2, "Slug is required");
-  }
-  if (!SLUG_REGEX.test(slug)) {
-    throw new ProvisionError(
-      2,
-      `Invalid slug "${slug}" — must match ${SLUG_REGEX.source}`,
-    );
-  }
-  if (FORBIDDEN_SLUGS.has(slug)) {
-    const reason =
-      slug === "personal"
-        ? "auto-provisioned per-user, not eligible for cloud promotion"
-        : "path-traversal slug (would resolve to a directory outside the intended company folder)";
-    throw new ProvisionError(2, `Slug "${slug}" is reserved (${reason})`);
-  }
-}
-
-/** Path to the top-level companies manifest file. */
-export function manifestPath(hqRoot: string): string {
-  return path.join(hqRoot, "companies", "manifest.yaml");
-}
-
-/** Path to a company's directory inside the HQ tree. */
-export function companyDirPath(hqRoot: string, slug: string): string {
-  return path.join(hqRoot, "companies", slug);
-}
-
-/** Path to a company's `.hq/config.json`. */
-export function companyConfigPath(hqRoot: string, slug: string): string {
-  return path.join(companyDirPath(hqRoot, slug), ".hq", "config.json");
-}
-
-/**
- * Validate that the company exists in the manifest and on disk.
- *
- * Throws ProvisionError with code=2 if:
- *   - manifest file missing
- *   - manifest is malformed (no `companies` map)
- *   - slug not present under `.companies`
- *   - company is `status: archived`
- *   - `companies/<slug>/` does not exist
- *
- * Strict on purpose — callers that want the "auto-insert a missing entry when
- * the local folder exists" affordance (cloud-provision's fault-tolerant flow)
- * MUST call `ensureManifestEntryForProvision` first. cloud-demote and other
- * sensitive callers depend on this strict failure for typo-catching.
- *
- * Returns the parsed manifest (so the caller can re-use it for the patch step).
- */
-export function validateManifestAndDir(
-  hqRoot: string,
-  slug: string,
-): { manifest: ManifestDoc } {
-  const mPath = manifestPath(hqRoot);
-  if (!fs.existsSync(mPath)) {
-    throw new ProvisionError(
-      2,
-      `companies/manifest.yaml not found at ${mPath}`,
-    );
-  }
-  const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = parseUserYaml<unknown>(raw, mPath);
-  if (
-    !parsed ||
-    typeof parsed !== "object" ||
-    !("companies" in parsed) ||
-    typeof (parsed as ManifestDoc).companies !== "object"
-  ) {
-    throw new ProvisionError(
-      2,
-      `companies/manifest.yaml is malformed — missing top-level .companies map`,
-    );
-  }
-  const manifest = parsed as ManifestDoc;
-  const entry = manifest.companies?.[slug];
-  if (entry === undefined) {
-    throw new ProvisionError(
-      2,
-      `Company "${slug}" not found under .companies in manifest.yaml`,
-    );
-  }
-  if (entry && typeof entry === "object" && entry.status === "archived") {
-    throw new ProvisionError(
-      2,
-      `Company "${slug}" is status=archived — refusing to promote`,
-    );
-  }
-  const dir = companyDirPath(hqRoot, slug);
-  if (!fs.existsSync(dir)) {
-    throw new ProvisionError(
-      2,
-      `Company directory ${dir} does not exist`,
-    );
-  }
-  return { manifest };
-}
-
-/**
- * Provision-only pre-step. If `companies/<slug>/` exists on disk but the slug
- * is absent from `manifest.yaml`, atomically insert an empty entry
- * (`<slug>: {}`) so the downstream `validateManifestAndDir` + `patchManifest`
- * flow has something to operate on. Heals the common folder-only state
- * (manual mkdir, or older tools that didn't patch manifest.yaml) that hq-sync's
- * Connect button used to dead-end on with exit 2.
- *
- * No-op in every other case:
- *   - manifest file missing / malformed (validation will surface)
- *   - slug already present (any value, including null — preserved as-is)
- *   - `companies/<slug>/` does not exist (validation will surface as a typo)
- *
- * This affordance is provision-specific. `cloud-demote` and other strict
- * callers MUST NOT call this — their typo-catching contract depends on
- * `validateManifestAndDir` throwing on missing-slug.
- */
-export function ensureManifestEntryForProvision(
-  hqRoot: string,
-  slug: string,
-): void {
-  const mPath = manifestPath(hqRoot);
-  if (!fs.existsSync(mPath)) return;
-  // Defense-in-depth against path-traversal slugs (`.`, `..`, anything that
-  // resolves outside companies/). validateSlug rejects these upstream, but
-  // this helper is exported and might be called directly by future code —
-  // never auto-insert based on a path that isn't a literal direct child of
-  // `companies/`. fs.realpathSync would also catch symlink-escapes, but the
-  // directory may legitimately not exist yet on disk; path.resolve gives us
-  // the canonical lexical form without a stat call.
-  const companiesDir = path.resolve(hqRoot, "companies");
-  const expected = path.resolve(companiesDir, slug);
-  const expectedParent = path.dirname(expected);
-  if (expectedParent !== companiesDir) return;
-  if (path.basename(expected) !== slug) return;
-  const dir = companyDirPath(hqRoot, slug);
-  // Must be an actual directory, not a stray file. fs.existsSync returns true
-  // for regular files too — without this guard, auto-insert would fire on a
-  // file at `companies/<slug>`, provisionCompany would then create the vault
-  // entity and patch manifest.yaml before writeCompanyConfig's `mkdir -p .hq`
-  // exploded with ENOTDIR. statSync swallows the not-found case so a missing
-  // path is treated the same as before (no auto-insert).
-  let dirStat: fs.Stats;
-  try {
-    dirStat = fs.statSync(dir);
-  } catch {
-    return;
-  }
-  if (!dirStat.isDirectory()) return;
-  const raw = fs.readFileSync(mPath, "utf-8");
-  let parsed: unknown;
-  try {
-    parsed = yaml.load(raw);
-  } catch {
-    return;
-  }
-  if (
-    !parsed ||
-    typeof parsed !== "object" ||
-    !("companies" in parsed) ||
-    typeof (parsed as ManifestDoc).companies !== "object"
-  ) {
-    return;
-  }
-  const doc = parsed as ManifestDoc;
-  if (!doc.companies) doc.companies = {};
-  if (doc.companies[slug] !== undefined) return;
-  doc.companies[slug] = {};
-  const dump = yaml.dump(doc, { lineWidth: -1, noRefs: true });
-  const tmp = `${mPath}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, dump);
-  fs.renameSync(tmp, mPath);
-}
-
-// ── Manifest patching (atomic) ───────────────────────────────────────────────
-
-/**
- * Top-level manifest shape we touch. We preserve all unknown fields — only
- * `cloud_uid` and `bucket_name` under the target slug are mutated.
- */
-export interface ManifestDoc {
-  companies?: Record<string, ManifestCompanyEntry | null>;
-  [k: string]: unknown;
-}
-
-export interface ManifestCompanyEntry {
-  cloud_uid?: string;
-  bucket_name?: string;
-  status?: string;
-  [k: string]: unknown;
-}
-
-/**
- * Atomically patch `companies/manifest.yaml` to set `cloud_uid` + `bucket_name`
- * under the target slug. Read → mutate → temp-write → rename so concurrent
- * readers never see a partially-written file.
- *
- * Skip-if-unchanged: if the target slug already carries the exact
- * `cloud_uid` + `bucket_name`, this is a true no-op — the file is left
- * byte-for-byte intact (comments, ordering, and formatting preserved) and
- * we return `false`. This matters because `yaml.dump` does NOT round-trip
- * comments or the original layout: an unconditional rewrite re-canonicalises
- * the manifest (stripping the `/newcompany` header comment, reflowing keys)
- * on EVERY provision/Connect, even when nothing semantically changed. Each
- * such rewrite is then pushed by the initial-sync step, so the
- * comment-stripped local form perpetually diverges from any peer/cloud copy
- * that still holds the commented form — manifesting as a recurring HQ Sync
- * conflict loop on `companies/manifest.yaml` that re-fires every sync. Only
- * writing when a value actually changes lets the two forms converge.
- *
- * Returns true if the file was written, false if it was already current.
- */
-export function patchManifest(
-  hqRoot: string,
-  slug: string,
-  cloudUid: string,
-  bucketName: string,
-): boolean {
-  const mPath = manifestPath(hqRoot);
-  const raw = fs.readFileSync(mPath, "utf-8");
-  const parsed = parseUserYaml<ManifestDoc | null>(raw, mPath) ?? { companies: {} };
-  if (!parsed.companies) parsed.companies = {};
-  const existing = parsed.companies[slug];
-  // Preserve null / object / unknown — promote null → {} so we can write keys.
-  const entry: ManifestCompanyEntry =
-    existing && typeof existing === "object" ? { ...existing } : {};
-
-  // No-op guard: both fields already match → leave the on-disk file (and its
-  // comments) untouched so a re-provision can't churn the manifest and seed a
-  // sync conflict loop.
-  if (entry.cloud_uid === cloudUid && entry.bucket_name === bucketName) {
-    return false;
-  }
-
-  entry.cloud_uid = cloudUid;
-  entry.bucket_name = bucketName;
-  parsed.companies[slug] = entry;
-
-  const dump = yaml.dump(parsed, { lineWidth: -1, noRefs: true });
-  const tmp = `${mPath}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, dump);
-  fs.renameSync(tmp, mPath);
-  return true;
-}
-
-// ── .hq/config.json writing (atomic) ─────────────────────────────────────────
-
-/**
- * Atomically write `companies/<slug>/.hq/config.json` with the cloud-promotion
- * config. Creates the parent `.hq/` directory if needed. Temp-write + rename
- * so concurrent readers never see a partial file.
- *
- * Idempotent: a re-run with the same inputs writes byte-identical output.
- */
-export function writeCompanyConfig(
-  hqRoot: string,
-  slug: string,
-  config: CompanyConfig,
-): boolean {
-  const cPath = companyConfigPath(hqRoot, slug);
-  const dir = path.dirname(cPath);
-  fs.mkdirSync(dir, { recursive: true });
-  const body = JSON.stringify(config, null, 2) + "\n";
-  const tmp = `${cPath}.tmp.${process.pid}`;
-  fs.writeFileSync(tmp, body);
-  fs.renameSync(tmp, cPath);
-  return true;
-}
-
-// ── Vault HTTP client (real impl) ────────────────────────────────────────────
-
-/**
- * Default vault HTTP client backed by global `fetch`. Uses the `/v1/entities`
- * route surface (matches AppBar `vault_client.rs` and hq-pro handler routes).
- *
- * Note: the hq-pro handler.ts uses `/entity` (singular, no `/v1/`); the API
- * Gateway in front of it exposes the same handlers under `/v1/entities/*`
- * (plural) — the deployed surface is the prefixed form, which is what
- * AppBar (`vault_client.rs`) and the architecture audit document. We use
- * the deployed `/v1/entities/*` form here.
- */
-export function createDefaultVaultClient(
-  apiUrl: string,
-  accessToken: string,
-): VaultClient {
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${accessToken}`,
-  };
-  return {
-    async listMyPersonEntities(): Promise<VaultEntity[]> {
-      const url = `${apiUrl.replace(/\/$/, "")}/entity/by-type/person`;
-      const res = await fetch(url, { method: "GET", headers });
-      if (res.status === 404) return [];
-      if (!res.ok) {
-        const body = await safeBody(res);
-        throw new ProvisionError(
-          1,
-          `Vault GET /entity/by-type/person failed: ${res.status} ${res.statusText} — ${body}`,
-        );
-      }
-      const data = (await res.json()) as { entities?: VaultEntity[] };
-      return data.entities ?? [];
-    },
-    async findCompanyBySlug(slug: string): Promise<VaultEntity | null> {
-      const url = `${apiUrl.replace(/\/$/, "")}/entity/by-slug/company/${encodeURIComponent(
-        slug,
-      )}`;
-      const res = await fetch(url, { method: "GET", headers });
-      if (res.status === 404) return null;
-      if (!res.ok) {
-        const body = await safeBody(res);
-        throw new ProvisionError(
-          1,
-          `Vault GET by-slug failed: ${res.status} ${res.statusText} — ${body}`,
-        );
-      }
-      const data = (await res.json()) as { entity?: VaultEntity };
-      if (!data.entity) {
-        throw new ProvisionError(
-          1,
-          `Vault GET by-slug returned 200 with no entity body`,
-        );
-      }
-      return data.entity;
-    },
-    async checkSlugInMyNamespace(slug: string): Promise<{
-      available: boolean;
-      conflictingCompanyUid?: string;
-    }> {
-      const url = `${apiUrl.replace(/\/$/, "")}/entity/check-slug/me?type=company&slug=${encodeURIComponent(
-        slug,
-      )}`;
-      const res = await fetch(url, { method: "GET", headers });
-      if (!res.ok) {
-        const body = await safeBody(res);
-        throw new ProvisionError(
-          1,
-          `Vault GET /entity/check-slug/me failed: ${res.status} ${res.statusText} — ${body}`,
-        );
-      }
-      return (await res.json()) as {
-        available: boolean;
-        conflictingCompanyUid?: string;
-      };
-    },
-    async getCompanyByUid(uid: string): Promise<VaultEntity> {
-      const url = `${apiUrl.replace(/\/$/, "")}/entity/${encodeURIComponent(uid)}`;
-      const res = await fetch(url, { method: "GET", headers });
-      if (!res.ok) {
-        const body = await safeBody(res);
-        throw new ProvisionError(
-          1,
-          `Vault GET /entity/${uid} failed: ${res.status} ${res.statusText} — ${body}`,
-        );
-      }
-      const data = (await res.json()) as { entity?: VaultEntity };
-      if (!data.entity) {
-        throw new ProvisionError(
-          1,
-          `Vault GET /entity/${uid} returned 200 with no entity body`,
-        );
-      }
-      return data.entity;
-    },
-    async createCompanyEntity(input: {
-      slug: string;
-      name: string;
-      ownerUid?: string;
-    }): Promise<VaultEntity> {
-      const url = `${apiUrl.replace(/\/$/, "")}/entity`;
-      const body: Record<string, unknown> = {
-        type: "company",
-        slug: input.slug,
-        name: input.name,
-      };
-      if (input.ownerUid) body.ownerUid = input.ownerUid;
-      const res = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-      });
-      if (!res.ok) {
-        const text = await safeBody(res);
-        // 409 SLUG_IN_USE_FOR_PERSON: the caller already has the slug
-        // in their namespace (owned ∪ active-member-of). Under the
-        // per-user-namespace model this is the new same-user-collision
-        // signal — distinct from the legacy global EntityAlreadyExists.
-        // The CLI normally reaches `createCompanyEntity` only after
-        // `checkSlugInMyNamespace` reported `available: true`, so a
-        // 409 here means a race between the pre-check and the POST.
-        // Surface the response body verbatim so the caller can see the
-        // `code` + `conflictingCompanyUid` and resolve / retry.
-        throw new ProvisionError(
-          1,
-          `Vault POST /entity failed: ${res.status} ${res.statusText} — ${text}`,
-        );
-      }
-      const data = (await res.json()) as { entity?: VaultEntity };
-      if (!data.entity) {
-        throw new ProvisionError(
-          1,
-          `Vault POST /entity returned ${res.status} with no entity body`,
-        );
-      }
-      return data.entity;
-    },
-  };
-}
-
-async function safeBody(res: Response): Promise<string> {
-  try {
-    return await res.text();
-  } catch {
-    return "<no body>";
-  }
-}
-
-// ── Default initial-sync runner (wraps share()) ──────────────────────────────
-
-async function defaultRunInitialSync(args: InitialSyncArgs): Promise<{
-  filesUploaded: number;
-  bytesUploaded: number;
-}> {
-  const result = await share({
-    paths: [companyDirPath(args.hqRoot, args.slug)],
-    company: args.slug,
-    message: `hq cloud provision:${args.slug}`,
-    onConflict: "keep",
-    vaultConfig: buildVaultConfig(args.accessToken),
-    hqRoot: args.hqRoot,
-  });
-  return {
-    filesUploaded: result.filesUploaded,
-    bytesUploaded: result.bytesUploaded,
-  };
-}
-
-// ── Orchestrator ─────────────────────────────────────────────────────────────
-
-/**
- * Run the full 9-step provision flow. Returns a `ProvisionResult` on success
- * (including partial success — sync failure after entity provisioned).
- *
- * Throws `ProvisionError` for terminal failures with the right exit code.
- *
- * All side effects (HTTP calls, file writes, sync) flow through injected
- * helpers so unit tests can fully exercise the flow without network or disk.
- */
-export async function provisionCompany(
-  options: ProvisionCompanyOptions,
-): Promise<ProvisionResult> {
-  const log = options.log ?? ((msg: string) => process.stderr.write(`[hq cloud provision] ${msg}\n`));
-
-  // Step 1+2+3: validate slug, auto-heal a folder-only manifest, then validate
-  // the resulting manifest + dir. The auto-heal is provision-specific: it
-  // inserts an empty entry when companies/<slug>/ exists on disk but the slug
-  // is missing from manifest.yaml. validateManifestAndDir stays strict so
-  // other callers (cloud-demote) keep their typo-catching guard.
-  validateSlug(options.slug);
-  ensureManifestEntryForProvision(options.hqRoot, options.slug);
-  validateManifestAndDir(options.hqRoot, options.slug);
-  log(`validated slug=${options.slug}`);
-
-  // Step 4: auth — defer to injected resolver (default: ensureCognitoToken)
-  const accessToken = options.resolveAccessToken
-    ? await options.resolveAccessToken()
-    : await ensureCognitoToken();
-  log(`acquired Cognito access token`);
-
-  // Step 5: GET-then-POST for idempotency
-  const vaultClient =
-    options.vaultClient ??
-    createDefaultVaultClient(options.vaultApiUrl, accessToken);
-
-  // Pre-flight: caller MUST have a registered person entity. Without one,
-  // the initial-sync step at the end of this flow (STS /sts/vend) returns
-  // 403 "no person entity" and leaves the operator with a half-built cloud
-  // company — vault entity created, S3 bucket provisioned, manifest patched,
-  // .hq/config.json written, but nothing actually syncing. This was the
-  // primary failure mode in the 2026-05-14 setup-session deep dive
-  // (Joey Muller / sum-digital).
-  //
-  // Failing here, BEFORE any cloud-side resource creation, leaves the operator
-  // with no cleanup work — they fix the underlying onboarding gap (run
-  // `hq onboard` / sign in with the correct federated identity) and re-run
-  // `hq cloud provision company <slug>` cleanly.
-  const persons = await vaultClient.listMyPersonEntities();
-  if (persons.length === 0) {
-    throw new ProvisionError(
-      2,
-      'No person entity found for this Cognito identity. Run `hq onboard` first to create your HQ identity, then re-run `hq cloud provision company`. (Provision was halted before any cloud-side resources were created.)',
-    );
-  }
-  log(`pre-flight ok — caller has ${persons.length} person entity(ies)`);
-
-  // Per-user-namespace-aware reuse-or-create. Replaces the legacy
-  // global `findCompanyBySlug` lookup, which under the per-user model
-  // (hq-pro 2026-05-15) returns ANY tenant's entity when more than one
-  // user holds the same slug, OR null when a different user has it —
-  // both wrong for the CLI's "reuse mine, or create" intent.
-  //
-  // `--owner` override: `options.ownerUid`, when set, lets a caller
-  // create the entity under a DIFFERENT person's ownership (e.g. an
-  // admin provisioning on behalf of someone). `/entity/check-slug/me`
-  // answers about the CALLER's namespace, not the target owner's, so
-  // the pre-check is meaningless in that case. Codex P2 on PR 7
-  // flagged this. The gate: only run the namespace check when the
-  // owner is the caller (or defaulted to the caller — i.e. no
-  // --owner supplied). On override, fall through to
-  // `createCompanyEntity` and let the server's authoritative 409
-  // (which IS scoped to the target's namespace, per the
-  // callerIsOwner gate on POST /entity in hq-pro PR 67) surface any
-  // real conflict.
-  //
-  // `callerIsOwner` is `true` whenever `options.ownerUid` is unset
-  // (defaults to caller server-side) OR — when set — happens to
-  // match the caller's own person UID(s) from `listMyPersonEntities`.
-  const callerOwnedUids = new Set(persons.map((p) => p.uid));
-  const callerIsOwner =
-    !options.ownerUid || callerOwnedUids.has(options.ownerUid);
-
-  let entity: VaultEntity;
-  let createdEntity = false;
-  if (callerIsOwner) {
-    const slugCheck = await vaultClient.checkSlugInMyNamespace(options.slug);
-    if (!slugCheck.available && slugCheck.conflictingCompanyUid) {
-      log(
-        `reusing existing vault entity uid=${slugCheck.conflictingCompanyUid} (slug already in caller's namespace)`,
-      );
-      entity = await vaultClient.getCompanyByUid(
-        slugCheck.conflictingCompanyUid,
-      );
-    } else {
-      log(`slug available in caller's namespace — creating vault entity`);
-      entity = await vaultClient.createCompanyEntity({
-        slug: options.slug,
-        name: options.name ?? options.slug,
-        ownerUid: options.ownerUid,
-      });
-      createdEntity = true;
-      log(`created vault entity uid=${entity.uid}`);
-    }
-  } else {
-    log(
-      `--owner ${options.ownerUid} differs from caller's person(s); skipping namespace pre-check (server authoritatively gates per-target-namespace)`,
-    );
-    entity = await vaultClient.createCompanyEntity({
-      slug: options.slug,
-      name: options.name ?? options.slug,
-      ownerUid: options.ownerUid,
-    });
-    createdEntity = true;
-    log(`created vault entity uid=${entity.uid}`);
-  }
-
-  if (!entity.bucketName) {
-    // Vault returned an entity without a bucket — this would happen if the
-    // provisioning Lambda asynchronously failed. We have a `cloud_uid` but
-    // no `bucket_name` to write to disk. Surface as a vault error since the
-    // entity exists but is incomplete.
-    throw new ProvisionError(
-      1,
-      `Vault entity ${entity.uid} has no bucketName — provisioning incomplete`,
-      {
-        ok: false,
-        company_slug: options.slug,
-        cloud_uid: entity.uid,
-        bucket_name: "",
-        vault_api_url: options.vaultApiUrl,
-        kms_key_id: entity.kmsKeyId ?? null,
-        created_entity: createdEntity,
-        manifest_patched: false,
-        config_written: false,
-        initial_sync: { ok: false, error: "entity has no bucketName" },
-      },
-    );
-  }
-
-  const cloudUid = entity.uid;
-  const bucketName = entity.bucketName;
-  const kmsKeyId = entity.kmsKeyId ?? null;
-
-  // Step 6: patch manifest atomically. Skip-if-unchanged returns false when
-  // the manifest already carries this slug's cloud_uid + bucket_name, so we
-  // report the honest outcome rather than always claiming a patch.
-  const manifestPatched = patchManifest(
-    options.hqRoot,
-    options.slug,
-    cloudUid,
-    bucketName,
-  );
-  log(
-    manifestPatched
-      ? `patched companies/manifest.yaml`
-      : `companies/manifest.yaml already current — left untouched`,
-  );
-
-  // Step 7: write .hq/config.json atomically
-  writeCompanyConfig(options.hqRoot, options.slug, {
-    companyUid: cloudUid,
-    companySlug: options.slug,
-    bucketName,
-    vaultApiUrl: options.vaultApiUrl,
-  });
-  log(`wrote companies/${options.slug}/.hq/config.json`);
-
-  // Step 8: trigger initial sync (failure ⇒ exit 3 with cloud_uid populated).
-  // Skipped when caller passed --skip-initial-sync (e.g. AppBar HQ Sync, which
-  // owns its own STS-credentialed upload pipeline + Tauri progress events).
-  let initialSync: ProvisionResult["initial_sync"];
-  if (options.skipInitialSync) {
-    log(`skipping initial sync (--skip-initial-sync)`);
-    initialSync = { skipped: true };
-  } else {
-    const runner = options.runInitialSync ?? defaultRunInitialSync;
-    try {
-      log(`triggering initial sync via share()`);
-      const sync = await runner({
-        slug: options.slug,
-        hqRoot: options.hqRoot,
-        accessToken,
-        vaultApiUrl: options.vaultApiUrl,
-      });
-      initialSync = {
-        ok: true,
-        files_uploaded: sync.filesUploaded,
-        bytes_uploaded: sync.bytesUploaded,
-      };
-      log(
-        `initial sync complete — files=${sync.filesUploaded} bytes=${sync.bytesUploaded}`,
-      );
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      log(`initial sync failed: ${msg}`);
-      throw new ProvisionError(3, `Initial sync failed: ${msg}`, {
-        ok: false,
-        company_slug: options.slug,
-        cloud_uid: cloudUid,
-        bucket_name: bucketName,
-        vault_api_url: options.vaultApiUrl,
-        kms_key_id: kmsKeyId,
-        created_entity: createdEntity,
-        manifest_patched: true,
-        config_written: true,
-        initial_sync: { ok: false, error: msg },
-      });
-    }
-  }
-
-  return {
-    ok: true,
-    company_slug: options.slug,
-    cloud_uid: cloudUid,
-    bucket_name: bucketName,
-    vault_api_url: options.vaultApiUrl,
-    kms_key_id: kmsKeyId,
-    created_entity: createdEntity,
-    manifest_patched: manifestPatched,
-    config_written: true,
-    initial_sync: initialSync,
-  };
-}
-
-// ── Commander wiring ─────────────────────────────────────────────────────────
-
-/**
- * Register `provision company <slug>` under a `cloud` subcommand group.
- *
- * Wired in `src/index.ts` via `registerCloudProvisionCommands(cloudCmd)` where
- * `cloudCmd` is the top-level `hq cloud` command group.
- */
-export function registerCloudProvisionCommands(program: Command): void {
-  const provisionCmd = program
-    .command("provision")
-    .description("Provision a cloud-backed entity (entity + bucket + initial sync)");
-
-  provisionCmd
-    .command("company")
-    .description(
-      "Promote a local company to a cloud-backed entity (idempotent). " +
-        "Provisions the vault entity if missing, patches manifest.yaml, " +
-        "writes .hq/config.json, and triggers an initial sync.",
-    )
-    .argument("<slug>", "Company slug (must match a top-level key in companies/manifest.yaml)")
-    .option("--name <name>", "Display name for the entity (default: slug)")
-    .option("--owner <uid>", "Owner person UID (default: current Cognito user sub)")
-    .option(
-      "--hq-root <path>",
-      `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`,
-      DEFAULT_HQ_ROOT,
-    )
-    .option(
-      "--vault-api-url <url>",
-      `Vault API URL (default: ${DEFAULT_VAULT_API_URL})`,
-      DEFAULT_VAULT_API_URL,
-    )
-    .option(
-      "--skip-initial-sync",
-      "Skip the post-provision share() initial sync. Use when the caller " +
-        "(e.g. AppBar HQ Sync) has its own upload pipeline. Result includes " +
-        "{ initial_sync: { skipped: true } } when set.",
-    )
-    .action(
-      async (
-        slug: string,
-        options: {
-          name?: string;
-          owner?: string;
-          hqRoot: string;
-          vaultApiUrl: string;
-          skipInitialSync?: boolean;
-        },
-      ) => {
-        try {
-          const result = await provisionCompany({
-            slug,
-            name: options.name,
-            ownerUid: options.owner,
-            hqRoot: options.hqRoot,
-            vaultApiUrl: options.vaultApiUrl,
-            skipInitialSync: options.skipInitialSync,
-          });
-          // Final stdout line — single JSON document for downstream consumers
-          process.stdout.write(JSON.stringify(result) + "\n");
-          process.exit(0);
-        } catch (err) {
-          if (err instanceof ProvisionError) {
-            // Partial-success path (code 3): cloud_uid is known; emit JSON to stdout
-            // so downstream consumers can capture it for retry.
-            if (err.partial) {
-              process.stdout.write(JSON.stringify(err.partial) + "\n");
-            }
-            process.stderr.write(
-              chalk.red(`[hq cloud provision] ${err.message}\n`),
-            );
-            process.exit(err.code);
-          }
-          process.stderr.write(
-            chalk.red(
-              `[hq cloud provision] Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`,
-            ),
-          );
-          process.exit(1);
-        }
-      },
-    );
-}