@edspencer/paddock 0.0.1 → 0.57.0

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

@@ -0,0 +1,197 @@
+/**
+ * One-shot importer for native Claude Code chats (#588) — the headless twin of
+ * `POST …/adopt-chats`.
+ *
+ * ## Why it lives here and not in `scripts/`
+ *
+ * It needs `loadPaddockConfig`, `ProjectStore` and `HerdctlService`, which are
+ * TypeScript modules in this package. `scripts/` is pinned to CommonJS by its
+ * own `package.json` (for the extensionless `pm` wrapper) and holds only plain
+ * `.mjs`, so a script there could not import them without a build step or a
+ * duplicated config parser — and a duplicated parser is exactly how the CLI and
+ * the server would come to disagree about which data dir or Claude home they are
+ * working on. Here it inherits this package's `"type": "module"`, its tsconfig
+ * and its `tsx`, and runs the SAME code the server runs.
+ *
+ * ## Deployment note
+ *
+ * The import needs READ access to the user's transcripts. In a container that
+ * usually means running this on the HOST against the data dir (`--data-dir`),
+ * or mounting `~/.claude` in and pointing `CLAUDE_HOME` at the mount. Detection
+ * silently finds nothing if the transcripts are not visible — which is why
+ * `--dry-run` prints the sources it found rather than only a count.
+ *
+ * ## Usage
+ *
+ *   npm run import-chats -w @paddock/server -- --project <slug> [options]
+ *
+ *   --project <slug>   Workspace to import into. Required. Use "" (or --root)
+ *                      for the ROOT workspace, whose key IS the empty string.
+ *   --root             Sugar for `--project ""`.
+ *   --from <dir>       Import only this source working directory. Default: every
+ *                      source detection offers.
+ *   --move             Move transcripts instead of copying them. DESTRUCTIVE:
+ *                      the sessions disappear from the user's own history.
+ *   --dry-run          Report what would happen and write nothing at all.
+ *   --data-dir <dir>   Paddock data dir (same meaning as PADDOCK_DATA_DIR).
+ *                      Applied to the environment BEFORE the config is read.
+ *   --json             Emit the raw result as JSON instead of prose.
+ */
+import { loadPaddockConfig } from "../config.js";
+import { ProjectStore, ROOT_KEY } from "../projects.js";
+import { HerdctlService } from "../herdctl.js";
+import { RunProvenanceStore, ADOPTED_ROOT } from "../run-provenance.js";
+/**
+ * Parse argv. Hand-rolled because this is the repo's FIRST script taking flags
+ * (`pm` parses its own, in CommonJS) — there is no convention to follow and no
+ * argument parser in the dependency tree, and adding one for six flags would be
+ * the larger change.
+ *
+ * `--project ""` must survive: the root workspace's key is the empty string, so
+ * a "missing value" check written as truthiness would reject the one workspace
+ * that always exists.
+ */
+export function parseArgs(argv) {
+    const args = { move: false, dryRun: false, json: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const value = () => {
+            const next = argv[i + 1];
+            if (next === undefined || (next.startsWith("--") && next.length > 2)) {
+                throw new Error(`${arg} needs a value`);
+            }
+            i++;
+            return next;
+        };
+        switch (arg) {
+            case "--project":
+                args.project = value();
+                break;
+            case "--root":
+                args.project = ROOT_KEY;
+                break;
+            case "--from":
+                args.from = value();
+                break;
+            case "--move":
+                args.move = true;
+                break;
+            case "--dry-run":
+                args.dryRun = true;
+                break;
+            case "--data-dir":
+                args.dataDir = value();
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--help":
+            case "-h":
+                args.help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return args;
+}
+const USAGE = `Import existing Claude Code CLI chats into a Paddock workspace.
+
+  npm run import-chats -w @paddock/server -- --project <slug> [options]
+
+  --project <slug>   Workspace to import into (required). "" = the root workspace.
+  --root             Sugar for --project ""
+  --from <dir>       Import only this source working directory
+  --move             Move transcripts instead of copying (DESTRUCTIVE)
+  --dry-run          Report what would happen; write nothing
+  --data-dir <dir>   Paddock data dir (same as PADDOCK_DATA_DIR)
+  --json             Emit raw JSON
+`;
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    // `=== undefined`, not falsiness: "" is the root workspace, a real target.
+    if (args.project === undefined) {
+        process.stderr.write("--project is required (use --root for the root workspace)\n\n" + USAGE);
+        return 2;
+    }
+    // Must land in the environment BEFORE the config is read — every other path
+    // (projects root, state dir, herdctl config) is derived from it.
+    if (args.dataDir !== undefined)
+        process.env.PADDOCK_DATA_DIR = args.dataDir;
+    const cfg = loadPaddockConfig();
+    const projects = new ProjectStore(cfg.projectsRoot);
+    const herdctl = new HerdctlService(cfg);
+    const project = await projects.get(args.project);
+    // Register the keepers so the agent this imports INTO exists and its `.chats/`
+    // symlink is in place. `init` is the same call the server makes at boot; the
+    // scheduler is never started, so nothing fires while we run.
+    const rootWorkspace = await projects.get(ROOT_KEY);
+    await herdctl.init([...(await projects.list()), rootWorkspace]);
+    try {
+        const summary = await herdctl.listAdoptable(project);
+        if (summary.count === 0 && summary.filtered.length === 0) {
+            process.stdout.write(args.json
+                ? JSON.stringify({ adopted: [], skipped: [] }) + "\n"
+                : `Nothing to import for "${project.slug || "(root)"}".\n` +
+                    `Working directory: ${project.workingDir}\n` +
+                    `Claude home:       ${cfg.claudeHome}\n` +
+                    `If you expected chats here, check that this process can READ the transcripts\n` +
+                    `(a container only sees what is mounted) and that CLAUDE_HOME points at them.\n`);
+            return 0;
+        }
+        const result = await herdctl.adoptChats(project, {
+            sourceCwd: args.from,
+            mode: args.move ? "move" : "copy",
+            dryRun: args.dryRun,
+        });
+        // Provenance is a server-side sidecar, so the CLI must stamp it too or a
+        // chat imported headlessly would badge differently from one imported in the
+        // UI. Skipped under --dry-run: it is a write.
+        if (!args.dryRun) {
+            const runProvenance = new RunProvenanceStore(cfg.dataDir);
+            for (const sessionId of result.adopted) {
+                await runProvenance.stampIfAbsent(sessionId, ADOPTED_ROOT).catch(() => undefined);
+            }
+        }
+        if (args.json) {
+            process.stdout.write(JSON.stringify({ ...result, sources: summary.sources }, null, 2) + "\n");
+            return 0;
+        }
+        const verb = args.dryRun ? "Would import" : "Imported";
+        const lines = [];
+        lines.push(`${verb} ${result.adopted.length} chat(s) into "${project.slug || "(root)"}".`);
+        for (const source of summary.sources) {
+            lines.push(`  from ${source.sourceCwd} (${source.sessionIds.length} offered)`);
+        }
+        if (summary.filtered.length > 0) {
+            lines.push(`  withheld as noise: ${summary.filtered.length}`);
+            for (const f of summary.filtered)
+                lines.push(`    ${f.sessionId}  ${f.reason}`);
+        }
+        if (result.skipped.length > 0) {
+            lines.push(`  skipped: ${result.skipped.length}`);
+            for (const s of result.skipped)
+                lines.push(`    ${s.sessionId}  ${s.reason}`);
+        }
+        if (args.dryRun)
+            lines.push("Dry run — nothing was written.");
+        process.stdout.write(lines.join("\n") + "\n");
+        return 0;
+    }
+    finally {
+        await herdctl.stop().catch(() => undefined);
+    }
+}
+// Only run when invoked directly, so the arg parser stays unit-testable.
+if (process.argv[1] !== undefined && import.meta.url === `file://${process.argv[1]}`) {
+    main()
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        process.stderr.write(`${err.message ?? err}\n`);
+        process.exit(1);
+    });
+}

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * `paddock` — the npx / global-install entrypoint (#TBD).
+ *
+ * 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 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:
+ *
+ *   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.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const MIN_NODE_MAJOR = 22;
+/** This module's own directory: `<…>/packages/server/dist/cli`. */
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Walk up from this module looking for `rel`, returning the containing dir.
+ *
+ * Two layouts have to work and they nest differently:
+ *
+ *   repo       `<repo>/packages/server/dist/cli/paddock.js`
+ *              deps at `<repo>/packages/server/node_modules` AND `<repo>/node_modules`
+ *   published  `<pkg>/packages/server/dist/cli/paddock.js`
+ *              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.
+ */
+function findUp(rel) {
+    let dir = moduleDir;
+    for (;;) {
+        if (fs.existsSync(path.join(dir, rel)))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** 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 };
+    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`);
+            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 "-h":
+            case "--help":
+                opts.help = true;
+                break;
+            case "-v":
+            case "--version":
+                opts.version = true;
+                break;
+            default:
+                fail(`unknown option: ${arg}\nRun \`paddock --help\` for usage.`);
+        }
+    }
+    return opts;
+}
+function fail(message) {
+    console.error(`paddock: ${message}`);
+    process.exit(1);
+}
+function readVersion() {
+    try {
+        const raw = fs.readFileSync(path.join(packageRoot, "package.json"), "utf8");
+        return JSON.parse(raw).version ?? "unknown";
+    }
+    catch {
+        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)
+  -v, --version           Print the Paddock version and exit
+  -h, --help              Show this help
+
+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\`.
+
+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}\`)`);
+    }
+}
+/**
+ * Put our bundled `claude` on PATH for child processes.
+ *
+ * Chat turns do NOT need this: they run herdctl's SDK runtime, which resolves
+ * the binary from the Claude Agent SDK's own platform package via
+ * `require.resolve` and never consults PATH. But the post-turn sweeper and all
+ * triggers are one-shot `trigger()` calls on the CLI runtime, which does
+ * `execa("claude", …)` — by name, without execa's `preferLocal`, so a local
+ * install is invisible to it unless PATH says otherwise.
+ *
+ * Without this, chats work and every sweep/trigger fails (logged, non-fatal).
+ */
+function addBundledBinsToPath() {
+    const owner = findUp(path.join("node_modules", ".bin"));
+    if (owner === undefined)
+        return;
+    const binDir = path.join(owner, "node_modules", ".bin");
+    const sep = process.platform === "win32" ? ";" : ":";
+    const current = process.env.PATH ?? "";
+    if (current.split(sep).includes(binDir))
+        return;
+    process.env.PATH = current ? `${binDir}${sep}${current}` : binDir;
+}
+/**
+ * Best-effort credential check — WARNS, never blocks.
+ *
+ * Claude Code stores credentials differently per platform (a file under
+ * ~/.claude on Linux, the Keychain on macOS), so absence of a file does not
+ * prove absence of a login. Refusing to start on a false negative would be
+ * worse than a chat that fails with the runtime's own error, so this only
+ * prints guidance.
+ */
+function warnIfNoCredentials(claudeHome) {
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN || process.env.ANTHROPIC_API_KEY)
+        return;
+    const looksLoggedIn = fs.existsSync(path.join(claudeHome, ".credentials.json")) ||
+        fs.existsSync(path.join(os.homedir(), ".claude.json"));
+    if (looksLoggedIn)
+        return;
+    console.warn([
+        "",
+        "  ⚠ No Claude credentials found.",
+        "",
+        "    Paddock will start, but chats will fail until it has credentials.",
+        "    Fix with either:",
+        "",
+        "      claude setup-token                  # Claude Max/Pro",
+        "      export ANTHROPIC_API_KEY=sk-ant-…   # API billing",
+        "",
+    ].join("\n"));
+}
+/**
+ * Report where the data lives, the first time we create it.
+ *
+ * `npx` is stateless enough that people reasonably assume the whole thing is
+ * ephemeral. It is not — projects, chat transcripts, and settings all persist
+ * here across runs, so say so once, at the moment the directory appears.
+ */
+function noteFirstRun(dataDir) {
+    if (fs.existsSync(dataDir))
+        return;
+    console.log([
+        "",
+        `  Welcome to Paddock. Creating a new instance in ${dataDir}`,
+        "  Projects, chats and settings persist there between runs.",
+        "",
+    ].join("\n"));
+}
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+        console.log(USAGE);
+        return;
+    }
+    if (opts.version) {
+        console.log(readVersion());
+        return;
+    }
+    checkNodeVersion();
+    addBundledBinsToPath();
+    // 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);
+    process.env.PADDOCK_DATA_DIR = dataDir;
+    if (opts.port)
+        process.env.PORT = opts.port;
+    if (opts.host)
+        process.env.HOST = opts.host;
+    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`);
+}
+main().catch((err) => {
+    console.error("fatal:", err);
+    process.exit(1);
+});

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

@@ -0,0 +1,57 @@
+/**
+ * concurrency — bounded fan-out for the routes that touch one file per chat.
+ *
+ * ## Why this exists
+ *
+ * Several endpoints map over every session in a project and open a transcript
+ * per session. Written as `Promise.all(sessions.map(...))` that starts EVERY
+ * read at once: on a real instance that is 1,515 concurrent read streams, each
+ * buffering a transcript that averages ~350 KB. The work is identical either
+ * way — the reads just all land in memory at the same moment instead of a few
+ * at a time.
+ *
+ * Measured on that corpus (`GET /chats/usage`, issue #544):
+ *
+ * | concurrency | wall time | peak RSS |
+ * |---|---|---|
+ * | unbounded (1,515) | 4,510 ms | 706 MB |
+ * | 64 | 4,477 ms | 280 MB |
+ * | 16 | 4,329 ms | 178 MB |
+ *
+ * Bounding it is not a latency trade: the bounded runs were marginally FASTER,
+ * because 1,515 interleaved streams cost more in scheduling and GC pressure than
+ * they buy in overlap. The disk is not the bottleneck at this size — the parse
+ * is, and the parse is single-threaded regardless.
+ *
+ * ## Why a local copy
+ *
+ * `@herdctl/core` has this function twice (`state/job-index.ts` and
+ * `state/utils/concurrency.ts`) and exports NEITHER from the package root, so it
+ * is not reachable from here today. Consolidating and exporting the survivor is
+ * filed upstream as **herdctl#421**; when that lands, this module should be
+ * deleted and the import repointed at core. The clamping below matches the
+ * `state/utils` variant deliberately — the `job-index` copy silently spawns zero
+ * workers (and so resolves having done nothing) when `limit <= 0`.
+ */
+/**
+ * Default bound for per-chat file fan-out.
+ *
+ * 16 measured *faster* than unbounded on a 1,515-chat project while cutting peak
+ * RSS ~4× (706 MB → 178 MB), so there is headroom on both sides of this number;
+ * it is not a knife-edge. Kept as a named constant because the next caller — the
+ * boot-warm sweep — must use the same bound to get the same guarantee.
+ */
+export declare const FILE_FANOUT_CONCURRENCY = 16;
+/**
+ * Map over `items` with at most `limit` calls to `fn` in flight, preserving
+ * input order in the result.
+ *
+ * Order-preserving is load-bearing: callers index the result positionally
+ * against the input array, so this must behave exactly like `Promise.all(
+ * items.map(fn))` in everything except how many calls are live at once.
+ *
+ * `limit` is clamped to at least 1, so a mis-computed or zero bound degrades to
+ * serial execution rather than silently completing without running `fn` at all.
+ * Rejections propagate as they would from `Promise.all`.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/packages/server/dist/concurrency.js

@@ -0,0 +1,71 @@
+/**
+ * concurrency — bounded fan-out for the routes that touch one file per chat.
+ *
+ * ## Why this exists
+ *
+ * Several endpoints map over every session in a project and open a transcript
+ * per session. Written as `Promise.all(sessions.map(...))` that starts EVERY
+ * read at once: on a real instance that is 1,515 concurrent read streams, each
+ * buffering a transcript that averages ~350 KB. The work is identical either
+ * way — the reads just all land in memory at the same moment instead of a few
+ * at a time.
+ *
+ * Measured on that corpus (`GET /chats/usage`, issue #544):
+ *
+ * | concurrency | wall time | peak RSS |
+ * |---|---|---|
+ * | unbounded (1,515) | 4,510 ms | 706 MB |
+ * | 64 | 4,477 ms | 280 MB |
+ * | 16 | 4,329 ms | 178 MB |
+ *
+ * Bounding it is not a latency trade: the bounded runs were marginally FASTER,
+ * because 1,515 interleaved streams cost more in scheduling and GC pressure than
+ * they buy in overlap. The disk is not the bottleneck at this size — the parse
+ * is, and the parse is single-threaded regardless.
+ *
+ * ## Why a local copy
+ *
+ * `@herdctl/core` has this function twice (`state/job-index.ts` and
+ * `state/utils/concurrency.ts`) and exports NEITHER from the package root, so it
+ * is not reachable from here today. Consolidating and exporting the survivor is
+ * filed upstream as **herdctl#421**; when that lands, this module should be
+ * deleted and the import repointed at core. The clamping below matches the
+ * `state/utils` variant deliberately — the `job-index` copy silently spawns zero
+ * workers (and so resolves having done nothing) when `limit <= 0`.
+ */
+/**
+ * Default bound for per-chat file fan-out.
+ *
+ * 16 measured *faster* than unbounded on a 1,515-chat project while cutting peak
+ * RSS ~4× (706 MB → 178 MB), so there is headroom on both sides of this number;
+ * it is not a knife-edge. Kept as a named constant because the next caller — the
+ * boot-warm sweep — must use the same bound to get the same guarantee.
+ */
+export const FILE_FANOUT_CONCURRENCY = 16;
+/**
+ * Map over `items` with at most `limit` calls to `fn` in flight, preserving
+ * input order in the result.
+ *
+ * Order-preserving is load-bearing: callers index the result positionally
+ * against the input array, so this must behave exactly like `Promise.all(
+ * items.map(fn))` in everything except how many calls are live at once.
+ *
+ * `limit` is clamped to at least 1, so a mis-computed or zero bound degrades to
+ * serial execution rather than silently completing without running `fn` at all.
+ * Rejections propagate as they would from `Promise.all`.
+ */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    const workers = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: workers }, worker));
+    return results;
+}