rdstudio 0.2.0__py3-none-any.whl

rdstudio/scaffold.py

@@ -0,0 +1,227 @@
+"""``rdstudio init``: scaffold rdstudio into a repository, idempotently."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import re
+import shutil
+from pathlib import Path
+from typing import Iterator
+
+from . import config as config_mod
+from .okf import Bundle, dump_frontmatter, split_frontmatter
+
+TEMPLATES = Path(__file__).parent / "templates"
+SECTION_START = "<!-- rdstudio:start"
+SECTION_END = "<!-- rdstudio:end -->"
+HOOK_COMMAND = "rdstudio brief"
+OPENCODE_AGENT = "opencode/unknown"
+
+# OpenCode subagent permissions; Claude Code's equivalent is each agent's `tools` list.
+OPENCODE_PERMISSIONS: dict[str, dict[str, str]] = {
+    "librarian": {"edit": "deny", "bash": "deny", "webfetch": "deny"},
+    "critic": {"edit": "deny", "bash": "deny", "webfetch": "deny"},
+    "searcher": {"edit": "deny"},
+}
+
+
+def _fill(text: str, values: dict[str, str]) -> str:
+    for key, value in values.items():
+        text = text.replace("{" + key + "}", value)
+    return text
+
+
+def _write(path: Path, content: str, root: Path, *, force: bool = False) -> str | None:
+    rel = path.relative_to(root).as_posix()
+    if path.exists():
+        if not force or path.read_text(encoding="utf-8") == content:
+            return None
+        path.write_text(content, encoding="utf-8")
+        return f"updated {rel}"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return f"created {rel}"
+
+
+def _uses_dev_dependency(root: Path) -> bool:
+    pyproject = root / "pyproject.toml"
+    return pyproject.is_file() and re.search(r"[\"']rdstudio\b", pyproject.read_text(encoding="utf-8")) is not None
+
+
+def mcp_command(root: Path) -> dict[str, object]:
+    if _uses_dev_dependency(root) or not shutil.which("rdstudio"):
+        return {"command": "uv", "args": ["run", "rdstudio", "mcp"]}
+    return {"command": "rdstudio", "args": ["mcp"]}
+
+
+def opencode_agent(src: str, name: str) -> str:
+    """Translate a Claude Code subagent file into an OpenCode one."""
+    meta, body = split_frontmatter(src)
+    meta = meta or {}
+    out = {"description": meta.get("description", name), "mode": "subagent"}
+    if name in OPENCODE_PERMISSIONS:
+        out["permission"] = OPENCODE_PERMISSIONS[name]
+    return f"---\n{dump_frontmatter(out)}---\n{body}"
+
+
+def _merge_json(path: Path, root: Path, update) -> str | None:
+    data = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8") or "{}")
+        except json.JSONDecodeError:
+            return f"skipped {path.relative_to(root).as_posix()} (not valid JSON; add rdstudio by hand)"
+    before = json.dumps(data, sort_keys=True)
+    update(data)
+    if json.dumps(data, sort_keys=True) == before:
+        return None
+    existed = path.exists()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return f"{'updated' if existed else 'created'} {path.relative_to(root).as_posix()}"
+
+
+def _managed_section(path: Path, section: str, root: Path, *, create: bool) -> str | None:
+    rel = path.relative_to(root).as_posix()
+    if not path.exists():
+        if not create:
+            return None
+        path.write_text(f"# {root.name}\n\n{section}", encoding="utf-8")
+        return f"created {rel}"
+    text = path.read_text(encoding="utf-8")
+    if SECTION_START in text and SECTION_END in text:
+        start = text.index(SECTION_START)
+        end = text.index(SECTION_END) + len(SECTION_END)
+        new = text[:start] + section.strip() + text[end:]
+    else:
+        new = text.rstrip() + "\n\n" + section
+    if new == text:
+        return None
+    path.write_text(new, encoding="utf-8")
+    return f"updated {rel}"
+
+
+def init(root: Path, *, title: str | None = None, human: str | None = None, force: bool = False) -> Iterator[str]:
+    root = root.resolve()
+    root.mkdir(parents=True, exist_ok=True)
+
+    toml = root / config_mod.PROJECT_FILE
+    if not toml.exists():
+        human = human or config_mod.load(root).human or f"human:{getpass.getuser()}"
+        if not human.startswith("human:"):
+            human = f"human:{human}"
+        toml.write_text(
+            "# rdstudio project configuration\n"
+            "[project]\n"
+            f'title = "{title or root.name}"\n\n'
+            "[paths]\n"
+            'knowledge = "knowledge"\n'
+            'reports = "reports"\n\n'
+            "[actors]\n"
+            f'human = "{human}"\n'
+            'agent = "claude-code/claude"\n\n'
+            "# Which files count as which kind of change in the Changes tab.\n"
+            "# [changes.categories]\n"
+            '# code = ["src/**", "tests/**"]\n',
+            encoding="utf-8",
+        )
+        yield f"created {config_mod.PROJECT_FILE}"
+    cfg = config_mod.load(root)
+    values = {
+        "title": cfg.title,
+        "knowledge": cfg.knowledge,
+        "reports": cfg.reports,
+        "human": cfg.human or "human:<you>",
+        "agent": cfg.agent,
+    }
+
+    # Knowledge bundle placeholders (never overwritten).
+    for src in sorted((TEMPLATES / "knowledge").rglob("*.md")):
+        dst = cfg.knowledge_dir / src.relative_to(TEMPLATES / "knowledge")
+        if msg := _write(dst, _fill(src.read_text(encoding="utf-8"), values), root):
+            yield msg
+
+    cfg.reports_dir.mkdir(parents=True, exist_ok=True)
+    if msg := _write(cfg.reports_dir / ".gitkeep", "", root):
+        yield msg
+
+    # Skills and agents (rdstudio-managed: --force refreshes them).
+    for src in sorted((TEMPLATES / "skills").rglob("*")):
+        if src.is_file():
+            dst = root / ".claude" / "skills" / src.relative_to(TEMPLATES / "skills")
+            if msg := _write(dst, _fill(src.read_text(encoding="utf-8"), values), root, force=force):
+                yield msg
+    for src in sorted((TEMPLATES / "agents").glob("*.md")):
+        text = _fill(src.read_text(encoding="utf-8"), values)
+        if msg := _write(root / ".claude" / "agents" / src.name, text, root, force=force):
+            yield msg
+        if msg := _write(root / ".opencode" / "agents" / src.name, opencode_agent(text, src.stem), root, force=force):
+            yield msg
+
+    # MCP registration and Claude Code settings.
+    command = mcp_command(root)
+
+    def add_server(data: dict) -> None:
+        data.setdefault("mcpServers", {})["rdstudio"] = command
+
+    if msg := _merge_json(root / ".mcp.json", root, add_server):
+        yield msg
+
+    def add_settings(data: dict) -> None:
+        enabled = data.setdefault("enabledMcpjsonServers", [])
+        if "rdstudio" not in enabled:
+            enabled.append("rdstudio")
+        allow = data.setdefault("permissions", {}).setdefault("allow", [])
+        if "mcp__rdstudio" not in allow:
+            allow.append("mcp__rdstudio")
+        hooks = data.setdefault("hooks", {}).setdefault("SessionStart", [])
+        brief = HOOK_COMMAND if command["command"] == "rdstudio" else "uv run " + HOOK_COMMAND
+        present = any(h.get("command", "").endswith(HOOK_COMMAND) for entry in hooks for h in entry.get("hooks", []))
+        if not present:
+            hooks.append({"hooks": [{"type": "command", "command": brief}]})
+
+    if msg := _merge_json(root / ".claude" / "settings.json", root, add_settings):
+        yield msg
+
+    # OpenCode: MCP registration. It reads skills from .claude/skills directly.
+    def add_opencode(data: dict) -> None:
+        data.setdefault("$schema", "https://opencode.ai/config.json")
+        data.setdefault("mcp", {})["rdstudio"] = {
+            "type": "local",
+            "command": [command["command"], *command["args"], "--agent", OPENCODE_AGENT],
+            "enabled": True,
+        }
+
+    jsonc = root / "opencode.jsonc"
+    if jsonc.exists() and not (root / "opencode.json").exists():
+        msg = _merge_json(jsonc, root, add_opencode)
+    else:
+        msg = _merge_json(root / "opencode.json", root, add_opencode)
+    if msg:
+        yield msg
+
+    # Instructions: the shared section lives in AGENTS.md (read by OpenCode, Codex
+    # and others); CLAUDE.md imports it.
+    section = _fill((TEMPLATES / "agents_section.md").read_text(encoding="utf-8"), values)
+    if msg := _managed_section(root / "AGENTS.md", section, root, create=True):
+        yield msg
+    claude_md = root / "CLAUDE.md"
+    if not (claude_md.is_symlink() and claude_md.resolve() == (root / "AGENTS.md").resolve()):
+        section = (TEMPLATES / "claude_section.md").read_text(encoding="utf-8")
+        if msg := _managed_section(claude_md, section, root, create=True):
+            yield msg
+
+    gitignore = root / ".gitignore"
+    ignore_line = cfg.output.strip("/") + "/"
+    lines = gitignore.read_text(encoding="utf-8").splitlines() if gitignore.exists() else []
+    if ignore_line not in lines and f"/{ignore_line}" not in lines:
+        with gitignore.open("a", encoding="utf-8") as fh:
+            prefix = "\n" if lines and lines[-1].strip() else ""
+            fh.write(f"{prefix}# rdstudio build output\n{ignore_line}\n")
+        yield "updated .gitignore"
+
+    for rel in Bundle.load(cfg.knowledge_dir).write_indexes():
+        yield f"wrote {cfg.knowledge}/{rel}"
+
+    yield "done. Next: `rdstudio serve` for the dashboard; start an agent session (Claude Code, OpenCode, ...) and run the bootstrap task."

rdstudio/scopes.py

@@ -0,0 +1,162 @@
+"""The global knowledge base, promotion between bundles, and skill scopes.
+
+The global knowledge base is an ordinary rdstudio root (by default
+``~/knowledge``, a private git repository) named in the user configuration::
+
+    # ~/.config/rdstudio/config.toml
+    [global]
+    path = "~/knowledge"
+
+Bundles never link to each other. Knowledge moves from a project to the global
+base by promotion; the project export never includes global content.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Iterator
+
+from . import config as config_mod
+from .config import Config
+from .okf import Bundle, render_concept, split_frontmatter
+from .store import concept_path
+
+
+class ScopeError(RuntimeError):
+    pass
+
+
+def global_config(cfg: Config) -> Config | None:
+    """The global knowledge base's configuration, if one is set up and enabled."""
+    if not cfg.use_global or cfg.global_bundle is None:
+        return None
+    root = cfg.global_bundle.expanduser()
+    if not (root / config_mod.PROJECT_FILE).is_file():
+        return None
+    if cfg.is_project and root.resolve() == cfg.root.resolve():
+        return None  # we are the global base
+    return config_mod.load(root)
+
+
+def scoped(cfg: Config, scope: str) -> list[tuple[str, Config]]:
+    """``[(name, config)]`` for ``project`` | ``global`` | ``all``."""
+    if scope not in ("project", "global", "all"):
+        raise ScopeError(f"unknown scope {scope!r}; use project, global or all")
+    out: list[tuple[str, Config]] = []
+    if scope in ("project", "all"):
+        out.append(("project", cfg))
+    if scope in ("global", "all"):
+        g = global_config(cfg)
+        if g is None:
+            if scope == "global":
+                raise ScopeError("no global knowledge base (run `rdstudio global init`)")
+        else:
+            out.append(("global", g))
+    return out
+
+
+def _set_user_global(path: Path) -> str:
+    user = config_mod.user_config_path()
+    text = user.read_text(encoding="utf-8") if user.exists() else ""
+    line = f'path = "{path}"'
+    if "[global]" in text:
+        lines = text.splitlines()
+        start = lines.index("[global]")
+        end = next((i for i in range(start + 1, len(lines)) if lines[i].startswith("[")), len(lines))
+        block = [l for l in lines[start + 1 : end] if not l.strip().startswith("path")]
+        lines[start + 1 : end] = [line, *block]
+        text = "\n".join(lines) + "\n"
+    else:
+        text = (text.rstrip() + "\n\n" if text.strip() else "") + f"[global]\n{line}\n"
+    user.parent.mkdir(parents=True, exist_ok=True)
+    user.write_text(text, encoding="utf-8")
+    return f"set [global] path in {user}"
+
+
+def init_global(path: Path, *, human: str | None = None) -> Iterator[str]:
+    from .scaffold import init
+
+    path = path.expanduser().resolve()
+    yield from init(path, title="Global knowledge", human=human)
+    if not (path / ".git").exists():
+        subprocess.run(["git", "init", "-q", "-b", "main", str(path)], check=False)
+        yield f"initialised a git repository in {path} (private: add no remote unless you mean to)"
+    yield _set_user_global(path)
+
+
+def promote(cfg: Config, cid: str, *, as_id: str | None = None, keep: bool = False,
+            force: bool = False) -> dict[str, Any]:
+    """Move (or copy, with ``keep``) a project concept into the global base."""
+    g = global_config(cfg)
+    if g is None:
+        raise ScopeError("no global knowledge base (run `rdstudio global init`)")
+    project = Bundle.load(cfg.knowledge_dir)
+    source_id = project.resolve_id(cid)
+    if source_id is None:
+        raise ScopeError(f"no project concept {cid!r}")
+    backlinks = project.backlinks(source_id)
+    if backlinks and not keep and not force:
+        raise ScopeError(
+            "project concepts link to it: " + ", ".join(backlinks)
+            + ". Use --keep to copy instead of move, or --force to move anyway."
+        )
+    target = concept_path(g.knowledge_dir, as_id or source_id)
+    if target.exists():
+        raise ScopeError(f"the global base already has {target.relative_to(g.knowledge_dir)}")
+    src = concept_path(cfg.knowledge_dir, source_id)
+    meta, body = split_frontmatter(src.read_text(encoding="utf-8"))
+    meta = dict(meta or {})
+    sources = list(meta.get("sources") or [])
+    sources.append({"resource": f"project {cfg.title}: {source_id}", "title": "Promoted from a project"})
+    meta["sources"] = sources
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(render_concept(meta, body), encoding="utf-8")
+    if not keep:
+        src.unlink()
+    new_id = target.relative_to(g.knowledge_dir).as_posix()[:-3]
+    global_bundle = Bundle.load(g.knowledge_dir)
+    unresolved = [l.target for l in global_bundle.concepts[new_id].links if l.broken]
+    global_bundle.write_indexes()
+    Bundle.load(cfg.knowledge_dir).write_indexes()
+    return {
+        "from": source_id,
+        "to": new_id,
+        "moved": not keep,
+        "broken_links_in_global": unresolved,
+        "project_backlinks": backlinks,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Skill scopes
+# --------------------------------------------------------------------------- #
+
+
+def user_skills_dir() -> Path:
+    return Path.home() / ".claude" / "skills"
+
+
+def skill_dirs(cfg: Config) -> dict[str, dict[str, Path]]:
+    out: dict[str, dict[str, Path]] = {"project": {}, "user": {}}
+    for scope, base in (("project", cfg.root / ".claude" / "skills"), ("user", user_skills_dir())):
+        if base.is_dir():
+            for d in sorted(base.iterdir()):
+                if (d / "SKILL.md").is_file():
+                    out[scope][d.name] = d
+    return out
+
+
+def move_skill(cfg: Config, name: str, to: str) -> str:
+    dirs = skill_dirs(cfg)
+    src_scope = "project" if to == "user" else "user"
+    if name not in dirs[src_scope]:
+        raise ScopeError(f"no {src_scope} skill {name!r}")
+    if name in dirs[to]:
+        raise ScopeError(f"a {to} skill {name!r} already exists")
+    dest_base = user_skills_dir() if to == "user" else cfg.root / ".claude" / "skills"
+    dest_base.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(dirs[src_scope][name]), dest_base / name)
+    return f"moved skill {name} to {to} scope ({dest_base / name})"
+

rdstudio/search.py

@@ -0,0 +1,149 @@
+"""Deterministic BM25 search over an OKF bundle.
+
+Results carry only what an agent needs to decide what to open next (id, title,
+description, score, a short snippet); bodies are fetched separately by section.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+from .okf import Bundle, Concept, headings
+
+_TOKEN = re.compile(r"[a-z0-9]+(?:['’][a-z]+)?")
+_STOP = frozenset(
+    "a an and are as at be by for from has have in is it its of on or that the this to was were "
+    "will with not but if then than so do does did can could should would into about".split()
+)
+FIELD_WEIGHTS = {"title": 4, "tags": 3, "description": 2, "headings": 2, "type": 1, "body": 1}
+K1, B = 1.4, 0.75
+
+
+def _stem(token: str) -> str:
+    for suffix in ("ness", "ing"):
+        if token.endswith(suffix) and len(token) - len(suffix) >= 4:
+            return token[: -len(suffix)]
+    if len(token) > 4 and token.endswith("ies"):
+        return token[:-3] + "y"
+    if len(token) > 3 and token.endswith("s") and not token.endswith(("ss", "us", "is")):
+        return token[:-1]
+    return token
+
+
+def tokenize(text: str) -> list[str]:
+    return [_stem(t) for t in _TOKEN.findall(text.lower().replace("’", "'")) if t not in _STOP]
+
+
+@dataclass
+class Hit:
+    concept: Concept
+    score: float
+    snippet: str
+
+    def as_dict(self) -> dict[str, Any]:
+        c = self.concept
+        return {
+            "id": c.id,
+            "title": c.title,
+            "type": c.type,
+            "description": c.description,
+            "trust": c.trust,
+            "score": round(self.score, 3),
+            "snippet": self.snippet,
+        }
+
+
+class Index:
+    def __init__(self, bundle: Bundle):
+        self.bundle = bundle
+        self.docs: dict[str, Counter[str]] = {}
+        self.lengths: dict[str, int] = {}
+        self.df: Counter[str] = Counter()
+        for cid, concept in bundle.concepts.items():
+            tf: Counter[str] = Counter()
+            fields = {
+                "title": concept.title,
+                "tags": " ".join(concept.tags),
+                "description": concept.description,
+                "headings": " ".join(h.text for h in headings(concept.body)),
+                "type": concept.type,
+                "body": concept.body,
+            }
+            for name, text in fields.items():
+                for token in tokenize(text):
+                    tf[token] += FIELD_WEIGHTS[name]
+            self.docs[cid] = tf
+            self.lengths[cid] = sum(tf.values())
+            self.df.update(tf.keys())
+        self.avg_len = (sum(self.lengths.values()) / len(self.lengths)) if self.lengths else 0.0
+
+    def _idf(self, token: str) -> float:
+        n = len(self.docs)
+        df = self.df.get(token, 0)
+        return math.log(1 + (n - df + 0.5) / (df + 0.5))
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 8,
+        type: str | None = None,
+        tags: Iterable[str] | None = None,
+        trust: str | None = None,
+        status: str | None = None,
+        under: str | None = None,
+    ) -> list[Hit]:
+        terms = tokenize(query)
+        wanted_tags = {t.lower() for t in (tags or [])}
+        hits: list[Hit] = []
+        for cid, tf in self.docs.items():
+            c = self.bundle.concepts[cid]
+            if type and c.type.lower() != type.lower():
+                continue
+            if wanted_tags and not wanted_tags <= {t.lower() for t in c.tags}:
+                continue
+            if trust and c.trust != trust:
+                continue
+            if status and c.status != status:
+                continue
+            if under and not (cid + "/").startswith(under.strip("/") + "/"):
+                continue
+            score = 0.0
+            norm = K1 * (1 - B + B * self.lengths[cid] / self.avg_len) if self.avg_len else K1
+            for term in terms:
+                f = tf.get(term, 0)
+                if f:
+                    score += self._idf(term) * f * (K1 + 1) / (f + norm)
+            if terms and score <= 0:
+                continue
+            hits.append(Hit(c, score, snippet(c, terms)))
+        hits.sort(key=lambda h: (-h.score, h.concept.id))
+        return hits[:limit]
+
+
+def snippet(concept: Concept, terms: list[str], width: int = 160) -> str:
+    """The first body line mentioning a query term, trimmed around the match."""
+    term_set = set(terms)
+    in_fence = False
+    for raw in concept.body.split("\n"):
+        line = raw.strip()
+        if line.startswith(("```", "~~~")):
+            in_fence = not in_fence
+            continue
+        if in_fence or not line:
+            continue
+        tokens = tokenize(line)
+        if term_set & set(tokens):
+            lower = line.lower()
+            pos = min((lower.find(t) for t in term_set if lower.find(t) >= 0), default=0)
+            start = max(0, pos - width // 3)
+            if start:
+                space = line.find(" ", start)
+                start = space + 1 if 0 <= space < pos else start
+            text = line[start : start + width]
+            return ("…" if start else "") + text + ("…" if start + width < len(line) else "")
+    return concept.description[:width]