Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -2,7 +2,7 @@
**Status:** active
**Owner:** web platform
**Related:** [`scripts/bundle-budgets.json`](../../scripts/bundle-budgets.json), [`scripts/verify-bundle-size.mjs`](../../scripts/verify-bundle-size.mjs), `docs/improvement-plan/10-compliance-polish/bundle-budget.md`
**Related:** [`scripts/bundle-budgets.json`](../../scripts/bundle-budgets.json), [`scripts/verify-bundle-size.mjs`](../../scripts/verify-bundle-size.mjs)
## Why
@@ -43,7 +43,7 @@ The per-route layer was added in task #71 (Phase 10) to make day-to-day creep vi
```bash
# Build apps/web normally and print the per-route table:
pnpm --filter @toolctrl/web build
pnpm --filter @hivegrid/web build
node scripts/verify-bundle-size.mjs
# Only the per-route table (skips group checks):
@@ -63,7 +63,7 @@ machine-readable output with human diagnostics.
To inspect why a chunk is big:
```bash
pnpm --filter @toolctrl/web run bundle:visualize
pnpm --filter @hivegrid/web run bundle:visualize
open apps/web/build/stats.html
```
@@ -75,7 +75,7 @@ The visualizer is gated on `ANALYZE_BUNDLE=true` so the regular production build
`.github/workflows/bundle-budget.yml` (and `.gitea/workflows/bundle-budget.yml`) run on every PR that touches `apps/web/**`, `packages/**`, or the budget config / verifier. They:
1. Build `@toolctrl/web`.
1. Build `@hivegrid/web`.
2. Run `verify-bundle-size.mjs --json`.
3. Download the latest `bundle-baseline-main` artifact (captured by `bundle-budget-baseline.yml` on `main` pushes).
4. Render a sticky markdown comment via `scripts/render-bundle-budget-comment.mjs`.
@@ -104,7 +104,7 @@ The first PR after a fresh checkout (or after a baseline-artifact expiry) sees `
- **PR comment never shows up:** check the `Bundle Budget` workflow run — the `Build web` step may have failed (e.g. server-only import in a client export). The comment job only runs if all upstream steps succeed.
- **`vendor-monaco-...` reports as `vendor-monaco-...-` with default budget:** rollup occasionally emits chunk hashes ending in `-`; the baseline normalizer skips that suffix and the asset falls back to `default`. Either rename via `manualChunks.ts` or add an explicit budget entry.
- **CI run is much slower than `pnpm typecheck`:** the workflow does a full `pnpm --filter @toolctrl/web build`. That's the expected cost. If it ever exceeds ~30 minutes, profile with `ANALYZE_BUNDLE=true` locally first.
- **CI run is much slower than `pnpm typecheck`:** the workflow does a full `pnpm --filter @hivegrid/web build`. That's the expected cost. If it ever exceeds ~30 minutes, profile with `ANALYZE_BUNDLE=true` locally first.
## Rollback
@@ -21,7 +21,7 @@ for three reasons:
eyebrow are shared across templates. Brand-theming threads
through a single `MailBrand` prop instead of token-replacement
on raw HTML strings.
3. **Live preview** — `pnpm --filter @toolctrl/mail preview` boots
3. **Live preview** — `pnpm --filter @hivegrid/mail preview` boots
a local HTTP server that renders every template with realistic
sample data so designers can iterate without triggering live
email sends.
@@ -54,7 +54,7 @@ Templates accept a `brand: MailBrand` prop with the following fields:
| Field | Source | Notes |
| --- | --- | --- |
| `productName` | `@toolctrl/brand` `BrandTokens.productName` | Defaults to "ToolCTRL". |
| `productName` | `@hivegrid/brand` `BrandTokens.productName` | Defaults to "HiveGrid". |
| `logoUrl` | `BrandTokens.assets.logoUrl` | Optional. Falls back to wordmark. |
| `primaryColor` | `BrandTokens.mail.colors.primary` | CTA background. |
| `primaryTextColor` | `BrandTokens.mail.colors.primaryText` | CTA foreground. |
@@ -88,12 +88,12 @@ choose which to display.
prop per template.
- **URL-validation tests** verify that `javascript:`, `http://`,
`data:`, and malformed URLs are rejected when passed to `<Button>`.
- Run `pnpm --filter @toolctrl/mail test` to execute the suite.
- Run `pnpm --filter @hivegrid/mail test` to execute the suite.
## Live preview workflow
```
pnpm --filter @toolctrl/mail preview
pnpm --filter @hivegrid/mail preview
```
Then open http://localhost:3001 — the index page lists every
@@ -105,8 +105,8 @@ them when adding a template; never commit real PII.
## Render pipeline
`renderTransactionalEmail(template, props)` from `@toolctrl/mail` is
the canonical entry point. The pre-Stripe-19 string-template renderer
`renderTransactionalEmail(template, props)` from `@hivegrid/mail` is
the canonical entry point. The pre-Legacy-Provider-19 string-template renderer
(`renderTransactionalMailTemplate`) was retired in the legacy-cleanup
pass; the host application's wrapper at
`apps/web/app/modules/emails/utils/EmailTemplates.ts` adapts the
@@ -120,8 +120,8 @@ legacy template-name surface onto the React-Email pipeline.
| `email-verification` | `magic-link` | merged into magic-link flow (30-min expiry variant) |
| `account-setup` | `welcome` | unified onboarding (overridable subject/eyebrow/title/intro/actionLabel) |
| — | `magic-link` | new |
| — | `subscription-success` / `subscription-failed` | new (Stripe webhooks) |
| — | `invoice-sent` | new (Stripe invoices) |
| — | `subscription-success` / `subscription-failed` | new (Legacy-Provider webhooks) |
| — | `invoice-sent` | new (Legacy-Provider invoices) |
| — | `tenant-notification` | new (in-app digest) |
## Security notes
@@ -74,7 +74,7 @@ have to import apps/web. Web boots the lookup during cache bootstrap:
```ts
// apps/web/app/utils/services/.server/tenantPlanLookup.server.ts
setSubscriptionToPlanTier((subscription) => {
// your classifier here — e.g. map stripe product ids to plan slugs
// your classifier here — e.g. map legacyProvider product ids to plan slugs
return subscription?.products[0]?.subscriptionProductId === "prod_enterprise"
? "enterprise"
: subscription?.products.length
@@ -104,7 +104,7 @@ Useful Grafana queries:
```promql
# Enqueue rate by priority for a queue
sum by (priority) (rate(queue_jobs_enqueued_total{queue="toolctrl.email"}[5m]))
sum by (priority) (rate(queue_jobs_enqueued_total{queue="hivegrid.email"}[5m]))
# Share of critical vs total
sum(rate(queue_jobs_enqueued_total{priority="critical"}[5m]))
@@ -1,11 +1,10 @@
# Lighthouse-CI audit and Web-Vitals reporting
This document describes how the Lighthouse-CI audit is wired into the
Toolctrl Boilerplate, how to run it locally when debugging a regression,
HiveGrid Boilerplate, how to run it locally when debugging a regression,
and how the Web-Vitals → Sentry bridge surfaces real-user metrics.
Spec: `docs/improvement-plan/10-compliance-polish/lighthouse.md`
(Task #70). Companion artefacts: `.lighthouserc.staging.json`,
Companion artefacts: `.lighthouserc.staging.json`,
`.lighthouserc.json`, `scripts/lighthouse-puppeteer-auth.cjs`,
`scripts/rotate-lighthouse-session-cookie.mjs`,
`.github/workflows/lighthouse.yml`, `.gitea/workflows/lighthouse.yml`,
@@ -80,8 +79,8 @@ Required workflow secrets:
| `LIGHTHOUSE_LOGIN_EMAIL` | Email of the staging Lighthouse bot user. |
| `LIGHTHOUSE_LOGIN_PASSWORD` | Password of the staging Lighthouse bot user. |
The session cookie name is `RJ_session`; workflows also pass
`LIGHTHOUSE_SESSION_COOKIE_NAME=RJ_session` and
The session cookie name is `hivegrid_session`; workflows also pass
`LIGHTHOUSE_SESSION_COOKIE_NAME=hivegrid_session` and
`LIGHTHOUSE_COOKIE_DOMAIN=boiler.saas-ctrl.com`.
During rollout the workflow still forwards the older
@@ -93,7 +92,7 @@ each run mints a fresh cookie.
## Authenticated routes
Auditing `/app/$tenant/*` and `/admin/*` needs that freshly minted
`RJ_session` cookie. `scripts/lighthouse-puppeteer-auth.cjs` injects the
`hivegrid_session` cookie. `scripts/lighthouse-puppeteer-auth.cjs` injects the
cookie for protected URLs and is already wired into
`.lighthouserc.staging.json`. The current staging target list still
audits only public routes; add protected URLs once the exact tenant/admin
@@ -109,10 +108,10 @@ expansion.
```sh
# Build apps/web (writes hashed assets the runtime SW expects to cache)
pnpm --filter @toolctrl/web build
pnpm --filter @hivegrid/web build
# Serve the build at http://localhost:3000.
pnpm --filter @toolctrl/web start &
pnpm --filter @hivegrid/web start &
# Run the full LHCI flow against the local server
pnpm verify:lighthouse
@@ -6,8 +6,7 @@ that triggered them. Without it, a crash between `DB COMMIT` and "call
mailer" leaves the DB updated but the side-effect lost.
This document describes how to publish and consume outbox events in this
codebase. See `docs/improvement-plan/03-scaling-infrastructure/outbox-pattern.md`
for the broader design rationale.
codebase.
## When to publish
@@ -15,7 +14,7 @@ Publish **inside** a Prisma `$transaction` block whenever a successful DB
write should fan out an asynchronous side-effect.
```ts
import { publishOutboxEvent } from "@toolctrl/db/outbox";
import { publishOutboxEvent } from "@hivegrid/db/outbox";
await prisma.$transaction(async (tx) => {
const subscription = await tx.subscription.update({
@@ -27,7 +26,7 @@ await prisma.$transaction(async (tx) => {
tenantId: subscription.tenantId,
type: "billing.subscription.updated",
payload: { subscriptionId: subscription.id, status: "active" },
dispatchKey: `stripe:${stripeEvent.id}`, // optional idempotency key
dispatchKey: `legacyProvider:${legacyProviderEvent.id}`, // optional idempotency key
});
});
```
@@ -74,14 +73,13 @@ gap is the current `waitForInput` boundary. Candidates that fail preflight are
skipped or recorded as rejected.
`apps/worker/src/jobs/workflow-trigger-store.ts` provides the worker-native
Prisma lookup/preflight port. Application events publish
`workflow.trigger.event` through `EventsService`. The route-backed row mutation
producers for `row.created`, `row.updated`, and `row.deleted` record the row
write, application event, and workflow outbox event in the same transaction
before post-commit notifications/webhook callouts run. Internal mutations
without a request context remain intentionally eventless unless the caller opts
into an event context. Workflow row blocks pass a `workflow` event context so
requestless `rowCreate`, `rowUpdate`, and `rowDelete` blocks still publish row
events without enabling external webhook callouts. A source-inventory test guards the current execution
`workflow.trigger.event` through `EventsService`. The generic entity-builder's
route-backed `row.created` / `row.updated` / `row.deleted` outbox producers were
**removed with the entity-builder** (R-P6B-β, AD-2): typed fachentities (CRM
`Kontakt` etc.) write their own audit/activity trail, and workflow row blocks
address typed models through the typed model registry
(`apps/web/app/services/typed-model-registry`) rather than emitting generic
`row.*` outbox events. A source-inventory test guards the current execution
boundary: manual and tenant API runs must publish
`workflow.execution.requested` instead of executing inline, non-stream
continuations must publish `workflow.execution.continue.requested`, only the
@@ -102,7 +100,7 @@ mail delivery workers. Production-like Coolify stacks need a persistent
`worker-general` (`WORKER_QUEUE_GROUP=general`) for the dispatcher and
`outbox.workflow`, plus a persistent `worker-mail`
(`WORKER_QUEUE_GROUP=mail`) for `outbox.mail`, `outbox.webhook`,
`outbox.marketing`, and `toolctrl.email` work. A green outbox row does not prove
`outbox.marketing`, and `hivegrid.email` work. A green outbox row does not prove
that both services exist or that the downstream BullMQ job finished.
### Non-durable exception: stream runs
@@ -125,10 +123,10 @@ workflow trigger outbox event, claims and routes it through the production
dispatcher seam, then executes a live safe-core workflow through the native
worker runner and verifies idempotent re-delivery. It also verifies the
`workflow.executed` plugin hook path by routing `plugin.hook.workflow.executed`
through `outbox.plugin-hook` fanout into `toolctrl.plugin-invoke`. A paired
through `outbox.plugin-hook` fanout into `hivegrid.plugin-invoke`. A paired
failure-path fixture forces an unsupported native block, verifies terminal
`status: "error"` persistence, then routes `plugin.hook.workflow.failed`
through the same fanout boundary into `toolctrl.plugin-invoke`.
through the same fanout boundary into `hivegrid.plugin-invoke`.
The canonical non-browser readiness gate for this path is
`pnpm run verify:workflow-outbox-native`. It composes the existing focused
@@ -174,7 +172,7 @@ processed the job, the provider call succeeded, or a domain state machine
reached a terminal success state. For workflow events, operators must also
watch the `outbox.workflow` BullMQ job state and the associated
`WorkflowExecution` status. For mail/webhook events, also watch the
`worker-mail` subscriber queues and the `toolctrl.email` job state.
`worker-mail` subscriber queues and the `hivegrid.email` job state.
The dispatcher is enabled by `OUTBOX_DISPATCHER_ENABLED=true`. Defaults to
**off** in dev so a missing Redis URL does not crash the worker.
@@ -200,8 +198,8 @@ BullMQ delivery is at-least-once: a receiver crash between
`withOutboxIdempotency` so duplicate deliveries are a no-op.
```ts
import { withOutboxIdempotency } from "@toolctrl/db/outbox-receiver";
import { createIdempotencyStore } from "@toolctrl/shared-store";
import { withOutboxIdempotency } from "@hivegrid/db/outbox-receiver";
import { createIdempotencyStore } from "@hivegrid/shared-store";
const idempotencyStore = createIdempotencyStore({
store: sharedStore,
@@ -230,14 +228,14 @@ Alert when > 1000 for > 5 minutes — that means the dispatcher is behind.
Outbox `DONE` counts are not sufficient for worker health. Alert separately on
target BullMQ queue depth, failed jobs, and stalled jobs for `outbox.workflow`,
`outbox.mail`, `outbox.webhook`, `outbox.marketing`, and `toolctrl.email`.
`outbox.mail`, `outbox.webhook`, `outbox.marketing`, and `hivegrid.email`.
Workflow incidents must include the `WorkflowExecution` terminal status because
`workflow.execution.requested` can be handed to BullMQ successfully while the
execution later fails, stalls, or remains queued behind a missing bridge.
### Re-queueing failed events
Use `toolctrl-cli outbox requeue` after fixing the underlying receiver.
Use `hivegrid-cli outbox requeue` after fixing the underlying receiver.
The CLI supports single-row and filtered bulk requeues, `--dry-run`, JSON
output, and guardrails that avoid replaying `PENDING` / `PROCESSING`
rows. Prefer it over raw SQL so `processedAt`, `lastError`, retry state,
@@ -134,7 +134,7 @@ The outbox dispatcher routes `plugin.hook.*` events to
`outbox.plugin-hook` on the `general` worker group. The fanout consumer
loads enabled plugins for the tenant, filters manifests that declare the
hook, and enqueues one idempotent `plugin.invoke` job per subscriber on
the isolated `toolctrl.plugin-invoke` queue. Plugin execution itself stays
the isolated `hivegrid.plugin-invoke` queue. Plugin execution itself stays
on `WORKER_QUEUE_GROUP=plugin`.
### 10. Per-user enablement — `prisma/schema/plugins.prisma`
@@ -148,18 +148,16 @@ tenant-default subscribers remain eligible.
### 11. Operator CLI — `packages/cli/src/commands/plugins/*`
```
toolctrl-cli plugins list [--tenantId X] [--enabled true|false]
toolctrl-cli plugins enable --tenantId X --pluginId com.acme.slack
toolctrl-cli plugins disable --tenantId X --pluginId com.acme.slack
toolctrl-cli plugins uninstall --tenantId X --pluginId com.acme.slack
hivegrid-cli plugins list [--tenantId X] [--enabled true|false]
hivegrid-cli plugins enable --tenantId X --pluginId com.acme.slack
hivegrid-cli plugins disable --tenantId X --pluginId com.acme.slack
hivegrid-cli plugins uninstall --tenantId X --pluginId com.acme.slack
```
## Remaining Slices
Current status and operator-facing caveats live in `docs/features/plugins.md`
and `docs/operations/plugin-lifecycle.md`. The historical implementation plan
in `docs/improvement-plan/06-plugin-system/hooks-lifecycle.md` remains useful
context, but it is not the current source of truth.
and `docs/operations/plugin-lifecycle.md`.
- The remaining hook points (`onWebhookOutbound`, `onEmailSend`,
`afterAuthLogin`, billing, integration-connected,
@@ -185,7 +183,7 @@ context, but it is not the current source of truth.
`PLUGIN_AUTO_DISABLE_WINDOW_MS` (default 600_000) are read by the
worker bootstrap when constructing the crash tracker.
- The outbox dispatcher routes `plugin.hook.*` events to
`outbox.plugin-hook`; that consumer fans out to `toolctrl.plugin-invoke`.
`outbox.plugin-hook`; that consumer fans out to `hivegrid.plugin-invoke`.
Keep the general worker and the separate plugin worker running in
production-like topology so health checks, queue wiring, and isolation are
exercised. Before external runtime signoff, the production `worker-plugin`
@@ -11,17 +11,17 @@ This document describes the WASM-sandbox foundation shipped under Phase 06 Task
What the foundation ships:
- **`@toolctrl/plugin-runtime`** — host-side runtime:
- **`@hivegrid/plugin-runtime`** — host-side runtime:
- Manifest schema (Zod) with closed-enum capabilities + reverse-DNS plugin IDs + SemVer versions + hex-encoded Ed25519 signature fields.
- Ed25519 signature verifier against the operator-controlled trusted-keys allowlist (`PLUGIN_TRUSTED_PUBLIC_KEYS` CSV).
- WebAssembly sandbox wrapper (`createPluginSandbox`) with deterministic memory cap + host-fn fuel budget, invoked through a killable worker-thread boundary with a wall-clock budget.
- Capability gateway (`createCapabilityGateway`) that wraps host-fn maps and rejects undeclared capability calls.
- **`@toolctrl/plugin-sdk`** — TS types plugin authors build against (`HookHandler`, `HostApi`, `PluginContext`, `defineHook`) and a `hello-world` example.
- **`@hivegrid/plugin-sdk`** — TS types plugin authors build against (`HookHandler`, `HostApi`, `PluginContext`, `defineHook`) and a `hello-world` example.
- **`Plugin` Prisma model + migration** — one row per installed plugin per tenant.
- **`plugin` worker queue group** with the `toolctrl.plugin-invoke` BullMQ queue.
- **`plugin` worker queue group** with the `hivegrid.plugin-invoke` BullMQ queue.
- **`handlePluginInvokeJob`** worker handler (`apps/worker/src/jobs/plugin-invoke.ts`) that wires Plugin lookup → binary load → signature verify → rate-limit → sandbox invoke → audit.
What is **deferred** (tracked in `docs/improvement-plan/06-plugin-system/wasm-sandbox.md` under `## Deviations from Plan` once that file is updated by the executing agent):
What is **deferred** (tracked in Plugin Lifecycle Operations and follow-up tickets):
- Hot-reload — operators restart the `worker-plugin` pod to pick up new binaries.
- Marketplace integration — backlog (#24).
@@ -53,7 +53,7 @@ A plugin ships a `plugin.toml` (or `plugin.json`) alongside the `.wasm` binary.
```ts
{
schemaVersion: 1,
id: "de.toolctrl.hello", // reverse-DNS, lowercase
id: "de.hivegrid.hello", // reverse-DNS, lowercase
version: "1.0.0", // SemVer
name: "Hello",
entry: "plugin.wasm",
@@ -83,7 +83,7 @@ The schema is `strict()` — unknown top-level fields are rejected. Unknown capa
## Capability gating
The capability gateway wraps a host-fn record so that calls to capabilities the plugin did not declare in its manifest, or that the tenant did not approve for this invocation, throw `CapabilityDeniedError`. The default fuel cost is 100 units per host-fn call; configurable per gateway. Deny paths (`not_declared_in_manifest`, `not_granted_for_tenant`, `no_host_implementation`) fire the `onDenied` callback so the worker can audit them. The plugin worker currently exposes safe synchronous `env.toolctrl_log(i32)` and `env.toolctrl_audit_record(i32)` imports through `invokeSync(...)`; higher-risk host functions remain absent and fail closed.
The capability gateway wraps a host-fn record so that calls to capabilities the plugin did not declare in its manifest, or that the tenant did not approve for this invocation, throw `CapabilityDeniedError`. The default fuel cost is 100 units per host-fn call; configurable per gateway. Deny paths (`not_declared_in_manifest`, `not_granted_for_tenant`, `no_host_implementation`) fire the `onDenied` callback so the worker can audit them. The plugin worker currently exposes safe synchronous `env.hivegrid_log(i32)` and `env.hivegrid_audit_record(i32)` imports through `invokeSync(...)`; higher-risk host functions remain absent and fail closed.
## Rate limit
@@ -97,7 +97,7 @@ Capability-use telemetry is batched through `PluginCapabilityUseRecorder`. The p
## Deferred env vars
The full env-var matrix in `docs/improvement-plan/06-plugin-system/wasm-sandbox.md` is broader than the current worker bootstrap. The foundation currently wires:
The historical foundation spec was broader than the current worker bootstrap. The foundation currently wires:
| Env var | Default | Used by |
|---|---|---|
@@ -11,7 +11,7 @@ import { db, dbRead } from "~/utils/db.server";
await db.user.update({ where: { id }, data: { lastSeenAt: new Date() } });
// Explicit primary — same client, communicates intent.
import { getWriteDbClient } from "@toolctrl/db/client.server";
import { getWriteDbClient } from "@hivegrid/db/client.server";
// Replica — eventually consistent. Use for listings, dashboards, public reads.
const users = await dbRead.user.findMany({ where: { tenantId } });
@@ -27,7 +27,7 @@ identical and lag = 0.
| ---------------------- | ----------------------------------------- |
| List endpoints / paginated grids | All mutations (`create`, `update`, `delete`, `upsert`) |
| Public marketing pages (sites, portals) | Auth-resolution paths (session → user → tenant) |
| Knowledge-base public reads + search | Stripe webhook handlers reading state they just wrote |
| Knowledge-base public reads + search | Legacy-Provider webhook handlers reading state they just wrote |
| Analytics dashboards & aggregations | Outbox dispatcher reading `PENDING` events (see #42) |
| Admin tenant / role enumerations (post-auth) | Anything inside a `db.$transaction(...)` callback |
| Dashboard counts (`count()` / `groupBy()`) | Idempotency-key lookups (request-scoped consistency) |
@@ -84,7 +84,7 @@ work without code changes. All migrations are zero-risk to roll out.
## Telemetry
`@toolctrl/db/telemetry.server` exposes `attachPrismaTelemetry()` — a
`@hivegrid/db/telemetry.server` exposes `attachPrismaTelemetry()` — a
`$extends({ query })` wrapper that records every operation with
`{ client: 'read' | 'write', model, operation, durationMs, ok }`. Wire it
in the app bootstrap by adapting the recorder to your metrics sink
@@ -109,7 +109,7 @@ steps live with the platform operator.
```sql
CREATE USER replicator WITH REPLICATION ENCRYPTED PASSWORD '...';
CREATE USER read_user WITH ENCRYPTED PASSWORD '...';
GRANT CONNECT ON DATABASE toolctrl TO read_user;
GRANT CONNECT ON DATABASE hivegrid TO read_user;
GRANT USAGE ON SCHEMA public TO read_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO read_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
@@ -136,8 +136,8 @@ steps live with the platform operator.
3. **App env**:
```sh
DATABASE_URL=postgres://app_user:...@pgbouncer:6432/toolctrl?pgbouncer=true&connection_limit=10
DATABASE_READ_URL=postgres://read_user:...@postgres-replica:5432/toolctrl?connection_limit=10
DATABASE_URL=postgres://app_user:...@pgbouncer:6432/hivegrid?pgbouncer=true&connection_limit=10
DATABASE_READ_URL=postgres://read_user:...@postgres-replica:5432/hivegrid?connection_limit=10
```
Optionally front the replica with its own PgBouncer for connection pooling.
@@ -1,181 +0,0 @@
# Storybook
A single Storybook instance under `apps/storybook/` aggregates component
stories from the boilerplate UI packages.
## Quickstart
```bash
pnpm install
pnpm --filter @toolctrl/storybook storybook
# -> http://localhost:6006
# Static build
pnpm --filter @toolctrl/storybook build-storybook
# -> apps/storybook/storybook-static
```
## Stack
- **Storybook 8.x** with `@storybook/react-vite` builder
- React 19 + Vite 7 (matches `apps/web`)
- Addons: `@storybook/addon-essentials`, `@storybook/addon-a11y`,
`@storybook/addon-interactions`, `@storybook/addon-themes`
## Where stories live
Stories are **co-located** with the UI packages. The `main.ts` glob picks
them up automatically:
```
packages/ui/src/stories/*.stories.tsx
packages/ui-app/src/stories/*.stories.tsx
packages/ui-subframe/src/stories/*.stories.tsx
packages/ui-mock/src/stories/*.stories.tsx
```
> **Why `packages/ui/` only today?** The i18n hardcoded-strings guard
> whitelists `packages/(ai|cli|config|entitlements|mail|plugins|queue|realtime|ui)/`,
> so stories under `packages/ui/src/stories/` author freely without
> tripping the gate. Stories in `ui-app`, `ui-subframe`, or `ui-mock`
> work too — but currently need to avoid uppercase user-facing prop
> literals (8+ char run starting `[A-ZÄÖÜ]`) or include their own
> reviewed-line patterns. A follow-up will widen the guard.
## Authoring a story
Use **Component Story Format 3 (CSF-3)**:
```tsx
import type { Meta, StoryObj } from "@storybook/react";
import { MyComponent } from "./MyComponent";
const meta: Meta<typeof MyComponent> = {
title: "UI / Category / MyComponent",
component: MyComponent,
tags: ["autodocs"],
argTypes: {
variant: { control: { type: "select" }, options: ["a", "b"] },
},
args: { variant: "a" },
};
export default meta;
type Story = StoryObj<typeof MyComponent>;
export const Default: Story = {};
export const VariantB: Story = { args: { variant: "b" } };
```
### Conventions
- **Title path**: `UI / <Category> / <Component>` (lowercase variants work
too if the case trips a guard).
- **Tags**: include `"autodocs"` to get an auto-generated docs page.
- **Render functions** when you need state or composition. Prefer plain
`args` for simple variants.
- **A11y opt-out**: `parameters: { a11y: { disable: true } }` plus a
comment explaining why. Default policy is "fail on a11y violations".
## Theming
`apps/storybook/.storybook/preview.tsx` wraps every story in a theme
decorator from `@storybook/addon-themes`. The toolbar exposes a
`light` / `dark` toggle that swaps the `dark` class on the preview root.
Stories should style themselves via the CSS variables declared in
`apps/storybook/.storybook/preview.css` (`--color-bg`, `--color-fg`,
`--color-primary`, …) so they flip automatically. See the **Theme
Guide** docs page inside Storybook for the full token table.
## A11y addon
`@storybook/addon-a11y` runs axe-core in the story panel. The
`preview.tsx` defaults enable the WCAG-style `color-contrast` rule.
Violations show up in the **Accessibility** panel.
## Test-runner & a11y gate
`@storybook/test-runner` walks every story registered in `main.ts` and
runs the `postVisit` hook in `.storybook/test-runner.ts` against each
render. The hook injects `axe-playwright` and re-runs the same ruleset
the in-canvas panel uses (`#storybook-root` as the context, WCAG-2.2-AA
tags) — but in a real headless Chromium where `color-contrast`
actually resolves CSS, so failures are real WCAG regressions.
Run locally:
```bash
# Terminal 1
pnpm --filter @toolctrl/storybook storybook
# Terminal 2
pnpm --filter @toolctrl/storybook test:storybook
```
The runner respects per-story opt-outs via `parameters.a11y.disable =
true` (must come with a justifying code comment).
## CI
`.github/workflows/storybook.yml` and `.gitea/workflows/storybook.yml`
run three jobs on PRs that touch `apps/storybook/` or any
`packages/ui*/src/stories/` path:
1. **build-storybook** — `pnpm --filter @toolctrl/storybook
build-storybook`; uploads the static site as a 14-day artifact.
2. **test-storybook** — downloads the artifact, serves it via
`http-server`, waits for readiness, installs Playwright Chromium,
and runs `pnpm test:storybook` against `http://127.0.0.1:6006`.
Any axe violation fails the job, blocking the PR until fixed or
explicitly opted-out.
3. **visual-regression** — Lost-Pixel diff (see below). Self-skips
until a baseline is committed.
The main CI Quality-Gates job is unchanged.
## Visual-regression (Lost-Pixel)
`lost-pixel` is wired via `apps/storybook/lostpixel.config.ts`. It
walks the built static Storybook, screenshots every story, and diffs
each shot against a committed baseline under
`apps/storybook/.lostpixel/baseline/`. A pixel diff above the 0.1 %
threshold fails CI and uploads the diff PNGs as a `lost-pixel-diff`
artifact.
The `visual-regression` CI job is **baseline-gated**: its first step
checks for `apps/storybook/.lostpixel/baseline/*.png` and, if none are
committed yet, skips the rest of the job with a notice instead of
failing. This keeps the job green until an operator opts in.
**Bootstrap (one-time, operator):**
```bash
pnpm --filter @toolctrl/storybook build-storybook
pnpm --filter @toolctrl/storybook visual-regression:update
git add apps/storybook/.lostpixel/baseline
git commit -m "test(storybook): commit Lost-Pixel baseline screenshots"
```
From the next PR on, the job blocks merges on unintended visual drift.
`.lostpixel/current/` and `.lostpixel/difference/` are per-run output
and git-ignored.
Chromatic (hosted, paid above a free tier) remains an alternative —
it would need `CHROMATIC_PROJECT_TOKEN` in CI secrets and is
deliberately **not** wired.
## Troubleshooting
- **Story missing?** Confirm the path matches the glob in
`apps/storybook/.storybook/main.ts`.
- **Story render error?** Run `pnpm --filter @toolctrl/storybook storybook`
locally and check the iframe error overlay.
- **A11y violation that should be allowed?** Use
`parameters.a11y.config.rules` to disable a specific axe rule, or
`parameters.a11y.disable = true` if a story is intentionally
decorative.
- **i18n guard flags story content?** Either keep user-facing prop
literals under 9 characters / starting lowercase, or route them
through translation keys (`@toolctrl/i18n`).
@@ -1,11 +1,10 @@
# Test Coverage Policy
**Status:** completed; no-regression gate in maintenance
**Spec:** `docs/improvement-plan/10-compliance-polish/test-coverage.md`
**Owner:** Engineering quality / release maintenance
This document explains how test coverage is measured, gated, and reported in the
ToolCTRL boilerplate. Per-path thresholds are encoded as data in
HiveGrid. Per-path thresholds are encoded as data in
`scripts/coverage-targets.json` and enforced by `scripts/verify-test-coverage.mjs`.
CI workflows run the gate on GitHub PRs and `push` to `main`, while the
Gitea coverage workflow currently runs on pull requests. Keep
@@ -63,7 +62,7 @@ disproportionate impact. Each entry in `scripts/coverage-targets.json` with
| `apps/web/app/services/auth/**` | 97 % / 88 % | 90 % / 85 % |
| `apps/web/app/utils/auth/**` | 97 % / 92 % | 90 % / 85 % |
| `apps/web/app/utils/session.server.ts` | 99 % / 98 % | 95 % / 90 % |
| `apps/web/app/utils/stripe.server.ts` | 95 % / 90 % | 85 % / 75 % |
| `apps/web/app/utils/legacyProvider.server.ts` | 95 % / 90 % | 85 % / 75 % |
| `apps/web/app/utils/db/permissions/**` | 99 % / 98 % | 90 % / 80 % |
| `apps/web/app/utils/db/tenants.db.server.ts` | 98 % / 95 % | 95 % / 90 % |
| `packages/entitlements/src/**` | 96 % / 89 % | 90 % / 80 % |
@@ -120,7 +119,7 @@ failure so contributors can drill into the HTML report.
## Type-only packages
Packages that intentionally emit no runtime JavaScript, such as
`@toolctrl/api-types`, must not add fake exports or `expect(true)` tests just
`@hivegrid/api-types`, must not add fake exports or `expect(true)` tests just
to satisfy statement coverage. Give these packages a 0/0 active gate and 0/0
sprint target, then cover their contract with `expectTypeOf` tests and
`tsc --noEmit` typecheck.
@@ -153,7 +152,6 @@ Task #76 is completed. Keep the gate useful as a no-regression control:
## References
- Spec: `docs/improvement-plan/10-compliance-polish/test-coverage.md`
- Gate runner: `scripts/verify-test-coverage.mjs`
- Targets data: `scripts/coverage-targets.json`
- Summary/badge: `scripts/coverage-summary.mjs`
@@ -2,7 +2,7 @@
**Status:** active
**Owner:** platform-scaling
**Related:** [`packages/shared-store/README.md`](../../packages/shared-store/README.md), `docs/improvement-plan/03-scaling-infrastructure/pubsub-cache-invalidation.md`
**Related:** [`packages/shared-store/README.md`](../../packages/shared-store/README.md)
## Why
@@ -21,7 +21,7 @@ A mutating call invalidates its local L1+L2 and publishes the key on the namespa
Use a two-tier cache when **all three** hold:
1. The key is read more than ~5x per request, or by every request (subscription, tenant, entitlements, feature flag).
2. Source-of-truth mutations are rare relative to reads (Stripe webhook firing seconds-to-minutes apart, admin edits).
2. Source-of-truth mutations are rare relative to reads (billing webhook firing seconds-to-minutes apart, admin edits).
3. Stale reads have user-visible consequences (showing the wrong plan limit, denying access after an upgrade).
Otherwise, prefer:
@@ -34,12 +34,12 @@ Otherwise, prefer:
Channels follow `shared-store:<store-namespace>:ch:cache:<cache-namespace>:invalidate`. Concretely, the web SharedStore (`namespace: "web"`) emits subscription invalidations on `shared-store:web:ch:cache:subscription:invalidate`. The API SharedStore (`namespace: "api"`) emits on `shared-store:api:ch:cache:subscription:invalidate`.
For cross-app fan-out (Stripe webhook in API → web replicas), both apps must use the same SharedStore namespace so they share a channel. The current implementation uses per-app namespaces (`api`, `web`) but both connect to the same Redis logical DB index (default `1`). The actual channel string is namespaced under the writing app's SharedStore prefix. **If you need cross-app fan-out**, either:
For cross-app fan-out (billing webhook in API -> web replicas), both apps must use the same SharedStore namespace so they share a channel. The current implementation uses per-app namespaces (`api`, `web`) but both connect to the same Redis logical DB index (default `1`). The actual channel string is namespaced under the writing app's SharedStore prefix. **If you need cross-app fan-out**, either:
1. Use a dedicated shared namespace (e.g. `namespace: "platform"`) for both apps' two-tier caches, or
2. Have the publishing app PUBLISH the message via a SharedStore configured with the receiving app's namespace explicitly.
The Stripe webhook → subscription pattern in this codebase publishes on `shared-store:api:ch:cache:subscription:invalidate`. For a production multi-replica web deploy to actually receive that broadcast, configure both `apps/api/src/cache/subscription-cache-publisher.ts` and `apps/web/app/utils/services/.server/subscriptionCache.server.ts` to construct their SharedStores with the same namespace (recommended: introduce `getCacheSharedStore({ namespace: "cache" })` for both apps). The current implementation broadcasts within the API process and applies the same `clearTenantSubscriptionCache` semantics on the web side via local mutation-paths that already publish; the cross-process broadcast is the work item documented under Deviations in the detail-md.
The billing webhook -> subscription pattern in this codebase publishes on `shared-store:api:ch:cache:subscription:invalidate`. For a production multi-replica web deploy to actually receive that broadcast, configure both `apps/api/src/cache/subscription-cache-publisher.ts` and `apps/web/app/utils/services/.server/subscriptionCache.server.ts` to construct their SharedStores with the same namespace (recommended: introduce `getCacheSharedStore({ namespace: "cache" })` for both apps). The current implementation broadcasts within the API process and applies the same `clearTenantSubscriptionCache` semantics on the web side via local mutation-paths that already publish; the cross-process broadcast is the work item documented under Deviations in the detail-md.
## Reconnect semantics
@@ -53,7 +53,7 @@ ioredis auto-reconnects on connection loss with exponential backoff. While disco
| Channel | Publisher | Subscriber | Payload | Defined in |
| --- | --- | --- | --- | --- |
| `cache:subscription:invalidate` | `apps/api/src/billing/stripe-webhook-route.ts` (after `updateTenantSubscriptionProductFromStripe`); `apps/web/.../subscriptionService.ts` (`clearTenantSubscriptionCache`, `clearAllSubscriptionsCache`) | `apps/web/app/utils/services/.server/subscriptionCache.server.ts` → bridges into `clearCacheKey('tenantSubscription:<tenantId>')` | tenantId (string) or `"*"` for wildcard | `subscriptionCache.server.ts` + `subscription-cache-publisher.ts` |
| `cache:subscription:invalidate` | billing webhook routes and `apps/web/.../subscriptionService.ts` (`clearTenantSubscriptionCache`, `clearAllSubscriptionsCache`) | `apps/web/app/utils/services/.server/subscriptionCache.server.ts` -> bridges into `clearCacheKey('tenantSubscription:<tenantId>')` | tenantId (string) or `"*"` for wildcard | `subscriptionCache.server.ts` + `subscription-cache-publisher.ts` |
| `cache:tenant:invalidate` | `apps/web/.../tenant-cache.server.ts` (`publishTenantInvalidation`) | `apps/web/.../tenant-cache.server.ts` → clears `tenant:`, `tenantSimple:`, `tenantIdOrSlug:` cachified keys | tenantId (string) or `"*"` | `tenant-cache.server.ts` |
| `cache:entitlements:invalidate` | _piggy-backs on subscription_ — entitlements derive from the subscription and recompute on the next read after the subscription L1 is flushed | _piggy-backs on subscription_ | n/a — chained | n/a (chain) |
| `cache:feature-flags:invalidate` | `packages/feature-flags` publishers, including CLI feature-flag enable/disable/rule updates | web feature-flag cache subscribers through the shared two-tier cache bootstrap | `{ flagKey?, tenantId?, all? }` | `packages/feature-flags/src/publisher.ts` |
@@ -90,4 +90,4 @@ Always re-enable after the incident; the L1-only mode has no replica-consistency
- Unit tests for `createTwoTierCache` cover round-trip, fallback, cross-replica invalidation, `localOnly`, wildcard flush, pubsub kill-switch — `packages/shared-store/src/helpers/two-tier-cache.test.ts`
- Subscription cache integration: `apps/web/app/utils/services/.server/subscriptionCache.server.test.ts`
- Tenant cache integration: `apps/web/app/utils/db/tenant-cache.server.test.ts`
- Stripe webhook publish path: `apps/api/src/billing/stripe-webhook-route.test.ts` (asserts `publishSubscriptionInvalidation(tenantId)` is called after the DB update)
- Legacy-Provider webhook publish path: `apps/api/src/billing/legacyProvider-webhook-route.test.ts` (asserts `publishSubscriptionInvalidation(tenantId)` is called after the DB update)
@@ -1,6 +1,6 @@
# Vector Store
`@toolctrl/vector-store` is a thin adapter layer over two interchangeable
`@hivegrid/vector-store` is a thin adapter layer over two interchangeable
nearest-neighbour stores. The interface is small enough that swapping one for
the other does not require code changes outside `createVectorStore`; the
identical conformance suite (`packages/vector-store/src/adapters/conformance.test.ts`)
@@ -34,7 +34,7 @@ deployment to run a second data store.
## Selection logic
```ts
import { createVectorStore } from "@toolctrl/vector-store";
import { createVectorStore } from "@hivegrid/vector-store";
const store = createVectorStore({
namespace: "rag-prod", // becomes a collection prefix