@indigoai-us/hq-cli 5.345.154 → 5.345.156

package/dist/commands/library-remove.js

@@ -0,0 +1,681 @@
+/**
+ * `hq library rm <placeholder|original> [more...]` — remove assets from the
+ * company media library.
+ *
+ * A library asset is three things: the `.hqcloud` placeholder in the tree,
+ * the same placeholder synced to the company vault at its company-relative
+ * path, and the content-addressed blob `.hq-offload/blobs/<sha256>` it points
+ * at. A fetched asset also has its original file beside the placeholder.
+ *
+ * What `rm` removes, in this order:
+ *   1. the local original, when one is on disk and its sha256 matches the
+ *      placeholder. Since hq-cloud #998, sync restores a deleted placeholder
+ *      while the original sits beside it, so the original has to go first.
+ *   2. the local placeholder;
+ *   3. the vault placeholder key, through POST /v1/files/delete (the endpoint
+ *      `hq files delete` uses; it versions the object and writes a tombstone so
+ *      sync does not bring it back). If sync already pushed the delete, the
+ *      key is simply gone.
+ *   4. with `--purge` only, the blob, once every placeholder that uses it is
+ *      gone.
+ *
+ * Nothing changes until every target has been checked: each must be a
+ * `vault: company` placeholder with an `hq-asset` block whose key is a
+ * `.hq-offload/blobs/<sha256>` blob. Personal placeholders, plain offload
+ * placeholders and synced-path keys (key = the file's own path) are refused.
+ * A dry-run delete of each vault key runs first, so a credential that cannot
+ * delete (an HQ_API_KEY without files:write) is refused before any local file
+ * is touched.
+ *
+ * The blob is kept by default: the same bytes added under two names share one
+ * blob, and teammates may hold placeholders this machine never synced.
+ * `--purge` deletes it only when no other placeholder references it, checked
+ * in the company's local tree and then in the company vault (see
+ * cloudBlobReferences: a quick asset search, then every `.hqcloud` key the
+ * caller can list). If either check finds another reference, or the vault
+ * check cannot run, `--purge` is refused and nothing changes.
+ *
+ * The vault bucket is versioned, so `hq files restore <key>` undoes the vault
+ * side.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import * as readline from "node:readline";
+import chalk from "chalk";
+import { isCloudPlaceholderName, parseCloudPlaceholder } from "@indigoai-us/hq-cloud";
+import { OFFLOAD_PREFIX, PLACEHOLDER_SUFFIX, digestFile, resolvePlaceholder } from "./storage-offload.js";
+/** A company library blob key: `.hq-offload/blobs/<64 lowercase hex>`. */
+const BLOB_KEY_PATTERN = /^\.hq-offload\/blobs\/([0-9a-f]{64})$/;
+/** hq-pro caps an asset search at 50 hits. */
+const CLOUD_REFERENCE_SEARCH_LIMIT = 50;
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+function posixRelative(hqRoot, abs) {
+    return path.relative(fs.realpathSync(path.resolve(hqRoot)), abs).split(path.sep).join("/");
+}
+function isCompanyUid(ref) {
+    return ref.startsWith("cmp_");
+}
+/**
+ * Check one target and work out what removing it means. Throws with a message
+ * that names the target and says what to do instead.
+ */
+async function planTarget(target, deps, hashFile) {
+    const placeholderAbs = resolvePlaceholder(deps.hqRoot, target);
+    const placeholderPath = posixRelative(deps.hqRoot, placeholderAbs);
+    const slug = /^companies\/([^/]+)\//.exec(placeholderPath)?.[1];
+    if (!slug) {
+        throw new Error(`'${placeholderPath}' is not inside companies/<slug>/, so it is not a company library asset.`);
+    }
+    const placeholder = parseCloudPlaceholder(await fs.promises.readFile(placeholderAbs, "utf8"));
+    if (!placeholder)
+        throw new Error(`'${placeholderPath}' is not a valid HQ cloud placeholder.`);
+    if (placeholder.vault !== "company") {
+        throw new Error(`'${placeholderPath}' is a ${placeholder.vault} placeholder. hq library rm only removes company library assets; ` +
+            "use `hq storage fetch` to bring a personal file back instead.");
+    }
+    if (!placeholder.asset) {
+        throw new Error(`'${placeholderPath}' is not a library asset (it has no hq-asset block). ` +
+            "It is a storage offload placeholder; use `hq storage fetch` to bring the file back.");
+    }
+    const originalAbs = placeholderAbs.slice(0, -PLACEHOLDER_SUFFIX.length);
+    const originalPath = placeholderPath.slice(0, -PLACEHOLDER_SUFFIX.length);
+    const vaultKey = placeholderPath.slice(`companies/${slug}/`.length);
+    const blob = BLOB_KEY_PATTERN.exec(placeholder.key);
+    if (!blob) {
+        throw new Error(`'${placeholderPath}' points at '${placeholder.key}', not a library blob (${OFFLOAD_PREFIX}<sha256>). ` +
+            "That key holds the file at its own synced path, and removing this entry could delete it for everyone. " +
+            "Use `hq storage fetch` and `hq files delete` if you mean to delete that file.");
+    }
+    if (placeholder.sha256 !== null && placeholder.sha256 !== blob[1]) {
+        throw new Error(`'${placeholderPath}' records sha256 ${placeholder.sha256} but points at blob ${blob[1]}. ` +
+            "Refusing to remove an inconsistent placeholder.");
+    }
+    let originalOnDisk = false;
+    const st = await fs.promises.lstat(originalAbs).catch((err) => {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    });
+    if (st) {
+        if (!st.isFile()) {
+            throw new Error(`'${originalPath}' is on disk but is not a regular file. Move it out of the library folder first.`);
+        }
+        const sha = await hashFile(originalAbs);
+        if (sha !== blob[1]) {
+            throw new Error(`'${originalPath}' is on disk and differs from the library copy (sha256 ${sha.slice(0, 12)}…, ` +
+                `library ${blob[1].slice(0, 12)}…). Move it out of the library folder first if you want to keep it, then re-run.`);
+        }
+        originalOnDisk = true;
+    }
+    return {
+        slug,
+        planned: {
+            placeholderAbs,
+            originalAbs,
+            originalOnDisk,
+            item: {
+                placeholderPath,
+                originalPath,
+                vaultKey,
+                blobKey: placeholder.key,
+                original: originalOnDisk ? "would-remove" : "absent",
+                placeholder: "would-remove",
+                vault: "not-run",
+            },
+        },
+    };
+}
+function walkPlaceholders(directory, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const child = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walkPlaceholders(child, out);
+        }
+        else if (entry.isFile() && isCloudPlaceholderName(entry.name)) {
+            out.push(child);
+        }
+    }
+}
+/** Local company placeholders, other than `exclude`, that point at `blobKey`. */
+export function localBlobReferences(hqRoot, slug, blobKey, exclude) {
+    const files = [];
+    walkPlaceholders(path.join(fs.realpathSync(path.resolve(hqRoot)), "companies", slug), files);
+    const refs = [];
+    for (const file of files.sort()) {
+        if (exclude.has(file))
+            continue;
+        let text;
+        try {
+            if (fs.statSync(file).size >= 4096)
+                continue;
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const placeholder = parseCloudPlaceholder(text);
+        if (placeholder?.vault === "company" && placeholder.key === blobKey)
+            refs.push(posixRelative(hqRoot, file));
+    }
+    return refs;
+}
+/** Company-relative form of a search hit's placeholder path. */
+function companyRelative(placeholderPath, slug) {
+    const anchored = `companies/${slug}/`;
+    return placeholderPath.startsWith(anchored) ? placeholderPath.slice(anchored.length) : placeholderPath;
+}
+/** Add `ref` to the reference list for `blobKey`. */
+function addRef(refs, blobKey, ref) {
+    const list = refs.get(blobKey) ?? [];
+    if (!list.includes(ref))
+        list.push(ref);
+    refs.set(blobKey, list);
+}
+function denialReason(res, body) {
+    const missing = Array.isArray(body.missing) ? body.missing.join(", ") : typeof body.missing === "string" ? body.missing : "";
+    if (missing)
+        return `this API key is missing ${missing}`;
+    return typeof body.error === "string" ? body.error : typeof body.message === "string" ? body.message : `HTTP ${res.status}`;
+}
+/**
+ * Placeholders in the company vault, other than `exclude` (company-relative
+ * keys), that point at any of `blobKeys`. Returns blob key → placeholder keys.
+ *
+ * Two passes:
+ *   1. a quick asset search (`kind: "asset"`, query "hqcloud", which every
+ *      placeholder path carries). Each hit returns its vaultKey, so a shared
+ *      blob is usually found in one call. This pass cannot prove a blob is
+ *      unused: hq-pro does not index the hashes and keys in a placeholder,
+ *      caps a search at 50 hits with no paging, and may lag a fresh upload.
+ *      Its errors are ignored; pass 2 decides.
+ *   2. when pass 1 finds nothing, every `.hqcloud` key the caller can list
+ *      (GET /v1/files/list, as `hq files search` does), read in one batched
+ *      presign and parsed. This lists the whole company vault, so it can take
+ *      minutes on a large one. Any listing or read failure throws: a purge
+ *      must not go ahead on a guess.
+ */
+export async function cloudBlobReferences(blobKeys, slug, companyUid, exclude, deps) {
+    const wanted = new Set(blobKeys);
+    const refs = new Map();
+    try {
+        const res = await deps.searchAssets({
+            query: "hqcloud",
+            kind: "asset",
+            company: companyUid,
+            limit: CLOUD_REFERENCE_SEARCH_LIMIT,
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (res.ok) {
+            for (const row of Array.isArray(body.results) ? body.results : []) {
+                const asset = row?.metadata?.asset;
+                if (!asset || typeof asset.vaultKey !== "string" || !wanted.has(asset.vaultKey))
+                    continue;
+                if (typeof asset.placeholderPath !== "string")
+                    continue;
+                const key = companyRelative(asset.placeholderPath, slug);
+                if (!exclude.has(key))
+                    addRef(refs, asset.vaultKey, key);
+            }
+        }
+    }
+    catch {
+        // Pass 2 is authoritative.
+    }
+    if (refs.size > 0)
+        return refs;
+    deps.log(chalk.dim("Checking every placeholder in the company vault for the same blob (a large vault can take a few minutes)..."));
+    let keys;
+    try {
+        keys = (await deps.listVaultKeys(companyUid)).filter((key) => key.endsWith(PLACEHOLDER_SUFFIX) && !exclude.has(key));
+    }
+    catch (err) {
+        throw new Error(`Could not list the company vault to check for other placeholders: ${err.message}`);
+    }
+    if (keys.length === 0)
+        return refs;
+    let texts;
+    try {
+        texts = await deps.readVaultObjects(companyUid, keys);
+    }
+    catch (err) {
+        throw new Error(`Could not read the company vault's placeholders to check for other references: ${err.message}`);
+    }
+    const unreadable = [];
+    for (const key of keys) {
+        const text = texts.get(key);
+        if (text === undefined || text === null) {
+            unreadable.push(key);
+            continue;
+        }
+        const placeholder = parseCloudPlaceholder(text);
+        if (placeholder?.vault === "company" && wanted.has(placeholder.key))
+            addRef(refs, placeholder.key, key);
+    }
+    if (unreadable.length > 0) {
+        throw new Error(`Could not read ${unreadable.length} placeholder(s) in the company vault (${unreadable.slice(0, 3).join(", ")}` +
+            `${unreadable.length > 3 ? ", ..." : ""}), so the blob may still be in use.`);
+    }
+    return refs;
+}
+/** GET /v1/files/list for every key in the company vault, following the cursor. */
+export async function listAllVaultKeys(companyUid, list) {
+    const keys = [];
+    let cursor;
+    for (let page = 0; page < 10_000; page++) {
+        const query = { company: companyUid };
+        if (cursor)
+            query.cursor = cursor;
+        const res = await list(query);
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(denialReason(res, body));
+        for (const object of Array.isArray(body.objects) ? body.objects : []) {
+            const key = object?.key;
+            if (typeof key === "string")
+                keys.push(key);
+        }
+        cursor = typeof body.cursor === "string" && body.cursor ? body.cursor : undefined;
+        if (!cursor)
+            return keys;
+    }
+    throw new Error("the vault listing did not end");
+}
+/** hq-pro accepts up to 1000 keys per presign request. */
+const PRESIGN_BATCH = 1000;
+const READ_CONCURRENCY = 8;
+/**
+ * Read small vault objects: one batched presign (op "get") per 1000 keys, then
+ * a GET per URL. A key that cannot be presigned or read maps to null. Errors
+ * never include a URL, which carries a signature.
+ */
+export async function readSmallVaultObjects(companyUid, keys, presign, get = (url) => fetch(url)) {
+    const out = new Map();
+    for (let i = 0; i < keys.length; i += PRESIGN_BATCH) {
+        const batch = keys.slice(i, i + PRESIGN_BATCH);
+        const res = await presign({ company: companyUid, op: "get", keys: batch });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(denialReason(res, body));
+        const urls = new Map();
+        for (const row of Array.isArray(body.results) ? body.results : []) {
+            const r = (row ?? {});
+            if (typeof r.key === "string" && typeof r.url === "string")
+                urls.set(r.key, r.url);
+        }
+        const queue = [...batch];
+        const worker = async () => {
+            for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
+                const url = urls.get(key);
+                if (!url) {
+                    out.set(key, null);
+                    continue;
+                }
+                try {
+                    const got = await get(url);
+                    const text = got.ok ? await got.text() : null;
+                    // A placeholder is under 4 KiB; a larger `.hqcloud` object is not one
+                    // and cannot reference a blob, so it reads as empty text.
+                    out.set(key, text === null ? null : Buffer.byteLength(text) < 4096 ? text : "");
+                }
+                catch {
+                    out.set(key, null);
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: READ_CONCURRENCY }, worker));
+    }
+    return out;
+}
+function describeItem(p, dryRun) {
+    const verb = dryRun ? "would remove" : "remove";
+    const lines = [`  ${chalk.bold(p.item.placeholderPath)}`];
+    if (p.originalOnDisk)
+        lines.push(`    local original: ${p.item.originalPath} (${verb}, sha256 matches the library copy)`);
+    lines.push(`    local placeholder: ${verb}`);
+    lines.push(p.vaultHas
+        ? `    vault key: ${p.item.vaultKey} (${verb})`
+        : `    vault key: ${p.item.vaultKey} (not in the vault; nothing to remove there)`);
+    return lines;
+}
+/**
+ * Testable core. Checks every target, previews, confirms, then removes in the
+ * order described at the top of this file.
+ */
+export async function runLibraryRemove(targets, options, deps) {
+    if (targets.length === 0)
+        throw new Error("Pass at least one library placeholder or original path.");
+    const hashFile = deps.hashFile ?? (async (file) => (await digestFile(file)).sha256);
+    const removeFile = deps.removeFile ?? ((file) => fs.promises.rm(file));
+    const dryRun = options.dryRun === true;
+    const purge = options.purge === true;
+    // 1. Check every target. Nothing changes if any of them is refused.
+    const planned = [];
+    const seen = new Set();
+    let slug;
+    for (const target of targets) {
+        const plan = await planTarget(target, deps, hashFile);
+        if (slug !== undefined && plan.slug !== slug) {
+            throw new Error(`All targets must be in one company; got companies/${slug}/ and companies/${plan.slug}/.`);
+        }
+        slug = plan.slug;
+        if (seen.has(plan.planned.placeholderAbs))
+            continue;
+        seen.add(plan.planned.placeholderAbs);
+        planned.push(plan.planned);
+    }
+    const company = slug;
+    if (options.company !== undefined && !isCompanyUid(options.company) && options.company !== company) {
+        throw new Error(`The targets are in companies/${company}/, but --company is ${options.company}.`);
+    }
+    const companyUid = await deps.resolveCompany(company);
+    if (options.company !== undefined && isCompanyUid(options.company) && options.company !== companyUid) {
+        throw new Error(`The targets are in companies/${company}/ (${companyUid}), but --company is ${options.company}.`);
+    }
+    // 2. Ask the vault what it holds, with the delete endpoint's own dry run.
+    //    This is also the permission check: a credential that cannot delete is
+    //    refused here, before any local file is touched.
+    const plans = [];
+    for (const p of planned) {
+        const preview = await deps.deleteKey(companyUid, p.item.vaultKey, true);
+        plans.push({ ...p, vaultHas: preview.matched > 0 });
+    }
+    // A local original is normally an untracked copy of the blob. If the vault
+    // also holds it at its own path, it is a synced file, and deleting it here
+    // would let sync delete that copy for everyone. Leave that to the user.
+    for (const p of plans) {
+        if (!p.originalOnDisk)
+            continue;
+        const originalKey = p.item.originalPath.slice(`companies/${company}/`.length);
+        const preview = await deps.deleteKey(companyUid, originalKey, true);
+        if (preview.matched > 0) {
+            throw new Error(`'${p.item.originalPath}' is also stored in the vault at its own path, so it is a synced file, not only a ` +
+                "fetched copy. Move it out of the library folder (or delete it with `hq files delete`) first, then re-run. " +
+                "Nothing was removed.");
+        }
+    }
+    for (const p of plans)
+        p.item.vault = p.vaultHas ? "would-remove" : "absent";
+    // 3. Blobs. Kept unless --purge, and purged only when nothing else uses them.
+    const blobKeys = [...new Set(plans.map((p) => p.item.blobKey))];
+    const blobs = [];
+    if (purge) {
+        const removingFiles = new Set(plans.map((p) => p.placeholderAbs));
+        const removingKeys = new Set(plans.map((p) => p.item.vaultKey));
+        const problems = [];
+        const localRefs = new Map(blobKeys.map((key) => [key, localBlobReferences(deps.hqRoot, company, key, removingFiles)]));
+        // Local references are enough to refuse; only ask the vault when the tree has none.
+        const cloudRefs = [...localRefs.values()].some((refs) => refs.length > 0)
+            ? new Map()
+            : await cloudBlobReferences(blobKeys, company, companyUid, removingKeys, deps);
+        for (const key of blobKeys) {
+            const local = localRefs.get(key) ?? [];
+            const cloud = (cloudRefs.get(key) ?? []).filter((ref) => !local.includes(`companies/${company}/${ref}`));
+            const refs = [...local, ...cloud.map((ref) => `${ref} (in the vault)`)];
+            if (refs.length > 0)
+                problems.push(`${key} is also used by: ${refs.join(", ")}`);
+        }
+        if (problems.length > 0) {
+            throw new Error(`Refusing --purge: other library placeholders point at the same blob.\n  ${problems.join("\n  ")}\n` +
+                "Remove those too in the same command, or re-run without --purge to keep the blob. Nothing was removed.");
+        }
+        for (const key of blobKeys) {
+            const preview = await deps.deleteKey(companyUid, key, true);
+            blobs.push({ key, state: preview.matched > 0 ? "would-remove" : "absent" });
+        }
+    }
+    else {
+        for (const key of blobKeys)
+            blobs.push({ key, state: "kept" });
+    }
+    const undo = [
+        ...plans.filter((p) => p.vaultHas).map((p) => `hq files restore ${p.item.vaultKey} --company ${company}`),
+        ...blobs.filter((b) => b.state === "would-remove").map((b) => `hq files restore ${b.key} --company ${company}`),
+    ];
+    const result = {
+        company,
+        companyUid,
+        dryRun,
+        purge,
+        confirmed: false,
+        items: plans.map((p) => p.item),
+        blobs,
+        undo,
+    };
+    // 4. Preview.
+    const noun = plans.length === 1 ? "library asset" : "library assets";
+    deps.log(chalk.yellow(`${dryRun ? "[dry-run] Would remove" : "About to remove"} ${plans.length} ${noun} from companies/${company}/:`));
+    for (const p of plans)
+        for (const line of describeItem(p, dryRun))
+            deps.log(line);
+    for (const blob of blobs) {
+        deps.log(blob.state === "kept"
+            ? chalk.dim(`  blob ${blob.key}: kept (other placeholders may use it; pass --purge to delete it)`)
+            : blob.state === "absent"
+                ? chalk.dim(`  blob ${blob.key}: not in the vault`)
+                : `  blob ${blob.key}: ${dryRun ? "would delete" : "delete"} (no other placeholder uses it)`);
+    }
+    if (dryRun) {
+        deps.log(chalk.dim("Nothing was removed (--dry-run)."));
+        return result;
+    }
+    // 5. Confirm.
+    if (!options.yes) {
+        const ok = await deps.confirm(`Remove ${plans.length} ${noun}? This deletes them from the shared vault for everyone` +
+            (plans.some((p) => p.originalOnDisk) ? " and deletes the local originals listed above" : "") +
+            ".");
+        if (!ok) {
+            for (const p of plans) {
+                p.item.original = p.originalOnDisk ? "kept" : "absent";
+                p.item.placeholder = "kept";
+                p.item.vault = p.vaultHas ? "kept" : "absent";
+            }
+            for (const blob of blobs)
+                if (blob.state === "would-remove")
+                    blob.state = "kept";
+            deps.log(chalk.dim("Aborted. Nothing was removed."));
+            return result;
+        }
+    }
+    result.confirmed = true;
+    // 6. Remove: local original, local placeholder, vault key. A failed step
+    //    stops that asset; the others still run.
+    const failedBlobs = new Set();
+    for (const p of plans) {
+        const { item } = p;
+        try {
+            if (p.originalOnDisk) {
+                item.original = "failed";
+                await removeFile(p.originalAbs);
+                item.original = "removed";
+            }
+            item.placeholder = "failed";
+            await removeFile(p.placeholderAbs);
+            item.placeholder = "removed";
+            if (p.vaultHas) {
+                item.vault = "failed";
+                await deps.deleteKey(companyUid, item.vaultKey, false);
+                // matched 0 here means sync pushed the delete first: the key is gone either way.
+                item.vault = "removed";
+            }
+        }
+        catch (err) {
+            item.error = err.message;
+            if (item.placeholder === "would-remove")
+                item.placeholder = "not-run";
+            if (item.vault === "would-remove")
+                item.vault = "not-run";
+            failedBlobs.add(item.blobKey);
+        }
+    }
+    // 7. Purge blobs whose placeholders were all removed.
+    for (const blob of blobs) {
+        if (blob.state !== "would-remove")
+            continue;
+        if (failedBlobs.has(blob.key)) {
+            blob.state = "not-run";
+            blob.error = "kept because removing a placeholder that uses it failed";
+            continue;
+        }
+        try {
+            blob.state = "failed";
+            await deps.deleteKey(companyUid, blob.key, false);
+            blob.state = "removed";
+        }
+        catch (err) {
+            blob.error = err.message;
+        }
+    }
+    return result;
+}
+export function formatLibraryRemoveResult(result) {
+    if (result.dryRun || !result.confirmed)
+        return "";
+    const lines = [];
+    for (const item of result.items) {
+        if (item.error) {
+            lines.push(`${chalk.red("Not removed")} ${item.placeholderPath}: ${item.error}`);
+            const done = [
+                item.original === "removed" ? "local original" : "",
+                item.placeholder === "removed" ? "local placeholder" : "",
+            ].filter(Boolean);
+            if (done.length > 0)
+                lines.push(chalk.yellow(`  Already removed: ${done.join(", ")}.`));
+            continue;
+        }
+        const parts = [
+            item.original === "removed" ? "local original" : "",
+            "local placeholder",
+            item.vault === "removed" ? `vault key ${item.vaultKey}` : "",
+        ].filter(Boolean);
+        lines.push(`${chalk.green("Removed")} ${item.placeholderPath} (${parts.join(", ")})`);
+    }
+    for (const blob of result.blobs) {
+        if (blob.state === "removed")
+            lines.push(`${chalk.green("Deleted")} blob ${blob.key}`);
+        else if (blob.state === "kept")
+            lines.push(chalk.dim(`Kept blob ${blob.key}.`));
+        else if (blob.error)
+            lines.push(`${chalk.red("Blob not deleted")} ${blob.key}: ${blob.error}`);
+    }
+    if (result.undo.length > 0) {
+        lines.push(chalk.dim("The vault keeps prior versions. To undo the vault side, run:"));
+        for (const cmd of result.undo)
+            lines.push(chalk.dim(`  ${cmd}`));
+        lines.push(chalk.dim("then `hq sync` to bring the placeholder back, and `hq library fetch` for the original."));
+    }
+    return lines.join("\n");
+}
+/**
+ * User-facing message for a failed POST /v1/files/delete. `err` is duck-typed
+ * on `status` (files.ts's FilesDeleteHttpError) so this module does not load
+ * files.ts at startup.
+ */
+export function vaultDeleteErrorMessage(err, key, apiKey, format) {
+    const status = err?.status;
+    if (typeof status !== "number")
+        return err.message;
+    if (status === 403 && apiKey) {
+        return (`This API key cannot remove library assets: deleting '${key}' needs files:write ` +
+            `(${err.message}). Use a key with files:write, or unset HQ_API_KEY and run signed in.`);
+    }
+    return format(err, key);
+}
+/** Yes/no prompt on stderr, so `--json` stdout stays machine-readable. */
+function confirmOnStderr(message) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+/**
+ * Company resolver for rm. A session resolves slugs through the API. An
+ * HQ_API_KEY cannot (hq-pro serves no keyed membership lookup), so it maps the
+ * placeholder folder's slug, or an explicit `--company` slug or uid, through
+ * companies/manifest.yaml with library.ts's libraryCompanyForApiKey; hq-pro
+ * still checks the uid against the key on every delete.
+ */
+export async function removeCompanyResolver(credential, hqRoot, explicit) {
+    const { getCompanyUid } = await import("../utils/vault-api.js");
+    if (credential.kind === "cognito")
+        return (slug) => getCompanyUid(credential.token, slug);
+    // The same manifest mapping `add`, `describe` and `link` use on a key
+    // (#2080). Imported lazily: library.ts registers this module.
+    const [{ readCompaniesManifestMap }, { libraryCompanyForApiKey }] = await Promise.all([
+        import("../lib/work-context/repo-remote.js"),
+        import("./library.js"),
+    ]);
+    return async (slug) => libraryCompanyForApiKey(readCompaniesManifestMap(hqRoot), explicit ?? slug, slug).uid;
+}
+export function registerLibraryRemoveCommand(library) {
+    library
+        .command("rm")
+        .alias("remove")
+        .description("Remove library assets: the local original (if fetched), the placeholder, and its vault copy. " +
+        "Keeps the shared blob unless --purge. Previews and asks first unless --yes")
+        .argument("<targets...>", "Library .hqcloud placeholders (or their original paths)")
+        .option("--company <company>", "Company slug (or cmp_ uid); default: the targets' companies/<slug>/")
+        .option("--purge", "Also delete the blob, after checking no other placeholder (local or in the vault) uses it")
+        .option("--dry-run", "Show what would be removed without changing anything")
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--json", "Print machine-readable JSON (the preview goes to stderr)")
+        .action(async (targets, options) => {
+        try {
+            const [{ resolveVaultCredentialForCapability }, { vaultApiFetch }, { findHqRoot }] = await Promise.all([
+                import("../utils/resolve-vault-credential.js"),
+                import("../utils/vault-api.js"),
+                import("../utils/manifest.js"),
+            ]);
+            const credential = await resolveVaultCredentialForCapability("files:write", "library rm", {
+                interactive: true,
+            });
+            const { token } = credential;
+            const apiKey = credential.kind === "api-key";
+            const hqRoot = findHqRoot();
+            const log = options.json ? (line) => console.error(line) : (line) => console.log(line);
+            const result = await runLibraryRemove(targets, { company: options.company, purge: options.purge, dryRun: options.dryRun, yes: options.yes }, {
+                hqRoot,
+                resolveCompany: await removeCompanyResolver(credential, hqRoot, options.company),
+                deleteKey: async (companyUid, key, dryRun) => {
+                    const { callDeleteEndpoint, formatFilesDeleteError } = await import("./files.js");
+                    try {
+                        return await callDeleteEndpoint({ token, companyUid, prefix: key, dryRun });
+                    }
+                    catch (err) {
+                        throw new Error(vaultDeleteErrorMessage(err, key, apiKey, formatFilesDeleteError));
+                    }
+                },
+                searchAssets: (body) => vaultApiFetch({ token, path: "/v1/search", method: "POST", body }),
+                listVaultKeys: (companyUid) => listAllVaultKeys(companyUid, (query) => vaultApiFetch({ token, path: "/v1/files/list", query })),
+                readVaultObjects: (companyUid, keys) => readSmallVaultObjects(companyUid, keys, (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body })),
+                confirm: confirmOnStderr,
+                log,
+            });
+            if (options.json)
+                console.log(JSON.stringify(result, null, 2));
+            else {
+                const text = formatLibraryRemoveResult(result);
+                if (text)
+                    console.log(text);
+            }
+            if (result.items.some((item) => item.error) || result.blobs.some((blob) => blob.error && blob.state === "failed")) {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=library-remove.js.map