forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/agentSetup/drawRun.js

@@ -0,0 +1,353 @@
+/**
+ * What `forgebook init --draw` runs: draws a story of the project in a real browser, trying components until one draws, and
+ * says why each that did not.
+ *
+ * @remarks
+ * Each step is the project's own installed `forgebook`, as a person or an agent would run it, in a process of its own: the
+ * command that started this one may be another copy (`npx`), and a catalogue's configuration imports the project's.
+ * Stories the project has come first. A file this run wrote stays only if its story drew; the others are removed, so a
+ * failed run leaves nothing behind. Starting a catalogue runs the project's code (its `vite.config`, its components), which
+ * is why this is asked for by name and `forgebook init` alone never does it. When several components fail alike the
+ * reason is not the component, so the run stops early and says so.
+ *
+ * @module
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isStoryCheckReport, isStoryShotReport } from "../../../src/storyCheck.js";
+import { isStoriesDocument } from "../../../src/vite/agentApi.js";
+import { drawCandidates } from "./drawCandidates.js";
+import { BLANK, diagnosed } from "./drawDiagnosis.js";
+import { isUniformPicture } from "./uniformPicture.js";
+/** How long one step may run, in ms: a first start pre-bundles a whole app's dependencies. */
+const STEP_MS = 240_000;
+/** How long a command's streams may stay open after it ended, in ms. */
+const STREAMS_MS = 2000;
+/** How long the whole run may take, in ms: an unattended command must end. */
+const RUN_MS = 600_000;
+/** How many components may fail alike before the reason is taken not to be theirs. */
+const SAME_FAILURES = 3;
+/**
+ * The file of the `forgebook` command a project installed; none when it has not.
+ *
+ * @remarks
+ * Run by Node and not through the package manager, which reads some of the arguments as its own: Yarn 1 takes `--json`.
+ *
+ * @param dir - the project's folder.
+ */
+export const installedForgebook = (dir) => {
+    const folder = join(dir, "node_modules", "forgebook");
+    if (existsSync(join(folder, "package.json"))) {
+        const real = realpathSync(folder);
+        const parsed = JSON.parse(readFileSync(join(real, "package.json"), "utf8"));
+        const bin = typeof parsed === "object" && parsed !== null && "bin" in parsed ? parsed.bin : undefined;
+        const file = typeof bin === "object" && bin !== null && "forgebook" in bin ? bin.forgebook : undefined;
+        return typeof file === "string" ? join(real, file) : undefined;
+    }
+    const parent = dirname(dir);
+    return parent === dir ? undefined : installedForgebook(parent);
+};
+/**
+ * Runs the project's own `forgebook`.
+ *
+ * @param dir - the project's folder.
+ * @param env - the environment.
+ */
+export const projectForgebook = (dir, env) => (args) => new Promise((resolve) => {
+    const file = installedForgebook(dir);
+    if (file === undefined) {
+        resolve({ stdout: "", stderr: "forgebook is not installed in this project", isOk: false });
+        return;
+    }
+    // ended by the command's own exit: a plugin of the app's may leave a watcher behind that holds these streams open
+    const child = spawn(process.execPath, [file, ...args], {
+        cwd: dir,
+        env: { ...env, NO_COLOR: "1" },
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    const out = [];
+    const err = [];
+    child.stdout.setEncoding("utf8").on("data", (chunk) => out.push(chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => err.push(chunk));
+    const timer = setTimeout(() => {
+        err.push(`\nThe command took over ${STEP_MS / 1000} s, and was stopped: timed out`);
+        child.kill("SIGKILL");
+    }, STEP_MS);
+    let isFinished = false;
+    const finish = (isOk) => {
+        if (isFinished)
+            return;
+        isFinished = true;
+        clearTimeout(timer);
+        resolve({ stdout: out.join(""), stderr: err.join(""), isOk });
+        child.stdout.destroy();
+        child.stderr.destroy();
+    };
+    child.once("error", (error) => {
+        err.push(error.message);
+        finish(false);
+    });
+    let exitCode = null;
+    child.once("close", (code) => finish(code === 0));
+    child.once("exit", (code) => {
+        exitCode = code;
+        // what it wrote just before it ended is still on its way, until "close"; a watcher a plugin left behind holds its
+        // streams open, and "close" then never comes
+        setTimeout(() => finish(exitCode === 0), STREAMS_MS);
+    });
+});
+/** A framework's generated folder, which its `tsconfig.json` extends, and the command in its package that writes it. */
+const GENERATED_FOLDERS = {
+    sveltekit: { folder: ".svelte-kit", bin: "svelte-kit", args: ["sync"] },
+    nuxt: { folder: ".nuxt", bin: "nuxt", args: ["prepare"] }
+};
+/**
+ * Writes a framework's generated folder when it is missing: its `prepare` script does on an install, and every module fails
+ * to compile without it after one that ran no scripts. A failure is left for the stories to say.
+ *
+ * @param dir - the project's folder.
+ * @param framework - the adapter's name.
+ * @param env - the environment.
+ */
+export const prepareGenerated = async (dir, framework, env) => {
+    const generated = GENERATED_FOLDERS[framework];
+    if (generated === undefined || existsSync(join(dir, generated.folder)))
+        return;
+    const bin = join(dir, "node_modules", ".bin", generated.bin);
+    if (!existsSync(bin))
+        return;
+    await new Promise((resolve) => {
+        const child = spawn(bin, [...generated.args], {
+            cwd: dir,
+            env: { ...env },
+            stdio: "ignore",
+            shell: process.platform === "win32"
+        });
+        const timer = setTimeout(() => child.kill("SIGKILL"), STEP_MS);
+        const finish = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        child.once("error", finish);
+        child.once("exit", finish);
+    });
+};
+/** A document a step printed; none when it printed something else. */
+const parsedDocument = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Why one story's result does not count as drawn; none when it does. */
+export const resultProblem = (result) => {
+    // a request that failed (a font, a picture, an API) says nothing of whether the story drew
+    const stopping = result.problems.filter(({ kind, message }) => kind === "frame" || (kind === "error" && !/^Failed to load resource/.test(message)));
+    if (stopping.length > 0)
+        return diagnosed(stopping.map(({ message }) => message).join("\n"));
+    if (result.notVerified !== undefined)
+        return diagnosed(result.notVerified);
+    return result.isBlank === true ? BLANK : undefined;
+};
+/** What a step said of its failure. */
+const stepFailure = ({ stdout, stderr }) => diagnosed(stderr.trim() || stdout);
+/** The lines of a server's log that name an error, without their stacks. */
+const SERVER_ERROR = /^.*\b(?:Internal server error|Pre-transform error|Error):\s.*$/m;
+/** A diagnosis with what the server said when the page's words name nothing. */
+const diagnosedWithServer = (problem, serverSaid) => {
+    const line = serverSaid.match(SERVER_ERROR)?.[0];
+    return line === undefined ? problem : diagnosed(line);
+};
+/** Checks one story in the default view: why it did not draw, or none. */
+const checkStory = async ({ run }, id) => {
+    const output = await run(["check", id, "--json"]);
+    const report = parsedDocument(output.stdout);
+    if (!isStoryCheckReport(report))
+        return stepFailure(output);
+    const [result] = report.results;
+    if (result === undefined)
+        return diagnosed(`No result for ${id}`);
+    const problem = resultProblem(result);
+    // a module the server could not compile says only "500" in the page; the server said why, on its own stream
+    return problem?.kind === "unknown" ? diagnosedWithServer(problem, output.stderr) : problem;
+};
+/** The picture of a story that drew: its file, or none when it cannot be taken, which does not undo the drawing. */
+const pictureOf = async ({ run }, id) => {
+    const report = parsedDocument((await run(["shot", id, "--json"])).stdout);
+    return isStoryShotReport(report) ? report.shots[0]?.file : undefined;
+};
+/** The catalogue's stories, or why they cannot be listed. */
+const listedStories = async ({ run }) => {
+    const output = await run(["stories", "--json"]);
+    const document = parsedDocument(output.stdout);
+    return isStoriesDocument(document) ? document : stepFailure(output);
+};
+/** The first story of the component a story file holds. */
+const firstStoryOf = (components, file) => components.find((component) => component.files.some((each) => each.endsWith(file)))?.stories[0]?.id;
+/** What is a component's own however many have it: another may well draw. */
+const OF_THE_COMPONENT = ["no-component", "blank", "needs-props"];
+/** Whether the last failures are all alike: the same kind and the same words. */
+const isSameFailure = (attempts) => {
+    const last = attempts.slice(-SAME_FAILURES);
+    const [first] = last;
+    return (last.length === SAME_FAILURES &&
+        first !== undefined &&
+        !OF_THE_COMPONENT.includes(first.diagnosis.kind) &&
+        last.every(({ diagnosis }) => diagnosis.kind === first.diagnosis.kind && diagnosis.message === first.diagnosis.message));
+};
+/** What a story that passed its checks came to: a run that drew, or a picture of nothing. */
+const drawnOrBlank = async (context, story, storyFile, isWritten, { attempts }) => {
+    const picture = await pictureOf(context, story);
+    if (picture !== undefined && existsSync(picture) && isUniformPicture(readFileSync(picture))) {
+        rmSync(picture, { force: true });
+        return undefined;
+    }
+    return { status: "drawn", story, storyFile, isWritten, picture, attempts, stoppedBecause: undefined };
+};
+/** A run that drew nothing. */
+const notDrawn = (attempts, stoppedBecause) => ({
+    status: "failed",
+    story: undefined,
+    storyFile: undefined,
+    isWritten: false,
+    picture: undefined,
+    attempts,
+    stoppedBecause
+});
+/** A run that has no browser to draw in: nothing can pass until there is one. */
+const noBrowser = (attempts) => notDrawn(attempts, "No browser to draw in: nothing can pass until it is installed");
+/** Tries the stories the project has already: one that draws ends the run. */
+const tryExisting = async (context, progress, components) => {
+    for (const component of components.slice(0, SAME_FAILURES)) {
+        const story = component.stories[0];
+        if (story === undefined)
+            continue;
+        const problem = await checkStory(context, story.id);
+        const result = problem === undefined ? await drawnOrBlank(context, story.id, story.file, false, progress) : undefined;
+        if (result !== undefined)
+            return result;
+        progress.attempts.push({ file: story.file, diagnosis: problem ?? BLANK });
+    }
+    return undefined;
+};
+/** The component to choose in a file of several: its name's, or the first. */
+export const chosenExport = (file, names) => {
+    const base = basename(file)
+        .replace(/\.[^.]+$/, "")
+        .replace(/[^a-z0-9]/gi, "")
+        .toLowerCase();
+    return names.find((name) => name.toLowerCase() === base) ?? names[0];
+};
+/** Writes a component's first stories, choosing one when the file exports several. */
+const writeStories = async ({ run }, file) => {
+    const written = await run(["new", file, "--json"]);
+    const several = written.stderr.match(/exports several components \(([^)]*)\)/)?.[1];
+    if (several === undefined)
+        return written;
+    const chosen = chosenExport(file, several.split(", "));
+    return chosen === undefined ? written : run(["new", file, "--export", chosen, "--json"]);
+};
+/** Draws the first story of a file just written: its id, and why it did not draw. */
+const drawWritten = async (context, storyFile) => {
+    const listed = await listedStories(context);
+    if ("kind" in listed)
+        return { problem: listed };
+    const story = firstStoryOf(listed.components, storyFile);
+    if (story === undefined)
+        return { problem: diagnosed(`The file ${storyFile} gave no story`) };
+    return { story, problem: await checkStory(context, story) };
+};
+/** Writes one component's first stories and draws the first: its file written, or why it did not draw. */
+const tryComponent = async (context, file, progress) => {
+    const written = await writeStories(context, file);
+    const document = parsedDocument(written.stdout);
+    const storyFile = typeof document === "object" &&
+        document !== null &&
+        "file" in document &&
+        typeof document.file === "string"
+        ? document.file
+        : undefined;
+    if (storyFile === undefined) {
+        progress.attempts.push({ file, diagnosis: stepFailure(written) });
+        return undefined;
+    }
+    const { story, problem } = await drawWritten(context, storyFile);
+    const result = problem === undefined && story !== undefined
+        ? await drawnOrBlank(context, story, storyFile, true, progress)
+        : undefined;
+    if (result !== undefined)
+        return result;
+    rmSync(join(context.dir, storyFile), { force: true });
+    progress.attempts.push({ file, diagnosis: problem ?? BLANK });
+    return undefined;
+};
+/**
+ * Tries again the components that wanted a provider, with the app's own in the preview; the preview goes back as it was when
+ * none draws.
+ */
+const drawnWithProviders = async (context, progress) => {
+    const wanting = progress.attempts
+        .filter(({ diagnosis }) => diagnosis.kind === "provider")
+        .slice(0, SAME_FAILURES);
+    if (wanting.length === 0)
+        return undefined;
+    const lifted = context.liftProviders?.();
+    if (lifted === undefined)
+        return undefined;
+    for (const { file } of wanting) {
+        const tried = { attempts: progress.attempts };
+        const result = await tryComponent(context, file, tried);
+        if (result !== undefined)
+            return { ...result, liftedProviders: lifted.names };
+    }
+    lifted.undo();
+    return undefined;
+};
+/** A run that should stop after its last failure; none when another component is worth a try. */
+const stoppedShort = (attempts) => {
+    const latest = attempts.at(-1)?.diagnosis;
+    if (latest?.kind === "browser")
+        return noBrowser(attempts);
+    return isSameFailure(attempts)
+        ? notDrawn(attempts, `${SAME_FAILURES} components failed alike, so the reason is not theirs: ${latest?.nextStep ?? ""}`)
+        : undefined;
+};
+/** Tries the components in turn: the first that draws, or what came of them. */
+const tryCandidates = async (context, candidates, progress) => {
+    const startedAt = Date.now();
+    for (const file of candidates) {
+        if (Date.now() - startedAt > RUN_MS)
+            return notDrawn(progress.attempts, `Stopped after ${RUN_MS / 60_000} minutes: each try takes long`);
+        const result = await tryComponent(context, file, progress);
+        if (result !== undefined)
+            return result;
+        const stopped = stoppedShort(progress.attempts);
+        if (stopped !== undefined)
+            return (await drawnWithProviders(context, progress)) ?? stopped;
+    }
+    return (await drawnWithProviders(context, progress)) ?? notDrawn(progress.attempts, undefined);
+};
+/**
+ * Draws a story of the project.
+ *
+ * @param context - where the steps run.
+ */
+export const runDraw = async (context) => {
+    const progress = { attempts: [] };
+    await context.prepare?.();
+    const hasStories = await listedStories(context);
+    if (!("kind" in hasStories)) {
+        const fromProject = await tryExisting(context, progress, hasStories.components);
+        if (fromProject !== undefined)
+            return fromProject;
+        if (progress.attempts.at(-1)?.diagnosis.kind === "browser")
+            return noBrowser(progress.attempts);
+    }
+    const candidates = drawCandidates(context.dir, context.framework, context.folders);
+    if (candidates.length === 0 && progress.attempts.length === 0)
+        return notDrawn([], "No component file was found: write a story by hand, or run forgebook new <component file>");
+    return tryCandidates(context, candidates, progress);
+};

package/dist/bin/forgebook/agentSetup/hookNames.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The names `--hooks` takes: light, so the command's definition does not load what writes them.
+ *
+ * @module
+ */
+/** The hooks `--hooks` names, with `none`. */
+export declare const HOOK_NAMES: readonly string[];

package/dist/bin/forgebook/agentSetup/hookNames.js

@@ -0,0 +1,7 @@
+/**
+ * The names `--hooks` takes: light, so the command's definition does not load what writes them.
+ *
+ * @module
+ */
+/** The hooks `--hooks` names, with `none`. */
+export const HOOK_NAMES = ["claude", "codex", "cursor", "gemini", "pre-commit", "none"];

package/dist/bin/forgebook/agentSetup/initAgentSteps.d.ts

@@ -0,0 +1,48 @@
+import type { ScriptIo } from "@ensiria/cli-kit/io.types";
+import type { InitInstall, PackageManagerName } from "../newProject/newProject.types.ts";
+import { type AgentFiles } from "./agentFiles.ts";
+import { type DrawResult } from "./drawRun.ts";
+/** What came of installing the browser. */
+export type BrowserStep = {
+    /** Whether it ran. */
+    readonly status: "ran" | "failed";
+    /** Why it failed. */
+    readonly error: string | undefined;
+};
+/** What the steps were given. */
+export type AgentStepsRequest = {
+    /** The project's folder. */
+    readonly projectDir: string;
+    /** The adapter's name. */
+    readonly framework: string;
+    /** The package manager. */
+    readonly manager: PackageManagerName;
+    /** How the install went. */
+    readonly install: InitInstall;
+    /** `--agents`. */
+    readonly isForAgents: boolean;
+    /** `--hooks`. */
+    readonly hooks: readonly string[] | undefined;
+    /** `--browser`. */
+    readonly shouldInstallBrowser: boolean;
+    /** `--draw`. */
+    readonly shouldDraw: boolean;
+    /** The story patterns written, so only a component whose stories the catalogue lists is tried; none for a catalogue kept. */
+    readonly stories: readonly string[] | undefined;
+};
+/** What came of the steps; a step not asked for is absent. */
+export type AgentSteps = {
+    /** The files written for the agents. */
+    readonly agents?: AgentFiles;
+    /** The browser. */
+    readonly browser?: BrowserStep;
+    /** The drawing. */
+    readonly draw?: DrawResult;
+};
+/**
+ * Runs the steps asked for.
+ *
+ * @param request - what they were given.
+ * @param io - the run's streams.
+ */
+export declare const runAgentSteps: (request: AgentStepsRequest, io: ScriptIo) => Promise<AgentSteps>;

package/dist/bin/forgebook/agentSetup/initAgentSteps.js

@@ -0,0 +1,104 @@
+/**
+ * What `forgebook init` does after the catalogue's own files, when asked: sets up the project's coding agents, installs the
+ * browser, and draws a story.
+ *
+ * @remarks
+ * Each is asked for by name, since each does more than write a catalogue's files: the browser is a large download, and
+ * drawing runs the project's code. A step that cannot go on is reported in the document and the next is still tried when
+ * it does not depend on it, so one run says everything that is wrong.
+ *
+ * @module
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { installBrowser } from "../browserRun.js";
+import { writeAgentFiles } from "./agentFiles.js";
+import { storyFolders } from "./drawCandidates.js";
+import { prepareGenerated, projectForgebook, runDraw } from "./drawRun.js";
+import { liftedProviders } from "./liftedProviders.js";
+/** The drawing, when what it needs is not there: the first thing to do about it. */
+const cannotDraw = (reason) => ({
+    status: "not-run",
+    story: undefined,
+    storyFile: undefined,
+    isWritten: false,
+    picture: undefined,
+    attempts: [],
+    stoppedBecause: reason
+});
+/** Installs the browser, its lines kept off stdout. */
+const browserStep = async (projectDir, io) => {
+    try {
+        await installBrowser(projectDir, false, io);
+        return { status: "ran", error: undefined };
+    }
+    catch (error) {
+        return { status: "failed", error: (error instanceof Error ? error.message : String(error)).slice(-400) };
+    }
+};
+/**
+ * Writes the providers of a React app's entry into the catalogue's preview.
+ *
+ * @param projectDir - the project's folder.
+ * @returns their names and how to take them out; none when the entry has none a copy can give.
+ */
+const liftEntryProviders = (projectDir) => {
+    const entry = ["src/main", "src/index", "src/client", "index"]
+        .flatMap((name) => ["tsx", "jsx"].map((extension) => join(projectDir, `${name}.${extension}`)))
+        .find((file) => existsSync(file));
+    if (entry === undefined)
+        return undefined;
+    const previewFile = join(projectDir, "forgebook.preview.tsx");
+    const before = existsSync(previewFile) ? readFileSync(previewFile, "utf8") : undefined;
+    const lifted = liftedProviders(readFileSync(entry, "utf8"), entry, previewFile, before ?? "");
+    if (lifted === undefined)
+        return undefined;
+    writeFileSync(previewFile, lifted.preview);
+    return {
+        names: lifted.names,
+        undo: () => {
+            if (before === undefined)
+                rmSync(previewFile, { force: true });
+            else
+                writeFileSync(previewFile, before);
+        }
+    };
+};
+/** Draws, when what it needs is there. */
+const drawStep = (install, browser, draw) => {
+    if (install.status !== "ran" && install.status !== "not-needed")
+        return Promise.resolve(cannotDraw(`The packages are not installed: ${install.command ?? "install them"}, or give --install`));
+    return browser?.status === "failed" ? Promise.resolve(cannotDraw("The browser did not install")) : draw();
+};
+/**
+ * Runs the steps asked for.
+ *
+ * @param request - what they were given.
+ * @param io - the run's streams.
+ */
+export const runAgentSteps = async (request, io) => {
+    const { projectDir, framework, manager, install } = request;
+    const run = projectForgebook(projectDir, io.env);
+    const agents = request.isForAgents
+        ? writeAgentFiles({ projectDir, framework, manager, hooks: request.hooks })
+        : undefined;
+    const isInstalled = install.status === "ran" || install.status === "not-needed";
+    const browser = request.shouldInstallBrowser && isInstalled ? await browserStep(projectDir, io) : undefined;
+    const draw = request.shouldDraw
+        ? await drawStep(install, browser, () => runDraw({
+            dir: projectDir,
+            framework,
+            run,
+            prepare: () => prepareGenerated(projectDir, framework, io.env),
+            ...(framework === "react" && request.stories !== undefined
+                ? { liftProviders: () => liftEntryProviders(projectDir) }
+                : {}),
+            folders: storyFolders(request.stories ?? [])
+        }))
+        : undefined;
+    return {
+        ...(agents === undefined ? {} : { agents }),
+        ...(browser === undefined ? {} : { browser }),
+        ...(draw === undefined ? {} : { draw })
+    };
+};

package/dist/bin/forgebook/agentSetup/liftedProviders.d.ts

@@ -0,0 +1,17 @@
+/** What providers came to. */
+export type LiftedProviders = {
+    /** The tags of the wrappers given, outermost first. */
+    readonly names: readonly string[];
+    /** The preview's text with them. */
+    readonly preview: string;
+};
+/**
+ * The providers of an app's entry, as a preview.
+ *
+ * @param entry - the entry's text.
+ * @param entryFile - its file, absolute.
+ * @param previewFile - the preview's file, absolute.
+ * @param previewText - what the preview holds now.
+ * @returns them; none when the entry wraps the app in nothing a copy can give.
+ */
+export declare const liftedProviders: (entry: string, entryFile: string, previewFile: string, previewText: string) => LiftedProviders | undefined;