icdev 1.0.0__py3-none-any.whl

icdev/tools/dx/skill_translator.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Translate Claude Code skills to other AI coding tool formats.
+
+ADR D198: Skill translation preserves semantic intent — each tool gets
+equivalent capability in its native format, not a literal copy.
+
+Reads .claude/skills/*/SKILL.md and generates equivalent skill/command
+files for Codex (.agents/skills/), Copilot (.github/prompts/), and
+Cursor (.cursor/rules/).
+
+Usage:
+    python tools/dx/skill_translator.py --all --write --json
+    python tools/dx/skill_translator.py --platform codex --skills icdev-build
+    python tools/dx/skill_translator.py --platform copilot --write
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from icdev._paths import get_project_root
+
+BASE_DIR = get_project_root()
+SKILLS_DIR = BASE_DIR / ".claude" / "skills"
+
+
+# ── Skill Parser ────────────────────────────────────────────────────────
+
+def parse_claude_skill(skill_dir):
+    """Parse a .claude/skills/*/SKILL.md into structured data.
+
+    Returns:
+        dict with: name, description, context, allowed_tools, usage,
+        steps, hard_prompts, examples, error_handling, raw_body
+    """
+    skill_path = Path(skill_dir) / "SKILL.md"
+    if not skill_path.exists():
+        return None
+
+    text = skill_path.read_text(encoding="utf-8")
+
+    # Parse YAML frontmatter
+    frontmatter = {}
+    body = text
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            fm_text = parts[1].strip()
+            body = parts[2].strip()
+            for line in fm_text.split("\n"):
+                if ":" in line:
+                    key, _, val = line.partition(":")
+                    frontmatter[key.strip()] = val.strip()
+
+    # Extract sections from body
+    sections = {}
+    current_section = "intro"
+    current_lines = []
+    for line in body.split("\n"):
+        header_match = re.match(r"^##\s+(.+)$", line)
+        if header_match:
+            sections[current_section] = "\n".join(current_lines).strip()
+            current_section = header_match.group(1).strip().lower()
+            current_lines = []
+        else:
+            current_lines.append(line)
+    sections[current_section] = "\n".join(current_lines).strip()
+
+    # Extract steps (### sub-sections within Steps or body)
+    steps = []
+    step_pattern = re.compile(r"^###\s+(\d+)\.\s+(.+)$")
+    in_steps = False
+    current_step = None
+    step_lines = []
+    for line in body.split("\n"):
+        if line.strip().lower().startswith("## steps"):
+            in_steps = True
+            continue
+        if in_steps and line.startswith("## ") and not line.startswith("### "):
+            if current_step:
+                steps.append({"title": current_step, "body": "\n".join(step_lines).strip()})
+            in_steps = False
+            continue
+        if in_steps:
+            m = step_pattern.match(line)
+            if m:
+                if current_step:
+                    steps.append({"title": current_step, "body": "\n".join(step_lines).strip()})
+                current_step = m.group(2).strip()
+                step_lines = []
+            else:
+                step_lines.append(line)
+    if current_step:
+        steps.append({"title": current_step, "body": "\n".join(step_lines).strip()})
+
+    return {
+        "name": frontmatter.get("name", Path(skill_dir).name),
+        "description": frontmatter.get("description", ""),
+        "context": frontmatter.get("context", "fork"),
+        "allowed_tools": frontmatter.get("allowed-tools", ""),
+        "usage": sections.get("usage", ""),
+        "what_this_does": sections.get("what this does", ""),
+        "steps": steps,
+        "hard_prompts": sections.get("hard prompts referenced", ""),
+        "example": sections.get("example", ""),
+        "error_handling": sections.get("error handling", ""),
+        "raw_body": body,
+        "source_path": str(skill_path),
+    }
+
+
+def list_skills(skills_dir=None):
+    """List all available Claude Code skills."""
+    sd = Path(skills_dir) if skills_dir else SKILLS_DIR
+    if not sd.exists():
+        return []
+    return sorted([
+        d.name for d in sd.iterdir()
+        if d.is_dir() and (d / "SKILL.md").exists()
+    ])
+
+
+# ── Translators ─────────────────────────────────────────────────────────
+
+def _translate_to_codex_skill(skill_data):
+    """Generate .agents/skills/{name}/SKILL.md for OpenAI Codex.
+
+    Codex skills use same YAML frontmatter + markdown body format as Claude,
+    but invoked with $skill-name syntax.
+    """
+    name = skill_data["name"]
+    desc = skill_data["description"]
+    tools = skill_data["allowed_tools"]
+
+    lines = [
+        "---",
+        f"name: {name}",
+        f"description: {desc}",
+    ]
+    if tools:
+        lines.append(f"allowed-tools: {tools}")
+    lines.append("---")
+    lines.append("")
+    lines.append(f"# ${name}")
+    lines.append("")
+
+    if skill_data["what_this_does"]:
+        lines.append("## What This Does")
+        lines.append(skill_data["what_this_does"])
+        lines.append("")
+
+    if skill_data["steps"]:
+        lines.append("## Steps")
+        lines.append("")
+        for i, step in enumerate(skill_data["steps"], 1):
+            lines.append(f"### {i}. {step['title']}")
+            # Replace MCP tool references with CLI equivalents
+            body = step["body"]
+            body = body.replace("Use the `", "Run the CLI command or use MCP tool `")
+            lines.append(body)
+            lines.append("")
+
+    if skill_data["example"]:
+        lines.append("## Example")
+        # Replace /command with $command syntax
+        example = skill_data["example"].replace(f"/{name}", f"${name}")
+        lines.append(example)
+        lines.append("")
+
+    if skill_data["error_handling"]:
+        lines.append("## Error Handling")
+        lines.append(skill_data["error_handling"])
+
+    return "\n".join(lines)
+
+
+def _translate_to_copilot_prompt(skill_data):
+    """Generate .github/prompts/{name}.prompt.md for GitHub Copilot.
+
+    Copilot prompt files use YAML frontmatter with mode, description, tools.
+    """
+    name = skill_data["name"]
+    desc = skill_data["description"]
+
+    lines = [
+        "---",
+        "mode: agent",
+        f"description: \"{desc}\"",
+        "tools:",
+        "  - terminal",
+        "  - file_search",
+        "---",
+        "",
+        f"# {name}",
+        "",
+    ]
+
+    if skill_data["what_this_does"]:
+        lines.append(skill_data["what_this_does"])
+        lines.append("")
+
+    if skill_data["steps"]:
+        lines.append("## Steps")
+        lines.append("")
+        for i, step in enumerate(skill_data["steps"], 1):
+            lines.append(f"{i}. **{step['title']}**")
+            # Convert MCP references to terminal commands
+            body = step["body"]
+            body = re.sub(
+                r"Use the `(\w+)` MCP tool from (\w[\w-]*)",
+                r"Run the equivalent CLI command for \1",
+                body,
+            )
+            # Keep code blocks, trim excessive detail
+            code_blocks = re.findall(r"```[^`]*```", body, re.DOTALL)
+            if code_blocks:
+                for block in code_blocks:
+                    lines.append(block)
+            else:
+                # Include first 3 lines of body
+                body_lines = [l for l in body.split("\n") if l.strip()][:3]
+                lines.extend(body_lines)
+            lines.append("")
+
+    if skill_data["example"]:
+        lines.append("## Example")
+        example = skill_data["example"].replace(f"/{name}", f"#prompt:{name}")
+        lines.append(example)
+
+    return "\n".join(lines)
+
+
+def _translate_to_cursor_rule(skill_data):
+    """Generate .cursor/rules/{name}.mdc for Cursor.
+
+    Cursor rules use MDC format with frontmatter: description, globs.
+    Agent-requested rules are triggered when the AI decides they're relevant.
+    """
+    name = skill_data["name"]
+    desc = skill_data["description"]
+
+    lines = [
+        "---",
+        f"description: \"ICDEV workflow: {desc}\"",
+        "globs:",
+        '  - "**/*.py"',
+        '  - "**/*.yaml"',
+        "---",
+        "",
+        f"# {name}",
+        "",
+        f"When the user asks to {desc.lower()}, follow these steps:",
+        "",
+    ]
+
+    if skill_data["steps"]:
+        for i, step in enumerate(skill_data["steps"], 1):
+            lines.append(f"{i}. **{step['title']}**")
+            # Convert to concise CLI instructions
+            body = step["body"]
+            # Extract bash commands
+            commands = re.findall(r"```(?:bash)?\s*\n(.*?)```", body, re.DOTALL)
+            if commands:
+                for cmd in commands:
+                    for cmd_line in cmd.strip().split("\n"):
+                        if cmd_line.strip() and not cmd_line.startswith("#"):
+                            lines.append(f"   ```bash")
+                            lines.append(f"   {cmd_line.strip()}")
+                            lines.append(f"   ```")
+            else:
+                # Summarize the step
+                summary = re.sub(
+                    r"Use the `\w+` MCP tool from [\w-]+[:\s]*",
+                    "Run: ",
+                    body,
+                )
+                first_line = summary.strip().split("\n")[0][:120]
+                if first_line:
+                    lines.append(f"   {first_line}")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+# ── Orchestrator ────────────────────────────────────────────────────────
+
+TRANSLATORS = {
+    "codex": ("codex_skill", _translate_to_codex_skill, ".agents/skills/{name}/SKILL.md"),
+    "copilot": ("copilot_prompt", _translate_to_copilot_prompt, ".github/prompts/{name}.prompt.md"),
+    "cursor": ("cursor_mdc", _translate_to_cursor_rule, ".cursor/rules/{name}.mdc"),
+}
+
+
+def translate_skills(directory=None, platforms=None, skills=None,
+                     write=False, dry_run=False):
+    """Translate Claude Code skills to other tool formats.
+
+    Args:
+        directory: Project root directory.
+        platforms: List of platform IDs or ['all'].
+        skills: List of skill names or None for all.
+        write: Write files to disk.
+        dry_run: Preview without writing.
+
+    Returns:
+        dict: {platform: {skill_name: {path, content, written}}}
+    """
+    directory = Path(directory) if directory else Path.cwd()
+    skills_dir = directory / ".claude" / "skills"
+
+    # Resolve skills to translate
+    available = list_skills(str(skills_dir))
+    if skills:
+        target_skills = [s for s in skills if s in available]
+    else:
+        target_skills = available
+
+    # Resolve platforms
+    if platforms is None or platforms == ["all"]:
+        platforms = list(TRANSLATORS.keys())
+    elif isinstance(platforms, str):
+        platforms = [p.strip() for p in platforms.split(",")]
+
+    results = {}
+
+    for platform in platforms:
+        if platform not in TRANSLATORS:
+            results[platform] = {"error": f"No translator for platform: {platform}"}
+            continue
+
+        fmt_name, translator_fn, path_template = TRANSLATORS[platform]
+        platform_results = {}
+
+        for skill_name in target_skills:
+            skill_data = parse_claude_skill(skills_dir / skill_name)
+            if not skill_data:
+                platform_results[skill_name] = {"error": "Could not parse skill"}
+                continue
+
+            content = translator_fn(skill_data)
+            output_path = path_template.format(name=skill_name)
+            full_path = directory / output_path
+
+            written = False
+            if write and not dry_run:
+                full_path.parent.mkdir(parents=True, exist_ok=True)
+                full_path.write_text(content, encoding="utf-8")
+                written = True
+
+            platform_results[skill_name] = {
+                "path": output_path,
+                "full_path": str(full_path),
+                "content": content,
+                "written": written,
+                "size_bytes": len(content.encode("utf-8")),
+            }
+
+        results[platform] = platform_results
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Translate Claude Code skills to other AI tool formats"
+    )
+    parser.add_argument("--dir", help="Project directory")
+    parser.add_argument("--platform", help="Comma-separated platform IDs")
+    parser.add_argument("--all", action="store_true", help="All platforms")
+    parser.add_argument("--skills", help="Comma-separated skill names")
+    parser.add_argument("--write", action="store_true", help="Write files")
+    parser.add_argument("--dry-run", action="store_true", help="Preview")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    parser.add_argument("--list", action="store_true", help="List available skills")
+    args = parser.parse_args()
+
+    if args.list:
+        skills = list_skills()
+        if args.json:
+            print(json.dumps({"skills": skills, "count": len(skills)}))
+        else:
+            print(f"Available skills ({len(skills)}):")
+            for s in skills:
+                print(f"  - {s}")
+        return
+
+    platforms = ["all"] if args.all else (
+        [p.strip() for p in args.platform.split(",")] if args.platform else None
+    )
+    skills = [s.strip() for s in args.skills.split(",")] if args.skills else None
+
+    results = translate_skills(
+        directory=args.dir, platforms=platforms, skills=skills,
+        write=args.write, dry_run=args.dry_run,
+    )
+
+    if args.json:
+        out = {}
+        for platform, platform_results in results.items():
+            if "error" in platform_results:
+                out[platform] = platform_results
+                continue
+            p_out = {}
+            for sk, info in platform_results.items():
+                p_out[sk] = {k: v for k, v in info.items() if k != "content"}
+            out[platform] = p_out
+        print(json.dumps(out, indent=2))
+    else:
+        for platform, platform_results in results.items():
+            if "error" in platform_results:
+                print(f"ERROR [{platform}]: {platform_results['error']}")
+                continue
+            print(f"\n{platform}:")
+            for skill_name, info in platform_results.items():
+                if "error" in info:
+                    print(f"  ERROR [{skill_name}]: {info['error']}")
+                    continue
+                status = "WRITTEN" if info["written"] else "PREVIEW"
+                print(f"  [{status}] {skill_name} -> {info['path']} ({info['size_bytes']} bytes)")
+
+
+if __name__ == "__main__":
+    main()

icdev/tools/dx/tool_detector.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Detect which AI coding tools are present in the current environment.
+
+ADR D197: Detection is advisory — auto-detect for convenience,
+explicit --platform override for certainty (D110/D185 pattern).
+
+Checks environment variables, configuration directories, and config
+files to determine which AI coding tools are active or installed.
+
+Usage:
+    python tools/dx/tool_detector.py --json
+    python tools/dx/tool_detector.py --dir /path/to/project
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from icdev._paths import get_project_root
+
+BASE_DIR = get_project_root()
+try:
+    import yaml as _yaml
+
+    def _load_yaml(path):
+        with open(path, encoding="utf-8") as f:
+            return _yaml.safe_load(f)
+except ImportError:
+    _yaml = None  # type: ignore[assignment]
+
+    def _load_yaml(path):
+        """Minimal YAML subset loader for the companion registry."""
+        import re
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {}
+
+
+REGISTRY_PATH = BASE_DIR / "args" / "companion_registry.yaml"
+
+
+def _load_registry(registry_path=None):
+    """Load the companion registry."""
+    path = Path(registry_path) if registry_path else REGISTRY_PATH
+    if not path.exists():
+        return {}
+    return _load_yaml(str(path))
+
+
+def detect_tools(directory=None, registry_path=None):
+    """Detect AI coding tools from env vars, config dirs, config files.
+
+    Returns:
+        dict with keys:
+        - detected: list of {tool_id, display_name, confidence, evidence}
+        - primary: tool_id of highest-confidence tool or None
+        - all_tools: list of all registered tool_ids
+    """
+    directory = Path(directory) if directory else Path.cwd()
+    registry = _load_registry(registry_path)
+    companions = registry.get("companions", {})
+
+    detected = []
+    for tool_id, config in companions.items():
+        evidence = []
+        detection = config.get("env_detection", {})
+
+        # Check env vars
+        for var in detection.get("env_vars", []):
+            if os.environ.get(var):
+                evidence.append(f"env:{var}")
+
+        # Check config directories
+        for d in detection.get("config_dirs", []):
+            if (directory / d).is_dir():
+                evidence.append(f"dir:{d}")
+
+        # Check config files
+        for f in detection.get("config_files", []):
+            if (directory / f).exists():
+                evidence.append(f"file:{f}")
+
+        # Check instruction file exists
+        inst_file = config.get("instruction_file", "")
+        if inst_file and (directory / inst_file).exists():
+            evidence.append(f"instruction:{inst_file}")
+
+        if evidence:
+            confidence = min(1.0, len(evidence) * 0.4)
+            detected.append({
+                "tool_id": tool_id,
+                "display_name": config.get("display_name", tool_id),
+                "vendor": config.get("vendor", "unknown"),
+                "confidence": round(confidence, 2),
+                "evidence": evidence,
+                "mcp_support": config.get("mcp_support", False),
+                "skill_format": config.get("skill_format", "none"),
+            })
+
+    # Sort by confidence descending
+    detected.sort(key=lambda x: x["confidence"], reverse=True)
+
+    return {
+        "detected": detected,
+        "primary": detected[0]["tool_id"] if detected else None,
+        "all_tools": list(companions.keys()),
+        "directory": str(directory),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Detect AI coding tools in the current environment"
+    )
+    parser.add_argument("--dir", help="Directory to scan")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    parser.add_argument("--registry", help="Path to companion registry YAML")
+    args = parser.parse_args()
+
+    result = detect_tools(directory=args.dir, registry_path=args.registry)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if not result["detected"]:
+            print("No AI coding tools detected.")
+            print(f"Registered tools: {', '.join(result['all_tools'])}")
+        else:
+            print(f"Detected {len(result['detected'])} AI coding tool(s):")
+            for t in result["detected"]:
+                mcp = " [MCP]" if t["mcp_support"] else ""
+                print(f"  {t['display_name']}{mcp} (confidence: {t['confidence']})")
+                for e in t["evidence"]:
+                    print(f"    - {e}")
+            print(f"\nPrimary: {result['primary']}")
+
+
+if __name__ == "__main__":
+    main()

icdev/tools/extensions/__init__.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Active extension hook system (Phase 44 — D261-D264).
+
+Adapted from Agent Zero's extension point architecture. Extensions can be
+behavioral (modify data flowing through) or observational (log/audit only).
+"""
+
+from icdev.tools.extensions.extension_manager import (
+    ExtensionPoint,
+    ExtensionHandler,
+    ExtensionManager,
+    extension_manager,
+)
+
+__all__ = [
+    "ExtensionPoint",
+    "ExtensionHandler",
+    "ExtensionManager",
+    "extension_manager",
+]