@regardio/dev 2.6.1 → 2.7.0

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

@@ -31,11 +31,15 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		console.log("\nFetching latest state from origin...");
 		git("fetch", "origin");
 		if (!branchExists("production")) {
-			console.error("Branch \"production\" does not exist. Create it first:\n  git checkout -b production && git push -u origin production");
-			process.exit(1);
+			console.log("Creating production branch...");
+			git("checkout", "-b", "production");
+			git("push", "-u", "origin", "production");
+			git("checkout", "main");
 		}
 		git("checkout", "production");
-		git("pull", "--ff-only", "origin", "production");
+		try {
+			git("pull", "--ff-only", "origin", "production");
+		} catch {}
 		git("checkout", "-b", hotfixBranch);
 		console.log(`\n✅ Hotfix branch "${hotfixBranch}" created from production.`);
 		console.log("Apply your fix using conventional commits, then run:");
@@ -80,12 +84,22 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		} else console.log("No packages configured for versioning — skipping.");
 		console.log("\nMerging hotfix into production...");
 		git("checkout", "production");
-		git("pull", "--ff-only", "origin", "production");
+		try {
+			git("pull", "--ff-only", "origin", "production");
+		} catch {}
 		git("merge", "--no-ff", currentBranch, "-m", `chore(hotfix): merge ${currentBranch} into production`);
 		git("push", "origin", "production");
 		console.log("\nPropagating hotfix to staging...");
+		if (!branchExists("staging")) {
+			console.log("Creating staging branch...");
+			git("checkout", "-b", "staging");
+			git("push", "-u", "origin", "staging");
+			git("checkout", "production");
+		}
 		git("checkout", "staging");
-		git("pull", "--ff-only", "origin", "staging");
+		try {
+			git("pull", "--ff-only", "origin", "staging");
+		} catch {}
 		git("merge", "--no-ff", "production", "-m", "chore(hotfix): merge production into staging");
 		git("push", "origin", "staging");
 		console.log("\nPropagating hotfix to main...");

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

@@ -27,15 +27,24 @@ function runShipProduction(cwd = process.cwd()) {
 	console.log("\nFetching latest state from origin...");
 	git("fetch", "origin");
 	if (!branchExists("staging")) {
-		console.error("Branch \"staging\" does not exist. Create it first:\n  git checkout -b staging && git push -u origin staging");
-		process.exit(1);
+		console.log("Creating staging branch...");
+		git("checkout", "-b", "staging");
+		git("push", "-u", "origin", "staging");
+		git("checkout", "main");
 	}
 	if (!branchExists("production")) {
-		console.error("Branch \"production\" does not exist. Create it first:\n  git checkout -b production && git push -u origin production");
-		process.exit(1);
+		console.log("Creating production branch...");
+		git("checkout", "-b", "production");
+		git("push", "-u", "origin", "production");
+		git("checkout", "main");
 	}
 	git("pull", "--ff-only", "origin", "main");
-	const ahead = gitRead("log", "origin/production..HEAD", "--oneline");
+	let ahead;
+	try {
+		ahead = gitRead("log", "origin/production..HEAD", "--oneline");
+	} catch {
+		ahead = gitRead("log", "--oneline");
+	}
 	if (!ahead) {
 		console.error("main is already in sync with production. Nothing to ship.");
 		process.exit(1);
@@ -72,7 +81,9 @@ function runShipProduction(cwd = process.cwd()) {
 	} else if (!confirm("\nNo packages configured for versioning — ship commits to production?\n")) process.exit(0);
 	console.log("\nMerging main into production...");
 	git("checkout", "production");
-	git("pull", "--ff-only", "origin", "production");
+	try {
+		git("pull", "--ff-only", "origin", "production");
+	} catch {}
 	git("merge", "--ff-only", "main");
 	git("push", "origin", "production");
 	console.log("\nSyncing staging with production...");

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

@@ -42,8 +42,10 @@ function runShipStaging(cwd = process.cwd()) {
 		process.exit(1);
 	}
 	if (!branchExists("staging")) {
-		console.error("Branch \"staging\" does not exist locally or on origin. Create it first:\n  git checkout -b staging && git push -u origin staging");
-		process.exit(1);
+		console.log("Creating staging branch...");
+		git("checkout", "-b", "staging");
+		git("push", "-u", "origin", "staging");
+		git("checkout", "main");
 	}
 	console.log("\nRunning quality checks...");
 	try {

package/docs/en/standards/testing.md

@@ -97,27 +97,45 @@ Schema tests run against a real Postgres so policies and triggers behave as they
 
 ## Coverage
 
-Library packages hold a floor around 80% for statements, branches, functions, and lines. The floor is a minimum, not a target — the goal is meaningful tests, not arithmetic.
+Library packages hold a floor of 80% for statements, branches, functions, and lines. The floor is a minimum, not a target — the goal is meaningful tests, not arithmetic.
 
-Enforced at:
+## Branch quality gates
 
-- Local development — `pnpm test`
-- Release preparation — `ship-staging`
-- CI — GitHub Actions
+Different branches carry different promises, and the gates match those promises.
+
+| Branch | Gate | What runs |
+|--------|------|-----------|
+| `main` | commit | lint, typecheck |
+| `staging` | CI | lint, typecheck, test, coverage |
+| `production` | CI + ship | lint, typecheck, test, coverage |
+| `feature/*` | none | — |
+| `hotfix/*` | none | — |
+
+**`main` is the development branch.** Commits to `main` must be syntactically sound — lint and typecheck pass — but tests and coverage are not required to succeed. Work in progress lives here.
+
+**`staging` and `production` promise correctness.** The full QA chain runs before anything lands there. The ship commands enforce this before merging, and CI enforces it again on push.
+
+**Feature and hotfix branches are free.** Commit at will. The gate is applied when the branch merges into its target — feature → main applies main's gate, hotfix → production applies production's gate.
+
+Coverage is enforced at:
+
+- `pnpm report` — fails locally if coverage drops below the floor (run before shipping)
+- `ship:staging` and `ship:production` — run the full quality suite before merging
+- CI on `staging` and `production` — re-runs the suite on push
 
 ## Quality gates
 
-Before a package publishes:
+Before a package ships to `staging` or `production`:
 
 1. Build succeeds
 2. Type check passes
-3. Coverage meets the floor
-4. Tests pass — no skipped or failing
+3. Tests pass — no skipped or failing
+4. Coverage meets the floor
 
 ## Continuous integration
 
-- Pre-commit hooks run linting (Biome)
-- CI runs build, typecheck, and the test suite with coverage
+- Pre-commit hooks run lint (Biome, markdownlint) and typecheck on staged files
+- CI on `staging` and `production` runs the full suite including coverage
 - Release workflow blocks publishing on any failure
 
 ## Test maintenance

package/docs/en/tools/husky.md

@@ -27,6 +27,24 @@ Husky configures itself through the `prepare` script:
 
 This runs after `pnpm install` and sets up the `.husky` directory.
 
+Copy the hook templates from `@regardio/dev`:
+
+```bash
+mkdir -p .husky
+cp node_modules/@regardio/dev/templates/husky/pre-commit .husky/pre-commit
+cp node_modules/@regardio/dev/templates/husky/commit-msg .husky/commit-msg
+cp node_modules/@regardio/dev/templates/husky/pre-push .husky/pre-push
+chmod +x .husky/pre-commit .husky/commit-msg .husky/pre-push
+```
+
+## What the hooks enforce
+
+The pre-commit hook enforces **syntax correctness**, not behavioural correctness. The distinction is intentional and matches the branch model:
+
+- **`main`** is the development branch. Commits to `main` must pass lint and typecheck, but tests and coverage are not required. Work in progress belongs here.
+- **`staging` and `production`** promise correctness. The full QA chain (typecheck, test, coverage) runs on every push to those branches via the `pre-push` hook, and again inside the `ship:*` commands as a second gate.
+- **`feature/*` and `hotfix/*`** branches carry no gate. Commit freely — the gate applies when merging into the target branch.
+
 ## Hooks
 
 ### `commit-msg`
@@ -35,25 +53,83 @@ Validates commit messages against the conventional-commit format:
 
 ```bash
 #!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-commitlint --edit $1
+pnpm exec commitlint --edit "$1"
 ```
 
-### `pre-commit` (optional)
+### `pre-push`
 
-Runs linting before a commit lands:
+Branch-aware: runs typecheck on every branch except `feature/*` and `hotfix/*`; runs the full QA chain before any push to `staging` or `production`.
 
 ```bash
 #!/bin/sh
-pnpm lint
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no push gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac
 ```
 
+### `pre-commit`
+
+Branch-aware: lints staged files and runs typecheck; full QA on `staging`/`production` commits.
+
+```bash
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no commit gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACMR)"
+[ -z "$STAGED_FILES" ] && exit 0
+
+STAGED_BIOME_FILES="$(echo "$STAGED_FILES" | grep -E '\.(cjs|cts|js|jsx|mjs|mts|ts|tsx|json|jsonc)$' || true)"
+STAGED_MD_FILES="$(echo "$STAGED_FILES" | grep -E '\.(md|mdoc|mdx)$' | grep -v 'CHANGELOG\.md' || true)"
+
+if [ -n "$STAGED_BIOME_FILES" ]; then
+  echo "$STAGED_BIOME_FILES" | xargs pnpm exec biome check --no-errors-on-unmatched
+fi
+if [ -n "$STAGED_MD_FILES" ]; then
+  echo "$STAGED_MD_FILES" | xargs pnpm exec markdownlint-cli2 --config .markdownlint-cli2.jsonc
+fi
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac
+```
+
+`--if-present` means repos that don't define a given script skip that step silently.
+
 ## Bypassing hooks
 
-In the rare case where a hook truly has to be skipped:
+In the rare case where a hook truly has to be skipped, `--no-verify` works for both commit and push:
 
 ```bash
 git commit --no-verify -m "emergency fix"
+git push --no-verify origin main
 ```
 
 Use sparingly. A bypass that becomes habit stops being a bypass.
@@ -82,4 +158,6 @@ chmod +x .husky/*
 
 - [Commitlint](./commitlint.md) — commit-message validation
 - [Biome](./biome.md) — linting and formatting
+- [Release Workflow](./releases.md) — how branches, ship commands, and CI enforce quality gates
+- [Testing](../standards/testing.md) — branch gate model explained
 - [Husky Documentation](https://typicode.github.io/husky/)

package/docs/en/tools/releases.md

@@ -143,7 +143,28 @@ pnpm ship:hotfix finish
 
 ## Adoption
 
-### 1. Add ship scripts to `package.json`
+### 1. Set up Husky hooks
+
+```bash
+mkdir -p .husky
+cp node_modules/@regardio/dev/templates/husky/pre-commit .husky/pre-commit
+cp node_modules/@regardio/dev/templates/husky/commit-msg .husky/commit-msg
+chmod +x .husky/pre-commit .husky/commit-msg
+```
+
+Add the `prepare` script so Husky installs itself after `pnpm install`:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky"
+  }
+}
+```
+
+The `pre-commit` template is branch-aware: feature and hotfix branches commit freely, `main` enforces lint and typecheck, and `staging`/`production` enforce the full QA chain. See [Husky](./husky.md) for details.
+
+### 2. Add ship scripts to `package.json`
 
 ```json
 {
@@ -176,7 +197,9 @@ Every `.versionrc.json` must include `"gitRawCommitsOpts": { "path": "." }` to f
 
 For a single-package repo, place `.versionrc.json` at the root instead.
 
-### 3. Create the branches
+### 3. Create the branches (optional)
+
+The ship scripts auto-create `staging` and `production` branches if they don't exist. You only need to create them manually if you prefer to set them up ahead of time:
 
 ```bash
 git checkout -b staging && git push -u origin staging
@@ -208,12 +231,22 @@ CI publishes subsequent versions; the very first one requires a local publish be
 
 ## Quality Gates
 
-Every ship command enforces the same gates before any commit or merge:
+Gates differ by branch. The ship commands enforce the appropriate gate before any merge.
+
+| Context | What runs |
+|---------|-----------|
+| Commit to `main` (pre-commit hook) | lint, typecheck |
+| Commit to `feature/*` or `hotfix/*` | nothing |
+| `ship:staging` / `ship:production` / `ship:hotfix finish` | build, typecheck, test, coverage |
+| CI on `staging` / `production` | build, typecheck, test, coverage |
+
+Ship commands run:
 
 ```bash
 pnpm build      # Must succeed
 pnpm typecheck  # Must succeed
 pnpm test       # Must succeed
+pnpm report     # Coverage must meet the floor
 ```
 
 ## Publishing vs Non-Publishing Repos

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.6.1",
+  "version": "2.7.0",
   "private": false,
   "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
@@ -74,10 +74,10 @@
   ],
   "devDependencies": {
     "@total-typescript/ts-reset": "0.6.1",
-    "@types/node": "25.6.2",
-    "@vitest/coverage-v8": "4.1.5",
+    "@types/node": "25.7.0",
+    "@vitest/coverage-v8": "4.1.6",
     "tsdown": "0.22.0",
-    "vitest": "4.1.5"
+    "vitest": "4.1.6"
   },
   "peerDependencies": {
     "@biomejs/biome": ">=2",

package/templates/husky/commit-msg

@@ -0,0 +1,2 @@
+#!/bin/sh
+pnpm exec commitlint --edit "$1"

package/templates/husky/pre-commit

@@ -0,0 +1,32 @@
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no commit gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACMR)"
+[ -z "$STAGED_FILES" ] && exit 0
+
+STAGED_BIOME_FILES="$(echo "$STAGED_FILES" | grep -E '\.(cjs|cts|js|jsx|mjs|mts|ts|tsx|json|jsonc)$' || true)"
+STAGED_MD_FILES="$(echo "$STAGED_FILES" | grep -E '\.(md|mdoc|mdx)$' | grep -v 'CHANGELOG\.md' || true)"
+
+if [ -n "$STAGED_BIOME_FILES" ]; then
+  echo "$STAGED_BIOME_FILES" | xargs pnpm exec biome check --no-errors-on-unmatched
+fi
+if [ -n "$STAGED_MD_FILES" ]; then
+  echo "$STAGED_MD_FILES" | xargs pnpm exec markdownlint-cli2 --config .markdownlint-cli2.jsonc
+fi
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac

package/templates/husky/pre-push

@@ -0,0 +1,19 @@
+#!/bin/sh
+set -eu
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo 'HEAD')"
+
+# Feature and hotfix branches carry no push gate.
+case "$BRANCH" in
+  feature/*|hotfix/*) exit 0 ;;
+esac
+
+pnpm run --if-present typecheck
+
+# Staging and production must pass the full QA chain.
+case "$BRANCH" in
+  staging|production)
+    pnpm run --if-present test
+    pnpm run --if-present report
+    ;;
+esac