@stringsync/splates 0.0.45 → 0.0.46

package/dev-options.d.ts

@@ -1,133 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,44 +0,0 @@
-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;
-}

package/dev-project.d.ts

@@ -1,168 +0,0 @@
-import type { Deps } from "webappwiz/cmd";
-import type { Transcriber } from "webappwiz/dictate";
-import type { AsyncResource } from "webappwiz/disposable";
-import type { Logger } from "webappwiz/log";
-import type { Fs, Ps } from "webappwiz/system";
-import type { ConversationState, Conversations } from "./conversations.js";
-import type { SecretStores } from "./creds.js";
-import type { Assets } from "./dev/assets.js";
-import type { TranscriberFor } from "./dev-transcriber.js";
-import type { Everywhere } from "./everywhere.js";
-import type { Format } from "./format.js";
-import type { LaneRecord } from "./lanes.js";
-import { type Needing } from "./needs.js";
-import type { Projects } from "./projects.js";
-import type { Behind, Release } from "./release.js";
-import type { Repository } from "./repository.js";
-import type { Details } from "./show.js";
-import type { Slot } from "./slots.js";
-import type { PortOwners } from "./task-ports.js";
-/**
- * Everything one project's page talks to: its records, its stream of
- * changes and its conversations, kept from the first request for it until
- * the server stops.
- */
-export declare function serveProject(project: Project, context: DevContext): Promise<Served>;
-/** What `dev` serves a project with: its own records, read and written. */
-export type Project = Pick<Repository, "service" | "journal" | "todos" | "format" | "splatesDir" | "git" | "creds" | "slots"> & {
-    fs: Fs;
-    ps: Ps;
-    log: Logger;
-};
-/**
- * What `dev` runs with: the machine's, not any project's, since it serves
- * every registered project wherever it was started.
- */
-export type DevMachine = Deps & {
-    fs: Fs;
-    /** Where each project's creds are kept; the system's stores by default. */
-    secrets?: SecretStores;
-    /** How setup's checks reach the network; the global fetch by default. */
-    fetch?: typeof fetch;
-    /** The built page. */
-    assets: Assets;
-    /** Every splates project on this machine. */
-    projects: Projects;
-    /**
-     * Projects opened already, served as they are rather than opened again:
-     * a test's own, with its fakes.
-     */
-    opened?: Project[];
-};
-/** What the server as a whole tells each project it serves. */
-export interface DevContext {
-    /** Where the agents' own `splates` reaches this server, once it listens. */
-    readonly url: string | null;
-    /** A newer splates on npm, once a check has found one; every page says so. */
-    readonly release: Release | null;
-    /** Commits to splates's own source since this run started, once seen. */
-    readonly behind: Behind | null;
-    /** Whether building the page failed, so it serves the one built before. */
-    readonly unbuilt: boolean;
-    /** The slot `splates server --slot` serves under, or null. */
-    readonly slot: Slot | null;
-    /** The conversations `project`'s page may hold, or null when they are off. */
-    conversationsFor(project: Project): Conversations | null;
-    /** Every served project's conversations, where a caller of one may be. */
-    readonly everywhere: Everywhere;
-    /** What `project`'s dictations transcribe with. */
-    readonly transcriberFor: TranscriberFor;
-}
-/** A route's work once its project is known. */
-export type Handler = (request: Request) => Promise<Response>;
-/** One project as the server holds it: what each of its routes does. */
-export interface Served extends AsyncResource {
-    root: string;
-    format: Format;
-    conversations: Conversations | null;
-    /** Reads the repo again soon, telling its pages if anything moved. */
-    refresh: () => void;
-    snapshot: Handler;
-    /** How many of its agents wait on the person. */
-    waiting: () => Promise<number>;
-    /** What each of its agents needs, and the lanes that name an orchestrator. */
-    needing: () => Promise<{
-        rows: Needing[];
-        lanes: LaneRecord[];
-    }>;
-    /** Every lane there has been, to name an orchestrator after. */
-    lanes: () => Promise<LaneRecord[]>;
-    /** Its tasks' worktrees and agents, whose processes' ports are the tasks'. */
-    portOwners: () => Promise<PortOwners>;
-    events: Handler;
-    file: Handler;
-    open: Handler;
-    paths: Handler;
-    systems: Handler;
-    systemChanges: Handler;
-    diff: Handler;
-    retryTask: Handler;
-    removeTask: Handler;
-    addTodo: Handler;
-    updateTodo: Handler;
-    moveTodo: Handler;
-    linkTodo: Handler;
-    arrangeTodo: Handler;
-    assignTodo: Handler;
-    joinLane: Handler;
-    addLane: Handler;
-    updateLane: Handler;
-    dropLane: Handler;
-    removeTodo: Handler;
-    restoreTodo: Handler;
-    listCreds: Handler;
-    saveCred: Handler;
-    removeCred: Handler;
-    dismissCred: Handler;
-    listBudgets: Handler;
-    setBudget: Handler;
-    raiseBudget: Handler;
-    endRaise: Handler;
-    pauseBudget: Handler;
-    resumeBudget: Handler;
-    listConversations: Handler;
-    refreshLimits: Handler;
-    startConversation: Handler;
-    listSessions: Handler;
-    bringSession: Handler;
-    /**
-     * Asks every live conversation here to bring its SPLATES.md up to date,
-     * answering with what settles as each answers.
-     */
-    checkpoint: (only?: string[]) => Promise<Promise<void>[]>;
-    moveConversation: Handler;
-    promptConversation: Handler;
-    tellConversation: Handler;
-    addArtifact: Handler;
-    removeArtifact: Handler;
-    deleteArtifactVersion: Handler;
-    terminateConversation: Handler;
-    conversationAttachment: Handler;
-    conversationArtifact: Handler;
-    answerConversation: Handler;
-    cancelConversation: Handler;
-    pauseConversation: Handler;
-    stopBackground: Handler;
-    backgroundOutput: Handler;
-    unqueueConversation: Handler;
-    sendQueuedNow: Handler;
-    chooseSetting: Handler;
-    renameConversation: Handler;
-    markUnread: Handler;
-    pinConversation: Handler;
-    reparentConversation: Handler;
-    archiveConversation: Handler;
-    conversationEvents: Handler;
-    terminalTree: (request: Request) => Promise<string>;
-    /**
-     * What a dictation transcribes with, read afresh for each take; null,
-     * after asking for the key on the Creds page, without one.
-     */
-    transcriber: () => Promise<Transcriber | null>;
-}
-/**
- * How many agents wait on the person, as the page's own waiting line counts
- * them, but for an external agent whose reply the page copied: only the page
- * knows that.
- */
-export declare function waitingOn(tasks: Details[], conversations: ConversationState[]): number;

package/dev-push.d.ts

@@ -1,59 +0,0 @@
-import type { Logger } from "webappwiz/log";
-import { type Pusher, type VapidKeys } from "webappwiz/push";
-import type { Fs, Ps } from "webappwiz/system";
-import { Duration } from "webappwiz/time";
-import type { Handler, Served } from "./dev-project.js";
-import type { Projects } from "./projects.js";
-/** How often the server looks for something worth pushing, while a device listens. */
-export declare const PUSH_EVERY: Duration;
-/** What `Pushes` reads each served project through. */
-export interface PushesDeps {
-    fs: Fs;
-    ps: Ps;
-    log: Logger;
-    projects: Projects;
-    /** By root, every project the server has opened. */
-    served: Map<string, Promise<Served>>;
-    /** What sends a push, signed with the keys kept; the Web Push services by default. */
-    pusher?: (keys: VapidKeys) => Pusher;
-    /** How often to look; `PUSH_EVERY` by default. */
-    every?: Duration;
-}
-/**
- * Tells each device that subscribed, through its browser's push service,
- * what the page's own notifications would: an agent that came to wait,
- * finished its turn or went quiet, in any project the server has open. The
- * page cannot tell it itself once a phone freezes it, soon after the app
- * leaves the front. The keys it signs with and the devices it pushes to are
- * kept in one file for every project on the machine, so a restart keeps them.
- */
-export declare class Pushes {
-    private readonly deps;
-    private readonly file;
-    private readonly keys;
-    private devices;
-    private readonly pusher;
-    /** By device and project, what the last look saw. */
-    private readonly notices;
-    private readonly tick;
-    private looking;
-    static start(deps: PushesDeps): Promise<Pushes>;
-    private constructor();
-    /** The public key a page subscribes with. */
-    readonly key: Handler;
-    /** Keeps a device's subscription and what it wants, replacing what it said before. */
-    readonly subscribe: Handler;
-    /** Forgets the device whose subscription `endpoint` names. */
-    readonly unsubscribe: Handler;
-    /**
-     * Compares every open project's rows with the last look, for each device,
-     * and pushes each notice it wants. A look still going when the next is due
-     * lets it pass.
-     */
-    look(): Promise<void>;
-    dispose(): void;
-    private lookOnce;
-    private push;
-    private forget;
-    private keep;
-}