foldkit-plus 0.17.0 → 0.19.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 +241 -28
- package/dist/cli.mjs +10930 -35
- package/dist/cli.mjs.map +1 -1
- package/dist/docs.d.mts +89 -0
- package/dist/docs.d.mts.map +1 -0
- package/dist/docs.mjs +290 -0
- package/dist/docs.mjs.map +1 -0
- package/dist/project.d.mts +45 -0
- package/dist/project.d.mts.map +1 -0
- package/dist/project.mjs +221 -0
- package/dist/project.mjs.map +1 -0
- package/dist/remote/filter.d.mts +1 -0
- package/dist/remote/filter.mjs +2 -0
- package/dist/remote/live.d.mts +1 -0
- package/dist/remote/live.mjs +2 -0
- package/dist/remote/outbox.d.mts +1 -0
- package/dist/remote/outbox.mjs +2 -0
- package/dist/remote/overlay.d.mts +1 -0
- package/dist/remote/overlay.mjs +2 -0
- package/dist/remote/persistence.d.mts +1 -0
- package/dist/remote/persistence.mjs +2 -0
- package/dist/remote/testing.d.mts +1 -0
- package/dist/remote/testing.mjs +2 -0
- package/dist/remote/why.d.mts +1 -0
- package/dist/remote/why.mjs +2 -0
- package/dist/setup.d.mts +45 -7
- package/dist/setup.d.mts.map +1 -1
- package/dist/setup.mjs +168 -25
- package/dist/setup.mjs.map +1 -1
- package/dist/testing/peer.d.mts +8 -0
- package/dist/testing/peer.d.mts.map +1 -0
- package/dist/testing/peer.mjs +19 -0
- package/dist/testing/peer.mjs.map +1 -0
- package/dist/testing/playwright.d.mts +84 -0
- package/dist/testing/playwright.d.mts.map +1 -0
- package/dist/testing/playwright.mjs +327 -0
- package/dist/testing/playwright.mjs.map +1 -0
- package/dist/testing/workers.d.mts +177 -0
- package/dist/testing/workers.d.mts.map +1 -0
- package/dist/testing/workers.mjs +593 -0
- package/dist/testing/workers.mjs.map +1 -0
- package/package.json +126 -59
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,218 @@ 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
|
-
`
|
|
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`, `@foldkit/vite-plugin` | `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`; `Cpu.budget`: fails a test when a route spends more CPU than a budget |
|
|
131
|
+
| `foldkit-plus/testing/playwright` | `playwright` (types) | `Behaviors`: a write shows while it is held at the network, holds still until its answer is drawn, and shows after (`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 bundle's views are branded as `@foldkit/vite-plugin` brands the
|
|
151
|
+
page's build: each function's result is named by its module's path from the
|
|
152
|
+
page's Vite root, which is the folder of `wrangler.toml` unless `pageRoot`
|
|
153
|
+
names another. Foldkit adopts a served element only when that name is the
|
|
154
|
+
one the browser's view gives it, and rebuilds the rest without a word in
|
|
155
|
+
production, so a Worker bundled without the brand had every page it rendered
|
|
156
|
+
rebuilt on hydration. A module an esbuild plugin of `plugins` loads is
|
|
157
|
+
branded too. Where the page root resolves no `foldkit`, there is no Foldkit
|
|
158
|
+
page to match, and the Worker is bundled as written.
|
|
159
|
+
|
|
160
|
+
The Worker's console is printed here as it arrives, each line with Node's
|
|
161
|
+
console method of its level and prefixed `[worker]`, so a 500 shows the error
|
|
162
|
+
behind it with its stack; `console: 'quiet'` keeps the lines for `logs()`
|
|
163
|
+
alone. The lines travel beside the response, not on it, so a test reading
|
|
164
|
+
what one request wrote polls (`expect.poll(() => stack.logs())`).
|
|
165
|
+
|
|
166
|
+
`stack.watch({ onSwap, onRefused, onStopped })` is the dev loop. It
|
|
167
|
+
rebuilds on every change to a file the bundle read, and rereads
|
|
168
|
+
`wrangler.toml` when it changes. Each change is started first on a workerd
|
|
169
|
+
of its own, with fresh storage and its D1 migrated. Only a change that
|
|
170
|
+
starts is swapped in at the same origin, over the same D1, R2 and Durable
|
|
171
|
+
Object storage, and the migrations not yet applied are applied. A change
|
|
172
|
+
that does not build, or builds a Worker that does not start, or a
|
|
173
|
+
configuration the stack refuses, goes to `onRefused`, and the Worker running
|
|
174
|
+
keeps answering. `onStopped` is the rest: a swap that failed after its trial
|
|
175
|
+
started, which takes Wrangler's harness down with its storage.
|
|
176
|
+
|
|
177
|
+
### CPU per request
|
|
178
|
+
|
|
179
|
+
A deployed Worker that spends more CPU on a request than its plan allows
|
|
180
|
+
fails it with error 1102 (the free plan allows 10 ms). Miniflare neither
|
|
181
|
+
enforces that limit nor reports CPU: its tail events say `cpuTime: 0`,
|
|
182
|
+
`limits.cpu_ms` is not applied, and `process.cpuUsage` is not implemented.
|
|
183
|
+
So `Cpu.budget` reads it from outside, and fails a test when a route spends
|
|
184
|
+
more than a budget:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { Cpu } from 'foldkit-plus/testing/workers'
|
|
188
|
+
|
|
189
|
+
const readings = await Cpu.budget(stack.cpu, {
|
|
190
|
+
warm: 20, // ms each request after the first may spend
|
|
191
|
+
cold: 150, // ms the first may spend; unchecked when left out
|
|
192
|
+
routes: {
|
|
193
|
+
home: '/', // a GET of this path
|
|
194
|
+
search: () => new Request(`${stack.origin}/remote`, { method: 'POST', body: '{}' }),
|
|
195
|
+
},
|
|
196
|
+
})
|
|
197
|
+
// [{ route: 'home', status: 200, cold: 31.2, warm: 4.1 }, …]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Each route is asked once, then `runs` (5) times more, one request at a time,
|
|
201
|
+
each response read in full. Over budget, it throws with every route's
|
|
202
|
+
reading; a 5xx throws too, since a failure costs nothing. `cold` is the
|
|
203
|
+
route's first request in the call, so in a fresh stack it is a cold
|
|
204
|
+
isolate's: code not yet optimized, and work kept per isolate (a compiled
|
|
205
|
+
query, Auth) done for the first time.
|
|
206
|
+
|
|
207
|
+
There are two meters:
|
|
208
|
+
|
|
209
|
+
- `stack.cpu` sends each request straight to the Worker and reads the main
|
|
210
|
+
thread of the stack's workerd processes, where JavaScript runs, from the
|
|
211
|
+
operating system (`/proc` on Linux, PowerShell on Windows; other systems
|
|
212
|
+
are refused). It counts the Worker's code and what workerd does on that
|
|
213
|
+
thread around it, D1's SQLite included, which a deployed Worker's CPU time
|
|
214
|
+
leaves out: an empty route reads about 1 ms. V8's helper threads (garbage
|
|
215
|
+
collection, compiling) are left out. Stacks started at the same time in one
|
|
216
|
+
process cannot tell their workerd apart, and their `spent()` refuses.
|
|
217
|
+
- `Cpu.inThread(handler, origin?)` runs a `(request) => Promise<Response>`
|
|
218
|
+
in this process and reads this thread's CPU time: for a handler Node can
|
|
219
|
+
run, such as a page renderer or a Remote server over Node's SQLite, with no
|
|
220
|
+
stack to start.
|
|
221
|
+
|
|
222
|
+
Read budgets on Linux, where both meters count nanoseconds. Windows adds to
|
|
223
|
+
a thread's time a scheduler tick (15.6 ms) at a time, so a reading there is
|
|
224
|
+
only good as a mean of many requests. Choose a budget from Linux readings,
|
|
225
|
+
with room for a slower CI runner: a route several times over it is the
|
|
226
|
+
fault to catch, not noise. The examples hold their main routes to one:
|
|
227
|
+
[examples/cloudflare](https://github.com/doeixd/foldkit-plus/blob/main/examples/cloudflare/test/cpu.test.ts),
|
|
228
|
+
[examples/chirp](https://github.com/doeixd/foldkit-plus/blob/main/examples/chirp/test/cpu.test.ts)
|
|
229
|
+
and
|
|
230
|
+
[examples/foldkit/domains-plus](https://github.com/doeixd/foldkit-plus/blob/main/examples/foldkit/domains-plus/test/cpu.test.ts).
|
|
231
|
+
|
|
232
|
+
<!-- docs-check
|
|
233
|
+
import type { Page } from 'playwright'
|
|
234
|
+
import { expect } from 'vitest'
|
|
235
|
+
declare const page: Page
|
|
236
|
+
-->
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
import { Behaviors } from 'foldkit-plus/testing/playwright'
|
|
240
|
+
|
|
241
|
+
const errors = Behaviors.consoleErrors(page)
|
|
242
|
+
await Behaviors.neverShows(page, {
|
|
243
|
+
text: 'Loading…',
|
|
244
|
+
during: () =>
|
|
245
|
+
Behaviors.optimistic(page, {
|
|
246
|
+
act: () => page.getByRole('button', { name: 'Add' }).click(),
|
|
247
|
+
shows: page.getByRole('button', { name: 'Buy milk', exact: true }),
|
|
248
|
+
}),
|
|
249
|
+
})
|
|
250
|
+
expect(errors()).toEqual([])
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
These check the drawn page over the real network. `optimistic` holds every
|
|
254
|
+
Remote mutation at the network, for `hold` and until it has looked for
|
|
255
|
+
`shows`, and requires `shows` within `within` of the action beginning, so what
|
|
256
|
+
it sees was drawn before any answer however long the action takes (an action
|
|
257
|
+
still running after 10 seconds, or `hold` if longer, is refused: one waiting
|
|
258
|
+
for its own write's answer would wait for good). From then until the write settles, each element `shows` resolves to
|
|
259
|
+
must stay the same node, in the same place in its parent, within 1px of where
|
|
260
|
+
it was drawn, and visible. A prediction that is drawn again, pushed down by a
|
|
261
|
+
line said only while the write is pending, or hidden for a frame fails with
|
|
262
|
+
what moved and when. Settled is evidence: no Remote request of the page in
|
|
263
|
+
flight (an answer can ask for more), then three quiet frames. `stays` names
|
|
264
|
+
what must hold still instead (a `Locator`: the list around a row its answer
|
|
265
|
+
deliberately draws again), or `'shown'` for only "shows after". Writes that
|
|
266
|
+
reach the server another way (a port to a SharedWorker) pass `writes: {
|
|
267
|
+
answered }`, and the page holds them itself; `examples/chirp`'s end-to-end
|
|
268
|
+
test opens its sandbox with `?latency=1500` and reads its outbox. An error the
|
|
269
|
+
page logs while a write settles fails it too. `consoleErrors` lists
|
|
270
|
+
`console.error` and uncaught exceptions, which includes every `error`
|
|
271
|
+
diagnostic the default `Diagnostics` reporter logs. To find which Message makes
|
|
272
|
+
a read blink, `foldkit-plus/remote/testing`'s `Trace` runs `update` and Remote's
|
|
273
|
+
Subscriptions without a browser and records every Model.
|
|
274
|
+
[examples/cloudflare](https://github.com/doeixd/foldkit-plus/tree/main/examples/cloudflare)
|
|
275
|
+
uses both subpaths.
|
|
276
|
+
|
|
84
277
|
## Versions
|
|
85
278
|
|
|
86
|
-
`effect` and `foldkit` are peers: this release targets Effect 4 (`^4.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
279
|
+
`effect` and `foldkit` are peers: this release targets Effect 4.1 (`^4.1.0`)
|
|
280
|
+
and Foldkit `0.170`, and `setup` installs the Foldkit and the Effect this
|
|
281
|
+
repository tests (`package.json`'s `setup` field). Foldkit and its Vite plugin
|
|
282
|
+
take one Effect minor (`~4.1.0`), and each `@effect/*` release peers on an
|
|
283
|
+
`effect` at least its own, so `setup` first has the project pin every Effect
|
|
284
|
+
package to the tested one, which keeps one copy of each:
|
|
285
|
+
|
|
286
|
+
- npm: `overrides`, and the project's own Effect dependencies set to the same
|
|
287
|
+
release, since npm overrides a direct dependency only where the project
|
|
288
|
+
names that version;
|
|
289
|
+
- pnpm: `overrides` with `peerDependencyRules`, at the workspace root, the only
|
|
290
|
+
place pnpm reads them (its `pnpm-workspace.yaml`, or its `package.json` where
|
|
291
|
+
that already holds a `pnpm` field);
|
|
292
|
+
- Yarn: `resolutions`; Bun: `overrides`.
|
|
293
|
+
|
|
294
|
+
npm keeps a package its lockfile holds rather than move it down to an
|
|
295
|
+
override, and a scaffold locks the newest Effect patch under
|
|
296
|
+
`@foldkit/vite-plugin`. Where `package-lock.json` already holds a later patch
|
|
297
|
+
of the tested minor, `setup` pins that one instead.
|
|
298
|
+
|
|
299
|
+
That also holds `foldkit-durable`'s `@effect/sql-sqlite-node`, whose every
|
|
300
|
+
release peers on an `effect` at least its own version. Each release of
|
|
301
|
+
`foldkit-plus` pins the release of every package it brings, so the set is one
|
|
302
|
+
tested combination; the
|
|
90
303
|
[release matrix](https://github.com/doeixd/foldkit-plus/blob/main/docs/releases.md)
|
|
91
304
|
lists them.
|
|
92
305
|
|