depa-codument 0.4.1

package/src/cli/commands/engineering.ts

@@ -0,0 +1,105 @@
+import * as path from 'path';
+import { parseOptions, CODUMENT_DIR } from '../utils';
+import { lintEngineeringRegistry } from '../engineering/lint';
+import { loadEngineeringConfig, engineeringEnabled } from '../engineering/config';
+import { validateEngineeringTree, type ValidateFinding } from '../engineering/validate';
+
+export async function engineeringCommand(args: string[]) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case 'lint':
+      return engineeringLint(rest);
+    case 'validate':
+      return engineeringValidate(rest);
+    default:
+      console.error(`Unknown engineering subcommand: ${sub ?? '(none)'}`);
+      console.log('Usage: codument engineering lint [dir] [--max-lines N] [--max-nodes N]');
+      console.log('       codument engineering validate [dir] [--deltas <track>]');
+      process.exit(1);
+  }
+}
+
+function engineeringValidate(args: string[]): void {
+  const { positional, options } = parseOptions(args);
+  const deltaTrack = typeof options.deltas === 'string' ? options.deltas : undefined;
+
+  let dir: string;
+  let mode: 'registry' | 'deltas';
+  // An explicit [dir] positional is a manual request: bypass the enabled gate.
+  let explicit = positional.length > 0;
+
+  if (deltaTrack) {
+    dir = path.join(CODUMENT_DIR, 'tracks', deltaTrack, 'engineering_deltas');
+    mode = 'deltas';
+    explicit = true;
+  } else if (positional[0]) {
+    dir = positional[0];
+    mode = 'registry';
+  } else {
+    dir = loadEngineeringConfig().registryDir;
+    mode = 'registry';
+  }
+
+  // Default registry mode is gated; explicit dir / --deltas bypass the gate.
+  if (!explicit && !engineeringEnabled()) {
+    console.log('engineering disabled，跳过 (set enabled="true" in codument/config/engineering.xml)');
+    return;
+  }
+
+  const findings = validateEngineeringTree(dir, { mode });
+  reportFindings(findings, dir);
+}
+
+function reportFindings(findings: ValidateFinding[], dir: string): void {
+  if (findings.length === 0) {
+    console.log(`✓ engineering validate: no issues in ${dir}`);
+    return;
+  }
+
+  // Group by file, preserving first-seen order.
+  const byFile = new Map<string, ValidateFinding[]>();
+  for (const f of findings) {
+    const list = byFile.get(f.file);
+    if (list) list.push(f);
+    else byFile.set(f.file, [f]);
+  }
+
+  console.log(`engineering validate: issues in ${dir}:`);
+  for (const [file, list] of byFile) {
+    console.log(`${file}:`);
+    for (const f of list) {
+      const where = f.line !== undefined ? ` (line ${f.line})` : '';
+      console.log(`  [${f.layer}/${f.severity}] ${f.message}${where}`);
+    }
+  }
+
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  console.log(`${errors} error(s), ${warnings} warning(s)`);
+
+  if (errors > 0) process.exit(1);
+}
+
+function engineeringLint(args: string[]): void {
+  const { positional, options } = parseOptions(args);
+  const config = loadEngineeringConfig();
+  const dir = positional[0] ?? config.registryDir;
+  const thresholds = {
+    maxLines: options['max-lines'] ? Number(options['max-lines']) : config.thresholds.maxLines,
+    maxNodes: options['max-nodes'] ? Number(options['max-nodes']) : config.thresholds.maxNodes,
+  };
+
+  const findings = lintEngineeringRegistry(dir, thresholds);
+  if (findings.length === 0) {
+    console.log(`✓ engineering lint: no fractal-split candidates in ${dir}`);
+    return;
+  }
+
+  console.log(`engineering lint: ${findings.length} fractal-split candidate(s) in ${dir}:`);
+  for (const f of findings) {
+    console.log(
+      `  • ${f.file} — ${f.reasons.join(', ')} → consider splitting into a same-name folder (see folder-manifest.md)`,
+    );
+  }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,54 @@
+import { parseOptions, codumentExists } from '../utils';
+import {
+  installSkillTemplates,
+  installTemplates,
+  ensureCodumentGitignoreRules,
+  injectAgentsBlock,
+  parseAgents,
+  resolveSkillsTargets,
+  writeCliToolsConfig,
+} from '../utils/install';
+
+/**
+ * `codument init` — pure text copy of the embedded templates into the project.
+ *
+ * No interactive prompts, no template rendering, no per-agent prompt variants,
+ * no commands: just copies codument/** into the workspace and the skill shells
+ * into the agent skills directory, then injects the AGENTS.md managed block.
+ *
+ * Options:
+ *   --agent <names>       comma-separated target agent skills dirs (claude|codex|opencode|eidolon|codeflicker|sparrow; default claude)
+ *   --skills-dir <path>   explicit skills destination (overrides --agent as a single target)
+ *   --force               overwrite existing codument/** files (default: preserve existing)
+ */
+export async function initCommand(args: string[]): Promise<void> {
+  const { options } = parseOptions(args);
+  const selectedTools = parseAgents(typeof options['agent'] === 'string' ? String(options['agent']) : undefined);
+  const targets = resolveSkillsTargets(options, selectedTools);
+  const [firstTarget, ...additionalTargets] = targets;
+  const force = options['force'] === true;
+
+  const result = installTemplates({ skillsDir: firstTarget.skillsDir, overwriteStd: false, force });
+  const skillResults = [{ ...firstTarget, skillsWritten: result.skillsWritten, skillsRemoved: result.skillsRemoved }];
+  for (const target of additionalTargets) {
+    skillResults.push({ ...target, ...installSkillTemplates(target.skillsDir) });
+  }
+  injectAgentsBlock();
+  const gitignoreRulesAdded = ensureCodumentGitignoreRules();
+
+  console.log('Codument initialized.');
+  console.log(`  codument/ : ${result.workspaceWritten} written, ${result.workspaceSkipped} kept`);
+  for (const skillResult of skillResults) {
+    const removed = skillResult.skillsRemoved ? `, ${skillResult.skillsRemoved} deprecated removed` : '';
+    console.log(`  skills    : ${skillResult.skillsWritten} → ${skillResult.skillsDir} (agent: ${skillResult.agent}${removed})`);
+  }
+  writeCliToolsConfig(selectedTools);
+  console.log('  config/cli-tools.json: tools updated');
+  console.log('  AGENTS.md : managed block written');
+  if (gitignoreRulesAdded > 0) {
+    console.log(`  .gitignore: ${gitignoreRulesAdded} codument rule(s) added`);
+  }
+  if (codumentExists()) {
+    console.log('\nNext: edit codument/attractors/{project,product}.md, then use the codument-plan-track skill.');
+  }
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,73 @@
+import { getTracks, getSpecs, parseOptions, formatStatus, codumentExists } from '../utils';
+
+export async function listCommand(args: string[]) {
+  if (!codumentExists()) {
+    console.error('Codument is not initialized. Run codument init first.');
+    process.exit(1);
+  }
+
+  const { options } = parseOptions(args);
+  const showSpecs = options['specs'] === true;
+  const jsonOutput = options['json'] === true;
+
+  if (showSpecs) {
+    const specs = getSpecs();
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(specs, null, 2));
+      return;
+    }
+
+    if (specs.length === 0) {
+      console.log('No specifications found.');
+      return;
+    }
+
+    console.log('\nSpecifications:\n');
+    console.log('  ID                          Format      Requirements  Scenarios');
+    console.log('  ' + '-'.repeat(72));
+
+    for (const spec of specs) {
+      const id = spec.id.padEnd(28);
+      const format = (spec.format || 'markdown').padEnd(12);
+      const reqs = String(spec.requirements).padStart(8);
+      const scenarios = String(spec.scenarios).padStart(10);
+      console.log(`  ${id}${format}${reqs}${scenarios}`);
+    }
+
+    console.log(`\nTotal: ${specs.length} spec(s)\n`);
+  } else {
+    const tracks = getTracks();
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(tracks, null, 2));
+      return;
+    }
+
+    if (tracks.length === 0) {
+      console.log('No active tracks found.');
+      return;
+    }
+
+    console.log('\nActive Tracks:\n');
+    console.log('  Status  ID                              Type      Progress');
+    console.log('  ' + '-'.repeat(68));
+
+    for (const track of tracks) {
+      const status = formatStatus(track.metadata.status);
+      const id = track.id.padEnd(32);
+      const type = track.metadata.type.padEnd(10);
+
+      let progress = '-';
+      if (track.taskSummary) {
+        const { completed, total_tasks } = track.taskSummary;
+        const pct = total_tasks > 0 ? Math.round((completed / total_tasks) * 100) : 0;
+        progress = `${completed}/${total_tasks} (${pct}%)`;
+      }
+
+      console.log(`  ${status}   ${id}${type}${progress}`);
+    }
+
+    console.log(`\nTotal: ${tracks.length} track(s)\n`);
+  }
+}

package/src/cli/commands/modeling.ts

@@ -0,0 +1,105 @@
+import * as path from 'path';
+import { parseOptions, CODUMENT_DIR } from '../utils';
+import { lintModelingRegistry } from '../modeling/lint';
+import { loadModelingConfig, modelingEnabled } from '../modeling/config';
+import { validateModelingTree, type ValidateFinding } from '../modeling/validate';
+
+export async function modelingCommand(args: string[]) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case 'lint':
+      return modelingLint(rest);
+    case 'validate':
+      return modelingValidate(rest);
+    default:
+      console.error(`Unknown modeling subcommand: ${sub ?? '(none)'}`);
+      console.log('Usage: codument modeling lint [dir] [--max-lines N] [--max-nodes N]');
+      console.log('       codument modeling validate [dir] [--deltas <track>]');
+      process.exit(1);
+  }
+}
+
+function modelingValidate(args: string[]): void {
+  const { positional, options } = parseOptions(args);
+  const deltaTrack = typeof options.deltas === 'string' ? options.deltas : undefined;
+
+  let dir: string;
+  let mode: 'registry' | 'deltas';
+  // An explicit [dir] positional is a manual request: bypass the enabled gate.
+  let explicit = positional.length > 0;
+
+  if (deltaTrack) {
+    dir = path.join(CODUMENT_DIR, 'tracks', deltaTrack, 'modeling_deltas');
+    mode = 'deltas';
+    explicit = true;
+  } else if (positional[0]) {
+    dir = positional[0];
+    mode = 'registry';
+  } else {
+    dir = loadModelingConfig().registryDir;
+    mode = 'registry';
+  }
+
+  // Default registry mode is gated; explicit dir / --deltas bypass the gate.
+  if (!explicit && !modelingEnabled()) {
+    console.log('modeling disabled，跳过 (set enabled="true" in codument/config/modeling.xml)');
+    return;
+  }
+
+  const findings = validateModelingTree(dir, { mode });
+  reportFindings(findings, dir);
+}
+
+function reportFindings(findings: ValidateFinding[], dir: string): void {
+  if (findings.length === 0) {
+    console.log(`✓ modeling validate: no issues in ${dir}`);
+    return;
+  }
+
+  // Group by file, preserving first-seen order.
+  const byFile = new Map<string, ValidateFinding[]>();
+  for (const f of findings) {
+    const list = byFile.get(f.file);
+    if (list) list.push(f);
+    else byFile.set(f.file, [f]);
+  }
+
+  console.log(`modeling validate: issues in ${dir}:`);
+  for (const [file, list] of byFile) {
+    console.log(`${file}:`);
+    for (const f of list) {
+      const where = f.line !== undefined ? ` (line ${f.line})` : '';
+      console.log(`  [${f.layer}/${f.severity}] ${f.message}${where}`);
+    }
+  }
+
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.filter((f) => f.severity === 'warning').length;
+  console.log(`${errors} error(s), ${warnings} warning(s)`);
+
+  if (errors > 0) process.exit(1);
+}
+
+function modelingLint(args: string[]): void {
+  const { positional, options } = parseOptions(args);
+  const config = loadModelingConfig();
+  const dir = positional[0] ?? config.registryDir;
+  const thresholds = {
+    maxLines: options['max-lines'] ? Number(options['max-lines']) : config.thresholds.maxLines,
+    maxNodes: options['max-nodes'] ? Number(options['max-nodes']) : config.thresholds.maxNodes,
+  };
+
+  const findings = lintModelingRegistry(dir, thresholds);
+  if (findings.length === 0) {
+    console.log(`✓ modeling lint: no fractal-split candidates in ${dir}`);
+    return;
+  }
+
+  console.log(`modeling lint: ${findings.length} fractal-split candidate(s) in ${dir}:`);
+  for (const f of findings) {
+    console.log(
+      `  • ${f.file} — ${f.reasons.join(', ')} → consider splitting into a same-name folder (see folder-manifest.md)`,
+    );
+  }
+}

package/src/cli/commands/show.ts

@@ -0,0 +1,238 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getTrack, getSpecs, parseOptions, formatStatus, codumentExists, TRACKS_DIR, SPECS_DIR } from '../utils';
+import { getSpecXmlStats, loadSpecXml } from '../utils/spec-xml';
+
+export async function showCommand(args: string[]) {
+  if (!codumentExists()) {
+    console.error('Codument is not initialized. Run codument init first.');
+    process.exit(1);
+  }
+
+  const { positional, options } = parseOptions(args);
+  const itemId = positional[0];
+  const itemType = options['type'] as string | undefined;
+  const jsonOutput = options['json'] === true;
+
+  if (!itemId) {
+    console.error('Please specify a track or spec ID.');
+    console.log('Usage: codument show <id> [--type track|spec] [--json]');
+    process.exit(1);
+  }
+
+  // Try to determine type
+  let foundType: 'track' | 'spec' | null = null;
+
+  if (itemType === 'track' || itemType === 'spec') {
+    foundType = itemType;
+  } else {
+    // Auto-detect
+    const trackDir = path.join(TRACKS_DIR, itemId);
+    const specDir = path.join(SPECS_DIR, itemId);
+    const specXmlFile = path.join(SPECS_DIR, `${itemId}.xml`);
+
+    if (fs.existsSync(trackDir)) {
+      foundType = 'track';
+    } else if (fs.existsSync(specDir) || fs.existsSync(specXmlFile)) {
+      foundType = 'spec';
+    }
+  }
+
+  if (!foundType) {
+    console.error(`Item not found: ${itemId}`);
+    console.log('Use --type to specify whether this is a track or spec.');
+    process.exit(1);
+  }
+
+  if (foundType === 'track') {
+    showTrack(itemId, jsonOutput);
+  } else {
+    showSpec(itemId, jsonOutput);
+  }
+}
+
+function showTrack(trackId: string, jsonOutput: boolean) {
+  const track = getTrack(trackId);
+
+  if (!track) {
+    console.error(`Track not found: ${trackId}`);
+    process.exit(1);
+  }
+
+  if (jsonOutput) {
+    // Include file contents in JSON output
+    const trackDir = path.join(TRACKS_DIR, trackId);
+    const specDeltaFiles = collectTrackXmlSpecDeltas(trackDir);
+    const result: Record<string, unknown> = {
+      ...track,
+      files: {},
+    };
+
+    const files = ['proposal.md', 'track.xml', 'design.md', 'decisions.md'];
+    for (const file of files) {
+      const filePath = path.join(trackDir, file);
+      if (fs.existsSync(filePath)) {
+        (result.files as Record<string, string>)[file] = fs.readFileSync(filePath, 'utf-8');
+      }
+    }
+    for (const filePath of specDeltaFiles) {
+      const relativePath = path.relative(trackDir, filePath);
+      (result.files as Record<string, string>)[relativePath] = fs.readFileSync(filePath, 'utf-8');
+    }
+
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const trackDir = path.join(TRACKS_DIR, trackId);
+  const specDeltaFiles = collectTrackXmlSpecDeltas(trackDir);
+
+  console.log('\n' + '='.repeat(60));
+  console.log(`Track: ${trackId}`);
+  console.log('='.repeat(60));
+
+  console.log(`\nStatus:      ${formatStatus(track.metadata.status)} ${track.metadata.status}`);
+  console.log(`Type:        ${track.metadata.type}`);
+  console.log(`Description: ${track.metadata.description}`);
+  console.log(`Created:     ${track.metadata.created_at}`);
+  console.log(`Updated:     ${track.metadata.updated_at}`);
+
+  if (track.taskSummary) {
+    const s = track.taskSummary;
+    const pct = s.total_tasks > 0 ? Math.round((s.completed / s.total_tasks) * 100) : 0;
+    console.log(`\nProgress:    ${s.completed}/${s.total_tasks} (${pct}%)`);
+    console.log(`  Phases:    ${s.total_phases}`);
+    console.log(`  Completed: ${s.completed}`);
+    console.log(`  In Progress: ${s.in_progress}`);
+    console.log(`  Todo:      ${s.todo}`);
+    console.log(`  Blocked:   ${s.blocked}`);
+  }
+
+  console.log('\nFiles:');
+  const files = ['proposal.md', 'track.xml', 'design.md', 'decisions.md'];
+  for (const file of files) {
+    const filePath = path.join(trackDir, file);
+    const exists = fs.existsSync(filePath);
+    const status = exists ? '✓' : '✗';
+    console.log(`  ${status} ${file}`);
+  }
+  if (specDeltaFiles.length > 0) {
+    for (const filePath of specDeltaFiles) {
+      console.log(`  ✓ ${path.relative(trackDir, filePath)}`);
+    }
+  } else {
+    console.log(`  ✗ behavior_deltas/**/*.xml`);
+  }
+
+  console.log('');
+}
+
+function collectTrackXmlSpecDeltas(trackDir: string): string[] {
+  const results: string[] = [];
+  const roots = [
+    path.join(trackDir, 'behavior_deltas'),
+    path.join(trackDir, 'spec_deltas'),
+    path.join(trackDir, 'spec-deltas'),
+  ];
+
+  const visit = (dir: string) => {
+    if (!fs.existsSync(dir)) {
+      return;
+    }
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(entryPath);
+      } else if (entry.isFile() && entry.name.endsWith('.xml')) {
+        results.push(entryPath);
+      }
+    }
+  };
+
+  for (const root of roots) {
+    visit(root);
+  }
+  return results.sort();
+}
+
+function showSpec(specId: string, jsonOutput: boolean) {
+  const specDir = path.join(SPECS_DIR, specId);
+  const specPath = path.join(specDir, 'spec.md');
+  const specXmlFilePath = path.join(SPECS_DIR, `${specId}.xml`);
+  const specXmlIndexPath = path.join(specDir, 'index.xml');
+
+  const isXml = fs.existsSync(specXmlFilePath) || fs.existsSync(specXmlIndexPath);
+  if (!fs.existsSync(specPath) && !isXml) {
+    console.error(`Spec not found: ${specId}`);
+    process.exit(1);
+  }
+
+  if (isXml) {
+    const xmlEntryPath = fs.existsSync(specXmlFilePath) ? specXmlFilePath : specDir;
+    const xmlDisplayPath = fs.existsSync(specXmlFilePath) ? specXmlFilePath : specXmlIndexPath;
+    const content = fs.readFileSync(xmlDisplayPath, 'utf-8');
+    const root = loadSpecXml(xmlEntryPath);
+    const stats = getSpecXmlStats(root);
+
+    if (jsonOutput) {
+      console.log(JSON.stringify({
+        id: specId,
+        path: xmlDisplayPath,
+        format: 'xml',
+        requirements: stats.requirements,
+        scenarios: stats.scenarios,
+        content,
+      }, null, 2));
+      return;
+    }
+
+    console.log('\n' + '='.repeat(60));
+    console.log(`Spec: ${specId}`);
+    console.log('='.repeat(60));
+    console.log('\nFormat: XML');
+    console.log(`Requirements: ${stats.requirements}`);
+    console.log(`Scenarios: ${stats.scenarios}`);
+    console.log('\nFiles:');
+    console.log(`  ✓ ${path.relative(specDir, xmlDisplayPath) || path.basename(xmlDisplayPath)}`);
+    console.log('');
+    return;
+  }
+
+  const content = fs.readFileSync(specPath, 'utf-8');
+  const requirements = content.match(/^### Requirement: (.+)$/gm) || [];
+  const scenarios = content.match(/^#### Scenario: (.+)$/gm) || [];
+
+  if (jsonOutput) {
+    console.log(JSON.stringify({
+      id: specId,
+      path: specPath,
+      format: 'markdown',
+      requirements: requirements.map(r => r.replace('### Requirement: ', '')),
+      scenarios: scenarios.map(s => s.replace('#### Scenario: ', '')),
+      content,
+    }, null, 2));
+    return;
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log(`Spec: ${specId}`);
+  console.log('='.repeat(60));
+
+  console.log(`\nRequirements: ${requirements.length}`);
+  for (const req of requirements) {
+    console.log(`  - ${req.replace('### Requirement: ', '')}`);
+  }
+
+  console.log(`\nScenarios: ${scenarios.length}`);
+
+  console.log('\nFiles:');
+  const files = ['spec.md', 'design.md'];
+  for (const file of files) {
+    const filePath = path.join(specDir, file);
+    const exists = fs.existsSync(filePath);
+    const status = exists ? '✓' : '✗';
+    console.log(`  ${status} ${file}`);
+  }
+
+  console.log('');
+}