Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+3
-3
@@ -13,11 +13,11 @@ An admin-managed feature is configured by admin/platform operators and consumed
|
||||
- Tenant feature enabled only for selected plans or accounts.
|
||||
- Browser automation where admin controls allowed domains and runtime policy.
|
||||
|
||||
## Required Manifest Entries
|
||||
## Required ticket contract
|
||||
|
||||
The feature manifest must declare:
|
||||
The owning ticket doc must declare:
|
||||
|
||||
- `integration.ownership = "admin-managed"` or `"hybrid"`.
|
||||
- Admin-managed or hybrid ownership.
|
||||
- Admin routes that manage provider/policy.
|
||||
- Tenant routes that consume the feature.
|
||||
- Secrets and who owns them.
|
||||
|
||||
@@ -1,68 +0,0 @@
|
||||
# Feature Integration Playbook
|
||||
|
||||
Use this playbook when adding a feature to the boilerplate or adapting a proprietary feature from another product.
|
||||
|
||||
## Goal
|
||||
|
||||
Make the feature understandable before implementation. A human operator and a coding agent should be able to answer where the feature lives, who owns its configuration, which flows it exposes, and how to verify it.
|
||||
|
||||
## Required Steps
|
||||
|
||||
1. Read `docs/agent-entrypoints.md`.
|
||||
2. Find or create a manifest in `docs/feature-manifests/`.
|
||||
3. Classify ownership:
|
||||
- `tenant-owned`: tenant configures and uses it.
|
||||
- `admin-managed`: admin/platform configures it; tenant only uses approved surfaces.
|
||||
- `hybrid`: admin defines policy/defaults; tenant can configure local behavior.
|
||||
- `system-only`: internal platform feature with no tenant-owned controls.
|
||||
4. Map surfaces:
|
||||
- Admin route source files and canonical admin-host runtime paths.
|
||||
- Tenant route source files and canonical tenant-host runtime paths.
|
||||
- Public route source files and root/web-host runtime paths.
|
||||
- API route source files and canonical API-host `/v1/...` runtime paths.
|
||||
- Link/form/action helpers: `adminPath`, `appPath`, `apiPath`, cross-host helpers, or `UrlUtils.getModulePath(...)` for tenant modules.
|
||||
5. Map persistence:
|
||||
- Prisma models.
|
||||
- Existing tables reused.
|
||||
- Migrations required.
|
||||
- Tenant scoping fields.
|
||||
6. Map configuration:
|
||||
- Admin settings.
|
||||
- Tenant settings.
|
||||
- Environment variables.
|
||||
- Secrets and their owner.
|
||||
7. Map runtime:
|
||||
- Request/response only.
|
||||
- Queue-backed.
|
||||
- Worker-backed.
|
||||
- Browser-backed.
|
||||
8. Map controls:
|
||||
- Permissions.
|
||||
- Audit events.
|
||||
- Billing or usage limits.
|
||||
9. Define UAT:
|
||||
- Operator-visible checks.
|
||||
- Negative checks for forbidden access.
|
||||
- Secret exposure checks if providers are involved.
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
- Do not expose provider secrets through tenant loaders, API responses, client bundles or logs.
|
||||
- Do not add sidebar/nav entries without stable UI IDs.
|
||||
- Do not add new root UI primitives without updating `docs/ui-inventory/components.json`.
|
||||
- Do not add worker behavior without declaring queues and jobs in the manifest.
|
||||
- Do not add admin-managed tenant behavior without admin permissions and audit events.
|
||||
- Keep proprietary feature logic behind explicit module boundaries.
|
||||
- Do not hard-code legacy runtime paths such as `/admin/...`, `/app/...`, or `/api/v1/...` outside tests that explicitly cover legacy redirects.
|
||||
- Do not ship visible UI text without locale keys and `pnpm run verify:i18n`.
|
||||
|
||||
## Done Criteria
|
||||
|
||||
- Manifest updated and valid.
|
||||
- Routes and surfaces match the manifest.
|
||||
- Permissions are enforced on admin/API/tenant surfaces.
|
||||
- Tenant-scope negative tests cover forbidden reads and mutations.
|
||||
- Route helpers and runtime host ownership are tested for new navigation.
|
||||
- i18n and deploy/static verifiers relevant to the change have run.
|
||||
- Required worker queues/jobs exist or are explicitly deferred.
|
||||
- UAT checks pass or are marked as deferred with a reason.
|
||||
+4
-2
@@ -1,6 +1,7 @@
|
||||
# Foundation Boundary Playbook
|
||||
|
||||
Use this when moving feature logic into the reusable boilerplate layer or when touching audit, idempotency, flags, permissions, billing usage, or notifications.
|
||||
Use this when moving feature logic into HiveGrid's shared foundation or when touching audit,
|
||||
idempotency, flags, permissions, billing usage, or notifications.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
@@ -20,5 +21,6 @@ Use this when moving feature logic into the reusable boilerplate layer or when t
|
||||
## Done Criteria
|
||||
|
||||
- Add or update focused tests in the owning package.
|
||||
- Update feature manifests when a feature changes ownership, billing, provider, worker, or admin-managed behavior.
|
||||
- Update the owning ticket doc and architecture decision when ownership, billing, provider, worker,
|
||||
or admin-managed behavior changes.
|
||||
- Run `pnpm run test:foundation`, the affected package tests, and the app-level route tests for changed runtimes.
|
||||
@@ -1,62 +0,0 @@
|
||||
# MVP Intake Playbook
|
||||
|
||||
Use this before adapting an existing MVP onto this boilerplate.
|
||||
|
||||
## Purpose
|
||||
|
||||
Prevent agents from copying product code blindly. The MVP must first be decomposed into flows, roles, data, providers, ownership and runtime behavior.
|
||||
|
||||
## Intake Checklist
|
||||
|
||||
Capture the following before implementation:
|
||||
|
||||
- Product summary: what the MVP does in one paragraph.
|
||||
- Primary user roles.
|
||||
- Admin/operator roles.
|
||||
- Tenant roles.
|
||||
- Critical user flows.
|
||||
- Data objects and ownership.
|
||||
- External providers.
|
||||
- Secrets and credentials.
|
||||
- Background jobs.
|
||||
- Browser automation or long-running work.
|
||||
- Billing or usage limits.
|
||||
- Existing UI surfaces.
|
||||
- Must-keep behavior.
|
||||
- Behavior that should become plugin-only.
|
||||
- Behavior that should be removed.
|
||||
|
||||
## Flow Mapping
|
||||
|
||||
For every flow, record:
|
||||
|
||||
- Entry point.
|
||||
- Actor.
|
||||
- Preconditions.
|
||||
- Data read.
|
||||
- Data written.
|
||||
- Provider calls.
|
||||
- Sync versus async behavior.
|
||||
- Success state.
|
||||
- Failure state.
|
||||
- UAT check.
|
||||
|
||||
## Boilerplate Mapping
|
||||
|
||||
Map each flow into:
|
||||
|
||||
- `apps/web/app/routes/admin*` for admin/platform management files; runtime links must use `adminPath` or admin-host helpers.
|
||||
- `apps/web/app/routes/app.$tenant*` for tenant-facing usage files; runtime links must use `appPath`, `UrlUtils.getModulePath(...)`, or an equivalent host-aware wrapper.
|
||||
- `apps/api/src/app.ts` under `/v1` for canonical public/service APIs and webhooks. If a `/v1` route temporarily proxies a web `internal/api` handler, record `apps/api` as the external route owner and the web handler as the temporary implementation owner until extraction lands.
|
||||
- `apps/web/app/modules/<feature>` for feature-owned application logic.
|
||||
- `apps/worker` and `packages/queue` for async jobs.
|
||||
- `docs/feature-manifests/<feature>.json` for the integration contract.
|
||||
|
||||
## Output Required From Agent
|
||||
|
||||
Before coding, the agent should produce:
|
||||
|
||||
- A short MVP decomposition.
|
||||
- A feature manifest draft or update.
|
||||
- A list of unknowns that block safe implementation.
|
||||
- An implementation plan tied to the manifest.
|
||||
+5
-4
@@ -12,11 +12,11 @@ Use this when a feature performs slow, retryable, external, scheduled, browser-b
|
||||
- Work should continue after a user navigates away.
|
||||
- Usage metering or cleanup must be reliable.
|
||||
|
||||
## Required Manifest Entries
|
||||
## Required ticket contract
|
||||
|
||||
The feature manifest must declare:
|
||||
The owning ticket doc must declare:
|
||||
|
||||
- `integration.workers.required`.
|
||||
- Whether a worker is required.
|
||||
- Queue names from `packages/queue/src/names.ts`.
|
||||
- Job names from `packages/queue/src/payloads.ts`.
|
||||
- Notes about retries, idempotency and cleanup.
|
||||
@@ -31,7 +31,8 @@ The feature manifest must declare:
|
||||
- Jobs should be idempotent or have explicit duplicate protection.
|
||||
- Browser jobs must enforce admin-owned navigation policy.
|
||||
- Failures should be visible to the initiating user or admin.
|
||||
- AI/browser-backed features use `hivegrid.ai-chatbot` and `hivegrid.browser-automation` unless a manifest explicitly justifies a new queue.
|
||||
- Browser-backed features use the existing queue contracts unless the ticket explicitly approves a
|
||||
new queue.
|
||||
|
||||
## Browser-Backed Work
|
||||
|
||||
|
||||
Reference in new issue
Block a user