@topline-build/harness-mcp 0.9.15 → 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,14 @@
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
+
5
13
  ## 0.9.15 - 2026-11-11
6
14
 
7
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.
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.15";
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[];
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.15";
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.
@@ -1288,9 +1299,13 @@ export async function javascriptSyntaxProblems(appDir) {
1288
1299
  const stderr = await nodeCheck(file);
1289
1300
  if (!stderr || !/SyntaxError/.test(stderr))
1290
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;
1291
1306
  const rel = path.relative(appDir, file).replaceAll("\\", "/");
1292
1307
  const line = new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(\\d+)`).exec(stderr)?.[1] ?? null;
1293
- const message = /SyntaxError:[^\n]*/.exec(stderr)?.[0]?.slice(0, 200) ?? "SyntaxError";
1308
+ const message = /SyntaxError:[^\r\n]*/.exec(stderr)?.[0]?.slice(0, 200) ?? "SyntaxError";
1294
1309
  problems.push({ code: "javascript_syntax_error", path: line ? `${rel}:${line}` : rel, detail: `${rel}${line ? ` line ${line}` : ""}: ${message}` });
1295
1310
  if (problems.length >= 10)
1296
1311
  break;
@@ -2071,7 +2086,7 @@ const BUILD_MCP_TOOLS = [
2071
2086
  },
2072
2087
  {
2073
2088
  name: "platform_deploy_artifact_app",
2074
- 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.",
2075
2090
  annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
2076
2091
  inputSchema: {
2077
2092
  type: "object",
@@ -2573,6 +2588,9 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2573
2588
  artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
2574
2589
  // Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
2575
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." },
2576
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." },
2577
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." },
2578
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." },
@@ -2584,7 +2602,9 @@ export function structuredToolError(message) {
2584
2602
  const code = recoveryErrorCode(message);
2585
2603
  // A 4xx means the same request will be refused again; only 5xx, timeouts and rate limits are worth retrying unchanged.
2586
2604
  const retryable = /^platform_harness_http_error:5|timeout|rate_limited|unavailable|internal_error/.test(message);
2587
- 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)
2588
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."
2589
2609
  : "Inspect the code and message, correct the input if needed, then retry the same tool." };
2590
2610
  const structuredContent = { ok: false, error: { code, message, ...selected, ...conflictFieldsFromMessage(message) } };
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.9.15",
5
+ "version": "0.9.16",
6
6
  "bin": {
7
7
  "topline-mcp": "dist/cli.js"
8
8
  }
@@ -12,7 +12,7 @@
12
12
  "defaultVersion": "2025-11-25",
13
13
  "server": {
14
14
  "name": "topline-build-stdio",
15
- "version": "0.9.15"
15
+ "version": "0.9.16"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -494,6 +494,21 @@
494
494
  "retryable": false,
495
495
  "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."
496
496
  },
497
+ {
498
+ "code": "artifact_package_not_ready",
499
+ "retryable": false,
500
+ "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."
501
+ },
502
+ {
503
+ "code": "build_session_project_id_not_allowed",
504
+ "retryable": false,
505
+ "recoveryAction": "Inside a build session the draft already belongs to the session's artifact and project. Leave projectId out and call again."
506
+ },
507
+ {
508
+ "code": "artifact_deploy_failed:build_session_cancelled",
509
+ "retryable": false,
510
+ "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."
511
+ },
497
512
  {
498
513
  "code": "build_session_deployment_arguments_required",
499
514
  "retryable": false,
@@ -929,7 +944,7 @@
929
944
  },
930
945
  {
931
946
  "name": "platform_deploy_artifact_app",
932
- "description": "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
947
+ "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.",
933
948
  "annotations": {
934
949
  "title": "Platform Deploy Artifact App",
935
950
  "readOnlyHint": false,
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
4
4
 
5
- Package: `@topline-build/harness-mcp@0.9.15`
5
+ Package: `@topline-build/harness-mcp@0.9.16`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -94,6 +94,9 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
94
94
  - `artifact_app_scaffold_starter_invalid` (not automatically retryable): Use one of the starters: bounded-bedrock-assistant, cache-warmed-multi-source-dashboard, internal-action-tool, live-operations-dashboard, materialized-sql-data-product, precomputed-s3-report, private-api-first-app, viewer-scoped-customer-portal.
95
95
  - `artifact_app_scaffold_starter_shape_conflict` (not automatically retryable): A starter scaffolds the single shape; leave shape out or set it to single.
96
96
  - `artifact_version_conflict` (not automatically retryable): 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.
97
+ - `artifact_package_not_ready` (not automatically retryable): 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.
98
+ - `build_session_project_id_not_allowed` (not automatically retryable): Inside a build session the draft already belongs to the session's artifact and project. Leave projectId out and call again.
99
+ - `artifact_deploy_failed:build_session_cancelled` (not automatically retryable): 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.
97
100
  - `build_session_deployment_arguments_required` (not automatically retryable): 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.
98
101
  - `artifact_source_conflict` (not automatically retryable): 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.
99
102
  - `artifact_operation_pending` (retryable): 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.
@@ -544,7 +547,7 @@ Output schema:
544
547
 
545
548
  ### `platform_deploy_artifact_app`
546
549
 
547
- Package a local artifact app directory, upload it, deploy a private draft, and return status.
550
+ 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.
548
551
 
549
552
  Safety: read-only=false, destructive=false, idempotent=false, open-world=true.
550
553
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.9.15",
3
+ "version": "0.9.16",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",