aidos 0.0.1__tar.gz

aidos-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yingding Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aidos-0.0.1/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include projectdescription.md
+include requirements.txt
+
+recursive-include src/aidos *.py
+
+recursive-exclude src/aidos/graphify-out *
+recursive-exclude src/aidos __pycache__ *.pyc *.pyo
+
+prune tests
+prune scripts
+prune docs
+prune config
+prune output

aidos-0.0.1/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: aidos
+Version: 0.0.1
+Summary: aidos (AI Diary Operating System) — the control-plane CLI for an agentic harness: roadmap index, knowledge-graph reindex, and module setup.
+Author: Yingding Wang
+License-Expression: MIT
+Keywords: aidos,ai-diary,harness,control-plane,knowledge-graph,roadmap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.15.1
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27.1; extra == "mcp"
+Dynamic: license-file
+
+# aidos
+
+**AI diary OS** — the control-plane CLI for an agentic harness. Index your roadmaps, keep knowledge graphs fresh, and stand up new modules, all from one command.
+
+## What it does
+
+`aidos` is the operations layer that sits *above* a multi-module workspace and manages the shared machinery your agent depends on:
+
+- **Roadmap index** — parse a roadmap markdown into identified items (stable UUIDs), classify them done / active / deferred, and build a SQLite **FTS5** keyword index for fast search. The markdown stays the source of truth; the index is derived.
+- **Graph reindex** — discover every subproject's knowledge graphs, report freshness, and rebuild them in the correct virtualenv. It never kills your MCP servers — it reports which ones need a restart.
+- **Module setup** — a reproducible recipe (and script) to make a new Python module a first-class citizen: its own venv, its own code + docs graphs, and wiring into the shared portal.
+
+It is **CLI-first**: all logic lives behind plain functions, so it is testable and scriptable without a server. A future control **MCP** wraps the same CLI.
+
+The name is a nod to [`aidiary`](https://pypi.org/project/aidiary/) (the *AI diary* memory system): `aidos` is the **OS** layer around it.
+
+## Install
+
+Requires: Python 3.12+
+
+```bash
+pip install aidos
+```
+
+Building a module's own knowledge graphs additionally uses `aidiary[graphs]` (installed editable in dev):
+
+```bash
+pip install "aidiary[graphs]"
+```
+
+## Quick start
+
+### 1. Check graph freshness across the workspace
+
+```bash
+aidos status
+```
+
+Lists each subproject's graph layers (code / docs / …) with a ✓ fresh / ⚠ stale / ✗ missing badge based on `graph.json` mtime vs. newest source.
+
+### 2. Index a roadmap and search it
+
+```bash
+aidos roadmap index path/to/ProjectRoadmap.md
+aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db
+```
+
+`index` assigns a stable UUID to every item and writes a SQLite FTS5 index + a JSON sidecar. `search` is instant keyword retrieval — no embeddings, no LLM.
+
+### 3. Preview a done / active split (non-destructive)
+
+```bash
+aidos roadmap split path/to/ProjectRoadmap.md
+```
+
+Writes `*-archive.md` (done) and `*-active.md` (active + deferred) previews. **The original file is never modified** — you review first.
+
+### 4. Rebuild knowledge graphs
+
+```bash
+aidos reindex --dry-run          # show what would rebuild
+aidos reindex --subproject aidos # rebuild one subproject's code graph
+```
+
+Any rebuilt layer is reported as `restart_required` — restart those MCP servers through your editor (or your restart script), never by killing the process.
+
+## Directory layout
+
+```
+my-module/
+├── pyproject.toml
+├── config/graphs.toml        # graphs.code (src/, ast) + graphs.docs (docs/, semantic)
+├── src/<pkg>/                # your package
+├── docs/                     # concept docs (feed the docs graph)
+└── output/                   # generated artifacts
+    ├── aidos/                # roadmap index db + json sidecar
+    └── graphs/{code,docs}/   # graph.json + graph.html
+```
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `aidos status` | Report knowledge-graph freshness across subprojects |
+| `aidos roadmap index <file>` | Build the SQLite FTS5 search index for a roadmap |
+| `aidos roadmap search <query> --db <db>` | Keyword-search the index |
+| `aidos roadmap split <file>` | Non-destructive done / active split preview |
+| `aidos reindex [--subproject N] [--docs] [--dry-run]` | Rebuild per-subproject graphs |
+
+## Design principles
+
+- **Markdown / files stay the source of truth** — every index, db, and graph is a *derived* artifact. Producers and consumers connect via files on disk, not imports.
+- **Keyword over embeddings** — on a few-hundred-item corpus, SQLite FTS5 is instant and sufficient; vector search is deferred until the data demands it.
+- **Never kill a stdio MCP server** — reindex reports `restart_required`; it does not respawn processes.
+
+## What's new
+
+### 0.0.1
+
+**First cut — the Developer-Control plane CLI**
+
+- **`roadmap`** — `index` (parse → stable UUIDs → done/active/deferred → SQLite FTS5 + JSON sidecar), `search` (FTS5 keyword), `split` (non-destructive done/active preview).
+- **`reindex`** — discover subproject graphs, report freshness, rebuild via each subproject's `aidiary-graphs`; reports `restart_required` (never kills MCP servers).
+- **`status`** — workspace-wide graph freshness.
+- **Reproducible module setup** — idempotent `setup.sh` (venv + editable installs + graphs) and a documented "make a module a first-class harness citizen" guide.
+- **Typer CLI**, stdlib-only core (plus Typer); builds to sdist + wheel.

aidos-0.0.1/README.md

@@ -0,0 +1,62 @@
+# aidos
+
+> **aidos** = **AI diary OS** — the control-plane CLI for an agentic harness. Roadmap index, knowledge-graph reindex, and module setup. CLI-first; a control MCP wraps the CLI.
+
+This is the **Developer-Control plane** of the harness control plane (see [ArchitectureReview-HarnessEstate-2026-06-24.md](../ArchitectureReview-HarnessEstate-2026-06-24.md) §5). It consolidates ad-hoc harness administration into one stdlib-only package. Roadmap: [#24](../ProjectRoadmap.md).
+
+## 📚 Contents
+
+- [📝 Overview](#-overview)
+- [🚀 Get Started](#-get-started)
+- [📦 Commands](#-commands)
+- [🤝 Author](#-author)
+- [📄 License](#-license)
+
+## 📝 Overview
+
+| Module | Responsibility |
+|--------|----------------|
+| `roadmap_tool` | Parse a roadmap markdown → stable per-item UUIDs → classify done/active/deferred → SQLite FTS5 search index → **non-destructive** done/active split preview |
+| `reindex` | Discover per-subproject knowledge graphs, report freshness, rebuild in each subproject's venv (never kills MCP servers — reports `restart_required`) |
+| `cli` | `aidos <command>` dispatch |
+
+**Design rules:** markdown stays the source of truth (git-native); the index is a derived artifact. Keyword (FTS5) search only — embeddings deferred (keyword wins on a few-hundred-item corpus). Never `pkill` a stdio MCP server.
+
+## 🚀 Get Started
+
+Run without installing:
+
+```bash
+python aidos/src/aidos/cli.py status
+```
+
+Or install editable for the `aidos` command:
+
+```bash
+pip install -e aidos
+aidos status
+```
+
+## 📦 Commands
+
+```bash
+# Roadmap: index, search, non-destructive split preview
+aidos roadmap index copilot-memory/ProjectRoadmap.md
+aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db
+aidos roadmap split copilot-memory/ProjectRoadmap.md   # writes *-archive.md + *-active.md previews
+
+# Graphs: freshness + rebuild
+aidos status
+aidos reindex --dry-run
+aidos reindex --subproject copilot-memory
+```
+
+`reindex` reports `restart_required` for any rebuilt layer — restart those MCP servers via VS Code (MCP: Restart) or `./restart-mcps.sh`, never by killing the process.
+
+## 🤝 Author
+
+**Yingding Wang**
+
+## 📄 License
+
+[MIT](../LICENSE) — © 2026 Yingding Wang

aidos-0.0.1/projectdescription.md

@@ -0,0 +1,106 @@
+# aidos
+
+**AI diary OS** — the control-plane CLI for an agentic harness. Index your roadmaps, keep knowledge graphs fresh, and stand up new modules, all from one command.
+
+## What it does
+
+`aidos` is the operations layer that sits *above* a multi-module workspace and manages the shared machinery your agent depends on:
+
+- **Roadmap index** — parse a roadmap markdown into identified items (stable UUIDs), classify them done / active / deferred, and build a SQLite **FTS5** keyword index for fast search. The markdown stays the source of truth; the index is derived.
+- **Graph reindex** — discover every subproject's knowledge graphs, report freshness, and rebuild them in the correct virtualenv. It never kills your MCP servers — it reports which ones need a restart.
+- **Module setup** — a reproducible recipe (and script) to make a new Python module a first-class citizen: its own venv, its own code + docs graphs, and wiring into the shared portal.
+
+It is **CLI-first**: all logic lives behind plain functions, so it is testable and scriptable without a server. A future control **MCP** wraps the same CLI.
+
+The name is a nod to [`aidiary`](https://pypi.org/project/aidiary/) (the *AI diary* memory system): `aidos` is the **OS** layer around it.
+
+## Install
+
+Requires: Python 3.12+
+
+```bash
+pip install aidos
+```
+
+Building a module's own knowledge graphs additionally uses `aidiary[graphs]` (installed editable in dev):
+
+```bash
+pip install "aidiary[graphs]"
+```
+
+## Quick start
+
+### 1. Check graph freshness across the workspace
+
+```bash
+aidos status
+```
+
+Lists each subproject's graph layers (code / docs / …) with a ✓ fresh / ⚠ stale / ✗ missing badge based on `graph.json` mtime vs. newest source.
+
+### 2. Index a roadmap and search it
+
+```bash
+aidos roadmap index path/to/ProjectRoadmap.md
+aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db
+```
+
+`index` assigns a stable UUID to every item and writes a SQLite FTS5 index + a JSON sidecar. `search` is instant keyword retrieval — no embeddings, no LLM.
+
+### 3. Preview a done / active split (non-destructive)
+
+```bash
+aidos roadmap split path/to/ProjectRoadmap.md
+```
+
+Writes `*-archive.md` (done) and `*-active.md` (active + deferred) previews. **The original file is never modified** — you review first.
+
+### 4. Rebuild knowledge graphs
+
+```bash
+aidos reindex --dry-run          # show what would rebuild
+aidos reindex --subproject aidos # rebuild one subproject's code graph
+```
+
+Any rebuilt layer is reported as `restart_required` — restart those MCP servers through your editor (or your restart script), never by killing the process.
+
+## Directory layout
+
+```
+my-module/
+├── pyproject.toml
+├── config/graphs.toml        # graphs.code (src/, ast) + graphs.docs (docs/, semantic)
+├── src/<pkg>/                # your package
+├── docs/                     # concept docs (feed the docs graph)
+└── output/                   # generated artifacts
+    ├── aidos/                # roadmap index db + json sidecar
+    └── graphs/{code,docs}/   # graph.json + graph.html
+```
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `aidos status` | Report knowledge-graph freshness across subprojects |
+| `aidos roadmap index <file>` | Build the SQLite FTS5 search index for a roadmap |
+| `aidos roadmap search <query> --db <db>` | Keyword-search the index |
+| `aidos roadmap split <file>` | Non-destructive done / active split preview |
+| `aidos reindex [--subproject N] [--docs] [--dry-run]` | Rebuild per-subproject graphs |
+
+## Design principles
+
+- **Markdown / files stay the source of truth** — every index, db, and graph is a *derived* artifact. Producers and consumers connect via files on disk, not imports.
+- **Keyword over embeddings** — on a few-hundred-item corpus, SQLite FTS5 is instant and sufficient; vector search is deferred until the data demands it.
+- **Never kill a stdio MCP server** — reindex reports `restart_required`; it does not respawn processes.
+
+## What's new
+
+### 0.0.1
+
+**First cut — the Developer-Control plane CLI**
+
+- **`roadmap`** — `index` (parse → stable UUIDs → done/active/deferred → SQLite FTS5 + JSON sidecar), `search` (FTS5 keyword), `split` (non-destructive done/active preview).
+- **`reindex`** — discover subproject graphs, report freshness, rebuild via each subproject's `aidiary-graphs`; reports `restart_required` (never kills MCP servers).
+- **`status`** — workspace-wide graph freshness.
+- **Reproducible module setup** — idempotent `setup.sh` (venv + editable installs + graphs) and a documented "make a module a first-class harness citizen" guide.
+- **Typer CLI**, stdlib-only core (plus Typer); builds to sdist + wheel.

aidos-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aidos"
+version = "0.0.1"
+description = "aidos (AI Diary Operating System) — the control-plane CLI for an agentic harness: roadmap index, knowledge-graph reindex, and module setup."
+readme = "projectdescription.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yingding Wang" }]
+keywords = ["aidos", "ai-diary", "harness", "control-plane", "knowledge-graph", "roadmap"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+# Base tier is stdlib-only except the CLI framework. Keeps the control plane
+# lightweight and installable everywhere. Version pins live in requirements.txt.
+dependencies = ["typer>=0.15.1"]
+
+[project.optional-dependencies]
+# Roadmap #24 Phase 2 — control MCP wraps the CLI.
+mcp = ["mcp>=1.27.1"]
+
+[project.scripts]
+aidos = "aidos.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["aidos*"]

aidos-0.0.1/requirements.txt

@@ -0,0 +1,4 @@
+# aidos production dependencies (source of truth for version pins).
+# Base tooling for the CLI. Keep this list minimal — the control plane should
+# stay lightweight and installable everywhere.
+typer>=0.26.7

aidos-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aidos-0.0.1/src/aidos/__init__.py

@@ -0,0 +1,27 @@
+"""aidos (AI diary OS) — workspace control-plane tooling for the harness.
+
+This package is the **Developer-Control plane** of the harness control plane
+(see workspace ``ArchitectureReview-HarnessEstate-2026-06-24.md`` §5). It
+consolidates ad-hoc harness administration into a CLI-first, stdlib-only
+package. A future control MCP (Roadmap #24 Phase 2) wraps this same CLI — the
+CLI is the source of truth so the logic is testable without MCP.
+
+Exports / submodules:
+
+- :mod:`aidos.roadmap_tool` — parse a roadmap markdown into identified
+  items (stable UUIDs), classify done/active/deferred, build a SQLite FTS5
+  search index, and produce a **non-destructive** done/active split preview.
+- :mod:`aidos.reindex` — discover per-subproject knowledge graphs,
+  report freshness/status, and orchestrate rebuilds in each subproject's venv
+  (never kills MCP servers — reports ``restart_required`` instead).
+- :mod:`aidos.cli` — argparse dispatch (``aidos <command>``).
+
+Consumers: the workspace operator (CLI) today; the ``aidos`` control MCP
+(Phase 2) tomorrow.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.0.1"

aidos-0.0.1/src/aidos/cli.py

@@ -0,0 +1,168 @@
+"""aidos command-line interface (Typer).
+
+Usage::
+
+    aidos roadmap index <file> [--db PATH]
+    aidos roadmap search <query> [--db PATH] [-n N]
+    aidos roadmap split <file> [--out-dir DIR]      # non-destructive preview
+    aidos status                                     # graph freshness
+    aidos reindex [--subproject NAME] [--docs] [--dry-run]
+
+The CLI is the source of truth; the future control MCP (Roadmap #24 Phase 2)
+wraps these same functions.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__, reindex as _reindex, roadmap_tool as _rt
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Workspace control-plane tooling for the harness.",
+)
+roadmap_app = typer.Typer(no_args_is_help=True, help="Parse / index / search / split a roadmap file.")
+app.add_typer(roadmap_app, name="roadmap")
+
+
+def _version_cb(value: bool) -> None:
+    if value:
+        typer.echo(f"aidos {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    _version: bool = typer.Option(
+        False, "--version", callback=_version_cb, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    """Workspace control-plane tooling for the harness."""
+
+
+def _find_root(start: Optional[Path] = None) -> Path:
+    """Walk up to the workspace root (marked by .vscode/ or .git/)."""
+    here = (start or Path.cwd()).resolve()
+    for cand in (here, *here.parents):
+        if (cand / ".vscode").is_dir() or (cand / ".git").is_dir():
+            return cand
+    return here
+
+
+def _default_db(root: Path, file: Path) -> Path:
+    return root / "output" / "aidos" / f"{file.stem}.db"
+
+
+@roadmap_app.command("index")
+def roadmap_index(
+    file: Path = typer.Argument(..., help="Roadmap markdown file to index."),
+    db: Optional[Path] = typer.Option(None, help="Output SQLite path (default under output/aidos/)."),
+) -> None:
+    """Parse a roadmap and build the SQLite FTS5 search index."""
+    root = _find_root()
+    file = file.resolve()
+    items = _rt.parse_roadmap(file)
+    db_path = db.resolve() if db else _default_db(root, file)
+    _rt.build_index(items, db_path)
+    counts = _rt.summarize(items)
+    typer.echo(f"Indexed {counts['total']} items from {file.name} → {db_path}")
+    typer.echo(f"  done={counts['done']}  active={counts['active']}  deferred={counts['deferred']}")
+    typer.echo(f"  sidecar: {db_path.with_suffix('.json')}")
+
+
+@roadmap_app.command("search")
+def roadmap_search(
+    query: str = typer.Argument(..., help="FTS5 keyword query."),
+    db: Optional[Path] = typer.Option(None, help="Index SQLite path to search."),
+    n: int = typer.Option(20, "-n", help="Max results."),
+) -> None:
+    """Keyword-search the roadmap index."""
+    if db is None or not db.exists():
+        typer.echo("error: no index db found; run 'aidos roadmap index <file>' first "
+                   "or pass --db", err=True)
+        raise typer.Exit(2)
+    rows = _rt.search_index(db, query, n)
+    if not rows:
+        typer.echo("(no matches)")
+        return
+    for r in rows:
+        typer.echo(f"  [{r['status']:8}] {r['key']:8} {r['title']}")
+
+
+@roadmap_app.command("split")
+def roadmap_split(
+    file: Path = typer.Argument(..., help="Roadmap markdown file to split."),
+    out_dir: Optional[Path] = typer.Option(None, help="Preview output dir."),
+) -> None:
+    """Write a NON-DESTRUCTIVE done/active split preview (original untouched)."""
+    root = _find_root()
+    file = file.resolve()
+    items = _rt.parse_roadmap(file)
+    target = out_dir.resolve() if out_dir else root / "output" / "aidos" / "split-preview"
+    written = _rt.split_preview(file, items, target)
+    counts = _rt.summarize(items)
+    typer.echo(f"Split preview (non-destructive) for {file.name}:")
+    typer.echo(f"  archive (done={counts['done']}): {written['archive']}")
+    typer.echo(f"  active  (active+deferred={counts['active'] + counts['deferred']}): {written['active']}")
+    typer.echo("  original file was NOT modified.")
+
+
+@app.command()
+def status() -> None:
+    """Report knowledge-graph freshness across subprojects."""
+    root = _find_root()
+    rows = _reindex.graph_status(root)
+    if not rows:
+        typer.echo("(no subprojects with output/graphs/ found)")
+        return
+    typer.echo(f"Graph status @ {root.name} ({datetime.now(timezone.utc):%Y-%m-%dT%H:%MZ})")
+    cur = None
+    for ls in rows:
+        if ls.subproject != cur:
+            cur = ls.subproject
+            typer.echo(f"\n{ls.subproject}")
+        mark = "✗ missing" if not ls.exists else ("⚠ stale" if ls.stale else "✓ fresh")
+        when = (datetime.fromtimestamp(ls.mtime, timezone.utc).strftime("%Y-%m-%d %H:%M")
+                if ls.mtime else "—")
+        typer.echo(f"  {ls.layer:10} {mark:10} graph.json {when}")
+
+
+@app.command()
+def reindex(
+    subproject: Optional[str] = typer.Option(None, help="Only this subproject."),
+    docs: bool = typer.Option(False, help="Rebuild docs (heavier) instead of code-only."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would run, don't execute."),
+) -> None:
+    """Rebuild per-subproject knowledge graphs (never restarts MCP servers)."""
+    root = _find_root()
+    results = _reindex.reindex(root, subproject=subproject, code_only=not docs, dry_run=dry_run)
+    if not results:
+        typer.echo("(nothing to reindex)")
+        return
+    failed = False
+    for r in results:
+        head = "would run" if not r.ran else f"rc={r.returncode}"
+        typer.echo(f"{r.subproject}: {head} — {' '.join(r.command)}")
+        if r.note:
+            typer.echo(f"    {r.note}")
+        if r.restart_required:
+            typer.echo(f"    restart_required: {', '.join(r.restart_required)} "
+                       f"(restart via VS Code MCP or ./restart-mcps.sh — never pkill)")
+        if r.ran and r.returncode:
+            failed = True
+    if failed:
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

aidos-0.0.1/src/aidos/reindex.py

@@ -0,0 +1,139 @@
+"""reindex — discover and rebuild per-subproject knowledge graphs.
+
+Part of the harness control plane (Roadmap #24 Phase 1). Orchestrates the
+graph-rebuild ritual that is otherwise a manual per-subproject ``cd`` +
+``aidiary-graphs`` dance.
+
+Hard constraint: this module **never** kills or restarts MCP servers
+(externally killing a stdio MCP server is a recorded anti-pattern — VS Code
+marks it permanently failed). A rebuild that changes ``graph.json`` reports
+``restart_required`` for the affected layers; the operator (or, later, the
+control MCP) triggers the sanctioned restart via VS Code / ``restart-mcps.sh``.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Source directory that feeds each graph layer (for staleness comparison).
+_LAYER_SOURCE = {
+    "code": ("src",),
+    "docs": ("docs",),
+    "frontend": ("dashboard/src", "src"),
+    "mem": ("memories",),
+}
+_SOURCE_SUFFIXES = {".py", ".ts", ".tsx", ".js", ".jsx", ".md"}
+
+
+@dataclass
+class Subproject:
+    name: str
+    path: Path
+    venv_python: Path
+    graphs_dir: Path
+
+    @property
+    def has_graphs(self) -> bool:
+        return self.graphs_dir.is_dir()
+
+
+@dataclass
+class LayerStatus:
+    subproject: str
+    layer: str
+    graph_json: Path
+    exists: bool
+    mtime: float | None
+    stale: bool
+    newest_source: float | None = None
+
+
+@dataclass
+class ReindexResult:
+    subproject: str
+    command: list[str]
+    ran: bool
+    returncode: int | None = None
+    restart_required: list[str] = field(default_factory=list)
+    note: str = ""
+
+
+def discover_subprojects(root: Path) -> list[Subproject]:
+    """Find subprojects with a venv and an ``output/graphs/`` tree."""
+    found: list[Subproject] = []
+    for child in sorted(p for p in root.iterdir() if p.is_dir()):
+        venv_py = child / ".venv" / "bin" / "python"
+        graphs = child / "output" / "graphs"
+        if venv_py.exists() and graphs.is_dir():
+            found.append(Subproject(child.name, child, venv_py, graphs))
+    return found
+
+
+def _newest_source_mtime(base: Path, layer: str) -> float | None:
+    newest: float | None = None
+    for rel in _LAYER_SOURCE.get(layer, ()):
+        src = base / rel
+        if not src.is_dir():
+            continue
+        for f in src.rglob("*"):
+            if f.is_file() and f.suffix in _SOURCE_SUFFIXES:
+                m = f.stat().st_mtime
+                if newest is None or m > newest:
+                    newest = m
+    return newest
+
+
+def graph_status(root: Path) -> list[LayerStatus]:
+    """Report each (subproject, layer) graph: existence, mtime, staleness."""
+    out: list[LayerStatus] = []
+    for sp in discover_subprojects(root):
+        for layer_dir in sorted(p for p in sp.graphs_dir.iterdir() if p.is_dir()):
+            layer = layer_dir.name
+            gj = layer_dir / "graph.json"
+            # Only report real graph layers (a directory that holds a graph.json).
+            # Sibling artifact dirs (analytics/, cache/) and backups are skipped.
+            if not gj.exists():
+                continue
+            mtime = gj.stat().st_mtime
+            newest = _newest_source_mtime(sp.path, layer)
+            stale = bool(newest is not None and newest > (mtime or 0))
+            out.append(LayerStatus(sp.name, layer, gj, True, mtime, stale, newest))
+    return out
+
+
+def reindex(
+    root: Path,
+    subproject: str | None = None,
+    code_only: bool = True,
+    dry_run: bool = False,
+) -> list[ReindexResult]:
+    """Rebuild graphs by invoking each subproject's own ``aidiary-graphs``.
+
+    ``code_only`` runs the instant AST rebuild (no LLM). Docs rebuilds are
+    heavier and are left to an explicit ``--docs`` run (not yet wired).
+    """
+    results: list[ReindexResult] = []
+    for sp in discover_subprojects(root):
+        if subproject and sp.name != subproject:
+            continue
+        flag = "--code-only" if code_only else "--build-only"
+        cmd = [str(sp.venv_python), "-m", "aidiary.graphs.cli", flag]
+        # Layers that would be affected (for restart_required reporting).
+        affected = [
+            ls.layer for ls in graph_status(root)
+            if ls.subproject == sp.name and (not code_only or ls.layer in ("code", "frontend"))
+        ]
+        if dry_run:
+            results.append(ReindexResult(sp.name, cmd, ran=False,
+                                         restart_required=affected,
+                                         note="dry-run — would rebuild"))
+            continue
+        proc = subprocess.run(cmd, cwd=sp.path, capture_output=True, text=True)
+        results.append(ReindexResult(
+            sp.name, cmd, ran=True, returncode=proc.returncode,
+            restart_required=affected if proc.returncode == 0 else [],
+            note=(proc.stderr.strip().splitlines() or [""])[-1] if proc.returncode else "ok",
+        ))
+    return results

aidos-0.0.1/src/aidos/roadmap_tool.py

@@ -0,0 +1,225 @@
+"""roadmap_tool — parse, identify, index, and split roadmap markdown files.
+
+Design (Roadmap #24 Phase 1):
+
+- **Markdown stays the source of truth** (git-native, hand-editable, PR-reviewable).
+  This module derives a fast search index *from* it — it does not replace it.
+- Each roadmap item gets a **stable UUID** (uuid5 over file + item key + title),
+  so re-runs are deterministic and an item keeps its id across edits to its body.
+- Status is classified from each item's **own** signals (✅ / strikethrough /
+  "Shipped"/"Completed" / "Deferred") — never from a separate priority-matrix
+  marker (the matrix is known to lag real status).
+- The done/active **split is a preview** written to a separate directory; the
+  original file is never mutated by this tool (operator reviews first).
+
+Search uses SQLite **FTS5** (keyword). Embeddings are intentionally NOT used:
+on a few-hundred-item corpus keyword search is instant, and the workspace
+convention is that TF-IDF/keyword beats embeddings on small technical corpora.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import uuid
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+# Stable namespace so UUIDs are reproducible across runs and machines.
+_NS = uuid.uuid5(uuid.NAMESPACE_URL, "aidos/roadmap")
+
+# An item heading is a level-2/3 heading whose text starts with an identifier
+# token containing a digit: ``#24``, ``24.``, ``NS-1.1``, ``GLM-1``, ``UI-15``,
+# ``I1``, ``DOCS-2``. Group 1 = hashes, group 2 = optional strikethrough,
+# group 3 = the item key token.
+_ITEM_RE = re.compile(
+    r"^(#{2,3})\s+(~~)?\s*(#?[A-Za-z]{0,5}-?\d[\w.\-]*)\b(.*)$"
+)
+
+_DONE_RE = re.compile(
+    r"(✅|~~|\bShipped\b|\bSHIPPED\b|\bCompleted\b|\bDone\b|\bDONE\b)"
+)
+_DEFER_RE = re.compile(r"defer", re.IGNORECASE)
+
+STATUSES = ("done", "deferred", "active")
+
+
+@dataclass
+class Item:
+    """A single roadmap item parsed from a markdown heading + its body."""
+
+    uuid: str
+    key: str               # e.g. "#24", "NS-1.1", "GLM-2", "10"
+    title: str
+    status: str            # one of STATUSES
+    level: int             # heading level (2 or 3)
+    line_start: int        # 1-based line of the heading
+    line_end: int          # 1-based last line of the body (exclusive of next item)
+    tags: list[str] = field(default_factory=list)
+    body: str = ""
+
+    def metadata_block(self) -> str:
+        """Human-readable + machine-parseable block to stamp under a heading."""
+        return (
+            f"- **id:** `{self.uuid}`\n"
+            f"- **status:** {self.status}\n"
+            f"- **tags:** {', '.join(self.tags) or '—'}\n"
+        )
+
+
+def _clean_title(key: str, trailing: str) -> str:
+    text = trailing.strip()
+    # Strip leading separators after the key (". ", ") ", "— ", "- ").
+    text = re.sub(r"^[.)\s—–-]+", "", text)
+    text = text.replace("~~", "").replace("✅", "").strip()
+    # Collapse a key that was split across the regex (e.g. "#24" + ". Title").
+    return text or key
+
+
+def _classify(heading_line: str, body: str) -> str:
+    if _DEFER_RE.search(heading_line):
+        return "deferred"
+    if _DONE_RE.search(heading_line):
+        return "done"
+    # Only look at the first ~25 lines of the body for a status declaration,
+    # so a passing mention of "shipped" deep in prose does not mislabel.
+    head = "\n".join(body.splitlines()[:25])
+    if re.search(r"(\*\*✅|✅\s*Shipped|Status:.*?(Shipped|Completed|Done|✅))", head):
+        return "done"
+    if _DEFER_RE.search(head):
+        return "deferred"
+    return "active"
+
+
+def _tags_for(key: str) -> list[str]:
+    m = re.match(r"#?([A-Za-z]+)", key)
+    return [m.group(1).upper()] if m and m.group(1) else []
+
+
+def parse_roadmap(path: Path) -> list[Item]:
+    """Parse a roadmap markdown file into a list of :class:`Item`."""
+    lines = path.read_text(encoding="utf-8").splitlines()
+    # Locate every item heading first, then slice bodies between them.
+    heads: list[tuple[int, int, str, str, str]] = []  # (idx, level, key, hashes, trailing)
+    for i, line in enumerate(lines):
+        m = _ITEM_RE.match(line)
+        if not m:
+            continue
+        hashes, _strike, key, trailing = m.groups()
+        heads.append((i, len(hashes), key, line, trailing))
+
+    items: list[Item] = []
+    for n, (idx, level, key, heading_line, trailing) in enumerate(heads):
+        end = heads[n + 1][0] if n + 1 < len(heads) else len(lines)
+        body = "\n".join(lines[idx + 1:end]).strip()
+        title = _clean_title(key, trailing)
+        status = _classify(heading_line, body)
+        item_uuid = str(uuid.uuid5(_NS, f"{path.name}:{key}:{title}"))
+        items.append(
+            Item(
+                uuid=item_uuid,
+                key=key.lstrip("#") and key,  # keep the literal token (e.g. "#24")
+                title=title,
+                status=status,
+                level=level,
+                line_start=idx + 1,
+                line_end=end,
+                tags=_tags_for(key),
+                body=body,
+            )
+        )
+    return items
+
+
+def build_index(items: list[Item], db_path: Path) -> Path:
+    """Write a SQLite FTS5 keyword index + a JSON sidecar. Returns db_path."""
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    if db_path.exists():
+        db_path.unlink()
+    con = sqlite3.connect(db_path)
+    try:
+        con.execute(
+            "CREATE TABLE items (uuid TEXT PRIMARY KEY, key TEXT, title TEXT, "
+            "status TEXT, level INT, line_start INT, line_end INT, tags TEXT)"
+        )
+        con.execute(
+            "CREATE VIRTUAL TABLE roadmap_fts USING fts5("
+            "uuid UNINDEXED, key, title, status UNINDEXED, tags, body)"
+        )
+        for it in items:
+            con.execute(
+                "INSERT INTO items VALUES (?,?,?,?,?,?,?,?)",
+                (it.uuid, it.key, it.title, it.status, it.level,
+                 it.line_start, it.line_end, ",".join(it.tags)),
+            )
+            con.execute(
+                "INSERT INTO roadmap_fts VALUES (?,?,?,?,?,?)",
+                (it.uuid, it.key, it.title, it.status, " ".join(it.tags), it.body),
+            )
+        con.commit()
+    finally:
+        con.close()
+    # JSON sidecar (bodies omitted to keep it small + diff-friendly).
+    sidecar = db_path.with_suffix(".json")
+    sidecar.write_text(
+        json.dumps(
+            [{k: v for k, v in asdict(it).items() if k != "body"} for it in items],
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    return db_path
+
+
+def search_index(db_path: Path, query: str, limit: int = 20) -> list[dict]:
+    """Run an FTS5 keyword search; return ranked item rows (no bodies)."""
+    con = sqlite3.connect(db_path)
+    try:
+        con.row_factory = sqlite3.Row
+        rows = con.execute(
+            "SELECT uuid, key, title, status FROM roadmap_fts "
+            "WHERE roadmap_fts MATCH ? ORDER BY rank LIMIT ?",
+            (query, limit),
+        ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        con.close()
+
+
+def split_preview(path: Path, items: list[Item], out_dir: Path) -> dict[str, Path]:
+    """Write NON-DESTRUCTIVE done/active+deferred split previews.
+
+    The original ``path`` is never modified. Returns the two written paths.
+    """
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stem = path.stem
+    archive = out_dir / f"{stem}-archive.md"
+    active = out_dir / f"{stem}-active.md"
+
+    def _render(title: str, chosen: list[Item]) -> str:
+        out = [f"# {title}", "", f"> Generated by aidos from {path.name} "
+               f"(non-destructive preview). {len(chosen)} items.", ""]
+        for it in chosen:
+            out.append(f"## {it.key} — {it.title}")
+            out.append("")
+            out.append(it.metadata_block())
+            out.append(it.body)
+            out.append("")
+            out.append("---")
+            out.append("")
+        return "\n".join(out)
+
+    done = [it for it in items if it.status == "done"]
+    rest = [it for it in items if it.status != "done"]
+    archive.write_text(_render(f"{stem} — Archive (done)", done), encoding="utf-8")
+    active.write_text(_render(f"{stem} — Active / Deferred", rest), encoding="utf-8")
+    return {"archive": archive, "active": active}
+
+
+def summarize(items: list[Item]) -> dict[str, int]:
+    counts = {s: 0 for s in STATUSES}
+    for it in items:
+        counts[it.status] = counts.get(it.status, 0) + 1
+    counts["total"] = len(items)
+    return counts

aidos-0.0.1/src/aidos.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: aidos
+Version: 0.0.1
+Summary: aidos (AI Diary Operating System) — the control-plane CLI for an agentic harness: roadmap index, knowledge-graph reindex, and module setup.
+Author: Yingding Wang
+License-Expression: MIT
+Keywords: aidos,ai-diary,harness,control-plane,knowledge-graph,roadmap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.15.1
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.27.1; extra == "mcp"
+Dynamic: license-file
+
+# aidos
+
+**AI diary OS** — the control-plane CLI for an agentic harness. Index your roadmaps, keep knowledge graphs fresh, and stand up new modules, all from one command.
+
+## What it does
+
+`aidos` is the operations layer that sits *above* a multi-module workspace and manages the shared machinery your agent depends on:
+
+- **Roadmap index** — parse a roadmap markdown into identified items (stable UUIDs), classify them done / active / deferred, and build a SQLite **FTS5** keyword index for fast search. The markdown stays the source of truth; the index is derived.
+- **Graph reindex** — discover every subproject's knowledge graphs, report freshness, and rebuild them in the correct virtualenv. It never kills your MCP servers — it reports which ones need a restart.
+- **Module setup** — a reproducible recipe (and script) to make a new Python module a first-class citizen: its own venv, its own code + docs graphs, and wiring into the shared portal.
+
+It is **CLI-first**: all logic lives behind plain functions, so it is testable and scriptable without a server. A future control **MCP** wraps the same CLI.
+
+The name is a nod to [`aidiary`](https://pypi.org/project/aidiary/) (the *AI diary* memory system): `aidos` is the **OS** layer around it.
+
+## Install
+
+Requires: Python 3.12+
+
+```bash
+pip install aidos
+```
+
+Building a module's own knowledge graphs additionally uses `aidiary[graphs]` (installed editable in dev):
+
+```bash
+pip install "aidiary[graphs]"
+```
+
+## Quick start
+
+### 1. Check graph freshness across the workspace
+
+```bash
+aidos status
+```
+
+Lists each subproject's graph layers (code / docs / …) with a ✓ fresh / ⚠ stale / ✗ missing badge based on `graph.json` mtime vs. newest source.
+
+### 2. Index a roadmap and search it
+
+```bash
+aidos roadmap index path/to/ProjectRoadmap.md
+aidos roadmap search "graph reindex" --db output/aidos/ProjectRoadmap.db
+```
+
+`index` assigns a stable UUID to every item and writes a SQLite FTS5 index + a JSON sidecar. `search` is instant keyword retrieval — no embeddings, no LLM.
+
+### 3. Preview a done / active split (non-destructive)
+
+```bash
+aidos roadmap split path/to/ProjectRoadmap.md
+```
+
+Writes `*-archive.md` (done) and `*-active.md` (active + deferred) previews. **The original file is never modified** — you review first.
+
+### 4. Rebuild knowledge graphs
+
+```bash
+aidos reindex --dry-run          # show what would rebuild
+aidos reindex --subproject aidos # rebuild one subproject's code graph
+```
+
+Any rebuilt layer is reported as `restart_required` — restart those MCP servers through your editor (or your restart script), never by killing the process.
+
+## Directory layout
+
+```
+my-module/
+├── pyproject.toml
+├── config/graphs.toml        # graphs.code (src/, ast) + graphs.docs (docs/, semantic)
+├── src/<pkg>/                # your package
+├── docs/                     # concept docs (feed the docs graph)
+└── output/                   # generated artifacts
+    ├── aidos/                # roadmap index db + json sidecar
+    └── graphs/{code,docs}/   # graph.json + graph.html
+```
+
+## Command reference
+
+| Command | Purpose |
+|---------|---------|
+| `aidos status` | Report knowledge-graph freshness across subprojects |
+| `aidos roadmap index <file>` | Build the SQLite FTS5 search index for a roadmap |
+| `aidos roadmap search <query> --db <db>` | Keyword-search the index |
+| `aidos roadmap split <file>` | Non-destructive done / active split preview |
+| `aidos reindex [--subproject N] [--docs] [--dry-run]` | Rebuild per-subproject graphs |
+
+## Design principles
+
+- **Markdown / files stay the source of truth** — every index, db, and graph is a *derived* artifact. Producers and consumers connect via files on disk, not imports.
+- **Keyword over embeddings** — on a few-hundred-item corpus, SQLite FTS5 is instant and sufficient; vector search is deferred until the data demands it.
+- **Never kill a stdio MCP server** — reindex reports `restart_required`; it does not respawn processes.
+
+## What's new
+
+### 0.0.1
+
+**First cut — the Developer-Control plane CLI**
+
+- **`roadmap`** — `index` (parse → stable UUIDs → done/active/deferred → SQLite FTS5 + JSON sidecar), `search` (FTS5 keyword), `split` (non-destructive done/active preview).
+- **`reindex`** — discover subproject graphs, report freshness, rebuild via each subproject's `aidiary-graphs`; reports `restart_required` (never kills MCP servers).
+- **`status`** — workspace-wide graph freshness.
+- **Reproducible module setup** — idempotent `setup.sh` (venv + editable installs + graphs) and a documented "make a module a first-class harness citizen" guide.
+- **Typer CLI**, stdlib-only core (plus Typer); builds to sdist + wheel.

aidos-0.0.1/src/aidos.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+MANIFEST.in
+README.md
+projectdescription.md
+pyproject.toml
+requirements.txt
+src/aidos/__init__.py
+src/aidos/cli.py
+src/aidos/reindex.py
+src/aidos/roadmap_tool.py
+src/aidos.egg-info/PKG-INFO
+src/aidos.egg-info/SOURCES.txt
+src/aidos.egg-info/dependency_links.txt
+src/aidos.egg-info/entry_points.txt
+src/aidos.egg-info/requires.txt
+src/aidos.egg-info/top_level.txt

aidos-0.0.1/src/aidos.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aidos-0.0.1/src/aidos.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aidos = aidos.cli:main

aidos-0.0.1/src/aidos.egg-info/requires.txt

@@ -0,0 +1,4 @@
+typer>=0.15.1
+
+[mcp]
+mcp>=1.27.1

aidos-0.0.1/src/aidos.egg-info/top_level.txt

@@ -0,0 +1 @@
+aidos