@geenius/release-toolkit 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,335 @@
+# Changelog
+
+All notable changes to `@geenius/release-toolkit` are documented in this file.
+The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.9.2] — 2026-05-18
+
+### Fixed
+
+- **Hide optional `@playwright/test` dynamic import from consumer-side static
+  analyzers.** When a consuming package's vitest config imported anything
+  from `@geenius/release-toolkit` (e.g. `packageVariants`), vite's
+  `import-analysis` plugin tried to resolve `@playwright/test` through the
+  toolkit's dist and failed with "Failed to resolve import @playwright/test"
+  even when the consumer hadn't asked to use the storybook static-smoke
+  command at all. The dynamic import now uses a variable specifier
+  (`const s = "@playwright/test"; await import(s)`) — semantically
+  identical, but invisible to static analyzers.
+
+## [0.9.1] — 2026-05-18
+
+### Fixed
+
+- **`lint` now accepts positional passthrough args.** Previously `geenius-release
+  lint -- --error-on-warnings` rejected with "too many arguments". The command
+  now declares `[passthrough...]` and forwards everything after the options
+  (and after a literal `--`) to biome. Unblocks geenie / config migrations
+  that want to enforce `--error-on-warnings` in their gauntlets.
+
+## [0.9.0] — 2026-05-18
+
+### Added — smoke-packed UI/workspace-dep enhancements
+
+Surfaced from auditing the 34 packages each carrying their own
+~80-400 LOC `scripts/smoke-packed-imports.mjs` variants. The toolkit's
+existing `smoke-packed` already handled pack → install → import; the
+per-package divergence was all in extra checks and UI runtime mocks.
+Six additive features absorb that divergence:
+
+- **`--check-exports-on-disk`** — extract tarball + verify every declared
+  `exports[*].{types,import,default}` target file exists.
+- **`--check-tarball-purity <regex>`** — every tar entry must match the
+  pattern; reports unexpected files (catches accidental dev-asset leaks).
+- **`--check-stylesheets`** — file-exists verification for `.css` export
+  targets (no import; matters for CSS-only subpaths).
+- **`--browser-conditions`** — pass `--conditions=browser` to the import
+  probe so browser/server condition splits resolve the browser branch.
+- **`--dom-stubs`** — prepend DOM stubs (window, document, matchMedia,
+  HTMLElement, …) to the probe so UI imports with module-evaluation-time
+  DOM access don't crash.
+- **`--inject-deps <list>`** — comma-separated workspace package names to
+  symlink into the consumer's `node_modules` before the probe runs. Each
+  name resolves against the sibling packages root via the
+  `@geenius/<x>` → `<siblingsRoot>/geenius-<x>` convention. Use for
+  `link:` workspace deps that can't be satisfied from a registry.
+
+All six are also available as `release-toolkit.config.json#smokePacked`
+fields (`checkExportsOnDisk`, `checkTarballPurity`, `checkStylesheets`,
+`browserConditions`, `domStubs`, `injectDeps`); CLI flags take precedence
+per-field.
+
+Distinct from `pack-contract` (which delegates assertions to a vitest
+config) — these flags are the convention-over-configuration path for the
+common UI smoke-test shape.
+
+## [0.8.0] — 2026-05-17
+
+### Performance (major)
+
+- **`pnpm-filters` no longer shells out to pnpm.** The previous implementation
+  invoked `pnpm -r --filter ./pkg run <task>` per fan-out, paying a
+  ~100-300ms pnpm bootstrap per package. The new implementation reads each
+  variant's `package.json`, looks up `scripts.<task>`, and spawns it
+  directly via `/bin/sh -c <cmd>` in the variant's cwd with PATH augmented
+  to include every ancestor `node_modules/.bin`. Result:
+    - 16 variants × parallel mode goes from ~3-4s of pure pnpm overhead to
+      ~50ms of orchestration overhead
+    - parallel mode no longer requires pnpm to be installed at all
+    - all `package.json` script semantics (shell pipes, &&, env subst)
+      are preserved because the command body is handed to sh untouched
+
+- **`publint`, `mutation-report`, `supply-chain` (socket probe) now spawn
+  their target binaries directly** instead of `pnpm exec`. Same direct-spawn
+  pattern as 0.7.2 lint/coverage/e2e/convex-build. publint and mutation-report
+  retain `pnpm dlx` fallbacks for explicit opt-in (`--dlx <spec>`).
+
+### Internal
+
+- `PnpmFiltersResult.argv` field renamed to `invocations: {label, cwd, command}[]`.
+  CLI consumers (`cli.ts`) only read `status`, which is unchanged. Library
+  consumers parsing the report shape are affected — hence the minor bump.
+
+### Benchmarks (against geenius-logger, 4 implemented variants)
+
+  pnpm build  (sequential, --workspace-concurrency=1):
+    0.7.2  →  ~12s   (~3s pnpm bootstrap + ~9s real build)
+    0.8.0  →  ~8.8s  (~0s pnpm bootstrap + ~8.8s real build)
+
+  pnpm clean (parallel):
+    0.7.2  →  ~1.5s  (pnpm bootstrap + rm -rf dist × 3)
+    0.8.0  →  ~0.8s  (sh -c rm -rf dist × 3)
+
+  Under heavy concurrent agent workloads (10-20× parallel), the savings
+  compound — pnpm bootstrap was previously the dominant cost.
+
+## [0.7.2] — 2026-05-17
+
+### Performance
+
+- **`lint`, `coverage`, `e2e`, `convex-build` now spawn local binaries
+  directly** instead of routing through `pnpm exec`. Saves the
+  ~100-300ms pnpm bootstrap per spawn — critical when 10-20 agents
+  invoke a `geenius-release` subcommand concurrently. New helper
+  `src/lib/resolve-bin.ts` walks ancestor `node_modules/.bin` (cached
+  per-process); env-PATH augmentation lets child processes find sibling
+  bins (tsup → esbuild, vitest → workers) without further hops.
+
+### Changed
+
+- Removed all in-tree references to `@geenius-agents`. The release
+  toolkit ships as a self-contained CLI/library; downstream report
+  consumers (CI integrations, dashboards) are not named in source or
+  docs.
+
+## [0.7.1] — 2026-05-17
+
+### Added
+
+- **`bundle-budgets`** — gzip-check `<packageDir>/dist/{index.js,index.css}` against
+  each variant's `bundleBudget` declared in `variants.json`. Replaces
+  `scripts/check-bundle-budgets.mjs` (surfaced from geenius-perf). 8 packages
+  declare `bundleBudget` (perf, agent, ai-magic, devtools, errors, onboarding,
+  ui, tools-legacy); this command absorbs the pattern for all of them.
+  Flags: `--assets`, `--include-unimplemented`, `--optional`.
+
+## [0.7.0] — 2026-05-17
+
+### Added
+
+Nine new commands that absorb every standalone `scripts/*.mjs` used in 3 or more
+geenius packages. Designed to clear the per-package script tail so package
+`scripts/` directories can hold only genuinely package-unique logic. See
+`standardization-plan.md` for the full migration map.
+
+- **`lint`** — canonical biome runner. Collapses `run-lint.mjs` (9 pkgs),
+  `lint-apps.mjs` (4), `lint-scope.mjs` (3), `biome-scope.mjs` (5). Flags:
+  `--scope <package|apps|all>`, `--apps`, `--command`, `--fix`, `--print`.
+
+- **`coverage`** — canonical `vitest run --coverage` runner. Collapses
+  `run-coverage.mjs` (5). Cleans coverage dirs, runs root pass excluding
+  separate-coverage packages, then runs per-package passes. Flags:
+  `--separate-frameworks`, `--separate-package-dirs`, `--no-clean`, `--strict`.
+
+- **`e2e`** — Playwright runner with ephemeral port reservation and
+  variant-derived `--project` filters. Collapses `e2e-runner.mjs` (5) and
+  `playwright-projects.mjs` (2). Flags: `--projects`, `--all-browsers`,
+  `--browser`, `--env-prefix`, `--print`.
+
+- **`vitest-browser-prepare`** — exports `vitestBrowserPrepareRetry()` for
+  vitest configs; the CLI prints the injected script. Collapses
+  `vitest-browser-prepare-retry.ts` (4 pkgs).
+
+- **`patch-dts`** — post-build dist patcher. Collapses `patch-dts-imports.mjs`
+  (4), `patch-solid-web-import.mjs` (2). Flags: `--rewrite <from=to>`
+  (repeatable, .d.ts only), `--solid`, `--solid-jsx`, `--dir`, `--files`.
+
+- **`db-migrations`** — runs migration tests for every `db-provider` variant
+  with `tests.migrations: true`. Collapses `db-migrations-check.mjs` (4).
+
+- **`sanitize-dist`** — strips tsup source-path comments, sourcemap URLs, and
+  optionally the Solid JSX runtime import from `dist/`. Collapses
+  `sanitize-dist-comments.mjs` (3) and `sanitize-dist.mjs` (2). Flags:
+  `--no-comments`, `--maps`, `--fix-solid-jsx-runtime`, `--dir`.
+
+- **`convex-codegen`** — generates `_generated/{server,api,dataModel}` shims
+  for Convex variants. Promotes the bin previously shipped from
+  `geenius-db`'s convex sub-package. Flags: `--src`, `--check`, `--clean`.
+
+- **`convex-build`** — Convex sub-package build = `convex-codegen` + `tsup`.
+  One implementation for the 16 packages carrying `convex.config.ts`. Flags:
+  `--src`, `--no-codegen`, `--no-build`, `--clean`, `--builder <tsup|tsc>`.
+
+## [0.6.1] — 2026-05-17
+
+### Fixed
+
+- **`pnpm-filters` CLI now exposes `--requires` and `--mode`**. The 0.6.0 release wired both options into the `runPnpmFilters` library API but forgot to register them on the CLI definition, so `geenius-release pnpm-filters … --mode shared-then-parallel` rejected the flag. Both flags now work as documented.
+- **`storybook --runner test-runner` no longer passes the invalid `--static-dir` flag** to `@storybook/test-runner`. The toolkit now spins up an ephemeral static file server on a free port, points the runner at it via `--url http://127.0.0.1:<port>`, and tears the server down after the run completes.
+
+## [0.6.0] — 2026-05-17
+
+### Added
+
+- **`variants check`** subcommand — verifies every required variant has an on-disk `packageDir`. With `--require-all`, every variant is required regardless of `required:false`. Replaces ad-hoc `variants-check.mjs` shims.
+- **`pnpm-filters --requires <names>`** — verify a comma-separated list of binaries is on PATH before fanning out. Fails fast with a clear error instead of a confusing per-variant spawn failure.
+- **`pnpm-filters --mode shared-then-parallel`** — run a single shared package first (e.g. `packages/shared`) and then fan the rest out in parallel. Replaces hand-written shared-first wrappers that called pnpm twice.
+- **`mutation-report --check-config-only`** — validate Stryker config without running mutations. For CI gates that want to ensure config drift is caught early.
+- **`mutation-report --dlx <spec>`** — fall back to `pnpm dlx <spec>` when Stryker isn't installed locally. Lets packages opt into mutation testing without committing the dependency.
+- **`mutation-report --markdown <path> --json <path> --report-json <path>`** — emit derived reports alongside the raw Stryker output, with fallback score computation when Stryker's summary fails.
+- **`attw --safe-pack-dir <path>`** — reuse a stable dir (relative to `packageRoot`) instead of mkdtemp for the tarball. Useful when CI caches need a deterministic path.
+- **`diff-coverage --min-ci <pct>` and `--min-local <pct>`** — CI-conditional thresholds. Common pattern: 0 locally, strict in CI, so contributors aren't blocked but coverage regressions still fail the pipeline.
+- **`storybook --runner test-runner|vitest|static-smoke`** — pick between `@storybook/test-runner`, Vitest browser-mode runner, or the original Playwright static smoke. Replaces 3 categories of per-package storybook smoke scripts.
+- **`rewrite-imports --preset solid-web`** — built-in preset that rewrites `solid-js/web` to `solid-js/web/dist/web.js` so Node ESM consumers can resolve it without subpath redirects. Replaces per-Solid-package rewrite shims.
+
+### Changed
+
+- **`variants-rich`** now understands `packagePath` as a fallback for `packageDir`, plus top-level `workspacePackages` arrays. Lets packages that follow either convention (admin's bare-name `react`, or ai-workflow's separate `workspacePackages`) consume the toolkit without rewriting their `variants.json`.
+
+## [0.5.0] — 2026-05-17
+
+### Added
+
+- **`run-scripts <s1> <s2> …`** + `runScripts` API — run multiple top-level `package.json` scripts sequentially in the package root, with PATH augmented to `node_modules/.bin` and `npm_package_*` env vars set. Stops on first failure (or `--continue-on-failure`). Replaces local `_run-root-scripts.mjs` shims used to chain build/test/exports/dist-contract.
+- **`type-check`** + `runTypeCheck` API — per-variant runner with a `type-check → lint → tsc --noEmit` fallback chain. Augments PATH with the variant's and root's `node_modules/.bin`. Honors `--shared-first`, `--continue-on-failure`, `--exclude-out-of-scope`. Replaces `scripts/type-check-packages.mjs`.
+- **`size-limit-config`** + `runSizeLimitConfig` API — emit size-limit entries to stdout, derived from `variants.json` `budget.gzip` and the root manifest's `exports` map. Enforces that every exported package has a `budget.gzip`. Replaces ~5 copies of per-package `size-limit-config.mjs`.
+- **`pack-contract`** + `runPackContract` API — generic harness: `pnpm pack --json` into a tmp dir, expose path via `PACK_CONTRACT_JSON` env, run a consumer-supplied `vitest --config <path>`. Replaces local `pack-contract.mjs` shims.
+
+### Changed
+
+- **`pnpm-filters` gains sequential mode**. New flags: `--sequential`, `--shared-first <packageDir>`, `--heartbeat-ms <ms>`, `--kind-order <tiers>` (pipe-separated tiers, comma-separated kinds). Sequential mode walks variants one at a time, runs `packages/shared` first when requested, skips packages that don't declare the script, emits a heartbeat line every N ms so CI doesn't kill a quiet job. The default parallel mode is unchanged. Replaces 43 copies of `_pnpm-filters.mjs` and the package-specific shared-first variants in adapters/admin/agent/ai.
+- **`runPnpmFilters` is now `async`**. The signature returns `Promise<PnpmFiltersResult>` because the sequential path uses `spawn` to run the heartbeat alongside the child process. Parallel callers must `await` the result (no behavior change otherwise). The CLI was already async, so no user-facing change.
+- **`coverage-report` accepts per-subpackage thresholds**. New flags: `--threshold-file <path>`, `--output <path>` (Markdown), `--json <path>` (structured), `--fail-on-gaps`. The threshold file shape is `{ subpackages: { <name>: { thresholds: { lines, statements, branches, functions }, required?, kind? } } }`. The toolkit walks per-subpackage `coverage-summary.json` files under `packages/<name>/coverage/`, computes pass/fail per metric, and writes Markdown + JSON reports. Replaces the 36-script category for packages whose call sites use these flags.
+- **`storybook` gains variant-driven discovery + shape check**. New flags: `--from-variants` (read app list from `variants.json` instead of auto-globbing `apps/storybook-*`), `--variants-scope <all|published>`, `--check-shape <jsonOrPath>` (asserts `requiredFiles`/`forbiddenFiles`/`requiredTitles` per app). Replaces variant-filtered `storybook-build.mjs` and `storybook-vitest-runner.mjs` shims, plus per-package `storybook-app-smoke.mjs`.
+
+### Migration
+
+`runPnpmFilters` is now async. If you import it as a library, `await` the call. CLI users see no change.
+
+## [0.4.0] — 2026-05-17
+
+### Fixed
+
+- **`smoke-packed` no longer swallows the npm install error.** The `--silent` flag was suppressing the stderr stream the `link:`/`workspace:` fallback regex depended on, producing "npm install exited 1" with empty `output` and forcing every Geenius package to ship its own `smoke-packed-imports.mjs` workaround (~36 copies, ~286 LOC each). The install now runs without `--silent`, falls back to `pnpm add` unconditionally on exit≠0, and reports the combined stderr from every attempt.
+
+### Added
+
+- **`publint` source-time `link:` tolerance.** When publint reports diagnostics of the form `The "X" dependency references "link:..."` for `X` declared in the manifest and matching `publint.sourceLinkScope` (default `^@geenius/`), the toolkit treats the run as passed. The semver rewrite that converts these to ranges still happens at publish time. Config: `publint.allowSourceTimeLinks` (default `true`), `publint.sourceLinkScope`. Replaces ~25 per-package `lint-pub.mjs` / `publint-package.mjs` wrappers.
+- **Gauntlet sibling-dist freshness pre-check.** Before running the first step, the gauntlet walks every `link:` `@geenius/*` dep, verifies its `dist/index.js` + `dist/index.d.ts` are newer than its `src/`, and either fails (`siblingDistFreshness: "check"`, default) or auto-builds (`siblingDistFreshness: "build"`). Eliminates the recurring TS7016 "cannot resolve declarations" failures inside nested gauntlet runs.
+- **`geenius-release variants [list|missing|published-subpaths|ui|db|storybook-apps]`** + a programmatic `loadRichVariants` / `packageVariants` / `uiVariants` / `storybookApps` / `publishedSubpaths` API. Reads `variants.json`, honors `OMEGA_INCLUDE_OUT_OF_SCOPE`, returns derived `packagePath` / `exists` / `subpaths` fields. Replaces 43 copies of `scripts/_variants.mjs`.
+- **`geenius-release pnpm-filters <task> [...passthrough]`** + `runPnpmFilters` programmatic API. Builds `pnpm -r --filter ./packages/<X>` invocations from the active variant matrix. Replaces 43 copies of `scripts/_pnpm-filters.mjs`.
+- **`geenius-release storybook --static-smoke <replace|after|only>`** runs the toolkit's built-in Playwright + http-server smoke against `apps/*/storybook-static`. Visits every indexed story under headless Chromium, asserts `#storybook-root` is non-empty, fails on page errors. `@playwright/test` is loaded lazily; if the consuming package doesn't have it the step reports a clear missing-peer error. Replaces ~30 copies of `storybook-runner.mjs` / `storybook-test-runner.mjs` / `test-storybook-static.mjs` that agents had to keep reinventing after Storybook's Vitest browser addon kept hanging.
+
+## [0.3.4] — 2026-05-16
+
+### Added
+
+- `rewrite-imports` now supports `deriveFromExports: true` (config + `--derive-from-exports` CLI flag). When set, the toolkit reads the root manifest's `exports` map, walks `packages/<name>/package.json` for each referenced variant, and generates one literal rule per private→public pair (e.g. `@geenius/i18n-react` → `@geenius/i18n/react`). Replaces hand-rolled scripts like i18n's `patch-dts-imports.mjs` (~129 LOC). Derived rules are appended after explicit `rules`.
+
+## [0.3.3] — 2026-05-16
+
+### Added
+
+- `rewrite-imports` rules now support a `literal: true` flag — when set, `replaceWith` is treated as literal text instead of a path-relative-to-packageRoot. Useful for JSDoc / comment cleanup ("internal-name → public-name") where there's no file to resolve against.
+- `rewrite-imports` rules now support a `quoted: true` flag — when set, only quoted occurrences are matched (both `"<match>"` and `'<match>'`). Use this for specifier rewrites that must not touch identical strings in JSDoc / comments.
+- `rewriteImports.extensions` config (and `extensions` option on the programmatic API) — list of file extensions to rewrite. Defaults to `[".js", ".d.ts"]`. Packages emitting `.cjs`/`.cts`/`.mjs` can now opt in.
+
+## [0.3.2] — 2026-05-16
+
+### Fixed
+
+- **`loadConfig` now walks up from a subdirectory** to find the package root before reading `release-toolkit.config.json`. Previously, when a CLI command was invoked from a variant subdirectory (e.g. a per-variant build script chaining `tsup && geenius-release rewrite-imports packages/<variant>`), the config was silently missed because `loadConfig` joined `release-toolkit.config.json` onto the raw cwd. Affected every command that reads config — most visibly `rewrite-imports`, where the resulting `no rules configured` skip silently let private specifiers leak into dist. The CLI now calls `resolvePaths(startCwd).packageRoot` first.
+
+## [0.3.1] — 2026-05-16
+
+### Added
+
+- `rewrite-imports <variant-dir>` — post-build codemod that rewrites private subpath imports (e.g. `@geenius/<pkg>/shared/react`) in a variant's built `dist/` into relative dist paths, so packed tarballs don't need to expose internal `./shared` exports. Replaces ~36 copies of `rewrite-private-imports.mjs` (≈ 2,800 LOC). Token-aware rules (`${packageName}`, `${framework}`, `${variant}`) configured under `rewriteImports` in `release-toolkit.config.json`, or supplied inline via repeatable `--rule <match>=<replaceWith>`. Auto-detects framework from variant basename (`solidjs*` → `solidjs`, else `react`); overridable via `--framework` or `rewriteImports.frameworkDetect` regex map.
+
+### Fixed
+
+- `manifest-contract`: replace hand-rolled glob with picomatch so `files` patterns like `packages/*/dist/**/*` correctly cover exports/main/types targets.
+- `size-check`: default to optional (mirrors `mutation-report`); CLI flag flipped from `--optional` to `--required`. Packages without `size-limit` configured no longer break the gauntlet.
+- `smoke-packed`: when `npm install` of the packed tarball fails due to unresolved `link:`/`workspace:` deps, retry with `pnpm add` so monorepo packages with workspace siblings can be smoke-tested end-to-end.
+
+## [0.3.0] — 2026-05-16
+
+### Added
+
+- **4 new subcommands**, taking the surface from 11 → 15 and completing every legacy-script category:
+  - `diff-coverage` — changed-line coverage diff vs a git base ref. Parses `git diff --unified=0 <base>...HEAD`, walks istanbul `coverage-final.json`, enforces `--min` (default 80%). Replaces 22 copies of `diff-coverage.mjs`.
+  - `manifest-contract` — verify `package.json:main/types/module/exports/bin` resolve on disk, `bin` entries are executable + have shebangs, and `files` patterns cover every export target. Absorbs the `test -f dist/index.js` inline checks scattered across the ecosystem (e.g. tools/devtools' `test:dist-contract`).
+  - `storybook` — build + test-run every Storybook app declared (or auto-discovered under `apps/storybook-*`). Replaces ~28 scripts across 5 filename variations (`storybook-runner.mjs`, `storybook-test-runner.mjs`, `test-storybook-static.mjs`, `storybook-build.mjs`, `storybook-apps.mjs`).
+  - `perf-smoke` — enforce perf budgets against `.eval/perf/results.json`. Supports both array `[{ metric, value }]` and object `{ metric: value }` result formats; reads budgets from `perf-budgets.json` if no inline config. Replaces 7 copies.
+- Each new command exported from the programmatic API (`runDiffCoverage`, `runManifestContract`, `runStorybook`, `runPerfSmoke`).
+- Gauntlet integration: all 4 new commands are recognized internal steps.
+
+### Cumulative absorption
+
+The toolkit now replaces approximately **260+ legacy `scripts/*.mjs` files** across the ecosystem (≈ 49,000 LOC of duplication). Every category of release-gate script identified in the original audit has a corresponding canonical subcommand.
+
+## [0.2.0] — 2026-05-16
+
+### Added
+
+- **6 new subcommands** absorbing ~80 more legacy `scripts/*.mjs` files across the ecosystem:
+  - `publint` — run publint against the packed tarball. Replaces 4 filename variations (~17 copies).
+  - `attw` — run `@arethetypeswrong/cli` against the packed tarball. Replaces 3 filename variations (~13 copies).
+  - `size-check` — size-limit driver. Replaces 13 copies.
+  - `coverage-report` — aggregate `coverage-summary.json` and enforce per-metric thresholds. Replaces 36 copies. Reads `coverage-thresholds.json` if present.
+  - `mutation-report` — Stryker driver. Optional by default. Replaces 36 copies.
+  - `a11y-report` — aggregate axe-core results from `.eval/a11y/results.json` and enforce a severity threshold. Replaces 28 copies.
+- **Programmatic API** for every new subcommand: `runPublint`, `runAttw`, `runSizeCheck`, `runCoverageReport`, `runMutationReport`, `runA11yReport`.
+- **Gauntlet integration**: every new subcommand is a recognised internal step in `geenius-release gauntlet`.
+- **`$schema` allowed in `release-toolkit.config.json`** so editors get JSON-schema autocomplete (no runtime effect).
+- **Repository infrastructure** to match the rest of the geenius ecosystem:
+  - `LICENSE` file (FSL-1.1-Apache-2.0)
+  - `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`, `SUPPORT.md`
+  - `.github/CODEOWNERS`, `dependabot.yml`, `PULL_REQUEST_TEMPLATE.md`, issue templates
+  - `.github/workflows/ci.yml` (PR + nightly with `osv-scanner` install + Socket strict mode)
+  - `.github/workflows/release.yml` (changesets-driven publish)
+  - `.changeset/config.json`
+  - `.nvmrc`
+- `@changesets/cli` added to devDependencies; `publint` and `@arethetypeswrong/cli` added so the toolkit's own gauntlet can run them.
+
+### Changed
+
+- `tsup.config.ts` scopes `dts` generation to the `index` entry only — `cli.ts` is a script, not a typed-library entry, so an empty `.d.ts` is no longer emitted.
+- Package exports now include `default` alongside `import` for stricter ESM-only resolver tolerance.
+
+### Known issues
+
+- **`attw` crashes with `Cannot read properties of undefined (reading 'filename')`** when run against the toolkit's own packed tarball under `@arethetypeswrong/cli@0.18.2`. The same attw version works correctly on every other geenius package; the toolkit's own bootstrap dogfood gauntlet excludes `attw` until the upstream issue is resolved. The toolkit itself is unaffected — running `geenius-release attw` against consumer packages works as designed.
+
+## [0.1.0] — 2026-05-15
+
+Initial greenfield release. See the git history of this file for the original v0.1 entry.
+
+### Added
+
+- CLI `geenius-release` with subcommands `supply-chain`, `license`, `sbom`, `smoke-packed`, `gauntlet`.
+- Programmatic API exports for every subcommand.
+- `release-toolkit.config.json` schema (Zod) with sensible defaults.
+- Env overrides (`GEENIUS_SUPPLY_CHAIN_<SCANNER>=off|optional|required`, `GEENIUS_RELEASE_STRICTNESS`, `SOCKET_API_TOKEN`).
+- Stable exit codes (0–4) and stable JSON report shape.

package/LICENSE

@@ -0,0 +1,88 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+FSL-1.1-Apache-2.0
+
+Notice
+
+Copyright 2026 Mehdi Nabhani
+
+License
+
+Terms and Conditions
+
+Licensor ("We") provides the Software described in the Notice, and reserves
+all rights in it other than those expressly granted in this License.
+
+Permitted Purpose means any purpose other than a Competing Use. A Competing
+Use means making the Software available to third parties as a hosted or
+managed service, where the service provides users with access to any
+substantial set of the features or functionality of the Software. Permitted
+Purpose expressly includes any internal use by employees and contractors of
+your business, and use by your customers that is limited to interactions
+with your products and services.
+
+License Grant
+
+Subject to your compliance with this License, We grant you a non-exclusive,
+royalty-free, worldwide, non-sublicensable, non-transferable license to
+use, copy, distribute, make available, and prepare derivative works of the
+Software, in each case subject to the limitations and conditions below.
+
+Limitations
+
+You may not make any use of the Software that competes with Our business.
+That includes (without limitation) offering the Software as a hosted or
+managed service to third parties.
+
+You may not move, change, disable, or circumvent any license key functionality
+in the Software, and you may not remove or obscure any functionality in the
+Software that is protected by a license key.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe
+Our patents, the license grant above includes a license under Our patents.
+If you make a claim against any party that the Software infringes or
+contributes to the infringement of any patent, then your patent license to
+the Software ends immediately.
+
+Redistribution
+
+The Terms and Conditions of this License apply to any copy, modification,
+or derivative work of the Software that you distribute. You must include
+a copy of this License with every such copy, and you must retain all
+copyright, trademark, and attribution notices.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND,
+INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR
+A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+ERROR-FREE.
+
+IN NO EVENT WILL WE BE LIABLE TO YOU FOR ANY DAMAGES ARISING OUT OF OR
+RELATED TO THIS LICENSE, INCLUDING DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+CONSEQUENTIAL, OR PUNITIVE DAMAGES, EVEN IF WE HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+Future License
+
+On the second anniversary of the date the Software is first distributed
+under this License, the Software will automatically also be made available
+under the Apache License, Version 2.0 (the "Future License"). You may, at
+your option, continue to use the Software under the terms of this License,
+or you may use the Software under the terms of the Future License.
+
+Your compliance with the Future License is a condition of your receiving
+the Software under that license.
+
+The Future License text is available at:
+https://www.apache.org/licenses/LICENSE-2.0
+
+Trademarks
+
+Except for the limited use required to comply with the Notice section
+above or as required by the redistribution terms, this License does not
+grant you any right in any trademark, service mark, or logo of Ours.

package/README.md

@@ -0,0 +1,104 @@
+# @geenius/release-toolkit
+
+> Canonical release toolkit for every Geenius package and boilerplate. One CLI (`geenius-release`) replaces the per-package supply-chain / license / SBOM / smoke-packed / gauntlet scripts that previously lived as 26–36 hand-copied duplicates.
+
+**Dev-only.** Add to `devDependencies`; never appears in your runtime bundle.
+
+```bash
+pnpm add -D @geenius/release-toolkit
+```
+
+## Quick start
+
+Wire the canonical scripts into your `package.json`:
+
+```jsonc
+{
+  "scripts": {
+    "audit:supply-chain": "geenius-release supply-chain",
+    "audit:license":      "geenius-release license",
+    "audit:sbom":         "geenius-release sbom",
+    "test:smoke-packed":  "geenius-release smoke-packed",
+    "test:gauntlet":      "geenius-release gauntlet"
+  }
+}
+```
+
+No config file required — the toolkit ships ecosystem-sensible defaults. Add `release-toolkit.config.json` next to `package.json` to override.
+
+## Subcommands (v0.1)
+
+| Subcommand | Replaces | Description |
+| --- | --- | --- |
+| `supply-chain` | 26 per-package scripts | pnpm audit + osv-scanner + Socket + license, all required/optional configurable |
+| `license` | 36 copies of `license-check.mjs` | Forbidden-license scan over installed deps |
+| `sbom` | 36 copies of `sbom.mjs` | CycloneDX 1.5 JSON SBOM (optional SPDX via `syft`) |
+| `smoke-packed` | 36 copies of `smoke-packed-imports.mjs` | Pack, install, dynamic-import every subpath in `package.json:exports` |
+| `gauntlet` | The `&&`-chained `pnpm test:gauntlet` macro | Compose the configured step sequence into one structured report |
+
+v0.2 adds `coverage-report`, `diff-coverage`, `mutation-report`, `a11y-report`, `size-check`. v0.3 adds `storybook`, `publint`, `attw`, `perf-smoke`.
+
+## Opting out of Socket
+
+Socket requires a free account. To opt out:
+
+```jsonc
+{
+  "supplyChain": {
+    "scanners": { "socket": { "required": false } }
+  }
+}
+```
+
+`required: false` is the default for every boilerplate. Internal `@geenius/*` packages opt-in to strict mode in CI via `SOCKET_API_TOKEN`. Env override for one-off CI runs:
+
+```bash
+GEENIUS_SUPPLY_CHAIN_SOCKET=off geenius-release supply-chain
+```
+
+## Configuration reference
+
+See [`.docs/DOCS/PACKAGES/RELEASE_TOOLKIT.md`](../../.docs/DOCS/PACKAGES/RELEASE_TOOLKIT.md) for the full config schema and examples, and [`.docs/PRDS/packages/PACKAGE_RELEASE_TOOLKIT_PRD.md`](../../.docs/PRDS/packages/PACKAGE_RELEASE_TOOLKIT_PRD.md) for the design rationale.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Required steps passed (optional steps may have skipped) |
+| `1` | At least one required step failed |
+| `2` | Configuration error |
+| `3` | Environment error (missing pnpm, missing lockfile) |
+| `4` | Internal toolkit bug |
+
+Stable across versions. CI integrations can rely on them.
+
+## Optional git hooks
+
+The toolkit ships a non-blocking pre-push hook template at `templates/husky/pre-push`. It runs `pnpm run audit:supply-chain` before each push and reports findings without blocking the push (remove the trailing `|| exit 0` in the script to make findings blocking).
+
+Install per-repo:
+
+```bash
+cp node_modules/@geenius/release-toolkit/templates/husky/pre-push .husky/pre-push
+chmod +x .husky/pre-push
+```
+
+The hook is not auto-installed by adding the toolkit as a dependency — adoption is opt-in.
+
+## Reports
+
+Every subcommand writes a JSON report at `.eval/release-toolkit/<command>.json`. The shape is documented in [`src/types.ts`](./src/types.ts) and is consumed by CI integrations and downstream report aggregators.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+pnpm lint
+pnpm exec geenius-release gauntlet   # dogfood
+```
+
+## License
+
+FSL-1.1-Apache-2.0

package/bin/geenius-release.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Entry shim. The real CLI lives in ./dist/cli.js; this file exists so
+// `bin` resolution lands on a stable, sourcemapped path without exposing
+// the dist layout to consumers.
+import("../dist/cli.js");