dna-cli 0.1.0__py3-none-any.whl

dna_cli/docs_cmd.py

@@ -0,0 +1,79 @@
+"""``dna docs`` — browse the in-product Doc corpus.
+
+Reads from the ``docs`` scope cross-scope (same as
+``manifest_tools.docs.list_docs`` under the hood). The CLI verb
+remains ``dna docs`` because that's the natural UX phrasing — the
+underlying Kind is ``Doc``.
+"""
+from __future__ import annotations
+
+import click
+
+from dna_cli._ctx import fail, get_holder, print_json, print_table
+
+DOCS_SCOPE = "docs"
+DOC_KIND = "Doc"
+
+
+@click.group(name="docs", help="Browse the in-product Doc corpus.")
+def docs_() -> None:
+    """Group root.
+
+    Phase 16 — renamed from ``dna help`` to ``dna docs``. The trailing
+    underscore on the function name avoids clashing with the ``docs``
+    builtin module name in some toolchains.
+    """
+
+
+@docs_.command("list")
+@click.option("--json", "as_json", is_flag=True)
+@click.option("--locale", default="pt-BR", show_default=True)
+def list_docs(as_json: bool, locale: str) -> None:
+    """List all docs (sidebar metadata)."""
+    holder = get_holder()
+    try:
+        mi = holder.kernel.instance(DOCS_SCOPE)
+    except Exception as e:
+        raise fail(f"docs scope unreachable: {e}")
+    _ = mi  # kept for future mi-based ops; current path uses kernel directly
+    rows = []
+    for d in holder.kernel.query_list_sync(DOCS_SCOPE, DOC_KIND):
+        loc = d.spec.get("locale") or "pt-BR"
+        if loc != locale:
+            continue
+        rows.append(
+            {
+                "name": d.name,
+                "icon": d.spec.get("icon", ""),
+                "title": d.metadata.get("description") or d.name,
+                "order": d.spec.get("order", 999),
+                "kind_of": d.spec.get("kind_of") or "",
+                "category": d.spec.get("category") or "",
+            }
+        )
+    rows.sort(key=lambda r: r["order"])
+    if as_json:
+        print_json(rows)
+    else:
+        print_table(rows, ["order", "icon", "name", "title", "kind_of", "category"])
+
+
+@docs_.command("show")
+@click.argument("doc_name")
+@click.option("--locale", default="pt-BR")
+def show(doc_name: str, locale: str) -> None:
+    """Print the full markdown body of a doc."""
+    holder = get_holder()
+    _mi = holder.kernel.instance(DOCS_SCOPE)
+    candidates = [
+        d for d in holder.kernel.query_list_sync(DOCS_SCOPE, DOC_KIND)
+        if d.name == doc_name
+    ]
+    if not candidates:
+        raise fail(f"Doc '{doc_name}' not found.")
+    chosen = next(
+        (c for c in candidates if (c.spec.get("locale") or "pt-BR") == locale),
+        candidates[0],
+    )
+    body = chosen.spec.get("body") or ""
+    click.echo(body)

dna_cli/eval_cmd.py

@@ -0,0 +1,274 @@
+"""``dna eval`` — run EvalSuites locally, offline, deterministically.
+
+The runner is the SDK's pure library (``dna.extensions.eval.runner``):
+the default target is the KERNEL ITSELF — a case with
+``target: {type: prompt, agent: X}`` composes ``build_prompt(agent=X)``
+and applies the case's checks (contains/regex/equals/length) to the
+composed prompt. "Does my agent compose what I expect?" is a real
+evaluation of declarative config, with zero LLM and zero network.
+LLM/live targets are host-registered ``EvalTargetPort``s (see
+docs/guides/evaluating-agents.md) — this CLI ships only the
+deterministic built-in.
+
+Commands:
+    dna eval run <suite> [--scope] [--save] [--baseline <name>] [--json]
+    dna eval list [--scope]                — suites + saved runs
+    dna eval show <run> [--scope]          — one run, per-case detail
+    dna eval pin <run> [--name] [--label]  — pin a run as the baseline
+
+Exit codes (CI-friendly):
+    ``run``                 → 1 when any case failed/errored
+    ``run --baseline <b>``  → 1 when the run REGRESSES vs the baseline
+                              (pre-existing failures don't re-fail CI)
+
+Kernel-bound: boots a local kernel against ``DNA_SOURCE_URL`` /
+``DNA_BASE_DIR`` (filesystem source, default ``./.dna``). No service.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import click
+
+from dna_cli._ctx import dna_session, fail, print_json, print_table
+
+EVAL_API_VERSION = "github.com/ruinosus/dna/eval/v1"
+
+_STATUS_GLYPH = {"passed": "✓", "failed": "✗", "error": "!", "skipped": "-"}
+
+
+def _spec_of(doc: Any) -> dict:
+    spec = getattr(doc, "spec", None)
+    if not isinstance(spec, dict):
+        spec = dict(spec) if spec else {}
+    return spec
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@click.group(name="eval")
+def eval_() -> None:
+    """Run EvalSuites locally (offline, deterministic) and compare runs
+    against a pinned EvalBaseline."""
+
+
+# ── run ─────────────────────────────────────────────────────────────────────
+
+
+def _print_run(spec: dict) -> None:
+    for r in spec.get("results") or []:
+        glyph = _STATUS_GLYPH.get(str(r.get("status")), "?")
+        line = f"  {glyph} {r.get('case')}  [{r.get('status')}]"
+        click.echo(line)
+        if r.get("status") == "failed":
+            for c in r.get("checks") or []:
+                if not c.get("passed"):
+                    click.echo(f"      · {c.get('type')}: {c.get('detail', '')}")
+        elif r.get("status") == "error":
+            click.echo(f"      · {r.get('error', '')}")
+    click.echo(
+        f"{spec.get('passed', 0)} passed · {spec.get('failed', 0)} failed · "
+        f"{spec.get('errored', 0)} errored · {spec.get('skipped', 0)} skipped "
+        f"(total {spec.get('total', 0)})"
+    )
+
+
+@eval_.command("run")
+@click.argument("suite")
+@click.option("--scope", default=None, help="Scope to run in (default: resolved from the source).")
+@click.option("--save", is_flag=True, help="Persist the result as an EvalRun document.")
+@click.option("--baseline", default=None, metavar="NAME",
+              help="Compare against the EvalBaseline document NAME; exit 1 on regressions.")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def cmd_run(suite: str, scope: str | None, save: bool, baseline: str | None, as_json: bool):
+    """Execute SUITE offline and report per-case results.
+
+    Without ``--baseline`` the exit code reflects the run itself (1 when
+    any case failed/errored). With ``--baseline`` it reflects the DIFF:
+    only a regression (a case the baseline passed, now failing) exits 1.
+    """
+    from dna.extensions.eval import compare, run_suite
+
+    with dna_session(scope) as s:
+        try:
+            raw = run_suite(s.kernel, s.scope, suite)
+        except ValueError as exc:
+            raise fail(str(exc))
+        spec = raw["spec"]
+        run_name = raw["metadata"]["name"]
+
+        diff = None
+        baseline_run = None
+        if baseline:
+            base_doc = s.get_doc("EvalBaseline", baseline)
+            if base_doc is None:
+                raise fail(
+                    f"EvalBaseline '{baseline}' not found in scope '{s.scope}' "
+                    f"— pin one with `dna eval pin <run>`."
+                )
+            baseline_run = str(_spec_of(base_doc).get("run_name") or "")
+            base_run_doc = s.get_doc("EvalRun", baseline_run)
+            if base_run_doc is None:
+                raise fail(
+                    f"EvalBaseline '{baseline}' points at EvalRun "
+                    f"'{baseline_run}', which does not exist."
+                )
+            diff = compare(spec, _spec_of(base_run_doc))
+
+        if save:
+            s.run(s.kernel.write_document(s.scope, "EvalRun", run_name, raw))
+
+        if as_json:
+            payload: dict[str, Any] = {"run": raw, "saved": save}
+            if diff is not None:
+                payload["baseline"] = {"name": baseline, "run_name": baseline_run}
+                payload["compare"] = diff
+            print_json(payload)
+        else:
+            click.echo(f"suite: {suite} (scope {s.scope})")
+            _print_run(spec)
+            if save:
+                click.echo(f"saved: EvalRun/{run_name}")
+            if diff is not None:
+                click.echo(
+                    f"vs baseline {baseline} ({baseline_run}): "
+                    f"{len(diff['regressions'])} regression(s) · "
+                    f"{len(diff['improvements'])} improvement(s) · "
+                    f"{len(diff['unchanged'])} unchanged"
+                )
+                for case in diff["regressions"]:
+                    click.echo(f"  ✗ REGRESSION: {case}")
+                for case in diff["improvements"]:
+                    click.echo(f"  ✓ improved: {case}")
+
+    if diff is not None:
+        if diff["has_regressions"]:
+            raise SystemExit(1)
+    elif int(spec.get("failed", 0)) + int(spec.get("errored", 0)) > 0:
+        raise SystemExit(1)
+
+
+# ── list ────────────────────────────────────────────────────────────────────
+
+
+@eval_.command("list")
+@click.option("--scope", default=None, help="Scope to list (default: resolved from the source).")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def cmd_list(scope: str | None, as_json: bool):
+    """List EvalSuites, saved EvalRuns and pinned EvalBaselines."""
+    with dna_session(scope) as s:
+        suites = s.query_list("EvalSuite")
+        runs = s.query_list("EvalRun")
+        baselines = s.query_list("EvalBaseline")
+
+        if as_json:
+            print_json({
+                "scope": s.scope,
+                "suites": [
+                    {"name": d.name, **{k: _spec_of(d).get(k) for k in ("description",)},
+                     "cases": len(_spec_of(d).get("cases") or [])}
+                    for d in suites
+                ],
+                "runs": [
+                    {"name": d.name, "suite": _spec_of(d).get("suite"),
+                     "passed": _spec_of(d).get("passed"), "failed": _spec_of(d).get("failed"),
+                     "total": _spec_of(d).get("total"),
+                     "finished_at": _spec_of(d).get("finished_at")}
+                    for d in runs
+                ],
+                "baselines": [
+                    {"name": d.name, "suite": _spec_of(d).get("suite"),
+                     "run_name": _spec_of(d).get("run_name")}
+                    for d in baselines
+                ],
+            })
+            return
+
+        click.echo(f"scope: {s.scope}")
+        click.echo("\nsuites:")
+        print_table(
+            [{"name": d.name, "cases": len(_spec_of(d).get("cases") or []) or "all",
+              "description": (_spec_of(d).get("description") or "")[:60]}
+             for d in suites],
+            ["name", "cases", "description"],
+        )
+        click.echo("\nruns:")
+        print_table(
+            [{"name": d.name, "suite": _spec_of(d).get("suite", ""),
+              "result": f"{_spec_of(d).get('passed', 0)}/{_spec_of(d).get('total', 0)} passed",
+              "finished_at": _spec_of(d).get("finished_at", "")}
+             for d in runs],
+            ["name", "suite", "result", "finished_at"],
+        )
+        click.echo("\nbaselines:")
+        print_table(
+            [{"name": d.name, "suite": _spec_of(d).get("suite", ""),
+              "run_name": _spec_of(d).get("run_name", "")}
+             for d in baselines],
+            ["name", "suite", "run_name"],
+        )
+
+
+# ── show ────────────────────────────────────────────────────────────────────
+
+
+@eval_.command("show")
+@click.argument("run_name")
+@click.option("--scope", default=None, help="Scope to read (default: resolved from the source).")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def cmd_show(run_name: str, scope: str | None, as_json: bool):
+    """Show one saved EvalRun with per-case detail."""
+    with dna_session(scope) as s:
+        doc = s.get_doc("EvalRun", run_name)
+        if doc is None:
+            raise fail(f"EvalRun '{run_name}' not found in scope '{s.scope}'.")
+        spec = _spec_of(doc)
+        if as_json:
+            print_json({"name": run_name, "spec": spec})
+            return
+        click.echo(f"EvalRun/{run_name}  (suite {spec.get('suite')}, scope {s.scope})")
+        click.echo(f"started {spec.get('started_at')} · finished {spec.get('finished_at')}")
+        _print_run(spec)
+
+
+# ── pin ─────────────────────────────────────────────────────────────────────
+
+
+@eval_.command("pin")
+@click.argument("run_name")
+@click.option("--scope", default=None, help="Scope to write in (default: resolved from the source).")
+@click.option("--name", "baseline_name", default=None,
+              help="Baseline document name (default: baseline-<suite>).")
+@click.option("--label", default=None, help="Why this run is the reference.")
+def cmd_pin(run_name: str, scope: str | None, baseline_name: str | None, label: str | None):
+    """Pin RUN_NAME as the EvalBaseline for its suite.
+
+    Future ``dna eval run <suite> --baseline <name>`` executions are
+    compared against the pinned run (regressions exit non-zero)."""
+    with dna_session(scope) as s:
+        run_doc = s.get_doc("EvalRun", run_name)
+        if run_doc is None:
+            raise fail(
+                f"EvalRun '{run_name}' not found in scope '{s.scope}' "
+                f"— run with --save first."
+            )
+        suite = str(_spec_of(run_doc).get("suite") or "")
+        name = baseline_name or f"baseline-{suite}"
+        spec: dict[str, Any] = {
+            "suite": suite,
+            "run_name": run_name,
+            "pinned_at": _now(),
+        }
+        if label:
+            spec["label"] = label
+        raw = {
+            "apiVersion": EVAL_API_VERSION,
+            "kind": "EvalBaseline",
+            "metadata": {"name": name},
+            "spec": spec,
+        }
+        s.run(s.kernel.write_document(s.scope, "EvalBaseline", name, raw))
+        click.echo(f"pinned: EvalBaseline/{name} → EvalRun/{run_name} (suite {suite})")

dna_cli/hooks_cmd.py

@@ -0,0 +1,146 @@
+"""``dna sdlc hooks`` — install/uninstall/status of the git↔SDLC hook.
+
+One command wires the symbiosis into a clone::
+
+    dna sdlc hooks install     # git config core.hooksPath scripts/git-hooks
+    dna sdlc hooks status      # what's wired + active story + coauthor
+    dna sdlc hooks uninstall   # git config --unset core.hooksPath
+
+``install`` points ``core.hooksPath`` at the repo-versioned hooks dir
+(``scripts/git-hooks/``). NOTE: that directory becomes the clone's ONLY
+hooks dir — git stops looking at ``.git/hooks`` entirely. If you keep
+personal hooks there, move them into ``scripts/git-hooks/`` (they are
+runnable from a versioned dir like any other) or skip the installer and
+wire the ``prepare-commit-msg`` script by hand.
+
+When ``scripts/git-hooks/prepare-commit-msg`` doesn't exist yet (e.g. a
+project other than the DNA repo adopting the convention), ``install``
+materializes it from the copy packaged inside dna-cli.
+
+Registered onto the ``sdlc`` group at import time (same pattern as
+``testkit_cmd``) — see ``dna_cli/__init__.py``.
+"""
+from __future__ import annotations
+
+import stat
+from pathlib import Path
+
+import click
+
+from dna_cli import _git_symbiosis as gs
+from dna_cli._active_story import read_active_story
+from dna_cli._ctx import fail
+from dna_cli.sdlc_cmd import sdlc
+
+
+def _hooks_path_config(root: Path) -> str | None:
+    out = gs._run_git(["config", "--get", "core.hooksPath"], cwd=root)
+    if out is None:
+        return None
+    return out.strip() or None
+
+
+def _require_repo_root() -> Path:
+    root = gs.repo_root()
+    if root is None:
+        raise fail("not inside a git repository (git rev-parse --show-toplevel failed)")
+    return root
+
+
+def _ensure_hook_file(root: Path) -> tuple[Path, bool]:
+    """Make sure ``scripts/git-hooks/prepare-commit-msg`` exists + is
+    executable. Returns ``(path, created)``."""
+    hook = root / gs.HOOKS_DIR / gs.HOOK_NAME
+    created = False
+    if not hook.exists():
+        src = gs.hook_source_path()
+        hook.parent.mkdir(parents=True, exist_ok=True)
+        hook.write_bytes(src.read_bytes())
+        created = True
+    mode = hook.stat().st_mode
+    if not mode & stat.S_IXUSR:
+        hook.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return hook, created
+
+
+@sdlc.group("hooks")
+def hooks_group() -> None:
+    """Git hooks that close the git↔SDLC loop (Work-Item trailers)."""
+
+
+@hooks_group.command("install")
+def cmd_hooks_install() -> None:
+    """Wire the repo's versioned hooks dir into this clone.
+
+    Sets ``git config core.hooksPath scripts/git-hooks`` — from then on
+    every ``git commit`` runs the versioned ``prepare-commit-msg``, which
+    stamps ``Work-Item:`` + the dna-sdlc[bot] provenance trailer whenever
+    a Story is active (``dna sdlc story start``).
+    """
+    root = _require_repo_root()
+    hook, created = _ensure_hook_file(root)
+    current = _hooks_path_config(root)
+    if current not in (None, gs.HOOKS_DIR):
+        raise fail(
+            f"core.hooksPath is already set to '{current}' — refusing to overwrite. "
+            f"Unset it first (git config --unset core.hooksPath) or merge your hooks "
+            f"into {gs.HOOKS_DIR}/."
+        )
+    if gs._run_git(["config", "core.hooksPath", gs.HOOKS_DIR], cwd=root) is None:
+        raise fail("git config core.hooksPath failed")
+    if created:
+        click.secho(f"  created {gs.HOOKS_DIR}/{gs.HOOK_NAME} (from dna-cli packaged copy)", fg="cyan")
+    click.secho(f"INSTALLED — core.hooksPath = {gs.HOOKS_DIR}", fg="green")
+    click.echo(
+        f"  note: {gs.HOOKS_DIR}/ is now this clone's ONLY hooks dir "
+        f"(.git/hooks is no longer consulted)."
+    )
+    click.echo(
+        "  commits made with an active story (dna sdlc story start) now get "
+        f"'{gs.WORK_ITEM_TRAILER}:' + '{gs.COAUTHOR_TRAILER}: {gs.sdlc_coauthor()}'."
+    )
+
+
+@hooks_group.command("uninstall")
+def cmd_hooks_uninstall() -> None:
+    """Remove the ``core.hooksPath`` wiring (git falls back to .git/hooks)."""
+    root = _require_repo_root()
+    current = _hooks_path_config(root)
+    if current is None:
+        click.secho("core.hooksPath not set — nothing to uninstall", fg="yellow")
+        return
+    if current != gs.HOOKS_DIR:
+        raise fail(
+            f"core.hooksPath points at '{current}' (not '{gs.HOOKS_DIR}') — "
+            f"not ours to remove; unset it manually if intended."
+        )
+    if gs._run_git(["config", "--unset", "core.hooksPath"], cwd=root) is None:
+        raise fail("git config --unset core.hooksPath failed")
+    click.secho("UNINSTALLED — core.hooksPath unset (git uses .git/hooks again)", fg="green")
+
+
+@hooks_group.command("status")
+def cmd_hooks_status() -> None:
+    """Show the symbiosis wiring: hooksPath, hook file, active story, coauthor."""
+    root = _require_repo_root()
+    current = _hooks_path_config(root)
+    hook = root / gs.HOOKS_DIR / gs.HOOK_NAME
+    installed = current == gs.HOOKS_DIR
+    click.secho("git↔SDLC symbiosis", fg="cyan", bold=True)
+    click.echo(f"  repo:            {root}")
+    click.echo(f"  core.hooksPath:  {current or '(not set)'}"
+               + ("" if installed else f"  → run `dna sdlc hooks install`"))
+    if hook.exists():
+        exec_ok = bool(hook.stat().st_mode & stat.S_IXUSR)
+        click.echo(f"  hook file:       {gs.HOOKS_DIR}/{gs.HOOK_NAME}"
+                   + ("" if exec_ok else "  (NOT executable!)"))
+    else:
+        click.echo(f"  hook file:       MISSING ({gs.HOOKS_DIR}/{gs.HOOK_NAME})")
+    active = read_active_story(start=root)
+    if active:
+        click.echo(f"  active story:    {active[0]}:{active[1]}  → commits get "
+                   f"'{gs.WORK_ITEM_TRAILER}: Story/{active[1]}'")
+    else:
+        click.echo("  active story:    (none — commits are not stamped)")
+    click.echo(f"  coauthor:        {gs.sdlc_coauthor()}"
+               + (f"  (via ${gs.COAUTHOR_ENV})" if gs.sdlc_coauthor() != gs.DEFAULT_SDLC_COAUTHOR else ""))