@bridge_gpt/mcp-server 0.2.23 → 0.2.25

package/build/sfcc/setup-status.js

@@ -19,7 +19,8 @@ import { getAmToken } from "./client.js";
  *   2. Repo name set (REPO_NAME)
  *   3. version config field is an SFCC version
  *   4. dw.json found / instance unambiguous
- *   5. AM token acquisition
+ *   5. AM token acquisition (OCAPI Account Manager — NOT log/WebDAV access)
+ *   6. SFCC Log Query capability (WebDAV Basic auth — independent of steps 3–5)
  *
  * Never throws; each check is caught independently so partial states are
  * always reported. Output is completely secret-free.
@@ -97,8 +98,37 @@ export async function sfccSetupStatusTool(deps) {
             tokenStatus = `✗ ${msg}`;
         }
     }
-    lines.push(`5. AM Token: ${tokenStatus}`);
-    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green.");
+    lines.push(`5. AM Token (OCAPI): ${tokenStatus}`);
+    // 6. SFCC Log Query capability — WebDAV Basic auth, independent of OCAPI/AM.
+    // A single Bridge backend probe (secret-free) reports readiness. This is a
+    // separate credential surface: an SFCC repo can have OCAPI working (steps 3–5)
+    // while log/WebDAV access is not configured, and vice versa.
+    let logQueryStatus = "— Skipped (Bridge API not configured)";
+    if (apiKeyOk && repoOk) {
+        try {
+            const url = deps.buildGetUrl("/sfcc/logs/capability", { repo_name: deps.repoName });
+            const resp = await fetch(url, { headers: await deps.getGetHeaders() });
+            if (!resp.ok) {
+                logQueryStatus = `✗ Could not read (Bridge API ${resp.status})`;
+            }
+            else {
+                const body = (await resp.json());
+                if (body?.configured === true) {
+                    logQueryStatus = "✓ Configured (WebDAV log access ready)";
+                }
+                else {
+                    const msg = typeof body?.message === "string" ? body.message : "Not configured";
+                    logQueryStatus = `✗ ${msg}`;
+                }
+            }
+        }
+        catch (err) {
+            logQueryStatus = `✗ Resolution error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    lines.push(`6. SFCC Log Query (WebDAV): ${logQueryStatus}`);
+    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green. " +
+        "Step 6 (log/WebDAV access) is independent and gates `sfcc_log_query`.");
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };

package/build/start-tickets.js

@@ -1469,9 +1469,10 @@ const defaultPruneStaleLaunchScriptsDeps = {
  * recursively. Newer entries and unrelated files/dirs are left untouched.
  *
  * Fully fail-open: any error (missing parent dir, unreadable entry, stat/unlink
- * failure) is swallowed and never blocks or aborts a spawn — the same fail-open
- * discipline as the launch-script writer fallback in
- * {@link materializeWorkerLaunchCommand}.
+ * failure) is swallowed and never blocks or aborts a spawn. (Unconditionally so,
+ * unlike {@link materializeWorkerLaunchCommand}, whose inline fallback is gated on
+ * {@link MAX_TERMINAL_COMMAND_BYTES} — pruning a stale temp dir has no launchable/
+ * unlaunchable axis to gate on.)
  */
 export async function pruneStaleLaunchScripts(deps = defaultPruneStaleLaunchScriptsDeps) {
     try {
@@ -1523,27 +1524,54 @@ export const defaultWriteWorkerLaunchScript = async ({ platform, key, content, }
     await writeFile(file, content, { mode: 0o600 });
     return file;
 };
+/**
+ * Canonical maximum UTF-8 byte length of a single command line handed to a
+ * terminal spawner. macOS `osascript`-driven Terminal/iTerm keystroke delivery
+ * silently truncates (or mangles) a longer line, so a command at or below this
+ * bound is "known-launchable" and anything above it is "known-unlaunchable".
+ *
+ * Exported so the launcher and every install-flow guard read the SAME number:
+ * two independently-written literals would silently drift apart, and the whole
+ * point of the bound is that the launcher's fallback decision and the caller's
+ * final pre-spawn check agree.
+ */
+export const MAX_TERMINAL_COMMAND_BYTES = 1024;
 /**
  * Resolve the command actually handed to the terminal spawner for one worker.
  * When `deps.writeWorkerLaunchScript` is provided, the full command is persisted
- * to a script and a short `source <path>` runner is returned; if writing fails
- * for any reason the original inline command is returned (fail-open — a launch
- * never aborts because a temp file could not be written). When the seam is
+ * to a script and a short `source <path>` runner is returned. When the seam is
  * absent, the inline command is returned unchanged (legacy behaviour).
+ *
+ * The fail-open on a failed write is CONDITIONAL, and the condition is the point.
+ * Falling back to the inline command is only a fallback if the terminal can
+ * actually run it: above {@link MAX_TERMINAL_COMMAND_BYTES} the spawner truncates
+ * the line, so "fail-open" would deliver a corrupted command — a silent, confusing
+ * failure strictly worse than a loud one. So a failed write falls back inline only
+ * at or below the bound, and returns a structured failure above it.
  */
 export async function materializeWorkerLaunchCommand(deps, key, fullCommand) {
     if (!deps.writeWorkerLaunchScript)
-        return fullCommand;
+        return { ok: true, command: fullCommand };
     try {
         const scriptPath = await deps.writeWorkerLaunchScript({
             platform: deps.platform,
             key,
             content: buildLaunchScriptContent(deps.platform, fullCommand),
         });
-        return buildLaunchScriptRunnerCommand(deps.platform, scriptPath);
+        return { ok: true, command: buildLaunchScriptRunnerCommand(deps.platform, scriptPath) };
     }
     catch {
-        return fullCommand;
+        // Bytes, not `.length`: the bound is a byte bound, and a multibyte prompt can
+        // sit under 1024 JS characters while being well over 1024 UTF-8 bytes.
+        if (Buffer.byteLength(fullCommand, "utf8") <= MAX_TERMINAL_COMMAND_BYTES) {
+            return { ok: true, command: fullCommand };
+        }
+        return {
+            ok: false,
+            reason: "launch-script-write-failed-oversized-command",
+            error: "Could not write the temporary launch script, and the full command is too long to send " +
+                "to the terminal directly. Check that the system temporary directory is writable.",
+        };
     }
 }
 // ---------------------------------------------------------------------------
@@ -1569,10 +1597,17 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
         // agents, or conductor disabled). Never mutates process/global env.
         const shellCommand = injectConductorEnvIntoShellCommand(deps.platform, baseShellCommand, row.conductorEnv);
         // Deliver the (potentially multi-KB) command via a launch-script file so the
-        // terminal spawn payload stays tiny and escaping-immune. Fail-open / no-op
-        // when no writer seam is configured (see materializeWorkerLaunchCommand).
-        const runnableCommand = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
-        const result = await deps.spawnTerminalTab(deps, terminal, runnableCommand, {
+        // terminal spawn payload stays tiny and escaping-immune. No-op when no writer
+        // seam is configured; a failed write falls back inline only while the command
+        // is still launchable (see materializeWorkerLaunchCommand).
+        const materialized = await materializeWorkerLaunchCommand(deps, row.key, shellCommand);
+        if (!materialized.ok) {
+            // Known-unlaunchable: spawning the oversized inline command would deliver a
+            // truncated line. Fail this row only — siblings still launch.
+            out.push({ ...row, status: "spawn-failed", error: materialized.error });
+            continue;
+        }
+        const result = await deps.spawnTerminalTab(deps, terminal, materialized.command, {
             key: row.key,
             worktreePath: row.path,
         });

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.23";
+export const VERSION = "0.2.25";

package/{CONDUCTOR.md → docs/CONDUCTOR.md}

@@ -8,7 +8,7 @@ involve Conductor — you opt in per run with `--conductor`.
 This document is the reference for Conductor's architecture, epic setup,
 observability stream, local git hooks, and the per-repo done-gate / auto-merge
 config. For the everyday `start-tickets` flags and cross-platform behavior, see
-[README → CLI Subcommands](./README.md#cli-subcommands).
+[README → CLI Subcommands](../README.md#cli-subcommands).
 
 ## Epic Conductor v2 — how an epic is actually driven
 
@@ -81,7 +81,7 @@ blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
 When `--conductor` is set, the spawn boundary also injects
 `BRIDGE_MCP_PROFILE=conductor` so each worker registers the 8 conductor/event/
 supervisor MCP tools (a plain `start-tickets` run stays on the default `core`
-profile). See [README → Environment Variables](./README.md#environment-variables).
+profile). See [README → Environment Variables](../README.md#environment-variables).
 
 ## `conductor install-git-hooks` (BAPI-395)
 

package/docs/install/github-app.md

@@ -0,0 +1,252 @@
+# Installing the Bridge GitHub App
+
+Bridge connects to GitHub through a **GitHub App**, not a personal access token. Once
+the app is installed on your repository and linked to your Bridge project, Bridge can
+open pull requests, run automated code review, read CI check status, and (when enabled)
+auto-merge — all using short-lived, per-call installation tokens. Your code and
+credentials stay on GitHub; Bridge mints a fresh token for each operation and stores no
+long-lived GitHub token.
+
+## The app
+
+| | |
+|---|---|
+| **Name** | Bridge GPT - AI Tools for SFCC |
+| **Owner** | [@Bridge-GPT](https://github.com/Bridge-GPT) |
+| **Public install page** | <https://github.com/apps/bridge-gpt-ai-tools-for-sfcc> |
+| **App ID** | `954077` |
+| **Client ID** | `Iv23liBEyDUeD25W06ix` |
+
+> The App ID and Client ID are **public** identifiers (GitHub shows them on the app's
+> settings page). They are not secrets. Only the app's **private key** and webhook
+> secret are sensitive, and those are held by whoever operates the Bridge deployment —
+> see [Self-hosting / operator setup](#self-hosting--operator-setup) at the end. As an
+> end user you never handle them.
+
+## Prerequisites
+
+- A GitHub repository you want Bridge to work on.
+- Permission to install a GitHub App on the account that owns it:
+  - **Personal repo:** you can install it yourself.
+  - **Organization repo:** you must be an **organization owner**, or a member who can
+    *request* the install for an owner to approve. (GitHub decides which button you see —
+    **Install**, **Install & request**, or **Request** — based on your role.)
+- Your Bridge project already registered (you have a Bridge API key and repo name).
+
+---
+
+## Option A — `connect-github` from your terminal (recommended)
+
+If you already have a Bridge API key configured (you ran `install-bridge`), you can
+connect GitHub without opening the Bridge web UI at all:
+
+```bash
+npx -y @bridge_gpt/mcp-server@latest connect-github --repo <repo_name>
+```
+
+Omit `--repo` and the command infers the project from the current directory, asking you
+to confirm.
+
+What happens:
+
+1. The command opens the GitHub App install screen in your browser.
+2. On GitHub, choose the **account or organization** that owns the repository, pick the
+   repositories under **Repository access** (see [Choosing
+   repositories](#choosing-repositories)), and click **Install**.
+3. GitHub returns to a page that just says *"GitHub connection received — return to your
+   terminal."* That page is intentionally blank of detail; your terminal is where the
+   flow continues.
+4. Back in the terminal, the command shows the repositories your installation covers and
+   asks which one to connect. **Every connection is confirmed by hand** — even when the
+   installation contains exactly one repository. There is no `--yes` flag.
+5. Choose one, and it prints the connected `owner/repo`.
+
+**You are never asked for a GitHub token, password, or installation ID.** You
+authenticate to GitHub in your own browser; the terminal only ever carries a short-lived
+Bridge-issued handle. Bridge never sees a GitHub credential.
+
+**If you decline at the confirmation prompt**, nothing is connected and nothing is
+changed — re-run the command whenever you like.
+
+**If it times out or fails**, no connection is made. Re-run the command; the request
+expires after about 15 minutes, so a stale attempt is never left half-applied.
+
+### Organization approval
+
+If an organization owns the repository and you are not an owner, GitHub sends an
+**approval request** to an owner instead of installing the app. That approval happens
+entirely on GitHub's side and **does not return to your terminal**, so `connect-github`
+cannot wait for it — the original request expires. This is a real limitation, not a bug.
+
+Once an owner has approved the install, finish the connection with
+[Option C](#option-c--manual-install--installation-id-fallback) below.
+
+---
+
+## Option B — Connect GitHub button (web UI)
+
+Bridge captures the installation automatically — you never copy an ID by hand.
+
+1. Open your project's **Get Started** page in the Bridge web UI. The page opens directly
+   on the GitHub connection task — connecting your repository is what the page is for.
+2. In the **1. Connect GitHub** panel, click **Connect GitHub**. Bridge mints a
+   short-lived, single-use link scoped to your project and sends you to GitHub's
+   app-install screen.
+3. On GitHub, choose the **account or organization** that owns the repository.
+4. Under **Repository access**, choose **Only select repositories** and pick the repo(s)
+   you want Bridge to cover (or **All repositories**). See
+   [Choosing repositories](#choosing-repositories) below.
+5. Review the requested permissions and click **Install** (or **Install & request** /
+   **Request** if an org owner must approve).
+6. GitHub redirects you back to Bridge. Bridge verifies the installation directly with
+   GitHub, links it to your project, and stores the installation automatically. If the
+   installation covers exactly one repo — or one repo clearly matches your project —
+   Bridge binds it for you; otherwise it shows a short **repository picker** so you can
+   confirm which repo maps to this project.
+7. The outcome appears in the **1. Connect GitHub** panel itself — you should see
+   **GitHub connected** naming the repository Bridge linked.
+
+That's it — no manual ID entry. If the automatic link fails for any reason, Bridge tells
+you in that same panel and points you to Option C.
+
+Connecting an editor over MCP is **optional** and is not a prerequisite for any of the
+above. If you need it, the Get Started page keeps that setup in a collapsed
+**"Need to connect an editor to the MCP?"** drawer below the GitHub panel — open it only
+if you want it.
+
+---
+
+## Option C — Manual install + Installation ID (fallback)
+
+This is the **advanced fallback**, not the normal path — use it only if neither the
+`connect-github` command (Option A) nor the one-click **Connect GitHub** button (Option B)
+is available to you (for example an org admin-approval or GitHub Marketplace install), or
+if automatic linking failed. Get Started links to it from the manual-fallback note under
+the GitHub panel.
+
+### 1. Install the app
+
+Go to the public install page and install it on the owning account/organization,
+selecting the repository/repositories you want Bridge to access:
+
+<https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new>
+
+(Same repository-selection and permissions-review screen as Option B, steps 3–5.)
+
+### 2. Find the Installation ID
+
+The Installation ID is the trailing number in the app's **Configure** URL:
+
+- **Personal account:** open **Settings → Applications → Installed GitHub Apps**, click
+  **Configure** next to *Bridge GPT - AI Tools for SFCC*. The URL is
+  `https://github.com/settings/installations/<INSTALLATION_ID>`.
+- **Organization:** open **Organization Settings → Third-party Access → GitHub Apps**,
+  click **Configure** next to the app. The URL is
+  `https://github.com/organizations/<ORG>/settings/installations/<INSTALLATION_ID>`.
+
+For example, `https://github.com/organizations/Bridge-GPT/settings/installations/61661616`
+has Installation ID **`61661616`**.
+
+### 3. Enter it in Bridge
+
+On your project's **Setup** page, in the GitHub section, paste the **Installation ID**
+into the field provided and save. Make sure the project's **version control system** is
+set to `github`. Bridge fills in the account owner and repository from your project
+settings.
+
+---
+
+## Choosing repositories
+
+When installing (any option), GitHub asks which repositories the app may access:
+
+- **All repositories** — the app can access every current and future repo on the account.
+- **Only select repositories** — pick specific repos from the **Select repositories**
+  dropdown. Recommended: grant only the repo(s) you actually want Bridge to work on.
+
+You can change this later at any time: **Configure** the installation (paths above),
+adjust **Repository access**, and click **Save**. If the app creates a repository, it is
+automatically granted access to that repo.
+
+## What the app can access
+
+At install time GitHub shows the **authoritative** list of permissions the app requests —
+review it there. Functionally, the Bridge integration exercises these GitHub permissions:
+
+| Permission | Why |
+|---|---|
+| **Contents** (read & write) | Read repo files for parsing/review; manage branch refs when opening/cleaning up PRs |
+| **Pull requests** (read & write) | List/read PRs and diffs; post review comments and reviews; merge when auto-merge is enabled |
+| **Checks / Commit statuses** (read) | Poll CI check-run and status results for a commit |
+| **Administration** (read) | Read branch-protection required-status-checks to resolve which checks must pass |
+| **Metadata** (read) | Baseline repo metadata; verify the installation's repository list |
+| **Webhook events** | Receive `pull_request`, `installation`, and review/merge events that drive automated review and merge |
+
+> These are inferred from the GitHub REST endpoints the integration calls. The exact set
+> the app is *registered* with is shown by GitHub on the install screen; treat that
+> screen as the source of truth.
+
+## Verifying the connection
+
+After linking, confirm Bridge can act on the repo:
+
+- The Bridge **Setup / integration status** should show version control as connected.
+- A Bridge operation that needs GitHub — e.g. `create_pull_request`, `resolve_ci_checks`,
+  or `poll_ci_checks` from the MCP — should succeed rather than return a
+  "no VCS connection" refusal. (See
+  [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) for which tools require
+  a VCS connection.)
+
+If a GitHub-dependent tool refuses, the installation isn't linked to that project yet —
+re-run Option A, or set the Installation ID via Option C.
+
+## Managing or removing the app
+
+- **Change repo access / review permissions:** **Configure** the installation (URLs
+  above) → adjust **Repository access** → **Save**.
+- **Uninstall:** on the same Configure page, scroll to **Danger zone → Uninstall**.
+  Uninstalling revokes Bridge's access immediately; existing stored installation IDs stop
+  working.
+
+---
+
+## Self-hosting / operator setup
+
+*Skip this section if you are an end user connecting to a hosted Bridge deployment — it is
+for whoever runs the Bridge API server.*
+
+The GitHub App identity is configured **once per deployment** via environment variables.
+Bridge uses the App private key to mint short-lived installation tokens on demand; it
+persists no long-lived GitHub token.
+
+| Env var | Value / purpose |
+|---|---|
+| `GIT_APP_ID` | The app's numeric App ID — `954077` for *Bridge GPT - AI Tools for SFCC*. |
+| `GIT_PRIVATE_KEY` | **base64-encoded PEM** private key generated for the app (GitHub → app settings → *Generate a private key*). This is the one true secret. |
+| `GITHUB_APP_INSTALL_URL` | The public install URL the **Connect GitHub** button sends users to: `https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new`. |
+| `GITHUB_WEBHOOK_SECRET` | App-level shared secret validating signed `installation` / merge webhooks. If unset, those webhooks are disabled (the redirect-callback path still works). |
+| `BGPT_ENCRYPTION_KEY` | Fernet key used to encrypt per-repo credentials at rest. |
+
+The app's **Setup URL** (in GitHub app settings) must point at the deployment's
+`GET /setup/github/callback` endpoint so the post-install redirect can auto-link the
+installation. Webhook endpoints used by the integration include the code-review hook
+(e.g. `https://<deployment-host>/github/code-review`); configure these on the app to match
+your deployment host.
+
+> **Note:** the install URL is published from two independent places, and only one reads
+> the environment. `GITHUB_APP_INSTALL_URL` drives the get-started **Connect GitHub**
+> button. The setup *instructions* — the install-instructions API, the capability report's
+> `configure_in`, and the generated README region — come from the `GITHUB_APP_INSTALL_URL`
+> constant in `api/library/config/integration_instructions.py`, which is **not**
+> env-overridable. Setting the env var alone will not correct the instructions. Keep the
+> two in sync; after editing the constant, regenerate the README with
+> `python scripts/sync_integration_readme.py`.
+
+## See also
+
+- [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) — which MCP tools need a
+  VCS connection (BLOCK) vs merely degrade without one.
+- [Installing the SFCC Integration (OCAPI)](./sfcc-integration.md) — the separate
+  Salesforce B2C sandbox integration.
+- GitHub docs: [Installing a GitHub App from a third party](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party),
+  [Reviewing and modifying installed GitHub Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).