@regardio/dev 1.6.0 → 1.7.0

package/README.md

@@ -1,453 +1,87 @@
 # @regardio/dev
 
-Developer tooling for testing, linting, and build workflows in Regardio projects.
+A unified developer toolchain for consistent, high-quality TypeScript projects.
 
-## Philosophy
-
-We believe in **balanced strictness**: rigorous enough to catch bugs early and maintain consistency, yet practical enough to not impede development velocity.
+## Purpose
 
-### Strict by Default
+`@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.
 
-- **TypeScript strict mode** with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`
-- **Comprehensive linting** via Biome for code quality, style, and complexity
-- **Conventional commits** enforced through commitlint
-- **Automated testing** as a first-class concern
+**One dependency. Zero configuration conflicts. Consistent quality across all projects.**
 
-### Practical in Application
+## Philosophy
 
-Strictness serves developers, not the other way around. Our approach:
+We believe in **balanced strictness**: rigorous enough to catch bugs early and maintain consistency, yet practical enough to not impede development velocity.
 
+- **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
-- **Clear exceptions** - When rules don't apply, document why with `// biome-ignore` or `@ts-expect-error`
-
-### The Balance
-
-We optimize for:
-
-1. **Catching bugs before they ship** - Strict types prevent runtime errors
-2. **Readable, maintainable code** - Consistent style reduces cognitive load
-3. **Developer experience** - Tools should help, not hinder
-4. **Team velocity** - Shared understanding through enforced conventions
 
-Exceptions are allowed but must be intentional and documented. The goal is code that's correct, consistent, and a pleasure to work with.
+The goal is code that's correct, consistent, and a pleasure to work with.
 
-## What's inside
+## What's Inside
 
-- **CLI bins**: exec-clean, exec-husky, exec-p, exec-s, exec-ts, exec-tsc, flow-release, lint-biome, lint-commit, lint-md
-- **Config presets**: Biome, Commitlint, Markdownlint, TypeScript (base/react)
-- **Testing configs**: Vitest (node/react), Playwright base config, Testing Library setup
-- **Dev dependencies**: All commonly needed testing and linting packages bundled
-- **[Developer Documentation](./docs/README.md)**: Foundational principles, testing philosophy, naming conventions
+| Category | Tools |
+|----------|-------|
+| **Linting** | Biome, Markdownlint, Commitlint |
+| **Testing** | Vitest, Playwright, Testing Library |
+| **Build** | TypeScript, tsx, Vite |
+| **Workflow** | Husky, Changesets |
+| **CLI utilities** | exec-clean, exec-p, exec-s, exec-ts, flow-release, lint-biome, lint-md |
 
-## Install
+## Quick Start
 
 ```bash
 pnpm add -D @regardio/dev
 ```
 
-## Testing
-
-### Vitest Configuration
-
-```typescript
-// vitest.config.ts (Node.js package)
-import { defineConfig } from 'vitest/config';
-import { vitestNodeConfig } from '@regardio/dev/vitest/node';
-
-export default defineConfig({ test: vitestNodeConfig });
-```
-
-```typescript
-// vitest.config.ts (React package)
-import { defineConfig } from 'vitest/config';
-import { vitestReactConfig } from '@regardio/dev/vitest/react';
-
-export default defineConfig({ test: vitestReactConfig });
-```
-
-### Playwright Configuration
-
-```typescript
-// playwright.config.ts
-import { defineConfig, devices } from '@playwright/test';
-import { buildPlaywrightBaseConfig } from '@regardio/dev/playwright';
-
-export default defineConfig(
-  buildPlaywrightBaseConfig({
-    appPort: 5100,
-    appUrl: 'http://localhost:5100',
-    devices,
-    webServerCommand: 'vite preview',
-  }),
-);
-```
-
-### Testing Library Setup
-
-For React packages, create a `src/test-setup.ts`:
-
-```typescript
-import '@regardio/dev/testing/setup-react';
-```
-
-## Config Presets
-
-- **Biome**: `"extends": ["@regardio/dev/biome"]`
-- **TypeScript**: `@regardio/dev/typescript/base.json`, `@regardio/dev/typescript/react.json`
-- **Commitlint**: `module.exports = require('@regardio/dev/commitlint');`
-- **Markdownlint**: `"extends": "@regardio/dev/markdownlint"`
-
-## Scripts (examples)
-
-```json
-{
-  "scripts": {
-    "fix": "exec-p fix:*",
-    "fix:biome": "lint-biome check --write --unsafe .",
-    "fix:md": "lint-md --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
-    "lint": "exec-p lint:*",
-    "lint:biome": "lint-biome check .",
-    "lint:md": "lint-md \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
-    "prepare": "exec-husky",
-    "test": "exec-p test:*",
-    "test:e2e": "playwright test",
-    "test:unit": "vitest run",
-  }
-}
-```
-
-## Local Config Files
-
-Each package needs a few local config files that extend the shared presets. Here's the minimal setup:
-
-### Required Files
-
-All config files should be placed in the **package root** (same level as `package.json`):
-
-| File | Purpose | Extends |
-|------|---------|---------|
-| `tsconfig.json` | TypeScript base config | `@regardio/dev/typescript/base.json` or `react.json` |
-| `tsconfig.build.json` | Build-specific config | `./tsconfig.json` + `@regardio/dev/typescript/build.json` |
-| `biome.jsonc` | Linting and formatting | `@regardio/dev/biome` |
-| `.commitlintrc.json` | Commit message linting | `@regardio/dev/commitlint` (workspace root only) |
-| `.markdownlint.jsonc` | Markdown linting | `@regardio/dev/markdownlint` |
-| `vitest.config.ts` | Unit test config | Uses `vitestNodeConfig` or `vitestReactConfig` |
-| `playwright.config.ts` | E2E test config | Uses `buildPlaywrightBaseConfig` |
-| `.hintrc` | webhint config (optional) | `development` preset |
-
-### File Naming Conventions
-
-- **JSON configs**: Use the standard names expected by each tool
-  - `.commitlintrc.json` (not `commitlint.config.json`)
-  - `.markdownlint.jsonc` (supports comments)
-  - `biome.jsonc` (supports comments, Biome also accepts `biome.json`)
-- **TypeScript configs**: Always `tsconfig*.json`
-- **Test configs**: `vitest.config.ts`, `playwright.config.ts`
-- **Hidden files**: Prefix with `.` for tool-specific configs (`.hintrc`, `.editorconfig`)
-
-### Workspace Root vs Package Root
-
-| Location | Files |
-|----------|-------|
-| **Workspace root** | `.editorconfig`, `.commitlintrc.json`, `.gitignore`, AI agent configs |
-| **Each package** | `tsconfig.json`, `tsconfig.build.json`, `biome.jsonc`, `.markdownlint.jsonc`, test configs |
-
-### Example: tsconfig.json (Node.js package)
-
-```json
-{
-  "extends": "@regardio/dev/typescript/base.json",
-  "include": ["src/**/*.ts"]
-}
-```
-
-### Example: tsconfig.build.json
-
-```json
-{
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "extends": ["./tsconfig.json", "@regardio/dev/typescript/build.json"],
-  "include": ["src/**/*.ts"]
-}
-```
-
-### Example: biome.jsonc
+Extend the shared configs in your project:
 
 ```jsonc
-{
-  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
-  "extends": ["@regardio/dev/biome"]
-}
-```
-
-## Code Quality Philosophy
-
-### Strictness by Default
-
-We enforce strict checks across the codebase:
-
-- **TypeScript**: `strict: true`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`
-- **Biome**: Comprehensive lint rules for correctness, style, and complexity
-- **Commits**: Conventional commit format enforced via commitlint
-
-### Why So Strict?
-
-1. **Catch bugs early** - Strict type checking prevents entire categories of runtime errors
-2. **Consistent codebase** - Uniform style reduces cognitive load when reading code
-3. **Self-documenting** - Explicit types and patterns make intent clear
-4. **Refactoring confidence** - Strong types enable safe, large-scale changes
-
-### Exceptions: Few and Intentional
-
-We allow very few exceptions, and each must be justified:
-
-- **`// biome-ignore`** - Only when the rule genuinely doesn't apply, don't use it just to make the linter happy. Always add a comment explaining why the exception is necessary.
-- **`@ts-expect-error`** - Only for known TypeScript limitations with an explanatory comment. Always include a reason for the exception.
-- **`eslint-disable`** - We don't use ESLint directly; all linting is handled by Biome. If you encounter an ESLint rule that needs to be disabled, discuss it with the team first and document the reasoning.
-
-The goal is balance: strict enough to prevent bugs, flexible enough to not block legitimate patterns.
-
-## Editor & AI Configuration
-
-### EditorConfig
-
-Create `.editorconfig` at the workspace root:
-
-```ini
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = tab
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-indent_style = space
-trim_trailing_whitespace = false
+// biome.jsonc
+{ "extends": ["@regardio/dev/biome"] }
 
-[*.{yml,yaml}]
-indent_style = space
+// tsconfig.json
+{ "extends": "@regardio/dev/typescript/base.json" }
 ```
 
-### AI Agent Configuration
+## Documentation
 
-These files help AI coding assistants understand project conventions.
+Detailed documentation is organized by topic:
 
-#### Claude (CLAUDE.md)
+### Concepts
 
-```markdown
-# Project Guidelines
+- [Development Principles](./docs/concepts/development-principles.md) - Code quality, architecture, maintainability
+- [Coding Standards](./docs/concepts/coding-standards.md) - TypeScript, React, and general patterns
+- [Naming Conventions](./docs/concepts/naming-conventions.md) - Consistent naming across languages
+- [Commit Conventions](./docs/concepts/commits.md) - Conventional commits and changelog generation
+- [Testing Approach](./docs/concepts/testing.md) - Testing philosophy and patterns
+- [AI Agent Guidelines](./docs/concepts/ai-agents.md) - Instructions for AI coding assistants
 
-## Code Style
-- Use TypeScript with strict mode
-- Follow Biome formatting (tabs, no semicolons where optional)
-- Prefer functional patterns over classes
+### Toolchain
 
-## Testing
-- Unit tests with Vitest, E2E with Playwright
-- Test files: `*.test.ts` or `*.test.tsx`
+- [TypeScript](./docs/toolchain/typescript.md) - Strict TypeScript configuration
+- [Biome](./docs/toolchain/biome.md) - Linting and formatting
+- [Vitest](./docs/toolchain/vitest.md) - Unit and integration testing
+- [Playwright](./docs/toolchain/playwright.md) - End-to-end testing
+- [Commitlint](./docs/toolchain/commitlint.md) - Commit message validation
+- [Markdownlint](./docs/toolchain/markdownlint.md) - Markdown quality
+- [Husky](./docs/toolchain/husky.md) - Git hooks
+- [Changesets](./docs/toolchain/changesets.md) - Versioning and releases
 
-## Commits
-- Use conventional commits: `feat:`, `fix:`, `docs:`, etc.
-```
-
-#### Gemini (.gemini/settings.json)
-
-```json
-{
-  "codeStyle": {
-    "language": "typescript",
-    "formatter": "biome",
-    "indentation": "tabs"
-  },
-  "testing": {
-    "framework": "vitest",
-    "e2e": "playwright"
-  }
-}
-```
-
-#### Windsurf (.windsurf/rules.md)
-
-```markdown
-# Windsurf Rules
-
-- Extend shared configs from `@regardio/dev`
-- Use `pnpm` for package management
-- Follow conventional commits
-- Prefer minimal, focused edits
-```
-
-#### Cursor (.cursor/rules.md)
-
-```markdown
-# Cursor Rules
-
-## Project Structure
-- Monorepo with pnpm workspaces
-- Shared tooling in `packages/dev`
-
-## Coding Standards
-- TypeScript strict mode
-- Biome for linting and formatting
-- Vitest for unit tests, Playwright for E2E
-
-## Workflow
-- Run `pnpm lint` before committing
-- Use conventional commit messages
-```
-
-## Bundled Dependencies
-
-When you add `@regardio/dev` as a dev dependency, you get access to:
+## Portability
 
-- **Testing**: vitest, @vitest/ui, @playwright/test, @testing-library/react, @testing-library/jest-dom, jsdom
-- **Linting**: @biomejs/biome, markdownlint-cli2, @commitlint/cli
-- **Build**: typescript, tsx, vite, husky
-- **Release**: @changesets/cli for versioning and publishing
-
-## Releasing
-
-This package uses [Changesets](https://github.com/changesets/changesets) for versioning and npm publishing, with a streamlined `flow-release` command that automates the entire process.
-
-### Quick Release (Recommended)
-
-The `flow-release` command handles everything in one step:
-
-```bash
-# From the package directory:
-pnpm release minor "Add new vitest configs"
-
-# Or use the bin directly after build:
-flow-release patch "Fix typo in config"
-flow-release minor "Add new feature"
-flow-release major "Breaking API change"
-```
-
-This command:
-
-1. Creates a changeset file with the specified bump type and message
-2. Runs `changeset version` to update package.json and CHANGELOG
-3. Updates the lockfile (`pnpm install --ignore-workspace`)
-4. Commits all changes with `chore(release): vX.Y.Z`
-5. Pushes to the current branch
-
-The GitHub Action then publishes to npm automatically.
-
-### Manual Release (Step by Step)
-
-If you prefer more control:
-
-```bash
-pnpm changeset              # Interactive: create changeset file
-git add . && git commit     # Commit the changeset
-git push                    # Push to trigger GitHub Action
-# GitHub Action creates "Version Packages" PR
-# Merge that PR → publishes to npm
-```
+While designed for Regardio projects, this toolchain follows well-established standards and can be adopted by any TypeScript project:
 
-### Reusing in Other Packages
-
-The `flow-release` bin is available to any package that depends on `@regardio/dev`:
-
-```json
-{
-  "scripts": {
-    "release": "flow-release"
-  }
-}
-```
-
-Then run:
-
-```bash
-pnpm release minor "Your release message"
-```
-
-**Requirements for other packages:**
-
-1. A `.changeset/config.json` file (copy from this package and update `repo`)
-2. A `.github/workflows/release.yml` (copy from this package)
-3. GitHub repo configured with NPM_TOKEN secret and Actions permissions
-
-### GitHub Repository Setup
-
-Before the release action works, configure these in **GitHub repo settings**:
-
-#### 1. NPM_TOKEN Secret
-
-```text
-Settings → Secrets and variables → Actions → New repository secret
-Name: NPM_TOKEN
-Value: <your npm access token with publish permissions>
-```
-
-To create an npm token:
-
-```bash
-npm login
-npm token create --read-only=false
-```
-
-#### 2. GitHub Actions Permissions
-
-```text
-Settings → Actions → General → Workflow permissions
-☑ Read and write permissions
-☑ Allow GitHub Actions to create and approve pull requests
-```
-
-#### 3. Branch Protection Ruleset
-
-```text
-Settings → Rules → Rulesets → New ruleset → New branch ruleset
-
-Ruleset Name: main-protection
-Enforcement: Active
-Target: Add target → Include by pattern → main
-
-Rules to enable:
-☑ Restrict deletions
-☑ Require a pull request before merging
-☑ Require status checks to pass
-  - Require up to date: ☑
-  - Status checks: Release (appears after first workflow run)
-☑ Block force pushes
-```
-
----
+- All configs extend official tool presets
+- No proprietary conventions or lock-in
+- Standard npm package distribution
+- MIT licensed
 
 ## License
 
 MIT © [Regardio](https://regard.io)
 
-## Contact
-
-- **Website**: [regard.io](https://regard.io)
-- **GitHub**: [@regardio](https://github.com/regardio)
-- **Email**: [bernd.matzner@regard.io](mailto:bernd.matzner@regard.io)
-
 ## Acknowledgments
 
-This project stands on the shoulders of giants. We're deeply grateful to the Open Source community and the maintainers of the tools that make this possible:
-
-- [Biome](https://biomejs.dev/) - The Biome team
-- [commitlint](https://commitlint.js.org/) - The commitlint team
-- [Husky](https://typicode.github.io/husky/) - typicode and contributors
-- [markdownlint](https://github.com/DavidAnson/markdownlint) - David Anson and contributors
-- [Playwright](https://playwright.dev/) - Microsoft
-- [pnpm](https://pnpm.io/) - Zoltan Kochan and contributors
-- [React](https://react.dev/) - Meta and contributors
-- [TypeScript](https://www.typescriptlang.org/) - Microsoft and contributors
-- [Vite](https://vitejs.dev/) - Evan You and the Vite team
-- [Vitest](https://vitest.dev/) - Anthony Fu and the Vitest team
-
-And countless other projects that form the foundation of modern web development. Thank you for sharing your work with the world. 💚
+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/flow-release.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 const args = process.argv.slice(2);
 const bumpType = args[0];
@@ -17,6 +17,18 @@ const run = (cmd) => {
 const runQuiet = (cmd) => {
     return execSync(cmd, { encoding: 'utf-8' }).trim();
 };
+const packageJsonPath = join(process.cwd(), 'package.json');
+if (!existsSync(packageJsonPath)) {
+    console.error('No package.json found in current directory');
+    process.exit(1);
+}
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const packageName = packageJson.name;
+if (!packageName) {
+    console.error('No "name" field found in package.json');
+    process.exit(1);
+}
+console.log(`Releasing ${packageName} with ${bumpType} bump...`);
 try {
     const status = runQuiet('git status --porcelain');
     if (status) {
@@ -28,24 +40,35 @@ catch {
     process.exit(1);
 }
 const changesetDir = join(process.cwd(), '.changeset');
+const changesetConfigPath = join(changesetDir, 'config.json');
+if (!existsSync(changesetConfigPath)) {
+    console.error('No .changeset/config.json found.');
+    console.error('Run: pnpm changeset init');
+    console.error('Then configure .changeset/config.json for your package.');
+    process.exit(1);
+}
+mkdirSync(changesetDir, { recursive: true });
+const existingChangesets = readdirSync(changesetDir).filter((f) => f.endsWith('.md') && f !== 'README.md');
+for (const file of existingChangesets) {
+    unlinkSync(join(changesetDir, file));
+    console.log(`Removed existing changeset: ${file}`);
+}
 const changesetId = `release-${Date.now()}`;
 const changesetFile = join(changesetDir, `${changesetId}.md`);
 const changesetContent = `---
-"@regardio/dev": ${bumpType}
+"${packageName}": ${bumpType}
 ---
 
 ${message}
 `;
-mkdirSync(changesetDir, { recursive: true });
 writeFileSync(changesetFile, changesetContent);
 console.log(`Created changeset: .changeset/${changesetId}.md`);
 run('pnpm changeset version');
 console.log('Updating lockfile...');
 run('pnpm install --ignore-workspace');
 run('git add -A');
-const packageJsonPath = join(process.cwd(), 'package.json');
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-const { version } = packageJson;
+const updatedPackageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const { version } = updatedPackageJson;
 run(`git commit -m "chore(release): v${version}"`);
 const branch = runQuiet('git branch --show-current');
 run(`git push origin ${branch}`);

package/package.json

@@ -17,11 +17,11 @@
     "url": "https://github.com/regardio/dev/issues"
   },
   "dependencies": {
-    "@biomejs/biome": "2.3.10",
+    "@biomejs/biome": "2.3.11",
     "@changesets/changelog-github": "0.5.2",
     "@changesets/cli": "2.29.8",
-    "@commitlint/cli": "20.2.0",
-    "@commitlint/config-conventional": "20.2.0",
+    "@commitlint/cli": "20.3.0",
+    "@commitlint/config-conventional": "20.3.0",
     "@playwright/test": "1.57.0",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.1",
@@ -66,10 +66,7 @@
       "types": "./dist/vitest/react.d.ts"
     }
   },
-  "files": [
-    "dist",
-    "src"
-  ],
+  "files": ["dist", "src"],
   "homepage": "https://github.com/regardio/dev/blob/main/README.md",
   "keywords": [
     "biome",
@@ -105,7 +102,7 @@
     "lint": "run-p lint:*",
     "lint:biome": "biome check .",
     "lint:md": "markdownlint-cli2 \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
-    "prepare": "pnpm run build && husky",
+    "prepare": "husky",
     "release": "pnpm exec tsx src/bin/flow-release.ts",
     "test": "run-p test:*",
     "test:unit": "vitest run",
@@ -113,5 +110,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "1.6.0"
+  "version": "1.7.0"
 }

package/src/bin/flow-release.ts

@@ -1,20 +1,34 @@
 #!/usr/bin/env node
 /**
- * flow-release: Automate the release flow for @regardio/dev.
+ * flow-release: Automate the release flow for any @regardio package.
  *
  * Usage: flow-release <patch|minor|major> [message]
  *
  * This script:
- * 1. Creates a changeset file with the specified bump type
- * 2. Runs `changeset version` to apply the version bump
- * 3. Updates the lockfile (pnpm install --ignore-workspace)
- * 4. Commits all changes
- * 5. Pushes to the current branch
+ * 1. Reads the package name from package.json
+ * 2. Creates a changeset file with the specified bump type
+ * 3. Runs `changeset version` to apply the version bump
+ * 4. Updates the lockfile (pnpm install --ignore-workspace)
+ * 5. Commits all changes
+ * 6. Pushes to the current branch
  *
  * The GitHub Action will then publish to npm automatically.
+ *
+ * Prerequisites for adopting packages:
+ * - Add @regardio/dev as a devDependency
+ * - Create .changeset/config.json (see template in dev docs)
+ * - Add .github/workflows/release.yml (see template in dev docs)
+ * - Add "release": "flow-release" to package.json scripts
  */
 import { execSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { join } from 'node:path';
 
 const args = process.argv.slice(2);
@@ -36,6 +50,25 @@ const runQuiet = (cmd: string): string => {
   return execSync(cmd, { encoding: 'utf-8' }).trim();
 };
 
+// Read package name from package.json
+const packageJsonPath = join(process.cwd(), 'package.json');
+if (!existsSync(packageJsonPath)) {
+  console.error('No package.json found in current directory');
+  process.exit(1);
+}
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as {
+  name: string;
+  version: string;
+};
+const packageName = packageJson.name;
+
+if (!packageName) {
+  console.error('No "name" field found in package.json');
+  process.exit(1);
+}
+
+console.log(`Releasing ${packageName} with ${bumpType} bump...`);
+
 // Ensure we're in a clean git state
 try {
   const status = runQuiet('git status --porcelain');
@@ -47,20 +80,39 @@ try {
   process.exit(1);
 }
 
-// Generate a unique changeset filename
+// Verify .changeset/config.json exists
 const changesetDir = join(process.cwd(), '.changeset');
+const changesetConfigPath = join(changesetDir, 'config.json');
+if (!existsSync(changesetConfigPath)) {
+  console.error('No .changeset/config.json found.');
+  console.error('Run: pnpm changeset init');
+  console.error('Then configure .changeset/config.json for your package.');
+  process.exit(1);
+}
+
+// Clean up existing changesets to ensure only our bump type is applied
+mkdirSync(changesetDir, { recursive: true });
+
+const existingChangesets = readdirSync(changesetDir).filter(
+  (f) => f.endsWith('.md') && f !== 'README.md',
+);
+for (const file of existingChangesets) {
+  unlinkSync(join(changesetDir, file));
+  console.log(`Removed existing changeset: ${file}`);
+}
+
+// Generate a unique changeset filename
 const changesetId = `release-${Date.now()}`;
 const changesetFile = join(changesetDir, `${changesetId}.md`);
 
-// Create the changeset file
+// Create the changeset file with dynamic package name
 const changesetContent = `---
-"@regardio/dev": ${bumpType}
+"${packageName}": ${bumpType}
 ---
 
 ${message}
 `;
 
-mkdirSync(changesetDir, { recursive: true });
 writeFileSync(changesetFile, changesetContent);
 console.log(`Created changeset: .changeset/${changesetId}.md`);
 
@@ -75,10 +127,11 @@ run('pnpm install --ignore-workspace');
 // Stage all changes
 run('git add -A');
 
-// Get the new version
-const packageJsonPath = join(process.cwd(), 'package.json');
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as { version: string };
-const { version } = packageJson;
+// Re-read package.json to get the new version after changeset version
+const updatedPackageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8')) as {
+  version: string;
+};
+const { version } = updatedPackageJson;
 
 // Commit
 run(`git commit -m "chore(release): v${version}"`);

package/src/templates/changeset-config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "access": "public",
+  "baseBranch": "main",
+  "changelog": ["@changesets/changelog-github", { "repo": "regardio/REPO_NAME" }],
+  "commit": false,
+  "fixed": [],
+  "ignore": [],
+  "linked": [],
+  "updateInternalDependencies": "patch"
+}

package/src/templates/changeset-readme.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/src/templates/release.yml

@@ -0,0 +1,83 @@
+# Regardio Release Workflow
+# Copy this file to .github/workflows/release.yml in your package
+#
+# Required setup:
+# 1. Create .changeset/config.json (see changeset-config.json template)
+# 2. Add "release": "flow-release" to package.json scripts
+# 3. Configure NPM_TOKEN secret in GitHub repository settings
+#    OR use npm provenance with OIDC (recommended, no secret needed)
+#
+# Usage:
+# - Run `pnpm release patch|minor|major "message"` locally
+# - Push to main branch
+# - This workflow publishes to npm and creates a GitHub release
+
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm for OIDC support
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        id: publish
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          PUBLISHED_VERSION=$(npm view "$PACKAGE_NAME" version 2>/dev/null || echo '0.0.0')
+          echo "package_name=$PACKAGE_NAME" >> $GITHUB_OUTPUT
+          echo "current_version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          if [ "$PUBLISHED_VERSION" != "$CURRENT_VERSION" ]; then
+            echo "Publishing $PACKAGE_NAME@$CURRENT_VERSION (npm has v$PUBLISHED_VERSION)"
+            npm publish --access public --provenance
+            echo "published=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version $CURRENT_VERSION already published, skipping"
+            echo "published=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create GitHub Release
+        if: steps.publish.outputs.published == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.publish.outputs.current_version }}
+          name: v${{ steps.publish.outputs.current_version }}
+          body_path: CHANGELOG.md
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}