rootless-config 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootless-config",
-  "version": "1.2.0",
+  "version": "1.4.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,22 +5,21 @@ 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, isRootRequired, isPatchable, isWebAsset, NEVER_MIGRATE } from '../../core/scriptPatcher.js'
 
-const CONFIG_PATTERN = /\.(config|rc)\.(js|ts|mjs|cjs|json)$|\.eslintrc$|\.babelrc$|tsconfig.*\.json$/
-const ENV_PATTERN = /^\.env/
-// Dot-files and special files that must be in root — auto-detected
-const DOTFILE_PATTERN = /^\.(nvmrc|node-version|npmrc|yarnrc|yarnrc\.yml|pnpmfile\.cjs|editorconfig|gitignore|gitattributes|dockerignore|browserslistrc|prettierignore|eslintignore|stylelintignore|czrc|cz\.json|commitlintrc.*|lintstagedrc.*|releaserc.*)$|^(Dockerfile.*|Procfile|browserslist)$/
+// A file is migratable when rootless knows what to do with it:
+//  - isRootRequired → must be in root (will be copied there by prepare)
+//  - isPatchable    → can be redirected via --config flag in package.json scripts
+// Anything that's NEVER_MIGRATE (lock files, package.json) is excluded.
 
 async function findMigratableFiles(projectRoot) {
   const entries = await readdir(projectRoot, { withFileTypes: true })
   return entries
-    .filter(e => e.isFile() && (
-      CONFIG_PATTERN.test(e.name) ||
-      ENV_PATTERN.test(e.name) ||
-      DOTFILE_PATTERN.test(e.name)
-    ))
-    .filter(e => e.name !== 'package.json')
+    .filter(e => {
+      if (!e.isFile()) return false
+      if (NEVER_MIGRATE.has(e.name)) return false
+      return isRootRequired(e.name) || isPatchable(e.name)
+    })
     .map(e => e.name)
     .sort()
 }
@@ -67,19 +66,18 @@ 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 isEnv = /^\.env/.test(name)
+      const destSubdir = isEnv ? 'env' : (isWebAsset(name) ? '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/scriptPatcher.js

@@ -1,92 +1,331 @@
-/*-------- 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 ────────────────────────────────────────────────────────
+
 /**
  * Tools that support a --config (or similar) flag.
- * These files can be REMOVED from root — scripts get patched instead.
- * Ordered by specificity (longer command first to avoid partial matches).
+ * 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 preview',     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 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'] },
-  { 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', 'prettier.config.mjs'] },
-  { cmd: 'jest',             flag: '--config',  files: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs', 'jest.config.cjs'] },
-  { cmd: 'webpack serve',    flag: '--config',  files: ['webpack.config.js', 'webpack.config.ts', 'webpack.config.mjs'] },
-  { 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', 'tsup.config.mjs'] },
-  { cmd: 'tsc',              flag: '--project', files: ['tsconfig.json', 'tsconfig.build.json', 'tsconfig.prod.json'] },
-  { cmd: 'nodemon',          flag: '--config',  files: ['nodemon.json', '.nodemonrc', 'nodemon.config.js'] },
-  { cmd: 'stylelint',        flag: '--config',  files: ['stylelint.config.js', 'stylelint.config.mjs', 'stylelint.config.cjs', '.stylelintrc.js', '.stylelintrc.json'] },
-  { cmd: 'next build',       flag: '--',        files: [] }, // next doesn't support --config; handled separately
-  { cmd: 'tailwindcss',      flag: '--config',  files: ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.mjs'] },
-  { cmd: 'postcss',          flag: '--config',  files: ['postcss.config.js', 'postcss.config.mjs', 'postcss.config.cjs'] },
-  { cmd: 'babel',            flag: '--config-file', files: ['babel.config.js', 'babel.config.mjs', 'babel.config.cjs', 'babel.config.json'] },
-  { cmd: 'mocha',            flag: '--config',  files: ['.mocharc.js', '.mocharc.cjs', '.mocharc.yml', '.mocharc.json', 'mocha.config.js'] },
-  { cmd: 'nyc',              flag: '--config',  files: ['.nycrc', '.nycrc.json', 'nyc.config.js', 'nyc.config.cjs'] },
-  { cmd: 'cypress run',      flag: '--config-file', files: ['cypress.config.js', 'cypress.config.ts', 'cypress.config.mjs'] },
-  { cmd: 'cypress open',     flag: '--config-file', files: ['cypress.config.js', 'cypress.config.ts', 'cypress.config.mjs'] },
-  { cmd: 'playwright test',  flag: '--config',  files: ['playwright.config.js', 'playwright.config.ts', 'playwright.config.mjs'] },
+  // 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).
- * These files can also be removed from root — the argument in the script is patched.
  */
 const POSITIONAL_TOOLS = [
-  { cmd: 'pm2 start',   files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs'] },
-  { cmd: 'pm2 restart', files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs'] },
-  { cmd: 'pm2 reload',  files: ['ecosystem.config.js', 'ecosystem.config.cjs', 'ecosystem.config.mjs'] },
+  { 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'] },
 ]
 
 /**
  * Files that MUST be physically present in the project root.
- * These cannot be redirected via CLI flags — tools discover them by convention.
- * Everything in .root/configs/ NOT matching TOOL_CONFIGS or POSITIONAL_TOOLS falls into this category,
- * but we keep an explicit list for clarity and migrate detection.
+ * 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.js version managers
+  // Node / npm
+  '.npmrc',
+  // Node version managers
   '.nvmrc', '.node-version',
   // Package managers
-  '.npmrc', '.yarnrc', '.yarnrc.yml', '.pnpmfile.cjs',
+  '.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 (root discovery via git, these are auto-found)
-  '.gitignore', '.gitattributes', '.gitmodules',
-  // Docker
-  'Dockerfile', '.dockerignore',
-  // Process / deployment
-  'Procfile',
+  // 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',
-  // Lint ignore files (eslint/prettier look for these automatically)
-  '.eslintignore', '.prettierignore', '.stylelintignore',
-  // Commitlint / lint-staged / release (auto-discovery only)
+  // 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', '.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',
-  'lint-staged.config.js', 'lint-staged.config.mjs', 'lint-staged.config.cjs',
-  '.releaserc', '.releaserc.js', '.releaserc.json', '.releaserc.yml',
-  'release.config.js', 'release.config.cjs',
-  // Semantic tooling
+  // 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',
-  // HTTPS / certs
-  '.htaccess',
-  // Web assets
+  // 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',
+  // GitHub Pages
+  '.nojekyll', 'CNAME', 'CXNAME',
+  // Hosting platform
+  '_redirects', '_headers', 'vercel.json', 'netlify.toml', 'wrangler.toml', 'fly.toml',
+  // Status / health
+  'status.json', 'health.json',
+  // NGINX / server
+  'nginx.conf', 'nginx.config',
+  // Service workers
+  'sw.js', 'service-worker.js',
+  // Web entry points
+  'index.html', 'index.htm', 'index.php',
+])
+
+// ─── Pattern-based root-required detection ───────────────────────────────────
+
+/**
+ * Regex patterns for files that MUST be physically in the project root,
+ * matched against the basename only.
+ * Used for file families whose exact names can vary
+ * (e.g. icon-192.png, 404.htm, logo-dark.svg, server.ps1 …).
+ */
+const ROOT_REQUIRED_PATTERNS = [
+  // Environment files
+  /^\.env/,
+  // Docker variants
+  /^Dockerfile(\..+)?$/,
+  /^docker-compose.*\.(yml|yaml)$/,
+  // tsconfig variants
+  /^tsconfig.*\.json$/,
+  // GitHub Pages & hosting markers
+  /^\.nojekyll$/,
+  /^CNAME$/i,
+  /^CXNAME$/i,
+  // Error pages — 404.html, 404.htm, 404.md, 500.html …
+  /^[45]\d{2}\.(html?|php|md|txt)$/,
+  // Web entry points
+  /^index\.(html?|php)$/,
+  // index-style assets — index-ui.css, index.app.js, index.min.js …
+  /^index[-.].+\.(css|js|mjs)$/,
+  // Service workers
+  /^sw\.js$/,
+  /^service-worker.*\.js$/,
+  /^workbox-.*\.js$/,
+  // Web manifests
+  /^manifest.*\.json$/,
+  /^site\.webmanifest$/,
+  // Favicon & icons
+  /^favicon(\..+)?$/,
+  /^apple-touch-icon.*\.(png|jpg)$/,
+  /^icon.*\.(png|ico|svg|jpg|jpeg)$/,
+  /^android-chrome-.*\.(png|jpg)$/,
+  /^mstile-.*\.png$/,
+  /^browserconfig\.xml$/,
+  // Social & OG images
+  /^og[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^twitter[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^social[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^opengraph.*\.(png|jpg|jpeg|webp)$/,
+  // Logo & branding
+  /^logo.*\.(png|svg|jpg|jpeg|webp)$/,
+  // Screenshots & splash screens
+  /^splash.*\.(png|jpg|jpeg)$/,
+  /^screenshot.*\.(png|jpg|jpeg)$/,
+  // Sitemaps & SEO
+  /^sitemap.*\.(xml|txt)$/,
+  // NGINX & server configs
+  /^nginx.*\.(conf|config)$/,
+  /\.nginx$/,
+  /^\.htaccess$/,
+  /^Procfile(\..+)?$/,
+  // Shell / batch scripts in root (server.ps1, server.run.cmd, start.sh …)
+  /\.ps1$/,
+  /\.sh$/,
+  /\.(bat|cmd)$/,
+  // Version manager dotfiles
+  /^\.nvmrc$/,
+  /^\.node-version$/,
+  // Git
+  /^\.gitignore$/,
+  /^\.gitattributes$/,
+  /^\.gitmodules$/,
+  /^CODEOWNERS$/,
+  // Docker misc
+  /^\.dockerignore$/,
+  // Documentation (any extension, any case)
+  /^README(\..+)?$/i,
+  /^CHANGELOG(\..+)?$/i,
+  /^OVERVIEW(\..+)?$/i,
+  /^LICENSE(\..+)?$/i,
+  /^CONTRIBUTING(\..+)?$/i,
+  /^CODE_OF_CONDUCT(\..+)?$/i,
+  /^SECURITY(\..+)?$/i,
+  /^SUPPORT(\..+)?$/i,
+  /^COPYING(\..+)?$/i,
+  /^AUTHORS(\..+)?$/i,
+  /^NOTICE(\..+)?$/i,
+  // Hosting platform
+  /^_redirects$/,
+  /^_headers$/,
+  /^vercel\.json$/,
+  /^netlify\.toml$/,
+  /^wrangler\.toml$/,
+  /^fly\.toml$/,
+  // Status / health check files
+  /^status\.json$/,
+  /^health\.json$/,
+]
+
+/**
+ * Patterns for web assets served directly from the root by a web server.
+ * Files matching these go into .root/assets/ so they get copied to root on `prepare`.
+ */
+const WEB_ASSET_PATTERNS = [
+  /^favicon(\..+)?$/,
+  /^apple-touch-icon.*\.(png|jpg)$/,
+  /^icon.*\.(png|ico|svg|jpg|jpeg)$/,
+  /^android-chrome-.*\.(png|jpg)$/,
+  /^mstile-.*\.png$/,
+  /^browserconfig\.xml$/,
+  /^og[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^twitter[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^social[-_]image.*\.(png|jpg|jpeg|webp)$/,
+  /^opengraph.*\.(png|jpg|jpeg|webp)$/,
+  /^logo.*\.(png|svg|jpg|jpeg|webp)$/,
+  /^splash.*\.(png|jpg|jpeg)$/,
+  /^screenshot.*\.(png|jpg|jpeg)$/,
+  /^[45]\d{2}\.(html?|php|md|txt)$/,
+  /^index\.(html?|php)$/,
+  /^index[-.].+\.(css|js|mjs)$/,
+  /^sw\.js$/,
+  /^service-worker.*\.js$/,
+  /^workbox-.*\.js$/,
+  /^manifest.*\.json$/,
+  /^site\.webmanifest$/,
+  /^sitemap.*\.(xml|txt)$/,
+  /^robots\.txt$/,
+  /^status\.json$/,
+  /^health\.json$/,
+  /^_redirects$/,
+  /^_headers$/,
+]
+
+/**
+ * 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 true if the file can be redirected away from root via CLI flags.
- * Files where this returns false MUST be copied to root.
+ * 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 (
@@ -96,23 +335,30 @@ function isPatchable(filename) {
 }
 
 /**
- * Returns true if the file must always be physically present in root.
+ * Returns true if the file must be physically present in the project root.
+ * Checks exact names first, then the pattern registry.
  */
 function isRootRequired(filename) {
+  if (NEVER_MIGRATE.has(filename)) return false
   if (ROOT_REQUIRED_FILES.has(filename)) return true
-  // .env* patterns
-  if (/^\.env/.test(filename)) return true
-  // Dockerfile variants: Dockerfile.dev, Dockerfile.prod etc.
-  if (/^Dockerfile/.test(filename)) return true
-  // Not patchable and not in ROOT_REQUIRED_FILES → still copy to be safe
-  if (!isPatchable(filename)) return true
+  if (ROOT_REQUIRED_PATTERNS.some(p => p.test(filename))) return true
+  if (!isPatchable(filename)) return true  // unknown file → safe default: copy to root
   return false
 }
 
 /**
- * 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
+ * Returns true if the file is a web asset that should be served
+ * directly from the project root by a web server (images, HTML, SW, manifest …).
+ * These land in .root/assets/ and are copied to root on `prepare`.
+ */
+function isWebAsset(filename) {
+  return WEB_ASSET_PATTERNS.some(p => p.test(filename))
+}
+
+// ─── Config map building ─────────────────────────────────────────────────────
+
+/**
+ * Build a map of { cmd → { path, flag, positional } } based on files in configsDir.
  */
 async function buildConfigMap(configsDir, projectRoot) {
   let files = []
@@ -124,10 +370,8 @@ async function buildConfigMap(configsDir, projectRoot) {
 
   const map = {}
 
-  // Flag-based tools
   for (const tool of TOOL_CONFIGS) {
-    if (!tool.files.length) continue
-    if (map[tool.cmd]) continue
+    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)
@@ -135,39 +379,36 @@ async function buildConfigMap(configsDir, projectRoot) {
     map[tool.cmd] = { path: rel.startsWith('.') ? rel : `./${rel}`, flag: tool.flag, positional: false }
   }
 
-  // Positional tools (pm2 etc.)
   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, originalFile: found }
+    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) {
-  // Sort by command length descending to avoid partial matches
   const sorted = Object.entries(configMap).sort((a, b) => b[0].length - a[0].length)
 
   let result = script
   for (const [cmd, info] of sorted) {
     if (info.positional) {
-      // Replace filename argument directly: pm2 start ecosystem.config.cjs → pm2 start .root/...
-      for (const file of (POSITIONAL_TOOLS.find(t => t.cmd === cmd)?.files ?? [])) {
+      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 {
-      // Flag-based: insert --config <path> after command if not already present
       const flag = info.flag
       const escapedCmd = cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+')
       const escapedFlag = flag.replace(/-/g, '\\-')
@@ -203,16 +444,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')
@@ -232,4 +469,17 @@ async function addPrepareHook(projectRoot) {
   return pkg.scripts.prepare
 }
 
-export { patchPackageScripts, addPrepareHook, buildConfigMap, patchScriptString, isPatchable, isRootRequired }
+export {
+  patchPackageScripts,
+  addPrepareHook,
+  buildConfigMap,
+  patchScriptString,
+  isPatchable,
+  isRootRequired,
+  isWebAsset,
+  getAllKnownFiles,
+  NEVER_MIGRATE,
+  ROOT_REQUIRED_PATTERNS,
+  WEB_ASSET_PATTERNS,
+}
+