claudekit-codex-sync 0.1.0 → 0.2.0

package/src/claudekit_codex_sync/source_resolver.py

@@ -41,7 +41,7 @@ def detect_claude_source() -> Path:
     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.")
+    raise SyncError("Claude Code not found. Use --source to specify.")
 
 
 def validate_source(source: Path) -> Dict[str, bool]:
@@ -61,11 +61,19 @@ def collect_skill_entries(zf: zipfile.ZipFile) -> 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/") :]
+        rel = name[len(".claude/skills/") :].replace("\\", "/")
+        path = Path(rel)
+        if path.is_absolute() or ".." in path.parts:
+            raise SyncError(f"Unsafe zip entry path: {name}")
         parts = rel.split("/", 1)
         if len(parts) != 2:
             continue
         skill, inner = parts
+        inner_path = Path(inner)
+        if Path(skill).is_absolute() or ".." in Path(skill).parts:
+            raise SyncError(f"Unsafe skill name in zip entry: {name}")
+        if inner_path.is_absolute() or ".." in inner_path.parts:
+            raise SyncError(f"Unsafe skill file path in zip entry: {name}")
         skill_files.setdefault(skill, []).append((name, inner))
     return skill_files
 

package/src/claudekit_codex_sync/sync_registry.py

@@ -28,6 +28,7 @@ def load_registry(codex_home: Path) -> Dict[str, Any]:
 def save_registry(codex_home: Path, registry: Dict[str, Any]) -> None:
     """Save sync registry to disk."""
     registry_path = codex_home / REGISTRY_FILE
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
     registry["lastSync"] = datetime.now(timezone.utc).isoformat()
     registry_path.write_text(json.dumps(registry, indent=2), encoding="utf-8")
 

package/templates/agents-md.md

@@ -35,11 +35,8 @@ Codex working profile for this workspace, adapted from ClaudeKit rules and workf
 - 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`
+## Reference Material
+
+- `README.md`
+- `docs/`
+- `plans/`

package/tests/test_clean_target.py

@@ -0,0 +1,55 @@
+"""Tests for clean_target module."""
+
+import json
+from pathlib import Path
+
+from claudekit_codex_sync.clean_target import clean_target
+
+
+def test_clean_removes_agents(tmp_path: Path):
+    """Clean removes agents dir."""
+    agents = tmp_path / "agents"
+    agents.mkdir()
+    (agents / "planner.toml").write_text("model = 'test'")
+    (agents / "researcher.toml").write_text("model = 'test'")
+
+    removed = clean_target(tmp_path, dry_run=False)
+    assert not agents.exists()
+    assert removed >= 2
+
+
+def test_clean_keeps_venv(tmp_path: Path):
+    """Clean keeps skills/.venv intact."""
+    skills = tmp_path / "skills"
+    skills.mkdir()
+    venv = skills / ".venv"
+    venv.mkdir()
+    (venv / "bin").mkdir()
+    (venv / "bin" / "python3").write_text("#!/usr/bin/env python3")
+    skill = skills / "my-skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("# test")
+
+    clean_target(tmp_path, dry_run=False)
+    assert venv.exists(), ".venv should survive cleaning"
+    assert not skill.exists(), "skill dirs should be removed"
+
+
+def test_clean_dry_run(tmp_path: Path):
+    """Dry run counts but doesn't delete."""
+    agents = tmp_path / "agents"
+    agents.mkdir()
+    (agents / "test.toml").write_text("x = 1")
+
+    removed = clean_target(tmp_path, dry_run=True)
+    assert removed >= 1
+    assert agents.exists(), "dry-run should not delete"
+
+
+def test_clean_removes_registry(tmp_path: Path):
+    """Clean clears sync registry."""
+    registry = tmp_path / ".claudekit-sync-registry.json"
+    registry.write_text(json.dumps({"version": 1}))
+
+    clean_target(tmp_path, dry_run=False)
+    assert not registry.exists()

package/tests/test_cli_args.py

@@ -0,0 +1,57 @@
+"""Tests for CLI argument parsing."""
+
+import sys
+from unittest.mock import patch
+
+from claudekit_codex_sync.cli import parse_args
+
+
+def test_default_args():
+    """Default: project scope, no flags."""
+    with patch.object(sys, "argv", ["ckc-sync"]):
+        args = parse_args()
+    assert not args.global_scope
+    assert not args.fresh
+    assert not args.force
+    assert not args.mcp
+    assert not args.no_deps
+    assert not args.dry_run
+    assert args.zip_path is None
+    assert args.source is None
+
+
+def test_global_flag():
+    """'-g' enables global scope."""
+    with patch.object(sys, "argv", ["ckc-sync", "-g"]):
+        args = parse_args()
+    assert args.global_scope
+
+
+def test_fresh_flag():
+    """'-f' enables fresh clean."""
+    with patch.object(sys, "argv", ["ckc-sync", "-f"]):
+        args = parse_args()
+    assert args.fresh
+
+
+def test_combined_short_flags():
+    """'-g -f -n' all work together."""
+    with patch.object(sys, "argv", ["ckc-sync", "-g", "-f", "-n"]):
+        args = parse_args()
+    assert args.global_scope
+    assert args.fresh
+    assert args.dry_run
+
+
+def test_zip_flag():
+    """'--zip' sets zip path and implies zip mode."""
+    with patch.object(sys, "argv", ["ckc-sync", "--zip", "test.zip"]):
+        args = parse_args()
+    assert str(args.zip_path) == "test.zip"
+
+
+def test_mcp_flag():
+    """'--mcp' includes MCP skills."""
+    with patch.object(sys, "argv", ["ckc-sync", "--mcp"]):
+        args = parse_args()
+    assert args.mcp

package/reports/brainstorm-260222-2051-claudekit-codex-community-sync.md

@@ -1,113 +0,0 @@
-# Brainstorm Report: ClaudeKit -> Codex Community Toolkit
-
-## Problem Statement
-You want a community-shareable toolkit that syncs ClaudeKit assets into Codex with minimal manual work, supports latest zip detection, and proves behavior is close to Claude workflows.
-
-## Requirements
-- Full-auto sync entrypoint (latest zip auto-select).
-- Pull from both zip and local `~/.claude` where needed.
-- Keep current exclusions default (`mcp`, `hooks`) but support opt-in.
-- Add agent-role sync compatible with Codex multi-agent system.
-- Publish for community consumption via:
-  - `npm`/`npx` install path.
-  - `git clone` + local run path.
-- Provide evidence that behavior is close to ClaudeKit orchestration (not only file-copy parity).
-
-## Current Reality Check
-- Current script (`~/.codex/scripts/claudekit-sync-all.py`) is strong for assets/skills/rules/prompts sync.
-- It is not yet productized as a public package.
-- It does not yet implement Claude-agent -> Codex-agent role transpilation + parity benchmark harness.
-- Behavior parity is therefore not yet provable by metrics.
-
-## Approaches Evaluated
-
-### Approach A: Keep Python Core + Add NPM Wrapper (Recommended for v1)
-Pros:
-- Fastest to ship.
-- Reuses proven sync logic now.
-- Lower regression risk.
-- Easy to support both `npx` and `python3` direct run.
-
-Cons:
-- Requires Python on user machine.
-- Wrapper layer adds runtime dependency checks.
-
-### Approach B: Full Rewrite to TypeScript Core
-Pros:
-- Native npm experience.
-- Simpler JS ecosystem integration.
-
-Cons:
-- High rewrite cost.
-- High regression risk in edge behavior already solved in Python.
-- Slower time-to-community release.
-
-### Approach C: Maintain Two Cores (Python + TS)
-Pros:
-- Maximum flexibility.
-
-Cons:
-- Highest maintenance burden.
-- Divergence risk.
-- Not YAGNI.
-
-## Recommended Strategy
-- **Ship staged hybrid strategy**:
-1. **v1**: Python core as source of truth + npm wrapper + git-clone workflow.
-2. **v1.1**: Add agent transpiler and parity benchmark harness.
-3. **v2**: Consider TS native core only if adoption justifies rewrite.
-
-This gives speed now and keeps path to long-term polish without over-engineering.
-
-## Claude -> Codex Customization That Matters Most
-- Agent transpiler that converts Claude `agents/*.md` into Codex role config:
-  - `~/.codex/config.toml` `[agents.<role>]`
-  - `~/.codex/agents/<role>.toml`
-- Role strategy:
-  - Prefix custom roles (`ck-*`) to avoid overriding built-ins accidentally.
-  - Allow explicit override mode if user wants `default/worker/explorer` replacement.
-- Instruction normalization:
-  - rewrite Claude-specific paths/tooling references to Codex equivalents.
-  - preserve intent, not literal syntax.
-- Execution guardrails:
-  - per-role `sandbox_mode`, `model_reasoning_effort`, `developer_instructions`.
-
-## Proof Plan: “Near-Similar Behavior”
-Define parity suite and publish numbers:
-- 20-30 canonical scenarios:
-  - planning, research, review, debug, docs update, testing loops.
-- A/B runs:
-  - A: Claude original flow.
-  - B: Codex transpiled flow.
-- Score dimensions:
-  - task success rate.
-  - required artifact completeness.
-  - policy compliance (test/lint/docs gates).
-  - orchestration quality (spawn/wait/close behavior).
-  - defect quality (severity-weighted findings for review/debug cases).
-
-Target thresholds:
-- >=85% parity: acceptable “near-similar”.
-- >=90% parity: strong community-grade claim.
-
-## Risks and Mitigations
-- Risk: Codex/Claude runtime semantics differ.
-  - Mitigation: parity scoring by outcomes, not literal step parity.
-- Risk: multi-agent feature drift across Codex versions.
-  - Mitigation: version compatibility matrix + CI smoke tests.
-- Risk: wrapper install friction.
-  - Mitigation: clear preflight checks + actionable errors.
-
-## Success Metrics
-- Install success rate >=95% on Ubuntu/macOS/WSL for default path.
-- End-to-end sync success rate >=98% on supported fixtures.
-- Parity benchmark >=85% before public “near-similar” claim.
-- Time to run full sync + verify under 3 minutes on standard machine.
-
-## Next Steps
-- Create implementation plan with phases for:
-  - productization,
-  - transpiler,
-  - benchmark harness,
-  - npm + git distribution,
-  - release process.

package/scripts/bootstrap-claudekit-skill-scripts.sh

@@ -1,150 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
-SKILLS_DIR="${CODEX_HOME}/skills"
-VENV_DIR="${SKILLS_DIR}/.venv"
-RUN_PYTHON=true
-RUN_NODE=true
-DRY_RUN=false
-INCLUDE_TEST_DEPS=false
-INCLUDE_MCP=false
-
-usage() {
-  cat <<'EOF'
-Install runtime dependencies for ClaudeKit skills synced into Codex.
-
-Usage:
-  bootstrap-claudekit-skill-scripts.sh [options]
-
-Options:
-  --python-only        Install Python dependencies only
-  --node-only          Install Node.js dependencies only
-  --include-test-deps  Also install requirements from test folders
-  --include-mcp        Also include mcp-builder and mcp-management skills
-  --dry-run            Print actions only
-  -h, --help           Show help
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --python-only)
-      RUN_PYTHON=true
-      RUN_NODE=false
-      ;;
-    --node-only)
-      RUN_PYTHON=false
-      RUN_NODE=true
-      ;;
-    --include-test-deps)
-      INCLUDE_TEST_DEPS=true
-      ;;
-    --include-mcp)
-      INCLUDE_MCP=true
-      ;;
-    --dry-run)
-      DRY_RUN=true
-      ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "Unknown option: $1" >&2
-      usage >&2
-      exit 1
-      ;;
-  esac
-  shift
-done
-
-if [[ ! -d "$SKILLS_DIR" ]]; then
-  echo "Skills directory not found: $SKILLS_DIR" >&2
-  exit 1
-fi
-
-py_ok=0
-py_fail=0
-node_ok=0
-node_fail=0
-
-skip_mcp_path() {
-  local p="$1"
-  if [[ "$INCLUDE_MCP" == true ]]; then
-    return 1
-  fi
-  [[ "$p" == *"/mcp-builder/"* || "$p" == *"/mcp-management/"* ]]
-}
-
-if [[ "$RUN_PYTHON" == true ]]; then
-  if ! command -v python3 >/dev/null 2>&1; then
-    echo "python3 not found" >&2
-    exit 1
-  fi
-
-  if [[ "$DRY_RUN" == true ]]; then
-    echo "[dry-run] python3 -m venv \"$VENV_DIR\""
-  else
-    python3 -m venv "$VENV_DIR"
-    "$VENV_DIR/bin/python3" -m pip install --upgrade pip >/dev/null
-  fi
-
-  while IFS= read -r req; do
-    if skip_mcp_path "$req"; then
-      continue
-    fi
-    if [[ "$DRY_RUN" == true ]]; then
-      echo "[dry-run] $VENV_DIR/bin/python3 -m pip install -r \"$req\""
-      py_ok=$((py_ok + 1))
-      continue
-    fi
-    if "$VENV_DIR/bin/python3" -m pip install -r "$req" >/dev/null; then
-      py_ok=$((py_ok + 1))
-    else
-      echo "python deps failed: $req" >&2
-      py_fail=$((py_fail + 1))
-    fi
-  done < <(
-    find "$SKILLS_DIR" \
-      \( -path '*/.system/*' -o -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
-      -type f -name 'requirements*.txt' -print \
-      | if [[ "$INCLUDE_TEST_DEPS" == true ]]; then cat; else grep -Ev '/tests?/'; fi \
-      | sort -u
-  )
-fi
-
-if [[ "$RUN_NODE" == true ]]; then
-  if ! command -v npm >/dev/null 2>&1; then
-    echo "npm not found" >&2
-    exit 1
-  fi
-
-  while IFS= read -r pkg; do
-    if skip_mcp_path "$pkg"; then
-      continue
-    fi
-    dir="$(dirname "$pkg")"
-    if [[ "$DRY_RUN" == true ]]; then
-      echo "[dry-run] npm install --prefix \"$dir\""
-      node_ok=$((node_ok + 1))
-      continue
-    fi
-    if npm install --prefix "$dir" >/dev/null; then
-      node_ok=$((node_ok + 1))
-    else
-      echo "node deps failed: $dir" >&2
-      node_fail=$((node_fail + 1))
-    fi
-  done < <(
-    find "$SKILLS_DIR" \
-      \( -path '*/.system/*' -o -path '*/node_modules/*' -o -path '*/.venv/*' -o -path '*/dist/*' -o -path '*/build/*' \) -prune -o \
-      -type f -name package.json -print \
-      | sort -u
-  )
-fi
-
-echo "python_ok=$py_ok python_fail=$py_fail node_ok=$node_ok node_fail=$node_fail"
-if [[ $py_fail -gt 0 || $node_fail -gt 0 ]]; then
-  exit 2
-fi