agentmeld 0.1.0__py3-none-any.whl

agentmeld/__init__.py

@@ -0,0 +1,12 @@
+"""agentmeld -- one AI context, every agent.
+
+A repo used with several AI coding tools ends up holding the same knowledge in
+``CLAUDE.md``, ``.github/copilot-instructions.md`` and ``.cursor/rules/*.mdc``,
+drifting apart. agentmeld keeps one canonical copy in ``.ai/`` and mirrors it
+into every vendor location -- as a real symlink where the formats agree, and as
+a small generated file where they do not.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

agentmeld/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentmeld/adopt.py

@@ -0,0 +1,243 @@
+"""Pulling vendor files back into the canonical tree.
+
+This is the direction the existing tools do not automate, and the reason watch
+mode can work: when an agent writes a brand-new ``.claude/skills/foo/SKILL.md``,
+that content becomes canonical and is fanned out to every other tool, instead of
+staying stranded in one vendor's directory.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .config import Config
+from .model import Adapter, AssetKind, KindSpec, Strategy
+from .state import State
+from .transform import HEADER_TOKEN, parse_header
+from .transform import frontmatter as fm
+
+__all__ = ["classify_path", "reverse_frontmatter", "canonical_dest", "run_adopt", "is_ours"]
+
+
+# ---------------------------------------------------------------------------
+# which adapter/kind does a path belong to?
+# ---------------------------------------------------------------------------
+
+
+def _target_regex(template: str) -> "re.Pattern":
+    parts = template.split("{slug}")
+    pattern = "(?P<slug>.+)".join(re.escape(p) for p in parts)
+    return re.compile("^" + pattern + "$")
+
+
+def classify_path(
+    rel_path: str,
+    registry: Dict[str, Adapter],
+) -> Optional[Tuple[Adapter, KindSpec, str]]:
+    """Match a repo-relative path against every adapter's target templates.
+
+    Templates with a ``{slug}`` are preferred over literal ones, so
+    ``.github/instructions/x.instructions.md`` is recognised as a rule rather
+    than accidentally matching something broader.
+    """
+    best: Optional[Tuple[Adapter, KindSpec, str]] = None
+    for adapter in registry.values():
+        for spec in adapter.kinds.values():
+            match = _target_regex(spec.target).match(rel_path)
+            if not match:
+                continue
+            slug = match.groupdict().get("slug") or spec.kind.value
+            candidate = (adapter, spec, slug)
+            if "{slug}" in spec.target:
+                return candidate
+            best = best or candidate
+    return best
+
+
+def is_ours(path: Path, rel_path: str, state: State) -> bool:
+    """True when this path is already a mirror we manage.
+
+    Checked three ways, because any one of them can be stale: state, a symlink
+    pointing into the canonical tree, and our generated header. This is the guard
+    that stops watch mode from adopting its own output in a loop.
+    """
+    if state.get(rel_path) is not None:
+        return True
+    if path.is_symlink():
+        return True
+    if path.is_file():
+        try:
+            head = path.read_text(encoding="utf-8", errors="replace")[:4096]
+        except OSError:
+            return False
+        if HEADER_TOKEN in head:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# vendor frontmatter -> canonical frontmatter
+# ---------------------------------------------------------------------------
+
+
+def reverse_frontmatter(vendor: Dict[str, object], spec: KindSpec) -> Dict[str, object]:
+    """Invert an adapter's frontmatter mapping.
+
+    Ambiguity is real here: Copilot maps both ``globs`` and ``always`` onto
+    ``applyTo``. It is resolved by value -- ``applyTo: "**"`` came from
+    ``always``, anything else from ``globs``.
+    """
+    plain: Dict[str, Tuple[str, str]] = {}
+    flags: Dict[str, List[Tuple[str, str]]] = {}
+
+    for canonical_key, directive in spec.frontmatter.items():
+        if directive == fm.DROP:
+            continue
+        if "!" in directive:
+            vendor_key, _, literal = directive.partition("!")
+            flags.setdefault(vendor_key, []).append((canonical_key, literal))
+        elif directive.endswith(":comma"):
+            plain[directive[: -len(":comma")]] = (canonical_key, "comma")
+        else:
+            plain[directive] = (canonical_key, "plain")
+
+    out: Dict[str, object] = {}
+    for vendor_key, value in vendor.items():
+        matched = False
+        for canonical_key, literal in flags.get(vendor_key, []):
+            if _matches_literal(value, literal):
+                out[canonical_key] = True
+                matched = True
+                break
+        if matched:
+            continue
+        if vendor_key in plain:
+            canonical_key, how = plain[vendor_key]
+            if how == "comma" and isinstance(value, str):
+                out[canonical_key] = [p.strip() for p in value.split(",") if p.strip()]
+            else:
+                out[canonical_key] = value
+            continue
+        if vendor_key in spec.defaults and spec.defaults[vendor_key] == value:
+            continue  # a default we wrote ourselves carries no information
+        if vendor_key not in plain and vendor_key not in flags:
+            out[vendor_key] = value  # unknown key: keep it rather than lose it
+    return out
+
+
+def _matches_literal(value: object, literal: str) -> bool:
+    lowered = literal.strip().lower()
+    if lowered in ("true", "false"):
+        return bool(value) is (lowered == "true")
+    return value == literal
+
+
+# ---------------------------------------------------------------------------
+# adoption
+# ---------------------------------------------------------------------------
+
+
+def canonical_dest(config: Config, kind: AssetKind, slug: str) -> Path:
+    base = config.canonical
+    if kind is AssetKind.INSTRUCTIONS:
+        return base / "instructions.md"
+    if kind is AssetKind.MCP:
+        return base / "mcp.json"
+    if kind is AssetKind.SKILL:
+        return base / "skills" / slug / "SKILL.md"
+    return base / {AssetKind.RULE: "rules", AssetKind.AGENT: "agents", AssetKind.COMMAND: "commands"}[kind] / (slug + ".md")
+
+
+def adopt_path(
+    path: Path,
+    config: Config,
+    registry: Dict[str, Adapter],
+    state: State,
+    dry_run: bool = False,
+) -> Optional[str]:
+    """Move one vendor file into the canonical tree. Returns a log line, or None."""
+    from .planner import now_iso
+
+    rel = config.rel(path)
+    if not path.exists():
+        return None
+    if is_ours(path, rel, state):
+        return None
+
+    hit = classify_path(rel, registry)
+    if hit is None:
+        return None
+    adapter, spec, slug = hit
+    if spec.strategy is Strategy.MERGE and hit[1].kind is not AssetKind.MCP:
+        return None
+
+    dest = canonical_dest(config, spec.kind, slug)
+    if dest.exists():
+        return "{}: canonical {} already exists, left alone".format(rel, config.rel(dest))
+
+    if dry_run:
+        return "{} -> {} (would adopt)".format(rel, config.rel(dest))
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if spec.kind is AssetKind.SKILL:
+        # A skill is its whole directory. Moving only SKILL.md would strand the
+        # sidecars and leave a real directory where the symlink belongs.
+        source_dir, dest_dir = path.parent, dest.parent
+        if dest_dir.exists():
+            shutil.rmtree(str(dest_dir))
+        shutil.move(str(source_dir), str(dest_dir))
+        state.record_adoption(config.rel(dest), rel, now_iso())
+        return "{} -> {} (adopted whole skill dir from {})".format(
+            config.rel(source_dir), config.rel(dest_dir), adapter.name
+        )
+
+    if spec.kind is AssetKind.MCP or path.suffix == ".json":
+        shutil.move(str(path), str(dest))
+    elif path.suffix == ".toml":
+        return "{}: adopting TOML commands is not supported yet".format(rel)
+    else:
+        text = path.read_text(encoding="utf-8")
+        vendor_fm, body = fm.split(text)
+        canonical_fm = reverse_frontmatter(vendor_fm, spec)
+        dest.write_bytes((fm.render(canonical_fm, body)).encode("utf-8"))
+        path.unlink()
+
+    state.record_adoption(config.rel(dest), rel, now_iso())
+    return "{} -> {} (adopted from {})".format(rel, config.rel(dest), adapter.name)
+
+
+def run_adopt(config: Config, registry, state: State, args) -> int:
+    from .cli import EXIT_ERROR, EXIT_OK
+
+    lines: List[str] = []
+    for raw in args.paths:
+        path = Path(raw)
+        if not path.is_absolute():
+            path = config.root / path
+        line = adopt_path(path, config, registry, state, dry_run=args.dry_run)
+        lines.append(line or "{}: nothing to adopt (unrecognised, or already managed)".format(raw))
+
+    for line in lines:
+        print("  " + line)
+
+    if args.dry_run:
+        print("dry run: nothing written")
+        return EXIT_OK
+
+    state.save(config.state_path)
+    if args.no_sync:
+        return EXIT_OK
+
+    print("\nfanning out:")
+    from .cli import build_parser
+
+    sync_args = build_parser().parse_args(["sync"])
+    sync_args.root = str(config.root)
+    sync_args.include_unverified = config.include_unverified
+    from .cli import cmd_sync
+
+    return cmd_sync(sync_args)

agentmeld/cli.py

@@ -0,0 +1,308 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from . import __version__
+from .config import Config, load_config
+from .model import Action, AssetKind, Confidence
+from .registry import kind_confidence, load_registry
+from .state import State
+
+EXIT_OK = 0
+EXIT_DRIFT = 1
+EXIT_CONFLICT = 2
+EXIT_ERROR = 3
+
+
+# ---------------------------------------------------------------------------
+# output helpers
+# ---------------------------------------------------------------------------
+
+_SYMBOL = {
+    Action.CREATE: "+",
+    Action.UPDATE: "~",
+    Action.UNCHANGED: " ",
+    Action.CONFLICT: "!",
+    Action.SKIP: "-",
+}
+
+
+def _print_plan(plan, config: Config, verbose: bool = False) -> None:
+    rows = plan.mirrors if verbose else plan.changes + plan.conflicts
+    if not rows:
+        print("everything already in sync ({} mirror(s) checked)".format(len(plan)))
+    for mirror in rows:
+        print(
+            "  {sym} {target:<48} {strategy:<9} {adapter}".format(
+                sym=_SYMBOL[mirror.action],
+                target=config.rel(mirror.target),
+                strategy=str(mirror.strategy),
+                adapter=mirror.adapter_id,
+            )
+        )
+        if mirror.reason and mirror.action is Action.CONFLICT:
+            print("      {}".format(mirror.reason))
+    for warning in plan.warnings:
+        print("  note: {}".format(warning))
+
+
+def _context(args) -> "tuple":
+    config = load_config(Path(args.root).resolve() if args.root else None)
+    if getattr(args, "include_unverified", False):
+        config.include_unverified = True
+    if getattr(args, "mode", None):
+        config.mode = args.mode
+    registry = load_registry([config.root / d for d in config.extra_adapter_dirs])
+    state = State.load(config.state_path)
+    return config, registry, state
+
+
+# ---------------------------------------------------------------------------
+# commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_detect(args) -> int:
+    from .detect import detect_tools
+
+    config, registry, state = _context(args)
+    found = detect_tools(registry, config, state)
+    print("repo: {}".format(config.root))
+    if not found:
+        print("no AI tool configuration detected")
+        print("run 'agentmeld init' to start a canonical {}/ tree".format(config.canonical_dir))
+        return EXIT_OK
+    print("detected {} tool(s):".format(len(found)))
+    for adapter_id, evidence in sorted(found.items()):
+        adapter = registry[adapter_id]
+        print("  {:<10} {:<26} {}".format(adapter_id, adapter.name, ", ".join(evidence)))
+    return EXIT_OK
+
+
+def cmd_list_adapters(args) -> int:
+    config, registry, _state = _context(args)
+    print("{:<10} {:<26} {:<13} {}".format("id", "tool", "kind", "confidence / strategy"))
+    for adapter_id, adapter in sorted(registry.items()):
+        for kind, spec in adapter.kinds.items():
+            confidence = kind_confidence(adapter, kind)
+            flag = "" if confidence is Confidence.VERIFIED else "  (opt-in)"
+            print(
+                "{:<10} {:<26} {:<13} {} / {}{}".format(
+                    adapter_id, adapter.name, str(kind), confidence, spec.strategy, flag
+                )
+            )
+    print()
+    print("Unverified paths are excluded from sync unless --include-unverified is passed.")
+    return EXIT_OK
+
+
+def cmd_sync(args) -> int:
+    from .config import discover_assets
+    from .linker import git_symlinks_enabled, resolve_mode
+    from .planner import apply_plan, build_plan, select_adapters
+
+    config, registry, state = _context(args)
+    if not config.canonical.is_dir():
+        print("no {}/ directory -- run 'agentmeld init' first".format(config.canonical_dir))
+        return EXIT_ERROR
+
+    mode = resolve_mode(config.mode, config.root)
+    if mode == "copy" and config.mode == "auto":
+        print("note: symlinks unavailable here, mirroring as copies instead")
+    if git_symlinks_enabled(config.root) is False and mode == "link":
+        print("warning: git core.symlinks=false -- links may not survive a fresh clone")
+
+    if getattr(args, "adopt", False):
+        from .watch import reconcile
+
+        for line in reconcile(config, registry, state):
+            print("  adopted: {}".format(line))
+
+    assets = discover_assets(config)
+    if not assets:
+        print("no canonical assets found under {}/".format(config.canonical_dir))
+        return EXIT_OK
+
+    adapters = select_adapters(registry, config, state, args.targets or None)
+    plan = build_plan(config, assets, adapters, state, mode)
+
+    quiet = getattr(args, "quiet", False)
+    if not (quiet and plan.is_clean):
+        print("{} asset(s) -> {} tool(s), mode={}".format(len(assets), len(adapters), mode))
+        _print_plan(plan, config, verbose=args.verbose)
+
+    if args.check:
+        if plan.conflicts:
+            return EXIT_CONFLICT
+        return EXIT_DRIFT if plan.changes else EXIT_OK
+
+    if args.dry_run:
+        print("\ndry run: nothing written")
+        return EXIT_CONFLICT if plan.conflicts else EXIT_OK
+
+    written = apply_plan(plan, config, state, mode)
+    if not (quiet and written == 0):
+        print("\nwrote {} file(s)".format(written))
+    if plan.conflicts:
+        print(
+            "{} conflict(s) left untouched -- resolve by hand, or delete the file to "
+            "let agentmeld own it".format(len(plan.conflicts))
+        )
+        return EXIT_CONFLICT
+    return EXIT_OK
+
+
+def cmd_doctor(args) -> int:
+    from .config import discover_assets
+    from .doctor import run_doctor
+
+    config, registry, state = _context(args)
+    return run_doctor(config, registry, state, args)
+
+
+def cmd_init(args) -> int:
+    from .init import run_init
+
+    config, registry, state = _context(args)
+    return run_init(config, registry, state, args)
+
+
+def cmd_adopt(args) -> int:
+    from .adopt import run_adopt
+
+    config, registry, state = _context(args)
+    return run_adopt(config, registry, state, args)
+
+
+def cmd_watch(args) -> int:
+    from .watch import run_watch
+
+    config, registry, state = _context(args)
+    return run_watch(config, registry, state, args)
+
+
+def cmd_install_hooks(args) -> int:
+    from .hooks import run_install_hooks
+
+    config, registry, state = _context(args)
+    return run_install_hooks(config, registry, state, args)
+
+
+# ---------------------------------------------------------------------------
+# parser
+# ---------------------------------------------------------------------------
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentmeld",
+        description="One AI context, every agent. Keep one canonical copy of your "
+        "AI instructions, rules, skills, agents, commands and MCP config, "
+        "mirrored into every tool's location.",
+    )
+    parser.add_argument("--version", action="version", version="agentmeld " + __version__)
+    parser.add_argument("--root", help="repo root (default: nearest .git or .ai ancestor)")
+
+    # --root is also accepted *after* the subcommand, because `agentmeld init
+    # --root .` is what people naturally type. SUPPRESS keeps the subcommand copy
+    # from overwriting a value given before the subcommand with None.
+    positional_root = argparse.ArgumentParser(add_help=False)
+    positional_root.add_argument("--root", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+
+    sub = parser.add_subparsers(dest="command", required=True)
+    _original_add_parser = sub.add_parser
+
+    def add_parser(name, **kwargs):
+        kwargs.setdefault("parents", [positional_root])
+        return _original_add_parser(name, **kwargs)
+
+    sub.add_parser = add_parser
+
+    def common(p):
+        p.add_argument(
+            "--include-unverified",
+            action="store_true",
+            help="also sync paths not confirmed against vendor documentation",
+        )
+        return p
+
+    p = sub.add_parser("detect", help="show which AI tools this repo uses")
+    common(p).set_defaults(func=cmd_detect)
+
+    p = sub.add_parser("list-adapters", help="show the support matrix")
+    common(p).set_defaults(func=cmd_list_adapters)
+
+    p = sub.add_parser("init", help="create the canonical tree, adopting existing config")
+    common(p)
+    p.add_argument("--force", action="store_true", help="proceed on a dirty worktree")
+    p.add_argument("--no-migrate", action="store_true", help="do not move existing files")
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("sync", help="materialise every mirror")
+    common(p)
+    p.add_argument("--check", action="store_true", help="exit 1 on drift, writing nothing (CI)")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("-v", "--verbose", action="store_true", help="list unchanged mirrors too")
+    p.add_argument("-q", "--quiet", action="store_true", help="only print on change or error")
+    p.add_argument("--mode", choices=["auto", "link", "copy"])
+    p.add_argument("--targets", nargs="*", help="limit to these adapter ids")
+    p.add_argument(
+        "--adopt",
+        action="store_true",
+        help="first pull any new vendor files into the canonical tree",
+    )
+    p.set_defaults(func=cmd_sync)
+
+    p = sub.add_parser("adopt", help="pull a vendor file into canonical, then fan out")
+    common(p)
+    p.add_argument("paths", nargs="+", help="vendor file(s) to adopt")
+    p.add_argument("--dry-run", action="store_true")
+    p.add_argument("--no-sync", action="store_true", help="adopt without fanning out")
+    p.set_defaults(func=cmd_adopt)
+
+    p = sub.add_parser("watch", help="adopt and fan out automatically as files change")
+    common(p)
+    p.add_argument("--interval", type=float, default=1.0, help="poll interval in seconds")
+    p.add_argument("--once", action="store_true", help="one pass, for testing")
+    p.add_argument("--timeout", type=float, help="stop after this many seconds")
+    p.set_defaults(func=cmd_watch)
+
+    p = sub.add_parser("install-hooks", help="auto-sync on agent writes and on commit")
+    common(p)
+    p.add_argument(
+        "--kind",
+        nargs="*",
+        choices=["claude", "git"],
+        help="which hooks to install (default: both)",
+    )
+    p.add_argument("--dry-run", action="store_true")
+    p.set_defaults(func=cmd_install_hooks)
+
+    p = sub.add_parser("doctor", help="report drift, conflicts, orphans and dropped keys")
+    common(p)
+    p.set_defaults(func=cmd_doctor)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args) or EXIT_OK)
+    except KeyboardInterrupt:
+        print("\ninterrupted")
+        return EXIT_ERROR
+    except (OSError, ValueError, KeyError) as exc:
+        print("error: {}".format(exc), file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())