@frontera-sdk/cli 1.43.10 → 1.44.0

package/src/template.ts

@@ -1,23 +1,23 @@
 import { mkdirSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 
+import { nextAppFiles } from './templates/next-app-files'
+import { nextSkillFiles } from './templates/next-skills'
 import vendored from './vendor/sdk-sources.json'
 
 /**
  * Project scaffold.
  *
- * Everything the author should NOT have to write lives here: the Vite config,
- * the entry point, the design tokens, and the SDK itself. What is left in
- * `src/App.tsx` is application code, which is the whole point of the rewrite.
- *
- * The SDK arrives as VENDORED SOURCE under `src/frontera/`, not as a
- * dependency — see `scripts/sync-sdk.ts` for why. The import specifiers still
- * read `@frontera-sdk/core/…`; `tsconfig` paths and a matching Vite alias
- * resolve them. So `package.json` needs nothing but public npm, and a project
- * pulled onto a machine that has never seen this monorepo still builds.
+ * New projects are ordinary Next.js applications using published Frontera SDK
+ * packages. The explicit legacy React template keeps its vendored SDK tree so
+ * existing Vite applications remain reproducible and can opt into `sdk sync`.
+ * In both cases package.json stays standard package metadata; the static-host
+ * contract belongs to frontera.config.json.
  */
-export function scaffold(target: string, name: string): void {
-  for (const [rel, content] of Object.entries(files(name))) {
+export type AppFramework = 'next' | 'react'
+
+export function scaffold(target: string, name: string, framework: AppFramework = 'next'): void {
+  for (const [rel, content] of Object.entries(scaffoldFiles(name, framework))) {
     const full = join(target, rel)
     mkdirSync(dirname(full), { recursive: true })
     writeFileSync(full, content)
@@ -30,8 +30,11 @@ export function scaffold(target: string, name: string): void {
  * shipped SKILL.md actually exists, and that every `@frontera-sdk/…` import
  * resolves to a file the scaffold actually writes.
  */
-export function scaffoldFiles(name: string): Record<string, string> {
-  return files(name)
+export function scaffoldFiles(
+  name: string,
+  framework: AppFramework = 'next',
+): Record<string, string> {
+  return framework === 'react' ? files(name) : nextFiles(name)
 }
 
 /**
@@ -117,18 +120,6 @@ function files(name: string): Record<string, string> {
         private: true,
         version: '0.1.0',
         type: 'module',
-        frontera: {
-          // No slug: the platform owns it and can rename it, so a committed
-          // copy would go stale. `name` above seeds it on the first deploy, and
-          // `frontera.appId` is written back once the app exists.
-          displayName: name,
-          // Origins this app may reach at runtime, enforced as a CSP by the
-          // host. `frontera app deploy` turns these into the version's
-          // manifest, so an addition takes effect on the next deploy — add one
-          // deliberately rather than discovering the block in production.
-          connectDomains: [],
-          resourceDomains: [],
-        },
         scripts: {
           dev: 'vite',
           build: 'vite build',
@@ -158,6 +149,21 @@ function files(name: string): Record<string, string> {
       2,
     )}\n`,
 
+    // Frontera deployment configuration is deliberately separate from npm's
+    // package manifest. package.json remains standard package metadata; this
+    // file describes how the already-built artifact is hosted.
+    'frontera.config.json': `${JSON.stringify(
+      {
+        displayName: name,
+        outputDirectory: 'dist',
+        routing: 'spa',
+        connectDomains: [],
+        resourceDomains: [],
+      },
+      null,
+      2,
+    )}\n`,
+
     'vite.config.ts': `import { fileURLToPath, URL } from 'node:url'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
@@ -306,7 +312,7 @@ dist/
 
     '.agents/skills/using-frontera-sdk/SKILL.md': `---
 name: using-frontera-sdk
-description: Use at the start of ANY task in a Frontera app project — a Vite project whose package.json carries a "frontera" key and that deploys via the frontera CLI. Establishes the project shape and routes to the right pattern.
+description: Use at the start of ANY task in a Frontera Vite app project with frontera.config.json that deploys via the frontera CLI. Establishes the project shape and routes to the right pattern.
 ---
 
 # Frontera App Development
@@ -395,13 +401,13 @@ handshake must not ship with the app.
 
     '.agents/skills/frontera-app-data/SKILL.md': `---
 name: frontera-app-data
-description: Use when reading platform data in a Frontera app — useObjects, useAggregate, useObjectInstance, where clauses, paging, and why filtering must happen on the server.
+description: Use when reading platform data in a Frontera app — useObjects, useAggregate, useMetric, useObjectInstance, where clauses, paging, and why filtering must happen on the server.
 ---
 
 # Reading Blueprint data
 
 \`\`\`tsx
-import { useObjects, useAggregate } from '@frontera-sdk/blueprint/hooks'
+import { useObjects, useAggregate, useMetric } from '@frontera-sdk/blueprint/hooks'
 import { objectsOf, type WhereNode } from '@frontera-sdk/blueprint/types'
 \`\`\`
 
@@ -419,7 +425,7 @@ const where: WhereNode | undefined = status
   ? { property: 'deliveryStatus', op: 'eq', value: status }
   : undefined
 
-const rows = useObjects<Shipment>('Shipment', { where, page: 1, pageSize: 20 })
+const rows = useObjects<Shipment>('Shipment', { where, pageToken, pageSize: 20 })
 \`\`\`
 
 Filtering \`rows.data.rows\` in the component instead is the classic mistake: it
@@ -429,15 +435,165 @@ renders 5 of them and the footer claims "Page 1 of 1".
 For the same reason, a total is its own query — \`useAggregate\` with a count
 over the SAME object set — not \`rows.length\`.
 
-## Paging
+## Paging is a cursor
 
-\`page\` is 1-based. Server-driven tables need \`pageCount\` and \`rowCount\` from
-the aggregate, or the table re-paginates one page of server data.
+Omit \`pageToken\` for the first request, then pass the response's opaque
+\`nextPageToken\` to advance. Keep earlier tokens in UI state if Previous is
+required, and reset them whenever filters, sort or projection change. Numeric
+page labels and aggregate totals are presentation; they are not Blueprint
+navigation inputs.
+\`\`\`tsx
+const [token, setToken] = useState<string | undefined>()
+const page = useObjects<Ticket>('SupportTicket', { pageSize: 25, pageToken: token })
+// next     setToken(page.data?.nextPageToken)
+// restart  setToken(undefined)
+\`\`\`
+
+There is **no page number**. Offset paging was removed — it has no defined
+meaning over an unordered scan — and the service refuses a request carrying
+\`page\` outright. \`hasMore\` is false and \`nextPageToken\` absent on the last
+page; its absence is how a scan learns it has finished.
+
+There is also no total, so a "Page 3 of 12" footer cannot be built from this.
+Show a count from \`useAggregate\` over the same object set if you need one.
 
 ## Identity
 
 \`useObjectInstance(objectType, pk)\` returns one record and is disabled while
 \`pk\` is null, so a detail panel can mount before a row is selected.
+
+## Metrics the organization already defined
+
+\`\`\`tsx
+const revenue = useMetric('codShare', { from, to })
+\`\`\`
+
+A metric exists so every reader computes it the same way. Prefer one over
+\`useAggregate\` whenever it exists: re-deriving a defined figure from raw
+columns is how two dashboards disagree about one number, and it is where the
+arithmetic bugs live. \`frontera blueprint list\` shows what is defined.
+
+Do NOT hand-roll a hook around \`useBlueprintClient\` for this — that escape
+hatch is for calls with no hook, and a metric has one.
+
+## The escape hatch
+
+\`useBlueprintClient()\` returns the raw client for anything the hooks do not
+cover. Everything above is built on it, so reach for it last, not first.
+`,
+
+    '.agents/skills/frontera-app-actions/SKILL.md': `---
+name: frontera-app-actions
+description: Use when an app must CHANGE something — governed Actions, useAction/useSubmitAction/useActionRequest, why a button may not exist for every user, and why submitting is not the same as done.
+---
+
+# Changing data through a governed Action
+
+\`\`\`tsx
+import { useAction, useSubmitAction, useActionRequest } from '@frontera-sdk/blueprint/action-hooks'
+\`\`\`
+
+An app never writes to the Blueprint directly. It submits a **Request** against
+a published Action, and the platform decides whether it runs, who must approve
+it, and when it dispatches. There is no write hook, and adding one is not the
+answer to "this is slow".
+
+## Render controls from discovery, never from a list you wrote
+
+\`\`\`tsx
+const { action } = useAction('escalateTicket')   // null when this user may not
+const submit = useSubmitAction(action)
+\`\`\`
+
+Authorization is per **person**, not per app: the signed-in user's role decides.
+The same page must offer a control to one colleague and not another, and only
+the server knows which. A hard-coded button that 403s on click is worse than one
+that was never drawn — so gate on \`action\`, and render a disabled control with
+a reason when you need the affordance to stay visible.
+
+An empty result during development is far more often permissions than a bug.
+An Action is hidden unless it is published, deployed, AND its invoke capability
+is held by the caller's role.
+
+## Submitting is not applying
+
+\`\`\`tsx
+submit.mutate({
+  objectId: ticket.ticketId,
+  input: { priority: 'Critical', escalated: true },
+  expectedVersion: recordVersionOf(instance.data),
+  reason: 'Customer escalated.',
+})
+
+const request = useActionRequest(submit.data?.id)   // polls until it settles
+\`\`\`
+
+\`mutate\` resolves when the Request is RECORDED. Dispatch happens on a
+background worker, and approval may sit with someone else for hours. A success
+toast fired on \`onSuccess\` is claiming something the app does not know.
+
+**Ask \`actionEffectOf\`, never the lifecycle.**
+
+\`\`\`tsx
+import { actionEffectOf } from '@frontera-sdk/blueprint/action-types'
+
+switch (actionEffectOf(request.data)) {
+  case 'applied':   return <Done />        // the write committed. Close the dialog.
+  case 'refused':   return <Refusal />
+  case 'uncertain': return <Checking />    // NOT failure — see below
+  case 'pending':   return <Spinner />
+}
+\`\`\`
+
+\`lifecycle\` says where the Request sits in the pipeline; \`effectCertainty\`
+says whether the change landed. They settle at different times, and the gap is
+not small. A Request reaches \`confirmed_applied\` the instant the write commits,
+then sits in \`finalizing\` while the platform verifies its own promise —
+re-reading the target, checking the properties the Action declared it would
+change. **That verification never undoes the write.** Its worst outcome still
+carries \`confirmed_applied\` and only means a human should look at why the proof
+was inconclusive. So blocking a dialog on \`succeeded\` leaves someone watching a
+spinner over a ticket that already exists.
+
+\`uncertain\` is the one that must not be collapsed into either neighbour. A
+dispatch was attempted and its outcome could not be established — the connection
+died mid-commit, and the write may well have landed. Rendering it as failure
+invites a duplicate; rendering it as success invites a lie. Say it is being
+checked and leave it: the platform reconciles it against the target and the
+answer arrives on its own.
+
+## Concurrency — and where the version actually comes from
+
+\`\`\`tsx
+import { recordVersionOf } from '@frontera-sdk/blueprint/action-types'
+
+const instance = useObjectInstance('SupportTicket', selectedId)
+const version = recordVersionOf(instance.data)
+\`\`\`
+
+**A list row does not carry the version.** It arrives as \`_meta.recordVersion\`
+from the INSTANCE route only, and only for an editable type. So a control that
+edits a row in a table fetches that row's instance first — selecting a row and
+submitting straight from \`useObjects\` data sends no version at all.
+
+That failure is silent: a missing version does not error, the compare-and-set
+is simply skipped, and two people overwrite each other with no refusal and no
+evidence. Use \`recordVersionOf\` rather than reaching into \`_meta\` yourself.
+
+A stale value IS refused, and that refusal is the feature — report it as
+"someone else changed this, reload" rather than retrying with a fresher version
+behind the user's back.
+
+Do not hand-build the invocation. One version travels as two fields of
+different types, and a wrong shape is refused without naming the field —
+\`useSubmitAction\` assembles it.
+
+## Idempotency
+
+A key is minted per \`mutate\` call. A retried network failure reuses it and
+cannot double-apply; a second click is a second intent and gets its own. Pass
+\`idempotencyKey\` yourself only when you have a stronger notion of "the same
+intended effect" than one click.
 `,
   }
 }
@@ -568,3 +724,26 @@ export function devHostHtml(name: string): string {
 </html>
 `
 }
+
+/**
+ * Default public-package scaffold: an ordinary Next.js project with a static
+ * artifact contract, a working reference feature, and the pattern skills that
+ * describe it.
+ *
+ * The file map and the skill set live in `templates/` rather than here: they
+ * are the parts that change with the product, while this module owns the
+ * vendoring rules the legacy Vite tree still depends on. Keeping them apart
+ * means a scaffold edit cannot accidentally move a vendored SDK path.
+ */
+function nextFiles(name: string): Record<string, string> {
+  return {
+    ...nextSkillFiles(),
+    ...nextAppFiles({
+      name,
+      // The platform stylesheet, vendored at CLI build time. It carries the
+      // token contract every shipped component and every skill refers to, so
+      // the scaffold must not hand-roll a second one.
+      themeCss: vendoredFiles()['src/theme.css'] ?? '@import "tailwindcss";\n',
+    }),
+  }
+}