devcouncil 0.3.1 → 0.4.0

package/src/devcouncil/cli/commands/cost.py

@@ -1,4 +1,5 @@
-import json
+from devcouncil.utils.json_persist import dump_json
+import logging
 from pathlib import Path
 
 import typer
@@ -6,9 +7,11 @@ from rich.console import Console
 from rich.table import Table
 
 from devcouncil.telemetry.cost import group_cost
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="Inspect DevCouncil model-call cost, grouped by task and run.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.command("show")
@@ -23,35 +26,141 @@ def show(
     grouped under ``(unattributed)``.
     """
     root = project_root.expanduser().resolve()
-    summary = group_cost(root)
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev cost show: json=%s", json_format)
 
-    if json_format:
-        typer.echo(json.dumps(summary, indent=2))
-        return
+    with log_stage("cost", project_root=root):
+        log_step("cost/1: aggregating model-call ledger", project_root=root, trace=True)
+        summary = group_cost(root)
 
-    console.print(
-        f"[bold]Total Cost:[/bold] ${summary['total_cost']:.4f} "
-        f"across {summary['total_calls']} model call(s)"
-    )
-
-    def _render(title: str, groups: dict) -> None:
-        if not groups:
+        if json_format:
+            typer.echo(dump_json(summary, indent=2))
+            log_step("cost/complete", project_root=root, trace=True)
             return
-        table = Table(title=title)
-        table.add_column("Group", style="cyan")
-        table.add_column("Cost ($)", justify="right")
-        table.add_column("Calls", justify="right")
-        table.add_column("Prompt", justify="right")
-        table.add_column("Completion", justify="right")
-        for name, stats in sorted(groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
-            table.add_row(
-                name,
-                f"{stats['cost']:.4f}",
-                str(stats["calls"]),
-                str(stats["prompt_tokens"]),
-                str(stats["completion_tokens"]),
+
+        console.print(
+            f"[bold]Total Cost:[/bold] ${summary['total_cost']:.4f} "
+            f"across {summary['total_calls']} model call(s)"
+        )
+
+        def _render(title: str, groups: dict) -> None:
+            if not groups:
+                return
+            table = Table(title=title)
+            table.add_column("Group", style="cyan")
+            table.add_column("Cost ($)", justify="right")
+            table.add_column("Calls", justify="right")
+            table.add_column("Prompt", justify="right")
+            table.add_column("Completion", justify="right")
+            for name, stats in sorted(groups.items(), key=lambda kv: kv[1]["cost"], reverse=True):
+                table.add_row(
+                    name,
+                    f"{stats['cost']:.4f}",
+                    str(stats["calls"]),
+                    str(stats["prompt_tokens"]),
+                    str(stats["completion_tokens"]),
+                )
+            console.print(table)
+
+        _render("Cost by Task", summary["by_task"])
+        _render("Cost by Run", summary["by_run"])
+        log_step("cost/complete", project_root=root, trace=True)
+
+
+@app.command("budget")
+def budget(
+    set_value: float = typer.Option(
+        None,
+        "--set",
+        help="Set the advisory spend budget in USD (telemetry.cost_budget_usd in config.yaml).",
+    ),
+    clear: bool = typer.Option(False, "--clear", help="Remove the configured budget."),
+    json_format: bool = typer.Option(False, "--json", help="Output machine-readable JSON."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Show or configure the advisory model-spend budget.
+
+    Reports the configured budget (``telemetry.cost_budget_usd``), spend-to-date from
+    the local ``model_calls.jsonl`` ledger, and the remainder. WARN-ONLY: when
+    cumulative spend crosses the budget the telemetry tracker logs a warning, but no
+    run is ever blocked.
+    """
+    root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev cost budget: set=%s clear=%s json=%s", set_value, clear, json_format)
+
+    if set_value is not None and clear:
+        console.print("[red]Use either --set or --clear, not both.[/red]")
+        raise typer.Exit(code=2)
+
+    with log_stage("cost", project_root=root, subcommand="budget"):
+        if set_value is not None or clear:
+            import yaml
+
+            config_path = root / ".devcouncil" / "config.yaml"
+            if not config_path.exists():
+                console.print(f"[red]Config not found at {config_path}. Run 'dev init' first.[/red]")
+                raise typer.Exit(code=1)
+            if set_value is not None and set_value <= 0:
+                console.print("[red]--set expects a positive USD amount (e.g. --set 5.00).[/red]")
+                raise typer.Exit(code=2)
+
+            log_step("cost/1: updating telemetry.cost_budget_usd", project_root=root, trace=True)
+            with open(config_path, encoding="utf-8") as f:
+                raw_config = yaml.safe_load(f) or {}
+            if set_value is not None:
+                raw_config.setdefault("telemetry", {})["cost_budget_usd"] = float(set_value)
+            else:
+                telemetry_section = raw_config.get("telemetry")
+                if isinstance(telemetry_section, dict):
+                    telemetry_section.pop("cost_budget_usd", None)
+                    if not telemetry_section:
+                        raw_config.pop("telemetry", None)
+            with open(config_path, "w", encoding="utf-8") as f:
+                yaml.dump(raw_config, f, default_flow_style=False)
+            if set_value is not None:
+                console.print(f"[green]Set telemetry.cost_budget_usd = {float(set_value):.2f}[/green]")
+            else:
+                console.print("[green]Cleared telemetry.cost_budget_usd.[/green]")
+
+        log_step("cost/2: aggregating model-call ledger", project_root=root, trace=True)
+        try:
+            from devcouncil.app.config import load_config
+
+            budget_usd = load_config(root).telemetry.cost_budget_usd
+        except Exception:
+            budget_usd = None
+        spend = float(group_cost(root)["total_cost"])
+        remaining = None if budget_usd is None else budget_usd - spend
+
+        if json_format:
+            typer.echo(
+                dump_json(
+                    {
+                        "budget_usd": budget_usd,
+                        "spend_usd": spend,
+                        "remaining_usd": remaining,
+                        "over_budget": bool(budget_usd is not None and spend > budget_usd),
+                    },
+                    indent=2,
+                )
             )
-        console.print(table)
+            log_step("cost/complete", project_root=root, trace=True)
+            return
 
-    _render("Cost by Task", summary["by_task"])
-    _render("Cost by Run", summary["by_run"])
+        if budget_usd is None:
+            console.print("[bold]Budget:[/bold] not configured (set one with 'dev cost budget --set 5.00')")
+            console.print(f"[bold]Spend to date:[/bold] ${spend:.4f}")
+        else:
+            console.print(f"[bold]Budget:[/bold] ${budget_usd:.2f}")
+            console.print(f"[bold]Spend to date:[/bold] ${spend:.4f}")
+            if remaining is not None and remaining < 0:
+                console.print(
+                    f"[bold]Remaining:[/bold] [red]-${abs(remaining):.4f} "
+                    "(over budget — warn-only, runs are never blocked)[/red]"
+                )
+            else:
+                console.print(f"[bold]Remaining:[/bold] ${remaining:.4f}")
+        log_step("cost/complete", project_root=root, trace=True)

package/src/devcouncil/cli/commands/dashboard.py

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 import webbrowser
 
@@ -6,9 +7,11 @@ from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
 from devcouncil.ui.dashboard import run_dashboard
+from devcouncil.telemetry.stages import log_stage, log_step
 
 app = typer.Typer(help="Serve the live DevCouncil dashboard.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 
 @app.callback(invoke_without_command=True)
@@ -23,9 +26,14 @@ def dashboard(
     if ctx.invoked_subcommand is not None:
         return
     root = project_root.expanduser().resolve()
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev dashboard: host=%s port=%d", host, port)
     initialize_project(root, quiet=True)
     url = f"http://{host}:{port}"
-    console.print(f"Serving DevCouncil dashboard at {url}")
-    if open_browser:
-        webbrowser.open(url)
-    run_dashboard(root, host=host, port=port)
+    with log_stage("dashboard", project_root=root, host=host, port=port):
+        log_step("dashboard/1: starting server", project_root=root, trace=True)
+        console.print(f"Serving DevCouncil dashboard at {url}")
+        if open_browser:
+            webbrowser.open(url)
+        run_dashboard(root, host=host, port=port)

package/src/devcouncil/cli/commands/debug_cmd.py

@@ -0,0 +1,249 @@
+"""``dev debug`` — persistent DAP control and runtime traces."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+
+from devcouncil.codeintel.debug.broker_client import DebugBrokerClient
+from devcouncil.codeintel.debug.consent import require_debug_consent, set_debug_consent
+from devcouncil.codeintel.debug.discovery import adapter_by_id, discover_adapters
+
+app = typer.Typer(name="debug", help="Control DAP adapters and capture runtime evidence.", add_completion=False)
+console = Console()
+status = Console(stderr=True)
+
+
+def _root(path: Path) -> Path:
+    return path.expanduser().resolve()
+
+
+def _require_consent(root: Path) -> None:
+    try:
+        require_debug_consent(root)
+    except PermissionError as exc:
+        status.print(f"[yellow]{exc}[/yellow]")
+        raise typer.Exit(code=2) from None
+
+
+def _config(value: str) -> dict:
+    parsed = json.loads(value or "{}")
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter("--config-json must contain a JSON object")
+    return parsed
+
+
+def _adapter_command(adapter_id: str, command: Optional[List[str]]) -> list[str]:
+    if command:
+        return list(command)
+    adapter = adapter_by_id(adapter_id)
+    if adapter is None:
+        raise typer.BadParameter(f"Adapter {adapter_id!r} was not discovered; use repeatable --adapter-command")
+    return list(adapter.command)
+
+
+def _initial_breakpoints(values: Optional[List[str]]) -> dict[str, list[int]]:
+    result: dict[str, list[int]] = {}
+    for value in values or []:
+        source, separator, raw_line = value.rpartition(":")
+        if not separator or not source:
+            raise typer.BadParameter("--breakpoint must use PATH:LINE")
+        try:
+            line = int(raw_line)
+        except ValueError:
+            raise typer.BadParameter("--breakpoint line must be an integer") from None
+        result.setdefault(str(Path(source).expanduser().resolve()), []).append(line)
+    return result
+
+
+@app.command("discover")
+def discover(
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+    consent: bool = typer.Option(False, "--consent", help="Persist the one-time debugger opt-in."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    root = _root(project_root)
+    if consent:
+        set_debug_consent(root, True)
+    _require_consent(root)
+    rows = [adapter.as_dict() for adapter in discover_adapters()]
+    if json_output:
+        typer.echo(json.dumps({"consent": True, "adapters": rows}, indent=2))
+        return
+    for row in rows:
+        requests = "/".join(row["requests"])
+        version = row["version"] or "unknown version"
+        console.print(f"{row['id']}: {row['path']}  {version}  requests={requests}  sha256={row['executable_hash']}")
+    if not rows:
+        console.print("No supported DAP adapters discovered.")
+
+
+def _start(
+    request: str,
+    adapter: str,
+    adapter_command: Optional[List[str]],
+    config_json: str,
+    breakpoints: Optional[List[str]],
+    project_root: Path,
+) -> None:
+    root = _root(project_root)
+    _require_consent(root)
+    client = DebugBrokerClient(root)
+    client.ensure_started()
+    result = client.call("start", {
+        "adapter_command": _adapter_command(adapter, adapter_command),
+        "request": request,
+        "arguments": _config(config_json),
+        "initial_breakpoints": _initial_breakpoints(breakpoints),
+    })
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("start")
+def start(
+    adapter: str = typer.Option("debugpy", "--adapter"),
+    adapter_command: Optional[List[str]] = typer.Option(None, "--adapter-command"),
+    config_json: str = typer.Option("{}", "--config-json"),
+    breakpoint: Optional[List[str]] = typer.Option(None, "--breakpoint", help="Set PATH:LINE before launch."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    """Launch a debuggee through a persistent local DAP broker."""
+    _start("launch", adapter, adapter_command, config_json, breakpoint, project_root)
+
+
+@app.command("attach")
+def attach(
+    adapter: str = typer.Option("debugpy", "--adapter"),
+    adapter_command: Optional[List[str]] = typer.Option(None, "--adapter-command"),
+    config_json: str = typer.Option("{}", "--config-json"),
+    breakpoint: Optional[List[str]] = typer.Option(None, "--breakpoint", help="Set PATH:LINE before attach."),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    """Attach to a debuggee through a persistent local DAP broker."""
+    _start("attach", adapter, adapter_command, config_json, breakpoint, project_root)
+
+
+@app.command("break")
+def set_breakpoint(
+    session_id: str = typer.Argument(...),
+    source: Path = typer.Argument(...),
+    lines: List[int] = typer.Argument(...),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    _require_consent(_root(project_root))
+    result = DebugBrokerClient(_root(project_root)).call("breakpoints", {
+        "session_id": session_id, "source": str(source), "lines": lines,
+    })
+    typer.echo(json.dumps(result, indent=2))
+
+
+def _control(action: str, session_id: str, thread_id: int | None, project_root: Path) -> None:
+    _require_consent(_root(project_root))
+    result = DebugBrokerClient(_root(project_root)).call("control", {
+        "session_id": session_id, "debug_action": action, "thread_id": thread_id,
+    })
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("continue")
+def continue_(session_id: str, thread_id: Optional[int] = typer.Option(None, "--thread"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _control("continue", session_id, thread_id, project_root)
+
+
+@app.command("pause")
+def pause(session_id: str, thread_id: Optional[int] = typer.Option(None, "--thread"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _control("pause", session_id, thread_id, project_root)
+
+
+@app.command("step")
+def step(session_id: str, kind: str = typer.Option("next", "--kind", help="next|stepIn|stepOut"), thread_id: int = typer.Option(..., "--thread"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _control(kind, session_id, thread_id, project_root)
+
+
+def _inspect(operation: str, session_id: str, arguments: dict, project_root: Path) -> None:
+    _require_consent(_root(project_root))
+    result = DebugBrokerClient(_root(project_root)).call("inspect", {
+        "session_id": session_id, "operation": operation, "arguments": arguments,
+    })
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("threads")
+def threads(session_id: str, project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _inspect("threads", session_id, {}, project_root)
+
+
+@app.command("stack")
+def stack(session_id: str, thread_id: int = typer.Option(..., "--thread"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _inspect("stackTrace", session_id, {"threadId": thread_id}, project_root)
+
+
+@app.command("scopes")
+def scopes(session_id: str, frame_id: int = typer.Option(..., "--frame"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _inspect("scopes", session_id, {"frameId": frame_id}, project_root)
+
+
+@app.command("variables")
+def variables(session_id: str, reference: int = typer.Option(..., "--reference"), project_root: Path = typer.Option(Path("."), "--project-root")) -> None:
+    _inspect("variables", session_id, {"variablesReference": reference}, project_root)
+
+
+@app.command("evaluate")
+def evaluate(
+    session_id: str,
+    expression: str,
+    frame_id: Optional[int] = typer.Option(None, "--frame"),
+    allow_side_effects: bool = typer.Option(False, "--allow-side-effects"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    if not allow_side_effects:
+        raise typer.BadParameter("evaluate can execute code; pass --allow-side-effects explicitly")
+    _require_consent(_root(project_root))
+    result = DebugBrokerClient(_root(project_root)).call("evaluate", {
+        "session_id": session_id,
+        "expression": expression,
+        "frame_id": frame_id,
+        "allow_side_effects": True,
+    })
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("trace")
+def trace(
+    script: Optional[Path] = typer.Option(None, "--python-script"),
+    node_script: Optional[Path] = typer.Option(None, "--node-script"),
+    args: Optional[List[str]] = typer.Option(None, "--arg"),
+    import_path: Optional[Path] = typer.Option(None, "--import"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    from devcouncil.codeintel.debug.tracing import NodeCpuProfileProvider, PythonTraceProvider, import_runtime_trace
+
+    root = _root(project_root)
+    _require_consent(root)
+    if script is not None:
+        result = PythonTraceProvider(root).run(script, args or [])
+    elif node_script is not None:
+        result = NodeCpuProfileProvider(root).run(node_script, args or [])
+    elif import_path is not None:
+        result = import_runtime_trace(root, import_path)
+    else:
+        raise typer.BadParameter("provide --python-script, --node-script, or --import")
+    typer.echo(json.dumps(result, indent=2))
+
+
+@app.command("stop")
+def stop(
+    session_id: str,
+    keep_debuggee: bool = typer.Option(False, "--keep-debuggee"),
+    project_root: Path = typer.Option(Path("."), "--project-root"),
+) -> None:
+    root = _root(project_root)
+    _require_consent(root)
+    result = DebugBrokerClient(root).call("stop", {
+        "session_id": session_id, "terminate_debuggee": not keep_debuggee,
+    })
+    typer.echo(json.dumps(result, indent=2))

package/src/devcouncil/cli/commands/design.py

@@ -21,9 +21,12 @@ from devcouncil.knowledge.design_conformance import (
     STYLE_EXTENSIONS,
     scan_files,
 )
+from devcouncil.telemetry.stages import log_stage, log_step
+import logging
 
 app = typer.Typer(help="Lint, export, and inspect a design.md design system.")
 console = Console()
+logger = logging.getLogger(__name__)
 
 # Where a project's design system is looked for, in order.
 _DEFAULT_PATHS = (
@@ -73,23 +76,30 @@ def lint(
 ):
     """Validate a design system: broken token refs, contrast, ordering, orphans."""
     root = project_root.expanduser().resolve()
-    target = _resolve_path(path, root)
-    if target is None:
-        console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
-        raise typer.Exit(code=1)
-
-    findings = lint_design(parse_design_md(target))
-    if not findings:
-        console.print(f"[green]✓ {target} passed all design.md lint rules.[/green]")
-        return
-
-    errors = [f for f in findings if f.severity == "error"]
-    color = {"error": "red", "warning": "yellow", "info": "cyan"}
-    console.print(f"[bold]{len(findings)} finding(s) in {target}:[/bold]")
-    for f in findings:
-        console.print(f"  [{color.get(f.severity, 'white')}]{f.format()}[/{color.get(f.severity, 'white')}]")
-    if errors:
-        raise typer.Exit(code=1)
+    from devcouncil.telemetry.logging_setup import set_log_dir
+    set_log_dir(root)
+    logger.info("dev design lint")
+    with log_stage("design", project_root=root, subcommand="lint"):
+        log_step("design/1: linting design system", project_root=root, trace=True)
+        target = _resolve_path(path, root)
+        if target is None:
+            console.print("[red]No design.md found.[/red] Looked for: " + ", ".join(_DEFAULT_PATHS))
+            raise typer.Exit(code=1)
+
+        findings = lint_design(parse_design_md(target))
+        if not findings:
+            console.print(f"[green]✓ {target} passed all design.md lint rules.[/green]")
+            log_step("design/complete", project_root=root, trace=True)
+            return
+
+        errors = [f for f in findings if f.severity == "error"]
+        color = {"error": "red", "warning": "yellow", "info": "cyan"}
+        console.print(f"[bold]{len(findings)} finding(s) in {target}:[/bold]")
+        for f in findings:
+            console.print(f"  [{color.get(f.severity, 'white')}]{f.format()}[/{color.get(f.severity, 'white')}]")
+        log_step("design/complete", project_root=root, trace=True)
+        if errors:
+            raise typer.Exit(code=1)
 
 
 @app.command("export")