foldkit-plus 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,205 @@
1
+ import { declarationsIn } from "./docs.mjs";
2
+ import { Option, Schema } from "effect";
3
+ import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
4
+ import { homedir } from "node:os";
5
+ import { dirname, join, relative, sep } from "node:path";
6
+ // src/project.ts
7
+ /**
8
+ * What the CLI reads from the disk: the project in a folder, its package
9
+ * manager, and this package's own manifest.
10
+ */
11
+ const Versions = Schema.Record(Schema.String, Schema.String);
12
+ const Manifest = Schema.Struct({
13
+ name: Schema.optional(Schema.String),
14
+ version: Schema.optional(Schema.String),
15
+ dependencies: Schema.optional(Versions),
16
+ devDependencies: Schema.optional(Versions),
17
+ peerDependencies: Schema.optional(Versions),
18
+ setup: Schema.optional(Schema.Struct({
19
+ effect: Schema.String,
20
+ foldkit: Schema.String
21
+ }))
22
+ });
23
+ const readManifest = (path) => Schema.decodeUnknownSync(Manifest)(JSON.parse(readFileSync(path, "utf8")));
24
+ /**
25
+ * A project's folder and those above it, up to its repository's root and no
26
+ * further, and never into the home folder: a file left there says nothing
27
+ * about this project. A folder that is no project has none.
28
+ */
29
+ const projectFolders = (folder) => {
30
+ const folders = [];
31
+ const project = existsSync(join(folder, "package.json"));
32
+ for (let at = folder; project && at !== homedir(); at = dirname(at)) {
33
+ folders.push(at);
34
+ if (existsSync(join(at, ".git")) || dirname(at) === at) break;
35
+ }
36
+ return folders;
37
+ };
38
+ /**
39
+ * Where pnpm reads `folder`'s `overrides` and `peerDependencyRules`: the
40
+ * workspace root, the nearest folder at or above it with a
41
+ * `pnpm-workspace.yaml`, since pnpm ignores them in a member's `package.json`.
42
+ * There, the root `package.json`'s `pnpm` field if it already has one, else
43
+ * the YAML; with no workspace, the project's own `package.json`.
44
+ */
45
+ const pnpmSettingsIn = (folder) => {
46
+ const root = projectFolders(folder).find((at) => existsSync(join(at, "pnpm-workspace.yaml")));
47
+ if (root === void 0) return {
48
+ folder: ".",
49
+ file: "package.json"
50
+ };
51
+ const manifest = join(root, "package.json");
52
+ const field = existsSync(manifest) && Object.hasOwn(JSON.parse(readFileSync(manifest, "utf8")), "pnpm");
53
+ return {
54
+ folder: relative(folder, root).split(sep).join("/") || ".",
55
+ file: field ? "package.json" : "pnpm-workspace.yaml"
56
+ };
57
+ };
58
+ /** The project in `folder`, if it is one. */
59
+ const projectIn = (folder) => {
60
+ const path = join(folder, "package.json");
61
+ if (!existsSync(path)) return Option.none();
62
+ const manifest = readManifest(path);
63
+ return Option.some({
64
+ name: manifest.name ?? "this project",
65
+ versions: {
66
+ ...manifest.peerDependencies,
67
+ ...manifest.devDependencies,
68
+ ...manifest.dependencies
69
+ },
70
+ gitattributes: projectFolders(folder).some((at) => existsSync(join(at, ".gitattributes"))),
71
+ pnpmSettings: pnpmSettingsIn(folder)
72
+ });
73
+ };
74
+ /**
75
+ * The project's package manager by its lockfile, here or in a project folder
76
+ * above (a workspace keeps one at its root), else the one running this.
77
+ */
78
+ const managerIn = (folder) => {
79
+ const locks = [
80
+ ["pnpm-lock.yaml", "pnpm"],
81
+ ["bun.lock", "bun"],
82
+ ["bun.lockb", "bun"],
83
+ ["yarn.lock", "yarn"],
84
+ ["package-lock.json", "npm"]
85
+ ];
86
+ for (const at of projectFolders(folder)) {
87
+ const locked = locks.find(([file]) => existsSync(join(at, file)));
88
+ if (locked !== void 0) return locked[1];
89
+ }
90
+ const agent = process.env["npm_config_user_agent"] ?? "";
91
+ return locks.map(([, manager]) => manager).find((manager) => agent.startsWith(`${manager}/`)) ?? "npm";
92
+ };
93
+ /** A failure the reader can act on, printed as its message alone. */
94
+ var Refusal = class extends Error {};
95
+ /** The Foldkit Plus packages a manifest names: its own `foldkit-*` dependencies and peers. */
96
+ const familyOf = (manifest) => Object.keys({
97
+ ...manifest.dependencies,
98
+ ...manifest.peerDependencies
99
+ }).filter((name) => name.startsWith("foldkit-"));
100
+ /**
101
+ * Where an `import` from `base` finds `name`: the nearest `node_modules` above
102
+ * it that holds the package, with links resolved, so a package's own
103
+ * dependencies are found beside it in pnpm's store. ESM reads neither
104
+ * `NODE_PATH` nor the global folders, which `require.resolve.paths` adds.
105
+ */
106
+ const installedFrom = (base, name) => {
107
+ for (let at = base;; at = dirname(at)) {
108
+ const candidate = join(at, "node_modules", name);
109
+ if (existsSync(join(candidate, "package.json"))) return Option.some(realpathSync(candidate));
110
+ if (dirname(at) === at) return Option.none();
111
+ }
112
+ };
113
+ /** The `foldkit-plus` skill nearest the project: in a dot-folder's `skills/` here, above, or at home. */
114
+ const skillIn = (folder) => {
115
+ for (const at of [...projectFolders(folder), homedir()]) {
116
+ const skill = (existsSync(at) ? readdirSync(at, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith(".")) : []).map((entry) => join(at, entry.name, "skills", "foldkit-plus")).find((dir) => existsSync(join(dir, "SKILL.md")));
117
+ if (skill !== void 0) return Option.some(skill);
118
+ }
119
+ return Option.none();
120
+ };
121
+ const declarationFiles = (dir) => existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? declarationFiles(join(dir, entry.name)) : /\.d\.m?ts$/.test(entry.name) ? [join(dir, entry.name)] : []) : [];
122
+ const topicOf = (name) => name.replace(/^foldkit-/, "");
123
+ /**
124
+ * The documents of what is installed in `folder`: the README of each Foldkit
125
+ * Plus package Node would load there, and the skill's files if it is
126
+ * installed. `family` is the packages this CLI knows of; an installed
127
+ * `foldkit-plus` adds those it knows. Refuses a folder with no project, a
128
+ * package the project names but has not installed, and a project with none.
129
+ */
130
+ const libraryIn = (folder, family) => {
131
+ const project = projectIn(folder);
132
+ if (Option.isNone(project)) throw new Refusal(`There is no package.json in ${folder}: run this in the application's folder.`);
133
+ const plus = installedFrom(folder, "foldkit-plus");
134
+ const names = /* @__PURE__ */ new Set([
135
+ "foldkit-plus",
136
+ ...family,
137
+ ...Option.match(plus, {
138
+ onNone: () => [],
139
+ onSome: (dir) => familyOf(readManifest(join(dir, "package.json")))
140
+ })
141
+ ]);
142
+ const installed = [];
143
+ for (const name of [...names].sort()) {
144
+ const named = project.value.versions[name] !== void 0;
145
+ const fromProject = () => installedFrom(folder, name);
146
+ const dir = named ? fromProject() : Option.orElse(Option.flatMap(plus, (at) => installedFrom(at, name)), fromProject);
147
+ Option.match(dir, {
148
+ onNone: () => {
149
+ if (named) throw new Refusal(`package.json names ${name}, but it is not installed in ${folder}: run the install first.`);
150
+ },
151
+ onSome: (at) => {
152
+ const version = readManifest(join(at, "package.json")).version ?? "unversioned";
153
+ installed.push({
154
+ name,
155
+ version,
156
+ dir: at
157
+ });
158
+ }
159
+ });
160
+ }
161
+ if (installed.length === 0) throw new Refusal(`No Foldkit Plus package is installed in ${folder}. \`npx foldkit-plus setup\` says how to install one.`);
162
+ const skill = Option.match(skillIn(folder), {
163
+ onNone: () => [],
164
+ onSome: (dir) => {
165
+ const front = readFileSync(join(dir, "SKILL.md"), "utf8");
166
+ const version = /^\s+version:\s*['"]?([^'"\s]+)/m.exec(front)?.[1] ?? "unversioned";
167
+ const references = join(dir, "references");
168
+ return [join(dir, "SKILL.md"), ...existsSync(references) ? readdirSync(references).filter((file) => file.endsWith(".md")).sort().map((file) => join(references, file)) : []].map((path) => ({
169
+ topic: path.endsWith("SKILL.md") ? "skill" : relative(references, path).slice(0, -3),
170
+ label: `foldkit-plus skill ${version} ${relative(dir, path).split(sep).join("/")}`,
171
+ path,
172
+ text: readFileSync(path, "utf8")
173
+ }));
174
+ }
175
+ });
176
+ const readmes = installed.flatMap((each) => {
177
+ const path = join(each.dir, "README.md");
178
+ return existsSync(path) ? [{
179
+ topic: topicOf(each.name),
180
+ label: `${each.name}@${each.version} README.md`,
181
+ path,
182
+ text: readFileSync(path, "utf8")
183
+ }] : [];
184
+ });
185
+ return {
186
+ docs: [...skill, ...readmes],
187
+ declarations: (symbol) => {
188
+ const seen = /* @__PURE__ */ new Set();
189
+ return installed.filter((each) => each.name !== "foldkit-plus").flatMap((each) => declarationFiles(join(each.dir, "dist")).flatMap((path) => declarationsIn({
190
+ topic: topicOf(each.name),
191
+ origin: `${each.name}@${each.version}`,
192
+ path,
193
+ text: readFileSync(path, "utf8")
194
+ }, symbol))).filter((found) => {
195
+ const key = [...found.comment, ...found.signature].join("\n");
196
+ if (seen.has(key)) return false;
197
+ seen.add(key);
198
+ return true;
199
+ });
200
+ }
201
+ };
202
+ };
203
+ export { Refusal, familyOf, libraryIn, managerIn, projectIn, readManifest };
204
+
205
+ //# sourceMappingURL=project.mjs.map
@@ -0,0 +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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"}
@@ -0,0 +1 @@
1
+ export * from "foldkit-remote/testing";
@@ -0,0 +1,2 @@
1
+ export * from "foldkit-remote/testing";
2
+ export {};
package/dist/setup.d.mts CHANGED
@@ -5,8 +5,20 @@ export interface Project {
5
5
  readonly name: string;
6
6
  /** Each named library's version range, from any dependency field. */
7
7
  readonly versions: Readonly<Record<string, string>>;
8
+ /** Whether a `.gitattributes` applies here: in the project's folder or one above it in its repository. */
9
+ readonly gitattributes: boolean;
10
+ /** Where pnpm reads this project's settings, which a workspace keeps at its root. */
11
+ readonly pnpmSettings: PnpmSettings;
8
12
  }
9
- /** The versions this release is built and tested against, from its own manifest. */
13
+ /** A file pnpm reads settings from, in `folder` relative to the project (`.`, `../..`). */
14
+ export interface PnpmSettings {
15
+ readonly folder: string;
16
+ readonly file: 'package.json' | 'pnpm-workspace.yaml';
17
+ }
18
+ /**
19
+ * The versions this release is built and tested against, from its own
20
+ * manifest: the workspace's Foldkit and Effect.
21
+ */
10
22
  export interface Versions {
11
23
  readonly plus: string;
12
24
  readonly effect: string;
@@ -19,10 +31,11 @@ export interface SetupInput {
19
31
  }
20
32
  /**
21
33
  * The `create-foldkit-app` release whose templates pin the Foldkit this
22
- * release needs (0.39.1 installs `foldkit` 0.168.0). A release that moves
23
- * the `foldkit` peer moves this with it.
34
+ * release needs (0.41.0 installs `foldkit`, `@foldkit/ui` and `@foldkit/devtools`
35
+ * 0.170.0, `@foldkit/vite-plugin` 0.29.0 and `effect` 4.1.0). A release that
36
+ * moves the `foldkit` peer moves this with it.
24
37
  */
25
- export declare const SCAFFOLDER = "create-foldkit-app@0.39.1";
38
+ export declare const SCAFFOLDER = "create-foldkit-app@0.41.0";
26
39
  /** What each job needs, where to import it from, and where it is explained. */
27
40
  export declare const jobs: ReadonlyArray<{
28
41
  readonly job: string;
@@ -31,14 +44,29 @@ export declare const jobs: ReadonlyArray<{
31
44
  }>;
32
45
  /**
33
46
  * The packages `foldkit-plus` does not install, since each needs a library of
34
- * its own, and that library. `test/setup.test.ts` holds this to the manifest.
47
+ * its own, and that library at the range the adapter peers on: a manager
48
+ * given a bare name installs the `latest` tag, which for `@yielded/auth` is a
49
+ * beta older than the one `foldkit-auth` names. `test/generated.test.ts`
50
+ * holds this to the manifests.
35
51
  */
36
52
  export declare const adapters: ReadonlyArray<{
37
53
  readonly name: string;
38
54
  readonly libraries: ReadonlyArray<string>;
39
55
  readonly when: string;
40
56
  }>;
41
- /** The command that adds `packages` with `manager`. */
42
- export declare const addCommand: (manager: Manager, packages: ReadonlyArray<string>) => string;
57
+ /**
58
+ * The Effect packages an application meets that something names at a version
59
+ * of its own: Foldkit's peers and its Vite plugin's dependencies name one
60
+ * minor (`~4.1.0`), and each `@effect/*` package peers on an `effect` at least
61
+ * its own version. Setup holds all of them at the Effect this release is
62
+ * tested on, as `pnpm-workspace.yaml` does here (`test/generated.test.ts`
63
+ * keeps the two lists together).
64
+ */
65
+ export declare const effectPackages: ReadonlyArray<string>;
66
+ /**
67
+ * The command that adds `packages` with `manager`, at exactly the versions
68
+ * named when `exact`. A range a shell would read (`^`, `>`, a space) is quoted.
69
+ */
70
+ export declare const addCommand: (manager: Manager, packages: ReadonlyArray<string>, exact?: boolean) => string;
43
71
  export declare const setupGuide: ({ project, manager, versions }: SetupInput) => string;
44
72
  //# sourceMappingURL=setup.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"setup.d.mts","names":[],"sources":["../src/setup.ts"],"mappings":";YAOY;;iBAGK;WACN;;WAEA,UAAU,SAAS;;;iBAIb;WACN;WACA;WACA;;iBAGM;WACN,SAAS,OAAO,OAAO;WACvB,SAAS;WACT,UAAU;;;;;;;qBAWR;;qBAKA,MAAM;WACR;WACA,SAAS;WACT;;;;;;qBA4GE,UAAU;WACZ;WACA,WAAW;WACX;;;qBAqCE,aAAU,SAAa,SAAO,UAAY;qBAuB1C,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;;;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"}
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,133 @@ 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
+ /** A YAML key, quoted where `@` would start something else. */
221
+ const yamlKey = (key) => key.startsWith("@") ? `'${key}'` : key;
222
+ /**
223
+ * The settings that hold every Effect package at `effect`, to merge into the
224
+ * file the manager reads them from. npm applies an override to a package the
225
+ * project depends on only where the project names that same version, so its
226
+ * block sets those dependencies too (a `$name` reference would follow them,
227
+ * but npm 10 cannot resolve a scoped one); pnpm reads them only at a
228
+ * workspace's root.
229
+ */
230
+ const pinsOf = (manager, effect, direct, pnpmSettings) => {
231
+ const pins = Object.fromEntries(effectPackages.map((name) => [name, effect]));
232
+ const allowedVersions = {
233
+ effect,
234
+ "@effect/platform-browser": effect
235
+ };
236
+ if (manager === "pnpm" && pnpmSettings.file === "pnpm-workspace.yaml") {
237
+ const lines = (entries, indent) => Object.entries(entries).map(([name, version]) => `${indent}${yamlKey(name)}: ${version}`);
238
+ return {
239
+ file: `${pnpmSettings.folder}/pnpm-workspace.yaml`,
240
+ language: "yaml",
241
+ text: [
242
+ "overrides:",
243
+ ...lines(pins, " "),
244
+ "peerDependencyRules:",
245
+ " allowedVersions:",
246
+ ...lines(allowedVersions, " ")
247
+ ].join("\n")
248
+ };
249
+ }
250
+ const fields = {
251
+ npm: {
252
+ dependencies: Object.fromEntries(effectPackages.filter((name) => direct.has(name)).map((name) => [name, effect])),
253
+ overrides: pins
254
+ },
255
+ pnpm: { pnpm: {
256
+ overrides: pins,
257
+ peerDependencyRules: { allowedVersions }
258
+ } },
259
+ yarn: { resolutions: pins },
260
+ bun: { overrides: pins }
261
+ }[manager];
262
+ return {
263
+ file: manager === "pnpm" && pnpmSettings.folder !== "." ? `${pnpmSettings.folder}/package.json` : "package.json",
264
+ language: "json",
265
+ text: JSON.stringify(fields, null, 2)
266
+ };
267
+ };
268
+ /** Why `manager` needs the pins, after "first merge this into `package.json`". */
269
+ const pinsWhy = {
270
+ 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",
271
+ pnpm: "`overrides` sets the version, and `peerDependencyRules` lets Foldkit's exact peers accept it",
272
+ yarn: "`resolutions` sets the version; Yarn warns of Foldkit's exact peers, and installs",
273
+ bun: "`overrides` sets the version; Bun warns of Foldkit's exact peers, and installs"
274
+ };
275
+ /**
276
+ * The command that adds `packages` with `manager`, at exactly the versions
277
+ * named when `exact`. A range a shell would read (`^`, `>`, a space) is quoted.
278
+ */
279
+ const addCommand = (manager, packages, exact = false) => [
280
+ manager,
281
+ manager === "npm" ? "install" : "add",
282
+ ...exact ? [manager === "npm" || manager === "pnpm" ? "--save-exact" : "--exact"] : [],
283
+ ...packages.map((spec) => /^[\w@/.-]+$/.test(spec) ? spec : `"${spec}"`)
284
+ ].join(" ");
202
285
  /** The major version a range asks for: `^4.0.0`, `~4.1`, `4.0.0-beta.1` all ask for 4. */
203
286
  const majorOf = (range) => Option.fromNullishOr(/(\d+)/.exec(range)?.[1]).pipe(Option.map(Number));
204
287
  /** What the project has of a library against what this release needs, as a line to act on. */
@@ -209,31 +292,59 @@ const finding = (project, library, wanted) => Option.match(Option.fromNullishOr(
209
292
  }
210
293
  });
211
294
  const setupGuide = ({ project, manager, versions }) => {
295
+ const listed = Option.match(project, {
296
+ onNone: () => [],
297
+ onSome: (found) => effectPackages.filter((name) => found.versions[name] !== void 0)
298
+ });
299
+ const moved = /* @__PURE__ */ new Set([
300
+ "effect",
301
+ "@effect/platform-browser",
302
+ ...listed
303
+ ]);
304
+ const pins = pinsOf(manager, versions.effect, moved, Option.match(project, {
305
+ onNone: () => ({
306
+ folder: ".",
307
+ file: "package.json"
308
+ }),
309
+ onSome: (found) => found.pnpmSettings
310
+ }));
311
+ const uiPeer = Option.exists(project, (found) => found.versions["@foldkit/devtools"] !== void 0 && found.versions["@foldkit/ui"] === void 0);
212
312
  const install = addCommand(manager, [
213
- `effect@${versions.effect}`,
313
+ ...manager === "npm" ? [] : effectPackages.filter((name) => moved.has(name)).map((name) => `${name}@${versions.effect}`),
214
314
  `foldkit@${versions.foldkit}`,
215
- `@effect/platform-browser@${versions.effect}`,
315
+ ...uiPeer ? [`@foldkit/ui@${versions.foldkit}`] : [],
216
316
  "foldkit-plus"
217
- ]);
317
+ ], true);
218
318
  const check = Option.match(project, {
219
319
  onNone: () => [
220
320
  "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
321
  "",
222
322
  `- ${GREENFIELD} (in the skill of step 3, \`references/greenfield.md\`)`,
223
323
  "",
224
- "When its first step has a name and a rendering mode, it scaffolds with:",
324
+ `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
325
  "",
226
326
  "```bash",
227
- `npx ${SCAFFOLDER} --name <name> --rendering <spa|ssg|ssr> --example counter --package-manager ${manager}`,
327
+ `npx ${SCAFFOLDER} --name <name> --rendering spa --example counter --package-manager ${manager}`,
328
+ `npx ${manager === "npm" ? "--force " : ""}${SCAFFOLDER} --name <name> --rendering ssg --package-manager ${manager}`,
329
+ `npx ${SCAFFOLDER} --name <name> --rendering ssr --package-manager ${manager}`,
228
330
  "```",
229
331
  "",
230
- "Then run `npx foldkit-plus setup` again in the new folder and continue from step 2."
332
+ "Then run `npx --legacy-peer-deps foldkit-plus setup` again in the new folder and continue from step 2."
231
333
  ],
232
334
  onSome: (found) => [
233
335
  `This is \`${found.name}\`, installed with ${manager}.`,
234
336
  "",
235
337
  finding(found, "effect", versions.effect),
236
- finding(found, "foldkit", versions.foldkit)
338
+ finding(found, "foldkit", versions.foldkit),
339
+ ...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
+ ...found.gitattributes ? ["- `.gitattributes` is there: leave it as it is."] : [
341
+ "- 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:",
342
+ "",
343
+ "```gitattributes",
344
+ "* text=auto eol=lf",
345
+ "*.wasm binary",
346
+ "```"
347
+ ]
237
348
  ]
238
349
  });
239
350
  return [
@@ -253,6 +364,14 @@ const setupGuide = ({ project, manager, versions }) => {
253
364
  "",
254
365
  "## 2. Install",
255
366
  "",
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"}):`,
368
+ "",
369
+ `\`\`\`${pins.language}`,
370
+ pins.text,
371
+ "```",
372
+ "",
373
+ "Then install:",
374
+ "",
256
375
  "```bash",
257
376
  install,
258
377
  "```",
@@ -267,10 +386,15 @@ const setupGuide = ({ project, manager, versions }) => {
267
386
  "npx skills add doeixd/foldkit-plus --skill foldkit-plus",
268
387
  "```",
269
388
  "",
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.",
389
+ "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
390
  ...Option.match(project, {
272
391
  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.`]
392
+ onSome: () => [
393
+ "",
394
+ `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.`,
395
+ "",
396
+ `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.`
397
+ ]
274
398
  }),
275
399
  "",
276
400
  "## 4. Import",
@@ -302,6 +426,6 @@ const setupGuide = ({ project, manager, versions }) => {
302
426
  ""
303
427
  ].join("\n");
304
428
  };
305
- export { SCAFFOLDER, adapters, addCommand, jobs, setupGuide };
429
+ export { SCAFFOLDER, adapters, addCommand, effectPackages, jobs, setupGuide };
306
430
 
307
431
  //# sourceMappingURL=setup.mjs.map