@apicircle/core 1.0.1 → 1.0.3

package/LICENSE

@@ -1,110 +1,110 @@
-API Circle Studio License
-Custom Source-Available License, v1.0
-
-Copyright (c) 2026 Deva Prakash ("Licensor")
-
-The source code in this repository ("the Software") is made available for
-the purposes of transparency, security review, contribution, and personal
-evaluation. This is NOT an open-source license as defined by the Open
-Source Initiative.
-
-0. Definitions
-
-   "Commercial Use" means any use of the Software that is intended for
-   or directed toward commercial advantage or monetary compensation,
-   whether direct or indirect, including without limitation:
-
-   (a) using the Software to build, test, develop, deploy, or operate
-       any product, service, application, or system that is sold,
-       licensed, hosted, distributed, or otherwise made available to
-       any third party for a fee or other consideration;
-   (b) using the Software in the course of paid employment, paid
-       consulting, paid contracting, freelance work, or any other
-       revenue-generating activity, regardless of whether the Software
-       itself is sold or transferred;
-   (c) using the Software internally within a for-profit organization
-       beyond the Evaluation Period defined below;
-   (d) integrating the Software, or any portion of it, into any tool,
-       pipeline, automation, or workflow that supports the commercial
-       operations of any business;
-   (e) using the Software to provide a hosted, managed, or embedded
-       service of any kind to a third party, whether free or paid.
-
-   "Non-Commercial Use" means any use that is not Commercial Use,
-   including personal hobby projects, individual learning, academic
-   research, classroom instruction, and good-faith contribution to
-   this repository.
-
-   "Evaluation Period" means a single, continuous period of up to
-   thirty (30) days during which a for-profit organization may
-   internally evaluate the Software at no charge. After the Evaluation
-   Period expires, any further use of the Software by that organization
-   constitutes Commercial Use and requires a separate commercial
-   license from the Licensor.
-
-1. Permitted Use
-
-   You may, without charge:
-
-   (a) view, read, and study the source code of the Software;
-   (b) run the Software, in source or compiled form, for your own
-       Non-Commercial Use, or for Commercial Use solely within the
-       Evaluation Period;
-   (c) submit improvements to the Software back to this repository via
-       pull request, subject to Section 3 (Contributions).
-
-2. Prohibited Use
-
-   Without prior written permission from the Licensor, you may NOT:
-
-   (a) make any Commercial Use of the Software, in whole or in part,
-       except during the Evaluation Period as defined in Section 0;
-   (b) redistribute the Software, in source or compiled form, whether
-       modified or unmodified, to any third party;
-   (c) sublicense, sell, rent, lease, or otherwise transfer the
-       Software or any rights granted herein;
-   (d) remove, obscure, or alter any copyright, trademark, attribution,
-       or license notice contained in the Software;
-   (e) use the names "API Circle", "API Circle Studio", or any related
-       logos or trademarks, except as required for accurate attribution.
-
-3. Contributions
-
-   By submitting any contribution (including but not limited to code,
-   documentation, or assets) to this repository, you grant the Licensor
-   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
-   license to use, modify, distribute, and relicense your contribution
-   under any terms, including the terms of this license or any future
-   version thereof.
-
-4. No Trademark License
-
-   This license does not grant permission to use the trade names,
-   trademarks, service marks, or product names of the Licensor, except
-   as required for reasonable and customary use in describing the
-   origin of the Software.
-
-5. Termination
-
-   The rights granted in Section 1 terminate automatically if you
-   breach any term of this license. Upon termination, you must cease
-   all use of the Software and destroy all copies in your possession.
-
-6. Disclaimer of Warranty
-
-   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, TITLE, AND
-   NON-INFRINGEMENT.
-
-7. Limitation of Liability
-
-   IN NO EVENT SHALL THE LICENSOR 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.
-
-8. Commercial Licensing
-
-   For commercial licensing, redistribution, or any use not permitted
-   under Section 1, contact: apicircle365@gmail.com
+API Circle Studio License
+Custom Source-Available License, v1.0
+
+Copyright (c) 2026 Deva Prakash ("Licensor")
+
+The source code in this repository ("the Software") is made available for
+the purposes of transparency, security review, contribution, and personal
+evaluation. This is NOT an open-source license as defined by the Open
+Source Initiative.
+
+0. Definitions
+
+   "Commercial Use" means any use of the Software that is intended for
+   or directed toward commercial advantage or monetary compensation,
+   whether direct or indirect, including without limitation:
+
+   (a) using the Software to build, test, develop, deploy, or operate
+       any product, service, application, or system that is sold,
+       licensed, hosted, distributed, or otherwise made available to
+       any third party for a fee or other consideration;
+   (b) using the Software in the course of paid employment, paid
+       consulting, paid contracting, freelance work, or any other
+       revenue-generating activity, regardless of whether the Software
+       itself is sold or transferred;
+   (c) using the Software internally within a for-profit organization
+       beyond the Evaluation Period defined below;
+   (d) integrating the Software, or any portion of it, into any tool,
+       pipeline, automation, or workflow that supports the commercial
+       operations of any business;
+   (e) using the Software to provide a hosted, managed, or embedded
+       service of any kind to a third party, whether free or paid.
+
+   "Non-Commercial Use" means any use that is not Commercial Use,
+   including personal hobby projects, individual learning, academic
+   research, classroom instruction, and good-faith contribution to
+   this repository.
+
+   "Evaluation Period" means a single, continuous period of up to
+   thirty (30) days during which a for-profit organization may
+   internally evaluate the Software at no charge. After the Evaluation
+   Period expires, any further use of the Software by that organization
+   constitutes Commercial Use and requires a separate commercial
+   license from the Licensor.
+
+1. Permitted Use
+
+   You may, without charge:
+
+   (a) view, read, and study the source code of the Software;
+   (b) run the Software, in source or compiled form, for your own
+       Non-Commercial Use, or for Commercial Use solely within the
+       Evaluation Period;
+   (c) submit improvements to the Software back to this repository via
+       pull request, subject to Section 3 (Contributions).
+
+2. Prohibited Use
+
+   Without prior written permission from the Licensor, you may NOT:
+
+   (a) make any Commercial Use of the Software, in whole or in part,
+       except during the Evaluation Period as defined in Section 0;
+   (b) redistribute the Software, in source or compiled form, whether
+       modified or unmodified, to any third party;
+   (c) sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any rights granted herein;
+   (d) remove, obscure, or alter any copyright, trademark, attribution,
+       or license notice contained in the Software;
+   (e) use the names "API Circle", "API Circle Studio", or any related
+       logos or trademarks, except as required for accurate attribution.
+
+3. Contributions
+
+   By submitting any contribution (including but not limited to code,
+   documentation, or assets) to this repository, you grant the Licensor
+   a perpetual, worldwide, irrevocable, royalty-free, sublicensable
+   license to use, modify, distribute, and relicense your contribution
+   under any terms, including the terms of this license or any future
+   version thereof.
+
+4. No Trademark License
+
+   This license does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except
+   as required for reasonable and customary use in describing the
+   origin of the Software.
+
+5. Termination
+
+   The rights granted in Section 1 terminate automatically if you
+   breach any term of this license. Upon termination, you must cease
+   all use of the Software and destroy all copies in your possession.
+
+6. Disclaimer of Warranty
+
+   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, TITLE, AND
+   NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+   IN NO EVENT SHALL THE LICENSOR 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.
+
+8. Commercial Licensing
+
+   For commercial licensing, redistribution, or any use not permitted
+   under Section 1, contact: apicircle365@gmail.com

package/README.md

@@ -4,31 +4,200 @@
 
 <h1 align="center">@apicircle/core</h1>
 
-The engine behind [API Circle Studio](https://github.com/apicircle/studio) — request execution, environment resolution, auth signing, assertions, spec imports, and the `applyMutation` workspace mutation API.
+<p align="center">
+  <strong>An embeddable API engine — execute requests, sign auth, import specs, and mutate workspaces from any JavaScript runtime.</strong><br />
+  The same engine that powers the API Circle Studio desktop app, web app, CLI, and MCP server.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@apicircle/core"><img src="https://img.shields.io/npm/v/@apicircle/core?color=cb3837&logo=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/auth%20schemes-17-blueviolet" alt="17 auth schemes" />
+  <img src="https://img.shields.io/badge/imports-OpenAPI%20%C2%B7%20Postman%20%C2%B7%20Insomnia%20%C2%B7%20cURL-blue" alt="Importers" />
+  <img src="https://img.shields.io/badge/runtimes-Node%20%C2%B7%20Bun%20%C2%B7%20Browser-success" alt="Runtimes" />
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-brightgreen" alt="Node ≥ 20" />
+</p>
+
+---
+
+## What it is
+
+`@apicircle/core` is the headless engine behind [API Circle Studio](https://github.com/apicircle/studio).
+It does **everything an API client needs to do** — except draw a UI:
+
+- Builds and executes HTTP requests with redirect, retry, and timeout handling.
+- Signs **17 different auth schemes** end-to-end, including the full OAuth2 grant set.
+- Imports **OpenAPI 3.x, Swagger 2.0, Postman v2/v2.1, Insomnia v4, and cURL** into a typed workspace.
+- Mutates workspace state through a single, audited choke point (`applyMutation`).
+- Runs saved execution plans headlessly — perfect for CI / regression gates.
+- Reads and writes workspace JSON to disk with advisory locking, in either a single-folder or multi-workspace registry layout.
+
+If you've ever wanted to embed "the Postman engine" inside a Node script,
+a CI runner, an internal portal, or your own product — this is that engine,
+typed and treeshakable.
 
 ## Install
 
 ```bash
-npm install @apicircle/core
+npm install @apicircle/core @apicircle/shared
+# pnpm add @apicircle/core @apicircle/shared
 ```
 
-## What's inside
+Dual ESM + CJS, full `.d.ts`, no native deps. Browser-safe — all crypto and
+signing primitives run on WebCrypto.
 
-- **Request execution** — `executeRequest`, request building, redirect and retry handling.
-- **Auth signing** — all 17 `RequestAuth` schemes: Bearer, Basic, API key, custom header, the full OAuth2 grant set, AWS SigV4, Digest, NTLM, Hawk, and JWT.
-- **`applyMutation(state, patch)`** — the single mutation choke point for every workspace write, over the `WorkspacePatch` discriminated union.
-- **Imports** — cURL, OpenAPI / Swagger, Postman, and Insomnia parsers.
-- **Assertions and execution plans** — `runPlan` executes a saved plan headlessly.
-- **Git serialization** — stable JSON serialize / three-way merge for clean workspace diffs.
+## What you can do with it
+
+### Execute any request, with real auth
+
+```ts
+import { executeRequest } from '@apicircle/core';
+
+const result = await executeRequest({
+  method: 'POST',
+  url: 'https://api.example.com/charges',
+  headers: [{ key: 'X-Idempotency-Key', value: 'k-001' }],
+  body: { kind: 'json', json: { amount: 4200, currency: 'usd' } },
+  auth: {
+    type: 'oauth2',
+    grant: 'client_credentials',
+    clientId: 'cid',
+    clientSecret: 'csec',
+    tokenUrl: 'https://auth.example.com/token',
+    scope: 'charges:write',
+  },
+});
+
+console.log(result.response.status, result.response.bodyText);
+```
+
+Behind the scenes the engine acquires a token, caches it for its TTL,
+refreshes it transparently when it expires, and signs the request. Every
+other auth scheme — Bearer, Basic, API key, custom header, AWS SigV4, Digest
+(with `stale=true` nonce rotation), NTLM (with the full 3-message handshake +
+MIC), Hawk, JWT — works the same way: declarative config in, signed request out.
+
+### The 17 auth schemes, in one place
+
+| Family      | Schemes                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------ |
+| Token       | Bearer, API key, custom header                                                                               |
+| Credentials | Basic, Digest (MD5/SHA-256/SHA-512-256), NTLM v2, Hawk                                                       |
+| AWS         | SigV4 (header & query)                                                                                       |
+| JWT         | HS / RS / ES / PS family, custom claims                                                                      |
+| OAuth2      | Client Credentials, Authorization Code (+ PKCE), Password, Implicit, Device Code, Refresh, `private_key_jwt` |
+| None        | …because sometimes the API just lets you in                                                                  |
+
+Every implementation is verified against the original RFCs (1320, 1321, 2202,
+2617, 7616, 7636, [MS-NLMP]) plus NIST CAVS vectors and Mozilla's Hawk
+fixtures. See [`docs/auth.md`](https://github.com/apicircle/studio/blob/main/docs/auth.md)
+for the full matrix.
+
+### Import a spec, get a typed collection
+
+```ts
+import { importOpenApi, importPostman, importInsomnia, importCurl } from '@apicircle/core';
+
+const { requests, folders, warnings } = await importOpenApi(rawYamlOrJson, {
+  format: 'yaml',
+});
+```
+
+All four importers return the same typed shape, ready to merge into a
+workspace with `applyMutation`.
+
+### Run a saved plan in CI
+
+```ts
+import { runPlan, loadFromFile } from '@apicircle/core/workspace/file-backed';
+
+const { synced, local } = await loadFromFile('./workspace');
+const planId = synced.plans.find((p) => p.name === 'Smoke Tests')!.id;
+
+const result = await runPlan({ synced, local }, planId, { bail: true });
+process.exit(result.passed ? 0 : 1);
+```
+
+Plans chain requests, evaluate assertions, and pass extracted variables
+forward — exit code 0 on green, non-zero on red. Drop it straight into GitHub
+Actions, GitLab CI, or any pipeline.
+
+### Mutate workspace state — one function, every entity
+
+```ts
+import { applyMutation, generateId } from '@apicircle/core';
+
+const next = applyMutation(state, {
+  kind: 'request.create',
+  id: generateId(),
+  name: 'List Users',
+  parentFolderId: null,
+  method: 'GET',
+  url: 'https://api.example.com/users',
+});
+```
+
+`WorkspacePatch` is a discriminated union over `request.* | folder.* |
+environment.* | assertion.* | mock.* | plan.*`. Adding a new entity in your
+own UI? One union variant + one switch case. The CLI, MCP server, and desktop
+app all flow through this single function — it's the audit log seam.
 
 ## Entry points
 
 ```ts
+// Engine API
 import { executeRequest, applyMutation, runPlan } from '@apicircle/core';
+
+// Disk-backed single-workspace helpers (load/save/withWorkspace under an advisory lock)
 import { loadFromFile, saveToFile, withWorkspace } from '@apicircle/core/workspace/file-backed';
+
+// Multi-workspace registry (registry.json + per-id subdirectories)
+import {
+  loadRegistry,
+  saveRegistry,
+  loadWorkspaceById,
+  saveWorkspaceById,
+  registerWorkspace,
+  setActiveWorkspace,
+  deleteWorkspaceById,
+  findWorkspaceEntry,
+  migrateLegacyWorkspace,
+  workspaceDirFor,
+  type WorkspaceRegistry,
+} from '@apicircle/core/workspace/registry';
+```
+
+- **`/workspace/file-backed`** — one workspace, one folder. `proper-lockfile`
+  advisory locking, so concurrent CLI runs don't corrupt each other.
+- **`/workspace/registry`** — many workspaces, one root. `registry.json` at
+  the top, per-id subdirectories underneath. The desktop app, CLI, and MCP
+  server all read this same shape, so an edit in one is visible to the others
+  on the next read.
+
+## Use cases
+
+- Build an **internal API explorer** for your engineering team.
+- Run **regression smoke tests** against staging in CI, with real OAuth2.
+- Generate a **runtime mock** from an OpenAPI spec on the fly.
+- Embed an **AI-powered request authoring** flow in your own product.
+- Migrate a Postman library into a typed, Git-trackable workspace.
+- Lint or validate workspaces in a pre-commit hook.
+
+## Where it fits
+
+```
+@apicircle/shared              (types + IDs + crypto + MCP catalog)
+└── @apicircle/core            ◀── you are here
+    ├── @apicircle/mcp-server  (wraps core as MCP tools)
+    ├── @apicircle/cli         (wraps core as a CLI binary)
+    └── @apicircle/mock-server-core (sister package — mock-server engine)
 ```
 
-`@apicircle/core/workspace/file-backed` provides disk-backed workspace helpers with `proper-lockfile` advisory locking — used by `@apicircle/cli` and the headless `@apicircle/mcp-server`.
+## Stability & test coverage
+
+- **1,911 unit + integration tests** in the OAuth2 / signing / executor suites
+  alone (mock IdP exercises every grant, every refresh path, every CSRF guard).
+- Every auth primitive is **CAVS-verified** against the original spec vectors.
+- The engine is built ESM-first and ships dual CJS bundles for legacy consumers.
 
 ## License
 

package/dist/chunk-SGI6KGQ7.js

@@ -0,0 +1,129 @@
+// src/workspace/fileBackedWorkspace.ts
+import { promises as fs } from "fs";
+import * as path from "path";
+import { FONT_SIZE_PERCENT_DEFAULT } from "@apicircle/shared";
+import lockfile from "proper-lockfile";
+var SYNCED_FILE = "workspace.synced.json";
+var LOCAL_FILE = "workspace.local.json";
+async function loadFromFile(dir, options = {}) {
+  const syncedPath = path.join(dir, SYNCED_FILE);
+  const localPath = path.join(dir, LOCAL_FILE);
+  let syncedRaw;
+  try {
+    syncedRaw = await fs.readFile(syncedPath, "utf-8");
+  } catch (err) {
+    if (options.allowMissing && isENOENT(err)) return null;
+    throw err;
+  }
+  const synced = JSON.parse(syncedRaw);
+  let local;
+  try {
+    local = JSON.parse(await fs.readFile(localPath, "utf-8"));
+  } catch (err) {
+    if (!isENOENT(err)) throw err;
+    local = createEmptyLocalForSynced(synced);
+  }
+  return { synced, local };
+}
+async function saveToFile(dir, state, options = {}) {
+  await fs.mkdir(dir, { recursive: true });
+  const syncedPath = path.join(dir, SYNCED_FILE);
+  const localPath = path.join(dir, LOCAL_FILE);
+  await ensureFile(syncedPath);
+  const release = await lockfile.lock(syncedPath, {
+    retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },
+    stale: options.lockTimeoutMs ?? 3e4
+  });
+  try {
+    await writeJsonAtomic(syncedPath, state.synced);
+    await writeJsonAtomic(localPath, state.local);
+  } finally {
+    await release();
+  }
+}
+async function withWorkspace(dir, fn, options = {}) {
+  await fs.mkdir(dir, { recursive: true });
+  const syncedPath = path.join(dir, SYNCED_FILE);
+  const localPath = path.join(dir, LOCAL_FILE);
+  await ensureFile(syncedPath);
+  const release = await lockfile.lock(syncedPath, {
+    retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },
+    stale: options.lockTimeoutMs ?? 3e4
+  });
+  try {
+    const syncedRaw = await fs.readFile(syncedPath, "utf-8");
+    const synced = JSON.parse(syncedRaw);
+    let local;
+    try {
+      local = JSON.parse(await fs.readFile(localPath, "utf-8"));
+    } catch (err) {
+      if (!isENOENT(err)) throw err;
+      local = createEmptyLocalForSynced(synced);
+    }
+    const out = await fn({ synced, local });
+    await writeJsonAtomic(syncedPath, out.next.synced);
+    await writeJsonAtomic(localPath, out.next.local);
+    return out.result;
+  } finally {
+    await release();
+  }
+}
+var WORKSPACE_FILE_MODE = 384;
+async function ensureFile(filePath) {
+  try {
+    await fs.access(filePath);
+  } catch (err) {
+    if (!isENOENT(err)) throw err;
+    await fs.writeFile(filePath, "{}", { encoding: "utf-8", mode: WORKSPACE_FILE_MODE });
+  }
+}
+async function writeJsonAtomic(filePath, value) {
+  const tmp = `${filePath}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(value, null, 2) + "\n", {
+    encoding: "utf-8",
+    mode: WORKSPACE_FILE_MODE
+  });
+  await fs.rename(tmp, filePath);
+}
+function isENOENT(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function createEmptyLocalForSynced(synced) {
+  return {
+    schemaVersion: 1,
+    workspaceId: synced.workspaceId,
+    executionPlans: {},
+    history: { requestRuns: [], planRuns: [] },
+    secretIndex: { entries: {} },
+    sessions: { github: { workspace: null, links: {} } },
+    connectedRepo: null,
+    workingBranch: null,
+    seededWorkspaceSha: null,
+    retiredBranch: null,
+    sync: {
+      lastPulledSnapshot: null,
+      lastPulledSha: null,
+      lastPulledAt: null,
+      dirtyKeys: []
+    },
+    linkedCollections: {},
+    globalContext: {},
+    mockRuntime: { active: {} },
+    ui: {
+      activeRequestId: null,
+      sidebarExpandedSections: [],
+      themeId: "studio-dark",
+      fontId: "system-mono",
+      fontSizePercent: FONT_SIZE_PERCENT_DEFAULT
+    },
+    settings: { validateOnSend: true, monacoConsumesWheel: false },
+    snapshots: { entries: [], maxBytes: 50 * 1024 * 1024 }
+  };
+}
+
+export {
+  loadFromFile,
+  saveToFile,
+  withWorkspace
+};
+//# sourceMappingURL=chunk-SGI6KGQ7.js.map

package/dist/chunk-SGI6KGQ7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace/fileBackedWorkspace.ts"],"sourcesContent":["import { promises as fs } from 'node:fs';\nimport * as path from 'node:path';\nimport { FONT_SIZE_PERCENT_DEFAULT } from '@apicircle/shared';\nimport type { WorkspaceLocal, WorkspaceSynced } from '@apicircle/shared';\nimport lockfile from 'proper-lockfile';\nimport type { WorkspaceState } from './patches';\n\n// =============================================================================\n// fileBackedWorkspace — load/save a `{ synced, local }` pair as two JSON\n// files on disk, with a `proper-lockfile` advisory lock so concurrent CLI /\n// MCP writers can't corrupt the document.\n//\n// Layout (relative to the directory passed in):\n//   workspace.synced.json   ← matches WorkspaceSynced exactly, push-to-git target\n//   workspace.local.json    ← WorkspaceLocal, host-private (CLI/MCP doesn't push)\n//\n// The lock is held on `workspace.synced.json` because that's the file the\n// editor races against. Stale locks are released after 30s.\n// =============================================================================\n\nconst SYNCED_FILE = 'workspace.synced.json';\nconst LOCAL_FILE = 'workspace.local.json';\n\nexport interface LoadFromFileOptions {\n  /** When true, return `null` instead of throwing if the synced file is missing. */\n  allowMissing?: boolean;\n}\n\nexport interface SaveToFileOptions {\n  /** Lock timeout (ms). Defaults to 30000. */\n  lockTimeoutMs?: number;\n}\n\n/**\n * Load both workspace documents from `dir`. The synced file is required;\n * the local file is optional and falls back to a minimal empty shape so a\n * CLI on a fresh machine can still operate (it just won't have history /\n * overrides until the desktop app runs once).\n */\nexport async function loadFromFile(\n  dir: string,\n  options: LoadFromFileOptions = {},\n): Promise<WorkspaceState | null> {\n  const syncedPath = path.join(dir, SYNCED_FILE);\n  const localPath = path.join(dir, LOCAL_FILE);\n\n  let syncedRaw: string;\n  try {\n    syncedRaw = await fs.readFile(syncedPath, 'utf-8');\n  } catch (err) {\n    if (options.allowMissing && isENOENT(err)) return null;\n    throw err;\n  }\n  const synced = JSON.parse(syncedRaw) as WorkspaceSynced;\n\n  let local: WorkspaceLocal;\n  try {\n    local = JSON.parse(await fs.readFile(localPath, 'utf-8')) as WorkspaceLocal;\n  } catch (err) {\n    if (!isENOENT(err)) throw err;\n    local = createEmptyLocalForSynced(synced);\n  }\n\n  return { synced, local };\n}\n\n/**\n * Atomically write both documents back to disk. Acquires an advisory lock\n * on the synced file for the duration of the write so a parallel CLI /\n * MCP / desktop save can't interleave.\n *\n * Both files are written via `<file>.tmp` + rename so a crash mid-write\n * never leaves a partial JSON document on disk.\n */\nexport async function saveToFile(\n  dir: string,\n  state: WorkspaceState,\n  options: SaveToFileOptions = {},\n): Promise<void> {\n  await fs.mkdir(dir, { recursive: true });\n  const syncedPath = path.join(dir, SYNCED_FILE);\n  const localPath = path.join(dir, LOCAL_FILE);\n\n  // proper-lockfile requires the target file to exist. Touch it on first save.\n  await ensureFile(syncedPath);\n\n  const release = await lockfile.lock(syncedPath, {\n    retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },\n    stale: options.lockTimeoutMs ?? 30000,\n  });\n  try {\n    await writeJsonAtomic(syncedPath, state.synced);\n    await writeJsonAtomic(localPath, state.local);\n  } finally {\n    await release();\n  }\n}\n\n/**\n * Run a load → mutate → save cycle under one lock so a single mutation\n * can't be clobbered by a racing reader-then-writer.\n */\nexport async function withWorkspace<T>(\n  dir: string,\n  fn: (state: WorkspaceState) => Promise<{ next: WorkspaceState; result?: T }>,\n  options: SaveToFileOptions = {},\n): Promise<T | undefined> {\n  await fs.mkdir(dir, { recursive: true });\n  const syncedPath = path.join(dir, SYNCED_FILE);\n  const localPath = path.join(dir, LOCAL_FILE);\n  await ensureFile(syncedPath);\n\n  const release = await lockfile.lock(syncedPath, {\n    retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },\n    stale: options.lockTimeoutMs ?? 30000,\n  });\n  try {\n    const syncedRaw = await fs.readFile(syncedPath, 'utf-8');\n    const synced = JSON.parse(syncedRaw) as WorkspaceSynced;\n    let local: WorkspaceLocal;\n    try {\n      local = JSON.parse(await fs.readFile(localPath, 'utf-8')) as WorkspaceLocal;\n    } catch (err) {\n      if (!isENOENT(err)) throw err;\n      local = createEmptyLocalForSynced(synced);\n    }\n    const out = await fn({ synced, local });\n    await writeJsonAtomic(syncedPath, out.next.synced);\n    await writeJsonAtomic(localPath, out.next.local);\n    return out.result;\n  } finally {\n    await release();\n  }\n}\n\n// ---------------------------------------------------------------------------\n// internals\n// ---------------------------------------------------------------------------\n\n// File mode for workspace JSON: owner read/write only. Default `fs.writeFile`\n// uses 0o666 minus umask (typically 0o644 — world-readable). The workspace\n// docs carry the synced state (which after redaction is mostly safe to read\n// but still includes per-workspace metadata) and the local state (which\n// holds the encrypted Secret Vault payload table, session metadata, and the\n// vault entries themselves). On multi-user POSIX hosts (CI runners,\n// classroom VMs, shared dev servers) the default would leak both. 0o600\n// keeps the file owner-only. Windows ignores POSIX modes — the inherited\n// per-user ACL under %USERPROFILE% is what protects it there.\nconst WORKSPACE_FILE_MODE = 0o600;\n\nasync function ensureFile(filePath: string): Promise<void> {\n  try {\n    await fs.access(filePath);\n  } catch (err) {\n    if (!isENOENT(err)) throw err;\n    await fs.writeFile(filePath, '{}', { encoding: 'utf-8', mode: WORKSPACE_FILE_MODE });\n  }\n}\n\nasync function writeJsonAtomic(filePath: string, value: unknown): Promise<void> {\n  const tmp = `${filePath}.tmp`;\n  await fs.writeFile(tmp, JSON.stringify(value, null, 2) + '\\n', {\n    encoding: 'utf-8',\n    mode: WORKSPACE_FILE_MODE,\n  });\n  await fs.rename(tmp, filePath);\n}\n\nfunction isENOENT(err: unknown): boolean {\n  return typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT';\n}\n\nfunction createEmptyLocalForSynced(synced: WorkspaceSynced): WorkspaceLocal {\n  return {\n    schemaVersion: 1,\n    workspaceId: synced.workspaceId,\n    executionPlans: {},\n    history: { requestRuns: [], planRuns: [] },\n    secretIndex: { entries: {} },\n    sessions: { github: { workspace: null, links: {} } },\n    connectedRepo: null,\n    workingBranch: null,\n    seededWorkspaceSha: null,\n    retiredBranch: null,\n    sync: {\n      lastPulledSnapshot: null,\n      lastPulledSha: null,\n      lastPulledAt: null,\n      dirtyKeys: [],\n    },\n    linkedCollections: {},\n    globalContext: {},\n    mockRuntime: { active: {} },\n    ui: {\n      activeRequestId: null,\n      sidebarExpandedSections: [],\n      themeId: 'studio-dark',\n      fontId: 'system-mono',\n      fontSizePercent: FONT_SIZE_PERCENT_DEFAULT,\n    },\n    settings: { validateOnSend: true, monacoConsumesWheel: false },\n    snapshots: { entries: [], maxBytes: 50 * 1024 * 1024 },\n  };\n}\n"],"mappings":"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","names":[]}