kodelyth-ecc 1.2.0

package/scripts/codemaps/generate.ts

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+/**
+ * scripts/codemaps/generate.ts
+ *
+ * Codemap Generator for everything-claude-code (ECC)
+ *
+ * Scans the current working directory and generates architectural
+ * codemap documentation under docs/CODEMAPS/ as specified by the
+ * doc-updater agent.
+ *
+ * Usage:
+ *   npx tsx scripts/codemaps/generate.ts [srcDir]
+ *
+ * Output:
+ *   docs/CODEMAPS/INDEX.md
+ *   docs/CODEMAPS/frontend.md
+ *   docs/CODEMAPS/backend.md
+ *   docs/CODEMAPS/database.md
+ *   docs/CODEMAPS/integrations.md
+ *   docs/CODEMAPS/workers.md
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const ROOT = process.cwd();
+const SRC_DIR = process.argv[2] ? path.resolve(process.argv[2]) : ROOT;
+const OUTPUT_DIR = path.join(ROOT, 'docs', 'CODEMAPS');
+const TODAY = new Date().toISOString().split('T')[0];
+
+// Patterns used to classify files into codemap areas
+const AREA_PATTERNS: Record<string, RegExp[]> = {
+  frontend: [
+    /\/(app|pages|components|hooks|contexts|ui|views|layouts|styles)\//i,
+    /\.(tsx|jsx|css|scss|sass|less|vue|svelte)$/i,
+  ],
+  backend: [
+    /\/(api|routes|controllers|middleware|server|services|handlers)\//i,
+    /\.(route|controller|handler|middleware|service)\.(ts|js)$/i,
+  ],
+  database: [
+    /\/(models|schemas|migrations|prisma|drizzle|db|database|repositories)\//i,
+    /\.(model|schema|migration|seed)\.(ts|js)$/i,
+    /prisma\/schema\.prisma$/,
+    /schema\.sql$/,
+  ],
+  integrations: [
+    /\/(integrations?|third-party|external|plugins?|adapters?|connectors?)\//i,
+    /\.(integration|adapter|connector)\.(ts|js)$/i,
+  ],
+  workers: [
+    /\/(workers?|jobs?|queues?|tasks?|cron|background)\//i,
+    /\.(worker|job|queue|task|cron)\.(ts|js)$/i,
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// File System Helpers
+// ---------------------------------------------------------------------------
+
+/** Recursively collect all files under a directory, skipping common noise dirs. */
+function walkDir(dir: string, results: string[] = []): string[] {
+  const SKIP = new Set([
+    'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
+    '.turbo', 'coverage', '.cache', '__pycache__', '.venv', 'venv',
+  ]);
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (SKIP.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(fullPath, results);
+    } else if (entry.isFile()) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/** Return path relative to ROOT, always using forward slashes. */
+function rel(p: string): string {
+  return path.relative(ROOT, p).replace(/\\/g, '/');
+}
+
+// ---------------------------------------------------------------------------
+// Analysis
+// ---------------------------------------------------------------------------
+
+interface AreaInfo {
+  name: string;
+  files: string[];
+  entryPoints: string[];
+  directories: string[];
+}
+
+function classifyFiles(allFiles: string[]): Record<string, AreaInfo> {
+  const areas: Record<string, AreaInfo> = {
+    frontend:     { name: 'Frontend', files: [], entryPoints: [], directories: [] },
+    backend:      { name: 'Backend/API', files: [], entryPoints: [], directories: [] },
+    database:     { name: 'Database', files: [], entryPoints: [], directories: [] },
+    integrations: { name: 'Integrations', files: [], entryPoints: [], directories: [] },
+    workers:      { name: 'Workers', files: [], entryPoints: [], directories: [] },
+  };
+
+  for (const file of allFiles) {
+    const relPath = rel(file);
+    for (const [area, patterns] of Object.entries(AREA_PATTERNS)) {
+      if (patterns.some((p) => p.test(relPath))) {
+        areas[area].files.push(relPath);
+        break;
+      }
+    }
+  }
+
+  // Derive unique directories and entry points per area
+  for (const area of Object.values(areas)) {
+    const dirs = new Set(area.files.map((f) => path.dirname(f)));
+    area.directories = [...dirs].sort();
+
+    area.entryPoints = area.files
+      .filter((f) => /index\.(ts|tsx|js|jsx)$/.test(f) || /main\.(ts|tsx|js|jsx)$/.test(f))
+      .slice(0, 10);
+  }
+
+  return areas;
+}
+
+/** Count lines in a file (returns 0 on error). */
+function lineCount(p: string): number {
+  try {
+    const content = fs.readFileSync(p, 'utf8');
+    return content.split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Build a simple directory tree ASCII diagram (max 3 levels deep). */
+function buildTree(dir: string, prefix = '', depth = 0): string {
+  if (depth > 2) return '';
+  const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage']);
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return '';
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory() && !SKIP.has(e.name));
+  const files = entries.filter((e) => e.isFile());
+
+  let result = '';
+  const items = [...dirs, ...files];
+  items.forEach((entry, i) => {
+    const isLast = i === items.length - 1;
+    const connector = isLast ? '└── ' : '├── ';
+    result += `${prefix}${connector}${entry.name}\n`;
+    if (entry.isDirectory()) {
+      const newPrefix = prefix + (isLast ? '    ' : '│   ');
+      result += buildTree(path.join(dir, entry.name), newPrefix, depth + 1);
+    }
+  });
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Markdown Generators
+// ---------------------------------------------------------------------------
+
+function generateAreaDoc(areaKey: string, area: AreaInfo, allFiles: string[]): string {
+  const fileCount = area.files.length;
+  const totalLines = area.files.reduce((sum, f) => sum + lineCount(path.join(ROOT, f)), 0);
+
+  const entrySection = area.entryPoints.length > 0
+    ? area.entryPoints.map((e) => `- \`${e}\``).join('\n')
+    : '- *(no index/main entry points detected)*';
+
+  const dirSection = area.directories.slice(0, 20)
+    .map((d) => `- \`${d}/\``)
+    .join('\n') || '- *(no dedicated directories detected)*';
+
+  const fileSection = area.files.slice(0, 30)
+    .map((f) => `| \`${f}\` | ${lineCount(path.join(ROOT, f))} |`)
+    .join('\n');
+
+  const moreFiles = area.files.length > 30
+    ? `\n*...and ${area.files.length - 30} more files*`
+    : '';
+
+  return `# ${area.name} Codemap
+
+**Last Updated:** ${TODAY}
+**Total Files:** ${fileCount}
+**Total Lines:** ${totalLines}
+
+## Entry Points
+
+${entrySection}
+
+## Architecture
+
+\`\`\`
+${area.name} Directory Structure
+${dirSection.replace(/- `/g, '').replace(/`\/$/gm, '/')}
+\`\`\`
+
+## Key Modules
+
+| File | Lines |
+|------|-------|
+${fileSection}${moreFiles}
+
+## Data Flow
+
+> Detected from file patterns. Review individual files for detailed data flow.
+
+## External Dependencies
+
+> Run \`npx jsdoc2md src/**/*.ts\` to extract JSDoc and identify external dependencies.
+
+## Related Areas
+
+- [INDEX](./INDEX.md) — Full overview
+- [Frontend](./frontend.md)
+- [Backend/API](./backend.md)
+- [Database](./database.md)
+- [Integrations](./integrations.md)
+- [Workers](./workers.md)
+`;
+}
+
+function generateIndex(areas: Record<string, AreaInfo>, allFiles: string[]): string {
+  const totalFiles = allFiles.length;
+  const areaRows = Object.entries(areas)
+    .map(([key, area]) => `| [${area.name}](./${key}.md) | ${area.files.length} files | ${area.directories.slice(0, 3).map((d) => `\`${d}\``).join(', ') || '—'} |`)
+    .join('\n');
+
+  const topLevelTree = buildTree(SRC_DIR);
+
+  return `# Codebase Overview — CODEMAPS Index
+
+**Last Updated:** ${TODAY}
+**Root:** \`${rel(SRC_DIR) || '.'}\`
+**Total Files Scanned:** ${totalFiles}
+
+## Areas
+
+| Area | Size | Key Directories |
+|------|------|-----------------|
+${areaRows}
+
+## Repository Structure
+
+\`\`\`
+${rel(SRC_DIR) || path.basename(SRC_DIR)}/
+${topLevelTree}\`\`\`
+
+## How to Regenerate
+
+\`\`\`bash
+npx tsx scripts/codemaps/generate.ts        # Regenerate codemaps
+npx madge --image graph.svg src/            # Dependency graph (requires graphviz)
+npx jsdoc2md src/**/*.ts                    # Extract JSDoc
+\`\`\`
+
+## Related Documentation
+
+- [Frontend](./frontend.md) — UI components, pages, hooks
+- [Backend/API](./backend.md) — API routes, controllers, middleware
+- [Database](./database.md) — Models, schemas, migrations
+- [Integrations](./integrations.md) — External services & adapters
+- [Workers](./workers.md) — Background jobs, queues, cron tasks
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  console.log(`[generate.ts] Scanning: ${SRC_DIR}`);
+  console.log(`[generate.ts] Output:   ${OUTPUT_DIR}`);
+
+  // Ensure output directory exists
+  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  // Walk the directory tree
+  const allFiles = walkDir(SRC_DIR);
+  console.log(`[generate.ts] Found ${allFiles.length} files`);
+
+  // Classify files into areas
+  const areas = classifyFiles(allFiles);
+
+  // Generate INDEX.md
+  const indexContent = generateIndex(areas, allFiles);
+  const indexPath = path.join(OUTPUT_DIR, 'INDEX.md');
+  fs.writeFileSync(indexPath, indexContent, 'utf8');
+  console.log(`[generate.ts] Written: ${rel(indexPath)}`);
+
+  // Generate per-area codemaps
+  for (const [key, area] of Object.entries(areas)) {
+    const content = generateAreaDoc(key, area, allFiles);
+    const outPath = path.join(OUTPUT_DIR, `${key}.md`);
+    fs.writeFileSync(outPath, content, 'utf8');
+    console.log(`[generate.ts] Written: ${rel(outPath)} (${area.files.length} files)`);
+  }
+
+  console.log('\n[generate.ts] Done! Codemaps written to docs/CODEMAPS/');
+  console.log('[generate.ts] Files generated:');
+  console.log('  docs/CODEMAPS/INDEX.md');
+  console.log('  docs/CODEMAPS/frontend.md');
+  console.log('  docs/CODEMAPS/backend.md');
+  console.log('  docs/CODEMAPS/database.md');
+  console.log('  docs/CODEMAPS/integrations.md');
+  console.log('  docs/CODEMAPS/workers.md');
+}
+
+main();

package/scripts/codex/check-codex-global-state.sh

@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ECC Codex global regression sanity check.
+# Validates that global ~/.codex state matches expected ECC integration.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+
+# Use rg if available, otherwise fall back to grep -E.
+# All patterns in this script must be POSIX ERE compatible.
+if command -v rg >/dev/null 2>&1; then
+  search_file() { rg -n "$1" "$2" >/dev/null 2>&1; }
+else
+  search_file() { grep -En "$1" "$2" >/dev/null 2>&1; }
+fi
+
+CONFIG_FILE="$CODEX_HOME/config.toml"
+AGENTS_FILE="$CODEX_HOME/AGENTS.md"
+PROMPTS_DIR="$CODEX_HOME/prompts"
+SKILLS_DIR="${AGENTS_HOME:-$HOME/.agents}/skills"
+HOOKS_DIR_EXPECT="${ECC_GLOBAL_HOOKS_DIR:-$CODEX_HOME/git-hooks}"
+
+failures=0
+warnings=0
+checks=0
+
+ok() {
+  checks=$((checks + 1))
+  printf '[OK] %s\n' "$*"
+}
+
+warn() {
+  checks=$((checks + 1))
+  warnings=$((warnings + 1))
+  printf '[WARN] %s\n' "$*"
+}
+
+fail() {
+  checks=$((checks + 1))
+  failures=$((failures + 1))
+  printf '[FAIL] %s\n' "$*"
+}
+
+require_file() {
+  local file="$1"
+  local label="$2"
+  if [[ -f "$file" ]]; then
+    ok "$label exists ($file)"
+  else
+    fail "$label missing ($file)"
+  fi
+}
+
+check_config_pattern() {
+  local pattern="$1"
+  local label="$2"
+  if search_file "$pattern" "$CONFIG_FILE"; then
+    ok "$label"
+  else
+    fail "$label"
+  fi
+}
+
+check_config_absent() {
+  local pattern="$1"
+  local label="$2"
+  if search_file "$pattern" "$CONFIG_FILE"; then
+    fail "$label"
+  else
+    ok "$label"
+  fi
+}
+
+printf 'ECC GLOBAL SANITY CHECK\n'
+printf 'Repo: %s\n' "$REPO_ROOT"
+printf 'Codex home: %s\n\n' "$CODEX_HOME"
+
+require_file "$CONFIG_FILE" "Global config.toml"
+require_file "$AGENTS_FILE" "Global AGENTS.md"
+
+if [[ -f "$AGENTS_FILE" ]]; then
+  if search_file '^# Kodelyth ECC \(ECC\)' "$AGENTS_FILE"; then
+    ok "AGENTS contains ECC root instructions"
+  else
+    fail "AGENTS missing ECC root instructions"
+  fi
+
+  if search_file '^# Codex Supplement \(From ECC \.codex/AGENTS\.md\)' "$AGENTS_FILE"; then
+    ok "AGENTS contains ECC Codex supplement"
+  else
+    fail "AGENTS missing ECC Codex supplement"
+  fi
+fi
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  check_config_pattern '^multi_agent[[:space:]]*=[[:space:]]*true' "multi_agent is enabled"
+  check_config_absent '^[[:space:]]*collab[[:space:]]*=' "deprecated collab flag is absent"
+  # persistent_instructions is recommended but optional; warn instead of fail
+  # so users who rely on AGENTS.md alone are not blocked (#967).
+  if search_file '^[[:space:]]*persistent_instructions[[:space:]]*=' "$CONFIG_FILE"; then
+    ok "persistent_instructions is configured"
+  else
+    warn "persistent_instructions is not set (recommended but optional)"
+  fi
+  check_config_pattern '^\[profiles\.strict\]' "profiles.strict exists"
+  check_config_pattern '^\[profiles\.yolo\]' "profiles.yolo exists"
+
+  for section in \
+    'mcp_servers.github' \
+    'mcp_servers.memory' \
+    'mcp_servers.sequential-thinking' \
+    'mcp_servers.context7'
+  do
+    if search_file "^\[$section\]" "$CONFIG_FILE"; then
+      ok "MCP section [$section] exists"
+    else
+      fail "MCP section [$section] missing"
+    fi
+  done
+
+  has_context7_legacy=0
+  has_context7_current=0
+
+  if search_file '^\[mcp_servers\.context7\]' "$CONFIG_FILE"; then
+    has_context7_legacy=1
+  fi
+
+  if search_file '^\[mcp_servers\.context7-mcp\]' "$CONFIG_FILE"; then
+    has_context7_current=1
+  fi
+
+  if [[ "$has_context7_legacy" -eq 1 || "$has_context7_current" -eq 1 ]]; then
+    ok "MCP section [mcp_servers.context7] or [mcp_servers.context7-mcp] exists"
+  else
+    fail "MCP section [mcp_servers.context7] or [mcp_servers.context7-mcp] missing"
+  fi
+
+  if [[ "$has_context7_legacy" -eq 1 && "$has_context7_current" -eq 1 ]]; then
+    warn "Both [mcp_servers.context7] and [mcp_servers.context7-mcp] exist; prefer one name"
+  fi
+fi
+
+declare -a required_skills=(
+  api-design
+  article-writing
+  backend-patterns
+  coding-standards
+  content-engine
+  e2e-testing
+  eval-harness
+  frontend-patterns
+  frontend-slides
+  investor-materials
+  investor-outreach
+  market-research
+  security-review
+  strategic-compact
+  tdd-workflow
+  verification-loop
+)
+
+if [[ -d "$SKILLS_DIR" ]]; then
+  missing_skills=0
+  for skill in "${required_skills[@]}"; do
+    if [[ -d "$SKILLS_DIR/$skill" ]]; then
+      :
+    else
+      printf '  - missing skill: %s\n' "$skill"
+      missing_skills=$((missing_skills + 1))
+    fi
+  done
+
+  if [[ "$missing_skills" -eq 0 ]]; then
+    ok "All 16 ECC skills are present in $SKILLS_DIR"
+  else
+    warn "$missing_skills ECC skills missing from $SKILLS_DIR (install via ECC installer or npx skills)"
+  fi
+else
+  warn "Skills directory missing ($SKILLS_DIR) — install via ECC installer or npx skills"
+fi
+
+if [[ -f "$PROMPTS_DIR/ecc-prompts-manifest.txt" ]]; then
+  ok "Command prompts manifest exists"
+else
+  fail "Command prompts manifest missing"
+fi
+
+if [[ -f "$PROMPTS_DIR/ecc-extension-prompts-manifest.txt" ]]; then
+  ok "Extension prompts manifest exists"
+else
+  fail "Extension prompts manifest missing"
+fi
+
+command_prompts_count="$(find "$PROMPTS_DIR" -maxdepth 1 -type f -name 'ecc-*.md' 2>/dev/null | wc -l | tr -d ' ')"
+if [[ "$command_prompts_count" -ge 43 ]]; then
+  ok "ECC prompts count is $command_prompts_count (expected >= 43)"
+else
+  fail "ECC prompts count is $command_prompts_count (expected >= 43)"
+fi
+
+hooks_path="$(git config --global --get core.hooksPath || true)"
+if [[ -n "$hooks_path" ]]; then
+  if [[ "$hooks_path" == "$HOOKS_DIR_EXPECT" ]]; then
+    ok "Global hooksPath is set to $HOOKS_DIR_EXPECT"
+  else
+    warn "Global hooksPath is $hooks_path (expected $HOOKS_DIR_EXPECT)"
+  fi
+else
+  fail "Global hooksPath is not configured"
+fi
+
+if [[ -x "$HOOKS_DIR_EXPECT/pre-commit" ]]; then
+  ok "Global pre-commit hook is installed and executable"
+else
+  fail "Global pre-commit hook missing or not executable"
+fi
+
+if [[ -x "$HOOKS_DIR_EXPECT/pre-push" ]]; then
+  ok "Global pre-push hook is installed and executable"
+else
+  fail "Global pre-push hook missing or not executable"
+fi
+
+if command -v ecc-sync-codex >/dev/null 2>&1; then
+  ok "ecc-sync-codex command is in PATH"
+else
+  warn "ecc-sync-codex is not in PATH"
+fi
+
+if command -v ecc-install-git-hooks >/dev/null 2>&1; then
+  ok "ecc-install-git-hooks command is in PATH"
+else
+  warn "ecc-install-git-hooks is not in PATH"
+fi
+
+if command -v ecc-check-codex >/dev/null 2>&1; then
+  ok "ecc-check-codex command is in PATH"
+else
+  warn "ecc-check-codex is not in PATH (this is expected before alias setup)"
+fi
+
+printf '\nSummary: checks=%d, warnings=%d, failures=%d\n' "$checks" "$warnings" "$failures"
+if [[ "$failures" -eq 0 ]]; then
+  printf 'ECC GLOBAL SANITY: PASS\n'
+else
+  printf 'ECC GLOBAL SANITY: FAIL\n'
+  exit 1
+fi

package/scripts/codex/install-global-git-hooks.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Install ECC git safety hooks globally via core.hooksPath.
+# Usage:
+#   ./scripts/codex/install-global-git-hooks.sh
+#   ./scripts/codex/install-global-git-hooks.sh --dry-run
+
+MODE="apply"
+if [[ "${1:-}" == "--dry-run" ]]; then
+  MODE="dry-run"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SOURCE_DIR="$REPO_ROOT/scripts/codex-git-hooks"
+DEST_DIR="${ECC_GLOBAL_HOOKS_DIR:-$HOME/.codex/git-hooks}"
+STAMP="$(date +%Y%m%d-%H%M%S)"
+BACKUP_DIR="$HOME/.codex/backups/git-hooks-$STAMP"
+
+log() {
+  printf '[ecc-hooks] %s\n' "$*"
+}
+
+run_or_echo() {
+  if [[ "$MODE" == "dry-run" ]]; then
+    printf '[dry-run]'
+    printf ' %q' "$@"
+    printf '\n'
+  else
+    "$@"
+  fi
+}
+
+if [[ ! -d "$SOURCE_DIR" ]]; then
+  log "Missing source hooks directory: $SOURCE_DIR"
+  exit 1
+fi
+
+log "Mode: $MODE"
+log "Source hooks: $SOURCE_DIR"
+log "Global hooks destination: $DEST_DIR"
+
+if [[ -d "$DEST_DIR" ]]; then
+  log "Backing up existing hooks directory to $BACKUP_DIR"
+  run_or_echo mkdir -p "$BACKUP_DIR"
+  run_or_echo cp -R "$DEST_DIR" "$BACKUP_DIR/hooks"
+fi
+
+run_or_echo mkdir -p "$DEST_DIR"
+run_or_echo cp "$SOURCE_DIR/pre-commit" "$DEST_DIR/pre-commit"
+run_or_echo cp "$SOURCE_DIR/pre-push" "$DEST_DIR/pre-push"
+run_or_echo chmod +x "$DEST_DIR/pre-commit" "$DEST_DIR/pre-push"
+
+if [[ "$MODE" == "apply" ]]; then
+  prev_hooks_path="$(git config --global core.hooksPath || true)"
+  if [[ -n "$prev_hooks_path" ]]; then
+    log "Previous global hooksPath: $prev_hooks_path"
+  fi
+fi
+run_or_echo git config --global core.hooksPath "$DEST_DIR"
+
+log "Installed ECC global git hooks."
+log "Disable per repo by creating .ecc-hooks-disable in project root."
+log "Temporary bypass: ECC_SKIP_PRECOMMIT=1 or ECC_SKIP_PREPUSH=1"