@bridge_gpt/mcp-server 0.2.36 → 0.2.38

package/README.md

@@ -397,7 +397,7 @@ An entry with no trailing `serve` still starts the server — bare invocation me
 <summary><strong>Upgrading Bridge</strong></summary>
 
 ```bash
-npx -y @bridge_gpt/mcp-server upgrade
+npx -y @bridge_gpt/mcp-server@latest --upgrade
 ```
 
 `upgrade` fetches the latest published version, refreshes your scaffolded slash
@@ -405,8 +405,34 @@ commands, agents, and pipelines, updates the version pin in your MCP config, and
 opens a session so you can reconnect. It is also available as the
 `/upgrade-bridge` slash command.
 
-The server checks for updates on startup and notes a newer version in your editor's
-MCP output log. That check is cached for a day and never blocks startup.
+Use the `@latest` form. It applies to the short-lived *upgrader* process: without
+it, npx may reuse a cached older copy of the package and "upgrade" you with the
+build you are trying to replace. The exact `MAJOR.MINOR.PATCH` pin the upgrader
+writes into your MCP config is deliberately different — host configs stay pinned
+to an exact release so a project's server is reproducible.
+
+`upgrade` reports **per config file**, because a project can have several
+(`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`) and they can disagree:
+
+```
+Launcher pins:
+  .mcp.json: 0.2.16 -> 0.2.36
+  .cursor/mcp.json: already 0.2.36
+```
+
+When every applicable launcher pin was already at the target, it prints
+`Already up-to-date.` — that status comes from comparing your configs, not from
+the version of the CLI process. A non-zero exit means the upgrade did **not**
+converge (an unreadable config, a launcher carrying a version range the upgrader
+must not rewrite, a competing local install it could not remove, or a pin that
+failed post-write verification); nothing is reported as complete in that case.
+
+The server checks for updates on startup. The check is cached for a day and never
+blocks startup. When a newer version is known, it surfaces in two places you do
+not have to go looking for: a one-line warning on the server's **stderr**, and a
+short advisory attached to the ordinary `tools/list` response so the agent in the
+session can see that some tools may be missing or renamed in the older build.
+Neither requires calling `ping` or `doctor`.
 
 Re-running `install` on an already-configured project is safe: it refreshes the
 scaffolded files without overwriting your stored credential unless you pass
@@ -559,6 +585,12 @@ Good to know, but not needed every day.
 - **How to use it:** Ask your agent to resume the full-automation chain, naming the run to continue.
 - **Flags:** None.
 
+**15. Update Ticket Description**
+- **What it does:** Rewrites a ticket's description with AI, using the ticket's own content and its reference material. A rewrite that changes more than 60% of the description is held for review instead of applied.
+- **When it's useful:** (Refinement) When a ticket has accumulated comments, attachments, or links and its description no longer reflects them.
+- **How to use it:** Ask your agent — "Update the description for BAPI-123."
+- **Flags:** None. Poll the ticket's state for the outcome; if the update was held for review, read the proposal instead of applying it blind.
+
 ### Now and then
 
 Useful once in a while.
@@ -611,7 +643,13 @@ Useful once in a while.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**9. Estimate Epic**
+**9. Estimate Ticket**
+- **What it does:** Estimates the development effort for one ticket. Use Estimate Epic instead for a whole epic or a named group of tickets.
+- **When it's useful:** (Refinement) When you need a size for a single ticket before committing to it.
+- **How to use it:** Ask your agent — "Estimate BAPI-123."
+- **Flags:** Ask for a fresh estimate to regenerate rather than reuse a stored one.
+
+**10. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
@@ -756,7 +794,9 @@ Without this, only the diagnostic tools are registered.
 
 ### Tools
 
-All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
+All SFCC tools are read-only and target a developer sandbox. An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
+
+Attribute-definition reads and writes can return an attribute's `default_value` at `projection: "full"`, and Bridge withholds it — every key is preserved except that one, whose value becomes `[REDACTED_BY_BRIDGE]` — from the inline response, the saved file, and a successful write echo alike. Attribute defaults are intentionally unavailable through this MCP surface; Business Manager is the supported path to read one.
 
 **Diagnostics** (always available, no profile needed)
 - `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
@@ -764,12 +804,12 @@ All SFCC tools are read-only and target a developer sandbox. Oversized responses
 
 **System object model** (needs the `sfcc` profile)
 - `system_object_list` — list system object types (Product, Order, Customer, …).
-- `system_object_get` — fetch one type's definition, optionally with its full attribute definitions (`expand_attribute_definitions`).
+- `system_object_get` — fetch one system object type's definition.
 - `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
 
 **Custom object definitions** (needs the `sfcc` profile)
-- `custom_object_definition_attributes_get` — fetch attribute definitions for a known custom object type. OCAPI cannot enumerate custom object types, so `object_type` must already be known.
-- `custom_object_definition_attribute_search` — search attribute definitions within a known custom object type. Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability.
+- `custom_object_definition_attributes_get` — fetch attribute definitions for a known custom object type (`default_value` withheld). OCAPI cannot enumerate custom object type *IDs* directly, so `object_type` must be known — but it is discoverable: call `system_object_list` at `projection: "full"` for each custom type's `display_name` and `attribute_definition_count`, derive a candidate id (e.g. strip spaces from `"Product Quality Result"` → `ProductQualityResult`), and confirm it by checking that this tool's returned attribute count matches that row's `attribute_definition_count`.
+- `custom_object_definition_attribute_search` — search attribute definitions within a known custom object type (`default_value` withheld). Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability. Same discovery path as above applies to `object_type`.
 - `custom_object_definition_attribute_create` — **write** (sandbox only): create an attribute definition on a known custom object type via `PUT /custom_object_definitions/{type}/attribute_definitions/{id}`. TYPE creation is never attempted (the type must pre-exist). Echoes paste-ready OCAPI grant JSON on 403.
 - `custom_object_definition_attribute_update` — **write** (sandbox only): update an attribute definition via an ETag-conditional `PATCH …/attribute_definitions/{id}`; surfaces 409/412 conflicts and echoes grant JSON on 403.
 

package/build/base-url.js

@@ -0,0 +1,79 @@
+/**
+ * Pure Bridge API base-URL normalization and validation (BAPI-727).
+ *
+ * Extracted so the executor's credential resolution and the `mcp-invoke` shim can
+ * share ONE definition of "normalized base URL" without `mcp-invoke` importing
+ * executor runtime behavior (`executor/credentials.ts` pulls in the executor deps
+ * types and the credential store, neither of which the shim should depend on).
+ *
+ * Everything here is pure: no filesystem, no process, no network, no environment.
+ * Validation messages name the flag and the reason ONLY — never the supplied URL,
+ * which can carry embedded credentials in its userinfo component.
+ */
+/**
+ * Trim, strip every trailing slash, and treat an empty result as absent.
+ *
+ * This is the executor's long-standing normalization, moved verbatim so the value
+ * a worker registration carries is byte-identical to the one the executor itself
+ * uses for its HTTP calls.
+ */
+export function normalizeBaseUrlCandidate(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const normalized = raw.trim().replace(/\/+$/, "");
+    return normalized.length > 0 ? normalized : null;
+}
+/** Fixed, secret-free explanation for each rejection reason. */
+const REJECTION_TEXT = {
+    empty: "value is empty",
+    "not-absolute-http-url": "value is not an absolute URL",
+    "unsupported-scheme": "only http: and https: URLs are supported",
+    "missing-hostname": "URL has no hostname",
+    "embedded-credentials": "URL must not embed a username or password",
+};
+/**
+ * Human-readable rejection message for a flag. Interpolates only the flag name and
+ * a fixed reason — deliberately NOT the rejected value, so a URL containing
+ * `https://user:secret@host` can never reach an error string, usage text, or log.
+ */
+export function describeBaseUrlRejection(flag, reason) {
+    return `Invalid ${flag}: ${REJECTION_TEXT[reason]}`;
+}
+/**
+ * Strictly validate a base URL supplied on a command line: it must be a non-empty,
+ * absolute `http:`/`https:` URL with a hostname and no embedded user information.
+ * The accepted value is returned normalized by
+ * {@link normalizeBaseUrlCandidate} so it matches the executor's own form.
+ */
+export function validateHttpBaseUrl(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { ok: false, reason: "empty" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        // A relative value ("/api", "api.example.test/x") lands here: the WHATWG URL
+        // constructor requires an absolute URL when no base is supplied.
+        return { ok: false, reason: "not-absolute-http-url" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, reason: "unsupported-scheme" };
+    }
+    // Defensive: for http/https the WHATWG parser already rejects an empty
+    // authority above (`http://` throws), so this branch is not reachable through
+    // those schemes today. It is kept because "must have a hostname" is the real
+    // invariant, and relying on a parser implementation detail to enforce it would
+    // be fragile.
+    if (parsed.hostname.length === 0) {
+        return { ok: false, reason: "missing-hostname" };
+    }
+    if (parsed.username.length > 0 || parsed.password.length > 0) {
+        return { ok: false, reason: "embedded-credentials" };
+    }
+    const normalized = normalizeBaseUrlCandidate(raw);
+    if (normalized === null)
+        return { ok: false, reason: "empty" };
+    return { ok: true, baseUrl: normalized };
+}

package/build/bridge-api-urls.js

@@ -9,6 +9,15 @@
  *
  * The base URL is supplied by the caller (never hardcoded here) and its
  * trailing slashes are trimmed so no doubled slash is produced.
+ *
+ * The `/jira` segment is the Bridge API's TRANSPORT namespace — the router mount
+ * that serves these routes in BOTH ticket backend modes. It is not, and must not
+ * become, an agent-visible ticket link: a ticket's URL is whatever the server
+ * returns on the create/read response (`https://…` in Jira mode,
+ * `local://tickets/…` in local mode) and is passed through verbatim. Renaming
+ * this mount is explicitly out of scope (no renaming of Jira-shaped surfaces),
+ * and synthesizing a ticket URL from it would produce a link to an API route
+ * rather than to a ticket.
  */
 /**
  * Create the URL builders bound to `baseUrl`. Trailing slashes on the base are

package/build/chain-orchestrator.js

@@ -25,6 +25,8 @@
  */
 import { runPipeline, resumePipeline, peekPipelineRun } from "./pipeline-orchestrator.js";
 import { toStringVariable, substituteChainValue } from "./chain-utils.js";
+import { isValidTicketKey, validateTicketKeys } from "./ticket-key-utils.js";
+import { isUnsupportedInLocalModeEnvelope, parseToolErrorEnvelope, } from "./tool-error-envelope.js";
 const CHAIN_NAME = "full-automation";
 const START_TICKETS_PIPELINE = "start-tickets";
 // Display titles for preambles, keyed by child pipeline name.
@@ -166,13 +168,22 @@ function normalizeAutoApprove(value) {
         return true;
     return false;
 }
-const JIRA_KEY_EXACT = /^[A-Z][A-Z0-9]+-\d+$/;
 /**
- * Extract created Jira ticket keys from a STRUCTURED payload (an object/array
+ * Extract created ticket keys from a STRUCTURED payload (an object/array
  * holding `created_ticket_keys` / `ticket_key` / etc.). Collects values from the
- * preferred key fields in a fixed preference order, validates each against
- * `JIRA_KEY_EXACT`, and de-dupes in encounter order. There is deliberately NO
- * free-text regex fallback: pass the parsed upload-step payload (via
+ * preferred key fields in a fixed preference order, validates each against the
+ * canonical `TICKET_KEY_PATTERN`, and de-dupes in encounter order.
+ *
+ * BAPI-710: the validation used to run against a private `/^[A-Z][A-Z0-9]+-\d+$/`
+ * that rejected keys the server mints (`MY_PROJ-248`, `A-1`), and this helper
+ * DROPPED every non-match silently. Silent dropping is now impossible for the
+ * chain — {@link extractCreatedTicketPayload} rejects the whole payload and names
+ * every offending key. This flat helper still filters (its `string[]` contract
+ * has no failure channel), but it is a non-chain compatibility path only and the
+ * grammar it filters on is now the correct one.
+ *
+ * There is deliberately NO free-text regex fallback: pass the parsed
+ * upload-step payload (via
  * `extractCreatedKeysFromCompletedChild`), never a whole pipeline transcript, so
  * keys merely *mentioned* by an earlier step (e.g. duplicate-detection search
  * hits) can never be mistaken for this run's creations. A string / no-field
@@ -226,7 +237,7 @@ export function extractCreatedTicketKeys(source) {
     const ordered = [];
     for (const key of preferredKeys) {
         for (const candidate of buckets[key]) {
-            if (JIRA_KEY_EXACT.test(candidate))
+            if (isValidTicketKey(candidate))
                 ordered.push(candidate);
         }
     }
@@ -278,7 +289,7 @@ function tryParseJson(raw) {
     }
 }
 function isValidJiraKey(value) {
-    return typeof value === "string" && JIRA_KEY_EXACT.test(value);
+    return isValidTicketKey(value);
 }
 /**
  * Normalize a PARSED, STRUCTURED upload payload into a {@link CreatedTicketPayload}.
@@ -316,7 +327,7 @@ export function extractCreatedTicketPayload(source) {
         if (!isValidJiraKey(parent)) {
             return {
                 ok: false,
-                error: `Epic payload "epic_parent_key" must be a valid Jira key; got ${JSON.stringify(parent)}.`,
+                error: `Epic payload "epic_parent_key" must be a valid ticket key; got ${JSON.stringify(parent)}.`,
             };
         }
         const rawChildren = obj.child_ticket_keys;
@@ -327,14 +338,20 @@ export function extractCreatedTicketPayload(source) {
                     "implementable child ticket key.",
             };
         }
+        // Validate the WHOLE child list first and report every rejected key in one
+        // error (BAPI-710). Failing on the first bad key made a caller fix its
+        // payload one key per round trip, and the previous grammar rejected keys the
+        // server legitimately mints — so a mixed-validity list must fail atomically,
+        // never advance with the valid subset.
+        const childKeyCheck = validateTicketKeys(rawChildren, "child_ticket_keys entry");
+        if (!childKeyCheck.ok) {
+            return {
+                ok: false,
+                error: `Epic payload "child_ticket_keys" must contain only valid implementable ticket keys. ${childKeyCheck.message}`,
+            };
+        }
         const children = [];
         for (const c of rawChildren) {
-            if (!isValidJiraKey(c)) {
-                return {
-                    ok: false,
-                    error: `Epic payload "child_ticket_keys" must contain only valid implementable Jira keys; got ${JSON.stringify(c)}.`,
-                };
-            }
             if (c === parent) {
                 return {
                     ok: false,
@@ -361,7 +378,7 @@ export function extractCreatedTicketPayload(source) {
             return {
                 ok: false,
                 error: 'Single-ticket payload "created_ticket_keys" must contain exactly ' +
-                    "one valid implementable Jira key. A multi-key list is malformed " +
+                    "one valid implementable ticket key. A multi-key list is malformed " +
                     '(the legacy "first key is the Epic parent" convention is not accepted).',
             };
         }
@@ -431,6 +448,36 @@ function failedEnvelopeMentions(env, token) {
     }
     return false;
 }
+/**
+ * Find a recognized ``UNSUPPORTED_IN_LOCAL_MODE`` refusal anywhere in a child
+ * pipeline envelope (BAPI-710).
+ *
+ * Scans the top-level halt error and each step's ``error`` / string ``result``,
+ * matching only the exact ``(error, status)`` pair via the strict parser — never
+ * a substring of prose, so an echoed input or a message that merely mentions the
+ * marker cannot terminate a chain.
+ *
+ * A ``completed`` envelope is scanned too, not just a ``failed`` one: a
+ * ``warn_and_continue`` step in an older persisted run can have swallowed the
+ * refusal into a completed envelope, and treating that as success is exactly the
+ * partial-success outcome this check exists to prevent.
+ */
+function findUnsupportedLocalModeRefusal(env) {
+    const topLevel = parseToolErrorEnvelope(env.error);
+    if (isUnsupportedInLocalModeEnvelope(topLevel))
+        return topLevel;
+    const results = env.results;
+    if (!Array.isArray(results))
+        return null;
+    for (const step of results) {
+        for (const candidate of [step?.error, step?.result]) {
+            const parsed = parseToolErrorEnvelope(candidate);
+            if (isUnsupportedInLocalModeEnvelope(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
 /**
  * Heuristic, no-LLM one-line stage summary. idea-to-ticket passes a structured
  * {@link CreatedTicketPayload} so the summary distinguishes the Epic parent from
@@ -782,6 +829,37 @@ async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, o
             }),
         };
     }
+    // BAPI-710 terminal gate. Runs BEFORE the failed-mapping branch, before the
+    // fan-out advance, and before the single-child finalize — i.e. before review
+    // fan-out, worktree preparation, or any start-tickets command can be emitted.
+    // A backend that cannot perform the operation will not start being able to on
+    // the next stage, so continuing would only produce a partial success that
+    // looks like a real one.
+    const refusal = findUnsupportedLocalModeRefusal(childEnv);
+    if (refusal) {
+        const stages = cloneStages(row.stages);
+        if (stages[idx])
+            stages[idx].status = "failed";
+        try {
+            await persistence.patchRun(row.chain_run_id, { stages, status: "failed" });
+        }
+        catch {
+            // best-effort — the terminal failure is what matters
+        }
+        return {
+            kind: "fail",
+            envelope: {
+                ...failedEnvelope("TOOL_ERROR", refusal.message, {
+                    chain_run_id: row.chain_run_id,
+                    chain_stage: stageRecipe.pipeline_name,
+                    chain_step: idx + 1,
+                    chain_total: total,
+                }),
+                backend_error: refusal.error,
+                ...(refusal.supported_in ? { supported_in: refusal.supported_in } : {}),
+            },
+        };
+    }
     if (childEnv.status === "failed") {
         // Stage 0 vagueness or no-keys produced => VALIDATION. Anchor the sentinel
         // check to the failure-text fields (the halt error + per-step error/result