icdev 1.0.0__py3-none-any.whl

icdev/tools/observability/tracer.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""ICDEV Tracer ABCs — Pluggable tracing abstraction (D280).
+
+Follows the Haystack ProxyTracer pattern:
+  - Span ABC: represents a single operation with attributes, events, status
+  - Tracer ABC: creates spans, manages lifecycle
+  - NullTracer/NullSpan: zero-overhead no-op implementations
+  - ProxyTracer: delegates to actual tracer, swappable at runtime
+
+Content tagging follows Haystack's set_content_tag() pattern (D282):
+  - SHA-256 hash always recorded
+  - Plaintext only when ICDEV_CONTENT_TRACING_ENABLED=true
+
+Architecture decisions:
+  D280 — Pluggable Tracer ABC (consistent with D66 LLMProvider, D116 BaseAssessor)
+  D282 — Content tracing opt-in via env var (CUI environments)
+"""
+
+import hashlib
+import os
+import uuid
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence
+
+
+# Content tracing gate (D282)
+def _content_tracing_enabled() -> bool:
+    """Check if plaintext content tracing is enabled."""
+    return os.environ.get("ICDEV_CONTENT_TRACING_ENABLED", "").lower() in (
+        "true", "1", "yes",
+    )
+
+
+def set_content_tag(span: "Span", key: str, value: str) -> None:
+    """Set a content tag on a span with privacy gating (D282).
+
+    Always records SHA-256 hash as {key}_hash.
+    Only records plaintext value when ICDEV_CONTENT_TRACING_ENABLED=true.
+
+    Args:
+        span: The span to tag.
+        key: Attribute key (e.g., "gen_ai.prompt").
+        value: The content value.
+    """
+    content_hash = hashlib.sha256(value.encode("utf-8")).hexdigest()
+    span.set_attribute(f"{key}_hash", content_hash)
+    if _content_tracing_enabled():
+        span.set_attribute(key, value)
+
+
+class Span(ABC):
+    """Abstract base for a trace span (D280)."""
+
+    @property
+    @abstractmethod
+    def span_id(self) -> str:
+        """Return the unique span identifier (hex string)."""
+
+    @property
+    @abstractmethod
+    def trace_id(self) -> str:
+        """Return the trace identifier (32-char hex string)."""
+
+    @property
+    @abstractmethod
+    def parent_span_id(self) -> Optional[str]:
+        """Return the parent span ID, or None for root spans."""
+
+    @abstractmethod
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set a key-value attribute on this span."""
+
+    @abstractmethod
+    def add_event(self, name: str, attributes: Optional[Dict[str, Any]] = None) -> None:
+        """Record a timestamped event on this span."""
+
+    @abstractmethod
+    def set_status(self, code: str, message: str = "") -> None:
+        """Set span status: UNSET, OK, or ERROR."""
+
+    @abstractmethod
+    def end(self) -> None:
+        """End this span and record its duration."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None:
+            self.set_status("ERROR", str(exc_val) if exc_val else "")
+        elif self._raw_status_code() == "UNSET":
+            self.set_status("OK")
+        self.end()
+        return False
+
+    def _raw_status_code(self) -> str:
+        """Return current status code. Subclasses should override."""
+        return "UNSET"
+
+
+class NullSpan(Span):
+    """No-op span that discards all data (D280 fallback)."""
+
+    def __init__(self, trace_id: str = "", span_id: str = "", parent_span_id: Optional[str] = None):
+        self._trace_id = trace_id or uuid.uuid4().hex
+        self._span_id = span_id or uuid.uuid4().hex[:16]
+        self._parent_span_id = parent_span_id
+        self._status_code = "UNSET"
+
+    @property
+    def span_id(self) -> str:
+        return self._span_id
+
+    @property
+    def trace_id(self) -> str:
+        return self._trace_id
+
+    @property
+    def parent_span_id(self) -> Optional[str]:
+        return self._parent_span_id
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        pass
+
+    def add_event(self, name: str, attributes: Optional[Dict[str, Any]] = None) -> None:
+        pass
+
+    def set_status(self, code: str, message: str = "") -> None:
+        self._status_code = code
+
+    def end(self) -> None:
+        pass
+
+    def _raw_status_code(self) -> str:
+        return self._status_code
+
+
+class Tracer(ABC):
+    """Abstract base for a tracer backend (D280)."""
+
+    @abstractmethod
+    def start_span(
+        self,
+        name: str,
+        parent: Optional[Span] = None,
+        kind: str = "INTERNAL",
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> Span:
+        """Create and start a new span.
+
+        Args:
+            name: Operation name (e.g., "mcp.tool_call", "gen_ai.invoke").
+            parent: Parent span for nesting, or None for root span.
+            kind: Span kind — INTERNAL, CLIENT, SERVER, PRODUCER, CONSUMER.
+            attributes: Initial attributes dict.
+
+        Returns:
+            A started Span instance (use as context manager).
+        """
+
+    @abstractmethod
+    def get_active_span(self) -> Optional[Span]:
+        """Return the currently active span, or None."""
+
+    @abstractmethod
+    def flush(self) -> None:
+        """Flush any buffered spans to the backend."""
+
+
+class NullTracer(Tracer):
+    """No-op tracer that creates NullSpans (D280 fallback)."""
+
+    def start_span(
+        self,
+        name: str,
+        parent: Optional[Span] = None,
+        kind: str = "INTERNAL",
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> NullSpan:
+        trace_id = parent.trace_id if parent else uuid.uuid4().hex
+        parent_id = parent.span_id if parent else None
+        return NullSpan(
+            trace_id=trace_id,
+            span_id=uuid.uuid4().hex[:16],
+            parent_span_id=parent_id,
+        )
+
+    def get_active_span(self) -> Optional[Span]:
+        return None
+
+    def flush(self) -> None:
+        pass
+
+
+class ProxyTracer(Tracer):
+    """Runtime-swappable tracer proxy (Haystack pattern, D280).
+
+    Starts as NullTracer. Call set_tracer() to activate a real backend.
+    All calls delegate to the underlying tracer.
+    """
+
+    def __init__(self):
+        self._actual: Tracer = NullTracer()
+
+    def set_tracer(self, tracer: Tracer) -> None:
+        """Set the actual tracer backend."""
+        self._actual = tracer
+
+    @property
+    def actual(self) -> Tracer:
+        """Return the underlying tracer (for type checking/inspection)."""
+        return self._actual
+
+    def start_span(
+        self,
+        name: str,
+        parent: Optional[Span] = None,
+        kind: str = "INTERNAL",
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> Span:
+        return self._actual.start_span(name, parent=parent, kind=kind, attributes=attributes)
+
+    def get_active_span(self) -> Optional[Span]:
+        return self._actual.get_active_span()
+
+    def flush(self) -> None:
+        self._actual.flush()

icdev/tools/orchestration/__init__.py

@@ -0,0 +1,2 @@
+# CUI // SP-CTI
+"""Cross-phase workflow orchestration (Phase 54, D343)."""

icdev/tools/orchestration/workflow_composer.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Cross-Phase Workflow Composer.
+
+Declarative workflow engine that composes ICDEV tools into reusable DAG-based
+workflows. Templates define tool sequences with dependencies; the engine
+resolves execution order via topological sort and runs tools via subprocess.
+
+Architecture Decisions:
+  D26:  Declarative YAML templates (no code changes to add workflows).
+  D40:  graphlib.TopologicalSorter (stdlib Python 3.9+, air-gap safe).
+  D343: Workflow composer uses declarative YAML templates + DAG resolution.
+
+Usage:
+  python tools/orchestration/workflow_composer.py --list --json
+  python tools/orchestration/workflow_composer.py --template ato_acceleration --project-id proj-test --dry-run --json
+  python tools/orchestration/workflow_composer.py --template security_hardening --project-id proj-test --json
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+from graphlib import TopologicalSorter, CycleError
+from pathlib import Path
+
+import yaml
+from icdev._paths import get_project_root
+
+BASE_DIR = get_project_root()
+TEMPLATE_DIR = BASE_DIR / "args" / "workflow_templates"
+
+
+def _load_template(template_name: str) -> dict:
+    """Load a workflow template from YAML.
+
+    Args:
+        template_name: Template name (without .yaml extension).
+
+    Returns:
+        Parsed template dict.
+
+    Raises:
+        FileNotFoundError: If template doesn't exist.
+        ValueError: If template is invalid.
+    """
+    template_file = TEMPLATE_DIR / f"{template_name}.yaml"
+    if not template_file.exists():
+        raise FileNotFoundError(f"Template not found: {template_file}")
+
+    with open(template_file, "r", encoding="utf-8") as f:
+        template = yaml.safe_load(f)
+
+    if not template or "steps" not in template:
+        raise ValueError(f"Template {template_name} missing 'steps' key")
+
+    return template
+
+
+def _resolve_dag(steps: list) -> list:
+    """Resolve step execution order via topological sort.
+
+    Args:
+        steps: List of step dicts with 'id' and optional 'depends_on'.
+
+    Returns:
+        Ordered list of step IDs respecting dependencies.
+
+    Raises:
+        CycleError: If circular dependencies detected.
+    """
+    graph = {}
+    for step in steps:
+        step_id = step["id"]
+        deps = step.get("depends_on", [])
+        graph[step_id] = set(deps)
+
+    sorter = TopologicalSorter(graph)
+    return list(sorter.static_order())
+
+
+def _build_command(step: dict, project_id: str, overrides: dict = None) -> list:
+    """Build subprocess command from step definition.
+
+    Args:
+        step: Step dict with 'tool' (Python module path) and optional 'args'.
+        project_id: Project ID to inject.
+        overrides: Optional argument overrides.
+
+    Returns:
+        Command list suitable for subprocess.run().
+    """
+    tool_path = step.get("tool", "")
+    if not tool_path:
+        return []
+
+    # Resolve tool path relative to project root
+    full_path = BASE_DIR / tool_path
+    cmd = [sys.executable, str(full_path)]
+
+    # Add standard args
+    step_args = step.get("args", {})
+    if overrides:
+        step_args.update(overrides)
+
+    # Inject project_id if tool expects it
+    if step.get("inject_project_id", True) and "--project-id" not in str(step_args):
+        cmd.extend(["--project-id", project_id])
+
+    # Add --json for structured output
+    if step.get("json_output", True):
+        cmd.append("--json")
+
+    # Add step-specific args
+    for key, value in step_args.items():
+        if isinstance(value, bool) and value:
+            cmd.append(f"--{key}")
+        elif not isinstance(value, bool):
+            cmd.extend([f"--{key}", str(value)])
+
+    return cmd
+
+
+def list_templates() -> list:
+    """List all available workflow templates.
+
+    Returns:
+        List of template summaries with name, description, step count.
+    """
+    templates = []
+    if not TEMPLATE_DIR.exists():
+        return templates
+
+    for f in sorted(TEMPLATE_DIR.glob("*.yaml")):
+        try:
+            with open(f, "r", encoding="utf-8") as fh:
+                data = yaml.safe_load(fh)
+            if data and "steps" in data:
+                templates.append({
+                    "name": f.stem,
+                    "description": data.get("description", ""),
+                    "steps": len(data["steps"]),
+                    "category": data.get("category", "general"),
+                    "file": str(f),
+                })
+        except Exception:
+            continue
+
+    return templates
+
+
+def compose_workflow(
+    template_name: str,
+    project_id: str,
+    overrides: dict = None,
+) -> dict:
+    """Compose a workflow execution plan from a template.
+
+    Args:
+        template_name: Template name.
+        project_id: Project ID for tool injection.
+        overrides: Optional argument overrides per step.
+
+    Returns:
+        Execution plan with ordered steps and commands.
+    """
+    template = _load_template(template_name)
+    steps = template["steps"]
+
+    # Resolve DAG order
+    try:
+        execution_order = _resolve_dag(steps)
+    except CycleError as e:
+        raise ValueError(f"Circular dependency in template {template_name}: {e}")
+
+    # Build step lookup
+    step_map = {s["id"]: s for s in steps}
+    overrides = overrides or {}
+
+    # Build execution plan
+    plan_steps = []
+    for step_id in execution_order:
+        step = step_map[step_id]
+        step_overrides = overrides.get(step_id, {})
+        cmd = _build_command(step, project_id, step_overrides)
+
+        plan_steps.append({
+            "id": step_id,
+            "name": step.get("name", step_id),
+            "tool": step.get("tool", ""),
+            "depends_on": step.get("depends_on", []),
+            "command": cmd,
+            "description": step.get("description", ""),
+            "required": step.get("required", True),
+            "timeout_seconds": step.get("timeout", 300),
+        })
+
+    return {
+        "workflow_id": f"wf-{uuid.uuid4().hex[:8]}",
+        "template": template_name,
+        "project_id": project_id,
+        "description": template.get("description", ""),
+        "category": template.get("category", "general"),
+        "total_steps": len(plan_steps),
+        "steps": plan_steps,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def execute_workflow(
+    plan: dict,
+    dry_run: bool = False,
+) -> dict:
+    """Execute a composed workflow plan.
+
+    Args:
+        plan: Execution plan from compose_workflow().
+        dry_run: If True, print commands without executing.
+
+    Returns:
+        Execution results with per-step status.
+    """
+    results = {
+        "workflow_id": plan["workflow_id"],
+        "template": plan["template"],
+        "project_id": plan["project_id"],
+        "dry_run": dry_run,
+        "steps": [],
+        "started_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    overall_success = True
+
+    for step in plan["steps"]:
+        step_result = {
+            "id": step["id"],
+            "name": step["name"],
+            "command": " ".join(step["command"]),
+            "status": "pending",
+            "output": None,
+            "error": None,
+            "duration_ms": 0,
+        }
+
+        if dry_run:
+            step_result["status"] = "dry_run"
+            results["steps"].append(step_result)
+            continue
+
+        if not step["command"]:
+            step_result["status"] = "skip"
+            step_result["error"] = "No tool path configured"
+            results["steps"].append(step_result)
+            continue
+
+        # Check tool file exists
+        tool_path = step.get("tool", "")
+        if tool_path:
+            full_tool_path = BASE_DIR / tool_path
+            if not full_tool_path.exists():
+                step_result["status"] = "skip"
+                step_result["error"] = f"Tool not found: {tool_path}"
+                results["steps"].append(step_result)
+                if step.get("required", True):
+                    overall_success = False
+                continue
+
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(
+                step["command"],
+                capture_output=True,
+                text=True,
+                timeout=step.get("timeout_seconds", 300),
+                stdin=subprocess.DEVNULL,
+                cwd=str(BASE_DIR),
+            )
+            elapsed = int((time.monotonic() - start) * 1000)
+            step_result["duration_ms"] = elapsed
+
+            if proc.returncode == 0:
+                step_result["status"] = "pass"
+                # Try to parse JSON output
+                try:
+                    step_result["output"] = json.loads(proc.stdout)
+                except (json.JSONDecodeError, ValueError):
+                    step_result["output"] = proc.stdout.strip()[:2000] if proc.stdout else None
+            else:
+                step_result["status"] = "fail"
+                step_result["error"] = proc.stderr.strip()[:2000] if proc.stderr else f"Exit code {proc.returncode}"
+                if step.get("required", True):
+                    overall_success = False
+
+        except subprocess.TimeoutExpired:
+            step_result["status"] = "timeout"
+            step_result["error"] = f"Timed out after {step.get('timeout_seconds', 300)}s"
+            if step.get("required", True):
+                overall_success = False
+        except Exception as e:
+            step_result["status"] = "error"
+            step_result["error"] = str(e)
+            if step.get("required", True):
+                overall_success = False
+
+        results["steps"].append(step_result)
+
+    results["finished_at"] = datetime.now(timezone.utc).isoformat()
+    results["overall_status"] = "pass" if overall_success else "fail"
+    results["passed"] = sum(1 for s in results["steps"] if s["status"] in ("pass", "dry_run"))
+    results["failed"] = sum(1 for s in results["steps"] if s["status"] in ("fail", "timeout", "error"))
+    results["skipped"] = sum(1 for s in results["steps"] if s["status"] == "skip")
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Cross-Phase Workflow Composer (D343)"
+    )
+    parser.add_argument("--template", help="Workflow template name")
+    parser.add_argument("--project-id", help="Project ID", dest="project_id")
+    parser.add_argument("--list", action="store_true", help="List available templates")
+    parser.add_argument("--dry-run", action="store_true", dest="dry_run", help="Preview commands without executing")
+    parser.add_argument("--json", action="store_true", dest="json_output", help="JSON output")
+    parser.add_argument("--human", action="store_true", help="Human-readable output")
+    args = parser.parse_args()
+
+    if args.list:
+        templates = list_templates()
+        if args.json_output:
+            print(json.dumps({"templates": templates, "count": len(templates)}, indent=2))
+        else:
+            print(f"\n=== Available Workflow Templates ({len(templates)}) ===")
+            for t in templates:
+                print(f"  {t['name']:30s} {t['steps']:3d} steps  {t['description']}")
+        return
+
+    if not args.template:
+        parser.error("--template required (or use --list)")
+    if not args.project_id:
+        parser.error("--project-id required with --template")
+
+    plan = compose_workflow(args.template, args.project_id)
+    result = execute_workflow(plan, dry_run=args.dry_run)
+
+    if args.json_output:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        print(f"\n=== Workflow: {result['template']} ===")
+        print(f"  Status: {result['overall_status']}")
+        print(f"  Steps: {result['passed']} passed, {result['failed']} failed, {result['skipped']} skipped")
+        for step in result["steps"]:
+            icon = {"pass": "+", "fail": "X", "skip": "-", "dry_run": "~", "timeout": "T", "error": "!"}
+            print(f"  [{icon.get(step['status'], '?')}] {step['name']}: {step['status']} ({step['duration_ms']}ms)")
+
+
+if __name__ == "__main__":
+    main()

icdev/tools/project/__init__.py

@@ -0,0 +1 @@
+# [TEMPLATE: CUI // SP-CTI]