howone 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.10",
+  "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

@@ -12,21 +12,78 @@ This skill is the normal source of truth for HowOne SDK usage in generated apps.
 ## Workflow
 
 1. Establish the app root. All `.howone/*` metadata and `src/lib/sdk.ts` work belongs inside that app root.
-2. Read `references/usage-patterns.md` once before writing SDK-related code. It contains the SDK mental model, essential public API, generation recipes, and common traps.
-3. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
-4. For Entity bindings, read `.howone/database/manifest.json`.
-5. For AI action bindings, read `.howone/ai/manifest.json`.
-6. Generate source code from the manifests, not from memory or tool-call summaries.
-7. 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`.
+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. Current app files: `src/lib/sdk.ts`, relevant UI files, and generated manifests.
-2. This skill: `SKILL.md` plus `references/usage-patterns.md`.
-3. TypeScript/compiler errors from verification.
-4. SDK source or declaration files, only as a narrow fallback for a missing or disputed API.
+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
 
@@ -42,4 +99,5 @@ Use this order when deciding what to read:
 
 ## References
 
-Read `references/usage-patterns.md` before writing SDK-related code. It is the working reference for `@howone/sdk` and `@howone/sdk/react`: mental model, imports, method names, app SDK entry shape, entity examples, AI action examples, React usage, validation caveats, and when source fallback is justified.
+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,18 +1,6 @@
 # HowOne SDK Usage Patterns
 
-Working reference for `@howone/sdk` and `@howone/sdk/react`. It covers the SDK surface that generated HowOne apps normally need: client setup, entity bindings, AI action bindings, React provider usage, and the known traps that cause repeated source inspection.
-
-## Reading Strategy
-
-Use this file as the working SDK manual for normal app generation. It intentionally includes the public imports, client shape, entity methods, AI action bindings, React exports, app SDK entry shape, and known validation caveats.
-
-Do not inspect `node_modules/@howone/sdk` for the same information unless:
-
-- This file does not cover the exact API needed.
-- TypeScript or runtime verification contradicts this file.
-- You are intentionally updating the SDK package itself, not an app that consumes it.
-
-When source fallback is necessary, keep it narrow: inspect the exact exported symbol or declaration that is missing, then return to app code. Do not glob or read the whole SDK package to relearn the basic usage below.
+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.
 
 ## SDK Mental Model
 
@@ -23,191 +11,6 @@ When source fallback is necessary, keep it narrow: inspect the exact exported sy
 - `@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.
 
-## Import Reference
-
-```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
-
-```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
-
-```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
-
-```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'
-```
-
 ## App SDK Entry
 
 Preferred Vite app entry shape:
@@ -401,37 +204,6 @@ await howone.entities.Story.create({
 })
 ```
 
-## Do Not Generate
-
-Avoid these patterns unless the SDK has explicitly added them:
-
-```ts
-// No data hooks in @howone/sdk/react
-const todos = useEntity('Todo')
-const query = useQuery(...)
-const result = useAi(...)
-
-// Wrong AI binding shape
-await howone.ai.run.generateStory(input)
-
-// Too-loose create payload
-type StoryCreate = Omit<StoryRecord, 'id' | 'createdDate' | 'updatedDate'>
-
-// Generated files do not belong under .howone
-// .howone stores synced manifests only.
-```
-
-## When To Read SDK Source
-
-Read SDK source or declaration files only for details not covered above, for example:
-
-- A newly added public method not listed here.
-- A TypeScript error proving a signature drifted.
-- A runtime error that points to a specific SDK helper.
-- Work that intentionally modifies `packages/sdk` itself.
-
-For app generation, do not inspect SDK source to rediscover `createClient`, entity CRUD, AI action binding shape, React exports, or Vite env setup.
-
 ## Generated Code Checklist
 
 - `src/lib/sdk.ts` imports only APIs it uses.