si-cartographer 0.1.0__tar.gz

si_cartographer-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: si-cartographer
+Version: 0.1.0
+Summary: Charts the workspace as graphed knowledge. The agent that thinks with its pen.
+Author: SuperInstance
+License-Expression: MIT
+Keywords: knowledge-graph,procedural-memory,wiki,chart,exo-filed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# cartographer
+
+*The agent that charts the workspace as graphed knowledge.*
+
+---
+
+The **cartographer** doesn't run tasks. The cartographer **charts** them.
+
+Every solution becomes a reusable script. Every dead-end becomes a hazard note. Every cross-repo connection becomes an edge on the knowledge graph. The graph is exo-filed (markdown + JSON) so humans and agents can both read it.
+
+## The maritime role
+
+The **deckhand** (sibling: [`able-bodied-crew`](https://github.com/SuperInstance/able-bodied-crew)) runs tasks — indexes, retrieves, batches, executes.
+
+The **cartographer** charts — documents solutions, maps hazards, draws coastlines, writes chronicles. Pen-on-paper. Thinks with its pen.
+
+```
+Deckhand runs the task → solves the problem → calls Cartographer
+Cartographer charts the solution → writes the script → notes hazards
+Next time the same problem appears → Cartographer finds the chart → Deckhand runs the known-good script
+```
+
+## What it does
+
+- **KnowledgeGraph** — nodes (repos, concepts, scripts, hazards) and edges (references, dependencies, solved-by). Stored as JSON + markdown. No database.
+- **ChartMaker** — writes reusable scripts, hazard notes (what NOT to do), and procedure docs. Tests scripts automatically.
+- **CoastlineBuilder** — generates maps at three zoom levels: 1000ft (fleet at a glance), 100ft (each repo in detail), 10ft (file-level for one repo)
+- **Navigator** — given a problem, finds the nearest documented solution or hazard
+- **Chronicler** — writes daily chronicles (the thinking-with-pen record)
+
+## Install
+
+```bash
+pip install si-cartographer
+```
+
+## Use
+
+```bash
+# Build knowledge graph from workspace
+cartographer graph /path/to/workspace
+
+# Generate coastline maps
+cartographer coastline /path/to/workspace
+
+# Find a solution
+cartographer navigate "How do I publish to PyPI?"
+
+# Write to the chronicle
+cartographer chronicle --section "PyPI" --message "Published si-cartographer v0.1.0"
+```
+
+## License
+
+MIT
+
+---
+
+*Built by SuperInstance. The cartographer charts the rocks so the deckhand doesn't hit them.*

si_cartographer-0.1.0/README.md

@@ -0,0 +1,59 @@
+# cartographer
+
+*The agent that charts the workspace as graphed knowledge.*
+
+---
+
+The **cartographer** doesn't run tasks. The cartographer **charts** them.
+
+Every solution becomes a reusable script. Every dead-end becomes a hazard note. Every cross-repo connection becomes an edge on the knowledge graph. The graph is exo-filed (markdown + JSON) so humans and agents can both read it.
+
+## The maritime role
+
+The **deckhand** (sibling: [`able-bodied-crew`](https://github.com/SuperInstance/able-bodied-crew)) runs tasks — indexes, retrieves, batches, executes.
+
+The **cartographer** charts — documents solutions, maps hazards, draws coastlines, writes chronicles. Pen-on-paper. Thinks with its pen.
+
+```
+Deckhand runs the task → solves the problem → calls Cartographer
+Cartographer charts the solution → writes the script → notes hazards
+Next time the same problem appears → Cartographer finds the chart → Deckhand runs the known-good script
+```
+
+## What it does
+
+- **KnowledgeGraph** — nodes (repos, concepts, scripts, hazards) and edges (references, dependencies, solved-by). Stored as JSON + markdown. No database.
+- **ChartMaker** — writes reusable scripts, hazard notes (what NOT to do), and procedure docs. Tests scripts automatically.
+- **CoastlineBuilder** — generates maps at three zoom levels: 1000ft (fleet at a glance), 100ft (each repo in detail), 10ft (file-level for one repo)
+- **Navigator** — given a problem, finds the nearest documented solution or hazard
+- **Chronicler** — writes daily chronicles (the thinking-with-pen record)
+
+## Install
+
+```bash
+pip install si-cartographer
+```
+
+## Use
+
+```bash
+# Build knowledge graph from workspace
+cartographer graph /path/to/workspace
+
+# Generate coastline maps
+cartographer coastline /path/to/workspace
+
+# Find a solution
+cartographer navigate "How do I publish to PyPI?"
+
+# Write to the chronicle
+cartographer chronicle --section "PyPI" --message "Published si-cartographer v0.1.0"
+```
+
+## License
+
+MIT
+
+---
+
+*Built by SuperInstance. The cartographer charts the rocks so the deckhand doesn't hit them.*

si_cartographer-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "si-cartographer"
+version = "0.1.0"
+description = "Charts the workspace as graphed knowledge. The agent that thinks with its pen."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "SuperInstance" }]
+keywords = ["knowledge-graph", "procedural-memory", "wiki", "chart", "exo-filed"]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[project.scripts]
+cartographer = "cartographer.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

si_cartographer-0.1.0/setup.cfg

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

si_cartographer-0.1.0/src/cartographer/__init__.py

@@ -0,0 +1,23 @@
+"""
+cartographer — the agent that charts the workspace as graphed knowledge.
+
+The deckhand runs tasks. The cartographer charts them.
+Pen-on-paper. Exo-filed. Every solution a script. Every dead-end a hazard.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = [
+    "KnowledgeGraph",
+    "ChartMaker",
+    "CoastlineBuilder",
+    "Navigator",
+    "Chronicler",
+]
+
+from cartographer.graph import KnowledgeGraph, Node, Edge
+from cartographer.chart_maker import ChartMaker, Script, HazardNote
+from cartographer.coastline import CoastlineBuilder
+from cartographer.navigator import Navigator
+from cartographer.chronicler import Chronicler

si_cartographer-0.1.0/src/cartographer/chart_maker.py

@@ -0,0 +1,296 @@
+"""ChartMaker — writes reusable scripts + hazard notes + procedure docs.
+
+Moved from deckhand. The cartographer's pen.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Script:
+    """A reusable solution script."""
+    name: str
+    description: str
+    language: str
+    code: str
+    problem: str
+    success: bool = False
+    tested_at: float = 0.0
+    test_output: str = ""
+    tags: list[str] = field(default_factory=list)
+    author: str = "cartographer"
+
+    def to_metadata(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "language": self.language,
+            "problem": self.problem,
+            "success": self.success,
+            "tested_at": self.tested_at,
+            "tags": self.tags,
+            "author": self.author,
+            "code_sha256": hashlib.sha256(self.code.encode()).hexdigest()[:12],
+        }
+
+
+@dataclass
+class HazardNote:
+    """A rock on the chart — what NOT to do."""
+    title: str
+    approach: str
+    failure: str
+    show_stopper: bool
+    workaround: str = ""
+    discovered_at: float = 0.0
+    context: str = ""
+
+
+class ChartMaker:
+    """The cartographer's pen. Writes scripts, hazards, procedures."""
+
+    def __init__(self, root_dir: str) -> None:
+        self.root = Path(root_dir)
+        self.scripts_dir = self.root / "scripts"
+        self.hazards_dir = self.root / "hazards"
+        self.procedures_dir = self.root / "procedures"
+        self.logs_dir = self.root / "chronicles"
+
+        for d in [self.scripts_dir, self.hazards_dir, self.procedures_dir, self.logs_dir]:
+            d.mkdir(parents=True, exist_ok=True)
+
+    def write_script(
+        self,
+        name: str,
+        description: str,
+        code: str,
+        problem: str,
+        language: str = "bash",
+        tags: list[str] | None = None,
+        run_immediately: bool = False,
+    ) -> Script:
+        """Write a reusable script and optionally test it."""
+        script = Script(
+            name=name, description=description, code=code,
+            problem=problem, language=language, tags=tags or [],
+        )
+
+        suffix = ".sh" if language == "bash" else f".{language}"
+        script_path = self.scripts_dir / f"{name}{suffix}"
+        script_path.write_text(code)
+        script_path.chmod(0o755)
+
+        # Procedure doc
+        proc_lines = [
+            f"# Procedure: {name}",
+            f"",
+            f"**Problem:** {problem}",
+            f"**Solution:** {description}",
+            f"**Tags:** {', '.join(tags) if tags else 'none'}",
+            f"",
+            f"## The Code",
+            f"",
+            f"```{language}",
+            code,
+            f"```",
+            f"",
+            f"## When to Use",
+            f"",
+            f"{problem}",
+            f"",
+        ]
+        (self.procedures_dir / f"{name}.md").write_text("\n".join(proc_lines))
+
+        if run_immediately:
+            self._test_script(script)
+
+        # Metadata
+        meta_path = self.scripts_dir / f"{name}.meta.json"
+        meta_path.write_text(json.dumps(script.to_metadata(), indent=2))
+
+        self._log(f"Wrote script `{name}` — {description}")
+        return script
+
+    def _test_script(self, script: Script) -> bool:
+        """Run a script and record result."""
+        suffix = ".sh" if script.language == "bash" else f".{script.language}"
+        script_path = self.scripts_dir / f"{script.name}{suffix}"
+
+        try:
+            runner = "python3" if script.language == "python" else "bash"
+            result = subprocess.run(
+                [runner, str(script_path)],
+                capture_output=True, text=True, timeout=30,
+            )
+            script.success = result.returncode == 0
+            script.tested_at = time.time()
+            script.test_output = (result.stdout[:500] + "\n" + result.stderr[:500]).strip()
+
+            status = "✓" if script.success else "✗"
+            self._log(f"{status} Script `{script.name}` tested")
+
+            if not script.success:
+                self.write_hazard(
+                    title=f"Script {script.name} failed",
+                    approach=f"Ran {script.name}",
+                    failure=result.stderr[:300] or result.stdout[:300],
+                    show_stopper=False,
+                    workaround="Debug and retry",
+                )
+            return script.success
+
+        except Exception as e:
+            script.success = False
+            script.test_output = f"EXCEPTION: {e}"
+            self._log(f"✗ Script `{script.name}` EXCEPTION: {e}")
+            return False
+
+    def write_hazard(
+        self,
+        title: str,
+        approach: str,
+        failure: str,
+        show_stopper: bool,
+        workaround: str = "",
+        context: str = "",
+    ) -> HazardNote:
+        """Chart a rock — what NOT to do."""
+        hazard = HazardNote(
+            title=title, approach=approach, failure=failure,
+            show_stopper=show_stopper, workaround=workaround,
+            discovered_at=time.time(), context=context,
+        )
+
+        safe = re.sub(r"[^a-z0-9_-]", "_", title.lower())[:60]
+        path = self.hazards_dir / f"{safe}.md"
+
+        lines = [
+            f"# ⚠️ Hazard: {title}",
+            f"",
+            f"**Discovered:** {time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime(hazard.discovered_at))}",
+            f"**Show-stopper:** {'🚫 YES' if show_stopper else '⚠️ No — workaround exists'}",
+            f"",
+            f"## What Was Tried",
+            f"",
+            f"```\n{approach}\n```",
+            f"",
+            f"## Why It Failed",
+            f"",
+            f"{failure}",
+            f"",
+        ]
+        if workaround:
+            lines += [f"## Workaround\n", f"{workaround}\n"]
+        if context:
+            lines += [f"## Context\n", f"{context}\n"]
+        lines += [f"## Lesson\n", f"**Do NOT do this.**\n"]
+
+        path.write_text("\n".join(lines))
+        self._log(f"⚠️ Hazard charted: {title}")
+        return hazard
+
+    def find_script(self, problem: str) -> Script | None:
+        """Find a previously written script for a similar problem."""
+        problem_words = set(re.findall(r"\w+", problem.lower()))
+        best_match = None
+        best_score = 0
+
+        for meta_file in self.scripts_dir.glob("*.meta.json"):
+            try:
+                meta = json.loads(meta_file.read_text())
+            except Exception:
+                continue
+            meta_text = (
+                meta.get("problem", "").lower() + " "
+                + meta.get("description", "").lower() + " "
+                + " ".join(meta.get("tags", []))
+            )
+            overlap = len(problem_words & set(re.findall(r"\w+", meta_text)))
+            if overlap > best_score:
+                best_score = overlap
+                best_match = meta
+
+        if best_match and best_score >= 2:
+            name = best_match["name"]
+            suffix = ".sh" if best_match.get("language", "bash") == "bash" else f".{best_match['language']}"
+            script_path = self.scripts_dir / f"{name}{suffix}"
+            if script_path.exists():
+                return Script(
+                    name=name, description=best_match.get("description", ""),
+                    code=script_path.read_text(), problem=best_match.get("problem", ""),
+                    language=best_match.get("language", "bash"),
+                    success=best_match.get("success", False),
+                    tested_at=best_match.get("tested_at", 0),
+                    tags=best_match.get("tags", []),
+                )
+        return None
+
+    def has_hazard_for(self, approach: str) -> bool:
+        """Check if there's a hazard for this approach."""
+        approach_words = set(re.findall(r"\w+", approach.lower()))
+        for hazard_file in self.hazards_dir.glob("*.md"):
+            content = hazard_file.read_text().lower()
+            content_words = set(re.findall(r"\w+", content))
+            if len(approach_words & content_words) >= 3:
+                return True
+        return False
+
+    def list_scripts(self) -> list[dict[str, Any]]:
+        """List all scripts."""
+        scripts = []
+        for meta_file in sorted(self.scripts_dir.glob("*.meta.json")):
+            try:
+                scripts.append(json.loads(meta_file.read_text()))
+            except Exception:
+                pass
+        return scripts
+
+    def list_hazards(self) -> list[str]:
+        """List all hazard titles."""
+        return [f.stem for f in sorted(self.hazards_dir.glob("*.md"))]
+
+    def _log(self, message: str) -> None:
+        """Write to the daily chronicle."""
+        log_path = self.logs_dir / f"{time.strftime('%Y-%m-%d')}.md"
+        timestamp = time.strftime("%H:%M:%S UTC", time.gmtime())
+        with open(log_path, "a") as fh:
+            fh.write(f"- [{timestamp}] {message}\n")
+
+    def generate_index(self) -> str:
+        """Generate PROCEDURES.md index."""
+        lines = [
+            "# Procedures & Hazards",
+            "",
+            f"*The cartographer's procedural memory. Generated {time.strftime('%Y-%m-%d %H:%M UTC', time.gmtime())}.*",
+            "",
+            "## Scripts",
+            "",
+            "| Script | Problem | Tested | Tags |",
+            "|--------|---------|--------|------|",
+        ]
+        for s in self.list_scripts():
+            tested = "✓" if s.get("success") else "✗"
+            tags = ", ".join(s.get("tags", [])) or "—"
+            lines.append(f"| `{s['name']}` | {s.get('problem', '—')[:50]} | {tested} | {tags} |")
+
+        lines += ["", "## Hazards", ""]
+        hazards = self.list_hazards()
+        if hazards:
+            for h in hazards:
+                lines.append(f"- ⚠️ {h}")
+        else:
+            lines.append("*No hazards charted. Waters clear.*")
+
+        path = self.root / "PROCEDURES.md"
+        path.write_text("\n".join(lines))
+        return str(path)

si_cartographer-0.1.0/src/cartographer/chronicler.py

@@ -0,0 +1,54 @@
+"""Chronicler — writes the daily chronicle (the thinking-with-pen record)."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+
+class Chronicler:
+    """Writes daily chronicles from workspace activity."""
+
+    def __init__(self, chronicle_dir: str) -> None:
+        self.dir = Path(chronicle_dir)
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def write_entry(self, section: str, message: str) -> None:
+        """Append an entry to today's chronicle."""
+        log_path = self.dir / f"{time.strftime('%Y-%m-%d')}.md"
+        timestamp = time.strftime("%H:%M:%S UTC", time.gmtime())
+
+        # Ensure file has header
+        if not log_path.exists():
+            log_path.write_text(
+                f"# Chronicle — {time.strftime('%Y-%m-%d')}\n\n"
+                f"*The cartographer's daily log. Thinking with the pen.*\n\n"
+            )
+
+        with open(log_path, "a") as fh:
+            fh.write(f"### [{timestamp}] {section}\n\n{message}\n\n")
+
+    def read_today(self) -> str:
+        """Read today's chronicle."""
+        path = self.dir / f"{time.strftime('%Y-%m-%d')}.md"
+        if path.exists():
+            return path.read_text()
+        return ""
+
+    def summarize(self) -> dict[str, Any]:
+        """Summarize today's chronicle."""
+        content = self.read_today()
+        sections = {}
+        current = None
+        for line in content.split("\n"):
+            if line.startswith("### ["):
+                current = line
+                sections[current] = []
+            elif current and line.strip():
+                sections[current].append(line.strip())
+        return {
+            "date": time.strftime("%Y-%m-%d"),
+            "entries": len(sections),
+            "sections": list(sections.keys()),
+        }

si_cartographer-0.1.0/src/cartographer/cli.py

@@ -0,0 +1,120 @@
+"""CLI for cartographer."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="cartographer",
+        description="🗺️ Charts the workspace as graphed knowledge.",
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    # graph
+    p_graph = sub.add_parser("graph", help="Build knowledge graph from workspace")
+    p_graph.add_argument("workspace", help="Workspace root")
+
+    # chart
+    p_chart = sub.add_parser("chart", help="Write a script/hazard")
+    p_chart.add_argument("--type", choices=["script", "hazard"], required=True)
+    p_chart.add_argument("--name", required=True)
+
+    # coastline
+    p_coast = sub.add_parser("coastline", help="Generate coastline maps")
+    p_coast.add_argument("workspace")
+    p_coast.add_argument("--output", default="charts")
+
+    # navigate
+    p_nav = sub.add_parser("navigate", help="Find nearest solution")
+    p_nav.add_argument("problem", help="The problem to solve")
+
+    # chronicle
+    p_chron = sub.add_parser("chronicle", help="Write or read chronicle")
+    p_chron.add_argument("--section", default="General")
+    p_chron.add_argument("--message", default="")
+    p_chron.add_argument("--read", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    if args.command == "graph":
+        from cartographer.graph import KnowledgeGraph
+        from pathlib import Path
+
+        kg = KnowledgeGraph()
+
+        # Scan repos in workspace
+        workspace = Path(args.workspace)
+        for entry in sorted(workspace.iterdir()):
+            if entry.is_dir() and not entry.name.startswith("."):
+                has_git = (entry / ".git").exists()
+                has_readme = any((entry / f).exists() for f in ["README.md", "readme.md"])
+                file_count = sum(1 for _ in entry.rglob("*") if _.is_file() and ".git" not in str(_))
+                health = "ok" if has_readme else "no-readme"
+                kg.add_node(entry.name, type="repo", health=health, file_count=file_count, has_git=has_git)
+
+        out = workspace / "cartographer-charts"
+        kg.save(str(out))
+        print(f"Graph: {kg.stats()}")
+        print(f"Saved to {out}")
+
+    elif args.command == "coastline":
+        from cartographer.graph import KnowledgeGraph
+        from cartographer.coastline import CoastlineBuilder
+
+        workspace = args.workspace
+        out = args.output
+        charts_path = workspace.rstrip("/") + "/cartographer-charts"
+
+        kg = KnowledgeGraph.load(charts_path)
+        if not kg.nodes:
+            print("No graph found. Run `cartographer graph <workspace>` first.")
+            return 1
+
+        cb = CoastlineBuilder(kg, workspace)
+        files = cb.build_all(out)
+        print(f"Coastline maps generated:")
+        for f in files:
+            print(f"  {f}")
+
+    elif args.command == "navigate":
+        from cartographer.chart_maker import ChartMaker
+        from cartographer.navigator import Navigator
+
+        cm = ChartMaker(".")
+        kg = KnowledgeGraph()
+        nav = Navigator(kg, cm)
+        result = nav.navigate(args.problem)
+        print(f"Problem: {result['problem']}")
+        if result["script"]:
+            print(f"Found script: {result['script']['name']}")
+        if result["hazards"]:
+            print(f"Hazards: {result['hazards']}")
+        if result["graph_neighbors"]:
+            print(f"Related: {result['graph_neighbors']}")
+
+    elif args.command == "chronicle":
+        from cartographer.chronicler import Chronicler
+
+        chron = Chronicler("chronicles")
+        if args.read:
+            print(chron.read_today())
+        elif args.message:
+            chron.write_entry(args.section, args.message)
+            print("Written.")
+        else:
+            summary = chron.summarize()
+            print(f"Today: {summary['entries']} entries")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())