diff --git a/.gitignore b/.gitignore index 53003a9..20bec76 100644 --- a/.gitignore +++ b/.gitignore @@ -82,3 +82,7 @@ mcp-arch.yaml # uv writes this as a side effect of `uv pip install`; the manifests # (requirements*.txt) are the declared dependency surface. uv.lock + +# Packaging output +build/ +*.egg-info/ diff --git a/CHANGELOG.md b/CHANGELOG.md index cf08a81..0e1c0be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,28 @@ All notable changes to the brain kernel. Versions correspond to shipped roadmap slices (`wiki/brain/roadmap.md` holds the full narrative; the ADR shelf holds the decisions). +## 0.31.2, 2026-10-25 +Published on PyPI as `tended`, so `uvx tended init my-wiki` creates a +working instance anywhere. +- The wheel carries the kernel manifest (every path in + `KERNEL_COPY_PATHS`, plus `sources/README.md` and `brain.config.yml`) + under `tended/kernel/` in the package, copied at build time by `setup.py`. The + top-level `tools` package is no longer shipped, so it cannot collide in + site-packages. Checkout use is unchanged. +- New `tended` command: `tended init [--org X]` births a full + instance from the bundled kernel, `tended --version` prints the version, + and any other verb says to run it inside an instance with + `python3 tools/brain.py `. The `brain` console script is gone; + `tools/brain` and `python3 tools/brain.py` remain. +- `init --full` now makes every copied file and directory writable by the + new owner, so an instance born from a read-only install (a wheel in + site-packages) can be edited and its seeded ADR filter can run. +- `init --full` recreates the UI's `ui/src/content/docs` link to `wiki/`, + which a wheel cannot carry, and the source package ships the kernel too + so the wheel builds from it. +- README leads with `uvx tended init my-wiki`; the clone route is the + contributor path. Nothing inside an instance is renamed. + ## 0.31.1, 2026-10-25 Final polish: documentation made to match the code, and defects that could mislead or hurt a user fixed. No new features. diff --git a/README.md b/README.md index 8292cba..fbde222 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,21 @@ running an LLM on a schedule. It's off by default; see ## Quickstart ```bash -git clone brain && cd brain +uvx tended init my-wiki # or: pipx run tended init my-wiki +cd my-wiki python3 tools/brain.py setup # idempotent bootstrap: env, config, hooks, timer, UI -brain # opens the app +tools/brain # opens the app +``` + +This project was called brain and is now published as `tended`. The +files inside an instance keep the old name (`tools/brain.py`, +`brain.config.yml`, the skills), so nothing already born needs to change. + +To work on the kernel itself, clone it instead: + +```bash +git clone https://github.com/misabegovic/tended.git && cd tended +python3 tools/brain.py setup ``` That's the whole surface. The app is the **rendered knowledge** — diff --git a/VERSION b/VERSION index f176c94..c415e1c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.31.1 +0.31.2 diff --git a/pyproject.toml b/pyproject.toml index 30aacb5..64b0350 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,11 +1,9 @@ -# Packaging for the brain kernel. The repo itself is the artifact — -# a brain lives as a checkout (or a born instance) because the CLI -# resolves everything relative to the repository root. This manifest -# makes `pip install -e .` provide the `brain` console script per -# checkout (editable installs only, by design), and gives releases -# canonical metadata. +# Packaging for tended (formerly the brain kernel). The wheel carries +# the kernel manifest as data inside the package (copied at build time +# by setup.py) and a `tended` command that births an instance from it. +# Inside a checkout or an instance, tools/brain.py is run directly. [project] -name = "brain-kernel" +name = "tended" description = "An LLM-maintained knowledge substrate: governed markdown wiki, queue-and-tend self-maintenance, connectors, composable SQL views, MCP serving, and a chat-first workbench." readme = "README.md" license = "MIT" @@ -20,10 +18,10 @@ cluster = ["scikit-learn"] full = ["tiktoken", "datasette", "pytest", "scikit-learn"] [project.scripts] -brain = "tools.brain:main" +tended = "tended.cli:main" [tool.setuptools] -packages = ["tools"] +packages = ["tended"] [tool.setuptools.dynamic] version = { file = "VERSION" } diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..6ce625e --- /dev/null +++ b/setup.py @@ -0,0 +1,59 @@ +"""Bundles the kernel manifest into the wheel inside the tended package.""" + +import ast +import os +import shutil +from pathlib import Path + +from setuptools import setup +from setuptools.command.build_py import build_py +from setuptools.command.egg_info import egg_info + +ROOT = Path(__file__).resolve().parent +EXTRA_PATHS = ["sources/README.md", "brain.config.yml"] +SKIP_NAMES = ("node_modules", "__pycache__", ".build-cache", "dist", + ".pytest_cache") +SKIP = shutil.ignore_patterns(*SKIP_NAMES, "*.pyc") + + +def manifest() -> list[str]: + tree = ast.parse((ROOT / "tools" / "brain.py").read_text()) + for node in tree.body: + if isinstance(node, ast.Assign) and any( + getattr(t, "id", "") == "KERNEL_COPY_PATHS" + for t in node.targets): + return list(ast.literal_eval(node.value)) + raise SystemExit("KERNEL_COPY_PATHS not found in tools/brain.py") + + +class BuildPy(build_py): + def run(self): + super().run() + dest = Path(self.build_lib) / "tended" / "kernel" + for rel in manifest() + EXTRA_PATHS: + src, dst = ROOT / rel, dest / rel + dst.parent.mkdir(parents=True, exist_ok=True) + if src.is_dir(): + shutil.rmtree(dst, ignore_errors=True) + shutil.copytree(src, dst, symlinks=True, ignore=SKIP) + else: + shutil.copyfile(src, dst) + + +class EggInfo(egg_info): + def find_sources(self): + super().find_sources() + for rel in manifest() + EXTRA_PATHS + ["setup.py"]: + src = ROOT / rel + if src.is_file(): + self.filelist.append(rel) + continue + for dirpath, dirnames, filenames in os.walk(src): + dirnames[:] = [d for d in dirnames if d not in SKIP_NAMES] + for name in filenames: + if not name.endswith(".pyc"): + self.filelist.append( + str(Path(dirpath, name).relative_to(ROOT))) + + +setup(cmdclass={"build_py": BuildPy, "egg_info": EggInfo}) diff --git a/tended/__init__.py b/tended/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tended/cli.py b/tended/cli.py new file mode 100644 index 0000000..7cf6a66 --- /dev/null +++ b/tended/cli.py @@ -0,0 +1,68 @@ +"""The `tended` command: births an instance from the bundled kernel.""" + +from __future__ import annotations + +import argparse +import os +import subprocess +import sys +from pathlib import Path + +HERE = Path(__file__).resolve().parent + + +def kernel_root() -> Path: + bundled = HERE / "kernel" + if (bundled / "tools" / "brain.py").exists(): + return bundled + checkout = HERE.parent + if (checkout / "tools" / "brain.py").exists(): + return checkout + raise SystemExit("tended: no kernel found next to this package") + + +def version() -> str: + return (kernel_root() / "VERSION").read_text().strip() + + +def init(args: argparse.Namespace) -> int: + root = kernel_root() + cmd = [sys.executable, str(root / "tools" / "brain.py"), "init", + args.path, "--full"] + if args.org: + cmd += ["--org", args.org] + if args.force: + cmd.append("--force") + env = {**os.environ, "BRAIN_DIR": str(root), "PYTHONDONTWRITEBYTECODE": "1"} + return subprocess.run(cmd, env=env).returncode + + +def main(argv: list[str] | None = None) -> int: + argv = list(sys.argv[1:] if argv is None else argv) + parser = argparse.ArgumentParser( + prog="tended", + description="Birth a tended knowledge base. Everything else runs " + "inside the instance with python3 tools/brain.py.") + parser.add_argument("--version", action="store_true") + sub = parser.add_subparsers(dest="verb") + p = sub.add_parser("init", help="create a full instance in ") + p.add_argument("path") + p.add_argument("--org", default="") + p.add_argument("--force", action="store_true") + if argv and argv[0] not in ("init", "--version", "-h", "--help"): + print(f"tended only creates instances. Run `{argv[0]}` inside an " + f"instance with: python3 tools/brain.py {argv[0]}", + file=sys.stderr) + return 2 + args = parser.parse_args(argv) + if args.version: + print(f"tended {version()}") + return 0 + if args.verb == "init": + return init(args) + parser.print_help() + return 2 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_kernel_mechanisms.py b/tests/test_kernel_mechanisms.py index 5b92b2c..1e9bc35 100644 --- a/tests/test_kernel_mechanisms.py +++ b/tests/test_kernel_mechanisms.py @@ -290,3 +290,57 @@ def test_internal_refs_scans_ui_source_strings(): "internal-refs missed a dangling path in ui/src source") finally: rogue.unlink() + + +# ---------- tended packaging ---------------------------------------------- + +def test_birth_from_read_only_kernel_is_writable(tmp_path): + """A read-only source (an installed wheel) births an owned instance.""" + import os + import shutil + import subprocess + kernel = tmp_path / "kernel" + skip = shutil.ignore_patterns("node_modules", "__pycache__", "*.pyc") + for rel in [*brain.KERNEL_COPY_PATHS, "sources/README.md", + "brain.config.yml"]: + src, dst = REPO / rel, kernel / rel + dst.parent.mkdir(parents=True, exist_ok=True) + if src.is_dir(): + shutil.copytree(src, dst, symlinks=True, ignore=skip) + else: + shutil.copyfile(src, dst) + (kernel / "ui" / "src" / "content" / "docs").unlink() + for p in [kernel, *kernel.rglob("*")]: + if not p.is_symlink(): + p.chmod(p.stat().st_mode & ~0o222) + target = tmp_path / "instance" + env = {**os.environ, "BRAIN_DIR": str(kernel)} + try: + proc = subprocess.run( + [sys.executable, str(kernel / "tools" / "brain.py"), "init", + str(target), "--full", "--org", "T"], + env=env, capture_output=True, text=True, timeout=180) + assert proc.returncode == 0, proc.stderr[:800] + for p in (target / "tools" / "brain.py", + target / "wiki" / "brain" / "adrs", + target / "sources" / "README.md"): + assert p.stat().st_mode & 0o200, f"not writable: {p}" + docs = target / "ui" / "src" / "content" / "docs" + assert docs.is_symlink() and docs.resolve() == (target / "wiki").resolve() + finally: + for p in [kernel, *kernel.rglob("*")]: + if not p.is_symlink(): + p.chmod(p.stat().st_mode | 0o700) + + +def test_tended_command_refuses_other_verbs(): + import subprocess + run = lambda *a: subprocess.run( + [sys.executable, "-m", "tended.cli", *a], cwd=REPO, + capture_output=True, text=True) + version = run("--version") + assert version.returncode == 0 + assert (REPO / "VERSION").read_text().strip() in version.stdout + other = run("search", "x") + assert other.returncode != 0 + assert "python3 tools/brain.py search" in other.stderr diff --git a/tools/brain.py b/tools/brain.py index 1db722e..e7f1b46 100755 --- a/tools/brain.py +++ b/tools/brain.py @@ -9233,6 +9233,16 @@ def cmd_schedule(args) -> int: ] +def _make_owner_writable(path: Path) -> None: + """Copies keep the source's modes; a read-only source (an installed + package) would otherwise birth an instance its owner cannot edit.""" + paths = [path] + if path.is_dir() and not path.is_symlink(): + paths += [p for p in path.rglob("*") if not p.is_symlink()] + for p in paths: + p.chmod(p.stat().st_mode | 0o200 | (0o100 if p.is_dir() else 0)) + + def _init_full(target: Path, org: str) -> int: """Birth a working instance: manifest copy + fresh scaffold.""" src_root = REPO @@ -9253,6 +9263,7 @@ def _init_full(target: Path, org: str) -> int: "dist", "*.pyc", ".pytest_cache")) else: shutil.copy2(src, dst) + _make_owner_writable(dst) # Drop the brain's own initiative children from the seeded ADR trail: # an ADR carrying parent_epic dangles without its epic (intentionally @@ -9266,9 +9277,18 @@ def _init_full(target: Path, org: str) -> int: p.unlink() (target / "CLAUDE.md").symlink_to("AGENTS.md") + # A wheel cannot carry the UI's link to the wiki, so a kernel installed + # from one arrives without it (or with the link followed into a copy). + docs = target / "ui" / "src" / "content" / "docs" + if not docs.is_symlink(): + if docs.exists(): + shutil.rmtree(docs) + docs.parent.mkdir(parents=True, exist_ok=True) + docs.symlink_to(Path("..") / ".." / ".." / "wiki") (target / "sources").mkdir(exist_ok=True) shutil.copy2(src_root / "sources" / "README.md", target / "sources" / "README.md") + _make_owner_writable(target / "sources" / "README.md") (target / "log").mkdir(exist_ok=True) (target / "log" / "log.md").write_text("") for d in ("_views", "_archive", "_overlaps", "_state",