create-foldkit-app 0.3.2 → 0.4.0

package/dist/commands/create.js

@@ -10,7 +10,7 @@ const validateProject = (name, projectPath, packageManager) => Effect.gen(functi
         return yield* Effect.fail(`Directory ${name} already exists!`);
     }
     const checkCommand = Command.make('which', packageManager).pipe(Command.stdout('pipe'), Command.stderr('pipe'));
-    return yield* Command.exitCode(checkCommand).pipe(Effect.filterOrFail((exitCode) => exitCode === 0, () => `Package manager '${packageManager}' is not available. Please install it first.`));
+    return yield* Command.exitCode(checkCommand).pipe(Effect.filterOrFail(exitCode => exitCode === 0, () => `Package manager '${packageManager}' is not available. Please install it first.`));
 });
 const setupProject = (name, projectPath, example) => Effect.gen(function* () {
     yield* Console.log(chalk.blue('🚀 Creating your Foldkit app...'));

package/dist/index.js

@@ -4,7 +4,7 @@ import { FetchHttpClient } from '@effect/platform';
 import { NodeContext, NodeRuntime } from '@effect/platform-node';
 import { Effect, Match, Option, Schema, String, flow } from 'effect';
 import { create as create_ } from './commands/create.js';
-const nameSchema = Schema.String.pipe(Schema.filter((name) => Match.value(name).pipe(Match.whenOr(String.includes('/'), String.includes('\\'), () => 'Project name cannot contain path separators (/ or \\)'), Match.when(String.includes(' '), () => 'Project name cannot contain spaces'), Match.when(flow(String.match(/[<>:"|?*]/), Option.isSome), () => 'Project name cannot contain special characters: < > : " | ? *'), Match.whenOr(String.startsWith('.'), String.startsWith('-'), () => 'Project name cannot start with . or -'), Match.when(String.isEmpty, () => 'Project name cannot be empty'), Match.orElse(() => true))));
+const nameSchema = Schema.String.pipe(Schema.filter(name => Match.value(name).pipe(Match.whenOr(String.includes('/'), String.includes('\\'), () => 'Project name cannot contain path separators (/ or \\)'), Match.when(String.includes(' '), () => 'Project name cannot contain spaces'), Match.when(flow(String.match(/[<>:"|?*]/), Option.isSome), () => 'Project name cannot contain special characters: < > : " | ? *'), Match.whenOr(String.startsWith('.'), String.startsWith('-'), () => 'Project name cannot start with . or -'), Match.when(String.isEmpty, () => 'Project name cannot be empty'), Match.orElse(() => true))));
 const name = Options.text('name').pipe(Options.withAlias('n'), Options.withDescription('The name of the project to create'), Options.withSchema(nameSchema));
 const example = Options.choice('example', [
     'counter',

package/dist/utils/files.js

@@ -14,7 +14,7 @@ const getBaseFiles = Effect.gen(function* () {
         yield* Match.value(stat.type).pipe(Match.when('Directory', () => processDirectory(fullPath)), Match.when('File', () => Effect.gen(function* () {
             const content = yield* fs.readFileString(fullPath);
             const relativePath = path.relative(templatesDir, fullPath);
-            yield* Ref.update(fileContentByPath, (files) => ({
+            yield* Ref.update(fileContentByPath, files => ({
                 ...files,
                 [relativePath]: content,
             }));
@@ -40,7 +40,7 @@ const createBaseFiles = (projectPath) => Effect.gen(function* () {
     yield* fs.makeDirectory(projectPath, { recursive: true });
     const baseFiles = yield* getBaseFiles;
     yield* pipe(baseFiles, Record.toEntries, Effect.forEach(([filePath, content]) => Effect.gen(function* () {
-        const targetPath = filePath === 'gitignore' ? '.gitignore' : filePath;
+        const targetPath = Match.value(filePath).pipe(Match.when('gitignore', () => '.gitignore'), Match.when('ignore', () => '.ignore'), Match.orElse(() => filePath));
         const fullPath = path.join(projectPath, targetPath);
         const dirPath = path.dirname(fullPath);
         yield* fs.makeDirectory(dirPath, { recursive: true });
@@ -51,7 +51,7 @@ const modifyBaseFiles = (projectPath, name) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const packageJsonPath = path.join(projectPath, 'package.json');
-    return yield* fs.readFileString(packageJsonPath).pipe(Effect.map(String.replace('my-foldkit-app', name)), Effect.flatMap((updatedContent) => fs.writeFileString(packageJsonPath, updatedContent)));
+    return yield* fs.readFileString(packageJsonPath).pipe(Effect.map(String.replace('my-foldkit-app', name)), Effect.flatMap(updatedContent => fs.writeFileString(packageJsonPath, updatedContent)));
 });
 const GitHubFileEntry = Schema.Struct({
     name: Schema.String,
@@ -66,7 +66,7 @@ const createExampleFiles = (projectPath, example) => Effect.gen(function* () {
     const files = yield* fetchExampleFileList(example);
     const srcPath = path.join(projectPath, 'src');
     yield* fs.makeDirectory(srcPath, { recursive: true });
-    yield* Effect.forEach(files, (file) => downloadExampleFile(file, projectPath), {
+    yield* Effect.forEach(files, file => downloadExampleFile(file, projectPath), {
         concurrency: 'unbounded',
     });
 });
@@ -77,7 +77,7 @@ const fetchExampleFileList = (example) => Effect.gen(function* () {
         const response = yield* client.execute(request);
         const json = yield* response.json;
         const entries = yield* Schema.decodeUnknown(Schema.Array(GitHubFileEntry))(json);
-        const results = yield* Effect.forEach(entries, (entry) => Match.value(entry.type).pipe(Match.when('file', () => Effect.succeed([entry])), Match.when('dir', () => fetchFilesRecursively(entry.url)), Match.orElse(() => Effect.succeed([]))));
+        const results = yield* Effect.forEach(entries, entry => Match.value(entry.type).pipe(Match.when('file', () => Effect.succeed([entry])), Match.when('dir', () => fetchFilesRecursively(entry.url)), Match.orElse(() => Effect.succeed([]))));
         return Array.flatten(results);
     });
     const githubApiUrl = `${GITHUB_API_BASE_URL}/${example}/src`;
@@ -94,10 +94,10 @@ const downloadExampleFile = (file, projectPath) => Effect.gen(function* () {
     const response = yield* client.execute(request);
     const content = yield* response.text;
     const pathParts = String.split(file.path, '/');
-    const srcIndex = Array.findFirstIndex(pathParts, (part) => part === 'src');
+    const srcIndex = Array.findFirstIndex(pathParts, part => part === 'src');
     const relativePath = pipe(srcIndex, Option.match({
         onNone: () => file.name,
-        onSome: (index) => pipe(pathParts, Array.drop(index + 1), Array.join('/')),
+        onSome: index => pipe(pathParts, Array.drop(index + 1), Array.join('/')),
     }));
     const targetPath = path.join(projectPath, 'src', relativePath);
     const dirPath = path.dirname(targetPath);

package/dist/utils/packages.js

@@ -1,7 +1,7 @@
 import { Command, HttpClient, HttpClientRequest } from '@effect/platform';
 import { Array, Effect, Match, Record, Schema, pipe } from 'effect';
 const GITHUB_RAW_BASE_URL = 'https://raw.githubusercontent.com/devinjameson/foldkit/main/examples';
-const getInstallArgs = (packageManager, isDev = false) => pipe(Match.value(packageManager), Match.when('npm', () => ['install']), Match.when('yarn', () => ['add']), Match.when('pnpm', () => ['add']), Match.exhaustive, (args) => (isDev ? [...args, '-D'] : args));
+const getInstallArgs = (packageManager, isDev = false) => pipe(Match.value(packageManager), Match.when('npm', () => ['install']), Match.when('yarn', () => ['add']), Match.when('pnpm', () => ['add']), Match.exhaustive, args => (isDev ? [...args, '-D'] : args));
 const StringRecord = Schema.Record({ key: Schema.String, value: Schema.String });
 const PackageJson = Schema.Struct({
     dependencies: Schema.optionalWith(StringRecord, { default: () => ({}) }),

package/package.json

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

package/templates/base/.prettierrc

@@ -1,6 +1,7 @@
 {
   "semi": false,
   "singleQuote": true,
+  "arrowParens": "avoid",
   "trailingComma": "all",
   "printWidth": 100,
 

package/templates/base/AGENTS.md

@@ -0,0 +1,138 @@
+# Agent Development Notes
+
+This is a Foldkit app — a framework built on Effect-TS.
+
+If `./foldkit` exists, it contains the full Foldkit repository as a git submodule. The `examples/` directory and `packages/typing-game/client/src/` in particular are the best reference for what idiomatic Foldkit apps look like.
+
+If `./foldkit` does not exist and the line below says `submodule_prompted: false`, offer to run `git submodule add https://github.com/devinjameson/foldkit.git` — this gives you access to the full source, examples, and docs. Whether the user accepts or declines, update the value to `true` so it isn't asked again.
+
+submodule_prompted: false
+
+## Project Conventions
+
+- 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 other tagged structs (model states, field validation), and `r()` for route schemas.
+- Every message union should include a `NoOp` variant: `const NoOp = m('NoOp')`.
+
+## Foldkit Patterns
+
+### Update
+
+`init` and `update` both return `[Model, ReadonlyArray<Command<Message>>]`:
+
+```ts
+type UpdateReturn = [Model, ReadonlyArray<Command<Message>>]
+const withUpdateReturn = M.withReturnType<UpdateReturn>()
+
+const update = (model: Model, message: Message): UpdateReturn =>
+  M.value(message).pipe(
+    withUpdateReturn,
+    M.tagsExhaustive({
+      NoOp: () => [model, []],
+      ClickedIncrement: () => [evo(model, { count: count => count + 1 }), []],
+    }),
+  )
+```
+
+### Model Updates with `evo`
+
+Use `evo()` for immutable model updates — never spread or Object.assign:
+
+```ts
+evo(model, { isSubmitting: () => true })
+evo(model, { count: count => count + 1 })
+```
+
+Don't add type annotations to `evo` callbacks when the type can be inferred.
+
+### View
+
+Call `html<Message>()` once in a dedicated `html.ts` file and import the destructured helpers everywhere else:
+
+```ts
+// html.ts
+export const { div, button, span, Class, OnClick } = html<Message>()
+```
+
+Use `empty` (not `null`) for conditional rendering. Use `M.value().pipe(M.tagsExhaustive({...}))` for rendering discriminated unions and `Array.match` for rendering lists that may be empty.
+
+Use `keyed` wrappers whenever the view branches into structurally different layouts based on route or model state. Without keying, the virtual DOM will try to diff one layout into another (e.g. a full-width landing page into a sidebar docs layout), which causes stale DOM, mismatched event handlers, and subtle rendering bugs. Key the outermost container of each layout branch with a stable string (e.g. `keyed('div')('landing', ...)` vs `keyed('div')('docs', ...)`). Within a single layout, key the content area on the route tag (e.g. `keyed('div')(model.route._tag, ...)`) so page transitions replace rather than patch.
+
+### Commands
+
+Commands catch all errors and return messages — side effects never crash the app:
+
+```ts
+const fetchWeather = (
+  city: string,
+): Command<typeof SucceededWeatherFetch | typeof FailedWeatherFetch> =>
+  Effect.gen(function* () {
+    // ...
+    return SucceededWeatherFetch({ data })
+  }).pipe(Effect.catchAll(error => Effect.succeed(FailedWeatherFetch({ error: String(error) }))))
+```
+
+Commands return specific schema types (e.g. `Command<typeof SucceededMsg | typeof FailedMsg>`) rather than the full Message type.
+
+### File Organization
+
+Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) to make files easier to skim. These are for wayfinding — they make it clear where things live and where new code should go. Use domain-specific headers too when it helps (e.g. `// PHYSICS`, `// ROUTING`).
+
+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.
+
+## 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 (`ClickedSubmit`, `GotWeatherData`, `UpdatedSearchInput`), not imperative commands. The verb prefix acts as a category marker: `Clicked*` for button presses, `Updated*` for input changes, `Requested*` for async triggers, `Got*` for data responses. 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.
+
+## Code Style Conventions
+
+### Effect-TS Patterns
+
+- Prefer `pipe()` for multi-step data flow. Never use `pipe` with a single operation — call the function directly instead: `Option.match(value, {...})` not `pipe(value, Option.match({...}))`.
+- Use `Effect.gen()` for imperative-style async operations.
+- Always use Effect.Match instead of switch.
+- Prefer Effect module functions over native methods when available — e.g. `Array.map`, `Array.filter`, `Option.map`, `String.startsWith` from Effect instead of their native equivalents. Exception: native `.map`, `.filter`, etc. are fine when calling directly on a named variable — use Effect's `Array.map` in `pipe` chains where the curried, data-last form composes naturally.
+- Never use `for` loops or `let` for iteration. Use `Array.makeBy` for index-based construction, `Array.range` + `Array.findFirst`/`Array.findLast` for searches, and `Array.filterMap`/`Array.flatMap` for transforms.
+- Never cast Schema values with `as Type`. Use callable constructors: `LoginSucceeded({ sessionId })` not `{ _tag: 'LoginSucceeded', sessionId } as Message`.
+- Use `Option` for model fields that may be absent — not empty strings or zero values. `loginError: S.OptionFromSelf(S.String)` not `loginError: S.String` with `''` as the "none" state. Use `Option.match` in views to conditionally render.
+- Use `Array.take` instead of `.slice(0, n)`.
+- Always use `Array.isEmptyArray(foo)` instead of `foo.length === 0`. Use `Array.isNonEmptyArray(foo)` for non-empty checks. When handling both cases, prefer `Array.match`.
+
+### Message Layout
+
+Message definitions follow a strict layout:
+
+```ts
+const NoOp = m('NoOp')
+const ClickedSubmit = m('ClickedSubmit')
+const ChangedEmail = m('ChangedEmail', { value: S.String })
+
+const Message = S.Union(NoOp, ClickedSubmit, ChangedEmail)
+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.
+
+### 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`.
+- 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`.
+- Don't add inline or block comments to explain code — if code needs explanation, refactor for clarity or use better names. Exceptions: section headers (see File Organization above) and TSDoc (`/** ... */`) on public exports.
+- Use capitalized string literals for Schema literal types: `S.Literal('Horizontal', 'Vertical')` not `S.Literal('horizontal', 'vertical')`.
+- Capitalize namespace imports: `import * as Command from './command'` not `import * as command from './command'`.
+- Extract magic numbers to named constants. No raw numeric literals in logic.
+- Never use `T[]` syntax. Always use `Array<T>` or `ReadonlyArray<T>`.
+- Extract repeated inline style values (colors, shadows) to constants.

package/templates/base/ignore

@@ -0,0 +1 @@
+foldkit/