rootless-config 1.0.0

package/src/core/generator.js

@@ -0,0 +1,59 @@
+/*-------- Single entry point for all file generation — proxy and copy modes --------*/
+
+import path from 'node:path'
+import { fileExists, atomicWrite, copyFile } from '../utils/fsUtils.js'
+import { computeAndCompare, updateHash } from './fileHashCache.js'
+import { addToManifest, isManaged } from './generatedManifest.js'
+import { resolveOverrideStrategy } from './overrideStrategy.js'
+
+const PROXY_TEMPLATE = (sourcePath) =>
+  `export { default } from "${sourcePath}"\n`
+
+async function generateFile({ source, target, mode = 'proxy', plugin, options = {}, logger }) {
+  const targetExists = await fileExists(target)
+
+  if (targetExists && !(await isManaged(target))) {
+    const shouldOverride = await resolveOverrideStrategy(target, options)
+    if (!shouldOverride) {
+      logger?.info(`Skipped: ${path.basename(target)} (user declined override)`)
+      return { skipped: true, target }
+    }
+  }
+
+  if (targetExists) {
+    const { changed } = await computeAndCompare(source)
+    if (!changed) {
+      logger?.debug(`Unchanged: ${path.basename(target)}`)
+      return { skipped: true, target, reason: 'unchanged' }
+    }
+  }
+
+  if (plugin?.generate) {
+    const content = await plugin.generate(source, { mode, target, options })
+    await atomicWrite(target, content)
+  } else if (mode === 'proxy') {
+    const rel = path.relative(path.dirname(target), source).replace(/\\/g, '/')
+    const relPath = rel.startsWith('.') ? rel : `./${rel}`
+    await atomicWrite(target, PROXY_TEMPLATE(relPath))
+  } else {
+    await copyFile(source, target)
+  }
+
+  const { newHash } = await computeAndCompare(source)
+  await updateHash(source, newHash)
+  await addToManifest(target)
+
+  logger?.success(`${path.basename(target)} generated`)
+  return { skipped: false, target }
+}
+
+async function generateFiles(entries, options = {}, logger) {
+  const sorted = [...entries].sort((a, b) => a.target.localeCompare(b.target))
+  const results = []
+  for (const entry of sorted) {
+    results.push(await generateFile({ ...entry, options, logger }))
+  }
+  return results
+}
+
+export { generateFile, generateFiles }

package/src/core/overrideStrategy.js

@@ -0,0 +1,15 @@
+/*-------- Resolves override strategy for file conflict detection --------*/
+
+import { confirm } from '../utils/prompt.js'
+
+async function resolveOverrideStrategy(filePath, options = {}) {
+  if (options.yes === true) return true
+  if (options.no === true) return false
+
+  const isCI = process.env.CI !== undefined && process.env.CI !== ''
+  if (isCI && options.yes === undefined) return true
+
+  return confirm(`File exists: ${filePath}\nOverride?`)
+}
+
+export { resolveOverrideStrategy }

package/src/core/pathResolver.js

@@ -0,0 +1,91 @@
+/*-------- Single source of truth for all path resolution in the project --------*/
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readFile } from 'node:fs/promises'
+import { findProjectRoot } from './rootSearch.js'
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+let _projectRoot = null
+let _containerPath = null
+let _containerOverride = null
+
+function resetPathResolver() {
+  _projectRoot = null
+  _containerPath = null
+  _containerOverride = null
+}
+
+function setContainerOverride(absolutePath) {
+  _containerOverride = absolutePath
+}
+
+async function resolveProjectRoot() {
+  if (_projectRoot) return _projectRoot
+  if (_containerOverride) {
+    const nodePath = await import('node:path')
+    _projectRoot = nodePath.default.dirname(_containerOverride)
+    return _projectRoot
+  }
+  _projectRoot = await findProjectRoot(process.cwd())
+  return _projectRoot
+}
+
+async function resolveContainerPath() {
+  if (_containerPath) return _containerPath
+  if (_containerOverride) {
+    _containerPath = _containerOverride
+    return _containerPath
+  }
+
+  const projectRoot = await resolveProjectRoot()
+  const configPath = path.resolve(projectRoot, 'rootless.config.json')
+
+  const containerFromConfig = await readContainerPathFromConfig(configPath)
+  _containerPath = containerFromConfig
+    ? path.resolve(projectRoot, containerFromConfig)
+    : path.resolve(projectRoot, '.root')
+
+  return _containerPath
+}
+
+async function readContainerPathFromConfig(configPath) {
+  try {
+    const raw = await readFile(configPath, 'utf8')
+    const config = JSON.parse(raw)
+    return config.containerPath ?? null
+  } catch {
+    return null
+  }
+}
+
+async function resolveCachePath(subPath) {
+  const container = await resolveContainerPath()
+  const base = path.join(container, '.cache')
+  return subPath ? path.join(base, subPath) : base
+}
+
+async function resolveGeneratedFilePath() {
+  const container = await resolveContainerPath()
+  return path.join(container, '.generated.json')
+}
+
+async function resolveSourceFilePath(relativePath) {
+  const container = await resolveContainerPath()
+  return path.join(container, relativePath)
+}
+
+function resolvePackageRoot() {
+  return PKG_ROOT
+}
+
+export {
+  resolveProjectRoot,
+  resolveContainerPath,
+  resolveCachePath,
+  resolveGeneratedFilePath,
+  resolveSourceFilePath,
+  resolvePackageRoot,
+  setContainerOverride,
+  resetPathResolver,
+}

package/src/core/remoteLoader.js

@@ -0,0 +1,64 @@
+/*-------- Parallel remote config fetching with TTL cache --------*/
+
+import path from 'node:path'
+import { fileExists, readJsonFile, writeJsonFile, atomicWrite, ensureDir } from '../utils/fsUtils.js'
+import { readFile } from 'node:fs/promises'
+import { hashString } from '../utils/hashUtils.js'
+import { resolveCachePath } from './pathResolver.js'
+import { RemoteError } from '../types/errors.js'
+
+const TTL_MS = 60 * 60 * 1000
+const REMOTE_CACHE_DIR = 'remote'
+const META_FILE = 'remote-meta.json'
+
+async function loadMeta() {
+  const metaPath = await resolveCachePath(META_FILE)
+  if (!(await fileExists(metaPath))) return {}
+  return readJsonFile(metaPath)
+}
+
+async function saveMeta(meta) {
+  const metaPath = await resolveCachePath(META_FILE)
+  await writeJsonFile(metaPath, meta)
+}
+
+async function fetchOne(url) {
+  const response = await fetch(url)
+  if (!response.ok) throw new RemoteError(`HTTP ${response.status} fetching ${url}`, url)
+  return response.text()
+}
+
+async function loadRemoteConfigs(urls = []) {
+  const remoteDir = await resolveCachePath(REMOTE_CACHE_DIR)
+  await ensureDir(remoteDir)
+
+  const meta = await loadMeta()
+  const now = Date.now()
+
+  const tasks = urls.map(async url => {
+    const key = hashString(url)
+    const cachedFile = path.join(remoteDir, key)
+    const entry = meta[key]
+
+    if (entry && now - entry.fetchedAt < TTL_MS && (await fileExists(cachedFile))) {
+      const content = await readFile(cachedFile, 'utf8')
+      return { url, content, fromCache: true }
+    }
+
+    const content = await fetchOne(url)
+    await atomicWrite(cachedFile, content)
+    meta[key] = { url, fetchedAt: now }
+    return { url, content, fromCache: false }
+  })
+
+  const results = await Promise.all(tasks)
+  await saveMeta(meta)
+  return results
+}
+
+async function clearRemoteCache() {
+  const metaPath = await resolveCachePath(META_FILE)
+  await writeJsonFile(metaPath, {})
+}
+
+export { loadRemoteConfigs, clearRemoteCache }

package/src/core/rootSearch.js

@@ -0,0 +1,36 @@
+/*-------- Upward directory traversal to locate the nearest .root container --------*/
+
+import path from 'node:path'
+import { access, constants } from 'node:fs/promises'
+import { ContainerNotFoundError } from '../types/errors.js'
+
+const GIT_MARKER = '.git'
+const CONTAINER_NAME = '.root'
+
+async function exists(dirPath) {
+  try {
+    await access(dirPath, constants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function findProjectRoot(startDir) {
+  let current = path.resolve(startDir)
+
+  while (true) {
+    const candidate = path.join(current, CONTAINER_NAME)
+    if (await exists(candidate)) return current
+
+    const parent = path.dirname(current)
+    if (parent === current) throw new ContainerNotFoundError(startDir)
+
+    const hasGit = await exists(path.join(current, GIT_MARKER))
+    if (hasGit) throw new ContainerNotFoundError(startDir)
+
+    current = parent
+  }
+}
+
+export { findProjectRoot }

package/src/core/versionCheck.js

@@ -0,0 +1,42 @@
+/*-------- Reads .root/rootless.version and checks library compatibility --------*/
+
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { fileExists } from '../utils/fsUtils.js'
+import { readFile } from 'node:fs/promises'
+import { resolveContainerPath } from './pathResolver.js'
+
+const require = createRequire(import.meta.url)
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+
+function getLibraryVersion() {
+  try {
+    const pkg = require(path.join(PKG_ROOT, 'package.json'))
+    return pkg.version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+function parseMajor(version) {
+  return parseInt(version.split('.')[0], 10)
+}
+
+async function checkVersionCompatibility() {
+  const container = await resolveContainerPath()
+  const versionFile = path.join(container, 'rootless.version')
+  const cliVersion = getLibraryVersion()
+
+  if (!(await fileExists(versionFile))) {
+    return { compatible: true, projectVersion: null, cliVersion }
+  }
+
+  const raw = await readFile(versionFile, 'utf8')
+  const projectVersion = raw.trim()
+  const compatible = parseMajor(cliVersion) === parseMajor(projectVersion)
+
+  return { compatible, projectVersion, cliVersion }
+}
+
+export { checkVersionCompatibility, getLibraryVersion }

package/src/experimental/capsule.js

@@ -0,0 +1,11 @@
+/*-------- Capsule stub — experimental.capsule = false --------*/
+
+function createCapsule() {
+  return {
+    enabled: false,
+    pack: async () => { throw new Error('Capsule feature is experimental and disabled. Set experimental.capsule = true to enable.') },
+    unpack: async () => { throw new Error('Capsule feature is experimental and disabled. Set experimental.capsule = true to enable.') },
+  }
+}
+
+export { createCapsule }

package/src/experimental/index.js

@@ -0,0 +1,20 @@
+/*-------- Experimental feature registry — reads the experimental block from config --------*/
+
+const DEFAULTS = {
+  virtualFS: false,
+  capsule: false,
+  profiles: false,
+  remoteConfigs: false,
+}
+
+function createExperimentalRegistry(config = {}) {
+  const flags = { ...DEFAULTS, ...(config.experimental ?? {}) }
+
+  function isEnabled(name) {
+    return flags[name] === true
+  }
+
+  return { isEnabled, flags }
+}
+
+export { createExperimentalRegistry }

package/src/experimental/virtualFS.js

@@ -0,0 +1,13 @@
+/*-------- Virtual Filesystem stub — experimental.virtualFS = false --------*/
+
+function createVirtualFS() {
+  return {
+    enabled: false,
+    read: async () => null,
+    write: async () => {},
+    flush: async () => {},
+    list: async () => [],
+  }
+}
+
+export { createVirtualFS }

package/src/index.js

@@ -0,0 +1,39 @@
+/*-------- Public programmatic API --------*/
+
+import { preparePipeline, cleanPipeline, 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'
+
+async function prepare(options = {}) {
+  return preparePipeline(options)
+}
+
+async function clean(options = {}) {
+  return cleanPipeline(options)
+}
+
+async function watch(options = {}) {
+  const ctx = await buildContext({ yes: true, ...options })
+  const containerPath = await resolveContainerPath()
+
+  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()
+
+  return {
+    stop: async () => {
+      watcher.stop()
+      dirtySet.clear()
+      await ctx.dispose()
+    },
+  }
+}
+
+export { prepare, watch, clean }

package/src/plugins/builtins/assetPlugin.js

@@ -0,0 +1,34 @@
+/*-------- Built-in asset plugin — handles static assets like favicon.ico, robots.txt --------*/
+
+const ASSET_NAMES = new Set(['favicon.ico', 'robots.txt', 'manifest.json', 'sitemap.xml'])
+const ASSET_EXTENSIONS = new Set(['.ico', '.png', '.jpg', '.jpeg', '.svg', '.webp', '.gif'])
+
+const assetPlugin = {
+  name: 'asset',
+  priority: 10,
+
+  match(filePath) {
+    const base = filePath.split(/[\\/]/).pop() ?? ''
+    const ext = '.' + base.split('.').pop()
+    return ASSET_NAMES.has(base) || ASSET_EXTENSIONS.has(ext)
+  },
+
+  async load(filePath) {
+    const { readFile } = await import('node:fs/promises')
+    return readFile(filePath)
+  },
+
+  async transform(content) {
+    return content
+  },
+
+  async generate(source, { target }) {
+    const { copyFile } = await import('../../utils/fsUtils.js')
+    await copyFile(source, target)
+    return null
+  },
+
+  async teardown() {},
+}
+
+export { assetPlugin }

package/src/plugins/builtins/configPlugin.js

@@ -0,0 +1,38 @@
+/*-------- Built-in config plugin — handles *.config.js / *.config.ts — full lifecycle --------*/
+
+import path from 'node:path'
+
+const CONFIG_PATTERN = /\.config\.(js|ts|mjs|cjs)$/
+
+const configPlugin = {
+  name: 'config',
+  priority: 15,
+
+  match(filePath) {
+    return CONFIG_PATTERN.test(filePath)
+  },
+
+  async load(filePath) {
+    const { readFile } = await import('node:fs/promises')
+    return readFile(filePath, 'utf8')
+  },
+
+  async transform(content) {
+    return content
+  },
+
+  async generate(source, { target, mode = 'proxy' }) {
+    if (mode === 'copy') {
+      const content = await configPlugin.load(source)
+      return configPlugin.transform(content)
+    }
+
+    const rel = path.relative(path.dirname(target), source).replace(/\\/g, '/')
+    const relPath = rel.startsWith('.') ? rel : `./${rel}`
+    return `export { default } from "${relPath}"\n`
+  },
+
+  async teardown() {},
+}
+
+export { configPlugin }

package/src/plugins/builtins/envPlugin.js

@@ -0,0 +1,33 @@
+/*-------- Built-in env plugin — handles .env files — full lifecycle --------*/
+
+import { readFile } from 'node:fs/promises'
+import { atomicWrite } from '../../utils/fsUtils.js'
+
+const envPlugin = {
+  name: 'env',
+  priority: 20,
+
+  match(filePath) {
+    const base = filePath.split(/[\\/]/).pop() ?? ''
+    return base === '.env' || base.startsWith('.env.')
+  },
+
+  async load(filePath) {
+    return readFile(filePath, 'utf8')
+  },
+
+  async transform(content) {
+    return content
+  },
+
+  async generate(source, { target }) {
+    const content = await envPlugin.load(source)
+    const transformed = await envPlugin.transform(content)
+    await atomicWrite(target, transformed)
+    return transformed
+  },
+
+  async teardown() {},
+}
+
+export { envPlugin }

package/src/plugins/builtins/index.js

@@ -0,0 +1,9 @@
+/*-------- Re-exports all built-in plugins as a registry-ready array --------*/
+
+import { envPlugin } from './envPlugin.js'
+import { configPlugin } from './configPlugin.js'
+import { assetPlugin } from './assetPlugin.js'
+
+const BUILTIN_PLUGINS = [assetPlugin, configPlugin, envPlugin]
+
+export { BUILTIN_PLUGINS }

package/src/plugins/pluginLoader.js

@@ -0,0 +1,35 @@
+/*-------- Discovers, validates, and loads plugins into a registry --------*/
+
+import { assertValidPlugin } from '../types/pluginInterface.js'
+import { PluginError } from '../types/errors.js'
+import { BUILTIN_PLUGINS } from './builtins/index.js'
+
+async function loadPlugins(config = {}, registry) {
+  for (const plugin of BUILTIN_PLUGINS) {
+    registry.register(plugin, 'builtin')
+  }
+
+  const externalDefs = config.plugins ?? []
+  for (const def of externalDefs) {
+    const moduleName = typeof def === 'string' ? def : def.name
+    const pluginOptions = typeof def === 'object' ? def.options ?? {} : {}
+
+    let mod
+    try {
+      mod = await import(moduleName)
+    } catch (err) {
+      throw new PluginError(`Cannot load plugin module "${moduleName}": ${err.message}`, moduleName)
+    }
+
+    const factory = mod.default ?? mod
+    if (typeof factory !== 'function') {
+      throw new PluginError(`Plugin "${moduleName}" must export a factory function`, moduleName)
+    }
+
+    const plugin = factory(pluginOptions)
+    assertValidPlugin(plugin, 'external')
+    registry.register(plugin, 'external')
+  }
+}
+
+export { loadPlugins }

package/src/plugins/pluginRegistry.js

@@ -0,0 +1,36 @@
+/*-------- Central plugin registry — sorted by priority before execution --------*/
+
+import { assertValidPlugin } from '../types/pluginInterface.js'
+import { PluginError } from '../types/errors.js'
+
+function createPluginRegistry() {
+  const plugins = new Map()
+
+  function register(plugin, type = 'external') {
+    assertValidPlugin(plugin, type)
+    if (plugins.has(plugin.name)) {
+      throw new PluginError(`Plugin "${plugin.name}" is already registered`, plugin.name)
+    }
+    plugins.set(plugin.name, { ...plugin, _type: type })
+  }
+
+  function getAll() {
+    return [...plugins.values()].sort((a, b) => {
+      const pa = a.priority ?? 0
+      const pb = b.priority ?? 0
+      return pa - pb
+    })
+  }
+
+  function resolve(filePath) {
+    return getAll().filter(p => p.match(filePath))
+  }
+
+  function unregister(name) {
+    plugins.delete(name)
+  }
+
+  return { register, getAll, resolve, unregister }
+}
+
+export { createPluginRegistry }

package/src/types/configTypes.js

@@ -0,0 +1,23 @@
+/*-------- Shape constants for rootless.config.json and related manifests --------*/
+
+const ROOT_CONFIG_SHAPE = {
+  containerPath: 'string|undefined',
+  mode: 'proxy|copy|undefined',
+  plugins: 'array|undefined',
+  remote: 'array|undefined',
+  extends: 'array|undefined',
+  experimental: 'object|undefined',
+}
+
+const GENERATED_MANIFEST_SHAPE = {
+  generated: 'array',
+}
+
+const EXPERIMENTAL_FLAGS_SHAPE = {
+  virtualFS: 'boolean',
+  capsule: 'boolean',
+  profiles: 'boolean',
+  remoteConfigs: 'boolean',
+}
+
+export { ROOT_CONFIG_SHAPE, GENERATED_MANIFEST_SHAPE, EXPERIMENTAL_FLAGS_SHAPE }

package/src/types/errors.js

@@ -0,0 +1,43 @@
+/*-------- Centralized error hierarchy for rootless-config --------*/
+
+class RcsError extends Error {
+  constructor(message, code) {
+    super(message)
+    this.name = 'RcsError'
+    this.code = code
+  }
+}
+
+class ContainerNotFoundError extends RcsError {
+  constructor(searchRoot) {
+    super(`No .root container found searching upward from: ${searchRoot}`, 'CONTAINER_NOT_FOUND')
+    this.name = 'ContainerNotFoundError'
+    this.searchRoot = searchRoot
+  }
+}
+
+class ValidationError extends RcsError {
+  constructor(message, field) {
+    super(message, 'VALIDATION_ERROR')
+    this.name = 'ValidationError'
+    this.field = field
+  }
+}
+
+class PluginError extends RcsError {
+  constructor(message, pluginName) {
+    super(message, 'PLUGIN_ERROR')
+    this.name = 'PluginError'
+    this.pluginName = pluginName
+  }
+}
+
+class RemoteError extends RcsError {
+  constructor(message, url) {
+    super(message, 'REMOTE_ERROR')
+    this.name = 'RemoteError'
+    this.url = url
+  }
+}
+
+export { RcsError, ContainerNotFoundError, ValidationError, PluginError, RemoteError }

package/src/types/pluginInterface.js

@@ -0,0 +1,25 @@
+/*-------- Plugin interface contracts and runtime shape validation --------*/
+
+import { PluginError } from './errors.js'
+
+const EXTERNAL_PLUGIN_FIELDS = ['name', 'match', 'generate']
+const BUILTIN_PLUGIN_FIELDS = ['name', 'match', 'load', 'transform', 'generate', 'teardown']
+
+function assertValidPlugin(plugin, type) {
+  const required = type === 'builtin' ? BUILTIN_PLUGIN_FIELDS : EXTERNAL_PLUGIN_FIELDS
+
+  for (const field of required) {
+    if (typeof plugin[field] !== 'function' && field !== 'name') {
+      throw new PluginError(
+        `Plugin "${plugin.name ?? '?'}" missing required method: ${field}`,
+        plugin.name ?? 'unknown'
+      )
+    }
+  }
+
+  if (typeof plugin.name !== 'string' || plugin.name.trim() === '') {
+    throw new PluginError('Plugin must have a non-empty string "name"', 'unknown')
+  }
+}
+
+export { EXTERNAL_PLUGIN_FIELDS, BUILTIN_PLUGIN_FIELDS, assertValidPlugin }