Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
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
|
||||
|
||||
Reference in new issue
Block a user