@chipschat/harness 0.0.0-stage → 1.0.0

package/dist/join.js

@@ -0,0 +1,289 @@
+/**
+ * Join a Chips (ADR 0122): find the server, ask to join, and come back with the four things
+ * `connect()` and a harness need — its address, the harness's id, its key and its room — with no
+ * token copied by hand.
+ *
+ * ```ts
+ * const me = await join({ link, name: "Tide" });
+ * const chips = await connect(me);
+ * ```
+ *
+ * Two ways in. With a link a person made in Chips (`<address>/j/<secret>`), it is allowed already
+ * and is taken up at once. With only an address, it asks: the server answers with a code, which
+ * `onCode` shows, and a person compares it and allows it; `join()` asks every few seconds until
+ * they do. Either way what it is handed is kept — in the keychain, the Secret Service, or a file
+ * only its user can read — and the next `join()` of the same name at the same server returns it
+ * without asking again. A link it wasn't handed that key by is taken up all the same, and its key
+ * kept in place of the old one: a person makes a new link when the old key is no good (the
+ * harness removed, Chips started afresh). A link already used or lapsed gives the kept key back,
+ * so a command run again as it was first written still starts.
+ *
+ * The server is found from the link, then `url`, then `CHIPS_URL`, then the `server.json` that
+ * `chips up` writes on its own machine.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join as joinPath } from "node:path";
+import { HARNESS_CAPABILITIES, JOIN_POLL_SECONDS, parseJoinLink, } from "@chipschat/protocol";
+import { configHome, openKeyStore } from "./keep.js";
+import { reportStep } from "./steps.js";
+/** Why it did not join, with the rule that refused it: `spent`, `expired`, `denied`, `too_many`… */
+export class JoinError extends Error {
+    refusal;
+    name = "JoinError";
+    constructor(refusal, message) {
+        super(message);
+        this.refusal = refusal;
+    }
+}
+/** Where `chips up` says the server on this machine is. */
+function serverJsonUrl(env) {
+    try {
+        const said = JSON.parse(readFileSync(joinPath(configHome(env), "server.json"), "utf8"));
+        return typeof said.url === "string" && said.url !== "" ? said.url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The server, and the link's secret when there is one. */
+export function findServer(options, env) {
+    if (options.link !== undefined) {
+        const parsed = parseJoinLink(options.link);
+        if (parsed === undefined) {
+            throw new JoinError("invalid", "That is not a join link: it looks like <address>/j/<secret>.");
+        }
+        return parsed;
+    }
+    const url = options.url ?? env["CHIPS_URL"] ?? serverJsonUrl(env);
+    if (url === undefined || url === "") {
+        throw new JoinError("nowhere", "Where is Chips? Pass a link or url, set CHIPS_URL, or run chips up on this machine.");
+    }
+    return { url: url.replace(/\/$/, "") };
+}
+/** The account a key is kept under: the harness's name, at its server. */
+export function accountOf(url, name) {
+    return `harness:${name}@${url.replace(/\/$/, "")}`;
+}
+function joinedOf(answer) {
+    return {
+        url: answer.url,
+        harnessId: answer.harness_id,
+        token: answer.token,
+        ...(answer.space_id === undefined ? {} : { spaceId: answer.space_id }),
+        capabilities: answer.capabilities,
+    };
+}
+/** A link's secret as it is kept beside the key: hashed, since a key store is no place for it. */
+function linkHash(secret) {
+    return createHash("sha256").update(secret).digest("base64url");
+}
+function keptAt(store, account) {
+    if (store === false)
+        return undefined;
+    try {
+        const kept = store.get(account);
+        if (kept === undefined)
+            return undefined;
+        const { from, hello, ...parsed } = JSON.parse(kept);
+        if (typeof parsed.token !== "string" || typeof parsed.harnessId !== "string")
+            return undefined;
+        if (typeof parsed.url !== "string")
+            return undefined;
+        return {
+            joined: { capabilities: [], ...parsed },
+            from: typeof from === "string" ? from : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The key `join()` takes up for a harness of this name when it has no link, at the server it would
+ * find (`url`, `CHIPS_URL`, then `server.json`): what `chips connect <id>` with no link joins with,
+ * so the harness keeps its rooms (ADR 0218's addendum of 24 October 2026). The server's address
+ * comes back as well where one is found, kept key or not.
+ */
+export function keptJoin(name, options = {}) {
+    // biome-ignore lint/style/noProcessEnv: as `join()`.
+    const env = options.env ?? process.env;
+    let url;
+    try {
+        url = findServer(options.url === undefined ? {} : { url: options.url }, env).url;
+    }
+    catch {
+        return {};
+    }
+    const kept = keptAt(options.keep ?? openKeyStore(env), accountOf(url, name));
+    return kept === undefined ? { url } : { url, joined: kept.joined };
+}
+/** The refusals that mean a link was already taken up or has lapsed: the kept key still stands. */
+const USED_UP = new Set(["spent", "expired"]);
+/** A refusal off the wire, as a `JoinError`. */
+async function refused(response) {
+    const body = (await response.json().catch(() => ({})));
+    return new JoinError(body.error?.refusal ?? body.error?.code ?? `http_${response.status}`, body.error?.message ?? `Chips answered ${response.status}.`);
+}
+const wait = (ms, signal) => new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new JoinError("stopped", "Stopped before a person decided."));
+    }, { once: true });
+});
+/** Ask with a code, and wait for a person. */
+async function ask(url, options, send, machine) {
+    const asked = await send(`${url}/v1/join`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            kind: "harness",
+            name: options.name,
+            machine,
+            ...(options.software === undefined ? {} : { software: options.software }),
+            wants: [...(options.wants ?? [HARNESS_CAPABILITIES.autonomy])],
+        }),
+    });
+    if (asked.status !== 201)
+        throw await refused(asked);
+    const { request_id, secret, code, interval } = (await asked.json());
+    const show = options.onCode ??
+        ((shown, where) => process.stderr.write(`Allow ${options.name} in Chips at ${where}. Its code is ${shown}.\n`));
+    show(code, url);
+    for (;;) {
+        await wait((interval ?? JOIN_POLL_SECONDS) * 1000, options.signal);
+        const polled = await send(`${url}/v1/join/${request_id}/redeem`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ secret }),
+        });
+        if (polled.status === 202)
+            continue;
+        if (polled.status === 200)
+            return (await polled.json());
+        throw await refused(polled);
+    }
+}
+/** Take up a link: allowed already, so the answer is the harness's at once. */
+async function redeem(url, secret, options, send, machine) {
+    const answered = await send(`${url}/v1/join/redeem`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            secret,
+            name: options.name,
+            machine,
+            ...(options.software === undefined ? {} : { software: options.software }),
+        }),
+    });
+    if (answered.status !== 200)
+        throw await refused(answered);
+    return (await answered.json());
+}
+/**
+ * A request that never reached Chips, said in one line rather than a stack (the new-person
+ * sweep's finding 3): a link made on Chips's own address, opened on a computer that can't reach
+ * that address, which no answer from the server would ever explain. A cancel is still a cancel.
+ */
+function reaching(send, url) {
+    return async (input, init) => {
+        try {
+            return await send(input, init);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError")
+                throw error;
+            throw new JoinError("unreachable", `Can't reach Chips at ${url} from this computer. It has to be on the same network as Chips, on its tailnet, or Chips has to be at an address this computer can reach.`);
+        }
+    };
+}
+/** Take up the link, or ask with a code when there is none. */
+function askOrRedeem(server, options) {
+    const send = reaching(options.fetch ?? fetch, server.url);
+    const machine = options.machine ?? hostname();
+    return server.secret === undefined
+        ? ask(server.url, options, send, machine)
+        : redeem(server.url, server.secret, options, send, machine);
+}
+const usedUp = (error) => error instanceof JoinError && USED_UP.has(error.refusal);
+export async function join(options) {
+    // biome-ignore lint/style/noProcessEnv: the environment is where a harness is told where Chips is.
+    const env = options.env ?? process.env;
+    reportStep("joining", {}, env);
+    const server = findServer(options, env);
+    const store = options.keep ?? openKeyStore(env);
+    const account = accountOf(server.url, options.name);
+    const kept = keptAt(store, account);
+    const from = server.secret === undefined ? undefined : linkHash(server.secret);
+    // No link, or the very link it was handed this key by: the key, and nothing asked.
+    if (kept !== undefined && (from === undefined || kept.from === from))
+        return kept.joined;
+    let answer;
+    try {
+        answer = await askOrRedeem(server, options);
+    }
+    catch (error) {
+        if (kept !== undefined && usedUp(error))
+            return kept.joined;
+        throw error;
+    }
+    const joined = joinedOf(answer);
+    // Handed over now, so its first words are due (`helloOnce`).
+    if (store !== false)
+        store.set(account, JSON.stringify({ ...joined, from, hello: "due" }));
+    return joined;
+}
+/**
+ * Say a harness's first words in the room it joined, once: the card that followed its link waits
+ * for them ("Said hello", ADR 0122), and a harness that only answers would leave it waiting. They
+ * are due when `join()` is handed a key, and noted as said beside it, so a restart says nothing
+ * again, a new link (a new key and room) says them again there, and a key kept from before says
+ * none. `say` posts the words, as the harness or its Main agent; nothing is said when Chips gave it
+ * no room. Whether it spoke comes back.
+ */
+export async function helloOnce(joined, options) {
+    const { spaceId } = joined;
+    if (spaceId === undefined)
+        return false;
+    // biome-ignore lint/style/noProcessEnv: as `join()`.
+    const store = options.keep ?? openKeyStore(options.env ?? process.env);
+    const account = accountOf(joined.url, options.name);
+    let record;
+    try {
+        const kept = store === false ? undefined : store.get(account);
+        record = kept === undefined ? undefined : JSON.parse(kept);
+    }
+    catch {
+        record = undefined;
+    }
+    // Nothing kept means it asks every time, so every start is a first.
+    const due = store === false || (record?.["hello"] === "due" && record["token"] === joined.token);
+    if (!due)
+        return false;
+    await options.say(spaceId);
+    if (store !== false)
+        store.set(account, JSON.stringify({ ...record, hello: "said" }));
+    return true;
+}
+/**
+ * Whether a value was filled in, rather than left as the placeholder a command was copied with
+ * (`API_SERVER_KEY=…`): a harness checks what it needs before it takes up a link, which works once.
+ */
+export function filledIn(value) {
+    if (value === undefined)
+        return false;
+    const given = value.trim();
+    return given !== "" && !/^(?:…|\.\.\.|<[^>]*>)$/.test(given);
+}
+/** Forget what a harness was handed, so the next `join()` asks again: a key withdrawn, say. */
+export function forgetJoin(options) {
+    // biome-ignore lint/style/noProcessEnv: as `join()`.
+    const env = options.env ?? process.env;
+    const store = options.keep ?? openKeyStore(env);
+    if (store === false)
+        return;
+    store.remove(accountOf(findServer(options, env).url, options.name));
+}
+//# sourceMappingURL=join.js.map

package/dist/join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.js","sourceRoot":"","sources":["../src/join.ts"],"names":[],"mappings":"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"}

package/dist/keep.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where a harness keeps the key it was handed when it joined (ADR 0122), so it asks once: the macOS
+ * keychain, the Secret Service where `secret-tool` is installed, or else a file only its user can
+ * read, in Chips's own config directory. The CLI's keychain does the same for the harnesses it
+ * connects (`cli/src/keychain.ts`); this is that, for a harness on the SDK, which cannot depend on
+ * the CLI.
+ *
+ * What is kept is what `join()` answers — the server's address, the harness's id, its key and its
+ * room — under the server and the harness's name, so a second harness of another name on the same
+ * machine asks for its own.
+ */
+export type Environment = Readonly<Record<string, string | undefined>>;
+/** A place a secret is kept, by account. */
+export interface KeyStore {
+    readonly kind: "keychain" | "secret-service" | "file";
+    readonly get: (account: string) => string | undefined;
+    readonly set: (account: string, secret: string) => void;
+    readonly remove: (account: string) => void;
+}
+/**
+ * The `add-generic-password` command as it is written to `security -i` (SEC-34): the secret
+ * crosses on stdin, which nothing else of this user's can read, rather than on argv, which `ps`
+ * shows every process of this user for the moment the tool runs. The CLI's keychain does the same.
+ */
+export declare function addPasswordCommand(account: string, secret: string): string;
+/** Chips's config directory: `CHIPS_CONFIG_HOME`, else `$XDG_CONFIG_HOME/chips`, else `~/.config/chips`. */
+export declare function configHome(env: Environment): string;
+/**
+ * The best place this machine has. `CHIPS_NO_KEYCHAIN=true` asks for the file, as it does of the
+ * CLI: a test, a container, a server with no keyring unlocked.
+ */
+export declare function openKeyStore(env: Environment, platform?: string): KeyStore;
+//# sourceMappingURL=keep.d.ts.map

package/dist/keep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keep.d.ts","sourceRoot":"","sources":["../src/keep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEvE,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,gBAAgB,GAAG,MAAM,CAAC;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAQnD;AA8GD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,GAAE,MAAyB,GAAG,QAAQ,CAO5F"}

package/dist/keep.js

@@ -0,0 +1,160 @@
+/**
+ * Where a harness keeps the key it was handed when it joined (ADR 0122), so it asks once: the macOS
+ * keychain, the Secret Service where `secret-tool` is installed, or else a file only its user can
+ * read, in Chips's own config directory. The CLI's keychain does the same for the harnesses it
+ * connects (`cli/src/keychain.ts`); this is that, for a harness on the SDK, which cannot depend on
+ * the CLI.
+ *
+ * What is kept is what `join()` answers — the server's address, the harness's id, its key and its
+ * room — under the server and the harness's name, so a second harness of another name on the same
+ * machine asks for its own.
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** The service name every Chips secret is kept under, as the CLI's are. */
+const SERVICE = "chips";
+/** A word as `security -i` reads it: in double quotes, its own quotes and backslashes escaped. */
+function quoted(word) {
+    if (/[\r\n]/.test(word))
+        throw new Error("A keychain account or secret is one line.");
+    return `"${word.replace(/[\\"]/g, "\\$&")}"`;
+}
+/**
+ * The `add-generic-password` command as it is written to `security -i` (SEC-34): the secret
+ * crosses on stdin, which nothing else of this user's can read, rather than on argv, which `ps`
+ * shows every process of this user for the moment the tool runs. The CLI's keychain does the same.
+ */
+export function addPasswordCommand(account, secret) {
+    return `add-generic-password -U -a ${quoted(account)} -s ${quoted(SERVICE)} -w ${quoted(secret)}\n`;
+}
+/** Chips's config directory: `CHIPS_CONFIG_HOME`, else `$XDG_CONFIG_HOME/chips`, else `~/.config/chips`. */
+export function configHome(env) {
+    const own = env["CHIPS_CONFIG_HOME"];
+    if (own !== undefined && own !== "")
+        return own;
+    const xdg = env["XDG_CONFIG_HOME"];
+    return join(xdg !== undefined && xdg !== "" ? xdg : join(env["HOME"] ?? homedir(), ".config"), "chips");
+}
+function answers(command, args) {
+    try {
+        execFileSync(command, [...args], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function keychain() {
+    const run = (args) => execFileSync("/usr/bin/security", [...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    return {
+        kind: "keychain",
+        get(account) {
+            try {
+                return run(["find-generic-password", "-a", account, "-s", SERVICE, "-w"]).trim();
+            }
+            catch {
+                return undefined;
+            }
+        },
+        set(account, secret) {
+            // On stdin, secret and all (SEC-34); the tool exits non-zero when the command inside fails.
+            execFileSync("/usr/bin/security", ["-i"], {
+                input: addPasswordCommand(account, secret),
+                stdio: ["pipe", "ignore", "ignore"],
+            });
+        },
+        remove(account) {
+            try {
+                run(["delete-generic-password", "-a", account, "-s", SERVICE]);
+            }
+            catch {
+                // Nothing kept: nothing to remove.
+            }
+        },
+    };
+}
+function secretService() {
+    const attributes = (account) => ["service", SERVICE, "account", account];
+    return {
+        kind: "secret-service",
+        get(account) {
+            try {
+                const kept = execFileSync("secret-tool", ["lookup", ...attributes(account)], {
+                    encoding: "utf8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                });
+                return kept === "" ? undefined : kept;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        set(account, secret) {
+            execFileSync("secret-tool", ["store", "--label", `Chips: ${account}`, ...attributes(account)], {
+                input: secret,
+                stdio: ["pipe", "ignore", "ignore"],
+            });
+        },
+        remove(account) {
+            try {
+                execFileSync("secret-tool", ["clear", ...attributes(account)], { stdio: "ignore" });
+            }
+            catch {
+                // Nothing kept: nothing to remove.
+            }
+        },
+    };
+}
+/** One JSON map, readable by this user alone, beside the CLI's own `secrets.json`. */
+function file(path) {
+    const read = () => {
+        if (!existsSync(path))
+            return {};
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    };
+    const write = (kept) => {
+        if (Object.keys(kept).length === 0) {
+            rmSync(path, { force: true });
+            return;
+        }
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify(kept, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(path, 0o600);
+    };
+    return {
+        kind: "file",
+        get: (account) => read()[account],
+        set(account, secret) {
+            write({ ...read(), [account]: secret });
+        },
+        remove(account) {
+            const { [account]: _gone, ...rest } = read();
+            write(rest);
+        },
+    };
+}
+/**
+ * The best place this machine has. `CHIPS_NO_KEYCHAIN=true` asks for the file, as it does of the
+ * CLI: a test, a container, a server with no keyring unlocked.
+ */
+export function openKeyStore(env, platform = process.platform) {
+    const plain = file(join(configHome(env), "harness-keys.json"));
+    if (env["CHIPS_NO_KEYCHAIN"] === "true")
+        return plain;
+    if (platform === "darwin" && answers("/usr/bin/security", ["list-keychains"]))
+        return keychain();
+    if (platform === "linux" && answers("sh", ["-c", "command -v secret-tool"]))
+        return secretService();
+    return plain;
+}
+//# sourceMappingURL=keep.js.map

package/dist/keep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keep.js","sourceRoot":"","sources":["../src/keep.ts"],"names":[],"mappings":"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"}

package/dist/lane.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A lane, from the lead's side: what `run.task()` hands back. The task is acknowledged with
+ * where the lane lives and which run it is; from then on the lead hears the lane's news as
+ * `lane.updated` — waiting, completed with the specialist's summary and what it cost, failed,
+ * cancelled — and `result` resolves with the last of those. A task Chips flattened into a step
+ * has no lane, and `result` says so at once.
+ *
+ * A lane between two spaces of one harness — a Space handed down to, a subagent — is routed to
+ * the harness itself, and the lead works it: `work()` is the run to post into (M3.5, ADR 0032).
+ */
+import type { LaneUpdated } from "@chipschat/protocol";
+import { type Handler } from "./events.js";
+export type LaneState = LaneUpdated["state"];
+/** How a lane ended, as `result` resolves: the last `lane.updated`, or the fact it never opened. */
+export type LaneOutcome = {
+    readonly state: "completed" | "failed" | "cancelled";
+    readonly summary?: string | undefined;
+    readonly costUsd?: number | undefined;
+    readonly event: LaneUpdated;
+} | {
+    readonly state: "flattened";
+};
+export interface LaneEvents {
+    /** Every `lane.updated` for this lane, in order. */
+    readonly updated: LaneUpdated;
+}
+/**
+ * What the connection gives a lane: its news, and a run for the lead to work it with. Generic
+ * over the run, so this module owes the run's nothing: `run.task()` hands back a `Lane<Run>`.
+ */
+export interface LaneWire<R> {
+    readonly hear: (laneId: string, handler: (event: LaneUpdated) => void) => () => void;
+    readonly accept: (runId: string, spaceId: string, laneId: string) => R;
+}
+export declare class Lane<R = unknown> {
+    readonly id: string;
+    private readonly wire;
+    private readonly events;
+    private settle;
+    private stop;
+    private laneState;
+    private laneRunId;
+    private laneSpaceId;
+    private lastSummary;
+    private lastCost;
+    /** Resolves when the lane ends, or at once when the task was flattened. Never rejects. */
+    readonly result: Promise<LaneOutcome>;
+    constructor(id: string, wire: LaneWire<R>);
+    /** The specialist's run, which the lane is. Known once the task is acknowledged. */
+    get runId(): string | undefined;
+    /** Where the lane lives. Known once the task is acknowledged. */
+    get spaceId(): string | undefined;
+    /** Where the lane got to: `opening` until acknowledged, then the specialist's state. */
+    get state(): LaneState | "flattened" | "opening";
+    get summary(): string | undefined;
+    get costUsd(): number | undefined;
+    /** True once the lane will not change again. */
+    get over(): boolean;
+    on<K extends keyof LaneEvents>(name: K, handler: Handler<LaneEvents[K]>): () => void;
+    /**
+     * The lane's run, for a lead that works the lane itself — a lane between two of its own
+     * spaces. Everything sent on it lands in the lane's home, as the lane's own steps and messages.
+     */
+    work(): R;
+    /** The task's acknowledgement: where the lane is, or that there is none. */
+    opened(lane: {
+        runId: string;
+        spaceId: string;
+    } | undefined): void;
+    private onUpdated;
+    private finish;
+}
+//# sourceMappingURL=lane.d.ts.map

package/dist/lane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane.d.ts","sourceRoot":"","sources":["../src/lane.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;AAE7C,oGAAoG;AACpG,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IACrD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,CAAC,CAAC;CACxE;AAID,qBAAa,IAAI,CAAC,CAAC,GAAG,OAAO;IAazB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAbvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,SAAS,CAAkD;IACnE,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAAqB;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;gBAG3B,EAAE,EAAE,MAAM,EACF,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IASpC,oFAAoF;IACpF,IAAI,KAAK,IAAI,MAAM,GAAG,SAAS,CAE9B;IAED,iEAAiE;IACjE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,wFAAwF;IACxF,IAAI,KAAK,IAAI,SAAS,GAAG,WAAW,GAAG,SAAS,CAE/C;IAED,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,gDAAgD;IAChD,IAAI,IAAI,IAAI,OAAO,CAElB;IAED,EAAE,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIpF;;;OAGG;IACH,IAAI,IAAI,CAAC;IAWT,4EAA4E;IAC5E,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GAAG,IAAI;IAWlE,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,MAAM;CAMf"}