howone 0.2.3 → 0.2.5

package/templates/vite/.howone/skills/howone/references/common-errors.md

@@ -0,0 +1,27 @@
+# Common SDK Errors
+
+Use this reference when typecheck, build, authentication, entity access, upload, or AI execution
+fails.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `AI_WORKFLOW_CONFIGURATION_ERROR` | Missing or non-UUID `workflowId` | Re-read `.howone/ai/manifest.json`; pass its exact workflow config UUID. There is no action-name fallback. |
+| `AI_SCHEMA_CONFIGURATION_ERROR` | JSON Schema passed to `defineAiAction` | Convert manifest JSON Schema to a Zod schema. |
+| `AI_SCHEMA_VALIDATION_ERROR` on output | Workflow `finalResult` disagrees with manifest output schema | Fix the workflow or contract. Do not add `.passthrough()` or make required fields optional. |
+| `WorkflowExecutionError` | `run_error` or `credit_insufficient` terminal event | Inspect `error.outcome`, `error.result.errors`, and `error.runId`; show app-owned UI or retry only when appropriate. |
+| `aiUrl` / `aiBaseUrl` is not accepted | EAX routing is environment-owned | Remove the URL override and set `env` to `local`, `dev`, or `prod`. |
+| Request hits `/api/api/...` | Raw path included `/api` even though the base already ends in `/api` | Use a path such as `/custom/stats`, not `/api/custom/stats`. |
+| `response.data` is undefined | `howone.raw.*` already returns response data | Use `const data = await howone.raw.get<T>(...)`. |
+| Provider renders blank forever in a public app | Provider guard conflicts with client auth or no client was passed | Pass `<HowOneProvider client={howone}>`; its guard defaults to `howone.auth.guard`. |
+| `useHowoneContext must be used within HowOneProvider` | Hook called outside the Provider | Keep one root Provider and move the hook below it. |
+| `ElementSelectorProvider` import fails from `/react` | Devtools moved to a separate entry | Import it from `@howone/sdk/devtools`. |
+| Entity method is absent at typecheck/runtime | Manifest access forbids that capability and contract wrappers pruned it | Use the allowed namespace/operation or change and re-sync the platform contract. Do not cast the method back. |
+| Public query rejects a filter/sort/scope | Query violates `access.public` | Put filters under `where`; use only `allowedFilters`, `allowedSorts`, and every `requiredScopes` field. |
+| Nested JSON keys unexpectedly changed | `caseDepth: 'deep'` was enabled | Prefer the default `caseDepth: 'top-level'` for business JSON. |
+| `HowOneProtocolError` key collision | snake_case and camelCase keys normalize to the same key | Fix the backend response contract; the SDK refuses silent overwrite. |
+| Upload has no progress updates | Transport did not provide total bytes | Keep a loading state; `onProgress` fires only when total size is available. |
+| Batch upload loops/fails immediately | `concurrent` is not a positive integer | Use `concurrent: 1` or higher. |
+| Core import pulls React or React is missing | Framework code imported from the wrong entry | Use `@howone/sdk` for core, `@howone/sdk/react` for React, and `@howone/sdk/devtools` for selector tooling. |
+
+After a fix, run the project verifier, typecheck, and production build. A successful build alone does
+not prove that workflow IDs or manifest access rules are correct.

package/templates/vite/.howone/skills/howone/references/version-evidence.md

@@ -0,0 +1,47 @@
+# SDK Version Evidence
+
+Use this reference before writing or repairing `@howone/sdk` bindings. HowOne app contracts and
+SDK APIs change independently; verify both.
+
+## Evidence Order
+
+1. Read `.howone/database/manifest.json` and `.howone/ai/manifest.json` for project-specific names,
+   fields, access rules, schemas, and workflow UUIDs.
+2. Read the app `package.json` for the requested `@howone/sdk` version.
+3. Read `node_modules/@howone/sdk/package.json` for the version actually installed.
+4. Inspect the installed version's public typings:
+   - `node_modules/@howone/sdk/dist/index.d.ts`
+   - `node_modules/@howone/sdk/dist/react.d.ts`
+   - `node_modules/@howone/sdk/dist/devtools.d.ts`
+5. Use this Skill for the workflow and code-generation recipe.
+6. Use official remote documentation only as supplemental evidence. Never let latest remote docs
+   override installed typings for an older app.
+
+If steps 2 and 3 disagree, run the project's package manager install before coding. Do not repair
+types by casting around a stale installation.
+
+## Deterministic Check
+
+From the app root, run:
+
+```bash
+node .howone/skills/howone/scripts/verify-project.mjs
+```
+
+Fix every reported error before final validation. Warnings identify missing evidence or code that
+still relies on compatibility behavior.
+
+## Lookup Patterns
+
+Use `rg` against installed declarations instead of relying on remembered signatures:
+
+```bash
+rg -n "CreateClientOptions|HowOneClientRuntime" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "defineAiAction|AiActionClient|WorkflowExecutionError" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "EntityClient|withEntityContract|withPublicEntities" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "HowOneProviderProps" node_modules/@howone/sdk/dist/react.d.ts
+rg -n "ElementSelectorProviderProps" node_modules/@howone/sdk/dist/devtools.d.ts
+```
+
+When declarations and this Skill disagree, use the installed declarations for signatures and this
+Skill for platform ordering. Report the mismatch instead of silently inventing an adapter.

package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const appRoot = path.resolve(process.argv[2] || process.cwd())
+const errors = []
+const warnings = []
+const facts = []
+
+function relative(filePath) {
+  return path.relative(appRoot, filePath) || '.'
+}
+
+function readText(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null
+}
+
+function readJson(filePath, required = false) {
+  const source = readText(filePath)
+  if (source === null) {
+    if (required) errors.push(`Missing ${relative(filePath)}`)
+    return null
+  }
+  try {
+    return JSON.parse(source)
+  } catch (error) {
+    errors.push(`Invalid JSON in ${relative(filePath)}: ${error.message}`)
+    return null
+  }
+}
+
+function dependencySpec(pkg, name) {
+  return (
+    pkg?.dependencies?.[name] ??
+    pkg?.devDependencies?.[name] ??
+    pkg?.peerDependencies?.[name] ??
+    null
+  )
+}
+
+function collectWorkflowIds(value, output = []) {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectWorkflowIds(entry, output)
+    return output
+  }
+  if (!value || typeof value !== 'object') return output
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === 'workflowId' && typeof entry === 'string') output.push(entry)
+    collectWorkflowIds(entry, output)
+  }
+  return output
+}
+
+const packagePath = path.join(appRoot, 'package.json')
+const pkg = readJson(packagePath, true)
+const requested = dependencySpec(pkg, '@howone/sdk')
+if (!requested) errors.push('package.json does not declare @howone/sdk')
+else facts.push(`requested @howone/sdk: ${requested}`)
+
+const installedPackagePath = path.join(appRoot, 'node_modules/@howone/sdk/package.json')
+const installed = readJson(installedPackagePath)
+if (!installed) {
+  errors.push('node_modules/@howone/sdk is missing; run the project package manager install')
+} else {
+  facts.push(`installed @howone/sdk: ${installed.version}`)
+  const normalizedRequest = String(requested || '').replace(/^[~^]/, '')
+  if (/^\d/.test(normalizedRequest) && normalizedRequest !== installed.version) {
+    errors.push(`SDK version mismatch: package.json requests ${requested}, installed ${installed.version}`)
+  }
+  for (const declaration of ['index.d.ts', 'react.d.ts', 'devtools.d.ts']) {
+    const declarationPath = path.join(appRoot, 'node_modules/@howone/sdk/dist', declaration)
+    if (!fs.existsSync(declarationPath)) {
+      errors.push(`Installed SDK is missing dist/${declaration}`)
+    }
+  }
+}
+
+const databaseManifestPath = path.join(appRoot, '.howone/database/manifest.json')
+const aiManifestPath = path.join(appRoot, '.howone/ai/manifest.json')
+const databaseManifest = readJson(databaseManifestPath)
+const aiManifest = readJson(aiManifestPath)
+if (databaseManifest) facts.push(`database manifest: ${relative(databaseManifestPath)}`)
+else warnings.push('No synced database manifest found')
+if (aiManifest) {
+  facts.push(`AI manifest: ${relative(aiManifestPath)}`)
+  const workflowIds = collectWorkflowIds(aiManifest)
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  for (const workflowId of workflowIds) {
+    if (!uuid.test(workflowId)) errors.push(`AI manifest contains invalid workflowId: ${workflowId}`)
+  }
+  if (workflowIds.length === 0) warnings.push('AI manifest contains no workflowId values')
+} else {
+  warnings.push('No synced AI manifest found')
+}
+
+const sdkSourcePath = path.join(appRoot, 'src/lib/sdk.ts')
+const sdkSource = readText(sdkSourcePath)
+if (sdkSource === null) {
+  warnings.push('src/lib/sdk.ts is missing')
+} else {
+  facts.push(`SDK binding: ${relative(sdkSourcePath)}`)
+  if (/\b(?:aiUrl|aiBaseUrl)\s*:/.test(sdkSource)) {
+    errors.push('src/lib/sdk.ts overrides the EAX URL; use createClient env only')
+  }
+  if (/\bmode\s*:\s*['"](?:auto|standalone|embedded)['"]/.test(sdkSource)) {
+    errors.push('src/lib/sdk.ts uses the removed createClient mode option')
+  }
+}
+
+const sourceRoot = path.join(appRoot, 'src')
+if (fs.existsSync(sourceRoot)) {
+  const sourceFiles = []
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name)
+      if (entry.isDirectory()) visit(entryPath)
+      else if (/\.[cm]?[jt]sx?$/.test(entry.name)) sourceFiles.push(entryPath)
+    }
+  }
+  visit(sourceRoot)
+
+  for (const filePath of sourceFiles) {
+    const source = readText(filePath) || ''
+    if (
+      /import\s*\{[^}]*\bElementSelectorProvider\b[^}]*\}\s*from\s*['"]@howone\/sdk\/react['"]/.test(
+        source,
+      )
+    ) {
+      errors.push(`${relative(filePath)} imports ElementSelectorProvider from /react; use /devtools`)
+    }
+    if (/\burl\s*:\s*[`'"]\/api\//.test(source)) {
+      warnings.push(`${relative(filePath)} contains a raw /api/... path; the SDK REST base already includes /api`)
+    }
+    if (/<HowOneProvider\b(?![^>]*\bclient=)[^>]*>/.test(source)) {
+      errors.push(`${relative(filePath)} renders HowOneProvider without client={howone}`)
+    }
+  }
+}
+
+console.log(`HowOne project verification: ${appRoot}`)
+for (const fact of facts) console.log(`  ok: ${fact}`)
+for (const warning of [...new Set(warnings)]) console.warn(`  warning: ${warning}`)
+for (const error of [...new Set(errors)]) console.error(`  error: ${error}`)
+
+if (errors.length > 0) {
+  console.error(`Verification failed with ${new Set(errors).size} error(s).`)
+  process.exit(1)
+}
+
+console.log('Verification passed.')

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.31",
+    "@howone/sdk": "2.0.0-beta.32",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/src/App.tsx

@@ -1,12 +1,16 @@
+import howone from '@/lib/sdk'
+import { ElementSelectorProvider } from '@howone/sdk/devtools'
 import { HowOneProvider } from '@howone/sdk/react'
 
 function App() {
   return (
-    <HowOneProvider brand="visible">
-      <div className="App">
-        <h1>Hello HowOne</h1>
-      </div>
-    </HowOneProvider>
+    <ElementSelectorProvider>
+      <HowOneProvider client={howone} brand="visible">
+        <div className="App">
+          <h1>Hello HowOne</h1>
+        </div>
+      </HowOneProvider>
+    </ElementSelectorProvider>
   )
 }
 

package/templates/vite/src/lib/sdk.ts

@@ -12,17 +12,19 @@ const client = createClient({
 })
 
 export const entities = defineEntities({
-  // Add generated entity bindings here, for example:
-  // Todo: client.entity<Todo, TodoCreate, TodoUpdate>("Todo"),
+  // Generate bindings from .howone/database/manifest.json.
+  // Wrap each client.entity(...) with withEntityContract(..., entityDefinition).
+  // Generate manifest-approved public bindings separately with
+  // definePublicEntities + withPublicEntityContract + withPublicEntities.
 })
 
 export const ai = defineAiActions({
-  // Add generated AI action bindings here, for example:
-  // import { z } from "zod" and define Zod schemas before using defineAiAction.
+  // Generate bindings from .howone/ai/manifest.json.
+  // Import z from "zod" and convert manifest JSON Schema before using defineAiAction.
   // Do not paste JSON Schema objects from .howone/ai/manifest.json here directly.
   // With outputSchema configured, howone.ai.<action>.run() returns the validated finalResult payload.
   // generateImage: defineAiAction("generateImage", {
-  //   workflowId: "<workflow-config-id>", // config_id for this capability
+  //   workflowId: "<exact-manifest-uuid>", // required; there is no action-name fallback
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,
   // }),