@stringsync/splates 0.0.0-stage → 0.0.45

package/dev-conversation-routes.d.ts

@@ -0,0 +1,90 @@
+import { type Conversations } from "./conversations.js";
+import type { Project } from "./dev-project.js";
+import { Everywhere } from "./everywhere.js";
+/**
+ * How a project's page talks to agents: starting, prompting and steering its
+ * conversations, and hearing each change to them as it streams. 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 ConversationRoutes {
+    #private;
+    constructor(project: Project, conversations: Conversations | null, everywhere?: Everywhere | null);
+    held(): Conversations;
+    /**
+     * Asks every conversation at work for a checkpoint, or only those `only`
+     * names by id, without waiting on the agents, passing over the idle ones,
+     * whose turn has ended already: one whose task is merging
+     * gets to finish the merge first. While one is still asked, the
+     * checkpoint under way stands, and nothing is asked again. Answers with
+     * what settles as each asked answers.
+     */
+    readonly checkpoint: (only?: string[]) => Promise<Promise<void>[]>;
+    /** Asks the agents that do not send their limits for them, now and then. */
+    readonly refreshLimits: () => Promise<Response>;
+    readonly listConversations: () => Promise<Response>;
+    /** The tree a terminal opens in: `?task=`'s worktree, or the main tree. */
+    readonly terminalTree: (request: Request) => Promise<string>;
+    readonly startConversation: (request: Request) => Promise<Response>;
+    /**
+     * The sessions the agents hold in `?task=`'s tree that no conversation
+     * does, such as ones started in their CLI, to bring in.
+     */
+    readonly listSessions: (request: Request) => Promise<Response>;
+    /** Brings in a session an agent holds, as a conversation in `task`'s tree. */
+    readonly bringSession: (request: Request) => Promise<Response>;
+    readonly moveConversation: (request: Request) => Promise<Response>;
+    readonly promptConversation: (request: Request) => Promise<Response>;
+    readonly conversationAttachment: (request: Request) => Promise<Response>;
+    readonly conversationArtifact: (request: Request) => Promise<Response>;
+    readonly answerConversation: (request: Request) => Promise<Response>;
+    readonly cancelConversation: (request: Request) => Promise<Response>;
+    /**
+     * Checkpoints a running agent for the person and leaves it stopped,
+     * answering without waiting on the agent; one whose task is merging gets
+     * to finish the merge first.
+     */
+    readonly pauseConversation: (request: Request) => Promise<Response>;
+    /** What a background command prints, as it prints it, until it ends. */
+    readonly backgroundOutput: (request: Request) => Promise<Response>;
+    readonly stopBackground: (request: Request) => Promise<Response>;
+    readonly unqueueConversation: (request: Request) => Promise<Response>;
+    readonly sendQueuedNow: (request: Request) => Promise<Response>;
+    readonly chooseSetting: (request: Request) => Promise<Response>;
+    readonly renameConversation: (request: Request) => Promise<Response>;
+    readonly markUnread: (request: Request) => Promise<Response>;
+    readonly pinConversation: (request: Request) => Promise<Response>;
+    readonly reparentConversation: (request: Request) => Promise<Response>;
+    readonly archiveConversation: (request: Request) => Promise<Response>;
+    /**
+     * Says `text` in a conversation as the person would, for the conversation
+     * that handed it its task, as `splates tell` does: the one way in to one
+     * that answers to it, and how a lane's orchestrator wakes or stops one it
+     * started. With `stop`, the running turn stops first.
+     */
+    readonly tellConversation: (request: Request) => Promise<Response>;
+    readonly addArtifact: (request: Request) => Promise<Response>;
+    readonly removeArtifact: (request: Request) => Promise<Response>;
+    readonly deleteArtifactVersion: (request: Request) => Promise<Response>;
+    /**
+     * The person's way out of a handed-out agent: stops its turn and its
+     * process, and tells the conversation that handed it out, which decides
+     * what becomes of the task. Its next word from that one resumes it.
+     */
+    readonly terminateConversation: (request: Request) => Promise<Response>;
+    readonly conversationEvents: () => Promise<Response>;
+    disposeAsync(): Promise<void>;
+    /** Where a conversation for `task` runs: its worktree, or the main tree. */
+    /**
+     * `task`'s name, worktree, the branch it was cut from, and the
+     * conversation whose agent added it.
+     */
+    private treeFor;
+    /**
+     * Whether a task landing on `base` is a part of `task`, or a part of one
+     * of its parts, following each base back while it is a task's branch.
+     */
+    private isPartOf;
+    /** The conversation a `/api/conversations/<id>` path names. */
+    private conversationAt;
+}

package/dev-creds.d.ts

@@ -0,0 +1,17 @@
+import type { Project } from "./dev-project.js";
+import type { ProjectWatch } from "./dev-project-watch.js";
+/**
+ * How a project's Creds page fills, replaces and removes creds, and turns
+ * requests down. A value only ever comes in: no route answers with one.
+ * Each handler is a property, so `serveProject` spreads them into the
+ * project's routes.
+ */
+export declare class CredRoutes {
+    #private;
+    constructor(project: Project, watch: ProjectWatch);
+    /** What each store keeps, by name, and what the stores are called. */
+    readonly listCreds: () => Promise<Response>;
+    readonly saveCred: (request: Request) => Promise<Response>;
+    readonly removeCred: (request: Request) => Promise<Response>;
+    readonly dismissCred: (request: Request) => Promise<Response>;
+}

package/dev-dictation-connection.d.ts

@@ -0,0 +1,18 @@
+import { type Transcriber } from "webappwiz/dictate";
+import type { Connection } from "./dev-sockets.js";
+/**
+ * One dictation's socket, relaying the page's audio to a transcription and
+ * its text back. A socket that closes takes its transcription with it: the
+ * text heard so far is already in the composer.
+ */
+export declare class DictationConnection implements Connection {
+    /** Null when the project has no key, which the Creds page now asks for. */
+    private readonly transcriber;
+    private relay;
+    constructor(
+    /** Null when the project has no key, which the Creds page now asks for. */
+    transcriber: Promise<Transcriber | null>);
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(_socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    closed(): void;
+}

package/dev-dictation.d.ts

@@ -0,0 +1,17 @@
+import { type HostGate } from "./dev-http.js";
+import type { Served } from "./dev-project.js";
+import type { Connection } from "./dev-sockets.js";
+/** How a dictation finds the project its request names. */
+export interface DictationProjects {
+    projectFor(request: Request): Promise<Served>;
+}
+/**
+ * The composer's dictations, each over a WebSocket: the page streams the
+ * mic's audio up, and the text comes back as it is heard.
+ */
+export declare class Dictations {
+    private readonly gate;
+    private readonly projects;
+    constructor(gate: HostGate, projects: DictationProjects);
+    readonly open: (request: Request, server: Bun.Server<Connection>) => Promise<Response | undefined>;
+}

package/dev-http.d.ts

@@ -0,0 +1,76 @@
+import type { Resource } from "webappwiz/disposable";
+import type { Logger } from "webappwiz/log";
+import type { Attachment } from "./attachments.js";
+import type { Access, Identity } from "./dev-access.js";
+import { type Reason } from "./exit.js";
+/**
+ * Which requests `splates server` answers at all: those to a host it may be
+ * reached by, and writes only from its own page. Given `access`, a host
+ * `hosts` lets in answers only to a request Cloudflare Access verified, and
+ * such a request may use conversations and terminals too; without it,
+ * those answer only to this machine's own names, so a tunnel still reaches
+ * no further than the todos.
+ */
+export declare class HostGate {
+    private readonly log;
+    readonly access: Access | null;
+    private readonly allowed;
+    constructor(hosts: string[], log: Logger, access?: Access | null);
+    readonly guarded: <Answered extends Response | undefined>(handle: (request: Request) => Promise<Answered>) => (request: Request) => Promise<Answered | Response>;
+    /**
+     * Who Cloudflare Access says `request` comes from, or null when it comes
+     * to this machine's own names or no Access stands in front.
+     */
+    readonly identity: (request: Request) => Promise<Identity | null>;
+    readonly local: <Answered extends Response | undefined>(handle: (request: Request) => Promise<Answered>) => (request: Request) => Promise<Answered | Response>;
+}
+/** The one address the server binds: this machine, and nothing else. */
+export declare const LOOPBACK = "127.0.0.1";
+/** Names this machine answers to, which a page opened on it always may use. */
+export declare const LOCAL_HOSTS: string[];
+/** A phone photo or a short screen recording fits; a long video does not. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * The images and recordings a todo or a task may hold, by extension, and how
+ * each is served; `dev/media.tsx` shows the same ones inline.
+ */
+export declare const MEDIA_TYPES: Record<string, string>;
+/** How a refusal from the core reads over HTTP. */
+export declare const STATUS: Partial<Record<Reason, number>>;
+/** An open server-sent event stream, as the server writes to it. */
+export type EventSink = ReadableStreamDefaultController<Uint8Array>;
+/** What a stream's owner does as pages join and leave it. */
+export interface StreamWatcher {
+    /** Called once a page's stream has joined the set. */
+    opened(): void;
+    /** Called once a page's stream has left the set. */
+    closed(): void;
+}
+/**
+ * A server-sent event stream, in `listeners` while its page holds it open,
+ * pulsing so the page can tell it went quiet, and telling `watcher` as it
+ * joins and leaves.
+ */
+export declare function eventStream(listeners: Set<EventSink>, watcher?: StreamWatcher): Response;
+/** The JSON a write sends, as an object. */
+export declare function body(request: Request): Promise<Record<string, unknown>>;
+/** The files a form carries under `file`, as bytes, each with its type. */
+export declare function uploads(form: FormData): Promise<(Attachment & {
+    mimeType: string;
+})[]>;
+/**
+ * `bytes`, served as `type`, or to download when it is not an image or a
+ * recording, in the part `request` asks for: Safari plays a video only from a
+ * server that hands out its parts.
+ */
+export declare function fileResponse(request: Request, bytes: Uint8Array, type: string | undefined, headers: Record<string, string>): Response;
+/** The host a Host header names, without its port. */
+export declare function hostname(host: string): string;
+/** `text` as JSON, or null when it is not. */
+export declare function json(text: string): unknown;
+export declare function refuse(status: number, reason: string, message: string): Response;
+/**
+ * Says to `stream`'s page, every pulse, that it is still there, so a page
+ * whose stream went quiet, as across a sleep, opens it again.
+ */
+export declare function pulsing(stream: EventSink): Resource;

package/dev-open.d.ts

@@ -0,0 +1,15 @@
+/** A file to open, and the tree its editor window should hold. */
+export interface InTree {
+    tree: string;
+    file: string;
+}
+/**
+ * Where `path` opens: inside the task worktree under `worktrees` it is in,
+ * or, once that worktree is gone, at the same place in the main tree `root`,
+ * or inside `root` itself. Null for a path in neither, which the page may not
+ * open.
+ */
+export declare function inTree(path: string, { root, worktrees }: {
+    root: string;
+    worktrees: string;
+}, exists: (path: string) => Promise<boolean>): Promise<InTree | null>;

package/dev-options.d.ts

@@ -0,0 +1,133 @@
+import type { Pusher, VapidKeys } from "webappwiz/push";
+import type { HeavyCap, PortProvider } from "webappwiz/system";
+import type { Duration } from "webappwiz/time";
+import type { Config } from "./config.js";
+import type { Conversations } from "./conversations.js";
+import type { CoordinatorState } from "./coordinator-state.js";
+import type { AccessConfig } from "./dev-access.js";
+import type { Project } from "./dev-project.js";
+import type { ServerChoice } from "./dev-servers.js";
+import type { TranscriberFor } from "./dev-transcriber.js";
+import type { TunnelConfig } from "./dev-tunnel.js";
+import type { DevWorkers } from "./dev-workers.js";
+import type { Git } from "./git.js";
+import type { MachineSensors } from "./machine.js";
+import type { Slot } from "./slots.js";
+import type { WorkerMachine } from "./worker-machine.js";
+/** What `dev` lets a caller choose. */
+export interface DevOptions {
+    /**
+     * Where the local worker dials in, a Unix socket path; without it, workers
+     * reach this server only through `/api/workers`.
+     */
+    workerSocket?: string | null;
+    /** Where workers are taken in; one of its own by default. */
+    workers?: DevWorkers | null;
+    /**
+     * What this coordinator keeps across its restarts: the roots of the
+     * projects whose agents the last run let go of, served before the worker
+     * joins so they are taken back, and written again at the next restart;
+     * null keeps nothing, and a restart ends every agent.
+     */
+    coordinator?: CoordinatorState | null;
+    /**
+     * The worker agents and terminals run on, whose process table a restart
+     * reads; this machine, read directly, by default.
+     */
+    worker?: WorkerMachine | null;
+    /**
+     * The wildcard base host task ports are served under, as
+     * `<task>-<port>.<base>`, behind `access`; null serves them only on
+     * loopback ports here. Refused without `access`.
+     */
+    portsHost?: string | null;
+    /** Where to listen; the port `--port` asked for, and the span above it. */
+    ports?: PortProvider;
+    /**
+     * Host names besides this machine's own that the page may be reached by,
+     * like the hostname of a tunnel. Anything else is refused, which is what
+     * stops another site from reading the repo through a browser pointed at
+     * localhost. Who may use those names is the Access policy's business, not
+     * splates's.
+     */
+    hosts?: string[];
+    /**
+     * The Cloudflare Access application in front of `hosts`, or null for none.
+     * Given one, a request to those hosts must carry a token it signed, and
+     * then may use conversations and terminals too. Anything that exposes the
+     * page beyond this machine refuses to without it.
+     */
+    access?: AccessConfig | null;
+    /**
+     * The Cloudflare tunnel to run once listening, whose host `hosts` also
+     * lets in. Refused without `access`.
+     */
+    tunnel?: TunnelConfig | null;
+    /**
+     * Makes the conversations a project's page may hold with agents, its
+     * records in `splatesDir`, its commands watched through `git`, its limits
+     * from `config`; without it no page has any to show, and the routes
+     * say they are off.
+     */
+    conversations?: ((project: {
+        splatesDir: string;
+        git: Git;
+        config: Config;
+    }) => Conversations) | null;
+    /**
+     * The shell a page's terminal runs, as argv, in the main tree or a task's
+     * worktree; without it, the page has no terminal and the route says so.
+     */
+    shell?: string[] | null;
+    /**
+     * What a project's dictations transcribe with, by default OpenAI on the
+     * key its creds keep; a test hands in a fake.
+     */
+    transcriber?: TranscriberFor;
+    /** Opens a registered project by its root; `openRepository` by default. */
+    open?: (root: string) => Promise<Project>;
+    /**
+     * The latest splates on npm, or null when it cannot say, asked as the server
+     * starts and hourly after; the page hints at a restart once it is past
+     * `running`. Without it, nothing is checked.
+     */
+    newest?: () => Promise<string | null>;
+    /** The version serving; the one installed by default. */
+    running?: string;
+    /** How often `newest` is asked after the first time: hourly by default. */
+    checkEvery?: Duration;
+    /**
+     * The last commit to splates's own source, or null when it does not run
+     * from a checkout. Asked as the server starts, then every `sourceEvery`;
+     * once it moves on, the page hints at a restart. A server started from a
+     * checkout asks this in place of `newest`, since a restart runs the
+     * checkout again. Without it, nothing is checked.
+     */
+    source?: () => Promise<string | null>;
+    /** How often `source` is asked after the first time. */
+    sourceEvery?: Duration;
+    /**
+     * Whether building the page failed before this start, so what it serves
+     * is the page built before; the page says so.
+     */
+    unbuilt?: boolean;
+    /** The slot `splates server --slot` serves under, which the page shows; null for none. */
+    slot?: Slot | null;
+    /**
+     * Every `splates server` on this machine, the machine's own and each slot's,
+     * which the page's switcher lists beside the projects; none by default.
+     */
+    servers?: () => Promise<ServerChoice[]>;
+    /**
+     * Ends the process with `RESTART` or `UPDATE` once the server has
+     * stopped, for its supervisor to start another; without it, the page
+     * cannot restart `splates server`.
+     */
+    exit?: ((code: number) => void) | null;
+    /** Where the page's machine stats come from; this machine's OS for none. */
+    sensors?: MachineSensors | null;
+    /** Whose test runs and installs the page shows; this machine's for none. */
+    heavy?: Pick<HeavyCap, "read"> | null;
+    /** What pushes notices to the devices that subscribed; the Web Push services by default. */
+    pusher?: (keys: VapidKeys) => Pusher;
+}

package/dev-outcomes.d.ts

@@ -0,0 +1,21 @@
+import type { Fs, Ps } from "webappwiz/system";
+import { Adherence } from "./adherence.js";
+import type { Handler } from "./dev-project.js";
+/**
+ * What the page reads of how tasks ended, from the records every project on
+ * this machine shares, so one not open here still counts: the Stats page's
+ * sums, and how one merged task went.
+ */
+export declare class DevOutcomes {
+    private readonly outcomes;
+    /** What `splates server` judged of each conversation as its turns ended. */
+    readonly adherence: Adherence;
+    constructor({ fs, ps }: {
+        fs: Fs;
+        ps: Ps;
+    });
+    /** `?period=` names the period, as `PERIODS` does, or `all` for all time; 7 days for none. */
+    readonly stats: Handler;
+    /** How `/api/tasks/:task/outcome`'s task went once it merged in `project`; null when it never did. */
+    landed(project: string): Handler;
+}

package/dev-pages.d.ts

@@ -0,0 +1,16 @@
+import type { Assets } from "./dev/assets.js";
+/**
+ * The page the server hands to browsers: the files built as this run
+ * started. It changes only with a restart, which builds it again before the
+ * server comes back, so the page always matches the server it talks to.
+ */
+export declare class Pages {
+    readonly assets: Assets;
+    /** The shell, naming the script and styles by what they hold. */
+    readonly page: string;
+    constructor(assets: Assets);
+    /** The server's routes for the page's own files, spread into its `routes`. */
+    routes(): Record<string, (request: Request) => Response>;
+    /** `body` as `type`, or a 304 for a request that holds this very build. */
+    respond(request: Request, body: string | Uint8Array<ArrayBuffer>, type: string): Response;
+}

package/dev-picker.d.ts

@@ -0,0 +1,57 @@
+import type { Deps } from "webappwiz/cmd";
+import type { Fs } from "webappwiz/system";
+import type { SecretStores } from "./creds.js";
+import type { DevMachine } from "./dev-project.js";
+import type { Project } from "./projects.js";
+/**
+ * What the page's project picker asks of `splates server` beyond listing: adding
+ * a project, committing what `splates init` wrote there, and focusing one. Its
+ * handlers are properties, so `dev` hands them to its routes as they are.
+ */
+export declare class Picker {
+    private readonly deps;
+    constructor(deps: DevMachine);
+    /**
+     * Adds the repository the body's `path` names, as `splates init` there
+     * would, and focuses it.
+     */
+    readonly add: (request: Request) => Promise<Response>;
+    /** Commits the body's `paths`, which `splates init` wrote, once the person said to. */
+    readonly commit: (request: Request) => Promise<Response>;
+    /** Makes the body's `project` what an address naming none shows, on any device. */
+    readonly focus: (request: Request) => Promise<Response>;
+}
+/**
+ * What `splates init` writes in a project: the skill, its link for Claude
+ * Code, and the lock `skills` keeps. Uncommitted, each is offered again,
+ * even when an earlier init left it so.
+ */
+export declare const INIT_WRITES: string[];
+/** A project the page added, and what `splates init` left in it to commit. */
+export interface Added {
+    project: Project;
+    /**
+     * Each file init wrote that is not committed, as `git status` names it:
+     * what the page asks to commit, and all it commits.
+     */
+    uncommitted: string[];
+    /** The same, each under one of `INIT_WRITES` named by that, for the page to say. */
+    shown: string[];
+    /** The branch a commit of them lands on; null on a detached HEAD. */
+    branch: string | null;
+}
+/**
+ * Makes the repository `path` sits in a splates project, as `splates init` run
+ * there would, `~` meaning the home directory: its records, made or brought
+ * forward, the skill, and its place in the registry, focused. Commits
+ * nothing, but says what init wrote, for the page to ask before it commits.
+ */
+export declare function initProject(machine: Deps & {
+    fs: Fs;
+    secrets?: SecretStores;
+}, path: string): Promise<Added>;
+/**
+ * Commits `paths` in the main tree at `root` as setting up splates, on
+ * whatever it has checked out, leaving every other change as it was.
+ */
+export declare function commitInit({ ps }: Deps, root: string, paths: string[]): Promise<void>;

package/dev-port-socket.d.ts

@@ -0,0 +1,26 @@
+import type { Connection } from "./dev-sockets.js";
+/**
+ * A page's WebSocket to a task's server, such as a dev server's hot reload,
+ * carried on to that server: each message as it came, both ways, and a
+ * close at either end closes the other. The server's end opens first, so the
+ * page's upgrade can answer with the subprotocol the server chose.
+ */
+export declare class PortSocket implements Connection {
+    private readonly upstream;
+    private socket;
+    /** What the task's server said before the page's end opened. */
+    private early;
+    private constructor();
+    /**
+     * Opens a WebSocket to `url` with the page's `headers` and subprotocols,
+     * or says why it could not.
+     */
+    static open(url: string, headers: Headers, protocols: string[]): Promise<PortSocket | {
+        refused: string;
+    }>;
+    /** The subprotocol the task's server chose, for the page's upgrade to answer with. */
+    get protocol(): string;
+    open(socket: Bun.ServerWebSocket<Connection>): void;
+    message(_socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    closed(): void;
+}

package/dev-ports.d.ts

@@ -0,0 +1,11 @@
+import { type PortProvider } from "webappwiz/system";
+/** Preferred, not required: `dev` moves up from here when it is taken. */
+export declare const DEFAULT_PORT = 4269;
+/** How far above the port asked for `dev` will look before giving up. */
+export declare const PORT_SPAN = 20;
+/**
+ * Where `dev` will listen, given the port asked for. A flag is outside input,
+ * so a port that cannot exist is a refusal with an exit code rather than the
+ * assertion `OpenPortProvider` would raise for a bug in here.
+ */
+export declare function devPorts(from: number): PortProvider;

package/dev-project-watch.d.ts

@@ -0,0 +1,44 @@
+import { Duration } from "webappwiz/time";
+import { type StreamWatcher } from "./dev-http.js";
+import type { DevContext, Project } from "./dev-project.js";
+import { type Snapshot } from "./snapshot.js";
+/** How long changes to a repo's files settle before it is read again. */
+export declare const SETTLE: Duration;
+/**
+ * What one project's pages hear of its repo: its records, read whole, and a
+ * stream that says `changed` whenever what they show moved. The repo is
+ * watched only while a page listens.
+ */
+export declare class ProjectWatch implements StreamWatcher {
+    private readonly project;
+    private readonly context;
+    /** The streams of the pages listening. */
+    private readonly open;
+    private last;
+    private watches;
+    private readonly trees;
+    private poll;
+    private readonly settle;
+    private readonly edits;
+    /** Watches `project`, read once now so the first change is told apart. */
+    static start(project: Project, context: DevContext): Promise<ProjectWatch>;
+    private constructor();
+    /** The whole repo, as a page shows it. */
+    read(): Promise<Snapshot>;
+    tick(): Promise<void>;
+    /** Reads the repo again soon, telling its pages if anything moved. */
+    readonly changed: () => void;
+    private readonly edited;
+    /** The stream a page listens to for `changed`. */
+    events(): Response;
+    opened(): void;
+    closed(): void;
+    dispose(): void;
+    private arm;
+    private disarm;
+    /**
+     * Watches each worktree in `paths`, and no other: its SPLATES.md, and its
+     * files as they are edited, which move its counts and its systems.
+     */
+    private follow;
+}