@aikdna/kdna-cli 0.14.0 → 0.16.0

package/README.md

@@ -4,24 +4,24 @@
 
 KDNA CLI 是 AI Agent 加载、验证、组合、测试和治理领域判断的运行控制平面。
 
-CLI 不是 Studio，不是 Chat，不是 Governance Console。它是这些产品共同依赖的底层协议接口。
-
 Part of the [KDNA](https://github.com/knowledge-dna/KDNA) ecosystem.
 
 ## Install
 
 ```bash
 npm install -g @aikdna/kdna-cli
+kdna setup
 ```
 
-## Quick Start
+## Quick Start (5 minutes)
 
 ```bash
-kdna install @aikdna/writing    # Install a domain
-kdna verify @aikdna/writing     # 3-layer verification
-kdna available                  # List installed domains
-kdna match "improve this post"  # Find relevant domains
-kdna load @aikdna/writing       # Load for agent consumption
+npm install -g @aikdna/kdna-cli
+kdna setup
+kdna install @aikdna/writing
+kdna verify @aikdna/writing --judgment
+kdna compare @aikdna/writing --input "help me improve this post"
+kdna doctor --agents
 ```
 
 ## Commands by Role
@@ -34,7 +34,8 @@ kdna load @aikdna/writing       # Load for agent consumption
 | `kdna validate <path>` | Validate domain structure |
 | `kdna validate --schema <path>` | Schema-only validation |
 | `kdna pack <path>` | Pack into .kdna container |
-| `kdna unpack <file>` | Unpack .kdna container |
+| `kdna pack <path> --encrypt --license <file>` | Pack encrypted .kdnae container |
+| `kdna unpack <file>` | Unpack .kdna or .kdnae container |
 | `kdna inspect <path>` | Inspect domain or .kdna file |
 | `kdna publish <path>` | Pack + sign + publish to registry |
 | `kdna publish --check <path>` | Quality gate check only |
@@ -47,15 +48,42 @@ kdna load @aikdna/writing       # Load for agent consumption
 | `kdna available [--json]` | List installed domains with v2.1 fields |
 | `kdna match "<task>" [--json]` | Signal matching — find relevant domains |
 | `kdna load <name> [--as=prompt\|json\|raw]` | Emit domain in agent-ready format |
+| `kdna postvalidate <name> --output <file>` | Post-generation judgment check |
 
 ### Testing & Verification
 
 | Command | Description |
 |---------|-------------|
-| `kdna verify <name>` | 3-layer verification: structure + trust + judgment |
+| `kdna verify <name>` | 3-layer: structure + trust + judgment |
 | `kdna compare <name> --input "..."` | With/without KDNA reasoning diff |
+| `kdna compare <name> --input "..." --report-md` | Markdown report with scoring |
+| `kdna compare <name> --input "..." --report-json` | JSON report with scoring |
 | `kdna diff <name>@<v1> <name>@<v2>` | Judgment-level diff between versions |
-| `kdna doctor` | Check runtime environment health |
+
+### Diagnostics & Trace
+
+| Command | Description |
+|---------|-------------|
+| `kdna doctor` | System health check |
+| `kdna doctor --agents` | Agent integration check (Codex/Claude/OpenCode/Cursor/Gemini) |
+| `kdna doctor --json` | Machine-readable health report |
+| `kdna trace` | View recent load/postvalidate traces |
+| `kdna trace --json` | Machine-readable trace output |
+| `kdna trace --export <file>` | Export traces for audit |
+| `kdna trace --since 7d\|30d\|90d` | Filter by time range |
+| `kdna history` | Recent domain usage (last 20) |
+| `kdna history --stats` | Aggregate by domain and agent |
+| `kdna history --domain <name>` | Filter by domain |
+
+### License & Authorization
+
+| Command | Description |
+|---------|-------------|
+| `kdna license generate <domain> --to <email>` | Generate signed license |
+| `kdna license install <license.json>` | Register license for auto-decrypt |
+| `kdna license verify <license.json>` | Verify license signature and validity |
+| `kdna license bind <license.json>` | Bind license to this machine |
+| `kdna license show <license.json>` | Display license details |
 
 ### Cluster Composition
 
@@ -68,6 +96,8 @@ kdna load @aikdna/writing       # Load for agent consumption
 | Command | Description |
 |---------|-------------|
 | `kdna install <name>` | Install domain from registry |
+| `kdna install ./file.kdna` | Install from local .kdna file |
+| `kdna install ./file.kdnae` | Install from encrypted .kdnae (auto-decrypt with license) |
 | `kdna remove <name>` | Uninstall a domain |
 | `kdna update <name>` | Update installed domain |
 | `kdna info <name>` | Show domain metadata and trust status |
@@ -90,6 +120,14 @@ kdna load @aikdna/writing       # Load for agent consumption
 |---------|-------------|
 | `kdna setup` | One-command setup: CLI + skill + data root |
 
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `KDNA_AGENT` | Override agent name in trace logs (e.g. `claude_code`, `codex`, `opencode`) |
+| `KDNA_REGISTRY_URL` | Override canonical registry URL |
+| `KDNA_IDENTITY_DIR` | Override identity key directory |
+
 ## Exit Codes
 
 | Code | Name | Meaning |
@@ -111,10 +149,10 @@ Machine-consumable commands support `--json` for structured output:
 ```bash
 kdna verify @aikdna/writing --json
 kdna available --json
-kdna match "help me write" --json
-kdna search writing --json
-kdna info @aikdna/writing --json
-kdna doctor --json
+kdna doctor --agents --json
+kdna trace --json
+kdna history --json
+kdna license verify --json <file>
 ```
 
 ## Product Matrix
@@ -123,14 +161,12 @@ kdna doctor --json
 |-------|---------|---------------|
 | Protocol | KDNA SPEC | Define judgment asset format |
 | Core Library | @aikdna/kdna-core | load / validate / compose / render |
-| Runtime | @aikdna/kdna-cli | Agent runtime + compile + verify + test + publish |
+| Runtime | @aikdna/kdna-cli | Agent runtime + compile + verify + test + publish + license |
 | Authoring | KDNA Studio | Human-led judgment production |
 | Consumption | KDNAChat | Load, use, compare |
 | Governance | KDNA Governance Console | Approve, release, audit |
 | Distribution | Registry | Discover, install, trade |
 
-CLI 不应该成为一个"命令行 Studio"，而是所有 KDNA 产品共同依赖的协议控制平面。
-
 ## Development
 
 ```bash
@@ -144,6 +180,7 @@ npm test
 
 - [@aikdna/kdna-core](https://github.com/knowledge-dna/KDNA/tree/main/packages/kdna-core) — Pure logic library
 - [KDNA Registry](https://github.com/knowledge-dna/kdna-registry) — Domain catalog
+- [KDNA SPEC](https://github.com/knowledge-dna/KDNA) — Protocol specification
 - [aikdna.com](https://aikdna.com) — Website
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "KDNA CLI — create, validate, install, and manage domain cognition packages for AI agents.",
   "type": "commonjs",
   "bin": {

package/src/agent.js

@@ -34,6 +34,10 @@ const path = require('path');
 const { parseName } = require('./registry');
 const { recordTrace } = require('./cmds/trace');
 
+function detectAgent() {
+  return process.env.KDNA_AGENT || 'cli';
+}
+
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 
@@ -367,7 +371,7 @@ function cmdLoad(input, args = []) {
   // JSON format
   if (format === 'json') {
     process.stdout.write(JSON.stringify({ manifest, core, patterns: pat }, null, 2) + '\n');
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'json' });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'json' });
     return;
   }
 
@@ -380,20 +384,20 @@ function cmdLoad(input, args = []) {
         process.stdout.write(fs.readFileSync(p, 'utf8'));
       }
     }
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'raw' });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'raw' });
     return;
   }
 
   // Load profiles
   if (profile) {
     emitProfile(parsed, manifest, core, pat, profile, profileInput);
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: `profile:${profile}` });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: `profile:${profile}` });
     return;
   }
 
   // Default: --as=prompt — compact text optimized for system-prompt injection.
   emitCompact(parsed, manifest, core, pat);
-  recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'prompt' });
+  recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'prompt' });
 }
 
 // ─── Load profiles ─────────────────────────────────────────────────────
@@ -821,7 +825,7 @@ function cmdPostvalidate(args = []) {
     console.log(JSON.stringify(result, null, 2));
     recordTrace({
       timestamp: new Date().toISOString(),
-      agent: 'cli',
+      agent: detectAgent(),
       domain: parsed.full,
       type: 'postvalidate',
       postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },
@@ -851,7 +855,7 @@ function cmdPostvalidate(args = []) {
 
   recordTrace({
     timestamp: new Date().toISOString(),
-    agent: 'cli',
+    agent: detectAgent(),
     domain: parsed.full,
     type: 'postvalidate',
     postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },

package/src/cli.js

@@ -24,7 +24,7 @@ const { cmdIdentity } = require('./cmds/identity');
 const { cmdSetup } = require('./cmds/setup');
 const { cmdDoctor } = require('./cmds/doctor');
 const { cmdTrace, cmdHistory } = require('./cmds/trace');
-const { cmdLicenseGenerate, cmdLicenseVerify, cmdLicenseBind, cmdLicenseShow } = require('./cmds/license');
+const { cmdLicenseGenerate, cmdLicenseVerify, cmdLicenseBind, cmdLicenseShow, cmdLicenseInstall } = require('./cmds/license');
 const { cmdPreview, cmdProject, cmdEval, cmdExport, cmdDemo } = require('./cmds/legacy');
 const { cmdStudioScaffold, cmdCardsValidate, cmdLockVerify, cmdStudioCompile, cmdStudioReadiness } = require('./cmds/studio');
 const { cmdTestRun, cmdTestImport } = require('./cmds/test');
@@ -138,6 +138,7 @@ Trace & Diagnostics:
 
 License & Authorization:
   license generate <domain> --to <email>   Generate signed license
+  license install <license.json>           Register license for auto-decrypt
   license verify <license.json>            Verify license signature
   license bind <license.json>              Bind license to this machine
   license show <license.json>              Display license details
@@ -436,10 +437,13 @@ switch (cmd) {
       cmdLicenseBind(rest);
     } else if (sub === 'show') {
       cmdLicenseShow(rest);
+    } else if (sub === 'install') {
+      cmdLicenseInstall(rest);
     } else {
       error(
         'Usage:\n' +
           '  kdna license generate <domain> --to <email> [--expires <date>]\n' +
+          '  kdna license install <license.json>\n' +
           '  kdna license verify <license.json>\n' +
           '  kdna license bind <license.json>\n' +
           '  kdna license show <license.json>',

package/src/cmds/license.js

@@ -81,7 +81,9 @@ function cmdLicenseGenerate(args) {
 }
 
 function cmdLicenseVerify(args) {
-  const licensePath = args[0];
+  const jsonMode = args.includes('--json');
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) error('Usage: kdna license verify <license.json>', EXIT.INPUT_ERROR);
 
   let license;
@@ -96,8 +98,6 @@ function cmdLicenseVerify(args) {
   const fp = machineFingerprint();
   const result = verifyLicense(license, publicKey, fp);
 
-  const jsonMode = args.includes('--json');
-
   if (jsonMode) {
     console.log(JSON.stringify({
       domain: license.domain,
@@ -135,7 +135,8 @@ function cmdLicenseVerify(args) {
 }
 
 function cmdLicenseBind(args) {
-  const licensePath = args[0];
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) error('Usage: kdna license bind <license.json>', EXIT.INPUT_ERROR);
 
   let license;
@@ -165,9 +166,9 @@ function cmdLicenseBind(args) {
 }
 
 function cmdLicenseShow(args) {
-  const licensePath = args[0];
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) {
-    // Try to find license in current directory
     const local = path.join(process.cwd(), 'license.json');
     if (fs.existsSync(local)) return cmdLicenseVerify([local, ...args.slice(1)]);
     error('Usage: kdna license show <license.json>', EXIT.INPUT_ERROR);
@@ -175,4 +176,32 @@ function cmdLicenseShow(args) {
   cmdLicenseVerify(args);
 }
 
-module.exports = { cmdLicenseGenerate, cmdLicenseVerify, cmdLicenseBind, cmdLicenseShow };
+function cmdLicenseInstall(args) {
+  const licensePath = args[0];
+  if (!licensePath) error('Usage: kdna license install <license.json>', EXIT.INPUT_ERROR);
+
+  let license;
+  try {
+    license = JSON.parse(fs.readFileSync(licensePath, 'utf8'));
+  } catch {
+    error(`Cannot read license file: ${licensePath}`, EXIT.INPUT_ERROR);
+  }
+
+  if (!license.domain) error('License missing domain field', EXIT.INPUT_ERROR);
+
+  const licenseDir = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna', 'licenses');
+  fs.mkdirSync(licenseDir, { recursive: true });
+
+  const safeName = license.domain.replace(/^@/, '').replace('/', '-');
+  const dest = path.join(licenseDir, `${safeName}.json`);
+
+  fs.writeFileSync(dest, JSON.stringify(license, null, 2) + '\n');
+
+  console.log(`License installed for ${license.domain}`);
+  console.log(`  License ID: ${license.license_id || 'unknown'}`);
+  console.log(`  Saved to: ${dest}`);
+  console.log('');
+  console.log(`Now install the domain: kdna install ${license.domain}`);
+}
+
+module.exports = { cmdLicenseGenerate, cmdLicenseVerify, cmdLicenseBind, cmdLicenseShow, cmdLicenseInstall };

package/src/install.js

@@ -20,6 +20,7 @@ const crypto = require('crypto');
 const { execSync, execFileSync } = require('child_process');
 const { RegistryResolver, parseName } = require('./registry');
 const { EXIT, error } = require('./cmds/_common');
+const { decrypt, deriveKey, machineFingerprint, isEncryptedContainer, ENCRYPTED_FILES } = require('./cmds/encrypt');
 
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
@@ -199,9 +200,9 @@ function warnLegacy() {
 // ─── Source parsing ─────────────────────────────────────────────────────
 
 function parseSource(input) {
-  // Local file
+  // Local file (.kdna or .kdnae)
   if (
-    input.endsWith('.kdna') &&
+    (input.endsWith('.kdna') || input.endsWith('.kdnae')) &&
     (input.startsWith('./') || input.startsWith('/') || input.startsWith('~/'))
   ) {
     const resolved = path.resolve(input.replace(/^~/, process.env.HOME || ''));
@@ -283,6 +284,53 @@ print('ok')
   }
 }
 
+function extractAndDecrypt(kdnaPath, destDir, licenseKey) {
+  extractKdna(kdnaPath, destDir);
+  const fp = machineFingerprint();
+  const key = deriveKey(licenseKey, fp);
+
+  for (const f of fs.readdirSync(destDir)) {
+    if (ENCRYPTED_FILES.includes(f)) {
+      try {
+        const fullPath = path.join(destDir, f);
+        const encrypted = fs.readFileSync(fullPath);
+        const decrypted = decrypt(encrypted, key);
+        fs.writeFileSync(fullPath, decrypted);
+      } catch (err) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+        error(`Failed to decrypt ${f}: ${err.message}. Wrong license key?`);
+      }
+    }
+  }
+}
+
+function findLicense(domainName) {
+  const licenseDir = path.join(USER_KDNA_DIR, 'licenses');
+  const licensePath = path.join(licenseDir, `${domainName.replace(/^@/, '').replace('/', '-')}.json`);
+  if (fs.existsSync(licensePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(licensePath, 'utf8'));
+    } catch { /* invalid license */ }
+  }
+  return null;
+}
+
+function findLicenseForDomain(domainFull) {
+  const licenseDir = path.join(USER_KDNA_DIR, 'licenses');
+  if (!fs.existsSync(licenseDir)) return null;
+  // Try exact match: @aikdna/writing → @aikdna-writing.json
+  const candidates = [domainFull.replace(/^@/, '').replace('/', '-')];
+  // Also try just the domain name
+  candidates.push(domainFull.split('/').pop());
+  for (const c of candidates) {
+    const p = path.join(licenseDir, `${c}.json`);
+    if (fs.existsSync(p)) {
+      try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { /* skip */ }
+    }
+  }
+  return null;
+}
+
 // ─── Signature verification ────────────────────────────────────────────
 
 function verifySignature({ destDir, scope, entry, lenient = true }) {
@@ -613,9 +661,53 @@ function installFromLocalFile(filePath, _yes, jsonMode = false) {
   const abs = path.resolve(filePath);
   if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) error(`Not a file: ${abs}`);
 
+  const isEncrypted = isEncryptedContainer(abs);
   const tmpDir = path.join(INSTALL_DIR, '.local-tmp-' + Date.now());
   ensureDir(tmpDir);
-  extractKdna(abs, tmpDir);
+
+  if (isEncrypted) {
+    // Find license for this .kdnae file
+    // First check the license directory, then ask for --license flag from args
+    const licenseFromArgs = process.argv.includes('--license')
+      ? process.argv[process.argv.indexOf('--license') + 1]
+      : null;
+    let licenseKey = null;
+
+    if (licenseFromArgs && fs.existsSync(licenseFromArgs)) {
+      try {
+        const lic = JSON.parse(fs.readFileSync(licenseFromArgs, 'utf8'));
+        licenseKey = lic.license_id;
+      } catch { /* invalid license file */ }
+    }
+
+    if (!licenseKey) {
+      // Try to auto-discover from ~/.kdna/licenses/
+      const manifest = readJson(path.join(tmpDir, 'kdna.json'));
+      // We need to extract just the manifest first to get the domain name
+      extractKdna(abs, tmpDir);
+      const mf = readJson(path.join(tmpDir, 'kdna.json'));
+      if (mf?.name) {
+        const lic = findLicenseForDomain(mf.name);
+        if (lic) licenseKey = lic.license_id;
+      }
+      if (!licenseKey) {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        error(
+          `Cannot install encrypted .kdnae without a license.\n` +
+            `Save the license to ~/.kdna/licenses/ or use --license <file>.`,
+          EXIT.TRUST_FAILED,
+        );
+      }
+      // Re-extract for decryption
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      ensureDir(tmpDir);
+    }
+
+    console.log('  Decrypting .kdnae container...');
+    extractAndDecrypt(abs, tmpDir, licenseKey);
+  } else {
+    extractKdna(abs, tmpDir);
+  }
 
   const manifest = readJson(path.join(tmpDir, 'kdna.json'));
   const declared = manifest?.name;
@@ -636,6 +728,7 @@ function installFromLocalFile(filePath, _yes, jsonMode = false) {
   destManifest._source = {
     type: 'local-file',
     path: abs,
+    encrypted: isEncrypted,
     installed_at: new Date().toISOString(),
   };
   fs.writeFileSync(path.join(dest, 'kdna.json'), JSON.stringify(destManifest, null, 2) + '\n');
@@ -647,9 +740,10 @@ function installFromLocalFile(filePath, _yes, jsonMode = false) {
       path: dest,
       source: 'local-file',
       source_path: abs,
+      encrypted: isEncrypted,
     }));
   } else {
-    console.log(`✓ Installed ${declared} from local file`);
+    console.log(`✓ Installed ${declared} from ${isEncrypted ? 'encrypted' : 'local'} file`);
     console.log(`  Location: ${dest}`);
   }
 }