@wirebench/engine 2.1.1

package/dist/workspace/index.js

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

package/dist/workspace/load.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reads a workspace folder back into a {@link Workspace}. Mirrors
+ * `project/load.ts`, with one deliberate difference: a workspace tolerates
+ * more damage than a project does. Neither a malformed environment file nor a
+ * project reference that fails its schema aborts the load — each becomes a
+ * {@link WorkspaceProblem} and is dropped, so a partially damaged workspace
+ * still opens (a broken *project* it references is the main process's problem
+ * when it tries to open that project, not this module's).
+ */
+import type { FsLike } from '../project/fs.js';
+import type { Workspace } from './model.js';
+/** A recoverable inconsistency found while loading a workspace. */
+export interface WorkspaceProblem {
+    readonly code: 'environment-file-invalid' | 'project-ref-invalid';
+    readonly message: string;
+    /** Path relative to the workspace root. */
+    readonly file: string;
+}
+/** Options for {@link loadWorkspace}. */
+export interface LoadWorkspaceOptions {
+    readonly fs?: FsLike;
+}
+/** The result of {@link loadWorkspace}: the model plus anything odd about the folder. */
+export interface LoadWorkspaceResult {
+    readonly workspace: Workspace;
+    readonly problems: readonly WorkspaceProblem[];
+    /**
+     * Whatever the migration pulled out of an older manifest because it no longer belongs there —
+     * today, a v1/v2 `activeEnvironmentId`. `workspace.activeEnvironmentId` is always left
+     * `undefined` by this function; the caller (main's `WorkspaceService`) is the one that decides
+     * whether to adopt this into `local.yaml`.
+     */
+    readonly legacy: {
+        readonly activeEnvironmentId?: string;
+    };
+}
+/**
+ * Loads the workspace stored in the directory `root`.
+ *
+ * @throws WorkspaceError `workspace-not-found` when there is no
+ * `workspace.yaml`, `workspace-format-too-new` for a newer format version,
+ * `workspace-file-invalid` for malformed or schema-violating YAML (with the
+ * offending file in `details`).
+ */
+export declare function loadWorkspace(root: string, options?: LoadWorkspaceOptions): Promise<LoadWorkspaceResult>;

package/dist/workspace/load.js

@@ -0,0 +1,155 @@
+/**
+ * Reads a workspace folder back into a {@link Workspace}. Mirrors
+ * `project/load.ts`, with one deliberate difference: a workspace tolerates
+ * more damage than a project does. Neither a malformed environment file nor a
+ * project reference that fails its schema aborts the load — each becomes a
+ * {@link WorkspaceProblem} and is dropped, so a partially damaged workspace
+ * still opens (a broken *project* it references is the main process's problem
+ * when it tries to open that project, not this module's).
+ */
+import { join } from 'node:path';
+import { parse as parseYamlDocument } from 'yaml';
+import { WorkspaceError } from '../errors.js';
+import { nodeFs, readFileIfExists, readdirIfExists } from '../project/fs.js';
+import { WORKSPACE_FORMAT_VERSION } from './model.js';
+import { migrateWorkspace } from './migrate.js';
+import { WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST } from './paths.js';
+import { parseWorkspaceFile, workspaceEnvironmentFileSchema, workspaceManifestSchema, workspaceProjectRefSchema, } from './schema.js';
+function abs(root, relative) {
+    return join(root, ...relative.split('/'));
+}
+/**
+ * Parses YAML text, raising `WorkspaceError('workspace-file-invalid')` with
+ * the offending file path when the document is malformed. A workspace-scoped
+ * equivalent of `project/yaml.ts`'s `parseYaml`, kept local since it must
+ * throw a different error class.
+ */
+function parseYaml(text, file) {
+    try {
+        return parseYamlDocument(text);
+    }
+    catch (error) {
+        throw new WorkspaceError('workspace-file-invalid', `Malformed YAML in ${file}`, {
+            details: { file, issues: [{ path: '', message: error instanceof Error ? error.message : String(error) }] },
+            cause: error,
+        });
+    }
+}
+async function readYaml(fs, root, relative) {
+    const buffer = await readFileIfExists(fs, abs(root, relative));
+    return buffer === undefined ? undefined : parseYaml(buffer.toString('utf8'), relative);
+}
+/** Orders entities by their persisted `order`, falling back to a stable name comparison. */
+function byOrder(a, b) {
+    return a.order - b.order || a.name.localeCompare(b.name);
+}
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/**
+ * Loads every `environments/<slug>.yaml`. A file that is not valid YAML or
+ * does not match {@link workspaceEnvironmentFileSchema} is reported as an
+ * `environment-file-invalid` problem and skipped, rather than aborting the
+ * whole load.
+ */
+async function loadEnvironments(fs, root, problems) {
+    const environments = [];
+    for (const entry of await readdirIfExists(fs, abs(root, WORKSPACE_ENVIRONMENTS_DIR))) {
+        if (!entry.isFile || !entry.name.endsWith('.yaml')) {
+            continue;
+        }
+        const relative = `${WORKSPACE_ENVIRONMENTS_DIR}/${entry.name}`;
+        let document;
+        try {
+            document = await readYaml(fs, root, relative);
+        }
+        catch {
+            problems.push({
+                code: 'environment-file-invalid',
+                message: `"${relative}" is not valid YAML and was skipped`,
+                file: relative,
+            });
+            continue;
+        }
+        const result = workspaceEnvironmentFileSchema.safeParse(document);
+        if (!result.success) {
+            problems.push({
+                code: 'environment-file-invalid',
+                message: `"${relative}" does not match the environment schema and was skipped`,
+                file: relative,
+            });
+            continue;
+        }
+        const parsed = result.data;
+        environments.push({
+            id: parsed.id,
+            name: parsed.name,
+            slug: entry.name.slice(0, -'.yaml'.length),
+            order: parsed.order,
+            properties: parsed.properties,
+            endpoints: parsed.endpoints,
+            disabledProperties: parsed.disabled ?? [],
+        });
+    }
+    return environments.sort(byOrder);
+}
+/**
+ * Validates the raw `projects` array of a manifest one entry at a time, so a
+ * single malformed reference becomes a `project-ref-invalid` problem instead
+ * of failing the whole manifest.
+ */
+function loadProjectRefs(rawProjects, problems) {
+    const refs = [];
+    if (!Array.isArray(rawProjects)) {
+        return refs;
+    }
+    for (const raw of rawProjects) {
+        const result = workspaceProjectRefSchema.safeParse(raw);
+        if (!result.success) {
+            problems.push({
+                code: 'project-ref-invalid',
+                message: `A project reference in ${WORKSPACE_MANIFEST} does not match the expected shape`,
+                file: WORKSPACE_MANIFEST,
+            });
+            continue;
+        }
+        const parsed = result.data;
+        refs.push(parsed.source === 'linked'
+            ? { id: parsed.id, slug: parsed.slug, source: parsed.source, path: parsed.path }
+            : { id: parsed.id, slug: parsed.slug, source: parsed.source });
+    }
+    return refs;
+}
+/**
+ * Loads the workspace stored in the directory `root`.
+ *
+ * @throws WorkspaceError `workspace-not-found` when there is no
+ * `workspace.yaml`, `workspace-format-too-new` for a newer format version,
+ * `workspace-file-invalid` for malformed or schema-violating YAML (with the
+ * offending file in `details`).
+ */
+export async function loadWorkspace(root, options) {
+    const fs = options?.fs ?? nodeFs;
+    const manifestDocument = await readYaml(fs, root, WORKSPACE_MANIFEST);
+    if (manifestDocument === undefined) {
+        throw new WorkspaceError('workspace-not-found', `No ${WORKSPACE_MANIFEST} in ${root}`, {
+            details: { file: WORKSPACE_MANIFEST, root },
+        });
+    }
+    const { manifest: migrated, legacy } = migrateWorkspace(manifestDocument, WORKSPACE_MANIFEST);
+    const problems = [];
+    const projects = loadProjectRefs(migrated['projects'], problems);
+    const manifest = parseWorkspaceFile(workspaceManifestSchema, { ...migrated, projects: [] }, WORKSPACE_MANIFEST);
+    const workspace = {
+        formatVersion: WORKSPACE_FORMAT_VERSION,
+        id: manifest.id,
+        name: manifest.name,
+        ...optional('description', manifest.description),
+        createdAt: manifest.createdAt,
+        properties: manifest.properties,
+        disabledProperties: manifest.disabled ?? [],
+        projects,
+        environments: await loadEnvironments(fs, root, problems),
+    };
+    return { workspace, problems, legacy };
+}

package/dist/workspace/local-state.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `local.yaml`: the machine-local half of a workspace's app-data folder. Never inside the tree,
+ * never committed, never shared — it is the one place `activeEnvironmentId` lives now that
+ * `workspace.yaml` no longer carries it (see `model.ts`).
+ *
+ * Mirrors `share.ts`'s discipline (`readYaml`/`parseWorkspaceFile` in, `stringifyYaml` +
+ * `writeFileAtomic` out) but never throws on a missing or corrupt file: a machine-local file
+ * that cannot be read is simply "no local state yet", not an error the user needs to see.
+ */
+import type { FsLike } from '../project/fs.js';
+/** File name of a workspace's machine-local state, directly under its app-data folder. */
+export declare const WORKSPACE_LOCAL_FILE = "local.yaml";
+/** The machine-local state of one workspace on this machine. */
+export interface WorkspaceLocalState {
+    readonly version: 1;
+    /** Id of the environment currently active for this workspace, on this machine. */
+    readonly activeEnvironmentId?: string;
+}
+/** The state of a workspace that has never had anything local recorded for it. */
+export declare const EMPTY_LOCAL_STATE: WorkspaceLocalState;
+/** Options shared by {@link loadLocalState} and {@link saveLocalState}. */
+export interface LocalStateOptions {
+    readonly fs?: FsLike;
+}
+/**
+ * Reads `<dir>/local.yaml`. A missing file, unparseable YAML, or a document that fails
+ * {@link workspaceLocalStateSchema} all resolve to {@link EMPTY_LOCAL_STATE} rather than
+ * throwing — this file is a cache of machine-local convenience state, not a source of truth
+ * worth failing an `open()` over.
+ */
+export declare function loadLocalState(dir: string, options?: LocalStateOptions): Promise<WorkspaceLocalState>;
+/**
+ * Writes `state` to `<dir>/local.yaml` atomically. When `state` equals {@link EMPTY_LOCAL_STATE}
+ * (nothing worth recording), the file is deleted instead of writing an empty document — so a
+ * workspace that never sets an active environment never grows a `local.yaml` at all.
+ */
+export declare function saveLocalState(dir: string, state: WorkspaceLocalState, options?: LocalStateOptions): Promise<void>;

package/dist/workspace/local-state.js

@@ -0,0 +1,59 @@
+/**
+ * `local.yaml`: the machine-local half of a workspace's app-data folder. Never inside the tree,
+ * never committed, never shared — it is the one place `activeEnvironmentId` lives now that
+ * `workspace.yaml` no longer carries it (see `model.ts`).
+ *
+ * Mirrors `share.ts`'s discipline (`readYaml`/`parseWorkspaceFile` in, `stringifyYaml` +
+ * `writeFileAtomic` out) but never throws on a missing or corrupt file: a machine-local file
+ * that cannot be read is simply "no local state yet", not an error the user needs to see.
+ */
+import { join } from 'node:path';
+import { parse as parseYamlDocument } from 'yaml';
+import { nodeFs, readFileIfExists, writeFileAtomic } from '../project/fs.js';
+import { stringifyYaml, compact } from '../project/yaml.js';
+import { workspaceLocalStateSchema } from './schema.js';
+/** File name of a workspace's machine-local state, directly under its app-data folder. */
+export const WORKSPACE_LOCAL_FILE = 'local.yaml';
+/** The state of a workspace that has never had anything local recorded for it. */
+export const EMPTY_LOCAL_STATE = { version: 1 };
+/**
+ * Reads `<dir>/local.yaml`. A missing file, unparseable YAML, or a document that fails
+ * {@link workspaceLocalStateSchema} all resolve to {@link EMPTY_LOCAL_STATE} rather than
+ * throwing — this file is a cache of machine-local convenience state, not a source of truth
+ * worth failing an `open()` over.
+ */
+export async function loadLocalState(dir, options) {
+    const fs = options?.fs ?? nodeFs;
+    const buffer = await readFileIfExists(fs, join(dir, WORKSPACE_LOCAL_FILE));
+    if (buffer === undefined) {
+        return EMPTY_LOCAL_STATE;
+    }
+    let document;
+    try {
+        document = parseYamlDocument(buffer.toString('utf8'));
+    }
+    catch {
+        return EMPTY_LOCAL_STATE;
+    }
+    const result = workspaceLocalStateSchema.safeParse(document);
+    if (!result.success) {
+        return EMPTY_LOCAL_STATE;
+    }
+    return result.data.activeEnvironmentId === undefined
+        ? EMPTY_LOCAL_STATE
+        : { version: 1, activeEnvironmentId: result.data.activeEnvironmentId };
+}
+/**
+ * Writes `state` to `<dir>/local.yaml` atomically. When `state` equals {@link EMPTY_LOCAL_STATE}
+ * (nothing worth recording), the file is deleted instead of writing an empty document — so a
+ * workspace that never sets an active environment never grows a `local.yaml` at all.
+ */
+export async function saveLocalState(dir, state, options) {
+    const fs = options?.fs ?? nodeFs;
+    const path = join(dir, WORKSPACE_LOCAL_FILE);
+    if (state.activeEnvironmentId === undefined) {
+        await fs.rm(path, { force: true });
+        return;
+    }
+    await writeFileAtomic(fs, path, stringifyYaml(compact({ ...state })));
+}

package/dist/workspace/migrate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Format-version handling for workspace folders. Mirrors `project/migrate.ts`.
+ *
+ * `formatVersion` is bumped only on breaking changes. Opening a workspace
+ * written by a newer Wirebench must fail loudly rather than silently dropping
+ * the parts this build does not understand.
+ */
+/** A raw manifest document, before schema validation. */
+type RawWorkspaceManifest = Record<string, unknown>;
+/**
+ * The result of bringing a raw manifest document up to {@link WORKSPACE_FORMAT_VERSION}: the
+ * migrated manifest itself, plus anything the migration pulled *out* of it because it no longer
+ * belongs there — today, a v1/v2 `activeEnvironmentId`, which `load.ts` hands to the caller so it
+ * can be adopted into `local.yaml` (see `local-state.ts`) rather than silently dropped.
+ */
+export interface MigratedWorkspaceManifest {
+    readonly manifest: RawWorkspaceManifest;
+    readonly legacy: {
+        readonly activeEnvironmentId?: string;
+    };
+}
+/**
+ * Brings a raw manifest document up to {@link WORKSPACE_FORMAT_VERSION}.
+ *
+ * Version 1 needs no rewrite of its own beyond what version 2 does: it simply has no `disabled`
+ * key, and `load.ts` defaults a missing list to empty. Versions 1 and 2 both carried
+ * `activeEnvironmentId` (machine-local, moved to `local.yaml` in v3) and `writtenBy` (dropped
+ * outright — see `model.ts`); this function lifts the former into {@link MigratedWorkspaceManifest.legacy}
+ * and drops both from the manifest, then stamps the document 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.
+ *
+ * @throws WorkspaceError `workspace-format-too-new` when the file was written
+ * by a newer Wirebench, `workspace-file-invalid` when the document is not a
+ * mapping or `formatVersion` is missing, not a number, or below 1.
+ */
+export declare function migrateWorkspace(document: unknown, file: string): MigratedWorkspaceManifest;
+export {};

package/dist/workspace/migrate.js

@@ -0,0 +1,50 @@
+/**
+ * Format-version handling for workspace folders. Mirrors `project/migrate.ts`.
+ *
+ * `formatVersion` is bumped only on breaking changes. Opening a workspace
+ * written by a newer Wirebench must fail loudly rather than silently dropping
+ * the parts this build does not understand.
+ */
+import { WorkspaceError } from '../errors.js';
+import { WORKSPACE_FORMAT_VERSION } from './model.js';
+/**
+ * Brings a raw manifest document up to {@link WORKSPACE_FORMAT_VERSION}.
+ *
+ * Version 1 needs no rewrite of its own beyond what version 2 does: it simply has no `disabled`
+ * key, and `load.ts` defaults a missing list to empty. Versions 1 and 2 both carried
+ * `activeEnvironmentId` (machine-local, moved to `local.yaml` in v3) and `writtenBy` (dropped
+ * outright — see `model.ts`); this function lifts the former into {@link MigratedWorkspaceManifest.legacy}
+ * and drops both from the manifest, then stamps the document 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.
+ *
+ * @throws WorkspaceError `workspace-format-too-new` when the file was written
+ * by a newer Wirebench, `workspace-file-invalid` when the document is not a
+ * mapping or `formatVersion` is missing, not a number, or below 1.
+ */
+export function migrateWorkspace(document, file) {
+    if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+        throw new WorkspaceError('workspace-file-invalid', `Invalid workspace file ${file}: expected a YAML mapping`, {
+            details: { file, issues: [{ path: '', message: 'expected a YAML mapping' }] },
+        });
+    }
+    const raw = document;
+    const version = raw['formatVersion'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+        throw new WorkspaceError('workspace-file-invalid', `Invalid workspace file ${file}: bad formatVersion`, {
+            details: {
+                file,
+                issues: [{ path: 'formatVersion', message: `expected an integer >= 1, got ${JSON.stringify(version)}` }],
+            },
+        });
+    }
+    if (version > WORKSPACE_FORMAT_VERSION) {
+        throw new WorkspaceError('workspace-format-too-new', `Workspace was created by a newer version of Wirebench (format ${version}, this build supports ${WORKSPACE_FORMAT_VERSION})`, { details: { file, formatVersion: version, supported: WORKSPACE_FORMAT_VERSION } });
+    }
+    const activeEnvironmentId = raw['activeEnvironmentId'];
+    const legacy = version < 3 && typeof activeEnvironmentId === 'string' ? { activeEnvironmentId } : {};
+    const rest = { ...raw };
+    delete rest['activeEnvironmentId'];
+    delete rest['writtenBy'];
+    return { manifest: { ...rest, formatVersion: WORKSPACE_FORMAT_VERSION }, legacy };
+}

package/dist/workspace/model.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The Wirebench workspace model: a container of projects with its own
+ * environments (see the design spec, "Workspaces").
+ *
+ * A workspace does not own project data itself: each {@link WorkspaceProjectRef}
+ * merely points at a project folder, either one Wirebench manages inside the
+ * workspace (`source: 'internal'`) or an existing project folder elsewhere on
+ * disk that the workspace only links to (`source: 'linked'`, always an
+ * absolute {@link WorkspaceProjectRef.path}). Environments live on the
+ * workspace, not the project: a workspace environment carries an endpoint
+ * override per `<projectSlug>/<interfaceSlug>` and its own property overrides,
+ * so the same set of projects can be pointed at different deployments without
+ * editing any of them.
+ *
+ * Every field is `readonly`, mirroring `project/model.ts`.
+ */
+import type { CreateOptions, PropertyMap } from '../project/model.js';
+/** The on-disk format version written to (and required by) `workspace.yaml`. */
+export declare const WORKSPACE_FORMAT_VERSION = 3;
+/**
+ * A pointer to one project inside a workspace. `internal` projects live under
+ * the workspace's own `projects/` directory and are managed by it; `linked`
+ * projects live at an existing, absolute `path` elsewhere on disk and the
+ * workspace only references them — nothing here checks that the folder they
+ * point at actually exists, or is a valid project; that is the main process's
+ * job when it opens one.
+ */
+export interface WorkspaceProjectRef {
+    readonly id: string;
+    readonly slug: string;
+    readonly source: 'internal' | 'linked';
+    /** Absolute path to the project folder. Present for `source: 'linked'` only. */
+    readonly path?: string;
+}
+/**
+ * A named set of per-interface endpoint overrides and property values,
+ * scoped to a workspace rather than to one project (compare
+ * `project/model.ts`'s `Environment`). `endpoints` is keyed by
+ * `<projectSlug>/<interfaceSlug>`.
+ */
+export interface WorkspaceEnvironment {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly properties: PropertyMap;
+    readonly endpoints: Readonly<Record<string, string>>;
+    /**
+     * Names of {@link properties} entries that are switched off, mirroring
+     * `project/model.ts`'s `Environment.disabledProperties`: resolution treats a disabled
+     * property as absent, while its value stays on disk. Written sorted, deduplicated, and only
+     * for names still present in `properties`.
+     */
+    readonly disabledProperties: readonly string[];
+}
+/** A whole Wirebench workspace, as loaded from (or saved to) a workspace folder. */
+export interface Workspace {
+    readonly formatVersion: typeof WORKSPACE_FORMAT_VERSION;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    /** ISO 8601 timestamp of when the workspace was created. */
+    readonly createdAt: string;
+    readonly properties: PropertyMap;
+    /** Names of {@link properties} entries switched off; see {@link WorkspaceEnvironment.disabledProperties}. */
+    readonly disabledProperties: readonly string[];
+    /**
+     * Id of the environment currently active for this workspace, if any. Machine-local: kept only
+     * in memory while a workspace is open, and never serialised into `workspace.yaml` — see
+     * `local-state.ts`, which is where it actually lives on disk.
+     */
+    readonly activeEnvironmentId?: string;
+    readonly projects: readonly WorkspaceProjectRef[];
+    readonly environments: readonly WorkspaceEnvironment[];
+}
+/** Creates an empty workspace with no projects and no environments. */
+export declare function createWorkspace(name: string, options?: CreateOptions & {
+    readonly now?: () => Date;
+}): Workspace;
+/**
+ * Creates a workspace environment: its `slug` is `uniqueSlug(name, taken)` (so
+ * it never collides with an already-taken slug, case-insensitively) and its
+ * `order` defaults to `taken.size` — i.e. it is appended after every
+ * environment `taken` was built from.
+ */
+export declare function createWorkspaceEnvironment(name: string, taken: ReadonlySet<string>, options?: CreateOptions): WorkspaceEnvironment;

package/dist/workspace/model.js

@@ -0,0 +1,54 @@
+/**
+ * The Wirebench workspace model: a container of projects with its own
+ * environments (see the design spec, "Workspaces").
+ *
+ * A workspace does not own project data itself: each {@link WorkspaceProjectRef}
+ * merely points at a project folder, either one Wirebench manages inside the
+ * workspace (`source: 'internal'`) or an existing project folder elsewhere on
+ * disk that the workspace only links to (`source: 'linked'`, always an
+ * absolute {@link WorkspaceProjectRef.path}). Environments live on the
+ * workspace, not the project: a workspace environment carries an endpoint
+ * override per `<projectSlug>/<interfaceSlug>` and its own property overrides,
+ * so the same set of projects can be pointed at different deployments without
+ * editing any of them.
+ *
+ * Every field is `readonly`, mirroring `project/model.ts`.
+ */
+import { generateId } from '../project/model.js';
+import { uniqueSlug } from '../project/paths.js';
+/** The on-disk format version written to (and required by) `workspace.yaml`. */
+export const WORKSPACE_FORMAT_VERSION = 3;
+function idOf(options) {
+    return options?.id ?? (options?.newId ?? generateId)();
+}
+/** Creates an empty workspace with no projects and no environments. */
+export function createWorkspace(name, options) {
+    const now = options?.now ?? (() => new Date());
+    return {
+        formatVersion: WORKSPACE_FORMAT_VERSION,
+        id: idOf(options),
+        name,
+        createdAt: now().toISOString(),
+        properties: {},
+        disabledProperties: [],
+        projects: [],
+        environments: [],
+    };
+}
+/**
+ * Creates a workspace environment: its `slug` is `uniqueSlug(name, taken)` (so
+ * it never collides with an already-taken slug, case-insensitively) and its
+ * `order` defaults to `taken.size` — i.e. it is appended after every
+ * environment `taken` was built from.
+ */
+export function createWorkspaceEnvironment(name, taken, options) {
+    return {
+        id: idOf(options),
+        name,
+        slug: uniqueSlug(name, taken),
+        order: options?.order ?? taken.size,
+        properties: {},
+        endpoints: {},
+        disabledProperties: [],
+    };
+}

package/dist/workspace/paths.d.ts

@@ -0,0 +1,64 @@
+/**
+ * File-system naming and layout for a workspace folder.
+ *
+ * Mirrors `project/paths.ts`: display names live inside the YAML, the
+ * folder/file names are derived slugs. `assertPathSegment` is workspace's own
+ * (not `project`'s) so a corrupted slug always throws a `WorkspaceError`.
+ */
+import type { WorkspaceShare } from './share.js';
+/**
+ * Rejects a value that cannot safely be used as a single path segment on disk:
+ * empty, `.`/`..`, containing a path separator or NUL, leading/trailing
+ * whitespace or dots, or a Windows reserved device name. Used to validate any
+ * slug that flows into a workspace file path before it is ever written to (or
+ * deleted from) disk.
+ *
+ * @throws WorkspaceError `workspace-path-invalid` carrying the offending segment.
+ */
+export declare function assertPathSegment(segment: string): void;
+/** Directory (under a user-data root) holding every workspace. */
+export declare const WORKSPACES_DIR = "workspaces";
+/** File name of a workspace's manifest. */
+export declare const WORKSPACE_MANIFEST = "workspace.yaml";
+/** Directory holding every workspace environment file. */
+export declare const WORKSPACE_ENVIRONMENTS_DIR = "environments";
+/** Directory holding every internal project's folder. */
+export declare const WORKSPACE_PROJECTS_DIR = "projects";
+/** File name of the (non-managed-format) file recording desktop UI state, e.g. the last opened workspace. */
+export declare const WORKSPACE_STATE_FILE = "workspace-state.json";
+/** Directory (under a workspace's app-data folder) holding a managed git/folder share's clone. */
+export declare const WORKSPACE_TREE_DIR = "tree";
+/** Directory a clone is checked out into while `join` is still in progress, before it is renamed into place. */
+export declare const WORKSPACE_JOINING_DIR = ".joining";
+/** File name of the tree's own `.gitattributes`, written on share and on join if missing. */
+export declare const GIT_ATTRIBUTES_FILE = ".gitattributes";
+/**
+ * Contents of {@link GIT_ATTRIBUTES_FILE}: normalises line endings, and leaves bytes alone where
+ * they must stay exact — attachments, and the definition caches of interfaces and APIs, which keep
+ * each document as fetched (a WSDL's manifest records its SHA-256, so a CRLF definition normalised
+ * by git fails that check on the other side, which then re-fetches and rewrites the cache).
+ */
+export declare const GIT_ATTRIBUTES = "* text=auto eol=lf\n*.yaml text\n*.xml text\n*.wsdl text\n*.xsd text\nprojects/*/attachments/** -text\nprojects/*/interfaces/*/definition/** -text\nprojects/*/apis/*/definition/** -text\n";
+/** Absolute path of a workspace's own directory, given the app's user-data root and the workspace id. */
+export declare function workspaceDir(userDataDir: string, workspaceId: string): string;
+/** Absolute path of a workspace's manifest. */
+export declare function workspaceManifestFile(dir: string): string;
+/**
+ * Absolute path of a workspace environment file.
+ *
+ * @throws WorkspaceError `workspace-path-invalid` (via {@link assertPathSegment}) when `slug` is not a safe path segment.
+ */
+export declare function workspaceEnvironmentFile(dir: string, slug: string): string;
+/**
+ * Absolute path of an internal project's directory inside a workspace.
+ *
+ * @throws WorkspaceError `workspace-path-invalid` (via {@link assertPathSegment}) when `slug` is not a safe path segment.
+ */
+export declare function workspaceProjectDir(dir: string, slug: string): string;
+/**
+ * The root of a workspace's tree — where `workspace.yaml`, `environments/` and `projects/`
+ * actually live. For a `local` workspace (`share === undefined`) that is `dir` itself; for a
+ * shared workspace it is `share.path` when the tree lives outside `dir` (an external git clone
+ * or synced folder), or the managed `<dir>/tree` clone otherwise.
+ */
+export declare function workspaceTreeDir(dir: string, share: WorkspaceShare | undefined): string;