@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/project/managed-files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which files of a request tree a save manages, and so may delete when it no longer writes them:
+ * the part of `save.ts` that every protocol keeping its requests under `apis/<slug>/requests/`
+ * shares, and that the webhook collection's tree uses too.
+ *
+ * One lister claims every sibling convention (`.body.<ext>`, `.msg-<slug>.<ext>`, the script
+ * files) whatever the API's protocol, exactly as it did when `save.ts` walked `apis/` itself.
+ */
+import type { FsLike } from './fs.js';
+/** The absolute path of a `/`-separated path relative to the project root. */
+export declare function toAbsolute(root: string, relative: string): string;
+/**
+ * True when `name` is a WebSocket request's saved-message sibling for `requestSlug`:
+ * `<requestSlug>.msg-<message-slug>.<ext>`, where `<ext>` is one `[A-Za-z0-9]+` run at the very
+ * end. Matched by trying the known `requestSlug` as a literal prefix — never by a greedy regex
+ * capture across the whole name — so a request slug that itself contains a dot or the literal text
+ * `.msg-` cannot be mis-split from the message slug that follows it.
+ */
+export declare function isWsMessageSibling(name: string, requestSlug: string): boolean;
+/**
+ * Lists the managed files inside one directory of an API's request tree: its `folder.yaml`, every
+ * `*.request.yaml`, and two conventions of per-request sibling file, each claimed only when it
+ * belongs to a request slug actually present in this directory:
+ *
+ * - `<slug>.body.<ext>` — a REST raw body or a gRPC message, one file for the whole request.
+ * - `<slug>.msg-<message-slug>.<ext>` — one WebSocket saved message, one file per message
+ *   ({@link isWsMessageSibling}).
+ * - `<slug>.pre.ts`, `<slug>.post.ts`, `<slug>.pre.js`, `<slug>.post.js` — a request's scripts (#63).
+ *
+ * Claiming only a sibling of a *known* request slug (rather than every file matching either
+ * pattern) means a hand-placed file — notes, a `.body.json` or `.msg-x.txt` with no matching
+ * request — is foreign and never a deletion candidate, exactly as in an operation folder.
+ */
+export declare function listApiTreeFiles(fs: FsLike, root: string, dir: string): Promise<string[]>;
+/** The managed files of one `apis/<slug>/`: its `api.yaml` when it is there, and its request tree. */
+export declare function apiManagedFiles(fs: FsLike, root: string, slug: string): Promise<string[]>;

package/dist/project/managed-files.js

@@ -0,0 +1,97 @@
+/**
+ * Which files of a request tree a save manages, and so may delete when it no longer writes them:
+ * the part of `save.ts` that every protocol keeping its requests under `apis/<slug>/requests/`
+ * shares, and that the webhook collection's tree uses too.
+ *
+ * One lister claims every sibling convention (`.body.<ext>`, `.msg-<slug>.<ext>`, the script
+ * files) whatever the API's protocol, exactly as it did when `save.ts` walked `apis/` itself.
+ */
+import { join } from 'node:path';
+import { isScriptFileOf } from '../script/model.js';
+import { readFileIfExists, readdirIfExists } from './fs.js';
+import { API_FILE, APIS_DIR, FOLDER_FILE, REQUEST_SUFFIX, REQUESTS_DIR } from './paths.js';
+/** The absolute path of a `/`-separated path relative to the project root. */
+export function toAbsolute(root, relative) {
+    return join(root, ...relative.split('/'));
+}
+/**
+ * True when `name` is a WebSocket request's saved-message sibling for `requestSlug`:
+ * `<requestSlug>.msg-<message-slug>.<ext>`, where `<ext>` is one `[A-Za-z0-9]+` run at the very
+ * end. Matched by trying the known `requestSlug` as a literal prefix — never by a greedy regex
+ * capture across the whole name — so a request slug that itself contains a dot or the literal text
+ * `.msg-` cannot be mis-split from the message slug that follows it.
+ */
+export function isWsMessageSibling(name, requestSlug) {
+    const prefix = `${requestSlug}.msg-`;
+    if (!name.startsWith(prefix)) {
+        return false;
+    }
+    const rest = name.slice(prefix.length);
+    const dot = rest.lastIndexOf('.');
+    // dot > 0 requires a non-empty message slug before the extension.
+    return dot > 0 && /^[A-Za-z0-9]+$/.test(rest.slice(dot + 1));
+}
+/**
+ * Lists the managed files inside one directory of an API's request tree: its `folder.yaml`, every
+ * `*.request.yaml`, and two conventions of per-request sibling file, each claimed only when it
+ * belongs to a request slug actually present in this directory:
+ *
+ * - `<slug>.body.<ext>` — a REST raw body or a gRPC message, one file for the whole request.
+ * - `<slug>.msg-<message-slug>.<ext>` — one WebSocket saved message, one file per message
+ *   ({@link isWsMessageSibling}).
+ * - `<slug>.pre.ts`, `<slug>.post.ts`, `<slug>.pre.js`, `<slug>.post.js` — a request's scripts (#63).
+ *
+ * Claiming only a sibling of a *known* request slug (rather than every file matching either
+ * pattern) means a hand-placed file — notes, a `.body.json` or `.msg-x.txt` with no matching
+ * request — is foreign and never a deletion candidate, exactly as in an operation folder.
+ */
+export async function listApiTreeFiles(fs, root, dir) {
+    const managed = [];
+    const entries = await readdirIfExists(fs, toAbsolute(root, dir));
+    const requestSlugs = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile) {
+            continue;
+        }
+        if (entry.name === FOLDER_FILE) {
+            managed.push(`${dir}/${entry.name}`);
+            continue;
+        }
+        if (entry.name.endsWith(REQUEST_SUFFIX)) {
+            requestSlugs.add(entry.name.slice(0, -REQUEST_SUFFIX.length));
+            managed.push(`${dir}/${entry.name}`);
+        }
+    }
+    for (const entry of entries) {
+        if (!entry.isFile) {
+            continue;
+        }
+        const body = /^(.*)\.body\.[A-Za-z0-9]+$/.exec(entry.name);
+        if (body !== null && requestSlugs.has(body[1])) {
+            managed.push(`${dir}/${entry.name}`);
+            continue;
+        }
+        for (const slug of requestSlugs) {
+            if (isWsMessageSibling(entry.name, slug) || isScriptFileOf(entry.name, slug)) {
+                managed.push(`${dir}/${entry.name}`);
+                break;
+            }
+        }
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory) {
+            managed.push(...(await listApiTreeFiles(fs, root, `${dir}/${entry.name}`)));
+        }
+    }
+    return managed;
+}
+/** The managed files of one `apis/<slug>/`: its `api.yaml` when it is there, and its request tree. */
+export async function apiManagedFiles(fs, root, slug) {
+    const base = `${APIS_DIR}/${slug}`;
+    const managed = [];
+    if ((await readFileIfExists(fs, toAbsolute(root, `${base}/${API_FILE}`))) !== undefined) {
+        managed.push(`${base}/${API_FILE}`);
+    }
+    managed.push(...(await listApiTreeFiles(fs, root, `${base}/${REQUESTS_DIR}`)));
+    return managed;
+}

package/dist/project/migrate.d.ts

@@ -16,8 +16,8 @@ type RawManifest = Record<string, unknown>;
  * with the current `formatVersion` so schema validation (which pins
  * `formatVersion` to a literal) accepts a document written by an older build.
  * The next save then writes the file back at the current version. Versions
- * 2 → 3 → 4 are the same kind of step: fields an older file simply lacks,
- * which the loader defaults.
+ * 2 → 3 → 4 → 5 → 6 are the same kind of step: fields an older file simply
+ * lacks, which the loader defaults.
  *
  * @throws ProjectError `project-format-too-new` when the file was written by a
  * newer Wirebench, `project-file-invalid` when `formatVersion` is missing,

package/dist/project/migrate.js

@@ -16,8 +16,8 @@ import { FORMAT_VERSION } from './model.js';
  * with the current `formatVersion` so schema validation (which pins
  * `formatVersion` to a literal) accepts a document written by an older build.
  * The next save then writes the file back at the current version. Versions
- * 2 → 3 → 4 are the same kind of step: fields an older file simply lacks,
- * which the loader defaults.
+ * 2 → 3 → 4 → 5 → 6 are the same kind of step: fields an older file simply
+ * lacks, which the loader defaults.
  *
  * @throws ProjectError `project-format-too-new` when the file was written by a
  * newer Wirebench, `project-file-invalid` when `formatVersion` is missing,

package/dist/project/model.d.ts

@@ -16,15 +16,24 @@ import type { WsaConfig } from '../wsa/model.js';
 import type { GrpcApi, GrpcRequestDef } from '../grpc/model.js';
 import type { RestApi, RestRequestDef } from '../rest/model.js';
 import type { WsApi, WsRequestDef } from '../ws/model.js';
+import type { SequenceDef } from '../sequence/model.js';
+import type { WebhookCollection } from '../webhooks/model.js';
+import type { ContainerBase, ContainerDir } from '../protocol/module.js';
+import type { RequestScripts } from '../script/model.js';
 export type { WsaConfig, WsaConfigPatch, WsaMustUnderstand, WsaVersion } from '../wsa/model.js';
 /**
  * The on-disk format version written to (and required by) `wirebench.yaml`.
  *
- * 4 added `assertions` on a request and the `…Env` name beside each secret reference. Both are
- * additive, and both still bump the version: this format does not round-trip unknown keys, so an
- * older build would delete them on its next save (see `schema.ts` and ADR-0003).
+ * 4 added `assertions` on a request and the `…Env` name beside each secret reference. 5 let a SOAP
+ * interface, endpoint or request carry `bearer`, `api-key` and `oauth2` auth (previously
+ * REST-only) — new keys and new enum values on an existing field. 6 added `scripts` on a SOAP, REST or
+ * gRPC request (#63), the project's webhook collection under `webhooks/`, `hook` on a request, `signing` on the
+ * collection, its folders and its items, the `callback` assertion kind (callback-assertion spec §2.1), and `assertions` on a WebSocket request (#192).
+ * 6 is not yet released, so these share it.
+ * All are additive; this format does not round-trip unknown keys, so an older build would delete them on
+ * its next save (see `schema.ts` and ADR-0003) — and would meanwhile send a request without its scripts.
  */
-export declare const FORMAT_VERSION = 4;
+export declare const FORMAT_VERSION = 6;
 /** A flat, ordered map of property name to value (project- or environment-scoped). */
 export type PropertyMap = Readonly<Record<string, string>>;
 /**
@@ -53,7 +62,7 @@ export interface EndpointAuth {
 /**
  * "Whatever the thing above me uses." Only a REST request or folder may say this; resolution
  * walks request → folder chain → API and takes the first configuration that is not `inherit`
- * (see `rest/auth.ts`).
+ * (see `http/auth/apply-auth.ts`).
  */
 export interface InheritAuth {
     readonly type: 'inherit';
@@ -116,6 +125,19 @@ export interface OAuth2Auth {
  * protocols.
  */
 export type AuthConfig = InheritAuth | EndpointAuth | BearerAuth | ApiKeyAuth | OAuth2Auth;
+/**
+ * What a SOAP interface, endpoint or request may hold: every {@link AuthConfig} arm except
+ * {@link InheritAuth} — a SOAP owner has no interface-like ancestor to inherit from, so the SOAP
+ * chain stays request → endpoint (override/complement) → interface.
+ */
+export type SoapOwnerAuth = Exclude<AuthConfig, InheritAuth>;
+/**
+ * How a definition document is fetched: Basic, a bearer token or an API key. Secrets are keychain
+ * references, as everywhere else. Separate from the API's own `auth`, which is what its requests send.
+ */
+export type DefinitionAuth = (EndpointAuth & {
+    readonly type: 'basic';
+}) | BearerAuth | ApiKeyAuth;
 /** The OAuth2 fields a freshly configured entry starts with. */
 export declare const DEFAULT_OAUTH2_AUTH: OAuth2Auth;
 /** One addressable endpoint (URL + optional credentials) of an interface. */
@@ -123,7 +145,7 @@ export interface Endpoint {
     readonly id: string;
     readonly name: string;
     readonly url: string;
-    readonly auth?: EndpointAuth;
+    readonly auth?: SoapOwnerAuth;
     /** `override` replaces request credentials, `complement` only fills in blanks. */
     readonly authMode: 'override' | 'complement';
     /**
@@ -225,7 +247,7 @@ export interface SoapRequestDef {
     readonly soapAction?: string;
     readonly headers: readonly HeaderEntry[];
     readonly attachments: readonly Attachment[];
-    readonly auth?: EndpointAuth;
+    readonly auth?: SoapOwnerAuth;
     readonly wsa?: WsaConfig;
     /** Name of a `wss/outgoing/<name>.yaml` configuration. */
     readonly wssOutgoingRef?: string;
@@ -241,14 +263,11 @@ export interface SoapRequestDef {
      * brings the operation back does.
      */
     readonly orphaned?: boolean;
+    /** Pre-request and post-response scripts, in files beside the request (#63). */
+    readonly scripts?: RequestScripts;
     /** Stored verbatim in the sibling `.xml` file, byte for byte. */
     readonly envelopeXml: string;
 }
-/**
- * The name this type had before REST requests existed, kept as an alias for one release so
- * callers that only ever mean a SOAP request need not be touched. Prefer {@link SoapRequestDef}.
- */
-export type RequestDef = SoapRequestDef;
 /**
  * A saved request of either protocol, which is what a lookup by request id can return: the id
  * space is one (ULIDs), so `kind` is how a caller finds out what it has.
@@ -278,7 +297,7 @@ export interface Interface {
     readonly defaultEndpointId?: string;
     readonly wsa: WsaConfig;
     /** Interface-level default credentials, overridable per endpoint and per request. */
-    readonly auth?: EndpointAuth;
+    readonly auth?: SoapOwnerAuth;
     readonly operations: readonly OperationDef[];
 }
 /** A named set of per-interface endpoint overrides and property values. */
@@ -325,6 +344,21 @@ export interface ProjectSettings {
 }
 /** The settings a new project starts with. */
 export declare const DEFAULT_PROJECT_SETTINGS: ProjectSettings;
+/**
+ * A container whose kind has no enabled module: kept on disk exactly as it is (spec §6).
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export interface UnsupportedContainer {
+    readonly dir: 'interfaces' | 'apis';
+    readonly slug: string;
+    /** As written in the container file. */
+    readonly kind: string;
+    readonly reason: 'unknown-kind' | 'feature-disabled';
+    /** Read from the container file when present, for a placeholder row. */
+    readonly name?: string;
+    readonly order?: number;
+}
 /** A whole Wirebench project, as loaded from (or saved to) a project folder. */
 export interface Project {
     readonly formatVersion: typeof FORMAT_VERSION;
@@ -354,6 +388,29 @@ export interface Project {
      * `order` is shared with all three.
      */
     readonly wsApis: readonly WsApi[];
+    /**
+     * Containers of a kind that has no list of its own above, keyed by kind. Absent means none.
+     * Read with {@link extraContainersOf}.
+     *
+     * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+     */
+    readonly extraContainers?: Readonly<Record<string, readonly ContainerBase[]>>;
+    /**
+     * Containers this build could not load and left untouched on disk. Absent means none.
+     *
+     * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+     */
+    readonly unsupported?: readonly UnsupportedContainer[];
+    /**
+     * The project's sequences, one file each under `sequences/`. Not a container like the four above: a
+     * sequence holds no requests of its own, only references to theirs by id.
+     */
+    readonly sequences: readonly SequenceDef[];
+    /**
+     * The project's webhook collection (spec `…-openapi-webhooks-import-design.md`), absent until the
+     * first webhook is created or imported. Not a list like the API containers: one per project.
+     */
+    readonly webhooks?: WebhookCollection;
     readonly environments: readonly Environment[];
     /** Id of the environment currently active for this project, if any. */
     readonly activeEnvironmentId?: string;
@@ -363,6 +420,27 @@ export interface Project {
         readonly keystores: readonly WssRef[];
     };
 }
+/**
+ * The project's placeholders; empty when it has none.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function unsupportedOf(project: Project): readonly UnsupportedContainer[];
+/**
+ * The project's containers of `kind` kept in {@link Project.extraContainers}.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function extraContainersOf(project: Project, kind: string): readonly ContainerBase[];
+/**
+ * Every slug in use under one of the two container directories: the containers the project holds
+ * there, and the placeholders (spec §6). A save keeps exactly these directories, whatever its
+ * registry can write. Hand it to `uniqueSlug` when naming a new container, so a save never has to
+ * refuse it with `container-slug-conflict`.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export declare function takenContainerSlugs(project: Project, dir: ContainerDir): ReadonlySet<string>;
 /** Generates entity ids; injectable so tests can produce deterministic projects. */
 export type IdGenerator = () => string;
 /** The default {@link IdGenerator}: a lexicographically sortable ULID. */
@@ -398,4 +476,4 @@ export interface CreateRequestInput extends CreateOptions {
     readonly properties?: Partial<RequestProperties>;
 }
 /** Creates a request with the default request properties applied. */
-export declare function createRequest(name: string, input: CreateRequestInput): RequestDef;
+export declare function createRequest(name: string, input: CreateRequestInput): SoapRequestDef;

package/dist/project/model.js

@@ -17,11 +17,16 @@ import { DEFAULT_WSA_CONFIG } from '../wsa/model.js';
 /**
  * The on-disk format version written to (and required by) `wirebench.yaml`.
  *
- * 4 added `assertions` on a request and the `…Env` name beside each secret reference. Both are
- * additive, and both still bump the version: this format does not round-trip unknown keys, so an
- * older build would delete them on its next save (see `schema.ts` and ADR-0003).
+ * 4 added `assertions` on a request and the `…Env` name beside each secret reference. 5 let a SOAP
+ * interface, endpoint or request carry `bearer`, `api-key` and `oauth2` auth (previously
+ * REST-only) — new keys and new enum values on an existing field. 6 added `scripts` on a SOAP, REST or
+ * gRPC request (#63), the project's webhook collection under `webhooks/`, `hook` on a request, `signing` on the
+ * collection, its folders and its items, the `callback` assertion kind (callback-assertion spec §2.1), and `assertions` on a WebSocket request (#192).
+ * 6 is not yet released, so these share it.
+ * All are additive; this format does not round-trip unknown keys, so an older build would delete them on
+ * its next save (see `schema.ts` and ADR-0003) — and would meanwhile send a request without its scripts.
  */
-export const FORMAT_VERSION = 4;
+export const FORMAT_VERSION = 6;
 /** The OAuth2 fields a freshly configured entry starts with. */
 export const DEFAULT_OAUTH2_AUTH = Object.freeze({
     type: 'oauth2',
@@ -62,6 +67,46 @@ export const DEFAULT_PROJECT_SETTINGS = Object.freeze({
     defaultTimeoutMs: 60_000,
     prettyPrintResponses: true,
 });
+/**
+ * The project's placeholders; empty when it has none.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function unsupportedOf(project) {
+    return project.unsupported ?? [];
+}
+/**
+ * The project's containers of `kind` kept in {@link Project.extraContainers}.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function extraContainersOf(project, kind) {
+    return project.extraContainers?.[kind] ?? [];
+}
+/**
+ * Every slug in use under one of the two container directories: the containers the project holds
+ * there, and the placeholders (spec §6). A save keeps exactly these directories, whatever its
+ * registry can write. Hand it to `uniqueSlug` when naming a new container, so a save never has to
+ * refuse it with `container-slug-conflict`.
+ *
+ * @internal Exported for the engine's own hosts; not yet a plugin API (ADR-0017).
+ */
+export function takenContainerSlugs(project, dir) {
+    const containers = dir === 'interfaces'
+        ? project.interfaces
+        : [
+            ...project.apis,
+            ...project.grpcApis,
+            ...project.wsApis,
+            ...Object.values(project.extraContainers ?? {}).flat(),
+        ];
+    return new Set([
+        ...containers.map((container) => container.slug),
+        ...unsupportedOf(project)
+            .filter((placeholder) => placeholder.dir === dir)
+            .map((placeholder) => placeholder.slug),
+    ]);
+}
 /** The default {@link IdGenerator}: a lexicographically sortable ULID. */
 export const generateId = () => ulid();
 function idOf(options) {
@@ -80,6 +125,7 @@ export function createProject(name, options) {
         apis: [],
         grpcApis: [],
         wsApis: [],
+        sequences: [],
         environments: [],
         wss: { outgoing: [], incoming: [], keystores: [] },
     };

package/dist/project/paths.d.ts

@@ -69,6 +69,15 @@ export declare const ATTACHMENTS_DIR = "attachments";
 export declare const REQUEST_SUFFIX = ".request.yaml";
 /** Directory holding every REST API, beside `interfaces/`. */
 export declare const APIS_DIR = "apis";
+/** Directory holding the project's webhook collection (`webhooks.yaml` and a `requests/` tree). */
+export declare const WEBHOOKS_DIR = "webhooks";
+/** File describing the webhook collection: its target and default credentials. */
+export declare const WEBHOOKS_FILE = "webhooks.yaml";
+/**
+ * The feature that also switches the webhook collection: it is REST requests in a tree of its own,
+ * so it is loaded and saved only while `rest` is on (spec §3.2).
+ */
+export declare const WEBHOOKS_FEATURE = "rest";
 /** Per-API directory holding the request tree: request files and folder directories. */
 export declare const REQUESTS_DIR = "requests";
 /** File naming a folder inside an API's request tree. */
@@ -94,7 +103,7 @@ export declare function interfaceFile(root: string, interfaceSlug: string): stri
 export declare function definitionDir(root: string, interfaceSlug: string): string;
 /**
  * Alias of {@link definitionDir} under the name the desktop facade (Task 21)
- * calls it by: the directory passed as `cache.dir` to `importDefinition`.
+ * calls it by: the directory passed as `cache.dir` to `importWsdl`.
  */
 export declare const definitionCacheDir: typeof definitionDir;
 /** Absolute path of an operation's directory. */

package/dist/project/paths.js

@@ -163,6 +163,15 @@ export const ATTACHMENTS_DIR = 'attachments';
 export const REQUEST_SUFFIX = '.request.yaml';
 /** Directory holding every REST API, beside `interfaces/`. */
 export const APIS_DIR = 'apis';
+/** Directory holding the project's webhook collection (`webhooks.yaml` and a `requests/` tree). */
+export const WEBHOOKS_DIR = 'webhooks';
+/** File describing the webhook collection: its target and default credentials. */
+export const WEBHOOKS_FILE = 'webhooks.yaml';
+/**
+ * The feature that also switches the webhook collection: it is REST requests in a tree of its own,
+ * so it is loaded and saved only while `rest` is on (spec §3.2).
+ */
+export const WEBHOOKS_FEATURE = 'rest';
 /** Per-API directory holding the request tree: request files and folder directories. */
 export const REQUESTS_DIR = 'requests';
 /** File naming a folder inside an API's request tree. */
@@ -196,7 +205,7 @@ export function definitionDir(root, interfaceSlug) {
 }
 /**
  * Alias of {@link definitionDir} under the name the desktop facade (Task 21)
- * calls it by: the directory passed as `cache.dir` to `importDefinition`.
+ * calls it by: the directory passed as `cache.dir` to `importWsdl`.
  */
 export const definitionCacheDir = definitionDir;
 /** Absolute path of an operation's directory. */

package/dist/project/preferences.d.ts

@@ -4,7 +4,7 @@
  *
  * Everything here is deliberately plain data — the engine never reads a file for it. The
  * desktop's `PreferencesService` loads/merges/persists a document; the engine consumes the
- * merged object (see `send-options.ts`).
+ * merged object (see `soap/send-input.ts`).
  *
  * Some sections are persisted and shown before they are wired to behaviour: `proxy` and `ssl`
  * become effective with the connection settings task.
@@ -173,6 +173,11 @@ export interface UpdatePreferences {
     /** Check GitHub Releases for a newer version once, shortly after the app starts. */
     readonly checkOnLaunch: boolean;
 }
+/** Account-related preferences. The account list itself lives elsewhere; this is display-only. */
+export interface AccountPreferences {
+    /** Whether the status bar shows the account item once a server is known. */
+    readonly showInStatusBar: boolean;
+}
 /** The whole preferences document. */
 export interface Preferences {
     readonly http: HttpPreferences;
@@ -185,6 +190,7 @@ export interface Preferences {
     readonly editor: EditorPreferences;
     readonly ui: UiPreferences;
     readonly updates: UpdatePreferences;
+    readonly accounts: AccountPreferences;
     /**
      * Keybinding overrides, keyed by command id: the chord that runs it, or `''` when the user
      * unbound it. Empty by default — a command with no entry uses its registered chord. Written
@@ -218,8 +224,8 @@ export declare const preferencesSchema: z.ZodObject<{
     proxy: z.ZodOptional<z.ZodObject<{
         mode: z.ZodOptional<z.ZodEnum<{
             none: "none";
-            manual: "manual";
             system: "system";
+            manual: "manual";
         }>>;
         host: z.ZodOptional<z.ZodString>;
         port: z.ZodOptional<z.ZodNumber>;
@@ -294,6 +300,9 @@ export declare const preferencesSchema: z.ZodObject<{
     updates: z.ZodOptional<z.ZodObject<{
         checkOnLaunch: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
+    accounts: z.ZodOptional<z.ZodObject<{
+        showInStatusBar: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
     shortcuts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 /** A partial preferences document, as accepted by {@link mergePreferences}. */

package/dist/project/preferences.js

@@ -4,7 +4,7 @@
  *
  * Everything here is deliberately plain data — the engine never reads a file for it. The
  * desktop's `PreferencesService` loads/merges/persists a document; the engine consumes the
- * merged object (see `send-options.ts`).
+ * merged object (see `soap/send-input.ts`).
  *
  * Some sections are persisted and shown before they are wired to behaviour: `proxy` and `ssl`
  * become effective with the connection settings task.
@@ -68,6 +68,7 @@ export const DEFAULT_PREFERENCES = Object.freeze({
         logSize: 500,
     }),
     updates: Object.freeze({ checkOnLaunch: false }),
+    accounts: Object.freeze({ showInStatusBar: true }),
     shortcuts: Object.freeze({}),
 });
 /**
@@ -158,6 +159,7 @@ export const preferencesSchema = z.object({
     })
         .optional(),
     updates: z.object({ checkOnLaunch: z.boolean().optional() }).optional(),
+    accounts: z.object({ showInStatusBar: z.boolean().optional() }).optional(),
     shortcuts: z.record(z.string(), z.string()).optional(),
 });
 /** Drops every `undefined` value so a patch never overwrites a default with nothing. */
@@ -210,6 +212,7 @@ export function mergePreferences(patch, base = DEFAULT_PREFERENCES) {
         editor: parseSection(shape.editor, root['editor']),
         ui: parseSection(shape.ui, root['ui']),
         updates: parseSection(shape.updates, root['updates']),
+        accounts: parseSection(shape.accounts, root['accounts']),
         shortcuts: parseSection(shape.shortcuts, root['shortcuts']),
     };
     return {
@@ -227,6 +230,7 @@ export function mergePreferences(patch, base = DEFAULT_PREFERENCES) {
             defaultLayout: mergeSection(base.ui.defaultLayout, value.ui?.defaultLayout),
         },
         updates: mergeSection(base.updates, value.updates),
+        accounts: mergeSection(base.accounts, value.accounts),
         shortcuts: { ...base.shortcuts, ...(value.shortcuts ?? {}) },
     };
 }

package/dist/project/properties.d.ts

@@ -7,11 +7,14 @@
  * unresolved expressions are left verbatim in the output and reported via
  * `unresolved`.
  *
+ * `${#Sequence#name}` is the exception: its values come from responses, so
+ * they are never expanded again, never reached by the shorthand, and never
+ * allowed to form another reference's name (ADR-0015).
+ *
  * Pure module: no I/O beyond reading the `scopes.system` map the caller
  * passes in (default `process.env`).
  */
 import type { PropertyMap } from './model.js';
-import type { SoapSendInput } from '../types.js';
 /** The property lookup scopes available to {@link expand}. */
 export interface PropertyScopes {
     readonly project: PropertyMap;
@@ -27,6 +30,19 @@ export interface PropertyScopes {
     readonly global: PropertyMap;
     /** Defaults to `process.env` when omitted. */
     readonly system?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Secret values keyed by name, for the `${secret:name}` token. Resolved by the caller (main
+     * from the keychain-backed store, the CLI from `WIREBENCH_SECRET_<NAME>`) and injected here so
+     * expansion itself stays synchronous and pure.
+     */
+    readonly secrets?: Readonly<Record<string, string>>;
+    /**
+     * Values a running sequence lifted out of earlier responses, for `${#Sequence#name}`. Text a
+     * server chose, so it is held to ADR-0015: substituted literally (never expanded again), reachable
+     * only by the explicit form (never by the `${name}` shorthand), and never allowed to name another
+     * reference.
+     */
+    readonly sequence?: PropertyMap;
 }
 /**
  * Filters `map` down to the entries not listed in `disabled`, preserving the map's key order.
@@ -44,7 +60,11 @@ export interface UnresolvedRef {
     readonly expr: string;
     readonly scope?: string;
     readonly name?: string;
-    readonly code: 'missing' | 'unknown-scope' | 'cycle' | 'too-deep' | 'malformed';
+    /**
+     * Why the reference stayed unexpanded. `name-from-response`: the reference's own name was built
+     * from a `${#Sequence#…}` value, so a server would be choosing which property (or secret) is read.
+     */
+    readonly code: 'missing' | 'unknown-scope' | 'cycle' | 'too-deep' | 'malformed' | 'name-from-response';
     /**
      * Offsets into the original text of the *outermost* `${...}` reference the user can see. When
      * this ref was discovered while recursively expanding a property's value (not the original
@@ -68,7 +88,7 @@ export interface ExpandResult {
         name: string;
     }[];
 }
-/** Options accepted by {@link expand} and {@link expandSendInput}. */
+/** Options accepted by {@link expand} and by `expandSendInput` in `soap/expand.ts`. */
 export interface ExpandOptions {
     readonly maxDepth?: number;
     /**
@@ -79,19 +99,13 @@ export interface ExpandOptions {
 }
 /** Expands every `${...}` property reference in `text` against `scopes`. */
 export declare function expand(text: string, scopes: PropertyScopes, options?: ExpandOptions): ExpandResult;
-/** True when `text` contains at least one (non-escaped) `${` sequence. */
-export declare function hasExpansions(text: string): boolean;
 /**
- * Expands the endpoint, envelope, soap action, and every header name/value of a
- * {@link SoapSendInput}. Header *names* are expanded too, so two headers whose names expand to
- * the same string collapse into one entry (last-write-wins, per `Object.entries` insertion
- * order — same as any other JS object key collision).
- *
- * Attachments are expanded as well, in the two places a property can reasonably appear: the
- * display/file name that ends up in `Content-Disposition`, and the path of a file-backed
- * attachment. Content-IDs are left alone — they are generated, not authored.
+ * The `secret:name` values reached from `text`: every `${secret:name}` token found directly, plus
+ * any reached by following `${name}` and `${#Scope#name}` property references whose stored value
+ * itself expands (or is) a secret token. Reuses the same tokenizer/lookup helpers as {@link expand},
+ * and is cycle-safe the same way (a visited `scope#name` is never revisited on a given path).
+ * `scopes` is optional — with none given, only literal `${secret:name}` tokens in `text` are found.
  */
-export declare function expandSendInput(input: SoapSendInput, scopes: PropertyScopes, options?: ExpandOptions): {
-    input: SoapSendInput;
-    unresolved: UnresolvedRef[];
-};
+export declare function secretNamesIn(text: string, scopes?: PropertyScopes): string[];
+/** True when `text` contains at least one (non-escaped) `${` sequence. */
+export declare function hasExpansions(text: string): boolean;