devcouncil 0.1.1 → 0.3.0

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

@@ -0,0 +1,106 @@
+"""`dev logs` — find and read DevCouncil's runtime logs.
+
+Comprehensive logging only helps if the logs are easy to reach when something
+breaks. This command surfaces the always-on shared log
+(``.devcouncil/logs/devcouncil.log``) and the per-run logs
+(``.devcouncil/runs/<run_id>/run.log``) without the user needing to remember
+paths or hand-roll ``tail``/``grep``.
+"""
+
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from devcouncil.telemetry.logging_setup import LOG_RELATIVE_PATH
+
+app = typer.Typer(help="View DevCouncil runtime logs (shared and per-run).")
+console = Console()
+
+
+def _shared_log(root: Path) -> Path:
+    return root / LOG_RELATIVE_PATH
+
+
+def _runs_dir(root: Path) -> Path:
+    return root / ".devcouncil" / "runs"
+
+
+def _print_tail(path: Path, limit: int, grep: Optional[str]) -> None:
+    if not path.exists():
+        console.print(f"[yellow]No log at {path}. Run a command first (or pass --project-root).[/yellow]")
+        raise typer.Exit(code=0)
+    # Read only the tail rather than the whole (potentially large, rotated) file.
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    if grep:
+        lines = [line for line in lines if grep.lower() in line.lower()]
+    for line in lines[-limit:]:
+        console.print(line, markup=False, highlight=False)
+
+
+@app.command("tail")
+def tail(
+    limit: int = typer.Option(50, "--limit", "-n", help="Number of trailing lines to show."),
+    follow: bool = typer.Option(False, "--follow", "-f", help="Keep printing new lines as they are written."),
+    grep: Optional[str] = typer.Option(None, "--grep", "-g", help="Only show lines containing this substring (case-insensitive)."),
+    run: Optional[str] = typer.Option(None, "--run", help="Show a specific run's log (.devcouncil/runs/<run>/run.log) instead of the shared log."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Print the tail of the shared log (or a per-run log with --run)."""
+    root = project_root.expanduser().resolve()
+    path = (_runs_dir(root) / run / "run.log") if run else _shared_log(root)
+
+    _print_tail(path, limit, grep)
+    if not follow:
+        return
+
+    # Follow mode: poll for appended bytes (the file is append-only between rotations).
+    console.print(f"[dim]— following {path} (Ctrl-C to stop) —[/dim]")
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            handle.seek(0, 2)  # jump to EOF; we already printed the tail
+            while True:
+                line = handle.readline()
+                if line:
+                    rendered = line.rstrip("\n")
+                    if not grep or grep.lower() in rendered.lower():
+                        console.print(rendered, markup=False, highlight=False)
+                else:
+                    time.sleep(0.4)
+    except KeyboardInterrupt:  # pragma: no cover - interactive
+        pass
+
+
+@app.command("path")
+def path(
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Print the shared log file path (and whether it exists)."""
+    root = project_root.expanduser().resolve()
+    log = _shared_log(root)
+    marker = "" if log.exists() else " [yellow](not created yet)[/yellow]"
+    console.print(f"{log}{marker}")
+
+
+@app.command("runs")
+def runs(
+    limit: int = typer.Option(20, "--limit", "-n", help="Maximum number of recent run logs to list."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """List per-run logs, newest first, with their paths."""
+    root = project_root.expanduser().resolve()
+    runs_dir = _runs_dir(root)
+    if not runs_dir.exists():
+        console.print("[yellow]No runs yet.[/yellow]")
+        return
+    run_logs = [d / "run.log" for d in runs_dir.iterdir() if (d / "run.log").exists()]
+    if not run_logs:
+        console.print("[yellow]No per-run logs yet (run.log appears once an executor runs).[/yellow]")
+        return
+    run_logs.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+    for log in run_logs[:limit]:
+        size_kb = log.stat().st_size / 1024
+        console.print(f"[bold]{log.parent.name}[/bold]  [dim]{log}  ({size_kb:.1f} KB)[/dim]")
+    console.print("\n[dim]View one with:[/dim] dev logs tail --run <run-id>")

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

@@ -5,13 +5,85 @@ import typer
 from rich.console import Console
 
 from devcouncil.cli.commands.init import initialize_project
-from devcouncil.indexing.repo_mapper import RepoMapper
+from devcouncil.indexing.repo_mapper import RepoMap, RepoMapper
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.storage.db import get_db
 
 console = Console()
 status_console = Console(stderr=True)
 
+AGENT_GUIDE_MARKER = "<!-- Managed by dev map: keep this file in sync with .devcouncil/repo_map.json. -->"
+
+
+def _important_surfaces(repo_map: RepoMap) -> list[str]:
+    """Derive the 'important surfaces' list from the computed map, so the guide points
+    at THIS repo's real subsystems instead of hardcoded DevCouncil paths."""
+    lines: list[str] = []
+    for index, subsystem in enumerate(repo_map.subsystems[:6], start=1):
+        lines.append(f"{index}. `{subsystem.area}/` — {subsystem.summary}")
+    if not lines:
+        for index, path in enumerate(repo_map.important_files[:6], start=1):
+            lines.append(f"{index}. `{path}`")
+    return lines or ["1. See `.devcouncil/repo_map.json` for the file index."]
+
+
+def _agent_guide_text(repo_map_path: Path, repo_root: Path, repo_map: RepoMap) -> str:
+    return "\n".join(
+        [
+            AGENT_GUIDE_MARKER,
+            "",
+            "# Agent Workspace Guide",
+            "",
+            "Use `.devcouncil/repo_map.json` as the primary file index for this workspace.",
+            f"Repo map: `{repo_map_path.relative_to(repo_root).as_posix() if repo_map_path.is_relative_to(repo_root) else repo_map_path}`",
+            "",
+            "Workflow for agents:",
+            "1. Open `.devcouncil/repo_map.json` before guessing at file locations.",
+            "2. Use the `files` list to resolve module ownership and nearby siblings.",
+            "3. Use `subsystems` for subsystem-level navigation.",
+            "4. In `subsystems`, use `entry_points` + `critical_files` for entry points and starting context.",
+            "5. Use `role_files` in `subsystems` for subsystem role buckets (entry, runtime, policy, adapters, etc.).",
+            "6. Use `neighbors` and `handoff_paths` in `subsystems` to follow cross-subsystem flow.",
+            "7. Run `dev map` again after large refactors to refresh the map.",
+            "",
+            "Important surfaces:",
+            *_important_surfaces(repo_map),
+            "",
+            "If the map and source disagree, trust the source and regenerate the map.",
+        ]
+    )
+
+
+def _write_agent_guides(repo_root: Path, repo_map_path: Path, repo_map: RepoMap) -> None:
+    for filename in ("AGENTS.md", "CLAUDE.md"):
+        path = repo_root / filename
+        if path.exists():
+            existing = path.read_text(encoding="utf-8")
+            if AGENT_GUIDE_MARKER not in existing:
+                continue
+        path.write_text(_agent_guide_text(repo_map_path, repo_root, repo_map) + "\n", encoding="utf-8")
+
+
+def generate_map_artifacts(root: Path, output: Path, goal: str = "", *, scan_dependencies: bool = False) -> RepoMap:
+    """Build the repo map and write repo_map.json + agent guides (no LLM, no re-init).
+
+    Assumes ``.devcouncil/`` already exists. Shared by the ``dev map`` command and
+    by project initialization so a freshly set-up repo is immediately navigable.
+    ``scan_dependencies`` is opt-in (off for init and default mapping) because it can
+    shell out to dependency auditors.
+    """
+    repo_map = RepoMapper(root).map_repo(goal, scan_dependencies=scan_dependencies)
+    graph_context = CodeReviewGraphAdapter(root).get_context()
+    output = output if output.is_absolute() else root / output
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(repo_map.model_dump_json(indent=2), encoding="utf-8")
+    _write_agent_guides(root, output, repo_map)
+    if graph_context.available:
+        graph_output = output.with_name("code_review_graph_context.json")
+        graph_output.write_text(graph_context.model_dump_json(indent=2), encoding="utf-8")
+        status_console.print(f"[green]Wrote code-review-graph context to {graph_output}[/green]")
+    return repo_map
+
 
 def map_repo(
     goal: str = typer.Argument("", help="Goal text used for candidate-file ranking."),
@@ -22,21 +94,19 @@ def map_repo(
         help="Path to write repo_map.json.",
     ),
     project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    scan_deps: bool = typer.Option(
+        False,
+        "--scan-deps",
+        help="Run available dependency auditors (pip-audit/npm audit/osv-scanner) and record dependency_risks in the map. Off by default.",
+    ),
 ):
     """Build the deterministic repository map without calling an LLM."""
     root = project_root.expanduser().resolve()
-    initialize_project(root, quiet=True)
+    initialize_project(root, quiet=True, with_map=False)
     if not get_db(root):
         raise typer.Exit(code=1)
 
-    repo_map = RepoMapper(root).map_repo(goal)
-    graph_context = CodeReviewGraphAdapter(root).get_context()
     output = output if output.is_absolute() else root / output
-    output.parent.mkdir(parents=True, exist_ok=True)
-    output.write_text(repo_map.model_dump_json(indent=2), encoding="utf-8")
-    if graph_context.available:
-        graph_output = output.with_name("code_review_graph_context.json")
-        graph_output.write_text(graph_context.model_dump_json(indent=2), encoding="utf-8")
-        status_console.print(f"[green]Wrote code-review-graph context to {graph_output}[/green]")
+    repo_map = generate_map_artifacts(root, output, goal, scan_dependencies=scan_deps)
     typer.echo(json.dumps(repo_map.model_dump(), indent=2))
     status_console.print(f"[green]Wrote repository map to {output}[/green]")

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

@@ -0,0 +1,245 @@
+"""`dev okf` — export, ingest, and validate Open Knowledge Format bundles.
+
+* ``dev okf export`` renders DevCouncil's artifact graph as a portable OKF bundle.
+* ``dev okf ingest`` imports an external OKF bundle as planning/coding context under
+  ``.devcouncil/knowledge/okf/`` (selected into prompts like a domain skill).
+* ``dev okf validate`` checks a bundle for the OKF invariants (typed docs, resolved links).
+"""
+
+from __future__ import annotations
+
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from devcouncil.cli.commands.init import initialize_project
+from devcouncil.knowledge.okf import read_bundle, validate_bundle
+from devcouncil.storage.db import get_db
+from devcouncil.storage.repositories import ArtifactGraphRepository
+
+app = typer.Typer(help="Export, ingest, and validate Open Knowledge Format bundles.")
+console = Console()
+
+
+def _knowledge_okf_dir(root: Path) -> Path:
+    from devcouncil.app.config import load_config
+
+    directory = ".devcouncil/knowledge"
+    try:
+        directory = load_config(root).knowledge.directory
+    except Exception:
+        pass
+    return root / directory / "okf"
+
+
+def _knowledge_design_md(root: Path) -> Path | None:
+    """Locate the project's design.md under the configured knowledge dir's design/ subdir.
+
+    Honors the same config dir resolution as :func:`_knowledge_okf_dir`, falling back to the
+    default ``.devcouncil/knowledge/design/design.md``. Returns ``None`` if no design.md exists.
+    """
+    from devcouncil.app.config import load_config
+
+    directory = ".devcouncil/knowledge"
+    try:
+        directory = load_config(root).knowledge.directory
+    except Exception:
+        pass
+    candidates = [
+        root / directory / "design" / "design.md",
+        root / ".devcouncil" / "knowledge" / "design" / "design.md",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+@app.command("export")
+def export(
+    output: Path = typer.Option(Path("okf_bundle"), "--output", "-o", help="Directory to write the OKF bundle into."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+    skills: bool = typer.Option(
+        True,
+        "--skills/--no-skills",
+        help="Include the engineering skills library as OKF documents in the bundle.",
+    ),
+    design: bool = typer.Option(
+        True,
+        "--design/--no-design",
+        help="Include the project's design.md (if present) as an OKF document in the bundle.",
+    ),
+):
+    """Export the DevCouncil artifact graph as an OKF bundle."""
+    root = project_root.expanduser().resolve()
+    initialize_project(root, quiet=True)
+    db = get_db(root)
+    if not db:
+        console.print("[red]DevCouncil state is unavailable in this directory.[/red]")
+        raise typer.Exit(code=1)
+
+    out_dir = output.expanduser().resolve()
+    with db.get_session() as session:
+        graph = ArtifactGraphRepository(session).load_graph()
+
+    project_name = root.name or "DevCouncil Project"
+    try:
+        from devcouncil.app.config import load_config
+
+        project_name = load_config(root).project.name or project_name
+    except Exception:
+        pass
+
+    # Load the FULL skill set (packaged library + this repo's own skills) so the export is
+    # complete; goal-driven selection would only emit the few skills that match a goal.
+    skill_list: list = []
+    if skills:
+        from devcouncil.skills.registry import load_skills
+
+        skill_list = load_skills(project_root=root)
+
+    # Look for the project's design.md under the configured knowledge dir; silently skip if
+    # absent so export stays useful for projects without a design system.
+    design_obj = None
+    if design:
+        design_md = _knowledge_design_md(root)
+        if design_md is not None:
+            from devcouncil.knowledge.design import parse_design_md
+
+            try:
+                design_obj = parse_design_md(design_md)
+            except Exception:
+                design_obj = None
+
+    timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    from devcouncil.reporting.okf_bundle_writer import OKFBundleWriter
+
+    written = OKFBundleWriter.generate(
+        graph,
+        out_dir,
+        project_name=project_name,
+        timestamp=timestamp,
+        include_skills=bool(skill_list),
+        skills=skill_list,
+        include_design=design_obj is not None,
+        design=design_obj,
+    )
+    console.print(
+        f"[green]Exported {len(written)} OKF documents to[/green] {out_dir} "
+        f"([cyan]{out_dir / 'index.md'}[/cyan])."
+    )
+    if skill_list:
+        console.print(f"[green]Included {len(skill_list)} engineering skill document(s).[/green]")
+    if design_obj is not None:
+        console.print("[green]Included 1 design system document(s).[/green]")
+
+
+@app.command("ingest")
+def ingest(
+    bundle: str = typer.Argument(
+        ...,
+        help="OKF bundle source: a local directory, a .tar.gz/.tgz/.zip archive, or a git URL.",
+    ),
+    name: str = typer.Option("", "--name", help="Subfolder name under knowledge/okf (defaults to the bundle name)."),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Repository root containing .devcouncil/."),
+):
+    """Ingest an external OKF bundle as durable planning/coding context.
+
+    The bundle may be a local directory, a local archive (``.tar.gz``/``.tgz``/``.zip``,
+    extracted behind a path-traversal guard), or a git URL (shallow-cloned). After the
+    source is materialized to a local directory, the existing read/validate/copy logic runs
+    unchanged; any temp directory is removed afterwards.
+    """
+    root = project_root.expanduser().resolve()
+
+    from devcouncil.knowledge.fetch import fetch_bundle
+
+    try:
+        fetched = fetch_bundle(bundle)
+    except Exception as exc:
+        console.print(f"[red]Could not fetch bundle[/red] {bundle!r}: {exc}")
+        raise typer.Exit(code=1)
+
+    try:
+        src = fetched.directory
+        if not src.is_dir():
+            console.print(f"[red]Not a directory:[/red] {src}")
+            raise typer.Exit(code=1)
+
+        initialize_project(root, quiet=True)
+        parsed = read_bundle(src)
+        if not parsed.documents:
+            console.print(f"[yellow]No OKF documents (*.md) found in[/yellow] {bundle}")
+            raise typer.Exit(code=1)
+
+        problems = validate_bundle(parsed)
+        if problems:
+            console.print(f"[yellow]Ingesting a bundle with {len(problems)} validation issue(s):[/yellow]")
+            for p in problems[:10]:
+                console.print(f"  - {p}")
+
+        dest = _knowledge_okf_dir(root) / (name or fetched.suggested_name or "bundle")
+        dest.mkdir(parents=True, exist_ok=True)
+        count = 0
+        for md in src.rglob("*.md"):
+            rel = md.relative_to(src)
+            target = dest / rel
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(md, target)
+            count += 1
+        console.print(
+            f"[green]Ingested {count} OKF document(s) into[/green] {dest}. "
+            "They are now available as planning/coding context."
+        )
+    finally:
+        fetched.cleanup()
+
+
+@app.command("validate")
+def validate(
+    bundle: Path = typer.Argument(..., help="Path to an OKF bundle directory to validate."),
+):
+    """Validate an OKF bundle (every doc typed; every intra-bundle link resolves)."""
+    src = bundle.expanduser().resolve()
+    if not src.is_dir():
+        console.print(f"[red]Not a directory:[/red] {src}")
+        raise typer.Exit(code=1)
+
+    parsed = read_bundle(src)
+    problems = validate_bundle(parsed)
+    if not problems:
+        console.print(f"[green]✓ Valid OKF bundle[/green] — {len(parsed.documents)} document(s), all links resolve.")
+        return
+    console.print(f"[red]✗ {len(problems)} problem(s) in[/red] {src}:")
+    for p in problems:
+        console.print(f"  - {p}")
+    raise typer.Exit(code=1)
+
+
+@app.command("html")
+def html(
+    bundle: Path = typer.Argument(..., help="Path to an OKF bundle directory to render."),
+    output: Path = typer.Option(Path("okf_site"), "--output", "-o", help="Directory to write the static HTML site into."),
+):
+    """Render an OKF bundle as a browsable, self-contained static HTML site."""
+    src = bundle.expanduser().resolve()
+    if not src.is_dir():
+        console.print(f"[red]Not a directory:[/red] {src}")
+        raise typer.Exit(code=1)
+
+    parsed = read_bundle(src)
+    if not parsed.documents:
+        console.print(f"[yellow]No OKF documents (*.md) found in[/yellow] {src}")
+        raise typer.Exit(code=1)
+
+    from devcouncil.reporting.okf_html import write_bundle_html
+
+    out_dir = output.expanduser().resolve()
+    written = write_bundle_html(parsed, out_dir)
+    console.print(
+        f"[green]Rendered {len(written)} page(s) to[/green] {out_dir} "
+        f"([cyan]{out_dir / 'index.html'}[/cyan])."
+    )