@edspencer/paddock 0.63.0 → 0.65.0

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

@@ -175,6 +175,61 @@ export interface ProjectYaml {
      * (like `slug`/`started`).
      */
     repo?: string;
+    /**
+     * Whether Paddock looks after this project's own files (issue #206).
+     *
+     * `true` — Paddock curates `CLAUDE.md` / `OVERVIEW.md` / `CHANGELOG.md` here;
+     * this is what "notebook" used to mean. `false` — the content is code that you
+     * or your agents source-control OUTSIDE Paddock, and Paddock never writes
+     * project files into it.
+     *
+     * This is the real axis. It replaced the derived `repoBacked` boolean, which
+     * was one flag doing four jobs and broke the moment a fifth backing shape
+     * appeared. Whether a git repo sits behind the project is INDEPENDENT of this
+     * and is not a type — it is just which of `path`/`repo` are set.
+     *
+     * **Optional on disk, and the default is DERIVED rather than constant:**
+     * `managed ?? !(repo || path)` (see
+     * {@link import("./project-paths.js").isManaged}). Every `project.yaml` written
+     * before this key existed relies on that: were an absent value to mean `true`,
+     * every existing repo-backed project would flip to managed on upgrade and the
+     * sweeper would begin writing `CLAUDE.md` into its checkout. `create()` always
+     * writes the key explicitly, so the derivation only ever serves legacy files.
+     *
+     * `managed: true` together with `repo` is REJECTED at creation rather than
+     * silently ignored — Paddock curating files into a repo it also clones is not a
+     * combination with a sensible meaning.
+     */
+    managed?: boolean;
+    /**
+     * Absolute path to the directory holding this project's content (issue #206).
+     *
+     * Applies on BOTH sides of the managed axis, which is what makes it a location
+     * rather than a type:
+     *
+     *  - **unmanaged + `path`** — LINK a code checkout you already have
+     *    (`~/Code/foo`), used in place with no copy: its real history, branches and
+     *    remotes. Paddock writes nothing into it (no `.chats/`, no sidecar
+     *    `.gitignore`, no `CLAUDE.md`); transcripts stay in `<slug>/.chats/` via
+     *    `ensureProjectChats`'s two-argument split. Transcripts key on this cwd, so
+     *    prior `claude` sessions run there by hand are offered for adoption, and
+     *    `claude.transcripts: host` / per-directory `~/.claude.json` MCP servers
+     *    finally mean something for a code project.
+     *  - **managed + `path`** — nominate where your NOTES live. The curated trio
+     *    (`OVERVIEW.md`/`CHANGELOG.md`/`CLAUDE.md`) follows the path, so those files
+     *    end up outside the Paddock data dir.
+     *
+     * Either way `project.yaml` (the registry entry Paddock discovers projects by
+     * scanning for) and `.chats/` (Paddock's own state) stay in
+     * `<projectsRoot>/<slug>/`.
+     *
+     * Acquisition when the path does NOT exist: with `repo`, Paddock clones into it;
+     * for a managed project, Paddock creates it; otherwise the create is rejected.
+     *
+     * Set at creation and immutable thereafter (like `slug`/`started`/`repo`) — the
+     * cwd is baked into every transcript path, so moving it would strand history.
+     */
+    path?: string;
     /**
      * Scheduled chat sessions for this project (issue #265 / DD-2), keyed by a
      * stable schedule name. Each value is herdctl's `ScheduleSchema` shape (plus the
@@ -211,22 +266,46 @@ export interface Project extends ProjectYaml {
      *  empty string means "Unsorted". */
     group: string;
     /**
-     * Absolute path to the project's METADATA directory — the per-slug dir in the
-     * instance data repo that holds `project.yaml`, `OVERVIEW.md`, `CHANGELOG.md`,
-     * `.chats/`, and (for a notebook project) `CLAUDE.md`. For a NOTEBOOK project
-     * this is also the keeper's cwd; for a REPO-BACKED project the cwd is
-     * {@link workingDir} (the nested checkout) instead — see #187.
+     * Absolute path to the project's METADATA directory — the per-slug dir under
+     * `projectsRoot`. Always holds `project.yaml` (the registry entry Paddock
+     * discovers projects by scanning for, so it can never move) and `.chats/`
+     * (Paddock's own state, and what backup tooling points at).
+     *
+     * It ALSO holds the curated trio (`OVERVIEW.md`/`CHANGELOG.md`/`CLAUDE.md`)
+     * unless the project is managed with an external `path`, in which case those
+     * follow the content — see {@link contentDir}.
      */
     dir: string;
     /**
-     * The keeper agent's working directory (cwd). For a notebook project this
-     * equals {@link dir}; for a repo-backed project it's the nested checkout
-     * (`<dir>/<repo-name>`), so the repo's own `CLAUDE.md` + git tooling apply
-     * (issue #187). Always concrete in the DTO.
+     * The keeper agent's working directory (cwd): {@link ProjectYaml.path} verbatim
+     * when set, else the nested checkout for a `repo`-backed project (#187), else
+     * {@link dir}. Always concrete in the DTO.
+     *
+     * This — not {@link dir} — is the directory the git surface reports on, which
+     * is what issue #597 was: the Changes tab read `dir`, so it showed the metadata
+     * directory rather than the code the project is actually about.
      */
     workingDir: string;
-    /** Whether this project is backed by an external git repo (issue #187). */
-    repoBacked: boolean;
+    /**
+     * Where the sweeper's curated trio lives — {@link workingDir} for a managed
+     * project, {@link dir} for an unmanaged one (issue #206). Always concrete.
+     *
+     * Equals {@link dir} in every pre-#206 shape; it differs only for a managed
+     * project with an external `path`.
+     */
+    contentDir: string;
+    /**
+     * Whether Paddock curates this project's own files — ALWAYS concrete in the
+     * DTO, derived via `managed ?? !(repo || path)` so legacy files keep their
+     * meaning (issue #206).
+     *
+     * This replaced `repoBacked`, which conflated four separate questions into one
+     * boolean and broke as soon as a fifth backing shape appeared. Each consumer
+     * now takes the fact it actually needs: the sweeper's `CLAUDE.md` suppression
+     * and the promote guard key on `managed`; the git surface keys on whether
+     * {@link workingDir} is a git working tree, asked per directory.
+     */
+    managed: boolean;
     /** Whether OVERVIEW.md exists in the project dir (sweep-curated context). */
     hasOverview: boolean;
     /** Always present in the DTO (defaults to []). */
@@ -259,6 +338,25 @@ export interface CreateProjectInput {
      * a notebook project (the classic type).
      */
     repo?: string;
+    /**
+     * Whether Paddock should curate this project's own files (issue #206). Absent ⇒
+     * derived as `!(repo || path)`, so a plain create is managed and a create that
+     * names a backing is not. `managed: true` together with `repo` is REJECTED.
+     */
+    managed?: boolean;
+    /**
+     * Absolute path to the directory this project's content lives in (issue #206).
+     *
+     * Validated at create time: absolute, and outside `projectsRoot` / the data dir
+     * / every other project's working directory. Immutable thereafter. If it does
+     * not exist, Paddock clones `repo` into it when one is given, creates it for a
+     * managed project, and otherwise rejects the create.
+     *
+     * There is deliberately NO requirement that it be a git repository — Paddock
+     * probes for git and lights up the git features when it finds one, exactly as
+     * it already does for the projects root.
+     */
+    path?: string;
 }
 /** Partial metadata update (slug + started are immutable). */
 export type UpdateProjectInput = Partial<Pick<ProjectYaml, "name" | "status" | "domain" | "group" | "visibility" | "summary" | "links" | "model" | "permissionMode" | "maxTurns" | "docker">> & {

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

@@ -1,12 +1,28 @@
 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 { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, isValidRepoUrl, repoCheckoutName, workingDirFor, slugify, ProjectError } from "./project-paths.js";
+export { ROOT_KEY, isRootKey, isPathInside, isManaged, contentDirFor, 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);
+    private readonly dataDir?;
+    private readonly log;
+    /**
+     * @param root The projects root (`cfg.projectsRoot`) — every project's metadata dir.
+     * @param dataDir The instance data dir (`cfg.dataDir`), used ONLY to reject a
+     *   `path:` that points inside Paddock's own state (issue #206). Optional so the
+     *   many tests that construct a bare store keep compiling; when omitted, `root`
+     *   alone is the containment check (in the default layout `projectsRoot` is
+     *   `<dataDir>/projects`, so it is the tighter of the two anyway).
+     * @param log Where non-fatal advisories go — currently only the declared-repo /
+     *   actual-remote mismatch on an existing `path` (issue #206), which must be
+     *   said out loud rather than silently ignored (#659) but must not fail the
+     *   create. Defaults to a no-op so a bare `new ProjectStore(root)` is unchanged.
+     */
+    constructor(root: string, dataDir?: string | undefined, log?: {
+        warn: (message: string) => void;
+    });
     /** Ensure the projects root exists. Call once at startup. */
     init(): Promise<void>;
     /**
@@ -40,12 +56,139 @@ export declare class ProjectStore {
      * record; the root workspace always exists, record or not.
      */
     exists(slug: string): Promise<boolean>;
+    /**
+     * Recursively delete `target`, but ONLY if it is strictly inside `projectsRoot`.
+     *
+     * The single choke point for every recursive delete in this store. Before issue
+     * #206 the containment was implicit: everything a project owned — including a
+     * repo-backed project's checkout — was nested under `<projectsRoot>/<slug>/`, so
+     * `fs.rm(dir, {recursive: true})` could not reach anything that wasn't ours.
+     * A LINKED project's working directory is the user's real work repo, outside the
+     * root, and that implicit safety is gone.
+     *
+     * So the check is made explicit and centralised here rather than re-derived at
+     * each call site: an `fs.rm` that escapes throws instead of deleting. Every
+     * caller already only passes in-root paths — this exists so that stays true
+     * when someone later adds another one.
+     *
+     * `promote()`'s two rollbacks route through here as well. Their target is
+     * `<projectsRoot>/<slug>/<checkoutName>`, which is in-root by construction, so
+     * the guard is inert there today — that is the point. This is the choke point
+     * the comment above promised, and a recursive delete that skips it is exactly
+     * the drift it exists to prevent. {@link rollback} is the deliberate exception:
+     * it deletes paths that may legitimately sit OUTSIDE the root (a user-nominated
+     * clone target), and is safe by a different mechanism — it only ever removes
+     * directories this operation created.
+     */
+    private rmInsideRoot;
+    /**
+     * Undo a failed {@link create} by removing the directories it created — and
+     * ONLY those.
+     *
+     * This is the non-negotiable half of the acquisition rules (issue #206). The
+     * previous rollback was an unconditional `fs.rm(dir, {recursive, force})` on the
+     * slug dir, safe only because everything a project owned was nested inside it.
+     * Once `path:` lets a user nominate a clone TARGET, an unconditional recursive
+     * delete is a footgun aimed at whatever they typed — a home directory, say. So
+     * the caller records what it brought into being and this removes exactly that
+     * list; a pre-existing directory is never in it and therefore can never be
+     * deleted, no matter how the create failed.
+     *
+     * Removed deepest-first so a nested pair (slug dir + its checkout) unwinds
+     * cleanly. Failures are swallowed: the original error is the one worth
+     * reporting, and a rollback that can't finish must not mask it.
+     */
+    private rollback;
+    /**
+     * Validate a `path:` (issue #206) and return it canonicalised, along with
+     * whether it already exists.
+     *
+     * This is the ONLY gate between a user-supplied string and a directory Paddock
+     * will hand an agent as its cwd (and may `git clone` into), so it is
+     * deliberately strict and ordered cheapest-first. It rejects:
+     *
+     *  - a relative path (a cwd must be unambiguous — it is baked into every
+     *    transcript path, and resolving it against the server's cwd is a footgun);
+     *  - a path that exists but isn't a directory;
+     *  - a path inside `projectsRoot` or the data dir — that is Paddock's own
+     *    state, and pointing at it re-creates the nesting this feature exists to
+     *    avoid (plus `remove()` would then really delete it);
+     *  - a path that is, contains, or sits inside another project's working
+     *    directory — two keepers sharing one cwd collide on transcripts (they are
+     *    keyed by cwd) and on the working tree itself.
+     *
+     * It deliberately does NOT reject a directory for not being a git repository.
+     * That would be the only mandatory git check in the codebase: everywhere else
+     * paddock PROBES and degrades (`GitService.isRepo()` → false, the Changes tab
+     * removes itself, commit/push return `{error: "not a repo"}`), and the default
+     * E2E server runs on a non-git directory on purpose.
+     *
+     * A MISSING path is not an error here — it is an acquisition instruction, which
+     * {@link acquirePath} resolves. Only the existing-path branch can be
+     * canonicalised by `realpath`, so for a missing one the containment checks run
+     * against the resolved-but-not-real path plus its nearest existing ancestor —
+     * otherwise `/tmp/link -> <projectsRoot>` with a missing leaf would slip past.
+     */
+    private validatePath;
+    /**
+     * Canonicalise a path that does not exist yet, by realpath-ing the deepest
+     * ancestor that DOES exist and re-appending the missing segments. Used only by
+     * {@link validatePath}, so a clone target under a symlinked parent still gets
+     * containment-checked against its real location.
+     */
+    private resolveViaExistingAncestor;
+    /**
+     * Bring a project's `path` into existence, returning the directories THIS call
+     * created so a failure can roll back exactly those and nothing else.
+     *
+     * The acquisition rules (issue #206):
+     *
+     *  - path exists ⇒ use it. With `repo` also set, verify the remote matches and
+     *    WARN on a mismatch rather than silently ignoring `repo` — that is the #659
+     *    bug class (a directory that is a clone of a *different* repo).
+     *  - path missing + `repo` ⇒ clone the repo to that path.
+     *  - path missing, managed ⇒ create the directory; the user is nominating where
+     *    their notes should live, and an empty dir is a valid notebook.
+     *  - path missing, unmanaged, no `repo` ⇒ error. There is nothing to acquire
+     *    from and an empty directory is not a codebase.
+     *
+     * **Cleanup rule:** `created` only ever gains directories this call brought into
+     * being. A pre-existing directory is never appended, so no rollback can delete
+     * one — the target is user-nominated and may be a home directory.
+     *
+     * `created` is an OUT-parameter rather than a return value on purpose. Returning
+     * the list would mean the caller only learns what to clean up on the success
+     * path: an `acquirePath` that threw would never hand back the directory it had
+     * already made, so a clone that died partway through would orphan it. Recording
+     * before the risky step is what makes the rollback complete.
+     */
+    private acquirePath;
+    /**
+     * Warn when a directory's git remotes don't include `repo`.
+     *
+     * Deliberately a warning, not a rejection: the directory the user named is the
+     * one they meant, and plenty of legitimate setups (a fork, a mirror, an
+     * ssh-vs-https spelling) won't match exactly. But silently ignoring `repo` is
+     * how #659 happened, so the mismatch has to be said out loud. A directory with
+     * no git at all is not a mismatch — it is just not a repo, which is allowed.
+     *
+     * Reuses `adoptable.ts`'s reader, which parses `.git/config` directly (no
+     * subprocess) and already follows a linked worktree's `gitdir:`/`commondir`
+     * pointers, and returns URLs already through {@link normalizeRemote}.
+     */
+    private warnOnRemoteMismatch;
     /**
      * 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>;
+    /**
+     * Write a new project's `project.yaml` and seed its content files. Split out of
+     * {@link create} so the whole sequence sits inside that method's single
+     * try/rollback rather than trailing off the end of it.
+     */
+    private finishCreate;
     /**
      * 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
@@ -87,6 +230,21 @@ export declare class ProjectStore {
     readChangelog(slug: string): Promise<string>;
     /** Whether OVERVIEW.md exists for this project. */
     overviewExists(slug: string): Promise<boolean>;
+    /**
+     * {@link overviewExists} for a content dir already in hand.
+     *
+     * `readSafe` needs this: it has just parsed the yaml, so it can derive the
+     * content dir for free, whereas going through the slug would re-read
+     * `project.yaml` on every project of every `list()`.
+     */
+    private overviewExistsIn;
+    /**
+     * Where this project's curated trio lives (issue #206) — see
+     * {@link contentDirFor}. Falls back to the metadata dir for a slug that names
+     * no project, so a caller reading a missing project still gets "" rather than
+     * throwing.
+     */
+    private contentDirOf;
     /** Read CLAUDE.md, or "" if it doesn't exist yet (issue #177). */
     readClaudeMd(slug: string): Promise<string>;
     /**
@@ -198,5 +356,14 @@ export declare class ProjectStore {
     private ensureSidecarGitignore;
     private writeYaml;
     private toDto;
+    /**
+     * Drop the derived DTO-only fields, leaving the on-disk shape.
+     *
+     * `managed` deliberately SURVIVES: it is a real `project.yaml` key, and because
+     * the DTO's value is always concrete, the first `update()` of a legacy project
+     * pins its derived value explicitly on disk. That is the desired direction —
+     * the file stops depending on a default — and it is safe precisely because the
+     * value written is the one the derivation already produced.
+     */
     private stripDto;
 }