gabriel / muse public
bridge.py python
74 lines 3.0 KB
Raw
sha256:e6465e8a9b7fa8e6223ed4a3576e96c568c913ae2caeb9c31f15e7a81b250b40 docs: add | jq convention to --json section of agent-guide Sonnet 4.6 1 day ago
1 """``muse bridge`` — Bidirectional Git interoperability.
2
3 Bridge makes Muse and Git speak to each other without losing identity in either
4 direction. Three subcommands form the bridge namespace:
5
6 git-import Git → Muse Replay a git repo's commits into a Muse repo.
7 git-export Muse → Git Sync a Muse snapshot into a git working tree.
8 git-status Both Show bridge state, drift, and last sync points.
9
10 Bridge state is persisted in ``.muse/git-bridge.toml`` — a TOML file that
11 records the last imported git SHA and the last exported Muse commit ID. Add
12 ``.muse/git-bridge.toml`` to ``.museignore`` to keep per-developer state out
13 of the object store.
14
15 All Muse commit IDs stored in bridge state are **canonically prefixed**:
16 ``sha256:<64-hex>``. Bare hex strings are never stored or returned.
17
18 Canonical prefix rules
19 -----------------------
20 - ``muse_commit_id`` — always ``sha256:<64-hex>``; :func:`write_bridge_state`
21 raises :class:`ValueError` if the value lacks the prefix.
22 - ``git_sha`` — bare 40-char SHA-1 hex; no prefix (Git native format).
23
24 CI authentication
25 -----------------
26 Both git-import and git-export read signing identity from:
27
28 1. ``MUSE_AGENT_KEY`` environment variable (PEM-encoded Ed25519 private key)
29 2. ``MUSE_AGENT_HANDLE`` environment variable (registered agent handle)
30 3. ``~/.muse/identity.toml`` — fallback for interactive use
31
32 Usage examples::
33
34 muse bridge git-import /path/to/git-repo --incremental --json
35 muse bridge git-export --git-dir /path/to/git-mirror --no-push
36 muse bridge git-status --json
37
38 Domain logic lives in ``muse.core.bridge``:
39 state BridgeState TypedDicts, read/write_bridge_state
40 hooks BridgeHook, BridgeHooks, load/run_bridge_hooks
41 git_primitives AttributionMapper, _CatFile, subprocess wrappers
42 importer Git → Muse import engine
43 harmony_shelf Harmony ↔ rerere, Shelf ↔ Stash migration
44 exporter Muse → Git export engine + watch loop
45 status drift computation and status display
46 """
47
48 import argparse
49
50 from muse.core.bridge.exporter import _register_git_export_parser
51 from muse.core.bridge.importer import _register_git_import_parser
52 from muse.core.bridge.status import _register_git_status_parser
53
54
55 def register(subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
56 """Register ``muse bridge`` and its three subcommands.
57
58 Subcommands:
59 git-import Git → Muse incremental import with attribution mapping.
60 git-export Muse → Git snapshot sync with CI push support.
61 git-status Bridge state and drift report.
62 """
63 parser = subparsers.add_parser(
64 "bridge",
65 help="Bidirectional Git interoperability (git-import / git-export).",
66 description=__doc__,
67 formatter_class=argparse.RawDescriptionHelpFormatter,
68 )
69 subs = parser.add_subparsers(dest="bridge_subcommand", metavar="SUBCOMMAND")
70 subs.required = True
71
72 _register_git_import_parser(subs)
73 _register_git_export_parser(subs)
74 _register_git_status_parser(subs)
File History 1 commit
sha256:e6465e8a9b7fa8e6223ed4a3576e96c568c913ae2caeb9c31f15e7a81b250b40 docs: add | jq convention to --json section of agent-guide Sonnet 4.6 1 day ago