@regardio/dev 2.0.2 → 2.1.1

package/README.md

@@ -1,25 +1,25 @@
 # @regardio/dev
 
-A unified developer toolchain for consistent, high-quality TypeScript projects.
+A shared developer toolchain for TypeScript projects that want consistent quality without wrestling with configuration.
 
-## Purpose
+## What it's for
 
-`@regardio/dev` provides a complete, opinionated development environment that can be adopted by any JavaScript/TypeScript project. It bundles best-in-class tools with sensible defaults, enabling teams to focus on building features rather than configuring tooling.
+`@regardio/dev` is an opinionated, complete development environment that any JavaScript or TypeScript project can pull in. It bundles well-tested tools with defaults that work out of the box, so a team can reach for features instead of assembling tooling.
 
-**One dependency. Zero configuration conflicts. Consistent quality across all projects.**
+**One dependency. No configuration tug-of-war. Steady quality across projects.**
 
-## Philosophy
+## The idea
 
-We believe in **balanced strictness**: rigorous enough to catch bugs early and maintain consistency, yet practical enough to not impede development velocity.
+Balanced strictness: rigorous enough to catch trouble early and keep things consistent, loose enough to stay out of the way.
 
-- **Strict by default** - TypeScript strict mode, comprehensive linting, conventional commits
-- **Sensible defaults** - Shared configs that work out of the box
-- **Minimal boilerplate** - Extend presets, override only what's necessary
-- **Fast feedback** - Quick linting and type checking during development
+- **Strict by default** — TypeScript strict mode, thorough linting, conventional commits
+- **Sensible defaults** — shared configs that work on first install
+- **Minimal boilerplate** — extend a preset, override only the odd line
+- **Fast feedback** — quick linting and type-checking during development
 
-The goal is code that's correct, consistent, and a pleasure to work with.
+The aim is code that's correct, consistent, and pleasant to work with — three things the industry likes to pretend are in tension.
 
-## What's Inside
+## What's inside
 
 | Category | Tools |
 |----------|-------|
@@ -29,13 +29,13 @@ The goal is code that's correct, consistent, and a pleasure to work with.
 | **Workflow** | Husky, GitLab Flow |
 | **CLI utilities** | `ship-staging`, `ship-production`, `ship-hotfix` |
 
-## Quick Start
+## Quick start
 
 ```bash
 pnpm add -D @regardio/dev
 ```
 
-Extend the shared configs in your project:
+Extend the shared configs:
 
 ```jsonc
 // biome.jsonc
@@ -47,47 +47,39 @@ Extend the shared configs in your project:
 
 ## Documentation
 
-Detailed documentation is organized by topic:
+Documentation sits alongside the code, organised by topic. Cross-project standards — principles, writing voice, documentation shape — live outside this package at [`commons/docs/en/`](../../docs/en/README.md), since they apply well beyond TypeScript.
 
-### Concepts
+### Code standards
 
-- [AI Agents](./docs/en/agents.md) - Instructions for AI coding assistants
-- [API](./docs/en/standards/api.md) - API design and implementation guidelines
-- [Coding](./docs/en/standards/coding.md) - TypeScript, React, and general patterns
-- [Commits](./docs/en/standards/commits.md) - Conventional commits and changelog generation
-- [Documentation](./docs/en/standards/documentation.md) - Documentation structure and conventions
-- [Naming](./docs/en/standards/naming.md) - Consistent naming across languages
-- [Principles](./docs/en/standards/principles.md) - Code quality, architecture, maintainability
-- [React](./docs/en/standards/react.md) - React and TypeScript development patterns
-- [SQL](./docs/en/standards/sql.md) - PostgreSQL schema styling, structure, and access control
-- [Testing](./docs/en/standards/testing.md) - Testing philosophy and patterns
-- [Writing](./docs/en/standards/writing.md) - Voice, tone, and language for content
+- [API](./docs/en/standards/api.md) — API design and implementation
+- [Coding](./docs/en/standards/coding.md) — TypeScript, React, and general patterns
+- [Commits](./docs/en/standards/commits.md) — conventional commits and changelog generation
+- [Naming](./docs/en/standards/naming.md) — consistent naming across languages
+- [React](./docs/en/standards/react.md) — React and TypeScript patterns
+- [SQL](./docs/en/standards/sql.md) — PostgreSQL schema, structure, access control
+- [Testing](./docs/en/standards/testing.md) — testing philosophy and patterns
 
 ### Toolchain
 
-- [Biome](./docs/en/tools/biome.md) - Linting and formatting
-- [Commitlint](./docs/en/tools/commitlint.md) - Commit message validation
-- [Dependencies](./docs/en/tools/dependencies.md) - Safe dependency updates and supply-chain controls
-- [Husky](./docs/en/tools/husky.md) - Git hooks
-- [Markdownlint](./docs/en/tools/markdownlint.md) - Markdown quality
-- [Playwright](./docs/en/tools/playwright.md) - End-to-end testing
-- [Releases](./docs/en/tools/releases.md) - GitLab-flow-based versioning and releases
-- [TypeScript](./docs/en/tools/typescript.md) - Strict TypeScript configuration
-- [Vitest](./docs/en/tools/vitest.md) - Unit and integration testing
+- [Biome](./docs/en/tools/biome.md) — linting and formatting
+- [Commitlint](./docs/en/tools/commitlint.md) — commit-message validation
+- [Dependencies](./docs/en/tools/dependencies.md) — safe dependency updates and supply-chain controls
+- [Husky](./docs/en/tools/husky.md) — git hooks
+- [Markdownlint](./docs/en/tools/markdownlint.md) — markdown quality
+- [Playwright](./docs/en/tools/playwright.md) — end-to-end testing
+- [Releases](./docs/en/tools/releases.md) — branch-based release flow with Changesets
+- [TypeScript](./docs/en/tools/typescript.md) — strict TypeScript configuration
+- [Vitest](./docs/en/tools/vitest.md) — unit and integration testing
 
 ## Portability
 
-While designed for Regardio projects, this toolchain follows well-established standards and can be adopted by any TypeScript project:
+The toolchain is designed for Regardio projects, but nothing about it ties it to Regardio. Any TypeScript project can adopt it:
 
-- All configs extend official tool presets
-- No proprietary conventions or lock-in
-- Standard npm package distribution
-- MIT licensed
+- Configs extend official tool presets
+- No proprietary conventions, no lock-in
+- Distributed as a standard npm package
+- MIT-licensed
 
 ## License
 
 MIT © [Regardio](https://regard.io)
-
-## Acknowledgments
-
-Built on the shoulders of giants: [Biome](https://biomejs.dev/), [TypeScript](https://www.typescriptlang.org/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/), [Vite](https://vitejs.dev/), and the entire open source ecosystem.

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

@@ -45,22 +45,21 @@ function runShipProduction(cwd = process.cwd()) {
 	}
 	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.`);
+	const hasChangesets = existsSync(join(cwd, ".changeset"));
+	if (hasChangesets) {
+		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);
+		}
+		console.log(`\n${pendingChangesets} pending changeset(s) will be consumed.`);
+	}
 	if (!confirm(`Ship ${packageName} to production?`)) {
 		console.log("Aborted.");
 		process.exit(0);
@@ -73,31 +72,33 @@ function runShipProduction(cwd = process.cwd()) {
 		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 {
+	if (hasChangesets) {
+		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");
-		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");
+		git("commit", "-m", "chore(release): version packages");
+	}
 	console.log("\nMerging main into production...");
 	git("checkout", "production");
 	git("pull", "--ff-only", "origin", "production");

package/docs/en/README.md

@@ -1,34 +1,29 @@
 ---
 
-title: @regardio/dev Documentation
-type: guide
-status: published
-summary: Complete documentation for the @regardio/dev toolchain
-related: [coding-standards, development-principles]
-locale: en-US
+title: "@regardio/dev Documentation"
+description: "Index for the @regardio/dev toolchain — code-level standards and the tools that enforce them."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
 ---
 
 # Documentation
 
-Documentation index and quick reference for the `@regardio/dev` toolchain.
+Index for the `@regardio/dev` toolchain.
 
-## Concepts
+Cross-project standards — voice, documentation shape, principles — live at the commons root in [`docs/en/`](../../../../docs/en/README.md). The documents below are the code-level standards and the tools that enforce them.
 
-Foundational principles and standards that guide development:
+## Code standards
 
 | Document | Description |
 |----------|-------------|
-| [AI Agents](./agents.md) | Instructions for AI coding assistants |
-| [API](./standards/api.md) | API design and implementation guidelines |
+| [API](./standards/api.md) | API design and implementation |
 | [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 |
+| [React](./standards/react.md) | React and TypeScript patterns |
+| [SQL](./standards/sql.md) | PostgreSQL schema, structure, access control |
 | [Testing](./standards/testing.md) | Testing philosophy and patterns |
-| [Writing](./standards/writing.md) | Voice, tone, and language |
 
 ## Toolchain
 
@@ -76,7 +71,7 @@ pnpm typecheck     # TypeScript type checking
 | `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`) |
+| `.sqlfluff` | SQL linting (copy from `node_modules/@regardio/dev/templates/sqlfluff/setup.cfg`) |
 
 ### Extending Presets
 

package/docs/en/standards/api.md

@@ -317,7 +317,7 @@ describe('User API', () => {
 - [React](./react.md) — Patterns for the clients that consume the API
 - [SQL](./sql.md) — Naming, structure, and access on the database side
 - [Testing](./testing.md) — Testing philosophy and layers
-- [Principles](./principles.md) — Shared principles
+- [Principles](../../../../../docs/en/principles.md) — Shared principles
 
 ---
 

package/docs/en/standards/coding.md

@@ -134,7 +134,7 @@ An unjustified suppression is a regression.
 
 ## Related
 
-- [Principles](./principles.md) — Shared principles the patterns build on
+- [Principles](../../../../../docs/en/principles.md) — Shared principles the patterns build on
 - [React](./react.md) — Component, hook, and state patterns
 - [Naming](./naming.md) — Names across languages
 - [Testing](./testing.md) — Testing philosophy

package/docs/en/standards/naming.md

@@ -173,7 +173,7 @@ NODE_ENV=production
 - [Coding](./coding.md) — TypeScript and general patterns
 - [SQL](./sql.md) — PostgreSQL naming, structure, and access
 - [Commits](./commits.md) — Branch and commit naming
-- [Writing](./writing.md) — Voice, tone, language
+- [Writing](../../../../../docs/en/writing.md) — Voice, tone, language
 
 ---
 

package/docs/en/standards/react.md

@@ -238,7 +238,7 @@ describe('SearchForm', () => {
 
 - [Coding](./coding.md) — TypeScript patterns React code builds on
 - [Testing](./testing.md) — Testing philosophy and layers
-- [Principles](./principles.md) — Shared principles across the stack
+- [Principles](../../../../../docs/en/principles.md) — Shared principles across the stack
 - [Naming](./naming.md) — Names across languages
 
 ---

package/docs/en/standards/sql.md

@@ -250,8 +250,8 @@ create policy pol_task_update on public.task
 
 - [Naming](./naming.md) — Names across languages
 - [API](./api.md) — How the schema is consumed
-- [Principles](./principles.md) — Shared principles
-- [Writing](./writing.md) — Voice, tone, language
+- [Principles](../../../../../docs/en/principles.md) — Shared principles
+- [Writing](../../../../../docs/en/writing.md) — Voice, tone, language
 
 ---
 

package/docs/en/standards/testing.md

@@ -128,7 +128,7 @@ Before a package publishes:
 
 ## Related
 
-- [Principles](./principles.md) — Shared principles, including specification-led workflow
+- [Principles](../../../../../docs/en/principles.md) — Shared principles, including specification-led workflow
 - [React](./react.md) — How components are shaped to be testable
 - [API](./api.md) — Testing API endpoints and contracts
 - [Vitest](../tools/vitest.md) — Unit and integration testing

package/docs/en/tools/biome.md

@@ -1,20 +1,21 @@
 ---
 
-title: Biome
-type: guide
-status: published
-summary: Fast, unified linting and formatting for JavaScript and TypeScript
-related: [typescript, markdownlint]
-locale: en-US
+title: "Biome"
+description: "Linting and formatting for JavaScript and TypeScript, configured centrally through @regardio/dev."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Biome
 
-Fast, unified linting and formatting for JavaScript and TypeScript. Single tool replacing ESLint + Prettier. Configuration is centralized through `@regardio/dev`; use wrapper commands so all packages behave consistently.
+[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.
 
 ## Configuration
 
-Create `biome.jsonc` in your package root:
+A `biome.jsonc` at the package root is all it takes:
 
 ```jsonc
 {
@@ -36,54 +37,56 @@ Create `biome.jsonc` in your package root:
 }
 ```
 
-## CLI Wrapper
+## CLI wrapper
 
-Use `lint-biome` instead of `biome` directly. This wrapper ensures consistent behavior across the monorepo.
+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 auto-fixable issues
+lint-biome check --write .   # Fix the auto-fixable
 lint-biome format .          # Format only
 ```
 
-## Package.json Handling
+## `package.json` handling
 
-The Biome preset excludes `package.json` files from processing. Instead, use `lint-package` which:
+The Biome preset leaves `package.json` alone. For those files, `lint-package` does the work:
 
-1. Sorts package.json using the well-known field order
-2. Fixes exports condition order (`types` before `default` for TypeScript)
+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 specific package.json
+lint-package path/to/pkg  # Sort a specific package.json
 ```
 
-This is automatically run as part of `pnpm fix`.
+It runs automatically as part of `pnpm fix`.
 
-## Rule Categories
+## Rule categories
 
-The preset enables rules across categories:
+The preset enables rules across:
 
-- **Correctness** - Catch bugs and incorrect code
-- **Style** - Consistent code formatting
-- **Complexity** - Prevent overly complex code
-- **Performance** - Identify performance issues
-- **Security** - Flag potential security vulnerabilities
+- **Correctness** — catch bugs and incorrect code
+- **Style** — consistent code formatting
+- **Complexity** — prevent overly complex code
+- **Performance** — flag performance issues
+- **Security** — flag possible vulnerabilities
 
-## Ignoring Rules
+## Ignoring rules
 
-When a rule genuinely doesn't apply, use inline comments:
+When a rule genuinely doesn't apply, an inline comment names the exception:
 
 ```typescript
 // biome-ignore lint/complexity/noForEach: forEach is clearer here for side effects
 items.forEach(item => process(item));
 ```
 
-Always include a reason explaining why the exception is necessary.
+Always include a reason — an unjustified suppression is a regression waiting to spread.
 
-## Editor Setup
+## Editor integration
 
-- **VS Code**: [Biome extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
-- **JetBrains**: Built-in support via settings
+Most editors pick up `biome.jsonc` automatically through a Biome plugin or built-in support. If the editor formats on save, point it at Biome rather than another formatter so the two don't fight over the same file.
 
-Resources: [Biome Documentation](https://biomejs.dev/) · [Rules Reference](https://biomejs.dev/linter/rules/)
+## Related
+
+- [TypeScript](./typescript.md) — strict TypeScript configuration
+- [Markdownlint](./markdownlint.md) — linting and formatting for Markdown

package/docs/en/tools/commitlint.md

@@ -1,20 +1,21 @@
 ---
 
-title: Commitlint
-type: guide
-status: published
-summary: Enforce conventional commit messages
-related: [husky]
-locale: en-US
+title: "Commitlint"
+description: "Validates commit messages against the conventional format through git hooks."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Commitlint
 
-Validates commit messages against the conventional format via Git hooks. Rules are centralized in `@regardio/dev`.
+Commitlint checks commit messages against the conventional-commits format through git hooks. The rules live in `@regardio/dev`; projects extend them without restating them.
 
 ## Configuration
 
-At the workspace root, create `.commitlintrc.json`:
+At the workspace root, a `.commitlintrc.json`:
 
 ```json
 {
@@ -22,14 +23,14 @@ At the workspace root, create `.commitlintrc.json`:
 }
 ```
 
-Or use a JavaScript config:
+Or, for projects that prefer JavaScript config:
 
 ```javascript
 // commitlint.config.cjs
 module.exports = require('@regardio/dev/commitlint');
 ```
 
-## Commit Format
+## Commit format
 
 ```text
 <type>(<scope>): <subject>
@@ -52,7 +53,7 @@ module.exports = require('@regardio/dev/commitlint');
 | `test` | Adding or updating tests |
 | `build` | Build system or dependencies |
 | `ci` | CI configuration |
-| `chore` | Other changes (tooling, etc.) |
+| `chore` | Other changes (tooling, and so on) |
 | `revert` | Revert a previous commit |
 
 ### Examples
@@ -68,25 +69,20 @@ feat(auth): implement OAuth2 flow
 fix(api): handle null response gracefully
 ```
 
-## Rules
+## Rules the preset enforces
 
-The preset enforces:
+- **Header max length** — 100 characters
+- **Body leading blank** — blank line before the body
+- **Footer leading blank** — blank line before the footer
+- **Type enum** — one of the allowed types, nothing exotic
 
-- **Header max length**: 100 characters
-- **Body leading blank**: Blank line before body
-- **Footer leading blank**: Blank line before footer
-- **Type enum**: Must be one of the allowed types
+## Git hooks
 
-## Git Hooks
+Commitlint runs automatically through Husky on commit. See [Husky](./husky.md) for setup.
 
-Commitlint runs automatically via Husky on commit. See [Husky](./husky.md) for setup.
+## Related
 
-Related documents:
-
-- [Commit Conventions](../standards/commits.md) — Conventional commits and changelog generation
-- [Husky](./husky.md) — Git hooks for quality gates
-
-### Resources
-
-- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Commits](../standards/commits.md) — conventional commits and changelog generation
+- [Husky](./husky.md) — git hooks for quality gates
+- [Conventional Commits](https://www.conventionalcommits.org/) — the specification behind all this
 - [Commitlint Documentation](https://commitlint.js.org/)