forgebook 0.3.2 → 0.4.0

package/dist/bin/forgebook/guide/switches.md

@@ -0,0 +1,43 @@
+# Switches, galleries and themes
+
+`forgebook switches --json` (`list_switches`) lists what a catalogue offers: each switch's id, its `control` and its
+values, each with the `view` to write (`--view look=night`), what it `implies`, its `sheet` and its `preview`.
+
+A catalogue declares them in `forgebook.config.ts`:
+
+```ts
+switches: [
+  { id: "theme", label: "Appearance", role: "colorScheme", default: "light",
+    apply: { kind: "attribute", name: "data-theme" },
+    values: [{ value: "light", label: "Light", scheme: "light" }, { value: "dark", label: "Dark", scheme: "dark" }] },
+  { id: "look", label: "Theme", control: "gallery", default: "plain",
+    apply: { kind: "attribute", name: "data-look" },
+    values: [
+      { value: "plain", label: "Plain", isUnset: true },
+      { value: "paper", label: "Paper", preview: { image: "previews/paper.png" }, sheet: "looks/paper.css" },
+      { value: "night", label: "Night", preview: { swatches: ["#0b1020", "#7c8cff"], font: "Harbor Sans" },
+        implies: { theme: "dark" }, sheet: "looks/night.css" }
+    ] }
+]
+```
+
+- **`control: "gallery"`** is a menu whose items show each value's `preview`. Its code and pictures load only when it
+  first opens. A value with no preview shows its label's first letter. The control's name comes from the switch and each
+  item's from the value's `label`, never from the picture.
+- **`preview`** is `{ image }`, a file by its path, or `{ swatches, font }`, 1 to 8 plain colours and a font's name.
+  A font is only a name: drawn in it where the reader has it installed, never fetched. An address is refused, in `image`
+  and in `sheet`, as are `url()` in a colour and a preview on a switch that is no gallery: the configuration's check
+  stops every command with the value's name.
+- **`implies`** sets other switches while the value is drawn. The implied switch's control is off and says what sets it;
+  its key does nothing. The address keeps the reader's own value, which returns when the value is left, so
+  `look=night&theme=light` draws dark. It wins over the address and over a story's `globals`. Between two values that imply
+  different values of one switch, the switch declared first wins. An implied value may imply nothing further. Compare
+  leaves out a cell it contradicts: `look,theme` shows Night only at dark, and Compare cannot pick a switch implied now.
+- **`sheet`** is a style sheet of that value alone, in dev and in a build, loaded with Styles › Full only, after the source's
+  sheets, the switches' in the order declared. Its path may not be an address; its contents are the author's own CSS. On a change the old sheet stays until the new one has loaded, and the root's
+  attributes move with it, so no frame is drawn with neither.
+- **A source's page colour** can follow a switch, so a story's box waits on the right colour:
+  `background: { light, dark, bySwitch: { look: { night: { dark: "#0b1020" } } } }`. The first declared switch whose
+  value gives the scheme's colour wins; otherwise `light` and `dark`.
+- The reader's own **Interface** menu, at the sidebar's foot, colours the catalogue around the stories and never the
+  stories themselves. `strings: { appearance: "…" }` renames it; the `appearance` setting keeps its name.

package/dist/bin/forgebook/guideCommand.d.mts

@@ -0,0 +1,13 @@
+/**
+ * `forgebook guide`: the rest of what `forgebook agents` leaves out of a project's files, printed a topic at a time.
+ *
+ * @module
+ */
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const guideCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/guideCommand.mjs

@@ -0,0 +1,37 @@
+import { formatJson } from "@ensiria/cli-kit/files";
+import { table } from "@ensiria/cli-kit/layout";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { guideList, guideTopic, projectFrameworks } from "./agentGuide.js";
+import { COMMAND, configPathOf } from "./catalogueCommands.js";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const guideCommands = (forgebook) => ({
+    guide: forgebook.command({
+        summary: "Print Forgebook's guide for coding agents: a framework's or a topic's full text, on demand.",
+        json: true,
+        positionals: [{ name: "topic", description: "The topic or the framework; none lists them." }],
+        examples: [
+            { command: `${COMMAND} guide`, description: "The topics, and this project's framework." },
+            { command: `${COMMAND} guide vue`, description: "Stories in Vue." },
+            { command: `${COMMAND} guide docs-pages`, description: "Writing a docs page." }
+        ],
+        run: ({ args, options, io, isJson, style }) => {
+            if (args.topic === undefined) {
+                const frameworks = projectFrameworks(configPathOf(options.config), process.cwd());
+                const list = guideList(frameworks);
+                const about = table(list.topics.map((each) => [each.topic, each.about]), { columns: [{ header: "Topic" }, { header: "What it holds" }] }, style);
+                const found = frameworks.length === 0 ? "" : `\n\nThis project: ${frameworks.join(", ")}`;
+                io.stdout.write(isJson ? formatJson(list) : `${about}${found}\n`);
+                return;
+            }
+            const topic = guideTopic(args.topic);
+            if (topic === undefined) {
+                throw new ScriptError(`No topic ${args.topic}`, { hint: `${COMMAND} guide lists them` });
+            }
+            io.stdout.write(isJson ? formatJson(topic) : `${topic.text}\n`);
+        }
+    })
+});

package/dist/bin/forgebook/importers/storybook.d.ts

@@ -18,6 +18,8 @@ export type ImportedConfig = {
     /** What was not read, each a sentence for the person who runs the command. */
     readonly notes: readonly string[];
 };
+/** Whether a value is a plain object. */
+export declare const isRecord: (value: unknown) => value is Readonly<Record<string, unknown>>;
 /**
  * Every glob a glob with alternatives stands for: `@(a|b)`, `?(a|b)` and `{a,b}` written out, nested ones too, so the
  * configuration lists plain globs a person reads at a glance.
@@ -50,6 +52,25 @@ export declare const previewSwitches: (text: string, file: string) => {
     readonly switches: ViewSwitch[] | undefined;
     readonly notes: string[];
 };
+/**
+ * The project's name: its package's, or its folder's.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const projectTitle: (dir: string) => string;
+/**
+ * The project's `package.json`, parsed; empty when it has none.
+ *
+ * @param dir - the project's folder.
+ */
+export declare const projectManifest: (dir: string) => Readonly<Record<string, unknown>>;
+/**
+ * The Storybook folder of a project: the first of Storybook's folders that holds a `main`.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @returns its path, or none for a project without one.
+ */
+export declare const findStorybookDir: (projectDir: string) => string | undefined;
 /**
  * Reads a project's Storybook configuration.
  *

package/dist/bin/forgebook/importers/storybook.js

@@ -36,7 +36,7 @@ const DEFAULT_FILES = "**/*.@(mdx|stories.@(js|jsx|mjs|ts|tsx))";
 /** The names `main` and the preview may have, in the order Storybook looks for them. */
 const SCRIPT_EXTENSIONS = ["ts", "mts", "tsx", "js", "mjs", "cjs", "jsx"];
 /** Whether a value is a plain object. */
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
  * The first file of a name that exists in a folder, whatever its script extension.
  *
@@ -283,7 +283,7 @@ export const previewSwitches = (text, file) => {
  *
  * @param dir - the project's folder.
  */
-const projectTitle = (dir) => {
+export const projectTitle = (dir) => {
     const manifest = projectManifest(dir);
     return typeof manifest["name"] === "string" && manifest["name"] !== "" ? manifest["name"] : basename(dir);
 };
@@ -292,7 +292,7 @@ const projectTitle = (dir) => {
  *
  * @param dir - the project's folder.
  */
-const projectManifest = (dir) => {
+export const projectManifest = (dir) => {
     const file = join(dir, "package.json");
     const parsed = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
     return isRecord(parsed) ? parsed : {};
@@ -333,6 +333,13 @@ const loadedMain = async (mainFile, projectDir) => {
     const main = isRecord(loaded) && isRecord(loaded["default"]) ? loaded["default"] : loaded;
     return isRecord(main) ? main : `${relative(projectDir, mainFile)} exports no configuration`;
 };
+/**
+ * The Storybook folder of a project: the first of Storybook's folders that holds a `main`.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @returns its path, or none for a project without one.
+ */
+export const findStorybookDir = (projectDir) => STORYBOOK_DIRS.map((name) => join(projectDir, name)).find((dir) => scriptFile(dir, "main") !== undefined);
 /**
  * Reads a project's Storybook configuration.
  *
@@ -340,8 +347,7 @@ const loadedMain = async (mainFile, projectDir) => {
  * @returns what a Forgebook configuration takes from it, or why it cannot be read.
  */
 export const importStorybook = async (projectDir) => {
-    const found = STORYBOOK_DIRS.map((name) => join(projectDir, name)).find((dir) => scriptFile(dir, "main") !== undefined);
-    const storybookDir = found ?? join(projectDir, STORYBOOK_DIRS[0] ?? ".storybook");
+    const storybookDir = findStorybookDir(projectDir) ?? join(projectDir, STORYBOOK_DIRS[0] ?? ".storybook");
     const mainFile = scriptFile(storybookDir, "main");
     if (mainFile === undefined)
         return `No .storybook/main (or .rnstorybook/main) file in ${projectDir}`;

package/dist/bin/forgebook/importers/storybookFrameworks.js

@@ -61,7 +61,7 @@ const STORYBOOK_FRAMEWORKS = {
 export const STORYBOOK_PACKAGES = Object.keys(STORYBOOK_FRAMEWORKS);
 /** What a Nuxt project's stories get differently once moved, said once the configuration is written. */
 const NUXT_NOTES = [
-    "Nuxt's modules and plugins are not run: a component that needs what one provides (a store, i18n) gets it from a decorator",
+    "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",
     "A story's route, data, state and cookies are set with parameters.nuxt (route, data, state, cookies), not by a decorator that drives the router"
 ];
 /** Whether a value is a plain object. */

package/dist/bin/forgebook/initCommands.d.mts

@@ -1,3 +1,14 @@
+/**
+ * The command that starts a catalogue: `init` writes `forgebook.config.ts` from what a project's files say, so a new user
+ * or an agent gets a catalogue that draws in one command, with no question asked.
+ *
+ * @remarks
+ * Defined here, on the scope `forgebookCommands.mts` hands it, so the commands module stays a list of commands; what it
+ * does is `initRun.ts`'s. The run loads the compiler to read the project's files, so only this command loads it. A file
+ * already there is never replaced unless asked (`--force`): it may hold a person's work.
+ *
+ * @module
+ */
 import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
 import { type ForgebookOptions } from "./catalogueCommands.ts";
 /**

package/dist/bin/forgebook/initCommands.mjs

@@ -1,54 +1,7 @@
-/**
- * The command that starts a catalogue: `init --from storybook` writes `forgebook.config.ts` from a project's Storybook
- * files, so a project on Storybook tries Forgebook in one command, its stories read as they are.
- *
- * @remarks
- * Defined here, on the scope `forgebookCommands.mts` hands it, so the commands module stays a list of commands; the reading is the
- * importer's (`importers/storybook.ts`), the writing `initConfig.ts`'s. A configuration already there is never
- * replaced unless asked (`--force`): it may hold a person's work.
- *
- * @module
- */
-import { existsSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { join, resolve } from "node:path";
-import { ScriptError } from "@ensiria/cli-kit/script";
-import { CONFIG_FILES } from "../../src/vite/configFile.js";
+import { HOOK_NAMES } from "./agentSetup/hookNames.js";
 import { COMMAND } from "./catalogueCommands.js";
-import { frameworkPeers } from "./importers/storybookFrameworks.js";
-import { CONFIG_FILE, initConfigText } from "./initConfig.js";
-/**
- * The modules the written configuration needs, by the package that has each: what it imports, and the framework's
- * peers.
- *
- * @param imported - what the importer read: the framework and its options.
- */
-const configImports = (imported) => ({
-    forgebook: "forgebook",
-    [`@forgebook/${imported.framework}`]: `@forgebook/${imported.framework}/vite`,
-    ...Object.fromEntries(frameworkPeers(imported.framework, imported.frameworkOptions).map((peer) => [
-        peer,
-        `${peer}/package.json`
-    ]))
-});
-/**
- * The packages the written configuration needs that the project cannot load yet.
- *
- * @param dir - the project's folder.
- * @param imported - what the importer read: the framework and its options.
- */
-const missingPackages = (dir, imported) => {
-    const require = createRequire(join(dir, "package.json"));
-    return Object.entries(configImports(imported)).flatMap(([name, specifier]) => {
-        try {
-            require.resolve(specifier);
-            return [];
-        }
-        catch {
-            return [name];
-        }
-    });
-};
+import { CONFIG_FILE } from "./initConfig.js";
+import { FRAMEWORK_NAMES } from "./newProject/projectFrameworks.js";
 /**
  * The commands.
  *
@@ -56,45 +9,65 @@ const missingPackages = (dir, imported) => {
  */
 export const initCommands = (forgebook) => ({
     init: forgebook.command({
-        summary: "Write forgebook.config.ts from another tool's files: Storybook's story globs, preview and globals.",
+        summary: "Write forgebook.config.ts, and a preview with the app's global style sheets, from the project's files; with --agents, what a project's coding agents need too.",
+        json: true,
         options: {
             from: {
                 type: "string",
-                required: true,
                 choices: ["storybook"],
                 valueName: "tool",
-                description: "The tool whose files are read (its folder in the current one: .storybook, or on-device Storybook's .rnstorybook)."
+                description: "Read this tool's files (its folder in the current one: .storybook, or on-device Storybook's .rnstorybook). Loading its main runs the project's code."
+            },
+            framework: {
+                type: "string",
+                valueName: "name",
+                choices: [...FRAMEWORK_NAMES],
+                description: "The framework the stories are written for, when package.json does not settle it (html for none); starts from the dependencies even on Storybook."
+            },
+            install: {
+                type: "boolean",
+                description: "Run the package manager's install of what the configuration imports; as any install, it runs what the project's package manager settings and the packages' scripts say."
             },
-            force: { type: "boolean", description: `Replace a ${CONFIG_FILE} that is already there.` }
+            force: { type: "boolean", description: `Replace a ${CONFIG_FILE} or a preview that is already there.` },
+            agents: {
+                type: "boolean",
+                description: "Also set up the project's coding agents: .mcp.json, AGENTS.md and the skill, a CI workflow for verify, and a hook that runs verify. Merges, and never replaces; keeps a catalogue already there, and starts beside a Storybook."
+            },
+            hooks: {
+                type: "string",
+                valueName: "list",
+                description: `With --agents, the hooks to write, by commas: ${HOOK_NAMES.join(", ")}. By default those of the assistants the repository shows signs of, otherwise pre-commit.`
+            },
+            browser: {
+                type: "boolean",
+                description: "Install the testing package and its browser, which downloads about 200 MB; implies --install."
+            },
+            draw: {
+                type: "boolean",
+                description: "Then draw a story in the browser, trying components until one draws, and say why each that did not; exits 1 if none does. Runs the project's code (its vite.config, its components), and keeps the story that drew."
+            }
         },
         examples: [
+            { command: `${COMMAND} init`, description: "Read the project and write the files." },
+            { command: `${COMMAND} init --json`, description: "The same, as a document, for an agent." },
+            { command: `${COMMAND} init --from storybook`, description: "Read .storybook." },
             {
-                command: `${COMMAND} init --from storybook`,
-                description: "Read .storybook and write the configuration."
+                command: `${COMMAND} init --agents --browser --draw --json`,
+                description: "All of it, unattended, for an agent: ends with a story drawn, or why none was."
             }
         ],
-        run: async ({ options, log }) => {
-            const file = resolve(CONFIG_FILE);
-            // any configuration the catalogue would read, not only the file written: a new .ts would win over a .mts
-            const existing = CONFIG_FILES.find((name) => existsSync(resolve(name)));
-            if (existing !== undefined && options.force !== true)
-                throw new ScriptError(`${existing} is already there`, {
-                    hint: "Give --force to replace it with the one read from Storybook"
-                });
-            // the importer reads Storybook's files with the compiler: only this command loads it
-            const { importStorybook } = await import("./importers/storybook.js");
-            const imported = await importStorybook(process.cwd());
-            if (typeof imported === "string")
-                throw new ScriptError(imported);
-            writeFileSync(file, initConfigText(imported, "Storybook"));
-            log.success(`${CONFIG_FILE} written: ${imported.stories.length} story globs`);
-            for (const note of imported.notes)
-                log.warn(note);
-            const missing = missingPackages(process.cwd(), imported);
-            if (missing.length > 0)
-                log.info(`Install what it imports first: npm install --save-dev ${missing.join(" ")}`);
-            log.info(`Next: ${COMMAND} dev to open the catalogue, ${COMMAND} stories to list what did not read, ` +
-                `${COMMAND} agents for the project's coding agents`);
+        run: async ({ options, io, log, isJson }) => {
+            const { runInit } = await import("./initRun.js");
+            await runInit({
+                from: options.from,
+                framework: options.framework,
+                isForced: options.force === true,
+                shouldInstall: options.install === true || options.browser === true,
+                isForAgents: options.agents === true,
+                hooks: options.hooks?.split(",").map((name) => name.trim()),
+                shouldInstallBrowser: options.browser === true,
+                shouldDraw: options.draw === true
+            }, { io, log, isJson });
         }
     })
 });

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

@@ -1,5 +1,6 @@
 /**
- * The `forgebook.config.ts` that `forgebook init` writes, from what an importer read of another tool's files.
+ * The `forgebook.config.ts` that `forgebook init` writes, from what an importer read of another tool's files or from a
+ * project's dependencies.
  *
  * @remarks
  * Pure: the configuration in, the file's text out. The file is written as a person would write it (the `defineConfig`
@@ -16,6 +17,7 @@ export declare const CONFIG_FILE = "forgebook.config.ts";
  * The configuration file's text.
  *
  * @param imported - what the importer read.
- * @param tool - the tool's name, for the file's comment (`Storybook`).
+ * @param tool - the tool's name, for the file's comment (`Storybook`); none for a configuration read from the project's
+ *   dependencies.
  */
-export declare const initConfigText: (imported: ImportedConfig, tool: string) => string;
+export declare const initConfigText: (imported: ImportedConfig, tool: string | undefined) => string;

package/dist/bin/forgebook/initConfig.js

@@ -29,7 +29,8 @@ const adapterArgument = (options) => {
  * The configuration file's text.
  *
  * @param imported - what the importer read.
- * @param tool - the tool's name, for the file's comment (`Storybook`).
+ * @param tool - the tool's name, for the file's comment (`Storybook`); none for a configuration read from the project's
+ *   dependencies.
  */
 export const initConfigText = (imported, tool) => {
     const adapter = ADAPTER_FUNCTIONS[imported.framework];
@@ -41,7 +42,7 @@ export const initConfigText = (imported, tool) => {
         ...(imported.switches === undefined
             ? []
             : [
-                `  // from the preview's globalTypes: applied by code, as ${tool}'s decorators read them`,
+                `  // from the preview's globalTypes: applied by code, as ${tool ?? "the app"}'s decorators read them`,
                 `  switches: ${sourceOf(imported.switches, "  ")},`
             ])
     ];
@@ -50,7 +51,9 @@ export const initConfigText = (imported, tool) => {
     fields[last] = fields[last]?.replace(/,$/, "") ?? "";
     return [
         "/**",
-        ` * The catalogue's configuration, written by \`forgebook init --from ${tool.toLowerCase()}\` from ${tool}'s files.`,
+        tool === undefined
+            ? " * The catalogue's configuration, written by `forgebook init` from the project's dependencies."
+            : ` * The catalogue's configuration, written by \`forgebook init --from ${tool.toLowerCase()}\` from ${tool}'s files.`,
         " *",
         " * @module",
         " */",

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

@@ -0,0 +1,15 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+import type { InitInstall } from "./newProject/newProject.types.ts";
+import { type DetectedPackageManager } from "./newProject/packageManagers.ts";
+import { type PackageState } from "./newProject/projectPackages.ts";
+/**
+ * What the configuration needs installed: the command, run when asked.
+ *
+ * @param projectDir - the project's folder.
+ * @param manager - its package manager.
+ * @param state - what it has of the packages.
+ * @param declared - what it declares.
+ * @param shouldInstall - whether to run the command.
+ * @param io - the run's streams.
+ */
+export declare const settleInstall: (projectDir: string, manager: DetectedPackageManager, state: PackageState, declared: ReadonlyMap<string, string>, shouldInstall: boolean, io: ScriptIo) => Promise<InitInstall>;

package/dist/bin/forgebook/initInstall.js

@@ -0,0 +1,77 @@
+/**
+ * What `forgebook init` needs installed, and the install when it is asked for: what a failed one said, and a second try
+ * on the peer conflicts npm stops on.
+ *
+ * @module
+ */
+import { exec } from "@ensiria/cli-kit/exec";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { printable } from "../../src/printable.js";
+import { installArguments, spawnedCommand, workspaceRootFlags } from "./newProject/packageManagers.js";
+import { installSpecifier } from "./newProject/projectPackages.js";
+/** How much of a failed install's end is kept: enough for its reason, not to flood an agent's context. */
+const INSTALL_LINES = 12;
+/** The same, in characters. */
+const INSTALL_TEXT = 360;
+/** The end of what an install said: why it failed is in its last lines, not in its exit code. */
+const installFailure = (command, code, said) => {
+    const lines = said.split("\n").filter((line) => /\S/.test(line));
+    const errorCode = said.match(/\bE[A-Z]{5,}\b/)?.[0];
+    return `${command} exited with code ${code ?? "none"}${errorCode === undefined ? "" : ` (${errorCode})`}: ${lines.slice(-INSTALL_LINES).join("\n").slice(-INSTALL_TEXT)}`;
+};
+/** Runs the install command, the program's lines on stderr so stdout stays the result's. */
+const runInstall = async (projectDir, manager, args, io) => {
+    const { program, args: spawnArgs, env } = spawnedCommand(manager.name, args, io.env);
+    try {
+        const { code, stdout, stderr } = await exec(program, spawnArgs, {
+            cwd: projectDir,
+            env,
+            output: "prefix",
+            prefix: manager.name,
+            io,
+            check: false
+        });
+        return code === 0
+            ? undefined
+            : installFailure(`${manager.name} ${args.join(" ")}`, code, `${stdout}\n${stderr}`);
+    }
+    catch (error) {
+        if (error instanceof ScriptError)
+            return error.message;
+        throw error;
+    }
+};
+/** The install's state, from what is needed, what was asked and how it went. */
+const installStatus = (needsInstall, shouldInstall, failure) => {
+    if (!needsInstall)
+        return "not-needed";
+    if (!shouldInstall)
+        return "to-run";
+    return failure === undefined ? "ran" : "failed";
+};
+/**
+ * What the configuration needs installed: the command, run when asked.
+ *
+ * @param projectDir - the project's folder.
+ * @param manager - its package manager.
+ * @param state - what it has of the packages.
+ * @param declared - what it declares.
+ * @param shouldInstall - whether to run the command.
+ * @param io - the run's streams.
+ */
+export const settleInstall = async (projectDir, manager, state, declared, shouldInstall, io) => {
+    const needsInstall = state.missing.length > 0 || state.hasUninstalled;
+    const args = installArguments(manager.name, state.missing.map((name) => installSpecifier(name, declared)), workspaceRootFlags(manager.name, projectDir));
+    const first = needsInstall && shouldInstall ? await runInstall(projectDir, manager, args, io) : undefined;
+    // npm stops on any peer conflict in the whole tree, often the project's own and older than this run: these packages
+    // install beside it either way, and the conflict stays the project's to settle
+    const isPeerConflict = manager.name === "npm" && first?.includes("ERESOLVE") === true;
+    const finalArgs = isPeerConflict ? [...args, "--legacy-peer-deps"] : args;
+    const failure = isPeerConflict ? await runInstall(projectDir, manager, finalArgs, io) : first;
+    return {
+        missing: state.missing,
+        command: needsInstall ? [manager.name, ...finalArgs].join(" ") : undefined,
+        status: installStatus(needsInstall, shouldInstall, failure),
+        error: failure === undefined ? undefined : printable(failure)
+    };
+};

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

@@ -0,0 +1,9 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+import type { Logger } from "@ensiria/cli-kit/log.types";
+import type { InitDocument } from "./newProject/newProject.types.ts";
+/** Prints the outcome: the document under `--json`, sentences for a person otherwise. */
+export declare const printInit: (document: InitDocument, { io, log, isJson }: {
+    readonly io: ScriptIo;
+    readonly log: Logger;
+    readonly isJson: boolean;
+}) => void;

package/dist/bin/forgebook/initPrint.js

@@ -0,0 +1,60 @@
+/**
+ * How `forgebook init` says what it did: its document under `--json`, sentences for a person otherwise.
+ *
+ * @module
+ */
+import { formatJson } from "@ensiria/cli-kit/files";
+import { CONFIG_FILE } from "./initConfig.js";
+import { PROJECT_FRAMEWORKS } from "./newProject/projectFrameworks.js";
+/** Says what of the project's own code will run when the catalogue starts, since nothing else tells a person. */
+const sayAppBuild = ({ viteConfig, tsconfigPaths, postcss, runsCode }, log) => {
+    const read = [
+        ...(viteConfig === undefined ? [] : [viteConfig]),
+        ...(postcss === undefined ? [] : [postcss]),
+        ...(tsconfigPaths ? ["tsconfig paths"] : [])
+    ];
+    if (read.length === 0)
+        return;
+    const running = runsCode.length === 0 ? "" : `; starting it runs ${runsCode.join(" and ")}, as the app's build does`;
+    log.info(`The catalogue will read ${read.join(", ")}${running} (appBuild: false turns it off)`);
+};
+/** Says what was written for the project's coding agents. */
+const sayAgentFiles = ({ agents }, log) => {
+    for (const file of agents?.written ?? [])
+        log.success(`${file} written`);
+    for (const hook of agents?.hooks ?? [])
+        log.info(`Hook: ${hook.name} (${hook.effect})`);
+};
+/** Says what came of drawing: what did not draw, each with what to do. */
+const sayDraw = ({ draw }, log) => {
+    if (draw === undefined)
+        return;
+    for (const { file, diagnosis } of draw.attempts)
+        log.warn(`${file}: ${diagnosis.kind}: ${diagnosis.message}\n  ${diagnosis.nextStep}`);
+    if (draw.status === "drawn")
+        log.success(`${draw.story ?? ""} drew: ${draw.picture ?? ""}`);
+};
+/** Prints the outcome: the document under `--json`, sentences for a person otherwise. */
+export const printInit = (document, { io, log, isJson }) => {
+    if (isJson) {
+        io.stdout.write(formatJson(document));
+        return;
+    }
+    const { detectedFrom, name } = document.packageManager;
+    if (document.route === "new-project") {
+        const from = detectedFrom === undefined ? "no lock file: assumed" : detectedFrom;
+        log.success(`${PROJECT_FRAMEWORKS[document.framework].label} project, ${name} (${from})`);
+    }
+    const count = document.stories.length;
+    if (document.written.includes(CONFIG_FILE))
+        log.success(`${CONFIG_FILE} written: ${count} story ${count === 1 ? "glob" : "globs"}`);
+    for (const file of document.written.filter((name) => name !== CONFIG_FILE))
+        log.success(`${file} written`);
+    sayAppBuild(document.appBuild, log);
+    sayAgentFiles(document, log);
+    for (const step of document.nextSteps)
+        log.warn(step.message);
+    sayDraw(document, log);
+    for (const { command, description } of document.commands)
+        log.info(`${command}: ${description}`);
+};

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

@@ -0,0 +1,45 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+import type { Logger } from "@ensiria/cli-kit/log.types";
+import type { InitRefusal } from "./newProject/newProject.types.ts";
+import type { PackageState } from "./newProject/projectPackages.ts";
+/** Where the command prints. */
+export type InitContext = {
+    /** The run's streams. */
+    readonly io: ScriptIo;
+    /** The run's logger. */
+    readonly log: Logger;
+    /** Whether stdout carries JSON. */
+    readonly isJson: boolean;
+};
+/** A refusal's document without what is always the same. */
+type Refusal = Pick<InitRefusal, "refused" | "message"> & Partial<InitRefusal>;
+/**
+ * Stops the command: its document on stdout under `--json`, the error otherwise. Never returns.
+ *
+ * @param refusal - why.
+ * @param context - where it prints.
+ */
+export declare const refuse: (refusal: Refusal, context: InitContext) => never;
+/** Whether a path holds anything, a dangling link included. */
+export declare const isThere: (path: string) => boolean;
+/**
+ * Refuses a file the catalogue reads that is there already, unless asked to replace it, and a link at any time.
+ *
+ * @param projectDir - the project's folder.
+ * @param name - the file found; none when there is none.
+ * @param isForced - `--force`.
+ * @param context - where a refusal prints.
+ */
+export declare const refuseExisting: (projectDir: string, name: string | undefined, isForced: boolean, context: InitContext) => void;
+/**
+ * Stops on a `package.json` that cannot be parsed: everything after this reads it.
+ *
+ * @param projectDir - the project's folder.
+ * @param context - where a refusal prints.
+ */
+export declare const refuseBrokenManifest: (projectDir: string, context: InitContext) => void;
+/** The sentence and the document's entry for packages too old, on the route that goes on regardless. */
+export declare const tooOldText: ({ tooOld }: PackageState) => string;
+/** Refuses what the project has too old for a new catalogue to draw. */
+export declare const refuseTooOld: (state: PackageState, context: InitContext) => void;
+export {};