fusion-cli 1.1.0__py3-none-any.whl

fusion/indexer.py

@@ -0,0 +1,75 @@
+"""INDEX.md generation — two implementations, identical bytes (SPEC §8)."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from . import ledger
+from .document import read_document
+
+MARKER = "<!-- generated by fusion index — do not edit -->"
+INDEXED_ZONES: tuple[str, ...] = ("library", "activities")
+
+
+def _section_key(section: str) -> tuple[int, str]:
+    if section == "./":
+        return (0, section)
+    if section.startswith("archive/"):
+        return (2, section)
+    return (1, section)
+
+
+def _zone_documents(zone_dir: Path) -> list[Path]:
+    """Every document file in the zone — the single filter both the index
+    content and the ledger's document count derive from."""
+    return [
+        p
+        for p in sorted(zone_dir.rglob("*.md"))
+        if p.name != "INDEX.md"
+        and not any(part.startswith(".")
+                    for part in p.relative_to(zone_dir).parts)
+    ]
+
+
+def generate(zone_dir: Path, zone_name: str) -> str:
+    sections: dict[str, list] = {}
+    for path in _zone_documents(zone_dir):
+        rel = path.relative_to(zone_dir)
+        parent = rel.parent.as_posix()
+        section = "./" if parent == "." else parent + "/"
+        sections.setdefault(section, []).append((rel, read_document(path)))
+
+    lines = [MARKER, f"# {zone_name.capitalize()} Index"]
+    for section in sorted(sections, key=_section_key):
+        lines += ["", f"## {section}", ""]
+        for rel, doc in sorted(sections[section], key=lambda t: t[0].as_posix()):
+            title = doc.title or rel.stem
+            summary = doc.summary_line or ""
+            aurora = doc.aurora or ""
+            lines.append(f"- [{title}]({rel.as_posix()}) — {summary} ({aurora})")
+    return "\n".join(lines) + "\n"
+
+
+def write_indexes(
+    bucket_root: Path,
+    actor: str | None = None,
+    at: datetime | None = None,
+) -> list[dict]:
+    results = []
+    for zone in INDEXED_ZONES:
+        zone_dir = bucket_root / zone
+        if not zone_dir.is_dir():
+            continue
+        content = generate(zone_dir, zone)
+        index_path = zone_dir / "INDEX.md"
+        old = index_path.read_bytes() if index_path.exists() else None
+        changed = old != content.encode("utf-8")
+        if changed:
+            index_path.write_text(content, encoding="utf-8", newline="\n")
+        count = len(_zone_documents(zone_dir))
+        if changed and actor:
+            plural = "s" if count != 1 else ""
+            ledger.append(bucket_root, actor, "indexed",
+                          f"{zone}/ ({count} document{plural})", at=at)
+        results.append({"zone": zone, "documents": count, "changed": changed})
+    return results

fusion/ledger.py

@@ -0,0 +1,106 @@
+"""LEDGER.md — append-only, chronological, exactly one writer (SPEC §6)."""
+from __future__ import annotations
+
+import getpass
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+VERBS: tuple[str, ...] = (
+    "created", "converted", "classified", "indexed", "moved",
+    "promoted", "archived", "restructured", "shipped", "reflected",
+    "noted",
+)
+
+_ENTRY_RE = re.compile(r"^- (\d{2}:\d{2}) · (\S+) · (\S+) · (.*)$")
+_NOTE_SEP = ' — "'
+
+
+@dataclass
+class Entry:
+    date: str
+    time: str
+    actor: str
+    verb: str
+    obj: str
+    note: str | None = None
+
+
+def parse(text: str) -> list[Entry]:
+    """Liberal reader: lines that don't match the grammar are ignored."""
+    entries: list[Entry] = []
+    date: str | None = None
+    for line in text.split("\n"):
+        if line.startswith("## "):
+            date = line[3:].strip()
+            continue
+        m = _ENTRY_RE.match(line)
+        if not (m and date):
+            continue
+        obj, note = m.group(4), None
+        if _NOTE_SEP in obj and obj.endswith('"'):
+            obj, _, rest = obj.partition(_NOTE_SEP)
+            note = rest[:-1]
+        entries.append(Entry(date, m.group(1), m.group(2), m.group(3), obj, note))
+    return entries
+
+
+def read(bucket_root: Path) -> list[Entry]:
+    path = bucket_root / "LEDGER.md"
+    if not path.exists():
+        return []
+    return parse(path.read_text(encoding="utf-8"))
+
+
+def format_line(entry: Entry) -> str:
+    line = f"- {entry.time} · {entry.actor} · {entry.verb} · {entry.obj}"
+    if entry.note:
+        line += f' — "{entry.note}"'
+    return line
+
+
+def append(
+    bucket_root: Path,
+    actor: str,
+    verb: str,
+    obj: str,
+    note: str | None = None,
+    at: datetime | None = None,
+) -> Entry:
+    """The one writer. Strict: refuses verbs outside the eleven.
+
+    Actors must be single tokens; objects and notes are collapsed to one
+    line — the register must round-trip through its own reader.
+    """
+    if verb not in VERBS:
+        raise ValueError(f"verb must be one of: {', '.join(VERBS)}")
+    if not actor or actor != actor.strip() or any(c.isspace() for c in actor) or "·" in actor:
+        raise ValueError(
+            f"actor must be a single token with no spaces or '·': {actor!r}"
+        )
+    obj = " ".join(obj.split())
+    if note is not None:
+        note = " ".join(note.split())
+    at = at or datetime.now()
+    entry = Entry(at.strftime("%Y-%m-%d"), at.strftime("%H:%M"),
+                  actor, verb, obj, note)
+    path = bucket_root / "LEDGER.md"
+    text = path.read_text(encoding="utf-8") if path.exists() else "# Ledger\n"
+    lines = text.rstrip("\n").split("\n")
+    heading = f"## {entry.date}"
+    last_heading = next(
+        (l for l in reversed(lines) if l.startswith("## ")), None
+    )
+    if last_heading == heading:
+        lines.append(format_line(entry))
+    else:
+        lines.extend(["", heading, format_line(entry)])
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+    return entry
+
+
+def resolve_actor(explicit: str | None = None) -> str:
+    """--as > FUSION_ACTOR > OS username. The pen always has a name."""
+    return explicit or os.environ.get("FUSION_ACTOR") or getpass.getuser()

fusion/manifest.py

@@ -0,0 +1,33 @@
+"""sources/MANIFEST.md — the register of preserved originals (SPEC §7)."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_ROW_RE = re.compile(r"^\| (.+?) \| (.+?) \| (.+?) \| (.+?) \| (.+?) \|$")
+
+
+@dataclass
+class ManifestRow:
+    file: str
+    added: str
+    by: str
+    sha256: str
+    library: str
+
+
+def read(bucket_root: Path) -> list[ManifestRow]:
+    path = bucket_root / "sources" / "MANIFEST.md"
+    if not path.exists():
+        return []
+    rows = []
+    for line in path.read_text(encoding="utf-8").split("\n"):
+        m = _ROW_RE.match(line)
+        if not m:
+            continue
+        cells = [c.strip() for c in m.groups()]
+        if cells[0] == "file" or set(cells[0]) <= {"-"}:
+            continue  # header and separator rows
+        rows.append(ManifestRow(*cells))
+    return rows

fusion/scaffold.py

@@ -0,0 +1,120 @@
+"""fusion new — a complete bucket, born conformant (SPEC §2, §3)."""
+from __future__ import annotations
+
+import os
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+
+from . import hub, indexer, ledger
+from .bucket import ZONES
+
+BUCKET_TEMPLATE = """---
+name: {name}
+kind: {kind}
+description: {description}
+fusion_version: "1.0"
+created: {created}
+inbox_max_age_days: 7
+reflection_cadence: weekly
+---
+
+{description_body}
+
+## Conventions
+
+### Rules
+
+### Delegations
+"""
+
+
+def _yaml_scalar(value: str) -> str:
+    """Render a string as a safe single-line YAML scalar (quoted only when needed)."""
+    style = '"' if "\n" in value else None
+    return yaml.safe_dump(
+        value, allow_unicode=True, width=2**31 - 1, default_style=style
+    ).split("\n")[0]
+
+MANIFEST_HEADER = (
+    "# Manifest\n\n| file | added | by | sha256 | library |\n"
+    "|---|---|---|---|---|\n"
+)
+
+
+class ScaffoldError(Exception):
+    pass
+
+
+def new_bucket(
+    path: Path,
+    name: str | None = None,
+    kind: str = "personal",
+    description: str | None = None,
+    actor: str = "human",
+    at: datetime | None = None,
+    register: bool = True,
+) -> tuple[Path, list[str]]:
+    root = path.expanduser().resolve()
+    name = name or root.name
+    description = description or f"A {kind} bucket. Describe me."
+    at = at or datetime.now()
+
+    if root.exists() and not root.is_dir():
+        raise ScaffoldError(f"target exists and is not a directory: {root}")
+    if root.exists() and any(root.iterdir()):
+        raise ScaffoldError(f"target exists and is not empty: {root}")
+    if register and any(e.name == name for e in hub.load()):
+        raise ScaffoldError(f"bucket '{name}' is already registered in the hub")
+
+    for zone in ZONES:
+        (root / zone).mkdir(parents=True, exist_ok=True)
+    for zone in ("inbox", "workbench", "output"):
+        (root / zone / ".gitkeep").write_text("", encoding="utf-8", newline="\n")
+    (root / "BUCKET.md").write_text(
+        BUCKET_TEMPLATE.format(
+            name=_yaml_scalar(name), kind=_yaml_scalar(kind),
+            description=_yaml_scalar(description),
+            description_body=description,
+            created=at.strftime("%Y-%m-%d"),
+        ),
+        encoding="utf-8", newline="\n",
+    )
+    (root / "sources" / "MANIFEST.md").write_text(
+        MANIFEST_HEADER, encoding="utf-8", newline="\n"
+    )
+    ledger.append(root, actor, "created", "BUCKET.md", note="bucket born", at=at)
+    indexer.write_indexes(root, actor=None)
+
+    warnings: list[str] = []
+    for cmd in (
+        ["git", "init", "-q"],
+        ["git", "add", "-A"],
+        ["git", "commit", "-q", "-m", "fusion new: bucket born"],
+    ):
+        try:
+            result = subprocess.run(
+                cmd, cwd=root, capture_output=True, text=True, timeout=30,
+                env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+            )
+            if result.returncode != 0:
+                warnings.append(
+                    f"{' '.join(cmd)}: {result.stderr.strip() or 'failed'}"
+                )
+                break
+        except FileNotFoundError:
+            warnings.append("git not found — bucket created without a repository")
+            break
+        except subprocess.TimeoutExpired:
+            warnings.append(f"{' '.join(cmd)}: timed out after 30s")
+            break
+
+    if register:
+        try:
+            hub.add(hub.HubEntry(name, kind, hub.display_path(root), description))
+        except (ValueError, OSError) as exc:
+            warnings.append(f"hub registration failed: {exc}")
+
+    return root, warnings

fusion/setup.py

@@ -0,0 +1,300 @@
+"""fusion setup — the installer brain. Bootstraps hand off here; every
+mechanical decision about skills placement lives in this module so it is
+written once, runs identically on macOS/Linux/Windows, and is tested.
+
+Never destroys content it did not create: foreign entries are warned and
+left unless --force. Writes only under the given directories.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata
+import importlib.resources
+import os
+import shutil
+from pathlib import Path
+
+
+class SetupError(Exception):
+    """A setup step that cannot proceed."""
+
+
+def payload_root() -> Path:
+    bundled = importlib.resources.files("fusion") / "_skills"
+    p = Path(str(bundled))
+    if p.is_dir() and sorted(p.glob("fusion-*")):
+        return p
+    repo = Path(__file__).resolve().parents[3] / "skills"
+    if repo.is_dir() and sorted(repo.glob("fusion-*")):
+        return repo
+    raise SetupError(
+        "no skills payload: neither bundled fusion/_skills nor a repo "
+        "skills/ directory — reinstall fusion-cli"
+    )
+
+
+def payload_version() -> str:
+    try:
+        return importlib.metadata.version("fusion-cli")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"
+
+
+def tree_digest(path: Path) -> str:
+    h = hashlib.sha256()
+    for f in sorted(p for p in path.rglob("*") if p.is_file()):
+        h.update(f.relative_to(path).as_posix().encode())
+        h.update(b"\0")
+        h.update(f.read_bytes())
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def install_canonical(payload: Path, skills_dir: Path,
+                      force: bool) -> list[dict]:
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    results = []
+    for skill in sorted(payload.glob("fusion-*")):
+        dest = skills_dir / skill.name
+        if dest.is_symlink():
+            if not force:
+                results.append({
+                    "skill": skill.name, "action": "left",
+                    "detail": f"{dest} is a symlink you manage — "
+                              f"--force replaces it"})
+                continue
+            dest.unlink()
+            shutil.copytree(skill, dest)
+            results.append({"skill": skill.name, "action": "replaced",
+                            "detail": str(dest)})
+            continue
+        if dest.is_dir():
+            if tree_digest(dest) == tree_digest(skill):
+                results.append({"skill": skill.name, "action": "up-to-date",
+                                "detail": str(dest)})
+                continue
+            shutil.rmtree(dest)
+            shutil.copytree(skill, dest)
+            results.append({"skill": skill.name, "action": "updated",
+                            "detail": str(dest)})
+            continue
+        if dest.exists():
+            if not force:
+                results.append({"skill": skill.name, "action": "left",
+                                "detail": f"{dest} is a file — "
+                                          f"--force replaces"})
+                continue
+            dest.unlink()
+            shutil.copytree(skill, dest)
+            results.append({"skill": skill.name, "action": "replaced",
+                            "detail": str(dest)})
+            continue
+        shutil.copytree(skill, dest)
+        results.append({"skill": skill.name, "action": "installed",
+                        "detail": str(dest)})
+    return results
+
+
+# One row per agent. mode "link": the agent does not read the standard
+# ~/.agents/skills dir, so each fusion-* skill gets a symlink (or copy)
+# in its own skills dir. mode "standard": the agent reads the standard
+# dir — creating links there too would load every skill twice.
+AGENTS = [
+    {"name": "Claude Code", "marker": ".claude",
+     "skills_subdir": ".claude/skills", "mode": "link",
+     "docs_url": "https://code.claude.com/docs/en/skills"},
+    {"name": "Codex", "marker": ".codex",
+     "skills_subdir": ".codex/skills", "mode": "link",
+     "docs_url": "https://developers.openai.com/codex/skills"},
+    {"name": "Pi", "marker": ".pi",
+     "skills_subdir": ".pi/agent/skills", "mode": "link",
+     "docs_url": "https://pi.dev/docs/latest/skills"},
+    {"name": "Cursor", "marker": ".cursor",
+     "skills_subdir": ".agents/skills", "mode": "standard",
+     "docs_url": "https://cursor.com/docs/skills"},
+    {"name": "Gemini CLI", "marker": ".gemini",
+     "skills_subdir": ".agents/skills", "mode": "standard",
+     "docs_url": "https://geminicli.com/docs/cli/skills"},
+    {"name": "opencode", "marker": ".config/opencode",
+     "skills_subdir": ".agents/skills", "mode": "standard",
+     "docs_url": "https://opencode.ai/docs/skills"},
+    {"name": "Goose", "marker": ".config/goose",
+     "skills_subdir": ".agents/skills", "mode": "standard",
+     "docs_url": "https://block.github.io/goose/docs/mcp/skills-mcp"},
+]
+
+
+def detect_agents(home: Path) -> list[dict]:
+    found = []
+    for row in AGENTS:
+        if (home / row["marker"]).is_dir():
+            found.append({**row, "skills_dir": home / row["skills_subdir"]})
+    return found
+
+
+def _points_into(link: Path, canonical: Path) -> bool:
+    try:
+        return link.resolve().is_relative_to(canonical.resolve())
+    except OSError:
+        return False
+
+
+def fan_out(canonical: Path, agents: list[dict], force: bool) -> list[dict]:
+    results = []
+    skills = sorted(canonical.glob("fusion-*"))
+    for agent in agents:
+        if agent["mode"] == "standard":
+            if canonical.resolve() != agent["skills_dir"].resolve():
+                detail = (f"reads ~/.agents/skills — but your skills are "
+                          f"at {canonical}, which this agent does not read")
+            else:
+                detail = "reads ~/.agents/skills — nothing to do"
+            results.append({"agent": agent["name"], "skill": "*",
+                            "action": "standard", "detail": detail})
+            continue
+        agent["skills_dir"].mkdir(parents=True, exist_ok=True)
+        for skill in skills:
+            target = agent["skills_dir"] / skill.name
+            row = {"agent": agent["name"], "skill": skill.name}
+            replaced = False
+            if target.is_symlink():
+                if _points_into(target, canonical):
+                    results.append({**row, "action": "up-to-date",
+                                    "detail": str(target)})
+                    continue
+                if not force:
+                    results.append({**row, "action": "left",
+                                    "detail": f"{target} links elsewhere — "
+                                              f"--force replaces"})
+                    continue
+                target.unlink()
+                replaced = True
+            elif target.is_dir():
+                if tree_digest(target) == tree_digest(skill):
+                    pass          # our current copy, refresh below keeps it current
+                elif (target / ".fusion-setup").is_file():
+                    pass          # our stale copy (sentinel proves provenance) — refresh
+                elif not force:
+                    results.append({**row, "action": "left",
+                                    "detail": f"{target} exists and is not "
+                                              f"ours — --force replaces"})
+                    continue
+                else:
+                    replaced = True
+                shutil.rmtree(target)
+            elif target.exists():
+                if not force:
+                    results.append({**row, "action": "left",
+                                    "detail": f"{target} is a file — "
+                                              f"--force replaces"})
+                    continue
+                target.unlink()
+                replaced = True
+            try:
+                os.symlink(skill, target, target_is_directory=True)
+                results.append({**row,
+                                "action": "replaced" if replaced else "linked",
+                                "detail": str(target)})
+            except OSError:
+                shutil.copytree(skill, target)
+                (target / ".fusion-setup").write_text(
+                    f"{payload_version()}\n{tree_digest(skill)}\n",
+                    encoding="utf-8", newline="\n")
+                results.append({**row,
+                                "action": "replaced" if replaced else "copied",
+                                "detail": f"{target} (symlinks unavailable — "
+                                          f"re-run setup after upgrades)"})
+    return results
+
+
+def remove_all(canonical: Path, home: Path) -> list[dict]:
+    results = []
+    for agent in detect_agents(home):
+        if agent["mode"] == "standard":
+            continue
+        entries = (sorted(agent["skills_dir"].glob("fusion-*"))
+                   if agent["skills_dir"].is_dir() else [])
+        for entry in entries:
+            row = {"agent": agent["name"], "skill": entry.name}
+            if entry.is_symlink() and _points_into(entry, canonical):
+                entry.unlink()
+                results.append({**row, "action": "removed",
+                                "detail": str(entry)})
+            elif entry.is_dir() and not entry.is_symlink() \
+                    and (canonical / entry.name).is_dir() \
+                    and ((entry / ".fusion-setup").is_file()
+                         or tree_digest(entry) == tree_digest(canonical / entry.name)):
+                shutil.rmtree(entry)
+                results.append({**row, "action": "removed",
+                                "detail": str(entry)})
+            else:
+                results.append({**row, "action": "left",
+                                "detail": f"{entry} is not attributable to "
+                                          f"setup — left in place"})
+    for skill in sorted(canonical.glob("fusion-*")):
+        row = {"agent": "canonical", "skill": skill.name}
+        if skill.is_symlink():
+            results.append({**row, "action": "left",
+                            "detail": f"{skill} is a symlink you manage"})
+            continue
+        shutil.rmtree(skill)
+        results.append({**row, "action": "removed", "detail": str(skill)})
+    return results
+
+
+def environment_advice(home: Path) -> list[dict]:
+    import os as _os
+    import subprocess
+    advice = []
+    if shutil.which("fusion") is None:
+        # spec §4d: fix PATH via uv's own mechanism when allowed
+        if _os.environ.get("FUSION_NO_MODIFY_PATH") != "1" \
+                and shutil.which("uv") is not None:
+            done = subprocess.run(["uv", "tool", "update-shell"],
+                                  capture_output=True).returncode == 0
+            advice.append({
+                "topic": "path",
+                "text": "uv tool update-shell ran — restart your shell so "
+                        "`fusion` resolves" if done else
+                        "uv tool update-shell failed — add uv's tool bin "
+                        "dir to PATH yourself (`uv tool dir --bin`)"})
+        else:
+            advice.append({
+                "topic": "path",
+                "text": "the uv tool bin dir is not on PATH — run: "
+                        "uv tool update-shell (or manage PATH yourself)"})
+    if shutil.which("git") is None:
+        advice.append({
+            "topic": "git",
+            "text": "git not found — buckets are git repos; install git"})
+    if shutil.which("soffice") is None:
+        advice.append({
+            "topic": "libreoffice",
+            "text": "LibreOffice (soffice) not found — only docx/pptx/"
+                    "legacy-office/html intake needs it "
+                    "(brew install --cask libreoffice · apt install "
+                    "libreoffice · winget install LibreOffice.LibreOffice)"})
+    return advice
+
+
+def run_setup(home: Path, skills_dir: Path, force: bool,
+              no_agents: bool, remove: bool) -> dict:
+    if remove:
+        results = remove_all(skills_dir, home)
+        return {"ok": True, "removed": results,
+                "next": ["uv tool uninstall fusion-cli"]}
+    payload = payload_root()
+    skills = install_canonical(payload, skills_dir, force)
+    agents = [] if no_agents else fan_out(
+        skills_dir, detect_agents(home), force)
+    return {
+        "ok": True,
+        "cli": {"version": payload_version()},
+        "skills": {"dir": str(skills_dir), "results": skills},
+        "agents": agents,
+        "advice": environment_advice(home),
+        "next": ["fusion new ~/buckets/personal --kind personal "
+                 "--description \"Home base.\"",
+                 "https://github.com/bluewaves-creations/fusion/blob/"
+                 "main/docs/GETTING-STARTED.md"],
+    }