claudekit-codex-sync 0.1.0 → 0.2.0

package/src/claudekit_codex_sync/asset_sync_dir.py

@@ -7,7 +7,8 @@ from pathlib import Path
 from typing import Dict
 
 from .constants import ASSET_DIRS, ASSET_FILES, CONFLICT_SKILLS, EXCLUDED_SKILLS_ALWAYS, MCP_SKILLS
-from .utils import is_excluded_path, write_bytes_if_changed
+from .sync_registry import check_user_edit, maybe_backup, update_entry
+from .utils import compute_hash, create_backup, is_excluded_path, write_bytes_if_changed
 
 
 def sync_assets_from_dir(
@@ -16,11 +17,14 @@ def sync_assets_from_dir(
     codex_home: Path,
     include_hooks: bool,
     dry_run: bool,
+    registry: dict | None = None,
+    force: bool = True,
 ) -> Dict[str, int]:
     """Sync non-skill assets from live directory."""
     claudekit_dir = codex_home / "claudekit"
-    claudekit_dir.mkdir(parents=True, exist_ok=True)
-    added = updated = 0
+    if not dry_run:
+        claudekit_dir.mkdir(parents=True, exist_ok=True)
+    added = updated = skipped = 0
 
     for dirname in ASSET_DIRS:
         src_dir = source / dirname
@@ -34,35 +38,81 @@ def sync_assets_from_dir(
             if not src_file.is_file() or is_excluded_path(src_file.parts):
                 continue
             rel = src_file.relative_to(src_dir)
+            rel_path = f"claudekit/{dirname}/{rel}"
             dst = dst_dir / rel
+
+            if not force and registry and dst.exists():
+                entry = registry.get("entries", {}).get(rel_path)
+                if entry:
+                    if dry_run and check_user_edit(entry, dst):
+                        skipped += 1
+                        print(f"skip(user-edit): {rel_path}")
+                        continue
+                    backup = maybe_backup(registry, rel_path, dst, respect_edits=True)
+                    if backup:
+                        skipped += 1
+                        print(f"skip(user-edit): {rel_path}")
+                        continue
+                elif compute_hash(src_file) != compute_hash(dst):
+                    if dry_run:
+                        print(f"[dry-run] backup(untracked): {rel_path}")
+                    else:
+                        backup = create_backup(dst)
+                        print(f"backup(untracked): {rel_path} -> {backup.name}")
+
             data = src_file.read_bytes()
             mode = src_file.stat().st_mode & 0o777 if src_file.stat().st_mode & 0o111 else None
             changed, is_added = write_bytes_if_changed(dst, data, mode=mode, dry_run=dry_run)
             if changed:
                 if is_added:
                     added += 1
-                    print(f"add: claudekit/{dirname}/{rel}")
+                    print(f"add: {rel_path}")
                 else:
                     updated += 1
-                    print(f"update: claudekit/{dirname}/{rel}")
+                    print(f"update: {rel_path}")
+            if registry and not dry_run and dst.exists():
+                update_entry(registry, rel_path, src_file, dst)
 
     for filename in ASSET_FILES:
         src = source / filename
         if not src.exists():
             continue
+        rel_path = f"claudekit/{filename}"
         dst = claudekit_dir / filename
+
+        if not force and registry and dst.exists():
+            entry = registry.get("entries", {}).get(rel_path)
+            if entry:
+                if dry_run and check_user_edit(entry, dst):
+                    skipped += 1
+                    print(f"skip(user-edit): {rel_path}")
+                    continue
+                backup = maybe_backup(registry, rel_path, dst, respect_edits=True)
+                if backup:
+                    skipped += 1
+                    print(f"skip(user-edit): {rel_path}")
+                    continue
+            elif compute_hash(src) != compute_hash(dst):
+                if dry_run:
+                    print(f"[dry-run] backup(untracked): {rel_path}")
+                else:
+                    backup = create_backup(dst)
+                    print(f"backup(untracked): {rel_path} -> {backup.name}")
+
         data = src.read_bytes()
         mode = src.stat().st_mode & 0o777 if src.stat().st_mode & 0o111 else None
         changed, is_added = write_bytes_if_changed(dst, data, mode=mode, dry_run=dry_run)
         if changed:
             if is_added:
                 added += 1
-                print(f"add: claudekit/{filename}")
+                print(f"add: {rel_path}")
             else:
                 updated += 1
-                print(f"update: claudekit/{filename}")
+                print(f"update: {rel_path}")
+        if registry and not dry_run and dst.exists():
+            update_entry(registry, rel_path, src, dst)
 
-    return {"added": added, "updated": updated, "removed": 0, "managed_files": added + updated}
+    return {"added": added, "updated": updated, "removed": 0, "skipped": skipped}
 
 
 def sync_skills_from_dir(
@@ -120,6 +170,7 @@ def sync_skills_from_dir(
         ignore = shutil.ignore_patterns("*.pyc", "__pycache__", ".venv", "node_modules", "dist", "build")
         shutil.copytree(skill_dir, dst, ignore=ignore)
 
-    skills_dst.mkdir(parents=True, exist_ok=True)
+    if not dry_run:
+        skills_dst.mkdir(parents=True, exist_ok=True)
     total_skills = len(list(skills_dst.rglob("SKILL.md")))
     return {"added": added, "updated": updated, "skipped": skipped, "total_skills": total_skills}

package/src/claudekit_codex_sync/asset_sync_zip.py

@@ -16,7 +16,16 @@ from .constants import (
     MCP_SKILLS,
 )
 from .source_resolver import collect_skill_entries, zip_mode
-from .utils import load_manifest, save_manifest, write_bytes_if_changed
+from .utils import SyncError, load_manifest, save_manifest, write_bytes_if_changed
+
+
+def _validate_zip_relpath(rel: str, zip_name: str) -> str:
+    """Validate zip relative path and return normalized form."""
+    normalized = rel.replace("\\", "/")
+    path = Path(normalized)
+    if path.is_absolute() or ".." in path.parts:
+        raise SyncError(f"Unsafe zip entry path: {zip_name}")
+    return normalized
 
 
 def sync_assets(
@@ -35,7 +44,7 @@ def sync_assets(
     for name in zf.namelist():
         if name.endswith("/") or not name.startswith(".claude/"):
             continue
-        rel = name[len(".claude/") :]
+        rel = _validate_zip_relpath(name[len(".claude/") :], name)
         first = rel.split("/", 1)[0]
         if first == "hooks" and include_hooks:
             selected.append((name, rel))
@@ -47,10 +56,11 @@ def sync_assets(
     added = updated = removed = 0
 
     for rel in sorted(old_manifest - new_manifest):
-        target = claudekit_dir / rel
+        safe_rel = _validate_zip_relpath(rel, rel)
+        target = claudekit_dir / safe_rel
         if target.exists():
             removed += 1
-            print(f"remove: {rel}")
+            print(f"remove: {safe_rel}")
             if not dry_run:
                 target.unlink()
 
@@ -135,6 +145,7 @@ def sync_skills(
             dst = dst_skill_dir / inner
             write_bytes_if_changed(dst, data, mode=zip_mode(info), dry_run=False)
 
-    skills_dir.mkdir(parents=True, exist_ok=True)
+    if not dry_run:
+        skills_dir.mkdir(parents=True, exist_ok=True)
     total_skills = len(list(skills_dir.rglob("SKILL.md")))
     return {"added": added, "updated": updated, "skipped": skipped, "total_skills": total_skills}

package/src/claudekit_codex_sync/clean_target.py

@@ -0,0 +1,49 @@
+"""Clean target directories for --fresh sync."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+def clean_target(codex_home: Path, *, dry_run: bool) -> int:
+    """Remove agents, skills (keep .venv), prompts, claudekit before fresh sync."""
+    removed = 0
+
+    for subdir in ("agents", "prompts", "claudekit"):
+        target = codex_home / subdir
+        if target.exists():
+            count = sum(1 for item in target.rglob("*") if item.is_file())
+            removed += count
+            print(f"fresh: rm {subdir}/ ({count} files)")
+            if not dry_run:
+                shutil.rmtree(target)
+
+    skills = codex_home / "skills"
+    if skills.exists():
+        for item in skills.iterdir():
+            if item.name == ".venv":
+                continue
+            if item.is_dir():
+                count = sum(1 for path in item.rglob("*") if path.is_file())
+                removed += count
+                if not dry_run:
+                    shutil.rmtree(item)
+            else:
+                removed += 1
+                if not dry_run:
+                    item.unlink()
+        print("fresh: rm skills/* (kept .venv)")
+
+    for name in (
+        ".claudekit-sync-registry.json",
+        ".sync-manifest-assets.txt",
+        ".claudekit-generated-prompts.txt",
+    ):
+        target = codex_home / name
+        if target.exists():
+            removed += 1
+            if not dry_run:
+                target.unlink()
+
+    return removed

package/src/claudekit_codex_sync/cli.py

@@ -8,12 +8,18 @@ import json
 import os
 import zipfile
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
 from .asset_sync_dir import sync_assets_from_dir, sync_skills_from_dir
 from .asset_sync_zip import sync_assets, sync_skills
 from .bridge_generator import ensure_bridge_skill
-from .config_enforcer import ensure_agents, enforce_config, enforce_multi_agent_flag
+from .clean_target import clean_target
+from .config_enforcer import (
+    enforce_config,
+    enforce_multi_agent_flag,
+    ensure_agents,
+    register_agents,
+)
 from .dep_bootstrapper import bootstrap_deps
 from .path_normalizer import normalize_agent_tomls, normalize_files
 from .prompt_exporter import export_prompts
@@ -26,41 +32,85 @@ from .utils import SyncError, eprint
 def print_summary(summary: Dict[str, Any]) -> None:
     print(json.dumps(summary, indent=2, ensure_ascii=False))
 
+
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(
-        description="All-in-one ClaudeKit -> Codex sync script."
+        prog="ckc-sync",
+        description="Sync ClaudeKit skills, agents, and config to Codex CLI.",
+    )
+    p.add_argument(
+        "-g",
+        "--global",
+        dest="global_scope",
+        action="store_true",
+        help="Sync to ~/.codex/ (default: ./.codex/)",
+    )
+    p.add_argument(
+        "-f",
+        "--fresh",
+        action="store_true",
+        help="Clean target dirs before sync",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite user-edited files without backup (required for zip write mode)",
+    )
+    p.add_argument(
+        "--zip",
+        dest="zip_path",
+        type=Path,
+        help="Sync from zip instead of live ~/.claude/",
+    )
+    p.add_argument(
+        "--source",
+        type=Path,
+        default=None,
+        help="Custom source dir (default: ~/.claude/)",
+    )
+    p.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Include MCP skills",
+    )
+    p.add_argument(
+        "--no-deps",
+        action="store_true",
+        help="Skip dependency bootstrap (venv)",
+    )
+    p.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="Preview only",
     )
-    p.add_argument("--zip", dest="zip_path", type=Path, help="Specific ClaudeKit zip path")
-    p.add_argument("--codex-home", type=Path, default=None, help="Codex home (default: $CODEX_HOME or ~/.codex)")
-    p.add_argument("--workspace", type=Path, default=Path.cwd(), help="Workspace root for AGENTS.md")
-    p.add_argument("--source-mode", choices=["auto", "live", "zip"], default="auto", help="Source mode")
-    p.add_argument("--source-dir", type=Path, default=None, help="Source directory for live mode")
-    p.add_argument("--include-mcp", action="store_true", help="Include MCP skills/prompts")
-    p.add_argument("--include-hooks", action="store_true", help="Include hooks")
-    p.add_argument("--include-conflicts", action="store_true", help="Include conflicting skills")
-    p.add_argument("--include-test-deps", action="store_true", help="Install test requirements")
-    p.add_argument("--skip-bootstrap", action="store_true", help="Skip dependency bootstrap")
-    p.add_argument("--skip-verify", action="store_true", help="Skip verification")
-    p.add_argument("--skip-agent-toml", action="store_true", help="Skip agent TOML normalization")
-    p.add_argument("--respect-edits", action="store_true", help="Backup user-edited files")
-    p.add_argument("--dry-run", action="store_true", help="Preview changes only")
     return p.parse_args()
 
 
 def main() -> int:
     args = parse_args()
-    codex_home = (args.codex_home or Path(os.environ.get("CODEX_HOME", "~/.codex"))).expanduser().resolve()
-    workspace = args.workspace.expanduser().resolve()
-    workspace.mkdir(parents=True, exist_ok=True)
 
-    # Load registry for backup/respect-edits
+    if args.global_scope:
+        codex_home = Path(os.environ.get("CODEX_HOME", "~/.codex")).expanduser().resolve()
+    else:
+        codex_home = (Path.cwd() / ".codex").resolve()
+
+    workspace = Path.cwd().resolve()
+    if not args.dry_run:
+        codex_home.mkdir(parents=True, exist_ok=True)
+
+    if args.fresh:
+        removed = clean_target(codex_home, dry_run=args.dry_run)
+        print(f"fresh: removed {removed} files")
+
     registry = load_registry(codex_home)
 
-    source_mode = args.source_mode
-    use_live = source_mode == "live" or (source_mode == "auto" and args.source_dir)
+    use_live = args.zip_path is None
+    if not use_live and not args.force and not args.dry_run:
+        raise SyncError("zip sync requires --force for write mode")
 
     if use_live:
-        source = args.source_dir or detect_claude_source()
+        source = args.source or detect_claude_source()
         validation = validate_source(source)
         print(f"source: {source} (live)")
         print(f"validation: {validation}")
@@ -71,101 +121,85 @@ def main() -> int:
         registry["sourceDir"] = None
 
     print(f"codex_home: {codex_home}")
-    print(f"workspace: {workspace}")
-    print(
-        f"include_mcp={args.include_mcp} include_hooks={args.include_hooks} "
-        f"dry_run={args.dry_run} respect_edits={args.respect_edits}"
-    )
-
-    codex_home.mkdir(parents=True, exist_ok=True)
+    print(f"scope: {'global' if args.global_scope else 'project'}")
+    print(f"fresh={args.fresh} force={args.force} mcp={args.mcp} dry_run={args.dry_run}")
 
     if use_live:
         assets_stats = sync_assets_from_dir(
-            source, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+            source,
+            codex_home=codex_home,
+            include_hooks=True,
+            dry_run=args.dry_run,
+            registry=registry,
+            force=args.force,
         )
         skills_stats = sync_skills_from_dir(
             source,
             codex_home=codex_home,
-            include_mcp=args.include_mcp,
-            include_conflicts=args.include_conflicts,
+            include_mcp=args.mcp,
+            include_conflicts=False,
             dry_run=args.dry_run,
         )
     else:
-        with zipfile.ZipFile(zip_path) as zf:  # type: ignore
+        with zipfile.ZipFile(zip_path) as zf:
             assets_stats = sync_assets(
-                zf, codex_home=codex_home, include_hooks=args.include_hooks, dry_run=args.dry_run
+                zf,
+                codex_home=codex_home,
+                include_hooks=True,
+                dry_run=args.dry_run,
             )
             skills_stats = sync_skills(
                 zf,
                 codex_home=codex_home,
-                include_mcp=args.include_mcp,
-                include_conflicts=args.include_conflicts,
+                include_mcp=args.mcp,
+                include_conflicts=False,
                 dry_run=args.dry_run,
             )
 
-    print(
-        f"assets: added={assets_stats['added']} updated={assets_stats['updated']} "
-        f"removed={assets_stats['removed']}"
-    )
-    print(
-        f"skills: added={skills_stats['added']} updated={skills_stats['updated']} "
-        f"skipped={skills_stats['skipped']}"
-    )
+    print(f"assets: added={assets_stats['added']} updated={assets_stats['updated']}")
+    print(f"skills: added={skills_stats['added']} updated={skills_stats['updated']}")
 
-    changed = normalize_files(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
+    changed = normalize_files(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run)
     print(f"normalize_changed={changed}")
 
-    # Agent TOML normalization
-    agent_toml_changed = 0
-    if not args.skip_agent_toml:
-        agent_toml_changed = normalize_agent_tomls(codex_home=codex_home, dry_run=args.dry_run)
-        print(f"agent_toml_changed={agent_toml_changed}")
+    agent_toml_changed = normalize_agent_tomls(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"agent_toml_changed={agent_toml_changed}")
+
+    agents_registered = register_agents(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"agents_registered={agents_registered}")
 
     baseline_changed = 0
     if ensure_agents(workspace=workspace, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {workspace / 'AGENTS.md'}")
-    if enforce_config(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run):
+    if enforce_config(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {codex_home / 'config.toml'}")
     if ensure_bridge_skill(codex_home=codex_home, dry_run=args.dry_run):
         baseline_changed += 1
-        print(f"upsert: {codex_home / 'skills' / 'claudekit-command-bridge'}")
 
-    # Enable multi_agent flag
     config_path = codex_home / "config.toml"
-    if enforce_multi_agent_flag(config_path, dry_run=args.dry_run):
-        print(f"upsert: multi_agent = true in {config_path}")
-
+    enforce_multi_agent_flag(config_path, dry_run=args.dry_run)
     print(f"baseline_changed={baseline_changed}")
 
-    prompt_stats = export_prompts(codex_home=codex_home, include_mcp=args.include_mcp, dry_run=args.dry_run)
-    print(
-        f"prompts: added={prompt_stats['added']} updated={prompt_stats['updated']} "
-        f"total_generated={prompt_stats['total_generated']}"
-    )
+    prompt_stats = export_prompts(codex_home=codex_home, include_mcp=args.mcp, dry_run=args.dry_run)
+    print(f"prompts: added={prompt_stats['added']} total={prompt_stats['total_generated']}")
 
     bootstrap_stats = None
-    if not args.skip_bootstrap:
+    if not args.no_deps:
         bootstrap_stats = bootstrap_deps(
             codex_home=codex_home,
-            include_mcp=args.include_mcp,
-            include_test_deps=args.include_test_deps,
+            include_mcp=args.mcp,
             dry_run=args.dry_run,
         )
         print(
-            f"bootstrap: python_ok={bootstrap_stats['python_ok']} "
-            f"python_fail={bootstrap_stats['python_fail']}"
+            f"bootstrap: py_ok={bootstrap_stats['python_ok']} "
+            f"py_fail={bootstrap_stats['python_fail']}"
         )
         if (bootstrap_stats["python_fail"] or bootstrap_stats["node_fail"]) and not args.dry_run:
             raise SyncError("Dependency bootstrap reported failures")
 
-    verify_stats = None
-    if not args.skip_verify:
-        verify_stats = verify_runtime(codex_home=codex_home, dry_run=args.dry_run)
-        print(f"verify: {verify_stats}")
+    verify_stats = verify_runtime(codex_home=codex_home, dry_run=args.dry_run)
+    print(f"verify: {verify_stats}")
 
-    # Save registry
     if not args.dry_run:
         save_registry(codex_home, registry)
 
@@ -173,21 +207,19 @@ def main() -> int:
         "source": str(source) if use_live else str(zip_path),
         "source_mode": "live" if use_live else "zip",
         "codex_home": str(codex_home),
-        "workspace": str(workspace),
-        "dry_run": args.dry_run,
-        "include_mcp": args.include_mcp,
-        "include_hooks": args.include_hooks,
+        "scope": "global" if args.global_scope else "project",
+        "fresh": args.fresh,
         "assets": assets_stats,
         "skills": skills_stats,
         "normalize_changed": changed,
         "agent_toml_changed": agent_toml_changed,
-        "baseline_changed": baseline_changed,
+        "agents_registered": agents_registered,
         "prompts": prompt_stats,
         "bootstrap": bootstrap_stats,
         "verify": verify_stats,
     }
     print_summary(summary)
-    print("done: claudekit all-in-one sync completed")
+    print("done: ckc-sync completed")
     return 0
 
 

package/src/claudekit_codex_sync/constants.py

@@ -2,19 +2,8 @@
 
 from typing import List, Set, Tuple
 
-ASSET_DIRS = {"agents", "commands", "output-styles", "rules", "scripts"}
-ASSET_FILES = {
-    "CLAUDE.md",
-    ".ck.json",
-    ".ckignore",
-    ".env.example",
-    ".mcp.json.example",
-    "settings.json",
-    "metadata.json",
-    "statusline.cjs",
-    "statusline.sh",
-    "statusline.ps1",
-}
+ASSET_DIRS = {"commands", "output-styles", "scripts"}
+ASSET_FILES = {".env.example"}
 ASSET_MANIFEST = ".sync-manifest-assets.txt"
 PROMPT_MANIFEST = ".claudekit-generated-prompts.txt"
 REGISTRY_FILE = ".claudekit-sync-registry.json"

package/src/claudekit_codex_sync/dep_bootstrapper.py

@@ -10,34 +10,88 @@ from typing import Dict
 from .utils import eprint, is_excluded_path, run_cmd
 
 
+def _try_symlink_venv(codex_home: Path, *, dry_run: bool) -> bool:
+    """Try to symlink from existing ClaudeKit venv. Returns True if successful."""
+    source_venv = Path.home() / ".claude" / "skills" / ".venv"
+    target_venv = codex_home / "skills" / ".venv"
+
+    if target_venv.is_symlink() and not target_venv.resolve().exists():
+        if not dry_run:
+            target_venv.unlink()
+
+    if target_venv.is_symlink() and target_venv.resolve().exists():
+        print("skip: skills/.venv (symlink intact)")
+        return True
+    if target_venv.exists() and not target_venv.is_symlink():
+        print("skip: skills/.venv (exists)")
+        return True
+
+    if source_venv.exists():
+        if not dry_run:
+            target_venv.parent.mkdir(parents=True, exist_ok=True)
+            if target_venv.is_symlink():
+                target_venv.unlink()
+            target_venv.symlink_to(source_venv)
+        print(f"symlink: skills/.venv -> {source_venv}")
+        return True
+
+    return False
+
+
+def _install_node_deps(*, skills_dir: Path, include_mcp: bool, dry_run: bool) -> tuple[int, int]:
+    """Install Node dependencies for skills."""
+    node_ok = node_fail = 0
+    npm = shutil.which("npm")
+    if not npm:
+        eprint("npm not found; skipping Node dependency bootstrap")
+        return node_ok, node_fail
+
+    pkg_files = sorted(skills_dir.rglob("package.json"))
+    for pkg in pkg_files:
+        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}")
+    return node_ok, node_fail
+
+
 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)
+    symlinked = _try_symlink_venv(codex_home, dry_run=dry_run)
+    venv_dir = skills_dir / ".venv"
     py_bin = venv_dir / "bin" / "python3"
-    run_cmd([str(py_bin), "-m", "pip", "install", "--upgrade", "pip"], dry_run=dry_run)
+    if symlinked and not dry_run and not py_bin.exists():
+        eprint("warn: skills/.venv missing bin/python3, recreating local venv")
+        if venv_dir.is_symlink():
+            venv_dir.unlink()
+        symlinked = False
+
+    if not symlinked:
+        if not shutil.which("python3"):
+            from .utils import SyncError
+
+            raise SyncError("python3 not found")
+        run_cmd(["python3", "-m", "venv", str(venv_dir)], dry_run=dry_run)
+        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:
@@ -47,23 +101,11 @@ def bootstrap_deps(
             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")
+    node_ok, node_fail = _install_node_deps(
+        skills_dir=skills_dir,
+        include_mcp=include_mcp,
+        dry_run=dry_run,
+    )
 
     return {
         "python_ok": py_ok,

package/src/claudekit_codex_sync/path_normalizer.py

@@ -83,6 +83,8 @@ def convert_agents_md_to_toml(*, codex_home: Path, dry_run: bool) -> int:
     agents_dir = codex_home / "agents"
     if not agents_dir.exists():
         return 0
+    if not dry_run:
+        agents_dir.mkdir(parents=True, exist_ok=True)
 
     converted = 0
     for md_file in sorted(agents_dir.glob("*.md")):