@aikdna/kdna-cli 0.9.0

package/src/cluster.js

@@ -0,0 +1,235 @@
+/**
+ * KDNA Cluster — Composable judgment system operations.
+ *
+ * Commands:
+ *   cluster lint <path>     Validate cluster manifest
+ *   cluster apply <path> [input]  Simulate cluster routing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ─── Lint ──────────────────────────────────────────────────────────────
+
+function cmdClusterLint(clusterPath) {
+  const abs = path.resolve(clusterPath);
+  if (!fs.existsSync(abs)) error(`Cluster file not found: ${abs}`);
+
+  const cluster = readJson(abs);
+  if (!cluster) error('Invalid JSON');
+  if (!cluster.name) error('Missing cluster name');
+  if (!cluster.version) error('Missing cluster version');
+  if (!cluster.packages || !Array.isArray(cluster.packages)) error('Missing packages array');
+  if (cluster.packages.length < 2) error('Cluster must have ≥2 packages');
+
+  let warnings = 0;
+  let errors = 0;
+
+  // Check each package
+  const roles = ['primary', 'advisor', 'constraint', 'critic'];
+  let primaryCount = 0;
+
+  for (const pkg of cluster.packages) {
+    if (!pkg.id) {
+      console.error(`  ✗ Package missing id`);
+      errors++;
+      continue;
+    }
+    if (!pkg.role) {
+      console.error(`  ✗ ${pkg.id}: missing role`);
+      errors++;
+      continue;
+    }
+    if (!roles.includes(pkg.role)) {
+      console.error(`  ✗ ${pkg.id}: invalid role "${pkg.role}" (must be: ${roles.join(', ')})`);
+      errors++;
+    }
+    if (pkg.role === 'primary') primaryCount++;
+    if (!pkg.use_when || !Array.isArray(pkg.use_when) || pkg.use_when.length === 0) {
+      console.warn(`  ⚠ ${pkg.id}: no use_when conditions (will never be auto-selected)`);
+      warnings++;
+    }
+  }
+
+  if (primaryCount === 0) {
+    console.error(`  ✗ No primary package defined (exactly one required)`);
+    errors++;
+  } else if (primaryCount > 1) {
+    console.warn(`  ⚠ ${primaryCount} primary packages (typically exactly one)`);
+    warnings++;
+  }
+
+  // Check composition rules
+  if (!cluster.composition_rules || cluster.composition_rules.length === 0) {
+    console.warn(`  ⚠ No composition rules defined`);
+    warnings++;
+  }
+
+  // Check routing questions
+  if (!cluster.routing_questions || cluster.routing_questions.length === 0) {
+    console.warn(`  ⚠ No routing questions defined`);
+    warnings++;
+  }
+
+  // Check for duplicate package ids
+  const ids = cluster.packages.map((p) => p.id);
+  const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+  if (dupes.length > 0) {
+    for (const d of [...new Set(dupes)]) {
+      console.error(`  ✗ Duplicate package id: "${d}"`);
+      errors++;
+    }
+  }
+
+  if (errors > 0) {
+    console.error(`\n  ${errors} error(s), ${warnings} warning(s)`);
+    process.exit(1);
+  }
+
+  console.log(`✓ KDNA Cluster valid: ${cluster.name} v${cluster.version}`);
+  console.log(
+    `  Packages: ${cluster.packages.length} (${primaryCount} primary, ${cluster.packages.filter((p) => p.role === 'advisor').length} advisor, ${cluster.packages.filter((p) => p.role === 'constraint').length} constraint, ${cluster.packages.filter((p) => p.role === 'critic').length} critic)`,
+  );
+  console.log(`  Rules: ${cluster.composition_rules?.length || 0}`);
+  console.log(`  Routing questions: ${cluster.routing_questions?.length || 0}`);
+  if (warnings > 0) console.log(`  ${warnings} warning(s)`);
+}
+
+// ─── Apply ─────────────────────────────────────────────────────────────
+
+function cmdClusterApply(clusterPath, input) {
+  const abs = path.resolve(clusterPath);
+  if (!fs.existsSync(abs)) error(`Cluster file not found: ${abs}`);
+
+  const cluster = readJson(abs);
+  if (!cluster || !cluster.packages) error('Invalid cluster file');
+
+  // Use input from argument, or from stdin, or prompt
+  let taskInput = input;
+  if (!taskInput) {
+    // Try reading from stdin if not a TTY
+    if (!process.stdin.isTTY) {
+      taskInput = fs.readFileSync(0, 'utf8').trim();
+    }
+    if (!taskInput) {
+      console.log('Enter task description (Ctrl+D when done):');
+      taskInput = fs.readFileSync(0, 'utf8').trim();
+    }
+  }
+
+  if (!taskInput) {
+    error('No input provided. Usage: kdna cluster apply <path> "<task description>"');
+  }
+
+  const inputLower = taskInput.toLowerCase();
+
+  // Select primary: best-matching package by use_when keyword overlap
+  const primaryCandidates = cluster.packages.filter((p) => p.role === 'primary');
+  const advisorCandidates = cluster.packages.filter((p) => p.role === 'advisor');
+  const constraintCandidates = cluster.packages.filter((p) => p.role === 'constraint');
+
+  function matchScore(pkg) {
+    if (!pkg.use_when) return 0;
+    let score = 0;
+    for (const kw of pkg.use_when) {
+      if (inputLower.includes(kw.toLowerCase())) score++;
+    }
+    return score;
+  }
+
+  // Pick primary with highest keyword match
+  const scored = primaryCandidates.map((p) => ({ pkg: p, score: matchScore(p) }));
+  scored.sort((a, b) => b.score - a.score);
+  const primary = scored[0]?.pkg || primaryCandidates[0];
+
+  // Pick advisors that match (max 3, score > 0)
+  const advisors = advisorCandidates
+    .map((p) => ({ pkg: p, score: matchScore(p) }))
+    .filter((a) => a.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 3)
+    .map((a) => a.pkg);
+
+  // Load constraints that match (always active if triggered)
+  const constraints = constraintCandidates
+    .map((p) => ({ pkg: p, score: matchScore(p) }))
+    .filter((c) => c.score > 0)
+    .map((c) => c.pkg);
+
+  // Output
+  console.log('═'.repeat(60));
+  console.log(`  Cluster: ${cluster.name} v${cluster.version}`);
+  console.log('═'.repeat(60));
+  console.log('');
+  console.log(`  Task: ${taskInput.length > 80 ? taskInput.slice(0, 80) + '...' : taskInput}`);
+  console.log('');
+
+  console.log('  ── Selected Packages ──');
+  console.log('');
+  console.log(`  Primary:  ${primary.id} (${primary.role})`);
+  if (primary.use_when) {
+    const matched = primary.use_when.filter((kw) => inputLower.includes(kw.toLowerCase()));
+    console.log(
+      `    Matched: ${matched.length > 0 ? matched.join(', ') : '(fallback — no keyword match)'}`,
+    );
+  }
+
+  if (advisors.length > 0) {
+    console.log('');
+    console.log(`  Advisors (${advisors.length}):`);
+    for (const a of advisors) {
+      const matched = (a.use_when || []).filter((kw) => inputLower.includes(kw.toLowerCase()));
+      console.log(`    • ${a.id} — matched: ${matched.join(', ')}`);
+    }
+  }
+
+  if (constraints.length > 0) {
+    console.log('');
+    console.log(`  Constraints (${constraints.length}):`);
+    for (const c of constraints) {
+      const matched = (c.use_when || []).filter((kw) => inputLower.includes(kw.toLowerCase()));
+      console.log(`    • ${c.id} — triggered by: ${matched.join(', ')}`);
+    }
+  }
+
+  if (advisors.length === 0 && constraints.length === 0) {
+    console.log('');
+    console.log('  No advisors or constraints matched. Only primary loaded.');
+  }
+
+  console.log('');
+  console.log('  ── Composition Rules ──');
+  if (cluster.composition_rules) {
+    for (const rule of cluster.composition_rules) {
+      console.log(`    • ${rule}`);
+    }
+  }
+
+  console.log('');
+  console.log('  ── Routing Questions (to refine selection) ──');
+  if (cluster.routing_questions) {
+    for (const q of cluster.routing_questions) {
+      console.log(`    ? ${q}`);
+    }
+  }
+
+  console.log('');
+  console.log('═'.repeat(60));
+  console.log(`  Total packages to load: ${1 + advisors.length + constraints.length}`);
+  console.log('═'.repeat(60));
+}
+
+module.exports = { cmdClusterLint, cmdClusterApply };

package/src/cmds/_common.js

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+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');
+
+function usage() {
+  console.log(`kdna — KDNA domain cognition asset tool
+
+Usage:
+
+  --- Domain authors ---
+  kdna init <name>              Scaffold a new KDNA domain from template
+  kdna validate <path>          Validate a domain directory
+  kdna validate --schema <path>   ...with JSON Schema
+  kdna pack <path>              Pack a domain folder into a .kdna container
+  kdna pack --output <dir> <path>   Output .kdna to specific directory
+  kdna unpack <path>            Unpack a .kdna container to a folder
+  kdna inspect <path>           Inspect a domain directory or .kdna file
+  kdna publish <path>           Pack + sign + output registry patch
+  kdna publish <path> --release-tag <tag> --repo <o/r>   ...also upload to GitHub
+  kdna publish --check <path>   Run quality gate only (no pack/upload)
+  kdna version bump <patch|minor|major> [path]   Bump domain version
+  kdna cluster lint <path>      Validate a cluster manifest
+
+  --- Domain consumers ---
+  kdna install <name>           Install official domain: @aikdna/<name>
+  kdna install @scope/name      Install any scoped domain
+  kdna install @aikdna/animation    Install a cluster (installs all sub-domains)
+  kdna install ./file.kdna      Install from a local .kdna file
+  kdna install ./folder         Install from a local directory (dev)
+  kdna remove <name>            Uninstall a domain
+  kdna update <name>            Update an installed domain
+  kdna update --all             Update all installed domains
+  kdna info <name>              Show version, signature, governance, risks
+  kdna list                     List installed domains
+  kdna list --available         List available domains from registry
+  kdna search <keyword>         Search registry by name/keywords/insight
+  kdna registry refresh         Refresh the canonical registry cache
+
+  --- Quality + judgment ---
+  kdna verify <name>            Quality check: structure + trust + judgment
+  kdna compare <name> --input "<text>"   With/without KDNA reasoning diff
+  kdna diff <name>@<v1> <name>@<v2>      Judgment-level diff between versions
+
+  --- Agent-facing (called by the kdna-loader skill) ---
+  kdna available [--json]                List installed domains + v2.1 fields
+  kdna match "<task>" [--json]           Hint signals (dropped + weak overlap)
+  kdna load <name> [--as=prompt|json|raw]   Emit domain in agent-ready format
+
+  --- Identity ---
+  kdna identity init            Generate Ed25519 identity key pair
+  kdna identity show            Display public key and buyer ID
+  kdna identity export [--out]  Backup private key (passphrase-encrypted)
+  kdna identity import <file>   Restore identity from backup
+
+  --- Other ---
+  kdna setup                    One-command setup: CLI + skill + data root
+  kdna version                  Show kdna CLI version
+  kdna help                     Show this help
+
+Examples:
+  kdna install writing
+  kdna verify @aikdna/writing
+  kdna available
+  kdna init my_domain
+  kdna publish ./my_domain --release-tag v0.1.0 --repo yourname/kdna-my_domain`);
+}
+
+function error(msg) {
+  console.error(`Error: ${msg}`);
+  process.exit(1);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, data) {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+}
+
+function loadRegistry() {
+  return loadCanonicalRegistry({ allowNetwork: true });
+}
+
+module.exports = {
+  USER_KDNA_DIR,
+  INSTALL_DIR,
+  usage,
+  error,
+  readJson,
+  writeJson,
+  loadRegistry,
+};

package/src/cmds/cluster.js

@@ -0,0 +1,235 @@
+const fs = require('fs');
+const path = require('path');
+const { error, readJson } = require('./_common');
+const {
+  loadCluster,
+  classifySignalsAcrossDomains,
+  composeContextWithAttribution,
+  detectDomainConflicts,
+  generateClusterTrace,
+} = require('@aikdna/kdna-core');
+
+function cmdCluster(args) {
+  const { cmdClusterLint } = require('../cluster');
+  const sub = args[1];
+  const target = args[2];
+
+  if (sub === 'lint') {
+    if (!target) error('Usage: kdna cluster lint <path>');
+    cmdClusterLint(target);
+  } else if (sub === 'init') {
+    const { cmdClusterInit } = require('../init');
+    cmdClusterInit(target);
+  } else if (sub === 'info') {
+    if (!target) error('Usage: kdna cluster info <path>');
+    cmdClusterInfo(target);
+  } else if (sub === 'load') {
+    if (!target) error('Usage: kdna cluster load <cluster.json> --input "<task>"');
+    cmdClusterLoad(target, args);
+  } else if (sub === 'match') {
+    if (!target) error('Usage: kdna cluster match <cluster.json> --input "<task>"');
+    cmdClusterMatch(target, args);
+  } else if (sub === 'apply') {
+    error(
+      'kdna cluster apply was removed in v0.9.\n' +
+        'To install a cluster (which installs all its sub-domains):\n' +
+        '  kdna install @aikdna/animation',
+    );
+  } else {
+    error(
+      `Unknown cluster subcommand: ${sub || '(none)'}\n` +
+        'Usage: kdna cluster lint <path>\n' +
+        '       kdna cluster init <name>\n' +
+        '       kdna cluster info <cluster.json>\n' +
+        '       kdna cluster match <cluster.json> --input "<task>"\n' +
+        '       kdna cluster load <cluster.json> --input "<task>"',
+    );
+  }
+}
+
+function cmdClusterInfo(target, format = 'human') {
+  const abs = path.resolve(target);
+  if (!fs.existsSync(abs)) error(`Cluster manifest not found: ${abs}`);
+
+  const manifest = readJson(abs);
+  if (!manifest) error(`Invalid cluster manifest (not valid JSON)`);
+  if (!manifest.cluster_id) error(`Not a valid cluster manifest (missing cluster_id)`);
+
+  const domainCount = (manifest.domains || []).length;
+  const requiredCount = (manifest.domains || []).filter((d) => d.required !== false).length;
+  const composition = manifest.composition || {};
+
+  console.log(`${manifest.name || manifest.cluster_id}`);
+  console.log(`  Cluster ID:       ${manifest.cluster_id}`);
+  console.log(`  Version:          ${manifest.version || '?'}`);
+  console.log(`  Type:             ${manifest.type || 'horizontal'}`);
+  console.log(`  Status:           ${manifest.status || 'experimental'}`);
+  console.log(`  Domains:          ${domainCount} total, ${requiredCount} required`);
+  console.log(`  Strategy:         ${composition.strategy || 'fixed'}`);
+  console.log(`  Max active:       ${composition.max_active_domains || 'unlimited'}`);
+  console.log(`  Conflict policy:  ${composition.conflict_policy || 'surface'}`);
+  console.log('');
+
+  if (manifest.domains?.length) {
+    console.log('  Domain inventory:');
+    for (const d of manifest.domains) {
+      const req = d.required !== false ? '(required)' : '(optional)';
+      console.log(`    ${d.role.padEnd(16)} ${d.id} ${req}`);
+    }
+    console.log('');
+  }
+
+  if (manifest.relationships?.length) {
+    console.log('  Relationships:');
+    for (const r of manifest.relationships) {
+      console.log(`    ${r.from} --${r.type}--> ${r.to}`);
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Load a cluster: resolve domains from installed ~/.kdna/domains/,
+ * classify input signals, compose context with attribution, detect
+ * conflicts, and emit the composed context.
+ */
+function cmdClusterLoad(target, args = []) {
+  const abs = path.resolve(target);
+  if (!fs.existsSync(abs)) error(`Cluster manifest not found: ${abs}`);
+
+  const inputIdx = args.indexOf('--input');
+  const input = inputIdx >= 0 ? args[inputIdx + 1] : '';
+  if (!input) error('Usage: kdna cluster load <cluster.json> --input "<task>"');
+
+  const manifest = readJson(abs);
+  if (!manifest || !manifest.cluster_id) error('Not a valid cluster manifest');
+
+  const INSTALL_DIR = path.join(
+    process.env.HOME || process.env.USERPROFILE || '.',
+    '.kdna',
+    'domains',
+  );
+
+  // Domain loader: resolve from installed ~/.kdna/domains/
+  const domainLoader = (domainId) => {
+    const [scope, ident] = domainId.startsWith('@')
+      ? [domainId.slice(0, domainId.indexOf('/')), domainId.slice(domainId.indexOf('/') + 1)]
+      : ['@aikdna', domainId];
+    const dir = path.join(INSTALL_DIR, scope, ident);
+    const core = readJson(path.join(dir, 'KDNA_Core.json'));
+    const pat = readJson(path.join(dir, 'KDNA_Patterns.json'));
+    if (!core || !pat) return null;
+    return { core, patterns: pat };
+  };
+
+  const result = loadCluster(abs, domainLoader);
+  if (result.errors.length) {
+    console.error('Warnings:');
+    result.errors.forEach((e) => console.error(`  - ${e}`));
+  }
+
+  // Classify signals
+  const classification = classifySignalsAcrossDomains(input, result.domains);
+
+  console.log(`Cluster: ${manifest.cluster_id}`);
+  console.log(`Input:   ${input.slice(0, 100)}${input.length > 100 ? '...' : ''}`);
+  console.log('');
+
+  if (classification.excluded.length) {
+    console.log(`Excluded domains (${classification.excluded.length}):`);
+    classification.excluded.forEach((d) => {
+      console.log(`  - ${d.id} (${d.reason})`);
+    });
+    console.log('');
+  }
+
+  if (!classification.selected.length) {
+    console.log('No domains matched. Try a different input or check domain trigger_signals.');
+    return;
+  }
+
+  console.log(`Selected domains (${classification.selected.length}):`);
+  classification.selected.forEach((d) => {
+    console.log(`  + ${d.id} (${d.role}) ← ${d.reason}`);
+  });
+  console.log('');
+
+  // Detect conflicts
+  const conflicts = detectDomainConflicts(classification.selected);
+  if (conflicts.length) {
+    console.log(`Conflicts detected (${conflicts.length}):`);
+    conflicts.forEach((c) => {
+      console.log(`  ⚠ [${c.type}] ${c.domains.join(' vs ')}: ${c.description}`);
+    });
+    console.log('');
+  }
+
+  // Compose context with attribution
+  const { context } = composeContextWithAttribution(classification.selected);
+  console.log('─'.repeat(64));
+  console.log(context);
+  console.log('─'.repeat(64));
+
+  // Judgment trace
+  const trace = generateClusterTrace({
+    input,
+    loadedDomains: result.domains,
+    activeDomains: classification.selected,
+    conflicts,
+  });
+  console.log('');
+  console.log('Judgment trace:');
+  console.log(JSON.stringify(trace, null, 2));
+}
+
+/**
+ * Match input against cluster domains without composing full context.
+ */
+function cmdClusterMatch(target, args = []) {
+  const abs = path.resolve(target);
+  if (!fs.existsSync(abs)) error(`Cluster manifest not found: ${abs}`);
+
+  const inputIdx = args.indexOf('--input');
+  const input = inputIdx >= 0 ? args[inputIdx + 1] : '';
+  if (!input) error('Usage: kdna cluster match <cluster.json> --input "<task>"');
+
+  const manifest = readJson(abs);
+  if (!manifest || !manifest.cluster_id) error('Not a valid cluster manifest');
+
+  const INSTALL_DIR = path.join(
+    process.env.HOME || process.env.USERPROFILE || '.',
+    '.kdna',
+    'domains',
+  );
+
+  const domainLoader = (domainId) => {
+    const [scope, ident] = domainId.startsWith('@')
+      ? [domainId.slice(0, domainId.indexOf('/')), domainId.slice(domainId.indexOf('/') + 1)]
+      : ['@aikdna', domainId];
+    const dir = path.join(INSTALL_DIR, scope, ident);
+    const core = readJson(path.join(dir, 'KDNA_Core.json'));
+    const pat = readJson(path.join(dir, 'KDNA_Patterns.json'));
+    if (!core || !pat) return null;
+    return { core, patterns: pat };
+  };
+
+  const result = loadCluster(abs, domainLoader);
+  const classification = classifySignalsAcrossDomains(input, result.domains);
+
+  console.log(`Input: ${input.slice(0, 100)}${input.length > 100 ? '...' : ''}`);
+  console.log(`Cluster: ${manifest.cluster_id} (${result.domains.length} domains loaded)`);
+  console.log('');
+  console.log(
+    `Matched: ${classification.selected.length} | Excluded: ${classification.excluded.length}`,
+  );
+  console.log('');
+
+  classification.selected.forEach((d) => {
+    console.log(`  ✓ ${d.id} [${d.role}]`);
+  });
+  classification.excluded.forEach((d) => {
+    console.log(`  ✗ ${d.id}: ${d.reason}`);
+  });
+}
+
+module.exports = { cmdCluster };