cc-dev-template 0.1.31 → 0.1.33

package/src/scripts/adr-list.js

@@ -1,298 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * adr-list.js - List ADRs with optional filtering by tags and status
- *
- * This CLI script scans all YAML ADR files in the project's .claude/adrs/
- * and returns their metadata, with optional filtering capabilities. Designed
- * to support progressive ADR filtering (per ADR-007) by providing descriptions
- * without full content.
- *
- * Usage:
- *   node ~/.claude/scripts/adr-list.js                           # All ADRs
- *   node ~/.claude/scripts/adr-list.js --tags=architecture       # Filter by single tag
- *   node ~/.claude/scripts/adr-list.js --tags=agents,planning    # Filter by multiple tags (OR logic)
- *   node ~/.claude/scripts/adr-list.js --status=Accepted         # Filter by status
- *   node ~/.claude/scripts/adr-list.js --tags=adrs --status=Accepted  # Combine filters
- *   node ~/.claude/scripts/adr-list.js --include-parent          # Include parent repo ADRs (in submodule)
- *
- * Flags:
- *   --tags=tag1,tag2   Filter ADRs that have ANY of the specified tags (OR logic)
- *   --status=Status    Filter ADRs that match the exact status string
- *   --include-parent   When in a git submodule, also scan parent repo's .claude/adrs/
- *
- * Output:
- *   JSON array to stdout: [{ id, title, description, tags, status, date, source, sourcePath }]
- *
- * Example output:
- *   [
- *     {
- *       "id": "ADR-001",
- *       "title": "Use YAML ADRs for Architectural Decisions",
- *       "description": "Establishes YAML-formatted ADRs as the primary mechanism...",
- *       "tags": ["architecture", "adrs", "format"],
- *       "status": "Accepted",
- *       "date": "2025-11-22",
- *       "source": "local",
- *       "sourcePath": "/path/to/project"
- *     }
- *   ]
- *
- * Note: This script supplements the adr-agent (per ADR-009), providing
- * quick CLI access to ADR listings without invoking the full agent.
- */
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-const { execSync } = require('child_process');
-
-// ADRs are in the project's .claude/adrs/ directory (relative to CWD)
-const ADRS_DIR = path.join(process.cwd(), '.claude', 'adrs');
-
-/**
- * Parse command line arguments for --tags, --status, and --include-parent flags
- * @returns {{ tags: string[] | null, status: string | null, includeParent: boolean }}
- */
-function parseArgs() {
-  const args = process.argv.slice(2);
-  let tags = null;
-  let status = null;
-  let includeParent = false;
-
-  for (const arg of args) {
-    // Handle --tags=value or --tags value
-    if (arg.startsWith('--tags=')) {
-      const value = arg.slice('--tags='.length);
-      tags = value.split(',').map(t => t.trim()).filter(t => t.length > 0);
-    }
-    // Handle --status=value or --status value
-    else if (arg.startsWith('--status=')) {
-      status = arg.slice('--status='.length).trim();
-    }
-    // Handle --include-parent flag
-    else if (arg === '--include-parent') {
-      includeParent = true;
-    }
-  }
-
-  return { tags, status, includeParent };
-}
-
-/**
- * Detect submodule context using git commands
- * @returns {{ isInSubmodule: boolean, parentRepoPath: string | null, currentSubmodulePath: string | null }}
- */
-function detectSubmoduleContext() {
-  const result = {
-    isInSubmodule: false,
-    parentRepoPath: null,
-    currentSubmodulePath: null
-  };
-
-  try {
-    // Check if we're in a git repo at all
-    execSync('git rev-parse --git-dir', { stdio: 'pipe' });
-
-    // Check if we're in a submodule by looking for a superproject
-    const superprojectPath = execSync('git rev-parse --show-superproject-working-tree', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-
-    if (superprojectPath) {
-      result.isInSubmodule = true;
-      result.parentRepoPath = superprojectPath;
-
-      // Get the current submodule path relative to parent
-      // This is the path from the parent repo root to the submodule
-      const currentPath = process.cwd();
-      result.currentSubmodulePath = path.relative(superprojectPath, currentPath);
-    }
-  } catch (error) {
-    // Not in a git repo or git not available - silently ignore
-  }
-
-  return result;
-}
-
-/**
- * Read and parse a YAML ADR file, extracting metadata fields
- * @param {string} filePath - Absolute path to the YAML file
- * @param {string} source - "local" or "inherited"
- * @param {string} sourcePath - Path to the repo containing this ADR
- * @returns {{ id: string, title: string, description: string, tags: string[], status: string, date: string, scope: string[] | null, source: string, sourcePath: string } | null}
- */
-function parseAdrFile(filePath, source, sourcePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const data = yaml.load(content);
-
-    // Extract fields, handling missing optional fields gracefully
-    const id = data?.id || path.basename(filePath, '.yaml');
-    const title = data?.title || '';
-    // Clean up description - remove trailing newlines from YAML multi-line strings
-    const description = (data?.description || '').trim();
-    const tags = Array.isArray(data?.tags) ? data.tags : [];
-    const status = data?.status || '';
-    const date = data?.date || '';
-    // Scope is optional - null means global (applies everywhere)
-    const scope = Array.isArray(data?.scope) ? data.scope : null;
-
-    return { id, title, description, tags, status, date, scope, source, sourcePath };
-  } catch (error) {
-    // Log to stderr so it doesn't pollute JSON output
-    console.error(`Warning: Failed to parse ${filePath}: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Check if an ADR matches the given tag filter (OR logic)
- * @param {string[]} adrTags - Tags from the ADR
- * @param {string[]} filterTags - Tags to filter by
- * @returns {boolean} - True if ADR has ANY of the filter tags
- */
-function matchesTags(adrTags, filterTags) {
-  if (!filterTags || filterTags.length === 0) {
-    return true; // No filter = match all
-  }
-  // OR logic: return true if ADR has ANY of the filter tags
-  return filterTags.some(filterTag => adrTags.includes(filterTag));
-}
-
-/**
- * Check if an ADR matches the given status filter (exact match)
- * @param {string} adrStatus - Status from the ADR
- * @param {string | null} filterStatus - Status to filter by
- * @returns {boolean} - True if status matches exactly
- */
-function matchesStatus(adrStatus, filterStatus) {
-  if (!filterStatus) {
-    return true; // No filter = match all
-  }
-  return adrStatus === filterStatus;
-}
-
-/**
- * Check if an inherited ADR's scope applies to the current submodule
- * @param {string[] | null} scope - ADR's scope field (null = global, array = specific submodules)
- * @param {string | null} currentSubmodulePath - Current submodule path relative to parent
- * @returns {boolean} - True if ADR applies to current context
- */
-function matchesScope(scope, currentSubmodulePath) {
-  // null scope = global, applies everywhere
-  if (scope === null) {
-    return true;
-  }
-
-  // If we don't know the current submodule path, be conservative and include it
-  if (!currentSubmodulePath) {
-    return true;
-  }
-
-  // Check if current submodule path matches any scope entry
-  return scope.some(scopePath => {
-    // Exact match or prefix match (for nested submodules)
-    return currentSubmodulePath === scopePath ||
-           currentSubmodulePath.startsWith(scopePath + '/');
-  });
-}
-
-/**
- * Collect ADRs from a specific directory
- * @param {string} adrsDir - Directory to scan for ADRs
- * @param {string} source - "local" or "inherited"
- * @param {string} sourcePath - Path to the repo containing this ADR
- * @param {{ tags: string[] | null, status: string | null }} filters
- * @param {string | null} currentSubmodulePath - For inherited ADRs, used for scope filtering
- * @returns {Array<object>}
- */
-function collectAdrsFromDir(adrsDir, source, sourcePath, filters, currentSubmodulePath) {
-  const adrs = [];
-
-  // Check if ADRs directory exists
-  if (!fs.existsSync(adrsDir)) {
-    return adrs;
-  }
-
-  // Read all .yaml files in the ADRs directory
-  const files = fs.readdirSync(adrsDir)
-    .filter(file => file.endsWith('.yaml'))
-    .sort() // Sort alphabetically for consistent ordering
-    .map(file => path.join(adrsDir, file));
-
-  // Process each ADR file
-  for (const filePath of files) {
-    const adr = parseAdrFile(filePath, source, sourcePath);
-    if (!adr) continue;
-
-    // Apply tag and status filters
-    if (!matchesTags(adr.tags, filters.tags)) continue;
-    if (!matchesStatus(adr.status, filters.status)) continue;
-
-    // For inherited ADRs, apply scope filtering
-    if (source === 'inherited' && !matchesScope(adr.scope, currentSubmodulePath)) {
-      continue;
-    }
-
-    adrs.push(adr);
-  }
-
-  return adrs;
-}
-
-/**
- * Scan ADRs directory and collect all ADR metadata with optional filtering
- * @param {{ tags: string[] | null, status: string | null, includeParent: boolean }} options
- * @returns {Array<{ id: string, title: string, description: string, tags: string[], status: string, date: string, source: string, sourcePath: string }>}
- */
-function collectAdrs(options) {
-  const { tags, status, includeParent } = options;
-  const filters = { tags, status };
-  let allAdrs = [];
-
-  // Always collect local ADRs
-  const localAdrs = collectAdrsFromDir(ADRS_DIR, 'local', process.cwd(), filters, null);
-  allAdrs = allAdrs.concat(localAdrs);
-
-  // If --include-parent flag is set and we're in a submodule, also collect parent ADRs
-  if (includeParent) {
-    const submoduleContext = detectSubmoduleContext();
-
-    if (submoduleContext.isInSubmodule && submoduleContext.parentRepoPath) {
-      const parentAdrsDir = path.join(submoduleContext.parentRepoPath, '.claude', 'adrs');
-      const parentAdrs = collectAdrsFromDir(
-        parentAdrsDir,
-        'inherited',
-        submoduleContext.parentRepoPath,
-        filters,
-        submoduleContext.currentSubmodulePath
-      );
-      allAdrs = allAdrs.concat(parentAdrs);
-    }
-  }
-
-  // For backward compatibility, remove scope field from output (internal use only)
-  // and only include source/sourcePath when --include-parent is used
-  return allAdrs.map(adr => {
-    const { scope, ...rest } = adr;
-    if (!includeParent) {
-      // For backward compatibility, don't include source fields when not using --include-parent
-      const { source, sourcePath, ...backwardCompatible } = rest;
-      return backwardCompatible;
-    }
-    return rest;
-  });
-}
-
-// Main execution
-function main() {
-  const options = parseArgs();
-  const adrs = collectAdrs(options);
-
-  // Output JSON to stdout
-  console.log(JSON.stringify(adrs, null, 2));
-}
-
-main();

package/src/scripts/adr-tags.js

@@ -1,242 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * adr-tags.js - List all distinct tags across all ADRs with usage counts
- *
- * This CLI script scans all YAML ADR files in the project's .claude/adrs/
- * and extracts tag information, producing a sorted summary of tag usage.
- *
- * Usage:
- *   node ~/.claude/scripts/adr-tags.js                   # Tags from local ADRs only
- *   node ~/.claude/scripts/adr-tags.js --include-parent  # Include parent repo ADRs (in submodule)
- *
- * Flags:
- *   --include-parent   When in a git submodule, also include tags from parent repo's ADRs
- *
- * Output:
- *   JSON array to stdout: [{ tag, count, adrs }] sorted by count descending
- *
- * Example output:
- *   [
- *     { "tag": "architecture", "count": 8, "adrs": ["ADR-001", "ADR-003"] },
- *     { "tag": "agents", "count": 4, "adrs": ["ADR-003", "ADR-004"] }
- *   ]
- *
- * Note: This script supplements the adr-agent (per ADR-009), providing
- * quick CLI access to tag information without invoking the full agent.
- */
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-const { execSync } = require('child_process');
-
-// ADRs are in the project's .claude/adrs/ directory (relative to CWD)
-const ADRS_DIR = path.join(process.cwd(), '.claude', 'adrs');
-
-/**
- * Parse command line arguments for --include-parent flag
- * @returns {{ includeParent: boolean }}
- */
-function parseArgs() {
-  const args = process.argv.slice(2);
-  let includeParent = false;
-
-  for (const arg of args) {
-    if (arg === '--include-parent') {
-      includeParent = true;
-    }
-  }
-
-  return { includeParent };
-}
-
-/**
- * Detect submodule context using git commands
- * @returns {{ isInSubmodule: boolean, parentRepoPath: string | null, currentSubmodulePath: string | null }}
- */
-function detectSubmoduleContext() {
-  const result = {
-    isInSubmodule: false,
-    parentRepoPath: null,
-    currentSubmodulePath: null
-  };
-
-  try {
-    // Check if we're in a git repo at all
-    execSync('git rev-parse --git-dir', { stdio: 'pipe' });
-
-    // Check if we're in a submodule by looking for a superproject
-    const superprojectPath = execSync('git rev-parse --show-superproject-working-tree', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-
-    if (superprojectPath) {
-      result.isInSubmodule = true;
-      result.parentRepoPath = superprojectPath;
-
-      // Get the current submodule path relative to parent
-      const currentPath = process.cwd();
-      result.currentSubmodulePath = path.relative(superprojectPath, currentPath);
-    }
-  } catch (error) {
-    // Not in a git repo or git not available - silently ignore
-  }
-
-  return result;
-}
-
-/**
- * Check if an inherited ADR's scope applies to the current submodule
- * @param {string[] | null} scope - ADR's scope field (null = global, array = specific submodules)
- * @param {string | null} currentSubmodulePath - Current submodule path relative to parent
- * @returns {boolean} - True if ADR applies to current context
- */
-function matchesScope(scope, currentSubmodulePath) {
-  // null scope = global, applies everywhere
-  if (scope === null) {
-    return true;
-  }
-
-  // If we don't know the current submodule path, be conservative and include it
-  if (!currentSubmodulePath) {
-    return true;
-  }
-
-  // Check if current submodule path matches any scope entry
-  return scope.some(scopePath => {
-    // Exact match or prefix match (for nested submodules)
-    return currentSubmodulePath === scopePath ||
-           currentSubmodulePath.startsWith(scopePath + '/');
-  });
-}
-
-/**
- * Read and parse a YAML ADR file, extracting id, tags, and scope
- * @param {string} filePath - Absolute path to the YAML file
- * @returns {{ id: string, tags: string[], scope: string[] | null } | null} - Parsed data or null on error
- */
-function parseAdrFile(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const data = yaml.load(content);
-
-    // Extract id, tags, and scope, handling missing fields gracefully
-    const id = data?.id || path.basename(filePath, '.yaml');
-    const tags = Array.isArray(data?.tags) ? data.tags : [];
-    const scope = Array.isArray(data?.scope) ? data.scope : null;
-
-    return { id, tags, scope };
-  } catch (error) {
-    // Log to stderr so it doesn't pollute JSON output
-    console.error(`Warning: Failed to parse ${filePath}: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Collect tags from a specific ADRs directory
- * @param {string} adrsDir - Directory to scan for ADRs
- * @param {Map<string, string[]>} tagMap - Map to add tags to
- * @param {boolean} isInherited - Whether these are inherited ADRs
- * @param {string | null} currentSubmodulePath - For scope filtering on inherited ADRs
- */
-function collectTagsFromDir(adrsDir, tagMap, isInherited, currentSubmodulePath) {
-  // Check if ADRs directory exists
-  if (!fs.existsSync(adrsDir)) {
-    return;
-  }
-
-  // Read all .yaml files in the ADRs directory
-  const files = fs.readdirSync(adrsDir)
-    .filter(file => file.endsWith('.yaml'))
-    .map(file => path.join(adrsDir, file));
-
-  // Process each ADR file
-  for (const filePath of files) {
-    const adr = parseAdrFile(filePath);
-    if (!adr) continue;
-
-    // For inherited ADRs, apply scope filtering
-    if (isInherited && !matchesScope(adr.scope, currentSubmodulePath)) {
-      continue;
-    }
-
-    // Add this ADR's id to each of its tags
-    for (const tag of adr.tags) {
-      if (!tagMap.has(tag)) {
-        tagMap.set(tag, []);
-      }
-      // Avoid duplicates (in case same ADR id exists in both local and parent)
-      const adrList = tagMap.get(tag);
-      if (!adrList.includes(adr.id)) {
-        adrList.push(adr.id);
-      }
-    }
-  }
-}
-
-/**
- * Scan ADRs directories and collect all tag information
- * @param {{ includeParent: boolean }} options
- * @returns {Map<string, string[]>} - Map of tag -> array of ADR ids
- */
-function collectTags(options) {
-  const tagMap = new Map();
-  const { includeParent } = options;
-
-  // Collect tags from local ADRs
-  collectTagsFromDir(ADRS_DIR, tagMap, false, null);
-
-  // If --include-parent flag is set and we're in a submodule, also collect parent tags
-  if (includeParent) {
-    const submoduleContext = detectSubmoduleContext();
-
-    if (submoduleContext.isInSubmodule && submoduleContext.parentRepoPath) {
-      const parentAdrsDir = path.join(submoduleContext.parentRepoPath, '.claude', 'adrs');
-      collectTagsFromDir(parentAdrsDir, tagMap, true, submoduleContext.currentSubmodulePath);
-    }
-  }
-
-  return tagMap;
-}
-
-/**
- * Format tag data as sorted output array
- * @param {Map<string, string[]>} tagMap - Map of tag -> array of ADR ids
- * @returns {Array<{ tag: string, count: number, adrs: string[] }>}
- */
-function formatOutput(tagMap) {
-  const result = [];
-
-  for (const [tag, adrs] of tagMap.entries()) {
-    result.push({
-      tag,
-      count: adrs.length,
-      adrs: adrs.sort() // Sort ADR ids alphabetically within each tag
-    });
-  }
-
-  // Sort by count descending, then alphabetically by tag name for ties
-  result.sort((a, b) => {
-    if (b.count !== a.count) {
-      return b.count - a.count;
-    }
-    return a.tag.localeCompare(b.tag);
-  });
-
-  return result;
-}
-
-// Main execution
-function main() {
-  const options = parseArgs();
-  const tagMap = collectTags(options);
-  const output = formatOutput(tagMap);
-
-  // Output JSON to stdout
-  console.log(JSON.stringify(output, null, 2));
-}
-
-main();

package/src/scripts/validate-yaml.js

@@ -1,142 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * validate-yaml.js - Validate YAML syntax in files
- *
- * This script validates YAML files after they are created or modified through Claude Code's
- * Edit or Write tools. It's invoked by the PostToolUse hook system with JSON input via stdin
- * containing the file path that was just modified.
- *
- * Usage:
- *   echo '{"tool_input":{"file_path":"/path/to/file.yaml"}}' | node validate-yaml.js
- *
- * Input format (JSON via stdin):
- *   {
- *     "tool_input": {
- *       "file_path": "/absolute/path/to/file.yaml"
- *     }
- *   }
- *
- * Exit codes:
- *   0 - File is valid YAML or not a YAML file (silent success)
- *   2 - File is invalid YAML (parsing error written to stderr)
- *
- * Behavior:
- *   - Non-YAML files (.yaml and .yml extensions) pass through silently with exit 0
- *   - Valid YAML files produce no output and exit 0
- *   - Invalid YAML files produce parsing error on stderr and exit 2
- *
- * Dependencies:
- *   - js-yaml (for YAML parsing)
- *   - Node.js built-ins (fs, path)
- */
-
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-
-/**
- * Read JSON from stdin and extract file_path
- * @returns {Promise<string | null>} - The file path from tool_input, or null if invalid
- */
-async function readStdin() {
-  return new Promise((resolve, reject) => {
-    let data = '';
-
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => {
-      data += chunk;
-    });
-
-    process.stdin.on('end', () => {
-      try {
-        const parsed = JSON.parse(data);
-        const filePath = parsed?.tool_input?.file_path;
-        resolve(filePath || null);
-      } catch (error) {
-        // If we can't parse the input, still exit cleanly - don't interrupt the user's work
-        resolve(null);
-      }
-    });
-
-    process.stdin.on('error', () => {
-      // If there's an issue reading stdin, exit cleanly
-      resolve(null);
-    });
-  });
-}
-
-/**
- * Check if a file has a YAML extension
- * @param {string} filePath - The file path to check
- * @returns {boolean} - True if the file ends with .yaml or .yml
- */
-function isYamlFile(filePath) {
-  return filePath.endsWith('.yaml') || filePath.endsWith('.yml');
-}
-
-/**
- * Check if a file is in a Helm charts directory (uses Go templating, not valid YAML)
- * @param {string} filePath - The file path to check
- * @returns {boolean} - True if the file is in a charts directory
- */
-function isHelmChartFile(filePath) {
-  return filePath.includes('/charts/');
-}
-
-/**
- * Validate YAML syntax by attempting to parse the file
- * @param {string} filePath - The absolute path to the YAML file
- * @returns {{ valid: boolean, error?: string }} - Validation result with optional error message
- */
-function validateYaml(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    yaml.load(content);
-    return { valid: true };
-  } catch (error) {
-    return {
-      valid: false,
-      error: error.message
-    };
-  }
-}
-
-/**
- * Main execution - validate YAML file from tool input
- */
-async function main() {
-  const filePath = await readStdin();
-
-  // If we couldn't extract a file path, exit silently
-  if (!filePath) {
-    process.exit(0);
-  }
-
-  // If it's not a YAML file, pass through silently
-  if (!isYamlFile(filePath)) {
-    process.exit(0);
-  }
-
-  // If it's a Helm chart file, skip validation (uses Go templating syntax)
-  if (isHelmChartFile(filePath)) {
-    process.exit(0);
-  }
-
-  // Validate the YAML file
-  const result = validateYaml(filePath);
-
-  if (result.valid) {
-    // Valid YAML - silent success
-    process.exit(0);
-  } else {
-    // Invalid YAML - report error to stderr
-    console.error(`YAML validation error in ${filePath}:\n${result.error}`);
-    process.exit(2);
-  }
-}
-
-main().catch(() => {
-  // If anything goes wrong, exit silently to avoid disrupting the user's workflow
-  process.exit(0);
-});

package/src/scripts/yaml-validation-hook.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ~/.claude/scripts/validate-yaml.js"
-          }
-        ]
-      }
-    ]
-  }
-}