mandrel-platform 1.4.1 → 1.5.0

package/scripts/check-wrangler-baseline.test.mjs

@@ -11,9 +11,17 @@
  */
 
 import assert from 'node:assert/strict';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  symlinkSync,
+  rmSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, test } from 'node:test';
 import {
   parseArgv,
@@ -452,3 +460,252 @@ test('runCli --help prints usage and exits 0 without touching the filesystem', (
   assert.equal(exit, 0);
   assert.match(streams.out, /check-wrangler-baseline\.mjs/);
 });
+
+// ---------------------------------------------------------------------------
+// JSONC tolerance — trailing commas, and string contents left alone (#407)
+// ---------------------------------------------------------------------------
+
+test('parseJsonc tolerates trailing commas in objects and arrays', () => {
+  const text = `{
+  "name": "web",
+  "analytics_engine_datasets": [
+    { "binding": "AE", "dataset": "events", },
+  ],
+}`;
+  assert.deepEqual(parseJsonc(text), {
+    name: 'web',
+    analytics_engine_datasets: [{ binding: 'AE', dataset: 'events' }],
+  });
+});
+
+test('parseJsonc tolerates a trailing comma separated by a comment', () => {
+  const text = '{ "a": [1, 2, /* done */ ], }';
+  assert.deepEqual(parseJsonc(text), { a: [1, 2] });
+});
+
+test('parseJsonc leaves string contents byte-identical', () => {
+  // Each of these would be corrupted by a regex-based comment/comma stripper:
+  // `,}` and `,]` look like trailing commas, and `//` looks like a comment
+  // even when it is not preceded by a scheme colon.
+  const text = JSON.stringify({
+    braces: 'a,} b,] c',
+    slashes: 'a//b',
+    url: 'https://example.com/x',
+    block: 'a/*b*/c',
+  });
+  assert.deepEqual(parseJsonc(text), {
+    braces: 'a,} b,] c',
+    slashes: 'a//b',
+    url: 'https://example.com/x',
+    block: 'a/*b*/c',
+  });
+});
+
+test('parseJsonc still strips real comments outside strings', () => {
+  const text = `{
+  // line comment
+  "logpush": true, /* block */
+  "name": "x"
+}`;
+  assert.deepEqual(parseJsonc(text), { logpush: true, name: 'x' });
+});
+
+test('parseJsonc reports parse-error positions against the original offsets', () => {
+  // Comments and trailing commas are blanked in place, never deleted, so a
+  // position in the error message still points at the operator's file.
+  const text = '{\n  // a comment\n  "a": 1\n  "b": 2\n}';
+  assert.throws(
+    () => parseJsonc(text),
+    (err) => /position (2[0-9]|3[0-9])/.test(err.message),
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Advisory mode is a promise about exit codes, not about findings (#407)
+// ---------------------------------------------------------------------------
+
+test('runCli exits 0 on an unparseable config with --warn-only', () => {
+  writeFileSync(join(tmpDir, 'wrangler.jsonc'), '{ not valid json');
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--warn-only'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+  });
+  assert.equal(exit, 0, 'advisory mode must never hard-fail on config content');
+  assert.match(streams.err, /failed to parse/);
+});
+
+test('runCli --json emits a parseError envelope instead of dying silently', () => {
+  writeFileSync(join(tmpDir, 'wrangler.jsonc'), '{ not valid json');
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--json', '--warn-only'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+  });
+  assert.equal(exit, 0);
+  const envelope = JSON.parse(streams.out);
+  assert.equal(envelope.kind, 'wrangler-baseline-report');
+  assert.equal(envelope.found, true);
+  assert.ok(envelope.parseError, 'the envelope names why the config was unusable');
+});
+
+test('runCli reads a trailing-comma wrangler.jsonc end to end', () => {
+  writeFileSync(
+    join(tmpDir, 'wrangler.jsonc'),
+    `{
+  "compatibility_date": "2026-06-15",
+  "logpush": true,
+  "env": { "production": { "logpush": true, }, },
+  "analytics_engine_datasets": [{ "binding": "AE", "dataset": "events", },],
+}`,
+  );
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: [],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+    now: new Date('2026-07-01T00:00:00Z'),
+  });
+  assert.equal(exit, 0, streams.out + streams.err);
+});
+
+// ---------------------------------------------------------------------------
+// The consumer end state reported in #406 (Turborepo + declared exception)
+// ---------------------------------------------------------------------------
+
+test('runCli renders a declared exception as EXCEPTED while still reporting a real violation', () => {
+  // domio's shape: the Worker config lives outside the repo root, uses
+  // trailing commas throughout, declares an analytics-engine opt-out, and has
+  // a genuinely stale compatibility_date.
+  mkdirSync(join(tmpDir, 'apps', 'web'), { recursive: true });
+  writeFileSync(
+    join(tmpDir, 'apps', 'web', 'wrangler.jsonc'),
+    `{
+  // Worker config for the web app
+  "name": "web",
+  "compatibility_date": "2025-01-01",
+  "logpush": true,
+  "env": { "production": { "logpush": true, }, },
+  "mandrel": {
+    "wranglerBaselineExceptions": {
+      "analytics-engine": "no telemetry sink for this static-asset Worker",
+    },
+  },
+}`,
+  );
+  const streams = noopStreams();
+  const exit = runCli({
+    argv: ['--file', 'apps/web/wrangler.jsonc', '--json'],
+    cwd: tmpDir,
+    stdout: streams.stdout,
+    stderr: streams.stderr,
+    now: new Date('2026-08-29T00:00:00Z'),
+  });
+
+  const envelope = JSON.parse(streams.out);
+  const analytics = envelope.findings.find((f) => f.id === 'analytics-engine');
+  assert.equal(analytics.excepted, true, 'the declared opt-out is honoured');
+  assert.ok(
+    !envelope.violations.some((v) => v.id === 'analytics-engine'),
+    'an excepted rule is absent from violations',
+  );
+  assert.ok(
+    envelope.violations.some((v) => v.id === 'compat-date-stale'),
+    'a genuine staleness violation is still reported',
+  );
+  assert.equal(exit, 1, 'a real un-excepted violation still fails in blocking mode');
+});
+
+// ---------------------------------------------------------------------------
+// Direct-invocation guard — spawned as a SUBPROCESS through a symlink (#407)
+//
+// Every other test here imports runCli, which is exactly why the guard bug
+// survived: the guard line only runs when the file is the process entry point.
+// These cases spawn it the way a pnpm consumer's CI does.
+// ---------------------------------------------------------------------------
+
+const REPO_ROOT = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * Spawn the CLI at `scriptPath` with `cwd`, returning the child result.
+ *
+ * @param {string} scriptPath Path to invoke (possibly through a symlink).
+ * @param {string[]} args CLI args.
+ * @param {string} cwd Working directory for the child.
+ */
+function runScript(scriptPath, args, cwd) {
+  return spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd,
+    encoding: 'utf-8',
+  });
+}
+
+test('the CLI runs when invoked through a pnpm-style symlinked node_modules', () => {
+  // node_modules/mandrel-platform -> <repo root>, the shape pnpm installs.
+  const nodeModules = join(tmpDir, 'node_modules');
+  mkdirSync(nodeModules, { recursive: true });
+  symlinkSync(REPO_ROOT, join(nodeModules, 'mandrel-platform'), 'dir');
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+
+  const linked = join(
+    nodeModules,
+    'mandrel-platform',
+    'scripts',
+    'check-wrangler-baseline.mjs',
+  );
+  const result = runScript(linked, ['--max-age-days', '90'], tmpDir);
+
+  assert.notEqual(
+    result.stdout.trim(),
+    '',
+    'a symlinked invocation must produce output, not a silent pass',
+  );
+  assert.match(result.stdout, /wrangler-baseline/);
+  assert.equal(result.status, 1, 'a violating config exits non-zero in blocking mode');
+});
+
+test('a symlinked invocation honours --warn-only rather than exiting silently', () => {
+  const nodeModules = join(tmpDir, 'node_modules');
+  mkdirSync(nodeModules, { recursive: true });
+  symlinkSync(REPO_ROOT, join(nodeModules, 'mandrel-platform'), 'dir');
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+
+  const linked = join(
+    nodeModules,
+    'mandrel-platform',
+    'scripts',
+    'check-wrangler-baseline.mjs',
+  );
+  const result = runScript(linked, ['--max-age-days', '90', '--warn-only'], tmpDir);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /violation/i, 'advisory mode still reports the findings');
+});
+
+test('the CLI still runs when invoked through its real path', () => {
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+  const direct = join(REPO_ROOT, 'scripts', 'check-wrangler-baseline.mjs');
+  const result = runScript(direct, ['--max-age-days', '90'], tmpDir);
+  assert.match(result.stdout, /wrangler-baseline/);
+  assert.equal(result.status, 1);
+});
+
+test('importing the module does not execute the CLI', () => {
+  // The guard must be false when the entry point is some other script.
+  const probe = join(tmpDir, 'probe.mjs');
+  const target = join(REPO_ROOT, 'scripts', 'check-wrangler-baseline.mjs');
+  writeFileSync(
+    probe,
+    `await import(${JSON.stringify(pathToFileURL(target).href)});\nconsole.log('IMPORT-OK');\n`,
+  );
+  writeFileSync(join(tmpDir, 'wrangler.json'), '{"compatibility_date": "2020-01-01"}');
+  const result = runScript(probe, [], tmpDir);
+  assert.equal(result.status, 0, 'an import must not exit(1) via the CLI');
+  assert.match(result.stdout, /IMPORT-OK/);
+  assert.doesNotMatch(result.stdout, /wrangler-baseline/);
+});

package/scripts/deploy-boot-smoke.mjs

@@ -6,7 +6,7 @@
  * (Story #231). Extracted from the workflow's former ~140-line inline bash so
  * the probe is unit-testable and reviewed as code, not as a YAML diff. The
  * workflow sparse-checks this script out of dsj1984/mandrel-platform at
- * `github.job_workflow_sha` — the exact commit the caller's
+ * `job.workflow_sha` — the exact commit the caller's
  * `deploy-cloudflare.yml@<ref>` pin resolved to — so the script version
  * always travels in lockstep with the workflow pin (same model as
  * `uptime-apply.yml` → `apply-uptime-monitors.mjs`).

package/scripts/deploy-worker-secrets.mjs

@@ -5,7 +5,7 @@
  * In-pipeline worker-secrets provisioning for the shared
  * `deploy-cloudflare.yml` workflow (Story #170; extracted from inline bash in
  * Story #231). The workflow sparse-checks this script out of
- * dsj1984/mandrel-platform at `github.job_workflow_sha` — the exact commit
+ * dsj1984/mandrel-platform at `job.workflow_sha` — the exact commit
  * the caller's `deploy-cloudflare.yml@<ref>` pin resolved to — so the script
  * version always travels in lockstep with the workflow pin (same model as
  * `uptime-apply.yml` → `apply-uptime-monitors.mjs`).

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());
 }