@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.4

package/dist/cjs/internal/AtomicFileSystemExecutable.js

@@ -0,0 +1,250 @@
+"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 AtomicFileSystemExecutable_exports = {};
+__export(AtomicFileSystemExecutable_exports, {
+  installedPackageRoot: () => installedPackageRoot,
+  outsideWorkspace: () => outsideWorkspace,
+  packageRoot: () => packageRoot,
+  registerEmbeddedHelper: () => registerEmbeddedHelper,
+  resolveConfiguredExecutable: () => resolveConfiguredExecutable,
+  resolveDefaultExecutable: () => resolveDefaultExecutable,
+  resolvePackageRoot: () => resolvePackageRoot,
+  stagePackaged: () => stagePackaged
+});
+module.exports = __toCommonJS(AtomicFileSystemExecutable_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_module = require("node:module");
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+var import_node_url = require("node:url");
+var import_AtomicFileSystemTransport = require("./AtomicFileSystemTransport.js");
+var import_AtomicHelperError = require("./AtomicHelperError.js");
+const import_meta = {};
+const moduleDirectory = typeof __dirname === "string" ? __dirname : (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+const resolvePackageRoot = (directory) => {
+  const sourcePackageRoot = (0, import_node_path.resolve)(directory, "../..");
+  return (0, import_node_fs.existsSync)((0, import_node_path.join)(sourcePackageRoot, "package.json")) ? sourcePackageRoot : (0, import_node_path.resolve)(directory, "../../..");
+};
+const installedPackageRoot = (modulePath, fallback) => {
+  try {
+    return (0, import_node_path.dirname)((0, import_node_module.createRequire)(modulePath).resolve("@smthrs/platform-node/package.json"));
+  } catch {
+    return fallback;
+  }
+};
+const packageRoot = installedPackageRoot(
+  (0, import_node_path.join)(moduleDirectory, "resolver.cjs"),
+  resolvePackageRoot(moduleDirectory)
+);
+const staged = /* @__PURE__ */ new Map();
+const stagedRoots = /* @__PURE__ */ new Set();
+const trusted = /* @__PURE__ */ new Set();
+const installHint = "install @smthrs/platform-node with its native helper, run cargo build --locked --release -p smithers-ffi --bin smithers-jj-export in a source checkout, or set SMITHERS_WORKSPACE_JJ_EXPORT_BINARY to its absolute path";
+const helperName = process.platform === "win32" ? "smithers-jj-export.exe" : "smithers-jj-export";
+const sha256 = (bytes) => (0, import_node_crypto.createHash)("sha256").update(bytes).digest("hex");
+const ownedByThisUser = (info) => {
+  const uid = process.getuid?.();
+  return uid === void 0 || info.uid === uid;
+};
+const privateDirectory = (directory) => {
+  try {
+    (0, import_node_fs.mkdirSync)(directory, { mode: 448 });
+  } catch (cause) {
+    if (cause.code !== "EEXIST") throw cause;
+  }
+  const info = (0, import_node_fs.lstatSync)(directory);
+  if (!info.isDirectory() || !ownedByThisUser(info)) {
+    throw new import_AtomicHelperError.AtomicHelperError({
+      code: "staging_directory_not_private",
+      message: `atomic helper staging directory is not a private directory: ${directory}`
+    });
+  }
+  (0, import_node_fs.chmodSync)(directory, 448);
+};
+const matches = (destination, digest) => {
+  try {
+    const info = (0, import_node_fs.lstatSync)(destination);
+    if (!info.isFile() || info.nlink !== 1 || !ownedByThisUser(info)) return false;
+    return sha256((0, import_node_fs.readFileSync)(destination)) === digest;
+  } catch {
+    return false;
+  }
+};
+const staleMs = 7 * 24 * 60 * 60 * 1e3;
+const refreshMs = 60 * 60 * 1e3;
+const refresh = (copy) => {
+  const now = Date.now();
+  if (now - copy.touchedAt < refreshMs) return;
+  copy.touchedAt = now;
+  (0, import_node_fs.utimes)((0, import_node_path.dirname)(copy.path), now / 1e3, now / 1e3, () => {
+  });
+};
+const prune = (base, keep) => {
+  const now = Date.now();
+  let names;
+  try {
+    names = (0, import_node_fs.readdirSync)(base);
+  } catch {
+    return;
+  }
+  const temporaryPrefix = `.${helperName}.`;
+  for (const name of names) {
+    if (!name.startsWith(".smthrs-atomic-helper-")) continue;
+    const directory = (0, import_node_path.join)(base, name);
+    try {
+      const info = (0, import_node_fs.lstatSync)(directory);
+      if (!info.isDirectory() || !ownedByThisUser(info)) continue;
+      if (name !== keep && now - info.mtimeMs > staleMs) {
+        (0, import_node_fs.rmSync)(directory, { recursive: true, force: true });
+        continue;
+      }
+      for (const entry of (0, import_node_fs.readdirSync)(directory)) {
+        if (!entry.startsWith(temporaryPrefix) || !/^\d+\.[0-9a-f]{12}$/.test(entry.slice(temporaryPrefix.length))) {
+          continue;
+        }
+        const temporary = (0, import_node_path.join)(directory, entry);
+        try {
+          const file = (0, import_node_fs.lstatSync)(temporary);
+          if (file.isFile() && ownedByThisUser(file) && now - file.mtimeMs > staleMs) {
+            (0, import_node_fs.rmSync)(temporary, { force: true });
+          }
+        } catch {
+        }
+      }
+    } catch {
+    }
+  }
+};
+let embeddedHelper;
+const registerEmbeddedHelper = (source) => {
+  embeddedHelper = source;
+};
+const outsideWorkspace = (source, boundaryRoot, bases = [(0, import_node_os.tmpdir)(), (0, import_node_os.homedir)()]) => {
+  const cached = staged.get(source);
+  if (cached !== void 0) {
+    if ((0, import_node_fs.existsSync)(cached.path)) {
+      refresh(cached);
+      return (0, import_AtomicFileSystemTransport.usableExecutable)(cached.path, boundaryRoot);
+    }
+    staged.delete(source);
+  }
+  const bytes = (0, import_node_fs.readFileSync)(source);
+  const digest = sha256(bytes);
+  for (const [index, base] of bases.entries()) {
+    const directory = (0, import_node_path.join)(base, `.smthrs-atomic-helper-${digest}`);
+    const destination = (0, import_node_path.join)(directory, helperName);
+    let temporary;
+    try {
+      privateDirectory(directory);
+      const now = /* @__PURE__ */ new Date();
+      (0, import_node_fs.utimesSync)(directory, now, now);
+      if (!matches(destination, digest)) {
+        temporary = (0, import_node_path.join)(directory, `.${helperName}.${process.pid}.${(0, import_node_crypto.randomBytes)(6).toString("hex")}`);
+        (0, import_node_fs.writeFileSync)(temporary, bytes, { flag: "wx", mode: 320 });
+        (0, import_node_fs.chmodSync)(temporary, 320);
+        (0, import_node_fs.renameSync)(temporary, destination);
+        temporary = void 0;
+      }
+      const executable = (0, import_AtomicFileSystemTransport.usableExecutable)(destination, boundaryRoot);
+      prune(base, `.smthrs-atomic-helper-${digest}`);
+      staged.set(source, { path: executable, touchedAt: now.getTime() });
+      return executable;
+    } catch (cause) {
+      if (temporary !== void 0) (0, import_node_fs.rmSync)(temporary, { force: true });
+      if (index === bases.length - 1) throw cause;
+    }
+  }
+  throw new import_AtomicHelperError.AtomicHelperError({
+    code: "staging_unavailable",
+    message: "no staging location for smithers-jj-export"
+  });
+};
+const packagedHelper = (root) => (0, import_node_path.join)(root, "bin", `${process.platform}-${process.arch}`, helperName);
+const checkoutHelpers = (root) => {
+  const checkout = (0, import_node_path.resolve)(root, "../../../..");
+  return (0, import_node_fs.existsSync)((0, import_node_path.join)(checkout, "pnpm-workspace.yaml")) ? [(0, import_node_path.join)(checkout, "target/release", helperName), (0, import_node_path.join)(checkout, "target/debug", helperName)] : [];
+};
+const stagePackaged = (root) => {
+  if (stagedRoots.has(root)) return;
+  stagedRoots.add(root);
+  const candidate = embeddedHelper ?? packagedHelper(root);
+  try {
+    if ((0, import_node_fs.existsSync)(candidate) && (0, import_node_fs.statSync)(candidate).isFile()) {
+      outsideWorkspace(candidate, void 0);
+      trusted.add(candidate);
+    }
+  } catch {
+  }
+  if (embeddedHelper !== void 0) return;
+  for (const build of checkoutHelpers(root)) {
+    try {
+      if ((0, import_node_fs.existsSync)(build)) {
+        const executable = (0, import_AtomicFileSystemTransport.usableExecutable)(build, void 0);
+        outsideWorkspace(executable, void 0);
+        trusted.add(executable);
+      }
+    } catch {
+    }
+  }
+};
+const workspaceSupplied = (candidate, source, boundaryRoot) => (0, import_AtomicFileSystemTransport.inside)(boundaryRoot, (0, import_node_path.resolve)(candidate)) || (0, import_AtomicFileSystemTransport.inside)(boundaryRoot, (0, import_node_path.join)(import_node_fs.realpathSync.native((0, import_node_path.dirname)(candidate)), (0, import_node_path.basename)(candidate))) || (0, import_AtomicFileSystemTransport.inside)(boundaryRoot, import_node_fs.realpathSync.native(source));
+const pinned = (candidate, source, boundaryRoot) => {
+  if (boundaryRoot !== void 0 && !trusted.has(source) && workspaceSupplied(candidate, source, boundaryRoot)) {
+    throw new import_AtomicHelperError.AtomicHelperError({
+      code: "helper_inside_workspace",
+      message: `atomic helper executable must live outside the confined workspace: ${candidate} was not present when the host was built`
+    });
+  }
+  return outsideWorkspace(source, boundaryRoot);
+};
+const resolveDefaultExecutable = (root, boundaryRoot, fallback = "/usr/local/bin/smithers-jj-export") => {
+  if (embeddedHelper !== void 0) return outsideWorkspace(embeddedHelper, boundaryRoot);
+  const candidates = [packagedHelper(root), ...checkoutHelpers(root), fallback];
+  for (const [index, candidate] of candidates.entries()) {
+    if (!(0, import_node_fs.existsSync)(candidate)) continue;
+    if (index === 0) {
+      if (!(0, import_node_fs.statSync)(candidate).isFile()) {
+        throw new import_AtomicHelperError.AtomicHelperError({
+          code: "helper_not_regular_file",
+          message: `packaged atomic helper is not a regular file: ${candidate}`
+        });
+      }
+      return pinned(candidate, candidate, boundaryRoot);
+    }
+    const executable = (0, import_AtomicFileSystemTransport.usableExecutable)(candidate, void 0);
+    return boundaryRoot !== void 0 && workspaceSupplied(candidate, executable, boundaryRoot) ? pinned(candidate, executable, boundaryRoot) : executable;
+  }
+  throw new import_AtomicHelperError.AtomicHelperError({
+    code: "helper_missing",
+    message: `smithers-jj-export is missing; ${installHint} (searched ${candidates.join(", ")})`
+  });
+};
+const resolveConfiguredExecutable = (configured, boundaryRoot) => {
+  try {
+    return (0, import_AtomicFileSystemTransport.usableExecutable)(configured, boundaryRoot);
+  } catch (cause) {
+    const reason = cause.message;
+    throw new import_AtomicHelperError.AtomicHelperError({
+      code: "helper_unusable",
+      message: `smithers-jj-export is unusable at SMITHERS_WORKSPACE_JJ_EXPORT_BINARY=${configured}: ${reason}; ${installHint}`
+    });
+  }
+};
+//# sourceMappingURL=AtomicFileSystemExecutable.js.map

package/dist/cjs/internal/AtomicFileSystemExecutable.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/AtomicFileSystemExecutable.ts"],
+  "sourcesContent": ["/**\n * Finds the native filesystem helper embedded in a host, shipped with this package, or built in a\n * source checkout, without accepting an executable from the workspace.\n * @since 1.0.0\n */\n\nimport { createHash, randomBytes } from \"node:crypto\"\nimport {\n  chmodSync,\n  existsSync,\n  lstatSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  realpathSync,\n  renameSync,\n  rmSync,\n  statSync,\n  utimes,\n  utimesSync,\n  writeFileSync\n} from \"node:fs\"\nimport { createRequire } from \"node:module\"\nimport { homedir, tmpdir } from \"node:os\"\nimport { basename, dirname, join, resolve } from \"node:path\"\nimport { fileURLToPath } from \"node:url\"\nimport { inside, usableExecutable } from \"./AtomicFileSystemTransport.ts\"\nimport { AtomicHelperError } from \"./AtomicHelperError.ts\"\n\n/* v8 ignore next -- the packed CJS consumer uses its loader's __dirname; source tests use the ESM loader */\nconst moduleDirectory = typeof __dirname === \"string\" ? __dirname : dirname(fileURLToPath(import.meta.url))\n\n/**\n * The same source module lives one directory deeper after an npm build.\n * @private\n * @since 1.0.0\n */\nexport const resolvePackageRoot = (directory: string): string => {\n  const sourcePackageRoot = resolve(directory, \"../..\")\n  return existsSync(join(sourcePackageRoot, \"package.json\"))\n    ? sourcePackageRoot\n    : resolve(directory, \"../../..\")\n}\n\n/**\n * Finds the installed package even when a host bundles this adapter elsewhere.\n * @private\n * @since 1.0.0\n */\nexport const installedPackageRoot = (modulePath: string, fallback: string): string => {\n  try {\n    return dirname(createRequire(modulePath).resolve(\"@smthrs/platform-node/package.json\"))\n  } catch {\n    // A compiled executable has no installed package; its bootstrap supplies\n    // the embedded helper. Source-only fixtures retain the directory fallback.\n    return fallback\n  }\n}\n\n/**\n * Package containing the currently loaded helper adapter.\n * @private\n * @since 1.0.0\n */\nexport const packageRoot = installedPackageRoot(\n  join(moduleDirectory, \"resolver.cjs\"),\n  resolvePackageRoot(moduleDirectory)\n)\n\n/** Each source's staged copy, and when this process last marked its directory in use. */\nconst staged = new Map<string, { readonly path: string; touchedAt: number }>()\n/**\n * Package roots already staged, and the sources that staging copied. Staging\n * happens once per root per process: a later layer build runs after flows may\n * have planted a helper, so only what existed at the FIRST build is trusted.\n */\nconst stagedRoots = new Set<string>()\nconst trusted = new Set<string>()\nconst installHint = \"install @smthrs/platform-node with its native helper, \" +\n  \"run cargo build --locked --release -p smithers-ffi --bin smithers-jj-export in a source checkout, \" +\n  \"or set SMITHERS_WORKSPACE_JJ_EXPORT_BINARY to its absolute path\"\n\nconst helperName = process.platform === \"win32\" ? \"smithers-jj-export.exe\" : \"smithers-jj-export\"\n\nconst sha256 = (bytes: Uint8Array): string => createHash(\"sha256\").update(bytes).digest(\"hex\")\n\n/** Whether this user owns `info`; Windows has no POSIX owner and relies on the per-user profile ACL. */\nconst ownedByThisUser = (info: { readonly uid: number }): boolean => {\n  const uid = process.getuid?.()\n  return uid === undefined || info.uid === uid\n}\n\n/** Creates or adopts the per-user staging directory, refusing links and other owners. */\nconst privateDirectory = (directory: string): void => {\n  try {\n    mkdirSync(directory, { mode: 0o700 })\n  } catch (cause) {\n    if ((cause as NodeJS.ErrnoException).code !== \"EEXIST\") throw cause\n  }\n  const info = lstatSync(directory)\n  if (!info.isDirectory() || !ownedByThisUser(info)) {\n    throw new AtomicHelperError({\n      code: \"staging_directory_not_private\",\n      message: `atomic helper staging directory is not a private directory: ${directory}`\n    })\n  }\n  chmodSync(directory, 0o700)\n}\n\n/**\n * Whether the staged copy is this user's own single-link file holding exactly\n * the helper's bytes. A planted link, even one with the right bytes, is\n * replaced: rename swaps the directory entry, never the linked inode.\n */\nconst matches = (destination: string, digest: string): boolean => {\n  try {\n    const info = lstatSync(destination)\n    if (!info.isFile() || info.nlink !== 1 || !ownedByThisUser(info)) return false\n    return sha256(readFileSync(destination)) === digest\n  } catch {\n    return false\n  }\n}\n\n/** A staged copy no process has used for this long is removed; use refreshes the directory's time. */\nconst staleMs = 7 * 24 * 60 * 60 * 1000\nconst refreshMs = 60 * 60 * 1000\n\n/** Marks a staging directory in use, at most hourly, so no other process prunes it while this one runs. */\nconst refresh = (copy: { readonly path: string; touchedAt: number }): void => {\n  const now = Date.now()\n  if (now - copy.touchedAt < refreshMs) return\n  copy.touchedAt = now\n  // Best effort and off the request path: a failed touch only risks a later re-stage.\n  utimes(dirname(copy.path), now / 1000, now / 1000, () => {})\n}\n\n/**\n * Removes this user's stale staging directories beside `keep`, and incomplete\n * temporary files left in live directories when a writer exited on a signal.\n */\nconst prune = (base: string, keep: string): void => {\n  const now = Date.now()\n  let names: Array<string>\n  try {\n    names = readdirSync(base)\n  } catch {\n    return\n  }\n  const temporaryPrefix = `.${helperName}.`\n  for (const name of names) {\n    if (!name.startsWith(\".smthrs-atomic-helper-\")) continue\n    const directory = join(base, name)\n    try {\n      const info = lstatSync(directory)\n      if (!info.isDirectory() || !ownedByThisUser(info)) continue\n      if (name !== keep && now - info.mtimeMs > staleMs) {\n        rmSync(directory, { recursive: true, force: true })\n        continue\n      }\n      for (const entry of readdirSync(directory)) {\n        if (!entry.startsWith(temporaryPrefix) || !/^\\d+\\.[0-9a-f]{12}$/.test(entry.slice(temporaryPrefix.length))) {\n          continue\n        }\n        const temporary = join(directory, entry)\n        try {\n          const file = lstatSync(temporary)\n          if (file.isFile() && ownedByThisUser(file) && now - file.mtimeMs > staleMs) {\n            rmSync(temporary, { force: true })\n          }\n        } catch {\n          // A writer or another pruner removed this entry first.\n        }\n      }\n    } catch {\n      // Another process removed or replaced it first.\n    }\n  }\n}\n\nlet embeddedHelper: string | undefined\n\n/**\n * Supplies the build's native asset without touching disk during --help.\n * @private\n * @since 1.0.0\n */\nexport const registerEmbeddedHelper = (source: string): void => {\n  embeddedHelper = source\n}\n\n/**\n * Pin an install inside the workspace before any flow can modify its bytes.\n * @private\n * @since 1.0.0\n */\nexport const outsideWorkspace = (\n  source: string,\n  boundaryRoot: string | undefined,\n  bases: ReadonlyArray<string> = [tmpdir(), homedir()]\n): string => {\n  const cached = staged.get(source)\n  if (cached !== undefined) {\n    if (existsSync(cached.path)) {\n      refresh(cached)\n      return usableExecutable(cached.path, boundaryRoot)\n    }\n    // A newer build's process pruned this copy after a week unused: stage it again.\n    staged.delete(source)\n  }\n  // readFile also supports assets embedded in a Bun executable; copyfile\n  // delegates to the OS, which cannot open its virtual /$bunfs path.\n  const bytes = readFileSync(source)\n  const digest = sha256(bytes)\n  for (const [index, base] of bases.entries()) {\n    const directory = join(base, `.smthrs-atomic-helper-${digest}`)\n    const destination = join(directory, helperName)\n    let temporary: string | undefined\n    try {\n      privateDirectory(directory)\n      // Fresh before it is read, so a concurrent prune passes it by.\n      const now = new Date()\n      utimesSync(directory, now, now)\n      if (!matches(destination, digest)) {\n        // One copy per user and helper: concurrent processes each write a\n        // private temporary file and rename it over the shared name, so a\n        // reader only ever sees a complete copy.\n        temporary = join(directory, `.${helperName}.${process.pid}.${randomBytes(6).toString(\"hex\")}`)\n        writeFileSync(temporary, bytes, { flag: \"wx\", mode: 0o500 })\n        chmodSync(temporary, 0o500)\n        renameSync(temporary, destination)\n        temporary = undefined\n      }\n      const executable = usableExecutable(destination, boundaryRoot)\n      prune(base, `.smthrs-atomic-helper-${digest}`)\n      staged.set(source, { path: executable, touchedAt: now.getTime() })\n      return executable\n    } catch (cause) {\n      if (temporary !== undefined) rmSync(temporary, { force: true })\n      if (index === bases.length - 1) throw cause\n    }\n  }\n  throw new AtomicHelperError({\n    code: \"staging_unavailable\",\n    message: \"no staging location for smithers-jj-export\"\n  })\n}\n\n/** The helper an installed package ships for this platform. */\nconst packagedHelper = (root: string): string => join(root, \"bin\", `${process.platform}-${process.arch}`, helperName)\n\n/** Source-checkout builds, when `root` is this package inside a checkout. */\nconst checkoutHelpers = (root: string): ReadonlyArray<string> => {\n  const checkout = resolve(root, \"../../../..\")\n  return existsSync(join(checkout, \"pnpm-workspace.yaml\"))\n    ? [join(checkout, \"target/release\", helperName), join(checkout, \"target/debug\", helperName)]\n    : []\n}\n\n/**\n * Stages the packaged helper and any source-checkout build the first time a\n * host layer over `root` is built in this process, so the bytes later requests\n * execute are the ones present before any flow ran. Later builds stage\n * nothing: a flow of an earlier run may already have planted a helper by then.\n * A flow that rewrites a workspace-local install or build afterwards changes\n * nothing that is executed. A missing or unusable helper is left for the first\n * request to report.\n * @private\n * @since 1.0.0\n */\nexport const stagePackaged = (root: string): void => {\n  if (stagedRoots.has(root)) return\n  stagedRoots.add(root)\n  const candidate = embeddedHelper ?? packagedHelper(root)\n  try {\n    if (existsSync(candidate) && statSync(candidate).isFile()) {\n      outsideWorkspace(candidate, undefined)\n      trusted.add(candidate)\n    }\n  } catch {\n    // The request path resolves again and reports the refusal it meets.\n  }\n  if (embeddedHelper !== undefined) return\n  for (const build of checkoutHelpers(root)) {\n    try {\n      if (existsSync(build)) {\n        const executable = usableExecutable(build, undefined)\n        outsideWorkspace(executable, undefined)\n        trusted.add(executable)\n      }\n    } catch {\n      // As above: the request path reports it.\n    }\n  }\n}\n\n/**\n * Whether a flow confined to `boundaryRoot` could have supplied what\n * `candidate` runs: the name itself lies inside the workspace (so a flow could\n * have replaced it with a link to any host binary), its directory resolves\n * inside it, or the file it resolves to does.\n */\nconst workspaceSupplied = (candidate: string, source: string, boundaryRoot: string): boolean =>\n  inside(boundaryRoot, resolve(candidate)) ||\n  inside(boundaryRoot, join(realpathSync.native(dirname(candidate)), basename(candidate))) ||\n  inside(boundaryRoot, realpathSync.native(source))\n\n/**\n * Copies `source` to a private directory only when the workspace cannot have\n * supplied its bytes: neither `candidate` nor what it resolves to lies inside\n * the confined workspace, or `source` was staged at the first host build,\n * before any flow ran. A helper, or a link to one, that appeared inside the\n * workspace later is exactly what a flow would plant.\n */\nconst pinned = (candidate: string, source: string, boundaryRoot: string | undefined): string => {\n  if (boundaryRoot !== undefined && !trusted.has(source) && workspaceSupplied(candidate, source, boundaryRoot)) {\n    throw new AtomicHelperError({\n      code: \"helper_inside_workspace\",\n      message: `atomic helper executable must live outside the confined workspace: ${candidate} ` +\n        \"was not present when the host was built\"\n    })\n  }\n  return outsideWorkspace(source, boundaryRoot)\n}\n\n/**\n * Select only trusted package or checkout locations; never consult PATH or cwd.\n * @private\n * @since 1.0.0\n */\nexport const resolveDefaultExecutable = (\n  root: string,\n  boundaryRoot: string | undefined,\n  fallback = \"/usr/local/bin/smithers-jj-export\"\n): string => {\n  if (embeddedHelper !== undefined) return outsideWorkspace(embeddedHelper, boundaryRoot)\n  const candidates = [packagedHelper(root), ...checkoutHelpers(root), fallback]\n  for (const [index, candidate] of candidates.entries()) {\n    if (!existsSync(candidate)) continue\n    if (index === 0) {\n      if (!statSync(candidate).isFile()) {\n        throw new AtomicHelperError({\n          code: \"helper_not_regular_file\",\n          message: `packaged atomic helper is not a regular file: ${candidate}`\n        })\n      }\n      // npm/pnpm tarballs may store package files without executable bits.\n      return pinned(candidate, candidate, boundaryRoot)\n    }\n    const executable = usableExecutable(candidate, undefined)\n    return boundaryRoot !== undefined && workspaceSupplied(candidate, executable, boundaryRoot)\n      ? pinned(candidate, executable, boundaryRoot)\n      : executable\n  }\n  throw new AtomicHelperError({\n    code: \"helper_missing\",\n    message: `smithers-jj-export is missing; ${installHint} (searched ${candidates.join(\", \")})`\n  })\n}\n\n/**\n * The helper `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY` names, refused with the same\n * install hint as a missing one.\n * @private\n * @since 1.0.0\n */\nexport const resolveConfiguredExecutable = (configured: string, boundaryRoot: string | undefined): string => {\n  try {\n    return usableExecutable(configured, boundaryRoot)\n  } catch (cause) {\n    // `usableExecutable` and the node:fs calls it makes throw only Error objects.\n    const reason = (cause as Error).message\n    throw new AtomicHelperError({\n      code: \"helper_unusable\",\n      message:\n        `smithers-jj-export is unusable at SMITHERS_WORKSPACE_JJ_EXPORT_BINARY=${configured}: ${reason}; ${installHint}`\n    })\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/internal/AtomicFileSystemProtocol.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The adapter's half of the helper wire protocol: the request frame it sends,
+ * the response frame it accepts, and the typed value or `PlatformError` each
+ * operation's answer decodes to. Every check a helper answer has to pass lives
+ * here, so a malformed or hostile response fails closed in one place.
+ * @since 1.0.0
+ */
+import type * as KernelFileSystem from "@smthrs/kernel/FileSystem";
+import { Effect, PlatformError } from "effect";
+import type { Limits } from "../AtomicFileSystem.ts";
+/**
+ * One helper answer: a value, or a rejection carrying the errno name and the
+ * syscall the helper observed.
+ * @private
+ * @since 1.0.0
+ */
+export interface HelperResult {
+    readonly ok: boolean;
+    readonly value?: unknown;
+    readonly code?: string | null;
+    readonly syscall?: string | null;
+    readonly badArgument?: boolean;
+    readonly message?: string;
+}
+/**
+ * The `module` every `PlatformError` this adapter reports names.
+ * @private
+ * @since 1.0.0
+ */
+export declare const moduleName = "AtomicFileSystem";
+/**
+ * Room for `flows-atomic/1 <digits>\n` above the payload ceiling.
+ * @private
+ * @since 1.0.0
+ */
+export declare const frameHeaderBytes = 64;
+/**
+ * A request framed for the helper: one atomic operation, or one member of a
+ * batch. The two protocols name their operands differently — a batch `glob`
+ * carries the `path` it expands where an atomic `glob` carries a `pattern` —
+ * so the reporting helpers read the operand by narrowing on the operation
+ * rather than by taking whichever of three optional fields happened to be set.
+ * @private
+ * @since 1.0.0
+ */
+export type FramedRequest = KernelFileSystem.AtomicRequest | KernelFileSystem.AtomicBatchRequest;
+/**
+ * A rejection carrying no errno is a transport or host failure — an absent
+ * helper, a killed child, output that is not a helper result — and stays
+ * `PermissionDenied` so the boundary fails closed rather than reporting a
+ * benign-looking reason for an operation that never ran.
+ * @private
+ * @since 1.0.0
+ */
+export declare const failure: (request: FramedRequest, cause: unknown, rejection?: HelperResult) => PlatformError.PlatformError;
+/**
+ * Frames a serialized request: the protocol tag, the body length, and the
+ * request, content, and response ceilings the helper enforces on its side,
+ * then the body.
+ * @private
+ * @since 1.0.0
+ */
+export declare const encode: (body: Buffer, limits: Limits) => Buffer;
+/**
+ * Decodes one complete response frame into a result envelope. Anything that
+ * is not exactly one well-formed frame within the response ceiling throws.
+ * @private
+ * @since 1.0.0
+ */
+export declare const decode: (frame: Buffer, limits: Limits) => HelperResult;
+/**
+ * Converts a successful helper value into the result the request's operation
+ * promises, and throws when the value does not have that shape.
+ * @private
+ * @since 1.0.0
+ */
+export declare const convert: <A>(request: FramedRequest, value: unknown, limits: Limits) => Effect.Effect<A, PlatformError.PlatformError>;
+//# sourceMappingURL=AtomicFileSystemProtocol.d.ts.map

package/dist/cjs/internal/AtomicFileSystemProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AtomicFileSystemProtocol.d.ts","sourceRoot":"","sources":["../../../src/internal/AtomicFileSystemProtocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,gBAAgB,MAAM,2BAA2B,CAAA;AAClE,OAAO,EAAE,MAAM,EAA2B,aAAa,EAAU,MAAM,QAAQ,CAAA;AAG/E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAGpD;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,qBAAqB,CAAA;AAG5C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAgClC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC,aAAa,GAAG,gBAAgB,CAAC,kBAAkB,CAAA;AAYhG;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAClB,SAAS,aAAa,EACtB,OAAO,OAAO,EACd,YAAY,YAAY,KACvB,aAAa,CAAC,aAiChB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,MAMrD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,YAmCtD,CAAA;AA0JD;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EACvB,SAAS,aAAa,EACtB,OAAO,OAAO,EACd,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,aAAa,CA0I9C,CAAA"}