claude-dev-env 1.19.3 → 1.21.0

package/scripts/sync_to_cursor/engine.py

@@ -0,0 +1,194 @@
+"""Sync Claude rules to Cursor .mdc files and manifest."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from sync_to_cursor.canonical_docs import check_canonical_docs, sync_canonical_docs
+from sync_to_cursor.config import GENERATOR_VERSION
+from sync_to_cursor.hashing import sha256_bytes
+from sync_to_cursor.paths import llm_layout_paths
+from sync_to_cursor.rules import RuleMapping, _full_mdc, apply_transform, build_mappings
+
+
+def _load_manifest(manifest_path: Path) -> dict:
+    if not manifest_path.is_file():
+        return {}
+    try:
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _sources_hash(paths: tuple[Path, ...]) -> str:
+    return sha256_bytes(b"\x00".join(p.read_bytes() for p in paths))
+
+
+def _run_check(
+    mappings: tuple[RuleMapping, ...],
+    out_dir: Path,
+    entries_meta: dict,
+    claude: Path,
+    cursor: Path,
+    docs_entries_meta: dict,
+) -> int:
+    for each_mapping in mappings:
+        key = f"rules/{each_mapping.output_name}"
+        out_path = out_dir / each_mapping.output_name
+        missing = [source for source in each_mapping.sources if not source.is_file()]
+        if missing:
+            if each_mapping.always_apply:
+                return 1
+            continue
+        src_hash = _sources_hash(each_mapping.sources)
+        prev = entries_meta.get(key, {})
+        if src_hash != prev.get("sources_hash"):
+            return 1
+        prev_out = prev.get("output_hash", "")
+        if out_path.is_file() and prev_out:
+            if sha256_bytes(out_path.read_bytes()) != prev_out:
+                return 1
+        elif not out_path.is_file():
+            return 1
+    if out_dir.is_dir():
+        for each_path in out_dir.glob("*.mdc"):
+            if each_path.name not in {x.output_name for x in mappings}:
+                return 1
+    if not check_canonical_docs(claude, cursor, docs_entries_meta):
+        return 1
+    return 0
+
+
+def _sync_rules(
+    mappings: tuple[RuleMapping, ...],
+    out_dir: Path,
+    entries_meta: dict,
+    *,
+    force: bool,
+    dry_run: bool,
+    quiet: bool,
+    cursor: Path,
+) -> tuple[dict, dict]:
+    summary: dict = {"skip": 0, "update": 0, "tampered": 0, "warn": 0, "orphan": 0}
+    new_entries: dict = {}
+    write_allowed = not dry_run
+
+    for each_mapping in mappings:
+        key = f"rules/{each_mapping.output_name}"
+        out_path = out_dir / each_mapping.output_name
+        missing = [source for source in each_mapping.sources if not source.is_file()]
+        if missing:
+            summary["warn"] += 1
+            if not quiet:
+                print(f"WARN     rules/{each_mapping.output_name} (missing source: {missing})")
+            continue
+
+        src_hash = _sources_hash(each_mapping.sources)
+        prev = entries_meta.get(key, {})
+        prev_src = prev.get("sources_hash", "")
+        prev_out = prev.get("output_hash", "")
+
+        if (
+            not force
+            and out_path.is_file()
+            and prev_src == src_hash
+            and prev_out
+            and sha256_bytes(out_path.read_bytes()) == prev_out
+        ):
+            summary["skip"] += 1
+            new_entries[key] = {"sources_hash": src_hash, "output_hash": prev_out}
+            continue
+
+        if (
+            not force
+            and out_path.is_file()
+            and prev_src == src_hash
+            and prev_out
+            and sha256_bytes(out_path.read_bytes()) != prev_out
+        ):
+            summary["tampered"] += 1
+            if not quiet:
+                print(f"TAMPERED rules/{each_mapping.output_name} (manual edit; regenerating)")
+
+        summary["update"] += 1
+        if not quiet:
+            print(f"UPDATE   rules/{each_mapping.output_name}")
+
+        body = apply_transform(
+            each_mapping.transform,
+            each_mapping.sources,
+            strip_leading_frontmatter=each_mapping.strip_leading_frontmatter,
+        )
+        full = _full_mdc(each_mapping, body)
+        out_hash = sha256_bytes(full.encode("utf-8"))
+        new_entries[key] = {"sources_hash": src_hash, "output_hash": out_hash}
+
+        if write_allowed:
+            out_path.write_text(full, encoding="utf-8", newline="\n")
+
+    expected = {each_mapping.output_name for each_mapping in mappings}
+    for each_path in out_dir.glob("*.mdc"):
+        if each_path.name not in expected:
+            summary["orphan"] += 1
+            if not quiet:
+                print(f"WARN     {each_path.relative_to(cursor)} (orphan — not generated by this tool)")
+
+    return summary, new_entries
+
+
+def run(argv: list[str] | None = None) -> int:
+    argument_parser = argparse.ArgumentParser(description="Sync Claude rules to Cursor .mdc files")
+    argument_parser.add_argument("--force", action="store_true", help="Regenerate all outputs")
+    argument_parser.add_argument("--dry-run", action="store_true", help="Print actions only")
+    argument_parser.add_argument("--check", action="store_true", help="Exit 1 if anything stale")
+    argument_parser.add_argument("--quiet", action="store_true", help="Minimal output when up to date")
+    args = argument_parser.parse_args(argv)
+
+    claude, cursor, out_dir, manifest_path = llm_layout_paths()
+    mappings = build_mappings(claude)
+    old_manifest = _load_manifest(manifest_path)
+    entries_meta: dict = old_manifest.get("entries", {})
+    docs_entries_meta: dict = old_manifest.get("docs_entries", {})
+
+    if args.check:
+        return _run_check(mappings, out_dir, entries_meta, claude, cursor, docs_entries_meta)
+
+    if not args.dry_run:
+        out_dir.mkdir(parents=True, exist_ok=True)
+    new_docs_entries = sync_canonical_docs(claude, cursor, args.dry_run, args.quiet)
+
+    summary, new_entries = _sync_rules(
+        mappings,
+        out_dir,
+        entries_meta,
+        force=args.force,
+        dry_run=args.dry_run,
+        quiet=args.quiet,
+        cursor=cursor,
+    )
+
+    manifest_out = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "generator_version": GENERATOR_VERSION,
+        "entries": new_entries,
+        "docs_entries": new_docs_entries,
+    }
+    if not args.dry_run:
+        manifest_path.write_text(json.dumps(manifest_out, indent=2) + "\n", encoding="utf-8")
+
+    if (
+        not args.quiet
+        and summary["skip"]
+        and not any((summary["update"], summary["tampered"], summary["warn"], summary["orphan"]))
+    ):
+        print(f"SKIP     all {summary['skip']} rule(s) unchanged")
+
+    return 0
+
+
+def main() -> int:
+    return run(sys.argv[1:])

package/scripts/sync_to_cursor/hashing.py

@@ -0,0 +1,7 @@
+"""Content hashing for manifest entries."""
+
+import hashlib
+
+
+def sha256_bytes(content_bytes: bytes) -> str:
+    return hashlib.sha256(content_bytes).hexdigest()

package/scripts/sync_to_cursor/paths.py

@@ -0,0 +1,18 @@
+"""Resolve Claude / Cursor layout paths (LLM_SETTINGS_ROOT or home)."""
+
+import os
+from pathlib import Path
+
+
+def llm_layout_paths() -> tuple[Path, Path, Path, Path]:
+    """Return (claude_dir, cursor_dir, rules_out_dir, manifest_path)."""
+    raw = os.environ.get("LLM_SETTINGS_ROOT", "").strip()
+    if raw:
+        base = Path(raw).expanduser().resolve()
+        claude = base / ".claude"
+        cursor = base / ".cursor"
+    else:
+        home = Path.home()
+        claude = home / ".claude"
+        cursor = home / ".cursor"
+    return claude, cursor, cursor / "rules", cursor / ".sync-manifest.json"

package/scripts/sync_to_cursor/rules.py

@@ -0,0 +1,321 @@
+"""Build Cursor .mdc bodies from Claude rules and docs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from sync_to_cursor.config import MAX_RULE_BODY_LINES
+
+
+def _parse_h2_sections(markdown: str) -> dict[str, str]:
+    parts = re.split(r"^## ", markdown, flags=re.MULTILINE)
+    sections: dict[str, str] = {}
+    for part in parts[1:]:
+        title_line, _, body = part.partition("\n")
+        sections[title_line.strip()] = body.strip()
+    return sections
+
+
+def _filter_core_principles(body: str) -> str:
+    lines = []
+    for line in body.splitlines():
+        if "readability-review" in line or "readability standard" in line:
+            continue
+        lines.append(line)
+    return "\n".join(lines).strip()
+
+
+def _limit_lines(text: str, max_lines: int) -> str:
+    lines = text.splitlines()
+    if len(lines) <= max_lines:
+        return text
+    return (
+        "\n".join(lines[:max_lines])
+        + "\n\n_(Truncated for Cursor rule length; see the synced reference in `.cursor/docs/` "
+        "(`CODE_RULES.md` or `TEST_QUALITY.md` as applicable) and follow its canonical source "
+        "under `~/.claude/system-prompts/software-engineer.xml` when needed.)_"
+    )
+
+
+def _strip_code_standards_blockquote(markdown: str) -> str:
+    lines = markdown.splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        if lines[i].startswith(">") and "MANDATORY REFERENCE" in lines[i]:
+            while i < len(lines) and lines[i].startswith(">"):
+                i += 1
+            while i < len(lines) and lines[i].strip() == "":
+                i += 1
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out).strip()
+
+
+def merge_code_standards(sources: tuple[Path, ...]) -> str:
+    code_standards_markdown = _strip_code_standards_blockquote(
+        sources[0].read_text(encoding="utf-8")
+    )
+    code_standards_markdown = "\n".join(
+        line for line in code_standards_markdown.splitlines() if not line.strip().startswith("- TDD ")
+    )
+    code_rules_markdown = sources[1].read_text(encoding="utf-8")
+    sections_by_heading = _parse_h2_sections(code_rules_markdown)
+    if not sections_by_heading:
+        pointer_fallback_note = (
+            "_(Full code-quality rules: `~/.claude/system-prompts/software-engineer.xml`"
+            " under `<code_quality>`.)_"
+        )
+        chunks = [code_standards_markdown, "", pointer_fallback_note]
+        return _limit_lines("\n\n".join(chunks), MAX_RULE_BODY_LINES)
+    include_order = [
+        "COMMENT PRESERVATION (ABSOLUTE RULE)",
+        "CORE PRINCIPLES",
+        "⚡ HOOK-ENFORCED RULES",
+        "4. CONFIG LOCATIONS",
+        "5. NO ABBREVIATIONS",
+        "6. COMPLETE TYPE HINTS",
+        "9. SELF-CONTAINED COMPONENTS",
+    ]
+    chunks = [
+        code_standards_markdown,
+        "",
+        "## Reference (full text: `.cursor/docs/CODE_RULES.md`)",
+    ]
+    for title in include_order:
+        body = sections_by_heading.get(title, "")
+        if title == "CORE PRINCIPLES":
+            body = _filter_core_principles(body)
+        if body:
+            chunks.append(f"## {title}\n\n{body}")
+    merged = "\n\n".join(chunks)
+    return _limit_lines(merged, MAX_RULE_BODY_LINES)
+
+
+def merge_test_quality(sources: tuple[Path, ...]) -> str:
+    testing = sources[0].read_text(encoding="utf-8").strip()
+    test_quality_markdown = sources[1].read_text(encoding="utf-8")
+    sections_by_heading = _parse_h2_sections(test_quality_markdown)
+    include_order = [
+        "Delete Useless Tests",
+        "Test Dependencies MUST FAIL",
+        "Core Testing Principles",
+        "React Testing Patterns",
+        "Test File Organization",
+    ]
+    chunks = [testing, "", "## Reference (full text: `.cursor/docs/TEST_QUALITY.md`)"]
+    for title in include_order:
+        body = sections_by_heading.get(title, "")
+        if body:
+            chunks.append(f"## {title}\n\n{body}")
+    merged = "\n\n".join(chunks)
+    return _limit_lines(merged, MAX_RULE_BODY_LINES)
+
+
+def strip_anthropic_refs(text: str) -> str:
+    out_lines: list[str] = []
+    for line in text.splitlines():
+        s = line.strip()
+        if s.startswith("Source:") and (
+            "anthropic" in s.lower()
+            or "claude.com" in s.lower()
+            or "docs.anthropic" in s.lower()
+        ):
+            continue
+        if "docs.anthropic.com" in line:
+            continue
+        out_lines.append(line)
+    text = "\n".join(out_lines)
+    text = re.sub(
+        r"<do_not_act_before_instructions>\s*",
+        "",
+        text,
+        flags=re.DOTALL,
+    )
+    text = re.sub(r"\s*</do_not_act_before_instructions>", "", text)
+    return text.strip()
+
+
+def verbatim(text: str) -> str:
+    return text.strip()
+
+
+def near_verbatim(text: str) -> str:
+    return strip_anthropic_refs(text)
+
+
+def strip_leading_yaml_frontmatter(text: str) -> str:
+    """Remove leading `---` ... `---` block (e.g. Claude `paths:`) so Cursor `.mdc` uses its own frontmatter."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return text
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            return "\n".join(lines[i + 1 :]).lstrip("\n")
+    return text
+
+
+TransformName = Literal["verbatim", "near_verbatim", "merge_code_standards", "merge_test_quality"]
+
+
+def apply_transform(
+    name: TransformName,
+    sources: tuple[Path, ...],
+    *,
+    strip_leading_frontmatter: bool = False,
+) -> str:
+    if name == "merge_code_standards":
+        return merge_code_standards(sources)
+    if name == "merge_test_quality":
+        return merge_test_quality(sources)
+    raw = "\n\n".join(p.read_text(encoding="utf-8") for p in sources)
+    if strip_leading_frontmatter:
+        raw = strip_leading_yaml_frontmatter(raw)
+    if name == "verbatim":
+        return verbatim(raw)
+    if name == "near_verbatim":
+        return near_verbatim(raw)
+    raise AssertionError(name)
+
+
+@dataclass(frozen=True)
+class RuleMapping:
+    key: str
+    sources: tuple[Path, ...]
+    output_name: str
+    always_apply: bool
+    globs: str | None
+    description: str
+    transform: TransformName
+    strip_leading_frontmatter: bool = False
+
+
+def _frontmatter(description: str, always_apply: bool, globs: str | None) -> str:
+    escaped_description = description.replace('"', '\\"')
+    lines = ["---", f'description: "{escaped_description}"']
+    if globs:
+        escaped_globs = globs.replace('"', '\\"')
+        lines.append(f'globs: "{escaped_globs}"')
+    lines.append(f"alwaysApply: {'true' if always_apply else 'false'}")
+    lines.append("---")
+    return "\n".join(lines) + "\n"
+
+
+def _full_mdc(mapping: RuleMapping, body: str) -> str:
+    generated_header = (
+        "<!-- Generated by sync-to-cursor.py — do not edit directly -->\n"
+        "<!-- Re-run: python ~/.claude/scripts/sync-to-cursor.py -->\n"
+        "<!-- Output: .cursor/rules/*.mdc, .cursor/docs/*.md"
+        " (see LLM_SETTINGS_ROOT in script docstring) -->\n"
+    )
+    return _frontmatter(mapping.description, mapping.always_apply, mapping.globs) + "\n" + generated_header + "\n" + body + "\n"
+
+
+def _read_paths_glob(rule_file: Path) -> str | None:
+    """Read `paths:` list from a Claude rule's YAML frontmatter; return as comma-separated Cursor glob string."""
+    if not rule_file.is_file():
+        return None
+    lines = rule_file.read_text(encoding="utf-8").splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    is_in_paths = False
+    all_paths: list[str] = []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        if line.startswith("paths:"):
+            is_in_paths = True
+            continue
+        if is_in_paths:
+            if line.startswith(" ") or line.startswith("\t"):
+                path_value = line.strip().lstrip("-").strip().strip('"').strip("'")
+                if path_value:
+                    all_paths.append(path_value)
+            else:
+                is_in_paths = False
+    return ",".join(all_paths) if all_paths else None
+
+
+def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
+    rules_directory = claude / "rules"
+    docs_directory = claude / "docs"
+    test_globs = "**/*.test.*,**/*.spec.*,**/test_*,**/*_test.*"
+    return (
+        RuleMapping(
+            "code-standards",
+            (rules_directory / "code-standards.md", docs_directory / "CODE_RULES.md"),
+            "code-standards.mdc",
+            True,
+            None,
+            "Core code standards: naming, types, config, hook-enforced rules",
+            "merge_code_standards",
+        ),
+        RuleMapping(
+            "tasklings-preferences",
+            (rules_directory / "tasklings-preferences.md",),
+            "tasklings-preferences.mdc",
+            False,
+            _read_paths_glob(rules_directory / "tasklings-preferences.md"),
+            "Tasklings: Prefer / Do / Always engineering preferences (scoped path)",
+            "verbatim",
+            True,
+        ),
+        RuleMapping(
+            "right-sized-engineering",
+            (rules_directory / "right-sized-engineering.md",),
+            "right-sized-engineering.mdc",
+            True,
+            None,
+            "Right-sized engineering and complexity budget",
+            "verbatim",
+        ),
+        RuleMapping(
+            "bdd",
+            (rules_directory / "bdd.md",),
+            "bdd.mdc",
+            True,
+            None,
+            "BDD: discovery-driven protocol (outside-in; Illustrate→Formulate→Automate)",
+            "verbatim",
+        ),
+        RuleMapping(
+            "test-quality",
+            (rules_directory / "testing.md", docs_directory / "TEST_QUALITY.md"),
+            "test-quality.mdc",
+            False,
+            test_globs,
+            "Testing quality for test files",
+            "merge_test_quality",
+        ),
+        RuleMapping(
+            "research-mode",
+            (rules_directory / "research-mode.md",),
+            "research-mode.mdc",
+            True,
+            None,
+            "Research mode: citations and I don't know",
+            "near_verbatim",
+        ),
+        RuleMapping(
+            "conservative-action",
+            (rules_directory / "conservative-action.md",),
+            "conservative-action.mdc",
+            True,
+            None,
+            "Prefer research over action when intent is unclear",
+            "near_verbatim",
+        ),
+        RuleMapping(
+            "explore-thoroughly",
+            (rules_directory / "explore-thoroughly.md",),
+            "explore-thoroughly.mdc",
+            True,
+            None,
+            "Explore codebase before committing to an approach",
+            "near_verbatim",
+        ),
+    )