@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/project/properties.js

@@ -7,10 +7,15 @@
  * 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 { entitizeValue } from '../soap/transforms.js';
+import { entitizeValue } from '../xml/entitize.js';
+import { SECRET_NAME_PATTERN } from '../secrets/secret-token.js';
 /**
  * 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,
@@ -30,7 +35,7 @@ export function enabledProperties(map, disabled) {
     return result;
 }
 const DEFAULT_MAX_DEPTH = 8;
-const SCOPE_NAMES = new Set(['Project', 'Env', 'Workspace', 'Global', 'System']);
+const SCOPE_NAMES = new Set(['Project', 'Env', 'Workspace', 'Global', 'System', 'Sequence']);
 /** Parses the inside of `${...}` (without the delimiters) into a scope + name. */
 function parseExpr(inner) {
     if (inner.startsWith('#')) {
@@ -43,6 +48,9 @@ function parseExpr(inner) {
             }
         }
     }
+    if (inner.startsWith('secret:')) {
+        return { scope: 'Secret', name: inner.slice('secret:'.length) };
+    }
     return { scope: undefined, name: inner };
 }
 function lookupInScope(scope, name, scopes) {
@@ -57,6 +65,10 @@ function lookupInScope(scope, name, scopes) {
             return scopes.global[name];
         case 'System':
             return (scopes.system ?? process.env)[name];
+        case 'Sequence':
+            return scopes.sequence !== undefined && Object.hasOwn(scopes.sequence, name) ? scopes.sequence[name] : undefined;
+        case 'Secret':
+            return SECRET_NAME_PATTERN.test(name) ? scopes.secrets?.[name] : undefined;
         default:
             return undefined;
     }
@@ -149,10 +161,12 @@ function pushUnresolved(ctx, outer, via, entry) {
 /**
  * The text a resolved reference contributes to the output. When entitizing is on, the value is
  * XML-escaped — but only at the outermost reference (`outer === undefined`), so a property whose
- * value itself expands another property is escaped once rather than once per nesting level.
+ * value itself expands another property is escaped once rather than once per nesting level. A
+ * `${secret:name}` token (`scope` `Secret`) is never escaped itself: its value goes out exactly as
+ * it was stored, which for one moved out of an envelope is XML text already.
  */
-function substituted(ctx, outer, value) {
-    return ctx.entitize && outer === undefined ? entitizeValue(value) : value;
+function substituted(ctx, outer, value, scope) {
+    return ctx.entitize && outer === undefined && scope !== 'Secret' ? entitizeValue(value) : value;
 }
 /**
  * Expands all `${...}` expressions in `text` at `depth`, tracking an active-resolution stack for
@@ -182,7 +196,19 @@ function expandAt(text, depth, stack, ctx, outer, via) {
         // The span/chain to attribute anything found from here on down (this token's own span, unless already nested).
         const effectiveOuter = outer ?? { start: token.start, end: token.end };
         // The inner text of the expression may itself contain expressions (nesting); expand those first.
+        const usedBefore = ctx.used.length;
         const resolvedInner = expandAt(token.inner, depth + 1, stack, ctx, effectiveOuter, via);
+        if (ctx.used.slice(usedBefore).some((entry) => entry.scope === 'Sequence')) {
+            // `${${#Sequence#n}}`: a response value would pick the reference, `secret:…` included.
+            pushUnresolved(ctx, outer, via, {
+                expr: token.raw,
+                code: 'name-from-response',
+                start: token.start,
+                end: token.end,
+            });
+            out += token.raw;
+            continue;
+        }
         const { scope, name } = parseExpr(resolvedInner);
         if (scope !== undefined) {
             const key = `${scope}#${name}`;
@@ -212,7 +238,13 @@ function expandAt(text, depth, stack, ctx, outer, via) {
                 continue;
             }
             ctx.used.push({ scope, name });
-            out += substituted(ctx, outer, expandAt(value, depth + 1, [...stack, key], ctx, effectiveOuter, [...via, key]));
+            if (scope === 'Sequence') {
+                // Literal: the value came from a response, and expanding it would let a server name any
+                // property or secret for the next request to carry back (ADR-0015).
+                out += substituted(ctx, outer, value, scope);
+                continue;
+            }
+            out += substituted(ctx, outer, expandAt(value, depth + 1, [...stack, key], ctx, effectiveOuter, [...via, key]), scope);
             continue;
         }
         // Shorthand: check it's not referencing an unknown explicit scope form like `${#Foo#x}`.
@@ -277,6 +309,57 @@ export function expand(text, scopes, options) {
     });
     return { text: out, unresolved: ctx.unresolved, used };
 }
+/**
+ * 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 function secretNamesIn(text, scopes) {
+    const found = new Set();
+    function visit(current, stack, depth) {
+        if (depth > DEFAULT_MAX_DEPTH) {
+            return;
+        }
+        for (const token of tokenize(current)) {
+            if (token.kind !== 'expr') {
+                continue;
+            }
+            const { scope, name } = parseExpr(token.inner);
+            if (scope === 'Secret') {
+                if (SECRET_NAME_PATTERN.test(name)) {
+                    found.add(name);
+                }
+                continue;
+            }
+            // A Sequence value is substituted literally, so a `${secret:…}` inside one is never resolved.
+            if (scopes === undefined || scope === 'Sequence') {
+                continue;
+            }
+            let value;
+            let key;
+            if (scope !== undefined) {
+                value = lookupInScope(scope, name, scopes);
+                key = `${scope}#${name}`;
+            }
+            else {
+                const shorthand = lookupShorthand(name, scopes);
+                if (shorthand === undefined) {
+                    continue;
+                }
+                value = shorthand.value;
+                key = `${shorthand.scope}#${name}`;
+            }
+            if (value === undefined || stack.includes(key)) {
+                continue;
+            }
+            visit(value, [...stack, key], depth + 1);
+        }
+    }
+    visit(text, [], 0);
+    return [...found];
+}
 /** True when `text` contains at least one (non-escaped) `${` sequence. */
 export function hasExpansions(text) {
     for (let i = 0; i < text.length; i++) {
@@ -290,67 +373,3 @@ export function hasExpansions(text) {
     }
     return false;
 }
-/**
- * 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 function expandSendInput(input, scopes, options) {
-    const unresolved = [];
-    function run(text, entitize = false) {
-        const result = expand(text, scopes, { ...options, entitize });
-        unresolved.push(...result.unresolved);
-        return result.text;
-    }
-    const endpoint = run(input.endpoint);
-    // Only the envelope is entitized: escaping a header value or an endpoint would corrupt it.
-    const envelopeXml = run(input.envelopeXml, options?.entitize ?? input.entitize ?? false);
-    const soapAction = input.soapAction !== undefined ? run(input.soapAction) : undefined;
-    let headers;
-    if (input.headers !== undefined) {
-        headers = {};
-        for (const [name, value] of Object.entries(input.headers)) {
-            headers[run(name)] = run(value);
-        }
-    }
-    const attachments = input.attachments?.map((attachment) => ({
-        ...attachment,
-        name: run(attachment.name),
-        source: attachment.source.kind === 'path'
-            ? { kind: 'path', path: run(attachment.source.path) }
-            : attachment.source,
-    }));
-    // The explicit WS-Addressing fields are user-typed strings just like the endpoint or a
-    // header value, and may carry the same `${#Env#…}`/`${#Global#…}` references — so they go
-    // through the same scopes rather than reaching the wire verbatim.
-    const wsa = input.wsa !== undefined
-        ? {
-            ...input.wsa,
-            config: {
-                ...input.wsa.config,
-                ...(input.wsa.config.to !== undefined ? { to: run(input.wsa.config.to) } : {}),
-                ...(input.wsa.config.action !== undefined ? { action: run(input.wsa.config.action) } : {}),
-                ...(input.wsa.config.replyTo !== undefined ? { replyTo: run(input.wsa.config.replyTo) } : {}),
-                ...(input.wsa.config.from !== undefined ? { from: run(input.wsa.config.from) } : {}),
-                ...(input.wsa.config.faultTo !== undefined ? { faultTo: run(input.wsa.config.faultTo) } : {}),
-            },
-        }
-        : undefined;
-    return {
-        input: {
-            ...input,
-            endpoint,
-            envelopeXml,
-            ...(soapAction !== undefined ? { soapAction } : {}),
-            ...(headers !== undefined ? { headers } : {}),
-            ...(attachments !== undefined ? { attachments } : {}),
-            ...(wsa !== undefined ? { wsa } : {}),
-        },
-        unresolved,
-    };
-}

package/dist/project/request-location.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Finds where a request's files live on disk, so a caller (the desktop main process, for a
+ * `<slug>.golden.yaml` snapshot sidecar) can place a file beside them without re-deriving the
+ * layout `serialize.ts` already owns.
+ */
+import type { Project } from './model.js';
+/** Where a request's files live: `dir` and `slug` such that `${dir}/${slug}.request.yaml` is a project file. */
+export interface RequestFileLocation {
+    /** POSIX path, relative to the project root. */
+    readonly dir: string;
+    readonly slug: string;
+}
+/**
+ * Locates the request identified by `requestId`: the folder it lives under and its file slug.
+ *
+ * Only SOAP, REST and webhook requests have file locations today — a gRPC or WebSocket request, or
+ * an unknown id, returns `undefined`. `dir` and `slug` are derived the same way `serialize.ts`
+ * builds its keys, so `${dir}/${slug}.request.yaml` is always a key of `projectFiles(project)`.
+ */
+export declare function requestFileLocation(project: Project, requestId: string): RequestFileLocation | undefined;

package/dist/project/request-location.js

@@ -0,0 +1,62 @@
+/**
+ * Finds where a request's files live on disk, so a caller (the desktop main process, for a
+ * `<slug>.golden.yaml` snapshot sidecar) can place a file beside them without re-deriving the
+ * layout `serialize.ts` already owns.
+ */
+import { APIS_DIR, INTERFACES_DIR, OPERATIONS_DIR, REQUESTS_DIR, WEBHOOKS_DIR } from './paths.js';
+/** Depth-first search of a REST API's folder tree for the request with `requestId`. */
+function findInFolders(folders, dir, requestId) {
+    for (const folder of folders) {
+        const childDir = `${dir}/${folder.slug}`;
+        for (const request of folder.requests) {
+            if (request.id === requestId) {
+                return { dir: childDir, slug: request.slug };
+            }
+        }
+        const found = findInFolders(folder.folders, childDir, requestId);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * Locates the request identified by `requestId`: the folder it lives under and its file slug.
+ *
+ * Only SOAP, REST and webhook requests have file locations today — a gRPC or WebSocket request, or
+ * an unknown id, returns `undefined`. `dir` and `slug` are derived the same way `serialize.ts`
+ * builds its keys, so `${dir}/${slug}.request.yaml` is always a key of `projectFiles(project)`.
+ */
+export function requestFileLocation(project, requestId) {
+    for (const iface of project.interfaces) {
+        for (const operation of iface.operations) {
+            for (const request of operation.requests) {
+                if (request.id === requestId) {
+                    return { dir: `${INTERFACES_DIR}/${iface.slug}/${OPERATIONS_DIR}/${operation.slug}`, slug: request.slug };
+                }
+            }
+        }
+    }
+    for (const api of project.apis) {
+        const base = `${APIS_DIR}/${api.slug}/${REQUESTS_DIR}`;
+        for (const request of api.requests) {
+            if (request.id === requestId) {
+                return { dir: base, slug: request.slug };
+            }
+        }
+        const found = findInFolders(api.folders, base, requestId);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    if (project.webhooks !== undefined) {
+        const base = `${WEBHOOKS_DIR}/${REQUESTS_DIR}`;
+        const root = project.webhooks.requests.find((request) => request.id === requestId);
+        if (root !== undefined)
+            return { dir: base, slug: root.slug };
+        const found = findInFolders(project.webhooks.folders, base, requestId);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}

package/dist/project/save.d.ts

@@ -5,13 +5,15 @@
  * rewritten (so an autosave produces a one-file git diff, and file watchers
  * stay quiet), and every write goes through a temp file plus `rename`.
  *
- * Only Wirebench's own subtrees are managed. The definition cache
+ * Only Wirebench's own subtrees are managed: core lists its own files, and each
+ * protocol module lists those of its containers. The definition cache
  * (`interfaces/<slug>/definition/`) and `attachments/` belong to other
  * components and are never read or removed here — except when their owning
  * interface is deleted, in which case the whole interface folder goes.
  */
-import type { Project } from './model.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
 import type { FsLike } from './fs.js';
+import type { Project } from './model.js';
 import type { ProjectFiles } from './serialize.js';
 /** What a {@link saveProject} call did, as relative `/`-separated paths. */
 export interface SaveResult {
@@ -39,6 +41,12 @@ export interface SaveProjectOptions {
     readonly fs?: FsLike;
     /** Recorded in the manifest as `writtenBy`. Defaults to `'wirebench'`. */
     readonly writer?: string;
+    /**
+     * The protocols this save can write: their containers are what is written, and their files what
+     * is managed. A container the project holds whose kind has no enabled module here is left on
+     * disk exactly as it is, as a placeholder is. Defaults to the built-in ones, all switched on.
+     */
+    readonly registry?: ProtocolRegistry;
     /**
      * Relative `<slug>.xml.bak` paths naming the requests to back up before this save overwrites
      * their `<slug>.xml`, as produced by `wsdl/update-definition.ts`'s `applyUpdate`. The bytes
@@ -61,5 +69,7 @@ export interface SaveProjectOptions {
  * Saves `project` into the directory `root`, creating it if needed.
  *
  * @returns which files were written, removed and left untouched.
+ * @throws ProjectError `container-slug-conflict` when a container has the slug of a placeholder in
+ * its directory; `sequence-file-conflict`; what {@link projectFiles} throws
  */
 export declare function saveProject(project: Project, root: string, options?: SaveProjectOptions): Promise<SaveResult>;