foldkit-plus 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,28 +3,6 @@
3
3
  Every Foldkit Plus package in one install, and a setup command for your coding
4
4
  agent.
5
5
 
6
- ```bash
7
- npx foldkit-plus setup
8
- ```
9
-
10
- Tell your agent to run that in your project. It prints, for that project, how to
11
- install Effect, Foldkit and Foldkit Plus with the package manager the project
12
- uses, how to add the agent skill, and which package does which job. It reads
13
- your `package.json` first and says when `effect` or `foldkit` is missing or at a
14
- version this release does not support. It writes nothing; the agent runs what it
15
- says.
16
-
17
- For a new application, run it in an empty folder. With no `package.json` it
18
- sends the agent to the skill's
19
- [greenfield guide](https://github.com/doeixd/foldkit-plus/blob/main/skills/foldkit-plus/references/greenfield.md):
20
- ask about the goals, the look (a theme designed at
21
- [/create](https://foldkit-plus.pages.dev/create)) and the domain first, record
22
- the answers in the project,
23
- map them to these packages with you, plan the architecture, performance, SEO,
24
- testing, CI and deployment, and build once you agree. It prints the
25
- `create-foldkit-app` command, at the release that installs this release's
26
- Foldkit, for when it is time to scaffold.
27
-
28
6
  ## What it is
29
7
 
30
8
  [Foldkit Plus](https://foldkit-plus.pages.dev) is a family of packages that
@@ -41,7 +19,45 @@ foldkit-mixins/theme -> foldkit-plus/mixins/theme
41
19
  ```
42
20
 
43
21
  A subpath is the package itself, re-exported: `foldkit-plus/remote`'s `Remote`
44
- is `foldkit-remote`'s, so the two can be mixed in one application.
22
+ is `foldkit-remote`'s, so the two can be mixed in one application. This package
23
+ owns no state and adds no runtime API of its own: what each package owns is in
24
+ its own guide. What it adds is the `setup` and `docs` commands, and two subpaths
25
+ for testing a running application.
26
+
27
+ ## Setup
28
+
29
+ ```bash
30
+ npx --legacy-peer-deps foldkit-plus setup
31
+ ```
32
+
33
+ Tell your agent to run that in your project. It writes nothing: it prints, for
34
+ that project, what the agent should run, in order:
35
+
36
+ 1. **Check the project.** It reads your `package.json` and says when `effect`
37
+ or `foldkit` is missing or at a version this release does not support. When
38
+ no `.gitattributes` applies to the project, it gives one that keeps text
39
+ files LF (`* text=auto eol=lf`), so a Windows checkout does not warn of
40
+ every file; one the project has is left as it is.
41
+ 2. **Install** Effect, Foldkit and Foldkit Plus with the package manager the
42
+ project uses, after the version pins described under [Versions](#versions),
43
+ and the command that adds each [adapter](#what-it-does-not-install-adapters).
44
+ 3. **Add the agent skill**, and paste its `AGENTS.md` block into the project.
45
+ 4. **Import**: which package does which job.
46
+
47
+ `--legacy-peer-deps` only stops npx installing the package's peers beside it,
48
+ which the CLI never reads (it carries everything it runs on): npx adds a newer
49
+ `foldkit-plus` to the tree an older one left in its cache, and their peers'
50
+ Foldkit versions clash (`ERESOLVE`) where none is needed.
51
+
52
+ For a new application, run it in an empty folder. With no `package.json` it
53
+ sends the agent to the skill's
54
+ [greenfield guide](https://github.com/doeixd/foldkit-plus/blob/main/skills/foldkit-plus/references/greenfield.md):
55
+ ask about the goals, the look (a theme designed at
56
+ [/create](https://foldkit-plus.pages.dev/create)) and the domain first, record
57
+ the answers in the project, map them to these packages with you, plan the
58
+ architecture, performance, SEO, testing, CI and deployment, and build once you
59
+ agree. It prints the `create-foldkit-app` command, at the release that installs
60
+ this release's Foldkit, for when it is time to scaffold.
45
61
 
46
62
  ## Import
47
63
 
@@ -72,21 +88,132 @@ once you add it with its library:
72
88
  | `foldkit-react-codegen` | `typescript` | Views compiled to React TSX |
73
89
  | `foldkit-remote-drizzle` | `drizzle-orm` | Remote reads answered with Drizzle |
74
90
  | `foldkit-cms-drizzle` | `drizzle-orm` | The CMS's server on Drizzle |
91
+ | `foldkit-auth` | `@yielded/auth` | Sign-in and sessions with Yielded Auth |
75
92
  | `foldkit-mixins-ui` | `@foldkit/ui` | `@foldkit/ui` components styled through slots |
76
93
  | `foldkit-richtext-code-shiki` | `shiki` | Code blocks highlighted with Shiki |
77
94
  | `foldkit-agent-native` | `@agent-native/core` | Agents through Agent Native |
78
95
 
79
- `npx foldkit-plus setup` lists them with the command that adds each.
96
+ `setup` lists them with the command that adds each, at the library version the
97
+ adapter peers on.
80
98
 
81
99
  `foldkit-media` is installed, but two of its subpaths need a library that is not:
82
100
  `foldkit-plus/media/sharp` needs `sharp`, and `foldkit-plus/media/unpic` needs `unpic`.
83
101
 
102
+ ## Docs for the versions you have
103
+
104
+ ```bash
105
+ npx foldkit-plus docs Data.preload # a symbol: its declaration and its sections
106
+ npx foldkit-plus docs "optimistic delete" # words: the three best sections
107
+ npx foldkit-plus docs --list remote # one topic's headings, with line numbers
108
+ ```
109
+
110
+ `docs` answers from what is installed in the project it runs in, so it
111
+ describes the versions the application has, not `main`. It reads the README
112
+ of each Foldkit Plus package that an import from the project would load (one
113
+ the project names from its own folder; the rest from beside `foldkit-plus`),
114
+ the `foldkit-plus` skill if it is installed in a dot-folder's `skills/` (the
115
+ project's, its repository's, or the home folder's), and for a symbol the
116
+ package's `.d.mts`. Each section comes with its file and line, so the rest is
117
+ one read away. Nothing is indexed ahead of time and nothing is fetched.
118
+ `--json` prints the same for a program. A query that matches nothing, a
119
+ project with no Foldkit Plus package, or one whose `package.json` names a
120
+ package that is not installed exits 1 and says which.
121
+
122
+ ## Testing a running application
123
+
124
+ Two subpaths of this package's own drive the tools an application tests with.
125
+ Those tools are optional peers too: add them as dev dependencies, and a
126
+ subpath that needs one it cannot find says which.
127
+
128
+ | Subpath | Needs | For |
129
+ | --- | --- | --- |
130
+ | `foldkit-plus/testing/workers` | `wrangler`, `esbuild` | `Stack.start`: the Worker on a local workerd, configured by its own `wrangler.toml`, with fresh migrated D1 per stack; `Stack.writeBundle`: the same bundle where `main` says, for `wrangler deploy` |
131
+ | `foldkit-plus/testing/playwright` | `playwright` (types) | `Behaviors`: a write shows while it is held at the network and after its answer (`optimistic`), a text never shows during some steps, even for one frame (`neverShows`), and the page's errors (`consoleErrors`) |
132
+
133
+ <!-- docs-check
134
+ interface Env { readonly ORIGIN: string }
135
+ -->
136
+
137
+ ```ts
138
+ import { Stack } from 'foldkit-plus/testing/workers'
139
+
140
+ const stack = await Stack.start<Env>({
141
+ wrangler: 'wrangler.toml', // bindings, compatibility date and flags, D1 migrations
142
+ entry: 'src/worker.ts', // bundled into what `main` names; `no_bundle = true`
143
+ vars: origin => ({ ORIGIN: origin }), // or a plain record; a function is given the stack's origin
144
+ })
145
+ await fetch(stack.origin)
146
+ stack.logs() // what the Worker wrote to its console since the last call; also printed as it arrives
147
+ await stack.stop()
148
+ ```
149
+
150
+ The Worker's console is printed here as it arrives, each line with Node's
151
+ console method of its level and prefixed `[worker]`, so a 500 shows the error
152
+ behind it with its stack; `console: 'quiet'` keeps the lines for `logs()`
153
+ alone. The lines travel beside the response, not on it, so a test reading
154
+ what one request wrote polls (`expect.poll(() => stack.logs())`).
155
+
156
+ `stack.watch({ onSwap, onRefused, onStopped })` is the dev loop. It
157
+ rebuilds on every change to a file the bundle read, and rereads
158
+ `wrangler.toml` when it changes. Each change is started first on a workerd
159
+ of its own, with fresh storage and its D1 migrated. Only a change that
160
+ starts is swapped in at the same origin, over the same D1, R2 and Durable
161
+ Object storage, and the migrations not yet applied are applied. A change
162
+ that does not build, or builds a Worker that does not start, or a
163
+ configuration the stack refuses, goes to `onRefused`, and the Worker running
164
+ keeps answering. `onStopped` is the rest: a swap that failed after its trial
165
+ started, which takes Wrangler's harness down with its storage.
166
+
167
+ <!-- docs-check
168
+ import type { Page } from 'playwright'
169
+ import { expect } from 'vitest'
170
+ declare const page: Page
171
+ -->
172
+
173
+ ```ts
174
+ import { Behaviors } from 'foldkit-plus/testing/playwright'
175
+
176
+ const errors = Behaviors.consoleErrors(page)
177
+ await Behaviors.neverShows(page, {
178
+ text: 'Loading…',
179
+ during: () =>
180
+ Behaviors.optimistic(page, {
181
+ act: () => page.getByRole('button', { name: 'Add' }).click(),
182
+ shows: page.getByRole('button', { name: 'Buy milk', exact: true }),
183
+ }),
184
+ })
185
+ expect(errors()).toEqual([])
186
+ ```
187
+
188
+ These check the drawn page over the real network. `consoleErrors` lists
189
+ `console.error` and uncaught exceptions, which includes every `error`
190
+ diagnostic the default `Diagnostics` reporter logs. To find which Message makes
191
+ a read blink, `foldkit-plus/remote/testing`'s `Trace` runs `update` and Remote's
192
+ Subscriptions without a browser and records every Model.
193
+ [examples/cloudflare](https://github.com/doeixd/foldkit-plus/tree/main/examples/cloudflare)
194
+ uses both subpaths.
195
+
84
196
  ## Versions
85
197
 
86
- `effect` and `foldkit` are peers: this release targets Effect 4 (`^4.0.0`,
87
- tested on 4.0.4) and Foldkit `0.168`, and `setup` installs the Effect that
88
- Foldkit names (`4.0.0`). Each release of `foldkit-plus` pins the release of every
89
- package it brings, so the set is one tested combination; the
198
+ `effect` and `foldkit` are peers: this release targets Effect 4.1 (`^4.1.0`)
199
+ and Foldkit `0.170`, and `setup` installs the Foldkit and the Effect this
200
+ repository tests (`package.json`'s `setup` field). Foldkit and its Vite plugin
201
+ take one Effect minor (`~4.1.0`), and each `@effect/*` release peers on an
202
+ `effect` at least its own, so `setup` first has the project pin every Effect
203
+ package to the tested one, which keeps one copy of each:
204
+
205
+ - npm: `overrides`, and the project's own Effect dependencies set to the same
206
+ release, since npm overrides a direct dependency only where the project
207
+ names that version;
208
+ - pnpm: `overrides` with `peerDependencyRules`, at the workspace root, the only
209
+ place pnpm reads them (its `pnpm-workspace.yaml`, or its `package.json` where
210
+ that already holds a `pnpm` field);
211
+ - Yarn: `resolutions`; Bun: `overrides`.
212
+
213
+ That also holds `foldkit-durable`'s `@effect/sql-sqlite-node`, whose every
214
+ release peers on an `effect` at least its own version. Each release of
215
+ `foldkit-plus` pins the release of every package it brings, so the set is one
216
+ tested combination; the
90
217
  [release matrix](https://github.com/doeixd/foldkit-plus/blob/main/docs/releases.md)
91
218
  lists them.
92
219