@indigoai-us/hq-cli 5.9.0 → 5.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [5.10.0] — 2026-05-04
+
+### Added
+
+- **`hq cloud demote company <slug>` subcommand** — inverse of
+  `hq cloud provision company`. Converts a cloud-backed company back to local-only
+  after its entity has been soft-tombstoned in hq-console (Settings → Delete company).
+  Removes `companies/<slug>/.hq/config.json`, flips `cloud: true → false` in
+  `companies/<slug>/company.yaml`, and strips `cloud_uid` + `bucket_name` from
+  `companies/manifest.yaml`. Default safety check verifies the cloud entity is
+  `deleted=true`; `--force` skips the check (used by AppBar HQ Sync's Path A after
+  it has already verified). All side-effects atomic + idempotent. Exit codes mirror
+  `cloud provision` (0 ok, 1 vault HTTP, 2 validation).
+
 ## [5.9.0] — 2026-05-04
 
 ### Added

package/dist/commands/cloud-demote.d.ts

@@ -0,0 +1,90 @@
+/**
+ * `hq cloud demote company <slug>` — convert a cloud-backed company back to
+ * local-only after hq-pro has soft-tombstoned its entity (Settings → Delete
+ * company in hq-console).
+ *
+ * Inverse of `hq cloud provision company <slug>`. Both commands live here in
+ * hq-cli so the file-touching contract (manifest patch + per-folder config
+ * write + company.yaml mutation) is single-sourced. AppBar HQ Sync's Path A
+ * shells out to this command on the `deleted=true` branch instead of
+ * re-implementing the file mutations in Rust.
+ *
+ * Side-effects (all atomic + idempotent):
+ *   1. Remove `companies/<slug>/.hq/config.json`.
+ *   2. Flip `cloud: true → false` in `companies/<slug>/company.yaml`. Without
+ *      this flip the next `provisionCompany` would re-mint a fresh cloud
+ *      company — exactly what the user just deleted.
+ *   3. Strip `cloud_uid` + `bucket_name` from `companies/manifest.yaml`'s
+ *      `companies.<slug>` entry. The slug entry + other fields stay.
+ *
+ * Safety check (default on): `findCompanyBySlug` MUST return an entity with
+ * `deleted: true`. A live entity, or no entity at all, refuses with code 2.
+ * `--force` skips the network call (AppBar passes it because Path A just
+ * checked).
+ *
+ * Exit codes (mirrors cloud-provision):
+ *   0 — success or idempotent no-op.
+ *   1 — vault HTTP failure during the safety check.
+ *   2 — validation (bad slug, missing dir/manifest, cloud not deleted).
+ */
+import { Command } from "commander";
+import { type VaultClient } from "./cloud-provision.js";
+/** Final stdout JSON shape. AppBar parses this. */
+export interface DemoteResult {
+    ok: boolean;
+    company_slug: string;
+    /** True if `.hq/config.json` was actually deleted (false if absent). */
+    config_removed: boolean;
+    /** True if `company.yaml`'s `cloud` was changed (true→false or absent→false). */
+    yaml_flipped: boolean;
+    /** True if manifest had `cloud_uid` / `bucket_name` to strip. */
+    manifest_stripped: boolean;
+    /**
+     * `true` when the cloud entity verified as `deleted=true`. `null` when
+     * `--force` was used and the verify was skipped. (`false` is unreachable —
+     * a non-deleted entity throws code 2 before reaching the result.)
+     */
+    cloud_was_deleted: boolean | null;
+}
+export interface DemoteCompanyOptions {
+    slug: string;
+    hqRoot: string;
+    vaultApiUrl: string;
+    /** Skip the `findCompanyBySlug` safety check. AppBar uses this. */
+    force?: boolean;
+    /** Injected vault HTTP client (override for tests). */
+    vaultClient?: VaultClient;
+    /** Injected access-token resolver (override for tests). */
+    resolveAccessToken?: () => Promise<string>;
+}
+/**
+ * Flip `cloud: true → false` in `companies/<slug>/company.yaml`. All other
+ * keys + ordering preserved (js-yaml round-trip). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (file missing, or
+ * `cloud` was already `false`).
+ *
+ * NOTE: js-yaml doesn't preserve comments, but this matches what
+ * `patchManifest` already does — accepted trade-off.
+ */
+export declare function flipCompanyYamlCloudOff(hqRoot: string, slug: string): boolean;
+/**
+ * Remove `cloud_uid` + `bucket_name` from `companies.<slug>` in
+ * `companies/manifest.yaml`. The slug entry is preserved (other fields like
+ * `name`/`status`/`path` stay). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (manifest missing,
+ * slug missing, or both fields already absent).
+ */
+export declare function stripManifestCloudForSlug(hqRoot: string, slug: string): boolean;
+/**
+ * Run the full demote flow. Returns a `DemoteResult` on success; throws
+ * `ProvisionError` (codes 1 or 2) on any failure.
+ */
+export declare function demoteCompany(options: DemoteCompanyOptions): Promise<DemoteResult>;
+/**
+ * Register `demote company <slug>` under the `cloud` command group. Wired in
+ * `src/index.ts` alongside `registerCloudProvisionCommands(cloudCmd)`.
+ */
+export declare function registerCloudDemoteCommands(program: Command): void;
+//# sourceMappingURL=cloud-demote.d.ts.map

package/dist/commands/cloud-demote.js

@@ -0,0 +1,193 @@
+/**
+ * `hq cloud demote company <slug>` — convert a cloud-backed company back to
+ * local-only after hq-pro has soft-tombstoned its entity (Settings → Delete
+ * company in hq-console).
+ *
+ * Inverse of `hq cloud provision company <slug>`. Both commands live here in
+ * hq-cli so the file-touching contract (manifest patch + per-folder config
+ * write + company.yaml mutation) is single-sourced. AppBar HQ Sync's Path A
+ * shells out to this command on the `deleted=true` branch instead of
+ * re-implementing the file mutations in Rust.
+ *
+ * Side-effects (all atomic + idempotent):
+ *   1. Remove `companies/<slug>/.hq/config.json`.
+ *   2. Flip `cloud: true → false` in `companies/<slug>/company.yaml`. Without
+ *      this flip the next `provisionCompany` would re-mint a fresh cloud
+ *      company — exactly what the user just deleted.
+ *   3. Strip `cloud_uid` + `bucket_name` from `companies/manifest.yaml`'s
+ *      `companies.<slug>` entry. The slug entry + other fields stay.
+ *
+ * Safety check (default on): `findCompanyBySlug` MUST return an entity with
+ * `deleted: true`. A live entity, or no entity at all, refuses with code 2.
+ * `--force` skips the network call (AppBar passes it because Path A just
+ * checked).
+ *
+ * Exit codes (mirrors cloud-provision):
+ *   0 — success or idempotent no-op.
+ *   1 — vault HTTP failure during the safety check.
+ *   2 — validation (bad slug, missing dir/manifest, cloud not deleted).
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6b5cd717-bba0-5dd4-a743-a070e8a62a6b")}catch(e){}}();
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import chalk from "chalk";
+import { ProvisionError, companyConfigPath, companyDirPath, createDefaultVaultClient, manifestPath, validateManifestAndDir, validateSlug, } from "./cloud-provision.js";
+import { DEFAULT_HQ_ROOT, DEFAULT_VAULT_API_URL, ensureCognitoToken, } from "../utils/cognito-session.js";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Flip `cloud: true → false` in `companies/<slug>/company.yaml`. All other
+ * keys + ordering preserved (js-yaml round-trip). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (file missing, or
+ * `cloud` was already `false`).
+ *
+ * NOTE: js-yaml doesn't preserve comments, but this matches what
+ * `patchManifest` already does — accepted trade-off.
+ */
+export function flipCompanyYamlCloudOff(hqRoot, slug) {
+    const yPath = path.join(companyDirPath(hqRoot, slug), "company.yaml");
+    if (!fs.existsSync(yPath))
+        return false;
+    const raw = fs.readFileSync(yPath, "utf-8");
+    const parsed = yaml.load(raw) ?? {};
+    if (parsed.cloud === false)
+        return false;
+    parsed.cloud = false;
+    const dump = yaml.dump(parsed, { lineWidth: -1, noRefs: true });
+    const tmp = `${yPath}.tmp.${process.pid}`;
+    fs.writeFileSync(tmp, dump);
+    fs.renameSync(tmp, yPath);
+    return true;
+}
+/**
+ * Remove `cloud_uid` + `bucket_name` from `companies.<slug>` in
+ * `companies/manifest.yaml`. The slug entry is preserved (other fields like
+ * `name`/`status`/`path` stay). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (manifest missing,
+ * slug missing, or both fields already absent).
+ */
+export function stripManifestCloudForSlug(hqRoot, slug) {
+    const mPath = manifestPath(hqRoot);
+    if (!fs.existsSync(mPath))
+        return false;
+    const raw = fs.readFileSync(mPath, "utf-8");
+    const parsed = yaml.load(raw) ?? {};
+    const companies = parsed.companies;
+    if (!companies || !(slug in companies))
+        return false;
+    const entry = companies[slug];
+    if (!entry || typeof entry !== "object")
+        return false;
+    const obj = entry;
+    const hadCloudUid = "cloud_uid" in obj;
+    const hadBucketName = "bucket_name" in obj;
+    if (!hadCloudUid && !hadBucketName)
+        return false;
+    delete obj.cloud_uid;
+    delete obj.bucket_name;
+    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;
+}
+// ── Orchestrator ─────────────────────────────────────────────────────────────
+/**
+ * Run the full demote flow. Returns a `DemoteResult` on success; throws
+ * `ProvisionError` (codes 1 or 2) on any failure.
+ */
+export async function demoteCompany(options) {
+    validateSlug(options.slug);
+    // Fails with code 2 if the manifest is missing/malformed, the slug is not
+    // present under `.companies`, or `companies/<slug>/` doesn't exist on disk.
+    // Without this, a `--force` demote against a missing or renamed slug would
+    // be a silent no-op (all helpers return false but we'd still report ok=true).
+    validateManifestAndDir(options.hqRoot, options.slug);
+    let cloudWasDeleted = null;
+    if (!options.force) {
+        const accessToken = options.resolveAccessToken
+            ? await options.resolveAccessToken()
+            : await ensureCognitoToken();
+        const client = options.vaultClient ??
+            createDefaultVaultClient(options.vaultApiUrl, accessToken);
+        let entity;
+        try {
+            entity = await client.findCompanyBySlug(options.slug);
+        }
+        catch (err) {
+            if (err instanceof ProvisionError)
+                throw err;
+            throw new ProvisionError(1, `Vault GET by-slug failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!entity) {
+            throw new ProvisionError(2, `Refusing to demote '${options.slug}': no cloud entity found. Pass --force to demote anyway.`);
+        }
+        // `deleted` is added by hq-pro and isn't in the static VaultEntity type.
+        const deleted = entity.deleted === true;
+        if (!deleted) {
+            throw new ProvisionError(2, `Refusing to demote '${options.slug}': cloud entity is not deleted (uid=${entity.uid}). Pass --force to demote anyway.`);
+        }
+        cloudWasDeleted = true;
+    }
+    const cPath = companyConfigPath(options.hqRoot, options.slug);
+    let configRemoved = false;
+    if (fs.existsSync(cPath)) {
+        fs.rmSync(cPath);
+        configRemoved = true;
+    }
+    const yamlFlipped = flipCompanyYamlCloudOff(options.hqRoot, options.slug);
+    const manifestStripped = stripManifestCloudForSlug(options.hqRoot, options.slug);
+    return {
+        ok: true,
+        company_slug: options.slug,
+        config_removed: configRemoved,
+        yaml_flipped: yamlFlipped,
+        manifest_stripped: manifestStripped,
+        cloud_was_deleted: cloudWasDeleted,
+    };
+}
+// ── Commander wiring ─────────────────────────────────────────────────────────
+/**
+ * Register `demote company <slug>` under the `cloud` command group. Wired in
+ * `src/index.ts` alongside `registerCloudProvisionCommands(cloudCmd)`.
+ */
+export function registerCloudDemoteCommands(program) {
+    const demoteCmd = program
+        .command("demote")
+        .description("Demote a cloud-backed entity back to local-only");
+    demoteCmd
+        .command("company")
+        .description("Demote a cloud-backed company to local-only after the cloud entity " +
+        "has been soft-tombstoned in hq-console. Removes .hq/config.json, " +
+        "flips company.yaml `cloud: false`, and strips the manifest cloud refs.")
+        .argument("<slug>", "Company slug")
+        .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("--force", "Skip the safety check that the cloud entity is actually deleted=true. " +
+        "AppBar HQ Sync passes this because its Path A just verified.")
+        .action(async (slug, options) => {
+        try {
+            const result = await demoteCompany({
+                slug,
+                hqRoot: options.hqRoot,
+                vaultApiUrl: options.vaultApiUrl,
+                force: options.force,
+            });
+            process.stdout.write(JSON.stringify(result) + "\n");
+            process.exit(0);
+        }
+        catch (err) {
+            if (err instanceof ProvisionError) {
+                process.stderr.write(chalk.red(`[hq cloud demote] ${err.message}\n`));
+                process.exit(err.code);
+            }
+            process.stderr.write(chalk.red(`[hq cloud demote] Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=cloud-demote.js.map
+//# debugId=6b5cd717-bba0-5dd4-a743-a070e8a62a6b

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ad8b9496-9cb2-5e12-ae08-5b29ef77c209")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ebc3116c-f836-550a-b5bb-4a74bce24abc")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -12,6 +12,7 @@ import { registerListCommand } from "./commands/list.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
+import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
 import { registerLogoutCommand } from "./commands/logout.js";
 import { registerWhoamiCommand } from "./commands/whoami.js";
@@ -64,6 +65,7 @@ const cloudCmd = program
     .command("cloud")
     .description("Cloud commands — provision entities and manage cloud-backed companies");
 registerCloudProvisionCommands(cloudCmd);
+registerCloudDemoteCommands(cloudCmd);
 // Team commands (top-level)
 registerTeamSyncCommand(program);
 // Auth commands (top-level — Cognito OAuth)
@@ -94,4 +96,4 @@ registerOnboardCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=ad8b9496-9cb2-5e12-ae08-5b29ef77c209
+//# debugId=ebc3116c-f836-550a-b5bb-4a74bce24abc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.9.0",
+  "version": "5.10.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

package/src/commands/cloud-demote.test.ts

@@ -0,0 +1,401 @@
+/**
+ * Unit tests for `hq cloud demote company <slug>` (cloud-demote.ts).
+ *
+ * Mirrors the cloud-provision test layout: tmp HQ root per test, helpers
+ * seed manifests + company yaml + .hq/config.json, then the orchestrator
+ * runs with an injected `findCompanyBySlug`.
+ *
+ * Coverage:
+ *   - flipCompanyYamlCloudOff — atomic mutation, preserves other keys
+ *   - stripManifestCloudForSlug — removes cloud_uid + bucket_name only
+ *   - demoteCompany — full orchestrator (verify + side-effects + JSON shape)
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+
+import {
+  ProvisionError,
+  manifestPath,
+  companyDirPath,
+  companyConfigPath,
+  type VaultEntity,
+} from "./cloud-provision.js";
+import {
+  demoteCompany,
+  flipCompanyYamlCloudOff,
+  stripManifestCloudForSlug,
+  type DemoteResult,
+} from "./cloud-demote.js";
+
+// ── Test fixtures ────────────────────────────────────────────────────────────
+
+let tmpRoot: string;
+
+function seedManifest(
+  root: string,
+  companies: Record<string, Record<string, unknown> | null> = {
+    acme: {
+      name: "Acme",
+      cloud_uid: "cmp_old",
+      bucket_name: "hq-vault-cmp-old",
+      status: "active",
+    },
+  },
+): void {
+  const mPath = manifestPath(root);
+  fs.mkdirSync(path.dirname(mPath), { recursive: true });
+  fs.writeFileSync(mPath, yaml.dump({ companies }));
+}
+
+function seedCompanyDir(root: string, slug: string, yamlBody?: string): void {
+  const dir = companyDirPath(root, slug);
+  fs.mkdirSync(dir, { recursive: true });
+  if (yamlBody !== undefined) {
+    fs.writeFileSync(path.join(dir, "company.yaml"), yamlBody);
+  }
+}
+
+function seedCompanyConfig(root: string, slug: string): void {
+  const cPath = companyConfigPath(root, slug);
+  fs.mkdirSync(path.dirname(cPath), { recursive: true });
+  fs.writeFileSync(
+    cPath,
+    JSON.stringify(
+      {
+        companyUid: "cmp_old",
+        companySlug: slug,
+        bucketName: "hq-vault-cmp-old",
+        vaultApiUrl: "https://v",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function readManifest(root: string): { companies?: Record<string, unknown> } {
+  return yaml.load(fs.readFileSync(manifestPath(root), "utf-8")) as {
+    companies?: Record<string, unknown>;
+  };
+}
+
+function readCompanyYaml(root: string, slug: string): Record<string, unknown> {
+  return yaml.load(
+    fs.readFileSync(path.join(companyDirPath(root, slug), "company.yaml"), "utf-8"),
+  ) as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "hq-demote-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+// ── flipCompanyYamlCloudOff ──────────────────────────────────────────────────
+
+describe("flipCompanyYamlCloudOff", () => {
+  it("flips cloud: true → false and preserves other keys", () => {
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\nname: Acme\nfoo: bar\n");
+    const changed = flipCompanyYamlCloudOff(tmpRoot, "acme");
+    expect(changed).toBe(true);
+    const after = readCompanyYaml(tmpRoot, "acme");
+    expect(after.cloud).toBe(false);
+    expect(after.name).toBe("Acme");
+    expect(after.foo).toBe("bar");
+  });
+
+  it("is idempotent when cloud is already false", () => {
+    seedCompanyDir(tmpRoot, "acme", "cloud: false\nname: Acme\n");
+    const changed = flipCompanyYamlCloudOff(tmpRoot, "acme");
+    expect(changed).toBe(false);
+    expect(readCompanyYaml(tmpRoot, "acme").cloud).toBe(false);
+  });
+
+  it("inserts cloud: false when the field is missing", () => {
+    seedCompanyDir(tmpRoot, "acme", "name: Acme\n");
+    const changed = flipCompanyYamlCloudOff(tmpRoot, "acme");
+    expect(changed).toBe(true);
+    expect(readCompanyYaml(tmpRoot, "acme").cloud).toBe(false);
+  });
+
+  it("returns false when company.yaml does not exist", () => {
+    seedCompanyDir(tmpRoot, "acme"); // no yaml
+    const changed = flipCompanyYamlCloudOff(tmpRoot, "acme");
+    expect(changed).toBe(false);
+  });
+
+  it("does not leave a .tmp file behind on success", () => {
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\n");
+    flipCompanyYamlCloudOff(tmpRoot, "acme");
+    const dir = companyDirPath(tmpRoot, "acme");
+    const tmps = fs.readdirSync(dir).filter((f) => f.includes(".tmp."));
+    expect(tmps).toEqual([]);
+  });
+});
+
+// ── stripManifestCloudForSlug ────────────────────────────────────────────────
+
+describe("stripManifestCloudForSlug", () => {
+  it("removes cloud_uid + bucket_name from the slug entry", () => {
+    seedManifest(tmpRoot);
+    const changed = stripManifestCloudForSlug(tmpRoot, "acme");
+    expect(changed).toBe(true);
+    const m = readManifest(tmpRoot);
+    const entry = m.companies?.acme as Record<string, unknown>;
+    expect(entry.cloud_uid).toBeUndefined();
+    expect(entry.bucket_name).toBeUndefined();
+    // Other fields preserved.
+    expect(entry.name).toBe("Acme");
+    expect(entry.status).toBe("active");
+  });
+
+  it("preserves other companies untouched", () => {
+    seedManifest(tmpRoot, {
+      acme: { cloud_uid: "cmp_a", bucket_name: "b-a" },
+      voyage: { cloud_uid: "cmp_v", bucket_name: "b-v" },
+    });
+    stripManifestCloudForSlug(tmpRoot, "acme");
+    const m = readManifest(tmpRoot);
+    const voyage = m.companies?.voyage as Record<string, unknown>;
+    expect(voyage.cloud_uid).toBe("cmp_v");
+    expect(voyage.bucket_name).toBe("b-v");
+  });
+
+  it("is idempotent — second call reports no change", () => {
+    seedManifest(tmpRoot, { acme: { name: "Acme" } });
+    expect(stripManifestCloudForSlug(tmpRoot, "acme")).toBe(false);
+  });
+
+  it("returns false when the manifest does not exist", () => {
+    // No seed.
+    expect(stripManifestCloudForSlug(tmpRoot, "acme")).toBe(false);
+  });
+
+  it("returns false when the slug is missing from the manifest", () => {
+    seedManifest(tmpRoot, { other: { cloud_uid: "x" } });
+    expect(stripManifestCloudForSlug(tmpRoot, "acme")).toBe(false);
+  });
+});
+
+// ── demoteCompany orchestrator ───────────────────────────────────────────────
+
+function tombstonedEntity(slug: string): VaultEntity {
+  return {
+    uid: "cmp_old",
+    type: "company",
+    slug,
+    name: slug,
+    bucketName: "hq-vault-cmp-old",
+    status: "active",
+    // @ts-expect-error — `deleted` is added on hq-pro side; VaultEntity
+    // doesn't declare it, but the verify path reads it dynamically.
+    deleted: true,
+  };
+}
+
+function liveEntity(slug: string): VaultEntity {
+  return {
+    uid: "cmp_old",
+    type: "company",
+    slug,
+    name: slug,
+    bucketName: "hq-vault-cmp-old",
+    status: "active",
+  };
+}
+
+describe("demoteCompany — happy path", () => {
+  it("removes config, flips yaml, strips manifest, returns full result", async () => {
+    seedManifest(tmpRoot);
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\nname: Acme\n");
+    seedCompanyConfig(tmpRoot, "acme");
+
+    const result: DemoteResult = await demoteCompany({
+      slug: "acme",
+      hqRoot: tmpRoot,
+      vaultApiUrl: "https://v",
+      vaultClient: {
+        findCompanyBySlug: async () => tombstonedEntity("acme"),
+        // unused on the demote path, but the type requires it
+        createCompanyEntity: async () => {
+          throw new Error("must not call createCompanyEntity from demote");
+        },
+      },
+      resolveAccessToken: async () => "tok",
+    });
+
+    expect(result).toEqual<DemoteResult>({
+      ok: true,
+      company_slug: "acme",
+      config_removed: true,
+      yaml_flipped: true,
+      manifest_stripped: true,
+      cloud_was_deleted: true,
+    });
+
+    // Side-effects landed.
+    expect(fs.existsSync(companyConfigPath(tmpRoot, "acme"))).toBe(false);
+    expect(readCompanyYaml(tmpRoot, "acme").cloud).toBe(false);
+    const entry = readManifest(tmpRoot).companies?.acme as Record<string, unknown>;
+    expect(entry.cloud_uid).toBeUndefined();
+    expect(entry.bucket_name).toBeUndefined();
+  });
+
+  it("is idempotent — re-running on an already-demoted company is a no-op", async () => {
+    // Already in post-demote state.
+    seedManifest(tmpRoot, { acme: { name: "Acme" } });
+    seedCompanyDir(tmpRoot, "acme", "cloud: false\nname: Acme\n");
+
+    const result = await demoteCompany({
+      slug: "acme",
+      hqRoot: tmpRoot,
+      vaultApiUrl: "https://v",
+      vaultClient: {
+        findCompanyBySlug: async () => tombstonedEntity("acme"),
+        createCompanyEntity: async () => {
+          throw new Error("unused");
+        },
+      },
+      resolveAccessToken: async () => "tok",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.config_removed).toBe(false);
+    expect(result.yaml_flipped).toBe(false);
+    expect(result.manifest_stripped).toBe(false);
+  });
+});
+
+describe("demoteCompany — safety check", () => {
+  it("refuses to demote when the cloud entity is NOT deleted (no --force)", async () => {
+    seedManifest(tmpRoot);
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\nname: Acme\n");
+    seedCompanyConfig(tmpRoot, "acme");
+
+    await expect(
+      demoteCompany({
+        slug: "acme",
+        hqRoot: tmpRoot,
+        vaultApiUrl: "https://v",
+        vaultClient: {
+          findCompanyBySlug: async () => liveEntity("acme"),
+          createCompanyEntity: async () => {
+            throw new Error("unused");
+          },
+        },
+        resolveAccessToken: async () => "tok",
+      }),
+    ).rejects.toMatchObject({
+      code: 2,
+      message: expect.stringMatching(/not.*deleted/i),
+    });
+
+    // No side-effects.
+    expect(fs.existsSync(companyConfigPath(tmpRoot, "acme"))).toBe(true);
+    expect(readCompanyYaml(tmpRoot, "acme").cloud).toBe(true);
+  });
+
+  it("refuses to demote when the cloud entity does not exist (no --force)", async () => {
+    seedManifest(tmpRoot);
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\nname: Acme\n");
+    seedCompanyConfig(tmpRoot, "acme");
+
+    await expect(
+      demoteCompany({
+        slug: "acme",
+        hqRoot: tmpRoot,
+        vaultApiUrl: "https://v",
+        vaultClient: {
+          findCompanyBySlug: async () => null,
+          createCompanyEntity: async () => {
+            throw new Error("unused");
+          },
+        },
+        resolveAccessToken: async () => "tok",
+      }),
+    ).rejects.toMatchObject({ code: 2 });
+  });
+
+  it("--force skips the verify and demotes anyway, recording cloud_was_deleted=null", async () => {
+    seedManifest(tmpRoot);
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\nname: Acme\n");
+    seedCompanyConfig(tmpRoot, "acme");
+
+    const find = vi.fn(async () => liveEntity("acme"));
+    const result = await demoteCompany({
+      slug: "acme",
+      hqRoot: tmpRoot,
+      vaultApiUrl: "https://v",
+      force: true,
+      vaultClient: {
+        findCompanyBySlug: find,
+        createCompanyEntity: async () => {
+          throw new Error("unused");
+        },
+      },
+      resolveAccessToken: async () => "tok",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.cloud_was_deleted).toBeNull();
+    // --force MUST skip the network call entirely.
+    expect(find).not.toHaveBeenCalled();
+  });
+
+  it("validateSlug rejects bad slugs with code 2", async () => {
+    await expect(
+      demoteCompany({
+        slug: "personal", // reserved
+        hqRoot: tmpRoot,
+        vaultApiUrl: "https://v",
+        force: true,
+        vaultClient: {
+          findCompanyBySlug: async () => null,
+          createCompanyEntity: async () => {
+            throw new Error("unused");
+          },
+        },
+        resolveAccessToken: async () => "tok",
+      }),
+    ).rejects.toBeInstanceOf(ProvisionError);
+  });
+
+  it("--force on a slug missing from the manifest throws code 2 (no silent no-op)", async () => {
+    seedManifest(tmpRoot, { other: { name: "Other" } });
+    seedCompanyDir(tmpRoot, "acme", "cloud: true\n");
+    await expect(
+      demoteCompany({
+        slug: "acme",
+        hqRoot: tmpRoot,
+        vaultApiUrl: "https://v",
+        force: true,
+      }),
+    ).rejects.toMatchObject({
+      code: 2,
+      message: expect.stringMatching(/not found.*manifest/i),
+    });
+  });
+
+  it("--force when company directory is missing throws code 2 (no silent no-op)", async () => {
+    seedManifest(tmpRoot); // seeds acme entry
+    // No seedCompanyDir — directory is missing.
+    await expect(
+      demoteCompany({
+        slug: "acme",
+        hqRoot: tmpRoot,
+        vaultApiUrl: "https://v",
+        force: true,
+      }),
+    ).rejects.toMatchObject({
+      code: 2,
+      message: expect.stringMatching(/does not exist/i),
+    });
+  });
+});

package/src/commands/cloud-demote.ts

@@ -0,0 +1,277 @@
+/**
+ * `hq cloud demote company <slug>` — convert a cloud-backed company back to
+ * local-only after hq-pro has soft-tombstoned its entity (Settings → Delete
+ * company in hq-console).
+ *
+ * Inverse of `hq cloud provision company <slug>`. Both commands live here in
+ * hq-cli so the file-touching contract (manifest patch + per-folder config
+ * write + company.yaml mutation) is single-sourced. AppBar HQ Sync's Path A
+ * shells out to this command on the `deleted=true` branch instead of
+ * re-implementing the file mutations in Rust.
+ *
+ * Side-effects (all atomic + idempotent):
+ *   1. Remove `companies/<slug>/.hq/config.json`.
+ *   2. Flip `cloud: true → false` in `companies/<slug>/company.yaml`. Without
+ *      this flip the next `provisionCompany` would re-mint a fresh cloud
+ *      company — exactly what the user just deleted.
+ *   3. Strip `cloud_uid` + `bucket_name` from `companies/manifest.yaml`'s
+ *      `companies.<slug>` entry. The slug entry + other fields stay.
+ *
+ * Safety check (default on): `findCompanyBySlug` MUST return an entity with
+ * `deleted: true`. A live entity, or no entity at all, refuses with code 2.
+ * `--force` skips the network call (AppBar passes it because Path A just
+ * checked).
+ *
+ * Exit codes (mirrors cloud-provision):
+ *   0 — success or idempotent no-op.
+ *   1 — vault HTTP failure during the safety check.
+ *   2 — validation (bad slug, missing dir/manifest, cloud not deleted).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { Command } from "commander";
+import chalk from "chalk";
+
+import {
+  ProvisionError,
+  companyConfigPath,
+  companyDirPath,
+  createDefaultVaultClient,
+  manifestPath,
+  validateManifestAndDir,
+  validateSlug,
+  type VaultClient,
+} from "./cloud-provision.js";
+import {
+  DEFAULT_HQ_ROOT,
+  DEFAULT_VAULT_API_URL,
+  ensureCognitoToken,
+} from "../utils/cognito-session.js";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/** Final stdout JSON shape. AppBar parses this. */
+export interface DemoteResult {
+  ok: boolean;
+  company_slug: string;
+  /** True if `.hq/config.json` was actually deleted (false if absent). */
+  config_removed: boolean;
+  /** True if `company.yaml`'s `cloud` was changed (true→false or absent→false). */
+  yaml_flipped: boolean;
+  /** True if manifest had `cloud_uid` / `bucket_name` to strip. */
+  manifest_stripped: boolean;
+  /**
+   * `true` when the cloud entity verified as `deleted=true`. `null` when
+   * `--force` was used and the verify was skipped. (`false` is unreachable —
+   * a non-deleted entity throws code 2 before reaching the result.)
+   */
+  cloud_was_deleted: boolean | null;
+}
+
+export interface DemoteCompanyOptions {
+  slug: string;
+  hqRoot: string;
+  vaultApiUrl: string;
+  /** Skip the `findCompanyBySlug` safety check. AppBar uses this. */
+  force?: boolean;
+  /** Injected vault HTTP client (override for tests). */
+  vaultClient?: VaultClient;
+  /** Injected access-token resolver (override for tests). */
+  resolveAccessToken?: () => Promise<string>;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Flip `cloud: true → false` in `companies/<slug>/company.yaml`. All other
+ * keys + ordering preserved (js-yaml round-trip). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (file missing, or
+ * `cloud` was already `false`).
+ *
+ * NOTE: js-yaml doesn't preserve comments, but this matches what
+ * `patchManifest` already does — accepted trade-off.
+ */
+export function flipCompanyYamlCloudOff(hqRoot: string, slug: string): boolean {
+  const yPath = path.join(companyDirPath(hqRoot, slug), "company.yaml");
+  if (!fs.existsSync(yPath)) return false;
+  const raw = fs.readFileSync(yPath, "utf-8");
+  const parsed = (yaml.load(raw) as Record<string, unknown> | null) ?? {};
+  if (parsed.cloud === false) return false;
+  parsed.cloud = false;
+  const dump = yaml.dump(parsed, { lineWidth: -1, noRefs: true });
+  const tmp = `${yPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, dump);
+  fs.renameSync(tmp, yPath);
+  return true;
+}
+
+/**
+ * Remove `cloud_uid` + `bucket_name` from `companies.<slug>` in
+ * `companies/manifest.yaml`. The slug entry is preserved (other fields like
+ * `name`/`status`/`path` stay). Atomic (tmp + rename).
+ *
+ * Returns true if the file was changed, false if no-op (manifest missing,
+ * slug missing, or both fields already absent).
+ */
+export function stripManifestCloudForSlug(hqRoot: string, slug: string): boolean {
+  const mPath = manifestPath(hqRoot);
+  if (!fs.existsSync(mPath)) return false;
+  const raw = fs.readFileSync(mPath, "utf-8");
+  const parsed = (yaml.load(raw) as { companies?: Record<string, unknown> } | null) ?? {};
+  const companies = parsed.companies;
+  if (!companies || !(slug in companies)) return false;
+  const entry = companies[slug];
+  if (!entry || typeof entry !== "object") return false;
+  const obj = entry as Record<string, unknown>;
+  const hadCloudUid = "cloud_uid" in obj;
+  const hadBucketName = "bucket_name" in obj;
+  if (!hadCloudUid && !hadBucketName) return false;
+  delete obj.cloud_uid;
+  delete obj.bucket_name;
+  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;
+}
+
+// ── Orchestrator ─────────────────────────────────────────────────────────────
+
+/**
+ * Run the full demote flow. Returns a `DemoteResult` on success; throws
+ * `ProvisionError` (codes 1 or 2) on any failure.
+ */
+export async function demoteCompany(
+  options: DemoteCompanyOptions,
+): Promise<DemoteResult> {
+  validateSlug(options.slug);
+  // Fails with code 2 if the manifest is missing/malformed, the slug is not
+  // present under `.companies`, or `companies/<slug>/` doesn't exist on disk.
+  // Without this, a `--force` demote against a missing or renamed slug would
+  // be a silent no-op (all helpers return false but we'd still report ok=true).
+  validateManifestAndDir(options.hqRoot, options.slug);
+
+  let cloudWasDeleted: boolean | null = null;
+
+  if (!options.force) {
+    const accessToken = options.resolveAccessToken
+      ? await options.resolveAccessToken()
+      : await ensureCognitoToken();
+    const client =
+      options.vaultClient ??
+      createDefaultVaultClient(options.vaultApiUrl, accessToken);
+    let entity;
+    try {
+      entity = await client.findCompanyBySlug(options.slug);
+    } catch (err) {
+      if (err instanceof ProvisionError) throw err;
+      throw new ProvisionError(
+        1,
+        `Vault GET by-slug failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    if (!entity) {
+      throw new ProvisionError(
+        2,
+        `Refusing to demote '${options.slug}': no cloud entity found. Pass --force to demote anyway.`,
+      );
+    }
+    // `deleted` is added by hq-pro and isn't in the static VaultEntity type.
+    const deleted = (entity as unknown as { deleted?: boolean }).deleted === true;
+    if (!deleted) {
+      throw new ProvisionError(
+        2,
+        `Refusing to demote '${options.slug}': cloud entity is not deleted (uid=${entity.uid}). Pass --force to demote anyway.`,
+      );
+    }
+    cloudWasDeleted = true;
+  }
+
+  const cPath = companyConfigPath(options.hqRoot, options.slug);
+  let configRemoved = false;
+  if (fs.existsSync(cPath)) {
+    fs.rmSync(cPath);
+    configRemoved = true;
+  }
+
+  const yamlFlipped = flipCompanyYamlCloudOff(options.hqRoot, options.slug);
+  const manifestStripped = stripManifestCloudForSlug(options.hqRoot, options.slug);
+
+  return {
+    ok: true,
+    company_slug: options.slug,
+    config_removed: configRemoved,
+    yaml_flipped: yamlFlipped,
+    manifest_stripped: manifestStripped,
+    cloud_was_deleted: cloudWasDeleted,
+  };
+}
+
+// ── Commander wiring ─────────────────────────────────────────────────────────
+
+/**
+ * Register `demote company <slug>` under the `cloud` command group. Wired in
+ * `src/index.ts` alongside `registerCloudProvisionCommands(cloudCmd)`.
+ */
+export function registerCloudDemoteCommands(program: Command): void {
+  const demoteCmd = program
+    .command("demote")
+    .description("Demote a cloud-backed entity back to local-only");
+
+  demoteCmd
+    .command("company")
+    .description(
+      "Demote a cloud-backed company to local-only after the cloud entity " +
+        "has been soft-tombstoned in hq-console. Removes .hq/config.json, " +
+        "flips company.yaml `cloud: false`, and strips the manifest cloud refs.",
+    )
+    .argument("<slug>", "Company slug")
+    .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(
+      "--force",
+      "Skip the safety check that the cloud entity is actually deleted=true. " +
+        "AppBar HQ Sync passes this because its Path A just verified.",
+    )
+    .action(
+      async (
+        slug: string,
+        options: { hqRoot: string; vaultApiUrl: string; force?: boolean },
+      ) => {
+        try {
+          const result = await demoteCompany({
+            slug,
+            hqRoot: options.hqRoot,
+            vaultApiUrl: options.vaultApiUrl,
+            force: options.force,
+          });
+          process.stdout.write(JSON.stringify(result) + "\n");
+          process.exit(0);
+        } catch (err) {
+          if (err instanceof ProvisionError) {
+            process.stderr.write(
+              chalk.red(`[hq cloud demote] ${err.message}\n`),
+            );
+            process.exit(err.code);
+          }
+          process.stderr.write(
+            chalk.red(
+              `[hq cloud demote] Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`,
+            ),
+          );
+          process.exit(1);
+        }
+      },
+    );
+}

package/src/index.ts

@@ -12,6 +12,7 @@ import { registerListCommand } from "./commands/list.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
+import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
 import { registerLogoutCommand } from "./commands/logout.js";
 import { registerWhoamiCommand } from "./commands/whoami.js";
@@ -78,6 +79,7 @@ const cloudCmd = program
   );
 
 registerCloudProvisionCommands(cloudCmd);
+registerCloudDemoteCommands(cloudCmd);
 
 // Team commands (top-level)
 registerTeamSyncCommand(program);