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.
Files changed (42) hide show
  1. package/README.md +241 -28
  2. package/dist/cli.mjs +10930 -35
  3. package/dist/cli.mjs.map +1 -1
  4. package/dist/docs.d.mts +89 -0
  5. package/dist/docs.d.mts.map +1 -0
  6. package/dist/docs.mjs +290 -0
  7. package/dist/docs.mjs.map +1 -0
  8. package/dist/project.d.mts +45 -0
  9. package/dist/project.d.mts.map +1 -0
  10. package/dist/project.mjs +221 -0
  11. package/dist/project.mjs.map +1 -0
  12. package/dist/remote/filter.d.mts +1 -0
  13. package/dist/remote/filter.mjs +2 -0
  14. package/dist/remote/live.d.mts +1 -0
  15. package/dist/remote/live.mjs +2 -0
  16. package/dist/remote/outbox.d.mts +1 -0
  17. package/dist/remote/outbox.mjs +2 -0
  18. package/dist/remote/overlay.d.mts +1 -0
  19. package/dist/remote/overlay.mjs +2 -0
  20. package/dist/remote/persistence.d.mts +1 -0
  21. package/dist/remote/persistence.mjs +2 -0
  22. package/dist/remote/testing.d.mts +1 -0
  23. package/dist/remote/testing.mjs +2 -0
  24. package/dist/remote/why.d.mts +1 -0
  25. package/dist/remote/why.mjs +2 -0
  26. package/dist/setup.d.mts +45 -7
  27. package/dist/setup.d.mts.map +1 -1
  28. package/dist/setup.mjs +168 -25
  29. package/dist/setup.mjs.map +1 -1
  30. package/dist/testing/peer.d.mts +8 -0
  31. package/dist/testing/peer.d.mts.map +1 -0
  32. package/dist/testing/peer.mjs +19 -0
  33. package/dist/testing/peer.mjs.map +1 -0
  34. package/dist/testing/playwright.d.mts +84 -0
  35. package/dist/testing/playwright.d.mts.map +1 -0
  36. package/dist/testing/playwright.mjs +327 -0
  37. package/dist/testing/playwright.mjs.map +1 -0
  38. package/dist/testing/workers.d.mts +177 -0
  39. package/dist/testing/workers.d.mts.map +1 -0
  40. package/dist/testing/workers.mjs +593 -0
  41. package/dist/testing/workers.mjs.map +1 -0
  42. package/package.json +126 -59
package/dist/setup.mjs CHANGED
@@ -9,11 +9,13 @@ const SITE = "https://foldkit-plus.pages.dev";
9
9
  const REPOSITORY = "https://github.com/doeixd/foldkit-plus";
10
10
  /**
11
11
  * The `create-foldkit-app` release whose templates pin the Foldkit this
12
- * release needs (0.39.1 installs `foldkit` 0.168.0). A release that moves
13
- * the `foldkit` peer moves this with it.
12
+ * release needs (0.41.0 installs `foldkit`, `@foldkit/ui` and `@foldkit/devtools`
13
+ * 0.170.0, `@foldkit/vite-plugin` 0.29.0 and `effect` 4.1.0). A release that
14
+ * moves the `foldkit` peer moves this with it.
14
15
  */
15
- const SCAFFOLDER = "create-foldkit-app@0.39.1";
16
+ const SCAFFOLDER = "create-foldkit-app@0.41.0";
16
17
  const GREENFIELD = `${REPOSITORY}/blob/main/skills/foldkit-plus/references/greenfield.md`;
18
+ const AGENTS_BLOCK = `${REPOSITORY}/blob/main/skills/foldkit-plus/references/agents-md.md`;
17
19
  /** What each job needs, where to import it from, and where it is explained. */
18
20
  const jobs = [
19
21
  {
@@ -153,52 +155,148 @@ const jobs = [
153
155
  ];
154
156
  /**
155
157
  * The packages `foldkit-plus` does not install, since each needs a library of
156
- * its own, and that library. `test/setup.test.ts` holds this to the manifest.
158
+ * its own, and that library at the range the adapter peers on: a manager
159
+ * given a bare name installs the `latest` tag, which for `@yielded/auth` is a
160
+ * beta older than the one `foldkit-auth` names. `test/generated.test.ts`
161
+ * holds this to the manifests.
157
162
  */
158
163
  const adapters = [
159
164
  {
160
165
  name: "foldkit-agent-native",
161
- libraries: ["@agent-native/core"],
166
+ libraries: ["@agent-native/core@0.214.0"],
162
167
  when: "agents through Agent Native"
163
168
  },
164
169
  {
165
170
  name: "foldkit-auth",
166
- libraries: ["@yielded/auth"],
171
+ libraries: ["@yielded/auth@0.1.0-beta.47"],
167
172
  when: "sign-in and sessions with Yielded Auth"
168
173
  },
169
174
  {
170
175
  name: "foldkit-cms-drizzle",
171
- libraries: ["drizzle-orm"],
176
+ libraries: ["drizzle-orm@1.0.0-rc.5"],
172
177
  when: "the CMS's server on Drizzle"
173
178
  },
174
179
  {
175
180
  name: "foldkit-mixins-ui",
176
- libraries: ["@foldkit/ui"],
181
+ libraries: ["@foldkit/ui@^0.170.0"],
177
182
  when: "styling `@foldkit/ui` components through slots"
178
183
  },
179
184
  {
180
185
  name: "foldkit-react",
181
- libraries: ["react", "react-dom"],
186
+ libraries: ["react@^19.0.0", "react-dom@^19.0.0"],
182
187
  when: "React interop"
183
188
  },
184
189
  {
185
190
  name: "foldkit-react-codegen",
186
- libraries: ["typescript"],
191
+ libraries: ["typescript@>=5.7.2 <7"],
187
192
  when: "compiling Foldkit views to React TSX (a dev dependency)"
188
193
  },
189
194
  {
190
195
  name: "foldkit-remote-drizzle",
191
- libraries: ["drizzle-orm"],
196
+ libraries: ["drizzle-orm@1.0.0-rc.5"],
192
197
  when: "answering Remote reads with Drizzle"
193
198
  },
194
199
  {
195
200
  name: "foldkit-richtext-code-shiki",
196
- libraries: ["shiki"],
201
+ libraries: ["shiki@^4.4.3"],
197
202
  when: "highlighting code blocks with Shiki"
198
203
  }
199
204
  ];
200
- /** The command that adds `packages` with `manager`. */
201
- const addCommand = (manager, packages) => `${manager} ${manager === "npm" ? "install" : "add"} ${packages.join(" ")}`;
205
+ /**
206
+ * The Effect packages an application meets that something names at a version
207
+ * of its own: Foldkit's peers and its Vite plugin's dependencies name one
208
+ * minor (`~4.1.0`), and each `@effect/*` package peers on an `effect` at least
209
+ * its own version. Setup holds all of them at the Effect this release is
210
+ * tested on, as `pnpm-workspace.yaml` does here (`test/generated.test.ts`
211
+ * keeps the two lists together).
212
+ */
213
+ const effectPackages = [
214
+ "effect",
215
+ "@effect/platform-browser",
216
+ "@effect/platform-node",
217
+ "@effect/platform-node-shared",
218
+ "@effect/sql-sqlite-node"
219
+ ];
220
+ const releaseOf = (version) => /^(\d+)\.(\d+)\.(\d+)$/.exec(version)?.slice(1).map(Number) ?? [];
221
+ /**
222
+ * The Effect release setup pins: the one this release is tested on, or a later
223
+ * patch of the same minor that the project's lockfile already holds. npm keeps
224
+ * a locked package that an override contradicts rather than move it down, so
225
+ * pinning 4.1.0 left the 4.1.1 that `@foldkit/vite-plugin`'s `~4.1.0` had
226
+ * locked under it, which `npm ls` calls invalid.
227
+ */
228
+ const effectRelease = (tested, locked) => {
229
+ const [major, minor] = releaseOf(tested);
230
+ return locked.reduce((newest, version) => {
231
+ const [lockedMajor, lockedMinor, patch = -1] = releaseOf(version);
232
+ return lockedMajor === major && lockedMinor === minor && patch > (releaseOf(newest)[2] ?? -1) ? version : newest;
233
+ }, tested);
234
+ };
235
+ /** A YAML key, quoted where `@` would start something else. */
236
+ const yamlKey = (key) => key.startsWith("@") ? `'${key}'` : key;
237
+ /**
238
+ * The settings that hold every Effect package at `effect`, to merge into the
239
+ * file the manager reads them from. npm applies an override to a package the
240
+ * project depends on only where the project names that same version, so its
241
+ * block sets those dependencies too (a `$name` reference would follow them,
242
+ * but npm 10 cannot resolve a scoped one); pnpm reads them only at a
243
+ * workspace's root.
244
+ */
245
+ const pinsOf = (manager, effect, direct, pnpmSettings) => {
246
+ const pins = Object.fromEntries(effectPackages.map((name) => [name, effect]));
247
+ const allowedVersions = {
248
+ effect,
249
+ "@effect/platform-browser": effect
250
+ };
251
+ if (manager === "pnpm" && pnpmSettings.file === "pnpm-workspace.yaml") {
252
+ const lines = (entries, indent) => Object.entries(entries).map(([name, version]) => `${indent}${yamlKey(name)}: ${version}`);
253
+ return {
254
+ file: `${pnpmSettings.folder}/pnpm-workspace.yaml`,
255
+ language: "yaml",
256
+ text: [
257
+ "overrides:",
258
+ ...lines(pins, " "),
259
+ "peerDependencyRules:",
260
+ " allowedVersions:",
261
+ ...lines(allowedVersions, " ")
262
+ ].join("\n")
263
+ };
264
+ }
265
+ const fields = {
266
+ npm: {
267
+ dependencies: Object.fromEntries(effectPackages.filter((name) => direct.has(name)).map((name) => [name, effect])),
268
+ overrides: pins
269
+ },
270
+ pnpm: { pnpm: {
271
+ overrides: pins,
272
+ peerDependencyRules: { allowedVersions }
273
+ } },
274
+ yarn: { resolutions: pins },
275
+ bun: { overrides: pins }
276
+ }[manager];
277
+ return {
278
+ file: manager === "pnpm" && pnpmSettings.folder !== "." ? `${pnpmSettings.folder}/package.json` : "package.json",
279
+ language: "json",
280
+ text: JSON.stringify(fields, null, 2)
281
+ };
282
+ };
283
+ /** Why `manager` needs the pins, after "first merge this into `package.json`". */
284
+ const pinsWhy = {
285
+ npm: "npm refuses a peer it does not match, and `overrides` lets one in without turning every peer check off; it overrides a dependency of the project only at the version the project names, so the block sets those too",
286
+ pnpm: "`overrides` sets the version, and `peerDependencyRules` lets Foldkit's exact peers accept it",
287
+ yarn: "`resolutions` sets the version; Yarn warns of Foldkit's exact peers, and installs",
288
+ bun: "`overrides` sets the version; Bun warns of Foldkit's exact peers, and installs"
289
+ };
290
+ /**
291
+ * The command that adds `packages` with `manager`, at exactly the versions
292
+ * named when `exact`. A range a shell would read (`^`, `>`, a space) is quoted.
293
+ */
294
+ const addCommand = (manager, packages, exact = false) => [
295
+ manager,
296
+ manager === "npm" ? "install" : "add",
297
+ ...exact ? [manager === "npm" || manager === "pnpm" ? "--save-exact" : "--exact"] : [],
298
+ ...packages.map((spec) => /^[\w@/.-]+$/.test(spec) ? spec : `"${spec}"`)
299
+ ].join(" ");
202
300
  /** The major version a range asks for: `^4.0.0`, `~4.1`, `4.0.0-beta.1` all ask for 4. */
203
301
  const majorOf = (range) => Option.fromNullishOr(/(\d+)/.exec(range)?.[1]).pipe(Option.map(Number));
204
302
  /** What the project has of a library against what this release needs, as a line to act on. */
@@ -209,31 +307,63 @@ const finding = (project, library, wanted) => Option.match(Option.fromNullishOr(
209
307
  }
210
308
  });
211
309
  const setupGuide = ({ project, manager, versions }) => {
310
+ const listed = Option.match(project, {
311
+ onNone: () => [],
312
+ onSome: (found) => effectPackages.filter((name) => found.versions[name] !== void 0)
313
+ });
314
+ const moved = /* @__PURE__ */ new Set([
315
+ "effect",
316
+ "@effect/platform-browser",
317
+ ...listed
318
+ ]);
319
+ const effect = effectRelease(versions.effect, Option.match(project, {
320
+ onNone: () => [],
321
+ onSome: (found) => found.locked
322
+ }));
323
+ const pins = pinsOf(manager, effect, moved, Option.match(project, {
324
+ onNone: () => ({
325
+ folder: ".",
326
+ file: "package.json"
327
+ }),
328
+ onSome: (found) => found.pnpmSettings
329
+ }));
330
+ const uiPeer = Option.exists(project, (found) => found.versions["@foldkit/devtools"] !== void 0 && found.versions["@foldkit/ui"] === void 0);
212
331
  const install = addCommand(manager, [
213
- `effect@${versions.effect}`,
332
+ ...manager === "npm" ? [] : effectPackages.filter((name) => moved.has(name)).map((name) => `${name}@${effect}`),
214
333
  `foldkit@${versions.foldkit}`,
215
- `@effect/platform-browser@${versions.effect}`,
334
+ ...uiPeer ? [`@foldkit/ui@${versions.foldkit}`] : [],
216
335
  "foldkit-plus"
217
- ]);
336
+ ], true);
218
337
  const check = Option.match(project, {
219
338
  onNone: () => [
220
339
  "There is no `package.json` here: this is a new application. Do not scaffold yet. Follow the greenfield guide, which asks the user about the goals, the look and the domain before any code:",
221
340
  "",
222
341
  `- ${GREENFIELD} (in the skill of step 3, \`references/greenfield.md\`)`,
223
342
  "",
224
- "When its first step has a name and a rendering mode, it scaffolds with:",
343
+ `When its first step has a name and a rendering mode, it scaffolds with the command for that mode; \`--example\` is for spa alone, and an ssg or ssr scaffold refuses it${manager === "npm" ? ". An ssg scaffold names `@foldkit/devtools` but not `@foldkit/ui`, its peer, so npm takes the newest `@foldkit/ui`, and refuses the install once that one needs a newer Effect than the scaffold's: `--force` lets it install with a warning, and step 2 replaces that `@foldkit/ui` with the one at the scaffold's Foldkit release (`--legacy-peer-deps` would also drop peers the scaffolder itself needs)" : ""}:`,
225
344
  "",
226
345
  "```bash",
227
- `npx ${SCAFFOLDER} --name <name> --rendering <spa|ssg|ssr> --example counter --package-manager ${manager}`,
346
+ `npx ${SCAFFOLDER} --name <name> --rendering spa --example counter --package-manager ${manager}`,
347
+ `npx ${manager === "npm" ? "--force " : ""}${SCAFFOLDER} --name <name> --rendering ssg --package-manager ${manager}`,
348
+ `npx ${SCAFFOLDER} --name <name> --rendering ssr --package-manager ${manager}`,
228
349
  "```",
229
350
  "",
230
- "Then run `npx foldkit-plus setup` again in the new folder and continue from step 2."
351
+ "Then run `npx --legacy-peer-deps foldkit-plus setup` again in the new folder and continue from step 2."
231
352
  ],
232
353
  onSome: (found) => [
233
354
  `This is \`${found.name}\`, installed with ${manager}.`,
234
355
  "",
235
- finding(found, "effect", versions.effect),
236
- finding(found, "foldkit", versions.foldkit)
356
+ finding(found, "effect", effect),
357
+ finding(found, "foldkit", versions.foldkit),
358
+ ...uiPeer ? [`- \`@foldkit/devtools\` peers on \`@foldkit/ui\`, which the project does not name: step 2 adds \`@foldkit/ui@${versions.foldkit}\`, since a manager left to choose takes the newest, which may need a newer Effect.`] : [],
359
+ ...found.gitattributes ? ["- `.gitattributes` is there: leave it as it is."] : [
360
+ "- There is no `.gitattributes`. Write one at the repository's root (beside `package.json` if this is not yet a repository), so Git keeps the LF line endings the formatter writes and `git add` on Windows does not warn of every file:",
361
+ "",
362
+ "```gitattributes",
363
+ "* text=auto eol=lf",
364
+ "*.wasm binary",
365
+ "```"
366
+ ]
237
367
  ]
238
368
  });
239
369
  return [
@@ -253,6 +383,14 @@ const setupGuide = ({ project, manager, versions }) => {
253
383
  "",
254
384
  "## 2. Install",
255
385
  "",
386
+ `Foldkit and its tooling take one Effect minor, and Foldkit Plus is tested on ${versions.effect}.${effect === versions.effect ? "" : ` The lockfile already holds ${effect}, a later patch of that minor, and npm keeps a locked package rather than move it down to an override, so the pins name ${effect}.`} To install one copy of each Effect package, at that release, first merge this into \`${pins.file}\`, keeping what it holds (${pinsWhy[manager]}${pins.file === "package.json" ? "" : "; pnpm reads them only at the workspace root"}):`,
387
+ "",
388
+ `\`\`\`${pins.language}`,
389
+ pins.text,
390
+ "```",
391
+ "",
392
+ "Then install:",
393
+ "",
256
394
  "```bash",
257
395
  install,
258
396
  "```",
@@ -267,10 +405,15 @@ const setupGuide = ({ project, manager, versions }) => {
267
405
  "npx skills add doeixd/foldkit-plus --skill foldkit-plus",
268
406
  "```",
269
407
  "",
270
- "It teaches you which package owns which kind of state, when to reach for each, and a working example of each. Read its `SKILL.md` before writing code with Foldkit Plus, and the reference for the package at hand before changing it.",
408
+ "It teaches you which package owns which kind of state, when to reach for each, and a working example of each. Read its `SKILL.md` before writing code with Foldkit Plus, and the reference for the package at hand before changing it. To look one symbol or topic up in the docs of the versions installed here, run `npx foldkit-plus docs <symbol or words>` (`--list` for what there is).",
271
409
  ...Option.match(project, {
272
410
  onNone: () => [],
273
- onSome: () => ["", `Building a new application rather than extending one? Follow its \`references/greenfield.md\` (${GREENFIELD}): goals and the look, then the domain with the user, recorded in the project and mapped to these packages, then a plan for architecture, performance, SEO, testing, CI and deployment, before implementing.`]
411
+ onSome: () => [
412
+ "",
413
+ `Paste the block in its \`references/agents-md.md\` (${AGENTS_BLOCK}) under Project Notes in the project's \`AGENTS.md\`: the house rules and known traps for an application on these packages.`,
414
+ "",
415
+ `Building a new application rather than extending one? Follow its \`references/greenfield.md\` (${GREENFIELD}): goals and the look, then the domain with the user, recorded in the project and mapped to these packages, then a plan for architecture, performance, SEO, testing, CI and deployment, before implementing.`
416
+ ]
274
417
  }),
275
418
  "",
276
419
  "## 4. Import",
@@ -302,6 +445,6 @@ const setupGuide = ({ project, manager, versions }) => {
302
445
  ""
303
446
  ].join("\n");
304
447
  };
305
- export { SCAFFOLDER, adapters, addCommand, jobs, setupGuide };
448
+ export { SCAFFOLDER, adapters, addCommand, effectPackages, effectRelease, jobs, setupGuide };
306
449
 
307
450
  //# sourceMappingURL=setup.mjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"setup.mjs","names":[],"sources":["../src/setup.ts"],"sourcesContent":["/**\n * What `npx foldkit-plus setup` prints: instructions a coding agent can follow\n * in order, for the project it is run in. Pure: the CLI reads the project and\n * this package's manifest and passes them in, so a test can give any project.\n */\nimport { Option } from 'effect'\n\nexport type Manager = 'pnpm' | 'npm' | 'yarn' | 'bun'\n\n/** What the project's `package.json` says about the libraries Foldkit Plus needs. */\nexport interface Project {\n readonly name: string\n /** Each named library's version range, from any dependency field. */\n readonly versions: Readonly<Record<string, string>>\n}\n\n/** The versions this release is built and tested against, from its own manifest. */\nexport interface Versions {\n readonly plus: string\n readonly effect: string\n readonly foldkit: string\n}\n\nexport interface SetupInput {\n readonly project: Option.Option<Project>\n readonly manager: Manager\n readonly versions: Versions\n}\n\nconst SITE = 'https://foldkit-plus.pages.dev'\nconst REPOSITORY = 'https://github.com/doeixd/foldkit-plus'\n\n/**\n * The `create-foldkit-app` release whose templates pin the Foldkit this\n * release needs (0.39.1 installs `foldkit` 0.168.0). A release that moves\n * the `foldkit` peer moves this with it.\n */\nexport const SCAFFOLDER = 'create-foldkit-app@0.39.1'\n\nconst GREENFIELD = `${REPOSITORY}/blob/main/skills/foldkit-plus/references/greenfield.md`\n\n/** What each job needs, where to import it from, and where it is explained. */\nexport const jobs: ReadonlyArray<{\n readonly job: string\n readonly imports: ReadonlyArray<string>\n readonly guide: string\n}> = [\n {\n job: 'Name what a feature may read and which Messages it may send',\n imports: ['surface', 'metadata'],\n guide: 'surface',\n },\n {\n job: 'A reusable Submodel placed several times, every part wired',\n imports: ['bundle', 'bundle-surface'],\n guide: 'bundle',\n },\n {\n job: 'Restyle or extend views from outside, through typed slots',\n imports: ['mixins', 'mixins-surface', 'mixins-ui'],\n guide: 'mixins',\n },\n {\n job: 'Media queries, timers, sockets, clipboard, undo history',\n imports: ['primitives'],\n guide: 'primitives',\n },\n {\n job: 'Declare the domain once: entities, relations, queries',\n imports: ['entity'],\n guide: 'entity',\n },\n {\n job: 'Server-owned data in the Model: queries, mutations, live updates',\n imports: ['remote', 'remote-server', 'remote-drizzle'],\n guide: 'remote',\n },\n {\n job: 'Edits that survive offline and converge across devices',\n imports: ['sync', 'durable'],\n guide: 'sync',\n },\n { job: 'Who may do what, enforced on every seam', imports: ['guard'], guide: 'guard' },\n {\n job: 'Who is signed in: a Yielded Auth session as the principal',\n imports: ['auth'],\n guide: 'auth',\n },\n {\n job: 'A slice of the Model kept in the URL or in storage',\n imports: ['mirror'],\n guide: 'mirror',\n },\n {\n job: 'Forms: drafts, validation, a decoded value, and dates, times and addresses in them',\n imports: ['form', 'mixins-form', 'form-recipes'],\n guide: 'form',\n },\n {\n job: 'Edit, create and list screens over Remote',\n imports: ['crud', 'mixins-crud'],\n guide: 'crud',\n },\n {\n job: 'An interactive data grid over rows you own',\n imports: ['data-grid', 'mixins-data-grid'],\n guide: 'data-grid',\n },\n {\n job: 'Drafts, revisions and publishing for content',\n imports: ['cms', 'cms-drizzle'],\n guide: 'cms',\n },\n {\n job: 'Pages as data, and a builder that edits them',\n imports: ['composition', 'builder', 'mixins-builder'],\n guide: 'composition',\n },\n {\n job: 'Rich text: the document, its editor, Markdown and code',\n imports: [\n 'richtext',\n 'richtext-dom',\n 'mixins-richtext',\n 'richtext-markdown',\n 'richtext-code',\n 'richtext-code-shiki',\n ],\n guide: 'richtext',\n },\n { job: 'Server rendering that hands the Model over', imports: ['ssr'], guide: 'ssr' },\n {\n job: 'Responsive images, their variants and placeholders, and icons as data',\n imports: ['media'],\n guide: 'media',\n },\n { job: 'Route topology as data: nodes, typed targets, titles', imports: ['site'], guide: 'site' },\n {\n job: 'What an AI agent may see and do, over MCP, WebMCP, A2A or Agent Native',\n imports: ['agent', 'agent-mcp', 'agent-webmcp', 'agent-a2a', 'agent-native'],\n guide: 'agent',\n },\n {\n job: 'React components in a Foldkit view, or Foldkit inside React',\n imports: ['react', 'react-codegen'],\n guide: 'react',\n },\n]\n\n/**\n * The packages `foldkit-plus` does not install, since each needs a library of\n * its own, and that library. `test/setup.test.ts` holds this to the manifest.\n */\nexport const adapters: ReadonlyArray<{\n readonly name: string\n readonly libraries: ReadonlyArray<string>\n readonly when: string\n}> = [\n {\n name: 'foldkit-agent-native',\n libraries: ['@agent-native/core'],\n when: 'agents through Agent Native',\n },\n {\n name: 'foldkit-auth',\n libraries: ['@yielded/auth'],\n when: 'sign-in and sessions with Yielded Auth',\n },\n { name: 'foldkit-cms-drizzle', libraries: ['drizzle-orm'], when: \"the CMS's server on Drizzle\" },\n {\n name: 'foldkit-mixins-ui',\n libraries: ['@foldkit/ui'],\n when: 'styling `@foldkit/ui` components through slots',\n },\n { name: 'foldkit-react', libraries: ['react', 'react-dom'], when: 'React interop' },\n {\n name: 'foldkit-react-codegen',\n libraries: ['typescript'],\n when: 'compiling Foldkit views to React TSX (a dev dependency)',\n },\n {\n name: 'foldkit-remote-drizzle',\n libraries: ['drizzle-orm'],\n when: 'answering Remote reads with Drizzle',\n },\n {\n name: 'foldkit-richtext-code-shiki',\n libraries: ['shiki'],\n when: 'highlighting code blocks with Shiki',\n },\n]\n\n/** The command that adds `packages` with `manager`. */\nexport const addCommand = (manager: Manager, packages: ReadonlyArray<string>): string =>\n `${manager} ${manager === 'npm' ? 'install' : 'add'} ${packages.join(' ')}`\n\n/** The major version a range asks for: `^4.0.0`, `~4.1`, `4.0.0-beta.1` all ask for 4. */\nconst majorOf = (range: string): Option.Option<number> =>\n Option.fromNullishOr(/(\\d+)/.exec(range)?.[1]).pipe(Option.map(Number))\n\n/** What the project has of a library against what this release needs, as a line to act on. */\nconst finding = (project: Project, library: string, wanted: string): string =>\n Option.match(Option.fromNullishOr(project.versions[library]), {\n onNone: () => `- \\`${library}\\` is not installed: step 2 adds \\`${library}@${wanted}\\`.`,\n onSome: range => {\n // Foldkit is 0.x, where a minor version breaks; Effect is past 1.\n const matches =\n library === 'foldkit'\n ? range.replace(/^[\\^~=v]*/, '').startsWith(wanted.split('.').slice(0, 2).join('.'))\n : Option.getOrUndefined(majorOf(range)) === Option.getOrUndefined(majorOf(wanted))\n return matches\n ? `- \\`${library}\\` ${range}: fits.`\n : `- \\`${library}\\` is ${range}, and Foldkit Plus needs ${wanted}: step 2 moves it to ${wanted}. Check the application builds after.`\n },\n })\n\nexport const setupGuide = ({ project, manager, versions }: SetupInput): string => {\n const install = addCommand(manager, [\n `effect@${versions.effect}`,\n `foldkit@${versions.foldkit}`,\n `@effect/platform-browser@${versions.effect}`,\n 'foldkit-plus',\n ])\n const check = Option.match(project, {\n onNone: () => [\n 'There is no `package.json` here: this is a new application. Do not scaffold yet. Follow the greenfield guide, which asks the user about the goals, the look and the domain before any code:',\n '',\n `- ${GREENFIELD} (in the skill of step 3, \\`references/greenfield.md\\`)`,\n '',\n 'When its first step has a name and a rendering mode, it scaffolds with:',\n '',\n '```bash',\n `npx ${SCAFFOLDER} --name <name> --rendering <spa|ssg|ssr> --example counter --package-manager ${manager}`,\n '```',\n '',\n 'Then run `npx foldkit-plus setup` again in the new folder and continue from step 2.',\n ],\n onSome: found => [\n `This is \\`${found.name}\\`, installed with ${manager}.`,\n '',\n finding(found, 'effect', versions.effect),\n finding(found, 'foldkit', versions.foldkit),\n ],\n })\n return [\n `# Foldkit Plus ${versions.plus}: setup`,\n '',\n 'Instructions for a coding agent, in order. Each step says what to run and why. Tell the user what you did at the end.',\n '',\n '## What these are',\n '',\n '- **Effect** (https://effect.website): TypeScript for typed effects, errors, schemas and streams. Foldkit Plus targets Effect 4.',\n '- **Foldkit** (https://foldkit.dev): an application is one state machine on Effect, a Schema-typed `Model`, a `Message` union and one pure `update`; I/O runs in Commands and Subscriptions.',\n '- **Foldkit Plus**: packages that extend a Foldkit application to agents, servers, other devices, the URL and design systems without a second place to keep state. An agent sends only Messages `update` already handles; server data lives in the Model; replicas replay the same Messages; the URL mirrors a slice of the Model.',\n '',\n '## 1. Check the project',\n '',\n ...check,\n '',\n '## 2. Install',\n '',\n '```bash',\n install,\n '```',\n '',\n '`foldkit-plus` brings every package except the adapters below, each of which needs a library of its own. Add one only when the application needs it:',\n '',\n ...adapters.map(\n each => `- ${each.when}: \\`${addCommand(manager, [each.name, ...each.libraries])}\\``,\n ),\n '',\n '## 3. Add the agent skill',\n '',\n '```bash',\n 'npx skills add doeixd/foldkit-plus --skill foldkit-plus',\n '```',\n '',\n 'It teaches you which package owns which kind of state, when to reach for each, and a working example of each. Read its `SKILL.md` before writing code with Foldkit Plus, and the reference for the package at hand before changing it.',\n // An empty folder was sent to the guide in step 1.\n ...Option.match(project, {\n onNone: () => [],\n onSome: () => [\n '',\n `Building a new application rather than extending one? Follow its \\`references/greenfield.md\\` (${GREENFIELD}): goals and the look, then the domain with the user, recorded in the project and mapped to these packages, then a plan for architecture, performance, SEO, testing, CI and deployment, before implementing.`,\n ],\n }),\n '',\n '## 4. Import',\n '',\n 'The namespaces most applications use come from the root:',\n '',\n '```ts',\n \"import { Surface, Projection, Remote, Sync, Mirror, Agent, Style } from 'foldkit-plus'\",\n '```',\n '',\n 'Everything else is a subpath named for its package, for example `foldkit-plus/remote-server` on the server, `foldkit-plus/sync/journal`, `foldkit-plus/mixins/theme`. Pick a package by who owns the data:',\n '',\n '| Job | Import from | Guide |',\n '| --- | --- | --- |',\n ...jobs.map(\n each =>\n `| ${each.job} | ${each.imports.map(name => `\\`foldkit-plus/${name}\\``).join(', ')} | ${SITE}/${each.guide} |`,\n ),\n '',\n '## 5. Rules every package keeps',\n '',\n '- One owner per datum: never keep a fact in the Model and again in a cache, a URL store or a second reducer.',\n '- Behaviour goes through Messages and `update`; agents, replicas and Behaviors never change the Model directly.',\n '- Rendering performs no I/O: fetching, syncing and mirroring run in Commands and Subscriptions.',\n '- Absence is an Effect `Option`, not `null`, except at a JSON, database or DOM boundary.',\n '',\n '## More',\n '',\n `- Guides and API: ${SITE}`,\n `- Demos: ${SITE}/demos`,\n `- Source and changelog: ${REPOSITORY}`,\n '',\n ].join('\\n')\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"setup.mjs","names":[],"sources":["../src/setup.ts"],"sourcesContent":["/**\n * What `npx foldkit-plus setup` prints: instructions a coding agent can follow\n * in order, for the project it is run in. Pure: the CLI reads the project and\n * this package's manifest and passes them in, so a test can give any project.\n */\nimport { Option } from 'effect'\n\nexport type Manager = 'pnpm' | 'npm' | 'yarn' | 'bun'\n\n/** What the project's `package.json` says about the libraries Foldkit Plus needs. */\nexport interface Project {\n readonly name: string\n /** Each named library's version range, from any dependency field. */\n readonly versions: Readonly<Record<string, string>>\n /** Whether a `.gitattributes` applies here: in the project's folder or one above it in its repository. */\n readonly gitattributes: boolean\n /** Where pnpm reads this project's settings, which a workspace keeps at its root. */\n readonly pnpmSettings: PnpmSettings\n /** The versions of Effect's packages (`effectPackages`) its npm lockfile holds, nested copies included. */\n readonly locked: ReadonlyArray<string>\n}\n\n/** A file pnpm reads settings from, in `folder` relative to the project (`.`, `../..`). */\nexport interface PnpmSettings {\n readonly folder: string\n readonly file: 'package.json' | 'pnpm-workspace.yaml'\n}\n\n/**\n * The versions this release is built and tested against, from its own\n * manifest: the workspace's Foldkit and Effect.\n */\nexport interface Versions {\n readonly plus: string\n readonly effect: string\n readonly foldkit: string\n}\n\nexport interface SetupInput {\n readonly project: Option.Option<Project>\n readonly manager: Manager\n readonly versions: Versions\n}\n\nconst SITE = 'https://foldkit-plus.pages.dev'\nconst REPOSITORY = 'https://github.com/doeixd/foldkit-plus'\n\n/**\n * The `create-foldkit-app` release whose templates pin the Foldkit this\n * release needs (0.41.0 installs `foldkit`, `@foldkit/ui` and `@foldkit/devtools`\n * 0.170.0, `@foldkit/vite-plugin` 0.29.0 and `effect` 4.1.0). A release that\n * moves the `foldkit` peer moves this with it.\n */\nexport const SCAFFOLDER = 'create-foldkit-app@0.41.0'\n\nconst GREENFIELD = `${REPOSITORY}/blob/main/skills/foldkit-plus/references/greenfield.md`\nconst AGENTS_BLOCK = `${REPOSITORY}/blob/main/skills/foldkit-plus/references/agents-md.md`\n\n/** What each job needs, where to import it from, and where it is explained. */\nexport const jobs: ReadonlyArray<{\n readonly job: string\n readonly imports: ReadonlyArray<string>\n readonly guide: string\n}> = [\n {\n job: 'Name what a feature may read and which Messages it may send',\n imports: ['surface', 'metadata'],\n guide: 'surface',\n },\n {\n job: 'A reusable Submodel placed several times, every part wired',\n imports: ['bundle', 'bundle-surface'],\n guide: 'bundle',\n },\n {\n job: 'Restyle or extend views from outside, through typed slots',\n imports: ['mixins', 'mixins-surface', 'mixins-ui'],\n guide: 'mixins',\n },\n {\n job: 'Media queries, timers, sockets, clipboard, undo history',\n imports: ['primitives'],\n guide: 'primitives',\n },\n {\n job: 'Declare the domain once: entities, relations, queries',\n imports: ['entity'],\n guide: 'entity',\n },\n {\n job: 'Server-owned data in the Model: queries, mutations, live updates',\n imports: ['remote', 'remote-server', 'remote-drizzle'],\n guide: 'remote',\n },\n {\n job: 'Edits that survive offline and converge across devices',\n imports: ['sync', 'durable'],\n guide: 'sync',\n },\n { job: 'Who may do what, enforced on every seam', imports: ['guard'], guide: 'guard' },\n {\n job: 'Who is signed in: a Yielded Auth session as the principal',\n imports: ['auth'],\n guide: 'auth',\n },\n {\n job: 'A slice of the Model kept in the URL or in storage',\n imports: ['mirror'],\n guide: 'mirror',\n },\n {\n job: 'Forms: drafts, validation, a decoded value, and dates, times and addresses in them',\n imports: ['form', 'mixins-form', 'form-recipes'],\n guide: 'form',\n },\n {\n job: 'Edit, create and list screens over Remote',\n imports: ['crud', 'mixins-crud'],\n guide: 'crud',\n },\n {\n job: 'An interactive data grid over rows you own',\n imports: ['data-grid', 'mixins-data-grid'],\n guide: 'data-grid',\n },\n {\n job: 'Drafts, revisions and publishing for content',\n imports: ['cms', 'cms-drizzle'],\n guide: 'cms',\n },\n {\n job: 'Pages as data, and a builder that edits them',\n imports: ['composition', 'builder', 'mixins-builder'],\n guide: 'composition',\n },\n {\n job: 'Rich text: the document, its editor, Markdown and code',\n imports: [\n 'richtext',\n 'richtext-dom',\n 'mixins-richtext',\n 'richtext-markdown',\n 'richtext-code',\n 'richtext-code-shiki',\n ],\n guide: 'richtext',\n },\n { job: 'Server rendering that hands the Model over', imports: ['ssr'], guide: 'ssr' },\n {\n job: 'Responsive images, their variants and placeholders, and icons as data',\n imports: ['media'],\n guide: 'media',\n },\n { job: 'Route topology as data: nodes, typed targets, titles', imports: ['site'], guide: 'site' },\n {\n job: 'What an AI agent may see and do, over MCP, WebMCP, A2A or Agent Native',\n imports: ['agent', 'agent-mcp', 'agent-webmcp', 'agent-a2a', 'agent-native'],\n guide: 'agent',\n },\n {\n job: 'React components in a Foldkit view, or Foldkit inside React',\n imports: ['react', 'react-codegen'],\n guide: 'react',\n },\n]\n\n/**\n * The packages `foldkit-plus` does not install, since each needs a library of\n * its own, and that library at the range the adapter peers on: a manager\n * given a bare name installs the `latest` tag, which for `@yielded/auth` is a\n * beta older than the one `foldkit-auth` names. `test/generated.test.ts`\n * holds this to the manifests.\n */\nexport const adapters: ReadonlyArray<{\n readonly name: string\n readonly libraries: ReadonlyArray<string>\n readonly when: string\n}> = [\n {\n name: 'foldkit-agent-native',\n libraries: ['@agent-native/core@0.214.0'],\n when: 'agents through Agent Native',\n },\n {\n name: 'foldkit-auth',\n libraries: ['@yielded/auth@0.1.0-beta.47'],\n when: 'sign-in and sessions with Yielded Auth',\n },\n {\n name: 'foldkit-cms-drizzle',\n libraries: ['drizzle-orm@1.0.0-rc.5'],\n when: \"the CMS's server on Drizzle\",\n },\n {\n name: 'foldkit-mixins-ui',\n libraries: ['@foldkit/ui@^0.170.0'],\n when: 'styling `@foldkit/ui` components through slots',\n },\n {\n name: 'foldkit-react',\n libraries: ['react@^19.0.0', 'react-dom@^19.0.0'],\n when: 'React interop',\n },\n {\n name: 'foldkit-react-codegen',\n libraries: ['typescript@>=5.7.2 <7'],\n when: 'compiling Foldkit views to React TSX (a dev dependency)',\n },\n {\n name: 'foldkit-remote-drizzle',\n libraries: ['drizzle-orm@1.0.0-rc.5'],\n when: 'answering Remote reads with Drizzle',\n },\n {\n name: 'foldkit-richtext-code-shiki',\n libraries: ['shiki@^4.4.3'],\n when: 'highlighting code blocks with Shiki',\n },\n]\n\n/**\n * The Effect packages an application meets that something names at a version\n * of its own: Foldkit's peers and its Vite plugin's dependencies name one\n * minor (`~4.1.0`), and each `@effect/*` package peers on an `effect` at least\n * its own version. Setup holds all of them at the Effect this release is\n * tested on, as `pnpm-workspace.yaml` does here (`test/generated.test.ts`\n * keeps the two lists together).\n */\nexport const effectPackages: ReadonlyArray<string> = [\n 'effect',\n '@effect/platform-browser',\n '@effect/platform-node',\n '@effect/platform-node-shared',\n '@effect/sql-sqlite-node',\n]\n\nconst releaseOf = (version: string) =>\n /^(\\d+)\\.(\\d+)\\.(\\d+)$/.exec(version)?.slice(1).map(Number) ?? []\n\n/**\n * The Effect release setup pins: the one this release is tested on, or a later\n * patch of the same minor that the project's lockfile already holds. npm keeps\n * a locked package that an override contradicts rather than move it down, so\n * pinning 4.1.0 left the 4.1.1 that `@foldkit/vite-plugin`'s `~4.1.0` had\n * locked under it, which `npm ls` calls invalid.\n */\nexport const effectRelease = (tested: string, locked: ReadonlyArray<string>): string => {\n const [major, minor] = releaseOf(tested)\n return locked.reduce((newest, version) => {\n const [lockedMajor, lockedMinor, patch = -1] = releaseOf(version)\n return lockedMajor === major && lockedMinor === minor && patch > (releaseOf(newest)[2] ?? -1)\n ? version\n : newest\n }, tested)\n}\n\n/** Where the pins go, and the block that holds them. */\ninterface Pins {\n /** The file, as the step names it: `package.json`, `../../pnpm-workspace.yaml`. */\n readonly file: string\n readonly language: 'json' | 'yaml'\n readonly text: string\n}\n\n/** A YAML key, quoted where `@` would start something else. */\nconst yamlKey = (key: string) => (key.startsWith('@') ? `'${key}'` : key)\n\n/**\n * The settings that hold every Effect package at `effect`, to merge into the\n * file the manager reads them from. npm applies an override to a package the\n * project depends on only where the project names that same version, so its\n * block sets those dependencies too (a `$name` reference would follow them,\n * but npm 10 cannot resolve a scoped one); pnpm reads them only at a\n * workspace's root.\n */\nconst pinsOf = (\n manager: Manager,\n effect: string,\n direct: ReadonlySet<string>,\n pnpmSettings: PnpmSettings,\n): Pins => {\n const pins = Object.fromEntries(effectPackages.map(name => [name, effect]))\n const allowedVersions = { effect, '@effect/platform-browser': effect }\n if (manager === 'pnpm' && pnpmSettings.file === 'pnpm-workspace.yaml') {\n const lines = (entries: Readonly<Record<string, string>>, indent: string) =>\n Object.entries(entries).map(([name, version]) => `${indent}${yamlKey(name)}: ${version}`)\n return {\n file: `${pnpmSettings.folder}/pnpm-workspace.yaml`,\n language: 'yaml',\n text: [\n 'overrides:',\n ...lines(pins, ' '),\n 'peerDependencyRules:',\n ' allowedVersions:',\n ...lines(allowedVersions, ' '),\n ].join('\\n'),\n }\n }\n const fields = {\n npm: {\n dependencies: Object.fromEntries(\n effectPackages.filter(name => direct.has(name)).map(name => [name, effect]),\n ),\n overrides: pins,\n },\n pnpm: { pnpm: { overrides: pins, peerDependencyRules: { allowedVersions } } },\n yarn: { resolutions: pins },\n bun: { overrides: pins },\n }[manager]\n return {\n file:\n manager === 'pnpm' && pnpmSettings.folder !== '.'\n ? `${pnpmSettings.folder}/package.json`\n : 'package.json',\n language: 'json',\n text: JSON.stringify(fields, null, 2),\n }\n}\n\n/** Why `manager` needs the pins, after \"first merge this into `package.json`\". */\nconst pinsWhy: Readonly<Record<Manager, string>> = {\n npm: 'npm refuses a peer it does not match, and `overrides` lets one in without turning every peer check off; it overrides a dependency of the project only at the version the project names, so the block sets those too',\n pnpm: \"`overrides` sets the version, and `peerDependencyRules` lets Foldkit's exact peers accept it\",\n yarn: \"`resolutions` sets the version; Yarn warns of Foldkit's exact peers, and installs\",\n bun: \"`overrides` sets the version; Bun warns of Foldkit's exact peers, and installs\",\n}\n\n/**\n * The command that adds `packages` with `manager`, at exactly the versions\n * named when `exact`. A range a shell would read (`^`, `>`, a space) is quoted.\n */\nexport const addCommand = (\n manager: Manager,\n packages: ReadonlyArray<string>,\n exact = false,\n): string =>\n [\n manager,\n manager === 'npm' ? 'install' : 'add',\n ...(exact ? [manager === 'npm' || manager === 'pnpm' ? '--save-exact' : '--exact'] : []),\n ...packages.map(spec => (/^[\\w@/.-]+$/.test(spec) ? spec : `\"${spec}\"`)),\n ].join(' ')\n\n/** The major version a range asks for: `^4.0.0`, `~4.1`, `4.0.0-beta.1` all ask for 4. */\nconst majorOf = (range: string): Option.Option<number> =>\n Option.fromNullishOr(/(\\d+)/.exec(range)?.[1]).pipe(Option.map(Number))\n\n/** What the project has of a library against what this release needs, as a line to act on. */\nconst finding = (project: Project, library: string, wanted: string): string =>\n Option.match(Option.fromNullishOr(project.versions[library]), {\n onNone: () => `- \\`${library}\\` is not installed: step 2 adds \\`${library}@${wanted}\\`.`,\n onSome: range => {\n // Foldkit is 0.x, where a minor version breaks; Effect is past 1.\n const matches =\n library === 'foldkit'\n ? range.replace(/^[\\^~=v]*/, '').startsWith(wanted.split('.').slice(0, 2).join('.'))\n : Option.getOrUndefined(majorOf(range)) === Option.getOrUndefined(majorOf(wanted))\n return matches\n ? `- \\`${library}\\` ${range}: fits.`\n : `- \\`${library}\\` is ${range}, and Foldkit Plus needs ${wanted}: step 2 moves it to ${wanted}. Check the application builds after.`\n },\n })\n\nexport const setupGuide = ({ project, manager, versions }: SetupInput): string => {\n // Every Effect package the project names moves with `effect`, so the pins hold.\n const listed = Option.match(project, {\n onNone: () => [],\n onSome: found => effectPackages.filter(name => found.versions[name] !== undefined),\n })\n const moved = new Set(['effect', '@effect/platform-browser', ...listed])\n const effect = effectRelease(\n versions.effect,\n Option.match(project, { onNone: () => [], onSome: found => found.locked }),\n )\n const pins = pinsOf(\n manager,\n effect,\n moved,\n Option.match(project, {\n onNone: () => ({ folder: '.', file: 'package.json' }),\n onSome: found => found.pnpmSettings,\n }),\n )\n // Foldkit's devtools peer on `@foldkit/ui` at any release, and a manager left\n // to pick one takes the newest, which may peer on a newer Effect (#229).\n const uiPeer = Option.exists(\n project,\n found =>\n found.versions['@foldkit/devtools'] !== undefined &&\n found.versions['@foldkit/ui'] === undefined,\n )\n // npm's block already names the Effect packages the project depends on.\n const install = addCommand(\n manager,\n [\n ...(manager === 'npm'\n ? []\n : effectPackages.filter(name => moved.has(name)).map(name => `${name}@${effect}`)),\n `foldkit@${versions.foldkit}`,\n ...(uiPeer ? [`@foldkit/ui@${versions.foldkit}`] : []),\n 'foldkit-plus',\n ],\n true,\n )\n const check = Option.match(project, {\n onNone: () => [\n 'There is no `package.json` here: this is a new application. Do not scaffold yet. Follow the greenfield guide, which asks the user about the goals, the look and the domain before any code:',\n '',\n `- ${GREENFIELD} (in the skill of step 3, \\`references/greenfield.md\\`)`,\n '',\n `When its first step has a name and a rendering mode, it scaffolds with the command for that mode; \\`--example\\` is for spa alone, and an ssg or ssr scaffold refuses it${manager === 'npm' ? \". An ssg scaffold names `@foldkit/devtools` but not `@foldkit/ui`, its peer, so npm takes the newest `@foldkit/ui`, and refuses the install once that one needs a newer Effect than the scaffold's: `--force` lets it install with a warning, and step 2 replaces that `@foldkit/ui` with the one at the scaffold's Foldkit release (`--legacy-peer-deps` would also drop peers the scaffolder itself needs)\" : ''}:`,\n '',\n '```bash',\n `npx ${SCAFFOLDER} --name <name> --rendering spa --example counter --package-manager ${manager}`,\n `npx ${manager === 'npm' ? '--force ' : ''}${SCAFFOLDER} --name <name> --rendering ssg --package-manager ${manager}`,\n `npx ${SCAFFOLDER} --name <name> --rendering ssr --package-manager ${manager}`,\n '```',\n '',\n 'Then run `npx --legacy-peer-deps foldkit-plus setup` again in the new folder and continue from step 2.',\n ],\n onSome: found => [\n `This is \\`${found.name}\\`, installed with ${manager}.`,\n '',\n finding(found, 'effect', effect),\n finding(found, 'foldkit', versions.foldkit),\n ...(uiPeer\n ? [\n `- \\`@foldkit/devtools\\` peers on \\`@foldkit/ui\\`, which the project does not name: step 2 adds \\`@foldkit/ui@${versions.foldkit}\\`, since a manager left to choose takes the newest, which may need a newer Effect.`,\n ]\n : []),\n // Never overwritten: line endings are the project's to choose once chosen.\n ...(found.gitattributes\n ? ['- `.gitattributes` is there: leave it as it is.']\n : [\n \"- There is no `.gitattributes`. Write one at the repository's root (beside `package.json` if this is not yet a repository), so Git keeps the LF line endings the formatter writes and `git add` on Windows does not warn of every file:\",\n '',\n '```gitattributes',\n '* text=auto eol=lf',\n '*.wasm binary',\n '```',\n ]),\n ],\n })\n return [\n `# Foldkit Plus ${versions.plus}: setup`,\n '',\n 'Instructions for a coding agent, in order. Each step says what to run and why. Tell the user what you did at the end.',\n '',\n '## What these are',\n '',\n '- **Effect** (https://effect.website): TypeScript for typed effects, errors, schemas and streams. Foldkit Plus targets Effect 4.',\n '- **Foldkit** (https://foldkit.dev): an application is one state machine on Effect, a Schema-typed `Model`, a `Message` union and one pure `update`; I/O runs in Commands and Subscriptions.',\n '- **Foldkit Plus**: packages that extend a Foldkit application to agents, servers, other devices, the URL and design systems without a second place to keep state. An agent sends only Messages `update` already handles; server data lives in the Model; replicas replay the same Messages; the URL mirrors a slice of the Model.',\n '',\n '## 1. Check the project',\n '',\n ...check,\n '',\n '## 2. Install',\n '',\n `Foldkit and its tooling take one Effect minor, and Foldkit Plus is tested on ${versions.effect}.${effect === versions.effect ? '' : ` The lockfile already holds ${effect}, a later patch of that minor, and npm keeps a locked package rather than move it down to an override, so the pins name ${effect}.`} To install one copy of each Effect package, at that release, first merge this into \\`${pins.file}\\`, keeping what it holds (${pinsWhy[manager]}${pins.file === 'package.json' ? '' : '; pnpm reads them only at the workspace root'}):`,\n '',\n `\\`\\`\\`${pins.language}`,\n pins.text,\n '```',\n '',\n 'Then install:',\n '',\n '```bash',\n install,\n '```',\n '',\n '`foldkit-plus` brings every package except the adapters below, each of which needs a library of its own. Add one only when the application needs it:',\n '',\n ...adapters.map(\n each => `- ${each.when}: \\`${addCommand(manager, [each.name, ...each.libraries])}\\``,\n ),\n '',\n '## 3. Add the agent skill',\n '',\n '```bash',\n 'npx skills add doeixd/foldkit-plus --skill foldkit-plus',\n '```',\n '',\n 'It teaches you which package owns which kind of state, when to reach for each, and a working example of each. Read its `SKILL.md` before writing code with Foldkit Plus, and the reference for the package at hand before changing it. To look one symbol or topic up in the docs of the versions installed here, run `npx foldkit-plus docs <symbol or words>` (`--list` for what there is).',\n // An empty folder was sent to the guide in step 1.\n ...Option.match(project, {\n onNone: () => [],\n onSome: () => [\n '',\n `Paste the block in its \\`references/agents-md.md\\` (${AGENTS_BLOCK}) under Project Notes in the project's \\`AGENTS.md\\`: the house rules and known traps for an application on these packages.`,\n '',\n `Building a new application rather than extending one? Follow its \\`references/greenfield.md\\` (${GREENFIELD}): goals and the look, then the domain with the user, recorded in the project and mapped to these packages, then a plan for architecture, performance, SEO, testing, CI and deployment, before implementing.`,\n ],\n }),\n '',\n '## 4. Import',\n '',\n 'The namespaces most applications use come from the root:',\n '',\n '```ts',\n \"import { Surface, Projection, Remote, Sync, Mirror, Agent, Style } from 'foldkit-plus'\",\n '```',\n '',\n 'Everything else is a subpath named for its package, for example `foldkit-plus/remote-server` on the server, `foldkit-plus/sync/journal`, `foldkit-plus/mixins/theme`. Pick a package by who owns the data:',\n '',\n '| Job | Import from | Guide |',\n '| --- | --- | --- |',\n ...jobs.map(\n each =>\n `| ${each.job} | ${each.imports.map(name => `\\`foldkit-plus/${name}\\``).join(', ')} | ${SITE}/${each.guide} |`,\n ),\n '',\n '## 5. Rules every package keeps',\n '',\n '- One owner per datum: never keep a fact in the Model and again in a cache, a URL store or a second reducer.',\n '- Behaviour goes through Messages and `update`; agents, replicas and Behaviors never change the Model directly.',\n '- Rendering performs no I/O: fetching, syncing and mirroring run in Commands and Subscriptions.',\n '- Absence is an Effect `Option`, not `null`, except at a JSON, database or DOM boundary.',\n '',\n '## More',\n '',\n `- Guides and API: ${SITE}`,\n `- Demos: ${SITE}/demos`,\n `- Source and changelog: ${REPOSITORY}`,\n '',\n ].join('\\n')\n}\n"],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Loads an optional peer of a `foldkit-plus/testing` subpath on first use, so
3
+ * importing the subpath loads nothing an application has not installed, and a
4
+ * missing peer says what to install instead of Node's bare "Cannot find
5
+ * package". Internal: not an export of `foldkit-plus`.
6
+ */
7
+ export declare const peer: <Module>(subpath: string, name: string, load: () => Promise<Module>) => Promise<Module>;
8
+ //# sourceMappingURL=peer.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"peer.d.mts","names":[],"sources":["../../src/testing/peer.ts"],"mappings":";;;;;;qBAMa,OAAc,QAAM,iBAChB,cACH,YACA,QAAQ,YACnB,QAAQ"}
@@ -0,0 +1,19 @@
1
+ // src/testing/peer.ts
2
+ /**
3
+ * Loads an optional peer of a `foldkit-plus/testing` subpath on first use, so
4
+ * importing the subpath loads nothing an application has not installed, and a
5
+ * missing peer says what to install instead of Node's bare "Cannot find
6
+ * package". Internal: not an export of `foldkit-plus`.
7
+ */
8
+ const peer = async (subpath, name, load) => {
9
+ try {
10
+ return await load();
11
+ } catch (error) {
12
+ if (!isMissing(error, name)) throw error;
13
+ throw new Error(`foldkit-plus/${subpath} needs \`${name}\`, which is not installed. Add it as a dev dependency: pnpm add -D ${name}`, { cause: error });
14
+ }
15
+ };
16
+ const isMissing = (error, name) => error instanceof Error && "code" in error && error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes(`'${name}'`);
17
+ export { peer };
18
+
19
+ //# sourceMappingURL=peer.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"peer.mjs","names":[],"sources":["../../src/testing/peer.ts"],"sourcesContent":["/**\n * Loads an optional peer of a `foldkit-plus/testing` subpath on first use, so\n * importing the subpath loads nothing an application has not installed, and a\n * missing peer says what to install instead of Node's bare \"Cannot find\n * package\". Internal: not an export of `foldkit-plus`.\n */\nexport const peer = async <Module>(\n subpath: string,\n name: string,\n load: () => Promise<Module>,\n): Promise<Module> => {\n try {\n return await load()\n } catch (error) {\n if (!isMissing(error, name)) throw error\n throw new Error(\n `foldkit-plus/${subpath} needs \\`${name}\\`, which is not installed. ` +\n `Add it as a dev dependency: pnpm add -D ${name}`,\n { cause: error },\n )\n }\n}\n\n// Node and Vitest both say `Cannot find package 'name'`. A package that is\n// installed but fails to load names something else, and is rethrown as it is.\nconst isMissing = (error: unknown, name: string): boolean =>\n error instanceof Error &&\n 'code' in error &&\n error.code === 'ERR_MODULE_NOT_FOUND' &&\n error.message.includes(`'${name}'`)\n"],"mappings":";;;;;;;AAMA,MAAa,OAAO,OAClB,SACA,MACA,SACoB;CACpB,IAAI;EACF,OAAO,MAAM,KAAK;CACpB,SAAS,OAAO;EACd,IAAI,CAAC,UAAU,OAAO,IAAI,GAAG,MAAM;EACnC,MAAM,IAAI,MACR,gBAAgB,QAAQ,WAAW,KAAK,sEACK,QAC7C,EAAE,OAAO,MAAM,CACjB;CACF;AACF;AAIA,MAAM,aAAa,OAAgB,SACjC,iBAAiB,SACjB,UAAU,SACV,MAAM,SAAS,0BACf,MAAM,QAAQ,SAAS,IAAI,KAAK,EAAE"}
@@ -0,0 +1,84 @@
1
+ import { Duration } from "effect";
2
+ import { Locator, Page } from "playwright";
3
+ /**
4
+ * Writes that reach the server some way other than `Remote.http` (a port to a
5
+ * SharedWorker, a sandbox in the page). The page holds its own answers (the
6
+ * test opened it so), and `answered` resolves on the page's own evidence that
7
+ * nothing it wrote is pending: an outbox emptied, a status gone.
8
+ */
9
+ export interface PageWrites {
10
+ readonly answered: () => Promise<unknown>;
11
+ }
12
+ export interface OptimisticOptions {
13
+ /** The user's action that writes: a click, a key. */
14
+ readonly act: () => Promise<unknown>;
15
+ /** What the page shows once the write is made. */
16
+ readonly shows: Locator;
17
+ /**
18
+ * What must hold still from the moment `shows` shows until the write is
19
+ * answered and drawn: `'put'` (the default), each element `shows` resolves
20
+ * to; a `Locator`, what it resolves to instead (the list around a row its
21
+ * answer deliberately draws again); `'shown'`, nothing, so only that
22
+ * `shows` shows again after the answer.
23
+ */
24
+ readonly stays?: 'put' | 'shown' | Locator;
25
+ /** How the writes travel: `'http'` (the default), `Remote.http`'s requests, held at the network. */
26
+ readonly writes?: 'http' | PageWrites;
27
+ /**
28
+ * How long each Remote mutation is held at the network at least: it is held
29
+ * on until `act` has ended and `shows` has been looked for. `'3 seconds'`
30
+ * unless given.
31
+ */
32
+ readonly hold?: Duration.Input;
33
+ /** How soon after `act` begins `shows` must show, while every write is held. `'1 second'` unless given. */
34
+ readonly within?: Duration.Input;
35
+ }
36
+ /**
37
+ * The write shows before the server answers, holds still until it has been
38
+ * answered and drawn, and still shows after.
39
+ *
40
+ * Every Remote mutation the page sends is held at the network until `act`
41
+ * has ended and `shows` has been looked for, and for `hold` at least, so
42
+ * what shows was drawn before any answer however long `act` takes;
43
+ * `shows` must be visible within `within` of `act` beginning. From
44
+ * then until settled, what `stays` names must stay in the page as the same
45
+ * nodes, in the same place in their parent, within 1px of where they were
46
+ * drawn, and visible. Settled is evidence, not a wait: no Remote request of
47
+ * the page in flight (an answer can lead to more, such as a placed list's
48
+ * first page under `verifyPredictions`), or `writes.answered`, then the page
49
+ * quiet for three frames. An error the page logs meanwhile fails it too: a
50
+ * `PredictionMismatch` is logged as one. Throws otherwise, when `act` sent
51
+ * no Remote mutation over HTTP, since nothing was then held, and when `act`
52
+ * has not ended 10 seconds (or `hold`, if longer) after it began: one that
53
+ * waits for its own write's answer would wait for good.
54
+ */
55
+ declare const optimistic: (page: Page, options: OptimisticOptions) => Promise<void>;
56
+ export interface NeverShowsOptions {
57
+ /** What the page must not show at any moment of `during`. */
58
+ readonly text: string | RegExp;
59
+ /**
60
+ * The steps to watch: a reload, a navigation away and back. End it on what
61
+ * the page waits for (an answer, a row), since watching stops once it ends
62
+ * and the page is quiet.
63
+ */
64
+ readonly during: () => Promise<unknown>;
65
+ }
66
+ /**
67
+ * The page never shows `text` while `during` runs, nor until the page is
68
+ * quiet after it: a cached page revisited never reads "Loading…", even for
69
+ * one frame. Throws with the line that showed.
70
+ */
71
+ declare const neverShows: (page: Page, options: NeverShowsOptions) => Promise<void>;
72
+ /**
73
+ * Collects every error the page logs (`console.error`) and every exception it
74
+ * does not catch, from now until the page closes. Read the list at the end.
75
+ */
76
+ declare const consoleErrors: (page: Page) => (() => ReadonlyArray<string>);
77
+ /** Assertions on what a running page shows, for Playwright. */
78
+ export declare const Behaviors: {
79
+ readonly optimistic: typeof optimistic;
80
+ readonly neverShows: typeof neverShows;
81
+ readonly consoleErrors: typeof consoleErrors;
82
+ };
83
+ export {};
84
+ //# sourceMappingURL=playwright.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"playwright.d.mts","names":[],"sources":["../../src/testing/playwright.ts"],"mappings":";;;;;;;;iBA6EiB;WACN,gBAAgB;;iBAGV;;WAEN,WAAW;;WAEX,OAAO;;;;;;;;WAQP,0BAA0B;;WAE1B,kBAAkB;;;;;;WAMlB,OAAO,SAAS;;WAEhB,SAAS,SAAS;;;;;;;;;;;;;;;;;;;;;cAwIvB,aAAU,MAAgB,MAAI,SAAW,sBAAoB;iBAiIlD;;WAEN,eAAe;;;;;;WAMf,cAAc;;;;;;;cA2CnB,aAAU,MAAgB,MAAI,SAAW,sBAAoB;;;;;cA6B7D,gBAAa,MAAU,gBAAc;;qBAU9B"}