@wirebench/engine 2.1.1

package/dist/validate/wsi/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The WS-I Basic Profile 1.1 assertion contracts.
+ *
+ * An *assertion* is one testable requirement of the profile (`R2001`, `R2705`, …). Each lives in
+ * its own module under `assertions/`, is registered in `assertions/index.ts`, and is evaluated by
+ * `runWsdlAssertions` against a {@link WsiWsdlContext} — the parsed WSDL plus the raw documents it
+ * was parsed from, so an assertion can look at constructs the model deliberately drops.
+ *
+ * Profile text is quoted only in short fragments (it is published under the WS-I document
+ * licence); the rest of every assertion's description is a paraphrase.
+ */
+import type { Document, Element } from '@xmldom/xmldom';
+import type { SoapExchange } from '../../types.js';
+import type { WsdlDefinition } from '../../wsdl/model.js';
+import type { DefinitionBundle } from '../../wsdl/resolver.js';
+import type { SchemaSet } from '../../xsd/schema-set.js';
+/** Conformance level of an assertion: a `MUST`, a `SHOULD`, or a `MAY` in the profile's wording. */
+export type WsiAssertionLevel = 'REQUIRED' | 'RECOMMENDED' | 'PERMITTED';
+/**
+ * Outcome of evaluating one assertion:
+ * - `passed` — the construct occurs and conforms;
+ * - `failed` — a `REQUIRED` assertion is violated;
+ * - `warning` — a `RECOMMENDED` assertion is violated;
+ * - `notApplicable` — the construct the assertion is about does not occur at all.
+ */
+export type WsiAssertionResult = 'passed' | 'failed' | 'warning' | 'notApplicable';
+/** Where in the description a finding was raised. */
+export interface WsiLocation {
+    /** Absolute location of the document holding the offending construct. */
+    readonly document: string;
+    /** 1-based line within that document. */
+    readonly line?: number;
+    /** 1-based column within that document. */
+    readonly column?: number;
+    /** A readable element path, e.g. `/definitions/binding[@name='EchoBinding']`. */
+    readonly xpath?: string;
+}
+/** One concrete violation of an assertion. */
+export interface WsiFinding {
+    readonly message: string;
+    readonly location?: WsiLocation;
+}
+/** The sentinel a `check` returns when the construct it examines does not occur. */
+export interface WsiNotApplicable {
+    readonly applicable: false;
+}
+/** The sentinel value assertions return instead of vacuously passing. */
+export declare const NOT_APPLICABLE: WsiNotApplicable;
+/** What an assertion's `check` returns: findings (possibly none), or {@link NOT_APPLICABLE}. */
+export type WsiCheckOutcome = readonly WsiFinding[] | WsiNotApplicable;
+/** Narrows a {@link WsiCheckOutcome} to the not-applicable sentinel. */
+export declare function isNotApplicable(outcome: WsiCheckOutcome): outcome is WsiNotApplicable;
+/** Everything a WSDL-level assertion may inspect. */
+export interface WsiWsdlContext {
+    /** The merged, parsed definition. */
+    readonly definition: WsdlDefinition;
+    /** The resolved import graph, including every document's raw text and kind. */
+    readonly bundle: DefinitionBundle;
+    /** The compiled schema set, for resolving element/type references. */
+    readonly schemaSet: SchemaSet;
+    /** Every document of the bundle, keyed by its canonical location. */
+    readonly documents: ReadonlyMap<string, Document>;
+}
+/** One testable requirement of the profile. */
+export interface WsiAssertion {
+    /** The profile's requirement id, e.g. `R2001`. */
+    readonly id: string;
+    /** A one-line, paraphrased statement of the requirement. */
+    readonly title: string;
+    readonly level: WsiAssertionLevel;
+    /** The profile section the requirement belongs to, e.g. `4.1 Required Description Formats`. */
+    readonly section: string;
+    /**
+     * Set when the requirement is real and implemented but its *number* could not be confirmed
+     * against the published profile. The generated catalogue marks such rows so a reader does not
+     * quote an id Wirebench is not sure of.
+     */
+    readonly unverifiedId?: boolean;
+    /** Evaluates the requirement against one description. */
+    check(context: WsiWsdlContext): WsiCheckOutcome;
+}
+/** One assertion's entry in a {@link WsiReport}. */
+export interface WsiAssertionReport {
+    readonly id: string;
+    readonly title: string;
+    readonly level: WsiAssertionLevel;
+    readonly section: string;
+    readonly result: WsiAssertionResult;
+    readonly findings: readonly WsiFinding[];
+    /** Carried from {@link WsiAssertion.unverifiedId}/{@link WsiMessageAssertion.unverifiedId}. */
+    readonly unverifiedId?: boolean;
+}
+/** How many assertions ended in each result. Always counts every assertion that ran. */
+export interface WsiSummary {
+    readonly passed: number;
+    readonly failed: number;
+    readonly warning: number;
+    readonly notApplicable: number;
+}
+/** The result of analysing one description against the profile. */
+export interface WsiReport {
+    /** The location of the description that was analysed (the bundle's root document). */
+    readonly target: string;
+    readonly profile: 'BP1.1';
+    /** Counts across every assertion that ran, regardless of `verbose`. */
+    readonly summary: WsiSummary;
+    /** Every assertion when `verbose`, only the failed/warning ones otherwise. */
+    readonly assertions: readonly WsiAssertionReport[];
+}
+/** Which half of an exchange an assertion is looking at. */
+export type WsiMessageDirection = 'request' | 'response';
+/**
+ * What the binding says about the messages of one operation. The message assertions need only
+ * this much of the description: whether a construct is legal usually turns on the SOAP version,
+ * the style and the `use`.
+ */
+export interface WsiMessageBinding {
+    readonly soapVersion: '1.1' | '1.2';
+    readonly style: 'document' | 'rpc';
+    readonly use: 'literal' | 'encoded';
+    /** The bound operation's name, for a readable finding. */
+    readonly operation?: string;
+    /** The `soapAction` the binding declares, when it declares one. */
+    readonly soapAction?: string;
+}
+/**
+ * One half of the exchange, prepared for the assertions: the HTTP metadata plus the parsed
+ * envelope. `document` is absent when the half carried no XML or could not be parsed — an
+ * assertion that needs a DOM reports {@link NOT_APPLICABLE} rather than guessing.
+ */
+export interface WsiMessageView {
+    readonly direction: WsiMessageDirection;
+    /**
+     * Header names lower-cased, as both `HttpExchange` halves already store them, and redacted down
+     * to the allow-list the message assertions actually need (`content-type`, `soapaction`,
+     * `content-length`, `transfer-encoding`, `content-encoding`, `accept`, `host`, `connection`) —
+     * see `HEADER_ALLOWLIST` in `run-message.ts`. Never quote a header value or element text outside
+     * this allow-list: an `Authorization` header or a WSS credential must never reach a finding
+     * message or an exported report.
+     */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The envelope text, when one is available. */
+    readonly envelopeXml?: string;
+    readonly document?: Document;
+    /** The document element, when it is a `soap:Envelope` of a SOAP version the profile knows. */
+    readonly envelope?: Element;
+    /** The envelope namespace actually used, which may differ from the bound version. */
+    readonly soapNs?: string;
+    /** HTTP status; responses only. */
+    readonly status?: number;
+}
+/** Everything a message-level assertion may inspect. */
+export interface WsiMessageContext {
+    readonly exchange: SoapExchange;
+    readonly binding: WsiMessageBinding;
+    /** The half the run was asked about; both halves are still offered in {@link messages}. */
+    readonly direction: WsiMessageDirection;
+    readonly request: WsiMessageView;
+    /** Absent when the send never got a response. */
+    readonly response?: WsiMessageView;
+    /** The request, then the response when there is one — what most assertions iterate. */
+    readonly messages: readonly WsiMessageView[];
+}
+/** One testable requirement of the profile that constrains a message rather than a description. */
+export interface WsiMessageAssertion {
+    readonly id: string;
+    readonly title: string;
+    readonly level: WsiAssertionLevel;
+    readonly section: string;
+    /** See {@link WsiAssertion.unverifiedId}. */
+    readonly unverifiedId?: boolean;
+    check(context: WsiMessageContext): WsiCheckOutcome;
+}

package/dist/validate/wsi/types.js

@@ -0,0 +1,17 @@
+/**
+ * The WS-I Basic Profile 1.1 assertion contracts.
+ *
+ * An *assertion* is one testable requirement of the profile (`R2001`, `R2705`, …). Each lives in
+ * its own module under `assertions/`, is registered in `assertions/index.ts`, and is evaluated by
+ * `runWsdlAssertions` against a {@link WsiWsdlContext} — the parsed WSDL plus the raw documents it
+ * was parsed from, so an assertion can look at constructs the model deliberately drops.
+ *
+ * Profile text is quoted only in short fragments (it is published under the WS-I document
+ * licence); the rest of every assertion's description is a paraphrase.
+ */
+/** The sentinel value assertions return instead of vacuously passing. */
+export const NOT_APPLICABLE = Object.freeze({ applicable: false });
+/** Narrows a {@link WsiCheckOutcome} to the not-applicable sentinel. */
+export function isNotApplicable(outcome) {
+    return 'applicable' in outcome;
+}

package/dist/workspace/commit-message.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Maps a path inside a shared workspace's tree to the entity it belongs to, and turns a list of
+ * changed paths into a git commit message. Pure: no file-system access, no git. `SyncService`
+ * (main) calls {@link commitMessage} with the paths `git status`/`diff --name-only` reported for
+ * the working tree, right before running `git commit`.
+ *
+ * Paths are always `/`-separated tree-relative paths, as git itself reports them — never joined
+ * with `node:path`, which would emit `\` on Windows and break every pattern below.
+ */
+/** What kind of entity a tree path belongs to. */
+export type TreeEntityKind = 'workspace' | 'environment' | 'project' | 'interface' | 'request' | 'project-environment' | 'wss' | 'keystores' | 'attachment' | 'definition' | 'other';
+/**
+ * The entity a tree path belongs to. `key` identifies the entity itself (as opposed to the file):
+ * a request's `.request.yaml` and `.xml` share one key, as do every file under one interface's
+ * `definition/` cache — so {@link commitMessage} can group them into a single change.
+ */
+export interface TreeEntity {
+    readonly kind: TreeEntityKind;
+    readonly name: string;
+    readonly projectSlug?: string;
+    readonly key: string;
+}
+/**
+ * Classifies a tree-relative path into the {@link TreeEntity} it belongs to, following the tree
+ * layout `workspace.yaml`, `environments/<slug>.yaml`, `.gitattributes` at the root plus
+ * `projects/<slug>/` per internal project (itself laid out exactly as `project/serialize.ts`'s
+ * `projectFiles()` writes it). Anything unrecognised — including `.gitattributes` — classifies as
+ * `other`.
+ */
+export declare function describeTreePath(relativePath: string): TreeEntity;
+/** A path that changed in the tree, as `git status`/`diff --name-only` reports it. */
+export interface TreeChange {
+    readonly path: string;
+    readonly status: 'added' | 'modified' | 'deleted';
+}
+/**
+ * Builds a git commit message — subject line, blank line, one changed path per line — from the
+ * tree paths a save touched. `''` for no changes (nothing to commit).
+ *
+ * One entity changed: `Update request GetWeather in billing`, `Add environment QA`, `Update
+ * workspace properties`. Several: `Update 3 requests, 1 environment`, counts sorted by count
+ * descending then label ascending. `options.autosave` appends ` (autosave)`; the subject
+ * (suffix included) is truncated to {@link MAX_SUBJECT_LENGTH} characters with a trailing `…`.
+ */
+export declare function commitMessage(changes: readonly TreeChange[], options?: {
+    readonly autosave?: boolean;
+}): string;

package/dist/workspace/commit-message.js

@@ -0,0 +1,195 @@
+/**
+ * Maps a path inside a shared workspace's tree to the entity it belongs to, and turns a list of
+ * changed paths into a git commit message. Pure: no file-system access, no git. `SyncService`
+ * (main) calls {@link commitMessage} with the paths `git status`/`diff --name-only` reported for
+ * the working tree, right before running `git commit`.
+ *
+ * Paths are always `/`-separated tree-relative paths, as git itself reports them — never joined
+ * with `node:path`, which would emit `\` on Windows and break every pattern below.
+ */
+import { WSS_DIR, REQUEST_SUFFIX } from '../project/paths.js';
+import { KEYSTORES_PATH } from '../project/serialize.js';
+import { WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST, WORKSPACE_PROJECTS_DIR } from './paths.js';
+/** Last `/`-separated segment of a path. */
+function basename(path) {
+    const index = path.lastIndexOf('/');
+    return index === -1 ? path : path.slice(index + 1);
+}
+/** Classifies a path inside a project's own folder (relative to `projects/<slug>/`). */
+function describeProjectPath(projectSlug, relative, fullPath) {
+    if (relative === 'wirebench.yaml') {
+        return { kind: 'project', name: projectSlug, projectSlug, key: fullPath };
+    }
+    if (relative === KEYSTORES_PATH) {
+        return { kind: 'keystores', name: 'keystores', projectSlug, key: fullPath };
+    }
+    const wssMatch = /^wss\/[^/]+\/([^/]+)\.yaml$/.exec(relative);
+    if (wssMatch !== undefined && wssMatch !== null) {
+        return { kind: 'wss', name: wssMatch[1] ?? basename(relative), projectSlug, key: fullPath };
+    }
+    if (relative.startsWith(`${WSS_DIR}/`)) {
+        // Any other file under wss/ that isn't the registry or a `<direction>/<name>.yaml` config.
+        return { kind: 'wss', name: basename(relative), projectSlug, key: fullPath };
+    }
+    if (relative.startsWith('attachments/')) {
+        return { kind: 'attachment', name: basename(relative), projectSlug, key: fullPath };
+    }
+    const environmentMatch = /^environments\/([^/]+)\.yaml$/.exec(relative);
+    if (environmentMatch !== undefined && environmentMatch !== null) {
+        return { kind: 'project-environment', name: environmentMatch[1] ?? basename(relative), projectSlug, key: fullPath };
+    }
+    // A request occupies two files under the same operation folder that share one entity key:
+    // `<slug>.request.yaml` (metadata) and `<slug>.xml` (the verbatim envelope) — see
+    // `project/paths.ts`'s `requestFiles()`.
+    const requestSuffix = escapeRegExp(REQUEST_SUFFIX);
+    const requestMatch = new RegExp(`^interfaces/[^/]+/operations/[^/]+/([^/]+)(?:${requestSuffix}|\\.xml)$`).exec(relative);
+    if (requestMatch !== undefined && requestMatch !== null) {
+        const requestSlug = requestMatch[1] ?? basename(relative);
+        const suffixLength = relative.endsWith(REQUEST_SUFFIX) ? REQUEST_SUFFIX.length : '.xml'.length;
+        const key = fullPath.slice(0, fullPath.length - suffixLength);
+        return { kind: 'request', name: requestSlug, projectSlug, key };
+    }
+    const interfaceMatch = /^interfaces\/([^/]+)\/interface\.yaml$/.exec(relative);
+    if (interfaceMatch !== undefined && interfaceMatch !== null) {
+        return { kind: 'interface', name: interfaceMatch[1] ?? basename(relative), projectSlug, key: fullPath };
+    }
+    const definitionMatch = /^interfaces\/([^/]+)\/definition\//.exec(relative);
+    if (definitionMatch !== undefined && definitionMatch !== null) {
+        const interfaceSlug = definitionMatch[1] ?? basename(relative);
+        return {
+            kind: 'definition',
+            name: interfaceSlug,
+            projectSlug,
+            key: `${WORKSPACE_PROJECTS_DIR}/${projectSlug}/interfaces/${interfaceSlug}/definition`,
+        };
+    }
+    return { kind: 'other', name: basename(relative), key: fullPath };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Classifies a tree-relative path into the {@link TreeEntity} it belongs to, following the tree
+ * layout `workspace.yaml`, `environments/<slug>.yaml`, `.gitattributes` at the root plus
+ * `projects/<slug>/` per internal project (itself laid out exactly as `project/serialize.ts`'s
+ * `projectFiles()` writes it). Anything unrecognised — including `.gitattributes` — classifies as
+ * `other`.
+ */
+export function describeTreePath(relativePath) {
+    if (relativePath === WORKSPACE_MANIFEST) {
+        return { kind: 'workspace', name: 'workspace', key: relativePath };
+    }
+    const environmentMatch = new RegExp(`^${WORKSPACE_ENVIRONMENTS_DIR}/([^/]+)\\.yaml$`).exec(relativePath);
+    if (environmentMatch !== undefined && environmentMatch !== null) {
+        return { kind: 'environment', name: environmentMatch[1] ?? basename(relativePath), key: relativePath };
+    }
+    const projectMatch = new RegExp(`^${WORKSPACE_PROJECTS_DIR}/([^/]+)/(.+)$`).exec(relativePath);
+    if (projectMatch !== undefined && projectMatch !== null) {
+        const projectSlug = projectMatch[1] ?? '';
+        const rest = projectMatch[2] ?? '';
+        return describeProjectPath(projectSlug, rest, relativePath);
+    }
+    return { kind: 'other', name: basename(relativePath), key: relativePath };
+}
+/** Human-facing label for one entity kind, singular. */
+const LABELS = {
+    workspace: 'workspace properties',
+    environment: 'environment',
+    project: 'project',
+    interface: 'interface',
+    request: 'request',
+    'project-environment': 'project environment',
+    wss: 'WS-Security config',
+    keystores: 'keystores',
+    attachment: 'attachment',
+    definition: 'definition',
+    other: 'file',
+};
+/** Kinds whose label does not take a plain `s` suffix when the count isn't 1. */
+const INVARIANT_PLURAL = new Set(['keystores', 'workspace']);
+function pluralise(kind, count) {
+    const label = LABELS[kind];
+    if (count === 1 || INVARIANT_PLURAL.has(kind)) {
+        return label;
+    }
+    return `${label}s`;
+}
+const MAX_SUBJECT_LENGTH = 72;
+const AUTOSAVE_SUFFIX = ' (autosave)';
+/** Combines an entity's changed-file statuses into one verb: mixed statuses read as `modified`. */
+function combinedStatus(statuses) {
+    if (statuses.every((status) => status === 'added')) {
+        return 'added';
+    }
+    if (statuses.every((status) => status === 'deleted')) {
+        return 'deleted';
+    }
+    return 'modified';
+}
+const VERBS = {
+    added: 'Add',
+    modified: 'Update',
+    deleted: 'Delete',
+};
+/** Truncates `subject` to fit `AUTOSAVE_SUFFIX` (when `autosave`) within {@link MAX_SUBJECT_LENGTH}. */
+function withAutosave(subject, autosave) {
+    const suffix = autosave === true ? AUTOSAVE_SUFFIX : '';
+    const full = `${subject}${suffix}`;
+    if (full.length <= MAX_SUBJECT_LENGTH) {
+        return full;
+    }
+    const budget = MAX_SUBJECT_LENGTH - suffix.length - 1; // 1 for the ellipsis
+    return `${subject.slice(0, budget)}…${suffix}`;
+}
+/**
+ * Builds a git commit message — subject line, blank line, one changed path per line — from the
+ * tree paths a save touched. `''` for no changes (nothing to commit).
+ *
+ * One entity changed: `Update request GetWeather in billing`, `Add environment QA`, `Update
+ * workspace properties`. Several: `Update 3 requests, 1 environment`, counts sorted by count
+ * descending then label ascending. `options.autosave` appends ` (autosave)`; the subject
+ * (suffix included) is truncated to {@link MAX_SUBJECT_LENGTH} characters with a trailing `…`.
+ */
+export function commitMessage(changes, options) {
+    if (changes.length === 0) {
+        return '';
+    }
+    const groups = new Map();
+    for (const change of changes) {
+        const entity = describeTreePath(change.path);
+        let group = groups.get(entity.key);
+        if (group === undefined) {
+            group = { entity, paths: [], statuses: [] };
+            groups.set(entity.key, group);
+        }
+        group.paths.push(change.path);
+        group.statuses.push(change.status);
+    }
+    const body = [...changes.map((change) => change.path)].sort().join('\n');
+    let subject;
+    if (groups.size === 1) {
+        const group = groups.values().next().value;
+        const { entity } = group;
+        const verb = VERBS[combinedStatus(group.statuses)];
+        const label = LABELS[entity.kind];
+        const nameSuffix = entity.kind === 'workspace' ? '' : ` ${entity.name}`;
+        const projectSuffix = entity.projectSlug === undefined ? '' : ` in ${entity.projectSlug}`;
+        subject = `${verb} ${label}${nameSuffix}${projectSuffix}`;
+    }
+    else {
+        const counts = new Map();
+        for (const group of groups.values()) {
+            counts.set(group.entity.kind, (counts.get(group.entity.kind) ?? 0) + 1);
+        }
+        const parts = [...counts.entries()]
+            .sort(([kindA, countA], [kindB, countB]) => {
+            if (countA !== countB) {
+                return countB - countA;
+            }
+            return LABELS[kindA].localeCompare(LABELS[kindB]);
+        })
+            .map(([kind, count]) => `${count} ${pluralise(kind, count)}`);
+        subject = `Update ${parts.join(', ')}`;
+    }
+    return `${withAutosave(subject, options?.autosave)}\n\n${body}`;
+}

package/dist/workspace/environments.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Teaches the workspace layer to `project/properties.ts` and
+ * `project/environments.ts`: linking a workspace environment to the project
+ * environment of the same slug, building the `PropertyScopes` for a project
+ * open inside a workspace, and resolving the endpoint a request should
+ * actually be sent to under an active workspace environment.
+ *
+ * Precedence for the endpoint: a linked project environment's own override
+ * for the interface wins (same as `resolveEndpoint`'s environment case);
+ * otherwise the active workspace environment's override for
+ * `<projectSlug>/<interfaceSlug>`; otherwise whatever `resolveEndpoint`
+ * would return with no project environment active (request-custom,
+ * request-endpoint, interface-default). Environment layers name no
+ * `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 { 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';
+/**
+ * The project environment whose `slug` matches `workspaceEnv`'s, or
+ * `undefined` when there is no such environment (or `workspaceEnv` itself
+ * is `undefined`).
+ */
+export declare function linkedEnvironment(project: Project, workspaceEnv: WorkspaceEnvironment | undefined): Environment | undefined;
+/**
+ * Builds the {@link PropertyScopes} for expanding properties against `project` as opened inside
+ * `workspace`. `env` merges the active workspace environment's properties with the linked
+ * project environment's (project wins on a shared key), and is omitted entirely when neither
+ * exists, so shorthand lookups correctly skip it — matching `resolveScopes`'s behaviour for a
+ * project with no active environment. A property switched off via `disabledProperties` (on the
+ * workspace, the project, the active workspace environment, or the linked project environment)
+ * is excluded from its own scope before the merge, so e.g. a value disabled only in the
+ * workspace environment still falls through to an enabled value in the linked project
+ * environment — see {@link enabledProperties}.
+ */
+export declare function resolveWorkspaceScopes(input: {
+    readonly workspace: Workspace;
+    readonly project: Project;
+    readonly globals: PropertyMap;
+    readonly system?: PropertyScopes['system'];
+}): PropertyScopes;
+/**
+ * Resolves the URL a request should actually be sent to for a project open inside `workspace`.
+ * See the module doc for the precedence order. `endpoint` is present only when the URL came
+ * from an `Endpoint` object (i.e. the fallback to {@link resolveEndpoint} landed on
+ * `request-endpoint` or `interface-default`) — the two environment-override branches name no
+ * `Endpoint`, matching `resolveEndpoint`'s own contract.
+ */
+export declare function resolveWorkspaceEndpoint(input: {
+    readonly workspace: Workspace;
+    readonly project: Project;
+    readonly projectSlug: string;
+    readonly iface: Interface;
+    readonly request: Pick<RequestDef, 'endpointId' | 'endpointUrl'>;
+}): {
+    url: string | undefined;
+    source: EndpointSource;
+    endpoint?: Endpoint;
+};
+/**
+ * Resolves an API's base URL the way a project open inside a workspace actually resolves it:
+ * a linked project's own environment first, then the workspace environment's override keyed
+ * `<projectSlug>/<apiSlug>`, then the API's own base URL.
+ *
+ * The same ladder {@link resolveWorkspaceEndpoint} climbs for a SOAP interface, and keyed the same
+ * way — which is why an API and an interface may not share a slug (`project/load.ts` refuses it).
+ */
+export declare function resolveWorkspaceApiBaseUrl(input: {
+    readonly workspace: Workspace;
+    readonly project: Project;
+    readonly projectSlug: string;
+    readonly api: Pick<RestApi, 'slug' | 'baseUrl'>;
+}): {
+    url: string;
+    source: BaseUrlSource;
+};

package/dist/workspace/environments.js

@@ -0,0 +1,115 @@
+/**
+ * Teaches the workspace layer to `project/properties.ts` and
+ * `project/environments.ts`: linking a workspace environment to the project
+ * environment of the same slug, building the `PropertyScopes` for a project
+ * open inside a workspace, and resolving the endpoint a request should
+ * actually be sent to under an active workspace environment.
+ *
+ * Precedence for the endpoint: a linked project environment's own override
+ * for the interface wins (same as `resolveEndpoint`'s environment case);
+ * otherwise the active workspace environment's override for
+ * `<projectSlug>/<interfaceSlug>`; otherwise whatever `resolveEndpoint`
+ * would return with no project environment active (request-custom,
+ * request-endpoint, interface-default). Environment layers name no
+ * `Endpoint` object of their own, so neither of the first two branches
+ * carries one.
+ */
+import { resolveApiBaseUrl, resolveEndpoint } from '../project/environments.js';
+import { enabledProperties } from '../project/properties.js';
+/**
+ * The project environment whose `slug` matches `workspaceEnv`'s, or
+ * `undefined` when there is no such environment (or `workspaceEnv` itself
+ * is `undefined`).
+ */
+export function linkedEnvironment(project, workspaceEnv) {
+    if (workspaceEnv === undefined) {
+        return undefined;
+    }
+    return project.environments.find((environment) => environment.slug === workspaceEnv.slug);
+}
+/** Finds `workspace`'s active environment (per `activeEnvironmentId`), or `undefined` when none is active. */
+function activeWorkspaceEnvironment(workspace) {
+    if (workspace.activeEnvironmentId === undefined) {
+        return undefined;
+    }
+    return workspace.environments.find((environment) => environment.id === workspace.activeEnvironmentId);
+}
+/**
+ * Builds the {@link PropertyScopes} for expanding properties against `project` as opened inside
+ * `workspace`. `env` merges the active workspace environment's properties with the linked
+ * project environment's (project wins on a shared key), and is omitted entirely when neither
+ * exists, so shorthand lookups correctly skip it — matching `resolveScopes`'s behaviour for a
+ * project with no active environment. A property switched off via `disabledProperties` (on the
+ * workspace, the project, the active workspace environment, or the linked project environment)
+ * is excluded from its own scope before the merge, so e.g. a value disabled only in the
+ * workspace environment still falls through to an enabled value in the linked project
+ * environment — see {@link enabledProperties}.
+ */
+export function resolveWorkspaceScopes(input) {
+    const { workspace, project, globals, system } = input;
+    const activeWorkspaceEnv = activeWorkspaceEnvironment(workspace);
+    const linkedProjectEnv = linkedEnvironment(project, activeWorkspaceEnv);
+    const enabledWorkspaceEnvProperties = activeWorkspaceEnv !== undefined
+        ? enabledProperties(activeWorkspaceEnv.properties, activeWorkspaceEnv.disabledProperties)
+        : undefined;
+    const enabledLinkedProjectEnvProperties = linkedProjectEnv !== undefined
+        ? enabledProperties(linkedProjectEnv.properties, linkedProjectEnv.disabledProperties)
+        : undefined;
+    const env = activeWorkspaceEnv !== undefined || linkedProjectEnv !== undefined
+        ? { ...enabledWorkspaceEnvProperties, ...enabledLinkedProjectEnvProperties }
+        : undefined;
+    return {
+        project: enabledProperties(project.properties, project.disabledProperties),
+        workspace: enabledProperties(workspace.properties, workspace.disabledProperties),
+        global: globals,
+        ...(env !== undefined ? { env } : {}),
+        ...(system !== undefined ? { system } : {}),
+    };
+}
+/**
+ * Resolves the URL a request should actually be sent to for a project open inside `workspace`.
+ * See the module doc for the precedence order. `endpoint` is present only when the URL came
+ * from an `Endpoint` object (i.e. the fallback to {@link resolveEndpoint} landed on
+ * `request-endpoint` or `interface-default`) — the two environment-override branches name no
+ * `Endpoint`, matching `resolveEndpoint`'s own contract.
+ */
+export function resolveWorkspaceEndpoint(input) {
+    const { workspace, project, projectSlug, iface, request } = input;
+    const activeWorkspaceEnv = activeWorkspaceEnvironment(workspace);
+    const linkedProjectEnv = linkedEnvironment(project, activeWorkspaceEnv);
+    if (linkedProjectEnv !== undefined) {
+        const override = linkedProjectEnv.endpoints[iface.slug];
+        if (override !== undefined) {
+            return { url: override, source: 'environment' };
+        }
+    }
+    if (activeWorkspaceEnv !== undefined) {
+        const override = activeWorkspaceEnv.endpoints[`${projectSlug}/${iface.slug}`];
+        if (override !== undefined) {
+            return { url: override, source: 'workspace-environment' };
+        }
+    }
+    return resolveEndpoint(project, undefined, iface, request);
+}
+/**
+ * Resolves an API's base URL the way a project open inside a workspace actually resolves it:
+ * a linked project's own environment first, then the workspace environment's override keyed
+ * `<projectSlug>/<apiSlug>`, then the API's own base URL.
+ *
+ * The same ladder {@link resolveWorkspaceEndpoint} climbs for a SOAP interface, and keyed the same
+ * way — which is why an API and an interface may not share a slug (`project/load.ts` refuses it).
+ */
+export function resolveWorkspaceApiBaseUrl(input) {
+    const { workspace, project, projectSlug, api } = input;
+    const activeWorkspaceEnv = activeWorkspaceEnvironment(workspace);
+    const linkedProjectEnv = linkedEnvironment(project, activeWorkspaceEnv);
+    const linkedOverride = linkedProjectEnv?.endpoints[api.slug];
+    if (linkedOverride !== undefined) {
+        return { url: linkedOverride, source: 'environment' };
+    }
+    const workspaceOverride = activeWorkspaceEnv?.endpoints[`${projectSlug}/${api.slug}`];
+    if (workspaceOverride !== undefined) {
+        return { url: workspaceOverride, source: 'workspace-environment' };
+    }
+    return resolveApiBaseUrl(project, undefined, api);
+}

package/dist/workspace/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public surface of the workspace module: a workspace's model, its on-disk
+ * schema and file-system layout, and the load/save/migrate functions that
+ * move between the two. Mirrors the shape of `project/` one level up (see
+ * `workspace/model.ts` for what a workspace is), collected here so
+ * `src/index.ts` can re-export the whole module with one pair of blocks.
+ */
+export { WORKSPACE_FORMAT_VERSION, createWorkspace, createWorkspaceEnvironment } from './model.js';
+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 { workspaceFiles } from './serialize.js';
+export type { WorkspaceFiles } from './serialize.js';
+export { loadWorkspace } from './load.js';
+export type { LoadWorkspaceOptions, LoadWorkspaceResult, WorkspaceProblem } from './load.js';
+export { saveWorkspace } from './save.js';
+export type { SaveWorkspaceOptions } from './save.js';
+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 { reidentifyProject } from './reidentify.js';
+export { resolveWorkspaceApiBaseUrl, linkedEnvironment, resolveWorkspaceEndpoint, resolveWorkspaceScopes, } from './environments.js';
+export { commitMessage, describeTreePath } from './commit-message.js';
+export type { TreeChange, TreeEntity, TreeEntityKind } from './commit-message.js';