@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/parent-detach.js

@@ -0,0 +1,109 @@
+/**
+ * ParentDetachStore — a Paddock-side sidecar recording which chats the user has
+ * explicitly DETACHED from their parent (#508).
+ *
+ * The nested chat list (#485) draws a chat under its parent, and that edge is
+ * resolved in two tiers (see `makeParentResolver`): the RECORDED
+ * `RunProvenance.parentSessionId`, and — for chats created before that field
+ * existed — an edge INFERRED from who injected the kickoff message. Detach
+ * therefore cannot be implemented by clearing the recorded edge: the inference
+ * tier would simply re-derive the old parent on the next page load. It needs an
+ * explicit, persisted "this chat is a root, whatever the tiers say" sentinel that
+ * is checked AHEAD of both.
+ *
+ * That sentinel lives here rather than on {@link RunProvenance}, which #508
+ * suggested. Provenance is documented — and implemented — as write-once creation
+ * metadata: "stamped once, at creation, and NEVER clobbered by a later turn".
+ * Detach is a user decision made long after creation, and a chat with no recorded
+ * provenance at all (every pre-#485 chat, i.e. exactly the population whose parent
+ * is inferred) would have needed an `origin`/`depth` fabricated for it just to
+ * carry the flag — which would then show a "spawned" badge the chat never earned.
+ * A separate flag keeps provenance honest and detach cheap.
+ *
+ * Shape/pattern is a near-verbatim copy of {@link ArchiveStore} — a tiny JSON
+ * array sidecar in the data dir, lazy-loaded, write-through, serialised,
+ * corruption-tolerant. Keyed by `<agent>\0<sessionId>` (NUL-separated) like
+ * archive/star, and SHARED rather than per-user: detaching restructures the list
+ * everyone sees, so it is not personal state the way read/unread is.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "parent-detach.json";
+/** Separator in a storage key; a NUL can't occur in an agent name or a UUID. */
+const KEY_SEP = "\u0000";
+/** Compose the storage key for an (agent, session) pair. */
+function keyOf(agent, sessionId) {
+    return `${agent}${KEY_SEP}${sessionId}`;
+}
+export class ParentDetachStore {
+    stateFile;
+    /** In-memory set of detached keys (loaded once, written through on change). */
+    detached = null;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read — the
+     * same lost-update guard {@link ArchiveStore} carries.
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted set (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.detached)
+            return Promise.resolve(this.detached);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                let keys = [];
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        keys = parsed.filter((k) => typeof k === "string");
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.detached = new Set(keys);
+                return this.detached;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /**
+     * Has this chat been detached from its parent? Non-throwing: any load error
+     * reads as false, so a corrupt sidecar degrades to "nesting as recorded"
+     * rather than flattening the whole list.
+     */
+    async isDetached(agent, sessionId) {
+        const set = await this.ensureLoaded().catch(() => new Set());
+        return set.has(keyOf(agent, sessionId));
+    }
+    /**
+     * Set (or clear) a chat's detached flag, persisting the change. Idempotent;
+     * returns whether the flag actually CHANGED. Clearing it re-exposes whatever
+     * the two resolver tiers say — which is what makes re-attach free: nothing was
+     * ever destroyed, only overridden.
+     */
+    async setDetached(agent, sessionId, detached) {
+        const set = await this.ensureLoaded();
+        const key = keyOf(agent, sessionId);
+        if (detached === set.has(key))
+            return false; // no-op — avoid a needless write
+        if (detached)
+            set.add(key);
+        else
+            set.delete(key);
+        await this.persist(set);
+        return true;
+    }
+    /** Write-through, serialised so overlapping toggles can't corrupt the file. */
+    persist(set) {
+        this.writing = this.writing.then(async () => {
+            const json = JSON.stringify([...set], null, 2);
+            await fs.writeFile(this.stateFile, json, "utf8").catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * The project-context "preload" wrapper (issue #1) — single-sourced here so the
+ * WS layer that BUILDS it and the chat-list that STRIPS it for display can't
+ * drift (issue #62).
+ *
+ * On the first turn of a new project chat with preload enabled, the server
+ * prepends the project's curated context — OVERVIEW.md (current state) plus
+ * CHANGELOG.md (cross-session history, issue #188) — to the user's message as a
+ * delimited block:
+ *
+ *   <project-context>
+ *   …OVERVIEW.md…
+ *
+ *   …CHANGELOG.md…
+ *   </project-context>
+ *
+ *   My request:
+ *   <the user's actual message>
+ *
+ * That block becomes the session's first user message, so Claude Code's derived
+ * preview (and thus the sidebar name) is the context text, not the request —
+ * exactly the #62 complaint. {@link stripPreloadWrapper} recovers the request.
+ */
+export declare const PRELOAD_CONTEXT_OPEN = "<project-context>";
+/** The literal boundary between the context block and the user's real request. */
+export declare const PRELOAD_REQUEST_MARKER = "</project-context>\n\nMy request:\n";
+/**
+ * Assemble the preload context body from the project's curated docs (issue
+ * #188). OVERVIEW.md carries current state; CHANGELOG.md carries the
+ * cross-session narrative — both reach the chat so the history is no longer
+ * write-only. Each doc self-labels via its own `#` heading, so they are joined
+ * with a blank line; empty docs are dropped.
+ */
+export declare function composePreloadContext(overview: string, changelog: string): string;
+/** Build the preload-wrapped prompt for a new project chat's first turn. */
+export declare function wrapPreload(context: string, message: string): string;
+/**
+ * Recover the user's real request from a (possibly) preload-wrapped message. If
+ * `text` isn't the wrapper it's returned unchanged; if it is, everything after
+ * the `My request:` marker is returned. Returns the input unchanged when the
+ * marker is absent (e.g. the wrapper was truncated before it).
+ */
+export declare function stripPreloadWrapper(text: string): string;

package/packages/server/dist/preload.js

@@ -0,0 +1,55 @@
+/**
+ * The project-context "preload" wrapper (issue #1) — single-sourced here so the
+ * WS layer that BUILDS it and the chat-list that STRIPS it for display can't
+ * drift (issue #62).
+ *
+ * On the first turn of a new project chat with preload enabled, the server
+ * prepends the project's curated context — OVERVIEW.md (current state) plus
+ * CHANGELOG.md (cross-session history, issue #188) — to the user's message as a
+ * delimited block:
+ *
+ *   <project-context>
+ *   …OVERVIEW.md…
+ *
+ *   …CHANGELOG.md…
+ *   </project-context>
+ *
+ *   My request:
+ *   <the user's actual message>
+ *
+ * That block becomes the session's first user message, so Claude Code's derived
+ * preview (and thus the sidebar name) is the context text, not the request —
+ * exactly the #62 complaint. {@link stripPreloadWrapper} recovers the request.
+ */
+export const PRELOAD_CONTEXT_OPEN = "<project-context>";
+/** The literal boundary between the context block and the user's real request. */
+export const PRELOAD_REQUEST_MARKER = "</project-context>\n\nMy request:\n";
+/**
+ * Assemble the preload context body from the project's curated docs (issue
+ * #188). OVERVIEW.md carries current state; CHANGELOG.md carries the
+ * cross-session narrative — both reach the chat so the history is no longer
+ * write-only. Each doc self-labels via its own `#` heading, so they are joined
+ * with a blank line; empty docs are dropped.
+ */
+export function composePreloadContext(overview, changelog) {
+    return [overview, changelog]
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0)
+        .join("\n\n");
+}
+/** Build the preload-wrapped prompt for a new project chat's first turn. */
+export function wrapPreload(context, message) {
+    return `${PRELOAD_CONTEXT_OPEN}\n${context.trim()}\n${PRELOAD_REQUEST_MARKER}${message}`;
+}
+/**
+ * Recover the user's real request from a (possibly) preload-wrapped message. If
+ * `text` isn't the wrapper it's returned unchanged; if it is, everything after
+ * the `My request:` marker is returned. Returns the input unchanged when the
+ * marker is absent (e.g. the wrapper was truncated before it).
+ */
+export function stripPreloadWrapper(text) {
+    if (!text.startsWith(PRELOAD_CONTEXT_OPEN))
+        return text;
+    const i = text.indexOf(PRELOAD_REQUEST_MARKER);
+    return i === -1 ? text : text.slice(i + PRELOAD_REQUEST_MARKER.length);
+}

package/packages/server/dist/project-files.d.ts

@@ -0,0 +1,76 @@
+import type { FileEntry, FileKind } from "./project-types.js";
+/**
+ * Resolve a freeform file name to an absolute path inside the project dir,
+ * rejecting path traversal AND traversal *through* a hidden (dot-prefixed)
+ * directory. The single guard shared by every file read and by the directory
+ * listing (issue #259). The project root itself (`name === ""`) resolves to the
+ * project dir and is allowed, so a root listing passes through.
+ *
+ * **Why hidden directories are refused, not merely omitted.** {@link listFiles}
+ * drops dot-prefixed entries from what it *returns*, which is presentation, not
+ * access control: naming the path explicitly still resolved it. And the read
+ * route's `:name` param decodes `%2F`, so a nominally single-segment route
+ * accepts a whole nested path. Together those let a caller read
+ * `…/files/.chats%2F<id>.jsonl` (a full chat transcript) or
+ * `…/files/.git%2Fconfig` (which carries credentials when a remote embeds a
+ * token). The root project (#516) widened the blast radius from one project's
+ * subtree to the instance's own backing repo and every project at once.
+ *
+ * **Why the LEAF may still be a dotfile.** Refusing every dot segment was the
+ * first cut, and it broke Changes: an UNTRACKED file has no diff, so the pane
+ * renders its content through this very surface — and `.gitignore` is untracked
+ * in a freshly-created repo-backed project, because `ensureSidecarGitignore`
+ * writes it. So a legitimate, visible-in-the-UI file became unopenable. The harm
+ * is *descending into* `.git/` and `.chats/`, not reading a dotfile git is
+ * already showing you, so the guard is scoped to directory segments.
+ * {@link listFiles} additionally refuses a hidden LEAF, because listing one is
+ * how `?path=.chats` enumerated every transcript.
+ *
+ * Honest severity: **defense-in-depth, not a privilege boundary.** Paddock has
+ * no per-user role model, and any caller who can reach these routes can already
+ * start a keeper chat and run Bash — strictly more capability than reading a
+ * file. The `/mcp` read-only token surface exposes no file verb, so it is not
+ * reachable there either. This is worth closing because "hidden in the listing"
+ * should not be the only thing standing between an API and a transcript, not
+ * because it grants anything new.
+ */
+export declare function resolveInProject(root: string, slug: string, name: string): string;
+/**
+ * List one level of a project directory (issue #259). `subpath` is a
+ * project-relative directory ("" = the project root); the returned entries
+ * carry a `kind` so the UI can distinguish (and descend into) subdirectories.
+ * Dotfiles are hidden as before; entries sort directories-first, then by name.
+ *
+ * Traversal is guarded by the shared `resolveInProject`, so `subpath` can't
+ * escape the project dir. Throws `ProjectError("not_found")` when the directory
+ * doesn't exist and `ProjectError("not_directory")` when `subpath` is a file —
+ * the latter lets the caller fall back to rendering that file.
+ */
+export declare function listFiles(root: string, slug: string, subpath?: string): Promise<FileEntry[]>;
+/** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
+export declare function readProjectFile(root: string, slug: string, name: string): Promise<string>;
+/**
+ * Read a file's raw bytes + its MIME type (issue #61), for the binary/image
+ * endpoint. Path-traversal guarded; throws ProjectError("not_found") if the
+ * file is missing so the route can 404 cleanly. NOT decoded as text, so binary
+ * (image) bytes survive intact.
+ */
+export declare function readFileBytes(root: string, slug: string, name: string): Promise<{
+    bytes: Buffer;
+    mime: string;
+}>;
+/**
+ * Read a file plus a render-kind hint derived from its extension, for the
+ * UI's markdown/Mermaid + sandboxed-iframe renderers (issue #3) and the image
+ * viewer (issue #61).
+ *
+ * For an IMAGE the raw bytes are NOT returned here (decoding binary as UTF-8
+ * would mangle it): `content` is empty and the client fetches the bytes from
+ * the raw endpoint. We still stat the file so a missing image 404s. Path-
+ * traversal guarded; throws ProjectError("not_found") when missing.
+ */
+export declare function readFileWithKind(root: string, slug: string, name: string): Promise<{
+    name: string;
+    kind: FileKind;
+    content: string;
+}>;

package/packages/server/dist/project-files.js

@@ -0,0 +1,191 @@
+/**
+ * project-files — the read-only freeform-file surface for a project directory.
+ *
+ * Extracted from projects.ts (issue #403): the path-traversal guard plus the
+ * directory listing + file readers (text / raw bytes / kind-hinted). Pure free
+ * functions taking `(root, slug, …)` — no `ProjectStore` state beyond the
+ * projects root — so `ProjectStore` keeps thin delegate methods over these and
+ * the public API is unchanged. `ProjectError` codes are preserved exactly.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ProjectError } from "./project-paths.js";
+import { fileKind, contentTypeFor } from "./project-mime.js";
+/**
+ * The directory backing a workspace key — a second copy of
+ * `ProjectStore.dirFor`'s resolution, kept in step by being the same one-liner.
+ *
+ * A key is a path relative to the projects root and the root workspace's key is
+ * `""`, so `path.join` handles both with no branch. That matters historically:
+ * the previous design DID need a branch here for a reserved slug, this copy was
+ * missed, and every root file route 404'd until it was found in live QA. There
+ * is no longer a branch to miss.
+ *
+ * The traversal guard below is unaffected: it compares against whatever this
+ * returns, so at the root "inside the workspace dir" means "inside the projects
+ * root" — exactly the scope of a keeper whose cwd is that directory.
+ */
+function dirFor(root, key) {
+    return path.join(root, key);
+}
+/**
+ * Resolve a freeform file name to an absolute path inside the project dir,
+ * rejecting path traversal AND traversal *through* a hidden (dot-prefixed)
+ * directory. The single guard shared by every file read and by the directory
+ * listing (issue #259). The project root itself (`name === ""`) resolves to the
+ * project dir and is allowed, so a root listing passes through.
+ *
+ * **Why hidden directories are refused, not merely omitted.** {@link listFiles}
+ * drops dot-prefixed entries from what it *returns*, which is presentation, not
+ * access control: naming the path explicitly still resolved it. And the read
+ * route's `:name` param decodes `%2F`, so a nominally single-segment route
+ * accepts a whole nested path. Together those let a caller read
+ * `…/files/.chats%2F<id>.jsonl` (a full chat transcript) or
+ * `…/files/.git%2Fconfig` (which carries credentials when a remote embeds a
+ * token). The root project (#516) widened the blast radius from one project's
+ * subtree to the instance's own backing repo and every project at once.
+ *
+ * **Why the LEAF may still be a dotfile.** Refusing every dot segment was the
+ * first cut, and it broke Changes: an UNTRACKED file has no diff, so the pane
+ * renders its content through this very surface — and `.gitignore` is untracked
+ * in a freshly-created repo-backed project, because `ensureSidecarGitignore`
+ * writes it. So a legitimate, visible-in-the-UI file became unopenable. The harm
+ * is *descending into* `.git/` and `.chats/`, not reading a dotfile git is
+ * already showing you, so the guard is scoped to directory segments.
+ * {@link listFiles} additionally refuses a hidden LEAF, because listing one is
+ * how `?path=.chats` enumerated every transcript.
+ *
+ * Honest severity: **defense-in-depth, not a privilege boundary.** Paddock has
+ * no per-user role model, and any caller who can reach these routes can already
+ * start a keeper chat and run Bash — strictly more capability than reading a
+ * file. The `/mcp` read-only token surface exposes no file verb, so it is not
+ * reachable there either. This is worth closing because "hidden in the listing"
+ * should not be the only thing standing between an API and a transcript, not
+ * because it grants anything new.
+ */
+export function resolveInProject(root, slug, name) {
+    const dir = dirFor(root, slug);
+    const resolved = path.resolve(dir, name);
+    if (resolved !== dir && !resolved.startsWith(dir + path.sep)) {
+        throw new ProjectError("Invalid file path", "invalid");
+    }
+    // Check the RESOLVED path's segments relative to the project dir, not the
+    // caller's raw string: `a/./.git/config` and `a/../.git/config` both normalise
+    // to a hidden directory segment the raw string doesn't literally contain. The
+    // project dir itself may legitimately sit under a dot-prefixed ancestor (a
+    // data dir like `/srv/.paddock/projects`), which is why only the relative part
+    // is examined. `slice(0, -1)` leaves the leaf to the caller (see doc-comment).
+    const segments = relSegments(dir, resolved);
+    if (segments.slice(0, -1).some(isHidden)) {
+        throw new ProjectError("Invalid file path", "invalid");
+    }
+    return resolved;
+}
+/** Path segments of `resolved` relative to `dir` ([] when they're the same). */
+function relSegments(dir, resolved) {
+    const rel = path.relative(dir, resolved);
+    return rel ? rel.split(path.sep) : [];
+}
+function isHidden(segment) {
+    return segment.startsWith(".");
+}
+/**
+ * List one level of a project directory (issue #259). `subpath` is a
+ * project-relative directory ("" = the project root); the returned entries
+ * carry a `kind` so the UI can distinguish (and descend into) subdirectories.
+ * Dotfiles are hidden as before; entries sort directories-first, then by name.
+ *
+ * Traversal is guarded by the shared `resolveInProject`, so `subpath` can't
+ * escape the project dir. Throws `ProjectError("not_found")` when the directory
+ * doesn't exist and `ProjectError("not_directory")` when `subpath` is a file —
+ * the latter lets the caller fall back to rendering that file.
+ */
+export async function listFiles(root, slug, subpath = "") {
+    const target = resolveInProject(root, slug, subpath);
+    // A LISTING target is a directory, so unlike a read the leaf gets no pass:
+    // `?path=.chats` is exactly how every transcript filename was enumerable.
+    const leaf = relSegments(dirFor(root, slug), target).at(-1);
+    if (leaf && isHidden(leaf)) {
+        throw new ProjectError("Invalid file path", "invalid");
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(target, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            throw new ProjectError(`Directory not found: ${subpath}`, "not_found");
+        if (code === "ENOTDIR")
+            throw new ProjectError(`Not a directory: ${subpath}`, "not_directory");
+        throw err;
+    }
+    return entries
+        .filter((e) => !e.name.startsWith("."))
+        .map((e) => ({ name: e.name, kind: e.isDirectory() ? "dir" : "file" }))
+        .sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "dir" ? -1 : 1);
+}
+/** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
+export async function readProjectFile(root, slug, name) {
+    return fs.readFile(resolveInProject(root, slug, name), "utf8");
+}
+/**
+ * Read a file's raw bytes + its MIME type (issue #61), for the binary/image
+ * endpoint. Path-traversal guarded; throws ProjectError("not_found") if the
+ * file is missing so the route can 404 cleanly. NOT decoded as text, so binary
+ * (image) bytes survive intact.
+ */
+export async function readFileBytes(root, slug, name) {
+    const resolved = resolveInProject(root, slug, name);
+    try {
+        const bytes = await fs.readFile(resolved);
+        return { bytes, mime: contentTypeFor(name) };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new ProjectError(`File not found: ${name}`, "not_found");
+        }
+        throw err;
+    }
+}
+/**
+ * Read a file plus a render-kind hint derived from its extension, for the
+ * UI's markdown/Mermaid + sandboxed-iframe renderers (issue #3) and the image
+ * viewer (issue #61).
+ *
+ * For an IMAGE the raw bytes are NOT returned here (decoding binary as UTF-8
+ * would mangle it): `content` is empty and the client fetches the bytes from
+ * the raw endpoint. We still stat the file so a missing image 404s. Path-
+ * traversal guarded; throws ProjectError("not_found") when missing.
+ */
+export async function readFileWithKind(root, slug, name) {
+    const kind = fileKind(name);
+    if (kind === "image") {
+        // Existence check only — the bytes go over the raw endpoint.
+        try {
+            await fs.stat(resolveInProject(root, slug, name));
+        }
+        catch (err) {
+            if (err instanceof ProjectError)
+                throw err;
+            if (err.code === "ENOENT") {
+                throw new ProjectError(`File not found: ${name}`, "not_found");
+            }
+            throw err;
+        }
+        return { name, kind, content: "" };
+    }
+    let content;
+    try {
+        content = await readProjectFile(root, slug, name);
+    }
+    catch (err) {
+        if (err instanceof ProjectError)
+            throw err; // traversal -> "invalid"
+        if (err.code === "ENOENT") {
+            throw new ProjectError(`File not found: ${name}`, "not_found");
+        }
+        throw err;
+    }
+    return { name, kind, content };
+}

package/packages/server/dist/project-mime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * project-mime — MIME maps + file-kind/content-type helpers for project files.
+ *
+ * Extracted from projects.ts (issue #403) as a zero-coupling leaf module: the
+ * three extension→MIME maps plus the two pure classifiers (`fileKind` for the UI
+ * renderer choice, `contentTypeFor` for the raw-byte endpoint's Content-Type).
+ * Re-exported from projects.ts so existing importers keep resolving in one place.
+ */
+import type { FileKind } from "./project-types.js";
+/**
+ * Image extensions → their MIME type, for the render kind + the raw byte
+ * endpoint's Content-Type (issue #61). SVG is included but is served with a
+ * locked-down CSP by the byte route (it can carry scripts).
+ */
+export declare const IMAGE_MIME: Record<string, string>;
+/**
+ * Video extensions → their MIME type, for the raw byte endpoint's Content-Type
+ * (issue #126). Kept SEPARATE from IMAGE_MIME so the image file-kind classifier
+ * (`fileKind`) is untouched — video only affects the content-type served, which
+ * (together with HTTP range support) is what lets a `<video>` play, incl. iOS.
+ */
+export declare const VIDEO_MIME: Record<string, string>;
+/**
+ * Non-image document extensions → their MIME type. Kept SEPARATE from
+ * `IMAGE_MIME` on purpose: the file-kind classifier (`fileKind`) treats every
+ * `IMAGE_MIME` entry as `kind: "image"`, so a `.pdf` must not live there. It's
+ * used only for the byte endpoint's Content-Type (a PDF must serve as
+ * `application/pdf`, not the octet-stream the attachment store rewrites to
+ * `text/plain`).
+ */
+export declare const DOCUMENT_MIME: Record<string, string>;
+/** Derive a render kind from a file name's extension. */
+export declare function fileKind(name: string): FileKind;
+/** The MIME type for a file name's extension, defaulting to octet-stream. */
+export declare function contentTypeFor(name: string): string;

package/packages/server/dist/project-mime.js

@@ -0,0 +1,55 @@
+/**
+ * Image extensions → their MIME type, for the render kind + the raw byte
+ * endpoint's Content-Type (issue #61). SVG is included but is served with a
+ * locked-down CSP by the byte route (it can carry scripts).
+ */
+export const IMAGE_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".svg": "image/svg+xml",
+};
+/**
+ * Video extensions → their MIME type, for the raw byte endpoint's Content-Type
+ * (issue #126). Kept SEPARATE from IMAGE_MIME so the image file-kind classifier
+ * (`fileKind`) is untouched — video only affects the content-type served, which
+ * (together with HTTP range support) is what lets a `<video>` play, incl. iOS.
+ */
+export const VIDEO_MIME = {
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".m4v": "video/x-m4v",
+};
+/**
+ * Non-image document extensions → their MIME type. Kept SEPARATE from
+ * `IMAGE_MIME` on purpose: the file-kind classifier (`fileKind`) treats every
+ * `IMAGE_MIME` entry as `kind: "image"`, so a `.pdf` must not live there. It's
+ * used only for the byte endpoint's Content-Type (a PDF must serve as
+ * `application/pdf`, not the octet-stream the attachment store rewrites to
+ * `text/plain`).
+ */
+export const DOCUMENT_MIME = {
+    ".pdf": "application/pdf",
+};
+/** Derive a render kind from a file name's extension. */
+export function fileKind(name) {
+    const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+    if (ext === ".md" || ext === ".markdown")
+        return "markdown";
+    if (ext === ".html" || ext === ".htm")
+        return "html";
+    if (ext in IMAGE_MIME)
+        return "image";
+    return "text";
+}
+/** The MIME type for a file name's extension, defaulting to octet-stream. */
+export function contentTypeFor(name) {
+    const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+    return (IMAGE_MIME[ext] ?? VIDEO_MIME[ext] ?? DOCUMENT_MIME[ext] ?? "application/octet-stream");
+}

package/packages/server/dist/project-paths.d.ts

@@ -0,0 +1,88 @@
+export declare const SLUG_RE: RegExp;
+/**
+ * A **workspace key** is a workspace's path RELATIVE to `projectsRoot`.
+ *
+ * The root workspace's key is the empty string. That is not a sentinel — it is
+ * the zero value already present in the key space, and it is what makes the
+ * resolution seam vanish instead of branch:
+ *
+ * ```ts
+ * dirFor(key) => path.join(this.root, key)   // path.join(root, "") === root
+ * ```
+ *
+ * The previous design (issue #516) modelled the root as a *project* with a
+ * reserved slug `__root`, which forced a `dirFor` branch — duplicated in
+ * `project-files.ts`, where it was missed, 404ing every root file route. With a
+ * relative-path key there is no branch to forget.
+ *
+ * A project is a workspace with a non-empty key. Nested workspaces (`repo/sub`)
+ * are simply longer relative paths; nothing here assumes a single segment.
+ */
+export type WorkspaceKey = string;
+/** The root workspace's key: its path relative to `projectsRoot` is empty. */
+export declare const ROOT_KEY: WorkspaceKey;
+/** Whether a key addresses the root workspace (i.e. `projectsRoot` itself). */
+export declare function isRootKey(key: WorkspaceKey): boolean;
+/**
+ * The root workspace's name in the **herdctl agent namespace**.
+ *
+ * This is the one place a sentinel is unavoidable, because that namespace
+ * genuinely cannot represent the empty key: herdctl agent names must be
+ * non-empty and must satisfy TWO disagreeing patterns — `AGENT_NAME_PATTERN`
+ * (`/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/`, used by `addAgent`) and the session store's
+ * `SAFE_IDENTIFIER_PATTERN` (`/^[a-zA-Z0-9]([a-zA-Z0-9_.-]*[a-zA-Z0-9])?$/`,
+ * which requires a trailing alphanumeric). A bare `keeper-` fails both, and the
+ * shape #516 originally proposed (`keeper-__root__`) registered cleanly and then
+ * threw PathTraversalError on the first resume.
+ *
+ * `_root` satisfies both patterns and can never collide with a project, because
+ * {@link SLUG_RE} rejects underscores — no slug can equal it.
+ *
+ * **This is a NAME, not an identity.** A workspace is identified by its relative
+ * path ({@link WorkspaceKey}); this encoding exists only at the herdctl
+ * boundary, is applied in one function, and keeps the four agent-name builders
+ * (`keeper-`/`sweeper-`/`hook-`/`trigger-`) uniform with no root branch.
+ */
+export declare const ROOT_AGENT_KEY = "_root";
+/** Encode a workspace key for use inside a herdctl agent name. */
+export declare function agentKeyFor(key: WorkspaceKey): string;
+/** Decode a herdctl agent-name segment back to a workspace key. */
+export declare function keyFromAgentKey(agentKey: string): WorkspaceKey;
+/**
+ * Accepted repo-URL shapes for a repo-backed project (issue #187): https(s),
+ * ssh (`git@host:owner/repo`), git://, and a local `file://` or absolute path
+ * (the last two make deterministic tests possible without a network). Anything
+ * else is rejected up front so a bad value never reaches `git clone`.
+ */
+export declare const REPO_URL_RE: RegExp;
+/** Validate a candidate repo URL (issue #187). */
+export declare function isValidRepoUrl(url: string): boolean;
+/**
+ * Derive the checkout directory NAME for a repo-backed project from its repo URL
+ * (issue #187) — the repo's own basename, sans a trailing `.git`, sanitised to a
+ * filesystem-safe token. The keeper's cwd becomes `<projectDir>/<thisName>`, so
+ * the cwd basename reads like the repo (e.g. `paddock`). Deterministic (same URL
+ * ⇒ same name), which is why `repo` is immutable once set.
+ */
+export declare function repoCheckoutName(repo: string): string;
+/**
+ * Resolve a project's working directory (keeper cwd) from its metadata dir + repo
+ * URL: the nested checkout for a repo-backed project, else the metadata dir
+ * itself for a notebook project (issue #187).
+ */
+export declare function workingDirFor(dir: string, repo?: string): string;
+export declare class ProjectError extends Error {
+    readonly code: "not_found" | "exists" | "invalid" | "not_directory";
+    constructor(message: string, code: "not_found" | "exists" | "invalid" | "not_directory");
+}
+export declare function slugify(name: string): string;
+export declare function today(): string;
+/**
+ * Minimal seed for a per-project CLAUDE.md (issue #177): the durable-identity
+ * layer of the two-level native-context model (instance-wide + per-project
+ * CLAUDE.md, loaded natively once #176 lands). Deliberately terse — the sweeper
+ * amends it conservatively over time under "Curated notes"; everything a human
+ * writes is preserved. OVERVIEW.md holds current state, CHANGELOG.md holds
+ * history; this file holds only what the project durably IS and how we work on it.
+ */
+export declare function claudeTemplate(name: string, summary: string): string;