dna-cli 0.1.0__py3-none-any.whl

dna_cli/__init__.py

@@ -0,0 +1,87 @@
+"""``dna`` — user-facing CLI for the DNA kernel.
+
+Boots a local Kernel against ``DNA_SOURCE_URL`` / ``DNA_BASE_DIR``
+(filesystem source) and runs one command per invocation. No service
+required — the kernel IS the backend.
+
+Output formatting:
+  - ``--json`` for machine-readable (default for CRUD writes).
+  - rich tables for ``list`` / ``show`` (default).
+"""
+from __future__ import annotations
+
+import os
+
+
+import click
+
+from dna_cli import (
+    doc_cmd,
+    docs_cmd,
+    eval_cmd,
+    install_cmd,
+    kind_cmd,
+    memory_cmd,
+    recall_cmd,
+    research_cmd,
+    scope_cmd,
+    sdlc_cmd,
+    source_cmd,
+)
+
+
+class _BannerGroup(click.Group):
+    """Click Group that prints the gradient banner before ``--help`` output."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        from dna_cli._banner import render_banner
+        banner = render_banner()
+        if banner:
+            formatter.write(banner)
+            formatter.write_paragraph()
+        super().format_help(ctx, formatter)
+
+
+@click.group(
+    cls=_BannerGroup,
+    help=(
+        "DNA — declarative lifecycle + document CLI.\n\n"
+        "Boots a local kernel via DNA_SOURCE_URL / DNA_BASE_DIR "
+        "(filesystem source). Run `dna kind list` to start exploring, "
+        "`dna sdlc --help` for the lifecycle verbs."
+    ),
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(version="0.1.0", prog_name="dna")
+def main() -> None:
+    """Top-level group — subcommands attached below."""
+
+
+main.add_command(kind_cmd.kind)
+main.add_command(doc_cmd.doc)
+main.add_command(scope_cmd.scope)
+main.add_command(docs_cmd.docs_)
+main.add_command(sdlc_cmd.sdlc)
+main.add_command(research_cmd.research)
+main.add_command(recall_cmd.recall)
+main.add_command(recall_cmd.search)
+main.add_command(memory_cmd.memory)
+# Importing testkit_cmd registers `sdlc test-guide` + `sdlc test-run` on the
+# sdlc group via its decorators (TESTS as first-class SDLC).
+from dna_cli import testkit_cmd as _testkit_cmd  # noqa: E402,F401
+# Importing hooks_cmd registers `sdlc hooks install|uninstall|status` — the
+# git↔SDLC symbiosis wiring (Work-Item trailers via prepare-commit-msg).
+from dna_cli import hooks_cmd as _hooks_cmd  # noqa: E402,F401
+# Importing pr_cmd registers `sdlc story pr` + `sdlc pr-footer` — the PR
+# half of the symbiosis (attribution footer, PR born from the Story).
+from dna_cli import pr_cmd as _pr_cmd  # noqa: E402,F401
+# Importing issue_bridge_cmd registers `sdlc issue publish|import|sync` —
+# the GitHub Issues side of the symbiosis (bridge with provenance).
+from dna_cli import issue_bridge_cmd as _issue_bridge_cmd  # noqa: E402,F401
+main.add_command(source_cmd.source)
+main.add_command(install_cmd.install)
+main.add_command(eval_cmd.eval_)
+
+
+if __name__ == "__main__":
+    main()

dna_cli/_active_story.py

@@ -0,0 +1,134 @@
+"""Active-Story pointer — `.dna/active-story.txt` at the repo root.
+
+Written by ``dna sdlc story start <name>`` so that out-of-band tools
+(Claude Code hooks, IDE plugins, dashboards) can attribute their
+events to the Story the human-or-agent is currently working on.
+
+File format (single line, plain text)::
+
+    <scope>:<story-name>
+
+Examples::
+
+    dna-development:s-foo
+    hr-screening:s-bar
+
+A trailing newline is optional. The file is gitignored — it is per-
+workstation state, not source-of-truth, so a fresh clone has no
+active Story until ``story start`` is invoked.
+
+Discovery walks up from ``cwd`` looking for ``.git`` to anchor the
+``.dna/`` directory; this matches the convention used by source
+replicas (``.dna-replicas.yaml`` discovery in ``source_replicas.py``).
+Override via ``DNA_ACTIVE_STORY_PATH`` for tests.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_ENV = "DNA_ACTIVE_STORY_PATH"
+_FILENAME = ".dna/active-story.txt"
+
+
+def _find_repo_root(start: Path | None = None) -> Path | None:
+    """Walk up from ``start`` looking for ``.git`` (file or dir).
+
+    Returns ``None`` when no repo root is found. Symmetric with the
+    discovery used in ``source_replicas.py``.
+    """
+    cur = (start or Path.cwd()).resolve()
+    for parent in (cur, *cur.parents):
+        if (parent / ".git").exists():
+            return parent
+    return None
+
+
+def get_active_story_path(*, start: Path | None = None) -> Path:
+    """Resolve the canonical pointer path. Order of precedence:
+
+    1. ``DNA_ACTIVE_STORY_PATH`` env var (tests + advanced setups)
+    2. ``<repo-root>/.dna/active-story.txt`` if walking up finds ``.git``
+    3. ``<cwd>/.dna/active-story.txt`` as fallback (loose-tree mode)
+    """
+    env = os.environ.get(_ENV)
+    if env:
+        return Path(env)
+    root = _find_repo_root(start)
+    if root is not None:
+        return root / _FILENAME
+    return (start or Path.cwd()).resolve() / _FILENAME
+
+
+def write_active_story(scope: str, name: str, *, start: Path | None = None) -> Path:
+    """Stamp ``<scope>:<name>`` to the pointer file. Creates the
+    parent directory if missing. Returns the resolved path. Atomic
+    via tmpfile + rename.
+    """
+    if not scope or not name:
+        raise ValueError("scope and name must both be non-empty")
+    if ":" in scope or ":" in name:
+        # Reserve `:` as the field separator. Story slugs use `s-` /
+        # `f-` / `e-` prefixes by convention so this never collides
+        # in practice; defensive guard just in case.
+        raise ValueError("scope/name must not contain ':'")
+    path = get_active_story_path(start=start)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(f"{scope}:{name}\n", encoding="utf-8")
+    tmp.replace(path)
+    return path
+
+
+def read_active_story(
+    *, start: Path | None = None
+) -> tuple[str, str] | None:
+    """Read the pointer; returns ``(scope, name)`` or ``None`` when
+    absent / empty / malformed. Non-fatal — callers (hooks) treat
+    ``None`` as "no active story; broadcast as ephemeral".
+    """
+    path = get_active_story_path(start=start)
+    try:
+        raw = path.read_text(encoding="utf-8").strip()
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return None
+    if not raw:
+        return None
+    if ":" not in raw:
+        return None
+    scope, _, name = raw.partition(":")
+    scope = scope.strip()
+    name = name.strip()
+    if not scope or not name:
+        return None
+    return scope, name
+
+
+def clear_active_story(*, start: Path | None = None) -> bool:
+    """Remove the pointer file. Returns True if a file was removed,
+    False if it was already absent. Idempotent.
+    """
+    path = get_active_story_path(start=start)
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def clear_if_matches(
+    scope: str, name: str, *, start: Path | None = None
+) -> bool:
+    """Clear the pointer ONLY when it currently points at the given
+    Story. Used by ``dna sdlc story done|block|cancel`` so that
+    closing some other Story (not the active one) doesn't blank the
+    pointer. Returns True when cleared.
+    """
+    cur = read_active_story(start=start)
+    if cur is None:
+        return False
+    if cur != (scope, name):
+        return False
+    return clear_active_story(start=start)

dna_cli/_banner.py

@@ -0,0 +1,61 @@
+"""ASCII banner with cobre/orange gradient, shown on ``dna --help``.
+
+Inspired by ``claude-code-templates`` ``cct`` banner. Renders only when
+stdout is a TTY (skip in pipes / CI). Set ``DNA_NO_BANNER=1`` to disable.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+from rich.console import Console
+from rich.text import Text
+
+# Cobre → laranja → pêssego gradient (same palette aitmpl.com uses).
+_GRADIENT = ["#EA580C", "#F97316", "#FB923C", "#FDBA74", "#FED7AA", "#FFE7CC"]
+
+# Compact 5-line block. Stencil-ish (block characters) for a "Claude Code SDK"
+# feel without being noisy. Width ~50 cols → fits any terminal.
+_LOGO = r"""
+  █████   █████  ██████
+ ██   ██ ██   ██ ██   ██
+ ███████ ███████ ██████
+ ██   ██ ██   ██ ██
+ ██   ██ ██   ██ ██     declarative agent platform
+"""
+
+
+def _gradient_text(line: str) -> Text:
+    """Apply per-character color gradient across visible glyphs."""
+    t = Text()
+    n = len(_GRADIENT)
+    for i, ch in enumerate(line):
+        if ch in (" ", "\n", "\t"):
+            t.append(ch)
+        else:
+            t.append(ch, style=_GRADIENT[i % n])
+    return t
+
+
+def render_banner() -> str:
+    """Return colorized banner string, or empty if banner suppressed."""
+    if os.environ.get("DNA_NO_BANNER") == "1":
+        return ""
+    if not sys.stdout.isatty():
+        return ""
+    lines = _LOGO.strip("\n").splitlines()
+    console = Console(file=sys.stdout, force_terminal=True)
+    # Build the colored block via Rich's capture so we can return it as a string
+    # (Click's HelpFormatter writes strings, not Rich objects).
+    with console.capture() as cap:
+        for line in lines:
+            console.print(_gradient_text(line))
+    return cap.get()
+
+
+def print_banner() -> None:
+    """Print banner to stdout when appropriate."""
+    out = render_banner()
+    if out:
+        click.echo(out)