@powerduck/workspace-yaml 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Powerduck limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# @powerduck/workspace-yaml
+
+> Initialize workspace.yaml and OpenAPI 3.2 YAML files with confidence.
+
+Production-grade YAML workspace initializer with a two-layer architecture:
+- **Core layer** (browser-safe): Pure functions that generate YAML content strings. No filesystem access.
+- **File layer** (Node.js / Electron): Wraps the core layer with atomic writes, file locking, and path normalization — all reused from [`@powerduck/conf-patch`](https://github.com/PowerDuckie/conf-patch).
+
+## Why this library?
+
+This library **only initializes files** — the "new file" / "manual creation" scenario. It does **not** reimplement reading, patching, or updating YAML files. For those operations, use `@powerduck/conf-patch` directly.
+
+- **No redundant IO**: Atomic writes, file locks, and path handling are delegated to `@powerduck/conf-patch`.
+- **No redundant validation**: OpenAPI validation is delegated to `@powerduck/openapi-parser`.
+- **Browser-safe core**: Generate YAML content in any JavaScript environment.
+- **Transaction-safe**: `createWorkspaceApi` writes both files atomically with rollback on failure.
+
+## Installation
+
+```bash
+npm install @powerduck/workspace-yaml
+```
+
+Peer dependencies (automatically installed):
+- `@powerduck/conf-patch` — atomic writes, file locking, path normalization
+- `@powerduck/openapi-parser` — OpenAPI validation and upgrade
+- `yaml` — YAML parsing and serialization
+
+## Quick Start
+
+### Node.js / Electron
+
+```typescript
+import { createWorkspaceApi } from "@powerduck/workspace-yaml";
+
+const { workspaceFilePath, openApiFilePath } = await createWorkspaceApi({
+  workspaceDirectory: "./my-project",
+  oasId: "users-api",
+  name: "Users API",
+  title: "Users API Documentation",
+  version: "1.0.0",
+});
+
+console.log("Workspace:", workspaceFilePath);
+console.log("OpenAPI:", openApiFilePath);
+```
+
+### Browser (no filesystem)
+
+```typescript
+import { createWorkspaceYaml, createOpenApiYaml } from "@powerduck/workspace-yaml/core";
+
+// Generate YAML content strings — save to IndexedDB, localStorage, or send to an API
+const workspaceContent = createWorkspaceYaml();
+const openApiContent = createOpenApiYaml({ title: "My API" });
+```
+
+## Two-Layer Architecture
+
+### Core Layer (`@powerduck/workspace-yaml/core`)
+
+Browser-safe pure functions. Zero filesystem dependencies.
+
+| Function | Description |
+|---|---|
+| `createWorkspaceYaml(options?)` | Generate a workspace.yaml content string |
+| `createOpenApiYaml(options)` | Generate an OpenAPI 3.2 YAML content string |
+| `createWorkspaceWithApi(options)` | Generate both workspace and OpenAPI content together |
+| `parseWorkspaceYaml(content)` | Parse and validate a workspace.yaml content string |
+
+### File Layer (`@powerduck/workspace-yaml`)
+
+Node.js / Electron only. Reuses `@powerduck/conf-patch` for IO.
+
+| Function | Description |
+|---|---|
+| `initializeWorkspace(options)` | Create a workspace.yaml file on disk |
+| `initializeOpenApi(options)` | Create an OpenAPI 3.2 YAML file on disk |
+| `createWorkspaceApi(options)` | Create both workspace and OpenAPI files atomically |
+
+## API Reference
+
+### Core Layer
+
+#### `createWorkspaceYaml(options?)`
+
+Generates a workspace.yaml content string.
+
+```typescript
+import { createWorkspaceYaml } from "@powerduck/workspace-yaml/core";
+
+const yaml = createWorkspaceYaml({
+  activeOasFileId: "api-v1",
+  oasFiles: [
+    { id: "api-v1", name: "API v1", file: "oasFiles/api-v1.openapi.yaml" },
+  ],
+});
+```
+
+**Options:**
+- `activeOasFileId?: string | null` — Initial active API file id (default: `null`)
+- `oasFiles?: OasFileEntry[]` — Initial API file entries (default: `[]`)
+
+**Returns:** `string` — YAML content
+
+**Throws:** `WorkspaceYamlError` on invalid input (duplicate ids, activeOasFileId not in oasFiles, invalid paths, etc.)
+
+---
+
+#### `createOpenApiYaml(options)`
+
+Generates an OpenAPI 3.2 YAML content string.
+
+```typescript
+import { createOpenApiYaml } from "@powerduck/workspace-yaml/core";
+
+const yaml = createOpenApiYaml({
+  title: "My API",
+  version: "2.0.0",
+  description: "A production-ready API.",
+  contact: { name: "API Team", email: "api@example.com" },
+  license: { name: "MIT", url: "https://opensource.org/licenses/MIT" },
+  servers: [{ url: "https://api.example.com", description: "Production" }],
+});
+```
+
+**Options:**
+- `title: string` — API title (required)
+- `version?: string` — API version (default: `"1.0.0"`)
+- `description?: string` — API description
+- `contact?: { name?, url?, email? }` — Contact information
+- `license?: { name, url? }` — License information
+- `servers?: Array<{ url, description? }>` — Server list
+
+**Returns:** `string` — YAML content
+
+**Throws:** `WorkspaceYamlError` on empty title or version
+
+---
+
+#### `createWorkspaceWithApi(options)`
+
+Generates both workspace and OpenAPI content together. The workspace will contain a single API entry and set it as active.
+
+```typescript
+import { createWorkspaceWithApi } from "@powerduck/workspace-yaml/core";
+
+const { workspaceYaml, openApiYaml, openApiRelativePath, workspace } =
+  createWorkspaceWithApi({
+    oasId: "my-api",
+    name: "My API",
+    title: "My API Documentation",
+    version: "1.0.0",
+    description: "Detailed description.",
+  });
+```
+
+**Options:**
+- `oasId: string` — Unique API identifier (required)
+- `name: string` — Display name (required)
+- `file?: string` — Workspace-relative path (default: `oasFiles/${oasId}.openapi.yaml`)
+- `title?: string` — API title (default: `name`)
+- `version?: string` — API version (default: `"1.0.0"`)
+- `description?: string` — API description
+
+**Returns:** `WorkspaceWithApiResult`
+- `workspaceYaml: string`
+- `openApiYaml: string`
+- `openApiRelativePath: string`
+- `workspace: WorkspaceConfig`
+
+---
+
+#### `parseWorkspaceYaml(content)`
+
+Parses and validates a workspace.yaml content string.
+
+```typescript
+import { parseWorkspaceYaml } from "@powerduck/workspace-yaml/core";
+
+const workspace = parseWorkspaceYaml(yamlContent);
+console.log(workspace.oasFiles);
+```
+
+**Returns:** `WorkspaceConfig`
+
+**Throws:** `WorkspaceYamlError` on invalid YAML, wrong version, duplicate ids, etc.
+
+---
+
+### File Layer
+
+#### `initializeWorkspace(options)`
+
+Creates a workspace.yaml file on disk. Uses `@powerduck/conf-patch` for atomic writes and file locking.
+
+```typescript
+import { initializeWorkspace } from "@powerduck/workspace-yaml";
+
+const { filePath, workspace } = await initializeWorkspace({
+  directory: "./my-project",
+  workspaceFileName: "workspace.yaml", // optional
+  overwrite: false, // optional, default: false
+  activeOasFileId: null, // optional
+  oasFiles: [], // optional
+});
+```
+
+---
+
+#### `initializeOpenApi(options)`
+
+Creates an OpenAPI 3.2 YAML file on disk.
+
+```typescript
+import { initializeOpenApi } from "@powerduck/workspace-yaml";
+
+const { filePath, title, version } = await initializeOpenApi({
+  filePath: "./my-project/oasFiles/my-api.openapi.yaml",
+  title: "My API",
+  version: "1.0.0",
+  description: "Optional description.",
+  overwrite: false, // optional, default: false
+});
+```
+
+---
+
+#### `createWorkspaceApi(options)`
+
+Creates both workspace and OpenAPI files atomically. If the workspace write fails, the OpenAPI file is rolled back.
+
+If a workspace already exists, the new API is added to it.
+
+```typescript
+import { createWorkspaceApi } from "@powerduck/workspace-yaml";
+
+const { workspaceFilePath, openApiFilePath, workspace } = await createWorkspaceApi({
+  workspaceDirectory: "./my-project",
+  oasId: "my-api",
+  name: "My API",
+  file: "custom/path/api.yaml", // optional
+  title: "My API Documentation", // optional, defaults to name
+  version: "1.0.0", // optional
+  description: "Optional.", // optional
+  overwriteOpenApi: false, // optional, default: false
+});
+```
+
+## Error Handling
+
+All errors are instances of `WorkspaceYamlError` with a machine-readable `code`:
+
+```typescript
+import { WorkspaceYamlError } from "@powerduck/workspace-yaml";
+
+try {
+  await createWorkspaceApi({ /* ... */ });
+} catch (error) {
+  if (error instanceof WorkspaceYamlError) {
+    console.error(`Error [${error.code}]: ${error.message}`);
+    console.error(`File: ${error.filePath}`);
+  }
+}
+```
+
+**Error codes:**
+- `INVALID_ARGUMENT` — Invalid input parameter
+- `ALREADY_EXISTS` — File already exists (and overwrite is false)
+- `NOT_FOUND` — File not found
+- `IO_ERROR` — Filesystem operation failed
+- `INVALID_WORKSPACE` — Invalid workspace configuration
+- `INVALID_OPENAPI` — Invalid OpenAPI document
+- `ROLLBACK_FAILED` — Transaction rollback failed
+
+## Reading and Updating Files
+
+This library only **initializes** files. To read, patch, or update existing files, use `@powerduck/conf-patch`:
+
+```typescript
+import { readConfigFile, setConfigValue, patchConfigFile } from "@powerduck/conf-patch";
+
+// Read
+const workspace = await readConfigFile("./my-project/workspace.yaml");
+
+// Update a single value
+await setConfigValue("./my-project/workspace.yaml", "activeOasFileId", "new-api");
+
+// Batch patch (RFC 6902)
+await patchConfigFile("./my-project/workspace.yaml", [
+  { op: "add", path: "/oasFiles/-", value: { id: "new-api", name: "New API", file: "..." } },
+]);
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Watch mode
+npm run test:watch
+```
+
+## Demos
+
+```bash
+# Node.js / Electron demo (file layer)
+npm run demo
+
+# Browser-safe demo (core layer only)
+npm run demo:browser
+```
+
+## Building
+
+```bash
+npm run build
+```
+
+Outputs:
+- `dist/index.js` — ESM build (file layer + core layer)
+- `dist/index.cjs` — CJS build
+- `dist/core.js` — ESM build (core layer only, browser-safe)
+- `dist/core.cjs` — CJS build
+- TypeScript declarations (`.d.ts`)
+
+## License
+
+MIT © Powerduck limited
+
+## Related Packages
+
+- [`@powerduck/conf-patch`](https://github.com/PowerDuckie/conf-patch) — Two-layer configuration editor with atomic writes and locking
+- [`@powerduck/openapi-parser`](https://github.com/PowerDuckie/openapi-parser) — Upgrade and validate OpenAPI documents to 3.2

package/dist/chunk-6LICMPRI.cjs

@@ -0,0 +1 @@
+function e(e,t){return null!=e?e:t()}Object.defineProperty(exports,"__esModule",{value:!0});var t=class extends Error{constructor(e,t,i,s){super(t),this.name="WorkspaceYamlError",this.code=e,this.filePath=i,this.cause=s}},i=require("yaml"),s={indent:2,lineWidth:0,sortKeys:!1};function o(e,i){if("string"!=typeof e)throw new t("INVALID_ARGUMENT",`${i} must be a string.`);const s=e.trim();if(0===s.length)throw new t("INVALID_ARGUMENT",`${i} must not be empty.`);return s}function r(e,i){if(null===e||"object"!=typeof e)throw new t("INVALID_ARGUMENT",`oasFiles[${i}] must be an object.`);if(o(e.id,`oasFiles[${i}].id`),o(e.name,`oasFiles[${i}].name`),o(e.file,`oasFiles[${i}].file`),e.file.includes("\\"))throw new t("INVALID_ARGUMENT",`oasFiles[${i}].file must use POSIX path separators ("/"), not backslashes.`);if(e.file.startsWith("/"))throw new t("INVALID_ARGUMENT",`oasFiles[${i}].file must be a workspace-relative path, not absolute.`);if(!/\.ya?ml$/i.test(e.file))throw new t("INVALID_ARGUMENT",`oasFiles[${i}].file must have a .yaml or .yml extension.`)}function n(e){if(1!==e.version)throw new t("INVALID_WORKSPACE",`workspace version must be 1, got: ${String(e.version)}.`);if(null!==e.activeOasFileId&&"string"!=typeof e.activeOasFileId)throw new t("INVALID_WORKSPACE","activeOasFileId must be a string or null.");if(!Array.isArray(e.oasFiles))throw new t("INVALID_WORKSPACE","oasFiles must be an array.");const i=new Set;for(let s=0;s<e.oasFiles.length;s++){const o=e.oasFiles[s];if(r(o,s),i.has(o.id))throw new t("INVALID_WORKSPACE",`Duplicate oasFiles id: "${o.id}".`);i.add(o.id)}if(null!==e.activeOasFileId&&!i.has(e.activeOasFileId))throw new t("INVALID_WORKSPACE",`activeOasFileId "${e.activeOasFileId}" does not exist in oasFiles.`)}function a(t){const r=function(t){const i={openapi:"3.2.0",info:{title:o(t.title,"title"),version:o(e(t.version,()=>"1.0.0"),"version")},paths:{}};return void 0!==t.description&&(i.info.description=t.description),void 0!==t.contact&&(i.info.contact=t.contact),void 0!==t.license&&(i.info.license=t.license),void 0!==t.servers&&t.servers.length>0&&(i.servers=t.servers),i}(t);return i.stringify.call(void 0,r,s)}exports.WorkspaceYamlError=t,exports.createWorkspaceYaml=function(t={}){const o=function(t){const i={version:1,activeOasFileId:e(t.activeOasFileId,()=>null),oasFiles:t.oasFiles?[...t.oasFiles]:[]};return n(i),i}(t);return i.stringify.call(void 0,o,s)},exports.createOpenApiYaml=a,exports.createWorkspaceWithApi=function(t){const r=o(t.oasId,"oasId"),l=o(t.name,"name"),c=function(t,i){let s=e(i,()=>`oasFiles/${t}.openapi.yaml`);for(s=s.replace(/\\/g,"/");s.startsWith("/");)s=s.slice(1);return/\.ya?ml$/i.test(s)||(s=`${s}.yaml`),s}(r,t.file),p={version:1,activeOasFileId:r,oasFiles:[{id:r,name:l,file:c}]};n(p);const f=a({title:e(t.title,()=>l),version:e(t.version,()=>"1.0.0"),description:t.description});return{workspaceYaml:i.stringify.call(void 0,p,s),openApiYaml:f,openApiRelativePath:c,workspace:p}},exports.parseWorkspaceYaml=function(e){if("string"!=typeof e||0===e.trim().length)throw new t("INVALID_WORKSPACE","Workspace content must be a non-empty string.");let s;try{const o=i.parseDocument.call(void 0,e,{prettyErrors:!0,strict:!0});if(o.errors.length>0)throw new t("INVALID_WORKSPACE",`Invalid YAML: ${o.errors.map(e=>e.message).join("; ")}`);s=o.toJS({mapAsMap:!1})}catch(e){if(e instanceof t)throw e;throw new t("INVALID_WORKSPACE",`Failed to parse workspace YAML: ${e instanceof Error?e.message:String(e)}`)}if(null===s||"object"!=typeof s||Array.isArray(s))throw new t("INVALID_WORKSPACE","Workspace must be a YAML mapping (object).");const o=s;return n(o),o};

package/dist/chunk-QMIGONFP.js

@@ -0,0 +1 @@
+var e=class extends Error{code;filePath;cause;constructor(e,t,i,s){super(t),this.name="WorkspaceYamlError",this.code=e,this.filePath=i,this.cause=s}};import{parseDocument as t,stringify as i}from"yaml";var s={indent:2,lineWidth:0,sortKeys:!1};function o(t,i){if("string"!=typeof t)throw new e("INVALID_ARGUMENT",`${i} must be a string.`);const s=t.trim();if(0===s.length)throw new e("INVALID_ARGUMENT",`${i} must not be empty.`);return s}function n(t,i){if(null===t||"object"!=typeof t)throw new e("INVALID_ARGUMENT",`oasFiles[${i}] must be an object.`);if(o(t.id,`oasFiles[${i}].id`),o(t.name,`oasFiles[${i}].name`),o(t.file,`oasFiles[${i}].file`),t.file.includes("\\"))throw new e("INVALID_ARGUMENT",`oasFiles[${i}].file must use POSIX path separators ("/"), not backslashes.`);if(t.file.startsWith("/"))throw new e("INVALID_ARGUMENT",`oasFiles[${i}].file must be a workspace-relative path, not absolute.`);if(!/\.ya?ml$/i.test(t.file))throw new e("INVALID_ARGUMENT",`oasFiles[${i}].file must have a .yaml or .yml extension.`)}function r(t){if(1!==t.version)throw new e("INVALID_WORKSPACE",`workspace version must be 1, got: ${String(t.version)}.`);if(null!==t.activeOasFileId&&"string"!=typeof t.activeOasFileId)throw new e("INVALID_WORKSPACE","activeOasFileId must be a string or null.");if(!Array.isArray(t.oasFiles))throw new e("INVALID_WORKSPACE","oasFiles must be an array.");const i=new Set;for(let s=0;s<t.oasFiles.length;s++){const o=t.oasFiles[s];if(n(o,s),i.has(o.id))throw new e("INVALID_WORKSPACE",`Duplicate oasFiles id: "${o.id}".`);i.add(o.id)}if(null!==t.activeOasFileId&&!i.has(t.activeOasFileId))throw new e("INVALID_WORKSPACE",`activeOasFileId "${t.activeOasFileId}" does not exist in oasFiles.`)}function a(e={}){const t=function(e){const t={version:1,activeOasFileId:e.activeOasFileId??null,oasFiles:e.oasFiles?[...e.oasFiles]:[]};return r(t),t}(e);return i(t,s)}function l(e){const t=function(e){const t={openapi:"3.2.0",info:{title:o(e.title,"title"),version:o(e.version??"1.0.0","version")},paths:{}};return void 0!==e.description&&(t.info.description=e.description),void 0!==e.contact&&(t.info.contact=e.contact),void 0!==e.license&&(t.info.license=e.license),void 0!==e.servers&&e.servers.length>0&&(t.servers=e.servers),t}(e);return i(t,s)}function c(e){const t=o(e.oasId,"oasId"),n=o(e.name,"name"),a=function(e,t){let i=t??`oasFiles/${e}.openapi.yaml`;for(i=i.replace(/\\/g,"/");i.startsWith("/");)i=i.slice(1);return/\.ya?ml$/i.test(i)||(i=`${i}.yaml`),i}(t,e.file),c={version:1,activeOasFileId:t,oasFiles:[{id:t,name:n,file:a}]};r(c);const f=l({title:e.title??n,version:e.version??"1.0.0",description:e.description});return{workspaceYaml:i(c,s),openApiYaml:f,openApiRelativePath:a,workspace:c}}function f(i){if("string"!=typeof i||0===i.trim().length)throw new e("INVALID_WORKSPACE","Workspace content must be a non-empty string.");let s;try{const o=t(i,{prettyErrors:!0,strict:!0});if(o.errors.length>0)throw new e("INVALID_WORKSPACE",`Invalid YAML: ${o.errors.map(e=>e.message).join("; ")}`);s=o.toJS({mapAsMap:!1})}catch(t){if(t instanceof e)throw t;throw new e("INVALID_WORKSPACE",`Failed to parse workspace YAML: ${t instanceof Error?t.message:String(t)}`)}if(null===s||"object"!=typeof s||Array.isArray(s))throw new e("INVALID_WORKSPACE","Workspace must be a YAML mapping (object).");const o=s;return r(o),o}export{e as WorkspaceYamlError,a as createWorkspaceYaml,l as createOpenApiYaml,c as createWorkspaceWithApi,f as parseWorkspaceYaml};

package/dist/core-DfwH7QX7.d.cts

@@ -0,0 +1,291 @@
+/**
+ * @powerduck/workspace-yaml
+ *
+ * Type definitions for workspace and OpenAPI YAML initialization.
+ * This module is browser-safe and contains no filesystem access.
+ */
+/**
+ * A single OpenAPI file entry in a workspace configuration.
+ */
+interface OasFileEntry {
+    /** Unique identifier for the API within the workspace. */
+    id: string;
+    /** Human-readable display name of the API. */
+    name: string;
+    /** Workspace-relative path to the OpenAPI YAML file (POSIX separators). */
+    file: string;
+}
+/**
+ * The workspace.yaml document structure.
+ */
+interface WorkspaceConfig {
+    /** Schema version, currently always 1. */
+    version: 1;
+    /** The currently active API file id, or null if none is active. */
+    activeOasFileId: string | null;
+    /** All registered OpenAPI files in this workspace. */
+    oasFiles: OasFileEntry[];
+}
+/**
+ * Options for creating a workspace.yaml content string.
+ */
+interface CreateWorkspaceOptions {
+    /** Optional initial active API file id. Defaults to null. */
+    activeOasFileId?: string | null;
+    /** Optional initial list of API file entries. Defaults to empty array. */
+    oasFiles?: OasFileEntry[];
+}
+/**
+ * Options for creating an OpenAPI 3.2 YAML content string.
+ */
+interface CreateOpenApiOptions {
+    /** API title. Required, must be non-empty after trimming. */
+    title: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Optional contact information. */
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    /** Optional license information. */
+    license?: {
+        name: string;
+        url?: string;
+    };
+    /** Optional servers list. */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+}
+/**
+ * Options for creating both a workspace and an OpenAPI file together.
+ */
+interface CreateWorkspaceWithApiOptions {
+    /** Unique identifier for the API. Required. */
+    oasId: string;
+    /** Display name of the API. Required. */
+    name: string;
+    /** Workspace-relative path for the OpenAPI file. Defaults to `oasFiles/${oasId}.openapi.yaml`. */
+    file?: string;
+    /** API title. Defaults to the name. */
+    title?: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+}
+/**
+ * Result of creating a workspace with an API.
+ */
+interface WorkspaceWithApiResult {
+    /** The generated workspace.yaml content. */
+    workspaceYaml: string;
+    /** The generated OpenAPI YAML content. */
+    openApiYaml: string;
+    /** The workspace-relative path of the OpenAPI file. */
+    openApiRelativePath: string;
+    /** The resolved workspace configuration. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Options for initializing a workspace file on disk.
+ */
+interface InitializeWorkspaceOptions {
+    /** Absolute or relative directory path where workspace.yaml will be created. */
+    directory: string;
+    /** Optional custom workspace file name. Defaults to "workspace.yaml". */
+    workspaceFileName?: string;
+    /** Whether to overwrite an existing file. Defaults to false. */
+    overwrite?: boolean;
+    /** Optional initial active API file id. */
+    activeOasFileId?: string | null;
+    /** Optional initial list of API file entries. */
+    oasFiles?: OasFileEntry[];
+}
+/**
+ * Options for initializing an OpenAPI file on disk.
+ */
+interface InitializeOpenApiOptions {
+    /** Absolute or relative path for the OpenAPI YAML file. */
+    filePath: string;
+    /** API title. Required. */
+    title: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Whether to overwrite an existing file. Defaults to false. */
+    overwrite?: boolean;
+}
+/**
+ * Options for creating a workspace with an API file on disk.
+ */
+interface CreateWorkspaceApiOptions {
+    /** Absolute or relative path to the workspace directory. */
+    workspaceDirectory: string;
+    /** Unique identifier for the API. Required. */
+    oasId: string;
+    /** Display name of the API. Required. */
+    name: string;
+    /** Workspace-relative path for the OpenAPI file. Defaults to `oasFiles/${oasId}.openapi.yaml`. */
+    file?: string;
+    /** API title. Defaults to the name. */
+    title?: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Whether to overwrite an existing OpenAPI file. Defaults to false. */
+    overwriteOpenApi?: boolean;
+}
+/**
+ * Result of initializing a workspace file.
+ */
+interface InitializeWorkspaceResult {
+    /** Absolute path to the created workspace.yaml file. */
+    filePath: string;
+    /** The workspace configuration that was written. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Result of initializing an OpenAPI file.
+ */
+interface InitializeOpenApiResult {
+    /** Absolute path to the created OpenAPI YAML file. */
+    filePath: string;
+    /** The OpenAPI document title. */
+    title: string;
+    /** The OpenAPI document version. */
+    version: string;
+}
+/**
+ * Result of creating a workspace with an API file on disk.
+ */
+interface CreateWorkspaceApiResult {
+    /** Absolute path to the workspace.yaml file. */
+    workspaceFilePath: string;
+    /** Absolute path to the OpenAPI YAML file. */
+    openApiFilePath: string;
+    /** The workspace configuration that was written. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Error codes for workspace-yaml operations.
+ */
+type WorkspaceYamlErrorCode = "INVALID_ARGUMENT" | "ALREADY_EXISTS" | "NOT_FOUND" | "IO_ERROR" | "INVALID_WORKSPACE" | "INVALID_OPENAPI" | "ROLLBACK_FAILED";
+/**
+ * Custom error class for workspace-yaml operations.
+ */
+declare class WorkspaceYamlError extends Error {
+    readonly code: WorkspaceYamlErrorCode;
+    readonly filePath?: string;
+    readonly cause?: unknown;
+    constructor(code: WorkspaceYamlErrorCode, message: string, filePath?: string, cause?: unknown);
+}
+
+/**
+ * Core layer — browser-safe pure functions for generating YAML content.
+ *
+ * This module has zero filesystem dependencies and works in browsers,
+ * Node.js, Electron, and any JavaScript environment.
+ *
+ * It generates:
+ * - workspace.yaml content
+ * - OpenAPI 3.2 YAML content
+ * - Both together (workspace + API)
+ */
+
+/**
+ * Creates a workspace.yaml content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * @param options - Workspace creation options
+ * @returns The workspace.yaml content as a YAML string
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceYaml } from "@powerduck/workspace-yaml/core";
+ *
+ * const yaml = createWorkspaceYaml({
+ *   activeOasFileId: "api-v1",
+ *   oasFiles: [
+ *     { id: "api-v1", name: "API v1", file: "oasFiles/api-v1.openapi.yaml" },
+ *   ],
+ * });
+ * // => "version: 1\nactiveOasFileId: api-v1\noasFiles:\n  - ..."
+ * ```
+ */
+declare function createWorkspaceYaml(options?: CreateWorkspaceOptions): string;
+/**
+ * Creates an OpenAPI 3.2 YAML content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * The generated document is a minimal but valid OpenAPI 3.2 spec
+ * with empty paths, ready for the user to add endpoints.
+ *
+ * @param options - OpenAPI creation options
+ * @returns The OpenAPI 3.2 YAML content as a string
+ *
+ * @example
+ * ```typescript
+ * import { createOpenApiYaml } from "@powerduck/workspace-yaml/core";
+ *
+ * const yaml = createOpenApiYaml({
+ *   title: "My API",
+ *   version: "2.0.0",
+ *   description: "A sample API",
+ * });
+ * // => "openapi: 3.2.0\ninfo:\n  title: My API\n  version: 2.0.0\npaths: {}"
+ * ```
+ */
+declare function createOpenApiYaml(options: CreateOpenApiOptions): string;
+/**
+ * Creates both a workspace.yaml and an OpenAPI 3.2 YAML content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * The workspace will contain a single API entry pointing to the
+ * generated OpenAPI file, and that API will be set as active.
+ *
+ * @param options - Options for creating workspace + API
+ * @returns Object containing both YAML strings and metadata
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceWithApi } from "@powerduck/workspace-yaml/core";
+ *
+ * const { workspaceYaml, openApiYaml, openApiRelativePath } = createWorkspaceWithApi({
+ *   oasId: "my-api",
+ *   name: "My API",
+ *   title: "My API Documentation",
+ *   version: "1.0.0",
+ * });
+ *
+ * // Save workspaceYaml to workspace.yaml
+ * // Save openApiYaml to oasFiles/my-api.openapi.yaml
+ * ```
+ */
+declare function createWorkspaceWithApi(options: CreateWorkspaceWithApiOptions): WorkspaceWithApiResult;
+/**
+ * Validates a workspace.yaml content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * @param content - The raw YAML content to validate
+ * @returns The parsed and validated workspace config
+ * @throws WorkspaceYamlError if the content is invalid
+ */
+declare function parseWorkspaceYaml(content: string): WorkspaceConfig;
+
+export { type CreateWorkspaceApiOptions as C, type InitializeOpenApiOptions as I, type OasFileEntry as O, type WorkspaceConfig as W, type CreateWorkspaceApiResult as a, type InitializeOpenApiResult as b, type InitializeWorkspaceOptions as c, type InitializeWorkspaceResult as d, type CreateOpenApiOptions as e, type CreateWorkspaceOptions as f, type CreateWorkspaceWithApiOptions as g, type WorkspaceWithApiResult as h, WorkspaceYamlError as i, type WorkspaceYamlErrorCode as j, createOpenApiYaml as k, createWorkspaceWithApi as l, createWorkspaceYaml as m, parseWorkspaceYaml as p };

package/dist/core-DfwH7QX7.d.ts

@@ -0,0 +1,291 @@
+/**
+ * @powerduck/workspace-yaml
+ *
+ * Type definitions for workspace and OpenAPI YAML initialization.
+ * This module is browser-safe and contains no filesystem access.
+ */
+/**
+ * A single OpenAPI file entry in a workspace configuration.
+ */
+interface OasFileEntry {
+    /** Unique identifier for the API within the workspace. */
+    id: string;
+    /** Human-readable display name of the API. */
+    name: string;
+    /** Workspace-relative path to the OpenAPI YAML file (POSIX separators). */
+    file: string;
+}
+/**
+ * The workspace.yaml document structure.
+ */
+interface WorkspaceConfig {
+    /** Schema version, currently always 1. */
+    version: 1;
+    /** The currently active API file id, or null if none is active. */
+    activeOasFileId: string | null;
+    /** All registered OpenAPI files in this workspace. */
+    oasFiles: OasFileEntry[];
+}
+/**
+ * Options for creating a workspace.yaml content string.
+ */
+interface CreateWorkspaceOptions {
+    /** Optional initial active API file id. Defaults to null. */
+    activeOasFileId?: string | null;
+    /** Optional initial list of API file entries. Defaults to empty array. */
+    oasFiles?: OasFileEntry[];
+}
+/**
+ * Options for creating an OpenAPI 3.2 YAML content string.
+ */
+interface CreateOpenApiOptions {
+    /** API title. Required, must be non-empty after trimming. */
+    title: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Optional contact information. */
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    /** Optional license information. */
+    license?: {
+        name: string;
+        url?: string;
+    };
+    /** Optional servers list. */
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+}
+/**
+ * Options for creating both a workspace and an OpenAPI file together.
+ */
+interface CreateWorkspaceWithApiOptions {
+    /** Unique identifier for the API. Required. */
+    oasId: string;
+    /** Display name of the API. Required. */
+    name: string;
+    /** Workspace-relative path for the OpenAPI file. Defaults to `oasFiles/${oasId}.openapi.yaml`. */
+    file?: string;
+    /** API title. Defaults to the name. */
+    title?: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+}
+/**
+ * Result of creating a workspace with an API.
+ */
+interface WorkspaceWithApiResult {
+    /** The generated workspace.yaml content. */
+    workspaceYaml: string;
+    /** The generated OpenAPI YAML content. */
+    openApiYaml: string;
+    /** The workspace-relative path of the OpenAPI file. */
+    openApiRelativePath: string;
+    /** The resolved workspace configuration. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Options for initializing a workspace file on disk.
+ */
+interface InitializeWorkspaceOptions {
+    /** Absolute or relative directory path where workspace.yaml will be created. */
+    directory: string;
+    /** Optional custom workspace file name. Defaults to "workspace.yaml". */
+    workspaceFileName?: string;
+    /** Whether to overwrite an existing file. Defaults to false. */
+    overwrite?: boolean;
+    /** Optional initial active API file id. */
+    activeOasFileId?: string | null;
+    /** Optional initial list of API file entries. */
+    oasFiles?: OasFileEntry[];
+}
+/**
+ * Options for initializing an OpenAPI file on disk.
+ */
+interface InitializeOpenApiOptions {
+    /** Absolute or relative path for the OpenAPI YAML file. */
+    filePath: string;
+    /** API title. Required. */
+    title: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Whether to overwrite an existing file. Defaults to false. */
+    overwrite?: boolean;
+}
+/**
+ * Options for creating a workspace with an API file on disk.
+ */
+interface CreateWorkspaceApiOptions {
+    /** Absolute or relative path to the workspace directory. */
+    workspaceDirectory: string;
+    /** Unique identifier for the API. Required. */
+    oasId: string;
+    /** Display name of the API. Required. */
+    name: string;
+    /** Workspace-relative path for the OpenAPI file. Defaults to `oasFiles/${oasId}.openapi.yaml`. */
+    file?: string;
+    /** API title. Defaults to the name. */
+    title?: string;
+    /** API version. Defaults to "1.0.0". */
+    version?: string;
+    /** Optional API description. */
+    description?: string;
+    /** Whether to overwrite an existing OpenAPI file. Defaults to false. */
+    overwriteOpenApi?: boolean;
+}
+/**
+ * Result of initializing a workspace file.
+ */
+interface InitializeWorkspaceResult {
+    /** Absolute path to the created workspace.yaml file. */
+    filePath: string;
+    /** The workspace configuration that was written. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Result of initializing an OpenAPI file.
+ */
+interface InitializeOpenApiResult {
+    /** Absolute path to the created OpenAPI YAML file. */
+    filePath: string;
+    /** The OpenAPI document title. */
+    title: string;
+    /** The OpenAPI document version. */
+    version: string;
+}
+/**
+ * Result of creating a workspace with an API file on disk.
+ */
+interface CreateWorkspaceApiResult {
+    /** Absolute path to the workspace.yaml file. */
+    workspaceFilePath: string;
+    /** Absolute path to the OpenAPI YAML file. */
+    openApiFilePath: string;
+    /** The workspace configuration that was written. */
+    workspace: WorkspaceConfig;
+}
+/**
+ * Error codes for workspace-yaml operations.
+ */
+type WorkspaceYamlErrorCode = "INVALID_ARGUMENT" | "ALREADY_EXISTS" | "NOT_FOUND" | "IO_ERROR" | "INVALID_WORKSPACE" | "INVALID_OPENAPI" | "ROLLBACK_FAILED";
+/**
+ * Custom error class for workspace-yaml operations.
+ */
+declare class WorkspaceYamlError extends Error {
+    readonly code: WorkspaceYamlErrorCode;
+    readonly filePath?: string;
+    readonly cause?: unknown;
+    constructor(code: WorkspaceYamlErrorCode, message: string, filePath?: string, cause?: unknown);
+}
+
+/**
+ * Core layer — browser-safe pure functions for generating YAML content.
+ *
+ * This module has zero filesystem dependencies and works in browsers,
+ * Node.js, Electron, and any JavaScript environment.
+ *
+ * It generates:
+ * - workspace.yaml content
+ * - OpenAPI 3.2 YAML content
+ * - Both together (workspace + API)
+ */
+
+/**
+ * Creates a workspace.yaml content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * @param options - Workspace creation options
+ * @returns The workspace.yaml content as a YAML string
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceYaml } from "@powerduck/workspace-yaml/core";
+ *
+ * const yaml = createWorkspaceYaml({
+ *   activeOasFileId: "api-v1",
+ *   oasFiles: [
+ *     { id: "api-v1", name: "API v1", file: "oasFiles/api-v1.openapi.yaml" },
+ *   ],
+ * });
+ * // => "version: 1\nactiveOasFileId: api-v1\noasFiles:\n  - ..."
+ * ```
+ */
+declare function createWorkspaceYaml(options?: CreateWorkspaceOptions): string;
+/**
+ * Creates an OpenAPI 3.2 YAML content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * The generated document is a minimal but valid OpenAPI 3.2 spec
+ * with empty paths, ready for the user to add endpoints.
+ *
+ * @param options - OpenAPI creation options
+ * @returns The OpenAPI 3.2 YAML content as a string
+ *
+ * @example
+ * ```typescript
+ * import { createOpenApiYaml } from "@powerduck/workspace-yaml/core";
+ *
+ * const yaml = createOpenApiYaml({
+ *   title: "My API",
+ *   version: "2.0.0",
+ *   description: "A sample API",
+ * });
+ * // => "openapi: 3.2.0\ninfo:\n  title: My API\n  version: 2.0.0\npaths: {}"
+ * ```
+ */
+declare function createOpenApiYaml(options: CreateOpenApiOptions): string;
+/**
+ * Creates both a workspace.yaml and an OpenAPI 3.2 YAML content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * The workspace will contain a single API entry pointing to the
+ * generated OpenAPI file, and that API will be set as active.
+ *
+ * @param options - Options for creating workspace + API
+ * @returns Object containing both YAML strings and metadata
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceWithApi } from "@powerduck/workspace-yaml/core";
+ *
+ * const { workspaceYaml, openApiYaml, openApiRelativePath } = createWorkspaceWithApi({
+ *   oasId: "my-api",
+ *   name: "My API",
+ *   title: "My API Documentation",
+ *   version: "1.0.0",
+ * });
+ *
+ * // Save workspaceYaml to workspace.yaml
+ * // Save openApiYaml to oasFiles/my-api.openapi.yaml
+ * ```
+ */
+declare function createWorkspaceWithApi(options: CreateWorkspaceWithApiOptions): WorkspaceWithApiResult;
+/**
+ * Validates a workspace.yaml content string.
+ *
+ * This is a pure function with no filesystem access.
+ * Works in browsers, Node.js, and Electron.
+ *
+ * @param content - The raw YAML content to validate
+ * @returns The parsed and validated workspace config
+ * @throws WorkspaceYamlError if the content is invalid
+ */
+declare function parseWorkspaceYaml(content: string): WorkspaceConfig;
+
+export { type CreateWorkspaceApiOptions as C, type InitializeOpenApiOptions as I, type OasFileEntry as O, type WorkspaceConfig as W, type CreateWorkspaceApiResult as a, type InitializeOpenApiResult as b, type InitializeWorkspaceOptions as c, type InitializeWorkspaceResult as d, type CreateOpenApiOptions as e, type CreateWorkspaceOptions as f, type CreateWorkspaceWithApiOptions as g, type WorkspaceWithApiResult as h, WorkspaceYamlError as i, type WorkspaceYamlErrorCode as j, createOpenApiYaml as k, createWorkspaceWithApi as l, createWorkspaceYaml as m, parseWorkspaceYaml as p };

package/dist/core.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,"__esModule",{value:!0});var e=require("./chunk-6LICMPRI.cjs");exports.WorkspaceYamlError=e.WorkspaceYamlError,exports.createOpenApiYaml=e.createOpenApiYaml,exports.createWorkspaceWithApi=e.createWorkspaceWithApi,exports.createWorkspaceYaml=e.createWorkspaceYaml,exports.parseWorkspaceYaml=e.parseWorkspaceYaml;

package/dist/core.d.cts

@@ -0,0 +1 @@
+export { e as CreateOpenApiOptions, f as CreateWorkspaceOptions, g as CreateWorkspaceWithApiOptions, O as OasFileEntry, W as WorkspaceConfig, h as WorkspaceWithApiResult, i as WorkspaceYamlError, j as WorkspaceYamlErrorCode, k as createOpenApiYaml, l as createWorkspaceWithApi, m as createWorkspaceYaml, p as parseWorkspaceYaml } from './core-DfwH7QX7.cjs';

package/dist/core.d.ts

@@ -0,0 +1 @@
+export { e as CreateOpenApiOptions, f as CreateWorkspaceOptions, g as CreateWorkspaceWithApiOptions, O as OasFileEntry, W as WorkspaceConfig, h as WorkspaceWithApiResult, i as WorkspaceYamlError, j as WorkspaceYamlErrorCode, k as createOpenApiYaml, l as createWorkspaceWithApi, m as createWorkspaceYaml, p as parseWorkspaceYaml } from './core-DfwH7QX7.js';

package/dist/core.js

@@ -0,0 +1 @@
+import{WorkspaceYamlError as o,createOpenApiYaml as r,createWorkspaceWithApi as m,createWorkspaceYaml as p,parseWorkspaceYaml as t}from"./chunk-QMIGONFP.js";export{o as WorkspaceYamlError,r as createOpenApiYaml,m as createWorkspaceWithApi,p as createWorkspaceYaml,t as parseWorkspaceYaml};

package/dist/index.cjs

@@ -0,0 +1 @@
+function e(e,a){return null!=e?e:a()}Object.defineProperty(exports,"__esModule",{value:!0});var a,r=require("./chunk-6LICMPRI.cjs"),i=require("fs/promises"),t=require("path"),o=(a=t)&&a.__esModule?a:{default:a},l=require("@powerduck/conf-patch");async function c(e){try{await i.mkdir.call(void 0,e,{recursive:!0})}catch(a){throw new(0,r.WorkspaceYamlError)("IO_ERROR",`Failed to create directory: ${e}`,e,a)}}async function s(e){try{return await l.readConfigFile.call(void 0,e),!0}catch(e){return!1}}exports.WorkspaceYamlError=r.WorkspaceYamlError,exports.createOpenApiYaml=r.createOpenApiYaml,exports.createWorkspaceApi=async function(a){if(null===a||"object"!=typeof a)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","createWorkspaceApi requires an options object.");if("string"!=typeof a.workspaceDirectory||0===a.workspaceDirectory.trim().length)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","workspaceDirectory must be a non-empty string.");if("string"!=typeof a.oasId||0===a.oasId.trim().length)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","oasId must be a non-empty string.");if("string"!=typeof a.name||0===a.name.trim().length)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","name must be a non-empty string.");const t=l.normalizeFilePath.call(void 0,a.workspaceDirectory),n=o.default.join(t,"workspace.yaml"),p=e(a.overwriteOpenApi,()=>!1),{openApiYaml:w,openApiRelativePath:d,workspace:m}=r.createWorkspaceWithApi.call(void 0,{oasId:a.oasId,name:a.name,file:a.file,title:a.title,version:a.version,description:a.description}),f=o.default.join(t,d);await c(t),await c(o.default.dirname(f));const k=[n,f].sort();return await l.withFileLock.call(void 0,k[0],async()=>await l.withFileLock.call(void 0,k[1],async()=>{let t,o,c=null;try{const e=await l.readConfigFile.call(void 0,n);c=r.parseWorkspaceYaml.call(void 0,e)}catch(e){c=null}if(null!==c&&c.oasFiles.some(e=>e.id===a.oasId))throw new(0,r.WorkspaceYamlError)("INVALID_WORKSPACE",`An API with id "${a.oasId}" already exists in workspace.yaml.`,n);if(!p&&await s(f))throw new(0,r.WorkspaceYamlError)("ALREADY_EXISTS",`OpenAPI file already exists: ${f}. Set overwriteOpenApi: true to replace it.`,f);try{t=await l.readConfigFile.call(void 0,f)}catch(e){t=void 0}try{await l.writeConfigFile.call(void 0,f,w,{lock:!1})}catch(e){throw new(0,r.WorkspaceYamlError)("IO_ERROR",`Failed to write OpenAPI file: ${f}`,f,e)}o=null!==c?{...c,activeOasFileId:e(c.activeOasFileId,()=>a.oasId),oasFiles:[...c.oasFiles,{id:a.oasId,name:a.name.trim(),file:d}]}:m;const k=r.createWorkspaceYaml.call(void 0,{activeOasFileId:o.activeOasFileId,oasFiles:o.oasFiles});try{await l.writeConfigFile.call(void 0,n,k,{lock:!1})}catch(e){try{void 0!==t?await l.writeConfigFile.call(void 0,f,t,{lock:!1}):await i.rm.call(void 0,f,{force:!0})}catch(a){throw new(0,r.WorkspaceYamlError)("ROLLBACK_FAILED",`Failed to update workspace and failed to roll back OpenAPI file: ${f}`,n,{workspaceWriteError:e,rollbackError:a})}throw e}return{workspaceFilePath:n,openApiFilePath:f,workspace:o}}))},exports.createWorkspaceWithApi=r.createWorkspaceWithApi,exports.createWorkspaceYaml=r.createWorkspaceYaml,exports.initializeOpenApi=async function(a){if(null===a||"object"!=typeof a)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","initializeOpenApi requires an options object.");if("string"!=typeof a.filePath||0===a.filePath.trim().length)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","filePath must be a non-empty string.");const i=l.normalizeFilePath.call(void 0,a.filePath),t=e(a.overwrite,()=>!1);if(!/\.ya?ml$/i.test(i))throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT",`OpenAPI file must have a .yaml or .yml extension: ${i}`,i);const n=r.createOpenApiYaml.call(void 0,{title:a.title,version:a.version,description:a.description}),p=o.default.dirname(i);return await c(p),await l.withFileLock.call(void 0,i,async()=>{if(!t&&await s(i))throw new(0,r.WorkspaceYamlError)("ALREADY_EXISTS",`OpenAPI file already exists: ${i}. Set overwrite: true to replace it.`,i);try{await l.writeConfigFile.call(void 0,i,n,{lock:!1})}catch(e){throw new(0,r.WorkspaceYamlError)("IO_ERROR",`Failed to write OpenAPI file: ${i}`,i,e)}}),{filePath:i,title:a.title.trim(),version:e(a.version,()=>"1.0.0")}},exports.initializeWorkspace=async function(a){if(null===a||"object"!=typeof a)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","initializeWorkspace requires an options object.");if("string"!=typeof a.directory||0===a.directory.trim().length)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","directory must be a non-empty string.");const i=l.normalizeFilePath.call(void 0,a.directory),t=e(a.workspaceFileName,()=>"workspace.yaml");if(t!==o.default.basename(t)||"."===t||".."===t)throw new(0,r.WorkspaceYamlError)("INVALID_ARGUMENT","workspaceFileName must be a file name only, not a path.");const n=o.default.join(i,t),p=e(a.overwrite,()=>!1),w=r.createWorkspaceYaml.call(void 0,{activeOasFileId:a.activeOasFileId,oasFiles:a.oasFiles});await c(i),await l.withFileLock.call(void 0,n,async()=>{if(!p&&await s(n))throw new(0,r.WorkspaceYamlError)("ALREADY_EXISTS",`Workspace file already exists: ${n}. Set overwrite: true to replace it.`,n);try{await l.writeConfigFile.call(void 0,n,w,{lock:!1})}catch(e){throw new(0,r.WorkspaceYamlError)("IO_ERROR",`Failed to write workspace file: ${n}`,n,e)}});const d={version:1,activeOasFileId:e(a.activeOasFileId,()=>null),oasFiles:a.oasFiles?[...a.oasFiles]:[]};return{filePath:n,workspace:d}},exports.parseWorkspaceYaml=r.parseWorkspaceYaml;

package/dist/index.d.cts

@@ -0,0 +1,100 @@
+import { C as CreateWorkspaceApiOptions, a as CreateWorkspaceApiResult, I as InitializeOpenApiOptions, b as InitializeOpenApiResult, c as InitializeWorkspaceOptions, d as InitializeWorkspaceResult } from './core-DfwH7QX7.cjs';
+export { e as CreateOpenApiOptions, f as CreateWorkspaceOptions, g as CreateWorkspaceWithApiOptions, O as OasFileEntry, W as WorkspaceConfig, h as WorkspaceWithApiResult, i as WorkspaceYamlError, j as WorkspaceYamlErrorCode, k as createOpenApiYaml, l as createWorkspaceWithApi, m as createWorkspaceYaml, p as parseWorkspaceYaml } from './core-DfwH7QX7.cjs';
+
+/**
+ * File layer — Node.js / Electron only.
+ *
+ * This module wraps the core layer's pure functions with filesystem IO.
+ * It reuses @powerduck/conf-patch for atomic writes, file locking,
+ * and path normalization — no redundant IO implementations.
+ *
+ * Do not import this module in browser environments.
+ * Use `@powerduck/workspace-yaml/core` instead.
+ */
+
+/**
+ * Initializes a workspace.yaml file on disk.
+ *
+ * Generates the workspace content using the core layer, then writes it
+ * atomically using conf-patch's writeConfigFile (which handles locking
+ * and crash-safe temp-file+rename).
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser usage, use `createWorkspaceYaml` from the core layer.
+ *
+ * @param options - Workspace initialization options
+ * @returns The absolute file path and the workspace config that was written
+ * @throws WorkspaceYamlError if the file already exists and overwrite is false
+ *
+ * @example
+ * ```typescript
+ * import { initializeWorkspace } from "@powerduck/workspace-yaml";
+ *
+ * const { filePath, workspace } = await initializeWorkspace({
+ *   directory: "./my-project",
+ *   overwrite: false,
+ * });
+ * console.log("Created workspace at:", filePath);
+ * ```
+ */
+declare function initializeWorkspace(options: InitializeWorkspaceOptions): Promise<InitializeWorkspaceResult>;
+/**
+ * Initializes an OpenAPI 3.2 YAML file on disk.
+ *
+ * Generates the OpenAPI content using the core layer, then writes it
+ * atomically using conf-patch's writeConfigFile.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser usage, use `createOpenApiYaml` from the core layer.
+ *
+ * @param options - OpenAPI initialization options
+ * @returns The absolute file path, title, and version
+ * @throws WorkspaceYamlError if the file already exists and overwrite is false
+ *
+ * @example
+ * ```typescript
+ * import { initializeOpenApi } from "@powerduck/workspace-yaml";
+ *
+ * const { filePath } = await initializeOpenApi({
+ *   filePath: "./my-project/oasFiles/my-api.openapi.yaml",
+ *   title: "My API",
+ *   version: "1.0.0",
+ * });
+ * ```
+ */
+declare function initializeOpenApi(options: InitializeOpenApiOptions): Promise<InitializeOpenApiResult>;
+/**
+ * Creates a workspace with an API file on disk, atomically.
+ *
+ * This is a transactional operation:
+ * 1. Generate both workspace.yaml and OpenAPI YAML content (core layer)
+ * 2. Acquire locks on both files
+ * 3. Write OpenAPI file first
+ * 4. Write workspace file (referencing the OpenAPI file)
+ * 5. If workspace write fails, roll back the OpenAPI file
+ *
+ * Reuses conf-patch's withFileLock for multi-file locking and
+ * writeConfigFile for atomic writes.
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param options - Options for creating workspace + API
+ * @returns Paths to both files and the workspace config
+ * @throws WorkspaceYamlError if either file already exists (unless overwriteOpenApi is true)
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceApi } from "@powerduck/workspace-yaml";
+ *
+ * const { workspaceFilePath, openApiFilePath } = await createWorkspaceApi({
+ *   workspaceDirectory: "./my-project",
+ *   oasId: "my-api",
+ *   name: "My API",
+ *   title: "My API Documentation",
+ *   version: "1.0.0",
+ * });
+ * ```
+ */
+declare function createWorkspaceApi(options: CreateWorkspaceApiOptions): Promise<CreateWorkspaceApiResult>;
+
+export { CreateWorkspaceApiOptions, CreateWorkspaceApiResult, InitializeOpenApiOptions, InitializeOpenApiResult, InitializeWorkspaceOptions, InitializeWorkspaceResult, createWorkspaceApi, initializeOpenApi, initializeWorkspace };

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+import { C as CreateWorkspaceApiOptions, a as CreateWorkspaceApiResult, I as InitializeOpenApiOptions, b as InitializeOpenApiResult, c as InitializeWorkspaceOptions, d as InitializeWorkspaceResult } from './core-DfwH7QX7.js';
+export { e as CreateOpenApiOptions, f as CreateWorkspaceOptions, g as CreateWorkspaceWithApiOptions, O as OasFileEntry, W as WorkspaceConfig, h as WorkspaceWithApiResult, i as WorkspaceYamlError, j as WorkspaceYamlErrorCode, k as createOpenApiYaml, l as createWorkspaceWithApi, m as createWorkspaceYaml, p as parseWorkspaceYaml } from './core-DfwH7QX7.js';
+
+/**
+ * File layer — Node.js / Electron only.
+ *
+ * This module wraps the core layer's pure functions with filesystem IO.
+ * It reuses @powerduck/conf-patch for atomic writes, file locking,
+ * and path normalization — no redundant IO implementations.
+ *
+ * Do not import this module in browser environments.
+ * Use `@powerduck/workspace-yaml/core` instead.
+ */
+
+/**
+ * Initializes a workspace.yaml file on disk.
+ *
+ * Generates the workspace content using the core layer, then writes it
+ * atomically using conf-patch's writeConfigFile (which handles locking
+ * and crash-safe temp-file+rename).
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser usage, use `createWorkspaceYaml` from the core layer.
+ *
+ * @param options - Workspace initialization options
+ * @returns The absolute file path and the workspace config that was written
+ * @throws WorkspaceYamlError if the file already exists and overwrite is false
+ *
+ * @example
+ * ```typescript
+ * import { initializeWorkspace } from "@powerduck/workspace-yaml";
+ *
+ * const { filePath, workspace } = await initializeWorkspace({
+ *   directory: "./my-project",
+ *   overwrite: false,
+ * });
+ * console.log("Created workspace at:", filePath);
+ * ```
+ */
+declare function initializeWorkspace(options: InitializeWorkspaceOptions): Promise<InitializeWorkspaceResult>;
+/**
+ * Initializes an OpenAPI 3.2 YAML file on disk.
+ *
+ * Generates the OpenAPI content using the core layer, then writes it
+ * atomically using conf-patch's writeConfigFile.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser usage, use `createOpenApiYaml` from the core layer.
+ *
+ * @param options - OpenAPI initialization options
+ * @returns The absolute file path, title, and version
+ * @throws WorkspaceYamlError if the file already exists and overwrite is false
+ *
+ * @example
+ * ```typescript
+ * import { initializeOpenApi } from "@powerduck/workspace-yaml";
+ *
+ * const { filePath } = await initializeOpenApi({
+ *   filePath: "./my-project/oasFiles/my-api.openapi.yaml",
+ *   title: "My API",
+ *   version: "1.0.0",
+ * });
+ * ```
+ */
+declare function initializeOpenApi(options: InitializeOpenApiOptions): Promise<InitializeOpenApiResult>;
+/**
+ * Creates a workspace with an API file on disk, atomically.
+ *
+ * This is a transactional operation:
+ * 1. Generate both workspace.yaml and OpenAPI YAML content (core layer)
+ * 2. Acquire locks on both files
+ * 3. Write OpenAPI file first
+ * 4. Write workspace file (referencing the OpenAPI file)
+ * 5. If workspace write fails, roll back the OpenAPI file
+ *
+ * Reuses conf-patch's withFileLock for multi-file locking and
+ * writeConfigFile for atomic writes.
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param options - Options for creating workspace + API
+ * @returns Paths to both files and the workspace config
+ * @throws WorkspaceYamlError if either file already exists (unless overwriteOpenApi is true)
+ *
+ * @example
+ * ```typescript
+ * import { createWorkspaceApi } from "@powerduck/workspace-yaml";
+ *
+ * const { workspaceFilePath, openApiFilePath } = await createWorkspaceApi({
+ *   workspaceDirectory: "./my-project",
+ *   oasId: "my-api",
+ *   name: "My API",
+ *   title: "My API Documentation",
+ *   version: "1.0.0",
+ * });
+ * ```
+ */
+declare function createWorkspaceApi(options: CreateWorkspaceApiOptions): Promise<CreateWorkspaceApiResult>;
+
+export { CreateWorkspaceApiOptions, CreateWorkspaceApiResult, InitializeOpenApiOptions, InitializeOpenApiResult, InitializeWorkspaceOptions, InitializeWorkspaceResult, createWorkspaceApi, initializeOpenApi, initializeWorkspace };

package/dist/index.js

@@ -0,0 +1 @@
+import{WorkspaceYamlError as e,createOpenApiYaml as t,createWorkspaceWithApi as i,createWorkspaceYaml as a,parseWorkspaceYaml as o}from"./chunk-QMIGONFP.js";import{mkdir as r,rm as n}from"fs/promises";import s from"path";import{normalizeFilePath as c,readConfigFile as l,writeConfigFile as w,withFileLock as p}from"@powerduck/conf-patch";async function I(t){try{await r(t,{recursive:!0})}catch(i){throw new e("IO_ERROR",`Failed to create directory: ${t}`,t,i)}}async function f(e){try{return await l(e),!0}catch{return!1}}async function y(t){if(null===t||"object"!=typeof t)throw new e("INVALID_ARGUMENT","initializeWorkspace requires an options object.");if("string"!=typeof t.directory||0===t.directory.trim().length)throw new e("INVALID_ARGUMENT","directory must be a non-empty string.");const i=c(t.directory),o=t.workspaceFileName??"workspace.yaml";if(o!==s.basename(o)||"."===o||".."===o)throw new e("INVALID_ARGUMENT","workspaceFileName must be a file name only, not a path.");const r=s.join(i,o),n=t.overwrite??!1,l=a({activeOasFileId:t.activeOasFileId,oasFiles:t.oasFiles});await I(i),await p(r,async()=>{if(!n&&await f(r))throw new e("ALREADY_EXISTS",`Workspace file already exists: ${r}. Set overwrite: true to replace it.`,r);try{await w(r,l,{lock:!1})}catch(t){throw new e("IO_ERROR",`Failed to write workspace file: ${r}`,r,t)}});const y={version:1,activeOasFileId:t.activeOasFileId??null,oasFiles:t.oasFiles?[...t.oasFiles]:[]};return{filePath:r,workspace:y}}async function h(i){if(null===i||"object"!=typeof i)throw new e("INVALID_ARGUMENT","initializeOpenApi requires an options object.");if("string"!=typeof i.filePath||0===i.filePath.trim().length)throw new e("INVALID_ARGUMENT","filePath must be a non-empty string.");const a=c(i.filePath),o=i.overwrite??!1;if(!/\.ya?ml$/i.test(a))throw new e("INVALID_ARGUMENT",`OpenAPI file must have a .yaml or .yml extension: ${a}`,a);const r=t({title:i.title,version:i.version,description:i.description}),n=s.dirname(a);return await I(n),await p(a,async()=>{if(!o&&await f(a))throw new e("ALREADY_EXISTS",`OpenAPI file already exists: ${a}. Set overwrite: true to replace it.`,a);try{await w(a,r,{lock:!1})}catch(t){throw new e("IO_ERROR",`Failed to write OpenAPI file: ${a}`,a,t)}}),{filePath:a,title:i.title.trim(),version:i.version??"1.0.0"}}async function m(t){if(null===t||"object"!=typeof t)throw new e("INVALID_ARGUMENT","createWorkspaceApi requires an options object.");if("string"!=typeof t.workspaceDirectory||0===t.workspaceDirectory.trim().length)throw new e("INVALID_ARGUMENT","workspaceDirectory must be a non-empty string.");if("string"!=typeof t.oasId||0===t.oasId.trim().length)throw new e("INVALID_ARGUMENT","oasId must be a non-empty string.");if("string"!=typeof t.name||0===t.name.trim().length)throw new e("INVALID_ARGUMENT","name must be a non-empty string.");const r=c(t.workspaceDirectory),y=s.join(r,"workspace.yaml"),h=t.overwriteOpenApi??!1,{openApiYaml:m,openApiRelativePath:d,workspace:A}=i({oasId:t.oasId,name:t.name,file:t.file,title:t.title,version:t.version,description:t.description}),u=s.join(r,d);await I(r),await I(s.dirname(u));const F=[y,u].sort();return await p(F[0],async()=>await p(F[1],async()=>{let i,r,s=null;try{const e=await l(y);s=o(e)}catch{s=null}if(null!==s&&s.oasFiles.some(e=>e.id===t.oasId))throw new e("INVALID_WORKSPACE",`An API with id "${t.oasId}" already exists in workspace.yaml.`,y);if(!h&&await f(u))throw new e("ALREADY_EXISTS",`OpenAPI file already exists: ${u}. Set overwriteOpenApi: true to replace it.`,u);try{i=await l(u)}catch{i=void 0}try{await w(u,m,{lock:!1})}catch(t){throw new e("IO_ERROR",`Failed to write OpenAPI file: ${u}`,u,t)}r=null!==s?{...s,activeOasFileId:s.activeOasFileId??t.oasId,oasFiles:[...s.oasFiles,{id:t.oasId,name:t.name.trim(),file:d}]}:A;const c=a({activeOasFileId:r.activeOasFileId,oasFiles:r.oasFiles});try{await w(y,c,{lock:!1})}catch(t){try{void 0!==i?await w(u,i,{lock:!1}):await n(u,{force:!0})}catch(i){throw new e("ROLLBACK_FAILED",`Failed to update workspace and failed to roll back OpenAPI file: ${u}`,y,{workspaceWriteError:t,rollbackError:i})}throw t}return{workspaceFilePath:y,openApiFilePath:u,workspace:r}}))}export{e as WorkspaceYamlError,t as createOpenApiYaml,m as createWorkspaceApi,i as createWorkspaceWithApi,a as createWorkspaceYaml,h as initializeOpenApi,y as initializeWorkspace,o as parseWorkspaceYaml};

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@powerduck/workspace-yaml",
+  "version": "0.2.0",
+  "description": "Initialize workspace.yaml and OpenAPI 3.2 YAML files with confidence. Two-layer architecture: browser-safe core for generating YAML content, plus Node.js/Electron file layer that reuses @powerduck/conf-patch for atomic writes and locking.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist coverage",
+    "build": "tsc --noEmit && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "demo": "tsx demo/demo.ts",
+    "demo:browser": "tsx demo/browser-demo.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "yaml",
+    "workspace",
+    "openapi",
+    "openapi-3.2",
+    "initializer",
+    "scaffold",
+    "electron",
+    "browser-safe",
+    "atomic-write",
+    "file-lock",
+    "conf-patch",
+    "powerduck"
+  ],
+  "license": "MIT",
+  "author": "Powerduck limited",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PowerDuckie/workspace-yaml.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PowerDuckie/workspace-yaml/issues"
+  },
+  "homepage": "https://github.com/PowerDuckie/workspace-yaml#readme",
+  "dependencies": {
+    "@powerduck/conf-patch": "^0.3.2",
+    "@powerduck/openapi-parser": "^0.3.3",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "terser": "^5.51.2",
+    "tsup": "^8.1.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}