@powerduck/conf-patch 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,348 @@
+# @powerduckie/confedit
+
+A production-grade configuration editor with a clean **two-layer architecture**:
+
+1. **Core layer** (browser-safe): Pure functions that patch JSON, JSONC, and YAML strings. No filesystem access. Works in Node.js, Electron, and browsers.
+2. **File layer** (Node.js / Electron only): Functions that read/write files, combining the core layer with atomic writes and cross-process file locking.
+
+RFC 6902 JSON Patch semantics, comment and formatting preservation, OpenAPI validation, and full TypeScript support.
+
+## Features
+
+### Core Layer (Browser-Safe)
+- **`patchContent`** — Apply RFC 6902 patch operations to a configuration string
+- **`setContentValue`** — Set or create a nested value
+- **`deleteContentValue`** — Remove a key or array element
+- **No filesystem access** — Works in browsers, IndexedDB, localStorage, or any storage layer
+
+### File Layer (Node.js / Electron)
+- **`readConfigFile`** — Read a configuration file
+- **`writeConfigFile`** — Write a file with atomic writes and optional locking
+- **`patchConfigFile`** — Read-patch-write transaction inside a file lock
+- **`setConfigValue`** — Set a value in a file
+- **`deleteConfigValue`** — Delete a value from a file
+- **Atomic writes** — Temp file + rename pattern, no partial writes on crash
+- **Cross-process file locking** — Exclusive locks with ownership tokens, exponential backoff, stale-lock recovery
+
+### Format Support
+- **JSON** — Standard JSON
+- **JSONC** — JSON with comments and trailing commas (preserved)
+- **YAML** — YAML 1.2 with comments and indentation preservation
+
+### OpenAPI Validation
+- **`validateOpenAPISpec`** — Validate raw OpenAPI/Swagger content (JSON or YAML)
+- **`validateOpenAPIFile`** — Validate from a file path
+- Delegates to `@powerduck/openapi-parser` with secure input handling (size limits, path sandboxing, deadlines, structural complexity guards)
+
+## Installation
+
+```bash
+npm install @powerduckie/confedit
+pnpm add @powerduckie/confedit
+yarn add @powerduckie/confedit
+```
+
+## Module System Support
+
+This package supports both **CommonJS (`require`)** and **ES Modules (`import`)** for all entry points.
+
+### CommonJS (Node.js / Electron main process)
+
+```javascript
+// Full library (includes file IO)
+const { setConfigValue, readConfigFile } = require("@powerduckie/confedit");
+
+// Core layer only (browser-safe, no fs dependency)
+const { patchContent, setContentValue } = require("@powerduckie/confedit/core");
+```
+
+### ES Modules (modern Node.js / browsers / bundlers)
+
+```typescript
+// Full library
+import { setConfigValue, readConfigFile } from "@powerduckie/confedit";
+
+// Core layer only (browser-safe)
+import { patchContent, setContentValue } from "@powerduckie/confedit/core";
+```
+
+### Build Outputs
+
+| Entry | CJS (`require`) | ESM (`import`) | Type Declarations |
+|---|---|---|---|
+| Main | `dist/index.js` (26KB) | `dist/index.mjs` (16KB) | `dist/index.d.ts` |
+| Core | `dist/core.js` (9.5KB) | `dist/core.mjs` (1KB) | `dist/core.d.ts` |
+
+The package does not set `"type": "module"`, so `.js` files are treated as CommonJS by default. The `exports` field in `package.json` explicitly maps `import` and `require` conditions to the correct builds.
+
+## Quick Start
+
+### Browser Usage (Core Layer Only)
+
+> **Important:** For browser usage, import from `@powerduckie/confedit/core` (subpath export).
+> This ensures the file layer (which depends on `node:fs`) is not bundled into your browser code.
+> The core entry is only ~9KB gzipped and has zero Node.js dependencies.
+
+```typescript
+import { patchContent, setContentValue, deleteContentValue } from "@powerduckie/confedit/core";
+
+// Patch a JSON string (no filesystem access)
+const updated = patchContent(
+  '{"name": "app"}',
+  [{ op: "add", path: ["version"], value: "1.0.0" }],
+  "json",
+);
+
+// Set a nested value in YAML
+const yaml = setContentValue("name: app\n", ["server", "port"], 8080, "yaml");
+
+// Delete a value
+const cleaned = deleteContentValue(updated, ["legacy"], "json");
+
+// Store in IndexedDB, localStorage, or any storage layer
+localStorage.setItem("config", updated);
+```
+
+### Node.js / Electron Usage (File Layer)
+
+```typescript
+import { setConfigValue, readConfigFile, patchConfigFile } from "@powerduckie/confedit";
+
+// Set a nested value in a file (atomic, lock-guarded)
+await setConfigValue("config.yaml", ["database", "port"], 5432);
+
+// Read a file
+const content = await readConfigFile("config.json");
+
+// Apply multiple patch operations atomically
+await patchConfigFile("config.jsonc", [
+  { op: "replace", path: ["server", "host"], value: "0.0.0.0" },
+  { op: "add", path: ["server", "ssl"], value: true },
+  { op: "remove", path: ["legacySection"] },
+]);
+```
+
+### Electron IPC Example
+
+```javascript
+// In the Electron main process (CommonJS)
+const { setConfigValue, readConfigFile } = require("@powerduckie/confedit");
+
+ipcMain.handle("config:set", async (_event, { filePath, path, value }) => {
+  try {
+    await setConfigValue(filePath, path, value);
+    return { success: true };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+});
+
+ipcMain.handle("config:read", async (_event, { filePath }) => {
+  try {
+    const data = await readConfigFile(filePath);
+    return { success: true, data };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+});
+```
+
+## API Reference
+
+### Core Layer (Browser-Safe)
+
+#### `patchContent(content, ops, format, options?)`
+
+Applies RFC 6902 patch operations to a configuration string.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `content` | `string` | The raw configuration content |
+| `ops` | `JsonPatchOp[]` | Array of patch operations |
+| `format` | `"json" \| "jsonc" \| "yaml"` | The configuration format |
+| `options.strict` | `boolean` | When true, failed operations throw. Default: `true` |
+
+**Returns:** The patched configuration content (`string`).
+
+#### `setContentValue(content, path, value, format)`
+
+Sets or creates a single value. Uses the `add` operation (replaces existing object properties, inserts at array indices).
+
+#### `deleteContentValue(content, path, format)`
+
+Removes a key or array element.
+
+### File Layer (Node.js / Electron Only)
+
+#### `readConfigFile(filePath)`
+
+Reads UTF-8 text from a file. Throws on failure.
+
+#### `writeConfigFile(filePath, content, options?)`
+
+Writes content to a file using atomic writes and optional file locking.
+
+| Option | Type | Description |
+|---|---|---|
+| `lock` | `boolean` | Enable file locking. Default: `true` |
+| `lockTimeoutMs` | `number` | Maximum time to wait for a lock |
+| `lockRetryDelayMs` | `number` | Initial retry delay (exponential backoff) |
+| `lockStaleThresholdMs` | `number` | Lock age after which recovery is allowed |
+| `allowStaleRecovery` | `boolean` | Allow automatic stale-lock recovery |
+
+#### `patchConfigFile(filePath, ops, options?)`
+
+Reads, patches, and writes a file inside a single atomic, lock-guarded transaction.
+
+| Option | Type | Description |
+|---|---|---|
+| `format` | `"json" \| "jsonc" \| "yaml"` | Explicit format (auto-detected from extension if omitted) |
+| `strict` | `boolean` | When true, failed operations throw. Default: `true` |
+| `lock` | `boolean` | Enable file locking. Default: `true` |
+| `lockTimeoutMs` | `number` | Maximum time to wait for a lock |
+| `lockRetryDelayMs` | `number` | Initial retry delay |
+| `lockStaleThresholdMs` | `number` | Lock age after which recovery is allowed |
+| `allowStaleRecovery` | `boolean` | Allow automatic stale-lock recovery |
+
+#### `setConfigValue(filePath, path, value, options?)`
+
+Sets or creates a nested value in a file.
+
+#### `deleteConfigValue(filePath, path, options?)`
+
+Removes a nested value from a file.
+
+### Types
+
+```typescript
+type ConfigFormat = "json" | "jsonc" | "yaml";
+type JsonPathSegment = string | number;
+
+interface JsonPatchOp {
+  op: "add" | "replace" | "remove";
+  path: JsonPathSegment[];
+  value?: unknown; // required for add and replace
+}
+```
+
+### OpenAPI Validation
+
+```typescript
+import { validateOpenAPISpec, validateOpenAPIFile, OpenApiValidationError } from "@powerduckie/confedit";
+
+// Validate raw content (JSON or YAML)
+try {
+  const doc = await validateOpenAPISpec(specContent);
+  console.log("Valid:", doc.openapi);
+} catch (error) {
+  if (error instanceof OpenApiValidationError) {
+    console.error(`Validation failed [${error.code}]:`, error.message);
+  }
+}
+
+// Validate from a file path (requires allowedRootDirectory for security)
+const doc = await validateOpenAPIFile("openapi.yaml", {
+  allowedRootDirectory: "./configs",
+});
+```
+
+Returns the validated document on success. Throws `OpenApiValidationError` with a machine-readable `code` on failure.
+
+#### Validation Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `inputKind` | `"content" \| "file"` | `"content"` | Whether input is raw content or a file path |
+| `baseFilePath` | `string` | - | Base path for reference resolution context |
+| `allowedRootDirectory` | `string` | - | Root directory for file input (required for file mode) |
+| `timeoutMs` | `number` | `15000` | Operation deadline in milliseconds |
+| `maxInputBytes` | `number` | `5242880` (5MB) | Maximum raw input size in bytes |
+| `maxDocumentNodes` | `number` | `100000` | Maximum nodes in parsed document (DoS protection) |
+| `maxDocumentDepth` | `number` | `100` | Maximum nesting depth (DoS protection) |
+| `maxValidationErrors` | `number` | `50` | Maximum validation errors included in error message |
+| `maxErrorMessageLength` | `number` | `1000` | Maximum characters per validation error |
+| `signal` | `AbortSignal` | - | Optional cancellation signal |
+
+#### Error Codes
+
+| Code | Description |
+|---|---|
+| `INVALID_OPTION` | Invalid option value provided |
+| `INPUT_TOO_LARGE` | Input exceeds maximum allowed size |
+| `INPUT_FILE_TOO_LARGE` | File exceeds maximum allowed size |
+| `FILE_INPUT_FORBIDDEN` | File input used without `allowedRootDirectory` |
+| `PATH_OUTSIDE_ROOT` | File path is outside the allowed root directory |
+| `PARSE_ERROR` | Failed to parse JSON/YAML content |
+| `INVALID_DOCUMENT_SHAPE` | Document is not a JSON object |
+| `UNSUPPORTED_VERSION` | Document does not declare a supported OpenAPI/Swagger version |
+| `DOCUMENT_TOO_DEEP` | Document exceeds maximum nesting depth |
+| `DOCUMENT_TOO_LARGE` | Document exceeds maximum node count |
+| `SPEC_VALIDATION_FAILED` | OpenAPI specification validation failed |
+| `OPERATION_TIMEOUT` | Operation timed out |
+| `OPERATION_ABORTED` | Operation was aborted via signal |
+| `UNKNOWN_ERROR` | Unexpected error occurred |
+
+## Behavior Notes
+
+### Array Operations
+- `add` at an array index **inserts** the element (RFC 6902 behavior)
+- `replace` at an array index **replaces** the element
+- To replace an existing array element, use `patchConfigFile` with `op: "replace"`
+
+### Nested Paths
+- `add` requires the parent path to exist. To create a nested object, first create the parent, then the child.
+- `replace` and `remove` require the target path to exist.
+
+### Format Detection
+- `.json` → JSON
+- `.jsonc` → JSON with comments
+- `.yaml` / `.yml` → YAML
+- Other extensions → throw unless `format` is explicitly set
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Application Code                       │
+├─────────────────────────────────────────────────────────┤
+│  File Layer (Node.js / Electron only)                    │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
+│  │ readConfigFile│  │writeConfigFile│  │patchConfigFile│ │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
+│         │                   │                   │         │
+│  ┌──────▼───────────────────▼───────────────────▼───────┐│
+│  │              Core Layer (Browser-Safe)                 ││
+│  │  patchContent  setContentValue  deleteContentValue    ││
+│  └────────────────────────────────────────────────────────┘│
+└───────────────────────────────────────────────────────────┘
+```
+
+The core layer has zero dependencies on `node:fs`, `node:path`, or any Node.js-specific APIs. It can be used in browsers, Edge Functions, or any JavaScript environment.
+
+The file layer wraps the core layer with filesystem access, atomic writes, and file locking. It only works in Node.js and Electron.
+
+## Performance
+
+- **Core patching**: Incremental text edits via `jsonc-parser` (JSON/JSONC) and AST-based mutation via `yaml` (YAML). No full re-serialization.
+- **Atomic writes**: Temp file + rename, no in-place modification.
+- **File locking**: Lock files with ownership tokens, exponential backoff, no busy-wait polling.
+- **Process-local queue**: Same-file operations are serialized in-process to avoid lock contention.
+- **Bundle size**: Core layer ~15KB gzipped. Full library ~30KB gzipped.
+
+## Testing
+
+```bash
+npm test          # Run all tests (280 tests)
+npm run typecheck # TypeScript type checking
+npm run build     # Build CJS + ESM + type declarations
+```
+
+Test coverage: 280 tests across 12 test files, covering all public APIs, edge cases, concurrency, error handling, browser compatibility, dual-module (CJS/ESM) support, and OpenAPI validation security controls.
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.
+
+## Repository
+
+[https://github.com/PowerDuckie/confedit](https://github.com/PowerDuckie/confedit)

package/dist/chunk-YWMVVRYM.mjs

@@ -0,0 +1 @@
+function assertNonEmptyString(t,r){if("string"!=typeof t||0===t.length)throw new TypeError(`[confedit] ${r} must be a non-empty string.`)}function assertPatchPath(t,r="path"){if(!Array.isArray(t)||0===t.length)throw new TypeError(`[confedit] ${r} must be a non-empty array.`);for(const[e,o]of t.entries())if("string"!=typeof o){if("number"!=typeof o||!Number.isSafeInteger(o)||o<0)throw new TypeError(`[confedit] ${r}[${e}] must be a non-empty string or a non-negative integer.`)}else if(0===o.length)throw new TypeError(`[confedit] ${r}[${e}] must not be an empty string.`)}function assertPatchOperations(t){if(!Array.isArray(t))throw new TypeError("[confedit] ops must be an array.");for(const[r,e]of t.entries()){if(null===e||"object"!=typeof e)throw new TypeError(`[confedit] Patch operation at index ${r} must be an object.`);if("add"!==e.op&&"replace"!==e.op&&"remove"!==e.op)throw new Error(`[confedit] Unsupported patch operation at index ${r}: ${String(e.op)}.`);if(assertPatchPath(e.path,`ops[${r}].path`),("add"===e.op||"replace"===e.op)&&!Object.prototype.hasOwnProperty.call(e,"value"))throw new TypeError(`[confedit] Patch operation at index ${r} requires a value.`)}}function assertConfigFormat(t){if("json"!==t&&"jsonc"!==t&&"yaml"!==t)throw new Error(`[confedit] Unsupported configuration format: ${String(t)}.`)}function getErrorMessage(t){return t instanceof Error?t.message:String(t)}function createError(t,r){const e=new Error(t);try{Object.defineProperty(e,"cause",{configurable:!0,enumerable:!1,value:r,writable:!0})}catch{}return e}import{applyEdits as t,findNodeAtLocation as r,modify as e,parseTree as o}from"jsonc-parser";var n={insertSpaces:!0,tabSize:2,eol:"\n"};function validateOperation(t){if(null===t||"object"!=typeof t)throw new TypeError("Patch operation must be an object.");if(!Array.isArray(t.path)||0===t.path.length)throw new Error("Patch operation path must be a non-empty array.");if("add"!==t.op&&"replace"!==t.op&&"remove"!==t.op)throw new Error(`Unsupported JSON patch operation: ${String(t.op)}`);if(("add"===t.op||"replace"===t.op)&&!Object.prototype.hasOwnProperty.call(t,"value"))throw new Error(`Patch operation "${t.op}" requires a value.`)}function normalizePath(t){return t.map(t=>{if("number"==typeof t){if(!Number.isSafeInteger(t)||t<0)throw new Error(`Invalid array index: ${t}`);return t}if("string"!=typeof t)throw new TypeError(`Patch path segments must be strings or numbers; received ${typeof t}.`);return t})}function applyAdd(t,e,o){const n=function(t,e){if(1===e.length){if("object"!==t.type&&"array"!==t.type)throw new Error("Cannot add a root child to a scalar JSON value.");return t}const o=e.slice(0,-1),n=r(t,o);if(void 0===n)throw new Error(`Cannot add value because its parent does not exist at path: ${formatPath(o)}`);if("object"!==n.type&&"array"!==n.type)throw new Error(`Cannot add value because its parent is not an object or array at path: ${formatPath(o)}`);return n}(getTree(t),e),a=e[e.length-1];if("array"===n.type){const r=function(t,r){if("number"!=typeof t)throw new Error(`Array index must be a number at path: ${formatPath(r)}`);if(!Number.isSafeInteger(t)||t<0)throw new Error(`Invalid array index ${t} at path: ${formatPath(r)}`);return t}(a,e),i=n.children?.length??0;if(r>i)throw new Error(`Cannot add at array index ${r}; array length is ${i} at path: ${formatPath(e.slice(0,-1))}`);return applyModify(t,e,o,!0)}if("object"===n.type){if("string"!=typeof a)throw new Error(`Object property path segment must be a string at path: ${formatPath(e)}`);return applyModify(t,e,o,!1)}throw new Error(`Cannot add a child to non-container value at path: ${formatPath(e.slice(0,-1))}`)}function applyReplace(t,e,o){const n=getTree(t);if(void 0===r(n,e))throw new Error(`Cannot replace a value that does not exist at path: ${formatPath(e)}`);return applyModify(t,e,o,!1)}function applyRemove(t,e){const o=getTree(t);if(void 0===r(o,e))throw new Error(`Cannot remove a value that does not exist at path: ${formatPath(e)}`);return applyModify(t,e,void 0,!1)}function applyModify(r,o,a,i){const s=e(r,o,a,{formattingOptions:n,isArrayInsertion:i});if(0===s.length)throw new Error(`No JSONC edit was generated for path: ${formatPath(o)}`);return t(r,s)}function getTree(t){const r=[],e=o(t,r,{allowTrailingComma:!0,disallowComments:!1});if(void 0===e||r.length>0)throw new Error(`The source text is not valid JSON or JSONC${function(t){if(0===t.length)return"";return` (parse errors: ${t.map(t=>`code=${t.error}, offset=${t.offset}`).join("; ")})`}(r)}.`);return e}function formatPath(t){return`[${t.map(t=>JSON.stringify(t)).join(", ")}]`}function safeStringify(t){try{return JSON.stringify(t)}catch{return"[unserializable patch operation]"}}function getErrorMessage2(t){return t instanceof Error?t.message:String(t)}function createError2(t,r){const e=new Error(t);try{Object.defineProperty(e,"cause",{configurable:!0,enumerable:!1,value:r,writable:!0})}catch{}return e}import{isMap as a,isSeq as i,parseDocument as s}from"yaml";function applyYamlOperation(t,r){!function(t){if(!Array.isArray(t.path)||0===t.path.length)throw new Error("[confedit] Patch path must be a non-empty array.");if("add"!==t.op&&"replace"!==t.op&&"remove"!==t.op)throw new Error(`[confedit] Unsupported patch operation: ${String(t.op)}.`)}(r);const e=r.path,o=function(t,r){if(0===r.length)throw new Error("[confedit] Replacing the YAML document root is not supported.");if(1===r.length){if(null===t.contents)throw new Error("[confedit] Cannot patch an empty YAML document without a root container.");return t.contents}const e=r.slice(0,-1),o=t.getIn(e,!0);if(null==o)throw new Error(`[confedit] Missing parent path: ${formatPath2(e)}.`);if(!a(o)&&!i(o))throw new Error(`[confedit] Parent at ${formatPath2(e)} is not a YAML map or sequence.`);return o}(t,e),n=e[e.length-1];if(a(o))!function(t,r,e,o){if("string"!=typeof e)throw new Error(`[confedit] YAML map keys must be strings at ${formatPath2(o.path)}.`);const n=r.has(e);switch(o.op){case"add":return void r.set(e,t.createNode(o.value));case"replace":if(!n)throw new Error(`[confedit] Cannot replace missing value at ${formatPath2(o.path)}.`);return void r.set(e,t.createNode(o.value));case"remove":if(!n)throw new Error(`[confedit] Cannot remove missing value at ${formatPath2(o.path)}.`);return void r.delete(e);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(t,o,n,r);else{if(!i(o))throw new Error(`[confedit] Cannot apply patch at ${formatPath2(e)} because its parent is not a YAML map or sequence.`);!function(t,r,e,o){if("number"!=typeof e||!Number.isSafeInteger(e)||e<0)throw new Error(`[confedit] YAML sequence indexes must be non-negative integers at ${formatPath2(o.path)}.`);const n=r.items.length;switch(o.op){case"add":if(e>n)throw new Error(`[confedit] Cannot insert at index ${e}; sequence length is ${n}.`);return void r.items.splice(e,0,t.createNode(o.value));case"replace":if(e>=n)throw new Error(`[confedit] Cannot replace index ${e}; sequence length is ${n}.`);return void(r.items[e]=t.createNode(o.value));case"remove":if(e>=n)throw new Error(`[confedit] Cannot remove index ${e}; sequence length is ${n}.`);return void r.items.splice(e,1);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(t,o,n,r)}}function formatPath2(t){return`[${t.map(t=>JSON.stringify(t)).join(", ")}]`}function patchContent(t,r,e,o={}){if("string"!=typeof t)throw new TypeError("[confedit] content must be a string.");if(assertPatchOperations(r),assertConfigFormat(e),0===r.length)return t;const n=o.strict??!0;switch(e){case"json":case"jsonc":return function(t,r,e=!0){if("string"!=typeof t)throw new TypeError("[confedit] sourceText must be a string.");if(!Array.isArray(r))throw new TypeError("[confedit] ops must be an array.");let o=t;for(const t of r)try{validateOperation(t);const r=normalizePath(t.path);switch(t.op){case"add":o=applyAdd(o,r,t.value);break;case"replace":o=applyReplace(o,r,t.value);break;case"remove":o=applyRemove(o,r);break;default:throw new Error(`[confedit] Unsupported JSON patch operation: ${String(t.op)}`)}}catch(r){const o=`[confedit] Failed to apply JSON patch ${safeStringify(t)}: ${getErrorMessage2(r)}`;if(e)throw createError2(o,r);console.warn(o)}return o}(t,r,n);case"yaml":return function(t,r,e=!0){const o=s(t,{prettyErrors:!0,strict:!0});if(o.errors.length>0)throw new Error(`[confedit] Invalid YAML source: ${o.errors.map(t=>t.message).join("; ")}`);for(const t of r)try{applyYamlOperation(o,t)}catch(r){if(e)throw r;console.warn(`[confedit yaml patch warn] Skip operation ${JSON.stringify(t)}`,r)}return o.toString()}(t,r,n)}}function setContentValue(t,r,e,o){return assertPatchPath(r),patchContent(t,[{op:"add",path:[...r],value:e}],o)}function deleteContentValue(t,r,e){return assertPatchPath(r),patchContent(t,[{op:"remove",path:[...r]}],e)}export{assertNonEmptyString,assertPatchPath,assertPatchOperations,assertConfigFormat,getErrorMessage,createError,patchContent,setContentValue,deleteContentValue};

package/dist/core-CDrue4z-.d.mts

@@ -0,0 +1,143 @@
+type ConfigFormat = "json" | "jsonc" | "yaml";
+type JsonPathSegment = string | number;
+interface JsonPatchOp {
+    op: "add" | "replace" | "remove";
+    path: JsonPathSegment[];
+    value?: unknown;
+}
+interface PatchConfigOptions {
+    format?: ConfigFormat;
+    strict?: boolean;
+    lock?: boolean;
+    lockTimeoutMs?: number;
+    lockRetryDelayMs?: number;
+    lockStaleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+interface FileLockOptions {
+    /** Maximum time to wait for a lock. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** Initial retry delay. Defaults to 25ms. */
+    retryDelayMs?: number;
+    /** Explicit lock age after which recovery is allowed. */
+    staleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+
+/**
+ * Options for content-level patch operations.
+ * These do not involve file IO and work in both Node.js and browser environments.
+ */
+interface PatchContentOptions {
+    /** When true, failed operations throw. When false, they are skipped with a warning. Default: true */
+    strict?: boolean;
+}
+/**
+ * Applies RFC 6902 patch operations to a configuration string.
+ *
+ * This is a pure function that does not touch the filesystem.
+ * It works in both Node.js and browser environments.
+ *
+ * @param content - The raw configuration content (JSON, JSONC, or YAML string)
+ * @param ops - Array of RFC 6902 patch operations
+ * @param format - The configuration format ("json" | "jsonc" | "yaml")
+ * @param options - Optional patch settings
+ * @returns The patched configuration content
+ *
+ * @example
+ * ```typescript
+ * import { patchContent } from "@powerduckie/confedit";
+ *
+ * const updated = patchContent(
+ *   '{"name": "app"}',
+ *   [{ op: "add", path: ["version"], value: "1.0.0" }],
+ *   "json",
+ * );
+ * // => '{\n  "name": "app",\n  "version": "1.0.0"\n}'
+ * ```
+ */
+declare function patchContent(content: string, ops: JsonPatchOp[], format: ConfigFormat, options?: PatchContentOptions): string;
+/**
+ * Sets or creates a single value in a configuration string.
+ *
+ * Uses the `add` operation, which replaces existing object properties
+ * or inserts at array indices (RFC 6902 behavior).
+ *
+ * This is a pure function that does not touch the filesystem.
+ *
+ * @param content - The raw configuration content
+ * @param path - Segment path to the target key (e.g. ["server", "port"])
+ * @param value - Value to set
+ * @param format - The configuration format
+ * @returns The updated configuration content
+ *
+ * @example
+ * ```typescript
+ * import { setContentValue } from "@powerduckie/confedit";
+ *
+ * const updated = setContentValue(
+ *   "name: app\n",
+ *   ["version"],
+ *   "1.0.0",
+ *   "yaml",
+ * );
+ * ```
+ */
+declare function setContentValue(content: string, path: readonly (string | number)[], value: unknown, format: ConfigFormat): string;
+/**
+ * Removes a key or array element from a configuration string.
+ *
+ * This is a pure function that does not touch the filesystem.
+ *
+ * @param content - The raw configuration content
+ * @param path - Segment path to remove
+ * @param format - The configuration format
+ * @returns The updated configuration content
+ *
+ * @example
+ * ```typescript
+ * import { deleteContentValue } from "@powerduckie/confedit";
+ *
+ * const updated = deleteContentValue(
+ *   '{"name": "app", "legacy": true}',
+ *   ["legacy"],
+ *   "json",
+ * );
+ * ```
+ */
+declare function deleteContentValue(content: string, path: readonly (string | number)[], format: ConfigFormat): string;
+
+/**
+ * Asserts that a value is a non-empty string.
+ */
+declare function assertNonEmptyString(value: unknown, label: string): asserts value is string;
+/**
+ * Asserts that a patch path is a non-empty array of valid segments.
+ */
+declare function assertPatchPath(path: readonly (string | number)[], label?: string): void;
+/**
+ * Asserts that an array of patch operations is valid.
+ */
+declare function assertPatchOperations(ops: JsonPatchOp[]): void;
+/**
+ * Asserts that a config format is supported.
+ */
+declare function assertConfigFormat(format: ConfigFormat): void;
+/**
+ * Extracts a human-readable error message from an unknown error.
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Creates an Error with an optional cause, preserving compatibility with older runtimes.
+ */
+declare function createError(message: string, cause: unknown): Error;
+
+export { type ConfigFormat as C, type FileLockOptions as F, type JsonPatchOp as J, type PatchConfigOptions as P, type JsonPathSegment as a, type PatchContentOptions as b, assertConfigFormat as c, assertNonEmptyString as d, assertPatchOperations as e, assertPatchPath as f, createError as g, deleteContentValue as h, getErrorMessage as i, patchContent as p, setContentValue as s };

package/dist/core-CDrue4z-.d.ts

@@ -0,0 +1,143 @@
+type ConfigFormat = "json" | "jsonc" | "yaml";
+type JsonPathSegment = string | number;
+interface JsonPatchOp {
+    op: "add" | "replace" | "remove";
+    path: JsonPathSegment[];
+    value?: unknown;
+}
+interface PatchConfigOptions {
+    format?: ConfigFormat;
+    strict?: boolean;
+    lock?: boolean;
+    lockTimeoutMs?: number;
+    lockRetryDelayMs?: number;
+    lockStaleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+interface FileLockOptions {
+    /** Maximum time to wait for a lock. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** Initial retry delay. Defaults to 25ms. */
+    retryDelayMs?: number;
+    /** Explicit lock age after which recovery is allowed. */
+    staleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+
+/**
+ * Options for content-level patch operations.
+ * These do not involve file IO and work in both Node.js and browser environments.
+ */
+interface PatchContentOptions {
+    /** When true, failed operations throw. When false, they are skipped with a warning. Default: true */
+    strict?: boolean;
+}
+/**
+ * Applies RFC 6902 patch operations to a configuration string.
+ *
+ * This is a pure function that does not touch the filesystem.
+ * It works in both Node.js and browser environments.
+ *
+ * @param content - The raw configuration content (JSON, JSONC, or YAML string)
+ * @param ops - Array of RFC 6902 patch operations
+ * @param format - The configuration format ("json" | "jsonc" | "yaml")
+ * @param options - Optional patch settings
+ * @returns The patched configuration content
+ *
+ * @example
+ * ```typescript
+ * import { patchContent } from "@powerduckie/confedit";
+ *
+ * const updated = patchContent(
+ *   '{"name": "app"}',
+ *   [{ op: "add", path: ["version"], value: "1.0.0" }],
+ *   "json",
+ * );
+ * // => '{\n  "name": "app",\n  "version": "1.0.0"\n}'
+ * ```
+ */
+declare function patchContent(content: string, ops: JsonPatchOp[], format: ConfigFormat, options?: PatchContentOptions): string;
+/**
+ * Sets or creates a single value in a configuration string.
+ *
+ * Uses the `add` operation, which replaces existing object properties
+ * or inserts at array indices (RFC 6902 behavior).
+ *
+ * This is a pure function that does not touch the filesystem.
+ *
+ * @param content - The raw configuration content
+ * @param path - Segment path to the target key (e.g. ["server", "port"])
+ * @param value - Value to set
+ * @param format - The configuration format
+ * @returns The updated configuration content
+ *
+ * @example
+ * ```typescript
+ * import { setContentValue } from "@powerduckie/confedit";
+ *
+ * const updated = setContentValue(
+ *   "name: app\n",
+ *   ["version"],
+ *   "1.0.0",
+ *   "yaml",
+ * );
+ * ```
+ */
+declare function setContentValue(content: string, path: readonly (string | number)[], value: unknown, format: ConfigFormat): string;
+/**
+ * Removes a key or array element from a configuration string.
+ *
+ * This is a pure function that does not touch the filesystem.
+ *
+ * @param content - The raw configuration content
+ * @param path - Segment path to remove
+ * @param format - The configuration format
+ * @returns The updated configuration content
+ *
+ * @example
+ * ```typescript
+ * import { deleteContentValue } from "@powerduckie/confedit";
+ *
+ * const updated = deleteContentValue(
+ *   '{"name": "app", "legacy": true}',
+ *   ["legacy"],
+ *   "json",
+ * );
+ * ```
+ */
+declare function deleteContentValue(content: string, path: readonly (string | number)[], format: ConfigFormat): string;
+
+/**
+ * Asserts that a value is a non-empty string.
+ */
+declare function assertNonEmptyString(value: unknown, label: string): asserts value is string;
+/**
+ * Asserts that a patch path is a non-empty array of valid segments.
+ */
+declare function assertPatchPath(path: readonly (string | number)[], label?: string): void;
+/**
+ * Asserts that an array of patch operations is valid.
+ */
+declare function assertPatchOperations(ops: JsonPatchOp[]): void;
+/**
+ * Asserts that a config format is supported.
+ */
+declare function assertConfigFormat(format: ConfigFormat): void;
+/**
+ * Extracts a human-readable error message from an unknown error.
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Creates an Error with an optional cause, preserving compatibility with older runtimes.
+ */
+declare function createError(message: string, cause: unknown): Error;
+
+export { type ConfigFormat as C, type FileLockOptions as F, type JsonPatchOp as J, type PatchConfigOptions as P, type JsonPathSegment as a, type PatchContentOptions as b, assertConfigFormat as c, assertNonEmptyString as d, assertPatchOperations as e, assertPatchPath as f, createError as g, deleteContentValue as h, getErrorMessage as i, patchContent as p, setContentValue as s };

package/dist/core.d.mts

@@ -0,0 +1 @@
+export { C as ConfigFormat, J as JsonPatchOp, a as JsonPathSegment, b as PatchContentOptions, c as assertConfigFormat, d as assertNonEmptyString, e as assertPatchOperations, f as assertPatchPath, g as createError, h as deleteContentValue, i as getErrorMessage, p as patchContent, s as setContentValue } from './core-CDrue4z-.mjs';

package/dist/core.d.ts

@@ -0,0 +1 @@
+export { C as ConfigFormat, J as JsonPatchOp, a as JsonPathSegment, b as PatchContentOptions, c as assertConfigFormat, d as assertNonEmptyString, e as assertPatchOperations, f as assertPatchPath, g as createError, h as deleteContentValue, i as getErrorMessage, p as patchContent, s as setContentValue } from './core-CDrue4z-.js';

package/dist/core.js

@@ -0,0 +1 @@
+var t,e=Object.defineProperty,r=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,n=Object.prototype.hasOwnProperty,a={};((t,r)=>{for(var o in r)e(t,o,{get:r[o],enumerable:!0})})(a,{assertConfigFormat:()=>assertConfigFormat,assertNonEmptyString:()=>assertNonEmptyString,assertPatchOperations:()=>assertPatchOperations,assertPatchPath:()=>assertPatchPath,createError:()=>createError2,deleteContentValue:()=>deleteContentValue,getErrorMessage:()=>getErrorMessage2,patchContent:()=>patchContent,setContentValue:()=>setContentValue}),module.exports=(t=a,((t,a,i,s)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let p of o(a))n.call(t,p)||p===i||e(t,p,{get:()=>a[p],enumerable:!(s=r(a,p))||s.enumerable});return t})(e({},"__esModule",{value:!0}),t));var i=require("jsonc-parser"),s={insertSpaces:!0,tabSize:2,eol:"\n"};function validateOperation(t){if(null===t||"object"!=typeof t)throw new TypeError("Patch operation must be an object.");if(!Array.isArray(t.path)||0===t.path.length)throw new Error("Patch operation path must be a non-empty array.");if("add"!==t.op&&"replace"!==t.op&&"remove"!==t.op)throw new Error(`Unsupported JSON patch operation: ${String(t.op)}`);if(("add"===t.op||"replace"===t.op)&&!Object.prototype.hasOwnProperty.call(t,"value"))throw new Error(`Patch operation "${t.op}" requires a value.`)}function normalizePath(t){return t.map(t=>{if("number"==typeof t){if(!Number.isSafeInteger(t)||t<0)throw new Error(`Invalid array index: ${t}`);return t}if("string"!=typeof t)throw new TypeError(`Patch path segments must be strings or numbers; received ${typeof t}.`);return t})}function applyAdd(t,e,r){const o=function(t,e){if(1===e.length){if("object"!==t.type&&"array"!==t.type)throw new Error("Cannot add a root child to a scalar JSON value.");return t}const r=e.slice(0,-1),o=(0,i.findNodeAtLocation)(t,r);if(void 0===o)throw new Error(`Cannot add value because its parent does not exist at path: ${formatPath(r)}`);if("object"!==o.type&&"array"!==o.type)throw new Error(`Cannot add value because its parent is not an object or array at path: ${formatPath(r)}`);return o}(getTree(t),e),n=e[e.length-1];if("array"===o.type){const a=function(t,e){if("number"!=typeof t)throw new Error(`Array index must be a number at path: ${formatPath(e)}`);if(!Number.isSafeInteger(t)||t<0)throw new Error(`Invalid array index ${t} at path: ${formatPath(e)}`);return t}(n,e),i=o.children?.length??0;if(a>i)throw new Error(`Cannot add at array index ${a}; array length is ${i} at path: ${formatPath(e.slice(0,-1))}`);return applyModify(t,e,r,!0)}if("object"===o.type){if("string"!=typeof n)throw new Error(`Object property path segment must be a string at path: ${formatPath(e)}`);return applyModify(t,e,r,!1)}throw new Error(`Cannot add a child to non-container value at path: ${formatPath(e.slice(0,-1))}`)}function applyReplace(t,e,r){const o=getTree(t);if(void 0===(0,i.findNodeAtLocation)(o,e))throw new Error(`Cannot replace a value that does not exist at path: ${formatPath(e)}`);return applyModify(t,e,r,!1)}function applyRemove(t,e){const r=getTree(t);if(void 0===(0,i.findNodeAtLocation)(r,e))throw new Error(`Cannot remove a value that does not exist at path: ${formatPath(e)}`);return applyModify(t,e,void 0,!1)}function applyModify(t,e,r,o){const n=(0,i.modify)(t,e,r,{formattingOptions:s,isArrayInsertion:o});if(0===n.length)throw new Error(`No JSONC edit was generated for path: ${formatPath(e)}`);return(0,i.applyEdits)(t,n)}function getTree(t){const e=[],r=(0,i.parseTree)(t,e,{allowTrailingComma:!0,disallowComments:!1});if(void 0===r||e.length>0)throw new Error(`The source text is not valid JSON or JSONC${function(t){if(0===t.length)return"";return` (parse errors: ${t.map(t=>`code=${t.error}, offset=${t.offset}`).join("; ")})`}(e)}.`);return r}function formatPath(t){return`[${t.map(t=>JSON.stringify(t)).join(", ")}]`}function safeStringify(t){try{return JSON.stringify(t)}catch{return"[unserializable patch operation]"}}function getErrorMessage(t){return t instanceof Error?t.message:String(t)}function createError(t,e){const r=new Error(t);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:e,writable:!0})}catch{}return r}var p=require("yaml");function applyYamlOperation(t,e){!function(t){if(!Array.isArray(t.path)||0===t.path.length)throw new Error("[confedit] Patch path must be a non-empty array.");if("add"!==t.op&&"replace"!==t.op&&"remove"!==t.op)throw new Error(`[confedit] Unsupported patch operation: ${String(t.op)}.`)}(e);const r=e.path,o=function(t,e){if(0===e.length)throw new Error("[confedit] Replacing the YAML document root is not supported.");if(1===e.length){if(null===t.contents)throw new Error("[confedit] Cannot patch an empty YAML document without a root container.");return t.contents}const r=e.slice(0,-1),o=t.getIn(r,!0);if(null==o)throw new Error(`[confedit] Missing parent path: ${formatPath2(r)}.`);if(!(0,p.isMap)(o)&&!(0,p.isSeq)(o))throw new Error(`[confedit] Parent at ${formatPath2(r)} is not a YAML map or sequence.`);return o}(t,r),n=r[r.length-1];if((0,p.isMap)(o))!function(t,e,r,o){if("string"!=typeof r)throw new Error(`[confedit] YAML map keys must be strings at ${formatPath2(o.path)}.`);const n=e.has(r);switch(o.op){case"add":return void e.set(r,t.createNode(o.value));case"replace":if(!n)throw new Error(`[confedit] Cannot replace missing value at ${formatPath2(o.path)}.`);return void e.set(r,t.createNode(o.value));case"remove":if(!n)throw new Error(`[confedit] Cannot remove missing value at ${formatPath2(o.path)}.`);return void e.delete(r);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(t,o,n,e);else{if(!(0,p.isSeq)(o))throw new Error(`[confedit] Cannot apply patch at ${formatPath2(r)} because its parent is not a YAML map or sequence.`);!function(t,e,r,o){if("number"!=typeof r||!Number.isSafeInteger(r)||r<0)throw new Error(`[confedit] YAML sequence indexes must be non-negative integers at ${formatPath2(o.path)}.`);const n=e.items.length;switch(o.op){case"add":if(r>n)throw new Error(`[confedit] Cannot insert at index ${r}; sequence length is ${n}.`);return void e.items.splice(r,0,t.createNode(o.value));case"replace":if(r>=n)throw new Error(`[confedit] Cannot replace index ${r}; sequence length is ${n}.`);return void(e.items[r]=t.createNode(o.value));case"remove":if(r>=n)throw new Error(`[confedit] Cannot remove index ${r}; sequence length is ${n}.`);return void e.items.splice(r,1);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(t,o,n,e)}}function formatPath2(t){return`[${t.map(t=>JSON.stringify(t)).join(", ")}]`}function assertNonEmptyString(t,e){if("string"!=typeof t||0===t.length)throw new TypeError(`[confedit] ${e} must be a non-empty string.`)}function assertPatchPath(t,e="path"){if(!Array.isArray(t)||0===t.length)throw new TypeError(`[confedit] ${e} must be a non-empty array.`);for(const[r,o]of t.entries())if("string"!=typeof o){if("number"!=typeof o||!Number.isSafeInteger(o)||o<0)throw new TypeError(`[confedit] ${e}[${r}] must be a non-empty string or a non-negative integer.`)}else if(0===o.length)throw new TypeError(`[confedit] ${e}[${r}] must not be an empty string.`)}function assertPatchOperations(t){if(!Array.isArray(t))throw new TypeError("[confedit] ops must be an array.");for(const[e,r]of t.entries()){if(null===r||"object"!=typeof r)throw new TypeError(`[confedit] Patch operation at index ${e} must be an object.`);if("add"!==r.op&&"replace"!==r.op&&"remove"!==r.op)throw new Error(`[confedit] Unsupported patch operation at index ${e}: ${String(r.op)}.`);if(assertPatchPath(r.path,`ops[${e}].path`),("add"===r.op||"replace"===r.op)&&!Object.prototype.hasOwnProperty.call(r,"value"))throw new TypeError(`[confedit] Patch operation at index ${e} requires a value.`)}}function assertConfigFormat(t){if("json"!==t&&"jsonc"!==t&&"yaml"!==t)throw new Error(`[confedit] Unsupported configuration format: ${String(t)}.`)}function getErrorMessage2(t){return t instanceof Error?t.message:String(t)}function createError2(t,e){const r=new Error(t);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:e,writable:!0})}catch{}return r}function patchContent(t,e,r,o={}){if("string"!=typeof t)throw new TypeError("[confedit] content must be a string.");if(assertPatchOperations(e),assertConfigFormat(r),0===e.length)return t;const n=o.strict??!0;switch(r){case"json":case"jsonc":return function(t,e,r=!0){if("string"!=typeof t)throw new TypeError("[confedit] sourceText must be a string.");if(!Array.isArray(e))throw new TypeError("[confedit] ops must be an array.");let o=t;for(const t of e)try{validateOperation(t);const e=normalizePath(t.path);switch(t.op){case"add":o=applyAdd(o,e,t.value);break;case"replace":o=applyReplace(o,e,t.value);break;case"remove":o=applyRemove(o,e);break;default:throw new Error(`[confedit] Unsupported JSON patch operation: ${String(t.op)}`)}}catch(e){const o=`[confedit] Failed to apply JSON patch ${safeStringify(t)}: ${getErrorMessage(e)}`;if(r)throw createError(o,e);console.warn(o)}return o}(t,e,n);case"yaml":return function(t,e,r=!0){const o=(0,p.parseDocument)(t,{prettyErrors:!0,strict:!0});if(o.errors.length>0)throw new Error(`[confedit] Invalid YAML source: ${o.errors.map(t=>t.message).join("; ")}`);for(const t of e)try{applyYamlOperation(o,t)}catch(e){if(r)throw e;console.warn(`[confedit yaml patch warn] Skip operation ${JSON.stringify(t)}`,e)}return o.toString()}(t,e,n)}}function setContentValue(t,e,r,o){return assertPatchPath(e),patchContent(t,[{op:"add",path:[...e],value:r}],o)}function deleteContentValue(t,e,r){return assertPatchPath(e),patchContent(t,[{op:"remove",path:[...e]}],r)}

package/dist/core.mjs

@@ -0,0 +1 @@
+import{assertConfigFormat as m,assertNonEmptyString as o,assertPatchOperations as r,assertPatchPath as p,createError as t,deleteContentValue as M,getErrorMessage as V,patchContent as Y,setContentValue as c}from"./chunk-YWMVVRYM.mjs";export{m as assertConfigFormat,o as assertNonEmptyString,r as assertPatchOperations,p as assertPatchPath,t as createError,M as deleteContentValue,V as getErrorMessage,Y as patchContent,c as setContentValue};

package/dist/index.d.mts

@@ -0,0 +1,207 @@
+import { P as PatchConfigOptions, J as JsonPatchOp, C as ConfigFormat } from './core-CDrue4z-.mjs';
+export { F as FileLockOptions, a as JsonPathSegment, b as PatchContentOptions, c as assertConfigFormat, d as assertNonEmptyString, e as assertPatchOperations, f as assertPatchPath, g as createError, h as deleteContentValue, i as getErrorMessage, p as patchContent, s as setContentValue } from './core-CDrue4z-.mjs';
+import { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+
+/**
+ * Reads UTF-8 text from a local file path or file URL.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use the core `patchContent` / `setContentValue`
+ * functions directly with string content.
+ *
+ * @param filePath - Path to the configuration file (absolute, relative, or file:// URL)
+ * @returns The raw UTF-8 content of the file
+ * @throws If the file cannot be read
+ */
+declare function readConfigFile(filePath: string): Promise<string>;
+
+/**
+ * Options for writing a configuration file.
+ */
+interface WriteConfigOptions {
+    /** Enable file locking during the write. Default: true */
+    lock?: boolean;
+    /** Maximum time (ms) to wait to acquire a file lock. */
+    lockTimeoutMs?: number;
+    /** Delay (ms) between retry attempts to acquire a lock. */
+    lockRetryDelayMs?: number;
+    /** Duration (ms) after which a lock is considered stale. */
+    lockStaleThresholdMs?: number;
+    /** Whether stale locks can be automatically reclaimed. */
+    allowStaleRecovery?: boolean;
+}
+/**
+ * Writes content to a configuration file using atomic writes and optional file locking.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use the core `patchContent` / `setContentValue`
+ * functions and store the result in IndexedDB, localStorage, or another storage layer.
+ *
+ * @param filePath - Path to the configuration file
+ * @param content - The content to write
+ * @param options - Optional write settings
+ * @throws If the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * import { writeConfigFile } from "@powerduckie/confedit";
+ *
+ * await writeConfigFile("config.json", '{"name": "app"}');
+ * ```
+ */
+declare function writeConfigFile(filePath: string, content: string, options?: WriteConfigOptions): Promise<void>;
+
+/**
+ * Patches a JSON, JSONC, or YAML file using an atomic locked transaction.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use `patchContent` directly and manage storage yourself.
+ *
+ * @param filePath - Path to the configuration file
+ * @param ops - Array of RFC 6902 patch operations
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { patchConfigFile } from "@powerduckie/confedit";
+ *
+ * await patchConfigFile("config.json", [
+ *   { op: "replace", path: ["server", "host"], value: "0.0.0.0" },
+ *   { op: "add", path: ["server", "ssl"], value: true },
+ *   { op: "remove", path: ["legacySection"] },
+ * ]);
+ * ```
+ */
+declare function patchConfigFile(filePath: string, ops: JsonPatchOp[], options?: PatchConfigOptions): Promise<void>;
+/**
+ * Adds or replaces a nested configuration value in a file.
+ *
+ * Uses the `add` operation, which replaces existing object properties
+ * or inserts at array indices (RFC 6902 behavior).
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param filePath - Path to the configuration file
+ * @param path - Segment path to the target key
+ * @param value - Value to set
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { setConfigValue } from "@powerduckie/confedit";
+ *
+ * await setConfigValue("config.yaml", ["database", "port"], 5432);
+ * ```
+ */
+declare function setConfigValue(filePath: string, path: readonly (string | number)[], value: unknown, options?: PatchConfigOptions): Promise<void>;
+/**
+ * Removes an existing nested configuration value from a file.
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param filePath - Path to the configuration file
+ * @param path - Segment path to remove
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { deleteConfigValue } from "@powerduckie/confedit";
+ *
+ * await deleteConfigValue("config.json", ["features", "betaPreview"]);
+ * ```
+ */
+declare function deleteConfigValue(filePath: string, path: readonly (string | number)[], options?: PatchConfigOptions): Promise<void>;
+
+interface FileLockOptions {
+    /** Maximum time to wait for a lock. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** Initial retry delay. Defaults to 25ms. */
+    retryDelayMs?: number;
+    /** Explicit lock age after which recovery is allowed. */
+    staleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+/**
+ * Runs work under a process-local queue and an exclusive lock file.
+ *
+ * A stale lock is recovered only when allowStaleRecovery = true and the lock exceeds staleThresholdMs.
+ * PID checks are intentionally avoided: PIDs can be reused and cannot reliably identify the original process.
+ */
+declare function withFileLock<T>(filePath: string, callback: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Release all locks owned by current process, designed for Electron app.will-quit
+ */
+declare function releaseAllLocalLocks(): Promise<void>;
+
+/** A permissive structural type for OpenAPI 3.2 documents. */
+interface OpenAPIV3_2Document {
+    openapi: string;
+    info: Record<string, unknown>;
+    paths?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Supported OpenAPI and Swagger document shapes. */
+type AnyOpenAPIDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document | OpenAPIV3_2Document;
+/** Selects how the supplied input string must be interpreted. */
+type OpenApiInputKind = "content" | "file";
+/** Options for secure OpenAPI parsing and validation. */
+interface ValidateOpenApiOptions {
+    /** Explicitly selects whether input is raw content or a local file path. */
+    inputKind?: OpenApiInputKind;
+    /** Base file path used for reference resolution context. */
+    baseFilePath?: string;
+    /** Root directory that contains every allowed local file. */
+    allowedRootDirectory?: string;
+    /** Total operation deadline in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum raw input size in bytes. */
+    maxInputBytes?: number;
+    /** Maximum nodes permitted in parsed documents. */
+    maxDocumentNodes?: number;
+    /** Maximum nested object or array depth permitted in documents. */
+    maxDocumentDepth?: number;
+    /** Maximum validation errors included in an error message. */
+    maxValidationErrors?: number;
+    /** Maximum characters included for each validation error. */
+    maxErrorMessageLength?: number;
+    /** Optional cancellation signal. */
+    signal?: AbortSignal;
+}
+/** A structured error safe to expose after mapping by an application boundary. */
+declare class OpenApiValidationError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+/**
+ * Validates a raw YAML or JSON OpenAPI document.
+ *
+ * Input is treated as content by default. File-path interpretation is only
+ * enabled by explicitly setting inputKind to "file".
+ *
+ * Validation is delegated to @powerduck/openapi-parser (which wraps
+ * @scalar/openapi-parser). This module adds secure input handling: size
+ * limits, path sandboxing, structural complexity guards, and deadlines.
+ */
+declare function validateOpenAPISpec(input: string, options?: ValidateOpenApiOptions): Promise<AnyOpenAPIDocument>;
+/**
+ * Validates an OpenAPI document from an explicitly supplied local file path.
+ */
+declare function validateOpenAPIFile(filePath: string, options?: ValidateOpenApiOptions): Promise<AnyOpenAPIDocument>;
+
+/**
+ * Detects a supported configuration format from a local file path or file URL.
+ */
+declare function detectFormat(filePath: string): ConfigFormat;
+
+/**
+ * Converts a local path or file URL into an absolute native path.
+ * Keeps valid whitespace and Unicode file names unchanged.
+ */
+declare function normalizeFilePath(filePath: string): string;
+
+export { type AnyOpenAPIDocument, ConfigFormat, JsonPatchOp, type OpenApiInputKind, OpenApiValidationError, PatchConfigOptions, type ValidateOpenApiOptions, type WriteConfigOptions, deleteConfigValue, detectFormat, normalizeFilePath, patchConfigFile, readConfigFile, releaseAllLocalLocks, setConfigValue, validateOpenAPIFile, validateOpenAPISpec, withFileLock, writeConfigFile };

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { P as PatchConfigOptions, J as JsonPatchOp, C as ConfigFormat } from './core-CDrue4z-.js';
+export { F as FileLockOptions, a as JsonPathSegment, b as PatchContentOptions, c as assertConfigFormat, d as assertNonEmptyString, e as assertPatchOperations, f as assertPatchPath, g as createError, h as deleteContentValue, i as getErrorMessage, p as patchContent, s as setContentValue } from './core-CDrue4z-.js';
+import { OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
+
+/**
+ * Reads UTF-8 text from a local file path or file URL.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use the core `patchContent` / `setContentValue`
+ * functions directly with string content.
+ *
+ * @param filePath - Path to the configuration file (absolute, relative, or file:// URL)
+ * @returns The raw UTF-8 content of the file
+ * @throws If the file cannot be read
+ */
+declare function readConfigFile(filePath: string): Promise<string>;
+
+/**
+ * Options for writing a configuration file.
+ */
+interface WriteConfigOptions {
+    /** Enable file locking during the write. Default: true */
+    lock?: boolean;
+    /** Maximum time (ms) to wait to acquire a file lock. */
+    lockTimeoutMs?: number;
+    /** Delay (ms) between retry attempts to acquire a lock. */
+    lockRetryDelayMs?: number;
+    /** Duration (ms) after which a lock is considered stale. */
+    lockStaleThresholdMs?: number;
+    /** Whether stale locks can be automatically reclaimed. */
+    allowStaleRecovery?: boolean;
+}
+/**
+ * Writes content to a configuration file using atomic writes and optional file locking.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use the core `patchContent` / `setContentValue`
+ * functions and store the result in IndexedDB, localStorage, or another storage layer.
+ *
+ * @param filePath - Path to the configuration file
+ * @param content - The content to write
+ * @param options - Optional write settings
+ * @throws If the file cannot be written
+ *
+ * @example
+ * ```typescript
+ * import { writeConfigFile } from "@powerduckie/confedit";
+ *
+ * await writeConfigFile("config.json", '{"name": "app"}');
+ * ```
+ */
+declare function writeConfigFile(filePath: string, content: string, options?: WriteConfigOptions): Promise<void>;
+
+/**
+ * Patches a JSON, JSONC, or YAML file using an atomic locked transaction.
+ *
+ * This function only works in Node.js / Electron environments.
+ * For browser environments, use `patchContent` directly and manage storage yourself.
+ *
+ * @param filePath - Path to the configuration file
+ * @param ops - Array of RFC 6902 patch operations
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { patchConfigFile } from "@powerduckie/confedit";
+ *
+ * await patchConfigFile("config.json", [
+ *   { op: "replace", path: ["server", "host"], value: "0.0.0.0" },
+ *   { op: "add", path: ["server", "ssl"], value: true },
+ *   { op: "remove", path: ["legacySection"] },
+ * ]);
+ * ```
+ */
+declare function patchConfigFile(filePath: string, ops: JsonPatchOp[], options?: PatchConfigOptions): Promise<void>;
+/**
+ * Adds or replaces a nested configuration value in a file.
+ *
+ * Uses the `add` operation, which replaces existing object properties
+ * or inserts at array indices (RFC 6902 behavior).
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param filePath - Path to the configuration file
+ * @param path - Segment path to the target key
+ * @param value - Value to set
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { setConfigValue } from "@powerduckie/confedit";
+ *
+ * await setConfigValue("config.yaml", ["database", "port"], 5432);
+ * ```
+ */
+declare function setConfigValue(filePath: string, path: readonly (string | number)[], value: unknown, options?: PatchConfigOptions): Promise<void>;
+/**
+ * Removes an existing nested configuration value from a file.
+ *
+ * This function only works in Node.js / Electron environments.
+ *
+ * @param filePath - Path to the configuration file
+ * @param path - Segment path to remove
+ * @param options - Optional patch settings
+ *
+ * @example
+ * ```typescript
+ * import { deleteConfigValue } from "@powerduckie/confedit";
+ *
+ * await deleteConfigValue("config.json", ["features", "betaPreview"]);
+ * ```
+ */
+declare function deleteConfigValue(filePath: string, path: readonly (string | number)[], options?: PatchConfigOptions): Promise<void>;
+
+interface FileLockOptions {
+    /** Maximum time to wait for a lock. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** Initial retry delay. Defaults to 25ms. */
+    retryDelayMs?: number;
+    /** Explicit lock age after which recovery is allowed. */
+    staleThresholdMs?: number;
+    /**
+     * Whether stale locks can be automatically reclaimed.
+     * Disable by default for Electron single main process to avoid live transaction preemption.
+     */
+    allowStaleRecovery?: boolean;
+}
+/**
+ * Runs work under a process-local queue and an exclusive lock file.
+ *
+ * A stale lock is recovered only when allowStaleRecovery = true and the lock exceeds staleThresholdMs.
+ * PID checks are intentionally avoided: PIDs can be reused and cannot reliably identify the original process.
+ */
+declare function withFileLock<T>(filePath: string, callback: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Release all locks owned by current process, designed for Electron app.will-quit
+ */
+declare function releaseAllLocalLocks(): Promise<void>;
+
+/** A permissive structural type for OpenAPI 3.2 documents. */
+interface OpenAPIV3_2Document {
+    openapi: string;
+    info: Record<string, unknown>;
+    paths?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Supported OpenAPI and Swagger document shapes. */
+type AnyOpenAPIDocument = OpenAPIV2.Document | OpenAPIV3.Document | OpenAPIV3_1.Document | OpenAPIV3_2Document;
+/** Selects how the supplied input string must be interpreted. */
+type OpenApiInputKind = "content" | "file";
+/** Options for secure OpenAPI parsing and validation. */
+interface ValidateOpenApiOptions {
+    /** Explicitly selects whether input is raw content or a local file path. */
+    inputKind?: OpenApiInputKind;
+    /** Base file path used for reference resolution context. */
+    baseFilePath?: string;
+    /** Root directory that contains every allowed local file. */
+    allowedRootDirectory?: string;
+    /** Total operation deadline in milliseconds. */
+    timeoutMs?: number;
+    /** Maximum raw input size in bytes. */
+    maxInputBytes?: number;
+    /** Maximum nodes permitted in parsed documents. */
+    maxDocumentNodes?: number;
+    /** Maximum nested object or array depth permitted in documents. */
+    maxDocumentDepth?: number;
+    /** Maximum validation errors included in an error message. */
+    maxValidationErrors?: number;
+    /** Maximum characters included for each validation error. */
+    maxErrorMessageLength?: number;
+    /** Optional cancellation signal. */
+    signal?: AbortSignal;
+}
+/** A structured error safe to expose after mapping by an application boundary. */
+declare class OpenApiValidationError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+/**
+ * Validates a raw YAML or JSON OpenAPI document.
+ *
+ * Input is treated as content by default. File-path interpretation is only
+ * enabled by explicitly setting inputKind to "file".
+ *
+ * Validation is delegated to @powerduck/openapi-parser (which wraps
+ * @scalar/openapi-parser). This module adds secure input handling: size
+ * limits, path sandboxing, structural complexity guards, and deadlines.
+ */
+declare function validateOpenAPISpec(input: string, options?: ValidateOpenApiOptions): Promise<AnyOpenAPIDocument>;
+/**
+ * Validates an OpenAPI document from an explicitly supplied local file path.
+ */
+declare function validateOpenAPIFile(filePath: string, options?: ValidateOpenApiOptions): Promise<AnyOpenAPIDocument>;
+
+/**
+ * Detects a supported configuration format from a local file path or file URL.
+ */
+declare function detectFormat(filePath: string): ConfigFormat;
+
+/**
+ * Converts a local path or file URL into an absolute native path.
+ * Keeps valid whitespace and Unicode file names unchanged.
+ */
+declare function normalizeFilePath(filePath: string): string;
+
+export { type AnyOpenAPIDocument, ConfigFormat, JsonPatchOp, type OpenApiInputKind, OpenApiValidationError, PatchConfigOptions, type ValidateOpenApiOptions, type WriteConfigOptions, deleteConfigValue, detectFormat, normalizeFilePath, patchConfigFile, readConfigFile, releaseAllLocalLocks, setConfigValue, validateOpenAPIFile, validateOpenAPISpec, withFileLock, writeConfigFile };

package/dist/index.js

@@ -0,0 +1 @@
+Object.create;var e,t=Object.defineProperty,r=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,n=(Object.getPrototypeOf,Object.prototype.hasOwnProperty),__copyProps=(e,a,i,s)=>{if(a&&"object"==typeof a||"function"==typeof a)for(let c of o(a))n.call(e,c)||c===i||t(e,c,{get:()=>a[c],enumerable:!(s=r(a,c))||s.enumerable});return e},a={};((e,r)=>{for(var o in r)t(e,o,{get:r[o],enumerable:!0})})(a,{OpenApiValidationError:()=>I,assertConfigFormat:()=>assertConfigFormat,assertNonEmptyString:()=>assertNonEmptyString,assertPatchOperations:()=>assertPatchOperations,assertPatchPath:()=>assertPatchPath,createError:()=>createError2,deleteConfigValue:()=>deleteConfigValue,deleteContentValue:()=>deleteContentValue,detectFormat:()=>detectFormat,getErrorMessage:()=>getErrorMessage2,normalizeFilePath:()=>normalizeFilePath,patchConfigFile:()=>patchConfigFile,patchContent:()=>patchContent,readConfigFile:()=>readConfigFile,releaseAllLocalLocks:()=>releaseAllLocalLocks,setConfigValue:()=>setConfigValue,setContentValue:()=>setContentValue,validateOpenAPIFile:()=>validateOpenAPIFile,validateOpenAPISpec:()=>validateOpenAPISpec,withFileLock:()=>withFileLock,writeConfigFile:()=>writeConfigFile}),module.exports=(e=a,__copyProps(t({},"__esModule",{value:!0}),e));var i=require("jsonc-parser"),s={insertSpaces:!0,tabSize:2,eol:"\n"};function validateOperation(e){if(null===e||"object"!=typeof e)throw new TypeError("Patch operation must be an object.");if(!Array.isArray(e.path)||0===e.path.length)throw new Error("Patch operation path must be a non-empty array.");if("add"!==e.op&&"replace"!==e.op&&"remove"!==e.op)throw new Error(`Unsupported JSON patch operation: ${String(e.op)}`);if(("add"===e.op||"replace"===e.op)&&!Object.prototype.hasOwnProperty.call(e,"value"))throw new Error(`Patch operation "${e.op}" requires a value.`)}function normalizePath(e){return e.map(e=>{if("number"==typeof e){if(!Number.isSafeInteger(e)||e<0)throw new Error(`Invalid array index: ${e}`);return e}if("string"!=typeof e)throw new TypeError(`Patch path segments must be strings or numbers; received ${typeof e}.`);return e})}function applyAdd(e,t,r){const o=function(e,t){if(1===t.length){if("object"!==e.type&&"array"!==e.type)throw new Error("Cannot add a root child to a scalar JSON value.");return e}const r=t.slice(0,-1),o=(0,i.findNodeAtLocation)(e,r);if(void 0===o)throw new Error(`Cannot add value because its parent does not exist at path: ${formatPath(r)}`);if("object"!==o.type&&"array"!==o.type)throw new Error(`Cannot add value because its parent is not an object or array at path: ${formatPath(r)}`);return o}(getTree(e),t),n=t[t.length-1];if("array"===o.type){const a=function(e,t){if("number"!=typeof e)throw new Error(`Array index must be a number at path: ${formatPath(t)}`);if(!Number.isSafeInteger(e)||e<0)throw new Error(`Invalid array index ${e} at path: ${formatPath(t)}`);return e}(n,t),i=o.children?.length??0;if(a>i)throw new Error(`Cannot add at array index ${a}; array length is ${i} at path: ${formatPath(t.slice(0,-1))}`);return applyModify(e,t,r,!0)}if("object"===o.type){if("string"!=typeof n)throw new Error(`Object property path segment must be a string at path: ${formatPath(t)}`);return applyModify(e,t,r,!1)}throw new Error(`Cannot add a child to non-container value at path: ${formatPath(t.slice(0,-1))}`)}function applyReplace(e,t,r){const o=getTree(e);if(void 0===(0,i.findNodeAtLocation)(o,t))throw new Error(`Cannot replace a value that does not exist at path: ${formatPath(t)}`);return applyModify(e,t,r,!1)}function applyRemove(e,t){const r=getTree(e);if(void 0===(0,i.findNodeAtLocation)(r,t))throw new Error(`Cannot remove a value that does not exist at path: ${formatPath(t)}`);return applyModify(e,t,void 0,!1)}function applyModify(e,t,r,o){const n=(0,i.modify)(e,t,r,{formattingOptions:s,isArrayInsertion:o});if(0===n.length)throw new Error(`No JSONC edit was generated for path: ${formatPath(t)}`);return(0,i.applyEdits)(e,n)}function getTree(e){const t=[],r=(0,i.parseTree)(e,t,{allowTrailingComma:!0,disallowComments:!1});if(void 0===r||t.length>0)throw new Error(`The source text is not valid JSON or JSONC${function(e){if(0===e.length)return"";return` (parse errors: ${e.map(e=>`code=${e.error}, offset=${e.offset}`).join("; ")})`}(t)}.`);return r}function formatPath(e){return`[${e.map(e=>JSON.stringify(e)).join(", ")}]`}function safeStringify(e){try{return JSON.stringify(e)}catch{return"[unserializable patch operation]"}}function getErrorMessage(e){return e instanceof Error?e.message:String(e)}function createError(e,t){const r=new Error(e);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:t,writable:!0})}catch{}return r}var c=require("yaml");function applyYamlOperation(e,t){!function(e){if(!Array.isArray(e.path)||0===e.path.length)throw new Error("[confedit] Patch path must be a non-empty array.");if("add"!==e.op&&"replace"!==e.op&&"remove"!==e.op)throw new Error(`[confedit] Unsupported patch operation: ${String(e.op)}.`)}(t);const r=t.path,o=function(e,t){if(0===t.length)throw new Error("[confedit] Replacing the YAML document root is not supported.");if(1===t.length){if(null===e.contents)throw new Error("[confedit] Cannot patch an empty YAML document without a root container.");return e.contents}const r=t.slice(0,-1),o=e.getIn(r,!0);if(null==o)throw new Error(`[confedit] Missing parent path: ${formatPath2(r)}.`);if(!(0,c.isMap)(o)&&!(0,c.isSeq)(o))throw new Error(`[confedit] Parent at ${formatPath2(r)} is not a YAML map or sequence.`);return o}(e,r),n=r[r.length-1];if((0,c.isMap)(o))!function(e,t,r,o){if("string"!=typeof r)throw new Error(`[confedit] YAML map keys must be strings at ${formatPath2(o.path)}.`);const n=t.has(r);switch(o.op){case"add":return void t.set(r,e.createNode(o.value));case"replace":if(!n)throw new Error(`[confedit] Cannot replace missing value at ${formatPath2(o.path)}.`);return void t.set(r,e.createNode(o.value));case"remove":if(!n)throw new Error(`[confedit] Cannot remove missing value at ${formatPath2(o.path)}.`);return void t.delete(r);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(e,o,n,t);else{if(!(0,c.isSeq)(o))throw new Error(`[confedit] Cannot apply patch at ${formatPath2(r)} because its parent is not a YAML map or sequence.`);!function(e,t,r,o){if("number"!=typeof r||!Number.isSafeInteger(r)||r<0)throw new Error(`[confedit] YAML sequence indexes must be non-negative integers at ${formatPath2(o.path)}.`);const n=t.items.length;switch(o.op){case"add":if(r>n)throw new Error(`[confedit] Cannot insert at index ${r}; sequence length is ${n}.`);return void t.items.splice(r,0,e.createNode(o.value));case"replace":if(r>=n)throw new Error(`[confedit] Cannot replace index ${r}; sequence length is ${n}.`);return void(t.items[r]=e.createNode(o.value));case"remove":if(r>=n)throw new Error(`[confedit] Cannot remove index ${r}; sequence length is ${n}.`);return void t.items.splice(r,1);default:throw new Error(`[confedit] Unsupported patch operation: ${String(o.op)}.`)}}(e,o,n,t)}}function formatPath2(e){return`[${e.map(e=>JSON.stringify(e)).join(", ")}]`}function assertNonEmptyString(e,t){if("string"!=typeof e||0===e.length)throw new TypeError(`[confedit] ${t} must be a non-empty string.`)}function assertPatchPath(e,t="path"){if(!Array.isArray(e)||0===e.length)throw new TypeError(`[confedit] ${t} must be a non-empty array.`);for(const[r,o]of e.entries())if("string"!=typeof o){if("number"!=typeof o||!Number.isSafeInteger(o)||o<0)throw new TypeError(`[confedit] ${t}[${r}] must be a non-empty string or a non-negative integer.`)}else if(0===o.length)throw new TypeError(`[confedit] ${t}[${r}] must not be an empty string.`)}function assertPatchOperations(e){if(!Array.isArray(e))throw new TypeError("[confedit] ops must be an array.");for(const[t,r]of e.entries()){if(null===r||"object"!=typeof r)throw new TypeError(`[confedit] Patch operation at index ${t} must be an object.`);if("add"!==r.op&&"replace"!==r.op&&"remove"!==r.op)throw new Error(`[confedit] Unsupported patch operation at index ${t}: ${String(r.op)}.`);if(assertPatchPath(r.path,`ops[${t}].path`),("add"===r.op||"replace"===r.op)&&!Object.prototype.hasOwnProperty.call(r,"value"))throw new TypeError(`[confedit] Patch operation at index ${t} requires a value.`)}}function assertConfigFormat(e){if("json"!==e&&"jsonc"!==e&&"yaml"!==e)throw new Error(`[confedit] Unsupported configuration format: ${String(e)}.`)}function getErrorMessage2(e){return e instanceof Error?e.message:String(e)}function createError2(e,t){const r=new Error(e);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:t,writable:!0})}catch{}return r}function patchContent(e,t,r,o={}){if("string"!=typeof e)throw new TypeError("[confedit] content must be a string.");if(assertPatchOperations(t),assertConfigFormat(r),0===t.length)return e;const n=o.strict??!0;switch(r){case"json":case"jsonc":return function(e,t,r=!0){if("string"!=typeof e)throw new TypeError("[confedit] sourceText must be a string.");if(!Array.isArray(t))throw new TypeError("[confedit] ops must be an array.");let o=e;for(const e of t)try{validateOperation(e);const t=normalizePath(e.path);switch(e.op){case"add":o=applyAdd(o,t,e.value);break;case"replace":o=applyReplace(o,t,e.value);break;case"remove":o=applyRemove(o,t);break;default:throw new Error(`[confedit] Unsupported JSON patch operation: ${String(e.op)}`)}}catch(t){const o=`[confedit] Failed to apply JSON patch ${safeStringify(e)}: ${getErrorMessage(t)}`;if(r)throw createError(o,t);console.warn(o)}return o}(e,t,n);case"yaml":return function(e,t,r=!0){const o=(0,c.parseDocument)(e,{prettyErrors:!0,strict:!0});if(o.errors.length>0)throw new Error(`[confedit] Invalid YAML source: ${o.errors.map(e=>e.message).join("; ")}`);for(const e of t)try{applyYamlOperation(o,e)}catch(t){if(r)throw t;console.warn(`[confedit yaml patch warn] Skip operation ${JSON.stringify(e)}`,t)}return o.toString()}(e,t,n)}}function setContentValue(e,t,r,o){return assertPatchPath(t),patchContent(e,[{op:"add",path:[...t],value:r}],o)}function deleteContentValue(e,t,r){return assertPatchPath(t),patchContent(e,[{op:"remove",path:[...t]}],r)}var l=require("fs/promises"),u=require("path"),f=require("url");function normalizeFilePath(e){if("string"!=typeof e||0===e.length)throw new TypeError("[confedit] filePath must be a non-empty string.");if(e.startsWith("file:"))try{return(0,f.fileURLToPath)(e)}catch(t){throw function(e,t){const r=new Error(e);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:t,writable:!0})}catch{}return r}(`[confedit] Invalid file URL "${e}": ${function(e){return e instanceof Error?e.message:String(e)}(t)}`,t)}return(0,u.isAbsolute)(e)?e:(0,u.resolve)(e)}async function readConfigFile(e){assertNonEmptyString(e,"filePath");const t=normalizeFilePath(e);try{return await(0,l.readFile)(t,"utf8")}catch(t){throw createError2(`[confedit] Failed to read "${e}": ${getErrorMessage2(t)}`,t)}}var p=require("fs/promises"),h=require("path"),d=require("crypto"),m=require("fs/promises"),w=require("path");async function atomicWrite(e,t){if(function(e,t){if("string"!=typeof e||0===e.length)throw new TypeError(`[confedit] ${t} must be a non-empty string.`)}(e,"filePath"),"string"!=typeof t)throw new TypeError("[confedit] content must be a string.");const r=normalizeFilePath(e),o=(0,w.dirname)(r),n=(0,w.basename)(r),a=`${process.pid}.${Date.now()}.${(0,d.randomBytes)(12).toString("hex")}`,i=(0,w.join)(o,`.${n}.${a}.tmp`),s=(0,w.join)(o,`.${n}.${a}.bak`);let c,l=!1,u=!1;try{await(0,m.mkdir)(o,{recursive:!0});const e=await async function(e){try{return 511&(await(0,m.stat)(e)).mode}catch(e){if("ENOENT"===getErrorCode(e))return;throw e}}(r);c=await(0,m.open)(i,"wx",e??384);try{await c.writeFile(t,"utf8"),await c.sync()}finally{await c.close(),c=void 0}void 0!==e&&await(0,m.chmod)(i,e);try{await(0,m.rename)(i,r),u=!0}catch(e){if(!function(e){if("win32"!==process.platform)return!1;const t=getErrorCode(e);return"EEXIST"===t||"EPERM"===t||"EACCES"===t}(e))throw e;await(0,m.rename)(r,s),l=!0;try{await(0,m.rename)(i,r),u=!0}catch(e){const t=await async function(e,t){try{return await(0,m.unlink)(e).catch(e=>{if("ENOENT"!==getErrorCode(e))throw e}),await(0,m.rename)(t,e),!0}catch{return!1}}(r,s);throw t&&(l=!1),createError4(t?`[confedit] Failed to replace "${r}", but the original file was restored.`:`[confedit] Failed to replace "${r}". The backup was retained at "${s}".`,e)}}await syncDirectory(o),l&&(await(0,m.unlink)(s),l=!1,await syncDirectory(o))}catch(t){throw void 0!==c&&await c.close().catch(()=>{}),createError4(`[confedit] Failed to atomically write "${e}": ${function(e){return e instanceof Error?e.message:String(e)}(t)}`,t)}finally{await(0,m.unlink)(i).catch(()=>{}),u&&l&&await(0,m.unlink)(s).catch(()=>{})}}async function syncDirectory(e){let t;try{t=await(0,m.open)(e,"r"),await t.sync()}catch(e){const t=getErrorCode(e);if("EINVAL"!==t&&"EPERM"!==t&&"EISDIR"!==t&&"ENOSYS"!==t&&"ENOTSUP"!==t)throw e}finally{await(t?.close().catch(()=>{}))}}function getErrorCode(e){if(null!==e&&"object"==typeof e&&"code"in e&&"string"==typeof e.code)return e.code}function createError4(e,t){const r=new Error(e);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:t,writable:!0})}catch{}return r}var y=require("crypto"),g=require("fs/promises"),E=require("os"),b=1e4,v=25,P=1e3,O=6e4,$=new Map,M=new Set;async function withFileLock(e,t,r={}){const o=normalizeFilePath(e);return function(e){if(void 0!==e.timeoutMs&&(!Number.isFinite(e.timeoutMs)||e.timeoutMs<0))throw new TypeError("[confedit] lock timeoutMs must be a non-negative finite number.");if(void 0!==e.retryDelayMs&&(!Number.isFinite(e.retryDelayMs)||e.retryDelayMs<=0))throw new TypeError("[confedit] lock retryDelayMs must be a positive finite number.");if(void 0!==e.staleThresholdMs&&(!Number.isFinite(e.staleThresholdMs)||e.staleThresholdMs<=0))throw new TypeError("[confedit] lock staleThresholdMs must be a positive finite number.")}(r),function(e,t){const r=$.get(e)??Promise.resolve();let o;const n=new Promise(e=>{o=e}),a=r.catch(()=>{}).then(()=>n);return $.set(e,a),r.catch(()=>{}).then(t).finally(()=>{o(),$.get(e)===a&&$.delete(e)})}(o,async()=>{const e=await async function(e,t){const r=t.timeoutMs??b,o=t.retryDelayMs??v,n=t.staleThresholdMs??Math.max(2*r,O),a=t.allowStaleRecovery??!1,i=`${e}.confedit.lock`,s=Date.now();let c=o;const l=createToken(),u={version:1,pid:process.pid,hostname:(0,E.hostname)(),createdAt:(new Date).toISOString(),token:l};for(;;)try{const e=await(0,g.open)(i,"wx",384);try{await(0,g.writeFile)(e,`${JSON.stringify(u)}\n`,"utf8"),await e.sync()}finally{await e.close()}return M.add(i),createReleaseHandler(i,l)}catch(t){if("EEXIST"!==getErrorCode2(t))throw createError5(`[confedit] Failed to acquire lock "${i}": ${getErrorMessage5(t)}`,t);if(a&&await tryRecoverStaleLock(i,n),Date.now()-s>=r)throw new Error(`[confedit] Timed out waiting for lock on "${e}" after ${r}ms.`);await sleep(c),c=Math.min(Math.ceil(1.5*c),P)}}(o,r);try{return await t()}finally{await e()}})}async function releaseAllLocalLocks(){const e=Array.from(M).map(e=>(0,g.unlink)(e).catch(()=>{}));await Promise.allSettled(e),M.clear()}function createReleaseHandler(e,t){return async()=>{try{const r=await readLockData(e);r?.token===t&&(await(0,g.unlink)(e).catch(()=>{}),M.delete(e))}catch{}}}async function tryRecoverStaleLock(e,t){const r=await readLockData(e);if(void 0===r||!isExpiredLock(r,t))return;const o=`${e}.stale.${createToken()}`;try{await(0,g.rename)(e,o)}catch(e){return void getErrorCode2(e)}try{const n=await readLockData(o);if(n?.token===r.token&&isExpiredLock(n,t))return void await(0,g.unlink)(o).catch(()=>{});await(0,g.rename)(o,e).catch(()=>{})}catch{}}function isExpiredLock(e,t){const r=Date.parse(e.createdAt);return Number.isFinite(r)&&Date.now()-r>t}async function readLockData(e){try{return function(e){try{const t=JSON.parse(e);if(1!==t.version||"number"!=typeof t.pid||!Number.isSafeInteger(t.pid)||t.pid<=0||"string"!=typeof t.hostname||"string"!=typeof t.createdAt||!Number.isFinite(Date.parse(t.createdAt))||"string"!=typeof t.token||t.token.length<16)return;return{version:1,pid:t.pid,hostname:t.hostname,createdAt:t.createdAt,token:t.token}}catch{return}}(await(0,g.readFile)(e,"utf8"))}catch{return}}function createToken(){return`${process.pid}-${Date.now()}-${(0,y.randomBytes)(16).toString("hex")}`}function sleep(e){return new Promise(t=>setTimeout(t,e))}function getErrorCode2(e){if(null!==e&&"object"==typeof e&&"code"in e&&"string"==typeof e.code)return e.code}function getErrorMessage5(e){return e instanceof Error?e.message:String(e)}function createError5(e,t){const r=new Error(e);try{Object.defineProperty(r,"cause",{configurable:!0,enumerable:!1,value:t,writable:!0})}catch{}return r}async function writeConfigFile(e,t,r={}){if(assertNonEmptyString(e,"filePath"),"string"!=typeof t)throw new TypeError("[confedit] content must be a string.");const o=normalizeFilePath(e),writeTransaction=async()=>{try{await atomicWrite(o,t)}catch(t){throw createError2(`[confedit] Failed to write "${e}": ${getErrorMessage2(t)}`,t)}};r.lock??!0?(await(0,p.mkdir)((0,h.dirname)(o),{recursive:!0}),await withFileLock(o,writeTransaction,{timeoutMs:r.lockTimeoutMs,retryDelayMs:r.lockRetryDelayMs,staleThresholdMs:r.lockStaleThresholdMs,allowStaleRecovery:r.allowStaleRecovery})):await writeTransaction()}var T=require("path");function detectFormat(e){const t=normalizeFilePath(e);switch((0,T.extname)(t).toLowerCase()){case".json":return"json";case".jsonc":return"jsonc";case".yaml":case".yml":return"yaml";default:throw new Error(`[confedit] Cannot detect a supported configuration format for "${e}". Expected .json, .jsonc, .yaml, or .yml.`)}}async function patchConfigFile(e,t,r={}){if("string"!=typeof e||0===e.length)throw new TypeError("[confedit] filePath must be a non-empty string.");if(assertPatchOperations(t),0===t.length)return;const o=normalizeFilePath(e),n=r.format??detectFormat(o);assertConfigFormat(n),function(e){if(void 0!==e.lockTimeoutMs&&(!Number.isFinite(e.lockTimeoutMs)||e.lockTimeoutMs<0))throw new TypeError("[confedit] lockTimeoutMs must be a non-negative finite number.");if(void 0!==e.lockRetryDelayMs&&(!Number.isFinite(e.lockRetryDelayMs)||e.lockRetryDelayMs<=0))throw new TypeError("[confedit] lockRetryDelayMs must be a positive finite number.");if(void 0!==e.lockStaleThresholdMs&&(!Number.isFinite(e.lockStaleThresholdMs)||e.lockStaleThresholdMs<=0))throw new TypeError("[confedit] lockStaleThresholdMs must be a positive finite number.")}(r);const a=r.strict??!0,patchTransaction=async()=>{const r=await readConfigFile(o),i=patchContent(r,t,n,{strict:a});if(i!==r)try{await atomicWrite(o,i)}catch(t){throw createError2(`[confedit] Failed to write "${e}": ${getErrorMessage2(t)}`,t)}};r.lock??!0?await withFileLock(o,patchTransaction,{timeoutMs:r.lockTimeoutMs,retryDelayMs:r.lockRetryDelayMs,staleThresholdMs:r.lockStaleThresholdMs,allowStaleRecovery:r.allowStaleRecovery}):await patchTransaction()}async function setConfigValue(e,t,r,o={}){await patchConfigFile(e,[{op:"add",path:[...t],value:r}],o)}async function deleteConfigValue(e,t,r={}){await patchConfigFile(e,[{op:"remove",path:[...t]}],r)}var D,N=require("fs/promises"),S=require("path"),A=require("yaml"),I=class extends Error{constructor(e,t,r){super(t),this.name="OpenApiValidationError",this.code=e,this.cause=r}},F={inputKind:"content",timeoutMs:15e3,maxInputBytes:5242880,maxDocumentNodes:1e5,maxDocumentDepth:100,maxValidationErrors:50,maxErrorMessageLength:1e3};async function validateOpenAPISpec(e,t={}){!function(e,t){if("string"!=typeof e||0===e.length)throw new TypeError(`[confedit] ${t} must be a non-empty string.`)}(e,"input");const r=function(e){const t={inputKind:e.inputKind??F.inputKind,baseFilePath:e.baseFilePath,allowedRootDirectory:e.allowedRootDirectory,timeoutMs:e.timeoutMs??F.timeoutMs,maxInputBytes:e.maxInputBytes??F.maxInputBytes,maxDocumentNodes:e.maxDocumentNodes??F.maxDocumentNodes,maxDocumentDepth:e.maxDocumentDepth??F.maxDocumentDepth,maxValidationErrors:e.maxValidationErrors??F.maxValidationErrors,maxErrorMessageLength:e.maxErrorMessageLength??F.maxErrorMessageLength,signal:e.signal};if("content"!==t.inputKind&&"file"!==t.inputKind)throw new I("INVALID_OPTION",`inputKind must be "content" or "file", got: ${String(t.inputKind)}.`);return assertPositiveFiniteNumber(t.timeoutMs,"timeoutMs"),assertPositiveFiniteNumber(t.maxInputBytes,"maxInputBytes"),assertPositiveFiniteNumber(t.maxDocumentNodes,"maxDocumentNodes"),assertPositiveFiniteNumber(t.maxDocumentDepth,"maxDocumentDepth"),assertPositiveFiniteNumber(t.maxValidationErrors,"maxValidationErrors"),assertPositiveFiniteNumber(t.maxErrorMessageLength,"maxErrorMessageLength"),t}(t),o=function(e){const t=new AbortController;if(e){if(!e.aborted){const onAbort=()=>t.abort();return e.addEventListener("abort",onAbort,{once:!0}),{controller:t,dispose:()=>e.removeEventListener("abort",onAbort)}}t.abort()}return{controller:t,dispose:()=>{}}}(r.signal),n={options:r,controller:o.controller,deadline:Date.now()+r.timeoutMs};try{return await runWithDeadline(n,async()=>{if("file"===r.inputKind){const t=await async function(e,t){const r=normalizeFilePath(e);if(!t.options.allowedRootDirectory)throw new I("FILE_INPUT_FORBIDDEN","File input requires allowedRootDirectory.");return async function(e,t){const r=(0,S.isAbsolute)(e)?e:(0,S.resolve)(t,e),o=await(0,N.realpath)(r),n=(0,S.relative)(t,o);if(n.startsWith("..")||""===n||"\\"===S.sep&&/^[a-zA-Z]:/.test(n))throw new I("PATH_OUTSIDE_ROOT",`File path is outside the allowed root directory: ${e}.`);return o}(r,await async function(e){if(e.rootDirectory)return e.rootDirectory;const t=e.options.allowedRootDirectory;if(!t)throw new I("INVALID_OPTION","allowedRootDirectory is required for file operations.");const r=(0,S.resolve)(t),o=await(0,N.realpath)(r);if(!(await(0,N.stat)(o)).isDirectory())throw new I("INVALID_OPTION",`allowedRootDirectory is not a directory: ${t}.`);return e.rootDirectory=o,o}(t))}(e,n),o=await async function(e,t,r,o){throwIfCancelled(r);const n=await(0,N.open)(e,"r");try{const r=await n.stat();if(r.size>t)throw new I(o,`File exceeds maximum allowed size of ${t} bytes: ${e}.`);const a=Buffer.alloc(r.size);return await n.read(a,0,r.size,0),a.toString("utf8")}finally{await n.close()}}(t,r.maxInputBytes,n,"INPUT_FILE_TOO_LARGE");return validateRawContent(o,{...n,options:{...r,baseFilePath:t}})}return assertByteLength(e,r.maxInputBytes,"INPUT_TOO_LARGE"),validateRawContent(e,n)})}catch(e){throw function(e){if(e instanceof I)return e;return new I("UNKNOWN_ERROR",`OpenAPI validation failed: ${getErrorMessage6(e)}.`,e)}(e)}finally{o.dispose(),n.controller.abort()}}async function validateOpenAPIFile(e,t={}){return validateOpenAPISpec(e,{...t,inputKind:"file",baseFilePath:e})}async function validateRawContent(e,t){throwIfCancelled(t),assertByteLength(e,t.options.maxInputBytes,"INPUT_TOO_LARGE");const r=function(e){try{const t=(0,A.parse)(e);if(null===t||"object"!=typeof t||Array.isArray(t))throw new I("INVALID_DOCUMENT_SHAPE","OpenAPI document must be a JSON object.");return t}catch(e){if(e instanceof I)throw e;throw new I("PARSE_ERROR",`Failed to parse OpenAPI document: ${getErrorMessage6(e)}.`,e)}}(e);!function(e,t){let r=0;const o=[{value:e,depth:0}];for(;o.length>0;){const{value:e,depth:n}=o.pop();if(n>t.maxDocumentDepth)throw new I("DOCUMENT_TOO_DEEP",`Document exceeds maximum nesting depth of ${t.maxDocumentDepth}.`);if(r++,r>t.maxDocumentNodes)throw new I("DOCUMENT_TOO_LARGE",`Document exceeds maximum node count of ${t.maxDocumentNodes}.`);if(Array.isArray(e))for(const t of e)o.push({value:t,depth:n+1});else if(null!==e&&"object"==typeof e)for(const t of Object.values(e))o.push({value:t,depth:n+1})}}(r,t.options),function(e){const t=e.openapi??e.swagger;if("string"!=typeof t||0===t.length)throw new I("UNSUPPORTED_VERSION","Document must declare an openapi or swagger version.");const r=Number.parseInt(t.split(".")[0]??"",10);if(!Number.isFinite(r)||2!==r&&3!==r)throw new I("UNSUPPORTED_VERSION",`Unsupported OpenAPI/Swagger version: ${t}. Supported: 2.x, 3.x.`)}(r);const o=await runWithDeadline(t,()=>async function(){return D??=import("@powerduck/openapi-parser").then(({validate:e})=>e),D}()),n=await runWithDeadline(t,()=>o(r,{throwOnError:!1}));if(!n.valid)throw new I("SPEC_VALIDATION_FAILED",`OpenAPI validation failed: ${function(e,t,r){const o=e.slice(0,t).map(e=>{const t=e.instancePath??"",o=e.message??"Unknown error",n=t?`${t}: ${o}`:o;return n.length>r?`${n.slice(0,r)}...`:n});e.length>t&&o.push(`... and ${e.length-t} more errors`);return o.join("; ")}(n.errors??[],t.options.maxValidationErrors,t.options.maxErrorMessageLength)}`);return n.specification}function assertPositiveFiniteNumber(e,t){if(!Number.isFinite(e)||e<=0)throw new I("INVALID_OPTION",`${t} must be a positive finite number, got: ${String(e)}.`)}async function runWithDeadline(e,t){throwIfCancelled(e);const r=await Promise.race([t(),createDeadlinePromise(e)]);return throwIfCancelled(e),r}function createDeadlinePromise(e){return new Promise((t,r)=>{const o=e.deadline-Date.now(),n=Math.max(0,Math.min(o,2147483647)),a=setTimeout(()=>{r(new I("OPERATION_TIMEOUT",`OpenAPI validation operation timed out after ${e.options.timeoutMs}ms.`))},n);e.controller.signal.addEventListener("abort",()=>{clearTimeout(a),r(new I("OPERATION_ABORTED","OpenAPI validation operation was aborted."))},{once:!0})})}function throwIfCancelled(e){if(e.controller.signal.aborted)throw new I("OPERATION_ABORTED","OpenAPI validation operation was aborted.");if(Date.now()>e.deadline)throw new I("OPERATION_TIMEOUT",`OpenAPI validation operation timed out after ${e.options.timeoutMs}ms.`)}function assertByteLength(e,t,r){const o=Buffer.byteLength(e,"utf8");if(o>t)throw new I(r,`Input exceeds maximum allowed size of ${t} bytes (actual: ${o} bytes).`)}function getErrorMessage6(e){return e instanceof Error?e.message:String(e)}

package/dist/index.mjs

@@ -0,0 +1 @@
+import{assertConfigFormat as t,assertNonEmptyString as e,assertPatchOperations as o,assertPatchPath as r,createError as n,deleteContentValue as i,getErrorMessage as a,patchContent as s,setContentValue as c}from"./chunk-YWMVVRYM.mjs";import{readFile as l}from"fs/promises";import{isAbsolute as u,resolve as f}from"path";import{fileURLToPath as m}from"url";function normalizeFilePath(t){if("string"!=typeof t||0===t.length)throw new TypeError("[confedit] filePath must be a non-empty string.");if(t.startsWith("file:"))try{return m(t)}catch(e){throw function(t,e){const o=new Error(t);try{Object.defineProperty(o,"cause",{configurable:!0,enumerable:!1,value:e,writable:!0})}catch{}return o}(`[confedit] Invalid file URL "${t}": ${function(t){return t instanceof Error?t.message:String(t)}(e)}`,e)}return u(t)?t:f(t)}async function readConfigFile(t){e(t,"filePath");const o=normalizeFilePath(t);try{return await l(o,"utf8")}catch(e){throw n(`[confedit] Failed to read "${t}": ${a(e)}`,e)}}import{mkdir as d}from"fs/promises";import{dirname as w}from"path";import{randomBytes as h}from"crypto";import{chmod as p,mkdir as y,open as g,rename as E,stat as D,unlink as b}from"fs/promises";import{basename as T,dirname as v,join as M}from"path";async function atomicWrite(t,e){if(function(t,e){if("string"!=typeof t||0===t.length)throw new TypeError(`[confedit] ${e} must be a non-empty string.`)}(t,"filePath"),"string"!=typeof e)throw new TypeError("[confedit] content must be a string.");const o=normalizeFilePath(t),r=v(o),n=T(o),i=`${process.pid}.${Date.now()}.${h(12).toString("hex")}`,a=M(r,`.${n}.${i}.tmp`),s=M(r,`.${n}.${i}.bak`);let c,l=!1,u=!1;try{await y(r,{recursive:!0});const t=await async function(t){try{return 511&(await D(t)).mode}catch(t){if("ENOENT"===getErrorCode(t))return;throw t}}(o);c=await g(a,"wx",t??384);try{await c.writeFile(e,"utf8"),await c.sync()}finally{await c.close(),c=void 0}void 0!==t&&await p(a,t);try{await E(a,o),u=!0}catch(t){if(!function(t){if("win32"!==process.platform)return!1;const e=getErrorCode(t);return"EEXIST"===e||"EPERM"===e||"EACCES"===e}(t))throw t;await E(o,s),l=!0;try{await E(a,o),u=!0}catch(t){const e=await async function(t,e){try{return await b(t).catch(t=>{if("ENOENT"!==getErrorCode(t))throw t}),await E(e,t),!0}catch{return!1}}(o,s);throw e&&(l=!1),createError3(e?`[confedit] Failed to replace "${o}", but the original file was restored.`:`[confedit] Failed to replace "${o}". The backup was retained at "${s}".`,t)}}await syncDirectory(r),l&&(await b(s),l=!1,await syncDirectory(r))}catch(e){throw void 0!==c&&await c.close().catch(()=>{}),createError3(`[confedit] Failed to atomically write "${t}": ${function(t){return t instanceof Error?t.message:String(t)}(e)}`,e)}finally{await b(a).catch(()=>{}),u&&l&&await b(s).catch(()=>{})}}async function syncDirectory(t){let e;try{e=await g(t,"r"),await e.sync()}catch(t){const e=getErrorCode(t);if("EINVAL"!==e&&"EPERM"!==e&&"EISDIR"!==e&&"ENOSYS"!==e&&"ENOTSUP"!==e)throw t}finally{await(e?.close().catch(()=>{}))}}function getErrorCode(t){if(null!==t&&"object"==typeof t&&"code"in t&&"string"==typeof t.code)return t.code}function createError3(t,e){const o=new Error(t);try{Object.defineProperty(o,"cause",{configurable:!0,enumerable:!1,value:e,writable:!0})}catch{}return o}import{randomBytes as P}from"crypto";import{open as O,readFile as I,rename as N,unlink as F,writeFile as x}from"fs/promises";import{hostname as k}from"os";var $=new Map,A=new Set;async function withFileLock(t,e,o={}){const r=normalizeFilePath(t);return function(t){if(void 0!==t.timeoutMs&&(!Number.isFinite(t.timeoutMs)||t.timeoutMs<0))throw new TypeError("[confedit] lock timeoutMs must be a non-negative finite number.");if(void 0!==t.retryDelayMs&&(!Number.isFinite(t.retryDelayMs)||t.retryDelayMs<=0))throw new TypeError("[confedit] lock retryDelayMs must be a positive finite number.");if(void 0!==t.staleThresholdMs&&(!Number.isFinite(t.staleThresholdMs)||t.staleThresholdMs<=0))throw new TypeError("[confedit] lock staleThresholdMs must be a positive finite number.")}(o),function(t,e){const o=$.get(t)??Promise.resolve();let r;const n=new Promise(t=>{r=t}),i=o.catch(()=>{}).then(()=>n);return $.set(t,i),o.catch(()=>{}).then(e).finally(()=>{r(),$.get(t)===i&&$.delete(t)})}(r,async()=>{const t=await async function(t,e){const o=e.timeoutMs??1e4,r=e.retryDelayMs??25,n=e.staleThresholdMs??Math.max(2*o,6e4),i=e.allowStaleRecovery??!1,a=`${t}.confedit.lock`,s=Date.now();let c=r;const l=createToken(),u={version:1,pid:process.pid,hostname:k(),createdAt:(new Date).toISOString(),token:l};for(;;)try{const t=await O(a,"wx",384);try{await x(t,`${JSON.stringify(u)}\n`,"utf8"),await t.sync()}finally{await t.close()}return A.add(a),createReleaseHandler(a,l)}catch(e){if("EEXIST"!==getErrorCode2(e))throw createError4(`[confedit] Failed to acquire lock "${a}": ${getErrorMessage4(e)}`,e);if(i&&await tryRecoverStaleLock(a,n),Date.now()-s>=o)throw new Error(`[confedit] Timed out waiting for lock on "${t}" after ${o}ms.`);await sleep(c),c=Math.min(Math.ceil(1.5*c),1e3)}}(r,o);try{return await e()}finally{await t()}})}async function releaseAllLocalLocks(){const t=Array.from(A).map(t=>F(t).catch(()=>{}));await Promise.allSettled(t),A.clear()}function createReleaseHandler(t,e){return async()=>{try{const o=await readLockData(t);o?.token===e&&(await F(t).catch(()=>{}),A.delete(t))}catch{}}}async function tryRecoverStaleLock(t,e){const o=await readLockData(t);if(void 0===o||!isExpiredLock(o,e))return;const r=`${t}.stale.${createToken()}`;try{await N(t,r)}catch(t){return void getErrorCode2(t)}try{const n=await readLockData(r);if(n?.token===o.token&&isExpiredLock(n,e))return void await F(r).catch(()=>{});await N(r,t).catch(()=>{})}catch{}}function isExpiredLock(t,e){const o=Date.parse(t.createdAt);return Number.isFinite(o)&&Date.now()-o>e}async function readLockData(t){try{return function(t){try{const e=JSON.parse(t);if(1!==e.version||"number"!=typeof e.pid||!Number.isSafeInteger(e.pid)||e.pid<=0||"string"!=typeof e.hostname||"string"!=typeof e.createdAt||!Number.isFinite(Date.parse(e.createdAt))||"string"!=typeof e.token||e.token.length<16)return;return{version:1,pid:e.pid,hostname:e.hostname,createdAt:e.createdAt,token:e.token}}catch{return}}(await I(t,"utf8"))}catch{return}}function createToken(){return`${process.pid}-${Date.now()}-${P(16).toString("hex")}`}function sleep(t){return new Promise(e=>setTimeout(e,t))}function getErrorCode2(t){if(null!==t&&"object"==typeof t&&"code"in t&&"string"==typeof t.code)return t.code}function getErrorMessage4(t){return t instanceof Error?t.message:String(t)}function createError4(t,e){const o=new Error(t);try{Object.defineProperty(o,"cause",{configurable:!0,enumerable:!1,value:e,writable:!0})}catch{}return o}async function writeConfigFile(t,o,r={}){if(e(t,"filePath"),"string"!=typeof o)throw new TypeError("[confedit] content must be a string.");const i=normalizeFilePath(t),writeTransaction=async()=>{try{await atomicWrite(i,o)}catch(e){throw n(`[confedit] Failed to write "${t}": ${a(e)}`,e)}};r.lock??!0?(await d(w(i),{recursive:!0}),await withFileLock(i,writeTransaction,{timeoutMs:r.lockTimeoutMs,retryDelayMs:r.lockRetryDelayMs,staleThresholdMs:r.lockStaleThresholdMs,allowStaleRecovery:r.allowStaleRecovery})):await writeTransaction()}import{extname as R}from"path";function detectFormat(t){const e=normalizeFilePath(t);switch(R(e).toLowerCase()){case".json":return"json";case".jsonc":return"jsonc";case".yaml":case".yml":return"yaml";default:throw new Error(`[confedit] Cannot detect a supported configuration format for "${t}". Expected .json, .jsonc, .yaml, or .yml.`)}}async function patchConfigFile(e,r,i={}){if("string"!=typeof e||0===e.length)throw new TypeError("[confedit] filePath must be a non-empty string.");if(o(r),0===r.length)return;const c=normalizeFilePath(e),l=i.format??detectFormat(c);t(l),function(t){if(void 0!==t.lockTimeoutMs&&(!Number.isFinite(t.lockTimeoutMs)||t.lockTimeoutMs<0))throw new TypeError("[confedit] lockTimeoutMs must be a non-negative finite number.");if(void 0!==t.lockRetryDelayMs&&(!Number.isFinite(t.lockRetryDelayMs)||t.lockRetryDelayMs<=0))throw new TypeError("[confedit] lockRetryDelayMs must be a positive finite number.");if(void 0!==t.lockStaleThresholdMs&&(!Number.isFinite(t.lockStaleThresholdMs)||t.lockStaleThresholdMs<=0))throw new TypeError("[confedit] lockStaleThresholdMs must be a positive finite number.")}(i);const u=i.strict??!0,patchTransaction=async()=>{const t=await readConfigFile(c),o=s(t,r,l,{strict:u});if(o!==t)try{await atomicWrite(c,o)}catch(t){throw n(`[confedit] Failed to write "${e}": ${a(t)}`,t)}};i.lock??!0?await withFileLock(c,patchTransaction,{timeoutMs:i.lockTimeoutMs,retryDelayMs:i.lockRetryDelayMs,staleThresholdMs:i.lockStaleThresholdMs,allowStaleRecovery:i.allowStaleRecovery}):await patchTransaction()}async function setConfigValue(t,e,o,r={}){await patchConfigFile(t,[{op:"add",path:[...e],value:o}],r)}async function deleteConfigValue(t,e,o={}){await patchConfigFile(t,[{op:"remove",path:[...e]}],o)}import{open as S,realpath as L,stat as C}from"fs/promises";import{isAbsolute as _,relative as V,resolve as U,sep as B}from"path";import{parse as j}from"yaml";var z,K=class extends Error{constructor(t,e,o){super(e),this.name="OpenApiValidationError",this.code=t,this.cause=o}},W={inputKind:"content",timeoutMs:15e3,maxInputBytes:5242880,maxDocumentNodes:1e5,maxDocumentDepth:100,maxValidationErrors:50,maxErrorMessageLength:1e3};async function validateOpenAPISpec(t,e={}){!function(t,e){if("string"!=typeof t||0===t.length)throw new TypeError(`[confedit] ${e} must be a non-empty string.`)}(t,"input");const o=function(t){const e={inputKind:t.inputKind??W.inputKind,baseFilePath:t.baseFilePath,allowedRootDirectory:t.allowedRootDirectory,timeoutMs:t.timeoutMs??W.timeoutMs,maxInputBytes:t.maxInputBytes??W.maxInputBytes,maxDocumentNodes:t.maxDocumentNodes??W.maxDocumentNodes,maxDocumentDepth:t.maxDocumentDepth??W.maxDocumentDepth,maxValidationErrors:t.maxValidationErrors??W.maxValidationErrors,maxErrorMessageLength:t.maxErrorMessageLength??W.maxErrorMessageLength,signal:t.signal};if("content"!==e.inputKind&&"file"!==e.inputKind)throw new K("INVALID_OPTION",`inputKind must be "content" or "file", got: ${String(e.inputKind)}.`);return assertPositiveFiniteNumber(e.timeoutMs,"timeoutMs"),assertPositiveFiniteNumber(e.maxInputBytes,"maxInputBytes"),assertPositiveFiniteNumber(e.maxDocumentNodes,"maxDocumentNodes"),assertPositiveFiniteNumber(e.maxDocumentDepth,"maxDocumentDepth"),assertPositiveFiniteNumber(e.maxValidationErrors,"maxValidationErrors"),assertPositiveFiniteNumber(e.maxErrorMessageLength,"maxErrorMessageLength"),e}(e),r=function(t){const e=new AbortController;if(t){if(!t.aborted){const onAbort=()=>e.abort();return t.addEventListener("abort",onAbort,{once:!0}),{controller:e,dispose:()=>t.removeEventListener("abort",onAbort)}}e.abort()}return{controller:e,dispose:()=>{}}}(o.signal),n={options:o,controller:r.controller,deadline:Date.now()+o.timeoutMs};try{return await runWithDeadline(n,async()=>{if("file"===o.inputKind){const e=await async function(t,e){const o=normalizeFilePath(t);if(!e.options.allowedRootDirectory)throw new K("FILE_INPUT_FORBIDDEN","File input requires allowedRootDirectory.");return async function(t,e){const o=_(t)?t:U(e,t),r=await L(o),n=V(e,r);if(n.startsWith("..")||""===n||"\\"===B&&/^[a-zA-Z]:/.test(n))throw new K("PATH_OUTSIDE_ROOT",`File path is outside the allowed root directory: ${t}.`);return r}(o,await async function(t){if(t.rootDirectory)return t.rootDirectory;const e=t.options.allowedRootDirectory;if(!e)throw new K("INVALID_OPTION","allowedRootDirectory is required for file operations.");const o=U(e),r=await L(o);if(!(await C(r)).isDirectory())throw new K("INVALID_OPTION",`allowedRootDirectory is not a directory: ${e}.`);return t.rootDirectory=r,r}(e))}(t,n),r=await async function(t,e,o,r){throwIfCancelled(o);const n=await S(t,"r");try{const o=await n.stat();if(o.size>e)throw new K(r,`File exceeds maximum allowed size of ${e} bytes: ${t}.`);const i=Buffer.alloc(o.size);return await n.read(i,0,o.size,0),i.toString("utf8")}finally{await n.close()}}(e,o.maxInputBytes,n,"INPUT_FILE_TOO_LARGE");return validateRawContent(r,{...n,options:{...o,baseFilePath:e}})}return assertByteLength(t,o.maxInputBytes,"INPUT_TOO_LARGE"),validateRawContent(t,n)})}catch(t){throw function(t){if(t instanceof K)return t;return new K("UNKNOWN_ERROR",`OpenAPI validation failed: ${getErrorMessage5(t)}.`,t)}(t)}finally{r.dispose(),n.controller.abort()}}async function validateOpenAPIFile(t,e={}){return validateOpenAPISpec(t,{...e,inputKind:"file",baseFilePath:t})}async function validateRawContent(t,e){throwIfCancelled(e),assertByteLength(t,e.options.maxInputBytes,"INPUT_TOO_LARGE");const o=function(t){try{const e=j(t);if(null===e||"object"!=typeof e||Array.isArray(e))throw new K("INVALID_DOCUMENT_SHAPE","OpenAPI document must be a JSON object.");return e}catch(t){if(t instanceof K)throw t;throw new K("PARSE_ERROR",`Failed to parse OpenAPI document: ${getErrorMessage5(t)}.`,t)}}(t);!function(t,e){let o=0;const r=[{value:t,depth:0}];for(;r.length>0;){const{value:t,depth:n}=r.pop();if(n>e.maxDocumentDepth)throw new K("DOCUMENT_TOO_DEEP",`Document exceeds maximum nesting depth of ${e.maxDocumentDepth}.`);if(o++,o>e.maxDocumentNodes)throw new K("DOCUMENT_TOO_LARGE",`Document exceeds maximum node count of ${e.maxDocumentNodes}.`);if(Array.isArray(t))for(const e of t)r.push({value:e,depth:n+1});else if(null!==t&&"object"==typeof t)for(const e of Object.values(t))r.push({value:e,depth:n+1})}}(o,e.options),function(t){const e=t.openapi??t.swagger;if("string"!=typeof e||0===e.length)throw new K("UNSUPPORTED_VERSION","Document must declare an openapi or swagger version.");const o=Number.parseInt(e.split(".")[0]??"",10);if(!Number.isFinite(o)||2!==o&&3!==o)throw new K("UNSUPPORTED_VERSION",`Unsupported OpenAPI/Swagger version: ${e}. Supported: 2.x, 3.x.`)}(o);const r=await runWithDeadline(e,()=>async function(){return z??=import("@powerduck/openapi-parser").then(({validate:t})=>t),z}()),n=await runWithDeadline(e,()=>r(o,{throwOnError:!1}));if(!n.valid)throw new K("SPEC_VALIDATION_FAILED",`OpenAPI validation failed: ${function(t,e,o){const r=t.slice(0,e).map(t=>{const e=t.instancePath??"",r=t.message??"Unknown error",n=e?`${e}: ${r}`:r;return n.length>o?`${n.slice(0,o)}...`:n});t.length>e&&r.push(`... and ${t.length-e} more errors`);return r.join("; ")}(n.errors??[],e.options.maxValidationErrors,e.options.maxErrorMessageLength)}`);return n.specification}function assertPositiveFiniteNumber(t,e){if(!Number.isFinite(t)||t<=0)throw new K("INVALID_OPTION",`${e} must be a positive finite number, got: ${String(t)}.`)}async function runWithDeadline(t,e){throwIfCancelled(t);const o=await Promise.race([e(),createDeadlinePromise(t)]);return throwIfCancelled(t),o}function createDeadlinePromise(t){return new Promise((e,o)=>{const r=t.deadline-Date.now(),n=Math.max(0,Math.min(r,2147483647)),i=setTimeout(()=>{o(new K("OPERATION_TIMEOUT",`OpenAPI validation operation timed out after ${t.options.timeoutMs}ms.`))},n);t.controller.signal.addEventListener("abort",()=>{clearTimeout(i),o(new K("OPERATION_ABORTED","OpenAPI validation operation was aborted."))},{once:!0})})}function throwIfCancelled(t){if(t.controller.signal.aborted)throw new K("OPERATION_ABORTED","OpenAPI validation operation was aborted.");if(Date.now()>t.deadline)throw new K("OPERATION_TIMEOUT",`OpenAPI validation operation timed out after ${t.options.timeoutMs}ms.`)}function assertByteLength(t,e,o){const r=Buffer.byteLength(t,"utf8");if(r>e)throw new K(o,`Input exceeds maximum allowed size of ${e} bytes (actual: ${r} bytes).`)}function getErrorMessage5(t){return t instanceof Error?t.message:String(t)}export{K as OpenApiValidationError,t as assertConfigFormat,e as assertNonEmptyString,o as assertPatchOperations,r as assertPatchPath,n as createError,deleteConfigValue,i as deleteContentValue,detectFormat,a as getErrorMessage,normalizeFilePath,patchConfigFile,s as patchContent,readConfigFile,releaseAllLocalLocks,setConfigValue,c as setContentValue,validateOpenAPIFile,validateOpenAPISpec,withFileLock,writeConfigFile};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@powerduck/conf-patch",
+  "version": "0.3.1",
+  "description": "Two-layer configuration editor: pure core for patching JSON/JSONC/YAML strings (browser-safe), plus file layer with atomic writes and locking for Node.js/Electron. RFC 6902 JSON Patch, comment and formatting preservation, OpenAPI validation.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && tsup",
+    "typecheck": "tsc --noEmit",
+    "demo": "ts-node demo/demo.ts",
+    "demo:openapi": "ts-node demo/openapi-demo.ts",
+    "reset-fixtures": "ts-node demo/reset-fixtures.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@powerduck/openapi-parser": "^0.3.3",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "openapi-types": "^12.1.3",
+    "terser": "^5.51.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "yaml",
+    "json",
+    "jsonc",
+    "config",
+    "rfc6902",
+    "config-editor",
+    "comment-preserve",
+    "atomic-write",
+    "electron"
+  ],
+  "author": "PowerDuck",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PowerDuckie/conf-patch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PowerDuckie/conf-patch/issues"
+  },
+  "homepage": "https://github.com/PowerDuckie/conf-patch#readme"
+}