forgebook 0.3.3 → 0.4.0

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

@@ -34,8 +34,9 @@ export type ServedCatalogue = {
  *
  * @param config - the catalogue's configuration.
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param isOwn - serve it for the run whatever runs at the address; `false` by default.
  */
-export declare const servedCatalogue: (config: ResolvedConfig, url: string | undefined) => Promise<ServedCatalogue>;
+export declare const servedCatalogue: (config: ResolvedConfig, url: string | undefined, isOwn?: boolean) => Promise<ServedCatalogue>;
 /**
  * The catalogue's answers: the running dev server at the address when it serves this catalogue, a server of its own
  * otherwise.

package/dist/bin/forgebook/agentClient.js

@@ -15,8 +15,10 @@ import { readFile } from "node:fs/promises";
 import { createServer as createNetServer } from "node:net";
 import { resolve } from "node:path";
 import { createServer } from "vite";
-import { AGENT_INDEX_FILE, indexAnswer, isAgentIndex } from "../../src/vite/agentIndex.js";
+import { AGENT_INDEX_FILE } from "../../src/agentIndexFile.js";
+import { indexAnswer, isAgentIndex } from "../../src/vite/agentIndex.js";
 import { AGENT_API, agentAnswer, agentServer, ROOT_HEADER, rootHeaderValue } from "../../src/vite/agentRoutes.js";
+import { withoutTrailingSlashes } from "../../src/vite/storyPatterns.js";
 import { commandServerVite } from "./commandServer.js";
 /** Where `forgebook dev` serves when no port is given: Vite's default. */
 export const DEFAULT_ORIGIN = "http://localhost:5173";
@@ -81,7 +83,7 @@ const indexSource = (from) => {
     if (!/^https?:\/\//i.test(from)) {
         return { text: () => readFile(resolve(from, AGENT_INDEX_FILE), "utf8"), origin: "" };
     }
-    const origin = from.replace(/\/+$/, "");
+    const origin = withoutTrailingSlashes(from);
     const address = `${origin}/${AGENT_INDEX_FILE}`;
     const text = async () => {
         const response = await fetch(address, { signal: AbortSignal.timeout(INDEX_TIMEOUT) });
@@ -149,7 +151,8 @@ const ownListening = async (config, port) => {
         await server.close();
         throw error;
     }
-    const address = server.resolvedUrls?.local[0]?.replace(/\/+$/, "");
+    const local = server.resolvedUrls?.local[0];
+    const address = local === undefined ? undefined : withoutTrailingSlashes(local);
     if (address === undefined) {
         await server.close();
         throw new Error("The catalogue's dev server started with no address");
@@ -162,9 +165,13 @@ const ownListening = async (config, port) => {
  *
  * @param config - the catalogue's configuration.
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
+ * @param isOwn - serve it for the run whatever runs at the address; `false` by default.
  */
-export const servedCatalogue = async (config, url) => {
-    const origin = (url ?? DEFAULT_ORIGIN).replace(/\/+$/, "");
+export const servedCatalogue = async (config, url, isOwn = false) => {
+    // a run that has just written a file serves it itself: a running server may still answer with its earlier module
+    if (isOwn)
+        return ownListening(config, 0);
+    const origin = withoutTrailingSlashes(url ?? DEFAULT_ORIGIN);
     const running = await runningClient(origin, config);
     if (running !== undefined)
         return { origin, runningAt: origin, close: async () => undefined };
@@ -178,7 +185,7 @@ export const servedCatalogue = async (config, url) => {
  * @param url - where `forgebook dev` runs, when not at Vite's default address.
  */
 export const catalogueClient = async (config, url) => {
-    const origin = (url ?? DEFAULT_ORIGIN).replace(/\/+$/, "");
+    const origin = withoutTrailingSlashes(url ?? DEFAULT_ORIGIN);
     return (await runningClient(origin, config)) ?? ownClient(config, origin);
 };
 /** A port free right now, asked of the system. */

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

@@ -0,0 +1,59 @@
+import type { GuideDocument, GuideListDocument } from "../../src/vite/agent.types.ts";
+import type { McpTool } from "../../src/vite/mcpProtocol.ts";
+/** The frameworks with an adapter, each named as the adapter's package and its `framework.name`. */
+export declare const GUIDE_FRAMEWORKS: readonly ["react", "preact", "solid", "vue", "nuxt", "svelte", "sveltekit", "angular", "nextjs", "react-native-web", "web-components", "html"];
+/** The topics that hold for every framework, with what each is about. */
+export declare const GUIDE_TOPICS: {
+    readonly stories: "Writing a story file: its exports, its parameters, the texts, the TSDoc agents read";
+    readonly devices: "Touch, phones and tablets: the Touch switch and the drawn devices";
+    readonly "docs-pages": "The docs pages and the written home: front matter, live stories, blocks";
+    readonly switches: "The switches, galleries and looks: previews, a value that implies another, a value's own style sheet";
+    readonly links: "The links an answer carries for a person, and a page drawn for its audience";
+    readonly commands: "Every command an agent uses, and when";
+    readonly setup: "What a catalogue may change: checks turned off, the frames' origin, edits that do not arrive, inline previews";
+};
+/**
+ * Whether a name is a framework with a guide.
+ *
+ * @param name - the name.
+ */
+export declare const isGuideFramework: (name: string) => name is (typeof GUIDE_FRAMEWORKS)[number];
+/**
+ * The frameworks a project's stories are written for: the adapter its catalogue's configuration imports, or, with no
+ * configuration yet, the adapters its manifest lists.
+ *
+ * @remarks
+ * Both are read as text, never run: a command that prints instructions has no reason to execute the project's code,
+ * and a configuration that prints, exits or never settles would decide what it answers.
+ *
+ * @param configFile - the catalogue's configuration file, when there is one.
+ * @param dir - where the manifest is read when there is no configuration file; beside the file otherwise.
+ * @returns the frameworks with a guide; none when they cannot be told.
+ */
+export declare const projectFrameworks: (configFile: string | undefined, dir: string) => readonly string[];
+/**
+ * The instructions as a project gets them: the short text, with its frameworks' essentials.
+ *
+ * @param frameworks - the project's frameworks. One gives its essentials; several, or none, say where to find them,
+ * so the section stays short whatever the project lists.
+ */
+export declare const agentsSection: (frameworks: readonly string[]) => string;
+/**
+ * The topics, with the project's frameworks.
+ *
+ * @param frameworks - the project's frameworks.
+ */
+export declare const guideList: (frameworks: readonly string[]) => GuideListDocument;
+/**
+ * One topic's text.
+ *
+ * @param topic - the topic.
+ * @returns the document, or none when there is no such topic.
+ */
+export declare const guideTopic: (topic: string) => GuideDocument | undefined;
+/**
+ * The tool that prints the guide, as `forgebook guide` does: it asks nothing of the catalogue, so it answers at once.
+ *
+ * @param frameworks - the catalogue's frameworks.
+ */
+export declare const guideTool: (frameworks: readonly string[]) => McpTool;

package/dist/bin/forgebook/agentGuide.js

@@ -0,0 +1,203 @@
+/**
+ * Forgebook's guide for coding agents, a topic at a time: what `forgebook agents` writes into a project is short on
+ * purpose, and `forgebook guide` and the `get_guide` tool print the rest when an agent needs it.
+ *
+ * @remarks
+ * Agents do better with text they ask for than with long static instructions, and a long file loses its middle, so
+ * every framework's words stay out of a project that does not use that framework. A framework's file holds its
+ * essentials up to the `more` marker, and only those reach the written section; the rest is printed on demand.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { textOf } from "./mcpToolParts.js";
+/** The frameworks with an adapter, each named as the adapter's package and its `framework.name`. */
+export const GUIDE_FRAMEWORKS = [
+    "react",
+    "preact",
+    "solid",
+    "vue",
+    "nuxt",
+    "svelte",
+    "sveltekit",
+    "angular",
+    "nextjs",
+    "react-native-web",
+    "web-components",
+    "html"
+];
+/**
+ * The framework an adapter's project also lists as a dependency of its own: it writes its stories for the adapter, so
+ * the base's sample would only contradict it.
+ */
+const BUILT_ON = {
+    nextjs: "react",
+    "react-native-web": "react",
+    nuxt: "vue",
+    sveltekit: "svelte"
+};
+/** The topics that hold for every framework, with what each is about. */
+export const GUIDE_TOPICS = {
+    stories: "Writing a story file: its exports, its parameters, the texts, the TSDoc agents read",
+    devices: "Touch, phones and tablets: the Touch switch and the drawn devices",
+    "docs-pages": "The docs pages and the written home: front matter, live stories, blocks",
+    switches: "The switches, galleries and looks: previews, a value that implies another, a value's own style sheet",
+    links: "The links an answer carries for a person, and a page drawn for its audience",
+    commands: "Every command an agent uses, and when",
+    setup: "What a catalogue may change: checks turned off, the frames' origin, edits that do not arrive, inline previews"
+};
+/** The topic that prints every other one, for an agent that wants the whole guide at once. */
+const ALL_TOPIC = "all";
+/** The line of a framework's file that ends its essentials. */
+const MORE_MARKER = /^<!-- more -->\n+/m;
+/** The placeholder of `agents.md` the framework's essentials take. */
+const FRAMEWORK_PLACEHOLDER = "{{framework}}";
+/**
+ * Whether a name is a framework with a guide.
+ *
+ * @param name - the name.
+ */
+export const isGuideFramework = (name) => GUIDE_FRAMEWORKS.some((framework) => framework === name);
+/**
+ * A file of the guide, as written.
+ *
+ * @param path - the file, from the guide's folder.
+ */
+const guideFile = (path) => readFileSync(new URL(`./guide/${path}`, import.meta.url), "utf8").trim();
+/**
+ * The adapters a manifest's dependency fields list; a manifest that cannot be read lists none, since it is the project's
+ * own tools that report it.
+ *
+ * @param text - the manifest's text.
+ */
+const manifestDependencies = (text) => {
+    let manifest;
+    try {
+        manifest = JSON.parse(text);
+    }
+    catch {
+        return new Set();
+    }
+    if (typeof manifest !== "object" || manifest === null)
+        return new Set();
+    const fields = Object.entries(manifest).filter(([field]) => ["dependencies", "devDependencies", "peerDependencies"].includes(field));
+    return new Set(fields.flatMap(([, value]) => typeof value === "object" && value !== null ? Object.keys(value) : []));
+};
+/**
+ * The frameworks a project's stories are written for: the adapter its catalogue's configuration imports, or, with no
+ * configuration yet, the adapters its manifest lists.
+ *
+ * @remarks
+ * Both are read as text, never run: a command that prints instructions has no reason to execute the project's code,
+ * and a configuration that prints, exits or never settles would decide what it answers.
+ *
+ * @param configFile - the catalogue's configuration file, when there is one.
+ * @param dir - where the manifest is read when there is no configuration file; beside the file otherwise.
+ * @returns the frameworks with a guide; none when they cannot be told.
+ */
+export const projectFrameworks = (configFile, dir) => {
+    const config = configFile !== undefined && existsSync(configFile) ? readFileSync(configFile, "utf8") : "";
+    const imported = GUIDE_FRAMEWORKS.filter((framework) => config.includes(`"@forgebook/${framework}/vite"`));
+    if (imported.length > 0)
+        return imported;
+    const manifest = join(configFile === undefined ? dir : dirname(configFile), "package.json");
+    if (!existsSync(manifest))
+        return [];
+    const listed = manifestDependencies(readFileSync(manifest, "utf8"));
+    const adapters = GUIDE_FRAMEWORKS.filter((framework) => listed.has(`@forgebook/${framework}`));
+    const bases = adapters.flatMap((framework) => BUILT_ON[framework] ?? []);
+    return adapters.filter((framework) => !bases.includes(framework));
+};
+/**
+ * What the section says of the project's framework.
+ *
+ * @param frameworks - the project's frameworks.
+ */
+const frameworkText = (frameworks) => {
+    const [only] = frameworks;
+    if (only === undefined) {
+        return "`npx forgebook guide <framework>` gives your framework's file names, types and a sample; `npx forgebook guide` lists them.";
+    }
+    if (frameworks.length > 1) {
+        const names = frameworks.map((name) => `\`${name}\``).join(", ");
+        return `This project lists several frameworks (${names}): \`npx forgebook guide <name>\` gives each one's file names, types and a sample.`;
+    }
+    const [essentials = ""] = guideFile(`frameworks/${only}.md`).split(MORE_MARKER);
+    return `${essentials.trim()}\n\nThe rest of it: \`npx forgebook guide ${only}\`.`;
+};
+/**
+ * The instructions as a project gets them: the short text, with its frameworks' essentials.
+ *
+ * @param frameworks - the project's frameworks. One gives its essentials; several, or none, say where to find them,
+ * so the section stays short whatever the project lists.
+ */
+export const agentsSection = (frameworks) => {
+    const text = frameworkText(frameworks);
+    return readFileSync(new URL("./agents.md", import.meta.url), "utf8").replace(FRAMEWORK_PLACEHOLDER, 
+    // a function, so a `$` in the text is not read as a replacement pattern
+    () => text);
+};
+/**
+ * The topics, with the project's frameworks.
+ *
+ * @param frameworks - the project's frameworks.
+ */
+export const guideList = (frameworks) => ({
+    schema: 1,
+    topics: [
+        ...Object.entries(GUIDE_TOPICS).map(([topic, about]) => ({ topic, about })),
+        ...GUIDE_FRAMEWORKS.map((topic) => ({
+            topic,
+            about: `Stories in ${topic}: files, types, args, a sample`
+        })),
+        { topic: ALL_TOPIC, about: "Everything above at once: ask for one topic when you can" }
+    ],
+    frameworks
+});
+/**
+ * One topic's text.
+ *
+ * @param topic - the topic.
+ * @returns the document, or none when there is no such topic.
+ */
+export const guideTopic = (topic) => {
+    const textOfTopic = (name) => {
+        if (isGuideFramework(name))
+            return guideFile(`frameworks/${name}.md`).replace(MORE_MARKER, "");
+        return Object.hasOwn(GUIDE_TOPICS, name) ? guideFile(`${name}.md`) : undefined;
+    };
+    if (topic === ALL_TOPIC) {
+        const text = [...Object.keys(GUIDE_TOPICS), ...GUIDE_FRAMEWORKS]
+            .map((name) => `<!-- forgebook guide ${name} -->\n\n${textOfTopic(name) ?? ""}`)
+            .join("\n\n");
+        return { schema: 1, topic, text };
+    }
+    const text = textOfTopic(topic);
+    return text === undefined ? undefined : { schema: 1, topic, text };
+};
+/**
+ * The tool that prints the guide, as `forgebook guide` does: it asks nothing of the catalogue, so it answers at once.
+ *
+ * @param frameworks - the catalogue's frameworks.
+ */
+export const guideTool = (frameworks) => ({
+    name: "get_guide",
+    description: "Forgebook's guide, on demand: how to write a story in this framework, touch and devices, docs pages, links, every command. With no topic, the list of topics.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: { type: "string", description: "The topic; none for the list." }
+        },
+        additionalProperties: false
+    },
+    call: async (args) => {
+        const topic = textOf(args, "topic");
+        if (topic === undefined)
+            return { structured: guideList(frameworks), isError: false };
+        const found = guideTopic(topic);
+        return found === undefined
+            ? { structured: { error: `No topic ${topic}: get_guide with no topic lists them` }, isError: true }
+            : { structured: found, isError: false };
+    }
+});

package/dist/bin/forgebook/agentLoopCommands.mjs

@@ -5,7 +5,7 @@
  *
  * @remarks
  * Defined here, on the scope `forgebookCommands.mts` hands them, so the commands module stays a list of commands; their work lives in
- * their own modules (`agentsText.ts`, `storyCheckRun.ts`, `errorsRun.ts`).
+ * their own modules (`agentGuide.ts`, `agentsText.ts`, `storyCheckRun.ts`, `errorsRun.ts`).
  *
  * @module
  */
@@ -16,13 +16,15 @@ import { formatJson } from "@ensiria/cli-kit/files";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { isChangedStoriesDocument, isFoundComponentsDocument } from "../../src/vite/agentApi.js";
 import { catalogueClient } from "./agentClient.js";
+import { agentsSection, GUIDE_FRAMEWORKS, projectFrameworks } from "./agentGuide.js";
 import { agentsSkill, SKILL_FOLDERS, withAgentsSection } from "./agentsText.js";
 import { checkText, errorsOutput, foundComponentsText, shotText } from "./agentText.js";
-import { askCatalogue, COMMAND, configOf, printAnswer } from "./catalogueCommands.js";
+import { askCatalogue, COMMAND, configOf, configPathOf, printAnswer } from "./catalogueCommands.js";
 import { runCheckCode } from "./checkCodeRun.js";
 import { askErrors, followErrors, sinceOf } from "./errorsRun.js";
 import { storyCheckCommands } from "./storyCheckCommands.mjs";
-import { runPageCheck, runStoryCheck, runStoryShot } from "./storyCheckRun.js";
+import { runPageCheck, runStoryShot } from "./storyCheckRun.js";
+import { verifyCommands } from "./verifyCommand.mjs";
 import { BASELINES_FOLDER, updateBaselines } from "./visualCommands.mjs";
 /**
  * The catalogue the errors are asked of: only frames open in a browser report to a running dev server, so without one
@@ -72,6 +74,7 @@ const changedOf = async (config, options, log) => {
  */
 export const agentLoopCommands = (forgebook) => ({
     ...storyCheckCommands(forgebook),
+    ...verifyCommands(forgebook),
     find: forgebook.command({
         summary: "Find components by what they are for, in your own words.",
         json: true,
@@ -120,44 +123,6 @@ export const agentLoopCommands = (forgebook) => ({
             io.stdout.write(isJson ? formatJson(body) : `${text === "" ? "No story touched." : text}\n`);
         }
     }),
-    verify: forgebook.command({
-        summary: "Run the catalogue's checks on every story a change touches, with one exit code.",
-        json: true,
-        options: {
-            since: {
-                type: "string",
-                valueName: "ref",
-                description: "The commit to compare with; HEAD by default, so what is not committed."
-            },
-            url: URL_OPTION
-        },
-        examples: [
-            { command: `${COMMAND} verify`, description: "Before you say a change is done." },
-            { command: `${COMMAND} verify --since origin/develop --json`, description: "In a pull request." }
-        ],
-        run: async ({ options, io, log, isJson, style }) => {
-            const config = await configOf(options.config);
-            const { stories, files } = await changedOf(config, options, log);
-            const reports = [];
-            for (const story of stories) {
-                const report = await runStoryCheck(config, options.url, {
-                    id: story.id,
-                    views: [],
-                    isAllVariants: false
-                });
-                if (typeof report === "string")
-                    throw new ScriptError(report);
-                reports.push(report);
-            }
-            const problems = reports
-                .flatMap((report) => report.results)
-                .reduce((sum, each) => sum + each.problems.length, 0);
-            const text = reports.length === 0 ? "No story touched." : reports.map((each) => checkText(each, style)).join("\n");
-            io.stdout.write(isJson ? formatJson({ schema: 1, files, stories, reports, problems }) : `${text}\n`);
-            if (problems > 0)
-                throw new ScriptError(`${problems} problems`, { exitCode: EXIT.failure, isReported: true });
-        }
-    }),
     "check-page": forgebook.command({
         summary: "Run the checks on a real page of the application: accessibility, what spills, its errors.",
         json: true,
@@ -318,6 +283,10 @@ export const agentLoopCommands = (forgebook) => ({
             if (typeof report === "string")
                 throw new ScriptError(report);
             io.stdout.write(isJson ? formatJson(report) : `${shotText(report, (file) => relative(process.cwd(), file), style)}\n`);
+            // a picture of an error or of a fallback was taken, and is not of the story: never a success
+            const notShown = report.shots.filter((shot) => shot.status !== undefined).length;
+            if (notShown > 0)
+                throw new ScriptError(`${notShown} not of the story`, { exitCode: EXIT.failure, isReported: true });
         }
     }),
     agents: forgebook.command({
@@ -333,6 +302,12 @@ export const agentLoopCommands = (forgebook) => ({
                 type: "boolean",
                 description: `Also write them as an Agent Skill, SKILL.md in ${SKILL_FOLDERS.join(" and ")}.`
             },
+            framework: {
+                type: "string",
+                choices: GUIDE_FRAMEWORKS,
+                valueName: "name",
+                description: "The framework whose essentials to include, when not the one found in this project."
+            },
             print: { type: "boolean", description: "Print the instructions instead of writing them." }
         },
         examples: [
@@ -340,7 +315,10 @@ export const agentLoopCommands = (forgebook) => ({
             { command: `${COMMAND} agents --skill`, description: "And the skill, for any agent." }
         ],
         run: ({ options, io, log }) => {
-            const section = readFileSync(new URL("./agents.md", import.meta.url), "utf8");
+            const frameworks = options.framework === undefined
+                ? projectFrameworks(configPathOf(options.config), process.cwd())
+                : [options.framework];
+            const section = agentsSection(frameworks);
             if (options.print) {
                 io.stdout.write(section);
                 return;
@@ -349,6 +327,8 @@ export const agentLoopCommands = (forgebook) => ({
             const isNew = !existsSync(file);
             writeFileSync(file, withAgentsSection(isNew ? undefined : readFileSync(file, "utf8"), section));
             log.success(`${relative(process.cwd(), file)}: Forgebook's section ${isNew ? "written" : "renewed"}`);
+            // said aloud: from a monorepo's root the framework found may not be the catalogue's, and --framework corrects it
+            log.info(`Framework: ${frameworks.join(", ") || "none found; --framework names one"}`);
             if (options.skill !== true)
                 return;
             for (const folder of SKILL_FOLDERS) {

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

@@ -0,0 +1,55 @@
+import type { NextStep, PackageManagerName } from "../newProject/newProject.types.ts";
+import { type AssistantName } from "./assistantHooks.ts";
+/** A hook `--hooks` names: an assistant's, or the commit's. */
+export type HookName = AssistantName | "pre-commit";
+/** The hook written, and what it can do. */
+export type WrittenHook = {
+    /** Which. */
+    readonly name: HookName;
+    /** Its file, from the repository's root. */
+    readonly file: string;
+    /** Whether it refuses to finish, starts another turn, or refuses the commit. */
+    readonly effect: "blocks" | "continues" | "blocks-commit";
+};
+/** What came of the files. */
+export type AgentFiles = {
+    /** The repository's root, from the project's folder; `.` when they are the same. */
+    readonly root: string;
+    /** The files written or merged, from the root. */
+    readonly written: readonly string[];
+    /** The files that already held what they should. */
+    readonly unchanged: readonly string[];
+    /** The hooks in place. */
+    readonly hooks: readonly WrittenHook[];
+    /** What it could not do. */
+    readonly nextSteps: readonly NextStep[];
+};
+/**
+ * A project's repository root: the nearest folder holding `.git` whose repository tracks it, or the project's otherwise.
+ *
+ * @param projectDir - the project's folder.
+ */
+export declare const repositoryRoot: (projectDir: string) => string;
+/**
+ * The hooks to write when none are named: those of the assistants the repository shows signs of, otherwise the commit's.
+ *
+ * @param root - the repository's root.
+ */
+export declare const detectedHooks: (root: string) => readonly HookName[];
+/** What the files are written for. */
+export type AgentFilesRequest = {
+    /** The project's folder. */
+    readonly projectDir: string;
+    /** The adapter's name. */
+    readonly framework: string;
+    /** The package manager. */
+    readonly manager: PackageManagerName;
+    /** The hooks asked for by name (`--hooks`); those found when none. */
+    readonly hooks: readonly string[] | undefined;
+};
+/**
+ * Writes what a project's coding agents need.
+ *
+ * @param request - what for.
+ */
+export declare const writeAgentFiles: ({ projectDir, framework, manager, hooks }: AgentFilesRequest) => AgentFiles;