@indigoai-us/hq-cli 5.345.80 → 5.345.82

package/dist/commands/storage.d.ts

@@ -0,0 +1,249 @@
+/**
+ * `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 { Command } from "commander";
+import { type ReclaimReport } from "./storage-core.js";
+import { ListObjectVersionsCommand, DeleteObjectsCommand, type ListObjectVersionsCommandOutput, type DeleteObjectsCommandOutput } from "@aws-sdk/client-s3";
+import { type OffloadResult, type OffloadStatus } from "./storage-offload.js";
+export type TrancheId = "7d" | "30d" | "90d" | "365d" | "older";
+export declare const TRANCHES: readonly {
+    id: TrancheId;
+    label: string;
+    maxAgeDays: number;
+}[];
+export declare function trancheFor(lastModified: Date, now: Date): TrancheId;
+export type LocalReport = Record<string, unknown> & {
+    available?: boolean;
+    reason?: string;
+};
+export interface CloudTranche {
+    id: TrancheId;
+    label: string;
+    count: number;
+    bytes: number;
+}
+export interface CloudCompanyStatus {
+    company: string;
+    available: boolean;
+    /** Whether the caller may delete this company's old versions (owner/admin). */
+    can_delete: boolean;
+    current_bytes: number;
+    noncurrent_bytes: number;
+    noncurrent_count: number;
+    delete_markers: number;
+    tranches: CloudTranche[];
+    error?: string;
+    /** When these figures were listed (ISO). Older than now when served from the cache. */
+    listed_at?: string;
+}
+export interface StorageStatus {
+    local: LocalReport;
+    cloud: CloudCompanyStatus[];
+    /** Set when cloud history could not be read at all, e.g. not signed in. */
+    cloud_error?: string;
+    offload?: OffloadStatus;
+    generated_at: string;
+}
+export interface CloudPruneResult {
+    company: string;
+    deleted_count: number;
+    deleted_bytes: number;
+    errors: string[];
+    /** Set when the company was not touched, e.g. the caller is not an owner/admin. */
+    skipped_reason?: string;
+    /** True when S3 refused the delete for this company (role not granted). */
+    access_denied?: boolean;
+}
+export interface StoragePruneResult {
+    local: LocalReport | null;
+    cloud: CloudPruneResult[];
+    dry_run: boolean;
+    /** Expired backups dropped before a real local prune; absent otherwise. */
+    reclaim?: ReclaimReport;
+}
+/** Subset of S3Client this command uses. Injectable for tests. */
+export interface StorageS3Client {
+    send(cmd: ListObjectVersionsCommand): Promise<ListObjectVersionsCommandOutput>;
+    send(cmd: DeleteObjectsCommand): Promise<DeleteObjectsCommandOutput>;
+}
+export interface CompanyRef {
+    uid: string;
+    slug: string;
+    /** Membership role from `/membership/me`: owner, admin, member or guest. */
+    role?: string;
+}
+/** Cloud history delete is owners and admins only. A missing role is not enough. */
+export declare function canDeleteCloudHistory(company: CompanyRef): boolean;
+export declare const DELETE_ROLE_REASON = "Only company owners and admins can delete cloud file history.";
+export interface CompanyStore {
+    bucket: string;
+    s3: StorageS3Client;
+}
+export type ScriptRunner = (scriptPath: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export interface StorageDeps {
+    hqRoot: string;
+    now: () => Date;
+    /** The caller's active company memberships. */
+    listCompanies: () => Promise<CompanyRef[]>;
+    /** Vend credentials and resolve the bucket for one member company. */
+    openCompany: (company: CompanyRef) => Promise<CompanyStore>;
+    runScript: ScriptRunner;
+    confirm: (message: string) => Promise<boolean>;
+    log: (line: string) => void;
+    /** Offload section for `status`. Absent in deps that only prune. */
+    getOffload?: () => Promise<OffloadStatus>;
+    /** Cache of cloud status per company (see cloudStatusCache). Absent = always list. */
+    cloudCache?: CloudStatusCache;
+}
+/**
+ * Listing every version of a large vault takes minutes (about 2 for 2.4M
+ * versions, most of it parsing S3's XML), so `status` keeps each company's
+ * cloud figures for CLOUD_CACHE_TTL_MS. Only complete, successful listings are
+ * kept; a real cloud prune drops the company's entry; dry runs and real prunes
+ * always list live.
+ */
+export interface CloudStatusCache {
+    read(company: CompanyRef): CloudCompanyStatus | undefined;
+    write(company: CompanyRef, status: CloudCompanyStatus): void;
+    drop(company: CompanyRef): void;
+}
+export declare const CLOUD_CACHE_TTL_MS: number;
+/** File cache under <hq>/workspace/.storage-cache/cloud-<company uid>.json. */
+export declare function cloudStatusCache(hqRoot: string, now: () => Date, ttlMs?: number): CloudStatusCache;
+export declare function localScriptPath(hqRoot: string): string;
+/**
+ * Core `drop-backups --expired` right before a real local prune; undefined
+ * when HQ lacks it. Status, dry runs and fetch never call it.
+ */
+export declare function dropExpiredLocal(deps: StorageDeps): Promise<ReclaimReport | undefined>;
+export declare function getLocalReport(deps: StorageDeps): Promise<LocalReport>;
+export declare function selectCompanies(memberships: CompanyRef[], requested: string | undefined): CompanyRef[];
+/**
+ * Active memberships from a `/membership/me` body, one per company. A company
+ * listed more than once keeps its highest-privilege role.
+ */
+export declare function companiesFromMemberships(body: unknown): CompanyRef[];
+export interface VersionEntry {
+    key: string;
+    versionId: string;
+    isLatest: boolean;
+    lastModified: Date;
+    size: number;
+    isDeleteMarker: boolean;
+    /**
+     * When this version stopped being current: the LastModified of the next
+     * newer version or delete marker of the same key. Unset for current entries.
+     */
+    noncurrentSince?: Date;
+}
+/**
+ * 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 declare function annotateNoncurrentSince(entries: VersionEntry[]): VersionEntry[];
+/** Folder levels split into parallel listings (`a/`, then `a/b/`). */
+export declare const LIST_SPLIT_DEPTH = 2;
+/** Listings in flight at once per bucket. */
+export declare const LIST_CONCURRENCY = 32;
+/**
+ * A printable-ASCII key strictly between `lo` and `hi` in S3's (UTF-8 byte)
+ * order, or undefined when none is found. Used to split one long listing into
+ * two that run at the same time.
+ */
+export declare function keyBetween(lo: string, hi: string): string | undefined;
+/** Plain message when S3 refuses a version delete for one company. */
+export declare function deleteDeniedMessage(slug: string): string;
+export declare function describeCloudError(err: unknown, action: "list" | "delete", slug?: string): string;
+export declare function getCloudStatus(company: CompanyRef, deps: StorageDeps): Promise<CloudCompanyStatus>;
+/**
+ * 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 declare function selectPrunable(versions: VersionEntry[], cutoff: Date): VersionEntry[];
+export declare function pruneCloud(company: CompanyRef, cutoff: Date, dryRun: boolean, deps: StorageDeps): Promise<CloudPruneResult>;
+export declare function runStorageStatus(opts: {
+    company?: string;
+    noCache?: boolean;
+}, deps: StorageDeps): Promise<StorageStatus>;
+export declare function parseCutoff(value: string, flag: string): Date;
+export declare function runStoragePrune(opts: {
+    localBefore?: string;
+    cloudBefore?: string;
+    company?: string;
+    dryRun: boolean;
+    yes: boolean;
+}, deps: StorageDeps): Promise<StoragePruneResult | undefined>;
+export declare function formatBytes(bytes: number): string;
+export declare function formatStorageStatus(status: StorageStatus): string;
+export declare function formatOffloadStatus(o: OffloadStatus): string[];
+export declare function formatOffload(r: OffloadResult): string;
+/** One line on when backed-up space comes back, or nothing. */
+export declare function reclaimLine(r: Record<string, unknown>): string | undefined;
+/** Readable name for a ref that keeps old history: "branch wip", "tag v1". */
+export declare function holderName(ref: string): string;
+/** Plain refusal text when branches or tags keep the history prune would remove. */
+export declare function formatHoldingRefusal(local: LocalReport): string[];
+/** Exit code for a prune result: 4 for nothing to free, 5 for a precondition, else 0/1. */
+export declare function pruneExitCode(result: StoragePruneResult): number;
+/** Plain lines for a local prune that was not refused (dry or real). */
+export declare function formatLocalPrune(local: LocalReport, dryRun: boolean): string[];
+export declare function formatStoragePrune(result: StoragePruneResult): string;
+export declare const defaultRunScript: ScriptRunner;
+export declare 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 declare function confirmOnTty(message: string, input?: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}, output?: NodeJS.WritableStream): Promise<boolean>;
+/** STS credentials from one vend, with the time they stop working. */
+export interface VendedCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiresAt?: string;
+}
+/**
+ * AWS credential provider that vends fresh credentials on first use and again
+ * whenever the previous ones are within `marginMs` of expiring. Each vend calls
+ * `vend` anew, which signs in again (the CLI refreshes an expiring Cognito
+ * session there), so a cloud listing or delete that starts after a long local
+ * scan, or that itself outlasts one STS session, never sends an expired token.
+ */
+export declare function refreshingVendedCredentials(vend: () => Promise<VendedCredentials>, now?: () => number, marginMs?: number): () => Promise<{
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration?: Date;
+}>;
+export declare function registerStorageCommand(program: Command): Command;
+//# sourceMappingURL=storage.d.ts.map