@wjarka/cezarion 0.10.0-pr30.54

package/dist/contract/projects.d.ts

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+/**
+ * The project-registry family: `GET/POST/PATCH/DELETE /api/v1/projects`, the folder picker
+ * (`GET /api/v1/fs/browse`) that feeds it, and the launch-key read.
+ *
+ * Node-free by construction (see README rule 1) — `zod` and nothing else.
+ */
+/**
+ * One `GET /api/v1/projects` registry entry (multi-project spec, step 1.6).
+ *
+ * Unlike health's id+name pairs this carries the absolute `root`: the registry routes are
+ * same-origin, the CORS-open health route is not, and that difference is the reason the two
+ * project shapes are deliberately NOT the same type.
+ *
+ * Deliberately a CLOSED object even though the server's persistence schema
+ * (`src/workspace/config.ts`, `workspaceProjectSchema.passthrough()`) keeps unknown keys in the
+ * file: passthrough is a durability promise about `~/.cezar/config.json`, not a promise that the
+ * API answers arbitrary keys. Modelling it as a loose object here would also be unprovable — see
+ * the note on the index signature in `src/server/contract-parity.workspace.test.ts`.
+ */
+export declare const projectListEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    root: z.ZodString;
+    addedAt: z.ZodString;
+    lastOpenedAt: z.ZodString;
+    source: z.ZodEnum<{
+        checkout: "checkout";
+        local: "local";
+    }>;
+    status: z.ZodEnum<{
+        missing: "missing";
+        "not-git": "not-git";
+        ok: "ok";
+    }>;
+    branch: z.ZodOptional<z.ZodString>;
+    forge: z.ZodOptional<z.ZodLiteral<"github">>;
+    repoUrl: z.ZodOptional<z.ZodString>;
+    maxParallel: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProjectListEntry = z.infer<typeof projectListEntrySchema>;
+/** `GET /api/v1/projects` — the workspace registry. Workspace-level: never 404s, never scoped.
+ *  An unreadable workspace degrades to `projects: []` plus the default `projectsDir`, so all
+ *  three keys are always present. */
+export declare const projectsResponseSchema: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodString;
+        addedAt: z.ZodString;
+        lastOpenedAt: z.ZodString;
+        source: z.ZodEnum<{
+            checkout: "checkout";
+            local: "local";
+        }>;
+        status: z.ZodEnum<{
+            missing: "missing";
+            "not-git": "not-git";
+            ok: "ok";
+        }>;
+        branch: z.ZodOptional<z.ZodString>;
+        forge: z.ZodOptional<z.ZodLiteral<"github">>;
+        repoUrl: z.ZodOptional<z.ZodString>;
+        maxParallel: z.ZodOptional<z.ZodNumber>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    bootProject: z.ZodString;
+    projectsDir: z.ZodString;
+}, z.core.$strip>;
+export type ProjectsResponse = z.infer<typeof projectsResponseSchema>;
+/**
+ * `POST /api/v1/projects` (multi-project spec, step 4.2) — what the folder-browser dialog gets
+ * back. `error` is present ONLY on the 409 (already registered), where `project` is the EXISTING
+ * entry: the dialog navigates to it rather than dead-ending on a duplicate.
+ */
+export declare const registerProjectResponseSchema: z.ZodObject<{
+    project: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodString;
+        addedAt: z.ZodString;
+        lastOpenedAt: z.ZodString;
+        source: z.ZodEnum<{
+            checkout: "checkout";
+            local: "local";
+        }>;
+        status: z.ZodEnum<{
+            missing: "missing";
+            "not-git": "not-git";
+            ok: "ok";
+        }>;
+        branch: z.ZodOptional<z.ZodString>;
+        forge: z.ZodOptional<z.ZodLiteral<"github">>;
+        repoUrl: z.ZodOptional<z.ZodString>;
+        maxParallel: z.ZodOptional<z.ZodNumber>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RegisterProjectResponse = z.infer<typeof registerProjectResponseSchema>;
+/**
+ * `DELETE /api/v1/projects/:projectId` (multi-project spec, step 4.4) — Settings → Projects'
+ * per-row Remove. Deregistration ONLY: the server never touches anything under the project root,
+ * so this is a registry edit and nothing else. The interesting failures are 409s (the project has
+ * running tasks, or it is the project this server booted in), whose `{ error }` the pane shows
+ * verbatim.
+ */
+export declare const removeProjectResponseSchema: z.ZodObject<{
+    removed: z.ZodLiteral<true>;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type RemoveProjectResponse = z.infer<typeof removeProjectResponseSchema>;
+/** `PATCH /api/v1/projects/:projectId` — the updated entry, the same shape `GET /api/v1/projects`
+ *  attaches (the handler re-probes `status`/`branch` so one project has one shape). */
+export declare const updateProjectResponseSchema: z.ZodObject<{
+    project: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodString;
+        addedAt: z.ZodString;
+        lastOpenedAt: z.ZodString;
+        source: z.ZodEnum<{
+            checkout: "checkout";
+            local: "local";
+        }>;
+        status: z.ZodEnum<{
+            missing: "missing";
+            "not-git": "not-git";
+            ok: "ok";
+        }>;
+        branch: z.ZodOptional<z.ZodString>;
+        forge: z.ZodOptional<z.ZodLiteral<"github">>;
+        repoUrl: z.ZodOptional<z.ZodString>;
+        maxParallel: z.ZodOptional<z.ZodNumber>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type UpdateProjectResponse = z.infer<typeof updateProjectResponseSchema>;
+/** Bounds for one tag and for a project's tag list. Named because three places must agree: this
+ *  schema, the registry schema that must never `.catch` away a value this accepts
+ *  (`workspaceProjectSchema` in the service), and the settings editor that refuses input early. */
+export declare const PROJECT_TAG_MAX_LENGTH = 32;
+export declare const PROJECT_TAGS_MAX = 20;
+/**
+ * `PATCH /api/v1/projects/:projectId` body — the two per-project registry fields the cockpit
+ * edits. Each key is optional and a body may carry either or both: a PATCH names the fields it
+ * changes, and an absent key must stay distinguishable from one set to `null` (which CLEARS). A
+ * `{ maxParallel }`-only body — every pre-tags client sends exactly that — therefore still means
+ * what it always did. An EMPTY body is still refused, as it was before tags existed: a request
+ * that names no field is a mistake, and answering 200 to it would report a change that never
+ * happened (and cost a full config rewrite to do nothing).
+ *
+ * - `maxParallel` (spec 2026-07-22-per-project-concurrency): `null` clears the override back to
+ *   "inherit the workspace cap"; an integer `1..16` pins it. The bounds mirror
+ *   `workspaceProjectSchema` exactly, so a value this schema accepts can never be degraded away
+ *   by the next load's `.catch`.
+ * - `tags`: the whole list, replaced wholesale — there is no add-one/remove-one spelling,
+ *   because the editor always knows the full set and a merge protocol would only add a way for
+ *   two tabs to disagree. `null` and `[]` both clear it; the server normalizes before storing.
+ *
+ * Deliberately NOT where the agent-account selection lives — that is
+ * `PUT /api/v1/workspace/agent-profiles/selection`, stored beside the accounts it names.
+ */
+export declare const updateProjectInputSchema: z.ZodObject<{
+    maxParallel: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tags: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type UpdateProjectInput = z.infer<typeof updateProjectInputSchema>;
+/**
+ * `POST /api/v1/projects/checkout` (multi-project spec, step 4.3) — the clone-from-GitHub body.
+ * `name` defaults server-side to the repo name; `checkoutId` is the cockpit's own correlation
+ * token, echoed on every `checkout-progress` event so two tabs cloning at once never render each
+ * other's progress.
+ */
+export declare const checkoutProjectInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    checkoutId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CheckoutProjectInput = z.infer<typeof checkoutProjectInputSchema>;
+/** One directory in a `GET /api/v1/fs/browse` listing (multi-project spec, step 4.1). `path` is
+ *  absolute — same-origin route, like `ProjectListEntry.root`. */
+export declare const fsBrowseDirSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    isRepo: z.ZodBoolean;
+}, z.core.$strip>;
+export type FsBrowseDir = z.infer<typeof fsBrowseDirSchema>;
+/** `GET /api/v1/fs/browse?path=` — the folder picker's listing. Rooted at the independently
+ *  configured browse root, directories only. */
+export declare const fsBrowseResponseSchema: z.ZodObject<{
+    path: z.ZodString;
+    parent: z.ZodNullable<z.ZodString>;
+    dirs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        isRepo: z.ZodBoolean;
+    }, z.core.$strip>>;
+    truncated: z.ZodBoolean;
+}, z.core.$strip>;
+export type FsBrowseResponse = z.infer<typeof fsBrowseResponseSchema>;
+/** `GET /api/v1/launch-key` — the bookmarklet auto-start secret (spec 011). Fetched to COMPARE
+ *  against the `?key=` query param and to bake into the `javascript:` links the Settings → Skills
+ *  bookmarklet panel generates. The value never renders as text, never logs, and never goes back
+ *  into the address bar. */
+export declare const launchKeyResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+export type LaunchKeyResponse = z.infer<typeof launchKeyResponseSchema>;

package/dist/contract/repo.d.ts

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+/**
+ * The repo / git family of `/api/v1` — the Repo view, the structured diff shapes the Changes and
+ * Files tabs read, and the worktree-retention panel.
+ *
+ * `RepoInfo` is NOT redeclared here: health already owns it (`./health.ts`), and the Repo view
+ * serves the very same record.
+ */
+/** One `git status --porcelain` row. */
+export declare const statusEntrySchema: z.ZodObject<{
+    status: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
+export type StatusEntry = z.infer<typeof statusEntrySchema>;
+/** One `git log` row; `when` is git's relative `%cr` ("3 hours ago"), not a timestamp. */
+export declare const logEntrySchema: z.ZodObject<{
+    hash: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    when: z.ZodString;
+}, z.core.$strip>;
+export type LogEntry = z.infer<typeof logEntrySchema>;
+/**
+ * `GET /api/v1/repo` — the Repo view's one read.
+ *
+ * A union, and deliberately so: the handler answers a DIFFERENT object when the project root is
+ * not a repository (`server.ts:3481`) than when it is (`server.ts:3494`), and the empty branch's
+ * `[]` literals make its arrays `never[]` in the route type. Modelling this as the flat
+ * `{ info: RepoInfo | null; status: StatusEntry[]; … }` the hand-written DTO used would be WIDER
+ * than the route — the parity guard rejects it. Both members still parse the real wire bytes
+ * (an empty array satisfies `z.array(z.never())`), so nothing is lost at runtime; it is the
+ * compile-time shape that is oddly precise. See the report note on `server.ts:3481`.
+ */
+export declare const repoResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
+    info: z.ZodNull;
+    status: z.ZodArray<z.ZodNever>;
+    log: z.ZodArray<z.ZodNever>;
+    branches: z.ZodArray<z.ZodNever>;
+    baseBranch: z.ZodNull;
+}, z.core.$strip>, z.ZodObject<{
+    info: z.ZodObject<{
+        root: z.ZodString;
+        branch: z.ZodString;
+        remote: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    status: z.ZodArray<z.ZodObject<{
+        status: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    log: z.ZodArray<z.ZodObject<{
+        hash: z.ZodString;
+        subject: z.ZodString;
+        author: z.ZodString;
+        when: z.ZodString;
+    }, z.core.$strip>>;
+    branches: z.ZodArray<z.ZodString>;
+    baseBranch: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>]>;
+export type RepoResponse = z.infer<typeof repoResponseSchema>;
+/** `POST /api/v1/repo/branch` — switch to an existing branch, or create one and switch. Every
+ *  predictable git failure (invalid name, unknown `from`, dirty-tree conflict) is a 409. */
+export declare const repoBranchResponseSchema: z.ZodObject<{
+    branch: z.ZodString;
+    created: z.ZodBoolean;
+}, z.core.$strip>;
+export type RepoBranchResponse = z.infer<typeof repoBranchResponseSchema>;
+/** One changed file of a structured diff (`/runs/:id/changes`, `/repo/changes`, the commit
+ *  routes). Assignable to the diff facade's `DiffFileChange` by construction. */
+export declare const changedFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    oldPath: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        added: "added";
+        copied: "copied";
+        deleted: "deleted";
+        modified: "modified";
+        renamed: "renamed";
+    }>;
+    adds: z.ZodNumber;
+    dels: z.ZodNumber;
+    binary: z.ZodBoolean;
+    image: z.ZodOptional<z.ZodBoolean>;
+    patch: z.ZodString;
+}, z.core.$strip>;
+export type ChangedFile = z.infer<typeof changedFileSchema>;
+/** `GET /api/v1/runs/:id/changes` and `GET /api/v1/repo/changes` — the structured diff.
+ *  409 (+ reason) when the run's backing directory is unavailable or git itself refuses; never HTML. */
+export declare const changesPayloadSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        oldPath: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            added: "added";
+            copied: "copied";
+            deleted: "deleted";
+            modified: "modified";
+            renamed: "renamed";
+        }>;
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        binary: z.ZodBoolean;
+        image: z.ZodOptional<z.ZodBoolean>;
+        patch: z.ZodString;
+    }, z.core.$strip>>;
+    stat: z.ZodObject<{
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        files: z.ZodNumber;
+    }, z.core.$strip>;
+    repointedHead: z.ZodOptional<z.ZodObject<{
+        headBranch: z.ZodString;
+        taskBranch: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ChangesPayload = z.infer<typeof changesPayloadSchema>;
+/** `GET /api/v1/repo/commit/:sha?structured=1` (and `/runs/:id/commit/:sha`) — one commit's
+ *  metadata plus the same `{files, stat}` shape the /changes routes serve. A merge commit
+ *  honestly answers zero files. The bare (unstructured) route keeps its legacy text shape. */
+export declare const repoCommitPayloadSchema: z.ZodObject<{
+    sha: z.ZodString;
+    subject: z.ZodString;
+    author: z.ZodString;
+    when: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        oldPath: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            added: "added";
+            copied: "copied";
+            deleted: "deleted";
+            modified: "modified";
+            renamed: "renamed";
+        }>;
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        binary: z.ZodBoolean;
+        image: z.ZodOptional<z.ZodBoolean>;
+        patch: z.ZodString;
+    }, z.core.$strip>>;
+    stat: z.ZodObject<{
+        adds: z.ZodNumber;
+        dels: z.ZodNumber;
+        files: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RepoCommitPayload = z.infer<typeof repoCommitPayloadSchema>;
+/** One row of a `GET /api/v1/runs/:id/files` directory listing. */
+export declare const worktreeDirEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        dir: "dir";
+        file: "file";
+    }>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type WorktreeDirEntry = z.infer<typeof worktreeDirEntrySchema>;
+/**
+ * `GET /api/v1/runs/:id/files?path=` — a directory listing or one file (size-capped, binary
+ * flagged). `content` is absent exactly when `binary` or `tooLarge`.
+ *
+ * A discriminated union on `type`. Both handlers now build their literal with `as const`; without
+ * it the property widened to `string` during Hono's route-type inference and the route lost the
+ * discriminant, so a consumer narrowing on `entry.type === 'dir'` was left with `never`.
+ */
+export declare const worktreeEntrySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"dir">;
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            dir: "dir";
+            file: "file";
+        }>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    size: z.ZodNumber;
+    binary: z.ZodBoolean;
+    tooLarge: z.ZodBoolean;
+    content: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type WorktreeEntry = z.infer<typeof worktreeEntrySchema>;
+/** One materialized task worktree in the management panel (#483). `sizeBytes` is null when `du`
+ *  is unavailable (Windows / missing). `reclaimable` = finished, has a directory, not yet
+ *  reclaimed (retention's rule). */
+export declare const worktreeInfoSchema: z.ZodObject<{
+    runId: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        done: "done";
+        failed: "failed";
+        queued: "queued";
+        review: "review";
+        running: "running";
+        waiting: "waiting";
+    }>;
+    branch: z.ZodNullable<z.ZodString>;
+    sizeBytes: z.ZodNullable<z.ZodNumber>;
+    finishedAt: z.ZodNullable<z.ZodString>;
+    reclaimable: z.ZodBoolean;
+}, z.core.$strip>;
+export type WorktreeInfo = z.infer<typeof worktreeInfoSchema>;
+/** `GET /api/v1/worktrees` (#483): the worktrees on disk, their total size (null when any
+ *  degraded), and the current keep-limit (0 = unlimited). */
+export declare const worktreesResponseSchema: z.ZodObject<{
+    worktrees: z.ZodArray<z.ZodObject<{
+        runId: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            cancelled: "cancelled";
+            done: "done";
+            failed: "failed";
+            queued: "queued";
+            review: "review";
+            running: "running";
+            waiting: "waiting";
+        }>;
+        branch: z.ZodNullable<z.ZodString>;
+        sizeBytes: z.ZodNullable<z.ZodNumber>;
+        finishedAt: z.ZodNullable<z.ZodString>;
+        reclaimable: z.ZodBoolean;
+    }, z.core.$strip>>;
+    totalBytes: z.ZodNullable<z.ZodNumber>;
+    keep: z.ZodNumber;
+}, z.core.$strip>;
+export type WorktreesResponse = z.infer<typeof worktreesResponseSchema>;
+/** `POST /api/v1/worktrees/reclaim` (#483): the run ids whose directory was reclaimed. */
+export declare const reclaimWorktreesResponseSchema: z.ZodObject<{
+    reclaimed: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ReclaimWorktreesResponse = z.infer<typeof reclaimWorktreesResponseSchema>;