wize-dev-kit 0.1.5 → 0.2.0

package/tools/installer/commands/agent.js

@@ -0,0 +1,197 @@
+// `wize-dev-kit agent <subcommand>` — manage built-in and custom agents.
+//
+//   list        - show every agent the active install resolves (built-in + custom)
+//   create      - scaffold a brand-new custom agent in .wize/custom/agents/{code}/
+//   edit <code> - override an existing built-in via .wize/custom/agents/{code}/customize.toml
+//
+// All write operations validate the result against schemas/agent.schema.json
+// (lite parser — no dependency on Ajv yet) and do a smoke dry-run before
+// persisting, matching the contract `wize-create-agent` describes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const prompts = require('prompts');
+const { collectAssets } = require('../render-shared.js');
+
+const VALID_CODE = /^wize-(agent|orchestrator)(?:-[a-z0-9-]+)?$/;
+const VALID_MODULES = ['orchestrator', 'method', 'tea', 'builder', 'core', 'web-overlay', 'app-overlay', 'custom'];
+
+function ensureDir(p) { fs.mkdirSync(p, { recursive: true }); }
+
+function listAgents(kitRoot, projectRoot) {
+  const builtIn = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent')
+    .map(a => ({ code: a.code, name: a.name, title: a.title, source: 'built-in' }));
+  const customDir = path.join(projectRoot, '.wize/custom/agents');
+  const custom = [];
+  if (fs.existsSync(customDir)) {
+    for (const entry of fs.readdirSync(customDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const yamlPath = path.join(customDir, entry.name, 'agent.yaml');
+      const customizePath = path.join(customDir, entry.name, 'customize.toml');
+      if (fs.existsSync(yamlPath)) {
+        const yaml = fs.readFileSync(yamlPath, 'utf-8');
+        const name = (yaml.match(/^name:\s*(.+)$/m) || [])[1] || entry.name;
+        const title = (yaml.match(/^title:\s*(.+)$/m) || [])[1] || '';
+        custom.push({ code: entry.name, name: name.trim(), title: title.trim(), source: 'custom' });
+      } else if (fs.existsSync(customizePath)) {
+        custom.push({ code: entry.name, name: '(override)', title: '', source: 'override' });
+      }
+    }
+  }
+  return { builtIn, custom };
+}
+
+function cmdAgentList({ kitRoot, projectRoot, log = console.log } = {}) {
+  const { builtIn, custom } = listAgents(kitRoot, projectRoot);
+  log('Built-in agents:');
+  for (const a of builtIn) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}`);
+  if (custom.length) {
+    log('\nCustom / override agents (from .wize/custom/agents/):');
+    for (const a of custom) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}   [${a.source}]`);
+  } else {
+    log('\nCustom / override agents: (none yet — use `wize-dev-kit agent create`)');
+  }
+  return { builtIn, custom };
+}
+
+function validateAgent(spec, kitRoot) {
+  const errs = [];
+  if (!spec.code) errs.push('code is required');
+  else if (!VALID_CODE.test(spec.code)) errs.push(`code "${spec.code}" must match wize-(agent|orchestrator)[-name]`);
+  if (!spec.name) errs.push('name is required');
+  if (!spec.title) errs.push('title is required');
+  if (!VALID_MODULES.includes(spec.module)) errs.push(`module must be one of: ${VALID_MODULES.join(', ')}`);
+  if (!spec.description || spec.description.length < 10) errs.push('description must be ≥ 10 characters');
+  // Collide check against built-ins when not overriding.
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (builtinCodes.includes(spec.code) && !spec.allowOverride) {
+    errs.push(`code "${spec.code}" already exists as a built-in. Use \`wize-dev-kit agent edit ${spec.code}\` to override.`);
+  }
+  return errs;
+}
+
+function renderAgentYaml(spec) {
+  return [
+    `code: ${spec.code}`,
+    `name: ${spec.name}`,
+    `title: ${spec.title}`,
+    `icon: "${spec.icon || '🔧'}"`,
+    `team: ${spec.team || 'software-development'}`,
+    `module: ${spec.module}`,
+    '',
+    'description: |',
+    ...spec.description.split('\n').map(l => '  ' + l),
+    ''
+  ].join('\n');
+}
+
+function renderPersonaMd(spec) {
+  const body = (spec.persona || `I am **${spec.name}**. ${spec.description}`).trim();
+  return [
+    `# ${spec.name} — ${spec.title}`,
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
+// Smoke dry-run: write to temp dir, re-read, assert frontmatter parses.
+function dryRunPersist(spec) {
+  const tmp = path.join(require('node:os').tmpdir(), `wize-agent-${spec.code}-${Date.now()}`);
+  ensureDir(tmp);
+  try {
+    fs.writeFileSync(path.join(tmp, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+    fs.writeFileSync(path.join(tmp, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+    const reread = fs.readFileSync(path.join(tmp, 'agent.yaml'), 'utf-8');
+    if (!/^code:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "code:" line');
+    if (!/^name:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "name:" line');
+    return { ok: true };
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+async function cmdAgentCreate({ kitRoot, projectRoot, opts = {} } = {}) {
+  const interactive = process.stdout.isTTY && process.stdin.isTTY && !opts.fromSpec;
+  let spec = opts.fromSpec || {};
+
+  if (interactive) {
+    const a = await prompts([
+      { type: 'text', name: 'code',  message: 'Agent code (e.g. wize-agent-runbooks)',
+        validate: v => VALID_CODE.test(v) || 'must match wize-(agent|orchestrator)[-name]' },
+      { type: 'text', name: 'name',  message: 'Display name (e.g. Riri Williams)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'title', message: 'Role / title (e.g. Reliability Engineer)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'icon',  message: 'Icon emoji (optional)', initial: '🔧' },
+      { type: 'text', name: 'team',  message: 'Team', initial: 'software-development' },
+      { type: 'select', name: 'module', message: 'Module', choices: VALID_MODULES.map(v => ({ title: v, value: v })), initial: VALID_MODULES.indexOf('custom') },
+      { type: 'text', name: 'description', message: 'One-paragraph description (≥ 10 chars)', validate: v => v.length >= 10 || 'must be ≥ 10 characters' },
+      { type: 'text', name: 'persona', message: 'Persona body (optional — defaults to description)', initial: '' }
+    ], { onCancel: () => process.exit(130) });
+    spec = { ...spec, ...a };
+  }
+
+  const errs = validateAgent(spec, kitRoot);
+  if (errs.length) {
+    console.error('✖ Validation failed:');
+    for (const e of errs) console.error('  - ' + e);
+    process.exit(2);
+  }
+
+  const dry = dryRunPersist(spec);
+  if (!dry.ok) {
+    console.error('✖ Dry-run failed; aborting.');
+    process.exit(3);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', spec.code);
+  ensureDir(target);
+  fs.writeFileSync(path.join(target, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+  fs.writeFileSync(path.join(target, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+
+  console.log(`✓ Created ${path.relative(projectRoot, target)}/`);
+  console.log('  Run `wize-dev-kit sync` to refresh IDE adapter outputs with the new agent.');
+  return { code: spec.code, path: target };
+}
+
+async function cmdAgentEdit({ kitRoot, projectRoot, code, opts = {} } = {}) {
+  if (!code) {
+    console.error('Usage: wize-dev-kit agent edit <code>');
+    process.exit(1);
+  }
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (!builtinCodes.includes(code)) {
+    console.error(`✖ "${code}" is not a built-in agent. Use \`wize-dev-kit agent create\` for new agents.`);
+    process.exit(2);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', code);
+  ensureDir(target);
+  const customize = path.join(target, 'customize.toml');
+  if (fs.existsSync(customize) && !opts.force) {
+    console.log(`= ${path.relative(projectRoot, customize)} already exists. Edit it directly.`);
+    return { code, path: customize };
+  }
+  fs.writeFileSync(customize, `# Wize Dev Kit — overrides for the built-in agent "${code}".
+# This file is loaded on top of the built-in agent's persona.md / agent.yaml
+# at IDE adapter render time. Only the fields you set here are overridden.
+
+[persona]
+# motto      = "your custom motto"
+# voice      = "succinct and irreverent"
+# style      = "show with code, not prose"
+
+[behavior]
+# defer_to   = []         # e.g. ["wize-agent-pm"] to lower priority on certain decisions
+# tools_deny = []         # tool codes the override removes from the agent
+`, 'utf-8');
+  console.log(`✓ Created ${path.relative(projectRoot, customize)}`);
+  console.log('  Edit the file, then run `wize-dev-kit sync` to apply.');
+  return { code, path: customize };
+}
+
+module.exports = { cmdAgentList, cmdAgentCreate, cmdAgentEdit, listAgents, validateAgent };

package/tools/installer/commands/sync.js

@@ -0,0 +1,45 @@
+// `wize-dev-kit sync` — regenerate adapter outputs for the IDE targets the
+// project opted into. Useful after editing .wize/config/project.toml,
+// running `agent create`, or pulling kit changes that don't bump version.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadProjectConfig } = require('./update.js');
+
+function cmdSync({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cfg = loadProjectConfig(projectRoot);
+  if (!cfg.project) {
+    log('No .wize/config/project.toml found here. Run `wize-dev-kit install` first.');
+    return { changed: false };
+  }
+  const ideTargets = (cfg.install && cfg.install.ide_targets) || ['claude-code', 'generic'];
+  const profiles = (cfg.install && cfg.install.profiles) || ['core'];
+  log(`Syncing ${ideTargets.length} adapter(s) for profile(s) ${profiles.join(' + ')}:`);
+
+  const results = [];
+  for (const code of ideTargets) {
+    const renderPath = path.join(kitRoot, 'adapters', code, 'render.js');
+    if (!fs.existsSync(renderPath)) {
+      log(`  - ${code}: skipped (adapter missing in installed kit)`);
+      results.push({ code, skipped: true });
+      continue;
+    }
+    delete require.cache[require.resolve(renderPath)];
+    try {
+      const out = require(renderPath).render(kitRoot, projectRoot, { profiles });
+      const n = out && Array.isArray(out.written) ? out.written.length : 0;
+      log(`  ✓ ${code}: ${n} file(s) emitted`);
+      results.push({ code, written: n });
+    } catch (err) {
+      log(`  ✖ ${code}: ${err.message}`);
+      results.push({ code, error: err.message });
+    }
+  }
+  log('\nDone. Restart your IDE if it caches skills at startup.');
+  return { changed: true, adapters: results };
+}
+
+module.exports = { cmdSync };

package/tools/installer/commands/update.js

@@ -0,0 +1,172 @@
+// `wize-dev-kit update` — refresh an installed kit to the version currently
+// resolved by `node_modules/wize-dev-kit`. Preserves .wize/config/user.toml,
+// re-runs the active IDE adapters, and re-applies the .gitignore block when
+// it was opted-in originally.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { applyGitignore } = require('../setup-helpers.js');
+
+// Minimal TOML reader for the subset we write — handles `[section]` headers,
+// `key = "value"` scalars, and `key = ["a", "b"]` string arrays.
+function readToml(file) {
+  if (!fs.existsSync(file)) return {};
+  const content = fs.readFileSync(file, 'utf-8');
+  const out = {};
+  let section = null;
+  for (const raw of content.split('\n')) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const head = line.match(/^\[([^\]]+)\]$/);
+    if (head) { section = head[1]; out[section] = out[section] || {}; continue; }
+    const kv = line.match(/^([a-zA-Z_][\w-]*)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    const [, key, valRaw] = kv;
+    const v = parseTomlValue(valRaw.trim());
+    if (section) out[section][key] = v;
+    else out[key] = v;
+  }
+  return out;
+}
+
+function parseTomlValue(raw) {
+  if (raw.startsWith('"') && raw.endsWith('"')) return raw.slice(1, -1);
+  if (raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    return raw.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  }
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (!isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+function loadProjectConfig(projectRoot) {
+  return readToml(path.join(projectRoot, '.wize/config/project.toml'));
+}
+
+function loadInstalledKitVersion(kitRoot) {
+  try { return require(path.join(kitRoot, 'package.json')).version; }
+  catch { return null; }
+}
+
+// Returns a list of CHANGELOG entries (markdown blocks) for versions strictly
+// between `from` and `to`. Best-effort — if CHANGELOG layout is unusual,
+// returns an empty list and falls back to a generic note.
+function changelogBetween(kitRoot, fromVersion, toVersion) {
+  const file = path.join(kitRoot, 'CHANGELOG.md');
+  if (!fs.existsSync(file)) return [];
+  const content = fs.readFileSync(file, 'utf-8');
+  const versionRe = /^## \[(\d+\.\d+\.\d+)\][^\n]*\n/gm;
+  const matches = [];
+  let m;
+  while ((m = versionRe.exec(content)) !== null) {
+    matches.push({ v: m[1], start: m.index, headerEnd: versionRe.lastIndex });
+  }
+  for (let i = 0; i < matches.length; i++) {
+    matches[i].end = i + 1 < matches.length ? matches[i + 1].start : content.length;
+  }
+  return matches
+    .filter(x => compare(x.v, fromVersion) > 0 && compare(x.v, toVersion) <= 0)
+    .map(x => content.slice(x.start, x.end).trim());
+}
+
+function compare(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
+
+// Re-runs every adapter that the project opted into at install time, using
+// the current versions of the kit's renderers.
+function rerunAdapters({ kitRoot, projectRoot, ideTargets, profiles, log }) {
+  const results = [];
+  for (const code of ideTargets) {
+    const renderPath = path.join(kitRoot, 'adapters', code, 'render.js');
+    if (!fs.existsSync(renderPath)) {
+      results.push({ code, skipped: true, reason: 'adapter missing in this kit version' });
+      log(`  - ${code}: skipped (adapter no longer exists)`);
+      continue;
+    }
+    delete require.cache[require.resolve(renderPath)]; // make `update` idempotent in the same process
+    try {
+      const mod = require(renderPath);
+      const out = mod.render(kitRoot, projectRoot, { profiles });
+      const n = out && Array.isArray(out.written) ? out.written.length : 0;
+      results.push({ code, written: n });
+      log(`  ✓ ${code}: ${n} file(s) refreshed`);
+    } catch (err) {
+      results.push({ code, error: err.message });
+      log(`  ✖ ${code}: ${err.message}`);
+    }
+  }
+  return results;
+}
+
+function writeUpdatedProjectToml(projectRoot, currentToml, newKitVersion) {
+  // Surgical rewrite — only updates `kit_version = ...` under `[project]`.
+  // Leaves everything else as the user/team configured it.
+  const file = path.join(projectRoot, '.wize/config/project.toml');
+  if (!fs.existsSync(file)) return false;
+  const content = fs.readFileSync(file, 'utf-8');
+  const updated = content.replace(/^kit_version\s*=\s*".*"$/m, `kit_version = "${newKitVersion}"`);
+  if (updated === content) return false;
+  fs.writeFileSync(file, updated, 'utf-8');
+  return true;
+}
+
+async function cmdUpdate({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cfg = loadProjectConfig(projectRoot);
+  if (!cfg.project) {
+    log('No .wize/config/project.toml found here.');
+    log('Run `wize-dev-kit install` first.');
+    return { changed: false };
+  }
+  const fromVersion = cfg.project.kit_version || '0.0.0';
+  const toVersion = loadInstalledKitVersion(kitRoot) || 'unknown';
+  if (toVersion === 'unknown') {
+    log('Could not read kit version from node_modules. Aborting.');
+    return { changed: false };
+  }
+
+  log(`Wize Dev Kit update: ${fromVersion} → ${toVersion}`);
+  if (fromVersion === toVersion) {
+    log('Already on the same version. Re-rendering adapters anyway (idempotent).');
+  }
+
+  const ideTargets = (cfg.install && cfg.install.ide_targets) || ['claude-code', 'generic'];
+  const profiles = (cfg.install && cfg.install.profiles) || ['core'];
+
+  log('\nRe-rendering active IDE adapters:');
+  const adapterResults = rerunAdapters({ kitRoot, projectRoot, ideTargets, profiles, log });
+
+  if (opts.refreshGitignore !== false) {
+    const r = applyGitignore(projectRoot);
+    if (r.changed) log(`\n✓ .gitignore ${r.mode}`);
+    else            log('\n= .gitignore already up to date');
+  }
+
+  writeUpdatedProjectToml(projectRoot, cfg, toVersion);
+  log(`\n✓ project.toml kit_version → ${toVersion}`);
+
+  const entries = changelogBetween(kitRoot, fromVersion, toVersion);
+  if (entries.length) {
+    log(`\nWhat changed (excerpt from CHANGELOG):`);
+    for (const e of entries) {
+      log(e.split('\n').slice(0, 4).map(l => '  ' + l).join('\n'));
+      log('  …');
+    }
+    log(`\nFull details: ${path.join(kitRoot, 'CHANGELOG.md')}`);
+  }
+
+  log('\nDone. Restart your IDE so the refreshed slash commands are picked up.');
+  return { changed: true, from: fromVersion, to: toVersion, adapters: adapterResults };
+}
+
+module.exports = { cmdUpdate, loadProjectConfig, loadInstalledKitVersion, changelogBetween };

package/tools/installer/wize-cli.js

@@ -15,6 +15,9 @@ const path = require('node:path');
 const readline = require('node:readline');
 const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
+const { cmdUpdate } = require('./commands/update.js');
+const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
+const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
 
 const INTERACTIVE = process.stdout.isTTY && process.stdin.isTTY;
 
@@ -386,7 +389,19 @@ async function cmdInstall(args) {
     }
   }
 
-  console.log('\nDone. Activate Wizer in your IDE and say: "Brief me on this project."');
+  console.log('\n──────────────────────────────────────────────────────────────');
+  console.log('Done.');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. ⚠  Restart your IDE — many harnesses load skills only at startup.');
+  console.log('  2. Activate Wizer and say: "Brief me on this project."');
+  console.log('     (or use any /wize-* slash command from the auto-complete list)');
+  console.log('');
+  console.log('Keep the kit in sync over time:');
+  console.log('  • `npx wize-dev-kit update`  refresh adapters after a new kit version');
+  console.log('  • `npx wize-dev-kit sync`    re-render adapters after editing config');
+  console.log('  • `npx wize-dev-kit agent list | create | edit <code>`  manage agents');
+  console.log('──────────────────────────────────────────────────────────────');
 }
 
 async function cmdUninstall() {
@@ -432,17 +447,18 @@ function cmdList() {
 }
 
 function cmdSync() {
-  console.log('(stub) Sync would regenerate IDE adapter files for active targets in .wize/config/project.toml.');
+  return cmdSyncReal({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
 }
 
 function cmdAgent(args) {
   const sub = args[0] || 'list';
-  if (sub === 'list') return cmdList();
-  if (sub === 'create') {
-    console.log('(stub) Interactive agent creation. See src/builder-skills/wize-create-agent/workflow.md.');
-    return;
-  }
+  const rest = args.slice(1);
+  const ctx = { kitRoot: KIT_ROOT, projectRoot: process.cwd() };
+  if (sub === 'list')   return cmdAgentList(ctx);
+  if (sub === 'create') return cmdAgentCreate(ctx);
+  if (sub === 'edit')   return cmdAgentEdit({ ...ctx, code: rest[0] });
   console.log(`Unknown agent subcommand: ${sub}`);
+  console.log('Available: list | create | edit <code>');
 }
 
 function cmdWorkflow(args) {
@@ -467,7 +483,7 @@ async function main() {
   }
   switch (cmd) {
     case 'install':   return cmdInstall(rest);
-    case 'update':    console.log('(stub) Update: diff + preserve customizations. Not yet implemented.'); return;
+    case 'update':    return cmdUpdate({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
     case 'uninstall': return cmdUninstall();
     case 'list':      return cmdList();
     case 'sync':      return cmdSync();