@stringsync/splates 0.0.0-stage → 0.0.45

package/show.d.ts

@@ -0,0 +1,106 @@
+import { type Logger } from "webappwiz/log";
+import { type Fs } from "webappwiz/system";
+import { type NamedSystem } from "./systems.js";
+import type { Worktree } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * One task in full: what `list` shows for it, plus the `SPLATES.md` its agent
+ * left at the worktree root. Reading a tree this way takes no lease, so it
+ * cannot knock the agent driving it off its own work.
+ */
+export declare function show({ service, fs, log }: {
+    service: WorktreeService;
+    fs: Fs;
+    log: Logger;
+}, task: string, opts?: ShowOptions): Promise<void>;
+export interface Details {
+    task: string;
+    status: string;
+    branch: string;
+    base: string;
+    /** The `splates server` conversation whose agent added it, or null. */
+    caller: string | null;
+    /**
+     * The `splates server` conversation whose agent last took it, or its caller's
+     * for a subagent; null for an agent outside the page.
+     */
+    takenBy: string | null;
+    worktree: string;
+    lease: "held" | "stale" | "none";
+    ahead: number | null;
+    added: number | null;
+    removed: number | null;
+    age: string | null;
+    /** When it was added, which `age` counts from. */
+    createdAt: string | null;
+    /**
+     * The last sign of an agent at work on it: a splates command writing its
+     * record, a commit on its branch, or an edit to its SPLATES.md or to a file
+     * not yet committed. Null when nothing says.
+     */
+    activeAt: string | null;
+    escalation: string | null;
+    /** The merges it has tried; at `mergeAttemptLimit`, only `splates retry` lets it try again. */
+    mergeAttempts: number;
+    mergeAttemptLimit: number;
+    /** While escalated, when it was; null otherwise. */
+    escalatedAt: string | null;
+    /**
+     * While escalated to be approved, what to look at before approving; null
+     * otherwise.
+     */
+    review: string | null;
+    /**
+     * Whether the plan leaves nothing unchecked under `## Blocked` or
+     * `## Next`, which `splates merge` and `splates escalate --review` require.
+     */
+    ready: boolean;
+    plan: string | null;
+    /** How the `SPLATES.md` departs from the shape the skill prescribes. */
+    planProblems: string[];
+    /**
+     * Whether `splates add --agent` handed it to an agent that `splates server` has
+     * yet to start a conversation with.
+     */
+    dispatched: boolean;
+    /**
+     * The conversation `splates server` started for the agent another conversation
+     * handed it to, which answers to that one, its caller, rather than to the
+     * user; null for any other task.
+     */
+    handedTo: string | null;
+    /**
+     * The systems its changed files fall in, committed or not, in the order
+     * its worktree's `splates.systems.ts` names them.
+     */
+    systems: NamedSystem[];
+}
+export interface ShowOptions {
+    /** Print the details as JSON instead of prose. */
+    json?: boolean;
+}
+/** Configures how {@link TaskDetails} gathers a task's info. */
+export interface TaskDetailsOptions {
+    /** What the worktree is read through; the real filesystem by default. */
+    fs?: Fs;
+}
+/**
+ * Everything there is to say about one task. Split out so `dev` can render the
+ * same fields this prints, rather than assembling its own and drifting.
+ */
+export declare class TaskDetails {
+    private readonly fs;
+    constructor(opts?: TaskDetailsOptions);
+    get(worktree: Worktree): Promise<Details>;
+    /**
+     * The latest of its record's last write, its own latest commit, and the
+     * edits to its SPLATES.md and uncommitted files, as `Details.activeAt`.
+     */
+    private activeAt;
+    /**
+     * Read from its own worktree, so a system named during the task counts at
+     * once. Its changed files cost three git calls, spent only once there is a
+     * system to match them against.
+     */
+    private systems;
+}

package/skill-checks.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The rules of the splates skill a program can decide, checked over one
+ * conversation: what it said and ran, condensed, and what it left behind.
+ * `splates server` runs them on its conversations, for the Stats page's pass rate
+ * per skill version; the hand-run evals run them on theirs. Rules that take
+ * judgment, such as whether a call should have been a question, are left to
+ * a model grading the evals.
+ */
+/** Each check's verdicts on one conversation, by its id. */
+export declare function judge(transcript: Transcript, end: EndState): Record<string, Verdict[]>;
+/** A conversation as the checks read it: its own words and acts, in order. */
+export interface Transcript {
+    beats: Beat[];
+    /**
+     * Whether another conversation handed it its task, a lane's orchestrator
+     * or an agent relaying for it, so it reports to that conversation, which
+     * proposes the next todo in its place.
+     */
+    handed: boolean;
+}
+/**
+ * One thing said or done. A `user` beat starts a turn. What the agent's
+ * subagents did is left out: the rules are the agent's own.
+ */
+export type Beat = {
+    kind: "user";
+    text: string;
+}
+/** Words the agent said, one stretch of text between its tool calls. */
+ | {
+    kind: "say";
+    text: string;
+}
+/** A shell command, with the end of what it printed and whether it succeeded. */
+ | {
+    kind: "run";
+    command: string;
+    output: string;
+    ok: boolean;
+}
+/** Files a tool call wrote or edited. */
+ | {
+    kind: "edit";
+    paths: string[];
+};
+/** What the conversation left behind, which its transcript does not say. */
+export interface EndState {
+    /** Each task it merged, with the message of each commit that landed. */
+    landed: {
+        task: string;
+        commits: string[];
+    }[];
+}
+/** How one place a rule applied went. */
+export interface Verdict {
+    ok: boolean;
+    /** What was checked, and what was found when it failed. */
+    why: string;
+}
+/** A rule a program can decide; `judge` returns no verdicts where it does not apply. */
+export interface Check {
+    id: string;
+    /** The rule, as the Stats page names it. */
+    rule: string;
+    judge(transcript: Transcript, end: EndState): Verdict[];
+}
+/** Every check, in the order the Stats page lists them. */
+export declare const CHECKS: readonly Check[];
+/** Each `splates` command `command` runs, by its verb and its words after. */
+export declare function splatesCalls(command: string): {
+    verb: string;
+    args: string[];
+}[];

package/skill-checks.js

@@ -0,0 +1,10 @@
+import {
+  judge2,
+  CHECKS2,
+  splatesCalls2
+} from "./index-0tfvy823.js";
+export {
+  CHECKS2 as CHECKS,
+  judge2 as judge,
+  splatesCalls2 as splatesCalls
+};

package/skills.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "webappwiz/log";
+import { ProjectSkills } from "webappwiz/skills";
+import type { Fs, Ps } from "webappwiz/system";
+/**
+ * The repository splates's skill comes from: each release is a tag in it, and
+ * the skill its `skills/splates/SKILL.md`, which `bunx skills add` finds.
+ */
+export declare const SOURCE = "stringsync/splates";
+/** The skills a project at `root` has, installing splates's from `SOURCE`. */
+export declare function projectSkills(root: string, deps: {
+    fs: Fs;
+    ps: Ps;
+    log: Logger;
+}): ProjectSkills;
+/** The installed splates skill's version, or null when absent or unreadable. */
+export declare function installedVersion(fs: Fs, root: string): Promise<string | null>;

package/slot-tunnel.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "webappwiz/log";
+import type { Creds } from "./creds.js";
+import type { SavedTunnel, TunnelRecord } from "./saved-tunnel.js";
+import type { Slot } from "./slots.js";
+/** What the Access application in front of every slot is called. */
+export declare const SLOTS_APP = "splates-slots";
+/** The cred a slot's tunnel token is kept as, on the device. */
+export declare function slotToken({ word }: Slot): string;
+/**
+ * Makes what carries `<word>.<zone>` to a slot's `splates server`, beside the
+ * tunnel `splates tunnel setup` made, through the API with the same token: the
+ * slot's tunnel, `splates-<word>`, the DNS record routing its host to it, and,
+ * once for every slot, an Access application in front of `*.<zone>` letting
+ * in whom the machine's own lets in. Saves them in the slot's home, so its
+ * `splates server` runs them as a bare one runs the machine's. What already exists
+ * by name is reused, so running it again is safe.
+ */
+export declare function slotTunnelSetup({ slot, machine, creds, saved, log, fetch, }: {
+    slot: Slot;
+    /** What `splates tunnel setup` saved, whose zone, team and policy slots share. */
+    machine: TunnelRecord;
+    creds: Creds;
+    /** The slot home's tunnel, saved here. */
+    saved: SavedTunnel;
+    log: Logger;
+    fetch?: typeof globalThis.fetch;
+}): Promise<TunnelRecord>;

package/slots.d.ts

@@ -0,0 +1,135 @@
+import type { Logger } from "webappwiz/log";
+import { type Fs, type Lock, type Ps } from "webappwiz/system";
+/** The file in a slot's home that its server writes its pid to. */
+export declare const SERVER_PID = "server.pid";
+/** Set in a slot's server's environment to the word it serves under. */
+export declare const SLOT = "SPLATES_SLOT";
+/**
+ * Set in a slot's server's environment to the machine's `SPLATES_HOME`, whose
+ * tunnel and slots the page lists to switch between.
+ */
+export declare const MACHINE_HOME = "SPLATES_MACHINE_HOME";
+/**
+ * Which tree holds which slot, kept in `~/.splates/slots.json` for every
+ * checkout on this machine. A tree holds the same word every time, so its host
+ * name is worth writing down, for as long as it owns it: a task's worktree
+ * owns its word until the task merges or is removed, which stops its server
+ * and gives the word back. The main tree of a splates repository owns none,
+ * since every agent of it stands there, so one agent's slot would be every
+ * other's to stop. A server left running from a tree that owns its word no
+ * more still holds its port and its host, so its word goes to no other tree
+ * until `prune` stops it.
+ */
+export declare class Slots {
+    /** `~/.splates/slots.json`, or a test's own. */
+    readonly path: string;
+    private readonly deps;
+    constructor(
+    /** `~/.splates/slots.json`, or a test's own. */
+    path: string, deps: {
+        fs: Fs;
+        /** Tells whether a slot's last server still runs. */
+        ps: Pick<Ps, "pid" | "alive" | "processes" | "spawnCapture">;
+        /** Held while claiming, so two trees starting together get a word each. */
+        lock: Lock;
+        pool?: readonly {
+            word: string;
+            emoji: string;
+        }[];
+    });
+    /** The machine's slots, read from inside a slot's server too. */
+    static ofMachine({ fs, ps, log }: {
+        fs: Fs;
+        ps: Ps;
+        log: Logger;
+    }): Slots;
+    /**
+     * Whether `tree` can own a word: it exists, and is no splates repository's
+     * main tree, whose `.git` is a directory holding splates's records rather
+     * than a linked worktree's file.
+     */
+    owns(tree: string): Promise<boolean>;
+    /**
+     * The slot `tree` holds, claimed now when it holds none: the first word no
+     * tree that owns it holds, and no server still runs on. Throws, naming each
+     * holder, when every word is held.
+     */
+    claim(tree: string): Promise<Slot>;
+    /** The slot's home, its `SPLATES_HOME`: `~/.splates/slots/<word>`. */
+    home(slot: Slot): string;
+    /**
+     * The pid of the slot's last server while it still runs, as one does when
+     * its wrapper was killed or its worktree merged; null once it has stopped,
+     * or for this process itself.
+     */
+    server(slot: Slot): Promise<number | null>;
+    /** Each slot a tree that owns it holds, in the pool's order. */
+    list(): Promise<{
+        slot: Slot;
+        tree: string;
+    }[]>;
+    /** Every claimed word, owned or orphaned, with its server, in the pool's order. */
+    status(): Promise<Held[]>;
+    /**
+     * Stops the slot's server, if one runs, which ends its cloudflared too:
+     * a SIGTERM, then a SIGKILL if it outlives `STOP_WAIT`. Answers with the
+     * pid it stopped, or null when none ran.
+     */
+    stop(slot: Slot): Promise<number | null>;
+    /**
+     * Gives back the word `tree` holds, stopping its server, as a task's
+     * worktree does when it merges or is removed. Answers with what it gave
+     * back, or null when the tree held none.
+     */
+    release(tree: string): Promise<{
+        slot: Slot;
+        stopped: number | null;
+    } | null>;
+    /**
+     * Frees every orphaned word, as `status` tells them, stopping its server:
+     * the only slots any agent may stop, since each of the rest is a task's.
+     * Answers with what it freed.
+     */
+    prune(): Promise<Held[]>;
+    private read;
+    private write;
+}
+/**
+ * The words `splates server --slot` hands out, tried in this order, as
+ * sound2score's dev slots are: short animals, spellable into a phone, each
+ * with an emoji that is that animal and nothing else.
+ * Each one's tunnel is made on its first ever claim and kept, so this is also
+ * every host name a slot will ever answer on. When every one is held, add the
+ * next: goat 🐐, seal 🦭.
+ */
+export declare const SLOT_POOL: readonly {
+    word: string;
+    emoji: string;
+}[];
+/** A word of the pool, which names a slot's tunnel, host and home. */
+export interface Slot {
+    /** Like "fox". */
+    word: string;
+    /** Like "🦊": shown beside the project's name while this slot serves it. */
+    emoji: string;
+}
+/** What `release` gave back, as `merge` and `remove` report it. */
+export declare function freedLine({ slot, stopped, }: {
+    slot: Slot;
+    stopped: number | null;
+}): string;
+/** The emoji of `word`, or null for a word not in the pool. */
+export declare function slotOf(word: string): Slot | null;
+/** A claimed word, the tree that holds it, and its server while one runs. */
+export interface Held {
+    slot: Slot;
+    tree: string;
+    /** The pid of its server while one runs, as `server` tells. */
+    pid: number | null;
+    /**
+     * Whether no tree can be said to own it any more: its tree is gone, or is
+     * the main tree of a splates repository, which every agent of it shares.
+     * Only an orphan's server is any agent's to stop, by `prune`.
+     */
+    orphaned: boolean;
+}

package/snapshot.d.ts

@@ -0,0 +1,75 @@
+import type { Fs } from "webappwiz/system";
+import type { CredRequest, Creds } from "./creds.js";
+import type { LaneRecord } from "./lanes.js";
+import type { Behind, Release } from "./release.js";
+import { type Details } from "./show.js";
+import type { Slot } from "./slots.js";
+import type { TodoState } from "./todo.js";
+import type { Todos } from "./todos.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Everything one page shows: `todo list`, and `list` and `show` for each
+ * task.
+ */
+export interface Snapshot {
+    /** The repository's directory name, so a page among many says whose it is. */
+    repo: string;
+    /** Where the repository sits, with the home directory as `~`. */
+    path: string;
+    /** The main tree, absolute, which agents' file paths start from. */
+    root: string;
+    /** The directory that holds each task's worktree, absolute. */
+    worktreeRoot: string;
+    /** Past this age a todo is offered for removal rather than recommended. */
+    todoStalenessMs: number;
+    todos: TodoState[];
+    /** Every lane, in board order, empty ones too. */
+    lanes: LaneRecord[];
+    /**
+     * The name of every lane there has been, those on the board first, to
+     * name a lane's orchestrator after it once the lane is done.
+     */
+    laneNames: LaneRecord[];
+    tasks: Details[];
+    /** Every cred agents requested, open or not, the latest first; never a value. */
+    creds: CredRequest[];
+    /** The branch tasks land on, which the main tree has checked out. */
+    trunk: string;
+    /** A newer splates than the one serving, once `splates server` has seen one on npm. */
+    release: Release | null;
+    /** Commits to splates's own source since `splates server` started from it. */
+    behind: Behind | null;
+    /**
+     * Whether building the page failed as `splates server` started, so the page
+     * serving is the one built before, and may be out of date.
+     */
+    unbuilt: boolean;
+    /** The slot `splates server --slot` serves under, shown beside the project's name. */
+    slot: Slot | null;
+}
+/**
+ * Reads the whole repo the way the CLI's read commands do. Takes no lease, so
+ * the page can sit open on a live tree without disturbing the agent in it.
+ */
+export declare function snapshot({ service, todos, creds, fs, home, release, behind, unbuilt, slot, }: {
+    service: WorktreeService;
+    todos: Todos;
+    creds: Creds;
+    fs: Fs;
+    /** The home directory to show as `~`, when there is one. */
+    home?: string;
+    release?: Release | null;
+    behind?: Behind | null;
+    unbuilt?: boolean;
+    slot?: Slot | null;
+}): Promise<Snapshot>;
+/** `list` and `show` for each task, as {@link snapshot} reads them. */
+export declare function tasksOf({ service, fs, }: {
+    service: WorktreeService;
+    fs: Fs;
+}): Promise<Details[]>;
+/**
+ * A key that changes only when what the page shows does, to push a snapshot
+ * to open pages only when it differs from the last one pushed.
+ */
+export declare function fingerprint({ todos, lanes, laneNames, tasks, creds, release, behind, }: Snapshot): string;

package/splates-artifact.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates artifact`, which the root cli mounts after `splates attach`. */
+export declare const splatesArtifact: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-creds.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates creds`, which the root cli mounts after `splates lane`. */
+export declare const splatesCreds: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-dev.d.ts

@@ -0,0 +1,22 @@
+import { type DevServer } from "./dev.js";
+import type { SplatesDeps } from "./splates.js";
+/**
+ * What `splates server` does with its flags: run itself as a supervised child, so
+ * the page can restart it, which then serves the page, reached through the
+ * tunnel and Access the flags name, or else the ones saved for this machine.
+ * It serves every registered project wherever it is started; the page picks
+ * which one it shows. The server, from the child; nothing from the
+ * supervisor, which exits.
+ */
+export declare function serveDev(ctx: SplatesDeps, opts: DevFlags): Promise<DevServer | undefined>;
+/** The flags `splates server` takes, as `serveDev` reads them. */
+export interface DevFlags {
+    port: number;
+    "allow-hosts": string;
+    "access-team": string;
+    "access-aud": string;
+    tunnel: string;
+    "tunnel-name": string;
+    "ports-host": string;
+    slot: boolean;
+}

package/splates-flags.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { Repository } from "./repository.js";
+import { type AgentPick, Roster, type RosterAgent } from "./roster.js";
+import { SavedPortsHost } from "./saved-ports-host.js";
+import { SavedTunnel } from "./saved-tunnel.js";
+import type { SplatesDeps } from "./splates.js";
+/** A place in the todo list, 1 at the top; absent leaves it to the command. */
+export declare const position: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+/**
+ * The agent `--agent` and `--model` name off the roster: undefined when
+ * neither is given, null for `--agent none`.
+ */
+export declare function assigneeIn(deps: SplatesDeps, agent: string, model: string): Promise<AgentPick | null | undefined>;
+/** The user's roster, beside the project registry. */
+export declare function rosterOf({ ps, fs }: SplatesDeps): Roster;
+/** The tunnel `splates tunnel setup` saved for this machine. */
+/** The base host `splates server --ports-host` saved for this machine. */
+export declare function savedPortsHostOf({ ps, fs }: SplatesDeps): SavedPortsHost;
+export declare function savedTunnelOf({ ps, fs, secrets, }: SplatesDeps): SavedTunnel;
+/** The tunnel each slot's home may have saved, for every word of the pool. */
+export declare function slotTunnelsOf({ ps, fs, secrets, }: SplatesDeps): SavedTunnel[];
+/** The roster's agents, written out as the defaults first when there is none. */
+export declare function seeded(roster: Roster): Promise<RosterAgent[]>;
+/** `--lane 3`, `new` or `none` as a lane; absent leaves it to the command. */
+export declare function laneIn(raw: string): number | "new" | null | undefined;
+/** `--todo 3,5` as ids, refusing anything that is not one. */
+export declare function todoIds(raw: string): number[];
+/** A comma-separated flag's values, with no empty ones. */
+export declare function commaList(raw: string): string[];
+/**
+ * Which task a command that takes no task name is about, so the journal can
+ * name it. `merge` and `escalate` read it off the current branch.
+ */
+export declare function here({ service, git, ps, project, }: SplatesDeps & Repository): Promise<string | null>;

package/splates-lane.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates lane`, which the root cli mounts after `splates todo`. */
+export declare const splatesLane: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-projects.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates projects`, which the root cli mounts after `splates lane`. */
+export declare const splatesProjects: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-setup.d.ts

@@ -0,0 +1,17 @@
+import { Setup } from "./setup.js";
+import type { SplatesDeps } from "./splates.js";
+/** This machine's setup, read through `deps`. */
+export declare function setupOf({ fs, ps, secrets, fetch, }: SplatesDeps): Setup;
+/** What `splates setup` was asked for. */
+export interface SetupOptions {
+    /** A step's id, or empty for every area's progress. */
+    step: string;
+    json: boolean;
+    skip: boolean;
+    unskip: boolean;
+}
+/**
+ * `splates setup [step]`: progress by area and the one next step, or one step's
+ * why and instructions, after skipping or unskipping it when asked.
+ */
+export declare function setup(deps: SplatesDeps, opts: SetupOptions): Promise<void>;

package/splates-slots.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates slots`, which the root cli mounts after `splates tunnel`. */
+export declare const splatesSlots: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-todo.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates todo`, which the root cli mounts after the task commands. */
+export declare const splatesTodo: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-tunnel.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates tunnel`, which the root cli mounts after `splates lane`. */
+export declare const splatesTunnel: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates-worker.d.ts

@@ -0,0 +1,3 @@
+import type { SplatesDeps } from "./splates.js";
+/** `splates worker`, which the root cli mounts after `splates slots`. */
+export declare const splatesWorker: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;

package/splates.d.ts

@@ -0,0 +1,28 @@
+import { type Deps } from "webappwiz/cmd";
+import type { Fs } from "webappwiz/system";
+import type { SecretStores } from "./creds.js";
+import type { Assets } from "./dev/assets.js";
+/** Everything `splates` is run with, before the repository middleware adds to it. */
+export interface SplatesDeps extends Deps {
+    fs: Fs;
+    /**
+     * The registered project a leading `--project <slug>` names, which repo
+     * commands run on instead of the one the working directory is in.
+     */
+    project?: string;
+    /** The built page `dev` serves as its preview. */
+    assets: Assets;
+    /** Where creds are kept; the system's stores by default. */
+    secrets?: SecretStores;
+    /** How `splates tunnel setup` reaches Cloudflare's API; the global one by default. */
+    fetch?: typeof fetch;
+}
+/**
+ * Splits a leading `--project <slug>`, or `--project=<slug>`, off the
+ * arguments, for `run` to be handed as `project`.
+ */
+export declare function projectArgs(argv: string[]): {
+    project?: string;
+    argv: string[];
+};
+export declare const splates: import("webappwiz/cmd").Cli<SplatesDeps, SplatesDeps>;