@edspencer/paddock 0.0.1 → 0.56.0

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

@@ -0,0 +1,202 @@
+import { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor } from "./project-mime.js";
+export { IMAGE_MIME, VIDEO_MIME, DOCUMENT_MIME, fileKind, contentTypeFor };
+import { ROOT_KEY, isRootKey, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError } from "./project-paths.js";
+export { ROOT_KEY, isRootKey, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError, };
+import { type Project, type FileKind, type FileEntry, type CreateProjectInput, type UpdateProjectInput } from "./project-types.js";
+export * from "./project-types.js";
+export declare class ProjectStore {
+    private readonly root;
+    constructor(root: string);
+    /** Ensure the projects root exists. Call once at startup. */
+    init(): Promise<void>;
+    /**
+     * The on-disk directory backing a workspace key.
+     *
+     * A key is a path RELATIVE to `projectsRoot`, and the root workspace's key is
+     * `""` — so `path.join` resolves it with no special case at all. The previous
+     * design needed a branch here for a reserved slug, and that branch had to be
+     * duplicated in `project-files.ts` (where it was missed, 404ing every root
+     * file route). There is now no branch to forget.
+     */
+    private dirFor;
+    /**
+     * Keep the root's `.chats/` out of the backing repo. Root chats are ordinary
+     * chats and get the same treatment project chats already do
+     * ({@link ensureSidecarGitignore}) — transcripts are append-heavy JSONL and are
+     * not tracked anywhere today.
+     */
+    private ensureRootGitignore;
+    /** List all projects, newest-updated first. Skips `_`-prefixed dirs. */
+    list(): Promise<Project[]>;
+    /**
+     * Get one workspace by key. Throws `ProjectError("not_found")` if missing.
+     *
+     * The root key (`""`) always resolves — the instance's own directory is always
+     * there — so this never throws for the root.
+     */
+    get(slug: string): Promise<Project>;
+    /**
+     * Whether a workspace exists. For a project that means a `project.yaml`
+     * record; the root workspace always exists, record or not.
+     */
+    exists(slug: string): Promise<boolean>;
+    /**
+     * Create a project: mkdir + write project.yaml (from template) + seed
+     * CHANGELOG.md. Idempotency: throws ProjectError("exists") if the slug
+     * directory already holds a project.yaml.
+     */
+    create(input: CreateProjectInput): Promise<Project>;
+    /**
+     * Promote an existing NOTEBOOK project into a REPO-BACKED one IN PLACE (issue
+     * #213), preserving its chats + sidecar metadata. This relaxes #187's create-time
+     * `repo` immutability on this ONE path: an existing project (a subdir of the data
+     * repo) gains an external git repo as its keeper's working directory.
+     *
+     * What it does (mirrors `create()`'s repo-backed branch, but non-destructively):
+     *   1. Clone the repo into the nested checkout `<dir>/<repo-name>/` — FIRST, so a
+     *      clone failure rolls back (rm just the checkout) and leaves the notebook
+     *      wholly intact (project.yaml, `.chats/`, OVERVIEW/CHANGELOG untouched).
+     *   2. Write the sidecar `.gitignore` (`/<repo-name>/` + `/.chats/`) so the
+     *      checkout + transcript store stay out of the data repo.
+     *   3. Set `repo:` in project.yaml → the DTO flips to repo-backed and the keeper's
+     *      cwd becomes the checkout ({@link workingDirFor}).
+     *   4. Drop the sweeper-owned per-project `CLAUDE.md`: a repo-backed project defers
+     *      to the repo's OWN `CLAUDE.md` (loaded natively from the checkout). Leaving
+     *      the notebook's would leak into the checkout's cwd walk-up (the metadata dir
+     *      is an ancestor of the nested checkout) — so it's removed (it survives in the
+     *      data repo's git history).
+     *
+     * The existing chats need NO transcript surgery: they already live in `<dir>/.chats/`;
+     * the caller's {@link import("./herdctl.js").HerdctlService.ensureProjectAgent} re-runs
+     * `ensureProjectChats(newWorkingDir, dir)` which re-symlinks the new cwd's encoded
+     * transcript path at that same `.chats/` store, so every chat stays listed + resumable
+     * (issue #213 open-question #1, resolved: Claude Code tolerates recorded-cwd ≠ process-cwd).
+     *
+     * Guards: throws `ProjectError("invalid")` for a not-yet-notebook (already
+     * repo-backed) project or a bad URL, and `ProjectError("exists")` if a
+     * `<repo-name>/` directory is already present (never clobber existing files).
+     */
+    promote(slug: string, repoUrl: string): Promise<Project>;
+    /** Update mutable metadata fields and bump `updated`. */
+    update(slug: string, patch: UpdateProjectInput): Promise<Project>;
+    /** Read OVERVIEW.md, or "" if it doesn't exist yet. */
+    readOverview(slug: string): Promise<string>;
+    /** Replace OVERVIEW.md wholesale (the sweep regenerates it each time). */
+    writeOverview(slug: string, content: string): Promise<void>;
+    /** Read CHANGELOG.md, or "" if it doesn't exist yet (issue #188). */
+    readChangelog(slug: string): Promise<string>;
+    /** Whether OVERVIEW.md exists for this project. */
+    overviewExists(slug: string): Promise<boolean>;
+    /** Read CLAUDE.md, or "" if it doesn't exist yet (issue #177). */
+    readClaudeMd(slug: string): Promise<string>;
+    /**
+     * Replace the CLAUDE.md "Curated notes" section wholesale with a sweeper-
+     * curated body (issue #379), preserving ALL human-authored content above the
+     * managed heading. This supersedes the old amend-only `appendClaudeMd`, which
+     * blind-appended and could never dedup — the sweeper only ever saw the first
+     * 2000 chars of the file, so it re-added "known" facts believing they were new.
+     * The sweeper now sees the full file and returns the ENTIRE curated-notes body,
+     * dedup'd/pruned to fit its budget. Everything up to and including the
+     * `## Curated notes` heading is kept verbatim; only the body below is rewritten.
+     * The file/heading is seeded if absent (older projects predating #177). A blank
+     * body is a no-op — the caller passes content only when there's something to
+     * write (NOCHANGE means "leave the file untouched", not "empty it").
+     */
+    writeClaudeCurated(slug: string, curatedBody: string): Promise<void>;
+    /**
+     * Pin a file: validate it exists in the project dir, dedupe, persist in
+     * project.yaml. Returns the updated project. Throws ProjectError("invalid")
+     * if the file doesn't exist or escapes the project dir.
+     */
+    pinFile(slug: string, file: string): Promise<Project>;
+    /** Unpin a file (no-op if not pinned). Returns the updated project. */
+    unpinFile(slug: string, file: string): Promise<Project>;
+    /**
+     * Add or replace one unified trigger in `project.yaml`, keyed by name (Epic T /
+     * T1) — the persistence half of a trigger mutation (the caller arms it against
+     * herdctl separately via `TriggerService`/`HerdctlService`). The record is validated
+     * + normalised by the Zod schema ({@link sanitizeTrigger}); an invalid name or record
+     * throws `ProjectError("invalid")`. Returns the updated project DTO.
+     */
+    setTrigger(slug: string, name: string, trigger: unknown): Promise<Project>;
+    /**
+     * Remove a trigger from `project.yaml` (no-op if absent). Returns the updated
+     * project DTO. The caller disarms the trigger's agent / schedule via `TriggerService`.
+     *
+     */
+    removeTrigger(slug: string, name: string): Promise<Project>;
+    /**
+     * Delete a project directory and everything in it (project.yaml, CHANGELOG.md,
+     * and any files the keeper agent created). Throws ProjectError("not_found")
+     * if the slug has no project.yaml, so callers can return a clean 404.
+     *
+     * Note: this removes the project DIRECTORY only. The caller (server) is
+     * responsible for dropping the generated keeper-agent yaml + regenerating
+     * herdctl.yaml + reloading the fleet — the inverse of the create flow.
+     */
+    remove(slug: string): Promise<Project>;
+    /**
+     * Replace CHANGELOG.md wholesale with a sweeper-curated body (issue #379). The
+     * sweeper now returns the FULL changelog — adding a dated entry for genuinely-
+     * new activity, coalescing duplicates, and dropping/summarizing the oldest to
+     * stay under its token budget — instead of one blind-appended bullet. That's
+     * what stops the file (and the per-chat preload that injects it) growing without
+     * bound. The `# Changelog — <slug>` title is owned by Paddock and re-asserted
+     * here so the model never has to reproduce it; if the model included its own
+     * top-level heading we drop it to avoid a duplicate title. A blank body is a
+     * no-op (guards against wiping the file on a malformed reply).
+     */
+    writeChangelog(slug: string, body: string): Promise<void>;
+    /**
+     * List one level of a project directory (issue #259). See
+     * {@link import("./project-files.js").listFiles}.
+     */
+    listFiles(slug: string, subpath?: string): Promise<FileEntry[]>;
+    /** Read a freeform file's contents as UTF-8 text (path-traversal guarded). */
+    readFile(slug: string, name: string): Promise<string>;
+    /**
+     * Read a file's raw bytes + its MIME type (issue #61), for the binary/image
+     * endpoint. See {@link import("./project-files.js").readFileBytes}.
+     */
+    readFileBytes(slug: string, name: string): Promise<{
+        bytes: Buffer;
+        mime: string;
+    }>;
+    /**
+     * Read a file plus a render-kind hint derived from its extension (issues #3 /
+     * #61). See {@link import("./project-files.js").readFileWithKind}.
+     */
+    readFileWithKind(slug: string, name: string): Promise<{
+        name: string;
+        kind: FileKind;
+        content: string;
+    }>;
+    /**
+     * Read one workspace, or `null` if the key doesn't name one.
+     *
+     * **The root workspace always exists.** For a project, `project.yaml` IS the
+     * existence gate — no record, not a project. But the root is the instance
+     * itself: its directory is always there, so a missing record just means
+     * "nothing has been customised yet" and every field falls back to a default
+     * (see {@link normalize}). The record is written lazily, on the first setting
+     * that actually changes.
+     *
+     * This is what removes the whole opt-in apparatus the previous design needed —
+     * no `createRoot`, no enable card, and no `/chat` that 404s on a fresh box.
+     */
+    private readSafe;
+    /** Fill defaults / coerce a parsed project.yaml into a complete ProjectYaml. */
+    private normalize;
+    /**
+     * Ensure the project dir's sidecar `.gitignore` ignores the nested repo-backed
+     * checkout (`/<checkoutName>/`) and the transcript store (`/.chats/`), so neither
+     * is tracked by the instance data repo (issue #187 option A). Idempotent and
+     * merge-aware: an existing `.gitignore` (rare for a notebook, but possible) keeps
+     * its lines and only the missing entries are appended — used by both `create()`
+     * and the in-place `promote()` (#213).
+     */
+    private ensureSidecarGitignore;
+    private writeYaml;
+    private toDto;
+    private stripDto;
+}