@topline-build/harness-mcp 0.5.1 → 0.5.3

package/docs/generated/build-mcp-reference.md

@@ -2,7 +2,7 @@
 
 > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
 
-Package: `@topline-build/harness-mcp@0.5.1`
+Package: `@topline-build/harness-mcp@0.5.3`
 Transport: `stdio`
 Default protocol: `2025-11-25`
 Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -32,6 +32,7 @@ The first authenticated tool call normally opens browser approval. Set `TOPLINE_
 
 Tool failures set `isError: true` and return `structuredContent.error` with `code`, `message`, `retryable`, and `recoveryAction`.
 
+- `authorization_required` (not automatically retryable): Clear only this connection's cached OAuth credentials, then reconnect the Build MCP through browser sign-in. If using a manual bearer token, replace the expired or revoked token. Recover existing artifact/deployment progress before retrying a write.
 - `platform_harness_timeout` (retryable): Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress.
 - `platform_mcp_tool_error` (not automatically retryable): Read the returned error code, correct the request or OAuth scopes, then retry.
 - `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.
@@ -1604,6 +1605,591 @@ Output schema:
 }
 ```
 
+### `platform_get_design_system_state`
+
+Get the tenant Storyboard's published and draft commits, run status, and preview URL before editing or publishing. May reconcile a completed managed draft.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=false.
+
+Example request:
+
+```json
+{}
+```
+
+Example success:
+
+```json
+{}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {},
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_checkout_design_system`
+
+Download the exact published tenant Storyboard source into a new local directory for Codex or Claude Code to edit and run with npm ci and npm run storybook. Never overwrites an existing directory.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "targetDir": "<targetDir>"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "directory": "<directory>",
+  "currentCommit": "<currentCommit>",
+  "localCommands": []
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "targetDir": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "targetDir"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "directory": {
+          "type": "string"
+        },
+        "currentCommit": {
+          "type": "string"
+        },
+        "localCommands": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "ok",
+        "directory",
+        "currentCommit",
+        "localCommands"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_submit_design_system_draft`
+
+Package a locally edited Storyboard source directory and submit it as a private draft against exact published and draft revisions. The server validates and builds it before it can be published.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "localDir": "<localDir>",
+  "expectedCurrentCommit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "expectedDraftRunId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "ok": true,
+  "runId": "<runId>",
+  "draftCommit": "<draftCommit>",
+  "draftState": "<draftState>",
+  "previewUrl": "<previewUrl>",
+  "requestId": "<requestId>",
+  "bundleSha256": "<bundleSha256>"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "localDir": {
+      "type": "string",
+      "minLength": 1
+    },
+    "expectedCurrentCommit": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{40}$"
+    },
+    "expectedDraftRunId": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uuid"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "localDir",
+    "expectedCurrentCommit",
+    "expectedDraftRunId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "runId": {
+          "type": "string"
+        },
+        "draftCommit": {
+          "type": "string"
+        },
+        "draftState": {
+          "type": "string"
+        },
+        "previewUrl": {
+          "type": "string"
+        },
+        "requestId": {
+          "type": "string"
+        },
+        "bundleSha256": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "ok",
+        "runId",
+        "draftCommit",
+        "draftState",
+        "previewUrl",
+        "requestId",
+        "bundleSha256"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_edit_design_system`
+
+Start an asynchronous Storyboard draft edit in an existing writable Topline Storyboard conversation. Pass expectedDraftRunId from the last state read (null for no draft); stale or concurrent retries are rejected.
+
+Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "conversationId": "00000000-0000-4000-8000-000000000001",
+  "instruction": "<instruction>",
+  "expectedDraftRunId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+Example success:
+
+```json
+{
+  "runId": "<runId>",
+  "previewUrl": "<previewUrl>"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "conversationId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "instruction": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 10000
+    },
+    "expectedDraftRunId": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "uuid"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "conversationId",
+    "instruction",
+    "expectedDraftRunId"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "runId": {
+          "type": "string"
+        },
+        "previewUrl": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "runId",
+        "previewUrl"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
+### `platform_publish_design_system`
+
+Publish the exact reviewed Storyboard draft after its build passes. Managed edits require their writable Storyboard conversation; local submissions require the submitting actor. Always pass state-bound run, draft, and current commits.
+
+Safety: read-only=false, destructive=true, idempotent=false, open-world=true.
+
+Example request:
+
+```json
+{
+  "expectedDraftRunId": "00000000-0000-4000-8000-000000000001",
+  "expectedDraftCommit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "expectedCurrentCommit": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+}
+```
+
+Example success:
+
+```json
+{
+  "publishedCommit": "<publishedCommit>"
+}
+```
+
+Input schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "conversationId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "expectedDraftRunId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "expectedDraftCommit": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{40}$"
+    },
+    "expectedCurrentCommit": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40}$"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "expectedDraftRunId",
+    "expectedDraftCommit",
+    "expectedCurrentCommit"
+  ],
+  "additionalProperties": false
+}
+```
+
+Output schema:
+
+```json
+{
+  "type": "object",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "publishedCommit": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "publishedCommit"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "const": false
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "recoveryAction": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable",
+            "recoveryAction"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "ok",
+        "error"
+      ],
+      "additionalProperties": false
+    }
+  ]
+}
+```
+
 ### `platform_validate_artifact`
 
 Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/certify-live.mjs

@@ -218,9 +218,7 @@ async function agentMediatedRead(name, command, scratch, apiUrl, appDir, workspa
     "-p", "--verbose", "--output-format", "stream-json", prompt
   ], scratch, 180000, strictAgentEnvironment(process.env));
   if (!result.ok) {
-    return authUnavailable(result.output)
-      ? skipped("provider_credentials_or_client_session_unavailable")
-      : failed("client_mediated_read_failed", result.exitCode);
+    return clientMediatedFailure(result);
   }
   const usedTool = hasToolCallEvidence(result.output, "platform_inspect_artifact_app");
   const certified = hasAssistantCertificationEvidence(result.output);
@@ -344,6 +342,12 @@ async function certifyProtocol({ apiUrl, token, appDir, workspaceRoot }) {
 }
 
 function selfTestReport() {
+  const timedOutProbe = run({ executable: process.execPath, prefix: [] }, ["-e", "console.log('api key authentication required'); setInterval(() => {}, 1000)"], process.cwd(), 1000);
+  const timedOutFailure = clientMediatedFailure(timedOutProbe);
+  if (!timedOutProbe.timedOut || !authUnavailable(timedOutProbe.output) || timedOutFailure.status !== "failed" || timedOutFailure.reason !== "client_mediated_read_timed_out"
+    || clientMediatedFailure({ timedOut: false, output: "not logged in", exitCode: 1 }).status !== "skipped") {
+    throw new Error("client_timeout_classification_self_test_failed");
+  }
   const toolName = "platform_inspect_artifact_app";
   const promptOnly = JSON.stringify({ type: "user", content: `Call ${toolName} and print TOPLINE_CLIENT_READ_CERTIFIED.` });
   const toolEvent = JSON.stringify({ type: "item.completed", item: { type: "mcp_tool_call", tool: toolName } });
@@ -477,12 +481,20 @@ function run(command, commandArgs, cwd, timeout = 30000, env = clientProbeEnviro
   return {
     ok: result.status === 0,
     missing: result.error?.code === "ENOENT",
+    timedOut: result.error?.code === "ETIMEDOUT",
     exitCode: result.status,
     stdout: result.stdout || "",
     output: `${result.stdout || ""}\n${result.stderr || ""}`
   };
 }
 
+function clientMediatedFailure(result) {
+  if (result.timedOut) return failed("client_mediated_read_timed_out", result.exitCode);
+  return authUnavailable(result.output)
+    ? skipped("provider_credentials_or_client_session_unavailable")
+    : failed("client_mediated_read_failed", result.exitCode);
+}
+
 function authUnavailable(output) {
   return /not logged in|not authenticated|authentication required|api key|login required|please login|sign in|unable to locate credentials|security token|AccessDeniedException|UnrecognizedClientException/i.test(output);
 }