claude-dev-env 8.12.0 → 8.13.0

package/scripts/sync_to_cursor/rules.py

@@ -1,494 +0,0 @@
-"""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 (
-    ALL_SKIPPED_RULE_FILE_NAMES,
-    CLAUDE_RULES_DIRECTORY_NAME,
-    MARKDOWN_SUFFIX,
-    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 each_part in parts[1:]:
-        title_line, _, body = each_part.partition("\n")
-        sections[title_line.strip()] = body.strip()
-    return sections
-
-
-def _filter_core_principles(body: str) -> str:
-    lines = []
-    for each_line in body.splitlines():
-        if "readability standard" in each_line:
-            continue
-        lines.append(each_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()
-
-
-_merged_mapping_key_order = (
-    "code-standards",
-    "tasklings-preferences",
-    "bdd",
-    "test-quality",
-    "research-mode",
-    "explore-thoroughly",
-)
-
-_code_standards_section_order = (
-    "COMMENT PRESERVATION",
-    "CORE PRINCIPLES",
-    "⚡ LINT-ENFORCED RULES",
-    "3. REUSE CONSTANTS / 4. CONFIG LOCATIONS",
-    "5. NO ABBREVIATIONS",
-    "6. COMPLETE TYPE HINTS",
-    "9. SELF-CONTAINED COMPONENTS",
-)
-
-_test_quality_section_order = (
-    "Delete Useless Tests",
-    "Test Dependencies MUST FAIL",
-    "Core Testing Principles",
-    "React Testing Patterns",
-    "Test File Organization",
-)
-
-
-def merge_code_standards(all_sources: tuple[Path, ...]) -> str:
-    """Merge the code-standards rule and CODE_RULES doc into one Cursor rule body.
-
-    Args:
-        all_sources: The code-standards rule path then the CODE_RULES doc path.
-
-    Returns:
-        The merged Cursor rule body, truncated to the maximum rule body length.
-    """
-    code_standards_markdown = _strip_code_standards_blockquote(
-        all_sources[0].read_text(encoding="utf-8")
-    )
-    code_standards_markdown = "\n".join(
-        each_line
-        for each_line in code_standards_markdown.splitlines()
-        if not each_line.strip().startswith("- TDD ")
-    )
-    code_rules_markdown = all_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)
-    chunks = [
-        code_standards_markdown,
-        "",
-        "## Reference (full text: `.cursor/docs/CODE_RULES.md`)",
-    ]
-    for each_title in _code_standards_section_order:
-        assert each_title in sections_by_heading, (
-            f"merge_code_standards: expected section absent from CODE_RULES.md: {each_title}"
-        )
-        body = sections_by_heading[each_title]
-        if each_title == "CORE PRINCIPLES":
-            body = _filter_core_principles(body)
-        if body:
-            chunks.append(f"## {each_title}\n\n{body}")
-    merged = "\n\n".join(chunks)
-    return _limit_lines(merged, MAX_RULE_BODY_LINES)
-
-
-def merge_test_quality(all_sources: tuple[Path, ...]) -> str:
-    """Merge the testing rule and TEST_QUALITY doc into one Cursor rule body.
-
-    Args:
-        all_sources: The testing rule path then the TEST_QUALITY doc path.
-
-    Returns:
-        The merged Cursor rule body, truncated to the maximum rule body length.
-    """
-    testing = strip_leading_yaml_frontmatter(
-        all_sources[0].read_text(encoding="utf-8")
-    ).strip()
-    test_quality_markdown = all_sources[1].read_text(encoding="utf-8")
-    sections_by_heading = _parse_h2_sections(test_quality_markdown)
-    chunks = [testing, "", "## Reference (full text: `.cursor/docs/TEST_QUALITY.md`)"]
-    for each_title in _test_quality_section_order:
-        assert each_title in sections_by_heading, (
-            f"merge_test_quality: expected section absent from TEST_QUALITY.md: {each_title}"
-        )
-        body = sections_by_heading[each_title]
-        if body:
-            chunks.append(f"## {each_title}\n\n{body}")
-    merged = "\n\n".join(chunks)
-    return _limit_lines(merged, MAX_RULE_BODY_LINES)
-
-
-def strip_anthropic_refs(text: str) -> str:
-    """Remove Anthropic source citations and the do-not-act wrapper from rule text.
-
-    Args:
-        text: The rule body to clean.
-
-    Returns:
-        The rule body without Anthropic citation lines or the wrapper tags.
-    """
-    out_lines: list[str] = []
-    for each_line in text.splitlines():
-        stripped_line = each_line.strip()
-        if stripped_line.startswith("Source:") and (
-            "anthropic" in stripped_line.lower()
-            or "claude.com" in stripped_line.lower()
-            or "docs.anthropic" in stripped_line.lower()
-        ):
-            continue
-        if "docs.anthropic.com" in each_line:
-            continue
-        out_lines.append(each_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 a leading `---` ... `---` block so Cursor `.mdc` keeps its own frontmatter.
-
-    Args:
-        text: The rule body that may open with a Claude YAML frontmatter block.
-
-    Returns:
-        The rule body with any leading frontmatter block removed.
-    """
-    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,
-    all_sources: tuple[Path, ...],
-    *,
-    strip_leading_frontmatter: bool = False,
-) -> str:
-    """Run the named transform over the source files and return the rule body.
-
-    Args:
-        name: The transform identifier selecting how the sources combine.
-        all_sources: The source files the transform reads.
-        strip_leading_frontmatter: When True, drop a leading YAML frontmatter
-            block from the raw concatenation before a verbatim transform.
-
-    Returns:
-        The transformed Cursor rule body.
-
-    Raises:
-        AssertionError: When *name* is not a recognized transform identifier.
-    """
-    if name == "merge_code_standards":
-        return merge_code_standards(all_sources)
-    if name == "merge_test_quality":
-        return merge_test_quality(all_sources)
-    raw = "\n\n".join(each_source.read_text(encoding="utf-8") for each_source in all_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 the `paths:` list from a Claude rule's YAML frontmatter as a Cursor glob.
-
-    Args:
-        rule_file: The Claude rule file whose frontmatter may declare `paths:`.
-
-    Returns:
-        The comma-separated glob string, or None when the rule declares no paths.
-    """
-    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 each_line in lines[1:]:
-        if each_line.strip() == "---":
-            break
-        if each_line.startswith("paths:"):
-            is_in_paths = True
-            continue
-        if is_in_paths:
-            if each_line.startswith(" ") or each_line.startswith("\t"):
-                stripped_path = each_line.strip().lstrip("-").strip().strip('"').strip("'")
-                if stripped_path:
-                    all_paths.append(stripped_path)
-            else:
-                is_in_paths = False
-    return ",".join(all_paths) if all_paths else None
-
-
-def _require_paths_glob(rule_file: Path) -> str | None:
-    """Return the path glob for an optional rule, requiring frontmatter when it exists.
-
-    Args:
-        rule_file: The Claude rule file whose frontmatter may declare `paths:`.
-
-    Returns:
-        The comma-separated glob string, or None when the rule file is absent.
-
-    Raises:
-        AssertionError: When the rule file exists but declares no `paths:`
-            frontmatter, which would silently disable the rule in Cursor.
-    """
-    if not rule_file.is_file():
-        return None
-    paths_glob = _read_paths_glob(rule_file)
-    assert paths_glob is not None, (
-        f"{rule_file.name}: path-scoped rule exists but declares no `paths:` frontmatter; "
-        "add a `paths:` list or remove the file"
-    )
-    return paths_glob
-
-
-def _always_apply_mappings(rules_directory: Path, docs_directory: Path) -> tuple[RuleMapping, ...]:
-    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(
-            "bdd",
-            (rules_directory / "bdd.md",),
-            "bdd.mdc",
-            True,
-            None,
-            "BDD: discovery-driven protocol (outside-in; Illustrate→Formulate→Automate)",
-            "verbatim",
-        ),
-        RuleMapping(
-            "research-mode",
-            (rules_directory / "research-mode.md",),
-            "research-mode.mdc",
-            True,
-            None,
-            "Research mode: citations and I don't know",
-            "near_verbatim",
-        ),
-        RuleMapping(
-            "explore-thoroughly",
-            (rules_directory / "explore-thoroughly.md",),
-            "explore-thoroughly.mdc",
-            True,
-            None,
-            "Explore codebase before committing to an approach",
-            "near_verbatim",
-        ),
-    )
-
-
-def _path_scoped_mappings(rules_directory: Path, docs_directory: Path) -> tuple[RuleMapping, ...]:
-    return (
-        RuleMapping(
-            "tasklings-preferences",
-            (rules_directory / "tasklings-preferences.md",),
-            "tasklings-preferences.mdc",
-            False,
-            _require_paths_glob(rules_directory / "tasklings-preferences.md"),
-            "Tasklings: Prefer / Do / Always engineering preferences (scoped path)",
-            "verbatim",
-            True,
-        ),
-        RuleMapping(
-            "test-quality",
-            (rules_directory / "testing.md", docs_directory / "TEST_QUALITY.md"),
-            "test-quality.mdc",
-            False,
-            _require_paths_glob(rules_directory / "testing.md"),
-            "Testing quality for test files",
-            "merge_test_quality",
-        ),
-    )
-
-
-def _description_from_rule_file(rule_file: Path, fallback_key: str) -> str:
-    """Return the first markdown heading, or the rule key with spaces.
-
-    Args:
-        rule_file: Claude rule markdown to read.
-        fallback_key: Stem used when the file has no heading.
-
-    Returns:
-        A one-line Cursor `description` value.
-    """
-    for each_line in rule_file.read_text(encoding="utf-8").splitlines():
-        stripped = each_line.strip()
-        if stripped.startswith("# "):
-            return stripped[2:].strip()
-    return fallback_key.replace("-", " ")
-
-
-def _discovered_mappings(
-    rules_directory: Path, all_covered_source_names: set[str]
-) -> tuple[RuleMapping, ...]:
-    """Map remaining `*.md` rule files to `<stem>.mdc` Cursor rules.
-
-    Args:
-        rules_directory: Claude `rules/` directory.
-        all_covered_source_names: Rule filenames already claimed by curated mappings.
-
-    Returns:
-        One mapping per remaining markdown rule, sorted by filename.
-    """
-    if not rules_directory.is_dir():
-        return ()
-    all_discovered: list[RuleMapping] = []
-    for each_rule_file in sorted(rules_directory.glob("*.md")):
-        if each_rule_file.name in ALL_SKIPPED_RULE_FILE_NAMES:
-            continue
-        if each_rule_file.name in all_covered_source_names:
-            continue
-        key = each_rule_file.stem
-        paths_glob = _read_paths_glob(each_rule_file)
-        has_paths = paths_glob is not None
-        all_discovered.append(
-            RuleMapping(
-                key,
-                (each_rule_file,),
-                f"{key}.mdc",
-                not has_paths,
-                paths_glob,
-                _description_from_rule_file(each_rule_file, key),
-                "verbatim",
-                strip_leading_frontmatter=has_paths,
-            )
-        )
-    return tuple(all_discovered)
-
-
-def build_mappings(claude: Path) -> tuple[RuleMapping, ...]:
-    """Resolve every rule into a concrete Cursor mapping against a Claude layout.
-
-    Args:
-        claude: The Claude layout root holding the `rules` and `docs` directories.
-
-    Returns:
-        One RuleMapping per rule, each path-scoped rule carrying a glob derived
-        from its source rule's `paths:` frontmatter. Curated mappings come first,
-        then one generated mapping per remaining `rules/*.md` file.
-    """
-    rules_directory = claude / "rules"
-    docs_directory = claude / "docs"
-    all_curated = (
-        *_always_apply_mappings(rules_directory, docs_directory),
-        *_path_scoped_mappings(rules_directory, docs_directory),
-    )
-    mapping_by_key = {each_mapping.key: each_mapping for each_mapping in all_curated}
-    assert set(mapping_by_key) == set(_merged_mapping_key_order)
-    ordered_curated = tuple(mapping_by_key[each_key] for each_key in _merged_mapping_key_order)
-    all_covered_source_names = {
-        each_source.name
-        for each_mapping in ordered_curated
-        for each_source in each_mapping.sources
-        if each_source.suffix == MARKDOWN_SUFFIX
-        and each_source.parent.name == CLAUDE_RULES_DIRECTORY_NAME
-    }
-    return ordered_curated + _discovered_mappings(
-        rules_directory, all_covered_source_names
-    )

package/scripts/sync_to_cursor.py

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-"""Generate Cursor rules from ~/.claude/rules and docs.
-
-Writes to <profile or repo>/.cursor/rules/*.mdc, .cursor/docs/*.md (byte copies of
-CODE_RULES.md and TEST_QUALITY.md when present), and .cursor/.sync-manifest.json.
-If LLM_SETTINGS_ROOT is set to the llm-settings repo root, uses <root>/.claude and
-<root>/.cursor. Otherwise uses ~/.claude and ~/.cursor (after junction install).
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-from sync_to_cursor.engine import main
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/tests/test_engine.py

@@ -1,101 +0,0 @@
-"""Tests for sync_to_cursor engine CLI roots."""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-import pytest
-
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-from sync_to_cursor.engine import run as run_sync_to_cursor
-
-_CODE_STANDARDS_SECTION_ORDER = (
-    "COMMENT PRESERVATION",
-    "CORE PRINCIPLES",
-    "⚡ LINT-ENFORCED RULES",
-    "3. REUSE CONSTANTS / 4. CONFIG LOCATIONS",
-    "5. NO ABBREVIATIONS",
-    "6. COMPLETE TYPE HINTS",
-    "9. SELF-CONTAINED COMPONENTS",
-)
-_TEST_QUALITY_SECTION_ORDER = (
-    "Delete Useless Tests",
-    "Test Dependencies MUST FAIL",
-    "Core Testing Principles",
-    "React Testing Patterns",
-    "Test File Organization",
-)
-
-
-def _write_minimal_curated_rules(rules_directory: Path) -> None:
-    rules_directory.mkdir(parents=True, exist_ok=True)
-    (rules_directory / "code-standards.md").write_text(
-        "# Code standards stub\n", encoding="utf-8"
-    )
-    (rules_directory / "tasklings-preferences.md").write_text(
-        '---\npaths:\n  - "Y:/x/**"\n---\n\n# Tasklings\n',
-        encoding="utf-8",
-    )
-    (rules_directory / "bdd.md").write_text("# BDD\n", encoding="utf-8")
-    (rules_directory / "testing.md").write_text(
-        '---\npaths:\n  - "**/test_*.py"\n---\n\n# Testing\n',
-        encoding="utf-8",
-    )
-    (rules_directory / "research-mode.md").write_text("# RM\n", encoding="utf-8")
-    (rules_directory / "explore-thoroughly.md").write_text("# ET\n", encoding="utf-8")
-
-
-def _write_minimal_docs(docs_directory: Path) -> None:
-    docs_directory.mkdir(parents=True, exist_ok=True)
-    (docs_directory / "CODE_RULES.md").write_text(
-        "\n\n".join(f"## {title}\n\nalpha" for title in _CODE_STANDARDS_SECTION_ORDER)
-        + "\n",
-        encoding="utf-8",
-    )
-    (docs_directory / "TEST_QUALITY.md").write_text(
-        "\n\n".join(f"## {title}\n\nbeta" for title in _TEST_QUALITY_SECTION_ORDER)
-        + "\n",
-        encoding="utf-8",
-    )
-
-
-def test_explicit_roots_write_stem_named_mdc(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    claude = tmp_path / "claude-home"
-    cursor = tmp_path / "cursor-home"
-    _write_minimal_curated_rules(claude / "rules")
-    _write_minimal_docs(claude / "docs")
-    (claude / "rules" / "asd-ste100-language.md").write_text(
-        "# ASD-STE100 Language Policy\n\nUse short sentences.\n",
-        encoding="utf-8",
-    )
-    (claude / "rules" / "CLAUDE.md").write_text("# Inventory\n", encoding="utf-8")
-    monkeypatch.delenv("LLM_SETTINGS_ROOT", raising=False)
-    assert cursor.exists() is False
-    assert (
-        run_sync_to_cursor(
-            [
-                "--force",
-                "--claude-root",
-                str(claude),
-                "--cursor-root",
-                str(cursor),
-            ]
-        )
-        == 0
-    )
-    generated = (cursor / "rules" / "asd-ste100-language.mdc").read_text(encoding="utf-8")
-    assert 'description: "ASD-STE100 Language Policy"' in generated
-    assert "alwaysApply: true" in generated
-    assert "Use short sentences." in generated
-    assert not (cursor / "rules" / "CLAUDE.mdc").is_file()
-
-
-def test_explicit_roots_require_both_flags(tmp_path: Path) -> None:
-    with pytest.raises(SystemExit):
-        run_sync_to_cursor(["--force", "--claude-root", str(tmp_path)])