promptdock 1.2.0 → 1.2.1

package/dist/commands/lifecycle.js

@@ -5,6 +5,7 @@ import { existsSync, lstatSync, rmdirSync, rmSync, unlinkSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
 import { ensureAuth } from "../auth.js";
 import { CliError, EXIT, mapFsError, usageError } from "../errors.js";
+import { SERVER_LABEL_MAX, SERVER_PATH_MAX, terminalLine } from "../terminal-text.js";
 import { checkInstallResponse, performInstall } from "../installer.js";
 import { formatRef, parseSkillRef } from "../ref.js";
 import { modifiedFiles, readReceipt, scanReceipts, RECEIPT_NAME, } from "../receipts.js";
@@ -16,8 +17,88 @@ function scopeOf(flags) {
         return "both";
     return flags.global === true ? "global" : "local";
 }
-function newerSchemaError(dir, schema, argsLine) {
-    return new CliError(`${dir} was installed by a newer promptdock CLI (receipt schema ${schema}). Run: npx promptdock@latest ${argsLine}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
+/**
+ * A re-run line built from the PARSED invocation — never from `ctx.argsLine`.
+ *
+ * `argsLine` is the REDACTED copy that rides `X-Promptdock-Cli-Args`: context.ts
+ * replaces `--token` and `--dir` values with `***` so a live bearer and an absolute
+ * home path never reach the server or a proxy log. Echoing it back into a "Run: …"
+ * remedy printed `npx promptdock@latest install a/b --dir ***` — a command that
+ * cannot be pasted, handed to the user at the one moment they need a command they
+ * can paste. The parsed flags hold the REAL values, so the remedy is built from
+ * those and the redaction stays where it belongs: on the wire.
+ */
+export function rerunCommand(command, positionals, flags) {
+    const parts = [command, ...positionals];
+    for (const [name, value] of Object.entries(flags)) {
+        // `--help` would turn the remedy into a no-op; `--token` is why redaction exists
+        // in the first place and must never be re-emitted, even though no lifecycle
+        // command accepts one today (a future one would inherit this guard silently).
+        if (name === "help" || name === "token")
+            continue;
+        if (value === true)
+            parts.push(`--${name}`);
+        else if (typeof value === "string")
+            parts.push(`--${name}`, shellArg(value));
+    }
+    return `npx promptdock@latest ${parts.join(" ")}`;
+}
+/** Single-quote a value the user is meant to paste (paths carry spaces). */
+function shellArg(value) {
+    return /^[\w@./:+-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+export function newerSchemaError(dir, schema, rerun) {
+    return new CliError(`${dir} was installed by a newer promptdock CLI (receipt schema ${schema}). Run: ${rerun}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
+}
+/**
+ * Turn per-item failures into the process's exit.
+ *
+ * WHY THIS EXISTS: both batch commands used to record every failure as
+ * `status: "skipped"` and return normally, so `promptdock update --all -y` in CI
+ * exited 0 having updated nothing — the job went green on the exact outcome it was
+ * added to catch. A silent no-op is worse than a red build.
+ *
+ * WHAT COUNTS: only a real failure. "Up to date", "an update is available"
+ * (--check), and a human answering No to a confirm are all correct outcomes and
+ * stay 0 — otherwise `--check` could never be used as a plain report.
+ *
+ * THE CODE: the FIRST failure's own exit code, so a single-item batch exits exactly
+ * as the same operation would have outside a batch, and a mixed batch still reports
+ * a cause rather than a generic "something failed".
+ */
+function batchExitError(failures, allowPartial, 
+/** true when the per-item `! <ref>: <message>` lines already went to stderr (non-JSON) */
+alreadyPrinted) {
+    if (allowPartial || failures.length === 0)
+        return null;
+    const first = failures[0].error;
+    // A heterogeneous batch: keep the first code, but only keep a docs footer when every
+    // failure points at the same page — one anchor cannot answer three different causes.
+    const footer = failures.every((f) => f.error.footer === first.footer) ? first.footer : undefined;
+    if (alreadyPrinted) {
+        // ⚠️ The `!` lines above already carry every ref and every message, so restating
+        // them here printed the identical sentence TWICE for one failure and 2N times for
+        // N — on the exact output a stuck user or a CI log reads. Returning the first
+        // failure verbatim is what preserved its hint and docs footer, so those ride this
+        // error instead; only the already-printed message is replaced.
+        return new CliError(failures.length === 1
+            ? "1 item failed (see above)."
+            : `${failures.length} items failed (see above).`, first.exitCode, {
+            footer,
+            hint: failures.length === 1 ? first.hint : "pass --allow-partial to exit 0 when some items fail",
+        });
+    }
+    // --json: the per-item lines were never printed (stdout must stay parseable), so
+    // "see above" would point at nothing and the only human-readable cause on stderr
+    // has to ride the thrown error.
+    if (failures.length === 1)
+        return first; // verbatim: same message, hint and footer
+    return new CliError(`${failures.length} items failed:\n` +
+        failures.map((f) => `  ${f.ref}: ${f.error.message}`).join("\n"), first.exitCode, { footer, hint: "pass --allow-partial to exit 0 when some items fail" });
+}
+/** A per-item error as a CliError (an unexpected throw is still a real failure). */
+function asCliError(err, exitCode) {
+    return err instanceof CliError ? err : new CliError(String(err), exitCode);
 }
 /** Collect the receipts a lifecycle command operates on. */
 function collect(ctx, flags, refArg) {
@@ -52,39 +133,96 @@ export async function runUninstall(ctx, positionals, flags) {
         throw usageError("pass a skill ref, --all, or --dir <path>", "usage: promptdock uninstall <handle>/<slug>");
     }
     const c = colors(ctx.env, ctx.io.isTTY);
+    const json = flags.json === true;
+    const allowPartial = flags["allow-partial"] === true;
     const items = collect(ctx, flags, refArg);
+    const rerun = rerunCommand("uninstall", positionals, flags);
     const removed = [];
-    for (const item of items) {
-        if (item.read.kind === "newer_schema") {
-            throw newerSchemaError(item.dir, item.read.schema, ctx.argsLine);
-        }
-        if (item.read.kind !== "ok") {
-            throw new CliError(`${item.dir} has an unreadable receipt — refusing to guess what to delete (remove the directory manually if you're sure)`, EXIT.INTEGRITY, { footer: "receipt_invalid" });
-        }
-        const receipt = item.read.receipt;
-        // DX5 local-edit guard: human work never dies to a default.
-        const modified = modifiedFiles(item.dir, receipt).filter((p) => existsSync(join(item.dir, p)));
-        if (modified.length > 0 && flags.force !== true) {
-            throw new CliError(`local changes in ${modified.length} file(s) under ${item.dir} (${modified.slice(0, 3).join(", ")}${modified.length > 3 ? ", …" : ""}) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" });
-        }
-        if (flags.yes !== true) {
-            if (!ctx.io.isTTY)
-                throw usageError("confirmation needed in a non-interactive session", "re-run with -y");
-            const go = await confirm(ctx.io, `Uninstall ${receipt.ref} from ${item.dir}?`, false, c);
-            if (!go) {
-                ctx.io.out("Skipped.");
-                continue;
+    const results = [];
+    const failures = [];
+    try {
+        for (const item of items) {
+            // The ref is only knowable from a READABLE receipt; fall back to the directory so
+            // an unreadable one is still named in the report rather than appearing as "".
+            // ⚠️ A DIFFERENT TRUST CLASS from the server strings elsewhere in this change:
+            // `receipt.ref` is read back off `.promptdock.json` on disk, which anyone can
+            // edit, and `readReceipt` type-checks almost nothing. Untrusted all the same.
+            // `item.dir` is a path this CLI computed itself, so it needs nothing.
+            const label = item.read.kind === "ok"
+                ? terminalLine(item.read.receipt.ref, SERVER_LABEL_MAX)
+                : item.dir;
+            try {
+                if (item.read.kind === "newer_schema") {
+                    throw newerSchemaError(item.dir, item.read.schema, rerun);
+                }
+                if (item.read.kind !== "ok") {
+                    throw new CliError(`${item.dir} has an unreadable receipt — refusing to guess what to delete (remove the directory manually if you're sure)`, EXIT.INTEGRITY, { footer: "receipt_invalid" });
+                }
+                const receipt = item.read.receipt;
+                // DX5 local-edit guard: human work never dies to a default.
+                const modified = modifiedFiles(item.dir, receipt).filter((p) => existsSync(join(item.dir, p)));
+                if (modified.length > 0 && flags.force !== true) {
+                    throw new CliError(`local changes in ${modified.length} file(s) under ${item.dir} (${modified.slice(0, 3).join(", ")}${modified.length > 3 ? ", …" : ""}) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" });
+                }
+                if (flags.yes !== true) {
+                    if (!ctx.io.isTTY)
+                        throw usageError("confirmation needed in a non-interactive session", "re-run with -y");
+                    // ⚠️ A CONFIRM PROMPT BECOMES THE PICKER'S TITLE, and ui.ts paints that title
+                    // INSIDE an in-place repaint frame that issues cursor-up and erase-line against
+                    // a counted number of painted rows. Both halves here are untrusted: `ref` is
+                    // read off an on-disk receipt anyone can edit, and `dir` is a readdirSync name.
+                    const go = await confirm(ctx.io, `Uninstall ${terminalLine(receipt.ref, SERVER_LABEL_MAX)} from ${terminalLine(item.dir, SERVER_PATH_MAX)}?`, false, c);
+                    if (!go) {
+                        // A human saying no is the command working, not failing: reported, exit 0.
+                        if (!json)
+                            ctx.io.out("Skipped.");
+                        results.push({ ref: receipt.ref, dir: item.dir, status: "skipped", reason: "declined" });
+                        continue;
+                    }
+                }
+                removeReceiptOwned(item.dir, receipt);
+                removed.push({ ref: receipt.ref, dir: item.dir });
+                results.push({ ref: receipt.ref, dir: item.dir, status: "uninstalled" });
+                if (!json)
+                    ctx.io.out(`${c.green("✓")} Uninstalled ${terminalLine(receipt.ref, SERVER_LABEL_MAX)} (${terminalLine(item.dir, SERVER_PATH_MAX)})`);
+            }
+            catch (err) {
+                if (isFatalForBatch(err)) {
+                    // The batch stops here — no later item could recover either, and an interrupt
+                    // is a verdict on the RUN. The row is still recorded FIRST so the --json
+                    // report names the cause instead of handing the caller an empty `results`.
+                    const fatal = asCliError(err, EXIT.INTEGRITY);
+                    results.push({ ref: label, dir: item.dir, status: "skipped", reason: fatal.message, failed: true, exit: fatal.exitCode });
+                    throw fatal;
+                }
+                const error = asCliError(err, EXIT.INTEGRITY);
+                // NOT a batch: throw exactly as before, so a one-skill uninstall keeps its
+                // message, hint and docs footer instead of being summarised at the end.
+                // Under --json it is recorded and rethrown after the report, so stdout stays
+                // parseable on every path.
+                if (items.length === 1 && !allowPartial && !json)
+                    throw error;
+                failures.push({ ref: label, error });
+                results.push({ ref: label, dir: item.dir, status: "skipped", reason: error.message, failed: true, exit: error.exitCode });
+                if (!json)
+                    ctx.io.err(`${c.yellow("!")} ${label}: ${error.message}`);
             }
         }
-        removeReceiptOwned(item.dir, receipt);
-        removed.push({ ref: receipt.ref, dir: item.dir });
-        if (flags.json !== true)
-            ctx.io.out(`${c.green("✓")} Uninstalled ${receipt.ref} (${item.dir})`);
     }
-    if (flags.json === true)
-        ctx.io.out(JSON.stringify({ uninstalled: removed }));
-    else if (removed.length === 0)
+    finally {
+        // ⚠️ THE ONLY emission, and it has to sit in a `finally`: a fatal-for-batch
+        // error (a non-TTY confirm, a Ctrl-C) escapes the loop, so a post-loop
+        // `if (json)` line is skipped on exactly the paths where a caller most needs
+        // to know what already happened to their working tree. stdout stays parseable
+        // on every path, which is the entire reason a caller asked for JSON.
+        if (json)
+            ctx.io.out(JSON.stringify({ uninstalled: removed, results }));
+    }
+    if (!json && removed.length === 0 && failures.length === 0)
         ctx.io.out("Nothing uninstalled.");
+    const failed = batchExitError(failures, allowPartial, !json);
+    if (failed)
+        throw failed;
 }
 /**
  * Remove ONLY what the receipt lists (+ the receipt), then prune emptied dirs
@@ -143,115 +281,182 @@ function removeReceiptOwned(dir, receipt) {
  *
  * USAGE means the invocation itself is wrong (a confirmation needed in a non-interactive
  * session), so every subsequent item would fail identically. AUTH means the token is gone.
+ * INTERRUPT means the human pressed Ctrl-C: that is a gesture about the RUN, not about
+ * this item — and raw mode swallows SIGINT (it arrives as a keypress, never as a signal),
+ * so this loop is the ONLY thing that can honour it. Without it, `uninstall --all` caught
+ * the interrupt as an ordinary item failure and asked the user to press Ctrl-C once per
+ * remaining skill, then reported the abort as N failures — and under --allow-partial as
+ * exit 0. This is the single gate both commands' catch sites route through, so any prompt
+ * that later moves inside a try inherits the fix.
+ *
  * Everything else — an integrity refusal, an over-fuse package, a network blip on one
  * download — is this item's problem and the next item deserves its turn.
  */
 function isFatalForBatch(err) {
-    return err instanceof CliError && (err.exitCode === EXIT.USAGE || err.exitCode === EXIT.AUTH);
+    return (err instanceof CliError &&
+        (err.exitCode === EXIT.USAGE ||
+            err.exitCode === EXIT.AUTH ||
+            err.exitCode === EXIT.INTERRUPT));
 }
 export async function runUpdate(ctx, positionals, flags) {
     const c = colors(ctx.env, ctx.io.isTTY);
     const checkOnly = flags.check === true;
     const json = flags.json === true;
+    const allowPartial = flags["allow-partial"] === true;
     const items = collect(ctx, flags, positionals[0]);
     if (items.length === 0) {
-        ctx.io.out(json ? JSON.stringify({ updated: [], checked: [] }) : "No promptdock skills installed in this scope.");
+        // ⚠️ THE SAME SHAPE AS EVERY OTHER RUN. This branch used to print
+        // {updated: [], checked: []} — two keys the non-empty branch never emits — so the
+        // one case a CI script hits before anything is installed was the one case its
+        // parser could not read. Neither key was ever populated, so nothing can have
+        // depended on their contents.
+        ctx.io.out(json ? JSON.stringify({ results: [] }) : "No promptdock skills installed in this scope.");
         return;
     }
     const { api } = await ensureAuth(ctx);
+    const rerun = rerunCommand("update", positionals, flags);
     const report = [];
-    for (const item of items) {
-        if (item.read.kind === "newer_schema") {
-            throw newerSchemaError(item.dir, item.read.schema, ctx.argsLine);
-        }
-        if (item.read.kind !== "ok")
-            continue;
-        const receipt = item.read.receipt;
-        let resolved;
-        try {
-            resolved = await api.request("GET", `/api/v1/cli/skills/resolve?ref=${encodeURIComponent(receipt.ref)}`);
-            assertInstallable(resolved, receipt.ref, ctx.version);
-        }
-        catch (err) {
-            const reason = err instanceof CliError ? err.message : String(err);
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: null, status: "skipped", reason });
-            if (!json)
-                ctx.io.out(`${c.yellow("!")} ${receipt.ref}: ${reason}`);
-            continue;
-        }
-        if (resolved.version_id === receipt.version_id) {
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: receipt.version, status: "up_to_date" });
-            if (!json)
-                ctx.io.out(`${c.dim("·")} ${receipt.ref} is up to date (v${receipt.version})`);
-            continue;
-        }
-        const toVersion = Number(resolved.version) || 0;
-        if (checkOnly) {
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "available" });
-            if (!json)
-                ctx.io.out(`${c.cyan("↑")} ${receipt.ref}: v${receipt.version} → v${toVersion} available`);
-            continue;
-        }
-        // DX5 local-edit guard BEFORE any overwrite.
-        const modified = modifiedFiles(item.dir, receipt);
-        if (modified.length > 0 && flags.force !== true) {
-            const reason = `local changes in ${modified.length} file(s) — --force to overwrite`;
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason });
-            if (!json)
-                ctx.io.out(`${c.yellow("!")} ${receipt.ref}: ${reason}`);
-            continue;
-        }
-        if (flags.yes !== true) {
-            if (!ctx.io.isTTY)
-                throw usageError("confirmation needed in a non-interactive session", "re-run with -y (or use --check)");
-            const go = await confirm(ctx.io, `Update ${receipt.ref} v${receipt.version} → v${toVersion}?`, true, c);
-            if (!go) {
-                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason: "declined" });
+    const failures = [];
+    /**
+     * Record a fatal-for-batch error and hand it back to be thrown.
+     *
+     * The batch stops here — no later item could recover either — but the row is
+     * recorded FIRST so the --json report names the cause instead of handing the caller
+     * an empty `results` after items 1..N-1 have already rewritten their directories.
+     * Returned rather than thrown so the direct `throw` at the non-TTY confirm below
+     * (which is outside `fail()` and outside every try) reuses the exact same path.
+     */
+    const recordFatal = (ref, dir, from, to, err) => {
+        const fatal = asCliError(err, EXIT.AUTH);
+        report.push({ ref, dir, from, to, status: "skipped", reason: fatal.message, failed: true, exit: fatal.exitCode });
+        return fatal;
+    };
+    /** Record a per-item failure; rethrow when this is not a batch at all. */
+    const fail = (ref, dir, from, to, err) => {
+        if (isFatalForBatch(err))
+            throw recordFatal(ref, dir, from, to, err);
+        const error = asCliError(err, EXIT.DENIED);
+        // NOT a batch: throw straight away so a one-skill update keeps the message, hint
+        // and docs footer it has always had. Under --json it is recorded instead and
+        // rethrown after the report — stdout must stay parseable on every path, which is
+        // the entire reason a caller asked for JSON.
+        if (items.length === 1 && !allowPartial && !json)
+            throw error;
+        failures.push({ ref, error });
+        report.push({ ref, dir, from, to, status: "skipped", reason: error.message, failed: true, exit: error.exitCode });
+        if (!json)
+            ctx.io.err(`${c.yellow("!")} ${ref}: ${error.message}`);
+    };
+    try {
+        for (const item of items) {
+            if (item.read.kind !== "ok") {
+                // Previously: `throw` on a newer schema (killing the batch) and a SILENT
+                // `continue` on an unreadable one. Both are now this item's failure — an
+                // update that could not read its own receipt updated nothing.
+                const err = item.read.kind === "newer_schema"
+                    ? newerSchemaError(item.dir, item.read.schema, rerun)
+                    : new CliError(`${item.dir} has an unreadable receipt — reinstall the skill to repair it`, EXIT.INTEGRITY, { footer: "receipt_invalid" });
+                fail(item.dir, item.dir, 0, null, err);
                 continue;
             }
+            const receipt = item.read.receipt;
+            let resolved;
+            try {
+                resolved = await api.request("GET", `/api/v1/cli/skills/resolve?ref=${encodeURIComponent(receipt.ref)}`);
+                assertInstallable(resolved, receipt.ref, ctx.version);
+            }
+            catch (err) {
+                fail(receipt.ref, item.dir, receipt.version, null, err);
+                continue;
+            }
+            if (resolved.version_id === receipt.version_id) {
+                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: receipt.version, status: "up_to_date" });
+                if (!json)
+                    ctx.io.out(`${c.dim("·")} ${receipt.ref} is up to date (v${receipt.version})`);
+                continue;
+            }
+            const toVersion = Number(resolved.version) || 0;
+            if (checkOnly) {
+                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "available" });
+                if (!json)
+                    ctx.io.out(`${c.cyan("↑")} ${receipt.ref}: v${receipt.version} → v${toVersion} available`);
+                continue;
+            }
+            // DX5 local-edit guard BEFORE any overwrite. A block is a FAILURE, not a
+            // shrug: the skill stays behind and someone has to decide what to do about it.
+            const modified = modifiedFiles(item.dir, receipt);
+            if (modified.length > 0 && flags.force !== true) {
+                fail(receipt.ref, item.dir, receipt.version, toVersion, new CliError(`local changes in ${modified.length} file(s) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" }));
+                continue;
+            }
+            if (flags.yes !== true) {
+                if (!ctx.io.isTTY) {
+                    throw recordFatal(receipt.ref, item.dir, receipt.version, toVersion, usageError("confirmation needed in a non-interactive session", "re-run with -y (or use --check)"));
+                }
+                const go = await confirm(ctx.io, 
+                // Same picker-frame sink as the uninstall confirm above.
+                `Update ${terminalLine(receipt.ref, SERVER_LABEL_MAX)} v${terminalLine(String(receipt.version), SERVER_LABEL_MAX)} → v${terminalLine(String(toVersion), SERVER_LABEL_MAX)}?`, true, c);
+                if (!go) {
+                    report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason: "declined" });
+                    continue;
+                }
+            }
+            if (typeof resolved.skill_id !== "string" || typeof resolved.version_id !== "string") {
+                // A 200 that cannot be acted on. Silently continuing here is how "updated
+                // nothing, exited 0" used to look from the outside.
+                fail(receipt.ref, item.dir, receipt.version, toVersion, new CliError("malformed resolve response — update the CLI and retry", EXIT.DENIED, {
+                    footer: "verdict",
+                }));
+                continue;
+            }
+            /**
+             * ⚠️ THE INSTALL MUST BE INSIDE THE PER-ITEM CATCH TOO, or "one bad package skips and
+             * the rest continue" is false for the population that matters.
+             *
+             * The catch above wraps only resolve + `assertInstallable` — and `assertInstallable`
+             * is exactly what OLDER CLIs do not have. On those, the only thing that refuses an
+             * over-fuse package is `assertSafeManifest`, deep inside `performInstall`, i.e. out
+             * here beyond the guard. So the CliError propagated out of the loop and killed the
+             * whole run: one oversized skill in a directory of twenty aborted the other nineteen.
+             * That is the population the package-scoped `min_cli_version` design exists to serve,
+             * so the guarantee was false precisely where it was load-bearing.
+             *
+             * Genuinely fatal classes still propagate — a usage error or a newer-schema receipt
+             * is not something the next item can recover from either.
+             */
+            try {
+                const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolved.skill_id}/install`, { version_id: resolved.version_id });
+                const resp = checkInstallResponse(respRaw);
+                await performInstall(ctx, api, {
+                    resp,
+                    targetDir: item.dir,
+                    targetId: item.targetId,
+                    refString: receipt.ref,
+                    prior: receipt,
+                });
+                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: resp.skill.version, status: "updated" });
+                if (!json)
+                    ctx.io.out(`${c.green("✓")} ${receipt.ref}: v${receipt.version} → v${resp.skill.version}`);
+            }
+            catch (err) {
+                fail(receipt.ref, item.dir, receipt.version, toVersion, err);
+            }
         }
-        if (typeof resolved.skill_id !== "string" || typeof resolved.version_id !== "string")
-            continue;
-        /**
-         * ⚠️ THE INSTALL MUST BE INSIDE THE PER-ITEM CATCH TOO, or "one bad package skips and
-         * the rest continue" is false for the population that matters.
-         *
-         * The catch above wraps only resolve + `assertInstallable` — and `assertInstallable`
-         * is exactly what OLDER CLIs do not have. On those, the only thing that refuses an
-         * over-fuse package is `assertSafeManifest`, deep inside `performInstall`, i.e. out
-         * here beyond the guard. So the CliError propagated out of the loop and killed the
-         * whole run: one oversized skill in a directory of twenty aborted the other nineteen.
-         * That is the population the package-scoped `min_cli_version` design exists to serve,
-         * so the guarantee was false precisely where it was load-bearing.
-         *
-         * Genuinely fatal classes still propagate — a usage error or a newer-schema receipt
-         * is not something the next item can recover from either.
-         */
-        try {
-            const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolved.skill_id}/install`, { version_id: resolved.version_id });
-            const resp = checkInstallResponse(respRaw);
-            await performInstall(ctx, api, {
-                resp,
-                targetDir: item.dir,
-                targetId: item.targetId,
-                refString: receipt.ref,
-                prior: receipt,
-            });
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: resp.skill.version, status: "updated" });
-            if (!json)
-                ctx.io.out(`${c.green("✓")} ${receipt.ref}: v${receipt.version} → v${resp.skill.version}`);
-        }
-        catch (err) {
-            if (isFatalForBatch(err))
-                throw err;
-            const reason = err instanceof CliError ? err.message : String(err);
-            report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "skipped", reason });
-            if (!json)
-                ctx.io.out(`${c.yellow("!")} ${receipt.ref}: ${reason}`);
-        }
     }
-    if (json)
-        ctx.io.out(JSON.stringify({ results: report }));
+    finally {
+        // ⚠️ THE ONLY emission, and it has to sit in a `finally`: a fatal-for-batch
+        // error escapes the loop (a revoked token 401ing on item N, the non-TTY
+        // confirm above), so a post-loop `if (json)` line is skipped on exactly the
+        // paths where a caller most needs the report — items 1..N-1 have already
+        // rewritten their directories. An empty stdout tells a pipeline nothing.
+        if (json)
+            ctx.io.out(JSON.stringify({ results: report }));
+    }
+    // Last, so the report is always printed first: a failing exit must never cost the
+    // caller the list of what DID succeed.
+    const failed = batchExitError(failures, allowPartial, !json);
+    if (failed)
+        throw failed;
 }
 /* ── list ───────────────────────────────────────────────────────────────────── */
 export async function runList(ctx, flags) {
@@ -284,10 +489,14 @@ export async function runList(ctx, flags) {
         if (i.read.kind === "ok") {
             const r = i.read.receipt;
             const when = typeof r.installed_at === "string" ? r.installed_at.slice(0, 10) : "?";
-            ctx.io.out(`${r.ref}  v${r.version}  ${i.targetId} (${i.scope})  ${when}  ${i.dir}`);
+            // The two-space gaps are column separators, so the FRAGMENTS are sanitized and
+            // the composed line is not — `terminalLine` would collapse them to one space.
+            const ref = terminalLine(r.ref, SERVER_LABEL_MAX);
+            const version = terminalLine(String(r.version), SERVER_LABEL_MAX);
+            ctx.io.out(`${ref}  v${version}  ${i.targetId} (${i.scope})  ${terminalLine(when, SERVER_LABEL_MAX)}  ${terminalLine(i.dir, SERVER_PATH_MAX)}`);
         }
         else {
-            ctx.io.out(`?  ${i.dir}  (${i.read.kind === "newer_schema" ? "newer receipt schema — run npx promptdock@latest" : "unreadable receipt"})`);
+            ctx.io.out(`?  ${terminalLine(i.dir, SERVER_PATH_MAX)}  (${i.read.kind === "newer_schema" ? "newer receipt schema — run npx promptdock@latest" : "unreadable receipt"})`);
         }
     }
 }

package/dist/commands/login.js

@@ -3,6 +3,7 @@
 // no keyboard — CI users should prefer PROMPTDOCK_TOKEN, but an explicit
 // invocation shouldn't refuse); the browser only auto-opens on a TTY.
 import { Api } from "../api.js";
+import { SERVER_LABEL_MAX, terminalLine } from "../terminal-text.js";
 import { deviceFlowLogin } from "../auth.js";
 import { loadConfig, resolveApiBase, saveConfig } from "../config.js";
 import { usageError } from "../errors.js";
@@ -25,8 +26,11 @@ export async function runLogin(ctx, flags) {
     const api = new Api(ctx, baseUrl, token);
     const who = await api.request("GET", "/api/v1/cli/whoami");
     saveConfig(ctx.home, { ...config, token, api_base: baseUrl }, ctx.platform);
-    const name = who.handle ? `@${who.handle}` : "your account";
-    ctx.io.out(`${c.green("✓")} Logged in as ${name}${who.role ? ` (${who.role})` : ""}.`);
+    // Server-chosen strings on the line a user trusts most — the one that says the
+    // login worked. Sanitized for display; the stored token is unaffected.
+    const name = who.handle ? `@${terminalLine(who.handle, SERVER_LABEL_MAX)}` : "your account";
+    const role = terminalLine(who.role, SERVER_LABEL_MAX);
+    ctx.io.out(`${c.green("✓")} Logged in as ${name}${role ? ` (${role})` : ""}.`);
     if (ctx.env.PROMPTDOCK_TOKEN) {
         ctx.io.out(c.dim("note: PROMPTDOCK_TOKEN is set and overrides the stored login."));
     }
@@ -81,7 +85,7 @@ export async function runWhoami(ctx, flags) {
         ctx.io.out(JSON.stringify(who));
         return;
     }
-    const name = who.handle ? `@${who.handle}` : "(no handle)";
+    const name = who.handle ? `@${terminalLine(who.handle, SERVER_LABEL_MAX)}` : "(no handle)";
     const expiry = who.expires_at ? new Date(who.expires_at).toISOString().slice(0, 10) : "unknown";
-    ctx.io.out(`Signed in as ${name} · role: ${who.role} · token expires: ${expiry}`);
+    ctx.io.out(`Signed in as ${name} · role: ${terminalLine(who.role, SERVER_LABEL_MAX)} · token expires: ${expiry}`);
 }

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-export declare const DEFAULT_API_BASE = "https://www.promptdock.ai";
+export declare const DEFAULT_API_BASE: string;
 export type CliConfig = {
     token?: string;
     api_base?: string;

package/dist/config.js

@@ -5,15 +5,21 @@
 import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { CliError, EXIT } from "./errors.js";
+import { CANONICAL_ORIGIN } from "./generated/constants.js";
 // ⚠️ MUST be the host the API is actually SERVED on, not the brand apex.
 // `promptdock.ai` 301-redirects to `www.promptdock.ai`, and Node's fetch follows
 // that redirect ACROSS AN ORIGIN — which per the fetch spec (a) downgrades POST to
 // GET and drops the body, and (b) STRIPS the `Authorization` header. Both, at any
 // status code: a 308 preserves the method and still scrubs the bearer. So pointing
 // this at the apex breaks every call — login POSTs answered with 405, and every
-// authenticated GET arriving anonymous and answered 401. Keep this in lockstep with
-// SITE_URL in lib/site-url.ts; `base-url.test.ts` fails the build if they diverge.
-export const DEFAULT_API_BASE = "https://www.promptdock.ai";
+// authenticated GET arriving anonymous and answered 401.
+//
+// ⚠️ DERIVED from `CANONICAL_ORIGIN` in the shared `skills-constants.json`, which
+// `lib/site-url.ts` SITE_URL reads too — so the CLI and the app can no longer disagree
+// about which host the product is served on. Until 2026-09-19 this was one of ~15
+// independent literals and three of them had already drifted to the apex.
+// `base-url.test.ts` pins both ends across the build boundary.
+export const DEFAULT_API_BASE = CANONICAL_ORIGIN;
 /**
  * Origins a PREVIOUS release persisted into ~/.promptdock/config.json and which are
  * known-broken. A successful login writes `api_base`, and a stored value outranks

package/dist/context.d.ts

@@ -59,6 +59,29 @@ export type CliContext = {
 };
 /** Read the package's own version (dist/ and src/ both sit one level under the root). */
 export declare function readOwnVersion(): string;
-/** Best-effort platform browser open (darwin `open`, win32 `start`, else xdg-open). */
+/**
+ * The ONLY shape allowed to reach a platform opener, or null to refuse.
+ *
+ * ⚠️ THE URL IS UNTRUSTED. `verification_url` comes from the UNAUTHENTICATED
+ * `/api/v1/cli/auth/start` response through `Api.request`, which is `res.body as T` — a
+ * bare cast, as contract.ts says in its own header. The OS opener is a far more
+ * dangerous sink than the terminal: it is the one path in this CLI with an effect
+ * outside the process.
+ *
+ * Measured on darwin: `open` treats a non-URL argument as a FILE PATH (so a value like
+ * `/Applications/Calculator.app` launches it), reads a leading `-` as a FLAG, and
+ * dispatches any scheme to its registered handler — which is how `file:`, `smb:` and
+ * `ms-msdt:` become interesting.
+ */
+export declare function openableUrl(raw: string): string | null;
+/**
+ * The `[command, args]` a platform open would spawn, or null when it is refused.
+ *
+ * Split out from the spawn PURELY so the decision is testable: the whole matrix can be
+ * asserted with no child process, on any host OS. There was no test referencing
+ * `openUrlBestEffort` at all, which is how the win32 defect below survived.
+ */
+export declare function openUrlCommand(url: string, platform: NodeJS.Platform): [string, string[]] | null;
+/** Best-effort platform browser open (darwin `open`, win32 `explorer`, else xdg-open). */
 export declare function openUrlBestEffort(url: string, platform: NodeJS.Platform): void;
 export declare function realContext(argv: string[]): CliContext;