pi-jscpd 0.1.0

package/docs/overlay-interaction.md

@@ -0,0 +1,347 @@
+# `/jscpd` overlay interaction contract
+
+Status: **implemented with managed-runtime action execution**
+
+Applies to: bare `/jscpd` only
+
+Does not change: `/jscpd scan`, `/jscpd changed`, `/jscpd status`, session controls, or `jscpd_run`
+
+Overlay actions route through the extension's single managed runtime while Pi TUI
+rendering and input remain the host adapter. The implementation preserves every
+interaction below.
+
+## Decision summary
+
+In Pi's TUI mode, bare `/jscpd` opens one centered responsive overlay. Its
+initial view is a **combined overview**, not an implicit scan or a command
+palette. It shows compact status, the current ephemeral result when one exists,
+and explicit actions. The user can request a changed-files check or full-project
+scan, inspect bounded findings, toggle the session mode, refresh status, or open
+help. The overlay never edits source, runs project tests, or changes jscpd
+configuration.
+
+The interface has three views:
+
+1. **Overview** — status, last check, changed-file count, current-result summary,
+   and explicit actions.
+2. **Findings navigator** — a bounded searchable list with inline expansion,
+   multi-selection, result counts, and a safe editor-prompt handoff.
+3. **Help** — controls, state meanings, explicit command equivalents, and the
+   intentional-duplication caveat.
+
+The visual and keyboard model follows Pi Fallow's established findings navigator:
+a branded frame, compact status/count pills, selected-row background plus marker,
+inline details, explicit earlier/later indicators, and visible controls. Navigation
+uses one focused overlay and never creates stacked child overlays.
+
+## Entry and initial state
+
+Bare `/jscpd` must never mean “scan now.” In TUI mode the command calls:
+
+```ts
+ctx.ui.custom(factory, {
+  overlay: true,
+  overlayOptions: {
+    anchor: "center",
+    width: "90%",
+    minWidth: 50,
+    maxHeight: "95%",
+  },
+});
+```
+
+The overlay opens immediately with a bounded loading overview while it obtains
+status through the existing service. A capability probe is allowed because the
+user explicitly opened the integration; no duplication scan starts until the
+user chooses one.
+
+The overview then shows:
+
+- session mode and whether it came from configuration or a session override;
+- binary readiness and version, or a short setup/recovery state;
+- effective extension configuration source;
+- last-check summary;
+- tracked session-change count and whether the current result is fresh;
+- current finding/clean summary when an ephemeral result is available; and
+- the available actions.
+
+An ephemeral result cache may retain up to 100 normalized findings only for the
+active extension runtime, project, branch scope, and mutation generation. This
+TUI-only retention is independent of `maxFindings`: model/tool messages, explicit
+subcommand output, acknowledgement writes, and persisted state remain capped by
+the configured limit. The cache is cleared on session replacement/reload and
+invalidated by a newer mutation or branch navigation. Findings and source
+fragments are not added to persisted session state. After restoration, the
+overview may show the persisted last-check summary, but opening details requires
+a new current result.
+
+## Views and actions
+
+### Overview
+
+The action list is ordered as follows:
+
+1. **Check session changes** — equivalent to `/jscpd changed`; this is the
+   default action when tracked changes exist and scanning is enabled.
+2. **Scan project** — equivalent to `/jscpd scan` with no target arguments.
+3. **View findings** — available only for a fresh cached result containing
+   findings.
+4. **Refresh status** — equivalent to the status service, not a duplication
+   scan.
+5. **Disable for session** or **Enable for session** — routes through the
+   existing `off`/`on` control and changes no project file.
+6. **Help**.
+
+Arbitrary target entry is intentionally omitted from the first overlay. Users
+retain `/jscpd scan <target ...>` for scoped scans; this avoids introducing a
+second path parser or an ambiguous free-form field.
+
+### Findings navigator
+
+The findings view uses the ordering already selected by the presentation layer.
+For changed checks, pairs whose two locations changed in the session come first,
+then larger pairs, then deterministic location order. Each compact row identifies
+both bounded paths and line spans plus line count, token count, and format.
+`N`, `E`, and `C` markers mean `new in this session`, `existing match`, and
+`current location`; inline expansion always spells those labels out.
+
+The navigator initially reveals 10 retained findings. **Load next 10 / L**
+reveals another page without rescanning, and moving down or paging past the last
+revealed row automatically reveals the next page. Search and “all shown”
+selection operate on revealed findings; loading another page extends that set.
+
+The header and result context distinguish filtered, shown, retained, total,
+overlay-cache omissions, and safely unclassified counts. The viewport shows
+explicit earlier/later indicators. The selected row uses both a `❯` marker and
+Pi's selected background. Below 64 columns, each finding becomes a three-line row
+so both locations remain readable rather than disappearing behind truncation.
+
+Enter, Space, Right, or `l` expands the current finding inline. Left or `h`
+collapses it. Expanded content repeats both locations, relation labels, size,
+format, verification state, omission/ambiguity context, and advisory next steps.
+The list never renders source fragments or internal fingerprints and retains at
+most 100 validated findings.
+
+`/` enters search mode. Search is a case-insensitive literal substring match
+against the two displayed paths and format. It is not a regular expression,
+does not access the filesystem, and is capped at 256 Unicode code points. Enter
+accepts the query, Esc restores the query that existed before editing, Ctrl+U
+clears it, and `x` clears an applied query. An empty query restores deterministic
+order. A no-match state keeps search and close controls visible.
+
+`s` or Tab marks the current finding, `A` toggles all shown findings, and `c`
+clears selection. `e` or `a` closes the overlay and returns a compact prompt for
+the selected findings—or the current finding when none are marked. At most 20
+findings and 12,000 Unicode code points enter that prompt. Only after
+`ui.custom()` has returned does the launcher call `setEditorText()` and notify
+the user. It never submits the editor, triggers a model turn, mutates source,
+runs tests, or writes configuration. No “refactor now,” “delete,” or automatic
+ignore/configure action belongs in the overlay.
+
+### Help
+
+Help lists the visible keyboard controls, command equivalents, missing-binary
+setup direction, session-only nature of enable/disable, and the advisory rule.
+It remains bounded and does not probe or scan.
+
+## Asynchronous state model
+
+The shell has exactly one of these states:
+
+| State | Rendering and available behavior |
+| --- | --- |
+| `loading-status` | Open immediately; show “Loading status…” and allow cancel/close. |
+| `ready` | Show overview and enabled actions. |
+| `running-changed` | Show “Checking session changes…” and allow cancellation. |
+| `running-scan` | Show “Scanning project…” and allow cancellation. |
+| `clean` | Show a short clean result; add no model message. |
+| `findings` | Show count and allow Findings/detail navigation. |
+| `empty` | Explain that no session-owned changed files are tracked and no scan ran. |
+| `disabled` | Explain the session/config state and make Enable the primary action. |
+| `unavailable` | Show missing/incompatible binary or baseline limitation and recovery action. |
+| `timed-out` | Show the configured bound and allow retry. |
+| `cancelled` | Confirm cancellation and return to usable overview state. |
+| `failed` | Show a bounded safe reason and allow status refresh/retry. |
+| `stale` | Do not present the result as current; require rescan or reopen. |
+
+Messages reuse normalized execution results and must not expose subprocess
+output, environment values, temporary paths, source fragments, or internal
+fingerprints.
+
+Only one overlay action may run at a time. While it runs, scan/toggle actions are
+disabled. Status/help navigation may remain available only if it does not hide
+the cancellation control.
+
+## Cancellation, lifecycle, and ownership
+
+Each overlay instance owns one action `AbortController`. The action still routes
+through the existing scheduled executor and serialized `JscpdService`; the UI
+never starts a child process directly.
+
+- `Esc` or the configured select-cancel key during an idle view goes back one
+  view; from Overview it closes the overlay.
+- During loading or a scan, the first cancel requests abort and keeps the overlay
+  open until the bounded operation settles, then shows `cancelled`.
+- `Ctrl+C` has the same safe cancel behavior while work is active. When idle it
+  closes the overlay rather than exiting Pi.
+- `q` closes from an idle view. If work is active it requests cancellation and
+  closes only after owned settlement.
+- `dispose()` is idempotent, aborts owned work, drops late render callbacks, and
+  starts no cleanup process of its own.
+- Session shutdown, reload, branch navigation, or command-context cancellation
+  aborts the action. Late completions cannot update another branch or project.
+- A result is renderable only when its overlay instance token, project identity,
+  lifecycle scope, and mutation generation remain current. Otherwise render
+  `stale` or discard it if the overlay has closed.
+
+Closing the overlay does not cancel unrelated explicit or automatic work. An
+overlay scan may supersede scheduler-owned automatic work under the existing
+explicit-work priority rule.
+
+## Keyboard and accessibility contract
+
+Use the injected `KeybindingsManager` for Pi select/navigation bindings and
+`matchesKey()` only for overlay-specific letter shortcuts. Never import or
+mutate global keybindings.
+
+| Input | Behavior |
+| --- | --- |
+| configured up/down; `j`/`k` outside search mode | Move selection |
+| configured page up/down; Home/End | Scroll one viewport or jump to a boundary |
+| configured confirm; Enter, Space, Right, `l` | Activate an action or expand/collapse a finding |
+| Left / `h` | Collapse the current finding |
+| configured cancel; `Esc` | Cancel search/work, go back, or close |
+| `Tab` | Open Findings from Overview; mark/unmark the current finding in Findings |
+| `Shift+Tab` | Return to Overview from Findings or Help |
+| `/` | Enter literal search mode in Findings |
+| `Backspace`, arrows, Home/End, `Ctrl+U` | Edit or clear search while search mode is active |
+| `x` | Clear the applied finding search |
+| `L` | Reveal the next 10 retained findings without rescanning |
+| `s` / Tab, `A`, `c` | Mark current, toggle all shown, or clear selected findings |
+| `e` / `a` | Close and load a bounded finding prompt into Pi's editor |
+| `r` | Rerun the current scan kind, or refresh status when no scan kind exists |
+| `c` | Start changed-files check from Overview |
+| `s` | Start full-project scan from Overview |
+| `o` | Toggle session enable/disable from Overview |
+| `?` | Open Help |
+| `q` / `Ctrl+C` | Safe close/cancel as defined above |
+
+Every action has a visible text label; color, glyphs, and punctuation are never
+the only indication of selection, disabled state, error, freshness, or relation.
+The selected row uses a textual `❯` marker plus Pi's selected background. The
+component accepts focus through the normal `Focusable` contract, propagates it
+to the search input, and requests a render after every state, selection, search,
+or async-result change.
+
+## Responsive and bounded rendering
+
+Implementation must use the callback-provided theme and ANSI-aware Pi TUI
+utilities (`visibleWidth`, `truncateToWidth`, and wrapping helpers). Every
+rendered line must have visible width less than or equal to the supplied width.
+
+- At 64 columns and wider, findings use one compact row with independently
+  middle-truncated locations and retained size/format metadata.
+- Below 64 columns, each finding uses three rows so both locations remain
+  identifiable.
+- Below 40 columns, use a compact single-column layout: short title, one action
+  or location field per line, no decorative side-by-side content, and a minimal
+  footer that always retains cancel/close guidance.
+- Height is capped at 95% of the terminal. Header and footer remain visible;
+  content scrolls within the remaining viewport. Render no more rows than the
+  current overlay viewport instead of relying on compositor truncation.
+- Paths use the existing middle-ellipsis bound and receive a second display-
+  width truncation at render time. Counts and omitted-state text remain visible.
+- Search is capped at 256 code points, findings reveal in pages of 10, the
+  overlay cache is capped at 100, inline detail at one finding, and prompt
+  handoff at 20 findings/12,000 code points. No unbounded report, list, or source
+  content enters a component.
+
+The overlay must remain closable on a 30x10 terminal. It may reduce content to a
+status line, selected action, and footer, but it must not use responsive
+`visible: false` because an invisible focused modal can strand input.
+
+## Non-TUI fallback
+
+The command must branch on `ctx.mode`, not `ctx.hasUI`: RPC reports UI capability
+but cannot render terminal components.
+
+- **RPC:** never call `ui.custom()`. Execute the existing status operation and
+  emit one non-blocking `ui.notify` request containing the bounded status plus:
+  `Use /jscpd changed, /jscpd scan, /jscpd off|on, or /jscpd help.`
+- **JSON and print:** never call `ui.custom()` and never start a duplication
+  scan. Execute the same status operation and write the same bounded plain-text
+  fallback once to stderr, preserving stdout for JSON/print output. A closed
+  stderr fails open.
+- **All non-TUI modes:** do not wait for input, create a component, alter model
+  context, or trigger a model turn. Explicit subcommands and `jscpd_run` remain
+  the machine-friendly interface.
+
+Exact fallback prefix:
+
+```text
+The /jscpd overlay requires Pi TUI mode.
+<bounded /jscpd status output>
+Use /jscpd changed, /jscpd scan, /jscpd off|on, or /jscpd help.
+```
+
+## Acceptance examples
+
+### Ready overview
+
+```text
+╭ ✦ pi-jscpd · enabled ─────────────────────────────────────────╮
+│ ✓ enabled (configuration)   jscpd 5.1.2 bundled              │
+│ Configuration built-in defaults · 3 session-changed files    │
+│ Last check 2 duplicate blocks                                │
+│                                                              │
+│ ❯ ◆ Check session changes · new blocks in tracked edits      │
+│   ◇ Scan project · all current duplicate blocks              │
+├──────────────────────────────────────────────────────────────┤
+│ ↑↓ navigate · Enter select · c changes · s scan · ? help     │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+### Findings navigator
+
+```text
+╭ ✦ pi-jscpd · 10/48 findings ─────────────────────────────────╮
+│ 10 shown   48 retained   48 total                            │
+│ Load next 10 / L · 38 cached findings remain                │
+│ ❯ ☐ ▸ N src/new.ts:12-28 ↔ E src/old.ts:44-60 · 17L/91T ts  │
+│   ☑ ▸ C lib/a.py:3-10 ↔ C lib/b.py:20-27 · 8L/42T python     │
+├──────────────────────────────────────────────────────────────┤
+│ 1 selected · ↑↓ navigate · L next 10 · Enter expand · e load│
+╰──────────────────────────────────────────────────────────────╯
+```
+
+### Component and smoke-test matrix
+
+Tests cover:
+
+- bare command opens exactly one overlay only in `mode === "tui"`;
+- RPC notification fallback and JSON/print stderr fallback start no scan;
+- loading, clean, empty, findings, disabled, missing, incompatible, timeout,
+  cancellation, failure, and stale states;
+- 100x30, 52x16, and 30x10 rendering with every line within visible width and
+  header/footer retained;
+- configured navigation plus expand/collapse, search editing/cancellation,
+  filtering/no-match, scrolling, selection, and view back behavior;
+- one active action, repeated-key suppression, cancellation propagation, late
+  completion discard, idempotent `dispose()`, and no timer/process leak;
+- both finding locations, relation labels, size, format,
+  filtered/shown/retained/total counts, 10-item manual and automatic reveal,
+  cache omissions, ambiguity, and no source fragments/fingerprints;
+- bounded prompt handoff only after overlay close, without submit or mutation;
+- no source mutation or configuration write from any overlay action; and
+- package/RPC smoke proving command discovery and non-TUI completion without a
+  hang.
+
+## Deferred from the first overlay
+
+- source preview or syntax-highlighted fragments;
+- arbitrary scan-target input;
+- mouse interaction;
+- clone-family graphs;
+- automatic refactoring, test execution, ignore-rule writes, or configuration
+  editing; and
+- persisted finding-detail caches.

package/docs/release.md

@@ -0,0 +1,115 @@
+# Release and publication policy
+
+`pi-jscpd` releases are explicitly authorized by
+[Revaz Zakalashvili](https://github.com/revazi) and published from reviewed tags
+through `.github/workflows/release.yml`. CI, issue closure, package certification,
+or CODEOWNERS review does not independently authorize a release.
+
+The first public release is `0.1.0`. The required Effect migration and
+recertification work is documented in
+[Effect architecture and conformance](effect-architecture.md).
+
+## Release gates
+
+Run the complete gate from a clean supported checkout:
+
+```text
+npm ci --ignore-scripts
+npm run release:check
+```
+
+`release:check` validates public Markdown links, repository hygiene, host
+compatibility, strict types, Biome, the network-free test suite, the exact packed
+and installed artifact, and the package dry run. CI repeats these checks on Node
+22.19.0 and 24.12.0.
+
+The manual **Release readiness (no publish)** workflow validates an exact
+40-character commit that must resolve to `origin/main`. It has read-only
+repository permission, receives no registry credential, retains no package
+artifact, and cannot publish or create a GitHub release.
+
+## Tagged publication workflow
+
+`.github/workflows/release.yml` follows the `pi-fallow` release pattern. A pushed
+`vMAJOR.MINOR.PATCH` tag starts one protected `npm` environment job that:
+
+1. checks out the complete tag history without persisting credentials;
+2. installs the pinned trusted-publishing npm version;
+3. verifies tag/package/changelog and package-lock version agreement;
+4. rejects a manifest that still has the npm `private` guard;
+5. installs locked dependencies without lifecycle scripts;
+6. reruns `npm run release:check`;
+7. publishes publicly through npm trusted publishing with provenance and
+   lifecycle scripts disabled; and
+8. creates the matching GitHub release only after npm publication succeeds.
+
+Because npm cannot attach trusted-publisher settings before an unscoped package
+exists, the `v0.1.0` publish step alone may receive a short-lived granular
+`NPM_TOKEN` repository secret for first-publication bootstrap. Dependency
+installation and release validation do not receive it, and `npm publish` runs
+with lifecycle scripts disabled. Delete the secret and remove this fallback as
+soon as npm confirms `0.1.0`; all later releases must use OIDC only. Default
+GitHub permissions are empty; the release job receives only `contents: write`
+for the GitHub release and `id-token: write` for trusted publishing.
+
+Before later tags are pushed, the repository's protected `npm` environment and
+npm trusted-publisher binding must match the exact repository and
+`.github/workflows/release.yml`. Authentication details, token values, `.npmrc`
+files, screenshots, and credential output must never be committed or copied into
+issues or CI logs.
+
+## Version and changelog procedure
+
+Published versions follow Semantic Versioning. For each approved release:
+
+1. Move relevant entries from `Unreleased` to
+   `## [MAJOR.MINOR.PATCH] - YYYY-MM-DD` and update comparison links.
+2. Update `package.json` and `package-lock.json` together.
+3. Confirm the package is publishable and `publishConfig` still requests public
+   access and provenance.
+4. Merge the reviewed release commit to `main` and wait for both supported-Node
+   CI jobs to pass on that exact commit.
+5. Run the manual non-publishing readiness workflow for the exact `main` SHA when
+   additional release evidence is required.
+6. Create one annotated `vMAJOR.MINOR.PATCH` tag on that exact commit and push it.
+7. Watch the release workflow through npm publication and GitHub Release
+   creation.
+
+Do not move a tag, publish from an unreviewed checkout, bypass a failed gate, or
+widen permissions to make a release pass.
+
+## Failure and rollback policy
+
+Before publication, any failed or ambiguous check means stop and discard or fix
+the candidate. npm versions are immutable. After publication:
+
+- never overwrite or silently replace a version;
+- verify registry name, version, integrity, provenance, and source commit;
+- deprecate a defective version with a concise migration message when needed;
+- publish a corrected patch through the full process;
+- use npm unpublish only when the maintainer determines it is necessary and
+  allowed by npm policy; and
+- coordinate security defects through GitHub private vulnerability reporting and
+  [SECURITY.md](../SECURITY.md).
+
+If GitHub Release creation fails after npm publication, verify npm first and
+create the GitHub release for the same immutable tag. Do not republish merely to
+repair release notes.
+
+## Post-release verification
+
+A release is complete only after the maintainer verifies:
+
+1. npm metadata matches the approved name/version and reports integrity and
+   provenance;
+2. a disposable project installs that exact version without lifecycle scripts;
+3. installed files match the certified allowlist;
+4. supported Pi discovers `/jscpd`, `jscpd_run`, and `/skill:jscpd` without
+   warnings in representative RPC, JSON, print, and TUI-compatible paths;
+5. the package-owned jscpd route performs a controlled real scan;
+6. damaged-analyzer behavior remains dormant and fail open;
+7. Effect interruption closes active fibers and the root scope; and
+8. shutdown leaves no child process or temporary report directory.
+
+Record only bounded pass/fail evidence, public versions, and artifact digests.
+Never retain source fragments, local paths, credentials, or environment dumps.

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "pi-jscpd",
+  "version": "0.1.0",
+  "description": "A Pi-native, polyglot duplication guardrail powered by jscpd.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Revaz Zakalashvili",
+    "url": "https://github.com/revazi"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/revazi/pi-jscpd.git"
+  },
+  "homepage": "https://github.com/revazi/pi-jscpd#readme",
+  "bugs": {
+    "url": "https://github.com/revazi/pi-jscpd/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "jscpd",
+    "code-duplication",
+    "agentic-coding"
+  ],
+  "files": [
+    "src",
+    "skills",
+    "docs",
+    "scripts/check-compatibility.mjs",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "format": "biome check --write src test scripts package.json tsconfig.json biome.json",
+    "lint": "biome check src test scripts package.json tsconfig.json biome.json",
+    "compatibility:check": "node scripts/check-compatibility.mjs",
+    "architecture:check": "node scripts/check-effect-boundaries.mjs",
+    "docs:check": "node scripts/check-markdown.mjs",
+    "repo:hygiene": "node scripts/check-repository-hygiene.mjs",
+    "check": "npm run compatibility:check && npm run architecture:check && npm run typecheck && npm run lint && npm test",
+    "pack:certify": "node scripts/package-certify.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "release:check": "npm run docs:check && npm run repo:hygiene && npm run check && npm run pack:certify && npm run pack:dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills/jscpd/SKILL.md"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.84.4 <0.85.0",
+    "typebox": ">=1.3.7 <2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.11",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
+    "@types/node": "22.20.1",
+    "typebox": "1.3.7",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "engines": {
+    "node": ">=22.19.0 <23 || >=24 <25"
+  },
+  "dependencies": {
+    "effect": "3.22.1",
+    "jscpd": "5.1.2"
+  }
+}

package/scripts/check-compatibility.mjs

@@ -0,0 +1,103 @@
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = await readJson(join(projectRoot, "package.json"));
+const expectedNodeRange = ">=22.19.0 <23 || >=24 <25";
+const expectedPiVersion = "0.84.4";
+const expectedEffectVersion = "3.22.1";
+const expectedEffectIntegrity =
+  "sha512-TNoXushmPOBAjJlthF5d2QwnX2xBPEtcNJr5XKNKbRLbDvBcOYkXlYDfvGfSA0zriwLFuCll5MDtNMAdZL17PQ==";
+const expectedJscpdVersion = "5.1.2";
+const expectedPeerRanges = Object.freeze({
+  "@earendil-works/pi-ai": ">=0.84.4 <0.85.0",
+  "@earendil-works/pi-coding-agent": ">=0.84.4 <0.85.0",
+  "@earendil-works/pi-tui": ">=0.84.4 <0.85.0",
+  typebox: ">=1.3.7 <2",
+});
+
+if (manifest.engines?.node !== expectedNodeRange) {
+  fail(`The Node engine range must remain ${expectedNodeRange}.`);
+}
+if (!supportsNode(process.versions.node)) {
+  fail(`Node ${process.versions.node} is outside the supported Node 22.19+ and Node 24 ranges.`);
+}
+
+for (const [name, range] of Object.entries(expectedPeerRanges)) {
+  if (manifest.peerDependencies?.[name] !== range) {
+    fail(`The ${name} peer range must remain ${range}.`);
+  }
+  const installed = await readJson(
+    join(projectRoot, "node_modules", ...name.split("/"), "package.json"),
+  );
+  const pinned = manifest.devDependencies?.[name];
+  if (typeof pinned !== "string" || pinned === "" || /[<>=*^~| ]/.test(pinned)) {
+    fail(`The development fixture for ${name} must be an exact version.`);
+  }
+  if (installed.version !== pinned) {
+    fail(
+      `Installed ${name} ${installed.version} does not match the ${pinned} development fixture.`,
+    );
+  }
+}
+
+for (const name of [
+  "@earendil-works/pi-ai",
+  "@earendil-works/pi-coding-agent",
+  "@earendil-works/pi-tui",
+]) {
+  if (manifest.devDependencies?.[name] !== expectedPiVersion) {
+    fail(`The tested Pi package set must remain aligned at ${expectedPiVersion}.`);
+  }
+}
+
+if (manifest.dependencies?.effect !== expectedEffectVersion) {
+  fail(`The Effect runtime dependency must remain pinned at ${expectedEffectVersion}.`);
+}
+const installedEffect = await readJson(join(projectRoot, "node_modules", "effect", "package.json"));
+if (installedEffect.version !== expectedEffectVersion || installedEffect.license !== "MIT") {
+  fail(
+    `Installed Effect ${installedEffect.version} (${installedEffect.license}) does not match the reviewed ${expectedEffectVersion} MIT runtime.`,
+  );
+}
+const lock = await readJson(join(projectRoot, "package-lock.json"));
+const lockedEffect = lock.packages?.["node_modules/effect"];
+if (
+  lock.packages?.[""]?.dependencies?.effect !== expectedEffectVersion ||
+  lockedEffect?.version !== expectedEffectVersion ||
+  lockedEffect?.integrity !== expectedEffectIntegrity
+) {
+  fail(`package-lock.json does not preserve reviewed Effect ${expectedEffectVersion} integrity.`);
+}
+
+if (manifest.dependencies?.jscpd !== expectedJscpdVersion) {
+  fail(`The bundled jscpd dependency must remain pinned at ${expectedJscpdVersion}.`);
+}
+const installedJscpd = await readJson(join(projectRoot, "node_modules", "jscpd", "package.json"));
+if (installedJscpd.version !== expectedJscpdVersion) {
+  fail(
+    `Installed jscpd ${installedJscpd.version} does not match the ${expectedJscpdVersion} runtime dependency.`,
+  );
+}
+
+console.log(
+  `Compatibility check passed: Node ${process.versions.node}, Pi ${expectedPiVersion}, TypeBox ${manifest.devDependencies.typebox}, Effect ${expectedEffectVersion}, jscpd ${expectedJscpdVersion}.`,
+);
+
+function supportsNode(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-|$)/.exec(version);
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return major === 24 || (major === 22 && minor >= 19);
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+function fail(message) {
+  console.error(`Compatibility check failed: ${message}`);
+  process.exit(1);
+}