forgebook 0.3.3 → 0.4.1

package/dist/bin/forgebook/migrate/objectEdits.js

@@ -0,0 +1,241 @@
+/**
+ * The text edits the codemods of `forgebook migrate` share: a file parsed, a configuration's object found, properties of an
+ * object literal removed or added, and edits applied.
+ *
+ * @remarks
+ * The file is edited as text, at the places the compiler's tree gives, so everything a codemod does not touch keeps its
+ * formatting and comments: printing the tree again would rewrite the whole file in the printer's style. A property alone on
+ * its lines is removed with its lines; one sharing a line with others is cut out of it.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/** How deep a configuration's name is followed back to the object it holds (`const config = …; export default config`). */
+const NAME_DEPTH = 4;
+/**
+ * The kind of script a file is, by its extension: JSX is only read in a file that may hold it.
+ *
+ * @param path - the file's path.
+ */
+const scriptKindOf = (path) => {
+    if (path.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (path.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(path))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+};
+/**
+ * A file's tree, with each node's parent set.
+ *
+ * @param text - the file's text.
+ * @param path - its path, for the kind of script.
+ */
+export const parsedFile = (text, path) => ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKindOf(path));
+/**
+ * A property's name as written, when it is a plain one (`play`, `"propGroups.choice"`); none for a spread, a method or a
+ * computed name.
+ *
+ * @param element - the object literal's element.
+ */
+export const propertyName = (element) => {
+    if (!ts.isPropertyAssignment(element) && !ts.isShorthandPropertyAssignment(element))
+        return undefined;
+    const { name } = element;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNoSubstitutionTemplateLiteral(name))
+        return name.text;
+    return undefined;
+};
+/**
+ * The value a name is given where the file declares it at its top (`const config = …`); none when it is not declared so.
+ *
+ * @param name - the name.
+ * @param file - the file.
+ */
+const declaredValue = (name, file) => file.statements
+    .flatMap((statement) => ts.isVariableStatement(statement) ? [...statement.declarationList.declarations] : [])
+    .find((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name)?.initializer;
+/** Whether an expression only wraps another: parentheses, `satisfies`, `as`. */
+const isWrapper = (expression) => ts.isParenthesizedExpression(expression) ||
+    ts.isSatisfiesExpression(expression) ||
+    ts.isAsExpression(expression);
+/**
+ * The object literal an expression stands for, through parentheses, `satisfies`, `as`, `defineConfig(…)` and a name
+ * declared in the file.
+ *
+ * @param expression - the expression.
+ * @param file - the file, for its declarations.
+ * @param depth - how many more names may be followed.
+ */
+const objectOf = (expression, file, depth) => {
+    if (ts.isObjectLiteralExpression(expression))
+        return expression;
+    if (isWrapper(expression))
+        return objectOf(expression.expression, file, depth);
+    if (ts.isCallExpression(expression)) {
+        const [first] = expression.arguments;
+        const isDefine = ts.isIdentifier(expression.expression) && expression.expression.text === "defineConfig";
+        return isDefine && first !== undefined ? objectOf(first, file, depth) : undefined;
+    }
+    if (!ts.isIdentifier(expression) || depth === 0)
+        return undefined;
+    const value = declaredValue(expression.text, file);
+    return value === undefined ? undefined : objectOf(value, file, depth - 1);
+};
+/**
+ * The object literal an expression stands for, as written in the file (through a name it declares, `satisfies`, `as`);
+ * none when it is built some other way.
+ *
+ * @param expression - the expression.
+ * @param file - the file.
+ */
+export const objectLiteralOf = (expression, file) => objectOf(expression, file, NAME_DEPTH);
+/**
+ * The object a configuration file exports by default, as written in it; none when the file builds it some other way (a
+ * function's result, an import).
+ *
+ * @param file - the configuration's tree.
+ */
+export const defaultExportObject = (file) => {
+    for (const statement of file.statements) {
+        if (ts.isExportAssignment(statement) && statement.isExportEquals !== true)
+            return objectOf(statement.expression, file, NAME_DEPTH);
+    }
+    return undefined;
+};
+/** The line ending a text uses: CRLF when any line ends so, LF otherwise. */
+const lineEndingOf = (text) => (text.includes("\r\n") ? "\r\n" : "\n");
+/** Where the line holding an offset starts. */
+const lineStart = (text, at) => text.lastIndexOf("\n", at - 1) + 1;
+/** Whether only spaces come before an offset on its line. */
+const isLineLead = (text, at) => text.slice(lineStart(text, at), at).trim() === "";
+/**
+ * Where the line after an offset ends, newline included, when only a comma, spaces and a line comment follow the offset on
+ * it; none when more code follows.
+ */
+const lineTailEnd = (text, at) => {
+    const newline = text.indexOf("\n", at);
+    const end = newline === -1 ? text.length : newline + 1;
+    return /^[ \t]*,?[ \t]*(\/\/[^\n]*)?\r?\n?$/.test(text.slice(at, end)) ? end : undefined;
+};
+/** The edit removing the comma right after an offset, past spaces; none when no comma comes next. */
+const commaAfter = (text, at) => {
+    const comma = /^\s*,/.exec(text.slice(at));
+    return comma === null
+        ? undefined
+        : { start: at + comma[0].length - 1, end: at + comma[0].length, insert: "" };
+};
+/**
+ * The runs of neighbouring properties to remove, so that no two edits meet.
+ *
+ * @param elements - the object's properties.
+ * @param removed - those to remove.
+ */
+const removedRuns = (elements, removed) => {
+    const runs = [];
+    elements.forEach((element, index) => {
+        if (!removed.has(element))
+            return;
+        const previous = runs[runs.length - 1];
+        if (previous !== undefined && previous.last === index - 1)
+            runs[runs.length - 1] = { ...previous, last: index };
+        else
+            runs.push({ first: index, last: index });
+    });
+    return runs;
+};
+/**
+ * The edits that remove one run: its lines when it has them to itself, else its text with the comma that joins it.
+ *
+ * @param file - the file's tree.
+ * @param elements - the object's properties.
+ * @param run - the run.
+ */
+const runEdits = (file, elements, { first, last }) => {
+    const text = file.text;
+    const before = elements[first - 1];
+    const after = elements[last + 1];
+    const start = elements[first]?.getStart(file) ?? 0;
+    const end = elements[last]?.end ?? start;
+    const tail = lineTailEnd(text, end);
+    if (isLineLead(text, start) && tail !== undefined) {
+        const lines = { start: lineStart(text, start), end: tail, insert: "" };
+        // the run was the end of the object: the property now last loses the comma it no longer needs
+        const isEnd = after === undefined && !elements.hasTrailingComma && before !== undefined;
+        const comma = isEnd ? commaAfter(text, before.end) : undefined;
+        return comma === undefined ? [lines] : [lines, comma];
+    }
+    if (after !== undefined)
+        return [{ start, end: after.getStart(file), insert: "" }];
+    return before === undefined ? [] : [{ start: before.end, end, insert: "" }];
+};
+/**
+ * The edits that remove some of an object literal's properties, keeping the others as written. Removing all of them leaves
+ * `{}`.
+ *
+ * @param file - the file's tree.
+ * @param object - the object literal.
+ * @param removed - the properties to remove, of that object.
+ */
+export const removalEdits = (file, object, removed) => {
+    const elements = object.properties;
+    if (elements.every((element) => removed.has(element)))
+        return [{ start: object.getStart(file) + 1, end: object.end - 1, insert: "" }];
+    return removedRuns(elements, removed).flatMap((run) => runEdits(file, elements, run));
+};
+/**
+ * The edit that adds a property to an object literal before one of its properties, or after the last when none is given,
+ * in the object's own layout: on a line of its own when the properties are, inline when they share one.
+ *
+ * @param file - the file's tree.
+ * @param object - the object literal.
+ * @param property - the property's text (`play: "on"`), with no comma.
+ * @param before - the property it goes before; none for the end.
+ * @returns the edits: one, or two when the last property needs a comma before the new one.
+ */
+export const insertionEdit = (file, object, property, before) => {
+    const text = file.text;
+    const eol = lineEndingOf(text);
+    const elements = object.properties;
+    const last = elements[elements.length - 1];
+    if (last === undefined) {
+        const inside = object.getStart(file) + 1;
+        return [{ start: inside, end: object.end - 1, insert: ` ${property} ` }];
+    }
+    if (before !== undefined) {
+        const start = before.getStart(file);
+        if (!isLineLead(text, start))
+            return [{ start, end: start, insert: `${property}, ` }];
+        const from = lineStart(text, start);
+        return [{ start: from, end: from, insert: `${text.slice(from, start)}${property},${eol}` }];
+    }
+    const start = last.getStart(file);
+    const tail = lineTailEnd(text, last.end);
+    if (!isLineLead(text, start) || tail === undefined)
+        return [{ start: last.end, end: last.end, insert: `, ${property}` }];
+    // a line of its own after the last property's, so that a comment ending that line stays with it
+    const indent = text.slice(lineStart(text, start), start);
+    const line = `${indent}${property}${elements.hasTrailingComma ? "," : ""}${text.endsWith("\n", tail) ? eol : ""}`;
+    const added = { start: tail, end: tail, insert: tail === text.length ? `${eol}${line}` : line };
+    return elements.hasTrailingComma ? [added] : [{ start: last.end, end: last.end, insert: "," }, added];
+};
+/**
+ * A text with edits applied, from the last to the first so that each offset still holds.
+ *
+ * @param text - the text.
+ * @param edits - the edits, in any order.
+ * @throws when two edits overlap, which would make the result depend on their order.
+ */
+export const appliedEdits = (text, edits) => {
+    const sorted = [...edits].sort((left, right) => right.start - left.start || right.end - left.end);
+    let result = text;
+    let floor = Number.POSITIVE_INFINITY;
+    for (const edit of sorted) {
+        if (edit.end > floor)
+            throw new Error(`two edits overlap at ${edit.start}`);
+        result = `${result.slice(0, edit.start)}${edit.insert}${result.slice(edit.end)}`;
+        floor = edit.start;
+    }
+    return result;
+};

package/dist/bin/forgebook/migrate/playOnInBuilds.d.ts

@@ -0,0 +1,3 @@
+import type { Codemod } from "./migrate.types.ts";
+/** The codemod. */
+export declare const playOnInBuilds: Codemod;

package/dist/bin/forgebook/migrate/playOnInBuilds.js

@@ -0,0 +1,86 @@
+/**
+ * The codemod for plays in a build: a built catalogue no longer runs a story's play when it opens, since a reader of
+ * published docs did not ask for it. A catalogue that relied on it gets `play: "on"` in its configuration, which keeps the
+ * behaviour on the dev server and in a build alike.
+ *
+ * @remarks
+ * It keeps an old behaviour rather than rewriting what broke, so it runs only for a project coming from before the change
+ * (`--from`): run again on a project that left `play` out on purpose, it would undo that choice.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { defaultExportObject, insertionEdit, parsedFile, propertyName } from "./objectEdits.js";
+/** The quote the object's own strings use, so that the added one matches them; double when it has none. */
+const quoteOf = (file, object) => {
+    let quote;
+    const visit = (node) => {
+        if (quote !== undefined)
+            return;
+        if (ts.isStringLiteral(node)) {
+            quote = file.text.charAt(node.getStart(file));
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(object);
+    return quote === "'" ? "'" : '"';
+};
+/** Whether a file names `play` as a property anywhere: in the configuration, or in an object it spreads or is built from. */
+const namesPlay = (file) => {
+    let isFound = false;
+    const visit = (node) => {
+        if (isFound)
+            return;
+        if ((ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) &&
+            ts.isObjectLiteralExpression(node.parent) &&
+            propertyName(node) === "play") {
+            isFound = true;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return isFound;
+};
+/**
+ * The edit to the configuration: `play: "on"` after its title, unless the file says `play` already. A configuration it
+ * cannot see into gets advice, which leaves the exit code alone: it may need nothing.
+ *
+ * @param text - the configuration's text.
+ * @param path - its path.
+ */
+const run = (text, path) => {
+    const file = parsedFile(text, path);
+    if (namesPlay(file))
+        return { edits: [], advice: [] };
+    const object = defaultExportObject(file);
+    if (object === undefined)
+        return {
+            edits: [],
+            advice: [
+                'The configuration\'s object is not written in this file: if plays should still run when a built story opens, write play: "on" in it.'
+            ]
+        };
+    if (object.properties.some(ts.isSpreadAssignment))
+        return {
+            edits: [],
+            advice: [
+                'The configuration spreads an object from elsewhere: if plays should still run when a built story opens, write play: "on" in it.'
+            ]
+        };
+    const names = object.properties.map(propertyName);
+    const title = names.indexOf("title");
+    const before = object.properties[title === -1 ? 0 : title + 1];
+    const quote = quoteOf(file, object);
+    return { edits: insertionEdit(file, object, `play: ${quote}on${quote}`, before), advice: [] };
+};
+/** The codemod. */
+export const playOnInBuilds = {
+    id: "play-on-in-builds",
+    breaksIn: "0.4.0",
+    kind: "keep",
+    files: ["config"],
+    summary: 'Writes play: "on", so a built catalogue still runs a story\'s play when it opens; leave it out to take the new default, where a build waits for Run.',
+    run
+};

package/dist/bin/forgebook/migrate/propGroupStrings.d.ts

@@ -0,0 +1,5 @@
+import type { Codemod } from "./migrate.types.ts";
+/** The strings the Props tab no longer has. */
+export declare const REMOVED_PROP_GROUP_STRINGS: ReadonlySet<string>;
+/** The codemod. */
+export declare const propGroupStrings: Codemod;

package/dist/bin/forgebook/migrate/propGroupStrings.js

@@ -0,0 +1,81 @@
+/**
+ * The codemod for the Props tab's control groups: the shell's strings `propGroups.choice`, `.text`, `.structured` and
+ * `.toggle` named their headings, and the tab now lists props in the order their source declares them, with no such
+ * headings. A catalogue's `strings` naming them replaces nothing any more, so they are removed, from the configuration and
+ * from any preset module given.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { objectLiteralOf, parsedFile, propertyName, removalEdits } from "./objectEdits.js";
+/** The strings the Props tab no longer has. */
+export const REMOVED_PROP_GROUP_STRINGS = new Set([
+    "propGroups.choice",
+    "propGroups.text",
+    "propGroups.structured",
+    "propGroups.toggle"
+]);
+/** Whether an object's element is one of the strings removed. */
+const isRemovedString = (element) => {
+    const name = propertyName(element);
+    return name !== undefined && REMOVED_PROP_GROUP_STRINGS.has(name);
+};
+/** Whether an object's element has a name only running the code would tell: a computed key or a spread. */
+const isUnreadName = (element) => ts.isSpreadAssignment(element) || (element.name !== undefined && ts.isComputedPropertyName(element.name));
+/** What a `strings` property holds: its own object, the object a name it uses is given in the file, or none. */
+const stringsObject = (property, file) => ts.isShorthandPropertyAssignment(property)
+    ? objectLiteralOf(property.name, file)
+    : objectLiteralOf(property.initializer, file);
+/** Whether a node is an object's `strings` property, written out or shorthand. */
+const isStringsProperty = (node) => (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) &&
+    ts.isObjectLiteralExpression(node.parent) &&
+    propertyName(node) === "strings";
+/** Advice for strings the codemod cannot read. */
+const UNREAD_STRINGS = "These strings are not all written in this file: if they name propGroups.choice, .text, .structured or .toggle, remove them, since the Props tab no longer has them.";
+/**
+ * The edits to one file: in every `strings` object, written in place or in a name the file declares, the removed strings
+ * out, and a `strings: { … }` left with nothing out as well.
+ *
+ * @param text - the file's text.
+ * @param path - its path.
+ */
+const run = (text, path) => {
+    const file = parsedFile(text, path);
+    const edits = [];
+    const advice = new Set();
+    // an object two configurations share through one name is rewritten once
+    const done = new Set();
+    const visit = (node) => {
+        ts.forEachChild(node, visit);
+        if (!isStringsProperty(node))
+            return;
+        const strings = stringsObject(node, file);
+        if (strings === undefined) {
+            advice.add(UNREAD_STRINGS);
+            return;
+        }
+        if (strings.properties.some(isUnreadName))
+            advice.add(UNREAD_STRINGS);
+        if (done.has(strings))
+            return;
+        done.add(strings);
+        const removed = new Set(strings.properties.filter(isRemovedString));
+        if (removed.size === 0)
+            return;
+        const isInPlace = ts.isPropertyAssignment(node) && node.initializer === strings;
+        edits.push(...(isInPlace && removed.size === strings.properties.length
+            ? removalEdits(file, node.parent, new Set([node]))
+            : removalEdits(file, strings, removed)));
+    };
+    visit(file);
+    return { edits, advice: [...advice] };
+};
+/** The codemod. */
+export const propGroupStrings = {
+    id: "prop-group-strings",
+    breaksIn: "0.4.0",
+    kind: "rewrite",
+    files: ["config", "module"],
+    summary: "Removes the strings propGroups.choice, .text, .structured and .toggle: the Props tab lists props in their source's order, with no such headings.",
+    run
+};

package/dist/bin/forgebook/newProject/newProject.d.ts

@@ -0,0 +1,39 @@
+import type { ImportedFramework } from "../importers/storybookFrameworks.ts";
+import type { NextStep } from "./newProject.types.ts";
+/** What `forgebook init` will write for a project. */
+export type NewProjectPlan = {
+    /** The framework. */
+    readonly framework: ImportedFramework;
+    /** Its adapter's options; none for the defaults. */
+    readonly frameworkOptions: Readonly<Record<string, unknown>> | undefined;
+    /** The catalogue's name. */
+    readonly title: string;
+    /** The story globs. */
+    readonly stories: readonly string[];
+    /** The preview, when the project has something for it to load. */
+    readonly preview: {
+        readonly file: string;
+        readonly text: string;
+    } | undefined;
+    /** What was left to do. */
+    readonly nextSteps: readonly NextStep[];
+    /** The packages the project's own setup asks for, beyond the adapter's. */
+    readonly extraPeers: readonly string[];
+};
+/**
+ * The configuration's story globs, and whether the search for story files stopped short.
+ *
+ * @param projectDir - the project's folder.
+ * @param framework - its framework.
+ */
+export declare const storyGlobsOf: (projectDir: string, framework: ImportedFramework) => {
+    readonly globs: readonly string[];
+    readonly isCut: boolean;
+};
+/**
+ * What `forgebook init` will write for a project.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @param framework - its framework.
+ */
+export declare const planNewProject: (projectDir: string, framework: ImportedFramework) => NewProjectPlan;

package/dist/bin/forgebook/newProject/newProject.js

@@ -0,0 +1,180 @@
+/**
+ * What `forgebook init` writes for a project with no Storybook: its framework read from `package.json`, the adapter's
+ * options, the story globs, and the preview that loads the app's global style sheets.
+ *
+ * @remarks
+ * Nothing is written here: the plan comes back whole, so a refusal leaves the project as it was. Story globs carry the
+ * extension `forgebook new` writes for the framework, and any folder that already has story files. A project with `src`
+ * keeps its components there; one without lists every usual folder, an absent one included, since create-next-app's
+ * `components` appears later. They are one pattern, braces and all, because a command stops on any pattern that matches
+ * nothing (a misspelt one looks the same), and a project's first story fills only one of its folders. The preview
+ * is `.tsx` where stories are, so the decorator a next step asks for needs no rename.
+ *
+ * @module
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { STORY_FILE } from "../../../src/vite/autoTitle.js";
+import { projectTitle } from "../importers/storybook.js";
+import { PROJECT_FRAMEWORKS } from "./projectFrameworks.js";
+import { hasPostcssConfig, readProjectLook } from "./projectLook.js";
+import { declaredPackages, installedVersion } from "./projectPackages.js";
+/** The folders never searched for story files: what is installed, built, or the tools' own. */
+const SKIPPED_FOLDERS = new Set(["node_modules", "dist", "build", "out", "coverage", "public"]);
+/** How many folders a search for story files goes through, so a huge repository's first run stays quick. */
+const SEARCH_LIMIT = 5000;
+/** A folder's entries; none for one the command may not read, which only leaves its stories out. */
+const readableEntries = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+/** The folders to search below a folder. */
+const foldersBelow = ({ dir, top }, entries) => entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !SKIPPED_FOLDERS.has(entry.name))
+    .map((entry) => ({ dir: join(dir, entry.name), top: top || entry.name }));
+/** The folders holding story files already, and those files' extensions. */
+const existingStories = (projectDir) => {
+    const folders = new Set();
+    const extensions = new Set();
+    const queue = [{ dir: projectDir, top: "" }];
+    for (const current of queue) {
+        if (queue.length > SEARCH_LIMIT)
+            break;
+        const entries = readableEntries(current.dir);
+        for (const folder of foldersBelow(current, entries))
+            queue.push(folder);
+        for (const { name } of entries.filter((entry) => entry.isFile() && STORY_FILE.test(entry.name))) {
+            folders.add(current.top);
+            extensions.add(name.slice(name.lastIndexOf(".") + 1));
+        }
+    }
+    return { folders, extensions, isCut: queue.length > SEARCH_LIMIT };
+};
+/** A glob's alternatives: one as it is, several in braces. */
+const oneOf = (names) => names.length === 1 ? (names[0] ?? "") : `{${names.join(",")}}`;
+/**
+ * The configuration's story globs, and whether the search for story files stopped short.
+ *
+ * @param projectDir - the project's folder.
+ * @param framework - its framework.
+ */
+export const storyGlobsOf = (projectDir, framework) => {
+    const { sourceFolders, storyExtension } = PROJECT_FRAMEWORKS[framework];
+    const isThere = (folder) => existsSync(join(projectDir, folder));
+    const hasSrc = sourceFolders.includes("src") && isThere("src");
+    const listed = hasSrc
+        ? ["src"]
+        : [...sourceFolders].sort((a, b) => Number(isThere(b)) - Number(isThere(a)));
+    const stories = existingStories(projectDir);
+    const extensions = [...new Set([storyExtension, ...stories.extensions])];
+    const folders = [...new Set([...listed, ...stories.folders])];
+    const extension = oneOf(extensions);
+    const nested = folders.filter((folder) => folder !== "");
+    const globs = [
+        ...(folders.includes("") ? [`*.stories.${extension}`] : []),
+        ...(nested.length === 0 ? [] : [`${oneOf(nested)}/**/*.stories.${extension}`])
+    ];
+    return { globs, isCut: stories.isCut };
+};
+/**
+ * What React Native's adapter must be told of a project: the JSX runtime of NativeWind, and the Babel plugin that
+ * compiles Reanimated's worklets, which Metro runs on the device and the catalogue must run here.
+ *
+ * @param projectDir - the project's folder.
+ * @param declared - the packages it declares.
+ */
+const reactNativeOptions = (projectDir, declared) => {
+    const reanimated = installedVersion(projectDir, "react-native-reanimated") ?? declared.get("react-native-reanimated");
+    const major = Number(reanimated?.match(/\d+/)?.[0] ?? 0);
+    const plugin = major >= 4 ? "react-native-worklets/plugin" : "react-native-reanimated/plugin";
+    const options = {
+        ...(declared.has("nativewind") ? { jsxImportSource: "nativewind" } : {}),
+        ...(reanimated === undefined ? {} : { babel: { plugins: [plugin] } })
+    };
+    return Object.keys(options).length === 0 ? undefined : options;
+};
+/** What a framework asks of a project besides the catalogue's own files. */
+const frameworkSteps = (projectDir, framework) => {
+    if (framework === "nuxt")
+        return [
+            {
+                kind: "provider",
+                file: "nuxt.config",
+                message: "Nuxt's modules are loaded for their plugins, styles and components, but what they and the app's plugins set up at run time is not: a component that needs one (a store, i18n) gets it from a decorator in forgebook.preview.ts"
+            }
+        ];
+    if (framework === "sveltekit" && !existsSync(join(projectDir, ".svelte-kit")))
+        return [
+            {
+                kind: "setup",
+                file: "tsconfig.json",
+                message: "Run `svelte-kit sync` before the catalogue: the project's tsconfig.json extends what it writes"
+            }
+        ];
+    if (framework === "react-native-web") {
+        const read = ["babel.config.js", "metro.config.js"].filter((name) => existsSync(join(projectDir, name)));
+        return read.length === 0
+            ? []
+            : [
+                {
+                    kind: "setup",
+                    file: read[0],
+                    message: `${read.join(" and ")} ${read.length === 1 ? "is" : "are"} not read: a plugin stories need goes to reactNativeWeb({ babel }) in the configuration`
+                }
+            ];
+    }
+    return [];
+};
+/** The text of the preview that loads the app's style sheets. */
+const previewText = (styleSheets) => [
+    "/**",
+    " * The catalogue's preview: what every story's frame loads, as the app's entry does. Written by `forgebook init`;",
+    " * decorators, a provider around every story and the like go here too.",
+    " *",
+    " * @module",
+    " */",
+    ...styleSheets.map((sheet) => `import ${JSON.stringify(sheet)};`),
+    ""
+].join("\n");
+/**
+ * What `forgebook init` will write for a project.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @param framework - its framework.
+ */
+export const planNewProject = (projectDir, framework) => {
+    const declared = declaredPackages(projectDir);
+    const look = readProjectLook(projectDir, framework, declared);
+    const { globs, isCut } = storyGlobsOf(projectDir, framework);
+    return {
+        framework,
+        frameworkOptions: framework === "react-native-web" ? reactNativeOptions(projectDir, declared) : undefined,
+        title: projectTitle(projectDir),
+        stories: globs,
+        preview: look.styleSheets.length === 0
+            ? undefined
+            : {
+                file: `forgebook.preview.${PROJECT_FRAMEWORKS[framework].storyExtension}`,
+                text: previewText(look.styleSheets)
+            },
+        nextSteps: [
+            ...frameworkSteps(projectDir, framework),
+            ...look.nextSteps,
+            ...(isCut
+                ? [
+                    {
+                        kind: "setup",
+                        file: undefined,
+                        message: `The search for story files stopped after ${SEARCH_LIMIT} folders: add the globs of any it missed`
+                    }
+                ]
+                : [])
+        ],
+        // React Native's adapter imports PostCSS when the project has a configuration for it
+        extraPeers: framework === "react-native-web" && hasPostcssConfig(projectDir) ? ["postcss"] : []
+    };
+};