@edspencer/paddock 0.71.1 → 0.72.0

package/packages/server/dist/profiles.js

@@ -0,0 +1,214 @@
+/**
+ * Named config profiles (#878) — `paranoid` / `balanced` / `yolo`.
+ *
+ * Paddock has a dozen independent security/capability levers, each with its own
+ * code default. A profile is the single place to express *posture* — "locked
+ * down" / "full capability" — instead of hand-setting twelve `PADDOCK_*` vars.
+ *
+ * ## Why this is a resolved key, not something an installer writes
+ *
+ * Config resolves as code default < YAML file < `PADDOCK_*` env. A profile
+ * implemented as "the installer materialises concrete values into
+ * `paddock.config.yaml`" only ever touches the FILE layer — so it only works on
+ * the one distribution that runs an installer. Docker and bare `node dist` would
+ * keep falling through to code defaults and the distributions would stay
+ * divergent, which is the actual complaint #878 opens with. Resolving `profile`
+ * at every layer — file, env, and a code default underneath both — is what makes
+ * every distribution converge on the same posture.
+ *
+ * ## Where a profile sits in the precedence chain
+ *
+ * A profile supplies the DEFAULT that each lever's loader falls back to. It does
+ * not become a config layer of its own. So the full chain is:
+ *
+ *     code-default profile  <  resolved profile  <  individual file key  <  individual env var
+ *
+ * The consequence worth stating out loud, because it inverts this codebase's
+ * otherwise universal env-beats-file rule: **an individual key in the YAML file
+ * beats `PADDOCK_PROFILE` in the env.** `PADDOCK_PROFILE=paranoid` with
+ * `claude: {hooks: host}` in a mounted file resolves hooks to `host`.
+ *
+ * That is deliberate — specific beats general. `PADDOCK_PROFILE` is a statement
+ * about the dozen levers you did NOT mention; a key you wrote by hand is a
+ * statement about the one you did. The alternative makes the env var a blunt
+ * instrument that silently discards deliberate per-key config, which is a worse
+ * failure than the surprise of a file winning. (Env still beats file for the same
+ * key, exactly as everywhere else: `PADDOCK_CLAUDE_HOOKS` beats
+ * `claude.hooks`.)
+ *
+ * ## Posture keys only
+ *
+ * Profiles govern the `claude:` inheritance modes, `maxSpawnDepth`, and the
+ * capability toggles — and define ALL of them (see `POSTURE_KEYS`, pinned by a
+ * test). They are silent on operational keys (port, data dir, bind host, auth,
+ * models, drive mode, curation/recovery/attachments, git author). Switching
+ * profile must never change your port or clobber your auth config.
+ *
+ * ## Two guardrails
+ *
+ * - Profiles stay orthogonal to bind address and auth. `yolo` must NOT open the
+ *   bind or relax auth — network exposure remains its own explicit decision,
+ *   already gated by the dangerous-allow-open opt-in. Otherwise "yolo" quietly
+ *   becomes "yolo, reachable from the whole network".
+ * - `host` resolves against whatever `~/.claude` actually exists: rich on a
+ *   workstation, typically empty in a container. **The profile sets the levers,
+ *   the environment sets the blast radius** — which is why the permissive
+ *   profiles are far more reasonable in a disposable container than on a primary
+ *   machine.
+ */
+import { DEFAULT_MAX_SPAWN_DEPTH } from "./spawn-capability.js";
+/** The three built-in profiles, in ascending order of capability. */
+export const PROFILE_NAMES = ["paranoid", "balanced", "yolo"];
+/**
+ * The code-default profile (#878).
+ *
+ * `balanced` rather than `paranoid` because of the **superset principle**:
+ * paddock is a presentation layer over the Claude Code CLI, so its capability
+ * surface should be a superset of what the plain CLI already gives you. A user
+ * whose CLI has MCP servers configured (and plugin-provided MCP servers, which
+ * additionally need `instructions: host`) reasonably expects those to work here;
+ * defaulting them off is experienced as a capability regression versus the tool
+ * paddock wraps.
+ */
+export const DEFAULT_PROFILE = "balanced";
+/**
+ * Every posture key, as data — so a test can assert that all three profiles
+ * cover exactly this set. Kept in sync with `Posture` by that same test: a key
+ * added to the interface but not here fails to typecheck against
+ * `Record<keyof Posture, …>` at the `PROFILES` declaration below.
+ */
+export const POSTURE_KEYS = [
+    "transcripts",
+    "credentials",
+    "instructions",
+    "hooks",
+    "mcpServers",
+    "maxSpawnDepth",
+    "selfMcpEnabled",
+    "selfMcpWriteEnabled",
+    "selfMcpProjectsEnabled",
+    "scheduleMutationEnabled",
+    "hooksMcpEnabled",
+    "browserMcp",
+];
+/**
+ * The three postures. All three define the same key set, differing only in
+ * values — so a diff between two columns is a diff in posture, never in
+ * coverage.
+ *
+ * Two choices here are argued rather than assumed:
+ *
+ * - **`hooks: own` in `balanced`.** Host hooks are shell commands that fire
+ *   AUTOMATICALLY on every matching tool call — inherited arbitrary code
+ *   execution. That is a different risk class from MCP servers, which are tools
+ *   an agent deliberately chooses to call. So `hooks` does not ride along with
+ *   the other `host` modes; it is `host` only under `yolo`.
+ * - **`browserMcp: false` in `balanced`.** It needs a browser installed on the
+ *   box. Enabling it by default on a host without one leads agents to fall back
+ *   to scripting a system browser instead, which is worse than not having it.
+ */
+export const PROFILES = {
+    /**
+     * Everything isolated, every capability off. This is paddock's historical code
+     * default, unchanged — `profiles.test.ts` pins it against the legacy
+     * `DEFAULT_*` constants, so selecting it is a no-op for anyone who was relying
+     * on those. `credentials` is the one lever that was never `own` by default:
+     * reading a login risks no file of the user's, and an instance that boots
+     * clean then fails every turn (#683) is the worse failure.
+     */
+    paranoid: {
+        transcripts: "own",
+        credentials: "host",
+        instructions: "own",
+        hooks: "own",
+        mcpServers: "own",
+        maxSpawnDepth: DEFAULT_MAX_SPAWN_DEPTH,
+        selfMcpEnabled: false,
+        selfMcpWriteEnabled: false,
+        selfMcpProjectsEnabled: false,
+        scheduleMutationEnabled: false,
+        hooksMcpEnabled: false,
+        browserMcp: false,
+    },
+    /**
+     * The default. Inherits the CAPABILITIES the host CLI already gives the user —
+     * `instructions`, `mcpServers`, and the plugins that ride on the former — and
+     * turns on read-only self-MCP, while leaving the genuinely additive/riskier
+     * ones off: write-side self-MCP, project creation, schedule mutation, hooks
+     * MCP, host hooks, deeper spawning.
+     *
+     * **`transcripts` stays `own`, against #878's original table.** The superset
+     * principle is an argument about capability: withholding the MCP servers and
+     * instructions a user has already configured reads as a regression against the
+     * tool paddock wraps. Transcripts are not a capability — they are where chat
+     * history physically lives. Sharing them makes paddock no more capable, and it
+     * changes what an existing verb MEANS: under `host` a delete *releases* a
+     * transcript rather than removing it (#689), because it is the user's history
+     * rather than paddock's copy. Defaulting that on would silently stop chat
+     * deletion from deleting, and would couple a brand-new instance to
+     * `~/.claude/projects` on first boot.
+     *
+     * It is also the status quo, so this half of the profile change is a no-op on
+     * upgrade. The cost — that flipping to `host` later is currently broken (#708)
+     * — is repaid by the guided migration specified in #882, which is what makes
+     * `own` a starting posture rather than a permanent one.
+     */
+    balanced: {
+        transcripts: "own",
+        credentials: "host",
+        instructions: "host",
+        hooks: "own",
+        mcpServers: "host",
+        maxSpawnDepth: DEFAULT_MAX_SPAWN_DEPTH,
+        selfMcpEnabled: true,
+        selfMcpWriteEnabled: false,
+        selfMcpProjectsEnabled: false,
+        scheduleMutationEnabled: false,
+        hooksMcpEnabled: false,
+        browserMcp: false,
+    },
+    /**
+     * Full capability. Note what it still does NOT do: it does not touch the bind
+     * address or auth (see the guardrail in this file's header).
+     */
+    yolo: {
+        transcripts: "host",
+        credentials: "host",
+        instructions: "host",
+        hooks: "host",
+        mcpServers: "host",
+        maxSpawnDepth: 2,
+        selfMcpEnabled: true,
+        selfMcpWriteEnabled: true,
+        selfMcpProjectsEnabled: true,
+        scheduleMutationEnabled: true,
+        hooksMcpEnabled: true,
+        browserMcp: true,
+    },
+};
+/** Whether `v` names a built-in profile. */
+export function isKnownProfile(v) {
+    return PROFILE_NAMES.includes(v);
+}
+/**
+ * Resolve the profile NAME from env > file > {@link DEFAULT_PROFILE}.
+ *
+ * An unrecognised name falls back to the default rather than failing the boot —
+ * the rule every other enum in `config.ts` follows (`driveMode`, the `claude:`
+ * modes, whisper `mode`). The direction is defensible here in a way it is not
+ * for a single lever: the fallback is `balanced`, so a typo can only ever land
+ * you on the same posture a config-less instance already has, never on `yolo`.
+ *
+ * Deliberately NOT tsconfig-style `extends`: a closed set of names, one level,
+ * no chains, no path resolution. The inheritance is fine; arbitrary-file
+ * inheritance graphs are what make `extends` unpleasant.
+ */
+export function resolveProfileName(fileVal, env = process.env) {
+    const raw = env.PADDOCK_PROFILE?.trim() || (fileVal === undefined || fileVal === null ? "" : String(fileVal).trim());
+    const name = raw.toLowerCase();
+    return name && isKnownProfile(name) ? name : DEFAULT_PROFILE;
+}
+/** The posture a profile name expands to. */
+export function posture(name) {
+    return PROFILES[name];
+}

package/packages/server/dist/routes/transcripts.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Instance-level transcript-migration routes (#882).
+ *
+ *   GET  /api/transcripts/migration        → the banner's probe. Cheap.
+ *   GET  /api/transcripts/migration/chats  → the modal's per-chat plan.
+ *   POST /api/transcripts/migration        → execute: quiesce, move, commit.
+ *
+ * ## Steps 1–3 of §4.1 are here, and that is deliberate
+ *
+ * The execute ordering is
+ * `single-flight → expectedVersion → quiesce → re-enumerate → move → write
+ * config`, and the first three are refusals: when any of them fires, NOTHING
+ * may have moved. The cleanest way to guarantee that is for them to run in the
+ * route, before `executeMigration` — which owns the mover — is entered at all.
+ * The config write is handed to it as a callback for the mirror-image reason:
+ * it is the COMMIT POINT and must be last, so the module that decides whether
+ * every project reached the postcondition is the module that gets to call it.
+ *
+ * The reverse order (config first) was rejected in the design: a crash between
+ * a config saying `host` and files still in `.chats/` is a genuine #708 split,
+ * where a crash the other way is the transient blank list #882 already tells
+ * the user to expect, and which re-running reconciles.
+ *
+ * ## Why two paths rather than one with `?summary=`
+ *
+ * The same reason `routes/discover.ts:9-18` gives for its own pair: paddock
+ * publishes an OpenAPI 3 document generated from these Fastify route schemas,
+ * and one path cannot describe two different 200 bodies there — it would have
+ * to be `additionalProperties: true` with no shape at all, which is the defect
+ * #822 was filed about. Cost confirms it independently: the probe is a readdir
+ * per project, the plan can be a second of scanning, and they have different
+ * call sites (every page load vs. when the modal opens).
+ *
+ * ## These schemas are deliberately NOT the house style
+ *
+ * Every other `response.200` in `packages/server/src/routes/` is
+ * `additionalProperties: true` with the real shape in English in the
+ * `description`. #822's stated preference is that shapes belong in the route
+ * schemas so the published spec describes them, so these two are written out in
+ * full: named fields, `required`, closed enums, `additionalProperties: false`.
+ *
+ * Treat the Fastify consequence as a feature: response serialization STRIPS
+ * undeclared keys, so a field added to the DTO and forgotten here disappears at
+ * runtime and the integration test catches it, rather than shipping
+ * undocumented.
+ *
+ * ## This reads `~/.claude`, and that is a posture change
+ *
+ * Under `transcripts: own` nothing in the user's own Claude home was read at
+ * all — `transcripts.ts` and `guides/what-paddock-touches.md` both promised
+ * exactly that. Telling `new` from `fast-forward` is impossible without reading
+ * it, so the plan endpoint does. It is behind its own route precisely so it is
+ * something the SPA asks for rather than something a fleet poll does silently,
+ * and both of those promises have been narrowed to match (design §8).
+ */
+import type { FastifyInstance } from "fastify";
+import type { RouteCtx } from "../route-context.js";
+/** Drop the single-flight latch. For tests, and for a process that somehow
+ *  leaked one — a stuck latch would refuse every future migration. */
+export declare function resetMigrationSingleFlight(): void;
+export declare function registerTranscriptsRoutes(app: FastifyInstance, ctx: RouteCtx): void;