Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: improve repo agent experience (#2569)
Maximilian Kaske274784cb0ee7
diff --git a/.github/workflows/buf-push.yml b/.github/workflows/buf-push.ymlindex 12ff5ab5f..33e039593 100644--- a/.github/workflows/buf-push.yml+++ b/.github/workflows/buf-push.yml@@ -32,7 +32,7 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π₯ Download depsdiff --git a/.github/workflows/check.yml b/.github/workflows/check.ymlindex 19510a393..a19ed3e0d 100644--- a/.github/workflows/check.yml+++ b/.github/workflows/check.yml@@ -24,16 +24,23 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π¦ Setup Denouses: denoland/setup-deno@v2with:- deno-version: v2.x+ deno-version: 2.9.4- name: π₯ Download depsrun: pnpm install+ # Blocking, unlike autofix.ci, which only commits formatting back.+ - name: π¬ Lint+ run: pnpm lint++ - name: π Doc references+ run: pnpm check:docs+- name: π Checkrun: pnpm checkdiff --git a/.github/workflows/dx.yml b/.github/workflows/dx.ymlindex 766bae466..6ddfb91d3 100644--- a/.github/workflows/dx.yml+++ b/.github/workflows/dx.yml@@ -35,7 +35,7 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π₯ Download deps@@ -44,7 +44,7 @@ jobs:- name: π¦ Setup Denouses: denoland/setup-deno@v2with:- deno-version: v2.x+ deno-version: 2.9.4- name: π₯ DX taskrun: pnpm dxdiff --git a/.github/workflows/lint.yml b/.github/workflows/lint.ymlindex 7169323ca..32aec6e4a 100644--- a/.github/workflows/lint.yml+++ b/.github/workflows/lint.yml@@ -25,7 +25,7 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π₯ Download depsdiff --git a/.github/workflows/migrate.yml b/.github/workflows/migrate.ymlindex 1770625c2..5d80891bd 100644--- a/.github/workflows/migrate.yml+++ b/.github/workflows/migrate.yml@@ -23,13 +23,13 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π¦ Install denouses: denoland/setup-deno@v2with:- deno-version: v2.x+ deno-version: 2.9.4- name: π₯ Download depsrun: pnpm installdiff --git a/.github/workflows/proto-check.yml b/.github/workflows/proto-check.ymlindex 3568dcab6..2ee4684a8 100644--- a/.github/workflows/proto-check.yml+++ b/.github/workflows/proto-check.yml@@ -32,7 +32,7 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π₯ Install bundiff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex 9e5c5fac7..b46e29eb1 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -66,13 +66,13 @@ jobs:- name: β Setup nodeuses: actions/setup-node@v6with:- node-version: 24+ node-version: 24.12.0cache: "pnpm"- name: π¦ Setup Denouses: denoland/setup-deno@v2with:- deno-version: v2.x+ deno-version: 2.9.4- name: π₯ Download depsrun: pnpm installdiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..da50576aa--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,91 @@+# AGENTS.md++Cross-cutting truth for openstatus. Package-scoped rules live in the nested+`AGENTS.md` files listed at the bottom. Setup and how-to-run belong in READMEs β+this file never restates them.++## Verify your change++```sh+pnpm verify # oxfmt + oxlint + doc refs + deno check. No database, seconds.+pnpm verify:test # tests for packages affected by your diff. Needs a database.+```++`pnpm verify` must be green before you hand work back β it is what CI's `Check`+job runs. For `verify:test`, start the local libSQL and seed it first; the steps+are in `apps/dashboard/README.md`.++## Toolchain++`devbox.json` pins exact node, deno, bun, turso-cli and sqld versions; the CI+workflows pin the same node and deno. Never float one back to `@latest` or+`v2.x` β `deno check` results differ by deno version, so a drifting pin makes+`pnpm verify` disagree with CI for reasons unrelated to your change.++## Architecture++- **`packages/services`** owns every workspace-scoped mutation. tRPC routers,+ Hono routes, MCP tools and jobs are thin adapters over it. Inline DB access in+ a router is a defect β see `packages/services/AGENTS.md`.+- **Turso (libSQL) holds application data**, through Drizzle in `packages/db`.+ **Tinybird holds monitoring time-series**, through `packages/tinybird`. The two+ are linked by id only: no cross-store transaction, no join across the boundary,+ no referential integrity.+- **Go is confined to the probing tier** (`apps/checker`, `apps/private-location`).+ Product logic stays in TypeScript. Anything duplicated across that boundary β+ assertion evaluation, region codes β must be changed on both sides in one PR.+- **Shared UI comes from `@openstatus/ui`.** Do not fork a primitive into an app.++## Tests++- CI gives every DB-touching package its own database (the matrix in+ `.github/workflows/test.yml`). Locally there is one shared libSQL, which is+ why `verify:test` runs the affected packages one at a time. Cross-package+ failures that vanish on a re-run of the single package are that sharing, not+ your change β confirm with `turbo run test --filter=@openstatus/services`.+- Suites mint their own workspace via `createTestWorkspace`+ (`packages/db/src/test/factories.ts`). Never load a shared seeded workspace,+ and never wipe a table globally β scope every cleanup to your own workspace id.+- The `external_service` suites are not workspace-scoped; an aborted run leaves+ rows that fail the *next* local run on a foreign key. Reseed to recover.+- The `test` turbo task is deliberately uncached β results depend on database+ state that is not in the input hash. Do not "fix" it.++## Comment discipline++Default to no comments. Code and identifiers already say *what*. Write a comment+only when the *why* is not visible: a non-obvious invariant, a workaround for a+specific bug, a constraint imposed from outside the file, a `// safe because β¦`+above an unavoidable cast.++- 1 short line where possible, 3 lines max. Never multi-paragraph JSDoc.+- Strip: restatements of the code, the name of the caller, history ("added for+ X"), PR or task context. That belongs in the commit message.+- JSDoc on an exported symbol is fine when the signature alone is ambiguous β+ one sentence, not a tutorial.++## Type cast discipline++`as unknown as X`, `as never` and `as any` are sometimes unavoidable at+boundaries with external SDKs or at registry-style dispatch. When you need one:++- **Centralize it in a named helper** whose name states the intent+ (`asUIMessages`, `renderToolDraft`). Do not scatter the same cast.+- **Comment the runtime guarantee** above the helper, so a future reader can+ check whether it still holds.+- A scattered `as never` is usually a missing helper.++## Package context++- `packages/services/AGENTS.md` β service verbs, audit log, scope enforcement+- `packages/ui/AGENTS.md` β stock shadcn vs. the published blocks registry+- `apps/dashboard/AGENTS.md` β Next.js runtimes, client boundary, UI verification+- `apps/server/AGENTS.md` β Hono API, API-key scopes+- `apps/status-page/AGENTS.md` β public surfaces and gated content+- `apps/workflows/AGENTS.md` β Deno runtime constraints+- `apps/checker/AGENTS.md` β Go probing tier+- `apps/web/AGENTS.md` β marketing site, `.well-known`, search, content pages++`docs/adr/` is frozen background on *why* some of these decisions were made. It+is history, not current state; this file and its nested siblings are current+state. Do not add new ADRs.diff --git a/CLAUDE.md b/CLAUDE.mdindex a621d75cf..af50da6d0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,161 +1,4 @@-# Agent.md+# CLAUDE.md-This file provides a comprehensive overview of the OpenStatus project, its architecture, and development conventions to be used as instructional context for future interactions.--## Project Overview--OpenStatus is an open-source synthetic monitoring platform. It allows users to monitor their websites and APIs from multiple locations and receive notifications when they are down or slow.--The project is a monorepo managed with pnpm workspaces and Turborepo. It consists of several applications and packages that work together to provide a complete monitoring solution.--### Core Technologies--- **Frontend:**- - Next.js (with Turbopack)- - React- - Tailwind CSS- - shadcn/ui- - tRPC-- **Backend:**- - Hono (Node.js framework)- - Go-- **Database:**- - Turso (libSQL)- - Drizzle ORM-- **Data Analytics:**- - Tinybird-- **Authentication:**- - NextAuth.js-- **Build System:**- - Turborepo--### Architecture--The OpenStatus platform is composed of three main applications:--- **`apps/dashboard`**: A Next.js application that provides the main user interface for managing monitors, viewing status pages, and configuring notifications.-- **`apps/server`**: A Hono-based backend server that provides the API for the dashboard application.-- **`apps/checker`**: A Go application responsible for performing the actual monitoring checks from different locations.--These applications are supported by a collection of shared packages in the `packages/` directory, which provide common functionality such as database access, UI components, and utility functions.--## Building and Running--The project can be run using Docker (recommended) or a manual setup.--### With Docker--1. Copy the example environment file:- ```sh- cp .env.docker.example .env.docker- ```-2. Start all services:- ```sh- docker compose up -d- ```-3. Access the applications:- - Dashboard: `http://localhost:3002`- - Status Pages: `http://localhost:3003`--### Manual Setup--1. Install dependencies:- ```sh- pnpm install- ```-2. Initialize the development environment:- ```sh- pnpm dx- ```-3. Run a specific application:- ```sh- pnpm dev:dashboard- pnpm dev:status-page- pnpm dev:web- ```--### Running Tests--To run the test suite, use the following command:--Before running the test you should launch turso dev in a separate terminal:-```sh-turso dev-```--Then, seed the database with test data:--```sh-cd packages/db-pnpm migrate-pnpm seed-```--Then run the tests with:--```sh-pnpm test-```--## Development Conventions--- **Monorepo:** The project is organized as a monorepo using pnpm workspaces. All applications and packages are located in the `apps/` and `packages/` directories, respectively.-- **Build System:** Turborepo is used to manage the build process. The `turbo.json` file defines the build pipeline and dependencies between tasks.-- **Linting and Formatting:** The project uses oxlint for linting and oxfmt for formatting. The configuration can be found in `oxlint.config.ts` and `oxfmt.config.ts`.-- **Code Generation:** The project uses `drizzle-kit` for database schema migrations.-- **API:** The backend API is built using Hono and tRPC. The API is documented using OpenAPI.--## Comment Discipline--Default to writing no comments. The code and identifiers should explain *what* β the reader can see that. Only write a comment when the *why* would not be obvious from reading the code: a non-obvious invariant, a workaround for a specific bug, a runtime guarantee that justifies a cast, a constraint imposed from outside this file.--- **Keep them to 1 short line where possible**, 3 lines max. Never write multi-paragraph JSDoc blocks.-- **Strip these every time:** restating what the code does, naming the caller / surface that uses the helper, history ("added for X", "used by the Y flow"), and PR/task context. That belongs in commit messages, not source.-- **Keep these:** the WHY behind a non-obvious choice, an invariant that callers must uphold, a `// safe because β¦` line above an unavoidable cast, a `// workaround: <bug>` for a known issue.-- **JSDoc:** allowed on exported symbols when the type signature alone is ambiguous β but one sentence, not a tutorial. Don't enumerate every branch of a function in prose.--If you find yourself writing a comment that explains *what just changed* or *what you did*, delete it.--## Type Cast Discipline--`as unknown as X`, `as never`, and `as any` are sometimes unavoidable β usually at boundaries with external SDKs (AI SDK, third-party libs) or at registry-style dispatch where TypeScript can't link a runtime string to a literal-keyed map. When you need one:--- **Centralize the cast in a named helper.** Don't scatter the same cast across call sites. Wrap it in a small function whose name describes the intent (`asUIMessages`, `findRenderer`, `renderToolDraft`).-- **Comment the runtime guarantee.** Above the helper, write one or two lines explaining *why the cast is safe at runtime* (e.g. "the persisted shape is validated on write by `storedMessageSchema`, so reads return SDK-conforming rows"). Future readers can verify the invariant or notice when it breaks.-- **Examples:** `apps/dashboard/src/components/chat/use-chat-session.ts` (`asUIMessages`); `apps/dashboard/src/components/chat/tool-renderers/index.tsx` (`renderToolDraft` / `renderToolResult` / `summarizeToolOutput`). Both eliminate scattered casts in the consuming components.--A scattered `as never` is usually a missing helper.--## Services & Audit Log Pattern--All workspace-scoped business logic lives in `packages/services` β **not** in tRPC routers. Routers stay thin: validate input, call a service verb, map errors. This keeps logic reusable across tRPC, Hono, and background jobs.--Note on runtimes: the dashboard's tRPC handler runs on the **Node.js** runtime (see the comment in `apps/dashboard/src/app/api/trpc/lambda/[trpc]/route.ts` β several routers pull Node-only deps), and no Edge route imports `@openstatus/services`. Node-only dependencies in services are therefore acceptable. What *is* enforced: `apps/workflows` runs on Deno and imports services, so `pnpm check` (`deno check --sloppy-imports`) must pass in both packages.--Conventions for any new mutation:--- **One file per verb** under `packages/services/src/<entity>/` (e.g. `create.ts`, `update.ts`, `remove.ts`), re-exported from the entity's `index.ts`. Routers import from `@openstatus/services/<entity>`.-- **Standard signature:** `async function verbEntity(args: { ctx: ServiceContext; input: VerbInput }): Promise<...>`. `ctx` carries `workspace`, `actor`, and an optional `db`/transaction. Parse input with the schema at the top of the function.-- **Wrap mutations in `withTransaction(ctx, async (tx) => { ... })`** β it reuses an outer tx if present, otherwise opens one. Always pass `tx` (not `defaultDb`) to writes inside the block.-- **Workspace scoping is mandatory.** Every read/write filters by `ctx.workspace.id`. Use the `getXInWorkspace` helpers in `internal.ts` for fetch-or-throw.-- **Throw `ServiceError` subclasses** (`NotFoundError`, `ForbiddenError`, etc. from `./errors`). Routers convert them via `toTRPCError`.-- **Emit an audit row for every mutation** via `emitAudit(tx, ctx, entry)` inside the same transaction. Fail-closed: a failed audit insert rolls back the mutation. See `packages/services/src/audit/emit.ts`.- - For updates, pass both `before` (pre-mutation snapshot) and `after` (post-`.returning()` row). `changed_fields` is auto-diffed; no-op updates are skipped.- - For creates/deletes, pass only `after` or only `before`.- - **Strip secrets** from snapshots before emitting (e.g. `credential`, bot tokens, raw API keys) β see `integration/remove.ts` for the pattern.- - Action names follow `{entity}.{verb}` (`monitor.update`, `integration.delete`). Add new variants to the discriminated union in `@openstatus/db/src/schema/audit_logs/validation.ts`.-- **Tests live in `packages/services/src/<entity>/__tests__/`** and use `expectAuditRow({ workspaceId, action, entityId, ... })` from `packages/services/test/helpers.ts` to assert the audit side-effect. Each suite scopes to its own workspace and clears `audit_log` between cases.--When adding a router endpoint, the default answer is "write the service verb first, then call it from the router." Inline DB access in routers is a smell β it bypasses the audit log.--## Scope Enforcement (API key RBAC)--API keys carry **scopes** (`'read'` / `'write'`) that gate write access. See `packages/services/src/auth/`.--- **Call `requireScope(ctx, "write")` as the first line** of every write verb β before `Input.parse(...)` and `withTransaction`. Import from `../auth`.-- **"Write"** = any DB mutation **or** side-effecting external call (probes, webhooks, notifications). Everything else is read.-- No-op for `user` / `system` / `slack` / `webhook` / `subscriber` actors; active for `apiKey` and `mcp`. Throws `ForbiddenError` on denial.-- **Tests:** every entity's `__tests__/` includes a `'rejects read-only actor'` case via `makeApiKeyCtx(workspace, { keyId: "k", userId: 1, scopes: ["read"] })`. `requireScope` fires before DB lookup, so fake ids work for delete/update verbs.-- **MCP tools** declare `scope: 'read' | 'write'` and register via `registerScopedTool` β read-only keys never see write tools.--Treat a missing `requireScope` the same as a missing `emitAudit` β mandatory for every mutation.+Read `AGENTS.md` in this directory β it holds the conventions for this repo, and+the nested `AGENTS.md` files it links carry the package-specific ones.diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.mdsimilarity index 83%rename from CONTRIBUTING.MDrename to CONTRIBUTING.mdindex 1f0b9e606..0625cf948 100644--- a/CONTRIBUTING.MD+++ b/CONTRIBUTING.md@@ -29,10 +29,13 @@ To contribute code changes, follow these steps:1. Fork the repository and create a new branch for your changes.2. Ensure that your code follows the project's coding conventions and style guide.-3. Make commits with clear and descriptive messages. Each commit should have a single logical purpose.-4. Push your branch to your forked repository.-5. Open a pull request (PR) from your branch to the original repository's `main` branch.-6. Provide a detailed description of your changes in the PR, including any related issues or feature requests.+3. Run `pnpm verify` β formatting, lint, doc references and type checks. It needs+ no database and takes seconds. `pnpm verify:test` runs the tests for the+ packages your diff touches; those do need a local libSQL server.+4. Make commits with clear and descriptive messages. Each commit should have a single logical purpose.+5. Push your branch to your forked repository.+6. Open a pull request (PR) from your branch to the original repository's `main` branch.+7. Provide a detailed description of your changes in the PR, including any related issues or feature requests.A project maintainer will review your PR, provide feedback if necessary, and merge it once it meets the project's standards.diff --git a/apps/checker/AGENTS.md b/apps/checker/AGENTS.mdnew file mode 100644index 000000000..97a797cee--- /dev/null+++ b/apps/checker/AGENTS.md@@ -0,0 +1,19 @@+# AGENTS.md β apps/checker++Go 1.25, the only non-TypeScript tier in the repo along with+`apps/private-location`. It probes customer endpoints from ~35 fly.io regions on+512 MB VMs and writes results straight to Tinybird.++Constraints:++- **Keep Go scoped to probing.** Product and workspace logic belongs in+ `packages/services`. The two sides talk through data contracts only β Tinybird+ rows and protobuf (`packages/proto`) β never shared in-process code.+- **Assertion evaluation exists twice**: `apps/checker/pkg/assertions` (Go) and+ `packages/assertions` (TypeScript). So do region codes. Changing one without+ the other silently diverges what the probe checks from what the dashboard+ shows β move both in the same PR and say so in the description.+- `pnpm verify` does not cover this app. Run `go test ./...` from+ `apps/checker`; CI runs it in `.github/workflows/go-tests.yml`.+- Per-phase timings (DNS, connect, TLS, TTFB, transfer) come from `httptrace`.+ They are a product surface, not diagnostics β do not drop or rename fields.diff --git a/apps/dashboard/AGENTS.md b/apps/dashboard/AGENTS.mdnew file mode 100644index 000000000..b5839e252--- /dev/null+++ b/apps/dashboard/AGENTS.md@@ -0,0 +1,33 @@+# AGENTS.md β apps/dashboard++## Visual changes need a human++An agent cannot verify rendering. If a change alters layout, styling or any+visible behaviour, say so and ask for confirmation rather than reporting it as+done. Prefer taking on work in `packages/services`, `packages/api` and the route+handlers, where `pnpm verify` and the test suites are real evidence.++## Runtimes++The whole tRPC surface is served from+`apps/dashboard/src/app/api/trpc/lambda/[trpc]/route.ts` on the **Node.js**+runtime β several routers pull Node-only SDKs (`@slack/web-api`, email and+notification clients). Node-only dependencies inside `@openstatus/services` are+still forbidden, because `apps/workflows` runs the same code on Deno.++## Client boundary++A `"use client"` file must not **value**-import the schema barrel+`@openstatus/db/src/schema` β it drags Drizzle and the whole schema graph into+the browser bundle. Import the specific sub-path instead+(`@openstatus/db/src/schema/page_components/constants`), or split the pure-zod+part into a sibling file. `import type` from the barrel is fine; types erase.++## Chat tool renderers++Reuse the dashboard's own primitives β `TableCell*`, `ResultTable`,+`ChangesTable`. Do not build bespoke chrome for a tool result.++Persisted chat messages are validated on write, which is what makes the+`asUIMessages` cast in `apps/dashboard/src/components/chat/use-chat-session.ts`+safe. Keep casts of that kind in one named helper.diff --git a/apps/dashboard/src/components/forms/monitor/form-general.tsx b/apps/dashboard/src/components/forms/monitor/form-general.tsxindex 0046efc2c..70179e263 100644--- a/apps/dashboard/src/components/forms/monitor/form-general.tsx+++ b/apps/dashboard/src/components/forms/monitor/form-general.tsx@@ -12,7 +12,7 @@ import {stringCompareDictionary,textBodyAssertion,} from "@openstatus/assertions";-import { monitorMethods } from "@openstatus/db/src/schema";+import { monitorMethods } from "@openstatus/db/src/schema/monitors/constants";import { Globe, Network, Add, Server, Close } from "@openstatus/icons";import {AlertDialog,diff --git a/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx b/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsxindex 6f4471e5d..7b57e3af2 100644--- a/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx+++ b/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx@@ -1,11 +1,9 @@"use client";import { zodResolver } from "@hookform/resolvers/zod";-import {- type StatusReportUpdate,- statusReportStatus,-} from "@openstatus/db/src/schema";+import type { StatusReportUpdate } from "@openstatus/db/src/schema";import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";import { Button } from "@openstatus/ui/components/ui/button";import { Calendar } from "@openstatus/ui/components/ui/calendar";diff --git a/apps/dashboard/src/components/forms/status-report-update/form.tsx b/apps/dashboard/src/components/forms/status-report-update/form.tsxindex 3c35a0c8a..94e821c43 100644--- a/apps/dashboard/src/components/forms/status-report-update/form.tsx+++ b/apps/dashboard/src/components/forms/status-report-update/form.tsx@@ -1,8 +1,8 @@"use client";import { zodResolver } from "@hookform/resolvers/zod";-import { statusReportStatus } from "@openstatus/db/src/schema";import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";import { Button } from "@openstatus/ui/components/ui/button";import { Calendar } from "@openstatus/ui/components/ui/calendar";diff --git a/apps/dashboard/src/components/forms/status-report/form.tsx b/apps/dashboard/src/components/forms/status-report/form.tsxindex 76828518e..72e5b658b 100644--- a/apps/dashboard/src/components/forms/status-report/form.tsx+++ b/apps/dashboard/src/components/forms/status-report/form.tsx@@ -1,8 +1,8 @@"use client";import { zodResolver } from "@hookform/resolvers/zod";-import { statusReportStatus } from "@openstatus/db/src/schema";import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";import { Button } from "@openstatus/ui/components/ui/button";import { Calendar } from "@openstatus/ui/components/ui/calendar";diff --git a/apps/server/AGENTS.md b/apps/server/AGENTS.mdnew file mode 100644index 000000000..40c03a340--- /dev/null+++ b/apps/server/AGENTS.md@@ -0,0 +1,36 @@+# AGENTS.md β apps/server++Hono, running on Deno. Four surfaces under `apps/server/src/routes/`: `v1`+(public REST), `rpc` (ConnectRPC), `mcp`, and `slack`.++## API-key scopes++Two layers enforce `read` / `write`, and both must stay:++- **Service level** β `requireScope(ctx, "write")` inside every service verb.+ This is the real gate for anything routed through `@openstatus/services`.+- **Transport level** β `requireWriteScope()` in+ `apps/server/src/libs/middlewares/require-scope.ts`, mounted on the V1 router+ after `authMiddleware`. V1 predates the services convention and still issues+ inline Drizzle queries, so service-level checks would skip its write handlers+ entirely. It maps method to scope: `GET`/`HEAD` are read, everything else is+ write. Adding a V1 route that mutates through a `GET` silently bypasses it.++New endpoints should call a service verb rather than query Drizzle directly;+`oxlint.config.ts` already bans `@openstatus/db` and `drizzle-orm` imports in+the handlers that have migrated, and that list grows one domain per PR.++## Route config++Resolve config once and pass it in;+`createSlackRoute(config)` in `apps/server/src/routes/slack/index.ts` is the+pattern β production calls `slackConfigFromEnv()` at module scope, tests build a+route with explicit config. Reading `env` at request time is what made the slack+route untestable under `deno test --parallel`, since the workers share one+process environment.++## MCP++MCP tools declare `scope: 'read' | 'write'` and register via+`registerScopedTool`, so a read-only key never sees a write tool in+`tools/list`. A tool registered the plain way leaks regardless of the key.diff --git a/apps/status-page/AGENTS.md b/apps/status-page/AGENTS.mdnew file mode 100644index 000000000..c9d0191bc--- /dev/null+++ b/apps/status-page/AGENTS.md@@ -0,0 +1,39 @@+# AGENTS.md β apps/status-page++Public, unauthenticated, multi-tenant: the page is resolved from the request+host or the `[domain]` segment. Assume every response you touch is served to+anonymous visitors and cached.++## Gated content++Pages can be password-protected. Any new surface that renders page content β+route, API handler, feed, embed β must apply the same gate the HTML route+applies. The existing public representations to mirror are+`apps/status-page/src/app/api/markdown/[[...path]]` and+`apps/status-page/src/app/api/status/[[...path]]`.++**Known open leak:** the public tRPC endpoint at `/api/trpc/lambda` serves+gated page content. `guardTRPCSource` only filters on a spoofable+`x-trpc-source` header and is explicitly not a security boundary. Do not treat+it as one, and do not widen the surface until the procedures themselves check+the gate.++Never log or report tRPC `input` β it carries page passwords and subscriber+tokens. `sentryLoggerLink` attaches the operation `path` only.++## Caching++Markdown and JSON representations negotiate on `Accept` at the same URL, so+every response sets `Vary: Accept` plus a strong ETag. Cache-control depends on+the page's access type β a gated page must not inherit a public TTL.++## Theming++Themes come from `@openstatus/theme-store` as OKLCH CSS variables. Add or edit+a theme in that package; do not hard-code colours in a component.++## Impact labels++Status-page impact labels are coloured text only β no dots, no chevrons. The+hover affordance is a dashed muted underline, never one tinted with the impact+colour.diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.mdnew file mode 100644index 000000000..fa2c679f0--- /dev/null+++ b/apps/web/AGENTS.md@@ -0,0 +1,24 @@+# AGENTS.md β apps/web++## `.well-known` routes++`apps/web/src/app/.well-known/` is a dot-directory, and TypeScript's `include`+wildcards skip those. Files under it are outside the tsconfig program, so path+aliases (`@/β¦`) do not resolve and nothing there is type-checked as part of the+app. Use relative imports (or node built-ins, as+`.well-known/agent-skills/index.json/route.ts` does) and check the output by+requesting the route.++## Search++The βK search is homegrown: the ranker lives in `apps/web/src/app/api/search`+and the index in `apps/web/src/content/utils/search-index.ts`. Do not reach for+Pagefind, Orama or Algolia.++## Content pages++Content pages are MDX prose built from the existing components (`Grid`,+`Details`, β¦). Reach for those before inventing a bespoke layout.++Never link out to a competitor. Name them as plain text β an external link+donates domain authority and leaks the conversion.diff --git a/apps/workflows/AGENTS.md b/apps/workflows/AGENTS.mdnew file mode 100644index 000000000..b0d6b0910--- /dev/null+++ b/apps/workflows/AGENTS.md@@ -0,0 +1,17 @@+# AGENTS.md β apps/workflows++Runs on **Deno**, not Node. `pnpm check` here is+`deno check --sloppy-imports src/serve.ts`, and it must pass β it is the only+type gate this app has (`pnpm test` runs with `--no-check`).++Constraints that follow from the runtime:++- No `node:*` built-ins, and no dependency that reaches for one. This app+ imports `@openstatus/services`, so a `node:*` import added there breaks the+ build here β run `pnpm check` in both packages after touching services.+- Sentry comes from `@sentry/deno`, not `@sentry/node`.+- Tests run `deno test --parallel`, so test files share one process+ environment. Never drive a branch by assigning to `process.env` mid-test β+ the assignment leaks into whatever else is running. Resolve config once at+ module scope and pass it in, so "credential missing" is a value a test hands+ you rather than a global it mutates.diff --git a/devbox.json b/devbox.jsonindex 8a893e539..752b7cf0f 100644--- a/devbox.json+++ b/devbox.json@@ -1,6 +1,12 @@{"$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.6/.schema/devbox.schema.json",- "packages": ["turso-cli@latest", "nodejs@22", "bun@latest", "sqld@latest"],+ "packages": [+ "[email protected]",+ "[email protected]",+ "[email protected]",+ "[email protected]",+ ],"env": {"DEVBOX_COREPACK_ENABLED": "true","COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"diff --git a/devbox.lock b/devbox.lockindex 2275c40a9..3fdfc1155 100644--- a/devbox.lock+++ b/devbox.lock@@ -1,51 +1,101 @@{"lockfile_version": "1","packages": {- "bun@latest": {- "last_modified": "2025-10-27T19:50:41Z",- "resolved": "github:NixOS/nixpkgs/1666250dbe4141e4ca8aaf89b40a3a51c2e36144#bun",+ "[email protected]": {+ "last_modified": "2026-08-01T16:34:20Z",+ "resolved": "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e#bun","source": "devbox-search",- "version": "1.3.1",+ "version": "1.3.13","systems": {"aarch64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/q77q60pidwk04lgw5q930a32w9zp7r0p-bun-1.3.1",+ "path": "/nix/store/f2lm68vnka4nz9wdz60vbmymnpv63f1x-bun-1.3.13","default": true}],- "store_path": "/nix/store/q77q60pidwk04lgw5q930a32w9zp7r0p-bun-1.3.1"+ "store_path": "/nix/store/f2lm68vnka4nz9wdz60vbmymnpv63f1x-bun-1.3.13"},"aarch64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/7ba6bigk4vpvxpmx0c3h6rg5zl9bs5np-bun-1.3.1",+ "path": "/nix/store/pm8kj4ysqkf8b53yyi3576kwd23q0x23-bun-1.3.13","default": true}],- "store_path": "/nix/store/7ba6bigk4vpvxpmx0c3h6rg5zl9bs5np-bun-1.3.1"+ "store_path": "/nix/store/pm8kj4ysqkf8b53yyi3576kwd23q0x23-bun-1.3.13"},"x86_64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/27338drvdd2cqz765wa4s51kz866v4ws-bun-1.3.1",+ "path": "/nix/store/wn9cggwqflvqryxxb9xinl9iygndm8d9-bun-1.3.13","default": true}],- "store_path": "/nix/store/27338drvdd2cqz765wa4s51kz866v4ws-bun-1.3.1"+ "store_path": "/nix/store/wn9cggwqflvqryxxb9xinl9iygndm8d9-bun-1.3.13"},"x86_64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/jzjyn4d12klv4kp47c86z4dk1bksbg0q-bun-1.3.1",+ "path": "/nix/store/sav1jc5c2axarnzif94rkm8byc6zw0kb-bun-1.3.13","default": true}],- "store_path": "/nix/store/jzjyn4d12klv4kp47c86z4dk1bksbg0q-bun-1.3.1"+ "store_path": "/nix/store/sav1jc5c2axarnzif94rkm8byc6zw0kb-bun-1.3.13"+ }+ }+ },+ "[email protected]": {+ "last_modified": "2026-08-01T16:34:20Z",+ "resolved": "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e#deno",+ "source": "devbox-search",+ "version": "2.9.4",+ "systems": {+ "aarch64-darwin": {+ "outputs": [+ {+ "name": "out",+ "path": "/nix/store/lmqwp7gr0hapgh48vwfkvzd9as1qzsp2-deno-2.9.4",+ "default": true+ },+ {+ "name": "denort",+ "path": "/nix/store/g0yd5grzazxkfgclcfbqxvqy1b8c6jy8-deno-2.9.4-denort"+ }+ ],+ "store_path": "/nix/store/lmqwp7gr0hapgh48vwfkvzd9as1qzsp2-deno-2.9.4"+ },+ "aarch64-linux": {+ "outputs": [+ {+ "name": "out",+ "path": "/nix/store/gskl25gjd0aqrz432ahapzyq45mfim0l-deno-2.9.4",+ "default": true+ },+ {+ "name": "denort",+ "path": "/nix/store/dm9j5iismy4bm9vch0z4g0ir6yg3k9bl-deno-2.9.4-denort"+ }+ ],+ "store_path": "/nix/store/gskl25gjd0aqrz432ahapzyq45mfim0l-deno-2.9.4"+ },+ "x86_64-linux": {+ "outputs": [+ {+ "name": "out",+ "path": "/nix/store/1w42p7jj0dmw525pnnlsj9496fsb30fc-deno-2.9.4",+ "default": true+ },+ {+ "name": "denort",+ "path": "/nix/store/0bgyyi7jcjlbjmf55if1xv7dk64qq2vr-deno-2.9.4-denort"+ }+ ],+ "store_path": "/nix/store/1w42p7jj0dmw525pnnlsj9496fsb30fc-deno-2.9.4"}}},@@ -53,90 +103,90 @@"last_modified": "2025-11-05T16:44:39Z","resolved": "github:NixOS/nixpkgs/ffcdcf99d65c61956d882df249a9be53e5902ea5?lastModified=1762361079&narHash=sha256-lz718rr1BDpZBYk7%2BG8cE6wee3PiBUpn8aomG%2FvLLiY%3D"},- "nodejs@22": {- "last_modified": "2025-05-31T03:30:20Z",+ "[email protected]": {+ "last_modified": "2025-12-27T12:56:01Z","plugin_version": "0.0.2",- "resolved": "github:NixOS/nixpkgs/59138c7667b7970d205d6a05a8bfa2d78caa3643#nodejs_22",+ "resolved": "github:NixOS/nixpkgs/3edc4a30ed3903fdf6f90c837f961fa6b49582d1#nodejs_24","source": "devbox-search",- "version": "22.14.0",+ "version": "24.12.0","systems": {"aarch64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/g5bv4gi6p7ryhs2hbaryxs6ivsxa6lqc-nodejs-22.14.0",+ "path": "/nix/store/b1h0af3yb3z9jz048phclcqw6ihiww67-nodejs-24.12.0","default": true},{"name": "dev",- "path": "/nix/store/96vpirdcns8zxdwzwl7n804012lwrf1n-nodejs-22.14.0-dev"+ "path": "/nix/store/ksn4nj0nbp0ikmh4scy9x4biqqdswwhy-nodejs-24.12.0-dev"},{"name": "libv8",- "path": "/nix/store/xph2837xqjnra80mqlk64xp7vb3kkqxs-nodejs-22.14.0-libv8"+ "path": "/nix/store/3x72bm7l30ib7l7cximrp0sklcq8jqwy-nodejs-24.12.0-libv8"}],- "store_path": "/nix/store/g5bv4gi6p7ryhs2hbaryxs6ivsxa6lqc-nodejs-22.14.0"+ "store_path": "/nix/store/b1h0af3yb3z9jz048phclcqw6ihiww67-nodejs-24.12.0"},"aarch64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/cwb781xbp70f72njqh8vhvbsf1xq87i5-nodejs-22.14.0",+ "path": "/nix/store/9jfsyhcr9c6rpm94lrkibv75jkggvwss-nodejs-24.12.0","default": true},{"name": "dev",- "path": "/nix/store/0w5mql46am2qai707a42q983l44l1h9z-nodejs-22.14.0-dev"+ "path": "/nix/store/7izhv9x1yvsmyrhmmyps6bxjjclajm80-nodejs-24.12.0-dev"},{"name": "libv8",- "path": "/nix/store/vy56lahz381ayvw3hym3wj4r4ggv7gbk-nodejs-22.14.0-libv8"+ "path": "/nix/store/8hl74pnc1qyz68rg10ixw7fz32hcxqkk-nodejs-24.12.0-libv8"}],- "store_path": "/nix/store/cwb781xbp70f72njqh8vhvbsf1xq87i5-nodejs-22.14.0"+ "store_path": "/nix/store/9jfsyhcr9c6rpm94lrkibv75jkggvwss-nodejs-24.12.0"},"x86_64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/086zjv14ipka2vbpgwil3xyvi5ml4vh3-nodejs-22.14.0",+ "path": "/nix/store/cj1243xswxvnwgifyiyg8axhn0r2vl48-nodejs-24.12.0","default": true},{"name": "dev",- "path": "/nix/store/24n01nfvy908pwzwpgsl0k4227187i7i-nodejs-22.14.0-dev"+ "path": "/nix/store/kzia3rkaf9vwpn3py23q9v49jpjm6zx7-nodejs-24.12.0-dev"},{"name": "libv8",- "path": "/nix/store/jiwk0in1wk85crn9vp03gg937gbh1s0w-nodejs-22.14.0-libv8"+ "path": "/nix/store/xszji81xj7ghjhz7jk0jkhb84nfwyd8f-nodejs-24.12.0-libv8"}],- "store_path": "/nix/store/086zjv14ipka2vbpgwil3xyvi5ml4vh3-nodejs-22.14.0"+ "store_path": "/nix/store/cj1243xswxvnwgifyiyg8axhn0r2vl48-nodejs-24.12.0"},"x86_64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/c8jxsih8yy2rnncdmx2hyraizf689nvp-nodejs-22.14.0",+ "path": "/nix/store/9z1v3wyrxp6fpyzw21lcakd5w7aknzyc-nodejs-24.12.0","default": true},{"name": "libv8",- "path": "/nix/store/s8gnrgh9hgnbkrc1wrn21d6zvkbvm9vi-nodejs-22.14.0-libv8"+ "path": "/nix/store/5yvx909wlis13qd2y1ahwl7ij21ma69a-nodejs-24.12.0-libv8"},{"name": "dev",- "path": "/nix/store/xw8c1c0inxq3xl1d7axz19vq8c05kjk5-nodejs-22.14.0-dev"+ "path": "/nix/store/7ll99p08gmpg0n048669p80zjibl5akr-nodejs-24.12.0-dev"}],- "store_path": "/nix/store/c8jxsih8yy2rnncdmx2hyraizf689nvp-nodejs-22.14.0"+ "store_path": "/nix/store/9z1v3wyrxp6fpyzw21lcakd5w7aknzyc-nodejs-24.12.0"}}},- "sqld@latest": {- "last_modified": "2025-10-22T20:59:19Z",- "resolved": "github:NixOS/nixpkgs/01b6809f7f9d1183a2b3e081f0a1e6f8f415cb09#sqld",+ "[email protected]": {+ "last_modified": "2026-05-21T08:15:18Z",+ "resolved": "github:NixOS/nixpkgs/4a29d733e8a7d5b824c3d8c958a946a9867b3eb2#sqld","source": "devbox-search","version": "0.24.32","systems": {@@ -144,47 +194,47 @@"outputs": [{"name": "out",- "path": "/nix/store/sgwjj0nld67nwx8w7b529bwvfyv9r9r0-sqld-0.24.32",+ "path": "/nix/store/kxi3jrkyd0sg0wy9rz948vig1lxy395y-sqld-0.24.32","default": true}],- "store_path": "/nix/store/sgwjj0nld67nwx8w7b529bwvfyv9r9r0-sqld-0.24.32"+ "store_path": "/nix/store/kxi3jrkyd0sg0wy9rz948vig1lxy395y-sqld-0.24.32"},"aarch64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/gh46ibxxbfvz2qymp0vd2n4akad5wp7x-sqld-0.24.32",+ "path": "/nix/store/4zlylzcrm9m8cvch4y88ynyi1d47kh7z-sqld-0.24.32","default": true}],- "store_path": "/nix/store/gh46ibxxbfvz2qymp0vd2n4akad5wp7x-sqld-0.24.32"+ "store_path": "/nix/store/4zlylzcrm9m8cvch4y88ynyi1d47kh7z-sqld-0.24.32"},"x86_64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/gm5zbh90kw0qc9zmmmyrn3icjjycmdgz-sqld-0.24.32",+ "path": "/nix/store/anmk86cv1hv6w89pak60cbadwm4fd1bs-sqld-0.24.32","default": true}],- "store_path": "/nix/store/gm5zbh90kw0qc9zmmmyrn3icjjycmdgz-sqld-0.24.32"+ "store_path": "/nix/store/anmk86cv1hv6w89pak60cbadwm4fd1bs-sqld-0.24.32"},"x86_64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/j29jdlfnnqpvm22n0w4sj4zf2lm3lv0w-sqld-0.24.32",+ "path": "/nix/store/ib3jvxmgc731dxqyzx2i9sh1sj5n229b-sqld-0.24.32","default": true}],- "store_path": "/nix/store/j29jdlfnnqpvm22n0w4sj4zf2lm3lv0w-sqld-0.24.32"+ "store_path": "/nix/store/ib3jvxmgc731dxqyzx2i9sh1sj5n229b-sqld-0.24.32"}}},- "turso-cli@latest": {- "last_modified": "2025-10-22T20:59:19Z",- "resolved": "github:NixOS/nixpkgs/01b6809f7f9d1183a2b3e081f0a1e6f8f415cb09#turso-cli",+ "[email protected]": {+ "last_modified": "2026-01-23T17:20:52Z",+ "resolved": "github:NixOS/nixpkgs/a1bab9e494f5f4939442a57a58d0449a109593fe#turso-cli","source": "devbox-search","version": "1.0.15","systems": {@@ -192,41 +242,41 @@"outputs": [{"name": "out",- "path": "/nix/store/n2a4r9cnif35d00qmn4zb96643n9xd05-turso-cli-1.0.15",+ "path": "/nix/store/7mm8wc2f5p2h6hz6hrjkh1b7kzlg9cpg-turso-cli-1.0.15","default": true}],- "store_path": "/nix/store/n2a4r9cnif35d00qmn4zb96643n9xd05-turso-cli-1.0.15"+ "store_path": "/nix/store/7mm8wc2f5p2h6hz6hrjkh1b7kzlg9cpg-turso-cli-1.0.15"},"aarch64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/yy8nfs9z5f19xvjn07qxgi533ah59wdd-turso-cli-1.0.15",+ "path": "/nix/store/619jqmd4q36k4li0ihq2hy3pvhlzkrgn-turso-cli-1.0.15","default": true}],- "store_path": "/nix/store/yy8nfs9z5f19xvjn07qxgi533ah59wdd-turso-cli-1.0.15"+ "store_path": "/nix/store/619jqmd4q36k4li0ihq2hy3pvhlzkrgn-turso-cli-1.0.15"},"x86_64-darwin": {"outputs": [{"name": "out",- "path": "/nix/store/6lcri76g9pdjw628kw60zxa4ixhz41vq-turso-cli-1.0.15",+ "path": "/nix/store/6kws97rwr8sbamhb7w9hmqi25w0p18c1-turso-cli-1.0.15","default": true}],- "store_path": "/nix/store/6lcri76g9pdjw628kw60zxa4ixhz41vq-turso-cli-1.0.15"+ "store_path": "/nix/store/6kws97rwr8sbamhb7w9hmqi25w0p18c1-turso-cli-1.0.15"},"x86_64-linux": {"outputs": [{"name": "out",- "path": "/nix/store/87zwzwq3h8hmznw1wqlqp9ksgy16s20n-turso-cli-1.0.15",+ "path": "/nix/store/k3s154j4q09k7h4hwacb3crw50p76g34-turso-cli-1.0.15","default": true}],- "store_path": "/nix/store/87zwzwq3h8hmznw1wqlqp9ksgy16s20n-turso-cli-1.0.15"+ "store_path": "/nix/store/k3s154j4q09k7h4hwacb3crw50p76g34-turso-cli-1.0.15"}}}diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 0dee58f9a..7ada3ca35 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -1,11 +1,16 @@# Architecture Decision Records-This directory holds the architecturally significant decisions made on-openstatus, in [MADR](https://adr.github.io/madr/) format.+**This set is frozen. Do not add new ADRs.**-An ADR captures *why* a decision was made, what alternatives were weighed, and-what trade-offs were accepted. `CLAUDE.md` documents the conventions in force-today; ADRs explain how those conventions came to be.+These nine records are background on *why* a handful of architectural decisions+were made, in [MADR](https://adr.github.io/madr/) format. They are history, and+several describe a change rather than a state β ADR-0008 says+"`loadSeededWorkspace` is gone", which only makes sense against the world before+it.++Current-state truth lives in `AGENTS.md` at the repo root and in the nested+`AGENTS.md` files it links. When a decision changes, update those; do not write+a superseding ADR here.## Index@@ -19,28 +24,4 @@ today; ADRs explain how those conventions came to be.| [0005](0005-turso-for-app-data-tinybird-for-time-series.md) | Turso for application data, Tinybird for time-series | accepted || [0006](0006-persist-external-incidents-in-turso.md) | Persist external-service incidents in Turso, not Tinybird | accepted || [0007](0007-store-external-service-components.md) | Store external-service components in Turso, their status history in Tinybird | accepted |--## When to write an ADR--Write one when a decision is hard to reverse, cross-cutting, or non-obvious β-for example:--- adopting or dropping a framework, library, or runtime;-- a repo-wide pattern every contributor must follow;-- a data-model or API-contract decision that is expensive to change;-- choosing one approach over a reasonable alternative someone would ask about.--Skip it for routine, local, or easily reversible changes.--## How to add one--1. Copy `template.md` to `NNNN-kebab-case-title.md`, where `NNNN` is the next- zero-padded number.-2. Fill it in. Keep it short β drivers, options, outcome, consequences.-3. Add a row to the index above.-4. Open it in the same PR as (or just before) the change it describes.--## Changing a decision--ADRs are immutable once accepted. To change a decision, write a new ADR and set-the old one's `status` to `superseded by ADR-NNNN`.+| [0008](0008-isolated-test-databases.md) | One test database per package, one workspace per suite, injected route config | accepted |diff --git a/oxlint.config.ts b/oxlint.config.tsindex 0d2de31ec..2f56e4ef6 100644--- a/oxlint.config.ts+++ b/oxlint.config.ts@@ -2,6 +2,7 @@ import { defineConfig } from "oxlint";export default defineConfig({plugins: ["eslint", "typescript", "react", "unicorn", "oxc"],+ jsPlugins: ["./scripts/oxlint-plugin-openstatus.js"],categories: {correctness: "warn",},@@ -111,5 +112,33 @@ export default defineConfig({"typescript/no-explicit-any": "off",},},+ {+ // Behaviour-triggered, not filename-triggered: anything opening a+ // transaction in the services layer is a mutation.+ files: ["packages/services/src/**/*.ts"],+ excludeFiles: ["**/__tests__/**", "**/*.test.ts"],+ rules: {+ "openstatus/services-mutation-guards": "error",+ // apps/workflows runs this on Deno, and it stays Edge-safe by design.+ "no-restricted-imports": [+ "error",+ {+ patterns: [+ {+ group: ["node:*"],+ message:+ "@openstatus/services must stay runtime-agnostic β no node built-ins. Hand-roll the helper (see deepEqual) or move the code to a Node-only package.",+ },+ ],+ },+ ],+ },+ },+ {+ files: ["apps/dashboard/src/**/*.tsx", "apps/dashboard/src/**/*.ts"],+ rules: {+ "openstatus/no-db-barrel-in-client": "error",+ },+ },],});diff --git a/package.json b/package.jsonindex 995b4fb7f..fe4747769 100644--- a/package.json+++ b/package.json@@ -17,6 +17,9 @@"format:check": "oxfmt --check && oxlint","lint:turbo": "turbo run lint","check": "turbo run check",+ "check:docs": "node scripts/check-doc-refs.mts",+ "verify": "pnpm format:check && pnpm check:docs && pnpm check",+ "verify:test": "turbo run test --affected --concurrency=1","dev:web": "turbo run dev --filter='./apps/web' --filter='./packages/db'","dev:status-page": "turbo run dev --filter='./apps/status-page' --filter='./packages/db'","dev:dashboard": "turbo run dev --filter='./apps/dashboard' --filter='./packages/db'",diff --git a/packages/api/src/router/import.test.ts b/packages/api/src/router/import.test.tsindex 9cb9869ad..40d9ac0ce 100644--- a/packages/api/src/router/import.test.ts+++ b/packages/api/src/router/import.test.ts@@ -195,7 +195,7 @@ async function cleanup() {// entity. The entities are gone but the rows are not β and// INTEGER PRIMARY KEY ids recycle, so a later test inserting into the// same table can land on an id that already has an audit row,- // inheriting its actor attribution. See docs/adr/test-audit-cleanup.md.+ // inheriting its actor attribution. See packages/services/AGENTS.md.await Promise.all([clearAuditLogFor({ entityType: "page", entityIds: createdIds.pages }),clearAuditLogFor({diff --git a/packages/api/src/router/maintenance.test.ts b/packages/api/src/router/maintenance.test.tsindex c24e94259..4917f6fd1 100644--- a/packages/api/src/router/maintenance.test.ts+++ b/packages/api/src/router/maintenance.test.ts@@ -21,7 +21,7 @@ let otherWorkspaceComponentId: number;// the `maintenance.create` / `maintenance.update` audit rows outlive// the row itself and β because INTEGER PRIMARY KEY recycles β a later// test inserting into `maintenance` can land on the orphan's id and-// inherit its actor attribution. See docs/adr/test-audit-cleanup.md.+// inherit its actor attribution. See packages/services/AGENTS.md.const createdMaintenanceIds: number[] = [];const updatedMaintenanceIds: number[] = [];diff --git a/packages/api/src/router/statusReport.test.ts b/packages/api/src/router/statusReport.test.tsindex 1c63e8ebd..a0cb8c7b1 100644--- a/packages/api/src/router/statusReport.test.ts+++ b/packages/api/src/router/statusReport.test.ts@@ -24,7 +24,7 @@ let otherWorkspaceComponentId: number;// reached the parent β leaving an orphan report and an orphan audit row.// SQLite recycles INTEGER PRIMARY KEY ids on delete, so a later test// inserting a status_report could land on the orphan's id and inherit-// its `actor_type=user` attribution. See docs/adr/test-audit-cleanup.md.+// its `actor_type=user` attribution. See packages/services/AGENTS.md.const createdReportIds: number[] = [];const updatedReportIds: number[] = [];diff --git a/packages/db/src/schema/status_reports/constants.ts b/packages/db/src/schema/status_reports/constants.tsnew file mode 100644index 000000000..fdaba4129--- /dev/null+++ b/packages/db/src/schema/status_reports/constants.ts@@ -0,0 +1,8 @@+// Kept free of drizzle imports so `"use client"` files can pull the enum+// without dragging the schema graph into the browser bundle.+export const statusReportStatus = [+ "investigating",+ "identified",+ "monitoring",+ "resolved",+] as const;diff --git a/packages/db/src/schema/status_reports/status_reports.ts b/packages/db/src/schema/status_reports/status_reports.tsindex 004a56cdf..4c245a745 100644--- a/packages/db/src/schema/status_reports/status_reports.ts+++ b/packages/db/src/schema/status_reports/status_reports.ts@@ -7,13 +7,9 @@ import {} from "../page_components";import { page } from "../pages";import { workspace } from "../workspaces";+import { statusReportStatus } from "./constants";-export const statusReportStatus = [- "investigating",- "identified",- "monitoring",- "resolved",-] as const;+export { statusReportStatus };export const statusReport = sqliteTable("status_report",diff --git a/packages/services/AGENTS.md b/packages/services/AGENTS.mdnew file mode 100644index 000000000..17da257ce--- /dev/null+++ b/packages/services/AGENTS.md@@ -0,0 +1,82 @@+# AGENTS.md β @openstatus/services++Every workspace-scoped mutation lives here, not in a tRPC router or a Hono+handler. Routers validate input, call a verb, map errors.++## Shape of a verb++- **One file per verb** under `packages/services/src/<entity>/` (`create.ts`,+ `update.ts`, `remove.ts`), re-exported from that entity's `index.ts`. Callers+ import from `@openstatus/services/<entity>`.+- **Signature:** `async function verbEntity(args: { ctx: ServiceContext; input: VerbInput })`.+ `ctx` carries `workspace`, `actor`, and an optional `db`/transaction.+- **`requireScope(ctx, "write")` is the first line of every write verb** β+ before `Input.parse(...)`, before `withTransaction`.+- **`withTransaction(ctx, async (tx) => β¦)`** wraps every mutation; it reuses an+ outer transaction if one was threaded through `ctx`, otherwise opens one.+ Inside the block, write through `tx` β never `defaultDb`.+- **Every read and write filters by `ctx.workspace.id`.** Use the+ `getXInWorkspace` fetch-or-throw helpers in the entity's `internal.ts`.+- **Throw `ServiceError` subclasses** from `./errors`. Routers convert them with+ `toTRPCError`.++## Audit log++`emitAudit(tx, ctx, entry)` runs inside the same transaction as the mutation.+Fail-closed: a failed audit insert rolls the mutation back.++- Updates pass both `before` (pre-mutation snapshot) and `after` (the+ `.returning()` row); `changed_fields` is diffed automatically and no-op updates+ are skipped. Creates pass only `after`, deletes only `before`.+- **Strip secrets from snapshots** β credentials, bot tokens, raw API keys.+- Action names are `{entity}.{verb}`; new variants go in the discriminated union+ at `packages/db/src/schema/audit_logs/validation.ts`.++A missing `emitAudit` or `requireScope` is a defect, not a style nit. Both are+lint-enforced; if a verb genuinely needs neither, the inline disable must carry+a reason.++## Scope enforcement++API keys carry `read` / `write` scopes. "Write" means any DB mutation **or**+side-effecting external call (probe, webhook, notification); everything else is+read. `requireScope` is a no-op for `user` / `system` / `slack` / `webhook` /+`subscriber` actors and active for `apiKey` and `mcp`. MCP tools declare+`scope` and register through `registerScopedTool`, so read-only keys never see+write tools.++## Runtime constraints++- **No `node:*` imports.** `apps/workflows` runs this code on Deno, and the+ package is written to stay Edge-safe so a Next.js route can adopt it without a+ rewrite β no Edge route imports it today. That is why `deepEqual` is+ hand-rolled rather than pulled from `node:util`.+- **No logtape here.** It breaks Edge builds; use `console.warn`.++## Query plans++Turso exposes neither `EXPLAIN` nor `ANALYZE`, and `sqlite_stat1` never exists+there. Verify a plan locally against `openstatus-dev.db` instead; in production+the only signal you get is `rows_read`.++## Tests++Suites live in `packages/services/src/<entity>/__tests__/`, mint their own+workspace, and assert the audit side-effect with `expectAuditRow(...)` from+`packages/services/test/helpers.ts`. Each entity also carries a+`'rejects read-only actor'` case built with `makeApiKeyCtx(...)`; `requireScope`+fires before any DB lookup, so fake ids are fine there.++**Audit rows outlive the entities they describe.** A suite that creates entities+through a service on the committed db and deletes them in cleanup must also call+`clearAuditLogFor(...)` β SQLite recycles `INTEGER PRIMARY KEY` ids after+deletes, so a later test's freshly-inserted entity can land on the orphan's id+and inherit its actor attribution. The failure surfaces in an unrelated suite,+which is what makes it expensive.++## Uptime weights++`impactUptimeWeight` in `packages/db/src/schema/page_components/constants.ts`+is pinned by tests: `major_outage` = 1, `partial_outage` = 0.5,+`degraded_performance` = 0. These numbers have been changed and reverted before β+confirm with a maintainer before touching them.diff --git a/packages/services/src/chat-session/create.ts b/packages/services/src/chat-session/create.tsindex e941065a0..3baea4188 100644--- a/packages/services/src/chat-session/create.ts+++ b/packages/services/src/chat-session/create.ts@@ -14,6 +14,10 @@ import { UnauthorizedError } from "../errors";import { enforceSessionCap } from "./internal";import { CreateChatSessionInput } from "./schemas";+// Per-user UI state, not workspace configuration: only user actors get past+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action+// union has no `chat_session` verb.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function createChatSession(args: {ctx: ServiceContext;input: CreateChatSessionInput;diff --git a/packages/services/src/chat-session/remove.ts b/packages/services/src/chat-session/remove.tsindex d6e3ebe03..166017677 100644--- a/packages/services/src/chat-session/remove.ts+++ b/packages/services/src/chat-session/remove.ts@@ -10,6 +10,10 @@ import { UnauthorizedError } from "../errors";import { getChatSessionInWorkspace } from "./internal";import { DeleteChatSessionInput } from "./schemas";+// Per-user UI state, not workspace configuration: only user actors get past+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action+// union has no `chat_session` verb.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function deleteChatSession(args: {ctx: ServiceContext;input: DeleteChatSessionInput;diff --git a/packages/services/src/chat-session/set.ts b/packages/services/src/chat-session/set.tsindex 4c6a5d85b..79fed1700 100644--- a/packages/services/src/chat-session/set.ts+++ b/packages/services/src/chat-session/set.ts@@ -20,6 +20,10 @@ import { SetChatSessionMessagesInput } from "./schemas";* full-replace lets each fire be the canonical snapshot. Existing-row* `createdAt` wins on overlap so older messages don't drift forward.*/+// Per-user UI state, not workspace configuration: only user actors get past+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action+// union has no `chat_session` verb.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function setChatSessionMessages(args: {ctx: ServiceContext;input: SetChatSessionMessagesInput;diff --git a/packages/services/src/import/run.ts b/packages/services/src/import/run.tsindex 35c8aabb6..9eab9de5c 100644--- a/packages/services/src/import/run.ts+++ b/packages/services/src/import/run.ts@@ -2,6 +2,7 @@ import { and, count, db as defaultDb, eq } from "@openstatus/db";import { page, pageComponent } from "@openstatus/db/src/schema";import type { ImportSummary } from "@openstatus/importers";+import { requireScope } from "../auth";import type { ServiceContext } from "../context";import { NotFoundError, ValidationError } from "../errors";import { addLimitWarnings } from "./limits";@@ -40,6 +41,7 @@ export async function runImport(args: {input: RunImportInput;}): Promise<ImportSummary> {const { ctx } = args;+ requireScope(ctx, "write");const input = RunImportInput.parse(args.input);const tx = ctx.db ?? defaultDb;diff --git a/packages/services/src/member/delete.ts b/packages/services/src/member/delete.tsindex 5e467c65d..e656c6ba4 100644--- a/packages/services/src/member/delete.ts+++ b/packages/services/src/member/delete.ts@@ -26,6 +26,9 @@ import { DeleteMemberInput } from "./schemas";* Only fires when the actor is an openstatus user: removing another user is* not something a system / apiKey / webhook actor should do today.*/+// The delete and its `member.delete` audit row live in+// `removeMemberInWorkspace`; this verb only adds the owner / self-removal guards.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function deleteMember(args: {ctx: ServiceContext;input: DeleteMemberInput;diff --git a/packages/services/src/monitor/relations.ts b/packages/services/src/monitor/relations.tsindex 1ecfc858f..0572e2470 100644--- a/packages/services/src/monitor/relations.ts+++ b/packages/services/src/monitor/relations.ts@@ -7,6 +7,7 @@ import {} from "@openstatus/db/src/schema";import { emitAudit } from "../audit";+import { requireScope } from "../auth";import { type ServiceContext, withTransaction } from "../context";import { LimitExceededError } from "../errors";import {@@ -31,6 +32,7 @@ export async function updateMonitorSchedulingRegions(args: {input: UpdateMonitorSchedulingRegionsInput;}): Promise<void> {const { ctx } = args;+ requireScope(ctx, "write");const input = UpdateMonitorSchedulingRegionsInput.parse(args.input);const limits = ctx.workspace.limits;@@ -104,6 +106,7 @@ export async function updateMonitorTags(args: {input: UpdateMonitorTagsInput;}): Promise<void> {const { ctx } = args;+ requireScope(ctx, "write");const input = UpdateMonitorTagsInput.parse(args.input);await withTransaction(ctx, async (tx) => {@@ -157,6 +160,7 @@ export async function updateMonitorNotifiers(args: {input: UpdateMonitorNotifiersInput;}): Promise<void> {const { ctx } = args;+ requireScope(ctx, "write");const input = UpdateMonitorNotifiersInput.parse(args.input);await withTransaction(ctx, async (tx) => {diff --git a/packages/services/src/page-subscriber/send-test-webhook.ts b/packages/services/src/page-subscriber/send-test-webhook.tsindex 5990e708f..186367b17 100644--- a/packages/services/src/page-subscriber/send-test-webhook.ts+++ b/packages/services/src/page-subscriber/send-test-webhook.ts@@ -17,6 +17,9 @@ import { SendPageSubscriberTestWebhookInput } from "./schemas";* No audit emit β a test dispatch has no effect on the entity's durable* state. If we add "last-tested-at" bookkeeping later, we'd revisit.*/+// The transaction only reads the subscriber row; the webhook send mutates+// nothing, so there is no state change to audit.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function sendPageSubscriberTestWebhook(args: {ctx: ServiceContext;input: SendPageSubscriberTestWebhookInput;diff --git a/packages/services/src/page-subscriber/slack.ts b/packages/services/src/page-subscriber/slack.tsindex dafb488bd..954f9ee0e 100644--- a/packages/services/src/page-subscriber/slack.ts+++ b/packages/services/src/page-subscriber/slack.ts@@ -41,6 +41,9 @@ function channelLabel(channelId: string, channelName?: string): string {* authenticated workspace at the call site β both workspace and audit actor* are resolved from the page. Auto-accepted (the slash command is consent).*/+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function createSlackSubscriber(args: {input: CreateSlackSubscriberInput;db?: DB;@@ -164,6 +167,9 @@ export async function createSlackSubscriber(args: {});}+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function removeSlackSubscriber(args: {input: RemoveSlackSubscriberInput;db?: DB;diff --git a/packages/services/src/page-subscriber/unsubscribe.ts b/packages/services/src/page-subscriber/unsubscribe.tsindex d5cc93ff3..6303dac61 100644--- a/packages/services/src/page-subscriber/unsubscribe.ts+++ b/packages/services/src/page-subscriber/unsubscribe.ts@@ -16,6 +16,9 @@ import { UnsubscribeSubscriberInput } from "./schemas";* second call on an already-unsubscribed row returns silently with no* audit emit.*/+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function unsubscribeSubscriber(args: {input: UnsubscribeSubscriberInput;db?: DB;diff --git a/packages/services/src/page-subscriber/update-scope.ts b/packages/services/src/page-subscriber/update-scope.tsindex 42f571f15..5ef3f981c 100644--- a/packages/services/src/page-subscriber/update-scope.ts+++ b/packages/services/src/page-subscriber/update-scope.ts@@ -23,6 +23,9 @@ import { UpdateSubscriberScopeInput } from "./schemas";* them via `metadata` to keep the audit row from being dropped by the* empty-diff guard in `emitAudit`.*/+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function updateSubscriberScope(args: {input: UpdateSubscriberScopeInput;db?: DB;diff --git a/packages/services/src/page-subscriber/upsert.ts b/packages/services/src/page-subscriber/upsert.tsindex fab85bf9a..b2710b087 100644--- a/packages/services/src/page-subscriber/upsert.ts+++ b/packages/services/src/page-subscriber/upsert.ts@@ -49,6 +49,9 @@ export type UpsertSelfSignupResult = {* components-only change)* - already verified row β no audit (no-op return)*/+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function upsertSelfSignupSubscriber(args: {input: UpsertSelfSignupSubscriberInput;db?: DB;diff --git a/packages/services/src/page-subscriber/verify.ts b/packages/services/src/page-subscriber/verify.tsindex f4f96bb80..120d051f7 100644--- a/packages/services/src/page-subscriber/verify.ts+++ b/packages/services/src/page-subscriber/verify.ts@@ -32,6 +32,9 @@ export type VerifyResult = {* `acceptedAt` and writes one `page_subscriber.update` audit row with* actor `subscriber:{id}`.*/+// Token-addressed self-service by an anonymous visitor: the audit actor is+// `subscriber`, for which `requireScope` is a documented no-op.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function verifySelfSignupSubscriber(args: {input: VerifySelfSignupSubscriberInput;db?: DB;diff --git a/packages/services/src/workspace/downgrade.ts b/packages/services/src/workspace/downgrade.tsindex 010df2021..035b5fafc 100644--- a/packages/services/src/workspace/downgrade.ts+++ b/packages/services/src/workspace/downgrade.ts@@ -43,6 +43,9 @@ import { updateWorkspacePlan } from "./update";* caller can release them on Vercel *after* the transaction commits β* that cleanup is best-effort and must not roll the downgrade back.*/+// Every trim step routes through an audited entity verb, so the cascade is+// fully attributable; the plan flip itself is audited by `updateWorkspacePlan`.+// oxlint-disable-next-line openstatus/services-mutation-guardsexport async function downgradeWorkspaceToFree(args: {ctx: ServiceContext;}): Promise<{ customDomains: string[]; ssoDisabled: boolean }> {diff --git a/packages/services/test/helpers.ts b/packages/services/test/helpers.tsindex d20810588..171697bdc 100644--- a/packages/services/test/helpers.ts+++ b/packages/services/test/helpers.ts@@ -66,7 +66,7 @@ export async function clearAuditLog(* the audit row outlives the entity, and because SQLite recycles* INTEGER PRIMARY KEY ids after deletes, a later test's freshly-inserted* entity can land on the orphan's id and inherit its actor attribution.- * See docs/adr/test-audit-cleanup.md.+ * See packages/services/AGENTS.md.*/export async function clearAuditLogFor(args: {entityType: string;diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.mdnew file mode 100644index 000000000..037f0251c--- /dev/null+++ b/packages/ui/AGENTS.md@@ -0,0 +1,69 @@+# AGENTS.md β @openstatus/ui++Three directories under `src/components/`, three different contracts. Getting+the wrong one is the most common mistake here.++| Directory | What it is | Who else sees it |+|---|---|---|+| `ui/` | Stock shadcn/ui primitives | Nobody β never shipped |+| `blocks/` | The openstatus shadcn registry (status page) | Every external consumer |+| `custom/` | openstatus-only components | Our apps only |++`blocks/README.md` documents the composition API and `REGISTRY.md` the publish+flow. This file is only the rules those two assume you already know.++## Do not customize `src/components/ui/`++These 41 files are shadcn's, and the registry ships **zero** of them. Blocks+instead declare `registryDependencies: ["button", "tooltip", β¦]`, which resolve+to the **consumer's own** shadcn components at install time.++So a block that depends on a local tweak to `button.tsx` renders correctly in+this repo and incorrectly for everyone who installs it β with no error anywhere.+Patching also means the next `shadcn add` either clobbers the change or silently+skips the upgrade.++When a primitive isn't enough, in order of preference: pass `className`, compose+a wrapper in `blocks/` or `custom/`, or add a variant to the block that needs it.++Editing a `ui/` file is a last resort, and only for a defect stock shadcn has+too. `input-group.tsx` is the precedent β `FormControl`'s Slot injected a+`data-slot` that clobbered the group's own, breaking the focus ring. It carries+a comment saying why the prop order matters. Do the same, or don't touch them.++## `blocks/` is a published registry, not internal code++Anything you add here ends up on `openstatus.dev/r` and gets installed into+codebases that are not this one.++- **Register it.** A new file needs an entry in `registry.json` with its+ `registryDependencies`. Forget that and it works in the monorepo and 404s for+ consumers β nothing in CI catches it.+- **No app imports.** No `next/link`, no `next-intl`, no `@openstatus/db`, no+ tRPC. Every direct dependency becomes a mandatory install for consumers, and+ most of them aren't even on Next.js. Routing, markdown and translation come in+ through slot props (`renderEvent`, `renderMessage`, `asChild`) and the+ `StatusBlocksI18nProvider` context.+- **Imports must exist in a stock shadcn install.** `pnpm registry:build`+ rewrites `@openstatus/ui/*` to `@/*`, so `@openstatus/ui/components/ui/button`+ becomes `@/components/ui/button` on the consumer's machine. Importing a+ primitive we have but they don't produces a build error there, not here.+- **New color tokens go in `registry.json` `cssVars`.** That is how `--success`,+ `--warning` and `--info` reach consumers; a token used only in `globals.css`+ is undefined for them.+- **Defaults must render unconfigured.** Slots are optional, i18n falls back to+ English. The registry preview has no wiring.++## Generated output++`dist/` and `public/r/` are build artifacts of `pnpm registry:build` (which+`apps/web`'s build runs). Both are gitignored. Never edit them, and never fix a+registry bug by editing `dist/` β change `src/` and rebuild.++## Imports++Exports are path-based, with no barrel:+`@openstatus/ui/components/ui/button`, `@openstatus/ui/components/blocks/status-bar`,+`@openstatus/ui/hooks/use-media-query`. Import the exact file.++Shared UI belongs here, not forked into an app β see `docs/adr/0003-shared-ui-comes-from-openstatus-ui.md`.diff --git a/ralph/.gitignore b/ralph/.gitignoredeleted file mode 100644index e93c46927..000000000--- a/ralph/.gitignore+++ /dev/null@@ -1,4 +0,0 @@-# Ignore PRD and progress files as they are specific to local development-prd.json-progress.txt-diff --git a/ralph/README.md b/ralph/README.mddeleted file mode 100644index b54a819dd..000000000--- a/ralph/README.md+++ /dev/null@@ -1,34 +0,0 @@-Ralph is a technique for running AI coding agents in a loop. Our approach is taken from Matt Pocock's [Getting Started with Ralph](https://www.aihero.dev/getting-started-with-ralph) writeup. Make sure to have everything installed.--The `prd.json` file is an array of object with the following format:--```-{- "category": "functional",- "description": "When a user is on wrong dashboard /status-pages/[id] redirect him to /status-pages",- "steps": [- "Redirect user no access for page id",- "Avoid throwing an error",- ],- "passes": false-}-```--- category: "functional" | "ui" or other categories-- description: define what you are building-- steps: break the task down into multiple smaller steps-- passes: determines whether or not all defined steps and tests have succeed or not and makes it easier to track progress--The `progress.txt` file simply keeps track of the changes and implementation decisions.--You can run Ralph with a human-in-the-loop by running:--```-./ralph-once.sh-```--Or in AFK mode within the sandbox environment by specifying the iteration number with:--```-./afk-raph.sh 10-```\ No newline at end of filediff --git a/ralph/afk-ralph.sh b/ralph/afk-ralph.shdeleted file mode 100755index e56b7116b..000000000--- a/ralph/afk-ralph.sh+++ /dev/null@@ -1,25 +0,0 @@-#!/bin/bash-set -e--if [ -z "$1" ]; then- echo "Usage: $0 <iterations>"- exit 1-fi--for ((i=1; i<=$1; i++)); do- result=$(docker sandbox run claude --permission-mode acceptEdits -p "@prd.json @progress.txt \- 1. Find the highest-priority task and implement it. \- 2. Run your tests and type checks. \- 3. Update the PRD with what was done. \- 4. Append your progress to progress.txt. \- 5. Commit your changes. \- ONLY WORK ON A SINGLE TASK. \- If the PRD is complete, output <promise>COMPLETE</promise>.")-- echo "$result"-- if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then- echo "PRD complete after $i iterations."- exit 0- fi-done\ No newline at end of filediff --git a/ralph/ralph-once.sh b/ralph/ralph-once.shdeleted file mode 100755index e157ae0e2..000000000--- a/ralph/ralph-once.sh+++ /dev/null@@ -1,8 +0,0 @@-#!/bin/bash--claude --permission-mode acceptEdits "@prd.json @progress.txt \-1. Read the PRD and progress file. \-2. Find the next incomplete task and implement it. \-3. Commit your changes. \-4. Update progress.txt with what you did. \-ONLY DO ONE TASK AT A TIME."\ No newline at end of filediff --git a/scripts/check-doc-refs.mts b/scripts/check-doc-refs.mtsnew file mode 100644index 000000000..d0c4cc77a--- /dev/null+++ b/scripts/check-doc-refs.mts@@ -0,0 +1,133 @@+/**+ * Fails when a cited path no longer exists: `docs/β¦` references anywhere in the+ * repo, and backticked repo paths inside any `AGENTS.md`.+ *+ * Paths only β resolving symbols would need a parser and is out of proportion.+ * Runs on node's native type stripping, so it needs no build step.+ */++import { execFileSync } from "node:child_process";+import { existsSync, readFileSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");++const SCANNED_EXTENSIONS = new Set([+ "ts",+ "tsx",+ "js",+ "jsx",+ "mjs",+ "cjs",+ "md",+ "mdx",+ "go",+ "yml",+ "yaml",+ "json",+ "jsonc",+ "sh",+ "toml",+ "sql",+]);++// A backticked token in AGENTS.md counts as a repo path only if it starts with+// one of these. Keeps `@openstatus/db`, `node:fs` and `hono/jsx` out.+const REPO_PATH_PREFIXES = [+ "apps/",+ "packages/",+ "docs/",+ "infra/",+ "utils/",+ "scripts/",+ ".github/",+ ".claude/",+];++// Brackets are in the class so Next.js route segments (`docs/[slug].md`) match.+const DOCS_REFERENCE = /(?<![\w./@-])docs\/[\w./[\]-]+/g;+const BACKTICKED = /`([^`\n]+)`/g;+// Extension required, so docs-site slugs (`docs/concept/page-1`) are not read+// as repo paths.+const FILE_LIKE = /\.[a-z0-9]+$/i;++type Violation = { file: string; line: number; path: string };++function trackedFiles(): string[] {+ return execFileSync("git", ["ls-files", "-z"], {+ cwd: REPO_ROOT,+ encoding: "utf8",+ maxBuffer: 64 * 1024 * 1024,+ })+ .split("\0")+ .filter((file) => file.length > 0);+}++/**+ * Strips sentence punctuation and a `:42` line suffix a citation may carry.+ * `]` is left alone β Next.js route segments legitimately end with it.+ */+function normalize(candidate: string): string {+ return candidate.replace(/[.,;:)]+$/, "").replace(/:\d+$/, "");+}++function isRepoPath(candidate: string): boolean {+ // `*`, `<β¦>` and `β¦` mark a pattern or placeholder, not a real path.+ if (/[*<>β¦\s]/.test(candidate)) return false;+ return REPO_PATH_PREFIXES.some((prefix) => candidate.startsWith(prefix));+}++function collect(file: string, contents: string): Violation[] {+ const violations: Violation[] = [];+ const isAgentsFile = file === "AGENTS.md" || file.endsWith("/AGENTS.md");++ contents.split("\n").forEach((text, index) => {+ const candidates = new Set<string>();++ for (const match of text.matchAll(DOCS_REFERENCE)) {+ const candidate = normalize(match[0]);+ if (FILE_LIKE.test(candidate)) candidates.add(candidate);+ }++ if (isAgentsFile) {+ for (const match of text.matchAll(BACKTICKED)) {+ const candidate = normalize(match[1] ?? "");+ if (isRepoPath(candidate)) candidates.add(candidate);+ }+ }++ for (const candidate of candidates) {+ if (!existsSync(join(REPO_ROOT, candidate))) {+ violations.push({ file, line: index + 1, path: candidate });+ }+ }+ });++ return violations;+}++const files = trackedFiles();+const violations: Violation[] = [];++for (const file of files) {+ const extension = file.split(".").pop()?.toLowerCase() ?? "";+ if (!SCANNED_EXTENSIONS.has(extension)) continue;++ violations.push(+ ...collect(file, readFileSync(join(REPO_ROOT, file), "utf8")),+ );+}++if (violations.length > 0) {+ console.error(`Dangling path references (${violations.length}):\n`);+ for (const { file, line, path } of violations) {+ console.error(` ${file}:${line} β ${path}`);+ }+ console.error(+ "\nEvery `docs/β¦` citation and every backticked repo path in an AGENTS.md must resolve.",+ );+ process.exit(1);+}++console.log(`No dangling path references (${files.length} tracked files).`);diff --git a/scripts/oxlint-plugin-openstatus.js b/scripts/oxlint-plugin-openstatus.jsnew file mode 100644index 000000000..6c302454a--- /dev/null+++ b/scripts/oxlint-plugin-openstatus.js@@ -0,0 +1,175 @@+/**+ * Custom oxlint rules for openstatus.+ *+ * `services-mutation-guards` keys off behaviour, not filename: a top-level+ * function that opens a transaction is a mutation, and every mutation must+ * check the actor's scope and leave an audit row.+ *+ * It matches call names, not the call graph. `emitAudit` therefore counts from+ * anywhere in the verb (it belongs inside the `withTransaction` callback), which+ * a nested helper that never runs could satisfy. `requireScope` must appear in+ * the verb body itself, which is where the convention puts it. A guard, not a+ * proof β the audit tests are what actually pin the behaviour.+ */++const FUNCTION_TYPES = [+ "FunctionDeclaration",+ "FunctionExpression",+ "ArrowFunctionExpression",+];++function calleeName(node) {+ const callee = node.callee;+ if (!callee) return null;+ if (callee.type === "Identifier") return callee.name;+ // `foo.bar()` β only the property matters here.+ if (+ callee.type === "MemberExpression" &&+ callee.property?.type === "Identifier"+ ) {+ return callee.property.name;+ }+ return null;+}++/** Arrows and function expressions have no `id`; fall back to the const they're assigned to. */+function functionName(node, assignedName) {+ if (node.id?.type === "Identifier") return node.id.name;+ return assignedName ?? "<anonymous>";+}++const servicesMutationGuards = {+ meta: {+ type: "problem",+ docs: {+ description:+ "A services function that calls withTransaction must also call requireScope and emitAudit.",+ },+ messages: {+ missing:+ "`{{name}}` opens a transaction but never calls {{missing}}. Every mutation in @openstatus/services must check the actor's scope and emit an audit row β see packages/services/AGENTS.md. If this verb genuinely needs neither, disable this rule inline with the reason above it.",+ },+ },+ create(context) {+ let depth = 0;+ let outermost = null;+ let outermostName = null;+ let pendingName = null;+ // Anywhere in the verb, so a `withTransaction` callback's `emitAudit` counts.+ const calls = new Set();+ // The verb's own body, where `requireScope` belongs.+ const bodyCalls = new Set();++ function enter(node) {+ if (depth === 0) {+ outermost = node;+ outermostName = functionName(node, pendingName);+ calls.clear();+ bodyCalls.clear();+ }+ depth += 1;+ }++ function exit() {+ depth -= 1;+ if (depth !== 0 || outermost === null) return;++ if (calls.has("withTransaction")) {+ const missing = [];+ if (!bodyCalls.has("requireScope")) missing.push("requireScope");+ if (!calls.has("emitAudit")) missing.push("emitAudit");++ if (missing.length > 0) {+ context.report({+ node: outermost,+ messageId: "missing",+ data: {+ name: outermostName,+ missing: missing.map((name) => `\`${name}\``).join(" or "),+ },+ });+ }+ }+ outermost = null;+ outermostName = null;+ pendingName = null;+ }++ const visitor = {+ VariableDeclarator(node) {+ if (depth === 0 && node.id?.type === "Identifier") {+ pendingName = node.id.name;+ }+ },+ CallExpression(node) {+ const name = calleeName(node);+ if (!name) return;+ calls.add(name);+ if (depth === 1) bodyCalls.add(name);+ },+ };+ for (const type of FUNCTION_TYPES) {+ visitor[type] = enter;+ visitor[`${type}:exit`] = exit;+ }+ return visitor;+ },+};++const DB_SCHEMA_BARREL = "@openstatus/db/src/schema";++/**+ * `"use client"` is a per-file directive, not a path convention, so this cannot+ * be expressed as a `no-restricted-imports` override keyed on globs.+ */+const noDbBarrelInClient = {+ meta: {+ type: "problem",+ docs: {+ description:+ 'A "use client" file must not value-import the db schema barrel.',+ },+ messages: {+ barrel:+ 'A "use client" file must not value-import `{{source}}` β it pulls drizzle and the whole schema graph into the browser bundle. Import the specific sub-path (e.g. `@openstatus/db/src/schema/monitors/constants`), or split the pure-zod part into a sibling file. `import type` is fine.',+ },+ },+ create(context) {+ let isClientFile = false;++ return {+ Program(node) {+ isClientFile = node.body.some(+ (statement) =>+ statement.type === "ExpressionStatement" &&+ statement.expression?.type === "Literal" &&+ statement.expression.value === "use client",+ );+ },+ ImportDeclaration(node) {+ if (!isClientFile) return;+ if (node.source?.value !== DB_SCHEMA_BARREL) return;+ if (node.importKind === "type") return;+ // `import { type Foo }` on every specifier erases too.+ const hasValueSpecifier = node.specifiers.some(+ (specifier) => specifier.importKind !== "type",+ );+ if (!hasValueSpecifier) return;++ context.report({+ node,+ messageId: "barrel",+ data: { source: DB_SCHEMA_BARREL },+ });+ },+ };+ },+};++export default {+ meta: { name: "openstatus" },+ rules: {+ "services-mutation-guards": servicesMutationGuards,+ "no-db-barrel-in-client": noDbBarrelInClient,+ },+};