@petercjl/tuda 0.0.0-bootstrap.20261112 → 0.1.0

package/skills/using-tuda/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: using-tuda
+description: Use Tuda for image and video creation, editing, boards and assets only when the user explicitly invokes /using-tuda or $using-tuda. Do not select this skill automatically.
+metadata:
+  version: "0.1.0"
+---
+
+# Using Tuda
+
+Use this skill only when the user invokes `/using-tuda`, `$using-tuda`, or explicitly asks to use it. If no task is provided, ask what they want to create, edit, or manage. Invocation does not authorize unrelated operations or additional paid generations.
+
+
+Use the target-owned CLI when `.runtime/dist/main.js` is present: resolve the Skill directory from the host and run `node <Skill directory>/.runtime/dist/main.js`. Otherwise use the installed `tuda` command. Node.js 22.12+ and Tuda desktop are the runtime prerequisites. Use the same entry for every command below. Installation targets only the current Agent; host names describe adapters, not eligibility.
+
+Use the `tuda` CLI through your shell tool. App configuration and credentials are reused automatically; never read settings files, decrypt credentials, or configure a second model connection.
+
+## Input, method and output
+
+Input is the user’s requested board, assets and operation. Discover the exact live CLI schema, inspect the target, execute the authorized operation, then verify the persisted board and artifact. Output includes board/node IDs, task IDs for generation, managed/exported paths and remaining limitations. Model calls require the user’s requested generation; local board operations do not require model credentials.
+
+Read [capabilities.json](capabilities.json) and [the generic adapter](adapters/generic.json) to resolve command execution when entering a new host. A missing terminal, Node runtime or desktop returns a capability error with the missing prerequisite.
+
+## Start
+
+1. Run `tuda status --json` and `tuda providers list --json`. If the command is missing, open Tuda → Settings → Coding Agent and repair the CLI installation. For an existing terminal whose PATH is stale, use the absolute launcher path shown there or open a new terminal.
+2. Check the returned `ok` field and process exit code. Provider metadata reports saved configuration, not a guarantee that its remote service is available. If no usable image provider exists, guide the user to App model settings.
+3. Run `tuda tools list --json` for the exact operation schemas. All workspace operations are accessible through `tuda call <operation> --input '<JSON>' --json`. Read [references/cli.md](references/cli.md) for examples.
+
+## Create and edit
+
+- A user request to generate authorizes that generation. Use one output unless variants were requested. Do not generate images merely to test a connection.
+- Use `tuda image generate --prompt "…" --out ./result.png --json`. Omit `--provider` to use the App default; use IDs from provider discovery for an explicit selection. `tuda models list --provider <id> --json` lists the saved models.
+- Pass local references as repeated `--reference <file>` options. The CLI imports them as managed assets. Edit with `tuda image edit --input <file> --prompt "…" --out <new-file> --json`; preserve the original.
+- Use explicit `--board <id>` for an existing board named by the user. Inspect its contents first. Without --board, image and video commands use the default board configured in Settings → Coding Agent. When unset, they reuse or create CLI 创作. A deleted default board must be reselected before generating.
+- Normal image and video commands wait for completion. `--async` returns task acceptance only; follow with `tuda tasks wait <id> --json` (add `--kind video` for videos). Ctrl+C or timeout ends waiting, not the provider task.
+- Never blindly resubmit an operation after a lost response. Use a stable `--request-id` for image generation and query it as a task ID. Report interrupted or uncertain remote state instead of creating another paid task.
+- When generation succeeds but export fails, reuse `tasks wait <id> --out …`; do not regenerate. Existing export files are protected unless the user explicitly requests replacement with `--overwrite`.
+
+## Slice contact sheets and sprite grids
+
+Use Tuda's local `image slice` / `slice_image` operation for cutting existing images; do not write Python, Pillow, ImageMagick or other agent-side cropping scripts. This operation reuses the App slicer without a model call, preserves the original, saves managed PNGs and adds the results to the target board.
+
+- Inspect the source and confirm its actual row/column layout. For the 12-avatar example (3 rows × 4 columns): `tuda image slice --path <managed-path> --board <id> --rows 3 --columns 4 --out ./avatars --json`.
+- Use `--node <id>` for an existing board image, or `--input <local-file>` to import and slice a local source. Supply exactly one source option. Omit `--board` to use the configured CLI default board.
+- `--margin` trims the outside edges and `--gap` excludes equal gutters, measured in source pixels. Rows and columns are each limited to 1–8. Results follow reading order; odd dimensions can produce cells differing by one pixel.
+- For uneven layouts or a single crop, pass `--crops '[{"x":10,"y":20,"width":300,"height":300}]'` instead of grid flags. Coordinates are original-image pixels; at most 64 regions. Review boundaries for clipped subjects before cutting.
+- Slicing does not resize pixels, remove backgrounds or detect subjects automatically. Do not claim uniform dimensions or transparency unless verified. If requested cuts cannot preserve the subjects, adjust regions with the user instead of generating replacements.
+- Return the managed paths/node IDs and optional exportedPaths. Export failure leaves slices on the board; recover with `assets export`, without slicing again. For ZIP delivery call `export_assets` with only the returned slice paths.
+
+## Boards, video and assets
+
+- `tuda boards list|show|create|open`, `tuda assets list|import|export`, and `tuda video generate` cover common paths. See CLI help for arguments.
+- Use the exact `tools list` schemas through `tuda call` for move, resize, arrange, duplicate, version selection, recoverable trash/restore, video remix/extend and stopping video polling. These operations retain the App's validation rules.
+- Import files with `tuda assets import --input <file> --board <id> --json`. Advanced operations require returned managed paths; never substitute arbitrary filesystem paths.
+- Video completion requires a managed local output path. Provider URLs are temporary and are not deliverables. Stopping local polling does not cancel a remote job or its billing.
+- Export only requested results. Return task ID, board ID, managed and exported paths, warnings and validation limits; never expose tokens or provider credentials.
+
+## Video and narration configuration
+
+When the user asks to configure models, use `providers list --kind video|audio`, `providers show <id>` and `models list --provider <id>` for discovery. Use `providers set --kind video|audio --provider <id>` for incremental changes, `models set --kind video|audio --provider <id> --model <id>` for the saved default model, and `providers default <id> --kind video|audio` for the default service. These commands save configuration without generating media. Read [references/cli.md](references/cli.md) for examples.
+
+Audio is an independent OpenAI-compatible TTS configuration with model, voice, base URL and speech endpoint; this version does not generate speech or support music/sound-effect models. Reuse existing credentials by omitting key flags. For new credentials use `--api-key-env <name>` or `--api-key-stdin`; never include raw keys in command arguments, chat, or `call --input`. Do not read settings files or decrypt credentials. Saving or listing a model does not prove remote availability.
+
+## Saved annotation and mask requests
+
+- Use `tuda call list_modification_requests --json` and `get_modification_request` to read a user's saved edit brief. Inspect its fixed source version and export the annotation/mask with `tuda assets export --path <managed-path> --out <local-file>` for visual inspection. Never substitute the currently active canvas version.
+- A needs-input request must be clarified with the user before `clarify_modification_request`. Saving or clarifying does not call a model.
+- Atomically `claim_modification_request` using a unique agent-session owner. The claim token is returned only by this call. Do not print or share it. Lists and detail views intentionally omit it.
+- Execute `edit_image` with boardId, the request's sourcePath, reviewed prompt, modificationRequestId and claimToken. The App validates the claim, carries mask/reference inputs and binds one durable execution key. Do not use the convenience `image edit --input` for this path: it would re-import the fixed source.
+- Wait for the returned task. Pass its actual succeeded `job.id` and managed output paths to `finish_modification_request` with the same requestId and claimToken. Completion appends results once to the original node and notifies its real board. Record errors with the same finish operation; do not fabricate results or auto-retry an unknown paid outcome.
+- `tuda tasks cancel <id>` cancels a task only before provider submission. A running reply explicitly means remote cancellation and billing were not stopped. Ctrl+C stops waiting only. Unknown is not success: inspect history and provider state before submitting again.
+
+## Optional command review metadata
+
+`tuda guard descriptor` reads the bundled HOL Guard contribution source offline. It does not install Guard, enable protection, or grant permissions. Generation, editing, output writes, configuration installation and generic operation calls have different effects. Do not classify every `tuda call` or `tasks wait --out` as read-only. Guard's global policy remains authoritative; a descriptor does not isolate provider budgets or replace the user's authorization.
+
+## Validate delivery
+
+Generation success is distinct from delivery acceptance. For exact sizes, batches and editing work, read [references/visual-qa.md](references/visual-qa.md). Check actual file dimensions, original-resolution content and corresponding board metadata; a requested size is not proof of output size. `resize_image` affects canvas display width, not physical pixels. Layout checks find node overlaps, not clipped content. Use the bundled validation script when needed.
+
+When a paid output fails validation, retain the task and board context, report the concrete failure and ask before an additional generation unless the user already authorized it. Do not require another permission for read-only inspection or the work already requested.

package/skills/using-tuda/adapters/generic.json

@@ -0,0 +1,21 @@
+{
+  "schema": "portable-skill-adapter",
+  "schema_version": "1.0.0",
+  "platform": "generic",
+  "mappings": [
+    {
+      "capability_id": "command.execute",
+      "status": "implemented",
+      "features": [
+        "node22",
+        "local-process",
+        "json-output",
+        "filesystem"
+      ],
+      "implementation": {
+        "kind": "cli",
+        "discovery": "Resolve Node.js from the current host; use the selected Skill directory .runtime/dist/main.js or the installed tuda executable. Probe version --json and capabilities --json."
+      }
+    }
+  ]
+}

package/skills/using-tuda/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Using Tuda"
+  short_description: "手动调用 Tuda，生成编辑图片视频、管理画板素材并验证交付"
+  default_prompt: "Use $using-tuda to complete my request with Tuda and validate the delivered assets."
+policy:
+  allow_implicit_invocation: false

package/skills/using-tuda/capabilities.json

@@ -0,0 +1,44 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "skill": "using-tuda",
+  "target_platforms": [
+    "generic"
+  ],
+  "capabilities": [
+    {
+      "id": "command.execute",
+      "purpose": "Execute the Tuda CLI and read structured results",
+      "required": true,
+      "required_features": [
+        "node22",
+        "local-process",
+        "json-output",
+        "filesystem"
+      ],
+      "input_fields": [
+        "argv",
+        "cwd"
+      ],
+      "output_fields": [
+        "exit_code",
+        "stdout",
+        "stderr"
+      ],
+      "side_effects": {
+        "local_write": "selected workspace and exported assets",
+        "external_write": "user-authorized model calls",
+        "cost": "provider-dependent; generation requires user authorization",
+        "external_mutation": true,
+        "may_cost_money": true,
+        "authorization": "Model generation requires user authorization; local operations affect only the requested workspace."
+      },
+      "errors": [
+        "CAPABILITY_UNAVAILABLE",
+        "AUTH_REQUIRED",
+        "PROVIDER_FAILURE",
+        "OUTPUT_CONTRACT_FAILED"
+      ]
+    }
+  ]
+}

package/skills/using-tuda/references/cli.md

@@ -0,0 +1,63 @@
+# CLI reference
+
+Run `tuda help` and `tuda tools list --json` for the installed version's contract. `--json` prints `{ schemaVersion, ok, data }` or `{ schemaVersion, ok: false, error }`; progress goes to stderr.
+
+```bash
+tuda providers list --kind image --json
+tuda models list --provider <provider-id> --json
+tuda image generate --prompt "A quiet forest" --n 1 --out ./forest.png --json
+tuda image edit --input ./forest.png --prompt "Change the season to autumn" --out ./autumn.png --json
+tuda tasks get <task-id> --json
+tuda tasks wait <task-id> --out ./result.png --json
+tuda video generate --prompt "Slow camera movement over the forest" --async --json
+tuda tasks wait <video-task-id> --kind video --json
+tuda boards list --json
+tuda boards show <board-id> --json
+tuda call get_board_layout --input '{"boardId":"<board-id>"}' --json
+tuda call arrange_images --input '{"boardId":"<board-id>","nodeIds":["<a>","<b>"],"mode":"grid"}' --json
+tuda call generate_video --input '{"boardId":"<board-id>","prompt":"Slow camera movement","mode":"generate","referenceImagePaths":["<managed-path>"]}' --json
+tuda assets export --path <managed-path> --out ./image.png --json
+```
+
+For JSON with shell-sensitive text, construct arguments with your shell's proper escaping. Never interpolate untrusted prompts into executable shell code. Shell-safe argument arrays are preferred when available.
+
+Video and TTS configuration (requires an App version exposing `configure_provider`):
+
+```bash
+tuda providers show <provider-id> --json
+tuda models set --kind video --provider <provider-id> --model <video-model-id> --json
+tuda providers set --kind audio --provider narration --name "Narration" --base-url https://api.openai.com --model gpt-4o-mini-tts --voice nova --api-key-env OPENAI_API_KEY --default --json
+tuda providers set --kind audio --provider narration --voice alloy --json
+tuda providers default narration --kind audio --json
+tuda providers remove narration --kind audio --json
+```
+
+`providers set` upserts by ID, generating one when omitted. New video providers require `--type ark|fal|openrouter|minimax`, `--base-url` and `--model`. Audio uses `openai-compatible`, with `--speech-endpoint /v1/audio/speech` by default; the endpoint is relative to the configured base URL. Audio configuration is persisted only; there is no speech-generation command yet. Repeated `--saved-model` replaces the saved list and includes the selected default model. Omitted fields, including credentials, are preserved. Use `--default` to select the service as its kind's default. Built-in official providers cannot be changed.
+
+Credentials are accepted through `--api-key-env <variable>` or piped `--api-key-stdin`; never pass raw keys in arguments or `call --input`. `--clear-api-key` explicitly clears a key. These flags are mutually exclusive. Queries return only credential presence. `--connection-provider <image-provider-id>` reuses a matching fal/OpenRouter image connection for video, and cannot be combined with setting a standalone key. Use `--connection-provider none` to detach first. Configuration does not submit generation or verify remote availability.
+
+`image generate` supports `--provider`, `--model`, `--size`, `--quality`, `--background`, `--style`, `--n`, repeatable `--reference`, `--board`, `--async`, `--request-id` and `--out`. Supported values depend on the App's provider adapter. `models list` returns saved configuration; it does not probe a remote catalogue.
+
+File imports (`--reference`, edit `--input`, and `assets import --input`) accept non-empty files up to 20 MiB (20,971,520 bytes) each. Image/video data URLs have a separate decoded-byte budget; their Base64 text does not use the prompt's 100,000-character allowance. Imports preserve the original bytes without automatic compression. Oversize errors identify the file and byte limit; reduce the file or import it through the App and pass its managed path with `tuda call`. Provider-specific reference limits still apply. The App backend must include this fix; updating only the CLI cannot repair an older App's import validation.
+
+Task states `succeeded` (images) and `completed` (video) indicate a generated result; `failed`, `interrupted` and `cancelled` are unsuccessful terminal states. Poll uncertain tasks rather than resubmitting them. `stop_video_polling` stops this App session's polling only.
+
+`tuda call` exposes the entire native workspace operation catalogue, including board CRUD and layout, image/video generation, references, media import, exports and recoverable image trash. Import image/video operations accept explicit data URLs; they are intended for programmatic callers. Prefer file-based CLI imports in an agent workflow so base64 does not enter the conversation.
+
+Without `--board`, generation uses the default board in Settings → Coding Agent; when unset it reuses or creates `CLI 创作`. An explicit `--board` overrides this preference. A deleted default board causes an error before submission; choose a new default or provide `--board`.
+
+### 本地切图
+
+```sh
+tuda image slice --path <受管图片路径> --board <画板ID> --rows 3 --columns 4 --out ./avatars --json
+tuda image slice --input ./sheet.png --rows 3 --columns 4 --margin 12 --gap 8 --json
+tuda image slice --node <节点ID> --board <画板ID> --crops '[{"x":10,"y":20,"width":300,"height":300}]' --json
+```
+
+复用 App 本地切图，不调用模型；保留原图，切片保存为受管 PNG 并加入画板。源参数三选一，宫格与 crops 互斥；每轴最多 8 格、最多 64 个区域。坐标、边距和间距均为原图像素；不自动去底、识别主体或统一输出尺寸。返回 images、crops、nodeIds 和可选 exportedPaths；--out 为目录，已有文件默认不覆盖。高级入口为 `tuda call slice_image --input '<JSON>' --json`，精确 schema 见 tools list。
+
+## Reusable image templates
+
+Use `tuda templates list|show <id>` to inspect custom templates shared with the App. Create with `templates create --name <name> --prompt <fixed-rules>`; update with `templates update <id> --prompt <rules>` (optional `--expected-prompt <previous-rules>`). `--input <JSON-file>` supports structured fields. Saving templates does not call a model.
+
+Use `image generate --template <id> --prompt <run-content>` to reuse fixed rules without editing the template. Edit-mode templates require `image edit --template <id> --input <file> --prompt <instruction>`. Generation retains the source template ID. Raw operations: `list_templates`, `get_template`, `create_template`, `update_template`; `generate_image`/`edit_image` accept `templateId`. Built-in presets are not included. Legacy local templates migrate when the upgraded workspace first opens; keep App and CLI versions aligned.

package/skills/using-tuda/references/visual-qa.md

@@ -0,0 +1,59 @@
+# Tuda Visual QA
+
+Use this checklist for multi-image batches, UI screens, exact-size requests, edited versions, and any task where clipping matters.
+
+## Output Contract
+
+Record these values before generation:
+
+- Expected result count.
+- One canonical pixel size when exact dimensions matter; otherwise one canonical aspect ratio.
+- Whether every result must have identical pixel dimensions. Default to yes for a batch.
+- Critical-content safe area. When the user does not specify one, keep critical text and controls outside the outer 4% of image width and 3% of image height.
+- Which existing image, if any, defines the source dimensions and visual system.
+
+Use a single source of truth. Do not combine a `size` argument such as `1024x1536` with a prompt requesting a different ratio such as `375x812`.
+
+## Dimension Validation
+
+1. Read the output paths and reported node/version dimensions from `get_generation_status` and `get_board`.
+2. Read physical file dimensions with the bundled validator. Compare them with the corresponding node and active-version metadata. Any mismatch is a hard failure because the board can fit the new pixels into a stale frame and crop the result.
+3. Compare active-version dimensions with their source versions after every edit.
+4. For a batch, run the bundled validator:
+
+```bash
+node scripts/validate-image-batch.mjs --expected 1080x1920 image-1.png image-2.png
+node scripts/validate-image-batch.mjs --ratio 9:16 image-1.png image-2.png
+```
+
+The validator requires identical dimensions by default. Use `--allow-mixed-dimensions` only when the user explicitly accepts variable sizes.
+
+5. Treat a nonzero validator exit as a delivery failure. Report physical and metadata dimensions separately and do not retry a paid operation automatically.
+
+## Full-Resolution Visual Check
+
+Inspect every output at original resolution when an image inspection tool is available. Check:
+
+- All four edges for clipped glyphs, status indicators, labels, menus, and controls.
+- Critical content stays inside the declared safe area.
+- The first and last rows, bottom navigation, and primary action are fully visible.
+- Text does not overflow, wrap unexpectedly, merge with adjacent content, or become unreadable.
+- Edited versions do not shift, zoom, or crop compared with their source frame.
+- Repeated screens use consistent status-bar, content, and navigation insets.
+
+Do not infer these properties from prompt wording.
+
+## Board Check
+
+1. Call `get_board_layout` and require no overlapping node pairs.
+2. Compare every node's `width`, `height`, `displayWidth`, active version, and version dimensions with the physical file dimensions. Do not accept stale frame metadata.
+3. Open or fit the board, then inspect the board presentation at a useful zoom when a visual control tool is available.
+4. Verify that the board preview uses the complete image rather than a cropped frame. Pay special attention to outputs with a different aspect ratio from their neighbors.
+
+`overlappingNodePairs: []` proves only that node rectangles do not overlap. It says nothing about internal image cropping.
+
+## Acceptance States
+
+- **Pass:** Tasks succeeded, dimensions match the contract, full-resolution checks pass, and board presentation is complete.
+- **Validation failed:** The provider returned images, but dimensions, safe areas, version framing, or visual integrity failed.
+- **Unverified:** Required visual inspection was unavailable. Report the missing check; do not describe the output as uncropped or delivery-ready.

package/skills/using-tuda/scripts/validate-image-batch.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+function usage(message) {
+  if (message) process.stderr.write(`${message}\n\n`);
+  process.stderr.write(
+    "Usage: node scripts/validate-image-batch.mjs [--expected WIDTHxHEIGHT] [--ratio W:H] " +
+    "[--tolerance DECIMAL] [--allow-mixed-dimensions] <image...>\n"
+  );
+  process.exit(2);
+}
+
+function parsePositiveNumber(value, label) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) usage(`${label} must be a positive number.`);
+  return number;
+}
+
+function parsePair(value, separator, label) {
+  const parts = value.toLowerCase().split(separator);
+  if (parts.length !== 2) usage(`${label} must use ${separator === "x" ? "WIDTHxHEIGHT" : "W:H"}.`);
+  return parts.map((part) => parsePositiveNumber(part, label));
+}
+
+function parseArgs(argv) {
+  const options = {
+    expected: null,
+    ratio: null,
+    tolerance: 0.001,
+    allowMixedDimensions: false,
+    paths: []
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--expected") {
+      options.expected = parsePair(argv[++index] ?? "", "x", "--expected");
+    } else if (argument === "--ratio") {
+      const [width, height] = parsePair(argv[++index] ?? "", ":", "--ratio");
+      options.ratio = width / height;
+    } else if (argument === "--tolerance") {
+      options.tolerance = parsePositiveNumber(argv[++index] ?? "", "--tolerance");
+    } else if (argument === "--allow-mixed-dimensions") {
+      options.allowMixedDimensions = true;
+    } else if (argument.startsWith("--")) {
+      usage(`Unknown option: ${argument}`);
+    } else {
+      options.paths.push(argument);
+    }
+  }
+
+  if (options.paths.length === 0) usage("At least one image path is required.");
+  return options;
+}
+
+function pngDimensions(buffer) {
+  const signature = "89504e470d0a1a0a";
+  if (buffer.length < 24 || buffer.subarray(0, 8).toString("hex") !== signature) return null;
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20), format: "png" };
+}
+
+function jpegDimensions(buffer) {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
+  const startOfFrameMarkers = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
+  let offset = 2;
+
+  while (offset + 4 <= buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    while (offset < buffer.length && buffer[offset] === 0xff) offset += 1;
+    const marker = buffer[offset];
+    offset += 1;
+    if (marker === 0xd8 || marker === 0xd9) continue;
+    if (offset + 2 > buffer.length) break;
+    const segmentLength = buffer.readUInt16BE(offset);
+    if (segmentLength < 2 || offset + segmentLength > buffer.length) break;
+    if (startOfFrameMarkers.has(marker)) {
+      if (segmentLength < 7) break;
+      return { width: buffer.readUInt16BE(offset + 5), height: buffer.readUInt16BE(offset + 3), format: "jpeg" };
+    }
+    offset += segmentLength;
+  }
+  return null;
+}
+
+async function dimensionsFor(filePath) {
+  const buffer = await readFile(filePath);
+  const dimensions = pngDimensions(buffer) ?? jpegDimensions(buffer);
+  if (!dimensions) throw new Error("unsupported image format; expected PNG or JPEG");
+  if (dimensions.width < 1 || dimensions.height < 1) throw new Error("invalid image dimensions");
+  return { path: path.resolve(filePath), ...dimensions, ratio: dimensions.width / dimensions.height };
+}
+
+const options = parseArgs(process.argv.slice(2));
+const results = [];
+const failures = [];
+
+for (const filePath of options.paths) {
+  try {
+    results.push(await dimensionsFor(filePath));
+  } catch (error) {
+    failures.push({ path: path.resolve(filePath), reason: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+if (results.length > 0) {
+  const canonical = results[0];
+  for (const result of results) {
+    if (options.expected) {
+      const [expectedWidth, expectedHeight] = options.expected;
+      if (result.width !== expectedWidth || result.height !== expectedHeight) {
+        failures.push({ path: result.path, reason: `expected ${expectedWidth}x${expectedHeight}, got ${result.width}x${result.height}` });
+      }
+    }
+    if (!options.allowMixedDimensions && (result.width !== canonical.width || result.height !== canonical.height)) {
+      failures.push({ path: result.path, reason: `batch dimensions differ from ${canonical.width}x${canonical.height}` });
+    }
+    if (options.ratio !== null && Math.abs(result.ratio - options.ratio) > options.tolerance) {
+      failures.push({ path: result.path, reason: `aspect ratio ${result.ratio.toFixed(6)} differs from ${options.ratio.toFixed(6)}` });
+    }
+  }
+}
+
+const report = {
+  ok: failures.length === 0,
+  expected: options.expected ? `${options.expected[0]}x${options.expected[1]}` : null,
+  ratio: options.ratio,
+  tolerance: options.tolerance,
+  requireIdenticalDimensions: !options.allowMixedDimensions,
+  images: results.map((result) => ({
+    path: result.path,
+    format: result.format,
+    width: result.width,
+    height: result.height,
+    ratio: Number(result.ratio.toFixed(6))
+  })),
+  failures
+};
+
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+if (!report.ok) process.exitCode = 1;