howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/howone/02-database/04-query-dsl-and-responses.md

@@ -0,0 +1,237 @@
+# Query DSL And Responses
+
+Use this reference when implementing list/detail pages, filters, sorting, pagination, or response
+normalization for HowOne dynamic entities.
+
+## SDK Query Shape
+
+```ts
+await howone.entities.Todo.query({
+  where: {
+    completed: false,
+    priority: { in: ['medium', 'high'] },
+    updatedDate: { gte: '2026-01-01T00:00:00.000Z' },
+  },
+  search: 'invoice',
+  page: { number: 1, size: 20 },
+  orderBy: { updatedDate: 'desc' },
+  include: ['owner'],
+  exactCount: true,
+})
+```
+
+Private owner-scoped list:
+
+```ts
+await howone.entities.Todo.query.mine({
+  page: { number: 1, size: 50 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+Public list:
+
+```ts
+await howone.public.entities.Article.query({
+  where: { status: 'published' },
+  orderBy: { publishedAt: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Public scoped:
+
+```ts
+await howone.public.entities.QrProfile.queryScoped({
+  where: { ownerId, slug, active: true },
+  page: { number: 1, size: 1 },
+})
+```
+
+## Operators
+
+Supported field operators:
+
+```ts
+type FieldOperator<T> = {
+  eq?: T
+  equals?: T
+  ne?: T
+  not?: T
+  gt?: T
+  gte?: T
+  lt?: T
+  lte?: T
+  contains?: string
+  like?: string
+  startsWith?: string
+  starts?: string
+  endsWith?: string
+  ends?: string
+  in?: T[]
+  notIn?: T[]
+  null?: boolean
+  empty?: boolean
+  exists?: boolean
+}
+```
+
+Examples:
+
+```ts
+where: { status: 'published' }
+where: { status: { eq: 'published' } }
+where: { score: { gte: 80, lt: 100 } }
+where: { category: { in: ['news', 'guide'] } }
+where: { title: { contains: 'AI' } }
+where: { deletedAt: { null: true } }
+```
+
+## Pagination
+
+Use SDK page object:
+
+```ts
+page: { number: 1, size: 20 }
+```
+
+Response:
+
+```ts
+type QueryResult<T> = {
+  items: T[]
+  page: {
+    number: number
+    size: number
+    total: number
+    totalPages: number
+    hasNext: boolean
+    hasPrev: boolean
+  }
+  traceId?: string | number
+  raw?: unknown
+}
+```
+
+Always render from a normalized array:
+
+```ts
+const result = await howone.entities.Todo.query.mine(...)
+const items = Array.isArray(result.items) ? result.items : []
+```
+
+## Sorting
+
+SDK uses:
+
+```ts
+orderBy: { updatedDate: 'desc' }
+```
+
+Rules:
+
+- Public sort fields must be in `access.public.allowedSorts`.
+- Private sort fields should be in `performance.allowedSorts` and covered by indexes.
+- Prefer `updatedDate` for recently changed lists and `createdDate` for creation history.
+- Do not expose arbitrary public sort fields.
+
+## Include / Relations
+
+Use `include` only for relation names declared in schema `relations`.
+
+```ts
+await howone.entities.Article.query({
+  include: ['author'],
+})
+```
+
+Rules:
+
+- Do not invent include names.
+- Public includes must be safe for anonymous exposure.
+- If a list needs a small display field frequently, consider denormalizing it instead of requiring include on every row.
+
+## Detail Reads
+
+Authenticated:
+
+```ts
+const item = await howone.entities.Todo.get(id)
+const item = await howone.entities.Todo.getOrThrow(id)
+```
+
+Public:
+
+```ts
+const item = await howone.public.entities.Article.get(id)
+```
+
+For public scoped detail, prefer `queryScoped` when the route naturally has scope fields like
+`ownerId + slug`.
+
+## Response Field Names
+
+SDK defaults to `caseStyle: 'camel'`, so responses are normalized toward camelCase where supported.
+Still know the backend system field meanings:
+
+| Backend concept | Common SDK field |
+|---|---|
+| record id | `id` |
+| created date | `createdDate` or `created_date` depending case style |
+| updated date | `updatedDate` or `updated_date` |
+| owner | `createdById` or `created_by_id` |
+| schema version id | `schemaVersionId` or `schema_version_id` |
+| schema version number | `schemaVersionNumber` or `schema_version_number` |
+
+Do not use `_id` in app code unless inspecting raw backend payloads.
+
+## Public Guardrails
+
+Before writing public query code, check schema:
+
+```json
+"public": {
+  "read": "list",
+  "allowedFilters": ["status", "slug"],
+  "allowedSorts": ["publishedAt"],
+  "defaultLimit": 20,
+  "maxLimit": 100
+}
+```
+
+Then only use allowed filters and sorts:
+
+```ts
+// OK
+where: { status: 'published' }
+orderBy: { publishedAt: 'desc' }
+
+// Not OK unless listed in access.public
+where: { internalReviewState: 'approved' }
+orderBy: { revenue: 'desc' }
+```
+
+## Search
+
+Use `search` for broad text search only when the backend/schema supports the desired behavior:
+
+```ts
+await howone.public.entities.Article.query({
+  search: query,
+  where: { status: 'published' },
+})
+```
+
+Do not use `search` as a substitute for required public scopes.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Rendering `res.data.data` from SDK query | SDK returns `QueryResult.items`; render `result.items`. |
+| Using `_id` as record id | Use `id`. |
+| Public query with unlisted filter | Add to `allowedFilters` or remove it. |
+| Public query with unlisted sort | Add to `allowedSorts` or change sorting. |
+| Passing owner filters in authenticated `own` queries | Use `query.mine()` and omit owner fields. |
+| Using include without schema relation | Add relation first or remove include. |
+| No pagination on list pages | Always pass `page` and respect `maxLimit`. |

package/templates/vite/.howone/skills/howone/02-database/05-ai-persistence-patterns.md

@@ -0,0 +1,372 @@
+# AI Persistence Patterns
+
+Use this reference when an AI workflow output must become durable product data: generation history,
+saved results, analysis reports, retryable jobs, share pages, or user libraries.
+
+AI workflow contracts describe **how to produce an output**. Entity schemas describe **what the app
+persists, lists, edits, shares, and reloads**. Do not merge those two responsibilities.
+
+## Core Rule
+
+```text
+AI capability outputSchema != database entity schema
+```
+
+The output schema is the workflow return contract. It can contain transient execution details,
+intermediate data, model metadata, or provider-shaped structures. The database schema is a product
+contract. It should store only fields that the app needs after refresh, across sessions, or on public
+pages.
+
+For every AI feature, ask:
+
+| Question | Persist? | Where |
+|---|---:|---|
+| Must the user see this after refresh? | yes | Entity field |
+| Must it appear in history/library/search? | yes | Entity field + index if queried |
+| Is it only needed while streaming/running? | no | Local UI state / runtime event |
+| Is it provider debug data? | usually no | Logs, not entity data |
+| Is it needed to retry or resume? | yes | Entity field |
+| Is it sensitive model/provider metadata? | usually no | Avoid public entity fields |
+
+## Recommended Flow
+
+For long-running or user-visible AI operations, create a pending record before calling the workflow.
+
+```ts
+import { runAiActionAndPersist } from '@howone/sdk'
+
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input: { prompt },
+  createPending: (input) => ({
+    prompt: input.prompt,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateImage.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    resultUrl: output.imageUrl,
+    completedAt: new Date().toISOString(),
+  }),
+  mapFailed: ({ error }) => ({
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  }),
+})
+```
+
+Why pending-first:
+
+- refresh can show an in-progress item instead of losing the request;
+- failure can be displayed in history;
+- retry can reuse the original prompt/options;
+- support/debug can identify which input produced the failed state;
+- UI can render from persisted data instead of assuming local state survived.
+
+For very fast, disposable AI actions, persistence may be unnecessary. Do not create an entity just
+because an AI workflow exists.
+
+## Status Fields
+
+Every persisted AI job/history entity should have a status field.
+
+Recommended:
+
+```json
+{
+  "status": {
+    "type": "string",
+    "description": "pending | running | completed | failed | canceled",
+    "default": "pending"
+  }
+}
+```
+
+Use stable string values:
+
+| Status | Meaning |
+|---|---|
+| `pending` | Record exists, workflow has not produced final output. |
+| `running` | Optional if the app receives a running state after submission. |
+| `completed` | Output fields are valid for display. |
+| `failed` | `errorMessage` or failure fields explain the failure. |
+| `canceled` | User/system canceled and no final output should be expected. |
+
+Rules:
+
+- Do not infer completion only from `resultUrl` or another output field.
+- Keep failed records when the product has history or retry UX.
+- If the UI shows a spinner from persisted data, it must also handle stale `pending/running` records.
+
+## Minimal Generation History Schema
+
+Use for image/text/report/music/video generation history.
+
+```json
+{
+  "name": "Generation",
+  "type": "object",
+  "visibility": "private",
+  "properties": {
+    "prompt": { "type": "string" },
+    "status": { "type": "string", "default": "pending" },
+    "resultUrl": { "type": ["string", "null"], "default": null },
+    "resultText": { "type": ["string", "null"], "default": null },
+    "errorMessage": { "type": ["string", "null"], "default": null },
+    "requestedAt": { "type": "date" },
+    "completedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["prompt", "status", "requestedAt"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  },
+  "indexes": [
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
+    { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" }
+  ],
+  "performance": {
+    "defaultLimit": 20,
+    "maxLimit": 100,
+    "allowedSorts": ["updatedDate", "requestedAt"]
+  },
+  "presentation": {
+    "titleField": "prompt",
+    "subtitleField": "status"
+  }
+}
+```
+
+Use separate result fields instead of one opaque `result` object when the UI lists or filters them.
+Use an object field only for genuinely nested, product-level structured results.
+
+## Analysis Report Schema
+
+Use when AI returns a structured report that users browse later.
+
+```json
+{
+  "name": "AnalysisReport",
+  "type": "object",
+  "visibility": "private",
+  "properties": {
+    "sourceTitle": { "type": "string" },
+    "sourceUrl": { "type": ["string", "null"], "default": null },
+    "status": { "type": "string", "default": "pending" },
+    "summary": { "type": ["string", "null"], "default": null },
+    "insights": { "type": "array", "default": [] },
+    "score": { "type": ["number", "null"], "default": null },
+    "errorMessage": { "type": ["string", "null"], "default": null },
+    "requestedAt": { "type": "date" },
+    "completedAt": { "type": ["date", "null"], "default": null }
+  },
+  "required": ["sourceTitle", "status", "requestedAt"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  }
+}
+```
+
+Mapping rule:
+
+```ts
+const output = await howone.ai.analyzeDocument.run(input)
+
+await howone.entities.AnalysisReport.update(report.id, {
+  status: 'completed',
+  summary: output.summary,
+  insights: output.insights,
+  score: output.score,
+  completedAt: new Date().toISOString(),
+})
+```
+
+Do not save the whole workflow envelope unless the entity has an explicitly designed field for that
+envelope and the product needs it.
+
+## Public AI Result Share Page
+
+Use when a user can share one generated result publicly.
+
+Recommended split:
+
+- private `Generation` entity for user history and edits;
+- public or scoped `SharedGeneration` entity for anonymous viewing.
+
+Why split:
+
+- private history may include prompts, failures, drafts, and internal metadata;
+- public page should expose only curated fields;
+- public access rules stay simple and auditable;
+- unsharing can delete or deactivate the shared record without destroying private history.
+
+Public scoped schema:
+
+```json
+{
+  "name": "SharedGeneration",
+  "type": "object",
+  "visibility": "public",
+  "properties": {
+    "shareId": {
+      "type": "string",
+      "autoGenerate": { "strategy": "uuid" }
+    },
+    "title": { "type": "string" },
+    "resultUrl": { "type": "string" },
+    "active": { "type": "boolean", "default": true },
+    "sourceGenerationId": { "type": "string" }
+  },
+  "required": ["shareId", "title", "resultUrl", "active", "sourceGenerationId"],
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": {
+      "read": "scoped",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["shareId"],
+      "allowedFilters": ["shareId", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  },
+  "indexes": [
+    { "name": "share_id_unique", "fields": ["shareId"], "unique": true },
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" }
+  ]
+}
+```
+
+Public page:
+
+```ts
+const result = await howone.public.entities.SharedGeneration.queryScoped({
+  where: { shareId, active: true },
+  page: { number: 1, size: 1 },
+})
+
+const shared = result.items[0] ?? null
+```
+
+Rules:
+
+- Do not expose private prompt fields unless the product explicitly wants that.
+- Use `active` or a deletion flow for unshare.
+- Keep public `maxLimit` at `1` for one-share pages.
+
+## Retry Design
+
+If the product has retry, store enough input fields to rebuild the workflow request.
+
+Persist:
+
+- user prompt or source content reference;
+- selected mode/model/style options that affect output;
+- uploaded file IDs/URLs needed by the workflow;
+- status and failure message;
+- timestamps.
+
+Do not persist:
+
+- temporary UI component state;
+- auth/session/token values;
+- raw streaming chunks;
+- provider secrets;
+- hidden prompt text that should stay server-side;
+- large binary content when file upload should store a URL or file id.
+
+Retry example:
+
+```ts
+const old = await howone.entities.Generation.getOrThrow(id)
+
+const retry = await howone.entities.Generation.create({
+  prompt: old.prompt,
+  status: 'pending',
+  requestedAt: new Date().toISOString(),
+})
+
+const output = await howone.ai.generateImage.run({
+  prompt: old.prompt,
+})
+
+await howone.entities.Generation.update(retry.id, {
+  status: 'completed',
+  resultUrl: output.imageUrl,
+  completedAt: new Date().toISOString(),
+})
+```
+
+Prefer creating a new retry record when the product is history-oriented. Prefer updating the same
+record only when the product treats retry as replacing the original attempt.
+
+## Resume Design
+
+On page load, query persisted records instead of relying on local state:
+
+```ts
+const history = await howone.entities.Generation.query.mine({
+  where: { status: { in: ['pending', 'running', 'completed', 'failed'] } },
+  orderBy: { updatedDate: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Then:
+
+- render `completed` from output fields;
+- render `failed` from `errorMessage`;
+- render `pending/running` as in progress only if the app has a way to poll status;
+- mark stale pending records as failed/canceled when product rules define a timeout.
+
+Do not leave indefinite pending rows with no recovery path.
+
+## Field Mapping Checklist
+
+Before implementing persistence, write the mapping explicitly:
+
+```text
+workflow input.prompt       -> Generation.prompt
+workflow input.style        -> Generation.style
+workflow output.imageUrl    -> Generation.resultUrl
+workflow output.caption     -> Generation.resultText
+workflow error.message      -> Generation.errorMessage
+runtime request started     -> Generation.requestedAt
+runtime request completed   -> Generation.completedAt
+```
+
+If a workflow output field has no mapping, decide whether it is intentionally transient or whether
+the entity schema is missing a product field.
+
+## Access Checklist
+
+Choose access based on product behavior:
+
+| Product behavior | Entity access |
+|---|---|
+| User-only private generation history | authenticated own, public none |
+| Team/shared authenticated library | authenticated all or future role-scoped model |
+| Anonymous public gallery | public list with safe fields only |
+| One public share link | public scoped with share id |
+| Public submission to AI queue | public create only if abuse constraints are handled |
+
+Never make the main generation history public just to support a public share page. Create a scoped
+share entity or a curated public entity.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Treating `outputSchema` as the entity schema | Design product persistence separately. |
+| Saving raw workflow envelopes | Map only fields the product needs after refresh. |
+| No status field | Add `status` and explicit failure fields. |
+| Creating history only after success | Create pending first when history/resume matters. |
+| Losing failures | Persist `failed` state and `errorMessage`. |
+| Publicly exposing private prompt/history | Use a separate public scoped/share entity. |
+| Retrying without stored inputs | Persist the inputs/options needed for retry. |
+| Rendering from local state only | Reload from entity queries on page load. |
+| Leaving stale pending forever | Add timeout/recovery behavior in product logic. |