rootless-config 1.0.0

package/src/cli/commands/migrate.js

@@ -0,0 +1,63 @@
+/*-------- rootless migrate — moves existing root configs into .root container --------*/
+
+import path from 'node:path'
+import { readdir } from 'node:fs/promises'
+import { createLogger } from '../../utils/logger.js'
+import { fileExists, ensureDir, atomicWrite } from '../../utils/fsUtils.js'
+import { readFile } from 'node:fs/promises'
+import { confirm } from '../../utils/prompt.js'
+import { resolveProjectRoot } from '../../core/pathResolver.js'
+
+const CONFIG_PATTERN = /\.(config|rc)\.(js|ts|mjs|cjs|json)$|\.eslintrc$|\.babelrc$/
+const ENV_PATTERN = /^\.env/
+
+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)))
+    .map(e => e.name)
+    .sort()
+}
+
+export default {
+  name: 'migrate',
+  description: 'Move existing config files from project root into .root container',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const projectRoot = await resolveProjectRoot()
+    const containerPath = path.join(projectRoot, '.root')
+
+    const candidates = await findMigratableFiles(projectRoot)
+    if (candidates.length === 0) {
+      logger.info('No config files found to migrate in project root')
+      return
+    }
+
+    logger.info(`Found ${candidates.length} migratable files:\n  ${candidates.join('\n  ')}`)
+
+    const proceed = args.yes || await confirm('Move these files to .root/?')
+    if (!proceed) {
+      logger.info('Migration cancelled')
+      return
+    }
+
+    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')
+
+      await ensureDir(destDir)
+      const content = await readFile(src, 'utf8')
+      await atomicWrite(path.join(destDir, name), content)
+
+      const rel = path.relative(path.dirname(src), path.join(containerPath, isEnv ? 'env' : 'configs', name)).replace(/\\/g, '/')
+      const relPath = rel.startsWith('.') ? rel : `./${rel}`
+      await atomicWrite(src, `export { default } from "${relPath}"\n`)
+
+      logger.success(`Migrated: ${name}`)
+    }
+
+    logger.info('Run: rootless prepare to regenerate')
+  },
+}

package/src/cli/commands/prepare.js

@@ -0,0 +1,18 @@
+/*-------- rootless prepare — scans .root, generates proxy/copy files --------*/
+
+import { preparePipeline } from '../../core/cliWrapper.js'
+
+export default {
+  name: 'prepare',
+  description: 'Scan .root container and generate proxy/copy files in project root',
+
+  async handler(args) {
+    const options = {
+      yes: args.yes ?? false,
+      no: args.no ?? false,
+      verbose: args.verbose ?? false,
+      silent: args.silent ?? false,
+    }
+    await preparePipeline(options)
+  },
+}

package/src/cli/commands/stats.js

@@ -0,0 +1,40 @@
+/*-------- rootless stats — aggregate statistics for the project --------*/
+
+import { readManifest } from '../../core/generatedManifest.js'
+import { loadHashCache } from '../../core/fileHashCache.js'
+import { hashFile } from '../../utils/hashUtils.js'
+import { fileExists } from '../../utils/fsUtils.js'
+import { resolveContainerPath, resolveProjectRoot } from '../../core/pathResolver.js'
+import { discoverFiles } from '../../core/containerLoader.js'
+
+export default {
+  name: 'stats',
+  description: 'Display aggregate project statistics',
+
+  async handler() {
+    const containerPath = await resolveContainerPath()
+    const managed = await readManifest()
+    const hashCache = await loadHashCache()
+    const files = await discoverFiles(containerPath)
+
+    const totalConfigs = (files.configs ?? []).length
+    const totalEnv = (files.env ?? []).length
+    const totalAssets = (files.assets ?? []).length
+
+    let stale = 0
+    for (const [filePath, cached] of Object.entries(hashCache.files ?? {})) {
+      if (!(await fileExists(filePath))) continue
+      const current = await hashFile(filePath).catch(() => null)
+      if (current && current !== cached) stale++
+    }
+
+    process.stdout.write('\nRootless Stats\n\n')
+    process.stdout.write(`Container:         ${containerPath}\n`)
+    process.stdout.write(`Configs detected:  ${totalConfigs}\n`)
+    process.stdout.write(`Env files:         ${totalEnv}\n`)
+    process.stdout.write(`Assets detected:   ${totalAssets}\n`)
+    process.stdout.write(`Generated files:   ${managed.length}\n`)
+    process.stdout.write(`Stale files:       ${stale}\n`)
+    process.stdout.write('\n')
+  },
+}

package/src/cli/commands/status.js

@@ -0,0 +1,47 @@
+/*-------- rootless status — shows managed files, stale files, loaded containers --------*/
+
+import { createLogger } from '../../utils/logger.js'
+import { readManifest } from '../../core/generatedManifest.js'
+import { loadHashCache } from '../../core/fileHashCache.js'
+import { hashFile } from '../../utils/hashUtils.js'
+import { fileExists } from '../../utils/fsUtils.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+import path from 'node:path'
+
+export default {
+  name: 'status',
+  description: 'Show status of generated files and container',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const containerPath = await resolveContainerPath()
+
+    process.stdout.write('\nRootless Config Status\n\n')
+    process.stdout.write(`Container: ${containerPath}\n`)
+
+    const managed = await readManifest()
+    const hashCache = await loadHashCache()
+
+    process.stdout.write(`\nGenerated files: ${managed.length}\n`)
+
+    for (const filePath of managed) {
+      const exists = await fileExists(filePath)
+      if (!exists) {
+        logger.fail(`${path.basename(filePath)} (missing)`)
+        continue
+      }
+
+      const currentHash = await hashFile(filePath).catch(() => null)
+      const cachedHash = hashCache.files[filePath]
+      const stale = currentHash && cachedHash && currentHash !== cachedHash
+
+      if (stale) {
+        process.stdout.write(` \x1b[33m~ ${path.basename(filePath)} (stale)\x1b[0m\n`)
+      } else {
+        process.stdout.write(` \x1b[32m✔ ${path.basename(filePath)}\x1b[0m\n`)
+      }
+    }
+
+    process.stdout.write('\n')
+  },
+}

package/src/cli/commands/validate.js

@@ -0,0 +1,34 @@
+/*-------- rootless validate — validates rootless.config.json structure --------*/
+
+import { createLogger } from '../../utils/logger.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+import { fileExists, readJsonFile } from '../../utils/fsUtils.js'
+import { validateConfig } from '../../core/configSchema.js'
+import path from 'node:path'
+
+export default {
+  name: 'validate',
+  description: 'Validate rootless.config.json against the expected schema',
+
+  async handler(args) {
+    const logger = createLogger({ verbose: args.verbose ?? false })
+    const containerPath = await resolveContainerPath()
+    const configPath = path.join(containerPath, 'rootless.config.json')
+
+    if (!(await fileExists(configPath))) {
+      logger.warn('No rootless.config.json found — nothing to validate')
+      return
+    }
+
+    const raw = await readJsonFile(configPath)
+    const { valid, errors } = validateConfig(raw)
+
+    if (valid) {
+      logger.success('rootless.config.json is valid')
+      return
+    }
+
+    errors.forEach(e => logger.fail(`${e.field ? `[${e.field}] ` : ''}${e.message}`))
+    process.exitCode = 1
+  },
+}

package/src/cli/commands/watch.js

@@ -0,0 +1,40 @@
+/*-------- rootless watch — watches .root and incrementally regenerates on change --------*/
+
+import { buildContext } from '../../core/cliWrapper.js'
+import { createWatcher } from '../../watch/watcher.js'
+import { createDirtySet } from '../../watch/dirtySet.js'
+import { runIncrementalRegeneration } from '../../watch/incrementalRegeneration.js'
+import { resolveContainerPath } from '../../core/pathResolver.js'
+
+export default {
+  name: 'watch',
+  description: 'Watch .root container and regenerate files on change',
+
+  async handler(args) {
+    const options = {
+      yes: true,
+      verbose: args.verbose ?? false,
+      silent: args.silent ?? false,
+    }
+
+    const ctx = await buildContext(options)
+    const containerPath = await resolveContainerPath()
+
+    ctx.logger.info(`Watching ${containerPath}`)
+
+    const dirtySet = createDirtySet(async changed => {
+      await runIncrementalRegeneration([...changed], ctx)
+    })
+
+    const watcher = createWatcher([containerPath], { ignoreInitial: true })
+    watcher.on('change', filePath => dirtySet.add(filePath))
+    watcher.on('add', filePath => dirtySet.add(filePath))
+    watcher.start()
+
+    process.on('SIGINT', async () => {
+      watcher.stop()
+      await ctx.dispose()
+      process.exit(0)
+    })
+  },
+}

package/src/cli/index.js

@@ -0,0 +1,53 @@
+/*-------- CLI application entry — bootstraps commander and routes commands --------*/
+
+import { Command } from 'commander'
+import { createCommandRegistry } from './commandRegistry.js'
+import { checkVersionCompatibility } from '../core/versionCheck.js'
+import { createLogger } from '../utils/logger.js'
+
+async function run(argv) {
+  const logger = createLogger()
+  const program = new Command()
+
+  program
+    .name('rootless')
+    .description('Store project configs in .root, generate them where tools expect them')
+    .version('1.0.0')
+
+  const registry = createCommandRegistry()
+  await registry.discover()
+
+  for (const cmd of registry.list()) {
+    const sub = program.command(cmd.name).description(cmd.description)
+
+    if (['prepare', 'watch', 'migrate'].includes(cmd.name)) {
+      sub.option('--yes', 'Auto-approve all file override prompts')
+      sub.option('--no-yes', 'Auto-decline all file override prompts')
+    }
+
+    sub.option('--verbose', 'Enable verbose output')
+    sub.option('--silent', 'Suppress all output')
+
+    sub.action(async (options) => {
+      try {
+        await cmd.handler(options)
+      } catch (err) {
+        logger.fail(err.message)
+        if (options.verbose) process.stderr.write(err.stack + '\n')
+        process.exitCode = 1
+      }
+    })
+  }
+
+  try {
+    const { compatible, projectVersion, cliVersion } = await checkVersionCompatibility().catch(() => ({ compatible: true }))
+    if (!compatible) {
+      logger.warn(`Container version ${projectVersion} may be incompatible with CLI ${cliVersion}. Run: rootless migrate`)
+    }
+  } catch {
+  }
+
+  await program.parseAsync(argv)
+}
+
+export { run }

package/src/core/cliWrapper.js

@@ -0,0 +1,106 @@
+/*-------- Shared pipeline functions reused by CLI commands and the public API --------*/
+
+import path from 'node:path'
+import { readdir } from 'node:fs/promises'
+import { createContainerLoader } from './containerLoader.js'
+import { createExecutionContext } from './executionContext.js'
+import { createPluginRegistry } from '../plugins/pluginRegistry.js'
+import { loadPlugins } from '../plugins/pluginLoader.js'
+import { validateConfig } from './configSchema.js'
+import { getGraph } from './configGraph.js'
+import { generateFiles } from './generator.js'
+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 { ValidationError } from '../types/errors.js'
+
+async function loadConfig(containerPath) {
+  const manifestPath = path.join(containerPath, 'rootless.config.json')
+  if (!(await fileExists(manifestPath))) return {}
+  const { readJsonFile } = await import('../utils/fsUtils.js')
+  return readJsonFile(manifestPath)
+}
+
+async function buildContext(options = {}) {
+  if (options.cwd) {
+    const { findProjectRoot } = await import('./rootSearch.js')
+    const root = await findProjectRoot(options.cwd)
+    const containerPath = path.join(root, '.root')
+    setContainerOverride(options.containerPath ?? containerPath)
+  }
+
+  const pluginRegistry = createPluginRegistry()
+  const containerLoader = createContainerLoader({ pluginRegistry })
+  const container = await containerLoader.load()
+
+  const config = container.manifest ?? {}
+  const { valid, errors } = validateConfig(config)
+  if (!valid) throw errors[0]
+
+  await loadPlugins(config, pluginRegistry)
+
+  return createExecutionContext({ container, pluginRegistry, options })
+}
+
+async function preparePipeline(options = {}) {
+  const ctx = await buildContext(options)
+
+  const containerPath = await resolveContainerPath()
+  const config = ctx.container.manifest ?? {}
+  const graph = await getGraph(config)
+
+  const entries = await buildGenerationEntries(containerPath, graph, ctx)
+  const projectRoot = await resolveProjectRoot()
+  const mapped = entries.map(e => ({
+    ...e,
+    target: path.join(projectRoot, path.basename(e.source)),
+  }))
+
+  const results = await generateFiles(mapped, options, ctx.logger)
+  await ctx.dispose()
+  return results
+}
+
+async function buildGenerationEntries(containerPath, graph, ctx) {
+  const entries = []
+
+  for (const node of Object.values(graph.nodes)) {
+    const plugin = ctx.pluginRegistry.resolve(node.absolutePath)[0] ?? null
+    entries.push({ source: node.absolutePath, mode: graph.mode ?? 'proxy', plugin })
+  }
+
+  const dirs = ['configs', 'env', 'assets']
+  for (const dir of dirs) {
+    const dirPath = path.join(containerPath, dir)
+    if (!(await fileExists(dirPath))) continue
+    const files = await readdir(dirPath, { withFileTypes: true })
+    for (const f of files) {
+      if (!f.isFile()) continue
+      const absPath = path.join(dirPath, f.name)
+      const alreadyIncluded = entries.some(e => e.source === absPath)
+      if (alreadyIncluded) continue
+      const plugin = ctx.pluginRegistry.resolve(absPath)[0] ?? null
+      entries.push({ source: absPath, mode: 'proxy', plugin })
+    }
+  }
+
+  return entries
+}
+
+async function cleanPipeline(options = {}) {
+  const ctx = await buildContext(options)
+  const managed = await readManifest()
+
+  for (const filePath of managed) {
+    await removeFile(filePath)
+    await removeHash(filePath)
+    await removeFromManifest(filePath)
+    ctx.logger.success(`Removed: ${path.basename(filePath)}`)
+  }
+
+  await ctx.dispose()
+  return { removed: managed }
+}
+
+export { preparePipeline, cleanPipeline, buildContext, loadConfig }

package/src/core/configGraph.js

@@ -0,0 +1,50 @@
+/*-------- Config dependency graph with hash-based cache invalidation --------*/
+
+import path from 'node:path'
+import { fileExists, readJsonFile, writeJsonFile } from '../utils/fsUtils.js'
+import { hashObject } from '../utils/hashUtils.js'
+import { resolveCachePath, resolveContainerPath } from './pathResolver.js'
+
+const GRAPH_CACHE_FILE = 'graph.json'
+
+async function buildGraph(config) {
+  const container = await resolveContainerPath()
+  const nodes = {}
+
+  const entries = Object.entries(config).filter(
+    ([k]) => !['containerPath', 'mode', 'experimental', 'plugins', 'extends'].includes(k)
+  )
+
+  for (const [name, relPath] of entries) {
+    if (typeof relPath !== 'string') continue
+    nodes[name] = {
+      name,
+      relPath,
+      absolutePath: path.join(container, relPath),
+    }
+  }
+
+  return { nodes, configHash: hashObject(config) }
+}
+
+async function loadCachedGraph() {
+  const cachePath = await resolveCachePath(GRAPH_CACHE_FILE)
+  if (!(await fileExists(cachePath))) return null
+  return readJsonFile(cachePath)
+}
+
+async function saveGraph(graph) {
+  const cachePath = await resolveCachePath(GRAPH_CACHE_FILE)
+  await writeJsonFile(cachePath, graph)
+}
+
+async function getGraph(config) {
+  const cached = await loadCachedGraph()
+  const fresh = await buildGraph(config)
+
+  if (cached && cached.configHash === fresh.configHash) return cached
+  await saveGraph(fresh)
+  return fresh
+}
+
+export { buildGraph, loadCachedGraph, saveGraph, getGraph }

package/src/core/configSchema.js

@@ -0,0 +1,45 @@
+/*-------- Validates rootless.config.json structure --------*/
+
+import { ValidationError } from '../types/errors.js'
+import { ROOT_CONFIG_SHAPE } from '../types/configTypes.js'
+
+const ALLOWED_KEYS = Object.keys(ROOT_CONFIG_SHAPE)
+
+function validateConfig(rawConfig) {
+  const errors = []
+
+  if (rawConfig === null || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+    errors.push(new ValidationError('rootless.config.json must be a JSON object', 'root'))
+    return { valid: false, errors }
+  }
+
+  if (rawConfig.containerPath !== undefined && typeof rawConfig.containerPath !== 'string') {
+    errors.push(new ValidationError('"containerPath" must be a string', 'containerPath'))
+  }
+
+  if (rawConfig.mode !== undefined && !['proxy', 'copy'].includes(rawConfig.mode)) {
+    errors.push(new ValidationError('"mode" must be "proxy" or "copy"', 'mode'))
+  }
+
+  if (rawConfig.plugins !== undefined && !Array.isArray(rawConfig.plugins)) {
+    errors.push(new ValidationError('"plugins" must be an array', 'plugins'))
+  }
+
+  if (rawConfig.remote !== undefined && !Array.isArray(rawConfig.remote)) {
+    errors.push(new ValidationError('"remote" must be an array', 'remote'))
+  }
+
+  if (rawConfig.extends !== undefined && !Array.isArray(rawConfig.extends)) {
+    errors.push(new ValidationError('"extends" must be an array', 'extends'))
+  }
+
+  if (rawConfig.experimental !== undefined) {
+    if (typeof rawConfig.experimental !== 'object' || Array.isArray(rawConfig.experimental)) {
+      errors.push(new ValidationError('"experimental" must be an object', 'experimental'))
+    }
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+export { validateConfig, ALLOWED_KEYS }

package/src/core/containerLoader.js

@@ -0,0 +1,67 @@
+/*-------- DI factory that wires together a container loading pipeline --------*/
+
+import path from 'node:path'
+import { readdir } from 'node:fs/promises'
+import { fileExists, readJsonFile } from '../utils/fsUtils.js'
+import { resolveContainerPath } from './pathResolver.js'
+import { ContainerNotFoundError } from '../types/errors.js'
+
+const MANIFEST_FILE = 'rootless.config.json'
+const VERSION_FILE = 'rootless.version'
+
+const KNOWN_DIRS = { env: 'env', configs: 'configs', assets: 'assets' }
+
+function createContainerLoader({ cache, resolver, graph, pluginRegistry } = {}) {
+  async function load() {
+    const containerPath = await resolveContainerPath()
+
+    if (!(await fileExists(containerPath))) {
+      throw new ContainerNotFoundError(containerPath)
+    }
+
+    const manifestPath = path.join(containerPath, MANIFEST_FILE)
+    const versionPath = path.join(containerPath, VERSION_FILE)
+
+    const [manifest, version, autoFiles] = await Promise.all([
+      fileExists(manifestPath).then(e => e ? readJsonFile(manifestPath) : null),
+      fileExists(versionPath).then(e => e ? readFile(versionPath) : null),
+      discoverFiles(containerPath),
+    ])
+
+    return {
+      containerPath,
+      manifest,
+      version: version ? String(version).trim() : null,
+      files: autoFiles,
+      cache,
+      resolver,
+      graph,
+      pluginRegistry,
+    }
+  }
+
+  return { load }
+}
+
+async function discoverFiles(containerPath) {
+  const results = {}
+
+  for (const [key, dir] of Object.entries(KNOWN_DIRS)) {
+    const dirPath = path.join(containerPath, dir)
+    if (!(await fileExists(dirPath))) continue
+
+    const entries = await readdir(dirPath, { withFileTypes: true })
+    results[key] = entries
+      .filter(e => e.isFile())
+      .map(e => path.join(dirPath, e.name))
+  }
+
+  return results
+}
+
+async function readFile(filePath) {
+  const { readFile: fsRead } = await import('node:fs/promises')
+  return fsRead(filePath, 'utf8')
+}
+
+export { createContainerLoader, discoverFiles }

package/src/core/executionContext.js

@@ -0,0 +1,27 @@
+/*-------- Isolated execution context per CLI command invocation --------*/
+
+import { createLogger } from '../utils/logger.js'
+
+function createExecutionContext({ container, cache, pluginRegistry, options = {} } = {}) {
+  const verbose = options.verbose ?? false
+  const silent = options.silent ?? false
+  const logger = createLogger({ verbose, silent })
+
+  let disposed = false
+
+  async function dispose() {
+    if (disposed) return
+    disposed = true
+
+    const plugins = pluginRegistry?.getAll() ?? []
+    for (const plugin of plugins) {
+      if (typeof plugin.teardown === 'function') {
+        await plugin.teardown({ logger })
+      }
+    }
+  }
+
+  return { container, cache, pluginRegistry, logger, options, dispose }
+}
+
+export { createExecutionContext }

package/src/core/fileHashCache.js

@@ -0,0 +1,39 @@
+/*-------- Per-file SHA-256 hash cache stored in .root/.cache/files.json --------*/
+
+import { fileExists, readJsonFile, writeJsonFile } from '../utils/fsUtils.js'
+import { hashFile } from '../utils/hashUtils.js'
+import { resolveCachePath } from './pathResolver.js'
+
+const CACHE_FILE = 'files.json'
+
+async function loadHashCache() {
+  const cachePath = await resolveCachePath(CACHE_FILE)
+  if (!(await fileExists(cachePath))) return { files: {} }
+  return readJsonFile(cachePath)
+}
+
+async function saveHashCache(cache) {
+  const cachePath = await resolveCachePath(CACHE_FILE)
+  await writeJsonFile(cachePath, cache)
+}
+
+async function computeAndCompare(filePath) {
+  const cache = await loadHashCache()
+  const newHash = await hashFile(filePath)
+  const prev = cache.files[filePath]
+  return { changed: prev !== newHash, newHash }
+}
+
+async function updateHash(filePath, hash) {
+  const cache = await loadHashCache()
+  cache.files[filePath] = hash
+  await saveHashCache(cache)
+}
+
+async function removeHash(filePath) {
+  const cache = await loadHashCache()
+  delete cache.files[filePath]
+  await saveHashCache(cache)
+}
+
+export { loadHashCache, saveHashCache, computeAndCompare, updateHash, removeHash }

package/src/core/generatedManifest.js

@@ -0,0 +1,35 @@
+/*-------- Tracks generated files in .root/.generated.json --------*/
+
+import { fileExists, readJsonFile, writeJsonFile } from '../utils/fsUtils.js'
+import { resolveGeneratedFilePath } from './pathResolver.js'
+
+async function readManifest() {
+  const manifestPath = await resolveGeneratedFilePath()
+  if (!(await fileExists(manifestPath))) return []
+  const data = await readJsonFile(manifestPath)
+  return Array.isArray(data.generated) ? data.generated : []
+}
+
+async function writeManifest(files) {
+  const manifestPath = await resolveGeneratedFilePath()
+  await writeJsonFile(manifestPath, { generated: files })
+}
+
+async function addToManifest(filePath) {
+  const current = await readManifest()
+  if (!current.includes(filePath)) {
+    await writeManifest([...current, filePath])
+  }
+}
+
+async function removeFromManifest(filePath) {
+  const current = await readManifest()
+  await writeManifest(current.filter(f => f !== filePath))
+}
+
+async function isManaged(filePath) {
+  const current = await readManifest()
+  return current.includes(filePath)
+}
+
+export { readManifest, writeManifest, addToManifest, removeFromManifest, isManaged }