@macpaw/cctk 1.0.0-beta.1

package/templates/claude/scripts/generate-catalogs.cjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Generate skill and command catalogs for Claude Code.
+ * Usage:
+ *   node generate-catalogs.cjs --skills     # Skills catalog only
+ *   node generate-catalogs.cjs --commands   # Commands catalog only
+ *   node generate-catalogs.cjs --json       # Output as JSON
+ *   node generate-catalogs.cjs              # Both catalogs (YAML-like)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Resolves from cwd — script must be invoked from project root
+const CLAUDE_DIR = path.resolve(process.cwd(), '.claude');
+const SKILLS_DIR = path.join(CLAUDE_DIR, 'skills');
+const COMMANDS_DIR = path.join(CLAUDE_DIR, 'commands');
+
+const CATEGORY_KEYWORDS = {
+  'ai-ml': ['ai-', 'gemini', 'multimodal', 'adk'],
+  frontend: ['frontend', 'ui', 'design', 'aesthetic', 'threejs'],
+  backend: ['backend', 'auth', 'payment'],
+  infrastructure: ['devops', 'docker', 'cloudflare', 'gcloud'],
+  database: ['database', 'mongodb', 'postgresql', 'sql'],
+  'dev-tools': ['mcp', 'skill-creator', 'claude-code', 'repomix', 'docs-seeker'],
+  multimedia: ['media', 'chrome-devtools'],
+  frameworks: ['web-frameworks', 'mobile', 'shopify'],
+  utilities: ['debug', 'problem', 'code-review', 'planning', 'research', 'sequential'],
+};
+
+const CATEGORY_NAMES = {
+  'ai-ml': 'AI & Machine Learning',
+  frontend: 'Frontend & Design',
+  backend: 'Backend Development',
+  infrastructure: 'Infrastructure & DevOps',
+  database: 'Database & Storage',
+  'dev-tools': 'Development Tools',
+  multimedia: 'Multimedia & Processing',
+  frameworks: 'Frameworks & Platforms',
+  utilities: 'Utilities & Helpers',
+  other: 'Other',
+};
+
+const COMMAND_CATEGORY_NAMES = {
+  core: 'Core Commands',
+  bootstrap: 'Bootstrap Commands',
+  content: 'Content Creation',
+  design: 'Design Commands',
+  docs: 'Documentation',
+  fix: 'Fix & Debug',
+  git: 'Git Commands',
+  integrate: 'Integrations',
+  plan: 'Planning',
+  review: 'Code Review',
+  scout: 'Scout Commands',
+  skill: 'Skill Management',
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Extract YAML frontmatter from markdown content.
+ * Parses simple key: value pairs (no nested YAML).
+ */
+function extractFrontmatter(content) {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const result = {};
+  for (const line of match[1].split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    let value = line.slice(colonIdx + 1).trim();
+    // Strip surrounding quotes (single or double)
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * Recursively find files matching a pattern.
+ */
+function findFiles(dir, filename) {
+  if (!fs.existsSync(dir)) return [];
+
+  const results = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true, recursive: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+
+    const matchesPattern =
+      typeof filename === 'string' ? entry.name === filename : filename.test(entry.name);
+
+    if (matchesPattern) {
+      // parentPath added in Node 20.12, entry.path is the legacy fallback
+      const fullPath = path.join(entry.parentPath || entry.path, entry.name);
+      results.push(fullPath);
+    }
+  }
+  return results.sort();
+}
+
+/**
+ * Group array of objects by a key.
+ */
+function groupBy(items, key) {
+  const groups = {};
+  for (const item of items) {
+    const group = item[key] || 'other';
+    if (!groups[group]) groups[group] = [];
+    groups[group].push(item);
+  }
+  return groups;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SKILL SCANNING
+// ═══════════════════════════════════════════════════════════════════════════
+
+function categorizeSkill(name) {
+  const lower = name.toLowerCase();
+  for (const [category, keywords] of Object.entries(CATEGORY_KEYWORDS)) {
+    if (keywords.some((kw) => lower.includes(kw))) return category;
+  }
+  return 'other';
+}
+
+function scanSkills() {
+  const files = findFiles(SKILLS_DIR, 'SKILL.md');
+  const skills = [];
+
+  for (const filePath of files) {
+    try {
+      const skillDir = path.dirname(filePath);
+      let skillName = path.basename(skillDir);
+
+      // Skip template
+      if (skillName === 'template-skill') continue;
+
+      // Handle nested skills (parent/child)
+      const parentDir = path.basename(path.dirname(skillDir));
+      if (parentDir !== 'skills') {
+        skillName = `${parentDir}/${skillName}`;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const frontmatter = extractFrontmatter(content);
+      const description = frontmatter.description || '';
+      const category = categorizeSkill(skillName);
+      const hasScripts = fs.existsSync(path.join(skillDir, 'scripts'));
+      const hasReferences = fs.existsSync(path.join(skillDir, 'references'));
+      const relPath = path.relative(SKILLS_DIR, filePath);
+
+      skills.push({ name: skillName, path: relPath, description, category, hasScripts, hasReferences });
+    } catch (err) {
+      process.stderr.write(`Warning: Failed to read ${filePath}: ${err.message}\n`);
+    }
+  }
+
+  return skills;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMMAND SCANNING
+// ═══════════════════════════════════════════════════════════════════════════
+
+function scanCommands() {
+  const files = findFiles(COMMANDS_DIR, /\.md$/);
+  const commands = [];
+
+  for (const filePath of files) {
+    try {
+      const relPath = path.relative(COMMANDS_DIR, filePath);
+      const parsed = path.parse(relPath);
+      const parts = [...parsed.dir.split(path.sep).filter(Boolean), parsed.name];
+      const commandName = '/ck:' + parts.join(':');
+
+      const content = fs.readFileSync(filePath, 'utf8');
+      const frontmatter = extractFrontmatter(content);
+      const rawDesc = frontmatter.description || '';
+      const powerLevel = (rawDesc.match(/⚡/g) || []).length;
+      const description = rawDesc.replace(/⚡/g, '').trim();
+      const argumentHint = frontmatter['argument-hint'] || '';
+      const category = parts.length > 1 ? parts[0] : 'core';
+
+      commands.push({ name: commandName, path: relPath, description, argumentHint, powerLevel, category });
+    } catch (err) {
+      process.stderr.write(`Warning: Failed to read ${filePath}: ${err.message}\n`);
+    }
+  }
+
+  return commands;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// OUTPUT FORMATTING
+// ═══════════════════════════════════════════════════════════════════════════
+
+function formatSkillsCatalog(skills) {
+  const today = new Date().toISOString().slice(0, 10);
+  const categories = groupBy(skills, 'category');
+
+  const lines = [
+    'metadata:',
+    '  title: Skills Catalog',
+    '  description: Auto-generated catalog of all available skills',
+    `  last_updated: ${today}`,
+    `  total_skills: ${skills.length}`,
+    '',
+    'categories:',
+  ];
+
+  for (const [key, label] of Object.entries(CATEGORY_NAMES)) {
+    lines.push(`  ${key}: "${label}"`);
+  }
+
+  lines.push('', 'skills:');
+
+  for (const [cat, catSkills] of Object.entries(categories).sort()) {
+    const catName = CATEGORY_NAMES[cat] || cat;
+    lines.push(`  # ${catName}`);
+    lines.push(`  ${cat}:`);
+
+    for (const skill of catSkills.sort((a, b) => a.name.localeCompare(b.name))) {
+      const scripts = skill.hasScripts ? ' [scripts]' : '';
+      const refs = skill.hasReferences ? ' [refs]' : '';
+      lines.push(`    - name: ${skill.name}`);
+      lines.push(`      description: "${skill.description}"`);
+      lines.push(`      path: ${skill.path}`);
+      if (scripts || refs) lines.push(`      features:${scripts}${refs}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function formatCommandsCatalog(commands) {
+  const today = new Date().toISOString().slice(0, 10);
+  const categories = groupBy(commands, 'category');
+
+  const lines = [
+    'metadata:',
+    '  title: Commands Catalog',
+    '  description: Auto-generated catalog of all available commands',
+    `  last_updated: ${today}`,
+    `  total_commands: ${commands.length}`,
+    '',
+    'categories:',
+  ];
+
+  for (const [key, label] of Object.entries(COMMAND_CATEGORY_NAMES)) {
+    lines.push(`  ${key}: "${label}"`);
+  }
+
+  lines.push('', 'commands:');
+
+  for (const [cat, catCmds] of Object.entries(categories).sort()) {
+    const catName = COMMAND_CATEGORY_NAMES[cat] || cat;
+    lines.push(`  # ${catName}`);
+    lines.push(`  ${cat}:`);
+
+    for (const cmd of catCmds.sort((a, b) => a.name.localeCompare(b.name))) {
+      const power = cmd.powerLevel > 0 ? ' ' + '⚡'.repeat(cmd.powerLevel) : '';
+      lines.push(`    - name: ${cmd.name}${power}`);
+      lines.push(`      description: "${cmd.description}"`);
+      if (cmd.argumentHint) lines.push(`      argument_hint: "${cmd.argumentHint}"`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN
+// ═══════════════════════════════════════════════════════════════════════════
+
+function main() {
+  const args = process.argv.slice(2);
+  const showSkills = args.includes('--skills');
+  const showCommands = args.includes('--commands');
+  const jsonOutput = args.includes('--json');
+  const showBoth = !showSkills && !showCommands;
+
+  if (jsonOutput) {
+    const result = {};
+    if (showCommands || showBoth) result.commands = scanCommands();
+    if (showSkills || showBoth) result.skills = scanSkills();
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (showCommands || showBoth) {
+    if (showBoth) console.log('# === COMMANDS CATALOG ===');
+    const commands = scanCommands();
+    console.log(formatCommandsCatalog(commands));
+  }
+
+  if (showSkills || showBoth) {
+    if (showBoth) console.log('\n# === SKILLS CATALOG ===');
+    const skills = scanSkills();
+    console.log(formatSkillsCatalog(skills));
+  }
+}
+
+main();

package/templates/claude/scripts/registry.json

@@ -0,0 +1,48 @@
+{
+  "name": "scripts",
+  "version": "1.0.0",
+  "items": [
+    {
+      "name": "catalog-generators",
+      "title": "Catalog Generators",
+      "description": "Generate skill and command catalogs for Claude Code",
+      "files": ["scripts/generate-catalogs.cjs"],
+      "dependencies": {},
+      "meta": {
+        "runtime": "node"
+      }
+    },
+    {
+      "name": "worktree",
+      "title": "Git Worktree Manager",
+      "description": "Git worktree management utilities",
+      "files": ["scripts/worktree.cjs"],
+      "dependencies": {},
+      "meta": {
+        "runtime": "node"
+      }
+    },
+    {
+      "name": "plan-manager",
+      "title": "Plan Manager",
+      "description": "Set and manage active development plans",
+      "files": ["scripts/set-active-plan.cjs"],
+      "dependencies": {
+        "hooks": ["core-libs"]
+      },
+      "meta": {
+        "runtime": "node"
+      }
+    },
+    {
+      "name": "validate-docs",
+      "title": "Documentation Validator",
+      "description": "Validate documentation files",
+      "files": ["scripts/validate-docs.cjs"],
+      "dependencies": {},
+      "meta": {
+        "runtime": "node"
+      }
+    }
+  ]
+}

package/templates/claude/scripts/set-active-plan.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Update session state with new active plan
+ *
+ * Usage: node .claude/scripts/set-active-plan.cjs <plan-path>
+ *
+ * This script updates the session temp file with the new active plan path,
+ * allowing subagents to receive the latest plan context via SubagentStart hook.
+ *
+ * The session temp file (/tmp/cctk-session-{id}.json) is the source of truth
+ * for plan context within a session. Env vars ($CCTK_ACTIVE_PLAN) are just
+ * the initial snapshot from session start.
+ */
+
+const { writeSessionState, readSessionState } = require('../hooks/lib/cctk-config-utils.cjs');
+
+const sessionId = process.env.CCTK_SESSION_ID;
+const newPlan = process.argv[2];
+
+if (!newPlan) {
+  console.error('Error: Plan path required');
+  console.log('Usage: node .claude/scripts/set-active-plan.cjs <plan-path>');
+  console.log('Example: node .claude/scripts/set-active-plan.cjs plans/251207-1030-feature-name');
+  process.exit(1);
+}
+
+if (!sessionId) {
+  console.warn('Warning: CCTK_SESSION_ID not set - session state will not persist');
+  console.log(`Would set active plan to: ${newPlan}`);
+  process.exit(0);
+}
+
+const current = readSessionState(sessionId) || {};
+const success = writeSessionState(sessionId, {
+  ...current,
+  activePlan: newPlan,
+  timestamp: Date.now(),
+});
+
+if (success) {
+  console.log(`Active plan set to: ${newPlan}`);
+} else {
+  console.error('Failed to update session state');
+  process.exit(1);
+}