@indigoai-us/hq-cli 5.345.171 → 5.345.173

package/dist/lib/sync-core/flag.js

@@ -0,0 +1,47 @@
+import { createFlagClient, readLocalOverride } from "@indigoai-us/hq-flags-client";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+export const SYNC_RUST_ENGINE_ROLLOUT_FLAG = "sync.rust-engine-rollout";
+const READ_TIMEOUT_MS = 5_000;
+export class RolloutFlagReadError extends Error {
+}
+export async function readCompanyRolloutFlag(companyUid, token, options = {}) {
+    const env = options.env ?? process.env;
+    const override = readLocalOverride(SYNC_RUST_ENGINE_ROLLOUT_FLAG, env);
+    if (override !== null)
+        return override;
+    let failure;
+    const onError = (error) => {
+        failure ??= error;
+    };
+    const client = (options.createClient ?? createFlagClient)({
+        endpoint: resolveFlagRegistryEndpoint(undefined, env),
+        getToken: () => token,
+        env: {},
+        refreshIntervalMs: 0,
+        requestTimeoutMs: READ_TIMEOUT_MS,
+        companyUid,
+        onError,
+    });
+    try {
+        await client.ready();
+        const resolution = client.explain(SYNC_RUST_ENGINE_ROLLOUT_FLAG, { fallback: false });
+        if (failure !== undefined) {
+            throw new RolloutFlagReadError(`could not read ${SYNC_RUST_ENGINE_ROLLOUT_FLAG} for ${companyUid}: ${failure instanceof Error ? failure.message : String(failure)}`);
+        }
+        return resolution.source === "snapshot" && resolution.value === true;
+    }
+    catch (error) {
+        if (error instanceof RolloutFlagReadError)
+            throw error;
+        throw new RolloutFlagReadError(`could not read ${SYNC_RUST_ENGINE_ROLLOUT_FLAG} for ${companyUid}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            client.close();
+        }
+        catch {
+            failure ??= undefined;
+        }
+    }
+}
+//# sourceMappingURL=flag.js.map

package/dist/lib/sync-core/reconcile.d.ts

@@ -0,0 +1,31 @@
+import { type SyncCorePlanFigures, type SyncCoreVault } from "./engine-home.js";
+import { type SyncCoreBinaryInstall } from "./release.js";
+import { type SyncCoreRolloutState } from "./rollout-state.js";
+export interface SyncCoreMembership {
+    companyUid: string;
+    companySlug?: string;
+}
+export interface SyncCoreReconcileDeps {
+    home: string;
+    hqRoot: string;
+    tokenFile: string;
+    companiesOnly: boolean;
+    listMemberships: () => Promise<SyncCoreMembership[]>;
+    resolvePersonUid: () => Promise<string | null>;
+    readRolloutFlag: (companyUid: string) => Promise<boolean>;
+    ensureBinary: (release: string) => Promise<SyncCoreBinaryInstall>;
+    release?: string;
+    now?: () => Date;
+    log?: (line: string) => void;
+}
+export interface SyncCoreReconcileResult {
+    state: SyncCoreRolloutState;
+    started: string[];
+    promoted: string[];
+    stopped: string[];
+    kept: string[];
+    warnings: string[];
+}
+export declare function promotionHold(vault: SyncCoreVault, plan: SyncCorePlanFigures, release: string): string | undefined;
+export declare function reconcileSyncCore(deps: SyncCoreReconcileDeps): Promise<SyncCoreReconcileResult>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/lib/sync-core/reconcile.js

@@ -0,0 +1,217 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readCompaniesManifestMap } from "../work-context/repo-remote.js";
+import { readVaultSyncSwitches, writeVaultSyncSwitches } from "../vault-sync-switches.js";
+import { clearEngineStatus, engineReadOnlyPlan, removeEngineOwnership, syncCoreEngineHome, writeEngineHome, } from "./engine-home.js";
+import { SYNC_CORE_COMPANY_FULL_RELEASE, SYNC_CORE_PROMOTION_OP_LIMIT, SYNC_CORE_RELEASE, companyFullModeAllowed, installedSyncCoreRelease, syncCoreBinaryPath, } from "./release.js";
+import { readSyncCoreSkips } from "./skip.js";
+import { readSyncCoreRolloutState, writeSyncCoreRolloutState, } from "./rollout-state.js";
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function promotionHold(vault, plan, release) {
+    if (vault.kind === "company" && !companyFullModeAllowed(release)) {
+        const needed = SYNC_CORE_COMPANY_FULL_RELEASE ? `engine release ${SYNC_CORE_COMPANY_FULL_RELEASE}` : "an engine release that";
+        return `company vaults stay read-only until ${needed} scopes the local tree to this account's visibility (${release} installed)`;
+    }
+    if (plan.deletes > SYNC_CORE_PROMOTION_OP_LIMIT) {
+        return `the read-only plan would delete ${plan.deletes} paths (limit ${SYNC_CORE_PROMOTION_OP_LIMIT})`;
+    }
+    if (plan.conflicts > SYNC_CORE_PROMOTION_OP_LIMIT) {
+        return `the read-only plan would write ${plan.conflicts} conflict or merge copies (limit ${SYNC_CORE_PROMOTION_OP_LIMIT})`;
+    }
+    if (plan.uploads > SYNC_CORE_PROMOTION_OP_LIMIT) {
+        return `the read-only plan would upload ${plan.uploads} files against ${plan.remoteRows} server rows (limit ${SYNC_CORE_PROMOTION_OP_LIMIT})`;
+    }
+    return undefined;
+}
+function localCompanies(hqRoot, memberships) {
+    const manifest = readCompaniesManifestMap(hqRoot) ?? {};
+    const byUid = new Map();
+    for (const [slug, entry] of Object.entries(manifest)) {
+        const uid = entry?.cloud_uid;
+        if (typeof uid === "string" && /^[a-z0-9][a-z0-9_-]*$/.test(slug))
+            byUid.set(uid, slug);
+    }
+    const candidates = [];
+    for (const membership of memberships) {
+        const slug = byUid.get(membership.companyUid);
+        if (!slug)
+            continue;
+        if (!fs.existsSync(path.join(hqRoot, "companies", slug)))
+            continue;
+        candidates.push({ uid: membership.companyUid, kind: "company", slug });
+    }
+    return candidates;
+}
+export async function reconcileSyncCore(deps) {
+    const now = deps.now ?? (() => new Date());
+    const log = deps.log ?? (() => { });
+    const release = deps.release ?? SYNC_CORE_RELEASE;
+    const warnings = [];
+    const previous = readSyncCoreRolloutState(deps.home);
+    const previousByUid = new Map((previous?.vaults ?? []).map((vault) => [vault.uid, vault]));
+    const memberships = await deps.listMemberships();
+    const desired = [];
+    let anyCompanyOn = false;
+    for (const company of localCompanies(deps.hqRoot, memberships)) {
+        let on;
+        try {
+            on = await deps.readRolloutFlag(company.uid);
+        }
+        catch (error) {
+            on = previousByUid.has(company.uid);
+            warnings.push(`${message(error)}; keeping ${company.slug} ${on ? "on the new engine" : "on the current sync"}`);
+        }
+        if (on) {
+            anyCompanyOn = true;
+            desired.push(company);
+        }
+    }
+    if (!deps.companiesOnly && anyCompanyOn) {
+        let personUid = null;
+        try {
+            personUid = await deps.resolvePersonUid();
+        }
+        catch (error) {
+            const kept = [...previousByUid.values()].find((vault) => vault.kind === "personal");
+            personUid = kept?.uid ?? null;
+            warnings.push(`${message(error)}; ${kept ? "keeping the personal vault on the new engine" : "leaving the personal vault on the current sync"}`);
+        }
+        if (personUid)
+            desired.push({ uid: personUid, kind: "personal" });
+    }
+    const skipped = [];
+    try {
+        const skips = readSyncCoreSkips(deps.home);
+        for (let i = desired.length - 1; i >= 0; i -= 1) {
+            const skip = skips.find((entry) => entry.uid === desired[i]?.uid);
+            if (!skip)
+                continue;
+            skipped.unshift(skip);
+            desired.splice(i, 1);
+        }
+    }
+    catch (error) {
+        warnings.push(message(error));
+    }
+    let binaryPath = syncCoreBinaryPath(deps.home);
+    let installedRelease = installedSyncCoreRelease(deps.home);
+    if (desired.length > 0) {
+        try {
+            const install = await deps.ensureBinary(release);
+            binaryPath = install.binaryPath;
+            installedRelease = install.release;
+            if (install.installed)
+                log(`installed hq-syncd ${install.release} at ${install.binaryPath}`);
+        }
+        catch (error) {
+            warnings.push(`${message(error)}; ${installedRelease ? `keeping hq-syncd ${installedRelease}` : "no vault moves until the engine download succeeds"}`);
+            if (!installedRelease)
+                desired.length = 0;
+        }
+    }
+    const at = now().toISOString();
+    const switchesBefore = readVaultSyncSwitches(deps.home);
+    const vaults = [];
+    const started = [];
+    const promoted = [];
+    const kept = [];
+    const companies = {};
+    let personalOff = false;
+    for (const vault of desired) {
+        const before = previousByUid.get(vault.uid);
+        const engineHome = syncCoreEngineHome(deps.home, vault.uid);
+        if (!before)
+            clearEngineStatus(deps.home, vault.uid);
+        const plan = engineReadOnlyPlan(engineHome, vault.uid) ?? undefined;
+        let phase = before?.phase === "full" ? "full" : "warming";
+        let hold;
+        if (phase === "warming" && plan) {
+            hold = promotionHold(vault, plan, installedRelease ?? release);
+            if (!hold)
+                phase = "full";
+        }
+        writeEngineHome({ home: deps.home, hqRoot: deps.hqRoot, vault, phase, tokenFile: deps.tokenFile });
+        const alreadyOff = vault.kind === "personal"
+            ? switchesBefore.personalOff
+            : switchesBefore.offCompanies.has(vault.slug ?? "");
+        const legacyAlreadyOff = before?.phase === "full" ? before.legacyAlreadyOff === true : phase === "full" && alreadyOff;
+        const legacyOffSince = phase === "full" ? before?.legacyOffSince ?? at : undefined;
+        vaults.push({
+            uid: vault.uid,
+            kind: vault.kind,
+            ...(vault.slug ? { slug: vault.slug } : {}),
+            phase,
+            engineHome,
+            ...(legacyOffSince ? { legacyOffSince } : {}),
+            ...(legacyAlreadyOff ? { legacyAlreadyOff: true } : {}),
+            ...(plan ? { plan } : {}),
+            ...(hold ? { hold } : {}),
+        });
+        if (hold && before?.hold !== hold)
+            log(`${vault.uid}: staying read-only: ${hold}`);
+        if (phase === "full") {
+            if (vault.kind === "company" && vault.slug)
+                companies[vault.slug] = false;
+            else
+                personalOff = true;
+        }
+        if (!before)
+            started.push(vault.uid);
+        else if (before.phase !== phase)
+            promoted.push(vault.uid);
+        else
+            kept.push(vault.uid);
+    }
+    const stopped = [];
+    let personalBackOn = false;
+    for (const vault of previousByUid.values()) {
+        if (desired.some((candidate) => candidate.uid === vault.uid))
+            continue;
+        stopped.push(vault.uid);
+        if (vault.phase !== "full" || vault.legacyAlreadyOff)
+            continue;
+        if (vault.kind === "company" && vault.slug)
+            companies[vault.slug] = true;
+        else
+            personalBackOn = true;
+    }
+    const state = {
+        version: 1,
+        readAt: at,
+        release: installedRelease ?? release,
+        binaryPath,
+        vaults,
+        ...(skipped.length > 0 ? { skipped } : {}),
+        ...(warnings.length > 0 ? { error: warnings.join("; ") } : {}),
+    };
+    writeSyncCoreRolloutState(deps.home, state);
+    for (const uid of stopped)
+        removeEngineOwnership(deps.home, uid);
+    const patch = {
+        ...(personalOff ? { personal: false } : personalBackOn ? { personal: true } : {}),
+        companies,
+    };
+    try {
+        if (writeVaultSyncSwitches(deps.home, patch))
+            log("updated the sync switches in menubar.json");
+    }
+    catch (error) {
+        warnings.push(`could not update the sync switches: ${message(error)}`);
+        state.error = warnings.join("; ");
+        writeSyncCoreRolloutState(deps.home, state);
+    }
+    for (const uid of started)
+        log(`${uid}: warming the new sync engine's index (home ${syncCoreEngineHome(deps.home, uid)})`);
+    for (const uid of promoted)
+        log(`${uid}: index warm; moving to the new sync engine`);
+    for (const uid of stopped)
+        log(`${uid}: back on the current sync`);
+    for (const skip of skipped)
+        log(`${skip.uid}: skipped on this machine: ${skip.reason}`);
+    for (const warning of warnings)
+        log(`warning: ${warning}`);
+    return { state, started, promoted, stopped, kept, warnings };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/lib/sync-core/release.d.ts

@@ -0,0 +1,32 @@
+export declare const SYNC_CORE_RELEASE = "v0.1.13";
+export declare const SYNC_CORE_COMPANY_FULL_RELEASE: string | null;
+export declare const SYNC_CORE_PROMOTION_OP_LIMIT = 100;
+export declare function compareSyncCoreReleases(a: string, b: string): number;
+export declare function companyFullModeAllowed(release: string): boolean;
+export declare const SYNC_CORE_DOWNLOAD_BASE = "https://indigoai-public.s3.amazonaws.com/hq-sync-core";
+export declare const SYNC_CORE_DOWNLOAD_BASE_ENV = "HQ_SYNC_CORE_DOWNLOAD_BASE";
+export declare function syncCoreBinaryPath(home?: string): string;
+export declare function syncCoreReleaseMarkerPath(home?: string): string;
+export declare function syncCoreAssetName(release: string, platform: NodeJS.Platform, arch: string): string | null;
+export declare function syncCoreDownloadBase(env?: NodeJS.ProcessEnv): string;
+export declare function parseSha256Sums(text: string): Map<string, string>;
+export declare function installedSyncCoreRelease(home: string): string | null;
+export interface EnsureSyncCoreBinaryOptions {
+    home: string;
+    platform: NodeJS.Platform;
+    arch: string;
+    release?: string;
+    baseUrl?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    run?: (file: string, args: string[]) => void;
+}
+export interface SyncCoreBinaryInstall {
+    binaryPath: string;
+    release: string;
+    installed: boolean;
+}
+export declare class SyncCoreReleaseError extends Error {
+}
+export declare function ensureSyncCoreBinary(opts: EnsureSyncCoreBinaryOptions): Promise<SyncCoreBinaryInstall>;
+//# sourceMappingURL=release.d.ts.map

package/dist/lib/sync-core/release.js

@@ -0,0 +1,142 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+export const SYNC_CORE_RELEASE = "v0.1.13";
+export const SYNC_CORE_COMPANY_FULL_RELEASE = null;
+export const SYNC_CORE_PROMOTION_OP_LIMIT = 100;
+export function compareSyncCoreReleases(a, b) {
+    const parse = (release) => release.replace(/^v/, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const [x, y] = [parse(a), parse(b)];
+    for (let i = 0; i < Math.max(x.length, y.length); i += 1) {
+        const diff = (x[i] ?? 0) - (y[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+export function companyFullModeAllowed(release) {
+    return SYNC_CORE_COMPANY_FULL_RELEASE !== null && compareSyncCoreReleases(release, SYNC_CORE_COMPANY_FULL_RELEASE) >= 0;
+}
+export const SYNC_CORE_DOWNLOAD_BASE = "https://indigoai-public.s3.amazonaws.com/hq-sync-core";
+export const SYNC_CORE_DOWNLOAD_BASE_ENV = "HQ_SYNC_CORE_DOWNLOAD_BASE";
+const DOWNLOAD_TIMEOUT_MS = 600_000;
+export function syncCoreBinaryPath(home = os.homedir()) {
+    return path.join(home, ".hq", "bin", "hq-syncd");
+}
+export function syncCoreReleaseMarkerPath(home = os.homedir()) {
+    return path.join(home, ".hq", "bin", "hq-syncd.release");
+}
+export function syncCoreAssetName(release, platform, arch) {
+    if (platform === "darwin")
+        return `hq-sync-core-${release}-macos-universal.tar.gz`;
+    if (platform === "linux" && arch === "x64")
+        return `hq-sync-core-${release}-linux-x64.tar.gz`;
+    if (platform === "linux" && arch === "arm64")
+        return `hq-sync-core-${release}-linux-arm64.tar.gz`;
+    return null;
+}
+export function syncCoreDownloadBase(env = process.env) {
+    const override = env[SYNC_CORE_DOWNLOAD_BASE_ENV]?.trim();
+    return (override || SYNC_CORE_DOWNLOAD_BASE).replace(/\/+$/, "");
+}
+export function parseSha256Sums(text) {
+    const sums = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^([0-9a-f]{64})\s+\*?(\S+)\s*$/i.exec(line.trim());
+        if (match)
+            sums.set(match[2], match[1].toLowerCase());
+    }
+    return sums;
+}
+export function installedSyncCoreRelease(home) {
+    try {
+        const marker = fs.readFileSync(syncCoreReleaseMarkerPath(home), "utf8").trim();
+        const binary = syncCoreBinaryPath(home);
+        if (!marker || !fs.statSync(binary).isFile())
+            return null;
+        fs.accessSync(binary, fs.constants.X_OK);
+        return marker;
+    }
+    catch {
+        return null;
+    }
+}
+export class SyncCoreReleaseError extends Error {
+}
+function findFile(dir, name) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = findFile(full, name);
+            if (nested)
+                return nested;
+        }
+        else if (entry.name === name) {
+            return full;
+        }
+    }
+    return null;
+}
+async function download(fetcher, url) {
+    let response;
+    try {
+        response = await fetcher(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+    }
+    catch (error) {
+        throw new SyncCoreReleaseError(`could not download ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new SyncCoreReleaseError(`could not download ${url}: HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+export async function ensureSyncCoreBinary(opts) {
+    const release = opts.release ?? SYNC_CORE_RELEASE;
+    const binaryPath = syncCoreBinaryPath(opts.home);
+    const installedRelease = installedSyncCoreRelease(opts.home);
+    if (installedRelease && compareSyncCoreReleases(installedRelease, release) >= 0 && fs.existsSync(binaryPath)) {
+        return { binaryPath, release: installedRelease, installed: false };
+    }
+    const asset = syncCoreAssetName(release, opts.platform, opts.arch);
+    if (!asset)
+        throw new SyncCoreReleaseError(`the sync engine has no ${release} build for ${opts.platform} on ${opts.arch}`);
+    const base = `${opts.baseUrl?.replace(/\/+$/, "") ?? syncCoreDownloadBase(opts.env)}/${release}`;
+    const fetcher = opts.fetch ?? fetch;
+    const run = opts.run ?? ((file, args) => {
+        execFileSync(file, args, { stdio: ["ignore", "ignore", "pipe"] });
+    });
+    const sums = parseSha256Sums((await download(fetcher, `${base}/SHA256SUMS`)).toString("utf8"));
+    const expected = sums.get(asset);
+    if (!expected)
+        throw new SyncCoreReleaseError(`SHA256SUMS for ${release} does not list ${asset}`);
+    const bytes = await download(fetcher, `${base}/${asset}`);
+    const actual = crypto.createHash("sha256").update(bytes).digest("hex");
+    if (actual !== expected)
+        throw new SyncCoreReleaseError(`${asset} did not match SHA256SUMS (${actual} != ${expected})`);
+    const binDir = path.dirname(binaryPath);
+    fs.mkdirSync(binDir, { recursive: true, mode: 0o700 });
+    const staging = fs.mkdtempSync(path.join(binDir, ".hq-syncd-staging-"));
+    try {
+        const archive = path.join(staging, asset);
+        fs.writeFileSync(archive, bytes, { mode: 0o600 });
+        const extracted = path.join(staging, "extracted");
+        fs.mkdirSync(extracted, { mode: 0o700 });
+        run("tar", ["-xzf", archive, "-C", extracted]);
+        const unpacked = findFile(extracted, "hq-syncd");
+        if (!unpacked)
+            throw new SyncCoreReleaseError(`${asset} does not contain hq-syncd`);
+        const prepared = path.join(staging, "hq-syncd");
+        fs.copyFileSync(unpacked, prepared);
+        fs.chmodSync(prepared, 0o700);
+        fs.renameSync(prepared, binaryPath);
+        const marker = syncCoreReleaseMarkerPath(opts.home);
+        fs.writeFileSync(`${marker}.tmp`, `${release}\n`, { mode: 0o600 });
+        fs.renameSync(`${marker}.tmp`, marker);
+    }
+    finally {
+        fs.rmSync(staging, { recursive: true, force: true });
+    }
+    return { binaryPath, release, installed: true };
+}
+//# sourceMappingURL=release.js.map

package/dist/lib/sync-core/rollout-state.d.ts

@@ -0,0 +1,28 @@
+import { type SyncCorePlanFigures, type SyncCoreVaultKind, type SyncCoreVaultPhase } from "./engine-home.js";
+export interface RolloutVault {
+    uid: string;
+    kind: SyncCoreVaultKind;
+    slug?: string;
+    phase: SyncCoreVaultPhase;
+    engineHome: string;
+    legacyOffSince?: string;
+    legacyAlreadyOff?: true;
+    plan?: SyncCorePlanFigures;
+    hold?: string;
+}
+export interface SyncCoreRolloutState {
+    version: 1;
+    readAt: string;
+    release: string;
+    binaryPath: string;
+    vaults: RolloutVault[];
+    skipped?: {
+        uid: string;
+        reason: string;
+    }[];
+    error?: string;
+}
+export declare function syncCoreRolloutStatePath(home: string): string;
+export declare function readSyncCoreRolloutState(home: string): SyncCoreRolloutState | null;
+export declare function writeSyncCoreRolloutState(home: string, state: SyncCoreRolloutState): void;
+//# sourceMappingURL=rollout-state.d.ts.map

package/dist/lib/sync-core/rollout-state.js

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isSyncCoreVaultUid } from "./engine-home.js";
+function planFigures(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const p = value;
+    if (typeof p.at !== "string")
+        return null;
+    const numbers = ["uploads", "downloads", "deletes", "remoteRows", "localFiles"];
+    if (numbers.some((key) => typeof p[key] !== "number" || !Number.isFinite(p[key])))
+        return null;
+    if (p.conflicts !== undefined && (typeof p.conflicts !== "number" || !Number.isFinite(p.conflicts)))
+        return null;
+    return {
+        at: p.at,
+        uploads: p.uploads,
+        downloads: p.downloads,
+        deletes: p.deletes,
+        conflicts: typeof p.conflicts === "number" ? p.conflicts : 0,
+        remoteRows: p.remoteRows,
+        localFiles: p.localFiles,
+    };
+}
+function skippedEntries(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const entry of value) {
+        const e = entry && typeof entry === "object" ? entry : undefined;
+        if (!e || !isSyncCoreVaultUid(e.uid) || typeof e.reason !== "string")
+            return null;
+        out.push({ uid: e.uid, reason: e.reason });
+    }
+    return out;
+}
+export function syncCoreRolloutStatePath(home) {
+    return path.join(home, ".hq", "sync-core", "rollout.json");
+}
+function vault(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const v = value;
+    if (!isSyncCoreVaultUid(v.uid))
+        return null;
+    if (v.kind !== "personal" && v.kind !== "company")
+        return null;
+    if (typeof v.engineHome !== "string" || !path.isAbsolute(v.engineHome))
+        return null;
+    if (v.legacyOffSince !== undefined && typeof v.legacyOffSince !== "string")
+        return null;
+    if (v.phase === undefined && typeof v.legacyOffSince === "string")
+        v.phase = "full";
+    if (v.phase !== "warming" && v.phase !== "full")
+        return null;
+    if (v.kind === "company" && (typeof v.slug !== "string" || !/^[a-z0-9][a-z0-9_-]*$/.test(v.slug)))
+        return null;
+    const plan = v.plan === undefined ? undefined : planFigures(v.plan);
+    if (plan === null)
+        return null;
+    if (v.hold !== undefined && typeof v.hold !== "string")
+        return null;
+    return {
+        uid: v.uid,
+        kind: v.kind,
+        ...(typeof v.slug === "string" ? { slug: v.slug } : {}),
+        phase: v.phase,
+        engineHome: v.engineHome,
+        ...(typeof v.legacyOffSince === "string" ? { legacyOffSince: v.legacyOffSince } : {}),
+        ...(v.legacyAlreadyOff === true ? { legacyAlreadyOff: true } : {}),
+        ...(plan ? { plan } : {}),
+        ...(typeof v.hold === "string" ? { hold: v.hold } : {}),
+    };
+}
+export function readSyncCoreRolloutState(home) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(syncCoreRolloutStatePath(home), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    if (obj.version !== 1 || typeof obj.release !== "string" || typeof obj.binaryPath !== "string")
+        return null;
+    if (typeof obj.readAt !== "string" || !Array.isArray(obj.vaults))
+        return null;
+    const vaults = obj.vaults.map(vault);
+    if (vaults.some((v) => v === null))
+        return null;
+    const skipped = skippedEntries(obj.skipped);
+    if (skipped === null)
+        return null;
+    return {
+        version: 1,
+        readAt: obj.readAt,
+        release: obj.release,
+        binaryPath: obj.binaryPath,
+        vaults: vaults,
+        ...(skipped.length > 0 ? { skipped } : {}),
+        ...(typeof obj.error === "string" ? { error: obj.error } : {}),
+    };
+}
+export function writeSyncCoreRolloutState(home, state) {
+    const file = syncCoreRolloutStatePath(home);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+//# sourceMappingURL=rollout-state.js.map

package/dist/lib/sync-core/skip.d.ts

@@ -0,0 +1,7 @@
+export interface SyncCoreSkip {
+    uid: string;
+    reason: string;
+}
+export declare function syncCoreSkipPath(home: string): string;
+export declare function readSyncCoreSkips(home: string): SyncCoreSkip[];
+//# sourceMappingURL=skip.d.ts.map

package/dist/lib/sync-core/skip.js

@@ -0,0 +1,30 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isSyncCoreVaultUid } from "./engine-home.js";
+export function syncCoreSkipPath(home) {
+    return path.join(home, ".hq", "sync-core", "skip.json");
+}
+export function readSyncCoreSkips(home) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(syncCoreSkipPath(home), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw new Error(`${syncCoreSkipPath(home)} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const vaults = raw && typeof raw === "object" && !Array.isArray(raw) ? raw.vaults : undefined;
+    if (!vaults || typeof vaults !== "object" || Array.isArray(vaults)) {
+        throw new Error(`${syncCoreSkipPath(home)} must be {"vaults": {"<vault uid>": "<reason>"}}`);
+    }
+    const skips = [];
+    for (const [uid, reason] of Object.entries(vaults)) {
+        if (!isSyncCoreVaultUid(uid) || typeof reason !== "string" || reason.trim() === "") {
+            throw new Error(`${syncCoreSkipPath(home)} must map vault uids to a non-empty reason (bad entry ${uid})`);
+        }
+        skips.push({ uid, reason: reason.trim() });
+    }
+    return skips;
+}
+//# sourceMappingURL=skip.js.map

package/dist/lib/vault-sync-switches.d.ts

@@ -38,4 +38,9 @@ export declare function unreadableSwitchesWarning(reason: string): string;
  * (`HQ_SYNC_SKIP_COMPANIES`, `HQ_SYNC_SKIP_PERSONAL`). Empty when all are on.
  */
 export declare function vaultSkipEnv(switches: VaultSyncSwitches): Record<string, string>;
+export interface VaultSyncSwitchPatch {
+    personal?: boolean;
+    companies?: Record<string, boolean>;
+}
+export declare function writeVaultSyncSwitches(home: string, patch: VaultSyncSwitchPatch): boolean;
 //# sourceMappingURL=vault-sync-switches.d.ts.map