fix(effect): harden v4 beta runtime boundaries

[altaywtf]

Summary

Pin vref to the reproducible Effect v4 beta.107 release, harden its Effect boundaries and scoped server lifecycle, and remove the retired Effect source-readiness workflow.

Changed

• Pin effect and @effect/platform-node to 4.0.0-beta.107 with matching pnpm lock/release-age policy. The old floating effect: beta selector was replaced because npm latest is still Effect v3 and a tag is not reproducible.
• Decode manifests through Effect Schema while preserving the published Promise APIs, VrefError(code, message), metadata, and accepted date-only/offset-less timestamps.
• Move synchronous CLI failures into typed Effects; render typed failures/defects as structured errors; preserve pure interrupts while surfacing mixed interrupt/failure causes.
• Run the CLI with canonical NodeRuntime signal handling.
• Make the HTTP server an acquired scoped resource with typed listen errors, pipeline error handling, real bound-port reporting, bounded active-client shutdown, and cancellation-safe cleanup.
• Remove scripts/prepare-effect-source.sh, .worktreeinclude, .repos/effect configuration, effect:prepare, and supporting contributor guidance. node_modules/effect/AGENTS.md and node_modules/effect/src are now the only documented Effect source path.
• Repository-wide search found no agent-readiness report, generator, or inbound report link to remove.

Review aids

flowchart LR
  A["CLI args or manifest JSON"] --> B["Typed Effect boundaries"]
  B --> C["Schema validation"]
  B --> D["Scoped HTTP server"]
  D --> E["NodeRuntime signals"]
  E --> F["Pure interrupt: exit 130"]
  E --> G["Failure or mixed cause: structured error"]
  D --> H["Scope release: stop accepts and active clients"]

Loading

The dependency/source workflow changes from a floating beta plus a vendored source clone to exact beta.107 packages plus installed-package guidance.

Risks

• @effect/platform-node brings its canonical Node runtime dependencies, including the auto-resolved ioredis peer. A fresh strict-peer consumer install and packaged CLI run passed; this weight is intentional for signal-aware runtime behavior.
• Server shutdown now terminates active local preview clients immediately when the scope closes, preventing stalled streams from hanging SIGINT/SIGTERM teardown.
• Schema error output intentionally reports all invalid paths, but installed beta.107 was verified to omit actual untrusted values.

Verification

• pnpm install --frozen-lockfile
• pnpm run verify (format/lint, typecheck, build/declarations, structured smoke, 33 tests, npm pack dry-run)
• Published @putdotio/vref@1.2.0 declarations compared byte-for-byte with rebuilt declarations
• Built CLI: HTTP 200, SIGTERM exit 130, port released
• Fresh packed consumer: pnpm --strict-peer-dependencies install and vref describe
• Claude Opus 5 autoreview in branch mode against origin/main: clean after validated fixes/dispositions

Complexity

Moderate. The public surface remains compatible; most complexity is localized to manifest decoding, the CLI runtime boundary, and server resource ownership.

[Copilot]

Pull request overview

This PR hardens @putdotio/vref’s Effect v4 beta runtime boundaries by pinning Effect dependencies, moving key runtime/CLI paths into typed Effects, and tightening server lifecycle management via scoped resources, while removing the retired “Effect source readiness” workflow.

Changes:

• Pin effect and introduce @effect/platform-node at 4.0.0-beta.107, plus related pnpm policy updates.
• Switch manifest decoding/validation to Effect Schema while preserving the existing Promise-facing surface and timestamp expectations.
• Rework serve into a scoped acquired resource with typed listen/start errors and more robust shutdown behavior; run the CLI via NodeRuntime.runMain and format boundary failures consistently.

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/vref.test.ts	Adds tests for timestamp parsing, scoped server shutdown, and CLI boundary error/interrupt behavior.
src/serve.ts	Converts HTTP server to a scoped Effect resource with typed listen/dir errors and improved request pipeline handling.
src/output.ts	Uses Effect Predicate helpers for object checks when selecting fields / computing untrusted text paths.
src/manifest.ts	Replaces hand-rolled validation with Effect Schema decoding and keeps additional semantic validation (e.g., file safety).
src/errors.ts	Reworks VrefError as an Effect Schema.TaggedError and normalizes error-to-JSON formatting.
src/cli.ts	Moves sync failures into typed Effects, scopes serve, and runs CLI under canonical NodeRuntime with cause-aware recovery.
scripts/smoke.ts	Aligns JSON “record” validation with Effect Predicate helpers.
scripts/prepare-effect-source.sh	Removes the retired Effect source preparation script.
pnpm-workspace.yaml	Adds release-age exclusions for pinned Effect beta packages.
pnpm-lock.yaml	Updates the lockfile to the pinned Effect beta.107 + platform-node dependency graph.
package.json	Pins effect and adds @effect/platform-node; removes effect:prepare script.
CONTRIBUTING.md	Removes docs for the retired Effect source preparation workflow.
AGENTS.md	Documents the new “read Effect guidance from installed package” workflow.
.worktreeinclude	Stops including the removed .repos/effect checkout path.
.gitignore	Removes ignore entry for .repos/effect since it’s no longer used.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

src/serve.ts:48

• serve is an Effect generator, but this branch currently does return yield* new VrefError(...). A VrefError is not an Effect, so this won’t typecheck/run as intended; it should fail in the typed error channel (e.g. Effect.fail(...)).

    return yield* new VrefError(
      "VREF_SERVE_DIR_NOT_DIRECTORY",
      `serve dir is not a directory: ${options.dir}`,
    );
  }

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[putio-releaser]

🎉 This PR is included in version 1.2.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀