@kennethsolomon/shipkit 1.0.0

package/skills/sk:setup-claude/scripts/apply_setup_claude.py

@@ -0,0 +1,443 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+
+GENERATED_MARKER = "<!-- Generated by /setup-claude -->"
+TEMPLATE_HASH_MARKER = "<!-- Template Hash: "
+TEMPLATE_HASH_END = " -->"
+
+
+@dataclass(frozen=True)
+class Detection:
+    project_name: str
+    description: str
+    language: str
+    framework: str
+    database: str
+    ui: str
+    testing: str
+    ai: str
+    browser_automation: str
+    dev_cmd: str
+    build_cmd: str
+    lint_cmd: str
+    test_cmd: str
+    arch_changelog_dir: str
+
+
+def _read_json(path: Path) -> Optional[dict]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except Exception:
+        return None
+
+
+def _has_dep(pkg: dict, name: str) -> bool:
+    deps = {}
+    for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        deps.update(pkg.get(key, {}) or {})
+    return name in deps
+
+
+def _any_dep_prefix(pkg: dict, prefix: str) -> bool:
+    deps = {}
+    for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        deps.update(pkg.get(key, {}) or {})
+    return any(k.startswith(prefix) for k in deps.keys())
+
+
+def detect(repo_root: Path) -> Detection:
+    package_json = _read_json(repo_root / "package.json") or {}
+    scripts = (package_json.get("scripts") or {}) if isinstance(package_json, dict) else {}
+
+    project_name = str(package_json.get("name") or repo_root.name)
+    description = str(package_json.get("description") or "Project instructions for Claude Code.")
+
+    # Language
+    if (repo_root / "tsconfig.json").exists() or _has_dep(package_json, "typescript"):
+        language = "TypeScript"
+    elif (repo_root / "package.json").exists():
+        language = "JavaScript"
+    elif (repo_root / "pyproject.toml").exists() or (repo_root / "requirements.txt").exists():
+        language = "Python"
+    elif (repo_root / "go.mod").exists():
+        language = "Go"
+    elif (repo_root / "Cargo.toml").exists():
+        language = "Rust"
+    elif (repo_root / "composer.json").exists():
+        language = "PHP"
+    else:
+        language = "Unknown"
+
+    # Framework (keep simple; expand later)
+    if _has_dep(package_json, "next"):
+        framework = "Next.js (App Router)"
+    elif _has_dep(package_json, "react"):
+        framework = "React"
+    elif _has_dep(package_json, "express"):
+        framework = "Express"
+    else:
+        framework = "Unknown"
+
+    # Database / ORM
+    if _has_dep(package_json, "drizzle-orm"):
+        if _has_dep(package_json, "better-sqlite3"):
+            database = "Drizzle ORM + SQLite"
+        elif _has_dep(package_json, "pg"):
+            database = "Drizzle ORM + PostgreSQL"
+        else:
+            database = "Drizzle ORM"
+    elif _has_dep(package_json, "prisma") or _has_dep(package_json, "@prisma/client"):
+        database = "Prisma"
+    elif _has_dep(package_json, "@supabase/supabase-js") or (repo_root / "supabase" / "config.toml").exists():
+        database = "Supabase (Postgres)"
+    else:
+        database = "Unknown"
+
+    # UI
+    if _has_dep(package_json, "tailwindcss"):
+        if (repo_root / "src" / "components" / "ui").exists():
+            ui = "Tailwind CSS + shadcn/ui"
+        else:
+            ui = "Tailwind CSS"
+    elif _has_dep(package_json, "bootstrap"):
+        ui = "Bootstrap"
+    else:
+        ui = "Unknown"
+
+    # Testing
+    if _has_dep(package_json, "vitest"):
+        testing = "Vitest"
+    elif _has_dep(package_json, "jest"):
+        testing = "Jest"
+    elif _has_dep(package_json, "@playwright/test") or _has_dep(package_json, "playwright"):
+        testing = "Playwright"
+    else:
+        testing = "Unknown"
+
+    # AI
+    if _has_dep(package_json, "openai"):
+        ai = "OpenAI-compatible"
+    elif _has_dep(package_json, "@anthropic-ai/sdk"):
+        ai = "Anthropic"
+    else:
+        ai = "Unknown"
+
+    # Browser automation
+    if _has_dep(package_json, "@playwright/test") or _has_dep(package_json, "playwright"):
+        browser_automation = "Playwright"
+    elif _has_dep(package_json, "puppeteer"):
+        browser_automation = "Puppeteer"
+    else:
+        browser_automation = "None"
+
+    dev_cmd = scripts.get("dev") and "npm run dev" or "npm run dev"
+    build_cmd = scripts.get("build") and "npm run build" or "npm run build"
+    lint_cmd = scripts.get("lint") and "npm run lint" or "npm run lint"
+    test_cmd = scripts.get("test") and "npm test" or "npm test"
+
+    typo_dir = repo_root / ".claude" / "docs" / "achritectural_change_log"
+    correct_dir = repo_root / ".claude" / "docs" / "architectural_change_log"
+    if typo_dir.exists():
+        arch_dir = ".claude/docs/achritectural_change_log/"
+    else:
+        arch_dir = ".claude/docs/architectural_change_log/"
+
+    return Detection(
+        project_name=project_name,
+        description=description,
+        language=language,
+        framework=framework,
+        database=database,
+        ui=ui,
+        testing=testing,
+        ai=ai,
+        browser_automation=browser_automation,
+        dev_cmd=dev_cmd,
+        build_cmd=build_cmd,
+        lint_cmd=lint_cmd,
+        test_cmd=test_cmd,
+        arch_changelog_dir=arch_dir,
+    )
+
+
+def _get_template_hash(template_path: Path) -> str:
+    """Calculate SHA256 hash of template file."""
+    try:
+        content = template_path.read_text(encoding="utf-8")
+        return hashlib.sha256(content.encode()).hexdigest()[:12]
+    except Exception:
+        return "unknown"
+
+
+def _extract_template_hash(content: str) -> Optional[str]:
+    """Extract template hash from generated file."""
+    match = re.search(rf"{re.escape(TEMPLATE_HASH_MARKER)}([a-f0-9]{{12}}){re.escape(TEMPLATE_HASH_END)}", content)
+    return match.group(1) if match else None
+
+
+def render_template(text: str, detection: Detection, template_path: Optional[Path] = None) -> str:
+    replacements = {
+        "[PROJECT_NAME]": detection.project_name,
+        "[ONE_SENTENCE_DESCRIPTION]": detection.description,
+        "[LANGUAGE]": detection.language,
+        "[FRAMEWORK]": detection.framework,
+        "[DATABASE]": detection.database,
+        "[UI]": detection.ui,
+        "[TESTING]": detection.testing,
+        "[AI]": detection.ai,
+        "[BROWSER_AUTOMATION]": detection.browser_automation,
+        "[DEV_COMMAND]": detection.dev_cmd,
+        "[BUILD_COMMAND]": detection.build_cmd,
+        "[LINT_COMMAND]": detection.lint_cmd,
+        "[TEST_COMMAND]": detection.test_cmd,
+        "[ARCH_CHANGELOG_DIR]": detection.arch_changelog_dir,
+    }
+    for k, v in replacements.items():
+        text = text.replace(k, v)
+
+    # Add template hash for future update detection
+    if template_path:
+        template_hash = _get_template_hash(template_path)
+        # Insert hash after the first line (GENERATED_MARKER)
+        lines = text.split('\n')
+        if lines and GENERATED_MARKER in lines[0]:
+            lines.insert(1, f"{TEMPLATE_HASH_MARKER}{template_hash}{TEMPLATE_HASH_END}")
+            text = '\n'.join(lines)
+
+    return text
+
+
+def _write_file_if_missing(dest: Path, content: str) -> Tuple[str, Path]:
+    if dest.exists():
+        return ("skipped", dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(content, encoding="utf-8")
+    return ("created", dest)
+
+
+def _write_file_if_generated(dest: Path, content: str, template_path: Optional[Path] = None) -> Tuple[str, Path]:
+    if not dest.exists():
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+        return ("created", dest)
+    try:
+        existing = dest.read_text(encoding="utf-8")
+    except Exception:
+        return ("skipped", dest)
+    if GENERATED_MARKER in existing:
+        # Check if content is identical (fast path)
+        if existing == content:
+            return ("skipped", dest)
+        # Check if template has changed (slow path)
+        if template_path:
+            old_hash = _extract_template_hash(existing)
+            new_hash = _get_template_hash(template_path)
+            if old_hash == new_hash:
+                # Template hasn't changed, but rendered content differs
+                # This shouldn't happen; keep existing file
+                return ("skipped", dest)
+        # Template has changed or hash check failed, update
+        dest.write_text(content, encoding="utf-8")
+        return ("updated", dest)
+    return ("skipped", dest)
+
+
+def _plan_file_if_missing(dest: Path) -> str:
+    return "skipped" if dest.exists() else "created"
+
+
+def _plan_file_if_generated(dest: Path, content: str) -> str:
+    if not dest.exists():
+        return "created"
+    try:
+        existing = dest.read_text(encoding="utf-8")
+    except Exception:
+        return "skipped"
+    if GENERATED_MARKER not in existing:
+        return "skipped"
+    return "skipped" if existing == content else "updated"
+
+
+def apply(
+    repo_root: Path,
+    skill_root: Path,
+    *,
+    update_generated: bool,
+    dry_run: bool,
+    detection: Optional[Detection] = None,
+) -> int:
+    detection = detection or detect(repo_root)
+
+    arch_dir_path = repo_root / detection.arch_changelog_dir.rstrip("/")
+    if not dry_run:
+        # Ensure arch dir exists if we selected the correct spelling.
+        arch_dir_path.mkdir(parents=True, exist_ok=True)
+
+    mapping: List[Tuple[Path, Path, str]] = []
+    notes: List[str] = []
+
+    def add(template_rel: str, dest_rel: str, mode: str) -> None:
+        mapping.append((skill_root / template_rel, repo_root / dest_rel, mode))
+
+    # tasks (create-only)
+    add("templates/tasks/todo.md.template", "tasks/todo.md", "missing")
+    add("templates/tasks/findings.md.template", "tasks/findings.md", "missing")
+    add("templates/tasks/progress.md.template", "tasks/progress.md", "missing")
+    add("templates/tasks/lessons.md.template", "tasks/lessons.md", "missing")
+    add("templates/tasks/security-findings.md.template", "tasks/security-findings.md", "missing")
+    add("templates/tasks/workflow-status.md.template", "tasks/workflow-status.md", "missing")
+
+    # commands (update if generated)
+    add("templates/commands/brainstorm.md.template", ".claude/commands/brainstorm.md", "generated")
+    add("templates/commands/write-plan.md.template", ".claude/commands/write-plan.md", "generated")
+    add("templates/commands/execute-plan.md.template", ".claude/commands/execute-plan.md", "generated")
+    add("templates/commands/plan.md.template", ".claude/commands/plan.md", "generated")
+    add("templates/commands/status.md.template", ".claude/commands/status.md", "generated")
+    add("templates/commands/finish-feature.md.template", ".claude/commands/finish-feature.md", "generated")
+    add("templates/commands/re-setup.md.template", ".claude/commands/re-setup.md", "generated")
+    add("templates/commands/release.md.template", ".claude/commands/release.md", "generated")
+    add("templates/commands/features.md.template", ".claude/commands/features.md", "generated")
+    add("templates/commands/security-check.md.template", ".claude/commands/security-check.md", "generated")
+
+    # docs (generated-update)
+    add("templates/.claude/docs/changelog-guide.md.template", ".claude/docs/changelog-guide.md", "generated")
+    add("templates/.claude/docs/arch-changelog-guide.md.template", ".claude/docs/arch-changelog-guide.md", "generated")
+
+    # root files
+    claude_md_path = repo_root / "CLAUDE.md"
+    sidecar_claude_md_path = repo_root / "CLAUDE.setup-claude.md"
+    use_sidecar_claude_md = False
+    if claude_md_path.exists():
+        try:
+            existing = claude_md_path.read_text(encoding="utf-8")
+            use_sidecar_claude_md = GENERATED_MARKER not in existing
+        except Exception:
+            use_sidecar_claude_md = True
+        if use_sidecar_claude_md:
+            notes.append("Found existing custom CLAUDE.md; writing CLAUDE.setup-claude.md instead.")
+
+    if use_sidecar_claude_md:
+        add("templates/CLAUDE.md.template", "CLAUDE.setup-claude.md", "generated")
+    else:
+        add("templates/CLAUDE.md.template", "CLAUDE.md", "generated")
+    add("templates/CHANGELOG.md.template", "CHANGELOG.md", "missing")
+
+    created: List[str] = []
+    updated: List[str] = []
+    skipped: List[str] = []
+
+    arch_dir_rel = str(arch_dir_path.relative_to(repo_root))
+    if dry_run:
+        if arch_dir_path.exists():
+            skipped.append(arch_dir_rel)
+        else:
+            created.append(arch_dir_rel)
+
+    for template_path, dest_path, mode in mapping:
+        try:
+            template_text = template_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            skipped.append(str(dest_path))
+            continue
+        rendered = render_template(template_text, detection, template_path if mode == "generated" else None)
+
+        if mode == "missing":
+            if dry_run:
+                action = _plan_file_if_missing(dest_path)
+                p = dest_path
+            else:
+                action, p = _write_file_if_missing(dest_path, rendered)
+        elif mode == "generated":
+            if dry_run:
+                action = _plan_file_if_generated(dest_path, rendered)
+                p = dest_path
+            else:
+                action, p = _write_file_if_generated(dest_path, rendered, template_path)
+        else:
+            action, p = ("skipped", dest_path)
+
+        if action == "created":
+            created.append(str(p.relative_to(repo_root)))
+        elif action == "updated":
+            updated.append(str(p.relative_to(repo_root)))
+        else:
+            skipped.append(str(p.relative_to(repo_root)))
+
+    if dry_run:
+        print("setup-claude dry-run complete (no files written)")
+    else:
+        print("setup-claude apply complete")
+    if notes:
+        print("\nNotes:")
+        for n in notes:
+            print(f"  - {n}")
+    if created:
+        print("\nCreated:")
+        for p in created:
+            print(f"  - {p}")
+    if updated:
+        print("\nUpdated:")
+        for p in updated:
+            print(f"  - {p}")
+    if skipped:
+        print("\nSkipped:")
+        for p in skipped:
+            print(f"  - {p}")
+
+    return 0
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(prog="apply_setup_claude.py")
+    parser.add_argument("repo_root", nargs="?", default=str(Path.cwd()), help="Target repository root (default: cwd)")
+    parser.add_argument(
+        "--update-generated",
+        action="store_true",
+        help="Update files previously generated by /setup-claude (marker-guarded).",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="Preview changes without writing any files.")
+    parser.add_argument(
+        "--print-detection",
+        action="store_true",
+        help="Print detected values as JSON and exit unless combined with --dry-run.",
+    )
+    args = parser.parse_args(argv[1:])
+
+    repo_root = Path(args.repo_root).resolve()
+    skill_root = Path(__file__).resolve().parents[1]
+
+    if not repo_root.exists():
+        print(f"Repo root not found: {repo_root}", file=sys.stderr)
+        return 2
+
+    detection = detect(repo_root)
+    if args.print_detection:
+        print(json.dumps(asdict(detection), indent=2, sort_keys=True))
+        if not args.dry_run:
+            return 0
+
+    return apply(
+        repo_root,
+        skill_root,
+        update_generated=args.update_generated,
+        dry_run=args.dry_run,
+        detection=detection,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))