@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/CHANGELOG.md +13 -0
- package/README.md +10 -0
- package/dist/build-session-tools.d.ts +9 -0
- package/dist/build-session-tools.js +63 -0
- package/dist/domain-tools.d.ts +11 -0
- package/dist/domain-tools.js +53 -0
- package/dist/index.d.ts +32 -6
- package/dist/index.js +259 -14
- package/dist/source-checkout.d.ts +10 -0
- package/dist/source-checkout.js +146 -0
- package/docs/generated/build-mcp-manifest.json +2635 -7
- package/docs/generated/build-mcp-reference.md +2760 -2
- package/package.json +5 -2
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.
|
|
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 () =>
|
|
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
|
|
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
|
|
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
|
|
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
|
+
}
|