@stringsync/splates 0.0.0-stage → 0.0.45

package/worktree.d.ts

@@ -0,0 +1,232 @@
+import { type FileDiff } from "./diff.js";
+import type { GitResult } from "./git.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * One task, whether or not it is still there. Commands ask the service for
+ * one of these and read its status rather than assembling the same handful of
+ * existence checks themselves.
+ */
+export declare class Worktree {
+    private readonly service;
+    private readonly snapshot;
+    constructor(service: WorktreeService, snapshot: WorktreeSnapshot);
+    get task(): string;
+    get branch(): string;
+    /** Where this task's work lands: its recorded base branch, else trunk. */
+    get base(): string;
+    /** The conversation whose agent added the task, or null. */
+    get caller(): string | null;
+    get path(): string;
+    get state(): TaskState | null;
+    get lease(): LeaseState | null;
+    /** The `splates server` conversation whose agent last took the task, or null. */
+    get takenBy(): string | null;
+    get leaseHeld(): boolean;
+    get leaseStatus(): "held" | "stale" | "none";
+    get leaseOurs(): boolean;
+    get leaseHeldByOther(): boolean;
+    get mergeAttempts(): number;
+    /** How many merge attempts a task gets before `merge` stops on `budget_exhausted`. */
+    get mergeAttemptLimit(): number;
+    get exists(): boolean;
+    get hasBranch(): boolean;
+    get removedAt(): string | null;
+    get status(): WorktreeStatus;
+    get gone(): boolean;
+    /**
+     * Merges changes into the record and writes it. Works on a name that has no
+     * record yet, which is how `add` writes the first one and how `claim`
+     * rebuilds one from a worktree found on disk.
+     */
+    save(changes?: Partial<TaskState>): Promise<Worktree>;
+    take(changes?: Partial<TaskState>): Promise<Worktree>;
+    /** Re-reads from disk. `merge` needs this: the record is the truth. */
+    reload(): Promise<Worktree>;
+    /**
+     * Removes the directory, the branch, and the record; remembers the name,
+     * and how the task ended.
+     */
+    discard(ended: "merged" | "removed", opts?: DiscardOptions): Promise<GitResult>;
+    /** The message of each commit it has that its base does not, oldest first. */
+    commitMessages(): Promise<string[] | null>;
+    commitsAhead(): Promise<number | null>;
+    /** Files and lines across all its pending work, as `diff` shows it; null without a branch. */
+    size(): Promise<DiffSize | null>;
+    /**
+     * Its committed and uncommitted changes, new files among them, parsed;
+     * null without a branch.
+     */
+    diff(): Promise<FileDiff[] | null>;
+    /** Committed and uncommitted paths this task touches; null without a branch. */
+    changedFiles(): Promise<string[] | null>;
+    uncommitted(): Promise<string[]>;
+    /** When its branch's latest commit was made, or null without a branch. */
+    committedAt(): Promise<string | null>;
+    interruptedOps(): Promise<string[]>;
+}
+export interface DiscardOptions {
+    /**
+     * The `splates server` conversation working on it, when ended from the page
+     * rather than by the agent, whose env names it.
+     */
+    conversation?: string;
+    /**
+     * The repo-relative paths the task changed, for a merge, which reads them
+     * before landing leaves nothing between the branch and its base. Read
+     * from the branch when not given.
+     */
+    changed?: string[];
+    /**
+     * The message of each commit a merge lands, read before landing as
+     * `changed` is.
+     */
+    commits?: string[];
+    /** Why it was removed, as `splates remove --reason` gives it. */
+    reason?: RemoveReason;
+    /** What a merge lands, read before landing as `changed` is. */
+    size?: DiffSize;
+}
+/** How big a change is, as its diff counts it. */
+export interface DiffSize {
+    files: number;
+    added: number;
+    removed: number;
+}
+/** Why a task can be removed rather than merged, as `--reason` names it. */
+export declare const REMOVE_REASONS: readonly ["nothing", "moot", "superseded", "redo"];
+/** Why a task was removed rather than merged. */
+export type RemoveReason = (typeof REMOVE_REASONS)[number];
+/** The status a task's own record carries. */
+export type RecordStatus = "working" | "merging" | "escalated";
+/** What a task's record stores about who is driving it. */
+export interface LeaseState {
+    pid: number;
+    hostname: string;
+    heartbeatAt: string;
+    /**
+     * The `splates server` conversation whose agent took it, or its caller's for a
+     * subagent; absent for an agent outside the page, and in older records.
+     */
+    conversation?: string;
+}
+export interface Escalation {
+    reason: string;
+    at: string;
+    /**
+     * Set for a task handed over to be approved rather than to answer
+     * questions, the reason saying what to look at.
+     */
+    review?: true | string;
+    /**
+     * When `claim` took the task back up, ending the wait on a person; absent
+     * while it waits, and in records from before it was kept.
+     */
+    resumedAt?: string;
+}
+/** Why a merge failed, as `merge` refuses it. */
+export type MergeFailure = "conflict" | "tests_failed" | "merge_failed";
+/** A test the gate named as failing, and what it said, as far as the runner printed. */
+export interface FailedTest {
+    name: string;
+    message: string;
+}
+/** One time `merge` turned a task away, and what it said of why. */
+export interface GateFailure {
+    reason: MergeFailure | "budget_exhausted";
+    at: string;
+    /** The files the rebase conflicted in, for a conflict. */
+    files?: string[];
+    /** What git said, for a conflict that named no file: why the rebase failed. */
+    output?: string;
+    /** The tests the gate named as failing, for `tests_failed`. */
+    tests?: string[];
+    /** Those tests with what each said, for `tests_failed`. Absent in old records. */
+    failures?: FailedTest[];
+    /** What git said, for `merge_failed`. */
+    error?: string;
+}
+export interface TaskState {
+    task: string;
+    branch: string;
+    worktree: string;
+    /** The branch this task lands on. Absent in old records: trunk. */
+    base?: string;
+    status: RecordStatus;
+    lease: LeaseState | null;
+    mergeAttempts: number;
+    /**
+     * Every merge that failed, which `retry` leaves alone while it hands back
+     * the attempts. Absent in old records: none counted yet.
+     */
+    mergeFailures?: number;
+    /** `mergeFailures` by why each failed. Absent in old records. */
+    mergeFailuresBy?: Partial<Record<MergeFailure, number>>;
+    /**
+     * Each time the gate turned it away, oldest first, with what it named:
+     * every failed merge, and each refusal once its attempts ran out. Absent in
+     * old records.
+     */
+    gateFailures?: GateFailure[];
+    /** How many times `splates retry` granted it more attempts. Absent in old records. */
+    retries?: number;
+    createdAt: string;
+    updatedAt: string;
+    escalations?: Escalation[];
+    /**
+     * The agent `splates add --agent` or `splates handoff` handed the task to, for
+     * `splates server` to start.
+     */
+    dispatch?: Dispatched;
+    /**
+     * The `splates server` conversation whose agent added the task, which the page
+     * nests it under. Absent for one added outside a conversation, or before
+     * tasks remembered it.
+     */
+    caller?: string;
+}
+/**
+ * Who `splates add --agent` or `splates handoff` handed a task to. `splates server` starts the agent in
+ * the task's tree and writes down the conversation it started, so it starts
+ * once.
+ */
+export interface Dispatched {
+    agent: string;
+    /** The model to pick, by the session's model setting; absent, the agent's own. */
+    model?: string;
+    /** What the agent is told beyond claiming the task. */
+    prompt?: string;
+    /** The conversation `splates server` started, once it has. */
+    conversation?: string;
+    /**
+     * Set while the postCheckout hook readies the tree; `splates server` starts the
+     * agent once it clears.
+     */
+    pending?: true;
+    /**
+     * Set when the agent at work on the task handed it on with `splates
+     * handoff`, so the one started is told `[SPLATES HANDOFF <task>]`.
+     */
+    handoff?: true;
+    /**
+     * Whether the agent started answers to the task's caller rather than the
+     * person, as for `splates handoff --relay`. Absent in records written
+     * before it was kept, when a handoff with a caller always relayed.
+     */
+    relay?: boolean;
+}
+/**
+ * Everything a name can turn out to be. The record's own status when the
+ * task is intact, and otherwise the way in which it is not.
+ */
+export type WorktreeStatus = RecordStatus | "absent" | "removed" | "orphaned" | "stray" | "unrecorded" | "unknown";
+/** What the service found on disk. */
+export interface WorktreeSnapshot {
+    task: string;
+    branch: string;
+    path: string;
+    state: TaskState | null;
+    exists: boolean;
+    hasBranch: boolean;
+    removedAt: string | null;
+    corrupt: boolean;
+}