@topline-build/harness-mcp 0.5.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,11 +1,14 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
3
  import { existsSync } from "node:fs";
4
- import { mkdir, mkdtemp, readdir, readFile, realpath, lstat, writeFile, rm, rename } from "node:fs/promises";
4
+ import { cp, mkdir, mkdtemp, readdir, readFile, realpath, lstat, writeFile, rm, rename } from "node:fs/promises";
5
5
  import { createServer } from "node:http";
6
6
  import os from "node:os";
7
7
  import path from "node:path";
8
8
  import { gzipSync } from "node:zlib";
9
+ import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS } from "./build-session-tools.js";
10
+ import { domainHelperTools, DOMAIN_FORWARD_TOOLS, DOMAIN_ERROR_CODES } from "./domain-tools.js";
11
+ import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
9
12
  import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
10
13
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
11
14
  import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
@@ -13,7 +16,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
13
16
  export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
14
17
  const DEFAULT_TIMEOUT_MS = 120_000;
15
18
  export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
16
- export const HARNESS_MCP_VERSION = "0.5.3";
19
+ export const HARNESS_MCP_VERSION = "0.7.0";
17
20
  export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
18
21
  export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
19
22
  { 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." },
@@ -107,13 +110,46 @@ export function cliInfo(argv) {
107
110
  ].join("\n");
108
111
  }
109
112
  export function createHarnessMcpStdioServer(opts, toolAllowlist) {
113
+ let discoveredGrant = null;
114
+ const grantTag = (stored) => stored?.accessToken && Date.parse(stored.accessTokenExpiresAt ?? "") > Date.now()
115
+ ? JSON.stringify([stored.clientId, stored.resource, [...stored.scopes].sort()]) : null;
110
116
  const allowedTools = toolAllowlist ? new Set(toolAllowlist) : null;
111
117
  const listedTools = () => {
112
118
  const listed = listTools();
113
119
  return allowedTools ? { ...listed, tools: listed.tools.filter((tool) => allowedTools.has(tool.name)) } : listed;
114
120
  };
115
- const mcp = new McpServer({ name: BUILD_MCP_SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
116
- mcp.setRequestHandler(ListToolsRequestSchema, async () => listedTools());
121
+ const mcp = new McpServer({ name: BUILD_MCP_SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: { listChanged: true } } });
122
+ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
123
+ const listed = listedTools();
124
+ if (mcpSurface(opts) !== "build" || opts.token)
125
+ return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
126
+ // Public deployment metadata never initiates OAuth or changes consent.
127
+ // Unknown/old servers fail closed for this default-off family.
128
+ try {
129
+ const metadata = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, `${platformBaseUrl(opts)}/mcp/build`, { method: "GET" }));
130
+ const names = new Set(Array.isArray(metadata.tools) ? metadata.tools.map(item => typeof item === "string" ? item : asRecord(item).name) : []);
131
+ const stored = await readStoredOAuthCredentials(opts);
132
+ if (stored?.accessToken && Date.parse(stored.accessTokenExpiresAt ?? "") > Date.now()) {
133
+ const payload = asRecord(await fetchJson({ ...opts, timeoutMs: Math.min(opts.timeoutMs, 5000) }, `${platformBaseUrl(opts)}/mcp/build`, {
134
+ method: "POST", headers: { authorization: `Bearer ${stored.accessToken}`, "content-type": "application/json", accept: "application/json, text/event-stream" },
135
+ body: JSON.stringify({ jsonrpc: "2.0", id: "domain-discovery", method: "tools/list", params: {} }),
136
+ }));
137
+ const remote = asRecord(payload.result).tools;
138
+ if (!Array.isArray(remote))
139
+ throw new Error("domain_discovery_unavailable");
140
+ const contracts = new Map(remote.filter(isRecord).map(tool => [tool.name, tool]));
141
+ discoveredGrant = grantTag(stored);
142
+ return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || (names.has(tool.name) && contracts.has(tool.name)))
143
+ .map(tool => DOMAIN_FORWARD_TOOLS.has(tool.name) ? { ...tool, inputSchema: contracts.get(tool.name).inputSchema } : tool) };
144
+ }
145
+ return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name) || names.has(tool.name)).map(tool => tool.name === "platform_read_artifact_domains"
146
+ ? { ...tool, inputSchema: { type: "object", additionalProperties: false, properties: { limit: { type: "integer", minimum: 1, maximum: 100 }, cursor: { type: "integer", minimum: 0, maximum: 10000 } } } }
147
+ : tool) };
148
+ }
149
+ catch {
150
+ return { tools: listed.tools.filter(tool => !DOMAIN_FORWARD_TOOLS.has(tool.name)) };
151
+ }
152
+ });
117
153
  mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
118
154
  if (allowedTools && !allowedTools.has(req.params.name)) {
119
155
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`);
@@ -132,6 +168,17 @@ export function createHarnessMcpStdioServer(opts, toolAllowlist) {
132
168
  await sendProgress(extra, 1, 1, "Failed artifact deployment");
133
169
  return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
134
170
  }
171
+ finally {
172
+ if (mcpSurface(opts) === "build" && !opts.token) {
173
+ const currentGrant = grantTag(await readStoredOAuthCredentials(opts));
174
+ if (currentGrant !== discoveredGrant) {
175
+ discoveredGrant = currentGrant;
176
+ // First browser sign-in changes manager-only selector availability.
177
+ // Tell MCP hosts to rediscover before setup status/recovery calls.
178
+ await mcp.sendToolListChanged().catch(() => undefined);
179
+ }
180
+ }
181
+ }
135
182
  });
136
183
  return mcp;
137
184
  }
@@ -161,6 +208,12 @@ export async function callHarnessTool(opts, name, args, hooks) {
161
208
  case "platform_checkout_design_system":
162
209
  result = toolResult(await checkoutDesignSystem(opts, input));
163
210
  break;
211
+ case "platform_checkout_artifact_app":
212
+ result = toolResult(await checkoutArtifactApp(opts, input));
213
+ break;
214
+ case "platform_materialize_assets":
215
+ result = toolResult(await materializeBuildAssets(opts, input));
216
+ break;
164
217
  case "platform_submit_design_system_draft":
165
218
  result = toolResult(await submitDesignSystemDraft(opts, input));
166
219
  break;
@@ -189,6 +242,36 @@ export async function callHarnessTool(opts, name, args, hooks) {
189
242
  result = toolResult(await initArtifactApp(opts, input));
190
243
  break;
191
244
  default:
245
+ if (DOMAIN_FORWARD_TOOLS.has(name)) {
246
+ try {
247
+ if (mcpSurface(opts) !== "build" || opts.token)
248
+ throw new Error("domain_tools_require_build_oauth");
249
+ result = toolResult(await callHostedBuildTool(opts, name, input));
250
+ }
251
+ catch (error) {
252
+ const message = error instanceof Error ? error.message : "";
253
+ const code = /^platform_harness_http_error:401(?::|$)/.test(message) ? "authorization_required"
254
+ : [...DOMAIN_ERROR_CODES].find(candidate => new RegExp(`(?:^|[^a-z_])${candidate}(?:$|[^a-z_])`).test(message)) ?? "domain_result_unknown";
255
+ result = structuredToolError(code);
256
+ const key = typeof input.idempotencyKey === "string" ? input.idempotencyKey : undefined;
257
+ const recovery = key && name === "platform_apply_artifact_address"
258
+ ? { tool: "platform_get_artifact_address", planId: input.planId, artifactIdRequiredFromSavedPlan: true, selector: { idempotencyKey: key } }
259
+ : key && ["platform_request_artifact_domain", "platform_verify_artifact_domain"].includes(name)
260
+ ? { tool: "platform_read_artifact_domains", arguments: { recovery: { kind: name === "platform_request_artifact_domain" ? "request" : "verify", idempotencyKey: key } }, domainId: input.domainId }
261
+ : undefined;
262
+ if (recovery) {
263
+ result.structuredContent.error.recovery = recovery;
264
+ result.content = [{ type: "text", text: JSON.stringify(result.structuredContent, null, 2) }];
265
+ }
266
+ }
267
+ break;
268
+ }
269
+ if (EXTERNAL_BUILD_FORWARD_TOOLS.has(name)) {
270
+ if (mcpSurface(opts) !== "build")
271
+ throw new Error("external_session_requires_build_surface");
272
+ result = toolResult(await callHostedBuildTool(opts, name, input));
273
+ break;
274
+ }
192
275
  throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
193
276
  }
194
277
  const outputError = tool.outputSchema
@@ -203,7 +286,8 @@ export async function deployArtifactApp(opts, input, onProgress) {
203
286
  await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
204
287
  const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
205
288
  const manifest = await readManifest(absoluteAppDir);
206
- const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
289
+ const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
290
+ const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
207
291
  const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
208
292
  .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
209
293
  .digest("hex");
@@ -213,18 +297,39 @@ export async function deployArtifactApp(opts, input, onProgress) {
213
297
  if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
214
298
  throw new Error("artifact_app_bundle_changed_after_inspection");
215
299
  }
300
+ const sessionId = optionalString(input, "sessionId");
301
+ const sessionVersion = optionalString(input, "artifactVersionId");
302
+ const idempotencyKey = optionalString(input, "idempotencyKey");
303
+ const inspectedSourceHash = optionalString(input, "inspectedSourceHash");
304
+ let sessionArtifactId;
305
+ if (sessionId) {
306
+ if (mcpSurface(opts) !== "build")
307
+ throw new Error("external_session_requires_build_surface");
308
+ if (!sessionVersion || !idempotencyKey || !inspectedSourceHash || !expectedBundleSha256)
309
+ throw new Error("build_session_deployment_arguments_required");
310
+ const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
311
+ // The server resolves a repeated operation key before checking current
312
+ // version/source. Do not reject a lost-response retry using the newer read.
313
+ // Fresh mutations still require the caller's exact inspected revision.
314
+ sessionArtifactId = stringValue(session.artifactId, "artifactId");
315
+ if (input.artifactId !== undefined && input.artifactId !== sessionArtifactId)
316
+ throw new Error("build_session_artifact_mismatch");
317
+ }
318
+ else if (sessionVersion || idempotencyKey || inspectedSourceHash || suppliedPlatformAppDir)
319
+ throw new Error("build_session_id_required");
216
320
  await onProgress?.(0.4, "Creating private artifact draft");
217
321
  const created = await fetchJson(opts, artifactAppsPath(opts), {
218
322
  method: "POST",
219
323
  headers: await jsonHeaders(opts),
220
324
  body: JSON.stringify({
221
- artifactId: optionalString(input, "artifactId"),
325
+ artifactId: sessionArtifactId ?? optionalString(input, "artifactId"),
222
326
  title: optionalString(input, "title"),
223
327
  description: optionalString(input, "description"),
224
328
  projectId: optionalString(input, "projectId"),
225
329
  clientRequestId,
226
330
  bundleSha256: bundle.sha256,
227
- manifest
331
+ manifest,
332
+ ...(sessionId ? { sessionId, artifactVersionId: sessionVersion, idempotencyKey, inspectedSourceHash } : {})
228
333
  })
229
334
  });
230
335
  const createdRecord = asRecord(created);
@@ -241,19 +346,22 @@ export async function deployArtifactApp(opts, input, onProgress) {
241
346
  "content-type": "application/gzip",
242
347
  "MCP-Protocol-Version": opts.protocolVersion,
243
348
  "x-platform-artifact-version-id": artifactVersionId,
244
- "x-platform-app-dir": platformAppDir
349
+ "x-platform-app-dir": platformAppDir,
350
+ ...(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 } : {})
245
351
  },
246
352
  body: bundle.body
247
353
  });
248
354
  await onProgress?.(1, "Completed trusted draft deployment");
249
355
  const deployedRecord = asRecord(deployed);
250
- const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
356
+ const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId
357
+ : typeof deployedRecord.operationId === "string" ? deployedRecord.operationId : null;
251
358
  return {
252
359
  ok: true,
253
360
  artifactId,
254
361
  artifactVersionId,
255
362
  manifestId: typeof manifest.id === "string" ? manifest.id : null,
256
363
  clientRequestId,
364
+ ...(sessionId ? { sessionId } : {}),
257
365
  operationId,
258
366
  bundle: {
259
367
  fileCount: bundle.fileCount,
@@ -265,13 +373,135 @@ export async function deployArtifactApp(opts, input, onProgress) {
265
373
  deploy: deployed
266
374
  };
267
375
  }
376
+ async function fetchBuildTransfer(opts, advertisedPath, expectedPath, sha256, maxBytes, expectedSize, revision) {
377
+ if (advertisedPath !== expectedPath || typeof sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(sha256))
378
+ throw new Error("build_transfer_identity_invalid");
379
+ const base = new URL(platformBaseUrl(opts));
380
+ const url = new URL(expectedPath, base);
381
+ if (url.origin !== base.origin || url.pathname !== expectedPath || url.search || url.hash)
382
+ throw new Error("build_transfer_identity_invalid");
383
+ const controller = new AbortController();
384
+ const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
385
+ try {
386
+ const response = await (opts.fetchImpl ?? fetch)(url.href, { method: "GET", headers: await jsonHeaders(opts), redirect: "error", signal: controller.signal });
387
+ if (!response.ok || (response.url && new URL(response.url).origin !== base.origin))
388
+ throw new Error("build_transfer_unavailable");
389
+ if (response.headers.get("x-topline-content-sha256")?.toLowerCase() !== sha256.toLowerCase())
390
+ throw new Error("build_transfer_hash_mismatch");
391
+ if (revision && (response.headers.get("x-topline-artifact-version") !== revision.artifactVersionId || response.headers.get("x-topline-source-commit") !== revision.commitSha))
392
+ throw new Error("build_transfer_revision_mismatch");
393
+ const body = await boundedTransfer(response, maxBytes, expectedSize);
394
+ if (createHash("sha256").update(body).digest("hex") !== sha256.toLowerCase())
395
+ throw new Error("build_transfer_hash_mismatch");
396
+ return body;
397
+ }
398
+ catch (error) {
399
+ if (controller.signal.aborted)
400
+ throw new Error("platform_harness_timeout");
401
+ throw error;
402
+ }
403
+ finally {
404
+ clearTimeout(timer);
405
+ }
406
+ }
407
+ async function newBuildInputTarget(opts, input) {
408
+ if (mcpSurface(opts) !== "build")
409
+ throw new Error("external_session_requires_build_surface");
410
+ const target = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
411
+ if (existsSync(target))
412
+ throw new Error("build_input_target_exists");
413
+ await assertAuthFileOutsideAppDir(opts.authFile, target);
414
+ await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
415
+ const checked = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
416
+ if (checked !== target)
417
+ throw new Error("build_input_target_changed");
418
+ return target;
419
+ }
420
+ async function installBuildInputs(opts, target, stage) {
421
+ // Reserve the new target exclusively; never rename over a directory another
422
+ // process created. cp refuses existing files rather than overwriting them.
423
+ await resolveWorkspacePathSafely(opts.workspaceRoot, path.relative(opts.workspaceRoot, target));
424
+ await mkdir(target, { mode: 0o700 });
425
+ try {
426
+ for (const entry of await readdir(stage))
427
+ await cp(path.join(stage, entry), path.join(target, entry), { recursive: true, force: false, errorOnExist: true });
428
+ }
429
+ catch (error) {
430
+ await rm(target, { recursive: true, force: true });
431
+ throw error;
432
+ }
433
+ }
434
+ export async function checkoutArtifactApp(opts, input) {
435
+ const target = await newBuildInputTarget(opts, input);
436
+ const sessionId = stringArg(input, "sessionId");
437
+ const metadata = asRecord(await callHostedBuildTool(opts, "platform_checkout_artifact_app", { sessionId }));
438
+ const artifactVersionId = stringValue(metadata.artifactVersionId, "artifactVersionId");
439
+ const commitSha = stringValue(metadata.commitSha, "commitSha");
440
+ if (!/^[a-f0-9]{40}$/.test(commitSha) || !/^[0-9a-f-]{36}$/i.test(artifactVersionId))
441
+ throw new Error("build_transfer_revision_invalid");
442
+ const body = await fetchBuildTransfer(opts, metadata.downloadPath, `/api/harness/build-sessions/${sessionId}/source`, metadata.sha256, MAX_SOURCE_ARCHIVE_BYTES, undefined, { artifactVersionId, commitSha });
443
+ const staging = await mkdtemp(path.join(path.dirname(target), ".topline-app-checkout-"));
444
+ try {
445
+ const source = path.join(staging, "source");
446
+ await mkdir(source, { mode: 0o700 });
447
+ const extracted = await extractArtifactSourceArchive(body, source);
448
+ if (extracted.fileCount !== metadata.fileCount || extracted.byteCount !== metadata.byteCount)
449
+ throw new Error("artifact_source_shape_mismatch");
450
+ await readManifest(source);
451
+ await installBuildInputs(opts, target, source);
452
+ return { ok: true, sessionId, artifactId: metadata.artifactId, artifactVersionId, commitSha, sourceHash: extracted.sha256,
453
+ appDir: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), platformAppDir: metadata.appDir,
454
+ fileCount: extracted.fileCount, byteCount: extracted.byteCount };
455
+ }
456
+ finally {
457
+ await rm(staging, { recursive: true, force: true });
458
+ }
459
+ }
460
+ export async function materializeBuildAssets(opts, input) {
461
+ const target = await newBuildInputTarget(opts, input);
462
+ const sessionId = stringArg(input, "sessionId");
463
+ const assetIds = input.assetIds;
464
+ if (!Array.isArray(assetIds) || !assetIds.length || assetIds.length > 50 || assetIds.some(id => typeof id !== "string" || !/^[0-9a-f-]{36}$/i.test(id)))
465
+ throw new Error("asset_selection_required");
466
+ const selected = new Set(assetIds);
467
+ const metadata = asRecord(await callHostedBuildTool(opts, "platform_materialize_assets", { sessionId, assetIds }));
468
+ if (!Array.isArray(metadata.assets) || metadata.assets.length !== selected.size)
469
+ throw new Error("asset_transfer_identity_invalid");
470
+ const assets = metadata.assets.map(asRecord);
471
+ if (assets.some(asset => typeof asset.id !== "string" || !selected.delete(asset.id)) || selected.size)
472
+ throw new Error("asset_transfer_identity_invalid");
473
+ const staging = await mkdtemp(path.join(path.dirname(target), ".topline-assets-"));
474
+ let total = 0;
475
+ try {
476
+ const files = [];
477
+ for (const asset of assets) {
478
+ const size = asset.size;
479
+ if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 16 * 1024 * 1024 || (total += size) > 64 * 1024 * 1024)
480
+ throw new Error("asset_transfer_too_large");
481
+ const name = stringValue(asset.name, "name");
482
+ if (Buffer.byteLength(name, "utf8") > 200 || name.includes("/") || safeSourcePath(name) !== name)
483
+ throw new Error("asset_transfer_name_invalid");
484
+ const id = stringValue(asset.id, "id");
485
+ const body = await fetchBuildTransfer(opts, asset.downloadPath, `/api/harness/build-sessions/${sessionId}/assets/${id}`, asset.sha256, 16 * 1024 * 1024, size);
486
+ const localName = `${id}-${name}`;
487
+ await writeFile(path.join(staging, localName), body, { mode: 0o600, flag: "wx" });
488
+ files.push({ id, file: localName, size, sha256: asset.sha256, mime: asset.mime });
489
+ }
490
+ await installBuildInputs(opts, target, staging);
491
+ return { ok: true, sessionId, directory: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), byteCount: total, files };
492
+ }
493
+ finally {
494
+ await rm(staging, { recursive: true, force: true });
495
+ }
496
+ }
268
497
  export async function inspectArtifactApp(opts, input) {
269
498
  const appDir = stringArg(input, "appDir");
270
499
  const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
271
500
  await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
272
501
  const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
273
502
  const manifest = await readManifest(absoluteAppDir);
274
- const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
503
+ const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
504
+ const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
275
505
  const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
276
506
  return {
277
507
  ok: true,
@@ -787,6 +1017,8 @@ function shouldExclude(relative, isDirectory) {
787
1017
  return true;
788
1018
  if (parts.some((part) => part === ".git" || part === "node_modules"))
789
1019
  return true;
1020
+ if (parts.some(part => /(?:\.(?:pem|key|p12|pfx)|^\.?(?:credentials|netrc|npmrc|aws|ssh)$)/i.test(part)))
1021
+ return true;
790
1022
  if (isDirectory && FORBIDDEN_DIRS.has(name))
791
1023
  return true;
792
1024
  return false;
@@ -927,7 +1159,12 @@ const BUILD_MCP_TOOLS = [
927
1159
  description: { type: "string" },
928
1160
  projectId: { type: "string", format: "uuid" },
929
1161
  expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
930
- requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
1162
+ requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." },
1163
+ sessionId: { type: "string", format: "uuid" },
1164
+ artifactVersionId: { type: "string", format: "uuid", description: "Exact current version from the session or checkout; required with sessionId." },
1165
+ idempotencyKey: { type: "string", minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" },
1166
+ 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." },
1167
+ 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." }
931
1168
  },
932
1169
  required: ["appDir"],
933
1170
  additionalProperties: false
@@ -953,7 +1190,7 @@ const BUILD_MCP_TOOLS = [
953
1190
  annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
954
1191
  inputSchema: {
955
1192
  type: "object",
956
- properties: { appDir: { type: "string", minLength: 1 } },
1193
+ 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." } },
957
1194
  required: ["appDir"],
958
1195
  additionalProperties: false
959
1196
  },
@@ -1207,7 +1444,9 @@ const BUILD_MCP_TOOLS = [
1207
1444
  properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
1208
1445
  required: ["ok", "deleted", "artifactId"]
1209
1446
  }
1210
- }
1447
+ },
1448
+ ...externalBuildHelperTools(mcpToolAnnotations),
1449
+ ...domainHelperTools(mcpToolAnnotations)
1211
1450
  ].map(withRecoveryOutputSchema);
1212
1451
  export function listTools() {
1213
1452
  // Preserve the original tools/list isolation boundary: callers must not be
@@ -1234,7 +1473,8 @@ function withRecoveryOutputSchema(value) {
1234
1473
  code: { type: "string" },
1235
1474
  message: { type: "string" },
1236
1475
  retryable: { type: "boolean" },
1237
- recoveryAction: { type: "string" }
1476
+ recoveryAction: { type: "string" },
1477
+ ...(DOMAIN_FORWARD_TOOLS.has(tool.name) ? { recovery: { type: "object", additionalProperties: true } } : {})
1238
1478
  },
1239
1479
  required: ["code", "message", "retryable", "recoveryAction"],
1240
1480
  additionalProperties: false
@@ -1273,6 +1513,9 @@ function toolError(message) {
1273
1513
  return structuredToolError(message);
1274
1514
  }
1275
1515
  const BUILD_MCP_RECOVERY_ERROR_VALUES = {
1516
+ ...Object.fromEntries([...DOMAIN_ERROR_CODES].map(code => [code, { retryable: false,
1517
+ recoveryAction: "Read current domain/address state and the original receipt with the saved pre-call key. Retain the exact original input. Review changed state, scopes or configuration before any new plan/key; never assume a rejected delivery means no effect." }])),
1518
+ domain_result_unknown: { retryable: false, recoveryAction: "The response did not establish an outcome. Recover the original receipt through platform_get_artifact_address (saved artifactId and apply key) or platform_read_artifact_domains (request/verify kind and key). Preserve the original plan/domain/input/key; an absent, pending or expired receipt does not authorize a fresh key. No mutation is replayed automatically." },
1276
1519
  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." },
1277
1520
  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." },
1278
1521
  platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
@@ -1300,6 +1543,8 @@ function structuredToolError(message) {
1300
1543
  function recoveryErrorCode(message) {
1301
1544
  if (/^platform_harness_http_error:401(?::|$)/.test(message))
1302
1545
  return "authorization_required";
1546
+ if (DOMAIN_ERROR_CODES.has(message) || message === "domain_result_unknown")
1547
+ return message;
1303
1548
  const known = [
1304
1549
  "artifact_delete_plan_stale",
1305
1550
  "artifact_deploy_wait_timeout",
@@ -0,0 +1,10 @@
1
+ export declare const MAX_SOURCE_ARCHIVE_BYTES: number;
2
+ /** All path rules apply on every host, including Windows aliases and devices. */
3
+ export declare function safeSourcePath(raw: string): string;
4
+ /** Extract only regular files into a task-created empty staging directory. */
5
+ export declare function extractArtifactSourceArchive(body: Buffer, stagingRoot: string): Promise<{
6
+ fileCount: number;
7
+ byteCount: number;
8
+ sha256: string;
9
+ }>;
10
+ export declare function boundedTransfer(response: Response, maxBytes: number, expectedSize?: number): Promise<Buffer>;
@@ -0,0 +1,146 @@
1
+ import { createHash } from "node:crypto";
2
+ import { mkdir, writeFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { gunzipSync } from "node:zlib";
5
+ export const MAX_SOURCE_ARCHIVE_BYTES = 64 * 1024 * 1024;
6
+ const MAX_CONTENT_BYTES = 512 * 1024 * 1024;
7
+ const MAX_FILES = 25_000;
8
+ const BLOCK = 512;
9
+ const forbiddenDirs = new Set([".git", "node_modules", ".next", ".vite", ".turbo", ".cache", "dist", "build", "coverage"]);
10
+ /** All path rules apply on every host, including Windows aliases and devices. */
11
+ export function safeSourcePath(raw) {
12
+ if (!raw || raw.startsWith("/") || raw.includes("\\"))
13
+ throw new Error("artifact_source_path_invalid");
14
+ const segments = raw.replace(/^\.\//, "").split("/");
15
+ if (segments.at(-1) === "")
16
+ segments.pop();
17
+ if (!segments.length || segments.length > 64 || segments.some(part => !part || part === "." || part === ".." || /[\u0000-\u001f\u007f:]/u.test(part) || /[. ]$/.test(part) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)))
18
+ throw new Error("artifact_source_path_invalid");
19
+ if (segments.some(part => forbiddenDirs.has(part.toLowerCase()) || part.toLowerCase().startsWith(".env") || /(?:\.(?:pem|key|p12|pfx)|^\.?(?:credentials|netrc|npmrc|aws|ssh)$)/i.test(part)))
20
+ throw new Error("artifact_source_credential_or_cache_forbidden");
21
+ return segments.join("/");
22
+ }
23
+ function text(header, offset, length) {
24
+ const field = header.subarray(offset, offset + length);
25
+ const nul = field.indexOf(0);
26
+ return field.subarray(0, nul < 0 ? field.length : nul).toString("utf8");
27
+ }
28
+ function octal(header, offset, length) {
29
+ const value = text(header, offset, length).trim();
30
+ if (!/^[0-7]+$/.test(value))
31
+ throw new Error("artifact_source_tar_invalid");
32
+ const number = Number.parseInt(value, 8);
33
+ if (!Number.isSafeInteger(number) || number < 0)
34
+ throw new Error("artifact_source_tar_invalid");
35
+ return number;
36
+ }
37
+ /** Extract only regular files into a task-created empty staging directory. */
38
+ export async function extractArtifactSourceArchive(body, stagingRoot) {
39
+ if (!body.length || body.length > MAX_SOURCE_ARCHIVE_BYTES)
40
+ throw new Error("artifact_source_transfer_too_large");
41
+ let tar;
42
+ try {
43
+ tar = gunzipSync(body, { maxOutputLength: MAX_CONTENT_BYTES + MAX_FILES * 1024 });
44
+ }
45
+ catch {
46
+ throw new Error("artifact_source_archive_invalid");
47
+ }
48
+ let position = 0;
49
+ let fileCount = 0;
50
+ let byteCount = 0;
51
+ let ended = false;
52
+ let entryCount = 0;
53
+ const files = new Set();
54
+ const dirs = new Set();
55
+ const paths = new Map();
56
+ while (position + BLOCK <= tar.length) {
57
+ const header = tar.subarray(position, position + BLOCK);
58
+ position += BLOCK;
59
+ if (header.every(byte => byte === 0)) {
60
+ if (position + BLOCK > tar.length || !tar.subarray(position).every(byte => byte === 0))
61
+ throw new Error("artifact_source_tar_invalid");
62
+ ended = true;
63
+ break;
64
+ }
65
+ if (++entryCount > MAX_FILES * 2)
66
+ throw new Error("artifact_source_unpacked_too_large");
67
+ const expectedChecksum = octal(header, 148, 8);
68
+ const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
69
+ if (checksum !== expectedChecksum || text(header, 257, 6) !== "ustar")
70
+ throw new Error("artifact_source_tar_invalid");
71
+ const prefix = text(header, 345, 155);
72
+ const rawName = `${prefix ? prefix + "/" : ""}${text(header, 0, 100)}`;
73
+ const size = octal(header, 124, 12);
74
+ const padded = Math.ceil(size / BLOCK) * BLOCK;
75
+ if (position + padded > tar.length)
76
+ throw new Error("artifact_source_tar_invalid");
77
+ const kind = String.fromCharCode(header[156]);
78
+ if ((rawName === "." || rawName === "./") && kind === "5" && size === 0)
79
+ continue;
80
+ const relative = safeSourcePath(rawName);
81
+ const key = relative.toLowerCase();
82
+ const segments = relative.split("/");
83
+ for (let length = 1; length <= segments.length; length++) {
84
+ const actual = segments.slice(0, length).join("/");
85
+ const canonical = actual.toLowerCase();
86
+ if (paths.has(canonical) && paths.get(canonical) !== actual)
87
+ throw new Error("artifact_source_duplicate_path");
88
+ paths.set(canonical, actual);
89
+ }
90
+ if (paths.size > MAX_FILES * 2)
91
+ throw new Error("artifact_source_unpacked_too_large");
92
+ if (kind !== "0" && kind !== "\0" && kind !== "5")
93
+ throw new Error("artifact_source_entry_type_forbidden");
94
+ if (files.has(key) || dirs.has(key))
95
+ throw new Error("artifact_source_duplicate_path");
96
+ const ancestors = key.split("/").slice(0, -1);
97
+ if (ancestors.some((_, index) => files.has(ancestors.slice(0, index + 1).join("/"))))
98
+ throw new Error("artifact_source_duplicate_path");
99
+ const output = path.resolve(stagingRoot, relative);
100
+ const diff = path.relative(stagingRoot, output);
101
+ if (diff === ".." || diff.startsWith(`..${path.sep}`) || path.isAbsolute(diff))
102
+ throw new Error("artifact_source_path_invalid");
103
+ if (kind === "5") {
104
+ if (size !== 0)
105
+ throw new Error("artifact_source_tar_invalid");
106
+ dirs.add(key);
107
+ await mkdir(output, { recursive: true, mode: 0o700 });
108
+ }
109
+ else {
110
+ if (++fileCount > MAX_FILES || (byteCount += size) > MAX_CONTENT_BYTES)
111
+ throw new Error("artifact_source_unpacked_too_large");
112
+ files.add(key);
113
+ await mkdir(path.dirname(output), { recursive: true, mode: 0o700 });
114
+ await writeFile(output, tar.subarray(position, position + size), { flag: "wx", mode: 0o600 });
115
+ }
116
+ position += padded;
117
+ }
118
+ if (!ended || !fileCount)
119
+ throw new Error("artifact_source_archive_invalid");
120
+ return { fileCount, byteCount, sha256: createHash("sha256").update(body).digest("hex") };
121
+ }
122
+ export async function boundedTransfer(response, maxBytes, expectedSize) {
123
+ const rawLength = response.headers.get("content-length");
124
+ const declared = rawLength === null ? null : Number(rawLength);
125
+ if (declared !== null && (!Number.isSafeInteger(declared) || declared < 0 || declared > maxBytes || (expectedSize !== undefined && declared !== expectedSize)))
126
+ throw new Error("build_transfer_size_invalid");
127
+ if (!response.body)
128
+ throw new Error("build_transfer_size_invalid");
129
+ const chunks = [];
130
+ let total = 0;
131
+ const reader = response.body.getReader();
132
+ for (;;) {
133
+ const part = await reader.read();
134
+ if (part.done)
135
+ break;
136
+ total += part.value.byteLength;
137
+ if (total > maxBytes) {
138
+ await reader.cancel().catch(() => undefined);
139
+ throw new Error("build_transfer_size_invalid");
140
+ }
141
+ chunks.push(Buffer.from(part.value));
142
+ }
143
+ if ((!total && expectedSize !== 0) || (declared !== null && total !== declared) || (expectedSize !== undefined && total !== expectedSize))
144
+ throw new Error("build_transfer_size_invalid");
145
+ return Buffer.concat(chunks);
146
+ }