@topline-build/harness-mcp 0.5.2 → 0.6.0

package/dist/index.js

@@ -1,11 +1,13 @@
 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 { cp, 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";
 import { gzipSync } from "node:zlib";
+import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS } from "./build-session-tools.js";
+import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
@@ -13,7 +15,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.2";
+export const HARNESS_MCP_VERSION = "0.6.0";
 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 +148,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 +160,18 @@ 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_checkout_artifact_app":
+            result = toolResult(await checkoutArtifactApp(opts, input));
+            break;
+        case "platform_materialize_assets":
+            result = toolResult(await materializeBuildAssets(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;
@@ -180,6 +197,12 @@ export async function callHarnessTool(opts, name, args, hooks) {
             result = toolResult(await initArtifactApp(opts, input));
             break;
         default:
+            if (EXTERNAL_BUILD_FORWARD_TOOLS.has(name)) {
+                if (mcpSurface(opts) !== "build")
+                    throw new Error("external_session_requires_build_surface");
+                result = toolResult(await callHostedBuildTool(opts, name, input));
+                break;
+            }
             throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
     }
     const outputError = tool.outputSchema
@@ -194,7 +217,8 @@ export async function deployArtifactApp(opts, input, onProgress) {
     await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
     const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
-    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
+    const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
     const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
         .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
         .digest("hex");
@@ -204,18 +228,39 @@ export async function deployArtifactApp(opts, input, onProgress) {
     if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
         throw new Error("artifact_app_bundle_changed_after_inspection");
     }
+    const sessionId = optionalString(input, "sessionId");
+    const sessionVersion = optionalString(input, "artifactVersionId");
+    const idempotencyKey = optionalString(input, "idempotencyKey");
+    const inspectedSourceHash = optionalString(input, "inspectedSourceHash");
+    let sessionArtifactId;
+    if (sessionId) {
+        if (mcpSurface(opts) !== "build")
+            throw new Error("external_session_requires_build_surface");
+        if (!sessionVersion || !idempotencyKey || !inspectedSourceHash || !expectedBundleSha256)
+            throw new Error("build_session_deployment_arguments_required");
+        const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
+        // The server resolves a repeated operation key before checking current
+        // version/source. Do not reject a lost-response retry using the newer read.
+        // Fresh mutations still require the caller's exact inspected revision.
+        sessionArtifactId = stringValue(session.artifactId, "artifactId");
+        if (input.artifactId !== undefined && input.artifactId !== sessionArtifactId)
+            throw new Error("build_session_artifact_mismatch");
+    }
+    else if (sessionVersion || idempotencyKey || inspectedSourceHash || suppliedPlatformAppDir)
+        throw new Error("build_session_id_required");
     await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
         body: JSON.stringify({
-            artifactId: optionalString(input, "artifactId"),
+            artifactId: sessionArtifactId ?? optionalString(input, "artifactId"),
             title: optionalString(input, "title"),
             description: optionalString(input, "description"),
             projectId: optionalString(input, "projectId"),
             clientRequestId,
             bundleSha256: bundle.sha256,
-            manifest
+            manifest,
+            ...(sessionId ? { sessionId, artifactVersionId: sessionVersion, idempotencyKey, inspectedSourceHash } : {})
         })
     });
     const createdRecord = asRecord(created);
@@ -232,19 +277,22 @@ export async function deployArtifactApp(opts, input, onProgress) {
             "content-type": "application/gzip",
             "MCP-Protocol-Version": opts.protocolVersion,
             "x-platform-artifact-version-id": artifactVersionId,
-            "x-platform-app-dir": platformAppDir
+            "x-platform-app-dir": platformAppDir,
+            ...(sessionId ? { "x-platform-build-session-id": sessionId, "x-platform-idempotency-key": idempotencyKey, "x-platform-inspected-source-sha256": inspectedSourceHash, "x-platform-expected-bundle-sha256": bundle.sha256 } : {})
         },
         body: bundle.body
     });
     await onProgress?.(1, "Completed trusted draft deployment");
     const deployedRecord = asRecord(deployed);
-    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
+    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId
+        : typeof deployedRecord.operationId === "string" ? deployedRecord.operationId : null;
     return {
         ok: true,
         artifactId,
         artifactVersionId,
         manifestId: typeof manifest.id === "string" ? manifest.id : null,
         clientRequestId,
+        ...(sessionId ? { sessionId } : {}),
         operationId,
         bundle: {
             fileCount: bundle.fileCount,
@@ -256,13 +304,135 @@ export async function deployArtifactApp(opts, input, onProgress) {
         deploy: deployed
     };
 }
+async function fetchBuildTransfer(opts, advertisedPath, expectedPath, sha256, maxBytes, expectedSize, revision) {
+    if (advertisedPath !== expectedPath || typeof sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(sha256))
+        throw new Error("build_transfer_identity_invalid");
+    const base = new URL(platformBaseUrl(opts));
+    const url = new URL(expectedPath, base);
+    if (url.origin !== base.origin || url.pathname !== expectedPath || url.search || url.hash)
+        throw new Error("build_transfer_identity_invalid");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        const response = await (opts.fetchImpl ?? fetch)(url.href, { method: "GET", headers: await jsonHeaders(opts), redirect: "error", signal: controller.signal });
+        if (!response.ok || (response.url && new URL(response.url).origin !== base.origin))
+            throw new Error("build_transfer_unavailable");
+        if (response.headers.get("x-topline-content-sha256")?.toLowerCase() !== sha256.toLowerCase())
+            throw new Error("build_transfer_hash_mismatch");
+        if (revision && (response.headers.get("x-topline-artifact-version") !== revision.artifactVersionId || response.headers.get("x-topline-source-commit") !== revision.commitSha))
+            throw new Error("build_transfer_revision_mismatch");
+        const body = await boundedTransfer(response, maxBytes, expectedSize);
+        if (createHash("sha256").update(body).digest("hex") !== sha256.toLowerCase())
+            throw new Error("build_transfer_hash_mismatch");
+        return body;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error("platform_harness_timeout");
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function newBuildInputTarget(opts, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error("external_session_requires_build_surface");
+    const target = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
+    if (existsSync(target))
+        throw new Error("build_input_target_exists");
+    await assertAuthFileOutsideAppDir(opts.authFile, target);
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const checked = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
+    if (checked !== target)
+        throw new Error("build_input_target_changed");
+    return target;
+}
+async function installBuildInputs(opts, target, stage) {
+    // Reserve the new target exclusively; never rename over a directory another
+    // process created. cp refuses existing files rather than overwriting them.
+    await resolveWorkspacePathSafely(opts.workspaceRoot, path.relative(opts.workspaceRoot, target));
+    await mkdir(target, { mode: 0o700 });
+    try {
+        for (const entry of await readdir(stage))
+            await cp(path.join(stage, entry), path.join(target, entry), { recursive: true, force: false, errorOnExist: true });
+    }
+    catch (error) {
+        await rm(target, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function checkoutArtifactApp(opts, input) {
+    const target = await newBuildInputTarget(opts, input);
+    const sessionId = stringArg(input, "sessionId");
+    const metadata = asRecord(await callHostedBuildTool(opts, "platform_checkout_artifact_app", { sessionId }));
+    const artifactVersionId = stringValue(metadata.artifactVersionId, "artifactVersionId");
+    const commitSha = stringValue(metadata.commitSha, "commitSha");
+    if (!/^[a-f0-9]{40}$/.test(commitSha) || !/^[0-9a-f-]{36}$/i.test(artifactVersionId))
+        throw new Error("build_transfer_revision_invalid");
+    const body = await fetchBuildTransfer(opts, metadata.downloadPath, `/api/harness/build-sessions/${sessionId}/source`, metadata.sha256, MAX_SOURCE_ARCHIVE_BYTES, undefined, { artifactVersionId, commitSha });
+    const staging = await mkdtemp(path.join(path.dirname(target), ".topline-app-checkout-"));
+    try {
+        const source = path.join(staging, "source");
+        await mkdir(source, { mode: 0o700 });
+        const extracted = await extractArtifactSourceArchive(body, source);
+        if (extracted.fileCount !== metadata.fileCount || extracted.byteCount !== metadata.byteCount)
+            throw new Error("artifact_source_shape_mismatch");
+        await readManifest(source);
+        await installBuildInputs(opts, target, source);
+        return { ok: true, sessionId, artifactId: metadata.artifactId, artifactVersionId, commitSha, sourceHash: extracted.sha256,
+            appDir: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), platformAppDir: metadata.appDir,
+            fileCount: extracted.fileCount, byteCount: extracted.byteCount };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+export async function materializeBuildAssets(opts, input) {
+    const target = await newBuildInputTarget(opts, input);
+    const sessionId = stringArg(input, "sessionId");
+    const assetIds = input.assetIds;
+    if (!Array.isArray(assetIds) || !assetIds.length || assetIds.length > 50 || assetIds.some(id => typeof id !== "string" || !/^[0-9a-f-]{36}$/i.test(id)))
+        throw new Error("asset_selection_required");
+    const selected = new Set(assetIds);
+    const metadata = asRecord(await callHostedBuildTool(opts, "platform_materialize_assets", { sessionId, assetIds }));
+    if (!Array.isArray(metadata.assets) || metadata.assets.length !== selected.size)
+        throw new Error("asset_transfer_identity_invalid");
+    const assets = metadata.assets.map(asRecord);
+    if (assets.some(asset => typeof asset.id !== "string" || !selected.delete(asset.id)) || selected.size)
+        throw new Error("asset_transfer_identity_invalid");
+    const staging = await mkdtemp(path.join(path.dirname(target), ".topline-assets-"));
+    let total = 0;
+    try {
+        const files = [];
+        for (const asset of assets) {
+            const size = asset.size;
+            if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 16 * 1024 * 1024 || (total += size) > 64 * 1024 * 1024)
+                throw new Error("asset_transfer_too_large");
+            const name = stringValue(asset.name, "name");
+            if (Buffer.byteLength(name, "utf8") > 200 || name.includes("/") || safeSourcePath(name) !== name)
+                throw new Error("asset_transfer_name_invalid");
+            const id = stringValue(asset.id, "id");
+            const body = await fetchBuildTransfer(opts, asset.downloadPath, `/api/harness/build-sessions/${sessionId}/assets/${id}`, asset.sha256, 16 * 1024 * 1024, size);
+            const localName = `${id}-${name}`;
+            await writeFile(path.join(staging, localName), body, { mode: 0o600, flag: "wx" });
+            files.push({ id, file: localName, size, sha256: asset.sha256, mime: asset.mime });
+        }
+        await installBuildInputs(opts, target, staging);
+        return { ok: true, sessionId, directory: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), byteCount: total, files };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
 export async function inspectArtifactApp(opts, input) {
     const appDir = stringArg(input, "appDir");
     const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
     await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
     const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
-    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
+    const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
     return {
         ok: true,
@@ -313,6 +483,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 +765,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 +808,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)
@@ -646,10 +948,19 @@ function shouldExclude(relative, isDirectory) {
         return true;
     if (parts.some((part) => part === ".git" || part === "node_modules"))
         return true;
+    if (parts.some(part => /(?:\.(?:pem|key|p12|pfx)|^\.?(?:credentials|netrc|npmrc|aws|ssh)$)/i.test(part)))
+        return true;
     if (isDirectory && FORBIDDEN_DIRS.has(name))
         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 +1009,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();
@@ -779,7 +1090,12 @@ const BUILD_MCP_TOOLS = [
                 description: { type: "string" },
                 projectId: { type: "string", format: "uuid" },
                 expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
-                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
+                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." },
+                sessionId: { type: "string", format: "uuid" },
+                artifactVersionId: { type: "string", format: "uuid", description: "Exact current version from the session or checkout; required with sessionId." },
+                idempotencyKey: { type: "string", minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" },
+                inspectedSourceHash: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Echo the session/source checkout hash; required with sessionId. expectedBundleSha256 separately pins the newly inspected local upload." },
+                platformAppDir: { type: "string", minLength: 1, description: "Saved remote app root from an existing-app checkout. Session mode only; preserve this when the local checkout directory has a different name." }
             },
             required: ["appDir"],
             additionalProperties: false
@@ -805,7 +1121,7 @@ const BUILD_MCP_TOOLS = [
         annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
         inputSchema: {
             type: "object",
-            properties: { appDir: { type: "string", minLength: 1 } },
+            properties: { appDir: { type: "string", minLength: 1 }, platformAppDir: { type: "string", minLength: 1, description: "Preserve the saved remote source root returned by checkout when inspecting an existing app." } },
             required: ["appDir"],
             additionalProperties: false
         },
@@ -940,6 +1256,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.",
@@ -997,7 +1375,8 @@ const BUILD_MCP_TOOLS = [
             properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
             required: ["ok", "deleted", "artifactId"]
         }
-    }
+    },
+    ...externalBuildHelperTools(mcpToolAnnotations)
 ].map(withRecoveryOutputSchema);
 export function listTools() {
     // Preserve the original tools/list isolation boundary: callers must not be

package/dist/source-checkout.d.ts

@@ -0,0 +1,10 @@
+export declare const MAX_SOURCE_ARCHIVE_BYTES: number;
+/** All path rules apply on every host, including Windows aliases and devices. */
+export declare function safeSourcePath(raw: string): string;
+/** Extract only regular files into a task-created empty staging directory. */
+export declare function extractArtifactSourceArchive(body: Buffer, stagingRoot: string): Promise<{
+    fileCount: number;
+    byteCount: number;
+    sha256: string;
+}>;
+export declare function boundedTransfer(response: Response, maxBytes: number, expectedSize?: number): Promise<Buffer>;