wize-dev-kit 0.16.0 → 0.16.1

package/tools/installer/commands/document-project.js

@@ -0,0 +1,93 @@
+// `wize-dev-kit document-project` — CLI command entry point.
+//
+// Parses mode + flags and delegates to the appropriate scan implementation.
+// Non-quick modes are stubs here; later stories fill them in.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { runQuick } = require('../document-project/modes/quick.js');
+const { runInitialScan } = require('../document-project/modes/initial-scan.js');
+const { runFullRescan } = require('../document-project/modes/full-rescan.js');
+const { runDeepDive } = require('../document-project/modes/deep-dive.js');
+const { loadState, archiveOldState } = require('../document-project/state.js');
+
+const VALID_MODES = new Set(['quick', 'initial_scan', 'full_rescan', 'deep_dive']);
+const VALID_SCAN_LEVELS = new Set(['quick', 'deep', 'exhaustive']);
+
+function parseMode(args) {
+  let mode = 'quick';
+  let resume = false;
+  let scanLevel = 'quick';
+  let target = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--resume') {
+      resume = true;
+      continue;
+    }
+    if (arg === '--target') {
+      target = args[i + 1];
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      return { mode: null, error: `unknown option: ${arg}` };
+    }
+    if (VALID_SCAN_LEVELS.has(arg)) {
+      scanLevel = arg;
+      continue;
+    }
+    if (mode === 'quick' && VALID_MODES.has(arg)) {
+      mode = arg;
+    } else if (mode === 'quick') {
+      return { mode: null, error: `unknown mode: ${arg}. Valid modes: ${[...VALID_MODES].join(', ')}` };
+    } else {
+      return { mode: null, error: `unexpected extra argument: ${arg}` };
+    }
+  }
+
+  if (!VALID_MODES.has(mode)) {
+    return { mode: null, error: `unknown mode: ${mode}. Valid modes: ${[...VALID_MODES].join(', ')}` };
+  }
+
+  return { mode, resume, scanLevel, target };
+}
+
+function cmdDocumentProject({ kitRoot, projectRoot, args = [], opts = {} }) {
+  const log = opts.log || console.log;
+  const parsed = parseMode(args);
+
+  if (parsed.mode === null) {
+    log(parsed.error);
+    return { ok: false, error: parsed.error, exitCode: 1 };
+  }
+
+  if (parsed.mode === 'quick') {
+    const r = runQuick(projectRoot, { log });
+    return { ok: true, mode: 'quick', ...r };
+  }
+
+  if (parsed.mode === 'initial_scan') {
+    const r = runInitialScan(projectRoot, { scanLevel: parsed.scanLevel, log });
+    return { ok: true, mode: 'initial_scan', ...r };
+  }
+
+  if (parsed.mode === 'full_rescan') {
+    const r = runFullRescan(projectRoot, { scanLevel: parsed.scanLevel, log });
+    return { ok: true, mode: 'full_rescan', ...r };
+  }
+
+  if (parsed.mode === 'deep_dive') {
+    const r = runDeepDive(projectRoot, { target: parsed.target, log });
+    return r;
+  }
+
+  log(`document-project ${parsed.mode} not implemented`);
+  return { ok: false, error: 'not implemented', exitCode: 1 };
+}
+
+module.exports = { cmdDocumentProject, parseMode };
+

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/document-project/batch-scanner.js

@@ -0,0 +1,93 @@
+// Batch scanner for `wize-dev-kit document-project`.
+//
+// Walks a repo in subfolder-sized batches, skipping noise directories.
+// Returns summaries without loading entire trees into memory.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_IGNORE = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'coverage',
+  '.cache',
+  '.tmp',
+  '.wize',
+  '.claude',
+  '.cursor',
+  '.kimi',
+  '.opencode',
+  '.windsurf',
+  '.continue',
+  '.codex',
+  '.antigravity'
+]);
+
+const MAX_FILE_LOC = 5000;
+
+function shouldIgnore(name, customIgnore = []) {
+  if (DEFAULT_IGNORE.has(name)) return true;
+  for (const pattern of customIgnore) {
+    if (name === pattern || (pattern.startsWith('*') && name.endsWith(pattern.slice(1)))) return true;
+  }
+  return false;
+}
+
+function listSubfolders(rootDir, options = {}) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(rootDir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (shouldIgnore(e.name, options.ignore)) continue;
+    out.push(path.join(rootDir, e.name));
+  }
+  return out;
+}
+
+function scanFolder(folderPath, options = {}) {
+  const files = [];
+  let totalLoc = 0;
+  const stack = [folderPath];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!shouldIgnore(e.name, options.ignore)) stack.push(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (/\.(min\.js|map)$/.test(e.name)) continue;
+      const stat = fs.statSync(full);
+      const loc = stat.size; // proxy; exact line count is optional
+      const info = {
+        path: full,
+        relative: path.relative(folderPath, full),
+        size: stat.size,
+        loc: loc > MAX_FILE_LOC ? MAX_FILE_LOC : loc,
+        skipped: loc > MAX_FILE_LOC
+      };
+      files.push(info);
+      totalLoc += info.loc;
+    }
+  }
+  return { folder: folderPath, files, totalLoc, fileCount: files.length };
+}
+
+function batchScanner(rootDir, options = {}) {
+  const folders = options.folders || listSubfolders(rootDir, options);
+  const results = [];
+  for (const folder of folders) {
+    results.push(scanFolder(folder, options));
+  }
+  return results;
+}
+
+module.exports = { batchScanner, listSubfolders, scanFolder, shouldIgnore, MAX_FILE_LOC };

package/tools/installer/document-project/classify.js

@@ -0,0 +1,170 @@
+// Project-type classifier for `wize-dev-kit document-project`.
+//
+// Detects the project type(s) of a repo from file patterns, then decides
+// whether the repo is a monolith, multi-part, or monorepo.
+// No source files are read — this is pattern-only detection.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MULTI_PART_FOLDERS = ['client', 'server', 'api', 'web', 'app', 'frontend', 'backend', 'mobile', 'desktop'];
+
+function toBool(v) {
+  return String(v).toLowerCase() === 'true';
+}
+
+function splitPatterns(str) {
+  if (!str || str === 'N/A') return [];
+  return str.split(';').map(s => s.trim()).filter(Boolean);
+}
+
+function loadRequirements(csvPath) {
+  const content = fs.readFileSync(csvPath, 'utf-8');
+  const lines = content.split(/\r?\n/).filter(l => l.trim());
+  const header = lines[0].split(',').map(h => h.trim());
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(',').map(v => v.trim());
+    const row = {};
+    for (let j = 0; j < header.length; j++) {
+      const key = header[j];
+      const raw = values[j];
+      if (key.startsWith('requires_')) {
+        row[key] = toBool(raw);
+      } else {
+        row[key] = raw || '';
+      }
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+function globMatch(rootDir, pattern) {
+  // Very small pattern matcher: supports * wildcard and trailing / for dirs.
+  const isDirPattern = pattern.endsWith('/');
+  const base = isDirPattern ? pattern.slice(0, -1) : pattern;
+  const parts = base.split('/');
+  return walkMatch(rootDir, parts, 0, isDirPattern);
+}
+
+function walkMatch(dir, parts, depth, isDirPattern) {
+  if (depth >= parts.length) return true;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  const part = parts[depth];
+  const isLast = depth === parts.length - 1;
+  const regex = globToRegex(part);
+  for (const e of entries) {
+    if (!regex.test(e.name)) continue;
+    if (isLast) {
+      if (isDirPattern && e.isDirectory()) return true;
+      if (!isDirPattern && e.isFile()) return true;
+      if (!isDirPattern && e.isDirectory()) {
+        // pattern like vite.config.* can match a directory named vite.config.ts? no.
+        // But pattern may be a prefix; treat directory match as false for files.
+        return false;
+      }
+    } else if (e.isDirectory()) {
+      if (walkMatch(path.join(dir, e.name), parts, depth + 1, isDirPattern)) return true;
+    }
+  }
+  return false;
+}
+
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`);
+}
+
+function scorePart(rootDir, row, { prefer = [] } = {}) {
+  let score = 0;
+  const keyPatterns = splitPatterns(row.key_file_patterns);
+  const dirPatterns = splitPatterns(row.critical_directories);
+  for (const p of keyPatterns) {
+    if (globMatch(rootDir, p)) score += 2;
+  }
+  for (const p of dirPatterns) {
+    if (globMatch(rootDir, p)) score += 1;
+  }
+  if (prefer.includes(row.project_type_id)) score += 0.5;
+  return score;
+}
+
+function detectParts(rootDir) {
+  const parts = [];
+  const candidates = [];
+  let entries;
+  try { entries = fs.readdirSync(rootDir, { withFileTypes: true }); } catch { return parts; }
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!MULTI_PART_FOLDERS.includes(e.name.toLowerCase())) continue;
+    candidates.push(e.name);
+  }
+
+  if (candidates.length < 2) return parts;
+
+  const rows = loadRequirements(requirementsPath());
+  for (const partId of candidates) {
+    const partRoot = path.join(rootDir, partId);
+    const prefer = partId.toLowerCase() === 'server' || partId.toLowerCase() === 'backend' ? ['backend'] : [];
+    const scored = rows.map(r => ({ ...r, score: scorePart(partRoot, r, { prefer }) }));
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    if (best && best.score > 0) {
+      parts.push({ part_id: partId, project_type_id: best.project_type_id, root_path: partRoot });
+    }
+  }
+  return parts;
+}
+
+function isMultiPart(rootDir) {
+  return detectParts(rootDir).length >= 2;
+}
+
+function classifyProject(rootDir, options = {}) {
+  const csvPath = options.csvPath || requirementsPath();
+  const rows = loadRequirements(csvPath);
+  const parts = detectParts(rootDir);
+
+  if (parts.length >= 2) {
+    return { projectTypes: [...new Set(parts.map(p => p.project_type_id))], parts };
+  }
+
+  const scored = rows.map(r => ({ ...r, score: scorePart(rootDir, r, { prefer: options.prefer || [] }) }));
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  const tied = scored.filter(s => s.score === best.score).map(s => s.project_type_id);
+
+  if (!best || best.score === 0) {
+    return { projectTypes: [], parts: [] };
+  }
+
+  // Cli + library often appear together; prefer both when tied at the top.
+  const projectTypes = tied.includes('cli') && tied.includes('library')
+    ? ['cli', 'library']
+    : [best.project_type_id];
+
+  return {
+    projectTypes,
+    parts: [{ part_id: 'root', project_type_id: best.project_type_id, root_path: rootDir }]
+  };
+}
+
+function requirementsPath() {
+  // When running from the installed package, the CSV is next to this file under
+  // node_modules/wize-dev-kit/... When running from the source repo, resolve from
+  // the repo root via the known relative path.
+  const installed = path.resolve(__dirname, '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+  if (fs.existsSync(installed)) return installed;
+  // Fallback for source repo layout.
+  return path.resolve(__dirname, '..', '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+}
+
+module.exports = { classifyProject, loadRequirements, isMultiPart, scorePart, requirementsPath, globMatch };