[verified] Expose canonical broker roles in CLI and docs

2026-10-12 06:01:42 +00:00
parent 7b4b5e72f3
commit 4acc28563c
3 changed files with 61 additions and 2 deletions
@@ -147,6 +147,63 @@ class ManagedLockBrokerTests(unittest.TestCase):
            self.assertFalse(sock.exists())
            self.assertTrue(probe_free(root / "repositories/alice/ledger/locks/issue-7.lock"))

+    def test_serve_parser_accepts_only_canonical_roles(self):
+        import contextlib
+        import io
+        roles = {"gitea-spec-agent", "gitea-impl-agent", "gitea-review-agent"}
+        self.assertEqual(broker.ROLES, roles)
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d) / "not-created"
+            args = ["serve", "--root", str(root), "--owner", "alice", "--repository", "ledger",
+                    "--issue", "7", "--run-id", "role-probe", "--ttl-seconds", "30"]
+            for role in sorted(roles):
+                with self.subTest(role=role):
+                    self.assertEqual(broker.parser().parse_args([*args, "--role", role]).role, role)
+            for role in ("spec", "impl", "review", "gitea-release-agent", "Gitea-spec-agent", " gitea-spec-agent", "gitea-spec-agent "):
+                with self.subTest(role=role):
+                    stderr = io.StringIO()
+                    with contextlib.redirect_stderr(stderr), self.assertRaises(SystemExit) as rejected:
+                        broker.parser().parse_args([*args, "--role", role])
+                    self.assertEqual(rejected.exception.code, 2)
+                    self.assertIn("invalid choice", stderr.getvalue())
+                    for allowed in roles:
+                        self.assertIn(allowed, stderr.getvalue())
+            help_text = io.StringIO()
+            with contextlib.redirect_stdout(help_text), self.assertRaises(SystemExit) as helped:
+                broker.parser().parse_args(["serve", "--help"])
+            self.assertEqual(helped.exception.code, 0)
+            for role in roles:
+                self.assertIn(role, help_text.getvalue())
+            self.assertFalse(root.exists())
+        # The direct Python constructor retains its independent role guard.
+        with self.assertRaisesRegex(ValueError, "invalid role"):
+            broker.Broker(Namespace(role="spec"))
+
+    def test_invalid_serve_role_cli_reports_choices_before_runtime_creation(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d) / "not-created"
+            result = subprocess.run(
+                [sys.executable, str(BROKER), "serve", "--root", str(root), "--owner", "alice",
+                 "--repository", "ledger", "--issue", "7", "--role", "spec", "--run-id", "role-probe",
+                 "--ttl-seconds", "30"], capture_output=True, text=True, timeout=10)
+            self.assertEqual(result.returncode, 2)
+            self.assertEqual(result.stdout, "")
+            self.assertFalse(root.exists())
+            self.assertIn("invalid choice", result.stderr)
+            for role in ("gitea-spec-agent", "gitea-impl-agent", "gitea-review-agent"):
+                self.assertIn(role, result.stderr)
+            self.assertNotIn("error: ValueError", result.stderr)
+            self.assertNotIn("Traceback", result.stderr)
+
+    def test_canonical_role_values_and_example_are_documented(self):
+        doc = (Path(__file__).parents[2] / "operations/repository-cache.md").read_text()
+        section = doc.split("### Canonical command templates", 1)[1].split("## Lock 규칙", 1)[0]
+        for role in ("gitea-spec-agent", "gitea-impl-agent", "gitea-review-agent"):
+            self.assertIn(f"`{role}`", section)
+        self.assertIn("--role gitea-spec-agent --run-id", section)
+        self.assertIn("spec`/`impl`/`review", section)
+        self.assertIn("authorization", section)
+
    def test_constructor_rejects_lexical_root_and_handle_aliases(self):
        with tempfile.TemporaryDirectory() as d:
            root = Path(d); ensure_cache(root)