@localsummer/incspec 0.0.1

package/lib/spec.mjs

@@ -0,0 +1,300 @@
+/**
+ * Specification file operations for incspec
+ * - File version management
+ * - CRUD for spec files
+ * - Archive management
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { INCSPEC_DIR, DIRS, parseFrontmatter, serializeFrontmatter } from './config.mjs';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureUniqueArchivePath(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return filePath;
+  }
+
+  const dir = path.dirname(filePath);
+  const ext = path.extname(filePath);
+  const base = path.basename(filePath, ext);
+  let counter = 1;
+  let candidate = filePath;
+
+  while (fs.existsSync(candidate)) {
+    candidate = path.join(dir, `${base}-copy${counter}${ext}`);
+    counter += 1;
+  }
+
+  return candidate;
+}
+
+/**
+ * List spec files in a directory
+ * @param {string} projectRoot
+ * @param {string} type - 'baselines' | 'requirements' | 'increments' | 'archives'
+ * @returns {Array<{name: string, path: string, mtime: Date}>}
+ */
+export function listSpecs(projectRoot, type) {
+  const dir = path.join(projectRoot, INCSPEC_DIR, DIRS[type] || type);
+
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  const files = fs.readdirSync(dir);
+  return files
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      const filePath = path.join(dir, f);
+      const stats = fs.statSync(filePath);
+      return {
+        name: f,
+        path: filePath,
+        mtime: stats.mtime,
+      };
+    })
+    .sort((a, b) => b.mtime - a.mtime); // Sort by modification time, newest first
+}
+
+/**
+ * Get next version number for a spec type
+ * @param {string} projectRoot
+ * @param {string} type - 'baselines' | 'increments'
+ * @param {string} prefix - file name prefix (e.g., module name)
+ * @returns {number}
+ */
+export function getNextVersion(projectRoot, type, prefix) {
+  const specs = listSpecs(projectRoot, type);
+  const safePrefix = escapeRegExp(prefix);
+  const pattern = new RegExp(`^${safePrefix}.*-v(\\d+)\\.md$`);
+
+  const versions = specs
+    .map(s => {
+      const match = s.name.match(pattern);
+      return match ? parseInt(match[1], 10) : 0;
+    })
+    .filter(v => v > 0);
+
+  return versions.length > 0 ? Math.max(...versions) + 1 : 1;
+}
+
+/**
+ * Get latest spec file for a given prefix
+ * @param {string} projectRoot
+ * @param {string} type
+ * @param {string} prefix
+ * @returns {Object|null}
+ */
+export function getLatestSpec(projectRoot, type, prefix) {
+  const specs = listSpecs(projectRoot, type);
+  const safePrefix = escapeRegExp(prefix);
+  const pattern = new RegExp(`^${safePrefix}.*-v(\\d+)\\.md$`);
+
+  const versioned = specs
+    .map(s => {
+      const match = s.name.match(pattern);
+      return match ? { ...s, version: parseInt(match[1], 10) } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.version - a.version);
+
+  return versioned.length > 0 ? versioned[0] : null;
+}
+
+/**
+ * Create a baseline spec file
+ * @param {string} projectRoot
+ * @param {string} moduleName
+ * @param {string} content
+ * @returns {string} Created file path
+ */
+export function createBaseline(projectRoot, moduleName, content) {
+  const version = getNextVersion(projectRoot, 'baselines', moduleName);
+  const fileName = `${moduleName}-baseline-v${version}.md`;
+  const filePath = path.join(projectRoot, INCSPEC_DIR, DIRS.baselines, fileName);
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}
+
+/**
+ * Create an increment spec file
+ * @param {string} projectRoot
+ * @param {string} featureName
+ * @param {string} content
+ * @returns {string} Created file path
+ */
+export function createIncrement(projectRoot, featureName, content) {
+  const version = getNextVersion(projectRoot, 'increments', featureName);
+  const fileName = `${featureName}-increment-v${version}.md`;
+  const filePath = path.join(projectRoot, INCSPEC_DIR, DIRS.increments, fileName);
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}
+
+/**
+ * Create a requirements file
+ * @param {string} projectRoot
+ * @param {string} type - 'structured-requirements' | 'ui-dependencies'
+ * @param {string} content
+ * @returns {string} Created file path
+ */
+export function createRequirement(projectRoot, type, content) {
+  const fileName = `${type}.md`;
+  const filePath = path.join(projectRoot, INCSPEC_DIR, DIRS.requirements, fileName);
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+  return filePath;
+}
+
+/**
+ * Read a spec file
+ * @param {string} filePath
+ * @returns {{frontmatter: Object, body: string, raw: string}}
+ */
+export function readSpec(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`文件不存在: ${filePath}`);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const { frontmatter, body } = parseFrontmatter(raw);
+
+  return { frontmatter, body, raw };
+}
+
+/**
+ * Archive a spec file
+ * @param {string} projectRoot
+ * @param {string} filePath
+ * @param {boolean} deleteOriginal - Default true (move mode) to keep workflow clean
+ * @param {string} [module] - Optional module name for subdirectory grouping
+ * @returns {string} Archive path
+ */
+export function archiveSpec(projectRoot, filePath, deleteOriginal = true, module = null) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`文件不存在: ${filePath}`);
+  }
+
+  const now = new Date();
+  const yearMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
+  
+  // Build archive directory: archives/YYYY-MM[/module]
+  let archiveDir = path.join(projectRoot, INCSPEC_DIR, DIRS.archives, yearMonth);
+  if (module) {
+    archiveDir = path.join(archiveDir, module);
+  }
+
+  // Create archive directory if needed
+  if (!fs.existsSync(archiveDir)) {
+    fs.mkdirSync(archiveDir, { recursive: true });
+  }
+
+  const fileName = path.basename(filePath);
+  const archivePath = path.join(archiveDir, fileName);
+  const finalArchivePath = ensureUniqueArchivePath(archivePath);
+
+  // Copy or move file
+  fs.copyFileSync(filePath, finalArchivePath);
+  if (deleteOriginal) {
+    fs.unlinkSync(filePath);
+  }
+
+  return finalArchivePath;
+}
+
+/**
+ * Get spec file info from path
+ * @param {string} filePath
+ * @returns {Object}
+ */
+export function getSpecInfo(filePath) {
+  const fileName = path.basename(filePath);
+  const dir = path.basename(path.dirname(filePath));
+
+  // Parse file name pattern: {name}-{type}-v{version}.md
+  const baselineMatch = fileName.match(/^(.+)-baseline-v(\d+)\.md$/);
+  const incrementMatch = fileName.match(/^(.+)-increment-v(\d+)\.md$/);
+  const requirementMatch = fileName.match(/^(structured-requirements|ui-dependencies)\.md$/);
+
+  if (baselineMatch) {
+    return {
+      type: 'baseline',
+      name: baselineMatch[1],
+      version: parseInt(baselineMatch[2], 10),
+      fileName,
+    };
+  }
+
+  if (incrementMatch) {
+    return {
+      type: 'increment',
+      name: incrementMatch[1],
+      version: parseInt(incrementMatch[2], 10),
+      fileName,
+    };
+  }
+
+  if (requirementMatch) {
+    return {
+      type: 'requirement',
+      name: requirementMatch[1],
+      version: null,
+      fileName,
+    };
+  }
+
+  return {
+    type: 'unknown',
+    name: fileName.replace('.md', ''),
+    version: null,
+    fileName,
+  };
+}
+
+/**
+ * Generate spec file path
+ * @param {string} projectRoot
+ * @param {string} type - 'baselines' | 'requirements' | 'increments'
+ * @param {string} fileName
+ * @returns {string}
+ */
+export function getSpecPath(projectRoot, type, fileName) {
+  return path.join(projectRoot, INCSPEC_DIR, DIRS[type] || type, fileName);
+}
+
+/**
+ * Check if spec file exists
+ * @param {string} projectRoot
+ * @param {string} type
+ * @param {string} fileName
+ * @returns {boolean}
+ */
+export function specExists(projectRoot, type, fileName) {
+  const filePath = getSpecPath(projectRoot, type, fileName);
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Delete a spec file
+ * @param {string} filePath
+ * @param {boolean} archive - Whether to archive before deleting
+ * @param {string} projectRoot - Required if archive is true
+ * @param {string} [module] - Optional module name for archive subdirectory
+ */
+export function deleteSpec(filePath, archive = true, projectRoot = null, module = null) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`文件不存在: ${filePath}`);
+  }
+
+  if (archive && projectRoot) {
+    archiveSpec(projectRoot, filePath, true, module);
+  } else {
+    fs.unlinkSync(filePath);
+  }
+}

package/lib/terminal.mjs

@@ -0,0 +1,292 @@
+/**
+ * Terminal utilities for CLI
+ * - ANSI color codes
+ * - Interactive prompts
+ * - Table formatting
+ */
+
+import * as readline from 'readline';
+
+// ANSI color codes
+export const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  underline: '\x1b[4m',
+
+  // Foreground colors
+  black: '\x1b[30m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+
+  // Background colors
+  bgBlack: '\x1b[40m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+  bgMagenta: '\x1b[45m',
+  bgCyan: '\x1b[46m',
+  bgWhite: '\x1b[47m',
+};
+
+/**
+ * Apply color to text
+ * @param {string} text
+ * @param {...string} colorCodes
+ * @returns {string}
+ */
+export function colorize(text, ...colorCodes) {
+  return `${colorCodes.join('')}${text}${colors.reset}`;
+}
+
+/**
+ * Print colored text
+ * @param {string} text
+ * @param {...string} colorCodes
+ */
+export function print(text, ...colorCodes) {
+  if (colorCodes.length > 0) {
+    console.log(colorize(text, ...colorCodes));
+  } else {
+    console.log(text);
+  }
+}
+
+/**
+ * Print error message
+ * @param {string} message
+ */
+export function printError(message) {
+  console.error(colorize(`Error: ${message}`, colors.red));
+}
+
+/**
+ * Print success message
+ * @param {string} message
+ */
+export function printSuccess(message) {
+  console.log(colorize(`✓ ${message}`, colors.green));
+}
+
+/**
+ * Print warning message
+ * @param {string} message
+ */
+export function printWarning(message) {
+  console.log(colorize(`⚠ ${message}`, colors.yellow));
+}
+
+/**
+ * Print info message
+ * @param {string} message
+ */
+export function printInfo(message) {
+  console.log(colorize(`ℹ ${message}`, colors.cyan));
+}
+
+/**
+ * Print a section header
+ * @param {string} title
+ */
+export function printHeader(title) {
+  console.log();
+  console.log(colorize(title, colors.bold, colors.cyan));
+  console.log(colorize('─'.repeat(title.length + 4), colors.dim));
+}
+
+/**
+ * Print a step status
+ * @param {number} step
+ * @param {string} name
+ * @param {string} status - 'completed' | 'in_progress' | 'pending'
+ */
+export function printStep(step, name, status) {
+  const statusIcons = {
+    completed: colorize('✓', colors.green),
+    in_progress: colorize('●', colors.yellow),
+    pending: colorize('○', colors.dim),
+  };
+  const statusColors = {
+    completed: colors.green,
+    in_progress: colors.yellow,
+    pending: colors.dim,
+  };
+  
+  const icon = statusIcons[status] || statusIcons.pending;
+  const color = statusColors[status] || colors.dim;
+  
+  console.log(`  ${icon} ${colorize(`步骤 ${step}:`, colors.bold)} ${colorize(name, color)}`);
+}
+
+/**
+ * Simple confirm prompt
+ * @param {string} message
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(message) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(colorize(`${message} (y/N): `, colors.cyan), (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    });
+  });
+}
+
+/**
+ * Prompt for text input
+ * @param {string} message
+ * @param {string} defaultValue
+ * @returns {Promise<string>}
+ */
+export async function prompt(message, defaultValue = '') {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const defaultHint = defaultValue ? colorize(` [${defaultValue}]`, colors.dim) : '';
+
+  return new Promise((resolve) => {
+    rl.question(colorize(`${message}${defaultHint}: `, colors.cyan), (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+/**
+ * Interactive single select prompt
+ * @param {Object} options
+ * @param {string} options.message
+ * @param {Array<{name: string, value: any, description?: string}>} options.choices
+ * @returns {Promise<any>}
+ */
+export async function select({ message, choices }) {
+  return new Promise((resolve) => {
+    let cursor = 0;
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    readline.emitKeypressEvents(process.stdin, rl);
+
+    const render = () => {
+      process.stdout.write('\x1b[2J\x1b[H');
+
+      console.log(colorize(message, colors.bold, colors.cyan));
+      console.log(colorize('(Use arrow keys to navigate, enter to select)', colors.dim));
+      console.log();
+
+      choices.forEach((choice, index) => {
+        const isCursor = cursor === index;
+        const pointer = isCursor ? colorize('❯', colors.cyan) : ' ';
+        const name = isCursor ? colorize(choice.name, colors.bold) : choice.name;
+
+        console.log(`${pointer} ${name}`);
+
+        if (choice.description && isCursor) {
+          console.log(colorize(`  ${choice.description}`, colors.gray));
+        }
+      });
+    };
+
+    const cleanup = () => {
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(false);
+      }
+      rl.close();
+    };
+
+    const handleKeypress = (str, key) => {
+      if (!key) return;
+
+      if (key.name === 'up' || key.name === 'k') {
+        cursor = cursor > 0 ? cursor - 1 : choices.length - 1;
+        render();
+      } else if (key.name === 'down' || key.name === 'j') {
+        cursor = cursor < choices.length - 1 ? cursor + 1 : 0;
+        render();
+      } else if (key.name === 'return') {
+        cleanup();
+        process.stdin.removeListener('keypress', handleKeypress);
+        process.stdout.write('\x1b[2J\x1b[H');
+        resolve(choices[cursor].value);
+      } else if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+        cleanup();
+        process.stdin.removeListener('keypress', handleKeypress);
+        process.stdout.write('\x1b[2J\x1b[H');
+        process.exit(0);
+      }
+    };
+
+    process.stdin.on('keypress', handleKeypress);
+    render();
+  });
+}
+
+/**
+ * Format a table for terminal output
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @param {Object} options
+ */
+export function printTable(headers, rows, options = {}) {
+  const { padding = 2 } = options;
+  
+  // Calculate column widths
+  const colWidths = headers.map((h, i) => {
+    const maxRowWidth = Math.max(...rows.map(r => (r[i] || '').length));
+    return Math.max(h.length, maxRowWidth);
+  });
+
+  // Print header
+  const headerRow = headers.map((h, i) => h.padEnd(colWidths[i])).join(' '.repeat(padding));
+  console.log(colorize(headerRow, colors.bold));
+  console.log(colorize('─'.repeat(headerRow.length), colors.dim));
+
+  // Print rows
+  rows.forEach(row => {
+    const rowStr = row.map((cell, i) => (cell || '').padEnd(colWidths[i])).join(' '.repeat(padding));
+    console.log(rowStr);
+  });
+}
+
+/**
+ * Create a simple spinner
+ * @param {string} message
+ * @returns {{stop: (success?: boolean, finalMessage?: string) => void}}
+ */
+export function spinner(message) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  
+  const interval = setInterval(() => {
+    process.stdout.write(`\r${colorize(frames[i], colors.cyan)} ${message}`);
+    i = (i + 1) % frames.length;
+  }, 80);
+
+  return {
+    stop: (success = true, finalMessage = message) => {
+      clearInterval(interval);
+      const icon = success ? colorize('✓', colors.green) : colorize('✗', colors.red);
+      process.stdout.write(`\r${icon} ${finalMessage}\n`);
+    }
+  };
+}