promptdock 1.2.1-rc.15.1 → 1.2.2

package/README.md

@@ -7,7 +7,9 @@ Codex, Gemini CLI, Cursor, GitHub Copilot, and more.
 npx promptdock@latest install <handle>/<slug>
 ```
 
-## 60-second quickstart
+## Quickstart
+
+Signed in: about 1-2 minutes. New account by email: about 2-5 minutes.
 
 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,
@@ -19,17 +21,17 @@ 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.
+#    confirm the email it sends, then enter the code from your terminal if the
+#    page asks for it. 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 /<slug>
 ```
 
 **Auth model, stated plainly: login is required.** A free PromptDock account
-installs free skills — no card, no subscription. Premium skills need the
-Explorer plan ($10/mo) or higher. `login` opens your browser; you approve a
-one-time code and the terminal continues. The token lives in
+installs free skills — no card, no subscription. Premium skills come with any
+paid plan ([pricing](https://www.promptdock.ai/pricing)). `login` opens your
+browser; you approve a one-time code and the terminal continues. The token lives in
 `~/.promptdock/config.json` (owner-only permissions; on Windows the user
 profile's ACL is the boundary).
 
@@ -42,11 +44,13 @@ profile's ACL is the boundary).
 | `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) |
-| `update [ref] [--all] [--check]` | Update to the latest approved version (`upgrade` is an alias) |
+| `update [ref] [--all] [--check]` | Update installed skills to the latest approved version (`upgrade` is an alias; it updates skills, not this CLI: `npm i -g promptdock@latest`) |
 | `list [--json] [-g] [--all]` | Show installed skills |
 
 Install options: `-g/--global` (per-user dir), `--target <tool>`, `--dir <path>`,
-`-y/--yes` (skip prompts — **never** implies `--force`), `--force`, `--dry-run`
+`-y/--yes` (skip prompts — **never** implies `--force`), `--force` (replace the files
+you edited and your files at paths the new version ships, keeping every other file
+you added; or replace another skill's folder, listing what it removed), `--dry-run`
 (print the plan, install nothing), `--json`.
 
 Update/uninstall options: `--check` (update only — report, apply nothing), `--all`,
@@ -149,19 +153,25 @@ confirms from painting a picker over your JSON.
 | --- | --- |
 | `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 }` |
+| `install --json` | `{ installed: true, update, ref, version, version_id, target, path, files, kept_files, replaced?, removed? }` — `replaced` under `--force`, `removed` when another skill's folder was replaced |
+| `install --json` (nothing to do) | `{ installed: false, up_to_date: true, update: true, ref, version, version_id, target, path, changes? }` |
+| `install --dry-run --json` | `{ dry_run: true, ref, skill_id, version_id, version, title, author, is_free, file_count, total_bytes, target, path, update, changes? }` |
 | `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? }`:
+A `results` row is `{ ref, dir, status, reason?, failed?, exit?, code?, changes?, kept_files?, replaced?, 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.
+- `code` — that failure's docs anchor (`local_changes`, `download`, …), from 1.2.2.
+- `changes` — `[{ path, reason }]` for the local changes that blocked (or, on an
+  `available` row from `--check`, that would block); `reason` is `modified`,
+  `path_conflict` or `not_regular_file`.
+- `kept_files` / `replaced` — on an `updated` row: the files of yours that were kept,
+  and what `--force` replaced.
 - `from`/`to` — version numbers, on `update` rows only.
 
 A **failure** that produced no report of its own is written to stdout as one document:
@@ -170,6 +180,8 @@ A **failure** that produced no report of its own is written to stdout as one doc
 { "error": { "code": "existing_dir", "message": "…", "exit_code": 5, "doc_url": "https://www.promptdock.ai/docs/cli/errors#existing_dir" } }
 ```
 
+A `local_changes` refusal adds `"changes": [{ "path", "reason" }]` to `error`.
+
 `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
@@ -189,15 +201,24 @@ skill id, ref, version, and the sha256 of every installed file. It is the
   project; `-g` the global scope; `--all` both.
 - `uninstall` removes **only** files the receipt lists, then the receipt, then
   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.
+- `install` and `update` **keep the files you added** (and your folders and links,
+  which are never followed) when they install a new version.
+- If you **edited** installed files, or put a file of yours where the new version
+  ships one, `install`, `update` and `uninstall` stop with exit 4 and change nothing.
+  The message lists each file with its reason and both ways out: move the files out
+  and run the same command again, or add `--force`, which replaces the listed files
+  and keeps every other file you added. Line endings alone (a CRLF checkout) are not
+  an edit.
 - 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**
-("integrity check failed — nothing installed").
+("integrity check failed — nothing installed"). Files download into a temporary
+folder above the skills folder, so an interrupted install never leaves a half-copied
+skill where your agent looks for skills; Ctrl-C removes it, and if an update is cut
+off mid-swap the next promptdock command puts your folder back.
 
 ## Exit codes & errors
 
@@ -207,10 +228,10 @@ path is re-validated before any write; a failed check aborts **all-or-nothing**
 | 1 | usage (bad flags, missing `--target`/`-y` in CI) |
 | 2 | auth (not logged in / token rejected) |
 | 3 | denied (tier gate, daily cap, denial, rate limit, version floor, not found) |
-| 4 | integrity (sha mismatch, unsafe manifest path, receipt schema) |
+| 4 | integrity or a local-safety conflict: checksum, unsafe path, receipt schema or local changes (an edited file, a file where the new version ships one, a special file) that an install or update would otherwise destroy |
 | 5 | filesystem (permissions, disk space, non-empty directory) |
-| 6 | network |
-| 130 | interrupted (`Ctrl-C` during an interactive prompt; `Esc` — a deliberate in-UI cancel — exits 1) |
+| 6 | network (including a connection that drops mid-download) |
+| 130 | interrupted (`Ctrl-C` during a prompt or a download; `Esc` — a deliberate in-UI cancel — exits 1) |
 
 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.
@@ -252,11 +273,36 @@ updates everything else and then exits `3` for the one it could not do (see
 
 - Node.js ≥ 18. Zero runtime dependencies.
 - The CLI always installs the **latest approved** version of a skill (no semver
-  pinning); every published skill has passed PromptDock's human review queue.
-  Review is a screening step, not a warranty — read what you install.
+  pinning). Skills that members submit are reviewed by a person before they go
+  live; review is a screening step, not a warranty — read what you install.
 - Skills are plain files on your machine after install; premium gates access,
   not copying.
 
+## Changes
+
+- **1.2.2:**
+  - `install` refuses to overwrite files you edited (exit 4). Before, it exited 0
+    and the edits were lost.
+  - `install` and `update` keep the files you added; before, they deleted them.
+  - A connection that drops during a download exits 6 (was 1) and names the file;
+    expired download links are refreshed once, by themselves.
+  - CRLF checkouts no longer count as edits.
+  - Temporary files live above the skills folder; Ctrl-C removes them, and the next
+    command restores a folder an interrupted update set aside.
+  - `promptdock upgrade` says it updates your skills, not the CLI.
+  - The receipt schema stays 1.
+  - Why older versions are refused for installs and updates: promptdock 1.2.1 and
+    older can overwrite files you edited and delete files you added when they update
+    a skill, so installing and updating need 1.2.2 or later; login, list and
+    uninstall still work. 1.2.1's `update --all` prints that refusal once per
+    installed skill.
+  - Did 1.2.1 overwrite your edits? Re-running `install` over an edited skill
+    replaced the edited files and deleted the ones you had added. Compare the folder
+    with your version control.
+- **1.2.1:** the premium refusal names no price: "Premium skills come with any
+  paid plan", with the pricing link (the old "$10/mo" was wrong in euros and
+  rupees).
+
 ## License
 
 [MIT](./LICENSE) © Prompt Dock, Inc.

package/dist/auth.js

@@ -34,13 +34,19 @@ export async function deviceFlowLogin(ctx, baseUrl, opts) {
             ctx.openUrl(start.verification_url);
             ctx.io.out("(if the page didn't open, paste the URL into your browser)");
         }
-        ctx.io.out("");
         // Clamp through Number.isFinite (review find): a missing/renamed numeric in
         // the start response made `deadline` NaN, and `remainMs <= 0` is FALSE for
         // NaN — an infinite countdown spin. A malformed numeric now degrades to the
         // protocol defaults instead of hanging the login.
         const expiresIn = Number(start.expires_in);
-        const deadline = ctx.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 600) * 1000;
+        const lifetimeSecs = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 600;
+        // DX-A4: a member signing up on that page confirms their email first, and the
+        // confirmation link can land them on a page that asks for this code. Say so here,
+        // where they still have the code in front of them.
+        const minutes = Math.max(1, Math.floor(lifetimeSecs / 60));
+        ctx.io.out(`New here? Sign up on that page and confirm your email. If a page then asks for a code, enter ${terminalLine(start.user_code, SERVER_LABEL_MAX)}. This terminal waits up to ${minutes} ${minutes === 1 ? "minute" : "minutes"}.`);
+        ctx.io.out("");
+        const deadline = ctx.now() + lifetimeSecs * 1000;
         const interval0 = Number(start.interval);
         let intervalSecs = Number.isFinite(interval0) && interval0 > 0 ? interval0 : 5;
         poll: for (;;) {

package/dist/commands/install.js

@@ -9,6 +9,8 @@ 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 { sweepAndReport, tempRootsFor } from "../leftovers.js";
+import { changeRows, changesJson, defaultPathKey, forceLines, keptLine, localChangesRefusal, receiptSideChanges, unlistedEntries, } from "../local-changes.js";
 import { formatRef, parseSkillRef } from "../ref.js";
 import { detectionLabel, detectTargets, detectTargetsAnyScope, nextStepLine, scopeChoices, targetById, targetInstallDir, TARGETS, } from "../registry.js";
 import { readReceipt } from "../receipts.js";
@@ -37,6 +39,10 @@ export async function runInstall(ctx, positionals, flags) {
     }
     // ── target resolution (D-UX11) ─────────────────────────────────────────────
     const picked = await resolveTarget(ctx, flags, ref);
+    // An interrupted install or update may have left this skill's folder set aside: put it
+    // back BEFORE reading its receipt (ENG-A4). A dry run writes nothing, so it skips this.
+    if (!dryRun)
+        sweepAndReport(ctx, tempRootsFor(picked.dir));
     // ── receipt awareness (DX3/DX5) ────────────────────────────────────────────
     const existing = readReceipt(picked.dir);
     if (existing.kind === "newer_schema") {
@@ -46,26 +52,15 @@ export async function runInstall(ctx, positionals, flags) {
         ? existing.receipt
         : null;
     const isUpdate = matching !== null;
-    if (!isUpdate && !dryRun && flags.force !== true && dirIsNonEmpty(picked.dir)) {
-        // The ONLY error whose remedy is --force (DX3).
-        const what = existing.kind === "ok" ? `a different skill (${existing.receipt.ref})` : "files";
-        throw new CliError(`${picked.dir} already exists and contains ${what} — pass --force to replace it`, EXIT.IO, { footer: "existing_dir" });
-    }
-    if (isUpdate && matching.version_id === resolve.version_id && flags.force !== true && !dryRun) {
-        ctx.io.out(json
-            ? 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;
-    }
+    const force = flags.force === true;
+    const occupied = dirIsNonEmpty(picked.dir);
+    const existingTarget = matching
+        ? { kind: "update", receipt: matching }
+        : !occupied
+            ? { kind: "none" }
+            : existing.kind === "ok"
+                ? { kind: "foreign", receipt: existing.receipt }
+                : { kind: "unmanaged" };
     // ⚠️ 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.
@@ -82,6 +77,56 @@ export async function runInstall(ctx, positionals, flags) {
     // 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);
+    // ── local changes the receipt can see (I1, DX-A1): before the confirm prompt and
+    // before the metered install request. Reads only, so a dry run reports them too.
+    const localChanges = matching
+        ? receiptSideChanges(picked.dir, matching, unlistedEntries(picked.dir, matching, defaultPathKey(ctx.platform)))
+        : [];
+    if (!isUpdate && !dryRun && !force && occupied) {
+        // The ONLY error whose remedy is --force (DX3). What --force does differs by what is
+        // there (DX-A1): another skill's folder is replaced and listed; files with no receipt
+        // (what an uninstall that kept your files leaves) are kept.
+        throw new CliError(existing.kind === "ok"
+            ? `${picked.dir} already holds a different skill (${terminalLine(existing.receipt.ref, SERVER_LABEL_MAX)}) — pass --force to replace it (the CLI lists what it removes)`
+            : `${picked.dir} already exists and contains files — pass --force to install into it; your files are kept unless the new version ships the same path`, EXIT.IO, { footer: "existing_dir" });
+    }
+    if (isUpdate && matching.version_id === resolve.version_id && !force && !dryRun) {
+        if (json) {
+            ctx.io.out(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,
+                ...(localChanges.length > 0 ? { changes: changesJson(localChanges) } : {}),
+            }));
+            return;
+        }
+        if (localChanges.length === 0) {
+            ctx.io.out(`"${safeTitle}" is already up to date (v${ver(matching.version)}) at ${safeDir} — use --force to reinstall.`);
+            return;
+        }
+        // DX-A1: a member with edits is NOT sent straight to the flag that replaces them.
+        const k = localChanges.length;
+        ctx.io.out(`"${safeTitle}" is up to date (v${ver(matching.version)}) at ${safeDir}, with ${k} local ${k === 1 ? "change" : "changes"}:`);
+        for (const row of changeRows(localChanges, null))
+            ctx.io.out(row);
+        ctx.io.out("--force would replace them and keep every other file you added.");
+        return;
+    }
+    if (isUpdate && localChanges.length > 0 && !force && !dryRun) {
+        throw localChangesRefusal({
+            verb: "install",
+            title: safeTitle,
+            from: ver(matching.version),
+            to: ver(resolve.version),
+            dir: picked.dir,
+            changes: localChanges,
+        });
+    }
     // ── summary block (D-UX11 confirm-before-write) ────────────────────────────
     const summary = [];
     if (isUpdate) {
@@ -113,11 +158,18 @@ export async function runInstall(ctx, positionals, flags) {
                 target: picked.id,
                 path: picked.dir,
                 update: isUpdate,
+                ...(localChanges.length > 0 ? { changes: changesJson(localChanges) } : {}),
             }));
             return;
         }
         for (const line of summary)
             ctx.io.out(line);
+        if (localChanges.length > 0 && !force && matching?.version_id !== resolve.version_id) {
+            const k = localChanges.length;
+            ctx.io.out(`${k} local ${k === 1 ? "change" : "changes"} would block this install:`);
+            for (const row of changeRows(localChanges, ver(resolve.version)))
+                ctx.io.out(row);
+        }
         ctx.io.out("");
         ctx.io.out(c.dim("Dry run — nothing was installed (the file list is fetched and verified at install)."));
         return;
@@ -136,31 +188,44 @@ export async function runInstall(ctx, positionals, flags) {
         }
     }
     // ── two-phase install ──────────────────────────────────────────────────────
-    const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolve.skill_id}/install`, { version_id: resolve.version_id });
-    const resp = checkInstallResponse(respRaw);
-    if (!json) {
-        ctx.io.out(`Downloading ${resp.manifest.length} files…`);
-        const shown = resp.manifest.slice(0, 8);
-        // ⚠️ 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`));
-        }
-    }
-    const receipt = await performInstall(ctx, api, {
+    // The same POST serves I9's one re-sign: `record_skill_install` is idempotent per
+    // member and skill, so a second call refreshes the links and records nothing new.
+    const postInstall = async () => checkInstallResponse(await api.request("POST", `/api/v1/cli/skills/${resolve.skill_id}/install`, {
+        version_id: resolve.version_id,
+    }));
+    const resp = await postInstall();
+    const outcome = await performInstall(ctx, api, {
         resp,
         targetDir: picked.dir,
         targetId: picked.id,
         refString,
-        prior: matching ?? undefined,
+        existing: existingTarget,
+        force,
+        verb: "install",
+        title: safeTitle,
+        resign: postInstall,
+        onDownload: json
+            ? undefined
+            : (r) => {
+                ctx.io.out(`Downloading ${r.manifest.length} files…`);
+                const shown = r.manifest.slice(0, 8);
+                // ⚠️ 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.
+                // These are printed BEFORE `assertSafeManifest` validates them, 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 (r.manifest.length > shown.length) {
+                    ctx.io.out(c.dim(`  +${r.manifest.length - shown.length} more`));
+                }
+            },
     });
+    const { receipt } = outcome;
+    for (const w of outcome.warnings)
+        ctx.io.err(`${c.yellow("!")} ${w}`);
     if (json) {
         ctx.io.out(JSON.stringify({
             installed: true,
@@ -171,11 +236,19 @@ export async function runInstall(ctx, positionals, flags) {
             target: picked.id,
             path: picked.dir,
             files: receipt.files.length,
+            kept_files: outcome.kept,
+            ...(force ? { replaced: outcome.replaced.map(({ path, reason }) => ({ path, reason })) } : {}),
+            ...(outcome.removed.length > 0 ? { removed: outcome.removed } : {}),
         }));
         return;
     }
     ctx.io.out("");
-    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(`${c.green("✓")} ${isUpdate ? "Updated" : "Installed"} "${terminalLine(resp.skill.title, SERVER_LABEL_MAX)}" v${terminalLine(String(receipt.version), SERVER_LABEL_MAX)} → ${terminalLine(picked.dir, SERVER_PATH_MAX)}`);
+    const kept = keptLine(outcome.kept);
+    if (kept)
+        ctx.io.out(kept);
+    for (const line of forceLines(outcome.replaced, outcome.removed))
+        ctx.io.out(line);
     ctx.io.out(nextStepLine(picked.id, resp.skill.slug));
 }
 /**