build: move to a Turborepo monorepo with Bun and Ultracite

.agents/skills/ultracite/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ultracite
+description: "Ultracite is a zero-config linting and formatting preset for JavaScript/TypeScript projects. Use when: (1) Setting up or initializing Ultracite in a project (ultracite init), (2) Running linting or formatting commands (check, fix, doctor), (3) Writing or reviewing JS/TS code in a project that uses Ultracite — to follow its code standards, (4) Troubleshooting linting/formatting issues, (5) User mentions 'ultracite', 'lint', 'format', 'code quality', or 'biome/eslint/oxlint' in a project with Ultracite installed."
+---
+
+# Ultracite
+
+Zero-config linting and formatting for JS/TS projects. Supports three linter backends: **Oxlint** + Oxfmt (recommended), **Biome**, and **ESLint** + Prettier + Stylelint.
+
+## Detecting Ultracite
+
+Check if `ultracite` is in `package.json` dependencies or devDependencies. Detect the active linter by looking for (searching upward from the current directory):
+
+- `biome.json` / `biome.jsonc` → Biome
+- `eslint.config.*` (`.mjs`, `.js`, `.cjs`, `.ts`, `.mts`, `.cts`) → ESLint (with Prettier for formatting)
+- `oxlint.config.ts` → Oxlint (with `oxfmt.config.ts` for formatting)
+
+## CLI Commands
+
+```bash
+# Check for issues (read-only)
+bunx ultracite check
+
+# Auto-fix issues
+bunx ultracite fix
+
+# Diagnose setup problems
+bunx ultracite doctor
+
+# Initialize in a new project
+bunx ultracite init
+```
+
+Replace `bunx` with `npx`, `pnpm exec`, or `yarn` depending on the package manager, so the project's installed Ultracite runs (`pnpm dlx` and `yarn dlx` download the latest release instead, and Yarn 1 has no `dlx`). Only `init` in a project without Ultracite needs a download runner such as `pnpm dlx`.
+
+`check` and `fix` accept optional file paths: `bunx ultracite check src/index.ts`. Unknown options are passed through to the underlying linter (e.g. `bunx ultracite check --max-warnings 0`).
+
+## Initialization
+
+`bunx ultracite init` runs an interactive setup. For non-interactive (CI) use, pass flags:
+
+```bash
+bunx ultracite init \
+  --pm bun \
+  --linter biome \
+  --editors universal \
+  --agents claude copilot \
+  --frameworks react next \
+  --integrations husky lint-staged \
+  --quiet
+```
+
+**Flags:**
+
+- `--pm` — `npm` | `yarn` | `pnpm` | `bun` | `deno` | `nub` | `aube`
+- `--linter` — `oxlint` (recommended) | `biome` | `eslint`
+- `--editors` — `universal` (writes `.vscode/settings.json` for every VS Code-based editor) | `vscode` | `cursor` | `windsurf` | `codebuddy` | `antigravity` | `bob` | `kiro` | `trae` | `void` | `zed`
+- `--agents` — `universal` (writes `AGENTS.md`) | `claude` | `codex` | `copilot` | `cline` | `amp` | `gemini` | `cursor-cli` + 34 more (41 agents supported)
+- `--frameworks` — `react` | `next` | `solid` | `vue` | `svelte` | `qwik` | `remix` | `tanstack` | `angular` | `astro` | `nestjs` | `jest` | `vitest`
+- `--integrations` — `husky` | `lefthook` | `lint-staged` | `pre-commit`
+- `--hooks` — Enable auto-fix hooks: `claude` | `copilot` | `cursor` | `windsurf` | `codebuddy`
+- `--js-plugins` — Opt-in Oxlint JS plugins: `@shadcn/lint` | `anti-slop` | `eslint-plugin-github` | `eslint-plugin-sonarjs` | `oxlint-plugin-react-doctor`
+- `--type-aware` — Enable type-aware linting (Biome: extends the `type-aware` preset; Oxlint: installs `oxlint-tsgolint`)
+- `--install-skill` — Install the reusable Ultracite skill after setup
+- `--skip-install` — Skip dependency installation
+- `--quiet` — Suppress prompts (auto-detected when `CI=true`); defaults to `oxlint` when `--linter` is omitted
+
+Init creates config that extends Ultracite presets:
+
+```jsonc
+// biome.jsonc
+{ "extends": ["ultracite/biome/core", "ultracite/biome/react"] }
+```
+
+```ts
+// eslint.config.mjs — arrays of flat configs, spread together
+import core from "ultracite/eslint/core";
+import react from "ultracite/eslint/react";
+export default [...core, ...react];
+```
+
+```ts
+// oxlint.config.ts — imports passed to extends
+import { defineConfig } from "oxlint";
+import core from "ultracite/oxlint/core";
+export default defineConfig({
+  extends: [core],
+  ignorePatterns: core.ignorePatterns,
+});
+```
+
+Presets available per linter (`ultracite/<linter>/<preset>`): `core`, `react`, `next`, `solid`, `vue`, `svelte`, `qwik`, `remix`, `tanstack`, `angular`, `astro`, `nestjs`, `jest`, `vitest`. Biome also has `type-aware`. Oxlint also has `js-plugins` (`eslint-plugin-github`, `eslint-plugin-sonarjs` and `oxlint-plugin-react-doctor` run through oxlint's JS plugin support, with `next/js-plugins` and `tanstack/js-plugins` adding framework-specific React Doctor rules), `anti-slop` and `shadcn`. These are opt-in: init only adds them when picked in its prompt or passed with `--js-plugins`.
+
+## Code Standards
+
+When writing code in a project with Ultracite, follow these standards. For the full rules reference, see [references/code-standards.md](references/code-standards.md).
+
+Key rules at a glance:
+
+Formatting is handled by the project's configured linter/formatter. Respect the repository's existing formatter settings instead of forcing one fixed line width, quote style, or trailing comma policy.
+
+**Type safety:** Use explicit types when they improve clarity. Prefer `unknown` over `any`. Use `as const` for immutable values and rely on type narrowing over blunt assertions.
+
+**Modern JavaScript/TypeScript:** Prefer `const`, destructuring, optional chaining, nullish coalescing, template literals, `for...of`, and concise arrow functions.
+
+**Async and correctness:** Always `await` promises in async functions. Prefer `async/await` over promise chains. Remove `console.log`, `debugger`, and `alert` from production code.
+
+**React and accessibility:** Use function components, keep hooks top-level with correct deps, avoid nested component definitions, and use semantic HTML with the right labels, headings, alt text, and keyboard affordances.
+
+**Organization, security, performance, and testing:** Keep functions focused, prefer early returns, avoid `dangerouslySetInnerHTML` and `eval()`, prefer specific imports and top-level regex, and keep tests free of `.only` and `.skip`.
+
+## Troubleshooting
+
+Run `bunx ultracite doctor` to diagnose. It checks:
+
+1. Linter and formatter installation (Biome; or ESLint + Prettier + Stylelint; or Oxlint + oxfmt)
+2. Config validity (extends the ultracite presets correctly)
+3. Ultracite in package.json dependencies
+4. Conflicting tools (legacy `.eslintrc.*` files; `.prettierrc.*`/`prettier.config.*` when not using the ESLint backend)
+
+Common fixes:
+
+- **Conflicting configs**: Delete legacy `.eslintrc.*` and `.prettierrc.*` files after migrating to Ultracite
+- **Missing dependency**: Run `bunx ultracite init` again or manually add `ultracite` to devDependencies
+- **Rules not applying**: Ensure config file extends the correct presets for your framework

.agents/skills/ultracite/references/code-standards.md

@@ -0,0 +1,102 @@
+# Ultracite Code Standards
+
+Formatting is intentionally handled by your project's configured linter or formatter. Respect the repository's existing quote, width, semicolon, trailing comma, and line ending settings instead of forcing one global formatting style.
+
+## Core Principles
+
+Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity.
+
+## Type Safety & Explicitness
+
+- Use explicit types for function parameters and return values when they enhance clarity
+- Prefer `unknown` over `any` when the type is genuinely unknown
+- Use const assertions (`as const`) for immutable values and literal types
+- Leverage TypeScript's type narrowing instead of type assertions
+- Use meaningful variable names instead of magic numbers — extract constants with descriptive names
+
+## Modern JavaScript/TypeScript
+
+- Use arrow functions for callbacks and short functions
+- Prefer `for...of` loops over `.forEach()` and indexed `for` loops
+- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
+- Prefer template literals over string concatenation
+- Use destructuring for object and array assignments
+- Use `const` by default, `let` only when reassignment is needed, never `var`
+
+## Async & Promises
+
+- Always `await` promises in async functions — don't forget to use the return value
+- Use `async/await` syntax instead of promise chains for better readability
+- Handle errors appropriately in async code with try-catch blocks
+- Don't use async functions as Promise executors
+
+## React & JSX
+
+- Use function components over class components
+- Call hooks at the top level only, never conditionally
+- Specify all dependencies in hook dependency arrays correctly
+- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
+- Nest children between opening and closing tags instead of passing as props
+- Don't define components inside other components
+- Use semantic HTML and ARIA attributes for accessibility:
+  - Provide meaningful alt text for images
+  - Use proper heading hierarchy
+  - Add labels for form inputs
+  - Include keyboard event handlers alongside mouse events
+  - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles
+
+## Error Handling & Debugging
+
+- Remove `console.log`, `debugger`, and `alert` statements from production code
+- Throw `Error` objects with descriptive messages, not strings or other values
+- Use `try-catch` blocks meaningfully — don't catch errors just to rethrow them
+- Prefer early returns over nested conditionals for error cases
+
+## Code Organization
+
+- Keep functions focused and under reasonable cognitive complexity limits
+- Extract complex conditions into well-named boolean variables
+- Use early returns to reduce nesting
+- Prefer simple conditionals over nested ternary operators
+- Group related code together and separate concerns
+
+## Security
+
+- Add `rel="noopener"` when using `target="_blank"` on links
+- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
+- Don't use `eval()` or assign directly to `document.cookie`
+- Validate and sanitize user input
+
+## Performance
+
+- Avoid spread syntax in accumulators within loops
+- Use top-level regex literals instead of creating them in loops
+- Prefer specific imports over namespace imports
+- Avoid barrel files (index files that re-export everything)
+- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
+
+## Framework-Specific
+
+**Next.js:** Use `<Image>` component for images. Use `next/head` or the App Router metadata API for head elements. Use Server Components for async data fetching instead of async Client Components.
+
+**React 19+:** Use ref as a prop instead of `React.forwardRef`.
+
+**Solid/Svelte/Vue/Qwik:** Use `class` and `for` attributes (not `className` or `htmlFor`).
+
+## Testing
+
+- Write assertions inside `it()` or `test()` blocks
+- Avoid done callbacks in async tests — use async/await instead
+- Don't use `.only` or `.skip` in committed code
+- Keep test suites reasonably flat — avoid excessive `describe` nesting
+
+## When Your Linter Can't Help
+
+Your configured linter or formatter will catch most mechanical issues automatically. Focus your attention on:
+
+1. Business logic correctness
+2. Meaningful naming
+3. Architecture decisions
+4. Edge cases
+5. User experience
+6. Documentation for genuinely complex logic

.changeset/README.md

@@ -1,3 +1,3 @@
 # Changesets
 
-Each file in this directory describes one change for the next release. Run `npx changeset` to add one, and see [docs/releasing.md](../docs/releasing.md) for the whole flow.
+Each file in this directory describes one change for the next release. Run `bun changeset` to add one, and see [docs/releasing.md](../docs/releasing.md) for the whole flow.

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "bun run fix --hook",
+            "type": "command"
+          }
+        ],
+        "matcher": "Write|Edit"
+      }
+    ]
+  }
+}

.claude/skills/ultracite

@@ -0,0 +1 @@
+../../.agents/skills/ultracite

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Learn how to add code owners here:
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+* @PunGrumpy

.github/ISSUE_TEMPLATE/0-bug-report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Report a trace, check or command that gives the wrong result
+labels: ["bug"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening a new issue, please [search](https://github.com/PunGrumpy/plumb/issues) the existing issues and :+1: the one that matches instead.
+
+        If a trace ends with a code such as `route-missing`, run `plumb explain <code>` and read [troubleshooting](https://github.com/PunGrumpy/plumb/blob/main/docs/troubleshooting.md) first.
+
+  - type: checkboxes
+    attributes:
+      label: Verify latest release
+      description: Some issues are already fixed. Install the [latest release](https://github.com/PunGrumpy/plumb/releases/latest) and check that the issue still happens.
+      options:
+        - label: I verified that the issue exists in the latest plumb release.
+          required: true
+
+  - type: input
+    attributes:
+      label: plumb version
+      description: The output of `plumb version`.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Environment information
+      render: block
+      description: |
+        Run `plumb doctor` and paste its output here, then add the OpenStack and OpenSDN releases of the cloud. Please remove host names and addresses you don't want to share.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Command
+      render: sh
+      description: The exact command you ran, with any secrets removed.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Actual behavior
+      description: The output you got. Run the command again with `--debug` if the HTTP calls help explain it.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: |
+        Anything else that helps. If you can, attach the directory from `--record DIR` as a `.zip`. It lets us replay your trace with `--replay DIR`, and it doesn't contain your password.

.github/ISSUE_TEMPLATE/1-feature-request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest a new command, check or layer for plumb to trace
+labels: ["enhancement"]
+
+body:
+  - type: textarea
+    attributes:
+      label: What problem do you want plumb to solve?
+      description: "Example: When a VM can't reach the metadata service, I check the link-local route on the vRouter by hand."
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: How would you like it to work?
+      description: The command, flag or output you have in mind.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: The OpenStack and OpenSDN APIs involved, or links to their docs.

.github/ISSUE_TEMPLATE/2-docs.yml

@@ -0,0 +1,26 @@
+name: "Documentation update or improvement"
+description: A request to update or improve documentation
+title: "Docs: "
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for helping us improve the docs! If you can fix it yourself, a pull request is welcome too.
+  - type: textarea
+    attributes:
+      label: What is the improvement or update you wish to see?
+      description: "Example: The quickstart doesn't say which role `plumb doctor` needs."
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Is there any context that might help us understand?
+      description: A clear description of any added context that might help us understand.
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Does the docs page already exist? Please link to it.
+      description: "Example: https://github.com/PunGrumpy/plumb/blob/main/docs/quickstart.md"
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/PunGrumpy/plumb/tree/main/docs
+    about: Read the quickstart, CLI reference and troubleshooting guide.