promptdock 1.2.0 → 1.2.1

package/dist/terminal-text.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Terminal-output hygiene - the ONE place this package decides what an untrusted
+ * string may write to a user's terminal.
+ *
+ * WARNING: THIS FILE EXISTS BECAUSE A DOC COMMENT IS NOT A CONTRACT. Its predecessor
+ * was a private `sanitizeForTerminal` inside api.ts whose comment stated a GENERAL
+ * rule ("strip control chars before a server-supplied string reaches the terminal")
+ * while the code was applied at exactly ONE call site - the redirect Location. Five
+ * sibling sites in the same function shipped raw for the life of the file, and the
+ * comment is what stopped anyone looking. So: the rule now lives in its own module,
+ * is exported, is unit-tested against a character table, and every guarantee below is
+ * one a test pins. Do not restate a guarantee here that no test holds.
+ *
+ * THE THREAT. A hostile or MITM'd API response (a 401 needs no valid token to
+ * produce, and a captive portal can mint any status) can put terminal control
+ * sequences into a string this CLI prints. What that buys an attacker, worst first:
+ *   1. NEWLINE injection - needs no escape at all, so it survives any strip-ESC
+ *      filter. One newline in a server message forges a whole line of CLI output: a
+ *      green "installed" tick, a fake footer URL, a fake prompt.
+ *   2. CSI erase/cursor-move (ESC, or the 8-bit C1 introducer U+009B) - repaints or
+ *      ERASES legitimate output already on screen, including an install summary the
+ *      user just approved.
+ *   3. OSC 52 - writes the system clipboard, so the developer's next paste is
+ *      attacker-chosen. The only class here with an effect outside the terminal.
+ *   4. OSC 8 hyperlinks - displayed text is not the link target, aimed at the DX3
+ *      footer URL a stuck user is told to click.
+ *   5. SGR conceal/reverse - hides text and forges this CLI's own red/green
+ *      semantics.
+ *   6. Bidi overrides and isolates (Trojan Source) and zero-width characters - NO
+ *      control byte and NO escape at all, so they defeat a strip-ESC filter AND every
+ *      terminal-agnostic argument about which emulator honours which sequence.
+ *
+ * WHY C1 MATTERS EVEN THOUGH JSON HIDES ESC. Measured, not assumed: `JSON.stringify`
+ * escapes every C0 byte (ESC becomes the six inert characters backslash-u-0-0-1-b),
+ * but passes DEL, the whole C1 range - including U+009B, the 8-bit CSI introducer, as
+ * bytes c2 9b - and every bidi/zero-width character straight through. So the `--json`
+ * document a developer reads in their terminal is a partial sink, not a safe one.
+ *
+ * PORTED FROM `lib/seo/meta-text.ts`, which solved the same problem for HTML meta
+ * attributes and paid for two lessons this file inherits. It cannot be imported:
+ * packages/cli ships to npm on its own and must not reach into the app (the same
+ * constraint that makes test/footer-codes.test.ts a text-scanning parity test).
+ *
+ * WHERE TO APPLY IT, AND WHY THE ANSWER DIFFERS BY CHANNEL.
+ *
+ * For an ERROR, the right place is the trust BOUNDARY — `Api.envelope()` sanitizes
+ * `error.message` once and every CliError built from it is safe, including the ones in
+ * files that never touch `mapEnvelopeError`.
+ *
+ * For everything else it is the DISPLAY SITE, and that is not inconsistency. A server
+ * string like a manifest `path` is PRINTED and then USED: `path` names the file the
+ * installer writes and the sha256 it verifies against. Sanitizing it at the boundary
+ * would silently change the byte the integrity check runs on — the fix would become a
+ * supply-chain bug. The same is true of a `slug` that builds a URL, a `version_id` sent
+ * back to the server, and a `device_code`. So the rule is:
+ *
+ *   sanitize the FRAGMENT, at the moment it is interpolated for a human to read,
+ *   and never the value the program goes on to use.
+ *
+ * WARNING: SANITIZE THE FRAGMENT, NOT THE COMPOSED LINE. `terminalLine` collapses
+ * whitespace runs, so running it over an already-built line destroys deliberate
+ * alignment — install.ts's summary block pads its labels into columns
+ * ("  version:  v3"), and one pass over the finished string would flatten every one of
+ * them to a single space.
+ *
+ * WARNING: A `CliError` FRAGMENT STILL NEEDS `terminalLine`. The constructor backstop
+ * strips control characters, but it deliberately preserves newlines and applies no cap
+ * — so a hostile skill title inside an error message can still forge a second output
+ * line or run to a megabyte. The backstop makes an error repaint-safe; only the
+ * fragment treatment makes it BOUNDED.
+ *
+ * WARNING: EVERY INVISIBLE OR CONTROL CHARACTER IN THIS FILE IS A \uXXXX ESCAPE, AND
+ * MUST STAY ONE. A literal one is invisible in a diff, is the exact Trojan-Source
+ * shape semgrep's `contains-bidirectional-characters` rule fires on (docs/memory.md
+ * records that firing as a TRUE positive on a guard that embedded a raw U+202E), and
+ * cannot be pasted into a shell safely. Name characters by code point in prose.
+ */
+/**
+ * Trim to at most `max` CODE POINTS, marking the cut with an ellipsis.
+ *
+ * WARNING: Code points, not UTF-16 units. The predecessor iterated code points and
+ * then did `out.slice(0, 200)` on the result, so a string ending in an astral
+ * character was cut mid-pair: measured, it returned a lone high surrogate U+D83C, and
+ * `Buffer.from(out,"utf8").toString("utf8") !== out` - invalid UTF-8, emitted straight
+ * at the terminal. Emoji in a server error message is not hypothetical.
+ *
+ * The ellipsis is not decoration. A silently truncated remedy is a WRONG command the
+ * user pastes; a visibly truncated one is a command they can see is incomplete.
+ *
+ * THE CUT LANDS ON A GRAPHEME BOUNDARY ({@link graphemePrefix}). The budget is still
+ * counted in code points - the name and every caller's arithmetic stay true - but the
+ * cut backs off to the last whole grapheme that fits. WARNING: KEEPING THE JOINER
+ * CREATED A NEW WAY TO BREAK IT. Once {@link LONE_ZWJ} preserves a joiner inside an
+ * emoji, a plain code-point slice can cut that emoji in half and leave the joiner
+ * DANGLING in front of the ellipsis - the exact lone-joiner shape the rule exists to
+ * remove - or leave a couple where a family was. Grapheme segmentation handles every such
+ * case by construction (ZWJ sequences, skin tones, flag pairs, combining marks).
+ *
+ * The repaint invariant in ui.ts (`clampLine`: logical lines == physical rows) is
+ * untouched: a grapheme cut only ever lands EARLIER than the code-point cut would, so a
+ * clamped line can never get wider.
+ */
+export declare function clampCodePoints(s: string, max: number): string;
+/**
+ * Collapse untrusted text to ONE safe, bounded line. Apply this at the trust
+ * BOUNDARY - the moment a server string enters this package - never at the terminal,
+ * where it is already mixed with the CLI's own escapes.
+ *
+ * Guarantees, each pinned by test/terminal-text.test.ts:
+ *   - no C0, DEL or C1 byte survives (so no escape introducer, 8-bit forms included)
+ *   - EVERY Unicode Bidi_Control code point is removed (all 12, swept by property in
+ *     the test — not by example), plus the named zero-width and format characters
+ *     listed on INVISIBLE. Other Default_Ignorable code points (variation selectors,
+ *     Hangul fillers, Mongolian FVS) are NOT stripped and are not claimed to be:
+ *     U+FE0F is load-bearing in legitimate emoji, so removing that whole property
+ *     would corrupt real text to close a channel that cannot reorder anything.
+ *   - U+200D is removed EXCEPT where it joins two emoji elements ({@link LONE_ZWJ}):
+ *     every lone joiner goes, and every RGI emoji ZWJ sequence survives intact - the
+ *     test sweeps an engine-validated corpus of 863, not a handful of examples.
+ *   - the result contains no newline: an untrusted fragment is ONE line and cannot
+ *     forge a second one. Line structure is the CLI's to compose, never the server's.
+ *   - the result is at most `max` code points, and the clamp never splits a GRAPHEME -
+ *     so never a surrogate pair, never an emoji sequence, and never a joiner left
+ *     dangling in front of the ellipsis. (It cannot make an already ill-formed INPUT
+ *     well-formed — a lone
+ *     surrogate in the server's JSON stays one, though Node's UTF-8 encoder writes it
+ *     out as U+FFFD, so no invalid byte reaches the terminal.)
+ *
+ * Control characters become a SPACE, never nothing: "line one\nline two" must not
+ * collapse to "line oneline two". The predecessor deleted them and did exactly that -
+ * measured. The whitespace pass then folds the runs it creates.
+ */
+export declare function terminalLine(raw: string | null | undefined, max: number): string;
+/**
+ * Make already-composed text safe WITHOUT touching its line structure - the
+ * defence-in-depth backstop applied in the `CliError` constructor.
+ *
+ * Two deliberate differences from {@link terminalLine}, both load-bearing:
+ *
+ * 1. NEWLINE SURVIVES. Exactly two repo-authored CliError messages are multi-line and
+ *    both are legitimate: api.ts's 426 joins message and remedy so the remedy keeps
+ *    its own copy-pasteable line, and lifecycle.ts's batch roll-up is one indented
+ *    line per failed item. A newline-stripping backstop would jam the remedy onto the
+ *    sentence - and integration.test.ts's two separate `toContain`s would still pass
+ *    while it did.
+ *
+ * 2. NO LENGTH CAP. The `--json` batch roll-up is legitimately around 435 characters
+ *    with real temp paths; a 200-cap drops the second failure and batch-exit.test.ts
+ *    asserts two. Bounding length is the boundary's job, where the untrusted fragment
+ *    is still identifiable as untrusted.
+ *
+ * This is a BACKSTOP, not the primary control: it cannot tell an untrusted fragment
+ * from the CLI's own prose, so it can only strip what is never legitimate anywhere.
+ * A future call site that reads a new server field still owes it a `terminalLine`.
+ *
+ * THE JOINER RULE IS THE SAME HERE AS IN {@link terminalLine}, DELIBERATELY - it is NOT a
+ * third difference. Two reasons, and the first is sufficient on its own:
+ *   - This backstop runs over COMPOSED messages that already contain line-sanitised
+ *     fragments: verdicts.ts builds `${title} needs promptdock CLI ...` from a
+ *     `terminalLine`'d skill title and hands it to `new CliError`, whose constructor
+ *     calls this. A block pass that still deleted every U+200D would re-break, in every
+ *     error message, the emoji title that line mode had just preserved - the fix would
+ *     reach the install summary and silently miss every refusal.
+ *   - "Strip only what is never legitimate anywhere" IS the contextual rule. A joiner
+ *     inside an emoji sequence is legitimate text; a lone one never is.
+ */
+export declare function terminalBlock(raw: string): string;
+/**
+ * A redirect `Location`, which is a URL - the original 200, and the one call site the
+ * predecessor actually covered. Also the right cap for the device-flow
+ * `verification_url`, which is the same kind of thing.
+ */
+export declare const LOCATION_MAX = 200;
+/**
+ * A short identifying LABEL a server sends for display: a skill title or license, a
+ * handle, a slug, a role, a version string, a pairing code.
+ *
+ * 120 is the largest of those bounds, not a round number — `skills.title` is capped at
+ * 120 server-side, and everything else is smaller by construction (the slug regex
+ * `^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$` tops out at 64, the handle regex at 63, a role is a
+ * closed set, a `user_code` is the 9-character `XXXX-XXXX`). So a legitimate value is
+ * never clamped and the cap only ever bounds a hostile one.
+ */
+export declare const SERVER_LABEL_MAX = 120;
+/**
+ * A manifest file path, printed in the download list and in the refusal
+ * `assertSafeManifest` throws.
+ *
+ * 256 EXACTLY MIRRORS `validateSkillPaths` in paths.ts, which rejects any path longer
+ * than that — so this cap can never truncate a path the CLI would go on to accept, and a
+ * path being clamped here is one that was already refused.
+ */
+export declare const SERVER_PATH_MAX = 256;
+/**
+ * Server prose (`error.message`). Generous, because the point is to bound a hostile
+ * megabyte rather than to edit an honest sentence - today's longest real one is the
+ * 426's, at 67 characters.
+ */
+export declare const SERVER_MESSAGE_MAX = 500;
+/**
+ * The 426 `details.remedy` - a copy-pasteable command, so the cap needs measured
+ * headroom rather than a round number.
+ *
+ * ARITHMETIC (server side, lib/cli-auth/protocol.ts `upgradeRemedy`): the prefix
+ * "Run: npx promptdock@latest " is 27 characters and the echoed args are already
+ * allowlisted and sliced to 120 there, so a legitimate remedy tops out at 147. 256
+ * leaves room for the prefix to grow without ever truncating an honest command.
+ *
+ * WARNING: AND THE CAP IS APPLIED TO THE REMEDY ALONE, BEFORE api.ts joins it to the
+ * message. Applied after the join it would be measured against about 215 characters
+ * worst case and cut the tail off the very command the remedy exists to provide.
+ */
+export declare const SERVER_REMEDY_MAX = 256;

package/dist/terminal-text.js

@@ -0,0 +1,368 @@
+/**
+ * Terminal-output hygiene - the ONE place this package decides what an untrusted
+ * string may write to a user's terminal.
+ *
+ * WARNING: THIS FILE EXISTS BECAUSE A DOC COMMENT IS NOT A CONTRACT. Its predecessor
+ * was a private `sanitizeForTerminal` inside api.ts whose comment stated a GENERAL
+ * rule ("strip control chars before a server-supplied string reaches the terminal")
+ * while the code was applied at exactly ONE call site - the redirect Location. Five
+ * sibling sites in the same function shipped raw for the life of the file, and the
+ * comment is what stopped anyone looking. So: the rule now lives in its own module,
+ * is exported, is unit-tested against a character table, and every guarantee below is
+ * one a test pins. Do not restate a guarantee here that no test holds.
+ *
+ * THE THREAT. A hostile or MITM'd API response (a 401 needs no valid token to
+ * produce, and a captive portal can mint any status) can put terminal control
+ * sequences into a string this CLI prints. What that buys an attacker, worst first:
+ *   1. NEWLINE injection - needs no escape at all, so it survives any strip-ESC
+ *      filter. One newline in a server message forges a whole line of CLI output: a
+ *      green "installed" tick, a fake footer URL, a fake prompt.
+ *   2. CSI erase/cursor-move (ESC, or the 8-bit C1 introducer U+009B) - repaints or
+ *      ERASES legitimate output already on screen, including an install summary the
+ *      user just approved.
+ *   3. OSC 52 - writes the system clipboard, so the developer's next paste is
+ *      attacker-chosen. The only class here with an effect outside the terminal.
+ *   4. OSC 8 hyperlinks - displayed text is not the link target, aimed at the DX3
+ *      footer URL a stuck user is told to click.
+ *   5. SGR conceal/reverse - hides text and forges this CLI's own red/green
+ *      semantics.
+ *   6. Bidi overrides and isolates (Trojan Source) and zero-width characters - NO
+ *      control byte and NO escape at all, so they defeat a strip-ESC filter AND every
+ *      terminal-agnostic argument about which emulator honours which sequence.
+ *
+ * WHY C1 MATTERS EVEN THOUGH JSON HIDES ESC. Measured, not assumed: `JSON.stringify`
+ * escapes every C0 byte (ESC becomes the six inert characters backslash-u-0-0-1-b),
+ * but passes DEL, the whole C1 range - including U+009B, the 8-bit CSI introducer, as
+ * bytes c2 9b - and every bidi/zero-width character straight through. So the `--json`
+ * document a developer reads in their terminal is a partial sink, not a safe one.
+ *
+ * PORTED FROM `lib/seo/meta-text.ts`, which solved the same problem for HTML meta
+ * attributes and paid for two lessons this file inherits. It cannot be imported:
+ * packages/cli ships to npm on its own and must not reach into the app (the same
+ * constraint that makes test/footer-codes.test.ts a text-scanning parity test).
+ *
+ * WHERE TO APPLY IT, AND WHY THE ANSWER DIFFERS BY CHANNEL.
+ *
+ * For an ERROR, the right place is the trust BOUNDARY — `Api.envelope()` sanitizes
+ * `error.message` once and every CliError built from it is safe, including the ones in
+ * files that never touch `mapEnvelopeError`.
+ *
+ * For everything else it is the DISPLAY SITE, and that is not inconsistency. A server
+ * string like a manifest `path` is PRINTED and then USED: `path` names the file the
+ * installer writes and the sha256 it verifies against. Sanitizing it at the boundary
+ * would silently change the byte the integrity check runs on — the fix would become a
+ * supply-chain bug. The same is true of a `slug` that builds a URL, a `version_id` sent
+ * back to the server, and a `device_code`. So the rule is:
+ *
+ *   sanitize the FRAGMENT, at the moment it is interpolated for a human to read,
+ *   and never the value the program goes on to use.
+ *
+ * WARNING: SANITIZE THE FRAGMENT, NOT THE COMPOSED LINE. `terminalLine` collapses
+ * whitespace runs, so running it over an already-built line destroys deliberate
+ * alignment — install.ts's summary block pads its labels into columns
+ * ("  version:  v3"), and one pass over the finished string would flatten every one of
+ * them to a single space.
+ *
+ * WARNING: A `CliError` FRAGMENT STILL NEEDS `terminalLine`. The constructor backstop
+ * strips control characters, but it deliberately preserves newlines and applies no cap
+ * — so a hostile skill title inside an error message can still forge a second output
+ * line or run to a megabyte. The backstop makes an error repaint-safe; only the
+ * fragment treatment makes it BOUNDED.
+ *
+ * WARNING: EVERY INVISIBLE OR CONTROL CHARACTER IN THIS FILE IS A \uXXXX ESCAPE, AND
+ * MUST STAY ONE. A literal one is invisible in a diff, is the exact Trojan-Source
+ * shape semgrep's `contains-bidirectional-characters` rule fires on (docs/memory.md
+ * records that firing as a TRUE positive on a guard that embedded a raw U+202E), and
+ * cannot be pasted into a shell safely. Name characters by code point in prose.
+ */
+/**
+ * Invisible and bidi-reordering code points, DELETED rather than spaced - unlike a
+ * control character, replacing one with a space inserts a gap nobody wrote.
+ *
+ * WARNING: THE RANGE STOPS AT U+202E, one short of U+202F: NARROW NO-BREAK SPACE is
+ * real whitespace and must become a space, not vanish. `lib/seo/meta-text.ts` records
+ * shipping a draft that covered only U+200B-U+200F and U+2060-U+206F, so RLO
+ * (U+202E) - the one that actually reverses rendered text - sailed through while the
+ * comment claimed otherwise. Caught there by a unit test, not by review.
+ *
+ * THE TWO CLASSES NOW HOLD THE SAME MEMBERS, and packages/cli/test/zwj-parity.test.ts
+ * pins that as text. This paragraph used to say this class was WIDER than meta-text's -
+ * that meta-text skipped the bidi ISOLATES (U+2066-U+2069) and left U+FEFF to its
+ * whitespace pass. Both were true when written and both went stale on 2026-09-10, when
+ * meta-text was widened to every Bidi_Control, U+00AD and U+FEFF. A comment describing a
+ * sibling file is a claim nothing checks, which is why the parity is now a test.
+ *
+ * U+FEFF is included for a reason that holds here regardless: the whitespace pass exists
+ * only in line mode, block mode below has none, so the class has to carry it.
+ *
+ * WARNING: U+200D ZERO WIDTH JOINER IS NOT IN THIS CLASS, AND IT USED TO BE. It sat inside
+ * U+200B-U+200F, so every emoji ZWJ sequence reaching the terminal was broken: measured
+ * through the equivalent web function, the superhero went 4 code points to 3 and
+ * rendered as two glyphs, the family 5 to 3 (three separate people), the rainbow flag
+ * 4 to 3 (a flag beside a rainbow). Skill titles, author names and server messages all
+ * reach the terminal through this module, and emoji in a title are common. It is now
+ * deleted CONTEXTUALLY, by {@link LONE_ZWJ}. NEVER collapse this class back to the
+ * U+200B-U+200F range: that one edit re-adds the joiner.
+ */
+const INVISIBLE = /[\u00ad\u061c\u200b-\u200c\u200e-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/gu;
+/**
+ * A ZERO WIDTH JOINER that is not joining two emoji elements - DELETED. A joiner
+ * holding an emoji sequence together is KEPT.
+ *
+ * The rule is contextual rather than a removal from the class, because deleting a LONE
+ * joiner is still exactly right: outside an emoji sequence it is invisible padding, and
+ * "Pay" + U+200D + "Pal" becoming "PayPal" is the obfuscation this module exists to
+ * remove. A joiner survives only when its left neighbour ends an emoji element and its
+ * right neighbour starts one.
+ *
+ * WHAT MAY SIT BETWEEN THE PICTOGRAPH AND THE JOINER, and both are load-bearing. UTS #51
+ * defines a ZWJ element as a pictograph, a pictograph plus U+FE0F, or a pictograph plus
+ * a skin-tone modifier:
+ *   - U+FE0F: the rainbow flag is U+1F3F3 U+FE0F U+200D U+1F308.
+ *   - Emoji_Modifier, U+1F3FB-U+1F3FF. WARNING: THE WEB RULE THIS WAS PORTED FROM ALLOWED
+ *     ONLY U+FE0F, AND IT BROKE EVERY SKIN-TONED SEQUENCE. The Fitzpatrick modifiers are
+ *     Emoji_Modifier, not Extended_Pictographic (measured: false for all five). Against
+ *     863 ZWJ sequences validated by the engine's own RGI_Emoji data, that version broke
+ *     715 - every one carrying a skin tone. Found while porting it, fixed on both sides in
+ *     the same change; this version breaks 0. The test file sweeps that corpus for
+ *     exactly this reason.
+ *
+ * WARNING: THIS REGEX IS lib/seo/meta-text.ts's LONE_ZWJ, BYTE FOR BYTE, and
+ * test/zwj-parity.test.ts fails the build if the two ever differ. It was generated from
+ * that source rather than retyped - retyping is how a literal invisible creeps back in.
+ *
+ * Lookbehind and property escapes are u-flag features every Node >= 18 parses - but a
+ * property escape also needs ICU, which is why the regex is BUILT (see loneJoinerRule)
+ * rather than written as a literal.
+ */
+const LONE_ZWJ = loneJoinerRule();
+/**
+ * Build {@link LONE_ZWJ} WITHOUT letting a runtime that lacks ICU take the module down.
+ *
+ * WARNING: THIS IS A `new RegExp` FROM A STRING, NOT A REGEX LITERAL, AND THAT IS THE
+ * WHOLE POINT. A Node built `--with-intl=none` has no Unicode property escapes: V8
+ * rejects every `\p{...}` as an invalid regular expression. In a LITERAL that rejection
+ * happens when the file is PARSED, so it is a SyntaxError no try can catch, and in the
+ * published CLI it killed every command at load - `--help` and `--version` included -
+ * with a raw stack trace instead of a CliError (review finding, reproduced on Node 18;
+ * the CLI declares `engines: node >= 18` and no ICU requirement). Constructed from a
+ * string, the same rejection is an ordinary exception, and the rule degrades to what it
+ * was before 2026-09-10: every joiner deleted. Emoji ZWJ sequences break on such a
+ * runtime, and nothing else does.
+ *
+ * packages/cli/test/terminal-text.test.ts fails the build on any `\p{` regex LITERAL
+ * in the CLI source, because this failure mode cannot be reproduced at runtime on a
+ * build that HAS ICU - a patched RegExp constructor never sees a literal.
+ */
+function loneJoinerRule() {
+    try {
+        return new RegExp("(?<!\\p{Extended_Pictographic}(?:\\uFE0F|\\p{Emoji_Modifier})?)\\u200D|\\u200D(?!\\p{Extended_Pictographic})", "gu");
+    }
+    catch {
+        // No property escapes on this runtime (a V8 without ICU).
+        return /\u200D/gu;
+    }
+}
+/**
+ * Every escape INTRODUCER: C0 (where newline, carriage return and tab live -
+ * deliberately), DEL, and C1. Removing the introducer leaves any payload behind it as
+ * inert printable text, which is why this is a complete answer to threat classes 2-5
+ * above rather than a best-effort sequence matcher. There is no allowlist of "safe"
+ * sequences to maintain and no parser to keep in step with a terminal's.
+ */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/gu;
+/** The same class MINUS U+000A. See {@link terminalBlock} for why newline survives. */
+const CONTROL_KEEP_LF = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/gu;
+/**
+ * Trim to at most `max` CODE POINTS, marking the cut with an ellipsis.
+ *
+ * WARNING: Code points, not UTF-16 units. The predecessor iterated code points and
+ * then did `out.slice(0, 200)` on the result, so a string ending in an astral
+ * character was cut mid-pair: measured, it returned a lone high surrogate U+D83C, and
+ * `Buffer.from(out,"utf8").toString("utf8") !== out` - invalid UTF-8, emitted straight
+ * at the terminal. Emoji in a server error message is not hypothetical.
+ *
+ * The ellipsis is not decoration. A silently truncated remedy is a WRONG command the
+ * user pastes; a visibly truncated one is a command they can see is incomplete.
+ *
+ * THE CUT LANDS ON A GRAPHEME BOUNDARY ({@link graphemePrefix}). The budget is still
+ * counted in code points - the name and every caller's arithmetic stay true - but the
+ * cut backs off to the last whole grapheme that fits. WARNING: KEEPING THE JOINER
+ * CREATED A NEW WAY TO BREAK IT. Once {@link LONE_ZWJ} preserves a joiner inside an
+ * emoji, a plain code-point slice can cut that emoji in half and leave the joiner
+ * DANGLING in front of the ellipsis - the exact lone-joiner shape the rule exists to
+ * remove - or leave a couple where a family was. Grapheme segmentation handles every such
+ * case by construction (ZWJ sequences, skin tones, flag pairs, combining marks).
+ *
+ * The repaint invariant in ui.ts (`clampLine`: logical lines == physical rows) is
+ * untouched: a grapheme cut only ever lands EARLIER than the code-point cut would, so a
+ * clamped line can never get wider.
+ */
+export function clampCodePoints(s, max) {
+    if (Array.from(s).length <= max)
+        return s;
+    // One code point of the budget belongs to the ellipsis.
+    return graphemePrefix(s, Math.max(0, max - 1)) + "…";
+}
+/**
+ * The longest prefix of `s` that fits in `budget` CODE POINTS and ends on a grapheme
+ * boundary. A grapheme larger than the whole budget yields an empty prefix: half an
+ * emoji is worse than none, and the caller's ellipsis still says something was cut.
+ *
+ * `Intl.Segmenter` is read at CALL time, through `globalThis` so that a runtime with no
+ * `Intl` at all (a Node built without ICU) is covered too. A runtime without it - or one
+ * that throws constructing it - falls back to a
+ * code-point cut with any trailing joiner removed, so the no-dangling-joiner guarantee
+ * holds on BOTH paths and a test can exercise the fallback by removing the constructor.
+ * A published CLI runs on Node builds this repo never sees, so the fallback is not
+ * hypothetical, and a clamp that could throw would turn a long title into a crash.
+ *
+ * WARNING: lib/seo/meta-text.ts carries the same function for its own clamp.
+ */
+function graphemePrefix(s, budget) {
+    if (budget <= 0)
+        return "";
+    // `Intl` itself does not exist on a runtime built without ICU, so a bare `Intl.Segmenter`
+    // throws ReferenceError before the try below can help. Read it through globalThis.
+    const Segmenter = globalThis.Intl?.Segmenter;
+    if (typeof Segmenter === "function") {
+        try {
+            let out = "";
+            let used = 0;
+            for (const { segment } of new Segmenter(undefined, { granularity: "grapheme" }).segment(s)) {
+                const n = Array.from(segment).length;
+                if (used + n > budget)
+                    break;
+                out += segment;
+                used += n;
+            }
+            return out;
+        }
+        catch {
+            // A build without the break-iterator data. Fall through to the code-point cut.
+        }
+    }
+    return Array.from(s).slice(0, budget).join("").replace(/\u200D+$/u, "");
+}
+/**
+ * Collapse untrusted text to ONE safe, bounded line. Apply this at the trust
+ * BOUNDARY - the moment a server string enters this package - never at the terminal,
+ * where it is already mixed with the CLI's own escapes.
+ *
+ * Guarantees, each pinned by test/terminal-text.test.ts:
+ *   - no C0, DEL or C1 byte survives (so no escape introducer, 8-bit forms included)
+ *   - EVERY Unicode Bidi_Control code point is removed (all 12, swept by property in
+ *     the test — not by example), plus the named zero-width and format characters
+ *     listed on INVISIBLE. Other Default_Ignorable code points (variation selectors,
+ *     Hangul fillers, Mongolian FVS) are NOT stripped and are not claimed to be:
+ *     U+FE0F is load-bearing in legitimate emoji, so removing that whole property
+ *     would corrupt real text to close a channel that cannot reorder anything.
+ *   - U+200D is removed EXCEPT where it joins two emoji elements ({@link LONE_ZWJ}):
+ *     every lone joiner goes, and every RGI emoji ZWJ sequence survives intact - the
+ *     test sweeps an engine-validated corpus of 863, not a handful of examples.
+ *   - the result contains no newline: an untrusted fragment is ONE line and cannot
+ *     forge a second one. Line structure is the CLI's to compose, never the server's.
+ *   - the result is at most `max` code points, and the clamp never splits a GRAPHEME -
+ *     so never a surrogate pair, never an emoji sequence, and never a joiner left
+ *     dangling in front of the ellipsis. (It cannot make an already ill-formed INPUT
+ *     well-formed — a lone
+ *     surrogate in the server's JSON stays one, though Node's UTF-8 encoder writes it
+ *     out as U+FFFD, so no invalid byte reaches the terminal.)
+ *
+ * Control characters become a SPACE, never nothing: "line one\nline two" must not
+ * collapse to "line oneline two". The predecessor deleted them and did exactly that -
+ * measured. The whitespace pass then folds the runs it creates.
+ */
+export function terminalLine(raw, max) {
+    if (!raw)
+        return "";
+    const flat = raw
+        .replace(LONE_ZWJ, "")
+        .replace(INVISIBLE, "")
+        .replace(CONTROL, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+    return clampCodePoints(flat, max);
+}
+/**
+ * Make already-composed text safe WITHOUT touching its line structure - the
+ * defence-in-depth backstop applied in the `CliError` constructor.
+ *
+ * Two deliberate differences from {@link terminalLine}, both load-bearing:
+ *
+ * 1. NEWLINE SURVIVES. Exactly two repo-authored CliError messages are multi-line and
+ *    both are legitimate: api.ts's 426 joins message and remedy so the remedy keeps
+ *    its own copy-pasteable line, and lifecycle.ts's batch roll-up is one indented
+ *    line per failed item. A newline-stripping backstop would jam the remedy onto the
+ *    sentence - and integration.test.ts's two separate `toContain`s would still pass
+ *    while it did.
+ *
+ * 2. NO LENGTH CAP. The `--json` batch roll-up is legitimately around 435 characters
+ *    with real temp paths; a 200-cap drops the second failure and batch-exit.test.ts
+ *    asserts two. Bounding length is the boundary's job, where the untrusted fragment
+ *    is still identifiable as untrusted.
+ *
+ * This is a BACKSTOP, not the primary control: it cannot tell an untrusted fragment
+ * from the CLI's own prose, so it can only strip what is never legitimate anywhere.
+ * A future call site that reads a new server field still owes it a `terminalLine`.
+ *
+ * THE JOINER RULE IS THE SAME HERE AS IN {@link terminalLine}, DELIBERATELY - it is NOT a
+ * third difference. Two reasons, and the first is sufficient on its own:
+ *   - This backstop runs over COMPOSED messages that already contain line-sanitised
+ *     fragments: verdicts.ts builds `${title} needs promptdock CLI ...` from a
+ *     `terminalLine`'d skill title and hands it to `new CliError`, whose constructor
+ *     calls this. A block pass that still deleted every U+200D would re-break, in every
+ *     error message, the emoji title that line mode had just preserved - the fix would
+ *     reach the install summary and silently miss every refusal.
+ *   - "Strip only what is never legitimate anywhere" IS the contextual rule. A joiner
+ *     inside an emoji sequence is legitimate text; a lone one never is.
+ */
+export function terminalBlock(raw) {
+    return raw.replace(LONE_ZWJ, "").replace(INVISIBLE, "").replace(CONTROL_KEEP_LF, " ");
+}
+/**
+ * A redirect `Location`, which is a URL - the original 200, and the one call site the
+ * predecessor actually covered. Also the right cap for the device-flow
+ * `verification_url`, which is the same kind of thing.
+ */
+export const LOCATION_MAX = 200;
+/**
+ * A short identifying LABEL a server sends for display: a skill title or license, a
+ * handle, a slug, a role, a version string, a pairing code.
+ *
+ * 120 is the largest of those bounds, not a round number — `skills.title` is capped at
+ * 120 server-side, and everything else is smaller by construction (the slug regex
+ * `^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$` tops out at 64, the handle regex at 63, a role is a
+ * closed set, a `user_code` is the 9-character `XXXX-XXXX`). So a legitimate value is
+ * never clamped and the cap only ever bounds a hostile one.
+ */
+export const SERVER_LABEL_MAX = 120;
+/**
+ * A manifest file path, printed in the download list and in the refusal
+ * `assertSafeManifest` throws.
+ *
+ * 256 EXACTLY MIRRORS `validateSkillPaths` in paths.ts, which rejects any path longer
+ * than that — so this cap can never truncate a path the CLI would go on to accept, and a
+ * path being clamped here is one that was already refused.
+ */
+export const SERVER_PATH_MAX = 256;
+/**
+ * Server prose (`error.message`). Generous, because the point is to bound a hostile
+ * megabyte rather than to edit an honest sentence - today's longest real one is the
+ * 426's, at 67 characters.
+ */
+export const SERVER_MESSAGE_MAX = 500;
+/**
+ * The 426 `details.remedy` - a copy-pasteable command, so the cap needs measured
+ * headroom rather than a round number.
+ *
+ * ARITHMETIC (server side, lib/cli-auth/protocol.ts `upgradeRemedy`): the prefix
+ * "Run: npx promptdock@latest " is 27 characters and the echoed args are already
+ * allowlisted and sliced to 120 there, so a legitimate remedy tops out at 147. 256
+ * leaves room for the prefix to grow without ever truncating an honest command.
+ *
+ * WARNING: AND THE CAP IS APPLIED TO THE REMEDY ALONE, BEFORE api.ts joins it to the
+ * message. Applied after the join it would be measured against about 215 characters
+ * worst case and cut the tail off the very command the remedy exists to provide.
+ */
+export const SERVER_REMEDY_MAX = 256;

package/dist/ui.js

@@ -1,3 +1,4 @@
+import { clampCodePoints } from "./terminal-text.js";
 import { CliError, EXIT } from "./errors.js";
 import { reduceSelectKey, selectHint } from "./select-keys.js";
 /** NO_COLOR (https://no-color.org) honored: any non-empty value disables color.
@@ -78,10 +79,12 @@ export async function promptSelect(io, title, options, preselect, c, hotkeys, ho
  *  prompt's absolute paths wrap on a stock 80-col terminal). Clamping before
  *  colorization keeps logical lines == physical rows by construction. */
 function clampLine(line, columns) {
-    const max = Math.max(8, columns - 1);
-    if (line.length <= max)
-        return line;
-    return line.slice(0, max - 1) + "…";
+    // ⚠️ CODE POINTS, NOT UTF-16 UNITS. `.length`/`.slice` cut an astral character in
+    // half — measured, this returned a lone high surrogate, which is not valid UTF-8.
+    // The picker paints this straight into a repaint frame, and an emoji in a skill
+    // title is not hypothetical. Same defect `clampCodePoints` exists to prevent, so it
+    // is reused rather than re-derived.
+    return clampCodePoints(line, Math.max(8, columns - 1));
 }
 async function interactiveSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel) {
     const count = options.length;

package/dist/verdicts.d.ts

@@ -1,4 +1,7 @@
 import type { ResolveResponse } from "./contract.js";
-export declare const UPGRADE_URL = "https://promptdock.ai/pricing";
+/** ⚠️ DERIVED from `CANONICAL_ORIGIN`. This is the CTA a user follows the moment the CLI
+ *  tells them their plan is too low — the one link most likely to be clicked under
+ *  friction, so it must not spend a redirect hop. */
+export declare const UPGRADE_URL = "https://www.promptdock.ai/pricing";
 /** Throws the DX3-copy CliError for a deny verdict; returns for ok/already_entitled. */
 export declare function assertInstallable(resolve: ResolveResponse, refString: string, cliVersion: string): void;