wize-dev-kit 0.1.5 → 0.2.5

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/version-check.js

@@ -0,0 +1,117 @@
+// Best-effort, non-blocking npm registry check for "is there a newer wize-dev-kit
+// version than the one I'm running?". Designed so the CLI can call it from
+// `list` / `agent list` / `help` and print a single hint at the top, without
+// ever blocking the command if the network is slow, the user is offline, or
+// the registry is misbehaving.
+//
+// Strategy:
+//   - Cache the registry answer in $XDG_CACHE_HOME (or ~/.cache) for 1 hour.
+//   - Resolve via fetch with a 1.5s timeout. Failure is silent.
+//   - Compare with the kit version baked into the running CLI.
+//   - Expose a `printUpdateHintIfAny(currentVersion)` helper for the CLI.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CACHE_TTL_MS = 60 * 60 * 1000;       // 1h
+const NETWORK_TIMEOUT_MS = 1500;
+
+function cacheFile() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'wize-dev-kit', 'registry-version.json');
+}
+
+function readCache() {
+  const f = cacheFile();
+  try {
+    const stat = fs.statSync(f);
+    if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
+    return JSON.parse(fs.readFileSync(f, 'utf-8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  const f = cacheFile();
+  try {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(payload), 'utf-8');
+  } catch (_) { /* cache failure is harmless */ }
+}
+
+async function fetchLatestFromRegistry() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    const res = await fetch('https://registry.npmjs.org/wize-dev-kit', {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/vnd.npm.install-v1+json' }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const latest = body && body['dist-tags'] && body['dist-tags'].latest;
+    return typeof latest === 'string' ? latest : null;
+  } catch (_) {
+    return null;   // any error → silent fallback
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Returns the registry-latest version, hitting the cache first. Never throws,
+// never blocks meaningfully (network call is capped + abortable).
+async function getLatestVersion({ skipCache = false } = {}) {
+  if (!skipCache) {
+    const c = readCache();
+    if (c && c.version) return c.version;
+  }
+  const fresh = await fetchLatestFromRegistry();
+  if (fresh) writeCache({ version: fresh, fetched_at: Date.now() });
+  return fresh;
+}
+
+function semverGreater(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return true;
+    if ((pa[i] || 0) < (pb[i] || 0)) return false;
+  }
+  return false;
+}
+
+// Prints a one-line hint when a newer version is available. Silent otherwise.
+// Designed to be awaited near the top of a CLI command; if anything is slow
+// or off, it just returns.
+async function printUpdateHintIfAny(currentVersion, { log = console.log, isTTY = process.stdout.isTTY } = {}) {
+  if (process.env.WIZE_DISABLE_UPDATE_CHECK === '1') return;
+  if (!isTTY) return;            // don't spam pipes
+  try {
+    const latest = await getLatestVersion();
+    if (!latest) return;
+    if (semverGreater(latest, currentVersion)) {
+      log('');
+      log(`  ↑ Update available: wize-dev-kit ${currentVersion} → ${latest}`);
+      log(`    Run \`npx wize-dev-kit@latest update\` in your project to refresh adapters.`);
+      log('');
+    }
+  } catch (_) {
+    /* total fallback — never block the command */
+  }
+}
+
+module.exports = {
+  CACHE_TTL_MS,
+  NETWORK_TIMEOUT_MS,
+  cacheFile,
+  readCache,
+  writeCache,
+  fetchLatestFromRegistry,
+  getLatestVersion,
+  semverGreater,
+  printUpdateHintIfAny
+};