loomwork 0.1.0__py3-none-any.whl

loomwork/__init__.py

@@ -0,0 +1,4 @@
+# one rename moves the copy marker and the registry file together
+PACKAGE_NAME = __name__
+# what a user types, while the package keeps its own name
+COMMAND_NAME = "loom"

loomwork/agents/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from loomwork.agents.base import Agent
+from loomwork.agents.claude_code import ClaudeCode
+from loomwork.agents.opencode import OpenCode
+
+
+def roster(claude_config_dir: Path) -> tuple[Agent, ...]:
+    """Every supported agent, in the order a machine converges them — Claude in the config dir of this profile."""
+    return (ClaudeCode(claude_config_dir), OpenCode())
+
+
+__all__ = ["Agent", "ClaudeCode", "OpenCode", "roster"]

loomwork/agents/base.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import shutil
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import ClassVar
+
+from loomwork import COMMAND_NAME, paths
+from loomwork.installation import Installation
+
+
+class Agent(ABC):
+    """A supported agent: global rules and skills go into `rules/` and `skills/` in its config dir.
+
+    An empty project path means the agent reads `.agents/` in the project itself, so nothing is laid for it there.
+    """
+
+    NAME: ClassVar[str]
+    # what the agent is called on PATH
+    COMMAND: ClassVar[str]
+    # what the agent calls the file it reads instructions from; empty when it reads none
+    AGENTS_MD_NAME: ClassVar[str] = ""
+    # the dir in a project it reads rules from, recursively
+    PROJECT_RULES_DIR: ClassVar[str] = ""
+    # the dir in a project it finds skills in, one level deep
+    PROJECT_SKILLS_DIR: ClassVar[str] = ""
+
+    @property
+    @abstractmethod
+    def config_dir(self) -> Path:
+        """Where the agent keeps its own configuration — our presence marker, and the root of its user-level paths."""
+
+    def bridge(self, installation: Installation) -> tuple[Path, ...]:
+        """Lay every user-level surface this agent names a path for, naming what was laid."""
+        return (
+            *self._publish_agents_md(installation),
+            *self._bridge_global_rules(installation),
+            *self._bridge_global_skills(installation),
+        )
+
+    def unbridge(self, installation: Installation) -> None:
+        """Mirror of bridge(): what is ours goes, anything the user put there stays."""
+        installation.clear_owned_in(self.config_dir / "skills")
+        rules_dir = self.config_dir / "rules"
+        installation.clear_owned_in(rules_dir)
+        paths.remove_if_empty(rules_dir)
+        if self.AGENTS_MD_NAME:
+            published = self.config_dir / self.AGENTS_MD_NAME
+            if installation.owned(published):
+                published.unlink()
+
+    def bridge_project(self, installation: Installation, project_dir: Path) -> tuple[Path, ...]:
+        """Point the agent at this project's rules and skills, naming where it reads them from."""
+        return (
+            *self._bridge_project_rules(installation, project_dir),
+            *self._bridge_project_skills(installation, project_dir),
+        )
+
+    def unbridge_project(self, installation: Installation, project_dir: Path) -> None:
+        """Drop our rule and skill links from the project, and the dirs when they empty out."""
+        for relative in (self.PROJECT_RULES_DIR, self.PROJECT_SKILLS_DIR):
+            if not relative:
+                continue
+            linked_dir = project_dir / relative
+            self._drop_whole_dir_link(installation, linked_dir)
+            installation.clear_owned_in(linked_dir)
+            paths.remove_if_empty(linked_dir)
+            paths.remove_if_empty(linked_dir.parent)
+
+    def project_folders(self) -> tuple[str, ...]:
+        """The folders this agent's bridges live in at a project's root — what the project's .gitignore must cover."""
+        relatives = (self.PROJECT_RULES_DIR, self.PROJECT_SKILLS_DIR)
+        return tuple(sorted({Path(relative).parts[0] for relative in relatives if relative}))
+
+    def is_present(self) -> bool:
+        """Whether the agent itself is on this machine — its config dir cannot say, since we create that ourselves."""
+        return bool(shutil.which(self.COMMAND))
+
+    def _publish_agents_md(self, installation: Installation) -> tuple[Path, ...]:
+        """Write the source's AGENTS.md under the name this agent reads it by."""
+        agents_md = installation.catalog.agents_md
+        if not self.AGENTS_MD_NAME or agents_md is None:
+            return ()
+        published = self.config_dir / self.AGENTS_MD_NAME
+        installation.place_file(agents_md, published)
+        # a file of the user's own was left alone, so it is not ours to report
+        if not installation.owned(published):
+            return ()
+        return (published,)
+
+    def _bridge_global_rules(self, installation: Installation) -> tuple[Path, ...]:
+        """Copy what the sources hand every project into the agent's own rules dir."""
+        rules_dir = self.config_dir / "rules"
+        catalog = installation.catalog
+        landed = installation.place(catalog.rule_files(catalog.global_rules), rules_dir)
+        # a source that hands out nothing leaves no empty dir behind
+        paths.remove_if_empty(rules_dir)
+        if not landed:
+            return ()
+        return (rules_dir,)
+
+    def _bridge_global_skills(self, installation: Installation) -> tuple[Path, ...]:
+        """Copy each globally wanted skill into the agent's own skills dir."""
+        skills_dir = self.config_dir / "skills"
+        catalog = installation.catalog
+        if not installation.place(catalog.skill_folders(catalog.global_skills), skills_dir):
+            return ()
+        return (skills_dir,)
+
+    def _bridge_project_rules(self, installation: Installation, project_dir: Path) -> tuple[Path, ...]:
+        """Link .agents/rules one level down in the agent's rules dir, beside whatever the project keeps there."""
+        copied_rules = paths.project_rules_dir(project_dir)
+        if not self.PROJECT_RULES_DIR:
+            return (copied_rules,)
+        rules_dir = project_dir / self.PROJECT_RULES_DIR
+        self._drop_whole_dir_link(installation, rules_dir)
+        rules_dir.mkdir(parents=True, exist_ok=True)
+        rules_link = rules_dir / COMMAND_NAME
+        installation.symlink(
+            paths.link_target(copied_rules, rules_dir),
+            rules_link,
+        )
+        if not installation.owned(rules_link):
+            return ()
+        return (rules_link,)
+
+    def _bridge_project_skills(self, installation: Installation, project_dir: Path) -> tuple[Path, ...]:
+        """One link per skill, since skills are found one level deep and the project's own stay beside ours."""
+        skills = paths.project_skills_dir(project_dir)
+        if not self.PROJECT_SKILLS_DIR:
+            if not skills.is_dir():
+                return ()
+            return (skills,)
+        skills_dir = project_dir / self.PROJECT_SKILLS_DIR
+        self._drop_whole_dir_link(installation, skills_dir)
+        placed = []
+        if skills.is_dir():
+            placed = sorted(skill for skill in skills.iterdir() if skill.is_dir())
+        if not placed and not skills_dir.is_dir():
+            return ()
+        installation.place_links(
+            {skill.name: paths.link_target(skill, skills_dir) for skill in placed},
+            skills_dir,
+        )
+        paths.remove_if_empty(skills_dir)
+        if not placed:
+            return ()
+        return (skills_dir,)
+
+    def _drop_whole_dir_link(self, installation: Installation, directory: Path) -> None:
+        """A link of ours standing in for the whole dir would put the links meant for it inside .agents/."""
+        if directory.is_symlink() and installation.owned(directory):
+            directory.unlink()

loomwork/agents/claude_code.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+import shlex
+import shutil
+import sys
+from pathlib import Path
+from typing import ClassVar
+
+from loomwork import COMMAND_NAME, paths
+from loomwork.agents.base import Agent
+from loomwork.declaration import Declaration
+from loomwork.installation import Installation
+
+
+class ClaudeCode(Agent):
+    """Mechanical loader and the host: its engine loads whatever files exist, so projects get wired — and its SessionStart hook is what runs sync for every agent."""
+
+    NAME = "claude"
+
+    COMMAND = "claude"
+    # at user level Claude reads CLAUDE.md only
+    AGENTS_MD_NAME = "CLAUDE.md"
+    # where Claude keeps its config unless it is launched with CONFIG_DIR_ENV
+    DEFAULT_CONFIG_DIR: ClassVar[Path] = Path("~/.claude").expanduser()
+    CONFIG_DIR_ENV: ClassVar[str] = "CLAUDE_CONFIG_DIR"
+    # read recursively, so our rules sit one level down beside the project's own
+    PROJECT_RULES_DIR = ".claude/rules"
+    PROJECT_SKILLS_DIR = ".claude/skills"
+    # a session waits on its start hooks, so ours has to be quick or get out of the way
+    HOOK_TIMEOUT_SECONDS: ClassVar[int] = 10
+
+    def __init__(self, config_dir: Path) -> None:
+        self._config_dir = config_dir
+
+    @property
+    def config_dir(self) -> Path:
+        return self._config_dir
+
+    def bridge(self, installation: Installation) -> tuple[Path, ...]:
+        """Claude's user-level surfaces, and the session hook that keeps every project in sync."""
+        return super().bridge(installation) + self._register_hook(installation)
+
+    def unbridge(self, installation: Installation) -> None:
+        """Mirror of bridge(), the session hook included."""
+        self._strip_hook(installation, self.config_dir / "settings.json")
+        super().unbridge(installation)
+
+    def our_hook(self, installation: Installation, hook: dict) -> bool:
+        """Ours by the command it calls, whatever path or entry-point name it was written with."""
+        # the hook line guards before it calls, so what it actually runs is the last statement
+        words = shlex.split(hook.get("command", "").rsplit(";", 1)[-1])
+        return bool(words) and Path(words[0]).name == COMMAND_NAME and "sync" in words[1:]
+
+    def _register_hook(self, installation: Installation) -> tuple[Path, ...]:
+        """Put our SessionStart hook in this config dir's settings, keeping every hook that is already there."""
+        settings_file = self.config_dir / "settings.json"
+        settings = json.loads(settings_file.read_text()) if settings_file.is_file() else {}
+        was = json.dumps(settings, sort_keys=True)
+        entries = settings.setdefault("hooks", {}).setdefault("SessionStart", [])
+        # replace-not-append: our own entries go first, so reruns and a moved install converge on one line
+        self._drop_our_entries(installation, entries)
+        hook = {"type": "command", "command": self._hook_command(installation), "timeout": self.HOOK_TIMEOUT_SECONDS}
+        entries.append({"hooks": [hook]})
+        if json.dumps(settings, sort_keys=True) != was:
+            settings_file.parent.mkdir(parents=True, exist_ok=True)
+            settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+        return (settings_file,)
+
+    def _strip_hook(self, installation: Installation, settings_file: Path) -> None:
+        """Remove exactly our entries from a settings file, and any key or file that empties out."""
+        if not settings_file.is_file():
+            return
+        settings = json.loads(settings_file.read_text())
+        entries = settings.get("hooks", {}).get("SessionStart")
+        if entries is None:
+            return
+        self._drop_our_entries(installation, entries)
+        if not entries:
+            del settings["hooks"]["SessionStart"]
+        if not settings["hooks"]:
+            del settings["hooks"]
+        if not settings:
+            # an empty settings file is litter, and Claude reads its absence the same way
+            settings_file.unlink()
+            paths.remove_if_empty(settings_file.parent)
+            return
+        settings_file.write_text(json.dumps(settings, indent=2) + "\n")
+
+    def _drop_our_entries(self, installation: Installation, entries: list[dict]) -> None:
+        for entry in entries:
+            entry["hooks"] = [hook for hook in entry.get("hooks", []) if not self.our_hook(installation, hook)]
+        entries[:] = [entry for entry in entries if entry.get("hooks")]
+
+    def _hook_command(self, installation: Installation) -> str:
+        """The guard is the opt-in: a project with no declaration never calls us, and the hook still exits clean."""
+        # the profile is named, so a session syncs the config dir it was launched with
+        return (
+            f'[ -f "$CLAUDE_PROJECT_DIR/{Declaration.FILE_NAME}" ] || exit 0; '
+            f"{self._loom_command()} --config-dir {shlex.quote(str(self.config_dir))} "
+            f'sync --for {self.NAME} "$CLAUDE_PROJECT_DIR"'
+        )
+
+    def _loom_command(self) -> str:
+        """How the hook calls us: by the full path we were started from, since its shell may not have us on PATH."""
+        found = shutil.which(sys.argv[0])
+        # started as anything but our own command (a test runner, python -m), the bare name is all we know
+        if not found or Path(found).name != COMMAND_NAME:
+            return COMMAND_NAME
+        return shlex.quote(str(Path(found).absolute()))

loomwork/agents/opencode.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from loomwork.agents.base import Agent
+
+
+class OpenCode(Agent):
+    """Instruction follower: its global AGENTS.md sends it to the rules, since it loads no rules dir on its own."""
+
+    NAME = "opencode"
+
+    COMMAND = "opencode"
+    AGENTS_MD_NAME = "AGENTS.md"
+
+    @property
+    def config_dir(self) -> Path:
+        # the XDG spec's config root, where an empty value counts as unset — as it does for OpenCode
+        return Path(os.environ.get("XDG_CONFIG_HOME") or "~/.config").expanduser() / "opencode"

loomwork/cli.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from loomwork import COMMAND_NAME
+from loomwork.agents import ClaudeCode
+from loomwork.declaration import Declaration
+from loomwork.loom import Loom
+from loomwork.questions import declare_project, wanted_agents, wanted_config_dir, wanted_source
+
+
+def project_dir(project: Path | None) -> Path:
+    return (project or Path.cwd()).resolve()
+
+
+def profile(config_dir: Path | None) -> Loom:
+    """The profile the flag names, else the one in Claude's default config dir."""
+    if config_dir:
+        return Loom(config_dir.expanduser())
+    return Loom(ClaudeCode.DEFAULT_CONFIG_DIR)
+
+
+@click.group(COMMAND_NAME)
+@click.option(
+    "--config-dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Claude's config dir, which this profile lives in. Defaults to ~/.claude; init asks when it is left out.",
+)
+@click.pass_context
+def cli(context: click.Context, config_dir: Path | None) -> None:
+    """Weave shared agent rules through your projects."""
+    context.obj = config_dir
+
+
+@cli.command()
+@click.argument("project", required=False, type=click.Path(file_okay=False, path_type=Path))
+@click.option("--agents", "chosen", metavar="NAMES", help="Comma-separated agents to wire, instead of being asked.")
+@click.option(
+    "--source",
+    "given_source",
+    help="Where the rules come from: a checkout, or <host>/<owner>/<repo>. Asked for when nothing else names one.",
+)
+@click.pass_obj
+def init(config_dir: Path | None, project: Path | None, chosen: str | None, given_source: str | None) -> None:
+    """Wire PROJECT and set up this profile.
+
+    PROJECT defaults to the current directory.
+    """
+    target = project_dir(project)
+    # the profile first: everything below is written into it
+    loom = Loom(wanted_config_dir(config_dir, target))
+    agents = wanted_agents(loom, target, chosen)
+    loom.init(target, agents, wanted_source(loom, target, given_source))
+    # the profile is set up either way; the project only joins in when it declares what it wants
+    if not Declaration.read(target) and not declare_project(loom, target):
+        return
+    loom.add(target, agents)
+
+
+@cli.command()
+@click.argument("project", required=False, type=click.Path(file_okay=False, path_type=Path))
+@click.pass_obj
+def remove(config_dir: Path | None, project: Path | None) -> None:
+    """Unwire PROJECT, undoing what loom put there.
+
+    PROJECT defaults to the current directory.
+    """
+    profile(config_dir).remove(project_dir(project))
+
+
+@cli.command()
+@click.argument("project", required=False, type=click.Path(file_okay=False, path_type=Path))
+@click.option("--all", "everywhere", is_flag=True, help="Refresh every wired project instead of this one.")
+@click.option("--for", "asked_by", metavar="NAME", help="The agent asking, as its session hook does.")
+@click.pass_obj
+def sync(config_dir: Path | None, project: Path | None, everywhere: bool, asked_by: str | None) -> None:
+    """Refresh PROJECT from its sources.
+
+    PROJECT defaults to the current directory.
+    """
+    target = None if everywhere else project_dir(project)
+    profile(config_dir).sync(target, asked_by)
+
+
+@cli.command()
+@click.pass_obj
+def status(config_dir: Path | None) -> None:
+    """Show the sources and the wired projects."""
+    profile(config_dir).status()
+
+
+@cli.command()
+@click.pass_obj
+def uninstall(config_dir: Path | None) -> None:
+    """Undo everything this profile installed."""
+    profile(config_dir).uninstall()
+
+
+if __name__ == "__main__":
+    cli()

loomwork/declaration.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar
+
+from loomwork.output import error
+
+
+@dataclass(frozen=True)
+class DeclaredSource:
+    """One [[source]] block of a declaration: where the rules repo is, and what the project takes from it."""
+
+    source: str
+    rules: tuple[str, ...] = ()
+    skills: tuple[str, ...] = ()
+
+    @classmethod
+    def of(cls, declared: dict) -> DeclaredSource:
+        return cls(
+            source=declared["source"],
+            rules=tuple(declared.get("rules", ())),
+            skills=tuple(declared.get("skills", ())),
+        )
+
+    def spelled(self) -> list[str]:
+        """The block's TOML lines, leaving out an empty rules or skills list."""
+        lines = [f'source = "{self.source}"']
+        for key, names in (("rules", self.rules), ("skills", self.skills)):
+            if names:
+                quoted = ", ".join(f'"{name}"' for name in names)
+                lines.append(f"{key} = [{quoted}]")
+        return lines
+
+
+@dataclass(frozen=True)
+class Declaration:
+    """A project's .agents.toml: the sources it uses and what it takes from each. Its presence is the opt-in."""
+
+    FILE_NAME: ClassVar[str] = ".agents.toml"
+    TABLE: ClassVar[str] = "source"
+
+    sources: tuple[DeclaredSource, ...]
+
+    @classmethod
+    def read(cls, project_dir: Path) -> Declaration | None:
+        """The project's declaration, or None when it carries none — which reads as the opt-out."""
+        declaration_file = project_dir / cls.FILE_NAME
+        if not declaration_file.is_file():
+            return None
+        declared = _parsed(declaration_file)
+        listed = declared.get(cls.TABLE)
+        if isinstance(listed, list):
+            sources = tuple(DeclaredSource.of(entry) for entry in listed if entry.get("source"))
+            if not sources:
+                return None
+            return cls(sources)
+        if not declared.get("source"):
+            return None
+        return cls((DeclaredSource.of(declared),))
+
+    def write(self, project_dir: Path) -> Path:
+        """Write the file into the project, returning its path."""
+        declaration_file = project_dir / self.FILE_NAME
+        declaration_file.write_text("\n".join(self._lines()) + "\n")
+        return declaration_file
+
+    @property
+    def rules(self) -> tuple[str, ...]:
+        """Every rule this project asks for, in the order its sources were declared."""
+        return tuple(name for declared in self.sources for name in declared.rules)
+
+    @property
+    def skills(self) -> tuple[str, ...]:
+        return tuple(name for declared in self.sources for name in declared.skills)
+
+    def _lines(self) -> list[str]:
+        lines = []
+        for declared in self.sources:
+            lines += [f"[[{self.TABLE}]]", *declared.spelled(), ""]
+        return lines[:-1]
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """A source's loom.toml: the sources it builds on, and the rules and skills it hands every project."""
+
+    FILE_NAME: ClassVar[str] = "loom.toml"
+    TABLE: ClassVar[str] = "global"
+
+    # the same [[source]] blocks a project writes, meaning "I build on this" rather than "I take this"
+    builds_on: tuple[str, ...] = ()
+    global_rules: tuple[str, ...] = ()
+    global_skills: tuple[str, ...] = ()
+
+    @classmethod
+    def read(cls, source: Path) -> Manifest:
+        """The source's manifest — an empty one when it has no loom.toml."""
+        manifest_file = source / cls.FILE_NAME
+        if not manifest_file.is_file():
+            return cls()
+        document = _parsed(manifest_file)
+        marked_global = document.get(cls.TABLE, {})
+        blocks = document.get(Declaration.TABLE)
+        if not isinstance(blocks, list):
+            blocks = []
+        return cls(
+            builds_on=tuple(entry["source"] for entry in blocks if entry.get("source")),
+            global_rules=tuple(marked_global.get("rules", ())),
+            global_skills=tuple(marked_global.get("skills", ())),
+        )
+
+
+def _parsed(toml_file: Path) -> dict:
+    """The file's contents, or a one-line failure naming it — a session hook's error shows its first line only."""
+    try:
+        return tomllib.loads(toml_file.read_text())
+    except tomllib.TOMLDecodeError as broken:
+        error(f"{toml_file}: {broken}")

loomwork/git.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from subprocess import CompletedProcess
+
+# a session's first answer waits on the hook that updates, so a slow network has to lose rather than hold it up
+UPDATE_TIMEOUT_SECONDS = 8
+CLONE_TIMEOUT_SECONDS = 120
+
+
+def run(*arguments: str, inside: Path | None = None, timeout: float | None = None) -> CompletedProcess[str] | None:
+    """One git call, or None when it failed — the user's own git, so their ssh agent and credential helpers apply."""
+    located = ["-C", str(inside)] if inside else []
+    # nobody is there to type a password or accept a host key, so git must fail instead of waiting for one
+    unattended = {
+        "GIT_TERMINAL_PROMPT": "0",
+        "GIT_SSH_COMMAND": os.environ.get("GIT_SSH_COMMAND", "ssh -o BatchMode=yes"),
+    }
+    try:
+        ran = subprocess.run(
+            ["git", *located, *arguments],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+            env={**os.environ, **unattended},
+        )
+    except subprocess.TimeoutExpired:
+        # macOS ships no timeout(1), so this bound is the only one the hook gets
+        return None
+    return ran if ran.returncode == 0 else None
+
+
+def clone(url: str, into: Path) -> bool:
+    """Clone the tip alone — what loom reads, with no history to grow."""
+    return bool(run("clone", "--quiet", "--depth", "1", url, str(into), timeout=CLONE_TIMEOUT_SECONDS))
+
+
+def pull(path: Path) -> bool:
+    """Fast-forward a checkout, reporting whether it worked."""
+    return bool(run("pull", "--ff-only", "--quiet", inside=path, timeout=UPDATE_TIMEOUT_SECONDS))
+
+
+def match_remote(path: Path) -> bool:
+    """Make a clone exactly its remote's tip, rewritten history included, reporting whether it worked."""
+    if not run("fetch", "--quiet", "--depth", "1", "origin", inside=path, timeout=UPDATE_TIMEOUT_SECONDS):
+        return False
+    return bool(run("reset", "--quiet", "--hard", "FETCH_HEAD", inside=path))
+
+
+def origin(path: Path) -> str | None:
+    """The url a checkout came from — None when it has no origin, which a local working copy may not."""
+    asked = run("remote", "get-url", "origin", inside=path)
+    if asked is None:
+        return None
+    return asked.stdout.strip().rstrip("/").removesuffix(".git")
+
+
+def root(path: Path) -> Path:
+    """The repo a path sits in, or the path itself when it is in none."""
+    for candidate in (path, *path.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return path