@topline-build/harness-mcp 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
 
 ## Unreleased
 
+## 0.5.3 - pending publication
+
+- Add tenant-scoped Storyboard state, guarded edit, and exact-draft publication tools to Build MCP.
+- Check out the published Storyboard source for local Storybook iteration and submit source-only edits as a private, server-validated draft.
+
+## 0.5.2 - 2026-09-26
+
+- Report rejected bearer credentials as `authorization_required`, with scoped cache-clearing and browser reconnect guidance instead of input-correction advice.
+- Guide connection-specific cache cleanup and recovery of existing deployment progress before a write is retried.
+- Report native client certification timeouts as failures even when partial output mentions authentication; a timed-out process is not proof of a missing provider session.
+
 ## 0.5.1 - 2026-09-18
 
 - Harden the bundled Claude certification script with strict tool isolation, effective-runtime proof, and noninteractive JSONL validation.

package/README.md

@@ -22,6 +22,10 @@ npx -y @topline-build/harness-mcp
 
 Run `npx -y @topline-build/harness-mcp --help` for every supported flag and environment variable. `TOPLINE_MCP_TOKEN` is an advanced manual-token fallback; browser-approved OAuth is preferred.
 
+If a tool returns `authorization_required`, clear only that connection's OAuth cache and reconnect through browser sign-in. Replace an expired or revoked manual token if using the fallback. Inspect existing artifact/deployment progress before retrying a write; the helper does not silently replay the rejected request.
+
+Storyboard authoring uses separate `storyboard:read` and `storyboard:write` OAuth scopes. Request them explicitly with `--scopes` (or `TOPLINE_MCP_SCOPES`) and reconnect so Topline can approve the expanded grant; they are not part of the default artifact scopes. `platform_get_design_system_state` shows the published commit and current draft. `platform_checkout_design_system` creates a local checkout of that published source; run `npm ci` and `npm run storybook` there to iterate, then call `platform_submit_design_system_draft` with the exact published commit and draft ID from the state read. Wait for a successful server build, inspect the private preview, and call `platform_publish_design_system` with the reviewed run and commit values. Alternatively, `platform_edit_design_system` asks Topline's guarded coding agent to edit a draft in an existing writable Storyboard conversation. A timed-out write should be recovered by reading state before another submission. The separate Storybook reference MCP endpoint does not accept source writes.
+
 ## Typical workflow
 
 1. Use `platform_init_artifact_app` to create a starter, or point at an existing artifact app.

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export interface PackedArtifactAppBundle {
 type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
 export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export declare const HARNESS_MCP_VERSION = "0.5.1";
+export declare const HARNESS_MCP_VERSION = "0.5.3";
 export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
 export interface BuildMcpSetupOption {
     readonly flag: string;
@@ -161,6 +161,7 @@ export declare function storybookAccess(opts: HarnessMcpStdioOptions): {
     operatorAction: string;
 };
 export declare function packArtifactAppDirectory(appDir: string, archivePrefix?: string): Promise<PackedArtifactAppBundle>;
+export declare function packStoryboardSourceDirectory(appDir: string): Promise<PackedArtifactAppBundle>;
 export declare function listTools(): ListToolsResult;
 export interface BuildMcpRecoveryGuidance {
     readonly retryable: boolean;

package/dist/index.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, realpath, lstat, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, realpath, lstat, writeFile, rm, rename } from "node:fs/promises";
 import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
@@ -13,7 +13,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
 export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.5.1";
+export const HARNESS_MCP_VERSION = "0.5.3";
 export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
 export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
     { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
@@ -146,6 +146,9 @@ export async function callHarnessTool(opts, name, args, hooks) {
     let result;
     switch (name) {
         case "platform_connection_check":
+        case "platform_get_design_system_state":
+        case "platform_edit_design_system":
+        case "platform_publish_design_system":
         case "platform_list_build_workspaces":
         case "platform_list_artifact_drafts":
         case "platform_deploy_operation":
@@ -155,6 +158,12 @@ export async function callHarnessTool(opts, name, args, hooks) {
         case "platform_delete_artifact_draft":
             result = toolResult(await callHostedBuildTool(opts, name, input));
             break;
+        case "platform_checkout_design_system":
+            result = toolResult(await checkoutDesignSystem(opts, input));
+            break;
+        case "platform_submit_design_system_draft":
+            result = toolResult(await submitDesignSystemDraft(opts, input));
+            break;
         case "platform_deploy_artifact_app":
             result = toolResult(await deployArtifactApp(opts, input, hooks?.onProgress));
             break;
@@ -313,6 +322,132 @@ async function callHostedBuildTool(opts, name, input) {
         return result.structuredContent;
     throw new Error(`platform_mcp_tool_output_missing:${name}`);
 }
+async function checkoutDesignSystem(opts, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error("storyboard_requires_build_surface");
+    const targetDir = stringArg(input, "targetDir");
+    const target = await resolveWorkspacePathSafely(opts.workspaceRoot, targetDir);
+    if (existsSync(target))
+        throw new Error("storyboard_checkout_target_exists");
+    await assertAuthFileOutsideAppDir(opts.authFile, target);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    let bundle;
+    let commitSha;
+    try {
+        const response = await (opts.fetchImpl ?? fetch)(`${platformBaseUrl(opts)}/api/harness/storyboard/source-bundle`, {
+            headers: await jsonHeaders(opts), signal: controller.signal
+        });
+        if (!response.ok)
+            throw new Error(`platform_harness_http_error:${response.status}:storyboard_source_unavailable`);
+        commitSha = response.headers.get("x-topline-storyboard-commit") ?? "";
+        if (!/^[a-f0-9]{40}$/.test(commitSha))
+            throw new Error("storyboard_source_commit_invalid");
+        bundle = await readBoundedStoryboardBundle(response);
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error("platform_harness_timeout");
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const temp = await mkdtemp(path.join(os.tmpdir(), "topline-storyboard-checkout-"));
+    try {
+        const bundlePath = path.join(temp, "source.bundle");
+        await writeFile(bundlePath, bundle);
+        await mkdir(path.dirname(target), { recursive: true });
+        const staging = await mkdtemp(path.join(path.dirname(target), ".topline-storyboard-checkout-"));
+        try {
+            const candidate = path.join(staging, "source");
+            await runLocalGit(["clone", "--quiet", bundlePath, candidate]);
+            await runLocalGit(["-C", candidate, "checkout", "--quiet", "--detach", commitSha]);
+            await runLocalGit(["-C", candidate, "remote", "remove", "origin"]);
+            const actual = (await runLocalGit(["-C", candidate, "rev-parse", "HEAD"])).trim();
+            if (actual !== commitSha)
+                throw new Error("storyboard_source_commit_mismatch");
+            if (existsSync(target))
+                throw new Error("storyboard_checkout_target_exists");
+            await rename(candidate, target);
+            return { ok: true, directory: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), currentCommit: commitSha, localCommands: ["npm ci", "npm run storybook"] };
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    }
+    finally {
+        await rm(temp, { recursive: true, force: true });
+    }
+}
+async function readBoundedStoryboardBundle(response) {
+    const declared = Number(response.headers.get("content-length") ?? 0);
+    if (!Number.isSafeInteger(declared) || declared < 0 || declared > MAX_BUNDLE_BYTES) {
+        throw new Error("storyboard_source_bundle_size_invalid");
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error("storyboard_source_bundle_size_invalid");
+    const chunks = [];
+    let bytes = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        bytes += value.byteLength;
+        if (bytes > MAX_BUNDLE_BYTES) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error("storyboard_source_bundle_size_invalid");
+        }
+        chunks.push(Buffer.from(value));
+    }
+    if (bytes === 0 || (declared > 0 && declared !== bytes))
+        throw new Error("storyboard_source_bundle_size_invalid");
+    return Buffer.concat(chunks, bytes);
+}
+async function submitDesignSystemDraft(opts, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error("storyboard_requires_build_surface");
+    const localDir = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "localDir"));
+    await assertAuthFileOutsideAppDir(opts.authFile, localDir);
+    const expectedCurrentCommit = stringArg(input, "expectedCurrentCommit");
+    const expectedDraftRunId = input.expectedDraftRunId === null ? null : stringArg(input, "expectedDraftRunId");
+    const bundle = await packStoryboardSourceDirectory(localDir);
+    const digest = createHash("sha256").update(`${platformBaseUrl(opts)}:${expectedCurrentCommit}:${expectedDraftRunId ?? "none"}:${bundle.sha256}`).digest();
+    digest[6] = (digest[6] & 0x0f) | 0x40;
+    digest[8] = (digest[8] & 0x3f) | 0x80;
+    const hex = digest.subarray(0, 16).toString("hex");
+    const requestId = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    const payload = await fetchJson(opts, `${platformBaseUrl(opts)}/api/harness/storyboard/draft-bundle`, {
+        method: "POST",
+        headers: {
+            ...await jsonHeaders(opts), "content-type": "application/gzip",
+            "x-topline-request-id": requestId,
+            "x-topline-expected-current-commit": expectedCurrentCommit,
+            "x-topline-expected-draft-run-id": expectedDraftRunId ?? "none"
+        },
+        body: new Uint8Array(bundle.body)
+    }, Math.max(opts.timeoutMs, 120_000));
+    return { ...asRecord(payload), requestId, bundleSha256: bundle.sha256 };
+}
+async function runLocalGit(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", ["-c", "core.fsmonitor=false", ...args], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        let output = "";
+        const collect = (chunk) => { output = (output + chunk.toString()).slice(-2000); };
+        child.stdout.on("data", collect);
+        child.stderr.on("data", collect);
+        const timer = setTimeout(() => child.kill(), 60_000);
+        child.on("error", reject);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(output);
+            else
+                reject(new Error(`storyboard_git_command_failed:${code ?? "unknown"}`));
+        });
+    });
+}
 export async function waitForArtifactDeploy(opts, input, onProgress) {
     const artifactId = stringArg(input, "artifactId");
     const operationId = stringArg(input, "operationId");
@@ -469,13 +604,19 @@ export function storybookAccess(opts) {
     };
 }
 export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
+    return packDirectory(appDir, archivePrefix, shouldExclude);
+}
+export async function packStoryboardSourceDirectory(appDir) {
+    return packDirectory(appDir, "", shouldExcludeStoryboard);
+}
+async function packDirectory(appDir, archivePrefix, exclude) {
     const root = path.resolve(appDir);
     if ((await lstat(root)).isSymbolicLink())
         throw new Error("artifact_app_bundle_symlink_forbidden:.");
     const prefix = archivePrefix ? validateArchivePrefix(archivePrefix) : "";
     const files = [];
     const excluded = [];
-    await walk(root, root, files, excluded);
+    await walk(root, root, files, excluded, exclude);
     if (files.length === 0)
         throw new Error("artifact_app_bundle_empty");
     let byteCount = 0;
@@ -506,21 +647,21 @@ export async function packArtifactAppDirectory(appDir, archivePrefix = "") {
 function compareUtf8Paths(left, right) {
     return Buffer.compare(Buffer.from(left, "utf8"), Buffer.from(right, "utf8"));
 }
-async function walk(root, current, files, excluded) {
+async function walk(root, current, files, excluded, exclude) {
     const entries = await readdir(current, { withFileTypes: true });
     for (const entry of entries) {
         const absolute = path.join(current, entry.name);
         const relative = toPosix(path.relative(root, absolute));
         validateRelativePath(relative);
-        const stat = await lstat(absolute);
-        if (stat.isSymbolicLink())
-            throw new Error(`artifact_app_bundle_symlink_forbidden:${relative}`);
-        if (shouldExclude(relative, entry.isDirectory())) {
+        if (exclude(relative, entry.isDirectory())) {
             excluded.push(relative);
             continue;
         }
+        const stat = await lstat(absolute);
+        if (stat.isSymbolicLink())
+            throw new Error(`artifact_app_bundle_symlink_forbidden:${relative}`);
         if (entry.isDirectory()) {
-            await walk(root, absolute, files, excluded);
+            await walk(root, absolute, files, excluded, exclude);
         }
         else if (entry.isFile()) {
             if (stat.nlink > 1)
@@ -650,6 +791,13 @@ function shouldExclude(relative, isDirectory) {
         return true;
     return false;
 }
+function shouldExcludeStoryboard(relative, isDirectory) {
+    const parts = relative.split("/").filter(Boolean);
+    const name = parts.at(-1) ?? "";
+    return name.startsWith(".env") || parts.some((part) => part === ".git" || part === "node_modules"
+        || part === "storybook-static" || part === ".topline" || part === ".cursor")
+        || (isDirectory && (name === ".vite" || name === ".cache"));
+}
 function tarHeader(name, size) {
     const header = Buffer.alloc(BLOCK_SIZE);
     const { fileName, prefix } = splitTarName(name);
@@ -698,9 +846,9 @@ function padSize(size) {
     const remainder = size % BLOCK_SIZE;
     return remainder === 0 ? 0 : BLOCK_SIZE - remainder;
 }
-async function fetchJson(opts, url, init) {
+async function fetchJson(opts, url, init, timeoutMs = opts.timeoutMs) {
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
         const response = await (opts.fetchImpl ?? fetch)(url, { ...init, signal: controller.signal });
         const text = await response.text();
@@ -940,6 +1088,68 @@ const BUILD_MCP_TOOLS = [
             required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
         }
     },
+    {
+        name: "platform_get_design_system_state",
+        description: "Get the tenant Storyboard's published and draft commits, run status, and preview URL before editing or publishing. May reconcile a completed managed draft.",
+        annotations: mcpToolAnnotations("platform_get_design_system_state", { readOnly: false }),
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        outputSchema: { type: "object" }
+    },
+    {
+        name: "platform_checkout_design_system",
+        description: "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.",
+        annotations: mcpToolAnnotations("platform_checkout_design_system", { readOnly: false, openWorld: true }),
+        inputSchema: { type: "object", properties: { targetDir: { type: "string", minLength: 1 } }, required: ["targetDir"], additionalProperties: false },
+        outputSchema: { type: "object", properties: { ok: { type: "boolean" }, directory: { type: "string" }, currentCommit: { type: "string" }, localCommands: { type: "array", items: { type: "string" } } }, required: ["ok", "directory", "currentCommit", "localCommands"] }
+    },
+    {
+        name: "platform_submit_design_system_draft",
+        description: "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.",
+        annotations: mcpToolAnnotations("platform_submit_design_system_draft", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            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
+        },
+        outputSchema: { 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"] }
+    },
+    {
+        name: "platform_edit_design_system",
+        description: "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.",
+        annotations: mcpToolAnnotations("platform_edit_design_system", { readOnly: false, openWorld: true }),
+        inputSchema: {
+            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
+        },
+        outputSchema: { type: "object", properties: { runId: { type: "string" }, previewUrl: { type: "string" } }, required: ["runId", "previewUrl"] }
+    },
+    {
+        name: "platform_publish_design_system",
+        description: "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.",
+        annotations: mcpToolAnnotations("platform_publish_design_system", { readOnly: false, destructive: true, openWorld: true }),
+        inputSchema: {
+            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
+        },
+        outputSchema: { type: "object", properties: { publishedCommit: { type: "string" } }, required: ["publishedCommit"] }
+    },
     {
         name: "platform_validate_artifact",
         description: "Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.",
@@ -1063,6 +1273,7 @@ function toolError(message) {
     return structuredToolError(message);
 }
 const BUILD_MCP_RECOVERY_ERROR_VALUES = {
+    authorization_required: { retryable: false, recoveryAction: "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: true, recoveryAction: "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: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
     artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
@@ -1087,6 +1298,8 @@ function structuredToolError(message) {
     };
 }
 function recoveryErrorCode(message) {
+    if (/^platform_harness_http_error:401(?::|$)/.test(message))
+        return "authorization_required";
     const known = [
         "artifact_delete_plan_stale",
         "artifact_deploy_wait_timeout",