@wjarka/cezarion 0.16.0 → 0.17.0

package/dist/worktree-manifest.d.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+/**
+ * The record of every path cezar wrote into a task worktree (hearsay-tools/cezarion#1814), for
+ * every module that writes there (`.ai/ast-grep/rules/worktree-write-outside-manifest.yml` names
+ * them). It lives in the worktree's private git dir, so it dies with the worktree and nothing in
+ * the tree (a tool, a diff, autosave) sees it. A writer replaces or removes a path only while the
+ * manifest lists it for that writer and the path still is what cezar left there, so a file the
+ * agent changed or added stays. A missing or unreadable manifest lists nothing: every file stays.
+ */
+export declare const MANIFEST_FILE = "cezar-manifest.json";
+/** The skills-only record before hearsay-tools/cezarion#1814: imported for paths the manifest
+ *  does not list, then removed once a manifest holding them is saved. */
+export declare const LEGACY_SKILLS_MANIFEST_FILE = "cezar-skills.json";
+export type ManifestWriter = 'skills' | 'seed';
+export type EntryKind = 'link' | 'copy' | 'generated' | 'team-copy' | 'ignore-file' | 'file';
+/** Unknown keys stay, so a rewrite keeps what a newer cezar of the same version added. */
+declare const entrySchema: z.ZodObject<{
+    path: z.ZodString;
+    writer: z.ZodString;
+    kind: z.ZodString;
+    skill: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    identity: z.ZodString;
+    alternate: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type ManifestEntry = z.infer<typeof entrySchema>;
+interface Loaded {
+    /** Top-level keys this cezar does not know, written back unchanged. */
+    extra: Record<string, unknown>;
+    skillsExtra: Record<string, unknown>;
+    entries: ManifestEntry[];
+    roots: string[];
+    /** A legacy record was imported: it is removed after the manifest that holds it is saved. */
+    legacy: boolean;
+}
+/** What is at `path` now, comparable with a recorded identity; null when nothing is there. */
+export declare function identityOf(path: string): Promise<string | null>;
+/** The identity `identityOf` reads from a regular file holding `content`. */
+export declare function fileIdentity(content: string | Buffer, executable?: boolean): string;
+/** The identity a copy of the file at `source` reads as: its bytes and executable bit, through a link. */
+export declare function copyIdentity(source: string): Promise<string>;
+/** Thrown when the platform refuses a link, so a writer can fall back to a copy. */
+export declare class LinkRefused extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * What a write leaves at a path. `staged` is a path the caller built in `stagingDir()`; every
+ * other kind is built here, so a writer imports no file-changing function of its own.
+ */
+export type EntryContent = {
+    type: 'link';
+    target: string;
+    linkType?: 'dir' | 'file' | 'junction';
+} | {
+    type: 'file';
+    text: string;
+} | {
+    type: 'file';
+    copyOf: string;
+} | {
+    type: 'dir';
+    files: ReadonlyArray<{
+        name: string;
+        text: string;
+    } | {
+        name: string;
+        copyOf: string;
+    } | {
+        name: string;
+        linkTo: string;
+    }>;
+} | {
+    type: 'copy';
+    from: string;
+} | {
+    type: 'staged';
+    path: string;
+};
+export interface EntryMeta {
+    kind: EntryKind;
+    skill?: string;
+    source?: string;
+}
+/** The steps of one write, in order. Tests stop a pass at one, as a crash would. */
+export type WriteBoundary = 'staged' | 'pending' | 'cleared' | 'placed' | 'removed';
+export interface WorktreeFilesOptions {
+    /** Injected in tests to exercise the copy fallback. */
+    symlink?: (target: string, path: string, type?: 'dir' | 'file' | 'junction') => Promise<void>;
+    /** Tests only: runs at each boundary of a write; a throw ends the pass there. */
+    faults?: (boundary: WriteBoundary, path: string) => void | Promise<void>;
+}
+/**
+ * Who may write a path, for one writer. `ours`: listed, and still what cezar left. `free`:
+ * nothing there. `theirs`: changed since, or never listed; the writer drops any entry and never
+ * touches it. `kept`: never touched and never dropped (an interrupted write that no longer matches,
+ * a kind or identity this cezar cannot check, another writer's path). `outside`: its parent dir
+ * leads out of the worktree.
+ */
+export interface PathState {
+    owner: 'ours' | 'free' | 'theirs' | 'kept' | 'outside';
+    current: string | null;
+    entry: ManifestEntry | undefined;
+}
+/**
+ * One writer's view of a worktree's manifest for one pass. A write runs stage, pending, clear,
+ * place, record: a crash leaves the old copy, nothing, or the new copy, each of which the next
+ * pass reads as cezar's and repairs.
+ */
+export declare class WorktreeFiles {
+    readonly worktree: string;
+    private readonly root;
+    private readonly gitDir;
+    private readonly writer;
+    private readonly loaded;
+    private readonly options;
+    private readonly byPath;
+    private readonly staged;
+    private swept;
+    private legacy;
+    roots: string[];
+    constructor(worktree: string, root: string, gitDir: string, writer: ManifestWriter, loaded: Loaded, options: WorktreeFilesOptions);
+    /** This writer's entries. */
+    entries(): ManifestEntry[];
+    entry(path: string): ManifestEntry | undefined;
+    present(path: string): Promise<boolean>;
+    inspect(path: string): Promise<PathState>;
+    /**
+     * An imported `tree:` identity, checked in its older encoding, which has no lengths: one tree can
+     * read the same as another. A match proves the path unchanged only for a single file, or for a
+     * dir holding only `SKILL.md` where cezar wrote just that. Then the entry is recorded again as
+     * `current`. Any other match is kept: it may be cezar's copy or the agent's edit. Null when
+     * nothing matched, so the path has changed.
+     */
+    private checkLegacy;
+    /** A new dir in the private git dir to build an entry in; removed when the pass ends. */
+    stagingDir(): Promise<string>;
+    /**
+     * Write `content` at `path`, which must be free or cezar's. Returns the identity it left. The
+     * pending entry is saved before the path changes; a file replaces a file in one rename. Returns
+     * null when the agent wrote at the path while the entry was staged: the path stays the agent's,
+     * with no entry.
+     */
+    put(path: string, content: EntryContent, meta: EntryMeta): Promise<string | null>;
+    /** Record what is already at `path` as cezar's: an interrupted write that finished. */
+    record(path: string, meta: EntryMeta, identity: string): void;
+    /** Remove `path` while it is cezar's. The caller's next `save()` drops the entry. */
+    remove(path: string): Promise<boolean>;
+    /** Drop this writer's entry for `path`; nothing at the path changes. */
+    forget(path: string): void;
+    /** Replace the manifest in one step: a crash leaves the old one or the new one, never half. */
+    save(): Promise<void>;
+    close(): Promise<void>;
+    /** The entry that replaces this writer's entry for `path`, if any: it keeps that entry's unknown fields. */
+    private newEntry;
+    private fault;
+    private link;
+    private build;
+}
+/**
+ * Run `pass` with `writer`'s view of the worktree's manifest. `fallback` when the worktree has no
+ * private git dir, or a newer cezar wrote a manifest version this one cannot read: then this cezar
+ * writes nothing there and leaves the file alone.
+ */
+export declare function withWorktreeFiles<T>(worktree: string, writer: ManifestWriter, options: WorktreeFilesOptions, fallback: T, pass: (files: WorktreeFiles) => Promise<T>): Promise<T>;
+export {};