lean-spec 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -7,6 +7,84 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.3] - 2025-11-10
+
+### Added
+
+**New Commands:**
+- `lean-spec migrate` - Migrate from existing tools (ADRs, RFCs, design docs) with AI assistance
+- `lean-spec archive` - Archive completed specs with automatic frontmatter updates
+- `lean-spec backfill` - Backfill timestamps and metadata from git history
+
+**Documentation Enhancements:**
+- Complete documentation site overhaul with improved information architecture
+- AI-assisted spec writing guide with philosophy and best practices
+- Migration guides for teams coming from ADRs, RFCs, and other tools
+- First principles documentation (Context Economy, Signal-to-Noise, etc.)
+- Comprehensive core concepts guide with practical examples
+
+**Quality & Validation:**
+- Enhanced `lean-spec validate` with complexity analysis
+- Spec relationship clarity with bidirectional `related` and directional `depends_on`
+- Improved frontmatter handling and metadata management
+
+### Changed
+
+**User Experience:**
+- Unified dashboard combining board view with project health metrics
+- Pattern-aware list grouping with visual icons and better organization
+- Improved init flow with pattern selection
+- Enhanced stats dashboard with actionable insights
+- Better MCP error handling and stability
+
+**Documentation:**
+- Restructured docs with clearer navigation and information flow
+- Updated README with AI-first positioning
+- Comprehensive examples and use cases
+- Improved CLI command documentation
+
+### Fixed
+- MCP server stability issues with frontmatter parsing
+- TypeScript type errors in migrate command
+- Documentation accuracy issues across all guides
+- Frontmatter handling edge cases
+
+### Philosophy
+
+This UAT release operationalizes LeanSpec's five first principles:
+1. **Context Economy** - Specs fit in working memory (<400 lines)
+2. **Signal-to-Noise** - Every word informs decisions
+3. **Intent Over Implementation** - Capture why, not just how
+4. **Bridge the Gap** - Both human and AI understand
+5. **Progressive Disclosure** - Add complexity only when needed
+
+**Notable Completed Specs in this Release:**
+- 063: Migration from existing tools
+- 062: Documentation information architecture v2
+- 061: AI-assisted spec writing
+- 060: Core concepts coherence
+- 058: Docs overview polish
+- 057: Docs validation comprehensive
+- 056: Docs site accuracy audit
+- 055: README redesign (AI-first)
+- 054: Validate output (lint-style)
+- 052: Branding assets
+- 051: First principles documentation
+- 049: LeanSpec first principles foundation
+- 048: Spec complexity analysis
+- 047: Git backfill timestamps
+- 046: Stats dashboard refactor
+- 045: Unified dashboard
+- 044: Spec relationships clarity
+
+**Testing:**
+- All 261 tests passing (100% pass rate)
+- Zero critical bugs
+- MCP server stable
+- Documentation site builds cleanly
+
+**Ready for:** UAT testing before official 0.2.0 launch
+
 ## [0.1.2] - 2025-11-10
 
 ### Changed
@@ -127,6 +205,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Gray-matter for frontmatter parsing
 - Dayjs for date handling
 
+[0.1.3]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.3
 [0.1.2]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.2
 [0.1.1]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.1
 [0.1.0]: https://github.com/codervisor/lean-spec/releases/tag/v0.1.0

package/dist/{chunk-OXTU3PN4.js → chunk-S6TGAL75.js}

@@ -141,13 +141,13 @@ async function loadSubFiles(specDir, options = {}) {
       if (entry.name === "README.md") continue;
       if (entry.isDirectory()) continue;
       const filePath = path2.join(specDir, entry.name);
-      const stat4 = await fs2.stat(filePath);
+      const stat5 = await fs2.stat(filePath);
       const ext = path2.extname(entry.name).toLowerCase();
       const isDocument = ext === ".md";
       const subFile = {
         name: entry.name,
         path: filePath,
-        size: stat4.size,
+        size: stat5.size,
         type: isDocument ? "document" : "asset"
       };
       if (isDocument && options.includeContent) {
@@ -734,7 +734,7 @@ ${options.description}`
       );
     }
   } catch (error) {
-    throw new Error(`Template not found: ${templatePath}. Run: lspec init`);
+    throw new Error(`Template not found: ${templatePath}. Run: lean-spec init`);
   }
   await fs5.writeFile(specFile, content, "utf-8");
   console.log(chalk4.green(`\u2713 Created: ${sanitizeUserInput(specDir)}/`));
@@ -755,6 +755,10 @@ async function archiveSpec(specPath) {
   if (!resolvedPath) {
     throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
   }
+  const specFile = await getSpecFile(resolvedPath, config.structure.defaultFile);
+  if (specFile) {
+    await updateFrontmatter(specFile, { status: "archived" });
+  }
   const archiveDir = path7.join(specsDir, "archived");
   await fs6.mkdir(archiveDir, { recursive: true });
   const specName = path7.basename(resolvedPath);
@@ -870,7 +874,7 @@ async function listSpecs(options = {}) {
     await fs7.access(specsDir);
   } catch {
     console.log("");
-    console.log("No specs directory found. Initialize with: lspec init");
+    console.log("No specs directory found. Initialize with: lean-spec init");
     console.log("");
     return;
   }
@@ -1359,7 +1363,7 @@ async function listTemplates(cwd = process.cwd()) {
     await fs8.access(templatesDir);
   } catch {
     console.log(chalk9.yellow("No templates directory found."));
-    console.log(chalk9.gray("Run: lspec init"));
+    console.log(chalk9.gray("Run: lean-spec init"));
     console.log("");
     return;
   }
@@ -1382,12 +1386,12 @@ async function listTemplates(cwd = process.cwd()) {
   console.log(chalk9.cyan("Available files:"));
   for (const file of templateFiles) {
     const filePath = path11.join(templatesDir, file);
-    const stat4 = await fs8.stat(filePath);
-    const sizeKB = (stat4.size / 1024).toFixed(1);
+    const stat5 = await fs8.stat(filePath);
+    const sizeKB = (stat5.size / 1024).toFixed(1);
     console.log(`  ${file} (${sizeKB} KB)`);
   }
   console.log("");
-  console.log(chalk9.gray("Use templates with: lspec create <name> --template=<template-name>"));
+  console.log(chalk9.gray("Use templates with: lean-spec create <name> --template=<template-name>"));
   console.log("");
 }
 async function showTemplate(templateName, cwd = process.cwd()) {
@@ -1423,7 +1427,7 @@ async function addTemplate(name, file, cwd = process.cwd()) {
     console.error(chalk9.red(`Template file not found: ${file}`));
     console.error(chalk9.gray(`Expected at: ${templatePath}`));
     console.error(
-      chalk9.yellow("Create the file first or use: lspec templates copy <source> <target>")
+      chalk9.yellow("Create the file first or use: lean-spec templates copy <source> <target>")
     );
     process.exit(1);
   }
@@ -1436,7 +1440,7 @@ async function addTemplate(name, file, cwd = process.cwd()) {
   config.templates[name] = file;
   await saveConfig(config, cwd);
   console.log(chalk9.green(`\u2713 Added template: ${name} \u2192 ${file}`));
-  console.log(chalk9.gray(`  Use with: lspec create <spec-name> --template=${name}`));
+  console.log(chalk9.gray(`  Use with: lean-spec create <spec-name> --template=${name}`));
 }
 async function removeTemplate(name, cwd = process.cwd()) {
   const config = await loadConfig(cwd);
@@ -1484,7 +1488,7 @@ async function copyTemplate(source, target, cwd = process.cwd()) {
   await saveConfig(config, cwd);
   console.log(chalk9.green(`\u2713 Registered template: ${templateName}`));
   console.log(chalk9.gray(`  Edit: ${targetPath}`));
-  console.log(chalk9.gray(`  Use with: lspec create <spec-name> --template=${templateName}`));
+  console.log(chalk9.gray(`  Use with: lean-spec create <spec-name> --template=${templateName}`));
 }
 
 // src/commands/init.ts
@@ -1820,7 +1824,7 @@ async function initProject() {
   console.log("Next steps:");
   console.log(chalk11.gray("  - Review and customize AGENTS.md"));
   console.log(chalk11.gray("  - Check out example spec in specs/"));
-  console.log(chalk11.gray("  - Create your first spec: lspec create my-feature"));
+  console.log(chalk11.gray("  - Create your first spec: lean-spec create my-feature"));
   console.log("");
 }
 
@@ -2786,6 +2790,220 @@ async function validateCommand(options = {}) {
   return !hasErrors;
 }
 
+// src/commands/migrate.ts
+import * as fs13 from "fs/promises";
+import * as path17 from "path";
+async function migrateCommand(inputPath, options = {}) {
+  const config = await loadConfig();
+  try {
+    const stats = await fs13.stat(inputPath);
+    if (!stats.isDirectory()) {
+      console.error("\x1B[31m\u274C Error:\x1B[0m Input path must be a directory");
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(`\x1B[31m\u274C Error:\x1B[0m Path not found: ${inputPath}`);
+    process.exit(1);
+  }
+  console.log(`\x1B[36mScanning:\x1B[0m ${inputPath}
+`);
+  const documents = await scanDocuments(inputPath);
+  if (documents.length === 0) {
+    console.error(`\x1B[31m\u274C Error:\x1B[0m No documents found in ${inputPath}`);
+    console.error("   Check path and try again");
+    process.exit(1);
+  }
+  console.log(`\x1B[32m\u2713\x1B[0m Found ${documents.length} document${documents.length === 1 ? "" : "s"}
+`);
+  if (options.aiProvider) {
+    await migrateWithAI(inputPath, documents, options);
+  } else {
+    await outputManualInstructions(inputPath, documents, config);
+  }
+}
+async function scanDocuments(dirPath) {
+  const documents = [];
+  async function scanRecursive(currentPath) {
+    const entries = await fs13.readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path17.join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith(".") && entry.name !== "node_modules") {
+          await scanRecursive(fullPath);
+        }
+      } else if (entry.isFile()) {
+        if (entry.name.endsWith(".md") || entry.name.endsWith(".markdown")) {
+          const stats = await fs13.stat(fullPath);
+          documents.push({
+            path: fullPath,
+            name: entry.name,
+            size: stats.size
+          });
+        }
+      }
+    }
+  }
+  await scanRecursive(dirPath);
+  return documents;
+}
+async function outputManualInstructions(inputPath, documents, config) {
+  const specsDir = config.specsDir || "specs";
+  console.log("\u2550".repeat(70));
+  console.log("\x1B[1m\x1B[36m\u{1F4CB} LeanSpec Migration Instructions\x1B[0m");
+  console.log("\u2550".repeat(70));
+  console.log();
+  console.log("\x1B[1mSource Location:\x1B[0m");
+  console.log(`  ${inputPath} (${documents.length} documents found)`);
+  console.log();
+  console.log("\x1B[1mMigration Prompt:\x1B[0m");
+  console.log("  Copy this prompt to your AI assistant (Copilot, Claude, ChatGPT, etc.):");
+  console.log();
+  console.log("\u2500".repeat(70));
+  console.log();
+  console.log("You are helping migrate specification documents to LeanSpec format.");
+  console.log();
+  console.log(`\x1B[1mSource:\x1B[0m ${inputPath}`);
+  console.log();
+  console.log("\x1B[1mYour Task:\x1B[0m");
+  console.log("1. Analyze the source documents to understand their format and structure");
+  console.log("2. For each document, extract:");
+  console.log("   - Title/name");
+  console.log("   - Status (map to: planned, in-progress, complete, archived)");
+  console.log("   - Creation date");
+  console.log("   - Priority (if present)");
+  console.log("   - Main content sections");
+  console.log("   - Relationships to other documents");
+  console.log();
+  console.log("3. Migrate each document by running these commands:");
+  console.log();
+  console.log("   # Create spec");
+  console.log("   lean-spec create <name>");
+  console.log();
+  console.log("   # Set metadata (NEVER edit frontmatter manually)");
+  console.log("   lean-spec update <name> --status <status>");
+  console.log("   lean-spec update <name> --priority <priority>");
+  console.log("   lean-spec update <name> --tags <tag1,tag2>");
+  console.log();
+  console.log("   # Edit content with your preferred tool");
+  console.log("   # Map original sections to LeanSpec structure:");
+  console.log("   # - Overview: Problem statement and context");
+  console.log("   # - Design: Technical approach and decisions");
+  console.log("   # - Plan: Implementation steps (if applicable)");
+  console.log("   # - Test: Validation criteria (if applicable)");
+  console.log("   # - Notes: Additional context, trade-offs, alternatives");
+  console.log();
+  console.log("4. After migration, run:");
+  console.log();
+  console.log("   lean-spec validate  # Check for issues");
+  console.log("   lean-spec board     # Verify migration");
+  console.log();
+  console.log("\x1B[1mImportant Rules:\x1B[0m");
+  console.log("- Preserve decision rationale and context");
+  console.log("- Map status appropriately to LeanSpec states");
+  console.log("- Link related specs using `related` field (manual frontmatter edit)");
+  console.log("- Follow LeanSpec first principles: clarity over completeness");
+  console.log("- Keep specs under 400 lines (split if needed)");
+  console.log();
+  console.log("\u2500".repeat(70));
+  console.log();
+  console.log("\x1B[36m\u2139\x1B[0m  \x1B[1mTip:\x1B[0m For AI-assisted migration, use:");
+  console.log("   \x1B[90mlean-spec migrate <path> --with copilot\x1B[0m");
+  console.log();
+}
+async function migrateWithAI(inputPath, documents, options) {
+  const provider = options.aiProvider;
+  console.log(`\x1B[36m\u{1F916} AI-Assisted Migration:\x1B[0m ${provider}
+`);
+  const tool = await verifyAITool(provider);
+  if (!tool.installed) {
+    console.error(`\x1B[31m\u274C ${tool.name} CLI not found\x1B[0m`);
+    console.error(`   Install: ${tool.installCmd}`);
+    console.error("   Or run without --with flag for manual instructions");
+    process.exit(1);
+  }
+  if (!tool.compatible) {
+    console.error(`\x1B[31m\u274C ${tool.name} version ${tool.version} too old\x1B[0m`);
+    console.error(`   Required: >=${tool.minVersion}`);
+    console.error(`   Update: ${tool.updateCmd}`);
+    process.exit(1);
+  }
+  console.log(`\x1B[32m\u2713\x1B[0m ${tool.name} CLI verified (v${tool.version})
+`);
+  console.log("\x1B[33m\u26A0 AI-assisted migration is not yet fully implemented\x1B[0m");
+  console.log("  This feature will automatically execute migration via AI CLI tools.");
+  console.log();
+  console.log("  For now, use manual mode (without --with flag) to get migration instructions.");
+  console.log();
+}
+async function verifyAITool(provider) {
+  const tools = {
+    copilot: {
+      name: "GitHub Copilot CLI",
+      cliCommand: "github-copilot-cli",
+      installCmd: "npm install -g @githubnext/github-copilot-cli",
+      updateCmd: "npm update -g @githubnext/github-copilot-cli",
+      versionCmd: "github-copilot-cli --version",
+      minVersion: "0.1.0"
+    },
+    claude: {
+      name: "Claude CLI",
+      cliCommand: "claude",
+      installCmd: "pip install claude-cli",
+      updateCmd: "pip install --upgrade claude-cli",
+      versionCmd: "claude --version",
+      minVersion: "1.0.0"
+    },
+    gemini: {
+      name: "Gemini CLI",
+      cliCommand: "gemini-cli",
+      installCmd: "npm install -g @google/gemini-cli",
+      updateCmd: "npm update -g @google/gemini-cli",
+      versionCmd: "gemini-cli --version",
+      minVersion: "1.0.0"
+    }
+  };
+  const toolDef = tools[provider];
+  let installed = false;
+  let version;
+  try {
+    const { execSync: execSync3 } = await import("child_process");
+    execSync3(`which ${toolDef.cliCommand}`, { stdio: "ignore" });
+    installed = true;
+    try {
+      const versionOutput = execSync3(toolDef.versionCmd, {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      const versionMatch = versionOutput.match(/(\d+\.\d+\.\d+)/);
+      if (versionMatch) {
+        version = versionMatch[1];
+      }
+    } catch {
+      version = "unknown";
+    }
+  } catch {
+    installed = false;
+  }
+  const compatible = installed && (version === "unknown" || version !== void 0 && satisfiesVersion(version, toolDef.minVersion));
+  return {
+    ...toolDef,
+    installed,
+    version,
+    compatible
+  };
+}
+function satisfiesVersion(version, minVersion) {
+  const vParts = version.split(".").map(Number);
+  const minParts = minVersion.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const v = vParts[i] || 0;
+    const min = minParts[i] || 0;
+    if (v > min) return true;
+    if (v < min) return false;
+  }
+  return true;
+}
+
 // src/commands/board.ts
 import chalk15 from "chalk";
 
@@ -3374,9 +3592,9 @@ async function statsCommand(options) {
     console.log(`  Throughput       ${chalk16.cyan((velocityMetrics.throughput.perWeek / 7 * 7).toFixed(1))}/week ${throughputTrend}`);
     console.log(`  WIP              ${chalk16.yellow(velocityMetrics.wip.current)} specs`);
     console.log("");
-    console.log(chalk16.dim("\u{1F4A1} Use `lspec stats --full` for detailed analytics"));
-    console.log(chalk16.dim("   Use `lspec stats --velocity` for velocity breakdown"));
-    console.log(chalk16.dim("   Use `lspec stats --timeline` for activity timeline"));
+    console.log(chalk16.dim("\u{1F4A1} Use `lean-spec stats --full` for detailed analytics"));
+    console.log(chalk16.dim("   Use `lean-spec stats --velocity` for velocity breakdown"));
+    console.log(chalk16.dim("   Use `lean-spec stats --timeline` for activity timeline"));
     console.log("");
     return;
   }
@@ -3723,12 +3941,12 @@ function escapeRegex(str) {
 
 // src/commands/deps.ts
 import chalk18 from "chalk";
-import * as path17 from "path";
+import * as path18 from "path";
 async function depsCommand(specPath, options) {
   await autoCheckIfEnabled();
   const config = await loadConfig();
   const cwd = process.cwd();
-  const specsDir = path17.join(cwd, config.specsDir);
+  const specsDir = path18.join(cwd, config.specsDir);
   const resolvedPath = await resolveSpecPath(specPath, cwd, specsDir);
   if (!resolvedPath) {
     throw new Error(`Spec not found: ${sanitizeUserInput(specPath)}`);
@@ -3804,8 +4022,8 @@ function findDependencies(spec, specMap) {
     if (dep) {
       deps.push(dep);
     } else {
-      for (const [path19, s] of specMap.entries()) {
-        if (path19.includes(depPath)) {
+      for (const [path20, s] of specMap.entries()) {
+        if (path20.includes(depPath)) {
           deps.push(s);
           break;
         }
@@ -3837,8 +4055,8 @@ function findRelated(spec, specMap) {
     if (rel) {
       related.push(rel);
     } else {
-      for (const [path19, s] of specMap.entries()) {
-        if (path19.includes(relPath)) {
+      for (const [path20, s] of specMap.entries()) {
+        if (path20.includes(relPath)) {
           related.push(s);
           break;
         }
@@ -4243,8 +4461,8 @@ function renderTimelineBar(spec, startDate, endDate, weeks, today) {
 }
 
 // src/commands/viewer.ts
-import * as fs13 from "fs/promises";
-import * as path18 from "path";
+import * as fs14 from "fs/promises";
+import * as path19 from "path";
 import chalk21 from "chalk";
 import { marked } from "marked";
 import { markedTerminal } from "marked-terminal";
@@ -4252,7 +4470,7 @@ import { spawn } from "child_process";
 marked.use(markedTerminal());
 async function readSpecContent(specPath, cwd = process.cwd()) {
   const config = await loadConfig(cwd);
-  const specsDir = path18.join(cwd, config.specsDir);
+  const specsDir = path19.join(cwd, config.specsDir);
   let resolvedPath = null;
   let targetFile = null;
   const pathParts = specPath.split("/").filter((p) => p);
@@ -4261,9 +4479,9 @@ async function readSpecContent(specPath, cwd = process.cwd()) {
     const filePart = pathParts[pathParts.length - 1];
     resolvedPath = await resolveSpecPath(specPart, cwd, specsDir);
     if (resolvedPath) {
-      targetFile = path18.join(resolvedPath, filePart);
+      targetFile = path19.join(resolvedPath, filePart);
       try {
-        await fs13.access(targetFile);
+        await fs14.access(targetFile);
       } catch {
         return null;
       }
@@ -4282,8 +4500,8 @@ async function readSpecContent(specPath, cwd = process.cwd()) {
   if (!targetFile) {
     return null;
   }
-  const rawContent = await fs13.readFile(targetFile, "utf-8");
-  const fileName = path18.basename(targetFile);
+  const rawContent = await fs14.readFile(targetFile, "utf-8");
+  const fileName = path19.basename(targetFile);
   const isSubSpec = fileName !== config.structure.defaultFile;
   let frontmatter = null;
   if (!isSubSpec) {
@@ -4312,7 +4530,7 @@ async function readSpecContent(specPath, cwd = process.cwd()) {
     }
   }
   const content = lines.slice(contentStartIndex).join("\n").trim();
-  const specName = path18.basename(resolvedPath);
+  const specName = path19.basename(resolvedPath);
   const displayName = isSubSpec ? `${specName}/${fileName}` : specName;
   return {
     frontmatter,
@@ -4379,7 +4597,7 @@ function displayFormattedSpec(spec) {
 async function viewCommand(specPath, options = {}) {
   const spec = await readSpecContent(specPath, process.cwd());
   if (!spec) {
-    throw new Error(`Spec not found: ${specPath}. Try: lspec list`);
+    throw new Error(`Spec not found: ${specPath}. Try: lean-spec list`);
   }
   if (options.json) {
     const jsonOutput = {
@@ -4402,7 +4620,7 @@ async function viewCommand(specPath, options = {}) {
 async function openCommand(specPath, options = {}) {
   const cwd = process.cwd();
   const config = await loadConfig(cwd);
-  const specsDir = path18.join(cwd, config.specsDir);
+  const specsDir = path19.join(cwd, config.specsDir);
   let resolvedPath = null;
   let targetFile = null;
   const pathParts = specPath.split("/").filter((p) => p);
@@ -4411,9 +4629,9 @@ async function openCommand(specPath, options = {}) {
     const filePart = pathParts[pathParts.length - 1];
     resolvedPath = await resolveSpecPath(specPart, cwd, specsDir);
     if (resolvedPath) {
-      targetFile = path18.join(resolvedPath, filePart);
+      targetFile = path19.join(resolvedPath, filePart);
       try {
-        await fs13.access(targetFile);
+        await fs14.access(targetFile);
       } catch {
         targetFile = null;
       }
@@ -5415,6 +5633,7 @@ export {
   initProject,
   filesCommand,
   validateCommand,
+  migrateCommand,
   boardCommand,
   statsCommand,
   searchCommand,
@@ -5426,4 +5645,4 @@ export {
   createMcpServer,
   mcpCommand
 };
-//# sourceMappingURL=chunk-OXTU3PN4.js.map
+//# sourceMappingURL=chunk-S6TGAL75.js.map