howone 0.1.23 → 0.1.26

package/templates/vite/.howone/skills/howone/02-database/02-schema-operations.md

@@ -0,0 +1,398 @@
+# Schema Operations
+
+Use this reference when applying backend entity schema changes through HowOne runtime tools or
+`client.schema.*`. It answers: **how do I safely change the schema and keep app code in sync?**
+
+For schema design decisions, read `01-schema-design.md` first.
+
+## Source Of Truth
+
+```text
+agent proposal                 = draft
+backend preview/apply result   = validated contract
+synced .howone/database files  = local copy of backend version
+src/lib/sdk.ts                 = generated app binding from synced manifest
+frontend code                  = consumer of generated bindings
+```
+
+Do not hand-write `.howone/database/*`. Sync artifacts from a concrete backend version.
+
+## Preferred Patch Flow
+
+Use patch flow for most feature-level changes:
+
+1. Inspect current `schema.getState()` and current entity definitions.
+2. Design a full patch containing all related operations.
+3. Preview the patch.
+4. Review risk, diff, and current version.
+5. Apply the exact same patch with `expectedVersionId`.
+6. Sync schema artifacts from `next.versionId`.
+7. Read `.howone/database/manifest.json`.
+8. Regenerate/update `src/lib/sdk.ts` bindings.
+9. Update frontend calls according to `access`.
+10. Run typecheck/build/tests.
+
+Do not preview one patch and apply a different operation set.
+
+## SDK Schema Client
+
+```ts
+const state = await client.schema.getState()
+const definitions = await client.schema.listDefinitions()
+const todo = await client.schema.getDefinition('Todo')
+
+const preview = await client.schema.previewPatch(patch, {
+  expectedVersionId: state.currentVersionId,
+  reason: 'Add priority field to Todo',
+})
+
+if (preview.risk?.level === 'dangerous') {
+  // stop and ask for confirmation
+}
+
+const applied = await client.schema.applyPatch(patch, {
+  expectedVersionId: state.currentVersionId,
+  reason: 'Add priority field to Todo',
+})
+```
+
+Available schema methods:
+
+| Method | Use |
+|---|---|
+| `listDefinitions()` | Get current entity definitions. |
+| `getDefinition(entityName)` | Inspect one entity. |
+| `upsertDefinitions(definition | definition[])` | Direct definition upsert; prefer patch for agent changes. |
+| `operate(operation)` | Single operation endpoint. |
+| `previewPatch(patch, options)` | Risk/diff preview without applying. |
+| `applyPatch(patch, options)` | Apply versioned patch. |
+| `getState()` | Current schema version pointer. |
+| `listVersions()` | Version history. |
+| `getVersion(versionId)` | Inspect version manifest. |
+| `restore(versionId, reason?)` | Restore definitions by creating a new restore version. |
+
+## Operation Types
+
+```ts
+type EntitySchemaOperationType =
+  | 'list_entities'
+  | 'get_entity'
+  | 'create_entity'
+  | 'update_entity'
+  | 'delete_entity'
+  | 'add_field'
+  | 'update_field'
+  | 'delete_field'
+  | 'set_field_required'
+  | 'unset_field_required'
+```
+
+Operation shape:
+
+```ts
+type EntitySchemaOperation = {
+  type: EntitySchemaOperationType
+  entityName?: string
+  payload?: Record<string, unknown>
+}
+```
+
+Patch shape:
+
+```ts
+type EntitySchemaPatch = {
+  operations: EntitySchemaOperation[]
+}
+```
+
+## Operation Payloads
+
+### create_entity
+
+Use when the entity does not exist.
+
+```json
+{
+  "type": "create_entity",
+  "entityName": "Todo",
+  "payload": {
+    "definition": {
+      "name": "Todo",
+      "type": "object",
+      "visibility": "private",
+      "properties": {
+        "text": { "type": "string" },
+        "completed": { "type": "boolean", "default": false }
+      },
+      "required": ["text"],
+      "access": {
+        "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+        "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- `payload.definition.properties` is required.
+- `required` must reference existing fields.
+- Include explicit `access`, even if `visibility` seems obvious.
+
+### update_entity
+
+Use for metadata and contract sections, not individual field changes.
+
+```json
+{
+  "type": "update_entity",
+  "entityName": "Article",
+  "payload": {
+    "patch": {
+      "access": {
+        "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+        "public": {
+          "read": "list",
+          "create": "none",
+          "update": "none",
+          "delete": "none",
+          "allowedFilters": ["status", "slug"],
+          "allowedSorts": ["publishedAt"],
+          "defaultLimit": 20,
+          "maxLimit": 100
+        }
+      },
+      "performance": {
+        "defaultLimit": 20,
+        "maxLimit": 100,
+        "allowedSorts": ["publishedAt", "updatedDate"]
+      }
+    }
+  }
+}
+```
+
+Use this for:
+
+- `description`
+- `visibility`
+- `access`
+- `indexes`
+- `relations`
+- `presentation`
+- `lifecycle`
+- `performance`
+
+### add_field
+
+```json
+{
+  "type": "add_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "priority",
+    "field": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "default": "medium"
+    },
+    "required": false
+  }
+}
+```
+
+Rules:
+
+- If adding a required field to an existing entity, prefer a default.
+- If no default exists and records already exist, treat as risky and ask for migration policy.
+- Add indexes only when new query paths need them.
+
+### update_field
+
+```json
+{
+  "type": "update_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "priority",
+    "patch": {
+      "enum": ["low", "medium", "high", "urgent"]
+    }
+  }
+}
+```
+
+Risk levels:
+
+- Adding enum values: usually safe.
+- Removing enum values: risky if existing records use them.
+- Changing type: high risk.
+- Making nullable field required: high risk.
+- Removing default: risky for create flows.
+
+### delete_field
+
+```json
+{
+  "type": "delete_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "legacyTag",
+    "removeFromData": false
+  }
+}
+```
+
+Rules:
+
+- Default `removeFromData` to `false`.
+- Only use `removeFromData: true` after explicit confirmation.
+- Removing from schema does not necessarily remove historical data.
+
+### set_field_required / unset_field_required
+
+```json
+{
+  "type": "set_field_required",
+  "entityName": "Todo",
+  "payload": { "fieldName": "text" }
+}
+```
+
+Rules:
+
+- Required fields must exist in `properties`.
+- Setting required on an existing field is risky unless a default exists or old records are acceptable.
+- Unsetting required is generally safe but may change frontend validation expectations.
+
+### delete_entity
+
+```json
+{
+  "type": "delete_entity",
+  "entityName": "Todo",
+  "payload": {
+    "hard": false,
+    "deleteData": false
+  }
+}
+```
+
+Rules:
+
+- Default to soft delete.
+- Hard delete requires explicit user request.
+- `deleteData: true` requires explicit confirmation because it destroys records.
+
+## Risk Checklist
+
+Stop and ask before applying when:
+
+- deleting an entity;
+- deleting a field used by UI or workflow output;
+- removing historical data;
+- changing field type;
+- making a field required without default;
+- broadening public access;
+- enabling public write;
+- reducing public guardrails such as removing required scopes or raising max limits;
+- changing owner/public scope semantics.
+
+Usually safe:
+
+- adding optional field;
+- adding field with default;
+- adding enum value;
+- adding index for existing query path;
+- adding presentation metadata;
+- adding stricter public filter/sort limits.
+
+## Version Semantics
+
+Schema versions manage definitions, not business records.
+
+Restore behavior:
+
+```text
+restore(versionId)
+  -> creates a new current schema version from old manifest
+  -> future create/update uses restored definitions
+  -> old entitydatashares records are not rolled back
+```
+
+Data records may still carry old fields after schema changes. Do not assume restore deletes or
+rewrites data.
+
+## Manifest Sync Handoff
+
+After apply, the result should include a version hint:
+
+```json
+{
+  "next": {
+    "recommendedAction": "sync_schema_artifacts",
+    "versionId": "dbv_next"
+  }
+}
+```
+
+Agent handoff sequence:
+
+1. Sync artifacts for `versionId`.
+2. Read `.howone/database/manifest.json`.
+3. Update `src/lib/sdk.ts` generated entity bindings.
+4. Update frontend CRUD/query code.
+5. Validate build.
+
+Never update frontend entity types from the draft patch alone when a synced manifest exists.
+
+## Common Agent Mistakes
+
+| Mistake | Correct behavior |
+|---|---|
+| Hand-writing `.howone/database/manifest.json` | Sync from backend version. |
+| Applying one operation after previewing a different patch | Apply the exact previewed patch. |
+| Adding required field without default | Treat as risk; ask migration/default policy. |
+| Public read list without `allowedFilters` / `allowedSorts` | Add public guardrails. |
+| Using `visibility: "public"` as permission model | Write explicit `access.public`. |
+| Deleting data because schema changed | Schema changes do not imply data deletion. |
+| Updating `src/lib/sdk.ts` before manifest sync | Wait for synced manifest. |
+
+## Minimal Safe Patch Template
+
+```ts
+const state = await client.schema.getState()
+
+const patch = {
+  operations: [
+    {
+      type: 'add_field',
+      entityName: 'Todo',
+      payload: {
+        fieldName: 'priority',
+        field: {
+          type: 'string',
+          enum: ['low', 'medium', 'high'],
+          default: 'medium',
+        },
+        required: false,
+      },
+    },
+  ],
+}
+
+const preview = await client.schema.previewPatch(patch, {
+  expectedVersionId: state.currentVersionId,
+  reason: 'Add todo priority',
+})
+
+if (preview.risk?.level === 'dangerous') {
+  throw new Error('User confirmation required before applying schema patch')
+}
+
+const applied = await client.schema.applyPatch(patch, {
+  expectedVersionId: state.currentVersionId,
+  reason: 'Add todo priority',
+})
+```

package/templates/vite/.howone/skills/howone/02-database/03-data-access-patterns.md

@@ -0,0 +1,309 @@
+# Data Access Patterns
+
+Use this reference to connect backend `access` design to frontend SDK calls. It answers:
+**which namespace should the app call, which filters are legal, and what must not be persisted?**
+
+For schema design, read `01-schema-design.md`. For query syntax details, read
+`04-query-dsl-and-responses.md`.
+
+## Namespace Decision
+
+| Schema / page need | SDK namespace | Auth header | Typical method |
+|---|---|---|---|
+| Current user's private records | `howone.entities.Entity` | yes | `query.mine`, `create`, `update`, `delete` |
+| Logged-in shared records | `howone.entities.Entity` | yes | `query`, `get`, CRUD |
+| Public list page | `howone.public.entities.Entity` | no | `query` |
+| Public scoped share/detail | `howone.public.entities.Entity` | no | `queryScoped`, `get` with scope options |
+| Schema tooling | `howone.schema` | yes | `previewPatch`, `applyPatch` |
+| Low-level fallback | `howone.raw` / `howone.public.raw` | depends | only when typed method missing |
+
+Do not mix authenticated and public namespaces for the same page without a clear reason.
+
+## Pattern A: Private Per-User Data
+
+Use for todos, notes, journals, saved generations, personal dashboards, private settings.
+
+Schema:
+
+```json
+{
+  "visibility": "private",
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  }
+}
+```
+
+Frontend:
+
+```ts
+const list = await howone.entities.Todo.query.mine({
+  page: { number: 1, size: 50 },
+  orderBy: { updatedDate: 'desc' },
+})
+
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+})
+```
+
+Rules:
+
+- Do not pass `ownerId`, `created_by_id`, `createdById`, `created_by_user_id`, or `puid`.
+- Backend derives owner from JWT/session.
+- Use `query.mine()` for owned lists.
+- For first auth load, call `await howone.me()` or `await howone.requireMe()`.
+
+## Pattern B: Authenticated Shared Data
+
+Use when logged-in app users can see shared records: team projects, CMS admin, internal catalogs.
+
+Schema:
+
+```json
+{
+  "visibility": "private",
+  "access": {
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+  }
+}
+```
+
+Frontend:
+
+```ts
+const list = await howone.entities.Project.query({
+  page: { number: 1, size: 20 },
+  orderBy: { updatedDate: 'desc' },
+})
+```
+
+Rules:
+
+- Use `query()`, not `query.mine()`.
+- Still require auth.
+- Be conservative with `update: "all"` and `delete: "all"` unless the app has a real role model.
+
+## Pattern C: Public Read-Only Content
+
+Use for public articles, templates, products, profiles, published galleries.
+
+Schema:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": {
+      "read": "list",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "allowedFilters": ["slug", "status", "category"],
+      "allowedSorts": ["publishedAt", "updatedDate"],
+      "defaultLimit": 20,
+      "maxLimit": 100
+    }
+  }
+}
+```
+
+Frontend:
+
+```ts
+const list = await howone.public.entities.Article.query({
+  where: { status: 'published', category },
+  page: { number: 1, size: 20 },
+  orderBy: { publishedAt: 'desc' },
+})
+```
+
+Rules:
+
+- Public filters must be in `allowedFilters`.
+- Public sorts must be in `allowedSorts`.
+- Never pass tokens or use authenticated namespace for anonymous landing pages.
+- Keep public result fields safe for anonymous users.
+
+## Pattern D: Public Scoped Share Pages
+
+Use for public URLs exposing one scoped record: QR profile, public report, resume, invite page.
+
+Schema:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+    "public": {
+      "read": "scoped",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["ownerId", "slug"],
+      "allowedFilters": ["slug", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 10
+    }
+  }
+}
+```
+
+Frontend:
+
+```ts
+const result = await howone.public.entities.QrProfile.queryScoped({
+  where: { ownerId, slug, active: true },
+  page: { number: 1, size: 1 },
+})
+const profile = result.items[0] ?? null
+```
+
+Rules:
+
+- Pass every `requiredScopes` field.
+- Do not use current JWT `puid` as `ownerId` unless schema explicitly stores that as public scope.
+- Do not turn scoped pages into broad list pages.
+- Keep `maxLimit` small.
+
+## Pattern E: Public Create / Anonymous Submission
+
+Use only for forms that must accept anonymous/public submissions: waitlist, contact, feedback,
+public RSVP.
+
+Schema:
+
+```json
+{
+  "visibility": "public",
+  "access": {
+    "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+    "public": {
+      "read": "none",
+      "create": "scoped",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["created_by_user_id"],
+      "allowedFilters": [],
+      "allowedSorts": [],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  }
+}
+```
+
+Frontend:
+
+```ts
+await howone.public.entities.Feedback.create({
+  created_by_user_id: projectUserId,
+  message,
+  rating,
+})
+```
+
+Rules:
+
+- Public create needs a clear `created_by_user_id` source when backend requires ownership mapping.
+- Do not expose public read unless needed.
+- Add anti-abuse UX/server constraints outside the dynamic schema when needed.
+- Never persist UI-only fields from form components.
+
+## Pattern F: AI Workflow Output Persistence
+
+Use for generation/analyze/report products that need history and refresh resilience.
+
+Recommended flow:
+
+```ts
+const pending = await howone.entities.Generation.create({
+  prompt,
+  status: 'pending',
+})
+
+try {
+  const output = await howone.ai.generateImage.run({ prompt })
+  await howone.entities.Generation.update(pending.id, {
+    status: 'completed',
+    resultUrl: output.imageUrl,
+    completedAt: new Date().toISOString(),
+  })
+} catch (error) {
+  await howone.entities.Generation.update(pending.id, {
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  })
+}
+
+const history = await howone.entities.Generation.query.mine({
+  orderBy: { updatedDate: 'desc' },
+  page: { number: 1, size: 20 },
+})
+```
+
+Rules:
+
+- Persist only fields declared in the entity schema.
+- Do not persist raw workflow event streams unless schema defines an object/array field for them.
+- Failure branch must persist failure if the product shows history.
+- Latest result, history list, and detail pages should reload from data API, not only local state.
+
+## Payload Whitelist Rule
+
+Before every create/update, mentally compute:
+
+```text
+payload keys ⊆ entity.properties keys
+```
+
+Allowed:
+
+```ts
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+})
+```
+
+Forbidden:
+
+```ts
+await howone.entities.Todo.create({
+  text,
+  completed: false,
+  gradient_direction: 'to right', // UI-only
+  created_by_id: user.id,         // system/owner field
+  workflowRawResult: output,      // undeclared workflow envelope
+})
+```
+
+If the app truly needs a new persisted field, update schema first.
+
+## Access-to-SDK Mapping
+
+| Access posture | Read | Create | Update/Delete |
+|---|---|---|---|
+| authenticated `own` | `entities.X.query.mine()` | `entities.X.create()` | `entities.X.update/delete()` |
+| authenticated `all` | `entities.X.query()` | `entities.X.create()` | `entities.X.update/delete()` |
+| public `list` | `public.entities.X.query()` | no | no |
+| public `scoped` | `public.entities.X.queryScoped()` | only if `create: scoped/any` | only if `update: scoped/any` |
+| public `none` | no public call | no public call | no public call |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Passing `created_by_user_id` for normal private data | Omit owner fields; backend derives owner. |
+| Using `entities.*` on public page | Use `public.entities.*`. |
+| Public filter not in `allowedFilters` | Add filter to schema or remove query. |
+| Public sort not in `allowedSorts` | Add sort to schema or change UI. |
+| Saving workflow output object directly | Map only declared fields. |
+| Rendering history only from local state | Reload via `query.mine()` / public query. |
+| Treating `visibility: "public"` as enough | Always define `access.public`. |