promptdock 1.0.1 → 1.2.0

package/dist/select-keys.js

@@ -0,0 +1,113 @@
+/**
+ * Key handling for the interactive picker, as a PURE reducer.
+ *
+ * Kept out of ui.ts on purpose: the rendering half needs a real TTY (raw mode,
+ * cursor moves) and cannot be unit-tested, but the DECISIONS — what wraps, what
+ * commits, what cancels — are the part that regresses. Pure in, pure out, so
+ * every key path is pinned by a table test with no terminal involved.
+ */
+const wrap = (i, count) => ((i % count) + count) % count;
+/**
+ * One keypress → the next state, or a terminal outcome.
+ *
+ * Both input styles stay live at once, which is the whole point: arrows move the
+ * highlight, digits ALSO move it (so typing is visible before you commit), and
+ * Enter commits whichever the user last expressed. Space commits the highlight
+ * only — it is a "this one" gesture, and treating it as a number-confirm would
+ * make a half-typed "1" + Space silently pick option 1 when the user meant 12.
+ *
+ * Digits never auto-commit. `3` in a 4-item list is unambiguous and a fancier
+ * picker would fire immediately, but the user asked to KEEP number entry, and
+ * number entry means "type it, then press Enter" — auto-firing would make a
+ * two-digit list behave differently from a one-digit list.
+ *
+ * `hotkeys` (letter → option index) commit IMMEDIATELY — the confirm path
+ * passes {y:0, n:1}. Without this, `n`+Enter at a default-Yes "Install?"
+ * committed the DEFAULT: the muscle-memory answer this CLI's own [y/N]
+ * fallback trains was silently ignored and the UI executed the opposite of
+ * what the user typed (dual-review find, PTY-proven).
+ */
+export function reduceSelectKey(state, key, count, hotkeys) {
+    const name = key.name;
+    const seq = key.sequence;
+    const keep = (s) => ({ kind: "state", state: s });
+    // Raw mode swallows SIGINT, so Ctrl-C is ours to honour or the picker hangs.
+    // It carries the `signal` mark → exit 130; Esc/^D are deliberate cancels.
+    if (key.ctrl && name === "c")
+        return { kind: "cancel", signal: true };
+    if (key.ctrl && name === "d")
+        return { kind: "cancel" };
+    if (name === "escape")
+        return { kind: "cancel" };
+    // Letter hotkeys beat every other mapping except cancel — `n` must never be
+    // read as "ignored key" while the footer implies typing works.
+    if (name && !key.ctrl && !key.meta && hotkeys && hotkeys[name] !== undefined) {
+        const idx = hotkeys[name];
+        if (idx >= 0 && idx < count)
+            return { kind: "commit", index: idx };
+    }
+    if (name === "return" || name === "enter") {
+        if (state.buffer === "")
+            return { kind: "commit", index: state.index };
+        const n = Number(state.buffer);
+        if (Number.isInteger(n) && n >= 1 && n <= count)
+            return { kind: "commit", index: n - 1 };
+        return {
+            kind: "reject",
+            state: { index: state.index, buffer: "" },
+            message: `Enter a number between 1 and ${count}.`,
+        };
+    }
+    if (name === "space") {
+        // With a live digit buffer, Space means what Enter means — validate the
+        // number. Committing the stale highlight would discard the visible buffer
+        // ("Number: 12") for a row the user never named (review find).
+        if (state.buffer !== "") {
+            const n = Number(state.buffer);
+            if (Number.isInteger(n) && n >= 1 && n <= count)
+                return { kind: "commit", index: n - 1 };
+            return {
+                kind: "reject",
+                state: { index: state.index, buffer: "" },
+                message: `Enter a number between 1 and ${count}.`,
+            };
+        }
+        return { kind: "commit", index: state.index };
+    }
+    if (name === "up" || name === "k" || (key.ctrl && name === "p"))
+        return keep({ index: wrap(state.index - 1, count), buffer: "" });
+    if (name === "down" || name === "j" || (key.ctrl && name === "n"))
+        return keep({ index: wrap(state.index + 1, count), buffer: "" });
+    if (name === "home")
+        return keep({ index: 0, buffer: "" });
+    if (name === "end")
+        return keep({ index: count - 1, buffer: "" });
+    if (name === "backspace") {
+        const buffer = state.buffer.slice(0, -1);
+        const n = Number(buffer);
+        // Re-point at whatever the shortened buffer now names; keep the highlight if it names nothing.
+        const index = buffer !== "" && n >= 1 && n <= count ? n - 1 : state.index;
+        return keep({ index, buffer });
+    }
+    if (seq !== undefined && /^[0-9]$/.test(seq)) {
+        // Bounded: 3 digits names any option a 20-row picker can hold; an unbounded
+        // buffer + full-frame repaint per digit is quadratic under a digit-spam
+        // paste (codex find). Extra digits are ignored, never mis-parsed.
+        if (state.buffer.length >= 3)
+            return keep(state);
+        // Leading zeros are dropped so "0" then "3" is 3, not a dead buffer.
+        const buffer = (state.buffer + seq).replace(/^0+(?=\d)/, "");
+        const n = Number(buffer);
+        const index = n >= 1 && n <= count ? n - 1 : state.index;
+        return keep({ index, buffer });
+    }
+    return keep(state);
+}
+/** Footer hint. Mentions BOTH input styles — neither is discoverable otherwise.
+ *  `hotkeyLabel` (e.g. "y/n") leads when the picker has letter hotkeys. */
+export function selectHint(count, buffer, hotkeyLabel) {
+    if (buffer !== "")
+        return `Number: ${buffer}   ↵ confirm · ⌫ clear · esc cancel`;
+    const hot = hotkeyLabel ? `${hotkeyLabel} · ` : "";
+    return `${hot}↑↓ move · ↵/space select · 1-${count} then ↵ · esc cancel`;
+}

package/dist/ui.d.ts

@@ -1,5 +1,6 @@
 import type { CliIo } from "./context.js";
-/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color. */
+/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color.
+ *  TERM=dumb too — a terminal that can't render ANSI gets plain text. */
 export declare function colors(env: Record<string, string | undefined>, isTTY: boolean): {
     bold: (s: string) => string;
     dim: (s: string) => string;
@@ -14,9 +15,18 @@ export declare function formatCountdown(totalSecs: number): string;
 /** ~Nh retry copy for the cap verdict (mirrors the app's premium-cap copy). */
 export declare function retryHours(retryAfterSecs: number): string;
 /**
- * Numbered-list picker (TTY only — callers gate). Returns the chosen index.
- * Enter accepts the preselected default.
+ * Picker. Arrow-key driven when the terminal can do raw mode, numbered otherwise.
+ * Returns the chosen index.
+ *
+ * BOTH input styles are live in the interactive path: ↑↓ (and j/k, ^p/^n) move,
+ * ↵/space select, and typing a number still works — it moves the highlight as you
+ * type and ↵ confirms it. The numbered path below is not a lesser fallback, it is
+ * the contract for every non-TTY caller (CI, pipes, tests) and its behaviour is
+ * unchanged: Enter alone accepts the preselect.
  */
-export declare function promptSelect(io: CliIo, title: string, options: string[], preselect: number): Promise<number>;
-/** y/N confirm (TTY only — callers gate; -y bypasses upstream). */
-export declare function confirm(io: CliIo, prompt: string, def?: boolean): Promise<boolean>;
+export declare function promptSelect(io: CliIo, title: string, options: string[], preselect: number, c?: Colors, hotkeys?: Record<string, number>, hotkeyLabel?: string): Promise<number>;
+/**
+ * Confirm. Arrow-driven Yes/No when the terminal allows, y/N text otherwise.
+ * (TTY only — callers gate; -y bypasses upstream.)
+ */
+export declare function confirm(io: CliIo, prompt: string, def?: boolean, c?: Colors): Promise<boolean>;

package/dist/ui.js

@@ -1,6 +1,9 @@
-/** NO_COLOR (https://no-color.org) honored: any non-empty value disables color. */
+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.
+ *  TERM=dumb too — a terminal that can't render ANSI gets plain text. */
 export function colors(env, isTTY) {
-    const on = isTTY && !env.NO_COLOR;
+    const on = isTTY && !env.NO_COLOR && env.TERM !== "dumb";
     const wrap = (open, close) => (s) => (on ? `${open}${s}${close}` : s);
     return {
         bold: wrap("\u001b[1m", "\u001b[22m"),
@@ -28,11 +31,31 @@ export function formatCountdown(totalSecs) {
 export function retryHours(retryAfterSecs) {
     return `~${Math.max(1, Math.ceil(retryAfterSecs / 3600))}h`;
 }
+const HIDE_CURSOR = "[?25l";
+const SHOW_CURSOR = "[?25h";
+/** Above this, cursor-up repainting fights terminal scrollback — use the numbered reader. */
+const MAX_INTERACTIVE_ROWS = 20;
+const passthrough = (s) => s;
 /**
- * Numbered-list picker (TTY only — callers gate). Returns the chosen index.
- * Enter accepts the preselected default.
+ * Picker. Arrow-key driven when the terminal can do raw mode, numbered otherwise.
+ * Returns the chosen index.
+ *
+ * BOTH input styles are live in the interactive path: ↑↓ (and j/k, ^p/^n) move,
+ * ↵/space select, and typing a number still works — it moves the highlight as you
+ * type and ↵ confirms it. The numbered path below is not a lesser fallback, it is
+ * the contract for every non-TTY caller (CI, pipes, tests) and its behaviour is
+ * unchanged: Enter alone accepts the preselect.
  */
-export async function promptSelect(io, title, options, preselect) {
+export async function promptSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel) {
+    // Height gate: the frame is title + options + hint. If it doesn't fit the
+    // terminal, `ESC[NA` clamps at the top edge and repaints mangle scrollback
+    // (an 8-row tmux pane was the review's concrete case) — the numbered reader
+    // is the honest fallback there.
+    const rows = io.size?.().rows ?? 24;
+    const fits = options.length + 2 <= rows - 1;
+    if (io.rawKeys && options.length > 0 && options.length <= MAX_INTERACTIVE_ROWS && fits) {
+        return interactiveSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel);
+    }
     io.out(title);
     options.forEach((opt, i) => {
         const marker = i === preselect ? "❯" : " ";
@@ -48,8 +71,136 @@ export async function promptSelect(io, title, options, preselect) {
         io.out(`Enter a number between 1 and ${options.length}.`);
     }
 }
-/** y/N confirm (TTY only — callers gate; -y bypasses upstream). */
-export async function confirm(io, prompt, def = false) {
+/** Clamp a PLAIN (uncolored) line to the terminal width. Load-bearing for the
+ *  in-place repaint: `ESC[NA` moves PHYSICAL rows while `painted` counts
+ *  logical lines, so one soft-wrapped line desyncs every later repaint into a
+ *  trail of stale frames (3 voices + codex converged on this; the scope
+ *  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) + "…";
+}
+async function interactiveSelect(io, title, options, preselect, c, hotkeys, hotkeyLabel) {
+    const count = options.length;
+    const bold = c?.bold ?? passthrough;
+    const cyan = c?.cyan ?? passthrough;
+    const dim = c?.dim ?? passthrough;
+    const width = String(count).length;
+    let state = { index: Math.min(Math.max(preselect, 0), count - 1), buffer: "" };
+    let notice = "";
+    let painted = 0;
+    const frame = () => {
+        // Re-read the width each paint so a mid-picker resize clamps the NEXT
+        // frame correctly (past frames are already committed to scrollback).
+        const columns = io.size?.().columns ?? 80;
+        const rows = options.map((opt, i) => {
+            const num = `${i + 1}.`.padStart(width + 1);
+            const body = clampLine(`${i === state.index ? "❯" : " "} ${num} ${opt}`, columns);
+            return i === state.index ? cyan(bold(body)) : body;
+        });
+        return [
+            clampLine(title, columns),
+            ...rows,
+            dim(clampLine(notice || selectHint(count, state.buffer, hotkeyLabel), columns)),
+        ];
+    };
+    const paint = () => {
+        // Redraw in place: jump back over the previous frame, then clear-and-rewrite
+        // each line. Clearing matters — a shorter line would otherwise leave the tail
+        // of the longer one it replaced (a stale path fragment) on screen.
+        const lines = frame();
+        let out = painted > 0 ? `[${painted}A` : "";
+        for (const line of lines)
+            out += `\r${line}\n`;
+        io.write(out);
+        painted = lines.length;
+    };
+    /** On commit, COLLAPSE the frame to one summary line ("Install? Yes") instead
+     *  of leaving the whole option list + a stale hint in scrollback (review
+     *  polish item). Clears every previously painted row, writes the summary,
+     *  and parks the cursor directly under it so the CLI's next output flows on. */
+    const collapse = (chosen) => {
+        const columns = io.size?.().columns ?? 80;
+        const summary = clampLine(`${title} ${chosen}`, columns);
+        let out = painted > 0 ? `[${painted}A` : "";
+        out += `\r${cyan(summary)}\n`;
+        for (let i = 0; i < painted - 1; i++)
+            out += ``;
+        if (painted > 1)
+            out += `[${painted - 1}A\r`;
+        io.write(out);
+        painted = 1;
+    };
+    io.write(HIDE_CURSOR);
+    // Seeded with a no-op rather than null: the executor below runs synchronously so
+    // this is always replaced before the await, and a non-nullable release means the
+    // finally can never be skipped by a narrowing accident. Leaving raw mode on is
+    // the one failure here that wrecks the user's terminal after we exit.
+    let release = () => { };
+    try {
+        return await new Promise((resolve, reject) => {
+            paint();
+            // Settled guard + immediate release: `finally` runs a microtask AFTER
+            // resolve, so keys buffered in the SAME tick (a paste like "2\n1") would
+            // otherwise keep reducing and repainting a highlight that diverges from
+            // the resolved index (codex find, verified). Settle → release NOW; the
+            // finally's idempotent release stays as the belt.
+            let settled = false;
+            const settle = () => {
+                settled = true;
+                release();
+            };
+            release = io.rawKeys((key) => {
+                if (settled)
+                    return;
+                const res = reduceSelectKey(state, key, count, hotkeys);
+                if (res.kind === "cancel") {
+                    settle();
+                    reject(res.signal
+                        ? new CliError("Interrupted.", EXIT.INTERRUPT)
+                        : new CliError("Cancelled.", EXIT.USAGE));
+                    return;
+                }
+                if (res.kind === "commit") {
+                    state = { index: res.index, buffer: "" };
+                    notice = "";
+                    collapse(options[res.index]);
+                    settle();
+                    resolve(res.index);
+                    return;
+                }
+                if (res.kind === "reject") {
+                    state = res.state;
+                    notice = res.message;
+                    paint();
+                    return;
+                }
+                state = res.state;
+                notice = "";
+                paint();
+            });
+        });
+    }
+    finally {
+        // Order matters: stop consuming keys BEFORE restoring the cursor, so a key
+        // pressed during teardown cannot repaint over the restored terminal.
+        release();
+        io.write(SHOW_CURSOR);
+    }
+}
+/**
+ * Confirm. Arrow-driven Yes/No when the terminal allows, y/N text otherwise.
+ * (TTY only — callers gate; -y bypasses upstream.)
+ */
+export async function confirm(io, prompt, def = false, c) {
+    // y/n commit IMMEDIATELY (hotkeys) — the [y/N] muscle memory this CLI's own
+    // fallback trains must never be silently ignored (dual-review find: `n`+Enter
+    // at a default-Yes confirm used to run the install against a typed no).
+    if (io.rawKeys)
+        return (await promptSelect(io, prompt, ["Yes", "No"], def ? 0 : 1, c, { y: 0, n: 1 }, "y/n")) === 0;
     const suffix = def ? "[Y/n]" : "[y/N]";
     const answer = (await io.question(`${prompt} ${suffix} `)).trim().toLowerCase();
     if (answer === "")

package/dist/verdicts.d.ts

@@ -1,4 +1,4 @@
 import type { ResolveResponse } from "./contract.js";
 export declare const UPGRADE_URL = "https://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): void;
+export declare function assertInstallable(resolve: ResolveResponse, refString: string, cliVersion: string): void;

package/dist/verdicts.js

@@ -1,11 +1,53 @@
 import { CliError, EXIT } from "./errors.js";
 import { retryHours } from "./ui.js";
+import { CANONICAL_INSTALL_COMMAND, CLI_DOS_MAX_SKILL_FILES, CLI_DOS_MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
 export const UPGRADE_URL = "https://promptdock.ai/pricing";
+/** Numeric semver compare; mirrors compareCliVersions in lib/validation/skills.ts. */
+function cmpVersion(a, b) {
+    const pa = a.split(".").map((n) => Number(n) || 0);
+    const pb = b.split(".").map((n) => Number(n) || 0);
+    return (pa[0] - pb[0]) || (pa[1] - pb[1]) || (pa[2] - pb[2]);
+}
+/**
+ * PACKAGE-SCOPED compatibility, checked BEFORE the metered install POST.
+ *
+ * Two reasons this lives here and not only in `assertSafeManifest`:
+ *  1. `POST /cli/skills/{id}/install` mints an entitlement ticket under the shared
+ *     15/day premium cap. Failing after it burns one of the user's daily slots on a
+ *     provably-doomed install.
+ *  2. A package this CLI is too old to install is a POLICY refusal (EXIT.DENIED — the
+ *     code whose own doc string reads "tier, cap, denial, rate limit, version floor"),
+ *     not a supply-chain signal. `assertSafeManifest` throws EXIT.INTEGRITY because
+ *     there it means the server sent something impossible; here it means "update me".
+ *
+ * `assertSafeManifest` stays as the untrusted-server backstop — this check makes it
+ * unreachable in practice, never redundant.
+ */
+function assertPackageCompatible(resolve, cliVersion) {
+    const upgrade = `Update: ${CANONICAL_INSTALL_COMMAND} …  (or: npm i -g promptdock@latest)`;
+    const title = resolve.title ? `"${resolve.title}"` : "This skill";
+    const min = resolve.min_cli_version;
+    if (typeof min === "string" && min.length > 0 && cmpVersion(cliVersion, min) < 0) {
+        throw new CliError(`${title} needs promptdock CLI ${min} or newer — you are on ${cliVersion}.`, EXIT.DENIED, { footer: "upgrade_required", hint: upgrade });
+    }
+    // Belt and braces for a server too old to send min_cli_version: compare the shape
+    // the resolve response already reports against this CLI's own fuses.
+    const files = Number(resolve.file_count);
+    if (Number.isFinite(files) && files > CLI_DOS_MAX_SKILL_FILES) {
+        throw new CliError(`${title} has ${files} files — this CLI installs at most ${CLI_DOS_MAX_SKILL_FILES}.`, EXIT.DENIED, { footer: "upgrade_required", hint: upgrade });
+    }
+    const total = Number(resolve.total_bytes);
+    if (Number.isFinite(total) && total > CLI_DOS_MAX_SKILL_TOTAL_BYTES) {
+        const mb = (n) => `${(n / (1024 * 1024)).toFixed(1)}MB`;
+        throw new CliError(`${title} is ${mb(total)} — this CLI installs at most ${mb(CLI_DOS_MAX_SKILL_TOTAL_BYTES)}.`, EXIT.DENIED, { footer: "upgrade_required", hint: upgrade });
+    }
+}
 /** Throws the DX3-copy CliError for a deny verdict; returns for ok/already_entitled. */
-export function assertInstallable(resolve, refString) {
+export function assertInstallable(resolve, refString, cliVersion) {
     switch (resolve.verdict) {
         case "ok":
         case "already_entitled":
+            assertPackageCompatible(resolve, cliVersion);
             return;
         case "not_found":
             throw new CliError(`skill not found: ${refString} — check the ref (the format is handle/slug; a pasted promptdock.ai skill URL also works)`, EXIT.DENIED, { footer: "not_found" });

package/package.json

@@ -1,28 +1,46 @@
 {
   "name": "promptdock",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Install AI agent skills from PromptDock — npx promptdock@latest install <handle>/<slug>",
-  "keywords": ["promptdock", "skills", "ai", "agents", "claude", "cli"],
+  "keywords": [
+    "promptdock",
+    "skills",
+    "ai",
+    "agents",
+    "claude",
+    "cli"
+  ],
   "homepage": "https://promptdock.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/klicklabs/promptdock.ai.git",
     "directory": "packages/cli"
   },
-  "bugs": { "url": "https://promptdock.ai/docs/cli/errors" },
-  "license": "UNLICENSED",
+  "bugs": {
+    "url": "https://promptdock.ai/docs/cli/errors"
+  },
+  "license": "MIT",
   "type": "module",
-  "bin": { "promptdock": "dist/index.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=18" },
+  "bin": {
+    "promptdock": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "test": "npm run typecheck && vitest run",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.test.json"
   },
   "devDependencies": {
     "@types/node": "^20",
     "typescript": "^5",
     "vitest": "^4.1.8"
-  }
+  },
+  "gitHead": "53545d74fc0baeec63684c96b49134e93625d63a"
 }