@aikdna/kdna-cli 0.9.0 → 0.12.0

package/src/cli.js

@@ -1,24 +1,12 @@
 #!/usr/bin/env node
 /**
- * kdna — Unified CLI for KDNA domain cognition assets.
+ * kdna — The runtime control plane for domain judgment.
  *
- * Commands:
- *   kdna validate <path>       Validate a domain directory or .kdna file
- *   kdna verify <path>         Verify a domain (alias for validate)
- *   kdna pack <path>           Pack a domain folder into .kdna container (ZIP)
- *   kdna unpack <path>         Unpack .kdna container to domain folder
- *   kdna install <domain-id>   Install a domain from registry
- *   kdna inspect <path>        Inspect a domain directory or .kdna file
- *   kdna list                  List installed domains
- *   kdna compare <before> <after>  Compare judgment with/without KDNA
- *   kdna match "<task>"        Match task against available domains
- *   kdna setup                 One-command setup: install CLI + skills + data root
- *   kdna cluster lint <path>   Validate a cluster manifest
- *   kdna identity init         Generate Ed25519 identity key pair
- *   kdna identity show         Display public key and buyer ID
+ * KDNA CLI is the runtime control plane for loading, validating,
+ * composing, testing, and governing domain judgment for AI agents.
  */
 
-const { usage, error } = require('./cmds/_common');
+const { error, EXIT, setQuiet, setExitCodeOnly } = require('./cmds/_common');
 const { cmdValidate, cmdPack, cmdUnpack, cmdInspect } = require('./cmds/domain');
 const { cmdList, cmdRegistry } = require('./cmds/registry');
 const {
@@ -27,29 +15,142 @@ const {
   cmdSearch,
   cmdAvailable,
   cmdMatch,
+  cmdSelect,
   cmdLoad,
+  cmdPostvalidate,
 } = require('./cmds/quality');
 const { cmdCluster } = require('./cmds/cluster');
 const { cmdIdentity } = require('./cmds/identity');
 const { cmdSetup } = require('./cmds/setup');
-const { cmdPreview, cmdProject, cmdEval, cmdSelect, cmdExport, cmdDemo } = require('./cmds/legacy');
+const { cmdDoctor } = require('./cmds/doctor');
+const { cmdTrace, cmdHistory } = require('./cmds/trace');
+const { cmdPreview, cmdProject, cmdEval, cmdExport, cmdDemo } = require('./cmds/legacy');
+const { cmdStudioScaffold, cmdCardsValidate, cmdLockVerify, cmdStudioCompile, cmdStudioReadiness } = require('./cmds/studio');
+const { cmdTestRun, cmdTestImport } = require('./cmds/test');
+const { cmdChangelog } = require('./cmds/changelog');
+const { cmdProposalCreate, cmdProposalValidate, cmdReview, cmdLockCard, cmdEvolution, cmdRegression } = require('./cmds/governance');
+const { cmdBadgeCompute, cmdRegistryAudit, cmdPackage } = require('./cmds/badge');
 
 // ─── Main ─────────────────────────────────────────────────────────────
 
 const args = process.argv.slice(2);
 if (!args.length || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
-  usage();
+  showHelp();
   process.exit(0);
 }
 
+// Global flags
+if (args.includes('--quiet')) setQuiet(true);
+if (args.includes('--exit-code')) setExitCodeOnly(true);
+
+function showHelp() {
+  const v = require('../package.json').version;
+  console.log(`kdna v${v} — The runtime control plane for domain judgment
+
+Usage: kdna <command> [options]
+
+Domain Authoring:
+  init <name>                      Scaffold a new domain from template
+  validate <path>                  Validate domain structure
+  validate --schema <path>         Schema-only validation
+  pack <path>                      Pack into .kdna container
+  unpack <file>                    Unpack .kdna container
+  inspect <path>                   Inspect domain or .kdna file
+  publish <path>                   Pack + sign + publish
+  publish --check <path>           Quality gate check only
+  version bump <level> [path]      Bump domain version
+  version bump --suggest [path]     Suggest version bump level
+
+Studio Integration (Phase 1):
+  studio scaffold <name>           Create Studio project + card templates
+  cards validate <project.json>    Validate Judgment Cards structure
+  lock verify <project.json>       Verify Human Lock status
+  studio compile <project.json>    Compile locked cards into KDNA domain
+  studio readiness <project.json>  Generate domain readiness card
+
+Agent Runtime:
+  available [--json]               List installed domains with v2.1 fields
+  match "<task>" [--json]          Signal matching — find relevant domains
+  select --input "..." [--json]    Selection policy — decide which domains to load
+  load <name> [--as=prompt|json|raw]  Emit domain in agent-ready format
+  load <name> --profile=index|compact|scenario|full  Load profiles (Phase 2)
+  postvalidate <name> --output <file>  Post-generation judgment check
+
+Testing & Verification:
+  verify <name>                    3-layer: structure + trust + judgment
+  verify <name> --judgment --run-tests  Judgment validation with eval cases
+  compare <name> --input "..."     With/without KDNA reasoning diff
+  diff <name>@<v1> <name>@<v2>     Judgment-level diff between versions
+  test run <name> --input <file>   Record test result against domain
+  test import <run> --as-eval      Convert test result to eval card
+  changelog <name> --from --to     Generate judgment changelog
+
+Cluster Composition:
+  cluster lint <path>              Validate cluster manifest
+  cluster match <path> --input ".." Match input to cluster domains
+  cluster compose <path> --input   Compose context with source attribution
+  cluster conflicts <path> --input Detect inter-domain conflicts
+  cluster graph <path>             Output domain relationship graph (DOT/JSON)
+
+Governance & Release (Phase 6):
+  proposal create --from-test <run> --domain <path>  Create improvement proposal
+  proposal validate <proposal.json>   Validate proposal structure
+  review accept <proposal> --by --reason   Accept improvement proposal
+  review reject <proposal> --by --reason   Reject improvement proposal
+  lock card <id> --by --reason        Record human lock on a card
+  evolution add-proposal <file>        Add proposal to evolution record
+  evolution add-lock <file>            Add lock to evolution record
+  evolution report <domain>            Show domain evolution history
+  regression <old> <new> --evals <dir>  Detect judgment regression
+
+Quality & Distribution (Phase 7):
+  badge compute <domain>              Compute quality badge (draft/tested/trusted)
+  registry audit --scope <@scope>     Audit registry scope health
+  package <domain> --format=kdna      Package domain as distributable asset
+
+Registry & Distribution:
+  install <name>                   Install domain from registry
+  remove <name>                    Uninstall a domain
+  update <name>                    Update installed domain
+  info <name>                      Show domain metadata and trust status
+  list [--available]               List installed or available domains
+  search <keyword>                 Search registry
+  registry refresh                 Refresh registry cache
+
+Identity & Signing:
+  identity init                    Generate Ed25519 signing key
+  identity show                    Display public key and buyer ID
+  identity export [--out]          Backup private key (encrypted)
+  identity import <file>           Restore identity from backup
+
+Setup:
+  setup                            One-command setup: CLI + skill + data root
+
+Trace & Diagnostics:
+  doctor [--agents] [--domains] [--json]   System health check
+  trace [--json] [--since 7d] [--export <file>]  Agent judgment trace
+  history [--stats] [--domain <name>] [--agent <name>]  Recent usage
+
+Flags:
+  --json                           Structured JSON output (machine-readable)
+  --quiet                          Suppress non-error output
+
+Exit Codes:
+  0 OK  1 VALIDATION_FAILED  2 INPUT_ERROR  3 TRUST_FAILED
+  4 JUDGMENT_QUALITY_FAILED  5 REGISTRY_ERROR  6 PROVIDER_ERROR
+  7 POLICY_VIOLATION  8 HUMAN_LOCK_REQUIRED
+`);
+}
+
 const cmd = args[0];
 
 switch (cmd) {
   case 'validate': {
     const schemaFlag = args.includes('--schema');
-    const target = args.filter((a, i) => i > 0 && a !== '--schema')[0];
+    const jsonFlag = args.includes('--json');
+    const target = args.filter((a, i) => i > 0 && a !== '--schema' && a !== '--json')[0];
     if (!target) error('Usage: kdna validate <path>');
-    cmdValidate(target, schemaFlag);
+    cmdValidate(target, schemaFlag, jsonFlag);
     break;
   }
   case 'pack': {
@@ -113,9 +214,9 @@ switch (cmd) {
   }
   case 'info': {
     const { cmdInfo } = require('./install');
-    const target = args[1];
+    const target = args.filter((a) => !a.startsWith('--'))[1];
     if (!target) error('Usage: kdna info <domain>');
-    cmdInfo(target);
+    cmdInfo(target, args.includes('--json'));
     break;
   }
   case 'update': {
@@ -130,9 +231,9 @@ switch (cmd) {
     break;
   }
   case 'inspect': {
-    const target = args[1];
+    const target = args.filter((a) => !a.startsWith('--'))[1];
     if (!target) error('Usage: kdna inspect <path>');
-    cmdInspect(target);
+    cmdInspect(target, args.includes('--json'));
     break;
   }
   case 'verify': {
@@ -174,6 +275,97 @@ switch (cmd) {
     cmdLoad(args);
     break;
   }
+  case 'select': {
+    cmdSelect(args);
+    break;
+  }
+  case 'postvalidate': {
+    cmdPostvalidate(args);
+    break;
+  }
+  case 'test': {
+    const sub = args[1];
+    if (sub === 'run') {
+      cmdTestRun(['test', ...args.slice(2)]);
+    } else if (sub === 'import') {
+      cmdTestImport(['test', ...args.slice(2)]);
+    } else {
+      error(
+        'Usage:\n' +
+          '  kdna test run <domain> --input <file> [--save <dir>]\n' +
+          '  kdna test import <run-file> --as-eval --out <file>',
+        EXIT.INPUT_ERROR,
+      );
+    }
+    break;
+  }
+  case 'changelog': {
+    cmdChangelog(args);
+    break;
+  }
+  case 'proposal': {
+    const sub = args[1];
+    if (sub === 'create') {
+      cmdProposalCreate(args);
+    } else if (sub === 'validate') {
+      cmdProposalValidate(args);
+    } else {
+      error('Usage: kdna proposal create --from-test <run.json> --domain <path>\n       kdna proposal validate <proposal.json>', EXIT.INPUT_ERROR);
+    }
+    break;
+  }
+  case 'review': {
+    cmdReview(args);
+    break;
+  }
+  case 'lock': {
+    const sub = args[1];
+    if (sub === 'verify') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna lock verify <studio.project.json>');
+      cmdLockVerify(target, args);
+    } else if (sub === 'card') {
+      cmdLockCard(args);
+    } else {
+      error(
+        'Usage:\n' +
+          '  kdna lock verify <studio.project.json>     Verify human lock status\n' +
+          '  kdna lock card <card-id> --by <name> --reason "..."   Lock a judgment card',
+        EXIT.INPUT_ERROR,
+      );
+    }
+    break;
+  }
+  case 'evolution': {
+    cmdEvolution(args);
+    break;
+  }
+  case 'regression': {
+    cmdRegression(args);
+    break;
+  }
+  case 'badge': {
+    const sub = args[1];
+    if (sub === 'compute') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna badge compute <domain>');
+      cmdBadgeCompute(target, args);
+    } else {
+      error('Usage: kdna badge compute <domain>', EXIT.INPUT_ERROR);
+    }
+    break;
+  }
+  case 'audit': {
+    cmdRegistryAudit(args);
+    break;
+  }
+  case 'package': {
+    const target = args.filter((a) => !a.startsWith('--'))[1];
+    if (!target) error('Usage: kdna package <domain> --format=kdna');
+    cmdPackage(target, args);
+    break;
+  }
+  // Legacy (removed) commands
   case 'project': {
     cmdProject();
     break;
@@ -182,22 +374,18 @@ switch (cmd) {
     cmdEval();
     break;
   }
-  case 'select': {
-    cmdSelect();
-    break;
-  }
   case 'export': {
     cmdExport();
     break;
   }
-  case 'list': {
-    cmdList(args.includes('--available'));
-    break;
-  }
   case 'demo': {
     cmdDemo();
     break;
   }
+  case 'list': {
+    cmdList(args.includes('--available'), args.includes('--json'));
+    break;
+  }
   case 'setup': {
     cmdSetup();
     break;
@@ -206,6 +394,18 @@ switch (cmd) {
     cmdCluster(args);
     break;
   }
+  case 'doctor': {
+    cmdDoctor(args);
+    break;
+  }
+  case 'trace': {
+    cmdTrace(args);
+    break;
+  }
+  case 'history': {
+    cmdHistory(args);
+    break;
+  }
   case 'identity': {
     cmdIdentity(args);
     break;
@@ -239,19 +439,61 @@ switch (cmd) {
     break;
   }
   case 'version': {
-    const { cmdVersionBump } = require('./version');
+    const { cmdVersionBump, cmdVersionSuggest } = require('./version');
     const sub = args[1];
     if (sub === 'bump') {
-      const level = args[2];
-      const target = args[3] || '.';
-      if (!level || !['patch', 'minor', 'major'].includes(level)) {
-        error('Usage: kdna version bump <patch|minor|major> [path]');
+      if (args.includes('--suggest')) {
+        const target = args.filter((a) => !a.startsWith('--'))[3] || '.';
+        cmdVersionSuggest(target, args);
+      } else {
+        const level = args[2];
+        const target = args[3] || '.';
+        if (!level || !['patch', 'minor', 'major'].includes(level)) {
+          error('Usage: kdna version bump <patch|minor|major> [path]');
+        }
+        cmdVersionBump(level, target);
       }
-      cmdVersionBump(level, target);
     } else {
       console.log(`kdna v${require('../package.json').version}`);
       console.log('');
       console.log('Usage: kdna version bump <patch|minor|major> [path]');
+      console.log('       kdna version bump --suggest [path]');
+    }
+    break;
+  }
+  case 'cards': {
+    const sub = args[1];
+    if (sub === 'validate') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna cards validate <studio.project.json>');
+      cmdCardsValidate(target, args);
+    } else {
+      error('Usage: kdna cards validate <studio.project.json>', EXIT.INPUT_ERROR);
+    }
+    break;
+  }
+  case 'studio': {
+    const sub = args[1];
+    if (sub === 'scaffold') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna studio scaffold <name> [--type=cluster] [--minimal]');
+      cmdStudioScaffold(target, args);
+    } else if (sub === 'compile') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna studio compile <studio.project.json> [--out <dir>]');
+      cmdStudioCompile(target, args);
+    } else if (sub === 'readiness') {
+      const target = args.filter((a) => !a.startsWith('--'))[2];
+      if (!target) error('Usage: kdna studio readiness <studio.project.json>');
+      cmdStudioReadiness(target, args);
+    } else {
+      error(
+        'Usage:\n' +
+          '  kdna studio scaffold <name> [--type=cluster] [--minimal]\n' +
+          '  kdna studio compile <studio.project.json> [--out <dir>]\n' +
+          '  kdna studio readiness <studio.project.json>',
+        EXIT.INPUT_ERROR,
+      );
     }
     break;
   }

package/src/cmds/_common.js

@@ -5,6 +5,48 @@ const { loadRegistry: loadCanonicalRegistry } = require('../registry');
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 
+// ─── Global flags ──────────────────────────────────────────────────────
+
+let _quiet = false;
+let _exitCodeOnly = false;
+const _originalLog = console.log;
+const _originalError = console.error;
+const _originalWarn = console.warn;
+
+function setQuiet(val) {
+  _quiet = val;
+  if (val) {
+    console.log = () => {};
+  } else {
+    console.log = _originalLog;
+  }
+}
+
+function isQuiet() { return _quiet; }
+
+function setExitCodeOnly(val) {
+  _exitCodeOnly = val;
+  if (val) {
+    console.log = () => {};
+    console.warn = () => {};
+    console.error = () => {};
+  } else {
+    console.log = _originalLog;
+    console.warn = _originalWarn;
+    console.error = _originalError;
+  }
+}
+
+function isExitCodeOnly() { return _exitCodeOnly; }
+
+function log(...args) {
+  if (!_quiet && !_exitCodeOnly) _originalLog(...args);
+}
+
+function warn(...args) {
+  if (!_exitCodeOnly) _originalWarn(...args);
+}
+
 function usage() {
   console.log(`kdna — KDNA domain cognition asset tool
 
@@ -57,6 +99,9 @@ Usage:
 
   --- Other ---
   kdna setup                    One-command setup: CLI + skill + data root
+  kdna doctor [--agents] [--domains] [--json]   System health check
+  kdna trace [--json] [--since 7d] [--export <file>]  Agent judgment trace
+  kdna history [--stats] [--domain <name>] [--agent <name>]  Recent usage
   kdna version                  Show kdna CLI version
   kdna help                     Show this help
 
@@ -68,9 +113,22 @@ Examples:
   kdna publish ./my_domain --release-tag v0.1.0 --repo yourname/kdna-my_domain`);
 }
 
-function error(msg) {
-  console.error(`Error: ${msg}`);
-  process.exit(1);
+// Exit codes — semantic exit codes for all KDNA CLI commands
+const EXIT = {
+  OK: 0,
+  VALIDATION_FAILED: 1,
+  INPUT_ERROR: 2,
+  TRUST_FAILED: 3,
+  JUDGMENT_QUALITY_FAILED: 4,
+  REGISTRY_ERROR: 5,
+  PROVIDER_ERROR: 6,
+  POLICY_VIOLATION: 7,
+  HUMAN_LOCK_REQUIRED: 8,
+};
+
+function error(msg, code = EXIT.VALIDATION_FAILED) {
+  if (!_exitCodeOnly) _originalError(`Error: ${msg}`);
+  process.exit(code);
 }
 
 function readJson(file) {
@@ -90,10 +148,17 @@ function loadRegistry() {
 }
 
 module.exports = {
+  EXIT,
   USER_KDNA_DIR,
   INSTALL_DIR,
   usage,
   error,
+  log,
+  warn,
+  setQuiet,
+  isQuiet,
+  setExitCodeOnly,
+  isExitCodeOnly,
   readJson,
   writeJson,
   loadRegistry,