@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 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.14";
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.14";
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. 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." },
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 {