brain-wiki 0.1.0.dev0__py3-none-any.whl

brainwiki/cli/_cmd_harvest.py

@@ -0,0 +1,137 @@
+"""harvest, origin."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any
+
+from brainwiki.cli._output import emit, warn
+from brainwiki.errors import UsageError
+
+
+def harvest(args: Any) -> int:
+    from brainwiki import harvest as hv
+    from brainwiki.config import load_user_config
+
+    user = load_user_config()
+    hosts = args.hosts or list(user.harvest.get("hosts") or ["claude-code", "codex", "antigravity"])
+    candidates = hv.discover(user, hosts, since=args.since, project=args.project)
+    eligible = [c for c in candidates if not c.skip]
+    if args.status:
+        rows = []
+        for host in hosts:
+            mine = [c for c in candidates if c.info.host == host]
+            rows.append(
+                {
+                    "host": host,
+                    "enabled": user.harvest_enabled(host),
+                    "sessions": len(mine),
+                    "unharvested": sum(1 for c in mine if not c.skip),
+                }
+            )
+        text = "\n".join(
+            f"{r['host']}: {'on' if r['enabled'] else 'off'}, {r['unharvested']} of {r['sessions']} sessions to harvest"
+            for r in rows
+        )
+        if not all(r["enabled"] for r in rows):
+            text += (
+                f"\nTo turn harvest on, add to {user.path}:\n"
+                '[harvest]\nenabled = true\nhosts = ["claude-code", "codex", "antigravity"]'
+            )
+        emit(args, rows, text)
+        return 0
+    if not args.apply:
+        data = [c.to_json() for c in candidates]
+        lines = [
+            f"{c.info.host} {c.info.id[:12]}  → {c.brain.display_name if c.brain else '-'}  "
+            + (
+                f"skip: {c.skip}"
+                if c.skip
+                else f"turns {c.to_json()['turns']}, ~{c.to_json()['estimated_tokens']} tokens"
+            )
+            for c in candidates
+        ]
+        total = sum(c.to_json()["estimated_tokens"] for c in eligible)
+        if any(c.skip == "routes to no brain" for c in candidates):
+            lines.append(
+                "Sessions route to the brain of their working directory: put a .brain-wiki.toml "
+                'with `brain = "NAME"` in the project, or map folders in [harvest.routes] in '
+                f"{user.path}."
+            )
+        lines.append(
+            f"{len(eligible)} sessions to harvest, ~{total} tokens to distill."
+            + (" Run with --apply." if eligible else "")
+        )
+        emit(args, data, "\n".join(lines))
+        return 0
+    preset = None if args.raw else (args.distill or user.harvest.get("distill") or "claude-code")
+    if preset == "raw":
+        preset = None
+    results = [_harvest_one(hv, c, preset, dry_run=args.dry_run) for c in eligible]
+    written = [p for r in results for p in r["episodes"]]
+    emit(args, results, f"Wrote {len(written)} episodes from {len(eligible)} sessions.")
+    return 0 if all(not r.get("error") for r in results) else 1
+
+
+def _harvest_one(hv: Any, candidate: Any, preset: str | None, *, dry_run: bool) -> dict[str, Any]:
+    from brainwiki.consolidate import run_command
+
+    out: dict[str, Any] = {
+        "session": candidate.info.id,
+        "host": candidate.info.host,
+        "episodes": [],
+    }
+    prompt_head = (resources.files("brainwiki") / "assets" / "prompts" / "distill.md").read_text(
+        encoding="utf-8"
+    )
+    for group in hv.chunks(candidate.new_turns):
+        first, last = group[0].index, group[-1].index
+        if dry_run:
+            out["episodes"].append(f"(dry run) turns {first}-{last}")
+            continue
+        if preset is None:
+            out["episodes"].append(
+                hv.write_episode_for(candidate, first, last, None, raw_turns=group)
+            )
+            hv.advance(candidate.info.host, candidate.info.id, last)
+            continue
+        turns, truncated = hv.condense(group, hv.CHUNK_CHARS)
+        payload = json.dumps(hv.session_payload(candidate, turns, truncated), ensure_ascii=False)
+        try:
+            reply = run_command(preset, prompt_head + "\n" + payload + "\n")
+        except Exception as exc:  # noqa: BLE001 - report per session and continue
+            out["error"] = str(exc)
+            warn(f"{candidate.info.id}: {exc}")
+            return out
+        data = _first_json(reply)
+        distilled, problems = hv.parse_distilled(data, first, last)
+        if problems:
+            out["error"] = "; ".join(problems)
+            return out
+        if distilled is not None and not distilled.skip:
+            out["episodes"].append(hv.write_episode_for(candidate, first, last, distilled))
+        hv.advance(candidate.info.host, candidate.info.id, last)
+    return out
+
+
+def _first_json(text: str) -> Any:
+    decoder = json.JSONDecoder()
+    for start in [i for i, ch in enumerate(text) if ch == "{"]:
+        try:
+            value, _ = decoder.raw_decode(text[start:])
+        except ValueError:
+            continue
+        if isinstance(value, dict):
+            return value
+    raise UsageError("the distill reply contained no JSON object")
+
+
+def origin(args: Any) -> int:
+    from brainwiki.engine import open_engine
+    from brainwiki.origin import format_origin, origin_window
+
+    with open_engine(args.brain, host=getattr(args, "as_host", None)) as engine:
+        result = origin_window(engine, args.episode, turns=args.turns)
+    emit(args, result, format_origin(result))
+    return 0

brainwiki/cli/_cmd_hosts.py

@@ -0,0 +1,52 @@
+"""connect, mcp."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def mcp(args: Any) -> int:
+    from brainwiki.mcp import serve
+
+    serve(args.host, args.brain)
+    return 0
+
+
+def connect(args: Any) -> int:
+    from brainwiki.cli._output import emit
+    from brainwiki.errors import UsageError
+    from brainwiki.hosts import connect as cn
+
+    if args.uninstall:
+        steps = cn.uninstall(args.host, dry_run=args.dry_run)
+        emit(args, {"host": args.host, "steps": steps}, "\n".join(steps))
+        return 0
+    if args.print_only or args.host == "generic":
+        if args.host not in cn.HOSTS:
+            raise UsageError(f"unknown host {args.host!r}; use one of {', '.join(cn.HOSTS)}")
+        text = cn.print_text(args.host, args.brain)
+        emit(args, {"text": text}, text)
+        return 0
+    plan = cn.plan(args.host, scope=args.scope, brain_name=args.brain, force=args.force)
+    if args.dry_run:
+        emit(args, {"plan": plan.describe()}, plan.describe())
+        return 0
+    record = cn.apply(plan, brain_name=args.brain, scope=args.scope)
+    failed = [c for c in record["commands"] if not c["ok"]]
+    lines = [f"Connected {args.host}: plugin at {record['plugin_dir']}"]
+    lines += [
+        f"  instructions: {item['written']}"
+        for item in record.get("instructions", [])
+        if not item.get("plugin")
+    ]
+    lines += [f"  failed: {' '.join(c['run'])}: {c['output'].strip()}" for c in failed]
+    lines += plan.notes
+    if "visible" in record:
+        lines.append(
+            "  verified: brain-wiki is listed"
+            if record["visible"]
+            else "  warning: brain-wiki is not listed yet"
+        )
+    lines.append(f"Undo with: brain connect {args.host} --uninstall")
+    emit(args, record, "\n".join(lines))
+    return 1 if failed else 0

brainwiki/cli/_cmd_import.py

@@ -0,0 +1,149 @@
+"""import."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.errors import NotFound, UsageError
+
+
+def import_(args: Any) -> int:
+    if args.from_host:
+        return _from_host(args)
+    if not args.path:
+        raise UsageError("give a folder or file to import, or --from HOST")
+    source = Path(args.path).expanduser()
+    if args.overlay:
+        return _overlay(args, source)
+    if args.into:
+        return _into(args, source)
+    if args.to_episodes:
+        return _to_episodes(args, source)
+    raise UsageError("choose a mode: --overlay, --into BRAIN, --to-episodes, or --from HOST")
+
+
+def _overlay(args: Any, source: Path) -> int:
+    from brainwiki.importer import overlay
+
+    if args.phase == 0:
+        if not args.apply:
+            from brainwiki.importer import survey
+
+            found = survey(source)
+            text = overlay.report(found, args.brain or source.resolve().name)
+            emit(
+                args,
+                found.to_json(),
+                text + "\nNothing changed. Run with --apply to adopt (phase 0).",
+            )
+            return 0
+        result = overlay.adopt(source, name=args.brain)
+        emit(
+            args,
+            result,
+            f"Adopted {result['root']} as brain {result['brain']!r}. Next: --phase 1, 2, 3 (each optional).",
+        )
+        return 0
+    from brainwiki.config import open_brain
+    from brainwiki.engine import Engine
+
+    with Engine(open_brain(source)) as engine:
+        record, diff = overlay.apply_phase(engine, args.phase, dry_run=not args.apply)
+    if not args.apply:
+        emit(
+            args,
+            {"diff": diff},
+            (diff or "Nothing to change.") + ("\n\nRun with --apply." if diff else ""),
+        )
+        return 0
+    if record is None:
+        emit(args, {"run": None}, "Nothing to change.")
+        return 0
+    emit(
+        args,
+        record.to_json(),
+        f"Phase {args.phase} applied ({record.run}); undo with brain undo {record.run}",
+    )
+    return 0
+
+
+def _into(args: Any, source: Path) -> int:
+    from brainwiki.engine import open_engine
+    from brainwiki.importer import plan_into, tidy_after_import
+    from brainwiki.lint import run_gate
+
+    with open_engine(args.into) as engine:
+        run, summary = plan_into(engine, source, topic=args.topic)
+        if not args.apply:
+            lines = [
+                f"Would copy {summary['files']} files into topics {', '.join(summary['topics'])}."
+            ]
+            lines.append(
+                f"Markdown links to files outside the source: {summary['unresolved_md_links']}"
+            )
+            emit(args, summary, "\n".join(lines) + "\nNothing changed. Run with --apply.")
+            return 0
+        record = run.commit(
+            check=run_gate(engine), log_lines=[f"- imported {summary['files']} files from {source}"]
+        )
+        tidy = [r.run for r in tidy_after_import(engine)]
+    text = f"Imported {summary['files']} files ({record.run})."
+    if tidy:
+        text += f" Then added hubs and refreshed AGENTS.md ({', '.join(tidy)}); undo all to revert."
+    emit(args, record.to_json() | summary | {"tidy_runs": tidy}, text)
+    return 0
+
+
+def _to_episodes(args: Any, source: Path) -> int:
+    from brainwiki.engine import open_engine
+    from brainwiki.importer import import_documents
+
+    if not source.exists():
+        raise NotFound(f"no such file or folder: {source}")
+    paths = sorted(source.rglob("*.md")) if source.is_dir() else [source]
+    with open_engine(args.brain, host=getattr(args, "as_host", None)) as engine:
+        results = import_documents(
+            engine,
+            paths,
+            base=source if source.is_dir() else source.parent,
+            origin="import",
+            inputs="external" if args.untrusted else "local",
+            agent=args.agent,
+            topic=args.topic,
+            dry_run=not args.apply,
+        )
+    failed = [r["file"] for r in results if r.get("error")]
+    written = len(results) - len(failed)
+    verb = "Would write" if not args.apply else "Wrote"
+    text = f"{verb} {written} episodes from {len(paths) - len(failed)} files."
+    if failed:
+        text += f" Could not read {len(failed)}: " + ", ".join(failed)
+    emit(args, results, text + ("" if args.apply else " Run with --apply."))
+    return 1 if failed else 0
+
+
+def _from_host(args: Any) -> int:
+    from brainwiki.engine import open_engine
+    from brainwiki.importer import import_documents, memory_files
+
+    override = Path(args.path).expanduser() if args.path else None
+    files = memory_files(args.from_host, override)
+    with open_engine(args.brain) as engine:
+        results = import_documents(
+            engine,
+            files,
+            base=Path.home(),
+            origin="agent",
+            inputs="unknown",
+            agent=args.from_host,
+            topic=args.topic,
+            dry_run=not args.apply,
+        )
+    lines = [f"{args.from_host}: {len(files)} memory files, {len(results)} episodes"]
+    lines += [f"  {f}" for f in files]
+    if not args.apply:
+        lines.append("Nothing changed. Run with --apply.")
+    emit(args, results, "\n".join(lines))
+    return 0

brainwiki/cli/_cmd_lint.py

@@ -0,0 +1,117 @@
+"""lint, report."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.engine import Engine, open_engine
+from brainwiki.errors import NotFound
+
+
+def _engine(args: Any) -> Engine:
+    return open_engine(args.brain, host=getattr(args, "as_host", None))
+
+
+def _codes(raw: str | None) -> list[str] | None:
+    return [c.strip().upper() for c in raw.split(",") if c.strip()] if raw else None
+
+
+def brain_paths(engine: Engine, raw: list[str]) -> list[str] | None:
+    """CLI paths (absolute, cwd-relative, or brain-relative) as brain-relative paths."""
+    if not raw:
+        return None
+    out = []
+    for item in raw:
+        candidate = Path(item) if Path(item).is_absolute() else Path.cwd() / item
+        try:
+            rel = candidate.resolve().relative_to(engine.brain.root).as_posix()
+        except ValueError:
+            rel = item.replace("\\", "/").strip("/")
+        out.append("" if rel == "." else rel)
+    return out
+
+
+def _changed_paths(engine: Engine) -> list[str]:
+    row = engine.db.execute("SELECT value FROM meta WHERE key='last_lint_ns'").fetchone()
+    since = int(row["value"]) if row else 0
+    return [
+        r["path"] for r in engine.db.execute("SELECT path FROM files WHERE mtime_ns > ?", (since,))
+    ]
+
+
+def _mark_linted(engine: Engine) -> None:
+    engine.db.execute(
+        "INSERT OR REPLACE INTO meta(key, value) VALUES ('last_lint_ns', ?)", (str(time.time_ns()),)
+    )
+
+
+def lint(args: Any) -> int:
+    from brainwiki.lint import lint as run_lint
+
+    with _engine(args) as engine:
+        if args.install_hook:
+            from brainwiki.lint import install_hook
+
+            target = install_hook(engine.brain.root)
+            emit(args, {"installed": str(target)}, f"Installed {target}")
+            return 0
+        paths = brain_paths(engine, args.paths)
+        for raw, rel in zip(args.paths or [], paths or [], strict=True):
+            if not (engine.brain.root / rel).exists():
+                raise NotFound(f"no such file or folder in the brain: {raw}")
+        select, ignore = _codes(args.select), _codes(args.ignore)
+        if args.fix:
+            from brainwiki.lint import fix
+
+            outcome = fix(
+                engine,
+                paths=paths,
+                profile=args.profile,
+                select=select,
+                ignore=ignore,
+                dry_run=args.dry_run,
+            )
+            if args.dry_run:
+                emit(
+                    args,
+                    {"fixes": [p.to_json() for p in outcome.applied], "diff": outcome.diff},
+                    outcome.diff or "Nothing to fix.",
+                )
+                return 0
+            data = outcome.remaining.to_json()
+            data["fixed"] = [p.to_json() for p in outcome.applied]
+            data["run"] = outcome.record.run if outcome.record else None
+            text = (
+                f"Fixed {len(outcome.applied)} problem(s) in {outcome.record.run} (undo: brain undo {outcome.record.run})\n"
+                if outcome.record
+                else "Nothing to fix.\n"
+            ) + outcome.remaining.format_text()
+            emit(args, data, text)
+            return 1 if outcome.remaining.errors else 0
+        staged = None
+        if args.staged:
+            from brainwiki.lint import staged_files
+
+            staged = staged_files(engine.brain.root)
+        elif args.changed:
+            engine.scan()
+            paths = _changed_paths(engine)
+        result = run_lint(
+            engine, paths=paths, profile=args.profile, select=select, ignore=ignore, staged=staged
+        )
+        if staged is None and (args.changed or paths is None):
+            _mark_linted(engine)
+        emit(args, result.to_json(), result.format_text())
+        return 1 if result.errors else 0
+
+
+def report(args: Any) -> int:
+    from brainwiki.lint import generate
+
+    with _engine(args) as engine:
+        written = generate(engine)
+    emit(args, {"written": written}, "\n".join(f"wrote {p}" for p in written))
+    return 0

brainwiki/cli/_cmd_read.py

@@ -0,0 +1,131 @@
+"""orient, search, read, neighbors, index."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.engine import open_engine
+from brainwiki.errors import UsageError
+
+
+def _engine(args: Any):
+    return open_engine(args.brain, host=getattr(args, "as_host", None))
+
+
+def orient(args: Any) -> int:
+    from brainwiki.index import orient as run
+
+    with _engine(args) as engine:
+        result = run(engine)
+    emit(args, result, result["text"])
+    return 0
+
+
+def search(args: Any) -> int:
+    from brainwiki.index import format_search_text
+    from brainwiki.index import search as run
+
+    include = {part.strip() for part in (args.include or "").split(",") if part.strip()}
+    with _engine(args) as engine:
+        result = run(
+            engine,
+            args.query,
+            limit=args.limit,
+            topics=args.topic,
+            types=args.types,
+            tags=args.tags,
+            where=_parse_where(args.where),
+            since=args.since,
+            until=args.until,
+            sort=args.sort,
+            cursor=args.cursor,
+            count_only=args.count,
+            facets=args.facets,
+            intent=args.intent,
+            include_episodes=True
+            if "episodes" in include
+            else (False if args.no_episodes else None),
+            include_archived="archived" in include,
+            include_archived_episodes="archived_episodes" in include,
+        )
+    if args.count and not args.json and not args.facets:
+        print(result["total"])
+        return 0
+    emit(args, result, format_search_text(result, "paths" if args.paths else "text"))
+    return 0
+
+
+def _parse_where(items: list[str]) -> dict[str, str]:
+    where = {}
+    for item in items or []:
+        key, sep, value = item.partition("=")
+        if not sep or not key.strip():
+            raise UsageError(f"--where takes KEY=VALUE, not {item!r}")
+        where[key.strip()] = value.strip()
+    return where
+
+
+def read(args: Any) -> int:
+    from brainwiki.index import format_read_text
+    from brainwiki.index import read as run
+
+    with _engine(args) as engine:
+        result = run(engine, args.target, mode=args.mode, section=args.section)
+    emit(args, result, format_read_text(result))
+    return 0
+
+
+def neighbors(args: Any) -> int:
+    from brainwiki.index import format_neighbors_text
+    from brainwiki.index import neighbors as run
+
+    with _engine(args) as engine:
+        result = run(
+            engine,
+            args.target,
+            relations=args.relations,
+            direction=args.direction,
+            depth=args.depth,
+            limit=args.limit,
+        )
+    text = (
+        "\n".join(n["path"] for n in result["nodes"][1:])
+        if args.paths
+        else format_neighbors_text(result)
+    )
+    emit(args, result, text)
+    return 0
+
+
+def index(args: Any) -> int:
+    with _engine(args) as engine:
+        stats = engine.rebuild() if args.rebuild else engine.scan(force=True)
+        counts = {
+            row["kind"]: row["c"]
+            for row in engine.db.execute("SELECT kind, COUNT(*) AS c FROM files GROUP BY kind")
+        }
+        edges = engine.db.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+        unresolved = engine.db.execute("SELECT COUNT(*) FROM edges WHERE other IS NULL").fetchone()[
+            0
+        ]
+    data = {
+        "files": counts,
+        "edges": edges,
+        "unresolved_links": unresolved,
+        "scan": {
+            "added": stats.added,
+            "changed": stats.changed,
+            "removed": stats.removed,
+            "seconds": round(stats.seconds, 3),
+        },
+    }
+    text = (
+        "Index "
+        + ("rebuilt" if args.rebuild else "up to date")
+        + f" in {stats.seconds:.2f}s: "
+        + ", ".join(f"{k}={v}" for k, v in sorted(counts.items()))
+        + f"; edges={edges} (unresolved {unresolved})"
+    )
+    emit(args, data, text)
+    return 0

brainwiki/cli/_cmd_runs.py

@@ -0,0 +1,66 @@
+"""runs, undo."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.engine import open_engine
+
+
+def runs(args: Any) -> int:
+    from brainwiki.runs import list_records, load_record
+
+    with open_engine(args.brain, host=getattr(args, "as_host", None)) as engine:
+        key = engine.brain.key
+        if args.action == "show":
+            record = load_record(key, args.run) if args.run else list_records(key)[0]
+            data = record.to_json()
+            lines = [
+                f"{record.run}  {record.kind}  {record.status}  {record.started}",
+                f"agent: {record.agent or 'owner'}"
+                + (f"  backend: {record.backend}" if record.backend else ""),
+            ]
+            if record.summary:
+                lines.append(record.summary)
+            for change in record.files:
+                if change.moved_to:
+                    lines.append(f"  {change.path} -> {change.moved_to}")
+                elif change.before is None:
+                    lines.append(f"  + {change.path}")
+                elif change.after is None:
+                    lines.append(f"  - {change.path}")
+                else:
+                    lines.append(f"  ~ {change.path}")
+            if record.git_commit:
+                lines.append(f"git: {record.git_commit[:12]}")
+            if record.git_error:
+                lines.append(f"git error: {record.git_error}")
+            if record.undone_by:
+                lines.append(f"undone by {record.undone_by}")
+            emit(args, data, "\n".join(lines))
+            return 0
+        records = list_records(key)
+        data = [
+            {
+                k: r.to_json()[k]
+                for k in ("run", "kind", "status", "started", "agent", "summary", "undone_by")
+            }
+            for r in records
+        ]
+        text = "\n".join(
+            f"{r.run}  {r.kind:<12} {r.status:<11} {r.started}  {r.summary}"
+            + (f"  (undone by {r.undone_by})" if r.undone_by else "")
+            for r in records
+        )
+        emit(args, data, text or "No runs on this device.")
+    return 0
+
+
+def undo(args: Any) -> int:
+    from brainwiki.runs import undo as run_undo
+
+    with open_engine(args.brain, host=getattr(args, "as_host", None)) as engine:
+        result = run_undo(engine, args.run, force=args.force, agent=getattr(args, "as_host", None))
+    emit(args, result.to_json(), f"{result.summary} ({result.run})")
+    return 0