faberun 0.19.0 → 0.19.2

package/src/run/node-store.mjs

@@ -11,6 +11,7 @@ import { validateNodeSnapshot } from "../contract/snapshot.mjs";
 
 /** @typedef {ReturnType<typeof import("./lock.mjs").acquire>} LockHandle */
 /** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
 
 const NODES_DIR_NAME = "nodes";
 
@@ -60,3 +61,35 @@ export function listNodeSnapshots(runDir) {
     throw error;
   }
 }
+
+/**
+ * The persisted node snapshots of one run.
+ *
+ * `tolerateMissing` returns only the snapshots that exist instead of refusing
+ * the run. For resume and supervise a node the contract declares and the run
+ * never persisted is corruption and stays fatal; for `cancel` it is the
+ * ordinary shape of what is being cancelled. A launch writes `contract.json`
+ * first and can die before it writes any node -- probing providers, shelling
+ * out to git, claiming the run ref -- and the directory then holds a
+ * contract, an occupied ref and no node state at all. Such a node started
+ * nothing, holds no invocation and no worktree, so there is nothing to
+ * terminate and only the git names to release, which is what cancel is for.
+ *
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {{tolerateMissing?: boolean}} [options]
+ * @returns {NodeSnapshot[]}
+ */
+export function readRunNodes(runDir, contract, options = {}) {
+  const names = listNodeSnapshots(runDir);
+  const expected = new Map(contract.nodes.map((node) => [`${node.id}.json`, node]));
+  for (const name of names) if (!expected.has(name)) throw new TypeError(`unexpected persisted node snapshot ${name}`);
+  return contract.nodes.flatMap((node) => {
+    const name = `${node.id}.json`;
+    if (!names.includes(name)) {
+      if (options.tolerateMissing === true) return [];
+      throw new TypeError(`missing persisted node snapshot ${name}`);
+    }
+    return [validateNodeSnapshot(readNodeSnapshot(runDir, node.id), node)];
+  });
+}

package/src/util.mjs

@@ -229,3 +229,49 @@ export function readJsonTolerant(path) {
 export function finite(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+
+/**
+ * Split a command string into the words a POSIX shell would pass as argv, for
+ * the two readers handed a command as a display string rather than an argv: a
+ * Definition of Done `command` proof, whose words `engine/scope.mjs` matches
+ * against the files the node wrote, and the node:test filters one declares
+ * (`engine/judge-gate.mjs`). Quotes group and are stripped; whitespace
+ * outside them separates.
+ *
+ * Deliberately not a shell: no expansion, no substitution, no operators, and
+ * no backslash escape -- on Windows a backslash is a path separator and
+ * `C:\Users\x` must survive this intact. The question both callers ask is
+ * "which words does this command name", and a quoted path holding a space is
+ * one word: splitting it on whitespace produced two fragments that matched no
+ * file, so a proof naming a real path read as naming none.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function shellWords(text) {
+  /** @type {string[]} */
+  const words = [];
+  /** @type {string|null} */
+  let current = null;
+  /** @type {string|null} */
+  let quote = null;
+  for (const character of text) {
+    if (quote === null && /\s/u.test(character)) {
+      if (current !== null) words.push(current);
+      current = null;
+      continue;
+    }
+    if (quote === null && (character === '"' || character === "'")) {
+      quote = character;
+      current ??= "";
+      continue;
+    }
+    if (quote === character) {
+      quote = null;
+      continue;
+    }
+    current = (current ?? "") + character;
+  }
+  if (current !== null) words.push(current);
+  return words;
+}