@edspencer/paddock 0.59.0 → 0.60.0

package/packages/server/dist/cli/args.js

@@ -0,0 +1,159 @@
+/**
+ * Pure argument parsing and message formatting for the `paddock` CLI.
+ *
+ * ## Why this is its own module
+ *
+ * These functions want unit tests, and the entrypoint they used to live in
+ * cannot be imported without running. The first attempt kept them in
+ * `paddock.ts` behind a run-directly guard:
+ *
+ * ```ts
+ * if (pathToFileURL(process.argv[1]).href === import.meta.url) main();
+ * ```
+ *
+ * **That guard shipped a silent no-op to npm.** npm installs a `bin` as a
+ * SYMLINK at `node_modules/.bin/paddock`, so `process.argv[1]` is the symlink
+ * path while `import.meta.url` is the module's realpath. They never match, the
+ * condition is always false, and `npx @edspencer/paddock` printed nothing and
+ * exited 0 — in 0.57.0, 0.58.0 and 0.59.0. It went unnoticed because the manual
+ * checks invoked `node <file>` directly, which is the one path where the guard
+ * does hold.
+ *
+ * `realpathSync(argv[1])` would fix that instance. Splitting the module removes
+ * the need for the guard entirely, so there is no condition left to get wrong on
+ * the next shim, platform or package manager. `paddock.ts` now always runs.
+ */
+/** A usage error. Thrown rather than exiting, so parsing stays testable. */
+export class CliError extends Error {
+}
+export const MIN_NODE_MAJOR = 22;
+export function parseArgs(argv) {
+    const opts = {
+        here: false,
+        open: false,
+        verbose: false,
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new CliError(`${arg} needs a value`);
+            return v;
+        };
+        switch (arg) {
+            case "-p":
+            case "--port":
+                opts.port = next();
+                break;
+            case "--host":
+                opts.host = next();
+                break;
+            case "-d":
+            case "--data-dir":
+                opts.dataDir = next();
+                break;
+            case "--here":
+                opts.here = true;
+                break;
+            case "-o":
+            case "--open":
+                opts.open = true;
+                break;
+            case "--verbose":
+                opts.verbose = true;
+                break;
+            case "-h":
+            case "--help":
+                opts.help = true;
+                break;
+            case "-v":
+            case "--version":
+                opts.version = true;
+                break;
+            default:
+                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+        }
+    }
+    return opts;
+}
+/**
+ * Why this Node is unusable, or `undefined` if it is fine.
+ *
+ * `engines` only warns by default, and the failure it eventually produces is an
+ * unexplained syntax error deep inside a dependency.
+ */
+export function nodeVersionProblem(nodeVersion) {
+    const major = Number(nodeVersion.split(".")[0]);
+    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
+        return undefined;
+    return (`Node ${nodeVersion} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
+        `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
+}
+/**
+ * Translate a listen failure into something a human can act on.
+ *
+ * `EADDRINUSE` on 4000 is the likeliest first-run failure — a popular port and
+ * Paddock's own default — and Node's raw error names neither the port nor the
+ * flag that fixes it.
+ */
+export function explainListenError(err, host, port) {
+    const code = err?.code;
+    if (code === "EADDRINUSE") {
+        return (`port ${port} is already in use.\n` +
+            `Something else is listening on ${host}:${port} — possibly another Paddock.\n` +
+            `Pick a different port:  paddock --port ${Number(port) + 1}`);
+    }
+    if (code === "EACCES") {
+        return (`not allowed to bind ${host}:${port}.\n` +
+            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
+    }
+    return String(err?.message ?? err);
+}
+export const USAGE = `paddock — run a Paddock instance locally
+
+Usage
+  npx @edspencer/paddock [options]
+
+Options
+  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)
+      --host <host>       Bind address (default 127.0.0.1)
+  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
+      --here              Open the CURRENT directory as the workspace (see below)
+  -o, --open              Open the app in your browser once it is listening
+      --verbose           Show the server's own logs (quiet by default)
+  -v, --version           Print the Paddock version and exit
+  -h, --help              Show this help
+
+Opening a directory (--here)
+  Run \`paddock --here\` inside a project and Paddock opens THAT directory as its
+  workspace: Claude works in your files, and any Claude Code sessions you already
+  have for the directory are offered for import. It:
+
+    · creates .paddock/ in the directory for this workspace's own state
+    · creates .chats/ for transcripts, and adds both to .gitignore
+    · links ~/.claude/projects/<encoded-dir> at this workspace
+
+  Once done, later runs in the same directory resume it — no flag needed.
+  Without --here, Paddock never touches the directory you ran it from.
+
+Credentials
+  Paddock drives Claude Code, so it needs Claude credentials in the
+  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
+  billing). If you already use Claude Code on this machine, an existing login
+  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
+
+Your data
+  Everything lives in one directory — ~/.paddock unless you pass --data-dir.
+  Projects, chat transcripts and settings all persist there between runs. Move
+  that directory to move your instance; delete it to start over. Nothing is
+  stored anywhere else.
+
+Notes
+  Binds loopback with authentication disabled, which is safe for a laptop. To
+  expose it on a network, set PADDOCK_AUTH_MODE first — Paddock refuses to bind
+  a routable interface wide open. See AUTH.md.
+
+Docs: https://github.com/edspencer/paddock`;

package/packages/server/dist/cli/paddock.d.ts

@@ -1,31 +1,2 @@
 #!/usr/bin/env node
-export interface CliOptions {
-    port?: string;
-    host?: string;
-    dataDir?: string;
-    here: boolean;
-    open: boolean;
-    verbose: boolean;
-    help: boolean;
-    version: boolean;
-}
-/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
-export declare class CliError extends Error {
-}
-export declare function parseArgs(argv: string[]): CliOptions;
-/**
- * Why this Node is unusable, or `undefined` if it is fine.
- *
- * Split from the exit so it can be tested. `engines` only warns by default, and
- * the failure it eventually produces is an unexplained syntax error deep inside
- * a dependency — which is nobody's idea of a first-run experience.
- */
-export declare function nodeVersionProblem(nodeVersion: string): string | undefined;
-/**
- * Translate a listen failure into something a human can act on.
- *
- * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
- * popular port and Paddock's own default — and Node's raw error names neither
- * the port nor the flag that fixes it.
- */
-export declare function explainListenError(err: unknown, host: string, port: string): string;
+export {};

package/packages/server/dist/cli/paddock.js

@@ -22,9 +22,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { HERE_MARKER, isHereWorkspace, countClaudeSessions, ensureGitignored } from "./here.js";
-const MIN_NODE_MAJOR = 22;
+import { CliError, USAGE, parseArgs, nodeVersionProblem, explainListenError, } from "./args.js";
 /** This module's own directory: `<…>/packages/server/dist/cli`. */
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 /**
@@ -53,61 +53,6 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-/** A usage error. Thrown rather than exiting, so `parseArgs` stays testable. */
-export class CliError extends Error {
-}
-export function parseArgs(argv) {
-    const opts = {
-        here: false,
-        open: false,
-        verbose: false,
-        help: false,
-        version: false,
-    };
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        const next = () => {
-            const v = argv[++i];
-            if (v === undefined)
-                throw new CliError(`${arg} needs a value`);
-            return v;
-        };
-        switch (arg) {
-            case "-p":
-            case "--port":
-                opts.port = next();
-                break;
-            case "--host":
-                opts.host = next();
-                break;
-            case "-d":
-            case "--data-dir":
-                opts.dataDir = next();
-                break;
-            case "--here":
-                opts.here = true;
-                break;
-            case "-o":
-            case "--open":
-                opts.open = true;
-                break;
-            case "--verbose":
-                opts.verbose = true;
-                break;
-            case "-h":
-            case "--help":
-                opts.help = true;
-                break;
-            case "-v":
-            case "--version":
-                opts.version = true;
-                break;
-            default:
-                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
-        }
-    }
-    return opts;
-}
 function fail(message) {
     console.error(`paddock: ${message}`);
     process.exit(1);
@@ -121,65 +66,6 @@ function readVersion() {
         return "unknown";
     }
 }
-const USAGE = `paddock — run a Paddock instance locally
-
-Usage
-  npx @edspencer/paddock [options]
-
-Options
-  -p, --port <port>       HTTP/WS port (default 4000, or $PORT)
-      --host <host>       Bind address (default 127.0.0.1)
-  -d, --data-dir <path>   Projects + state (default ~/.paddock, or $PADDOCK_DATA_DIR)
-      --here              Open the CURRENT directory as the workspace (see below)
-  -o, --open              Open the app in your browser once it is listening
-      --verbose           Show the server's own logs (quiet by default)
-  -v, --version           Print the Paddock version and exit
-  -h, --help              Show this help
-
-Opening a directory (--here)
-  Run \`paddock --here\` inside a project and Paddock opens THAT directory as its
-  workspace: Claude works in your files, and any Claude Code sessions you already
-  have for the directory are offered for import. It:
-
-    · creates .paddock/ in the directory for this workspace's own state
-    · creates .chats/ for transcripts, and adds both to .gitignore
-    · links ~/.claude/projects/<encoded-dir> at this workspace
-
-  Once done, later runs in the same directory resume it — no flag needed.
-  Without --here, Paddock never touches the directory you ran it from.
-
-Credentials
-  Paddock drives Claude Code, so it needs Claude credentials in the
-  environment: CLAUDE_CODE_OAUTH_TOKEN (Max/Pro) or ANTHROPIC_API_KEY (API
-  billing). If you already use Claude Code on this machine, an existing login
-  under ~/.claude is picked up automatically. Otherwise run \`claude setup-token\`.
-
-Your data
-  Everything lives in one directory — ~/.paddock unless you pass --data-dir.
-  Projects, chat transcripts and settings all persist there between runs. Move
-  that directory to move your instance; delete it to start over. Nothing is
-  stored anywhere else.
-
-Notes
-  Binds loopback with authentication disabled, which is safe for a laptop. To
-  expose it on a network, set PADDOCK_AUTH_MODE first — Paddock refuses to bind
-  a routable interface wide open. See AUTH.md.
-
-Docs: https://github.com/edspencer/paddock`;
-/**
- * Why this Node is unusable, or `undefined` if it is fine.
- *
- * Split from the exit so it can be tested. `engines` only warns by default, and
- * the failure it eventually produces is an unexplained syntax error deep inside
- * a dependency — which is nobody's idea of a first-run experience.
- */
-export function nodeVersionProblem(nodeVersion) {
-    const major = Number(nodeVersion.split(".")[0]);
-    if (!Number.isFinite(major) || major >= MIN_NODE_MAJOR)
-        return undefined;
-    return (`Node ${nodeVersion} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
-        `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
-}
 /**
  * Put our bundled `claude` on PATH for child processes.
  *
@@ -308,26 +194,6 @@ function openBrowser(url) {
         /* as above */
     }
 }
-/**
- * Translate a listen failure into something a human can act on.
- *
- * `EADDRINUSE` on 4000 is the single most likely first-run failure — it is a
- * popular port and Paddock's own default — and Node's raw error names neither
- * the port nor the flag that fixes it.
- */
-export function explainListenError(err, host, port) {
-    const code = err?.code;
-    if (code === "EADDRINUSE") {
-        return (`port ${port} is already in use.\n` +
-            `Something else is listening on ${host}:${port} — possibly another Paddock.\n` +
-            `Pick a different port:  paddock --port ${Number(port) + 1}`);
-    }
-    if (code === "EACCES") {
-        return (`not allowed to bind ${host}:${port}.\n` +
-            `Ports below 1024 need elevated privileges — use a higher one:  paddock --port 4000`);
-    }
-    return String(err?.message ?? err);
-}
 async function main() {
     let opts;
     try {
@@ -433,13 +299,7 @@ async function main() {
     if (opts.open)
         openBrowser(url);
 }
-// Run only when executed directly, so the unit tests can import the pure parts.
-// `pathToFileURL`, not `"file://" + argv[1]`: the naive concatenation breaks on
-// any path containing a space or non-ASCII character — the same percent-encoding
-// trap as #636.
-if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
-    main().catch((err) => {
-        console.error("fatal:", err);
-        process.exit(1);
-    });
-}
+main().catch((err) => {
+    console.error("fatal:", err);
+    process.exit(1);
+});

package/packages/server/dist/herdctl.d.ts

@@ -134,6 +134,24 @@ export declare class HerdctlService {
      * {@link cancel}). Entries are removed when the turn's stream ends.
      */
     private liveSessions;
+    /**
+     * Background-phase turns keyed by the synthetic job id the sink minted for
+     * them, valued by the chat session they belong to (paddock#528).
+     *
+     * After a turn's primary `result` lands, {@link chatSession} returns and drops
+     * its {@link liveSessions} entry — but the session itself may live on, held
+     * open by the reaper because the turn launched background work, streaming
+     * autonomous re-invocation turns. Those turns are real, running, and shown as
+     * such; until now they were also uncancellable, because nothing registered
+     * them anywhere Stop could reach.
+     *
+     * `interrupt()` would be the wrong tool even if it could: it targets an
+     * in-flight model turn, and the wedge case is a session sitting idle holding
+     * background work that will never finish. So these route to a force-reap
+     * instead — end the session, let the stream end, and let the ordinary unwind
+     * emit `chat:complete`. Entries are removed when the background stream ends.
+     */
+    private backgroundTurns;
     /**
      * Incremental index of `<stateDir>/jobs`, backing the unread-badge reads
      * (`lastTurnCompletedAt*`) — one per service, reused across requests so a warm
@@ -325,12 +343,61 @@ export declare class HerdctlService {
      */
     adoptChats(project: Project, opts?: {
         sourceCwd?: string;
+        /**
+         * Import only these sessions (#660). Anything else the engine adopts along
+         * the way is released again, exactly as a noise-filtered session is — see
+         * the "honouring the noise filter" note above, which this reuses wholesale.
+         * Undefined means "everything on offer", which is what a confirmed
+         * select-all sends and what the CLI has always sent.
+         */
+        sessionIds?: string[];
         mode?: AdoptionPlacementMode;
         dryRun?: boolean;
     }): Promise<{
         adopted: string[];
         skipped: AdoptSkipped[];
     }>;
+    /**
+     * Did an import of `sessionId` from `fromWorkingDir` place a NEW file?
+     *
+     * The same test `releaseWithheld` makes before deleting anything: an in-place
+     * adoption resolves the destination and the origin to one path, so there is no
+     * copy and nothing that may be removed.
+     */
+    private placedACopy;
+    /**
+     * What the LAST import into each workspace did, so it can be undone (#660).
+     *
+     * Keyed by workspace key (which may be `""` — the root). Holds the sessions
+     * that import actually brought in, and of those, the ones where it PLACED a
+     * copy and may therefore delete one again.
+     *
+     * Server-side rather than a token the client hands back: undo deletes files, so
+     * the set of paths it may touch must come from what this process actually did,
+     * not from a request body. A restart forgets it, which is the right failure —
+     * the offer to undo is a transient toast, not a durable feature.
+     *
+     * Only the most recent import per workspace is kept. Undoing an import two
+     * imports ago is not offered and would be a lie to describe as "undo".
+     */
+    private readonly lastImport;
+    /**
+     * Undo the import this process most recently performed into `project` (#660).
+     *
+     * Releases each adoption and deletes the copies that import placed, leaving the
+     * user's own `~/.claude` history exactly as it was. Returns the sessions it
+     * released; an empty array means there was nothing to undo (nothing imported
+     * yet, already undone, or the server restarted since).
+     *
+     * `sessionIds` narrows it to part of that import — the rest stays. Ids that
+     * were not part of it are ignored rather than rejected: undo is a best-effort
+     * safety net, and the alternative is a 400 for a button the user pressed once.
+     */
+    unadoptChats(project: Project, opts?: {
+        sessionIds?: string[];
+    }): Promise<{
+        released: string[];
+    }>;
     /**
      * Undo the adoption of a session detection had withheld, restoring the state
      * that existed before this import. See {@link adoptChats} for why the file
@@ -452,11 +519,24 @@ export declare class HerdctlService {
     }): Promise<{
         sessionId: string | null;
     }>;
+    /**
+     * Register a background-phase turn so Stop can reach it (paddock#528). Called
+     * by the background turn sink once it knows both the synthetic job id it
+     * published and the session that stream belongs to. Re-registering the same
+     * job id with a later session id is fine — the sink refreshes the mapping if
+     * the stream resolves a different session.
+     */
+    registerBackgroundTurn(jobId: string, sessionId: string): void;
+    /** Forget a background-phase turn once its stream has ended. */
+    unregisterBackgroundTurn(jobId: string): void;
     /**
      * Cancel a running turn (Stop button → WS chat:cancel). Handles BOTH drive
      * modes off the single id the client holds as `jobId`:
      *  - **session mode** — the id is a synthetic turn id in {@link liveSessions};
      *    interrupt the live `RuntimeSession` (there is no herdctl job to cancel).
+     *  - **background phase** — the id is a synthetic id in
+     *    {@link backgroundTurns}; there is no model turn to interrupt, so reap the
+     *    session (paddock#528).
      *  - **batch mode** — the id is a real herdctl job id; abort it via `cancelJob`
      *    (which kills the CLI subprocess / aborts the SDK query).
      *