feat: scaffold publishable package libraries

[lloydrichards]

Goals/Scope

Add a small publishable library starter under packages/, with one public entry point and no child modules. Keep publication configuration in catalog templates using the existing scaffold engine.

Description

stack-effect add --target package/sdk:package-library

The workspace package stays private and exports TypeScript source. A separate publication manifest describes the compiled npm package:

packages/sdk/
  package.json          # private workspace package
  package.publish.json  # npm metadata, exports, Effect peer
  src/index.ts
  dist/package.json     # copied publication manifest
  dist/index.js
  dist/index.d.ts

npm run pack removes stale output, compiles JavaScript and declarations, copies the manifest and documentation into dist/, and packs that directory. Publish with npm publish ./dist after inspecting the tarball.

The PR adds a publishing guide and verification. Catalog workspace authoring separates the library from domain content and excludes runtime-incompatible modules. The matrix tests alternative database providers separately.

How to Test

bun run --cwd apps/cli verify:library

This generates Bun and npm workspaces and installs their tarballs into clean consumers. It checks Node execution, NodeNext and bundler declarations, private subpath rejection, and stale-output cleanup.

Generated workspace validation and affected scoped tests passed locally.

Comments

No domain, scaffold, catalog protocol, or authoring-package changes remain. The release changeset is removed. Remaining CLI edits support catalog authoring and verification: they exclude unsupported runtimes and keep the starter separate from domain content. No new production scaffolding command is required.

Set npm metadata in package.publish.json before publishing. All CI checks passed. Pullfrog found no new issues and verified compatibility with the unchanged v1 interpreter.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
stack-effect-docs	Ready	Preview	Oct 11, 2026 4:13pm UTC

[changeset-bot]

🦋 Changeset detected

Latest commit: 206ac8c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
stack-effect	Minor
@stack-effect/author	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pullfrog]

Important

Two regressions need addressing before merging: the default Deno authoring workspace now fails, and the newly generated public-package matrix bundle contains incompatible contributions.

Reviewed changes across the library starter, catalog authoring/protocol, Plan/Apply composition, publishing documentation, and CI verification.

• Library starter: Adds a named package with one compiled ESM root export, declarations, Effect peers, and clean-before-build/prepack scripts.
• Publishing fields: Adds whole-field package.json contributions, nested token resolution, competing-contribution validation, and repository conflicts while preserving conditional-export order.
• Catalog integration: Makes shared packages public, assigns separate authoring package names to generic starters, and declares the new capability only when used.
• Documentation and verification: Adds publication guidance and clean-consumer tarball checks for generated Bun and npm workspaces.

Validation passed for affected workspace tests, verify:library, bun format, bun lint, and bun run type-check. Both findings were reproduced with isolated probes. The targeted matrix E2E run stopped earlier during init with 1 finalize script(s) failed., so its incompatible bundle was verified directly through Blueprint and Plan services instead.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes in 42bfb7e against the initial review, with the full PR diff checked for context.

• Filtered authoring modules: Excluded runtime-incompatible modules from default workspace Selection without bypassing validation for explicit requests.
• Separated matrix identities: Assigned generic package modules to package/library, keeping the library starter separate from identity-specific domain bundles.
• Added regression coverage: Tested successful default Deno Blueprint resolution and rejection of an explicitly requested unsupported library.

Both original findings are resolved. Validation passed for bun run test --filter=stack-effect, bun format, bun lint, and bun run type-check; direct Blueprint, Plan, and Apply probes passed for default Deno authoring and both package matrix selections. The standalone library and maximal domain E2E cases also passed after supplying a temporary Git author identity, which addressed the runner's initialization failure. Full Deno finalization was not exercised because Deno is unavailable in this environment.

  ^{｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes in 0a0d887c against the prior review at 42bfb7ea, with the full PR diff read for context.

• Split maximal target bundles into separate capability-provider variants, retaining the non-provider modules in each bundle.
• Honored explicit provider selections in requiredProviderSelections, preserving the first-provider fallback when no provider is selected.

Verification passed for both maximal database bundles: SQLite plus Todo Repository, and PostgreSQL plus Todo Repository. Each completed CLI generation, dependency installation, formatting, lint, type checks, and build. The PostgreSQL case exercises the selected-provider fix: adding the fallback SQLite provider would violate Blueprint's single-provider invariant.

Five additional targeted matrix cases passed: the standalone Todo Repository fallback, both explicit capability-provider cases, the standalone library, and the separate maximal domain bundle. bun run test --filter=stack-effect, bun format, bun lint, and bun run type-check also passed. E2E used temporary Git author/committer environment variables and automatically cleaned its disposable workspaces; the working tree is clean. The remaining matrix cases were not run in this review.

  ^{｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes at 7c90db8c, including the full reduced PR diff and the latest commit’s removal of the publishing-field interpreter feature.

• Scope reduction: No changes remain under domain, scaffold, catalog protocol, or authoring packages, and the release changeset is removed; the module uses only existing file and pkg-json-entry contributions.
• Publishing workflow: The workspace manifest stays private and exports source; package.publish.json is copied to dist/package.json, and npm run pack rebuilds before packing the compiled directory.
• Catalog compatibility: Generic library authoring stays separate from domain content, default Selection excludes runtime-incompatible modules, and maximal database matrix bundles select alternative providers independently.
• Documentation and verification: The publishing guide is wired into routes, navigation, Markdown assets, and headers; CI runs the clean-consumer library verifier.

verify:library passed for Bun and npm workspaces, including Node execution, NodeNext and bundler declarations, rejection of private subpaths, and stale-output cleanup. A generated-library npm publish ./dist --dry-run --json succeeded and selected only the compiled package, README, and publication manifest with public access. The exported catalog also decoded successfully with the unchanged v1 interpreter and did not declare contribution:pkg-json-field.

Validation passed for scoped CLI/catalog/scaffold tests, all four targeted matrix cases (library, maximal domain, SQLite, PostgreSQL), catalog workspace reset/validation with a clean baseline diff, docs build and 22 targeted docs/registry tests, and bun format, bun lint, and bun run type-check. Default Deno Blueprint selection and explicit unsupported-library rejection passed their regression tests; full Deno Finalize and actual registry publication were not exercised. The repository working tree is clean.

  ^{｜ View workflow run ｜ Using gpt-6.1-sol ｜ 𝕏}