@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/drive-epic-help.js

@@ -0,0 +1,212 @@
+/**
+ * Help text for `drive-epic`, in two parts.
+ *
+ * Basic help (`-h` / `--help`) is what a customer needs to launch an epic.
+ * Advanced help (`--help-advanced`) holds the material only an owner who runs
+ * their own Bridge server needs: the local plane and its port, the composed
+ * bring-up, durable hosts, repository-wide executors, and launch profiles.
+ *
+ * This module is pure. It reads no files, resolves no credentials, opens no
+ * network connection, starts no process, and imports nothing from
+ * `drive-epic.ts`, so `parseDriveEpicArgs` can return either text before any
+ * side effect. It imports only two neutral constants.
+ */
+import { CONDUCTOR_DEFAULT_BASE_URL } from "./conductor/bridge-api-client.js";
+import { PLANE_SERVER_PORT_ENV_VAR } from "./plane/types.js";
+/** Shown on the last line of basic help. */
+const ADVANCED_HELP_POINTER = "Owners who run their own Bridge server: drive-epic --help-advanced";
+export function getDriveEpicUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>",
+        "",
+        "Launches one epic. Reads this project's readiness from Bridge API and picks",
+        "exactly one path for you — it never asks you to choose. A refusal names the",
+        "missing item and its fix, and creates nothing.",
+        "",
+        "Arguments:",
+        "  <EPIC>                 Epic key, matches [A-Z]+-[0-9]+ (e.g. PROJ-123)",
+        "",
+        "Finding the plan: without --plan-file, drive-epic searches",
+        "{docs_dir}/epic-plans/*/epic-plan.meta.json for a file naming this epic",
+        "({\"epic_key\": \"<KEY>\"}), where docs_dir is BAPI_DOCS_DIR or docs/tmp",
+        "resolved against the Git top level. Exactly one match with a sibling",
+        "epic-plan.dag.json is used as if you had passed --plan-file, and its path is",
+        "printed before anything is created. It never guesses: no match, two or more",
+        "matches, or an unusable meta file stops with the paths it found and creates",
+        "nothing. /define-tickets writes these files; `emit-epic-implementer-bundle",
+        "finalize` writes them for a plan from /plan-epic. A supplied --plan-file",
+        "always wins.",
+        "",
+        "Branch strategy: a plan with two or more nodes defaults to a dedicated",
+        "epic/<KEY> branch. Child PRs target it, and one draft integration PR targets",
+        "the repository base branch. The flags below only override that default.",
+        "",
+        "Unattended by default: a run on an epic branch merges child PRs into that",
+        "branch on its own. The integration PR into the base branch always stays",
+        "human-gated. Pass --attended to opt out. An unattended run needs consent",
+        "(on by default, switched on the Setup page of the Bridge admin panel), an",
+        "escalation channel (a verified notify webhook or your account email), and",
+        "confirmed review and CI workflows on the default branch. Readiness lists each",
+        "with its state, and a missing one is refused by name before a run is created.",
+        "",
+        "Every run gets an executor: once the run is created, drive-epic starts one in",
+        "the background from this checkout's Git top level. It claims only that run's",
+        "jobs, logs to .bridge/executors/<run>.log, and exits when the run is done.",
+        "Running again for the same live run starts no second one. If it fails to",
+        "start, the run is left intact and the log path and the command to start it",
+        "by hand are printed.",
+        "",
+        "Run it from a Git work tree inside the target repository. Preconditions are",
+        "checked, never repaired: each failure names the fix. Fix it and rerun.",
+        "",
+        "Options:",
+        "  --plan-file <path>     Plan DAG sidecar. Optional: without it, drive-epic finds",
+        "                         the plan by epic key (see above).",
+        "  --repo <name>          Repo name (default: BAPI_REPO_NAME or .bridge/config)",
+        "  --feature-branch <name>  Override the derived epic/<KEY> name. Forwarded",
+        "                         verbatim, never interpreted here.",
+        "  --into-base            Opt out of the epic-branch default: children target the",
+        "                         repository base branch. Cannot be combined with",
+        "                         --feature-branch.",
+        "  --attended             Opt out of the unattended default. Forwarded verbatim to",
+        "                         setup, which owns what it composes.",
+        "",
+        "Policy (forwarded verbatim; drive-epic interprets none of it):",
+        "  --policy-file <path>   JSON file holding the COMPLETE run policy.",
+        "  --review-policy <src>  Per-run review policy source.",
+        "  --replace-policy       Authorize replacing a LIVE run's stored policy.",
+        "  --verification-handoff proceed|block",
+        "                         The owner's verification hand-off choice for a NEW run.",
+        "  --verification-handoff-exception <TICKET>:<e2e_tests|rendered_ui_review>",
+        "                         Repeatable. With `block`, keeps verification a blocker",
+        "                         for that ticket and class.",
+        "",
+        "Target:",
+        "  --base-url <url>       Explicit Bridge API target. Without it, BAPI_BASE_URL is",
+        `                         used; with neither, drive-epic targets production`,
+        `                         (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the stored`,
+        "                         bapi:<repo> key when one is available. A stored key",
+        "                         approved for a different endpoint is never sent.",
+        "",
+        "Preview:",
+        "  --dry-run              Read-only launch preview. Resolves the target, reads",
+        "                         readiness and the epic's live run, discovers the plan,",
+        "                         and runs setup's own dry-run validation. It shows what a",
+        "                         real run WOULD do (create a run, reuse the epic's live run,",
+        "                         refuse, or stop) and creates nothing. Exit 0 when it would",
+        "                         create or reuse a run, 1 when it would refuse or stop.",
+        "  --json                 With --dry-run only: print exactly one JSON document on",
+        "                         stdout and nothing else. Alone, it is a parse error.",
+        "",
+        "Already-merged children: when a NEW run is created, drive-epic leaves out plan",
+        "children that are provably already merged. A child with a merged PR but no",
+        "delivery record is only 'probably done' and runs unless you confirm it.",
+        "Anything uncertain runs. Skipped children are recorded for audit only.",
+        "  --keep-child <KEY>     Repeatable. Run this child even if it is already merged.",
+        "  --skip-child <KEY>     Repeatable. Leave this child out. Refused unless the",
+        "                         child is currently done or probably done.",
+        "  --no-merged-check      Do not look for already-merged children. Cannot be",
+        "                         combined with --skip-child.",
+        "",
+        "  -h, --help             Show this help",
+        "  --help-advanced        Show the owner-only options",
+        "",
+        ADVANCED_HELP_POINTER,
+    ].join("\n");
+}
+export function getDriveEpicAdvancedUsage() {
+    return [
+        "Usage: mcp-server drive-epic [options] <EPIC>   (advanced help)",
+        "",
+        "Owner-only material for people who run their own Bridge server, or who host",
+        "epic launches on a durable machine. Hosted customers do not need any of it:",
+        "see `drive-epic --help` for the normal launch options.",
+        "",
+        "Reconciler liveness is read from the deployment's heartbeat. Against a target",
+        "that is not this machine's local plane (production, say), drive-epic never",
+        "touches a local plane: a target with no live reconciler is refused by name.",
+        "",
+        "Composed bring-up: with --plan-file, drive-epic starts the Epic Implementer",
+        "runtime for you against the local plane endpoint, when readiness is missing",
+        "ONLY the reconciler. It brings up the CONTROL PLANE first (server and",
+        "reconciler), creates and approves the run, then starts executor lanes SCOPED",
+        "to that run, and starts the dead-man observer last — one invocation, no",
+        "manual `plane up` first. A report missing supervisor setup, supervisor",
+        "configuration, GitHub App credentials, or an unattended prerequisite is NOT",
+        "started: those are owner-owned, and drive-epic exits with that one named",
+        "reason instead.",
+        "",
+        "The plane port: with --plan-file and BAPI_BASE_URL naming the local plane",
+        `endpoint (127.0.0.1, port ${PLANE_SERVER_PORT_ENV_VAR} or the default),`,
+        "drive-epic handles the port one of three ways, and never asks you to choose:",
+        "  - cold start: nothing listens there — it brings the plane up, then creates",
+        "    the run;",
+        "  - attach: this repository's own healthy plane is there — it creates the run",
+        "    against that plane and starts NO second server or reconciler;",
+        "  - refusal: anything else holds the port (another listener, a manifest for a",
+        "    different repository, an unreadable manifest, a plane that cannot take a",
+        "    run) — one named reason, and nothing is started.",
+        "One epic per plane — for its LANES: a plane's lanes serve the one run it is",
+        "bound to. A second run attaches to the same plane's reconciler and gets its own",
+        "run-scoped executor instead. A plane whose bound run cannot be read is refused",
+        "as plane-already-bound. Concurrent planes on one database are not supported.",
+        "Executor lanes and run-scoped executors are always scoped to the one run with",
+        "--epic-run-id, on every path.",
+        "",
+        "Run-scoped executors and durable hosts: a durable launch profile starts no",
+        "run-scoped executor. It requires a fresh --repo-wide executor instead, which",
+        "covers the repository. A plane's own lane is that run's executor, so none is",
+        "started beside it. Checks that need no run happen FIRST, so a refusal before",
+        "the run is created creates nothing.",
+        "",
+        "A live run beside a FOUND plan: when the epic already has a live run and the",
+        "plan came from discovery rather than --plan-file, drive-epic attaches to the",
+        "live run first. The found plan is reported as \"Found, unused\", is not treated",
+        "as approved input, and its file is left untouched. A plan you pass with",
+        "--plan-file keeps its create-path behavior unchanged.",
+        "",
+        "A live run with no plan: when the epic already has a live run and no plan was",
+        "supplied or found, drive-epic does not create anything. It makes sure that run",
+        "has an executor (reusing a live one, never starting a second) and shows it. A",
+        "durable launch profile starts none and relies on its host's confirmed",
+        "repo-wide executor; a plane already bound to the run needs none. An epic with",
+        "several active runs, or a run that cannot be read, is refused by name.",
+        "",
+        "Repository-wide executors: `install conductor --executor-id <id> --repo-wide`",
+        "provisions a persistent executor that claims jobs for every run in the",
+        "repository. A durable host needs one before it can launch.",
+        "",
+        "Launch target — decided BEFORE any authenticated request:",
+        "  --launch-profile <name>  Select the host-local launch profile guided setup",
+        "                         approved (`install conductor --launch-profile <name>`):",
+        "                         target, repository, mode, runtime, and policy and",
+        "                         credential references. Useful for a local or other",
+        "                         non-production server and for durable hosts.",
+        "  --base-url <url>       Explicit Bridge API target. With a profile it must",
+        "                         agree with it — an override never rebinds a profile.",
+        "BAPI_EPIC_LAUNCH_PROFILE selects a host-local launch profile for epic",
+        "launches. --launch-profile takes precedence. For an environment-selected",
+        "profile, BAPI_BASE_URL remains the general CLI endpoint and does not",
+        "conflict with the epic launch target; --base-url still must agree.",
+        "Without either, BAPI_BASE_URL is used. With none of the three, drive-epic",
+        `targets production (${CONDUCTOR_DEFAULT_BASE_URL}) and uses the`,
+        "stored bapi:<repo> key when one is available. A stored key approved for a",
+        "different endpoint is never sent; an unapproved key is sent only to",
+        "production.",
+        "",
+        "Local-plane freshness:",
+        "  Before a launch CREATES a run on this machine's plane, drive-epic checks that the",
+        "  plane's pinned snapshot is not behind origin/main and that the database is at the",
+        "  migration head. A CONFIRMED problem refuses before any setup or run creation; evidence",
+        "  it cannot read is a warning. Attaching to a run that already exists only warns.",
+        "  --allow-stale-plane    Override for ONE invocation: bypasses only those two",
+        "                         refusals. It repairs nothing, is not persisted, and does not",
+        "                         bypass readiness, authentication, ownership, or admission.",
+        "                         Valid with or without --dry-run.",
+        "  --dry-run may run `git fetch` (it updates remote-tracking refs) but changes no checkout",
+        "  contents, plane configuration, database state, or run state.",
+        "",
+        "  -h, --help             Show the basic help",
+        "  --help-advanced        Show this help",
+    ].join("\n");
+}