foldkit-plus 0.18.0 → 0.20.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.
@@ -0,0 +1 @@
1
+ export * from "foldkit-mixins/vite";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-mixins/vite";
2
+ export {};
@@ -1 +1 @@
1
- {"version":3,"file":"project.d.mts","names":[],"sources":["../src/project.ts"],"mappings":";;;qBAqBa,eAAY;;;;;;;;;;;;;;;;;;qBAuCZ,YAAS,mBAAqB,OAAO,OAAO;;;;;qBAoB5C,YAAS,mBAAqB;;qBAmB9B,gBAAgB;;qBAGhB,WAAQ,UAAc,kBAAkB,kBAAgB;;iBAuDpD;WACN,MAAM,cAAc;WACpB,eAAe,mBAAmB,cAAc;;;;;;;;;qBAU9C,YAAS,gBAAkB,QAAU,0BAAwB"}
1
+ {"version":3,"file":"project.d.mts","names":[],"sources":["../src/project.ts"],"mappings":";;;qBAqBa,eAAY;;;;;;;;;;;;;;;;;;qBAuEZ,YAAS,mBAAqB,OAAO,OAAO;;;;;qBAqB5C,YAAS,mBAAqB;;qBAmB9B,gBAAgB;;qBAGhB,WAAQ,UAAc,kBAAkB,kBAAgB;;iBAuDpD;WACN,MAAM,cAAc;WACpB,eAAe,mBAAmB,cAAc;;;;;;;;;qBAU9C,YAAS,gBAAkB,QAAU,0BAAwB"}
package/dist/project.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  import { declarationsIn } from "./docs.mjs";
2
+ import { effectPackages } from "./setup.mjs";
2
3
  import { Option, Schema } from "effect";
3
4
  import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
4
5
  import { homedir } from "node:os";
@@ -55,6 +56,20 @@ const pnpmSettingsIn = (folder) => {
55
56
  file: field ? "package.json" : "pnpm-workspace.yaml"
56
57
  };
57
58
  };
59
+ const NpmLock = Schema.Struct({ packages: Schema.Record(Schema.String, Schema.Struct({ version: Schema.optional(Schema.String) })) });
60
+ /**
61
+ * The versions of Effect's packages in the nearest npm lockfile, keyed by
62
+ * install path (`node_modules/@foldkit/vite-plugin/node_modules/effect`). One
63
+ * npm cannot read holds none.
64
+ */
65
+ const lockedEffect = (folder) => {
66
+ const lock = projectFolders(folder).map((at) => join(at, "package-lock.json")).find(existsSync);
67
+ if (lock === void 0) return [];
68
+ return Option.match(Schema.decodeUnknownOption(Schema.fromJsonString(NpmLock))(readFileSync(lock, "utf8")), {
69
+ onNone: () => [],
70
+ onSome: ({ packages }) => Object.entries(packages).flatMap(([path, entry]) => entry.version !== void 0 && effectPackages.some((name) => path.endsWith(`node_modules/${name}`)) ? [entry.version] : [])
71
+ });
72
+ };
58
73
  /** The project in `folder`, if it is one. */
59
74
  const projectIn = (folder) => {
60
75
  const path = join(folder, "package.json");
@@ -68,7 +83,8 @@ const projectIn = (folder) => {
68
83
  ...manifest.dependencies
69
84
  },
70
85
  gitattributes: projectFolders(folder).some((at) => existsSync(join(at, ".gitattributes"))),
71
- pnpmSettings: pnpmSettingsIn(folder)
86
+ pnpmSettings: pnpmSettingsIn(folder),
87
+ locked: lockedEffect(folder)
72
88
  });
73
89
  };
74
90
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"project.mjs","names":[],"sources":["../src/project.ts"],"sourcesContent":["/**\n * What the CLI reads from the disk: the project in a folder, its package\n * manager, and this package's own manifest.\n */\nimport { Option, Schema } from 'effect'\nimport { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { dirname, join, relative, sep } from 'node:path'\n\nimport { declarationsIn, type Declaration, type Doc } from './docs.js'\nimport type { Manager, PnpmSettings, Project } from './setup.js'\n\nconst Versions = Schema.Record(Schema.String, Schema.String)\nconst Manifest = Schema.Struct({\n name: Schema.optional(Schema.String),\n version: Schema.optional(Schema.String),\n dependencies: Schema.optional(Versions),\n devDependencies: Schema.optional(Versions),\n peerDependencies: Schema.optional(Versions),\n setup: Schema.optional(Schema.Struct({ effect: Schema.String, foldkit: Schema.String })),\n})\nexport const readManifest = (path: string) =>\n Schema.decodeUnknownSync(Manifest)(JSON.parse(readFileSync(path, 'utf8')))\n\n/**\n * A project's folder and those above it, up to its repository's root and no\n * further, and never into the home folder: a file left there says nothing\n * about this project. A folder that is no project has none.\n */\nconst projectFolders = (folder: string): ReadonlyArray<string> => {\n const folders: Array<string> = []\n const project = existsSync(join(folder, 'package.json'))\n for (let at = folder; project && at !== homedir(); at = dirname(at)) {\n folders.push(at)\n if (existsSync(join(at, '.git')) || dirname(at) === at) break\n }\n return folders\n}\n\n/**\n * Where pnpm reads `folder`'s `overrides` and `peerDependencyRules`: the\n * workspace root, the nearest folder at or above it with a\n * `pnpm-workspace.yaml`, since pnpm ignores them in a member's `package.json`.\n * There, the root `package.json`'s `pnpm` field if it already has one, else\n * the YAML; with no workspace, the project's own `package.json`.\n */\nconst pnpmSettingsIn = (folder: string): PnpmSettings => {\n const root = projectFolders(folder).find(at => existsSync(join(at, 'pnpm-workspace.yaml')))\n if (root === undefined) return { folder: '.', file: 'package.json' }\n const manifest = join(root, 'package.json')\n const field =\n existsSync(manifest) &&\n Object.hasOwn(JSON.parse(readFileSync(manifest, 'utf8')) as object, 'pnpm')\n return {\n folder: relative(folder, root).split(sep).join('/') || '.',\n file: field ? 'package.json' : 'pnpm-workspace.yaml',\n }\n}\n\n/** The project in `folder`, if it is one. */\nexport const projectIn = (folder: string): Option.Option<Project> => {\n const path = join(folder, 'package.json')\n if (!existsSync(path)) return Option.none()\n const manifest = readManifest(path)\n return Option.some({\n name: manifest.name ?? 'this project',\n versions: {\n ...manifest.peerDependencies,\n ...manifest.devDependencies,\n ...manifest.dependencies,\n },\n gitattributes: projectFolders(folder).some(at => existsSync(join(at, '.gitattributes'))),\n pnpmSettings: pnpmSettingsIn(folder),\n })\n}\n\n/**\n * The project's package manager by its lockfile, here or in a project folder\n * above (a workspace keeps one at its root), else the one running this.\n */\nexport const managerIn = (folder: string): Manager => {\n const locks: ReadonlyArray<readonly [string, Manager]> = [\n ['pnpm-lock.yaml', 'pnpm'],\n ['bun.lock', 'bun'],\n ['bun.lockb', 'bun'],\n ['yarn.lock', 'yarn'],\n ['package-lock.json', 'npm'],\n ]\n for (const at of projectFolders(folder)) {\n const locked = locks.find(([file]) => existsSync(join(at, file)))\n if (locked !== undefined) return locked[1]\n }\n const agent = process.env['npm_config_user_agent'] ?? ''\n return (\n locks.map(([, manager]) => manager).find(manager => agent.startsWith(`${manager}/`)) ?? 'npm'\n )\n}\n\n/** A failure the reader can act on, printed as its message alone. */\nexport class Refusal extends Error {}\n\n/** The Foldkit Plus packages a manifest names: its own `foldkit-*` dependencies and peers. */\nexport const familyOf = (manifest: ReturnType<typeof readManifest>): ReadonlyArray<string> =>\n Object.keys({ ...manifest.dependencies, ...manifest.peerDependencies }).filter(name =>\n name.startsWith('foldkit-'),\n )\n\n/**\n * Where an `import` from `base` finds `name`: the nearest `node_modules` above\n * it that holds the package, with links resolved, so a package's own\n * dependencies are found beside it in pnpm's store. ESM reads neither\n * `NODE_PATH` nor the global folders, which `require.resolve.paths` adds.\n */\nconst installedFrom = (base: string, name: string): Option.Option<string> => {\n for (let at = base; ; at = dirname(at)) {\n const candidate = join(at, 'node_modules', name)\n if (existsSync(join(candidate, 'package.json'))) return Option.some(realpathSync(candidate))\n if (dirname(at) === at) return Option.none()\n }\n}\n\ninterface Installed {\n readonly name: string\n readonly version: string\n readonly dir: string\n}\n\n/** The `foldkit-plus` skill nearest the project: in a dot-folder's `skills/` here, above, or at home. */\nconst skillIn = (folder: string): Option.Option<string> => {\n for (const at of [...projectFolders(folder), homedir()]) {\n const holders = existsSync(at)\n ? readdirSync(at, { withFileTypes: true }).filter(\n entry => entry.isDirectory() && entry.name.startsWith('.'),\n )\n : []\n const skill = holders\n .map(entry => join(at, entry.name, 'skills', 'foldkit-plus'))\n .find(dir => existsSync(join(dir, 'SKILL.md')))\n if (skill !== undefined) return Option.some(skill)\n }\n return Option.none()\n}\n\nconst declarationFiles = (dir: string): ReadonlyArray<string> =>\n existsSync(dir)\n ? readdirSync(dir, { withFileTypes: true }).flatMap(entry =>\n entry.isDirectory()\n ? declarationFiles(join(dir, entry.name))\n : /\\.d\\.m?ts$/.test(entry.name)\n ? [join(dir, entry.name)]\n : [],\n )\n : []\n\nconst topicOf = (name: string) => name.replace(/^foldkit-/, '')\n\n/** What `docs` reads for a project: its documents, and a way to look a symbol up in its types. */\nexport interface Library {\n readonly docs: ReadonlyArray<Doc>\n readonly declarations: (symbol: string) => ReadonlyArray<Declaration>\n}\n\n/**\n * The documents of what is installed in `folder`: the README of each Foldkit\n * Plus package Node would load there, and the skill's files if it is\n * installed. `family` is the packages this CLI knows of; an installed\n * `foldkit-plus` adds those it knows. Refuses a folder with no project, a\n * package the project names but has not installed, and a project with none.\n */\nexport const libraryIn = (folder: string, family: ReadonlyArray<string>): Library => {\n const project = projectIn(folder)\n if (Option.isNone(project))\n throw new Refusal(\n `There is no package.json in ${folder}: run this in the application's folder.`,\n )\n const plus = installedFrom(folder, 'foldkit-plus')\n const names = new Set([\n 'foldkit-plus',\n ...family,\n ...Option.match(plus, {\n onNone: () => [],\n onSome: dir => familyOf(readManifest(join(dir, 'package.json'))),\n }),\n ])\n const installed: Array<Installed> = []\n for (const name of [...names].sort()) {\n // What the project names is what its own imports load; the rest is what\n // `foldkit-plus` loads, which a copy in a folder above must not stand for.\n const named = project.value.versions[name] !== undefined\n const fromProject = () => installedFrom(folder, name)\n const dir = named\n ? fromProject()\n : Option.orElse(\n Option.flatMap(plus, at => installedFrom(at, name)),\n fromProject,\n )\n Option.match(dir, {\n onNone: () => {\n if (named)\n throw new Refusal(\n `package.json names ${name}, but it is not installed in ${folder}: run the install first.`,\n )\n },\n onSome: at => {\n const version = readManifest(join(at, 'package.json')).version ?? 'unversioned'\n installed.push({ name, version, dir: at })\n },\n })\n }\n if (installed.length === 0)\n throw new Refusal(\n `No Foldkit Plus package is installed in ${folder}. \\`npx foldkit-plus setup\\` says how to install one.`,\n )\n const skill = Option.match(skillIn(folder), {\n onNone: () => [],\n onSome: dir => {\n const front = readFileSync(join(dir, 'SKILL.md'), 'utf8')\n const version = /^\\s+version:\\s*['\"]?([^'\"\\s]+)/m.exec(front)?.[1] ?? 'unversioned'\n const references = join(dir, 'references')\n const files = [\n join(dir, 'SKILL.md'),\n ...(existsSync(references)\n ? readdirSync(references)\n .filter(file => file.endsWith('.md'))\n .sort()\n .map(file => join(references, file))\n : []),\n ]\n return files.map(path => ({\n topic: path.endsWith('SKILL.md') ? 'skill' : relative(references, path).slice(0, -3),\n label: `foldkit-plus skill ${version} ${relative(dir, path).split(sep).join('/')}`,\n path,\n text: readFileSync(path, 'utf8'),\n }))\n },\n })\n const readmes = installed.flatMap(each => {\n const path = join(each.dir, 'README.md')\n return existsSync(path)\n ? [\n {\n topic: topicOf(each.name),\n label: `${each.name}@${each.version} README.md`,\n path,\n text: readFileSync(path, 'utf8'),\n },\n ]\n : []\n })\n return {\n docs: [...skill, ...readmes],\n // Read only for a symbol; `foldkit-plus`'s own types re-export the others'.\n declarations: symbol => {\n const seen = new Set<string>()\n return installed\n .filter(each => each.name !== 'foldkit-plus')\n .flatMap(each =>\n declarationFiles(join(each.dir, 'dist')).flatMap(path =>\n declarationsIn(\n {\n topic: topicOf(each.name),\n origin: `${each.name}@${each.version}`,\n path,\n text: readFileSync(path, 'utf8'),\n },\n symbol,\n ),\n ),\n )\n .filter(found => {\n const key = [...found.comment, ...found.signature].join('\\n')\n if (seen.has(key)) return false\n seen.add(key)\n return true\n })\n },\n }\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"project.mjs","names":[],"sources":["../src/project.ts"],"sourcesContent":["/**\n * What the CLI reads from the disk: the project in a folder, its package\n * manager, and this package's own manifest.\n */\nimport { Option, Schema } from 'effect'\nimport { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'\nimport { homedir } from 'node:os'\nimport { dirname, join, relative, sep } from 'node:path'\n\nimport { declarationsIn, type Declaration, type Doc } from './docs.js'\nimport { effectPackages, type Manager, type PnpmSettings, type Project } from './setup.js'\n\nconst Versions = Schema.Record(Schema.String, Schema.String)\nconst Manifest = Schema.Struct({\n name: Schema.optional(Schema.String),\n version: Schema.optional(Schema.String),\n dependencies: Schema.optional(Versions),\n devDependencies: Schema.optional(Versions),\n peerDependencies: Schema.optional(Versions),\n setup: Schema.optional(Schema.Struct({ effect: Schema.String, foldkit: Schema.String })),\n})\nexport const readManifest = (path: string) =>\n Schema.decodeUnknownSync(Manifest)(JSON.parse(readFileSync(path, 'utf8')))\n\n/**\n * A project's folder and those above it, up to its repository's root and no\n * further, and never into the home folder: a file left there says nothing\n * about this project. A folder that is no project has none.\n */\nconst projectFolders = (folder: string): ReadonlyArray<string> => {\n const folders: Array<string> = []\n const project = existsSync(join(folder, 'package.json'))\n for (let at = folder; project && at !== homedir(); at = dirname(at)) {\n folders.push(at)\n if (existsSync(join(at, '.git')) || dirname(at) === at) break\n }\n return folders\n}\n\n/**\n * Where pnpm reads `folder`'s `overrides` and `peerDependencyRules`: the\n * workspace root, the nearest folder at or above it with a\n * `pnpm-workspace.yaml`, since pnpm ignores them in a member's `package.json`.\n * There, the root `package.json`'s `pnpm` field if it already has one, else\n * the YAML; with no workspace, the project's own `package.json`.\n */\nconst pnpmSettingsIn = (folder: string): PnpmSettings => {\n const root = projectFolders(folder).find(at => existsSync(join(at, 'pnpm-workspace.yaml')))\n if (root === undefined) return { folder: '.', file: 'package.json' }\n const manifest = join(root, 'package.json')\n const field =\n existsSync(manifest) &&\n Object.hasOwn(JSON.parse(readFileSync(manifest, 'utf8')) as object, 'pnpm')\n return {\n folder: relative(folder, root).split(sep).join('/') || '.',\n file: field ? 'package.json' : 'pnpm-workspace.yaml',\n }\n}\n\nconst NpmLock = Schema.Struct({\n packages: Schema.Record(\n Schema.String,\n Schema.Struct({ version: Schema.optional(Schema.String) }),\n ),\n})\n\n/**\n * The versions of Effect's packages in the nearest npm lockfile, keyed by\n * install path (`node_modules/@foldkit/vite-plugin/node_modules/effect`). One\n * npm cannot read holds none.\n */\nconst lockedEffect = (folder: string): ReadonlyArray<string> => {\n const lock = projectFolders(folder)\n .map(at => join(at, 'package-lock.json'))\n .find(existsSync)\n if (lock === undefined) return []\n return Option.match(\n Schema.decodeUnknownOption(Schema.fromJsonString(NpmLock))(readFileSync(lock, 'utf8')),\n {\n onNone: () => [],\n onSome: ({ packages }) =>\n Object.entries(packages).flatMap(([path, entry]) =>\n entry.version !== undefined &&\n effectPackages.some(name => path.endsWith(`node_modules/${name}`))\n ? [entry.version]\n : [],\n ),\n },\n )\n}\n\n/** The project in `folder`, if it is one. */\nexport const projectIn = (folder: string): Option.Option<Project> => {\n const path = join(folder, 'package.json')\n if (!existsSync(path)) return Option.none()\n const manifest = readManifest(path)\n return Option.some({\n name: manifest.name ?? 'this project',\n versions: {\n ...manifest.peerDependencies,\n ...manifest.devDependencies,\n ...manifest.dependencies,\n },\n gitattributes: projectFolders(folder).some(at => existsSync(join(at, '.gitattributes'))),\n pnpmSettings: pnpmSettingsIn(folder),\n locked: lockedEffect(folder),\n })\n}\n\n/**\n * The project's package manager by its lockfile, here or in a project folder\n * above (a workspace keeps one at its root), else the one running this.\n */\nexport const managerIn = (folder: string): Manager => {\n const locks: ReadonlyArray<readonly [string, Manager]> = [\n ['pnpm-lock.yaml', 'pnpm'],\n ['bun.lock', 'bun'],\n ['bun.lockb', 'bun'],\n ['yarn.lock', 'yarn'],\n ['package-lock.json', 'npm'],\n ]\n for (const at of projectFolders(folder)) {\n const locked = locks.find(([file]) => existsSync(join(at, file)))\n if (locked !== undefined) return locked[1]\n }\n const agent = process.env['npm_config_user_agent'] ?? ''\n return (\n locks.map(([, manager]) => manager).find(manager => agent.startsWith(`${manager}/`)) ?? 'npm'\n )\n}\n\n/** A failure the reader can act on, printed as its message alone. */\nexport class Refusal extends Error {}\n\n/** The Foldkit Plus packages a manifest names: its own `foldkit-*` dependencies and peers. */\nexport const familyOf = (manifest: ReturnType<typeof readManifest>): ReadonlyArray<string> =>\n Object.keys({ ...manifest.dependencies, ...manifest.peerDependencies }).filter(name =>\n name.startsWith('foldkit-'),\n )\n\n/**\n * Where an `import` from `base` finds `name`: the nearest `node_modules` above\n * it that holds the package, with links resolved, so a package's own\n * dependencies are found beside it in pnpm's store. ESM reads neither\n * `NODE_PATH` nor the global folders, which `require.resolve.paths` adds.\n */\nconst installedFrom = (base: string, name: string): Option.Option<string> => {\n for (let at = base; ; at = dirname(at)) {\n const candidate = join(at, 'node_modules', name)\n if (existsSync(join(candidate, 'package.json'))) return Option.some(realpathSync(candidate))\n if (dirname(at) === at) return Option.none()\n }\n}\n\ninterface Installed {\n readonly name: string\n readonly version: string\n readonly dir: string\n}\n\n/** The `foldkit-plus` skill nearest the project: in a dot-folder's `skills/` here, above, or at home. */\nconst skillIn = (folder: string): Option.Option<string> => {\n for (const at of [...projectFolders(folder), homedir()]) {\n const holders = existsSync(at)\n ? readdirSync(at, { withFileTypes: true }).filter(\n entry => entry.isDirectory() && entry.name.startsWith('.'),\n )\n : []\n const skill = holders\n .map(entry => join(at, entry.name, 'skills', 'foldkit-plus'))\n .find(dir => existsSync(join(dir, 'SKILL.md')))\n if (skill !== undefined) return Option.some(skill)\n }\n return Option.none()\n}\n\nconst declarationFiles = (dir: string): ReadonlyArray<string> =>\n existsSync(dir)\n ? readdirSync(dir, { withFileTypes: true }).flatMap(entry =>\n entry.isDirectory()\n ? declarationFiles(join(dir, entry.name))\n : /\\.d\\.m?ts$/.test(entry.name)\n ? [join(dir, entry.name)]\n : [],\n )\n : []\n\nconst topicOf = (name: string) => name.replace(/^foldkit-/, '')\n\n/** What `docs` reads for a project: its documents, and a way to look a symbol up in its types. */\nexport interface Library {\n readonly docs: ReadonlyArray<Doc>\n readonly declarations: (symbol: string) => ReadonlyArray<Declaration>\n}\n\n/**\n * The documents of what is installed in `folder`: the README of each Foldkit\n * Plus package Node would load there, and the skill's files if it is\n * installed. `family` is the packages this CLI knows of; an installed\n * `foldkit-plus` adds those it knows. Refuses a folder with no project, a\n * package the project names but has not installed, and a project with none.\n */\nexport const libraryIn = (folder: string, family: ReadonlyArray<string>): Library => {\n const project = projectIn(folder)\n if (Option.isNone(project))\n throw new Refusal(\n `There is no package.json in ${folder}: run this in the application's folder.`,\n )\n const plus = installedFrom(folder, 'foldkit-plus')\n const names = new Set([\n 'foldkit-plus',\n ...family,\n ...Option.match(plus, {\n onNone: () => [],\n onSome: dir => familyOf(readManifest(join(dir, 'package.json'))),\n }),\n ])\n const installed: Array<Installed> = []\n for (const name of [...names].sort()) {\n // What the project names is what its own imports load; the rest is what\n // `foldkit-plus` loads, which a copy in a folder above must not stand for.\n const named = project.value.versions[name] !== undefined\n const fromProject = () => installedFrom(folder, name)\n const dir = named\n ? fromProject()\n : Option.orElse(\n Option.flatMap(plus, at => installedFrom(at, name)),\n fromProject,\n )\n Option.match(dir, {\n onNone: () => {\n if (named)\n throw new Refusal(\n `package.json names ${name}, but it is not installed in ${folder}: run the install first.`,\n )\n },\n onSome: at => {\n const version = readManifest(join(at, 'package.json')).version ?? 'unversioned'\n installed.push({ name, version, dir: at })\n },\n })\n }\n if (installed.length === 0)\n throw new Refusal(\n `No Foldkit Plus package is installed in ${folder}. \\`npx foldkit-plus setup\\` says how to install one.`,\n )\n const skill = Option.match(skillIn(folder), {\n onNone: () => [],\n onSome: dir => {\n const front = readFileSync(join(dir, 'SKILL.md'), 'utf8')\n const version = /^\\s+version:\\s*['\"]?([^'\"\\s]+)/m.exec(front)?.[1] ?? 'unversioned'\n const references = join(dir, 'references')\n const files = [\n join(dir, 'SKILL.md'),\n ...(existsSync(references)\n ? readdirSync(references)\n .filter(file => file.endsWith('.md'))\n .sort()\n .map(file => join(references, file))\n : []),\n ]\n return files.map(path => ({\n topic: path.endsWith('SKILL.md') ? 'skill' : relative(references, path).slice(0, -3),\n label: `foldkit-plus skill ${version} ${relative(dir, path).split(sep).join('/')}`,\n path,\n text: readFileSync(path, 'utf8'),\n }))\n },\n })\n const readmes = installed.flatMap(each => {\n const path = join(each.dir, 'README.md')\n return existsSync(path)\n ? [\n {\n topic: topicOf(each.name),\n label: `${each.name}@${each.version} README.md`,\n path,\n text: readFileSync(path, 'utf8'),\n },\n ]\n : []\n })\n return {\n docs: [...skill, ...readmes],\n // Read only for a symbol; `foldkit-plus`'s own types re-export the others'.\n declarations: symbol => {\n const seen = new Set<string>()\n return installed\n .filter(each => each.name !== 'foldkit-plus')\n .flatMap(each =>\n declarationFiles(join(each.dir, 'dist')).flatMap(path =>\n declarationsIn(\n {\n topic: topicOf(each.name),\n origin: `${each.name}@${each.version}`,\n path,\n text: readFileSync(path, 'utf8'),\n },\n symbol,\n ),\n ),\n )\n .filter(found => {\n const key = [...found.comment, ...found.signature].join('\\n')\n if (seen.has(key)) return false\n seen.add(key)\n return true\n })\n },\n }\n}\n"],"mappings":"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"}
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/filter";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/filter";
2
+ export {};
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/live";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/live";
2
+ export {};
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/outbox";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/outbox";
2
+ export {};
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/overlay";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/overlay";
2
+ export {};
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/persistence";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/persistence";
2
+ export {};
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/why";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/why";
2
+ export {};
package/dist/setup.d.mts CHANGED
@@ -9,6 +9,8 @@ export interface Project {
9
9
  readonly gitattributes: boolean;
10
10
  /** Where pnpm reads this project's settings, which a workspace keeps at its root. */
11
11
  readonly pnpmSettings: PnpmSettings;
12
+ /** The versions of Effect's packages (`effectPackages`) its npm lockfile holds, nested copies included. */
13
+ readonly locked: ReadonlyArray<string>;
12
14
  }
13
15
  /** A file pnpm reads settings from, in `folder` relative to the project (`.`, `../..`). */
14
16
  export interface PnpmSettings {
@@ -63,6 +65,14 @@ export declare const adapters: ReadonlyArray<{
63
65
  * keeps the two lists together).
64
66
  */
65
67
  export declare const effectPackages: ReadonlyArray<string>;
68
+ /**
69
+ * The Effect release setup pins: the one this release is tested on, or a later
70
+ * patch of the same minor that the project's lockfile already holds. npm keeps
71
+ * a locked package that an override contradicts rather than move it down, so
72
+ * pinning 4.1.0 left the 4.1.1 that `@foldkit/vite-plugin`'s `~4.1.0` had
73
+ * locked under it, which `npm ls` calls invalid.
74
+ */
75
+ export declare const effectRelease: (tested: string, locked: ReadonlyArray<string>) => string;
66
76
  /**
67
77
  * The command that adds `packages` with `manager`, at exactly the versions
68
78
  * named when `exact`. A range a shell would read (`^`, `>`, a space) is quoted.
@@ -1 +1 @@
1
- {"version":3,"file":"setup.d.mts","names":[],"sources":["../src/setup.ts"],"mappings":";YAOY;;iBAGK;WACN;;WAEA,UAAU,SAAS;;WAEnB;;WAEA,cAAc;;;iBAIR;WACN;WACA;;;;;;iBAOM;WACN;WACA;WACA;;iBAGM;WACN,SAAS,OAAO,OAAO;WACvB,SAAS;WACT,UAAU;;;;;;;;qBAYR;;qBAMA,MAAM;WACR;WACA,SAAS;WACT;;;;;;;;;qBA+GE,UAAU;WACZ;WACA,WAAW;WACX;;;;;;;;;;qBAoDE,gBAAgB;;;;;qBAmFhB,aAAU,SACZ,SAAO,UACN,uBAAqB;qBA8BpB,eAAU,SAAA,SAAA,YAAoC"}
1
+ {"version":3,"file":"setup.d.mts","names":[],"sources":["../src/setup.ts"],"mappings":";YAOY;;iBAGK;WACN;;WAEA,UAAU,SAAS;;WAEnB;;WAEA,cAAc;;WAEd,QAAQ;;;iBAIF;WACN;WACA;;;;;;iBAOM;WACN;WACA;WACA;;iBAGM;WACN,SAAS,OAAO,OAAO;WACvB,SAAS;WACT,UAAU;;;;;;;;qBAYR;;qBAMA,MAAM;WACR;WACA,SAAS;WACT;;;;;;;;;qBA+GE,UAAU;WACZ;WACA,WAAW;WACX;;;;;;;;;;qBAoDE,gBAAgB;;;;;;;;qBAkBhB,gBAAa,gBAAkB,QAAU;;;;;qBAqFzC,aAAU,SACZ,SAAO,UACN,uBAAqB;qBA8BpB,eAAU,SAAA,SAAA,YAAoC"}
package/dist/setup.mjs CHANGED
@@ -217,6 +217,21 @@ const effectPackages = [
217
217
  "@effect/platform-node-shared",
218
218
  "@effect/sql-sqlite-node"
219
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
+ };
220
235
  /** A YAML key, quoted where `@` would start something else. */
221
236
  const yamlKey = (key) => key.startsWith("@") ? `'${key}'` : key;
222
237
  /**
@@ -301,7 +316,11 @@ const setupGuide = ({ project, manager, versions }) => {
301
316
  "@effect/platform-browser",
302
317
  ...listed
303
318
  ]);
304
- const pins = pinsOf(manager, versions.effect, moved, Option.match(project, {
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, {
305
324
  onNone: () => ({
306
325
  folder: ".",
307
326
  file: "package.json"
@@ -310,7 +329,7 @@ const setupGuide = ({ project, manager, versions }) => {
310
329
  }));
311
330
  const uiPeer = Option.exists(project, (found) => found.versions["@foldkit/devtools"] !== void 0 && found.versions["@foldkit/ui"] === void 0);
312
331
  const install = addCommand(manager, [
313
- ...manager === "npm" ? [] : effectPackages.filter((name) => moved.has(name)).map((name) => `${name}@${versions.effect}`),
332
+ ...manager === "npm" ? [] : effectPackages.filter((name) => moved.has(name)).map((name) => `${name}@${effect}`),
314
333
  `foldkit@${versions.foldkit}`,
315
334
  ...uiPeer ? [`@foldkit/ui@${versions.foldkit}`] : [],
316
335
  "foldkit-plus"
@@ -334,7 +353,7 @@ const setupGuide = ({ project, manager, versions }) => {
334
353
  onSome: (found) => [
335
354
  `This is \`${found.name}\`, installed with ${manager}.`,
336
355
  "",
337
- finding(found, "effect", versions.effect),
356
+ finding(found, "effect", effect),
338
357
  finding(found, "foldkit", versions.foldkit),
339
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.`] : [],
340
359
  ...found.gitattributes ? ["- `.gitattributes` is there: leave it as it is."] : [
@@ -364,7 +383,7 @@ const setupGuide = ({ project, manager, versions }) => {
364
383
  "",
365
384
  "## 2. Install",
366
385
  "",
367
- `Foldkit and its tooling name one Effect release exactly, and Foldkit Plus is tested on ${versions.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"}):`,
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"}):`,
368
387
  "",
369
388
  `\`\`\`${pins.language}`,
370
389
  pins.text,
@@ -426,6 +445,6 @@ const setupGuide = ({ project, manager, versions }) => {
426
445
  ""
427
446
  ].join("\n");
428
447
  };
429
- export { SCAFFOLDER, adapters, addCommand, effectPackages, jobs, setupGuide };
448
+ export { SCAFFOLDER, adapters, addCommand, effectPackages, effectRelease, jobs, setupGuide };
430
449
 
431
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 /** 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}\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\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 pins = pinsOf(\n manager,\n versions.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}@${versions.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', versions.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 name one Effect release exactly, and Foldkit Plus is tested on ${versions.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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"}
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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"}
@@ -1,21 +1,56 @@
1
1
  import { Duration } from "effect";
2
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
+ }
3
12
  export interface OptimisticOptions {
4
13
  /** The user's action that writes: a click, a key. */
5
14
  readonly act: () => Promise<unknown>;
6
15
  /** What the page shows once the write is made. */
7
16
  readonly shows: Locator;
8
- /** How long each Remote mutation is held at the network. `'3 seconds'` unless given. */
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
+ */
9
32
  readonly hold?: Duration.Input;
10
33
  /** How soon after `act` begins `shows` must show, while every write is held. `'1 second'` unless given. */
11
34
  readonly within?: Duration.Input;
12
35
  }
13
36
  /**
14
- * The write shows before the server answers, and still shows once it has.
15
- * Every Remote mutation the page sends is held at the network for `hold`;
16
- * `shows` must be visible within `within` of `act` while they are held, and
17
- * again after every answer has landed and been drawn. Throws otherwise, and
18
- * when `act` sent no Remote mutation, since nothing was then held.
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.
19
54
  */
20
55
  declare const optimistic: (page: Page, options: OptimisticOptions) => Promise<void>;
21
56
  export interface NeverShowsOptions {
@@ -1 +1 @@
1
- {"version":3,"file":"playwright.d.mts","names":[],"sources":["../../src/testing/playwright.ts"],"mappings":";;iBAgEiB;;WAEN,WAAW;;WAEX,OAAO;;WAEP,OAAO,SAAS;;WAEhB,SAAS,SAAS;;;;;;;;;cAUvB,aAAU,MAAgB,MAAI,SAAW,sBAAoB;iBAmDlD;;WAEN,eAAe;;;;;;WAMf,cAAc;;;;;;;cA2CnB,aAAU,MAAgB,MAAI,SAAW,sBAAoB;;;;;cA6B7D,gBAAa,MAAU,gBAAc;;qBAU9B"}
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;iBAoIlD;;WAEN,eAAe;;;;;;WAMf,cAAc;;;;;;;cA2CnB,aAAU,MAAgB,MAAI,SAAW,sBAAoB;;;;;cA6B7D,gBAAa,MAAU,gBAAc;;qBAU9B"}