feat(constructive-blocks): copy-in UI Blocks skill + GA auth-flows selection guide#161
Draft
yyyyaaa wants to merge 8 commits into
Draft
feat(constructive-blocks): copy-in UI Blocks skill + GA auth-flows selection guide#161yyyyaaa wants to merge 8 commits into
yyyyaaa wants to merge 8 commits into
Conversation
Add the constructive-blocks skill so agents can discover the copy-in block workflow: SKILL.md, binding-doctrine and manifest-and-checks references, and the zero-dependency check-sdk.mjs preflight gate that proves the host's generated GraphQL SDK exports every operation a data block requires. List the skill in the CLAUDE.md and README.md catalogs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…, and signUp shapes
Real live-run blockers a builder hit, corrected against the generated SDK
types and the working provisioning builder:
- secureTableProvision input is the Blueprint shape (nodes/fields/grants/
policies discriminated by $type), not the flat nodeType/grantRoles/
policyType/policyData shape. fields[] is the one Record<string,unknown>[]
array member, so it assigns uncast (matching the live builder); nodes/
grants/policies stay cast as they are scalar object members.
- SDK import is @constructive-io/sdk (the @constructive-db/sdk package does
not exist).
- signUp selects fields off `result` (a SignUpRecord), never top-level on
SignUpPayload: the { ok, errors } form is replaced with { result { id } },
and the device example selects outDeviceToken under result and reads it via
result.signUp.result (it was selected at the payload root, which does not
compile; outDeviceToken is devices_module-gated, mirroring the sign-in
example above it).
Also reconcile constructive-starter-kits: document the SDK output path
(src/graphql/schema-builder-sdk/api) vs the blocks @/generated/* convention
so an agent following both is not contradicted, and add brief block/React
test guidance (replace the data layer via BlocksRuntime override or mock the
@/generated module — never the network — since generated hooks bind a
module-level singleton).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… apps
The bundled preflight failed on every standard Next.js app, for two reasons:
- JSONC comment stripping was a naive regex that also devoured `/* … */`
sequences occurring INSIDE quoted strings. A tsconfig path glob like
`"@/*": ["./src/*"]` contains a `/*`…`*/` span across string literals, so
the regex corrupted valid JSON and `JSON.parse` threw ("Bad control
character…"). Replace it with a single-pass, string-aware scanner
(`stripJsonComments` + `stripTrailingCommas`) that only strips comments and
trailing commas OUTSIDE string literals and honours `\"` / `\\` escapes.
This also hardens the `extends` path, which routes through the same reader.
- shadcn writes block manifests to `<project>/src/.constructive/blocks` when
the blocks registry target resolves under `src/` (the usual Next.js
layout), but the script only scanned the project-root `.constructive`, so
it silently found nothing and false-passed. Discover manifests under BOTH
`<root>/.constructive/blocks` and `<root>/src/.constructive/blocks`, add a
`--manifests-dir`/`-m` override that short-circuits discovery, and de-dupe
by manifest file name (root wins) so the same block present in both
locations is reported once while distinct blocks are never merged.
Update SKILL.md and references/manifest-and-checks.md to document the `src/`
manifest location, the dual-location scan, the `--manifests-dir` override, and
the string-aware stripping. Regenerate the distribution zip so the packaged
artifact carries the fixed script and docs.
Exit-code contract is preserved (0 satisfied/nothing-to-check, 1 missing op,
2 cannot-run). Verified against a real Next.js tsconfig fixture and the full
contract matrix.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ovisioning docs 'all' is not a provisioning sentinel. metaschema_generators.provision_database_modules matches explicit module names via 58 `ANY(v_modules)` branches; there is no 'all' expansion in the SQL proc, trigger, SDK, or CLI. modules:['all'] therefore installs nothing, after which bootstrapUser fails (TARGET_USERS_NOT_FOUND), per-DB auth is empty, and app-public queries hit RLS denials. Replace every recommended ['all'] with explicit module lists across constructive-sdk (SKILL + references/provisioning.md), constructive-sdk-services, constructive-sdk-database, constructive-features, and constructive-platform (module-presets, blueprint-definition-format). The basic-auth default is the verified auth:email 12-module list; b2b/full point at their preset module lists. Also add the missing bootstrapUser:true to the constructive-sdk-services provisioning example so the recommended path actually creates the admin user. Correct the stale "via ['all'] sentinel" claims for devices_module (in b2b+full) and realtime_module (in no shipped preset). Names and lists verified against constructive/packages/node-type-registry/src/module-presets. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
SKILL.md 'Flow selection (start here)' decision-point reads the generated references/flows.json + flow-catalog.md (from the apps/blocks SoT). check-flows.mjs asserts sotHash sync (SoT/skill/harness) + referential integrity; exposed as pnpm check:flows. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Regenerate references/flows.json (+ flow-catalog.md) so backend.modules carries
the preset's native ["name",{scope}] tuples — the form the provision proc
accepts (colon "name:scope" strings throw NOT_FOUND). New sotHash
a47970f72893f7483eb9ab844c3744a6403154ffa0a8c2b660980b87aafa631c.
check-flows.mjs: the modules ⊆ preset referential check now normalizes BOTH
sides to the display key, so a native tuple ["memberships_module",{scope:"app"}]
matches the preset's memberships_module:app. All checks green; skill/harness
flows.json byte-identical.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…red-pending ops; align field/security shapes
Three friction fixes from the email-free verification wave (VERIFICATION-FINDINGS).
F12 — check-sdk.mjs model check (the exit-1 on correctly-wired org blocks):
- The ORM accessor and its models/<name>.ts file are ALWAYS singular, but
catalog manifests declare list models plural (orgMemberships, users,
appMemberships, orgProfiles). Add singularizeModel() and key the SDK's model
set through it; normalise the declared name the same way before matching.
Plural-manifest, singular-manifest, and singular-file now collapse onto one
key — so a manifest is correct whether the apps/blocks owner ships singular
OR plural (the "make BOTH-correct" rule).
- Support an optional manifest `pending` array: ops a block declares as
backend-pending seams (transferOrgOwnership, removeOrgMember) are reported
(◦ informational) but NEVER fail the check. A missing op NOT declared pending
still fails clearly, so genuine wiring/stale-SDK errors are never masked.
- Add a zero-dep node:test suite (check-sdk.test.mjs) + `test:sdk` script; doc
the singular-normalisation + `pending` field in manifest-and-checks.md.
Verified end-to-end against the real generated SDK + the shipped org manifests.
F5 — constructive-sdk-fields: add a field-shape disambiguation note. db.field
(metaschema) uses bare-string `type`/`defaultValue` (matches generated
CreateFieldInput) and must stay that way; the OBJECT shape (type {name:'text'}
+ default {value:false}) belongs to the blueprint createBlueprint node, a
different API. Clarify both (and the third secureTableProvision fields[] shape)
so builders stop conflating them.
F9 — constructive-sdk-security §5: rewrite secureTableProvision off the stale
flat nodeType/grantRoles/grantPrivileges/policyType/policyData shape onto the
Blueprint nodes[]/fields[]/grants[]/policies[] arrays that the generated
CreateSecureTableProvisionInput actually exposes (matching the verified
constructive-sdk example). Left the separate tableGrant/policy/applyRls
metaschema APIs (§3/§4) untouched — those legitimately differ.
flows.json / flow-catalog.md untouched; drift guard green (sotHash a47970f7).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Integrates the boss's umbrella-skill consolidation (2c114e9) plus targeted fixes (102c9fb colon→jsonb-tuple, 5f7a550/8181c43 FieldType/FieldDefault, b66e20a auth/authz gap-fill, c10ee85 node-type-registry, dce76fd cross-ref renames, features.md) on top of the constructive-blocks work. Conflict resolution (10 conflicts): - CLAUDE.md, README.md: took boss's 20-umbrella structure; re-added the constructive-blocks row (boss has no constructive-blocks skill). - constructive-features/SKILL.md, constructive-blueprints/references/ module-presets.md: took boss (richer b2b:storage/user_settings content; cross-refs already point at new umbrella skills). - constructive-blocks skill (8 files) + flows.json: kept OURS verbatim (untouched by main); flows.json sotHash a47970f7… preserved byte-for-byte. - 6 modify/delete (boss consolidated away skills we edited): accepted the boss's deletions. Then: * Ported our F9 secureTableProvision Blueprint-shape fix (nodes[]/fields[]/ grants[]/policies[] arrays, validated against node-type-registry generated types) into constructive-security/SKILL.md and constructive-data-modeling/ SKILL.md — the boss's new locations carried the stale flat nodeType/ grantRoles/policyType shape. * Dropped our F5 field-shape note (constructive-sdk-fields): the boss's canonical FieldType/FieldDefault object shape supersedes it; the note's bare-string premise is wrong (metaschema field triggers reject strings). * Rehomed the blocks testing recipe (override seam / @generated mock / BlocksRuntime) from the deleted starter-kits/nextjs-app.md into the constructive-blocks skill (no equivalent existed post-merge). modules:['all'] consistency: git auto-carried our explicit-list fix through the boss's renames into provisioning.md + blueprint-definition-format.md, contradicting boss files that kept the ['all'] sentinel text. Verified against the SQL source of truth (provision_database_modules: 38 named-module branches, 0 'all' expansion) that ['all'] installs nothing, then made the whole tree consistent in the explicit-list direction (module-presets.md, data-modeling/ SKILL.md, i18n prereq line). Updated constructive-blocks cross-refs that the consolidation broke (constructive-sdk-graphql → constructive-codegen/hooks/orm/search) and re-zipped the skill to match its full 8-file on-disk inventory. Guards green: check-flows (sotHash a47970f7, in sync), check-sdk 6/6. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds the
constructive-blocksAI-agent skill and the GA auth-flows selection guide — the agent-facing half of the cross-repo Constructive Blocks effort (library/docs inconstructive-io/dashboard#227, build harness inconstructive-sdk-agentic-flow, scaffold template insandbox-templates).Contents
constructive-blocksskill — install / wire / author copy-in UI blocks (shadcn registry,@constructive/<block>) that bind to the host's per-app generatedauth+adminSDK:blocks-runtime,requires.jsonmanifests, bundledcheck-sdk.mjspreflight.flows.json+flow-catalog.md(the 18 GA auth "flows", better-auth-plugin style) generated from the single source of truth inapps/blocks, with acheck-flows.mjssotHash drift guard.:scopeform is rejected by the provision proc),secureTableProvision/field/security shapes,check-sdksingular/plural + declared-pending ops, andmodules:['all']→ explicit module lists.main(the 33 → 20 umbrella-skill consolidation).Status
Draft / WIP. Verified by building + browser-testing the catalogued flows on a live
constructive-hubvia the agentic-flow harness (the doc-bug classes the skill teaches all routed in the latest speed re-runs).🤖 Generated with Claude Code