configorama 0.11.0 → 1.0.0

package/cli.js

@@ -9,11 +9,28 @@ const { logHeader } = require('./src/utils/ui/logs')
 const configorama = require('./src')
 const { makeBox } = require('@davidwells/box-logger')
 const getValueAtPath = require('./src/utils/parsing/getValueAtPath')
+const { redactConfigByRequirements } = require('./src/utils/redaction/setupRedaction')
+const { normalizeError } = require('./src/errors')
+const { didYouMean } = require('./src/utils/strings/didYouMean')
+const { buildCapabilities } = require('./src/capabilities')
+
+// Subcommands an agent might type; used for "did you mean" command suggestions.
+const KNOWN_COMMANDS = ['inspect', 'requirements', 'audit', 'graph', 'setup', 'capabilities']
+const INSPECT_VIEWS = ['requirements', 'audit', 'graph']
+// Long flag names recognized by the parser; used for "did you mean" flag suggestions.
+// Unknown flags that are NOT near one of these are left alone so arbitrary
+// ${opt:...} passthrough flags (e.g. --stage, --domain) keep working.
+const KNOWN_FLAGS = [
+  'help', 'version', 'output', 'format', 'param', 'error-format', 'safe-root', 'file-root',
+  'debug', 'verbose', 'allow-unknown', 'allow-undefined', 'allow-unknown-file-refs',
+  'return-metadata', 'list', 'info', 'verify', 'raw', 'copy', 'setup', 'requirements',
+  'capabilities', 'view', 'safe', 'unsafe',
+]
 
 // Parse command line arguments
 const argv = minimist(process.argv.slice(2), {
-  string: ['output', 'o', 'format', 'f', 'param'],
-  boolean: ['help', 'h', 'version', 'v', 'V', 'debug', 'allow-unknown', 'allow-undefined', 'list', 'info', 'verify', 'raw', 'r', 'copy', 'c'],
+  string: ['output', 'o', 'format', 'f', 'param', 'error-format', 'safe-root', 'file-root', 'view'],
+  boolean: ['help', 'h', 'version', 'v', 'V', 'debug', 'allow-unknown', 'allow-undefined', 'list', 'info', 'verify', 'raw', 'r', 'copy', 'c', 'setup', 'requirements', 'capabilities', 'safe', 'unsafe'],
   alias: {
     h: 'help',
     v: 'version',
@@ -38,21 +55,37 @@ Configorama - Variable resolution for configuration files
 
 Usage:
   configorama [options] <file> [path]
+  configorama <command> <file> [options]
+
+Commands:
+  (default)                 Resolve <file> and print the result
+  inspect <file>            Introspect a config without resolving it (full model)
+                              --view requirements|audit|graph for a single slice
+  setup <file>              Run the interactive config wizard (experimental)
+  capabilities              Print the machine-readable CLI contract (JSON)
 
 Options:
   -h, --help                Show this help message
   -v, --version             Show version number
   -o, --output <file>       Write output to file instead of stdout
-  -f, --format <format>     Output format: json, yaml, or js (default: json)
+  -f, --format <format>     Output format: json, yaml, js (resolve); json, mermaid, dot (graph)
+      --view <view>         inspect view: requirements, audit, or graph
   -r, --raw                 Print extracted scalar values without JSON quoting
   -c, --copy                Copy the formatted output to the clipboard
   -d, --debug               Enable debug mode
   -i, --info                Show info about the config
   -V, --verify              Verify the config
+  --safe                    Block executable/config-mutating surfaces during resolution
+  --unsafe                  Disable inspect/audit/graph default safe inspection
+  --safe-root <dir>         Restrict file/text references to an allowed root
+  --error-format <fmt>      Error format on stderr: json or human. json is the
+                              default for inspect/requirements/audit/graph/capabilities
   --param <key=value>       Pass parameter values (can be used multiple times)
   --allow-unknown           Allow unknown variables to pass through
   --allow-undefined         Allow undefined values in the final output
 
+  Aliases: \`setup\` is also available as \`--setup\`, and \`capabilities\` as \`--capabilities\`.
+
 Path Extraction:
   Use jq-style paths to extract specific values from the resolved config.
   Paths can appear before or after options.
@@ -72,6 +105,13 @@ Examples:
   configorama -r --copy config.yml .database.host
   configorama '.servers[0].port' config.yml
   configorama --info config.yml
+  configorama --setup config.yml
+  configorama setup config.yml
+  configorama inspect config.yml
+  configorama inspect config.yml --view requirements
+  configorama inspect config.yml --view audit
+  configorama inspect config.yml --view graph --format mermaid
+  configorama capabilities
   configorama --format yaml config.json
   configorama --output resolved.json config.yml
   configorama --param="domain=myapp.com" --param="key=value" config.yml
@@ -87,16 +127,89 @@ if (argv.version) {
   process.exit(0)
 }
 
+// Capabilities is an informational command and needs no input file.
+if (argv._[0] === 'capabilities' || argv.capabilities) {
+  const capsOutput = JSON.stringify(buildCapabilities(), null, 2)
+  if (argv.output) {
+    fs.writeFileSync(argv.output, capsOutput)
+    console.log(`Capabilities written to ${argv.output}`)
+  } else {
+    console.log(capsOutput)
+  }
+  process.exit(0)
+}
+
+// Warn (don't fail) on a misspelled flag that is one edit from a known flag.
+// Genuine ${opt:...} passthrough flags are far from any known flag, so they
+// are left untouched and keep working.
+function warnUnknownFlags() {
+  for (const token of process.argv.slice(2)) {
+    if (!token.startsWith('--') || token === '--') continue
+    const name = token.slice(2).split('=')[0]
+    if (!name || KNOWN_FLAGS.includes(name)) continue
+    const suggestion = didYouMean(name, KNOWN_FLAGS)
+    if (suggestion) {
+      console.error(`Warning: unknown flag "--${name}". Did you mean "--${suggestion}"?`)
+    }
+  }
+}
+warnUnknownFlags()
+
 // Parse positional args: find file path and jq-style extraction path
 // File is first arg that exists as a file, jq path starts with '.' or '['
 let inputFile = null
 let extractPath = null
+const requirementsSubcommand = argv._[0] === 'requirements'
+const auditSubcommand = argv._[0] === 'audit'
+const graphSubcommand = argv._[0] === 'graph'
+const inspectSubcommand = argv._[0] === 'inspect'
+const requirementsMode = requirementsSubcommand || Boolean(argv.requirements)
+// Commands that emit JSON to stdout; their errors default to JSON on stderr too.
+const structuredCommand = requirementsMode || auditSubcommand || graphSubcommand || inspectSubcommand
 
 function isFileArg(arg) {
   if (fs.existsSync(arg) && fs.statSync(arg).isFile()) return true
   return arg.startsWith('./') || arg.startsWith('../')
 }
 
+/**
+ * Print a CLI-level error and exit non-zero, honoring --error-format.
+ * Structured commands default to JSON; resolve mode defaults to a plain message.
+ * @param {string} code - stable error code (see ERROR_CODES)
+ * @param {string} message - human-readable message
+ * @param {object} [details] - extra machine-readable context
+ */
+function emitCliError(code, message, details = {}) {
+  const wantsJson = argv['error-format'] === 'json' || (structuredCommand && argv['error-format'] !== 'human')
+  if (wantsJson) {
+    console.error(JSON.stringify({ error: { code, message, details } }, null, 2))
+  } else {
+    console.error(`Error: ${message}`)
+  }
+  process.exit(1)
+}
+
+// If the first arg looks like a misspelled command (not a file or jq-path),
+// suggest the closest command instead of silently treating it as a filename.
+const firstArg = argv._[0]
+if (
+  firstArg &&
+  !KNOWN_COMMANDS.includes(firstArg) &&
+  !firstArg.startsWith('.') &&
+  !firstArg.startsWith('[') &&
+  !isFileArg(firstArg) &&
+  !fs.existsSync(firstArg)
+) {
+  const suggestion = didYouMean(firstArg, KNOWN_COMMANDS)
+  if (suggestion) {
+    emitCliError(
+      'unknown_command',
+      `Unknown command "${firstArg}". Did you mean "${suggestion}"? Run --help for usage.`,
+      { provided: firstArg, suggestion, commands: KNOWN_COMMANDS }
+    )
+  }
+}
+
 function getClipboardCommands() {
   if (process.env.CONFIGORAMA_CLIPBOARD_COMMAND) {
     return [{ command: process.env.CONFIGORAMA_CLIPBOARD_COMMAND, shell: true }]
@@ -132,29 +245,32 @@ function copyToClipboard(value) {
   }
 }
 
-for (const arg of argv._) {
-  if (arg === 'setup') continue
-
-  // jq-style paths start with '.' or '['
-  if (!inputFile && isFileArg(arg)) {
-    inputFile = arg
-  } else if (arg.startsWith('.') || arg.startsWith('[')) {
-    extractPath = arg
-  } else if (!inputFile) {
-    inputFile = arg
+if (requirementsSubcommand) {
+  inputFile = argv._[1] || null
+} else if (auditSubcommand || graphSubcommand || inspectSubcommand) {
+  inputFile = argv._[1] || null
+} else {
+  for (const arg of argv._) {
+    if (arg === 'setup') continue
+
+    // jq-style paths start with '.' or '['
+    if (!inputFile && isFileArg(arg)) {
+      inputFile = arg
+    } else if (arg.startsWith('.') || arg.startsWith('[')) {
+      extractPath = arg
+    } else if (!inputFile) {
+      inputFile = arg
+    }
   }
 }
 
 if (!inputFile) {
-  console.error('Error: No input file specified')
-  console.error('Run with --help for usage information')
-  process.exit(1)
+  emitCliError('no_input_file', 'No input file specified. Run with --help for usage information.', {})
 }
 
 // Check if file exists
 if (!fs.existsSync(inputFile)) {
-  console.error(`Error: File not found: ${inputFile}`)
-  process.exit(1)
+  emitCliError('file_not_found', `File not found: ${inputFile}`, { path: inputFile })
 }
 
 // Set options for Configorama
@@ -164,9 +280,21 @@ const options = {
   allowUnknownFileRefs: argv['allow-unknown-file-refs'] || false,
   returnMetadata: argv['return-metadata'] || false,
   returnPreResolvedVariableDetails: false,
+  // Setup wizard via --setup flag or `setup` subcommand
+  setup: Boolean(argv.setup) || argv._.includes('setup'),
+  safeMode: Boolean(argv.safe) || ((auditSubcommand || graphSubcommand || inspectSubcommand) && !argv.unsafe),
+  safeRoots: [],
   dynamicArgs: argv
 }
 
+options.safeRoots = []
+if (argv['safe-root']) options.safeRoots = options.safeRoots.concat(argv['safe-root'])
+if (argv['file-root']) options.safeRoots = options.safeRoots.concat(argv['file-root'])
+if (options.safeRoots.length > 0) {
+  options.allowedFileRoots = options.safeRoots
+  options.restrictFileRoots = true
+}
+
 const dynamicArgs = options.dynamicArgs || {}
 const { 
   _, 
@@ -188,7 +316,14 @@ const {
   raw,
   c,
   copy,
-  'allow-unknown': allowUnknown, 
+  setup,
+  requirements,
+  safe,
+  unsafe,
+  'safe-root': safeRoot,
+  'file-root': fileRoot,
+  'error-format': errorFormat,
+  'allow-unknown': allowUnknown,
   'allow-undefined': allowUndefined,
   'allow-unknown-file-refs': allowUnknownFileRefs,
   'return-metadata': returnMetadata,
@@ -208,57 +343,166 @@ if (options.dynamicArgs.verbose) {
   console.log()
 }
 
-let isSetupMode = false
-if (argv._.length) {
-  isSetupMode = argv._.includes('setup')
-}
-
 // Set -- flags as options
 options.options = rest
 options.handleSignalEvents = true
 
+function handleCliError(error) {
+  const wantsJson = argv['error-format'] === 'json' || (structuredCommand && argv['error-format'] !== 'human')
+  if (wantsJson) {
+    console.error(JSON.stringify(normalizeError(error).toJSON(), null, 2))
+    process.exit(1)
+  }
+
+  const errorMsg = makeBox({
+    title: `Error Processing Configuration: ${inputFile}`,
+    minWidth: '100%',
+    content: error.message,
+    type: 'error',
+  })
+  console.error(errorMsg)
+  if (argv.debug) {
+    console.error('error', error)
+  }
+  process.exit(1)
+}
+
+if (requirementsMode) {
+  configorama.analyze(inputFile, {
+    ...options,
+    instructions: true,
+  })
+    .then((requirementsJson) => {
+      const output = JSON.stringify(requirementsJson, null, 2)
+
+      if (argv.copy) {
+        const copyResult = copyToClipboard(output)
+        if (!copyResult.ok) {
+          console.error(`Error: Unable to copy to clipboard: ${copyResult.error}`)
+          process.exit(1)
+        }
+      }
+
+      if (argv.output) {
+        fs.writeFileSync(argv.output, output)
+        console.log(`Configuration written to ${argv.output}`)
+      } else if (!argv.verbose) {
+        console.log(output)
+      }
+    })
+    .catch(handleCliError)
+} else if (auditSubcommand) {
+  configorama.audit(inputFile, options)
+    .then((report) => {
+      const output = JSON.stringify(report, null, 2)
+
+      if (argv.output) {
+        fs.writeFileSync(argv.output, output)
+        console.log(`Audit written to ${argv.output}`)
+      } else {
+        console.log(output)
+      }
+    })
+    .catch(handleCliError)
+} else if (graphSubcommand) {
+  configorama.graph(inputFile, {
+    ...options,
+    format: argv.format || 'json',
+  })
+    .then((graphOutput) => {
+      const output = typeof graphOutput === 'string' ? graphOutput : JSON.stringify(graphOutput, null, 2)
+      if (argv.output) {
+        fs.writeFileSync(argv.output, output)
+        console.log(`Graph written to ${argv.output}`)
+      } else {
+        console.log(output)
+      }
+    })
+    .catch(handleCliError)
+} else if (inspectSubcommand) {
+  const view = argv.view
+  if (view && !INSPECT_VIEWS.includes(view)) {
+    const suggestion = didYouMean(String(view), INSPECT_VIEWS)
+    emitCliError(
+      'invalid_view',
+      `Unknown view "${view}".${suggestion ? ` Did you mean "${suggestion}"?` : ''} Valid views: ${INSPECT_VIEWS.join(', ')}.`,
+      { provided: view, suggestion: suggestion || null, views: INSPECT_VIEWS }
+    )
+  }
+  configorama.inspect(inputFile, {
+    ...options,
+    view: view || undefined,
+    format: argv.format || 'json',
+  })
+    .then((result) => {
+      const output = typeof result === 'string' ? result : JSON.stringify(result, null, 2)
+      if (argv.output) {
+        fs.writeFileSync(argv.output, output)
+        console.log(`Inspection written to ${argv.output}`)
+      } else {
+        console.log(output)
+      }
+    })
+    .catch(handleCliError)
+} else {
+
 // Process the configuration
-configorama(inputFile, options)
+const shouldRedactSetupStdout = options.setup && !argv.output && !argv.copy
+let setupRequirementsForRedaction = []
+const configPromise = shouldRedactSetupStdout
+  ? (() => {
+      const instance = new Configorama(inputFile, options)
+      return instance.init(options.options || {}).then((config) => {
+        setupRequirementsForRedaction = instance.setupRequirements || []
+        return config
+      })
+    })()
+  : configorama(inputFile, options)
+
+configPromise
   .then((config) => {
+    let outputConfig = shouldRedactSetupStdout
+      ? redactConfigByRequirements(config, setupRequirementsForRedaction)
+      : config
+
     // Apply path extraction if specified
     if (extractPath) {
-      config = getValueAtPath(config, extractPath)
-      if (config === undefined) {
-        console.error(`Error: Path not found: ${extractPath}`)
-        process.exit(1)
+      outputConfig = getValueAtPath(outputConfig, extractPath)
+      if (outputConfig === undefined) {
+        emitCliError('path_not_found', `Path not found: ${extractPath}`, { path: extractPath })
       }
     }
 
     let output
 
     // Format the output
-    if (argv.raw && extractPath && (config === null || ['string', 'number', 'boolean'].includes(typeof config))) {
-      output = config === null ? 'null' : String(config)
+    if (argv.raw && extractPath && (outputConfig === null || ['string', 'number', 'boolean'].includes(typeof outputConfig))) {
+      output = outputConfig === null ? 'null' : String(outputConfig)
     } else switch (argv.format.toLowerCase()) {
       case 'yaml':
       case 'yml':
         const YAML = require('./src/parsers/yaml')
-        output = YAML.dump(config)
+        output = YAML.dump(outputConfig)
         break
       case 'esm':
       case 'mjs':
       case 'module':
-        output = `export default ${JSON.stringify(config, null, 2)}`
+        output = `export default ${JSON.stringify(outputConfig, null, 2)}`
         break
       case 'js':
       case 'cjs':
       case 'commonjs':
       case 'javascript':
-        output = `module.exports = ${JSON.stringify(config, null, 2)}`
+        output = `module.exports = ${JSON.stringify(outputConfig, null, 2)}`
         break
       case 'json':
       case 'json5':
       default:
         if (returnMetadata) {
           // turn regex into string
-          config.variableSyntax = config.variableSyntax ? config.variableSyntax.source : undefined
+          outputConfig.variableSyntax = outputConfig.variableSyntax ? outputConfig.variableSyntax.source : undefined
         }
-        output = JSON.stringify(config, null, 2)
+        output = JSON.stringify(outputConfig, null, 2)
     }
 
     if (argv.copy) {
@@ -283,16 +527,5 @@ configorama(inputFile, options)
       }
     }
   })
-  .catch((error) => {
-    const errorMsg = makeBox({
-      title: `Error Processing Configuration: ${inputFile}`,
-      minWidth: '100%',
-      content: error.message,
-      type: 'error',
-    })
-    console.error(errorMsg)
-    if (argv.debug) {
-      console.error('error', error)
-    }
-    process.exit(1)
-  })
+  .catch(handleCliError)
+}

package/index.d.ts

@@ -77,6 +77,24 @@ interface ConfigoramaSettings {
   filePathOverrides?: Record<string, string>
   /** Install Configorama CLI signal handlers. Defaults to false for library calls. */
   handleSignalEvents?: boolean
+  /** Block executable and mutating surfaces such as JS/TS file refs, custom resolvers/functions, and dotenv. */
+  safeMode?: boolean
+  /** Alias for safeMode */
+  safe?: boolean
+  /** Restrict file/text references to allowed roots. Enabled by default in safeMode. */
+  restrictFileRoots?: boolean
+  /** Allowed roots for file/text references */
+  allowedFileRoots?: string[]
+  /** Alias for allowedFileRoots */
+  safeRoots?: string[]
+  /** Allow executable file refs even when safeMode is enabled */
+  blockExecutableFiles?: boolean
+  /** Allow custom resolvers even when safeMode is enabled */
+  blockCustomResolvers?: boolean
+  /** Allow custom functions even when safeMode is enabled */
+  blockCustomFunctions?: boolean
+  /** Allow dotenv loading even when safeMode is enabled */
+  blockDotEnv?: boolean
 }
 
 interface ConfigoramaResult<T = any> {
@@ -129,12 +147,36 @@ declare namespace configorama {
     settings?: ConfigoramaSettings
   ): T
 
-  /** Analyze config variables without resolving them */
+  /** Unified introspection entry point. Returns requirements, graph, and audit, or one view. */
+  export function inspect(
+    configPathOrObject: string | object,
+    settings?: ConfigoramaSettings & { view?: 'requirements' | 'audit' | 'graph', format?: 'json' | 'mermaid' | 'mmd' | 'dot' | 'graphviz' }
+  ): Promise<any>
+
+  /** @deprecated Use inspect(config, { view: 'requirements' }) for requirements, or returnMetadata for resolved metadata. */
   export function analyze(
     configPathOrObject: string | object,
     settings?: ConfigoramaSettings
   ): Promise<any>
 
+  /** @deprecated Use inspect(config) for the unified inspection model. */
+  export function introspect(
+    configPathOrObject: string | object,
+    settings?: ConfigoramaSettings
+  ): Promise<any>
+
+  /** @deprecated Use inspect(config, { view: 'audit' }). */
+  export function audit(
+    configPathOrObject: string | object,
+    settings?: ConfigoramaSettings
+  ): Promise<any>
+
+  /** @deprecated Use inspect(config, { view: 'graph', format }). */
+  export function graph(
+    configPathOrObject: string | object,
+    settings?: ConfigoramaSettings & { format?: 'json' | 'mermaid' | 'mmd' | 'dot' | 'graphviz', formatGraph?: boolean }
+  ): Promise<any>
+
   /** Format utilities for parsing various config formats */
   export const format: {
     yaml: any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -24,6 +24,10 @@
   "scripts": {
     "info": "repomix --include \"cli.js,src/**/*.js\" --ignore \"**/*.test.js\" --copy",
     "docs": "node ./scripts/docs.js",
+    "site:dev": "cd site && npm run dev",
+    "site:build": "cd site && npm run build",
+    "site:validate": "cd site && npm run validate",
+    "site:deploy": "cd site && npm run deploy",
     "t": "./scripts/run-tests.sh",
     "test": "npm run test:slow && npm run test:lib && uvu tests \".*\\.test.js$\"",
     "test:tests": "uvu tests \".*\\.test.js$\" ",

package/src/capabilities.js

@@ -0,0 +1,59 @@
+// Machine-readable description of the configorama CLI contract for agents.
+// Lists commands, views, output formats, error codes, exit codes, and flags so
+// an agent can read the contract from the tool instead of guessing or reading docs.
+
+const { ERROR_CODES } = require('./errors')
+const pkg = require('../package.json')
+
+const SCHEMA_VERSION = 1
+
+const VIEWS = ['requirements', 'audit', 'graph']
+
+/**
+ * Build the capabilities contract object.
+ * @returns {object} stable, deterministic description of the CLI surface
+ */
+function buildCapabilities() {
+  return {
+    name: 'configorama',
+    version: pkg.version,
+    schemaVersion: SCHEMA_VERSION,
+    commands: [
+      { name: 'resolve', usage: 'configorama <file> [path]', summary: 'Resolve a config file and print the result (default command).' },
+      { name: 'inspect', usage: 'configorama inspect <file> [--view requirements|audit|graph]', summary: 'Introspect a config without resolving it; returns the full model or one view.' },
+      { name: 'setup', usage: 'configorama setup <file>', summary: 'Run the interactive setup wizard (experimental).' },
+      { name: 'capabilities', usage: 'configorama capabilities', summary: 'Print this machine-readable contract.' },
+    ],
+    // Hidden back-compat commands that map to an inspect view. They still run if
+    // typed, but inspect is the documented surface.
+    aliases: [
+      { name: 'requirements', mapsTo: 'inspect --view requirements', summary: 'Inputs a config needs.' },
+      { name: 'audit', mapsTo: 'inspect --view audit', summary: 'Risky references.' },
+      { name: 'graph', mapsTo: 'inspect --view graph', summary: 'Dependency graph of variables and files.' },
+    ],
+    views: VIEWS,
+    formats: {
+      resolve: ['json', 'yaml', 'js', 'esm'],
+      graph: ['json', 'mermaid', 'dot'],
+    },
+    errorCodes: ERROR_CODES,
+    exitCodes: [
+      { code: 0, meaning: 'Success.' },
+      { code: 1, meaning: 'Error. The category is in the JSON `error.code` field (use --error-format json).' },
+    ],
+    flags: [
+      { flag: '--output, -o <file>', summary: 'Write output to a file instead of stdout.' },
+      { flag: '--format, -f <format>', summary: 'Output format (see formats).' },
+      { flag: '--view <view>', summary: 'inspect view: requirements, audit, or graph.' },
+      { flag: '--raw, -r', summary: 'Print extracted scalar values without JSON quoting.' },
+      { flag: '--error-format <json|human>', summary: 'Error output format on stderr (json is machine-readable).' },
+      { flag: '--param <key=value>', summary: 'Pass parameter values (repeatable).' },
+      { flag: '--safe', summary: 'Block executable/config-mutating references during resolution.' },
+      { flag: '--safe-root <dir>', summary: 'Restrict file/text references to an allowed root.' },
+      { flag: '--allow-unknown', summary: 'Allow unknown variables to pass through.' },
+      { flag: '--allow-undefined', summary: 'Allow undefined values in the final output.' },
+    ],
+  }
+}
+
+module.exports = { SCHEMA_VERSION, VIEWS, buildCapabilities }

package/src/capabilities.test.js

@@ -0,0 +1,44 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { buildCapabilities } = require('./capabilities')
+const { ERROR_CODES } = require('./errors')
+const pkg = require('../package.json')
+
+test('buildCapabilities - reports name, version and schemaVersion', () => {
+  const caps = buildCapabilities()
+  assert.is(caps.name, 'configorama')
+  assert.is(caps.version, pkg.version)
+  assert.is(caps.schemaVersion, 1)
+})
+
+test('buildCapabilities - commands list is the documented surface', () => {
+  const names = buildCapabilities().commands.map(c => c.name)
+  assert.equal(names, ['resolve', 'inspect', 'setup', 'capabilities'])
+})
+
+test('buildCapabilities - hidden verbs are discoverable under aliases', () => {
+  const aliases = buildCapabilities().aliases
+  assert.equal(aliases.map(a => a.name), ['requirements', 'audit', 'graph'])
+  assert.is(aliases.find(a => a.name === 'audit').mapsTo, 'inspect --view audit')
+})
+
+test('buildCapabilities - exposes the full error-code registry', () => {
+  const caps = buildCapabilities()
+  assert.equal(caps.errorCodes, ERROR_CODES)
+  const codes = caps.errorCodes.map(e => e.code)
+  assert.ok(codes.includes('missing_env'))
+  assert.ok(codes.includes('blocked_by_safe_mode'))
+})
+
+test('buildCapabilities - documents exit codes and graph formats', () => {
+  const caps = buildCapabilities()
+  assert.equal(caps.exitCodes.map(e => e.code), [0, 1])
+  assert.equal(caps.formats.graph, ['json', 'mermaid', 'dot'])
+  assert.equal(caps.views, ['requirements', 'audit', 'graph'])
+})
+
+test('buildCapabilities - output is deterministic', () => {
+  assert.is(JSON.stringify(buildCapabilities()), JSON.stringify(buildCapabilities()))
+})
+
+test.run()