@vibe-agent-toolkit/utils 0.1.41 → 0.1.42-rc.1

package/eslint/README.md

@@ -0,0 +1,191 @@
+# `@vibe-agent-toolkit/utils/eslint`
+
+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.
+
+## Installation
+
+```bash
+bun add @vibe-agent-toolkit/utils
+```
+
+There is no separate plugin package: the rules are a subpath of the package whose helpers they enforce, so the two can never drift to different versions. Requires ESLint 9+ (flat config) and Node >= 22.
+
+`eslint` is an **optional** peer dependency, and this subpath adds no dependency to the others. An ESLint plugin is data, not code that runs — every rule module here exports a plain object and none of them `require('eslint')` — so installing `utils` for `safePath.join()` alone pulls in nothing extra and warns about nothing.
+
+## Usage
+
+```js
+// eslint.config.js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  vat.configs.recommended,
+];
+```
+
+`configs.recommended` registers the plugin under the `@vibe-agent-toolkit` namespace and enables the **cross-platform safety core** — 18 of the 21 rules, most at `error` and three at `warn` (see [Severities](#severities)). The other three 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:
+
+```js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  {
+    files: ['**/*.{ts,tsx,js,cjs,mjs}'],
+    plugins: { '@vibe-agent-toolkit': vat },
+    rules: {
+      '@vibe-agent-toolkit/no-path-join': 'error',
+      '@vibe-agent-toolkit/no-os-tmpdir': 'error',
+    },
+  },
+];
+```
+
+### Exempting the file that implements the wrapper
+
+A rule that bans `os.tmpdir()` has to let *something* call it — the file that implements your `normalizedTmpdir()`. That file's path is a fact about your repo, so the plugin ships **no** built-in exemptions; you declare them:
+
+```js
+'@vibe-agent-toolkit/no-os-tmpdir': ['error', { exemptFiles: ['src/paths.ts'] }],
+'@vibe-agent-toolkit/no-path-join': ['error', { exemptFiles: [
+  'src/paths.ts',
+  'test/paths.test.ts',   // asserts the platform-native behavior the wrapper hides
+] }],
+```
+
+Paths are repo-relative and matched at a **path-segment boundary**, never as a substring: declaring `src/paths.ts` does not exempt `tools/hooks/paths.ts`, `src/my-paths.ts`, or `src/paths.ts.bak`. (It used to be a substring check. A private `tools/hooks/path-utils.ts` full of raw `tmpdir()` calls linted clean for months.) Matching is separator-agnostic, so the same list works on Windows.
+
+The match is anchored at the **end** of the path, so a declaration is a suffix: `src/paths.ts` also exempts `packages/anything/src/paths.ts`. Name enough leading segments to be unambiguous in your tree (this repo declares `packages/utils/src/path-utils.ts`, not `path-utils.ts`).
+
+Taken to its limit, a **bare filename with no `/` exempts that filename everywhere in the repo** — including files added later by someone who never read the config. The rules report that as `unanchoredExemptFile` rather than letting it pass, because it is the same repo-wide hole the segment-boundary matching exists to close. `./paths.ts` is the same hole with a slash in it, so the check runs on the normalized entry, not the raw string.
+
+The option **replaces** any default rather than merging with it, and unknown option keys are a config error — a typo'd `exemptFile` must fail loudly rather than quietly exempt nothing.
+
+The rules taking `exemptFiles` are `no-path-join`, `no-path-resolve`, `no-path-relative`, `no-os-tmpdir`, `no-fs-mkdirSync`, `no-fs-realpathSync`, `no-child-process-execSync`, and `no-fs-promises-cp`.
+
+## Rules
+
+The "use instead" column names the `@vibe-agent-toolkit/utils` subpath the replacement lives on; ✓ marks an auto-fix. The **`recommended`** column is the severity `configs.recommended` assigns — `—` means the rule is **not** in `recommended` and must be enabled explicitly.
+
+**The auto-fix writes the import to the subpath in that column**, not to the barrel — `--fix` on a raw `path.join()` inserts `import { safePath } from '@vibe-agent-toolkit/utils/path'`. A file that already reaches the helper through the barrel keeps its existing import and only has the call rewritten: adding a second binding of the same name is a `SyntaxError`, not a redundant import.
+
+### Pointing the fix at your own re-export seam — `safeModule`
+
+If your repo re-exports these helpers through its own module, the defaults above are wrong for you, and not merely stylistically: in a workspace with isolated `node_modules` (pnpm, Yarn PnP), an import of a package the receiving package does not declare **fails to resolve**. One adopter measured 620 files across 52 such packages. Point the rule at the module that resolves where the fix lands:
+
+```js
+'@vibe-agent-toolkit/no-path-join':  ['warn',  { safeModule: '@acme/dev-tools/paths' }],
+'@vibe-agent-toolkit/no-os-tmpdir':  ['error', { safeModule: '@acme/dev-tools/fs' }],
+```
+
+It is **per-rule**, not one shared `settings` key, because a seam need not split its symbols the way this package does — an adopter whose narrow entry carried `normalizedTmpdir()` but not `safePath` needed the two rules pointed at different modules, which a single key cannot express. Note the two lines above therefore name *different* modules. It composes with `exemptFiles`, and it changes the error message as well as the fix, so the advice never names a module you don't use. Every rule that names a module accepts it, including the ones that only advise and never fix.
+
+> **Point each rule at a module that exports the symbol *that rule writes*, not merely one that resolves.** This is the failure mode worth spending a minute on, because it is the quiet one. A `safeModule` that doesn't resolve fails loudly and immediately. A `safeModule` that resolves but lacks the symbol passes every resolution check — including an explicit `import()` probe — and then throws `Cannot read properties of undefined` at each call site, once per fixed file. Aim `no-path-join` at an entry without `safePath` and you get a green `--fix`, a green install, and thousands of latent `TypeError`s. The rules cannot check this for you: verifying it would mean resolving and importing your module from inside the linter, which is neither its job nor reliable from wherever ESLint happens to be running.
+
+Two ways your target can be wrong, which surface differently: `ERR_MODULE_NOT_FOUND` means the receiving package doesn't declare it at all, while `ERR_PACKAGE_PATH_NOT_EXPORTED` means it does — but the version resolved *at that location* doesn't export the subpath. In a monorepo mid-upgrade those differ, so the question is never "does the package declare it" but "does the resolved version there export it."
+
+### Path handling
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-path-join` | `path.join()` | `safePath.join()` | `/path` | ✓ | `warn` |
+| `no-path-resolve` | `path.resolve()` | `safePath.resolve()` | `/path` | ✓ | `warn` |
+| `no-path-relative` | `path.relative()` | `safePath.relative()` | `/path` | ✓ | `warn` |
+| `no-path-startswith` | `path.startsWith()` on a raw path | `toForwardSlash()` first | `/path` | | `error` |
+| `no-hardcoded-path-split` | `split('/')` / `split('\\')` on a path | `path.basename()`, or `toForwardSlash()` first | `/path` | | `error` |
+| `no-path-sep-in-strings` | `path.sep` embedded in a string literal | `toForwardSlash()` | `/path` | | `error` |
+| `no-manual-path-normalize` | hand-rolled `.replace(/\\/g, '/')` | `toForwardSlash()` | `/path` | ✓ | `error` |
+| `no-path-operations-in-comparisons` | raw `path.*()` results in string comparisons | wrap in `toForwardSlash()` | `/path` | | `error` |
+| `no-unsafe-root-join` | `safePath.join(someRoot, x)` where `x` can escape | `safePath.joinUnderRoot()` | `/path` | | — |
+
+### Filesystem and process
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-os-tmpdir` | `os.tmpdir()` (8.3 short names on Windows) | `normalizedTmpdir()` | `/fs` | ✓ | `error` |
+| `no-fs-realpathSync` | `fs.realpathSync()` | `normalizePath()` | `/fs` | ✓ | `error` |
+| `no-fs-mkdirSync` | `fs.mkdirSync()` | `mkdirSyncReal()` | `/fs` | ✓ | `error` |
+| `no-fs-promises-cp` | `cp()` from `node:fs/promises` (drops nested files on Node 22) | `cpSync()` from `node:fs` | — | ✓ | `error` |
+| `no-child-process-execSync` | `child_process.execSync()` | `safeExecSync()` | `/process` | ✓ | `error` |
+| `no-unix-shell-commands` | `tar`, `grep`, `rm`, `echo`, … spawned directly | Node APIs, or a portable script fixture | — | | `error` |
+
+### URLs and dynamic imports
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `no-url-pathname-for-fs` | `new URL(x, import.meta.url).pathname` as a filesystem path | `resolveFromImportMeta()` / `fileURLToPath()` | `/fs` | | `error` |
+| `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` |
+
+### Code and test hygiene
+
+| Rule | Bans | Use instead | Subpath | Fix | `recommended` |
+|---|---|---|---|---|---|
+| `prefer-startswith-over-regex` | `/^foo/.test(s)` | `s.startsWith('foo')` | — | | `error` |
+| `no-test-scoped-functions` | helper functions declared inside `describe`/`it` | module scope | — | | — |
+| `require-justified-skip` | unannotated `it.skip`/`it.todo`, tautological assertions, empty test bodies | a `SKIP(#123): reason` annotation, or a real assertion | — | | — |
+
+### What `recommended` deliberately leaves out
+
+Three rules ship without riding in `recommended`, for two different reasons.
+
+**Test-style opinions** — `no-test-scoped-functions` (where a helper may be declared) and `require-justified-skip` (the annotation grammar for a disabled test). Neither is a portability or correctness fact, and installing this package for `safePath.join()` should not also import someone else's test conventions. Both are worth turning on deliberately.
+
+**Unsound, pending a rewrite** — `no-unsafe-root-join`. It keys on whether an identifier's *name* ends in `root` rather than on whether any segment is caller-controlled, which makes it noisy and blind at the same time. Measured against 4,670 files of real adopter source: 108 findings, none autofixable. Verified behaviour:
+
+```js
+safePath.join(repoRoot, 'docs', 'product')  // FIRES — all literals, nothing can escape
+safePath.resolve(packageRoot, '..', '..')   // FIRES — escaping is the intent; the fix breaks it
+safePath.join(repoRoot)                     // FIRES — one argument, no segment at all
+safePath.join(base, userInput)              // SILENT — the shape it exists to catch
+```
+
+A rule that misses its own target does not belong in a config named `recommended` at any severity: a safety core that cries wolf teaches people to ignore it, and that costs you the true positives too. It still ships, and it still earns `error` when scoped to directories where a path escape is a security boundary — which is how this repo uses it, on its skill-test staging code. It will return to `recommended` when it keys on taint rather than on naming.
+
+Enable any of the three by naming it:
+
+```js
+import vat from '@vibe-agent-toolkit/utils/eslint';
+
+export default [
+  vat.configs.recommended,
+  {
+    rules: {
+      '@vibe-agent-toolkit/no-test-scoped-functions': 'error',
+      '@vibe-agent-toolkit/require-justified-skip': 'error',
+    },
+  },
+  {
+    // Scope it to where an escape is a security boundary, not repo-wide.
+    files: ['src/staging/**/*.ts'],
+    rules: { '@vibe-agent-toolkit/no-unsafe-root-join': 'error' },
+  },
+];
+```
+
+### Severities
+
+Within `recommended`, `error` is the default; three rules are `warn`:
+
+- **`no-path-join`, `no-path-resolve`, `no-path-relative`** — by far the highest-churn rules; they fire on every raw `node:path` call in an existing codebase. Measured on a 4,670-file adopter tree: 3,963 + 372 + 1 findings, **every one of them autofixable**. `warn` lets a project run `--fix` and burn the list down incrementally instead of blocking CI on day one.
+
+Raise all three to `error` once the backlog is clear. That is what this repo does.
+
+The criterion for `warn` is **migration volume**, not how real the finding is — a rule whose findings we doubted would be out of `recommended` entirely, not demoted. Everything at `error` either prevents a bug or moves a static-analysis finding left of a merge.
+
+## Why custom rules
+
+A cross-platform safety helper is only as good as its enforcement. `safePath.join()` prevents a class of Windows bug precisely once — the moment someone writes `path.join()` instead, the helper's existence has bought nothing. Publishing the API without the lint rule ships half a product: the fix is available, and nothing directs anyone to it.
+
+What these rules buy is *when* you find out. Without them, a raw `os.tmpdir()` is found by a Windows CI job — a different machine, twenty minutes later, on someone else's push, with a failure message about a path that doesn't obviously relate to the line that caused it. With them, it is a red squiggle under the call, on the author's machine, with the replacement named in the message and usually applied by `--fix`. The bug never leaves the editor. That is the whole argument, and it is why the rules are written to name the replacement rather than merely to forbid the primitive.
+
+The second reason is agentic. When most code in a repo is written by an LLM, a convention that lives only in a style guide or a CLAUDE.md gets re-violated constantly — the model is confident, `path.join` is what it saw a million times in training, and the guidance was three thousand tokens back. A lint rule is feedback the model receives at the moment it is wrong, which is the only moment it can act on. Treat rules as the durable form of any convention you'd otherwise repeat in a prompt.
+
+Most projects will want rules the ones here don't cover, for invariants only that project has: a deprecated internal API, a logging call that must carry a request ID, a module boundary nothing may import across. These rules are readable, small, and built on two shared factories plus a segment-anchored path matcher — copy the shape. `eslint-rule-factory.cjs` handles "ban function X from module Y, suggest Z, fix the import"; `exempt-path-matcher.cjs` handles the exemption question every such rule eventually asks, and is worth reading before you write `filename.includes(...)`.
+
+## License
+
+MIT

package/eslint/index.cjs

@@ -0,0 +1,161 @@
+/**
+ * `@vibe-agent-toolkit/utils/eslint` — cross-platform and agentic-code safety rules.
+ *
+ * These rules enforce the safe helpers published by the rest of this package
+ * (`safePath.*` on `/path`, `normalizedTmpdir()`, `mkdirSyncReal()`,
+ * `normalizePath()` on `/fs`, `safeExecSync()` on `/process`). The helpers exist
+ * because the raw primitives they wrap have platform potholes; the rules exist so
+ * a call to the raw primitive fails at lint time on the author's machine rather
+ * than in CI on a different OS.
+ *
+ * They ship as a SUBPATH rather than a separate package because an ESLint plugin
+ * is data, not code that runs: every module below exports a plain rule object and
+ * none of them `require('eslint')`. So this entry resolves — and the other twelve
+ * subpaths keep resolving — whether or not ESLint is installed, which is why
+ * `eslint` is declared as an OPTIONAL peer dependency. One install, one version,
+ * no way for the rules to drift from the helpers they name.
+ *
+ * CommonJS on purpose, in an ESM package: the rule modules are `.cjs`, Node keys
+ * module format off the extension regardless of the package's `"type"`, and a CJS
+ * entry point can be both `require()`d from an `eslint.config.cjs` and `import`ed
+ * from an `eslint.config.js`/`.mjs`.
+ *
+ * Rules whose exemptions name a file (the ONE implementation file allowed to call
+ * the primitive) take an `exemptFiles` option — see README.md. The shipped
+ * defaults are EMPTY: an exemption is a claim about a specific repo's layout, and
+ * inheriting another repo's claim is how a same-named file silently opts itself
+ * out of a rule.
+ */
+
+'use strict';
+
+const rules = {
+  'no-child-process-execSync': require('./rules/no-child-process-execSync.cjs'),
+  'no-hardcoded-path-split': require('./rules/no-hardcoded-path-split.cjs'),
+  'no-path-startswith': require('./rules/no-path-startswith.cjs'),
+  'no-unix-shell-commands': require('./rules/no-unix-shell-commands.cjs'),
+  'no-os-tmpdir': require('./rules/no-os-tmpdir.cjs'),
+  'no-fs-mkdirSync': require('./rules/no-fs-mkdirSync.cjs'),
+  'no-fs-realpathSync': require('./rules/no-fs-realpathSync.cjs'),
+  'no-manual-path-normalize': require('./rules/no-manual-path-normalize.cjs'),
+  'no-path-sep-in-strings': require('./rules/no-path-sep-in-strings.cjs'),
+  'no-path-operations-in-comparisons': require('./rules/no-path-operations-in-comparisons.cjs'),
+  'no-path-join': require('./rules/no-path-join.cjs'),
+  'no-path-resolve': require('./rules/no-path-resolve.cjs'),
+  'no-path-relative': require('./rules/no-path-relative.cjs'),
+  'no-test-scoped-functions': require('./rules/no-test-scoped-functions.cjs'),
+  'no-fs-promises-cp': require('./rules/no-fs-promises-cp.cjs'),
+  'no-url-pathname-for-fs': require('./rules/no-url-pathname-for-fs.cjs'),
+  'no-bare-dynamic-import-path': require('./rules/no-bare-dynamic-import-path.cjs'),
+  'no-file-url-string-concat': require('./rules/no-file-url-string-concat.cjs'),
+  'prefer-startswith-over-regex': require('./rules/prefer-startswith-over-regex.cjs'),
+  'no-unsafe-root-join': require('./rules/no-unsafe-root-join.cjs'),
+  'require-justified-skip': require('./rules/require-justified-skip.cjs'),
+};
+
+/**
+ * Rules deliberately LEFT OUT of `configs.recommended`.
+ *
+ * `recommended` is the cross-platform-safety core: every rule in it flags a call
+ * that is wrong (or unportable) regardless of how the adopting project likes to
+ * write tests. The two below are neither — they encode a position on TEST STYLE:
+ *
+ * - `require-justified-skip` — a specific annotation grammar (`SKIP(#123): reason`)
+ *   for a disabled test, plus a view on what counts as a tautological assertion.
+ * - `no-test-scoped-functions` — a view on WHERE a test helper may be declared
+ *   (module scope, never inside `describe`/`it`).
+ *
+ * Someone installing this package for `safePath.join()` should not silently
+ * inherit either. Both ship in `rules` and stay enabled explicitly:
+ *
+ *   '@vibe-agent-toolkit/require-justified-skip': 'error',
+ *
+ * That is exactly what VAT's own `eslint.config.js` does — it does not consume
+ * `configs.recommended` at all, so this exclusion changes nothing about how this
+ * repo lints itself.
+ */
+const RECOMMENDED_EXCLUDE = new Set([
+  'require-justified-skip',
+  'no-test-scoped-functions',
+  // Excluded for a DIFFERENT reason than the two above: not a style opinion, but
+  // an unsound heuristic. It keys on whether an identifier's name ends in `root`
+  // rather than on whether any segment is caller-controlled, which makes it
+  // simultaneously noisy and blind. Measured on a 4,670-file adopter tree: 108
+  // findings, 0 autofixable, and every one of these verified by execution here:
+  //
+  //   FIRES   safePath.join(repoRoot, 'docs', 'product')  <- all literals, cannot escape
+  //   FIRES   safePath.resolve(packageRoot, '..', '..')   <- escaping IS the intent; the fix breaks it
+  //   FIRES   safePath.join(repoRoot)                     <- one argument, no segment at all
+  //   silent  safePath.join(base, userInput)              <- THE dangerous shape, missed
+  //
+  // A rule that misses the case it exists to catch must not ride in a config
+  // named `recommended` at any severity — a safety core that cries wolf teaches
+  // people to ignore it, which costs the true positives too. It still ships, and
+  // it still earns `error` where scoped to directories in which a path escape is
+  // a security boundary (this repo scopes it to the skill-test staging code).
+  // Re-include it when it keys on taint rather than on naming.
+  'no-unsafe-root-join',
+]);
+
+/**
+ * Default severities for `configs.recommended`.
+ *
+ * `error` is the default: every rule below flags a call whose replacement is a
+ * one-line swap, and a wrong answer is a real bug on some platform.
+ *
+ * `warn` is reserved for the case where a fresh adopter's first run would
+ * otherwise be a wall of blocking errors they cannot triage in one sitting:
+ * `no-path-join` / `no-path-resolve` / `no-path-relative`, the highest-churn
+ * rules by far (they fire on every raw `node:path` call in the codebase).
+ * Measured on a 4,670-file adopter tree: 3,963 + 372 + 1 findings, **all
+ * autofixable**. All three auto-fix, so `warn` lets a project run `--fix` and
+ * burn the list down incrementally instead of blocking CI on day one.
+ *
+ * Raise them to `error` once the backlog is clear — that is what VAT itself does.
+ *
+ * The criterion for `warn` is MIGRATION VOLUME, not how real the finding is. Every
+ * rule in this pack either prevents a bug or shifts a static-analysis finding left of
+ * a merge, and both are worth blocking on; what `warn` buys is a first run that reads
+ * as a backlog to `--fix` rather than a wall. `prefer-startswith-over-regex` was
+ * briefly graded on a different axis ("style, not a defect") and demoted — that was
+ * wrong twice over: avoiding a SonarQube S6557 at lint time instead of at merge time
+ * is a real saving, and the rule's matcher rejects any regex containing a
+ * metacharacter, so it only fires on true literal prefixes and has near-zero churn.
+ * It is `error`.
+ */
+const RECOMMENDED_WARN = new Set([
+  'no-path-join',
+  'no-path-resolve',
+  'no-path-relative',
+]);
+
+/**
+ * Plugin namespace an adopter gets from `configs.recommended`, and therefore the
+ * prefix on every rule id (`@vibe-agent-toolkit/no-path-join`).
+ *
+ * Deliberately the SCOPE, not the full subpath specifier: rule ids are the surface
+ * adopters type into `rules`, `eslint-disable` comments and CI baselines, and they
+ * should not have to change if the pack ever moves house again. (This repo's own
+ * config registers the same object under `local` for exactly that reason.)
+ */
+const NAMESPACE = '@vibe-agent-toolkit';
+
+const plugin = {
+  meta: {
+    name: '@vibe-agent-toolkit/utils/eslint',
+  },
+  rules,
+  configs: {},
+};
+
+plugin.configs.recommended = {
+  name: '@vibe-agent-toolkit/utils/eslint/recommended',
+  plugins: { [NAMESPACE]: plugin },
+  rules: Object.fromEntries(
+    Object.keys(rules)
+      .filter((name) => !RECOMMENDED_EXCLUDE.has(name))
+      .map((name) => [`${NAMESPACE}/${name}`, RECOMMENDED_WARN.has(name) ? 'warn' : 'error']),
+  ),
+};
+
+module.exports = plugin;

package/eslint/index.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Types for `@vibe-agent-toolkit/utils/eslint`.
+ *
+ * Hand-written, and deliberately structural rather than `import type { ESLint }
+ * from 'eslint'`: `eslint` is an OPTIONAL peer dependency, so a consumer who took
+ * this package for `safePath.join()` has no `eslint` types installed, and a
+ * reference to them here would turn this entry into a type error for exactly the
+ * people the optional peer exists to spare. The shapes below are the subset flat
+ * config consumes, and are structurally assignable to `ESLint.Plugin`.
+ *
+ * `export =`, not `export default`: the implementation ends in
+ * `module.exports = plugin`, and `export =` is the only declaration form that says
+ * so. Consumers with `esModuleInterop` (the default for this repo's base config)
+ * still write `import vat from '@vibe-agent-toolkit/utils/eslint'`.
+ *
+ * `.d.cts`, not `.d.ts`: under `moduleResolution: node16`/`nodenext` TypeScript
+ * matches the declaration's extension to the module format of the file it
+ * describes, and `index.cjs` is CommonJS inside a `"type": "module"` package.
+ *
+ * This file exists because `eslint.config.ts` is supported from ESLint 9.18.
+ * Without it, an adopter writing one gets TS7016 on the import. It is NOT covered
+ * by `bun run typecheck` (utils' tsconfig includes only `src/**‍/*.ts`), so the
+ * packaged-artifact integration test compiles a consumer fixture against it
+ * instead — see `test/integration/eslint-recommended-config.integration.test.ts`.
+ */
+
+declare const plugin: plugin.Plugin;
+
+declare namespace plugin {
+  /** A rule module, opaque here — adopters hand these to ESLint, never call them. */
+  interface RuleModule {
+    meta?: Record<string, unknown>;
+    create: (context: unknown) => Record<string, unknown>;
+  }
+
+  /** A flat-config object, as returned by `configs.recommended`. */
+  interface FlatConfig {
+    name: string;
+    plugins: Record<string, Plugin>;
+    /** Rule id → severity. Keys are namespaced: `@vibe-agent-toolkit/no-path-join`. */
+    rules: Record<string, 'error' | 'warn' | 'off'>;
+  }
+
+  interface Plugin {
+    meta: { name: string };
+    /** Rule name WITHOUT the namespace prefix, e.g. `no-path-join`. */
+    rules: Record<string, RuleModule>;
+    configs: {
+      /**
+       * The cross-platform safety core: 18 of the 21 rules, 15 `error` / 3 `warn`.
+       * `no-test-scoped-functions` and `require-justified-skip` are excluded — they
+       * are positions on test style, not portability facts. Both still ship in
+       * `rules` and are enabled by naming them.
+       */
+      recommended: FlatConfig;
+    };
+  }
+}
+
+export = plugin;

package/eslint/rules/eslint-rule-factory.cjs

@@ -0,0 +1,241 @@
+/**
+ * ESLint Rule Factory - Shared implementation for unsafe operation rules
+ *
+ * Creates ESLint rules that detect unsafe operations and suggest safe alternatives.
+ * Supports auto-fixing with import management.
+ *
+ * @param {Object} config - Rule configuration
+ * @param {string} config.unsafeFn - Name of unsafe function (e.g., 'tmpdir', 'mkdirSync')
+ * @param {string} config.unsafeModule - Module containing unsafe function (e.g., 'node:os', 'node:fs')
+ * @param {string} config.safeFn - Name of safe replacement function (e.g., 'normalizedTmpdir')
+ * @param {string} config.safeModule - Module containing safe function. Pass the
+ *   NARROW subpath that owns the symbol (`@vibe-agent-toolkit/utils/fs`), never
+ *   the barrel — see `safe-import.cjs` for why.
+ * @param {string} config.message - Error message to display
+ * @param {readonly string[]} [config.exemptFiles] - FALLBACK repo-relative paths
+ *   allowed to call the unsafe function, used only when the consuming config
+ *   passes no `exemptFiles` option. Ship this empty: an exemption names one file
+ *   in one repo, so a baked-in default is a hole in every OTHER repo. Consumers
+ *   declare their own via the rule option (see `exempt-path-matcher.cjs`).
+ * @param {boolean} [config.checkMemberExpression] - Check for obj.method() calls (default: false)
+ * @returns {Object} ESLint rule definition
+ *
+ * @example
+ * // no-os-tmpdir.cjs
+ * const factory = require('./eslint-rule-factory.cjs');
+ * module.exports = factory({
+ *   unsafeFn: 'tmpdir',
+ *   unsafeModule: 'node:os',
+ *   safeFn: 'normalizedTmpdir',
+ *   safeModule: SAFE_FS_MODULE,
+ *   message: 'Use normalizedTmpdir() for Windows compatibility',
+ * });
+ *
+ * // …and in the consumer's eslint.config.js, naming ITS implementation file:
+ * // '@vibe-agent-toolkit/no-os-tmpdir': ['error', { exemptFiles: ['src/paths.ts'] }]
+ */
+
+const {
+  UNANCHORED_EXEMPT_FILE,
+  UNANCHORED_EXEMPT_MESSAGE,
+  createConfigurableExemptPathMatcher,
+  reportUnanchoredExemptEntries,
+} = require('./exempt-path-matcher.cjs');
+const {
+  EXEMPT_AND_SAFE_MODULE_SCHEMA,
+  isNameAlreadyBound,
+  resolveSafeModule,
+} = require('./safe-import.cjs');
+
+/**
+ * Helper function to filter unsafe import specifiers
+ * Extracted to reduce nesting depth for code quality
+ */
+function filterUnsafeSpecifiers(importNode, unsafeFn) {
+  return importNode.specifiers.filter((s) => s.imported && s.imported.name === unsafeFn);
+}
+
+/**
+ * Helper function to remove unsafe import specifiers
+ * Extracted to reduce nesting depth for code quality
+ */
+function removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeImportNode, unsafeSpecs) {
+  const fixes = [];
+  for (const spec of unsafeSpecs) {
+    const comma = sourceCode.getTokenAfter(spec);
+    if (comma?.value === ',') {
+      fixes.push(fixer.removeRange([spec.range[0], comma.range[1]]));
+    } else {
+      const commaBefore = sourceCode.getTokenBefore(spec);
+      if (commaBefore?.value === ',') {
+        fixes.push(fixer.removeRange([commaBefore.range[0], spec.range[1]]));
+      } else {
+        fixes.push(fixer.remove(spec));
+      }
+    }
+  }
+  return fixes;
+}
+
+module.exports = function createNoUnsafeRule(config) {
+  const {
+    unsafeFn,
+    unsafeModule,
+    safeFn,
+    safeModule,
+    message,
+    exemptFiles = [],
+    checkMemberExpression = false,
+  } = config;
+
+  const exemptMatcherFor = createConfigurableExemptPathMatcher(exemptFiles);
+
+  // Normalize module names (support both 'node:os' and 'os')
+  const moduleVariants = [unsafeModule];
+  if (unsafeModule.startsWith('node:')) {
+    moduleVariants.push(unsafeModule.replace('node:', ''));
+  } else {
+    moduleVariants.push(`node:${unsafeModule}`);
+  }
+
+  return {
+    meta: {
+      type: 'problem',
+      docs: {
+        description: `Enforce use of ${safeFn}() instead of ${unsafeFn}()`,
+        category: 'Best Practices',
+        recommended: true,
+      },
+      fixable: 'code',
+      schema: [EXEMPT_AND_SAFE_MODULE_SCHEMA],
+      messages: {
+        noUnsafeOperation: message,
+        [UNANCHORED_EXEMPT_FILE]: UNANCHORED_EXEMPT_MESSAGE,
+      },
+    },
+
+    create(context) {
+      const sourceCode = context.getSourceCode();
+      // Resolved per invocation, not at factory-construction time: the option is
+      // the consuming repo's, and one repo can configure the same rule
+      // differently across config blocks.
+      const targetModule = resolveSafeModule(context, safeModule);
+
+      // Only the declared implementation file(s) may call the unsafe function.
+      if (exemptMatcherFor(context)(context.getFilename())) {
+        // Still surface a malformed exemption list: the file we are standing in
+        // may be exempt only BECAUSE the entry is unanchored.
+        return {
+          Program(node) {
+            reportUnanchoredExemptEntries(context, node);
+          },
+        };
+      }
+
+      let hasUnsafeImport = false;
+      // Seeded from SCOPE, not from "did I see an import from safeModule?".
+      // A file already importing `safeFn` from the barrel needs the call
+      // rewritten but must NOT gain a second binding of the same name — that is
+      // a SyntaxError, not a redundant import. See `safe-import.cjs`.
+      let hasSafeImport = isNameAlreadyBound(sourceCode, safeFn);
+      let unsafeImportNode = null;
+      let safeImportNode = null;
+
+      return {
+        Program(node) {
+          reportUnanchoredExemptEntries(context, node);
+        },
+
+        ImportDeclaration(node) {
+          // Track unsafe module imports
+          if (moduleVariants.includes(node.source.value)) {
+            unsafeImportNode = node;
+            for (const spec of node.specifiers) {
+              if (spec.type === 'ImportSpecifier' && spec.imported.name === unsafeFn) {
+                hasUnsafeImport = true;
+              }
+            }
+          }
+
+          // Track safe module imports
+          if (node.source.value === targetModule) {
+            safeImportNode = node;
+            for (const spec of node.specifiers) {
+              if (spec.type === 'ImportSpecifier' && spec.imported.name === safeFn) {
+                hasSafeImport = true;
+              }
+            }
+          }
+        },
+
+        CallExpression(node) {
+          let isUnsafeCall = false;
+
+          // Check for direct function call: unsafeFn()
+          if (node.callee.name === unsafeFn) {
+            isUnsafeCall = true;
+          }
+
+          // Check for member expression: obj.unsafeFn()
+          if (
+            checkMemberExpression &&
+            node.callee.type === 'MemberExpression' &&
+            node.callee.property.name === unsafeFn
+          ) {
+            isUnsafeCall = true;
+          }
+
+          if (!isUnsafeCall) {
+            return;
+          }
+
+          context.report({
+            node,
+            messageId: 'noUnsafeOperation',
+            data: { safeModule: targetModule },
+            fix(fixer) {
+              const fixes = [];
+
+              // Replace unsafe call with safe call
+              if (node.callee.type === 'MemberExpression') {
+                // For obj.method(), replace just the method name
+                fixes.push(fixer.replaceText(node.callee.property, safeFn));
+              } else {
+                // For method(), replace the whole callee
+                fixes.push(fixer.replaceText(node.callee, safeFn));
+              }
+
+              // Add import if needed
+              if (!hasSafeImport) {
+                if (safeImportNode) {
+                  // Add to existing safe module import
+                  const lastSpecifier = safeImportNode.specifiers.at(-1);
+                  fixes.push(fixer.insertTextAfter(lastSpecifier, `, ${safeFn}`));
+                } else {
+                  // Create new import after unsafe import or at the top
+                  const targetNode = unsafeImportNode || sourceCode.ast.body[0];
+                  const newImport = `import { ${safeFn} } from '${targetModule}';\n`;
+                  fixes.push(fixer.insertTextAfter(targetNode, newImport));
+                }
+              }
+
+              // Remove unsafe import if it's the only specifier
+              if (hasUnsafeImport && unsafeImportNode) {
+                const unsafeSpecs = filterUnsafeSpecifiers(unsafeImportNode, unsafeFn);
+                if (unsafeImportNode.specifiers.length === 1 && unsafeSpecs.length === 1) {
+                  // Remove entire import
+                  fixes.push(fixer.remove(unsafeImportNode));
+                } else if (unsafeSpecs.length > 0) {
+                  // Remove just the unsafe specifier
+                  fixes.push(...removeUnsafeImportSpecifiers(fixer, sourceCode, unsafeImportNode, unsafeSpecs));
+                }
+              }
+
+              return fixes;
+            },
+          });
+        },
+      };
+    },
+  };
+};