@regardio/dev 1.24.0 → 2.0.2

package/README.md

@@ -27,7 +27,7 @@ The goal is code that's correct, consistent, and a pleasure to work with.
 | **Testing** | Vitest, Playwright, Testing Library |
 | **Build** | TypeScript, tsx, Vite |
 | **Workflow** | Husky, GitLab Flow |
-| **CLI utilities** | exec-clean, exec-p, exec-s, exec-tsc, ship-staging, ship-production, ship-hotfix, lint-biome, lint-md, lint-package |
+| **CLI utilities** | `ship-staging`, `ship-production`, `ship-hotfix` |
 
 ## Quick Start
 
@@ -42,7 +42,7 @@ Extend the shared configs in your project:
 { "extends": ["@regardio/dev/biome"] }
 
 // tsconfig.json
-{ "extends": "@regardio/dev/typescript/base.json" }
+{ "extends": "@regardio/dev/typescript/base" }
 ```
 
 ## Documentation

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { a as runQualityChecks, i as gitRead, o as runScript, r as git, t as branchExists } from "./utils-BQ-JZ2D5.mjs";
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/bin/ship/hotfix.ts
+/**
+* ship-hotfix: Manage hotfix branches based on production code.
+*
+* Usage:
+*   ship-hotfix start <name>   - Create hotfix/<name> from production
+*   ship-hotfix finish         - Finish and propagate the hotfix
+*
+* GitLab workflow:
+*   production → hotfix/<name> → production → staging → main
+*
+* During a hotfix, add a changeset (`pnpm changeset`) describing the fix.
+* `ship-hotfix finish` consumes all pending changesets, commits the version
+* bumps, and propagates the hotfix through production → staging → main.
+* CI on `production` handles the `changeset publish` to npm.
+*/
+function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
+	if (subcommand === "start") {
+		const name = subArgs[0];
+		if (!name) {
+			console.error("Usage: ship-hotfix start <name>");
+			process.exit(1);
+		}
+		const hotfixBranch = `hotfix/${name}`;
+		if (gitRead("status", "--porcelain")) {
+			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");
+		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);
+		}
+		git("checkout", "production");
+		git("pull", "--ff-only", "origin", "production");
+		git("checkout", "-b", hotfixBranch);
+		console.log(`\n✅ Hotfix branch "${hotfixBranch}" created from production.`);
+		console.log("Apply your fix, add a changeset (`pnpm changeset`), commit, then run:");
+		console.log("  ship-hotfix finish");
+		process.exit(0);
+	}
+	if (subcommand === "finish") {
+		const currentBranch = gitRead("branch", "--show-current");
+		if (!currentBranch.startsWith("hotfix/")) {
+			console.error(`Must be on a hotfix/* branch. Currently on: ${currentBranch}`);
+			process.exit(1);
+		}
+		if (gitRead("status", "--porcelain")) {
+			console.error("Working directory has uncommitted changes. Commit or stash them first.");
+			process.exit(1);
+		}
+		if (!existsSync(join(cwd, ".changeset"))) {
+			console.error("\nNo .changeset/ directory found. This tooling requires Changesets.\nCopy the template from @regardio/dev/templates/changeset and run:\n  pnpm changeset init");
+			process.exit(1);
+		}
+		if (execFileSync("sh", ["-c", `ls .changeset/*.md 2>/dev/null | grep -v README.md | wc -l | tr -d ' '`], { encoding: "utf-8" }).trim() === "0") {
+			console.error("\nNo pending changesets. Run `pnpm changeset` before finishing the hotfix.");
+			process.exit(1);
+		}
+		console.log("\nRunning quality checks...");
+		try {
+			runQualityChecks();
+		} catch {
+			console.error("\nQuality checks failed. Fix all issues before finishing the hotfix.");
+			process.exit(1);
+		}
+		console.log("✅ Quality checks passed");
+		const packageJsonPath = join(cwd, "package.json");
+		if (!existsSync(packageJsonPath)) {
+			console.error("No package.json found in current directory.");
+			process.exit(1);
+		}
+		const { name: packageName } = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+		console.log("\nApplying changesets (bumping versions and updating CHANGELOGs)...");
+		runScript("changeset version");
+		try {
+			runScript("fix:pkg");
+		} catch {}
+		try {
+			git("add", "-A");
+			const changedFiles = gitRead("diff", "--cached", "--name-only").split("\n").filter(Boolean);
+			for (const file of changedFiles) {
+				if (file.endsWith(".json")) try {
+					execSync(`npx biome check --write ${file}`, {
+						cwd,
+						stdio: "inherit"
+					});
+				} catch {}
+				if (file.endsWith(".md")) try {
+					execSync(`npx markdownlint-cli2 --fix ${file}`, {
+						cwd,
+						stdio: "inherit"
+					});
+				} catch {}
+			}
+		} catch {}
+		git("add", "-A");
+		git("commit", "-m", "chore(hotfix): version packages");
+		console.log("\nFetching latest state from origin...");
+		git("fetch", "origin");
+		console.log("\nMerging hotfix into production...");
+		git("checkout", "production");
+		git("pull", "--ff-only", "origin", "production");
+		git("merge", "--no-ff", currentBranch, "-m", `chore(hotfix): merge ${currentBranch} into production`);
+		git("push", "origin", "production");
+		console.log("\nPropagating hotfix to staging...");
+		git("checkout", "staging");
+		git("pull", "--ff-only", "origin", "staging");
+		git("merge", "--no-ff", "production", "-m", "chore(hotfix): merge production into staging");
+		git("push", "origin", "staging");
+		console.log("\nPropagating hotfix to main...");
+		git("checkout", "main");
+		git("pull", "--ff-only", "origin", "main");
+		git("merge", "--no-ff", "staging", "-m", "chore(hotfix): merge staging into main");
+		git("push", "origin", "main");
+		git("branch", "-d", currentBranch);
+		try {
+			git("push", "origin", "--delete", currentBranch);
+		} catch {}
+		console.log(`\n✅ Hotfix ${packageName} shipped to production → staging → main`);
+		console.log("CI will publish changed packages to npm.");
+		console.log("You are on main and ready to keep working.");
+		process.exit(0);
+	}
+	console.error("Usage:");
+	console.error("  ship-hotfix start <name>");
+	console.error("  ship-hotfix finish");
+	process.exit(1);
+}
+//#endregion
+//#region src/bin/ship/hotfix.bin.ts
+runShipHotfix(process.argv[2], process.argv.slice(3));
+//#endregion
+export {};

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

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { a as runQualityChecks, i as gitRead, n as confirm, o as runScript, r as git, t as branchExists } from "./utils-BQ-JZ2D5.mjs";
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/bin/ship/production.ts
+/**
+* ship-production: Promote main to production following the GitLab workflow.
+*
+* Usage: ship-production
+*
+* GitLab workflow:
+*   main → (changeset version + commit) → production → staging → main
+*
+* Versioning is driven by Changesets. Authors add a changeset (`pnpm changeset`)
+* alongside their change on main. This script consumes all pending changesets
+* at ship time, commits the version bumps, then merges main → production.
+* CI on `production` handles the actual `changeset publish` to npm.
+*/
+function runShipProduction(cwd = process.cwd()) {
+	const currentBranch = gitRead("branch", "--show-current");
+	if (currentBranch !== "main") {
+		console.error(`Must be on the main branch to ship. Currently on: ${currentBranch}`);
+		process.exit(1);
+	}
+	if (gitRead("status", "--porcelain")) {
+		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");
+	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);
+	}
+	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);
+	}
+	git("pull", "--ff-only", "origin", "main");
+	const ahead = gitRead("log", "origin/production..HEAD", "--oneline");
+	if (!ahead) {
+		console.error("main is already in sync with production. Nothing to ship.");
+		process.exit(1);
+	}
+	console.log("\nCommits to be shipped to production:");
+	console.log(ahead);
+	if (!existsSync(join(cwd, ".changeset"))) {
+		console.error("\nNo .changeset/ directory found. This tooling requires Changesets.\nCopy the template from @regardio/dev/templates/changeset and run:\n  pnpm changeset init");
+		process.exit(1);
+	}
+	const pendingChangesets = execFileSync("sh", ["-c", `ls .changeset/*.md 2>/dev/null | grep -v README.md | wc -l | tr -d ' '`], { encoding: "utf-8" }).trim();
+	if (pendingChangesets === "0") {
+		console.error("\nNo pending changesets. Run `pnpm changeset` before shipping to production.");
+		process.exit(1);
+	}
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) {
+		console.error("No package.json found in current directory.");
+		process.exit(1);
+	}
+	const { name: packageName } = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+	console.log(`\n${pendingChangesets} pending changeset(s) will be consumed.`);
+	if (!confirm(`Ship ${packageName} to production?`)) {
+		console.log("Aborted.");
+		process.exit(0);
+	}
+	console.log("\nRunning quality checks on main...");
+	try {
+		runQualityChecks();
+	} catch {
+		console.error("\nQuality checks failed on main. Fix issues before shipping.");
+		process.exit(1);
+	}
+	console.log("✅ Quality checks passed");
+	console.log("\nApplying changesets (bumping versions and updating CHANGELOGs)...");
+	runScript("changeset version");
+	try {
+		runScript("fix:pkg");
+	} catch {}
+	try {
+		git("add", "-A");
+		const changedFiles = gitRead("diff", "--cached", "--name-only").split("\n").filter(Boolean);
+		for (const file of changedFiles) {
+			if (file.endsWith(".json")) try {
+				execSync(`npx biome check --write ${file}`, {
+					cwd,
+					stdio: "inherit"
+				});
+			} catch {}
+			if (file.endsWith(".md")) try {
+				execSync(`npx markdownlint-cli2 --fix ${file}`, {
+					cwd,
+					stdio: "inherit"
+				});
+			} catch {}
+		}
+	} catch {}
+	git("add", "-A");
+	git("commit", "-m", "chore(release): version packages");
+	console.log("\nMerging main into production...");
+	git("checkout", "production");
+	git("pull", "--ff-only", "origin", "production");
+	git("merge", "--ff-only", "main");
+	git("push", "origin", "production");
+	console.log("\nSyncing staging with production...");
+	git("checkout", "staging");
+	git("pull", "--ff-only", "origin", "staging");
+	git("merge", "--ff-only", "production");
+	git("push", "origin", "staging");
+	git("checkout", "main");
+	git("push", "origin", "main");
+	console.log(`\n✅ Shipped ${packageName} to production. CI will publish changed packages to npm.`);
+	console.log("You are on main and ready to keep working.");
+}
+//#endregion
+//#region src/bin/ship/production.bin.ts
+runShipProduction();
+//#endregion
+export {};

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { a as runQualityChecks, i as gitRead, r as git, t as branchExists } from "./utils-BQ-JZ2D5.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/bin/ship/staging.ts
+/**
+* ship-staging: Deploy changes to staging following the GitLab workflow.
+*
+* Usage: ship-staging
+*
+* GitLab workflow:
+*   main → staging  (staging deploy, no version bump yet)
+*
+* Optional step: you can ship directly to production via ship-production,
+* which automatically syncs staging afterward. Use ship-staging when you
+* want to validate changes in a staging environment first.
+*
+* Versioning is deferred to ship-production so version numbers only ever
+* correspond to production-verified code.
+*/
+function runShipStaging(cwd = process.cwd()) {
+	const currentBranch = gitRead("branch", "--show-current");
+	if (currentBranch !== "main") {
+		console.error(`Must be on the main branch to release. Currently on: ${currentBranch}`);
+		process.exit(1);
+	}
+	if (gitRead("status", "--porcelain")) {
+		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");
+	git("pull", "--ff-only", "origin", "main");
+	const packageJsonPath = join(cwd, "package.json");
+	if (!existsSync(packageJsonPath)) {
+		console.error("No package.json found in current directory.");
+		process.exit(1);
+	}
+	const packageName = JSON.parse(readFileSync(packageJsonPath, "utf-8")).name;
+	if (!packageName) {
+		console.error("No \"name\" field found in package.json.");
+		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("\nRunning quality checks...");
+	try {
+		runQualityChecks();
+	} catch {
+		console.error("\nQuality checks failed. Fix all issues before releasing.");
+		process.exit(1);
+	}
+	console.log("✅ Quality checks passed");
+	console.log("\nMerging main into staging...");
+	git("checkout", "staging");
+	git("merge", "--ff-only", "main");
+	git("push", "origin", "staging");
+	git("checkout", "main");
+	git("push", "origin", "main");
+	console.log(`\n✅ ${packageName} deployed to staging`);
+	console.log("Run ship-production when ready to ship to production.");
+	console.log("(Or ship directly from main to production without using ship-staging first.)");
+}
+//#endregion
+//#region src/bin/ship/staging.bin.ts
+runShipStaging();
+//#endregion
+export {};

package/dist/bin/ship/utils-BQ-JZ2D5.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { execFileSync, execSync } from "node:child_process";
+import { closeSync, openSync, readSync } from "node:fs";
+//#region src/bin/ship/utils.ts
+/**
+* Shared utilities for ship-staging, ship-production, and ship-hotfix.
+*
+* Git commands use execFileSync (not a shell string) so user-provided
+* strings such as commit messages are never interpolated by the shell.
+* pnpm script invocations use execSync via shell since script names are
+* developer-controlled and pnpm itself is resolved through PATH.
+*/
+const git = (...args) => {
+	console.log(`$ git ${args.join(" ")}`);
+	execFileSync("git", args, { stdio: "inherit" });
+};
+const gitRead = (...args) => execFileSync("git", args, { encoding: "utf-8" }).trim();
+const runScript = (script) => {
+	console.log(`$ pnpm ${script}`);
+	execSync(`pnpm ${script}`, { stdio: "inherit" });
+};
+const runQualityChecks = () => {
+	runScript("build");
+	runScript("typecheck");
+	runScript("test");
+};
+const branchExists = (name) => gitRead("branch", "--list", name) !== "" || gitRead("branch", "--list", "--remotes", `origin/${name}`) !== "";
+const confirm = (prompt, ttyPath = "/dev/tty") => {
+	process.stdout.write(`${prompt} (y/N) `);
+	const buf = Buffer.alloc(1024);
+	let fd;
+	let shouldClose = false;
+	try {
+		fd = openSync(ttyPath, "r");
+		shouldClose = true;
+	} catch {
+		fd = process.stdin.fd;
+	}
+	const bytesRead = readSync(fd, buf, 0, buf.length, null);
+	if (shouldClose) closeSync(fd);
+	const answer = buf.slice(0, bytesRead).toString().trim();
+	return answer === "y" || answer === "Y";
+};
+//#endregion
+export { runQualityChecks as a, gitRead as i, confirm as n, runScript as o, git as r, branchExists as t };

package/dist/playwright/index.d.mts

@@ -0,0 +1,24 @@
+import * as _$_playwright_test0 from "@playwright/test";
+import { PlaywrightTestConfig } from "@playwright/test";
+
+//#region src/playwright/index.d.ts
+interface BuildPlaywrightBaseConfigParams {
+  appPort: number;
+  appUrl: string;
+  ci?: boolean;
+  devices: typeof _$_playwright_test0.devices;
+  webServerCommand: string;
+}
+/**
+ * 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,
+  devices,
+  ci,
+  webServerCommand
+}: BuildPlaywrightBaseConfigParams): PlaywrightTestConfig;
+//#endregion
+export { BuildPlaywrightBaseConfigParams, buildPlaywrightBaseConfig };

package/dist/playwright/index.mjs

@@ -0,0 +1,61 @@
+//#region src/playwright/index.ts
+/**
+* Build a base Playwright config object with Regardio defaults.
+* Consumers should wrap with defineConfig() in their local playwright.config.ts
+*/
+function buildPlaywrightBaseConfig({ appUrl, appPort, devices, ci = !!process.env.CI, webServerCommand }) {
+	if (!appUrl || typeof appUrl !== "string") throw new Error("[playwright] appUrl must be a non-empty string");
+	if (!appPort || typeof appPort !== "number") throw new Error("[playwright] appPort must be a number");
+	if (!devices) throw new Error("[playwright] devices must be provided from \"@playwright/test\"");
+	return {
+		forbidOnly: ci,
+		fullyParallel: true,
+		outputDir: "./tests/test-results",
+		projects: [
+			{
+				name: "chromium",
+				use: { ...devices["Desktop Chrome"] }
+			},
+			{
+				name: "firefox",
+				use: { ...devices["Desktop Firefox"] }
+			},
+			{
+				name: "webkit",
+				use: { ...devices["Desktop Safari"] }
+			},
+			{
+				name: "iPad Pro 11 landscape",
+				use: { ...devices["iPad Pro 11 landscape"] }
+			},
+			{
+				name: "iPhone 14 portrait",
+				use: { ...devices["iPhone 14"] }
+			},
+			{
+				name: "Pixel 7 portrait",
+				use: { ...devices["Pixel 7"] }
+			}
+		],
+		reporter: [["html", {
+			open: "never",
+			outputFolder: "./tests/playwright-report"
+		}]],
+		retries: ci ? 2 : 0,
+		testDir: "./tests",
+		testMatch: "**/*.e2e.ts",
+		use: {
+			baseURL: appUrl,
+			trace: "on-first-retry"
+		},
+		webServer: {
+			command: webServerCommand,
+			ignoreHTTPSErrors: true,
+			reuseExistingServer: !ci,
+			url: appUrl
+		},
+		...ci ? { workers: 1 } : {}
+	};
+}
+//#endregion
+export { buildPlaywrightBaseConfig };

package/dist/vitest/node.d.mts

@@ -0,0 +1,22 @@
+//#region src/vitest/node.d.ts
+/**
+ * Base Vitest configuration for Node.js packages.
+ * Use with defineConfig() in your vitest.config.ts
+ */
+declare const vitestNodeConfig: {
+  coverage: {
+    provider: "v8";
+    thresholds: {
+      branches: number;
+      functions: number;
+      lines: number;
+      statements: number;
+    };
+  };
+  environment: string;
+  exclude: string[];
+  globals: boolean;
+  include: string[];
+};
+//#endregion
+export { vitestNodeConfig };

package/dist/vitest/node.mjs

@@ -0,0 +1,28 @@
+//#region src/vitest/node.ts
+/**
+* Base Vitest configuration for Node.js packages.
+* Use with defineConfig() in your vitest.config.ts
+*/
+const vitestNodeConfig = {
+	coverage: {
+		provider: "v8",
+		thresholds: {
+			branches: 80,
+			functions: 80,
+			lines: 80,
+			statements: 80
+		}
+	},
+	environment: "node",
+	exclude: [
+		"node_modules",
+		"dist",
+		"build",
+		".turbo",
+		".react-router"
+	],
+	globals: true,
+	include: ["**/*.test.ts", "**/*.test.tsx"]
+};
+//#endregion
+export { vitestNodeConfig };

package/dist/vitest/react.d.mts

@@ -0,0 +1,22 @@
+//#region src/vitest/react.d.ts
+/**
+ * Vitest configuration for React packages with jsdom environment.
+ * Use with defineConfig() in your vitest.config.ts
+ */
+declare const vitestReactConfig: {
+  coverage: {
+    provider: "v8";
+    thresholds: {
+      branches: number;
+      functions: number;
+      lines: number;
+      statements: number;
+    };
+  };
+  environment: string;
+  exclude: string[];
+  globals: boolean;
+  include: string[];
+};
+//#endregion
+export { vitestReactConfig };

package/dist/vitest/react.mjs

@@ -0,0 +1,28 @@
+//#region src/vitest/react.ts
+/**
+* Vitest configuration for React packages with jsdom environment.
+* Use with defineConfig() in your vitest.config.ts
+*/
+const vitestReactConfig = {
+	coverage: {
+		provider: "v8",
+		thresholds: {
+			branches: 80,
+			functions: 80,
+			lines: 80,
+			statements: 80
+		}
+	},
+	environment: "jsdom",
+	exclude: [
+		"node_modules",
+		"dist",
+		"build",
+		".turbo",
+		".react-router"
+	],
+	globals: true,
+	include: ["**/*.test.ts", "**/*.test.tsx"]
+};
+//#endregion
+export { vitestReactConfig };

package/docs/en/README.md

@@ -0,0 +1,95 @@
+---
+
+title: @regardio/dev Documentation
+type: guide
+status: published
+summary: Complete documentation for the @regardio/dev toolchain
+related: [coding-standards, development-principles]
+locale: en-US
+---
+
+# Documentation
+
+Documentation index and quick reference for the `@regardio/dev` toolchain.
+
+## Concepts
+
+Foundational principles and standards that guide development:
+
+| Document | Description |
+|----------|-------------|
+| [AI Agents](./agents.md) | Instructions for AI coding assistants |
+| [API](./standards/api.md) | API design and implementation guidelines |
+| [Coding](./standards/coding.md) | TypeScript, React, and general patterns |
+| [Commits](./standards/commits.md) | Conventional commits and changelog generation |
+| [Documentation](./standards/documentation.md) | Documentation structure and conventions |
+| [Naming](./standards/naming.md) | Consistent naming across languages |
+| [Principles](./standards/principles.md) | Code quality, architecture, maintainability |
+| [React](./standards/react.md) | React and TypeScript development patterns |
+| [SQL](./standards/sql.md) | PostgreSQL schema styling, structure, and access control |
+| [Testing](./standards/testing.md) | Testing philosophy and patterns |
+| [Writing](./standards/writing.md) | Voice, tone, and language |
+
+## Toolchain
+
+Configuration and usage for each tool in the stack:
+
+| Document | Description |
+|----------|-------------|
+| [Biome](./tools/biome.md) | Linting and formatting |
+| [Commitlint](./tools/commitlint.md) | Commit message validation |
+| [Dependencies](./tools/dependencies.md) | Safe dependency updates and supply-chain controls |
+| [Husky](./tools/husky.md) | Git hooks |
+| [Markdownlint](./tools/markdownlint.md) | Markdown quality |
+| [Playwright](./tools/playwright.md) | End-to-end testing |
+| [Releases](./tools/releases.md) | GitLab-flow-based versioning and releases |
+| [TypeScript](./tools/typescript.md) | Strict TypeScript configuration |
+| [Vitest](./tools/vitest.md) | Unit and integration testing |
+
+## Quick Reference
+
+### Commands
+
+```bash
+pnpm build         # Build all packages
+pnpm dev           # Start development
+pnpm fix           # Run all fixes and linting
+pnpm lint          # Run linting only
+pnpm report        # Run tests with coverage
+pnpm changeset     # Declare a version bump alongside your change
+pnpm ship:staging  # Deploy main to staging for validation (optional)
+pnpm ship:production  # Consume changesets, merge main → production, trigger publish
+pnpm ship:hotfix start <name>  # Start an urgent fix from production
+pnpm ship:hotfix finish  # Propagate the hotfix back through production → staging → main
+pnpm test          # Run tests
+pnpm typecheck     # TypeScript type checking
+```
+
+### Config Files
+
+| File | Purpose |
+|------|---------|
+| `.commitlintrc.json` | Commit message rules |
+| `.markdownlint.json` | Markdown rules |
+| `biome.jsonc` | Linting and formatting |
+| `playwright.config.ts` | E2E test configuration |
+| `pnpm-workspace.yaml` | Workspace dependency and supply-chain policy |
+| `tsconfig.json` | TypeScript configuration |
+| `vitest.config.ts` | Unit test configuration |
+| `.sqlfluff` | SQL linting (copy from `@regardio/dev/sqlfluff/setup.cfg`) |
+
+### Extending Presets
+
+```jsonc
+// biome.jsonc
+{ "extends": ["@regardio/dev/biome"] }
+
+// tsconfig.json
+{ "extends": "@regardio/dev/typescript/base" }
+
+// .commitlintrc.json
+{ "extends": ["@regardio/dev/commitlint"] }
+
+// .markdownlint.json
+{ "extends": "@regardio/dev/markdownlint" }
+```