@immediately-run/sdk 0.16.0 → 0.18.0

package/dist/debug.js

@@ -0,0 +1,141 @@
+import { createPushChannel } from "./pushChannel";
+import { sendMessage, addListener } from "./sandboxUtils";
+const enabledChannel = createPushChannel({
+  pushType: "debug-enabled",
+  requestType: "request-debug-enabled",
+  initial: false,
+  parse: (msg) => typeof msg.enabled === "boolean" ? msg.enabled : void 0
+});
+const isDebugEnabled = () => enabledChannel.get();
+const useDebugEnabled = () => enabledChannel.use();
+const MAX_DATA_BYTES = 16 * 1024;
+function safeData(data) {
+  if (data === void 0) return void 0;
+  try {
+    const json = JSON.stringify(data);
+    if (json === void 0) return "[unserializable]";
+    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;
+    return JSON.parse(json);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function log(level, message, data) {
+  if (!enabledChannel.get()) return;
+  try {
+    sendMessage("debug-log", { level, message: String(message), data: safeData(data) });
+  } catch {
+  }
+}
+const ATTR_ALLOW = /* @__PURE__ */ new Set(["role", "aria-hidden", "data-theme", "data-active", "href", "type", "hidden"]);
+const MAX_NODES = 2e3;
+const MAX_DEPTH = 25;
+const MAX_TEXT = 200;
+function round(n) {
+  return Math.round(n);
+}
+function snapshotDom(params) {
+  if (typeof document === "undefined") return null;
+  const root = params.selector ? document.querySelector(params.selector) : document.body;
+  if (!root) return null;
+  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);
+  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);
+  let budget = maxNodes;
+  const walk = (el, depth) => {
+    budget--;
+    const r = el.getBoundingClientRect();
+    const classes = el.classList.length ? [...el.classList] : void 0;
+    const attrs = {};
+    for (const name of el.getAttributeNames()) {
+      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? "";
+    }
+    const ownText = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => (n.textContent ?? "").trim()).join(" ").trim();
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      ...el.id ? { id: el.id } : {},
+      ...classes ? { classes } : {},
+      ...Object.keys(attrs).length ? { attrs } : {},
+      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },
+      ...ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}
+    };
+    if (depth < maxDepth && el.children.length && budget > 0) {
+      const children = [];
+      for (const child of el.children) {
+        if (budget <= 0) {
+          node.truncated = true;
+          break;
+        }
+        children.push(walk(child, depth + 1));
+      }
+      if (children.length) node.children = children;
+    } else if (el.children.length) {
+      node.truncated = true;
+    }
+    return node;
+  };
+  return walk(root, 0);
+}
+function computedStyle(params) {
+  if (typeof document === "undefined") return null;
+  const el = document.querySelector(params.selector);
+  if (!el) return null;
+  const cs = getComputedStyle(el);
+  const out = {};
+  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p]?.toString?.() || "";
+  return out;
+}
+function rects(params) {
+  if (typeof document === "undefined") return [];
+  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {
+    const r = el.getBoundingClientRect();
+    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };
+  });
+}
+let responderStarted = false;
+function startResponder() {
+  if (responderStarted || typeof window === "undefined") return;
+  responderStarted = true;
+  addListener("debug-query", (msg) => {
+    if (!enabledChannel.get()) return;
+    const id = msg.id;
+    const method = msg.method;
+    const params = msg.params ?? {};
+    let ok = true;
+    let result = null;
+    let error;
+    try {
+      switch (method) {
+        case "snapshotDom":
+          result = snapshotDom(params);
+          break;
+        case "computedStyle":
+          result = computedStyle(params);
+          break;
+        case "rect":
+          result = rects(params);
+          break;
+        default:
+          ok = false;
+          error = `unknown debug method: ${String(method)}`;
+      }
+    } catch (e) {
+      ok = false;
+      error = e instanceof Error ? e.message : String(e);
+    }
+    try {
+      sendMessage("debug-query-result", { id, ok, result, error });
+    } catch {
+    }
+  });
+}
+enabledChannel.onChange((enabled) => {
+  if (enabled) startResponder();
+});
+const debug = { log, isEnabled: isDebugEnabled };
+export {
+  debug,
+  isDebugEnabled,
+  log,
+  useDebugEnabled
+};
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debug.ts"],"sourcesContent":["// System-app devtools — the app-facing surface (plan: docs/plans/system-app-devtools.md).\n//\n// Two opt-in, DEV-ONLY instruments for debugging a sandboxed UI-as-app region:\n//   1. `debug.log(...)` — an app→host one-way log surfaced in the host dev panel\n//      / CLI `/debug` stream (instead of hand-fishing console output out of a\n//      cross-origin iframe's devtools).\n//   2. a READ-ONLY DOM/layout responder the host can query from outside — the\n//      thing a cross-origin screenshot can't reliably give you (a blank capture\n//      is ambiguous between a real 0-height collapse and a paint artifact).\n//\n// SECURITY (the gating constraint — see the plan's §0):\n//   - Both are inert unless the HOST signals dev mode via the `debug-enabled`\n//     channel. The host only sets it for a dev/override session (the `ir-dev-*`\n//     deep link) or an explicit operator developer-mode. A published app served\n//     to a normal user gets `enabled:false` → `debug.log` is a no-op and the\n//     responder never answers. Production isolation is therefore unchanged.\n//   - The responder is READ-ONLY with a fixed vocabulary (snapshotDom /\n//     computedStyle / rect). There is deliberately NO eval bridge — that would\n//     turn a debug aid into remote code execution into the sandbox.\n//   - The responder reads only its OWN `document` (it lives in its own opaque\n//     iframe and cannot reach a sibling app), so there is no app↔app leak even\n//     in dev.\n//   - Output is bounded (node/depth/text caps) so a query can't exfiltrate an\n//     unbounded payload or wedge the app.\n//\n// Apps that want the strongest guarantee can additionally guard their own usage\n// behind `import.meta.env.DEV` so the calls are tree-shaken from prod bundles;\n// the runtime gate here is the backstop that holds regardless.\n\nimport { createPushChannel } from './pushChannel';\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** Severity of a {@link debug.log} entry. */\nexport type DebugLevel = 'debug' | 'info' | 'warn' | 'error';\n\n// ── Dev gate ────────────────────────────────────────────────────────────────\n// The host pushes `debug-enabled:true` only for a dev/override session. Until\n// then (and always in production) it stays false and every instrument is inert.\nconst enabledChannel = createPushChannel<boolean>({\n  pushType: 'debug-enabled',\n  requestType: 'request-debug-enabled',\n  initial: false,\n  parse: (msg) => (typeof msg.enabled === 'boolean' ? msg.enabled : undefined),\n});\n\n/** Is the host dev-debug surface active for this session? `false` in production. */\nexport const isDebugEnabled = (): boolean => enabledChannel.get();\n\n/** React hook: whether the host dev-debug surface is active (re-renders on change).\n *  Handy for showing a debug affordance only when it would do something. */\nexport const useDebugEnabled = (): boolean => enabledChannel.use();\n\n// ── 1. App→host debug log ─────────────────────────────────────────────────────\n// Best-effort: a value that can't be structured-cloned is replaced with a marker\n// rather than throwing — `debug.log` must never break the app.\nconst MAX_DATA_BYTES = 16 * 1024;\n\nfunction safeData(data: unknown): unknown {\n  if (data === undefined) return undefined;\n  try {\n    const json = JSON.stringify(data);\n    if (json === undefined) return '[unserializable]';\n    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;\n    return JSON.parse(json);\n  } catch {\n    return '[unserializable]';\n  }\n}\n\n/**\n * Emit a structured debug entry to the host dev surface. A NO-OP unless the host\n * has enabled the dev-debug session ({@link isDebugEnabled}); in production it\n * does nothing and sends nothing.\n *\n *   debug.log('info', 'mounted', { activeFile });\n */\nexport function log(level: DebugLevel, message: string, data?: unknown): void {\n  if (!enabledChannel.get()) return; // inert in prod / non-dev sessions\n  try {\n    sendMessage('debug-log', { level, message: String(message), data: safeData(data) });\n  } catch {\n    /* transport not ready — drop silently; logging must never throw */\n  }\n}\n\n// ── 2. Read-only DOM / layout responder ───────────────────────────────────────\n// The host sends `debug-query` { id, method, params }; we reply with\n// `debug-query-result` { id, ok, result | error }. Only ever active while the dev\n// gate is enabled. Vocabulary is fixed and read-only.\n\ninterface DomNode {\n  tag: string;\n  id?: string;\n  classes?: string[];\n  attrs?: Record<string, string>;\n  rect?: { x: number; y: number; w: number; h: number };\n  text?: string;\n  children?: DomNode[];\n  truncated?: true;\n}\n\nconst ATTR_ALLOW = new Set(['role', 'aria-hidden', 'data-theme', 'data-active', 'href', 'type', 'hidden']);\nconst MAX_NODES = 2000;\nconst MAX_DEPTH = 25;\nconst MAX_TEXT = 200;\n\nfunction round(n: number): number {\n  return Math.round(n);\n}\n\nfunction snapshotDom(params: { selector?: string; maxDepth?: number; maxNodes?: number }): DomNode | null {\n  if (typeof document === 'undefined') return null;\n  const root = params.selector ? document.querySelector(params.selector) : document.body;\n  if (!root) return null;\n  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);\n  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);\n  let budget = maxNodes;\n\n  const walk = (el: Element, depth: number): DomNode => {\n    budget--;\n    const r = el.getBoundingClientRect();\n    const classes = el.classList.length ? [...el.classList] : undefined;\n    const attrs: Record<string, string> = {};\n    for (const name of el.getAttributeNames()) {\n      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? '';\n    }\n    // Direct text (not descendants') so a leaf's label is visible without dumping\n    // the whole subtree's text.\n    const ownText = [...el.childNodes]\n      .filter((n) => n.nodeType === 3)\n      .map((n) => (n.textContent ?? '').trim())\n      .join(' ')\n      .trim();\n    const node: DomNode = {\n      tag: el.tagName.toLowerCase(),\n      ...(el.id ? { id: el.id } : {}),\n      ...(classes ? { classes } : {}),\n      ...(Object.keys(attrs).length ? { attrs } : {}),\n      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },\n      ...(ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}),\n    };\n    if (depth < maxDepth && el.children.length && budget > 0) {\n      const children: DomNode[] = [];\n      for (const child of el.children) {\n        if (budget <= 0) {\n          node.truncated = true;\n          break;\n        }\n        children.push(walk(child, depth + 1));\n      }\n      if (children.length) node.children = children;\n    } else if (el.children.length) {\n      node.truncated = true;\n    }\n    return node;\n  };\n\n  return walk(root, 0);\n}\n\nfunction computedStyle(params: { selector: string; props: string[] }): Record<string, string> | null {\n  if (typeof document === 'undefined') return null;\n  const el = document.querySelector(params.selector);\n  if (!el) return null;\n  const cs = getComputedStyle(el);\n  const out: Record<string, string> = {};\n  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p as keyof CSSStyleDeclaration]?.toString?.() || '';\n  return out;\n}\n\nfunction rects(params: { selector: string }): Array<{ x: number; y: number; w: number; h: number }> {\n  if (typeof document === 'undefined') return [];\n  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {\n    const r = el.getBoundingClientRect();\n    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };\n  });\n}\n\nlet responderStarted = false;\n\n/** Wire the read-only DOM/layout responder. Idempotent; called lazily once the\n *  dev gate turns on. No effect when `document` is absent (non-browser realm). */\nfunction startResponder(): void {\n  if (responderStarted || typeof window === 'undefined') return;\n  responderStarted = true;\n  addListener('debug-query', (msg: { id?: unknown; method?: unknown; params?: unknown }) => {\n    if (!enabledChannel.get()) return; // gate: ignore unless dev-enabled\n    const id = msg.id;\n    const method = msg.method;\n    const params = (msg.params ?? {}) as Record<string, unknown>;\n    let ok = true;\n    let result: unknown = null;\n    let error: string | undefined;\n    try {\n      switch (method) {\n        case 'snapshotDom':\n          result = snapshotDom(params as never);\n          break;\n        case 'computedStyle':\n          result = computedStyle(params as never);\n          break;\n        case 'rect':\n          result = rects(params as never);\n          break;\n        default:\n          ok = false;\n          error = `unknown debug method: ${String(method)}`;\n      }\n    } catch (e) {\n      ok = false;\n      error = e instanceof Error ? e.message : String(e);\n    }\n    try {\n      sendMessage('debug-query-result', { id, ok, result, error });\n    } catch {\n      /* transport gone — nothing to do */\n    }\n  });\n}\n\n// Start the responder as soon as the gate flips on (and not before).\nenabledChannel.onChange((enabled) => {\n  if (enabled) startResponder();\n});\n\n/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */\nexport const debug = { log, isEnabled: isDebugEnabled } as const;\n"],"mappings":"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","names":[]}

package/dist/fs.cjs

@@ -0,0 +1,214 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var fs_exports = {};
+__export(fs_exports, {
+  fsAvailable: () => fsAvailable,
+  openAppFs: () => openAppFs,
+  openFs: () => openFs,
+  sandboxFs: () => sandboxFs
+});
+module.exports = __toCommonJS(fs_exports);
+var import_mounts = require("./mounts");
+const hasFs = (fs) => typeof fs?.promises?.readFile === "function" || typeof fs?.readFile === "function";
+function sandboxFs() {
+  try {
+    const shared = globalThis.__sandpackSharedFs;
+    if (hasFs(shared)) return shared;
+  } catch {
+  }
+  try {
+    const layers = module?.evaluation?.module?.bundler?.fs?.layers;
+    if (Array.isArray(layers)) {
+      for (const layer of layers) {
+        const fs = layer?.boundContext?.fs;
+        if (hasFs(fs)) return fs;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function fsAvailable() {
+  return sandboxFs() != null;
+}
+const ERRNO = {
+  ENOENT: "not-found",
+  EROFS: "read-only",
+  EACCES: "not-permitted",
+  EPERM: "not-permitted",
+  EEXIST: "exists",
+  ENOTEMPTY: "not-empty"
+};
+const fsError = (code, message) => {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+};
+const mapError = (e) => {
+  const errno = e?.code;
+  const code = (errno ? ERRNO[errno] : void 0) ?? "unknown";
+  const err = new Error(e?.message ?? "fs operation failed");
+  err.code = code;
+  return err;
+};
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+const resolveUnder = (root, relPath) => {
+  if (relPath.startsWith("/")) {
+    throw fsError("invalid-path", `expected a mount-relative path, got absolute "${relPath}"`);
+  }
+  const parts = [];
+  for (const seg of relPath.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      throw fsError("invalid-path", `"${relPath}" escapes the mount root`);
+    }
+    parts.push(seg);
+  }
+  const base = root.endsWith("/") ? root.slice(0, -1) : root;
+  return parts.length ? `${base}/${parts.join("/")}` : base;
+};
+const writableAt = (mount, relPath) => {
+  const path = "/" + relPath.split("/").filter((s) => s && s !== ".").join("/");
+  const rules = mount.rules;
+  if (rules && rules.length) {
+    let best;
+    for (const r of rules) {
+      const sub = r.subtree.endsWith("/") ? r.subtree : r.subtree + "/";
+      if (path === r.subtree || path.startsWith(sub) || r.subtree === "/") {
+        if (!best || r.subtree.length > best.subtree.length) best = r;
+      }
+    }
+    if (best) return best.mode === "rw";
+  }
+  return (mount.mode ?? "rw") === "rw";
+};
+const promisesOf = (port) => port.promises ?? port;
+function openFs(mount) {
+  const root = mount.path;
+  const port = () => {
+    const p = sandboxFs();
+    if (!p) throw fsError("unavailable", "immediately.run: sandbox filesystem unavailable");
+    return promisesOf(p);
+  };
+  const api = {
+    mount,
+    async readFile(relPath, encoding) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const data = await p.readFile(abs);
+        const bytes = typeof data === "string" ? encoder.encode(data) : data;
+        return encoding === "utf8" ? decoder.decode(bytes) : bytes;
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async writeFile(relPath, data) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.writeFile(abs, typeof data === "string" ? encoder.encode(data) : data);
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async readdir(relPath = "") {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const entries = await p.readdir(abs, { withFileTypes: true });
+        return entries.map(
+          (d) => typeof d === "string" ? { name: d, kind: "file" } : { name: d.name, kind: d.isDirectory?.() ? "dir" : "file" }
+        );
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async stat(relPath) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        const s = await p.stat(abs);
+        return {
+          kind: s.isDirectory?.() ? "dir" : "file",
+          size: typeof s.size === "number" ? s.size : 0,
+          mtimeMs: typeof s.mtimeMs === "number" ? s.mtimeMs : void 0
+        };
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async exists(relPath) {
+      try {
+        await api.stat(relPath);
+        return true;
+      } catch (e) {
+        if (e.code === "not-found") return false;
+        if (e.code === "unavailable" || e.code === "invalid-path") {
+          throw e;
+        }
+        return false;
+      }
+    },
+    async mkdir(relPath, opts) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.mkdir(abs, { recursive: opts?.recursive ?? false });
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async rm(relPath, opts) {
+      const p = port();
+      const abs = resolveUnder(root, relPath);
+      try {
+        await p.rm(abs, { recursive: opts?.recursive ?? false });
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    async rename(fromRel, toRel) {
+      const p = port();
+      const from = resolveUnder(root, fromRel);
+      const to = resolveUnder(root, toRel);
+      try {
+        await p.rename(from, to);
+      } catch (e) {
+        throw mapError(e);
+      }
+    },
+    canWrite(relPath = "") {
+      return writableAt(mount, relPath);
+    }
+  };
+  return api;
+}
+function openAppFs() {
+  return openFs({ path: (0, import_mounts.getAppMountPath)(), type: "repo" });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fsAvailable,
+  openAppFs,
+  openFs,
+  sandboxFs
+});
+//# sourceMappingURL=fs.cjs.map

package/dist/fs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fs.ts"],"sourcesContent":["// Typed, discoverable filesystem access — the app-facing surface for the ZenFS\n// mount ports (SDK_FS_SURFACE_SPEC; FILESYSTEM_SPEC §2 the ZenFS-shaped contract).\n//\n// The single most important thing an app does — read/write files in its mounts —\n// previously had NO SDK surface: apps reached an ambient `globalThis.__sandpackSharedFs`\n// by hand-rolling the same accessor (editor/file-explorer `src/fs/mountFs.ts`, \"keep the\n// two in sync\"), with a documented footgun (`module.evaluation.module.bundler.fs` is the\n// WRONG object — it has no `promises`/`stat`). This module is that accessor's ONE home,\n// typed and documented.\n//\n// It adds NO authority: the ZenFS port is already minted and chroot/`ro`-enforced\n// host-side (FILESYSTEM_SPEC §2, UI_AS_APPS §8.7). This is typing + discoverability +\n// de-duplication only. `fs` is a Resource PORT (a byte channel), not a host-brokered RPC,\n// so — unlike the `invoke()` catalog surface — it is hand-written, not gate-table-derived.\nimport type { SandboxMount, MountRule } from './mounts';\nimport { getAppMountPath } from './mounts';\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */\ninterface NodeFsPromises {\n  readFile(path: string, encoding?: any): Promise<string | Uint8Array>;\n  writeFile(path: string, data: string | Uint8Array): Promise<void>;\n  readdir(path: string, opts?: any): Promise<any[]>;\n  stat(path: string): Promise<any>;\n  mkdir(path: string, opts?: any): Promise<unknown>;\n  rm(path: string, opts?: any): Promise<void>;\n  rename(from: string, to: string): Promise<void>;\n}\n\n/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —\n *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */\nexport interface SandboxFsPort {\n  promises?: NodeFsPromises;\n  readFile?: NodeFsPromises['readFile'];\n}\n\nconst hasFs = (fs: any): boolean =>\n  typeof fs?.promises?.readFile === 'function' || typeof fs?.readFile === 'function';\n\n/**\n * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the\n * resolution order previously duplicated in every app's `mountFs.ts`:\n *\n * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.\n * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`\n *    whose surface has `readFile` (the bundler ZenFS-layer bound context).\n * 3. else `null` (local `vite dev` / before boot).\n *\n * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute\n * `/mnt/{hash}` paths (the file explorer / editor).\n */\nexport function sandboxFs(): SandboxFsPort | null {\n  try {\n    const shared = (globalThis as any).__sandpackSharedFs;\n    if (hasFs(shared)) return shared as SandboxFsPort;\n  } catch {\n    /* not in the sandbox */\n  }\n  try {\n    // @ts-ignore - `module` is injected by the sandbox runtime (see sandboxUtils transport).\n    const layers = module?.evaluation?.module?.bundler?.fs?.layers;\n    if (Array.isArray(layers)) {\n      for (const layer of layers) {\n        const fs = layer?.boundContext?.fs;\n        if (hasFs(fs)) return fs as SandboxFsPort;\n      }\n    }\n  } catch {\n    /* not in the sandbox */\n  }\n  return null;\n}\n\n/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before\n *  boot — gate file affordances on it so an app degrades instead of throwing. */\nexport function fsAvailable(): boolean {\n  return sandboxFs() != null;\n}\n\n/** A directory entry from {@link MountFs.readdir}. */\nexport interface DirEntry {\n  name: string;\n  kind: 'file' | 'dir';\n}\n\n/** A stat result from {@link MountFs.stat}. */\nexport interface FileStat {\n  kind: 'file' | 'dir';\n  size: number;\n  mtimeMs?: number;\n}\n\n/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`\n *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */\nexport interface FsError extends Error {\n  code:\n    | 'not-found' // ENOENT\n    | 'read-only' // EROFS — a `ro` mount / downgraded role; NEVER surface as UX (gate with canWrite)\n    | 'not-permitted' // EACCES\n    | 'exists' // EEXIST\n    | 'not-empty' // ENOTEMPTY\n    | 'invalid-path' // a `..` segment / absolute escape was passed as a relPath\n    | 'unavailable' // no sandbox fs (local dev / pre-boot)\n    | 'unknown';\n}\n\nconst ERRNO: Record<string, FsError['code']> = {\n  ENOENT: 'not-found',\n  EROFS: 'read-only',\n  EACCES: 'not-permitted',\n  EPERM: 'not-permitted',\n  EEXIST: 'exists',\n  ENOTEMPTY: 'not-empty',\n};\n\nconst fsError = (code: FsError['code'], message: string): FsError => {\n  const err = new Error(message) as FsError;\n  err.code = code;\n  return err;\n};\n\nconst mapError = (e: unknown): FsError => {\n  const errno = (e as { code?: string } | null)?.code;\n  const code: FsError['code'] = (errno ? ERRNO[errno] : undefined) ?? 'unknown';\n  const err = new Error((e as Error)?.message ?? 'fs operation failed') as FsError;\n  err.code = code;\n  return err;\n};\n\nconst decoder = new TextDecoder();\nconst encoder = new TextEncoder();\n\n// Join a mount-RELATIVE path under the mount root, rejecting `..` escapes and absolute\n// paths (CLAUDE.md security rule 3 — don't probe for escapes). The host chroot is the\n// real enforcer; this keeps an honest app from accidentally naming outside its grant.\nconst resolveUnder = (root: string, relPath: string): string => {\n  if (relPath.startsWith('/')) {\n    throw fsError('invalid-path', `expected a mount-relative path, got absolute \"${relPath}\"`);\n  }\n  const parts: string[] = [];\n  for (const seg of relPath.split('/')) {\n    if (seg === '' || seg === '.') continue;\n    if (seg === '..') {\n      throw fsError('invalid-path', `\"${relPath}\" escapes the mount root`);\n    }\n    parts.push(seg);\n  }\n  const base = root.endsWith('/') ? root.slice(0, -1) : root;\n  return parts.length ? `${base}/${parts.join('/')}` : base;\n};\n\n// The longest matching `rules` subtree governs a path (mounts.ts MountRule); fall back to\n// the whole-mount `mode`. A CLIENT-SIDE hint mirroring the host rule — EROFS stays\n// authoritative (the host re-checks live policy on every write).\nconst writableAt = (mount: SandboxMount, relPath: string): boolean => {\n  const path = '/' + relPath.split('/').filter((s) => s && s !== '.').join('/');\n  const rules: MountRule[] | undefined = mount.rules;\n  if (rules && rules.length) {\n    let best: MountRule | undefined;\n    for (const r of rules) {\n      const sub = r.subtree.endsWith('/') ? r.subtree : r.subtree + '/';\n      if (path === r.subtree || path.startsWith(sub) || r.subtree === '/') {\n        if (!best || r.subtree.length > best.subtree.length) best = r;\n      }\n    }\n    if (best) return best.mode === 'rw';\n  }\n  return (mount.mode ?? 'rw') === 'rw';\n};\n\n/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;\n *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).\n *  Obtain one with {@link openFs}. */\nexport interface MountFs {\n  /** The mount this view is anchored to (read `mode`/`rules` for writability). */\n  readonly mount: SandboxMount;\n  /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */\n  readFile(relPath: string, encoding: 'utf8'): Promise<string>;\n  readFile(relPath: string): Promise<Uint8Array>;\n  /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */\n  writeFile(relPath: string, data: string | Uint8Array): Promise<void>;\n  /** List a directory (the mount root when `relPath` is omitted). */\n  readdir(relPath?: string): Promise<DirEntry[]>;\n  /** Stat a path. Throws `not-found` if absent. */\n  stat(relPath: string): Promise<FileStat>;\n  /** Does `relPath` exist? Never throws on absence. */\n  exists(relPath: string): Promise<boolean>;\n  /** Create a directory (pass `{ recursive: true }` to make parents). */\n  mkdir(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Remove a file, or a directory with `{ recursive: true }`. */\n  rm(relPath: string, opts?: { recursive?: boolean }): Promise<void>;\n  /** Rename/move within the mount. */\n  rename(fromRel: string, toRel: string): Promise<void>;\n  /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),\n   *  so an app can hide an \"edit\" affordance instead of catching `read-only`\n   *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade\n   *  flips it. EROFS from the host stays authoritative. */\n  canWrite(relPath?: string): boolean;\n}\n\nconst promisesOf = (port: SandboxFsPort): NodeFsPromises =>\n  (port.promises ?? (port as unknown as NodeFsPromises));\n\n/**\n * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:\n * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you\n * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path\n * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the\n * real enforcer).\n *\n * ```ts\n * import { mountSpace } from '@immediately-run/sdk';\n * import { openFs } from '@immediately-run/sdk/fs';\n * const fs = openFs(await mountSpace({ spaceId }));\n * const text = await fs.readFile('notes/idea.mdx', 'utf8');\n * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);\n * ```\n *\n * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`\n * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}\n * with a mapped `.code` (`not-found`, `read-only`, …).\n */\nexport function openFs(mount: SandboxMount): MountFs {\n  const root = mount.path;\n\n  const port = (): NodeFsPromises => {\n    const p = sandboxFs();\n    if (!p) throw fsError('unavailable', 'immediately.run: sandbox filesystem unavailable');\n    return promisesOf(p);\n  };\n\n  const api: MountFs = {\n    mount,\n    async readFile(relPath: string, encoding?: 'utf8'): Promise<any> {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const data = await p.readFile(abs);\n        const bytes =\n          typeof data === 'string' ? encoder.encode(data) : (data as Uint8Array);\n        return encoding === 'utf8' ? decoder.decode(bytes) : bytes;\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async writeFile(relPath, data) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.writeFile(abs, typeof data === 'string' ? encoder.encode(data) : data);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async readdir(relPath = '') {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const entries = await p.readdir(abs, { withFileTypes: true });\n        return entries.map((d: any) =>\n          typeof d === 'string'\n            ? ({ name: d, kind: 'file' } as DirEntry)\n            : ({ name: d.name, kind: d.isDirectory?.() ? 'dir' : 'file' } as DirEntry),\n        );\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async stat(relPath) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        const s: any = await p.stat(abs);\n        return {\n          kind: s.isDirectory?.() ? 'dir' : 'file',\n          size: typeof s.size === 'number' ? s.size : 0,\n          mtimeMs: typeof s.mtimeMs === 'number' ? s.mtimeMs : undefined,\n        };\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async exists(relPath) {\n      try {\n        await api.stat(relPath);\n        return true;\n      } catch (e) {\n        if ((e as FsError).code === 'not-found') return false;\n        if ((e as FsError).code === 'unavailable' || (e as FsError).code === 'invalid-path') {\n          throw e;\n        }\n        return false;\n      }\n    },\n    async mkdir(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.mkdir(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rm(relPath, opts) {\n      const p = port();\n      const abs = resolveUnder(root, relPath);\n      try {\n        await p.rm(abs, { recursive: opts?.recursive ?? false });\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    async rename(fromRel, toRel) {\n      const p = port();\n      const from = resolveUnder(root, fromRel);\n      const to = resolveUnder(root, toRel);\n      try {\n        await p.rename(from, to);\n      } catch (e) {\n        throw mapError(e);\n      }\n    },\n    canWrite(relPath = '') {\n      return writableAt(mount, relPath);\n    },\n  };\n  return api;\n}\n\n/** Open a mount-anchored view of this app's OWN repository working tree — a convenience\n *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */\nexport function openAppFs(): MountFs {\n  return openFs({ path: getAppMountPath(), type: 'repo' } as SandboxMount);\n}\n"],"mappings":"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","names":[]}

package/dist/fs.d.cts

@@ -0,0 +1,109 @@
+import { SandboxMount } from './mounts.cjs';
+import './tasks.cjs';
+
+/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */
+interface NodeFsPromises {
+    readFile(path: string, encoding?: any): Promise<string | Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readdir(path: string, opts?: any): Promise<any[]>;
+    stat(path: string): Promise<any>;
+    mkdir(path: string, opts?: any): Promise<unknown>;
+    rm(path: string, opts?: any): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —
+ *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */
+interface SandboxFsPort {
+    promises?: NodeFsPromises;
+    readFile?: NodeFsPromises['readFile'];
+}
+/**
+ * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the
+ * resolution order previously duplicated in every app's `mountFs.ts`:
+ *
+ * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.
+ * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`
+ *    whose surface has `readFile` (the bundler ZenFS-layer bound context).
+ * 3. else `null` (local `vite dev` / before boot).
+ *
+ * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute
+ * `/mnt/{hash}` paths (the file explorer / editor).
+ */
+declare function sandboxFs(): SandboxFsPort | null;
+/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before
+ *  boot — gate file affordances on it so an app degrades instead of throwing. */
+declare function fsAvailable(): boolean;
+/** A directory entry from {@link MountFs.readdir}. */
+interface DirEntry {
+    name: string;
+    kind: 'file' | 'dir';
+}
+/** A stat result from {@link MountFs.stat}. */
+interface FileStat {
+    kind: 'file' | 'dir';
+    size: number;
+    mtimeMs?: number;
+}
+/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`
+ *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */
+interface FsError extends Error {
+    code: 'not-found' | 'read-only' | 'not-permitted' | 'exists' | 'not-empty' | 'invalid-path' | 'unavailable' | 'unknown';
+}
+/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;
+ *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).
+ *  Obtain one with {@link openFs}. */
+interface MountFs {
+    /** The mount this view is anchored to (read `mode`/`rules` for writability). */
+    readonly mount: SandboxMount;
+    /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */
+    readFile(relPath: string, encoding: 'utf8'): Promise<string>;
+    readFile(relPath: string): Promise<Uint8Array>;
+    /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */
+    writeFile(relPath: string, data: string | Uint8Array): Promise<void>;
+    /** List a directory (the mount root when `relPath` is omitted). */
+    readdir(relPath?: string): Promise<DirEntry[]>;
+    /** Stat a path. Throws `not-found` if absent. */
+    stat(relPath: string): Promise<FileStat>;
+    /** Does `relPath` exist? Never throws on absence. */
+    exists(relPath: string): Promise<boolean>;
+    /** Create a directory (pass `{ recursive: true }` to make parents). */
+    mkdir(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Remove a file, or a directory with `{ recursive: true }`. */
+    rm(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Rename/move within the mount. */
+    rename(fromRel: string, toRel: string): Promise<void>;
+    /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),
+     *  so an app can hide an "edit" affordance instead of catching `read-only`
+     *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade
+     *  flips it. EROFS from the host stays authoritative. */
+    canWrite(relPath?: string): boolean;
+}
+/**
+ * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:
+ * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you
+ * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path
+ * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the
+ * real enforcer).
+ *
+ * ```ts
+ * import { mountSpace } from '@immediately-run/sdk';
+ * import { openFs } from '@immediately-run/sdk/fs';
+ * const fs = openFs(await mountSpace({ spaceId }));
+ * const text = await fs.readFile('notes/idea.mdx', 'utf8');
+ * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);
+ * ```
+ *
+ * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`
+ * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}
+ * with a mapped `.code` (`not-found`, `read-only`, …).
+ */
+declare function openFs(mount: SandboxMount): MountFs;
+/** Open a mount-anchored view of this app's OWN repository working tree — a convenience
+ *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */
+declare function openAppFs(): MountFs;
+
+export { type DirEntry, type FileStat, type FsError, type MountFs, type SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs };

package/dist/fs.d.ts

@@ -0,0 +1,109 @@
+import { SandboxMount } from './mounts.js';
+import './tasks.js';
+
+/** The node-compatible promises surface the sandbox ZenFS exposes (the subset we use). */
+interface NodeFsPromises {
+    readFile(path: string, encoding?: any): Promise<string | Uint8Array>;
+    writeFile(path: string, data: string | Uint8Array): Promise<void>;
+    readdir(path: string, opts?: any): Promise<any[]>;
+    stat(path: string): Promise<any>;
+    mkdir(path: string, opts?: any): Promise<unknown>;
+    rm(path: string, opts?: any): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+/** The resolved sandbox ZenFS handle (node-compatible, `/`-rooted). Opaque to apps —
+ *  reach it through {@link openFs}; the raw handle is the {@link sandboxFs} escape hatch. */
+interface SandboxFsPort {
+    promises?: NodeFsPromises;
+    readFile?: NodeFsPromises['readFile'];
+}
+/**
+ * The resolved sandbox ZenFS, or `null` when unavailable. The ONE home for the
+ * resolution order previously duplicated in every app's `mountFs.ts`:
+ *
+ * 1. `globalThis.__sandpackSharedFs` — the `/`-rooted bound ZenFS the sandbox publishes.
+ * 2. fallback: the first `module.evaluation.module.bundler.fs.layers[].boundContext.fs`
+ *    whose surface has `readFile` (the bundler ZenFS-layer bound context).
+ * 3. else `null` (local `vite dev` / before boot).
+ *
+ * Prefer {@link openFs}; reach for this only when a system app spans mounts in absolute
+ * `/mnt/{hash}` paths (the file explorer / editor).
+ */
+declare function sandboxFs(): SandboxFsPort | null;
+/** Is the sandbox filesystem reachable at all? `false` in local `vite dev` and before
+ *  boot — gate file affordances on it so an app degrades instead of throwing. */
+declare function fsAvailable(): boolean;
+/** A directory entry from {@link MountFs.readdir}. */
+interface DirEntry {
+    name: string;
+    kind: 'file' | 'dir';
+}
+/** A stat result from {@link MountFs.stat}. */
+interface FileStat {
+    kind: 'file' | 'dir';
+    size: number;
+    mtimeMs?: number;
+}
+/** An error from a {@link MountFs} operation, carrying a machine-readable `.code`
+ *  (mapped from the ZenFS errno) so an app branches on `.code`, never on a message. */
+interface FsError extends Error {
+    code: 'not-found' | 'read-only' | 'not-permitted' | 'exists' | 'not-empty' | 'invalid-path' | 'unavailable' | 'unknown';
+}
+/** A mount-anchored, typed filesystem view. All paths are RELATIVE to the mount root;
+ *  the accessor resolves them under `mount.path`. Async-only (ZenFS rides a MessagePort).
+ *  Obtain one with {@link openFs}. */
+interface MountFs {
+    /** The mount this view is anchored to (read `mode`/`rules` for writability). */
+    readonly mount: SandboxMount;
+    /** Read a file as UTF-8 text (`encoding: 'utf8'`) or raw bytes (omit encoding). */
+    readFile(relPath: string, encoding: 'utf8'): Promise<string>;
+    readFile(relPath: string): Promise<Uint8Array>;
+    /** Write text or bytes, creating or truncating the file. Throws `read-only` on a `ro` mount. */
+    writeFile(relPath: string, data: string | Uint8Array): Promise<void>;
+    /** List a directory (the mount root when `relPath` is omitted). */
+    readdir(relPath?: string): Promise<DirEntry[]>;
+    /** Stat a path. Throws `not-found` if absent. */
+    stat(relPath: string): Promise<FileStat>;
+    /** Does `relPath` exist? Never throws on absence. */
+    exists(relPath: string): Promise<boolean>;
+    /** Create a directory (pass `{ recursive: true }` to make parents). */
+    mkdir(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Remove a file, or a directory with `{ recursive: true }`. */
+    rm(relPath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Rename/move within the mount. */
+    rename(fromRel: string, toRel: string): Promise<void>;
+    /** Client-side writability hint for `relPath` (mount `mode` ∩ longest-matching `rule`),
+     *  so an app can hide an "edit" affordance instead of catching `read-only`
+     *  (EDITOR_FIRST_EDITING_SPEC §3). Re-evaluate on `onMountsChange` — a role downgrade
+     *  flips it. EROFS from the host stays authoritative. */
+    canWrite(relPath?: string): boolean;
+}
+/**
+ * Open a typed, mount-anchored filesystem view (SDK_FS_SURFACE_SPEC §2.1). Pure-client:
+ * resolves the ambient ZenFS once ({@link sandboxFs}) and binds it to `mount.path`, so you
+ * read/write with paths RELATIVE to the mount root — you cannot accidentally name a path
+ * outside your grant (a `..`/absolute path throws `invalid-path`; the host chroot is the
+ * real enforcer).
+ *
+ * ```ts
+ * import { mountSpace } from '@immediately-run/sdk';
+ * import { openFs } from '@immediately-run/sdk/fs';
+ * const fs = openFs(await mountSpace({ spaceId }));
+ * const text = await fs.readFile('notes/idea.mdx', 'utf8');
+ * if (fs.canWrite('notes/idea.mdx')) await fs.writeFile('notes/idea.mdx', text);
+ * ```
+ *
+ * Throws {@link FsError} `unavailable` if the sandbox fs is not present (local `vite dev`
+ * / before boot — gate with {@link fsAvailable}). Per-op failures throw {@link FsError}
+ * with a mapped `.code` (`not-found`, `read-only`, …).
+ */
+declare function openFs(mount: SandboxMount): MountFs;
+/** Open a mount-anchored view of this app's OWN repository working tree — a convenience
+ *  over {@link openFs} using `getAppMountPath()` (FILE_SHARING_SPEC §11.2). */
+declare function openAppFs(): MountFs;
+
+export { type DirEntry, type FileStat, type FsError, type MountFs, type SandboxFsPort, fsAvailable, openAppFs, openFs, sandboxFs };