rdstudio 0.2.0__py3-none-any.whl

rdstudio/brief.py

@@ -0,0 +1,46 @@
+"""A short orientation for the start of an agent session (``rdstudio brief``).
+
+Printed by a Claude Code SessionStart hook and returned by the MCP ``brief``
+tool, so it must stay small: it tells the
+agent what exists and where to look, not the content itself.
+"""
+
+from __future__ import annotations
+
+from . import gitlog
+from .config import Config
+from .okf import Bundle
+
+
+def brief(cfg: Config, *, commits: int = 3) -> str:
+    b = Bundle.load(cfg.knowledge_dir)
+    if not b.concepts:
+        return f"rdstudio: no knowledge base found in {cfg.knowledge}/ (run `rdstudio init`)."
+    lines = [f"Project knowledge base ({cfg.title}): {len(b.concepts)} concepts in {cfg.knowledge}/, OKF format."]
+    root = b.directories[""]
+    dirs = []
+    for d in sorted(root.children):
+        count = sum(1 for cid in b.concepts if cid.startswith(d + "/"))
+        dirs.append(f"{d} ({count})")
+    if dirs:
+        lines.append("Directories: " + ", ".join(dirs))
+    active = [c for c in b.concepts.values() if c.type.lower() == "task" and "active" in c.tags]
+    if active:
+        lines.append("Active tasks: " + "; ".join(f"{c.title} [{c.id}]" for c in active[:5]))
+    stale = sum(c.verification_stale for c in b.concepts.values())
+    questions = sum(c.type.lower() == "question" and "answered" not in c.tags for c in b.concepts.values())
+    unverified = sum(c.trust == "unverified" for c in b.concepts.values())
+    lines.append(f"Awaiting the developer: {stale} changed since review, {questions} open questions, {unverified} unverified.")
+    history = gitlog.history(cfg.root, cfg.category_globs(), limit=commits, exclude=(cfg.output.strip("/") + "/",))
+    recent = [c["subject"] for c in history.get("commits", []) if not c.get("pending")][:commits]
+    if recent:
+        lines.append("Recent commits: " + " | ".join(recent))
+    from .scopes import global_config
+
+    g = global_config(cfg)
+    if g is not None:
+        count = len(Bundle.load(g.knowledge_dir).concepts)
+        lines.append(f"A global knowledge base (cross-project; {count} concepts) is searchable with scope=\"global\".")
+    lines.append("Search it (rdstudio MCP tools, the search-okf skill, or the librarian subagent) before re-deriving; "
+                 "record decisions, questions and findings as you go.")
+    return "\n".join(lines)

rdstudio/build.py

@@ -0,0 +1,218 @@
+"""Build the static dashboard: web assets plus JSON data under ``.rdstudio/site``."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from . import gitlog, learner, reports
+from .config import Config
+from .okf import Bundle, FrontmatterError, headings, iso, jsonable, now, split_frontmatter
+
+WEB_DIR = Path(__file__).parent / "web"
+
+
+def _sync_tree(src: Path, dst: Path, *, skip: frozenset[str] = frozenset()) -> None:
+    """Copy ``src`` into ``dst``, skipping files whose size and mtime already match
+    and the relative paths in ``skip``."""
+    for path in src.rglob("*"):
+        rel = path.relative_to(src)
+        if rel.as_posix() in skip:
+            continue
+        target = dst / rel
+        if path.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+            continue
+        st = path.stat()
+        if target.exists():
+            tt = target.stat()
+            if tt.st_size == st.st_size and int(tt.st_mtime) == int(st.st_mtime):
+                continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, target)
+
+
+def service_worker() -> str:
+    """The service worker, stamped with a fingerprint of the app's files, so a
+    new rdstudio (or an edited app file) replaces what browsers have cached."""
+    digest = hashlib.sha256()
+    for path in sorted(WEB_DIR.rglob("*")):
+        if path.is_file():
+            st = path.stat()
+            digest.update(f"{path.relative_to(WEB_DIR).as_posix()}:{st.st_size}:{st.st_mtime_ns}\n".encode())
+    return (WEB_DIR / "sw.js").read_text(encoding="utf-8").replace("__SHELL__", digest.hexdigest()[:16])
+
+
+def _write_if_changed(path: Path, content: str) -> None:
+    if path.exists() and path.read_text(encoding="utf-8") == content:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _dump(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=str)
+
+
+def concept_record(bundle: Bundle, cid: str) -> dict[str, Any]:
+    c = bundle.concepts[cid]
+    rec = c.summary()
+    place = bundle.prerequisite_order()[cid]
+    rec.update({
+        "hash": learner.content_hash(c.body),  # the version learner-record events refer to
+        "order": place["order"],  # reading order from requires links
+        "depth": place["depth"],  # longest chain of prerequisites below this note
+        "requires": bundle.requires_graph()[cid],
+        "meta": jsonable(c.meta),
+        "directory": c.directory,
+        "links": [{"target": l.target, "kind": l.kind, "broken": l.broken, "rel": l.rel} for l in c.links],
+        "backlinks": bundle.backlinks(cid),
+        "headings": [{"level": h.level, "text": h.text, "slug": h.slug} for h in headings(c.body)],
+        "generated_at": iso(c.generated_at) if c.generated_at else None,
+        "mtime": int(c.mtime),
+    })
+    return rec
+
+
+def tree_record(bundle: Bundle) -> dict[str, Any]:
+    out = {}
+    for did, d in bundle.directories.items():
+        overview = bundle.overview_for(did)
+        out[did] = {
+            "id": did,
+            "name": d.name,
+            "concepts": sorted(d.concepts, key=lambda c: bundle.concepts[c].title.lower()),
+            "children": sorted(d.children),
+            "overview": overview.id if overview else None,
+            "index": bundle.render_index(did),
+        }
+    return out
+
+
+def _skill_files(root: Path, *, user: bool = True) -> dict[str, list[dict[str, Any]]]:
+    """Skills (``.claude/skills/<name>/SKILL.md``) and agents (``.claude/agents/*.md``),
+    from the project and, unless ``user`` is false, from ``~/.claude``."""
+    out: dict[str, list[dict[str, Any]]] = {"skills": [], "agents": []}
+    specs = [("skills", "project", root, sorted((root / ".claude" / "skills").glob("*/SKILL.md"))),
+             ("agents", "project", root, sorted((root / ".claude" / "agents").glob("*.md")))]
+    if user:
+        home = Path.home()
+        specs += [("skills", "user", home, sorted((home / ".claude" / "skills").glob("*/SKILL.md"))),
+                  ("agents", "user", home, sorted((home / ".claude" / "agents").glob("*.md")))]
+    for kind, scope, base, paths in specs:
+        for path in paths:
+            try:
+                meta, body = split_frontmatter(path.read_text(encoding="utf-8"))
+            except FrontmatterError:
+                meta, body = {}, path.read_text(encoding="utf-8")
+            meta = meta or {}
+            name = meta.get("name") or (path.parent.name if kind == "skills" else path.stem)
+            out[kind].append({
+                "name": str(name),
+                "description": str(meta.get("description") or ""),
+                "path": ("~/" if scope == "user" else "") + path.relative_to(base).as_posix(),
+                "scope": scope,
+                "meta": jsonable(meta),
+                "body": body,
+            })
+    return out
+
+
+def build(cfg: Config, *, write_indexes: bool | None = None, export: bool = False,
+          site: Path | None = None) -> Path:
+    """Build the dashboard into ``site`` (default ``.rdstudio/site``).
+
+    ``export`` produces a snapshot for static hosting: no user-level skills, no
+    uncommitted changes, and the page does not poll for updates."""
+    site = site or cfg.site_dir
+    data = site / "data"
+    site.mkdir(parents=True, exist_ok=True)
+    _sync_tree(WEB_DIR, site, skip=frozenset({"sw.js"}))
+    _write_if_changed(site / "sw.js", service_worker())
+
+    auto_index = cfg.raw.get("index", {}).get("auto", True) if write_indexes is None else write_indexes
+    bundle = Bundle.load(cfg.knowledge_dir)
+    if auto_index and cfg.knowledge_dir.is_dir():
+        if bundle.write_indexes():
+            bundle = Bundle.load(cfg.knowledge_dir)
+
+    concepts = [concept_record(bundle, cid) for cid in sorted(bundle.concepts)]
+    tree = tree_record(bundle)
+    changes = gitlog.history(cfg.root, cfg.category_globs(), exclude=(cfg.output.strip("/") + "/",))
+    if export:
+        changes["commits"] = [c for c in changes["commits"] if not c.get("pending")]
+    report_items = reports.scan(cfg.reports_dir, cfg.knowledge, cfg.reports)
+    skills = _skill_files(cfg.root, user=not export)
+    issues = [{"path": i.path, "level": i.level, "code": i.code, "message": i.message} for i in bundle.lint()]
+
+    payload = {
+        "concepts.json": _dump(concepts),
+        "tree.json": _dump(tree),
+        "changes.json": _dump(changes),
+        "reports.json": _dump(report_items),
+        "skills.json": _dump(skills),
+    }
+    site_info = {
+        "title": cfg.title,
+        "knowledge": cfg.knowledge,
+        "reports": cfg.reports,
+        "human": cfg.human,
+        "okf_version": bundle.root_meta.get("okf_version"),
+        "static": export,
+        "map": cfg.raw.get("map", {}),  # project defaults for the Map tab ([map] in rdstudio.toml)
+        "issues": issues,
+        "counts": {"concepts": len(concepts), "reports": len(report_items),
+                   "skills": len(skills["skills"]), "agents": len(skills["agents"])},
+    }
+    payload["site.json"] = _dump(site_info)
+
+    bodies: dict[str, str] = {f"k/{cid}.md": c.body for cid, c in bundle.concepts.items()}
+    digest = hashlib.sha256()
+    for name in sorted(payload):
+        digest.update(payload[name].encode())
+    for name in sorted(bodies):
+        digest.update(name.encode() + bodies[name].encode())
+    version = digest.hexdigest()[:16]
+
+    for rel, text in bodies.items():
+        _write_if_changed(data / rel, text)
+    keep = {data / rel for rel in bodies}
+    # Non-markdown bundle files (images, data) are served beside the bodies.
+    if cfg.knowledge_dir.is_dir():
+        for path in cfg.knowledge_dir.rglob("*"):
+            rel = path.relative_to(cfg.knowledge_dir)
+            if path.is_file() and path.suffix != ".md" and not any(p.startswith(".") for p in rel.parts):
+                target = data / "k" / rel
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if not target.exists() or target.stat().st_mtime < path.stat().st_mtime:
+                    shutil.copy2(path, target)
+    if (data / "k").is_dir():
+        for stale in (data / "k").rglob("*.md"):
+            if stale not in keep:
+                stale.unlink()
+
+    # Reports are served beside the app so relative media keeps working.
+    if cfg.reports_dir.is_dir():
+        _sync_tree(cfg.reports_dir, site / "reports")
+
+    for name, text in payload.items():
+        _write_if_changed(data / name, text)
+    # Installable as an app (add to home screen), opening full screen.
+    _write_if_changed(site / "manifest.webmanifest", _dump({
+        "name": cfg.title, "short_name": cfg.title[:24], "start_url": "./", "scope": "./",
+        "display": "fullscreen", "display_override": ["fullscreen", "standalone"],
+        "background_color": "#141a20", "theme_color": "#141a20",
+        "icons": [{"src": f"icon-{n}.png", "sizes": f"{n}x{n}", "type": "image/png", "purpose": "any maskable"}
+                  for n in (192, 512)],
+    }))
+    vfile = data / "version.json"
+    try:
+        old = json.loads(vfile.read_text(encoding="utf-8")).get("version")
+    except (OSError, ValueError):
+        old = None
+    if old != version:
+        vfile.write_text(_dump({"version": version, "built": iso(now())}), encoding="utf-8")
+    return site

rdstudio/classify.py

@@ -0,0 +1,131 @@
+"""Small structured decisions behind one interface.
+
+Two places in rdstudio need a quick classification rather than generated text:
+
+- whether an edit to a concept is significant (it bumps ``generated`` and flags
+  human-reviewed concepts for re-review), when the agent leaves it to rdstudio;
+- which step of a procedure an agent is on, when its description does not match
+  a step exactly.
+
+The default backend is deterministic and offline. A ``command`` backend hands
+the question to any external program, which is how a structured-output model
+(for example TypeSafe's Jev) or a local model can be plugged in without
+rdstudio depending on a vendor SDK::
+
+    [classifier]
+    backend = "command"
+    command = ["my-classifier"]   # reads JSON on stdin, writes JSON on stdout
+    min_confidence = 0.7          # below this, fall back to the rules
+
+The program receives ``{"question", "options", "state"}`` and must answer
+``{"choice": <one of options>, "confidence": <0..1>}``.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .search import tokenize
+
+
+@dataclass
+class Decision:
+    choice: str | None
+    confidence: float
+    backend: str
+
+
+class Classifier(Protocol):
+    def choose(self, question: str, options: list[str], state: dict[str, Any]) -> Decision: ...
+
+
+# --------------------------------------------------------------------------- #
+# Rules
+# --------------------------------------------------------------------------- #
+
+_WS = re.compile(r"\s+")
+_PUNCT = re.compile(r"[^\w\s]")
+
+
+def _norm(text: str) -> str:
+    return _WS.sub(" ", _PUNCT.sub("", text.lower())).strip()
+
+
+def edit_significance(before: str, after: str) -> Decision:
+    """``minor`` for formatting, punctuation, case or very small wording changes;
+    ``significant`` otherwise."""
+    if _norm(before) == _norm(after):
+        return Decision("minor", 0.95, "rules")
+    a, b = tokenize(before), tokenize(after)
+    matcher = difflib.SequenceMatcher(a=a, b=b, autojunk=False)
+    changed = sum(max(i2 - i1, j2 - j1) for tag, i1, i2, j1, j2 in matcher.get_opcodes() if tag != "equal")
+    if changed <= 3 and changed / max(len(a), 1) < 0.05:
+        return Decision("minor", 0.7, "rules")
+    return Decision("significant", 0.8 if changed > 10 else 0.6, "rules")
+
+
+def match_step(description: str, steps: dict[str, str]) -> Decision:
+    """The step whose label shares the most words with ``description``."""
+    def same(a: str, b: str) -> bool:  # tolerate inflection: "renamed" ~ "rename"
+        return a == b or (min(len(a), len(b)) >= 4 and (a.startswith(b) or b.startswith(a)))
+
+    words = set(tokenize(description))
+    best, best_score = None, 0.0
+    for sid, label in steps.items():
+        label_words = set(tokenize(label)) | set(tokenize(sid.replace("-", " ").replace("_", " ")))
+        if not label_words or not words:
+            continue
+        shared = sum(1 for w in words if any(same(w, l) for l in label_words))
+        score = shared / (len(words) + len(label_words) - shared)
+        if score > best_score:
+            best, best_score = sid, score
+    return Decision(best if best_score >= 0.34 else None, round(best_score, 2), "rules")
+
+
+class RulesClassifier:
+    def choose(self, question: str, options: list[str], state: dict[str, Any]) -> Decision:
+        if question == "edit_significance":
+            return edit_significance(state.get("before", ""), state.get("after", ""))
+        if question == "procedure_step":
+            return match_step(state.get("description", ""), state.get("steps", {}))
+        return Decision(None, 0.0, "rules")
+
+
+# --------------------------------------------------------------------------- #
+# External command
+# --------------------------------------------------------------------------- #
+
+
+class CommandClassifier:
+    def __init__(self, command: list[str], min_confidence: float = 0.7, timeout: float = 10.0):
+        self.command = command
+        self.min_confidence = min_confidence
+        self.timeout = timeout
+        self.fallback = RulesClassifier()
+
+    def choose(self, question: str, options: list[str], state: dict[str, Any]) -> Decision:
+        payload = json.dumps({"question": question, "options": options, "state": state})
+        try:
+            proc = subprocess.run(self.command, input=payload, capture_output=True, text=True,
+                                  timeout=self.timeout, check=True)
+            answer = json.loads(proc.stdout)
+            choice, confidence = answer.get("choice"), float(answer.get("confidence", 0))
+        except (OSError, subprocess.SubprocessError, ValueError, AttributeError):
+            return self.fallback.choose(question, options, state)
+        if choice not in options or confidence < self.min_confidence:
+            return self.fallback.choose(question, options, state)
+        return Decision(choice, confidence, "command")
+
+
+def from_config(raw: dict[str, Any]) -> Classifier:
+    conf = raw.get("classifier", {})
+    if conf.get("backend") == "command" and conf.get("command"):
+        command = conf["command"]
+        return CommandClassifier(command if isinstance(command, list) else str(command).split(),
+                                 float(conf.get("min_confidence", 0.7)))
+    return RulesClassifier()