promptdock 1.2.1 → 1.2.2

package/dist/commands/lifecycle.js

@@ -7,6 +7,8 @@ import { ensureAuth } from "../auth.js";
 import { CliError, EXIT, mapFsError, usageError } from "../errors.js";
 import { SERVER_LABEL_MAX, SERVER_PATH_MAX, terminalLine } from "../terminal-text.js";
 import { checkInstallResponse, performInstall } from "../installer.js";
+import { sweepAndReport, sweepRoots } from "../leftovers.js";
+import { changeRows, changesJson, defaultPathKey, forceLines, keptLine, localChangesRefusal, receiptSideChanges, unlistedEntries, } from "../local-changes.js";
 import { formatRef, parseSkillRef } from "../ref.js";
 import { modifiedFiles, readReceipt, scanReceipts, RECEIPT_NAME, } from "../receipts.js";
 import { colors, confirm } from "../ui.js";
@@ -50,6 +52,15 @@ function shellArg(value) {
 export function newerSchemaError(dir, schema, rerun) {
     return new CliError(`${dir} was installed by a newer promptdock CLI (receipt schema ${schema}). Run: ${rerun}`, EXIT.INTEGRITY, { footer: "receipt_schema" });
 }
+/** The failure half of a result row: the old `failed`/`exit` plus 1.2.2's `code`/`changes`. */
+function failedRow(error) {
+    return {
+        failed: true,
+        exit: error.exitCode,
+        code: error.code,
+        ...(error.changes ? { changes: error.changes } : {}),
+    };
+}
 /**
  * Turn per-item failures into the process's exit.
  *
@@ -85,7 +96,13 @@ alreadyPrinted) {
             ? "1 item failed (see above)."
             : `${failures.length} items failed (see above).`, first.exitCode, {
             footer,
-            hint: failures.length === 1 ? first.hint : "pass --allow-partial to exit 0 when some items fail",
+            hint: failures.length === 1
+                ? first.hint
+                : // Every local-changes refusal carries the same two ways out (1.2.2), so a batch
+                    // of them keeps that hint rather than losing it to the generic one.
+                    failures.every((f) => f.error.changes) && first.hint
+                        ? `${first.hint}\npass --allow-partial to exit 0 when some items fail`
+                        : "pass --allow-partial to exit 0 when some items fail",
         });
     }
     // --json: the per-item lines were never printed (stdout must stay parseable), so
@@ -100,6 +117,21 @@ alreadyPrinted) {
 function asCliError(err, exitCode) {
     return err instanceof CliError ? err : new CliError(String(err), exitCode);
 }
+/** The temporary-folder roots a lifecycle command sweeps before it reads a receipt. */
+function rootsFor(ctx, flags) {
+    const dir = typeof flags.dir === "string"
+        ? isAbsolute(flags.dir)
+            ? flags.dir
+            : resolvePath(ctx.cwd, flags.dir)
+        : undefined;
+    return sweepRoots({
+        cwd: ctx.cwd,
+        home: ctx.home,
+        scope: scopeOf(flags),
+        targetId: typeof flags.target === "string" ? flags.target : undefined,
+        dir,
+    });
+}
 /** Collect the receipts a lifecycle command operates on. */
 function collect(ctx, flags, refArg) {
     if (typeof flags.dir === "string") {
@@ -135,6 +167,7 @@ export async function runUninstall(ctx, positionals, flags) {
     const c = colors(ctx.env, ctx.io.isTTY);
     const json = flags.json === true;
     const allowPartial = flags["allow-partial"] === true;
+    sweepAndReport(ctx, rootsFor(ctx, flags));
     const items = collect(ctx, flags, refArg);
     const rerun = rerunCommand("uninstall", positionals, flags);
     const removed = [];
@@ -159,10 +192,19 @@ export async function runUninstall(ctx, positionals, flags) {
                     throw new CliError(`${item.dir} has an unreadable receipt — refusing to guess what to delete (remove the directory manually if you're sure)`, EXIT.INTEGRITY, { footer: "receipt_invalid" });
                 }
                 const receipt = item.read.receipt;
-                // DX5 local-edit guard: human work never dies to a default.
+                // DX5 local-edit guard: human work never dies to a default. A missing file is
+                // not a change (nothing is lost by not deleting it), and line endings alone never
+                // count (I8).
                 const modified = modifiedFiles(item.dir, receipt).filter((p) => existsSync(join(item.dir, p)));
                 if (modified.length > 0 && flags.force !== true) {
-                    throw new CliError(`local changes in ${modified.length} file(s) under ${item.dir} (${modified.slice(0, 3).join(", ")}${modified.length > 3 ? ", …" : ""}) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" });
+                    throw localChangesRefusal({
+                        verb: "uninstall",
+                        title: terminalLine(receipt.ref, SERVER_LABEL_MAX),
+                        from: terminalLine(String(receipt.version), SERVER_LABEL_MAX),
+                        to: null,
+                        dir: item.dir,
+                        changes: modified.map((path) => ({ path, reason: "modified" })),
+                    });
                 }
                 if (flags.yes !== true) {
                     if (!ctx.io.isTTY)
@@ -192,7 +234,7 @@ export async function runUninstall(ctx, positionals, flags) {
                     // is a verdict on the RUN. The row is still recorded FIRST so the --json
                     // report names the cause instead of handing the caller an empty `results`.
                     const fatal = asCliError(err, EXIT.INTEGRITY);
-                    results.push({ ref: label, dir: item.dir, status: "skipped", reason: fatal.message, failed: true, exit: fatal.exitCode });
+                    results.push({ ref: label, dir: item.dir, status: "skipped", reason: fatal.message, ...failedRow(fatal) });
                     throw fatal;
                 }
                 const error = asCliError(err, EXIT.INTEGRITY);
@@ -203,7 +245,7 @@ export async function runUninstall(ctx, positionals, flags) {
                 if (items.length === 1 && !allowPartial && !json)
                     throw error;
                 failures.push({ ref: label, error });
-                results.push({ ref: label, dir: item.dir, status: "skipped", reason: error.message, failed: true, exit: error.exitCode });
+                results.push({ ref: label, dir: item.dir, status: "skipped", reason: error.message, ...failedRow(error) });
                 if (!json)
                     ctx.io.err(`${c.yellow("!")} ${label}: ${error.message}`);
             }
@@ -303,6 +345,9 @@ export async function runUpdate(ctx, positionals, flags) {
     const checkOnly = flags.check === true;
     const json = flags.json === true;
     const allowPartial = flags["allow-partial"] === true;
+    // `--check` is a report and writes nothing, so it leaves leftovers to the next command.
+    if (!checkOnly)
+        sweepAndReport(ctx, rootsFor(ctx, flags));
     const items = collect(ctx, flags, positionals[0]);
     if (items.length === 0) {
         // ⚠️ THE SAME SHAPE AS EVERY OTHER RUN. This branch used to print
@@ -328,7 +373,7 @@ export async function runUpdate(ctx, positionals, flags) {
      */
     const recordFatal = (ref, dir, from, to, err) => {
         const fatal = asCliError(err, EXIT.AUTH);
-        report.push({ ref, dir, from, to, status: "skipped", reason: fatal.message, failed: true, exit: fatal.exitCode });
+        report.push({ ref, dir, from, to, status: "skipped", reason: fatal.message, ...failedRow(fatal) });
         return fatal;
     };
     /** Record a per-item failure; rethrow when this is not a batch at all. */
@@ -343,7 +388,7 @@ export async function runUpdate(ctx, positionals, flags) {
         if (items.length === 1 && !allowPartial && !json)
             throw error;
         failures.push({ ref, error });
-        report.push({ ref, dir, from, to, status: "skipped", reason: error.message, failed: true, exit: error.exitCode });
+        report.push({ ref, dir, from, to, status: "skipped", reason: error.message, ...failedRow(error) });
         if (!json)
             ctx.io.err(`${c.yellow("!")} ${ref}: ${error.message}`);
     };
@@ -376,17 +421,41 @@ export async function runUpdate(ctx, positionals, flags) {
                 continue;
             }
             const toVersion = Number(resolved.version) || 0;
+            const title = terminalLine(resolved.title, SERVER_LABEL_MAX) || terminalLine(receipt.ref, SERVER_LABEL_MAX);
+            // I1/DX-A1: the changes the receipt can see, before the confirm prompt and before
+            // the metered install request. Reads only, so `--check` reports them too.
+            const localChanges = receiptSideChanges(item.dir, receipt, unlistedEntries(item.dir, receipt, defaultPathKey(ctx.platform)));
             if (checkOnly) {
-                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: toVersion, status: "available" });
-                if (!json)
+                report.push({
+                    ref: receipt.ref,
+                    dir: item.dir,
+                    from: receipt.version,
+                    to: toVersion,
+                    status: "available",
+                    ...(localChanges.length > 0 ? { changes: changesJson(localChanges) } : {}),
+                });
+                if (!json) {
                     ctx.io.out(`${c.cyan("↑")} ${receipt.ref}: v${receipt.version} → v${toVersion} available`);
+                    if (localChanges.length > 0 && flags.force !== true) {
+                        const k = localChanges.length;
+                        ctx.io.out(`  ${k} local ${k === 1 ? "change" : "changes"} would block this update:`);
+                        for (const row of changeRows(localChanges, String(toVersion)))
+                            ctx.io.out(`  ${row}`);
+                    }
+                }
                 continue;
             }
             // DX5 local-edit guard BEFORE any overwrite. A block is a FAILURE, not a
             // shrug: the skill stays behind and someone has to decide what to do about it.
-            const modified = modifiedFiles(item.dir, receipt);
-            if (modified.length > 0 && flags.force !== true) {
-                fail(receipt.ref, item.dir, receipt.version, toVersion, new CliError(`local changes in ${modified.length} file(s) — copy your changes out first, then re-run with --force`, EXIT.INTEGRITY, { footer: "local_changes" }));
+            if (localChanges.length > 0 && flags.force !== true) {
+                fail(receipt.ref, item.dir, receipt.version, toVersion, localChangesRefusal({
+                    verb: "update",
+                    title,
+                    from: terminalLine(String(receipt.version), SERVER_LABEL_MAX),
+                    to: terminalLine(String(toVersion), SERVER_LABEL_MAX),
+                    dir: item.dir,
+                    changes: localChanges,
+                }));
                 continue;
             }
             if (flags.yes !== true) {
@@ -424,19 +493,47 @@ export async function runUpdate(ctx, positionals, flags) {
              * Genuinely fatal classes still propagate — a usage error or a newer-schema receipt
              * is not something the next item can recover from either.
              */
+            const skillId = resolved.skill_id;
+            const versionId = resolved.version_id;
+            // The same POST serves I9's one re-sign (`record_skill_install` is idempotent per
+            // member and skill, so it records nothing new).
+            const postInstall = async () => checkInstallResponse(await api.request("POST", `/api/v1/cli/skills/${skillId}/install`, {
+                version_id: versionId,
+            }));
             try {
-                const respRaw = await api.request("POST", `/api/v1/cli/skills/${resolved.skill_id}/install`, { version_id: resolved.version_id });
-                const resp = checkInstallResponse(respRaw);
-                await performInstall(ctx, api, {
+                const resp = await postInstall();
+                const outcome = await performInstall(ctx, api, {
                     resp,
                     targetDir: item.dir,
                     targetId: item.targetId,
                     refString: receipt.ref,
-                    prior: receipt,
+                    existing: { kind: "update", receipt },
+                    force: flags.force === true,
+                    verb: "update",
+                    title,
+                    resign: postInstall,
                 });
-                report.push({ ref: receipt.ref, dir: item.dir, from: receipt.version, to: resp.skill.version, status: "updated" });
-                if (!json)
-                    ctx.io.out(`${c.green("✓")} ${receipt.ref}: v${receipt.version} → v${resp.skill.version}`);
+                report.push({
+                    ref: receipt.ref,
+                    dir: item.dir,
+                    from: receipt.version,
+                    to: outcome.receipt.version,
+                    status: "updated",
+                    kept_files: outcome.kept,
+                    ...(flags.force === true
+                        ? { replaced: outcome.replaced.map(({ path, reason }) => ({ path, reason })) }
+                        : {}),
+                });
+                for (const w of outcome.warnings)
+                    ctx.io.err(`${c.yellow("!")} ${w}`);
+                if (!json) {
+                    ctx.io.out(`${c.green("✓")} ${receipt.ref}: v${receipt.version} → v${outcome.receipt.version}`);
+                    const kept = keptLine(outcome.kept);
+                    if (kept)
+                        ctx.io.out(`  ${kept}`);
+                    for (const line of forceLines(outcome.replaced, []))
+                        ctx.io.out(`  ${line}`);
+                }
             }
             catch (err) {
                 fail(receipt.ref, item.dir, receipt.version, toVersion, err);
@@ -461,6 +558,7 @@ export async function runUpdate(ctx, positionals, flags) {
 /* ── list ───────────────────────────────────────────────────────────────────── */
 export async function runList(ctx, flags) {
     const scope = scopeOf(flags);
+    sweepAndReport(ctx, sweepRoots({ cwd: ctx.cwd, home: ctx.home, scope }));
     const items = scanReceipts({ cwd: ctx.cwd, home: ctx.home, scope });
     if (flags.json === true) {
         ctx.io.out(JSON.stringify(items.map((i) => ({

package/dist/context.d.ts

@@ -56,7 +56,16 @@ export type CliContext = {
     sleep: (ms: number) => Promise<void>;
     /** best-effort browser open; NEVER throws (failure → the caller printed the URL) */
     openUrl: (url: string) => void;
+    /**
+     * Run `cleanup` if the process is interrupted (Ctrl-C, SIGTERM, SIGHUP) or exits
+     * before the returned release is called (I5). The install engine registers the removal
+     * of its temporary folder here for the length of the download, so a Ctrl-C never
+     * leaves a half-downloaded skill behind. OPTIONAL: test contexts omit it, and the
+     * engine then simply has nothing to register with.
+     */
+    trap?: (cleanup: () => void) => () => void;
 };
+export declare function trapInterrupts(cleanup: () => void, err: (s: string) => void): () => void;
 /** Read the package's own version (dist/ and src/ both sit one level under the root). */
 export declare function readOwnVersion(): string;
 /**

package/dist/context.js

@@ -78,6 +78,61 @@ function installTerminalSafety() {
         });
     }
 }
+/**
+ * The real `trap` (I5, DX-A2). Signal listeners exist only while something is
+ * registered, so Ctrl-C keeps its default meaning everywhere else (a prompt in raw mode
+ * never sees SIGINT at all: it arrives as a keypress).
+ *
+ * ⚠️ Cleanups run SYNCHRONOUSLY: an `exit` listener cannot await, and a signal handler
+ * that awaited would let the process die mid-cleanup. The engine's cleanup is one
+ * `rmSync`, which is the point.
+ */
+const trapped = new Set();
+let trapListeners = null;
+function runTrapped() {
+    for (const fn of [...trapped]) {
+        trapped.delete(fn);
+        try {
+            fn();
+        }
+        catch {
+            /* best-effort during teardown */
+        }
+    }
+}
+export function trapInterrupts(cleanup, err) {
+    trapped.add(cleanup);
+    if (!trapListeners) {
+        const signals = [
+            ["SIGINT", 130],
+            ["SIGTERM", 143],
+            ["SIGHUP", 129],
+        ];
+        trapListeners = signals.map(([sig, code]) => {
+            const fn = () => {
+                runTrapped();
+                err("Interrupted. Nothing was installed and the temporary files were removed.");
+                process.exit(code);
+            };
+            process.on(sig, fn);
+            return { sig, fn };
+        });
+        process.on("exit", runTrapped);
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        trapped.delete(cleanup);
+        if (trapped.size === 0 && trapListeners) {
+            for (const { sig, fn } of trapListeners)
+                process.off(sig, fn);
+            process.off("exit", runTrapped);
+            trapListeners = null;
+        }
+    };
+}
 /** Read the package's own version (dist/ and src/ both sit one level under the root). */
 export function readOwnVersion() {
     try {
@@ -253,5 +308,6 @@ export function realContext(argv) {
         now: () => Date.now(),
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
         openUrl: (url) => openUrlBestEffort(url, process.platform),
+        trap: (cleanup) => trapInterrupts(cleanup, (s) => process.stderr.write(s + "\n")),
     };
 }

package/dist/errors.d.ts

@@ -6,7 +6,9 @@ export declare const EXIT: {
     readonly AUTH: 2;
     /** server gate: tier, cap, denial, rate limit, version floor, not found */
     readonly DENIED: 3;
-    /** sha256 mismatch, unsafe manifest path, receipt schema problems */
+    /** 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 */
     readonly INTEGRITY: 4;
     /** filesystem: permissions, disk, existing dir */
     readonly IO: 5;
@@ -49,6 +51,15 @@ export declare class CliError extends Error {
      * picker's Cancelled/Interrupted) report `"error"` and point at the index page.
      */
     readonly code: string;
+    /**
+     * The local changes a `local_changes` refusal lists (1.2.2). Rides `--json` as
+     * `error.changes` and a batch row's `changes`, so a script can name the files without
+     * parsing the human rows. Paths come from the member's own disk, never the server.
+     */
+    readonly changes?: {
+        path: string;
+        reason: string;
+    }[];
     /**
      * ⚠️ `message` and `hint` are passed through {@link terminalBlock} — the
      * defence-in-depth BACKSTOP for terminal-control injection, not the primary control.
@@ -72,6 +83,10 @@ export declare class CliError extends Error {
     constructor(message: string, exitCode: ExitCode, opts?: {
         footer?: string;
         hint?: string;
+        changes?: {
+            path: string;
+            reason: string;
+        }[];
     });
 }
 /**
@@ -87,6 +102,11 @@ export type CliFailure = {
         exit_code: ExitCode;
         /** always present — the anchor when there is one, else the errors index */
         doc_url: string;
+        /** a `local_changes` refusal only (1.2.2): each path and why it blocked */
+        changes?: {
+            path: string;
+            reason: string;
+        }[];
     };
 };
 /**

package/dist/errors.js

@@ -9,7 +9,9 @@ export const EXIT = {
     AUTH: 2,
     /** server gate: tier, cap, denial, rate limit, version floor, not found */
     DENIED: 3,
-    /** sha256 mismatch, unsafe manifest path, receipt schema problems */
+    /** 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 */
     INTEGRITY: 4,
     /** filesystem: permissions, disk, existing dir */
     IO: 5,
@@ -53,6 +55,12 @@ export class CliError extends Error {
      * picker's Cancelled/Interrupted) report `"error"` and point at the index page.
      */
     code;
+    /**
+     * The local changes a `local_changes` refusal lists (1.2.2). Rides `--json` as
+     * `error.changes` and a batch row's `changes`, so a script can name the files without
+     * parsing the human rows. Paths come from the member's own disk, never the server.
+     */
+    changes;
     /**
      * ⚠️ `message` and `hint` are passed through {@link terminalBlock} — the
      * defence-in-depth BACKSTOP for terminal-control injection, not the primary control.
@@ -80,6 +88,8 @@ export class CliError extends Error {
         this.footer = opts?.footer;
         this.hint = opts?.hint === undefined ? undefined : terminalBlock(opts.hint);
         this.code = opts?.footer ?? "error";
+        if (opts?.changes)
+            this.changes = opts.changes;
     }
 }
 /**
@@ -105,6 +115,7 @@ export function toFailureJson(err) {
                 message: err.message,
                 exit_code: err.exitCode,
                 doc_url: err.footer ? footerUrl(err.footer) : CLI_ERRORS_URL,
+                ...(err.changes ? { changes: err.changes } : {}),
             },
         };
     }

package/dist/help.d.ts

@@ -1,2 +1,4 @@
 export declare function globalHelp(version: string): string;
+/** DX-A6: `upgrade` is the npm word, and people reach for it to update the CLI itself. */
+export declare const UPGRADE_NOTICE = "`promptdock upgrade` updates your installed skills; it does not update the promptdock CLI. To update the CLI: npm i -g promptdock@latest (or use npx promptdock@latest).";
 export declare const COMMAND_HELP: Record<string, string>;

package/dist/help.js

@@ -34,7 +34,7 @@ export function globalHelp(version) {
     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)
     update [ref] [--all]      update installed skills to the latest approved version
-    upgrade                   alias of update
+    upgrade                   alias of update (updates skills, not the CLI: npm i -g promptdock@latest)
     list [--json]             show installed skills (receipts)
     help                      this map
 
@@ -43,7 +43,8 @@ export function globalHelp(version) {
     --target <tool>           pick the tool (${TARGETS.map((t) => t.id).join(", ")}); scope is still asked — add -g or -y to skip
     --dir <path>              install into an explicit directory
     -y, --yes                 skip prompts (needs an unambiguous target; NEVER implies --force)
-    --force                   replace a non-empty foreign directory / overwrite local edits
+    --force                   replace files you edited and files at paths the new version ships,
+                              keeping every other file you added; or replace another skill's folder
     --dry-run                 resolve + print what would happen; installs nothing
     --json                    machine-readable output
 
@@ -62,13 +63,18 @@ ${targets}
     NO_COLOR                  disable colored output
 
   Exit codes
-    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)
+    0 ok · 1 usage · 2 auth · 3 denied/gated · 5 filesystem · 6 network
+    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
+    130 interrupted (Ctrl-C; Esc in a prompt cancels with 1)
 
   Docs:    ${SITE}/docs/cli
   Errors:  ${SITE}/docs/cli/errors
   Support: ${SITE}${CANONICAL_CONTACT_PATH}`;
 }
+/** DX-A6: `upgrade` is the npm word, and people reach for it to update the CLI itself. */
+export const UPGRADE_NOTICE = "`promptdock upgrade` updates your installed skills; it does not update the promptdock CLI. To update the CLI: npm i -g promptdock@latest (or use npx promptdock@latest).";
 export const COMMAND_HELP = {
     login: `promptdock login [--token pdk_…]
 
@@ -96,7 +102,15 @@ Non-interactive sessions (CI) must pass --target or --dir plus -y, and
 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).`,
+installing (and without spending any premium-unlock slot).
+
+Installing over a copy you changed: files you added are kept. A file you
+edited, or a file of yours where the new version ships one, stops the install
+(exit 4) and nothing is changed. --force replaces those files and keeps every
+other file you added. With no receipt in a non-empty folder (what an uninstall
+leaves when you had added files), --force keeps your files that do not collide
+with the new version's; another skill's folder is replaced, and the CLI lists
+what it removed.`,
     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
@@ -109,9 +123,14 @@ 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]
 
+${UPGRADE_NOTICE}
+
 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, including local changes that would block. Files you added
+are kept; a file you edited, or a file of yours where the new version ships
+one, blocks the update without --force (which replaces those files and keeps
+every other file you added).
 
 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

package/dist/index.js

@@ -4,7 +4,7 @@
 import { parseArgs } from "./args.js";
 import { realContext } from "./context.js";
 import { CliError, EXIT, footerUrl, toFailureJson, wantsJsonOutput } from "./errors.js";
-import { COMMAND_HELP, globalHelp } from "./help.js";
+import { COMMAND_HELP, globalHelp, UPGRADE_NOTICE } from "./help.js";
 import { colors } from "./ui.js";
 import { runInstall } from "./commands/install.js";
 import { runLogin, runLogout, runWhoami } from "./commands/login.js";
@@ -75,6 +75,9 @@ async function main() {
                 await runUninstall(ctx, positionals, flags);
                 return EXIT.OK;
             case "update":
+                // DX-A6: on stderr, so `upgrade --json` keeps stdout to one document.
+                if (argv[0] === "upgrade")
+                    ctx.io.err(UPGRADE_NOTICE);
                 await runUpdate(ctx, positionals, flags);
                 return EXIT.OK;
             case "list":

package/dist/installer.d.ts

@@ -1,7 +1,15 @@
 import type { Api } from "./api.js";
 import type { CliContext } from "./context.js";
 import type { InstallResponse, ManifestEntry } from "./contract.js";
+import { type ChangeReason } from "./local-changes.js";
 import { type Receipt } from "./receipts.js";
+/** An install's temporary folders, by kind. The number in the name is the operation's start. */
+export declare const STAGING_PREFIX = ".promptdock-staging-";
+export declare const OLD_PREFIX = ".promptdock-old-";
+/** A previous copy kept because the new one did not verify: never removed automatically. */
+export declare const KEPT_PREFIX = ".promptdock-kept-";
+/** `.promptdock-<kind>-<start ms>-<random>`: the age a later command reads (ENG-A4). */
+export declare function tempName(kind: "staging" | "old" | "kept", startedAt: number): string;
 /** Narrow the untrusted install response; throws INTEGRITY on a bad shape. */
 export declare function checkInstallResponse(resp: unknown): InstallResponse;
 /**
@@ -19,35 +27,100 @@ export declare function checkInstallResponse(resp: unknown): InstallResponse;
  * function is the untrusted-server backstop behind it and must never be removed.
  */
 export declare function assertSafeManifest(manifest: ManifestEntry[]): void;
+/**
+ * Where an install's temporary folders live (DX-A2, I5): the folder ABOVE the skills
+ * folder, so a killed install never leaves a folder holding a SKILL.md where the agent
+ * scans for skills. Falls back to the skills folder itself when the folder above is
+ * missing, not writable, or on another filesystem (the swap must stay a rename, and a
+ * rename across filesystems fails with EXDEV). The skills folder must exist.
+ */
+export declare function tempRootFor(targetDir: string): string;
 export type StagedInstall = {
     tempDir: string;
     files: {
         path: string;
         sha256: string;
     }[];
+    /** the response the files came from (a re-signed one after I9's refresh) */
+    resp: InstallResponse;
 };
 /**
- * Download every manifest file into `<parent>/.promptdock-staging-*` (SIBLING of
- * the target so the final rename never crosses filesystems), verifying sha256 +
- * byte length against the manifest. Throws (and discards the temp dir) on ANY
+ * Download every manifest file into `tempDir` (which must not exist yet), verifying
+ * sha256 + byte length against the manifest. Throws (and removes `tempDir`) on ANY
  * mismatch — the sha in the manifest is the transport-integrity anchor.
+ *
+ * I6: a dropped connection is exit 6 (`download`), never an "unexpected error".
+ * I9: signed URLs expire after a few minutes while files download one at a time, so a
+ * 400 or 403 from a signed URL re-signs ONCE through `resign` (the install endpoint:
+ * `record_skill_install` is idempotent per member and skill, so no second install is
+ * recorded) and retries; a second expiry is the plain "links expired" refusal.
  */
-export declare function downloadAndStage(ctx: CliContext, api: Api, resp: InstallResponse, targetDir: string): Promise<StagedInstall>;
-/**
- * Atomic-ish commit: fresh target → one rename; existing target → staged
- * replace (target → .promptdock-old-*, temp → target, drop old; on failure the
- * old dir is restored). Same-parent renames only.
- */
-export declare function commitStaged(tempDir: string, targetDir: string): void;
+export declare function downloadAndStage(ctx: CliContext, resp0: InstallResponse, tempDir: string, opts?: {
+    resign?: () => Promise<InstallResponse>;
+}): Promise<StagedInstall>;
+/** What sits at the target before this install, which decides what may be carried. */
+export type ExistingTarget = 
+/** nothing, or an empty folder */
+{
+    kind: "none";
+}
+/** this skill's own earlier install: carry the member's files, refuse on changes */
+ | {
+    kind: "update";
+    receipt: Receipt;
+}
+/** a non-empty folder with no readable receipt (what an uninstall that kept files leaves) */
+ | {
+    kind: "unmanaged";
+}
+/** another skill's install: replaced under --force, as before 1.2.2 */
+ | {
+    kind: "foreign";
+    receipt: Receipt;
+};
+export type ReplacedPath = {
+    path: string;
+    reason: ChangeReason;
+    shipped: boolean;
+};
+export type InstallOutcome = {
+    receipt: Receipt;
+    /** member files and links carried into the new copy */
+    kept: string[];
+    /** what --force replaced or removed in this skill's own folder */
+    replaced: ReplacedPath[];
+    /** what --force removed from another skill's folder */
+    removed: string[];
+    /** non-fatal notices for stderr (a previous copy that could not be removed, …) */
+    warnings: string[];
+};
 /**
- * The full phase-2: download → verify → commit → receipt → best-effort complete.
- * `refString` is the canonical handle/slug; `prior` carries a matching update's
- * receipt so unknown fields survive the rewrite (DX F16).
+ * The full phase 2: refuse on manifest conflicts → download → verify → check again →
+ * carry → receipt into the new copy → swap → verify → drop the old copy → best-effort
+ * complete. `refString` is the canonical handle/slug.
  */
 export declare function performInstall(ctx: CliContext, api: Api, opts: {
     resp: InstallResponse;
     targetDir: string;
     targetId: string;
     refString: string;
-    prior?: Receipt;
-}): Promise<Receipt>;
+    existing: ExistingTarget;
+    force: boolean;
+    /** for a refusal's first line */
+    verb: "install" | "update";
+    /** terminal-safe already */
+    title: string;
+    /** I9's one re-sign (the install POST again); omitted, an expired link fails as before */
+    resign?: () => Promise<InstallResponse>;
+    /** called once the manifest has passed the conflict check, just before the download */
+    onDownload?: (resp: InstallResponse) => void;
+}): Promise<InstallOutcome>;
+/**
+ * The swap. A fresh target is one rename. An existing target goes aside as
+ * `.promptdock-old-*` under `root`, beside a sidecar naming the target so a later
+ * command can put it back after a crash (ENG-A4); the staged copy is renamed in, and
+ * the old copy is returned for the caller to verify against and then delete (ENG-A36).
+ * A failed second rename renames the old copy back: the machine must never end up with
+ * NOTHING.
+ */
+export declare function commitStaged(tempDir: string, targetDir: string, root: string, startedAt: number): string | null;