@akairos/pipeline 0.20.1 → 0.21.0

package/cover-snapshot.ts

@@ -0,0 +1,2 @@
+export { createCoverSnapshot, validateCoverSnapshot } from "./src/cover-snapshot";
+export type { CoverSnapshot, CoverSnapshotInput } from "./src/cover-snapshot";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/pipeline",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -13,6 +13,7 @@
   "files": [
     "src/",
     "article-style.ts",
+    "cover-snapshot.ts",
     "ARTICLE-THEMES.md",
     "THIRD-PARTY-NOTICES.md"
   ],
@@ -29,12 +30,12 @@
   },
   "dependencies": {
     "@akairos/milkdown-article-plugins": "^0.1.6",
-    "@akairos/typeset-studio": "0.2.7",
+    "@akairos/myno": "0.3.2",
+    "@akairos/typeset-studio": "0.3.0",
     "@chenglou/pretext": "0.0.8",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",
-    "zod": "^4.4.2",
-    "@akairos/myno": "0.3.1"
+    "zod": "^4.4.2"
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^0.1.97",

package/src/commands/render.ts

@@ -256,6 +256,9 @@ Options:
 
   try {
   const imageRenderer = await resolveImageRenderer(config);
+  if (process.env.ZZHUB_PIPELINE_COVER_SNAPSHOT === "1" && imageRenderer.name !== "typeset-studio") {
+    throw new Error("Cover snapshot requires the Typeset Studio image renderer");
+  }
   reportProgress({ stage: "render.adapter", message: "开始生成图片" });
 
   const bodyImages = (

package/src/cover-snapshot.test.ts

@@ -0,0 +1,43 @@
+import { expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { createCanvas } from "@napi-rs/canvas";
+import { ARTICLE_COVER_FONT, DEFAULT_ARTICLE_COVER_CONTROLS } from "@akairos/typeset-studio/cover";
+import { createCoverSnapshot, validateCoverSnapshot } from "../cover-snapshot";
+
+function input() {
+  const canvas = createCanvas(1000, 1000);
+  canvas.getContext("2d").fillRect(0, 0, 1000, 1000);
+  const bytes = canvas.toBuffer("image/jpeg");
+  return {
+    id: "adca5060-0ef7-49fa-bfc5-567208a70494", revision: 1, name: "封面",
+    controls: { ...DEFAULT_ARTICLE_COVER_CONTROLS, backgroundColor: "#AABBCC" },
+    asset: { id: "3aebf96a-455f-4543-825a-ab425c1b53a3", sha256: createHash("sha256").update(bytes).digest("hex"), contentType: "image/jpeg", dataBase64: bytes.toString("base64") },
+    font: { id: ARTICLE_COVER_FONT.id, sha256: ARTICLE_COVER_FONT.sha256 },
+  };
+}
+
+test("封面快照复用 Typeset 控件与工厂，规范化并绑定修订/素材/字体身份", () => {
+  const fields = input();
+  const snapshot = createCoverSnapshot(fields);
+  expect(snapshot.controls.backgroundColor).toBe("#aabbcc");
+  expect(snapshot.config.images?.[0].src).toBe(`asset:${fields.asset.id}`);
+  expect(validateCoverSnapshot(JSON.parse(JSON.stringify(snapshot)))).toEqual(snapshot);
+  expect(createCoverSnapshot({ ...fields, revision: 2 }).hash).not.toBe(snapshot.hash);
+  expect(createCoverSnapshot(Object.fromEntries(Object.entries(fields).reverse())).hash).toBe(snapshot.hash);
+});
+
+test("封面快照拒绝任意配置、路径、字体、字节篡改和超范围输入", () => {
+  const fields = input();
+  const snapshot = createCoverSnapshot(fields);
+  for (const patch of [{ schemaVersion: 2 }, { revision: 0 }, { hash: "0".repeat(64) }, { path: "/private/image.jpg" }, { config: { ...snapshot.config, name: "改变配置" } }, { controls: { ...snapshot.controls, fontSize: 201 } }])
+    expect(() => validateCoverSnapshot({ ...snapshot, ...patch })).toThrow();
+  for (const patch of [
+    { id: "../template" }, { name: "x".repeat(81) }, { controls: { ...fields.controls, font: "serif" } },
+    { font: { ...fields.font, path: "/tmp/font.ttc" } }, { font: { ...fields.font, sha256: "0".repeat(64) } },
+    { asset: { ...fields.asset, sha256: "0".repeat(64) } }, { asset: { ...fields.asset, dataBase64: `${fields.asset.dataBase64}\n` } },
+    { asset: { ...fields.asset, dataBase64: Buffer.alloc(1_048_577).toString("base64") } },
+    { asset: { ...fields.asset, url: "https://example.test/image.jpg" } },
+  ]) expect(() => createCoverSnapshot({ ...fields, ...patch })).toThrow();
+  const bytes = createCanvas(10, 10).toBuffer("image/jpeg");
+  expect(() => createCoverSnapshot({ ...fields, asset: { ...fields.asset, sha256: createHash("sha256").update(bytes).digest("hex"), dataBase64: bytes.toString("base64") } })).toThrow("1000x1000");
+});

package/src/cover-snapshot.ts

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { imageSize } from "image-size";
+import { z } from "zod";
+import { ARTICLE_COVER_FONT, createArticleCoverConfig, validateArticleCoverControls, type ArticleCoverControls } from "@akairos/typeset-studio/cover";
+
+const identity = z.string().uuid().transform(value => value.toLowerCase());
+const sha256 = z.string().regex(/^[a-f\d]{64}$/);
+const SnapshotInputSchema = z.object({
+  id: identity,
+  revision: z.number().int().positive(),
+  name: z.string().trim().min(1).max(80),
+  controls: z.unknown(),
+  asset: z.object({
+    id: identity,
+    sha256,
+    contentType: z.literal("image/jpeg"),
+    dataBase64: z.string().min(4).max(1_398_104),
+  }).strict(),
+  font: z.object({ id: z.literal(ARTICLE_COVER_FONT.id), sha256: z.literal(ARTICLE_COVER_FONT.sha256) }).strict(),
+}).strict();
+
+export interface CoverSnapshot {
+  schemaVersion: 1;
+  id: string;
+  revision: number;
+  name: string;
+  controls: ArticleCoverControls;
+  config: ReturnType<typeof createArticleCoverConfig>;
+  asset: { id: string; sha256: string; contentType: "image/jpeg"; dataBase64: string };
+  font: { id: string; sha256: string };
+  hash: string;
+}
+
+export interface CoverSnapshotInput {
+  id: string;
+  revision: number;
+  name: string;
+  controls: ArticleCoverControls;
+  asset: CoverSnapshot["asset"];
+  font: CoverSnapshot["font"];
+}
+
+/** 单图只接收已规范化的不可变 JPEG 字节，不解析远程地址或调用方路径。 */
+export function createCoverSnapshot(value: unknown): CoverSnapshot {
+  const input = SnapshotInputSchema.parse(value);
+  const controls = validateArticleCoverControls(input.controls);
+  const bytes = Buffer.from(input.asset.dataBase64, "base64");
+  if (!bytes.length || bytes.length > 1_048_576 || bytes.toString("base64") !== input.asset.dataBase64)
+    throw new Error("Cover asset must be canonical base64 JPEG <= 1 MiB");
+  const image = imageSize(bytes);
+  if (image.type !== "jpg" || image.width !== 1000 || image.height !== 1000)
+    throw new Error("Cover asset must be a normalized 1000x1000 JPEG");
+  if (createHash("sha256").update(bytes).digest("hex") !== input.asset.sha256)
+    throw new Error("Cover asset hash mismatch");
+  const config = createArticleCoverConfig({ id: input.id, name: input.name, controls, assetId: input.asset.id });
+  const content = { schemaVersion: 1 as const, id: input.id, revision: input.revision, name: input.name, controls, config, asset: input.asset, font: input.font };
+  const hash = createHash("sha256").update(JSON.stringify(content)).digest("hex");
+  return { ...content, hash };
+}
+
+/** 配置只能由 Typeset 有限工厂生成；同 hash 不能夹带其他布局、素材或字体。 */
+export function validateCoverSnapshot(value: unknown): CoverSnapshot {
+  const input = SnapshotInputSchema.extend({ schemaVersion: z.literal(1), config: z.unknown(), hash: sha256 }).strict().parse(value);
+  const { schemaVersion: _, config, hash, ...fields } = input;
+  const snapshot = createCoverSnapshot(fields);
+  if (!isDeepStrictEqual(config, snapshot.config)) throw new Error("Cover config does not match canonical template");
+  if (hash !== snapshot.hash) throw new Error("Cover snapshot hash mismatch");
+  return snapshot;
+}