@stringsync/splates 0.0.61 → 1.13.3

package/vendor/@stringsync/splates-server/terminal/shell.d.ts

@@ -0,0 +1,70 @@
+import type { AsyncResource } from "../../../core/disposable/index.js";
+import type { ProcessEntry } from "../../../core/system/index.js";
+import { Duration, type Timer } from "../../../core/time/index.js";
+import type { ProcessHandle } from "../agents";
+import type { Connection } from "../server/shared";
+import type { RemotePtyOptions } from "../workers";
+import type { RemotePty } from "./remote-pty";
+/** Bigger than any screen, and small enough that a typo cannot hurt. */
+export declare const MAX_SIZE = 1000;
+/**
+ * How long a keyed shell stays once its page's socket goes, for the page to
+ * come back to it: through a reload, or a restart of `splates server`.
+ */
+export declare const TERMINAL_GRACE: Duration;
+/** The shells a terminal opens, as a worker runs them. */
+export type TerminalShell = RemotePty;
+/** What a terminal needs of the worker it runs on. */
+export interface ShellHost {
+    pty(options: RemotePtyOptions): TerminalShell;
+    /** Takes back a shell the worker kept through a restart; see `ConnectedWorker.resumePty`. */
+    resumePty(handle: ProcessHandle): TerminalShell;
+    processes(): Promise<ProcessEntry[]>;
+}
+/** A shell handed to the next run of `splates server`, as `coordinator.json` keeps it. */
+export interface KeptShell {
+    key: string;
+    handle: ProcessHandle;
+}
+/**
+ * One shell the server runs for a page's terminal, by its key: the page's
+ * socket shows it, and may go and come back, through a reload or a restart
+ * of `splates server`, the worker redrawing the screen for the one that comes
+ * back. One with no key ends with its socket; one with a key stays
+ * `TERMINAL_GRACE` after it, or until the page says it is closing it.
+ */
+export declare class Shell implements AsyncResource {
+    readonly key: string | null;
+    readonly pty: TerminalShell;
+    /** The worker the shell runs on, where its job in front is read from. */
+    private readonly worker;
+    private readonly timer;
+    /** Hears that the shell is gone: exited, closed, or let go. */
+    private readonly gone;
+    private socket;
+    private grace;
+    private ended;
+    constructor(key: string | null, pty: TerminalShell, 
+    /** The worker the shell runs on, where its job in front is read from. */
+    worker: ShellHost, timer: Timer, 
+    /** Hears that the shell is gone: exited, closed, or let go. */
+    gone: (shell: Shell) => void);
+    /** What the next run takes the shell back by, once it has a key. */
+    get kept(): KeptShell | null;
+    /**
+     * Shows the shell on `socket`, in place of any before it: one come back
+     * to a shell has the worker redraw its screen first.
+     */
+    attach(socket: Bun.ServerWebSocket<Connection>, back: boolean): void;
+    /** Keeps the shell `TERMINAL_GRACE` for a page to come back to it. */
+    wait(): void;
+    /** The page's `socket` went: keyed, the shell waits for it to come back. */
+    detach(socket: Bun.ServerWebSocket<Connection>): void;
+    message(socket: Bun.ServerWebSocket<Connection>, message: string | Buffer<ArrayBuffer>): void;
+    /** Tells the page what the shell runs in front, or null at its prompt. */
+    private front;
+    /** Lets go of the shell for the next run to take back, without ending it. */
+    release(): void;
+    /** Hangs up, as closing a terminal window does. */
+    disposeAsync(): Promise<void>;
+}

package/vendor/@stringsync/splates-server/terminal/spawn.d.ts

@@ -0,0 +1,22 @@
+import { type Ps, type SpawnCaptureResult, type SpawnOptions, type SpawnResult } from "../../../core/system/index.js";
+/** What a `Shell` spawns through; the real process by default. */
+export interface ShellOptions {
+    ps?: Ps;
+}
+/** How a command runs, beyond what a spawn takes. */
+export interface ShellRunOptions extends SpawnOptions {
+    /** Runs it under `nice -n <nice>`, as a hook beside a merge gate does. */
+    nice?: number;
+}
+/**
+ * Runs the commands a repo configures (the lifecycle hooks) as shell strings
+ * rather than argv, since that is how a repo writes them.
+ */
+export declare class Shell {
+    private readonly ps;
+    constructor(opts?: ShellOptions);
+    /** Captures output, for commands whose failure has to be reported back. */
+    run(command: string, cwd: string, { nice, ...opts }?: ShellRunOptions): Promise<SpawnCaptureResult>;
+    /** Inherits stdio, for commands the agent should watch as they run. */
+    stream(command: string, cwd: string, { nice, ...opts }?: ShellRunOptions): Promise<SpawnResult>;
+}

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

@@ -0,0 +1,52 @@
+import { type Timer } from "../../../core/time/index.js";
+import type { Connection, Served } from "../server/shared";
+import { type HostGate } from "../server/shared";
+import { type KeptShell, type ShellHost } from "./shell";
+/** How a terminal finds the project its request names. */
+export interface TerminalProjects {
+    projectFor(request: Request): Promise<Served>;
+    /**
+     * The root of the project `request` names, read without opening it: where
+     * a shell starts in one whose records failed to migrate.
+     */
+    unopened?(request: Request): Promise<string>;
+}
+/**
+ * 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>;
+    /**
+     * Where a new shell for `request` starts: the tree it names in its
+     * project, or the project's root when its records failed to migrate, so
+     * an agent can be started there to fix them.
+     */
+    private treeFor;
+    disposeAsync(): Promise<void>;
+}

package/vendor/@stringsync/splates-server/tunnel/access.d.ts

@@ -0,0 +1,61 @@
+import { type WallClock } from "../../../core/time/index.js";
+/** Who a verified token says is asking. */
+export interface Identity {
+    email: string | null;
+    sub: string;
+}
+/** A request's token, verified or refused with why. */
+export type Verified = {
+    identity: Identity;
+    refused?: undefined;
+} | {
+    identity?: undefined;
+    refused: string;
+};
+/** The header Access sets on each request it lets through to the origin. */
+export declare const ACCESS_HEADER = "cf-access-jwt-assertion";
+/** The cookie a browser carries it in, which an upgrade may have alone. */
+export declare const ACCESS_COOKIE = "CF_Authorization";
+/**
+ * Checks the token Cloudflare Access hands each request against the team's
+ * signing keys, so a request that merely claims to come through Access, as
+ * any process on this machine could, gets nowhere.
+ */
+export declare class Access {
+    readonly config: AccessConfig;
+    private keys;
+    private fetching;
+    private fetchedAt;
+    private readonly fetch;
+    private readonly clock;
+    constructor(config: AccessConfig, opts?: AccessOptions);
+    /** Where the team publishes the keys its tokens are signed with. */
+    get certs(): string;
+    /** Who `request` comes from, by the token in its header or its cookie. */
+    verify(request: Request): Promise<Verified>;
+    private check;
+    private key;
+    private refetch;
+}
+/**
+ * The Cloudflare Access application in front of `splates server`: the team it
+ * belongs to, as the issuer its tokens name, and its AUD tag. The one place
+ * both live, so whatever exposes the page beyond this machine can ask whether
+ * Access stands in front of it.
+ */
+export interface AccessConfig {
+    /** The team's own origin, `https://<team>.cloudflareaccess.com`. */
+    issuer: string;
+    /** The application's AUD tag, which each of its tokens names. */
+    aud: string;
+}
+/**
+ * The Access application `--access-team` and `--access-aud` name, or null
+ * when neither is given. The team is its name, its domain or its URL alike.
+ */
+export declare function accessConfig(team: string, aud: string): AccessConfig | null;
+/** What an `Access` reaches the world through, swapped in tests. */
+export interface AccessOptions {
+    fetch?: typeof fetch;
+    clock?: WallClock;
+}

package/vendor/@stringsync/splates-server/tunnel/cloudflare-api.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** Where Cloudflare's v4 API answers. */
+export declare const CLOUDFLARE_API = "https://api.cloudflare.com/client/v4";
+/**
+ * The few calls `splates tunnel setup` makes of Cloudflare's v4 API, over plain
+ * `fetch` rather than the `cloudflare` SDK, which every `bunx` of splates would
+ * download for some ten endpoints. Each answer's result is checked against
+ * the shape the caller names, so a field that moved fails here, saying where.
+ */
+export declare class CloudflareApi {
+    private readonly token;
+    private readonly fetch;
+    constructor(token: string, opts?: {
+        fetch?: typeof fetch;
+    });
+    get<T>(path: string, shape: z.ZodType<T>): Promise<T>;
+    /** Every item of the list at `path`, page after page. */
+    list<T>(path: string, item: z.ZodType<T>): Promise<T[]>;
+    post<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    put<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    patch<T>(path: string, body: unknown, shape: z.ZodType<T>): Promise<T>;
+    /** Deletes what is at `path`, whatever Cloudflare answers with. */
+    delete(path: string): Promise<void>;
+    private call;
+}

package/vendor/@stringsync/splates-server/tunnel/cloudflare-error.d.ts

@@ -0,0 +1,5 @@
+/** A call Cloudflare refused, with the HTTP status it answered. */
+export declare class CloudflareError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/vendor/@stringsync/splates-server/tunnel/cloudflared.d.ts

@@ -0,0 +1,43 @@
+import type { AsyncResource } from "../../../core/disposable/index.js";
+import type { Ps } from "../../../core/system/index.js";
+import type { TunnelProvider, TunnelRoute } from "./provider";
+/**
+ * An `sh -c` script that runs the command after it, `sh -c GUARD sh <argv>`,
+ * until the guard's stdin closes or a SIGTERM reaches it, and exits with the
+ * command's status. Start it with stdin a pipe, so it dies with its parent.
+ */
+export declare const GUARD: string;
+/**
+ * A TunnelProvider over the `cloudflared` binary, running the named tunnel
+ * the account already has, or the one its own config names, or, given a
+ * token, the tunnel `splates tunnel setup` made, with no login or credentials
+ * file. One that dies while running is logged and restarted with
+ * backoff; after repeated fast failures the server exits, so its supervisor
+ * restarts the whole unit. Until then the page still answers on this machine.
+ */
+export declare class CloudflaredTunnelProvider implements TunnelProvider {
+    private readonly ps;
+    private readonly name;
+    /** The tunnel's token, handed over in the environment, never the argv `ps` lists. */
+    private readonly token;
+    private readonly opts;
+    constructor(ps: Ps, name?: string | null, 
+    /** The tunnel's token, handed over in the environment, never the argv `ps` lists. */
+    token?: string | null, opts?: CloudflaredOptions);
+    ready(): Promise<void>;
+    run({ host, url, log }: TunnelRoute): AsyncResource;
+    /**
+     * Reads `child`'s stderr until it exits, saying once where the page is up,
+     * and returns its exit code with the tail of what it printed, or null
+     * when it never started.
+     */
+    private watch;
+}
+/** Waits out a restart's backoff. */
+export interface Waiter {
+    wait(ms: number): Promise<void>;
+}
+export interface CloudflaredOptions {
+    /** Tests pass one that returns at once. */
+    waiter?: Waiter;
+}

package/vendor/@stringsync/splates-server/tunnel/index.d.ts

@@ -0,0 +1,14 @@
+export type { AccessConfig, Identity } from "./access";
+export { ACCESS_COOKIE, ACCESS_HEADER, Access, accessConfig } from "./access";
+export { CloudflareApi } from "./cloudflare-api";
+export { CloudflareError } from "./cloudflare-error";
+export { GUARD } from "./cloudflared";
+export { asideOf, machineTunnel } from "./machine";
+export type { TunnelProvider, TunnelRoute } from "./provider";
+export { releaseHost, tunnelRemove } from "./remove";
+export type { TunnelRecord } from "./saved";
+export { API_TOKEN, SavedTunnel, TUNNEL_TOKEN } from "./saved";
+export { portsHostFlag, SavedPortsHost } from "./saved-ports-host";
+export { App, CloudflareTunnels, Include, Policy, SESSION, SLOTS_APP, TOKEN_PERMISSIONS, TOKENS_PAGE, tokenInstructions, tunnelSetup, workersPolicy, } from "./setup";
+export type { TunnelConfig } from "./tunnel";
+export { savedTunnelConfig, startTunnel, tunnelConfig } from "./tunnel";

package/vendor/@stringsync/splates-server/tunnel/index.js

@@ -0,0 +1,70 @@
+import {
+  ACCESS_HEADER2,
+  ACCESS_COOKIE2,
+  Access2,
+  accessConfig2,
+  CloudflareError2,
+  CloudflareApi2,
+  GUARD2,
+  TUNNEL_TOKEN2,
+  API_TOKEN2,
+  SavedTunnel2,
+  asideOf2,
+  machineTunnel2,
+  tunnelConfig2,
+  savedTunnelConfig2,
+  startTunnel2,
+  tunnelSetup2,
+  TOKEN_PERMISSIONS2,
+  TOKENS_PAGE2,
+  tokenInstructions2,
+  SESSION2,
+  SLOTS_APP2,
+  workersPolicy2,
+  Include2,
+  Policy2,
+  App2,
+  CloudflareTunnels2,
+  tunnelRemove2,
+  releaseHost2,
+  SavedPortsHost2,
+  portsHostFlag2
+} from "../index-caep3sde.js";
+import"../index-01z7ycdk.js";
+import"../index-e9z7s5hh.js";
+import"../index-kmzdvvt0.js";
+import"../index-t9w5a8ed.js";
+import"../index-0jttnv86.js";
+import"../index-g18nxyn7.js";
+export {
+  ACCESS_COOKIE2 as ACCESS_COOKIE,
+  ACCESS_HEADER2 as ACCESS_HEADER,
+  API_TOKEN2 as API_TOKEN,
+  Access2 as Access,
+  App2 as App,
+  CloudflareApi2 as CloudflareApi,
+  CloudflareError2 as CloudflareError,
+  CloudflareTunnels2 as CloudflareTunnels,
+  GUARD2 as GUARD,
+  Include2 as Include,
+  Policy2 as Policy,
+  SESSION2 as SESSION,
+  SLOTS_APP2 as SLOTS_APP,
+  SavedPortsHost2 as SavedPortsHost,
+  SavedTunnel2 as SavedTunnel,
+  TOKENS_PAGE2 as TOKENS_PAGE,
+  TOKEN_PERMISSIONS2 as TOKEN_PERMISSIONS,
+  TUNNEL_TOKEN2 as TUNNEL_TOKEN,
+  accessConfig2 as accessConfig,
+  asideOf2 as asideOf,
+  machineTunnel2 as machineTunnel,
+  portsHostFlag2 as portsHostFlag,
+  releaseHost2 as releaseHost,
+  savedTunnelConfig2 as savedTunnelConfig,
+  startTunnel2 as startTunnel,
+  tokenInstructions2 as tokenInstructions,
+  tunnelConfig2 as tunnelConfig,
+  tunnelRemove2 as tunnelRemove,
+  tunnelSetup2 as tunnelSetup,
+  workersPolicy2 as workersPolicy
+};

package/vendor/@stringsync/splates-server/tunnel/machine.d.ts

@@ -0,0 +1,18 @@
+import type { SecretStore } from "../../../core/creds/index.js";
+import type { Fs } from "../../../core/system/index.js";
+import { type Storage } from "../storage";
+import { type TunnelRecord } from "./saved";
+/** Where a move at `stamp` puts this machine's server records aside, kept. */
+export declare function asideOf(home: string, stamp: string): string;
+/**
+ * The machine's tunnel, as `splates tunnel setup` saved it: in `home`, or,
+ * once the server moved onto its box and took the tunnel with it, as
+ * the last move put it aside, still naming the zone and Access team the
+ * box serves under. Null when neither holds one.
+ */
+export declare function machineTunnel({ fs, home, store, storage, }: {
+    fs: Fs;
+    home: string;
+    store: SecretStore;
+    storage?: Storage;
+}): Promise<TunnelRecord | null>;

package/vendor/@stringsync/splates-server/tunnel/provider.d.ts

@@ -0,0 +1,37 @@
+import type { AsyncResource } from "../../../core/disposable/index.js";
+import type { Logger } from "../../../core/log/index.js";
+/** What a provider is asked to publish. */
+export interface TunnelRoute {
+    /** The public host name that must reach `url`. */
+    host: string;
+    /** The page on this machine, `http://localhost:<port>`. */
+    url: string;
+    /** Where the provider says what it is doing, such as where it is reachable. */
+    log: Logger;
+}
+/**
+ * TunnelProvider is the seam onto whatever puts the `splates server` page on a
+ * public host name: `cloudflared` by default, or any tunnel a repo's
+ * `splates.config.ts` names as `tunnel`:
+ *
+ * ```ts
+ * export default { tunnel: new MyTunnel() } satisfies ConfigFile;
+ * ```
+ *
+ * Whatever it is, `--tunnel` still refuses to run without Cloudflare Access in
+ * front, which is what decides who may enter; a provider only carries traffic.
+ */
+export interface TunnelProvider {
+    /**
+     * Throws unless whatever runs the tunnel is installed and signed in, with a
+     * message saying what to do about it. Asked before `run`, which is skipped
+     * when it throws: the page keeps serving on this machine.
+     */
+    ready(): Promise<void>;
+    /**
+     * Starts carrying `route.host` to `route.url`, and answers with the run,
+     * which serves until it is disposed of. Disposing stops the tunnel and
+     * returns once it is gone; disposing one that stopped on its own is silent.
+     */
+    run(route: TunnelRoute): AsyncResource;
+}

package/vendor/@stringsync/splates-server/tunnel/remove.d.ts

@@ -0,0 +1,35 @@
+import { type Logger } from "../../../core/log/index.js";
+import type { Fs } from "../../../core/system/index.js";
+import type { Creds } from "../creds";
+import { type SavedTunnel, type TunnelRecord } from "./saved";
+import { CloudflareTunnels } from "./setup";
+/** What `splates tunnel remove` is asked to remove, and what it runs with. */
+export interface RemoveOptions {
+    /** The tunnel `splates tunnel setup` saved for this machine. */
+    saved: SavedTunnel;
+    /** Each slot home's tunnel, in the pool's order, whether or not it has one. */
+    slots: SavedTunnel[];
+    /** Where the API token is read from, and the tunnels' tokens forgotten. */
+    creds: Creds;
+    /** The task asking, for the request to name; null outside any. */
+    task: string | null;
+    fs: Fs;
+    log: Logger;
+    fetch?: typeof fetch;
+}
+/**
+ * Deletes what `splates tunnel setup` and `splates server --slot` made, by what they
+ * saved: each tunnel and the DNS record routing to it, the Access application
+ * in front of the machine's host and the one in front of every slot, and the
+ * policy they share, and the workers' policy with the service tokens it lets in. Then forgets each saved file and the machine's tunnel
+ * token. What is already gone is passed over, and a file is forgotten only
+ * once its tunnel is, so running it again after a failure finishes the job.
+ * The Cloudflare API token is kept, for `splates tunnel setup` to use again.
+ */
+export declare function tunnelRemove(opts: RemoveOptions): Promise<void>;
+/**
+ * Frees `record.host` for another tunnel: deletes the record routing it to
+ * `record`'s tunnel and the Access applications in front of it with their
+ * policies, leaving the tunnel itself, which nothing then reaches.
+ */
+export declare function releaseHost(cloudflare: CloudflareTunnels, record: TunnelRecord, log: Logger): Promise<void>;

package/vendor/@stringsync/splates-server/tunnel/saved-ports-host.d.ts

@@ -0,0 +1,26 @@
+import type { Document, Storage } from "../storage";
+/** What `--ports-host` takes to forget the saved base host. */
+export declare const NO_PORTS_HOST = "none";
+/**
+ * The wildcard base host this machine serves task ports under, as
+ * `<task>-<port>.<base>`: saved by `splates server --ports-host`, per machine as
+ * the tunnel is, in `~/.splates/ports.json`, so a bare `splates server` serves it.
+ */
+export declare class SavedPortsHost {
+    /** `~/.splates/ports.json`, or a test's own. */
+    private readonly file;
+    constructor(
+    /** `~/.splates/ports.json`, or a test's own. */
+    file: Document<unknown>);
+    /** The ports host saved in `storage`. */
+    static in(storage: Storage): SavedPortsHost;
+    /** The saved base, or null when none is, or its format is newer. */
+    read(): Promise<string | null>;
+    /** Keeps `base`, over what was there, or forgets it for null. */
+    save(base: string | null): Promise<void>;
+}
+/**
+ * What `--ports-host` asks for: a base host to save, null to forget the
+ * saved one, or undefined to serve whatever was saved.
+ */
+export declare function portsHostFlag(flag: string): string | null | undefined;

package/vendor/@stringsync/splates-server/tunnel/saved.d.ts

@@ -0,0 +1,63 @@
+import type { SecretStore } from "../../../core/creds/index.js";
+import type { Document, Storage } from "../storage";
+/** The file's own format, which a box's record from its stack is written in too. */
+export declare const FORMAT = 1;
+/** The name the tunnel's token is kept under in the system's secret store. */
+export declare const TUNNEL_TOKEN = "SPLATES_TUNNEL_TOKEN";
+/**
+ * The cred the Cloudflare API token is kept as, on the device, since the
+ * account is the person's. Not `CLOUDFLARE_API_TOKEN`, which scry's Workers
+ * AI token goes by in the same store.
+ */
+export declare const API_TOKEN = "SPLATES_CLOUDFLARE_API_TOKEN";
+/** What `splates tunnel setup` made, which a bare `splates server` runs. */
+export interface TunnelRecord {
+    /** The public host name the tunnel carries to the page. */
+    host: string;
+    /** The Zero Trust team, as in `<team>.cloudflareaccess.com`. */
+    team: string;
+    /** The AUD tag of the Access application in front of `host`. */
+    aud: string;
+    /** The Cloudflare tunnel's id. */
+    tunnel: string;
+    /**
+     * The account a slot's tunnel is in, whose token is asked of the API at
+     * each start rather than kept, so slots leave no creds behind. The
+     * machine's tunnel has none: its token is kept as `TUNNEL_TOKEN`.
+     */
+    account?: string;
+}
+/**
+ * The tunnel this machine set up, kept per machine rather than per project,
+ * since one `splates server` serves every project: what it is in
+ * `~/.splates/tunnel.json`, and the token that runs it, a secret of this
+ * machine, in the device's secret store, as the cred `TUNNEL_TOKEN`.
+ */
+export declare class SavedTunnel {
+    /** `~/.splates/tunnel.json`, or a test's own. */
+    private readonly file;
+    private readonly deps;
+    constructor(
+    /** `~/.splates/tunnel.json`, or a test's own. */
+    file: Document<unknown>, deps: {
+        /** The device's store, which `splates tunnel setup` saves the token in. */
+        store: SecretStore;
+        /** How a slot's token is asked of the Cloudflare API. */
+        fetch?: typeof fetch;
+    });
+    /** The tunnel saved in `storage`, a machine's or a slot's. */
+    static in(storage: Storage, store: SecretStore, fetch?: typeof globalThis.fetch): SavedTunnel;
+    /** Where it is kept, as a key of the storage it is in. */
+    get key(): string;
+    /** Forgets what was saved; its token is a cred, left to the caller. */
+    forget(): Promise<void>;
+    /** What was saved, or null when nothing was, or its format is newer. */
+    read(): Promise<TunnelRecord | null>;
+    /**
+     * The token that runs the saved tunnel, or undefined when the store lost
+     * it: a slot's asked of the API with the token kept as `API_TOKEN`.
+     */
+    token(): Promise<string | undefined>;
+    /** Keeps `record` in the file, over what was there; its token is a cred. */
+    save(record: TunnelRecord): Promise<void>;
+}