@wirebench/engine 2.1.1

package/dist/project/preferences.d.ts

@@ -0,0 +1,318 @@
+/**
+ * The application's global preferences: the settings that live with the *user*, not with a
+ * project, and are persisted by the desktop app in `userData/preferences.yaml`.
+ *
+ * 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`).
+ *
+ * Some sections are persisted and shown before they are wired to behaviour: `proxy` and `ssl`
+ * become effective with the connection settings task.
+ * They are modelled now so a preferences file written today survives those tasks unchanged.
+ */
+import { z } from 'zod';
+/** HTTP transport preferences applied to every send. */
+export interface HttpPreferences {
+    /** Reserved: only HTTP/1.1 is implemented. */
+    readonly version: '1.1';
+    /** `User-Agent` added to a request that does not set one itself. */
+    readonly userAgent: string;
+    /** `gzip` compresses the request body and sets `Content-Encoding: gzip`. */
+    readonly requestCompression: 'none' | 'gzip';
+    /** Advertise `Accept-Encoding: gzip, deflate` so servers may compress the response. */
+    readonly responseCompression: boolean;
+    /** Send `Connection: close` instead of reusing the keep-alive pool. */
+    readonly closeConnections: boolean;
+    /** Body size (bytes) above which chunked transfer would be used. Reserved. */
+    readonly chunkingThreshold: number;
+    /** Socket timeout used when neither the request nor the project sets one. */
+    readonly socketTimeoutMs: number;
+    /** Maximum simultaneous connections per host. Reserved. */
+    readonly maxConnections: number;
+    /**
+     * Offer HTTP/2 in the TLS ALPN handshake. Off by default: HTTP/2 changes what the raw view
+     * can faithfully reconstruct, and most SOAP stacks speak HTTP/1.1 only.
+     */
+    readonly allowH2: boolean;
+}
+/** Proxy preferences, consulted for every send by `resolveProxyFor`. */
+export interface ProxyPreferences {
+    readonly mode: 'none' | 'system' | 'manual';
+    readonly host?: string;
+    readonly port?: number;
+    readonly username?: string;
+    /** Opaque reference into the OS-keychain-backed secret store. Never a password. */
+    readonly passwordRef?: string;
+    /** Hosts that bypass the proxy. */
+    readonly excludes: readonly string[];
+}
+/** TLS preferences, folded into every send's `TlsOptions`. */
+export interface SslPreferences {
+    readonly minVersion: 'TLSv1.2' | 'TLSv1.3';
+    /** Absolute path to a PEM bundle of extra trust anchors; read in main, never by the engine. */
+    readonly caBundlePath?: string;
+    /**
+     * Set by the desktop main process when, and only when, {@link caBundlePath} came from a
+     * native file picker it ran itself. It is the evidence that the path was *chosen* rather than
+     * typed, pasted over IPC or edited into `preferences.yaml` by hand — and main re-records the
+     * path as a read pick at startup only when it is present, so a hand-edited file adds no trust
+     * until the bundle is picked again. Never settable through `preferences.update`.
+     */
+    readonly caBundlePickedByMain?: boolean;
+    /** Id of a `wss/keystores.yaml` entry used as the client identity when a request selects none. */
+    readonly clientKeystoreRef?: string;
+    /**
+     * Always `false`: trusting every certificate globally is not an option Wirebench offers.
+     * The only escape hatch is an endpoint's `trustInvalid`, which is badged in red wherever
+     * that endpoint appears.
+     */
+    readonly trustAll: false;
+}
+/** Git executable preferences, main-only, never settable through `preferences.update`. */
+export interface GitPreferences {
+    /** Absolute path to the `git` executable the desktop uses; read/written in main only. */
+    readonly path?: string;
+    /**
+     * Set by the desktop main process when, and only when, {@link path} came from a native file
+     * picker it ran itself (`git.locate`). Mirrors `SslPreferences.caBundlePickedByMain`: a
+     * hand-edited `preferences.yaml` gets no trust from this field until the path is picked
+     * again. Never settable through `preferences.update`.
+     */
+    readonly pathPickedByMain?: boolean;
+}
+/** WSDL import and request-generation preferences. */
+export interface WsdlPreferences {
+    /** Default `cacheDefinition` for a newly imported interface. */
+    readonly cacheDefinitions: boolean;
+    /** Pretty-print generated envelopes. */
+    readonly prettyPrint: boolean;
+    /** Fill generated leaves with sample values rather than `?` placeholders. */
+    readonly sampleValues: boolean;
+    /** Annotate generated elements with their schema type. */
+    readonly typeComments: boolean;
+    /** Include `minOccurs="0"` particles when generating. */
+    readonly includeOptional: boolean;
+    /** Treat schema problems as errors rather than warnings. */
+    readonly strictSchema: boolean;
+    /** Store cached definitions compressed. */
+    readonly compression: boolean;
+    /** Name a generated request after its binding as well as its operation. */
+    readonly nameWithBinding: boolean;
+}
+/**
+ * REST client preferences: the defaults every REST request inherits, and the two viewer limits.
+ *
+ * Redirects are followed by default here and not for SOAP, deliberately: a REST API that answers a
+ * `GET` with a 301 to its canonical URL is ordinary, while a redirected SOAP `POST` is a sign
+ * something is wrong (see the roadmap's note on the same-host upgrade case).
+ */
+export interface RestPreferences {
+    readonly followRedirects: boolean;
+    readonly maxRedirects: number;
+    /** Above this many bytes the response viewer stops offering the formatted view. */
+    readonly prettyPrintMaxBytes: number;
+    /** `Accept` added to a request that does not set one. Empty by default: say nothing, take anything. */
+    readonly defaultAccept: string;
+    /**
+     * Fixed loopback port for the OAuth2 authorization-code callback, for providers that demand an
+     * exact redirect URI. Absent means a random free port, which is what RFC 8252 §7.3 prefers.
+     */
+    readonly oauth2CallbackPort?: number;
+}
+/** WS-I Basic Profile validation preferences. */
+export interface WsiPreferences {
+    readonly verbose: boolean;
+    readonly profile: 'BP1.1';
+}
+/** Editor preferences, applied to every XML editor and to formatting. */
+export interface EditorPreferences {
+    readonly fontFamily?: string;
+    readonly fontSize: number;
+    /** Indentation width, also used as the pretty-printer's indent. */
+    readonly tabSize: number;
+    readonly lineNumbers: boolean;
+    readonly wordWrap: boolean;
+    /** Validate the envelope against the schema before sending. */
+    readonly autoValidateOnSend: boolean;
+    /** Pretty-print responses in the response pane. */
+    readonly autoFormatResponses: boolean;
+    /**
+     * Write a project's edits out on a short debounce instead of waiting to be told to.
+     *
+     * Off by default: an edit is the user's to commit, and a tool that writes to their project
+     * folder behind them is a tool they cannot experiment in. Closing a workspace and quitting
+     * still save whatever is outstanding — this chooses when routine edits land, not whether
+     * work can be lost.
+     */
+    readonly autosave: boolean;
+}
+/** How a request editor arranges its panes. Mirrors the renderer's layout snapshot. */
+export interface LayoutPreference {
+    readonly orientation: 'side-by-side' | 'stacked';
+    readonly mode: 'split' | 'tabs';
+}
+/** Shell/appearance preferences. */
+export interface UiPreferences {
+    readonly theme: 'dark' | 'light' | 'system';
+    readonly defaultLayout: LayoutPreference;
+    readonly confirmOnDelete: boolean;
+    /** How many history entries are kept per project. */
+    readonly historyCap: number;
+    /** How many rows the HTTP Log keeps in memory ({@link LOG_SIZE_MIN}–{@link LOG_SIZE_MAX}). */
+    readonly logSize: number;
+}
+/** The smallest HTTP Log row limit a user can set. */
+export declare const LOG_SIZE_MIN = 100;
+/** The largest HTTP Log row limit a user can set. */
+export declare const LOG_SIZE_MAX = 5000;
+/**
+ * Software-update preferences. `checkOnLaunch` is off by default and stays off until the user
+ * turns it on: Wirebench contacts the release feed when asked, not when started.
+ */
+export interface UpdatePreferences {
+    /** Check GitHub Releases for a newer version once, shortly after the app starts. */
+    readonly checkOnLaunch: boolean;
+}
+/** The whole preferences document. */
+export interface Preferences {
+    readonly http: HttpPreferences;
+    readonly proxy: ProxyPreferences;
+    readonly ssl: SslPreferences;
+    readonly git: GitPreferences;
+    readonly wsdl: WsdlPreferences;
+    readonly wsi: WsiPreferences;
+    readonly rest: RestPreferences;
+    readonly editor: EditorPreferences;
+    readonly ui: UiPreferences;
+    readonly updates: UpdatePreferences;
+    /**
+     * 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
+     * by the Shortcuts editor and read by the renderer's keybinding dispatcher.
+     */
+    readonly shortcuts: Readonly<Record<string, string>>;
+}
+/** The preferences a first run gets. */
+export declare const DEFAULT_PREFERENCES: Preferences;
+/**
+ * The persisted document shape. Deliberately loose: every section and every field is optional
+ * and unknown keys are stripped, so a file written by a newer build (or hand-edited badly)
+ * still loads — {@link mergePreferences} fills the gaps from {@link DEFAULT_PREFERENCES}.
+ */
+export declare const preferencesSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodLiteral<1>>;
+    http: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodLiteral<"1.1">>;
+        userAgent: z.ZodOptional<z.ZodString>;
+        requestCompression: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            gzip: "gzip";
+        }>>;
+        responseCompression: z.ZodOptional<z.ZodBoolean>;
+        closeConnections: z.ZodOptional<z.ZodBoolean>;
+        chunkingThreshold: z.ZodOptional<z.ZodNumber>;
+        socketTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        maxConnections: z.ZodOptional<z.ZodNumber>;
+        allowH2: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    proxy: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            system: "system";
+            manual: "manual";
+        }>>;
+        host: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        username: z.ZodOptional<z.ZodString>;
+        passwordRef: z.ZodOptional<z.ZodString>;
+        excludes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    ssl: z.ZodOptional<z.ZodObject<{
+        minVersion: z.ZodOptional<z.ZodEnum<{
+            "TLSv1.2": "TLSv1.2";
+            "TLSv1.3": "TLSv1.3";
+        }>>;
+        caBundlePath: z.ZodOptional<z.ZodString>;
+        caBundlePickedByMain: z.ZodOptional<z.ZodBoolean>;
+        clientKeystoreRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    git: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        pathPickedByMain: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    wsdl: z.ZodOptional<z.ZodObject<{
+        cacheDefinitions: z.ZodOptional<z.ZodBoolean>;
+        prettyPrint: z.ZodOptional<z.ZodBoolean>;
+        sampleValues: z.ZodOptional<z.ZodBoolean>;
+        typeComments: z.ZodOptional<z.ZodBoolean>;
+        includeOptional: z.ZodOptional<z.ZodBoolean>;
+        strictSchema: z.ZodOptional<z.ZodBoolean>;
+        compression: z.ZodOptional<z.ZodBoolean>;
+        nameWithBinding: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    wsi: z.ZodOptional<z.ZodObject<{
+        verbose: z.ZodOptional<z.ZodBoolean>;
+        profile: z.ZodOptional<z.ZodLiteral<"BP1.1">>;
+    }, z.core.$strip>>;
+    rest: z.ZodOptional<z.ZodObject<{
+        followRedirects: z.ZodOptional<z.ZodBoolean>;
+        maxRedirects: z.ZodOptional<z.ZodNumber>;
+        prettyPrintMaxBytes: z.ZodOptional<z.ZodNumber>;
+        defaultAccept: z.ZodOptional<z.ZodString>;
+        oauth2CallbackPort: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    editor: z.ZodOptional<z.ZodObject<{
+        fontFamily: z.ZodOptional<z.ZodString>;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        tabSize: z.ZodOptional<z.ZodNumber>;
+        lineNumbers: z.ZodOptional<z.ZodBoolean>;
+        wordWrap: z.ZodOptional<z.ZodBoolean>;
+        autoValidateOnSend: z.ZodOptional<z.ZodBoolean>;
+        autoFormatResponses: z.ZodOptional<z.ZodBoolean>;
+        autosave: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    ui: z.ZodOptional<z.ZodObject<{
+        theme: z.ZodOptional<z.ZodEnum<{
+            system: "system";
+            dark: "dark";
+            light: "light";
+        }>>;
+        defaultLayout: z.ZodOptional<z.ZodObject<{
+            orientation: z.ZodOptional<z.ZodEnum<{
+                "side-by-side": "side-by-side";
+                stacked: "stacked";
+            }>>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                split: "split";
+                tabs: "tabs";
+            }>>;
+        }, z.core.$strip>>;
+        confirmOnDelete: z.ZodOptional<z.ZodBoolean>;
+        historyCap: z.ZodOptional<z.ZodNumber>;
+        logSize: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    updates: z.ZodOptional<z.ZodObject<{
+        checkOnLaunch: 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}. */
+export type PreferencesPatch = z.infer<typeof preferencesSchema>;
+/**
+ * Deep-merges `patch` onto `base` (default {@link DEFAULT_PREFERENCES}), one level per
+ * section. Unknown keys are ignored (the schema strips them), `undefined` values leave the
+ * base value alone, and `trustAll` is pinned to `false` regardless of what a file claims.
+ *
+ * Each top-level section is parsed independently, so a bad field in (say) `wsdl` only loses
+ * `wsdl` — every other section of the same patch still applies. Parsing the whole document in
+ * one shot would instead discard the entire patch the moment any single field anywhere in it
+ * failed to validate, which is worse than doing nothing with the parts that were fine.
+ *
+ * @param patch a parsed (or raw) partial preferences document
+ * @param base the preferences to merge onto; defaults to the built-in defaults
+ */
+export declare function mergePreferences(patch: unknown, base?: Preferences): Preferences;
+/** The section names a "Reset section" action addresses. */
+export type PreferencesSection = keyof Preferences;
+/** Restores one section (or, with no section, everything) to {@link DEFAULT_PREFERENCES}. */
+export declare function resetPreferences(current: Preferences, section?: PreferencesSection): Preferences;

package/dist/project/preferences.js

@@ -0,0 +1,239 @@
+/**
+ * The application's global preferences: the settings that live with the *user*, not with a
+ * project, and are persisted by the desktop app in `userData/preferences.yaml`.
+ *
+ * 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`).
+ *
+ * Some sections are persisted and shown before they are wired to behaviour: `proxy` and `ssl`
+ * become effective with the connection settings task.
+ * They are modelled now so a preferences file written today survives those tasks unchanged.
+ */
+import { z } from 'zod';
+/** The smallest HTTP Log row limit a user can set. */
+export const LOG_SIZE_MIN = 100;
+/** The largest HTTP Log row limit a user can set. */
+export const LOG_SIZE_MAX = 5000;
+function clampLogSize(value) {
+    return Math.min(LOG_SIZE_MAX, Math.max(LOG_SIZE_MIN, Math.round(value)));
+}
+/** The preferences a first run gets. */
+export const DEFAULT_PREFERENCES = Object.freeze({
+    http: Object.freeze({
+        version: '1.1',
+        userAgent: 'Wirebench/0.1',
+        requestCompression: 'none',
+        responseCompression: true,
+        closeConnections: false,
+        chunkingThreshold: 0,
+        socketTimeoutMs: 60_000,
+        maxConnections: 100,
+        allowH2: false,
+    }),
+    proxy: Object.freeze({ mode: 'none', excludes: Object.freeze([]) }),
+    ssl: Object.freeze({ minVersion: 'TLSv1.2', trustAll: false }),
+    git: Object.freeze({}),
+    wsdl: Object.freeze({
+        cacheDefinitions: true,
+        prettyPrint: true,
+        sampleValues: false,
+        typeComments: false,
+        includeOptional: true,
+        strictSchema: false,
+        compression: false,
+        nameWithBinding: false,
+    }),
+    wsi: Object.freeze({ verbose: false, profile: 'BP1.1' }),
+    rest: Object.freeze({
+        followRedirects: true,
+        maxRedirects: 5,
+        prettyPrintMaxBytes: 5 * 1024 * 1024,
+        defaultAccept: '',
+    }),
+    editor: Object.freeze({
+        fontSize: 13,
+        tabSize: 3,
+        lineNumbers: true,
+        wordWrap: false,
+        autoValidateOnSend: false,
+        autoFormatResponses: true,
+        autosave: false,
+    }),
+    ui: Object.freeze({
+        theme: 'dark',
+        defaultLayout: Object.freeze({ orientation: 'side-by-side', mode: 'split' }),
+        confirmOnDelete: true,
+        historyCap: 1000,
+        logSize: 500,
+    }),
+    updates: Object.freeze({ checkOnLaunch: false }),
+    shortcuts: Object.freeze({}),
+});
+/**
+ * The persisted document shape. Deliberately loose: every section and every field is optional
+ * and unknown keys are stripped, so a file written by a newer build (or hand-edited badly)
+ * still loads — {@link mergePreferences} fills the gaps from {@link DEFAULT_PREFERENCES}.
+ */
+export const preferencesSchema = z.object({
+    version: z.literal(1).optional(),
+    http: z
+        .object({
+        version: z.literal('1.1').optional(),
+        userAgent: z.string().optional(),
+        requestCompression: z.enum(['none', 'gzip']).optional(),
+        responseCompression: z.boolean().optional(),
+        closeConnections: z.boolean().optional(),
+        chunkingThreshold: z.number().optional(),
+        socketTimeoutMs: z.number().optional(),
+        maxConnections: z.number().optional(),
+        allowH2: z.boolean().optional(),
+    })
+        .optional(),
+    proxy: z
+        .object({
+        mode: z.enum(['none', 'system', 'manual']).optional(),
+        host: z.string().optional(),
+        port: z.number().optional(),
+        username: z.string().optional(),
+        passwordRef: z.string().optional(),
+        excludes: z.array(z.string()).optional(),
+    })
+        .optional(),
+    ssl: z
+        .object({
+        minVersion: z.enum(['TLSv1.2', 'TLSv1.3']).optional(),
+        caBundlePath: z.string().optional(),
+        caBundlePickedByMain: z.boolean().optional(),
+        clientKeystoreRef: z.string().optional(),
+    })
+        .optional(),
+    git: z.object({ path: z.string().optional(), pathPickedByMain: z.boolean().optional() }).optional(),
+    wsdl: z
+        .object({
+        cacheDefinitions: z.boolean().optional(),
+        prettyPrint: z.boolean().optional(),
+        sampleValues: z.boolean().optional(),
+        typeComments: z.boolean().optional(),
+        includeOptional: z.boolean().optional(),
+        strictSchema: z.boolean().optional(),
+        compression: z.boolean().optional(),
+        nameWithBinding: z.boolean().optional(),
+    })
+        .optional(),
+    wsi: z.object({ verbose: z.boolean().optional(), profile: z.literal('BP1.1').optional() }).optional(),
+    rest: z
+        .object({
+        followRedirects: z.boolean().optional(),
+        maxRedirects: z.number().int().nonnegative().optional(),
+        prettyPrintMaxBytes: z.number().int().positive().optional(),
+        defaultAccept: z.string().optional(),
+        oauth2CallbackPort: z.number().int().min(1024).max(65_535).optional(),
+    })
+        .optional(),
+    editor: z
+        .object({
+        fontFamily: z.string().optional(),
+        fontSize: z.number().optional(),
+        tabSize: z.number().optional(),
+        lineNumbers: z.boolean().optional(),
+        wordWrap: z.boolean().optional(),
+        autoValidateOnSend: z.boolean().optional(),
+        autoFormatResponses: z.boolean().optional(),
+        autosave: z.boolean().optional(),
+    })
+        .optional(),
+    ui: z
+        .object({
+        theme: z.enum(['dark', 'light', 'system']).optional(),
+        defaultLayout: z
+            .object({
+            orientation: z.enum(['side-by-side', 'stacked']).optional(),
+            mode: z.enum(['split', 'tabs']).optional(),
+        })
+            .optional(),
+        confirmOnDelete: z.boolean().optional(),
+        historyCap: z.number().optional(),
+        logSize: z.number().finite().optional(),
+    })
+        .optional(),
+    updates: z.object({ checkOnLaunch: 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. */
+function defined(value) {
+    const out = {};
+    for (const [key, entry] of Object.entries(value ?? {})) {
+        if (entry !== undefined) {
+            out[key] = entry;
+        }
+    }
+    return out;
+}
+/**
+ * Overlays the defined fields of `patch` onto `base`. The cast is sound because the schema has
+ * already validated every value it let through, and TypeScript cannot express "the same keys,
+ * each optional but never `undefined`" for a spread under `exactOptionalPropertyTypes`.
+ */
+function mergeSection(base, patch) {
+    return { ...base, ...defined(patch) };
+}
+/** Parses one top-level section's raw value against its own schema; `undefined` on any failure. */
+function parseSection(schema, raw) {
+    const parsed = schema.safeParse(raw);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Deep-merges `patch` onto `base` (default {@link DEFAULT_PREFERENCES}), one level per
+ * section. Unknown keys are ignored (the schema strips them), `undefined` values leave the
+ * base value alone, and `trustAll` is pinned to `false` regardless of what a file claims.
+ *
+ * Each top-level section is parsed independently, so a bad field in (say) `wsdl` only loses
+ * `wsdl` — every other section of the same patch still applies. Parsing the whole document in
+ * one shot would instead discard the entire patch the moment any single field anywhere in it
+ * failed to validate, which is worse than doing nothing with the parts that were fine.
+ *
+ * @param patch a parsed (or raw) partial preferences document
+ * @param base the preferences to merge onto; defaults to the built-in defaults
+ */
+export function mergePreferences(patch, base = DEFAULT_PREFERENCES) {
+    const root = typeof patch === 'object' && patch !== null ? patch : {};
+    const shape = preferencesSchema.shape;
+    const value = {
+        http: parseSection(shape.http, root['http']),
+        proxy: parseSection(shape.proxy, root['proxy']),
+        ssl: parseSection(shape.ssl, root['ssl']),
+        git: parseSection(shape.git, root['git']),
+        wsdl: parseSection(shape.wsdl, root['wsdl']),
+        wsi: parseSection(shape.wsi, root['wsi']),
+        rest: parseSection(shape.rest, root['rest']),
+        editor: parseSection(shape.editor, root['editor']),
+        ui: parseSection(shape.ui, root['ui']),
+        updates: parseSection(shape.updates, root['updates']),
+        shortcuts: parseSection(shape.shortcuts, root['shortcuts']),
+    };
+    return {
+        http: mergeSection(base.http, value.http),
+        proxy: mergeSection(base.proxy, value.proxy),
+        ssl: { ...mergeSection(base.ssl, value.ssl), trustAll: false },
+        git: mergeSection(base.git, value.git),
+        wsdl: mergeSection(base.wsdl, value.wsdl),
+        wsi: mergeSection(base.wsi, value.wsi),
+        rest: mergeSection(base.rest, value.rest),
+        editor: mergeSection(base.editor, value.editor),
+        ui: {
+            ...mergeSection(base.ui, value.ui),
+            logSize: clampLogSize(value.ui?.logSize ?? base.ui.logSize),
+            defaultLayout: mergeSection(base.ui.defaultLayout, value.ui?.defaultLayout),
+        },
+        updates: mergeSection(base.updates, value.updates),
+        shortcuts: { ...base.shortcuts, ...(value.shortcuts ?? {}) },
+    };
+}
+/** Restores one section (or, with no section, everything) to {@link DEFAULT_PREFERENCES}. */
+export function resetPreferences(current, section) {
+    if (section === undefined) {
+        return DEFAULT_PREFERENCES;
+    }
+    return { ...current, [section]: DEFAULT_PREFERENCES[section] };
+}

package/dist/project/properties.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Property expansion over the `${#Project#name}`, `${#Env#name}`,
+ * `${#Workspace#name}`, `${#Global#name}` and `${#System#name}` syntax, plus
+ * the shorthand `${name}` which resolves through the scope chain
+ * Env -> Project -> Workspace -> Global (System is never implicit). Values
+ * are themselves expanded recursively (cycle-safe, depth limited);
+ * unresolved expressions are left verbatim in the output and reported via
+ * `unresolved`.
+ *
+ * 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;
+    readonly env?: PropertyMap;
+    /** Workspace-level properties, when expanding within a workspace. */
+    readonly workspace?: PropertyMap;
+    /**
+     * Global properties. Unlike the other scopes, globals have no `disabledProperties` list of
+     * their own in this package (they are not part of `Project`/`Workspace`) — a caller that wants
+     * disabled globals excluded from resolution must filter this map itself (with
+     * {@link enabledProperties}, say) before passing it in.
+     */
+    readonly global: PropertyMap;
+    /** Defaults to `process.env` when omitted. */
+    readonly system?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Filters `map` down to the entries not listed in `disabled`, preserving the map's key order.
+ * Used to make property resolution treat a disabled property as absent (its value stays on disk,
+ * see `Environment.disabledProperties`) without mutating the stored map itself.
+ */
+export declare function enabledProperties(map: PropertyMap, disabled: readonly string[]): PropertyMap;
+/** One `${...}` expression that could not be resolved, with offsets into the original text. */
+export interface UnresolvedRef {
+    /**
+     * The `${...}` expression text (or the unterminated `${` for a `malformed` ref). When this
+     * ref was found while expanding a property's VALUE (see `via`), this is the inner expression
+     * text, not the outer reference the user typed — use `start`/`end` for the user-visible span.
+     */
+    readonly expr: string;
+    readonly scope?: string;
+    readonly name?: string;
+    readonly code: 'missing' | 'unknown-scope' | 'cycle' | 'too-deep' | 'malformed';
+    /**
+     * 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
+     * text directly), these are the outer reference's offsets, not offsets into that value string.
+     */
+    readonly start: number;
+    readonly end: number;
+    /**
+     * The chain of `scope#name` properties traversed to reach this ref, outermost first. Present
+     * only when this ref was found while expanding a property's value (i.e. it is nested at least
+     * one level below the outer reference at `start`/`end`).
+     */
+    readonly via?: readonly string[];
+}
+/** The result of expanding a string: the expanded text plus any problems and properties used. */
+export interface ExpandResult {
+    readonly text: string;
+    readonly unresolved: readonly UnresolvedRef[];
+    readonly used: readonly {
+        scope: string;
+        name: string;
+    }[];
+}
+/** Options accepted by {@link expand} and {@link expandSendInput}. */
+export interface ExpandOptions {
+    readonly maxDepth?: number;
+    /**
+     * XML-escape every substituted value ("Entitize Properties"). Off by default; the
+     * send path turns it on only for the envelope, never for headers or the endpoint.
+     */
+    readonly entitize?: boolean;
+}
+/** 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.
+ */
+export declare function expandSendInput(input: SoapSendInput, scopes: PropertyScopes, options?: ExpandOptions): {
+    input: SoapSendInput;
+    unresolved: UnresolvedRef[];
+};