promptdock 1.2.0 → 1.2.1

package/dist/context.js

@@ -88,15 +88,87 @@ export function readOwnVersion() {
         return "0.0.0";
     }
 }
-/** 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 function openableUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return null; // not a URL at all — a UNC path and a bare `-h` both land here
+    }
+    const loopback = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
+    // Mirrors config.ts's TLS floor (`assertSecureBase`). Blocks file:, smb:, javascript:,
+    // vbscript: and every app-registered scheme from reaching the platform opener.
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback))
+        return null;
+    return u.toString();
+}
+/**
+ * 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 function openUrlCommand(url, platform) {
+    const safe = openableUrl(url);
+    if (!safe)
+        return null;
+    if (platform === "darwin") {
+        // `--` ends option parsing: measured, `open` reads a leading-dash first argument as
+        // a flag. Belt-and-braces over the scheme gate above, which a future edit could drift
+        // from.
+        return ["open", ["--", safe]];
+    }
+    if (platform === "win32") {
+        // ⚠️ NOT `cmd /c start`, WHICH WAS A COMMAND-INJECTION PRIMITIVE.
+        //
+        // libuv quotes arguments for the MSVCRT argv parser (`quote_cmd_arg`, src/win/
+        // process.c) and copies any argument containing no space, tab or quote VERBATIM.
+        // cmd.exe then parses that string by ITS OWN rules, where `&`, `|` and `^` are
+        // command separators and `\"` is not an escape. So a perfectly well-formed https URL
+        // — `https://host/cli-auth?code=A&calc` — reached cmd.exe as two commands.
+        //
+        // ⚠️ AND A SCHEME CHECK ALONE DOES NOT CLOSE IT: `new URL(u).toString()`
+        // percent-encodes space, quotes and control characters but PRESERVES `&`, `|` and
+        // `^`, and `&` is ordinary in a query string — so no URL-shape validation short of a
+        // character allowlist (which would break legitimate multi-parameter URLs) helps. The
+        // fix has to be not going through cmd.exe.
+        //
+        // This is the BatBadBut root cause (CVE-2024-27980). Node's fix does NOT cover it:
+        // that throws EINVAL only when the spawn TARGET is a .bat/.cmd file, and the target
+        // here was cmd.exe itself — so no Node version protected this call shape.
+        //
+        // explorer.exe is a normal PE, so libuv's CRT-style quoting is the CORRECT quoting
+        // for it and no second parser ever sees the string. (It always exits 1; the status
+        // was already ignored.)
+        return ["explorer.exe", [safe]];
+    }
+    return ["xdg-open", ["--", safe]];
+}
+/** Best-effort platform browser open (darwin `open`, win32 `explorer`, else xdg-open). */
 export function openUrlBestEffort(url, platform) {
+    const decided = openUrlCommand(url, platform);
+    // Refusing is SAFE and silent by design: auth.ts has already PRINTED the URL and tells
+    // the user to paste it if the browser did not open.
+    if (!decided)
+        return;
     try {
-        const [cmd, args] = platform === "darwin"
-            ? ["open", [url]]
-            : platform === "win32"
-                ? // `start` is a cmd.exe builtin; the empty "" is its window-title slot.
-                    ["cmd", ["/c", "start", "", url]]
-                : ["xdg-open", [url]];
+        const [cmd, args] = decided;
         const child = spawn(cmd, args, { stdio: "ignore", detached: true });
         child.on("error", () => undefined);
         child.unref();

package/dist/errors.d.ts

@@ -19,6 +19,14 @@ export declare const EXIT: {
     readonly INTERRUPT: 130;
 };
 export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** The error catalogue itself — the anchor-less landing page for a failure with no slug.
+ *
+ *  ⚠️ DERIVED from `CANONICAL_ORIGIN`, not a literal, and the reason is not tidiness:
+ *  this URL is printed under EVERY error — including the one that says the apex redirect
+ *  drops your body and your token. It shipped naming the apex, so that error handed the
+ *  user a redirecting link while explaining that redirects break things. It also rides
+ *  `toFailureJson`'s `doc_url`, which a `--json` consumer can fetch. */
+export declare const CLI_ERRORS_URL = "https://www.promptdock.ai/docs/cli/errors";
 /** DX3: every named error footer links its docs anchor. */
 export declare function footerUrl(code: string): string;
 export declare class CliError extends Error {
@@ -27,11 +35,90 @@ export declare class CliError extends Error {
     readonly footer?: string;
     /** one-line "what to do" printed after the message */
     readonly hint?: string;
+    /**
+     * Stable machine-readable slug for `--json` consumers (`error.code`).
+     *
+     * ⚠️ DERIVED from `footer`, with no constructor option of its own — deliberately.
+     * Two independently-set fields could disagree, and one of them is the docs anchor a
+     * stuck user clicks. It also keeps ONE source of slugs in this package, which is what
+     * `lib/cli/error-docs.test.ts` scans for (it reads the literal slug off every
+     * construction site) to prove every printed anchor has a page entry; a second slug
+     * channel would be invisible to that guard.
+     *
+     * The 9 CliErrors that carry no footer (base-url config, the batch roll-up, the
+     * picker's Cancelled/Interrupted) report `"error"` and point at the index page.
+     */
+    readonly code: string;
+    /**
+     * ⚠️ `message` and `hint` are passed through {@link terminalBlock} — the
+     * defence-in-depth BACKSTOP for terminal-control injection, not the primary control.
+     *
+     * The primary control is `terminalLine` at the trust boundary (api.ts's
+     * `Api.envelope`, and the 426 remedy), which is where an untrusted fragment is still
+     * identifiable as untrusted and can be bounded and collapsed to one line. This
+     * constructor cannot tell a server's prose from the CLI's own, so it only strips what
+     * is never legitimate ANYWHERE: escape introducers (C0 except newline, DEL, C1) and
+     * bidi/zero-width code points.
+     *
+     * It earns its place by covering what a boundary fix structurally cannot — the NEXT
+     * call site. A future command that reads a new server field and throws a CliError
+     * built from it is repaint-safe on the day it is written, which is precisely the
+     * failure this whole change exists to close.
+     *
+     * ⚠️ NEWLINE SURVIVES AND THERE IS NO LENGTH CAP, both deliberate and both load-
+     * bearing — see `terminalBlock`. Adding either here silently breaks the 426's
+     * two-line layout and truncates the `--json` batch roll-up.
+     */
     constructor(message: string, exitCode: ExitCode, opts?: {
         footer?: string;
         hint?: string;
     });
 }
+/**
+ * The `--json` shape of a TOP-LEVEL failure (Vercel's `{status, reason, hint, next}`
+ * lineage, keyed to this CLI's vocabulary). Stable: keys may be added in a patch,
+ * existing ones never change meaning — the same promise README makes for `results` rows.
+ */
+export type CliFailure = {
+    error: {
+        /** the docs anchor slug, or "error" when the failure has none */
+        code: string;
+        message: string;
+        exit_code: ExitCode;
+        /** always present — the anchor when there is one, else the errors index */
+        doc_url: string;
+    };
+};
+/**
+ * ONE place that turns any thrown value into the failure envelope, so the exit code a
+ * script reads and the exit code the process returns cannot drift (index.ts returns
+ * `failure.error.exit_code`).
+ *
+ * ⚠️ The `footerUrl` call below, with its inline `internal` slug, is load-bearing beyond
+ * this function: `lib/cli/error-docs.test.ts` scans packages/cli/src for that call shape
+ * and asserts it finds `internal` — an assertion that guards the SCANNER itself. If this
+ * moves, the literal call must stay somewhere under src/.
+ *
+ * ⚠️ AND THAT SCANNER IS A PLAIN TEXT SCAN, COMMENTS INCLUDED. Spelling either slug
+ * pattern out in prose registers a slug that has no docs entry and fails the guard the
+ * prose is explaining (it cost one red run writing this file). Name the channels
+ * indirectly, as above — never paste the shape.
+ */
+export declare function toFailureJson(err: unknown): CliFailure;
+/**
+ * Does this invocation want machine-readable output? Read from RAW argv, never from the
+ * parsed flags.
+ *
+ * ⚠️ `parseArgs` runs INSIDE index.ts's `try`, so `flags` does not exist in the `catch`
+ * at all — and a malformed invocation (`install a/b --json --bogus`) throws before it
+ * ever could. Those are precisely the failures a CI job most needs machine-readable, so
+ * the detection has to be independent of parsing succeeding.
+ *
+ * `--json` is boolean-only in COMMAND_SPECS (`--json=true` is a usage error), and
+ * everything after a bare `--` is a positional, so an exact scan of the pre-`--` slice
+ * is the whole rule.
+ */
+export declare function wantsJsonOutput(argv: readonly string[]): boolean;
 export declare function usageError(message: string, hint?: string): CliError;
 /**
  * DX3 per-OS filesystem error mapping. THREE distinct messages; the --force

package/dist/errors.js

@@ -1,3 +1,5 @@
+import { CANONICAL_ORIGIN } from "./generated/constants.js";
+import { SERVER_MESSAGE_MAX, terminalBlock, terminalLine } from "./terminal-text.js";
 // Stable exit codes (DX3) — scripts and CI depend on these; never renumber.
 export const EXIT = {
     OK: 0,
@@ -19,9 +21,17 @@ export const EXIT = {
      *  in-UI cancel) stays USAGE=1. Scripts never reach pickers (TTY-only). */
     INTERRUPT: 130,
 };
+/** The error catalogue itself — the anchor-less landing page for a failure with no slug.
+ *
+ *  ⚠️ DERIVED from `CANONICAL_ORIGIN`, not a literal, and the reason is not tidiness:
+ *  this URL is printed under EVERY error — including the one that says the apex redirect
+ *  drops your body and your token. It shipped naming the apex, so that error handed the
+ *  user a redirecting link while explaining that redirects break things. It also rides
+ *  `toFailureJson`'s `doc_url`, which a `--json` consumer can fetch. */
+export const CLI_ERRORS_URL = `${CANONICAL_ORIGIN}/docs/cli/errors`;
 /** DX3: every named error footer links its docs anchor. */
 export function footerUrl(code) {
-    return `https://promptdock.ai/docs/cli/errors#${code}`;
+    return `${CLI_ERRORS_URL}#${code}`;
 }
 export class CliError extends Error {
     exitCode;
@@ -29,14 +39,108 @@ export class CliError extends Error {
     footer;
     /** one-line "what to do" printed after the message */
     hint;
+    /**
+     * Stable machine-readable slug for `--json` consumers (`error.code`).
+     *
+     * ⚠️ DERIVED from `footer`, with no constructor option of its own — deliberately.
+     * Two independently-set fields could disagree, and one of them is the docs anchor a
+     * stuck user clicks. It also keeps ONE source of slugs in this package, which is what
+     * `lib/cli/error-docs.test.ts` scans for (it reads the literal slug off every
+     * construction site) to prove every printed anchor has a page entry; a second slug
+     * channel would be invisible to that guard.
+     *
+     * The 9 CliErrors that carry no footer (base-url config, the batch roll-up, the
+     * picker's Cancelled/Interrupted) report `"error"` and point at the index page.
+     */
+    code;
+    /**
+     * ⚠️ `message` and `hint` are passed through {@link terminalBlock} — the
+     * defence-in-depth BACKSTOP for terminal-control injection, not the primary control.
+     *
+     * The primary control is `terminalLine` at the trust boundary (api.ts's
+     * `Api.envelope`, and the 426 remedy), which is where an untrusted fragment is still
+     * identifiable as untrusted and can be bounded and collapsed to one line. This
+     * constructor cannot tell a server's prose from the CLI's own, so it only strips what
+     * is never legitimate ANYWHERE: escape introducers (C0 except newline, DEL, C1) and
+     * bidi/zero-width code points.
+     *
+     * It earns its place by covering what a boundary fix structurally cannot — the NEXT
+     * call site. A future command that reads a new server field and throws a CliError
+     * built from it is repaint-safe on the day it is written, which is precisely the
+     * failure this whole change exists to close.
+     *
+     * ⚠️ NEWLINE SURVIVES AND THERE IS NO LENGTH CAP, both deliberate and both load-
+     * bearing — see `terminalBlock`. Adding either here silently breaks the 426's
+     * two-line layout and truncates the `--json` batch roll-up.
+     */
     constructor(message, exitCode, opts) {
-        super(message);
+        super(terminalBlock(message));
         this.name = "CliError";
         this.exitCode = exitCode;
         this.footer = opts?.footer;
-        this.hint = opts?.hint;
+        this.hint = opts?.hint === undefined ? undefined : terminalBlock(opts.hint);
+        this.code = opts?.footer ?? "error";
     }
 }
+/**
+ * ONE place that turns any thrown value into the failure envelope, so the exit code a
+ * script reads and the exit code the process returns cannot drift (index.ts returns
+ * `failure.error.exit_code`).
+ *
+ * ⚠️ The `footerUrl` call below, with its inline `internal` slug, is load-bearing beyond
+ * this function: `lib/cli/error-docs.test.ts` scans packages/cli/src for that call shape
+ * and asserts it finds `internal` — an assertion that guards the SCANNER itself. If this
+ * moves, the literal call must stay somewhere under src/.
+ *
+ * ⚠️ AND THAT SCANNER IS A PLAIN TEXT SCAN, COMMENTS INCLUDED. Spelling either slug
+ * pattern out in prose registers a slug that has no docs entry and fails the guard the
+ * prose is explaining (it cost one red run writing this file). Name the channels
+ * indirectly, as above — never paste the shape.
+ */
+export function toFailureJson(err) {
+    if (err instanceof CliError) {
+        return {
+            error: {
+                code: err.code,
+                message: err.message,
+                exit_code: err.exitCode,
+                doc_url: err.footer ? footerUrl(err.footer) : CLI_ERRORS_URL,
+            },
+        };
+    }
+    // ⚠️ THE ONE SINK WITH NO BACKSTOP. Everything else that reaches the terminal is
+    // either a CliError (sanitized in its constructor) or a display site that now calls
+    // `terminalLine`. This branch is neither: the thrown value is arbitrary — a library's
+    // Error message, a rejected fetch, a string from anywhere — and index.ts prints it.
+    // Bounded as well as stripped, since a stack-shaped message can run for pages.
+    const detail = terminalLine(err instanceof Error ? err.message : String(err), SERVER_MESSAGE_MAX);
+    return {
+        error: {
+            code: "internal",
+            message: `unexpected error: ${detail}`,
+            exit_code: EXIT.USAGE,
+            doc_url: footerUrl("internal"),
+        },
+    };
+}
+/**
+ * Does this invocation want machine-readable output? Read from RAW argv, never from the
+ * parsed flags.
+ *
+ * ⚠️ `parseArgs` runs INSIDE index.ts's `try`, so `flags` does not exist in the `catch`
+ * at all — and a malformed invocation (`install a/b --json --bogus`) throws before it
+ * ever could. Those are precisely the failures a CI job most needs machine-readable, so
+ * the detection has to be independent of parsing succeeding.
+ *
+ * `--json` is boolean-only in COMMAND_SPECS (`--json=true` is a usage error), and
+ * everything after a bare `--` is a positional, so an exact scan of the pre-`--` slice
+ * is the whole rule.
+ */
+export function wantsJsonOutput(argv) {
+    const sep = argv.indexOf("--");
+    const scanned = sep === -1 ? argv : argv.slice(0, sep);
+    return scanned.includes("--json");
+}
 export function usageError(message, hint) {
     return new CliError(message, EXIT.USAGE, { hint, footer: "usage" });
 }

package/dist/generated/constants.d.ts

@@ -13,7 +13,9 @@ export declare const CLI_FUSE_HISTORY: {
 export declare const MAX_SKILL_IMAGES = 5;
 export declare const SKILL_REVEAL_DAILY_CAP = 15;
 export declare const CLI_MIN_VERSION = "1.0.1";
-export declare const PUBLISHED_CLI_VERSION = "1.1.0";
+export declare const PUBLISHED_CLI_VERSION = "1.2.0";
 export declare const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export declare const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export declare const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";
+export declare const CANONICAL_ORIGIN = "https://www.promptdock.ai";
+export declare const CANONICAL_CONTACT_PATH = "/contact";

package/dist/generated/constants.js

@@ -10,7 +10,9 @@ export const CLI_FUSE_HISTORY = [{ "cli_version": "0.0.0", "max_files": 25, "max
 export const MAX_SKILL_IMAGES = 5;
 export const SKILL_REVEAL_DAILY_CAP = 15;
 export const CLI_MIN_VERSION = "1.0.1";
-export const PUBLISHED_CLI_VERSION = "1.1.0";
+export const PUBLISHED_CLI_VERSION = "1.2.0";
 export const SKILL_SLUG_RE_SOURCE = "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$";
 export const SKILL_HANDLE_RE_SOURCE = "^[a-z0-9][a-z0-9_-]{0,62}$";
 export const CANONICAL_INSTALL_COMMAND = "npx promptdock@latest install";
+export const CANONICAL_ORIGIN = "https://www.promptdock.ai";
+export const CANONICAL_CONTACT_PATH = "/contact";

package/dist/help.js

@@ -1,7 +1,25 @@
 // DX4: `promptdock --help` is a COMPLETE zero-config map; every command also
 // answers `promptdock <cmd> --help`.
-import { CANONICAL_INSTALL_COMMAND } from "./generated/constants.js";
+import { CANONICAL_CONTACT_PATH, CANONICAL_INSTALL_COMMAND, CANONICAL_ORIGIN } from "./generated/constants.js";
 import { TARGETS } from "./registry.js";
+/**
+ * ⚠️ THE HELP FOOTER NAMES URLs, NEVER AN EMAIL ADDRESS — and that is the whole design,
+ * not a style preference. A published binary is frozen on someone's disk forever: an
+ * address baked into 1.2.1 is still being printed years after the mailbox moves, with no
+ * way to correct it. A URL is indirection: the PAGE decides which mailbox is current, so
+ * support routing changes without an npm publish. (The single exception is
+ * package.json's `bugs.email`, which npm's metadata schema has no URL form for — and
+ * that field IS re-published with every release.)
+ *
+ * `CANONICAL_CONTACT_PATH` comes from lib/validation/skills-constants.json via
+ * `pnpm run gen:cli-constants`, so the web route and this footer cannot drift apart.
+ * These lines are also captured verbatim into lib/cli/reference.generated.json when
+ * PUBLISHED_CLI_VERSION catches up — /docs/cli/reference keeps showing 1.2.0's footer
+ * (no Support line) until then, by design.
+ */
+/** ⚠️ DERIVED from `CANONICAL_ORIGIN` (same shared JSON as CANONICAL_CONTACT_PATH above),
+ *  so the Docs / Errors / Support lines cannot name a host the API is not served on. */
+const SITE = CANONICAL_ORIGIN;
 export function globalHelp(version) {
     const targets = TARGETS.map((t) => `      ${t.id.padEnd(9)} ${t.localBase}/<slug>   (-g: ~/${t.globalBase}/<slug>)${t.experimental ? "  (experimental)" : ""}`).join("\n");
     return `promptdock v${version} — install AI agent skills from promptdock.ai
@@ -11,7 +29,7 @@ export function globalHelp(version) {
 
   Commands
     login [--token pdk_…]     log in (browser hand-off, or store a CI token)
-    logout                    remove the local token (revoke in Settings to kill it server-side)
+    logout                    log out (revokes the session server-side, clears the local token)
     whoami [--json]           show the signed-in account
     install <ref> [options]   install a skill (ref = handle/slug, @handle/slug, or a pasted URL)
     uninstall <ref|--all>     remove an installed skill (receipt-driven; never touches unmanaged files)
@@ -33,19 +51,23 @@ export function globalHelp(version) {
     --check                   (update) report available updates without applying
     --all                     operate across project-local AND global scopes
     -g, --global              operate on the global scope (bare commands are project-local)
+    --allow-partial           exit 0 even when an item failed (default: exit non-zero)
 
   Targets
 ${targets}
 
   Environment
-    PROMPTDOCK_TOKEN          bearer token for CI/non-interactive use (Settings → CLI sessions → Generate token)
+    PROMPTDOCK_TOKEN          CI bearer token (Settings → Account → CLI sessions)
     PROMPTDOCK_API_BASE       API origin override (default https://www.promptdock.ai)
     NO_COLOR                  disable colored output
 
   Exit codes
-    0 ok · 1 usage · 2 auth · 3 denied/gated · 4 integrity · 5 filesystem · 6 network
+    0 ok · 1 usage · 2 auth · 3 denied/gated · 4 integrity · 5 filesystem
+    6 network · 130 interrupted (Ctrl-C in a prompt; Esc cancels with 1)
 
-  Docs: https://promptdock.ai/docs/cli`;
+  Docs:    ${SITE}/docs/cli
+  Errors:  ${SITE}/docs/cli/errors
+  Support: ${SITE}${CANONICAL_CONTACT_PATH}`;
 }
 export const COMMAND_HELP = {
     login: `promptdock login [--token pdk_…]
@@ -55,8 +77,12 @@ you approve there, and the terminal continues. --token stores a token minted in
 Settings → Account → CLI sessions (the CI path; or set PROMPTDOCK_TOKEN).`,
     logout: `promptdock logout
 
-Removes the locally-stored token (~/.promptdock/config.json). The server-side
-session stays valid until revoked in Settings → Account → CLI sessions.`,
+Revokes the session server-side FIRST — the token this machine holds stops
+working immediately — then removes the local copy from ~/.promptdock/config.json.
+
+If the revoke cannot reach the server (offline), the local token is still
+removed and the CLI says so on stderr: that session stays valid until it
+expires, so revoke it at Settings → Account → CLI sessions.`,
     whoami: `promptdock whoami [--json]
 
 Shows the signed-in handle, role, and token expiry.`,
@@ -71,16 +97,26 @@ authenticate via PROMPTDOCK_TOKEN. -y skips the prompts ONLY — a non-empty
 foreign directory still requires --force, and scope stays project-local
 unless -g is passed. --dry-run resolves and prints the plan without
 installing (and without spending any premium-unlock slot).`,
-    uninstall: `promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--json]
+    uninstall: `promptdock uninstall <handle>/<slug> | --all [-g] [--target <tool>] [--dir <path>] [--force] [-y] [--allow-partial] [--json]
 
 Removes an installed skill using its .promptdock.json receipt — only files the
 receipt lists are ever deleted. Locally-modified files block removal without
---force (copy your changes out first).`,
-    update: `promptdock update [<handle>/<slug>] [--all] [--check] [-g] [-y] [--force] [--json]
+--force (copy your changes out first).
+
+Across a batch (--all, or a scope holding several skills) one bad item no
+longer aborts the rest: the others are still removed and the command exits
+with that item's code at the end. --allow-partial exits 0 instead. Declining
+a confirm is not a failure.`,
+    update: `promptdock update [<handle>/<slug>] [--all] [--check] [-g] [-y] [--force] [--allow-partial] [--json]
 
 Updates installed skills to the latest approved version. Bare \`update\` covers
 the project-local scope; -g the global scope; --all both. --check reports
-without applying. Locally-modified files block an update without --force.`,
+without applying. Locally-modified files block an update without --force.
+
+An item that FAILS (unreachable, gated, blocked by local edits) no longer
+stops the batch — the rest still update — but the command exits non-zero at
+the end so CI cannot go green on an update that did nothing. --allow-partial
+exits 0 instead. "Up to date" and a declined confirm are not failures.`,
     list: `promptdock list [--json] [-g] [--all]
 
 Lists installed skills from their receipts: ref, version, target, installed-at.`,

package/dist/index.js

@@ -3,15 +3,46 @@
 // Contract: app/api/v1/cli/** (server), docs/plans/skills-marketplace.md.
 import { parseArgs } from "./args.js";
 import { realContext } from "./context.js";
-import { CliError, EXIT, footerUrl } from "./errors.js";
+import { CliError, EXIT, footerUrl, toFailureJson, wantsJsonOutput } from "./errors.js";
 import { COMMAND_HELP, globalHelp } from "./help.js";
 import { colors } from "./ui.js";
 import { runInstall } from "./commands/install.js";
 import { runLogin, runLogout, runWhoami } from "./commands/login.js";
 import { runList, runUninstall, runUpdate } from "./commands/lifecycle.js";
+/**
+ * SINGLE-OWNER stdout serialization for `--json`.
+ *
+ * ⚠️ THE BUG THIS PREVENTS: `update`/`uninstall` flush their complete report from a
+ * `finally` and THEN throw (lifecycle.ts — a failing item must never cost the caller the
+ * list of what did succeed). A top-level catch that unconditionally printed its own
+ * `{error:…}` would put TWO JSON documents on stdout, and `jq` reads exactly one — so
+ * the fix for "failures are invisible under --json" would have broken every batch
+ * consumer that already works (`batch-exit.test.ts` does a bare `JSON.parse(stdout)`).
+ *
+ * So stdout has one owner per run: whoever writes first keeps it. This wrapper records
+ * whether anything reached stdout at all, which is exactly the right predicate because
+ * under `--json` every stdout write in this CLI IS a complete document followed by a
+ * return (install.ts, lifecycle.ts, login.ts all gate their human progress lines on
+ * `!json`). `write` is tracked too: the countdown repaint is TTY-only, but a partial
+ * line on stdout means the same thing — the stream is no longer ours to own.
+ */
+function trackStdout(base) {
+    let used = false;
+    const mark = (fn) => (s) => {
+        used = true;
+        return fn(s);
+    };
+    return {
+        ctx: { ...base, io: { ...base.io, out: mark(base.io.out), write: mark(base.io.write) } },
+        used: () => used,
+    };
+}
 async function main() {
     const argv = process.argv.slice(2);
-    const ctx = realContext(argv);
+    // From RAW argv: `flags` is scoped to the try below and a parse error throws before it
+    // exists, yet a malformed invocation is exactly what CI needs machine-readable.
+    const json = wantsJsonOutput(argv);
+    const { ctx, used: stdoutUsed } = trackStdout(realContext(argv));
     const c = colors(ctx.env, Boolean(process.stderr.isTTY));
     try {
         const { command, positionals, flags } = parseArgs(argv);
@@ -55,18 +86,26 @@ async function main() {
         }
     }
     catch (err) {
+        const failure = toFailureJson(err);
+        // Human text ALWAYS goes to stderr, `--json` or not: under --json stdout is reserved
+        // for at most one machine-readable document, and a person watching a piped run still
+        // needs to see what happened. Byte-identical to the pre-1.2.1 output.
         if (err instanceof CliError) {
             ctx.io.err(c.red(err.message));
             if (err.hint)
                 ctx.io.err(err.hint);
             if (err.footer)
                 ctx.io.err(c.dim(footerUrl(err.footer)));
-            return err.exitCode;
         }
-        const detail = err instanceof Error ? err.message : String(err);
-        ctx.io.err(c.red(`unexpected error: ${detail}`));
-        ctx.io.err(c.dim(footerUrl("internal")));
-        return EXIT.USAGE;
+        else {
+            ctx.io.err(c.red(failure.error.message));
+            ctx.io.err(c.dim(failure.error.doc_url));
+        }
+        // The report a batch command already flushed IS the machine-readable answer (its
+        // rows carry `failed`/`exit` per item). Appending a second document would corrupt it.
+        if (json && !stdoutUsed())
+            ctx.io.out(JSON.stringify(failure));
+        return failure.error.exit_code;
     }
 }
 main().then((code) => process.exit(code), () => process.exit(EXIT.USAGE));

package/dist/installer.js

@@ -9,6 +9,7 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CliError, EXIT, mapFsError, networkError } from "./errors.js";
+import { SERVER_PATH_MAX, terminalLine } from "./terminal-text.js";
 import { CLI_DOS_MAX_SKILL_FILES as MAX_SKILL_FILES, CLI_DOS_MAX_SKILL_FILE_BYTES as MAX_SKILL_FILE_BYTES, CLI_DOS_MAX_SKILL_TOTAL_BYTES as MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
 import { sha256Hex, sha256Matches } from "./integrity.js";
 import { validateSkillPaths } from "./paths.js";
@@ -98,7 +99,14 @@ export function assertSafeManifest(manifest) {
     const issues = validateSkillPaths(manifest.map((e) => e.path));
     if (issues.length > 0) {
         const first = issues[0];
-        throw new CliError(`unsafe file path in manifest ("${first.path}": ${first.reason}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_path" });
+        throw new CliError(
+        // ⚠️ THE SECURITY CONTROL'S OWN MESSAGE WAS THE INJECTION CHANNEL.
+        // `validateSkillPaths` checks length → backslash → absolute → control chars in
+        // that order, so a path rejected on any of the first three is echoed here having
+        // never been control-char checked. The CliError backstop strips escapes, but only
+        // this bounds it to one line — and 256 is validateSkillPaths' own length rule, so
+        // it can never clamp a path this function would have accepted.
+        `unsafe file path in manifest ("${terminalLine(first.path, SERVER_PATH_MAX)}": ${first.reason}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_path" });
     }
     if (manifest.length === 0 || manifest.length > MAX_SKILL_FILES) {
         throw new CliError(`manifest lists ${manifest.length} files (limit ${MAX_SKILL_FILES}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_bounds" });

package/dist/registry.d.ts

@@ -96,4 +96,4 @@ export declare function detectTargets(opts: {
     exists?: (p: string) => boolean;
 }): DetectedTarget[];
 /** DX1/DX F2/F16 — the per-target next step, incl. the RELOAD caveat. */
-export declare function nextStepLine(targetId: string, slug: string): string;
+export declare function nextStepLine(targetId: string, rawSlug: string): string;

package/dist/registry.js

@@ -4,6 +4,7 @@
 // floats detected tools to the top and preselects the first (D-UX11).
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { SERVER_LABEL_MAX, terminalLine } from "./terminal-text.js";
 export const TARGETS = [
     {
         id: "claude",
@@ -158,7 +159,10 @@ export function detectTargets(opts) {
     return [...all.filter((t) => t.detected), ...all.filter((t) => !t.detected)];
 }
 /** DX1/DX F2/F16 — the per-target next step, incl. the RELOAD caveat. */
-export function nextStepLine(targetId, slug) {
+export function nextStepLine(targetId, rawSlug) {
+    // Sanitized INSIDE rather than at the call site: this function's whole output is
+    // display, so every present and future caller is covered by one line.
+    const slug = terminalLine(rawSlug, SERVER_LABEL_MAX);
     switch (targetId) {
         case "claude":
             return `Next: start a NEW session in Claude Code (open sessions don't see new skills) and type /${slug}`;