CLI implementation handoff
Machine-readable page contracts, verified database journey, known SQL corrections, and the order for turning every preview into a working admin.
Verified creation journey
The durable order the production worker/API must preserve.
CustomerAccountId, separate BuilderUserId, plan and subscription.
SaaSAppId + SaasAppIdInt, domain, route, allocation and usage meters.
Core clone, logging DB, AI DB, memory-optimized container and identity stamp.
AppAccount, tenant owner UserId, data role, log/AI bridges; app Active.
Settings, theme, top bar, shell, navigation and empty Home page.
Component contract, edit lock, Draft history, Publish history and page v2.
sp_Runtime_GetPageBootstrap with four ordered result sets.
TypeScript normalizer and core.text renderer; install/typecheck in the real app.
Identity boundaries
- Builder plane
- CustomerAccountId + BuilderUserId
- App identity
- SaaSAppId + SaasAppIdInt
- Tenant plane
- AppAccountId + tenant UserId
- Never reuse
- BuilderUserId as tenant UserId
Database boundaries
- Control
- buildwithHQ_Customers
- Golden clone
- buildwithHQ_CustomerCopy
- Shared catalog
- BuildWithHQ_TemplateLibrary
- Per app
- core + logs + AI
CLI completion rules
Apply these to every route before marking it complete.
Server context
- JWT/session resolves account and builder user.
- Route app ID is ownership-validated.
- Tenant IDs are server-injected.
- Never trust entitlement, price, role, or scope IDs from the browser.
Page states
- Loading and skeleton.
- Empty real-data state.
- Forbidden and not found.
- Validation errors mapped to fields.
- Retrying, succeeded, failed and stale-worker states.
Data discipline
- Remove fixture rows after wiring.
- Use keyset pagination for operational history.
- Return safe messages and correlation IDs.
- Keep secrets, hashes and provider payloads server-side.
Known corrections discovered during the journey
These are part of the final contract, not optional cleanup.
| Area | Required behavior | Failure avoided |
|---|---|---|
| Component upsert | A supplied new ComponentId inserts; existing ID updates; natural key resolves canonical ID. | Silent zero-row UPDATE that returned a nonexistent component ID. |
| Save draft result | sp_SaveBasePageRaw can expose a nested PageHistoryId row and an outer JSON report; select only valid JSON. | Passing a GUID into JSON_VALUE (Msg 13609). |
| Publish page | Execute sp_PublishBasePage directly and verify durable page/history rows. | FOR JSON inside INSERT...EXEC (Msg 13602). |
| Templates | Install exact immutable schema-v2 TemplatePackVersionId with verified fingerprints/members. | Seeding catalog-only, mutable, mismatched, or another account's pack. |
| Activation | Activate after tenant root/security/bridges verify; domain and container remain separate. | Blocking BuilderOnly apps on optional container or pending custom domain. |
Files the CLI should read first
All are included in this archive.
1 · Global guide
CLI_IMPLEMENTATION_GUIDE.md
Architecture, route policy, work order, error handling and completion checklist.
2 · Page manifest
admin-cli-manifest.json
One structured entry per page with route, access, retrieve/save/success contracts and status.
3 · Verified references
reference/signup-journey/reference/runtime-react-contract/
Final SQL journey and TypeScript/React contract.
4 · Task checklist
CLI_TASK_CHECKLIST.jsonCLI_PROGRESS_CHECKLIST.md
One incomplete implementation record per route.
Behind this page/cli-handoff · authenticated developer
Retrieve
Static implementation documentation generated from the preview contracts and verified journey outputs.
Save
Read-only. The CLI changes application code, not this page at runtime.
Success
- Every route is wired to real data.
- Fixture rows are removed.
- Server-side authorization is enforced.
- Integration tests cover critical workflows.
CLI handoff
Implement this scaffold from the structured contract, then remove hard-coded preview rows. The source of truth is CLI Handoff and admin-cli-manifest.json.
Server-inject identity and scope values; never trust browser-supplied account, app, tenant, user, entitlement, price, or permission identifiers. Preserve the loading, empty, forbidden, failed, retrying, and completed states shown by the preview.