@regardio/dev 2.4.0 → 2.5.0

package/dist/bin/ship/hotfix.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, c as runScript, i as getWorkspacePackages, n as chooseForEach, o as gitRead, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, s as runPackageRelease, t as branchExists } from "./utils-BPxpSgv6.mjs";
 //#region src/bin/ship/hotfix.ts
 /**
 * ship-hotfix: Manage hotfix branches based on production code.
@@ -52,6 +52,8 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 			console.error("Working directory has uncommitted changes. Commit or stash them first.");
 			process.exit(1);
 		}
+		console.log("\nFetching latest state from origin...");
+		git("fetch", "origin");
 		console.log("\nRunning quality checks...");
 		try {
 			runQualityChecks();
@@ -61,29 +63,21 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		}
 		console.log("✅ Quality checks passed");
 		const packages = getWorkspacePackages(cwd);
-		if (packages.length === 0) {
-			console.error("No publishable workspace packages found.");
-			process.exit(1);
-		}
-		console.log("\nSelect a version bump for each package (or skip):");
-		const bumps = chooseForEach(packages);
-		if (bumps.length === 0) {
-			console.log("\nNo packages selected for release. Aborted.");
-			process.exit(0);
-		}
-		console.log("\nBumping versions and updating CHANGELOGs...");
-		for (const { package: pkg, bump } of bumps) {
-			const originalCwd = process.cwd();
-			process.chdir(pkg.path);
-			try {
-				runScript(`--filter-root release:${bump}`);
+		const bumps = [];
+		if (packages.length > 0) {
+			console.log("\nSelect a version bump for each package (or skip):");
+			bumps.push(...chooseForEach(packages));
+			if (bumps.length === 0) {
+				console.log("\nNo packages selected for release. Aborted.");
+				process.exit(0);
+			}
+			console.log("\nBumping versions and updating CHANGELOGs...");
+			for (const { package: pkg, bump } of bumps) try {
+				runPackageRelease(pkg.path, bump);
 			} catch {
-				runScript(`commit-and-tag-version ${bump === "patch" ? "" : `--release-as ${bump}`}`);
+				console.log(`No versioning configured for ${pkg.name} — skipping.`);
 			}
-			process.chdir(originalCwd);
-		}
-		console.log("\nFetching latest state from origin...");
-		git("fetch", "origin");
+		} else console.log("No publishable packages — skipping versioning.");
 		console.log("\nMerging hotfix into production...");
 		git("checkout", "production");
 		git("pull", "--ff-only", "origin", "production");
@@ -103,9 +97,11 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		try {
 			git("push", "origin", "--delete", currentBranch);
 		} catch {}
-		const shipped = bumps.map((b) => b.package.name).join(", ");
-		console.log(`\n✅ Hotfix ${shipped} shipped to production → staging → main`);
-		console.log("CI will publish changed packages to npm.");
+		if (bumps.length > 0) {
+			const shipped = bumps.map((b) => b.package.name).join(", ");
+			console.log(`\n✅ Hotfix ${shipped} shipped to production → staging → main`);
+			console.log("CI will publish changed packages to npm.");
+		} else console.log("\n✅ Hotfix shipped to production → staging → main.");
 		console.log("You are on main and ready to keep working.");
 		process.exit(0);
 	}

package/dist/bin/ship/production.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, c as runScript, i as getWorkspacePackages, n as chooseForEach, o as gitRead, r as confirm, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, r as confirm, s as runPackageRelease, t as branchExists } from "./utils-BPxpSgv6.mjs";
 //#region src/bin/ship/production.ts
 /**
 * ship-production: Promote main to production following the GitLab workflow.
@@ -42,21 +42,6 @@ function runShipProduction(cwd = process.cwd()) {
 	}
 	console.log("\nCommits to be shipped to production:");
 	console.log(ahead);
-	const packages = getWorkspacePackages(cwd);
-	if (packages.length === 0) {
-		console.error("No publishable workspace packages found.");
-		process.exit(1);
-	}
-	console.log("\nSelect a version bump for each package (or skip):");
-	const bumps = chooseForEach(packages);
-	if (bumps.length === 0) {
-		console.log("\nNo packages selected for release. Aborted.");
-		process.exit(0);
-	}
-	if (!confirm(`\nShip to production?\n${bumps.map((b) => `  ${b.package.name}  →  ${b.bump}`).join("\n")}\n`)) {
-		console.log("Aborted.");
-		process.exit(0);
-	}
 	console.log("\nRunning quality checks on main...");
 	try {
 		runQualityChecks();
@@ -65,17 +50,26 @@ function runShipProduction(cwd = process.cwd()) {
 		process.exit(1);
 	}
 	console.log("✅ Quality checks passed");
-	console.log("\nBumping versions and updating CHANGELOGs...");
-	for (const { package: pkg, bump } of bumps) {
-		const originalCwd = process.cwd();
-		process.chdir(pkg.path);
-		try {
-			runScript(`--filter-root release:${bump}`);
+	const packages = getWorkspacePackages(cwd);
+	const bumps = [];
+	if (packages.length > 0) {
+		console.log("\nSelect a version bump for each package (or skip):");
+		bumps.push(...chooseForEach(packages));
+		if (bumps.length === 0) {
+			console.log("\nNo packages selected for release. Aborted.");
+			process.exit(0);
+		}
+		if (!confirm(`\nShip to production?\n${bumps.map((b) => `  ${b.package.name}  →  ${b.bump}`).join("\n")}\n`)) {
+			console.log("Aborted.");
+			process.exit(0);
+		}
+		console.log("\nBumping versions and updating CHANGELOGs...");
+		for (const { package: pkg, bump } of bumps) try {
+			runPackageRelease(pkg.path, bump);
 		} catch {
-			runScript(`commit-and-tag-version ${bump === "patch" ? "" : `--release-as ${bump}`}`);
+			console.log(`No versioning configured for ${pkg.name} — skipping.`);
 		}
-		process.chdir(originalCwd);
-	}
+	} else if (!confirm("\nNo publishable packages — ship commits to production?\n")) process.exit(0);
 	console.log("\nMerging main into production...");
 	git("checkout", "production");
 	git("pull", "--ff-only", "origin", "production");
@@ -88,8 +82,10 @@ function runShipProduction(cwd = process.cwd()) {
 	git("push", "origin", "staging");
 	git("checkout", "main");
 	git("push", "--follow-tags", "origin", "main");
-	const shipped = bumps.map((b) => b.package.name).join(", ");
-	console.log(`\n✅ Shipped ${shipped} to production. CI will publish changed packages to npm.`);
+	if (bumps.length > 0) {
+		const shipped = bumps.map((b) => b.package.name).join(", ");
+		console.log(`\n✅ Shipped ${shipped} to production. CI will publish changed packages to npm.`);
+	} else console.log("\n✅ Commits shipped to production.");
 	console.log("You are on main and ready to keep working.");
 }
 //#endregion

package/dist/bin/ship/staging.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, o as gitRead, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, o as gitRead, t as branchExists } from "./utils-BPxpSgv6.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/bin/ship/staging.ts

package/dist/bin/ship/{utils-rnvdLrkF.mjs → utils-BPxpSgv6.mjs}

@@ -19,6 +19,13 @@ const runScript = (script) => {
 	console.log(`$ pnpm ${script}`);
 	execSync(`pnpm ${script}`, { stdio: "inherit" });
 };
+const runPackageRelease = (pkgPath, bump) => {
+	console.log(`$ commit-and-tag-version --release-as ${bump}`);
+	execSync(`pnpm exec commit-and-tag-version --release-as ${bump}`, {
+		cwd: pkgPath,
+		stdio: "inherit"
+	});
+};
 const runQualityChecks = () => {
 	runScript("lint");
 	runScript("typecheck");
@@ -120,4 +127,4 @@ const choose = (prompt, options, ttyPath = "/dev/tty") => {
 	return chosen.value;
 };
 //#endregion
-export { git as a, runScript as c, getWorkspacePackages as i, chooseForEach as n, gitRead as o, confirm as r, runQualityChecks as s, branchExists as t };
+export { git as a, runQualityChecks as c, getWorkspacePackages as i, chooseForEach as n, gitRead as o, confirm as r, runPackageRelease as s, branchExists as t };

package/dist/playwright/index.d.mts

@@ -10,9 +10,9 @@ interface BuildPlaywrightBaseConfigParams {
   webServerCommand: string;
 }
 /**
-* Build a base Playwright config object with Regardio defaults.
-* Consumers should wrap with defineConfig() in their local playwright.config.ts
-*/
+ * Build a base Playwright config object with Regardio defaults.
+ * Consumers should wrap with defineConfig() in their local playwright.config.ts
+ */
 declare function buildPlaywrightBaseConfig({
   appUrl,
   appPort,

package/dist/vitest/node.d.mts

@@ -1,11 +1,11 @@
 //#region src/vitest/node.d.ts
 /**
-* Base Vitest configuration for Node.js packages.
-* Use with defineConfig() in your vitest.config.ts
-*/
+ * Base Vitest configuration for Node.js packages.
+ * Use with defineConfig() in your vitest.config.ts
+ */
 declare const vitestNodeConfig: {
   coverage: {
-    provider: "v8";
+    provider: 'v8';
     thresholds: {
       branches: number;
       functions: number;

package/dist/vitest/react.d.mts

@@ -1,11 +1,11 @@
 //#region src/vitest/react.d.ts
 /**
-* Vitest configuration for React packages with jsdom environment.
-* Use with defineConfig() in your vitest.config.ts
-*/
+ * Vitest configuration for React packages with jsdom environment.
+ * Use with defineConfig() in your vitest.config.ts
+ */
 declare const vitestReactConfig: {
   coverage: {
-    provider: "v8";
+    provider: 'v8';
     thresholds: {
       branches: number;
       functions: number;

package/docs/en/tools/biome.md

@@ -11,7 +11,7 @@ area: "dev"
 
 # Biome
 
-[Biome](https://biomejs.dev/) is the linter and formatter every Regardio package reaches for. Configuration is centralised through `@regardio/dev`, and wrapper commands keep every package behaving the same way.
+[Biome](https://biomejs.dev/) is the linter and formatter every Regardio package reaches for. Configuration is centralised through `@regardio/dev`.
 
 ## Configuration
 
@@ -29,34 +29,22 @@ A `biome.jsonc` at the package root is all it takes:
 ```json
 {
   "scripts": {
-    "fix": "exec-s fix:pkg fix:md fix:biome",
-    "fix:biome": "lint-biome check --write --unsafe .",
-    "lint": "exec-s lint:md lint:biome",
-    "lint:biome": "lint-biome check ."
+    "fix:biome": "biome check --write --unsafe .",
+    "lint:biome": "biome check ."
   }
 }
 ```
 
-## CLI wrapper
-
-Use `lint-biome` rather than `biome` directly — the wrapper keeps behaviour consistent across the monorepo.
-
-```bash
-lint-biome check .           # Check for issues
-lint-biome check --write .   # Fix the auto-fixable
-lint-biome format .          # Format only
-```
-
 ## `package.json` handling
 
-The Biome preset leaves `package.json` alone. For those files, `lint-package` does the work:
+The Biome preset leaves `package.json` alone. For those files, use `sort-package-json`:
 
 1. Sorts `package.json` using the well-known field order
 2. Fixes export-condition order (`types` before `default` for TypeScript)
 
 ```bash
-lint-package              # Sort package.json in current directory
-lint-package path/to/pkg  # Sort a specific package.json
+pnpm sort-package-json              # Sort package.json in current directory
+pnpm sort-package-json path/to/pkg  # Sort a specific package.json
 ```
 
 It runs automatically as part of `pnpm fix`.

package/docs/en/tools/husky.md

@@ -20,7 +20,7 @@ Husky configures itself through the `prepare` script:
 ```json
 {
   "scripts": {
-    "prepare": "exec-husky"
+    "prepare": "husky"
   }
 }
 ```
@@ -35,7 +35,8 @@ Validates commit messages against the conventional-commit format:
 
 ```bash
 #!/bin/sh
-pnpm lint-commit --edit $1
+. "$(dirname "$0")/_/husky.sh"
+commitlint --edit $1
 ```
 
 ### `pre-commit` (optional)
@@ -47,10 +48,6 @@ Runs linting before a commit lands:
 pnpm lint
 ```
 
-## CLI wrapper
-
-`exec-husky` takes the place of `husky` directly — the wrapper handles monorepo scenarios that bare Husky doesn't.
-
 ## Bypassing hooks
 
 In the rare case where a hook truly has to be skipped:

package/docs/en/tools/markdownlint.md

@@ -11,7 +11,7 @@ area: "dev"
 
 # Markdownlint
 
-Markdownlint checks Markdown structure and formatting. The rules live in `@regardio/dev`; projects reach for the `lint-md` wrapper rather than calling the tool directly.
+Markdownlint checks Markdown structure and formatting. The rules live in `@regardio/dev`.
 
 ## Configuration
 
@@ -28,21 +28,12 @@ A `.markdownlint.json` at the package root:
 ```json
 {
   "scripts": {
-    "fix:md": "lint-md --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
-    "lint:md": "lint-md \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\""
+    "fix:md": "markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\""
   }
 }
 ```
 
-## CLI wrapper
-
-Use `lint-md` rather than `markdownlint-cli2` directly:
-
-```bash
-lint-md "**/*.md"              # Check all Markdown files
-lint-md --fix "**/*.md"        # Auto-fix what can be auto-fixed
-```
-
 ## Key rules
 
 | Rule | Description |

package/docs/en/tools/releases.md

@@ -1,8 +1,8 @@
 ---
 
 title: "Release Workflow"
-description: "Branch-based release workflow for Regardio packages — main → staging → production, driven by commit-and-tag-version."
-publishedAt: 2026-04-17
+description: "GitLab-flow release workflow for Regardio repos — branches mirror environments, ship tooling drives versioning, CI carries it out."
+publishedAt: 2026-05-07
 language: "en"
 status: "published"
 kind: "guide"
@@ -11,114 +11,92 @@ area: "dev"
 
 # Release Workflow
 
-Branch-based release workflow for Regardio packages. `main` → `staging` → `production`. `commit-and-tag-version` reads conventional commits to determine the version bump; quality gates run locally before any branch promotion. Nothing broken reaches a shared branch.
+Branches mirror environments. `main` is where development happens. `staging` reflects what is deployed to the staging server. `production` reflects what is live. Version bumps happen locally at ship time — CI on `production` carries the result out (publishes to npm or deploys to a server).
 
-## Overview
+## The Three-Branch Model
 
-Branches mirror deployment environments:
+```text
+main  ──── ship:staging ────►  staging  (optional staging server)
+  │
+  └──── ship:production ──►  production  (live / npm)
+                                  │
+                             sync back to staging
+```
+
+| Branch | Contains | CI role |
+|--------|----------|---------|
+| `main` | All committed, tested work | None (Husky runs local gates on commit) |
+| `staging` | Deployed to staging server or preview | Verify + deploy to staging |
+| `production` | Only shipped, versioned releases | Verify + deploy or publish |
+
+**Why version bumps happen locally, not in CI.** Hotfixes start from `production` and must write their version bump back up through `staging` and `main` in one pass. Keeping the bump local means both the normal ship path and the hotfix path behave identically — there is no special case in CI.
+
+## Hotfix Flow
+
+A hotfix is an urgent fix that must go to production immediately, without pulling in unreleased changes from `main`.
 
 ```text
-main → staging (optional) → production
+production ──► hotfix/<name>  (fix here with conventional commits)
+                    │
+                    └──► production ──► staging ──► main
 ```
 
-- **`main`** — active development, always deployable. Version bumps happen at ship time, not per-commit.
-- **`staging`** — optional validation environment. No versioning happens here.
-- **`production`** — versioned, published code only.
+`ship:hotfix start <name>` creates the branch from `production`, not from `main`. This is deliberate: it avoids accidentally shipping work-in-progress that has not yet been reviewed for production.
 
-When `ship-production` runs, it discovers all publishable workspace packages and asks you to assign a bump type — `0` (skip), `1` (patch), `2` (minor), or `3` (major) — to each one individually. Packages you skip are left untouched. For each package with a bump, it first tries to run the release script from the root package.json (using `--filter-root release:<type>`), and if that fails, falls back to running `commit-and-tag-version` directly with the appropriate bump flag. This bumps that package's version, rewrites its `CHANGELOG.md` using commits since its last scoped tag, and commits on `main`. The branches merge once after all bumps are applied. CI on `production` publishes only the packages whose version changed.
+`ship:hotfix finish` versions the fix, merges it into `production`, then propagates through `staging` and back to `main` so nothing is lost.
 
-## How It Works
+## Commands
 
-### Design principles
+| Command | Purpose |
+|---------|---------|
+| `pnpm ship:staging` | Fast-forward `main` → `staging`, push. Triggers staging CI. |
+| `pnpm ship:production` | Version selected packages (if any), fast-forward `main` → `production`, sync `staging`. Triggers production CI. |
+| `pnpm ship:hotfix start <name>` | Create `hotfix/<name>` from `production`. |
+| `pnpm ship:hotfix finish` | Version selected packages (if any), merge hotfix → `production` → `staging` → `main`. |
 
-1. **Branches mirror environments.** `staging` reflects what is deployed to the staging server (when used); `production` always reflects what is published to npm. There is never ambiguity about what is running where.
-2. **You choose the bump per package at ship time.** When running `ship-production` or `ship-hotfix finish`, every publishable package is listed and you assign it `0` (skip), `1` (patch), `2` (minor), or `3` (major). Packages you skip are untouched. The conventional commits in the log inform each choice; the decisions are always explicit.
-3. **Version numbers are a production guarantee.** Bumps are applied only at `ship-production` time. Every version tag in git and every release on npm corresponds to code that has been validated and shipped.
-4. **Staging is optional.** You can ship directly from `main` to `production`. Use `ship-staging` when you want to test changes in a staging environment first.
-5. **Tests are a local gate, not a CI gate.** Quality checks (`lint`, `typecheck`, `test`) run on your machine before any commit is made. Broken code cannot enter the repository.
-6. **You always land back on `main`.** Every command returns you to `main` when it finishes.
+## Versioning — Per-Package, at Ship Time
 
-### Full flow diagram
+`ship:production` and `ship:hotfix finish` discover all publishable workspace packages (those without `"private": true`) and ask you to assign a bump type to each:
 
-```text
-                ship-staging (OPTIONAL)
-                ┌──────────────────────────┐
-main ───────────┤ quality checks pass      ├──► staging (pushed)
-                │ ff-merge main → staging  │
-                └──────────────────────────┘
-                            │
-                   (validated in staging)
-                            │
-                            ▼
-                ship-production
-                ┌──────────────────────────┐
-                │ quality checks on main   │
-                │ pnpm release             │
-main ───────────┤ bumps version +          ├──► production
-                │ rewrites CHANGELOG.md    │
-                │ ff-merge main → prod     │
-                │ ff-merge prod → staging  │
-                │ push --follow-tags main  │
-                └──────────────────────────┘
-                            │
-                   (CI: pnpm -r publish → npm)
-                            ▼
-                       production
-
-
-                ship-hotfix start fix-name
-                ┌──────────────────────────┐
-production ─────┤ create hotfix/fix-name   ├──► hotfix/fix-name
-                └──────────────────────────┘
-                            │
-                   (author fixes with conventional commits)
-                            │
-                ship-hotfix finish
-                ┌──────────────────────────┐
-                │ quality checks           │
-                │ pnpm release             │
-hotfix/fix-name ┤ bumps version +          ├──► production → staging → main
-                │ rewrites CHANGELOG.md    │
-                │ merge to production      │
-                │ propagate to staging     │
-                │ propagate to main        │
-                └──────────────────────────┘
-```
+- `0` — skip (no version change)
+- `1` — patch
+- `2` — minor
+- `3` — major
 
-### What each branch represents at any point in time
+For each selected package, `commit-and-tag-version` runs from within that package's directory, reading the package's own `.versionrc.json`. It bumps the `version` field in `package.json`, rewrites `CHANGELOG.md` to include only commits that touched files under that package's directory (`gitRawCommitsOpts.path: "."`), commits the bump, and creates a scoped tag (e.g. `@regardio/dev@v1.2.0`).
 
-| Branch | Contains | Version bumped? |
-|--------|----------|-----------------|
-| `main` | All committed, tested work | Only after `ship-production` / `ship-hotfix finish` |
-| `staging` | Synced from `production` after each ship, or from `main` via `ship-staging` | After a ship propagates |
-| `production` | Only shipped, versioned releases | Yes — always |
+If a repo has no publishable packages (all are `private: true` or there are no `.versionrc.json` files), the versioning UI is skipped entirely and `ship:production` proceeds directly to the git merge.
 
-### CI role
+## CI — What Happens on Each Branch
 
-CI is intentionally minimal. On push to `production` it:
+CI behaviour differs by what the repo produces.
 
-1. Installs dependencies and builds
-2. Runs `pnpm -r publish --access public --no-git-checks` — publishes every workspace package whose current version is not yet on npm, skipping `private: true` packages
-3. Tags are already present (pushed by `ship-production` via `--follow-tags`)
+### Publishing monorepos (e.g. `commons`)
 
-## Commands
+- **staging**: Run typecheck and tests. Nothing is published.
+- **production**: Run typecheck, tests, then `pnpm -r publish --access public --no-git-checks`. Only packages whose current version is not yet on npm are published — packages with `"private": true` are skipped automatically.
 
-| Command | Usage | Purpose |
-|---------|-------|---------|
-| `pnpm release` | auto | Bump version from conventional commits, update CHANGELOG.md, commit |
-| `pnpm release:patch` | explicit | Force a patch bump |
-| `pnpm release:minor` | explicit | Force a minor bump |
-| `pnpm release:major` | explicit | Force a major bump |
-| `ship-staging` | `ship-staging` | (Optional) Deploy changes to staging for testing |
-| `ship-production` | `ship-production` | Bump version, merge main → production, trigger publish |
-| `ship-hotfix start <name>` | `ship-hotfix start <name>` | Create a hotfix branch from production |
-| `ship-hotfix finish` | `ship-hotfix finish` | Bump version, propagate hotfix through production → staging → main |
+### Server-deployed apps with Docker (e.g. `brass-berlin`)
 
-## Typical Release Flow
+- **staging**: Run tests, build the Docker image, push to the container registry, trigger a staging deploy (e.g. Coolify webhook).
+- **production**: Run typecheck + tests, build and push the Docker image, trigger a production deploy.
+
+### Cloudflare Workers apps (e.g. `magic-of-open-source`)
+
+- **staging**: Run tests, then `wrangler versions upload --preview-alias preview`.
+- **production**: Run typecheck + tests, then `wrangler deploy`.
+
+### Documentation / vocabulary repos (e.g. `system`)
 
-### 1. Develop with conventional commits
+- **staging** and **production**: Verify the repo is well-formed (build, typecheck, test). No publishing or deployment — the repo is distributed via git clone, not npm.
 
-On `main`, use conventional commits so the bump type is inferred automatically:
+### Static sites without a configured deployment (e.g. `bam-berlin-org`)
+
+- **staging** and **production**: Run tests, typecheck (production only), and build. A deployment step is left as a TODO until the hosting platform is chosen.
+
+## Typical Release Flow
+
+### 1. Develop on `main` with conventional commits
 
 ```bash
 feat: add user authentication       # → minor bump
@@ -126,111 +104,114 @@ fix: resolve login redirect loop    # → patch bump
 feat!: redesign authentication API  # → major bump
 ```
 
-### 2. Ship to production
+### 2. (Optional) Test in staging first
 
 ```bash
-pnpm ship:production
+pnpm ship:staging
 ```
 
-This will:
-
-1. Guard: must be on `main`, working tree clean
-2. Fetch and verify `staging` + `production` branches exist
-3. Show commits to be shipped
-4. For each publishable package: choose `0 (skip) / 1 (patch) / 2 (minor) / 3 (major)`
-5. Confirm the planned bumps — abort if declined or all skipped
-6. Run full quality suite on `main` — aborts on failure
-7. For each non-skipped package: run release script from root (if defined) or `commit-and-tag-version` directly — bumps version, rewrites `CHANGELOG.md`, commits
-8. Fast-forward merge `main` into `production` and push
-9. Sync `staging` with `production`
-10. Push `main` with `--follow-tags` to push all new version tags
-11. Return to `main`
-
-CI on `production` runs `pnpm -r publish` to push changed packages to npm.
+Deploys `main` to `staging` without touching versions.
 
-### Option: Test in staging first
+### 3. Ship to production
 
 ```bash
-pnpm ship:staging
+pnpm ship:production
 ```
 
-Deploys `main` to `staging` without touching versions. Useful for validating in a staging environment before shipping to production.
+1. Guard: must be on `main`, working tree clean.
+2. Fetch and verify `staging` and `production` branches exist.
+3. Show commits to be shipped.
+4. Run full quality suite — aborts on failure.
+5. If publishable packages exist: assign a bump type to each; confirm the planned bumps.
+6. If no publishable packages: confirm whether to ship (versioning is skipped).
+7. For each selected package: run `commit-and-tag-version --release-as <type>` from within the package directory.
+8. Fast-forward merge `main` → `production`, push.
+9. Sync `staging` with `production`, push.
+10. Push `main` with `--follow-tags` to carry the new version tags.
+11. Return to `main`.
 
-## Hotfix Flow
-
-For urgent fixes that must go directly to production:
+### 4. Hotfix flow
 
 ```bash
 pnpm ship:hotfix start fix-auth-bug
-# apply your fix with conventional commits
+# apply fix with conventional commits
 git add . && git commit -m "fix: ..."
 pnpm ship:hotfix finish
 ```
 
-`finish` asks you to assign a bump type (`0` (skip), `1` (patch), `2` (minor), or `3` (major)) to each publishable package, runs the release script from root (if defined) or `commit-and-tag-version` directly for each non-skipped one to bump versions and update `CHANGELOG.md`, then merges `hotfix → production → staging → main` and deletes the hotfix branch. CI publishes from `production`.
+`finish` fetches origin, runs quality checks, assigns bump types (if publishable packages exist), versions the fix, then merges `hotfix → production → staging → main` and deletes the hotfix branch.
 
 ## Adoption
 
-Install `@regardio/dev` and:
+### 1. Add ship scripts to `package.json`
 
-1. **Add the scripts to `package.json`** (optional, for monorepos):
+```json
+{
+  "scripts": {
+    "ship:hotfix": "ship-hotfix",
+    "ship:production": "ship-production",
+    "ship:staging": "ship-staging"
+  }
+}
+```
 
-   In a monorepo, you can define release scripts in the root `package.json` to centralize version management. The ship scripts will use these if available, and fall back to running `commit-and-tag-version` directly if not.
+For repos that publish to npm, also add:
+
+```json
+{
+  "scripts": {
+    "release": "commit-and-tag-version",
+    "release:major": "commit-and-tag-version --release-as major",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:patch": "commit-and-tag-version --release-as patch"
+  }
+}
+```
 
-   ```json
-   {
-     "scripts": {
-       "release": "commit-and-tag-version",
-       "release:major": "commit-and-tag-version --release-as major",
-       "release:minor": "commit-and-tag-version --release-as minor",
-       "release:patch": "commit-and-tag-version --release-as patch",
-       "ship:hotfix": "ship-hotfix",
-       "ship:production": "ship-production",
-       "ship:staging": "ship-staging"
-     }
-   }
-   ```
+### 2. Add `.versionrc.json` to each publishable package
 
-   For single-package repos or when you prefer direct `commit-and-tag-version` usage, you can omit the release scripts — the ship commands will call `commit-and-tag-version` directly.
+```bash
+cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
+# then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
+```
 
-2. **Add a `.versionrc.json` to each publishable package** with a scoped `tagPrefix` so tags and changelogs stay isolated per package:
+Every `.versionrc.json` must include `"gitRawCommitsOpts": { "path": "." }` to filter the git log to commits that actually touched files under that package's directory. Without this, the changelog accumulates noise from unrelated packages.
 
-   ```bash
-   cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
-   # then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
-   ```
+For a single-package repo, place `.versionrc.json` at the root instead.
 
-   For a single-package repo, put `.versionrc.json` at the root instead.
+### 3. Create the branches
 
-3. **Create the branches**:
+```bash
+git checkout -b staging && git push -u origin staging
+git checkout -b production && git push -u origin production
+git checkout main
+```
 
-   ```bash
-   git checkout -b staging && git push -u origin staging
-   git checkout -b production && git push -u origin production
-   git checkout main
-   ```
+### 4. Copy and adapt the CI workflow
 
-4. **Copy the release workflow** for your forge:
+```bash
+# Forgejo / Codeberg
+mkdir -p .forgejo/workflows
+cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/production.yml
 
-   ```bash
-   # GitHub
-   mkdir -p .github/workflows
-   cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+# GitHub
+mkdir -p .github/workflows
+cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+```
 
-   # Forgejo / Codeberg
-   mkdir -p .forgejo/workflows
-   cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/release.yml
-   ```
+Adapt the workflow for your repo type (see CI section above). The template covers the npm-publishing case; server-deployed and Cloudflare repos need the deployment step replaced.
 
-5. **First publish of any new package must be done locally**:
+### 5. First publish of any new package must be done locally
 
-   ```bash
-   pnpm build && npm publish --access public
-   ```
+```bash
+pnpm build && npm publish --access public
+```
+
+CI publishes subsequent versions; the very first one requires a local publish because the package does not yet exist on npm.
 
 ## Quality Gates
 
-Every ship command enforces the same gates — no broken code reaches any environment:
+Every ship command enforces the same gates before any commit or merge:
 
 ```bash
 pnpm build      # Must succeed
@@ -238,9 +219,11 @@ pnpm typecheck  # Must succeed
 pnpm test       # Must succeed
 ```
 
-## Private Packages
+## Private Packages and Non-Publishing Repos
+
+Packages with `"private": true` are skipped by `pnpm -r publish` automatically.
 
-Packages that should never be published to npm must set `"private": true` in `package.json`. `pnpm -r publish` skips them automatically. The git flow (`ship-staging`, `ship-production`, `ship-hotfix`) works identically — version bumps and branch promotion continue as normal; only the npm publish step is skipped.
+For repos where all packages are private (channels, deployment repos), the ship tools skip the versioning UI entirely and only perform the git merges. This makes the same tooling reusable across publishing and non-publishing repositories.
 
 ## Related
 

package/docs/en/tools/typescript.md

@@ -17,33 +17,62 @@ Strict, shared TypeScript presets for Regardio projects. Extending from `@regard
 
 | Preset | Use case |
 |--------|----------|
-| `@regardio/dev/typescript/base` | Node.js packages, libraries |
-| `@regardio/dev/typescript/react` | React applications and components |
-| `@regardio/dev/typescript/build` | Build-specific settings (extends base) |
+| `@regardio/dev/typescript/base` | Non-publishing packages and meta-configs (e.g. the workspace root) |
+| `@regardio/dev/typescript/library` | Published Node.js packages — adds declaration enforcement |
+| `@regardio/dev/typescript/react` | React apps and channels — adds JSX and DOM libs |
+| `@regardio/dev/typescript/react-library` | Published React packages — JSX, DOM libs, and declaration enforcement |
+| `@regardio/dev/typescript/build` | Build-time emission settings (pair with any of the above) |
+
+### Choosing a preset
+
+The guiding question is whether the package **publishes type declarations** to consumers.
+
+- **App or channel** (`private: true`) → `react` (or `base` for non-React)
+- **Published library without React** → `library`
+- **Published library with React** → `react-library`
+
+The `library` and `react-library` presets add two settings on top of the base:
+
+- `declaration: true` — validates that `.d.ts` files can be generated (even when `noEmit: true` during typecheck)
+- `isolatedDeclarations: true` — enforces that every exported declaration carries an explicit type annotation, enabling per-file parallel declaration generation
+
+`isolatedDeclarations` is a library-authoring constraint. It requires explicit return types on exported functions and explicit annotations on exported variables. Applying it to app code is unnecessarily strict — especially with frameworks like TanStack Router whose `Route` objects carry deeply inferred generics that cannot be spelled out without extraordinary verbosity.
 
 ## Configuration
 
-### `tsconfig.json`
+### App or channel
 
 ```json
 {
-  "extends": "@regardio/dev/typescript/base",
+  "compilerOptions": {
+    "paths": { "#/*": ["./src/*"] }
+  },
+  "extends": "@regardio/dev/typescript/react",
+  "include": ["**/*.ts", "**/*.tsx", "**/*.d.ts"]
+}
+```
+
+### Published Node.js library
+
+```json
+{
+  "extends": "@regardio/dev/typescript/library",
   "include": ["src/**/*.ts"]
 }
 ```
 
-For React projects:
+### Published React library
 
 ```json
 {
-  "extends": "@regardio/dev/typescript/react",
+  "extends": "@regardio/dev/typescript/react-library",
   "include": ["src/**/*.ts", "src/**/*.tsx"]
 }
 ```
 
 ### `tsconfig.build.json`
 
-A separate build config for production output:
+Pair any preset with `build` for production output:
 
 ```json
 {
@@ -51,28 +80,26 @@ A separate build config for production output:
     "outDir": "./dist",
     "rootDir": "./src"
   },
-  "extends": ["./tsconfig.json", "@regardio/dev/typescript/build"],
-  "include": ["src/**/*.ts"]
+  "extends": ["./tsconfig.json", "@regardio/dev/typescript/build"]
 }
 ```
 
 ## Strict settings
 
-The base config turns on strict type-checking across the board:
+All presets share the same strict type-checking baseline:
 
 - `strict: true` — every strict type-checking option
 - `noUncheckedIndexedAccess: true` — adds `undefined` to index signatures
-- `exactOptionalPropertyTypes: true` — distinguishes `undefined` from missing
 - `noImplicitReturns: true` — every code path returns a value
 - `noFallthroughCasesInSwitch: true` — prevents switch-fallthrough surprises
+- `verbatimModuleSyntax: true` — `import type` vs. `import` must be explicit
 
 ## Scripts
 
 ```json
 {
   "scripts": {
-    "build": "exec-tsc --project tsconfig.build.json",
-    "typecheck": "exec-tsc --noEmit"
+    "typecheck": "tsc --noEmit"
   }
 }
 ```

package/docs/en/tools/vitest.md

@@ -65,7 +65,7 @@ export default defineConfig({ test: vitestReactConfig });
 ```json
 {
   "scripts": {
-    "test": "exec-s test:*",
+    "test": "vitest run",
     "test:unit": "vitest run",
     "report": "vitest run --coverage"
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "private": false,
   "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
@@ -44,7 +44,9 @@
     },
     "./typescript/base": "./src/typescript/base.json",
     "./typescript/build": "./src/typescript/build.json",
+    "./typescript/library": "./src/typescript/library.json",
     "./typescript/react": "./src/typescript/react.json",
+    "./typescript/react-library": "./src/typescript/react-library.json",
     "./vitest/node": {
       "import": "./dist/vitest/node.mjs",
       "types": "./dist/vitest/node.d.mts"
@@ -61,6 +63,7 @@
   },
   "files": [
     "dist",
+    "LICENSE",
     "src/biome",
     "src/commitlint",
     "src/markdownlint",
@@ -71,9 +74,9 @@
   ],
   "devDependencies": {
     "@total-typescript/ts-reset": "0.6.1",
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.1",
     "@vitest/coverage-v8": "4.1.5",
-    "tsdown": "0.21.10",
+    "tsdown": "0.22.0",
     "vitest": "4.1.5"
   },
   "peerDependencies": {
@@ -90,9 +93,6 @@
     "typescript": ">=6",
     "vitest": ">=4"
   },
-  "engines": {
-    "node": ">=24"
-  },
   "scripts": {
     "build": "tsdown",
     "clean": "rimraf .turbo dist",
@@ -101,7 +101,7 @@
     "fix:biome": "biome check --write --unsafe .",
     "fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
     "fix:pkg": "sort-package-json",
-    "lint": "run-s lint:md lint:biome",
+    "lint": "run-p lint:*",
     "lint:biome": "biome check .",
     "lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc",
     "lint:pkg": "sort-package-json --check",

package/src/typescript/base.json

@@ -7,13 +7,11 @@
     "allowUnusedLabels": false,
     "alwaysStrict": true,
     "checkJs": false,
-    "declaration": true,
     "esModuleInterop": true,
     "exactOptionalPropertyTypes": false,
     "forceConsistentCasingInFileNames": true,
     "incremental": false,
     "inlineSources": false,
-    "isolatedDeclarations": true,
     "isolatedModules": true,
     "module": "ESNext",
     "moduleDetection": "force",

package/src/typescript/library.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "isolatedDeclarations": true
+  },
+  "extends": "./base.json"
+}

package/src/typescript/react-library.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "isolatedDeclarations": true
+  },
+  "extends": "./react.json"
+}

package/templates/versionrc/.versionrc.json

@@ -1,5 +1,6 @@
 {
   "commitAll": false,
+  "gitRawCommitsOpts": { "path": "." },
   "sign": false,
   "tagPrefix": "v",
   "types": [