create-foldkit-app 0.20.0 → 0.21.0

package/README.md

@@ -38,6 +38,7 @@ The CLI prompts you for a project name, starter example, and package manager. Pa
 | `generative-art`         | Perlin-noise flow field with evolving particle trails, mouse vortex, and high-frequency Messages       |
 | `auth`                   | Authentication with Submodels, OutMessage, and protected routes                                        |
 | `shopping-cart`          | Complex state management with nested Models and routing                                                |
+| `checkout-machine`       | Experimental state machine checkout with guarded branches and edge Commands                            |
 | `pixel-art`              | Pixel editor with undo/redo, UI components, and localStorage persistence                               |
 | `websocket-chat`         | Managed resources with WebSocket integration                                                           |
 | `managed-resource-layer` | Layer-backed ManagedResource lifecycle with an Effect service                                          |

package/dist/commands/create.js

@@ -1,10 +1,10 @@
 import chalk from 'chalk';
-import { Console, Effect, FileSystem, Match, Option, Path } from 'effect';
+import { Console, Effect, FileSystem, Option, Path } from 'effect';
 import { Prompt } from 'effect/unstable/cli';
 import { spawnSync } from 'node:child_process';
 import { examples } from '../examples.js';
 import { createProject } from '../utils/files.js';
-import { installDependencies } from '../utils/packages.js';
+import { devCommand, installDependencies, } from '../utils/packages.js';
 import { validateProjectName } from '../validateName.js';
 const isWindows = process.platform === 'win32';
 const promptForName = Prompt.text({
@@ -73,12 +73,11 @@ const installProjectDependencies = (projectPath, packageManager, example) => Eff
     yield* Console.log(chalk.green('✅ Dependencies installed'));
     yield* Console.log('');
 });
-const runDevServerCommand = (packageManager) => Match.value(packageManager).pipe(Match.when('pnpm', () => 'pnpm dev'), Match.when('npm', () => 'npm run dev'), Match.when('yarn', () => 'yarn dev'), Match.when('bun', () => 'bun dev'), Match.exhaustive);
 const displaySuccessMessage = (name, packageManager) => Effect.gen(function* () {
     yield* Console.log(chalk.bold('All systems nominal.'));
     yield* Console.log('');
     yield* Console.log(`  > ${chalk.cyan('cd')} ${name}`);
-    yield* Console.log(`  > ${chalk.cyan(runDevServerCommand(packageManager))}`);
+    yield* Console.log(`  > ${chalk.cyan(devCommand(packageManager))}`);
     yield* Console.log('');
     yield* Console.log(chalk.bold('AI-Assisted Development'));
     yield* Console.log('');

package/dist/examples.js

@@ -11,12 +11,14 @@ export const EXAMPLE_VALUES = [
     'api-cache',
     'charting',
     'routing',
+    'route-transitions',
     'query-sync',
     'snake',
     'canvas-art',
     'generative-art',
     'auth',
     'shopping-cart',
+    'checkout-machine',
     'pixel-art',
     'websocket-chat',
     'managed-resource-layer',
@@ -87,6 +89,11 @@ export const examples = [
         title: 'routing',
         description: 'URL routing with parser combinators and route parameters',
     },
+    {
+        value: 'route-transitions',
+        title: 'route-transitions',
+        description: 'Live transition log with entry, exit, and stayed navigation policies',
+    },
     {
         value: 'query-sync',
         title: 'query-sync',
@@ -117,6 +124,11 @@ export const examples = [
         title: 'shopping-cart',
         description: 'Complex state management with nested models and routing',
     },
+    {
+        value: 'checkout-machine',
+        title: 'checkout-machine',
+        description: 'Checkout workflow powered by the experimental state machine module with guarded branches and edge Commands',
+    },
     {
         value: 'pixel-art',
         title: 'pixel-art',

package/dist/utils/files.js

@@ -1,6 +1,7 @@
 import { Array, Effect, FileSystem, Match, Option, Path, Record, Ref, Schema, String, pipe, } from 'effect';
 import { HttpClient, HttpClientRequest, } from 'effect/unstable/http';
 import { fileURLToPath } from 'node:url';
+import { devCommand, installCommand } from './packages.js';
 const GITHUB_API_BASE_URL = 'https://api.github.com/repos/foldkit/foldkit/contents/examples';
 const getTemplateRoot = Effect.gen(function* () {
     const path = yield* Path.Path;
@@ -73,17 +74,20 @@ const createPackageManagerFiles = (projectPath, packageManager) => Effect.gen(fu
 });
 export const createProject = (name, projectPath, example, packageManager) => Effect.gen(function* () {
     yield* createBaseFiles(projectPath);
-    yield* modifyBaseFiles(projectPath, name);
+    yield* modifyBaseFiles(projectPath, name, packageManager);
     yield* createPackageManagerFiles(projectPath, packageManager);
     yield* createExampleFiles(projectPath, example);
 });
-const modifyBaseFiles = (projectPath, name) => Effect.gen(function* () {
+export const applyPackageManager = (readme, packageManager) => pipe(readme, String.replace('{{installCommand}}', installCommand(packageManager)), String.replace('{{devCommand}}', devCommand(packageManager)));
+const modifyBaseFiles = (projectPath, name, packageManager) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const packageJsonPath = path.join(projectPath, 'package.json');
-    const content = yield* fs.readFileString(packageJsonPath);
-    const updatedContent = String.replace('my-foldkit-app', name)(content);
-    yield* fs.writeFileString(packageJsonPath, updatedContent);
+    const packageJson = yield* fs.readFileString(packageJsonPath);
+    yield* fs.writeFileString(packageJsonPath, String.replace('{{name}}', name)(packageJson));
+    const readmePath = path.join(projectPath, 'README.md');
+    const readme = yield* fs.readFileString(readmePath);
+    yield* fs.writeFileString(readmePath, applyPackageManager(readme, packageManager));
 });
 const GitHubFileEntry = Schema.Struct({
     name: Schema.String,

package/dist/utils/packages.js

@@ -1,6 +1,14 @@
 import { Array, Effect, FileSystem, Match, Order, Path, Record, Result, Schema, pipe, } from 'effect';
 import { HttpClient, HttpClientRequest } from 'effect/unstable/http';
 import { spawn } from 'node:child_process';
+export const installCommand = (packageManager) => `${packageManager} install`;
+const DEV_COMMANDS = {
+    pnpm: 'pnpm dev',
+    npm: 'npm run dev',
+    yarn: 'yarn dev',
+    bun: 'bun dev',
+};
+export const devCommand = (packageManager) => DEV_COMMANDS[packageManager];
 const GITHUB_RAW_BASE_URL = 'https://raw.githubusercontent.com/foldkit/foldkit/main/examples';
 const NPM_REGISTRY_BASE_URL = 'https://registry.npmjs.org';
 const FOLDKIT_SCOPE_PREFIX = '@foldkit/';

package/package.json

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

package/templates/base/.oxlintrc.json

@@ -1,12 +1,7 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": ["./node_modules/@foldkit/oxlint-plugin/recommended.json"],
   "plugins": ["typescript"],
-  "jsPlugins": [
-    {
-      "name": "foldkit",
-      "specifier": "@foldkit/oxlint-plugin"
-    }
-  ],
   "categories": {
     "correctness": "off"
   },
@@ -24,15 +19,7 @@
     "typescript/consistent-type-assertions": [
       "error",
       { "assertionStyle": "never" }
-    ],
-    "foldkit/no-noop-message": "error",
-    "foldkit/got-submodel-message-name": "error",
-    "foldkit/message-binding-matches-tag": "error",
-    "foldkit/got-prefix-requires-submodel-payload": "error",
-    "foldkit/no-empty-object-tagged-call": "error",
-    "foldkit/prefer-callable-message-constructor": "error",
-    "foldkit/command-binding-matches-name": "error",
-    "foldkit/no-module-level-mutable-state": "error"
+    ]
   },
   "ignorePatterns": [
     "dist/",

package/templates/base/AGENTS.md

@@ -66,7 +66,9 @@ For DOM operations (focus, scroll, modals, scroll lock), Foldkit ships a `Dom` m
 
 ### File Organization
 
-A Foldkit app lives in two files. `src/main.ts` holds the pure definitions (Model, Messages, init, update, view). `src/entry.ts` imports them and boots the runtime with `Runtime.makeApplication` and `Runtime.run`. `index.html` references `entry.ts`. The split keeps `main.ts` importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+The invariant: keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication` and `Runtime.run`, and `index.html` references it. The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run`, so they stay importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+
+For a small app the definitions all fit in one `src/main.ts`. Split a unit into its own file when it has _both_ a distinct reason to change _and_ a name you'd give it unprompted: the pure domain core into `timer.ts` or `domain.ts`, the view into `view.ts` (or a `components/` directory), a Command's owned resource into its own module. Split on that revealed seam, not on line count alone. A file that has grown large is _evidence_ a seam has formed, so treat its size as a prompt to re-check for one. Two splits are forced: extract Messages to `message.ts` when Commands need the constructors (this breaks the cycle between `command.ts` and `main.ts`), and colocate Commands with the update that returns them. Exemplars: counter and stopwatch are a single `main.ts`; kanban splits `domain` / `command` / `message` / `model`; typing-game splits views by page.
 
 Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) for wayfinding.
 

package/templates/base/README.md

@@ -5,8 +5,8 @@ A Foldkit application built with Effect.
 ## Getting Started
 
 ```bash
-pnpm install
-pnpm dev
+{{installCommand}}
+{{devCommand}}
 ```
 
 ## Learn More

package/templates/base/gitignore

@@ -23,3 +23,6 @@ Thumbs.db
 
 # TypeScript
 *.tsbuildinfo
+
+# Claude Code worktrees
+.claude/worktrees/

package/templates/base/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "my-foldkit-app",
+  "name": "{{name}}",
   "version": "0.1.0",
   "type": "module",
   "scripts": {
@@ -9,6 +9,6 @@
     "typecheck": "tsc --noEmit",
     "format": "prettier -w .",
     "test": "vitest run",
-    "lint": "oxlint"
+    "lint": "oxlint src"
   }
 }

package/templates/base/vitest.config.ts

@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
+    include: ['src/**/*.{test,spec}.ts'],
     environment: 'happy-dom',
     setupFiles: ['./src/vitest-setup.ts'],
     server: {