@aladac/hu 0.1.0-a1

package/src/commands/docs.ts

@@ -0,0 +1,729 @@
+/**
+ * Documentation management commands
+ */
+
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defineCommand } from 'citty';
+import { c, formatSize } from '../lib/colors.ts';
+import {
+  GLOBAL_DOCS,
+  SYSTEM_DOCS,
+  countCheckboxes,
+  exists,
+  findMarkdownFiles,
+  findRepoRoot,
+  getStats,
+  parseFrontmatter,
+  readFile,
+  writeFile,
+} from '../lib/fs.ts';
+import type { DocInfo, SystemDocInfo } from '../types/index.ts';
+
+// ─────────────────────────────────────────────────────────────
+// List Docs
+// ─────────────────────────────────────────────────────────────
+
+function getFileInfo(filePath: string): DocInfo | null {
+  const stats = getStats(filePath);
+  const content = readFile(filePath);
+  if (!stats || !content) return null;
+
+  const frontmatter = parseFrontmatter(content);
+  const lines = content.split('\n').length;
+
+  // Get title from first # heading
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].trim() : path.basename(filePath, '.md');
+
+  return {
+    path: filePath,
+    name: path.basename(filePath),
+    title,
+    size: stats.size,
+    sizeHuman: formatSize(stats.size),
+    lines,
+    modified: stats.mtime.toISOString().split('T')[0],
+    source: frontmatter.source || null,
+    fetched: frontmatter.fetched || null,
+  };
+}
+
+function listDocs(location: string, format: string): void {
+  const cwd = process.cwd();
+  let files: string[] = [];
+
+  if (location === 'project' || location === 'all') {
+    const docDir = path.join(cwd, 'doc');
+    files.push(...findMarkdownFiles(docDir).filter((f) => !f.endsWith('README.md')));
+  }
+
+  if (location === 'global' || location === 'all') {
+    files.push(...findMarkdownFiles(GLOBAL_DOCS));
+  }
+
+  if (location === 'repo') {
+    const repoRoot = findRepoRoot();
+    const allMd = findMarkdownFiles(repoRoot);
+    files = allMd.filter((f) => {
+      const name = path.basename(f);
+      const rel = path.relative(repoRoot, f);
+      if (SYSTEM_DOCS.includes(name)) return false;
+      if (rel.startsWith('.claude/commands')) return false;
+      return true;
+    });
+  }
+
+  const docs = files.map(getFileInfo).filter((doc): doc is DocInfo => doc !== null);
+  docs.sort((a, b) => a.path.localeCompare(b.path));
+
+  if (format === 'json') {
+    console.log(JSON.stringify(docs, null, 2));
+  } else if (format === 'simple') {
+    for (const doc of docs) {
+      console.log(doc.path);
+    }
+  } else {
+    if (docs.length === 0) {
+      console.log('No documentation files found.');
+      return;
+    }
+
+    console.log('| File | Title | Size | Lines | Modified | Source |');
+    console.log('|------|-------|------|-------|----------|--------|');
+    for (const doc of docs) {
+      const relPath = path.relative(cwd, doc.path);
+      const source = doc.source ? `[link](${doc.source})` : '-';
+      console.log(
+        `| ${relPath} | ${doc.title} | ${doc.sizeHuman} | ${doc.lines} | ${doc.modified} | ${source} |`,
+      );
+    }
+    console.log(`\nTotal: ${docs.length} files`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Check System Docs
+// ─────────────────────────────────────────────────────────────
+
+const INTERNAL_DOCS = ['MODELS.md', 'PLAN.md', 'TODO.md', 'TEST.md', 'REFACTOR.md'];
+const STANDARD_DOCS = ['README.md', 'CLAUDE.md', 'LICENSE.md', 'CHANGELOG.md', 'CONTRIBUTING.md'];
+
+function getSystemDocInfo(repoRoot: string, filename: string): SystemDocInfo {
+  const filePath = path.join(repoRoot, filename);
+  const filePathLower = path.join(repoRoot, filename.toLowerCase());
+
+  let actualPath: string | null = null;
+  if (exists(filePath)) actualPath = filePath;
+  else if (exists(filePathLower)) actualPath = filePathLower;
+
+  if (!actualPath) {
+    return {
+      name: filename,
+      found: false,
+      path: null,
+      size: null,
+      sizeHuman: null,
+      lines: null,
+      modified: null,
+      pending: null,
+      completed: null,
+    };
+  }
+
+  const stats = getStats(actualPath);
+  const content = readFile(actualPath);
+  if (!stats || !content) {
+    return {
+      name: filename,
+      found: false,
+      path: null,
+      size: null,
+      sizeHuman: null,
+      lines: null,
+      modified: null,
+      pending: null,
+      completed: null,
+    };
+  }
+
+  const lines = content.split('\n').length;
+  const info: SystemDocInfo = {
+    name: filename,
+    found: true,
+    path: actualPath,
+    size: stats.size,
+    sizeHuman: formatSize(stats.size),
+    lines,
+    modified: stats.mtime.toISOString().split('T')[0],
+    pending: null,
+    completed: null,
+  };
+
+  if (['TODO.md', 'PLAN.md'].includes(filename)) {
+    const { pending, completed } = countCheckboxes(content);
+    info.pending = pending;
+    info.completed = completed;
+  }
+
+  return info;
+}
+
+function checkSystemDocs(format: string): void {
+  const repoRoot = findRepoRoot();
+  const internalDocs = INTERNAL_DOCS.map((name) => getSystemDocInfo(repoRoot, name));
+  const standardDocs = STANDARD_DOCS.map((name) => getSystemDocInfo(repoRoot, name));
+
+  const allDocs = [...internalDocs, ...standardDocs];
+  const foundCount = allDocs.filter((d) => d.found).length;
+  const pendingFiles = allDocs.filter((d) => d.pending !== null && d.pending > 0);
+
+  if (format === 'json') {
+    console.log(
+      JSON.stringify(
+        {
+          repoRoot,
+          internal: internalDocs,
+          standard: standardDocs,
+          summary: {
+            found: foundCount,
+            total: allDocs.length,
+            filesWithPending: pendingFiles.map((d) => d.name),
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log('## System Documents Status\n');
+    console.log(`Repository: ${repoRoot}\n`);
+
+    console.log('### Internal Project Files');
+    console.log('| File | Status | Size | Lines | Notes |');
+    console.log('|------|--------|------|-------|-------|');
+    for (const doc of internalDocs) {
+      const status = doc.found ? '✓ Found' : '✗ Not found';
+      const size = doc.sizeHuman || '-';
+      const lines = doc.lines?.toString() || '-';
+      let notes = '-';
+      if (doc.pending !== null) {
+        notes = `${doc.pending} pending, ${doc.completed} done`;
+      }
+      console.log(`| ${doc.name} | ${status} | ${size} | ${lines} | ${notes} |`);
+    }
+
+    console.log('\n### Standard Repo Files');
+    console.log('| File | Status | Size | Lines |');
+    console.log('|------|--------|------|-------|');
+    for (const doc of standardDocs) {
+      const status = doc.found ? '✓ Found' : '✗ Not found';
+      const size = doc.sizeHuman || '-';
+      const lines = doc.lines?.toString() || '-';
+      console.log(`| ${doc.name} | ${status} | ${size} | ${lines} |`);
+    }
+
+    console.log('\n### Summary');
+    console.log(`- Total system documents: ${foundCount} of ${allDocs.length}`);
+    if (pendingFiles.length > 0) {
+      console.log(`- Files with pending items: ${pendingFiles.map((d) => d.name).join(', ')}`);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Scan Docs (for sync/update)
+// ─────────────────────────────────────────────────────────────
+
+interface DocScanResult {
+  path: string;
+  relativePath: string;
+  source: string | null;
+  additionalSources: string[];
+  fetched: string | null;
+  size: number;
+  lines: number;
+  title: string;
+  location: 'project' | 'global';
+}
+
+interface ScanSummary {
+  targets: DocScanResult[];
+  withSource: number;
+  withoutSource: number;
+  stale: number; // fetched > 30 days ago
+  location: string;
+}
+
+/**
+ * Parse additional_sources from frontmatter (can be array or single value)
+ */
+function parseAdditionalSources(content: string): string[] {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return [];
+
+  const fmContent = match[1];
+  const sources: string[] = [];
+
+  // Check for array format
+  const arrayMatch = fmContent.match(/additional_sources:\s*\n((?:\s+-\s+.+\n?)+)/);
+  if (arrayMatch) {
+    const lines = arrayMatch[1].split('\n');
+    for (const line of lines) {
+      const urlMatch = line.match(/^\s+-\s+(.+)/);
+      if (urlMatch) sources.push(urlMatch[1].trim());
+    }
+  }
+
+  return sources;
+}
+
+/**
+ * Check if a date string is stale (> 30 days old)
+ */
+function isStale(dateStr: string | null): boolean {
+  if (!dateStr) return true;
+  const fetched = new Date(dateStr);
+  const now = new Date();
+  const diffDays = (now.getTime() - fetched.getTime()) / (1000 * 60 * 60 * 24);
+  return diffDays > 30;
+}
+
+/**
+ * Scan a single doc file for sync/update info
+ */
+function scanDocFile(filePath: string, location: 'project' | 'global'): DocScanResult | null {
+  const content = readFile(filePath);
+  const stats = getStats(filePath);
+  if (!content || !stats) return null;
+
+  const frontmatter = parseFrontmatter(content);
+  const additionalSources = parseAdditionalSources(content);
+
+  // Get title from first # heading
+  const titleMatch = content.match(/^#\s+(.+)$/m);
+  const title = titleMatch ? titleMatch[1].trim() : path.basename(filePath, '.md');
+
+  const repoRoot = findRepoRoot();
+  const relativePath =
+    location === 'project'
+      ? path.relative(repoRoot, filePath)
+      : path.relative(GLOBAL_DOCS, filePath);
+
+  return {
+    path: filePath,
+    relativePath,
+    source: frontmatter.source || null,
+    additionalSources,
+    fetched: frontmatter.fetched || null,
+    size: stats.size,
+    lines: content.split('\n').length,
+    title,
+    location,
+  };
+}
+
+/**
+ * Identify doc files to scan based on target argument
+ */
+function identifyTargets(target: string): { files: string[]; location: string } {
+  const cwd = process.cwd();
+  const repoRoot = findRepoRoot();
+
+  if (target === 'global') {
+    const files = findMarkdownFiles(GLOBAL_DOCS).filter((f) => !f.endsWith('README.md'));
+    return { files, location: 'global' };
+  }
+
+  if (target === 'all') {
+    const projectFiles = findMarkdownFiles(path.join(repoRoot, 'doc')).filter(
+      (f) => !f.endsWith('README.md'),
+    );
+    const globalFiles = findMarkdownFiles(GLOBAL_DOCS).filter((f) => !f.endsWith('README.md'));
+    return { files: [...projectFiles, ...globalFiles], location: 'all' };
+  }
+
+  // Check if it's a specific file path
+  const asPath = path.isAbsolute(target) ? target : path.join(cwd, target);
+  if (exists(asPath) && asPath.endsWith('.md')) {
+    return { files: [asPath], location: 'file' };
+  }
+
+  // Check if it's a category (subdirectory of doc/)
+  const categoryPath = path.join(repoRoot, 'doc', target);
+  if (exists(categoryPath) && getStats(categoryPath)?.isDirectory()) {
+    const files = findMarkdownFiles(categoryPath).filter((f) => !f.endsWith('README.md'));
+    return { files, location: `category:${target}` };
+  }
+
+  // Default: project docs
+  const docDir = path.join(repoRoot, 'doc');
+  const files = findMarkdownFiles(docDir).filter((f) => !f.endsWith('README.md'));
+  return { files, location: 'project' };
+}
+
+function scanDocs(target: string, format: string): void {
+  const { files, location } = identifyTargets(target);
+
+  const targets: DocScanResult[] = [];
+  for (const file of files) {
+    const loc = file.startsWith(GLOBAL_DOCS) ? 'global' : 'project';
+    const result = scanDocFile(file, loc);
+    if (result) targets.push(result);
+  }
+
+  const withSource = targets.filter((t) => t.source).length;
+  const withoutSource = targets.filter((t) => !t.source).length;
+  const stale = targets.filter((t) => t.source && isStale(t.fetched)).length;
+
+  const summary: ScanSummary = {
+    targets,
+    withSource,
+    withoutSource,
+    stale,
+    location,
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log('## Documentation Scan\n');
+    console.log(`Location: ${location}`);
+    console.log(`Total: ${targets.length} | With source: ${withSource} | Stale: ${stale}\n`);
+
+    if (targets.length === 0) {
+      console.log('No documentation files found.');
+      return;
+    }
+
+    console.log('| File | Source | Fetched | Status |');
+    console.log('|------|--------|---------|--------|');
+    for (const t of targets) {
+      const source = t.source ? 'Yes' : 'No';
+      const fetched = t.fetched || '-';
+      let status = '-';
+      if (t.source) {
+        status = isStale(t.fetched) ? `${c.yellow}stale${c.reset}` : `${c.green}current${c.reset}`;
+      }
+      console.log(`| ${t.relativePath} | ${source} | ${fetched} | ${status} |`);
+    }
+
+    if (stale > 0) {
+      console.log(`\n${c.yellow}${stale} doc(s) need updating (fetched > 30 days ago)${c.reset}`);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Archive Docs
+// ─────────────────────────────────────────────────────────────
+
+interface ArchiveResult {
+  file: string;
+  success: boolean;
+  archived?: string;
+  deleted?: boolean;
+  reason?: string;
+  error?: string;
+}
+
+/**
+ * Get project name from git repo or directory
+ */
+function getProjectName(): string {
+  const repoRoot = findRepoRoot();
+  try {
+    const remoteUrl = execSync('git remote get-url origin 2>/dev/null', {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+    }).trim();
+    // Extract repo name from URL (handles https and ssh)
+    const match = remoteUrl.match(/\/([^/]+?)(\.git)?$/);
+    if (match) return match[1];
+  } catch {
+    // No git remote, use directory name
+  }
+  return path.basename(repoRoot);
+}
+
+/**
+ * Generate timestamp in YYYYMMDD-HHMMSS format
+ */
+function generateTimestamp(): string {
+  const now = new Date();
+  const pad = (n: number) => n.toString().padStart(2, '0');
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+/**
+ * Remove completed items from checkbox content
+ * Returns null if all items are completed (file should be deleted)
+ */
+function removeCompletedItems(content: string): string | null {
+  const lines = content.split('\n');
+  const filtered = lines.filter((line) => !line.match(/^(\s*)-\s*\[x\]/i));
+
+  // Check if any pending items remain
+  const hasPending = filtered.some((line) => line.match(/^(\s*)-\s*\[ \]/));
+  if (!hasPending) return null;
+
+  return filtered.join('\n');
+}
+
+/**
+ * Archive a single file
+ */
+function archiveFile(
+  filePath: string,
+  projectName: string,
+  timestamp: string,
+  dryRun: boolean,
+): ArchiveResult {
+  const filename = path.basename(filePath);
+  const repoRoot = findRepoRoot();
+  const absPath = path.isAbsolute(filePath) ? filePath : path.join(repoRoot, filePath);
+
+  if (!exists(absPath)) {
+    return { file: filename, success: false, error: 'File not found' };
+  }
+
+  const content = readFile(absPath);
+  if (!content) {
+    return { file: filename, success: false, error: 'Could not read file' };
+  }
+
+  // Special handling for TODO.md and PLAN.md
+  const isProgressTracker = ['TODO.md', 'PLAN.md'].includes(filename.toUpperCase());
+  let archiveContent = content;
+
+  if (isProgressTracker) {
+    const processed = removeCompletedItems(content);
+    if (processed === null) {
+      // All items completed - delete without archiving
+      if (!dryRun) {
+        fs.unlinkSync(absPath);
+        try {
+          execSync(`git add "${absPath}" && git commit -m "docs: remove completed ${filename}"`, {
+            cwd: repoRoot,
+            stdio: 'pipe',
+          });
+        } catch {
+          // Not in git or commit failed
+        }
+      }
+      return {
+        file: filename,
+        success: true,
+        deleted: true,
+        reason: 'All items completed',
+      };
+    }
+    archiveContent = processed;
+  }
+
+  // Create archive destination
+  const archiveDir = path.join(GLOBAL_DOCS, projectName);
+  const archiveName = `${timestamp}-${filename}`;
+  const archivePath = path.join(archiveDir, archiveName);
+
+  if (!dryRun) {
+    // Ensure archive directory exists
+    fs.mkdirSync(archiveDir, { recursive: true });
+
+    // Write to archive
+    writeFile(archivePath, archiveContent);
+
+    // Delete from repo
+    fs.unlinkSync(absPath);
+
+    // Commit the deletion
+    try {
+      execSync(`git add "${absPath}" && git commit -m "docs: archive ${filename}"`, {
+        cwd: repoRoot,
+        stdio: 'pipe',
+      });
+    } catch {
+      // Not in git or commit failed
+    }
+
+    // Update manifest if exists
+    const manifestPath = path.join(repoRoot, 'document-manifest.toml');
+    if (exists(manifestPath)) {
+      const manifest = readFile(manifestPath);
+      if (manifest) {
+        // Remove entry for this file (simple approach)
+        const lines = manifest.split('\n');
+        const filtered = lines.filter((line) => !line.includes(filename));
+        if (filtered.length !== lines.length) {
+          writeFile(manifestPath, filtered.join('\n'));
+        }
+      }
+    }
+  }
+
+  return {
+    file: filename,
+    success: true,
+    archived: archivePath,
+  };
+}
+
+function archiveDocs(files: string[], dryRun: boolean, format: string): void {
+  if (files.length === 0) {
+    console.log('No files specified. Usage: hu docs archive <file...>');
+    return;
+  }
+
+  const projectName = getProjectName();
+  const timestamp = generateTimestamp();
+  const results: ArchiveResult[] = [];
+
+  for (const file of files) {
+    const result = archiveFile(file, projectName, timestamp, dryRun);
+    results.push(result);
+  }
+
+  if (format === 'json') {
+    console.log(JSON.stringify({ projectName, timestamp, dryRun, results }, null, 2));
+  } else {
+    console.log('## Archive Results\n');
+    console.log(`Project: ${projectName}`);
+    console.log(`Timestamp: ${timestamp}`);
+    if (dryRun) console.log(`Mode: ${c.yellow}DRY RUN${c.reset}\n`);
+    else console.log('');
+
+    for (const r of results) {
+      if (r.success) {
+        if (r.deleted) {
+          console.log(`${c.green}✓${c.reset} ${r.file} - deleted (${r.reason})`);
+        } else {
+          console.log(`${c.green}✓${c.reset} ${r.file} → ${r.archived}`);
+        }
+      } else {
+        console.log(`${c.red}✗${c.reset} ${r.file} - ${r.error}`);
+      }
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Subcommands
+// ─────────────────────────────────────────────────────────────
+
+const listCommand = defineCommand({
+  meta: {
+    name: 'list',
+    description: 'List documentation files with metadata',
+  },
+  args: {
+    location: {
+      type: 'positional',
+      description: 'Location to scan: project (default), global, all, repo',
+      required: false,
+    },
+    json: {
+      type: 'boolean',
+      alias: 'j',
+      description: 'Output as JSON',
+    },
+    simple: {
+      type: 'boolean',
+      alias: 's',
+      description: 'Output as simple list',
+    },
+  },
+  run: ({ args }) => {
+    const location = (args.location as string) || 'project';
+    const format = args.json ? 'json' : args.simple ? 'simple' : 'table';
+    listDocs(location, format);
+  },
+});
+
+const checkCommand = defineCommand({
+  meta: {
+    name: 'check',
+    description: 'Check status of system documents in repo',
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      alias: 'j',
+      description: 'Output as JSON',
+    },
+  },
+  run: ({ args }) => {
+    const format = args.json ? 'json' : 'table';
+    checkSystemDocs(format);
+  },
+});
+
+const scanCommand = defineCommand({
+  meta: {
+    name: 'scan',
+    description: 'Scan docs for sync/update (shows sources and staleness)',
+  },
+  args: {
+    target: {
+      type: 'positional',
+      description: 'Target: file path, category, "global", "all", or empty for project',
+      required: false,
+    },
+    json: {
+      type: 'boolean',
+      alias: 'j',
+      description: 'Output as JSON',
+    },
+  },
+  run: ({ args }) => {
+    const target = (args.target as string) || '';
+    const format = args.json ? 'json' : 'table';
+    scanDocs(target, format);
+  },
+});
+
+const archiveCommand = defineCommand({
+  meta: {
+    name: 'archive',
+    description: 'Archive docs from repo to global store',
+  },
+  args: {
+    files: {
+      type: 'positional',
+      description: 'Files to archive',
+      required: false,
+    },
+    dryRun: {
+      type: 'boolean',
+      alias: 'd',
+      description: 'Show what would be done without making changes',
+    },
+    json: {
+      type: 'boolean',
+      alias: 'j',
+      description: 'Output as JSON',
+    },
+  },
+  run: ({ args }) => {
+    const files = (args._ || []) as string[];
+    const format = args.json ? 'json' : 'table';
+    archiveDocs(files, !!args.dryRun, format);
+  },
+});
+
+// ─────────────────────────────────────────────────────────────
+// Main Command
+// ─────────────────────────────────────────────────────────────
+
+export const docsCommand = defineCommand({
+  meta: {
+    name: 'docs',
+    description: 'Documentation management tools',
+  },
+  subCommands: {
+    list: listCommand,
+    check: checkCommand,
+    scan: scanCommand,
+    archive: archiveCommand,
+  },
+});