claudekit-codex-sync 0.1.0

package/src/claudekit_codex_sync/utils.py

@@ -0,0 +1,130 @@
+"""Utility functions for ClaudeKit Codex Sync."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+
+class SyncError(RuntimeError):
+    """Custom error for sync operations."""
+    pass
+
+
+def eprint(msg: str) -> None:
+    """Print to stderr."""
+    print(msg, file=sys.stderr)
+
+
+def run_cmd(
+    cmd: Sequence[str],
+    *,
+    cwd: Optional[Path] = None,
+    dry_run: bool = False,
+    check: bool = True,
+    capture: bool = False,
+) -> subprocess.CompletedProcess:
+    """Run a shell command with optional dry-run mode."""
+    pretty = " ".join(cmd)
+    if dry_run:
+        print(f"[dry-run] {pretty}")
+        return subprocess.CompletedProcess(cmd, 0, "", "")
+    return subprocess.run(
+        list(cmd),
+        cwd=str(cwd) if cwd else None,
+        check=check,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def ensure_parent(path: Path, dry_run: bool) -> None:
+    """Ensure parent directory exists."""
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def write_bytes_if_changed(
+    path: Path, data: bytes, *, mode: Optional[int], dry_run: bool
+) -> Tuple[bool, bool]:
+    """Write bytes to file if content changed. Returns (changed, is_new)."""
+    exists = path.exists()
+    if exists and path.read_bytes() == data:
+        if mode is not None and not dry_run:
+            os.chmod(path, mode)
+        return False, False
+    if dry_run:
+        return True, not exists
+    ensure_parent(path, dry_run=False)
+    path.write_bytes(data)
+    if mode is not None:
+        os.chmod(path, mode)
+    return True, not exists
+
+
+def write_text_if_changed(
+    path: Path, text: str, *, executable: bool = False, dry_run: bool = False
+) -> bool:
+    """Write text to file if content changed."""
+    mode = None
+    if executable:
+        mode = 0o755
+    data = text.encode("utf-8")
+    changed, _ = write_bytes_if_changed(path, data, mode=mode, dry_run=dry_run)
+    return changed
+
+
+def load_manifest(path: Path) -> Set[str]:
+    """Load manifest file as set of paths."""
+    if not path.exists():
+        return set()
+    return {line.strip() for line in path.read_text(encoding="utf-8").splitlines() if line.strip()}
+
+
+def save_manifest(path: Path, values: Iterable[str], dry_run: bool) -> None:
+    """Save manifest file from set of paths."""
+    data = "\n".join(sorted(set(values)))
+    if data:
+        data += "\n"
+    write_text_if_changed(path, data, dry_run=dry_run)
+
+
+def apply_replacements(text: str, rules: Sequence[Tuple[str, str]]) -> str:
+    """Apply string replacements in sequence."""
+    out = text
+    for old, new in rules:
+        out = out.replace(old, new)
+    return out
+
+
+def is_excluded_path(parts: Sequence[str]) -> bool:
+    """Check if path contains excluded directories."""
+    blocked = {".system", "node_modules", ".venv", "dist", "build", "__pycache__", ".pytest_cache"}
+    return any(p in blocked for p in parts)
+
+
+def compute_hash(path: Path) -> str:
+    """Compute SHA-256 hash of file contents."""
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def create_backup(path: Path) -> Path:
+    """Create a timestamped backup of a file."""
+    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+    backup = path.with_suffix(f".ck-backup-{ts}{path.suffix}")
+    shutil.copy2(path, backup)
+    return backup
+
+
+def load_template(name: str) -> str:
+    """Load a template file from the templates directory."""
+    templates_dir = Path(__file__).parent.parent.parent / "templates"
+    return (templates_dir / name).read_text(encoding="utf-8")

package/templates/agents-md.md

@@ -0,0 +1,45 @@
+# AGENTS.md
+
+Codex working profile for this workspace, adapted from ClaudeKit rules and workflows.
+
+## Operating Principles
+
+- Follow `YAGNI`, `KISS`, `DRY`.
+- Prefer direct, maintainable solutions over speculative abstraction.
+- Do not claim completion without evidence (tests, checks, or concrete validation).
+- Never use fake implementations just to make tests/build pass.
+
+## Default Workflow
+
+1. Read context first: `README.md` and relevant docs under `./docs/`.
+2. For non-trivial work, create/update a plan in `./plans/` before coding.
+3. Implement in existing files unless new files are clearly needed.
+4. Validate with project compile/lint/test commands.
+5. Run code-review mindset before finalizing (bugs, regressions, missing tests first).
+6. Update docs when behavior, architecture, contracts, or operations change.
+
+## Quality Gates
+
+- Handle edge cases and error paths explicitly.
+- Keep security and performance implications visible in design decisions.
+- Keep code readable and intention-revealing; add comments only when needed for non-obvious logic.
+
+## Documentation Rules
+
+- `./docs` is the source of truth for project docs.
+- Keep docs synchronized with code and implementation decisions.
+- When summarizing/reporting, be concise and list unresolved questions at the end.
+
+## Skill Usage
+
+- Activate relevant skills intentionally per task.
+- For legacy ClaudeKit command intents (`/ck-help`, `/coding-level`, `/ask`, `/docs/*`, `/journal`, `/watzup`), use `$claudekit-command-bridge`.
+
+## Reference Material (Imported from ClaudeKit)
+
+- `~/.codex/claudekit/CLAUDE.md`
+- `~/.codex/claudekit/rules/development-rules.md`
+- `~/.codex/claudekit/rules/primary-workflow.md`
+- `~/.codex/claudekit/rules/orchestration-protocol.md`
+- `~/.codex/claudekit/rules/documentation-management.md`
+- `~/.codex/claudekit/rules/team-coordination-rules.md`

package/templates/bridge-docs-init.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DOCS_DIR="${1:-docs}"
+mkdir -p "$DOCS_DIR"
+mkdir -p "$DOCS_DIR/journals"
+
+create_if_missing() {
+  local file="$1"
+  local content="$2"
+  if [[ ! -f "$file" ]]; then
+    printf "%s\\n" "$content" > "$file"
+    echo "created: $file"
+  else
+    echo "exists: $file"
+  fi
+}
+
+create_if_missing "$DOCS_DIR/project-overview-pdr.md" "# Project Overview / PDR"
+create_if_missing "$DOCS_DIR/code-standards.md" "# Code Standards"
+create_if_missing "$DOCS_DIR/codebase-summary.md" "# Codebase Summary"
+create_if_missing "$DOCS_DIR/design-guidelines.md" "# Design Guidelines"
+create_if_missing "$DOCS_DIR/deployment-guide.md" "# Deployment Guide"
+create_if_missing "$DOCS_DIR/system-architecture.md" "# System Architecture"
+create_if_missing "$DOCS_DIR/project-roadmap.md" "# Project Roadmap"

package/templates/bridge-project-status.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PLANS_DIR="${1:-plans}"
+
+echo "## Project Status"
+echo
+
+if [[ -d "$PLANS_DIR" ]]; then
+  total_plans=0
+  completed=0
+  in_progress=0
+  pending=0
+
+  while IFS= read -r plan; do
+    total_plans=$((total_plans + 1))
+    status="$(grep -E '^status:' "$plan" | head -n1 | awk '{print $2}')"
+    case "$status" in
+      completed) completed=$((completed + 1)) ;;
+      in-progress|in_progress) in_progress=$((in_progress + 1)) ;;
+      pending|"") pending=$((pending + 1)) ;;
+      *) ;;
+    esac
+  done < <(find "$PLANS_DIR" -type f -name plan.md | sort)
+
+  echo "- Plans: $total_plans"
+  echo "- Completed: $completed"
+  echo "- In progress: $in_progress"
+  echo "- Pending/unknown: $pending"
+  echo
+else
+  echo "- Plans directory not found: $PLANS_DIR"
+  echo
+fi
+
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "## Git"
+  echo
+  echo "- Branch: $(git rev-parse --abbrev-ref HEAD)"
+  if [[ -n "$(git status --porcelain)" ]]; then
+    echo "- Working tree: dirty"
+  else
+    echo "- Working tree: clean"
+  fi
+else
+  echo "## Git"
+  echo
+  echo "- Not in a git repository"
+fi

package/templates/bridge-resolve-command.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+import sys
+
+MAP = {
+    "/preview": "markdown-novel-viewer",
+    "/kanban": "plans-kanban",
+    "/review/codebase": "code-review",
+    "/test": "web-testing",
+    "/test/ui": "web-testing",
+    "/worktree": "git",
+    "/plan": "plan",
+    "/plan/validate": "plan",
+    "/plan/archive": "project-management",
+    "/plan/red-team": "plan",
+    "/docs/init": "claudekit-command-bridge (docs-init.sh)",
+    "/docs/update": "claudekit-command-bridge",
+    "/docs/summarize": "claudekit-command-bridge",
+    "/journal": "claudekit-command-bridge",
+    "/watzup": "claudekit-command-bridge",
+    "/ask": "claudekit-command-bridge (architecture mode)",
+    "/coding-level": "claudekit-command-bridge (explanation depth)",
+    "/ck-help": "claudekit-command-bridge (this resolver)",
+}
+
+
+def main() -> int:
+    raw = " ".join(sys.argv[1:]).strip()
+    if not raw:
+        print('Usage: resolve-command.py "<legacy-command-or-intent>"')
+        return 1
+
+    cmd = raw.split()[0]
+    if cmd in MAP:
+        print(f"{cmd} -> {MAP[cmd]}")
+        return 0
+
+    for prefix, target in [
+        ("/docs/", "claudekit-command-bridge"),
+        ("/plan/", "plan"),
+        ("/review/", "code-review"),
+        ("/test", "web-testing"),
+    ]:
+        if cmd.startswith(prefix):
+            print(f"{cmd} -> {target}")
+            return 0
+
+    print(f"{cmd} -> no direct map; use find-skills + claudekit-command-bridge")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/bridge-skill.md

@@ -0,0 +1,63 @@
+---
+name: claudekit-command-bridge
+description: Bridge legacy ClaudeKit commands to Codex-native workflows. Use when users mention /ck-help, /coding-level, /ask, /docs/*, /journal, /watzup, or ask for Claude command equivalents.
+---
+
+# ClaudeKit Command Bridge
+
+Translate ClaudeKit command intent into Codex skills/workflows.
+
+## Quick Mapping
+
+| Legacy command | Codex target |
+|---|---|
+| `/preview` | `markdown-novel-viewer` skill |
+| `/kanban` | `plans-kanban` skill |
+| `/review/codebase` | `code-review` skill |
+| `/test` or `/test/ui` | `web-testing` skill |
+| `/worktree` | `git` skill + git worktree commands |
+| `/plan/*` | `plan` skill |
+| `/docs/init` | Run `scripts/docs-init.sh` then review docs |
+| `/docs/update` | Update docs from latest code changes |
+| `/docs/summarize` | Summarize codebase into `docs/codebase-summary.md` |
+| `/journal` | Write concise entry under `docs/journals/` |
+| `/watzup` | Produce status report from plans + git state |
+| `/ask` | Architecture consultation mode (no implementation) |
+| `/coding-level` | Adjust explanation depth (levels 0-5 rubric below) |
+| `/ck-help` | Run `scripts/resolve-command.py "<request>"` |
+
+## Commands Converted Here
+
+### `/ask` -> Architecture mode
+
+- Provide architecture analysis, tradeoffs, risks, and phased strategy.
+- Do not start implementation unless user explicitly asks.
+
+### `/coding-level` -> Explanation depth policy
+
+Use requested level when explaining:
+
+- `0`: ELI5, minimal jargon, analogies.
+- `1`: Junior, explain why and common mistakes.
+- `2`: Mid, include patterns and tradeoffs.
+- `3`: Senior, architecture and constraints focus.
+- `4`: Lead, risk/business impact and strategy.
+- `5`: Expert, concise implementation-first.
+
+### `/docs/init`, `/docs/update`, `/docs/summarize`
+
+- Initialize docs structure with `scripts/docs-init.sh`.
+- Keep docs source of truth under `./docs`.
+
+### `/journal`, `/watzup`
+
+- Write concise journal entries in `docs/journals/`.
+- For status, summarize plans and git state.
+
+## Helper Scripts
+
+```bash
+python3 ${CODEX_HOME:-$HOME/.codex}/skills/claudekit-command-bridge/scripts/resolve-command.py "/docs/update"
+${CODEX_HOME:-$HOME/.codex}/skills/claudekit-command-bridge/scripts/docs-init.sh
+${CODEX_HOME:-$HOME/.codex}/skills/claudekit-command-bridge/scripts/project-status.sh
+```

package/templates/command-map.md

@@ -0,0 +1,44 @@
+# ClaudeKit -> Codex Command Map
+
+## Covered by existing skills
+
+- `/preview` -> `markdown-novel-viewer`
+- `/kanban` -> `plans-kanban`
+- `/review/codebase` -> `code-review`
+- `/test`, `/test/ui` -> `web-testing`
+- `/worktree` -> `git`
+- `/plan/*` -> `plan`
+
+## Converted into bridge workflows
+
+- `/ck-help` -> `claudekit-command-bridge` (`resolve-command.py`)
+- `/coding-level` -> `claudekit-command-bridge` (depth rubric + output styles)
+- `/ask` -> `claudekit-command-bridge` (architecture mode)
+- `/docs/init`, `/docs/update`, `/docs/summarize` -> `claudekit-command-bridge`
+- `/journal`, `/watzup` -> `claudekit-command-bridge`
+
+## Explicitly excluded in this sync
+
+- `/use-mcp` (excluded when `--include-mcp` is not set)
+- Hooks (excluded when `--include-hooks` is not set)
+
+## Custom Prompt Aliases (`/prompts:<name>`)
+
+- `/ask` -> `/prompts:ask`
+- `/ck-help` -> `/prompts:ck-help`
+- `/coding-level` -> `/prompts:coding-level`
+- `/docs/init` -> `/prompts:docs-init`
+- `/docs/summarize` -> `/prompts:docs-summarize`
+- `/docs/update` -> `/prompts:docs-update`
+- `/journal` -> `/prompts:journal`
+- `/kanban` -> `/prompts:kanban`
+- `/plan/archive` -> `/prompts:plan-archive`
+- `/plan/red-team` -> `/prompts:plan-red-team`
+- `/plan/validate` -> `/prompts:plan-validate`
+- `/preview` -> `/prompts:preview`
+- `/review/codebase` -> `/prompts:review-codebase`
+- `/review/codebase/parallel` -> `/prompts:review-codebase-parallel`
+- `/test` -> `/prompts:test`
+- `/test/ui` -> `/prompts:test-ui`
+- `/watzup` -> `/prompts:watzup`
+- `/worktree` -> `/prompts:worktree`

package/tests/__init__.py

@@ -0,0 +1 @@
+# Tests package

package/tests/test_config_enforcer.py

@@ -0,0 +1,44 @@
+"""Tests for config_enforcer module."""
+
+import pytest
+from claudekit_codex_sync.config_enforcer import enforce_multi_agent_flag
+
+
+def test_adds_multi_agent_to_existing_features(tmp_path):
+    """Test adding multi_agent to existing [features] section."""
+    config = tmp_path / "config.toml"
+    config.write_text("[features]\n")
+    enforce_multi_agent_flag(config, dry_run=False)
+    content = config.read_text()
+    assert "multi_agent = true" in content
+
+
+def test_creates_features_section_if_missing(tmp_path):
+    """Test creating [features] section if it doesn't exist."""
+    config = tmp_path / "config.toml"
+    config.write_text("some_other_setting = 1\n")
+    enforce_multi_agent_flag(config, dry_run=False)
+    content = config.read_text()
+    assert "[features]" in content
+    assert "multi_agent = true" in content
+
+
+def test_preserves_existing_config(tmp_path):
+    """Test that existing config is preserved when adding multi_agent."""
+    config = tmp_path / "config.toml"
+    original = 'project_doc_max_bytes = 65536\n'
+    config.write_text(original)
+    enforce_multi_agent_flag(config, dry_run=False)
+    content = config.read_text()
+    assert "project_doc_max_bytes = 65536" in content
+    assert "multi_agent = true" in content
+
+
+def test_creates_file_if_not_exists(tmp_path):
+    """Test creating config file if it doesn't exist."""
+    config = tmp_path / "config.toml"
+    enforce_multi_agent_flag(config, dry_run=False)
+    assert config.exists()
+    content = config.read_text()
+    assert "[features]" in content
+    assert "multi_agent = true" in content

package/tests/test_path_normalizer.py

@@ -0,0 +1,61 @@
+"""Tests for path_normalizer module."""
+
+import pytest
+from claudekit_codex_sync.constants import SKILL_MD_REPLACEMENTS
+from claudekit_codex_sync.path_normalizer import apply_replacements
+
+
+def test_claude_to_codex_path():
+    """Test that .claude paths are normalized to .codex paths."""
+    text = "$HOME/.claude/skills/brainstorm/SKILL.md"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert ".claude" not in result
+    assert ".codex" in result or "CODEX_HOME" in result
+
+
+def test_home_claude_replacement():
+    """Test $HOME/.claude/skills/ replacement."""
+    text = "$HOME/.claude/skills/test/skill.py"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert result == "${CODEX_HOME:-$HOME/.codex}/skills/test/skill.py"
+
+
+def test_dot_slash_claude_replacement():
+    """Test ./.claude/skills/ replacement."""
+    text = "./.claude/skills/test/skill.py"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert result == "${CODEX_HOME:-$HOME/.codex}/skills/test/skill.py"
+
+
+def test_tilde_claude_replacement():
+    """Test ~/.claude/ replacement."""
+    text = "~/.claude/config.json"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert result == "~/.codex/config.json"
+
+
+def test_ck_json_replacement():
+    """Test .ck.json path replacement."""
+    text = "~/.claude/.ck.json"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert result == "~/.codex/claudekit/.ck.json"
+
+
+def test_no_change_for_non_claude():
+    """Test that non-claude paths are not changed."""
+    text = "/some/other/path/file.txt"
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert result == text
+
+
+def test_multiple_replacements():
+    """Test multiple paths in same text."""
+    text = """
+    Use skills from $HOME/.claude/skills/
+    And scripts from ./.claude/scripts/
+    Config at ~/.claude/.ck.json
+    """
+    result = apply_replacements(text, SKILL_MD_REPLACEMENTS)
+    assert "$HOME/.claude/skills/" not in result
+    assert "./.claude/scripts/" not in result
+    assert "~/.claude/.ck.json" not in result