@stringsync/splates 0.0.61 → 1.13.3

package/vendor/@stringsync/splates-server/board/lanes-from-tags.d.ts

@@ -0,0 +1,17 @@
+import { type Logger } from "../../../core/log/index.js";
+import { type Fs, type Ps } from "../../../core/system/index.js";
+/** Where the repository at `dir` keeps its tasks, and what to do it with. */
+export interface LanesFromTagsOptions {
+    /** The root of a repository, or of one of its worktrees. */
+    dir: string;
+    log?: Logger;
+    fs?: Fs;
+    ps?: Ps;
+}
+/**
+ * Moves the tasks of the repository at `dir` that still have tags, from
+ * before splates kept lanes instead, into a lane a tag, and says where each
+ * went; splates refuses to read them until then. Says nothing when `dir` is
+ * no repository, keeps no tasks, or none has tags.
+ */
+export declare function lanesFromTags(opts: LanesFromTagsOptions): Promise<void>;

package/vendor/@stringsync/splates-server/board/lanes.d.ts

@@ -0,0 +1,117 @@
+import type { TaskRecord } from "./task";
+/**
+ * Use these to say what blocks which tasks and which lane each runs in,
+ * given the task records: the CLI and the `splates server` page both call
+ * them, so each draws the same lanes from the same list.
+ */
+/**
+ * Every lane to show, in the order `records` keeps them, each with its
+ * tasks in list order; one a task names but `records` lacks comes last,
+ * called by its number.
+ */
+export declare function lanes(tasks: TaskRecord[], records: LaneRecord[]): LaneState[];
+/**
+ * A lane as stored: its number, never handed out again once it is gone, and
+ * what it is called. Lanes are kept in the order the board shows them.
+ */
+export interface LaneRecord {
+    id: number;
+    name: string;
+}
+/** A queue of tasks that build on each other, worked top first. */
+export interface LaneState {
+    id: number;
+    name: string;
+    todos: TaskRecord[];
+    /** The started tasks at work on its queued ones now, top first: who is on the lane. */
+    agents: string[];
+    /** The first task no started task has taken: what the lane's orchestrator hands out next. */
+    next: TaskRecord | null;
+    /**
+     * Tasks in other lanes, or in none, blocking `next` that have
+     * yet to merge: what the lane is waiting on before it can go on.
+     */
+    blockers: Blocker[];
+    /** `next` can be taken now: nothing blocking it is left but in this lane's hands. */
+    ready: boolean;
+}
+/** A task that has to merge first, and where it stands now. */
+export interface Blocker {
+    id: number;
+    subject: string;
+    /** The lane it is in, or null when it is in none. */
+    lane: number | null;
+    /** The task working on it, or null while nobody has it. */
+    takenBy: string | null;
+}
+/**
+ * The lane of each queued task some started task has taken, by the started
+ * task's name: which lane each agent at work is on.
+ */
+export declare function lanesTaken(todos: readonly TaskRecord[]): Record<string, number>;
+/** `records`, and after them a record for each lane a task is in that they lack. */
+export declare function named(tasks: TaskRecord[], records: LaneRecord[]): LaneRecord[];
+/** The lane `record` stands for, empty when no task is in it. */
+export declare function lane(tasks: TaskRecord[], record: LaneRecord): LaneState;
+/** What blocks `task` and has yet to merge, in list order. */
+export declare function blockersOf(tasks: TaskRecord[], task: TaskRecord): Blocker[];
+/** The tasks `id` blocks, in list order. */
+export declare function followers(tasks: TaskRecord[], id: number): TaskRecord[];
+/**
+ * Nothing blocking it is still open, here or in another project, none was
+ * removed from under it, and nobody has it: free to start.
+ */
+export declare function isReady(task: TaskRecord): boolean;
+/**
+ * The tasks that would form a loop if `blocker` blocked `id`, as the chain
+ * from `id` round to itself in merge order, or null when there is none. A
+ * loop is `id` already blocking `blocker`, however far down.
+ */
+export declare function cycle(tasks: TaskRecord[], id: number, blocker: number): number[] | null;
+/**
+ * `tasks` in list order, but with each one below every task in its own lane
+ * that blocks it: a task that would come too soon is moved down to just
+ * below the last of them, and everything else keeps its place.
+ */
+export declare function settle(tasks: TaskRecord[]): TaskRecord[];
+/**
+ * The first pair in `tasks`, in list order, where a task sits above one in
+ * its own lane that blocks it; null when the lanes all keep to their
+ * links.
+ */
+export declare function misordered(tasks: TaskRecord[]): {
+    task: TaskRecord;
+    blockedBy: TaskRecord;
+} | null;
+/** A blocking task, and the lane it is in by name: `#177 in Licensing`. */
+export declare function blockerLabel({ id, lane }: {
+    id: number;
+    lane: number | null;
+}, records: LaneRecord[]): string;
+/**
+ * A name for a lane holding `tasks`, none of `taken`: its first task's
+ * subject, numbered past any lane already called that. The user renames it
+ * to what the run adds up to.
+ */
+export declare function aptName(tasks: TaskRecord[], taken: string[]): string;
+/**
+ * The tasks a markdown text mentions as `#N`, once each, in the order
+ * mentioned. Code spans and blocks are left out, where `#3` means something
+ * else, as is `#N` inside a word or a link like `page#2`, and one named as
+ * the task of a project among `others`, by slug (see `elsewhereMention`).
+ */
+export declare function mentioned(text: string, others?: readonly string[]): number[];
+/** `#` and a number, standing on its own, not escaped as `\#`. */
+export declare const MENTION: RegExp;
+/**
+ * A `#N` named as the task of another project, by its slug among `others`
+ * just before it, as agents write it: `webappwiz #404`, `webappwiz task #404`,
+ * `webappwiz#404` or `#webappwiz #404`, the slug in any case. Group 1 is the
+ * slug as written, group 2 the number; null when there are no others.
+ */
+export declare function elsewhereMention(others: readonly string[]): RegExp | null;
+/**
+ * Why `task` waits on the person, its blockers removed without merging,
+ * and how to let it go on.
+ */
+export declare function lostLine(task: TaskRecord): string;

package/vendor/@stringsync/splates-server/board/routes.d.ts

@@ -0,0 +1,54 @@
+import type { ConversationRoutes } from "../conversations";
+import type { Project, ProjectWatch } from "../server/shared";
+import { type ElsewhereBoards } from "./elsewhere";
+/**
+ * Answers the page's requests to add, edit, queue and remove a project's
+ * tasks and lanes.
+ */
+export declare class BoardRoutes {
+    #private;
+    constructor(project: Project, conversations: ConversationRoutes, watch: ProjectWatch, elsewhere: {
+        boards?: ElsewhereBoards;
+        root: string;
+    });
+    readonly addQueued: (request: Request) => Promise<Response>;
+    readonly updateQueued: (request: Request) => Promise<Response>;
+    readonly moveQueued: (request: Request) => Promise<Response>;
+    readonly linkQueued: (request: Request) => Promise<Response>;
+    readonly elsewhereTasks: () => Promise<Response>;
+    /** `named` as its project's board holds it, or refuses one that is gone. */
+    private openElsewhere;
+    readonly arrangeQueued: (request: Request) => Promise<Response>;
+    readonly joinLane: (request: Request) => Promise<Response>;
+    readonly addLane: (request: Request) => Promise<Response>;
+    readonly updateLane: (request: Request) => Promise<Response>;
+    readonly assignQueued: (request: Request) => Promise<Response>;
+    /**
+     * Puts the task in the queue, `{queued: true}`, or takes it out, as
+     * `splates queue add` and `remove` do.
+     */
+    readonly queueQueued: (request: Request) => Promise<Response>;
+    /**
+     * Records the person's answer, `{answer}`, to question `{index}` of the
+     * task's deferral, which adds it to the task's detail.
+     */
+    readonly answerDeferred: (request: Request) => Promise<Response>;
+    /** Marks what the task's deferral waits on outside splates, `{index}`, as done. */
+    readonly doneOutside: (request: Request) => Promise<Response>;
+    /** Moves a queued task to `{position}` in the queue, from 1 for the next to start. */
+    readonly moveInQueue: (request: Request) => Promise<Response>;
+    /** Removes a lane with the tasks in it, which can be put back. */
+    readonly dropLane: (request: Request) => Promise<Response>;
+    readonly removeQueued: (request: Request) => Promise<Response>;
+    /** Puts back a task the page removed, under its id, where it stood. */
+    readonly restoreQueued: (request: Request) => Promise<Response>;
+    /** The task a `/api/todos/<id>` path names, or `/api/todos/<id>/position`. */
+    private taskAt;
+    /** The id a `/api/todos/<id>` path names, or `/api/todos/<id>/restore`. */
+    private idAt;
+    /**
+     * The agent a body names, `{ agent, model, effort }`, off the roster the page's
+     * conversations start from; null for `{ agent: null }`, for none.
+     */
+    private assigneeIn;
+}

package/vendor/@stringsync/splates-server/board/store.d.ts

@@ -0,0 +1,74 @@
+import type { Collection, Storage } from "../storage";
+import type { TaskState } from "../tasks";
+import type { TaskRecord, WaitingStage } from "./task";
+/**
+ * What a task gains once started: its branch, tree, lease and the rest, as
+ * its record keeps them. Its start is `startedAt`, apart from when it was
+ * first numbered.
+ */
+export type Started = Omit<TaskState, "id" | "status" | "createdAt" | "autoPick"> & {
+    startedAt: string;
+    /** The stage it was in before it started, which ending its start puts it back in. */
+    startedFrom: WaitingStage;
+};
+/**
+ * One task as `tasks/<N>.md` holds it: what the list shows of it, and once
+ * started, what `Started` adds and how its work stands.
+ */
+export type StoredTask = TaskRecord & Partial<Started> & {
+    /** How its work stands while it runs; absent before it starts. */
+    status?: TaskState["status"];
+    /**
+     * False for a task started without ever being queued, which the list
+     * leaves out; absent for one on it.
+     */
+    listed?: false;
+    /** Tags it was saved with before lanes, for `splates update` to move. */
+    tags?: string[];
+};
+/** What `record` adds once started, or null for one never started. */
+export declare function startedOf(record: StoredTask): Started | null;
+/** `record` without what starting it added, its status or whether it is listed. */
+export declare function queuedOf(record: StoredTask): TaskRecord & {
+    tags?: string[];
+};
+/**
+ * Every task in the repo, queued or started, one markdown file each under
+ * `.git/splates/tasks`, numbered. The list of tasks and the worktrees of
+ * started ones each read and write their own fields of a record, under one
+ * lock, so neither undoes what the other wrote.
+ */
+export declare class TaskStore {
+    readonly storage: Storage;
+    /** The number each started task was last found under, by its name. */
+    private readonly numbers;
+    /** The records themselves, with the files beside them that numbers and lanes keep. */
+    readonly records: Collection;
+    /** The tasks removed but kept, in `tasks/removed`. */
+    readonly removed: Collection;
+    /** Held while writing any record, and while numbering a new one. */
+    private readonly lock;
+    /** `storage` is the project's, holding `tasks/` and `tasks.lock`. */
+    constructor(storage: Storage);
+    /** Runs `run` holding the lock every write goes through. */
+    locked<T>(run: () => Promise<T>): Promise<T>;
+    /** Where task `id`'s files are kept, beside its record. */
+    filesKey(id: number): string;
+    /** Task `id`, or null when there is none or it will not parse. */
+    read(id: number): Promise<StoredTask | null>;
+    /** Every task that parses, by number. */
+    all(): Promise<StoredTask[]>;
+    /** Every started task, by number. */
+    started(): Promise<StoredTask[]>;
+    /** The started task called `task`, or null for none. */
+    find(task: string): Promise<StoredTask | null>;
+    /** Writes one task, which a reader sees whole, old or new. */
+    write(record: StoredTask): Promise<void>;
+    remove(id: number): Promise<void>;
+    /**
+     * The next number, past every one handed out before, removed ones
+     * included, so a number never comes back meaning something else. Call it
+     * under the lock.
+     */
+    next(): Promise<number>;
+}

package/vendor/@stringsync/splates-server/board/task-edit.d.ts

@@ -0,0 +1,81 @@
+import { type Logger } from "../../../core/log/index.js";
+import type { Fs, Ps } from "../../../core/system/index.js";
+import type { AgentPick } from "../models";
+import type { Facts } from "../records";
+import { type ElsewhereBlocker, type ElsewhereBoards } from "./elsewhere";
+import type { Task, TaskOrigin } from "./task";
+import type { Tasks } from "./tasks";
+export interface TaskFileOptions {
+    /** Files to attach, relative to the current directory or absolute. */
+    files?: string[];
+}
+export interface TaskAddOptions extends TaskFileOptions {
+    /** The name the task that takes it starts under; one from its subject by default. */
+    slug?: string;
+    /** Whatever more there is to say than the subject. */
+    text?: string;
+    /** Where it goes in the list, 1 at the top; the bottom by default. */
+    position?: number;
+    /** The tasks blocking it: each has to merge before it starts. */
+    blockedBy?: number[];
+    /** The tasks of other projects blocking it, each to merge there first. */
+    blockedElsewhere?: ElsewhereBlocker[];
+    /** The lane it goes in, `"new"` for one of its own; none by default. */
+    lane?: number | "new" | null;
+    /** The agent that should work it; none by default. */
+    assignee?: AgentPick | null;
+    /** The other project it is added from; none by default. */
+    origin?: TaskOrigin;
+    /** Whether whoever wrote it groomed it, for ready; the backlog by default. */
+    ready?: boolean;
+    /** This project's slug, when added from another: the task is then written `slug #N`. */
+    project?: string;
+    /** Names the projects of its blockers elsewhere by their slugs; by their directories without. */
+    boards?: Pick<ElsewhereBoards, "slug">;
+}
+export declare function taskAdd(deps: {
+    tasks: Tasks;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+}, subject: string, from: string | null, { slug, text, files, position, blockedBy, blockedElsewhere, lane, assignee, origin, ready, project, boards, }?: TaskAddOptions): Promise<Task>;
+/** What a `task add` event says of the task it added. */
+export declare function addedFacts(task: Task): Facts["task add"];
+export interface TaskUpdateOptions extends TaskFileOptions {
+    /** A new line; the old one stays when this is absent or empty. */
+    subject?: string;
+    /** A new name for the task that takes it; the old stays when this is absent or empty. */
+    slug?: string;
+    /** New detail; the old stays when this is absent or empty. */
+    text?: string;
+    /** Where to move it in the list, 1 at the top; it stays put when absent. */
+    position?: number;
+    /** Attached files to drop, by path or by the name they were stored under. */
+    removeFiles?: string[];
+    /** Tasks blocking it from now on, besides those that already do. */
+    blockedBy?: number[];
+    /** Tasks no longer blocking it. */
+    removeBlockedBy?: number[];
+    /** Tasks of other projects blocking it from now on, besides those that already do. */
+    blockedElsewhere?: ElsewhereBlocker[];
+    /** Tasks of other projects no longer blocking it. */
+    removeElsewhere?: Pick<ElsewhereBlocker, "project" | "id">[];
+    /** The lane it moves to, `"new"` for one of its own, null for none; it stays when absent. */
+    lane?: number | "new" | null;
+    /** The agent that should work it, null for none; it stays when absent. */
+    assignee?: AgentPick | null;
+    /** Marks it groomed, moving it from the backlog to ready. */
+    ready?: boolean;
+    /** Names the projects of its blockers elsewhere by their slugs; by their directories without. */
+    boards?: Pick<ElsewhereBoards, "slug">;
+}
+export declare function taskUpdate(deps: {
+    tasks: Tasks;
+    log: Logger;
+    fs: Fs;
+    ps: Ps;
+}, id: number, { subject, slug, text, position, files, removeFiles, blockedBy, removeBlockedBy, blockedElsewhere, removeElsewhere, lane, assignee, ready, boards, }?: TaskUpdateOptions): Promise<Task>;
+export declare function taskRemove({ tasks, log }: {
+    tasks: Tasks;
+    log: Logger;
+}, id: number): Promise<Task>;

package/vendor/@stringsync/splates-server/board/task-file.d.ts

@@ -0,0 +1,24 @@
+import { type TaskRecord, type TaskStage } from "./task";
+/** A task's file name under `tasks/`: its number, then `.md`. */
+export declare const TASK_FILE: RegExp;
+/** Task `record` as the text of its `tasks/<N>.md`, front matter then body. */
+export declare function encodeTask(record: object): string;
+/**
+ * The fields of a task file `encodeTask` wrote, its body as `text`; null
+ * when it will not parse or names no number.
+ */
+export declare function decodeTask(raw: string): Record<string, unknown> | null;
+/** The stage of a task whose record has none: `ready` when a model is named for it, else `backlog`. */
+export declare function stageOf(state: {
+    stage?: TaskStage;
+    assignee?: unknown;
+}): TaskStage;
+/**
+ * A task as the list reads it, with any tags it was saved with, and whether
+ * the list shows it at all; null when it will not parse.
+ */
+export declare function parseTaskFile(raw: string): {
+    state: TaskRecord;
+    tags: string[];
+    listed: boolean;
+} | null;

package/vendor/@stringsync/splates-server/board/task-journal.d.ts

@@ -0,0 +1,9 @@
+import type { Journal } from "../records";
+import type { Task } from "./task";
+import type { Tasks } from "./tasks";
+/**
+ * Use it to change task `id` with a record of it: pass `update`, what
+ * changes the task, and the journal gets what it moved, or nothing moved
+ * when the change is refused.
+ */
+export declare function recordUpdate(journal: Journal, tasks: Tasks, id: number, update: () => Promise<Task>): Promise<Task>;

package/vendor/@stringsync/splates-server/board/task-lanes.d.ts

@@ -0,0 +1,95 @@
+import { type LaneRecord } from "./lanes";
+import { type Task, type TaskRecord } from "./task";
+import type { Tasks } from "./tasks";
+/**
+ * Creates, changes and removes the lanes of a `Tasks`, moves tasks between
+ * them, and queues the tasks of a lane. Each change is atomic.
+ */
+export declare class TaskLanes {
+    private readonly tasks;
+    constructor(tasks: Tasks);
+    /** Places unmatched work in Backlog, settling dependencies and preserving a concurrent move. */
+    backlog(id: number): Promise<Task>;
+    /**
+     * Moves every task in lane `from` to the bottom of lane `into`, in the
+     * order they had, and the lane `from` is gone.
+     */
+    joinLanes(from: number, into: number): Promise<void>;
+    /** Starts an empty lane called `name`, after the others. */
+    addLane(name: string): Promise<LaneRecord>;
+    /** Calls lane `id` by another name. */
+    renameLane(id: number, name: string): Promise<LaneRecord>;
+    /**
+     * Puts lane `id` at `position` among the lanes, 1 the first column, past
+     * the last meaning the last; the others close up around it.
+     */
+    moveLane(id: number, position: number): Promise<LaneRecord[]>;
+    /**
+     * Queues every task waiting in lane `id`, once: each nobody has taken, in
+     * the backlog or ready, goes in the queue as the lane's, which starts it
+     * once nothing blocks it. A task put in the lane later is not queued. With
+     * `queued` false, takes each of its queued tasks nobody has taken back
+     * out. Gives back the lane and the tasks it queued or took out.
+     */
+    queueLane(id: number, queued: boolean): Promise<{
+        lane: LaneRecord;
+        changed: TaskRecord[];
+    }>;
+    /** Removes lane `id`, putting its tasks back in none, untriaged. */
+    dropLane(id: number, opts?: {
+        emptyOnly?: boolean;
+    }): Promise<void>;
+    /**
+     * @internal Removes each lane in `ids` that no task is in any more: a lane
+     * whose last task merged is done. One emptied by hand stays, to be filled.
+     */
+    endLanes(ids: number[]): Promise<void>;
+    /**
+     * Moves tasks saved while splates kept tags into lanes, one lane a tag,
+     * and drops their tags, which splates refuses to read until then. A task
+     * in no lane goes to the lane of its tag the most tasks share, at the
+     * bottom, in list order, below anything in that lane blocking it; a lane
+     * already called that takes them. Gives back each lane it filled, with
+     * the tasks it put there, in board order; none once no task has tags.
+     */
+    moveTagsToLanes(): Promise<{
+        lane: LaneRecord;
+        tasks: number[];
+    }[]>;
+    /**
+     * @internal The lane `lane` names: null for none, one there is, or for
+     * `"new"` one started for `tasks`, called `name` or named after them. Call
+     * it under the lock.
+     */
+    laneId(lane: number | "new" | null, states: TaskRecord[], tasks: TaskRecord[], name?: string): Promise<number | null>;
+    /**
+     * Starts a lane for `tasks` after the others, called `name`, or aptly
+     * named without one. Call it under the lock.
+     */
+    private newLane;
+    /**
+     * A lane id never handed out before, so a lane's number never comes back
+     * meaning another. Call it under the lock.
+     */
+    private nextLaneId;
+    /**
+     * @internal The lanes as stored, and after them any lane a task is in that
+     * has no record. A file that will not parse reads as none.
+     */
+    records(states: TaskRecord[]): Promise<LaneRecord[]>;
+    /**
+     * The name of every lane there has been: those on the board, and after
+     * them each that is gone as it was last called, so an orchestrator whose
+     * lanes are done still goes by their names.
+     */
+    names(states: TaskRecord[]): Promise<LaneRecord[]>;
+    /** The lane records in `file`, none when it is missing or will not parse. */
+    private read;
+    /**
+     * Writes the lanes, in board order, keeping the name of each lane they
+     * drop in `ended-lanes`. Call it under the lock.
+     */
+    private writeLanes;
+    /** Writes `records` to `file` whole, so a reader never sees half of it. */
+    private write;
+}

package/vendor/@stringsync/splates-server/board/task-list.d.ts

@@ -0,0 +1,40 @@
+import { type Logger } from "../../../core/log/index.js";
+import { type ElsewhereBoards } from "./elsewhere";
+import type { Tasks } from "./tasks";
+export interface TaskListOptions {
+    /** Print the tasks as JSON instead of a table. */
+    json?: boolean;
+    /** Only those no task has taken: the ones free to pick up. */
+    open?: boolean;
+    /**
+     * Only those free to start now: nobody has taken them, and nothing they
+     * is blocked by is still open.
+     */
+    ready?: boolean;
+    /** This project's slug, when listed from another: ids are then written `slug #N`. */
+    project?: string;
+}
+export declare function taskList({ tasks, log }: {
+    tasks: Tasks;
+    log: Logger;
+}, { json, open, ready, project }?: TaskListOptions): Promise<void>;
+export interface TaskShowOptions {
+    /** Print the task as JSON instead of prose. */
+    json?: boolean;
+    /** The other projects' slugs, whose tasks a `webappwiz #4` names, not this one's. */
+    others?: readonly string[];
+    /** This project's slug, when shown from another: the task is then written `slug #N`. */
+    project?: string;
+    /**
+     * The other projects' boards, to say where its blockers there stand and
+     * which of their tasks wait on it; without them, as its record says.
+     */
+    boards?: ElsewhereBoards;
+    /** This project's main tree, which the other projects' tasks name it by. */
+    root?: string;
+}
+/** One task in full: what `task list` shows of it, its files, and its detail. */
+export declare function taskShow({ tasks, log }: {
+    tasks: Tasks;
+    log: Logger;
+}, id: number, { json, others, project, boards, root }?: TaskShowOptions): Promise<void>;