@wirebench/engine 2.1.1

package/dist/workspace/share.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `share.yaml`: whether (and how) a workspace's tree is shared, kept in the workspace's app-data
+ * folder — never inside the tree itself (see `paths.ts`'s `workspaceTreeDir`, spec §4.2). Absent
+ * means a local workspace.
+ *
+ * Mirrors `local-state.ts`'s read/write shape, but unlike that file a corrupt `share.yaml` *is*
+ * an error worth surfacing: it names how (and whether) this workspace talks to other machines,
+ * so silently treating it as "not shared" would be a data-loss-shaped surprise.
+ */
+import type { FsLike } from '../project/fs.js';
+/** File name of a workspace's share settings, directly under its app-data folder. */
+export declare const WORKSPACE_SHARE_FILE = "share.yaml";
+/** How a workspace's tree is shared. */
+export type ShareKind = 'folder' | 'git' | 'server';
+/** Git-specific share settings, all required once `kind: 'git'` is set (`remote` may still be unset). */
+export interface GitShareSettings {
+    readonly remote?: string;
+    readonly branch: string;
+    readonly autoFetchSeconds: number;
+    readonly commitOnSave: boolean;
+    readonly pushOnSave: boolean;
+}
+/** Defaults a freshly-shared git workspace is given. */
+export declare const DEFAULT_GIT_SHARE_SETTINGS: GitShareSettings;
+/** `share.yaml`, as loaded (or about to be saved). */
+export interface WorkspaceShare {
+    readonly version: 1;
+    readonly kind: ShareKind;
+    /** Absolute path to an externally managed clone/folder; absent means the managed `tree/`. */
+    readonly path?: string;
+    readonly git?: GitShareSettings;
+    readonly server?: {
+        readonly url: string;
+        readonly workspaceId: string;
+    };
+}
+/** Options shared by {@link loadShare}, {@link saveShare} and {@link deleteShare}. */
+export interface ShareOptions {
+    readonly fs?: FsLike;
+}
+/**
+ * Reads `<dir>/share.yaml`. `undefined` when the file does not exist (a local workspace).
+ *
+ * @throws WorkspaceError `workspace-file-invalid` when the file exists but is not valid YAML or
+ * does not match {@link workspaceShareSchema} (e.g. a relative `path`, or `kind: 'git'` with no
+ * `git` block).
+ */
+export declare function loadShare(dir: string, options?: ShareOptions): Promise<WorkspaceShare | undefined>;
+/** Writes `share` to `<dir>/share.yaml` atomically. */
+export declare function saveShare(dir: string, share: WorkspaceShare, options?: ShareOptions): Promise<void>;
+/** Removes `<dir>/share.yaml`, if present — used when a workspace stops being shared. */
+export declare function deleteShare(dir: string, options?: ShareOptions): Promise<void>;

package/dist/workspace/share.js

@@ -0,0 +1,89 @@
+/**
+ * `share.yaml`: whether (and how) a workspace's tree is shared, kept in the workspace's app-data
+ * folder — never inside the tree itself (see `paths.ts`'s `workspaceTreeDir`, spec §4.2). Absent
+ * means a local workspace.
+ *
+ * Mirrors `local-state.ts`'s read/write shape, but unlike that file a corrupt `share.yaml` *is*
+ * an error worth surfacing: it names how (and whether) this workspace talks to other machines,
+ * so silently treating it as "not shared" would be a data-loss-shaped surprise.
+ */
+import { join } from 'node:path';
+import { parse as parseYamlDocument } from 'yaml';
+import { WorkspaceError } from '../errors.js';
+import { nodeFs, readFileIfExists, writeFileAtomic } from '../project/fs.js';
+import { compact, stringifyYaml } from '../project/yaml.js';
+import { parseWorkspaceFile, workspaceShareSchema } from './schema.js';
+/** File name of a workspace's share settings, directly under its app-data folder. */
+export const WORKSPACE_SHARE_FILE = 'share.yaml';
+/** Defaults a freshly-shared git workspace is given. */
+export const DEFAULT_GIT_SHARE_SETTINGS = {
+    branch: 'main',
+    autoFetchSeconds: 60,
+    commitOnSave: true,
+    pushOnSave: true,
+};
+function shareFile(dir) {
+    return join(dir, WORKSPACE_SHARE_FILE);
+}
+/**
+ * Reads `<dir>/share.yaml`. `undefined` when the file does not exist (a local workspace).
+ *
+ * @throws WorkspaceError `workspace-file-invalid` when the file exists but is not valid YAML or
+ * does not match {@link workspaceShareSchema} (e.g. a relative `path`, or `kind: 'git'` with no
+ * `git` block).
+ */
+export async function loadShare(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const path = shareFile(dir);
+    const buffer = await readFileIfExists(fs, path);
+    if (buffer === undefined) {
+        return undefined;
+    }
+    let document;
+    try {
+        document = parseYamlDocument(buffer.toString('utf8'));
+    }
+    catch (error) {
+        throw new WorkspaceError('workspace-file-invalid', `Malformed YAML in ${WORKSPACE_SHARE_FILE}`, {
+            details: {
+                file: WORKSPACE_SHARE_FILE,
+                issues: [{ path: '', message: error instanceof Error ? error.message : String(error) }],
+            },
+            cause: error,
+        });
+    }
+    const parsed = parseWorkspaceFile(workspaceShareSchema, document, WORKSPACE_SHARE_FILE);
+    return {
+        version: parsed.version,
+        kind: parsed.kind,
+        ...(parsed.path !== undefined ? { path: parsed.path } : {}),
+        ...(parsed.git !== undefined
+            ? {
+                git: {
+                    branch: parsed.git.branch,
+                    autoFetchSeconds: parsed.git.autoFetchSeconds,
+                    commitOnSave: parsed.git.commitOnSave,
+                    pushOnSave: parsed.git.pushOnSave,
+                    ...(parsed.git.remote !== undefined ? { remote: parsed.git.remote } : {}),
+                },
+            }
+            : {}),
+        ...(parsed.server !== undefined ? { server: parsed.server } : {}),
+    };
+}
+/** Writes `share` to `<dir>/share.yaml` atomically. */
+export async function saveShare(dir, share, options) {
+    const fs = options?.fs ?? nodeFs;
+    await writeFileAtomic(fs, shareFile(dir), stringifyYaml(compact({
+        version: share.version,
+        kind: share.kind,
+        path: share.path,
+        git: share.git === undefined ? undefined : compact({ ...share.git }),
+        server: share.server === undefined ? undefined : compact({ ...share.server }),
+    })));
+}
+/** Removes `<dir>/share.yaml`, if present — used when a workspace stops being shared. */
+export async function deleteShare(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    await fs.rm(shareFile(dir), { force: true });
+}

package/dist/ws/browser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The browser-safe face of `ws/`: pure helpers with no Node dependency, reachable from the
+ * renderer as `@wirebench/engine/ws` (ESLint allows this subpath and no other). `model.ts` needs
+ * `project/paths.js` for its slugs (`node:path`), so only its types are re-exported here — the
+ * factories (`createWsApi` and friends) stay engine-side; the tree-walking and file-naming rules
+ * come from `shape.ts`, which is node-free, and URL resolution and frame pretty-printing come from
+ * `url.ts` and `pretty.ts`, also node-free.
+ */
+export type { CreateWsApiInput, CreateWsFolderInput, CreateWsRequestInput, WsApi, WsDefinitionRef, WsExchange, WsFolder, WsFrame, WsHandshake, WsOpcode, WsRequestDef, WsRequestSettings, WsSavedMessage, } from './model.js';
+export { wsApiFolders, wsApiRequests, wsFolderRequests, wsMessageFileName } from './shape.js';
+export { resolveWsUrl } from './url.js';
+export { prettyFrameText } from './pretty.js';
+export type { PrettyFrameResult } from './pretty.js';

package/dist/ws/browser.js

@@ -0,0 +1,11 @@
+/**
+ * The browser-safe face of `ws/`: pure helpers with no Node dependency, reachable from the
+ * renderer as `@wirebench/engine/ws` (ESLint allows this subpath and no other). `model.ts` needs
+ * `project/paths.js` for its slugs (`node:path`), so only its types are re-exported here — the
+ * factories (`createWsApi` and friends) stay engine-side; the tree-walking and file-naming rules
+ * come from `shape.ts`, which is node-free, and URL resolution and frame pretty-printing come from
+ * `url.ts` and `pretty.ts`, also node-free.
+ */
+export { wsApiFolders, wsApiRequests, wsFolderRequests, wsMessageFileName } from './shape.js';
+export { resolveWsUrl } from './url.js';
+export { prettyFrameText } from './pretty.js';

package/dist/ws/call.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Turns a saved WebSocket request, plus the API it belongs to and the credentials the host has
+ * already resolved, into the options `openWsSession` takes. Everything here is pure: no socket is
+ * opened, nothing is read from disk or the keychain — that is `apiHeaders`, `material.auth` and
+ * friends, all handed in already resolved.
+ *
+ * Layering, in order: API headers first, then the request's own headers (which override the API's
+ * by case-insensitive name), then auth (which overrides both). An API key configured "in query"
+ * lands in the URL's query string, exactly where REST puts it — `resolveWsUrl` appends it after
+ * the request's own query rows.
+ */
+import type { SendAuth } from '../types.js';
+import type { ProxyOptions, TlsOptions } from '../http/types.js';
+import type { WsSessionOptions } from './session.js';
+import type { WsCallInput } from './expand.js';
+export type { WsCallInput } from './expand.js';
+/**
+ * Handshake header names undici either refuses or silently mangles when a caller sets them
+ * itself: `sec-websocket-key`/`-version` end up sent *twice* (the caller's value and undici's own,
+ * comma-joined on the wire — confirmed against `startTestWsServer`, which then sees a malformed
+ * `Sec-WebSocket-Version: 99, 13`), `upgrade`/`connection` collide with the ones undici sets to
+ * open the connection, and `sec-websocket-protocol` as a plain header does nothing at all — undici
+ * only negotiates a subprotocol through its own `protocols` option, which `subprotocols` here
+ * becomes. Dropping these rather than throwing keeps a pasted-in header harmless instead of fatal;
+ * `sec-websocket-accept` is included for the same reason though it only ever appears in a
+ * response, never a request. `host` stays here too: the transport sets it itself from the URL, so
+ * a caller-supplied value would only ever be overridden, never honoured.
+ *
+ * Exported for the unit test only — not part of the package's public surface.
+ */
+export declare const FORBIDDEN_HANDSHAKE_HEADERS: ReadonlySet<string>;
+/**
+ * What {@link toWsSessionOptions} additionally accepts beyond the call's own fields. An absent
+ * `auth` means no credentials at all — the common case of a request that inherited nothing and
+ * configured nothing.
+ */
+export interface WsSessionMaterial {
+    readonly auth?: SendAuth;
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Builds the options `openWsSession` takes from a saved request: URL resolution, header merging,
+ * auth, and the request's own transport settings. The project/preference settings ladder (trust
+ * store, bind address, timeouts inherited from higher up) is a desktop concern handled later —
+ * this reads only `input.request.settings`.
+ *
+ * @throws WsError `ws-auth-unsupported` for NTLM. An absent `material.auth` means no credentials
+ * and never throws.
+ * @throws WsError `ws-bad-url` (via `resolveWsUrl`) for a URL that cannot be resolved.
+ */
+export declare function toWsSessionOptions(input: WsCallInput, material: WsSessionMaterial): WsSessionOptions;

package/dist/ws/call.js

@@ -0,0 +1,106 @@
+/**
+ * Turns a saved WebSocket request, plus the API it belongs to and the credentials the host has
+ * already resolved, into the options `openWsSession` takes. Everything here is pure: no socket is
+ * opened, nothing is read from disk or the keychain — that is `apiHeaders`, `material.auth` and
+ * friends, all handed in already resolved.
+ *
+ * Layering, in order: API headers first, then the request's own headers (which override the API's
+ * by case-insensitive name), then auth (which overrides both). An API key configured "in query"
+ * lands in the URL's query string, exactly where REST puts it — `resolveWsUrl` appends it after
+ * the request's own query rows.
+ */
+import { applyAuth } from '../rest/auth.js';
+import { WsError } from '../errors.js';
+import { resolveWsUrl } from './url.js';
+/**
+ * Handshake header names undici either refuses or silently mangles when a caller sets them
+ * itself: `sec-websocket-key`/`-version` end up sent *twice* (the caller's value and undici's own,
+ * comma-joined on the wire — confirmed against `startTestWsServer`, which then sees a malformed
+ * `Sec-WebSocket-Version: 99, 13`), `upgrade`/`connection` collide with the ones undici sets to
+ * open the connection, and `sec-websocket-protocol` as a plain header does nothing at all — undici
+ * only negotiates a subprotocol through its own `protocols` option, which `subprotocols` here
+ * becomes. Dropping these rather than throwing keeps a pasted-in header harmless instead of fatal;
+ * `sec-websocket-accept` is included for the same reason though it only ever appears in a
+ * response, never a request. `host` stays here too: the transport sets it itself from the URL, so
+ * a caller-supplied value would only ever be overridden, never honoured.
+ *
+ * Exported for the unit test only — not part of the package's public surface.
+ */
+export const FORBIDDEN_HANDSHAKE_HEADERS = new Set([
+    'sec-websocket-key',
+    'sec-websocket-version',
+    'sec-websocket-extensions',
+    'sec-websocket-accept',
+    'sec-websocket-protocol',
+    'upgrade',
+    'connection',
+    'host',
+]);
+/** Merges header rows by case-insensitive name, later rows overriding earlier ones. */
+function mergeHeaders(...layers) {
+    const byLowerName = new Map();
+    for (const layer of layers) {
+        for (const row of layer) {
+            if (!row.enabled || row.name === '')
+                continue;
+            byLowerName.set(row.name.toLowerCase(), { name: row.name, value: row.value });
+        }
+    }
+    const result = {};
+    for (const { name, value } of byLowerName.values()) {
+        if (FORBIDDEN_HANDSHAKE_HEADERS.has(name.toLowerCase()))
+            continue;
+        result[name] = value;
+    }
+    return result;
+}
+/** Credentials resolved into the header (or headers) they become on the wire. */
+function authHeadersAndQuery(auth) {
+    if (auth === undefined) {
+        return { headers: {}, query: [] };
+    }
+    if (auth.type === 'ntlm') {
+        throw new WsError('ws-auth-unsupported', 'NTLM authenticates a connection over several HTTP round trips, which a single WebSocket handshake cannot do. Use Basic, Bearer, an API key, or OAuth2 instead.', { details: { type: auth.type } });
+    }
+    if (auth.type === 'basic') {
+        // `rest/auth.ts`'s `applyAuth` deliberately leaves Basic to the HTTP transport's challenge
+        // flow, because a REST send can retry after a 401. A WebSocket handshake gets exactly one
+        // request, so there is no challenge to wait for: the header goes straight on, same as REST's
+        // "preemptive" Basic.
+        const encoded = Buffer.from(`${auth.username}:${auth.password}`, 'utf8').toString('base64');
+        return { headers: { Authorization: `Basic ${encoded}` }, query: [] };
+    }
+    const applied = applyAuth(auth);
+    return { headers: { ...applied.headers }, query: applied.query };
+}
+/**
+ * Builds the options `openWsSession` takes from a saved request: URL resolution, header merging,
+ * auth, and the request's own transport settings. The project/preference settings ladder (trust
+ * store, bind address, timeouts inherited from higher up) is a desktop concern handled later —
+ * this reads only `input.request.settings`.
+ *
+ * @throws WsError `ws-auth-unsupported` for NTLM. An absent `material.auth` means no credentials
+ * and never throws.
+ * @throws WsError `ws-bad-url` (via `resolveWsUrl`) for a URL that cannot be resolved.
+ */
+export function toWsSessionOptions(input, material) {
+    const { headers: authHeaders, query: authQuery } = authHeadersAndQuery(material.auth);
+    const query = [...input.request.query, ...authQuery];
+    const url = resolveWsUrl(input.serverUrl, input.request.url, query);
+    const headers = mergeHeaders(input.apiHeaders, input.request.headers, [
+        ...Object.entries(authHeaders).map(([name, value]) => ({ name, value, enabled: true })),
+    ]);
+    const settings = input.request.settings;
+    const tls = settings.trustInvalid === true ? { ...material.tls, rejectUnauthorized: false } : material.tls;
+    return {
+        url,
+        headers,
+        ...(input.request.subprotocols.length > 0 ? { subprotocols: input.request.subprotocols } : {}),
+        ...(tls !== undefined ? { tls } : {}),
+        ...(material.proxy !== undefined ? { proxy: material.proxy } : {}),
+        ...(settings.bindAddress !== undefined ? { localAddress: settings.bindAddress } : {}),
+        ...(settings.handshakeTimeoutMs !== undefined ? { handshakeTimeoutMs: settings.handshakeTimeoutMs } : {}),
+        ...(settings.maxMessageBytes !== undefined ? { maxMessageBytes: settings.maxMessageBytes } : {}),
+        ...(material.signal !== undefined ? { signal: material.signal } : {}),
+    };
+}

package/dist/ws/command.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The command-line equivalent of a WebSocket session, for the Code panel: what a person would
+ * type at a shell to dial the same URL with `websocat`, a generic open-source WebSocket
+ * command-line client (as `grpcurl` is in `grpc/command.ts`).
+ */
+import type { WsSessionOptions } from './session.js';
+/** Options for {@link wsToCommand}. */
+export interface WsToCommandFlags {
+    /** `-k`: connect even when the certificate does not verify. */
+    readonly insecure?: boolean;
+    readonly shell?: 'posix' | 'powershell';
+}
+/**
+ * Renders a session's options as a `websocat` command line: `-H='name: value'` per header, in
+ * insertion order, `--protocol` with the subprotocols joined by a comma when there are any, `-k`
+ * when the caller says the connection is insecure, and the URL last, every argument quoted for
+ * the shell.
+ */
+export declare function wsToCommand(options: Pick<WsSessionOptions, 'url' | 'headers' | 'subprotocols'>, flags?: WsToCommandFlags): string;

package/dist/ws/command.js

@@ -0,0 +1,28 @@
+/**
+ * The command-line equivalent of a WebSocket session, for the Code panel: what a person would
+ * type at a shell to dial the same URL with `websocat`, a generic open-source WebSocket
+ * command-line client (as `grpcurl` is in `grpc/command.ts`).
+ */
+import { quoteForShell } from '../http/curl.js';
+/**
+ * Renders a session's options as a `websocat` command line: `-H='name: value'` per header, in
+ * insertion order, `--protocol` with the subprotocols joined by a comma when there are any, `-k`
+ * when the caller says the connection is insecure, and the URL last, every argument quoted for
+ * the shell.
+ */
+export function wsToCommand(options, flags = {}) {
+    const shell = flags.shell ?? 'posix';
+    const q = (value) => quoteForShell(value, shell);
+    const parts = ['websocat'];
+    if (flags.insecure === true) {
+        parts.push('-k');
+    }
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+        parts.push(`-H=${q(`${name}: ${value}`)}`);
+    }
+    if (options.subprotocols !== undefined && options.subprotocols.length > 0) {
+        parts.push('--protocol', q(options.subprotocols.join(',')));
+    }
+    parts.push(q(options.url));
+    return parts.join(' ');
+}

package/dist/ws/expand.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Property expansion for a WebSocket call: every `${…}` reference in the request URL, its query
+ * and header rows, and its subprotocols, resolved against the same scopes a REST or gRPC send
+ * uses. Message text is expanded separately (`expandWsMessage`), since a message is sent long
+ * after the call's other fields are settled and may be edited and resent several times over one
+ * session.
+ *
+ * Mirrors `grpc/expand.ts`: names as well as values are expanded, an unresolved reference is
+ * reported once per place it appears rather than guessed at or deduplicated, and `escape` — JSON
+ * string escaping — applies only to a message, never to a header, query row or the URL.
+ */
+import type { PropertyScopes, UnresolvedRef } from '../project/properties.js';
+import type { KeyValueEntry } from '../rest/model.js';
+import type { WsRequestDef } from './model.js';
+/** Input to {@link expandWsInput}: the parts of a saved request an open call needs. */
+export interface WsCallInput {
+    readonly serverUrl: string;
+    readonly request: Pick<WsRequestDef, 'url' | 'query' | 'headers' | 'subprotocols' | 'settings'>;
+    readonly apiHeaders: readonly KeyValueEntry[];
+}
+/**
+ * Expands every property reference in a call's URL, query rows, header rows (both the API's and
+ * the request's own) and subprotocols.
+ */
+export declare function expandWsInput(input: WsCallInput, scopes: PropertyScopes): {
+    readonly input: WsCallInput;
+    readonly unresolved: readonly UnresolvedRef[];
+};
+/**
+ * Expands every property reference in one message's text. `escape: true` JSON-escapes every
+ * substituted value, for a message that is going to be embedded in a larger JSON payload.
+ */
+export declare function expandWsMessage(text: string, scopes: PropertyScopes, options: {
+    readonly escape: boolean;
+}): {
+    readonly text: string;
+    readonly unresolved: readonly UnresolvedRef[];
+};

package/dist/ws/expand.js

@@ -0,0 +1,76 @@
+/**
+ * Property expansion for a WebSocket call: every `${…}` reference in the request URL, its query
+ * and header rows, and its subprotocols, resolved against the same scopes a REST or gRPC send
+ * uses. Message text is expanded separately (`expandWsMessage`), since a message is sent long
+ * after the call's other fields are settled and may be edited and resent several times over one
+ * session.
+ *
+ * Mirrors `grpc/expand.ts`: names as well as values are expanded, an unresolved reference is
+ * reported once per place it appears rather than guessed at or deduplicated, and `escape` — JSON
+ * string escaping — applies only to a message, never to a header, query row or the URL.
+ */
+import { expand } from '../project/properties.js';
+import { escapeForLanguage } from '../rest/body.js';
+function runRows(rows, run) {
+    return rows.map((row) => ({ ...row, name: run(row.name), value: run(row.value) }));
+}
+/**
+ * Expands every property reference in a call's URL, query rows, header rows (both the API's and
+ * the request's own) and subprotocols.
+ */
+export function expandWsInput(input, scopes) {
+    const unresolved = [];
+    const run = (text) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        return result.text;
+    };
+    return {
+        input: {
+            ...input,
+            request: {
+                ...input.request,
+                url: run(input.request.url),
+                query: runRows(input.request.query, run),
+                headers: runRows(input.request.headers, run),
+                subprotocols: input.request.subprotocols.map((protocol) => run(protocol)),
+            },
+            apiHeaders: runRows(input.apiHeaders, run),
+        },
+        unresolved,
+    };
+}
+/**
+ * Expands every property reference in one message's text. `escape: true` JSON-escapes every
+ * substituted value, for a message that is going to be embedded in a larger JSON payload.
+ */
+export function expandWsMessage(text, scopes, options) {
+    const unresolved = [];
+    const plain = expand(text, scopes);
+    unresolved.push(...plain.unresolved);
+    if (!options.escape) {
+        return { text: plain.text, unresolved };
+    }
+    const escaped = expand(text, escapedScopes(scopes));
+    return { text: escaped.text, unresolved };
+}
+/** The same scopes with every value JSON-escaped, so substitution escapes as it goes. */
+function escapedScopes(scopes) {
+    const escapeMap = (map) => {
+        const out = {};
+        for (const [name, value] of Object.entries(map ?? {})) {
+            if (value !== undefined) {
+                out[name] = escapeForLanguage(value, 'json');
+            }
+        }
+        return out;
+    };
+    return {
+        ...scopes,
+        project: escapeMap(scopes.project),
+        global: escapeMap(scopes.global),
+        system: escapeMap(scopes.system),
+        ...(scopes.env !== undefined ? { env: escapeMap(scopes.env) } : {}),
+        ...(scopes.workspace !== undefined ? { workspace: escapeMap(scopes.workspace) } : {}),
+    };
+}