@topline-build/harness-mcp 0.9.13 → 0.9.14

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,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.14 - 2026-11-11
6
+
7
+ - `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.
8
+ - `platform_inspect_artifact_app` runs the manifest and data-binding checks Topline's build would fail: every `datasets[]` entry needs a `name` and `route`, every `routes[]` entry a `path`, and each `./_artifact/data/<name>` the source fetches needs a matching dataset. `packageReady` is false and `problems` names each field or file until they are fixed.
9
+ - Descriptions match the server: with company tables on, workspace SQL without a scope runs against company tables; an approved review completes the build session (asking again returns `validation_already_completed`); `needs_fix` keeps it active; rendered smoke can report `passed_with_warnings`; and omitted `buildOk` / `typecheckOk` are read as not reported.
10
+
5
11
  ## 0.9.13 - 2026-11-10
6
12
 
7
13
  - New `platform_read_logs`, for Topline staff only: bounded, redacted reads of the platform API and worker logs and of one-off task logs (connector syncs, one-off scripts, route optimization, link migrations, a coding task's runtime lines). It forwards to the hosted Build MCP, which checks operator access and audits every read.
@@ -19,7 +19,7 @@ export function externalBuildHelperTools(annotate) {
19
19
  }, ["idempotencyKey", "budgetCents", "brief"]),
20
20
  tool("platform_read_build_session", "Read the owned build session and original pending operations. Does not start another coder or deployment.", session, ["sessionId"], true),
21
21
  tool("platform_close_build_session", "Stop new authoring and request pending-operation cancellation. Unknown effects retain their reservation; cancellation does not undo committed writes.", session, ["sessionId"]),
22
- tool("platform_run_artifact_workspace_sql", "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.", {
22
+ tool("platform_run_artifact_workspace_sql", "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope \"company\". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.", {
23
23
  ...mutation, scope: { type: "string", enum: ["artifact", "company"] },
24
24
  sql: { type: "string", minLength: 1, maxLength: 20000 }, purpose: { type: "string", minLength: 3, maxLength: 500 },
25
25
  params: { type: "object", additionalProperties: true }, maxRows: { type: "integer", minimum: 1, maximum: 5000 }, documentation: { type: "object" }, columnDocumentation: { type: "object" }
@@ -38,14 +38,14 @@ export function externalBuildHelperTools(annotate) {
38
38
  tool("platform_add_acceptance_check", "Add a required acceptance check bound to this build session and deployed revision. A semantic control query requires separate Build data-verification consent.", {
39
39
  ...mutation, description: { type: "string", minLength: 3, maxLength: 1000 }
40
40
  }, [...Object.keys(mutation), "description"]),
41
- tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.", mutation, Object.keys(mutation)),
41
+ tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.", mutation, Object.keys(mutation)),
42
42
  tool("platform_record_acceptance_review", "Record the builder's review of a reviewer-only acceptance check. A passed result is accepted only for a check whose latest result platform_run_acceptance_checks recorded as a skipped reviewer check for this version, so run the checks first. Does not impersonate the independent validator or remove required checks.", {
43
43
  ...mutation, checkId: id, status: { type: "string", enum: ["passed", "failed"] }, summary: { type: "string", minLength: 3, maxLength: 2000 }
44
44
  }, [...Object.keys(mutation), "checkId", "status", "summary"]),
45
45
  tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id, idempotencyKey: requestKey }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
46
- tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.", {
46
+ tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.", {
47
47
  ...deployed, summary: { type: "string", minLength: 3, maxLength: 4000 }, waitMs: { type: "integer", minimum: 0, maximum: 1000, description: "Milliseconds to wait for the review before returning, 0 to 1000." },
48
- buildOk: { type: "boolean" }, typecheckOk: { type: "boolean" }, docImpact: { type: "string", enum: ["material", "none"] },
48
+ buildOk: { type: "boolean", description: "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version." }, typecheckOk: { type: "boolean", description: "Your own local typecheck result. Omit if you did not run one." }, docImpact: { type: "string", enum: ["material", "none"] },
49
49
  docImpactNotes: { type: "string", minLength: 12, maxLength: 2000 }, visualReview: { type: "object", additionalProperties: true }, dataValidation: { type: "object", additionalProperties: true }
50
50
  }, [...Object.keys(deployed), "summary", "docImpact", "docImpactNotes", "visualReview"]),
51
51
  tool("platform_artifact_validation_status", "Read the original validation result and pending prompts without starting another reviewer or deploy. operationId selects the review; the result names the artifactVersionId it reviewed, and a supplied artifactVersionId that differs is refused (validation_operation_version_mismatch). Use the operationId this build session's request returned; another session's operation is refused (validation_operation_not_found). Current authorization is rechecked before evidence delivery.", {
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.13";
45
+ export declare const HARNESS_MCP_VERSION = "0.9.14";
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[];
@@ -131,6 +131,11 @@ export declare function materializeBuildAssets(opts: HarnessMcpStdioOptions, inp
131
131
  export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
132
132
  ok: boolean;
133
133
  packageReady: boolean;
134
+ problems: {
135
+ code: string;
136
+ path: string;
137
+ detail: string;
138
+ }[];
134
139
  serverManifestValidationRequired: boolean;
135
140
  appDir: string;
136
141
  platformAppDir: string;
@@ -153,6 +158,16 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
153
158
  };
154
159
  nextAction: string;
155
160
  }>;
161
+ /**
162
+ * Round 11 P4: the checks Topline's server and trusted build run that a local inspect can repeat
163
+ * cheaply, so packageReady isn't true for a package the deploy will refuse: dataset and route
164
+ * fields the manifest needs, and ./_artifact/data/<name> references with no matching dataset.
165
+ */
166
+ export declare function localPreflightProblems(appDir: string, manifest: Record<string, unknown>): Promise<Array<{
167
+ code: string;
168
+ path: string;
169
+ detail: string;
170
+ }>>;
156
171
  export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
157
172
  export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
158
173
  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.13";
22
+ export const HARNESS_MCP_VERSION = "0.9.14";
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([
@@ -1153,9 +1153,11 @@ export async function inspectArtifactApp(opts, input) {
1153
1153
  const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
1154
1154
  const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
1155
1155
  const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
1156
+ const problems = await localPreflightProblems(absoluteAppDir, manifest);
1156
1157
  return {
1157
1158
  ok: true,
1158
- packageReady: true,
1159
+ packageReady: problems.length === 0,
1160
+ problems,
1159
1161
  serverManifestValidationRequired: true,
1160
1162
  appDir: workspaceAppDir,
1161
1163
  platformAppDir,
@@ -1178,9 +1180,69 @@ export async function inspectArtifactApp(opts, input) {
1178
1180
  sha256: bundle.sha256,
1179
1181
  excluded: bundle.excluded
1180
1182
  },
1181
- nextAction: "Call platform_deploy_artifact_app with the same appDir and expectedBundleSha256 set to bundle.sha256 when this local package is ready to deploy."
1183
+ nextAction: problems.length
1184
+ ? `Fix the ${problems.length === 1 ? "problem" : "problems"} listed in problems (each names its field or file), then inspect again. Topline's build would refuse this package as it is.`
1185
+ : "Call platform_deploy_artifact_app with the same appDir and expectedBundleSha256 set to bundle.sha256 when this local package is ready to deploy."
1182
1186
  };
1183
1187
  }
1188
+ const PREFLIGHT_SCAN_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".html", ".json", ".py", ".txt"]);
1189
+ const PREFLIGHT_SKIP_DIRS = new Set(["node_modules", ".git", ".next", ".vite", ".turbo", ".cache"]);
1190
+ /**
1191
+ * Round 11 P4: the checks Topline's server and trusted build run that a local inspect can repeat
1192
+ * cheaply, so packageReady isn't true for a package the deploy will refuse: dataset and route
1193
+ * fields the manifest needs, and ./_artifact/data/<name> references with no matching dataset.
1194
+ */
1195
+ export async function localPreflightProblems(appDir, manifest) {
1196
+ const problems = [];
1197
+ const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
1198
+ const datasets = Array.isArray(manifest.datasets) ? manifest.datasets : [];
1199
+ datasets.forEach((dataset, index) => {
1200
+ const record = isRecord(dataset) ? dataset : {};
1201
+ for (const key of ["name", "route"]) {
1202
+ if (!nonEmpty(record[key]))
1203
+ problems.push({ code: "invalid_artifact_app_manifest", path: `datasets[${index}].${key}`, detail: `datasets[${index}].${key} must be a non-empty string${key === "route" ? " (the page's path, for example /_artifact/data/<name>)" : ""}` });
1204
+ }
1205
+ });
1206
+ const routes = Array.isArray(manifest.routes) ? manifest.routes : [];
1207
+ routes.forEach((route, index) => {
1208
+ if (!isRecord(route) || !nonEmpty(route.path))
1209
+ problems.push({ code: "invalid_artifact_app_manifest", path: `routes[${index}].path`, detail: `routes[${index}].path must be a non-empty string` });
1210
+ });
1211
+ const declared = new Set([
1212
+ ...datasets.filter(isRecord).map((dataset) => dataset.name),
1213
+ ...(Array.isArray(manifest.sourceBindings) ? manifest.sourceBindings : []).filter(isRecord).map((binding) => binding.name)
1214
+ ].filter((name) => typeof name === "string"));
1215
+ const reported = new Set();
1216
+ let scanned = 0;
1217
+ const visit = async (dir) => {
1218
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
1219
+ if (scanned > 5_000)
1220
+ return;
1221
+ const full = path.join(dir, entry.name);
1222
+ if (entry.isDirectory()) {
1223
+ if (!PREFLIGHT_SKIP_DIRS.has(entry.name))
1224
+ await visit(full);
1225
+ continue;
1226
+ }
1227
+ if (!entry.isFile() || !PREFLIGHT_SCAN_EXTENSIONS.has(path.extname(entry.name)))
1228
+ continue;
1229
+ scanned += 1;
1230
+ const content = await readFile(full, "utf8").catch(() => "");
1231
+ if (content.length > 2_000_000)
1232
+ continue;
1233
+ for (const match of content.matchAll(/\.\/_artifact\/data\/([A-Za-z0-9_-]+)/g)) {
1234
+ const rel = path.relative(appDir, full).replaceAll("\\", "/");
1235
+ const key = `${rel}:${match[1]}`;
1236
+ if (declared.has(match[1]) || reported.has(key))
1237
+ continue;
1238
+ reported.add(key);
1239
+ problems.push({ code: "undeclared_artifact_data_binding", path: rel, detail: `${rel} fetches ./_artifact/data/${match[1]}, but no datasets[] entry is named ${match[1]}. Declare it (with its route) or remove the reference.` });
1240
+ }
1241
+ }
1242
+ };
1243
+ await visit(appDir);
1244
+ return problems.slice(0, 25);
1245
+ }
1184
1246
  async function callHostedBuildTool(opts, name, input) {
1185
1247
  if (!servesBuild(opts))
1186
1248
  throw new Error(`${name}_requires_build_surface`);
@@ -1351,8 +1413,12 @@ export async function waitForArtifactDeploy(opts, input, onProgress) {
1351
1413
  if (typeof latest.nextSeq === "number")
1352
1414
  afterSeq = latest.nextSeq;
1353
1415
  if (latest.terminal === true) {
1354
- if (latest.successful !== true)
1355
- throw new Error(`artifact_deploy_failed:${String(latest.taskStatus ?? "failed")}`);
1416
+ if (latest.successful !== true) {
1417
+ // Round 11 P3: name the build's failure code, not just the task status.
1418
+ const failure = isRecord(latest.failure) ? latest.failure : {};
1419
+ const code = typeof failure.code === "string" && /^[a-z][a-z0-9_]{2,80}$/.test(failure.code) ? failure.code : String(latest.taskStatus ?? "failed");
1420
+ throw new Error(`artifact_deploy_failed:${code}`);
1421
+ }
1356
1422
  return latest;
1357
1423
  }
1358
1424
  const waitMs = typeof latest.nextPollAfterMs === "number" ? Math.min(Math.max(latest.nextPollAfterMs, 250), 10_000) : 2_000;
@@ -1959,7 +2025,7 @@ const BUILD_MCP_TOOLS = [
1959
2025
  },
1960
2026
  {
1961
2027
  name: "platform_inspect_artifact_app",
1962
- description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
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.",
1963
2029
  annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
1964
2030
  inputSchema: {
1965
2031
  type: "object",
@@ -1972,6 +2038,7 @@ const BUILD_MCP_TOOLS = [
1972
2038
  properties: {
1973
2039
  ok: { type: "boolean" },
1974
2040
  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." },
1975
2042
  serverManifestValidationRequired: { type: "boolean" },
1976
2043
  appDir: { type: "string" },
1977
2044
  platformAppDir: { type: "string" },
@@ -2005,7 +2072,7 @@ const BUILD_MCP_TOOLS = [
2005
2072
  },
2006
2073
  {
2007
2074
  name: "platform_wait_artifact_deploy",
2008
- description: "Wait for a durable deployment operation and stream server-derived progress.",
2075
+ description: "Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.",
2009
2076
  annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
2010
2077
  inputSchema: { type: "object", properties: { artifactId: { type: "string", format: "uuid" }, operationId: { type: "string", format: "uuid" }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
2011
2078
  outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
@@ -2402,6 +2469,9 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2402
2469
  build_session_id_required: { retryable: false, recoveryAction: "The fields named after the code only work inside a build session. Remove them for a plain deploy of an app you created over MCP, or start a session and pass its sessionId." },
2403
2470
  artifact_external_session_active: { retryable: false, recoveryAction: "An open build session holds this app. If it is yours, pass its sessionId; otherwise close it with platform_close_build_session or wait for it to end." },
2404
2471
  artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
2472
+ // Round 11 P3: the wait names the failure code; the detail (the build's own error) is on the operation.
2473
+ artifact_deploy_failed: { retryable: false, recoveryAction: "The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way." },
2474
+ validation_already_completed: { retryable: false, recoveryAction: "A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline." },
2405
2475
  artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
2406
2476
  artifact_app_bundle_changed_after_inspection: { retryable: true, recoveryAction: "Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash." },
2407
2477
  artifact_app_bundle_hardlink_forbidden: { retryable: false, recoveryAction: "Replace the hard link with a regular file copied into appDir, then inspect again." },
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.9.13",
5
+ "version": "0.9.14",
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.13"
15
+ "version": "0.9.14"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -420,6 +420,16 @@
420
420
  "retryable": true,
421
421
  "recoveryAction": "Call platform_wait_artifact_deploy again with the same artifactId and operationId."
422
422
  },
423
+ {
424
+ "code": "artifact_deploy_failed",
425
+ "retryable": false,
426
+ "recoveryAction": "The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way."
427
+ },
428
+ {
429
+ "code": "validation_already_completed",
430
+ "retryable": false,
431
+ "recoveryAction": "A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline."
432
+ },
423
433
  {
424
434
  "code": "artifact_delete_plan_stale",
425
435
  "retryable": true,
@@ -1060,7 +1070,7 @@
1060
1070
  },
1061
1071
  {
1062
1072
  "name": "platform_inspect_artifact_app",
1063
- "description": "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.",
1073
+ "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.",
1064
1074
  "annotations": {
1065
1075
  "title": "Platform Inspect Artifact App",
1066
1076
  "readOnlyHint": true,
@@ -1097,6 +1107,13 @@
1097
1107
  "packageReady": {
1098
1108
  "type": "boolean"
1099
1109
  },
1110
+ "problems": {
1111
+ "type": "array",
1112
+ "items": {
1113
+ "type": "object"
1114
+ },
1115
+ "description": "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain."
1116
+ },
1100
1117
  "serverManifestValidationRequired": {
1101
1118
  "type": "boolean"
1102
1119
  },
@@ -1515,7 +1532,7 @@
1515
1532
  },
1516
1533
  {
1517
1534
  "name": "platform_wait_artifact_deploy",
1518
- "description": "Wait for a durable deployment operation and stream server-derived progress.",
1535
+ "description": "Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.",
1519
1536
  "annotations": {
1520
1537
  "title": "Platform Wait Artifact Deploy",
1521
1538
  "readOnlyHint": true,
@@ -3736,7 +3753,7 @@
3736
3753
  },
3737
3754
  {
3738
3755
  "name": "platform_run_artifact_workspace_sql",
3739
- "description": "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.",
3756
+ "description": "Run guarded SQL using the exact session, version and retry key. Without scope, or scope \"artifact\", it reads and writes this app's own build-checkpoint and cache tables; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope \"company\". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. With scope \"company\", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.",
3740
3757
  "annotations": {
3741
3758
  "title": "Platform Run Artifact Workspace Sql",
3742
3759
  "readOnlyHint": false,
@@ -4445,7 +4462,7 @@
4445
4462
  },
4446
4463
  {
4447
4464
  "name": "platform_run_acceptance_checks",
4448
- "description": "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.",
4465
+ "description": "Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.",
4449
4466
  "annotations": {
4450
4467
  "title": "Platform Run Acceptance Checks",
4451
4468
  "readOnlyHint": false,
@@ -4768,7 +4785,7 @@
4768
4785
  },
4769
4786
  {
4770
4787
  "name": "platform_request_artifact_validation",
4771
- "description": "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.",
4788
+ "description": "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.",
4772
4789
  "annotations": {
4773
4790
  "title": "Platform Request Artifact Validation",
4774
4791
  "readOnlyHint": false,
@@ -4810,10 +4827,12 @@
4810
4827
  "description": "Milliseconds to wait for the review before returning, 0 to 1000."
4811
4828
  },
4812
4829
  "buildOk": {
4813
- "type": "boolean"
4830
+ "type": "boolean",
4831
+ "description": "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version."
4814
4832
  },
4815
4833
  "typecheckOk": {
4816
- "type": "boolean"
4834
+ "type": "boolean",
4835
+ "description": "Your own local typecheck result. Omit if you did not run one."
4817
4836
  },
4818
4837
  "docImpact": {
4819
4838
  "type": "string",
@@ -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.13`
5
+ Package: `@topline-build/harness-mcp@0.9.14`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -81,6 +81,8 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
81
81
  - `build_session_id_required` (not automatically retryable): The fields named after the code only work inside a build session. Remove them for a plain deploy of an app you created over MCP, or start a session and pass its sessionId.
82
82
  - `artifact_external_session_active` (not automatically retryable): An open build session holds this app. If it is yours, pass its sessionId; otherwise close it with platform_close_build_session or wait for it to end.
83
83
  - `artifact_deploy_wait_timeout` (retryable): Call platform_wait_artifact_deploy again with the same artifactId and operationId.
84
+ - `artifact_deploy_failed` (not automatically retryable): The deploy finished and failed; the code after artifact_deploy_failed names why. Call platform_deploy_operation with the same artifactId and operationId for failure.detail (the build's own error) and failure.nextAction. Fix the source, run platform_inspect_artifact_app, then deploy again. Retrying the wait or redeploying the same source fails the same way.
85
+ - `validation_already_completed` (not automatically retryable): A review already approved this version and completed the build session. Don't request another review or start a new session to repeat it; read the verdict with platform_artifact_validation_status. Publishing is the person's step in Topline.
84
86
  - `artifact_delete_plan_stale` (retryable): Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken.
85
87
  - `artifact_app_bundle_changed_after_inspection` (retryable): Call platform_inspect_artifact_app again, review the new bundle hash, then retry deployment with that hash.
86
88
  - `artifact_app_bundle_hardlink_forbidden` (not automatically retryable): Replace the hard link with a regular file copied into appDir, then inspect again.
@@ -704,7 +706,7 @@ Output schema:
704
706
 
705
707
  ### `platform_inspect_artifact_app`
706
708
 
707
- Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft.
709
+ 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.
708
710
 
709
711
  Safety: read-only=true, destructive=false, idempotent=false, open-world=false.
710
712
 
@@ -769,6 +771,13 @@ Output schema:
769
771
  "packageReady": {
770
772
  "type": "boolean"
771
773
  },
774
+ "problems": {
775
+ "type": "array",
776
+ "items": {
777
+ "type": "object"
778
+ },
779
+ "description": "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain."
780
+ },
772
781
  "serverManifestValidationRequired": {
773
782
  "type": "boolean"
774
783
  },
@@ -1207,7 +1216,7 @@ Output schema:
1207
1216
 
1208
1217
  ### `platform_wait_artifact_deploy`
1209
1218
 
1210
- Wait for a durable deployment operation and stream server-derived progress.
1219
+ Wait for a durable deployment operation and stream server-derived progress. A failed deploy returns artifact_deploy_failed:<failure code>; read platform_deploy_operation for the build's own error (failure.detail) and next step. A successful deploy returns the session's next sourceHash for the following deploy.
1211
1220
 
1212
1221
  Safety: read-only=true, destructive=false, idempotent=false, open-world=true.
1213
1222
 
@@ -3652,7 +3661,7 @@ Output schema:
3652
3661
 
3653
3662
  ### `platform_run_artifact_workspace_sql`
3654
3663
 
3655
- Run guarded SQL using the exact session, version and retry key. Without scope, or scope "artifact", it reads and writes this app's own build-checkpoint and cache tables. With scope "company", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.
3664
+ Run guarded SQL using the exact session, version and retry key. Without scope, or scope "artifact", it reads and writes this app's own build-checkpoint and cache tables; when the build session's workspace.routing is company_tables there are no private tables and every statement runs against company tables, as with scope "company". A statement the database rejects returns sql_statement_failed:<SQLSTATE> (company tables: company_table_sql_failed:<SQLSTATE>) with a fixed hint. With scope "company", it creates, changes or drops a company table in company_data, or changes its rows, at once with no confirmation step; check the catalog before creating one, and declare tables an app uses in manifest tables[]. The company scope needs the harness:company:tables:write permission on your sign-in and the build session. CREATE TABLE/ADD COLUMN require documentation (company tables: a description and sensitivity for every column). Enforced non-admin writes remain denied; unknown writes are never replayed.
3656
3665
 
3657
3666
  Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
3658
3667
 
@@ -4438,7 +4447,7 @@ Output schema:
4438
4447
 
4439
4448
  ### `platform_run_acceptance_checks`
4440
4449
 
4441
- Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version, which also gates validation.
4450
+ Run required acceptance checks for the exact current draft revision through the shared service. Pass counts cover acceptance checks only; renderedSmoke reports the latest rendered smoke for this version (passed, passed_with_warnings with qualityWarnings codes, failed with failingChecks, or not_run), which also gates validation.
4442
4451
 
4443
4452
  Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
4444
4453
 
@@ -4794,7 +4803,7 @@ Output schema:
4794
4803
 
4795
4804
  ### `platform_request_artifact_validation`
4796
4805
 
4797
- Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish.
4806
+ Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval. waitMs is 0 to 1000 (milliseconds to wait before returning); poll platform_artifact_validation_status for longer reviews. An approved review marks the private draft ready for an operator to publish and completes this build session; asking again returns validation_already_completed. A needs_fix review keeps the session active: fix, deploy a new version, smoke, then request a review of that version. If the draft isn't ready, the refusal names the blocker platform_prepare_artifact_validation reports.
4798
4807
 
4799
4808
  Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
4800
4809
 
@@ -4856,10 +4865,12 @@ Input schema:
4856
4865
  "description": "Milliseconds to wait for the review before returning, 0 to 1000."
4857
4866
  },
4858
4867
  "buildOk": {
4859
- "type": "boolean"
4868
+ "type": "boolean",
4869
+ "description": "Your own local build result. Omit if you did not run one; the reviewer is told separately that Topline's trusted build deployed this version."
4860
4870
  },
4861
4871
  "typecheckOk": {
4862
- "type": "boolean"
4872
+ "type": "boolean",
4873
+ "description": "Your own local typecheck result. Omit if you did not run one."
4863
4874
  },
4864
4875
  "docImpact": {
4865
4876
  "type": "string",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.9.13",
3
+ "version": "0.9.14",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",