claudekit-codex-sync 0.1.0

package/src/claudekit_codex_sync/dep_bootstrapper.py

@@ -0,0 +1,73 @@
+"""Dependency bootstrap for skills."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict
+
+from .utils import eprint, is_excluded_path, run_cmd
+
+
+def bootstrap_deps(
+    *,
+    codex_home: Path,
+    include_mcp: bool,
+    include_test_deps: bool,
+    dry_run: bool,
+) -> Dict[str, int]:
+    """Bootstrap Python and Node dependencies for skills."""
+    skills_dir = codex_home / "skills"
+    venv_dir = skills_dir / ".venv"
+
+    if not shutil.which("python3"):
+        from .utils import SyncError
+        raise SyncError("python3 not found")
+
+    py_ok = py_fail = node_ok = node_fail = 0
+
+    run_cmd(["python3", "-m", "venv", str(venv_dir)], dry_run=dry_run)
+    py_bin = venv_dir / "bin" / "python3"
+    run_cmd([str(py_bin), "-m", "pip", "install", "--upgrade", "pip"], dry_run=dry_run)
+
+    req_files = sorted(skills_dir.rglob("requirements*.txt"))
+    for req in req_files:
+        rel = req.relative_to(skills_dir).as_posix()
+        if is_excluded_path(req.parts):
+            continue
+        if not include_test_deps and "/test" in rel:
+            continue
+        if not include_mcp and ("mcp-builder" in req.parts or "mcp-management" in req.parts):
+            continue
+        try:
+            run_cmd([str(py_bin), "-m", "pip", "install", "-r", str(req)], dry_run=dry_run)
+            py_ok += 1
+        except subprocess.CalledProcessError:
+            py_fail += 1
+            eprint(f"python deps failed: {req}")
+
+    npm = shutil.which("npm")
+    if npm:
+        pkg_files = sorted(skills_dir.rglob("package.json"))
+        for pkg in pkg_files:
+            rel = pkg.relative_to(skills_dir).as_posix()
+            if is_excluded_path(pkg.parts):
+                continue
+            if not include_mcp and ("mcp-builder" in pkg.parts or "mcp-management" in pkg.parts):
+                continue
+            try:
+                run_cmd([npm, "install", "--prefix", str(pkg.parent)], dry_run=dry_run)
+                node_ok += 1
+            except subprocess.CalledProcessError:
+                node_fail += 1
+                eprint(f"node deps failed: {pkg.parent}")
+    else:
+        eprint("npm not found; skipping Node dependency bootstrap")
+
+    return {
+        "python_ok": py_ok,
+        "python_fail": py_fail,
+        "node_ok": node_ok,
+        "node_fail": node_fail,
+    }

package/src/claudekit_codex_sync/path_normalizer.py

@@ -0,0 +1,248 @@
+"""Path normalization for Codex compatibility."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+from .constants import (
+    AGENT_TOML_REPLACEMENTS,
+    CLAUDE_SYNTAX_ADAPTATIONS,
+    SKILL_MD_REPLACEMENTS,
+)
+from .utils import apply_replacements, load_template, write_text_if_changed
+
+
+def normalize_files(
+    *,
+    codex_home: Path,
+    include_mcp: bool,
+    dry_run: bool,
+) -> int:
+    """Normalize paths in skill files and claudekit files."""
+    changed = 0
+    skills_dir = codex_home / "skills"
+    claudekit_dir = codex_home / "claudekit"
+
+    for path in sorted(skills_dir.rglob("SKILL.md")):
+        if ".system" in path.parts:
+            continue
+        rel = path.relative_to(codex_home).as_posix()
+        if not include_mcp and any(m in rel for m in ("/mcp-builder/", "/mcp-management/")):
+            continue
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        new_text = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+        if new_text != text:
+            changed += 1
+            print(f"normalize: {rel}")
+            if not dry_run:
+                path.write_text(new_text, encoding="utf-8")
+
+    for path in sorted(claudekit_dir.rglob("*.md")):
+        rel = path.relative_to(codex_home).as_posix()
+        text = path.read_text(encoding="utf-8", errors="ignore")
+        new_text = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+        if new_text != text:
+            changed += 1
+            print(f"normalize: {rel}")
+            if not dry_run:
+                path.write_text(new_text, encoding="utf-8")
+
+    copy_script = skills_dir / "copywriting" / "scripts" / "extract-writing-styles.py"
+    if patch_copywriting_script(copy_script, dry_run=dry_run):
+        changed += 1
+        print("normalize: skills/copywriting/scripts/extract-writing-styles.py")
+
+    default_style = skills_dir / "copywriting" / "assets" / "writing-styles" / "default.md"
+    fallback_style = skills_dir / "copywriting" / "references" / "writing-styles.md"
+    if not default_style.exists() and fallback_style.exists():
+        changed += 1
+        print("add: skills/copywriting/assets/writing-styles/default.md")
+        if not dry_run:
+            default_style.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(fallback_style, default_style)
+
+    command_map = codex_home / "claudekit" / "commands" / "codex-command-map.md"
+    template = load_template("command-map.md")
+    if write_text_if_changed(command_map, template, dry_run=dry_run):
+        changed += 1
+        print("upsert: claudekit/commands/codex-command-map.md")
+
+    return changed
+
+
+def convert_agents_md_to_toml(*, codex_home: Path, dry_run: bool) -> int:
+    """Convert ClaudeKit agent .md files to Codex .toml format."""
+    from .constants import (
+        CLAUDE_MODEL_REASONING_EFFORT,
+        CLAUDE_TO_CODEX_MODELS,
+        READ_ONLY_AGENT_ROLES,
+    )
+
+    agents_dir = codex_home / "agents"
+    if not agents_dir.exists():
+        return 0
+
+    converted = 0
+    for md_file in sorted(agents_dir.glob("*.md")):
+        text = md_file.read_text(encoding="utf-8")
+        # Parse YAML frontmatter
+        if not text.startswith("---"):
+            continue
+        parts = text.split("---", 2)
+        if len(parts) < 3:
+            continue
+
+        frontmatter = parts[1].strip()
+        body = parts[2].strip()
+
+        # Extract fields from frontmatter
+        claude_model = ""
+        for line in frontmatter.splitlines():
+            m = re.match(r"^model:\s*(.+)$", line)
+            if m:
+                claude_model = m.group(1).strip().strip("'\"")
+
+        # Map model
+        codex_model = CLAUDE_TO_CODEX_MODELS.get(claude_model, "gpt-5.3-codex")
+        effort = CLAUDE_MODEL_REASONING_EFFORT.get(claude_model, "high")
+
+        # Determine sandbox mode
+        slug = md_file.stem.replace("-", "_")
+        if slug in READ_ONLY_AGENT_ROLES:
+            sandbox = "read-only"
+        else:
+            sandbox = "workspace-write"
+
+        # Build TOML
+        toml_lines = []
+        if codex_model:
+            toml_lines.append(f'model = "{codex_model}"')
+            toml_lines.append(f'model_reasoning_effort = "{effort}"')
+        toml_lines.append(f'sandbox_mode = "{sandbox}"')
+        toml_lines.append("")
+        # Escape triple quotes in body
+        safe_body = body.replace('"""', '\\"\\"\\"\\"')
+        toml_lines.append(f'developer_instructions = """\n{safe_body}\n"""')
+
+        toml_content = "\n".join(toml_lines) + "\n"
+        toml_file = agents_dir / f"{slug}.toml"
+
+        if not dry_run:
+            toml_file.write_text(toml_content, encoding="utf-8")
+        converted += 1
+        print(f"convert: agents/{md_file.name} → agents/{slug}.toml ({codex_model}, {sandbox})")
+
+    return converted
+
+
+def normalize_agent_tomls(*, codex_home: Path, dry_run: bool) -> int:
+    """Normalize paths and models in agent TOML files."""
+    from .constants import (
+        CLAUDE_MODEL_REASONING_EFFORT,
+        CLAUDE_TO_CODEX_MODELS,
+        READ_ONLY_AGENT_ROLES,
+    )
+
+    agents_dir = codex_home / "agents"
+    if not agents_dir.exists():
+        return 0
+
+    # First convert any .md agents to .toml
+    convert_agents_md_to_toml(codex_home=codex_home, dry_run=dry_run)
+
+    changed = 0
+    for toml_file in sorted(agents_dir.glob("*.toml")):
+        text = toml_file.read_text(encoding="utf-8")
+        new_text = apply_replacements(text, AGENT_TOML_REPLACEMENTS)
+        new_text = apply_replacements(new_text, CLAUDE_SYNTAX_ADAPTATIONS)
+
+        # Map commented Claude models to active Codex models
+        for claude_name, codex_model in CLAUDE_TO_CODEX_MODELS.items():
+            pattern = rf'^#\s*model\s*=\s*"{claude_name}"\s*$'
+            if re.search(pattern, new_text, re.MULTILINE):
+                effort = CLAUDE_MODEL_REASONING_EFFORT.get(claude_name, "high")
+                if codex_model:
+                    replacement = f'model = "{codex_model}"\nmodel_reasoning_effort = "{effort}"'
+                else:
+                    replacement = ""
+                new_text = re.sub(pattern, replacement, new_text, flags=re.MULTILINE)
+
+        # Set read-only sandbox for appropriate roles
+        slug = toml_file.stem
+        if slug in READ_ONLY_AGENT_ROLES:
+            new_text = re.sub(
+                r'^sandbox_mode\s*=\s*"workspace-write"',
+                'sandbox_mode = "read-only"',
+                new_text,
+                flags=re.MULTILINE,
+            )
+
+        if new_text != text:
+            changed += 1
+            if not dry_run:
+                toml_file.write_text(new_text, encoding="utf-8")
+    return changed
+
+
+def patch_copywriting_script(copy_script: Path, *, dry_run: bool) -> bool:
+    """Patch copywriting script for Codex compatibility."""
+    from .utils import SyncError
+
+    if not copy_script.exists():
+        return False
+
+    text = copy_script.read_text(encoding="utf-8")
+    original = text
+    if "CODEX_HOME = Path(os.environ.get('CODEX_HOME'" in text:
+        return False
+
+    new_func = """def find_project_root(start_dir: Path) -> Path:
+    \"\"\"Find project root by preferring a directory that contains assets/writing-styles.\"\"\"
+    search_chain = [start_dir] + list(start_dir.parents)
+    for parent in search_chain:
+        if (parent / 'assets' / 'writing-styles').exists():
+            return parent
+    for parent in search_chain:
+        if (parent / 'SKILL.md').exists():
+            return parent
+    for parent in search_chain:
+        if (parent / '.codex').exists() or (parent / '.claude').exists():
+            return parent
+    return start_dir
+"""
+
+    text, count_func = re.subn(
+        r"def find_project_root\(start_dir: Path\) -> Path:\n(?:    .*\n)+?    return start_dir\n",
+        new_func,
+        text,
+        count=1,
+    )
+
+    new_block = """PROJECT_ROOT = find_project_root(Path(__file__).parent)
+STYLES_DIR = PROJECT_ROOT / 'assets' / 'writing-styles'
+CODEX_HOME = Path(os.environ.get('CODEX_HOME', str(Path.home() / '.codex')))
+
+_ai_multimodal_candidates = [
+    PROJECT_ROOT / '.claude' / 'skills' / 'ai-multimodal' / 'scripts',
+    CODEX_HOME / 'skills' / 'ai-multimodal' / 'scripts',
+]
+AI_MULTIMODAL_SCRIPTS = next((p for p in _ai_multimodal_candidates if p.exists()), _ai_multimodal_candidates[-1])
+"""
+
+    text, count_block = re.subn(
+        r"PROJECT_ROOT = find_project_root\(Path\(__file__\)\.parent\)\nSTYLES_DIR = PROJECT_ROOT / 'assets' / 'writing-styles'\nAI_MULTIMODAL_SCRIPTS = PROJECT_ROOT / '.claude' / 'skills' / 'ai-multimodal' / 'scripts'\n",
+        new_block,
+        text,
+        count=1,
+    )
+
+    if count_func == 0 or count_block == 0:
+        raise SyncError("copywriting patch failed: upstream pattern changed")
+
+    if text == original:
+        return False
+    if not dry_run:
+        copy_script.write_text(text, encoding="utf-8")
+    return True

package/src/claudekit_codex_sync/prompt_exporter.py

@@ -0,0 +1,89 @@
+"""Prompt export functionality."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Set
+
+from .constants import PROMPT_MANIFEST, PROMPT_REPLACEMENTS
+from .utils import apply_replacements, load_manifest, save_manifest, write_bytes_if_changed
+
+
+def ensure_frontmatter(content: str, command_path: str) -> str:
+    """Ensure content has YAML frontmatter."""
+    if content.lstrip().startswith("---"):
+        return content
+    return f"---\ndescription: ClaudeKit compatibility prompt for /{command_path}\n---\n\n{content}"
+
+
+def export_prompts(
+    *,
+    codex_home: Path,
+    include_mcp: bool,
+    dry_run: bool,
+) -> Dict[str, int]:
+    """Export prompts from claudekit/commands to prompts directory."""
+    from .utils import SyncError
+
+    source = codex_home / "claudekit" / "commands"
+    prompts_dir = codex_home / "prompts"
+    manifest_path = prompts_dir / PROMPT_MANIFEST
+
+    if not source.exists():
+        if dry_run:
+            print(f"skip: prompt export dry-run requires existing {source}")
+            return {"added": 0, "updated": 0, "skipped": 0, "removed": 0, "collisions": 0, "total_generated": 0}
+        raise SyncError(f"Prompt source directory not found: {source}")
+
+    old_manifest = load_manifest(manifest_path)
+    files = sorted(source.rglob("*.md"))
+    generated: Set[str] = set()
+    added = updated = skipped = removed = collisions = 0
+
+    if not dry_run:
+        prompts_dir.mkdir(parents=True, exist_ok=True)
+
+    for src in files:
+        rel = src.relative_to(source).as_posix()
+        base = src.name
+        if base == "codex-command-map.md":
+            skipped += 1
+            print(f"skip: {rel}")
+            continue
+        if base == "use-mcp.md" and not include_mcp:
+            skipped += 1
+            print(f"skip: {rel}")
+            continue
+
+        prompt_name = rel[:-3].replace("/", "-") + ".md"
+        dst = prompts_dir / prompt_name
+        text = src.read_text(encoding="utf-8", errors="ignore")
+        text = apply_replacements(text, PROMPT_REPLACEMENTS)
+        text = ensure_frontmatter(text, rel[:-3])
+        data = text.encode("utf-8")
+
+        if dst.exists() and prompt_name not in old_manifest:
+            collisions += 1
+            print(f"skip(collision): {prompt_name}")
+            continue
+
+        generated.add(prompt_name)
+        changed, is_added = write_bytes_if_changed(dst, data, mode=0o644, dry_run=dry_run)
+        if changed:
+            if is_added:
+                added += 1
+                print(f"add: {prompt_name} <= {rel}")
+            else:
+                updated += 1
+                print(f"update: {prompt_name} <= {rel}")
+
+    for name in sorted(old_manifest - generated):
+        target = prompts_dir / name
+        if target.exists():
+            removed += 1
+            print(f"remove(stale): {name}")
+            if not dry_run:
+                target.unlink()
+
+    save_manifest(manifest_path, generated, dry_run=dry_run)
+    return {"added": added, "updated": updated, "skipped": skipped, "removed": removed, "collisions": collisions, "total_generated": len(generated)}

package/src/claudekit_codex_sync/runtime_verifier.py

@@ -0,0 +1,32 @@
+"""Runtime verification."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+from .utils import run_cmd
+
+
+def verify_runtime(*, codex_home: Path, dry_run: bool) -> Dict[str, Any]:
+    """Verify runtime health after sync."""
+    if dry_run:
+        return {"skipped": True}
+
+    run_cmd(["codex", "--help"], dry_run=False)
+
+    copy_script = codex_home / "skills" / "copywriting" / "scripts" / "extract-writing-styles.py"
+    py_bin = codex_home / "skills" / ".venv" / "bin" / "python3"
+    copywriting_ok = False
+    if copy_script.exists() and py_bin.exists():
+        run_cmd([str(py_bin), str(copy_script), "--list"], dry_run=False)
+        copywriting_ok = True
+
+    prompts_count = len(list((codex_home / "prompts").glob("*.md")))
+    skills_count = len(list((codex_home / "skills").rglob("SKILL.md")))
+    return {
+        "codex_help": "ok",
+        "copywriting": "ok" if copywriting_ok else "skipped",
+        "prompts": prompts_count,
+        "skills": skills_count,
+    }

package/src/claudekit_codex_sync/source_resolver.py

@@ -0,0 +1,78 @@
+"""Source resolution for ClaudeKit zip or live directory."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .utils import SyncError
+
+
+def find_latest_zip(explicit_zip: Optional[Path]) -> Path:
+    """Find the latest ClaudeKit zip file."""
+    if explicit_zip:
+        p = explicit_zip.expanduser().resolve()
+        if not p.exists():
+            raise SyncError(f"Zip not found: {p}")
+        return p
+
+    candidates: List[Path] = []
+    roots = {Path("/tmp"), Path(tempfile.gettempdir())}
+    for root in roots:
+        if root.exists():
+            candidates.extend(root.glob("claudekit-*/*.zip"))
+
+    if not candidates:
+        raise SyncError("No ClaudeKit zip found. Expected /tmp/claudekit-*/*.zip")
+
+    latest = max(candidates, key=lambda p: p.stat().st_mtime)
+    return latest.resolve()
+
+
+def detect_claude_source() -> Path:
+    """Auto-detect Claude Code installation directory."""
+    candidates = [
+        Path.home() / ".claude",
+        Path(os.environ.get("USERPROFILE", "")) / ".claude",
+    ]
+    for p in candidates:
+        if p.exists() and (p / "skills").is_dir():
+            return p
+    raise SyncError("Claude Code not found. Use --source-dir to specify.")
+
+
+def validate_source(source: Path) -> Dict[str, bool]:
+    """Validate source directory structure."""
+    return {
+        "skills": (source / "skills").is_dir(),
+        "agents": (source / "agents").is_dir(),
+        "commands": (source / "commands").is_dir(),
+        "rules": (source / "rules").is_dir(),
+        "claude_md": (source / "CLAUDE.md").is_file(),
+    }
+
+
+def collect_skill_entries(zf: zipfile.ZipFile) -> Dict[str, List[Tuple[str, str]]]:
+    """Collect skill entries from zip file."""
+    skill_files: Dict[str, List[Tuple[str, str]]] = {}
+    for name in zf.namelist():
+        if name.endswith("/") or not name.startswith(".claude/skills/"):
+            continue
+        rel = name[len(".claude/skills/") :]
+        parts = rel.split("/", 1)
+        if len(parts) != 2:
+            continue
+        skill, inner = parts
+        skill_files.setdefault(skill, []).append((name, inner))
+    return skill_files
+
+
+def zip_mode(info: zipfile.ZipInfo) -> Optional[int]:
+    """Extract Unix mode from ZipInfo."""
+    unix_mode = (info.external_attr >> 16) & 0o777
+    if unix_mode:
+        return unix_mode
+    return None

package/src/claudekit_codex_sync/sync_registry.py

@@ -0,0 +1,77 @@
+"""Sync registry with SHA-256 checksums and backup support."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .utils import compute_hash, create_backup
+
+REGISTRY_FILE = ".claudekit-sync-registry.json"
+
+
+def load_registry(codex_home: Path) -> Dict[str, Any]:
+    """Load sync registry from disk."""
+    registry_path = codex_home / REGISTRY_FILE
+    if not registry_path.exists():
+        return {
+            "version": 1,
+            "lastSync": None,
+            "sourceDir": None,
+            "entries": {},
+        }
+    return json.loads(registry_path.read_text(encoding="utf-8"))
+
+
+def save_registry(codex_home: Path, registry: Dict[str, Any]) -> None:
+    """Save sync registry to disk."""
+    registry_path = codex_home / REGISTRY_FILE
+    registry["lastSync"] = datetime.now(timezone.utc).isoformat()
+    registry_path.write_text(json.dumps(registry, indent=2), encoding="utf-8")
+
+
+def check_user_edit(entry: Dict[str, str], target: Path) -> bool:
+    """Check if user has modified the file since last sync."""
+    if not target.exists():
+        return False
+    current_hash = compute_hash(target)
+    return current_hash != entry.get("targetHash", "")
+
+
+def update_entry(
+    registry: Dict[str, Any],
+    rel_path: str,
+    source: Path,
+    target: Path,
+) -> None:
+    """Update registry entry after sync."""
+    source_hash = compute_hash(source) if source.exists() else ""
+    target_hash = compute_hash(target) if target.exists() else ""
+    registry["entries"][rel_path] = {
+        "sourceHash": source_hash,
+        "targetHash": target_hash,
+        "syncedAt": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def maybe_backup(
+    registry: Dict[str, Any],
+    rel_path: str,
+    target: Path,
+    respect_edits: bool,
+) -> Optional[Path]:
+    """Backup file if user has edited it and respect_edits is enabled."""
+    if not target.exists():
+        return None
+    entry = registry.get("entries", {}).get(rel_path)
+    if not entry:
+        return None
+    if not respect_edits:
+        return None
+    if check_user_edit(entry, target):
+        backup = create_backup(target)
+        print(f"backup(user-edit): {rel_path} -> {backup.name}")
+        return backup
+    return None