howone 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/howone-sdk/SKILL.md

@@ -5,16 +5,85 @@ description: Build application code with @howone/sdk correctly. Use when impleme
 
 # HowOne SDK
 
-Use this skill when writing app code that consumes `@howone/sdk`. The goal is stable generated code: read backend-synced manifests, define zod schemas, bind entities and AI actions in the app SDK entry, then call those bindings from UI code.
+Use this skill when writing app code that consumes `@howone/sdk`. The goal is stable generated code: read backend-synced manifests, define runtime schemas, bind entities and AI actions in the app SDK entry, then call those bindings from UI code.
+
+This skill is the normal source of truth for HowOne SDK usage in generated apps. Do not inspect `node_modules/@howone/sdk` just to rediscover imports, hook names, entity methods, AI action call shapes, or Vite environment wiring. Use dependency source only for narrow missing details, signature drift proven by verification, or SDK-package development.
 
 ## Workflow
 
-1. Locate the app root first. If an app was created by `howone init app <name>`, all `.howone/*` metadata and `src/lib/sdk.ts` work should happen inside that created app directory.
-2. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
-3. For Entity bindings, read `.howone/database/manifest.json`.
-4. For AI action bindings, read `.howone/ai/manifest.json`.
-5. Generate source code from the manifests, not from memory or tool-call summaries.
-6. Keep sync tools and app-code edits separate. `sync_schema_artifacts` and `sync_ai_artifacts` write metadata only; the coding agent edits `src/lib/sdk.ts`.
+1. Establish the app root. All `.howone/*` metadata and `src/lib/sdk.ts` work belongs inside that app root.
+2. Read `node_modules/@howone/sdk/dist/index.d.ts` and `node_modules/@howone/sdk/dist/react.d.ts` to get the complete, always-up-to-date type signatures and public exports.
+3. Read `references/usage-patterns.md` for generation recipes, usage examples, and known traps that aren't in the type declarations.
+4. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
+5. For Entity bindings, read `.howone/database/manifest.json`.
+6. For AI action bindings, read `.howone/ai/manifest.json`.
+7. Generate source code from the manifests, not from memory or tool-call summaries.
+8. Keep sync tools and app-code edits separate. `sync_schema_artifacts` and `sync_ai_artifacts` write metadata only; the coding agent edits `src/lib/sdk.ts`.
+
+## Quick SDK Contract
+
+See `/sdk/dist/index.d.ts` and `/sdk/dist/react.d.ts` for the full type signatures. The minimal app wiring looks like:
+
+```ts
+import {
+  createClient,
+  defineAiAction,
+  defineAiActions,
+  defineEntities,
+  type EntityRecord,
+  withAiActions,
+  withEntities,
+} from '@howone/sdk'
+import { HowOneProvider, useHowoneContext } from '@howone/sdk/react'
+import { z } from 'zod'
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+})
+
+export const entities = defineEntities({
+  Todo: client.entity<Todo, TodoCreate, TodoUpdate>('Todo'),
+})
+
+export const ai = defineAiActions({
+  summarizeTodo: defineAiAction('summarizeTodo', {
+    inputSchema: z.object({ title: z.string() }),
+  }),
+})
+
+const howone = withAiActions(withEntities(client, entities), ai)
+export default howone
+```
+
+Entity calls are plain async SDK calls:
+
+```ts
+await howone.entities.Todo.list()
+await howone.entities.Todo.create({ title: 'Ship it', completed: false })
+await howone.entities.Todo.update(id, { completed: true })
+await howone.entities.Todo.delete(id)
+```
+
+AI action calls are bound by action name:
+
+```ts
+const result = await howone.ai.summarizeTodo.run({ title })
+const session = howone.ai.summarizeTodo.stream({ title })
+for await (const event of howone.ai.summarizeTodo.events({ title })) {
+  // handle event
+}
+```
+
+React integration provides provider/auth/loading UI only: `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading`, and `LoadingSpinner`. It does not provide entity/query/AI data hooks. Use `useEffect`/`useState` or a data-fetching library around plain async SDK calls.
+
+## Source Order
+
+Use this order when deciding what to read:
+
+1. `packages/sdk/dist/index.d.ts` and `packages/sdk/dist/react.d.ts` — complete public API.
+2. `references/usage-patterns.md` — generation recipes, examples, traps.
+3. Current app files: `src/lib/sdk.ts`, relevant UI files, and generated manifests.
 
 ## Rules
 
@@ -24,9 +93,11 @@ Use this skill when writing app code that consumes `@howone/sdk`. The goal is st
 - Current action binding shape is `howone.ai.<actionName>.run(input)`, `stream(input)`, and `events(input)`. Do not generate `howone.ai.run.<actionName>(input)` unless the SDK implementation has been changed to support that API.
 - Do not name AI actions `run`, `stream`, or `events`; those are reserved.
 - Define entity create/update types explicitly. Avoid deriving create types from `Omit<EntityRecord & ...>` when it widens the payload.
+- React integration does not provide entity/query/AI hooks. Use plain async SDK calls from React state/effects or an app-level data-fetching library.
 - Never make generated SDK/type files under `.howone`. `.howone` stores manifests only.
 - If an AI-first feature persists generated results, create/update AI capability schema first, sync `.howone/ai`, then derive Entity fields from the AI `outputSchema`.
 
 ## References
 
-Read `references/usage-patterns.md` before writing any code. It is the complete API reference for `@howone/sdk` and `@howone/sdk/react` — all type signatures, method names, import paths, and call patterns are already there.
+Read `packages/sdk/dist/index.d.ts` and `packages/sdk/dist/react.d.ts` for the full SDK type surface.
+Read `references/usage-patterns.md` for generation recipes, usage examples, and known traps.

package/templates/vite/.howone/skills/howone-sdk/references/usage-patterns.md

@@ -1,191 +1,15 @@
 # HowOne SDK Usage Patterns
 
-Complete API reference for `@howone/sdk` and `@howone/sdk/react`. Covers all type signatures, method names, import paths, and usage patterns needed to wire up entities, AI actions, and React components in a HowOne app.
+This file covers what the type declarations don't: generation recipes, usage examples, and known traps. For the complete public API (all types, method signatures, exports), read `node_modules/@howone/sdk/dist/index.d.ts` and `node_modules/@howone/sdk/dist/react.d.ts` first.
 
-## Complete Import Reference
+## SDK Mental Model
 
-```ts
-// @howone/sdk — all public exports
-import {
-  createClient,
-  defineAiAction,
-  defineAiActions,
-  defineEntities,
-  withAiActions,
-  withEntities,
-  type CreateClientOptions,
-  type EntityRecord,
-  type EntityClient,
-  type EntityBindings,
-  type QueryOptions,
-  type QueryResult,
-  type PageInfo,
-  type DeleteResult,
-  type AiClient,
-  type AiActionDefinition,
-  type AiActionClient,
-  type AiActionConfig,
-  type AiResult,       // = ExecutionResult
-  type AiSession,      // { result: Promise<AiResult>, cancel(): void, signal: AbortSignal }
-  type AiEvent,        // SSE event payload
-  type AiOptions,
-  type UserProfile,
-  AiSchemaValidationError,
-} from '@howone/sdk'
-
-// @howone/sdk/react — React components and hooks
-import {
-  HowOneProvider,
-  useHowoneContext,
-  FloatingButton,
-  Loading,
-  LoadingSpinner,
-  type HowOneProviderProps,
-  type HowOneAuthMode,
-  type HowOneThemeMode,
-  type HowOneBrandMode,
-} from '@howone/sdk/react'
-
-import { z } from 'zod'
-```
-
----
-
-## createClient — signature & return shape
-
-```ts
-const client = createClient({
-  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,  // required in Vite apps
-  env: import.meta.env.VITE_HOWONE_ENV,               // 'local' | 'dev' | 'prod'
-  // Optional advanced options (rarely needed):
-  // apiUrl, aiUrl, caseStyle ('camel'|'snake'), auth: { mode, getToken }
-})
-
-// client shape:
-client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient<...>
-client.entities: Record<string, EntityClient>
-client.ai: AiClient  // low-level; prefer withAiActions bindings
-client.me(): Promise<UserProfile | null>
-client.requireMe(): Promise<UserProfile>
-client.auth.setToken(t: string | null): void
-client.auth.getToken(): string | null
-client.auth.isAuthenticated(): boolean
-client.auth.login(redirect?: string): void
-client.auth.logout(): void
-client.upload.file(file, options?): Promise<{ url, thumbnailUrl?, id?, size?, mimeType? }>
-client.upload.image(file): Promise<{ url }>
-client.upload.batch({ files, concurrent?, onProgress?, onFileComplete? }): Promise<BatchUploadResponse>
-```
-
----
-
-## EntityClient — complete method signatures
-
-```ts
-type EntityClient<TRecord, TCreate, TUpdate> = {
-  name: string
-  // Basic CRUD
-  list(options?: { page?, limit?, sort?, order?, ...filters }): Promise<TRecord[]>
-  get(id: string): Promise<TRecord | null>
-  getOrThrow(id: string): Promise<TRecord>
-  create(data: TCreate): Promise<TRecord>
-  update(id: string, data: TUpdate): Promise<TRecord>
-  delete(id: string): Promise<{ deleted: boolean; id: string; message? }>
-  // Advanced query with filters/pagination
-  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
-  query.mine(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
-  bulkCreate(records: TCreate[], options?: { sample?: boolean }): Promise<TRecord[]>
-  aggregate(pipeline: unknown[]): Promise<unknown[]>
-}
-
-// QueryOptions
-type QueryOptions<TRecord> = {
-  where?: { [K in keyof TRecord]?: TRecord[K] | FieldOperator }
-  // FieldOperator: { eq, ne, gt, gte, lt, lte, contains, like, startsWith, endsWith, in, notIn }
-  search?: string
-  page?: { number?: number; size?: number }
-  orderBy?: Partial<Record<keyof TRecord | string, 'asc' | 'desc'>>
-}
-
-// QueryResult
-type QueryResult<T> = {
-  items: T[]
-  page: { number, size, total, totalPages, hasNext, hasPrev }
-}
-
-// EntityRecord base
-type EntityRecord = {
-  id: string
-  createdDate?: string
-  updatedDate?: string
-  createdById?: string
-  isSample?: boolean
-  [key: string]: unknown
-}
-```
-
----
-
-## AI Action — complete signatures
-
-```ts
-// Define a typed action
-defineAiAction(id: string, config?: {
-  inputSchema?: z.ZodType<TInput>
-  outputSchema?: z.ZodType<TOutput>
-  mode?: 'run' | 'stream' | 'events'
-}): AiActionDefinition<TInput, TOutput>
-
-// Group actions
-defineAiActions({ [name]: AiActionDefinition, ... }): actions
-
-// Bind to client
-withAiActions(client, actions): client & { ai: { [name]: AiActionClient } }
-
-// AiActionClient methods
-howone.ai.<actionName>.run(inputs?, options?): Promise<TOutput>
-howone.ai.<actionName>.stream(inputs?, options?): AiSession
-howone.ai.<actionName>.events(inputs?, options?): AsyncIterable<AiEvent>
-
-// AiSession
-type AiSession = {
-  result: Promise<AiResult>
-  cancel(): void
-  signal: AbortSignal
-}
-
-// Reserved names — do NOT use as action names: run, stream, events
-```
-
----
-
-## React: HowOneProvider & hooks
-
-`@howone/sdk/react` exports exactly: `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading`, `LoadingSpinner`.
-
-**There are no `useEntity`, `useQuery`, `useAi`, or other data-fetching hooks.** Entity and AI calls are plain async functions — call them directly in components with `useEffect`/`useState` or any data-fetching library (SWR, React Query, etc.).
-
-```tsx
-// Wrap app root — handles auth, theme, toasts, floating button
-<HowOneProvider
-  projectId={...}           // optional if client is already configured
-  auth="optional"           // 'required' | 'optional' | 'none'
-  brand="visible"           // 'visible' | 'hidden'
-  theme="inherit"           // 'dark' | 'light' | 'system' | 'inherit'
-  showBrandButton={true}
->
-  <App />
-</HowOneProvider>
-
-// Auth context hook — the only hook in the package
-const { user, token, isAuthenticated, logout } = useHowoneContext()
-// user shape: { id, email, name, avatar } | null
-
-// Loading components
-<Loading size="md" tone="brand" label="..." description="..." fullScreen />
-<LoadingSpinner size="sm" tone="neutral" />
-// size: 'sm' | 'md' | 'lg'    tone: 'brand' | 'neutral' | 'inverse'
-```
+- `createClient(...)` creates the base HowOne client with auth, entity, AI, upload, and user helpers.
+- `client.entity<TRecord, TCreate, TUpdate>('EntityName')` creates one typed entity client.
+- `defineEntities(...)` plus `withEntities(client, entities)` makes `howone.entities.<EntityName>` typed in app code.
+- `defineAiAction(...)` plus `defineAiActions(...)` plus `withAiActions(...)` makes `howone.ai.<actionName>.run|stream|events` typed in app code.
+- `@howone/sdk/react` provides auth/theme/loading UI primitives only. It does not provide entity, query, or AI data hooks.
+- `.howone/database/manifest.json` and `.howone/ai/manifest.json` are the generated contracts. App source should be generated from those manifests, not from memory.
 
 ## App SDK Entry
 
@@ -215,7 +39,6 @@ export const entities = defineEntities({
 export const ai = defineAiActions({
   // generateImage: defineAiAction('generateImage', {
   //   inputSchema: generateImageInputSchema,
-  //   outputSchema: generateImageOutputSchema,
   // }),
 })
 
@@ -224,6 +47,29 @@ const howone = withAiActions(withEntities(client, entities), ai)
 export default howone
 ```
 
+## Manifest-To-Code Recipe
+
+When backend metadata has been synced, generate app SDK code in this order:
+
+1. Read `src/lib/sdk.ts` to preserve the template's import style and existing bindings.
+2. Read `.howone/database/manifest.json` for entity names and fields. Generate `Record`, `Create`, and `Update` types, then bind each entity with `client.entity<Record, Create, Update>('EntityName')`.
+3. Read `.howone/ai/manifest.json` for AI capability names and JSON schemas. Generate zod input schemas and, only when safe, output schemas.
+4. Export a single default `howone` client built by composing `withEntities` and `withAiActions`.
+5. In UI code, import the default client and call `howone.entities.<Entity>.*` or `howone.ai.<action>.run(...)`.
+
+Basic JSON schema mapping for generated zod:
+
+```ts
+string -> z.string()
+number -> z.number()
+integer -> z.number().int()
+boolean -> z.boolean()
+array -> z.array(...)
+object -> z.object({ ... })
+enum -> z.enum([...])
+missing from required[] -> .optional()
+```
+
 ## Entity Types
 
 Prefer explicit payload types:
@@ -248,6 +94,22 @@ export const entities = defineEntities({
 })
 ```
 
+Generated entity app code usually needs only these calls:
+
+```ts
+const result = await howone.entities.Story.query({
+  search,
+  page: { number: 1, size: 20 },
+  orderBy: { createdDate: 'desc' },
+})
+
+await howone.entities.Story.create({ title, content, prompt })
+await howone.entities.Story.update(id, { title })
+await howone.entities.Story.delete(id)
+```
+
+Prefer `query()` for list UIs that need paging/search/sort metadata. Use `list()` only for simple array reads.
+
 Avoid this for generated create payloads:
 
 ```ts
@@ -277,7 +139,6 @@ export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
     inputSchema: generateStoryInputSchema,
-    outputSchema: generateStoryOutputSchema,
     mode: 'run',
   }),
 })
@@ -290,6 +151,7 @@ const result = await howone.ai.generateStory.run({
   topic,
   ageRange,
 })
+const story = result.finalResult as GenerateStoryOutput
 ```
 
 For streaming:
@@ -311,15 +173,15 @@ for await (const event of howone.ai.generateStory.events(input)) {
 
 `run()` validates input with `inputSchema`, calls the workflow, then validates the **raw `ExecutionResult`** (the full SSE envelope) with `outputSchema`. It does **not** automatically unwrap `result.finalResult`.
 
-If you want to type the final result only, either:
-1. Define `outputSchema` to match the full `ExecutionResult` shape, or
-2. Omit `outputSchema` and unwrap manually:
+If you want to type the final result only, omit `outputSchema` and unwrap manually:
 
 ```ts
 const result = await howone.ai.generateStory.run(input) // returns AiResult
 const finalResult = result.finalResult as GenerateStoryOutput
 ```
 
+Only define `outputSchema` when it matches the full `ExecutionResult` envelope or after verifying the SDK has changed to validate `finalResult` directly.
+
 ## AI Result Persistence
 
 For AI-generated data that should be saved:
@@ -333,10 +195,11 @@ Example:
 
 ```ts
 const story = await howone.ai.generateStory.run(input)
+const finalResult = story.finalResult as GenerateStoryOutput
 
 await howone.entities.Story.create({
-  title: story.title,
-  content: story.content,
+  title: finalResult.title,
+  content: finalResult.content,
   prompt: input.topic,
 })
 ```