@topline-build/harness-mcp 0.9.14 → 0.9.16

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 CHANGED
@@ -2,6 +2,20 @@
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.16 - 2026-11-11
6
+
7
+ - `platform_deploy_artifact_app` runs inspect's manifest and `node --check` checks and refuses with `artifact_package_not_ready`, naming each problem's code and file, before it uploads anything or spends build budget. (Data-binding findings stay inspect-only, since a leftover build file can trip them.)
8
+ - `node --check` no longer reports an ES module file as a syntax error on Node versions that check it as CommonJS ("Cannot use import statement outside a module").
9
+ - Inside a build session, a deploy that passes `projectId` is refused locally with `build_session_project_id_not_allowed` instead of reaching Topline as a retryable server error.
10
+ - A deploy cancelled because its build session was closed (`artifact_deploy_failed:build_session_cancelled`) says to start a new session and deploy again, not to fix the source.
11
+ - `javascript_syntax_error` details no longer end in a stray carriage return on Windows.
12
+
13
+ ## 0.9.15 - 2026-11-11
14
+
15
+ - `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.
16
+ - 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.
17
+ - 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.
18
+
5
19
  ## 0.9.14 - 2026-11-11
6
20
 
7
21
  - `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.14";
45
+ export declare const HARNESS_MCP_VERSION = "0.9.16";
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.14";
22
+ export const HARNESS_MCP_VERSION = "0.9.16";
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([
@@ -936,6 +936,14 @@ export async function deployArtifactApp(opts, input, onProgress) {
936
936
  .digest("hex");
937
937
  await onProgress?.(0.2, "Packaging local artifact app");
938
938
  const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
939
+ // Round 13 R4: a package inspect says isn't ready fails the build the same way, after spending
940
+ // budget and a minute; refuse it here, before anything is uploaded.
941
+ // Only checks that can't be a stale or unrelated file (manifest fields and syntax errors) block a deploy;
942
+ // inspect still lists data-binding findings, which a leftover build output can trip.
943
+ const problems = (await localPreflightProblems(absoluteAppDir, manifest)).filter((problem) => problem.code === "invalid_artifact_app_manifest");
944
+ problems.push(...await javascriptSyntaxProblems(absoluteAppDir));
945
+ if (problems.length)
946
+ throw new Error(`artifact_package_not_ready:${problems.slice(0, 5).map((problem) => `${problem.code} ${problem.path}`).join("; ")}`);
939
947
  const expectedBundleSha256 = optionalString(input, "expectedBundleSha256")?.toLowerCase();
940
948
  if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
941
949
  throw new Error("artifact_app_bundle_changed_after_inspection");
@@ -952,6 +960,9 @@ export async function deployArtifactApp(opts, input, onProgress) {
952
960
  .filter(([, value]) => !value).map(([name]) => name);
953
961
  if (missing.length)
954
962
  throw new Error(`build_session_deployment_arguments_required:${missing.join(",")}`);
963
+ // Round 13 R7: the session already belongs to its artifact (and project); Topline refuses projectId here.
964
+ if (optionalString(input, "projectId"))
965
+ throw new Error("build_session_project_id_not_allowed");
955
966
  const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
956
967
  // The server resolves a repeated operation key before checking current
957
968
  // version/source. Do not reject a lost-response retry using the newer read.
@@ -1154,10 +1165,13 @@ export async function inspectArtifactApp(opts, input) {
1154
1165
  const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
1155
1166
  const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
1156
1167
  const problems = await localPreflightProblems(absoluteAppDir, manifest);
1168
+ problems.push(...await javascriptSyntaxProblems(absoluteAppDir));
1169
+ const warnings = await renderedTextRuleWarnings(absoluteAppDir);
1157
1170
  return {
1158
1171
  ok: true,
1159
1172
  packageReady: problems.length === 0,
1160
1173
  problems,
1174
+ warnings,
1161
1175
  serverManifestValidationRequired: true,
1162
1176
  appDir: workspaceAppDir,
1163
1177
  platformAppDir,
@@ -1243,6 +1257,91 @@ export async function localPreflightProblems(appDir, manifest) {
1243
1257
  await visit(appDir);
1244
1258
  return problems.slice(0, 25);
1245
1259
  }
1260
+ const SYNTAX_CHECK_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
1261
+ const SYNTAX_CHECK_SKIP_DIRS = new Set([...PREFLIGHT_SKIP_DIRS, "dist", "build", "out", "vendor"]);
1262
+ async function listAppFiles(appDir, extensions, skipDirs, limit) {
1263
+ const out = [];
1264
+ const visit = async (dir) => {
1265
+ for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
1266
+ if (out.length >= limit)
1267
+ return;
1268
+ const full = path.join(dir, entry.name);
1269
+ if (entry.isDirectory()) {
1270
+ if (!skipDirs.has(entry.name))
1271
+ await visit(full);
1272
+ continue;
1273
+ }
1274
+ if (entry.isFile() && extensions.has(path.extname(entry.name)))
1275
+ out.push(full);
1276
+ }
1277
+ };
1278
+ await visit(appDir);
1279
+ return out;
1280
+ }
1281
+ function nodeCheck(file) {
1282
+ return new Promise((resolve) => {
1283
+ const child = spawn(process.execPath, ["--check", file], { stdio: ["ignore", "ignore", "pipe"] });
1284
+ let stderr = "";
1285
+ child.stderr?.on("data", (chunk) => { if (stderr.length < 4_000)
1286
+ stderr += String(chunk); });
1287
+ const timer = setTimeout(() => { child.kill(); resolve(null); }, 10_000);
1288
+ child.on("error", () => { clearTimeout(timer); resolve(null); });
1289
+ child.on("close", (code) => { clearTimeout(timer); resolve(code === 0 ? null : stderr); });
1290
+ });
1291
+ }
1292
+ /**
1293
+ * Round 12: a JavaScript syntax error passed inspect (packageReady true) and then failed the
1294
+ * build. Check each source file the way the build's Node would, and name the file and line.
1295
+ */
1296
+ export async function javascriptSyntaxProblems(appDir) {
1297
+ const problems = [];
1298
+ for (const file of await listAppFiles(appDir, SYNTAX_CHECK_EXTENSIONS, SYNTAX_CHECK_SKIP_DIRS, 200)) {
1299
+ const stderr = await nodeCheck(file);
1300
+ if (!stderr || !/SyntaxError/.test(stderr))
1301
+ continue;
1302
+ // Round 13 review: an ES module file checked as CommonJS (older Node, no "type": "module") isn't
1303
+ // a syntax error the build hits; only real syntax errors count.
1304
+ if (/outside a module|Unexpected token 'export'|Cannot use 'import\.meta'/.test(stderr))
1305
+ continue;
1306
+ const rel = path.relative(appDir, file).replaceAll("\\", "/");
1307
+ const line = new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(\\d+)`).exec(stderr)?.[1] ?? null;
1308
+ const message = /SyntaxError:[^\r\n]*/.exec(stderr)?.[0]?.slice(0, 200) ?? "SyntaxError";
1309
+ problems.push({ code: "javascript_syntax_error", path: line ? `${rel}:${line}` : rel, detail: `${rel}${line ? ` line ${line}` : ""}: ${message}` });
1310
+ if (problems.length >= 10)
1311
+ break;
1312
+ }
1313
+ return problems;
1314
+ }
1315
+ // The page-text rule the build's render smoke applies (sample_or_mock_data_text). Inspect can only
1316
+ // see static text, so a match is a warning: the build fails only if the rendered page shows it.
1317
+ const SAMPLE_DATA_TEXT_PATTERNS = [
1318
+ /\b(showing|using|displaying|rendering|loaded|fallback|placeholder)\s+(sample|demo|mock|placeholder|example)?\s*(data|dataset|rows|metrics|values)\b/i,
1319
+ /\b(sample|demo|mock|placeholder|example)\s+(data|dataset|rows|metrics|values)\b/i,
1320
+ /\b(template[-\s]?local|local[-\s]?(summary|tasks|events|rows|metrics|dataset))\b/i
1321
+ ];
1322
+ export async function renderedTextRuleWarnings(appDir) {
1323
+ const warnings = [];
1324
+ for (const file of await listAppFiles(appDir, new Set([".html", ".js", ".jsx", ".ts", ".tsx", ".mjs"]), SYNTAX_CHECK_SKIP_DIRS, 500)) {
1325
+ const content = await readFile(file, "utf8").catch(() => "");
1326
+ if (content.length > 2_000_000)
1327
+ continue;
1328
+ // Visible text only: HTML text between tags and quoted string literals, not identifiers or comments.
1329
+ const texts = [...content.matchAll(/>([^<>]{3,400})</g), ...content.matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.){3,400})\1/g)].map((m) => m[m.length - 1] ?? "");
1330
+ for (const text of texts) {
1331
+ const match = SAMPLE_DATA_TEXT_PATTERNS.map((pattern) => pattern.exec(text)).find(Boolean);
1332
+ if (!match)
1333
+ continue;
1334
+ const rel = path.relative(appDir, file).replaceAll("\\", "/");
1335
+ const phrase = match[0].slice(0, 80);
1336
+ warnings.push({ code: "rendered_text_rule:sample_or_mock_data_text", path: rel, phrase,
1337
+ 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.` });
1338
+ break;
1339
+ }
1340
+ if (warnings.length >= 10)
1341
+ break;
1342
+ }
1343
+ return warnings;
1344
+ }
1246
1345
  async function callHostedBuildTool(opts, name, input) {
1247
1346
  if (!servesBuild(opts))
1248
1347
  throw new Error(`${name}_requires_build_surface`);
@@ -1987,7 +2086,7 @@ const BUILD_MCP_TOOLS = [
1987
2086
  },
1988
2087
  {
1989
2088
  name: "platform_deploy_artifact_app",
1990
- description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
2089
+ description: "Package a local artifact app directory, upload it, deploy a private draft, and return status. It runs platform_inspect_artifact_app's manifest and JavaScript syntax checks first and refuses with artifact_package_not_ready, before uploading or spending budget, while any of those problems remain. Inside a build session, leave projectId out.",
1991
2090
  annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
1992
2091
  inputSchema: {
1993
2092
  type: "object",
@@ -2025,7 +2124,7 @@ const BUILD_MCP_TOOLS = [
2025
2124
  },
2026
2125
  {
2027
2126
  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.",
2127
+ 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
2128
  annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
2030
2129
  inputSchema: {
2031
2130
  type: "object",
@@ -2038,7 +2137,8 @@ const BUILD_MCP_TOOLS = [
2038
2137
  properties: {
2039
2138
  ok: { type: "boolean" },
2040
2139
  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." },
2140
+ 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." },
2141
+ 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
2142
  serverManifestValidationRequired: { type: "boolean" },
2043
2143
  appDir: { type: "string" },
2044
2144
  platformAppDir: { type: "string" },
@@ -2407,6 +2507,9 @@ function withRecoveryOutputSchema(value) {
2407
2507
  retryable: { type: "boolean" },
2408
2508
  recoveryAction: { type: "string" },
2409
2509
  signInUrl: { type: "string" },
2510
+ currentSourceHash: { type: "string" },
2511
+ pendingOperationId: { type: "string" },
2512
+ pendingKind: { type: "string" },
2410
2513
  ...(DOMAIN_FORWARD_TOOLS.has(tool.name) ? { recovery: { type: "object", additionalProperties: true } } : {})
2411
2514
  },
2412
2515
  required: ["code", "message", "retryable", "recoveryAction"],
@@ -2485,9 +2588,12 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2485
2588
  artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
2486
2589
  // Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
2487
2590
  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." },
2591
+ artifact_package_not_ready: { retryable: false, recoveryAction: "platform_inspect_artifact_app reports problems Topline's build would fail on (named after the code, with file and line), so nothing was uploaded or spent. Fix them, run platform_inspect_artifact_app until packageReady is true, then deploy with the new expectedBundleSha256." },
2592
+ build_session_project_id_not_allowed: { retryable: false, recoveryAction: "Inside a build session the draft already belongs to the session's artifact and project. Leave projectId out and call again." },
2593
+ "artifact_deploy_failed:build_session_cancelled": { retryable: false, recoveryAction: "This deploy was cancelled because its build session was closed before it finished; the source wasn't at fault. Start a new build session for this artifact, then inspect and deploy again." },
2488
2594
  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. 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." },
2490
- artifact_operation_pending: { retryable: false, recoveryAction: "Another operation on this app has not settled. Read it with platform_deploy_operation (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal." },
2595
+ 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." },
2596
+ 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
2597
  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
2598
  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
2599
  };
@@ -2496,16 +2602,40 @@ export function structuredToolError(message) {
2496
2602
  const code = recoveryErrorCode(message);
2497
2603
  // A 4xx means the same request will be refused again; only 5xx, timeouts and rate limits are worth retrying unchanged.
2498
2604
  const retryable = /^platform_harness_http_error:5|timeout|rate_limited|unavailable|internal_error/.test(message);
2499
- const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
2605
+ // A failure code after the error code can have its own guidance (artifact_deploy_failed:build_session_cancelled).
2606
+ const detailCode = /^[a-z_]+:([a-z][a-z0-9_]{2,80})\b/.exec(message)?.[1];
2607
+ const selected = (detailCode ? BUILD_MCP_RECOVERY_ERRORS[`${code}:${detailCode}`] : undefined) ?? BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
2500
2608
  ? "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
2609
  : "Inspect the code and message, correct the input if needed, then retry the same tool." };
2502
- const structuredContent = { ok: false, error: { code, message, ...selected } };
2610
+ const structuredContent = { ok: false, error: { code, message, ...selected, ...conflictFieldsFromMessage(message) } };
2503
2611
  return {
2504
2612
  content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
2505
2613
  structuredContent,
2506
2614
  isError: true
2507
2615
  };
2508
2616
  }
2617
+ /** Round 12 Q5: Topline names the value a conflict needs (value-free hashes and ids); lift them onto the error. */
2618
+ function conflictFieldsFromMessage(message) {
2619
+ const http = /^platform_harness_http_error:\d{3}:(.*)$/s.exec(message);
2620
+ if (!http)
2621
+ return {};
2622
+ let body;
2623
+ try {
2624
+ body = JSON.parse(http[1]);
2625
+ }
2626
+ catch {
2627
+ return {};
2628
+ }
2629
+ if (!isRecord(body))
2630
+ return {};
2631
+ const out = {};
2632
+ for (const key of ["currentSourceHash", "pendingOperationId", "pendingKind"]) {
2633
+ const value = body[key];
2634
+ if (typeof value === "string" && /^[A-Za-z0-9_:.-]{1,128}$/.test(value))
2635
+ out[key] = value;
2636
+ }
2637
+ return out;
2638
+ }
2509
2639
  /** The code Topline put inside a wrapped tool error: JSON `{ error: { code } }`, `{ error: "code" }`, or a leading code token. */
2510
2640
  function hostedToolErrorCode(inner) {
2511
2641
  try {