howone 0.1.6 → 0.1.8

package/package.json

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

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

@@ -0,0 +1,32 @@
+---
+name: howone-sdk
+description: Build application code with @howone/sdk correctly. Use when implementing or reviewing HowOne app SDK wiring, src/lib/sdk.ts, dynamic entity bindings, AI action bindings, zod runtime schemas, Vite environment variables, calls like howone.entities.* and howone.ai.*.run, or code generated from .howone/database and .howone/ai manifests.
+---
+
+# 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.
+
+## 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`.
+
+## Rules
+
+- Use `createClient({ projectId: import.meta.env.VITE_HOWONE_PROJECT_ID, env: import.meta.env.VITE_HOWONE_ENV })` in Vite apps. Do not add `?? 'prod'` or hardcoded project IDs in generated app code.
+- Use zod for AI input/output runtime schemas.
+- Use `defineAiAction` inside `defineAiActions`.
+- 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.
+- 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` when implementing or reviewing actual code.

package/templates/vite/.howone/skills/howone-sdk/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HowOne SDK"
+  short_description: "Build HowOne SDK integrations correctly."
+  default_prompt: "Use this skill when implementing HowOne SDK client, entity, and AI action code."

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

@@ -0,0 +1,166 @@
+# HowOne SDK Usage Patterns
+
+## App SDK Entry
+
+Preferred Vite app entry shape:
+
+```ts
+import {
+  createClient,
+  defineAiAction,
+  defineAiActions,
+  defineEntities,
+  type EntityRecord,
+  withAiActions,
+  withEntities,
+} from '@howone/sdk'
+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({
+  // generateImage: defineAiAction('generateImage', {
+  //   inputSchema: generateImageInputSchema,
+  //   outputSchema: generateImageOutputSchema,
+  // }),
+})
+
+const howone = withAiActions(withEntities(client, entities), ai)
+
+export default howone
+```
+
+## Entity Types
+
+Prefer explicit payload types:
+
+```ts
+export type StoryRecord = EntityRecord & {
+  title: string
+  content: string
+  prompt: string
+}
+
+export type StoryCreate = {
+  title: string
+  content: string
+  prompt: string
+}
+
+export type StoryUpdate = Partial<StoryCreate>
+
+export const entities = defineEntities({
+  Story: client.entity<StoryRecord, StoryCreate, StoryUpdate>('Story'),
+})
+```
+
+Avoid this for generated create payloads:
+
+```ts
+type StoryCreate = Omit<StoryRecord, 'id' | 'createdDate' | 'updatedDate'>
+```
+
+`EntityRecord` has an index signature, so `Omit` can make generated create types looser than intended.
+
+## AI Action Types
+
+Generate zod schemas from `.howone/ai/manifest.json`:
+
+```ts
+export const generateStoryInputSchema = z.object({
+  topic: z.string().min(1),
+  ageRange: z.enum(['3-5', '6-8', '9-12']),
+})
+
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+})
+
+export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
+
+export const ai = defineAiActions({
+  generateStory: defineAiAction('generateStory', {
+    inputSchema: generateStoryInputSchema,
+    outputSchema: generateStoryOutputSchema,
+    mode: 'run',
+  }),
+})
+```
+
+Call from app code:
+
+```ts
+const result = await howone.ai.generateStory.run({
+  topic,
+  ageRange,
+})
+```
+
+For streaming:
+
+```ts
+const session = howone.ai.generateStory.stream(input)
+session.cancel()
+```
+
+For event iteration:
+
+```ts
+for await (const event of howone.ai.generateStory.events(input)) {
+  console.log(event)
+}
+```
+
+## AI Output Validation Caveat
+
+Check `packages/sdk/src/services/ai.ts` before relying on output validation. The desired behavior is for `defineAiAction(...).run()` to validate and return the workflow final result, not the whole SSE execution envelope.
+
+Desired implementation shape:
+
+```ts
+const result = await base.run(definition.id, validInputs, options)
+const output = result?.finalResult ?? result
+return parseAiValue(definition.id, 'output', output, definition.outputSchema)
+```
+
+If the SDK still validates the whole `ExecutionResult`, either fix the SDK first or avoid generating final-result `outputSchema` in app code that will immediately run.
+
+## AI Result Persistence
+
+For AI-generated data that should be saved:
+
+1. Define AI input/output schemas from `.howone/ai/manifest.json`.
+2. Define entity fields from the AI output schema.
+3. Add only needed request metadata fields, such as prompt, selected options, language, status, or timestamps.
+4. Save with `howone.entities.<Entity>.create(...)`.
+
+Example:
+
+```ts
+const story = await howone.ai.generateStory.run(input)
+
+await howone.entities.Story.create({
+  title: story.title,
+  content: story.content,
+  prompt: input.topic,
+})
+```
+
+## Generated Code Checklist
+
+- `src/lib/sdk.ts` imports only APIs it uses.
+- `createClient` uses `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`.
+- Entity names match `.howone/database/manifest.json`.
+- AI action names and schemas match `.howone/ai/manifest.json`.
+- zod schemas are strict enough for generated UI inputs and backend contracts.
+- UI code calls `howone.ai.<action>.run(input)` and `howone.entities.<Entity>.*`.
+- No generated source file is written under `.howone`.

package/templates/vite/AGENTS.md

@@ -1,11 +1,46 @@
-Use the project SDK from `src/lib/sdk.ts` for backend access.
+# AGENTS.md
 
-For entity CRUD, prefer typed project bindings:
+This file defines project-specific instructions for coding agents.
 
-```ts
-import howone from "@/lib/sdk"
+Read this file once when entering the project.
+Follow it during implementation.
+Do not repeatedly reread it unless it changes or the current task requires checking project rules again.
 
-await howone.entities.Todo.create({ text, completed: false })
-```
+## Library Trust Policy
 
-Do not call `howone.entity("Todo")` directly in application code when a typed `howone.entities.Todo` binding exists. Add or update the binding in `src/lib/sdk.ts` first.
+For common public libraries already known to modern coding models, prefer model knowledge and package metadata over reading local source files.
+
+This project may include generated or vendored library-style files, such as shadcn/ui components under `src/components/ui/*`.
+
+Do not inspect these files during ordinary feature work just to confirm standard APIs.
+
+Examples of trusted public libraries:
+
+- React
+- Vite
+- TypeScript
+- Tailwind CSS
+- shadcn/ui
+- lucide-react
+- Radix UI
+- clsx
+- class-variance-authority
+
+When implementing ordinary usage of these libraries:
+
+1. Use standard public APIs first.
+2. Read `package.json`, `components.json`, `tsconfig.json`, or alias config only when needed.
+3. Implement the feature.
+4. Run build/typecheck.
+5. Inspect the smallest relevant local file only if validation fails or the API is genuinely unclear.
+
+Only read local component or library-style source files when:
+
+- build/typecheck fails
+- imports cannot be resolved from `package.json`, `tsconfig.json`, or `components.json`
+- the component API is unclear
+- the task requires modifying the component implementation
+- the project has custom wrappers, custom variants, or unusual exports
+- the user explicitly asks to follow local component conventions
+
+Prefer failure-driven inspection over speculative context loading.