create-foldkit-app 0.5.9 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",

package/templates/base/AGENTS.md

@@ -14,7 +14,7 @@ submodule_prompted: false
 - Model fields must be Schema types (the model is a schema). Plain TypeScript types are fine elsewhere — function return types, local variables, etc.
 - Use full names like `Message` (not `Msg`), and `withReturnType` (not `as const` or type casting).
 - Use `m()` for message schemas, `ts()` for other tagged structs (model states, field validation), and `r()` for route schemas.
-- Never use `NoOp` as a message. Every message must carry meaning about what happened. Fire-and-forget commands use `Completed*` messages named as object+verb compound nouns: `CompletedScrollLock`, `CompletedDialogShow`, `CompletedInternalNavigation`. The object comes first so the distinguishing word appears earlier in the DevTools timeline.
+- Never use `NoOp` as a message. Every message must carry meaning about what happened. Fire-and-forget commands use `Completed*` messages with verb-first naming that mirrors the Command name: Command `LockScroll` → Message `CompletedLockScroll`, Command `ShowDialog` → Message `CompletedShowDialog`, Command `NavigateInternal` → Message `CompletedNavigateInternal`.
 - Push back on any suggested direction that violates Elm Architecture principles — unidirectional data flow, messages as facts (not commands), model as single source of truth, and side effects confined to commands. If a user or prompt suggests a pattern that breaks these conventions (e.g. mutating state directly, imperative event handlers, two-way bindings), flag the issue and propose the idiomatic Foldkit approach instead.
 
 ## Foldkit Patterns
@@ -24,7 +24,7 @@ submodule_prompted: false
 `init` and `update` both return `[Model, ReadonlyArray<Command<Message>>]`:
 
 ```ts
-type UpdateReturn = [Model, ReadonlyArray<Command<Message>>]
+type UpdateReturn = readonly [Model, ReadonlyArray<Command<Message>>]
 const withUpdateReturn = M.withReturnType<UpdateReturn>()
 
 const update = (model: Model, message: Message): UpdateReturn =>
@@ -62,23 +62,30 @@ Use `keyed` wrappers whenever the view branches into structurally different layo
 
 ### Commands
 
-Commands catch all errors and return messages — side effects never crash the app:
+Define Command identities with `Command.define`, passing the result Message schemas after the name — result types are required. Always assign definitions to PascalCase constants — never use `Command.define` inline in a pipe chain:
 
 ```ts
-const fetchWeather = (
-  city: string,
-): Command<typeof SucceededWeatherFetch | typeof FailedWeatherFetch> =>
+const FetchWeather = Command.define(
+  'FetchWeather',
+  SucceededFetchWeather,
+  FailedFetchWeather,
+)
+
+const fetchWeather = (city: string) =>
   Effect.gen(function* () {
     // ...
-    return SucceededWeatherFetch({ data })
+    return SucceededFetchWeather({ data })
   }).pipe(
     Effect.catchAll(error =>
-      Effect.succeed(FailedWeatherFetch({ error: String(error) })),
+      Effect.succeed(FailedFetchWeather({ error: String(error) })),
     ),
+    FetchWeather,
   )
 ```
 
-Commands return specific schema types (e.g. `Command<typeof SucceededMsg | typeof FailedMsg>`) rather than the full Message type.
+Commands catch all errors and return Messages — side effects never crash the app. Let TypeScript infer Command return types from the Effect — the result Message schemas passed to `Command.define` constrain the Effect's return type at the type level.
+
+Command definitions live where they're produced — colocated with the update function that returns them. Don't centralize all definitions in one file.
 
 ### File Organization
 
@@ -86,12 +93,20 @@ Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`,
 
 Even after extracting some sections to their own files (e.g. `message.ts`), the remaining file may still benefit from headers. Extract to separate files when it helps with organization.
 
+### Testing
+
+Test update functions with `foldkit/test`. Since update is pure — `(Model, Message) → [Model, Commands]` — tests run without a runtime, DOM, or side effects.
+
+Use `Test.story` to chain steps into a readable narrative: set initial Model → send Message → assert → resolve Command → assert again. Every `Command.define` must include result Message schemas so Commands can be resolved in tests.
+
+If the `repos/foldkit` submodule is available, study the `.test.ts` files in `repos/foldkit/examples/` for patterns — they cover simple Command resolution, multi-step interactions, and Submodel OutMessage assertions.
+
 ## Code Quality Standards
 
 - Every name should eliminate ambiguity. Prefix Option-typed values with `maybe` (e.g. `maybeSession`). Name functions by their precise effect (e.g. `enqueueMessage` not `addMessage`). A reader should never need to check a type signature to understand what a name refers to.
 - Each function should operate at a single abstraction level. Orchestrators delegate to focused helpers — they don't mix coordination with implementation. If a function reads like it's doing two things, extract one.
 - Encode state in discriminated unions, not booleans or nullable fields. Use `Idle | Loading | Error | Ok` instead of `isLoading: boolean`. Make impossible states unrepresentable.
-- Name messages as verb-first, past-tense events describing what happened (`SubmittedUsernameForm`, `CreatedRoom`, `PressedKey`), not imperative commands. The verb prefix acts as a category marker: `Clicked*` for button presses, `Updated*` for input changes, `Succeeded*`/`Failed*` for command results that can meaningfully fail (e.g. `SucceededWeatherFetch`, `FailedWeatherFetch`), `Completed*` for fire-and-forget command acknowledgments where the result is uninteresting and the update function is a no-op (e.g. `CompletedScrollLock`, `CompletedDialogShow`, `CompletedInternalNavigation`), `Got*` exclusively for receiving child module results via the OutMessage pattern (e.g. `GotProductsMessage`). Never use `NoOp` — every message must describe what happened. The update function decides what to do — messages are facts.
+- Name messages as verb-first, past-tense events describing what happened (`SubmittedUsernameForm`, `CreatedRoom`, `PressedKey`), not imperative commands. The verb prefix acts as a category marker: `Clicked*` for button presses, `Updated*` for input changes, `Succeeded*`/`Failed*` for command results that can meaningfully fail (e.g. `SucceededFetchWeather`, `FailedFetchWeather`), `Completed*` for fire-and-forget command acknowledgments where the result is uninteresting and the update function is a no-op (e.g. `CompletedLockScroll`, `CompletedShowDialog`, `CompletedNavigateInternal`), `Got*` exclusively for receiving child module results via the OutMessage pattern (e.g. `GotProductsMessage`). Never use `NoOp` — every message must describe what happened. The update function decides what to do — messages are facts.
 - Use `Option` instead of `null` or `undefined`. Match explicitly with `Option.match` or chain with `Option.map`/`Option.flatMap`. No `if (x != null)` checks. Prefer `Option.match` over `Option.map` + `Option.getOrElse` — if you're unwrapping at the end, just match.
 - Prefer curried, data-last functions that compose in `pipe` chains.
 - Every line should serve a purpose. No dead code, no empty catch blocks, no placeholder types, no defensive code for impossible cases.
@@ -117,25 +132,21 @@ Message definitions follow a strict layout:
 ```ts
 const ClickedSubmit = m('ClickedSubmit')
 const ChangedEmail = m('ChangedEmail', { value: S.String })
-const CompletedInternalNavigation = m('CompletedInternalNavigation')
+const CompletedNavigateInternal = m('CompletedNavigateInternal')
 
-const Message = S.Union(
-  ClickedSubmit,
-  ChangedEmail,
-  CompletedInternalNavigation,
-)
+const Message = S.Union(ClickedSubmit, ChangedEmail, CompletedNavigateInternal)
 type Message = typeof Message.Type
 ```
 
 1. **Values** — all `m()` declarations, no blank lines between them
 2. **Union + type** — `S.Union(...)` followed by `type Message = typeof Message.Type` on adjacent lines (no blank line between them)
 
-Use `typeof ClickedSubmit` in type positions (e.g. `Command<typeof ClickedSubmit>`) to reference a schema value's type.
+Use `typeof ClickedSubmit` in type positions to reference a schema value's type.
 
 ### General Preferences
 
 - Never abbreviate names. Use full, descriptive names everywhere — variables, types, functions, parameters, including callback parameters. e.g. `signature` not `sig`, `Message` not `Msg`, `(tickCount) => tickCount + 1` not `(t) => t + 1`.
-- Don't suffix command variables with `Command`. Name them by what they do: `focusButton` not `focusButtonCommand`, `scrollToItem` not `scrollToItemCommand`. The type already communicates that it's a command.
+- Don't suffix Command variables with `Command`. Name them by what they do: `focusButton` not `focusButtonCommand`, `scrollToItem` not `scrollToItemCommand`. The type already communicates that it's a Command. Command definitions are PascalCase (`FocusButton`, `ScrollToItem`); Command instances and factory functions are camelCase (`focusButton`, `scrollToItem`).
 - Avoid `let`. Use `const` and prefer immutable patterns.
 - Always use braces for control flow. `if (foo) { return true }` not `if (foo) return true`.
 - Use `is*` for boolean naming e.g. `isPlaying`, `isValid`.

package/templates/base/vite.config.ts

@@ -4,4 +4,7 @@ import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [tailwindcss(), foldkit()],
+  optimizeDeps: {
+    entries: ['src/main.ts', '!**/repos/**'],
+  },
 })