@wirebench/engine 2.1.1

package/dist/workspace/paths.js

@@ -0,0 +1,97 @@
+/**
+ * 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 { join } from 'node:path';
+import { WorkspaceError } from '../errors.js';
+/** Device names Windows refuses to use as a file name, with or without an extension. */
+const RESERVED_NAMES = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+/**
+ * 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 function assertPathSegment(segment) {
+    const invalid = segment === '' ||
+        segment === '.' ||
+        segment === '..' ||
+        segment.includes('/') ||
+        segment.includes('\\') ||
+        segment.includes('\u0000') ||
+        /^[. ]/.test(segment) ||
+        /[. ]$/.test(segment) ||
+        RESERVED_NAMES.test(segment);
+    if (invalid) {
+        throw new WorkspaceError('workspace-path-invalid', `Invalid path segment: ${JSON.stringify(segment)}`, {
+            details: { segment },
+        });
+    }
+}
+/** Directory (under a user-data root) holding every workspace. */
+export const WORKSPACES_DIR = 'workspaces';
+/** File name of a workspace's manifest. */
+export const WORKSPACE_MANIFEST = 'workspace.yaml';
+/** Directory holding every workspace environment file. */
+export const WORKSPACE_ENVIRONMENTS_DIR = 'environments';
+/** Directory holding every internal project's folder. */
+export const WORKSPACE_PROJECTS_DIR = 'projects';
+/** File name of the (non-managed-format) file recording desktop UI state, e.g. the last opened workspace. */
+export const WORKSPACE_STATE_FILE = 'workspace-state.json';
+/** Directory (under a workspace's app-data folder) holding a managed git/folder share's clone. */
+export 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 const WORKSPACE_JOINING_DIR = '.joining';
+/** File name of the tree's own `.gitattributes`, written on share and on join if missing. */
+export 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 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 function workspaceDir(userDataDir, workspaceId) {
+    return join(userDataDir, WORKSPACES_DIR, workspaceId);
+}
+/** Absolute path of a workspace's manifest. */
+export function workspaceManifestFile(dir) {
+    return join(dir, WORKSPACE_MANIFEST);
+}
+/**
+ * Absolute path of a workspace environment file.
+ *
+ * @throws WorkspaceError `workspace-path-invalid` (via {@link assertPathSegment}) when `slug` is not a safe path segment.
+ */
+export function workspaceEnvironmentFile(dir, slug) {
+    assertPathSegment(slug);
+    return join(dir, WORKSPACE_ENVIRONMENTS_DIR, `${slug}.yaml`);
+}
+/**
+ * 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 function workspaceProjectDir(dir, slug) {
+    assertPathSegment(slug);
+    return join(dir, WORKSPACE_PROJECTS_DIR, slug);
+}
+/**
+ * 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 function workspaceTreeDir(dir, share) {
+    if (share === undefined) {
+        return dir;
+    }
+    return share.path ?? join(dir, WORKSPACE_TREE_DIR);
+}

package/dist/workspace/reidentify.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Gives a {@link Project} a fresh identity: every entity id becomes a new one, and every
+ * reference to an old id is rewritten to match — so a project folder copied into a workspace
+ * never shares an id with the project it was copied from.
+ *
+ * Used when a project folder is imported as a copy (see the workspace import flow); a *linked*
+ * project keeps its ids, since it stays the same on-disk project.
+ */
+import type { IdGenerator, Project } from '../project/model.js';
+/**
+ * Reassigns `project` and every one of its entities a new id, rewriting every internal
+ * reference (including the ids buried inside `WssRef.document` bags) to match. An id this
+ * project does not have an entity for — a dangling reference — is left untouched rather than
+ * invented. `secretRef`/`passwordRef`/`passwordSecretRef` values and attachment `sha256`
+ * sources are never ids, and are carried through byte-identical.
+ *
+ * @param project the project to give a fresh identity
+ * @param newId id generator; defaults to {@link generateId}. Injectable so the result is
+ *   deterministic in tests.
+ * @returns a new `Project` with fresh ids throughout
+ */
+export declare function reidentifyProject(project: Project, newId?: IdGenerator): Project;

package/dist/workspace/reidentify.js

@@ -0,0 +1,122 @@
+/**
+ * Gives a {@link Project} a fresh identity: every entity id becomes a new one, and every
+ * reference to an old id is rewritten to match — so a project folder copied into a workspace
+ * never shares an id with the project it was copied from.
+ *
+ * Used when a project folder is imported as a copy (see the workspace import flow); a *linked*
+ * project keeps its ids, since it stays the same on-disk project.
+ */
+import { defaultContentId, generateId } from '../project/model.js';
+/** Every entity id in `project`, in visit order (an id shared by two entities is deduplicated). */
+function collectIds(project) {
+    const ids = [project.id];
+    for (const iface of project.interfaces) {
+        ids.push(iface.id);
+        for (const endpoint of iface.endpoints) {
+            ids.push(endpoint.id);
+        }
+        for (const operation of iface.operations) {
+            for (const request of operation.requests) {
+                ids.push(request.id);
+                for (const attachment of request.attachments) {
+                    ids.push(attachment.id);
+                }
+            }
+        }
+    }
+    for (const environment of project.environments) {
+        ids.push(environment.id);
+    }
+    for (const ref of [...project.wss.outgoing, ...project.wss.incoming, ...project.wss.keystores]) {
+        ids.push(ref.id);
+    }
+    return ids;
+}
+/** Assigns one new id per unique old id, calling `newId` exactly once per old id. */
+function buildIdMap(ids, newId) {
+    const map = new Map();
+    for (const id of ids) {
+        if (!map.has(id)) {
+            map.set(id, newId());
+        }
+    }
+    return map;
+}
+/** Recursively replaces any string in `value` that is a key of `idMap`, arrays and nested objects included. */
+function remapValue(value, idMap) {
+    if (typeof value === 'string') {
+        return idMap.get(value) ?? value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => remapValue(item, idMap));
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, remapValue(v, idMap)]));
+    }
+    return value;
+}
+/** `{ [key]: value }` when `value` is defined, `{}` otherwise — keeps an omitted optional field omitted. */
+function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/**
+ * Reassigns `project` and every one of its entities a new id, rewriting every internal
+ * reference (including the ids buried inside `WssRef.document` bags) to match. An id this
+ * project does not have an entity for — a dangling reference — is left untouched rather than
+ * invented. `secretRef`/`passwordRef`/`passwordSecretRef` values and attachment `sha256`
+ * sources are never ids, and are carried through byte-identical.
+ *
+ * @param project the project to give a fresh identity
+ * @param newId id generator; defaults to {@link generateId}. Injectable so the result is
+ *   deterministic in tests.
+ * @returns a new `Project` with fresh ids throughout
+ */
+export function reidentifyProject(project, newId = generateId) {
+    const idMap = buildIdMap(collectIds(project), newId);
+    const mapId = (id) => idMap.get(id) ?? id;
+    const mapRef = (id) => (id === undefined ? undefined : mapId(id));
+    const mapWssRef = (ref) => ({
+        ...ref,
+        id: mapId(ref.id),
+        document: remapValue(ref.document, idMap),
+    });
+    const reidentifyAttachment = (attachment) => {
+        const id = mapId(attachment.id);
+        const hadDefaultContentId = attachment.contentId === defaultContentId(attachment.id);
+        return {
+            ...attachment,
+            id,
+            contentId: hadDefaultContentId ? defaultContentId(id) : attachment.contentId,
+        };
+    };
+    const reidentifyRequest = (request) => ({
+        ...request,
+        id: mapId(request.id),
+        ...optional('endpointId', mapRef(request.endpointId)),
+        ...optional('wssOutgoingRef', mapRef(request.wssOutgoingRef)),
+        ...optional('wssIncomingRef', mapRef(request.wssIncomingRef)),
+        attachments: request.attachments.map(reidentifyAttachment),
+        properties: { ...request.properties, ...optional('sslKeystoreRef', mapRef(request.properties.sslKeystoreRef)) },
+    });
+    return {
+        ...project,
+        id: mapId(project.id),
+        interfaces: project.interfaces.map((iface) => ({
+            ...iface,
+            id: mapId(iface.id),
+            endpoints: iface.endpoints.map((endpoint) => ({ ...endpoint, id: mapId(endpoint.id) })),
+            ...optional('defaultEndpointId', mapRef(iface.defaultEndpointId)),
+            operations: iface.operations.map((operation) => ({
+                ...operation,
+                requests: operation.requests.map(reidentifyRequest),
+            })),
+        })),
+        environments: project.environments.map((environment) => ({ ...environment, id: mapId(environment.id) })),
+        ...optional('activeEnvironmentId', mapRef(project.activeEnvironmentId)),
+        wss: {
+            outgoing: project.wss.outgoing.map(mapWssRef),
+            incoming: project.wss.incoming.map(mapWssRef),
+            keystores: project.wss.keystores.map(mapWssRef),
+        },
+    };
+}

package/dist/workspace/save.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Writes a {@link Workspace} to a workspace folder. Mirrors `project/save.ts`:
+ * saving is incremental (only changed files are rewritten) and every write
+ * goes through a temp file plus `rename`. Unlike a project, a workspace format
+ * carries no backup mechanism, so {@link SaveResult.backups} is always `[]`.
+ *
+ * Only the workspace's own subtree is managed here (`workspace.yaml` and
+ * `environments/*.yaml`); `projects/<slug>` — an internal project's own
+ * folder — is owned and saved by the project module, not this one.
+ */
+import type { SaveResult } from '../project/save.js';
+import type { FsLike } from '../project/fs.js';
+import type { Workspace } from './model.js';
+import type { WorkspaceFiles } from './serialize.js';
+/** Options for {@link saveWorkspace}. */
+export interface SaveWorkspaceOptions {
+    /**
+     * The files as they were last written. When supplied, unchanged files are
+     * detected without reading them back from disk; when omitted, the current
+     * on-disk bytes are read and compared instead.
+     */
+    readonly previous?: WorkspaceFiles;
+    readonly fs?: FsLike;
+}
+/**
+ * Saves `workspace` into the directory `root`, creating it if needed.
+ *
+ * @returns which files were written, removed and left untouched. `backups` is
+ * always `[]` — the workspace format has none.
+ */
+export declare function saveWorkspace(workspace: Workspace, root: string, options?: SaveWorkspaceOptions): Promise<SaveResult>;

package/dist/workspace/save.js

@@ -0,0 +1,84 @@
+/**
+ * Writes a {@link Workspace} to a workspace folder. Mirrors `project/save.ts`:
+ * saving is incremental (only changed files are rewritten) and every write
+ * goes through a temp file plus `rename`. Unlike a project, a workspace format
+ * carries no backup mechanism, so {@link SaveResult.backups} is always `[]`.
+ *
+ * Only the workspace's own subtree is managed here (`workspace.yaml` and
+ * `environments/*.yaml`); `projects/<slug>` — an internal project's own
+ * folder — is owned and saved by the project module, not this one.
+ */
+import { join } from 'node:path';
+import { nodeFs, readFileIfExists, readdirIfExists, writeFileAtomic } from '../project/fs.js';
+import { WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST } from './paths.js';
+import { workspaceFiles } from './serialize.js';
+function toAbsolute(root, relative) {
+    return join(root, ...relative.split('/'));
+}
+/**
+ * Lists every file this format manages under `root`: `workspace.yaml` and
+ * `environments/*.yaml`. Anything else — a README, a foreign file dropped
+ * into `environments/` — is never a deletion candidate.
+ */
+async function listManagedFiles(fs, root) {
+    const managed = [];
+    if ((await readFileIfExists(fs, toAbsolute(root, WORKSPACE_MANIFEST))) !== undefined) {
+        managed.push(WORKSPACE_MANIFEST);
+    }
+    for (const entry of await readdirIfExists(fs, toAbsolute(root, WORKSPACE_ENVIRONMENTS_DIR))) {
+        if (entry.isFile && entry.name.endsWith('.yaml')) {
+            managed.push(`${WORKSPACE_ENVIRONMENTS_DIR}/${entry.name}`);
+        }
+    }
+    return managed;
+}
+/**
+ * Saves `workspace` into the directory `root`, creating it if needed.
+ *
+ * @returns which files were written, removed and left untouched. `backups` is
+ * always `[]` — the workspace format has none.
+ */
+export async function saveWorkspace(workspace, root, options) {
+    const fs = options?.fs ?? nodeFs;
+    const desired = workspaceFiles(workspace);
+    const existing = await listManagedFiles(fs, root);
+    const written = [];
+    const unchanged = [];
+    for (const [relative, content] of desired) {
+        const absolute = toAbsolute(root, relative);
+        // When a `previous` map was supplied, trust it as the full picture (a missing key means
+        // "not previously written", not "go check disk"); only fall back to a real disk read when
+        // no `previous` map was given at all.
+        const previous = options?.previous?.get(relative) ??
+            (options?.previous !== undefined ? undefined : (await readFileIfExists(fs, absolute))?.toString('utf8'));
+        if (previous === content) {
+            unchanged.push(relative);
+            continue;
+        }
+        await writeFileAtomic(fs, absolute, Buffer.from(content, 'utf8'));
+        written.push(relative);
+    }
+    const removed = [];
+    let environmentsDirTouched = false;
+    for (const relative of existing) {
+        if (desired.has(relative)) {
+            continue;
+        }
+        await fs.rm(toAbsolute(root, relative), { force: true });
+        removed.push(relative);
+        if (relative.startsWith(`${WORKSPACE_ENVIRONMENTS_DIR}/`)) {
+            environmentsDirTouched = true;
+        }
+    }
+    if (environmentsDirTouched) {
+        const remaining = await readdirIfExists(fs, toAbsolute(root, WORKSPACE_ENVIRONMENTS_DIR));
+        if (remaining.length === 0) {
+            await fs.rm(toAbsolute(root, WORKSPACE_ENVIRONMENTS_DIR), { recursive: true, force: true });
+            removed.push(WORKSPACE_ENVIRONMENTS_DIR);
+        }
+    }
+    written.sort();
+    removed.sort();
+    unchanged.sort();
+    return { written, removed, unchanged, backups: [] };
+}

package/dist/workspace/schema.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Zod schemas for every YAML document in a workspace folder.
+ *
+ * Mirrors `project/schema.ts`'s discipline: every object schema is
+ * `z.looseObject` (unknown keys accepted and ignored on load — see that
+ * file's doc comment for the "additive bumps formatVersion" policy this
+ * implies), and `formatVersion` stays a `z.literal` so an out-of-range value
+ * is still caught explicitly (see `migrate.ts`).
+ */
+import { z } from 'zod';
+/** One `workspace.yaml` `projects` entry, as persisted. */
+export declare const workspaceProjectRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    source: z.ZodLiteral<"internal">;
+}, z.core.$loose>, z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    source: z.ZodLiteral<"linked">;
+    path: z.ZodString;
+}, z.core.$loose>], "source">;
+/** `workspace.yaml`. */
+export declare const workspaceManifestSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<3>;
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodString>;
+    disabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    projects: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        source: z.ZodLiteral<"internal">;
+    }, z.core.$loose>, z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        source: z.ZodLiteral<"linked">;
+        path: z.ZodString;
+    }, z.core.$loose>], "source">>;
+}, z.core.$loose>;
+/** `environments/<slug>.yaml`. */
+export declare const workspaceEnvironmentFileSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    order: z.ZodNumber;
+    properties: z.ZodRecord<z.ZodString, z.ZodString>;
+    endpoints: z.ZodRecord<z.ZodString, z.ZodString>;
+    disabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+/** `local.yaml`: machine-local state, never part of the shared tree. See `local-state.ts`. */
+export declare const workspaceLocalStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    activeEnvironmentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `share.yaml`: absent means a local workspace. `path`, when set, must be absolute — it is only
+ * ever written from a native folder picker. `kind: 'git'` requires `git`; `kind: 'server'`
+ * requires `server`.
+ */
+export declare const workspaceShareSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        folder: "folder";
+        server: "server";
+        git: "git";
+    }>;
+    path: z.ZodOptional<z.ZodString>;
+    git: z.ZodOptional<z.ZodObject<{
+        remote: z.ZodOptional<z.ZodString>;
+        branch: z.ZodString;
+        autoFetchSeconds: z.ZodNumber;
+        commitOnSave: z.ZodBoolean;
+        pushOnSave: z.ZodBoolean;
+    }, z.core.$strip>>;
+    server: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        workspaceId: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The manifest document as persisted. */
+export type WorkspaceManifestFile = z.infer<typeof workspaceManifestSchema>;
+/** One `projects` entry as persisted. */
+export type WorkspaceProjectRefFile = z.infer<typeof workspaceProjectRefSchema>;
+/** An environment document as persisted. */
+export type WorkspaceEnvironmentFile = z.infer<typeof workspaceEnvironmentFileSchema>;
+/**
+ * Validates `value` against `schema`, raising
+ * `WorkspaceError('workspace-file-invalid')` carrying the file path and the
+ * individual zod issues when it does not match. Mirrors `project/schema.ts`'s
+ * `parseFile`, distinct only in which error class it throws.
+ */
+export declare function parseWorkspaceFile<T>(schema: z.ZodType<T>, value: unknown, file: string): T;

package/dist/workspace/schema.js

@@ -0,0 +1,115 @@
+/**
+ * Zod schemas for every YAML document in a workspace folder.
+ *
+ * Mirrors `project/schema.ts`'s discipline: every object schema is
+ * `z.looseObject` (unknown keys accepted and ignored on load — see that
+ * file's doc comment for the "additive bumps formatVersion" policy this
+ * implies), and `formatVersion` stays a `z.literal` so an out-of-range value
+ * is still caught explicitly (see `migrate.ts`).
+ */
+import { isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { WorkspaceError } from '../errors.js';
+import { WORKSPACE_FORMAT_VERSION } from './model.js';
+const nonEmpty = z.string().min(1);
+const propertyMapSchema = z.record(z.string(), z.string());
+const workspaceProjectRefInternalSchema = z.looseObject({
+    id: nonEmpty,
+    slug: nonEmpty,
+    source: z.literal('internal'),
+});
+/** A linked project ref's `path` must be absolute — a workspace never stores a path relative to itself. */
+const workspaceProjectRefLinkedSchema = z
+    .looseObject({
+    id: nonEmpty,
+    slug: nonEmpty,
+    source: z.literal('linked'),
+    path: nonEmpty,
+})
+    .refine((value) => isAbsolute(value.path), {
+    message: 'a linked project reference path must be absolute',
+    path: ['path'],
+});
+/** One `workspace.yaml` `projects` entry, as persisted. */
+export const workspaceProjectRefSchema = z.discriminatedUnion('source', [
+    workspaceProjectRefInternalSchema,
+    workspaceProjectRefLinkedSchema,
+]);
+/** `workspace.yaml`. */
+export const workspaceManifestSchema = z.looseObject({
+    formatVersion: z.literal(WORKSPACE_FORMAT_VERSION),
+    id: nonEmpty,
+    name: z.string(),
+    description: z.string().optional(),
+    createdAt: nonEmpty,
+    properties: propertyMapSchema,
+    /** Names of `properties` entries switched off; absent means none. See `model.ts`. */
+    disabled: z.array(z.string()).optional(),
+    projects: z.array(workspaceProjectRefSchema),
+});
+/** `environments/<slug>.yaml`. */
+export const workspaceEnvironmentFileSchema = z.looseObject({
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    properties: propertyMapSchema,
+    endpoints: z.record(z.string(), z.string()),
+    /** Names of `properties` entries switched off; absent means none. */
+    disabled: z.array(z.string()).optional(),
+});
+/** `local.yaml`: machine-local state, never part of the shared tree. See `local-state.ts`. */
+export const workspaceLocalStateSchema = z.object({
+    version: z.literal(1),
+    activeEnvironmentId: z.string().optional(),
+});
+/** `share.yaml`'s `git` block: settings for a git-backed share. See `share.ts`. */
+const gitShareSettingsSchema = z.object({
+    remote: z.string().optional(),
+    branch: nonEmpty,
+    autoFetchSeconds: z.number().int().min(0),
+    commitOnSave: z.boolean(),
+    pushOnSave: z.boolean(),
+});
+/**
+ * `share.yaml`: absent means a local workspace. `path`, when set, must be absolute — it is only
+ * ever written from a native folder picker. `kind: 'git'` requires `git`; `kind: 'server'`
+ * requires `server`.
+ */
+export const workspaceShareSchema = z
+    .object({
+    version: z.literal(1),
+    kind: z.enum(['folder', 'git', 'server']),
+    path: z
+        .string()
+        .optional()
+        .refine((value) => value === undefined || isAbsolute(value), { message: 'path must be absolute' }),
+    git: gitShareSettingsSchema.optional(),
+    server: z.object({ url: nonEmpty, workspaceId: nonEmpty }).optional(),
+})
+    .refine((value) => value.kind !== 'git' || value.git !== undefined, {
+    message: 'kind: git requires a git block',
+    path: ['git'],
+})
+    .refine((value) => value.kind !== 'server' || value.server !== undefined, {
+    message: 'kind: server requires a server block',
+    path: ['server'],
+});
+/**
+ * Validates `value` against `schema`, raising
+ * `WorkspaceError('workspace-file-invalid')` carrying the file path and the
+ * individual zod issues when it does not match. Mirrors `project/schema.ts`'s
+ * `parseFile`, distinct only in which error class it throws.
+ */
+export function parseWorkspaceFile(schema, value, file) {
+    const result = schema.safeParse(value);
+    if (result.success) {
+        return result.data;
+    }
+    const issues = result.error.issues.map((issue) => ({
+        path: issue.path.join('.'),
+        message: issue.message,
+    }));
+    throw new WorkspaceError('workspace-file-invalid', `Invalid workspace file ${file}`, {
+        details: { file, issues },
+    });
+}

package/dist/workspace/serialize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Turns a {@link Workspace} into the exact set of files it occupies on disk.
+ *
+ * Mirrors `project/serialize.ts`: pure (workspace in, `relative path -> file
+ * content` out), so `saveWorkspace` only has to diff two maps and tests can
+ * assert on the layout without touching a file system. `compact` and
+ * `stringifyYaml` are the same format-agnostic helpers `project/serialize.ts`
+ * uses (sorted keys, no line wrapping, `undefined` fields dropped).
+ */
+import type { Workspace } from './model.js';
+/** A workspace's files, keyed by path relative to the workspace root (always `/`-separated). */
+export type WorkspaceFiles = ReadonlyMap<string, string>;
+/**
+ * Builds the complete `relative path -> content` map for a workspace.
+ *
+ * Every environment slug is validated with {@link assertPathSegment} before
+ * any path is built, so a corrupted slug throws
+ * `WorkspaceError('workspace-path-invalid')` here — before `saveWorkspace`
+ * ever touches the file system.
+ *
+ * `activeEnvironmentId` (machine-local, see `model.ts`) and `writtenBy` (dropped outright) never
+ * appear in the written manifest — see `local-state.ts` for where the former actually lives.
+ */
+export declare function workspaceFiles(workspace: Workspace): WorkspaceFiles;

package/dist/workspace/serialize.js

@@ -0,0 +1,60 @@
+/**
+ * Turns a {@link Workspace} into the exact set of files it occupies on disk.
+ *
+ * Mirrors `project/serialize.ts`: pure (workspace in, `relative path -> file
+ * content` out), so `saveWorkspace` only has to diff two maps and tests can
+ * assert on the layout without touching a file system. `compact` and
+ * `stringifyYaml` are the same format-agnostic helpers `project/serialize.ts`
+ * uses (sorted keys, no line wrapping, `undefined` fields dropped).
+ */
+import { assertPathSegment, WORKSPACE_ENVIRONMENTS_DIR, WORKSPACE_MANIFEST } from './paths.js';
+import { compact, stringifyYaml } from '../project/yaml.js';
+function projectRefDocument(ref) {
+    return compact({ id: ref.id, slug: ref.slug, source: ref.source, path: ref.path });
+}
+/**
+ * The `disabled` list as written: sorted, deduplicated, and dropped entirely once it would be
+ * empty — a name with no entry left in `properties` never outlives its map. Mirrors
+ * `project/serialize.ts`'s helper of the same purpose.
+ */
+function disabledList(disabled, properties) {
+    const known = new Set(Object.keys(properties));
+    const kept = [...new Set(disabled.filter((name) => known.has(name)))].sort();
+    return kept.length > 0 ? kept : undefined;
+}
+/**
+ * Builds the complete `relative path -> content` map for a workspace.
+ *
+ * Every environment slug is validated with {@link assertPathSegment} before
+ * any path is built, so a corrupted slug throws
+ * `WorkspaceError('workspace-path-invalid')` here — before `saveWorkspace`
+ * ever touches the file system.
+ *
+ * `activeEnvironmentId` (machine-local, see `model.ts`) and `writtenBy` (dropped outright) never
+ * appear in the written manifest — see `local-state.ts` for where the former actually lives.
+ */
+export function workspaceFiles(workspace) {
+    const files = new Map();
+    files.set(WORKSPACE_MANIFEST, stringifyYaml(compact({
+        formatVersion: workspace.formatVersion,
+        id: workspace.id,
+        name: workspace.name,
+        description: workspace.description,
+        createdAt: workspace.createdAt,
+        properties: { ...workspace.properties },
+        disabled: disabledList(workspace.disabledProperties, workspace.properties),
+        projects: workspace.projects.map((ref) => projectRefDocument(ref)),
+    })));
+    for (const environment of workspace.environments) {
+        assertPathSegment(environment.slug);
+        files.set(`${WORKSPACE_ENVIRONMENTS_DIR}/${environment.slug}.yaml`, stringifyYaml(compact({
+            id: environment.id,
+            name: environment.name,
+            order: environment.order,
+            properties: { ...environment.properties },
+            endpoints: { ...environment.endpoints },
+            disabled: disabledList(environment.disabledProperties, environment.properties),
+        })));
+    }
+    return files;
+}