howone 0.1.22 → 0.1.25

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

@@ -1,76 +1,332 @@
 # Schema Operations
 
-Use this reference when applying backend entity schema changes through HowOne runtime tools.
+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 != source of truth
-validated backend manifest = source of truth
-synced .howone/database files = local copy of a backend version
-src/lib/sdk.ts = app binding generated from synced manifest
+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` files. Sync them from a concrete backend schema version.
+Do not hand-write `.howone/database/*`. Sync artifacts from a concrete backend version.
 
 ## Preferred Patch Flow
 
-For feature-level schema work:
+Use patch flow for most feature-level changes:
 
-1. Inspect current schema definitions or schema state.
-2. Design one complete patch containing all related operations.
+1. Inspect current `schema.getState()` and current entity definitions.
+2. Design a full patch containing all related operations.
 3. Preview the patch.
-4. Apply the exact same operations if risk is acceptable.
-5. Sync schema artifacts using the returned `next.versionId`.
-6. Read `.howone/database/manifest.json`.
-7. Update `src/lib/sdk.ts` from the manifest.
-8. Update frontend calls according to access.
-9. Validate.
+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 a patch and then apply a different set of single operations.
+Do not preview one patch and apply a different operation set.
 
-## Operation Types
+## 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',
+})
+```
 
-Supported schema operations:
+Available schema methods:
 
-| Type | Purpose |
+| Method | Use |
 |---|---|
-| `list_entities` | List current entity definitions. |
-| `get_entity` | Read one entity definition before modifying it. |
-| `create_entity` | Create a new entity contract. |
-| `update_entity` | Update entity metadata such as description, visibility, access, indexes, relations, presentation, lifecycle, performance. |
-| `delete_entity` | Soft or hard delete an entity definition. |
-| `add_field` | Add a new field. |
-| `update_field` | Patch an existing field definition. |
-| `delete_field` | Remove a field from schema, optionally from historical data. |
-| `set_field_required` | Add a field to top-level `required`. |
-| `unset_field_required` | Remove a field from top-level `required`. |
-
-## Payload Rules
-
-- `entityName` is required for every operation except `list_entities`.
-- `payload.properties` is required for `create_entity`.
-- `payload.required` must only contain fields that exist in `properties`.
-- `add_field` should use `{ fieldName, field, required }`.
-- `update_field` should use `{ fieldName, patch, required? }`.
-- `delete_field` should use `{ fieldName, removeFromData: false }` by default.
-- `required` belongs to the entity top level, not inside individual field definitions.
-
-## Risk Guardrails
-
-- Default entity deletion to soft delete.
-- Use hard delete only when the user explicitly asks.
-- Use `deleteData: true` only when the user explicitly asks to delete all records too.
-- Use `removeFromData: true` only after explicit confirmation.
-- Adding a required field to an existing entity should include a default when possible.
-- Changing a field type is high risk; inspect current schema and confirm intent before applying.
-- Schema restore creates a new restore version; it does not roll business data back.
-
-## Version Rules
-
-Schema versions manage entity definitions only. They do not roll back `entitydatashares`.
-
-After apply, use the returned version context:
+| `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
 {
@@ -81,16 +337,62 @@ After apply, use the returned version context:
 }
 ```
 
-The synced manifest must be read before updating SDK bindings.
+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.
 
-## Narrow Edit Flow
+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. |
 
-Single operations are acceptable for small explicit edits, such as "add priority to Todo":
+## Minimal Safe Patch Template
 
-1. `get_entity`
-2. Check whether field already exists.
-3. Preview/apply one `add_field` patch or use the schema operation fallback.
-4. Sync artifacts.
-5. Update SDK/UI.
+```ts
+const state = await client.schema.getState()
 
-For broader features, batch operations into one patch.
+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',
+})
+```