rootless-config 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootless-config",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Store project config files outside the project root, auto-deploy them where tools expect them.",
   "type": "module",
   "bin": {

package/src/cli/commands/migrate.js

@@ -5,16 +5,29 @@ import { readdir, unlink, readFile } from 'node:fs/promises'
 import { createLogger } from '../../utils/logger.js'
 import { fileExists, ensureDir, atomicWrite, readJsonFile } from '../../utils/fsUtils.js'
 import { confirm } from '../../utils/prompt.js'
-import { patchPackageScripts } from '../../core/scriptPatcher.js'
+import { patchPackageScripts, getAllKnownFiles, NEVER_MIGRATE } from '../../core/scriptPatcher.js'
 
-const CONFIG_PATTERN = /\.(config|rc)\.(js|ts|mjs|cjs|json)$|\.eslintrc$|\.babelrc$|tsconfig.*\.json$/
-const ENV_PATTERN = /^\.env/
+// Pattern-based detection for file families not covered by the explicit known-files set
+const ENV_PATTERN      = /^\.env/                   // .env, .env.local, .env.production, etc.
+const TSCONFIG_PATTERN = /^tsconfig.*\.json$/        // tsconfig.custom.json etc.
+const DOCKERFILE_PATTERN = /^Dockerfile/            // Dockerfile.dev, Dockerfile.prod etc.
+const DOCKER_COMPOSE_PATTERN = /^docker-compose/    // docker-compose.override.yml etc.
 
 async function findMigratableFiles(projectRoot) {
+  const knownFiles = getAllKnownFiles()
   const entries = await readdir(projectRoot, { withFileTypes: true })
   return entries
-    .filter(e => e.isFile() && (CONFIG_PATTERN.test(e.name) || ENV_PATTERN.test(e.name)))
-    .filter(e => e.name !== 'package.json') // never migrate package.json
+    .filter(e => {
+      if (!e.isFile()) return false
+      if (NEVER_MIGRATE.has(e.name)) return false
+      return (
+        knownFiles.has(e.name) ||
+        ENV_PATTERN.test(e.name) ||
+        TSCONFIG_PATTERN.test(e.name) ||
+        DOCKERFILE_PATTERN.test(e.name) ||
+        DOCKER_COMPOSE_PATTERN.test(e.name)
+      )
+    })
     .map(e => e.name)
     .sort()
 }
@@ -62,18 +75,19 @@ export default {
     for (const name of candidates) {
       const src = path.join(projectRoot, name)
       const isEnv = ENV_PATTERN.test(name)
-      const destDir = path.join(containerPath, isEnv ? 'env' : 'configs')
+      const isAsset = /\.(ico|png|jpg|jpeg|svg|txt|xml|webmanifest|json)$/.test(name) &&
+        ['favicon.ico', 'robots.txt', 'sitemap.xml', 'manifest.json', 'site.webmanifest'].includes(name)
+      const destSubdir = isEnv ? 'env' : (isAsset ? 'assets' : 'configs')
+      const destDir = path.join(containerPath, destSubdir)
 
       await ensureDir(destDir)
       const content = await readFile(src, 'utf8')
       await atomicWrite(path.join(destDir, name), content)
 
       if (isCleanMode) {
-        // Clean mode: delete original — no proxy file in root
         await unlink(src)
-        logger.success(`Moved to .root/${isEnv ? 'env' : 'configs'}/${name} (deleted from root)`)
+        logger.success(`Moved to .root/${destSubdir}/${name} (deleted from root)`)
       } else {
-        // Proxy mode: replace original with re-export stub
         const rel = path.relative(path.dirname(src), path.join(destDir, name)).replace(/\\/g, '/')
         const relPath = rel.startsWith('.') ? rel : `./${rel}`
         await atomicWrite(src, `export { default } from "${relPath}"\n`)

package/src/core/cliWrapper.js

@@ -13,7 +13,7 @@ import { readManifest, removeFromManifest } from './generatedManifest.js'
 import { removeHash } from './fileHashCache.js'
 import { resolveProjectRoot, resolveContainerPath, setContainerOverride } from './pathResolver.js'
 import { fileExists, removeFile } from '../utils/fsUtils.js'
-import { patchPackageScripts } from './scriptPatcher.js'
+import { patchPackageScripts, isRootRequired } from './scriptPatcher.js'
 import { ValidationError } from '../types/errors.js'
 
 async function loadConfig(containerPath) {
@@ -50,28 +50,54 @@ async function preparePipeline(options = {}) {
   const containerPath = await resolveContainerPath()
   const config = ctx.container.manifest ?? {}
   const graph = await getGraph(config)
-  const isCleanMode = (config.mode ?? 'proxy') === 'clean'
+  const isCleanMode = (config.mode ?? 'clean') === 'clean'
 
   const projectRoot = await resolveProjectRoot()
 
   if (isCleanMode) {
-    // Clean mode: only copy .env files to root, patch package.json scripts for everything else
-    const envDir = path.join(containerPath, 'env')
+    const envDir     = path.join(containerPath, 'env')
     const configsDir = path.join(containerPath, 'configs')
+    const assetsDir  = path.join(containerPath, 'assets')
 
-    const envEntries = []
+    const copyEntries = []
+
+    // 1. env/* — all .env files always go to root
     if (await fileExists(envDir)) {
-      const envFiles = await readdir(envDir, { withFileTypes: true })
-      for (const f of envFiles) {
+      for (const f of await readdir(envDir, { withFileTypes: true })) {
         if (!f.isFile()) continue
         const absPath = path.join(envDir, f.name)
         const plugin = ctx.pluginRegistry.resolve(absPath)[0] ?? null
-        envEntries.push({ source: absPath, target: path.join(projectRoot, f.name), mode: 'copy', plugin })
+        copyEntries.push({ source: absPath, target: path.join(projectRoot, f.name), mode: 'copy', plugin })
+      }
+    }
+
+    // 2. assets/* — favicon, robots.txt, manifests etc. always go to root
+    if (await fileExists(assetsDir)) {
+      for (const f of await readdir(assetsDir, { withFileTypes: true })) {
+        if (!f.isFile()) continue
+        const absPath = path.join(assetsDir, f.name)
+        const plugin = ctx.pluginRegistry.resolve(absPath)[0] ?? null
+        copyEntries.push({ source: absPath, target: path.join(projectRoot, f.name), mode: 'copy', plugin })
+      }
+    }
+
+    // 3. configs/* — split by whether the file can be redirected via CLI flags
+    //    isRootRequired(name) = true  → copy to root (tool can't be redirected: .nvmrc, .editorconfig, etc.)
+    //    isRootRequired(name) = false → skip copy, only patch scripts below
+    if (await fileExists(configsDir)) {
+      for (const f of await readdir(configsDir, { withFileTypes: true })) {
+        if (!f.isFile()) continue
+        if (isRootRequired(f.name)) {
+          const absPath = path.join(configsDir, f.name)
+          const plugin = ctx.pluginRegistry.resolve(absPath)[0] ?? null
+          copyEntries.push({ source: absPath, target: path.join(projectRoot, f.name), mode: 'copy', plugin })
+        }
       }
     }
 
-    const results = await generateFiles(envEntries, options, ctx.logger)
+    const results = await generateFiles(copyEntries, options, ctx.logger)
 
+    // 4. Patch package.json scripts for all patchable tool configs (vite, eslint, jest, pm2, etc.)
     const patched = await patchPackageScripts(projectRoot, configsDir, ctx.logger)
     if (patched) ctx.logger.success('package.json scripts patched with --config flags')
     else ctx.logger.debug('No script patching needed')
@@ -80,7 +106,7 @@ async function preparePipeline(options = {}) {
     return results
   }
 
-  // Proxy mode (default): generate proxy/copy for every file in .root/
+  // Proxy mode: generate proxy/copy for every file in .root/
   const entries = await buildGenerationEntries(containerPath, graph, ctx)
   const mapped = entries.map(e => ({
     ...e,

package/src/core/scriptPatcher.js

@@ -1,31 +1,216 @@
-/*-------- Patches package.json scripts to use --config flags pointing to .root/ --------*/
+/*-------- Patches package.json scripts to use --config flags pointing to .root/ --------*/
 
 import path from 'node:path'
 import { readdir } from 'node:fs/promises'
 import { readJsonFile, writeJsonFile, fileExists } from '../utils/fsUtils.js'
 
+// ─── Tool definitions ────────────────────────────────────────────────────────
+
 /**
- * Known tools: what config files they use and which flag points to a config.
- * Ordered by specificity (longer command first to avoid partial matches).
+ * Tools that support a --config (or similar) flag.
+ * Matching files will NOT be copied to root — scripts get patched instead.
+ * Ordered by command specificity (longer commands first to avoid partial matches).
  */
 const TOOL_CONFIGS = [
-  { cmd: 'vite build',  flag: '--config', files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs'] },
-  { cmd: 'vite',        flag: '--config', files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs'] },
-  { cmd: 'vitest',      flag: '--config', files: ['vitest.config.js', 'vitest.config.ts', 'vitest.config.mjs'] },
-  { cmd: 'eslint',      flag: '--config', files: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'] },
-  { cmd: 'prettier',    flag: '--config', files: ['prettier.config.js', 'prettier.config.cjs', '.prettierrc.js'] },
-  { cmd: 'jest',        flag: '--config', files: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs', 'jest.config.cjs'] },
-  { cmd: 'webpack',     flag: '--config', files: ['webpack.config.js', 'webpack.config.ts', 'webpack.config.mjs'] },
-  { cmd: 'rollup',      flag: '--config', files: ['rollup.config.js', 'rollup.config.ts', 'rollup.config.mjs'] },
-  { cmd: 'tsup',        flag: '--config', files: ['tsup.config.js', 'tsup.config.ts'] },
-  { cmd: 'tsc',         flag: '--project', files: ['tsconfig.json', 'tsconfig.build.json'] },
-  { cmd: 'nodemon',     flag: '--config', files: ['nodemon.json', '.nodemonrc', 'nodemon.config.js'] },
+  // Vite
+  { cmd: 'vite build',       flag: '--config',      files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.cjs'] },
+  { cmd: 'vite preview',     flag: '--config',      files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.cjs'] },
+  { cmd: 'vite',             flag: '--config',      files: ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.cjs'] },
+  // Vitest
+  { cmd: 'vitest run',       flag: '--config',      files: ['vitest.config.js', 'vitest.config.ts', 'vitest.config.mjs'] },
+  { cmd: 'vitest',           flag: '--config',      files: ['vitest.config.js', 'vitest.config.ts', 'vitest.config.mjs'] },
+  // ESLint (v8 flat config + legacy .eslintrc variants)
+  { cmd: 'eslint',           flag: '--config',      files: ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.mjs', '.eslintrc.json', '.eslintrc.yaml', '.eslintrc.yml'] },
+  // Prettier
+  { cmd: 'prettier',         flag: '--config',      files: ['prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs', '.prettierrc', '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.json', '.prettierrc.yaml', '.prettierrc.yml'] },
+  // Stylelint
+  { cmd: 'stylelint',        flag: '--config',      files: ['stylelint.config.js', 'stylelint.config.cjs', 'stylelint.config.mjs', '.stylelintrc', '.stylelintrc.js', '.stylelintrc.json', '.stylelintrc.yaml', '.stylelintrc.yml'] },
+  // Jest
+  { cmd: 'jest',             flag: '--config',      files: ['jest.config.js', 'jest.config.cjs', 'jest.config.mjs', 'jest.config.ts', 'jest.config.json'] },
+  // Webpack
+  { cmd: 'webpack serve',    flag: '--config',      files: ['webpack.config.js', 'webpack.config.cjs', 'webpack.config.mjs', 'webpack.config.ts', 'webpack.common.js', 'webpack.dev.js', 'webpack.prod.js', 'webpack.base.js', 'webpack.config.babel.js'] },
+  { cmd: 'webpack',          flag: '--config',      files: ['webpack.config.js', 'webpack.config.cjs', 'webpack.config.mjs', 'webpack.config.ts', 'webpack.common.js', 'webpack.dev.js', 'webpack.prod.js', 'webpack.base.js', 'webpack.config.babel.js'] },
+  // Rollup
+  { cmd: 'rollup',           flag: '--config',      files: ['rollup.config.js', 'rollup.config.mjs', 'rollup.config.cjs', 'rollup.config.ts'] },
+  // tsup
+  { cmd: 'tsup',             flag: '--config',      files: ['tsup.config.js', 'tsup.config.ts', 'tsup.config.mjs'] },
+  // TypeScript compiler
+  { cmd: 'tsc',              flag: '--project',     files: ['tsconfig.json', 'tsconfig.base.json', 'tsconfig.app.json', 'tsconfig.build.json', 'tsconfig.node.json', 'tsconfig.spec.json', 'tsconfig.test.json', 'tsconfig.worker.json'] },
+  // Nodemon
+  { cmd: 'nodemon',          flag: '--config',      files: ['nodemon.json', '.nodemonrc', 'nodemon.config.js'] },
+  // Babel
+  { cmd: 'babel',            flag: '--config-file', files: ['babel.config.js', 'babel.config.cjs', 'babel.config.mjs', 'babel.config.json', '.babelrc', '.babelrc.js', '.babelrc.cjs', '.babelrc.json'] },
+  // PostCSS
+  { cmd: 'postcss',          flag: '--config',      files: ['postcss.config.js', 'postcss.config.cjs', 'postcss.config.mjs', 'postcss.config.ts'] },
+  // Tailwind CSS
+  { cmd: 'tailwindcss',      flag: '--config',      files: ['tailwind.config.js', 'tailwind.config.cjs', 'tailwind.config.mjs', 'tailwind.config.ts'] },
+  // Mocha
+  { cmd: 'mocha',            flag: '--config',      files: ['.mocharc.js', '.mocharc.cjs', '.mocharc.json', '.mocharc.yaml', '.mocharc.yml'] },
+  // nyc (Istanbul coverage)
+  { cmd: 'nyc',              flag: '--nycrc',       files: ['.nycrc', '.nycrc.json', 'nyc.config.js', 'nyc.config.cjs'] },
+  // Cypress
+  { cmd: 'cypress run',      flag: '--config-file', files: ['cypress.config.js', 'cypress.config.ts'] },
+  { cmd: 'cypress open',     flag: '--config-file', files: ['cypress.config.js', 'cypress.config.ts'] },
+  // Playwright
+  { cmd: 'playwright test',  flag: '--config',      files: ['playwright.config.js', 'playwright.config.ts'] },
+  // Astro
+  { cmd: 'astro dev',        flag: '--config',      files: ['astro.config.js', 'astro.config.mjs', 'astro.config.ts'] },
+  { cmd: 'astro build',      flag: '--config',      files: ['astro.config.js', 'astro.config.mjs', 'astro.config.ts'] },
+  { cmd: 'astro preview',    flag: '--config',      files: ['astro.config.js', 'astro.config.mjs', 'astro.config.ts'] },
+  { cmd: 'astro',            flag: '--config',      files: ['astro.config.js', 'astro.config.mjs', 'astro.config.ts'] },
+  // Biome
+  { cmd: 'biome check',      flag: '--config-path', files: ['biome.json'] },
+  { cmd: 'biome lint',       flag: '--config-path', files: ['biome.json'] },
+  { cmd: 'biome format',     flag: '--config-path', files: ['biome.json'] },
+  { cmd: 'biome ci',         flag: '--config-path', files: ['biome.json'] },
+  { cmd: 'biome',            flag: '--config-path', files: ['biome.json'] },
+]
+
+/**
+ * Tools that use the config file as a POSITIONAL argument (not a --flag).
+ */
+const POSITIONAL_TOOLS = [
+  { cmd: 'pm2 start',   files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs', 'pm2.config.js'] },
+  { cmd: 'pm2 restart', files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs', 'pm2.config.js'] },
+  { cmd: 'pm2 reload',  files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs', 'pm2.config.js'] },
+  { cmd: 'karma start', files: ['karma.conf.js', 'karma.conf.ts'] },
+  { cmd: 'karma',       files: ['karma.conf.js', 'karma.conf.ts'] },
 ]
 
 /**
- * Build a map of { cmd → relative config path } based on what actually exists in configsDir.
- * configsDir is the absolute path to .root/configs/
- * projectRoot is used to compute relative paths in scripts
+ * Files that MUST be physically present in the project root.
+ * Tools discover them by convention — no CLI redirect is possible.
+ * These are COPIED to root by `rootless prepare`.
+ */
+const ROOT_REQUIRED_FILES = new Set([
+  // Node / npm
+  '.npmrc',
+  // Node version managers
+  '.nvmrc', '.node-version',
+  // Package managers
+  '.yarnrc', '.yarnrc.yml', '.pnpmfile.cjs', 'pnpm-workspace.yaml',
+  // TypeScript (auto-discovered by ts-node, ts-jest, esbuild, IDEs, etc.)
+  'tsconfig.json', 'tsconfig.base.json', 'tsconfig.app.json', 'tsconfig.build.json',
+  'tsconfig.node.json', 'tsconfig.spec.json', 'tsconfig.test.json', 'tsconfig.worker.json',
+  'jsconfig.json',
+  // Editor
+  '.editorconfig',
+  // Git
+  '.gitignore', '.gitattributes', '.gitmodules', '.mailmap',
+  // Linting ignore files (auto-discovered, no --flag support)
+  '.eslintignore', '.prettierignore', '.stylelintignore',
+  // Parcel (auto-discovers .parcelrc from root)
+  '.parcelrc', 'parcel.config.js',
+  // Next.js (no --config flag support)
+  'next.config.js', 'next.config.mjs', 'next.config.ts',
+  'middleware.ts', 'middleware.js', 'instrumentation.ts', 'instrumentation.js',
+  // Nuxt (auto-discovered)
+  'nuxt.config.js', 'nuxt.config.ts',
+  // Vue CLI (auto-discovered)
+  'vue.config.js',
+  // Angular
+  'angular.json', 'proxy.conf.json',
+  // SvelteKit / Svelte (auto-discovered by Vite plugin from root)
+  'svelte.config.js', 'svelte.config.cjs', 'svelte.config.mjs',
+  // Remix (auto-discovered)
+  'remix.config.js', 'remix.config.mjs', 'remix.config.ts',
+  // Monorepo tools
+  'turbo.json', 'nx.json', 'workspace.json', 'project.json', 'lerna.json', 'rush.json',
+  // Build tools (auto-discovered from root)
+  '.swcrc', 'swc.config.js', 'rome.json',
+  // CSS tooling (auto-discovered by framework plugins)
+  'windicss.config.js', 'windicss.config.ts', 'unocss.config.js', 'unocss.config.ts',
+  // Browser targets
+  '.browserslistrc', 'browserslist',
+  // Commit / git hooks
+  '.huskyrc', '.huskyrc.json', '.huskyrc.js', '.huskyrc.yaml', '.huskyrc.yml',
+  'commitlint.config.js', 'commitlint.config.cjs', 'commitlint.config.mjs',
+  '.commitlintrc', '.commitlintrc.js', '.commitlintrc.json', '.commitlintrc.yaml', '.commitlintrc.yml',
+  'lint-staged.config.js', 'lint-staged.config.cjs', 'lint-staged.config.mjs',
+  '.lintstagedrc', '.lintstagedrc.js', '.lintstagedrc.json', '.lintstagedrc.cjs',
+  // Release automation
+  'release.config.js', 'release.config.cjs', 'semantic-release.config.js', '.semantic-release.json',
+  '.releaserc', '.releaserc.js', '.releaserc.json', '.releaserc.yml', '.releaserc.yaml',
+  // Semantic commit
+  '.czrc', '.cz.json',
+  // Docker
+  'Dockerfile', '.dockerignore', 'docker-compose.yml', 'docker-compose.yaml',
+  // CI
+  '.gitlab-ci.yml', 'azure-pipelines.yml',
+  // Web assets (served directly from root by web servers)
+  'robots.txt', 'sitemap.xml', 'favicon.ico', 'manifest.json', 'site.webmanifest',
+  // Documentation
+  'README.md', 'LICENSE', 'CHANGELOG.md', 'CONTRIBUTING.md', 'CODE_OF_CONDUCT.md',
+  'SECURITY.md', 'SUPPORT.md',
+  // Dependency management / update bots
+  'renovate.json', '.renovaterc', '.renovaterc.json',
+  // Misc
+  '.htaccess', 'Procfile',
+])
+
+/**
+ * Lock files and core manifests that should NEVER be migrated.
+ * They must always live in the project root and are managed by package managers.
+ */
+const NEVER_MIGRATE = new Set([
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'npm-shrinkwrap.json',
+])
+
+// ─── Helper functions ────────────────────────────────────────────────────────
+
+/**
+ * Returns all config file names known to rootless across all categories.
+ * Excludes NEVER_MIGRATE entries. Used by the migrate command.
+ */
+function getAllKnownFiles() {
+  const all = new Set()
+  for (const tool of TOOL_CONFIGS) {
+    for (const f of tool.files) all.add(f)
+  }
+  for (const tool of POSITIONAL_TOOLS) {
+    for (const f of tool.files) all.add(f)
+  }
+  for (const f of ROOT_REQUIRED_FILES) {
+    all.add(f)
+  }
+  for (const f of NEVER_MIGRATE) {
+    all.delete(f)
+  }
+  return all
+}
+
+/**
+ * Returns true if the file can be redirected via CLI flags (not copied to root).
+ */
+function isPatchable(filename) {
+  return (
+    TOOL_CONFIGS.some(t => t.files.includes(filename)) ||
+    POSITIONAL_TOOLS.some(t => t.files.includes(filename))
+  )
+}
+
+/**
+ * Returns true if the file must be physically present in the project root.
+ */
+function isRootRequired(filename) {
+  if (NEVER_MIGRATE.has(filename)) return false
+  if (ROOT_REQUIRED_FILES.has(filename)) return true
+  if (/^\.env/.test(filename)) return true           // .env.local, .env.production, etc.
+  if (/^Dockerfile/.test(filename)) return true      // Dockerfile.dev, Dockerfile.prod etc.
+  if (/^tsconfig.*\.json$/.test(filename)) return true // tsconfig.custom.json variants
+  if (/^docker-compose/.test(filename)) return true  // docker-compose.override.yml etc.
+  if (!isPatchable(filename)) return true            // unknown file → copy to root to be safe
+  return false
+}
+
+// ─── Config map building ─────────────────────────────────────────────────────
+
+/**
+ * Build a map of { cmd → { path, flag, positional } } based on files in configsDir.
  */
 async function buildConfigMap(configsDir, projectRoot) {
   let files = []
@@ -36,36 +221,52 @@ async function buildConfigMap(configsDir, projectRoot) {
   }
 
   const map = {}
+
   for (const tool of TOOL_CONFIGS) {
-    if (map[tool.cmd]) continue // already mapped (longer cmd took priority)
+    if (!tool.files.length || map[tool.cmd]) continue
     const found = tool.files.find(f => files.includes(f))
     if (!found) continue
     const abs = path.join(configsDir, found)
     const rel = path.relative(projectRoot, abs).replace(/\\/g, '/')
-    map[tool.cmd] = rel.startsWith('.') ? rel : `./${rel}`
+    map[tool.cmd] = { path: rel.startsWith('.') ? rel : `./${rel}`, flag: tool.flag, positional: false }
   }
+
+  for (const tool of POSITIONAL_TOOLS) {
+    if (map[tool.cmd]) continue
+    const found = tool.files.find(f => files.includes(f))
+    if (!found) continue
+    const abs = path.join(configsDir, found)
+    const rel = path.relative(projectRoot, abs).replace(/\\/g, '/')
+    map[tool.cmd] = { path: rel.startsWith('.') ? rel : `./${rel}`, flag: null, positional: true, originalFiles: tool.files }
+  }
+
   return map
 }
 
+// ─── Script patching ─────────────────────────────────────────────────────────
+
 /**
- * Inject --config flag into a single script string where missing.
- * Handles semicolons, &&, || (multi-command scripts).
+ * Inject --config flag (or replace positional arg) in a single script string.
  */
 function patchScriptString(script, configMap) {
-  // Process longer commands first to avoid partial matches (vite build before vite)
   const sorted = Object.entries(configMap).sort((a, b) => b[0].length - a[0].length)
 
   let result = script
-  for (const [cmd, configPath] of sorted) {
-    const tool = TOOL_CONFIGS.find(t => t.cmd === cmd)
-    if (!tool) continue
-    const flag = tool.flag
-
-    // Match the command not already followed by its flag
-    // Word boundary on left, ensure flag not already present after the cmd
-    const escapedCmd = cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')
-    const regex = new RegExp(`((?:^|[;&|\\s]))(${escapedCmd})(?!\\s+${flag.replace(/-/g, '\\-')})`, 'g')
-    result = result.replace(regex, (_, pre, match) => `${pre}${match} ${flag} ${configPath}`)
+  for (const [cmd, info] of sorted) {
+    if (info.positional) {
+      for (const file of (info.originalFiles ?? [])) {
+        const escapedFile = file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        const escapedCmd = cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')
+        const regex = new RegExp(`(${escapedCmd})\\s+${escapedFile}`, 'g')
+        result = result.replace(regex, `$1 ${info.path}`)
+      }
+    } else {
+      const flag = info.flag
+      const escapedCmd = cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')
+      const escapedFlag = flag.replace(/-/g, '\\-')
+      const regex = new RegExp(`((?:^|[;&|\\s]))(${escapedCmd})(?!\\s+${escapedFlag})`, 'g')
+      result = result.replace(regex, (_, pre, match) => `${pre}${match} ${flag} ${info.path}`)
+    }
   }
   return result
 }
@@ -95,16 +296,12 @@ async function patchPackageScripts(projectRoot, configsDir, logger) {
     }
   }
 
-  if (changed) {
-    await writeJsonFile(pkgPath, pkg)
-  }
+  if (changed) await writeJsonFile(pkgPath, pkg)
   return changed
 }
 
 /**
  * Add "prepare": "rootless prepare --yes" to project's package.json.
- * If prepare already exists and doesn't include rootless, prepends to it.
- * Returns the final prepare script value.
  */
 async function addPrepareHook(projectRoot) {
   const pkgPath = path.join(projectRoot, 'package.json')
@@ -114,7 +311,7 @@ async function addPrepareHook(projectRoot) {
   if (!pkg.scripts) pkg.scripts = {}
 
   const existing = pkg.scripts.prepare ?? ''
-  if (existing.includes('rootless prepare')) return existing // already set
+  if (existing.includes('rootless prepare')) return existing
 
   pkg.scripts.prepare = existing
     ? `rootless prepare --yes && ${existing}`
@@ -124,4 +321,14 @@ async function addPrepareHook(projectRoot) {
   return pkg.scripts.prepare
 }
 
-export { patchPackageScripts, addPrepareHook, buildConfigMap, patchScriptString }
+export {
+  patchPackageScripts,
+  addPrepareHook,
+  buildConfigMap,
+  patchScriptString,
+  isPatchable,
+  isRootRequired,
+  getAllKnownFiles,
+  NEVER_MIGRATE,
+}
+