@vibe-agent-toolkit/utils 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/testing.d.ts

@@ -18,6 +18,7 @@
  * it. {@link replantableCorpus} exists precisely so the per-test wrapper each
  * suite still writes is three lines rather than twelve.
  */
+import type { UnreadablePolicy } from './listing-refusal.js';
 export * from './test-helpers.js';
 /** A planted fixture tree and the means to remove it. */
 export interface TempCorpus {
@@ -75,4 +76,19 @@ export interface ReplantableCorpus {
  * @returns Plant/clear/root, to be driven from the caller's own hooks
  */
 export declare function replantableCorpus(prefix: string, corpus: Readonly<Record<string, string>>): ReplantableCorpus;
+/**
+ * The `unreadable` policy a FIXTURE crawl states: refuse, against the fixture
+ * root, with a remedy that names the fixture rather than an adopter knob.
+ *
+ * A suite that is not ABOUT refusals still has to say what one would mean —
+ * the policy is required, with no default, and test files are not typechecked
+ * — and the honest answer for a planted tree is that a directory it cannot
+ * list is a broken fixture, not a case to degrade around. A suite that IS
+ * about refusals spells its own policy inline, because the policy is the
+ * subject.
+ *
+ * @param root - The fixture root the refused directory is expressed against
+ * @returns A `refuse` policy for `crawlDirectory` and the git listings
+ */
+export declare function refuseUnreadableFixture(root: string): UnreadablePolicy;
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,cAAc,mBAAmB,CAAC;AAElC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,UAAU,CAOZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,iBAAiB,CAyBnB"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAO7D,cAAc,mBAAmB,CAAC;AAElC,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,UAAU,CAOZ;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wDAAwD;IACxD,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,iBAAiB,CAyBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAEtE"}

package/dist/testing.js

@@ -95,4 +95,21 @@ export function replantableCorpus(prefix, corpus) {
         },
     };
 }
+/**
+ * The `unreadable` policy a FIXTURE crawl states: refuse, against the fixture
+ * root, with a remedy that names the fixture rather than an adopter knob.
+ *
+ * A suite that is not ABOUT refusals still has to say what one would mean —
+ * the policy is required, with no default, and test files are not typechecked
+ * — and the honest answer for a planted tree is that a directory it cannot
+ * list is a broken fixture, not a case to degrade around. A suite that IS
+ * about refusals spells its own policy inline, because the policy is the
+ * subject.
+ *
+ * @param root - The fixture root the refused directory is expressed against
+ * @returns A `refuse` policy for `crawlDirectory` and the git listings
+ */
+export function refuseUnreadableFixture(root) {
+    return { refuse: { root, remedy: 'A test fixture must be listable in full; fix the fixture, not the walk.' } };
+}
 //# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,sEAAsE;AACtE,cAAc,mBAAmB,CAAC;AAUlC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAwC;IAExC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,gKAAgK;QAChK,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAAwC;IAExC,IAAI,OAA+B,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,0EAA0E;YAC1E,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,iEAAiE,CAC9F,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE7D,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,sEAAsE;AACtE,cAAc,mBAAmB,CAAC;AAUlC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,MAAwC;IAExC,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,gKAAgK;QAChK,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AACjF,CAAC;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,MAAwC;IAExC,IAAI,OAA+B,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,0EAA0E;YAC1E,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,sBAAsB,MAAM,iEAAiE,CAC9F,CAAC;YACJ,CAAC;YACD,OAAO,OAAO,CAAC,IAAI,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,yEAAyE,EAAE,EAAE,CAAC;AACjH,CAAC"}

package/eslint/README.md

@@ -2,7 +2,7 @@
 
 ESLint rules that enforce the cross-platform and agentic-code safety helpers in the rest of [`@vibe-agent-toolkit/utils`](https://www.npmjs.com/package/@vibe-agent-toolkit/utils).
 
-Twenty-one rules, all of them derived from a bug that actually shipped: `os.tmpdir()` returning an 8.3 short path on a Windows CI runner, `path.join()` producing backslashes that then failed a string comparison, `await import(absolutePath)` throwing on Windows without a `file://` URL, `execSync()` interpolating a caller-controlled string into a shell. Most auto-fix.
+Twenty-six rules, all of them derived from a bug that actually shipped: `os.tmpdir()` returning an 8.3 short path on a Windows CI runner, `path.join()` producing backslashes that then failed a string comparison, `await import(absolutePath)` throwing on Windows without a `file://` URL, `execSync()` interpolating a caller-controlled string into a shell. Most auto-fix.
 
 ## Installation
 
@@ -25,7 +25,7 @@ export default [
 ];
 ```
 
-`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 22 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other four are opt-in; the [rule tables](#rules) mark each rule's `recommended` severity, and `—` means not in `recommended`.
+`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 26 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other eight are opt-in; the [rule tables](#rules) mark each rule's `recommended` severity, and `—` means not in `recommended`.
 
 To pick rules yourself, register the plugin and name them:
 
@@ -137,6 +137,20 @@ The member-call rules here check the **receiver**, not just the method name, so
 | `no-bare-dynamic-import-path` | `await import(absolutePath)` | `dynamicImportPath()` / `pathToFileURL(p).href` | `/fs` | | `error` |
 | `no-file-url-string-concat` | `` `file://${p}` `` | `pathToFileURL(p).href` | — | | `error` |
 
+### Entrypoint guards
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-fragile-entrypoint-guard` | `import.meta.main`; `import.meta.url === pathToFileURL(process.argv[1]).href`; `fileURLToPath(import.meta.url) === process.argv[1]` | `isEntrypoint(import.meta.url)` | `/process` | | — |
+
+All three banned spellings fail the same way: the guard answers **false for the script it is guarding**, so the process exits 0 having run nothing — the quietest failure a CLI has.
+
+`import.meta.main` shipped in Node **24.2 / 22.18**. Below that it is `undefined`, measured on a real 22.13.0, and this package's own floor is `>=22`. A repository-structure gate guarded that way printed nothing and exited 0 on the exact Node its CI job installed.
+
+The other two are one defect wearing two spellings: a raw string comparison of where the module lives against `process.argv[1]`, with no realpath pass, written either in URL space (`pathToFileURL` the argv path) or in path space (`fileURLToPath` the module URL). A `node_modules/.bin` entry is a **symlink**, so `process.argv[1]` is the link and the module's own location is the resolved target: the strings differ and the guard is false, in either space. Measured false on Node 22.14.0 and 24.13.1 alike, where `isEntrypoint()` is true. Only `process.argv[1]` counts — `argv[2]` and up are ordinary CLI arguments. `import.meta.url`, `import.meta.dirname` and `import.meta.filename` are untouched; only `.main` is banned.
+
+Not in `recommended` because the first half depends on **your** Node floor — at or above 24.2 / 22.18, `import.meta.main` is correct. The argv compares depend on nothing and are a defect everywhere; the two share a rule id, so enable it explicitly if your floor is below 24.2 / 22.18 or you ship a `bin`.
+
 ### Content decoding
 
 | Rule | Bans | Use instead | Subpath | Fix | `recommended` |

package/eslint/index.cjs

@@ -55,6 +55,7 @@ const rules = {
   'require-justified-skip': require('./rules/require-justified-skip.cjs'),
   'no-bare-symlink-in-tests': require('./rules/no-bare-symlink-in-tests.cjs'),
   'no-process-exit-in-phase': require('./rules/no-process-exit-in-phase.cjs'),
+  'no-fragile-entrypoint-guard': require('./rules/no-fragile-entrypoint-guard.cjs'),
 };
 
 /**
@@ -145,6 +146,20 @@ const RECOMMENDED_EXCLUDE = new Set([
   // that legitimately exits would get a finding they cannot act on. It ships in
   // `rules` and VAT enables it explicitly, scoped to its own orchestrators.
   'no-process-exit-in-phase',
+  // Excluded because ONE of its two halves is a claim about the CONSUMER's Node
+  // floor rather than a portable fact. `import.meta.main` shipped in Node 24.2 /
+  // 22.18; an adopter whose floor is at or above that writes it correctly and
+  // would get a finding they cannot act on. This package's own floor is `>=22`,
+  // which spans 22.13–22.17 where the property is `undefined` — so the hazard is
+  // real for some adopters and absent for others, and only they know which.
+  //
+  // The rule's OTHER half (`rawEntrypointCompare`) has no such dependency: a raw
+  // string compare against `pathToFileURL(argv[1]).href` misses a symlinked
+  // entry on every Node there has ever been. The two share one rule id and
+  // cannot be enabled separately, and the floor-dependent half is what keeps the
+  // pair out — the same trade already recorded for `no-bare-symlink-in-tests`.
+  // VAT enables the whole rule explicitly, because VAT's floor is 22.13.0.
+  'no-fragile-entrypoint-guard',
 ]);
 
 /**

package/eslint/index.d.cts

@@ -47,17 +47,20 @@ declare namespace plugin {
     rules: Record<string, RuleModule>;
     configs: {
       /**
-       * The cross-platform safety core: 18 of the 25 rules, 15 `error` / 3 `warn`.
+       * The cross-platform safety core: 18 of the 26 rules, 15 `error` / 3 `warn`.
        *
-       * Seven are excluded, for four reasons. `no-test-scoped-functions`,
+       * Eight are excluded, for five reasons. `no-test-scoped-functions`,
        * `require-justified-skip` and `no-bare-symlink-in-tests` are positions on
        * TEST STYLE rather than portability facts. `no-unsafe-root-join` and
        * `no-process-exit-in-phase` key on NAMING rather than on the property they
        * care about (taint, and an orchestrated call site). `no-raw-text-decode`
-       * names a decoding SEAM that only exists in the consuming repo. And
+       * names a decoding SEAM that only exists in the consuming repo.
        * `no-self-package-import` REQUIRES an option this config cannot supply.
+       * And `no-fragile-entrypoint-guard` half-depends on the CONSUMER's Node
+       * floor — `import.meta.main` is correct at or above 24.2 / 22.18 and
+       * `undefined` below it.
        *
-       * All seven still ship in `rules` and are enabled by naming them — which is
+       * All eight still ship in `rules` and are enabled by naming them — which is
        * what this repo's own `eslint.config.js` does. The count above is asserted
        * by `packages/utils/test/eslint/rules.test.ts`, so it cannot drift
        * unnoticed the way it did when this comment said "four".

package/eslint/rules/no-fragile-entrypoint-guard.cjs

@@ -0,0 +1,215 @@
+/**
+ * ESLint rule: no-fragile-entrypoint-guard
+ *
+ * Ban the two "am I the script Node was asked to run?" idioms that answer
+ * **false for the script they are guarding**, so the process exits 0 having done
+ * nothing at all.
+ *
+ * @example
+ * // ❌ BAD — undefined before Node 24.2 / 22.18
+ * if (import.meta.main) { await main(); }
+ *
+ * // ❌ BAD — raw string compare, no realpath: false through any `.bin` symlink
+ * if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { … }
+ *
+ * // ❌ BAD — the same compare done in path space instead of URL space
+ * if (fileURLToPath(import.meta.url) === process.argv[1]) { … }
+ *
+ * // ✅ GOOD
+ * import { isEntrypoint } from '@vibe-agent-toolkit/utils/process';
+ * if (isEntrypoint(import.meta.url)) { await main(); }
+ *
+ * ## Why a lint rule and not a comment
+ *
+ * Both defects have already shipped in this repo, and both were invisible to
+ * every gate:
+ *
+ * - `import.meta.main` was added in Node **24.2 / 22.18**. Measured on the exact
+ *   floor this repo declares — `>=22.13.0` — the property is `undefined`:
+ *
+ *   ```
+ *   $ node-v22.13.0 --input-type=module -e "console.log(import.meta.main)"  -> undefined
+ *   $ node-v24.13.1 --input-type=module -e "console.log(import.meta.main)"  -> true
+ *   ```
+ *
+ *   So a repository-structure gate guarded this way printed nothing and exited 0
+ *   on the very Node its own CI job installs. A contributor sitting exactly on
+ *   the supported floor got a green pre-commit gate that had run no rule.
+ *
+ * - `import.meta.url === pathToFileURL(process.argv[1]).href` compares two
+ *   strings with no realpath pass. Invoked through a `node_modules/.bin` shim —
+ *   i.e. the normal way a package's own bin is run — `process.argv[1]` is the
+ *   SYMLINK and `import.meta.url` is the resolved target, the strings differ,
+ *   and the guard is false. Measured false on Node 22.14.0 and 24.13.1 alike,
+ *   where `isEntrypoint()` is true.
+ *
+ *   ⚠️ That defect is about the MISSING REALPATH, not about URLs, so it has a
+ *   second spelling that is just as common and just as wrong:
+ *   `fileURLToPath(import.meta.url) === process.argv[1]` converts the module URL
+ *   to a path instead of converting the invoked path to a URL, and then compares
+ *   the same two unresolved strings. A matcher that only knew the URL-space form
+ *   would be a mechanism with a hole in the middle of its own premise, which is
+ *   the thing this rule exists to refuse. Both directions of both spellings are
+ *   flagged, under one message, because they are one defect.
+ *
+ * The first of those was fixed once already and the fix was pinned by nothing:
+ * reverting all three call sites to `if (import.meta.main)` left the entire test
+ * suite green, because the only thing standing against it was three prose
+ * comments addressed to a human. A banner is not a mechanism. This rule is.
+ *
+ * ## What it does NOT flag
+ *
+ * `import.meta.url`, `import.meta.dirname` and `import.meta.filename` are all
+ * fine and all common — only `.main` is the unavailable one. And
+ * `pathToFileURL(x).href` is only a finding when it is being compared to
+ * `import.meta.url`; on its own it is just a URL.
+ *
+ * ## No `exemptFiles`
+ *
+ * Unlike the wrapper rules in this pack, there is no implementation file that
+ * has to call the banned thing: `isEntrypoint()` is written in terms of
+ * `process.argv[1]` and a realpath comparison, and touches neither idiom. An
+ * exemption option here would only ever be used to opt a file out of a fix.
+ */
+
+'use strict';
+
+/** `import.meta`, as the parser sees it. */
+function isImportMeta(node) {
+  return (
+    node?.type === 'MetaProperty' && node.meta?.name === 'import' && node.property?.name === 'meta'
+  );
+}
+
+/**
+ * `import.meta.<name>` — a static, non-computed member of `import.meta`.
+ *
+ * @param {object} node - Any node.
+ * @param {string} name - The property to match, e.g. `main`.
+ * @returns {boolean}
+ */
+function isImportMetaMember(node, name) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.computed === false &&
+    isImportMeta(node.object) &&
+    node.property?.type === 'Identifier' &&
+    node.property.name === name
+  );
+}
+
+/**
+ * The called function's NAME, whether called bare or off a namespace.
+ *
+ * `pathToFileURL(p)` and `url.pathToFileURL(p)` are the same call, and a matcher
+ * that only understood the bare form would be blind to every file that imports
+ * `node:url` as a namespace.
+ *
+ * @param {object} callee - The `callee` of a CallExpression.
+ * @returns {string | undefined}
+ */
+function calleeName(callee) {
+  if (callee === null || callee === undefined) return undefined;
+  if (callee.type === 'Identifier') return callee.name;
+  if (callee.type === 'MemberExpression' && callee.computed === false) {
+    return callee.property?.type === 'Identifier' ? callee.property.name : undefined;
+  }
+  return undefined;
+}
+
+/** `pathToFileURL(…).href`, in either import style. */
+function isPathToFileUrlHref(node) {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.computed === false &&
+    node.property?.type === 'Identifier' &&
+    node.property.name === 'href' &&
+    node.object?.type === 'CallExpression' &&
+    calleeName(node.object.callee) === 'pathToFileURL'
+  );
+}
+
+/** `fileURLToPath(import.meta.url)`, in either import style. */
+function isFileUrlToPathOfImportMetaUrl(node) {
+  return (
+    node?.type === 'CallExpression' &&
+    calleeName(node.callee) === 'fileURLToPath' &&
+    isImportMetaMember(node.arguments?.[0], 'url')
+  );
+}
+
+/**
+ * `process.argv[1]` — and the `const { argv } = process` spelling of it.
+ *
+ * The index is pinned to `1` on purpose: `argv[2]` and up are ordinary CLI
+ * arguments, and comparing one of those to anything is not this defect.
+ */
+function isArgvEntry(node) {
+  if (node === null || node === undefined) return false;
+  if (node.type !== 'MemberExpression' || node.computed !== true) return false;
+  if (node.property?.type !== 'Literal' || node.property.value !== 1) return false;
+
+  const target = node.object;
+  if (target?.type === 'Identifier') return target.name === 'argv';
+  return (
+    target?.type === 'MemberExpression' &&
+    target.computed === false &&
+    target.property?.type === 'Identifier' &&
+    target.property.name === 'argv'
+  );
+}
+
+/** Where THIS module lives, in whichever space the comparison is written in. */
+function isModuleLocation(node) {
+  return isImportMetaMember(node, 'url') || isFileUrlToPathOfImportMetaUrl(node);
+}
+
+/** The script Node was ASKED to run, in whichever space the comparison uses. */
+function isInvokedScript(node) {
+  return isArgvEntry(node) || isPathToFileUrlHref(node);
+}
+
+/** Identity comparisons; `==`/`!=` on these operands never occurs and is not the idiom. */
+const IDENTITY_OPERATORS = new Set(['===', '!==']);
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ban entrypoint guards that silently answer false — `import.meta.main` (undefined before Node 24.2/22.18) and any raw compare of where the module lives to `process.argv[1]`, in URL space or path space (false through any symlink). Use `isEntrypoint()`.',
+      category: 'Cross-Platform',
+      recommended: false,
+    },
+    messages: {
+      importMetaMain:
+        '`import.meta.main` is undefined before Node 24.2 / 22.18, so this guard is FALSE on older supported Node and the script exits 0 having done nothing. Use `isEntrypoint(import.meta.url)` from `@vibe-agent-toolkit/utils/process`.',
+      rawEntrypointCompare:
+        'Comparing where this module lives to `process.argv[1]` (as `import.meta.url === pathToFileURL(argv[1]).href`, or as `fileURLToPath(import.meta.url) === argv[1]`) is a raw string compare with no realpath pass, so it is FALSE whenever the script is reached through a symlink (any `node_modules/.bin` shim) and the script exits 0 having done nothing. Use `isEntrypoint(import.meta.url)` from `@vibe-agent-toolkit/utils/process`.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (isImportMetaMember(node, 'main')) {
+          context.report({ node, messageId: 'importMetaMain' });
+        }
+      },
+
+      BinaryExpression(node) {
+        if (!IDENTITY_OPERATORS.has(node.operator)) return;
+
+        // Either operand order: a matcher keyed on side would be half blind.
+        const compares =
+          (isModuleLocation(node.left) && isInvokedScript(node.right)) ||
+          (isModuleLocation(node.right) && isInvokedScript(node.left));
+
+        if (compares) {
+          context.report({ node, messageId: 'rawEntrypointCompare' });
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/utils",
-  "version": "0.2.0-rc.5",
+  "version": "0.2.0-rc.7",
   "type": "module",
   "description": "Core utility functions shared across the vibe-agent-toolkit packages",
   "sideEffects": [
@@ -17,7 +17,7 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -118,7 +118,7 @@
     "eslint": "^9.39.5",
     "rimraf": "^6.0.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
+    "vitest": "^4.1.11",
     "zod": "^3.25.0"
   },
   "publishConfig": {