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
@@ -1,14 +1,14 @@
|
||||
# CLI ops (`toolctrl ops`)
|
||||
# CLI ops (`hivegrid ops`)
|
||||
|
||||
The operator CLI under `packages/cli/` ships three ops sub-commands
|
||||
for day-to-day operational work:
|
||||
|
||||
- `toolctrl ops doctor` — local environment health check
|
||||
- `toolctrl ops migrate-tenant` — resumable tenant migration between envs
|
||||
- `toolctrl ops impersonate` — audit-logged debug magic-link for a tenant user
|
||||
- `hivegrid ops doctor` — local environment health check
|
||||
- `hivegrid ops migrate-tenant` — resumable tenant migration between envs
|
||||
- `hivegrid ops impersonate` — audit-logged debug magic-link for a tenant user
|
||||
|
||||
All three commands accept the `--env` flag to target a named env file
|
||||
under `~/.toolctrl/envs/`. The default is the current working-dir's
|
||||
under `~/.hivegrid/envs/`. The default is the current working-dir's
|
||||
`.env` (i.e. whatever is already loaded into `process.env`).
|
||||
|
||||
## Env-file layout
|
||||
@@ -16,13 +16,13 @@ under `~/.toolctrl/envs/`. The default is the current working-dir's
|
||||
Named envs live under:
|
||||
|
||||
```
|
||||
~/.toolctrl/envs/<name>.env
|
||||
~/.hivegrid/envs/<name>.env
|
||||
```
|
||||
|
||||
Example layout:
|
||||
|
||||
```
|
||||
~/.toolctrl/envs/
|
||||
~/.hivegrid/envs/
|
||||
├── staging.env # chmod 600
|
||||
├── staging-backup.env
|
||||
└── dev.env
|
||||
@@ -32,12 +32,12 @@ Example layout:
|
||||
No shell interpolation, no multi-line values.
|
||||
- File permissions must be `0600` (owner-only). The CLI emits a warning
|
||||
when world-readable bits are set; rotate the file with
|
||||
`chmod 600 ~/.toolctrl/envs/<name>.env`.
|
||||
`chmod 600 ~/.hivegrid/envs/<name>.env`.
|
||||
- Production env files **must not** live in CI. The `impersonate`
|
||||
command refuses any env named `prod`, `production`, or `live`
|
||||
regardless of file content.
|
||||
|
||||
## `toolctrl ops doctor`
|
||||
## `hivegrid ops doctor`
|
||||
|
||||
Runs eight probes against the resolved env and emits an ok/warn/fail
|
||||
table:
|
||||
@@ -57,13 +57,13 @@ Examples:
|
||||
|
||||
```bash
|
||||
# Default — read local .env
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops doctor
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops doctor
|
||||
|
||||
# Read ~/.toolctrl/envs/staging.env
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops doctor --env=staging
|
||||
# Read ~/.hivegrid/envs/staging.env
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops doctor --env=staging
|
||||
|
||||
# JSON output for CI
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops doctor --json
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops doctor --json
|
||||
```
|
||||
|
||||
**Exit codes:** `0` when every probe is `ok` or `warn`; `1` when any
|
||||
@@ -79,12 +79,12 @@ probe reports `fail`.
|
||||
| `env.required: fail Missing required env vars: SESSION_SECRET` | Bootstrap your `.env` from `.env.example` |
|
||||
| `prisma.migrations: warn N pending` | Run `pnpm db:migrate dev` |
|
||||
|
||||
## `toolctrl ops migrate-tenant`
|
||||
## `hivegrid ops migrate-tenant`
|
||||
|
||||
End-to-end tenant migration between named envs. Reuses the
|
||||
`packages/cli/src/commands/tenant/snapshot.ts` infrastructure from
|
||||
phase 03 (#44). Resumable via a state file under
|
||||
`~/.toolctrl/migrations/<tenantId>-<timestamp>.state.json`.
|
||||
`~/.hivegrid/migrations/<tenantId>-<timestamp>.state.json`.
|
||||
|
||||
Steps (each is an atomic resume-point):
|
||||
|
||||
@@ -98,42 +98,42 @@ Examples:
|
||||
|
||||
```bash
|
||||
# Plan a migration (no writes)
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops migrate-tenant tenant-abc \
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops migrate-tenant tenant-abc \
|
||||
--from=staging --to=staging-backup --dry-run
|
||||
|
||||
# Real migration
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops migrate-tenant tenant-abc \
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops migrate-tenant tenant-abc \
|
||||
--from=staging --to=staging-backup
|
||||
|
||||
# Resume after a crash
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops migrate-tenant tenant-abc \
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops migrate-tenant tenant-abc \
|
||||
--from=staging --to=staging-backup \
|
||||
--resume ~/.toolctrl/migrations/tenant-abc-2026-05-17T120000000Z.state.json
|
||||
--resume ~/.hivegrid/migrations/tenant-abc-2026-05-17T120000000Z.state.json
|
||||
```
|
||||
|
||||
The CLI emits a per-step status line:
|
||||
|
||||
```
|
||||
state-file=/home/op/.toolctrl/migrations/tenant-abc-2026-05-17T120000000Z.state.json
|
||||
state-file=/home/op/.hivegrid/migrations/tenant-abc-2026-05-17T120000000Z.state.json
|
||||
preflight: ok — from=staging to=staging-backup
|
||||
snapshot: ok — /home/op/.toolctrl/migrations/tenant-abc-….tar.gz
|
||||
snapshot: ok — /home/op/.hivegrid/migrations/tenant-abc-….tar.gz
|
||||
restore: ok — restored 12345 rows
|
||||
verify: ok — row-counts match
|
||||
cleanup: ok — snapshot kept on disk for audit
|
||||
```
|
||||
|
||||
The Prisma + S3 backends are injected at the `bin/toolctrl-cli.mjs`
|
||||
The Prisma + S3 backends are injected at the `bin/hivegrid-cli.mjs`
|
||||
entrypoint. The standalone subcommand prints a warning if invoked
|
||||
without that injection (no destructive operations happen).
|
||||
|
||||
## `toolctrl ops impersonate`
|
||||
## `hivegrid ops impersonate`
|
||||
|
||||
Generates a 15-minute HMAC-signed magic-link the engineer can paste
|
||||
into a browser to debug a specific tenant user. Every issued link
|
||||
writes an `AuditEvent` so the action is reviewable.
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs ops impersonate \
|
||||
node packages/cli/bin/hivegrid-cli.mjs ops impersonate \
|
||||
tenant-abc user-123 \
|
||||
--env=staging \
|
||||
--reason="support-ticket-456"
|
||||
@@ -186,14 +186,14 @@ packages/cli/src/commands/ops/
|
||||
└── index.ts # citty subcommand group
|
||||
```
|
||||
|
||||
The bin entrypoint in `packages/cli/bin/toolctrl-cli.mjs` is responsible
|
||||
The bin entrypoint in `packages/cli/bin/hivegrid-cli.mjs` is responsible
|
||||
for injecting the live Prisma client + S3 client + URL base into the
|
||||
commands. The standalone files keep zero dependencies on `@prisma/client`
|
||||
or AWS SDK so the package builds without optional peers.
|
||||
|
||||
## Security considerations
|
||||
|
||||
- **Never commit `~/.toolctrl/envs/*.env`.** The path is outside the
|
||||
- **Never commit `~/.hivegrid/envs/*.env`.** The path is outside the
|
||||
repo on purpose.
|
||||
- The `migrate-tenant` state files contain tenant IDs but no secrets.
|
||||
They are safe to retain for audit.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# CLI scaffolding (`toolctrl create` / `toolctrl add`)
|
||||
# CLI scaffolding (`hivegrid create` / `hivegrid add`)
|
||||
|
||||
The operator CLI under `packages/cli/` ships scaffolding generators that
|
||||
emit minimal, opinionated skeletons for the most common boilerplate
|
||||
@@ -9,15 +9,15 @@ chores. Each generator writes to **new paths only** and supports a
|
||||
|
||||
```bash
|
||||
# from the repo root, after `pnpm install`
|
||||
pnpm --filter @toolctrl/cli build
|
||||
pnpm --filter @hivegrid/cli build
|
||||
|
||||
# show the full command tree
|
||||
node packages/cli/bin/toolctrl-cli.mjs --help
|
||||
node packages/cli/bin/hivegrid-cli.mjs --help
|
||||
```
|
||||
|
||||
## Command reference
|
||||
|
||||
### `toolctrl create module <name>`
|
||||
### `hivegrid create module <name>`
|
||||
|
||||
Scaffolds a feature-module skeleton under `apps/web/app/modules/<name>/`:
|
||||
|
||||
@@ -36,7 +36,7 @@ Flags:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs create module inventory
|
||||
node packages/cli/bin/hivegrid-cli.mjs create module inventory
|
||||
```
|
||||
|
||||
Manual follow-up (the README in the generated module repeats this):
|
||||
@@ -45,10 +45,10 @@ Manual follow-up (the README in the generated module repeats this):
|
||||
2. Replace the `TODO` markers in the db layer.
|
||||
3. Add the permission keys to
|
||||
`packages/db/src/permissions-seed.server.ts` (see
|
||||
`toolctrl add permission` below).
|
||||
`hivegrid add permission` below).
|
||||
4. Run `pnpm typecheck` to generate the route types.
|
||||
|
||||
### `toolctrl create route <filename>`
|
||||
### `hivegrid create route <filename>`
|
||||
|
||||
Scaffolds a single React-Router-v7 route file at
|
||||
`apps/web/app/routes/<filename>.tsx` plus a co-located vitest stub.
|
||||
@@ -61,7 +61,7 @@ Flags:
|
||||
Example:
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs create route app.\$tenant.dashboard
|
||||
node packages/cli/bin/hivegrid-cli.mjs create route app.\$tenant.dashboard
|
||||
```
|
||||
|
||||
The generated file imports `Route` types from `./+types/<filename>`
|
||||
@@ -69,7 +69,7 @@ The generated file imports `Route` types from `./+types/<filename>`
|
||||
and an `ErrorBoundary` export. Run `pnpm typecheck` after generation
|
||||
to populate the `./+types/` directory.
|
||||
|
||||
### `toolctrl create entity <name>`
|
||||
### `hivegrid create entity <name>`
|
||||
|
||||
Emits a Prisma model snippet plus a timestamped migration directory:
|
||||
|
||||
@@ -89,21 +89,21 @@ pnpm prisma migrate dev --name create_entity_<name>
|
||||
pnpm prisma generate
|
||||
```
|
||||
|
||||
### `toolctrl add hook <name>`
|
||||
### `hivegrid add hook <name>`
|
||||
|
||||
Scaffolds a plugin-hook registration file under
|
||||
`apps/web/app/hooks/_generated/`. The output is a **forward-compatible
|
||||
stub** for generated hook registration. The plugin runtime and
|
||||
`@toolctrl/plugin-sdk` now exist; keep generated hooks on the scaffolded
|
||||
`@hivegrid/plugin-sdk` now exist; keep generated hooks on the scaffolded
|
||||
no-op shape until a focused task wires that specific hook into the runtime.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs add hook onContactCreated
|
||||
node packages/cli/bin/hivegrid-cli.mjs add hook onContactCreated
|
||||
```
|
||||
|
||||
### `toolctrl add event-type <name>`
|
||||
### `hivegrid add event-type <name>`
|
||||
|
||||
Scaffolds an EntityWebhook event-type definition with a zod schema, an
|
||||
example payload, and an async handler stub under
|
||||
@@ -113,10 +113,10 @@ names MUST be dotted lowercase, e.g. `crm.contact.created`.
|
||||
Example:
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs add event-type crm.contact.created
|
||||
node packages/cli/bin/hivegrid-cli.mjs add event-type crm.contact.created
|
||||
```
|
||||
|
||||
### `toolctrl add permission <name>`
|
||||
### `hivegrid add permission <name>`
|
||||
|
||||
Scaffolds two fragments for a new permission key:
|
||||
|
||||
@@ -132,7 +132,7 @@ README notes spell out the manual paste step.
|
||||
Example:
|
||||
|
||||
```bash
|
||||
node packages/cli/bin/toolctrl-cli.mjs add permission app.inventory.view
|
||||
node packages/cli/bin/hivegrid-cli.mjs add permission app.inventory.view
|
||||
```
|
||||
|
||||
## Safety guarantees
|
||||
|
||||
@@ -16,7 +16,7 @@ Translate every user-facing string that:
|
||||
|
||||
Do **not** translate:
|
||||
|
||||
- Brand names (`ToolCTRL`, `Stripe`, `GitHub`, `Scira AI` etc.) — they're
|
||||
- Brand names (`HiveGrid`, `Legacy-Provider`, `GitHub`, `Scira AI` etc.) — they're
|
||||
proper nouns and stay constant across locales
|
||||
- Developer-only tooling labels (Storybook globals, CLI prompts, log
|
||||
messages, internal admin operator screens marked as such)
|
||||
@@ -77,7 +77,7 @@ In components:
|
||||
|
||||
```tsx
|
||||
import { useTranslation } from "react-i18next";
|
||||
import { formatIcu } from "@toolctrl/i18n";
|
||||
import { formatIcu } from "@hivegrid/i18n";
|
||||
|
||||
function SelectionToolbar({ count }: { count: number }) {
|
||||
const { t, i18n } = useTranslation("common");
|
||||
@@ -85,7 +85,7 @@ function SelectionToolbar({ count }: { count: number }) {
|
||||
}
|
||||
```
|
||||
|
||||
A `createUseTranslate()` factory in `@toolctrl/i18n` returns a hook that
|
||||
A `createUseTranslate()` factory in `@hivegrid/i18n` returns a hook that
|
||||
auto-detects ICU syntax and routes to FormatJS — useful when most of your
|
||||
keys are ICU-shaped. Plain (non-ICU) messages keep working through
|
||||
i18next's `{{name}}` interpolation, so a gradual migration is safe.
|
||||
@@ -106,10 +106,10 @@ actually wired up correctly?" — see
|
||||
|
||||
## Intl helpers
|
||||
|
||||
The `@toolctrl/i18n` package exports locale-aware Intl-API wrappers:
|
||||
The `@hivegrid/i18n` package exports locale-aware Intl-API wrappers:
|
||||
|
||||
```tsx
|
||||
import { formatCurrency, formatDate, formatNumber, formatPercent, formatList, formatRelativeTime } from "@toolctrl/i18n";
|
||||
import { formatCurrency, formatDate, formatNumber, formatPercent, formatList, formatRelativeTime } from "@hivegrid/i18n";
|
||||
|
||||
formatCurrency(1234.5, { locale, currency: "EUR" }); // "1.234,50 €" / "$1,234.50"
|
||||
formatDate(new Date(), { locale, dateStyle: "medium" });
|
||||
@@ -171,7 +171,7 @@ calls the root `setLocale` action.
|
||||
The `scripts/i18n-audit.mjs` script scans web routes, modules,
|
||||
route modules, and components for hardcoded English/German JSX text, then
|
||||
records locale-sensitive formatting signals that should move to the
|
||||
`@toolctrl/i18n` helpers over time. Run it before starting an extraction
|
||||
`@hivegrid/i18n` helpers over time. Run it before starting an extraction
|
||||
sprint to baseline the count, and again after to measure progress:
|
||||
|
||||
```bash
|
||||
@@ -205,7 +205,7 @@ translations yet.
|
||||
- [ ] Strings live in a per-area namespace (`common`, `settings`, …)
|
||||
- [ ] DE and EN are both filled in (parity test enforces this)
|
||||
- [ ] Plural-aware copy uses ICU syntax
|
||||
- [ ] Currency/date/number rendering uses `@toolctrl/i18n` helpers,
|
||||
- [ ] Currency/date/number rendering uses `@hivegrid/i18n` helpers,
|
||||
passing the active locale
|
||||
- [ ] Direction-sensitive Tailwind classes use `rtl:` / `ltr:` modifiers
|
||||
(or logical CSS properties)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# WCAG 2.2 AA — Internal Audit & Fix Backlog
|
||||
|
||||
**Status:** infrastructure shipped (Phase 10 #73), fix-sprint deferred
|
||||
**Spec:** [`docs/improvement-plan/10-compliance-polish/wcag-internal.md`](../improvement-plan/10-compliance-polish/wcag-internal.md)
|
||||
**Spec:** Historical Boilerplate spec removed during Bespoke cleanup; current checks are documented here and in [`docs/architecture/test-coverage.md`](../architecture/test-coverage.md).
|
||||
**Last updated:** 2026-05-26
|
||||
|
||||
This document is the operator-facing companion to the WCAG-internal task. It
|
||||
@@ -18,7 +18,7 @@ explains:
|
||||
|
||||
| Surface | Tool | Trigger |
|
||||
| -------------------------------- | ------------------------------------------------------------------- | ---------------------- |
|
||||
| Component unit tests (jsdom) | `vitest-axe` via `@toolctrl/ui-app/test-setup/axe.ts` | `pnpm test:a11y` |
|
||||
| Component unit tests (jsdom) | `vitest-axe` via `@hivegrid/ui-app/test-setup/axe.ts` | `pnpm test:a11y` |
|
||||
| Static heuristic checks | `apps/web/app/utils/test/a11y.tsx` (`expectNoA11yViolations`) | `*.a11y.test.tsx` |
|
||||
| Live design feedback | Storybook `@storybook/addon-a11y` (WCAG-2.2-AA preset) | `pnpm --filter storybook dev` |
|
||||
| Lint rules | `eslint-plugin-jsx-a11y` (`plugin:jsx-a11y/recommended`) | `pnpm lint` |
|
||||
@@ -141,7 +141,7 @@ Severity tiers are deliberately small so a single PR can usually clear one.
|
||||
| ~~9~~ | ~~P2~~ | ~~Single tabindex container~~ | ~~`no-noninteractive-tabindex`~~ | ✅ Promoted 2026-05-25 — stale baseline entry reproduced as 0. |
|
||||
| ~~10~~| ~~P2~~ | ~~`packages/ui/src/stories/Popover.stories.tsx`~~ | ~~`anchor-is-valid`~~ | ✅ Fixed 2026-05-25 — demo menu actions use buttons. |
|
||||
|
||||
Track per-fix PRs in the [Issue tracker](https://github.com/toolctrl-labs/boilerplate/issues) with
|
||||
Track per-fix PRs in the HiveGrid issue tracker with
|
||||
label `area:accessibility`.
|
||||
|
||||
## 4. Adding a new component with a11y coverage from day-1
|
||||
@@ -217,7 +217,7 @@ pnpm lint # incl. jsx-a11y/recommended (baseline-res
|
||||
pnpm verify:a11y-coverage # component + browser-level a11y coverage ratchet
|
||||
pnpm verify:a11y-baseline # jsx-a11y baseline regression gate
|
||||
pnpm verify:e2e-a11y # SKIP-safe playwright + axe-core route sweep
|
||||
pnpm --filter @toolctrl/storybook dev # designer-facing live a11y feedback
|
||||
pnpm --filter @hivegrid/storybook dev # designer-facing live a11y feedback
|
||||
```
|
||||
|
||||
`pnpm verify:e2e-a11y` exits successfully with a SKIP message when Playwright is
|
||||
@@ -237,6 +237,6 @@ missing inputs or unavailable 400/403/404/login responses into failures.
|
||||
Scheduled GitHub/Gitea readiness workflows run this contract against staging
|
||||
with `E2E_BROWSER_MATRIX=1`, `E2E_A11Y_STRICT=1`, and
|
||||
`E2E_ALLOW_WORKFLOW_RUN=1`.
|
||||
Stripe/provider-live paths and mutating account/workflow actions stay separately
|
||||
Legacy-Provider/provider-live paths and mutating account/workflow actions stay separately
|
||||
opt-in through their own env vars. Set `SKIP_E2E_A11Y=1` when a local or CI lane
|
||||
should explicitly bypass the browser sweep.
|
||||
Reference in new issue
Block a user