@flow-as-code/cli 0.1.0

package/dist/bridge/pair.js

@@ -0,0 +1,219 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Reading and writing one <name>.flowdoc.json / <name>.flow.ts pair.
+//
+// This is the only place the studio bridge touches disk, and it is deliberately
+// the mirror image of the A04 watch engine: the watcher owns the ts -> doc
+// direction, this module owns doc -> ts.
+//
+// The rule that keeps the two directions from fighting each other is
+// meta.sourceHash. A pair is "in sync" when the doc carries the sha256 of the
+// exact builder source sitting next to it (docs/01-flowdoc-spec.md), which is
+// what the watcher's dirty guard reads. So a canvas save must write BOTH
+// halves and stamp the doc with the hash of the source it just generated;
+// writing only the doc would leave a pair the watcher then reports as dirty
+// in an unknowable direction.
+//
+// Generation goes through @flow-as-code/core's codegen with the existing file passed as
+// options.previous, which is how `// @keep` comments a human added to the
+// generated file survive a canvas edit (packages/core/src/codegen.ts).
+import { existsSync } from "node:fs";
+import { readFile, readdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { codegen } from "@flow-as-code/core";
+import { flowDocProblems } from "../docs.js";
+import { serializeWithMeta, sha256Hex, synthFile } from "../synth.js";
+import { pickDoc } from "../watch.js";
+import { DOC_SUFFIX, TS_SUFFIX, isBridgeDocName, } from "./protocol.js";
+/** A failure with the HTTP status the bridge should answer with. */
+export class BridgeError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "BridgeError";
+        this.status = status;
+    }
+}
+/**
+ * Thrown by writePair when the builder file has moved since the document being
+ * written was generated from it. Both sides changed, so the write is refused
+ * and the caller turns this into the "which side wins" question.
+ */
+export class PairConflict extends Error {
+    name = "PairConflict";
+    docName;
+    reason;
+    constructor(docName, reason) {
+        super(reason);
+        this.docName = docName;
+        this.reason = reason;
+    }
+}
+/**
+ * Both file paths for a document name. The name is re-checked here rather than
+ * only at the route, because this function is what turns a client string into
+ * a filesystem path: a slug cannot contain a separator, a dot, or a NUL, so
+ * traversal is impossible by construction rather than by sanitizing.
+ */
+export function pairPaths(dir, name) {
+    if (!isBridgeDocName(name)) {
+        throw new BridgeError(400, `"${name}" is not a document name: names are lowercase words separated by single hyphens.`);
+    }
+    const base = resolve(dir);
+    return { docPath: join(base, name + DOC_SUFFIX), tsPath: join(base, name + TS_SUFFIX) };
+}
+/** Every FlowDoc name in the directory, sorted, non-recursive. */
+export async function listDocNames(dir) {
+    let entries;
+    try {
+        entries = await readdir(resolve(dir));
+    }
+    catch {
+        throw new BridgeError(500, `Cannot read ${resolve(dir)}.`);
+    }
+    return entries
+        .filter((f) => f.endsWith(DOC_SUFFIX))
+        .map((f) => f.slice(0, -DOC_SUFFIX.length))
+        .filter((name) => isBridgeDocName(name))
+        .sort();
+}
+/** Parses and schema-validates a FlowDoc, naming what is wrong with it. */
+export function parseDoc(text, what) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new BridgeError(422, `${what} is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const problems = flowDocProblems(parsed);
+    if (problems.length > 0) {
+        throw new BridgeError(422, `${what} is not a valid FlowDoc: ${problems.join("; ")}`);
+    }
+    return parsed;
+}
+/** The document on disk, exactly as the file holds it. */
+export async function readPair(dir, name) {
+    const { docPath } = pairPaths(dir, name);
+    let text;
+    try {
+        text = await readFile(docPath, "utf8");
+    }
+    catch {
+        throw new BridgeError(404, `No document named "${name}" in ${resolve(dir)}.`);
+    }
+    return { name, doc: parseDoc(text, `${name}${DOC_SUFFIX}`), text };
+}
+export async function writePair(dir, name, doc, watcher, options = {}) {
+    const { docPath, tsPath } = pairPaths(dir, name);
+    if (doc.name !== name) {
+        throw new BridgeError(400, `Refusing to write flow "${doc.name}" as ${name}${DOC_SUFFIX}: the watcher pairs ` +
+            `${name}${TS_SUFFIX} with ${name}${DOC_SUFFIX} by name, so the two must agree.`);
+    }
+    const problems = flowDocProblems(doc);
+    if (problems.length > 0) {
+        throw new BridgeError(422, `Refusing to write an invalid FlowDoc: ${problems.join("; ")}`);
+    }
+    // Read the current source first: @keep comments live in it and would be
+    // deleted by a blind overwrite.
+    const previous = existsSync(tsPath) ? await readFile(tsPath, "utf8") : undefined;
+    // The dirty guard, in the doc -> ts direction. The document says which
+    // builder source it was generated from; if that file has changed since,
+    // regenerating it would throw away an edit nobody has seen. That is the same
+    // dirty-both state the watcher detects in the other direction, and it gets
+    // the same answer: refuse, and let the user choose.
+    //
+    // A document with no meta.sourceHash has no provenance to check (it was
+    // authored outside this loop), so the write proceeds; @keep comments in the
+    // existing source still survive it.
+    const provenance = doc.meta?.sourceHash;
+    if (options.force !== true && previous !== undefined && typeof provenance === "string") {
+        const onDisk = `sha256:${sha256Hex(previous)}`;
+        if (onDisk !== provenance) {
+            throw new PairConflict(name, `both sides changed: ${name}${TS_SUFFIX} was edited since this document was ` +
+                `generated from it, and saving would overwrite that edit`);
+        }
+    }
+    let tsText;
+    try {
+        tsText = codegen(doc, previous === undefined ? {} : { previous });
+    }
+    catch (err) {
+        throw new BridgeError(422, `Cannot generate ${name}${TS_SUFFIX} from this document: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const text = serializeWithMeta(doc, `sha256:${sha256Hex(tsText)}`);
+    await writeFile(tsPath, tsText, "utf8");
+    await writeFile(docPath, text, "utf8");
+    watcher?.noteWrite(name, { tsContent: tsText, docContent: text });
+    return { name, doc: JSON.parse(text), text, docPath, tsPath, tsText };
+}
+/** The FlowDoc the builder file synths to right now. */
+export async function synthPair(dir, name) {
+    const { tsPath } = pairPaths(dir, name);
+    const { flows } = await synthFile(tsPath);
+    const doc = pickDoc(flows, name);
+    if (doc === undefined) {
+        throw new BridgeError(422, `${name}${TS_SUFFIX} exports ${String(flows.length)} flows and none is named "${name}".`);
+    }
+    return doc;
+}
+/**
+ * Resolution in the code direction: the builder file wins, so the FlowDoc is
+ * rewritten from it. The source is NOT regenerated, because the user chose the
+ * source they have; only the doc moves.
+ */
+export async function adoptCode(dir, name, watcher) {
+    const { docPath, tsPath } = pairPaths(dir, name);
+    const tsText = await readFile(tsPath, "utf8").catch(() => {
+        throw new BridgeError(404, `No builder file named "${name}${TS_SUFFIX}" in ${resolve(dir)}.`);
+    });
+    const doc = await synthPair(dir, name);
+    const text = serializeWithMeta(doc, `sha256:${sha256Hex(tsText)}`);
+    await writeFile(docPath, text, "utf8");
+    watcher?.noteWrite(name, { tsContent: tsText, docContent: text });
+    return { name, doc: JSON.parse(text), text };
+}
+/**
+ * Writes `<name>.flow.ts` for every document in `dir` that has none.
+ *
+ * A directory holding only FlowDocs (an export from a live instance, a doc
+ * copied out of conformance/, a file a colleague sent) had no builder file, so
+ * the loop the studio is built around - edit the builder file, watch the canvas
+ * follow - could not start there: there was nothing to edit. Generating the
+ * file on open is safe because codegen is deterministic and the studio already
+ * regenerates it on every canvas save, so this writes exactly the bytes the
+ * first save would have written.
+ *
+ * It goes through writePair, which also stamps the document with the
+ * meta.sourceHash of the source just generated. Without that stamp the watcher
+ * would meet a pair it has never seen in sync and report a conflict on the
+ * first edit, which is the state a hand-assembled pair lands in. The bytes
+ * come back so the caller can hand them to the watcher's noteWrite as well:
+ * the stamp alone leaves the outcome resting on the initial scan winning a
+ * race against the user's first edit.
+ *
+ * A document that cannot be generated from (invalid, or holding something
+ * codegen cannot express) is reported and skipped, not thrown: the rest of the
+ * directory still opens.
+ */
+export async function ensureBuilderFiles(dir) {
+    const generated = [];
+    const problems = [];
+    for (const name of await listDocNames(dir)) {
+        const { tsPath } = pairPaths(dir, name);
+        if (existsSync(tsPath))
+            continue;
+        try {
+            const { doc } = await readPair(dir, name);
+            const written = await writePair(dir, name, doc);
+            generated.push({ name, tsPath, tsText: written.tsText, docText: written.text });
+        }
+        catch (err) {
+            problems.push({ name, message: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { generated, problems };
+}
+//# sourceMappingURL=pair.js.map

package/dist/bridge/pair.js.map

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

package/dist/bridge/protocol.d.ts

@@ -0,0 +1,187 @@
+import type { FlowDoc } from "@flow-as-code/core";
+/** Bumped when a change to this file is not backwards compatible. */
+export declare const BRIDGE_PROTOCOL = 1;
+/** Every bridge route lives under this prefix; everything else is an asset. */
+export declare const BRIDGE_PREFIX = "/bridge";
+/**
+ * The global the server injects into the served index.html. Its presence is
+ * how the studio knows it is being served by the bridge rather than opened as
+ * a static build, so the app never has to speculatively probe for a server
+ * that is not there.
+ */
+export declare const BRIDGE_GLOBAL = "__FLOW_STUDIO_BRIDGE__";
+/**
+ * Per-session secret proving a request came from the page flow-cli opened.
+ *
+ * Binding to loopback keeps the network out but not the developer's own
+ * browser: any site they visit can send this server a CORS-simple POST. A page
+ * cannot read the URL of a document it did not open, so it cannot learn this,
+ * which is what separates the studio from any other tab.
+ */
+export declare const TOKEN_PARAM = "token";
+export declare const TOKEN_HEADER = "x-flow-studio-token";
+/** The file suffixes the bridge pairs, matching the A04 watch engine. */
+export declare const DOC_SUFFIX = ".flowdoc.json";
+export declare const TS_SUFFIX = ".flow.ts";
+/** What the bridge says about itself. Injected, and served at /bridge/info. */
+export interface BridgeInfo {
+    protocol: number;
+    /** Absolute path of the served directory, for the toolbar. */
+    dir: string;
+    /** Short label for the toolbar (the directory's base name). */
+    label: string;
+    /** Session token; every bridge API request must present it. */
+    token: string;
+}
+export interface BridgeDocRef {
+    name: string;
+}
+export interface BridgeDocList {
+    docs: BridgeDocRef[];
+}
+/** A document as it exists on disk right now. `text` is the exact file bytes. */
+export interface BridgeDocPayload {
+    name: string;
+    doc: FlowDoc;
+    text: string;
+}
+/** PUT /bridge/docs/<name> */
+export interface BridgeWriteRequest {
+    doc: FlowDoc;
+    /**
+     * Write even though the builder file no longer matches the doc's
+     * meta.sourceHash. This is the user answering the conflict dialog with "keep
+     * the canvas version", and it is the ONLY thing that may set it: a write
+     * that sets it by default would be the silent overwrite the dirty guard
+     * exists to prevent.
+     */
+    force?: boolean;
+}
+/** What a successful write wrote, both halves of the pair. */
+export interface BridgeWriteResult extends BridgeDocPayload {
+    docPath: string;
+    tsPath: string;
+    /** The regenerated builder source. */
+    tsText: string;
+}
+/** Which side of a conflict the user chose: the FlowDoc or the builder code. */
+export type ConflictSide = "doc" | "code";
+/** POST /bridge/docs/<name>/resolve */
+export interface BridgeResolveRequest {
+    side: ConflictSide;
+}
+/**
+ * Both sides of a dirty-both pair, so the studio can show the diff and ask.
+ * Either side can be null when it cannot be read (unparseable JSON, a builder
+ * file that throws); the matching *Error says why, and the UI must then offer
+ * only the side it has.
+ */
+export interface BridgeConflict {
+    name: string;
+    /** The sentence describing what diverged, from whichever side noticed. */
+    reason: string;
+    /**
+     * Where the canvas side lives, which decides how the choice is applied.
+     *
+     *   "disk"   both sides are files: the watcher found the pair diverged.
+     *            Either choice is a POST to /resolve.
+     *   "canvas" the canvas side is the unsaved document in the studio (a write
+     *            the bridge refused, or a builder-file edit arriving while the
+     *            canvas had unsaved changes). Keeping it is a forced write of
+     *            that document, which only the studio holds.
+     */
+    origin: "disk" | "canvas";
+    /** Absolute paths, when the side that raised the conflict knows them. */
+    docPath?: string;
+    tsPath?: string;
+    /** The canvas side: the FlowDoc on disk, or the one the studio holds. */
+    docSide: FlowDoc | null;
+    /** The FlowDoc the builder file synths to right now. */
+    codeSide: FlowDoc | null;
+    docError?: string;
+    codeError?: string;
+}
+/**
+ * The A04 watch engine's three events, enriched with the payload the studio
+ * needs: "synced" carries the new document so the canvas can hot-reload
+ * without a second request, and "conflict" carries both sides.
+ */
+export type BridgeEvent = ({
+    seq: number;
+    kind: "synced";
+} & BridgeDocPayload) | ({
+    seq: number;
+    kind: "conflict";
+} & BridgeConflict) | {
+    seq: number;
+    kind: "error";
+    name?: string;
+    path: string;
+    message: string;
+};
+export interface BridgeEventBatch {
+    /** Highest seq in this batch, or the cursor unchanged when it is empty. */
+    cursor: number;
+    events: BridgeEvent[];
+}
+/** Every non-2xx response body. */
+export interface BridgeErrorBody {
+    error: string;
+    /** Set on the 409 a write gets while the pair is in conflict. */
+    conflict?: BridgeConflict;
+}
+/** The export targets, the same three `flow-cli emit` and `render` produce. */
+export declare const EXPORT_TARGETS: readonly ["cdk", "raw", "tf"];
+export type ExportTarget = (typeof EXPORT_TARGETS)[number];
+/**
+ * POST /bridge/export: the studio has emitted a file map and the CLI writes
+ * it, because the browser cannot and the bridge is the only thing here that
+ * touches disk. The studio computes the bytes (it holds the documents and the
+ * address or resource map); the server only checks and writes them.
+ *
+ * Deliberately not a document write: nothing is paired, nothing is synced, no
+ * event is published, and existing files are overwritten in place exactly as
+ * `flow-cli emit` overwrites them.
+ */
+export interface BridgeExportRequest {
+    target: ExportTarget;
+    /**
+     * Relative POSIX path to file content, each path satisfying isExportPath and
+     * taken relative to `subdir`.
+     */
+    files: Record<string, string>;
+    /**
+     * Subdirectory of the served directory to write into. Absent or "" writes to
+     * its root, which is where `flow-cli emit` writes with no --out.
+     */
+    subdir?: string;
+}
+export interface BridgeExportResult {
+    target: ExportTarget;
+    /** Absolute paths written, sorted. */
+    paths: string[];
+}
+/** Most files an export may carry, and the most bytes across all of them. */
+export declare const EXPORT_MAX_FILES = 200;
+export declare const EXPORT_MAX_BYTES: number;
+/** `flows.tf`, `flows/support-line.flow.tftpl`: relative, POSIX, no traversal. */
+export declare function isExportPath(path: string): boolean;
+/** A destination subdirectory: the same rule, and "" for the served root. */
+export declare function isExportSubdir(subdir: string): boolean;
+/** Documents are addressed by @flow-as-code/core slug, which is also the path guard. */
+export declare function isBridgeDocName(name: string): boolean;
+export declare function infoUrl(base: string): string;
+export declare function docsUrl(base: string): string;
+export declare function docUrl(base: string, name: string): string;
+export declare function resolveUrl(base: string, name: string): string;
+export declare function eventsUrl(base: string, cursor: number): string;
+export declare function exportUrl(base: string): string;
+/** Type guard for the injected global, used by the studio at boot. */
+export declare function readBridgeInfo(scope: unknown): BridgeInfo | undefined;
+/**
+ * The script tag the server injects into index.html. "<" is escaped so a
+ * directory name containing "</script>" cannot close the tag it sits in;
+ * JSON.stringify handles the rest, and the result is still valid JSON.
+ */
+export declare function bridgeBootScript(info: BridgeInfo): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/bridge/protocol.d.ts.map

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

package/dist/bridge/protocol.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2026 The flow-as-code Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The `flow-cli studio` bridge protocol: the whole contract between the local
+// server (packages/cli/src/bridge/server.ts) and the studio's BridgeStore
+// (packages/studio/src/store/bridgeStore.ts).
+//
+// This file exists twice, byte for byte, once in each package. The studio does
+// not depend on @flow-as-code/cli (which depends on the studio, for its built
+// assets), so importing across would make the dependency circular. The copy is
+// only safe while it is provably a copy: packages/cli/src/bridge/
+// protocol.test.ts fails if the two files differ by a single byte, the same
+// arrangement src/schema.test.ts uses for the packaged FlowDoc schema.
+//
+// Transport notes that belong to the contract, not to either implementation:
+//
+//   - Everything is JSON over plain HTTP on 127.0.0.1. No websocket library
+//     and no EventSource: the event stream is a long poll, which needs nothing
+//     but fetch, behaves identically in a browser and in a node test, and
+//     cannot half-close the way a streamed response can.
+//   - The client holds one GET /bridge/events?cursor=<seq> open at a time. The
+//     server answers immediately when it already has events past the cursor,
+//     and otherwise parks the request until one arrives or the poll times out
+//     with an empty batch. The client then re-polls from the returned cursor,
+//     so no event can be missed between two polls.
+//   - Every document is addressed by NAME, never by path. A name is a
+//     @flow-as-code/core slug; the server refuses anything else, which is also what
+//     keeps ".." out of the file paths it builds.
+import { SLUG_PATTERN } from "@flow-as-code/core";
+/** Bumped when a change to this file is not backwards compatible. */
+export const BRIDGE_PROTOCOL = 1;
+/** Every bridge route lives under this prefix; everything else is an asset. */
+export const BRIDGE_PREFIX = "/bridge";
+/**
+ * The global the server injects into the served index.html. Its presence is
+ * how the studio knows it is being served by the bridge rather than opened as
+ * a static build, so the app never has to speculatively probe for a server
+ * that is not there.
+ */
+export const BRIDGE_GLOBAL = "__FLOW_STUDIO_BRIDGE__";
+/**
+ * Per-session secret proving a request came from the page flow-cli opened.
+ *
+ * Binding to loopback keeps the network out but not the developer's own
+ * browser: any site they visit can send this server a CORS-simple POST. A page
+ * cannot read the URL of a document it did not open, so it cannot learn this,
+ * which is what separates the studio from any other tab.
+ */
+export const TOKEN_PARAM = "token";
+export const TOKEN_HEADER = "x-flow-studio-token";
+/** The file suffixes the bridge pairs, matching the A04 watch engine. */
+export const DOC_SUFFIX = ".flowdoc.json";
+export const TS_SUFFIX = ".flow.ts";
+/** The export targets, the same three `flow-cli emit` and `render` produce. */
+export const EXPORT_TARGETS = ["cdk", "raw", "tf"];
+/** Most files an export may carry, and the most bytes across all of them. */
+export const EXPORT_MAX_FILES = 200;
+export const EXPORT_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * One path segment of an export path: printable, no separator, no traversal,
+ * and never a dotfile. Anything else is refused rather than sanitized, because
+ * a sanitizer is a guess about intent and this writes files the user owns.
+ */
+const EXPORT_SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+/** Deepest an export path may nest, counting the file itself. */
+const EXPORT_MAX_DEPTH = 4;
+function exportSegments(path, maxDepth) {
+    if (path === "" || path.length > 200 || path.includes("\0") || path.includes("\\")) {
+        return undefined;
+    }
+    const segments = path.split("/");
+    if (segments.length > maxDepth)
+        return undefined;
+    return segments.every((s) => EXPORT_SEGMENT.test(s)) ? segments : undefined;
+}
+/** `flows.tf`, `flows/support-line.flow.tftpl`: relative, POSIX, no traversal. */
+export function isExportPath(path) {
+    return exportSegments(path, EXPORT_MAX_DEPTH) !== undefined;
+}
+/** A destination subdirectory: the same rule, and "" for the served root. */
+export function isExportSubdir(subdir) {
+    return subdir === "" || exportSegments(subdir, EXPORT_MAX_DEPTH - 1) !== undefined;
+}
+/** Documents are addressed by @flow-as-code/core slug, which is also the path guard. */
+export function isBridgeDocName(name) {
+    return SLUG_PATTERN.test(name);
+}
+export function infoUrl(base) {
+    return `${base}${BRIDGE_PREFIX}/info`;
+}
+export function docsUrl(base) {
+    return `${base}${BRIDGE_PREFIX}/docs`;
+}
+export function docUrl(base, name) {
+    return `${docsUrl(base)}/${encodeURIComponent(name)}`;
+}
+export function resolveUrl(base, name) {
+    return `${docUrl(base, name)}/resolve`;
+}
+export function eventsUrl(base, cursor) {
+    return `${base}${BRIDGE_PREFIX}/events?cursor=${String(cursor)}`;
+}
+export function exportUrl(base) {
+    return `${base}${BRIDGE_PREFIX}/export`;
+}
+/** Type guard for the injected global, used by the studio at boot. */
+export function readBridgeInfo(scope) {
+    if (scope === null || typeof scope !== "object")
+        return undefined;
+    const value = scope[BRIDGE_GLOBAL];
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const info = value;
+    if (info.protocol !== BRIDGE_PROTOCOL)
+        return undefined;
+    if (typeof info.token !== "string" || info.token === "")
+        return undefined;
+    if (typeof info.dir !== "string" || typeof info.label !== "string")
+        return undefined;
+    return { protocol: info.protocol, dir: info.dir, label: info.label, token: info.token };
+}
+/**
+ * The script tag the server injects into index.html. "<" is escaped so a
+ * directory name containing "</script>" cannot close the tag it sits in;
+ * JSON.stringify handles the rest, and the result is still valid JSON.
+ */
+export function bridgeBootScript(info) {
+    const json = JSON.stringify(info).replace(/</g, "\\u003c");
+    return `<script>window.${BRIDGE_GLOBAL} = ${json};</script>`;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/bridge/protocol.js.map

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

package/dist/bridge/server.d.ts

@@ -0,0 +1,95 @@
+import { type Server } from "node:http";
+import { type BridgeEvent, type BridgeInfo } from "./protocol.js";
+import { type EnsureBuilderFilesResult } from "./pair.js";
+/**
+ * A bridge event before it is published. Distributive by hand: `Omit` over a
+ * union keeps only the keys every member shares, which would erase the payload
+ * of all three event kinds.
+ */
+type Unsequenced<T> = T extends {
+    seq: number;
+} ? Omit<T, "seq"> : never;
+export type PendingEvent = Unsequenced<BridgeEvent>;
+/** The one address this server may bind. See the note at the top of the file. */
+export declare const BRIDGE_HOST = "127.0.0.1";
+export interface StudioServerOptions {
+    /** Directory of FlowDocs and builder files to serve. */
+    dir: string;
+    /**
+     * Directory of built studio assets. Omitted, the bridge serves the API only,
+     * which is what the tests use and what a `vite dev` session would proxy to.
+     */
+    assetsDir?: string;
+    /** 0 (the default) picks a free port. */
+    port?: number;
+    /** Watch `dir` for builder-file edits. Default true. */
+    watch?: boolean;
+    /**
+     * Write the missing `<name>.flow.ts` for every document in `dir` before
+     * serving it, so a directory of FlowDocs alone can start the edit-the-code
+     * loop. Default false; `flow-cli studio` turns it on. See ensureBuilderFiles.
+     */
+    ensurePairs?: boolean;
+    /** Shortened in tests; the default is a normal long-poll timeout. */
+    pollTimeoutMs?: number;
+    /** Fixed session token. Tests pin it; production generates one per run. */
+    token?: string;
+    /** Called for every published event, so the command can log a line. */
+    onEvent?: (event: BridgeEvent) => void;
+}
+export interface StudioServer {
+    readonly url: string;
+    /** Session token embedded in `url`; every bridge API call must present it. */
+    readonly token: string;
+    readonly host: string;
+    readonly port: number;
+    readonly dir: string;
+    /** What `ensurePairs` wrote and what it could not write. Empty when off. */
+    readonly prepared: EnsureBuilderFilesResult;
+    /** The underlying server, for tests that assert the bound address. */
+    readonly server: Server;
+    close(): Promise<void>;
+}
+/** 256 bits from the CSPRNG. Never logged except as part of the URL. */
+export declare function newSessionToken(): string;
+export declare function hostHeaderAllowed(host: string | undefined): boolean;
+/**
+ * Where an asset request points: the absolute path, or the status the refusal
+ * deserves. The two failures are not the same thing and must not answer the
+ * same way. A request the client mis-encoded is a 400 (it can be fixed by
+ * asking differently); a well-formed path that leaves the asset root is a 403
+ * (it cannot). Collapsing them was a real bug: decodeURIComponent throws a
+ * URIError on a truncated escape such as "/%E0%A4%A", which left this function
+ * uncaught and surfaced as 500 "URI malformed", reporting our own fault for
+ * the client's mistake.
+ */
+export type AssetTarget = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    status: 400 | 403;
+    message: string;
+};
+/**
+ * The URL parser has already collapsed "." and ".." segments, and the
+ * containment check below catches whatever survives that (an encoded
+ * separator, a symlinked name, a Windows drive letter).
+ */
+export declare function assetPathFor(root: string, pathname: string): AssetTarget;
+/**
+ * Percent-decodes one piece of a request path, or undefined when the escaping
+ * is malformed. Every decodeURIComponent in this file goes through here:
+ * unguarded it throws a URIError, and a URIError reaching the router is a 500
+ * for what is really a bad request.
+ */
+export declare function decodePathSegment(raw: string): string | undefined;
+/** Puts the boot script first in <head>, before the app's module script. */
+export declare function injectBoot(html: string, info: BridgeInfo): string;
+/**
+ * Starts the bridge on 127.0.0.1. Resolves once it is listening, with the URL
+ * to open.
+ */
+export declare function startStudioServer(options: StudioServerOptions): Promise<StudioServer>;
+export {};
+//# sourceMappingURL=server.d.ts.map