mandrel-platform 1.4.2 → 1.5.1

package/scripts/lib/actions-expression.mjs

@@ -0,0 +1,271 @@
+/**
+ * actions-expression.mjs — a minimal GitHub Actions expression evaluator.
+ *
+ * Extracted from check-toolchain-cache-default.test.mjs (Story #364) when a
+ * second guard needed it (Story #421). It exists because **a `grep` is not an
+ * acceptance criterion for a workflow expression**: string-matching pins the
+ * spelling, not the behaviour, and both expression defects this repo has
+ * shipped read correctly and evaluated wrong. Extract the real expression from
+ * the YAML and RUN it.
+ *
+ * Supported surface — only what the guarded expressions use: string literals,
+ * `inputs.<name>` / `inputs['<name>']` reads, `==`/`!=`, `&&`/`||`,
+ * parentheses, and `contains()`, `startsWith()`, `format()`, `fromJSON()`.
+ *
+ * The semantics that matter, and that a hand-read gets wrong:
+ *
+ *   - `a && b` yields `b` when `a` is truthy, else `a`.
+ *   - `a || b` yields `a` when `a` is truthy, else `b`.
+ *     Both yield OPERANDS, not booleans.
+ *   - EVERY non-empty string is truthy — including the string `'false'`.
+ *   - Arrays and objects are truthy. GitHub documents the falsy set as exactly
+ *     `false`, `0`, `-0`, `''`, `null`; an array is not in it.
+ *   - String comparison is case-insensitive.
+ *
+ * ## On short-circuiting
+ *
+ * This evaluator parses to an AST first and evaluates `&&`/`||` lazily, which
+ * is the standard semantic. GitHub does NOT document whether its own evaluator
+ * short-circuits, so a guarded expression **must not depend on it** — never
+ * place a throwing call (`fromJSON` on caller-controlled text) in a branch that
+ * is only conditionally reached. Wrap the conditional instead:
+ *
+ *     fromJSON(cond && '<json>' || '<json>')     ← safe under either semantic
+ *     cond && fromJSON(x) || x                   ← safe ONLY if lazy
+ *
+ * Evaluating lazily here while requiring the safe shape in the workflows means
+ * the guard cannot bless an expression whose correctness rests on an
+ * unverified assumption about GitHub's evaluator.
+ *
+ * Errors are thrown as plain `Error`s; nothing here depends on a test framework.
+ */
+
+/** Actions truthiness — NOT JavaScript's. */
+export function truthy(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0;
+  if (typeof v === "string") return v !== "";
+  return v !== null && v !== undefined;
+}
+
+/** Actions comparison: case-insensitive for strings. */
+export function looseEqual(a, b) {
+  if (typeof a === "string" && typeof b === "string") {
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  return a === b;
+}
+
+function fail(message) {
+  throw new Error(`[actions-expression] ${message}`);
+}
+
+const FUNCTIONS = new Map([
+  ["contains", 2],
+  ["startsWith", 2],
+  ["endsWith", 2],
+  ["fromJSON", 1],
+]);
+
+/** Parse `expr` into an AST. Exported for tests that assert on shape. */
+export function parse(expr) {
+  let i = 0;
+
+  const ws = () => {
+    while (i < expr.length && /\s/.test(expr[i])) i++;
+  };
+  const eat = (token) => {
+    ws();
+    if (expr.startsWith(token, i)) {
+      i += token.length;
+      return true;
+    }
+    return false;
+  };
+
+  function parseOr() {
+    let left = parseAnd();
+    for (;;) {
+      ws();
+      if (!eat("||")) return left;
+      left = { kind: "or", left, right: parseAnd() };
+    }
+  }
+
+  function parseAnd() {
+    let left = parseCompare();
+    for (;;) {
+      ws();
+      if (!eat("&&")) return left;
+      left = { kind: "and", left, right: parseCompare() };
+    }
+  }
+
+  function parseCompare() {
+    const left = parsePrimary();
+    ws();
+    if (eat("!=")) return { kind: "ne", left, right: parsePrimary() };
+    if (eat("==")) return { kind: "eq", left, right: parsePrimary() };
+    return left;
+  }
+
+  function parsePrimary() {
+    ws();
+    if (eat("(")) {
+      const node = parseOr();
+      ws();
+      if (!eat(")")) fail(`unbalanced parenthesis at ${i} in: ${expr}`);
+      return node;
+    }
+    if (expr[i] === "'") {
+      i++;
+      let out = "";
+      while (i < expr.length) {
+        if (expr[i] === "'" && expr[i + 1] === "'") {
+          out += "'";
+          i += 2;
+          continue;
+        }
+        if (expr[i] === "'") {
+          i++;
+          return { kind: "literal", value: out };
+        }
+        out += expr[i++];
+      }
+      fail(`unterminated string literal in: ${expr}`);
+    }
+    for (const [name, arity] of FUNCTIONS) {
+      if (!expr.startsWith(`${name}(`, i)) continue;
+      i += `${name}(`.length;
+      const args = [parseOr()];
+      while (args.length < arity) {
+        ws();
+        if (!eat(",")) fail(`${name}() expects ${arity} arguments in: ${expr}`);
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed ${name}() in: ${expr}`);
+      return { kind: "call", name, args };
+    }
+    // `format()` is variadic, so it is parsed separately from the fixed-arity table.
+    if (expr.startsWith("format(", i)) {
+      i += "format(".length;
+      const args = [parseOr()];
+      for (;;) {
+        ws();
+        if (!eat(",")) break;
+        args.push(parseOr());
+      }
+      ws();
+      if (!eat(")")) fail(`unclosed format() in: ${expr}`);
+      return { kind: "call", name: "format", args };
+    }
+    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
+    if (!ident) fail(`unparseable token at ${i} in: ${expr}`);
+    i += ident[0].length;
+    const raw = ident[0];
+    if (raw === "true") return { kind: "literal", value: true };
+    if (raw === "false") return { kind: "literal", value: false };
+    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
+    const dotted = raw.match(/^inputs\.(.+)$/);
+    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
+    if (key === null) fail(`unsupported context read \`${raw}\` in: ${expr}`);
+    return { kind: "input", key };
+  }
+
+  const ast = parseOr();
+  ws();
+  if (i !== expr.length) fail(`trailing tokens at ${i} in: ${expr}`);
+  return ast;
+}
+
+function applyFormat(args) {
+  const template = String(args[0]);
+  const rest = args.slice(1);
+  let out = "";
+  for (let k = 0; k < template.length; k++) {
+    const ch = template[k];
+    if (ch === "{" && template[k + 1] === "{") {
+      out += "{";
+      k++;
+    } else if (ch === "}" && template[k + 1] === "}") {
+      out += "}";
+      k++;
+    } else if (ch === "{") {
+      const close = template.indexOf("}", k);
+      if (close === -1) fail(`unclosed format placeholder in: ${template}`);
+      const idx = Number(template.slice(k + 1, close));
+      if (!Number.isInteger(idx)) fail(`non-numeric format placeholder in: ${template}`);
+      out += rest[idx] === undefined ? "" : String(rest[idx]);
+      k = close;
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+function evalNode(node, inputs) {
+  switch (node.kind) {
+    case "literal":
+      return node.value;
+    case "input":
+      if (!(node.key in inputs)) {
+        fail(`expression reads \`inputs.${node.key}\`, not provided by the caller`);
+      }
+      return inputs[node.key];
+    case "and": {
+      // Lazy on purpose — see the module header's note on short-circuiting.
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? evalNode(node.right, inputs) : left;
+    }
+    case "or": {
+      const left = evalNode(node.left, inputs);
+      return truthy(left) ? left : evalNode(node.right, inputs);
+    }
+    case "eq":
+      return looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "ne":
+      return !looseEqual(evalNode(node.left, inputs), evalNode(node.right, inputs));
+    case "call": {
+      const args = node.args.map((a) => evalNode(a, inputs));
+      if (node.name === "format") return applyFormat(args);
+      const [a, b] = args;
+      if (node.name === "contains") {
+        // Substring on a string haystack; exact-item match on an array one.
+        if (Array.isArray(a)) return a.some((item) => looseEqual(item, b));
+        return String(a).toLowerCase().includes(String(b).toLowerCase());
+      }
+      if (node.name === "startsWith") {
+        return String(a).toLowerCase().startsWith(String(b).toLowerCase());
+      }
+      if (node.name === "endsWith") {
+        return String(a).toLowerCase().endsWith(String(b).toLowerCase());
+      }
+      if (node.name === "fromJSON") {
+        try {
+          return JSON.parse(String(a));
+        } catch {
+          // A parse failure is a HARD expression error in Actions — the run
+          // fails rather than yielding null, which is what makes a malformed
+          // `runner` value loud instead of silently unmatchable.
+          fail(`fromJSON() could not parse ${JSON.stringify(String(a))} in this expression`);
+        }
+      }
+      return fail(`unsupported function \`${node.name}\``);
+    }
+    default:
+      return fail(`unsupported node kind \`${node.kind}\``);
+  }
+}
+
+/**
+ * Evaluate `expr` (the body BETWEEN `${{` and `}}`) against `inputs`.
+ *
+ * @param {string} expr
+ * @param {Record<string, unknown>} inputs values for `inputs.*` reads
+ * @returns {unknown} the resulting operand — a string, boolean, or array
+ */
+export function evaluate(expr, inputs) {
+  return evalNode(parse(expr), inputs);
+}

package/scripts/lib/actions-expression.test.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * actions-expression.test.mjs — the evaluator must be trustworthy before it
+ * can judge a workflow (Story #421).
+ *
+ * These assertions are the reason the evaluator exists: every one of them is a
+ * place where Actions semantics diverge from JavaScript's, and where a
+ * hand-read of an expression gets the wrong answer.
+ *
+ * Run: node --test scripts/lib/actions-expression.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { evaluate, truthy } from "./actions-expression.mjs";
+
+test("`&&` and `||` yield OPERANDS, not booleans", () => {
+  assert.equal(evaluate("true && 'kept'", {}), "kept");
+  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
+  assert.equal(evaluate("'a' || 'b'", {}), "a");
+});
+
+test("every non-empty string is truthy — including the string 'false'", () => {
+  // The trap the toolchain-cache expression depends on: an explicitly-pinned
+  // 'false' must survive the first arm of the ternary rather than falling
+  // through to the derivation.
+  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
+  assert.equal(truthy("false"), true);
+  assert.equal(truthy(""), false);
+});
+
+test("arrays are truthy — the property the runs-on normalization rests on", () => {
+  // GitHub documents the falsy set as exactly false, 0, -0, '', null. An array
+  // is not in it, so a parsed label array carries through `&&` / `||`.
+  assert.equal(truthy([]), true);
+  assert.equal(truthy(["self-hosted"]), true);
+});
+
+test("comparison is case-insensitive", () => {
+  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
+  assert.equal(evaluate("'AUTO' != 'auto'", {}), false);
+});
+
+test("contains() is substring on a string and exact-item on an array", () => {
+  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
+  assert.equal(evaluate("contains(inputs.r, 'self-hosted')", { r: ["self-hosted", "x"] }), true);
+  // Exact-item, NOT substring, once the haystack is an array.
+  assert.equal(evaluate("contains(inputs.r, 'self')", { r: ["self-hosted"] }), false);
+});
+
+test("startsWith() casts to string and is case-insensitive", () => {
+  assert.equal(evaluate("startsWith('[\"a\"]', '[')", {}), true);
+  assert.equal(evaluate("startsWith('ubuntu-latest', '[')", {}), false);
+  assert.equal(evaluate("startsWith('UBUNTU', 'ub')", {}), true);
+});
+
+test("format() substitutes positionally and unescapes doubled braces", () => {
+  assert.equal(evaluate("format('\"{0}\"', inputs.r)", { r: "my-runner" }), '"my-runner"');
+  assert.equal(evaluate("format('{{{0}}}', inputs.r)", { r: "x" }), "{x}");
+});
+
+test("fromJSON() parses arrays and scalars", () => {
+  assert.deepEqual(evaluate("fromJSON('[\"self-hosted\",\"x\"]')", {}), ["self-hosted", "x"]);
+  assert.equal(evaluate("fromJSON('\"bare-label\"')", {}), "bare-label");
+});
+
+test("fromJSON() on malformed input THROWS — it does not yield null", () => {
+  // Load-bearing: in Actions a fromJSON parse failure fails the run. If it
+  // degraded to null here, a malformed `runner` would look like a clean
+  // fallback in the guard while hanging forever in production.
+  assert.throws(() => evaluate("fromJSON('[\"unterminated')", {}), /could not parse/);
+});
+
+test("`&&` / `||` short-circuit, so an unreached branch is never evaluated", () => {
+  // The evaluator is lazy. Guarded workflow expressions must NOT rely on that
+  // (GitHub does not document its own behaviour here) — but modelling it
+  // faithfully keeps the guard honest about what it is asserting.
+  assert.equal(evaluate("false && fromJSON('nonsense') || 'safe'", {}), "safe");
+});
+
+test("an unknown input read is an error, not a silent undefined", () => {
+  assert.throws(() => evaluate("inputs.missing", {}), /not provided by the caller/);
+});

package/scripts/lib/entry-guard.mjs

@@ -0,0 +1,111 @@
+/**
+ * scripts/lib/entry-guard.mjs
+ *
+ * The single direct-invocation ("am I the process entry point?") seam shared
+ * by the `scripts/*.mjs` CLIs. Each of those scripts had grown its own guard,
+ * and they had drifted into three mutually incompatible spellings:
+ *
+ *   1. an identity comparison of the resolved `argv[1]` against the resolved
+ *      pathname of `import.meta.url`;
+ *   2. a string comparison of `import.meta.url` against a `file:` URL built by
+ *      interpolating `argv[1]`;
+ *   3. a suffix test — the resolved `argv[1]` ending with the script basename.
+ *
+ * Spellings 1 and 2 are both broken under pnpm, and broken in the most
+ * dangerous possible way — silently. `import.meta.url` is **realpath-resolved**
+ * by the ESM loader, while `process.argv[1]` is not: it keeps whatever path the
+ * caller typed. pnpm installs every package as a symlink
+ * (`node_modules/<pkg>` → `node_modules/.pnpm/<pkg>@<version>/node_modules/<pkg>`),
+ * so a consumer invoking
+ *
+ *     node node_modules/mandrel-platform/scripts/check-wrangler-baseline.mjs
+ *
+ * compares the symlinked path against the store realpath. They never match, the
+ * guard is false, the CLI never runs, and the process exits 0 having printed
+ * nothing. In a CI log that is indistinguishable from a clean pass — the gate
+ * reports success precisely because it did not run (Story #407, superseding the
+ * consumer report in #406).
+ *
+ * Spelling 2 fails a second way even without a symlink: it string-compares a
+ * URL against an unencoded path, so a relative `argv[1]` (`node scripts/x.mjs`)
+ * or any path needing percent-encoding (a space, a `#`) also misses.
+ *
+ * Spelling 3 is not broken — a path suffix survives realpath resolution — but
+ * it is loose (any file with that basename matches) and it duplicates the
+ * script's own name as a string literal that nothing keeps in sync with a
+ * rename. It is left in place where it already exists; new entry points should
+ * use this helper.
+ *
+ * `isDirectInvocation(importMetaUrl)` resolves BOTH sides through
+ * `realpathSync` so the comparison is symlink-agnostic in either direction. It
+ * is total: it never throws, and answers `false` for every shape that cannot be
+ * a direct invocation (no `argv[1]`, a deleted or unreadable entry path), so
+ * merely importing a module for its exports can never crash on the guard line
+ * and can never be mistaken for running it.
+ *
+ * This module performs no I/O beyond the two realpath probes and reads no
+ * environment, so the sibling `entry-guard.test.mjs` suite exercises it
+ * entirely offline.
+ */
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve a filesystem path through `realpathSync`, falling back to a plain
+ * absolute resolution when the path cannot be realpath'd.
+ *
+ * A path that does not exist has no realpath — `realpathSync` throws ENOENT.
+ * That is a normal, non-exceptional case here (`process.argv[1]` can name a
+ * file that was deleted mid-run, and is absent entirely under `node -e`), so
+ * it degrades to `resolve()` rather than propagating. Two non-existent paths
+ * then still compare equal to themselves, which keeps the guard meaningful
+ * instead of collapsing to a blanket `false`.
+ *
+ * @param {string} candidate Path to canonicalize.
+ * @returns {string} The realpath when resolvable, else the absolute path.
+ */
+function canonicalize(candidate) {
+  const absolute = resolve(candidate);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+/**
+ * Report whether the module identified by `importMetaUrl` is the process entry
+ * point — i.e. whether it was run as `node <this-file>` rather than imported.
+ *
+ * Symlink-safe in both directions: the entry path and the module URL are each
+ * canonicalized through `realpathSync`, so a pnpm-style symlinked
+ * `node_modules` invocation matches its own store realpath.
+ *
+ * Total by construction — never throws. A `file:` URL that cannot be converted
+ * to a path (an `http:`/`data:` specifier, a malformed URL) answers `false`,
+ * because such a module cannot be a filesystem entry point.
+ *
+ * @param {string} importMetaUrl The calling module's `import.meta.url`.
+ * @returns {boolean} True when this module is the direct invocation target.
+ *
+ * @example
+ *   if (isDirectInvocation(import.meta.url)) {
+ *     process.exit(runCli());
+ *   }
+ */
+export function isDirectInvocation(importMetaUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry === '') return false;
+  if (typeof importMetaUrl !== 'string' || importMetaUrl === '') return false;
+
+  let modulePath;
+  try {
+    modulePath = fileURLToPath(importMetaUrl);
+  } catch {
+    return false;
+  }
+
+  return canonicalize(entry) === canonicalize(modulePath);
+}

package/scripts/lib/entry-guard.test.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * entry-guard.test.mjs — node:test suite for the shared direct-invocation
+ * guard (`scripts/lib/entry-guard.mjs`, Story #407).
+ *
+ * The load-bearing case is the symlinked one: pnpm installs packages as
+ * symlinks, and the guard spelling this helper replaces compared a
+ * realpath-resolved `import.meta.url` against an unresolved `process.argv[1]`.
+ * Under pnpm those never matched, so the CLI never ran and the process exited
+ * 0 having printed nothing — a silent pass. Every assertion below that builds
+ * a symlink exists to keep that specific regression dead.
+ *
+ * Offline: the suite only creates files and symlinks under a temp dir and
+ * swaps `process.argv[1]`, which it restores after each case.
+ *
+ * Run: node --test scripts/lib/entry-guard.test.mjs
+ */
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { isDirectInvocation } from './entry-guard.mjs';
+
+/**
+ * Run `fn` with `process.argv[1]` swapped to `entry`, restoring it after.
+ *
+ * @param {string | undefined} entry Value to install at `process.argv[1]`.
+ * @param {() => void} fn Body to run under the swapped argv.
+ */
+function withArgv(entry, fn) {
+  const original = process.argv[1];
+  if (entry === undefined) {
+    process.argv.splice(1, 1);
+  } else {
+    process.argv[1] = entry;
+  }
+  try {
+    fn();
+  } finally {
+    process.argv[1] = original;
+  }
+}
+
+/**
+ * Build a temp dir holding `store/pkg/scripts/cli.mjs` plus a `link` symlink
+ * pointing at `store/pkg` — the shape pnpm's `node_modules` produces.
+ *
+ * @returns {{ dir: string, realScript: string, linkedScript: string }}
+ */
+function makeSymlinkedPackage() {
+  const dir = mkdtempSync(join(tmpdir(), 'entry-guard-test-'));
+  const pkg = join(dir, 'store', 'pkg');
+  mkdirSync(join(pkg, 'scripts'), { recursive: true });
+  const realScript = join(pkg, 'scripts', 'cli.mjs');
+  writeFileSync(realScript, '// fixture\n');
+  const link = join(dir, 'link');
+  symlinkSync(pkg, link, 'dir');
+  return { dir, realScript, linkedScript: join(link, 'scripts', 'cli.mjs') };
+}
+
+// ---------------------------------------------------------------------------
+// The regression this helper exists for
+// ---------------------------------------------------------------------------
+
+test('isDirectInvocation matches when the entry path traverses a symlink', () => {
+  const { dir, realScript, linkedScript } = makeSymlinkedPackage();
+  try {
+    // The module was loaded through its realpath (what the ESM loader does),
+    // while argv[1] kept the symlinked path (what the caller typed). This is
+    // exactly the pnpm shape that used to answer false.
+    withArgv(linkedScript, () => {
+      assert.equal(
+        isDirectInvocation(pathToFileURL(realScript).href),
+        true,
+        'a symlinked invocation must still count as direct',
+      );
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('isDirectInvocation matches with the symlink on the module side too', () => {
+  const { dir, realScript, linkedScript } = makeSymlinkedPackage();
+  try {
+    withArgv(realScript, () => {
+      assert.equal(isDirectInvocation(pathToFileURL(linkedScript).href), true);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Ordinary direct / imported cases
+// ---------------------------------------------------------------------------
+
+test('isDirectInvocation matches an unsymlinked direct invocation', () => {
+  const { dir, realScript } = makeSymlinkedPackage();
+  try {
+    withArgv(realScript, () => {
+      assert.equal(isDirectInvocation(pathToFileURL(realScript).href), true);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('isDirectInvocation resolves a relative entry path against cwd', () => {
+  withArgv('scripts/lib/entry-guard.test.mjs', () => {
+    const absolute = join(process.cwd(), 'scripts/lib/entry-guard.test.mjs');
+    assert.equal(isDirectInvocation(pathToFileURL(absolute).href), true);
+  });
+});
+
+test('isDirectInvocation answers false when another module is the entry', () => {
+  const { dir, realScript } = makeSymlinkedPackage();
+  try {
+    const sibling = join(dir, 'store', 'pkg', 'scripts', 'other.mjs');
+    writeFileSync(sibling, '// fixture\n');
+    withArgv(sibling, () => {
+      assert.equal(isDirectInvocation(pathToFileURL(realScript).href), false);
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Totality — the guard must never throw on an import
+// ---------------------------------------------------------------------------
+
+test('isDirectInvocation answers false when argv[1] is absent', () => {
+  withArgv(undefined, () => {
+    assert.equal(isDirectInvocation(import.meta.url), false);
+  });
+});
+
+test('isDirectInvocation answers false for an empty argv[1]', () => {
+  withArgv('', () => {
+    assert.equal(isDirectInvocation(import.meta.url), false);
+  });
+});
+
+test('isDirectInvocation tolerates an entry path that does not exist', () => {
+  const missing = join(tmpdir(), 'entry-guard-does-not-exist-407', 'cli.mjs');
+  withArgv(missing, () => {
+    assert.doesNotThrow(() => isDirectInvocation(import.meta.url));
+    assert.equal(isDirectInvocation(import.meta.url), false);
+    // A non-existent path still compares equal to itself rather than
+    // collapsing to a blanket false.
+    assert.equal(isDirectInvocation(pathToFileURL(missing).href), true);
+  });
+});
+
+test('isDirectInvocation answers false for a non-file module URL', () => {
+  withArgv('/tmp/whatever.mjs', () => {
+    assert.equal(isDirectInvocation('https://example.com/cli.mjs'), false);
+    assert.equal(isDirectInvocation('data:text/javascript,0'), false);
+  });
+});
+
+test('isDirectInvocation answers false for a missing or malformed URL', () => {
+  withArgv('/tmp/whatever.mjs', () => {
+    assert.equal(isDirectInvocation(''), false);
+    assert.equal(isDirectInvocation(/** @type {any} */ (undefined)), false);
+    assert.equal(isDirectInvocation('not a url'), false);
+  });
+});

package/scripts/platform-repair.mjs

@@ -77,6 +77,8 @@ import {
 import { defaultGhRunner } from "./lib/gh-json.mjs";
 import { parseSemver } from "./lib/semver-duration.mjs";
 
+import { isDirectInvocation } from './lib/entry-guard.mjs';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // The stable head branch every repair PR is opened from. Keying idempotency off
@@ -782,9 +784,9 @@ export function runCli({
   return 0;
 }
 
-// Direct-invocation guard (matches the repo's other scripts/*.mjs entry style).
-const invokedDirectly =
-  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
-if (invokedDirectly) {
+// Direct-invocation guard — symlink-safe via the shared seam (Story #407):
+// comparing an unresolved argv[1] against a realpath-resolved
+// import.meta.url silently never matches under pnpm's symlinked node_modules.
+if (isDirectInvocation(import.meta.url)) {
   process.exit(runCli());
 }