ver 0.9

2026-06-21 11:46:54 -05:00
parent 88210a4e84
commit d404f6e96f
38 changed files with 2561 additions and 1046 deletions
@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""bootstrap.py — stand up (or repair) an ECHO vault deterministically.
+
+Idempotent and additive: every write is probe-before-write and NEVER overwrites
+an existing file. The marker (_agent/echo-vault.md) is written LAST, so the vault
+is only flagged "set up" once every piece is in place. Re-running is the repair
+path (it fills in only what is missing). Cross-platform: pure Python via echo.py.
+
+Usage:
+  bootstrap.py [--dry-run]
+
+Env: ECHO_BASE, ECHO_KEY (via echo.py), ECHO_TODAY (YYYY-MM-DD for {{DATE}}).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SKILL_DIR = SCRIPT_DIR.parent
+SCAFFOLD = SKILL_DIR / "scaffold"
+sys.path.insert(0, str(SCRIPT_DIR))
+
+import echo  # noqa: E402
+
+LEAVES = [
+    "inbox/captures", "inbox/imports", "inbox/processing-log",
+    "journal/daily", "journal/weekly", "journal/monthly", "journal/quarterly",
+    "journal/annual", "journal/templates",
+    "projects/active", "projects/incubating", "projects/on-hold", "projects/archived",
+    "areas/business", "areas/personal", "areas/learning", "areas/systems",
+    "resources/concepts", "resources/references", "resources/people",
+    "resources/companies", "resources/meetings",
+    "decisions/by-date",
+    "_agent/context", "_agent/memory/working", "_agent/memory/episodic",
+    "_agent/memory/semantic", "_agent/sessions", "_agent/health", "_agent/templates",
+    "_agent/heartbeat", "_agent/skills/active", "_agent/skills/archived", "_agent/locks",
+    "_agent/index",
+]
+
+
+def exists(path: str) -> bool:
+    status, _ = echo.request("GET", echo.vault_url(path))
+    return status == 200
+
+
+def put_text(path: str, text: str) -> None:
+    status, body = echo.request("PUT", echo.vault_url(path), data=text.encode(),
+                                headers={"Content-Type": "text/markdown"})
+    echo.check(status, body, f"bootstrap put {path}")
+
+
+def seed(path: str, source: Path, dry_run: bool) -> None:
+    if exists(path):
+        print(f"bootstrap: skip (exists)  {path}")
+        return
+    if dry_run:
+        print(f"bootstrap: would seed     {path} <- {source.relative_to(SKILL_DIR)}")
+        return
+    text = source.read_text(encoding="utf-8").replace("{{DATE}}", echo.today())
+    put_text(path, text)
+    print(f"bootstrap: seeded         {path}")
+
+
+def leaf_readme(folder: str, dry_run: bool) -> None:
+    path = f"{folder}/README.md"
+    if exists(path):
+        return
+    if dry_run:
+        print(f"bootstrap: would readme   {path}")
+        return
+    name = folder.rsplit("/", 1)[-1]
+    put_text(path, f"# {name}\n\nMemory vault folder. See the echo-memory plugin for conventions.\n")
+    print(f"bootstrap: readme         {path}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Bootstrap or repair an ECHO vault")
+    parser.add_argument("--dry-run", "-n", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not SCAFFOLD.is_dir():
+        print(f"bootstrap: scaffold not found at {SCAFFOLD}", file=sys.stderr)
+        return 1
+
+    if exists("_agent/echo-vault.md"):
+        status, body = echo.request("GET", echo.vault_url("_agent/echo-vault.md"))
+        version = "unknown"
+        if status == 200:
+            version = next((ln.split(":", 1)[1].strip()
+                            for ln in body.decode(errors="replace").splitlines()
+                            if ln.startswith("schema_version:")), "unknown")
+        print(f"bootstrap: marker present (schema_version={version}). Running repair pass (fills only missing files).")
+
+    for folder in LEAVES:
+        leaf_readme(folder, args.dry_run)
+
+    templates = SCAFFOLD / "templates"
+    if templates.is_dir():
+        for source in sorted(templates.rglob("*.md")):
+            seed(source.relative_to(templates).as_posix(), source, args.dry_run)
+
+    seed("_agent/memory/semantic/operator-preferences.md", SCAFFOLD / "anchors" / "operator-preferences.seed.md", args.dry_run)
+    seed("_agent/context/current-context.md", SCAFFOLD / "anchors" / "current-context.seed.md", args.dry_run)
+    seed("inbox/captures/inbox.md", SCAFFOLD / "anchors" / "inbox.seed.md", args.dry_run)
+    seed("README.md", SCAFFOLD / "README.vault.md", args.dry_run)
+    seed("_agent/echo-vault.md", SCAFFOLD / "echo-vault.md", args.dry_run)  # marker LAST
+
+    print(f"bootstrap: done ({'DRY-RUN ' if args.dry_run else ''}{echo.today()}).")
+    print("bootstrap: next: create today's daily note + a bootstrap session log + heartbeat (see SKILL.md).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())