@stringsync/splates 0.0.0-stage → 0.0.45

package/dev-tasks.d.ts

@@ -0,0 +1,20 @@
+import type { Conversations } from "./conversations.js";
+import type { Project } from "./dev-project.js";
+import type { ProjectWatch } from "./dev-project-watch.js";
+/**
+ * What a project's page reads of its tasks, and what it does to them. Each
+ * handler is a property, so `serveProject` spreads them into the project's
+ * routes; what they work on stays private, out of the spread.
+ */
+export declare class TaskRoutes {
+    #private;
+    constructor(project: Project, conversations: Conversations | null, watch: ProjectWatch);
+    readonly file: (request: Request) => Promise<Response>;
+    readonly open: (request: Request) => Promise<Response>;
+    readonly paths: (request: Request) => Promise<Response>;
+    readonly systems: (request: Request) => Promise<Response>;
+    readonly systemChanges: () => Promise<Response>;
+    readonly diff: (request: Request) => Promise<Response>;
+    readonly retryTask: (request: Request) => Promise<Response>;
+    readonly removeTask: (request: Request) => Promise<Response>;
+}

package/dev-terminal-connection.d.ts

@@ -0,0 +1,19 @@
+import type { Shell } from "./dev-shell.js";
+import type { Connection } from "./dev-sockets.js";
+/**
+ * One terminal's socket, which shows a `Shell`: bytes both ways are the
+ * shell's own; text is for what is not, as JSON: a resize or a question
+ * from the page, the shell's exit code and the job in front, null at a
+ * prompt, from here.
+ */
+export declare class TerminalConnection implements Connection {
+    private readonly shell;
+    /** Whether the page comes back to a shell it had, which redraws for it. */
+    private readonly back;
+    constructor(shell: Shell, 
+    /** Whether the page comes back to a shell it had, which redraws for it. */
+    back: boolean);
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    closed(socket: Bun.ServerWebSocket<Connection>): void;
+}

package/dev-terminal.d.ts

@@ -0,0 +1,42 @@
+import { type Timer } from "webappwiz/time";
+import { type HostGate } from "./dev-http.js";
+import type { Served } from "./dev-project.js";
+import { type KeptShell, type ShellHost } from "./dev-shell.js";
+import type { Connection } from "./dev-sockets.js";
+/** How a terminal finds the project its request names. */
+export interface TerminalProjects {
+    projectFor(request: Request): Promise<Served>;
+}
+/**
+ * The shells a page opens over `/api/terminal`, each in the main tree or a
+ * task's worktree. Open one with `?terminal=<key>` to come back to it by
+ * that key after a reload or a restart of `splates server`; `handOver` and
+ * `takeBack` carry keyed shells across the restart, and `disposeAsync`
+ * hangs up on them all.
+ */
+export declare class Terminals {
+    private readonly gate;
+    private readonly shell;
+    private readonly projects;
+    /** The worker the shells run on, whose process table says their jobs in front. */
+    private readonly worker;
+    private readonly shells;
+    private readonly timer;
+    constructor(gate: HostGate, shell: string[] | null, projects: TerminalProjects, 
+    /** The worker the shells run on, whose process table says their jobs in front. */
+    worker: ShellHost, { timer }?: {
+        timer?: Timer;
+    });
+    /**
+     * Takes back the shells the last run let go of, each waiting for its page
+     * to come back; before the worker joins, whose hello says which it kept.
+     */
+    takeBack(kept: KeptShell[]): void;
+    /**
+     * Lets go of every keyed shell for the next run to take back, and says
+     * which; the rest end with the server.
+     */
+    handOver(): KeptShell[];
+    readonly open: (request: Request, server: Bun.Server<Connection>) => Promise<Response | undefined>;
+    disposeAsync(): Promise<void>;
+}

package/dev-todos.d.ts

@@ -0,0 +1,35 @@
+import type { ConversationRoutes } from "./dev-conversation-routes.js";
+import type { Project } from "./dev-project.js";
+import type { ProjectWatch } from "./dev-project-watch.js";
+/**
+ * How a project's page writes its todos and lanes, each write journaled and
+ * read back for the pages listening. Each handler is a property, so
+ * `serveProject` spreads them into the project's routes; what they work on
+ * stays private, out of the spread.
+ */
+export declare class TodoRoutes {
+    #private;
+    constructor(project: Project, conversations: ConversationRoutes, watch: ProjectWatch);
+    readonly addTodo: (request: Request) => Promise<Response>;
+    readonly updateTodo: (request: Request) => Promise<Response>;
+    readonly moveTodo: (request: Request) => Promise<Response>;
+    readonly linkTodo: (request: Request) => Promise<Response>;
+    readonly arrangeTodo: (request: Request) => Promise<Response>;
+    readonly joinLane: (request: Request) => Promise<Response>;
+    readonly addLane: (request: Request) => Promise<Response>;
+    readonly updateLane: (request: Request) => Promise<Response>;
+    readonly assignTodo: (request: Request) => Promise<Response>;
+    readonly dropLane: (request: Request) => Promise<Response>;
+    readonly removeTodo: (request: Request) => Promise<Response>;
+    /** Puts back a todo the page removed, under its id, where it stood. */
+    readonly restoreTodo: (request: Request) => Promise<Response>;
+    /** The todo a `/api/todos/<id>` path names, or `/api/todos/<id>/position`. */
+    private todoAt;
+    /** The id a `/api/todos/<id>` path names, or `/api/todos/<id>/restore`. */
+    private idAt;
+    /**
+     * The agent a body names, `{ agent, model }`, off the roster the page's
+     * conversations start from; null for `{ agent: null }`, for none.
+     */
+    private assigneeIn;
+}

package/dev-transcriber.d.ts

@@ -0,0 +1,15 @@
+import type { Transcriber } from "webappwiz/dictate";
+import type { Project } from "./dev-project.js";
+/** The cred a dictation transcribes with. */
+export declare const OPENAI_KEY = "OPENAI_API_KEY";
+/** What a dictation in a project transcribes with, null once it asked for a key. */
+export type TranscriberFor = (project: Project, 
+/** Tells the project's pages that its records moved, as a new request does. */
+tick: () => Promise<void>) => Promise<Transcriber | null>;
+/**
+ * What a dictation in `project` transcribes with: OpenAI on the key the
+ * project's or the device's store keeps, told the project's own words so it
+ * spells them its way, read afresh for each take. Null, after asking for the
+ * key on the Creds page, when neither store keeps one.
+ */
+export declare const transcriberFor: TranscriberFor;

package/dev-tunnel.d.ts

@@ -0,0 +1,38 @@
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Ps } from "webappwiz/system";
+import { type AccessConfig } from "./dev-access.js";
+import type { SavedTunnel } from "./saved-tunnel.js";
+import type { TunnelProvider } from "./tunnel-provider.js";
+/** The tunnel `splates server` runs to reach the page from elsewhere. */
+export interface TunnelConfig {
+    /** The public hostname the tunnel carries to the page. */
+    host: string;
+    provider: TunnelProvider;
+}
+/**
+ * The tunnel `--tunnel` and `--tunnel-name` ask for, or null when no host is
+ * given, run by `custom`, the provider `splates.config.ts` names, or else by
+ * `cloudflared`. Refused without `access`, so a tunnel never exposes the page
+ * to anyone Cloudflare Access has not let in.
+ */
+export declare function tunnelConfig(host: string, name: string, access: AccessConfig | null, custom: TunnelProvider | null, ps: Ps): TunnelConfig | null;
+/** `host`, lowercased, refused unless it is a host name. */
+export declare function hostName(host: string): string;
+/**
+ * The tunnel `splates tunnel setup` saved, and the Access application in front
+ * of it, which a bare `splates server` runs; null when none was saved. One whose
+ * token the secret store cannot give is logged and left off, never fatal: the
+ * page still answers on this machine.
+ */
+export declare function savedTunnelConfig(saved: SavedTunnel, ps: Ps, log: Logger): Promise<{
+    access: AccessConfig;
+    tunnel: TunnelConfig;
+} | null>;
+/**
+ * Starts `tunnel` carrying its host to `url`, once the page listens. A provider
+ * that is not ready, or that cannot start, is logged and skipped, never fatal:
+ * the page still answers on this machine. The run is what to dispose of with
+ * the server, or null when there is none.
+ */
+export declare function startTunnel(tunnel: TunnelConfig, url: string, log: Logger): Promise<AsyncResource | null>;

package/dev-versions.d.ts

@@ -0,0 +1,53 @@
+import type { Resource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Duration } from "webappwiz/time";
+import type { Served } from "./dev-project.js";
+import { type Behind, type Release } from "./release.js";
+/** What `Versions` takes from `dev`'s options. */
+export interface VersionsOptions {
+    /** The version serving. */
+    running: string;
+    /** The latest splates on npm, or null when it cannot say. */
+    newest: () => Promise<string | null>;
+    checkEvery: Duration;
+    /** The last commit to splates's own source, or null outside a checkout. */
+    source: () => Promise<string | null>;
+    sourceEvery: Duration;
+}
+/**
+ * Whether this run of `splates server` is stale: a newer splates on npm, or, run
+ * from a checkout, commits to splates's own source since it started. Each
+ * project's pages are told as a check finds one.
+ */
+export declare class Versions {
+    private readonly served;
+    private readonly log;
+    /**
+     * The last commit to splates's own source as this run started, or null
+     * when it does not run from a checkout of it.
+     */
+    private readonly started;
+    private readonly opts;
+    /** A newer splates on npm, once a check has found one; every page says so. */
+    private newer;
+    /** Commits to that source since, once a check has seen one. */
+    private ahead;
+    /**
+     * Versions for this run, reading splates's source now, so a later commit
+     * to it is what makes this run stale.
+     */
+    static start(served: Map<string, Promise<Served>>, log: Logger, opts: VersionsOptions): Promise<Versions>;
+    private constructor();
+    get running(): string;
+    get release(): Release | null;
+    get behind(): Behind | null;
+    /**
+     * Checks for a newer splates, or, run from a checkout, for commits to its
+     * source, until disposed.
+     */
+    check(): Resource;
+    private checkNpm;
+    private checkSource;
+    /** Tells each project's pages to read it again. */
+    private refresh;
+}

package/dev-workers.d.ts

@@ -0,0 +1,55 @@
+import type { AsyncResource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+import type { Connection } from "./dev-sockets.js";
+import type { RemoteWorker } from "./remote-worker.js";
+import { WorkerRegistry } from "./worker-registry.js";
+/** What the worker the supervisor starts beside the server is known by. */
+export declare const LOCAL_WORKER = "local";
+/** What `DevWorkers` answers workers as. */
+export interface DevWorkersOptions {
+    /**
+     * The session id every worker hears in its welcome: the same across
+     * restarts, so a worker keeps what it runs for the next run to take
+     * back; new by default, which ends what the worker held.
+     */
+    session?: string;
+}
+/**
+ * Where `splates server` takes its workers in, as their coordinator: the local
+ * worker through a Unix socket only this user may open, and others through
+ * `/api/workers`. Nothing places work on them yet; the registry keeps them
+ * for what comes next.
+ */
+export declare class DevWorkers implements AsyncResource {
+    private readonly log;
+    readonly registry: WorkerRegistry;
+    /** This machine's worker, which agents run on; work waits for it to join. */
+    readonly local: RemoteWorker;
+    private listener;
+    /** Whether a worker may join: not while what the last run let go of is being taken back. */
+    private ready;
+    constructor(log: Logger, { session }?: DevWorkersOptions);
+    /**
+     * Turns workers away until `serving`, while the conversations the last
+     * run let go of take their processes back, since a worker's hello
+     * settles which channels live on.
+     */
+    takingBack(): void;
+    /** Lets workers join again. */
+    serving(): void;
+    /** Hangs up on every worker for a restart, keeping what each runs (see `WorkerRegistry.detach`). */
+    detach(): Promise<void>;
+    /**
+     * Listens at `path`, logging rather than failing when it cannot, as when
+     * another `splates server` with the same home already does: the page works
+     * without workers.
+     */
+    listen(path: string, fs: Fs): Promise<void>;
+    readonly open: (request: Request, server: Bun.Server<Connection>) => Response | undefined;
+    /** `GET /api/workers`: each worker and each refusal, as `splates worker list` shows them. */
+    readonly list: () => Promise<Response>;
+    /** A worker upgrades; anyone else is asking who has joined, and `guard` decides who may. */
+    readonly route: (request: Request, server: Bun.Server<Connection>, guard: (handle: (request: Request) => Promise<Response>) => (request: Request) => Promise<Response>) => Response | undefined | Promise<Response>;
+    disposeAsync(): Promise<void>;
+}

package/dev.d.ts

@@ -0,0 +1,24 @@
+import { type AsyncResource } from "webappwiz/disposable";
+import type { DevOptions } from "./dev-options.js";
+import { type DevMachine } from "./dev-project.js";
+export type { DevOptions } from "./dev-options.js";
+export { DEFAULT_PORT, devPorts, PORT_SPAN } from "./dev-ports.js";
+/**
+ * Serves what `todo list`, `list` and `show` print as one page that refetches
+ * when the repo changes, where a person adds, edits, reorders and removes
+ * todos. Anything that moves a task (merge, claim) stays in the CLI, and
+ * removing one answers only to this machine's own names, so a page that
+ * should not have been reachable can at worst change a todo.
+ *
+ * Given `conversations`, the page also talks to agents, which run commands on
+ * this machine. Those routes answer only to this machine's own names, or,
+ * given `access`, to a host `hosts` lets in once Cloudflare Access verified
+ * who is asking; without it, a tunnel still reaches no further than the todos.
+ */
+export declare function dev(deps: DevMachine, { ports, hosts, access, tunnel, conversations: converse, shell, transcriber, newest, running, checkEvery, // how often to ask npm for a newer splates
+source, sourceEvery, // how often to read a checkout's last commit
+unbuilt, slot, servers, exit, sensors, heavy, workerSocket, workers: givenWorkers, worker, coordinator, portsHost, pusher, open, }?: DevOptions): Promise<DevServer>;
+/** A running server, and the one thing a caller ever wants to do with it. */
+export interface DevServer extends AsyncResource {
+    port: number;
+}

package/diff.d.ts

@@ -0,0 +1,29 @@
+/** A line of a diff, as assistant-ui's `CodeDiff` draws one. */
+export interface DiffLine {
+    kind: "context" | "added" | "removed";
+    text: string;
+}
+/** A run of changed lines and the context around them. */
+export interface Hunk {
+    /** Where it is, as git heads it: `@@ -10,6 +10,8 @@`. */
+    range: string;
+    lines: DiffLine[];
+}
+/** One file's changes. */
+export interface FileDiff {
+    path: string;
+    /** Where it was, for a file that moved; null otherwise. */
+    from: string | null;
+    status: "added" | "deleted" | "renamed" | "modified";
+    added: number;
+    removed: number;
+    /** Git says only that it differs, with no lines to show. */
+    binary: boolean;
+    /** Some of it is not committed yet. */
+    uncommitted: boolean;
+    hunks: Hunk[];
+}
+/** `git diff` output as files, hunks and lines. */
+export declare function parseDiff(text: string): FileDiff[];
+/** An edit as lines: what it took out, then what it put in. */
+export declare function editLines(old: string | null, now: string): DiffLine[];

package/dispatched.d.ts

@@ -0,0 +1,16 @@
+import type { Logger } from "webappwiz/log";
+import type { Conversations } from "./conversations.js";
+import type { WorktreeService } from "./worktree-service.js";
+/**
+ * Starts the agent of each task `splates add --agent` or `splates handoff` handed
+ * to one and that has none yet, in the task's tree, on the model asked for,
+ * told to claim it, or to take it over for a handoff. The
+ * conversation it starts goes on the record before the agent is told
+ * anything, so a task is started once however often this runs, as long as
+ * no two runs overlap. Answers once each is started, not told.
+ */
+export declare function startDispatched({ service, conversations, log, }: {
+    service: WorktreeService;
+    conversations: Conversations;
+    log: Logger;
+}): Promise<void>;

package/editors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The editors a file the page names opens in: the link the browser hands it,
+ * and the command `dev` runs on this machine to open the file inside the
+ * tree it belongs to, which a link cannot say.
+ */
+export interface Editor {
+    id: string;
+    /** What the Settings dialog calls it. */
+    label: string;
+    /** The scheme of its `<scheme>://file/<path>:<line>` links. */
+    scheme: string;
+    /**
+     * The command that opens `tree` as its window and `file` in it, at `line`
+     * when there is one; the window alone when `file` is the tree.
+     */
+    argv(tree: string, file: string, line: number | null): string[];
+}
+export declare const ZED: Editor;
+/** Every editor, in the order the Settings dialog offers them. */
+export declare const EDITORS: readonly [Editor, Editor, Editor];
+/** The editor `id` names, or null for one this splates does not know. */
+export declare function editorOf(id: string): Editor | null;

package/escalate.d.ts

@@ -0,0 +1,27 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs, Lock } from "webappwiz/system";
+import type { Facts } from "./events.js";
+import type { Git } from "./git.js";
+import type { WorktreeService } from "./worktree-service.js";
+export interface EscalateOptions {
+    /** Task to escalate. Defaults to the one `cwd` is a worktree for. */
+    task?: string;
+    /**
+     * Ask a person to approve merging, rather than to answer questions, with
+     * the reason as what to look at. Refused until the task is ready to merge:
+     * every question under `## Blocked` and step under `## Next` checked.
+     */
+    review?: boolean;
+}
+/**
+ * The way out that is not "resolve the conflict badly to finish the task".
+ * When both sides restructured the same logic there is no correct merge, only
+ * a decision, and that belongs to a human.
+ */
+export declare function escalate({ service, git, lock, log, fs, }: {
+    service: WorktreeService;
+    git: Git;
+    lock: Lock;
+    log: Logger;
+    fs: Fs;
+}, reason: string, cwd: string, { task, review }?: EscalateOptions): Promise<Facts["escalate"]>;