wize-dev-kit 0.2.5 → 0.3.1

package/tools/installer/document-project/modes/quick.js

@@ -0,0 +1,211 @@
+// Quick baseline mode for `wize-dev-kit document-project`.
+//
+// Produces the 6 lightweight baseline files. Does not read source files.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BASELINE_FILES = {
+  'overview.md': overviewMarkdown,
+  'architecture-snapshot.md': architectureMarkdown,
+  'conventions.md': conventionsMarkdown,
+  'dependencies.md': dependenciesMarkdown,
+  'risk-spots.md': riskMarkdown,
+  'open-questions.md': questionsMarkdown
+};
+
+function now() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readPackage(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function countLines(root) {
+  let total = 0;
+  const dirs = ['src', 'tools', 'adapters', 'schemas', 'test'];
+  for (const dir of dirs) {
+    const full = path.join(root, dir);
+    if (!fs.existsSync(full)) continue;
+    total += walkLines(full);
+  }
+  return total;
+}
+
+function walkLines(dir) {
+  let total = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) total += walkLines(full);
+    else if (e.isFile() && /\.(js|md|yaml|json)$/.test(e.name)) {
+      const content = fs.readFileSync(full, 'utf-8');
+      total += content.split('\n').length;
+    }
+  }
+  return total;
+}
+
+function recentCommitCount(root) {
+  // Avoid shelling out; return 0 if not a git repo or git unavailable.
+  // Caller can overlay a real count from CLI.
+  return 0;
+}
+
+function overviewMarkdown(root, pkg) {
+  return `---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Overview
+
+**Project:** ${pkg.name || path.basename(root)}
+**What it is:** ${pkg.description || 'Project documented by Wize Dev Kit.'}
+**Current version:** ${pkg.version || 'unknown'}
+
+## Size
+
+- Source lines of code: ~${countLines(root)} LOC.
+- Runtime dependencies: ${Object.keys(pkg.dependencies || {}).length}.
+- Dev dependencies: ${Object.keys(pkg.devDependencies || {}).length}.
+
+## What it ships
+
+- See architecture-snapshot.md for components and entry points.
+- See conventions.md for coding patterns.
+- See dependencies.md for runtime and dev dependency roles.
+`;
+}
+
+function architectureMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Tony Stark
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Architecture Snapshot
+
+## Entry points
+
+- Documented after a deeper scan (initial_scan mode).
+
+## Components
+
+- Run \`wize-dev-kit document-project initial_scan deep\` for component-level detail.
+
+## Integration surface
+
+- See dependencies.md for external integrations.
+`;
+}
+
+function conventionsMarkdown() {
+  return `---
+status: baseline
+owner: Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+sampled: "pending deeper scan"
+---
+
+# Conventions (observed, not prescribed)
+
+## Quick notes
+
+- Run \`wize-dev-kit document-project initial_scan deep\` to sample files and fill this doc.
+`;
+}
+
+function dependenciesMarkdown(root, pkg) {
+  const runtime = Object.entries(pkg.dependencies || {})
+    .map(([name, version]) => `| ${name} | ${version} | | |`).join('\n');
+  const dev = Object.entries(pkg.devDependencies || {})
+    .map(([name, version]) => `| ${name} | ${version} | | |`).join('\n');
+
+  return `---
+status: baseline
+owner: Pepper Potts
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Dependencies
+
+## Runtime
+
+| Name | Version | Role in this repo | Load-bearing? |
+|---|---|---|---|
+${runtime || '| — | — | — | — |'}
+
+## Dev / bundled
+
+| Name | Version | Role in this repo | Load-bearing? |
+|---|---|---|---|
+${dev || '| — | — | — | — |'}
+`;
+}
+
+function riskMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Tony Stark
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Risk Spots
+
+| Area | Symptom | Likely cause | Confidence |
+|---|---|---|---|
+| | | | |
+
+Run \`wize-dev-kit document-project initial_scan deep\` to populate risk spots.
+`;
+}
+
+function questionsMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Open Questions
+
+| Question | Why it matters | Owner to ask |
+|---|---|---|
+| | | |
+`;
+}
+
+function runQuick(projectRoot, opts = {}) {
+  const pkg = readPackage(projectRoot);
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const written = [];
+  for (const [name, factory] of Object.entries(BASELINE_FILES)) {
+    const file = path.join(dir, name);
+    const content = factory(projectRoot, pkg);
+    fs.writeFileSync(file, content, 'utf-8');
+    written.push(name);
+  }
+
+  if (opts.log) opts.log(`Quick baseline written to ${dir}`);
+  return { changed: true, mode: 'quick', written };
+}
+
+module.exports = { runQuick, BASELINE_FILES, countLines };

package/tools/installer/document-project/render-index.js

@@ -0,0 +1,101 @@
+// Master index renderer for `wize-dev-kit document-project`.
+//
+// Generates `.wize/knowledge/document-project/index.md` linking all docs.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function link(name, file) {
+  return `- [${name}](./${file})`;
+}
+
+function linkWithMarker(name, file, exists) {
+  const base = link(name, file);
+  return exists ? base : `${base} _(To be generated)_`;
+}
+
+function renderIndex(projectRoot, { projectTypes = [], parts = [], generated = [], existing = [], deepDiveFiles = [] } = {}) {
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const generatedSet = new Set(generated.map(g => path.basename(g)));
+  const existingSet = new Set(existing.map(e => path.basename(e)));
+  const has = name => generatedSet.has(name) || existingSet.has(name);
+
+  const isMultiPart = parts.length >= 2;
+  const primaryType = projectTypes[0] || 'unknown';
+
+  const lines = [
+    '---',
+    'status: baseline',
+    'owner: Pepper Potts + Peggy Carter',
+    `created: ${new Date().toISOString().slice(0, 10)}`,
+    `last_refreshed: ${new Date().toISOString().slice(0, 10)}`,
+    '---',
+    '',
+    '# Project Documentation Index',
+    '',
+    `**Type:** ${isMultiPart ? 'multi-part' : primaryType}`,
+    `**Primary project type(s):** ${projectTypes.join(', ') || 'unknown'}`,
+    '',
+    '## Generated Documentation',
+    '',
+    link('Project Overview', 'project-overview.md'),
+    linkWithMarker('Source Tree Analysis', 'source-tree-analysis.md', has('source-tree-analysis.md')),
+  ];
+
+  if (isMultiPart) {
+    for (const part of parts) {
+      const suffix = part.part_id === 'root' ? '' : `-${part.part_id}`;
+      lines.push(linkWithMarker(`Architecture — ${part.part_id || 'root'}`, `architecture${suffix}.md`, has(`architecture${suffix}.md`)));
+      lines.push(linkWithMarker(`Development Guide — ${part.part_id || 'root'}`, `development-guide${suffix}.md`, has(`development-guide${suffix}.md`)));
+      lines.push(linkWithMarker(`Component Inventory — ${part.part_id || 'root'}`, `component-inventory${suffix}.md`, has(`component-inventory${suffix}.md`)));
+      lines.push(linkWithMarker(`API Contracts — ${part.part_id || 'root'}`, `api-contracts${suffix}.md`, has(`api-contracts${suffix}.md`)));
+      lines.push(linkWithMarker(`Data Models — ${part.part_id || 'root'}`, `data-models${suffix}.md`, has(`data-models${suffix}.md`)));
+    }
+    lines.push(linkWithMarker('Integration Architecture', 'integration-architecture.md', has('integration-architecture.md')));
+  } else {
+    lines.push(linkWithMarker('Architecture', 'architecture.md', has('architecture.md')));
+    lines.push(linkWithMarker('Development Guide', 'development-guide.md', has('development-guide.md')));
+    lines.push(linkWithMarker('Component Inventory', 'component-inventory.md', has('component-inventory.md')));
+    lines.push(linkWithMarker('API Contracts', 'api-contracts.md', has('api-contracts.md')));
+    lines.push(linkWithMarker('Data Models', 'data-models.md', has('data-models.md')));
+  }
+
+  lines.push(linkWithMarker('Deployment Guide', 'deployment-guide.md', has('deployment-guide.md')));
+  lines.push(linkWithMarker('Contribution Guide', 'contribution-guide.md', has('contribution-guide.md')));
+  if (deepDiveFiles.length) {
+    lines.push('', '## Deep-Dive Docs', '');
+    for (const f of deepDiveFiles) {
+      lines.push(link(f.replace(/^deep-dive-/, '').replace(/\.md$/, ''), f));
+    }
+  } else {
+    lines.push(linkWithMarker('Deep-Dive Docs', 'deep-dive/', false)); // directory marker
+  }
+
+  if (existing.length) {
+    lines.push('', '## Existing Documentation', '');
+    for (const doc of existing) {
+      const rel = path.relative(dir, doc);
+      lines.push(`- [${path.basename(doc)}](./${rel})`);
+    }
+  }
+
+  lines.push('', '## Brownfield Baseline', '');
+  lines.push(link('Overview', 'overview.md'));
+  lines.push(link('Architecture Snapshot', 'architecture-snapshot.md'));
+  lines.push(link('Conventions', 'conventions.md'));
+  lines.push(link('Dependencies', 'dependencies.md'));
+  lines.push(link('Risk Spots', 'risk-spots.md'));
+  lines.push(link('Open Questions', 'open-questions.md'));
+
+  lines.push('', '---', '', '_Generated by `wize-document-project`._', '');
+
+  const file = path.join(dir, 'index.md');
+  fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  return { changed: true, written: ['index.md'] };
+}
+
+module.exports = { renderIndex, link, linkWithMarker };

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

@@ -0,0 +1,110 @@
+// State file management for `wize-dev-kit document-project`.
+//
+// Tracks scan progress so long-running deep/exhaustive scans can resume.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const WORKFLOW_VERSION = '0.3.1';
+const STATE_FILE = 'project-scan-report.json';
+const ARCHIVE_DIR = '_archive';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.wize', 'knowledge', 'document-project', STATE_FILE);
+}
+
+function archivePath(projectRoot, timestamp) {
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project', ARCHIVE_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const safe = timestamp.replace(/[:.]/g, '-');
+  return path.join(dir, `project-scan-report-${safe}.json`);
+}
+
+function initState(projectRoot, mode, scanLevel) {
+  const state = {
+    workflow_version: WORKFLOW_VERSION,
+    timestamps: { started: nowIso(), last_updated: nowIso() },
+    mode,
+    scan_level: scanLevel,
+    project_root: projectRoot,
+    project_knowledge: path.join(projectRoot, '.wize', 'knowledge', 'document-project'),
+    completed_steps: [],
+    current_step: 'step_1',
+    findings: {},
+    outputs_generated: [STATE_FILE],
+    resume_instructions: `Starting ${mode} (${scanLevel}) from step_1`
+  };
+  writeState(projectRoot, state);
+  return state;
+}
+
+function loadState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const content = fs.readFileSync(p, 'utf-8');
+    const state = JSON.parse(content);
+    if (!state.workflow_version || !state.timestamps || !state.mode || !state.scan_level) {
+      return null;
+    }
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(projectRoot, state) {
+  const p = statePath(projectRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  state.timestamps.last_updated = nowIso();
+  fs.writeFileSync(p, JSON.stringify(state, null, 2), 'utf-8');
+}
+
+function updateState(projectRoot, patch) {
+  const state = loadState(projectRoot) || initState(projectRoot, 'quick', 'quick');
+  for (const key of Object.keys(patch)) {
+    const val = patch[key];
+    if (Array.isArray(val) && Array.isArray(state[key])) {
+      state[key].push(...val);
+    } else if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+      state[key] = { ...(state[key] || {}), ...val };
+    } else {
+      state[key] = val;
+    }
+  }
+  writeState(projectRoot, state);
+  return state;
+}
+
+function archiveOldState(projectRoot) {
+  const p = statePath(projectRoot);
+  if (!fs.existsSync(p)) return false;
+  const content = fs.readFileSync(p, 'utf-8');
+  const archived = archivePath(projectRoot, nowIso());
+  fs.writeFileSync(archived, content, 'utf-8');
+  fs.rmSync(p);
+  return true;
+}
+
+function stateAgeDays(state) {
+  if (!state || !state.timestamps || !state.timestamps.last_updated) return null;
+  const then = Date.parse(state.timestamps.last_updated);
+  if (Number.isNaN(then)) return null;
+  return Math.floor((Date.now() - then) / (24 * 3600 * 1000));
+}
+
+module.exports = {
+  statePath,
+  initState,
+  loadState,
+  updateState,
+  archiveOldState,
+  stateAgeDays,
+  WORKFLOW_VERSION
+};

package/tools/installer/wize-cli.js

@@ -16,10 +16,11 @@ const readline = require('node:readline');
 const prompts = require('prompts');
 const { applyGitignore, generateUserToml } = require('./setup-helpers.js');
 const { cmdUpdate } = require('./commands/update.js');
-const { detectHarnessCli, runHeadlessBaseline, manualInstructions, defaultPrompt } = require('./baseline.js');
 const { printUpdateHintIfAny } = require('./version-check.js');
 const { cmdSync: cmdSyncReal } = require('./commands/sync.js');
 const { cmdAgentList, cmdAgentCreate, cmdAgentEdit } = require('./commands/agent.js');
+const { cmdDoctor } = require('./commands/doctor.js');
+const { cmdDocumentProject } = require('./commands/document-project.js');
 
 const INTERACTIVE = process.stdout.isTTY && process.stdin.isTTY;
 
@@ -72,6 +73,8 @@ Commands:
   agent <create|list>     Manage agents (built-in or custom).
   workflow <create|list>  Manage workflows.
   validate                Run schema + lint + dry-run validators.
+  doctor                  Diagnose the kit + project state, suggest fixes.
+  document-project        Document the current repo (quick | initial_scan | full_rescan | deep_dive).
   help                    Show this message.
 
 Documentation:
@@ -135,6 +138,23 @@ async function confirm(question, defaultYes = true) {
   return ans.startsWith('y');
 }
 
+async function select(label, choices, defaultValue) {
+  if (INTERACTIVE) {
+    const initial = choices.findIndex(c => c.value === defaultValue);
+    const { picked } = await prompts({
+      type: 'select',
+      name: 'picked',
+      message: label,
+      choices: choices.map(c => ({ title: c.title, value: c.value, description: c.description })),
+      initial: initial === -1 ? 0 : initial
+    });
+    if (picked === undefined) process.exit(130);
+    return picked;
+  }
+  // Non-TTY fallback: return default.
+  return defaultValue;
+}
+
 async function selectLanguage(label, defaultCode = 'en') {
   if (INTERACTIVE) {
     const choices = LANGUAGES.map(l => ({
@@ -417,35 +437,26 @@ async function cmdInstall(args) {
   }
 
   if (detection.brownfield) {
-    const baseline = await confirm('\nRun `wize-document-project` to baseline the existing repo now?', true);
-    if (baseline) {
-      const preferIde = targets.map(t => t.code);
-      const harnesses = detectHarnessCli({ preferIde });
-      if (process.env.WIZE_SKIP_BASELINE === '1') {
-        console.log('\nWIZE_SKIP_BASELINE=1 — not running the baseline.');
-        console.log(manualInstructions(harnesses[0]));
-      } else if (harnesses.length === 0) {
-        console.log(manualInstructions(null));
+    if (process.env.WIZE_SKIP_BASELINE === '1') {
+      console.log('\nWIZE_SKIP_BASELINE=1 — not running the baseline.');
+    } else if (!INTERACTIVE) {
+      console.log('\nNon-interactive install detected; running quick baseline...');
+      cmdDocumentProject({ kitRoot: KIT_ROOT, projectRoot: cwd, args: ['quick'], opts: { log: console.log } });
+    } else {
+      const mode = await select(
+        'Document the existing repo now?',
+        [
+          { title: 'Quick baseline (default, 6 files)', value: 'quick' },
+          { title: 'Initial scan (pattern + conditional docs)', value: 'initial_scan' },
+          { title: 'Full rescan (archive old state, re-run)', value: 'full_rescan' },
+          { title: 'Skip documentation for now', value: 'skip' }
+        ],
+        'quick'
+      );
+      if (mode !== 'skip') {
+        cmdDocumentProject({ kitRoot: KIT_ROOT, projectRoot: cwd, args: [mode], opts: { log: console.log } });
       } else {
-        const chosen = harnesses[0];
-        console.log(`\nDetected harness: ${chosen.binary} (${chosen.path}).`);
-        const confirmRun = await confirm(
-          `Run /wize-document-project via ${chosen.binary} now?`,
-          true
-        );
-        if (confirmRun) {
-          const r = runHeadlessBaseline({
-            harness: chosen,
-            projectRoot: cwd,
-            prompt: defaultPrompt()
-          });
-          if (!r.ok && !r.skipped) {
-            console.log(`\n${chosen.binary} exited with code ${r.exitCode}. You can re-run later with:`);
-            console.log(manualInstructions(chosen));
-          }
-        } else {
-          console.log(manualInstructions(chosen));
-        }
+        console.log('\nSkipped documentation. Run `wize-dev-kit document-project` later.');
       }
     }
   }
@@ -540,7 +551,7 @@ function cmdValidate() {
 // for `update` (already updating), `install` (already setting up), `uninstall`
 // (already leaving), `validate` (developer-tool), and `version` (the user is
 // already asking about versions).
-const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help']);
+const HINT_COMMANDS = new Set(['list', 'sync', 'agent', 'workflow', 'help', 'doctor', 'document-project']);
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
@@ -561,6 +572,14 @@ async function main() {
     case 'agent':     return cmdAgent(rest);
     case 'workflow':  return cmdWorkflow(rest);
     case 'validate':  return cmdValidate();
+    case 'doctor':    return cmdDoctor({ kitRoot: KIT_ROOT, projectRoot: process.cwd() });
+    case 'document-project':
+      return cmdDocumentProject({
+        kitRoot: KIT_ROOT,
+        projectRoot: process.cwd(),
+        args: rest,
+        opts: { log: console.log }
+      });
     case 'version':
     case '--version':
     case '-v':