rootless-config 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# rootless-config
+
+> Keep your project root clean. Store all config files in `.root/`, generate them where tools expect them.
+
+## Problem
+
+Every modern JS project accumulates a pile of config files at the root:
+
+```
+vite.config.js
+eslint.config.js
+prettier.config.js
+postcss.config.js
+tailwind.config.js
+.env
+```
+
+They aren't your code. They clutter navigation, git diffs, and onboarding.
+
+## Solution
+
+Move them into `.root/`. `rootless-config` generates proxy files (or copies) exactly where tools expect them.
+
+```
+project/
+  .root/
+    configs/
+      vite.config.js
+      eslint.config.js
+    env/
+      .env
+    assets/
+      favicon.ico
+  src/
+  package.json
+```
+
+After `rootless prepare`:
+
+```
+vite.config.js     ← proxy → .root/configs/vite.config.js
+eslint.config.js   ← proxy → .root/configs/eslint.config.js
+.env               ← copy  from .root/env/.env
+```
+
+All generated files are git-ignored automatically.
+
+## Installation
+
+```bash
+npm install -D rootless-config
+```
+
+## Quick Start
+
+```bash
+rootless init       # scaffold .root/ structure
+# move your configs into .root/configs/, .root/env/, .root/assets/
+rootless prepare    # generate proxy/copy files
+```
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "rootless prepare && vite"
+  }
+}
+```
+
+## Project Structure
+
+```
+.root/
+  configs/        ← *.config.js, *.config.ts
+  env/            ← .env, .env.production
+  assets/         ← favicon.ico, robots.txt
+  rootless.config.json
+  rootless.version
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `rootless init` | Scaffold a new `.root/` container |
+| `rootless prepare` | Generate proxy/copy files |
+| `rootless watch` | Watch `.root/` and regenerate on change |
+| `rootless clean` | Remove generated files |
+| `rootless doctor` | Health-check the container |
+| `rootless status` | Show status of generated files |
+| `rootless migrate` | Move existing configs into `.root/` |
+| `rootless inspect` | Show detected config sources |
+| `rootless graph` | Display config dependency graph |
+| `rootless validate` | Validate `rootless.config.json` |
+| `rootless debug` | Dump internal state |
+| `rootless stats` | Show project statistics |
+| `rootless benchmark` | Measure prepare pipeline timings |
+| `rootless completion` | Generate shell autocompletion |
+
+### Flags
+
+```bash
+rootless prepare --yes       # auto-approve file override prompts (CI-friendly)
+rootless prepare --no        # auto-decline file override prompts
+rootless prepare --verbose   # verbose output
+rootless prepare --silent    # suppress all output
+```
+
+## Programmatic API
+
+```js
+import { prepare, watch, clean } from 'rootless-config'
+
+await prepare()
+await prepare({ yes: true })
+
+const watcher = await watch()
+// ...
+await watcher.stop()
+
+await clean()
+```
+
+## rootless.config.json
+
+```json
+{
+  "mode": "proxy",
+  "containerPath": ".root",
+  "plugins": [],
+  "remote": [],
+  "experimental": {
+    "virtualFS": false,
+    "capsule": false
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `"proxy" \| "copy"` | `"proxy"` | Generation mode |
+| `containerPath` | `string` | `".root"` | Path to container (relative to project root) |
+| `plugins` | `string[]` | `[]` | External plugin module names |
+| `remote` | `string[]` | `[]` | Remote config URLs |
+| `experimental` | `object` | `{}` | Feature flags |
+
+## FAQ
+
+**Q: Will this break my tools?**
+Proxy mode generates `export { default } from "./.root/configs/vite.config.js"` — tools load the original file through the re-export. Copy mode duplicates the file.
+
+**Q: What about CI?**
+Use `rootless prepare --yes` or set `CI=true` in environment — overrides are auto-approved.
+
+**Q: Monorepo?**
+Place `.root/` at the monorepo root. Each sub-package finds it automatically via upward traversal. Or set `containerPath` per package.
+
+**Q: My config file already exists at root?**
+`rootless prepare` will ask `Override? (y/n)`. Existing unmanaged files are never silently overwritten.
+
+## Documentation
+
+- [Beginner Guide](docs/beginner-guide.md)
+- [Advanced Guide](docs/advanced.md)
+- [Plugin API](docs/plugin-api.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Architecture](docs/architecture.md)
+
+## License
+
+MIT

package/bin/rootless.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli/index.js'
+
+process.on('unhandledRejection', err => {
+  process.stderr.write(`[ROOTLESS] Fatal: ${err?.message ?? err}\n`)
+  process.exit(1)
+})
+
+process.on('uncaughtException', err => {
+  process.stderr.write(`[ROOTLESS] Fatal: ${err?.message ?? err}\n`)
+  process.exit(1)
+})
+
+await run(process.argv)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "rootless-config",
+  "version": "1.0.0",
+  "description": "Store project config files outside the project root, auto-deploy them where tools expect them.",
+  "type": "module",
+  "bin": {
+    "rootless": "./bin/rootless.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src bin"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "cosmiconfig": "^9.0.0",
+    "fs-extra": "^11.2.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "config",
+    "rootless",
+    "cli",
+    "devtool",
+    "zero-root"
+  ],
+  "license": "MIT"
+}

package/src/cli/commandRegistry.js

@@ -0,0 +1,42 @@
+/*-------- Auto-discovers and registers CLI commands from src/cli/commands/ --------*/
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readdir } from 'node:fs/promises'
+import { RcsError } from '../types/errors.js'
+
+const COMMANDS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'commands')
+
+function createCommandRegistry() {
+  const commands = new Map()
+
+  async function discover() {
+    const entries = await readdir(COMMANDS_DIR, { withFileTypes: true })
+    const jsFiles = entries.filter(e => e.isFile() && e.name.endsWith('.js'))
+
+    for (const file of jsFiles) {
+      const mod = await import(path.join(COMMANDS_DIR, file.name))
+      const descriptor = mod.default ?? mod
+      if (!descriptor?.name || typeof descriptor?.handler !== 'function') continue
+      commands.set(descriptor.name, descriptor)
+    }
+  }
+
+  function list() {
+    return [...commands.values()]
+  }
+
+  function get(name) {
+    return commands.get(name) ?? null
+  }
+
+  async function dispatch(name, args, context) {
+    const cmd = commands.get(name)
+    if (!cmd) throw new RcsError(`Unknown command: ${name}`, 'UNKNOWN_COMMAND')
+    return cmd.handler(args, context)
+  }
+
+  return { discover, list, get, dispatch }
+}
+
+export { createCommandRegistry }

package/src/cli/commands/benchmark.js

@@ -0,0 +1,43 @@
+/*-------- rootless benchmark — measures prepare pipeline phase timings --------*/
+
+import { createLogger } from '../../utils/logger.js'
+import { buildContext, loadConfig } from '../../core/cliWrapper.js'
+import { getGraph } from '../../core/configGraph.js'
+import { preparePipeline } from '../../core/cliWrapper.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+
+async function time(label, fn) {
+  const start = performance.now()
+  await fn()
+  return { label, ms: (performance.now() - start).toFixed(2) }
+}
+
+export default {
+  name: 'benchmark',
+  description: 'Measure prepare pipeline phase timings',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const timings = []
+
+    await time('total prepare', async () => {
+      const containerPath = await resolveContainerPath()
+
+      const configTiming = await time('config load', () => loadConfig(containerPath))
+      timings.push(configTiming)
+
+      const config = await loadConfig(containerPath)
+      const graphTiming = await time('graph build', () => getGraph(config))
+      timings.push(graphTiming)
+
+      const pipeTiming = await time('full prepare pipeline', () => preparePipeline({ yes: true, silent: true }))
+      timings.push(pipeTiming)
+    }).then(t => timings.push(t))
+
+    process.stdout.write('\nBenchmark Results\n\n')
+    for (const { label, ms } of timings) {
+      process.stdout.write(`  ${label.padEnd(30)} ${ms}ms\n`)
+    }
+    process.stdout.write('\n')
+  },
+}

package/src/cli/commands/clean.js

@@ -0,0 +1,16 @@
+/*-------- rootless clean — removes only files tracked in .generated.json --------*/
+
+import { cleanPipeline } from '../../core/cliWrapper.js'
+
+export default {
+  name: 'clean',
+  description: 'Remove generated files tracked in .root/.generated.json',
+
+  async handler(args) {
+    const options = {
+      verbose: args.verbose ?? false,
+      silent: args.silent ?? false,
+    }
+    await cleanPipeline(options)
+  },
+}

package/src/cli/commands/completion.js

@@ -0,0 +1,59 @@
+/*-------- rootless completion — generates shell autocompletion scripts --------*/
+
+import { createCommandRegistry } from '../commandRegistry.js'
+
+const SHELLS = ['bash', 'zsh', 'fish']
+
+function generateBash(commands) {
+  const names = commands.map(c => c.name).join(' ')
+  return `
+_rootless_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  COMPREPLY=($(compgen -W "${names}" -- "$cur"))
+}
+complete -F _rootless_completions rootless
+`.trim()
+}
+
+function generateZsh(commands) {
+  const entries = commands.map(c => `    '${c.name}:${c.description}'`).join('\n')
+  return `
+#compdef rootless
+_rootless() {
+  local -a commands
+  commands=(
+${entries}
+  )
+  _describe 'command' commands
+}
+_rootless "$@"
+`.trim()
+}
+
+function generateFish(commands) {
+  return commands
+    .map(c => `complete -c rootless -n '__fish_use_subcommand' -a '${c.name}' -d '${c.description}'`)
+    .join('\n')
+}
+
+const GENERATORS = { bash: generateBash, zsh: generateZsh, fish: generateFish }
+
+export default {
+  name: 'completion',
+  description: 'Generate shell autocompletion script (bash, zsh, fish)',
+
+  async handler(args) {
+    const shell = args._[0] ?? 'bash'
+    if (!SHELLS.includes(shell)) {
+      process.stderr.write(`Unknown shell: ${shell}. Supported: ${SHELLS.join(', ')}\n`)
+      process.exitCode = 1
+      return
+    }
+
+    const registry = createCommandRegistry()
+    await registry.discover()
+    const commands = registry.list()
+
+    process.stdout.write(GENERATORS[shell](commands) + '\n')
+  },
+}

package/src/cli/commands/debug.js

@@ -0,0 +1,50 @@
+/*-------- rootless debug — dumps full internal state for diagnostics --------*/
+
+import { createLogger } from '../../utils/logger.js'
+import { resolveProjectRoot, resolveContainerPath, resolveCachePath } from '../../core/pathResolver.js'
+import { loadHashCache } from '../../core/fileHashCache.js'
+import { readManifest } from '../../core/generatedManifest.js'
+import { checkVersionCompatibility } from '../../core/versionCheck.js'
+import { loadCachedGraph } from '../../core/configGraph.js'
+import { fileExists } from '../../utils/fsUtils.js'
+import path from 'node:path'
+
+export default {
+  name: 'debug',
+  description: 'Dump internal state: paths, cache, graph, version info',
+
+  async handler() {
+    const projectRoot = await resolveProjectRoot()
+    const containerPath = await resolveContainerPath()
+    const cachePath = await resolveCachePath()
+
+    process.stdout.write('\nRootless Debug Dump\n')
+    process.stdout.write('===================\n\n')
+    process.stdout.write(`Project root:    ${projectRoot}\n`)
+    process.stdout.write(`Container path:  ${containerPath}\n`)
+    process.stdout.write(`Cache path:      ${cachePath}\n\n`)
+
+    const { cliVersion, projectVersion, compatible } = await checkVersionCompatibility()
+    process.stdout.write(`CLI version:     ${cliVersion}\n`)
+    process.stdout.write(`Container ver:   ${projectVersion ?? 'none'}\n`)
+    process.stdout.write(`Compatible:      ${compatible}\n\n`)
+
+    const managed = await readManifest()
+    process.stdout.write(`Managed files (${managed.length}):\n`)
+    for (const f of managed) process.stdout.write(`  ${path.relative(projectRoot, f)}\n`)
+
+    const hashCache = await loadHashCache()
+    const hashEntries = Object.entries(hashCache.files ?? {})
+    process.stdout.write(`\nHash cache entries: ${hashEntries.length}\n`)
+
+    const graph = await loadCachedGraph()
+    if (graph) {
+      const nodeCount = Object.keys(graph.nodes ?? {}).length
+      process.stdout.write(`\nCached graph: ${nodeCount} nodes (hash: ${graph.configHash ?? '?'})\n`)
+    } else {
+      process.stdout.write('\nCached graph: none\n')
+    }
+
+    process.stdout.write('\n')
+  },
+}

package/src/cli/commands/doctor.js

@@ -0,0 +1,63 @@
+/*-------- rootless doctor — health checks for container structure and config --------*/
+
+import path from 'node:path'
+import { createLogger } from '../../utils/logger.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+import { fileExists } from '../../utils/fsUtils.js'
+import { validateConfig } from '../../core/configSchema.js'
+import { checkVersionCompatibility } from '../../core/versionCheck.js'
+
+export default {
+  name: 'doctor',
+  description: 'Check .root container structure, config validity, and version compatibility',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    let allOk = true
+
+    const containerPath = await resolveContainerPath()
+    const containerExists = await fileExists(containerPath)
+
+    if (!containerExists) {
+      logger.fail(`.root container not found at: ${containerPath}`)
+      logger.info('Run: rootless init')
+      process.exitCode = 1
+      return
+    }
+    logger.success(`.root found: ${containerPath}`)
+
+    const manifestPath = path.join(containerPath, 'rootless.config.json')
+    if (await fileExists(manifestPath)) {
+      const { readJsonFile } = await import('../../utils/fsUtils.js')
+      const raw = await readJsonFile(manifestPath)
+      const { valid, errors } = validateConfig(raw)
+      if (!valid) {
+        errors.forEach(e => logger.fail(`Config error: ${e.message}`))
+        allOk = false
+      } else {
+        logger.success('rootless.config.json is valid')
+      }
+    } else {
+      logger.warn('No rootless.config.json found — will use auto-discovery')
+    }
+
+    const { compatible, projectVersion, cliVersion } = await checkVersionCompatibility()
+    if (!compatible) {
+      logger.fail(`Version mismatch: container=${projectVersion}, cli=${cliVersion}`)
+      logger.info('Run: rootless migrate')
+      allOk = false
+    } else {
+      logger.success(`Version compatible (${cliVersion})`)
+    }
+
+    const knownDirs = ['configs', 'env', 'assets']
+    for (const dir of knownDirs) {
+      const dirPath = path.join(containerPath, dir)
+      if (await fileExists(dirPath)) {
+        logger.success(`Found: .root/${dir}/`)
+      }
+    }
+
+    if (!allOk) process.exitCode = 1
+  },
+}

package/src/cli/commands/graph.js

@@ -0,0 +1,34 @@
+/*-------- rootless graph — renders config dependency graph as ASCII tree --------*/
+
+import { createLogger } from '../../utils/logger.js'
+import { buildContext, loadConfig } from '../../core/cliWrapper.js'
+import { getGraph } from '../../core/configGraph.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+import path from 'node:path'
+
+function renderGraph(graph) {
+  const nodes = Object.values(graph.nodes)
+  if (nodes.length === 0) return 'No config nodes found.'
+
+  return nodes
+    .map((node, i) => {
+      const isLast = i === nodes.length - 1
+      return `${isLast ? '└─' : '├─'} ${node.name}: .root/${node.relPath}`
+    })
+    .join('\n')
+}
+
+export default {
+  name: 'graph',
+  description: 'Display the config dependency graph',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const containerPath = await resolveContainerPath()
+    const config = await loadConfig(containerPath)
+    const graph = await getGraph(config)
+
+    process.stdout.write('\nConfig Dependency Graph\n\n')
+    process.stdout.write(renderGraph(graph) + '\n\n')
+  },
+}

package/src/cli/commands/init.js

@@ -0,0 +1,53 @@
+/*-------- rootless init — scaffolds a new .root container structure --------*/
+
+import path from 'node:path'
+import { createLogger } from '../../utils/logger.js'
+import { fileExists, ensureDir, atomicWrite, writeJsonFile } from '../../utils/fsUtils.js'
+import { confirm } from '../../utils/prompt.js'
+import { resolveProjectRoot } from '../../core/pathResolver.js'
+import { getLibraryVersion } from '../../core/versionCheck.js'
+
+const DIRS = ['configs', 'env', 'assets']
+
+const DEFAULT_CONFIG = {
+  mode: 'proxy',
+  experimental: {
+    virtualFS: false,
+    capsule: false,
+    profiles: false,
+    remoteConfigs: false,
+  },
+}
+
+export default {
+  name: 'init',
+  description: 'Interactively scaffold a new .root container in the project',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const projectRoot = await resolveProjectRoot()
+    const containerPath = path.join(projectRoot, '.root')
+
+    if (await fileExists(containerPath)) {
+      const proceed = await confirm('.root already exists. Reinitialize?')
+      if (!proceed) {
+        logger.info('Init cancelled')
+        return
+      }
+    }
+
+    for (const dir of DIRS) {
+      await ensureDir(path.join(containerPath, dir))
+      logger.success(`Created: .root/${dir}/`)
+    }
+
+    await writeJsonFile(path.join(containerPath, 'rootless.config.json'), DEFAULT_CONFIG)
+    logger.success('Created: .root/rootless.config.json')
+
+    await atomicWrite(path.join(containerPath, 'rootless.version'), getLibraryVersion())
+    logger.success('Created: .root/rootless.version')
+
+    logger.info('Done. Move your config files into .root/configs/, .root/env/, or .root/assets/')
+    logger.info('Then run: rootless prepare')
+  },
+}

package/src/cli/commands/inspect.js

@@ -0,0 +1,48 @@
+/*-------- rootless inspect — shows resolved config sources --------*/
+
+import path from 'node:path'
+import { createLogger } from '../../utils/logger.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+import { fileExists } from '../../utils/fsUtils.js'
+import { discoverFiles } from '../../core/containerLoader.js'
+
+export default {
+  name: 'inspect',
+  description: 'Show all detected config sources and their paths in the container',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const containerPath = await resolveContainerPath()
+
+    if (!(await fileExists(containerPath))) {
+      logger.fail(`Container not found: ${containerPath}`)
+      process.exitCode = 1
+      return
+    }
+
+    process.stdout.write('\nConfig Inspector\n\n')
+
+    const files = await discoverFiles(containerPath)
+    for (const [category, filePaths] of Object.entries(files)) {
+      process.stdout.write(`[${category}]\n`)
+      for (const fp of filePaths) {
+        const rel = path.relative(containerPath, fp)
+        process.stdout.write(`  ${path.basename(fp)}\n    source: .root/${rel.replace(/\\/g, '/')}\n`)
+      }
+    }
+
+    const manifestPath = path.join(containerPath, 'rootless.config.json')
+    if (await fileExists(manifestPath)) {
+      const { readJsonFile } = await import('../../utils/fsUtils.js')
+      const manifest = await readJsonFile(manifestPath)
+      process.stdout.write('\n[manifest entries]\n')
+      for (const [key, val] of Object.entries(manifest)) {
+        if (typeof val === 'string') {
+          process.stdout.write(`  ${key}: .root/${val}\n`)
+        }
+      }
+    }
+
+    process.stdout.write('\n')
+  },
+}