@indigoai-us/hq-cli 5.345.80 → 5.345.81

package/dist/commands/storage.js

@@ -0,0 +1,931 @@
+/**
+ * `hq storage` — how much space HQ backups use, and pruning of old ones.
+ *
+ * Two stores:
+ *   - Local autosave history (the HQ root git repo). Measured and pruned by the
+ *     hq-core script `core/scripts/hq-storage.sh`; older HQ installs lack it and
+ *     report `{ available: false, reason: "update HQ" }`.
+ *   - Cloud file history: S3 object versioning on company vault buckets. Read
+ *     with ListObjectVersions and pruned with batched DeleteObjects, using
+ *     membership-scoped credentials from `/sts/vend`.
+ *
+ * Tenant isolation: cloud work only ever targets companies in the caller's own
+ * active memberships (`/membership/me`). `--company` narrows that set; a slug
+ * outside it is rejected before any credentials are vended. Deleting cloud
+ * history is for owners and admins only: prune checks the membership role
+ * before vending, and `status` marks each company with `can_delete`.
+ *
+ * `offload` and `fetch` (big files to the personal vault) live in
+ * `storage-offload.ts`; this file registers them and adds the offload section
+ * to `status`.
+ */
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { execFile } from "node:child_process";
+import { dropExpiredBackups, reclaimFields, reclaimWindowHours, runCoreScript, } from "./storage-core.js";
+import { S3Client, ListObjectVersionsCommand, DeleteObjectsCommand, } from "@aws-sdk/client-s3";
+import { PERSONAL_VAULT_EXCLUDED_TOP_LEVEL, VaultClient } from "@indigoai-us/hq-cloud";
+import { buildVaultConfig, DEFAULT_COGNITO } from "../utils/cognito-session.js";
+import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { findHqRoot } from "../utils/manifest.js";
+import { maxLength } from "../utils/table-width.js";
+import { resolveCanonicalPersonUid } from "./cloud.js";
+import { DEFAULT_IDLE_DAYS, currentAvailability, defaultTmpDir, getOffloadStatus, gitExportBlob, gitListPlaceholders, personalS3Store, resolveMinBytes, runFetch, runFetchGitBlob, runOffload, s3VaultObjectStore, syncExcludesOffload, } from "./storage-offload.js";
+export const TRANCHES = [
+    { id: "7d", label: "Last 7 days", maxAgeDays: 7 },
+    { id: "30d", label: "8-30 days", maxAgeDays: 30 },
+    { id: "90d", label: "31-90 days", maxAgeDays: 90 },
+    { id: "365d", label: "91-365 days", maxAgeDays: 365 },
+    { id: "older", label: "Older than a year", maxAgeDays: Number.POSITIVE_INFINITY },
+];
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function trancheFor(lastModified, now) {
+    const ageDays = (now.getTime() - lastModified.getTime()) / DAY_MS;
+    for (const t of TRANCHES) {
+        if (ageDays <= t.maxAgeDays)
+            return t.id;
+    }
+    return "older";
+}
+const DELETE_ROLES = new Set(["owner", "admin"]);
+/** Cloud history delete is owners and admins only. A missing role is not enough. */
+export function canDeleteCloudHistory(company) {
+    return company.role !== undefined && DELETE_ROLES.has(company.role);
+}
+export const DELETE_ROLE_REASON = "Only company owners and admins can delete cloud file history.";
+// ── Local (hq-core script) ──────────────────────────────────────────────────
+export function localScriptPath(hqRoot) {
+    return path.join(hqRoot, "core", "scripts", "hq-storage.sh");
+}
+async function runLocal(deps, args) {
+    const script = localScriptPath(deps.hqRoot);
+    if (!fs.existsSync(script))
+        return { available: false, reason: "update HQ" };
+    return runCoreScript(deps.runScript, script, args);
+}
+/**
+ * Core `drop-backups --expired` right before a real local prune; undefined
+ * when HQ lacks it. Status, dry runs and fetch never call it.
+ */
+export async function dropExpiredLocal(deps) {
+    const script = localScriptPath(deps.hqRoot);
+    return fs.existsSync(script) ? dropExpiredBackups(deps.runScript, script) : undefined;
+}
+export async function getLocalReport(deps) {
+    const report = await runLocal(deps, ["report", "--json"]);
+    if (report.available === false)
+        return report;
+    // Bytes still held by backups during the grace period, and when they go.
+    return {
+        ...report,
+        pending_reclaim_bytes: num(report.pending_reclaim_bytes),
+        reclaim_after: typeof report.reclaim_after === "string" ? report.reclaim_after : null,
+    };
+}
+// ── Company selection (tenant boundary) ─────────────────────────────────────
+export function selectCompanies(memberships, requested) {
+    if (requested === undefined)
+        return memberships;
+    const match = memberships.find((c) => c.slug === requested || c.uid === requested);
+    if (!match) {
+        throw new Error(`You are not an active member of '${requested}'. hq storage only works on your own companies.`);
+    }
+    return [match];
+}
+const ROLE_RANK = { owner: 3, admin: 2, member: 1, guest: 0 };
+/**
+ * Active memberships from a `/membership/me` body, one per company. A company
+ * listed more than once keeps its highest-privilege role.
+ */
+export function companiesFromMemberships(body) {
+    const rows = body?.memberships;
+    const byUid = new Map();
+    for (const raw of Array.isArray(rows) ? rows : []) {
+        const m = raw;
+        if (m.status !== "active" || typeof m.companyUid !== "string")
+            continue;
+        const ref = {
+            uid: m.companyUid,
+            slug: m.companySlug ?? m.slug ?? m.companyUid,
+            ...(typeof m.role === "string" ? { role: m.role } : {}),
+        };
+        const prev = byUid.get(ref.uid);
+        if (!prev || (ROLE_RANK[ref.role ?? ""] ?? -1) > (ROLE_RANK[prev.role ?? ""] ?? -1)) {
+            byUid.set(ref.uid, ref);
+        }
+    }
+    return [...byUid.values()];
+}
+/**
+ * Fill `noncurrentSince` on every noncurrent entry. A noncurrent version's
+ * age is how long it has been a backup, not when it was written: a file
+ * written two years ago and overwritten yesterday became an undo copy
+ * yesterday. Within a key the current entry comes first, then newest to
+ * oldest. A noncurrent entry with no newer entry in the listing falls back
+ * to its own LastModified.
+ */
+export function annotateNoncurrentSince(entries) {
+    const byKey = new Map();
+    for (const e of entries) {
+        const list = byKey.get(e.key);
+        if (list)
+            list.push(e);
+        else
+            byKey.set(e.key, [e]);
+    }
+    for (const list of byKey.values()) {
+        list.sort((a, b) => Number(b.isLatest) - Number(a.isLatest) || b.lastModified.getTime() - a.lastModified.getTime());
+        for (let i = 0; i < list.length; i++) {
+            if (list[i].isLatest)
+                continue;
+            list[i].noncurrentSince = i > 0 ? list[i - 1].lastModified : list[i].lastModified;
+        }
+    }
+    return entries;
+}
+function noncurrentAge(v) {
+    return v.noncurrentSince ?? v.lastModified;
+}
+async function* listAllVersions(store) {
+    let keyMarker;
+    let versionIdMarker;
+    do {
+        const page = await store.s3.send(new ListObjectVersionsCommand({
+            Bucket: store.bucket,
+            KeyMarker: keyMarker,
+            VersionIdMarker: versionIdMarker,
+        }));
+        for (const v of page.Versions ?? []) {
+            if (!v.Key || !v.VersionId)
+                continue;
+            yield {
+                key: v.Key,
+                versionId: v.VersionId,
+                isLatest: Boolean(v.IsLatest),
+                lastModified: v.LastModified ? new Date(v.LastModified) : new Date(0),
+                size: v.Size ?? 0,
+                isDeleteMarker: false,
+            };
+        }
+        for (const m of page.DeleteMarkers ?? []) {
+            if (!m.Key || !m.VersionId)
+                continue;
+            yield {
+                key: m.Key,
+                versionId: m.VersionId,
+                isLatest: Boolean(m.IsLatest),
+                lastModified: m.LastModified ? new Date(m.LastModified) : new Date(0),
+                size: 0,
+                isDeleteMarker: true,
+            };
+        }
+        if (page.IsTruncated && !page.NextKeyMarker) {
+            throw new Error("File history listing was cut short (no next marker). Nothing was changed.");
+        }
+        keyMarker = page.IsTruncated ? page.NextKeyMarker : undefined;
+        versionIdMarker = page.IsTruncated ? page.NextVersionIdMarker : undefined;
+    } while (keyMarker !== undefined);
+}
+/** Every version and delete marker in the bucket, with `noncurrentSince` set. */
+async function listVersions(store) {
+    const all = [];
+    for await (const v of listAllVersions(store))
+        all.push(v);
+    return annotateNoncurrentSince(all);
+}
+function emptyTranches() {
+    return TRANCHES.map((t) => ({ id: t.id, label: t.label, count: 0, bytes: 0 }));
+}
+function s3ErrorName(err) {
+    const e = err;
+    return e?.name ?? e?.Code ?? e?.code ?? "";
+}
+function isAccessDenied(err) {
+    const name = s3ErrorName(err);
+    return name === "AccessDenied" || name === "AccessDeniedException";
+}
+/** Plain message when S3 refuses a version delete for one company. */
+export function deleteDeniedMessage(slug) {
+    return `${DELETE_ROLE_REASON} Your access to ${slug} does not allow deleting old versions yet.`;
+}
+export function describeCloudError(err, action, slug) {
+    if (isAccessDenied(err)) {
+        if (action === "delete")
+            return deleteDeniedMessage(slug ?? "this company");
+        return "Access denied listing file history (needs s3:ListBucketVersions on the vault bucket).";
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg || s3ErrorName(err) || "Unknown error";
+}
+export async function getCloudStatus(company, deps) {
+    const status = {
+        company: company.slug,
+        available: true,
+        can_delete: canDeleteCloudHistory(company),
+        current_bytes: 0,
+        noncurrent_bytes: 0,
+        noncurrent_count: 0,
+        delete_markers: 0,
+        tranches: emptyTranches(),
+    };
+    const now = deps.now();
+    try {
+        const store = await deps.openCompany(company);
+        for (const v of await listVersions(store)) {
+            if (v.isDeleteMarker) {
+                status.delete_markers += 1;
+                continue;
+            }
+            if (v.isLatest) {
+                status.current_bytes += v.size;
+                continue;
+            }
+            status.noncurrent_bytes += v.size;
+            status.noncurrent_count += 1;
+            const tranche = status.tranches.find((x) => x.id === trancheFor(noncurrentAge(v), now));
+            if (tranche) {
+                tranche.count += 1;
+                tranche.bytes += v.size;
+            }
+        }
+    }
+    catch (err) {
+        return {
+            ...status,
+            available: false,
+            tranches: emptyTranches(),
+            current_bytes: 0,
+            noncurrent_bytes: 0,
+            noncurrent_count: 0,
+            delete_markers: 0,
+            error: describeCloudError(err, "list"),
+        };
+    }
+    return status;
+}
+/**
+ * Versions eligible for prune: noncurrent content versions and noncurrent
+ * delete markers that stopped being current before the cutoff (see
+ * annotateNoncurrentSince). The current version of a key (content or delete
+ * marker) is never selected.
+ */
+export function selectPrunable(versions, cutoff) {
+    annotateNoncurrentSince(versions);
+    return versions.filter((v) => !v.isLatest && noncurrentAge(v).getTime() < cutoff.getTime());
+}
+const DELETE_BATCH = 1000;
+export async function pruneCloud(company, cutoff, dryRun, deps) {
+    const result = {
+        company: company.slug,
+        deleted_count: 0,
+        deleted_bytes: 0,
+        errors: [],
+    };
+    let store;
+    let candidates;
+    try {
+        store = await deps.openCompany(company);
+        candidates = selectPrunable(await listVersions(store), cutoff);
+    }
+    catch (err) {
+        result.errors.push(describeCloudError(err, "list"));
+        return result;
+    }
+    if (dryRun) {
+        result.deleted_count = candidates.length;
+        result.deleted_bytes = candidates.reduce((sum, v) => sum + v.size, 0);
+        return result;
+    }
+    const byId = new Map(candidates.map((v) => [`${v.key}\u0000${v.versionId}`, v]));
+    for (let i = 0; i < candidates.length; i += DELETE_BATCH) {
+        const batch = candidates.slice(i, i + DELETE_BATCH);
+        try {
+            const res = await store.s3.send(new DeleteObjectsCommand({
+                Bucket: store.bucket,
+                Delete: {
+                    Objects: batch.map((v) => ({ Key: v.key, VersionId: v.versionId })),
+                    Quiet: false,
+                },
+            }));
+            for (const d of res.Deleted ?? []) {
+                const v = byId.get(`${d.Key}\u0000${d.VersionId}`);
+                if (!v)
+                    continue;
+                result.deleted_count += 1;
+                result.deleted_bytes += v.size;
+            }
+            const errors = res.Errors ?? [];
+            const denied = errors.filter((e) => e.Code === "AccessDenied");
+            if (denied.length > 0) {
+                result.access_denied = true;
+                if (!result.errors.includes(deleteDeniedMessage(company.slug))) {
+                    result.errors.push(deleteDeniedMessage(company.slug));
+                }
+            }
+            for (const e of errors.filter((x) => x.Code !== "AccessDenied")) {
+                result.errors.push(`${e.Key ?? "?"}: ${e.Code ?? "Error"} ${e.Message ?? ""}`.trim());
+            }
+        }
+        catch (err) {
+            if (isAccessDenied(err)) {
+                result.access_denied = true;
+                if (!result.errors.includes(deleteDeniedMessage(company.slug))) {
+                    result.errors.push(deleteDeniedMessage(company.slug));
+                }
+                break;
+            }
+            result.errors.push(describeCloudError(err, "delete", company.slug));
+        }
+    }
+    return result;
+}
+// ── Orchestrators ───────────────────────────────────────────────────────────
+export async function runStorageStatus(opts, deps) {
+    // Read-only: no backup drop, no gc. Pending backup bytes come from report.
+    const local = await getLocalReport(deps);
+    const offload = deps.getOffload ? await deps.getOffload().catch(offloadUnavailable) : undefined;
+    let memberships;
+    try {
+        memberships = await deps.listCompanies();
+    }
+    catch (err) {
+        // Local sections still report when cloud is unreachable (signed out, API key).
+        return {
+            local,
+            cloud: [],
+            cloud_error: err instanceof Error ? err.message : String(err),
+            ...(offload ? { offload } : {}),
+            generated_at: deps.now().toISOString(),
+        };
+    }
+    const companies = selectCompanies(memberships, opts.company);
+    const cloud = [];
+    for (const c of companies)
+        cloud.push(await getCloudStatus(c, deps));
+    return {
+        local,
+        cloud,
+        ...(offload ? { offload } : {}),
+        generated_at: deps.now().toISOString(),
+    };
+}
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function parseCutoff(value, flag) {
+    const d = new Date(`${value}T00:00:00Z`);
+    if (!DATE_RE.test(value) || Number.isNaN(d.getTime())) {
+        throw new Error(`${flag} must be a date in YYYY-MM-DD form, got '${value}'.`);
+    }
+    return d;
+}
+export async function runStoragePrune(opts, deps) {
+    if (!opts.localBefore && !opts.cloudBefore) {
+        throw new Error("Pass --local-before and/or --cloud-before to choose what to prune.");
+    }
+    if (opts.localBefore)
+        parseCutoff(opts.localBefore, "--local-before");
+    const cloudCutoff = opts.cloudBefore ? parseCutoff(opts.cloudBefore, "--cloud-before") : undefined;
+    const selected = cloudCutoff
+        ? selectCompanies(await deps.listCompanies(), opts.company)
+        : [];
+    // Role gate before any credentials are vended. Naming a company you cannot
+    // delete in is an error; otherwise those companies are skipped and reported.
+    if (opts.company !== undefined && selected.some((c) => !canDeleteCloudHistory(c))) {
+        throw new Error(`${DELETE_ROLE_REASON} You are not an owner or admin of '${opts.company}'.`);
+    }
+    const companies = selected.filter(canDeleteCloudHistory);
+    const skipped = selected.filter((c) => !canDeleteCloudHistory(c));
+    if (!opts.dryRun && !opts.yes) {
+        const parts = [];
+        if (opts.localBefore)
+            parts.push(`local autosave history before ${opts.localBefore}`);
+        if (cloudCutoff) {
+            const names = companies.map((c) => c.slug).join(", ") || "no companies";
+            parts.push(`old cloud file versions before ${opts.cloudBefore} in ${names}`);
+        }
+        const ok = await deps.confirm(`Permanently delete ${parts.join(" and ")}? This cannot be undone.`);
+        if (!ok) {
+            deps.log(chalk.dim("Aborted - nothing was deleted."));
+            return undefined;
+        }
+    }
+    const reclaim = opts.localBefore && !opts.dryRun ? await dropExpiredLocal(deps) : undefined;
+    let local = null;
+    if (opts.localBefore) {
+        // prune always prints JSON; it takes no --json flag.
+        const args = ["prune", "--before", opts.localBefore];
+        args.push(opts.dryRun ? "--dry-run" : "--yes");
+        const windowHours = reclaimWindowHours(localScriptPath(deps.hqRoot));
+        local = withLocalReclaim(await runLocal(deps, args), opts.dryRun, deps.now(), windowHours);
+    }
+    const cloud = [];
+    if (cloudCutoff) {
+        for (const c of companies)
+            cloud.push(await pruneCloud(c, cloudCutoff, opts.dryRun, deps));
+        for (const c of skipped) {
+            cloud.push({
+                company: c.slug,
+                deleted_count: 0,
+                deleted_bytes: 0,
+                errors: [],
+                skipped_reason: DELETE_ROLE_REASON,
+            });
+        }
+    }
+    return { local, cloud, dry_run: opts.dryRun, ...(reclaim ? { reclaim } : {}) };
+}
+/**
+ * Add freed / pending space to a local prune result. Space held by the
+ * backup ref is freed after `reclaim_after`; a dry run estimates that time.
+ */
+function withLocalReclaim(local, dryRun, now, windowHours) {
+    if (local.available === false || local.refused)
+        return local;
+    const freed = dryRun
+        ? 0
+        : typeof local.freed_bytes === "number"
+            ? local.freed_bytes
+            : Math.max(0, num(local.git_dir_bytes_before) - num(local.git_dir_bytes_after));
+    const fields = reclaimFields(local, { dryRun, now, expectedBytes: num(local.est_bytes), freedBytes: freed, windowHours });
+    return dryRun ? { ...local, ...fields } : { ...local, freed_bytes: freed, ...fields };
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 ** 2)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MiB`;
+    return `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+}
+function table(cols, data) {
+    const widths = cols.map((col, i) => maxLength(data, (row) => row[i].length, col.length));
+    const render = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    return [
+        chalk.bold(render(cols)),
+        chalk.dim(render(widths.map((w) => "─".repeat(w)))),
+        ...data.map(render),
+    ].join("\n");
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+export function formatStorageStatus(status) {
+    const lines = [chalk.bold("Local autosave history")];
+    const local = status.local;
+    if (local.available === false) {
+        lines.push(`  Not available: ${String(local.reason ?? "unknown")}`);
+    }
+    else {
+        const pending = reclaimLine(local);
+        if (pending)
+            lines.push(`  ${pending}`);
+        lines.push(`  History size: ${formatBytes(num(local.git_dir_bytes))}, ` +
+            `${num(local.commit_count)} saves, oldest ${String(local.oldest_commit_at ?? "-")}`);
+        const tranches = Array.isArray(local.tranches) ? local.tranches : [];
+        if (tranches.length > 0) {
+            lines.push(table(["AGE", "SAVES", "EST. SIZE"], tranches.map((t) => [
+                String(t.label ?? t.id),
+                String(num(t.commit_count)),
+                formatBytes(num(t.est_bytes)),
+            ])));
+        }
+    }
+    lines.push("", chalk.bold("Cloud file history"));
+    if (status.cloud_error)
+        lines.push(`  Not available: ${status.cloud_error}`);
+    else if (status.cloud.length === 0)
+        lines.push("  No companies.");
+    for (const c of status.cloud) {
+        if (!c.available) {
+            lines.push(`  ${c.company}: not available - ${c.error ?? "unknown error"}`);
+            continue;
+        }
+        lines.push(`  ${c.company}: current ${formatBytes(c.current_bytes)}, old versions ` +
+            `${formatBytes(c.noncurrent_bytes)} (${c.noncurrent_count}), delete markers ${c.delete_markers}` +
+            (c.can_delete ? "" : " (view only: owners and admins can delete)"));
+        lines.push(table(["AGE", "OLD VERSIONS", "SIZE"], c.tranches.map((t) => [t.label, String(t.count), formatBytes(t.bytes)])));
+    }
+    if (status.offload)
+        lines.push("", ...formatOffloadStatus(status.offload));
+    return lines.join("\n");
+}
+function offloadUnavailable(err) {
+    const zero = { count: 0, bytes: 0 };
+    return {
+        history_candidates: zero,
+        current_candidates: { ...zero },
+        placeholders: { ...zero },
+        ...currentAvailability(false),
+        available: false,
+        reason: err instanceof Error ? err.message : String(err),
+    };
+}
+export function formatOffloadStatus(o) {
+    const lines = [chalk.bold("Big files")];
+    lines.push(`  Already in the cloud: ${o.placeholders.count} file(s), ${formatBytes(o.placeholders.bytes)}`);
+    if (o.available === false) {
+        lines.push(`  Not available: ${o.reason ?? "unknown"}`);
+        return lines;
+    }
+    if (o.history_held && o.history_held.count > 0) {
+        lines.push(`  Kept by other worktrees: ${o.history_held.count}, ${formatBytes(o.history_held.bytes)} (${o.history_held.worktrees
+            .slice(0, 5)
+            .map((p) => `worktree ${p}`)
+            .join(", ")})`);
+    }
+    lines.push(`  Old versions in history: ${o.history_candidates.count}, ${formatBytes(o.history_candidates.bytes)}`, `  Idle current files: ${o.current_candidates.count}, ${formatBytes(o.current_candidates.bytes)}`);
+    return lines;
+}
+export function formatOffload(r) {
+    const lines = [];
+    const h = r.history;
+    if (h.refused) {
+        lines.push(r.dry_run
+            ? `History: a real run would stop before uploading: ${h.message ?? ""}`.trimEnd()
+            : `History: nothing was uploaded or changed. ${h.message ?? ""}`.trimEnd());
+    }
+    else if (h.available === false) {
+        lines.push(`History: not available - ${h.reason ?? "unknown"}`);
+    }
+    else if (r.dry_run) {
+        lines.push(`History: would move ${h.candidates ?? 0} old version(s), ${formatBytes(h.candidate_bytes ?? 0)}`);
+        if (num(h.freed_bytes) > 0)
+            lines.push(`  ${formatBytes(num(h.freed_bytes))} is freed right away.`);
+    }
+    else {
+        lines.push(`History: uploaded ${h.uploaded} old version(s), ${formatBytes(h.bytes)}; freed ${formatBytes(h.freed_bytes)}`);
+    }
+    if (h.available !== false) {
+        const pending = reclaimLine(h);
+        if (pending)
+            lines.push(`  ${pending}`);
+        if (h.held_by_worktrees && h.held_by_worktrees.count > 0 && h.refused !== "nothing_to_free") {
+            const names = (h.worktree_holders ?? []).slice(0, 5).map((p) => `worktree ${p}`).join(", ");
+            lines.push(`  ${h.held_by_worktrees.count} more old version(s) (${formatBytes(h.held_by_worktrees.bytes)}) stay: ${names} still uses this history.`);
+        }
+    }
+    if (r.current.available === false) {
+        lines.push(`Current files: not available - ${r.current.reason ?? "unknown"}`);
+    }
+    else {
+        lines.push(`Current files: moved ${r.current.offloaded.length}, freed ${formatBytes(r.current.freed_bytes)}`);
+    }
+    for (const e of r.errors)
+        lines.push(chalk.red(`  ${e}`));
+    return lines.join("\n");
+}
+/** One line on when backed-up space comes back, or nothing. */
+export function reclaimLine(r) {
+    const pending = num(r.pending_reclaim_bytes);
+    if (pending <= 0 || typeof r.reclaim_after !== "string")
+        return undefined;
+    return `${formatBytes(pending)} stays on disk as undo history and is freed by ${r.reclaim_after}`;
+}
+/** Readable name for a ref that keeps old history: "branch wip", "tag v1". */
+export function holderName(ref) {
+    if (ref === "refs/stash")
+        return "changes set aside with git stash";
+    if (ref.startsWith("refs/heads/"))
+        return `branch ${ref.slice("refs/heads/".length)}`;
+    if (ref.startsWith("refs/tags/"))
+        return `tag ${ref.slice("refs/tags/".length)}`;
+    if (ref.startsWith("worktree:"))
+        return `worktree ${ref.slice("worktree:".length)}`;
+    return ref.replace(/^refs\//, "");
+}
+/** Plain refusal text when branches or tags keep the history prune would remove. */
+export function formatHoldingRefusal(local) {
+    const refs = Array.isArray(local.holding_refs) ? local.holding_refs : [];
+    const n = num(local.holding_refs_count) || refs.length;
+    const lines = [
+        `Local: nothing was changed. ${n} ${n === 1 ? "branch, saved version or worktree still uses" : "branches, saved versions or worktrees still use"} this history, so pruning it would free no space:`,
+        ...refs.slice(0, 10).map((r) => `  - ${holderName(r.name)}`),
+    ];
+    if (n > 10)
+        lines.push(`  - and ${n - 10} more`);
+    lines.push("They may hold work that exists nowhere else, so HQ leaves them alone.", "Next step: run `hq storage offload --dry-run` to see big old files that can move to the cloud instead.");
+    return lines;
+}
+/** Exit code for a prune result: 4 for nothing to free, 5 for a precondition, else 0/1. */
+export function pruneExitCode(result) {
+    const local = result.local;
+    if (local?.refused === "nothing_to_free")
+        return 4;
+    if (local && typeof local.refused === "string")
+        return 5;
+    if (result.cloud.some((c) => c.errors.length > 0))
+        return 1;
+    return 0;
+}
+/** Plain lines for a local prune that was not refused (dry or real). */
+export function formatLocalPrune(local, dryRun) {
+    const w = local.would_refuse && typeof local.would_refuse === "object" ? local.would_refuse : null;
+    if (dryRun && w) {
+        if (w.code === "nothing_to_free") {
+            const lines = formatHoldingRefusal({ ...local, holding_refs: w.holding_refs ?? local.holding_refs, holding_refs_count: w.holding_refs_count ?? local.holding_refs_count });
+            lines[0] = lines[0].replace("Local: nothing was changed.", "Local: a real run would stop and change nothing.");
+            return lines;
+        }
+        return [`Local: a real run would stop: ${String(w.message ?? "HQ history cannot be rewritten right now.")}`];
+    }
+    const lines = [];
+    if (dryRun) {
+        const n = num(local.would_remove_commits);
+        if (n === 0)
+            return ["Local: nothing older than that date to remove."];
+        lines.push(`Local: would combine ${n} old save(s) into one and free about ${formatBytes(num(local.est_bytes))}.`);
+    }
+    else {
+        const n = num(local.removed_commits);
+        if (n === 0)
+            return ["Local: nothing older than that date to remove."];
+        lines.push(`Local: combined ${n} old save(s) into one. Freed ${formatBytes(num(local.freed_bytes))} now.`);
+    }
+    const pending = reclaimLine(local);
+    if (pending)
+        lines.push(`  ${pending}`);
+    return lines;
+}
+export function formatStoragePrune(result) {
+    const verb = result.dry_run ? "Would delete" : "Deleted";
+    const lines = [];
+    const local = result.local;
+    if (local) {
+        if (local.available === false) {
+            lines.push(`Local: not available - ${String(local.reason ?? "unknown")}`);
+        }
+        else if (local.refused === "nothing_to_free") {
+            lines.push(...formatHoldingRefusal(local));
+        }
+        else if (typeof local.refused === "string") {
+            lines.push(`Local: ${String(local.message ?? "HQ history cannot be rewritten right now. Nothing was changed.")}`);
+        }
+        else {
+            lines.push(...formatLocalPrune(local, result.dry_run));
+        }
+    }
+    for (const c of result.cloud) {
+        if (c.skipped_reason) {
+            lines.push(`${c.company}: skipped - ${c.skipped_reason}`);
+            continue;
+        }
+        lines.push(`${c.company}: ${verb} ${c.deleted_count} old version(s), ${formatBytes(c.deleted_bytes)}`);
+        for (const e of c.errors)
+            lines.push(chalk.red(`  ${e}`));
+    }
+    return lines.join("\n");
+}
+// ── Production deps ─────────────────────────────────────────────────────────
+export const defaultRunScript = (scriptPath, args) => new Promise((resolve) => {
+    execFile("bash", [scriptPath, ...args], { maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const rawCode = err?.code;
+        const code = err ? (typeof rawCode === "number" ? rawCode : 1) : 0;
+        resolve({ code, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+export const NEEDS_YES = "No terminal to confirm in. Re-run with --yes to go ahead, or --dry-run to preview.";
+/**
+ * Ask y/N on a terminal. Without a TTY the question could never be answered,
+ * so it throws and the command exits non-zero instead of hanging or exiting 0.
+ */
+export function confirmOnTty(message, input = process.stdin, output = process.stdout) {
+    if (!input.isTTY)
+        return Promise.reject(new Error(NEEDS_YES));
+    const rl = readline.createInterface({ input, output });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+async function signedInVault() {
+    // Non-interactive: a signed-out run fails fast instead of waiting on a browser login.
+    const cred = await resolveVaultCredential({ interactive: false });
+    if (cred.kind === "api-key") {
+        throw new Error("hq storage needs a signed-in session. Run `hq login`.");
+    }
+    return { token: cred.token, vault: new VaultClient(buildVaultConfig(cred.token)) };
+}
+/**
+ * Deps for offload/fetch. The only store is the caller's personal vault,
+ * resolved from their canonical person entity and vended with `/sts/vend-self`.
+ */
+async function buildOffloadDeps() {
+    const hqRoot = findHqRoot();
+    const personalVault = async () => {
+        const { vault } = await signedInVault();
+        const personUid = await resolveCanonicalPersonUid({
+            listMyMemberships: () => vault.listMyMemberships(),
+            listPersonEntities: () => vault.entity.listByType("person"),
+            getEntity: async () => null,
+        });
+        const entity = await vault.entity.get(personUid);
+        if (entity.type !== "person") {
+            throw new Error("Offload only writes to your personal vault, and the resolved entity is not a person.");
+        }
+        if (!entity.bucketName)
+            throw new Error("Your personal vault has no storage yet. Run `hq onboard`.");
+        const vend = await vault.sts.vendSelf({ personUid: entity.uid });
+        return { bucket: entity.bucketName, credentials: vend.credentials };
+    };
+    const activeCompanies = async () => {
+        const { token } = await signedInVault();
+        const res = await vaultApiFetch({ token, path: "/membership/me" });
+        if (!res.ok) {
+            throw new Error(`Could not load your companies (HTTP ${res.status}). Run \`hq login\`.`);
+        }
+        return companiesFromMemberships(await res.json());
+    };
+    return {
+        hqRoot,
+        now: () => new Date(),
+        runScript: defaultRunScript,
+        confirm: (message) => confirmOnTty(message),
+        log: (line) => console.log(line),
+        exportBlob: gitExportBlob(hqRoot),
+        listPlaceholders: gitListPlaceholders(hqRoot),
+        tmpDir: defaultTmpDir,
+        syncExcludesOffload: () => syncExcludesOffload(PERSONAL_VAULT_EXCLUDED_TOP_LEVEL),
+        openPersonal: async () => {
+            const { bucket, credentials } = await personalVault();
+            return personalS3Store({ bucket, region: DEFAULT_COGNITO.region, credentials });
+        },
+        activeCompanySlugs: async () => (await activeCompanies()).map((c) => c.slug),
+        // Read-only, for placeholders that HQ sync rewrote. Company credentials
+        // come from the existing membership-scoped /sts/vend path.
+        openVaultObjects: async (target) => {
+            if (target.vault === "personal") {
+                const { bucket, credentials } = await personalVault();
+                return s3VaultObjectStore(bucket, new S3Client({ region: DEFAULT_COGNITO.region, credentials }));
+            }
+            const company = (await activeCompanies()).find((c) => c.slug === target.slug);
+            if (!company)
+                throw new Error(`You are not an active member of '${target.slug}'.`);
+            const { vault } = await signedInVault();
+            const vend = await vault.sts.vend({ companyUid: company.uid });
+            const entity = await vault.entity.get(company.uid);
+            const bucket = entity.bucketName ?? `hq-vault-cmp-${company.slug}`;
+            return s3VaultObjectStore(bucket, new S3Client({ region: DEFAULT_COGNITO.region, credentials: vend.credentials }));
+        },
+    };
+}
+async function buildDeps() {
+    // Sign-in is lazy so `status` can still report local sections when signed out.
+    let session;
+    const signedIn = () => (session ??= signedInVault());
+    const offloadDeps = await buildOffloadDeps();
+    return {
+        getOffload: () => getOffloadStatus(offloadDeps, {
+            minBytes: resolveMinBytes(undefined, process.env),
+            idleDays: DEFAULT_IDLE_DAYS,
+        }),
+        hqRoot: findHqRoot(),
+        now: () => new Date(),
+        runScript: defaultRunScript,
+        confirm: (message) => confirmOnTty(message),
+        log: (line) => console.log(line),
+        listCompanies: async () => {
+            const { token } = await signedIn();
+            const res = await vaultApiFetch({ token, path: "/membership/me" });
+            if (!res.ok) {
+                throw new Error(`Could not load your companies (HTTP ${res.status}). Run \`hq login\`.`);
+            }
+            return companiesFromMemberships(await res.json());
+        },
+        openCompany: async (company) => {
+            const { vault } = await signedIn();
+            const vend = await vault.sts.vend({ companyUid: company.uid });
+            const entity = await vault.entity.get(company.uid);
+            const bucket = entity.bucketName ?? `hq-vault-cmp-${company.slug}`;
+            const s3 = new S3Client({ region: DEFAULT_COGNITO.region, credentials: vend.credentials });
+            return { bucket, s3 };
+        },
+    };
+}
+// ── CLI registration ────────────────────────────────────────────────────────
+export function registerStorageCommand(program) {
+    const storage = program
+        .command("storage")
+        .description("See how much space HQ backups use and delete old ones");
+    storage
+        .command("status")
+        .description("Show local autosave history and cloud file history sizes")
+        .option("--json", "Print JSON")
+        .option("--company <slug>", "Only this company (must be one of yours)")
+        .action(async (opts) => {
+        try {
+            const status = await runStorageStatus({ company: opts.company }, await buildDeps());
+            console.log(opts.json ? JSON.stringify(status, null, 2) : formatStorageStatus(status));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    storage
+        .command("prune")
+        .description("Delete local autosave history and old cloud file versions before a date")
+        .option("--local-before <date>", "Prune local autosave history before YYYY-MM-DD")
+        .option("--cloud-before <date>", "Delete old (noncurrent) cloud file versions before YYYY-MM-DD")
+        .option("--company <slug>", "Only this company (must be one of yours)")
+        .option("--dry-run", "Show what would be deleted without deleting")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--json", "Print JSON")
+        .action(async (opts) => {
+        try {
+            const result = await runStoragePrune({
+                localBefore: opts.localBefore,
+                cloudBefore: opts.cloudBefore,
+                company: opts.company,
+                dryRun: Boolean(opts.dryRun),
+                yes: Boolean(opts.yes),
+            }, await buildDeps());
+            if (!result)
+                return;
+            console.log(opts.json ? JSON.stringify(result, null, 2) : formatStoragePrune(result));
+            // Same contract as core: 4 = nothing to free, 5 = precondition
+            // refusal; the JSON on stdout still describes it.
+            const code = pruneExitCode(result);
+            if (code !== 0)
+                process.exitCode = code;
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    storage
+        .command("offload")
+        .description("Move big files to your personal HQ cloud storage and leave links behind (old versions in history; idle current files)")
+        .option("--min-size <size>", "Only files at least this big, e.g. 50MB (env HQ_OFFLOAD_MIN_BYTES)")
+        .option("--idle-days <days>", "Current files must be untouched this many days", String(DEFAULT_IDLE_DAYS))
+        .option("--history", "Only old versions in local autosave history")
+        .option("--current", "Only idle files in the working tree")
+        .option("--dry-run", "Show what would move without uploading or changing anything")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--json", "Print JSON")
+        .action(async (opts) => {
+        try {
+            const idleDays = Number(opts.idleDays);
+            if (!Number.isInteger(idleDays) || idleDays < 0) {
+                throw new Error(`--idle-days must be a whole number, got '${opts.idleDays}'.`);
+            }
+            const result = await runOffload({
+                minBytes: resolveMinBytes(opts.minSize, process.env),
+                idleDays,
+                history: Boolean(opts.history),
+                current: Boolean(opts.current),
+                dryRun: Boolean(opts.dryRun),
+                yes: Boolean(opts.yes),
+            }, await buildOffloadDeps());
+            if (!result)
+                return;
+            console.log(opts.json ? JSON.stringify(result, null, 2) : formatOffload(result));
+            if (result.history.refused)
+                process.exitCode = result.history.refused === "nothing_to_free" ? 4 : 5;
+            else if (result.errors.length > 0)
+                process.exitCode = 1;
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    storage
+        .command("fetch [path]")
+        .description("Download a file moved to HQ cloud storage, check it, and put it back in place")
+        .option("--git-blob <sha>", "Download an old version from history by its git blob id")
+        .option("--out <file>", "Where to write the --git-blob or --force-orphan download")
+        .option("--force-orphan", "For a file a teammate deleted: write your own personal-vault copy to --out (outside HQ). It is never synced back to your team.")
+        .option("--json", "Print JSON")
+        .action(async (target, opts) => {
+        try {
+            const deps = await buildOffloadDeps();
+            let result;
+            if (opts.gitBlob !== undefined) {
+                if (!opts.out)
+                    throw new Error("--git-blob needs --out <file>.");
+                result = await runFetchGitBlob(opts.gitBlob, opts.out, deps);
+            }
+            else {
+                if (!target)
+                    throw new Error("Pass a path, a .hqcloud placeholder, or --git-blob <sha> --out <file>.");
+                result = await runFetch(target, deps, { forceOrphan: opts.forceOrphan, out: opts.out });
+            }
+            console.log(opts.json
+                ? JSON.stringify(result, null, 2)
+                : `Restored ${result.path} (${formatBytes(result.bytes)}), checksum verified.`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    return storage;
+}
+//# sourceMappingURL=storage.js.map