@topline-build/harness-mcp 0.9.14 → 0.9.15
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 +6 -0
- package/dist/index.d.ts +22 -1
- package/dist/index.js +116 -6
- package/docs/generated/build-mcp-manifest.json +437 -7
- package/docs/generated/build-mcp-reference.md +426 -5
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,12 @@
|
|
|
2
2
|
|
|
3
3
|
All notable customer-visible Build MCP changes are recorded here. A source change is not a published package or customer release.
|
|
4
4
|
|
|
5
|
+
## 0.9.15 - 2026-11-11
|
|
6
|
+
|
|
7
|
+
- `platform_inspect_artifact_app` runs `node --check` on each `.js`, `.mjs` and `.cjs` source file, so a syntax error makes `packageReady` false with a `javascript_syntax_error` problem naming the file and line, instead of failing the build after deploy.
|
|
8
|
+
- Inspect also returns `warnings` for static page text that Topline's render smoke would refuse as sample or mock data (`rendered_text_rule:sample_or_mock_data_text`), with the file and the phrase.
|
|
9
|
+
- A source conflict error carries `currentSourceHash`, and a pending-operation error carries this session's `pendingOperationId` and `pendingKind`, when Topline sends them. `artifact_operation_pending` is marked retryable once the operation settles.
|
|
10
|
+
|
|
5
11
|
## 0.9.14 - 2026-11-11
|
|
6
12
|
|
|
7
13
|
- `platform_wait_artifact_deploy` names the build's failure code (`artifact_deploy_failed:<code>`) instead of only `failed`, and its recovery says to read `platform_deploy_operation` for the build's own error instead of retrying the wait.
|
package/dist/index.d.ts
CHANGED
|
@@ -42,7 +42,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
|
|
|
42
42
|
export type McpSurface = "build" | "topline" | "harness";
|
|
43
43
|
export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
44
44
|
export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
45
|
-
export declare const HARNESS_MCP_VERSION = "0.9.
|
|
45
|
+
export declare const HARNESS_MCP_VERSION = "0.9.15";
|
|
46
46
|
export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
|
|
47
47
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
48
48
|
export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
|
|
@@ -136,6 +136,12 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
|
|
|
136
136
|
path: string;
|
|
137
137
|
detail: string;
|
|
138
138
|
}[];
|
|
139
|
+
warnings: {
|
|
140
|
+
code: string;
|
|
141
|
+
path: string;
|
|
142
|
+
phrase: string;
|
|
143
|
+
detail: string;
|
|
144
|
+
}[];
|
|
139
145
|
serverManifestValidationRequired: boolean;
|
|
140
146
|
appDir: string;
|
|
141
147
|
platformAppDir: string;
|
|
@@ -168,6 +174,21 @@ export declare function localPreflightProblems(appDir: string, manifest: Record<
|
|
|
168
174
|
path: string;
|
|
169
175
|
detail: string;
|
|
170
176
|
}>>;
|
|
177
|
+
/**
|
|
178
|
+
* Round 12: a JavaScript syntax error passed inspect (packageReady true) and then failed the
|
|
179
|
+
* build. Check each source file the way the build's Node would, and name the file and line.
|
|
180
|
+
*/
|
|
181
|
+
export declare function javascriptSyntaxProblems(appDir: string): Promise<Array<{
|
|
182
|
+
code: string;
|
|
183
|
+
path: string;
|
|
184
|
+
detail: string;
|
|
185
|
+
}>>;
|
|
186
|
+
export declare function renderedTextRuleWarnings(appDir: string): Promise<Array<{
|
|
187
|
+
code: string;
|
|
188
|
+
path: string;
|
|
189
|
+
phrase: string;
|
|
190
|
+
detail: string;
|
|
191
|
+
}>>;
|
|
171
192
|
export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
|
|
172
193
|
export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
|
|
173
194
|
ok: boolean;
|
package/dist/index.js
CHANGED
|
@@ -19,7 +19,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
|
|
|
19
19
|
export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
20
20
|
const DEFAULT_TIMEOUT_MS = 120_000;
|
|
21
21
|
export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
22
|
-
export const HARNESS_MCP_VERSION = "0.9.
|
|
22
|
+
export const HARNESS_MCP_VERSION = "0.9.15";
|
|
23
23
|
export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
|
|
24
24
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
25
25
|
export const TOPLINE_OAUTH_SCOPES = Object.freeze([
|
|
@@ -1154,10 +1154,13 @@ export async function inspectArtifactApp(opts, input) {
|
|
|
1154
1154
|
const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
|
|
1155
1155
|
const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
|
|
1156
1156
|
const problems = await localPreflightProblems(absoluteAppDir, manifest);
|
|
1157
|
+
problems.push(...await javascriptSyntaxProblems(absoluteAppDir));
|
|
1158
|
+
const warnings = await renderedTextRuleWarnings(absoluteAppDir);
|
|
1157
1159
|
return {
|
|
1158
1160
|
ok: true,
|
|
1159
1161
|
packageReady: problems.length === 0,
|
|
1160
1162
|
problems,
|
|
1163
|
+
warnings,
|
|
1161
1164
|
serverManifestValidationRequired: true,
|
|
1162
1165
|
appDir: workspaceAppDir,
|
|
1163
1166
|
platformAppDir,
|
|
@@ -1243,6 +1246,87 @@ export async function localPreflightProblems(appDir, manifest) {
|
|
|
1243
1246
|
await visit(appDir);
|
|
1244
1247
|
return problems.slice(0, 25);
|
|
1245
1248
|
}
|
|
1249
|
+
const SYNTAX_CHECK_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
|
|
1250
|
+
const SYNTAX_CHECK_SKIP_DIRS = new Set([...PREFLIGHT_SKIP_DIRS, "dist", "build", "out", "vendor"]);
|
|
1251
|
+
async function listAppFiles(appDir, extensions, skipDirs, limit) {
|
|
1252
|
+
const out = [];
|
|
1253
|
+
const visit = async (dir) => {
|
|
1254
|
+
for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
|
|
1255
|
+
if (out.length >= limit)
|
|
1256
|
+
return;
|
|
1257
|
+
const full = path.join(dir, entry.name);
|
|
1258
|
+
if (entry.isDirectory()) {
|
|
1259
|
+
if (!skipDirs.has(entry.name))
|
|
1260
|
+
await visit(full);
|
|
1261
|
+
continue;
|
|
1262
|
+
}
|
|
1263
|
+
if (entry.isFile() && extensions.has(path.extname(entry.name)))
|
|
1264
|
+
out.push(full);
|
|
1265
|
+
}
|
|
1266
|
+
};
|
|
1267
|
+
await visit(appDir);
|
|
1268
|
+
return out;
|
|
1269
|
+
}
|
|
1270
|
+
function nodeCheck(file) {
|
|
1271
|
+
return new Promise((resolve) => {
|
|
1272
|
+
const child = spawn(process.execPath, ["--check", file], { stdio: ["ignore", "ignore", "pipe"] });
|
|
1273
|
+
let stderr = "";
|
|
1274
|
+
child.stderr?.on("data", (chunk) => { if (stderr.length < 4_000)
|
|
1275
|
+
stderr += String(chunk); });
|
|
1276
|
+
const timer = setTimeout(() => { child.kill(); resolve(null); }, 10_000);
|
|
1277
|
+
child.on("error", () => { clearTimeout(timer); resolve(null); });
|
|
1278
|
+
child.on("close", (code) => { clearTimeout(timer); resolve(code === 0 ? null : stderr); });
|
|
1279
|
+
});
|
|
1280
|
+
}
|
|
1281
|
+
/**
|
|
1282
|
+
* Round 12: a JavaScript syntax error passed inspect (packageReady true) and then failed the
|
|
1283
|
+
* build. Check each source file the way the build's Node would, and name the file and line.
|
|
1284
|
+
*/
|
|
1285
|
+
export async function javascriptSyntaxProblems(appDir) {
|
|
1286
|
+
const problems = [];
|
|
1287
|
+
for (const file of await listAppFiles(appDir, SYNTAX_CHECK_EXTENSIONS, SYNTAX_CHECK_SKIP_DIRS, 200)) {
|
|
1288
|
+
const stderr = await nodeCheck(file);
|
|
1289
|
+
if (!stderr || !/SyntaxError/.test(stderr))
|
|
1290
|
+
continue;
|
|
1291
|
+
const rel = path.relative(appDir, file).replaceAll("\\", "/");
|
|
1292
|
+
const line = new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(\\d+)`).exec(stderr)?.[1] ?? null;
|
|
1293
|
+
const message = /SyntaxError:[^\n]*/.exec(stderr)?.[0]?.slice(0, 200) ?? "SyntaxError";
|
|
1294
|
+
problems.push({ code: "javascript_syntax_error", path: line ? `${rel}:${line}` : rel, detail: `${rel}${line ? ` line ${line}` : ""}: ${message}` });
|
|
1295
|
+
if (problems.length >= 10)
|
|
1296
|
+
break;
|
|
1297
|
+
}
|
|
1298
|
+
return problems;
|
|
1299
|
+
}
|
|
1300
|
+
// The page-text rule the build's render smoke applies (sample_or_mock_data_text). Inspect can only
|
|
1301
|
+
// see static text, so a match is a warning: the build fails only if the rendered page shows it.
|
|
1302
|
+
const SAMPLE_DATA_TEXT_PATTERNS = [
|
|
1303
|
+
/\b(showing|using|displaying|rendering|loaded|fallback|placeholder)\s+(sample|demo|mock|placeholder|example)?\s*(data|dataset|rows|metrics|values)\b/i,
|
|
1304
|
+
/\b(sample|demo|mock|placeholder|example)\s+(data|dataset|rows|metrics|values)\b/i,
|
|
1305
|
+
/\b(template[-\s]?local|local[-\s]?(summary|tasks|events|rows|metrics|dataset))\b/i
|
|
1306
|
+
];
|
|
1307
|
+
export async function renderedTextRuleWarnings(appDir) {
|
|
1308
|
+
const warnings = [];
|
|
1309
|
+
for (const file of await listAppFiles(appDir, new Set([".html", ".js", ".jsx", ".ts", ".tsx", ".mjs"]), SYNTAX_CHECK_SKIP_DIRS, 500)) {
|
|
1310
|
+
const content = await readFile(file, "utf8").catch(() => "");
|
|
1311
|
+
if (content.length > 2_000_000)
|
|
1312
|
+
continue;
|
|
1313
|
+
// Visible text only: HTML text between tags and quoted string literals, not identifiers or comments.
|
|
1314
|
+
const texts = [...content.matchAll(/>([^<>]{3,400})</g), ...content.matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.){3,400})\1/g)].map((m) => m[m.length - 1] ?? "");
|
|
1315
|
+
for (const text of texts) {
|
|
1316
|
+
const match = SAMPLE_DATA_TEXT_PATTERNS.map((pattern) => pattern.exec(text)).find(Boolean);
|
|
1317
|
+
if (!match)
|
|
1318
|
+
continue;
|
|
1319
|
+
const rel = path.relative(appDir, file).replaceAll("\\", "/");
|
|
1320
|
+
const phrase = match[0].slice(0, 80);
|
|
1321
|
+
warnings.push({ code: "rendered_text_rule:sample_or_mock_data_text", path: rel, phrase,
|
|
1322
|
+
detail: `${rel} contains "${phrase}". If the page shows this text, Topline's build refuses it as sample or mock data. Reword it (for example "synthetic figures") or show the real data.` });
|
|
1323
|
+
break;
|
|
1324
|
+
}
|
|
1325
|
+
if (warnings.length >= 10)
|
|
1326
|
+
break;
|
|
1327
|
+
}
|
|
1328
|
+
return warnings;
|
|
1329
|
+
}
|
|
1246
1330
|
async function callHostedBuildTool(opts, name, input) {
|
|
1247
1331
|
if (!servesBuild(opts))
|
|
1248
1332
|
throw new Error(`${name}_requires_build_surface`);
|
|
@@ -2025,7 +2109,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
2025
2109
|
},
|
|
2026
2110
|
{
|
|
2027
2111
|
name: "platform_inspect_artifact_app",
|
|
2028
|
-
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset); packageReady is false and problems lists each one until they are fixed.",
|
|
2112
|
+
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset) and a node --check of each .js/.mjs/.cjs file (javascript_syntax_error with file and line); packageReady is false and problems lists each one until they are fixed. warnings lists static text the build's page-text rules would refuse if the page shows it.",
|
|
2029
2113
|
annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
|
|
2030
2114
|
inputSchema: {
|
|
2031
2115
|
type: "object",
|
|
@@ -2038,7 +2122,8 @@ const BUILD_MCP_TOOLS = [
|
|
|
2038
2122
|
properties: {
|
|
2039
2123
|
ok: { type: "boolean" },
|
|
2040
2124
|
packageReady: { type: "boolean" },
|
|
2041
|
-
problems: { type: "array", items: { type: "object" }, description: "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain." },
|
|
2125
|
+
problems: { type: "array", items: { type: "object" }, description: "Checks Topline's build would fail: each has code, path (manifest field or file, with :line for javascript_syntax_error) and detail. packageReady is false while any remain." },
|
|
2126
|
+
warnings: { type: "array", items: { type: "object" }, description: "Static text that matches a rule Topline's render smoke applies to the page (rendered_text_rule:sample_or_mock_data_text), with the file and phrase. The build fails only if the rendered page shows it." },
|
|
2042
2127
|
serverManifestValidationRequired: { type: "boolean" },
|
|
2043
2128
|
appDir: { type: "string" },
|
|
2044
2129
|
platformAppDir: { type: "string" },
|
|
@@ -2407,6 +2492,9 @@ function withRecoveryOutputSchema(value) {
|
|
|
2407
2492
|
retryable: { type: "boolean" },
|
|
2408
2493
|
recoveryAction: { type: "string" },
|
|
2409
2494
|
signInUrl: { type: "string" },
|
|
2495
|
+
currentSourceHash: { type: "string" },
|
|
2496
|
+
pendingOperationId: { type: "string" },
|
|
2497
|
+
pendingKind: { type: "string" },
|
|
2410
2498
|
...(DOMAIN_FORWARD_TOOLS.has(tool.name) ? { recovery: { type: "object", additionalProperties: true } } : {})
|
|
2411
2499
|
},
|
|
2412
2500
|
required: ["code", "message", "retryable", "recoveryAction"],
|
|
@@ -2486,8 +2574,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
|
|
|
2486
2574
|
// Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
|
|
2487
2575
|
artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session). A build session always starts from the app's current version; Build MCP can't check out an older saved version, so to go back, deploy source you saved before (or ask the coding agent in Topline to go back to version N). For a refused deploy: keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash. For a refused validation request: don't deploy again. Wait for the current version's deploy to settle (platform_deploy_operation), run its checks and smoke, prepare it with platform_prepare_artifact_validation, then call platform_request_artifact_validation with that prepared evidence." },
|
|
2488
2576
|
build_session_deployment_arguments_required: { retryable: false, recoveryAction: "Inside a build session a deploy needs artifactVersionId, idempotencyKey, and the inspectedSourceHash and expectedBundleSha256 that platform_inspect_artifact_app returned. The fields named after the code are missing; add them and call again." },
|
|
2489
|
-
artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence.
|
|
2490
|
-
artifact_operation_pending: { retryable:
|
|
2577
|
+
artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence. Use currentSourceHash from this error when present, or read the session for its current sourceHash (or check out again into a new directory). Keep your local edits, inspect again, then deploy with the fresh hash." },
|
|
2578
|
+
artifact_operation_pending: { retryable: true, recoveryAction: "Another operation on this app has not settled. Read it with platform_deploy_operation, using pendingOperationId from this error when present (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal." },
|
|
2491
2579
|
artifact_deploy_in_flight: { retryable: true, recoveryAction: "A deploy for this app is still running. Wait until platform_deploy_operation says it is terminal, then retry the call that was refused (checkout, delete or deploy)." },
|
|
2492
2580
|
artifact_logs_deployment_not_found: { retryable: false, recoveryAction: "There is no deployment to read runtime logs from yet. For a failed build, read platform_deploy_operation: its failure field carries the build error." }
|
|
2493
2581
|
};
|
|
@@ -2499,13 +2587,35 @@ export function structuredToolError(message) {
|
|
|
2499
2587
|
const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
|
|
2500
2588
|
? "Topline refused this request as sent. Read the code, correct the input or state it names, then call the tool again; the same input fails the same way."
|
|
2501
2589
|
: "Inspect the code and message, correct the input if needed, then retry the same tool." };
|
|
2502
|
-
const structuredContent = { ok: false, error: { code, message, ...selected } };
|
|
2590
|
+
const structuredContent = { ok: false, error: { code, message, ...selected, ...conflictFieldsFromMessage(message) } };
|
|
2503
2591
|
return {
|
|
2504
2592
|
content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
|
|
2505
2593
|
structuredContent,
|
|
2506
2594
|
isError: true
|
|
2507
2595
|
};
|
|
2508
2596
|
}
|
|
2597
|
+
/** Round 12 Q5: Topline names the value a conflict needs (value-free hashes and ids); lift them onto the error. */
|
|
2598
|
+
function conflictFieldsFromMessage(message) {
|
|
2599
|
+
const http = /^platform_harness_http_error:\d{3}:(.*)$/s.exec(message);
|
|
2600
|
+
if (!http)
|
|
2601
|
+
return {};
|
|
2602
|
+
let body;
|
|
2603
|
+
try {
|
|
2604
|
+
body = JSON.parse(http[1]);
|
|
2605
|
+
}
|
|
2606
|
+
catch {
|
|
2607
|
+
return {};
|
|
2608
|
+
}
|
|
2609
|
+
if (!isRecord(body))
|
|
2610
|
+
return {};
|
|
2611
|
+
const out = {};
|
|
2612
|
+
for (const key of ["currentSourceHash", "pendingOperationId", "pendingKind"]) {
|
|
2613
|
+
const value = body[key];
|
|
2614
|
+
if (typeof value === "string" && /^[A-Za-z0-9_:.-]{1,128}$/.test(value))
|
|
2615
|
+
out[key] = value;
|
|
2616
|
+
}
|
|
2617
|
+
return out;
|
|
2618
|
+
}
|
|
2509
2619
|
/** The code Topline put inside a wrapped tool error: JSON `{ error: { code } }`, `{ error: "code" }`, or a leading code token. */
|
|
2510
2620
|
function hostedToolErrorCode(inner) {
|
|
2511
2621
|
try {
|