promptdock 1.2.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # promptdock
 
-Install AI agent **skills** from [PromptDock](https://promptdock.ai) into Claude Code,
+Install AI agent **skills** from [PromptDock](https://www.promptdock.ai) into Claude Code,
 Codex, Gemini CLI, Cursor, GitHub Copilot, and more.
 
 ```bash
@@ -9,13 +9,21 @@ npx promptdock@latest install <handle>/<slug>
 
 ## 60-second quickstart
 
+Replace `<handle>/<slug>` with a real skill's ref — every skill page on
+[promptdock.ai/skills](https://www.promptdock.ai/skills) shows its own install command,
+ready to copy.
+
 ```bash
 # 1) Install a skill into this project (the CLI walks you through login + target)
-npx promptdock@latest install garry/seo-content-audit
+npx promptdock@latest install <handle>/<slug>
 
 # 2) Approve the login code in your browser when prompted (one time per machine)
+#    No account yet? The page it opens has a sign-up link: create the account,
+#    confirm the email it sends, then approve. The code lasts 15 minutes for
+#    exactly this, the terminal waits, and if it does run out the CLI issues a
+#    fresh one once.
 
-# 3) Start a NEW session in Claude Code and type /seo-content-audit
+# 3) Start a NEW session in Claude Code and type /<slug>
 ```
 
 **Auth model, stated plainly: login is required.** A free PromptDock account
@@ -29,8 +37,8 @@ profile's ACL is the boundary).
 
 | Command | What it does |
 | --- | --- |
-| `login [--token pdk_…]` | Browser hand-off login, or store a CI token from Settings → CLI sessions |
-| `logout` | Remove the local token (revoke in Settings to kill the session server-side) |
+| `login [--token pdk_…]` | Browser hand-off login, or store a CI token from Settings → Account → CLI sessions |
+| `logout` | Revoke the session server-side, then remove the local token |
 | `whoami [--json]` | Show the signed-in account + token expiry |
 | `install <ref> [options]` | Install a skill (`ref` = `handle/slug`, `@handle/slug`, or a pasted URL) |
 | `uninstall <ref \| --all>` | Remove an installed skill (receipt-driven — see below) |
@@ -41,6 +49,16 @@ Install options: `-g/--global` (per-user dir), `--target <tool>`, `--dir <path>`
 `-y/--yes` (skip prompts — **never** implies `--force`), `--force`, `--dry-run`
 (print the plan, install nothing), `--json`.
 
+Update/uninstall options: `--check` (update only — report, apply nothing), `--all`,
+`-g/--global`, `--force`, `--allow-partial` (see
+[batch exit codes](#batch-exit-codes)), `--json`.
+
+`logout` calls the server first: the token this machine holds stops working
+immediately, and only then is the local copy deleted. If that call cannot get
+through (offline), the local token is still removed and the CLI warns you on
+stderr — that session stays valid until it expires, so revoke it under
+**Settings → Account → CLI sessions**.
+
 ## Install targets
 
 | Target | Project install | Global (`-g`) | Status |
@@ -83,7 +101,7 @@ Non-TTY sessions never open a browser or show a picker. The contract:
 
 ```bash
 export PROMPTDOCK_TOKEN=pdk_…       # Settings → Account → CLI sessions → Generate token
-npx promptdock@latest install garry/seo-content-audit --target claude -y
+npx promptdock@latest install <handle>/<slug> --target claude -y
 ```
 
 - `PROMPTDOCK_TOKEN` — bearer token (overrides any stored login).
@@ -94,6 +112,71 @@ npx promptdock@latest install garry/seo-content-audit --target claude -y
 - Without `--target`/`--dir` **and** `-y`, a non-interactive install exits `1`
   with the exact flags to add. Without a token it exits `2`.
 - `NO_COLOR` is honored.
+- Installs are **latest-only** — there is no version pinning. A build that must be
+  byte-reproducible should vendor the installed files, not re-resolve them.
+- Node's built-in `fetch` does **not** read `HTTPS_PROXY`/`HTTP_PROXY` by itself.
+  Recent Node versions opt in with `NODE_USE_ENV_PROXY=1`; if yours does not
+  support it, the CLI cannot use your proxy. When a request fails it names the
+  proxy variable it found, so the cause is not a mystery.
+
+### Batch exit codes
+
+`update` and `uninstall` can act on several skills at once (`--all`, or a scope
+holding more than one). One bad item no longer aborts the rest — the others are
+still processed — and the command then **exits with that item's code**:
+
+```bash
+npx promptdock@latest update --all -y          # exits 4 if one skill has local edits
+npx promptdock@latest update --all -y --allow-partial   # same report, exits 0
+```
+
+What counts as a failure: unreachable server, a tier/cap refusal, a package this
+CLI is too old for, an unreadable receipt, or local edits blocking an overwrite.
+What does **not**: a skill already up to date, an available update under
+`--check`, or a human answering "no" to a confirm.
+
+⚠️ Before 1.2.1 every one of those was reported as `skipped` and the command
+exited `0`, so a CI step could go green having updated nothing.
+
+### `--json` output
+
+Every shape below is printed to **stdout** as a single line; human progress text
+and warnings go to stderr. Log in first — an interactive login hand-off prints to
+stdout, so in CI set `PROMPTDOCK_TOKEN` and pass `-y`, which also stops the
+confirms from painting a picker over your JSON.
+
+| Command | Shape |
+| --- | --- |
+| `whoami --json` | `{ handle, role, expires_at }` |
+| `list --json` | `[{ dir, target, scope, ref, version, version_id, installed_at, schema }]` — an unreadable receipt yields `{ dir, target, scope, receipt: "newer_schema" \| "invalid" }` instead |
+| `install --json` | `{ installed: true, update, ref, version, version_id, target, path, files }` |
+| `install --json` (nothing to do) | `{ installed: false, up_to_date: true, update: true, ref, version, version_id, target, path }` |
+| `install --dry-run --json` | `{ dry_run: true, ref, skill_id, version_id, version, title, author, is_free, file_count, total_bytes, target, path, update }` |
+| `update --json` | `{ results: [ … ] }` — always, including when nothing is installed (`{ results: [] }`) |
+| `uninstall --json` | `{ uninstalled: [{ ref, dir }], results: [ … ] }` |
+
+A `results` row is `{ ref, dir, status, reason?, failed?, exit?, from?, to? }`:
+
+- `status` — `updated` · `up_to_date` · `available` (`--check`) · `uninstalled` ·
+  `skipped` (declined, or failed).
+- `failed` — present and `true` **only** for a real failure. This is the field to
+  branch on; `status` keeps the vocabulary 1.2.0 shipped.
+- `exit` — that failure's own exit code. The process exits with the first one.
+- `from`/`to` — version numbers, on `update` rows only.
+
+A **failure** that produced no report of its own is written to stdout as one document:
+
+```json
+{ "error": { "code": "existing_dir", "message": "…", "exit_code": 5, "doc_url": "https://www.promptdock.ai/docs/cli/errors#existing_dir" } }
+```
+
+`code` is the docs anchor (`"error"` when the failure has none, and `doc_url` then
+points at the index). `update`/`uninstall` do **not** add this — their `results` report
+already answers the same question per item — so stdout is always exactly one JSON
+value, on every path.
+
+New keys may be added in a patch release; existing keys and `status` values will
+not change meaning.
 
 ## Receipts, update, uninstall
 
@@ -108,8 +191,9 @@ skill id, ref, version, and the sha256 of every installed file. It is the
   any emptied directories. Files you added are never touched.
 - If you **edited** installed files, update/uninstall refuse without `--force`
   ("copy your changes out first") — your local changes never die to a default.
-- A receipt written by a newer CLI version is left alone with a
-  "run `npx promptdock@latest`" notice — never a guessy uninstall.
+- A receipt written by a newer CLI version is left alone with a notice naming
+  the exact `npx promptdock@latest …` command to re-run — never a guessy
+  uninstall. It counts as a failed item (see [batch exit codes](#batch-exit-codes)).
 
 Downloads are verified against the server manifest (per-file sha256) and every
 path is re-validated before any write; a failed check aborts **all-or-nothing**
@@ -128,9 +212,19 @@ path is re-validated before any write; a failed check aborts **all-or-nothing**
 | 6 | network |
 | 130 | interrupted (`Ctrl-C` during an interactive prompt; `Esc` — a deliberate in-UI cancel — exits 1) |
 
-Every named error links `https://promptdock.ai/docs/cli/errors#<code>`. That page
+Every named error links `https://www.promptdock.ai/docs/cli/errors#<code>`. That page
 lists every code with what happened, why, and what to do.
 
+## Getting help
+
+- **A named error, an exit code:** [promptdock.ai/docs/cli/errors](https://www.promptdock.ai/docs/cli/errors) —
+  every code, with what happened and what to do. The link the CLI prints goes straight
+  to the entry.
+- **Anything else:** [promptdock.ai/contact](https://www.promptdock.ai/contact) names the
+  right mailbox for the question (account, billing, the CLI). Include the command you
+  ran, `promptdock --version`, and the error text.
+- `npm bugs promptdock` opens the errors page from your terminal.
+
 ## Package compatibility
 
 This CLI carries its own **install-safety limits** — how many files it will write and how
@@ -143,12 +237,16 @@ When that happens you get, for **that skill only**:
 
 ```
 "Big Skill" needs promptdock CLI 1.2.0 or newer — you are on 1.0.1.
-  Update: npx promptdock@latest install …
+  Update: npx promptdock@latest install <handle>/<slug>  (or: npm i -g promptdock@latest)
 ```
 
+(the real message names the skill you asked for, so the second line is a command
+you can paste as-is)
+
 It exits `3` (denied), not `4` (integrity) — the package is fine, your CLI is just older
-than it. Your login, your other installs and `promptdock update` are unaffected;
-`promptdock update` skips that one skill and continues with the rest.
+than it. Your login and your other installs are unaffected: `promptdock update`
+updates everything else and then exits `3` for the one it could not do (see
+[batch exit codes](#batch-exit-codes)).
 
 ## Notes
 
@@ -169,5 +267,5 @@ website, or the rest of the repository, which are proprietary.
 
 It also does not cover **the skills you install**. Those are third-party content
 licensed by their authors under the
-[PromptDock Terms](https://promptdock.ai/terms) — installing a skill grants you
+[PromptDock Terms](https://www.promptdock.ai/terms) — installing a skill grants you
 access to use it, not the rights this MIT license grants over the CLI itself.

package/dist/api.d.ts

@@ -9,6 +9,29 @@ export type RawResponse = {
     body: unknown;
     headers: Headers;
 };
+/**
+ * The server ErrorCodes that have their OWN anchor on /docs/cli/errors.
+ *
+ * `env.code` is a string lifted off an untrusted response body, and it used to become
+ * the docs anchor verbatim (`footer: env?.code ?? "api"`). Anything a proxy, a captive
+ * portal, a future server or a plain typo put there therefore became
+ * `…/docs/cli/errors#whatever` — a link printed to a stuck user that scrolls nowhere.
+ * The fallbacks are the point of the `??`, and they were unreachable for every string
+ * that was not literally absent.
+ *
+ * ⚠️ TWO CODES ARE DELIBERATELY ABSENT FROM THE APP'S VOCABULARY HERE, and it is not
+ * an oversight: `unauthenticated` / `invalid_token` are ALIASED to the `auth` entry in
+ * lib/cli/error-docs.ts, and `idempotency_key_required` is
+ * aliased to `api`. An alias has no anchor of its own, so passing one through would
+ * mint exactly the dead link this list exists to prevent — they fall back instead,
+ * which is where their doc entries already say they belong.
+ *
+ * ⚠️ COUPLING (guarded by test/footer-codes.test.ts, which reads both files as text):
+ * every entry must be an app ErrorCode (lib/errors.ts) AND carry its own `slug` in
+ * lib/cli/error-docs.ts. The CLI cannot import either — packages/cli ships to npm on
+ * its own — so a test is the only seam that can hold the two vocabularies together.
+ */
+export declare const DOCUMENTED_SERVER_CODES: ReadonlySet<string>;
 export declare class Api {
     private readonly ctx;
     readonly baseUrl: string;
@@ -19,7 +42,27 @@ export declare class Api {
     raw(method: string, path: string, body?: unknown): Promise<RawResponse>;
     /** Envelope-aware request: 2xx → typed body; anything else → a mapped CliError. */
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
-    /** Extract {error:{code,message,details}} defensively (untrusted input). */
+    /**
+     * Extract {error:{code,message,details}} defensively (untrusted input).
+     *
+     * ⚠️ THIS IS THE TRUST BOUNDARY, and `message` is sanitized HERE rather than at the
+     * five sites that print it. Every one of those sites reads this function's output —
+     * and so does auth.ts's device-flow poll, which builds its own CliError and never
+     * touches `mapEnvelopeError` at all. Sanitizing per call site would have covered
+     * five of six and left the sixth to be found later, which is exactly how the
+     * original gap (one covered site, five raw) came about.
+     *
+     * ⚠️ `details` is deliberately NOT sanitized: it is an opaque bag whose values are
+     * read for meaning, not just printed (`min_version`, `retry_after_secs`), and
+     * blanket-sanitizing a `Record<string, unknown>` would coerce non-strings. Every
+     * read site that PRINTS a details value owes it a `terminalLine` — see the 426
+     * remedy in `mapEnvelopeError`, the only such site today.
+     *
+     * ⚠️ `code` is not sanitized either, because it never reaches the terminal on its
+     * own: `documentedFooter` gates it against a frozen 12-slug allowlist before it can
+     * become a docs anchor. The allowlist is what makes that safe, so do not relax it
+     * into a passthrough.
+     */
     static envelope(body: unknown): ApiEnvelopeError | null;
     private mapEnvelopeError;
 }

package/dist/api.js

@@ -1,5 +1,6 @@
 import { DEFAULT_API_BASE } from "./config.js";
 import { CliError, EXIT, networkError } from "./errors.js";
+import { LOCATION_MAX, SERVER_MESSAGE_MAX, SERVER_REMEDY_MAX, terminalLine, } from "./terminal-text.js";
 /**
  * The redirect target may only become an ACTIONABLE hint when it is trustworthy
  * (review CRITICAL): a 3xx can come from a captive portal, hijacked DNS, or a
@@ -25,17 +26,56 @@ function trustedRedirectOrigin(location, baseUrl) {
         return null; // relative/unparseable Location — never actionable
     }
 }
-/** Strip control chars (incl. ESC) before a server-supplied string reaches the
- *  terminal — a Location carrying ANSI sequences could rewrite what the user
- *  sees (review find). */
-function sanitizeForTerminal(s) {
-    let out = "";
-    for (const ch of s) {
-        const c = ch.codePointAt(0) ?? 0;
-        if (c >= 0x20 && c !== 0x7f && !(c >= 0x80 && c <= 0x9f))
-            out += ch;
-    }
-    return out.slice(0, 200);
+/**
+ * The server ErrorCodes that have their OWN anchor on /docs/cli/errors.
+ *
+ * `env.code` is a string lifted off an untrusted response body, and it used to become
+ * the docs anchor verbatim (`footer: env?.code ?? "api"`). Anything a proxy, a captive
+ * portal, a future server or a plain typo put there therefore became
+ * `…/docs/cli/errors#whatever` — a link printed to a stuck user that scrolls nowhere.
+ * The fallbacks are the point of the `??`, and they were unreachable for every string
+ * that was not literally absent.
+ *
+ * ⚠️ TWO CODES ARE DELIBERATELY ABSENT FROM THE APP'S VOCABULARY HERE, and it is not
+ * an oversight: `unauthenticated` / `invalid_token` are ALIASED to the `auth` entry in
+ * lib/cli/error-docs.ts, and `idempotency_key_required` is
+ * aliased to `api`. An alias has no anchor of its own, so passing one through would
+ * mint exactly the dead link this list exists to prevent — they fall back instead,
+ * which is where their doc entries already say they belong.
+ *
+ * ⚠️ COUPLING (guarded by test/footer-codes.test.ts, which reads both files as text):
+ * every entry must be an app ErrorCode (lib/errors.ts) AND carry its own `slug` in
+ * lib/cli/error-docs.ts. The CLI cannot import either — packages/cli ships to npm on
+ * its own — so a test is the only seam that can hold the two vocabularies together.
+ */
+export const DOCUMENTED_SERVER_CODES = new Set([
+    // Web-only today: no /api/v1/cli route carries `refuseWhenClosing`, because installing a
+    // skill takes on no obligation to settle. Passed through anyway — the day one does, the
+    // entry is already reachable, and a code that cannot arrive costs nothing here
+    // (`documentedFooter` only ever maps a code a response actually carried).
+    "account_closing",
+    "account_disabled",
+    // Reachable from EVERY cli-token route: the spine refuses a suspended account before the
+    // handler runs and no /cli route is `allowDisabled`, so this is the one a stuck user hits
+    // on `whoami` as readily as on `install`.
+    "account_suspended",
+    "conflict",
+    "insufficient_tier",
+    "internal",
+    "mfa_required",
+    "not_found",
+    "not_owner",
+    "rate_limited",
+    // Web-only today (payout re-authentication); passed through so the entry is reachable if it ever arrives.
+    "reauth_required",
+    "service_unavailable",
+    "upgrade_required",
+    "validation_error",
+    "version_conflict",
+]);
+/** The server's code as a docs anchor, or undefined so the caller's fallback wins. */
+function documentedFooter(code) {
+    return code !== undefined && DOCUMENTED_SERVER_CODES.has(code) ? code : undefined;
 }
 export class Api {
     ctx;
@@ -82,7 +122,7 @@ export class Api {
         // ctx.fetch directly and must keep following them — storage hands out redirects.
         if (res.status >= 300 && res.status < 400) {
             const to = res.headers.get("location") ?? "(no location header)";
-            throw new CliError(`${this.baseUrl} redirected to ${sanitizeForTerminal(to)} — the API must be called on its canonical origin, because a redirect drops the request body and the login token.`, EXIT.NETWORK, {
+            throw new CliError(`${this.baseUrl} redirected to ${terminalLine(to, LOCATION_MAX)} — the API must be called on its canonical origin, because a redirect drops the request body and the login token.`, EXIT.NETWORK, {
                 // An UNTRUSTED target (cross-domain / non-https — a captive portal or
                 // MITM can mint a 3xx) gets the STATIC known-good hint, never its own
                 // origin echoed back as an instruction. DEFAULT_API_BASE is imported,
@@ -108,7 +148,27 @@ export class Api {
             return res.body;
         throw this.mapEnvelopeError(res);
     }
-    /** Extract {error:{code,message,details}} defensively (untrusted input). */
+    /**
+     * Extract {error:{code,message,details}} defensively (untrusted input).
+     *
+     * ⚠️ THIS IS THE TRUST BOUNDARY, and `message` is sanitized HERE rather than at the
+     * five sites that print it. Every one of those sites reads this function's output —
+     * and so does auth.ts's device-flow poll, which builds its own CliError and never
+     * touches `mapEnvelopeError` at all. Sanitizing per call site would have covered
+     * five of six and left the sixth to be found later, which is exactly how the
+     * original gap (one covered site, five raw) came about.
+     *
+     * ⚠️ `details` is deliberately NOT sanitized: it is an opaque bag whose values are
+     * read for meaning, not just printed (`min_version`, `retry_after_secs`), and
+     * blanket-sanitizing a `Record<string, unknown>` would coerce non-strings. Every
+     * read site that PRINTS a details value owes it a `terminalLine` — see the 426
+     * remedy in `mapEnvelopeError`, the only such site today.
+     *
+     * ⚠️ `code` is not sanitized either, because it never reaches the terminal on its
+     * own: `documentedFooter` gates it against a frozen 12-slug allowlist before it can
+     * become a docs anchor. The allowlist is what makes that safe, so do not relax it
+     * into a passthrough.
+     */
     static envelope(body) {
         if (typeof body !== "object" || body === null)
             return null;
@@ -118,9 +178,14 @@ export class Api {
         const e = err;
         if (typeof e.code !== "string")
             return null;
+        // An all-control message sanitizes to "", which would print a blank line where a
+        // reason belongs — so fall back to the code, and note that every call site below
+        // uses `||` (not `??`) so an empty result still reaches the CLI's own sentence.
+        const raw = typeof e.message === "string" ? e.message : e.code;
+        const message = terminalLine(raw, SERVER_MESSAGE_MAX) || terminalLine(e.code, SERVER_MESSAGE_MAX);
         return {
             code: e.code,
-            message: typeof e.message === "string" ? e.message : e.code,
+            message,
             details: typeof e.details === "object" && e.details !== null
                 ? e.details
                 : undefined,
@@ -130,15 +195,31 @@ export class Api {
         const env = Api.envelope(res.body);
         // 426 version floor: print the SERVER's remedy verbatim (DX3/F8) — the
         // server knows the canonical command better than a stale client does.
+        //
+        // ⚠️ "VERBATIM" MEANS "DO NOT REWRITE THE SERVER'S WORDS", NOT "DO NOT SANITIZE".
+        // The reason the comment above gives is that a stale client must not substitute
+        // its own command — an argument about WHICH command, not about which bytes. Our
+        // own server already strips escapes and newlines from this string before sending
+        // it (lib/cli-auth/protocol.ts `upgradeRemedy`, a strict allowlist), so sanitizing
+        // here changes nothing an honest server sends and only alters a hostile one's.
+        // Stripping control characters preserves copy-pasteability; it is truncation and
+        // newline-collapsing that would destroy it, which is why the two halves are
+        // sanitized SEPARATELY and joined afterwards.
+        //
+        // ⚠️ SANITIZE BEFORE THE JOIN, NEVER AFTER. The `\n` below is the CLIENT's, not
+        // the server's, so a single pass over the joined string would delete the deliberate
+        // line break AND measure the cap against ~215 characters worst case, cutting the
+        // tail off the very command the remedy exists to provide.
         if (res.status === 426) {
-            const remedy = typeof env?.details?.remedy === "string" ? env.details.remedy : null;
-            const msg = env?.message ?? "This promptdock CLI version is no longer supported.";
+            const rawRemedy = typeof env?.details?.remedy === "string" ? env.details.remedy : null;
+            const remedy = rawRemedy ? terminalLine(rawRemedy, SERVER_REMEDY_MAX) : "";
+            const msg = env?.message || "This promptdock CLI version is no longer supported.";
             return new CliError(remedy ? `${msg}\n${remedy}` : msg, EXIT.DENIED, {
                 footer: "upgrade_required",
             });
         }
         if (res.status === 401) {
-            return new CliError(env?.message ?? "Not authenticated.", EXIT.AUTH, {
+            return new CliError(env?.message || "Not authenticated.", EXIT.AUTH, {
                 footer: "auth",
                 hint: "run: npx promptdock@latest login",
             });
@@ -147,12 +228,12 @@ export class Api {
             const retryAfter = res.headers.get("retry-after");
             const secs = retryAfter ? Number(retryAfter) : null;
             const wait = secs && Number.isFinite(secs) ? ` Retry in ~${Math.ceil(secs / 60)} min.` : "";
-            return new CliError((env?.message ?? "Rate limited.") + wait, EXIT.DENIED, {
-                footer: env?.code ?? "rate_limited",
+            return new CliError((env?.message || "Rate limited.") + wait, EXIT.DENIED, {
+                footer: documentedFooter(env?.code) ?? "rate_limited",
             });
         }
-        return new CliError(env?.message ?? `request failed (HTTP ${res.status})`, EXIT.DENIED, {
-            footer: env?.code ?? "api",
+        return new CliError(env?.message || `request failed (HTTP ${res.status})`, EXIT.DENIED, {
+            footer: documentedFooter(env?.code) ?? "api",
         });
     }
 }

package/dist/args.js

@@ -16,11 +16,11 @@ export const COMMAND_SPECS = {
         values: ["target", "dir"],
     },
     uninstall: {
-        booleans: ["help", "json", "global", "yes", "force", "all"],
+        booleans: ["help", "json", "global", "yes", "force", "all", "allow-partial"],
         values: ["target", "dir"],
     },
     update: {
-        booleans: ["help", "json", "global", "yes", "force", "all", "check"],
+        booleans: ["help", "json", "global", "yes", "force", "all", "check", "allow-partial"],
         values: ["target", "dir"],
     },
     list: { booleans: ["help", "json", "global", "all"], values: [] },

package/dist/auth.js

@@ -5,6 +5,7 @@ import { hostname } from "node:os";
 import { Api } from "./api.js";
 import { loadConfig, resolveApiBase, resolveToken, saveConfig } from "./config.js";
 import { CliError, EXIT } from "./errors.js";
+import { LOCATION_MAX, SERVER_LABEL_MAX, terminalLine } from "./terminal-text.js";
 import { formatCountdown } from "./ui.js";
 /**
  * Run the browser hand-off and return the bearer token. NEVER logs the token.
@@ -19,12 +20,16 @@ export async function deviceFlowLogin(ctx, baseUrl, opts) {
             device_label: safeDeviceLabel(),
             long: opts.long,
         });
+        // ⚠️ PRE-AUTH SINK. `/cli/auth/start` needs no token, so anything that can answer
+        // this request — a hostile origin, a captive portal, a MITM — chooses these two
+        // strings, and `api.request` returns `res.body as T` with no runtime validation.
+        // Sanitized for DISPLAY only; the raw `verification_url` is what gets opened.
         ctx.io.out("");
         ctx.io.out("Confirm this code in your browser:");
         ctx.io.out("");
-        ctx.io.out(`    ${start.user_code}`);
+        ctx.io.out(`    ${terminalLine(start.user_code, SERVER_LABEL_MAX)}`);
         ctx.io.out("");
-        ctx.io.out(`Open: ${start.verification_url}`);
+        ctx.io.out(`Open: ${terminalLine(start.verification_url, LOCATION_MAX)}`);
         if (ctx.io.isTTY) {
             ctx.openUrl(start.verification_url);
             ctx.io.out("(if the page didn't open, paste the URL into your browser)");

package/dist/commands/install.js

@@ -5,7 +5,9 @@
 import { existsSync, readdirSync } from "node:fs";
 import { isAbsolute, resolve as resolvePath } from "node:path";
 import { ensureAuth } from "../auth.js";
+import { newerSchemaError, rerunCommand } from "./lifecycle.js";
 import { CliError, EXIT, 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 { detectionLabel, detectTargets, detectTargetsAnyScope, nextStepLine, scopeChoices, targetById, targetInstallDir, TARGETS, } from "../registry.js";
@@ -38,7 +40,7 @@ export async function runInstall(ctx, positionals, flags) {
     // ── receipt awareness (DX3/DX5) ────────────────────────────────────────────
     const existing = readReceipt(picked.dir);
     if (existing.kind === "newer_schema") {
-        throw new CliError(`${picked.dir} was installed by a newer promptdock CLI (receipt schema ${existing.schema}). Run: npx promptdock@latest ${ctx.argsLine}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
+        throw newerSchemaError(picked.dir, existing.schema, rerunCommand("install", positionals, flags));
     }
     const matching = existing.kind === "ok" && existing.receipt.skill_id === resolve.skill_id
         ? existing.receipt
@@ -51,25 +53,50 @@ export async function runInstall(ctx, positionals, flags) {
     }
     if (isUpdate && matching.version_id === resolve.version_id && flags.force !== true && !dryRun) {
         ctx.io.out(json
-            ? JSON.stringify({ installed: false, up_to_date: true, version: matching.version, path: picked.dir })
-            : `"${resolve.title ?? refString}" is already up to date (v${matching.version}) at ${picked.dir} — use --force to reinstall.`);
+            ? JSON.stringify({
+                installed: false,
+                up_to_date: true,
+                update: true,
+                ref: refString,
+                version: matching.version,
+                version_id: matching.version_id,
+                target: picked.id,
+                path: picked.dir,
+            })
+            : `"${terminalLine(resolve.title, SERVER_LABEL_MAX) || refString}" is already up to date (v${matching.version}) at ${picked.dir} — use --force to reinstall.`);
         return;
     }
+    // ⚠️ SANITIZE THE FRAGMENTS, NOT THE LINES. The summary pads its labels into
+    // columns ("  version:  v3"), and `terminalLine` collapses whitespace runs — one
+    // pass over a finished line would flatten every one of them.
+    const safeTitle = terminalLine(resolve.title, SERVER_LABEL_MAX) || refString;
+    const safeAuthor = terminalLine(resolve.author, SERVER_LABEL_MAX) || ref.handle;
+    const safeLicense = terminalLine(resolve.license, SERVER_LABEL_MAX);
+    // ⚠️ `version` IS TYPED `number` AND IS NOT ONE. It arrives through the same bare
+    // `res.body as T` cast as everything else, and `checkInstallResponse` validates
+    // `skill.version_id` and `skill.slug` but NOT `skill.version` — so a hostile string
+    // used to render raw right beside the title this block sanitizes.
+    const ver = (v) => terminalLine(String(v), SERVER_LABEL_MAX);
+    // A filesystem path, not a server string — but `readdirSync` entry names may contain
+    // anything except `/` and NUL, and this is the ONE line that tells the user where
+    // files are about to be written. A crafted directory name could erase it, which
+    // defeats confirm-before-write itself.
+    const safeDir = terminalLine(picked.dir, SERVER_PATH_MAX);
     // ── summary block (D-UX11 confirm-before-write) ────────────────────────────
     const summary = [];
     if (isUpdate) {
-        summary.push(`Update ${c.bold(`"${resolve.title ?? refString}"`)} by @${resolve.author ?? ref.handle}`);
-        summary.push(`  version:  v${matching.version} → v${resolve.version}`);
+        summary.push(`Update ${c.bold(`"${safeTitle}"`)} by @${safeAuthor}`);
+        summary.push(`  version:  v${ver(matching.version)} → v${ver(resolve.version)}`);
     }
     else {
-        summary.push(`Install ${c.bold(`"${resolve.title ?? refString}"`)} by @${resolve.author ?? ref.handle}`);
-        summary.push(`  version:  v${resolve.version}`);
+        summary.push(`Install ${c.bold(`"${safeTitle}"`)} by @${safeAuthor}`);
+        summary.push(`  version:  v${ver(resolve.version)}`);
     }
     summary.push(`  files:    ${resolve.file_count ?? "?"} files · ${formatBytes(Number(resolve.total_bytes) || 0)}`);
-    if (resolve.license)
-        summary.push(`  license:  ${resolve.license}`);
+    if (safeLicense)
+        summary.push(`  license:  ${safeLicense}`);
     summary.push(`  access:   ${resolve.is_free === false ? "premium" : "free"}`);
-    summary.push(`  to:       ${picked.dir}`);
+    summary.push(`  to:       ${safeDir}`);
     if (dryRun) {
         if (json) {
             ctx.io.out(JSON.stringify({
@@ -114,8 +141,15 @@ export async function runInstall(ctx, positionals, flags) {
     if (!json) {
         ctx.io.out(`Downloading ${resp.manifest.length} files…`);
         const shown = resp.manifest.slice(0, 8);
-        for (const e of shown)
-            ctx.io.out(`  ${e.path} ${c.dim(`(${formatBytes(e.bytes)})`)}`);
+        // ⚠️ DISPLAY ONLY. `e.path` names the file `performInstall` writes and the sha256
+        // it verifies against, so the value itself must stay byte-identical — sanitizing
+        // it at the source would change what the integrity check runs on. Note these are
+        // printed BEFORE `assertSafeManifest` validates them (checkInstallResponse →
+        // print → performInstall → validate), so a path that is about to be REFUSED is
+        // rendered here; that ordering is what makes sanitizing this line necessary.
+        for (const e of shown) {
+            ctx.io.out(`  ${terminalLine(e.path, SERVER_PATH_MAX)} ${c.dim(`(${formatBytes(e.bytes)})`)}`);
+        }
         if (resp.manifest.length > shown.length) {
             ctx.io.out(c.dim(`  +${resp.manifest.length - shown.length} more`));
         }
@@ -141,7 +175,7 @@ export async function runInstall(ctx, positionals, flags) {
         return;
     }
     ctx.io.out("");
-    ctx.io.out(`${c.green("✓")} ${isUpdate ? "Updated" : "Installed"} "${resp.skill.title}" v${resp.skill.version} → ${picked.dir}`);
+    ctx.io.out(`${c.green("✓")} ${isUpdate ? "Updated" : "Installed"} "${terminalLine(resp.skill.title, SERVER_LABEL_MAX)}" v${terminalLine(String(resp.skill.version), SERVER_LABEL_MAX)} → ${terminalLine(picked.dir, SERVER_PATH_MAX)}`);
     ctx.io.out(nextStepLine(picked.id, resp.skill.slug));
 }
 /**

package/dist/commands/lifecycle.d.ts

@@ -1,5 +1,19 @@
 import type { CliContext } from "../context.js";
+import { CliError } from "../errors.js";
 type Flags = Record<string, string | boolean>;
+/**
+ * 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 declare function rerunCommand(command: string, positionals: string[], flags: Flags): string;
+export declare function newerSchemaError(dir: string, schema: number, rerun: string): CliError;
 export declare function runUninstall(ctx: CliContext, positionals: string[], flags: Flags): Promise<void>;
 export declare function runUpdate(ctx: CliContext, positionals: string[], flags: Flags): Promise<void>;
 export declare function runList(ctx: CliContext, flags: Flags): Promise<void>;