@apicircle/core 1.0.0

package/dist/test/mock-idp.js

@@ -0,0 +1,207 @@
+// src/auth/oauth2/__fixtures__/mockIdp.ts
+import { createServer } from "http";
+async function startMockIdp() {
+  let nextAuthorizeError = null;
+  const deviceCodes = /* @__PURE__ */ new Map();
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Accept");
+    if (req.method === "OPTIONS") {
+      res.statusCode = 204;
+      res.end();
+      return;
+    }
+    if (url.pathname === "/authorize") {
+      const redirectUri = url.searchParams.get("redirect_uri") ?? "";
+      const state = url.searchParams.get("state") ?? "";
+      const responseType = url.searchParams.get("response_type") ?? "code";
+      if (!redirectUri) {
+        res.statusCode = 400;
+        res.end("redirect_uri required");
+        return;
+      }
+      if (nextAuthorizeError) {
+        const params = new URLSearchParams({
+          error: nextAuthorizeError.error,
+          state
+        });
+        if (nextAuthorizeError.description) {
+          params.set("error_description", nextAuthorizeError.description);
+        }
+        res.statusCode = 302;
+        res.setHeader("Location", `${redirectUri}?${params.toString()}`);
+        res.end();
+        nextAuthorizeError = null;
+        return;
+      }
+      if (responseType === "token") {
+        res.statusCode = 302;
+        res.setHeader(
+          "Location",
+          `${redirectUri}#access_token=tk-implicit&token_type=Bearer&expires_in=3600&state=${state}`
+        );
+        res.end();
+        return;
+      }
+      res.statusCode = 302;
+      res.setHeader("Location", `${redirectUri}?code=test-code&state=${state}`);
+      res.end();
+      return;
+    }
+    if (url.pathname === "/token" && req.method === "POST") {
+      collectBody(req, (body) => {
+        const params = new URLSearchParams(body);
+        const grant = params.get("grant_type");
+        const clientId = params.get("client_id");
+        if (!clientId) {
+          jsonError(res, 400, "invalid_client", "client_id missing");
+          return;
+        }
+        if (grant === "client_credentials") {
+          jsonOk(res, {
+            access_token: `tk-cc-${clientId}`,
+            token_type: "Bearer",
+            expires_in: 3600,
+            scope: params.get("scope") ?? ""
+          });
+          return;
+        }
+        if (grant === "password") {
+          if (params.get("password") !== "hunter2") {
+            jsonError(res, 400, "invalid_grant", "wrong password");
+            return;
+          }
+          jsonOk(res, {
+            access_token: `tk-ropc-${params.get("username") ?? ""}`,
+            token_type: "Bearer",
+            expires_in: 3600,
+            refresh_token: "rt-ropc"
+          });
+          return;
+        }
+        if (grant === "authorization_code") {
+          if (params.get("code") !== "test-code") {
+            jsonError(res, 400, "invalid_grant", "unknown code");
+            return;
+          }
+          jsonOk(res, {
+            access_token: "tk-authcode",
+            token_type: "Bearer",
+            expires_in: 3600,
+            refresh_token: "rt-authcode",
+            scope: params.get("scope") ?? ""
+          });
+          return;
+        }
+        if (grant === "refresh_token") {
+          if (params.get("refresh_token") === "rt-rotated-once") {
+            jsonError(res, 400, "invalid_grant", "refresh already used");
+            return;
+          }
+          jsonOk(res, {
+            access_token: "tk-refreshed",
+            token_type: "Bearer",
+            expires_in: 3600,
+            // Rotate: hand back a fresh refresh_token.
+            refresh_token: "rt-rotated-once"
+          });
+          return;
+        }
+        if (grant === "urn:ietf:params:oauth:grant-type:device_code") {
+          const code = params.get("device_code") ?? "";
+          const state = deviceCodes.get(code);
+          if (!state) {
+            jsonError(res, 400, "invalid_grant", "unknown device_code");
+            return;
+          }
+          state.pollCount++;
+          if (state.pollCount < state.approvedAfter) {
+            jsonError(res, 400, "authorization_pending");
+            return;
+          }
+          jsonOk(res, {
+            access_token: "tk-device",
+            token_type: "Bearer",
+            expires_in: 3600
+          });
+          return;
+        }
+        jsonError(res, 400, "unsupported_grant_type");
+      });
+      return;
+    }
+    if (url.pathname === "/device_authorize" && req.method === "POST") {
+      const code = `dc-${Date.now()}`;
+      deviceCodes.set(code, { approvedAfter: 2, pollCount: 0 });
+      jsonOk(res, {
+        device_code: code,
+        user_code: "ABCD-EFGH",
+        verification_uri: `http://127.0.0.1:${server.address().port}/device`,
+        interval: 1,
+        expires_in: 600
+      });
+      return;
+    }
+    if (url.pathname === "/protected") {
+      const auth = req.headers["authorization"] ?? "";
+      if (!auth.toLowerCase().startsWith("bearer tk-")) {
+        res.statusCode = 401;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ error: "unauthorized" }));
+        return;
+      }
+      jsonOk(res, { ok: true, sawAuth: auth });
+      return;
+    }
+    if (url.pathname === "/www-auth-bearer") {
+      res.statusCode = 401;
+      res.setHeader(
+        "WWW-Authenticate",
+        'Bearer error="invalid_token", error_description="The access token expired"'
+      );
+      res.end();
+      return;
+    }
+    res.statusCode = 404;
+    res.end("Not Found");
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+  const baseUrl = `http://127.0.0.1:${port}`;
+  return {
+    port,
+    url: (path) => `${baseUrl}${path}`,
+    setNextAuthorizeError: (err) => {
+      nextAuthorizeError = err;
+    },
+    approveDevice: () => {
+      for (const state of deviceCodes.values()) state.approvedAfter = state.pollCount + 1;
+    },
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    })
+  };
+}
+function jsonOk(res, body) {
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(body));
+}
+function jsonError(res, status, error, description) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  const body = { error };
+  if (description) body.error_description = description;
+  res.end(JSON.stringify(body));
+}
+function collectBody(req, cb) {
+  const chunks = [];
+  req.on("data", (c) => chunks.push(c));
+  req.on("end", () => cb(Buffer.concat(chunks).toString("utf8")));
+}
+export {
+  startMockIdp
+};
+//# sourceMappingURL=mock-idp.js.map

package/dist/test/mock-idp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/auth/oauth2/__fixtures__/mockIdp.ts"],"sourcesContent":["/**\n * Programmatic OAuth2 IdP for E2E tests. Implements every grant the\n * studio supports with the simplest possible logic — no real user\n * accounts, no real key material. Tokens are deterministic strings\n * keyed by `client_id` so assertions can match exactly.\n *\n *   POST /token              — token endpoint (every grant_type)\n *   GET  /authorize          — auth-code / implicit redirect\n *   POST /device_authorize   — device flow user-code endpoint\n *   GET  /protected          — resource server, requires Bearer header\n *   POST /protected          — same, lets tests assert on POST too\n *   GET  /www-auth-bearer    — emits WWW-Authenticate Bearer error (no JSON)\n *   POST /digest-protected   — Digest 401-retry endpoint\n *\n * Spin up via `await startMockIdp()` and tear down with the returned\n * `close()`. Port is dynamic to avoid collisions in CI.\n */\n\nimport { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';\nimport { type AddressInfo } from 'node:net';\n\ninterface DeviceState {\n  approvedAfter: number; // poll count threshold\n  pollCount: number;\n}\n\nexport interface MockIdp {\n  port: number;\n  url: (path: string) => string;\n  /** Force the next /authorize redirect to include this error param. */\n  setNextAuthorizeError: (err: { error: string; description?: string } | null) => void;\n  /** Approve the current device flow (subsequent /token polls succeed). */\n  approveDevice: () => void;\n  close: () => Promise<void>;\n}\n\nexport async function startMockIdp(): Promise<MockIdp> {\n  let nextAuthorizeError: { error: string; description?: string } | null = null;\n  const deviceCodes = new Map<string, DeviceState>();\n\n  const server: Server = createServer((req, res) => {\n    const url = new URL(req.url ?? '/', `http://127.0.0.1`);\n\n    // Permissive CORS so the web app's fetch can reach the IdP across\n    // origins (e.g. http://localhost:5174 → http://127.0.0.1:<idp>).\n    // Real IdPs aren't this permissive — but only the test harness\n    // ever talks to this server.\n    res.setHeader('Access-Control-Allow-Origin', '*');\n    res.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS');\n    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Accept');\n    if (req.method === 'OPTIONS') {\n      res.statusCode = 204;\n      res.end();\n      return;\n    }\n\n    if (url.pathname === '/authorize') {\n      const redirectUri = url.searchParams.get('redirect_uri') ?? '';\n      const state = url.searchParams.get('state') ?? '';\n      const responseType = url.searchParams.get('response_type') ?? 'code';\n      if (!redirectUri) {\n        res.statusCode = 400;\n        res.end('redirect_uri required');\n        return;\n      }\n      if (nextAuthorizeError) {\n        const params = new URLSearchParams({\n          error: nextAuthorizeError.error,\n          state,\n        });\n        if (nextAuthorizeError.description) {\n          params.set('error_description', nextAuthorizeError.description);\n        }\n        res.statusCode = 302;\n        res.setHeader('Location', `${redirectUri}?${params.toString()}`);\n        res.end();\n        nextAuthorizeError = null;\n        return;\n      }\n      if (responseType === 'token') {\n        // Implicit: redirect with fragment.\n        res.statusCode = 302;\n        res.setHeader(\n          'Location',\n          `${redirectUri}#access_token=tk-implicit&token_type=Bearer&expires_in=3600&state=${state}`,\n        );\n        res.end();\n        return;\n      }\n      // Default: auth-code redirect.\n      res.statusCode = 302;\n      res.setHeader('Location', `${redirectUri}?code=test-code&state=${state}`);\n      res.end();\n      return;\n    }\n\n    if (url.pathname === '/token' && req.method === 'POST') {\n      collectBody(req, (body) => {\n        const params = new URLSearchParams(body);\n        const grant = params.get('grant_type');\n        const clientId = params.get('client_id');\n        if (!clientId) {\n          jsonError(res, 400, 'invalid_client', 'client_id missing');\n          return;\n        }\n        if (grant === 'client_credentials') {\n          jsonOk(res, {\n            access_token: `tk-cc-${clientId}`,\n            token_type: 'Bearer',\n            expires_in: 3600,\n            scope: params.get('scope') ?? '',\n          });\n          return;\n        }\n        if (grant === 'password') {\n          if (params.get('password') !== 'hunter2') {\n            jsonError(res, 400, 'invalid_grant', 'wrong password');\n            return;\n          }\n          jsonOk(res, {\n            access_token: `tk-ropc-${params.get('username') ?? ''}`,\n            token_type: 'Bearer',\n            expires_in: 3600,\n            refresh_token: 'rt-ropc',\n          });\n          return;\n        }\n        if (grant === 'authorization_code') {\n          if (params.get('code') !== 'test-code') {\n            jsonError(res, 400, 'invalid_grant', 'unknown code');\n            return;\n          }\n          // PKCE clients carry code_verifier — accept any non-empty value.\n          jsonOk(res, {\n            access_token: 'tk-authcode',\n            token_type: 'Bearer',\n            expires_in: 3600,\n            refresh_token: 'rt-authcode',\n            scope: params.get('scope') ?? '',\n          });\n          return;\n        }\n        if (grant === 'refresh_token') {\n          if (params.get('refresh_token') === 'rt-rotated-once') {\n            jsonError(res, 400, 'invalid_grant', 'refresh already used');\n            return;\n          }\n          jsonOk(res, {\n            access_token: 'tk-refreshed',\n            token_type: 'Bearer',\n            expires_in: 3600,\n            // Rotate: hand back a fresh refresh_token.\n            refresh_token: 'rt-rotated-once',\n          });\n          return;\n        }\n        if (grant === 'urn:ietf:params:oauth:grant-type:device_code') {\n          const code = params.get('device_code') ?? '';\n          const state = deviceCodes.get(code);\n          if (!state) {\n            jsonError(res, 400, 'invalid_grant', 'unknown device_code');\n            return;\n          }\n          state.pollCount++;\n          if (state.pollCount < state.approvedAfter) {\n            jsonError(res, 400, 'authorization_pending');\n            return;\n          }\n          jsonOk(res, {\n            access_token: 'tk-device',\n            token_type: 'Bearer',\n            expires_in: 3600,\n          });\n          return;\n        }\n        jsonError(res, 400, 'unsupported_grant_type');\n      });\n      return;\n    }\n\n    if (url.pathname === '/device_authorize' && req.method === 'POST') {\n      const code = `dc-${Date.now()}`;\n      deviceCodes.set(code, { approvedAfter: 2, pollCount: 0 });\n      jsonOk(res, {\n        device_code: code,\n        user_code: 'ABCD-EFGH',\n        verification_uri: `http://127.0.0.1:${(server.address() as AddressInfo).port}/device`,\n        interval: 1,\n        expires_in: 600,\n      });\n      return;\n    }\n\n    if (url.pathname === '/protected') {\n      const auth = req.headers['authorization'] ?? '';\n      if (!auth.toLowerCase().startsWith('bearer tk-')) {\n        res.statusCode = 401;\n        res.setHeader('Content-Type', 'application/json');\n        res.end(JSON.stringify({ error: 'unauthorized' }));\n        return;\n      }\n      jsonOk(res, { ok: true, sawAuth: auth });\n      return;\n    }\n\n    if (url.pathname === '/www-auth-bearer') {\n      res.statusCode = 401;\n      res.setHeader(\n        'WWW-Authenticate',\n        'Bearer error=\"invalid_token\", error_description=\"The access token expired\"',\n      );\n      res.end();\n      return;\n    }\n\n    res.statusCode = 404;\n    res.end('Not Found');\n  });\n\n  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));\n  const port = (server.address() as AddressInfo).port;\n  const baseUrl = `http://127.0.0.1:${port}`;\n\n  return {\n    port,\n    url: (path) => `${baseUrl}${path}`,\n    setNextAuthorizeError: (err) => {\n      nextAuthorizeError = err;\n    },\n    approveDevice: () => {\n      for (const state of deviceCodes.values()) state.approvedAfter = state.pollCount + 1;\n    },\n    close: () =>\n      new Promise<void>((resolve, reject) => {\n        server.close((err) => (err ? reject(err) : resolve()));\n      }),\n  };\n}\n\nfunction jsonOk(res: ServerResponse, body: unknown): void {\n  res.statusCode = 200;\n  res.setHeader('Content-Type', 'application/json');\n  res.end(JSON.stringify(body));\n}\n\nfunction jsonError(res: ServerResponse, status: number, error: string, description?: string): void {\n  res.statusCode = status;\n  res.setHeader('Content-Type', 'application/json');\n  const body: Record<string, string> = { error };\n  if (description) body.error_description = description;\n  res.end(JSON.stringify(body));\n}\n\nfunction collectBody(req: IncomingMessage, cb: (body: string) => void): void {\n  const chunks: Buffer[] = [];\n  req.on('data', (c: Buffer) => chunks.push(c));\n  req.on('end', () => cb(Buffer.concat(chunks).toString('utf8')));\n}\n"],"mappings":";AAkBA,SAAS,oBAA4E;AAkBrF,eAAsB,eAAiC;AACrD,MAAI,qBAAqE;AACzE,QAAM,cAAc,oBAAI,IAAyB;AAEjD,QAAM,SAAiB,aAAa,CAAC,KAAK,QAAQ;AAChD,UAAM,MAAM,IAAI,IAAI,IAAI,OAAO,KAAK,kBAAkB;AAMtD,QAAI,UAAU,+BAA+B,GAAG;AAChD,QAAI,UAAU,gCAAgC,kBAAkB;AAChE,QAAI,UAAU,gCAAgC,qCAAqC;AACnF,QAAI,IAAI,WAAW,WAAW;AAC5B,UAAI,aAAa;AACjB,UAAI,IAAI;AACR;AAAA,IACF;AAEA,QAAI,IAAI,aAAa,cAAc;AACjC,YAAM,cAAc,IAAI,aAAa,IAAI,cAAc,KAAK;AAC5D,YAAM,QAAQ,IAAI,aAAa,IAAI,OAAO,KAAK;AAC/C,YAAM,eAAe,IAAI,aAAa,IAAI,eAAe,KAAK;AAC9D,UAAI,CAAC,aAAa;AAChB,YAAI,aAAa;AACjB,YAAI,IAAI,uBAAuB;AAC/B;AAAA,MACF;AACA,UAAI,oBAAoB;AACtB,cAAM,SAAS,IAAI,gBAAgB;AAAA,UACjC,OAAO,mBAAmB;AAAA,UAC1B;AAAA,QACF,CAAC;AACD,YAAI,mBAAmB,aAAa;AAClC,iBAAO,IAAI,qBAAqB,mBAAmB,WAAW;AAAA,QAChE;AACA,YAAI,aAAa;AACjB,YAAI,UAAU,YAAY,GAAG,WAAW,IAAI,OAAO,SAAS,CAAC,EAAE;AAC/D,YAAI,IAAI;AACR,6BAAqB;AACrB;AAAA,MACF;AACA,UAAI,iBAAiB,SAAS;AAE5B,YAAI,aAAa;AACjB,YAAI;AAAA,UACF;AAAA,UACA,GAAG,WAAW,qEAAqE,KAAK;AAAA,QAC1F;AACA,YAAI,IAAI;AACR;AAAA,MACF;AAEA,UAAI,aAAa;AACjB,UAAI,UAAU,YAAY,GAAG,WAAW,yBAAyB,KAAK,EAAE;AACxE,UAAI,IAAI;AACR;AAAA,IACF;AAEA,QAAI,IAAI,aAAa,YAAY,IAAI,WAAW,QAAQ;AACtD,kBAAY,KAAK,CAAC,SAAS;AACzB,cAAM,SAAS,IAAI,gBAAgB,IAAI;AACvC,cAAM,QAAQ,OAAO,IAAI,YAAY;AACrC,cAAM,WAAW,OAAO,IAAI,WAAW;AACvC,YAAI,CAAC,UAAU;AACb,oBAAU,KAAK,KAAK,kBAAkB,mBAAmB;AACzD;AAAA,QACF;AACA,YAAI,UAAU,sBAAsB;AAClC,iBAAO,KAAK;AAAA,YACV,cAAc,SAAS,QAAQ;AAAA,YAC/B,YAAY;AAAA,YACZ,YAAY;AAAA,YACZ,OAAO,OAAO,IAAI,OAAO,KAAK;AAAA,UAChC,CAAC;AACD;AAAA,QACF;AACA,YAAI,UAAU,YAAY;AACxB,cAAI,OAAO,IAAI,UAAU,MAAM,WAAW;AACxC,sBAAU,KAAK,KAAK,iBAAiB,gBAAgB;AACrD;AAAA,UACF;AACA,iBAAO,KAAK;AAAA,YACV,cAAc,WAAW,OAAO,IAAI,UAAU,KAAK,EAAE;AAAA,YACrD,YAAY;AAAA,YACZ,YAAY;AAAA,YACZ,eAAe;AAAA,UACjB,CAAC;AACD;AAAA,QACF;AACA,YAAI,UAAU,sBAAsB;AAClC,cAAI,OAAO,IAAI,MAAM,MAAM,aAAa;AACtC,sBAAU,KAAK,KAAK,iBAAiB,cAAc;AACnD;AAAA,UACF;AAEA,iBAAO,KAAK;AAAA,YACV,cAAc;AAAA,YACd,YAAY;AAAA,YACZ,YAAY;AAAA,YACZ,eAAe;AAAA,YACf,OAAO,OAAO,IAAI,OAAO,KAAK;AAAA,UAChC,CAAC;AACD;AAAA,QACF;AACA,YAAI,UAAU,iBAAiB;AAC7B,cAAI,OAAO,IAAI,eAAe,MAAM,mBAAmB;AACrD,sBAAU,KAAK,KAAK,iBAAiB,sBAAsB;AAC3D;AAAA,UACF;AACA,iBAAO,KAAK;AAAA,YACV,cAAc;AAAA,YACd,YAAY;AAAA,YACZ,YAAY;AAAA;AAAA,YAEZ,eAAe;AAAA,UACjB,CAAC;AACD;AAAA,QACF;AACA,YAAI,UAAU,gDAAgD;AAC5D,gBAAM,OAAO,OAAO,IAAI,aAAa,KAAK;AAC1C,gBAAM,QAAQ,YAAY,IAAI,IAAI;AAClC,cAAI,CAAC,OAAO;AACV,sBAAU,KAAK,KAAK,iBAAiB,qBAAqB;AAC1D;AAAA,UACF;AACA,gBAAM;AACN,cAAI,MAAM,YAAY,MAAM,eAAe;AACzC,sBAAU,KAAK,KAAK,uBAAuB;AAC3C;AAAA,UACF;AACA,iBAAO,KAAK;AAAA,YACV,cAAc;AAAA,YACd,YAAY;AAAA,YACZ,YAAY;AAAA,UACd,CAAC;AACD;AAAA,QACF;AACA,kBAAU,KAAK,KAAK,wBAAwB;AAAA,MAC9C,CAAC;AACD;AAAA,IACF;AAEA,QAAI,IAAI,aAAa,uBAAuB,IAAI,WAAW,QAAQ;AACjE,YAAM,OAAO,MAAM,KAAK,IAAI,CAAC;AAC7B,kBAAY,IAAI,MAAM,EAAE,eAAe,GAAG,WAAW,EAAE,CAAC;AACxD,aAAO,KAAK;AAAA,QACV,aAAa;AAAA,QACb,WAAW;AAAA,QACX,kBAAkB,oBAAqB,OAAO,QAAQ,EAAkB,IAAI;AAAA,QAC5E,UAAU;AAAA,QACV,YAAY;AAAA,MACd,CAAC;AACD;AAAA,IACF;AAEA,QAAI,IAAI,aAAa,cAAc;AACjC,YAAM,OAAO,IAAI,QAAQ,eAAe,KAAK;AAC7C,UAAI,CAAC,KAAK,YAAY,EAAE,WAAW,YAAY,GAAG;AAChD,YAAI,aAAa;AACjB,YAAI,UAAU,gBAAgB,kBAAkB;AAChD,YAAI,IAAI,KAAK,UAAU,EAAE,OAAO,eAAe,CAAC,CAAC;AACjD;AAAA,MACF;AACA,aAAO,KAAK,EAAE,IAAI,MAAM,SAAS,KAAK,CAAC;AACvC;AAAA,IACF;AAEA,QAAI,IAAI,aAAa,oBAAoB;AACvC,UAAI,aAAa;AACjB,UAAI;AAAA,QACF;AAAA,QACA;AAAA,MACF;AACA,UAAI,IAAI;AACR;AAAA,IACF;AAEA,QAAI,aAAa;AACjB,QAAI,IAAI,WAAW;AAAA,EACrB,CAAC;AAED,QAAM,IAAI,QAAc,CAAC,YAAY,OAAO,OAAO,GAAG,aAAa,OAAO,CAAC;AAC3E,QAAM,OAAQ,OAAO,QAAQ,EAAkB;AAC/C,QAAM,UAAU,oBAAoB,IAAI;AAExC,SAAO;AAAA,IACL;AAAA,IACA,KAAK,CAAC,SAAS,GAAG,OAAO,GAAG,IAAI;AAAA,IAChC,uBAAuB,CAAC,QAAQ;AAC9B,2BAAqB;AAAA,IACvB;AAAA,IACA,eAAe,MAAM;AACnB,iBAAW,SAAS,YAAY,OAAO,EAAG,OAAM,gBAAgB,MAAM,YAAY;AAAA,IACpF;AAAA,IACA,OAAO,MACL,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,aAAO,MAAM,CAAC,QAAS,MAAM,OAAO,GAAG,IAAI,QAAQ,CAAE;AAAA,IACvD,CAAC;AAAA,EACL;AACF;AAEA,SAAS,OAAO,KAAqB,MAAqB;AACxD,MAAI,aAAa;AACjB,MAAI,UAAU,gBAAgB,kBAAkB;AAChD,MAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B;AAEA,SAAS,UAAU,KAAqB,QAAgB,OAAe,aAA4B;AACjG,MAAI,aAAa;AACjB,MAAI,UAAU,gBAAgB,kBAAkB;AAChD,QAAM,OAA+B,EAAE,MAAM;AAC7C,MAAI,YAAa,MAAK,oBAAoB;AAC1C,MAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B;AAEA,SAAS,YAAY,KAAsB,IAAkC;AAC3E,QAAM,SAAmB,CAAC;AAC1B,MAAI,GAAG,QAAQ,CAAC,MAAc,OAAO,KAAK,CAAC,CAAC;AAC5C,MAAI,GAAG,OAAO,MAAM,GAAG,OAAO,OAAO,MAAM,EAAE,SAAS,MAAM,CAAC,CAAC;AAChE;","names":[]}

package/dist/workspace/file-backed.cjs

@@ -0,0 +1,165 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/workspace/fileBackedWorkspace.ts
+var fileBackedWorkspace_exports = {};
+__export(fileBackedWorkspace_exports, {
+  loadFromFile: () => loadFromFile,
+  saveToFile: () => saveToFile,
+  withWorkspace: () => withWorkspace
+});
+module.exports = __toCommonJS(fileBackedWorkspace_exports);
+var import_node_fs = require("fs");
+var path = __toESM(require("path"), 1);
+var import_shared = require("@apicircle/shared");
+var import_proper_lockfile = __toESM(require("proper-lockfile"), 1);
+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 import_node_fs.promises.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 import_node_fs.promises.readFile(localPath, "utf-8"));
+  } catch (err) {
+    if (!isENOENT(err)) throw err;
+    local = createEmptyLocalForSynced(synced);
+  }
+  return { synced, local };
+}
+async function saveToFile(dir, state, options = {}) {
+  await import_node_fs.promises.mkdir(dir, { recursive: true });
+  const syncedPath = path.join(dir, SYNCED_FILE);
+  const localPath = path.join(dir, LOCAL_FILE);
+  await ensureFile(syncedPath);
+  const release = await import_proper_lockfile.default.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 import_node_fs.promises.mkdir(dir, { recursive: true });
+  const syncedPath = path.join(dir, SYNCED_FILE);
+  const localPath = path.join(dir, LOCAL_FILE);
+  await ensureFile(syncedPath);
+  const release = await import_proper_lockfile.default.lock(syncedPath, {
+    retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },
+    stale: options.lockTimeoutMs ?? 3e4
+  });
+  try {
+    const syncedRaw = await import_node_fs.promises.readFile(syncedPath, "utf-8");
+    const synced = JSON.parse(syncedRaw);
+    let local;
+    try {
+      local = JSON.parse(await import_node_fs.promises.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 import_node_fs.promises.access(filePath);
+  } catch (err) {
+    if (!isENOENT(err)) throw err;
+    await import_node_fs.promises.writeFile(filePath, "{}", { encoding: "utf-8", mode: WORKSPACE_FILE_MODE });
+  }
+}
+async function writeJsonAtomic(filePath, value) {
+  const tmp = `${filePath}.tmp`;
+  await import_node_fs.promises.writeFile(tmp, JSON.stringify(value, null, 2) + "\n", {
+    encoding: "utf-8",
+    mode: WORKSPACE_FILE_MODE
+  });
+  await import_node_fs.promises.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: import_shared.FONT_SIZE_PERCENT_DEFAULT
+    },
+    settings: { validateOnSend: true, monacoConsumesWheel: false },
+    snapshots: { entries: [], maxBytes: 50 * 1024 * 1024 }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadFromFile,
+  saveToFile,
+  withWorkspace
+});
+//# sourceMappingURL=file-backed.cjs.map

package/dist/workspace/file-backed.cjs.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":["fs","lockfile"]}

package/dist/workspace/file-backed.d.cts

@@ -0,0 +1,37 @@
+import { W as WorkspaceState } from '../patches-N7mvDpXn.cjs';
+import '@apicircle/shared';
+
+interface LoadFromFileOptions {
+    /** When true, return `null` instead of throwing if the synced file is missing. */
+    allowMissing?: boolean;
+}
+interface SaveToFileOptions {
+    /** Lock timeout (ms). Defaults to 30000. */
+    lockTimeoutMs?: number;
+}
+/**
+ * Load both workspace documents from `dir`. The synced file is required;
+ * the local file is optional and falls back to a minimal empty shape so a
+ * CLI on a fresh machine can still operate (it just won't have history /
+ * overrides until the desktop app runs once).
+ */
+declare function loadFromFile(dir: string, options?: LoadFromFileOptions): Promise<WorkspaceState | null>;
+/**
+ * Atomically write both documents back to disk. Acquires an advisory lock
+ * on the synced file for the duration of the write so a parallel CLI /
+ * MCP / desktop save can't interleave.
+ *
+ * Both files are written via `<file>.tmp` + rename so a crash mid-write
+ * never leaves a partial JSON document on disk.
+ */
+declare function saveToFile(dir: string, state: WorkspaceState, options?: SaveToFileOptions): Promise<void>;
+/**
+ * Run a load → mutate → save cycle under one lock so a single mutation
+ * can't be clobbered by a racing reader-then-writer.
+ */
+declare function withWorkspace<T>(dir: string, fn: (state: WorkspaceState) => Promise<{
+    next: WorkspaceState;
+    result?: T;
+}>, options?: SaveToFileOptions): Promise<T | undefined>;
+
+export { type LoadFromFileOptions, type SaveToFileOptions, loadFromFile, saveToFile, withWorkspace };

package/dist/workspace/file-backed.d.ts

@@ -0,0 +1,37 @@
+import { W as WorkspaceState } from '../patches-N7mvDpXn.js';
+import '@apicircle/shared';
+
+interface LoadFromFileOptions {
+    /** When true, return `null` instead of throwing if the synced file is missing. */
+    allowMissing?: boolean;
+}
+interface SaveToFileOptions {
+    /** Lock timeout (ms). Defaults to 30000. */
+    lockTimeoutMs?: number;
+}
+/**
+ * Load both workspace documents from `dir`. The synced file is required;
+ * the local file is optional and falls back to a minimal empty shape so a
+ * CLI on a fresh machine can still operate (it just won't have history /
+ * overrides until the desktop app runs once).
+ */
+declare function loadFromFile(dir: string, options?: LoadFromFileOptions): Promise<WorkspaceState | null>;
+/**
+ * Atomically write both documents back to disk. Acquires an advisory lock
+ * on the synced file for the duration of the write so a parallel CLI /
+ * MCP / desktop save can't interleave.
+ *
+ * Both files are written via `<file>.tmp` + rename so a crash mid-write
+ * never leaves a partial JSON document on disk.
+ */
+declare function saveToFile(dir: string, state: WorkspaceState, options?: SaveToFileOptions): Promise<void>;
+/**
+ * Run a load → mutate → save cycle under one lock so a single mutation
+ * can't be clobbered by a racing reader-then-writer.
+ */
+declare function withWorkspace<T>(dir: string, fn: (state: WorkspaceState) => Promise<{
+    next: WorkspaceState;
+    result?: T;
+}>, options?: SaveToFileOptions): Promise<T | undefined>;
+
+export { type LoadFromFileOptions, type SaveToFileOptions, loadFromFile, saveToFile, withWorkspace };

package/dist/workspace/file-backed.js

@@ -0,0 +1,128 @@
+// 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=file-backed.js.map

package/dist/workspace/file-backed.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":[]}