@stringsync/splates 0.0.61 → 1.13.3

package/vendor/@stringsync/splates-server/replica/replica.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where a copy of a project's records goes: an object store kept by key, as
+ * a bucket keeps one, so any S3-compatible service or a folder can be one.
+ * Keys are `/`-separated paths, as storage keys are. What the records are,
+ * and how they map onto keys, is the `Replicator`'s; a replica only keeps
+ * bytes.
+ */
+export interface Replica {
+    /** Where it is, for a person to read, as `s3://records/splates`. */
+    readonly name: string;
+    /** Keeps `bytes` at `key`, replacing what was there. */
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    /** What is kept at `key`, or null when nothing is. */
+    get(key: string): Promise<Uint8Array | null>;
+    /**
+     * Everything kept under `key`, nested keys included, sorted by key; the
+     * whole replica under `""`.
+     */
+    list(key: string): Promise<ReplicaObject[]>;
+    /** Removes what is at `key`; nothing there is no error. */
+    delete(key: string): Promise<void>;
+}
+/** One thing a replica keeps, as its listing tells of it. */
+export interface ReplicaObject {
+    key: string;
+    size: number;
+    /** The MD5 of its bytes, as hex: what an S3 listing gives as its ETag. */
+    md5: string;
+}
+/** The MD5 of `bytes` as hex, as a replica lists it. */
+export declare function md5(bytes: Uint8Array): string;
+/** Orders objects by key, as a listing gives them. */
+export declare function byKey(left: {
+    key: string;
+}, right: {
+    key: string;
+}): number;

package/vendor/@stringsync/splates-server/replica/replicator.d.ts

@@ -0,0 +1,102 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import type { Logger } from "../../../core/log/index.js";
+import { Duration, type Timer, type WallClock } from "../../../core/time/index.js";
+import type { Storage } from "../storage";
+import { type Replica } from "./replica";
+import type { ReplicaStatus } from "./status";
+export interface ReplicatorOptions {
+    /** The project's records, every key of which is copied but those `replicated` keeps back. */
+    storage: Storage;
+    replica: Replica;
+    timer: Timer;
+    clock: WallClock;
+    log: Logger;
+    /** This machine's name, for the manifest. */
+    host: string;
+    /** How long changes gather before they are shipped together. */
+    batch?: Duration;
+    /** The longest a failed batch waits before it is tried again. */
+    maxRetry?: Duration;
+}
+/**
+ * Keeps a replica a copy of a project's storage: it watches every key, so it
+ * hears a CLI process's writes as well as the server's, gathers the changes
+ * of a few seconds, and ships each changed key as it now stands, a value
+ * whole and a log's new lines as a chunk. On `start` it catches up with
+ * whatever changed while it was not running by comparing the replica's
+ * listing with the storage. It replicates only into a replica it began, or
+ * an empty one, so two servers never write over each other's records.
+ */
+export declare class Replicator implements Resource {
+    private readonly opts;
+    private readonly batch;
+    private readonly maxRetry;
+    /** Each value's MD5 as the replica holds it, by storage key. */
+    private values;
+    /** Each log's chunks as the replica holds them, oldest first, by storage key. */
+    private logs;
+    /** The keys changed since they were last shipped. */
+    private readonly pending;
+    private behindSince;
+    private caughtUpAt;
+    private error;
+    private origin;
+    private failures;
+    private watch;
+    private scheduled;
+    private flushing;
+    private stopped;
+    /** The status last recorded, as JSON. */
+    private recordedAs;
+    /** Whether this run has written the manifest yet. */
+    private claimed;
+    constructor(opts: ReplicatorOptions);
+    /**
+     * Takes the replica as this server's, or refuses one another server
+     * began, then ships everything that differs and watches for more. A
+     * replica it cannot reach is tried again later, as a failed batch is.
+     */
+    start(): Promise<void>;
+    status(): ReplicaStatus;
+    /** Where the replicator of `storage` last said its replica stood, or null when none has run. */
+    static recorded(storage: Storage): Promise<ReplicaStatus | null>;
+    /**
+     * Makes `storage` the server that began the replica whose origin is
+     * `origin`, as a restore does, so its replicator writes on into it
+     * rather than refusing it as another server's.
+     */
+    static adopt(storage: Storage, origin: string): Promise<void>;
+    /** Ships what has changed now, rather than when the batch is due; done once it is. */
+    flush(): Promise<void>;
+    /** Catches up first when it has yet to, then ships what is pending. */
+    private run;
+    dispose(): void;
+    private changed;
+    private schedule;
+    /**
+     * Reads the manifest and listing, settles whose replica it is, and marks
+     * every key on either side to be shipped, which ships only what differs.
+     * False when it cannot replicate yet.
+     */
+    private catchUp;
+    /** Ships each pending key, then the manifest, leaving any that failed to be tried again. */
+    private ship;
+    /** Makes the replica hold what `key` holds now, or nothing when it holds nothing. */
+    private shipKey;
+    /**
+     * Ships a log's lines since its last chunk as one more chunk, or, when
+     * it no longer begins with what was shipped, as a rotation leaves it,
+     * all of them again in place of the chunks there were.
+     */
+    private shipLines;
+    private dropChunks;
+    private manifest;
+    /** Writes the manifest, saying it caught up at `at` when given. */
+    private writeManifest;
+    /** The id this server's replicas are begun with, made the first time. */
+    private ownOrigin;
+    /** Records the status beside the origin when it changed since last recorded. */
+    private record;
+    /** Records why the batch failed and tries again later, waiting longer each time. */
+    private failed;
+}

package/vendor/@stringsync/splates-server/replica/restore.d.ts

@@ -0,0 +1,40 @@
+import type { Fs } from "../../../core/system/index.js";
+import type { Storage } from "../storage";
+import type { Replica } from "./replica";
+/** The project's records, as a restore needs them; a `ProjectHome` is one. */
+export interface RestoreTarget {
+    dir(): Promise<string>;
+    exists(): Promise<boolean>;
+    open(): Promise<Storage>;
+    dispose(): void;
+    /** Copies the files under `dir` in, stamping the database with `format`. */
+    import(dir: string, format: number): Promise<void>;
+    /** Leaves the database there is aside; returns where. */
+    moveAside(to: string): Promise<string>;
+    clearMoved(): Promise<void>;
+}
+/** What a restore brought. */
+export interface Restored {
+    /** How many values and logs it wrote. */
+    values: number;
+    logs: number;
+    /** The machine that last caught the replica up. */
+    host: string;
+    /** Where the records it replaced went, when it replaced some. */
+    replaced: string | null;
+}
+/**
+ * Rebuilds a project's records from `replica` into `target`: each value
+ * whole and each log its chunks joined in order, written as the files the
+ * records were once kept as and imported into a database made beside the
+ * live one and renamed into place, so a restore that fails leaves nothing
+ * half done. Records already there stop it unless `force`, which leaves
+ * them aside. The database then adopts the replica's origin, so a server
+ * started on it replicates on into the same replica.
+ */
+export declare function restoreFromReplica(replica: Replica, { target, fs, format, force, }: {
+    target: RestoreTarget;
+    fs: Fs;
+    format: number;
+    force: boolean;
+}): Promise<Restored>;

package/vendor/@stringsync/splates-server/replica/s3.d.ts

@@ -0,0 +1,45 @@
+import { type AwsCredentials } from "./aws-sign";
+import { type Replica, type ReplicaObject } from "./replica";
+/** Where an S3-compatible bucket is, as a `splates.config.ts` names it. */
+export interface S3Place {
+    /** The service's address, as `https://<region>.digitaloceanspaces.com`. */
+    endpoint: string;
+    bucket: string;
+    /** The region requests are signed for; `us-east-1` by default, which most stores take. */
+    region?: string;
+    /** The key everything is kept under in the bucket, so projects can share one; none by default. */
+    prefix?: string;
+}
+export interface S3ReplicaOptions extends S3Place {
+    /** The key and secret to sign with, read at each request so a cred saved later is taken. */
+    credentials: () => Promise<AwsCredentials>;
+    fetch?: typeof fetch;
+    /** When a request is signed as made. */
+    now?: () => Date;
+}
+/**
+ * A replica in a bucket of any store that speaks S3's API (DigitalOcean
+ * Spaces, Cloudflare R2, Backblaze B2, Tigris, MinIO), addressed by path,
+ * as `<endpoint>/<bucket>/<key>`, and signed with SigV4 over fetch.
+ */
+export declare class S3Replica implements Replica {
+    private readonly opts;
+    readonly name: string;
+    private readonly fetch;
+    private readonly now;
+    private readonly prefix;
+    constructor(opts: S3ReplicaOptions);
+    put(key: string, bytes: Uint8Array): Promise<void>;
+    get(key: string): Promise<Uint8Array | null>;
+    list(key: string): Promise<ReplicaObject[]>;
+    delete(key: string): Promise<void>;
+    /** The key in the bucket, under the prefix. */
+    private full;
+    private relative;
+    /** The object's address, each part of its key percent-encoded. */
+    private url;
+    /** The address of `key` in the bucket, or the bucket's for `""`. */
+    private at;
+    /** Sends a signed request, throwing on a status that is not a success or one of `allowed`. */
+    private send;
+}

package/vendor/@stringsync/splates-server/replica/shipped.d.ts

@@ -0,0 +1,2 @@
+/** Whether `key` is one a replica carries, on the way in and on the way out. */
+export declare function replicated(key: string): boolean;

package/vendor/@stringsync/splates-server/replica/status.d.ts

@@ -0,0 +1,18 @@
+/** Where a replica stands, for `splates replica` and the page. */
+export interface ReplicaStatus {
+    /** Where it is, as `s3://records/splates`. */
+    replica: string;
+    /** When it last held every change, epoch ms; null before it first has. */
+    caughtUpAt: number | null;
+    /** How many keys have changed since and wait to be shipped. */
+    pending: number;
+    /** When the oldest change not yet shipped was made, epoch ms; null when none waits. */
+    behindSince: number | null;
+    /** Why the last batch failed, or why it will not replicate; null when it is well. */
+    error: string | null;
+}
+/**
+ * `status` as `splates replica status` prints it, as of `now`; with none
+ * recorded, whether the project names a replica says what to do.
+ */
+export declare function statusLines(status: ReplicaStatus | null, named: boolean, now: number): string[];

package/vendor/@stringsync/splates-server/server/assets.d.ts

@@ -0,0 +1,35 @@
+/** The files the browser asks for, as the server hands them over. */
+export interface Assets {
+    /** The page, which asks for the rest. */
+    shell: string;
+    /** The React app, bundled for the browser. */
+    script: string;
+    /** The React app's source map, which DevTools asks for while open. */
+    scriptMap: string;
+    /** The stylesheet, with Tailwind already compiled. */
+    styles: string;
+    /**
+     * The chunks of the React app that load when a page first needs them, by
+     * the name the script asks for, each with its source map. They are most of
+     * the page's bytes, the maps most of theirs, so each loads only on its
+     * first ask: a process that serves no page never holds them.
+     */
+    chunks: {
+        names: readonly string[];
+        code(): Promise<Record<string, string>>;
+        maps(): Promise<Record<string, string>>;
+    };
+    /** The service worker, through which a phone shows notifications. */
+    worker: string;
+    /** The service worker's source map. */
+    workerMap: string;
+    /** The web app manifest, which makes the page installable as an app. */
+    manifest: string;
+    /** The app icon as PNG, at 192px and 512px square. */
+    icons: {
+        192: Uint8Array<ArrayBuffer>;
+        512: Uint8Array<ArrayBuffer>;
+    };
+}
+/** The page this package ships. Serve each field's contents as-is. */
+export declare const assets: Assets;

package/vendor/@stringsync/splates-server/server/automations.d.ts

@@ -0,0 +1,26 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import { type Conversations } from "../conversations";
+import { type Automation, AutomationRoutes } from "../hooks";
+import type { Journal } from "../records";
+import type { Project } from "./project";
+/**
+ * One project's automations as `splates server` runs them: each on a task
+ * event as the journal takes it, and each on a schedule as it comes due,
+ * with the routes the Automations page reads and changes them through.
+ */
+export declare class Automations implements Resource {
+    #private;
+    readonly routes: AutomationRoutes;
+    constructor(project: Project);
+    /** Every automation: the person's, and the shell hooks the project checks in run after them. */
+    readonly all: () => Promise<Automation[]>;
+    /** Starts running them, catching up on what came while the server was down. */
+    start(conversations: Conversations, journal: Journal): Promise<void>;
+    /**
+     * Wakes the groomer as its automation now stands: on, it grooms the
+     * backlog; paused, it puts its run away, keeping its row; off, it retires
+     * its conversation.
+     */
+    groomed(): Promise<void>;
+    dispose(): void;
+}

package/vendor/@stringsync/splates-server/server/chunk-files.d.ts

@@ -0,0 +1,4 @@
+export declare const chunkFiles: {
+    code: URL;
+    maps: URL;
+};

package/vendor/@stringsync/splates-server/server/conflict-watch.d.ts

@@ -0,0 +1,22 @@
+import { type AsyncResource } from "../../../core/disposable/index.js";
+import { type Conversations } from "../conversations";
+import type { Project } from "./project";
+/** Checks active tasks after ref moves, even with no page open. */
+export declare class ConflictWatch implements AsyncResource {
+    private readonly project;
+    private readonly conversations;
+    private readonly timer;
+    private readonly settled;
+    private readonly checks;
+    private readonly disposer;
+    private readonly overlaps;
+    private readonly told;
+    private running;
+    private disposed;
+    constructor(project: Project, conversations: Conversations | null);
+    start(): Promise<void>;
+    /** Checks active tasks now, notifying their working agents of new warnings. */
+    sweep(): Promise<void>;
+    private tell;
+    disposeAsync(): Promise<void>;
+}

package/vendor/@stringsync/splates-server/server/early-warning.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What `ConflictWatch` tells a task's working agent, the page drawing each as
+ * an event line rather than a message: `words` under a line naming the task.
+ */
+export declare function earlyWarning(task: string, words: string): string;
+/** The words of an early warning that the task's commits conflict with its base. */
+export declare function conflictWarning(base: string, files: readonly string[]): string;

package/vendor/@stringsync/splates-server/server/general.d.ts

@@ -0,0 +1,53 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import { ConversationRoutes, type Conversations } from "../conversations";
+import type { Snapshot } from "../tasks";
+import type { Handler, ProjectHeard, Served } from "./project";
+import type { Behind, Release } from "./release";
+/** What the server needs to construct General before its release feed exists. */
+export interface GeneralOptions {
+    conversations: Conversations;
+    root: string;
+    scratchRoot: string;
+}
+/** The release and slot metadata General's static snapshot shares with projects. */
+interface GeneralSettings {
+    release: () => Release | null;
+    behind: () => Behind | null;
+    unbuilt: boolean;
+    slot: Snapshot["slot"];
+    /** The registered project `slug` names, served, as a request's `?project=` reaches it. */
+    projectNamed: (slug: string) => Promise<Served>;
+}
+/** The shared conversation handlers exposed on a General, assigned from `talks`. */
+export interface General extends Omit<Pick<ConversationRoutes, keyof ConversationRoutes>, "listen"> {
+}
+/** The machine's projectless conversations, shown as one global destination. */
+export declare class General {
+    readonly conversations: Conversations;
+    readonly root: string;
+    readonly scratchRoot: string;
+    private readonly opts;
+    readonly talks: ConversationRoutes;
+    readonly startAutoPick: Handler;
+    readonly snapshot: Handler;
+    readonly events: Handler;
+    readonly continueConversation: Handler;
+    private readonly listeners;
+    constructor(conversations: Conversations, root: string, scratchRoot: string, opts: GeneralSettings);
+    /**
+     * Carries the General conversation the path names on in the project the
+     * body names, for work that changes its repository: a new conversation in
+     * that project's main tree, on the same agent and settings, told to read
+     * what was said here. The General one stays as it is.
+     */
+    private continueIn;
+    current(): Promise<Snapshot>;
+    waiting(): Promise<number>;
+    needing(): Promise<{
+        rows: import("../plans").Needing[];
+        lanes: never[];
+    }>;
+    listen(heard: ProjectHeard): Resource;
+    disposeAsync(): Promise<void>;
+}
+export {};

package/vendor/@stringsync/splates-server/server/groomer.d.ts

@@ -0,0 +1,53 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import type { Logger } from "../../../core/log/index.js";
+import type { Task } from "../board";
+import { type Conversations } from "../conversations";
+import { type AgentPick } from "../models";
+/**
+ * The project's groomer, one at a time: woken by a task added to the
+ * backlog, or as `splates server` starts, it works down the backlog in
+ * order, claiming each task before telling the run's conversation
+ * `[SPLATES GROOM #N]`, and waits for that turn to end before the next. The
+ * backlog as it stands decides what it grooms, never the event that woke
+ * it, so a wake missed or doubled changes nothing.
+ *
+ * Each run, from a wake to an empty backlog, starts a conversation of its
+ * own (unless one waits on you, below), so its agent starts from a fresh
+ * context, and archives it resting as
+ * the run ends, which stops its agent; the newest holds the groomer's row
+ * on the page until the next run. One that ends asking you something stays
+ * open until a turn after your reply ends with nothing more asked, and the
+ * next run works in it rather than open a second.
+ *
+ * A task someone takes meanwhile, or one already groomed, is left be, as
+ * the claim (`Task.groom`) refuses it; one a groomer had its turn on and
+ * left in the backlog keeps its claim, so no later run grooms it again.
+ *
+ * Once the backlog is empty, it tells the run `[SPLATES SORT #N ...]`
+ * for the Untriaged tasks not yet looked at, marking each (`Task.sort`) so
+ * none is looked at twice, for it to find them lanes: one at a time, a
+ * task shows no theme it shares with others.
+ */
+export declare class Groomer implements Resource {
+    #private;
+    private readonly deps;
+    constructor(deps: GroomerDeps);
+    dispose(): void;
+    /**
+     * Grooms the backlog as `pick`; `"paused"`, puts its run away resting
+     * once it is idle, so its row stays; null, as when the groomer is off,
+     * retires its conversation, row and all. Settles once the backlog holds
+     * nothing more to claim.
+     */
+    wake(pick: AgentPick | "paused" | null): Promise<void>;
+}
+/** What a `Groomer` works with. */
+export interface GroomerDeps {
+    /** Every task on the list, in its order, the top first. */
+    tasks: () => Promise<Task[]>;
+    /** The project's conversations, where its groomer is kept. */
+    conversations: Conversations;
+    /** The main tree, where the groomer runs, with no worktree of its own. */
+    root: string;
+    log: Logger;
+}

package/vendor/@stringsync/splates-server/server/held.d.ts

@@ -0,0 +1,10 @@
+import type { Logger } from "../../../core/log/index.js";
+import type { Conversations } from "../conversations";
+import type { HeldConversations } from "../queue";
+import type { WorktreeService } from "../tasks";
+/**
+ * Lists the conversations the queue holds for tasks not yet started, for
+ * the queue to start. Each waits in the main tree on the agent, model and
+ * thinking level its task names, titled for its task.
+ */
+export declare function heldFor(conversations: Conversations, service: WorktreeService, log: Logger): HeldConversations;

package/vendor/@stringsync/splates-server/server/http.d.ts

@@ -0,0 +1,76 @@
+import type { Resource } from "../../../core/disposable/index.js";
+import type { Logger } from "../../../core/log/index.js";
+import type { Attachment } from "../artifacts";
+import { type Reason } from "../exit";
+import type { Access, Identity } from "../tunnel";
+/**
+ * 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 queued tasks.
+ */
+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 queued or started task may hold, by extension, and how
+ * each is served; `web/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/vendor/@stringsync/splates-server/server/index.d.ts

@@ -0,0 +1,16 @@
+export { assets } from "./assets";
+export { DEFAULT_PORT } from "./ports";
+export { BESIDE_GATE_NICE, CHECKED_COMMIT, GATE_DEADLINE, GATE_PHASES, PREMERGE_HELD, PREMERGE_HOLD_MS, PREMERGE_TIMEOUT_MS, premergeLockOfProject, projectRootOf, RECENT_FAILED_FILES, } from "./premerge";
+export type { Behind, Release } from "./release";
+export { newest, RUNNING } from "./release";
+export type { SplatesDeps } from "./runtime-deps";
+export type { DevServer } from "./server";
+export { dev } from "./server";
+export type { ServerChoice } from "./servers";
+export { serveDev } from "./start";
+export { rosterOf, savedTunnelOf, seeded } from "./start-settings";
+export { SUITE_GRANT_MS, SuiteGrants } from "./suite-grant";
+export { SERVING } from "./supervise";
+export type { PlacedAcquireOptions, PlacedLock } from "./ticketed-lock";
+export { refreshHere, update } from "./update";
+export { recordsFirst } from "./update-records";