@topline-build/harness-mcp 0.9.3 → 0.9.5

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,17 @@
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.5 - 2026-11-01
6
+
7
+ - A Topline refusal wrapped as `platform_mcp_tool_error` keeps its code when the code is camelCase in part (for example `workspace_table_displayName_too_short`), from the message or from a JSON body. It was reported as a bare `platform_mcp_tool_error` before.
8
+ - A Topline refusal whose code has no recovery step of its own now says the same input fails the same way, as a 4xx already did, instead of offering a plain retry.
9
+
10
+ ## 0.9.4 - 2026-11-01
11
+
12
+ - `platform_init_artifact_app` takes an optional `starter`, one of the Build cookbook examples that ship a manifest (for example `internal-action-tool`, `private-api-first-app` or `live-operations-dashboard`). It scaffolds that recipe's page and private routes in dependency-free Node, each answering with a placeholder, and returns `recipe` with the example's docs id, its path in the Topline plugin and the steps still to do. Datasets, source bindings, secret bindings and Bedrock env are not declared; you add them from your own tables, sources and approved secrets. A starter works with the single shape only (`artifact_app_scaffold_starter_shape_conflict`); an unknown name returns `artifact_app_scaffold_starter_invalid` with the list.
13
+ - Topline's HTTP errors keep their code: the package reads it from the response body (for example `artifact_version_conflict`, `artifact_source_conflict`, `artifact_operation_pending`, `artifact_deploy_in_flight` or `artifact_logs_deployment_not_found`), gives each its own recovery step, and marks any 4xx as not retryable unchanged. A stale-version conflict was reported as a retryable 500 before.
14
+ - Generated structured tests (every shape and starter) are now labelled "Scaffold check:" with `evidence.scaffold: true`, so a starter's passing tests are not read as proof of the app's behavior.
15
+
5
16
  ## 0.9.3 - 2026-10-29
6
17
 
7
18
  - `platform_run_artifact_smoke` and `platform_read_artifact_logs` accept `target: "sandbox"` with `sessionId` and `sandboxId`, so an assistant can check and read the logs of its own running dev sandbox. Both go to Topline's hosted tools, and the sandbox smoke keeps its screenshot.
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Catalog-backed starters for platform_init_artifact_app.
3
+ *
4
+ * Each starter mirrors the route shape of one golden example in the Build
5
+ * cookbook (skills/build-topline-artifact-apps/examples/<id>/), so a new app
6
+ * starts with the recipe's page and private routes instead of a blank page.
7
+ * The scaffold is dependency-free Node and serves placeholder answers only:
8
+ * it never declares datasets, source bindings, secret bindings or Bedrock env,
9
+ * because those need the customer's own tables, sources and approved secrets.
10
+ * Its structured tests are labelled scaffold checks, not proof of behavior.
11
+ */
12
+ export type ArtifactStarterRoute = {
13
+ path: string;
14
+ method?: "GET" | "POST";
15
+ note: string;
16
+ };
17
+ export type ArtifactStarter = {
18
+ id: string;
19
+ kind: "tool" | "dashboard";
20
+ summary: string;
21
+ routes: ArtifactStarterRoute[];
22
+ /** What the recipe adds on top of the scaffold, in the order to do it. */
23
+ nextSteps: string[];
24
+ };
25
+ export declare const ARTIFACT_STARTERS: ArtifactStarter[];
26
+ export declare const ARTIFACT_STARTER_IDS: string[];
27
+ export declare function findArtifactStarter(id: string): ArtifactStarter | undefined;
28
+ export declare function artifactStarterRecipe(starter: ArtifactStarter): {
29
+ example: string;
30
+ summary: string;
31
+ docsId: string;
32
+ pluginPath: string;
33
+ nextSteps: string[];
34
+ };
35
+ /** Source for src/index.js: one handler serving the page and a placeholder per declared route. */
36
+ export declare function artifactStarterSource(starter: ArtifactStarter, title: string): string;
@@ -0,0 +1,170 @@
1
+ /**
2
+ * Catalog-backed starters for platform_init_artifact_app.
3
+ *
4
+ * Each starter mirrors the route shape of one golden example in the Build
5
+ * cookbook (skills/build-topline-artifact-apps/examples/<id>/), so a new app
6
+ * starts with the recipe's page and private routes instead of a blank page.
7
+ * The scaffold is dependency-free Node and serves placeholder answers only:
8
+ * it never declares datasets, source bindings, secret bindings or Bedrock env,
9
+ * because those need the customer's own tables, sources and approved secrets.
10
+ * Its structured tests are labelled scaffold checks, not proof of behavior.
11
+ */
12
+ export const ARTIFACT_STARTERS = [
13
+ {
14
+ id: "bounded-bedrock-assistant",
15
+ kind: "tool",
16
+ summary: "Private page plus one bounded server-side Converse call.",
17
+ routes: [
18
+ { path: "/_artifact/api/health", note: "Health check." },
19
+ { path: "/_artifact/api/openapi.json", note: "Describe the private API." },
20
+ { path: "/_artifact/api/chat", method: "POST", note: "One bounded model call; replace the placeholder reply." }
21
+ ],
22
+ nextSteps: [
23
+ "The recipe uses the python-api template; port its bounds (input size, max tokens, timeout) to this handler or keep Node.",
24
+ "Add PLATFORM_ARTIFACT_BEDROCK_MODEL_ID to env only once the app is allowed to call Bedrock."
25
+ ]
26
+ },
27
+ {
28
+ id: "cache-warmed-multi-source-dashboard",
29
+ kind: "dashboard",
30
+ summary: "Dashboard over a live dataset whose cache a schedule keeps warm.",
31
+ routes: [{ path: "/_artifact/data/branch-service-summary", note: "Placeholder for the recipe's live dataset." }],
32
+ nextSteps: [
33
+ "Find your own tables with the Workspace data catalog, then add the recipe's datasets[] and refreshSchedules[] with your SQL.",
34
+ "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
35
+ ]
36
+ },
37
+ {
38
+ id: "internal-action-tool",
39
+ kind: "tool",
40
+ summary: "Private work surface with one bounded, idempotent action.",
41
+ routes: [{ path: "/_artifact/api/actions/approve", method: "POST", note: "Bounded idempotent action; replace the placeholder." }],
42
+ nextSteps: [
43
+ "Bind an approved secret (list approved secret references first) as secretBindings[] and add its env name; never put a secret value in source.",
44
+ "Make the action idempotent with an idempotency key before it calls anything outside the app."
45
+ ]
46
+ },
47
+ {
48
+ id: "live-operations-dashboard",
49
+ kind: "dashboard",
50
+ summary: "Dashboard over two live datasets with stable IDs.",
51
+ routes: [
52
+ { path: "/_artifact/data/operations-by-branch", note: "Placeholder for the branch metrics dataset." },
53
+ { path: "/_artifact/data/open-work", note: "Placeholder for the oldest-open work dataset." }
54
+ ],
55
+ nextSteps: [
56
+ "Find your own tables with the Workspace data catalog, then add the recipe's two datasets[] with your SQL.",
57
+ "Replace the placeholder data handlers and their scaffold checks once the datasets serve the routes."
58
+ ]
59
+ },
60
+ {
61
+ id: "materialized-sql-data-product",
62
+ kind: "dashboard",
63
+ summary: "Dashboard over a relation someone else materializes.",
64
+ routes: [{ path: "/_artifact/data/service-health", note: "Placeholder for the materialized relation's dataset." }],
65
+ nextSteps: [
66
+ "Point a datasets[] entry at the existing materialized relation; the app never creates or refreshes it.",
67
+ "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
68
+ ]
69
+ },
70
+ {
71
+ id: "precomputed-s3-report",
72
+ kind: "dashboard",
73
+ summary: "Report over a precomputed dataset with declared warm parameters.",
74
+ routes: [{ path: "/_artifact/data/service-performance-report", note: "Placeholder for the precomputed report (windowDays 30 or 90)." }],
75
+ nextSteps: [
76
+ "Add the recipe's precomputed datasets[] entry (paramsSchema, warmParams) and its refresh schedule with your SQL.",
77
+ "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
78
+ ]
79
+ },
80
+ {
81
+ id: "private-api-first-app",
82
+ kind: "tool",
83
+ summary: "Deterministic private API under /_artifact/api/* with a docs page at /.",
84
+ routes: [
85
+ { path: "/_artifact/api/health", note: "Health check." },
86
+ { path: "/_artifact/api/openapi.json", note: "Describe the private API." },
87
+ { path: "/_artifact/api/validate-service-window", method: "POST", note: "Main deterministic endpoint; replace the placeholder." }
88
+ ],
89
+ nextSteps: ["The recipe uses the python-api template; keep this Node scaffold or port it, but keep every route under /_artifact/api/."]
90
+ },
91
+ {
92
+ id: "viewer-scoped-customer-portal",
93
+ kind: "dashboard",
94
+ summary: "Read-only portal where each viewer sees only their own rows.",
95
+ routes: [{ path: "/_artifact/data/customers", note: "Placeholder for the viewer-scoped source binding." }],
96
+ nextSteps: [
97
+ "Add the recipe's viewer-scoped sourceBindings[] entry for a source you already have, then switch viewerPolicy to tenant.",
98
+ "Keep viewerPolicy private until the binding filters every row to the signed-in viewer."
99
+ ]
100
+ }
101
+ ];
102
+ export const ARTIFACT_STARTER_IDS = ARTIFACT_STARTERS.map((starter) => starter.id);
103
+ export function findArtifactStarter(id) {
104
+ return ARTIFACT_STARTERS.find((starter) => starter.id === id);
105
+ }
106
+ export function artifactStarterRecipe(starter) {
107
+ return {
108
+ example: starter.id,
109
+ summary: starter.summary,
110
+ docsId: `build-cookbook-example-${starter.id}`,
111
+ pluginPath: `skills/build-topline-artifact-apps/examples/${starter.id}/EXAMPLE.md`,
112
+ nextSteps: starter.nextSteps
113
+ };
114
+ }
115
+ const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
116
+ /** Source for src/index.js: one handler serving the page and a placeholder per declared route. */
117
+ export function artifactStarterSource(starter, title) {
118
+ const safeTitle = escapeHtml(title);
119
+ const items = starter.routes
120
+ .map((route) => `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-route="${escapeHtml(route.path)}" data-method="${route.method ?? "GET"}">...</span></li>`)
121
+ .join("");
122
+ const page = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeTitle}</title></head><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Starter from the <code>${starter.id}</code> recipe. ${escapeHtml(starter.summary)}</p><ul>${items}</ul></main><script type="module">for (const el of document.querySelectorAll("[data-route]")) { const method = el.dataset.method; fetch("." + el.dataset.route, { method, headers: { "content-type": "application/json" }, body: method === "POST" ? "{}" : undefined }).then((r) => el.textContent = "answers " + r.status).catch(() => el.textContent = "not reachable"); }</script></body></html>`;
123
+ const routes = starter.routes.map((route) => ({ path: route.path, method: route.method ?? "GET" }));
124
+ const tests = [
125
+ { description: "Scaffold check: the page renders a visible app root.", required: true, status: "passed", summary: "Generated starter check; not proof of implemented behavior.", evidence: { selector: "data-platform-artifact-root", scaffold: true } },
126
+ ...starter.routes.map((route) => ({
127
+ description: `Scaffold check: ${route.method ?? "GET"} ${route.path} answers with a placeholder.`,
128
+ required: false,
129
+ status: "passed",
130
+ summary: "Generated starter check; replace it with a check of the real behavior.",
131
+ evidence: { route: route.path, scaffold: true }
132
+ }))
133
+ ];
134
+ return `import { mkdirSync, writeFileSync } from "node:fs";
135
+ import path from "node:path";
136
+
137
+ // Starter from the Build cookbook recipe "${starter.id}". Every route below
138
+ // returns a placeholder; follow the recipe to make each one real.
139
+ const page = ${JSON.stringify(page)};
140
+ const routes = ${JSON.stringify(routes)};
141
+
142
+ export function artifactApp(req, res) {
143
+ const url = new URL(req.url ?? "/", "http://artifact.local");
144
+ const route = routes.find((candidate) => url.pathname.endsWith(candidate.path));
145
+ if (!route) {
146
+ res.setHeader("content-type", "text/html; charset=utf-8");
147
+ res.end(page);
148
+ return;
149
+ }
150
+ res.setHeader("content-type", "application/json; charset=utf-8");
151
+ if ((req.method ?? "GET") !== route.method) {
152
+ res.statusCode = 405;
153
+ res.end(JSON.stringify({ error: "method_not_allowed", allowed: route.method }));
154
+ return;
155
+ }
156
+ res.end(JSON.stringify({ ok: true, placeholder: true, route: route.path, rows: [] }));
157
+ }
158
+
159
+ if (process.argv.includes("--build")) {
160
+ mkdirSync("dist", { recursive: true });
161
+ writeFileSync(path.join("dist", "index.html"), page, "utf8");
162
+ }
163
+
164
+ if (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {
165
+ console.log(JSON.stringify({ tests: ${JSON.stringify(tests)} }));
166
+ } else if (process.argv.includes("--build") || process.argv.includes("--test")) {
167
+ console.log("artifact app starter ok");
168
+ }
169
+ `;
170
+ }
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.3";
45
+ export declare const HARNESS_MCP_VERSION = "0.9.5";
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[];
@@ -234,6 +234,7 @@ export interface BuildMcpRecoveryGuidance {
234
234
  readonly recoveryAction: string;
235
235
  }
236
236
  export declare const BUILD_MCP_RECOVERY_ERRORS: Readonly<Record<string, BuildMcpRecoveryGuidance>>;
237
+ export declare function structuredToolError(message: string): CallToolResult;
237
238
  export declare function getBearerToken(opts: HarnessMcpStdioOptions): Promise<string>;
238
239
  export declare function browserOpenCommand(url: string, platform?: string): {
239
240
  command: string;
package/dist/index.js CHANGED
@@ -9,6 +9,7 @@ import path from "node:path";
9
9
  import { gzipSync } from "node:zlib";
10
10
  import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_TOOLS } from "./build-session-tools.js";
11
11
  import { domainHelperTools, DOMAIN_FORWARD_TOOLS, DOMAIN_ERROR_CODES } from "./domain-tools.js";
12
+ import { ARTIFACT_STARTER_IDS, artifactStarterRecipe, artifactStarterSource, findArtifactStarter } from "./artifact-starters.js";
12
13
  import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
13
14
  import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
14
15
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -18,7 +19,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
18
19
  export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
19
20
  const DEFAULT_TIMEOUT_MS = 120_000;
20
21
  export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
21
- export const HARNESS_MCP_VERSION = "0.9.3";
22
+ export const HARNESS_MCP_VERSION = "0.9.5";
22
23
  export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
23
24
  /** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
24
25
  export const TOPLINE_OAUTH_SCOPES = Object.freeze([
@@ -1367,6 +1368,12 @@ export async function initArtifactApp(opts, input) {
1367
1368
  if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
1368
1369
  throw new Error("artifact_app_scaffold_target_not_empty");
1369
1370
  const shape = optionalString(input, "shape") ?? "single";
1371
+ const starterId = optionalString(input, "starter");
1372
+ const starter = starterId ? findArtifactStarter(starterId) : undefined;
1373
+ if (starterId && !starter)
1374
+ throw new Error("artifact_app_scaffold_starter_invalid");
1375
+ if (starter && shape !== "single")
1376
+ throw new Error("artifact_app_scaffold_starter_shape_conflict");
1370
1377
  if (shape === "web-and-api")
1371
1378
  return initWebAndApiArtifactApp(opts, { appDir, absoluteAppDir, manifestId, title });
1372
1379
  if (shape !== "single")
@@ -1376,21 +1383,23 @@ export async function initArtifactApp(opts, input) {
1376
1383
  manifestVersion: 2,
1377
1384
  id: manifestId,
1378
1385
  title,
1379
- kind: "tool",
1386
+ kind: starter?.kind ?? "tool",
1380
1387
  runtime: { target: "aws_lambda_function_url", region: "us-west-2", entryPoint: "artifactApp" },
1381
1388
  build: { command: "node src/index.js --build", outputDir: "dist" },
1382
1389
  validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
1383
- routes: [
1384
- { path: "/", kind: "page", handler: "artifactApp" },
1385
- { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
1386
- ],
1390
+ routes: starter
1391
+ ? [{ path: "/", kind: "page", handler: "artifactApp" }, ...starter.routes.map((route) => ({ path: route.path, kind: "api", handler: "artifactApp" }))]
1392
+ : [
1393
+ { path: "/", kind: "page", handler: "artifactApp" },
1394
+ { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
1395
+ ],
1387
1396
  sourceBindings: [],
1388
1397
  env: ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"],
1389
1398
  viewerPolicy: "private"
1390
1399
  };
1391
1400
  const packageJson = { name: manifestId, private: true, type: "module", main: "src/index.js", scripts: { build: "node src/index.js --build", test: "node src/index.js --test" } };
1392
1401
  const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
1393
- const source = `import { mkdirSync, writeFileSync } from "node:fs";\nimport path from "node:path";\n\nconst page = ${JSON.stringify(`<!doctype html><html><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Ready.</p></main></body></html>`)};\n\nexport function artifactApp(_req, res) {\n res.setHeader("content-type", "text/html; charset=utf-8");\n res.end(page);\n}\n\nif (process.argv.includes("--build")) {\n mkdirSync("dist", { recursive: true });\n writeFileSync(path.join("dist", "index.html"), page, "utf8");\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "The artifact renders a visible app root.", required: true, status: "passed", summary: "The page includes data-platform-artifact-root.", evidence: { selector: "data-platform-artifact-root" } }] }));\n} else if (process.argv.includes("--build") || process.argv.includes("--test")) {\n console.log("artifact app template ok");\n}\n`;
1402
+ const source = starter ? artifactStarterSource(starter, title) : `import { mkdirSync, writeFileSync } from "node:fs";\nimport path from "node:path";\n\nconst page = ${JSON.stringify(`<!doctype html><html><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Ready.</p></main></body></html>`)};\n\nexport function artifactApp(_req, res) {\n res.setHeader("content-type", "text/html; charset=utf-8");\n res.end(page);\n}\n\nif (process.argv.includes("--build")) {\n mkdirSync("dist", { recursive: true });\n writeFileSync(path.join("dist", "index.html"), page, "utf8");\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "Scaffold check: the artifact renders a visible app root.", required: true, status: "passed", summary: "Generated starter check; not proof of implemented behavior.", evidence: { selector: "data-platform-artifact-root", scaffold: true } }] }));\n} else if (process.argv.includes("--build") || process.argv.includes("--test")) {\n console.log("artifact app template ok");\n}\n`;
1394
1403
  await Promise.all([
1395
1404
  writeFile(path.join(absoluteAppDir, "artifact-app.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" }),
1396
1405
  writeFile(path.join(absoluteAppDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, { flag: "wx" }),
@@ -1402,7 +1411,10 @@ export async function initArtifactApp(opts, input) {
1402
1411
  manifestId,
1403
1412
  title,
1404
1413
  files: ["artifact-app.json", "package.json", "src/index.js"],
1405
- nextAction: `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
1414
+ ...(starter ? { starter: starter.id, recipe: artifactStarterRecipe(starter) } : {}),
1415
+ nextAction: starter
1416
+ ? `Read the ${starter.id} recipe (docs id build-cookbook-example-${starter.id}) and replace each placeholder route. Its tests are scaffold checks, not proof of behavior. Then run npm test in ${appDir} and call platform_inspect_artifact_app with the same appDir before deployment.`
1417
+ : `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
1406
1418
  };
1407
1419
  }
1408
1420
  const ARTIFACT_APP_ENV = ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"];
@@ -1436,7 +1448,7 @@ async function initWebAndApiArtifactApp(opts, input) {
1436
1448
  const page = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeTitle}</title></head><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p id="message">Loading...</p></main><script type="module" src="./app.js"></script></body></html>`;
1437
1449
  const browserScript = `fetch("./_artifact/api/hello").then((response) => response.json()).then((body) => { document.getElementById("message").textContent = body.message; }).catch(() => { document.getElementById("message").textContent = "The API is not reachable yet."; });\n`;
1438
1450
  const webBuild = `import { mkdirSync, writeFileSync } from "node:fs";\n\n// Asset URLs stay relative so the same files work on the draft, live, and version addresses.\nmkdirSync("dist", { recursive: true });\nwriteFileSync("dist/index.html", ${JSON.stringify(page)}, "utf8");\nwriteFileSync("dist/app.js", ${JSON.stringify(browserScript)}, "utf8");\nconsole.log("web build ok");\n`;
1439
- const apiSource = `export function artifactApp(req, res) {\n const url = new URL(req.url ?? "/", "http://artifact.local");\n res.setHeader("content-type", "application/json; charset=utf-8");\n if (url.pathname.endsWith("/_artifact/api/health")) {\n res.end(JSON.stringify({ ok: true, part: process.env.PLATFORM_ARTIFACT_PART ?? null }));\n return;\n }\n if (url.pathname.endsWith("/_artifact/api/hello")) {\n res.end(JSON.stringify({ ok: true, message: "Hello from the api part. Replace this endpoint with your API." }));\n return;\n }\n res.statusCode = 404;\n res.end(JSON.stringify({ error: "not_found" }));\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "The api part answers its hello route.", required: true, status: "passed", summary: "artifactApp handles /_artifact/api/hello." }] }));\n} else if (process.argv.includes("--test")) {\n console.log("api part ok");\n}\n`;
1451
+ const apiSource = `export function artifactApp(req, res) {\n const url = new URL(req.url ?? "/", "http://artifact.local");\n res.setHeader("content-type", "application/json; charset=utf-8");\n if (url.pathname.endsWith("/_artifact/api/health")) {\n res.end(JSON.stringify({ ok: true, part: process.env.PLATFORM_ARTIFACT_PART ?? null }));\n return;\n }\n if (url.pathname.endsWith("/_artifact/api/hello")) {\n res.end(JSON.stringify({ ok: true, message: "Hello from the api part. Replace this endpoint with your API." }));\n return;\n }\n res.statusCode = 404;\n res.end(JSON.stringify({ error: "not_found" }));\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n console.log(JSON.stringify({ tests: [{ description: "Scaffold check: the api part answers its hello route.", required: true, status: "passed", summary: "Generated starter check; not proof of implemented behavior.", evidence: { scaffold: true } }] }));\n} else if (process.argv.includes("--test")) {\n console.log("api part ok");\n}\n`;
1440
1452
  const files = [
1441
1453
  ["artifact-app.json", `${JSON.stringify(manifest, null, 2)}\n`],
1442
1454
  ["web/package.json", `${JSON.stringify(webPackage, null, 2)}\n`],
@@ -1877,6 +1889,11 @@ const BUILD_MCP_TOOLS = [
1877
1889
  type: "string",
1878
1890
  enum: ["single", "web-and-api"],
1879
1891
  description: "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
1892
+ },
1893
+ starter: {
1894
+ type: "string",
1895
+ enum: ARTIFACT_STARTER_IDS,
1896
+ description: "Optional Build cookbook example to start from (single shape only). Scaffolds the recipe's page and private routes with placeholder answers and scaffold-labelled checks, and returns the recipe to follow. Datasets, source bindings and secrets are left for you to add from your own data."
1880
1897
  }
1881
1898
  },
1882
1899
  required: ["appDir"],
@@ -1884,7 +1901,16 @@ const BUILD_MCP_TOOLS = [
1884
1901
  },
1885
1902
  outputSchema: {
1886
1903
  type: "object",
1887
- properties: { ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } },
1904
+ properties: {
1905
+ ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } },
1906
+ starter: { type: "string" },
1907
+ recipe: {
1908
+ type: "object",
1909
+ properties: { example: { type: "string" }, summary: { type: "string" }, docsId: { type: "string" }, pluginPath: { type: "string" }, nextSteps: { type: "array", items: { type: "string" } } },
1910
+ required: ["example", "summary", "docsId", "pluginPath", "nextSteps"]
1911
+ },
1912
+ nextAction: { type: "string" }
1913
+ },
1888
1914
  required: ["ok", "appDir", "manifestId", "title", "files", "nextAction"]
1889
1915
  }
1890
1916
  },
@@ -2336,12 +2362,24 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2336
2362
  artifact_app_manifest_too_large: { retryable: false, recoveryAction: "Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again." },
2337
2363
  scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
2338
2364
  artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." },
2339
- artifact_app_scaffold_shape_invalid: { retryable: false, recoveryAction: "Use shape single or web-and-api." }
2365
+ artifact_app_scaffold_shape_invalid: { retryable: false, recoveryAction: "Use shape single or web-and-api." },
2366
+ artifact_app_scaffold_starter_invalid: { retryable: false, recoveryAction: `Use one of the starters: ${ARTIFACT_STARTER_IDS.join(", ")}.` },
2367
+ artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
2368
+ // Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
2369
+ artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash." },
2370
+ 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." },
2371
+ 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." },
2372
+ 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)." },
2373
+ 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." }
2340
2374
  };
2341
2375
  export const BUILD_MCP_RECOVERY_ERRORS = Object.freeze(Object.fromEntries(Object.entries(BUILD_MCP_RECOVERY_ERROR_VALUES).map(([code, guidance]) => [code, Object.freeze(guidance)])));
2342
- function structuredToolError(message) {
2376
+ export function structuredToolError(message) {
2343
2377
  const code = recoveryErrorCode(message);
2344
- const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: "Inspect the code and message, correct the input if needed, then retry the same tool." };
2378
+ // A 4xx means the same request will be refused again; only 5xx, timeouts and rate limits are worth retrying unchanged.
2379
+ const retryable = /^platform_harness_http_error:5|timeout|rate_limited|unavailable|internal_error/.test(message);
2380
+ const selected = BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
2381
+ ? "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."
2382
+ : "Inspect the code and message, correct the input if needed, then retry the same tool." };
2345
2383
  const structuredContent = { ok: false, error: { code, message, ...selected } };
2346
2384
  return {
2347
2385
  content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
@@ -2356,7 +2394,7 @@ function hostedToolErrorCode(inner) {
2356
2394
  if (isRecord(parsed)) {
2357
2395
  const error = parsed.error;
2358
2396
  const code = isRecord(error) ? error.code : typeof error === "string" ? error : parsed.code;
2359
- if (typeof code === "string" && /^[a-z][a-z0-9_]{2,}$/.test(code))
2397
+ if (typeof code === "string" && /^[a-z][A-Za-z0-9_]{2,}$/.test(code))
2360
2398
  return code;
2361
2399
  }
2362
2400
  }
@@ -2365,7 +2403,8 @@ function hostedToolErrorCode(inner) {
2365
2403
  }
2366
2404
  // Only a code-shaped token (it has an underscore): plain English such as
2367
2405
  // "missing scope ..." or "not found" is a message, not a code.
2368
- return inner.match(/^([a-z][a-z0-9]*_[a-z0-9_]+)(?::|$|\s)/)?.[1] ?? null;
2406
+ // Documentation codes can be camelCase in part (`workspace_table_displayName_too_short`).
2407
+ return inner.match(/^([a-z][A-Za-z0-9]*_[A-Za-z0-9_]+)(?::|$|\s)/)?.[1] ?? null;
2369
2408
  }
2370
2409
  function recoveryErrorCode(message) {
2371
2410
  if (/^platform_harness_http_error:401(?::|$)/.test(message))
@@ -2377,11 +2416,30 @@ function recoveryErrorCode(message) {
2377
2416
  }
2378
2417
  if (DOMAIN_ERROR_CODES.has(message) || message === "domain_result_unknown")
2379
2418
  return message;
2419
+ // Topline's HTTP error body names its code (`{"ok":false,"error":"artifact_version_conflict"}`); use it.
2420
+ const http = /^platform_harness_http_error:(\d{3}):(.*)$/s.exec(message);
2421
+ if (http) {
2422
+ let inner = hostedToolErrorCode(http[2].trim());
2423
+ if (!inner) {
2424
+ // An error string can carry a suffix (`artifact_logs_deployment_not_found:draft`).
2425
+ try {
2426
+ const body = JSON.parse(http[2]);
2427
+ inner = typeof body.error === "string" ? body.error.match(/^([a-z][a-z0-9_]{2,})(?::|$)/)?.[1] ?? null : null;
2428
+ }
2429
+ catch {
2430
+ inner = null;
2431
+ }
2432
+ }
2433
+ if (inner && BUILD_MCP_RECOVERY_ERRORS[inner])
2434
+ return inner;
2435
+ }
2380
2436
  const known = [
2381
2437
  "artifact_delete_plan_stale",
2382
2438
  "artifact_deploy_wait_timeout",
2383
2439
  "artifact_app_scaffold_target_not_empty",
2384
2440
  "artifact_app_scaffold_shape_invalid",
2441
+ "artifact_app_scaffold_starter_invalid",
2442
+ "artifact_app_scaffold_starter_shape_conflict",
2385
2443
  "platform_harness_timeout",
2386
2444
  // Before the generic wrapper, which every hosted error message starts with.
2387
2445
  "scope_required",
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.9.3",
5
+ "version": "0.9.5",
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.3"
15
+ "version": "0.9.5"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -434,6 +434,41 @@
434
434
  "code": "artifact_app_scaffold_shape_invalid",
435
435
  "retryable": false,
436
436
  "recoveryAction": "Use shape single or web-and-api."
437
+ },
438
+ {
439
+ "code": "artifact_app_scaffold_starter_invalid",
440
+ "retryable": false,
441
+ "recoveryAction": "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."
442
+ },
443
+ {
444
+ "code": "artifact_app_scaffold_starter_shape_conflict",
445
+ "retryable": false,
446
+ "recoveryAction": "A starter scaffolds the single shape; leave shape out or set it to single."
447
+ },
448
+ {
449
+ "code": "artifact_version_conflict",
450
+ "retryable": false,
451
+ "recoveryAction": "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash."
452
+ },
453
+ {
454
+ "code": "artifact_source_conflict",
455
+ "retryable": false,
456
+ "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."
457
+ },
458
+ {
459
+ "code": "artifact_operation_pending",
460
+ "retryable": false,
461
+ "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."
462
+ },
463
+ {
464
+ "code": "artifact_deploy_in_flight",
465
+ "retryable": true,
466
+ "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)."
467
+ },
468
+ {
469
+ "code": "artifact_logs_deployment_not_found",
470
+ "retryable": false,
471
+ "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."
437
472
  }
438
473
  ]
439
474
  },
@@ -667,6 +702,20 @@
667
702
  "web-and-api"
668
703
  ],
669
704
  "description": "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
705
+ },
706
+ "starter": {
707
+ "type": "string",
708
+ "enum": [
709
+ "bounded-bedrock-assistant",
710
+ "cache-warmed-multi-source-dashboard",
711
+ "internal-action-tool",
712
+ "live-operations-dashboard",
713
+ "materialized-sql-data-product",
714
+ "precomputed-s3-report",
715
+ "private-api-first-app",
716
+ "viewer-scoped-customer-portal"
717
+ ],
718
+ "description": "Optional Build cookbook example to start from (single shape only). Scaffolds the recipe's page and private routes with placeholder answers and scaffold-labelled checks, and returns the recipe to follow. Datasets, source bindings and secrets are left for you to add from your own data."
670
719
  }
671
720
  },
672
721
  "required": [
@@ -698,6 +747,39 @@
698
747
  "type": "string"
699
748
  }
700
749
  },
750
+ "starter": {
751
+ "type": "string"
752
+ },
753
+ "recipe": {
754
+ "type": "object",
755
+ "properties": {
756
+ "example": {
757
+ "type": "string"
758
+ },
759
+ "summary": {
760
+ "type": "string"
761
+ },
762
+ "docsId": {
763
+ "type": "string"
764
+ },
765
+ "pluginPath": {
766
+ "type": "string"
767
+ },
768
+ "nextSteps": {
769
+ "type": "array",
770
+ "items": {
771
+ "type": "string"
772
+ }
773
+ }
774
+ },
775
+ "required": [
776
+ "example",
777
+ "summary",
778
+ "docsId",
779
+ "pluginPath",
780
+ "nextSteps"
781
+ ]
782
+ },
701
783
  "nextAction": {
702
784
  "type": "string"
703
785
  }
@@ -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.3`
5
+ Package: `@topline-build/harness-mcp@0.9.5`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -84,6 +84,13 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
84
84
  - `artifact_app_manifest_too_large` (not automatically retryable): Keep artifact-app.json below 512 KiB. Move application data and source into separate files, then inspect again.
85
85
  - `artifact_app_scaffold_target_not_empty` (not automatically retryable): Choose an empty appDir or deploy the existing app without scaffolding.
86
86
  - `artifact_app_scaffold_shape_invalid` (not automatically retryable): Use shape single or web-and-api.
87
+ - `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.
88
+ - `artifact_app_scaffold_starter_shape_conflict` (not automatically retryable): A starter scaffolds the single shape; leave shape out or set it to single.
89
+ - `artifact_version_conflict` (not automatically retryable): The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash.
90
+ - `artifact_source_conflict` (not automatically retryable): 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.
91
+ - `artifact_operation_pending` (not automatically retryable): 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.
92
+ - `artifact_deploy_in_flight` (retryable): 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).
93
+ - `artifact_logs_deployment_not_found` (not automatically retryable): 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.
87
94
 
88
95
  ## Tools
89
96
 
@@ -360,6 +367,20 @@ Input schema:
360
367
  "web-and-api"
361
368
  ],
362
369
  "description": "single (default): one app. web-and-api: one artifact with a static website part and an API part under one address; use it instead of two artifacts."
370
+ },
371
+ "starter": {
372
+ "type": "string",
373
+ "enum": [
374
+ "bounded-bedrock-assistant",
375
+ "cache-warmed-multi-source-dashboard",
376
+ "internal-action-tool",
377
+ "live-operations-dashboard",
378
+ "materialized-sql-data-product",
379
+ "precomputed-s3-report",
380
+ "private-api-first-app",
381
+ "viewer-scoped-customer-portal"
382
+ ],
383
+ "description": "Optional Build cookbook example to start from (single shape only). Scaffolds the recipe's page and private routes with placeholder answers and scaffold-labelled checks, and returns the recipe to follow. Datasets, source bindings and secrets are left for you to add from your own data."
363
384
  }
364
385
  },
365
386
  "required": [
@@ -396,6 +417,39 @@ Output schema:
396
417
  "type": "string"
397
418
  }
398
419
  },
420
+ "starter": {
421
+ "type": "string"
422
+ },
423
+ "recipe": {
424
+ "type": "object",
425
+ "properties": {
426
+ "example": {
427
+ "type": "string"
428
+ },
429
+ "summary": {
430
+ "type": "string"
431
+ },
432
+ "docsId": {
433
+ "type": "string"
434
+ },
435
+ "pluginPath": {
436
+ "type": "string"
437
+ },
438
+ "nextSteps": {
439
+ "type": "array",
440
+ "items": {
441
+ "type": "string"
442
+ }
443
+ }
444
+ },
445
+ "required": [
446
+ "example",
447
+ "summary",
448
+ "docsId",
449
+ "pluginPath",
450
+ "nextSteps"
451
+ ]
452
+ },
399
453
  "nextAction": {
400
454
  "type": "string"
401
455
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.9.3",
3
+ "version": "0.9.5",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",