@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/plans-kanban/scripts/lib/plan-scanner.cjs

@@ -0,0 +1,277 @@
+/**
+ * Plan Scanner Utility
+ * Recursively discovers plan directories and aggregates metadata for dashboard view
+ *
+ * @module plan-scanner
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parsePlanTable } = require('./plan-parser.cjs');
+const {
+  extractPlanMetadata,
+  generateTimelineStats,
+  generateActivityHeatmap,
+  normalizeStatus,
+} = require('./plan-metadata-extractor.cjs');
+
+/**
+ * Calculate progress statistics from phases array
+ * @param {Array<{status: string}>} phases - Array of phase objects with status
+ * @returns {{total: number, completed: number, inProgress: number, pending: number, percentage: number}}
+ */
+function calculateProgress(phases) {
+  if (!phases || phases.length === 0) {
+    return { total: 0, completed: 0, inProgress: 0, pending: 0, percentage: 0 };
+  }
+
+  const stats = {
+    total: phases.length,
+    completed: 0,
+    inProgress: 0,
+    pending: 0,
+  };
+
+  for (const phase of phases) {
+    const status = (phase.status || '').toLowerCase();
+
+    if (status === 'completed' || status === 'done') {
+      stats.completed++;
+    } else if (status === 'in-progress' || status === 'in progress' || status === 'active') {
+      stats.inProgress++;
+    } else {
+      stats.pending++;
+    }
+  }
+
+  stats.percentage = stats.total > 0 ? Math.round((stats.completed / stats.total) * 100) : 0;
+
+  return stats;
+}
+
+/**
+ * Parse plan name from directory name (strip date prefix)
+ * @param {string} dirName - Directory name like "251211-feature-name"
+ * @returns {string} - Human readable name like "Feature Name"
+ */
+function parsePlanName(dirName) {
+  // Remove date prefix: YYMMDD-, YYYYMMDD-, YYMMDD-HHMM-, YYYYMMDD-HHMM-
+  const withoutDate = dirName.replace(/^\d{6,8}(-\d{4})?-/, '');
+
+  // Convert kebab-case to Title Case
+  return withoutDate
+    .split('-')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Derive overall status from phase statistics or header status
+ * @param {{completed: number, inProgress: number, pending: number, total: number}} stats
+ * @param {string} [headerStatus] - Optional status from plan header (e.g., **Status:** completed)
+ * @returns {'completed' | 'in-progress' | 'in-review' | 'cancelled' | 'pending'}
+ */
+function deriveStatus(stats, headerStatus) {
+  // If header explicitly defines status, use it (normalized)
+  if (headerStatus) {
+    const normalized = headerStatus.toLowerCase().trim();
+
+    if (normalized.includes('complete') || normalized.includes('done')) {
+      return 'completed';
+    }
+    if (normalized.includes('review')) {
+      return 'in-review';
+    }
+    if (normalized.includes('cancel')) {
+      return 'cancelled';
+    }
+    if (normalized.includes('progress') || normalized.includes('active')) {
+      return 'in-progress';
+    }
+    if (normalized.includes('pending') || normalized.includes('todo') || normalized.includes('planned')) {
+      return 'pending';
+    }
+  }
+
+  // Otherwise derive from phase stats
+  if (stats.completed === stats.total && stats.total > 0) {
+    return 'completed';
+  }
+  if (stats.inProgress > 0 || stats.completed > 0) {
+    return 'in-progress';
+  }
+
+  return 'pending';
+}
+
+/**
+ * Get metadata for a single plan
+ * @param {string} planFilePath - Absolute path to plan.md
+ * @returns {Object|null} - Plan metadata object or null if invalid
+ */
+function getPlanMetadata(planFilePath) {
+  try {
+    if (!fs.existsSync(planFilePath)) {
+      return null;
+    }
+
+    const directory = path.dirname(planFilePath);
+    const dirName = path.basename(directory);
+    const stats = fs.statSync(planFilePath);
+
+    // Parse phases from plan table
+    const phases = parsePlanTable(planFilePath);
+    const progress = calculateProgress(phases);
+
+    // Extract rich metadata (dates, effort, priority, etc.)
+    const richMeta = extractPlanMetadata(planFilePath);
+
+    return {
+      id: dirName,
+      name: parsePlanName(dirName),
+      path: planFilePath,
+      directory,
+      phases: progress,
+      progress: progress.percentage,
+      lastModified: stats.mtime.toISOString(),
+      // Use frontmatter status if hasFrontmatter (already normalized), otherwise derive from phases
+      status:
+        richMeta.hasFrontmatter && richMeta.headerStatus
+          ? normalizeStatus(richMeta.headerStatus)
+          : deriveStatus(progress, richMeta.headerStatus),
+      // Rich metadata
+      createdDate: richMeta.createdDate,
+      completedDate: richMeta.completedDate,
+      durationDays: richMeta.durationDays,
+      durationFormatted: richMeta.durationFormatted,
+      totalEffortHours: richMeta.totalEffortHours,
+      totalEffortFormatted: richMeta.totalEffortFormatted,
+      priority: richMeta.priority,
+      issue: richMeta.issue,
+      branch: richMeta.branch,
+      // New frontmatter fields
+      description: richMeta.description,
+      tags: richMeta.tags || [],
+      assignee: richMeta.assignee,
+      title: richMeta.title,
+    };
+  } catch (error) {
+    console.error(`[plan-scanner] Error reading plan: ${planFilePath}`, error.message);
+
+    return null;
+  }
+}
+
+/**
+ * Check if path is safe (within allowed directory, no traversal)
+ * @param {string} targetPath - Path to check
+ * @param {string} baseDir - Allowed base directory
+ * @returns {boolean}
+ */
+function isPathSafe(targetPath, baseDir) {
+  const resolved = path.resolve(targetPath);
+  const resolvedBase = path.resolve(baseDir);
+
+  // Must start with base directory
+  if (!resolved.startsWith(resolvedBase)) {
+    return false;
+  }
+
+  // No null bytes
+  if (targetPath.includes('\0')) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Scan directory for plan.md files
+ * @param {string} plansDir - Root directory to scan (e.g., ./plans)
+ * @param {Object} options - Scan options
+ * @param {number} options.maxDepth - Maximum recursion depth (default: 2)
+ * @param {string[]} options.exclude - Directory names to exclude (default: ['node_modules', '.git', 'templates', 'reports', 'research'])
+ * @returns {Array<Object>} - Array of plan metadata objects sorted by lastModified desc
+ */
+function scanPlans(plansDir, options = {}) {
+  const { maxDepth = 2, exclude = ['node_modules', '.git', 'templates', 'reports', 'research'] } = options;
+
+  const resolvedBase = path.resolve(plansDir);
+  const plans = [];
+
+  /**
+   * Recursive directory scanner
+   * @param {string} dir - Current directory
+   * @param {number} depth - Current depth
+   */
+  function scanDir(dir, depth) {
+    if (depth > maxDepth) return;
+
+    // Security: validate path
+    if (!isPathSafe(dir, resolvedBase)) {
+      console.error(`[plan-scanner] Path traversal blocked: ${dir}`);
+
+      return;
+    }
+
+    let entries;
+
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (error) {
+      console.error(`[plan-scanner] Cannot read directory: ${dir}`, error.message);
+
+      return;
+    }
+
+    for (const entry of entries) {
+      // Skip excluded directories
+      if (exclude.includes(entry.name)) continue;
+
+      // Skip hidden directories
+      if (entry.name.startsWith('.')) continue;
+
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Check for plan.md in this directory
+        const planFile = path.join(fullPath, 'plan.md');
+
+        if (fs.existsSync(planFile)) {
+          const metadata = getPlanMetadata(planFile);
+
+          if (metadata) {
+            plans.push(metadata);
+          }
+        } else {
+          // Recurse into subdirectory
+          scanDir(fullPath, depth + 1);
+        }
+      }
+    }
+  }
+
+  // Start scanning
+  if (fs.existsSync(resolvedBase)) {
+    scanDir(resolvedBase, 0);
+  } else {
+    console.error(`[plan-scanner] Plans directory not found: ${plansDir}`);
+  }
+
+  // Sort by lastModified descending (newest first)
+  plans.sort((a, b) => new Date(b.lastModified) - new Date(a.lastModified));
+
+  return plans;
+}
+
+module.exports = {
+  scanPlans,
+  getPlanMetadata,
+  calculateProgress,
+  parsePlanName,
+  deriveStatus,
+  isPathSafe,
+  // Re-export timeline helpers
+  generateTimelineStats,
+  generateActivityHeatmap,
+};

package/templates/claude/skills/plans-kanban/scripts/lib/port-finder.cjs

@@ -0,0 +1,49 @@
+/**
+ * Port finder utility for plans-kanban server
+ * Uses port range 3500-3550 to avoid conflicts with markdown-novel-viewer
+ */
+
+const net = require('node:net');
+
+const DEFAULT_PORT = 3500;
+const PORT_RANGE_END = 3550;
+
+/**
+ * Check if a port is available
+ * @param {number} port - Port to check
+ * @returns {Promise<boolean>} - True if available
+ */
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port);
+  });
+}
+
+/**
+ * Find first available port in range
+ * @param {number} startPort - Starting port (default: 3500)
+ * @returns {Promise<number>} - Available port
+ * @throws {Error} - If no port available in range
+ */
+async function findAvailablePort(startPort = DEFAULT_PORT) {
+  for (let port = startPort; port <= PORT_RANGE_END; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  throw new Error(`No available port in range ${startPort}-${PORT_RANGE_END}`);
+}
+
+module.exports = {
+  isPortAvailable,
+  findAvailablePort,
+  DEFAULT_PORT,
+  PORT_RANGE_END,
+};

package/templates/claude/skills/plans-kanban/scripts/lib/process-mgr.cjs

@@ -0,0 +1,128 @@
+/**
+ * Process manager for plans-kanban server
+ * Handles PID files and server lifecycle
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Cross-platform temp directory for PID files
+const PID_DIR = os.tmpdir();
+const PID_PREFIX = 'plans-kanban-';
+
+/**
+ * Get PID file path for a port
+ * @param {number} port - Server port
+ * @returns {string} - PID file path
+ */
+function getPidFilePath(port) {
+  return path.join(PID_DIR, `${PID_PREFIX}${port}.pid`);
+}
+
+/**
+ * Write PID file for running server
+ * @param {number} port - Server port
+ * @param {number} pid - Process ID
+ */
+function writePidFile(port, pid) {
+  fs.writeFileSync(getPidFilePath(port), String(pid));
+}
+
+/**
+ * Read PID from file
+ * @param {number} port - Server port
+ * @returns {number|null} - PID or null if not found
+ */
+function readPidFile(port) {
+  const pidPath = getPidFilePath(port);
+  if (fs.existsSync(pidPath)) {
+    return parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+  }
+  return null;
+}
+
+/**
+ * Remove PID file
+ * @param {number} port - Server port
+ */
+function removePidFile(port) {
+  const pidPath = getPidFilePath(port);
+  if (fs.existsSync(pidPath)) {
+    fs.unlinkSync(pidPath);
+  }
+}
+
+/**
+ * Find all running kanban server instances
+ * @returns {Array<{port: number, pid: number}>}
+ */
+function findRunningInstances() {
+  const instances = [];
+  const files = fs.readdirSync(PID_DIR);
+
+  for (const file of files) {
+    if (file.startsWith(PID_PREFIX) && file.endsWith('.pid')) {
+      const port = parseInt(file.replace(PID_PREFIX, '').replace('.pid', ''), 10);
+      const pid = readPidFile(port);
+      if (pid) {
+        try {
+          process.kill(pid, 0);
+          instances.push({ port, pid });
+        } catch {
+          removePidFile(port);
+        }
+      }
+    }
+  }
+
+  return instances;
+}
+
+/**
+ * Stop all running kanban servers
+ * @returns {number} - Number of servers stopped
+ */
+function stopAllServers() {
+  const instances = findRunningInstances();
+  let stopped = 0;
+
+  for (const { port, pid } of instances) {
+    try {
+      process.kill(pid, 'SIGTERM');
+      removePidFile(port);
+      stopped++;
+    } catch {
+      removePidFile(port);
+    }
+  }
+
+  return stopped;
+}
+
+/**
+ * Setup graceful shutdown handlers
+ * @param {number} port - Server port
+ * @param {Function} cleanup - Additional cleanup function
+ */
+function setupShutdownHandlers(port, cleanup) {
+  const handler = () => {
+    if (cleanup) cleanup();
+    removePidFile(port);
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', handler);
+  process.on('SIGINT', handler);
+}
+
+module.exports = {
+  getPidFilePath,
+  writePidFile,
+  readPidFile,
+  removePidFile,
+  findRunningInstances,
+  stopAllServers,
+  setupShutdownHandlers,
+  PID_PREFIX
+};

package/templates/claude/skills/plans-kanban/scripts/server.cjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * Plans Kanban Server
+ * Background HTTP server for plans dashboard with progress tracking
+ *
+ * Usage:
+ *   node server.cjs --dir ./plans [--port 3500] [--open] [--stop] [--host 0.0.0.0]
+ *
+ * Options:
+ *   --dir <path>    Path to plans directory
+ *   --port <number> Server port (default: 3500, auto-increment if busy)
+ *   --host <addr>   Host to bind (default: localhost, use 0.0.0.0 for all interfaces)
+ *   --open          Auto-open browser after start
+ *   --stop          Stop all running kanban servers
+ *   --background    Run in background (detached) - legacy mode
+ *   --foreground    Run in foreground (for CC background tasks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+
+const { findAvailablePort, DEFAULT_PORT } = require('./lib/port-finder.cjs');
+const { writePidFile, stopAllServers, setupShutdownHandlers, findRunningInstances } = require('./lib/process-mgr.cjs');
+const { createHttpServer } = require('./lib/http-server.cjs');
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(argv) {
+  const args = {
+    dir: null,
+    port: DEFAULT_PORT,
+    host: 'localhost',
+    open: false,
+    stop: false,
+    background: false,
+    foreground: false,
+    isChild: false
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if ((arg === '--dir' || arg === '--plans') && argv[i + 1]) {
+      args.dir = argv[++i];
+    } else if (arg === '--port' && argv[i + 1]) {
+      args.port = parseInt(argv[++i], 10);
+    } else if (arg === '--host' && argv[i + 1]) {
+      args.host = argv[++i];
+    } else if (arg === '--open') {
+      args.open = true;
+    } else if (arg === '--stop') {
+      args.stop = true;
+    } else if (arg === '--background') {
+      args.background = true;
+    } else if (arg === '--foreground') {
+      args.foreground = true;
+    } else if (arg === '--child') {
+      args.isChild = true;
+    } else if (!arg.startsWith('--') && !args.dir) {
+      args.dir = arg;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Get local network IP address for remote access
+ */
+function getLocalIP() {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const iface of interfaces[name]) {
+      if (iface.family === 'IPv4' && !iface.internal) {
+        return iface.address;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Build URL with network URL for remote access
+ */
+function buildUrl(host, port, plansDir) {
+  const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+  const urlPath = `/kanban?dir=${encodeURIComponent(plansDir)}`;
+  const url = `http://${displayHost}:${port}${urlPath}`;
+
+  let networkUrl = null;
+  if (host === '0.0.0.0') {
+    const localIP = getLocalIP();
+    if (localIP) {
+      networkUrl = `http://${localIP}:${port}${urlPath}`;
+    }
+  }
+
+  return { url, networkUrl };
+}
+
+/**
+ * Open browser (macOS)
+ */
+function openBrowser(url) {
+  try {
+    execSync(`open "${url}"`, { stdio: 'ignore' });
+  } catch {
+    // Ignore browser open errors
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const args = parseArgs(process.argv);
+  const cwd = process.cwd();
+  const assetsDir = path.join(__dirname, '..', 'assets');
+
+  // Handle --stop
+  if (args.stop) {
+    const instances = findRunningInstances();
+    if (instances.length === 0) {
+      console.log('No kanban server running to stop');
+      process.exit(0);
+    }
+    const stopped = stopAllServers();
+    console.log(`Stopped ${stopped} kanban server(s)`);
+    process.exit(0);
+  }
+
+  // Validate input
+  if (!args.dir) {
+    console.error('Error: --dir argument required');
+    console.error('Usage:');
+    console.error('  node server.cjs --dir <plans-dir> [--port 3500] [--open]');
+    process.exit(1);
+  }
+
+  // Resolve plans directory
+  const plansDir = path.isAbsolute(args.dir) ? args.dir : path.resolve(cwd, args.dir);
+
+  if (!fs.existsSync(plansDir) || !fs.statSync(plansDir).isDirectory()) {
+    console.error(`Error: Directory not found: ${args.dir}`);
+    process.exit(1);
+  }
+
+  // Background mode - spawn child and exit (legacy mode for manual runs)
+  // Skip if --foreground is set (for Claude Code background tasks)
+  if (args.background && !args.foreground && !args.isChild) {
+    const childArgs = ['--dir', plansDir, '--port', String(args.port), '--host', args.host, '--child'];
+    if (args.open) childArgs.push('--open');
+
+    const child = spawn(process.execPath, [__filename, ...childArgs], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: cwd
+    });
+    child.unref();
+
+    await new Promise(r => setTimeout(r, 500));
+
+    const instances = findRunningInstances();
+    const instance = instances.find(i => i.port >= args.port);
+    const port = instance ? instance.port : args.port;
+
+    const { url, networkUrl } = buildUrl(args.host, port, plansDir);
+
+    const result = {
+      success: true,
+      url,
+      dir: plansDir,
+      port,
+      host: args.host,
+      mode: 'kanban'
+    };
+    if (networkUrl) result.networkUrl = networkUrl;
+
+    console.log(JSON.stringify(result));
+    process.exit(0);
+  }
+
+  // Find available port
+  const port = await findAvailablePort(args.port);
+  if (port !== args.port) {
+    console.error(`Port ${args.port} in use, using ${port}`);
+  }
+
+  // Determine allowed directories
+  const allowedDirs = [assetsDir, cwd, plansDir];
+
+  // Create server
+  const server = createHttpServer({
+    assetsDir,
+    allowedDirs,
+    plansDir
+  });
+
+  // Start server
+  server.listen(port, args.host, () => {
+    const { url, networkUrl } = buildUrl(args.host, port, plansDir);
+
+    writePidFile(port, process.pid);
+    setupShutdownHandlers(port, () => server.close());
+
+    // Output for CLI/command integration
+    // In foreground mode (CC background task), always output JSON
+    if (args.foreground || args.isChild || process.env.CLAUDE_COMMAND) {
+      const result = {
+        success: true,
+        url,
+        dir: plansDir,
+        port,
+        host: args.host,
+        mode: 'kanban'
+      };
+      if (networkUrl) result.networkUrl = networkUrl;
+      console.log(JSON.stringify(result));
+    } else {
+      console.log(`\nPlans Kanban Dashboard`);
+      console.log(`${'─'.repeat(40)}`);
+      console.log(`URL: ${url}`);
+      if (networkUrl) {
+        console.log(`Network: ${networkUrl}`);
+      }
+      console.log(`Plans: ${plansDir}`);
+      console.log(`Port: ${port}`);
+      console.log(`Host: ${args.host}`);
+      console.log(`\nPress Ctrl+C to stop\n`);
+    }
+
+    if (args.open) {
+      openBrowser(url);
+    }
+  });
+
+  server.on('error', (err) => {
+    console.error(`Server error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+main().catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});