@edspencer/paddock 0.63.0 → 0.64.0

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,130 @@ 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. Both
+     * current callers already only pass in-root paths — this exists so that stays
+     * true when someone later adds a third one.
+     */
+    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 +221,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 +347,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;
 }