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 +155 -28
- package/dist/cli.mjs +10389 -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 +205 -0
- package/dist/project.mjs.map +1 -0
- package/dist/remote/testing.d.mts +1 -0
- package/dist/remote/testing.mjs +2 -0
- package/dist/setup.d.mts +35 -7
- package/dist/setup.d.mts.map +1 -1
- package/dist/setup.mjs +148 -24
- 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 +49 -0
- package/dist/testing/playwright.d.mts.map +1 -0
- package/dist/testing/playwright.mjs +171 -0
- package/dist/testing/playwright.mjs.map +1 -0
- package/dist/testing/workers.d.mts +103 -0
- package/dist/testing/workers.d.mts.map +1 -0
- package/dist/testing/workers.mjs +320 -0
- package/dist/testing/workers.mjs.map +1 -0
- package/package.json +89 -58
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
|
-
`
|
|
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.
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
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
|
|