@regardio/dev 1.24.0 → 2.0.2

package/docs/en/tools/dependencies.md

@@ -0,0 +1,116 @@
+---
+
+title: Dependency Handling
+type: guide
+status: published
+summary: Safe dependency updates and supply-chain controls for Regardio workspaces
+related: [releases, typescript, vitest]
+locale: en-US
+---
+
+# Dependency Handling
+
+Dependency update workflow and supply-chain controls for Regardio workspaces. Automated updates are combined with pnpm guardrails; the lockfile is authoritative.
+
+## Update workflow
+
+- Use `pnpm ncu` to prepare workspace dependency upgrades
+- Install through `pnpm` so workspace-level safety settings are applied
+- Run the normal verification flow after updates:
+
+The root `ncu` script uses a 1-day cooldown so it does not propose versions that are newer than the workspace release-age policy.
+
+```bash
+pnpm audit
+pnpm build
+pnpm lint
+pnpm test
+pnpm typecheck
+```
+
+For larger automated upgrade passes, use the existing safety wrapper:
+
+```bash
+pnpm safe-upgrade
+```
+
+## Workspace safety settings
+
+The root `pnpm-workspace.yaml` defines the main supply-chain controls.
+
+### Allow-listed dependency builds
+
+Regardio keeps dependency build scripts restricted through `onlyBuiltDependencies`.
+
+This means dependencies cannot start running build or postinstall steps unless they are already trusted and listed explicitly. If a package that previously needed no build step suddenly adds one in a compromised release, pnpm will not execute it automatically.
+
+When a legitimate dependency genuinely needs a build step, add it deliberately to the allow-list and review why it is required.
+
+### Block exotic transitive dependencies
+
+```yaml
+blockExoticSubdeps: true
+```
+
+This prevents transitive dependencies from resolving through git URLs, tarballs, or other non-registry sources.
+
+### Delay newly published versions
+
+```yaml
+minimumReleaseAge: 1440
+```
+
+We wait 24 hours before pnpm may install a newly published version. This gives time for compromised packages to be detected and removed before they reach the workspace.
+
+The root `ncu` script mirrors this with `--cooldown 1`, which helps align version selection with the install policy. pnpm still remains the authoritative enforcement point during installation.
+
+### Prevent trust downgrades
+
+```yaml
+trustPolicy: no-downgrade
+```
+
+If a package release becomes less trustworthy than earlier releases, pnpm rejects the installation instead of silently accepting the downgrade.
+
+`npm-check-updates` does not enforce trust policy, build-script allow-lists, or exotic transitive source restrictions. Those safeguards only take effect when `pnpm install` resolves and installs dependencies.
+
+## Lockfile discipline
+
+- Commit `pnpm-lock.yaml`
+- Review lockfile changes together with manifest changes
+- Prefer normal installs over ad hoc per-package package manager commands so the workspace lock remains authoritative
+
+## Reviewing dependency updates
+
+When an automated update lands, review:
+
+- whether the package is direct or transitive
+- whether the update adds or changes a build requirement
+- whether the package affects runtime, build tooling, or release tooling
+- whether overrides should be added for newly disclosed vulnerabilities
+
+## Shipping dependency changes
+
+Dependency updates follow the same release gates as any other change.
+
+- verify locally before shipping
+- keep changelog subjects clear when a release is primarily dependency maintenance
+- use provenance when publishing public packages
+
+## When to make an exception
+
+Exceptions should stay explicit and rare.
+
+Examples:
+
+- adding a package to `onlyBuiltDependencies`
+- introducing a workspace override for a vulnerable transitive dependency
+- reducing the release-age delay for a security-critical emergency update
+
+When an exception is necessary, document the reason in the change itself so later readers can understand why the safer default was not enough.
+
+Related documents:
+
+- [Release Workflow](./releases.md) — Automated release process for Regardio packages
+- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
+- [TypeScript Configuration](./typescript.md) — TypeScript setup and configuration for Regardio projects

package/docs/en/tools/husky.md

@@ -0,0 +1,90 @@
+---
+
+title: Husky
+type: guide
+status: published
+summary: Git hooks for quality gates
+related: [commitlint, biome]
+locale: en-US
+---
+
+# Husky
+
+Runs quality checks at commit time via Git hooks. Configured through `@regardio/dev`; bypass only in genuine emergencies.
+
+## Setup
+
+Husky is configured automatically via the `prepare` script:
+
+```json
+{
+  "scripts": {
+    "prepare": "exec-husky"
+  }
+}
+```
+
+This runs after `pnpm install` and sets up the `.husky` directory.
+
+## Hooks
+
+### commit-msg
+
+Validates commit messages against conventional commit format:
+
+```bash
+#!/bin/sh
+pnpm lint-commit --edit $1
+```
+
+### pre-commit (optional)
+
+Run linting before commit:
+
+```bash
+#!/bin/sh
+pnpm lint
+```
+
+## CLI Wrapper
+
+Use `exec-husky` instead of `husky` directly. This wrapper handles monorepo scenarios correctly.
+
+## Bypassing Hooks
+
+In rare cases where you need to skip hooks:
+
+```bash
+git commit --no-verify -m "emergency fix"
+```
+
+Use sparingly and only when absolutely necessary.
+
+## Troubleshooting
+
+### Hooks not running
+
+Ensure Husky is installed:
+
+```bash
+pnpm install
+```
+
+Check that `.husky` directory exists and contains hook files.
+
+### Permission denied
+
+Make hooks executable:
+
+```bash
+chmod +x .husky/*
+```
+
+Related documents:
+
+- [Commitlint](./commitlint.md) — Commit message validation
+- [Biome](./biome.md) — Linting and formatting
+
+### Resources
+
+- [Husky Documentation](https://typicode.github.io/husky/)

package/docs/en/tools/markdownlint.md

@@ -0,0 +1,84 @@
+---
+
+title: Markdownlint
+type: guide
+status: published
+summary: Linting and formatting for Markdown files
+related: [biome]
+locale: en-US
+---
+
+# Markdownlint
+
+Lints Markdown structure and formatting. Rules are centralized in `@regardio/dev`; use the `lint-md` wrapper instead of calling the tool directly.
+
+## Configuration
+
+Create `.markdownlint.json` in your package root:
+
+```json
+{
+  "extends": "@regardio/dev/markdownlint"
+}
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "fix:md": "lint-md --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
+    "lint:md": "lint-md \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\""
+  }
+}
+```
+
+## CLI Wrapper
+
+Use `lint-md` instead of `markdownlint-cli2` directly:
+
+```bash
+lint-md "**/*.md"              # Check all Markdown files
+lint-md --fix "**/*.md"        # Auto-fix issues
+```
+
+## Key Rules
+
+| Rule | Description |
+|------|-------------|
+| MD001 | Heading levels increment by one |
+| MD003 | Consistent heading style (ATX) |
+| MD009 | No trailing spaces |
+| MD012 | No multiple consecutive blank lines |
+| MD022 | Headings surrounded by blank lines |
+| MD032 | Lists surrounded by blank lines |
+| MD041 | First line should be a top-level heading |
+
+## Ignoring Rules
+
+For specific files or sections:
+
+```markdown
+<!-- markdownlint-disable MD013 -->
+This line can be very long without triggering a warning.
+<!-- markdownlint-enable MD013 -->
+```
+
+Or in config for specific files:
+
+```json
+{
+  "extends": "@regardio/dev/markdownlint",
+  "ignores": ["CHANGELOG.md"]
+}
+```
+
+Related documents:
+
+- [Documentation](../standards/documentation.md) — Structure and conventions
+- [Biome](./biome.md) — Fast, unified linting and formatting
+
+### Resources
+
+- [Markdownlint Rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
+- [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)

package/docs/en/tools/playwright.md

@@ -0,0 +1,117 @@
+---
+
+title: Playwright
+type: guide
+status: published
+summary: End-to-end testing for web applications
+related: [vitest]
+locale: en-US
+---
+
+# Playwright
+
+End-to-end testing for web applications. Prefer role-based, accessible selectors. Use E2E tests for critical user workflows, not as a substitute for unit or integration tests.
+
+## 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',
+  }),
+);
+```
+
+## Scripts
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test"
+  }
+}
+```
+
+## Running Tests
+
+```bash
+pnpm test:e2e                    # Run all E2E tests
+pnpm playwright test --ui        # Interactive UI mode
+pnpm playwright test --debug     # Debug mode with inspector
+pnpm playwright show-report      # View HTML report
+```
+
+## Writing Tests
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('user can submit contact form', async ({ page }) => {
+  await page.goto('/contact');
+
+  await page.getByLabel('Email').fill('user@example.com');
+  await page.getByLabel('Message').fill('Hello!');
+  await page.getByRole('button', { name: 'Submit' }).click();
+
+  await expect(page.getByText('Message sent')).toBeVisible();
+});
+```
+
+## Best Practices
+
+### Use Role-Based Selectors
+
+```typescript
+// Preferred - accessible and resilient
+await page.getByRole('button', { name: 'Submit' });
+await page.getByLabel('Email');
+
+// Avoid - brittle
+await page.locator('.submit-btn');
+await page.locator('#email-input');
+```
+
+### Add data-test Attributes
+
+For elements without accessible names:
+
+```tsx
+<div data-test="user-avatar">{avatar}</div>
+```
+
+```typescript
+await page.getByTestId('user-avatar');
+```
+
+### Page Object Pattern
+
+For complex pages, use page objects:
+
+```typescript
+class LoginPage {
+  constructor(private page: Page) {}
+
+  async login(email: string, password: string) {
+    await this.page.getByLabel('Email').fill(email);
+    await this.page.getByLabel('Password').fill(password);
+    await this.page.getByRole('button', { name: 'Sign in' }).click();
+  }
+}
+```
+
+Related documents:
+
+- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
+- [Vitest](./vitest.md) — Unit and integration testing for TypeScript projects
+
+### Resources
+
+- [Playwright Documentation](https://playwright.dev/)
+- [Best Practices](https://playwright.dev/docs/best-practices)

package/docs/en/tools/releases.md

@@ -0,0 +1,242 @@
+---
+
+title: Release Workflow
+type: guide
+status: published
+summary: GitLab-flow release process with Changesets for Regardio packages
+related: [commitlint]
+locale: en-US
+---
+
+# Release Workflow
+
+Branch-based release workflow for Regardio packages. `main` → `staging` → `production`. Versioning is driven by [Changesets](https://github.com/changesets/changesets); quality gates run locally before any branch promotion.
+
+## Overview
+
+Branches mirror deployment environments:
+
+```text
+main → staging (optional) → production
+```
+
+- **`main`** — active development, always deployable. Authors add a changeset (`pnpm changeset`) alongside each version-worthy change.
+- **`staging`** — optional validation environment. No versioning happens here.
+- **`production`** — versioned, published code only.
+
+Changesets decide what bumps. When `ship-production` runs, it consumes every pending changeset, bumps affected packages, rewrites each package's `CHANGELOG.md`, and commits the result on `main` before merging to `production`. CI on `production` runs `changeset publish` to push the new versions to npm.
+
+## How It Works
+
+### Design principles
+
+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. **Changesets drive versioning.** A bump is declared in a `.changeset/*.md` file alongside the code change, not chosen at ship time. Every published version corresponds to a set of consumed changesets.
+3. **Version numbers are a production guarantee.** Bumps are applied only at `ship-production` time. This means 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. Either way, `staging` is automatically synced with `production` after each ship.
+5. **Tests are a local gate, not a CI gate.** Quality checks (`build`, `typecheck`, `test`) run on your machine before any commit is made. Broken code cannot enter the repository. CI only runs `build` and `publish`.
+6. **You always land back on `main`.** Every command returns you to `main` when it finishes.
+
+### Full flow diagram
+
+```text
+                    pnpm changeset           (on main, alongside your change)
+                    ┌──────────────────────────┐
+                    │ write .changeset/<x>.md  │
+main ───────────────┤ commit + push            ├──► main
+                    └──────────────────────────┘
+                                │
+                    ship-staging (OPTIONAL)
+                    ┌──────────────────────────┐
+main ───────────────┤ quality checks pass      ├──► staging (pushed)
+                    │ ff-merge main → staging  │
+                    └──────────────────────────┘
+                                │
+                           (validated in staging)
+                                │
+                                ▼
+                    ship-production
+                    ┌──────────────────────────┐
+                    │ quality checks on main   │
+                    │ pnpm changeset version   │
+main ───────────────┤ bumps + CHANGELOG.md     ├──► production
+                    │ chore(release): ...      │
+                    │ ff-merge main → prod     │
+                    │ ff-merge prod → staging  │
+                    │ sync back to main        │
+                    └──────────────────────────┘
+                                │
+                           (CI: pnpm changeset publish → npm + git tags)
+                                ▼
+                           production
+
+
+                    ship-hotfix start fix-name
+                    ┌──────────────────────────┐
+production ─────────┤ create hotfix/fix-name   ├──► hotfix/fix-name
+                    └──────────────────────────┘
+                                │
+                       (author fixes + pnpm changeset)
+                                │
+                    ship-hotfix finish
+                    ┌──────────────────────────┐
+                    │ quality checks           │
+                    │ pnpm changeset version   │
+hotfix/fix-name ────┤ bumps + CHANGELOG.md     ├──► production → staging → main
+                    │ merge to production      │
+                    │ propagate to staging     │
+                    │ propagate to main        │
+                    └──────────────────────────┘
+```
+
+### What each branch represents at any point in time
+
+| Branch | Contains | Version bumped? |
+|--------|----------|-----------------|
+| `main` | All committed, tested work + pending `.changeset/*.md` files | 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 |
+
+### CI role
+
+CI is intentionally minimal. It does not re-run tests. On push to `production` it:
+
+1. Installs dependencies and builds
+2. Runs `pnpm changeset publish` — publishes every workspace package whose current version is not yet on npm, skipping `private: true` packages, and creates git tags per published package
+3. Pushes the tags
+
+## Commands
+
+| Command | Usage | Purpose |
+|---------|-------|---------|
+| `pnpm changeset` | interactive | Declare a version bump alongside your change |
+| `ship-staging` | `ship-staging` | (Optional) Deploy changes to staging for testing |
+| `ship-production` | `ship-production` | Consume changesets, 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` | Consume changesets, propagate hotfix through production → staging → main |
+
+Bump types (`patch` / `minor` / `major`) are no longer passed on the command line — they come from the changeset files.
+
+## Typical Release Flow
+
+### 1. Author a change with a changeset
+
+On `main`:
+
+```bash
+# make your code change
+pnpm changeset          # choose packages, bump type, write a one-line description
+git add .
+git commit -m "feat: ..."
+git push
+```
+
+A file like `.changeset/lively-otters-hop.md` is committed with the change.
+
+### 2. Ship to production
+
+```bash
+pnpm ship:production
+```
+
+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, report pending changeset count, ask for confirmation
+4. Run full quality suite on `main` — aborts on failure
+5. Run `pnpm changeset version` — bumps versions, rewrites `CHANGELOG.md` per package, deletes consumed changeset files
+6. Format modified files
+7. Commit with `chore(release): version packages` on `main`
+8. Fast-forward merge `main` into `production` and push
+9. Sync `staging` with `production`
+10. Return to `main`
+
+CI on `production` runs `pnpm changeset publish` to push the new versions to npm and create tags.
+
+### Option: Test in staging first
+
+```bash
+pnpm ship:staging
+```
+
+Deploys `main` to `staging` without touching versions. Useful for validating in a staging environment before shipping to production.
+
+## Hotfix Flow
+
+For urgent fixes that must go directly to production:
+
+```bash
+pnpm ship:hotfix start fix-auth-bug
+# apply your fix
+pnpm changeset          # describe the fix and the bump
+git add . && git commit -m "fix: ..."
+pnpm ship:hotfix finish
+```
+
+`finish` consumes the pending changeset, bumps the version, then merges `hotfix → production → staging → main` and deletes the hotfix branch. CI publishes from `production`.
+
+## Adoption
+
+Install `@regardio/dev` and:
+
+1. **Initialize Changesets** — copy the template:
+
+   ```bash
+   cp -r node_modules/@regardio/dev/templates/changeset .changeset
+   ```
+
+2. **Add the scripts to `package.json`**:
+
+   ```json
+   {
+     "scripts": {
+       "changeset": "changeset",
+       "changeset:publish": "changeset publish",
+       "changeset:version": "changeset version",
+       "ship:hotfix": "ship-hotfix",
+       "ship:production": "ship-production",
+       "ship:staging": "ship-staging"
+     }
+   }
+   ```
+
+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
+   ```
+
+4. **Copy the release workflow** for your forge:
+
+   ```bash
+   mkdir -p .github/workflows
+   cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+   ```
+
+5. **First publish of any new package must be done locally**:
+
+   ```bash
+   pnpm build && npm publish --access public
+   ```
+
+## Quality Gates
+
+Every ship command enforces the same gates — no broken code reaches any environment:
+
+```bash
+pnpm build      # Must succeed
+pnpm typecheck  # Must succeed
+pnpm test       # Must succeed
+```
+
+## Private Packages
+
+Packages that should never be published to npm must set `"private": true` in `package.json`. `changeset publish` skips them automatically. The git flow (`ship-staging`, `ship-production`, `ship-hotfix`) works identically for private packages — changesets, version bumps, and branch promotion all continue as normal; only the npm publish step is skipped.
+
+Related documents:
+
+- [Commit Conventions](../standards/commits.md) — Conventional commits for consistent history
+- [Commitlint](./commitlint.md) — Commit message validation