@wirebench/engine 2.2.1 → 3.1.0

package/dist/workspace/environments.d.ts

@@ -14,9 +14,8 @@
  * `Endpoint` object of their own, so neither of the first two branches
  * carries one.
  */
-import type { Endpoint, Environment, Interface, Project, PropertyMap, RequestDef } from '../project/model.js';
+import type { Endpoint, Environment, Interface, Project, PropertyMap, SoapRequestDef } from '../project/model.js';
 import type { BaseUrlSource, EndpointSource } from '../project/environments.js';
-import type { RestApi } from '../rest/model.js';
 import type { PropertyScopes } from '../project/properties.js';
 import type { Workspace, WorkspaceEnvironment } from './model.js';
 /**
@@ -25,6 +24,11 @@ import type { Workspace, WorkspaceEnvironment } from './model.js';
  * is `undefined`).
  */
 export declare function linkedEnvironment(project: Project, workspaceEnv: WorkspaceEnvironment | undefined): Environment | undefined;
+/**
+ * `workspace` with `environmentId` as its active environment, or with none active when it is
+ * `undefined`: resolution under a chosen environment without touching the workspace's own.
+ */
+export declare function withActiveEnvironment(workspace: Workspace, environmentId: string | undefined): Workspace;
 /**
  * Builds the {@link PropertyScopes} for expanding properties against `project` as opened inside
  * `workspace`. `env` merges the active workspace environment's properties with the linked
@@ -54,7 +58,7 @@ export declare function resolveWorkspaceEndpoint(input: {
     readonly project: Project;
     readonly projectSlug: string;
     readonly iface: Interface;
-    readonly request: Pick<RequestDef, 'endpointId' | 'endpointUrl'>;
+    readonly request: Pick<SoapRequestDef, 'endpointId' | 'endpointUrl'>;
 }): {
     url: string | undefined;
     source: EndpointSource;
@@ -72,7 +76,10 @@ export declare function resolveWorkspaceApiBaseUrl(input: {
     readonly workspace: Workspace;
     readonly project: Project;
     readonly projectSlug: string;
-    readonly api: Pick<RestApi, 'slug' | 'baseUrl'>;
+    readonly api: {
+        readonly slug: string;
+        readonly baseUrl: string;
+    };
 }): {
     url: string;
     source: BaseUrlSource;

package/dist/workspace/environments.js

@@ -27,6 +27,18 @@ export function linkedEnvironment(project, workspaceEnv) {
     }
     return project.environments.find((environment) => environment.slug === workspaceEnv.slug);
 }
+/**
+ * `workspace` with `environmentId` as its active environment, or with none active when it is
+ * `undefined`: resolution under a chosen environment without touching the workspace's own.
+ */
+export function withActiveEnvironment(workspace, environmentId) {
+    if (environmentId !== undefined) {
+        return { ...workspace, activeEnvironmentId: environmentId };
+    }
+    const copy = { ...workspace };
+    delete copy.activeEnvironmentId;
+    return copy;
+}
 /** Finds `workspace`'s active environment (per `activeEnvironmentId`), or `undefined` when none is active. */
 function activeWorkspaceEnvironment(workspace) {
     if (workspace.activeEnvironmentId === undefined) {

package/dist/workspace/index.d.ts

@@ -9,7 +9,7 @@ export { WORKSPACE_FORMAT_VERSION, createWorkspace, createWorkspaceEnvironment }
 export type { Workspace, WorkspaceEnvironment, WorkspaceProjectRef } from './model.js';
 export { parseWorkspaceFile, workspaceEnvironmentFileSchema, workspaceManifestSchema, workspaceProjectRefSchema, workspaceLocalStateSchema, workspaceShareSchema, } from './schema.js';
 export type { WorkspaceEnvironmentFile, WorkspaceManifestFile, WorkspaceProjectRefFile } from './schema.js';
-export { WORKSPACES_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR, WORKSPACE_STATE_FILE, WORKSPACE_TREE_DIR, WORKSPACE_JOINING_DIR, GIT_ATTRIBUTES_FILE, GIT_ATTRIBUTES, workspaceDir, workspaceEnvironmentFile, workspaceManifestFile, workspaceProjectDir, workspaceTreeDir, assertPathSegment, } from './paths.js';
+export { WORKSPACES_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR, WORKSPACE_STATE_FILE, WORKSPACE_TREE_DIR, WORKSPACE_JOINING_DIR, GIT_ATTRIBUTES_FILE, GIT_ATTRIBUTES, TEAM_SECRETS_DIR, workspaceDir, workspaceEnvironmentFile, workspaceManifestFile, workspaceProjectDir, workspaceTreeDir, assertPathSegment, } from './paths.js';
 export { workspaceFiles } from './serialize.js';
 export type { WorkspaceFiles } from './serialize.js';
 export { loadWorkspace } from './load.js';
@@ -20,8 +20,8 @@ export { migrateWorkspace } from './migrate.js';
 export type { MigratedWorkspaceManifest } from './migrate.js';
 export { WORKSPACE_LOCAL_FILE, EMPTY_LOCAL_STATE, loadLocalState, saveLocalState } from './local-state.js';
 export type { WorkspaceLocalState, LocalStateOptions } from './local-state.js';
-export { WORKSPACE_SHARE_FILE, DEFAULT_GIT_SHARE_SETTINGS, loadShare, saveShare, deleteShare } from './share.js';
-export type { ShareKind, GitShareSettings, WorkspaceShare, ShareOptions } from './share.js';
+export { WORKSPACE_SHARE_FILE, DEFAULT_GIT_SHARE_SETTINGS, DEFAULT_SYNC_SETTINGS, loadShare, saveShare, deleteShare, shareSyncSettings, } from './share.js';
+export type { ShareKind, GitShareSettings, ServerShareSettings, SyncSettings, WorkspaceShare, ShareOptions, } from './share.js';
 export { reidentifyProject } from './reidentify.js';
 export { resolveWorkspaceApiBaseUrl, linkedEnvironment, resolveWorkspaceEndpoint, resolveWorkspaceScopes, } from './environments.js';
 export { commitMessage, describeTreePath } from './commit-message.js';

package/dist/workspace/index.js

@@ -7,13 +7,13 @@
  */
 export { WORKSPACE_FORMAT_VERSION, createWorkspace, createWorkspaceEnvironment } from './model.js';
 export { parseWorkspaceFile, workspaceEnvironmentFileSchema, workspaceManifestSchema, workspaceProjectRefSchema, workspaceLocalStateSchema, workspaceShareSchema, } from './schema.js';
-export { WORKSPACES_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR, WORKSPACE_STATE_FILE, WORKSPACE_TREE_DIR, WORKSPACE_JOINING_DIR, GIT_ATTRIBUTES_FILE, GIT_ATTRIBUTES, workspaceDir, workspaceEnvironmentFile, workspaceManifestFile, workspaceProjectDir, workspaceTreeDir, assertPathSegment, } from './paths.js';
+export { WORKSPACES_DIR, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR, WORKSPACE_STATE_FILE, WORKSPACE_TREE_DIR, WORKSPACE_JOINING_DIR, GIT_ATTRIBUTES_FILE, GIT_ATTRIBUTES, TEAM_SECRETS_DIR, workspaceDir, workspaceEnvironmentFile, workspaceManifestFile, workspaceProjectDir, workspaceTreeDir, assertPathSegment, } from './paths.js';
 export { workspaceFiles } from './serialize.js';
 export { loadWorkspace } from './load.js';
 export { saveWorkspace } from './save.js';
 export { migrateWorkspace } from './migrate.js';
 export { WORKSPACE_LOCAL_FILE, EMPTY_LOCAL_STATE, loadLocalState, saveLocalState } from './local-state.js';
-export { WORKSPACE_SHARE_FILE, DEFAULT_GIT_SHARE_SETTINGS, loadShare, saveShare, deleteShare } from './share.js';
+export { WORKSPACE_SHARE_FILE, DEFAULT_GIT_SHARE_SETTINGS, DEFAULT_SYNC_SETTINGS, loadShare, saveShare, deleteShare, shareSyncSettings, } from './share.js';
 export { reidentifyProject } from './reidentify.js';
 export { resolveWorkspaceApiBaseUrl, linkedEnvironment, resolveWorkspaceEndpoint, resolveWorkspaceScopes, } from './environments.js';
 export { commitMessage, describeTreePath } from './commit-message.js';

package/dist/workspace/paths.d.ts

@@ -32,13 +32,16 @@ export declare const WORKSPACE_TREE_DIR = "tree";
 export declare const WORKSPACE_JOINING_DIR = ".joining";
 /** File name of the tree's own `.gitattributes`, written on share and on join if missing. */
 export declare const GIT_ATTRIBUTES_FILE = ".gitattributes";
+/** Directory at the tree root holding team secrets: key requests, the access log and the vault (team-secrets §4). */
+export declare const TEAM_SECRETS_DIR = "team-secrets";
 /**
  * Contents of {@link GIT_ATTRIBUTES_FILE}: normalises line endings, and leaves bytes alone where
  * they must stay exact — attachments, and the definition caches of interfaces and APIs, which keep
  * each document as fetched (a WSDL's manifest records its SHA-256, so a CRLF definition normalised
- * by git fails that check on the other side, which then re-fetches and rewrites the cache).
+ * by git fails that check on the other side, which then re-fetches and rewrites the cache). A vault
+ * entry is never text-merged: two concurrent changes are a conflict the sync settles whole.
  */
-export declare const GIT_ATTRIBUTES = "* text=auto eol=lf\n*.yaml text\n*.xml text\n*.wsdl text\n*.xsd text\nprojects/*/attachments/** -text\nprojects/*/interfaces/*/definition/** -text\nprojects/*/apis/*/definition/** -text\n";
+export declare const GIT_ATTRIBUTES = "* text=auto eol=lf\n*.yaml text\n*.xml text\n*.wsdl text\n*.xsd text\nprojects/*/attachments/** -text\nprojects/*/interfaces/*/definition/** -text\nprojects/*/apis/*/definition/** -text\nteam-secrets/values/** -merge\n";
 /** Absolute path of a workspace's own directory, given the app's user-data root and the workspace id. */
 export declare function workspaceDir(userDataDir: string, workspaceId: string): string;
 /** Absolute path of a workspace's manifest. */

package/dist/workspace/paths.js

@@ -50,13 +50,16 @@ export const WORKSPACE_TREE_DIR = 'tree';
 export const WORKSPACE_JOINING_DIR = '.joining';
 /** File name of the tree's own `.gitattributes`, written on share and on join if missing. */
 export const GIT_ATTRIBUTES_FILE = '.gitattributes';
+/** Directory at the tree root holding team secrets: key requests, the access log and the vault (team-secrets §4). */
+export const TEAM_SECRETS_DIR = 'team-secrets';
 /**
  * Contents of {@link GIT_ATTRIBUTES_FILE}: normalises line endings, and leaves bytes alone where
  * they must stay exact — attachments, and the definition caches of interfaces and APIs, which keep
  * each document as fetched (a WSDL's manifest records its SHA-256, so a CRLF definition normalised
- * by git fails that check on the other side, which then re-fetches and rewrites the cache).
+ * by git fails that check on the other side, which then re-fetches and rewrites the cache). A vault
+ * entry is never text-merged: two concurrent changes are a conflict the sync settles whole.
  */
-export const GIT_ATTRIBUTES = '* text=auto eol=lf\n*.yaml text\n*.xml text\n*.wsdl text\n*.xsd text\nprojects/*/attachments/** -text\nprojects/*/interfaces/*/definition/** -text\nprojects/*/apis/*/definition/** -text\n';
+export const GIT_ATTRIBUTES = '* text=auto eol=lf\n*.yaml text\n*.xml text\n*.wsdl text\n*.xsd text\nprojects/*/attachments/** -text\nprojects/*/interfaces/*/definition/** -text\nprojects/*/apis/*/definition/** -text\nteam-secrets/values/** -merge\n';
 /** Absolute path of a workspace's own directory, given the app's user-data root and the workspace id. */
 export function workspaceDir(userDataDir, workspaceId) {
     return join(userDataDir, WORKSPACES_DIR, workspaceId);

package/dist/workspace/schema.d.ts

@@ -55,15 +55,15 @@ export declare const workspaceLocalStateSchema: z.ZodObject<{
 }, z.core.$strip>;
 /**
  * `share.yaml`: absent means a local workspace. `path`, when set, must be absolute — it is only
- * ever written from a native folder picker. `kind: 'git'` requires `git`; `kind: 'server'`
- * requires `server`.
+ * ever written from a native folder picker — and a server share has none, because its tree is
+ * always the managed `tree/`. `kind: 'git'` requires `git`; `kind: 'server'` requires `server`.
  */
 export declare const workspaceShareSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     kind: z.ZodEnum<{
         server: "server";
-        folder: "folder";
         git: "git";
+        folder: "folder";
     }>;
     path: z.ZodOptional<z.ZodString>;
     git: z.ZodOptional<z.ZodObject<{
@@ -76,6 +76,10 @@ export declare const workspaceShareSchema: z.ZodObject<{
     server: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
         workspaceId: z.ZodString;
+        teamName: z.ZodOptional<z.ZodString>;
+        autoFetchSeconds: z.ZodDefault<z.ZodNumber>;
+        commitOnSave: z.ZodDefault<z.ZodBoolean>;
+        pushOnSave: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** The manifest document as persisted. */

package/dist/workspace/schema.js

@@ -10,6 +10,7 @@
 import { isAbsolute } from 'node:path';
 import { z } from 'zod';
 import { WorkspaceError } from '../errors.js';
+import { TEAMS_ID_PATTERN } from '../server-api/teams.js';
 import { WORKSPACE_FORMAT_VERSION } from './model.js';
 const nonEmpty = z.string().min(1);
 const propertyMapSchema = z.record(z.string(), z.string());
@@ -70,10 +71,26 @@ const gitShareSettingsSchema = z.object({
     commitOnSave: z.boolean(),
     pushOnSave: z.boolean(),
 });
+/** An http(s) origin and nothing more: what the desktop's `normalizeServerUrl` returns (`URL.origin`). */
+const SERVER_ORIGIN_PATTERN = /^https?:\/\/[^/?#]+$/;
+/**
+ * `share.yaml`'s `server` block (server-sync spec §4.1). The three sync settings default to the
+ * values in `DEFAULT_SYNC_SETTINGS` (`share.ts`, which imports this file, so they are literals
+ * here; a test pins that the two agree). `workspaceId` is the server's ULID and equals
+ * `workspace.yaml`'s id; `teamName` is for display only.
+ */
+const serverShareSettingsSchema = z.object({
+    url: z.string().regex(SERVER_ORIGIN_PATTERN, 'url must be an http(s) origin, with no path'),
+    workspaceId: z.string().regex(TEAMS_ID_PATTERN, 'workspaceId must be a ULID'),
+    teamName: nonEmpty.optional(),
+    autoFetchSeconds: z.number().int().min(0).default(60),
+    commitOnSave: z.boolean().default(true),
+    pushOnSave: z.boolean().default(true),
+});
 /**
  * `share.yaml`: absent means a local workspace. `path`, when set, must be absolute — it is only
- * ever written from a native folder picker. `kind: 'git'` requires `git`; `kind: 'server'`
- * requires `server`.
+ * ever written from a native folder picker — and a server share has none, because its tree is
+ * always the managed `tree/`. `kind: 'git'` requires `git`; `kind: 'server'` requires `server`.
  */
 export const workspaceShareSchema = z
     .object({
@@ -84,7 +101,7 @@ export const workspaceShareSchema = z
         .optional()
         .refine((value) => value === undefined || isAbsolute(value), { message: 'path must be absolute' }),
     git: gitShareSettingsSchema.optional(),
-    server: z.object({ url: nonEmpty, workspaceId: nonEmpty }).optional(),
+    server: serverShareSettingsSchema.optional(),
 })
     .refine((value) => value.kind !== 'git' || value.git !== undefined, {
     message: 'kind: git requires a git block',
@@ -93,6 +110,10 @@ export const workspaceShareSchema = z
     .refine((value) => value.kind !== 'server' || value.server !== undefined, {
     message: 'kind: server requires a server block',
     path: ['server'],
+})
+    .refine((value) => value.kind !== 'server' || value.path === undefined, {
+    message: 'kind: server always uses the managed tree, so it takes no path',
+    path: ['path'],
 });
 /**
  * Validates `value` against `schema`, raising

package/dist/workspace/share.d.ts

@@ -12,38 +12,57 @@ import type { FsLike } from '../project/fs.js';
 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;
+/**
+ * The settings `SyncService` and the Sync panel read, whatever carries the sync: how often to
+ * fetch, and whether a save commits and pushes (server-sync spec §5.2).
+ */
+export interface SyncSettings {
     readonly autoFetchSeconds: number;
     readonly commitOnSave: boolean;
     readonly pushOnSave: boolean;
 }
+/** Defaults a freshly shared git or server workspace is given. */
+export declare const DEFAULT_SYNC_SETTINGS: SyncSettings;
+/** Git-specific share settings, all required once `kind: 'git'` is set (`remote` may still be unset). */
+export interface GitShareSettings extends SyncSettings {
+    readonly remote?: string;
+    readonly branch: string;
+}
 /** Defaults a freshly-shared git workspace is given. */
 export declare const DEFAULT_GIT_SHARE_SETTINGS: GitShareSettings;
+/** Wirebench Server share settings (server-sync spec §4.1). */
+export interface ServerShareSettings extends SyncSettings {
+    /** An http(s) origin, no path — written through the desktop's normalizeServerUrl. */
+    readonly url: string;
+    /** A ULID (TEAMS_ID_PATTERN); equals workspace.yaml's id. */
+    readonly workspaceId: string;
+    /** The team's name when shared or joined; display only. */
+    readonly teamName?: string;
+}
 /** `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/`. */
+    /** Absolute path to an externally managed clone/folder; absent means the managed `tree/`. Never set for `server`. */
     readonly path?: string;
     readonly git?: GitShareSettings;
-    readonly server?: {
-        readonly url: string;
-        readonly workspaceId: string;
-    };
+    readonly server?: ServerShareSettings;
 }
 /** Options shared by {@link loadShare}, {@link saveShare} and {@link deleteShare}. */
 export interface ShareOptions {
     readonly fs?: FsLike;
 }
+/**
+ * The sync settings of a git or server share, undefined for a folder share. Only the three shared
+ * fields are returned, so a caller cannot come to depend on one kind's extras.
+ */
+export declare function shareSyncSettings(share: WorkspaceShare): SyncSettings | undefined;
 /**
  * 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).
+ * does not match {@link workspaceShareSchema} (e.g. a relative `path`, `kind: 'git'` with no
+ * `git` block, or a server block whose `workspaceId` is not a ULID).
  */
 export declare function loadShare(dir: string, options?: ShareOptions): Promise<WorkspaceShare | undefined>;
 /** Writes `share` to `<dir>/share.yaml` atomically. */

package/dist/workspace/share.js

@@ -15,13 +15,28 @@ 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',
+/** Defaults a freshly shared git or server workspace is given. */
+export const DEFAULT_SYNC_SETTINGS = {
     autoFetchSeconds: 60,
     commitOnSave: true,
     pushOnSave: true,
 };
+/** Defaults a freshly-shared git workspace is given. */
+export const DEFAULT_GIT_SHARE_SETTINGS = {
+    ...DEFAULT_SYNC_SETTINGS,
+    branch: 'main',
+};
+/**
+ * The sync settings of a git or server share, undefined for a folder share. Only the three shared
+ * fields are returned, so a caller cannot come to depend on one kind's extras.
+ */
+export function shareSyncSettings(share) {
+    const block = share.kind === 'git' ? share.git : share.kind === 'server' ? share.server : undefined;
+    if (block === undefined) {
+        return undefined;
+    }
+    return { autoFetchSeconds: block.autoFetchSeconds, commitOnSave: block.commitOnSave, pushOnSave: block.pushOnSave };
+}
 function shareFile(dir) {
     return join(dir, WORKSPACE_SHARE_FILE);
 }
@@ -29,8 +44,8 @@ function shareFile(dir) {
  * 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).
+ * does not match {@link workspaceShareSchema} (e.g. a relative `path`, `kind: 'git'` with no
+ * `git` block, or a server block whose `workspaceId` is not a ULID).
  */
 export async function loadShare(dir, options) {
     const fs = options?.fs ?? nodeFs;
@@ -68,7 +83,18 @@ export async function loadShare(dir, options) {
                 },
             }
             : {}),
-        ...(parsed.server !== undefined ? { server: parsed.server } : {}),
+        ...(parsed.server !== undefined
+            ? {
+                server: {
+                    url: parsed.server.url,
+                    workspaceId: parsed.server.workspaceId,
+                    autoFetchSeconds: parsed.server.autoFetchSeconds,
+                    commitOnSave: parsed.server.commitOnSave,
+                    pushOnSave: parsed.server.pushOnSave,
+                    ...(parsed.server.teamName !== undefined ? { teamName: parsed.server.teamName } : {}),
+                },
+            }
+            : {}),
     };
 }
 /** Writes `share` to `<dir>/share.yaml` atomically. */

package/dist/ws/call.d.ts

@@ -9,7 +9,7 @@
  * 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 { SendAuth } from '../http/auth/send-auth.js';
 import type { ProxyOptions, TlsOptions } from '../http/types.js';
 import type { WsSessionOptions } from './session.js';
 import type { WsCallInput } from './expand.js';

package/dist/ws/call.js

@@ -9,7 +9,7 @@
  * 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 { applyAuth } from '../http/auth/apply-auth.js';
 import { WsError } from '../errors.js';
 import { resolveWsUrl } from './url.js';
 /**
@@ -63,7 +63,7 @@ function authHeadersAndQuery(auth) {
         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
+        // `http/auth/apply-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.

package/dist/ws/connect.d.ts

@@ -0,0 +1,60 @@
+import { WebSocket, type Dispatcher } from 'undici';
+import type { ProxyOptions, TlsOptions } from '../http/types.js';
+/** Options for {@link connectWebSocket}: the TLS and proxy settings an HTTP call to the same server gets. */
+export interface ConnectOptions {
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+}
+/** A socket from {@link connectWebSocket}, and what to call once finished with it. */
+export interface ConnectedWebSocket {
+    /** undici's WHATWG `WebSocket`, already connecting. */
+    readonly socket: WebSocket;
+    /**
+     * The HTTP status that refused the upgrade (e.g. `404` from a server without the endpoint), once the
+     * socket has failed without opening. `undefined` for an opened socket and for a network or TLS
+     * failure.
+     *
+     * The WHATWG API reports every refusal as the same bare `error`, so this is the only way a caller can
+     * tell "this server has no such endpoint" from "try again later". Two sockets opened to the same URL
+     * at the same moment could read each other's status; the live client keeps one socket per server.
+     */
+    refusedStatus(): number | undefined;
+    /**
+     * Closes the socket with `1000` if it is still connecting or open, and releases a dispatcher this
+     * call built. Idempotent (the same promise every time), and it never rejects.
+     */
+    dispose(): Promise<void>;
+}
+/** The transport options a WebSocket handshake's dispatcher is built from. */
+export interface WsTransportOptions {
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly localAddress?: string;
+}
+/** A handshake's dispatcher, and whether the caller owns (and so must close) it. */
+export interface WsDispatcher {
+    readonly dispatcher: Dispatcher;
+    readonly owned: boolean;
+}
+/**
+ * The dispatcher for one WebSocket handshake. It is shared by `openWsSession` and
+ * {@link connectWebSocket}, so the two can never reach a server differently.
+ *
+ * Why a proxied socket owns its own `ProxyAgent`: `createDispatcher({ proxy })` does not CONNECT-tunnel
+ * a WebSocket handshake. undici rewrites `ws:`/`wss:` to `http:`/`https:` before it dispatches, and
+ * `ProxyAgent` tunnels `http:` only when it is built with `proxyTunnel: true`.
+ *
+ * When an unproxied socket owns its dispatcher: only when it asked for TLS or bind-address options.
+ * With neither, `createDispatcher` hands back the shared keep-alive agent, which the caller must never
+ * close.
+ *
+ * Not part of the package's public surface: `index.ts` does not re-export it.
+ */
+export declare function wsDispatcher(options: WsTransportOptions): WsDispatcher;
+/**
+ * Opens `url` (`ws:` or `wss:`) through a dispatcher built from `options`.
+ *
+ * @throws WsError `ws-bad-options` for a URL or an option the constructor refuses. When it throws,
+ *   nothing is left subscribed or open.
+ */
+export declare function connectWebSocket(url: string, options?: ConnectOptions): ConnectedWebSocket;

package/dist/ws/connect.js

@@ -0,0 +1,131 @@
+/**
+ * A bare WebSocket with Wirebench's transport options (live-updates spec §5.2, R5), for a caller that
+ * speaks its own protocol over it: the desktop's live-updates client.
+ *
+ * Why not the WHATWG constructor: it takes no TLS or proxy options. A server trusted through
+ * Wirebench's CA bundle, or reached through the configured proxy, would then work over HTTP but never
+ * over the socket. undici's `WebSocket` takes a `dispatcher` instead, built here by
+ * {@link wsDispatcher}, the same function `openWsSession` uses.
+ *
+ * How it differs from `openWsSession`:
+ * - it records no frames and writes no History;
+ * - the socket is returned as is, and the caller owns its events;
+ * - the handshake carries no `Origin` and no credentials, so whatever authenticates the socket
+ *   travels in its first message (§6).
+ */
+import diagnosticsChannel from 'node:diagnostics_channel';
+import { ProxyAgent, WebSocket } from 'undici';
+import { WsError } from '../errors.js';
+import { createDispatcher, proxyAgentOptionsFor } from '../http/client.js';
+/**
+ * The dispatcher for one WebSocket handshake. It is shared by `openWsSession` and
+ * {@link connectWebSocket}, so the two can never reach a server differently.
+ *
+ * Why a proxied socket owns its own `ProxyAgent`: `createDispatcher({ proxy })` does not CONNECT-tunnel
+ * a WebSocket handshake. undici rewrites `ws:`/`wss:` to `http:`/`https:` before it dispatches, and
+ * `ProxyAgent` tunnels `http:` only when it is built with `proxyTunnel: true`.
+ *
+ * When an unproxied socket owns its dispatcher: only when it asked for TLS or bind-address options.
+ * With neither, `createDispatcher` hands back the shared keep-alive agent, which the caller must never
+ * close.
+ *
+ * Not part of the package's public surface: `index.ts` does not re-export it.
+ */
+export function wsDispatcher(options) {
+    const connect = {
+        ...(options.tls !== undefined ? { tls: options.tls } : {}),
+        ...(options.localAddress !== undefined ? { localAddress: options.localAddress } : {}),
+    };
+    if (options.proxy !== undefined) {
+        const agent = new ProxyAgent(proxyAgentOptionsFor(options.proxy, connect, false, { proxyTunnel: true }));
+        return { dispatcher: agent, owned: true };
+    }
+    return {
+        dispatcher: createDispatcher(connect),
+        owned: options.tls !== undefined || options.localAddress !== undefined,
+    };
+}
+/**
+ * The status in `message` (an `undici:request:headers` payload) when it answers this socket's own
+ * upgrade request: the request asked for `websocket`, and its origin, path and query are the socket's.
+ * undici hands a `101` to `onUpgrade` and never publishes it here, so any status seen here is a
+ * refusal.
+ */
+function refusalStatusFor(message, httpOrigin, pathAndSearch) {
+    const m = message;
+    if (m.request?.upgrade !== 'websocket' || m.request.path !== pathAndSearch)
+        return undefined;
+    const origin = typeof m.request.origin === 'string'
+        ? m.request.origin
+        : m.request.origin instanceof URL
+            ? m.request.origin.origin
+            : undefined;
+    if (origin !== httpOrigin)
+        return undefined;
+    return typeof m.response?.statusCode === 'number' ? m.response.statusCode : undefined;
+}
+/**
+ * Opens `url` (`ws:` or `wss:`) through a dispatcher built from `options`.
+ *
+ * @throws WsError `ws-bad-options` for a URL or an option the constructor refuses. When it throws,
+ *   nothing is left subscribed or open.
+ */
+export function connectWebSocket(url, options = {}) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch (err) {
+        throw new WsError('ws-bad-options', `"${url}" is not a valid URL`, { cause: err, details: { url } });
+    }
+    const httpOrigin = `${target.protocol === 'wss:' ? 'https:' : 'http:'}//${target.host}`;
+    const pathAndSearch = `${target.pathname}${target.search}`;
+    let refused;
+    const onResponseHeaders = (message) => {
+        refused ??= refusalStatusFor(message, httpOrigin, pathAndSearch);
+    };
+    const stopWatching = () => {
+        diagnosticsChannel.unsubscribe('undici:request:headers', onResponseHeaders);
+    };
+    let transport;
+    let socket;
+    try {
+        transport = wsDispatcher(options);
+        // Subscribed before the socket exists: undici starts the handshake inside the constructor.
+        diagnosticsChannel.subscribe('undici:request:headers', onResponseHeaders);
+        socket = new WebSocket(url, { dispatcher: transport.dispatcher });
+    }
+    catch (err) {
+        stopWatching();
+        if (transport?.owned === true)
+            void transport.dispatcher.close().catch(() => undefined);
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new WsError('ws-bad-options', `The WebSocket options for "${url}" are invalid: ${reason}`, {
+            cause: err,
+            details: { url },
+        });
+    }
+    // The handshake has an answer once any of these fires; nothing later can be this socket's refusal.
+    socket.addEventListener('open', stopWatching, { once: true });
+    socket.addEventListener('error', stopWatching, { once: true });
+    socket.addEventListener('close', stopWatching, { once: true });
+    const { dispatcher, owned } = transport;
+    const ws = socket;
+    let disposed;
+    return {
+        socket: ws,
+        refusedStatus: () => refused,
+        dispose() {
+            disposed ??= (async () => {
+                stopWatching();
+                // On a connecting socket this fails the handshake and aborts its request, so the graceful
+                // dispatcher close below has nothing in flight to wait for.
+                if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)
+                    ws.close(1000);
+                if (owned)
+                    await dispatcher.close().catch(() => undefined);
+            })();
+            return disposed;
+        },
+    };
+}

package/dist/ws/events.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What a WebSocket session reports while it runs (spec §3.2): the handshake once the server has
+ * switched protocols, each frame sent or received, and the session closed.
+ */
+import type { WsFrame, WsHandshake } from './model.js';
+export type WsLiveEvent = {
+    readonly protocol: 'websocket';
+    readonly kind: 'handshake';
+    readonly handshake: WsHandshake;
+} | {
+    readonly protocol: 'websocket';
+    readonly kind: 'frame';
+    readonly frame: WsFrame;
+} | {
+    readonly protocol: 'websocket';
+    readonly kind: 'closed';
+};

package/dist/ws/events.js

@@ -0,0 +1 @@
+export {};

package/dist/ws/expand.d.ts

@@ -10,7 +10,7 @@
  * 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 { KeyValueEntry } from '../http/entries.js';
 import type { WsRequestDef } from './model.js';
 /** Input to {@link expandWsInput}: the parts of a saved request an open call needs. */
 export interface WsCallInput {

package/dist/ws/expand.js

@@ -10,7 +10,7 @@
  * 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';
+import { escapeForLanguage } from '../http/escape.js';
 function runRows(rows, run) {
     return rows.map((row) => ({ ...row, name: run(row.name), value: run(row.value) }));
 }