create-foldkit-app 0.27.3 → 0.28.0

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { Effect, Layer, Option, Schema } from 'effect';
 import { Command, Flag } from 'effect/unstable/cli';
-import { FetchHttpClient } from 'effect/unstable/http';
 import { createRequire } from 'node:module';
 import { NodeRuntime, NodeServices, NodeStdio } from '@effect/platform-node';
 import { create as create_ } from './commands/create.js';
@@ -33,7 +32,4 @@ const create = Command.make('create', {
 const cli = Command.run(create, {
     version: packageJson.version,
 });
-cli.pipe(Effect.provide([
-    FetchHttpClient.layer,
-    Layer.mergeAll(NodeServices.layer, NodeStdio.layer),
-]), NodeRuntime.runMain);
+cli.pipe(Effect.provide([Layer.mergeAll(NodeServices.layer, NodeStdio.layer)]), NodeRuntime.runMain);

package/{templates → dist/templates}/base/AGENTS.md

@@ -25,7 +25,7 @@ If `foldkit-skills` is installed as a Claude Code plugin, the `generate-program`
 - Foldkit is tightly coupled to the Effect ecosystem. Do not suggest solutions outside of Effect-TS.
 - 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 tagged structs (model states, field validation), and `r()` for route schemas.
+- Use `defineMessageUnion()` for Message unions, `ts()` for tagged structs (Model states, field validation), and `r()` for route schemas.
 - Push back on any direction that violates Elm Architecture principles: unidirectional data flow, messages as facts (not commands), model as single source of truth, side effects confined to commands. If a prompt suggests mutating state, imperative event handlers, or two-way bindings, flag the issue and propose the idiomatic Foldkit approach.
 - Never use `NoOp`. Every message must describe what happened. A command's result message is named from the command, not from the fact it reports, whether or not it carries a payload: `LockScroll` → `CompletedLockScroll`, `DetermineStartTime` → `CompletedDetermineStartTime` (never `DeterminedStartTime`).
 
@@ -37,15 +37,11 @@ If `foldkit-skills` is installed as a Claude Code plugin, the `generate-program`
 
 ```ts
 type UpdateReturn = readonly [Model, ReadonlyArray<Command<Message>>]
-const withUpdateReturn = M.withReturnType<UpdateReturn>()
-
-const update = (model: Model, message: Message): UpdateReturn =>
-  M.value(message).pipe(
-    withUpdateReturn,
-    M.tagsExhaustive({
-      ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
-    }),
-  )
+
+const update = (model: Model, message: Message) =>
+  Message.match<UpdateReturn>(message, {
+    ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
+  })
 ```
 
 Use `evo()` from `foldkit/struct` for immutable model updates. Never spread or `Object.assign`.
@@ -60,7 +56,7 @@ Omit the children argument when an element has none: `h.div([h.Class('divider')]
 
 ### Commands
 
-Define a Command with `Command.define(name, { args, messages, execute })`; omit `args` when the Command takes none. Assign definitions to PascalCase constants. Never inline in pipe chains. Name the effect `execute` performs, not the later Model transition caused when update handles its result: a timer that only waits before update starts a dismissal is `WaitBeforeDismissal`, not `DismissAfter`. Commands catch all errors via `Effect.catch(() => Effect.succeed(FailedX(...)))` so side effects never crash the app. Definitions live colocated with the update function that returns them.
+Define a Command with `Command.define(name, { args, messages, execute })`; omit `args` when the Command takes none. Assign definitions to PascalCase constants. Never inline in pipe chains. Name the effect `execute` performs, not the later Model transition caused when update handles its result: a timer that only waits before update starts a dismissal is `WaitBeforeDismissal`, not `DismissAfter`. Commands catch all errors via `Effect.catch(() => Effect.succeed(Message.FailedX(...)))` so side effects never crash the app. Definitions live colocated with the update function that returns them.
 
 For the with-args shape, see `repos/foldkit/examples/weather/src/main.ts` or `repos/foldkit/examples/kanban/src/command.ts`. For an argless DOM-side-effect Command, the argless form in `kanban/src/command.ts` (`FocusAddCardInput`) is the canonical reference.
 
@@ -89,27 +85,29 @@ Scene runs at any level, since a page's own `update`/`view` pair drops into `sce
 - Encode state in discriminated unions, not booleans or nullable fields. `Idle | Loading | Error | Ok`, not `isLoading: boolean`. Make impossible states unrepresentable.
 - Use `Option` instead of `null` or `undefined`. Prefix Option-typed values with `maybe*`. Match with `Option.match`; don't unwrap with `Option.map(...)` + `Option.getOrElse(...)` when you can just match.
 - Use Effect modules over native methods in `pipe` chains (`Array.map`, `String.startsWith`, `Array.findFirst`). Native methods are fine when calling directly on a named variable.
-- Never cast Schema values with `as Type`. Use the callable constructor: `SucceededLogin({ sessionId })`, not `{ _tag: 'SucceededLogin', sessionId } as Message`.
+- Never cast Schema values with `as Type`. Use the callable constructor: `Message.SucceededLogin({ sessionId })`, not `{ _tag: 'SucceededLogin', sessionId } as Message`.
 - Always `Array.isArrayEmpty` / `Array.isArrayNonEmpty` (not `.length === 0` / `.length > 0`). Use `Array.match` when handling both empty and non-empty cases.
 - Never use `for` loops or `let` for iteration. Reach for `Array.map`, `Array.filterMap`, `Array.makeBy`, `Array.reduce`.
 - Never use `T[]`. Always `Array<T>` or `ReadonlyArray<T>`.
-- Always use `Effect.Match`, never `switch`.
+- Use `Message.match` for exhaustive Message matching. Use Effect `Match` for other tagged unions, partial matching, fallbacks, and one handler shared across multiple tags. Never use `switch`.
 - Always use braces for control flow: `if (foo) { return true }`.
 - Don't add inline comments to explain code. Use better names instead. Reserve `// NOTE:` for behavior that would mislead a careful reader.
 
 ## Message Layout
 
-Group all `m()` declarations together, then put `S.Union([...])` and `type Message = typeof Message.Type` on adjacent lines:
+Declare the whole Message union with `defineMessageUnion()`, then put `type Message = typeof Message.Type` on the next line:
 
 ```ts
-const ClickedSubmit = m('ClickedSubmit')
-const UpdatedEmail = m('UpdatedEmail', { value: S.String })
-
-const Message = S.Union([ClickedSubmit, UpdatedEmail])
+const Message = defineMessageUnion({
+  ClickedSubmit: {},
+  UpdatedEmail: { value: S.String },
+})
 type Message = typeof Message.Type
 ```
 
-Keep the declarations in one unbroken block while the union is small, up to roughly a dozen Messages. Past that, blank-line thematic clusters (navigation, session, one per feature) are equally fine, so pick whichever reads better for the union at hand. The `S.Union([...])` and `type Message` pair stays adjacent, directly after the declarations, either way.
+Keep the `defineMessageUnion()` declaration and `type Message` alias adjacent. Construct values through the namespace (`Message.ClickedSubmit()`) and handle the union with `Message.match`. Never destructure constructors from `Message` or `OutMessage`; the owning namespace stays visible at every call site.
+
+Keep each case's payload object on one line when it fits. Let Prettier wrap payloads that need more space, so the declaration remains easy to scan as one variant per line.
 
 Messages are verb-first past-tense. Common prefixes: `Clicked*`, `Updated*` (input changes and external state updates), `Submitted*`, `Pressed*`, `Selected*`, `Succeeded*` / `Failed*` (paired async results), `Completed*` (every other Command result), `Got*` (child OutMessage in the Submodel pattern).
 

package/dist/templates/examples/api-cache/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "api-cache-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-browser": "4.0.0-rc.109",
+    "@foldkit/ui": "workspace:*",
+    "@tailwindcss/vite": "^4.3.1",
+    "effect": "4.0.0-rc.109",
+    "foldkit": "workspace:*",
+    "tailwindcss": "^4.3.1"
+  },
+  "devDependencies": {
+    "@foldkit/devtools": "workspace:*",
+    "@foldkit/vite-plugin": "workspace:*",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "happy-dom": "^20.10.4",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

package/dist/templates/examples/api-cache/src/data.test.ts

@@ -0,0 +1,28 @@
+import { Effect, Exit } from 'effect'
+import { expect, test } from 'vitest'
+
+import { FLAKY_POST_ID, fetchPostDetail } from './data'
+
+test('a regular post resolves with its detail', async () => {
+  const detail = await Effect.runPromise(fetchPostDetail('model-is-the-cache'))
+
+  expect(detail.title).toBe('The Model Is the Cache')
+})
+
+test('the flaky post fails on the first fetch and succeeds on retry', async () => {
+  const firstAttempt = await Effect.runPromiseExit(
+    fetchPostDetail(FLAKY_POST_ID),
+  )
+
+  expect(Exit.isFailure(firstAttempt)).toBe(true)
+
+  const secondAttempt = await Effect.runPromise(fetchPostDetail(FLAKY_POST_ID))
+
+  expect(secondAttempt.id).toBe(FLAKY_POST_ID)
+})
+
+test('an unknown post id fails', async () => {
+  const attempt = await Effect.runPromiseExit(fetchPostDetail('does-not-exist'))
+
+  expect(Exit.isFailure(attempt)).toBe(true)
+})

package/dist/templates/examples/api-cache/src/data.ts

@@ -0,0 +1,126 @@
+import { Array, Duration, Effect, Option, Random, Schema as S } from 'effect'
+
+export const Post = S.Struct({
+  id: S.String,
+  title: S.String,
+  excerpt: S.String,
+})
+export type Post = typeof Post.Type
+
+export const PostDetail = S.Struct({
+  id: S.String,
+  title: S.String,
+  author: S.String,
+  body: S.String,
+})
+export type PostDetail = typeof PostDetail.Type
+
+export const Stats = S.Struct({
+  activeUsers: S.Number,
+  requestsPerSecond: S.Number,
+  cacheHitRatePercent: S.Number,
+})
+export type Stats = typeof Stats.Type
+
+export const FLAKY_POST_ID = 'flaky-connection'
+
+const SERVER_LATENCY = Duration.millis(700)
+
+type Article = Readonly<{
+  id: string
+  title: string
+  excerpt: string
+  author: string
+  body: string
+}>
+
+const articles: ReadonlyArray<Article> = [
+  {
+    id: 'model-is-the-cache',
+    title: 'The Model Is the Cache',
+    excerpt: 'Why a single source of truth needs no query client.',
+    author: 'Maya Okafor',
+    body: 'A cache is a place where fetched data lives between requests. In The Elm Architecture that place already exists: the Model. Store each query as a small state machine and every view reads the same truth.',
+  },
+  {
+    id: 'stale-while-revalidate',
+    title: 'Stale-While-Revalidate, Explained',
+    excerpt: 'Show the old data while the new data loads.',
+    author: 'Theo Lindqvist',
+    body: 'Dropping back to a spinner throws away perfectly good data. A Refreshing state carries the previous value while the fetch runs, so the screen never goes blank.',
+  },
+  {
+    id: 'query-keys-are-names',
+    title: 'Query Keys Are Just Names',
+    excerpt: 'A Model field per query replaces stringly-typed keys.',
+    author: 'Priya Raman',
+    body: 'When queries are known statically, the field name is the key. Reach for a HashMap keyed by a domain identifier only when the entries are genuinely dynamic, like these post details.',
+  },
+  {
+    id: 'invalidation-is-a-message',
+    title: 'Invalidation Is a Message',
+    excerpt: 'Marking data stale is a fact, not a framework feature.',
+    author: 'Jonas Weber',
+    body: 'Invalidation means the cached value can no longer be trusted. Dispatch a Message, move the entry to Refreshing, and return the fetch Command. The whole policy is visible in update.',
+  },
+  {
+    id: FLAKY_POST_ID,
+    title: 'This Post Fails Every Other Fetch',
+    excerpt: 'Open it to see the Failure state, then retry.',
+    author: 'Flaky McNetwork',
+    body: 'You made it. The fake server failed your first attempt on purpose and succeeded on the retry, which is exactly the round trip a Failure state plus a retry Message is for.',
+  },
+]
+
+const posts = Array.map(articles, ({ id, title, excerpt }) =>
+  Post.make({ id, title, excerpt }),
+)
+
+const postDetails = Array.map(articles, ({ id, title, author, body }) =>
+  PostDetail.make({ id, title, author, body }),
+)
+
+export const fetchPosts = Effect.gen(function* () {
+  yield* Effect.sleep(SERVER_LATENCY)
+
+  return posts
+})
+
+// NOTE: Module-level mutation simulates a flaky server so the Failure and
+// retry path is reachable from the UI. The Foldkit app itself never mutates.
+const flakyAttempts = { count: 0 }
+
+export const fetchPostDetail = (
+  postId: string,
+): Effect.Effect<PostDetail, string> =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(SERVER_LATENCY)
+
+    if (postId === FLAKY_POST_ID) {
+      flakyAttempts.count += 1
+
+      if (flakyAttempts.count % 2 === 1) {
+        return yield* Effect.fail(
+          'The connection dropped. Retry to fetch this post again.',
+        )
+      }
+    }
+
+    return yield* Option.match(
+      Array.findFirst(postDetails, ({ id }) => id === postId),
+      {
+        onNone: () => Effect.fail(`No post found with id ${postId}`),
+        onSome: Effect.succeed,
+      },
+    )
+  })
+
+export const fetchStats = Effect.gen(function* () {
+  yield* Effect.sleep(SERVER_LATENCY)
+
+  const activeUsers = yield* Random.nextIntBetween(80, 140)
+  const requestsPerSecond = yield* Random.nextIntBetween(900, 1600)
+  const cacheHitRatePercent = yield* Random.nextIntBetween(86, 99)
+
+  return Stats.make({ activeUsers, requestsPerSecond, cacheHitRatePercent })
+})

package/dist/templates/examples/api-cache/src/entry.ts

@@ -0,0 +1,17 @@
+import { Runtime } from 'foldkit'
+
+import { Message, Model, init, subscriptions, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  init,
+  update,
+  view,
+  subscriptions,
+  container: document.getElementById('root'),
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.run(application)

package/dist/templates/examples/api-cache/src/main.fixtures.ts

@@ -0,0 +1,70 @@
+import { HashMap, Option } from 'effect'
+
+import { Tabs } from '@foldkit/ui'
+
+import type { Post, PostDetail, Stats } from './data'
+import type { Model } from './main'
+import { PostDetailData, PostsData, StatsData, TABS_ID } from './main'
+
+export const FETCHED_AT = 1_750_000_000_000
+
+export const fixturePosts: ReadonlyArray<Post> = [
+  {
+    id: 'first-post',
+    title: 'First Post',
+    excerpt: 'The first fixture post.',
+  },
+  {
+    id: 'second-post',
+    title: 'Second Post',
+    excerpt: 'The second fixture post.',
+  },
+]
+
+export const firstPostDetail: PostDetail = {
+  id: 'first-post',
+  title: 'First Post',
+  author: 'Grace Hopper',
+  body: 'The whole body of the first fixture post.',
+}
+
+export const fixtureStats: Stats = {
+  activeUsers: 120,
+  requestsPerSecond: 1234,
+  cacheHitRatePercent: 97,
+}
+
+export const loadingPostsModel: Model = {
+  tabs: Tabs.init({ id: TABS_ID }),
+  activeTab: 'Posts',
+  posts: PostsData.Loading(),
+  postDetailById: HashMap.empty(),
+  maybeSelectedPostId: Option.none(),
+  stats: StatsData.Idle(),
+}
+
+export const loadedPostsModel: Model = {
+  ...loadingPostsModel,
+  posts: PostsData.Success({
+    data: { posts: fixturePosts, fetchedAt: FETCHED_AT },
+  }),
+}
+
+export const cachedFirstPostModel: Model = {
+  ...loadedPostsModel,
+  postDetailById: HashMap.set(
+    HashMap.empty(),
+    'first-post',
+    PostDetailData.Success({
+      data: { detail: firstPostDetail, fetchedAt: FETCHED_AT },
+    }),
+  ),
+}
+
+export const loadedStatsModel: Model = {
+  ...loadedPostsModel,
+  activeTab: 'Stats',
+  stats: StatsData.Success({
+    data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
+  }),
+}