@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/curation-config.js

@@ -0,0 +1,64 @@
+/**
+ * Sweeper curation budgets — the per-file token limits the post-turn curator
+ * keeps OVERVIEW.md / CHANGELOG.md / CLAUDE.md under (issue #379), with a
+ * per-project override layer (issue #384).
+ *
+ * ── Config discipline (the `recovery`/`driveMode` pattern) ────────────────────
+ * Every budget is an instance default (`PADDOCK_CURATION_*` env, YAML instance
+ * file beneath it — resolved in config.ts's `loadCurationConfig`) with an
+ * optional PER-PROJECT override (`project.yaml` →
+ * {@link import("./projects.js").ProjectYaml.curation}). An absent/invalid
+ * override inherits the instance default, resolved at sweep time by
+ * {@link resolveCurationConfig} — never baked into the DTO (mirrors how
+ * `recovery` resolves via `resolveRecoveryConfig`). A malformed override is
+ * ignored rather than fatal so a hand-edited `project.yaml` can't wedge a sweep.
+ *
+ * #379 shipped these instance-only; #384 adds the override so a docs-heavy
+ * project can raise its CHANGELOG budget (or a lean project tighten it) without
+ * changing the fleet-wide default.
+ */
+/** Built-in defaults when neither env nor YAML nor a project override sets a budget. */
+export const DEFAULT_CURATION = Object.freeze({
+    overviewMaxTokens: 2000,
+    changelogMaxTokens: 8000,
+    claudeMaxTokens: 6000,
+});
+/** True when `n` is a usable budget: a positive, finite integer. */
+function isPositiveInt(n) {
+    return typeof n === "number" && Number.isInteger(n) && n > 0 && Number.isFinite(n);
+}
+/**
+ * Validate + normalise an untrusted value (from `project.yaml` or a PATCH body)
+ * into a {@link CurationOverride}, dropping any field that is missing or invalid,
+ * and returning `undefined` when nothing valid remains (so an empty override is
+ * never persisted). Each budget must be a positive integer. Defensive by design —
+ * a malformed hand-edit degrades to "inherit the instance default", never a
+ * sweep crash.
+ */
+export function sanitizeCurationOverride(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const out = {};
+    if (isPositiveInt(o.overviewMaxTokens))
+        out.overviewMaxTokens = o.overviewMaxTokens;
+    if (isPositiveInt(o.changelogMaxTokens))
+        out.changelogMaxTokens = o.changelogMaxTokens;
+    if (isPositiveInt(o.claudeMaxTokens))
+        out.claudeMaxTokens = o.claudeMaxTokens;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the effective curation budgets for a sweep: a valid per-project
+ * override wins field-by-field; every absent field inherits the instance default
+ * (which is itself `env > paddock.config.yaml > built-in default`). The override
+ * is re-sanitised so a corrupt on-disk value can't leak through.
+ */
+export function resolveCurationConfig(override, instanceDefault) {
+    const clean = sanitizeCurationOverride(override) ?? {};
+    return {
+        overviewMaxTokens: clean.overviewMaxTokens ?? instanceDefault.overviewMaxTokens,
+        changelogMaxTokens: clean.changelogMaxTokens ?? instanceDefault.changelogMaxTokens,
+        claudeMaxTokens: clean.claudeMaxTokens ?? instanceDefault.claudeMaxTokens,
+    };
+}

package/packages/server/dist/event-bus.d.ts

@@ -0,0 +1,87 @@
+/**
+ * In-process lifecycle event bus (Epic G, ticket G1 — hook foundation).
+ *
+ * Paddock lifecycle events (a chat archived, later: created/forked/unarchived) fire
+ * INSIDE Paddock's own server — unlike schedules (Epic D), there is no herdctl seam
+ * to add. This tiny typed emitter is that seam: the place that COMMITS a lifecycle
+ * action ({@link ArchiveEvent}, from the archive route / the self-MCP archive tool)
+ * `emit`s the event AFTER it commits, and the hook dispatcher (wired in `ws.ts`)
+ * `on`s it to fire each of the project's enabled hooks via `startAgentTurn`.
+ *
+ * Two invariants make this safe as a foundation (GG-2, non-blocking after-commit):
+ *
+ *  1. **`emit` never throws into its caller and never blocks it.** Listeners run
+ *     fire-and-forget; a listener that throws (sync or async) is swallowed so the
+ *     triggering action (the archive) can NEVER fail or hang because of a hook. This
+ *     is the whole point — a buggy hook must not break the thing that triggered it.
+ *  2. **The bus event name IS a hook/trigger `event` value.** So a dispatcher is a
+ *     trivial `bus.on("onArchive", …)` that matches hooks/triggers with that `event`.
+ *     v1 wired `onArchive` (hooks + event triggers); T5 adds `afterTurn`, which drives
+ *     the folded-in sweeper (the default post-turn curator trigger).
+ *
+ * Kept deliberately minimal (no Node `EventEmitter`: its `error`-event footgun and
+ * default max-listener warnings are noise here) and dependency-free, matching the
+ * hand-rolled sidecar style of the rest of the server.
+ */
+/**
+ * Payload for the `onArchive` event: which chat, in which project, was archived.
+ * The dispatcher passes `slug` to resolve the project's hooks and `sessionId` into
+ * the fired hook's prompt so the hook knows WHAT was archived (e.g. which pm server
+ * / clone to tear down).
+ */
+export interface ArchiveEvent {
+    /** The project slug whose chat was archived. */
+    slug: string;
+    /** The archived chat's session id. */
+    sessionId: string;
+}
+/**
+ * Payload for the `afterTurn` event (Epic T / T5): a turn just completed in `slug`.
+ * Emitted at every post-turn commit site (a human chat turn, a session-mode wake, and
+ * every server-initiated `startAgentTurn`) so the folded-in sweeper — the default
+ * `curate-overview` `event`/`afterTurn` trigger — dispatches EXACTLY ONCE per turn.
+ * `sessionId` is the chat whose turn completed (`null` when none was resolved), carried
+ * for parity with `onArchive`; the curator only needs the `slug` to sweep.
+ */
+export interface AfterTurnEvent {
+    /** The project slug whose chat turn just completed. */
+    slug: string;
+    /** The completed turn's session id, or `null` if none was resolved. */
+    sessionId: string | null;
+}
+/**
+ * The typed event map. The bus event name IS a trigger/hook `event` value, so
+ * `on`/`emit` line up with the dispatchers. `onArchive` fires the enabled onArchive
+ * hooks + event triggers (Epic G/T); `afterTurn` (T5) drives the post-turn curator
+ * (the sweeper). Adding a sibling event is: a new value here + its payload + an `emit`
+ * at the commit site.
+ */
+export interface PaddockEventMap {
+    onArchive: ArchiveEvent;
+    afterTurn: AfterTurnEvent;
+}
+/** A lifecycle event name — a key of {@link PaddockEventMap}, matching a trigger/hook event. */
+export type PaddockEventName = keyof PaddockEventMap;
+/** A listener for event `E`; may be async — its result is awaited-and-swallowed. */
+export type EventListener<E extends PaddockEventName> = (payload: PaddockEventMap[E]) => void | Promise<void>;
+/**
+ * A minimal typed publish/subscribe hub. One instance is constructed in `app.ts` and
+ * shared by the commit sites (archive route / self-MCP archive tool → `emit`) and the
+ * hook dispatcher in `ws.ts` (→ `on`).
+ */
+export declare class PaddockEventBus {
+    private readonly listeners;
+    /**
+     * Subscribe `listener` to `event`. Returns an unsubscribe function. Multiple
+     * listeners per event are supported (v1 registers one — the hook dispatcher).
+     */
+    on<E extends PaddockEventName>(event: E, listener: EventListener<E>): () => void;
+    /**
+     * Fire `event` to every subscribed listener, FIRE-AND-FORGET. Returns immediately
+     * (never awaits a listener) and never throws into the caller — a listener that
+     * throws synchronously or rejects asynchronously is swallowed. So the action that
+     * emitted the event (an archive commit) is fully decoupled from hook execution: it
+     * neither waits on hooks nor fails because of them (GG-2).
+     */
+    emit<E extends PaddockEventName>(event: E, payload: PaddockEventMap[E]): void;
+}

package/packages/server/dist/event-bus.js

@@ -0,0 +1,48 @@
+/**
+ * A minimal typed publish/subscribe hub. One instance is constructed in `app.ts` and
+ * shared by the commit sites (archive route / self-MCP archive tool → `emit`) and the
+ * hook dispatcher in `ws.ts` (→ `on`).
+ */
+export class PaddockEventBus {
+    listeners = new Map();
+    /**
+     * Subscribe `listener` to `event`. Returns an unsubscribe function. Multiple
+     * listeners per event are supported (v1 registers one — the hook dispatcher).
+     */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => {
+            this.listeners.get(event)?.delete(listener);
+        };
+    }
+    /**
+     * Fire `event` to every subscribed listener, FIRE-AND-FORGET. Returns immediately
+     * (never awaits a listener) and never throws into the caller — a listener that
+     * throws synchronously or rejects asynchronously is swallowed. So the action that
+     * emitted the event (an archive commit) is fully decoupled from hook execution: it
+     * neither waits on hooks nor fails because of them (GG-2).
+     */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set || set.size === 0)
+            return;
+        for (const listener of set) {
+            try {
+                // A listener may be sync or async. Wrap in Promise.resolve so a synchronous
+                // throw and an async rejection are both funneled into the same swallow — the
+                // emitter's caller is never affected either way.
+                void Promise.resolve()
+                    .then(() => listener(payload))
+                    .catch(() => undefined);
+            }
+            catch {
+                /* a synchronous throw before the microtask — swallow too */
+            }
+        }
+    }
+}

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

@@ -0,0 +1,128 @@
+/**
+ * Clone an external git repo into `dest` — the checkout that becomes a
+ * repo-backed project's working directory (issue #187). Shells out to the `git`
+ * binary via execFile (arg array, no shell → no injection surface), the same
+ * discipline as {@link GitService}.
+ *
+ * A FULL clone (not `--depth 1`): a repo-backed project is where you *do
+ * engineering*, so the keeper wants real history — `git log`, blame, bisect, and
+ * a non-shallow base for branches/PRs — from the start. Credentials are the
+ * ambient git environment's job (a public URL needs none; a private repo needs a
+ * box-level credential helper / token — per-project scoped credentials are a
+ * documented #187 follow-up). Throws with git's stderr on failure so the caller
+ * can surface a clean error and roll back the half-created project.
+ */
+export declare function cloneRepo(url: string, dest: string): Promise<void>;
+/** A single changed path within a project (porcelain v1 semantics). */
+export interface GitFileChange {
+    /** Path relative to the project directory. */
+    path: string;
+    /** Two-letter porcelain code, trimmed (e.g. "M", "??", "A", "RM"). */
+    status: string;
+    /** Whether the change is staged (index differs from HEAD). */
+    staged: boolean;
+    /** True for an untracked ("??") path. */
+    untracked: boolean;
+    /** Lines added (undefined for a binary change). Untracked text files count as all-added. */
+    added?: number;
+    /** Lines removed (undefined for a binary change / an untracked file). */
+    removed?: number;
+    /** True when the change is binary (no line-level stat). */
+    binary?: boolean;
+}
+/** A project's git status (or `repo: false` when the store isn't a repo). */
+export interface GitProjectStatus {
+    /** Whether `projectsRoot` is a git working tree at all. */
+    repo: boolean;
+    /** Current branch (omitted when not a repo / detached). */
+    branch?: string;
+    /** Changes confined to this project's subtree. */
+    files: GitFileChange[];
+    /** True when the project subtree has no pending changes. */
+    clean: boolean;
+}
+export declare class GitService {
+    private readonly projectsRoot;
+    private readonly author;
+    /** Cached repo-detection result for `projectsRoot` (null = not yet checked). */
+    private repoFlag;
+    /**
+     * @param projectsRoot Absolute path to the projects root the service operates on.
+     * @param author Commit identity used when Paddock commits on a project's behalf.
+     *   Folded into PaddockConfig from `PADDOCK_GIT_AUTHOR_*` (issue #269); defaults
+     *   preserve the pre-fold values so a bare `new GitService(root)` is unchanged.
+     */
+    constructor(projectsRoot: string, author?: {
+        name: string;
+        email: string;
+    });
+    /** Run git in a directory, returning stdout. Throws on non-zero exit. */
+    private git;
+    /**
+     * Whether the backing store is a git working tree. Cached after the first
+     * successful check (repo-ness doesn't change under a running server); a thrown
+     * git / missing-binary error resolves to `false`.
+     */
+    isRepo(): Promise<boolean>;
+    /** Force the next `isRepo()` to re-check (e.g. after `git init` at runtime). */
+    resetRepoCache(): void;
+    /**
+     * Status for one project's subtree. Returns `{ repo: false }` when the store
+     * isn't a repo (the UI then hides the git affordance). Paths are relative to
+     * `projectDir`.
+     */
+    projectStatus(projectDir: string): Promise<GitProjectStatus>;
+    /**
+     * `git diff --numstat` for a project's tracked working-tree changes, keyed by
+     * PROJECT-relative path (`--relative` makes git emit paths relative to the
+     * project dir, matching the porcelain paths). Binary changes report `-\t-` and
+     * are flagged `binary`. Returns an empty map on any failure.
+     */
+    private trackedNumstat;
+    /**
+     * Unified diff for a project's tracked changes (working tree vs HEAD), or for
+     * a single file when `file` is given. Untracked files don't appear in a diff
+     * (they're listed by `projectStatus`). Returns "" when not a repo / no diff.
+     */
+    projectDiff(projectDir: string, file?: string): Promise<string>;
+    /** Commit identity (from config, no global git config needed). */
+    private identity;
+    /** Origin remote info + ahead/behind vs upstream (best-effort). */
+    remote(): Promise<{
+        repo: boolean;
+        configured: boolean;
+        url?: string;
+        branch?: string;
+        ahead?: number;
+        behind?: number;
+    }>;
+    /**
+     * Stage + commit a single project's changes (tracked mods, deletions, and
+     * untracked files within its subtree). `committed: false` when nothing was
+     * pending. Explicit identity so the LXC needs no global git config.
+     *
+     * When `paths` (project-relative) is given, commit ONLY those files — the
+     * pathspec scopes both the staging and the commit, so unselected changes stay
+     * uncommitted (issue #258). Paths are validated to stay inside the subtree; an
+     * all-invalid selection is an error rather than a silent commit-everything.
+     * Omitting `paths` keeps the legacy commit-the-whole-subtree behavior.
+     */
+    commitProject(projectDir: string, message: string, paths?: string[]): Promise<{
+        committed: boolean;
+        hash?: string;
+        error?: string;
+    }>;
+    /**
+     * Uncommitted-file counts per top-level project subtree, in ONE `git status`
+     * over the whole store (cheap — no per-project fan-out) so the projects grid
+     * can flag "N uncommitted" without opening each project (issue #258). Keyed by
+     * the first path segment (= project slug); only dirty projects appear. `{}`
+     * when the store isn't a repo.
+     */
+    dirtyCounts(): Promise<Record<string, number>>;
+    /** Push the current branch to origin (sets upstream on first push). */
+    push(): Promise<{
+        pushed: boolean;
+        error?: string;
+    }>;
+}