@edspencer/paddock 0.57.0 → 0.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

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

@@ -0,0 +1,25 @@
+/** Directory name that both stores `--here` state and marks the workspace. */
+export declare const HERE_MARKER = ".paddock";
+/** Has this directory been opened with `--here` before? */
+export declare function isHereWorkspace(dir: string): boolean;
+/**
+ * How many of `dir`'s existing Claude Code sessions are worth offering.
+ *
+ * **`encodePathForCli`, not `transcripts.ts`'s `encodeProjectDir`.** The latter
+ * omits Claude Code's truncate-and-hash branch for paths over 200 characters,
+ * on the explicit assumption that "paddock's project dirs are always short".
+ * An arbitrary user directory is exactly where that assumption fails.
+ *
+ * `MIN_TRANSCRIPT_BYTES` is shared with `AdoptableIndex` so the number quoted
+ * here matches what the UI will actually offer to import — a count that
+ * disagreed with the import screen would be worse than no count.
+ */
+export declare function countClaudeSessions(claudeHome: string, dir: string): number;
+/**
+ * Add `entry` to `dir`'s `.gitignore` if no equivalent line is already there.
+ *
+ * Mirrors `ProjectStore.ensureRootGitignore`: read, tolerate the equivalent
+ * forms, append rather than overwrite. `--here` runs inside somebody's real
+ * repository, so clobbering their `.gitignore` is not an option.
+ */
+export declare function ensureGitignored(dir: string, entry: string): void;

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

@@ -0,0 +1,104 @@
+/**
+ * `--here` support: opening the user's own directory as a Paddock workspace (#640).
+ *
+ * ## Why this needs no new concept
+ *
+ * A *project* cannot live outside `projectsRoot` — `dirFor` joins the key onto
+ * the root with no branch, deliberately. But the **root workspace** is a
+ * different thing: its key is `""`, so `dirFor("")` resolves to `projectsRoot`
+ * itself, and `projectsRoot` is user-configurable. Pointing
+ * `PADDOCK_PROJECTS_DIR` at a directory therefore makes that directory the root
+ * workspace, named after its own basename, with no schema change anywhere.
+ *
+ * Session adoption then works by construction: `AdoptableIndex`'s notebook
+ * branch matches on exact `cwd === project.workingDir` equality, and in this
+ * mode the workspace's working directory IS the user's cwd.
+ *
+ * ## Why the data dir goes inside the directory
+ *
+ * `--here` puts state in `<dir>/.paddock` rather than the shared `~/.paddock`.
+ * Two reasons, and the second is the important one:
+ *
+ *  1. **Self-containment.** Opening directory A and later directory B must not
+ *     have them share one job store, herdctl config and sidecar set — that is
+ *     how A's run history leaks into B's UI.
+ *  2. **It gives us an unambiguous marker.** A second, flagless run in the same
+ *     directory should resume it (the `git` model: `--here` is `git init`,
+ *     `.paddock/` is `.git`). Keying that off `project.yaml` would be ambiguous
+ *     — that filename already exists in the wild, including in every project
+ *     directory of the `edspencer/projects` notes repo — whereas `.paddock/` is
+ *     ours and its presence means exactly one thing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { encodePathForCli } from "@herdctl/core";
+import { MIN_TRANSCRIPT_BYTES } from "../adoptable.js";
+/** Directory name that both stores `--here` state and marks the workspace. */
+export const HERE_MARKER = ".paddock";
+/** Has this directory been opened with `--here` before? */
+export function isHereWorkspace(dir) {
+    try {
+        return fs.statSync(path.join(dir, HERE_MARKER)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * How many of `dir`'s existing Claude Code sessions are worth offering.
+ *
+ * **`encodePathForCli`, not `transcripts.ts`'s `encodeProjectDir`.** The latter
+ * omits Claude Code's truncate-and-hash branch for paths over 200 characters,
+ * on the explicit assumption that "paddock's project dirs are always short".
+ * An arbitrary user directory is exactly where that assumption fails.
+ *
+ * `MIN_TRANSCRIPT_BYTES` is shared with `AdoptableIndex` so the number quoted
+ * here matches what the UI will actually offer to import — a count that
+ * disagreed with the import screen would be worse than no count.
+ */
+export function countClaudeSessions(claudeHome, dir) {
+    const folder = path.join(claudeHome, "projects", encodePathForCli(dir));
+    let entries;
+    try {
+        entries = fs.readdirSync(folder);
+    }
+    catch {
+        return 0;
+    }
+    let n = 0;
+    for (const entry of entries) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        try {
+            if (fs.statSync(path.join(folder, entry)).size >= MIN_TRANSCRIPT_BYTES)
+                n++;
+        }
+        catch {
+            /* raced or unreadable — not offerable either way */
+        }
+    }
+    return n;
+}
+/**
+ * Add `entry` to `dir`'s `.gitignore` if no equivalent line is already there.
+ *
+ * Mirrors `ProjectStore.ensureRootGitignore`: read, tolerate the equivalent
+ * forms, append rather than overwrite. `--here` runs inside somebody's real
+ * repository, so clobbering their `.gitignore` is not an option.
+ */
+export function ensureGitignored(dir, entry) {
+    const file = path.join(dir, ".gitignore");
+    let existing = "";
+    try {
+        existing = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        /* no .gitignore yet */
+    }
+    const bare = entry.replace(/^\/|\/$/g, "");
+    const have = new Set(existing.split("\n").map((l) => l.trim()));
+    if (have.has(`/${bare}/`) || have.has(`${bare}/`) || have.has(bare))
+        return;
+    const body = existing && !existing.endsWith("\n") ? `${existing}\n` : existing;
+    fs.writeFileSync(file, `${body}${entry}\n`, "utf8");
+}

package/packages/server/dist/cli/import-chats.js

@@ -37,6 +37,7 @@
  *                      Applied to the environment BEFORE the config is read.
  *   --json             Emit the raw result as JSON instead of prose.
  */
+import { pathToFileURL } from "node:url";
 import { loadPaddockConfig } from "../config.js";
 import { ProjectStore, ROOT_KEY } from "../projects.js";
 import { HerdctlService } from "../herdctl.js";
@@ -187,7 +188,11 @@ async function main() {
     }
 }
 // Only run when invoked directly, so the arg parser stays unit-testable.
-if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+// `pathToFileURL`, not `"file://" + argv[1]`: the naive concatenation leaves any
+// space or non-ASCII character in the path un-encoded, so the comparison fails
+// and the script silently does nothing when run from such a directory — the same
+// percent-encoding trap as #636.
+if (process.argv[1] !== undefined && pathToFileURL(process.argv[1]).href === import.meta.url) {
     main()
         .then((code) => process.exit(code))
         .catch((err) => {

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

@@ -1,2 +1,31 @@
 #!/usr/bin/env node
-export {};
+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;

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

@@ -1,34 +1,29 @@
 #!/usr/bin/env node
 /**
- * `paddock` — the npx / global-install entrypoint (#TBD).
+ * `paddock` — the npx / global-install entrypoint (#637, #638).
  *
- * PROTOTYPE. This is the user-facing front door for `npx @edspencer/paddock`:
- * someone who has never seen this repo runs one command and gets a working
- * instance on localhost. Everything here is preflight and defaults — the server
- * itself is unchanged, and `start()` is the same lifecycle `node dist/index.js`
- * uses.
+ * The user-facing front door for `npx @edspencer/paddock`: someone who has never
+ * seen this repo runs one command and gets a working instance on localhost.
+ * Everything here is preflight, defaults and presentation — the server itself is
+ * untouched, and `start()` is the same lifecycle `node dist/index.js` uses.
  *
- * The design constraint that shapes this file: the server is already
- * *tolerant* — every setting has a default, an empty data dir self-initializes,
- * and auth defaults to `none` on a loopback bind. So a bare `start()` would in
- * fact boot. What it would NOT do is tell a first-time user why their chats
- * fail, or where their data went. Hence:
+ * The design constraint that shapes this file: the server is already *tolerant*
+ * — every setting has a default, an empty data dir self-initializes, and auth
+ * defaults to `none` on a loopback bind. So a bare `start()` would in fact boot.
+ * What it would NOT do is tell a first-time user why their chats fail, where
+ * their data went, or which of the several hundred lines of JSON that just
+ * scrolled past contained the URL.
  *
- *   1. Node version — checked explicitly, because the `engines` field only
- *      warns and the eventual failure is an opaque syntax error.
- *   2. Data dir — defaults to `~/.paddock`, NOT the server's `./data`, which is
- *      relative to cwd and would litter whatever directory you happened to run
- *      npx from (and silently give you a different instance next time).
- *   3. `claude` on PATH — prepended from our own node_modules/.bin. Chats do not
- *      need it (the SDK runtime resolves its own bundled binary), but the
- *      sweeper and triggers shell out to `claude` by name.
- *   4. Credentials — a warning, never a hard failure: we cannot reliably detect
- *      a macOS Keychain login, so refusing to start would lock out valid users.
+ * Everything below the arg parser is side-effecting by nature, so the pure parts
+ * (`parseArgs`, `nodeVersionProblem`, `explainListenError`) are exported and
+ * unit-tested; the rest is exercised by running the built binary.
  */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { HERE_MARKER, isHereWorkspace, countClaudeSessions, ensureGitignored } from "./here.js";
 const MIN_NODE_MAJOR = 22;
 /** This module's own directory: `<…>/packages/server/dist/cli`. */
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -43,8 +38,7 @@ const moduleDir = path.dirname(fileURLToPath(import.meta.url));
  *              deps at `<pkg>/node_modules` only — two levels FURTHER up
  *
  * A fixed `../..` hop is right for the repo and wrong for the published tarball,
- * where it lands on `packages/server` and finds no `node_modules` at all. Walking
- * up is correct for both without branching on which one we are in.
+ * where it lands on `packages/server` and finds no `node_modules` at all.
  */
 function findUp(rel) {
     let dir = moduleDir;
@@ -59,14 +53,23 @@ function findUp(rel) {
 }
 /** Nearest ancestor holding a `package.json` — `packages/server` in both layouts. */
 const packageRoot = findUp("package.json") ?? path.resolve(moduleDir, "../..");
-function parseArgs(argv) {
-    const opts = { help: false, version: false };
+/** 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)
-                fail(`${arg} needs a value`);
+                throw new CliError(`${arg} needs a value`);
             return v;
         };
         switch (arg) {
@@ -81,6 +84,16 @@ function parseArgs(argv) {
             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;
@@ -90,7 +103,7 @@ function parseArgs(argv) {
                 opts.version = true;
                 break;
             default:
-                fail(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+                throw new CliError(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
         }
     }
     return opts;
@@ -117,29 +130,55 @@ 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`;
-/** Node's own version gate. `engines` only warns by default, and the failure it
- *  eventually produces is an unexplained syntax error deep in a dependency. */
-function checkNodeVersion() {
-    const major = Number(process.versions.node.split(".")[0]);
-    if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
-        fail(`Node ${process.versions.node} is too old — Paddock needs Node ${MIN_NODE_MAJOR}+.\n` +
-            `Upgrade Node, then re-run. (nodejs.org, or \`nvm install ${MIN_NODE_MAJOR}\`)`);
-    }
+/**
+ * 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.
@@ -209,8 +248,96 @@ function noteFirstRun(dataDir) {
         "",
     ].join("\n"));
 }
+/**
+ * Say what `--here` is about to do to this directory, on the run that does it.
+ *
+ * The flag IS the consent — there is no prompt, and no `--yes` to remember.
+ * But consent only means something if you can know what you agreed to, so the
+ * effects are announced rather than asked about. Printed only on the first
+ * `--here` in a directory; resuming an already-opened one says nothing.
+ */
+function announceHereConsent(dir, dataDir) {
+    console.log([
+        "",
+        `  Opening ${dir} as a Paddock workspace.`,
+        `    · ${path.relative(dir, dataDir) || HERE_MARKER}/ and .chats/ created here, and added to .gitignore`,
+        "    · ~/.claude sessions for this directory are linked at the workspace",
+        "  Later runs here resume it — no flag needed.",
+        "",
+    ].join("\n"));
+}
+/**
+ * Tell the user their existing Claude history could be opened here.
+ *
+ * The only way anyone discovers `--here` exists. Read-only: a bare run counts
+ * transcripts and prints, and changes nothing on disk.
+ */
+function offerHereIfSessionsExist(dir) {
+    const claudeHome = process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+    let sessions = 0;
+    try {
+        sessions = countClaudeSessions(claudeHome, dir);
+    }
+    catch {
+        return; // detection is a courtesy; never let it break a boot
+    }
+    if (sessions === 0)
+        return;
+    console.log([
+        "",
+        `  This directory has ${sessions} Claude Code session${sessions === 1 ? "" : "s"}.`,
+        "  Run `paddock --here` to open it as a workspace and import them.",
+        "",
+    ].join("\n"));
+}
+/** Open `url` in the default browser. Best-effort: failing is never fatal. */
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(cmd, [url], {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32", // `start` is a cmd builtin, not a binary
+        });
+        // A headless box has no xdg-open. The URL is printed either way, so an
+        // unopenable browser is a non-event rather than a failed run.
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* 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() {
-    const opts = parseArgs(process.argv.slice(2));
+    let opts;
+    try {
+        opts = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            fail(err.message);
+        throw err;
+    }
     if (opts.help) {
         console.log(USAGE);
         return;
@@ -219,29 +346,100 @@ async function main() {
         console.log(readVersion());
         return;
     }
-    checkNodeVersion();
+    const problem = nodeVersionProblem(process.versions.node);
+    if (problem !== undefined)
+        fail(problem);
     addBundledBinsToPath();
+    // Canonical, because working directories "MUST be canonical so session
+    // discovery (which encodes the real path) can find Claude transcripts"
+    // (config.ts). On macOS a /tmp vs /private/tmp divergence would silently
+    // break adoption — and macOS is most laptops.
+    let cwd = process.cwd();
+    try {
+        cwd = fs.realpathSync(cwd);
+    }
+    catch {
+        /* keep the literal path; the server will surface any real problem */
+    }
+    // `--here` is the consent. A flagless run in a directory ALREADY opened this
+    // way resumes it — the git model, where `--here` is `git init` and `.paddock/`
+    // is `.git`. A flagless run anywhere else touches nothing.
+    const resuming = !opts.here && isHereWorkspace(cwd);
+    const hereMode = opts.here || resuming;
     // Apply CLI defaults as env vars. This is the whole integration surface: the
     // server resolves config inside `buildApp()`, so anything set before the
     // dynamic import below is picked up with no special-casing in config.ts.
     // Precedence is explicit flag > existing env > our default.
-    const dataDir = path.resolve(opts.dataDir ?? process.env.PADDOCK_DATA_DIR ?? path.join(os.homedir(), ".paddock"));
-    noteFirstRun(dataDir);
+    const dataDir = path.resolve(opts.dataDir ??
+        process.env.PADDOCK_DATA_DIR ??
+        (hereMode ? path.join(cwd, HERE_MARKER) : path.join(os.homedir(), ".paddock")));
+    if (hereMode) {
+        if (!resuming)
+            announceHereConsent(cwd, dataDir);
+        // The root workspace IS `projectsRoot` (its key is ""), so pointing this at
+        // the user's directory makes that directory the workspace. No schema change,
+        // no new project type — see cli/here.ts.
+        process.env.PADDOCK_PROJECTS_DIR = cwd;
+        fs.mkdirSync(dataDir, { recursive: true });
+        ensureGitignored(cwd, `/${HERE_MARKER}/`);
+        ensureGitignored(cwd, "/.chats/");
+    }
+    else {
+        noteFirstRun(dataDir);
+        offerHereIfSessionsExist(cwd);
+    }
     process.env.PADDOCK_DATA_DIR = dataDir;
     if (opts.port)
         process.env.PORT = opts.port;
     if (opts.host)
         process.env.HOST = opts.host;
+    // Quiet by default. The server emits a few hundred lines on the way up, which
+    // scrolls the one line the user actually needs — the URL — off the top of the
+    // terminal. TWO loggers have to be told, and they are unrelated:
+    //   LOG_LEVEL          Paddock's own pino logger (config.ts).
+    //   HERDCTL_LOG_LEVEL  @herdctl/core's `createLogger`, which writes the
+    //                      `[fleet-manager] …` lines via console.info — pino's
+    //                      level cannot reach those.
+    // An explicit value for either is left alone, and `--verbose` skips both.
+    if (!opts.verbose) {
+        if (process.env.LOG_LEVEL === undefined)
+            process.env.LOG_LEVEL = "warn";
+        if (process.env.HERDCTL_LOG_LEVEL === undefined)
+            process.env.HERDCTL_LOG_LEVEL = "warn";
+    }
     warnIfNoCredentials(process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude"));
     const port = process.env.PORT ?? "4000";
     const host = process.env.HOST ?? "127.0.0.1";
     // Imported dynamically, AFTER the env above is set: a static import would
     // pull in app.ts -> config.ts and resolve config against the wrong data dir.
     const { start } = await import("../start.js");
-    await start();
-    console.log(`\n  Paddock is running at http://${host}:${port}\n  Press Ctrl-C to stop.\n`);
+    try {
+        await start();
+    }
+    catch (err) {
+        fail(explainListenError(err, host, port));
+    }
+    const url = `http://${host}:${port}`;
+    // ALWAYS name the workspace, not just in --here mode. Behaviour that varies
+    // with cwd is only safe if it is observable: "why is this instance different
+    // today" should be answerable by reading the two lines the tool just printed.
+    console.log([
+        "",
+        `  Paddock is running at ${url}`,
+        `  Workspace: ${hereMode ? cwd : dataDir}${resuming ? "  (resumed)" : ""}`,
+        "  Press Ctrl-C to stop.",
+        "",
+    ].join("\n"));
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "private": true,
   "type": "module"
 }

package/packages/web/dist/assets/{InstanceConfigPage-Bypd_quL.js → InstanceConfigPage-Cli_WHsM.js}

@@ -1,2 +1,2 @@
-import{r as o,b as f,j as e,A as b,k as E,l as A,m as O,M as F,n as I}from"./index-B-YuzkF6.js";function $(){const[t,s]=o.useState(null),[l,i]=o.useState(!0),[r,c]=o.useState(null),[d,m]=o.useState({}),[h,k]=o.useState(!1),[j,p]=o.useState(null),[N,u]=o.useState(!1);o.useEffect(()=>{let a=!0;return i(!0),f.getInstanceConfig().then(n=>{a&&(s(n),c(null))}).catch(n=>a&&c(n instanceof Error?n.message:String(n))).finally(()=>a&&i(!1)),()=>{a=!1}},[]);const v=(a,n)=>{u(!1),p(null),m(g=>({...g,[a]:n}))},S=a=>Object.prototype.hasOwnProperty.call(d,a.key)?d[a.key]:a.value,y=o.useMemo(()=>t?t.groups.flatMap(a=>a.fields):[],[t]),x=o.useMemo(()=>y.filter(a=>a.editable&&!a.envOverridden).filter(a=>Object.prototype.hasOwnProperty.call(d,a.key)).filter(a=>!B(d[a.key],a.value)).map(a=>a.key),[y,d]),w=async()=>{if(x.length===0)return;const a={};for(const n of x)a[n]=d[n];k(!0),p(null);try{await f.updateInstanceConfig(a);const n=await f.getInstanceConfig();s(n),m({}),u(!0)}catch(n){p(n instanceof A||n instanceof Error?n.message:String(n))}finally{k(!1)}},C=()=>{m({}),p(null),u(!1)};return e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"min-h-0 flex-1 overflow-y-auto px-4 py-5 sm:px-6",children:e.jsxs("div",{className:"mx-auto max-w-2xl",children:[e.jsx(L,{saved:N,configPath:t==null?void 0:t.configPath}),l&&e.jsx("p",{className:"text-sm text-paddock-500",children:"Loading…"}),r&&e.jsxs("p",{className:"text-sm text-red-600 dark:text-red-400",role:"alert",children:["Failed to load settings: ",r]}),t&&t.groups.map(a=>e.jsx(M,{title:a.label,description:a.description,children:e.jsx("div",{className:"grid grid-cols-1 gap-4",children:a.fields.map(n=>e.jsx(P,{field:n,value:S(n),onChange:g=>v(n.key,g)},n.key))})},a.id))]})}),t&&e.jsxs("footer",{className:"flex items-center gap-3 border-t border-paddock-200 px-4 py-3 dark:border-paddock-800 sm:px-6",children:[j&&e.jsxs("span",{className:"flex items-center gap-1.5 text-[13px] text-red-600 dark:text-red-400",role:"alert",children:[e.jsx(b,{width:14,height:14,className:"shrink-0"}),j]}),e.jsx("span",{className:"ml-auto text-[12px] text-paddock-400",children:x.length>0?`${x.length} unsaved change${x.length===1?"":"s"}`:"No changes"}),e.jsx("button",{type:"button",className:"btn-subtle",onClick:C,disabled:x.length===0||h,children:"Reset"}),e.jsx("button",{type:"button",className:"btn-primary",onClick:w,disabled:x.length===0||h,children:h?"Saving…":"Save changes"})]})]})}function L({saved:t,configPath:s}){return e.jsxs("div",{role:"status",className:`mb-6 flex items-start gap-2 rounded-lg border px-3 py-2.5 text-[13px] leading-snug ${t?"border-emerald-300 bg-emerald-50 text-emerald-800 dark:border-emerald-700/60 dark:bg-emerald-900/20 dark:text-emerald-300":"border-amber-300 bg-amber-50 text-amber-800 dark:border-amber-700/60 dark:bg-amber-900/20 dark:text-amber-300"}`,children:[t?e.jsx(E,{width:15,height:15,className:"mt-0.5 shrink-0"}):e.jsx(b,{width:15,height:15,className:"mt-0.5 shrink-0"}),e.jsx("span",{children:t?e.jsxs(e.Fragment,{children:[e.jsx("strong",{children:"Saved to disk."})," These changes take effect only after the server restarts."]}):e.jsxs(e.Fragment,{children:["Changes here are written to ",e.jsx("code",{className:"font-mono text-[12px]",children:T(s)})," ","and take effect only after the server restarts — the running instance keeps its current config until then."]})})]})}function M({title:t,description:s,children:l}){return e.jsxs("section",{className:"mb-6",children:[e.jsx("h2",{className:"text-sm font-semibold uppercase tracking-wide text-paddock-500",children:t}),s&&e.jsx("p",{className:"mb-3 mt-0.5 text-[13px] text-paddock-500",children:s}),e.jsx("div",{className:`card ${s?"":"mt-2"}`,children:l})]})}function P({field:t,value:s,onChange:l}){const i=!t.editable||t.envOverridden,r=`cfg-${t.key}`;return e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center justify-between gap-3",children:[e.jsxs("label",{htmlFor:i?void 0:r,className:"text-sm font-medium",children:[t.label,t.sensitive&&e.jsx("span",{className:"ml-1.5 align-middle text-[10px] font-semibold uppercase tracking-wide text-amber-600 dark:text-amber-400",children:"sensitive"})]}),t.type==="boolean"&&!i&&e.jsx("input",{id:r,type:"checkbox",className:"h-4 w-4 accent-accent",checked:!!s,onChange:c=>l(c.target.checked)})]}),t.help&&e.jsx("p",{className:"mt-0.5 text-[12px] leading-snug text-paddock-500",children:t.help}),i?e.jsx(V,{field:t,value:s}):t.type!=="boolean"&&e.jsx(R,{field:t,value:s,onChange:l,inputId:r}),t.envOverridden&&e.jsxs("p",{className:"mt-1 flex items-start gap-1.5 text-[12px] leading-snug text-amber-600 dark:text-amber-400",children:[e.jsx(b,{width:13,height:13,className:"mt-0.5 shrink-0"}),e.jsxs("span",{children:["Overridden by environment variable ",e.jsx("code",{className:"font-mono",children:t.envVar})," — edit that env var (and restart) to change it."]})]})]})}function R({field:t,value:s,onChange:l,inputId:i}){if(t.type==="enum")return e.jsx("select",{id:i,className:"input mt-1.5",value:String(s??""),onChange:r=>l(r.target.value),children:(t.enumValues??[]).map(r=>e.jsx("option",{value:r,children:r},r))});if(t.type==="number")return e.jsx("input",{id:i,type:"number",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"default":String(t.default),onChange:r=>l(r.target.value===""?null:Number(r.target.value))});if(t.type==="text"){const r=s==null||s===t.default,c=s==null?String(t.default??""):String(s),d=typeof t.default=="string"&&!r;return e.jsxs("div",{className:"mt-1.5",children:[e.jsx("textarea",{id:i,className:"input min-h-[9rem] resize-y font-mono text-[12px] leading-relaxed",rows:10,spellCheck:!1,value:c,onChange:m=>l(m.target.value)}),e.jsxs("div",{className:"mt-1 flex items-center justify-between gap-3 text-[12px] text-paddock-500",children:[e.jsx("span",{children:r?"Using the built-in default.":s===""?"Empty — nothing will be appended.":`${c.length.toLocaleString()} characters.`}),d&&e.jsx("button",{type:"button",className:"shrink-0 underline underline-offset-2 hover:text-paddock-700 dark:hover:text-paddock-300",onClick:()=>l(null),children:"Restore default"})]})]})}if(t.type==="string-list"){const r=Array.isArray(s)?s.join(", "):String(s??"");return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:r,onChange:c=>l(c.target.value.split(",").map(d=>d.trim()).filter(Boolean))})}return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"":String(t.default),onChange:r=>l(r.target.value)})}function V({field:t,value:s}){return e.jsx("div",{className:"mt-1.5 rounded-md border border-dashed border-paddock-300 bg-paddock-50 px-2.5 py-1.5 text-[13px] text-paddock-600 dark:border-paddock-700 dark:bg-paddock-900/40 dark:text-paddock-300",children:t.type==="boolean"?e.jsx("span",{className:"font-mono",children:s?"true":"false"}):s==null||s===""?e.jsx("span",{className:"italic text-paddock-400",children:t.type==="text"&&s===""?"(empty — nothing appended)":"(not set)"}):t.type==="text"?e.jsx("span",{className:"block max-h-64 overflow-y-auto whitespace-pre-wrap font-mono text-[12px] leading-relaxed",children:String(s)}):e.jsx("span",{className:"break-all font-mono",children:Array.isArray(s)?s.join(", "):String(s)})})}function B(t,s){return Array.isArray(t)&&Array.isArray(s)?t.length===s.length&&t.every((l,i)=>l===s[i]):t===s}function T(t){if(!t)return"paddock.config.yaml";const s=t.split("/");return s[s.length-1]||t}function z(){const t=O(),s=(t==null?void 0:t.openNav)??(()=>{});return e.jsxs("div",{className:"flex h-full min-h-0 flex-col",children:[e.jsxs("header",{className:"pt-safe flex items-center gap-2 border-b border-paddock-200 px-3 pb-2.5 dark:border-paddock-800 sm:px-6 lg:py-4",children:[e.jsx("button",{type:"button",onClick:s,"aria-label":"Open menu",className:"btn-subtle -ml-1 shrink-0 px-2 py-1.5 lg:hidden",children:e.jsx(F,{width:20,height:20})}),e.jsx(I,{width:18,height:18,className:"shrink-0 text-paddock-400"}),e.jsx("h1",{className:"text-[15px] font-semibold tracking-tight",children:"Config"})]}),e.jsx($,{})]})}export{z as InstanceConfigPage};
+import{r as o,b as f,j as e,A as b,k as E,l as A,m as O,M as F,n as I}from"./index-CcYeBUNk.js";function $(){const[t,s]=o.useState(null),[l,i]=o.useState(!0),[r,c]=o.useState(null),[d,m]=o.useState({}),[h,k]=o.useState(!1),[j,p]=o.useState(null),[N,u]=o.useState(!1);o.useEffect(()=>{let a=!0;return i(!0),f.getInstanceConfig().then(n=>{a&&(s(n),c(null))}).catch(n=>a&&c(n instanceof Error?n.message:String(n))).finally(()=>a&&i(!1)),()=>{a=!1}},[]);const v=(a,n)=>{u(!1),p(null),m(g=>({...g,[a]:n}))},S=a=>Object.prototype.hasOwnProperty.call(d,a.key)?d[a.key]:a.value,y=o.useMemo(()=>t?t.groups.flatMap(a=>a.fields):[],[t]),x=o.useMemo(()=>y.filter(a=>a.editable&&!a.envOverridden).filter(a=>Object.prototype.hasOwnProperty.call(d,a.key)).filter(a=>!B(d[a.key],a.value)).map(a=>a.key),[y,d]),w=async()=>{if(x.length===0)return;const a={};for(const n of x)a[n]=d[n];k(!0),p(null);try{await f.updateInstanceConfig(a);const n=await f.getInstanceConfig();s(n),m({}),u(!0)}catch(n){p(n instanceof A||n instanceof Error?n.message:String(n))}finally{k(!1)}},C=()=>{m({}),p(null),u(!1)};return e.jsxs(e.Fragment,{children:[e.jsx("div",{className:"min-h-0 flex-1 overflow-y-auto px-4 py-5 sm:px-6",children:e.jsxs("div",{className:"mx-auto max-w-2xl",children:[e.jsx(L,{saved:N,configPath:t==null?void 0:t.configPath}),l&&e.jsx("p",{className:"text-sm text-paddock-500",children:"Loading…"}),r&&e.jsxs("p",{className:"text-sm text-red-600 dark:text-red-400",role:"alert",children:["Failed to load settings: ",r]}),t&&t.groups.map(a=>e.jsx(M,{title:a.label,description:a.description,children:e.jsx("div",{className:"grid grid-cols-1 gap-4",children:a.fields.map(n=>e.jsx(P,{field:n,value:S(n),onChange:g=>v(n.key,g)},n.key))})},a.id))]})}),t&&e.jsxs("footer",{className:"flex items-center gap-3 border-t border-paddock-200 px-4 py-3 dark:border-paddock-800 sm:px-6",children:[j&&e.jsxs("span",{className:"flex items-center gap-1.5 text-[13px] text-red-600 dark:text-red-400",role:"alert",children:[e.jsx(b,{width:14,height:14,className:"shrink-0"}),j]}),e.jsx("span",{className:"ml-auto text-[12px] text-paddock-400",children:x.length>0?`${x.length} unsaved change${x.length===1?"":"s"}`:"No changes"}),e.jsx("button",{type:"button",className:"btn-subtle",onClick:C,disabled:x.length===0||h,children:"Reset"}),e.jsx("button",{type:"button",className:"btn-primary",onClick:w,disabled:x.length===0||h,children:h?"Saving…":"Save changes"})]})]})}function L({saved:t,configPath:s}){return e.jsxs("div",{role:"status",className:`mb-6 flex items-start gap-2 rounded-lg border px-3 py-2.5 text-[13px] leading-snug ${t?"border-emerald-300 bg-emerald-50 text-emerald-800 dark:border-emerald-700/60 dark:bg-emerald-900/20 dark:text-emerald-300":"border-amber-300 bg-amber-50 text-amber-800 dark:border-amber-700/60 dark:bg-amber-900/20 dark:text-amber-300"}`,children:[t?e.jsx(E,{width:15,height:15,className:"mt-0.5 shrink-0"}):e.jsx(b,{width:15,height:15,className:"mt-0.5 shrink-0"}),e.jsx("span",{children:t?e.jsxs(e.Fragment,{children:[e.jsx("strong",{children:"Saved to disk."})," These changes take effect only after the server restarts."]}):e.jsxs(e.Fragment,{children:["Changes here are written to ",e.jsx("code",{className:"font-mono text-[12px]",children:T(s)})," ","and take effect only after the server restarts — the running instance keeps its current config until then."]})})]})}function M({title:t,description:s,children:l}){return e.jsxs("section",{className:"mb-6",children:[e.jsx("h2",{className:"text-sm font-semibold uppercase tracking-wide text-paddock-500",children:t}),s&&e.jsx("p",{className:"mb-3 mt-0.5 text-[13px] text-paddock-500",children:s}),e.jsx("div",{className:`card ${s?"":"mt-2"}`,children:l})]})}function P({field:t,value:s,onChange:l}){const i=!t.editable||t.envOverridden,r=`cfg-${t.key}`;return e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center justify-between gap-3",children:[e.jsxs("label",{htmlFor:i?void 0:r,className:"text-sm font-medium",children:[t.label,t.sensitive&&e.jsx("span",{className:"ml-1.5 align-middle text-[10px] font-semibold uppercase tracking-wide text-amber-600 dark:text-amber-400",children:"sensitive"})]}),t.type==="boolean"&&!i&&e.jsx("input",{id:r,type:"checkbox",className:"h-4 w-4 accent-accent",checked:!!s,onChange:c=>l(c.target.checked)})]}),t.help&&e.jsx("p",{className:"mt-0.5 text-[12px] leading-snug text-paddock-500",children:t.help}),i?e.jsx(V,{field:t,value:s}):t.type!=="boolean"&&e.jsx(R,{field:t,value:s,onChange:l,inputId:r}),t.envOverridden&&e.jsxs("p",{className:"mt-1 flex items-start gap-1.5 text-[12px] leading-snug text-amber-600 dark:text-amber-400",children:[e.jsx(b,{width:13,height:13,className:"mt-0.5 shrink-0"}),e.jsxs("span",{children:["Overridden by environment variable ",e.jsx("code",{className:"font-mono",children:t.envVar})," — edit that env var (and restart) to change it."]})]})]})}function R({field:t,value:s,onChange:l,inputId:i}){if(t.type==="enum")return e.jsx("select",{id:i,className:"input mt-1.5",value:String(s??""),onChange:r=>l(r.target.value),children:(t.enumValues??[]).map(r=>e.jsx("option",{value:r,children:r},r))});if(t.type==="number")return e.jsx("input",{id:i,type:"number",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"default":String(t.default),onChange:r=>l(r.target.value===""?null:Number(r.target.value))});if(t.type==="text"){const r=s==null||s===t.default,c=s==null?String(t.default??""):String(s),d=typeof t.default=="string"&&!r;return e.jsxs("div",{className:"mt-1.5",children:[e.jsx("textarea",{id:i,className:"input min-h-[9rem] resize-y font-mono text-[12px] leading-relaxed",rows:10,spellCheck:!1,value:c,onChange:m=>l(m.target.value)}),e.jsxs("div",{className:"mt-1 flex items-center justify-between gap-3 text-[12px] text-paddock-500",children:[e.jsx("span",{children:r?"Using the built-in default.":s===""?"Empty — nothing will be appended.":`${c.length.toLocaleString()} characters.`}),d&&e.jsx("button",{type:"button",className:"shrink-0 underline underline-offset-2 hover:text-paddock-700 dark:hover:text-paddock-300",onClick:()=>l(null),children:"Restore default"})]})]})}if(t.type==="string-list"){const r=Array.isArray(s)?s.join(", "):String(s??"");return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:r,onChange:c=>l(c.target.value.split(",").map(d=>d.trim()).filter(Boolean))})}return e.jsx("input",{id:i,type:"text",className:"input mt-1.5",value:s==null?"":String(s),placeholder:t.default===null?"":String(t.default),onChange:r=>l(r.target.value)})}function V({field:t,value:s}){return e.jsx("div",{className:"mt-1.5 rounded-md border border-dashed border-paddock-300 bg-paddock-50 px-2.5 py-1.5 text-[13px] text-paddock-600 dark:border-paddock-700 dark:bg-paddock-900/40 dark:text-paddock-300",children:t.type==="boolean"?e.jsx("span",{className:"font-mono",children:s?"true":"false"}):s==null||s===""?e.jsx("span",{className:"italic text-paddock-400",children:t.type==="text"&&s===""?"(empty — nothing appended)":"(not set)"}):t.type==="text"?e.jsx("span",{className:"block max-h-64 overflow-y-auto whitespace-pre-wrap font-mono text-[12px] leading-relaxed",children:String(s)}):e.jsx("span",{className:"break-all font-mono",children:Array.isArray(s)?s.join(", "):String(s)})})}function B(t,s){return Array.isArray(t)&&Array.isArray(s)?t.length===s.length&&t.every((l,i)=>l===s[i]):t===s}function T(t){if(!t)return"paddock.config.yaml";const s=t.split("/");return s[s.length-1]||t}function z(){const t=O(),s=(t==null?void 0:t.openNav)??(()=>{});return e.jsxs("div",{className:"flex h-full min-h-0 flex-col",children:[e.jsxs("header",{className:"pt-safe flex items-center gap-2 border-b border-paddock-200 px-3 pb-2.5 dark:border-paddock-800 sm:px-6 lg:py-4",children:[e.jsx("button",{type:"button",onClick:s,"aria-label":"Open menu",className:"btn-subtle -ml-1 shrink-0 px-2 py-1.5 lg:hidden",children:e.jsx(F,{width:20,height:20})}),e.jsx(I,{width:18,height:18,className:"shrink-0 text-paddock-400"}),e.jsx("h1",{className:"text-[15px] font-semibold tracking-tight",children:"Config"})]}),e.jsx($,{})]})}export{z as InstanceConfigPage};