@shippp/mcp 0.2.0 → 0.3.0

package/dist/index.js

@@ -18,7 +18,208 @@ function loadConfig() {
   return { apiUrl, apiKey };
 }
 
+// ../../src/lib/repoSync/wireReceipt.ts
+import { createHash } from "node:crypto";
+import { z as z2 } from "zod";
+
+// ../../src/lib/repoSync/receiptContract.ts
+import { z } from "zod";
+var hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+var receiptFileEntrySchema = z.object({
+  path: z.string().min(1),
+  hash,
+  bytes: z.number().int().nonnegative()
+});
+var syncReceiptSchema = z.object({
+  shippp_receipt: z.literal("v2"),
+  // `revision`/`versionId`: MC-9.2 kompatibilis bővítés — hiányuk a bővítés
+  // előtti receipt érvényes olvasata; a zod-objektum strippelne, ezért a
+  // mezők itt is deklaráltak, hogy a repóba írt receipt megőrizze őket.
+  source: z.object({
+    file: z.string(),
+    unit: z.string(),
+    version: hash,
+    revision: z.number().int().nullable().optional(),
+    versionId: z.string().optional()
+  }),
+  target: z.object({
+    outputProfile: z.string().min(1),
+    profileSchemaVersion: z.number().int().positive(),
+    adapterVersion: z.string().min(1),
+    packagerVersion: z.string().min(1),
+    packages: z.object({
+      dependencies: z.record(z.string(), z.string()),
+      devDependencies: z.record(z.string(), z.string())
+    })
+  }),
+  config: z.object({ engine: z.string().min(1), irVersion: z.string().min(1), tokens: hash }),
+  output: z.object({ hash, files: z.array(receiptFileEntrySchema) }),
+  reproducible: z.literal(true),
+  generated_at: z.string()
+});
+var ReceiptParseError = class extends Error {
+};
+function parseSyncReceipt(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new ReceiptParseError("A receipt nem \xE9rv\xE9nyes JSON.");
+  }
+  const parsed = syncReceiptSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new ReceiptParseError(
+      `A receipt nem felel meg a v2 kontraktusnak: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return parsed.data;
+}
+function serializeSyncReceipt(receipt) {
+  return `${JSON.stringify(receipt, null, 2)}
+`;
+}
+var compilerEnvOfReceipt = (r) => ({
+  engine: r.config.engine,
+  irVersion: r.config.irVersion,
+  adapterVersion: r.target.adapterVersion,
+  packagerVersion: r.target.packagerVersion
+});
+function compilerDeltaOf(previous, next) {
+  const delta = [];
+  if (previous.config.engine !== next.engine) delta.push(`engine: ${previous.config.engine} \u2192 ${next.engine}`);
+  if (previous.config.irVersion !== next.irVersion) delta.push(`IR: ${previous.config.irVersion} \u2192 ${next.irVersion}`);
+  if (previous.target.adapterVersion !== next.adapterVersion) {
+    delta.push(`adapter: ${previous.target.adapterVersion} \u2192 ${next.adapterVersion}`);
+  }
+  if (previous.target.packagerVersion !== next.packagerVersion) {
+    delta.push(`packager: ${previous.target.packagerVersion} \u2192 ${next.packagerVersion}`);
+  }
+  return delta;
+}
+
+// ../../src/lib/repoSync/wireReceipt.ts
+var wireReceiptRefEntrySchema = z2.object({
+  path: z2.string().min(1),
+  bytes: z2.number().int().nonnegative(),
+  ref: z2.object({ uploadId: z2.string().min(1) })
+});
+var wireReceiptOutputEntrySchema = z2.union([receiptFileEntrySchema, wireReceiptRefEntrySchema]);
+var wireSyncReceiptSchema = syncReceiptSchema.extend({
+  output: z2.object({ hash, files: z2.array(wireReceiptOutputEntrySchema) })
+});
+var WireReceiptError = class extends Error {
+};
+function parseWireSyncReceipt(raw) {
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new WireReceiptError("A wire-receipt nem \xE9rv\xE9nyes JSON.");
+  }
+  const parsed = wireSyncReceiptSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new WireReceiptError(
+      `A wire-receipt nem felel meg a v2 kontraktusnak: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return parsed.data;
+}
+var sha = (s) => `sha256:${createHash("sha256").update(s).digest("hex")}`;
+function outputCanonicalOf(entries) {
+  return [...entries].sort((a, b) => a.path.localeCompare(b.path)).map((e) => "ref" in e ? `${e.path}\0ref:${e.ref.uploadId}:${e.bytes}` : `${e.path}\0${e.hash}`).join("\0");
+}
+function outputHashOfEntries(entries) {
+  return sha(outputCanonicalOf(entries));
+}
+function completeWireReceipt(wire, bytesByPath) {
+  const files = wire.output.files.map((entry) => {
+    if (!("ref" in entry)) return entry;
+    const bytes = bytesByPath.get(entry.path);
+    if (!bytes) {
+      throw new WireReceiptError(`A wire-receipt ref-sora feloldatlan maradt: ${entry.path} (${entry.ref.uploadId}).`);
+    }
+    if (bytes.byteLength !== entry.bytes) {
+      throw new WireReceiptError(
+        `A feloldott asset m\xE9rete nem egyezik a receipt kontraktus\xE1val: ${entry.path} \u2014 v\xE1rt ${entry.bytes}, kapott ${bytes.byteLength} b\xE1jt.`
+      );
+    }
+    return { path: entry.path, hash: sha(bytes), bytes: bytes.byteLength };
+  });
+  const completed = { ...wire, output: { hash: outputHashOfEntries(files), files } };
+  const parsed = syncReceiptSchema.safeParse(completed);
+  if (!parsed.success) {
+    throw new WireReceiptError(
+      `A kieg\xE9sz\xEDtett receipt nem felel meg a sync-kontraktusnak: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return parsed.data;
+}
+
+// ../../src/lib/repoSync/exportArtifactContract.ts
+var ExportArtifactContractError = class extends Error {
+};
+function bytesOfBase64(b64) {
+  if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const binary = atob(b64);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function inlineFileOf(entry) {
+  if (typeof entry.path !== "string" || typeof entry.content !== "string") {
+    throw new ExportArtifactContractError("The export artifact container has a malformed file row.");
+  }
+  return entry.encoding === "base64" ? { path: entry.path, content: bytesOfBase64(entry.content) } : { path: entry.path, content: entry.content };
+}
+function refOf(entry) {
+  const ref = entry.ref;
+  if (typeof entry.path !== "string" || !ref || typeof ref.uploadId !== "string" || typeof ref.downloadPath !== "string" || typeof ref.bytes !== "number" || !Number.isFinite(ref.bytes) || ref.bytes < 0) {
+    throw new ExportArtifactContractError("The export artifact container has a malformed asset-reference row.");
+  }
+  return {
+    path: entry.path,
+    uploadId: ref.uploadId,
+    downloadPath: ref.downloadPath,
+    bytes: ref.bytes,
+    contentType: typeof ref.contentType === "string" ? ref.contentType : null
+  };
+}
+function parseExportArtifactJson(json) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new ExportArtifactContractError("The export artifact container is not valid JSON.");
+  }
+  const container = parsed;
+  const version = container.shippp_artifact;
+  if (version !== "v1" && version !== "v2" || !Array.isArray(container.files)) {
+    throw new ExportArtifactContractError(
+      `Unknown export artifact container shape (shippp_artifact: ${JSON.stringify(version ?? null)}) \u2014 this reader supports v1 and v2.`
+    );
+  }
+  const files = [];
+  const refs = [];
+  for (const raw of container.files) {
+    if (raw?.encoding === "ref") {
+      if (version === "v1") {
+        throw new ExportArtifactContractError("A v1 export artifact container cannot carry asset-reference rows.");
+      }
+      refs.push(refOf(raw));
+      continue;
+    }
+    files.push(inlineFileOf(raw ?? {}));
+  }
+  return { version, files, refs };
+}
+
 // src/client.ts
+var REQUEST_TIMEOUT_MS = 6e4;
+var GENERATE_TIMEOUT_MS = 12e4;
+var ASSET_FETCH_TIMEOUT_MS = 18e4;
+var ASSET_FETCH_CONCURRENCY = 4;
 var ShipppApiError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -26,20 +227,16 @@ var ShipppApiError = class extends Error {
     this.name = "ShipppApiError";
   }
 };
-function decodeFiles(files) {
-  return files.map(
-    (f) => f.encoding === "base64" ? { path: f.path, content: new Uint8Array(Buffer.from(f.content, "base64")) } : { path: f.path, content: f.content }
-  );
-}
 var ShipppClient = class {
   constructor(config) {
     this.config = config;
   }
-  async request(path2, init) {
+  async request(path2, init, timeoutMs = REQUEST_TIMEOUT_MS) {
     let res;
     try {
       res = await fetch(`${this.config.apiUrl}${path2}`, {
         ...init,
+        signal: AbortSignal.timeout(timeoutMs),
         headers: {
           Authorization: `Bearer ${this.config.apiKey}`,
           "Content-Type": "application/json",
@@ -47,7 +244,11 @@ var ShipppClient = class {
         }
       });
     } catch (e) {
-      throw new ShipppApiError(0, `Could not reach Shippp at ${this.config.apiUrl}: ${e.message}`);
+      const err = e;
+      if (err.name === "TimeoutError") {
+        throw new ShipppApiError(0, `Shippp did not answer ${path2} within ${Math.round(timeoutMs / 1e3)}s.`);
+      }
+      throw new ShipppApiError(0, `Could not reach Shippp at ${this.config.apiUrl}: ${err.message}`);
     }
     const body = await res.json().catch(() => ({}));
     if (!res.ok) throw new ShipppApiError(res.status, body?.error || `HTTP ${res.status}`);
@@ -57,42 +258,98 @@ var ShipppClient = class {
   manifest(fileId2) {
     return this.request(`/api/mcp/manifest?fileId=${encodeURIComponent(fileId2)}`, { method: "GET" });
   }
-  /** Generate code for a unit (or a diff against a baseline). */
+  /** Resolves the versioned (v2) asset references of a generate response:
+   * each referenced binary is fetched from its authorized download path with
+   * the same Bearer credential, under bounded parallelism and a per-asset
+   * deadline, and must match the reference's byte size exactly — a partial
+   * result is never a success; the failure names every affected asset. */
+  async downloadAssetRefs(refs) {
+    const out = /* @__PURE__ */ new Map();
+    const failures = [];
+    let next = 0;
+    const worker = async () => {
+      for (; ; ) {
+        const i = next++;
+        if (i >= refs.length) return;
+        const ref = refs[i];
+        try {
+          const res = await fetch(`${this.config.apiUrl}${ref.downloadPath}`, {
+            headers: { Authorization: `Bearer ${this.config.apiKey}` },
+            signal: AbortSignal.timeout(ASSET_FETCH_TIMEOUT_MS)
+          });
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const bytes = new Uint8Array(await res.arrayBuffer());
+          if (bytes.byteLength !== ref.bytes) {
+            throw new Error(`size mismatch: expected ${ref.bytes} bytes, got ${bytes.byteLength}`);
+          }
+          out.set(ref.path, bytes);
+        } catch (e) {
+          const err = e;
+          failures.push(`${ref.path} (${err.name === "TimeoutError" ? "timed out" : err.message})`);
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(ASSET_FETCH_CONCURRENCY, refs.length) }, worker));
+    if (failures.length > 0) {
+      throw new ShipppApiError(
+        0,
+        `Failed to download ${failures.length} of ${refs.length} referenced export assets: ${failures.join("; ")}`
+      );
+    }
+    return out;
+  }
+  /** Generate code for a unit (or a diff against a baseline). This client
+   * declares the versioned asset-reference capability (artifact contract v2):
+   * above the server's inline budget the image mass arrives as authorized
+   * download references, which are resolved here into byte-complete files and
+   * a hash-complete receipt — identical to what an inline delivery would have
+   * produced, so the sync core and every consumer see one artifact shape. */
   async generate(fileId2, request, baseline) {
     const body = await this.request(
       "/api/mcp/generate",
       {
         method: "POST",
-        body: JSON.stringify(baseline ? { fileId: fileId2, request, baseline } : { fileId: fileId2, request })
-      }
+        body: JSON.stringify(
+          baseline ? { fileId: fileId2, request, baseline, acceptAssetRefs: true } : { fileId: fileId2, request, acceptAssetRefs: true }
+        )
+      },
+      GENERATE_TIMEOUT_MS
     );
-    if ("files" in body) return { ...body, files: decodeFiles(body.files) };
-    return body;
+    if (!("files" in body)) return body;
+    const { shippp_artifact, files: rawFiles, receipt: rawReceipt, ...rest } = body;
+    const parsed = parseExportArtifactJson(JSON.stringify({ shippp_artifact: shippp_artifact ?? "v1", files: rawFiles }));
+    if (parsed.refs.length === 0) {
+      return { ...rest, files: parsed.files, receipt: rawReceipt };
+    }
+    const bytesByPath = await this.downloadAssetRefs(parsed.refs);
+    const receipt = completeWireReceipt(parseWireSyncReceipt(JSON.stringify(rawReceipt)), bytesByPath);
+    const resolved = parsed.refs.map((r) => ({ path: r.path, content: bytesByPath.get(r.path) }));
+    return { ...rest, files: [...parsed.files, ...resolved], receipt };
   }
 };
 
 // src/tools.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/runner.ts
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 
 // ../../src/lib/repoSync/applySync.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 
 // ../../src/lib/repoSync/targetConfig.ts
-import { z } from "zod";
+import { z as z3 } from "zod";
 var TARGET_CONFIG_PATH = "shippp.target.json";
 var TARGET_CONFIG_SCHEMA_VERSION = 1;
 var DEFAULT_SYNC_UNIT = "project";
-var targetConfigSchema = z.object({
-  schemaVersion: z.literal(TARGET_CONFIG_SCHEMA_VERSION),
-  profile: z.string().min(1),
-  profileSchemaVersion: z.number().int().positive(),
-  generatedRoot: z.string().min(1),
-  project: z.object({ fileId: z.string().min(1), name: z.string().min(1) }).optional(),
-  unit: z.enum(["project", "design-system"]).optional()
+var targetConfigSchema = z3.object({
+  schemaVersion: z3.literal(TARGET_CONFIG_SCHEMA_VERSION),
+  profile: z3.string().min(1),
+  profileSchemaVersion: z3.number().int().positive(),
+  generatedRoot: z3.string().min(1),
+  project: z3.object({ fileId: z3.string().min(1), name: z3.string().min(1) }).optional(),
+  unit: z3.enum(["project", "design-system"]).optional()
 });
 var TargetConfigError = class extends Error {
 };
@@ -120,72 +377,6 @@ function parseTargetConfig(raw) {
   return parsed.data;
 }
 
-// ../../src/lib/repoSync/receiptContract.ts
-import { z as z2 } from "zod";
-var hash = z2.string().regex(/^sha256:[0-9a-f]{64}$/);
-var receiptFileEntrySchema = z2.object({
-  path: z2.string().min(1),
-  hash,
-  bytes: z2.number().int().nonnegative()
-});
-var syncReceiptSchema = z2.object({
-  shippp_receipt: z2.literal("v2"),
-  source: z2.object({ file: z2.string(), unit: z2.string(), version: hash }),
-  target: z2.object({
-    outputProfile: z2.string().min(1),
-    profileSchemaVersion: z2.number().int().positive(),
-    adapterVersion: z2.string().min(1),
-    packagerVersion: z2.string().min(1),
-    packages: z2.object({
-      dependencies: z2.record(z2.string(), z2.string()),
-      devDependencies: z2.record(z2.string(), z2.string())
-    })
-  }),
-  config: z2.object({ engine: z2.string().min(1), irVersion: z2.string().min(1), tokens: hash }),
-  output: z2.object({ hash, files: z2.array(receiptFileEntrySchema) }),
-  reproducible: z2.literal(true),
-  generated_at: z2.string()
-});
-var ReceiptParseError = class extends Error {
-};
-function parseSyncReceipt(raw) {
-  let json;
-  try {
-    json = JSON.parse(raw);
-  } catch {
-    throw new ReceiptParseError("A receipt nem \xE9rv\xE9nyes JSON.");
-  }
-  const parsed = syncReceiptSchema.safeParse(json);
-  if (!parsed.success) {
-    throw new ReceiptParseError(
-      `A receipt nem felel meg a v2 kontraktusnak: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
-    );
-  }
-  return parsed.data;
-}
-function serializeSyncReceipt(receipt) {
-  return `${JSON.stringify(receipt, null, 2)}
-`;
-}
-var compilerEnvOfReceipt = (r) => ({
-  engine: r.config.engine,
-  irVersion: r.config.irVersion,
-  adapterVersion: r.target.adapterVersion,
-  packagerVersion: r.target.packagerVersion
-});
-function compilerDeltaOf(previous, next) {
-  const delta = [];
-  if (previous.config.engine !== next.engine) delta.push(`engine: ${previous.config.engine} \u2192 ${next.engine}`);
-  if (previous.config.irVersion !== next.irVersion) delta.push(`IR: ${previous.config.irVersion} \u2192 ${next.irVersion}`);
-  if (previous.target.adapterVersion !== next.adapterVersion) {
-    delta.push(`adapter: ${previous.target.adapterVersion} \u2192 ${next.adapterVersion}`);
-  }
-  if (previous.target.packagerVersion !== next.packagerVersion) {
-    delta.push(`packager: ${previous.target.packagerVersion} \u2192 ${next.packagerVersion}`);
-  }
-  return delta;
-}
-
 // ../../src/lib/repoSync/syncPlan.ts
 function computeSyncPlan(input) {
   const entries = [];
@@ -234,7 +425,7 @@ function computeSyncPlan(input) {
 
 // ../../src/lib/repoSync/applySync.ts
 var RECEIPT_FILENAME = "shippp.receipt.json";
-var sha256 = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+var sha256 = (content) => `sha256:${createHash2("sha256").update(content).digest("hex")}`;
 var refusal = (code, message, conflicts) => ({
   status: "refused",
   code,
@@ -588,7 +779,7 @@ ${changed}
 --- RECEIPT ---
 ${JSON.stringify(result.receipt, null, 2)}`;
 }
-var fileId = z3.string().min(1).describe("The Shippp file id (from the file's URL, or shippp_list_units).");
+var fileId = z4.string().min(1).describe("The Shippp file id (from the file's URL, or shippp_list_units).");
 function registerTools(server, client) {
   server.registerTool(
     "shippp_list_units",
@@ -613,8 +804,8 @@ function registerTools(server, client) {
       description: "Get ONE component's deterministic Chakra UI code + a reproducibility receipt. `unitType` is 'master' (a design-system component) or 'screen' (a depth-0 artboard). Get ids from shippp_list_units.",
       inputSchema: {
         fileId,
-        unitId: z3.string().min(1).describe("The master/screen id from shippp_list_units."),
-        unitType: z3.enum(["master", "screen"])
+        unitId: z4.string().min(1).describe("The master/screen id from shippp_list_units."),
+        unitType: z4.enum(["master", "screen"])
       }
     },
     async ({ fileId: fileId2, unitId, unitType }) => {
@@ -677,10 +868,10 @@ function registerTools(server, client) {
       description: "Diff your CURRENT code against a fresh deterministic generation of a unit \u2014 shows exactly what a designer changed. Pass the same unit params as the get tools, plus `baseline` (the files you currently have for that unit).",
       inputSchema: {
         fileId,
-        unit: z3.enum(["tokens", "design-system", "project", "component"]),
-        unitId: z3.string().optional().describe("Required when unit='component'."),
-        unitType: z3.enum(["master", "screen"]).optional().describe("Required when unit='component'."),
-        baseline: z3.array(z3.object({ path: z3.string(), content: z3.string() })).describe("Your current files for this unit (path + content).")
+        unit: z4.enum(["tokens", "design-system", "project", "component"]),
+        unitId: z4.string().optional().describe("Required when unit='component'."),
+        unitType: z4.enum(["master", "screen"]).optional().describe("Required when unit='component'."),
+        baseline: z4.array(z4.object({ path: z4.string(), content: z4.string() })).describe("Your current files for this unit (path + content).")
       }
     },
     async ({ fileId: fileId2, unit, unitId, unitType, baseline }) => {
@@ -721,10 +912,10 @@ function registerTools(server, client) {
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: "Run the full repository sync with the bundled deterministic runner: fetch the bound unit's artifact, plan against the real on-disk state, apply atomically with rollback, run the repo's checks (SHIPPP_SYNC_CHECKS env), and write the receipt ONLY on full success. Writes are confined to the generated root of the repo's own binding; hand-modified generated files are structured conflicts and are never overwritten. If the plan or a refusal reports a compilerDelta, present it to the user and re-call with approvedCompilerDelta set to EXACTLY those lines ONLY after their explicit approval. After an approved re-bind, pass acceptReboundBaseline to adopt the previous binding's receipt as baseline.",
       inputSchema: {
-        approvedCompilerDelta: z3.array(z3.string().min(1).max(500)).max(20).optional().describe(
+        approvedCompilerDelta: z4.array(z4.string().min(1).max(500)).max(20).optional().describe(
           "The exact compilerDelta lines the user explicitly approved \u2014 a mismatch with the current delta refuses."
         ),
-        acceptReboundBaseline: z3.boolean().optional().describe("Explicit adoption of a previous binding's leftover receipt as hash baseline after a re-bind.")
+        acceptReboundBaseline: z4.boolean().optional().describe("Explicit adoption of a previous binding's leftover receipt as hash baseline after a re-bind.")
       }
     },
     async ({ approvedCompilerDelta, acceptReboundBaseline }) => {
@@ -801,7 +992,7 @@ async function main() {
     process.exit(1);
   }
   const config = loadConfig();
-  const server = new McpServer({ name: "shippp", version: "0.2.0" }, { instructions: INSTRUCTIONS });
+  const server = new McpServer({ name: "shippp", version: "0.3.0" }, { instructions: INSTRUCTIONS });
   registerTools(server, new ShipppClient(config));
   await server.connect(new StdioServerTransport());
   console.error(`[shippp-mcp] connected via stdio \u2192 ${config.apiUrl}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shippp/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "ai.shippp/mcp",
   "description": "Shippp MCP server + local sync runner — pull deterministic, production-perfect UI code from your Shippp design files, and keep your repository current over the receipt-tracked sync.",
   "type": "module",