howone 0.2.2 → 0.2.5

package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md

@@ -1,509 +1,194 @@
 # Manifest Codegen
 
-## Overview
+Generate `src/lib/sdk.ts` from the two synced manifests. Do not infer names, fields, access rules,
+schemas, or workflow IDs from a prompt, old source file, or dependency cache.
 
-HowOne apps are driven by two backend-synced manifests:
+## Source and evidence order
 
-| File | Contents | Drives |
-|---|---|---|
-| `.howone/database/manifest.json` | Entity names, fields, types | Entity type definitions + `client.entity<...>` bindings |
-| `.howone/ai/manifest.json` | AI action IDs, input/output JSON schemas | zod schemas + `defineAiAction` bindings |
+1. Read `.howone/database/manifest.json` and `.howone/ai/manifest.json` after the latest sync.
+2. Read `package.json` and installed SDK declarations as described by
+   `../../references/version-evidence.md`.
+3. Load only the operation recipe needed by the app.
+4. Generate bindings, run the project verifier, then typecheck/build.
 
-**The coding agent should always generate `src/lib/sdk.ts` from these manifest files, not from memory or assumptions.**
+If an AI workflow update may rotate `workflowId`, re-read the AI manifest immediately before writing
+the binding. Never preserve a stale UUID merely to avoid a diff.
 
-Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. The coding agent reads the manifests and writes `src/lib/sdk.ts`.
+## Database manifest mapping
 
-For AI capabilities, external workflow create/update is submitted by `external-ai-capability` from
-the synced manifest. Do not duplicate AI schemas in app code beyond generated zod/type bindings.
-For workflow edits, `external-ai-capability` may rotate the manifest `workflowId`; always re-read
-`.howone/ai/manifest.json` after the tool returns before updating `src/lib/sdk.ts`.
+For each entity, generate:
 
----
+- `Record` type extending `EntityRecord` with only declared business fields;
+- explicit `Create` type (never `Omit<Record, ...>`);
+- `Update = Partial<Create>` unless the product needs a narrower update contract;
+- a `defineEntityDefinition(...)` constant that preserves `properties`, `required`, and the entire
+  `access` block;
+- an authenticated binding wrapped with `withEntityContract`;
+- a public binding only when `access.public` exposes at least one operation, wrapped with
+  `withPublicEntityContract`.
 
-## Reading `.howone/database/manifest.json`
+### Type mapping
 
-### Example manifest
-
-```json
-{
-  "version": "1",
-  "entities": [
-    {
-      "name": "Story",
-      "fields": [
-        { "name": "title", "type": "string", "required": true },
-        { "name": "content", "type": "text", "required": true },
-        { "name": "authorId", "type": "string", "required": true },
-        { "name": "status", "type": "string", "required": true, "enum": ["draft", "published", "archived"] },
-        { "name": "wordCount", "type": "integer", "required": true },
-        { "name": "tags", "type": "array", "items": "string", "required": false },
-        { "name": "coverUrl", "type": "string", "required": false }
-      ]
-    },
-    {
-      "name": "Comment",
-      "fields": [
-        { "name": "storyId", "type": "string", "required": true },
-        { "name": "authorId", "type": "string", "required": true },
-        { "name": "body", "type": "text", "required": true },
-        { "name": "likes", "type": "integer", "required": false }
-      ]
-    }
-  ]
-}
-```
-
-### Field type → TypeScript type mapping
-
-| Manifest type | TypeScript type |
+| Manifest field type | TypeScript/Zod |
 |---|---|
-| `string` | `string` |
-| `text` | `string` |
-| `integer` | `number` |
-| `number` / `float` | `number` |
-| `boolean` | `boolean` |
-| `date` / `datetime` | `string` (ISO 8601) |
-| `array` (items: string) | `string[]` |
-| `array` (items: object) | `Record<string, unknown>[]` or inline type |
-| `object` | `Record<string, unknown>` |
-| `enum` | `'value1' \| 'value2' \| ...` |
-| `["string", "null"]` | `string \| null` |
-
-- Fields in `required: true` are non-optional in `Record` types.
-- In `Create` types, required fields are required only when they do not have `default` or `autoGenerate`.
-- Fields with `default`, `defaultValue`, or `autoGenerate` are optional in `Create`.
-- Nullable fields include `null`.
-- System response fields are never generated into `Create` or `Update`.
-
-### Access-aware generated helpers
-
-Use the manifest `access` block to decide which namespace UI code should call:
-
-```ts
-export type ArticlePublicQuery = {
-  published?: boolean
-  category?: string
-  slug?: string
-  page?: { number?: number; size?: number }
-  orderBy?: { publishedAt?: 'asc' | 'desc'; updatedDate?: 'asc' | 'desc' }
-}
-
-const publicArticles = await howone.public.entities.Article.query({
-  published: true,
-  orderBy: { publishedAt: 'desc' },
-})
-```
-
-Rules:
-
-- `access.authenticated.*` drives `howone.entities.*`.
-- `access.public.read = "list"` allows `howone.public.entities.Entity.query`.
-- `access.public.read = "scoped"` requires `queryScoped` / `query.scoped` and all `requiredScopes`.
-- Public query types must include only `allowedFilters`, `allowedSorts`, `page`, `limit`, `search`, `include`, and `exactCount`.
-- Public create/update types should only be emitted when `access.public.create/update` is not `"none"`.
-- Public create must include `created_by_user_id` when the schema requires public owner assignment.
-
-### Generated TypeScript from the example manifest
-
-```ts
-import { type EntityRecord } from '@howone/sdk'
-
-// ── Story ─────────────────────────────────────────────────────
-export type StoryRecord = EntityRecord & {
-  title: string
-  content: string
-  authorId: string
-  status: 'draft' | 'published' | 'archived'
-  wordCount: number
-  tags?: string[]
-  coverUrl?: string
-}
-
-export type StoryCreate = {
-  title: string
-  content: string
-  authorId: string
-  status: 'draft' | 'published' | 'archived'
-  wordCount: number
-  tags?: string[]
-  coverUrl?: string
-}
+| `string`, `text` | `string` / `z.string()` |
+| `integer`, `number`, `float` | `number` / `z.number()` (`.int()` for integer) |
+| `boolean` | `boolean` / `z.boolean()` |
+| `date`, `datetime` | ISO `string` / `z.string()` (add `.datetime()` only when the contract guarantees it) |
+| `array` | `T[]` / `z.array(...)` |
+| `object` | explicit object type / `z.object(...)` |
+| enum | literal union / `z.enum([...])` |
+| nullable union | `T \| null` / `z.nullable(...)` |
 
-export type StoryUpdate = Partial<StoryCreate>
+Fields with `default`, `defaultValue`, or `autoGenerate` can be optional in `Create` even when
+listed as required by the response schema. Never include system fields (`id`, timestamps, schema
+version) or ownership fields in Create/Update types.
 
-// ── Comment ───────────────────────────────────────────────────
-export type CommentRecord = EntityRecord & {
-  storyId: string
-  authorId: string
-  body: string
-  likes?: number
-}
+## AI manifest mapping
 
-export type CommentCreate = {
-  storyId: string
-  authorId: string
-  body: string
-  likes?: number
-}
+For each action:
 
-export type CommentUpdate = Partial<CommentCreate>
-```
+- preserve the manifest action `id` exactly (case-sensitive);
+- convert `inputSchema` and `outputSchema` to Zod;
+- preserve required arrays and closed enums;
+- include the exact UUID `workflowId` in `defineAiAction`;
+- never add `.passthrough()` to hide an envelope mismatch;
+- never make required output fields optional to make validation pass.
 
----
-
-## Reading `.howone/ai/manifest.json`
-
-### Example manifest
-
-```json
-{
-  "version": "1",
-  "actions": [
-    {
-      "id": "generateStory",
-      "name": "Generate Story",
-      "workflowId": "d69ab648-2c00-4d94-928e-01bd7b2a5bb2",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "topic": { "type": "string" },
-          "ageRange": { "type": "string", "enum": ["3-5", "6-8", "9-12"] },
-          "language": { "type": "string" }
-        },
-        "required": ["topic", "ageRange"]
-      },
-      "outputSchema": {
-        "type": "object",
-        "properties": {
-          "title": { "type": "string" },
-          "content": { "type": "string" },
-          "summary": { "type": "string" }
-        },
-        "required": ["title", "content"]
-      }
-    },
-    {
-      "id": "translateText",
-      "name": "Translate Text",
-      "workflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "text": { "type": "string" },
-          "targetLang": { "type": "string" },
-          "formality": { "type": "string", "enum": ["formal", "informal"] }
-        },
-        "required": ["text", "targetLang"]
-      }
-    }
-  ]
-}
-```
-
-### JSON Schema → zod mapping
+`defineAiAction` validates workflow IDs during module initialization. Missing or invalid values are
+configuration failures, not a runtime fallback case.
 
-| JSON Schema | zod |
-|---|---|
-| `{ "type": "string" }` | `z.string()` |
-| `{ "type": "number" }` | `z.number()` |
-| `{ "type": "integer" }` | `z.number().int()` |
-| `{ "type": "boolean" }` | `z.boolean()` |
-| `{ "type": "string", "enum": ["a","b"] }` | `z.enum(['a', 'b'])` |
-| `{ "type": "array", "items": { "type": "string" } }` | `z.array(z.string())` |
-| `{ "type": "object", "properties": { ... } }` | `z.object({ ... })` |
-| Field NOT in `required[]` | append `.optional()` |
+## Generated shape
 
-### Generated zod schemas from the example manifest
-
-```ts
-import { z } from 'zod'
-
-// ── generateStory ─────────────────────────────────────────────
-export const generateStoryInputSchema = z.object({
-  topic: z.string(),
-  ageRange: z.enum(['3-5', '6-8', '9-12']),
-  language: z.string().optional(),
-})
-export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
-
-export const generateStoryOutputSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  summary: z.string().optional(),
-})
-export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
-
-// ── translateText ─────────────────────────────────────────────
-export const translateTextInputSchema = z.object({
-  text: z.string(),
-  targetLang: z.string(),
-  formality: z.enum(['formal', 'informal']).optional(),
-})
-export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
-```
-
-Do not make required output fields optional to silence validation failures. Do not add
-`.passthrough()` as a workaround for EAX execution envelopes. `defineAiAction` validates the
-workflow `finalResult` payload when an `outputSchema` is configured.
-
----
-
-## Full Generated `src/lib/sdk.ts`
-
-Combining both manifests from the examples above:
+This is the architecture pattern; replace every placeholder with manifest-derived code:
 
 ```ts
 // src/lib/sdk.ts
-// Generated from .howone/database/manifest.json and .howone/ai/manifest.json
 import {
   createClient,
   defineAiAction,
   defineAiActions,
+  defineEntityDefinition,
   defineEntities,
-  runAiActionAndPersist,
+  definePublicEntities,
   type EntityDefinition,
   type EntityRecord,
   withAiActions,
   withEntities,
+  withEntityContract,
+  withPublicEntities,
+  withPublicEntityContract,
 } from '@howone/sdk'
 import { z } from 'zod'
 
-// ═══════════════════════════════════════════════════════════════
-// ENTITY TYPES
-// ═══════════════════════════════════════════════════════════════
-
-export type StoryRecord = EntityRecord & {
-  title: string
-  content: string
-  authorId: string
-  status: 'draft' | 'published' | 'archived'
-  wordCount: number
-  tags?: string[]
-  coverUrl?: string
-}
-export type StoryCreate = {
+export type ArticleRecord = EntityRecord & {
   title: string
-  content: string
-  authorId: string
-  status: 'draft' | 'published' | 'archived'
-  wordCount: number
-  tags?: string[]
-  coverUrl?: string
+  status: 'draft' | 'published'
 }
-export type StoryUpdate = Partial<StoryCreate>
+export type ArticleCreate = { title: string; status: 'draft' | 'published' }
+export type ArticleUpdate = Partial<ArticleCreate>
 
-export type CommentRecord = EntityRecord & {
-  storyId: string
-  authorId: string
-  body: string
-  likes?: number
-}
-export type CommentCreate = {
-  storyId: string
-  authorId: string
-  body: string
-  likes?: number
-}
-export type CommentUpdate = Partial<CommentCreate>
-
-export const storyEntityDefinition = {
-  name: 'Story',
+export const articleEntityDefinition = defineEntityDefinition({
+  name: 'Article',
   type: 'object',
   properties: {
     title: { type: 'string' },
-    content: { type: 'string' },
-    authorId: { type: 'string' },
-    status: { type: 'string', enum: ['draft', 'published', 'archived'] },
-    wordCount: { type: 'integer' },
-    tags: { type: 'array', items: { type: 'string' } },
-    coverUrl: { type: 'string' },
-  },
-  required: ['title', 'content', 'authorId', 'status', 'wordCount'],
-  access: {
-    authenticated: { read: 'own', create: 'own', update: 'own', delete: 'own' },
-    public: { read: 'none', create: 'none', update: 'none', delete: 'none' },
-  },
-} satisfies EntityDefinition
-
-export const commentEntityDefinition = {
-  name: 'Comment',
-  type: 'object',
-  properties: {
-    storyId: { type: 'string' },
-    authorId: { type: 'string' },
-    body: { type: 'string' },
-    likes: { type: 'integer' },
+    status: { type: 'string', enum: ['draft', 'published'] },
   },
-  required: ['storyId', 'authorId', 'body'],
+  required: ['title', 'status'],
   access: {
-    authenticated: { read: 'own', create: 'own', update: 'own', delete: 'own' },
-    public: { read: 'none', create: 'none', update: 'none', delete: 'none' },
+    authenticated: { read: 'all', create: 'all', update: 'all', delete: 'all' },
+    public: {
+      read: 'list',
+      create: 'none',
+      update: 'none',
+      allowedFilters: ['status'],
+      allowedSorts: ['createdDate'],
+    },
   },
-} satisfies EntityDefinition
-
-// ═══════════════════════════════════════════════════════════════
-// AI SCHEMAS & TYPES
-// ═══════════════════════════════════════════════════════════════
-
-export const generateStoryInputSchema = z.object({
-  topic: z.string(),
-  ageRange: z.enum(['3-5', '6-8', '9-12']),
-  language: z.string().optional(),
-})
-export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
-export const generateStoryOutputSchema = z.object({
-  title: z.string(),
-  content: z.string(),
-  summary: z.string().optional(),
-})
-export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
-
-export const translateTextInputSchema = z.object({
-  text: z.string(),
-  targetLang: z.string(),
-  formality: z.enum(['formal', 'informal']).optional(),
-})
-export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
-
-// ═══════════════════════════════════════════════════════════════
-// CLIENT
-// ═══════════════════════════════════════════════════════════════
+} satisfies EntityDefinition)
 
 const client = createClient({
   projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
   env: import.meta.env.VITE_HOWONE_ENV,
 })
 
-// ═══════════════════════════════════════════════════════════════
-// ENTITY BINDINGS
-// ═══════════════════════════════════════════════════════════════
-
 export const entities = defineEntities({
-  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
-  Comment: client.entity<CommentRecord, CommentCreate, CommentUpdate>('Comment'),
+  Article: withEntityContract(
+    client.entity<ArticleRecord, ArticleCreate, ArticleUpdate>('Article'),
+    articleEntityDefinition,
+  ),
 })
 
-// ═══════════════════════════════════════════════════════════════
-// AI ACTION BINDINGS
-// ═══════════════════════════════════════════════════════════════
+// Include only manifest-approved public entities/capabilities.
+export const publicEntities = definePublicEntities({
+  Article: withPublicEntityContract(
+    client.public.entity<ArticleRecord, ArticleCreate, ArticleUpdate>('Article'),
+    articleEntityDefinition,
+  ),
+})
+
+const summarizeInputSchema = z.object({ text: z.string() })
+const summarizeOutputSchema = z.object({ summary: z.string() })
+export type SummarizeInput = z.infer<typeof summarizeInputSchema>
+export type SummarizeOutput = z.infer<typeof summarizeOutputSchema>
 
 export const ai = defineAiActions({
-  generateStory: defineAiAction('generateStory', {
+  summarize: defineAiAction('summarize', {
     workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
-    inputSchema: generateStoryInputSchema,
-    outputSchema: generateStoryOutputSchema,
-  }),
-  translateText: defineAiAction('translateText', {
-    workflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
-    inputSchema: translateTextInputSchema,
+    inputSchema: summarizeInputSchema,
+    outputSchema: summarizeOutputSchema,
   }),
 })
 
-// ═══════════════════════════════════════════════════════════════
-// COMPOSED CLIENT
-// ═══════════════════════════════════════════════════════════════
-
-const howone = withAiActions(withEntities(client, entities), ai)
+const howoneWithEntities = withEntities(client, entities)
+const howoneWithPublicEntities = withPublicEntities(howoneWithEntities, publicEntities)
+const howone = withAiActions(howoneWithPublicEntities, ai)
 export default howone
 ```
 
----
-
-## Codegen Checklist
-
-Before finalising generated code, verify:
+If the manifest has no public capability, omit `publicEntities` and `withPublicEntities`. If an
+entity has `access.authenticated.create: 'none'`, the authenticated wrapper has no `create` or
+`bulkCreate` property at both runtime and type level. Do not cast it back.
 
-- [ ] Every entity from `.howone/database/manifest.json` has a `Record`, `Create`, and `Update` type
-- [ ] Entity definitions are exported as `*EntityDefinition` when app code needs payload/query guards
-- [ ] `Create` types are defined **explicitly** (not via `Omit`)
-- [ ] Create optionality accounts for `required`, `default`, `defaultValue`, `autoGenerate`, and nullable types
-- [ ] System fields are not present in create/update input types
-- [ ] Public query/write types are generated only from `access.public.allowedFilters`, `allowedSorts`, `requiredScopes`, and write permissions
-- [ ] Every AI action from `.howone/ai/manifest.json` has an `inputSchema` zod object
-- [ ] Every AI action with manifest `outputSchema` has a matching zod `outputSchema`
-- [ ] Every AI action binding includes the exact manifest `workflowId`
-- [ ] Required input fields are not `.optional()` in zod
-- [ ] Required output fields are not `.optional()` in zod
-- [ ] AI output schemas do not use `.passthrough()` to hide execution-envelope mismatches
-- [ ] AI action names match the manifest `id` exactly (case-sensitive)
-- [ ] `createClient` uses `import.meta.env.*` only
-- [ ] `withEntities` is applied before `withAiActions` in the composition chain
-- [ ] No generated source files are placed under `.howone/`
-- [ ] Exported types and schemas are importable from `@/lib/sdk`
+## Query and access generation
 
----
-
-## Incremental Update Pattern
-
-When new entities or actions are added to the manifests, update `src/lib/sdk.ts` by:
-
-1. Reading the current `src/lib/sdk.ts` to preserve existing bindings and import style.
-2. Appending new types, schemas, entity bindings, and action bindings.
-3. Not removing existing bindings unless the manifest explicitly removed them.
-4. Preserving export names for backward compatibility with existing UI code.
+Authenticated code uses `howone.entities.Entity`; public code uses `howone.public.entities.Entity`.
+Generate `QueryOptions` with `where`, `page`, `orderBy`, `include`, and `exactCount` only. Public
+filters and sorts must be limited to manifest `allowedFilters`/`allowedSorts`; scoped reads must
+provide every `requiredScopes` field under `where`.
 
 ```ts
-// Before (existing)
-export const entities = defineEntities({
-  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
-})
-
-// After (added Comment entity from new manifest)
-export const entities = defineEntities({
-  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
-  Comment: client.entity<CommentRecord, CommentCreate, CommentUpdate>('Comment'),
+await howone.public.entities.Article.query({
+  where: { status: 'published' },
+  orderBy: { createdDate: 'desc' },
+  page: { number: 1, size: 20 },
 })
 ```
 
----
+Never put `created_by_id`, `ownerId`, `puid`, or system fields into authenticated or public payloads.
+Ownership comes from auth or the public scope contract.
 
-## AI-First Persistence Pattern
+## Incremental changes
 
-When the app generates data with AI and saves it to an entity:
+When a manifest changes:
 
-1. Read `.howone/ai/manifest.json` to know the typed AI output.
-2. Decide which output fields are durable product fields.
-3. Add app-specific persistence fields such as `status`, `errorMessage`, `requestedAt`,
-   `completedAt`, source URLs, prompt/options, or share state.
-4. Define/update the entity schema from product persistence needs, not by blindly copying
-   `outputSchema`.
-5. Generate entity types and AI action bindings from synced manifests.
-6. Use `runAiActionAndPersist()` for history-style products.
+1. re-read the complete current manifest;
+2. preserve app exports that are still present;
+3. add/remove bindings to match the manifest exactly;
+4. regenerate affected Zod and entity definitions;
+5. run the verifier and typecheck.
 
-```ts
-// AI generates: { title: string, content: string, summary: string }
-// Save it to Story entity which adds: authorId, status, wordCount
-
-async function generateAndSave(input: GenerateStoryInput, authorId: string) {
-  const output = await howone.ai.generateStory.run(input)
-
-  return howone.entities.Story.create({
-    title: output.title,
-    content: output.content,
-    authorId,
-    status: 'draft',
-    wordCount: output.content.split(' ').length,
-  })
-}
-```
+Do not hand-edit `.howone/*` metadata. Do not place generated source files under `.howone/`.
 
-History-style generation should create a pending record before running AI:
+## Codegen checklist
 
-```ts
-await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input,
-  createPending: (input) => ({
-    prompt: input.topic,
-    status: 'pending',
-    requestedAt: new Date().toISOString(),
-  }),
-  run: (input) => howone.ai.generateStory.run(input),
-  mapCompleted: ({ output }) => ({
-    status: 'completed',
-    title: output.title,
-    content: output.content,
-    completedAt: new Date().toISOString(),
-  }),
-})
-```
+- [ ] Every current entity has Record/Create/Update types and a definition constant.
+- [ ] System/ownership fields are absent from write types.
+- [ ] Access wrappers match authenticated/public operations.
+- [ ] Public bindings include only manifest-approved entities.
+- [ ] Query fields are typed from the generated Record, not `Record<string, unknown>`.
+- [ ] Every AI action has a real Zod input schema and exact manifest UUID.
+- [ ] Output requiredness and enums match the manifest.
+- [ ] Provider consumes the composed `howone` client.
+- [ ] `node .howone/skills/howone/scripts/verify-project.mjs` passes.