From 9b565117b3dcc260ecbfd4ef45a45807b3055c46 Mon Sep 17 00:00:00 2001 From: mapleluv Date: Mon, 27 Jul 2026 23:57:57 +0800 Subject: [PATCH] Migrate visual primitives to VP CLI and Skill Set Squashed from locally reviewed branch feature/vp-cli-skill-set-release. Final local review accepted VPREL-001 through VPREL-012. --- .gitattributes | 9 + .github/workflows/ci.yml | 30 + .github/workflows/release.yml | 60 + .gitignore | 5 + CHANGELOG.md | 25 + LICENSE | 21 + README.md | 342 +-- README.zh-CN.md | 340 +-- RELEASE.md | 69 + .../work/vp-cli-skill-set-release/README.md | 23 + .../contracts/package-and-cli-contract.md | 92 + .../0001-single-package-architecture.md | 46 + .../work/vp-cli-skill-set-release/intent.md | 71 + index.ts | 6 - package-lock.json | 2490 ++++------------- package.json | 70 +- scripts/build-cli.mjs | 34 + scripts/package-smoke.mjs | 158 ++ scripts/release-state.mjs | 26 + scripts/resolve-release-state.mjs | 53 + scripts/verify-release-bootstrap.mjs | 38 + scripts/verify-release-tag.mjs | 11 + skills/_shared/run-vp.mjs | 21 + skills/frontend-replication/SKILL.md | 10 +- .../references/masked-oracle-diff.md | 4 +- .../scripts}/masked-oracle-diff.ts | 0 .../scripts/run-masked-oracle-diff.mjs | 21 + skills/inline-replication/SKILL.md | 6 +- skills/subagent-driven-replication/SKILL.md | 12 +- skills/using-visual-primitives/SKILL.md | 168 +- src/cli.ts | 913 ++++++ src/crop.ts | 14 +- src/extension.ts | 171 -- src/phase2.ts | 62 +- src/schema.ts | 207 +- tests/cli.test.ts | 702 +++++ tests/crop.test.ts | 2 +- tests/extension.test.ts | 225 -- tests/masked-oracle-diff.test.ts | 49 +- tests/package-runtime.test.ts | 128 + tests/package.test.ts | 619 +--- tests/release-bootstrap.test.ts | 63 + tests/release-contract.test.ts | 130 + tests/release-state-adapter.test.ts | 89 + tests/release-state.test.ts | 51 + tests/schema.test.ts | 36 - 46 files changed, 3947 insertions(+), 3775 deletions(-) create mode 100644 .gitattributes create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/release.yml create mode 100644 CHANGELOG.md create mode 100644 LICENSE create mode 100644 RELEASE.md create mode 100644 docs/superpowers/work/vp-cli-skill-set-release/README.md create mode 100644 docs/superpowers/work/vp-cli-skill-set-release/contracts/package-and-cli-contract.md create mode 100644 docs/superpowers/work/vp-cli-skill-set-release/decisions/0001-single-package-architecture.md create mode 100644 docs/superpowers/work/vp-cli-skill-set-release/intent.md delete mode 100644 index.ts create mode 100644 scripts/build-cli.mjs create mode 100644 scripts/package-smoke.mjs create mode 100644 scripts/release-state.mjs create mode 100644 scripts/resolve-release-state.mjs create mode 100644 scripts/verify-release-bootstrap.mjs create mode 100644 scripts/verify-release-tag.mjs create mode 100644 skills/_shared/run-vp.mjs rename {scripts => skills/frontend-replication/scripts}/masked-oracle-diff.ts (100%) create mode 100644 skills/frontend-replication/scripts/run-masked-oracle-diff.mjs create mode 100644 src/cli.ts delete mode 100644 src/extension.ts create mode 100644 tests/cli.test.ts delete mode 100644 tests/extension.test.ts create mode 100644 tests/package-runtime.test.ts create mode 100644 tests/release-bootstrap.test.ts create mode 100644 tests/release-contract.test.ts create mode 100644 tests/release-state-adapter.test.ts create mode 100644 tests/release-state.test.ts delete mode 100644 tests/schema.test.ts diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..b437e2b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,9 @@ +* text=auto eol=lf +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.webp binary +*.bmp binary +*.ico binary +*.tgz binary diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4a96a9d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,30 @@ +name: CI + +on: + push: + branches: [master, main] + pull_request: + +permissions: + contents: read + +jobs: + verify: + name: ${{ matrix.os }} / Node ${{ matrix.node }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + node: [22.18.0, 24.x] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + cache: npm + - run: npm ci --ignore-scripts + - run: npm run check + - run: npm test + - run: npm run package:smoke + - run: npm audit --audit-level=high diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..2c4df63 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,60 @@ +name: Release + +on: + push: + tags: + - 'v*.*.*' + +permissions: + contents: write + id-token: write + +jobs: + publish: + name: Publish npm package and GitHub Release + runs-on: ubuntu-latest + environment: npm + steps: + - uses: actions/checkout@v4 + - name: Verify first-publication bootstrap + env: + GH_TOKEN: ${{ github.token }} + RELEASE_BOOTSTRAPPED: ${{ vars.RELEASE_BOOTSTRAPPED }} + TARGET_REPOSITORY: mapleluvr/visual-primitives + run: | + test "${RELEASE_BOOTSTRAPPED}" = "true" + test "${GITHUB_REPOSITORY}" = "${TARGET_REPOSITORY}" + gh api "repos/${TARGET_REPOSITORY}" >/dev/null + npm run release:verify-bootstrap + - uses: actions/setup-node@v4 + with: + node-version: 24.x + cache: npm + registry-url: https://registry.npmjs.org + - run: npm install --global npm@11.6.2 + - run: npm ci --ignore-scripts + - run: npm run check + - run: npm test + - run: npm run package:smoke + - run: npm audit --audit-level=high + - run: npm run release:verify-tag -- "${GITHUB_REF_NAME}" + - name: Build release artifacts + run: | + mkdir release + npm pack --json --ignore-scripts --pack-destination release > release/pack.json + sha256sum release/*.tgz > release/SHA256SUMS + npm sbom --sbom-format spdx > release/sbom.spdx.json + - name: Resolve npm publication state + id: npm-state + run: node scripts/resolve-release-state.mjs release/pack.json + - name: Publish npm package + if: steps.npm-state.outputs.publish == 'true' + run: npm publish release/*.tgz --provenance --access public + - name: Create or update GitHub Release + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1 || \ + gh release create "${GITHUB_REF_NAME}" --verify-tag --generate-notes + gh release upload "${GITHUB_REF_NAME}" \ + release/*.tgz release/SHA256SUMS release/sbom.spdx.json --clobber diff --git a/.gitignore b/.gitignore index 545fd06..e79ca97 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,10 @@ node_modules/ +dist/ +skills/frontend-replication/scripts/masked-oracle-diff.js npm-debug.log* .DS_Store *.crop-*.png tmp/ +.worktrees/ +.superpowers/ +.pi-subagents/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..22cf058 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,25 @@ +# Changelog + +All notable changes to this package are documented here. + +## [0.2.0] - 2026-07-27 + +### Added + +- Standalone vp CLI through the `vp` and `visual-primitives` binaries, with `crop`, `crop-multi`, `annotate`, `point`, and `colors` commands. +- Strict JSON compatibility mode for the five former visual primitive tool payloads. +- Package-local Skill launcher at `skills/_shared/run-vp.mjs`. +- Frontend-owned package-local masked-diff runner that works from consumer project directories. +- Six-Skill package containing generic visual evidence guidance and the frontend replication workflow family. +- Cross-platform CI, packed-install smoke coverage, restartable GitHub Release assets, and tag-gated npm Trusted Publishing configuration. + +### Changed + +- Renamed the npm package from the legacy Pi extension identity to `@mapleluvr/visual-primitives`. +- Moved `masked-oracle-diff` under frontend-replication-owned Skill resources. +- Unified the CLI and Skill Set under one package version and Git tag. + +### Removed + +- Pi extension registration and the runtime peer dependency on `@earendil-works/pi-coding-agent`. +- `masked-oracle-diff` from the generic visual primitive execution surface. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f5aa677 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 mapleluvr + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index b33a198..f2a9e0a 100644 --- a/README.md +++ b/README.md @@ -1,329 +1,143 @@ -# Pi Visual Primitives +# Visual Primitives [中文](README.zh-CN.md) -Pi Visual Primitives is a Pi extension package that gives agents visual evidence workflow helper tools. Use it for tasks involving images, screenshots, rendered UI, reference designs, visual effects, frontend visual reproduction, visual comparison, or visual QA when the agent needs to draw conclusions from visual appearance. +`@mapleluvr/visual-primitives` ships one versioned package containing: -Visual evidence needs trigger the package. Coordinates are selected, estimated, or provided during the evidence workflow, then turned into local crop, annotation, point-crop, and color-sampling artifacts that agents can inspect or reuse while reasoning about visuals. +- the workflow-agnostic `vp` CLI for turning explicit boxes and points into inspectable image evidence; and +- six Agent Skills for generic visual evidence and frontend replication workflows. -The design is inspired by the "Thinking with Visual Primitives" paper overview: points and bounding boxes can act as concrete spatial references during visual reasoning. Detection, OCR, segmentation, automatic box generation, and automatic UI inference stay outside the tool contract. The package turns user-provided or agent-estimated regions into local evidence artifacts. +Node.js 22.18 or newer is required. The package does not perform object detection, OCR, segmentation, automatic box generation, or UI inference. Users or agents provide the coordinates, and direct visual inspection remains the interpreter of generated artifacts. -## Features +## Install The CLI -- Create visual evidence artifacts for screenshot analysis, frontend visual reproduction, visual comparison, and visual QA. -- Annotate or crop UI regions such as headers, cards, sidebars, forms, buttons, charts, and footers. -- Crop one bounding box from a local image. -- Batch-crop multiple boxes from the same image with deterministic output names. -- Create same-size annotated preview images with box outlines and optional labels. -- Crop around an explicit point using a required radius or width/height. -- Sample exact colors at provided points with `sample_colors` for CSS-level color precision. -- Supports paper-style normalized `0-999` coordinates. -- Supports direct pixel coordinates. -- Supports top-left and bottom-left coordinate origins. -- Supports `[left, top, right, bottom]` and `[left, bottom, right, top]` box orders. -- Optional pixel padding. -- Optional bounds clamping. -- Returns structured metadata including source dimensions and resolved pixel box. - -## Installation - -From this repository checkout, install dependencies: - -```bash -cd pi-visual-primitives -npm install -``` - -Use temporarily in Pi: +Install both binary aliases globally from npm: ```bash -pi -e ./pi-visual-primitives +npm install -g @mapleluvr/visual-primitives +vp --help +visual-primitives --version ``` -Install as a Pi package so Pi loads both the extension tool and the Skill: - -```bash -pi install ./pi-visual-primitives -``` - -Then run `/reload` in Pi. - -## Skill Set - -This package includes a Pi Skill Set under `skills/`: - -- `skills/using-visual-primitives/SKILL.md` for general visual evidence work: marking, cropping, comparing, aligning, and analyzing images. -- `skills/frontend-replication/SKILL.md` as the gateway for oracle-image-driven frontend replication. -- `skills/inline-replication/SKILL.md` for parent-agent execution loops. -- `skills/subagent-driven-replication/SKILL.md` for orchestrated subagent replication loops. This route uses optional environment support from `pi-subagents`, `subagent-driven-development`, and superpowers workflows; use `inline-replication` when those are unavailable. -- `skills/refining-with-feedback/SKILL.md` for turning process verdicts into feedback drafts. -- `skills/finalizing-replication/SKILL.md` for final direct inspection and delivery review. - -Use `using-visual-primitives` for standalone visual evidence tasks and `frontend-replication` for screenshot-oracle webpage reproduction. - -## Visual Evidence Workflow Example - -For a prompt like `Recreate this dashboard screenshot and match the spacing`, an agent should identify the screenshot, decide which visual conclusions need evidence, annotate major regions such as `sidebar`, `header`, `primary-card`, and `button`, crop important areas for focused inspection, implement the UI, then compare equivalent reference/current regions after rendering. - -For screenshots and rendered UI, prefer `coordinateSpace: "pixel"` unless the source clearly uses normalized visual-primitive coordinates. For paper-style visual primitive coordinates, use the default `normalized-999` behavior. +The two aliases are equivalent. The public command surface contains exactly five commands: -## Worked Examples +| Command | Purpose | +| --- | --- | +| `vp crop` | Crop one rectangular region. | +| `vp crop-multi` | Crop several regions from one source image. | +| `vp annotate` | Draw labeled boxes on a same-size preview. | +| `vp point` | Crop around an explicit point and radius or size. | +| `vp colors` | Sample exact colors at explicit points. | -Frontend is meant to be looked at, so these examples are shown, not scored. Both renders are a single pass by a mid-tier frontend model driven through `frontend-replication` -> `inline-replication`. +Run `vp --help` for complete flag and JSON input documentation. -These results depend on the workflow actually being followed. The quality comes from running the replication loop, not from the model alone — skip the workflow and let the model free-run, and the output degrades noticeably. A short starting prompt that reliably drives the loop: +## CLI Examples -```text -Replicate the frontend screenshot at (viewport x). Follow the -frontend-replication workflow strictly. +Flag mode defaults to pixel coordinates: -- Match the oracle's exact pixel dimensions in the rendered screenshot. -- Render every code-drawable region in code (CSS/SVG): text, song/artist names, - table columns, icons, badges, status pills, progress bars, and brand colors. -- Approved exclusions may be represented by placeholders or delegated image assets: avatars, album / cover art, organic illustrations, and dense logo marks. -- Keep code-drawable content inside the scoring domain; use exclusions only for - tightly bounded regions that cannot be described as boxes and paths. +```bash +vp annotate screenshot.png --box "header:40,30,240,180" --out annotated.png +vp crop screenshot.png --box "40,30,240,180" --out header.png +vp crop-multi screenshot.png \ + --box "header:40,30,240,180" \ + --box "button:280,220,420,280" \ + --out-dir crops +vp point screenshot.png --point "80,50" --radius 30 --out detail.png +vp colors screenshot.png --point "header-bg:80,50" --patch 3 ``` -The exclusion boundary is drawn by *what a text model can render*, not by *what is an image*. The code-drawable list keeps structured UI work inside the scoring domain instead of quietly widening exclusions to make the task easier. - -### Simple task: fast and accurate - -The oracle is an analytics dashboard mockup — a regular layout of a sidebar, a KPI row, two chart cards, and a transactions table. - -![Dashboard mockup next to the single-pass render](docs/visual-primitives/examples/pulse-side-by-side.png) - -*Left: the oracle mockup. Right: the single-pass render.* - -On a clean, regular layout like this the workflow does not even need its feedback loop. The first render matches the oracle closely enough that the two are hard to tell apart at a glance — sidebar, stat cards, the revenue area chart, the traffic donut, and the transactions table with its colored status pills all land in place, with the semantic colors (green up-deltas, red down-deltas, amber pending) reproduced. Simple targets come out fast and accurate in one pass. +Use `--space normalized-999` for normalized thousandths, `--origin bottom-left` when y grows upward, and `--box-order left-bottom-right-top` for bottom-left box tuples. -### Complex task: a dense real-world screenshot +Every successful command writes one JSON value to stdout. Summaries and warnings go to stderr and can be suppressed with `--quiet`. Usage failures exit `2`; image and filesystem failures exit `1`. -The oracle is a real NetEase Cloud Music desktop screenshot (`1448x940`) — a much harder target: a three-region client with dozens of code-drawable icons, badge systems (`超清母带`, `VIP`), a brand-specific red, multi-size Chinese typography, right-aligned table columns, and a floating progress bar. +### JSON Compatibility -![NetEase screenshot next to the single-pass render](docs/visual-primitives/examples/netease-side-by-side.png) - -*Left: the real screenshot used as the oracle. Right: the single-pass render. Full-resolution copies of every example are under [`docs/visual-primitives/examples/`](docs/visual-primitives/examples/).* - -Six regions were **delegated out of the code-replication scope** as exclusions rather than reproduced by the text model — the playlist cover art, two avatars, two track thumbnails, and the rotating vinyl. The workflow delegates organic, imagination-driven imagery to image assets or placeholders, while keeping structured UI content in the code-scored domain. - -Even at this density the single-pass render holds together — the layout skeleton, table alignment, badge system, brand red, and icon glyphs all reproduce closely enough that the remaining differences take focused inspection to find. What is visible on close viewing is small-area detail rather than layout failure: - -- The **NetEase logo mark** is only approximated — the render draws a rough glyph inside the red circle instead of the precise headphone/note mark, and its size and weight are slightly off. -- The **progress-bar knob** sits a few pixels high of the red/gray boundary instead of centered on it. -- A handful of icons differ by a font-weight step. - -The NetEase logo mark was left in the code-replication scope for this run, so its rough SVG approximation remains a visible limitation. In stricter production runs, dense brand marks can be declared as narrow exclusion candidates alongside avatars and cover art. The scoring domain is reserved for structured UI details a text model can describe and render accurately. - -## Masked Oracle Diff CLI - -`masked-oracle-diff` compares an oracle image and rendered image while excluding narrowly justified non-code-drawable regions. Everything outside the exclusion boxes is scored. - -Run it with: +`--json ` accepts the original five Pi tool payload shapes. JSON mode preserves their `normalized-999` default and rejects unknown properties, wrong types, non-finite values, invalid enums, mutually exclusive fields, and command-inapplicable fields. ```bash -npm run oracle:diff -- --manifest docs/visual-primitives/runs//scripts/diff-manifest.json +vp crop --json crop.json ``` -The CLI writes `diff.gray.png`, masks, previews, a `25 x 25` matrix, components, stripes, `summary.json`, and `VERDICT.md` into the manifest `outputDir`. - -## Tool: `crop_bounding_box` - -Crops one provided bounding box from a source image. - -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| `imagePath` | `string` | required | Source image path. Relative paths resolve against Pi's current working directory. A leading `@` is ignored. | -| `box` | `[number, number, number, number]` | required | Bounding box coordinates. | -| `coordinateSpace` | `"normalized-999" \| "pixel"` | `"normalized-999"` | Interpret coordinates as paper-style normalized values or direct pixels. | -| `origin` | `"top-left" \| "bottom-left"` | `"top-left"` | Coordinate origin. Bottom-left means y grows upward. | -| `boxOrder` | `"left-top-right-bottom" \| "left-bottom-right-top"` | `"left-top-right-bottom"` | Coordinate order of the input box. | -| `outputPath` | `string` | generated | Output PNG path. Relative paths resolve against Pi's current working directory. | -| `padding` | `number` | `0` | Pixel padding added around the resolved box. | -| `clamp` | `boolean` | `true` | Clip out-of-bounds boxes to image bounds. If false, out-of-bounds boxes fail. | - -## Tool: `crop_multiple_bounding_boxes` - -Crops several boxes from the same source image in one fail-fast call. It reuses the same coordinate options as `crop_bounding_box`. - -| Parameter | Type | Default | Description | -| --- | --- | --- | --- | -| `imagePath` | `string` | required | Source image path. | -| `boxes` | `Array<{ box, label?, outputPath? }>` | required | Boxes to crop. Each item may include a label and per-box output path. | -| `outputDir` | `string` | generated beside source | Directory for generated crop files when a box does not provide `outputPath`. | -| `coordinateSpace` | `"normalized-999" \| "pixel"` | `"normalized-999"` | Coordinate interpretation shared by all boxes. | -| `origin` | `"top-left" \| "bottom-left"` | `"top-left"` | Coordinate origin shared by all boxes. | -| `boxOrder` | `"left-top-right-bottom" \| "left-bottom-right-top"` | `"left-top-right-bottom"` | Coordinate order shared by all boxes. | -| `padding` | `number` | `0` | Pixel padding shared by all boxes. | -| `clamp` | `boolean` | `true` | Shared bounds-clamping behavior. | - -Example: - ```json { - "imagePath": "scene.png", - "outputDir": "scene-crops", + "imagePath": "screenshot.png", + "box": [40, 30, 240, 180], "coordinateSpace": "pixel", - "boxes": [ - { "label": "title", "box": [10, 20, 180, 80] }, - { "label": "button", "box": [220, 300, 380, 360] } - ] + "outputPath": "header.png" } ``` -The tool starts with fail-fast behavior: if one box is invalid, the call fails instead of returning partial results. - -## Tool: `annotate_bounding_boxes` - -Creates an annotated preview image with provided boxes drawn over the source image. The output image keeps the source dimensions and returns resolved box metadata. +## Install The Skill Set In Pi -Example: - -```json -{ - "imagePath": "scene.png", - "outputPath": "scene-annotated.png", - "coordinateSpace": "pixel", - "boxes": [ - { "label": "target", "box": [50, 40, 250, 180] } - ] -} -``` +Install a pinned npm version: -Use this to verify coordinate-space, origin, or box-order assumptions before making visual claims. - -## Tool: `sample_colors` - -Samples exact pixel or patch colors at provided points in a source image. Use it when CSS-level color precision matters. - -Example: - -```json -{ - "imagePath": "scene.png", - "coordinateSpace": "pixel", - "patchSize": 3, - "points": [ - { "label": "header-bg", "point": [130, 40] }, - { "label": "cta-button", "point": [620, 340] } - ] -} +```bash +pi install npm:@mapleluvr/visual-primitives@0.2.0 ``` -The tool returns resolved pixel points plus RGB, hex, OKLab, patch size, sampled pixel count, and patch mean hex values. Palette and dominant-color discovery stay outside the point-sampling contract. - -## Tool: `crop_around_point` - -Crops a region centered around a provided point. The call requires an explicit crop size through either `radius` or `size`. - -Example with radius: +Or install a pinned Git tag: -```json -{ - "imagePath": "scene.png", - "point": [500, 500], - "radius": 80, - "outputPath": "scene-point.png" -} +```bash +pi install git:github.com/mapleluvr/visual-primitives@v0.2.0 ``` -Example with explicit size: +The Pi package manifest loads Skills only. It does not register a visual-primitives extension. -```json -{ - "imagePath": "scene.png", - "point": [120, 90], - "size": { "width": 60, "height": 40 }, - "coordinateSpace": "pixel" -} -``` +Pi package installation does not guarantee that npm binaries are placed on the system `PATH`. Agent guidance therefore invokes the packaged CLI through `skills/_shared/run-vp.mjs`. Humans may still use a globally installed `vp` binary. -The coordinate options match `crop_bounding_box`. +## Skill Set -### Normalized visual-primitive box +The package includes six discoverable Skills: -```json -{ - "imagePath": "scene.png", - "box": [120, 80, 420, 360] -} -``` +- `using-visual-primitives`: generic guidance for selecting and using the five `vp` commands, coordinate conventions, direct inspection, and second-order measurements. +- `frontend-replication`: gateway for oracle-driven frontend reproduction. +- `inline-replication`: parent-agent replication loop. +- `subagent-driven-replication`: orchestrated worker and reviewer loop. +- `refining-with-feedback`: draft-history and verdict synthesis. +- `finalizing-replication`: final direct inspection and delivery routing. -This uses the default `coordinateSpace: "normalized-999"`, matching the visual-primitives paper convention. +Use `using-visual-primitives` for standalone image and screenshot evidence. Use `frontend-replication` when the task includes oracle intake, implementation rounds, masked scoring, verdicts, or delivery review. Specialized Skills reference the generic command and coordinate guidance instead of duplicating it. -### Pixel box +## Frontend Workflow Helper -```json -{ - "imagePath": "scene.png", - "box": [50, 40, 250, 180], - "coordinateSpace": "pixel", - "outputPath": "scene-object.png" -} -``` +`masked-oracle-diff` remains owned by the frontend replication workflow. It is not a `vp` command, npm binary, generic core export, or responsibility of `using-visual-primitives`. -### Bottom-left coordinate system +When a replication Skill is loaded, resolve `scripts/run-masked-oracle-diff.mjs` relative to the loaded `frontend-replication` Skill directory and invoke that package-local runner from the consumer project: -```json -{ - "imagePath": "plot.png", - "box": [10, 20, 60, 80], - "coordinateSpace": "pixel", - "origin": "bottom-left", - "boxOrder": "left-bottom-right-top" -} +```bash +node /scripts/run-masked-oracle-diff.mjs --manifest docs/visual-primitives/runs//scripts/diff-manifest.json ``` -The tool converts this to the top-left pixel rectangle required by image processing libraries. +A repository maintainer working in this package checkout may instead use `npm run oracle:diff -- --manifest `. Consumer projects do not need that npm script. The runner, source, and built runtime live under `skills/frontend-replication/scripts/`. The helper writes masks, previews, diff images, matrix data, components, stripes, `summary.json`, and `VERDICT.md`. A clean diff opens final direct inspection; it does not declare delivery success by itself. -### Strict bounds checking +## Versioning -```json -{ - "imagePath": "scene.png", - "box": [-10, 0, 100, 100], - "coordinateSpace": "pixel", - "clamp": false -} -``` - -This fails because the box exceeds image bounds. +The CLI and Skill Set use one package version and one Git tag. Package version `X.Y.Z` corresponds to tag `vX.Y.Z`. Command names, JSON input semantics, exit codes, documented Skill resources, and helper ownership are protected compatibility contracts. -## Returned Metadata +## Migration from `pi-visual-primitives` -The tool returns text containing the output path and resolved crop rectangle. Structured details include: +The legacy package registered TypeScript Pi extension tools such as `crop_bounding_box` and `sample_colors`. Version `0.2.0` replaces that runtime surface with the standalone five-command CLI and a skills-only Pi package. -- `imagePath` -- `outputPath` -- `source.width` -- `source.height` -- `source.format` -- `input.box` -- `input.coordinateSpace` -- `input.origin` -- `input.boxOrder` -- `input.padding` -- `input.clamp` -- `resolvedPixelBox` -- `unclampedPixelBox` -- `clamped` +1. Remove the legacy package from Pi settings or uninstall it with the source identity previously used. +2. Install `npm:@mapleluvr/visual-primitives@0.2.0` or the pinned Git tag shown above. +3. Replace old extension tool calls with `vp crop`, `vp crop-multi`, `vp annotate`, `vp point`, and `vp colors`. +4. For agent execution, use the package-local launcher described by `using-visual-primitives`; do not assume `vp` is on `PATH`. +5. Keep masked oracle diff work inside the frontend replication Skill family. ## Development -Run tests: - ```bash +npm ci --ignore-scripts +npm run check npm test +npm run package:smoke +npm audit --audit-level=high ``` -Run syntax checks: - -```bash -npm run check -``` +`npm run package:smoke` creates and installs a temporary tarball, invokes both aliases and all five commands on a generated PNG, validates all six Skills, runs the package-local launcher with package bins removed from `PATH`, and verifies frontend helper ownership. -The tests generate temporary PNG fixtures with `sharp.create()`, so the repository does not need binary fixture images. +CI runs on Ubuntu, Windows, and macOS with Node 22.18.0 and Node 24.x. Publishing is tag-gated and uses npm Trusted Publishing with provenance. First-publication prerequisites, restart behavior, and the separately authorized live steps are documented in [RELEASE.md](RELEASE.md). Creating or pushing a release tag is a separate authorized release action; ordinary commits do not publish the package. ## License -MIT +[MIT](LICENSE) diff --git a/README.zh-CN.md b/README.zh-CN.md index efc0691..dbcbfa8 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,327 +1,143 @@ -# Pi Visual Primitives +# Visual Primitives [English](README.md) -Pi Visual Primitives 是一个 Pi 扩展包,为 Agent 提供视觉证据工作流辅助工具。适用场景包括图片、截图、渲染 UI、参考设计、视觉效果、前端视觉复现、视觉对比和视觉 QA,只要任务需要从视觉外观中得出结论,就可以使用它。 +`@mapleluvr/visual-primitives` 用一个统一版本的 package 提供: -视觉证据需求会触发这个包。坐标可以由用户提供,也可以由 Agent 在证据工作流中选择或估计;随后这些坐标会被转换成本地裁剪图、标注图、点裁剪图和颜色采样结果,供 Agent 直接查看、复用和推理。 +- 与工作流无关的 `vp` CLI,将明确给定的框和点转换为可检查的图像证据; +- 六个 Agent Skills,分别覆盖通用视觉证据和前端复现工作流。 -这个设计受到 “Thinking with Visual Primitives” 思路启发:点和 bounding box 可以作为视觉推理中的具体空间参照。检测、OCR、分割、自动生成 box、自动推断 UI 元素等能力留在工具契约之外;本包负责把用户提供或 Agent 估计的区域转换成可检查的本地证据产物。 +需要 Node.js 22.18 或更高版本。这个 package 不负责目标检测、OCR、图像分割、自动生成框或自动推断 UI 元素。坐标由用户或 agent 提供,生成的图像仍需直接视觉检查后才能解释。 -## 功能 +## 安装 CLI -- 为截图分析、前端视觉复现、视觉对比和视觉 QA 创建视觉证据产物。 -- 标注或裁剪 header、card、sidebar、form、button、chart、footer 等 UI 区域。 -- 从本地图片裁剪一个 bounding box。 -- 从同一张图片批量裁剪多个 box,并生成确定性的输出文件名。 -- 创建和原图同尺寸的标注预览图,带 box 边框和可选 label。 -- 围绕明确的点进行裁剪,必须提供 radius 或 width/height。 -- 使用 `sample_colors` 在指定点采样精确颜色,支持 CSS 级颜色精度。 -- 支持论文风格的 `0-999` 归一化坐标。 -- 支持直接像素坐标。 -- 支持 top-left 和 bottom-left 坐标原点。 -- 支持 `[left, top, right, bottom]` 和 `[left, bottom, right, top]` 两种 box 顺序。 -- 支持可选 padding。 -- 支持可选边界 clamp。 -- 返回包含 source dimensions 和 resolved pixel box 的结构化 metadata。 - -## 安装 - -从仓库 checkout 安装依赖: - -```bash -cd pi-visual-primitives -npm install -``` - -在 Pi 中临时使用: +从 npm 全局安装两个等价的命令别名: ```bash -pi -e ./pi-visual-primitives -``` - -作为 Pi package 安装,让 Pi 同时加载扩展工具和 Skill: - -```bash -pi install ./pi-visual-primitives -``` - -然后在 Pi 中运行 `/reload`。 - -## 技能集 - -本包在 `skills/` 下提供一组 Pi Skill: - -- `skills/using-visual-primitives/SKILL.md`:通用视觉证据工作,包括标记、裁剪、对比、对齐和分析图像。 -- `skills/frontend-replication/SKILL.md`:基于 oracle 图片的前端复现入口 skill。 -- `skills/inline-replication/SKILL.md`:由父 Agent 自行执行的复现循环。 -- `skills/subagent-driven-replication/SKILL.md`:由 Orchestrator 编排 subagent 的复现循环。该路线可使用 `pi-subagents`、`subagent-driven-development` 和 superpowers workflow;如果环境不可用,则使用 `inline-replication`。 -- `skills/refining-with-feedback/SKILL.md`:把过程性 verdict 转换为下一轮 feedback draft。 -- `skills/finalizing-replication/SKILL.md`:最终直接检查和交付审查。 - -独立视觉证据任务使用 `using-visual-primitives`;截图 oracle 驱动的网页复现使用 `frontend-replication`。 - -## 视觉证据工作流示例 - -对于 `Recreate this dashboard screenshot and match the spacing` 这样的任务,Agent 应该先识别截图,判断哪些视觉结论需要证据,标注 `sidebar`、`header`、`primary-card`、`button` 等主要区域,裁剪关键区域进行聚焦检查,实现 UI,然后在渲染后对比 reference/current 的对应区域。 - -对于截图和渲染 UI,优先使用 `coordinateSpace: "pixel"`。只有当来源明确使用论文/模型风格的 visual primitive 坐标时,才使用默认的 `normalized-999`。 - -## 完整示例 - -前端是用来看的。两组 render 都是一个中档前端模型(GPT 5.5)在 `frontend-replication` -> `inline-replication` 驱动下完成的一次性输出。 - -这些结果依赖工作流被真正执行。经过A/B实验可以发现工作流对于复现以下结果来说,是非常必要的。使用的Prompt示例: - -```text -Replicate the frontend screenshot at (viewport x). Follow the -frontend-replication workflow strictly. - -- Match the oracle's exact pixel dimensions in the rendered screenshot. -- Render every code-drawable region in code (CSS/SVG): text, song/artist names, - table columns, icons, badges, status pills, progress bars, and brand colors. -- Approved exclusions may be represented by placeholders or delegated image assets: avatars, album / cover art, organic illustrations, and dense logo marks. -- Keep code-drawable content inside the scoring domain; use exclusions only for - tightly bounded regions that cannot be described as boxes and paths. +npm install -g @mapleluvr/visual-primitives +vp --help +visual-primitives --version ``` -排除边界由“文本模型用代码渲染什么”决定。用代码渲染所有可代码绘制区域,让可代码绘制的区域被用于工作流内自评估完成度。批准的排除区域可以用占位图或委托图像资产表示。 - -### 简单任务:快速且准确 - -Oracle 是一个分析仪表盘 mockup:sidebar、KPI 行、两个 chart card 和 transaction table 组成的规则布局。 - -![仪表盘 mockup 与单次 render 对照](docs/visual-primitives/examples/pulse-side-by-side.png) - -*左:oracle mockup。右:单次 render。* - -在这种干净、规则的布局上,工作流甚至不需要进入 feedback loop。第一次 render 已经接近 oracle:sidebar、stat cards、revenue area chart、traffic donut、transaction table 以及彩色 status pill 都落在正确位置;绿色上升、红色下降、琥珀色 pending 等语义色也被复现。简单目标通常能在一轮中快速得到准确结果。 - -### 复杂任务:密集真实截图 - -Oracle 是一张网易云音乐桌面端截图(`1448x940`),难度更高:三大区域、几十个可代码绘制 icon、`超清母带` / `VIP` badge、品牌红、多字号中文排版、右对齐表格列和浮动进度条。 - -![网易云音乐截图与单次 render 对照](docs/visual-primitives/examples/netease-side-by-side.png) - -*左:作为 oracle 的真实截图。右:单次 render。完整分辨率示例都在 [`docs/visual-primitives/examples/`](docs/visual-primitives/examples/) 下。* - -这次 run 中有六个区域被委托出 code-replication scope 作为 exclusions:歌单封面、两个头像、两个曲目缩略图和旋转黑胶。工作流把有机的、想象驱动的图像交给图像资产或占位图,同时让结构化 UI 内容留在代码评分域。 - -即使在这种密度下,单次 render 仍然保持了整体结构:布局骨架、表格对齐、badge 系统、品牌红和 icon glyph 都足够接近,剩余差异需要聚焦检查才能发现。近看可见的是小面积细节,而不是布局失败: +公开命令面严格包含五个子命令: -- **网易云 logo mark** 只是近似绘制,render 在红色圆形内画了一个粗略 glyph,而不是精确的耳机/音符标志,尺寸和字重也略有偏差。 -- **进度条旋钮** 比红/灰分界线高了几个像素,没有完全居中。 -- 少数 icon 的 font-weight 差一个档位。 +| 命令 | 用途 | +| --- | --- | +| `vp crop` | 裁剪一个矩形区域。 | +| `vp crop-multi` | 从同一张图裁剪多个区域。 | +| `vp annotate` | 在同尺寸预览图上绘制带标签的框。 | +| `vp point` | 按明确的点和半径或尺寸裁剪。 | +| `vp colors` | 在明确的点采样精确颜色。 | -网易云 logo mark 在这次 run 中保留在 code-replication scope 内,所以粗略 SVG 近似是一个可见 limitation。更严格的生产 run 可以把密集品牌标志声明为窄 exclusion candidate,和头像、封面图一起处理。评分域应保留给文本模型能够描述并准确渲染的结构化 UI 细节。 +运行 `vp --help` 查看完整 flags 和 JSON 输入文档。 -## Masked Oracle Diff CLI +## CLI 示例 -`masked-oracle-diff` 会比较 oracle image 和 rendered image,同时排除经过窄边界论证的非代码可精确绘制区域。exclusion box 之外的所有像素都会进入评分域。 - -运行方式: +Flag 模式默认使用像素坐标: ```bash -npm run oracle:diff -- --manifest docs/visual-primitives/runs//scripts/diff-manifest.json +vp annotate screenshot.png --box "header:40,30,240,180" --out annotated.png +vp crop screenshot.png --box "40,30,240,180" --out header.png +vp crop-multi screenshot.png \ + --box "header:40,30,240,180" \ + --box "button:280,220,420,280" \ + --out-dir crops +vp point screenshot.png --point "80,50" --radius 30 --out detail.png +vp colors screenshot.png --point "header-bg:80,50" --patch 3 ``` -CLI 会把 `diff.gray.png`、mask、preview、`25 x 25` matrix、components、stripes、`summary.json` 和 `VERDICT.md` 写入 manifest 的 `outputDir`。 - -## 工具:`crop_bounding_box` - -从源图片裁剪一个已提供的 bounding box。 +归一化千分位坐标使用 `--space normalized-999`;y 轴向上时使用 `--origin bottom-left`;左下原点的框顺序使用 `--box-order left-bottom-right-top`。 -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `imagePath` | `string` | required | 源图片路径。相对路径按 Pi 当前工作目录解析。前导 `@` 会被忽略。 | -| `box` | `[number, number, number, number]` | required | Bounding box 坐标。 | -| `coordinateSpace` | `"normalized-999" \| "pixel"` | `"normalized-999"` | 按论文风格归一化坐标或直接像素坐标解释。 | -| `origin` | `"top-left" \| "bottom-left"` | `"top-left"` | 坐标原点。Bottom-left 表示 y 轴向上增长。 | -| `boxOrder` | `"left-top-right-bottom" \| "left-bottom-right-top"` | `"left-top-right-bottom"` | 输入 box 的坐标顺序。 | -| `outputPath` | `string` | generated | 输出 PNG 路径。相对路径按 Pi 当前工作目录解析。 | -| `padding` | `number` | `0` | 在 resolved box 周围增加的像素 padding。 | -| `clamp` | `boolean` | `true` | 把越界 box 裁到图片边界内。设为 false 时,越界 box 会失败。 | +成功命令会向 stdout 写出一个 JSON 值。摘要和 warning 写到 stderr,可用 `--quiet` 抑制。用法错误退出码为 `2`;图像或文件系统运行时错误退出码为 `1`。 -## 工具:`crop_multiple_bounding_boxes` +### JSON 兼容模式 -从同一张源图片裁剪多个 box。它复用 `crop_bounding_box` 的坐标选项,并采用 fail-fast 行为。 +`--json ` 接受原先五个 Pi tool 的 payload 形状。JSON 模式保留 `normalized-999` 默认值,并拒绝未知字段、错误类型、非有限数值、非法枚举、互斥字段和不适用于命令的字段。 -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `imagePath` | `string` | required | 源图片路径。 | -| `boxes` | `Array<{ box, label?, outputPath? }>` | required | 要裁剪的 box。每个条目可以包含 label 和单独的输出路径。 | -| `outputDir` | `string` | generated beside source | 当 box 没有提供 `outputPath` 时,用于生成裁剪文件的目录。 | -| `coordinateSpace` | `"normalized-999" \| "pixel"` | `"normalized-999"` | 所有 box 共享的坐标解释。 | -| `origin` | `"top-left" \| "bottom-left"` | `"top-left"` | 所有 box 共享的坐标原点。 | -| `boxOrder` | `"left-top-right-bottom" \| "left-bottom-right-top"` | `"left-top-right-bottom"` | 所有 box 共享的坐标顺序。 | -| `padding` | `number` | `0` | 所有 box 共享的像素 padding。 | -| `clamp` | `boolean` | `true` | 共享的边界 clamp 行为。 | - -示例: - -```json -{ - "imagePath": "scene.png", - "outputDir": "scene-crops", - "coordinateSpace": "pixel", - "boxes": [ - { "label": "title", "box": [10, 20, 180, 80] }, - { "label": "button", "box": [220, 300, 380, 360] } - ] -} +```bash +vp crop --json crop.json ``` -## 工具:`annotate_bounding_boxes` - -创建一张带 box 标注的预览图。输出图片保持源图尺寸,并返回 resolved box metadata。 - -示例: - ```json { - "imagePath": "scene.png", - "outputPath": "scene-annotated.png", + "imagePath": "screenshot.png", + "box": [40, 30, 240, 180], "coordinateSpace": "pixel", - "boxes": [ - { "label": "target", "box": [50, 40, 250, 180] } - ] + "outputPath": "header.png" } ``` -用它来验证 coordinate space、origin 或 box order 假设,再进行视觉判断。 - -## 工具:`sample_colors` +## 在 Pi 中安装 Skill Set -在源图片的指定点采样精确像素色或 patch 平均色。适合需要 CSS 级颜色精度的场景。 +安装固定 npm 版本: -示例: - -```json -{ - "imagePath": "scene.png", - "coordinateSpace": "pixel", - "patchSize": 3, - "points": [ - { "label": "header-bg", "point": [130, 40] }, - { "label": "cta-button", "point": [620, 340] } - ] -} +```bash +pi install npm:@mapleluvr/visual-primitives@0.2.0 ``` -工具返回 resolved pixel points、RGB、hex、OKLab、patch size、sampled pixel count 和 patch mean hex。调色板和主色发现留在 point-sampling contract 之外。 - -## 工具:`crop_around_point` - -围绕一个指定点裁剪区域。调用必须通过 `radius` 或 `size` 提供明确裁剪尺寸。 - -Radius 示例: +或者安装固定 Git tag: -```json -{ - "imagePath": "scene.png", - "point": [500, 500], - "radius": 80, - "outputPath": "scene-point.png" -} +```bash +pi install git:github.com/mapleluvr/visual-primitives@v0.2.0 ``` -明确 size 示例: +Pi package manifest 只加载 Skills,不注册 visual-primitives extension。 -```json -{ - "imagePath": "scene.png", - "point": [120, 90], - "size": { "width": 60, "height": 40 }, - "coordinateSpace": "pixel" -} -``` +Pi package 安装不保证 npm binary 会进入系统 `PATH`。因此 agent 指南通过 `skills/_shared/run-vp.mjs` 调用 package 内的 CLI;人类用户仍可使用全局安装的 `vp`。 -坐标选项与 `crop_bounding_box` 一致。 +## Skill Set -### 归一化 visual-primitive box +Package 包含六个可发现的 Skills: -```json -{ - "imagePath": "scene.png", - "box": [120, 80, 420, 360] -} -``` +- `using-visual-primitives`:五个 `vp` 命令的选择和使用、坐标约定、直接检查与二阶测量。 +- `frontend-replication`:oracle 驱动前端复现的入口。 +- `inline-replication`:父 agent 执行的复现循环。 +- `subagent-driven-replication`:由父会话编排 worker 和 reviewer 的循环。 +- `refining-with-feedback`:整合 DraftHistory 与 verdict。 +- `finalizing-replication`:最终直接检查与交付路由。 -这会使用默认的 `coordinateSpace: "normalized-999"`,匹配 visual-primitives 论文约定。 +独立的图像和截图证据任务使用 `using-visual-primitives`。包含 oracle intake、实现轮次、masked scoring、verdict 或交付审查时使用 `frontend-replication`。专用 Skills 引用通用命令和坐标指南,不重复定义它们。 -### 像素 box +## 前端工作流 Helper -```json -{ - "imagePath": "scene.png", - "box": [50, 40, 250, 180], - "coordinateSpace": "pixel", - "outputPath": "scene-object.png" -} -``` +`masked-oracle-diff` 归 `frontend-replication` 工作流所有。它不是 `vp` 子命令,不是 npm binary,不是通用 core export,也不属于 `using-visual-primitives` 的职责。 -### Bottom-left 坐标系 +加载 replication Skill 后,相对于已加载的 `frontend-replication` Skill 目录解析 `scripts/run-masked-oracle-diff.mjs`,再从 consumer project 调用这个 package-local runner: -```json -{ - "imagePath": "plot.png", - "box": [10, 20, 60, 80], - "coordinateSpace": "pixel", - "origin": "bottom-left", - "boxOrder": "left-bottom-right-top" -} +```bash +node /scripts/run-masked-oracle-diff.mjs --manifest docs/visual-primitives/runs//scripts/diff-manifest.json ``` -工具会把它转换成图像处理库需要的 top-left 像素矩形。 +在本 package checkout 中工作的仓库维护者也可以使用 `npm run oracle:diff -- --manifest `;consumer project 不需要这个 npm script。Runner、源码和构建后的 runtime 都位于 `skills/frontend-replication/scripts/`。Helper 会写出 mask、preview、diff 图、matrix、components、stripes、`summary.json` 和 `VERDICT.md`。干净的 diff 只会打开最终直接检查,不能自行宣布交付成功。 -### 严格边界检查 +## 版本策略 -```json -{ - "imagePath": "scene.png", - "box": [-10, 0, 100, 100], - "coordinateSpace": "pixel", - "clamp": false -} -``` - -这个调用会失败,因为 box 超出了图片边界。 +CLI 与 Skill Set 使用一个 package 版本和一个 Git tag。Package `X.Y.Z` 对应 tag `vX.Y.Z`。命令名、JSON 输入语义、退出码、已文档化的 Skill 资源和 helper 归属都属于受保护兼容契约。 -## 返回 Metadata +## 从 `pi-visual-primitives` 迁移 -工具返回文本中包含输出路径和 resolved crop rectangle。结构化详情包括: +旧 package 通过 Pi extension 注册 `crop_bounding_box`、`sample_colors` 等 TypeScript tools。`0.2.0` 用独立的五命令 CLI 和只包含 Skills 的 Pi package 取代该运行面。 -- `imagePath` -- `outputPath` -- `source.width` -- `source.height` -- `source.format` -- `input.box` -- `input.coordinateSpace` -- `input.origin` -- `input.boxOrder` -- `input.padding` -- `input.clamp` -- `resolvedPixelBox` -- `unclampedPixelBox` -- `clamped` +1. 从 Pi settings 移除旧 package,或使用之前安装时的 source identity 卸载。 +2. 安装上面的 `npm:@mapleluvr/visual-primitives@0.2.0` 或固定 Git tag。 +3. 将旧 extension tool 调用替换为 `vp crop`、`vp crop-multi`、`vp annotate`、`vp point` 和 `vp colors`。 +4. Agent 执行时使用 `using-visual-primitives` 说明的 package-local launcher,不假设 `vp` 在 `PATH` 中。 +5. 将 masked oracle diff 工作保留在 frontend replication Skill family 内。 ## 开发 -运行测试: - ```bash +npm ci --ignore-scripts +npm run check npm test +npm run package:smoke +npm audit --audit-level=high ``` -运行语法检查: - -```bash -npm run check -``` +`npm run package:smoke` 会创建并安装临时 tarball,在生成的 PNG 上运行两个 binary aliases 和五个命令,验证六个 Skills,在从 `PATH` 移除 package bins 后执行 package-local launcher,并检查 frontend helper 的归属。 -测试使用 `sharp.create()` 生成临时 PNG fixture,因此仓库不需要额外的二进制测试 fixture。 +CI 在 Ubuntu、Windows 和 macOS 上测试 Node 22.18.0 与 Node 24.x。发布仅由 tag 触发,并使用 npm Trusted Publishing 和 provenance。首次发布先决条件、失败重跑行为和需要单独授权的 live steps 记录在 [RELEASE.md](RELEASE.md)。创建或推送 release tag 是需要单独授权的发布动作;普通 commit 不会发布 package。 ## 许可证 -MIT +[MIT](LICENSE) diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..6f6fb41 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,69 @@ +# Release Runbook + +This file documents live release effects. It does not authorize them. Repository renames, pushes, npm publication, GitHub environment changes, tag creation, and GitHub Releases each require separate authorization. + +## First Publication Bootstrap + +The automated release workflow is intentionally blocked until the public repository and npm package already exist and npm Trusted Publishing is configured. At the time this runbook was added, those live prerequisites had not been performed. + +Perform the following only in an authorized release session: + +1. Rename or create the target GitHub repository as `mapleluvr/visual-primitives`. +2. Update the local Git remote to the target repository, push the reviewed branch, and wait for the CI matrix to pass. +3. Create the npm package settings entry without consuming the formal release version. In a temporary directory outside this repository, create a minimal package named `@mapleluvr/visual-primitives` at prerelease version `0.0.0-bootstrap.0`, then publish it interactively under the non-default `bootstrap` dist-tag with an authorized npm account and required second factor: + + ```bash + mkdir visual-primitives-bootstrap && cd visual-primitives-bootstrap + npm init --yes + npm pkg set name=@mapleluvr/visual-primitives version=0.0.0-bootstrap.0 license=MIT + npm publish --access public --tag bootstrap + ``` + + Do not store a long-lived npm token in the repository or GitHub. The bootstrap prerelease is not the CLI + Skill Set release and must not receive the `latest` dist-tag. +4. In the npm package settings for `@mapleluvr/visual-primitives`, configure a Trusted Publisher for: + - GitHub organization/user: `mapleluvr` + - repository: `visual-primitives` + - workflow: `release.yml` + - GitHub environment: `npm` +5. In the target GitHub repository, create or configure the `npm` Environment. Add required reviewers if desired. Add the environment variable `RELEASE_BOOTSTRAPPED=true` only after the target repository exists, the bootstrap prerelease is visible, and the Trusted Publisher relationship is active. +6. Verify that `npm view @mapleluvr/visual-primitives@bootstrap name version --json` resolves to `@mapleluvr/visual-primitives@0.0.0-bootstrap.0` (or run `npm run release:verify-bootstrap`) and that the repository Actions page can see the `npm` Environment. Do not use the unqualified package query before the formal release because no `latest` dist-tag exists yet. +7. From the exact reviewed formal-release commit, run the local release suite: + + ```bash + npm ci --ignore-scripts + npm run check + npm test + npm run package:smoke + npm audit --audit-level=high + npm pack --json --ignore-scripts --pack-destination release + ``` + + Inspect and preserve the formal tarball metadata, SHA-256, integrity, and shasum. Do not publish this tarball manually. +8. Create and push the matching `vX.Y.Z` tag only after a separate authorization. The workflow publishes the formal version through the Trusted Publisher with provenance, then creates or repairs the GitHub Release assets. +9. After the formal release succeeds and the `latest` dist-tag points to it, optionally remove the bootstrap dist-tag with a separately authorized `npm dist-tag rm @mapleluvr/visual-primitives bootstrap`. The immutable bootstrap prerelease remains in history. + +The workflow rejects a tag in the legacy repository, a missing target repository, a missing npm package, or an unset bootstrap variable before any publish step. + +## Routine Release + +For later versions: + +1. Update `package.json`, `package-lock.json`, and `CHANGELOG.md` together. +2. Run the local release suite and obtain review approval on the exact commit. +3. Confirm the target repository, npm Trusted Publisher, and `npm` Environment remain configured. +4. With separate authorization, create and push tag `vX.Y.Z`, where `X.Y.Z` exactly matches `package.json`. +5. Inspect the workflow result, npm provenance, tarball checksum, SBOM, and GitHub Release assets. + +Ordinary branch pushes and pull requests run CI only; they never publish. + +## Restart And Recovery + +The release workflow is restartable across its two external effects: + +- Before npm publication it compares the locally packed tarball with the registry's integrity and shasum. +- If the version is unpublished, it publishes the tarball with OIDC provenance. +- If the same version already contains an identical artifact, it skips npm publication. +- If the immutable version exists with different integrity or shasum, it stops instead of overwriting or attaching misleading release assets. +- GitHub Release creation is `view-or-create`; asset upload uses `--clobber`. A rerun can therefore repair a missing or partial GitHub Release after npm publication succeeded. + +If any bootstrap or release step fails, stop and inspect the exact remote state before retrying. Do not create a replacement tag or version merely to bypass a failed transaction. diff --git a/docs/superpowers/work/vp-cli-skill-set-release/README.md b/docs/superpowers/work/vp-cli-skill-set-release/README.md new file mode 100644 index 0000000..5981b76 --- /dev/null +++ b/docs/superpowers/work/vp-cli-skill-set-release/README.md @@ -0,0 +1,23 @@ +# VP CLI + Skill Set Release Authority + +Status: Approved + +Approval source: user approval in the project session on 2026-07-27, including the subsequent ownership clarifications for `using-visual-primitives` and `masked-oracle-diff`. + +## Authority + +- [Intent](intent.md) +- [Package and CLI contract](contracts/package-and-cli-contract.md) +- [Single-package architecture decision](decisions/0001-single-package-architecture.md) + +## Relationship to Existing Authority + +This authority changes the package and execution surface from a Pi extension to a standalone `vp` CLI plus a packaged Skill Set. It supersedes extension-registration and release-organization assumptions in older design documents. + +The established frontend replication workflow semantics, oracle inputs, draft history, masked scoring, verdicts, refinement limits, direct inspection requirements, and visual-evidence principles remain authoritative unless this authority explicitly changes their ownership or invocation boundary. + +In particular: + +- `using-visual-primitives` remains the general-purpose skill for deciding when and how to use visual primitives. +- `frontend-replication` and its lifecycle skills remain the specialized workflow layer. +- `masked-oracle-diff` remains owned by the frontend replication workflow and is not part of the `vp` command surface. diff --git a/docs/superpowers/work/vp-cli-skill-set-release/contracts/package-and-cli-contract.md b/docs/superpowers/work/vp-cli-skill-set-release/contracts/package-and-cli-contract.md new file mode 100644 index 0000000..e8cb09d --- /dev/null +++ b/docs/superpowers/work/vp-cli-skill-set-release/contracts/package-and-cli-contract.md @@ -0,0 +1,92 @@ +# Contract: Package, CLI, and Skill Boundaries + +## Package Identity + +The publishable package identity is `@mapleluvr/visual-primitives`. One package version covers the CLI, generic skill, frontend replication skill family, and workflow-owned helper scripts. + +The package exposes two equivalent binaries: + +- `vp` +- `visual-primitives` + +The Pi manifest exposes skills only. It does not expose an extension. + +## VP Command Surface + +The stable command names are: + +- `crop` +- `crop-multi` +- `annotate` +- `point` +- `colors` + +`masked-oracle-diff`, oracle management, screenshot capture, draft creation, verdict creation, refinement, and finalization are not `vp` commands. + +### Input Modes + +Human-oriented flags default to pixel coordinates. The command help must disclose that default. + +JSON input is a compatibility mode for the former Pi tool payloads. It preserves the original payload field names and `normalized-999` default. JSON validation must reject: + +- unknown properties; +- invalid optional-property types; +- non-finite numbers; +- invalid enum values; +- invalid mutually exclusive fields; +- command-inapplicable properties. + +Validation failures are usage errors and use exit code 2. Runtime image or filesystem failures use exit code 1. Successful commands use exit code 0. + +### Output + +Successful commands write one JSON value to stdout. Optional human summaries and warnings go to stderr and can be suppressed. Generated image artifacts are PNG files. The result identifies resolved paths, source dimensions, resolved pixel coordinates, and clamping where applicable. + +The CLI must never report an invalid typed value as if it were a valid resolved option. + +## Skill Invocation + +A skill installation must not depend on a globally installed `vp` executable. The package provides a package-local, cross-platform launcher that resolves and invokes the packaged CLI. Skill documentation may prefer a global `vp` for humans but must use or fall back to the package-local launcher for agent execution. + +## Skill Ownership + +### `using-visual-primitives` + +Owns generic agent guidance for: + +- when visual evidence is needed; +- selecting among the five `vp` commands; +- choosing pixel or normalized coordinates, origin, and box order; +- annotating assumptions before relying on them; +- inspecting generated crops and annotations; +- sampling explicit color points; +- computing second-order quantities from independently estimated coordinates. + +It does not own oracle manifests, exclusion policy, masked scoring, drafts, verdicts, replication rounds, or delivery routing. + +### Frontend replication family + +Owns oracle intake, screenshot alignment, draft history, code execution loops, masked scoring, verdicts, feedback, subagent orchestration, and final direct inspection. It references the generic visual primitive guidance instead of redefining it. + +### `masked-oracle-diff` + +This helper is shipped inside the frontend replication skill resources. It may have a repository-development npm script for tests or maintainers, but it is not an npm bin, a `vp` subcommand, a generic package export, or part of the generic skill. + +## Package Artifact + +The npm artifact includes only declared runtime and documentation files. Development plans, workspaces, tests, fixtures used only by tests, and repository-local run evidence are excluded. + +A release candidate is valid only if a tarball-install smoke test proves: + +- both binary aliases execute; +- all five commands are discoverable; +- all six skills are included and valid; +- Pi package metadata points only at skills; +- the frontend workflow helper exists at its documented package-relative location; +- no extension entrypoint or Pi runtime peer dependency is required. + +## Compatibility and Invalidation + +Removing or renaming a command, changing JSON field semantics, changing exit codes, moving a documented skill resource, or moving `masked-oracle-diff` into the generic CLI is a protected-contract change. + +Internal module paths and implementation details are not stable APIs unless separately documented later. diff --git a/docs/superpowers/work/vp-cli-skill-set-release/decisions/0001-single-package-architecture.md b/docs/superpowers/work/vp-cli-skill-set-release/decisions/0001-single-package-architecture.md new file mode 100644 index 0000000..c9dcfaf --- /dev/null +++ b/docs/superpowers/work/vp-cli-skill-set-release/decisions/0001-single-package-architecture.md @@ -0,0 +1,46 @@ +# Decision 0001: Single Repository and Single Versioned Package + +Status: Approved + +## Decision + +Publish the standalone CLI and all six skills from one GitHub repository and one scoped npm package, `@mapleluvr/visual-primitives`. Use one SemVer version and one Git tag for the entire artifact. + +Keep three responsibility layers inside that package: + +1. `vp` as the workflow-independent execution engine; +2. `using-visual-primitives` as generic agent guidance for using `vp`; +3. the frontend replication skill family as the specialized workflow layer, including its workflow-owned `masked-oracle-diff` helper. + +## Reasons + +- Skill instructions and CLI flags, JSON fields, result shapes, and exit semantics form one compatibility unit. +- Atomic releases prevent a Skill version from describing a CLI version that is not installed. +- One issue tracker and changelog preserve the reason for cross-layer changes. +- Pi can install skills from the same npm or Git package that contains their runtime helper. +- The scoped npm name avoids collision with the already occupied unscoped `vp` package while retaining the short `vp` binary. + +## Rejected Alternatives + +### Separate CLI and Skill npm packages + +Rejected for the initial public contract because it introduces dependency/version coordination without an independent release cadence that justifies it. + +### Separate GitHub repositories + +Rejected because CLI and Skill changes commonly co-change and require integrated package smoke tests. + +### GitHub-only distribution + +Rejected as the primary stable channel because npm provides platform-aware dependency installation, immutable version resolution, and a natural binary installation path. Pinned GitHub tags remain a supported secondary channel. + +### Put `masked-oracle-diff` in `vp` + +Rejected because its oracle, exclusion, scoring, draft, and verdict semantics belong to frontend replication rather than general visual evidence primitives. + +## Consequences + +- Any CLI/Skill contract change increments the one package version. +- Package tests must validate the integrated artifact rather than only source directories. +- Skills need a package-local launcher because Pi package installation does not promise system `PATH` exposure for npm bins. +- Release automation and documentation must distinguish GitHub source releases, npm shell installation, and Pi skill installation. diff --git a/docs/superpowers/work/vp-cli-skill-set-release/intent.md b/docs/superpowers/work/vp-cli-skill-set-release/intent.md new file mode 100644 index 0000000..4530072 --- /dev/null +++ b/docs/superpowers/work/vp-cli-skill-set-release/intent.md @@ -0,0 +1,71 @@ +# Intent: Publish Visual Primitives as VP CLI + Skill Set + +## User-Observable Outcome + +Users can install one versioned package from npm or GitHub and receive both: + +1. a standalone `vp` command for framework-independent visual evidence primitives; and +2. a discoverable Agent Skill Set whose generic and frontend-replication responsibilities are clearly separated. + +Pi is one supported consumer of the Skill Set, but the visual primitive execution surface no longer depends on the Pi extension API. + +## Acceptance + +- **VPREL-001 Unified package:** One repository root is one publishable npm package with one version covering the CLI and all packaged skills. +- **VPREL-002 Public commands:** The package exposes `vp` and `visual-primitives` binaries with the five commands `crop`, `crop-multi`, `annotate`, `point`, and `colors`. +- **VPREL-003 CLI evidence:** Each command supports non-interactive structured JSON output, documented exit semantics, deterministic artifact generation, and focused runtime verification on real or generated PNG inputs. +- **VPREL-004 JSON compatibility:** JSON input accepts the original five Pi tool payload shapes and defaults, rejects schema-invalid fields and types as usage errors, and does not silently reinterpret invalid values. +- **VPREL-005 Skill package:** Pi package discovery loads all six skills from the package and loads no visual-primitives extension. +- **VPREL-006 Generic skill boundary:** `using-visual-primitives` remains useful independently of frontend replication and owns generic guidance for selecting and using `vp`, coordinate conventions, visual evidence, direct inspection, and second-order measurements. +- **VPREL-007 Workflow boundary:** `frontend-replication`, `inline-replication`, `subagent-driven-replication`, `refining-with-feedback`, and `finalizing-replication` own the oracle-driven reproduction workflow without duplicating the generic `vp` guidance. +- **VPREL-008 Diff ownership:** `masked-oracle-diff` ships with and remains owned by the frontend replication workflow. It is not a `vp` command, npm binary, generic core export, or generic-skill responsibility. +- **VPREL-009 Package-local execution:** Packaged skills can invoke the packaged CLI without assuming that `pi install` or another skill installer places npm binaries on the system `PATH`. +- **VPREL-010 Publishable artifact:** A packed tarball contains only the intended runtime, skills, workflow helper, documentation, and license files; installing that tarball proves both binary aliases and Pi skill discovery. +- **VPREL-011 Release automation:** GitHub CI verifies supported operating systems and Node versions, while release automation verifies the tag/package version and uses npm trusted publishing with provenance. Merely merging code does not publish or rename anything. +- **VPREL-012 Migration documentation:** English and Chinese documentation distinguish shell installation, Pi installation, the generic skill, the frontend workflow, legacy extension behavior, and the live release steps that still require authorization. + +## Hard Constraints + +- The public npm package name is `@mapleluvr/visual-primitives`; `vp` remains a binary name rather than an unscoped npm package name. +- CLI and Skill Set releases use one SemVer version and one Git tag. +- The package must not depend at runtime on `@earendil-works/pi-coding-agent` after extension retirement. +- Coordinate selection remains user- or agent-provided. Detection, OCR, segmentation, automatic box generation, and automatic UI inference remain outside the primitive contract. +- Direct visual inspection remains the interpreter of generated evidence. +- Existing frontend replication draft, verdict, exclusion, scoring, and final-inspection semantics must remain intact. +- `masked-oracle-diff` must not migrate into `vp`. +- The repository must remain installable from both npm and a pinned GitHub tag. + +## Non-Goals + +- Publishing a standalone native executable or bundling platform-specific `sharp` binaries as GitHub release assets. +- Splitting the CLI and Skills into separate repositories or independently versioned npm packages. +- Establishing a stable JavaScript library API for internal image-processing modules. +- Adding new visual inference, browser automation, OCR, CV, or screenshot-capture capabilities. +- Redesigning the frontend replication workflow or its visual quality thresholds. +- Performing a live GitHub repository rename, push, npm publish, npm ownership change, or GitHub Release creation during local implementation. + +## Protected Invariants + +- `vp` stays workflow-agnostic. +- `using-visual-primitives` stays frontend-workflow-agnostic. +- `masked-oracle-diff` stays frontend-workflow-specific. +- Skill guidance and CLI behavior share one tested command/input/output contract. +- Invalid user input fails clearly rather than succeeding with altered semantics. +- A clean diff remains evidence that opens direct inspection; it never declares delivery success by itself. + +## Effect Authorization + +Authorized now: + +- local file changes in the isolated feature worktree; +- local dependency installation without lifecycle scripts where needed; +- local tests, builds, package creation, and temporary installation smoke tests; +- local commits on the feature branch. + +Not authorized without a later explicit user instruction: + +- `git push`; +- renaming or creating a GitHub repository; +- publishing or deprecating an npm package; +- creating tags or GitHub Releases on the remote; +- changing npm or GitHub ownership, secrets, environments, or trusted-publisher settings. diff --git a/index.ts b/index.ts deleted file mode 100644 index 2b2d9f0..0000000 --- a/index.ts +++ /dev/null @@ -1,6 +0,0 @@ -import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; -import { pluginDirFromImportMeta, registerVisualPrimitives } from "./src/extension.ts"; - -export default function (pi: ExtensionAPI): void { - registerVisualPrimitives(pi, { pluginDir: pluginDirFromImportMeta(import.meta.url) }); -} diff --git a/package-lock.json b/package-lock.json index 23d9801..fb42322 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,1965 +1,477 @@ { - "name": "pi-visual-primitives", - "version": "0.1.0", + "name": "@mapleluvr/visual-primitives", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "pi-visual-primitives", - "version": "0.1.0", + "name": "@mapleluvr/visual-primitives", + "version": "0.2.0", "license": "MIT", "dependencies": { - "sharp": "^0.34.0" - }, - "peerDependencies": { - "@earendil-works/pi-coding-agent": "*" - } - }, - "node_modules/@earendil-works/pi-coding-agent": { - "version": "0.78.1", - "resolved": "https://registry.npmjs.org/@earendil-works/pi-coding-agent/-/pi-coding-agent-0.78.1.tgz", - "integrity": "sha512-Syjf6Ib8UoY5t9ZdKjp0BRrQZuFkFBc8j2KEU9zG/ZnmYPcAxYeioofdv2Q3MEXnHEX2U8sKQptkSnJIdMsd0g==", - "hasShrinkwrap": true, - "license": "MIT", - "peer": true, - "dependencies": { - "@earendil-works/pi-agent-core": "^0.78.1", - "@earendil-works/pi-ai": "^0.78.1", - "@earendil-works/pi-tui": "^0.78.1", - "@silvia-odwyer/photon-node": "0.3.4", - "chalk": "5.6.2", - "cross-spawn": "7.0.6", - "diff": "8.0.4", - "glob": "13.0.6", - "highlight.js": "10.7.3", - "hosted-git-info": "9.0.3", - "ignore": "7.0.5", - "jiti": "2.7.0", - "minimatch": "10.2.5", - "proper-lockfile": "4.1.2", - "typebox": "1.1.38", - "undici": "8.3.0", - "yaml": "2.9.0" - }, - "bin": { - "pi": "dist/cli.js" - }, - "engines": { - "node": ">=22.19.0" - }, - "optionalDependencies": { - "@mariozechner/clipboard": "0.3.9" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@anthropic-ai/sdk": { - "version": "0.91.1", - "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.91.1.tgz", - "integrity": "sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==", - "license": "MIT", - "peer": true, - "dependencies": { - "json-schema-to-ts": "^3.1.1" - }, - "bin": { - "anthropic-ai-sdk": "bin/cli" - }, - "peerDependencies": { - "zod": "^3.25.0 || ^4.0.0" - }, - "peerDependenciesMeta": { - "zod": { - "optional": true - } - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/crc32": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/crc32/-/crc32-5.2.0.tgz", - "integrity": "sha512-nLbCWqQNgUiwwtFsen1AdzAtvuLRsQS8rYgMuxCrdKf9kOssamGLuPwyTY9wyYblNr9+1XM8v6zoDTPPSIeANg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=16.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/sha256-browser": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-browser/-/sha256-browser-5.2.0.tgz", - "integrity": "sha512-AXfN/lGotSQwu6HNcEsIASo7kWXZ5HYWvfOmSNKDsEqC4OashTp8alTmaz+F7TC2L083SFv5RdB+qU3Vs1kZqw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/sha256-js": "^5.2.0", - "@aws-crypto/supports-web-crypto": "^5.2.0", - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "@aws-sdk/util-locate-window": "^3.0.0", - "@smithy/util-utf8": "^2.0.0", - "tslib": "^2.6.2" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/sha256-js": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/sha256-js/-/sha256-js-5.2.0.tgz", - "integrity": "sha512-FFQQyu7edu4ufvIZ+OadFpHHOt+eSTBaYaki44c+akjg7qZg9oOQeLlk77F6tSYqjDAFClrHJk9tMf0HdVyOvA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/util": "^5.2.0", - "@aws-sdk/types": "^3.222.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=16.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/supports-web-crypto": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/supports-web-crypto/-/supports-web-crypto-5.2.0.tgz", - "integrity": "sha512-iAvUotm021kM33eCdNfwIN//F77/IADDSs58i+MDaOqFrVjZo9bAal0NK7HurRuWLLpF1iLX7gbWrjHjeo+YFg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "tslib": "^2.6.2" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-crypto/util": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/@aws-crypto/util/-/util-5.2.0.tgz", - "integrity": "sha512-4RkU9EsI6ZpBve5fseQlGNUWKMa1RLPQ1dnjnQoe07ldfIzcsGb5hC5W0Dm7u423KWzawlrpbjXBrXCEv9zazQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/types": "^3.222.0", - "@smithy/util-utf8": "^2.0.0", - "tslib": "^2.6.2" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/client-bedrock-runtime": { - "version": "3.1048.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.1048.0.tgz", - "integrity": "sha512-u+NT61JZEkRFtpL0CAw1N1dwxnaLgwVXQl/zjJxTGgLyS/jTIdg2SdoEoCTHxgDyCnqa1HEi9QOoE9/pYRNpOQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/sha256-browser": "5.2.0", - "@aws-crypto/sha256-js": "5.2.0", - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/credential-provider-node": "^3.972.42", - "@aws-sdk/eventstream-handler-node": "^3.972.16", - "@aws-sdk/middleware-eventstream": "^3.972.12", - "@aws-sdk/middleware-websocket": "^3.972.19", - "@aws-sdk/token-providers": "3.1048.0", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/fetch-http-handler": "^5.4.2", - "@smithy/node-http-handler": "^4.7.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/core": { - "version": "3.974.11", - "resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.974.11.tgz", - "integrity": "sha512-QpnINq5FZH6EOaDEkmHdT7eUunbvD27pDNQypaWjFyYz7Zl1q3UCMQErBZxpmfGfI7MvI2TlK8KTkgNpv8b1ug==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/types": "^3.973.8", - "@aws-sdk/xml-builder": "^3.972.24", - "@aws/lambda-invoke-store": "^0.2.2", - "@smithy/core": "^3.24.2", - "@smithy/signature-v4": "^5.4.2", - "@smithy/types": "^4.14.1", - "bowser": "^2.11.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-env": { - "version": "3.972.37", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.37.tgz", - "integrity": "sha512-/jpPvEh6f7ntmIzf7dNxoNX6Q8vt8UpesCjbW6mFfk4V1NW6bIy9qxcQ6WbA8As5yQhsZOe+xeNd4xHX8kdY2Q==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-http": { - "version": "3.972.39", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.39.tgz", - "integrity": "sha512-pIgTpisWyWg7X1bUbzSjuUYosYTD0Ghz2M0hkSTmb3a6i3qV3uU+NYJPI/E2XSC0HcsZh5rsLPzeXrkb2DS0Cg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/fetch-http-handler": "^5.4.2", - "@smithy/node-http-handler": "^4.7.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-ini": { - "version": "3.972.41", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.972.41.tgz", - "integrity": "sha512-u2tyjaxJJzW8UtW4SM1ZcPMDwO6y+kV+llvou+Adts0FAKyzes5jG4izQN+KX3yE8ZROpS5y1LJ//xL2iSf76w==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/credential-provider-env": "^3.972.37", - "@aws-sdk/credential-provider-http": "^3.972.39", - "@aws-sdk/credential-provider-login": "^3.972.41", - "@aws-sdk/credential-provider-process": "^3.972.37", - "@aws-sdk/credential-provider-sso": "^3.972.41", - "@aws-sdk/credential-provider-web-identity": "^3.972.41", - "@aws-sdk/nested-clients": "^3.997.9", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/credential-provider-imds": "^4.3.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-login": { - "version": "3.972.41", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.41.tgz", - "integrity": "sha512-0LBitxXiAiaE5nlFPfpNIww/8FRY/I7WIndWsc9GmNFOM7cE1wNpVNQEGEk9Outg5l8xl+3vybxFyUy4l9q/LQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/nested-clients": "^3.997.9", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-node": { - "version": "3.972.42", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.42.tgz", - "integrity": "sha512-D4oon2zbqqsWOJUM99Gm3/ZyJ0IJvTXVN3PyloGb3kQEyI36fjCZheZj422lAgTWWd6TSHgiImLt3RIaLdv3dQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/credential-provider-env": "^3.972.37", - "@aws-sdk/credential-provider-http": "^3.972.39", - "@aws-sdk/credential-provider-ini": "^3.972.41", - "@aws-sdk/credential-provider-process": "^3.972.37", - "@aws-sdk/credential-provider-sso": "^3.972.41", - "@aws-sdk/credential-provider-web-identity": "^3.972.41", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/credential-provider-imds": "^4.3.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-process": { - "version": "3.972.37", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.37.tgz", - "integrity": "sha512-7nVaHBUaWIddASYfVaA9O4D5ZVjewU3sCol9WqZPGfW0nR+0WqE0xHZnD/U2L33PlOB8KNXGKZ6wOES/QijKzg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-sso": { - "version": "3.972.41", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.972.41.tgz", - "integrity": "sha512-IOWAWEHe5LkjSKkkUUX9ciV6Y1scHTsnfEkdt5yyC4Slrc7AGbkLPrpntjqh18ksJAMOaVhoBsO8p2WyTcY2wQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/nested-clients": "^3.997.9", - "@aws-sdk/token-providers": "3.1048.0", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/credential-provider-web-identity": { - "version": "3.972.41", - "resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.41.tgz", - "integrity": "sha512-mbACk9Yypa8nm4iGZLs0PofOXEcTDOUw6wDnsPXNDNSd2WNXs1tSo+6nc/fh0jLYdfVZThhBL98PHW4aXFsG5A==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/nested-clients": "^3.997.9", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/eventstream-handler-node": { - "version": "3.972.16", - "resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.16.tgz", - "integrity": "sha512-yedpPgKftqjU5SlPFHfqWpOw6xSCRieWRG1euWOlXn4WJxt2VX92VprCa2PpSOXjVCAeK6dTjW9eJRXVig9yGA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/middleware-eventstream": { - "version": "3.972.12", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.12.tgz", - "integrity": "sha512-tHTHHCHNrq6XklQvlzHBDJG4Iuhh7NVPRdtmvP+nHFA+5sxPlIDzlAHHgfoYHGvT3NXP1yVP/L5c3opUn6T3Qg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/middleware-websocket": { - "version": "3.972.19", - "resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.19.tgz", - "integrity": "sha512-mkEhOGYozqKQkbFaVrjwr0faiwwZza1v5/jSY6Tucm3bD+uKTazIUH/4Yo6aMnQD2ua2W9cMP6s8mvwTcjtqHw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/fetch-http-handler": "^5.4.2", - "@smithy/signature-v4": "^5.4.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">= 14.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/nested-clients": { - "version": "3.997.9", - "resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.9.tgz", - "integrity": "sha512-jPR3rnmRI4hWYyzfmTGBr7NblMp8QYYeflHXba1H6+7CGrWVqWKQzaXFQ4qbExqPRsXN3T3L3JxFhr6aouXUGQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/sha256-browser": "5.2.0", - "@aws-crypto/sha256-js": "5.2.0", - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/signature-v4-multi-region": "^3.996.27", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/fetch-http-handler": "^5.4.2", - "@smithy/node-http-handler": "^4.7.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/signature-v4-multi-region": { - "version": "3.996.27", - "resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.27.tgz", - "integrity": "sha512-0Phbz4t6HI3D3skxvG2uI+VWU034/nSIw1T8d+FPzzQG9EQTrw94o9mOKO2Gv3n3Oc8P7JD7RAUxkoneLWv5Eg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/signature-v4": "^5.4.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/token-providers": { - "version": "3.1048.0", - "resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1048.0.tgz", - "integrity": "sha512-k0y/GcuesuSfWyUM0WamrGyeZmltRYaPbHO82UDA6mZ/doB+FOHKutikPAtSXMn/hDz970cF+iRuuiYO9VEbAA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-sdk/core": "^3.974.11", - "@aws-sdk/nested-clients": "^3.997.9", - "@aws-sdk/types": "^3.973.8", - "@smithy/core": "^3.24.2", - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/types": { - "version": "3.973.8", - "resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.973.8.tgz", - "integrity": "sha512-gjlAdtHMbtR9X5iIhVUvbVcy55KnznpC6bkDUWW9z915bi0ckdUr5cjf16Kp6xq0bP5HBD2xzgbL9F9Quv5vUw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/types": "^4.14.1", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/util-locate-window": { - "version": "3.965.5", - "resolved": "https://registry.npmjs.org/@aws-sdk/util-locate-window/-/util-locate-window-3.965.5.tgz", - "integrity": "sha512-WhlJNNINQB+9qtLtZJcpQdgZw3SCDCpXdUJP7cToGwHbCWCnRckGlc6Bx/OhWwIYFNAn+FIydY8SZ0QmVu3xTQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws-sdk/xml-builder": { - "version": "3.972.24", - "resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.24.tgz", - "integrity": "sha512-V8z5YcDPfsvzrBlj0xR1vhRtocblhYbqdreCJB/voGd4Sr5zjNAeWxexbnqVtskTJe0vFb5KMqbSL++ePl+zRw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@nodable/entities": "2.1.0", - "@smithy/types": "^4.14.1", - "fast-xml-parser": "5.7.3", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=20.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@aws/lambda-invoke-store": { - "version": "0.2.4", - "resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.2.4.tgz", - "integrity": "sha512-iY8yvjE0y651BixKNPgmv1WrQc+GZ142sb0z4gYnChDDY2YqI4P/jsSopBWrKfAt7LOJAkOXt7rC/hms+WclQQ==", - "license": "Apache-2.0", - "peer": true, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@babel/runtime": { - "version": "7.29.2", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz", - "integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==", - "license": "MIT", - "peer": true, - "engines": { - "node": ">=6.9.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core": { - "version": "0.78.1", - "resolved": "https://registry.npmjs.org/@earendil-works/pi-agent-core/-/pi-agent-core-0.78.1.tgz", - "license": "MIT", - "peer": true, - "dependencies": { - "@earendil-works/pi-ai": "^0.78.1", - "ignore": "7.0.5", - "typebox": "1.1.38", - "yaml": "2.9.0" - }, - "engines": { - "node": ">=22.19.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai": { - "version": "0.78.1", - "resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.78.1.tgz", - "license": "MIT", - "peer": true, - "dependencies": { - "@anthropic-ai/sdk": "0.91.1", - "@aws-sdk/client-bedrock-runtime": "3.1048.0", - "@google/genai": "1.52.0", - "@mistralai/mistralai": "2.2.1", - "@smithy/node-http-handler": "4.7.3", - "http-proxy-agent": "7.0.2", - "https-proxy-agent": "7.0.6", - "openai": "6.26.0", - "partial-json": "0.1.7", - "typebox": "1.1.38" + "sharp": "^0.35.3" }, "bin": { - "pi-ai": "dist/cli.js" - }, - "engines": { - "node": ">=22.19.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui": { - "version": "0.78.1", - "resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.78.1.tgz", - "license": "MIT", - "peer": true, - "dependencies": { - "get-east-asian-width": "1.6.0", - "marked": "15.0.12" - }, - "engines": { - "node": ">=22.19.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@google/genai": { - "version": "1.52.0", - "resolved": "https://registry.npmjs.org/@google/genai/-/genai-1.52.0.tgz", - "integrity": "sha512-gwSvbpiN/17O9TbsqSsE/OzZcpv5Fo4RQjdngGgogtuB9RsyJ8ZHhX5KjHj1bp5N9snN2eK8LDGXSaWW2hof8Q==", - "hasInstallScript": true, - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "google-auth-library": "^10.3.0", - "p-retry": "^4.6.2", - "protobufjs": "^7.5.4", - "ws": "^8.18.0" - }, - "engines": { - "node": ">=20.0.0" - }, - "peerDependencies": { - "@modelcontextprotocol/sdk": "^1.25.2" + "visual-primitives": "dist/cli.js", + "vp": "dist/cli.js" }, - "peerDependenciesMeta": { - "@modelcontextprotocol/sdk": { - "optional": true - } - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard/-/clipboard-0.3.9.tgz", - "integrity": "sha512-ABnA53mdfkGZwOFUdZNv2S0CWGO/EIuPj8Vv9xmBFmSYg/qFc7ihO6q5FcQjvoE67kZpWkEc4AhD6B/os04yuA==", - "license": "MIT", - "optional": true, - "peer": true, - "engines": { - "node": ">= 10" + "devDependencies": { + "esbuild": "^0.25.0" }, - "optionalDependencies": { - "@mariozechner/clipboard-darwin-arm64": "0.3.9", - "@mariozechner/clipboard-darwin-universal": "0.3.9", - "@mariozechner/clipboard-darwin-x64": "0.3.9", - "@mariozechner/clipboard-linux-arm64-gnu": "0.3.9", - "@mariozechner/clipboard-linux-arm64-musl": "0.3.9", - "@mariozechner/clipboard-linux-riscv64-gnu": "0.3.9", - "@mariozechner/clipboard-linux-x64-gnu": "0.3.9", - "@mariozechner/clipboard-linux-x64-musl": "0.3.9", - "@mariozechner/clipboard-win32-arm64-msvc": "0.3.9", - "@mariozechner/clipboard-win32-x64-msvc": "0.3.9" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-arm64": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-arm64/-/clipboard-darwin-arm64-0.3.9.tgz", - "integrity": "sha512-BfgV7vCEWZwJwZJw03r6bP5+tf0iI/ANuQYCxi9RNn7FrWB3yzGuMKCrNLRl6V761vXRdL8+OqZ0wd4TqlsNOQ==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "darwin" - ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=22.18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-universal": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-universal/-/clipboard-darwin-universal-0.3.9.tgz", - "integrity": "sha512-BGGR4iA9Z2shAjI65eI5xtyb3LYNlDW9X3gxKxDbqtbnREohsrqznov6zpKoIrsRWpzlYVEdKphS7ksJ0/ndSQ==", + "node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", "license": "MIT", "optional": true, - "os": [ - "darwin" - ], - "peer": true, - "engines": { - "node": ">= 10" + "dependencies": { + "tslib": "^2.4.0" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-darwin-x64": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-darwin-x64/-/clipboard-darwin-x64-0.3.9.tgz", - "integrity": "sha512-4kURmCbS6nt8uYhtmWpUcJWyPHfmAr5dTpXD1nO3pIfa+TSQ9DbrGOYCKH+aEFW47XhQ4Vp8ZTszie+wfFvDKg==", + "node_modules/@esbuild/aix-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", + "integrity": "sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==", "cpu": [ - "x64" + "ppc64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "darwin" + "aix" ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-arm64-gnu": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-gnu/-/clipboard-linux-arm64-gnu-0.3.9.tgz", - "integrity": "sha512-g59OkUGP2DDfCOIKypHeYgv2M55u/cKvXa5dSxFbEJ34XvIQMdcVmpKCkGUro3ZgefXiGVdwguvTMQGpHWzIXw==", + "node_modules/@esbuild/android-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.25.12.tgz", + "integrity": "sha512-VJ+sKvNA/GE7Ccacc9Cha7bpS8nyzVv0jdVgwNDaR4gDMC/2TTRc33Ip8qrNYUcpkOHUT5OZ0bUcNNVZQ9RLlg==", "cpu": [ - "arm64" - ], - "libc": [ - "glibc" + "arm" ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "linux" + "android" ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-arm64-musl": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-arm64-musl/-/clipboard-linux-arm64-musl-0.3.9.tgz", - "integrity": "sha512-AGuJdgKsmJdm4Pych7kv3sqe591ERRaAHW3xjLooiFzn8J+PxUyof++7YZrB5Y5tpnTO+K18Og3taj2NpluCRQ==", + "node_modules/@esbuild/android-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.25.12.tgz", + "integrity": "sha512-6AAmLG7zwD1Z159jCKPvAxZd4y/VTO0VkprYy+3N2FtJ8+BQWFXU+OxARIwA46c5tdD9SsKGZ/1ocqBS/gAKHg==", "cpu": [ "arm64" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "linux" + "android" ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-riscv64-gnu": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-riscv64-gnu/-/clipboard-linux-riscv64-gnu-0.3.9.tgz", - "integrity": "sha512-DXBEAiuMpk7dhS1a9NzNxVAFi1vaKoPu7rQNgY8LIDLGrK3lnIp3nT10DUum+PKVJoJppIP+NAA8IZe4DMNDPw==", + "node_modules/@esbuild/android-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.25.12.tgz", + "integrity": "sha512-5jbb+2hhDHx5phYR2By8GTWEzn6I9UqR11Kwf22iKbNpYrsmRB18aX/9ivc5cabcUiAT/wM+YIZ6SG9QO6a8kg==", "cpu": [ - "riscv64" - ], - "libc": [ - "glibc" + "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "linux" + "android" ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-x64-gnu": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-gnu/-/clipboard-linux-x64-gnu-0.3.9.tgz", - "integrity": "sha512-WORrMLd6EpElEME7JRKfSaY34nW1P5LbdgK5YNCS1ncG2LqmITsSMEJ8nh2mpvxb3TxqbOOKgY7k9eMJYlW9Mw==", + "node_modules/@esbuild/darwin-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.25.12.tgz", + "integrity": "sha512-N3zl+lxHCifgIlcMUP5016ESkeQjLj/959RxxNYIthIg+CQHInujFuXeWbWMgnTo4cp5XVHqFPmpyu9J65C1Yg==", "cpu": [ - "x64" - ], - "libc": [ - "glibc" + "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "linux" + "darwin" ], - "peer": true, "engines": { - "node": ">= 10" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-linux-x64-musl": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-linux-x64-musl/-/clipboard-linux-x64-musl-0.3.9.tgz", - "integrity": "sha512-/DHn+1DrfL6oRaPPWXaOKvonFFrni666fxd+zFqiQEfvBH0tsHVWjq9iqBk0oDp0qaPA72lIMy5BptxISBEhZQ==", + "node_modules/@esbuild/darwin-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.25.12.tgz", + "integrity": "sha512-HQ9ka4Kx21qHXwtlTUVbKJOAnmG1ipXhdWTmNXiPzPfWKpXqASVcWdnf2bnL73wgjNrFXAa3yYvBSd9pzfEIpA==", "cpu": [ "x64" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ - "linux" + "darwin" ], - "peer": true, "engines": { - "node": ">= 10" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-win32-arm64-msvc": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-arm64-msvc/-/clipboard-win32-arm64-msvc-0.3.9.tgz", - "integrity": "sha512-O5FHD3ErkMwMhNzAfu3ggy0ug4z7btZuoQgwwxlzPrwV2bxlD6WDpqBY4NCgICAgZdDKdp+loUEKVAVt8aYnhQ==", - "cpu": [ - "arm64" - ], - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "peer": true, - "engines": { - "node": ">= 10" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mariozechner/clipboard-win32-x64-msvc": { - "version": "0.3.9", - "resolved": "https://registry.npmjs.org/@mariozechner/clipboard-win32-x64-msvc/-/clipboard-win32-x64-msvc-0.3.9.tgz", - "integrity": "sha512-ihQC3EufqEY81vhXBgVBtK4prL+wc62zJsSvxrgz7K1hsdt6OObz6v9p3Rn1OG3GJksTTKMJF0u/guMISHPhSA==", - "cpu": [ - "x64" - ], - "license": "MIT", - "optional": true, - "os": [ - "win32" - ], - "peer": true, - "engines": { - "node": ">= 10" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@mistralai/mistralai": { - "version": "2.2.1", - "resolved": "https://registry.npmjs.org/@mistralai/mistralai/-/mistralai-2.2.1.tgz", - "integrity": "sha512-uKU8CZmL2RzYKmplsU01hii4p3pe4HqJefpWNRWXm1Tcm0Sm4xXfwSLIy4k7ZCPlbETCGcp69E7hZs+WOJ5itQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "ws": "^8.18.0", - "zod": "^3.25.0 || ^4.0.0", - "zod-to-json-schema": "^3.25.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@nodable/entities": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.1.0.tgz", - "integrity": "sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/nodable" - } - ], - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/aspromise": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz", - "integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/base64": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz", - "integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/codegen": { - "version": "2.0.5", - "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz", - "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/eventemitter": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.0.tgz", - "integrity": "sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/fetch": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz", - "integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==", - "license": "BSD-3-Clause", - "peer": true, - "dependencies": { - "@protobufjs/aspromise": "^1.1.1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/float": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz", - "integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/inquire": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.2.tgz", - "integrity": "sha512-pa0vFRuws4wkvaXKK1uXZMAwAX4/t8ANaJo45iw/oQHNQ9q5xUzwgFmVJGXiga2BeN+zpX7Vf9vmsiIa2J+MUw==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/path": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz", - "integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/pool": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz", - "integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@protobufjs/utf8": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz", - "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@silvia-odwyer/photon-node": { - "version": "0.3.4", - "resolved": "https://registry.npmjs.org/@silvia-odwyer/photon-node/-/photon-node-0.3.4.tgz", - "integrity": "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==", - "license": "Apache-2.0", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/core": { - "version": "3.24.3", - "resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.24.3.tgz", - "integrity": "sha512-Ep/7tPamGY8mgESE3LyLKtxJyy6U52WWAqr/3wial47Sj4u3PiIF73AOGI27UyLy9duTkhZbgzodOfLV4TduZg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@aws-crypto/crc32": "5.2.0", - "@smithy/types": "^4.14.2", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/credential-provider-imds": { - "version": "4.3.3", - "resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.3.3.tgz", - "integrity": "sha512-I2Bti0DKFo2IJyN28ijCsx51BAumEYR4/1yZ1FXyBygy9MqbnMqCev4JPth/MbpRfBSRAX35hITSnAdJRo1u5w==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/core": "^3.24.3", - "@smithy/types": "^4.14.2", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/fetch-http-handler": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.4.3.tgz", - "integrity": "sha512-F+DRf8IJazRJgYog2A/yJK7eYVc0rqTlRzO+5ZxjJd4WkZoKz0IJRncf7G6t1pdVT3kryJcwuTFhN1c5m6N47A==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/core": "^3.24.3", - "@smithy/types": "^4.14.2", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/is-array-buffer": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/is-array-buffer/-/is-array-buffer-2.2.0.tgz", - "integrity": "sha512-GGP3O9QFD24uGeAXYUjwSTXARoqpZykHadOmA8G5vfJPK0/DC67qa//0qvqrJzL1xc8WQWX7/yc7fwudjPHPhA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/node-http-handler": { - "version": "4.7.3", - "resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.7.3.tgz", - "integrity": "sha512-/jPhevcTFPMVl6KNjbaI47iOg1zxC7IsnX4PQDGVZKMFceOXtB8IEYaB7a9VvkP/3oC60WzTeKocvSI7vLT0vA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/core": "^3.24.3", - "@smithy/types": "^4.14.2", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/signature-v4": { - "version": "5.4.3", - "resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.4.3.tgz", - "integrity": "sha512-53+75QuPl6DL+ct6vVEB51FDO5oulXr20TPV46VvJZg76lIlXNWfxi8j+G2V/t0I2qxCBOa3vX/8bmjrpFVo9g==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/core": "^3.24.3", - "@smithy/types": "^4.14.2", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/types": { - "version": "4.14.2", - "resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.14.2.tgz", - "integrity": "sha512-P+otAxbV4CqBybp7EkcJCrig63yE2E7PuNVOmilVMRcx/O+QDzGULTrKsq4DV13gSfak9ObPrWaHl/9bL5YcWw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=18.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/util-buffer-from": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@smithy/util-buffer-from/-/util-buffer-from-2.2.0.tgz", - "integrity": "sha512-IJdWBbTcMQ6DA0gdNhh/BwrLkDR+ADW5Kr1aZmd4k3DIF6ezMV4R2NIAmT08wQJ3yUK82thHWmC/TnK/wpMMIA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/is-array-buffer": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@smithy/util-utf8": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/@smithy/util-utf8/-/util-utf8-2.3.0.tgz", - "integrity": "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "@smithy/util-buffer-from": "^2.2.0", - "tslib": "^2.6.2" - }, - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/@types/node": { - "version": "22.19.19", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz", - "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==", - "license": "MIT", - "peer": true, - "dependencies": { - "undici-types": "~6.21.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/agent-base": { - "version": "7.1.4", - "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz", - "integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==", - "license": "MIT", - "peer": true, - "engines": { - "node": ">= 14" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/balanced-match": { - "version": "4.0.4", - "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz", - "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==", - "license": "MIT", - "peer": true, - "engines": { - "node": "18 || 20 || >=22" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/base64-js": { - "version": "1.5.1", - "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz", - "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } - ], - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/bignumber.js": { - "version": "9.3.1", - "resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz", - "integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==", - "license": "MIT", - "peer": true, - "engines": { - "node": "*" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/bowser": { - "version": "2.14.1", - "resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz", - "integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/brace-expansion": { - "version": "5.0.6", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz", - "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==", - "license": "MIT", - "peer": true, - "dependencies": { - "balanced-match": "^4.0.2" - }, - "engines": { - "node": "18 || 20 || >=22" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/buffer-equal-constant-time": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz", - "integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==", - "license": "BSD-3-Clause", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/chalk": { - "version": "5.6.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.6.2.tgz", - "integrity": "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==", - "license": "MIT", - "peer": true, - "engines": { - "node": "^12.17.0 || ^14.13 || >=16.0.0" - }, - "funding": { - "url": "https://github.com/chalk/chalk?sponsor=1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/cross-spawn": { - "version": "7.0.6", - "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", - "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", - "license": "MIT", - "peer": true, - "dependencies": { - "path-key": "^3.1.0", - "shebang-command": "^2.0.0", - "which": "^2.0.1" - }, - "engines": { - "node": ">= 8" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/data-uri-to-buffer": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz", - "integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==", - "license": "MIT", - "peer": true, - "engines": { - "node": ">= 12" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/debug": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", - "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", - "license": "MIT", - "peer": true, - "dependencies": { - "ms": "^2.1.3" - }, - "engines": { - "node": ">=6.0" - }, - "peerDependenciesMeta": { - "supports-color": { - "optional": true - } - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/diff": { - "version": "8.0.4", - "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.4.tgz", - "integrity": "sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==", - "license": "BSD-3-Clause", - "peer": true, - "engines": { - "node": ">=0.3.1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/ecdsa-sig-formatter": { - "version": "1.0.11", - "resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz", - "integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "safe-buffer": "^5.0.1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/extend": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz", - "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/fast-xml-builder": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz", - "integrity": "sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "peer": true, - "dependencies": { - "path-expression-matcher": "^1.5.0", - "xml-naming": "^0.1.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/fast-xml-parser": { - "version": "5.7.3", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz", - "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "peer": true, - "dependencies": { - "@nodable/entities": "^2.1.0", - "fast-xml-builder": "^1.1.7", - "path-expression-matcher": "^1.5.0", - "strnum": "^2.2.3" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/fetch-blob": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz", - "integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/jimmywarting" - }, - { - "type": "paypal", - "url": "https://paypal.me/jimmywarting" - } - ], - "license": "MIT", - "peer": true, - "dependencies": { - "node-domexception": "^1.0.0", - "web-streams-polyfill": "^3.0.3" - }, - "engines": { - "node": "^12.20 || >= 14.13" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/formdata-polyfill": { - "version": "4.0.10", - "resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz", - "integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==", - "license": "MIT", - "peer": true, - "dependencies": { - "fetch-blob": "^3.1.2" - }, - "engines": { - "node": ">=12.20.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/gaxios": { - "version": "7.1.4", - "resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.4.tgz", - "integrity": "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "extend": "^3.0.2", - "https-proxy-agent": "^7.0.1", - "node-fetch": "^3.3.2" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/gcp-metadata": { - "version": "8.1.2", - "resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz", - "integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "gaxios": "^7.0.0", - "google-logging-utils": "^1.0.0", - "json-bigint": "^1.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/get-east-asian-width": { - "version": "1.6.0", - "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz", - "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==", - "license": "MIT", - "peer": true, - "engines": { - "node": ">=18" - }, - "funding": { - "url": "https://github.com/sponsors/sindresorhus" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/glob": { - "version": "13.0.6", - "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz", - "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==", - "license": "BlueOak-1.0.0", - "peer": true, - "dependencies": { - "minimatch": "^10.2.2", - "minipass": "^7.1.3", - "path-scurry": "^2.0.2" - }, - "engines": { - "node": "18 || 20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/google-auth-library": { - "version": "10.6.2", - "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.6.2.tgz", - "integrity": "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==", - "license": "Apache-2.0", - "peer": true, - "dependencies": { - "base64-js": "^1.3.0", - "ecdsa-sig-formatter": "^1.0.11", - "gaxios": "^7.1.4", - "gcp-metadata": "8.1.2", - "google-logging-utils": "1.1.3", - "jws": "^4.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/google-logging-utils": { - "version": "1.1.3", - "resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz", - "integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==", - "license": "Apache-2.0", - "peer": true, - "engines": { - "node": ">=14" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/graceful-fs": { - "version": "4.2.11", - "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", - "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", - "license": "ISC", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/highlight.js": { - "version": "10.7.3", - "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz", - "integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==", - "license": "BSD-3-Clause", - "peer": true, - "engines": { - "node": "*" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/hosted-git-info": { - "version": "9.0.3", - "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-9.0.3.tgz", - "integrity": "sha512-Hc+ghLoSt6QaYZUv0WBiIvmMDZuZZ7oaDvdH8MbfOO4lOsxdXLEvuC6ePoGs9H1X9oCLyq6+NVN0MKqD+ydxyg==", - "license": "ISC", - "peer": true, - "dependencies": { - "lru-cache": "^11.1.0" - }, - "engines": { - "node": "^20.17.0 || >=22.9.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/http-proxy-agent": { - "version": "7.0.2", - "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", - "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", - "license": "MIT", - "peer": true, - "dependencies": { - "agent-base": "^7.1.0", - "debug": "^4.3.4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/https-proxy-agent": { - "version": "7.0.6", - "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz", - "integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==", - "license": "MIT", - "peer": true, - "dependencies": { - "agent-base": "^7.1.2", - "debug": "4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/ignore": { - "version": "7.0.5", - "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz", - "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==", - "license": "MIT", - "peer": true, - "engines": { - "node": ">= 4" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/isexe": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", - "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", - "license": "ISC", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/jiti": { - "version": "2.7.0", - "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz", - "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==", - "license": "MIT", - "peer": true, - "bin": { - "jiti": "lib/jiti-cli.mjs" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/json-bigint": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz", - "integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==", - "license": "MIT", - "peer": true, - "dependencies": { - "bignumber.js": "^9.0.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/json-schema-to-ts": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz", - "integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==", - "license": "MIT", - "peer": true, - "dependencies": { - "@babel/runtime": "^7.18.3", - "ts-algebra": "^2.0.0" - }, - "engines": { - "node": ">=16" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/jwa": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz", - "integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==", - "license": "MIT", - "peer": true, - "dependencies": { - "buffer-equal-constant-time": "^1.0.1", - "ecdsa-sig-formatter": "1.0.11", - "safe-buffer": "^5.0.1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/jws": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz", - "integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==", - "license": "MIT", - "peer": true, - "dependencies": { - "jwa": "^2.0.1", - "safe-buffer": "^5.0.1" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/long": { - "version": "5.3.2", - "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz", - "integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==", - "license": "Apache-2.0", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/lru-cache": { - "version": "11.4.0", - "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz", - "integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==", - "license": "BlueOak-1.0.0", - "peer": true, - "engines": { - "node": "20 || >=22" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/marked": { - "version": "15.0.12", - "resolved": "https://registry.npmjs.org/marked/-/marked-15.0.12.tgz", - "integrity": "sha512-8dD6FusOQSrpv9Z1rdNMdlSgQOIP880DHqnohobOmYLElGEqAL/JvxvuxZO16r4HtjTlfPRDC1hbvxC9dPN2nA==", - "license": "MIT", - "peer": true, - "bin": { - "marked": "bin/marked.js" - }, - "engines": { - "node": ">= 18" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/minimatch": { - "version": "10.2.5", - "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz", - "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==", - "license": "BlueOak-1.0.0", - "peer": true, - "dependencies": { - "brace-expansion": "^5.0.5" - }, - "engines": { - "node": "18 || 20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/minipass": { - "version": "7.1.3", - "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz", - "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==", - "license": "BlueOak-1.0.0", - "peer": true, - "engines": { - "node": ">=16 || 14 >=14.17" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/ms": { - "version": "2.1.3", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", - "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/node-domexception": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz", - "integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==", - "deprecated": "Use your platform's native DOMException instead", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/jimmywarting" - }, - { - "type": "github", - "url": "https://paypal.me/jimmywarting" - } - ], - "license": "MIT", - "peer": true, - "engines": { - "node": ">=10.5.0" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/node-fetch": { - "version": "3.3.2", - "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz", - "integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==", - "license": "MIT", - "peer": true, - "dependencies": { - "data-uri-to-buffer": "^4.0.0", - "fetch-blob": "^3.1.4", - "formdata-polyfill": "^4.0.10" - }, - "engines": { - "node": "^12.20.0 || ^14.13.1 || >=16.0.0" - }, - "funding": { - "type": "opencollective", - "url": "https://opencollective.com/node-fetch" - } - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/openai": { - "version": "6.26.0", - "resolved": "https://registry.npmjs.org/openai/-/openai-6.26.0.tgz", - "integrity": "sha512-zd23dbWTjiJ6sSAX6s0HrCZi41JwTA1bQVs0wLQPZ2/5o2gxOJA5wh7yOAUgwYybfhDXyhwlpeQf7Mlgx8EOCA==", - "license": "Apache-2.0", - "peer": true, - "bin": { - "openai": "bin/cli" - }, - "peerDependencies": { - "ws": "^8.18.0", - "zod": "^3.25 || ^4.0" - }, - "peerDependenciesMeta": { - "ws": { - "optional": true - }, - "zod": { - "optional": true - } + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/p-retry": { - "version": "4.6.2", - "resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz", - "integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==", + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.25.12.tgz", + "integrity": "sha512-gA0Bx759+7Jve03K1S0vkOu5Lg/85dou3EseOGUes8flVOGxbhDDh/iZaoek11Y8mtyKPGF3vP8XhnkDEAmzeg==", + "cpu": [ + "arm64" + ], + "dev": true, "license": "MIT", - "peer": true, - "dependencies": { - "@types/retry": "0.12.0", - "retry": "^0.13.1" - }, + "optional": true, + "os": [ + "freebsd" + ], "engines": { - "node": ">=8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/p-retry/node_modules/@types/retry": { - "version": "0.12.0", - "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz", - "integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/partial-json": { - "version": "0.1.7", - "resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz", - "integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/path-expression-matcher": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/path-expression-matcher/-/path-expression-matcher-1.5.0.tgz", - "integrity": "sha512-cbrerZV+6rvdQrrD+iGMcZFEiiSrbv9Tfdkvnusy6y0x0GKBXREFg/Y65GhIfm0tnLntThhzCnfKwp1WRjeCyQ==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } + "node_modules/@esbuild/freebsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.25.12.tgz", + "integrity": "sha512-TGbO26Yw2xsHzxtbVFGEXBFH0FRAP7gtcPE7P5yP7wGy7cXK2oO7RyOhL5NLiqTlBh47XhmIUXuGciXEqYFfBQ==", + "cpu": [ + "x64" ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "freebsd" + ], "engines": { - "node": ">=14.0.0" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/path-key": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", - "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "node_modules/@esbuild/linux-arm": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.25.12.tgz", + "integrity": "sha512-lPDGyC1JPDou8kGcywY0YILzWlhhnRjdof3UlcoqYmS9El818LLfJJc3PXXgZHrHCAKs/Z2SeZtDJr5MrkxtOw==", + "cpu": [ + "arm" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">=8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/path-scurry": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz", - "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==", - "license": "BlueOak-1.0.0", - "peer": true, - "dependencies": { - "lru-cache": "^11.0.0", - "minipass": "^7.1.2" - }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.25.12.tgz", + "integrity": "sha512-8bwX7a8FghIgrupcxb4aUmYDLp8pX06rGh5HqDT7bB+8Rdells6mHvrFHHW2JAOPZUbnjUpKTLg6ECyzvas2AQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": "18 || 20 || >=22" - }, - "funding": { - "url": "https://github.com/sponsors/isaacs" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/proper-lockfile": { - "version": "4.1.2", - "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz", - "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==", + "node_modules/@esbuild/linux-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.25.12.tgz", + "integrity": "sha512-0y9KrdVnbMM2/vG8KfU0byhUN+EFCny9+8g202gYqSSVMonbsCfLjUO+rCci7pM0WBEtz+oK/PIwHkzxkyharA==", + "cpu": [ + "ia32" + ], + "dev": true, "license": "MIT", - "peer": true, - "dependencies": { - "graceful-fs": "^4.2.4", - "retry": "^0.12.0", - "signal-exit": "^3.0.2" + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/proper-lockfile/node_modules/retry": { - "version": "0.12.0", - "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz", - "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==", + "node_modules/@esbuild/linux-loong64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.25.12.tgz", + "integrity": "sha512-h///Lr5a9rib/v1GGqXVGzjL4TMvVTv+s1DPoxQdz7l/AYv6LDSxdIwzxkrPW438oUXiDtwM10o9PmwS/6Z0Ng==", + "cpu": [ + "loong64" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">= 4" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/protobufjs": { - "version": "7.5.9", - "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.9.tgz", - "integrity": "sha512-Od4muIm3HW1AouyHF5lONOf1FWo3hY1NbFDoy191X9GzhpgW1clCoaFjfVs2rKJNFYpTNJbje4cbAIDBZJ63ZA==", - "hasInstallScript": true, - "license": "BSD-3-Clause", - "peer": true, - "dependencies": { - "@protobufjs/aspromise": "^1.1.2", - "@protobufjs/base64": "^1.1.2", - "@protobufjs/codegen": "^2.0.5", - "@protobufjs/eventemitter": "^1.1.0", - "@protobufjs/fetch": "^1.1.1", - "@protobufjs/float": "^1.0.2", - "@protobufjs/inquire": "^1.1.2", - "@protobufjs/path": "^1.1.2", - "@protobufjs/pool": "^1.1.0", - "@protobufjs/utf8": "^1.1.1", - "@types/node": ">=13.7.0", - "long": "^5.0.0" - }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.25.12.tgz", + "integrity": "sha512-iyRrM1Pzy9GFMDLsXn1iHUm18nhKnNMWscjmp4+hpafcZjrr2WbT//d20xaGljXDBYHqRcl8HnxbX6uaA/eGVw==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">=12.0.0" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/retry": { - "version": "0.13.1", - "resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz", - "integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==", + "node_modules/@esbuild/linux-ppc64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.25.12.tgz", + "integrity": "sha512-9meM/lRXxMi5PSUqEXRCtVjEZBGwB7P/D4yT8UG/mwIdze2aV4Vo6U5gD3+RsoHXKkHCfSxZKzmDssVlRj1QQA==", + "cpu": [ + "ppc64" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">= 4" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/safe-buffer": { - "version": "5.2.1", - "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", - "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/feross" - }, - { - "type": "patreon", - "url": "https://www.patreon.com/feross" - }, - { - "type": "consulting", - "url": "https://feross.org/support" - } + "node_modules/@esbuild/linux-riscv64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.25.12.tgz", + "integrity": "sha512-Zr7KR4hgKUpWAwb1f3o5ygT04MzqVrGEGXGLnj15YQDJErYu/BGg+wmFlIDOdJp0PmB0lLvxFIOXZgFRrdjR0w==", + "cpu": [ + "riscv64" ], + "dev": true, "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/shebang-command": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", - "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", - "license": "MIT", - "peer": true, - "dependencies": { - "shebang-regex": "^3.0.0" - }, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">=8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/shebang-regex": { - "version": "3.0.0", - "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", - "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "node_modules/@esbuild/linux-s390x": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.25.12.tgz", + "integrity": "sha512-MsKncOcgTNvdtiISc/jZs/Zf8d0cl/t3gYWX8J9ubBnVOwlk65UIEEvgBORTiljloIWnBzLs4qhzPkJcitIzIg==", + "cpu": [ + "s390x" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">=8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/signal-exit": { - "version": "3.0.7", - "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz", - "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==", - "license": "ISC", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/strnum": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.3.0.tgz", - "integrity": "sha512-ums3KNd42PGyx5xaoVTO1mjU1bH3NpY4vsrVlnv9PNGqQj8wd7rJ6nEypLrJ7z5vxK5RP0yMLo6J/Gsm62DI5Q==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } + "node_modules/@esbuild/linux-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.25.12.tgz", + "integrity": "sha512-uqZMTLr/zR/ed4jIGnwSLkaHmPjOjJvnm6TVVitAa08SLS9Z0VM8wIRx7gWbJB5/J54YuIMInDquWyYvQLZkgw==", + "cpu": [ + "x64" ], + "dev": true, "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/ts-algebra": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz", - "integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/tslib": { - "version": "2.8.1", - "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", - "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "license": "0BSD", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/typebox": { - "version": "1.1.38", - "resolved": "https://registry.npmjs.org/typebox/-/typebox-1.1.38.tgz", - "integrity": "sha512-pZ0aQPmMmXoUvSbeuWf/Hzsc+avNw/Zd6VeE8CFgkVGWyuHPJvqeJJDeJqLve+K70LvjYIoleGcoJHPT17cWoA==", - "license": "MIT", - "peer": true - }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/undici": { - "version": "8.3.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-8.3.0.tgz", - "integrity": "sha512-TkUDgb6tl7KOGZ+7e8E3d2FYgUQgF6z5YypqjWmixVQSQERFcVrVg0ySADm2LVLRh5ljAaHTCR5Fmz3Q34rB7Q==", - "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "linux" + ], "engines": { - "node": ">=22.19.0" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/undici-types": { - "version": "6.21.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", - "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.25.12.tgz", + "integrity": "sha512-xXwcTq4GhRM7J9A8Gv5boanHhRa/Q9KLVmcyXHCTaM4wKfIpWkdXiMog/KsnxzJ0A1+nD+zoecuzqPmCRyBGjg==", + "cpu": [ + "arm64" + ], + "dev": true, "license": "MIT", - "peer": true + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/web-streams-polyfill": { - "version": "3.3.3", - "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz", - "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==", + "node_modules/@esbuild/netbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.25.12.tgz", + "integrity": "sha512-Ld5pTlzPy3YwGec4OuHh1aCVCRvOXdH8DgRjfDy/oumVovmuSzWfnSJg+VtakB9Cm0gxNO9BzWkj6mtO1FMXkQ==", + "cpu": [ + "x64" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "netbsd" + ], "engines": { - "node": ">= 8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/which": { - "version": "2.0.2", - "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", - "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", - "license": "ISC", - "peer": true, - "dependencies": { - "isexe": "^2.0.0" - }, - "bin": { - "node-which": "bin/node-which" - }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.25.12.tgz", + "integrity": "sha512-fF96T6KsBo/pkQI950FARU9apGNTSlZGsv1jZBAlcLL1MLjLNIWPBkj5NlSz8aAzYKg+eNqknrUJ24QBybeR5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], "engines": { - "node": ">= 8" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/ws": { - "version": "8.20.1", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz", - "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==", + "node_modules/@esbuild/openbsd-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.25.12.tgz", + "integrity": "sha512-MZyXUkZHjQxUvzK7rN8DJ3SRmrVrke8ZyRusHlP+kuwqTcfWLyqMOE3sScPPyeIXN/mDJIfGXvcMqCgYKekoQw==", + "cpu": [ + "x64" + ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "openbsd" + ], "engines": { - "node": ">=10.0.0" - }, - "peerDependencies": { - "bufferutil": "^4.0.1", - "utf-8-validate": ">=5.0.2" - }, - "peerDependenciesMeta": { - "bufferutil": { - "optional": true - }, - "utf-8-validate": { - "optional": true - } + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/xml-naming": { - "version": "0.1.0", - "resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.1.0.tgz", - "integrity": "sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.25.12.tgz", + "integrity": "sha512-rm0YWsqUSRrjncSXGA7Zv78Nbnw4XL6/dzr20cyrQf7ZmRcsovpcRBdhD43Nuk3y7XIoW2OxMVvwuRvk9XdASg==", + "cpu": [ + "arm64" ], + "dev": true, "license": "MIT", - "peer": true, + "optional": true, + "os": [ + "openharmony" + ], "engines": { - "node": ">=16.0.0" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/yaml": { - "version": "2.9.0", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", - "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", - "license": "ISC", - "peer": true, - "bin": { - "yaml": "bin.mjs" - }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.25.12.tgz", + "integrity": "sha512-3wGSCDyuTHQUzt0nV7bocDy72r2lI33QL3gkDNGkod22EsYl04sMf0qLb8luNKTOmgF/eDEDP5BFNwoBKH441w==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], "engines": { - "node": ">= 14.6" - }, - "funding": { - "url": "https://github.com/sponsors/eemeli" + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "node_modules/@esbuild/win32-arm64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.25.12.tgz", + "integrity": "sha512-rMmLrur64A7+DKlnSuwqUdRKyd3UE7oPJZmnljqEptesKM8wx9J8gx5u0+9Pq0fQQW8vqeKebwNXdfOyP+8Bsg==", + "cpu": [ + "arm64" + ], + "dev": true, "license": "MIT", - "peer": true, - "funding": { - "url": "https://github.com/sponsors/colinhacks" + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" } }, - "node_modules/@earendil-works/pi-coding-agent/node_modules/zod-to-json-schema": { - "version": "3.25.2", - "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", - "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", - "license": "ISC", - "peer": true, - "peerDependencies": { - "zod": "^3.25.28 || ^4" + "node_modules/@esbuild/win32-ia32": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.25.12.tgz", + "integrity": "sha512-HkqnmmBoCbCwxUKKNPBixiWDGCpQGVsrQfJoVGYLPT41XWF8lHuE5N6WhVia2n4o5QK5M4tYr21827fNhi4byQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" } }, - "node_modules/@emnapi/runtime": { - "version": "1.11.0", - "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.0.tgz", - "integrity": "sha512-55coeOFKHv1ywEcUXJtWU5f+Jr/W5tZDvZig8DLKSwUN1JpROQ4rk/SNOQiFWmaR/VKF4zuFyW1B8JduOSv6Pg==", + "node_modules/@esbuild/win32-x64": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.25.12.tgz", + "integrity": "sha512-alJC0uCZpTFrSL0CCDjcgleBXPnCrEAhTBILpeAp7M/OFgoqtAetfBzX0xM00MUsVVPpVjlPuMbREqnZCXaTnA==", + "cpu": [ + "x64" + ], + "dev": true, "license": "MIT", "optional": true, - "dependencies": { - "tslib": "^2.4.0" + "os": [ + "win32" + ], + "engines": { + "node": ">=18" } }, "node_modules/@img/colour": { @@ -1972,9 +484,9 @@ } }, "node_modules/@img/sharp-darwin-arm64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz", - "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.3.tgz", + "integrity": "sha512-RMnFX7YQsMoh7lWfcM4NEHHymBX/rLuKNPVM84XE9ONPcaSCDgE7CHIHpSgPcO2xcRthgBy1HfNO319mwhIAkg==", "cpu": [ "arm64" ], @@ -1984,19 +496,19 @@ "darwin" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-darwin-arm64": "1.2.4" + "@img/sharp-libvips-darwin-arm64": "1.3.2" } }, "node_modules/@img/sharp-darwin-x64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz", - "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.3.tgz", + "integrity": "sha512-Xo+5uFBtLN0BKqieTxiFzFPQAUlBbbH5iBKyRX/z1JrbnYsHTfKJnUfL8+p2TPXr1pXqao4eeL4Rl144uDpK9w==", "cpu": [ "x64" ], @@ -2006,19 +518,38 @@ "darwin" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-darwin-x64": "1.2.4" + "@img/sharp-libvips-darwin-x64": "1.3.2" + } + }, + "node_modules/@img/sharp-freebsd-wasm32": { + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.3.tgz", + "integrity": "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg==", + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "dependencies": { + "@img/sharp-wasm32": "0.35.3" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-libvips-darwin-arm64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz", - "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.2.tgz", + "integrity": "sha512-9J6ypZFpQBj4YnePGoq/S38w6nz+vqg5WZLrLGY4YuSemdMq47GMLBPO42MzwdGwpg/agZ7xzZcFHa48xlywfg==", "cpu": [ "arm64" ], @@ -2032,9 +563,9 @@ } }, "node_modules/@img/sharp-libvips-darwin-x64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz", - "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.2.tgz", + "integrity": "sha512-m2pW1n6cns9VaubNwsZ+c3CRYjxNQWgJ5gPlnL1nbBcpkBvFm6SCFN5o0psFHI8w9n11NKhFkeEDns98tiqbEw==", "cpu": [ "x64" ], @@ -2048,9 +579,9 @@ } }, "node_modules/@img/sharp-libvips-linux-arm": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz", - "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.2.tgz", + "integrity": "sha512-1eMLzy92I4J6rmi4mAT8yC3HxOtniyGELlzGbNMLLeqe052ahFQ0h6LFq+lh5DsDIdYViIDst08abvSbcEdLXQ==", "cpu": [ "arm" ], @@ -2067,9 +598,9 @@ } }, "node_modules/@img/sharp-libvips-linux-arm64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz", - "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.2.tgz", + "integrity": "sha512-dqVSFynCox4C/J8kT16V7SIFAns0IjgLwkvYT7p8LQVmJ5OS5b6tI9IGflxTeuBS//zXeFIUbwt5dwxyZ17cnA==", "cpu": [ "arm64" ], @@ -2086,9 +617,9 @@ } }, "node_modules/@img/sharp-libvips-linux-ppc64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz", - "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.2.tgz", + "integrity": "sha512-3z0NHDxD6n5I9gc05U1eW1AyRm+Gznzq3naMrthPNqE6oYykcogW0l/jfpJdjYnuNl8R7yI9pNbE1XiUeyq0Aw==", "cpu": [ "ppc64" ], @@ -2105,9 +636,9 @@ } }, "node_modules/@img/sharp-libvips-linux-riscv64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz", - "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.2.tgz", + "integrity": "sha512-bsb4rI+NldGOsXuej2r8OdSS8+zXDVaCWxyWrcv6kneTOlgAHtZABRzBBCwdsPiD90J4myNJuHpg6kA20ImW/w==", "cpu": [ "riscv64" ], @@ -2124,9 +655,9 @@ } }, "node_modules/@img/sharp-libvips-linux-s390x": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz", - "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.2.tgz", + "integrity": "sha512-/ABshyj8gCpyIrNXnHn4LorDJ0HHm1VhXPBlxZ8zAtfVPAaSafXPGn+sUSIRiwaSBy0mmFjSjiXI5mkcwdChKQ==", "cpu": [ "s390x" ], @@ -2143,9 +674,9 @@ } }, "node_modules/@img/sharp-libvips-linux-x64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz", - "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.2.tgz", + "integrity": "sha512-ITPEtgffGJ0S6G9dRyw/366tJQqFRcHWPHhC+Stpg3Z8AEMrDrTr2lhdz4f/Y/HMbRh//7Z5mBzEpVdi62Oc3w==", "cpu": [ "x64" ], @@ -2162,9 +693,9 @@ } }, "node_modules/@img/sharp-libvips-linuxmusl-arm64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz", - "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.2.tgz", + "integrity": "sha512-zE9EdiUzUmg5mDT5a1rk5fYJ6GWPloTwWBYDS14naqHsL+EaMpDj1AWnpLgh3u0YCORv2Tt50wrcrpYqkP97Kw==", "cpu": [ "arm64" ], @@ -2181,9 +712,9 @@ } }, "node_modules/@img/sharp-libvips-linuxmusl-x64": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz", - "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==", + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.2.tgz", + "integrity": "sha512-m0lrLiUt+lBYnCFr8qV/65yMR4E/c7/wf78I5eKTdkEakFAlZ9QlzEM3QIhhAwVeUhLAHLcCq7a7Vszq/oFNZQ==", "cpu": [ "x64" ], @@ -2200,9 +731,9 @@ } }, "node_modules/@img/sharp-linux-arm": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz", - "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.3.tgz", + "integrity": "sha512-affVWCTLooy8TSxbDx2qkzuDeaWLNVBA+P//FNBirHsXpP2fuBhk5AuboYUnrDnzoXes8GFjpTx0SBFOCRg+FA==", "cpu": [ "arm" ], @@ -2215,19 +746,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-arm": "1.2.4" + "@img/sharp-libvips-linux-arm": "1.3.2" } }, "node_modules/@img/sharp-linux-arm64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz", - "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.3.tgz", + "integrity": "sha512-QgKDspHPnrU+GQ55XPhGwyhC8acLVOOSyAvo1oVfFmrIXLkDNmGWzAfDZ4xK8oSA1qBQrALcHX0G5UZni/SuFQ==", "cpu": [ "arm64" ], @@ -2240,19 +771,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-arm64": "1.2.4" + "@img/sharp-libvips-linux-arm64": "1.3.2" } }, "node_modules/@img/sharp-linux-ppc64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz", - "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.3.tgz", + "integrity": "sha512-sMd8rDxmpLOwv/7N44klFjOD5DUO7FLdjiXDI0hoxYaf7Ar262dQIEkosE98bps+5HPLtp/EvNqeqQtOycP/IA==", "cpu": [ "ppc64" ], @@ -2265,19 +796,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-ppc64": "1.2.4" + "@img/sharp-libvips-linux-ppc64": "1.3.2" } }, "node_modules/@img/sharp-linux-riscv64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz", - "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.3.tgz", + "integrity": "sha512-0Eob78yjlYPfL5vMNWAW55l3R9Y6BQS/gOfe0ZcP9mEz9ohhKSt4im1hayiknXgf8AWrFqMvJcKIdmLmEe7yeQ==", "cpu": [ "riscv64" ], @@ -2290,19 +821,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-riscv64": "1.2.4" + "@img/sharp-libvips-linux-riscv64": "1.3.2" } }, "node_modules/@img/sharp-linux-s390x": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz", - "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.3.tgz", + "integrity": "sha512-KgAxQ0DxpNOq1rG2t5cgTgShJFGSuU7XO45cqC+1NVOuZnP6tlgZRuSYOfNupGkHID0o3cJOsw4DVeJpMovcGw==", "cpu": [ "s390x" ], @@ -2315,19 +846,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-s390x": "1.2.4" + "@img/sharp-libvips-linux-s390x": "1.3.2" } }, "node_modules/@img/sharp-linux-x64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz", - "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.3.tgz", + "integrity": "sha512-8pqvxubL2PGdhlPy6GLqzDYMUjyRmKAwKHYKixpdJYBUK7PJ0C029XdsnpFIdgRZG68fZiGdHVWcKPvtiPB4cA==", "cpu": [ "x64" ], @@ -2340,19 +871,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linux-x64": "1.2.4" + "@img/sharp-libvips-linux-x64": "1.3.2" } }, "node_modules/@img/sharp-linuxmusl-arm64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz", - "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.3.tgz", + "integrity": "sha512-Vz0iQjzzcSX3HCbfwFfCSG/9SCIqyO0mH2sXyiHaAYfBk0cRsCWXRyQYX0ovCK/PAQBbTzQ0dsPQHh5MAFL59w==", "cpu": [ "arm64" ], @@ -2365,19 +896,19 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linuxmusl-arm64": "1.2.4" + "@img/sharp-libvips-linuxmusl-arm64": "1.3.2" } }, "node_modules/@img/sharp-linuxmusl-x64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz", - "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.3.tgz", + "integrity": "sha512-6O1NPKcDVj9QEdg7Hx549EX8U0rp6yXQERqru6yRN7fGBn32UvIRJUlWnk+8xDCiG76hXVBbX82NZ/ZKr0euIg==", "cpu": [ "x64" ], @@ -2390,38 +921,54 @@ "linux" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-libvips-linuxmusl-x64": "1.2.4" + "@img/sharp-libvips-linuxmusl-x64": "1.3.2" } }, "node_modules/@img/sharp-wasm32": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz", - "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.3.tgz", + "integrity": "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w==", + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.11.1" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-webcontainers-wasm32": { + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.3.tgz", + "integrity": "sha512-2rnq7bX3NzeR2T4YWgz8qiG4h3TSdMe+vN1iQXpJleSJ3SM5zQ8Fy2SyyXAWlbxpEZ2Y+Z4u1BePgJEYbSy80Q==", "cpu": [ "wasm32" ], - "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "license": "Apache-2.0", "optional": true, "dependencies": { - "@emnapi/runtime": "^1.7.0" + "@img/sharp-wasm32": "0.35.3" }, "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-arm64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz", - "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.3.tgz", + "integrity": "sha512-4bPwFdMbeC4JQ8L8LOyWp6nsHcboP5fxkp6iPOXz2Vg49R42TuMs2whkJ5OAP4/Ul035qOzy0AecOF9VOscn4w==", "cpu": [ "arm64" ], @@ -2431,16 +978,16 @@ "win32" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-ia32": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz", - "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.3.tgz", + "integrity": "sha512-r53mXsBN6lFUDiST764SvgwUdHAqM4rPAiDzAmf4fLoB6X/rkfyTrLCg6+g17wJJiCmB3JYgHuUldCWUIRFSXw==", "cpu": [ "ia32" ], @@ -2450,16 +997,16 @@ "win32" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": "^20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" } }, "node_modules/@img/sharp-win32-x64": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz", - "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==", + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.3.tgz", + "integrity": "sha512-D4y1vNeZrIIJCN+uHaWVtH86B+aCrdMYYjicy9pXHvbGZeGYLLSd3wdVuC37FxVXlU1ARsk84eKWfWMXGYEqvA==", "cpu": [ "x64" ], @@ -2469,7 +1016,7 @@ "win32" ], "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" @@ -2484,10 +1031,52 @@ "node": ">=8" } }, + "node_modules/esbuild": { + "version": "0.25.12", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz", + "integrity": "sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.25.12", + "@esbuild/android-arm": "0.25.12", + "@esbuild/android-arm64": "0.25.12", + "@esbuild/android-x64": "0.25.12", + "@esbuild/darwin-arm64": "0.25.12", + "@esbuild/darwin-x64": "0.25.12", + "@esbuild/freebsd-arm64": "0.25.12", + "@esbuild/freebsd-x64": "0.25.12", + "@esbuild/linux-arm": "0.25.12", + "@esbuild/linux-arm64": "0.25.12", + "@esbuild/linux-ia32": "0.25.12", + "@esbuild/linux-loong64": "0.25.12", + "@esbuild/linux-mips64el": "0.25.12", + "@esbuild/linux-ppc64": "0.25.12", + "@esbuild/linux-riscv64": "0.25.12", + "@esbuild/linux-s390x": "0.25.12", + "@esbuild/linux-x64": "0.25.12", + "@esbuild/netbsd-arm64": "0.25.12", + "@esbuild/netbsd-x64": "0.25.12", + "@esbuild/openbsd-arm64": "0.25.12", + "@esbuild/openbsd-x64": "0.25.12", + "@esbuild/openharmony-arm64": "0.25.12", + "@esbuild/sunos-x64": "0.25.12", + "@esbuild/win32-arm64": "0.25.12", + "@esbuild/win32-ia32": "0.25.12", + "@esbuild/win32-x64": "0.25.12" + } + }, "node_modules/semver": { - "version": "7.8.2", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.2.tgz", - "integrity": "sha512-c8jsqUZm3omBOI66G90z1Dyw5z622G8oLG+omfsHBJf3CWQTlOcwOjvOG6wtiNfW6anKm/eA39LMwMtMez2TiQ==", + "version": "7.8.5", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz", + "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==", "license": "ISC", "bin": { "semver": "bin/semver.js" @@ -2497,47 +1086,52 @@ } }, "node_modules/sharp": { - "version": "0.34.5", - "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz", - "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==", - "hasInstallScript": true, + "version": "0.35.3", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.3.tgz", + "integrity": "sha512-ej0zVHuZGHCiABXcNxeYhpRnPNPAcvbG8RMdBAhDAxLKkCRVSpK3Iyu7qbqw3JMzoj0REeM6f3tJLtVwl0023Q==", "license": "Apache-2.0", "dependencies": { - "@img/colour": "^1.0.0", + "@img/colour": "^1.1.0", "detect-libc": "^2.1.2", - "semver": "^7.7.3" + "semver": "^7.8.5" }, "engines": { - "node": "^18.17.0 || ^20.3.0 || >=21.0.0" + "node": ">=20.9.0" }, "funding": { "url": "https://opencollective.com/libvips" }, "optionalDependencies": { - "@img/sharp-darwin-arm64": "0.34.5", - "@img/sharp-darwin-x64": "0.34.5", - "@img/sharp-libvips-darwin-arm64": "1.2.4", - "@img/sharp-libvips-darwin-x64": "1.2.4", - "@img/sharp-libvips-linux-arm": "1.2.4", - "@img/sharp-libvips-linux-arm64": "1.2.4", - "@img/sharp-libvips-linux-ppc64": "1.2.4", - "@img/sharp-libvips-linux-riscv64": "1.2.4", - "@img/sharp-libvips-linux-s390x": "1.2.4", - "@img/sharp-libvips-linux-x64": "1.2.4", - "@img/sharp-libvips-linuxmusl-arm64": "1.2.4", - "@img/sharp-libvips-linuxmusl-x64": "1.2.4", - "@img/sharp-linux-arm": "0.34.5", - "@img/sharp-linux-arm64": "0.34.5", - "@img/sharp-linux-ppc64": "0.34.5", - "@img/sharp-linux-riscv64": "0.34.5", - "@img/sharp-linux-s390x": "0.34.5", - "@img/sharp-linux-x64": "0.34.5", - "@img/sharp-linuxmusl-arm64": "0.34.5", - "@img/sharp-linuxmusl-x64": "0.34.5", - "@img/sharp-wasm32": "0.34.5", - "@img/sharp-win32-arm64": "0.34.5", - "@img/sharp-win32-ia32": "0.34.5", - "@img/sharp-win32-x64": "0.34.5" + "@img/sharp-darwin-arm64": "0.35.3", + "@img/sharp-darwin-x64": "0.35.3", + "@img/sharp-freebsd-wasm32": "0.35.3", + "@img/sharp-libvips-darwin-arm64": "1.3.2", + "@img/sharp-libvips-darwin-x64": "1.3.2", + "@img/sharp-libvips-linux-arm": "1.3.2", + "@img/sharp-libvips-linux-arm64": "1.3.2", + "@img/sharp-libvips-linux-ppc64": "1.3.2", + "@img/sharp-libvips-linux-riscv64": "1.3.2", + "@img/sharp-libvips-linux-s390x": "1.3.2", + "@img/sharp-libvips-linux-x64": "1.3.2", + "@img/sharp-libvips-linuxmusl-arm64": "1.3.2", + "@img/sharp-libvips-linuxmusl-x64": "1.3.2", + "@img/sharp-linux-arm": "0.35.3", + "@img/sharp-linux-arm64": "0.35.3", + "@img/sharp-linux-ppc64": "0.35.3", + "@img/sharp-linux-riscv64": "0.35.3", + "@img/sharp-linux-s390x": "0.35.3", + "@img/sharp-linux-x64": "0.35.3", + "@img/sharp-linuxmusl-arm64": "0.35.3", + "@img/sharp-linuxmusl-x64": "0.35.3", + "@img/sharp-webcontainers-wasm32": "0.35.3", + "@img/sharp-win32-arm64": "0.35.3", + "@img/sharp-win32-ia32": "0.35.3", + "@img/sharp-win32-x64": "0.35.3" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } } }, "node_modules/tslib": { diff --git a/package.json b/package.json index 6a74b67..d334c02 100644 --- a/package.json +++ b/package.json @@ -1,24 +1,66 @@ { - "name": "pi-visual-primitives", - "version": "0.1.0", - "description": "Pi extension package for cropping image regions from visual primitive bounding boxes.", + "name": "@mapleluvr/visual-primitives", + "version": "0.2.0", + "description": "CLI for visual evidence primitives: crop, batch-crop, annotate, point-crop, and color sampling on local images and screenshots.", "type": "module", - "keywords": ["pi-package", "pi-extension", "visual-primitives", "bounding-box", "image-crop"], + "bin": { + "visual-primitives": "./dist/cli.js", + "vp": "./dist/cli.js" + }, + "engines": { + "node": ">=22.18" + }, + "files": [ + "dist", + "skills", + "README.md", + "README.zh-CN.md", + "CHANGELOG.md", + "RELEASE.md", + "LICENSE" + ], + "keywords": [ + "pi-package", + "cli", + "visual-primitives", + "bounding-box", + "image-crop", + "screenshot", + "visual-evidence", + "color-sampling" + ], "author": "mapleluvr", "license": "MIT", - "scripts": { - "check": "node --experimental-strip-types --check index.ts && node --experimental-strip-types --check src/schema.ts && node --experimental-strip-types --check src/crop.ts && node --experimental-strip-types --check src/phase2.ts && node --experimental-strip-types --check src/extension.ts && node --experimental-strip-types --check scripts/masked-oracle-diff.ts", - "test": "node --experimental-strip-types --test tests/*.test.ts", - "oracle:diff": "node --experimental-strip-types scripts/masked-oracle-diff.ts" + "repository": { + "type": "git", + "url": "git+https://github.com/mapleluvr/visual-primitives.git" }, - "dependencies": { - "sharp": "^0.34.0" + "bugs": { + "url": "https://github.com/mapleluvr/visual-primitives/issues" }, - "peerDependencies": { - "@earendil-works/pi-coding-agent": "*" + "homepage": "https://github.com/mapleluvr/visual-primitives#readme", + "publishConfig": { + "access": "public" }, "pi": { - "extensions": ["./index.ts"], - "skills": ["./skills"] + "skills": [ + "./skills" + ] + }, + "scripts": { + "build": "node scripts/build-cli.mjs", + "check": "npm run build && node --check dist/cli.js && node --check scripts/package-smoke.mjs && node --check scripts/release-state.mjs && node --check scripts/resolve-release-state.mjs && node --check scripts/verify-release-bootstrap.mjs && node --check scripts/verify-release-tag.mjs && node --check skills/_shared/run-vp.mjs && node --check skills/frontend-replication/scripts/run-masked-oracle-diff.mjs && node --check skills/frontend-replication/scripts/masked-oracle-diff.js && node --check src/schema.ts && node --check src/crop.ts && node --check src/phase2.ts && node --check src/cli.ts && node --check skills/frontend-replication/scripts/masked-oracle-diff.ts", + "oracle:diff": "node skills/frontend-replication/scripts/masked-oracle-diff.js", + "package:smoke": "node scripts/package-smoke.mjs", + "prepare": "npm run build", + "release:verify-bootstrap": "node scripts/verify-release-bootstrap.mjs", + "release:verify-tag": "node scripts/verify-release-tag.mjs", + "test": "node --test \"tests/*.test.ts\"" + }, + "dependencies": { + "sharp": "^0.35.3" + }, + "devDependencies": { + "esbuild": "^0.25.0" } } diff --git a/scripts/build-cli.mjs b/scripts/build-cli.mjs new file mode 100644 index 0000000..6c23b5a --- /dev/null +++ b/scripts/build-cli.mjs @@ -0,0 +1,34 @@ +import { chmod, mkdir } from "node:fs/promises"; +import { dirname } from "node:path"; +import { fileURLToPath } from "node:url"; +import { build } from "esbuild"; + +const packageRoot = new URL("../", import.meta.url); +const outputs = [ + { + entry: new URL("src/cli.ts", packageRoot), + output: new URL("dist/cli.js", packageRoot), + executable: true, + }, + { + entry: new URL("skills/frontend-replication/scripts/masked-oracle-diff.ts", packageRoot), + output: new URL("skills/frontend-replication/scripts/masked-oracle-diff.js", packageRoot), + executable: false, + }, +]; + +for (const item of outputs) { + await mkdir(dirname(fileURLToPath(item.output)), { recursive: true }); + await build({ + entryPoints: [fileURLToPath(item.entry)], + outfile: fileURLToPath(item.output), + bundle: true, + platform: "node", + format: "esm", + target: "node22.18", + packages: "external", + legalComments: "none", + logLevel: "info", + }); + if (item.executable) await chmod(item.output, 0o755); +} diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjs new file mode 100644 index 0000000..739a0ea --- /dev/null +++ b/scripts/package-smoke.mjs @@ -0,0 +1,158 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { promisify } from "node:util"; +import sharp from "sharp"; + +const execFileAsync = promisify(execFile); +const packageRoot = new URL("../", import.meta.url); +const packageRootPath = decodeURIComponent(packageRoot.pathname).replace(/^\/(?:([A-Za-z]:))/, "$1"); +const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm"; +const expectedSkills = [ + "finalizing-replication", + "frontend-replication", + "inline-replication", + "refining-with-feedback", + "subagent-driven-replication", + "using-visual-primitives", +]; + +async function runNpm(args, cwd) { + if (process.platform === "win32") { + return execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", npmCommand, ...args], { cwd }); + } + return execFileAsync(npmCommand, args, { cwd }); +} + +async function runNode(script, args, options = {}) { + return execFileAsync(process.execPath, [script, ...args], options); +} + +async function parsePackResult(packDir) { + const { stdout } = await runNpm(["pack", "--json", "--pack-destination", packDir], packageRootPath); + const jsonStart = stdout.indexOf("["); + assert.notEqual(jsonStart, -1, `npm pack did not return JSON: ${stdout}`); + const [result] = JSON.parse(stdout.slice(jsonStart)); + return result; +} + +async function assertArtifactEntries(files) { + const entries = files.map((file) => file.path).sort(); + const required = [ + "CHANGELOG.md", + "LICENSE", + "README.md", + "README.zh-CN.md", + "RELEASE.md", + "dist/cli.js", + "package.json", + "skills/_shared/run-vp.mjs", + ...expectedSkills.map((skill) => `skills/${skill}/SKILL.md`), + "skills/frontend-replication/scripts/masked-oracle-diff.js", + "skills/frontend-replication/scripts/masked-oracle-diff.ts", + "skills/frontend-replication/scripts/run-masked-oracle-diff.mjs", + ]; + for (const entry of required) assert.ok(entries.includes(entry), `missing packed entry: ${entry}`); + + for (const entry of entries) { + assert.doesNotMatch(entry, /^(?:tests?|docs\/superpowers|\.superpowers|\.pi-subagents|index\.ts|src\/extension\.ts)/, `unexpected packed entry: ${entry}`); + } +} + +async function runInstalledAlias(binDir, alias, args, cwd) { + const executable = join(binDir, process.platform === "win32" ? `${alias}.cmd` : alias); + if (process.platform === "win32") { + return execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", executable, ...args], { cwd }); + } + return execFileAsync(executable, args, { cwd }); +} + +async function readJsonResult(result, command) { + assert.equal(result.stderr.includes("error:"), false, `${command}: ${result.stderr}`); + return JSON.parse(result.stdout); +} + +const tempRoot = await mkdtemp(join(tmpdir(), "visual-primitives-package-smoke-")); +try { + const packDir = join(tempRoot, "pack"); + const installDir = join(tempRoot, "install"); + await mkdir(packDir); + await mkdir(installDir); + await writeFile(join(installDir, "package.json"), JSON.stringify({ private: true })); + + const packResult = await parsePackResult(packDir); + await assertArtifactEntries(packResult.files); + const tarballPath = join(packDir, packResult.filename); + const tarballBytes = await readFile(tarballPath); + assert.ok(tarballBytes.length > 0); + + await runNpm(["install", "--no-audit", "--no-fund", tarballPath], installDir); + const packageDir = join(installDir, "node_modules", "@mapleluvr", "visual-primitives"); + const binDir = join(installDir, "node_modules", ".bin"); + const fixture = join(installDir, "fixture.png"); + await sharp({ + create: { width: 24, height: 20, channels: 4, background: { r: 30, g: 80, b: 140, alpha: 1 } }, + }).png().toFile(fixture); + + for (const alias of ["vp", "visual-primitives"]) { + const version = await runInstalledAlias(binDir, alias, ["--version"], installDir); + assert.equal(version.stdout.trim(), packResult.version); + } + + const operations = [ + ["crop", fixture, "--space", "pixel", "--box", "1,1,12,12", "--out", join(installDir, "crop.png")], + ["crop-multi", fixture, "--space", "pixel", "--box", "left:1,1,8,8", "--box", "right:10,2,20,12", "--out-dir", join(installDir, "crops")], + ["annotate", fixture, "--space", "pixel", "--box", "target:2,2,18,15:#ff0000", "--out", join(installDir, "annotated.png")], + ["point", fixture, "--space", "pixel", "--point", "12,10", "--radius", "4", "--out", join(installDir, "point.png")], + ["colors", fixture, "--space", "pixel", "--point", "sample:5,5", "--patch", "1"], + ]; + for (const args of operations) { + const result = await runInstalledAlias(binDir, "vp", args, installDir); + await readJsonResult(result, args[0]); + } + + for (const skill of expectedSkills) await access(join(packageDir, "skills", skill, "SKILL.md")); + await access(join(packageDir, "skills", "frontend-replication", "scripts", "masked-oracle-diff.ts")); + await access(join(packageDir, "skills", "frontend-replication", "scripts", "masked-oracle-diff.js")); + const diffRunner = join(packageDir, "skills", "frontend-replication", "scripts", "run-masked-oracle-diff.mjs"); + await access(diffRunner); + + const launcher = join(packageDir, "skills", "_shared", "run-vp.mjs"); + const launcherEnv = { ...process.env, PATH: "" }; + const help = await runNode(launcher, ["--help"], { cwd: installDir, env: launcherEnv }); + assert.match(help.stdout, /crop-multi/); + const launcherCrop = join(installDir, "launcher-crop.png"); + const launcherResult = await runNode(launcher, [ + "crop", fixture, "--space", "pixel", "--box", "2,2,10,10", "--out", launcherCrop, + ], { cwd: installDir, env: launcherEnv }); + await readJsonResult(launcherResult, "package-local launcher crop"); + await access(launcherCrop); + + const diffManifest = join(installDir, "diff-manifest.json"); + await writeFile(diffManifest, JSON.stringify({ + oracleImage: "fixture.png", + renderedImage: "fixture.png", + outputDir: "diff-output", + })); + await runNode(diffRunner, ["--manifest", diffManifest], { cwd: installDir, env: launcherEnv }); + await access(join(installDir, "diff-output", "summary.json")); + await access(join(installDir, "diff-output", "VERDICT.md")); + + process.stdout.write(`${JSON.stringify({ + status: "pass", + package: packResult.id, + tarball: packResult.filename, + tarballBytes: tarballBytes.length, + packedEntries: packResult.files.length, + aliases: ["vp", "visual-primitives"], + commands: operations.map(([command]) => command), + skills: expectedSkills, + packageLocalLauncher: true, + packageLocalMaskedOracleDiffRunner: true, + maskedOracleDiffOwner: "skills/frontend-replication/scripts", + }, null, 2)}\n`); +} finally { + await rm(tempRoot, { recursive: true, force: true }); +} diff --git a/scripts/release-state.mjs b/scripts/release-state.mjs new file mode 100644 index 0000000..d25af70 --- /dev/null +++ b/scripts/release-state.mjs @@ -0,0 +1,26 @@ +function assertLocalMetadata(local) { + for (const key of ["name", "version", "integrity", "shasum"]) { + if (typeof local?.[key] !== "string" || local[key].length === 0) { + throw new Error(`local package metadata is missing ${key}`); + } + } +} + +export function decideNpmPublish(local, published) { + assertLocalMetadata(local); + if (published === null) { + return { action: "publish", reason: "version-unpublished" }; + } + if (published?.name !== local.name || published?.version !== local.version) { + throw new Error(`published package identity mismatch for ${local.name}@${local.version}`); + } + const integrityMatches = published?.dist?.integrity === local.integrity; + const shasumMatches = published?.dist?.shasum === local.shasum; + if (!integrityMatches || !shasumMatches) { + throw new Error(`${local.name}@${local.version} already exists with different integrity`); + } + return { + action: "skip-identical", + reason: "version-already-published-with-matching-integrity", + }; +} diff --git a/scripts/resolve-release-state.mjs b/scripts/resolve-release-state.mjs new file mode 100644 index 0000000..87407cf --- /dev/null +++ b/scripts/resolve-release-state.mjs @@ -0,0 +1,53 @@ +#!/usr/bin/env node +import { execFile } from "node:child_process"; +import { appendFile, readFile } from "node:fs/promises"; +import { promisify } from "node:util"; +import { decideNpmPublish } from "./release-state.mjs"; + +const execFileAsync = promisify(execFile); +const packJsonPath = process.argv[2]; +if (!packJsonPath) throw new Error("Usage: resolve-release-state "); + +const parsed = JSON.parse(await readFile(packJsonPath, "utf8")); +const local = Array.isArray(parsed) ? parsed[0] : parsed; +if (!local) throw new Error("npm pack metadata is empty"); + +let published = null; +try { + const viewArgs = [ + "view", + `${local.name}@${local.version}`, + "name", + "version", + "dist", + "--json", + ]; + const npmCommand = process.env.NPM_CLI_PATH; + const npmPrefix = process.env.NPM_CLI_PREFIX ? [process.env.NPM_CLI_PREFIX] : []; + const invocation = npmCommand + ? { command: npmCommand, args: [...npmPrefix, ...viewArgs] } + : process.platform === "win32" + ? { + command: process.env.ComSpec || "cmd.exe", + args: ["/d", "/s", "/c", "npm.cmd", ...viewArgs], + } + : { command: "npm", args: viewArgs }; + const { stdout } = await execFileAsync(invocation.command, invocation.args); + published = JSON.parse(stdout); +} catch (error) { + const output = `${error?.stdout ?? ""}\n${error?.stderr ?? ""}`; + if (!/E404|404 Not Found|is not in this registry/i.test(output)) throw error; +} + +const decision = decideNpmPublish(local, published); +const publish = decision.action === "publish"; +const output = { + package: `${local.name}@${local.version}`, + publish, + ...decision, +}; +process.stdout.write(`${JSON.stringify(output)}\n`); + +if (process.env.GITHUB_OUTPUT) { + await appendFile(process.env.GITHUB_OUTPUT, `publish=${publish}\naction=${decision.action}\nreason=${decision.reason}\n`); +} diff --git a/scripts/verify-release-bootstrap.mjs b/scripts/verify-release-bootstrap.mjs new file mode 100644 index 0000000..e2eee17 --- /dev/null +++ b/scripts/verify-release-bootstrap.mjs @@ -0,0 +1,38 @@ +#!/usr/bin/env node +import { execFile } from "node:child_process"; +import { promisify } from "node:util"; + +const execFileAsync = promisify(execFile); +const expected = { + name: "@mapleluvr/visual-primitives", + version: "0.0.0-bootstrap.0", +}; +const viewArgs = [ + "view", + `${expected.name}@bootstrap`, + "name", + "version", + "--json", +]; +const npmCommand = process.env.NPM_CLI_PATH; +const npmPrefix = process.env.NPM_CLI_PREFIX ? [process.env.NPM_CLI_PREFIX] : []; +const invocation = npmCommand + ? { command: npmCommand, args: [...npmPrefix, ...viewArgs] } + : process.platform === "win32" + ? { + command: process.env.ComSpec || "cmd.exe", + args: ["/d", "/s", "/c", "npm.cmd", ...viewArgs], + } + : { command: "npm", args: viewArgs }; + +try { + const { stdout } = await execFileAsync(invocation.command, invocation.args); + const metadata = JSON.parse(stdout); + if (metadata?.name !== expected.name || metadata?.version !== expected.version) { + throw new Error(`expected ${expected.name}@bootstrap to resolve to ${expected.version}`); + } + process.stdout.write(`${metadata.name}@${metadata.version} bootstrap verified\n`); +} catch (error) { + const detail = `${error?.stdout ?? ""}\n${error?.stderr ?? ""}`.trim(); + throw new Error(`bootstrap verification failed${detail ? `: ${detail}` : ""}`, { cause: error }); +} diff --git a/scripts/verify-release-tag.mjs b/scripts/verify-release-tag.mjs new file mode 100644 index 0000000..69bc033 --- /dev/null +++ b/scripts/verify-release-tag.mjs @@ -0,0 +1,11 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; + +const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")); +const tag = process.argv[2] ?? process.env.GITHUB_REF_NAME; + +assert.equal(typeof tag, "string", "release tag is required as argv[2] or GITHUB_REF_NAME"); +assert.match(tag, /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/, `invalid release tag: ${tag}`); +assert.equal(tag, `v${packageJson.version}`, `tag ${tag} does not match package version ${packageJson.version}`); + +process.stdout.write(`${packageJson.name}@${packageJson.version} matches ${tag}\n`); diff --git a/skills/_shared/run-vp.mjs b/skills/_shared/run-vp.mjs new file mode 100644 index 0000000..f87f47a --- /dev/null +++ b/skills/_shared/run-vp.mjs @@ -0,0 +1,21 @@ +#!/usr/bin/env node +import { spawn } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const cliPath = fileURLToPath(new URL("../../dist/cli.js", import.meta.url)); +const child = spawn(process.execPath, [cliPath, ...process.argv.slice(2)], { + stdio: "inherit", + windowsHide: true, +}); + +child.on("error", (error) => { + console.error(`failed to start packaged vp CLI: ${error.message}`); + process.exitCode = 1; +}); +child.on("exit", (code, signal) => { + if (signal) { + process.kill(process.pid, signal); + return; + } + process.exitCode = code ?? 1; +}); diff --git a/skills/frontend-replication/SKILL.md b/skills/frontend-replication/SKILL.md index 1299e5c..6f10410 100644 --- a/skills/frontend-replication/SKILL.md +++ b/skills/frontend-replication/SKILL.md @@ -71,13 +71,13 @@ docs/visual-primitives/runs// Directory behavior: - `oracles/`: oracle pictures, source reference images, user descriptions, derived descriptions, and `oracle-manifest.json`. -- `annots/`: outputs from `annotate_bounding_boxes`. -- `cropped/`: outputs from `crop_bounding_box` and `crop_multiple_bounding_boxes`. +- `annots/`: outputs from `vp annotate`. +- `cropped/`: outputs from `vp crop` and `vp crop-multi`. - `rendered/`: rendered webpage screenshots. - `diffs/`: masked diff artifacts and summaries. - `drafts/`: initial and feedback drafts. Drafts accumulate as new files. - `verdict/`: process verdicts from inline or subagent verification. A verdict is feedback evidence and may become stale. -- `scripts/`: run-local manifests, screenshot commands, and one-off task scripts. Shared implementation scripts belong in the package `scripts/` or `src/` directories. +- `scripts/`: run-local manifests, screenshot commands, and one-off task scripts. The packaged `masked-oracle-diff` implementation remains under this Skill's `scripts/` resources. - `final/`: final direct-inspection notes and user-facing delivery review artifacts. ## Oracle Intake @@ -87,14 +87,14 @@ If the user provides screenshots or reference images without sufficient text, de Use `using-visual-primitives` to: 1. register oracle images under `oracles/`; -2. annotate major regions with `annotate_bounding_boxes`; +2. annotate major regions with `vp annotate`; 3. directly inspect annotated outputs; 4. crop important regions with the same coordinates; 5. directly inspect crop outputs; 6. write an evidence-backed oracle description; 7. write or update `oracles/oracle-manifest.json` using `references/oracle-manifest.md`. -The derived oracle description should record layout, visual hierarchy, region labels, important coordinates, relative positions, colors or `sample_colors` evidence, code-drawable areas, exclusion candidates, and evidence artifact paths. Use `references/draft-contract.md` for draft shape and `references/screenshot-capture.md` before Verify needs rendered images. +The derived oracle description should record layout, visual hierarchy, region labels, important coordinates, relative positions, colors or `vp colors` evidence, code-drawable areas, exclusion candidates, and evidence artifact paths. Use `references/draft-contract.md` for draft shape and `references/screenshot-capture.md` before Verify needs rendered images. If the user already provided a description, keep it as authoritative intent. The derived description supplements it with visual evidence; it does not replace user intent. diff --git a/skills/frontend-replication/references/masked-oracle-diff.md b/skills/frontend-replication/references/masked-oracle-diff.md index 8c14070..8e3f8b3 100644 --- a/skills/frontend-replication/references/masked-oracle-diff.md +++ b/skills/frontend-replication/references/masked-oracle-diff.md @@ -4,8 +4,10 @@ Use `masked-oracle-diff` during Verify after a rendered screenshot exists at the ## Command +Resolve the runner relative to the loaded `frontend-replication` Skill directory. It is package-local and works from the consumer project's working directory without a host-project npm script: + ```bash -npm run oracle:diff -- --manifest docs/visual-primitives/runs//scripts/diff-manifest.json +node /scripts/run-masked-oracle-diff.mjs --manifest docs/visual-primitives/runs//scripts/diff-manifest.json ``` ## Manifest Path diff --git a/scripts/masked-oracle-diff.ts b/skills/frontend-replication/scripts/masked-oracle-diff.ts similarity index 100% rename from scripts/masked-oracle-diff.ts rename to skills/frontend-replication/scripts/masked-oracle-diff.ts diff --git a/skills/frontend-replication/scripts/run-masked-oracle-diff.mjs b/skills/frontend-replication/scripts/run-masked-oracle-diff.mjs new file mode 100644 index 0000000..914b298 --- /dev/null +++ b/skills/frontend-replication/scripts/run-masked-oracle-diff.mjs @@ -0,0 +1,21 @@ +#!/usr/bin/env node +import { spawn } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const helperPath = fileURLToPath(new URL("./masked-oracle-diff.js", import.meta.url)); +const child = spawn(process.execPath, [helperPath, ...process.argv.slice(2)], { + stdio: "inherit", + windowsHide: true, +}); + +child.on("error", (error) => { + console.error(`failed to start packaged masked-oracle-diff helper: ${error.message}`); + process.exitCode = 1; +}); +child.on("exit", (code, signal) => { + if (signal) { + process.kill(process.pid, signal); + return; + } + process.exitCode = code ?? 1; +}); diff --git a/skills/inline-replication/SKILL.md b/skills/inline-replication/SKILL.md index 0e723f2..9fd612e 100644 --- a/skills/inline-replication/SKILL.md +++ b/skills/inline-replication/SKILL.md @@ -89,15 +89,15 @@ Before masked diff, write a run-local manifest such as: scripts/diff-manifest.json ``` -Run: +Resolve `scripts/run-masked-oracle-diff.mjs` relative to the loaded `frontend-replication` Skill directory, then run the package-local helper from any project working directory: ```bash -npm run oracle:diff -- --manifest docs/visual-primitives/runs//scripts/diff-manifest.json +node /scripts/run-masked-oracle-diff.mjs --manifest docs/visual-primitives/runs//scripts/diff-manifest.json ``` Store diff outputs under `diffs/`. Cite `VERDICT.md`, `summary.json`, `matrix.json`, `components.json`, and `stripes.json` in process findings under `verdict/`. -When `components.json` reports local highlights, inspect each important component center with `crop_around_point` before explaining the difference. Use second-order coordinate calculations for offsets, gaps, sizes, and alignment, and use `sample_colors` when the component suggests a color, contrast, gradient, or shadow mismatch. +When `components.json` reports local highlights, inspect each important component center with `vp point` before explaining the difference. Use second-order coordinate calculations for offsets, gaps, sizes, and alignment, and use `vp colors` when the component suggests a color, contrast, gradient, or shadow mismatch. ## Verdict And Feedback diff --git a/skills/subagent-driven-replication/SKILL.md b/skills/subagent-driven-replication/SKILL.md index 27015d4..b2b6e67 100644 --- a/skills/subagent-driven-replication/SKILL.md +++ b/skills/subagent-driven-replication/SKILL.md @@ -49,9 +49,9 @@ Initial Draft may use a read-write subagent. This worker is closer to a visual a Give the visual annotation worker permission to use: ```text -annotate_bounding_boxes -crop_bounding_box -crop_multiple_bounding_boxes +vp annotate +vp crop +vp crop-multi write/edit draft markdown ``` @@ -95,15 +95,15 @@ Reviewer tasks should inspect the actual artifacts: - masked diff outputs; - code diff or implementation files when relevant. -The Orchestrator prepares or approves `scripts/diff-manifest.json`, then runs or assigns exactly one worker/reviewer step to run: +The Orchestrator prepares or approves `scripts/diff-manifest.json`, resolves `scripts/run-masked-oracle-diff.mjs` relative to the loaded `frontend-replication` Skill directory, then runs or assigns exactly one worker/reviewer step to run: ```bash -npm run oracle:diff -- --manifest docs/visual-primitives/runs//scripts/diff-manifest.json +node /scripts/run-masked-oracle-diff.mjs --manifest docs/visual-primitives/runs//scripts/diff-manifest.json ``` Diff evidence should include `VERDICT.md`, `summary.json`, `matrix.json`, `components.json`, and `stripes.json` from `diffs/`. -When `components.json` reports local highlights, assign exactly one current worker or reviewer step to inspect important component centers with `crop_around_point`. Ask for second-order coordinate calculations for offsets, gaps, sizes, and alignment, and use `sample_colors` when the component suggests a color, contrast, gradient, or shadow mismatch. +When `components.json` reports local highlights, assign exactly one current worker or reviewer step to inspect important component centers with `vp point`. Ask for second-order coordinate calculations for offsets, gaps, sizes, and alignment, and use `vp colors` when the component suggests a color, contrast, gradient, or shadow mismatch. Ask reviewers for approval findings scoped to draft reasonableness, completion, and evidence quality. Useful angles include: diff --git a/skills/using-visual-primitives/SKILL.md b/skills/using-visual-primitives/SKILL.md index 5904188..226192c 100644 --- a/skills/using-visual-primitives/SKILL.md +++ b/skills/using-visual-primitives/SKILL.md @@ -7,146 +7,74 @@ description: Use when marking, comparing, aligning, analyzing, cropping, annotat ## Overview -Use this Skill when an image task needs visual evidence. `pi-visual-primitives` tools turn concrete regions and points into artifacts you can inspect: annotated images, single crops, batch crops, and point-centered crops. +Use `vp` when an image task needs inspectable visual evidence from agent- or user-provided boxes and points. The five commands annotate images, crop regions, crop several regions, crop around a point, and sample exact colors. They do not detect objects, read text, segment images, or infer UI elements. -This Skill is the general-purpose visual evidence layer. It supports standalone image proofreading, screenshot comparison, layout comparison, spacing checks, edge alignment, text baseline analysis, chart alignment, generated image analysis, UI render inspection, masked diff triage, color verification, and local region study. +Direct visual inspection remains the interpreter: inspect generated images before making detailed claims. -## Core Principles +## Invocation -1. **User requirements take priority.** If user instructions specify what to inspect, compare, ignore, crop, annotate, or conclude, follow those requirements before default heuristics. -2. **Direct visual inspection takes priority.** CV or script-derived conclusions can provide useful evidence, but they are not universally interpretable and can be misleading. Inspect the actual images, annotated outputs, crop outputs, and overlays before making visual claims. -3. **Think geometrics, write coordinates.** Use repeated `appearance -> coordinates -> appearance` loops: observe the visual impression, express the relevant local geometry as coordinates, inspect the crop or annotation, then refine both the coordinates and the interpretation. The goal is understanding specific local image content at specific positions. +Agent execution must not assume that `vp` is on `PATH`. Resolve the package root from this Skill's installed location, then invoke the package-local launcher: -## When to Use +```bash +node /skills/_shared/run-vp.mjs [arguments] +``` -Use this Skill for: +A user who installed the npm binary globally may use `vp` in place of the launcher. Successful commands print JSON to stdout and write PNG artifacts to the reported paths. -- marking images with labeled boxes; -- turning a region hypothesis into visible evidence; -- comparing images or screenshots; -- checking layout comparison, spacing, edge alignment, text baselines, and nearby anchors; -- aligning images through corresponding regions; -- analyzing local image details, including masked diff components and stripe-like findings; -- checking UI renders, charts, generated images, diagrams, product photos, or visual QA artifacts; -- verifying shadow mismatch, gradient behavior, palette-sensitive colors, and contrast-sensitive local areas; -- converting visual impressions into pixel or normalized coordinates; -- verifying that a crop or annotation actually covers the intended local content. +## Command Selection -Do not use this Skill for pure style advice without an image or visual artifact. Do not claim the tools detect objects, OCR text, segment images, or infer UI elements automatically. - -## Tool Selection - -| Need | Tool | +| Need | Command | | --- | --- | -| Marking images with visible boxes or testing a region hypothesis | `annotate_bounding_boxes` | -| Checking one region closely | `crop_bounding_box` | -| Checking several regions from one source | `crop_multiple_bounding_boxes` | -| Comparing corresponding regions across screenshots or variants | `annotate_bounding_boxes`, then `crop_multiple_bounding_boxes` | -| Layout comparison, spacing, edge alignment, or text baseline checks | matching annotations, shared labels, comparable coordinates, and `resolvedPixelBox` arithmetic | -| Inspecting a masked diff component, localized highlight, tiny overlap, cursor target, or label anchor | `crop_around_point` with explicit `radius` or `size` | -| Investigating shadow mismatch, gradient behavior, palette-sensitive areas, or CSS-level color claims | `sample_colors` at explicit points, supported by crops around the sampled area | - -For screenshots and rendered UI, prefer `coordinateSpace: "pixel"`, `origin: "top-left"`, and `boxOrder: "left-top-right-bottom"`. Use `normalized-999` when coordinates come from visual-primitives style normalized values. - -## Marking Images - -1. Identify the visual question and the source image. -2. Estimate or use provided boxes for the relevant local regions. -3. Use `annotate_bounding_boxes` with semantic labels. -4. Directly inspect the annotated image. -5. If a box is off-target, too broad, too tight, or ambiguous, revise the coordinates and annotate again. -6. Record the final labels and coordinates. - -Good labels name the visual role: `header`, `legend`, `left-card`, `button-shadow`, `chart-axis`, `logo-mark`, `error-highlight`, or `painted-figure`. - -## Verifying Marks With Crops - -Annotations show placement, but crops prove whether a region contains the intended content at useful precision. - -After marking, use `crop_bounding_box` or `crop_multiple_bounding_boxes` with the same coordinates. Inspect each crop and confirm: - -- the intended element is fully included; -- unrelated surrounding content is not meaningfully included; -- the crop is not empty or clamped in a way that changes the claim; -- the crop supports the visual conclusion being made. - -## Comparing Images - -For two or more images: - -1. Choose corresponding regions in each image. -2. Use the same labels across images. -3. Annotate each image so the correspondence is visible. -4. Crop corresponding regions with `crop_multiple_bounding_boxes`. -5. Directly inspect the annotated images and crop outputs. -6. Use returned `resolvedPixelBox` metadata to quantify `width`, `height`, and `area` before making size claims. -7. Describe both absolute differences and relative differences against nearby regions. - -Use numeric differences to choose where to inspect; use image evidence to explain what is happening. - -## Aligning Images - -Alignment requires explicit coordinate evidence. - -Use shared frames of reference: - -- image dimensions; -- viewport or canvas size; -- matching labels; -- corresponding boxes; -- center points; -- distances to nearby anchors; -- pixel coordinates and normalized thousandths. - -When alignment matters, record both pixel coordinates and normalized `0-999` coordinates. Pixel coordinates preserve implementation precision. Normalized coordinates make cross-size comparison easier. - -## Second-Order Quantities Must Be Computed +| Mark boxes and labels on the source image | `vp annotate` | +| Inspect one rectangular region | `vp crop` | +| Inspect several regions from one source | `vp crop-multi` | +| Inspect a local area centered on a point | `vp point` | +| Sample exact colors at explicit points | `vp colors` | -Distance, gap, size difference, alignment offset, and ratio are second-order quantities: they are derived from multiple coordinates, not read directly. +For screenshots, prefer `--space pixel --origin top-left --box-order left-top-right-bottom`. Use `--space normalized-999` when coordinates are normalized thousandths. Flag mode defaults to pixels; JSON compatibility mode preserves normalized-999 defaults. -Procedure for any second-order quantity: +## Common Invocations -1. Estimate each endpoint or edge coordinate separately using direct perception. -2. Write the arithmetic explicitly, for example: `gap = card2.left - card1.right = 412 - 330 = 82px`. -3. Report the computed result, not the visual impression. +Use the package-local launcher prefix shown above for agent execution. The shorter `vp` form below shows the command arguments: -Alignment checks follow the same rule: record both edge coordinates, subtract to get the offset, and compare the computed offset against the task tolerance. +```bash +vp annotate screenshot.png --space pixel --box "header:40,30,240,180" --out header-annotated.png +vp crop screenshot.png --space pixel --box "40,30,240,180" --out header-crop.png +vp crop-multi screenshot.png --space pixel --box "header:40,30,240,180" --box "button:280,220,420,280" --out-dir crops +vp point screenshot.png --space pixel --point "80,50" --radius 30 --out point-crop.png +vp colors screenshot.png --space pixel --point "header-bg:80,50" --patch 3 +``` -## Analyzing Images +Run `node /skills/_shared/run-vp.mjs --help` for the complete flags and JSON input shape. -Use the smallest useful region, then iterate. +## Evidence Workflow -1. Start from the visible appearance. -2. Write coordinates for the local geometry. -3. Generate an annotation or crop. -4. Inspect the artifact directly. -5. Refine the coordinates, labels, or interpretation. -6. Repeat until the evidence is specific enough to support the conclusion. +1. Identify the visual question and source image. +2. Estimate or use supplied coordinates. +3. Run `vp annotate` with semantic labels such as `header`, `legend`, or `button-shadow`. +4. Inspect the annotated PNG and revise off-target boxes. +5. Run `vp crop` or `vp crop-multi` with the confirmed coordinates. +6. Inspect each crop and verify that it contains the intended content without meaningful clamping. +7. Use `vp point` for a small point-centered area and `vp colors` when a color claim needs exact RGB, hex, OKLab, or patch means. +8. Record source paths, artifact paths, coordinates, coordinate conventions, and direct observations. -For point-centered defects such as overlaps, cursor targets, label anchors, tiny artifacts, or alignment points, use `crop_around_point` only with an explicit `radius` or `size` chosen for the inspection. +For two or more images, reuse labels and coordinate frames. Annotate each image, crop corresponding regions, then compare the artifacts directly. -For color-sensitive questions, use `sample_colors` at explicit points or small local patches when CSS-level color precision matters. Avoid broad color names when a visual claim depends on hue, brightness, contrast, or gradient behavior. +## Second-Order Quantities -## Evidence Notes +Distance, gap, size difference, alignment offset, and ratio must be computed from independently estimated coordinates. Write the arithmetic explicitly, for example: -When writing conclusions, include: +```text +gap = card2.left - card1.right = 412 - 330 = 82px +``` -- source image path; -- artifact paths for annotations and crops; -- labels and coordinates; -- coordinate space and origin; -- `resolvedPixelBox` width, height, and area when comparing sizes; -- `sample_colors` points and hex/RGB/OKLab results when color precision matters; -- direct visual observations from the artifacts; -- uncertainties or regions that need another crop. +Use returned `resolvedPixelBox` values to calculate width, height, area, and offsets before reporting them. ## Common Mistakes -- Treating tool output metadata as more authoritative than direct viewing. -- Skipping annotation before relying on estimated boxes. -- Forgetting to crop after annotation when precision matters. -- Comparing images with mismatched labels or coordinate frames. -- Using `normalized-999` for screenshots when pixel coordinates are the natural frame. -- Reporting detailed visual claims before directly inspecting generated artifacts. -- Treating a broad box as precise because it contains the target. -- Claiming the tools automatically detect or identify image content. +- Treating result metadata as a substitute for viewing the generated image. +- Reporting a visual claim before inspecting the annotation or crop. +- Using mismatched labels, image dimensions, or coordinate frames across images. +- Omitting an explicit `--radius` or `--size` for `vp point`. +- Using broad color names when `vp colors` can provide exact local evidence. +- Claiming the commands automatically locate or identify image content. diff --git a/src/cli.ts b/src/cli.ts new file mode 100644 index 0000000..62ceec3 --- /dev/null +++ b/src/cli.ts @@ -0,0 +1,913 @@ +#!/usr/bin/env node +import { existsSync, readFileSync, readdirSync } from "node:fs"; +import { readFile } from "node:fs/promises"; +import { basename, dirname, extname, isAbsolute, join } from "node:path"; +import { parseArgs, type ParseArgsConfig } from "node:util"; +import sharp from "sharp"; +import { cropBoundingBox } from "./crop.ts"; +import { + annotateBoundingBoxes, + cropAroundPoint, + cropMultipleBoundingBoxes, + sampleColors, + type AnnotateBoundingBoxesInput, + type CropAroundPointInput, + type CropMultipleBoundingBoxesInput, +} from "./phase2.ts"; +import { + BOX_ORDERS, + COORDINATE_SPACES, + ORIGINS, + type BoundingBoxTuple, + type BoxOrder, + type CoordinateOrigin, + type CoordinateSpace, + type CropBoundingBoxInput, + type PointTuple, + type SampleColorsInput, +} from "./schema.ts"; + +const packageMetadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown }; +if (typeof packageMetadata.version !== "string" || packageMetadata.version.length === 0) { + throw new Error("package.json must contain a non-empty version string"); +} +const VERSION = packageMetadata.version; + +class UsageError extends Error {} + +const COLOR_ENABLED = Boolean(process.stderr.isTTY) && !process.env.NO_COLOR; + +function paint(code: number, text: string): string { + return COLOR_ENABLED ? `\x1b[${code}m${text}\x1b[0m` : text; +} + +function levenshtein(a: string, b: string): number { + const rows = a.length + 1; + const cols = b.length + 1; + const dist = Array.from({ length: rows }, (_, i) => { + const row = new Array(cols).fill(0); + row[0] = i; + return row; + }); + for (let j = 0; j < cols; j += 1) dist[0][j] = j; + for (let i = 1; i < rows; i += 1) { + for (let j = 1; j < cols; j += 1) { + dist[i][j] = Math.min( + dist[i - 1][j] + 1, + dist[i][j - 1] + 1, + dist[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1), + ); + } + } + return dist[rows - 1][cols - 1]; +} + +function closestMatch(input: string, candidates: string[]): string | undefined { + let best: string | undefined; + let bestDistance = Infinity; + for (const candidate of candidates) { + const distance = levenshtein(input.toLowerCase(), candidate.toLowerCase()); + if (distance < bestDistance) { + bestDistance = distance; + best = candidate; + } + } + return best !== undefined && bestDistance <= Math.max(2, Math.floor(input.length / 3)) ? best : undefined; +} + +let currentCommand: string | undefined; +const pendingWarnings: string[] = []; +const hintContext: { space?: string; coords?: number[] } = {}; + +function warnIfOverwriting(outputPath: string | undefined): void { + if (!outputPath) return; + const resolved = isAbsolute(outputPath) ? outputPath : join(process.cwd(), outputPath); + if (existsSync(resolved)) pendingWarnings.push(`overwriting existing ${outputPath}`); +} + +function warnIfNotPng(outputPath: string | undefined): void { + if (!outputPath) return; + const ext = extname(outputPath).toLowerCase(); + if (ext && ext !== ".png") { + pendingWarnings.push(`output is always PNG data; "${outputPath}" keeps its ${ext} extension anyway`); + } +} + +const GLOBAL_HELP = `visual-primitives ${VERSION} — visual evidence primitives for images and screenshots + +Usage: vp [options] + +Commands: + crop Crop one bounding box from an image + crop-multi Crop multiple labeled boxes from the same image (fail-fast) + annotate Draw provided boxes over the image as a same-size preview + point Crop a region centered on a point (requires --radius or --size) + colors Sample exact colors at provided points + +Common options: + -i, --image Source image (or first positional argument) + -s, --space pixel | normalized-999 (default: pixel; aliases px, 999) + --origin top-left | bottom-left (default: top-left) + --box-order ltrb | lbrt (default: ltrb, i.e. left-top-right-bottom) + --padding Pixel padding around resolved boxes (default: 0) + --no-clamp Fail on out-of-bounds boxes instead of clipping + --json Read the full input as JSON (file path or - for stdin); + other input flags are then ignored. JSON payloads keep + the original tool defaults (space: normalized-999) + --compact Print compact JSON instead of pretty-printed + -q, --quiet Suppress the one-line summary on stderr + -h, --help Show help for a command + -v, --version Show version + +Results are printed as JSON on stdout, plus a one-line summary on stderr. +Errors go to stderr with exit code 1 (usage errors: exit code 2). +Generated artifacts default to the current working directory. + +Note: option values starting with "-" need "=" syntax, e.g. --box=-5,0,10,10. + +Run "vp --help" (or "vp help ") for command-specific +options and examples.`; + +const COMMAND_HELP: Record = { + crop: `Usage: vp crop --box [options] + +Crop one bounding box from a source image for focused visual inspection. + +Options: + --box Bounding box coordinates (required) + -o, --out Output PNG path (default: generated in the current directory) + plus common options (see "vp --help") + +Examples: + vp crop scene.png --box 50,40,250,180 -o scene-object.png + vp crop scene.png --box 120,80,420,360 --space 999 # normalized 0-999 + vp crop plot.png --box 10,20,60,80 --origin bottom-left --box-order lbrt + vp crop --json input.json`, + "crop-multi": `Usage: vp crop-multi --box <[label:]l,t,r,b> [--box ...] [options] + +Crop several boxes from the same image in one fail-fast call. Labels feed +deterministic output filenames and metadata. + +Options: + --box <[label:]l,t,r,b> Repeatable labeled box (at least one required) + --out-dir Directory for generated crops (default: current directory) + plus common options (see "vp --help") + +Examples: + vp crop-multi scene.png --out-dir crops \\ + --box "title:10,20,180,80" --box "button:220,300,380,360" + vp crop-multi --json input.json`, + annotate: `Usage: vp annotate --box <[label:]l,t,r,b[:color]> [--box ...] [options] + +Draw provided boxes over the source image as a same-size annotated preview. +Use it to verify coordinate-space, origin, or box-order assumptions before +relying on them for visual conclusions. + +Options: + --box <[label:]l,t,r,b[:color]> Repeatable box with optional label and + outline color (default color: #ff0055) + -o, --out Output PNG path (default: generated in the current directory) + plus common options (see "vp --help") + +Examples: + vp annotate scene.png -o scene-annotated.png \\ + --box "target:50,40,250,180" --box "header:0,0,800,64:#00aaff" + vp annotate --json input.json`, + point: `Usage: vp point --point (--radius | --size ) [options] + +Crop a region centered on a point of interest. An explicit --radius or --size +is required; pick it from the intended inspection area. + +Options: + --point Center point (required) + --radius Half-size of the square crop (mutually exclusive with --size) + --size Explicit crop size, e.g. 60x40 (also accepts W,H) + -o, --out Output PNG path (default: generated in the current directory) + plus common options (see "vp --help") + +Examples: + vp point scene.png --point 500,500 --radius 80 + vp point scene.png --point 120,90 --size 60x40 -o detail.png + vp point --json input.json`, + colors: `Usage: vp colors --point <[label:]x,y> [--point ...] [options] + +Sample exact colors at provided points for CSS-level color precision. Returns +RGB, hex, OKLab, and patch mean values per point. Use a small odd --patch such +as 3 or 5 when antialiasing or gradients make a single pixel misleading. + +Options: + --point <[label:]x,y> Repeatable labeled point (at least one required) + --patch Odd square patch size in pixels (default: 1) + plus common options (see "vp --help") + +Examples: + vp colors scene.png --patch 3 \\ + --point "header-bg:130,40" --point "cta-button:620,340" + vp colors --json input.json`, +}; + +function usageError(command: string, message: string): UsageError { + const usageLine = COMMAND_HELP[command]?.split("\n")[0]; + return new UsageError(usageLine ? `${message}\n${usageLine}` : message); +} + +function isValidCssColor(value: string): boolean { + if (value.trim() === "") return false; + try { + sharp({ create: { width: 1, height: 1, channels: 4, background: value } }); + return true; + } catch { + return false; + } +} + +function assertValidColor(value: string, context: string): void { + if (isValidCssColor(value)) return; + const hint = /^[0-9a-f]{3,8}$/i.test(value) ? `; did you mean "#${value}"?` : ""; + throw new UsageError(`invalid ${context} color "${value}"; use a CSS name, hex, rgb(), or rgba() color${hint}`); +} + +function validateJsonPayload(command: string, payload: unknown): void { + const fail = (message: string): never => { + throw new UsageError(`invalid --json payload: ${message}`); + }; + const objectAt = (value: unknown, path: string): Record => { + if (typeof value !== "object" || value === null || Array.isArray(value)) { + fail(path === "payload" ? "payload must be a JSON object" : `"${path}" must be an object`); + } + return value as Record; + }; + const rejectUnknown = (value: Record, allowed: readonly string[], path = ""): void => { + const allowedSet = new Set(allowed); + for (const key of Object.keys(value)) { + if (!allowedSet.has(key)) fail(`${path ? `${path}: ` : ""}unknown property "${key}"`); + } + }; + const requireString = (value: unknown, path: string, optional = false): void => { + if (optional && value === undefined) return; + if (typeof value !== "string" || (!optional && value.length === 0)) { + fail(`"${path}" must be ${optional ? "a string" : "a non-empty string"}`); + } + }; + const requireBoolean = (value: unknown, path: string): void => { + if (value !== undefined && typeof value !== "boolean") fail(`"${path}" must be a boolean`); + }; + const requireFiniteNonNegative = (value: unknown, path: string): void => { + if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) { + fail(`"${path}" must be a finite non-negative number`); + } + }; + const requireEnum = (value: unknown, path: string, allowed: readonly string[]): void => { + if (value !== undefined && (typeof value !== "string" || !allowed.includes(value))) { + fail(`"${path}" must be one of: ${allowed.join(", ")}`); + } + }; + const requireBox = (value: unknown, path: string): void => { + if (!Array.isArray(value) || value.length !== 4 || !value.every((item) => typeof item === "number" && Number.isFinite(item))) { + fail(`"${path}" must be [left, top, right, bottom] finite numbers`); + } + }; + const requirePoint = (value: unknown, path: string): void => { + if (!Array.isArray(value) || value.length !== 2 || !value.every((item) => typeof item === "number" && Number.isFinite(item))) { + fail(`"${path}" must be [x, y] finite numbers`); + } + }; + const validateCoordinates = (value: Record, includeBoxOptions: boolean): void => { + requireEnum(value.coordinateSpace, "coordinateSpace", COORDINATE_SPACES); + requireEnum(value.origin, "origin", ORIGINS); + if (includeBoxOptions) { + requireEnum(value.boxOrder, "boxOrder", BOX_ORDERS); + requireFiniteNonNegative(value.padding, "padding"); + requireBoolean(value.clamp, "clamp"); + } + }; + + const obj = objectAt(payload, "payload"); + requireString(obj.imagePath, "imagePath"); + + switch (command) { + case "crop": { + rejectUnknown(obj, ["imagePath", "box", "coordinateSpace", "origin", "boxOrder", "outputPath", "padding", "clamp"]); + requireBox(obj.box, "box"); + requireString(obj.outputPath, "outputPath", true); + validateCoordinates(obj, true); + break; + } + case "crop-multi": + case "annotate": { + const isAnnotate = command === "annotate"; + rejectUnknown(obj, isAnnotate + ? ["imagePath", "boxes", "coordinateSpace", "origin", "boxOrder", "outputPath", "padding", "clamp"] + : ["imagePath", "boxes", "coordinateSpace", "origin", "boxOrder", "outputDir", "padding", "clamp"]); + if (!Array.isArray(obj.boxes) || obj.boxes.length === 0) fail('"boxes" must be a non-empty array'); + for (const [index, item] of obj.boxes.entries()) { + const path = `boxes[${index}]`; + const itemObj = objectAt(item, path); + rejectUnknown(itemObj, isAnnotate ? ["box", "label", "color"] : ["box", "label", "outputPath"], path); + requireBox(itemObj.box, `${path}.box`); + requireString(itemObj.label, `${path}.label`, true); + if (isAnnotate) { + requireString(itemObj.color, `${path}.color`, true); + if (typeof itemObj.color === "string" && !isValidCssColor(itemObj.color)) { + fail(`"${path}.color" is not a valid CSS color: ${JSON.stringify(itemObj.color)}`); + } + } else { + requireString(itemObj.outputPath, `${path}.outputPath`, true); + } + } + requireString(isAnnotate ? obj.outputPath : obj.outputDir, isAnnotate ? "outputPath" : "outputDir", true); + validateCoordinates(obj, true); + break; + } + case "point": { + rejectUnknown(obj, ["imagePath", "point", "radius", "size", "coordinateSpace", "origin", "boxOrder", "outputPath", "padding", "clamp"]); + requirePoint(obj.point, "point"); + if (obj.radius === undefined && obj.size === undefined) fail('requires "radius" or "size"'); + if (obj.radius !== undefined && obj.size !== undefined) fail('"radius" and "size" are mutually exclusive'); + if (obj.radius !== undefined && (typeof obj.radius !== "number" || !Number.isFinite(obj.radius) || obj.radius <= 0)) { + fail('"radius" must be a finite positive number'); + } + if (obj.size !== undefined) { + const size = objectAt(obj.size, "size"); + rejectUnknown(size, ["width", "height"], "size"); + for (const dimension of ["width", "height"] as const) { + const value = size[dimension]; + if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) { + fail(`"size.${dimension}" must be a finite positive number`); + } + } + } + requireString(obj.outputPath, "outputPath", true); + validateCoordinates(obj, true); + break; + } + case "colors": { + rejectUnknown(obj, ["imagePath", "points", "coordinateSpace", "origin", "patchSize"]); + if (!Array.isArray(obj.points) || obj.points.length === 0) fail('"points" must be a non-empty array'); + for (const [index, item] of obj.points.entries()) { + const path = `points[${index}]`; + const itemObj = objectAt(item, path); + rejectUnknown(itemObj, ["point", "label"], path); + requirePoint(itemObj.point, `${path}.point`); + requireString(itemObj.label, `${path}.label`, true); + } + if (obj.patchSize !== undefined && (!Number.isInteger(obj.patchSize) || (obj.patchSize as number) < 1)) { + fail('"patchSize" must be a positive integer'); + } + validateCoordinates(obj, false); + break; + } + default: + fail(`unknown command contract "${command}"`); + } +} + +const NUMBER_PATTERN = "-?\\d+(?:\\.\\d+)?"; +const BOX_COORDS_RE = new RegExp(`^${NUMBER_PATTERN}(?:\\s*,\\s*${NUMBER_PATTERN}){3}$`); +const POINT_COORDS_RE = new RegExp(`^${NUMBER_PATTERN}\\s*,\\s*${NUMBER_PATTERN}$`); + +function parseNumbers(value: string): number[] { + return value.split(",").map((part) => Number(part.trim())); +} + +function parseBoxSpec(value: string, allowColor: boolean): { label?: string; box: BoundingBoxTuple; color?: string } { + const segments = value.split(":").map((segment) => segment.trim()); + let label: string | undefined; + let coords: string | undefined; + let color: string | undefined; + + if (segments.length === 1) { + [coords] = segments; + } else if (segments.length === 2) { + if (BOX_COORDS_RE.test(segments[0])) { + [coords, color] = segments; + } else { + [label, coords] = segments; + } + } else if (segments.length === 3) { + [label, coords, color] = segments; + } + + if (!coords || !BOX_COORDS_RE.test(coords)) { + throw new UsageError(`invalid --box value "${value}"; expected "[label:]left,top,right,bottom${allowColor ? "[:color]" : ""}"`); + } + if (color !== undefined && !allowColor) { + throw new UsageError(`invalid --box value "${value}"; per-box colors are only supported by "vp annotate"`); + } + if (color !== undefined) assertValidColor(color, "--box"); + + return { label, box: parseNumbers(coords) as BoundingBoxTuple, color }; +} + +function parsePointSpec(value: string): { label?: string; point: PointTuple } { + const segments = value.split(":").map((segment) => segment.trim()); + let label: string | undefined; + let coords: string | undefined; + + if (segments.length === 1) { + [coords] = segments; + } else if (segments.length === 2) { + [label, coords] = segments; + } + + if (!coords || !POINT_COORDS_RE.test(coords)) { + throw new UsageError(`invalid --point value "${value}"; expected "[label:]x,y"`); + } + + return { label, point: parseNumbers(coords) as PointTuple }; +} + +function parseSizeSpec(value: string): { width: number; height: number } { + const match = value.trim().match(new RegExp(`^(${NUMBER_PATTERN})\\s*[x,]\\s*(${NUMBER_PATTERN})$`)); + if (!match) { + throw new UsageError(`invalid --size value "${value}"; expected "WxH" such as 60x40`); + } + const size = { width: Number(match[1]), height: Number(match[2]) }; + if (!Number.isFinite(size.width) || !Number.isFinite(size.height) || size.width <= 0 || size.height <= 0) { + throw new UsageError("--size width and height must be positive numbers"); + } + return size; +} + +function parseEnum(value: string | undefined, allowed: readonly T[], aliases: Record, flag: string): T | undefined { + if (value === undefined) return undefined; + const normalized = aliases[value] ?? value; + if (!(allowed as readonly string[]).includes(normalized)) { + throw new UsageError(`invalid ${flag} value "${value}"; expected one of: ${allowed.join(", ")}${Object.keys(aliases).length ? ` (aliases: ${Object.keys(aliases).join(", ")})` : ""}`); + } + return normalized as T; +} + +function parseOptionalNumber(value: string | undefined, flag: string): number | undefined { + if (value === undefined) return undefined; + const parsed = Number(value); + if (!Number.isFinite(parsed)) { + throw new UsageError(`invalid ${flag} value "${value}"; expected a number`); + } + return parsed; +} + +interface CommonValues { + image?: string; + space?: string; + origin?: string; + "box-order"?: string; + padding?: string; + "no-clamp"?: boolean; + json?: string; + compact?: boolean; + quiet?: boolean; + help?: boolean; + version?: boolean; +} + +const COMMON_OPTIONS: ParseArgsConfig["options"] = { + image: { type: "string", short: "i" }, + space: { type: "string", short: "s" }, + origin: { type: "string" }, + "box-order": { type: "string" }, + padding: { type: "string" }, + "no-clamp": { type: "boolean" }, + json: { type: "string" }, + compact: { type: "boolean" }, + quiet: { type: "boolean", short: "q" }, + help: { type: "boolean", short: "h" }, + version: { type: "boolean" }, +}; + +const outputState = { compact: false, quiet: false }; + +function resolveImage(values: CommonValues, positionals: string[]): string { + const image = values.image ?? positionals[0]; + if (!image) { + throw new UsageError("missing source image; pass it as the first argument or with --image"); + } + if (values.image && positionals.length > 0) { + throw new UsageError(`unexpected positional argument "${positionals[0]}" alongside --image`); + } + if (positionals.length > 1) { + throw new UsageError(`unexpected positional argument "${positionals[1]}"`); + } + return image; +} + +function coordinateOptions(values: CommonValues): Pick { + const padding = parseOptionalNumber(values.padding, "--padding"); + if (padding !== undefined && padding < 0) { + throw new UsageError("--padding must be zero or a positive number"); + } + return { + coordinateSpace: parseEnum(values.space, COORDINATE_SPACES, { px: "pixel", norm: "normalized-999", "999": "normalized-999" }, "--space") ?? "pixel", + origin: parseEnum(values.origin, ORIGINS, {}, "--origin"), + boxOrder: parseEnum(values["box-order"], BOX_ORDERS, { ltrb: "left-top-right-bottom", lbrt: "left-bottom-right-top" }, "--box-order"), + padding, + clamp: values["no-clamp"] ? false : undefined, + }; +} + +async function readJsonInput(source: string): Promise { + let raw: string; + if (source === "-") { + if (process.stdin.isTTY) { + throw new UsageError('"--json -" expects JSON piped on stdin, but stdin is a terminal'); + } + raw = await new Promise((resolvePromise, rejectPromise) => { + let buffer = ""; + process.stdin.setEncoding("utf8"); + process.stdin.on("data", (chunk) => { buffer += chunk; }); + process.stdin.on("end", () => resolvePromise(buffer)); + process.stdin.on("error", rejectPromise); + }); + } else { + try { + raw = await readFile(source, "utf8"); + } catch { + throw new UsageError(`--json file not found or unreadable: ${source}`); + } + } + try { + // strip a UTF-8 BOM (common in PowerShell-generated files) + return JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw); + } catch (error) { + throw new UsageError(`--json input is not valid JSON: ${(error as Error).message}`); + } +} + +type CommandArgs = { values: CommonValues & Record; positionals: string[] }; + +function parseCommandArgs(argv: string[], extraOptions: ParseArgsConfig["options"]): CommandArgs { + try { + const { values, positionals } = parseArgs({ + args: argv, + options: { ...COMMON_OPTIONS, ...extraOptions }, + allowPositionals: true, + }); + outputState.compact = Boolean((values as CommonValues).compact); + outputState.quiet = Boolean((values as CommonValues).quiet); + return { values: values as CommandArgs["values"], positionals }; + } catch (error) { + const err = error as Error & { code?: string }; + if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") { + const flag = err.message.match(/Unknown option '([^']+)'/)?.[1] ?? ""; + const known = Object.keys({ ...COMMON_OPTIONS, ...extraOptions }).map((name) => `--${name}`); + const suggestion = closestMatch(flag, known); + throw new UsageError(`unknown option '${flag}'${suggestion ? `; did you mean '${suggestion}'?` : ""}`); + } + throw new UsageError(err.message); + } +} + +const TOOL_CWD = { cwd: process.cwd() }; + +async function runCrop(argv: string[]): Promise { + const { values, positionals } = parseCommandArgs(argv, { + box: { type: "string", multiple: true }, + out: { type: "string", short: "o" }, + }); + if (values.help) return COMMAND_HELP.crop; + if (values.version) return VERSION; + if (values.json) { + const payload = await readJsonInput(values.json); + validateJsonPayload("crop", payload); + return cropBoundingBox(payload as CropBoundingBoxInput, TOOL_CWD); + } + + const boxSpecs = (values.box as string[] | undefined) ?? []; + const missing: string[] = []; + if (!values.image && positionals.length === 0) missing.push(""); + if (boxSpecs.length === 0) missing.push('--box "left,top,right,bottom"'); + if (missing.length > 0) throw usageError("crop", `missing ${missing.join(" and ")}`); + if (boxSpecs.length > 1) throw new UsageError('"vp crop" accepts exactly one --box; use "vp crop-multi" to crop several boxes in one call'); + const { label, box } = parseBoxSpec(boxSpecs[0], false); + if (label) throw new UsageError('"vp crop" does not accept a box label; use "vp crop-multi" for labeled boxes'); + + const options = coordinateOptions(values); + hintContext.space = options.coordinateSpace; + hintContext.coords = box; + warnIfOverwriting(values.out as string | undefined); + warnIfNotPng(values.out as string | undefined); + + return cropBoundingBox({ + imagePath: resolveImage(values, positionals), + box, + outputPath: values.out as string | undefined, + ...options, + }, TOOL_CWD); +} + +async function runCropMulti(argv: string[]): Promise { + const { values, positionals } = parseCommandArgs(argv, { + box: { type: "string", multiple: true }, + "out-dir": { type: "string" }, + }); + if (values.help) return COMMAND_HELP["crop-multi"]; + if (values.version) return VERSION; + if (values.json) { + const payload = await readJsonInput(values.json); + validateJsonPayload("crop-multi", payload); + return cropMultipleBoundingBoxes(payload as CropMultipleBoundingBoxesInput, TOOL_CWD); + } + + const boxSpecs = (values.box as string[] | undefined) ?? []; + const missing: string[] = []; + if (!values.image && positionals.length === 0) missing.push(""); + if (boxSpecs.length === 0) missing.push('--box "[label:]left,top,right,bottom" (repeatable)'); + if (missing.length > 0) throw usageError("crop-multi", `missing ${missing.join(" and ")}`); + + const boxes = boxSpecs.map((spec) => { + const { label, box } = parseBoxSpec(spec, false); + return { label, box }; + }); + const options = coordinateOptions(values); + hintContext.space = options.coordinateSpace; + hintContext.coords = boxes.flatMap((item) => item.box); + + return cropMultipleBoundingBoxes({ + imagePath: resolveImage(values, positionals), + boxes, + outputDir: values["out-dir"] as string | undefined, + ...options, + }, TOOL_CWD); +} + +async function runAnnotate(argv: string[]): Promise { + const { values, positionals } = parseCommandArgs(argv, { + box: { type: "string", multiple: true }, + out: { type: "string", short: "o" }, + }); + if (values.help) return COMMAND_HELP.annotate; + if (values.version) return VERSION; + if (values.json) { + const payload = await readJsonInput(values.json); + validateJsonPayload("annotate", payload); + return annotateBoundingBoxes(payload as AnnotateBoundingBoxesInput, TOOL_CWD); + } + + const boxSpecs = (values.box as string[] | undefined) ?? []; + const missing: string[] = []; + if (!values.image && positionals.length === 0) missing.push(""); + if (boxSpecs.length === 0) missing.push('--box "[label:]left,top,right,bottom[:color]" (repeatable)'); + if (missing.length > 0) throw usageError("annotate", `missing ${missing.join(" and ")}`); + + const boxes = boxSpecs.map((spec) => parseBoxSpec(spec, true)); + const options = coordinateOptions(values); + hintContext.space = options.coordinateSpace; + hintContext.coords = boxes.flatMap((item) => item.box); + warnIfOverwriting(values.out as string | undefined); + warnIfNotPng(values.out as string | undefined); + + return annotateBoundingBoxes({ + imagePath: resolveImage(values, positionals), + boxes, + outputPath: values.out as string | undefined, + ...options, + }, TOOL_CWD); +} + +async function runPoint(argv: string[]): Promise { + const { values, positionals } = parseCommandArgs(argv, { + point: { type: "string" }, + radius: { type: "string" }, + size: { type: "string" }, + out: { type: "string", short: "o" }, + }); + if (values.help) return COMMAND_HELP.point; + if (values.version) return VERSION; + if (values.json) { + const payload = await readJsonInput(values.json); + validateJsonPayload("point", payload); + return cropAroundPoint(payload as CropAroundPointInput, TOOL_CWD); + } + + const missing: string[] = []; + if (!values.image && positionals.length === 0) missing.push(""); + if (!values.point) missing.push('--point "x,y"'); + if (values.radius === undefined && values.size === undefined) missing.push("--radius or --size"); + if (missing.length > 0) throw usageError("point", `missing ${missing.join(" and ")}`); + if (values.radius !== undefined && values.size !== undefined) { + throw new UsageError("--radius and --size are mutually exclusive"); + } + const { label, point } = parsePointSpec(values.point as string); + if (label) throw new UsageError('"vp point" does not accept a point label'); + + const radius = parseOptionalNumber(values.radius as string | undefined, "--radius"); + if (radius !== undefined && radius <= 0) { + throw new UsageError("--radius must be a positive number"); + } + + const options = coordinateOptions(values); + hintContext.space = options.coordinateSpace; + hintContext.coords = point; + warnIfOverwriting(values.out as string | undefined); + warnIfNotPng(values.out as string | undefined); + + return cropAroundPoint({ + imagePath: resolveImage(values, positionals), + point, + radius, + size: values.size !== undefined ? parseSizeSpec(values.size as string) : undefined, + outputPath: values.out as string | undefined, + ...options, + }, TOOL_CWD); +} + +async function runColors(argv: string[]): Promise { + const { values, positionals } = parseCommandArgs(argv, { + point: { type: "string", multiple: true }, + patch: { type: "string" }, + }); + if (values.help) return COMMAND_HELP.colors; + if (values.version) return VERSION; + for (const [key, flag] of [["box-order", "--box-order"], ["padding", "--padding"], ["no-clamp", "--no-clamp"]] as const) { + if (values[key] !== undefined) throw new UsageError(`${flag} does not apply to "vp colors"`); + } + if (values.json) { + const payload = await readJsonInput(values.json); + validateJsonPayload("colors", payload); + return sampleColors(payload as SampleColorsInput, TOOL_CWD); + } + + const pointSpecs = (values.point as string[] | undefined) ?? []; + const missing: string[] = []; + if (!values.image && positionals.length === 0) missing.push(""); + if (pointSpecs.length === 0) missing.push('--point "[label:]x,y" (repeatable)'); + if (missing.length > 0) throw usageError("colors", `missing ${missing.join(" and ")}`); + + const patchSize = parseOptionalNumber(values.patch as string | undefined, "--patch"); + if (patchSize !== undefined && (!Number.isInteger(patchSize) || patchSize < 1)) { + throw new UsageError("--patch must be a positive integer"); + } + if (patchSize !== undefined && Number.isInteger(patchSize) && patchSize > 0 && patchSize % 2 === 0) { + pendingWarnings.push(`--patch ${patchSize} is even; using ${patchSize + 1} (patch must be odd)`); + } + + const coordinate = coordinateOptions(values); + return sampleColors({ + imagePath: resolveImage(values, positionals), + points: pointSpecs.map(parsePointSpec), + coordinateSpace: coordinate.coordinateSpace, + origin: coordinate.origin, + patchSize, + }, TOOL_CWD); +} + +const COMMANDS: Record Promise> = { + crop: runCrop, + "crop-multi": runCropMulti, + annotate: runAnnotate, + point: runPoint, + colors: runColors, +}; + +function summarize(command: string, details: any): string | undefined { + switch (command) { + case "crop": + case "point": { + const box = details.resolvedPixelBox; + return `cropped → ${details.outputPath} (${box.width}×${box.height}px${details.clamped ? ", clamped" : ""})`; + } + case "crop-multi": { + const labels = details.crops.map((crop: any) => crop.label).filter(Boolean); + const where = details.outputDir ?? (details.crops[0] ? dirname(details.crops[0].outputPath) : ""); + return `cropped ${details.crops.length} boxes${labels.length ? ` (${labels.join(", ")})` : ""} → ${where}`; + } + case "annotate": + return `annotated ${details.boxes.length} box${details.boxes.length === 1 ? "" : "es"} → ${details.outputPath}`; + case "colors": + return `sampled ${details.samples.map((sample: any) => { + const swatch = COLOR_ENABLED ? `\x1b[48;2;${sample.rgb.r};${sample.rgb.g};${sample.rgb.b}m \x1b[0m ` : ""; + return `${swatch}${sample.label ?? `point-${sample.index + 1}`}=${sample.hex}`; + }).join(" ")}`; + default: + return undefined; + } +} + +function clampWarning(item: any, label?: string): string | undefined { + if (!item.clamped) return undefined; + const kept = item.resolvedPixelBox.width * item.resolvedPixelBox.height; + const asked = item.unclampedPixelBox.width * item.unclampedPixelBox.height; + if (asked <= 0 || kept / asked >= 0.5) return undefined; + const pct = (1 - kept / asked) * 100; + const shown = pct >= 99.5 ? "over 99%" : `${Math.round(pct)}%`; + return `${shown} of the requested box${label ? ` "${label}"` : ""} was outside the image and was clipped`; +} + +function collectWarnings(command: string, details: any): string[] { + const warnings: string[] = []; + switch (command) { + case "crop": + case "point": { + const warning = clampWarning(details); + if (warning) warnings.push(warning); + break; + } + case "crop-multi": + for (const crop of details.crops) { + const warning = clampWarning(crop, crop.label ?? `#${crop.index + 1}`); + if (warning) warnings.push(warning); + } + break; + case "annotate": + for (const box of details.boxes) { + const warning = clampWarning(box, box.label ?? `#${box.index + 1}`); + if (warning) warnings.push(warning); + } + break; + case "colors": + for (const sample of details.samples) { + if (sample.clamped) { + warnings.push(`point ${sample.label ?? `#${sample.index + 1}`} [${sample.inputPoint.join(", ")}] is outside the image; sampled the nearest edge pixel (${sample.resolvedPixelPoint.x}, ${sample.resolvedPixelPoint.y})`); + } + } + break; + } + const orientation = command === "crop-multi" ? details.crops[0]?.source?.orientation : details.source?.orientation; + if (orientation !== undefined && orientation > 1) { + warnings.push(`image has EXIF orientation ${orientation}; coordinates apply to the stored (un-rotated) pixels`); + } + return warnings; +} + +function augmentError(error: unknown): unknown { + if (!(error instanceof Error)) return error; + + if (error.message.includes("completely outside") + && hintContext.space === "pixel" + && hintContext.coords?.every((value) => value >= 0 && value <= 999)) { + error.message += "\nhint: all coordinates fall within 0-999 — if they are normalized visual-primitive coordinates, add --space 999"; + } + + const missingFile = error.message.match(/Input file is missing or cannot be read: (.+)/); + if (missingFile) { + const path = missingFile[1].trim(); + const dir = dirname(path); + if (existsSync(dir)) { + const suggestion = closestMatch(basename(path), readdirSync(dir)); + if (suggestion) error.message += `\nhint: did you mean "${join(dir, suggestion)}"?`; + } + } + + return error; +} + +async function main(): Promise { + const [command, ...rest] = process.argv.slice(2); + + if (!command || command === "--help" || command === "-h") { + console.log(GLOBAL_HELP); + return; + } + if (command === "help") { + const target = rest[0]; + if (!target) { + console.log(GLOBAL_HELP); + return; + } + if (COMMAND_HELP[target]) { + console.log(COMMAND_HELP[target]); + return; + } + const suggestion = closestMatch(target, Object.keys(COMMANDS)); + throw new UsageError(`unknown command "${target}"${suggestion ? `; did you mean "vp help ${suggestion}"?` : ""}`); + } + if (command === "--version" || command === "-v") { + console.log(VERSION); + return; + } + + const run = COMMANDS[command]; + if (!run) { + const suggestion = closestMatch(command, [...Object.keys(COMMANDS), "help"]); + throw new UsageError(`unknown command "${command}"; ${suggestion ? `did you mean "${suggestion}"? ` : ""}expected one of: ${Object.keys(COMMANDS).join(", ")}`); + } + currentCommand = command; + + let result: unknown; + try { + result = await run(rest); + } catch (error) { + throw augmentError(error); + } + if (typeof result === "string") { + console.log(result); + return; + } + console.log(JSON.stringify(result, null, outputState.compact ? undefined : 2)); + if (!outputState.quiet) { + for (const warning of [...pendingWarnings, ...collectWarnings(command, result)]) { + console.error(paint(33, `warning: ${warning}`)); + } + const summary = summarize(command, result); + if (summary) console.error(summary); + } +} + +main().catch((error: unknown) => { + const message = error instanceof Error ? error.message : String(error); + console.error(paint(31, `error: ${message}`)); + if (error instanceof UsageError && currentCommand && !message.includes("--help")) { + console.error(`run "vp ${currentCommand} --help" for details`); + } + process.exit(error instanceof UsageError ? 2 : 1); +}); diff --git a/src/crop.ts b/src/crop.ts index 05bbf82..6a58b85 100644 --- a/src/crop.ts +++ b/src/crop.ts @@ -154,6 +154,9 @@ function resolvePixelBox( } const resolvedPixelBox = options.clamp ? clampBox(unclampedPixelBox, image) : unclampedPixelBox; + if (options.clamp && (resolvedPixelBox.width <= 0 || resolvedPixelBox.height <= 0)) { + throw new Error(`box resolves to pixel rect [${unclampedPixelBox.left}, ${unclampedPixelBox.top}, ${unclampedPixelBox.right}, ${unclampedPixelBox.bottom}], completely outside the ${image.width}x${image.height} image`); + } assertPositiveArea(resolvedPixelBox); return { @@ -164,14 +167,14 @@ function resolvePixelBox( }; } -function defaultOutputPath(imagePath: string, input: CropBoundingBoxInput): string { +function defaultOutputPath(imagePath: string, input: CropBoundingBoxInput, cwd: string): string { const parsedExt = extname(imagePath); const base = basename(imagePath, parsedExt); const hash = createHash("sha256") .update(JSON.stringify({ imagePath, input })) .digest("hex") .slice(0, 12); - return join(dirname(imagePath), `${base}.crop-${hash}.png`); + return join(cwd, `${base}.crop-${hash}.png`); } export async function resolveCropBoundingBoxDetails( @@ -204,6 +207,7 @@ export async function resolveCropBoundingBoxDetails( width: metadata.width, height: metadata.height, format: metadata.format, + ...(metadata.orientation !== undefined ? { orientation: metadata.orientation } : {}), }, input: { box: input.box, @@ -224,7 +228,7 @@ export async function cropBoundingBox( options: CropBoundingBoxOptions, ): Promise { if (options.signal?.aborted) { - throw new Error("crop_bounding_box was cancelled"); + throw new Error("crop was cancelled"); } const imagePath = normalizeToolPath(input.imagePath, options.cwd); @@ -236,14 +240,14 @@ export async function cropBoundingBox( const outputPath = input.outputPath ? normalizeToolPath(input.outputPath, options.cwd) - : defaultOutputPath(imagePath, input); + : defaultOutputPath(imagePath, input, options.cwd); const details = await resolveCropBoundingBoxDetails(input, options, outputPath); await mkdir(dirname(outputPath), { recursive: true }); if (options.signal?.aborted) { - throw new Error("crop_bounding_box was cancelled"); + throw new Error("crop was cancelled"); } await sharp(imagePath) diff --git a/src/extension.ts b/src/extension.ts deleted file mode 100644 index 3c52703..0000000 --- a/src/extension.ts +++ /dev/null @@ -1,171 +0,0 @@ -import { dirname } from "node:path"; -import { fileURLToPath } from "node:url"; -import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; -import { cropBoundingBox } from "./crop.ts"; -import { - annotateBoundingBoxesSchema, - cropAroundPointSchema, - cropBoundingBoxSchema, - cropMultipleBoundingBoxesSchema, - sampleColorsSchema, - type CropBoundingBoxInput, - type SampleColorsInput, -} from "./schema.ts"; -import { - annotateBoundingBoxes, - cropAroundPoint, - cropMultipleBoundingBoxes, - sampleColors, - type AnnotateBoundingBoxesInput, - type CropAroundPointInput, - type CropMultipleBoundingBoxesInput, -} from "./phase2.ts"; - -type ToolInput = CropBoundingBoxInput | CropMultipleBoundingBoxesInput | AnnotateBoundingBoxesInput | CropAroundPointInput | SampleColorsInput; - -interface PiLike { - registerTool(tool: { - name: string; - label: string; - description: string; - promptSnippet?: string; - promptGuidelines?: string[]; - parameters: unknown; - execute: ( - toolCallId: string, - params: ToolInput, - signal?: AbortSignal, - onUpdate?: unknown, - ctx?: { cwd?: string }, - ) => Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }>; - }): void; -} - -export interface VisualPrimitivesOptions { - pluginDir: string; -} - -export function registerVisualPrimitives(pi: PiLike | ExtensionAPI, _options: VisualPrimitivesOptions): void { - pi.registerTool({ - name: "crop_bounding_box", - label: "Crop Bounding Box", - description: "Crop one image or screenshot region for focused visual evidence. Supports visual-primitive normalized 0-999 and pixel coordinates, top-left and bottom-left origins, padding, and bounds clamping.", - promptSnippet: "Crop a visually relevant region from an image, screenshot, or UI render so the agent can inspect it before drawing conclusions.", - promptGuidelines: [ - "Use crop_bounding_box to isolate one visually relevant region when answering image, screenshot, UI reproduction, or visual QA questions.", - "Coordinates may come from the user or from the agent's provisional region estimate; inspect the crop before making detailed claims.", - "Prefer coordinateSpace: pixel for screenshots and rendered UI unless the source clearly uses normalized visual-primitive coordinates.", - "For bottom-left coordinate systems, set origin to bottom-left and boxOrder to left-bottom-right-top.", - ], - parameters: cropBoundingBoxSchema, - async execute(_toolCallId, params, signal, _onUpdate, ctx) { - const details = await cropBoundingBox(params as CropBoundingBoxInput, { cwd: ctx?.cwd ?? process.cwd(), signal }); - return { - content: [{ - type: "text", - text: `Cropped bounding box to ${details.outputPath} (left=${details.resolvedPixelBox.left}, top=${details.resolvedPixelBox.top}, width=${details.resolvedPixelBox.width}, height=${details.resolvedPixelBox.height})`, - }], - details, - }; - }, - }); - - pi.registerTool({ - name: "crop_multiple_bounding_boxes", - label: "Crop Multiple Bounding Boxes", - description: "Crop multiple regions from the same image or screenshot in one fail-fast call for visual evidence and UI decomposition.", - promptSnippet: "Batch-crop several semantically labeled regions from one image, screenshot, or UI render for focused inspection.", - promptGuidelines: [ - "Use crop_multiple_bounding_boxes when a complex image, complex screenshot, or UI should be inspected as multiple regions.", - "Label boxes with semantic region names such as header, card, sidebar, form, button, chart, or footer so artifacts remain useful during implementation and comparison.", - "This tool fails fast on the first invalid box; use single crop calls when partial progress is required.", - ], - parameters: cropMultipleBoundingBoxesSchema, - async execute(_toolCallId, params, signal, _onUpdate, ctx) { - const details = await cropMultipleBoundingBoxes(params as CropMultipleBoundingBoxesInput, { cwd: ctx?.cwd ?? process.cwd(), signal }); - return { - content: [{ - type: "text", - text: `Cropped ${details.crops.length} bounding boxes: ${details.crops.map((crop) => crop.outputPath).join(", ")}`, - }], - details, - }; - }, - }); - - pi.registerTool({ - name: "annotate_bounding_boxes", - label: "Annotate Bounding Boxes", - description: "Create an annotated preview image by drawing provided or agent-estimated bounding boxes over the source image.", - promptSnippet: "Draw boxes over an image or screenshot to verify region assumptions before relying on them for visual conclusions.", - promptGuidelines: [ - "Use annotate_bounding_boxes to make region assumptions visible before relying on them for visual conclusions.", - "Use it for UI screenshot decomposition, visual comparison planning, and frontend reproduction checkpoints.", - "The output image keeps the source dimensions and overlays simple box outlines and optional labels.", - "This tool does not detect elements; it only draws boxes selected or provided by the agent or user.", - ], - parameters: annotateBoundingBoxesSchema, - async execute(_toolCallId, params, signal, _onUpdate, ctx) { - const details = await annotateBoundingBoxes(params as AnnotateBoundingBoxesInput, { cwd: ctx?.cwd ?? process.cwd(), signal }); - return { - content: [{ - type: "text", - text: `Annotated ${details.boxes.length} bounding boxes to ${details.outputPath}`, - }], - details, - }; - }, - }); - - pi.registerTool({ - name: "crop_around_point", - label: "Crop Around Point", - description: "Crop an image region centered on a point of interest using an explicit radius or size.", - promptSnippet: "Crop around a point-based visual primitive or UI point of interest when focused inspection needs an explicit radius or size.", - promptGuidelines: [ - "Use crop_around_point when the visual question centers on a point of interest such as an overlap, alignment issue, cursor target, label anchor, or small defect.", - "Require an explicit radius or size based on the intended inspection area; do not invent arbitrary defaults without a reason.", - "Coordinate space, origin, padding, and clamp behavior match crop_bounding_box.", - "Inspect the crop before drawing detailed conclusions.", - ], - parameters: cropAroundPointSchema, - async execute(_toolCallId, params, signal, _onUpdate, ctx) { - const details = await cropAroundPoint(params as CropAroundPointInput, { cwd: ctx?.cwd ?? process.cwd(), signal }); - return { - content: [{ - type: "text", - text: `Cropped around point to ${details.outputPath} (left=${details.resolvedPixelBox.left}, top=${details.resolvedPixelBox.top}, width=${details.resolvedPixelBox.width}, height=${details.resolvedPixelBox.height})`, - }], - details, - }; - }, - }); - - pi.registerTool({ - name: "sample_colors", - label: "Sample Colors", - description: "Sample exact colors at provided image points for CSS-level color precision and visual evidence.", - promptSnippet: "Sample exact RGB, hex, OKLab, and patch mean colors from user- or agent-provided points in an image or screenshot.", - promptGuidelines: [ - "Use sample_colors when color-sensitive visual analysis needs exact values for CSS-level color precision.", - "Sample only provided points; choose points from direct visual inspection, annotations, crops, or user instructions.", - "Use a small odd patchSize such as 3 or 5 when antialiasing, gradients, or texture make a single pixel misleading.", - "This tool does not detect palettes, dominant colors, objects, or regions automatically.", - ], - parameters: sampleColorsSchema, - async execute(_toolCallId, params, signal, _onUpdate, ctx) { - const details = await sampleColors(params as SampleColorsInput, { cwd: ctx?.cwd ?? process.cwd(), signal }); - return { - content: [{ - type: "text", - text: `Sampled ${details.samples.length} color${details.samples.length === 1 ? "" : "s"}: ${details.samples.map((sample) => `${sample.label ?? `point-${sample.index + 1}`}: ${sample.hex}`).join(", ")}`, - }], - details, - }; - }, - }); -} - -export function pluginDirFromImportMeta(url: string): string { - return dirname(fileURLToPath(url)); -} diff --git a/src/phase2.ts b/src/phase2.ts index 5e8f519..9eb32c0 100644 --- a/src/phase2.ts +++ b/src/phase2.ts @@ -36,6 +36,7 @@ export interface AnnotateBoundingBoxesDetails { width: number; height: number; format?: string; + orientation?: number; }; boxes: Array & { index: number; label?: string }>; } @@ -66,6 +67,7 @@ export interface SampleColorsDetails { width: number; height: number; format?: string; + orientation?: number; }; input: { coordinateSpace: CoordinateSpace; @@ -77,6 +79,7 @@ export interface SampleColorsDetails { label?: string; inputPoint: [number, number]; resolvedPixelPoint: { x: number; y: number }; + clamped: boolean; rgb: { r: number; g: number; b: number }; alpha: number; hex: string; @@ -102,7 +105,7 @@ function normalizeToolPath(path: string, cwd: string): string { } function slugifyLabel(label: string): string { - const slug = label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""); + const slug = label.toLowerCase().replace(/[^\p{Letter}\p{Number}]+/gu, "-").replace(/^-+|-+$/g, ""); return slug || "box"; } @@ -116,14 +119,14 @@ function defaultMultiCropOutputPath(imagePath: string, input: CropMultipleBoundi const base = basename(resolvedImagePath, parsedExt); const suffix = label ? `-${slugifyLabel(label)}` : ""; const fileName = `${base}.crop-${String(index + 1).padStart(3, "0")}${suffix}-${hashInput({ imagePath, input, index, label })}.png`; - return input.outputDir ? join(input.outputDir, fileName) : join(dirname(resolvedImagePath), fileName); + return input.outputDir ? join(input.outputDir, fileName) : join(cwd, fileName); } function defaultAnnotationOutputPath(imagePath: string, input: AnnotateBoundingBoxesInput, cwd: string): string { const resolvedImagePath = normalizeToolPath(imagePath, cwd); const parsedExt = extname(resolvedImagePath); const base = basename(resolvedImagePath, parsedExt); - return join(dirname(resolvedImagePath), `${base}.annotated-${hashInput({ imagePath, input })}.png`); + return join(cwd, `${base}.annotated-${hashInput({ imagePath, input })}.png`); } function escapeXml(value: string): string { @@ -134,6 +137,24 @@ function escapeXml(value: string): string { .replace(/"/g, """); } +function estimateTextWidth(text: string, fontSize: number): number { + let units = 0; + for (const char of text) { + units += char.codePointAt(0)! > 0xff ? 1 : 0.62; + } + return Math.ceil(units * fontSize); +} + +function contrastingTextColor(color: string): string { + const match = color.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i); + if (!match) return "#ffffff"; + const hex = match[1].length === 3 ? [...match[1]].map((c) => c + c).join("") : match[1]; + const r = parseInt(hex.slice(0, 2), 16); + const g = parseInt(hex.slice(2, 4), 16); + const b = parseInt(hex.slice(4, 6), 16); + return (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.6 ? "#000000" : "#ffffff"; +} + function assertFinitePoint(point: [number, number]): void { if (!Array.isArray(point) || point.length !== 2 || !point.every((value) => Number.isFinite(value))) { throw new Error("point must contain exactly two finite coordinates"); @@ -162,12 +183,14 @@ function resolvePixelPoint( image: { width: number; height: number }, coordinateSpace: CoordinateSpace, origin: CoordinateOrigin, -): { x: number; y: number } { +): { x: number; y: number; clamped: boolean } { assertFinitePoint(point); - const x = clampPixelIndex(scalePointCoordinate(point[0], image.width, coordinateSpace), image.width); + const rawX = scalePointCoordinate(point[0], image.width, coordinateSpace); + const x = clampPixelIndex(rawX, image.width); const yInSpace = scalePointCoordinate(point[1], image.height, coordinateSpace); - const y = origin === "bottom-left" ? image.height - 1 - yInSpace : yInSpace; - return { x, y: clampPixelIndex(y, image.height) }; + const rawY = origin === "bottom-left" ? image.height - 1 - yInSpace : yInSpace; + const y = clampPixelIndex(rawY, image.height); + return { x, y, clamped: x !== rawX || y !== rawY }; } function toHex(rgb: { r: number; g: number; b: number }): string { @@ -235,7 +258,7 @@ function pointBox(input: CropAroundPointInput): BoundingBoxTuple { return [x - halfWidth, y - halfHeight, x + halfWidth, y + halfHeight]; } - throw new Error("crop_around_point requires an explicit radius or size"); + throw new Error("crop-around-point requires an explicit radius or size"); } export async function cropMultipleBoundingBoxes( @@ -313,12 +336,26 @@ export async function annotateBoundingBoxes( const outputPath = input.outputPath ? normalizeToolPath(input.outputPath, options.cwd) : defaultAnnotationOutputPath(input.imagePath, input, options.cwd); await mkdir(dirname(outputPath), { recursive: true }); + const fontSize = Math.max(12, Math.round(Math.min(metadata.width, metadata.height) / 40)); + const strokeWidth = Math.max(2, Math.round(fontSize / 8)); + const chipHeight = Math.round(fontSize * 1.6); + const chipPadX = Math.round(fontSize * 0.45); + const svg = ` ${boxes.map((item) => { const box = item.resolvedPixelBox; const color = escapeXml(item.color); - const label = item.label ? `${escapeXml(item.label)}` : ""; - return `${label}`; + const rect = ``; + if (!item.label) return rect; + + const chipWidth = estimateTextWidth(item.label, fontSize) + chipPadX * 2; + const chipLeft = Math.max(0, Math.min(box.left, metadata.width! - chipWidth)); + const aboveTop = box.top - chipHeight - Math.ceil(strokeWidth / 2); + const chipTop = aboveTop >= 0 ? aboveTop : box.top + Math.ceil(strokeWidth / 2); + const textY = chipTop + Math.round(chipHeight * 0.72); + const chip = `` + + `${escapeXml(item.label)}`; + return `${rect}${chip}`; }).join("\n")} `; @@ -334,6 +371,7 @@ ${boxes.map((item) => { width: metadata.width, height: metadata.height, format: metadata.format, + ...(metadata.orientation !== undefined ? { orientation: metadata.orientation } : {}), }, boxes: boxes.map(({ color: _color, ...item }) => item), }; @@ -424,7 +462,8 @@ export async function sampleColors( index, label: item.label, inputPoint: point, - resolvedPixelPoint: resolved, + resolvedPixelPoint: { x: resolved.x, y: resolved.y }, + clamped: resolved.clamped, rgb, alpha: pixel.alpha, hex: toHex(rgb), @@ -452,6 +491,7 @@ export async function sampleColors( width: metadata.width, height: metadata.height, format: metadata.format, + ...(metadata.orientation !== undefined ? { orientation: metadata.orientation } : {}), }, input: { coordinateSpace, diff --git a/src/schema.ts b/src/schema.ts index 21944a2..6728acb 100644 --- a/src/schema.ts +++ b/src/schema.ts @@ -49,6 +49,7 @@ export interface CropBoundingBoxDetails { width: number; height: number; format?: string; + orientation?: number; }; input: { box: BoundingBoxTuple; @@ -62,209 +63,3 @@ export interface CropBoundingBoxDetails { unclampedPixelBox: ResolvedPixelBox; clamped: boolean; } - -export const cropBoundingBoxSchema = { - type: "object", - additionalProperties: false, - required: ["imagePath", "box"], - properties: { - imagePath: { - type: "string", - description: "Source image path. Relative paths resolve against the current Pi working directory. A leading @ is ignored.", - }, - box: { - type: "array", - minItems: 4, - maxItems: 4, - items: { type: "number" }, - description: "Bounding box coordinates. Defaults to normalized 0-999 [left, top, right, bottom].", - }, - coordinateSpace: { - type: "string", - enum: COORDINATE_SPACES, - description: "Coordinate space for box values. Defaults to normalized-999, matching visual-primitives paper examples.", - }, - origin: { - type: "string", - enum: ORIGINS, - description: "Coordinate origin. top-left means y grows downward; bottom-left means y grows upward. Defaults to top-left.", - }, - boxOrder: { - type: "string", - enum: BOX_ORDERS, - description: "Input box order. Defaults to left-top-right-bottom. Use left-bottom-right-top for bottom-left style boxes.", - }, - outputPath: { - type: "string", - description: "Optional output PNG path. Relative paths resolve against the current Pi working directory.", - }, - padding: { - type: "number", - description: "Pixel padding to add around the resolved rectangle before clamp or bounds validation. Defaults to 0.", - }, - clamp: { - type: "boolean", - description: "When true, clip out-of-bounds rectangles to image bounds. When false, out-of-bounds rectangles fail. Defaults to true.", - }, - }, -} as const; - -const coordinateProperties = { - coordinateSpace: cropBoundingBoxSchema.properties.coordinateSpace, - origin: cropBoundingBoxSchema.properties.origin, - boxOrder: cropBoundingBoxSchema.properties.boxOrder, - padding: cropBoundingBoxSchema.properties.padding, - clamp: cropBoundingBoxSchema.properties.clamp, -} as const; - -const labeledBoxSchema = { - type: "object", - additionalProperties: false, - required: ["box"], - properties: { - box: cropBoundingBoxSchema.properties.box, - label: { - type: "string", - description: "Optional label used in metadata and deterministic output filenames.", - }, - outputPath: { - type: "string", - description: "Optional per-box output PNG path. Relative paths resolve against the current Pi working directory.", - }, - }, -} as const; - -const annotationBoxSchema = { - type: "object", - additionalProperties: false, - required: ["box"], - properties: { - box: cropBoundingBoxSchema.properties.box, - label: { - type: "string", - description: "Optional label drawn near the box and returned in metadata.", - }, - color: { - type: "string", - description: "Optional SVG/CSS color for the box outline. Defaults to a high-contrast pink.", - }, - }, -} as const; - -export const cropMultipleBoundingBoxesSchema = { - type: "object", - additionalProperties: false, - required: ["imagePath", "boxes"], - properties: { - imagePath: cropBoundingBoxSchema.properties.imagePath, - boxes: { - type: "array", - minItems: 1, - items: labeledBoxSchema, - description: "Bounding boxes to crop from the same source image. Fails fast on the first invalid box.", - }, - outputDir: { - type: "string", - description: "Optional directory for generated crop files. Relative paths resolve against the current Pi working directory.", - }, - ...coordinateProperties, - }, -} as const; - -export const annotateBoundingBoxesSchema = { - type: "object", - additionalProperties: false, - required: ["imagePath", "boxes"], - properties: { - imagePath: cropBoundingBoxSchema.properties.imagePath, - boxes: { - type: "array", - minItems: 1, - items: annotationBoxSchema, - description: "Bounding boxes to draw over the source image.", - }, - outputPath: { - type: "string", - description: "Optional annotated PNG path. Relative paths resolve against the current Pi working directory.", - }, - ...coordinateProperties, - }, -} as const; - -const pointSchema = { - type: "array", - minItems: 2, - maxItems: 2, - items: { type: "number" }, - description: "Point coordinates.", -} as const; - -const labeledPointSchema = { - type: "object", - additionalProperties: false, - required: ["point"], - properties: { - point: pointSchema, - label: { - type: "string", - description: "Optional label returned in sampled color metadata.", - }, - }, -} as const; - -export const cropAroundPointSchema = { - type: "object", - additionalProperties: false, - required: ["imagePath", "point"], - oneOf: [ - { required: ["radius"], not: { required: ["size"] } }, - { required: ["size"], not: { required: ["radius"] } }, - ], - properties: { - imagePath: cropBoundingBoxSchema.properties.imagePath, - point: { - ...pointSchema, - description: "Point coordinates to center the crop around.", - }, - radius: { - type: "number", - exclusiveMinimum: 0, - description: "Explicit crop radius in the selected coordinate space. Mutually exclusive with size.", - }, - size: { - type: "object", - additionalProperties: false, - required: ["width", "height"], - properties: { - width: { type: "number", exclusiveMinimum: 0, description: "Explicit crop width in the selected coordinate space." }, - height: { type: "number", exclusiveMinimum: 0, description: "Explicit crop height in the selected coordinate space." }, - }, - description: "Explicit crop size in the selected coordinate space. Mutually exclusive with radius.", - }, - outputPath: cropBoundingBoxSchema.properties.outputPath, - ...coordinateProperties, - }, -} as const; - -export const sampleColorsSchema = { - type: "object", - additionalProperties: false, - required: ["imagePath", "points"], - properties: { - imagePath: cropBoundingBoxSchema.properties.imagePath, - points: { - type: "array", - minItems: 1, - items: labeledPointSchema, - description: "Points to sample from the source image.", - }, - coordinateSpace: cropBoundingBoxSchema.properties.coordinateSpace, - origin: cropBoundingBoxSchema.properties.origin, - patchSize: { - type: "integer", - minimum: 1, - default: 1, - description: "Odd positive square patch size in pixels. Even values are rounded up to the next odd value.", - }, - }, -} as const; diff --git a/tests/cli.test.ts b/tests/cli.test.ts new file mode 100644 index 0000000..3091021 --- /dev/null +++ b/tests/cli.test.ts @@ -0,0 +1,702 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import sharp from "sharp"; + +const execFileAsync = promisify(execFile); +const CLI_PATH = fileURLToPath(new URL("../src/cli.ts", import.meta.url)); +const PACKAGE_JSON_PATH = fileURLToPath(new URL("../package.json", import.meta.url)); + +async function runCli(args: string[], options: { cwd?: string } = {}): Promise<{ code: number; stdout: string; stderr: string }> { + try { + const { stdout, stderr } = await execFileAsync(process.execPath, [CLI_PATH, ...args], { cwd: options.cwd }); + return { code: 0, stdout, stderr }; + } catch (error) { + const failed = error as { code?: number; stdout?: string; stderr?: string }; + return { code: failed.code ?? 1, stdout: failed.stdout ?? "", stderr: failed.stderr ?? "" }; + } +} + +async function withTempDir(fn: (dir: string) => Promise): Promise { + const dir = await mkdtemp(join(tmpdir(), "visual-primitives-cli-test-")); + try { + await fn(dir); + } finally { + await rm(dir, { recursive: true, force: true }); + } +} + +async function createFixture(path: string, width = 100, height = 80): Promise { + await sharp({ + create: { + width, + height, + channels: 4, + background: { r: 120, g: 80, b: 40, alpha: 1 }, + }, + }).png().toFile(path); +} + +async function imageSize(path: string): Promise<{ width: number; height: number }> { + const metadata = await sharp(path).metadata(); + return { width: metadata.width!, height: metadata.height! }; +} + +test("vp --help lists all commands", async () => { + const result = await runCli(["--help"]); + assert.equal(result.code, 0); + for (const command of ["crop", "crop-multi", "annotate", "point", "colors"]) { + assert.match(result.stdout, new RegExp(`\\b${command}\\b`)); + } +}); + +test("package manifest exposes the scoped CLI without a Pi extension peer", async () => { + const packageJson = JSON.parse(await readFile(PACKAGE_JSON_PATH, "utf8")); + + assert.equal(packageJson.name, "@mapleluvr/visual-primitives"); + assert.deepEqual(packageJson.bin, { + vp: "./dist/cli.js", + "visual-primitives": "./dist/cli.js", + }); + assert.equal(packageJson.peerDependencies?.["@earendil-works/pi-coding-agent"], undefined); + assert.equal(packageJson.pi?.extensions, undefined); +}); + +test("vp version is derived from the package manifest", async () => { + const packageJson = JSON.parse(await readFile(PACKAGE_JSON_PATH, "utf8")); + const source = await readFile(CLI_PATH, "utf8"); + const result = await runCli(["--version"]); + + assert.equal(result.code, 0, result.stderr); + assert.equal(result.stdout.trim(), packageJson.version); + assert.doesNotMatch(source, /const VERSION\s*=\s*["'][^"']+["']/); +}); + +test("vp crop crops a pixel box and prints details JSON", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "crop.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "10,20,60,80", "--space", "pixel", "--out", out]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.equal(details.resolvedPixelBox.width, 50); + assert.equal(details.resolvedPixelBox.height, 60); + assert.equal(details.input.coordinateSpace, "pixel"); + assert.deepEqual(await imageSize(out), { width: 50, height: 60 }); + }); +}); + +test("vp crop resolves relative paths against the working directory", async () => { + await withTempDir(async (dir) => { + await createFixture(join(dir, "scene.png")); + + const result = await runCli(["crop", "scene.png", "--box", "0,0,40,40", "--space", "pixel", "--out", "out.png"], { cwd: dir }); + assert.equal(result.code, 0, result.stderr); + assert.deepEqual(await imageSize(join(dir, "out.png")), { width: 40, height: 40 }); + }); +}); + +test("vp crop-multi crops labeled boxes into --out-dir", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const outDir = join(dir, "crops"); + await createFixture(image); + + const result = await runCli([ + "crop-multi", image, "--space", "pixel", "--out-dir", outDir, + "--box", "title:10,10,50,30", + "--box", "button:20,40,80,70", + ]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.equal(details.crops.length, 2); + assert.equal(details.crops[0].label, "title"); + assert.equal(details.crops[1].label, "button"); + + const files = await readdir(outDir); + assert.equal(files.length, 2); + assert.ok(files.some((file) => file.includes("title"))); + assert.ok(files.some((file) => file.includes("button"))); + }); +}); + +test("vp annotate keeps source dimensions and accepts per-box colors", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "annotated.png"); + await createFixture(image); + + const result = await runCli([ + "annotate", image, "--space", "pixel", "--out", out, + "--box", "target:10,10,60,50", + "--box", "header:0,0,99,20:#00aaff", + ]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.equal(details.boxes.length, 2); + assert.deepEqual(await imageSize(out), { width: 100, height: 80 }); + }); +}); + +test("vp point crops around a point with a radius", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "point.png"); + await createFixture(image); + + const result = await runCli(["point", image, "--point", "50,40", "--radius", "10", "--space", "pixel", "--out", out]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.deepEqual(details.input.point, [50, 40]); + assert.equal(details.input.radius, 10); + assert.deepEqual(await imageSize(out), { width: 20, height: 20 }); + }); +}); + +test("vp point accepts --size WxH", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "sized.png"); + await createFixture(image); + + const result = await runCli(["point", image, "--point", "50,40", "--size", "30x20", "--space", "pixel", "--out", out]); + assert.equal(result.code, 0, result.stderr); + assert.deepEqual(await imageSize(out), { width: 30, height: 20 }); + }); +}); + +test("vp colors samples the fixture color", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["colors", image, "--space", "pixel", "--patch", "3", "--point", "center:50,40"]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.equal(details.samples.length, 1); + assert.equal(details.samples[0].label, "center"); + assert.equal(details.samples[0].hex, "#785028"); + assert.equal(details.samples[0].patch.meanHex, "#785028"); + assert.equal(details.input.patchSize, 3); + }); +}); + +test("vp crop --json accepts the original tool input shape", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "from-json.png"); + await createFixture(image); + + const inputPath = join(dir, "input.json"); + await writeFile(inputPath, JSON.stringify({ + imagePath: image, + box: [10, 20, 60, 80], + coordinateSpace: "pixel", + outputPath: out, + })); + + const result = await runCli(["crop", "--json", inputPath]); + assert.equal(result.code, 0, result.stderr); + assert.deepEqual(await imageSize(out), { width: 50, height: 60 }); + }); +}); + +test("vp crop defaults to pixel coordinates", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "default-space.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "10,20,60,80", "--out", out]); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.equal(details.input.coordinateSpace, "pixel"); + assert.deepEqual(await imageSize(out), { width: 50, height: 60 }); + }); +}); + +test("vp crop --json keeps the original normalized-999 default", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "json-space.png"); + await createFixture(image); + + const inputPath = join(dir, "input.json"); + await writeFile(inputPath, JSON.stringify({ imagePath: image, box: [0, 0, 999, 999], outputPath: out })); + + const result = await runCli(["crop", "--json", inputPath]); + assert.equal(result.code, 0, result.stderr); + assert.equal(JSON.parse(result.stdout).input.coordinateSpace, "normalized-999"); + assert.deepEqual(await imageSize(out), { width: 100, height: 80 }); + }); +}); + +test("generated artifacts default to the working directory, not the source directory", async () => { + await withTempDir(async (dir) => { + const sourceDir = join(dir, "assets"); + await mkdir(sourceDir); + const image = join(sourceDir, "scene.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "0,0,40,40"], { cwd: dir }); + assert.equal(result.code, 0, result.stderr); + + const details = JSON.parse(result.stdout); + assert.ok(!details.outputPath.includes("assets"), `expected artifact outside assets/: ${details.outputPath}`); + const files = await readdir(dir); + assert.ok(files.some((file) => file.startsWith("scene.crop-")), files.join(", ")); + }); +}); + +test("a one-line summary is printed to stderr unless --quiet", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "sum.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "10,20,60,80", "--out", out]); + assert.equal(result.code, 0, result.stderr); + assert.match(result.stderr, /cropped → .*sum\.png \(50×60px\)/); + assert.doesNotMatch(result.stdout, /cropped →/); + + const quiet = await runCli(["crop", image, "--box", "10,20,60,80", "--out", join(dir, "quiet.png"), "--quiet"]); + assert.equal(quiet.code, 0, quiet.stderr); + assert.equal(quiet.stderr.trim(), ""); + }); +}); + +test("vp crop rejects repeated --box with a crop-multi hint", async () => { + const result = await runCli(["crop", "x.png", "--box", "0,0,1,1", "--box", "2,2,3,3"]); + assert.equal(result.code, 2); + assert.match(result.stderr, /crop-multi/); +}); + +test("vp point requires --radius or --size up front", async () => { + const missing = await runCli(["point", "x.png", "--point", "5,5"]); + assert.equal(missing.code, 2); + assert.match(missing.stderr, /--radius or --size/); + + const both = await runCli(["point", "x.png", "--point", "5,5", "--radius", "3", "--size", "4x4"]); + assert.equal(both.code, 2); + assert.match(both.stderr, /mutually exclusive/); +}); + +test("--json payloads are validated: bad enums and missing keys are rejected", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const badEnum = join(dir, "bad-enum.json"); + await writeFile(badEnum, JSON.stringify({ imagePath: image, box: [0, 0, 10, 10], coordinateSpace: "bogus" })); + const enumResult = await runCli(["crop", "--json", badEnum]); + assert.equal(enumResult.code, 2); + assert.match(enumResult.stderr, /"coordinateSpace" must be one of: normalized-999, pixel/); + + const noImage = join(dir, "no-image.json"); + await writeFile(noImage, JSON.stringify({ image: image, box: [0, 0, 10, 10] })); + const imageResult = await runCli(["crop", "--json", noImage]); + assert.equal(imageResult.code, 2); + assert.match(imageResult.stderr, /"imagePath"/); + + const noRadius = join(dir, "no-radius.json"); + await writeFile(noRadius, JSON.stringify({ imagePath: image, point: [5, 5] })); + const radiusResult = await runCli(["point", "--json", noRadius]); + assert.equal(radiusResult.code, 2); + assert.match(radiusResult.stderr, /"radius" or "size"/); + + const missingFile = await runCli(["crop", "--json", join(dir, "nope.json")]); + assert.equal(missingFile.code, 2); + assert.match(missingFile.stderr, /--json file not found/); + }); +}); + +test("JSON mode rejects unknown top-level and nested properties", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const topLevel = join(dir, "top-level.json"); + await writeFile(topLevel, JSON.stringify({ imagePath: image, box: [0, 0, 10, 10], unexpected: true })); + const topLevelResult = await runCli(["crop", "--json", topLevel]); + assert.equal(topLevelResult.code, 2, topLevelResult.stderr); + assert.match(topLevelResult.stderr, /unknown property "unexpected"/); + + const nested = join(dir, "nested.json"); + await writeFile(nested, JSON.stringify({ + imagePath: image, + outputDir: dir, + boxes: [{ box: [0, 0, 10, 10], unexpected: true }], + })); + const nestedResult = await runCli(["crop-multi", "--json", nested]); + assert.equal(nestedResult.code, 2, nestedResult.stderr); + assert.match(nestedResult.stderr, /boxes\[0\].*unknown property "unexpected"/); + }); +}); + +test("JSON mode rejects invalid optional-property types before runtime", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const cases = [ + { + command: "crop", + name: "string-clamp", + payload: { imagePath: image, box: [-5, -5, 10, 10], clamp: "false", outputPath: join(dir, "clamp.png") }, + message: /"clamp" must be a boolean/, + }, + { + command: "crop-multi", + name: "numeric-label", + payload: { imagePath: image, boxes: [{ box: [0, 0, 10, 10], label: 42 }], outputDir: dir }, + message: /boxes\[0\]\.label.*string/, + }, + { + command: "point", + name: "string-size", + payload: { imagePath: image, point: [5, 5], size: { width: "10", height: 10 }, outputPath: join(dir, "point.png") }, + message: /size\.width.*number/, + }, + ] as const; + + for (const item of cases) { + const inputPath = join(dir, `${item.name}.json`); + await writeFile(inputPath, JSON.stringify(item.payload)); + const result = await runCli([item.command, "--json", inputPath]); + assert.equal(result.code, 2, `${item.name}: ${result.stderr}`); + assert.match(result.stderr, item.message); + } + }); +}); + +test("JSON mode rejects non-finite numbers before runtime", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + const inputPath = join(dir, "infinite-radius.json"); + await writeFile(inputPath, `{"imagePath":${JSON.stringify(image)},"point":[5,5],"radius":1e400}`); + + const result = await runCli(["point", "--json", inputPath]); + assert.equal(result.code, 2, result.stderr); + assert.match(result.stderr, /"radius" must be a finite positive number/); + }); +}); + +test("JSON mode rejects command-inapplicable properties", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + const inputPath = join(dir, "colors-padding.json"); + await writeFile(inputPath, JSON.stringify({ + imagePath: image, + points: [{ point: [5, 5] }], + padding: 2, + })); + + const result = await runCli(["colors", "--json", inputPath]); + assert.equal(result.code, 2, result.stderr); + assert.match(result.stderr, /unknown property "padding"/); + }); +}); + +test("colors rejects command-inapplicable flags in flag and JSON modes", async () => { + const padding = await runCli(["colors", "x.png", "--point", "1,1", "--padding", "2"]); + assert.equal(padding.code, 2, padding.stderr); + assert.match(padding.stderr, /--padding does not apply/); + + const clamp = await runCli(["colors", "x.png", "--point", "1,1", "--no-clamp"]); + assert.equal(clamp.code, 2, clamp.stderr); + assert.match(clamp.stderr, /--no-clamp does not apply/); + + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + const inputPath = join(dir, "colors.json"); + await writeFile(inputPath, JSON.stringify({ imagePath: image, coordinateSpace: "pixel", points: [{ point: [1, 1] }] })); + + for (const flags of [["--padding", "2"], ["--no-clamp"], ["--box-order", "ltrb"]]) { + const result = await runCli(["colors", "--json", inputPath, ...flags]); + assert.equal(result.code, 2, `${flags.join(" ")}: ${result.stderr}`); + assert.match(result.stderr, /does not apply/); + } + }); +}); + +test("annotate accepts Sharp CSS colors and rejects malformed numeric syntax", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const hslOut = join(dir, "hsl.png"); + const modernOut = join(dir, "modern.png"); + await createFixture(image); + + for (const invalidColor of ["notacolor", "rgb(0x10,0,0)"]) { + const invalid = await runCli(["annotate", image, "--box", `x:10,10,50,50:${invalidColor}`]); + assert.equal(invalid.code, 2, invalid.stderr); + assert.match(invalid.stderr, /invalid --box color/); + } + + const bareHex = await runCli(["annotate", image, "--box", "x:10,10,50,50:ff0000"]); + assert.equal(bareHex.code, 2); + assert.match(bareHex.stderr, /did you mean "#ff0000"\?/); + + const hsl = await runCli(["annotate", image, "--box", "x:10,10,50,50:hsl(0, 100%, 50%)", "--out", hslOut]); + assert.equal(hsl.code, 0, hsl.stderr); + + const modernInput = join(dir, "modern.json"); + await writeFile(modernInput, JSON.stringify({ + imagePath: image, + coordinateSpace: "pixel", + outputPath: modernOut, + boxes: [{ box: [10, 10, 50, 50], color: "rgb(255 0 0 / 50%)" }], + })); + const modern = await runCli(["annotate", "--json", modernInput]); + assert.equal(modern.code, 0, modern.stderr); + + const malformedInput = join(dir, "malformed.json"); + await writeFile(malformedInput, JSON.stringify({ + imagePath: image, + coordinateSpace: "pixel", + outputPath: join(dir, "malformed.png"), + boxes: [{ box: [10, 10, 50, 50], color: "rgb(0x10,0,0)" }], + })); + const malformed = await runCli(["annotate", "--json", malformedInput]); + assert.equal(malformed.code, 2, malformed.stderr); + assert.match(malformed.stderr, /not a valid CSS color/); + + for (const out of [hslOut, modernOut]) { + const raw = await sharp(out).ensureAlpha().raw().toBuffer({ resolveWithObject: true }); + const offset = (10 * raw.info.width + 30) * 4; + assert.ok(raw.data[offset] > 100 && raw.data[offset + 1] < 100, `expected red stroke in ${out}`); + } + }); +}); + +test("--quiet suppresses warning-producing stderr", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli([ + "crop", + image, + "--box", + "0,0,10,10", + "--out", + join(dir, "quiet.jpg"), + "--quiet", + ]); + assert.equal(result.code, 0, result.stderr); + assert.equal(result.stderr, ""); + }); +}); + +test("colors flags out-of-bounds points as clamped and warns", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["colors", image, "--point", "500,500"]); + assert.equal(result.code, 0, result.stderr); + const details = JSON.parse(result.stdout); + assert.equal(details.samples[0].clamped, true); + assert.deepEqual(details.samples[0].resolvedPixelPoint, { x: 99, y: 79 }); + assert.match(result.stderr, /warning: point #1 \[500, 500\] is outside the image/); + + const inside = await runCli(["colors", image, "--point", "10,10"]); + assert.equal(JSON.parse(inside.stdout).samples[0].clamped, false); + }); +}); + +test("flag validation errors exit with code 2, not 1", async () => { + const padding = await runCli(["crop", "x.png", "--box", "0,0,10,10", "--padding=-5"]); + assert.equal(padding.code, 2); + assert.match(padding.stderr, /--padding must be zero or a positive/); + + const patch = await runCli(["colors", "x.png", "--point", "1,1", "--patch", "0"]); + assert.equal(patch.code, 2); + assert.match(patch.stderr, /--patch must be a positive integer/); + + const radius = await runCli(["point", "x.png", "--point", "1,1", "--radius", "0"]); + assert.equal(radius.code, 2); + assert.match(radius.stderr, /--radius must be a positive number/); + + for (const args of [["--size", "0x10"], ["--size=-1x10"]]) { + const size = await runCli(["point", "x.png", "--point", "1,1", ...args]); + assert.equal(size.code, 2, size.stderr); + assert.match(size.stderr, /--size width and height must be positive numbers/); + } +}); + +test("vp help with a typo suggests the right command", async () => { + const result = await runCli(["help", "crp"]); + assert.equal(result.code, 2); + assert.match(result.stderr, /did you mean "vp help crop"\?/); +}); + +test("coordinates with spaces after commas are accepted", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "spaced.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "10, 20, 60, 80", "--out", out]); + assert.equal(result.code, 0, result.stderr); + assert.deepEqual(await imageSize(out), { width: 50, height: 60 }); + }); +}); + +test("non-png --out extensions warn", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "0,0,10,10", "--out", join(dir, "crop.jpg")]); + assert.equal(result.code, 0, result.stderr); + assert.match(result.stderr, /warning: output is always PNG data/); + }); +}); + +test("EXIF-oriented images trigger a warning", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "rotated.jpg"); + await sharp({ create: { width: 100, height: 80, channels: 3, background: { r: 10, g: 20, b: 30 } } }) + .jpeg().withMetadata({ orientation: 6 }).toFile(image); + + const result = await runCli(["crop", image, "--box", "0,0,50,40", "--out", join(dir, "out.png")]); + assert.equal(result.code, 0, result.stderr); + assert.match(result.stderr, /warning: image has EXIF orientation 6/); + }); +}); + +test("--json files with a UTF-8 BOM are accepted", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "bom.png"); + await createFixture(image); + + const inputPath = join(dir, "input.json"); + await writeFile(inputPath, String.fromCharCode(0xfeff) + JSON.stringify({ imagePath: image, box: [0, 0, 10, 10], coordinateSpace: "pixel", outputPath: out })); + + const result = await runCli(["crop", "--json", inputPath]); + assert.equal(result.code, 0, result.stderr); + assert.deepEqual(await imageSize(out), { width: 10, height: 10 }); + }); +}); + +test("usage errors exit with code 2", async () => { + const missingBox = await runCli(["crop", "whatever.png"]); + assert.equal(missingBox.code, 2); + assert.match(missingBox.stderr, /--box/); + + const unknownCommand = await runCli(["frobnicate"]); + assert.equal(unknownCommand.code, 2); + assert.match(unknownCommand.stderr, /unknown command/); + + const badSpace = await runCli(["crop", "x.png", "--box", "0,0,1,1", "--space", "bogus"]); + assert.equal(badSpace.code, 2); + assert.match(badSpace.stderr, /--space/); +}); + +test("fully out-of-bounds boxes explain themselves and hint at --space 999", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "500,500,900,900"]); + assert.equal(result.code, 1); + assert.match(result.stderr, /completely outside the 100x80 image/); + assert.match(result.stderr, /--space 999/); + }); +}); + +test("unknown options and commands get did-you-mean suggestions", async () => { + const option = await runCli(["crop", "x.png", "--box", "0,0,1,1", "--boxorder", "lbrt"]); + assert.equal(option.code, 2); + assert.match(option.stderr, /did you mean '--box-order'\?/); + + const command = await runCli(["color"]); + assert.equal(command.code, 2); + assert.match(command.stderr, /did you mean "colors"\?/); +}); + +test("missing arguments are aggregated with a usage line and help hint", async () => { + const result = await runCli(["crop"]); + assert.equal(result.code, 2); + assert.match(result.stderr, /missing and --box/); + assert.match(result.stderr, /Usage: vp crop/); + assert.match(result.stderr, /run "vp crop --help" for details/); +}); + +test("vp help routes to the command help", async () => { + const result = await runCli(["help", "crop"]); + assert.equal(result.code, 0); + assert.match(result.stdout, /^Usage: vp crop/); +}); + +test("severe clamping produces a warning", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["crop", image, "--box", "0,0,2000,2000", "--out", join(dir, "clamped.png")]); + assert.equal(result.code, 0, result.stderr); + assert.match(result.stderr, /warning: (over )?\d+% of the requested box was outside the image/); + }); +}); + +test("even --patch values warn about rounding", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + await createFixture(image); + + const result = await runCli(["colors", image, "--point", "10,10", "--patch", "4"]); + assert.equal(result.code, 0, result.stderr); + assert.match(result.stderr, /--patch 4 is even; using 5/); + assert.equal(JSON.parse(result.stdout).input.patchSize, 5); + }); +}); + +test("overwriting an explicit --out warns", async () => { + await withTempDir(async (dir) => { + const image = join(dir, "scene.png"); + const out = join(dir, "same.png"); + await createFixture(image); + + const first = await runCli(["crop", image, "--box", "0,0,10,10", "--out", out]); + assert.equal(first.code, 0, first.stderr); + assert.doesNotMatch(first.stderr, /overwriting/); + + const second = await runCli(["crop", image, "--box", "0,0,10,10", "--out", out]); + assert.equal(second.code, 0, second.stderr); + assert.match(second.stderr, /warning: overwriting existing/); + }); +}); + +test("misspelled image paths suggest a nearby file", async () => { + await withTempDir(async (dir) => { + await createFixture(join(dir, "scene-v2.png")); + + const result = await runCli(["crop", join(dir, "scene-v2.jpg"), "--box", "0,0,10,10"]); + assert.equal(result.code, 1); + assert.match(result.stderr, /did you mean ".*scene-v2\.png"\?/); + }); +}); + +test("runtime errors exit with code 1", async () => { + const result = await runCli(["crop", "does-not-exist.png", "--box", "0,0,10,10", "--space", "pixel"]); + assert.equal(result.code, 1); + assert.match(result.stderr, /missing or cannot be read/); +}); diff --git a/tests/crop.test.ts b/tests/crop.test.ts index 7e1d443..97ac6d8 100644 --- a/tests/crop.test.ts +++ b/tests/crop.test.ts @@ -7,7 +7,7 @@ import sharp from "sharp"; import { cropBoundingBox, resolvePixelBoxForTest } from "../src/crop.ts"; async function withTempDir(fn: (dir: string) => Promise): Promise { - const dir = await mkdtemp(join(tmpdir(), "pi-visual-primitives-test-")); + const dir = await mkdtemp(join(tmpdir(), "visual-primitives-test-")); try { await fn(dir); } finally { diff --git a/tests/extension.test.ts b/tests/extension.test.ts deleted file mode 100644 index 571a949..0000000 --- a/tests/extension.test.ts +++ /dev/null @@ -1,225 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { registerVisualPrimitives } from "../src/extension.ts"; - -interface RegisteredTool { - name: string; - label: string; - description: string; - promptSnippet?: string; - promptGuidelines?: string[]; - parameters: unknown; - execute: ( - toolCallId: string, - params: any, - signal?: AbortSignal, - onUpdate?: unknown, - ctx?: { cwd?: string }, - ) => Promise<{ content: Array<{ type: "text"; text: string }>; details?: unknown }>; -} - -function registeredTools(): RegisteredTool[] { - const tools: RegisteredTool[] = []; - const pi = { - registerTool(tool: RegisteredTool) { - tools.push(tool); - }, - }; - - registerVisualPrimitives(pi, { pluginDir: "/plugin" }); - return tools; -} - -test("registerVisualPrimitives registers crop_bounding_box", () => { - const tools = registeredTools(); - const tool = tools.find((candidate) => candidate.name === "crop_bounding_box"); - - assert.ok(tool); - assert.equal(tool.label, "Crop Bounding Box"); - assert.match(tool.description, /visual-primitive normalized 0-999/); - assert.match(tool.promptSnippet ?? "", /visually relevant region/); - assert.ok(tool.promptGuidelines?.some((line) => line.includes("bottom-left"))); - assert.deepEqual(tool.parameters, { - type: "object", - additionalProperties: false, - required: ["imagePath", "box"], - properties: { - imagePath: { - type: "string", - description: "Source image path. Relative paths resolve against the current Pi working directory. A leading @ is ignored.", - }, - box: { - type: "array", - minItems: 4, - maxItems: 4, - items: { type: "number" }, - description: "Bounding box coordinates. Defaults to normalized 0-999 [left, top, right, bottom].", - }, - coordinateSpace: { - type: "string", - enum: ["normalized-999", "pixel"], - description: "Coordinate space for box values. Defaults to normalized-999, matching visual-primitives paper examples.", - }, - origin: { - type: "string", - enum: ["top-left", "bottom-left"], - description: "Coordinate origin. top-left means y grows downward; bottom-left means y grows upward. Defaults to top-left.", - }, - boxOrder: { - type: "string", - enum: ["left-top-right-bottom", "left-bottom-right-top"], - description: "Input box order. Defaults to left-top-right-bottom. Use left-bottom-right-top for bottom-left style boxes.", - }, - outputPath: { - type: "string", - description: "Optional output PNG path. Relative paths resolve against the current Pi working directory.", - }, - padding: { - type: "number", - description: "Pixel padding to add around the resolved rectangle before clamp or bounds validation. Defaults to 0.", - }, - clamp: { - type: "boolean", - description: "When true, clip out-of-bounds rectangles to image bounds. When false, out-of-bounds rectangles fail. Defaults to true.", - }, - }, - }); -}); - -test("registerVisualPrimitives registers visual primitive helper tools", () => { - const tools = registeredTools(); - - assert.deepEqual(tools.map((tool) => tool.name), [ - "crop_bounding_box", - "crop_multiple_bounding_boxes", - "annotate_bounding_boxes", - "crop_around_point", - "sample_colors", - ]); - assert.match(tools[1].description, /multiple regions/); - assert.match(tools[2].description, /annotated preview/); - assert.match(tools[3].description, /point of interest/); - assert.match(tools[4].description, /exact colors/); -}); - -test("registered tools guide proactive visual evidence workflows", () => { - const tools = registeredTools(); - const crop = tools.find((candidate) => candidate.name === "crop_bounding_box"); - const multi = tools.find((candidate) => candidate.name === "crop_multiple_bounding_boxes"); - const annotate = tools.find((candidate) => candidate.name === "annotate_bounding_boxes"); - const point = tools.find((candidate) => candidate.name === "crop_around_point"); - const colors = tools.find((candidate) => candidate.name === "sample_colors"); - - assert.ok(crop); - assert.ok(multi); - assert.ok(annotate); - assert.ok(point); - assert.ok(colors); - - assert.match(`${crop.description} ${crop.promptSnippet} ${crop.promptGuidelines?.join(" ")}`, /screenshot/i); - assert.match(`${crop.description} ${crop.promptSnippet} ${crop.promptGuidelines?.join(" ")}`, /UI reproduction|visual QA/i); - assert.match(`${crop.description} ${crop.promptSnippet} ${crop.promptGuidelines?.join(" ")}`, /inspect the crop/i); - - assert.match(`${multi.description} ${multi.promptSnippet} ${multi.promptGuidelines?.join(" ")}`, /complex image|complex screenshot|UI/i); - assert.match(`${multi.description} ${multi.promptSnippet} ${multi.promptGuidelines?.join(" ")}`, /header.*card.*sidebar|semantic region/i); - - assert.match(`${annotate.description} ${annotate.promptSnippet} ${annotate.promptGuidelines?.join(" ")}`, /region assumptions/i); - assert.match(`${annotate.description} ${annotate.promptSnippet} ${annotate.promptGuidelines?.join(" ")}`, /frontend reproduction|visual comparison/i); - assert.match(`${annotate.description} ${annotate.promptSnippet} ${annotate.promptGuidelines?.join(" ")}`, /does not detect/i); - - assert.match(`${point.description} ${point.promptSnippet} ${point.promptGuidelines?.join(" ")}`, /point of interest/i); - assert.match(`${point.description} ${point.promptSnippet} ${point.promptGuidelines?.join(" ")}`, /alignment issue|overlap/i); - - assert.match(`${colors.description} ${colors.promptSnippet} ${colors.promptGuidelines?.join(" ")}`, /CSS-level color precision/i); - assert.match(`${colors.description} ${colors.promptSnippet} ${colors.promptGuidelines?.join(" ")}`, /provided points/i); -}); - -test("crop_bounding_box execution returns crop result details", async () => { - const tool = registeredTools().find((candidate) => candidate.name === "crop_bounding_box"); - assert.ok(tool); - - await assert.rejects( - () => tool.execute("call-1", { - imagePath: "missing.png", - box: [0, 0, 10, 10], - coordinateSpace: "pixel", - }, undefined, undefined, { cwd: "/tmp" }), - /does not exist|cannot be read|Input file is missing/, - ); -}); - -test("sample_colors execution returns exact color details", async () => { - const { mkdtemp, rm } = await import("node:fs/promises"); - const { join } = await import("node:path"); - const { tmpdir } = await import("node:os"); - const sharp = (await import("sharp")).default; - - const dir = await mkdtemp(join(tmpdir(), "pi-visual-primitives-ext-colors-test-")); - try { - const source = join(dir, "source.png"); - const data = Buffer.from([ - 255, 0, 0, 255, - 0, 255, 0, 255, - 0, 0, 255, 255, - 255, 255, 255, 255, - ]); - await sharp(data, { raw: { width: 2, height: 2, channels: 4 } }).png().toFile(source); - - const tool = registeredTools().find((candidate) => candidate.name === "sample_colors"); - assert.ok(tool); - const result = await tool.execute("call-colors", { - imagePath: source, - points: [{ label: "red", point: [0, 0] }], - coordinateSpace: "pixel", - }, undefined, undefined, { cwd: dir }); - - assert.match(result.content[0].text, /Sampled 1 color/); - assert.match(result.content[0].text, /red: #ff0000/); - assert.equal((result.details as any).samples[0].hex, "#ff0000"); - } finally { - await rm(dir, { recursive: true, force: true }); - } -}); - -test("crop_bounding_box result text includes output and resolved pixel box", async () => { - const { mkdtemp, rm } = await import("node:fs/promises"); - const { join } = await import("node:path"); - const { tmpdir } = await import("node:os"); - const sharp = (await import("sharp")).default; - - const dir = await mkdtemp(join(tmpdir(), "pi-visual-primitives-ext-test-")); - try { - const source = join(dir, "source.png"); - const output = join(dir, "crop.png"); - await sharp({ - create: { - width: 20, - height: 20, - channels: 4, - background: { r: 0, g: 0, b: 0, alpha: 1 }, - }, - }).png().toFile(source); - - const tool = registeredTools().find((candidate) => candidate.name === "crop_bounding_box"); - assert.ok(tool); - const result = await tool.execute("call-2", { - imagePath: source, - outputPath: output, - box: [1, 2, 11, 12], - coordinateSpace: "pixel", - }, undefined, undefined, { cwd: dir }); - - assert.match(result.content[0].text, /Cropped bounding box to/); - assert.match(result.content[0].text, /left=1, top=2, width=10, height=10/); - assert.deepEqual((result.details as any).resolvedPixelBox, { - left: 1, - top: 2, - right: 11, - bottom: 12, - width: 10, - height: 10, - }); - } finally { - await rm(dir, { recursive: true, force: true }); - } -}); diff --git a/tests/masked-oracle-diff.test.ts b/tests/masked-oracle-diff.test.ts index df1646f..4c6d742 100644 --- a/tests/masked-oracle-diff.test.ts +++ b/tests/masked-oracle-diff.test.ts @@ -1,10 +1,24 @@ import test from "node:test"; import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; import { access, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { tmpdir } from "node:os"; +import { promisify } from "node:util"; import sharp from "sharp"; +const execFileAsync = promisify(execFile); +const packageRoot = new URL("..", import.meta.url); +const packageRootPath = decodeURIComponent(packageRoot.pathname).replace(/^\/(?:([A-Za-z]:))/, "$1"); +const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm"; + +async function runNpm(args: string[]): Promise<{ stdout: string; stderr: string }> { + if (process.platform === "win32") { + return execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", npmCommand, ...args], { cwd: packageRootPath }); + } + return execFileAsync(npmCommand, args, { cwd: packageRootPath }); +} + async function withTempDir(fn: (dir: string) => Promise): Promise { const dir = await mkdtemp(join(tmpdir(), "masked-oracle-diff-test-")); try { @@ -102,7 +116,7 @@ test("masked-oracle-diff writes artifacts and excludes masked pixels from scorin }, }, null, 2)); - const { runMaskedOracleDiff } = await import("../scripts/masked-oracle-diff.ts"); + const { runMaskedOracleDiff } = await import("../skills/frontend-replication/scripts/masked-oracle-diff.ts"); const result = await runMaskedOracleDiff({ manifestPath: manifest }); assert.equal(result.summaryPath, join(outputDir, "summary.json")); @@ -179,7 +193,7 @@ test("masked-oracle-diff handles large same-size images without spread overflow" }, }, null, 2)); - const { runMaskedOracleDiff } = await import("../scripts/masked-oracle-diff.ts"); + const { runMaskedOracleDiff } = await import("../skills/frontend-replication/scripts/masked-oracle-diff.ts"); await runMaskedOracleDiff({ manifestPath: manifest }); const summary = await readJson(join(outputDir, "summary.json")); @@ -216,7 +230,7 @@ test("masked-oracle-diff filters tiny noise components while preserving larger l }, }, null, 2)); - const { runMaskedOracleDiff } = await import("../scripts/masked-oracle-diff.ts"); + const { runMaskedOracleDiff } = await import("../skills/frontend-replication/scripts/masked-oracle-diff.ts"); await runMaskedOracleDiff({ manifestPath: manifest }); const components = await readJson(join(outputDir, "components.json")); @@ -234,6 +248,33 @@ test("masked-oracle-diff filters tiny noise components while preserving larger l }); }); +test("npm oracle:diff script resolves the relocated helper", async () => { + await withTempDir(async (dir) => { + const oracle = join(dir, "oracle.png"); + const rendered = join(dir, "rendered.png"); + const manifest = join(dir, "manifest.json"); + const outputDir = join(dir, "diff-output"); + + await writeFixturePng(oracle, 12, 12); + await writeFixturePng(rendered, 12, 12, (buffer) => { + fillRect(buffer, 12, 3, 3, 7, 7, [0, 0, 0, 255]); + }); + await writeFile(manifest, JSON.stringify({ + oracleImage: oracle, + renderedImage: rendered, + outputDir, + coordinateSpace: "pixel", + exclusionBoxes: [], + }, null, 2)); + + const { stdout, stderr } = await runNpm(["run", "oracle:diff", "--", "--manifest", manifest]); + assert.equal(stderr, ""); + assert.match(stdout, /summary\.json/); + assert.equal(await fileExists(join(outputDir, "summary.json")), true); + assert.equal(await fileExists(join(outputDir, "VERDICT.md")), true); + }); +}); + test("masked-oracle-diff writes blocked summary and verdict for dimension mismatch", async () => { await withTempDir(async (dir) => { const oracle = join(dir, "oracle.png"); @@ -251,7 +292,7 @@ test("masked-oracle-diff writes blocked summary and verdict for dimension mismat exclusionBoxes: [], }, null, 2)); - const { runMaskedOracleDiff } = await import("../scripts/masked-oracle-diff.ts"); + const { runMaskedOracleDiff } = await import("../skills/frontend-replication/scripts/masked-oracle-diff.ts"); await assert.rejects( () => runMaskedOracleDiff({ manifestPath: manifest }), /identical dimensions/, diff --git a/tests/package-runtime.test.ts b/tests/package-runtime.test.ts new file mode 100644 index 0000000..b4681d4 --- /dev/null +++ b/tests/package-runtime.test.ts @@ -0,0 +1,128 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { access, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { pathToFileURL } from "node:url"; +import { promisify } from "node:util"; + +const execFileAsync = promisify(execFile); +const packageRoot = new URL("..", import.meta.url); +const packageRootPath = decodeURIComponent(packageRoot.pathname).replace(/^\/(?:([A-Za-z]:))/, "$1"); +const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm"; + +async function runNpm(args: string[], cwd: string): Promise<{ stdout: string; stderr: string }> { + if (process.platform === "win32") { + return execFileAsync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", npmCommand, ...args], { cwd }); + } + return execFileAsync(npmCommand, args, { cwd }); +} + +async function withTempDir(fn: (dir: string) => Promise): Promise { + const dir = await mkdtemp(join(tmpdir(), "visual-primitives-package-runtime-")); + try { + await fn(dir); + } finally { + await rm(dir, { recursive: true, force: true }); + } +} + +async function runInstalledAlias(aliasPath: string): Promise<{ code: number; stdout: string; stderr: string }> { + try { + const command = process.platform === "win32" ? (process.env.ComSpec ?? "cmd.exe") : aliasPath; + const args = process.platform === "win32" ? ["/d", "/s", "/c", aliasPath, "--version"] : ["--version"]; + const { stdout, stderr } = await execFileAsync(command, args); + return { code: 0, stdout, stderr }; + } catch (error) { + const failed = error as { code?: number; stdout?: string; stderr?: string }; + return { code: failed.code ?? 1, stdout: failed.stdout ?? "", stderr: failed.stderr ?? "" }; + } +} + +async function assertInstalledAliases(installDir: string): Promise { + const packageJson = JSON.parse(await readFile(new URL("package.json", packageRoot), "utf8")); + for (const alias of ["vp", "visual-primitives"]) { + const executable = join(installDir, "node_modules", ".bin", process.platform === "win32" ? `${alias}.cmd` : alias); + const result = await runInstalledAlias(executable); + assert.equal(result.code, 0, `${alias}: ${result.stderr}`); + assert.equal(result.stdout.trim(), packageJson.version); + } +} + +async function initializeInstallDir(installDir: string): Promise { + await mkdir(installDir); + await writeFile(join(installDir, "package.json"), JSON.stringify({ private: true })); +} + +async function assertInstalledSkillResources(installDir: string): Promise { + const packageDir = join(installDir, "node_modules", "@mapleluvr", "visual-primitives"); + const launcher = join(packageDir, "skills", "_shared", "run-vp.mjs"); + const { stdout, stderr } = await execFileAsync(process.execPath, [launcher, "--help"], { + cwd: installDir, + env: { ...process.env, PATH: "" }, + }); + assert.equal(stderr, ""); + for (const command of ["crop", "crop-multi", "annotate", "point", "colors"]) { + assert.match(stdout, new RegExp(`\\b${command.replace("-", "\\-")}\\b`)); + } + + for (const skill of [ + "finalizing-replication", + "frontend-replication", + "inline-replication", + "refining-with-feedback", + "subagent-driven-replication", + "using-visual-primitives", + ]) { + await access(join(packageDir, "skills", skill, "SKILL.md")); + } + await access(join(packageDir, "skills", "frontend-replication", "scripts", "masked-oracle-diff.ts")); + await access(join(packageDir, "skills", "frontend-replication", "scripts", "masked-oracle-diff.js")); +} + +test("packed package installs runnable vp and visual-primitives aliases", async () => { + await withTempDir(async (dir) => { + const packDir = join(dir, "pack"); + const installDir = join(dir, "install"); + await mkdir(packDir); + await initializeInstallDir(installDir); + + const { stdout: packStdout } = await runNpm([ + "pack", + "--json", + "--pack-destination", + packDir, + ], packageRootPath); + const [packResult] = JSON.parse(packStdout) as Array<{ filename: string }>; + const tarballPath = join(packDir, packResult.filename); + + await runNpm([ + "install", + "--no-audit", + "--no-fund", + tarballPath, + ], installDir); + + await assertInstalledAliases(installDir); + await assertInstalledSkillResources(installDir); + }); +}); + +test("pinned Git package installs runnable vp and visual-primitives aliases", async () => { + await withTempDir(async (dir) => { + const installDir = join(dir, "install"); + await initializeInstallDir(installDir); + + const { stdout: commit } = await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: packageRootPath }); + const gitUrl = `git+${pathToFileURL(packageRootPath).href}#${commit.trim()}`; + await runNpm([ + "install", + "--no-audit", + "--no-fund", + gitUrl, + ], installDir); + + await assertInstalledAliases(installDir); + }); +}); diff --git a/tests/package.test.ts b/tests/package.test.ts index 5042c69..36f7337 100644 --- a/tests/package.test.ts +++ b/tests/package.test.ts @@ -1,513 +1,158 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { readFile } from "node:fs/promises"; +import { execFile } from "node:child_process"; +import { access, readdir, readFile } from "node:fs/promises"; import { join } from "node:path"; +import { promisify } from "node:util"; +const execFileAsync = promisify(execFile); const packageRoot = new URL("..", import.meta.url); +const packageRootPath = decodeURIComponent(packageRoot.pathname).replace(/^\/(?:([A-Za-z]:))/, "$1"); +const expectedSkills = [ + "finalizing-replication", + "frontend-replication", + "inline-replication", + "refining-with-feedback", + "subagent-driven-replication", + "using-visual-primitives", +]; +const legacyToolNames = [ + "annotate_bounding_boxes", + "crop_around_point", + "crop_bounding_box", + "crop_multiple_bounding_boxes", + "sample_colors", +]; async function readText(relativePath: string): Promise { return readFile(new URL(relativePath, packageRoot), "utf8"); } -test("package exposes the visual-primitives Skill directory", async () => { - const packageJson = JSON.parse(await readText("package.json")); +function normalizeLines(value: string): string { + return value.replace(/\r\n?/g, "\n"); +} - assert.deepEqual(packageJson.pi?.skills, ["./skills"]); -}); +async function pathExists(relativePath: string): Promise { + try { + await access(new URL(relativePath, packageRoot)); + return true; + } catch { + return false; + } +} -test("package exposes masked-oracle-diff CLI scripts", async () => { +test("Pi metadata exposes exactly the Skill Set and no extension", async () => { const packageJson = JSON.parse(await readText("package.json")); - assert.match(packageJson.scripts?.["oracle:diff"], /scripts\/masked-oracle-diff\.ts/); - assert.match(packageJson.scripts?.check, /scripts\/masked-oracle-diff\.ts/); -}); - -test("README documents the packaged visual-primitives Skill Set", async () => { - const readme = await readText("README.md"); - - assert.match(readme, /## Skill Set/); - assert.match(readme, /skills\/using-visual-primitives\/SKILL\.md/); - assert.match(readme, /skills\/frontend-replication\/SKILL\.md/); - assert.match(readme, /masked-oracle-diff/); - assert.match(readme, /npm run oracle:diff/); -}); - -test("README documents package installation so the Skill is loaded", async () => { - const readme = await readText("README.md"); - - assert.match(readme, /pi install \.\/pi-visual-primitives/); - assert.match(readme, /loads both the extension tool and the Skill/); -}); - -test("README links to a Chinese translation with matching core guidance", async () => { - const readme = await readText("README.md"); - const zhReadme = await readText("README.zh-CN.md"); - - assert.match(readme, /\[中文\]\(README\.zh-CN\.md\)/); - assert.match(zhReadme, /\[English\]\(README\.md\)/); - assert.match(zhReadme, /视觉证据/); - assert.match(zhReadme, /技能集/); - assert.match(zhReadme, /Worked Examples|完整示例|示例/); - assert.match(zhReadme, /docs\/visual-primitives\/examples\/pulse-side-by-side\.png/); - assert.match(zhReadme, /docs\/visual-primitives\/examples\/netease-side-by-side\.png/); - assert.match(zhReadme, /masked-oracle-diff/); - assert.match(zhReadme, /npm run oracle:diff/); - assert.match(zhReadme, /crop_bounding_box/); - assert.match(zhReadme, /sample_colors/); - assert.match(zhReadme, /用代码渲染所有可代码绘制区域/); - assert.match(zhReadme, /批准的排除区域可以用占位图或委托图像资产表示/); - assert.match(zhReadme, /让可代码绘制内容留在评分域/); - assert.doesNotMatch(zhReadme, /不要使用图像资产/); - assert.doesNotMatch(zhReadme, /永远不要排除/); -}); - -test("legacy visual-primitives Skill entry is retired", async () => { - await assert.rejects( - () => readText(join("skills", "visual-primitives", "SKILL.md")), - /ENOENT/, - ); -}); - -test("using-visual-primitives Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: using-visual-primitives\n/); - assert.match(skill, /\ndescription: Use when marking, comparing, aligning, analyzing, cropping, annotating, or inspecting images/ms); - assert.match(skill, /\n---\n/); -}); - -test("frontend-replication Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "frontend-replication", "SKILL.md")); - - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: frontend-replication\n/); - assert.match(skill, /\ndescription: Use when reproducing frontend webpages from AIGC oracle images, reference screenshots, rendered UI, and descriptions/ms); - assert.match(skill, /\n---\n/); -}); - -test("inline-replication Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "inline-replication", "SKILL.md")); - - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: inline-replication\n/); - assert.match(skill, /\ndescription: Use when one parent agent is executing frontend webpage replication from oracle images/ms); - assert.match(skill, /\n---\n/); + assert.deepEqual(packageJson.pi, { skills: ["./skills"] }); + assert.equal(packageJson.peerDependencies?.["@earendil-works/pi-coding-agent"], undefined); }); -test("subagent-driven-replication Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "subagent-driven-replication", "SKILL.md")); - - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: subagent-driven-replication\n/); - assert.match(skill, /\ndescription: Use when orchestrating subagents for frontend webpage replication from oracle images/ms); - assert.match(skill, /\n---\n/); -}); +test("all six Skills have portable discoverable frontmatter", async () => { + const skillRoot = new URL("skills/", packageRoot); + const entries = await readdir(skillRoot, { withFileTypes: true }); + const discovered: string[] = []; -test("refining-with-feedback Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "refining-with-feedback", "SKILL.md")); + for (const entry of entries) { + if (!entry.isDirectory() || entry.name === "_shared") continue; + const skillPath = `skills/${entry.name}/SKILL.md`; + if (!(await pathExists(skillPath))) continue; + const skill = normalizeLines(await readText(skillPath)); + assert.match(skill, /^---\n/); + assert.match(skill, new RegExp(`\\nname: ${entry.name}\\n`)); + assert.match(skill, /\ndescription: Use when .+\n/); + assert.match(skill, /\n---\n/); + discovered.push(entry.name); + } - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: refining-with-feedback\n/); - assert.match(skill, /\ndescription: Use when a frontend replication loop has a process verdict, failed inspection, masked diff evidence, or previous draft history/ms); - assert.match(skill, /\n---\n/); + assert.deepEqual(discovered.sort(), expectedSkills); }); -test("finalizing-replication Skill has valid discoverable frontmatter", async () => { - const skill = await readText(join("skills", "finalizing-replication", "SKILL.md")); +test("package-local launcher executes the packaged CLI without PATH lookup", async () => { + const launcher = join(packageRootPath, "skills", "_shared", "run-vp.mjs"); + const { stdout, stderr } = await execFileAsync(process.execPath, [launcher, "--help"], { + cwd: packageRootPath, + env: { ...process.env, PATH: "" }, + }); - assert.match(skill, /^---\n/); - assert.match(skill, /\nname: finalizing-replication\n/); - assert.match(skill, /\ndescription: Use when frontend replication verification is clean enough for final direct inspection, delivery review, or final failure routing/ms); - assert.match(skill, /\n---\n/); + assert.equal(stderr, ""); + for (const command of ["crop", "crop-multi", "annotate", "point", "colors"]) { + assert.match(stdout, new RegExp(`\\b${command.replace("-", "\\-")}\\b`)); + } }); -test("using-visual-primitives Skill owns visual evidence workflow safeguards", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); +test("using-visual-primitives teaches the five vp commands and package-local fallback", async () => { + const skill = normalizeLines(await readText("skills/using-visual-primitives/SKILL.md")); assert.match(skill, /visual evidence/i); - assert.match(skill, /User requirements take priority/i); - assert.match(skill, /Direct visual inspection takes priority/i); - assert.match(skill, /Think geometrics, write coordinates/i); - assert.match(skill, /annotate_bounding_boxes/); - assert.match(skill, /crop_multiple_bounding_boxes/); - assert.match(skill, /crop_around_point/); - assert.match(skill, /normalized-999/); - assert.match(skill, /pixel/); - assert.match(skill, /top-left/); - assert.match(skill, /left-top-right-bottom/); - assert.match(skill, /tools detect objects, OCR text, segment images, or infer UI elements automatically/i); -}); - -test("using-visual-primitives Skill documents core principles and general techniques", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /User requirements take priority/i); - assert.match(skill, /Direct visual inspection takes priority/i); - assert.match(skill, /Think geometrics, write coordinates/i); - assert.match(skill, /appearance -> coordinates -> appearance/i); - assert.match(skill, /specific local image content at specific positions/i); - assert.match(skill, /annotate_bounding_boxes/); - assert.match(skill, /crop_bounding_box/); - assert.match(skill, /crop_multiple_bounding_boxes/); - assert.match(skill, /crop_around_point/); - assert.match(skill, /marking images/i); - assert.match(skill, /comparing images/i); - assert.match(skill, /aligning images/i); - assert.match(skill, /analyzing images/i); - assert.match(skill, /resolvedPixelBox/i); - assert.match(skill, /width.*height.*area/is); - assert.match(skill, /normalized-999/); - assert.match(skill, /pixel/); - assert.match(skill, /directly inspect/i); -}); - -test("frontend-replication Skill documents oracle intake, workspace, and route selection", async () => { - const skill = await readText(join("skills", "frontend-replication", "SKILL.md")); - - assert.match(skill, /gateway skill/i); - assert.match(skill, /Oracle Intake/i); - assert.match(skill, /derive a working oracle description/i); - assert.match(skill, /Screenshots or reference images are sufficient to start Oracle Intake/i); - assert.match(skill, /using-visual-primitives/); - assert.match(skill, /oracle-manifest\.json/); - assert.match(skill, /docs\/visual-primitives\/runs\//); - assert.match(skill, /oracles\//); - assert.match(skill, /annots\//); - assert.match(skill, /cropped\//); - assert.match(skill, /rendered\//); - assert.match(skill, /diffs\//); - assert.match(skill, /drafts\//); - assert.match(skill, /verdict\//); - assert.match(skill, /scripts\//); - assert.match(skill, /final\//); - assert.match(skill, /inline-replication/); - assert.match(skill, /subagent-driven-replication/); - assert.match(skill, /refining-with-feedback/); - assert.match(skill, /finalizing-replication/); - assert.match(skill, /Drafts accumulate as new files/i); - assert.match(skill, /Use `verdict\/` only for process feedback/i); - assert.match(skill, /use `final\/` for delivery review/i); - assert.doesNotMatch(skill, /does not block the workflow/i); - assert.doesNotMatch(skill, /should not overwrite earlier drafts/i); - assert.doesNotMatch(skill, /Do not treat `verdict\/` as final delivery/i); -}); - -test("using-visual-primitives Skill avoids redundant negative definitions", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /standalone image proofreading/i); - assert.match(skill, /Use numeric differences to choose where to inspect/i); - assert.match(skill, /Alignment requires explicit coordinate evidence/i); - assert.doesNotMatch(skill, /even when no frontend replication workflow is involved/i); - assert.doesNotMatch(skill, /Do not let a script or metric overrule direct visual inspection/i); - assert.doesNotMatch(skill, /not just a visual guess/i); -}); - -test("inline-replication Skill documents the parent-agent replication loop", async () => { - const skill = await readText(join("skills", "inline-replication", "SKILL.md")); - - assert.match(skill, /frontend-replication/); - assert.match(skill, /using-visual-primitives/); - assert.match(skill, /Initial Draft/i); - assert.match(skill, /Code Execution/i); - assert.match(skill, /Verify/i); - assert.match(skill, /Feedback/i); - assert.match(skill, /finalizing-replication/); - assert.match(skill, /drafts\/initial-draft/i); - assert.match(skill, /rendered\//); - assert.match(skill, /diffs\//); - assert.match(skill, /verdict\//); - assert.match(skill, /refining-with-feedback/); - assert.match(skill, /all previous drafts/i); - assert.match(skill, /latest verdict/i); -}); - -test("subagent-driven-replication Skill documents orchestrator-led worker and reviewer flow", async () => { - const skill = await readText(join("skills", "subagent-driven-replication", "SKILL.md")); - - assert.match(skill, /Orchestrator/i); - assert.match(skill, /Initial Draft/i); - assert.match(skill, /visual annotation worker/i); - assert.match(skill, /read-write/i); - assert.match(skill, /annotate_bounding_boxes/); - assert.match(skill, /crop_multiple_bounding_boxes/); - assert.match(skill, /write.*draft/is); - assert.match(skill, /Code Execution/i); - assert.match(skill, /subagent-driven-development/i); - assert.match(skill, /superpowers/i); - assert.match(skill, /same time only one worker/i); - assert.match(skill, /sequentially dispatch multiple workers/i); - assert.match(skill, /Verify/i); - assert.match(skill, /reviewer preset/i); - assert.match(skill, /completion approval/i); - assert.match(skill, /avoid.*timeoutMs/is); - assert.match(skill, /avoid.*maxRuntimeMs/is); - assert.match(skill, /async: true/); - assert.match(skill, /synthesize.*verdict/is); - assert.match(skill, /verdict\.md/i); - assert.match(skill, /refining-with-feedback/); -}); - -test("inline and subagent replication Skills avoid redundant negative definitions", async () => { - const inline = await readText(join("skills", "inline-replication", "SKILL.md")); - const sdr = await readText(join("skills", "subagent-driven-replication", "SKILL.md")); - - assert.match(inline, /Use the gateway workspace directory meanings/i); - assert.match(inline, /masked diff evidence as supporting evidence/i); - assert.match(inline, /direct inspection remains the interpreter/i); - assert.match(inline, /mask-out regions preserve all code-drawable content/i); - assert.match(inline, /Use `verdict\/` for process feedback and `final\/` for delivery handoff/i); - assert.doesNotMatch(inline, /without redefining their meaning/i); - assert.doesNotMatch(inline, /not as the final interpreter/i); - assert.doesNotMatch(inline, /do not hide code-drawable content/i); - assert.doesNotMatch(inline, /Letting `verdict\/` become the final handoff instead of process feedback/i); - - assert.match(sdr, /orchestration stays in the parent session/i); - assert.match(sdr, /Page implementation starts in Code Execution/i); - assert.match(sdr, /approval findings scoped to draft reasonableness, completion, and evidence quality/i); - assert.match(sdr, /Synthesize child outputs into the verdict/i); - assert.match(sdr, /final direct inspection happens through `finalizing-replication`/i); - assert.match(sdr, /Synthesize reviewer output before writing verdict\.md/i); - assert.doesNotMatch(sdr, /should not run their own orchestration loops/i); - assert.doesNotMatch(sdr, /should not implement page code during this phase/i); - assert.doesNotMatch(sdr, /not open-ended redesign/i); - assert.doesNotMatch(sdr, /Do not paste child outputs as the verdict/i); - assert.doesNotMatch(sdr, /does not replace final direct inspection/i); - assert.doesNotMatch(sdr, /Accepting reviewer output as verdict\.md without Orchestrator synthesis/i); -}); - -test("refining-with-feedback Skill documents draft-history synthesis", async () => { - const skill = await readText(join("skills", "refining-with-feedback", "SKILL.md")); - - assert.match(skill, /DraftHistory/i); - assert.match(skill, /all previous drafts/i); - assert.match(skill, /latest verdict/i); - assert.match(skill, /oracles\/oracle-manifest\.json/); - assert.match(skill, /drafts\//); - assert.match(skill, /verdict\//); - assert.match(skill, /preserve confirmed facts/i); - assert.match(skill, /stable element names/i); - assert.match(skill, /blockers/i); - assert.match(skill, /fixes worth doing now/i); - assert.match(skill, /optional.*deferred/is); - assert.match(skill, /accepted exclusions/i); - assert.match(skill, /rejected exclusions/i); - assert.match(skill, /mask problems/i); - assert.match(skill, /drafts\/feedback-draft/i); - assert.match(skill, /inline-replication/); - assert.match(skill, /subagent-driven-replication/); - assert.match(skill, /code execution/i); - assert.match(skill, /evidence paths/i); - assert.match(skill, /code execution and worker dispatch stay with inline-replication or subagent-driven-replication/i); -}); - -test("refining-with-feedback Skill avoids redundant negative definitions", async () => { - const skill = await readText(join("skills", "refining-with-feedback", "SKILL.md")); - - assert.match(skill, /a user request can promote them into the next loop scope/i); - assert.match(skill, /code execution and worker dispatch stay with inline-replication or subagent-driven-replication/i); - assert.match(skill, /required work contains blockers, fix-now targets, rejected exclusions, and mask problems/i); - assert.match(skill, /Preserve DraftHistory when writing each feedback draft/i); - assert.match(skill, /Keep stable element names unless verdict evidence requires a rename/i); - assert.match(skill, /Create a concrete feedback draft before returning to the execution loop/i); - assert.doesNotMatch(skill, /should not expand the next loop unless the user asks for them/i); - assert.doesNotMatch(skill, /does not implement code/i); - assert.doesNotMatch(skill, /does not dispatch workers/i); - assert.doesNotMatch(skill, /optional\/deferred notes are not mixed into required work/i); - assert.doesNotMatch(skill, /Rewriting the Initial Draft from scratch instead of preserving DraftHistory/i); - assert.doesNotMatch(skill, /Changing element names without evidence/i); - assert.doesNotMatch(skill, /Sending the next loop forward without a concrete feedback draft/i); -}); - -test("finalizing-replication Skill documents final inspection and delivery routing", async () => { - const skill = await readText(join("skills", "finalizing-replication", "SKILL.md")); - - assert.match(skill, /final direct inspection/i); - assert.match(skill, /direct visual inspection remains the interpreter/i); - assert.match(skill, /oracles\/oracle-manifest\.json/); - assert.match(skill, /DraftHistory/i); - assert.match(skill, /rendered\//); - assert.match(skill, /diffs\//); - assert.match(skill, /accepted exclusions/i); - assert.match(skill, /user requirements/i); - assert.match(skill, /final\/final-inspection\.md/); - assert.match(skill, /final\/delivery-review\.md/); - assert.match(skill, /final\/accepted-render\.png/); - assert.match(skill, /final\/remaining-limitations\.md/); - assert.match(skill, /final\/final-inspection-failed\.md/); - assert.match(skill, /verdict\/finalizing-verdict/i); - assert.match(skill, /refining-with-feedback/); - assert.match(skill, /user-facing delivery review/i); - assert.match(skill, /diff clean opens final inspection/i); -}); - -test("README documents visual evidence workflows and Phase 2 auxiliary tools", async () => { - const readme = await readText("README.md"); - - assert.match(readme, /visual evidence workflow/i); - assert.match(readme, /screenshots/i); - assert.match(readme, /frontend visual reproduction/i); - assert.match(readme, /visual QA/i); - assert.match(readme, /Visual evidence needs trigger the package/i); - assert.match(readme, /## Tool: `crop_multiple_bounding_boxes`/); - assert.match(readme, /## Tool: `annotate_bounding_boxes`/); - assert.match(readme, /## Tool: `crop_around_point`/); - assert.match(readme, /fail-fast/i); - assert.match(readme, /requires an explicit crop size/i); -}); - -test("using-visual-primitives Skill routes helper tool workflows", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /crop_multiple_bounding_boxes/); - assert.match(skill, /annotate_bounding_boxes/); - assert.match(skill, /crop_around_point/); - assert.match(skill, /Tool Selection/i); - assert.match(skill, /explicit `radius` or `size`/i); -}); - -test("using-visual-primitives Skill describes broad tool usage scenarios", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /region hypothesis/i); - assert.match(skill, /layout comparison/i); - assert.match(skill, /spacing/i); - assert.match(skill, /visual QA/i); - assert.match(skill, /masked diff component/i); - assert.match(skill, /edge alignment/i); - assert.match(skill, /text baseline/i); - assert.match(skill, /shadow mismatch/i); - assert.match(skill, /gradient/i); - assert.match(skill, /palette/i); -}); - -test("using-visual-primitives Skill documents multi-image proofreading workflow", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /For two or more images/i); - assert.match(skill, /annotate_bounding_boxes[\s\S]*crop_multiple_bounding_boxes/); - assert.match(skill, /resolvedPixelBox/i); - assert.match(skill, /width.*height.*area/i); - assert.match(skill, /Directly inspect the annotated images and crop outputs/i); -}); - -test("using-visual-primitives Skill documents second-order quantities and color sampling", async () => { - const skill = await readText(join("skills", "using-visual-primitives", "SKILL.md")); - - assert.match(skill, /Second-Order Quantities Must Be Computed/i); - assert.match(skill, /Distance, gap, size difference, alignment offset, and ratio/i); - assert.match(skill, /gap = card2\.left - card1\.right = 412 - 330 = 82px/i); - assert.match(skill, /sample_colors/); - assert.match(skill, /CSS-level color precision/i); -}); - -test("frontend replication references publish stable loop contracts", async () => { - const oracleManifest = await readText(join("skills", "frontend-replication", "references", "oracle-manifest.md")); - const draftContract = await readText(join("skills", "frontend-replication", "references", "draft-contract.md")); - const verdictContract = await readText(join("skills", "frontend-replication", "references", "verdict-contract.md")); - const maskedDiff = await readText(join("skills", "frontend-replication", "references", "masked-oracle-diff.md")); - const screenshotCapture = await readText(join("skills", "frontend-replication", "references", "screenshot-capture.md")); - - assert.match(oracleManifest, /oracles\/oracle-manifest\.json/); - assert.match(oracleManifest, /viewport/); - assert.match(oracleManifest, /oraclePairs/); - assert.match(draftContract, /Initial Draft/); - assert.match(draftContract, /Feedback Draft/); - assert.match(verdictContract, /blockers/i); - assert.match(verdictContract, /fixes worth doing now/i); - assert.match(maskedDiff, /npm run oracle:diff -- --manifest/); - assert.match(maskedDiff, /scripts\/diff-manifest\.json/); - assert.match(maskedDiff, /minComponentArea/); - assert.match(screenshotCapture, /same viewport/i); - assert.match(screenshotCapture, /same pixel dimensions/i); -}); - -test("replication Skills wire Verify to masked-oracle-diff and reference contracts", async () => { - const frontend = await readText(join("skills", "frontend-replication", "SKILL.md")); - const inline = await readText(join("skills", "inline-replication", "SKILL.md")); - const sdr = await readText(join("skills", "subagent-driven-replication", "SKILL.md")); - const refining = await readText(join("skills", "refining-with-feedback", "SKILL.md")); - const finalizing = await readText(join("skills", "finalizing-replication", "SKILL.md")); - - assert.match(frontend, /references\/oracle-manifest\.md/); - assert.match(frontend, /references\/draft-contract\.md/); - assert.match(frontend, /references\/screenshot-capture\.md/); - assert.match(inline, /npm run oracle:diff -- --manifest/); - assert.match(inline, /scripts\/diff-manifest\.json/); - assert.match(inline, /VERDICT\.md/); - assert.match(inline, /components\.json[\s\S]*center[\s\S]*crop_around_point/i); - assert.match(inline, /second-order[\s\S]*sample_colors/i); - assert.match(sdr, /npm run oracle:diff -- --manifest/); - assert.match(sdr, /pi-subagents/); - assert.match(sdr, /fall back to `inline-replication`/i); - assert.match(sdr, /components\.json[\s\S]*center[\s\S]*crop_around_point/i); - assert.match(sdr, /second-order[\s\S]*sample_colors/i); - assert.match(refining, /Default max feedback rounds: 3/i); - assert.match(refining, /same finding recurs after two feedback drafts/i); - assert.match(finalizing, /summary\.json/); - assert.match(finalizing, /components\.json/); - assert.match(finalizing, /stripes\.json/); -}); - -test("loop hardening spec matches sample_colors output shape", async () => { - const spec = await readText(join("docs", "superpowers", "specs", "2026-07-02-review-proposal-loop-hardening-spec.md")); - - assert.match(spec, /"patch"[\s\S]*"meanHex"/); - assert.doesNotMatch(spec, /"patchMeanHex"/); -}); - -test("README and roadmap record approved tool boundary decisions", async () => { - const readme = await readText("README.md"); - const roadmap = await readText(join("docs", "assistant-capabilities-roadmap.md")); - - assert.match(readme, /sample_colors/); - assert.match(readme, /pi-subagents/); - assert.match(readme, /subagent-driven-replication/); - assert.match(roadmap, /overlay_grid.*rejected/is); - assert.match(roadmap, /measure_distance.*rejected/is); - assert.match(roadmap, /sample_colors.*approved/is); - assert.match(roadmap, /coordinates into visual artifacts/i); - assert.match(roadmap, /coordinates into numeric evidence/i); -}); - -test("README uses positive capability boundaries", async () => { - const readme = await readText("README.md"); - - assert.match(readme, /Visual evidence needs trigger the package/i); - assert.match(readme, /Detection, OCR, segmentation, automatic box generation, and automatic UI inference stay outside the tool contract/i); - assert.match(readme, /requires an explicit crop size/i); - assert.match(readme, /Palette and dominant-color discovery stay outside the point-sampling contract/i); - assert.match(readme, /Use `using-visual-primitives` for standalone visual evidence tasks/i); - assert.doesNotMatch(readme, /Coordinates are not the trigger/i); - assert.doesNotMatch(readme, /does not generate boxes, detect objects, OCR text, segment images, or infer UI elements automatically/i); - assert.doesNotMatch(readme, /The legacy single `visual-primitives` Skill entry has been retired/i); - assert.doesNotMatch(readme, /it does not detect palettes or dominant colors/i); - assert.doesNotMatch(readme, /does not invent a default crop size/i); -}); - -test("README worked examples keep exclusion guidance positive and internally consistent", async () => { - const readme = await readText("README.md"); - - assert.match(readme, /Render every code-drawable region in code/i); - assert.match(readme, /Approved exclusions may be represented by placeholders or delegated image assets/i); - assert.match(readme, /Keep code-drawable content inside the scoring domain/i); - assert.match(readme, /The NetEase logo mark was left in the code-replication scope/i); - assert.match(readme, /dense brand marks can be declared as narrow exclusion candidates/i); - assert.doesNotMatch(readme, /Do not use image assets/i); - assert.doesNotMatch(readme, /Never exclude code-drawable content/i); - assert.doesNotMatch(readme, /should not be asked to paint/i); - assert.doesNotMatch(readme, /That is exactly why the workflow treats logos, avatars, and cover art as delegation-and-exclusion candidates/i); -}); - -test("roadmap records Phase 2 as implemented while keeping UI deferred", async () => { - const roadmap = await readText(join("docs", "assistant-capabilities-roadmap.md")); - - assert.match(roadmap, /## Phase 2: Auxiliary Tools/); - assert.match(roadmap, /Implemented in this package as runtime tools/); - assert.match(roadmap, /crop_multiple_bounding_boxes/); - assert.match(roadmap, /annotate_bounding_boxes/); - assert.match(roadmap, /crop_around_point/); - assert.match(roadmap, /## Phase 3: UI Interaction/); - assert.match(roadmap, /UI interaction should be deferred/i); + assert.match(skill, /direct visual inspection/i); + assert.match(skill, /skills\/_shared\/run-vp\.mjs/); + assert.match(skill, /package-local/i); + assert.match(skill, /second-order/i); + assert.match(skill, /resolvedPixelBox/); + for (const command of ["vp crop", "vp crop-multi", "vp annotate", "vp point", "vp colors"]) { + assert.match(skill, new RegExp(command.replace("-", "\\-"))); + } + for (const legacyName of legacyToolNames) { + assert.doesNotMatch(skill, new RegExp(legacyName)); + } + assert.doesNotMatch(skill, /pi-visual-primitives/i); + assert.doesNotMatch(skill, /masked[- ]diff|oracle|draft|verdict|replication|finaliz/i); +}); + +test("replication Skills reference generic guidance without old extension tool calls", async () => { + const family = await Promise.all(expectedSkills + .filter((name) => name !== "using-visual-primitives") + .map(async (name) => [name, normalizeLines(await readText(`skills/${name}/SKILL.md`))] as const)); + const combined = family.map(([, skill]) => skill).join("\n"); + + assert.match(combined, /using-visual-primitives/); + assert.match(combined, /oracle/i); + assert.match(combined, /masked diff/i); + assert.match(combined, /draft/i); + assert.match(combined, /verdict/i); + assert.match(combined, /final direct inspection/i); + assert.match(combined, /vp annotate/); + assert.match(combined, /vp point/); + assert.match(combined, /vp colors/); + for (const legacyName of legacyToolNames) { + assert.doesNotMatch(combined, new RegExp(legacyName)); + } +}); + +test("masked-oracle-diff remains frontend-replication-owned", async () => { + const packageJson = JSON.parse(await readText("package.json")); + const cliHelp = (await execFileAsync(process.execPath, [join(packageRootPath, "dist", "cli.js"), "--help"], { + cwd: packageRootPath, + })).stdout; + + assert.equal(await pathExists("scripts/masked-oracle-diff.ts"), false); + assert.equal(await pathExists("skills/frontend-replication/scripts/masked-oracle-diff.ts"), true); + assert.equal(await pathExists("skills/frontend-replication/scripts/masked-oracle-diff.js"), true); + assert.equal(await pathExists("skills/frontend-replication/scripts/run-masked-oracle-diff.mjs"), true); + assert.match(packageJson.scripts?.check, /skills\/frontend-replication\/scripts\/run-masked-oracle-diff\.mjs/); + assert.match(packageJson.scripts?.check, /skills\/frontend-replication\/scripts\/masked-oracle-diff\.(?:ts|js)/); + assert.match(packageJson.scripts?.["oracle:diff"], /skills\/frontend-replication\/scripts\/masked-oracle-diff\.js/); + assert.doesNotMatch(JSON.stringify(packageJson.bin), /masked-oracle-diff/); + assert.doesNotMatch(cliHelp, /masked-oracle-diff/); +}); + +test("frontend replication references retain workflow contracts", async () => { + const references = await Promise.all([ + "oracle-manifest.md", + "draft-contract.md", + "verdict-contract.md", + "masked-oracle-diff.md", + "screenshot-capture.md", + ].map((name) => readText(`skills/frontend-replication/references/${name}`))); + const combined = normalizeLines(references.join("\n")); + + assert.match(combined, /oracle-manifest\.json/); + assert.match(combined, /Initial Draft/); + assert.match(combined, /Feedback Draft/); + assert.match(combined, /blockers/i); + assert.match(combined, /fixes worth doing now/i); + assert.match(combined, /run-masked-oracle-diff\.mjs --manifest/); + assert.doesNotMatch(combined, /npm run oracle:diff/); + assert.match(combined, /same pixel dimensions/i); }); diff --git a/tests/release-bootstrap.test.ts b/tests/release-bootstrap.test.ts new file mode 100644 index 0000000..605c17a --- /dev/null +++ b/tests/release-bootstrap.test.ts @@ -0,0 +1,63 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { promisify } from "node:util"; + +const execFileAsync = promisify(execFile); +const verifier = new URL("../scripts/verify-release-bootstrap.mjs", import.meta.url); + +async function runVerifier(state: "bootstrap-only" | "missing") { + const root = await mkdtemp(join(tmpdir(), "visual-primitives-bootstrap-")); + try { + const mockPath = join(root, "mock-npm.mjs"); + await writeFile(mockPath, ` +const args = process.argv.slice(2); +const explicitBootstrap = args.includes("@mapleluvr/visual-primitives@bootstrap"); +if (!explicitBootstrap || process.env.MOCK_BOOTSTRAP_STATE === "missing") { + console.error("npm error code E404"); + process.exit(1); +} +process.stdout.write(JSON.stringify({ + name: "@mapleluvr/visual-primitives", + version: "0.0.0-bootstrap.0" +})); +`); + try { + const result = await execFileAsync(process.execPath, [ + verifier.pathname.replace(/^\/(?:([A-Za-z]:))/, "$1"), + ], { + env: { + ...process.env, + MOCK_BOOTSTRAP_STATE: state, + NPM_CLI_PATH: process.execPath, + NPM_CLI_PREFIX: mockPath, + }, + }); + return { status: "fulfilled" as const, stdout: result.stdout }; + } catch (error) { + return { + status: "rejected" as const, + stderr: String((error as { stderr?: string }).stderr ?? error), + }; + } + } finally { + await rm(root, { recursive: true, force: true }); + } +} + +test("bootstrap verifier succeeds when bootstrap exists without latest", async () => { + const result = await runVerifier("bootstrap-only"); + assert.equal(result.status, "fulfilled"); + if (result.status !== "fulfilled") return; + assert.match(result.stdout, /0\.0\.0-bootstrap\.0/); +}); + +test("bootstrap verifier fails when the explicit bootstrap tag is missing", async () => { + const result = await runVerifier("missing"); + assert.equal(result.status, "rejected"); + if (result.status !== "rejected") return; + assert.match(result.stderr, /bootstrap verification failed/i); +}); diff --git a/tests/release-contract.test.ts b/tests/release-contract.test.ts new file mode 100644 index 0000000..afd2698 --- /dev/null +++ b/tests/release-contract.test.ts @@ -0,0 +1,130 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; + +const packageRoot = new URL("..", import.meta.url); + +async function readText(relativePath: string): Promise { + return readFile(new URL(relativePath, packageRoot), "utf8"); +} + +test("package manifest declares the public artifact and smoke entrypoint", async () => { + const packageJson = JSON.parse(await readText("package.json")); + + assert.equal(packageJson.name, "@mapleluvr/visual-primitives"); + assert.equal(packageJson.engines?.node, ">=22.18"); + assert.equal(packageJson.repository?.url, "git+https://github.com/mapleluvr/visual-primitives.git"); + assert.equal(packageJson.publishConfig?.access, "public"); + assert.ok(packageJson.keywords?.includes("pi-package")); + assert.equal(packageJson.scripts?.["package:smoke"], "node scripts/package-smoke.mjs"); + assert.deepEqual(packageJson.files, [ + "dist", + "skills", + "README.md", + "README.zh-CN.md", + "CHANGELOG.md", + "RELEASE.md", + "LICENSE", + ]); +}); + +test("public release files and LF policy exist", async () => { + const [license, changelog, releaseGuide, attributes] = await Promise.all([ + readText("LICENSE"), + readText("CHANGELOG.md"), + readText("RELEASE.md"), + readText(".gitattributes"), + ]); + + assert.match(license, /MIT License/); + assert.match(license, /Copyright \(c\) 2026 mapleluvr/i); + assert.match(changelog, /## \[0\.2\.0\]/); + assert.match(changelog, /vp CLI/i); + assert.match(changelog, /Skill Set/i); + assert.match(releaseGuide, /first publication bootstrap/i); + assert.match(releaseGuide, /rename[\s\S]*mapleluvr\/visual-primitives/i); + assert.match(releaseGuide, /0\.0\.0-bootstrap\.0/); + assert.match(releaseGuide, /--tag bootstrap/); + assert.match(releaseGuide, /trusted publisher[\s\S]*provenance/i); + assert.match(releaseGuide, /npm view @mapleluvr\/visual-primitives@bootstrap name/); + assert.match(releaseGuide, /RELEASE_BOOTSTRAPPED/); + assert.match(releaseGuide, /separate authorization/i); + assert.match(attributes, /^\* text=auto eol=lf$/m); + assert.match(attributes, /^\*\.png binary$/m); +}); + +test("CI tests supported operating systems and Node versions", async () => { + const workflow = await readText(".github/workflows/ci.yml"); + + assert.match(workflow, /ubuntu-latest/); + assert.match(workflow, /windows-latest/); + assert.match(workflow, /macos-latest/); + assert.match(workflow, /22\.18\.0/); + assert.match(workflow, /24\.x/); + assert.match(workflow, /npm ci --ignore-scripts/); + assert.match(workflow, /npm run check/); + assert.match(workflow, /npm test/); + assert.match(workflow, /npm run package:smoke/); +}); + +test("release workflow is tag-gated and uses npm trusted publishing", async () => { + const [workflow, bootstrapVerifier] = await Promise.all([ + readText(".github/workflows/release.yml"), + readText("scripts/verify-release-bootstrap.mjs"), + ]); + + assert.match(workflow, /tags:\s*\n\s*- ['"]v\*\.\*\.\*['"]/); + assert.match(workflow, /id-token: write/); + assert.match(workflow, /contents: write/); + assert.match(workflow, /npm run release:verify-tag/); + assert.match(workflow, /vars\.RELEASE_BOOTSTRAPPED/); + assert.match(workflow, /TARGET_REPOSITORY: mapleluvr\/visual-primitives/); + assert.match(workflow, /test "\$\{GITHUB_REPOSITORY\}" = "\$\{TARGET_REPOSITORY\}"/); + assert.match(workflow, /release:verify-bootstrap/); + assert.match(bootstrapVerifier, /@bootstrap/); + assert.match(bootstrapVerifier, /0\.0\.0-bootstrap\.0/); + assert.match(workflow, /npm pack --json --ignore-scripts --pack-destination release/); + assert.match(workflow, /id:\s*npm-state/); + assert.match(workflow, /steps\.npm-state\.outputs\.publish == 'true'/); + assert.match(workflow, /npm publish[\s\S]*--provenance[\s\S]*--access public/); + assert.match(workflow, /gh release view[\s\S]*gh release create/); + assert.match(workflow, /gh release upload[\s\S]*--clobber/); + assert.match(workflow, /npm sbom/); + assert.doesNotMatch(workflow, /NPM_TOKEN|NODE_AUTH_TOKEN|npm_token/i); +}); + +test("English README documents installation, roles, versioning, and extension migration", async () => { + const readme = await readText("README.md"); + + assert.match(readme, /npm install -g @mapleluvr\/visual-primitives/); + assert.match(readme, /pi install npm:@mapleluvr\/visual-primitives@0\.2\.0/); + assert.match(readme, /pi install git:github\.com\/mapleluvr\/visual-primitives@v0\.2\.0/); + assert.match(readme, /Node\.js 22\.18 or newer/); + assert.match(readme, /using-visual-primitives/); + assert.match(readme, /frontend-replication/); + assert.match(readme, /masked-oracle-diff[\s\S]*not a `vp` command/i); + assert.match(readme, /one package version[\s\S]*one Git tag/i); + assert.match(readme, /Migration from `pi-visual-primitives`/); + assert.match(readme, /skills\/_shared\/run-vp\.mjs/); + assert.match(readme, /run-masked-oracle-diff\.mjs/); + assert.match(readme, /RELEASE\.md/); + assert.doesNotMatch(readme, /pi -e \.\/pi-visual-primitives|loads both the extension tool and the Skill/i); +}); + +test("Chinese README documents the same installation and migration boundary", async () => { + const readme = await readText("README.zh-CN.md"); + + assert.match(readme, /npm install -g @mapleluvr\/visual-primitives/); + assert.match(readme, /pi install npm:@mapleluvr\/visual-primitives@0\.2\.0/); + assert.match(readme, /pi install git:github\.com\/mapleluvr\/visual-primitives@v0\.2\.0/); + assert.match(readme, /Node\.js 22\.18/); + assert.match(readme, /using-visual-primitives/); + assert.match(readme, /frontend-replication/); + assert.match(readme, /masked-oracle-diff/); + assert.match(readme, /不是 `vp` 子命令/); + assert.match(readme, /pi-visual-primitives/); + assert.match(readme, /skills\/_shared\/run-vp\.mjs/); + assert.match(readme, /run-masked-oracle-diff\.mjs/); + assert.match(readme, /RELEASE\.md/); + assert.doesNotMatch(readme, /同时加载扩展工具和技能/); +}); diff --git a/tests/release-state-adapter.test.ts b/tests/release-state-adapter.test.ts new file mode 100644 index 0000000..7fcc381 --- /dev/null +++ b/tests/release-state-adapter.test.ts @@ -0,0 +1,89 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { tmpdir } from "node:os"; +import { promisify } from "node:util"; + +const execFileAsync = promisify(execFile); +const resolver = new URL("../scripts/resolve-release-state.mjs", import.meta.url); +const local = { + id: "@mapleluvr/visual-primitives@0.2.0", + name: "@mapleluvr/visual-primitives", + version: "0.2.0", + integrity: "sha512-local", + shasum: "local-shasum", +}; + +async function runResolver(state: "missing" | "identical" | "mismatch") { + const root = await mkdtemp(join(tmpdir(), "visual-primitives-release-state-")); + try { + const packPath = join(root, "pack.json"); + const outputPath = join(root, "github-output.txt"); + const mockPath = join(root, "mock-npm.mjs"); + await writeFile(packPath, JSON.stringify([local])); + await writeFile(mockPath, ` +const state = process.env.MOCK_NPM_STATE; +if (state === "missing") { + console.error("npm error code E404"); + process.exit(1); +} +const same = state === "identical"; +process.stdout.write(JSON.stringify({ + name: "@mapleluvr/visual-primitives", + version: "0.2.0", + dist: { + integrity: same ? "sha512-local" : "sha512-other", + shasum: same ? "local-shasum" : "other-shasum" + } +})); +`); + try { + const result = await execFileAsync(process.execPath, [resolver.pathname.replace(/^\/(?:([A-Za-z]:))/, "$1"), packPath], { + env: { + ...process.env, + GITHUB_OUTPUT: outputPath, + MOCK_NPM_STATE: state, + NPM_CLI_PATH: process.execPath, + NPM_CLI_PREFIX: mockPath, + }, + }); + return { + status: "fulfilled" as const, + stdout: result.stdout, + githubOutput: await readFile(outputPath, "utf8"), + }; + } catch (error) { + return { + status: "rejected" as const, + stderr: String((error as { stderr?: string }).stderr ?? error), + }; + } + } finally { + await rm(root, { recursive: true, force: true }); + } +} + +test("release adapter marks a registry 404 for publication", async () => { + const result = await runResolver("missing"); + assert.equal(result.status, "fulfilled"); + if (result.status !== "fulfilled") return; + assert.match(result.stdout, /"action":"publish"/); + assert.match(result.githubOutput, /^publish=true$/m); +}); + +test("release adapter skips an identical published tarball", async () => { + const result = await runResolver("identical"); + assert.equal(result.status, "fulfilled"); + if (result.status !== "fulfilled") return; + assert.match(result.stdout, /"action":"skip-identical"/); + assert.match(result.githubOutput, /^publish=false$/m); +}); + +test("release adapter blocks an immutable version mismatch", async () => { + const result = await runResolver("mismatch"); + assert.equal(result.status, "rejected"); + if (result.status !== "rejected") return; + assert.match(result.stderr, /already exists with different integrity/i); +}); diff --git a/tests/release-state.test.ts b/tests/release-state.test.ts new file mode 100644 index 0000000..a7d5c2e --- /dev/null +++ b/tests/release-state.test.ts @@ -0,0 +1,51 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { decideNpmPublish } from "../scripts/release-state.mjs"; + +const local = { + id: "@mapleluvr/visual-primitives@0.2.0", + name: "@mapleluvr/visual-primitives", + version: "0.2.0", + integrity: "sha512-local", + shasum: "local-shasum", +}; + +test("release state publishes an unpublished version", () => { + assert.deepEqual(decideNpmPublish(local, null), { + action: "publish", + reason: "version-unpublished", + }); +}); + +test("release state skips an already-published identical artifact", () => { + assert.deepEqual(decideNpmPublish(local, { + name: local.name, + version: local.version, + dist: { integrity: local.integrity, shasum: local.shasum }, + }), { + action: "skip-identical", + reason: "version-already-published-with-matching-integrity", + }); +}); + +test("release state rejects an already-published different artifact", () => { + assert.throws( + () => decideNpmPublish(local, { + name: local.name, + version: local.version, + dist: { integrity: "sha512-other", shasum: "other-shasum" }, + }), + /already exists with different integrity/i, + ); +}); + +test("release state rejects mismatched registry identity", () => { + assert.throws( + () => decideNpmPublish(local, { + name: "@mapleluvr/not-visual-primitives", + version: local.version, + dist: { integrity: local.integrity, shasum: local.shasum }, + }), + /identity mismatch/i, + ); +}); diff --git a/tests/schema.test.ts b/tests/schema.test.ts deleted file mode 100644 index 4b6592c..0000000 --- a/tests/schema.test.ts +++ /dev/null @@ -1,36 +0,0 @@ -import test from "node:test"; -import assert from "node:assert/strict"; -import { cropAroundPointSchema, sampleColorsSchema } from "../src/schema.ts"; - -test("cropAroundPointSchema requires exactly one explicit crop size mode", () => { - assert.deepEqual((cropAroundPointSchema as any).oneOf, [ - { required: ["radius"], not: { required: ["size"] } }, - { required: ["size"], not: { required: ["radius"] } }, - ]); -}); - -test("cropAroundPointSchema documents positive radius and size dimensions", () => { - const schema = cropAroundPointSchema as any; - - assert.equal(schema.properties.radius.exclusiveMinimum, 0); - assert.equal(schema.properties.size.properties.width.exclusiveMinimum, 0); - assert.equal(schema.properties.size.properties.height.exclusiveMinimum, 0); -}); - -test("sampleColorsSchema requires image path and points", () => { - const schema = sampleColorsSchema as any; - - assert.deepEqual(schema.required, ["imagePath", "points"]); - assert.equal(schema.properties.points.minItems, 1); - assert.deepEqual(schema.properties.coordinateSpace.enum, ["normalized-999", "pixel"]); - assert.deepEqual(schema.properties.origin.enum, ["top-left", "bottom-left"]); -}); - -test("sampleColorsSchema documents odd positive patch size", () => { - const schema = sampleColorsSchema as any; - - assert.equal(schema.properties.patchSize.type, "integer"); - assert.equal(schema.properties.patchSize.minimum, 1); - assert.equal(schema.properties.patchSize.default, 1); - assert.match(schema.properties.patchSize.description, /odd/i); -});