@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/templates/next-skills.ts

@@ -21,6 +21,11 @@
  * unreadable skill.
  */
 
+import vendored from '../vendor/sdk-sources.json'
+
+/** The SDK release these skills describe: the one the scaffold pins (`^<version>`). */
+const SDK_VERSION = vendored.sdkVersion
+
 interface Skill {
   name: string
   description: string
@@ -514,6 +519,14 @@ const actions: Skill = {
     "import { actionEffectOf, recordVersionOf } from '@frontera-sdk/blueprint/action-types'",
     '```',
     '',
+    `This skill describes \`@frontera-sdk/blueprint\` ${SDK_VERSION}, the release the scaffold pins`,
+    `(\`^${SDK_VERSION}\`). \`useAction\`'s \`available\`, \`reason\` and \`reasonText\` need that release or`,
+    'later: an older install returns only `{ action, isLoading, error }`. `frontera local check` (its',
+    'apps step) and `app_dev` warn when the installed SDK is older than this, or lacks what it exports,',
+    'and name the upgrade. When the local runtime runs from a platform checkout (source mode), the App',
+    'uses that checkout\'s SDK instead: `frontera app sdk use-local` packs it into `vendor/frontera-sdk/`',
+    '(`--npm` switches back).',
+    '',
     '## Rules',
     '',
     '- **Render controls from `useActions()`**, or `useAction(apiName)` for one — never from a',
@@ -521,6 +534,12 @@ const actions: Skill = {
     '  server knows which. A button that 403s on click is worse than one that was never drawn.',
     '- An empty discovery list in development is almost always permissions, not a bug: an Action is',
     '  hidden unless it is published, deployed, AND its invoke capability is held by your role.',
+    '- **Never disable a control without saying why.** `useAction(apiName)` returns `available` and,',
+    '  when it is false, `reasonText`: a sentence for the person, the platform\'s own when it may tell',
+    '  this caller (such as `capability_not_granted` or `not_deployed` in `reason`, with `next` saying',
+    '  what would fix it while you build), else a neutral "not available". Leave the control out, or',
+    '  keep it visible and show `reasonText` beside it or as its tooltip; a silently greyed-out button',
+    '  reads as a bug. Never show `next` to the App\'s users: it is for the person building it.',
     '- **A submit is not a write.** `useSubmitAction(action)` resolves when the Request is RECORDED;',
     '  dispatch happens on a background worker. A success toast in `onSuccess` claims something the',
     '  App does not know yet.',
@@ -534,9 +553,11 @@ const actions: Skill = {
     '  takes `{ requestId, decision, reason }`. Do not design a flow that assumes instant application.',
     '  For an approval with steps, the decision must also pass the current step of the request,',
     '  `request.approval.currentStage`, as `stage`.',
-    '- Editing an existing record: pass `expectedVersion: recordVersionOf(instance.data)`, read from',
-    '  `useObjectInstance` — a LIST row does not carry the version. Omitting it does not fail; the',
-    '  compare-and-set is skipped and two people overwrite each other with no refusal and no evidence.',
+    '- Editing an existing record: pass `objectId` and `expectedVersion: recordVersionOf(instance.data)`,',
+    '  read from `useObjectInstance` — a LIST row does not carry the version. The platform fills the',
+    '  Action\'s key input and its `expectedVersion` input from these, so `input` holds only the change.',
+    '  An edit without the version is refused as stale; a key or version in `input` that disagrees with',
+    '  them is refused too.',
     '- Idempotency keys are minted per `mutate` call. That is the correct lifetime — a retried network',
     '  call cannot double-apply, a second click is a second intent — so do not supply your own.',
     '- Refresh reads when the request reaches a terminal APPLIED state, not when the submit resolves.',
@@ -545,14 +566,22 @@ const actions: Skill = {
     '',
     '```tsx',
     '// src/ui/approve-loan/approve-loan.tsx',
-    "const { action } = useAction('ApproveLoan')",
+    "const { action, isLoading, reasonText } = useAction('ApproveLoan')",
     'const submit = useSubmitAction(action)',
     'const [requestId, setRequestId] = useState<string | null>(null)',
     'const request = useActionRequest(requestId)',
     'const effect = actionEffectOf(request.data)',
     '',
-    '// Not drawn at all when the caller may not invoke it.',
-    'if (!action) return null',
+    'if (isLoading) return null',
+    '// Kept visible, it says why it cannot be used (or return null to leave it out).',
+    'if (!action) {',
+    '  return (',
+    '    <div>',
+    '      <Button disabled title={reasonText ?? undefined}>{copy.loan.approve}</Button>',
+    '      <p className="text-sm text-muted-foreground">{reasonText}</p>',
+    '    </div>',
+    '  )',
+    '}',
     '',
     'return (',
     '  <>',
@@ -1126,7 +1155,7 @@ const security: Skill = {
     '## Verification',
     '',
     '```bash',
-    'frontera app deploy --no-promote',
+    'frontera app deploy',
     '```',
     '',
     'Open the preview URL and watch the browser console: a blocked request is a CSP declaration you',
@@ -1152,40 +1181,46 @@ const release: Skill = {
     '## Safe sequence',
     '',
     '1. `bun run check` — typecheck, tests, then the build. The build is the authoritative',
-    '   static-export compatibility check.',
+    '   static-export compatibility check. `frontera app deploy` runs it too and records the result.',
     '2. Confirm `out/index.html` exists, along with every route you intended to export.',
-    '3. `frontera app deploy --no-promote` — publishes a version without moving the live pointer.',
-    '4. Open the returned preview URL. Check it embedded and at a narrow width, in both themes, and',
-    '   watch the console for blocked requests.',
-    '5. `frontera app promote <version>` — point live at it.',
+    '3. `frontera app deploy` — uploads an immutable preview deployment with its own id and link,',
+    '   and moves this branch\'s and this session\'s preview links to it. It never changes what users see.',
+    '4. Open the returned preview URL (or render it). Check it embedded and at a narrow width, in both',
+    '   themes, and watch the console for blocked requests.',
+    '5. `frontera app promote <deployment>` — point production at it, once the required checks pass.',
+    '   Promoting needs the promote permission; a coding agent leaves it to a person.',
     '',
     '```bash',
-    'frontera app deploy --no-promote',
+    'frontera app deploy',
     '```',
     '',
     '```bash',
-    'frontera app versions',
+    'frontera app deployments',
     '```',
     '',
     '## Rules',
     '',
-    '- Versions are immutable. Never reuse a version string for different bytes.',
-    '- Rollback is promoting an earlier version, not rebuilding one. That is the whole reason the old',
-    '  bytes are kept.',
-    '- Promote deliberately. A deploy that promotes by default turns every experiment into a release.',
-    '- `frontera app versions` shows runtime, routing, framework provenance, source commit and dirty',
-    '  status, sizes and the live pointer. The CLI-recorded provenance is metadata; the',
-    '  service-computed digest, file count, byte count and uploader are authoritative.',
+    '- Deployments are immutable and get their own id. `--label 1.4.0` adds a release label,',
+    '  unique per App; never reuse one for different bytes.',
+    '- `frontera app deploy --prod` goes live in one step once the checks pass; `--prod --no-promote`',
+    '  stages it for production without serving it.',
+    '- Rollback moves a pointer, it never rebuilds: `frontera app rollback --reason "…"` returns',
+    '  production to the previous production deployment and PINS it. Nothing promotes until',
+    '  `frontera app rollback --undo` or an Unpin, so the next routine deploy cannot undo the rollback.',
+    '- `frontera app deployments` shows each deployment\'s producer, session, branch, commit and',
+    '  dirty status, render evidence and which link serves it. The CLI-recorded provenance is',
+    '  metadata; the service-computed digest, file count, byte count and producer are authoritative.',
     '- Deploying from a dirty tree is recorded as dirty. Do not do it for a release you intend to',
     '  reproduce later.',
-    '- Customer CI runs the same two commands with credentials from the CI secret store, never from',
+    '- Customer CI runs the same commands with credentials from the CI secret store, never from',
     '  the repository.',
     '- A schema-dependent change needs `bun run blueprint:types:check` in CI: the App can build',
-    '  perfectly against a contract the workspace no longer has.',
+    '  perfectly against a contract the workspace no longer has. The platform checks the',
+    '  deployment\'s Blueprint contract again before it goes live.',
     '',
     '## Red Flags — STOP',
     '',
-    '- Promoting a version nobody opened.',
+    '- Promoting a deployment nobody opened.',
     '- Deploying without `bun run check`, or after only a typecheck.',
     '- Editing `out/` by hand.',
     '- Rebuilding to "roll back".',
@@ -1194,11 +1229,10 @@ const release: Skill = {
     '## Verification',
     '',
     '```bash',
-    'frontera app versions',
+    'frontera app deployments',
     '```',
     '',
-    'The live pointer must name the version you promoted, and its digest must match the deploy you',
-    'previewed.',
+    'Production must name the deployment you promoted, and it must be the one you previewed.',
     '',
     '## Scope',
     '',