forgebook 0.1.7 → 0.2.0

package/dist/bin/forgebook/catalogueCommands.js

@@ -20,6 +20,13 @@ export const FORGEBOOK_OPTIONS = {
 };
 /** The command, as the hints print it. */
 export const COMMAND = "forgebook";
+/**
+ * The configuration file a command reads: the one given, or the one in the folder it runs in.
+ *
+ * @param file - the configuration file given; none to look in the current folder.
+ * @returns its absolute path, or none when there is none here.
+ */
+export const configPathOf = (file) => file === undefined ? findConfigFile(process.cwd()) : resolve(file);
 /**
  * The catalogue's configuration: the file given, or the one in the folder the command runs in.
  *
@@ -27,7 +34,7 @@ export const COMMAND = "forgebook";
  * @throws a `ScriptError` when there is none, or it cannot be used.
  */
 export const configOf = async (file) => {
-    const found = file === undefined ? findConfigFile(process.cwd()) : resolve(file);
+    const found = configPathOf(file);
     if (found === undefined)
         throw new ScriptError(`No ${CONFIG_FILES[0]} here`, {
             hint: `Run ${COMMAND} in the catalogue's folder, or give --config`
@@ -87,4 +94,16 @@ export const printAnswer = (text, document, problems, context) => {
     if (problems.length > 0)
         throw new ScriptError(`${problems.length} problems`, { exitCode: EXIT.failure, isReported: true });
 };
-//# sourceMappingURL=catalogueCommands.js.map
+/**
+ * Prints an answer about tokens that holds whatever else is wrong in the files: the problems are warned about, and the
+ * command succeeds, since a good answer must not read as a failure because of an unrelated token.
+ *
+ * @param text - the answer as a person reads it.
+ * @param document - the answer.
+ * @param context - where it goes.
+ */
+export const printTokenAnswer = (text, document, context) => {
+    context.io.stdout.write(context.isJson ? formatJson(document) : `${text}\n`);
+    for (const problem of document.problems)
+        context.log.warn(problem);
+};

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

@@ -1,16 +1,58 @@
-/**
- * The Vite configuration the `forgebook` command runs a catalogue with: its folder as the root, Forgebook's plugin
- * with the configuration already read, and the framework's own plugins.
- *
- * @module
- */
-import type { InlineConfig } from "vite";
+import type { InlineConfig, ServerOptions } from "vite";
 import type { ResolvedConfig } from "../../src/vite/configFile.ts";
 /**
  * Vite's configuration for a catalogue.
  *
  * @param config - the catalogue's configuration, read.
- * @param overrides - what the command sets (the port, the output folder).
+ * @param overrides - what the command sets (the port, the output folder); its plugins run after the catalogue's.
  */
 export declare const catalogueVite: (config: ResolvedConfig, overrides: InlineConfig) => Promise<InlineConfig>;
-//# sourceMappingURL=catalogueVite.d.ts.map
+/**
+ * The configuration with the frames' port the command line gives (`--frame-port`), over the file's.
+ *
+ * @param config - the configuration.
+ * @param framePort - the option's value; none when not given.
+ * @throws a `ScriptError` when it is not a port, or the frames run on the catalogue's origin.
+ */
+export declare const withFramePort: (config: ResolvedConfig, framePort: string | undefined) => ResolvedConfig;
+/** Where the command line can put the stories' frames, as `--frames` names it. */
+export declare const FRAMES_MODES: readonly ["isolated", "same-origin"];
+/** A placement `--frames` names. */
+export type FramesMode = (typeof FRAMES_MODES)[number];
+/**
+ * The configuration with the frames where the command line puts them (`--frames`), over the file's: on the catalogue's
+ * origin for one run behind a setup that forwards one port, or on their own for a catalogue whose file keeps them on
+ * the catalogue's; and to compare the two placements without editing the file.
+ *
+ * @param config - the configuration.
+ * @param mode - the option's value; none when not given.
+ */
+export declare const withFramesMode: (config: ResolvedConfig, mode: FramesMode | undefined) => ResolvedConfig;
+/**
+ * The configuration with the build's scripts named after their modules when the command line asks
+ * (`--readable-names`), over the file's.
+ *
+ * @param config - the configuration.
+ * @param isAsked - the option's value; none when not given.
+ */
+export declare const withReadableNames: (config: ResolvedConfig, isAsked: boolean | undefined) => ResolvedConfig;
+/** What the command line sets of the dev server's own options. */
+export type DevServerChoice = {
+    /** The port to listen on; Vite's when none. */
+    readonly port: number | undefined;
+    /** The address to listen on; localhost when none. */
+    readonly host: string | undefined;
+    /** Whether file edits are noticed by checking the files (`--poll`) instead of the system's change events. */
+    readonly isPolling: boolean;
+};
+/**
+ * The dev server's options the command line sets (`--port`, `--host`, `--poll`).
+ *
+ * @remarks
+ * Polling is the remedy where the system's change events come late or never: a container's mounted volume, a Windows
+ * drive under WSL, a network drive, or a machine whose file-event service is overloaded. Vite checks each watched file
+ * every 100 ms then, which costs some processor time, so it is asked for, never the default.
+ *
+ * @param choice - what the command line asks.
+ */
+export declare const devServerOptions: (choice: DevServerChoice) => ServerOptions;

package/dist/bin/forgebook/catalogueVite.js

@@ -1,15 +1,101 @@
+/**
+ * The Vite configuration the `forgebook` command runs a catalogue with: its folder as the root, Forgebook's plugin
+ * with the configuration already read, the framework's own plugins, and the server's export conditions taken from the
+ * pages'; and where the command line puts the frames.
+ *
+ * @module
+ */
+import { ScriptError } from "@ensiria/cli-kit/script";
 import { forgebookPlugin } from "../../src/vite/forgebookPlugin.js";
+import { ISOLATED_FRAMES } from "../../src/vite/framesConfig.js";
+import { serverConditions } from "../../src/vite/serverConditions.js";
+import { unresolvedImports } from "./viteCache.js";
 /**
  * Vite's configuration for a catalogue.
  *
  * @param config - the catalogue's configuration, read.
- * @param overrides - what the command sets (the port, the output folder).
- */
-export const catalogueVite = async (config, overrides) => ({
-    ...overrides,
-    root: config.dir,
-    // the configuration file is Forgebook's: a vite.config beside it is not read
-    configFile: false,
-    plugins: [forgebookPlugin({ config }), ...((await config.framework.vitePlugins?.()) ?? [])]
+ * @param overrides - what the command sets (the port, the output folder); its plugins run after the catalogue's.
+ */
+export const catalogueVite = async (config, overrides) => {
+    // what a first start's pre-bundling left out, left out here too: it is part of the pre-bundle's hash, and a server
+    // whose hash differed would pre-bundle everything again itself
+    const unresolved = unresolvedImports(config.dir);
+    return {
+        ...overrides,
+        ...(unresolved.length === 0
+            ? {}
+            : {
+                optimizeDeps: {
+                    ...overrides.optimizeDeps,
+                    exclude: [...(overrides.optimizeDeps?.exclude ?? []), ...unresolved]
+                }
+            }),
+        root: config.dir,
+        // the configuration file is Forgebook's: a vite.config beside it is not read
+        configFile: false,
+        plugins: [
+            forgebookPlugin({ config }),
+            ...((await config.framework.vitePlugins?.()) ?? []),
+            ...(overrides.plugins ?? []),
+            // the server loads the stories and previews for tools: it resolves them as the pages do
+            serverConditions()
+        ]
+    };
+};
+/**
+ * The configuration with the frames' port the command line gives (`--frame-port`), over the file's.
+ *
+ * @param config - the configuration.
+ * @param framePort - the option's value; none when not given.
+ * @throws a `ScriptError` when it is not a port, or the frames run on the catalogue's origin.
+ */
+export const withFramePort = (config, framePort) => {
+    if (framePort === undefined)
+        return config;
+    const port = /^\d+$/.test(framePort) ? Number(framePort) : Number.NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new ScriptError(`--frame-port ${framePort} is not a port`);
+    if (config.frames.kind === "same-origin")
+        throw new ScriptError("--frame-port asks for a port the frames do not use", {
+            hint: 'They run on the catalogue\'s origin (frames: "same-origin", or --frames same-origin)'
+        });
+    return { ...config, frames: { ...config.frames, port } };
+};
+/** Where the command line can put the stories' frames, as `--frames` names it. */
+export const FRAMES_MODES = ["isolated", "same-origin"];
+/**
+ * The configuration with the frames where the command line puts them (`--frames`), over the file's: on the catalogue's
+ * origin for one run behind a setup that forwards one port, or on their own for a catalogue whose file keeps them on
+ * the catalogue's; and to compare the two placements without editing the file.
+ *
+ * @param config - the configuration.
+ * @param mode - the option's value; none when not given.
+ */
+export const withFramesMode = (config, mode) => {
+    if (mode === undefined || mode === config.frames.kind)
+        return config;
+    return { ...config, frames: mode === "same-origin" ? { kind: "same-origin" } : ISOLATED_FRAMES };
+};
+/**
+ * The configuration with the build's scripts named after their modules when the command line asks
+ * (`--readable-names`), over the file's.
+ *
+ * @param config - the configuration.
+ * @param isAsked - the option's value; none when not given.
+ */
+export const withReadableNames = (config, isAsked) => isAsked === true ? { ...config, build: { ...config.build, readableNames: true } } : config;
+/**
+ * The dev server's options the command line sets (`--port`, `--host`, `--poll`).
+ *
+ * @remarks
+ * Polling is the remedy where the system's change events come late or never: a container's mounted volume, a Windows
+ * drive under WSL, a network drive, or a machine whose file-event service is overloaded. Vite checks each watched file
+ * every 100 ms then, which costs some processor time, so it is asked for, never the default.
+ *
+ * @param choice - what the command line asks.
+ */
+export const devServerOptions = (choice) => ({
+    ...(choice.port === undefined ? {} : { port: choice.port, strictPort: true }),
+    ...(choice.host === undefined ? {} : { host: choice.host }),
+    ...(choice.isPolling ? { watch: { usePolling: true } } : {})
 });
-//# sourceMappingURL=catalogueVite.js.map

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

@@ -0,0 +1,8 @@
+import type { TokensReach } from "./tokensRun.ts";
+/**
+ * Answers `forgebook check-code`.
+ *
+ * @param reach - where the answer comes from and goes.
+ * @param since - the commit to compare with.
+ */
+export declare const runCheckCode: ({ config, url, context }: TokensReach, since: string | undefined) => Promise<void>;

package/dist/bin/forgebook/checkCodeRun.js

@@ -0,0 +1,27 @@
+/**
+ * What `forgebook check-code` does: asks the catalogue, prints, and fails when the change broke something.
+ *
+ * @module
+ */
+import { EXIT } from "@ensiria/cli-kit/constants";
+import { formatJson } from "@ensiria/cli-kit/files";
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { isCheckedCodeDocument } from "../../src/vite/agentApi.js";
+import { checkedCodeText } from "./agentText.js";
+import { askCatalogue } from "./catalogueCommands.js";
+/**
+ * Answers `forgebook check-code`.
+ *
+ * @param reach - where the answer comes from and goes.
+ * @param since - the commit to compare with.
+ */
+export const runCheckCode = async ({ config, url, context }, since) => {
+    const { io, log, isJson } = context;
+    const body = await askCatalogue(config, url, "check-code", new URLSearchParams({ since: since ?? "" }), log);
+    if (!isCheckedCodeDocument(body))
+        throw new ScriptError("The catalogue's answer has an unexpected shape");
+    io.stdout.write(isJson ? formatJson(body) : `${checkedCodeText(body)}\n`);
+    if (body.problems.length > 0) {
+        throw new ScriptError(`${body.problems.length} problems`, { exitCode: EXIT.failure, isReported: true });
+    }
+};

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

@@ -0,0 +1,11 @@
+import type { InlineConfig } from "vite";
+import type { ResolvedConfig } from "../../src/vite/configFile.ts";
+/** The folder, inside the catalogue's Vite cache folder, where the servers commands start keep their cache. */
+export declare const COMMAND_CACHE_FOLDER = "forgebook-commands";
+/**
+ * Vite's configuration for a server a command starts: the catalogue's, with a cache of its own.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param overrides - what the command sets (the port, middleware mode).
+ */
+export declare const commandServerVite: (config: ResolvedConfig, overrides: InlineConfig) => Promise<InlineConfig>;

package/dist/bin/forgebook/commandServer.js

@@ -0,0 +1,39 @@
+/**
+ * The Vite configuration of a dev server a command starts for itself (`forgebook stories`, `story`, `mcp`, the story
+ * checks), beside the `forgebook dev` the user may be running in the same folder.
+ *
+ * @remarks
+ * Two Vite servers on one cache folder rewrite each other's pre-bundled dependencies: each one's optimizer replaces the
+ * whole `deps` folder when it commits, and a `--force` start deletes it, so the other server's frames ask for files
+ * that are gone or of another bundle and fail as outdated. A command's server therefore keeps its cache in a folder of
+ * its own inside the one the dev server uses: still warm from one command to the next, never the dev server's, and
+ * outside its watcher (Vite ignores everything under its cache folder) and its cleanup (only the `deps` folder and
+ * `_temp_` folders are removed).
+ *
+ * @module
+ */
+import { join } from "node:path";
+import { catalogueVite } from "./catalogueVite.js";
+import { viteCacheDir } from "./viteCache.js";
+/** The folder, inside the catalogue's Vite cache folder, where the servers commands start keep their cache. */
+export const COMMAND_CACHE_FOLDER = "forgebook-commands";
+/**
+ * Moves the server's cache into {@link COMMAND_CACHE_FOLDER} of the folder Vite would use: run after every other
+ * plugin, so a framework's plugin that sets its own cache folder is followed too.
+ */
+const commandCache = () => ({
+    name: "forgebook:command-cache",
+    config: {
+        order: "post",
+        handler: (current) => ({
+            cacheDir: join(viteCacheDir(current), COMMAND_CACHE_FOLDER)
+        })
+    }
+});
+/**
+ * Vite's configuration for a server a command starts: the catalogue's, with a cache of its own.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param overrides - what the command sets (the port, middleware mode).
+ */
+export const commandServerVite = (config, overrides) => catalogueVite(config, { ...overrides, plugins: [...(overrides.plugins ?? []), commandCache()] });

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

@@ -0,0 +1,7 @@
+/**
+ * The compile cache's folder for an installation of Forgebook.
+ *
+ * @param installed - the folder of the command's module, as Node loaded it.
+ * @returns the folder, or none when Forgebook does not run from a `node_modules` (its own sources).
+ */
+export declare const compileCacheFolder: (installed: string) => string | undefined;

package/dist/bin/forgebook/compileCache.js

@@ -0,0 +1,24 @@
+/**
+ * Where the `forgebook` command keeps Node's compile cache: the Vite cache folder of the outermost `node_modules` its
+ * installation sits in, so a package manager's nested store (`node_modules/.pnpm/…/node_modules/forgebook`) shares the
+ * project's folder, and removing the project's `node_modules/.vite` empties it. Pure: a path in, a path out.
+ *
+ * @module
+ */
+import { join, parse, sep } from "node:path";
+/** The folder name a package manager installs packages in. */
+const DEPENDENCIES = "node_modules";
+/**
+ * The compile cache's folder for an installation of Forgebook.
+ *
+ * @param installed - the folder of the command's module, as Node loaded it.
+ * @returns the folder, or none when Forgebook does not run from a `node_modules` (its own sources).
+ */
+export const compileCacheFolder = (installed) => {
+    const { root } = parse(installed);
+    const parts = installed.slice(root.length).split(sep);
+    const outermost = parts.indexOf(DEPENDENCIES);
+    if (outermost < 0)
+        return undefined;
+    return join(root, ...parts.slice(0, outermost + 1), ".vite", "forgebook", "compile");
+};

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

@@ -0,0 +1,14 @@
+/**
+ * The `forgebook` commands that run a catalogue's dev server: `dev`, and `prebundle`, the dependencies' pre-bundling
+ * a first start does.
+ *
+ * @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 devCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/devCommands.mjs

@@ -0,0 +1,104 @@
+import { ScriptError } from "@ensiria/cli-kit/script";
+import { createServer } from "vite";
+import { COMMAND, configOf, configPathOf } from "./catalogueCommands.js";
+import { catalogueVite, devServerOptions, FRAMES_MODES, withFramePort, withFramesMode } from "./catalogueVite.js";
+import { prebundle } from "./prebundleRun.js";
+import { prebundleForDev } from "./prebundleStart.js";
+import { openTouchWindow } from "./touchWindowRun.js";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const devCommands = (forgebook) => ({
+    dev: forgebook.command({
+        summary: "Run the catalogue's dev server.",
+        options: {
+            port: {
+                type: "string",
+                valueName: "number",
+                description: "The port to listen on; Vite's by default."
+            },
+            host: {
+                type: "string",
+                valueName: "address",
+                description: "The address to listen on; localhost by default."
+            },
+            "frame-port": {
+                type: "string",
+                valueName: "number",
+                description: "The stories' frames' port (their own origin); the catalogue's port + 1 by default."
+            },
+            frames: {
+                type: "string",
+                choices: FRAMES_MODES,
+                valueName: "placement",
+                description: "Where the stories' frames run for this run: on an origin of their own, or on the catalogue's (frames in the configuration)."
+            },
+            force: {
+                type: "boolean",
+                description: "Pre-bundle the dependencies again, ignoring Vite's cache (as a first start does)."
+            },
+            poll: {
+                type: "boolean",
+                description: "Notice file edits by checking the files every 100 ms instead of waiting for the system's change events: " +
+                    "for files whose events come late or never (a container's mounted volume, a Windows drive under WSL, a " +
+                    "network drive, an overloaded machine). Costs some processor time."
+            },
+            touch: {
+                type: "boolean",
+                description: "Also open the catalogue in a Chromium window with Chromium's own touch emulation: the mouse makes real " +
+                    "touch events, native scrolling included (needs @forgebook/testing and Playwright). Still a computer: no " +
+                    "virtual keyboard, no iOS Safari; a device remains the last word."
+            }
+        },
+        examples: [
+            { command: `${COMMAND} dev`, description: "Run the catalogue of the folder you are in." },
+            { command: `${COMMAND} dev --port 6006`, description: "On a given port." },
+            { command: `${COMMAND} dev --touch`, description: "And try the stories with Chromium's real touch." },
+            {
+                command: `${COMMAND} dev --poll`,
+                description: "In a container or under WSL, where an edit's change event does not reach the server."
+            },
+            {
+                command: `${COMMAND} dev --frames same-origin`,
+                description: "With the frames on the catalogue's origin, as behind a proxy that forwards one port."
+            }
+        ],
+        run: async ({ options, onInterrupt, log }) => {
+            const isForced = options.force === true;
+            // the one the entry started, when it could; it works while the configuration loads
+            const prebundling = prebundleForDev(configPathOf(options.config), options);
+            const read = withFramesMode(await configOf(options.config), options.frames);
+            const config = withFramePort(read, options["frame-port"]);
+            const port = options.port === undefined ? undefined : Number(options.port);
+            if (port !== undefined && !Number.isInteger(port))
+                throw new ScriptError(`--port ${options.port} is not a port`);
+            // the server reads the cache folder the child writes; should the child have failed, it does the work itself
+            const isPrebundled = await prebundling;
+            const server = await createServer(await catalogueVite(config, {
+                server: devServerOptions({ port, host: options.host, isPolling: options.poll === true }),
+                ...(isForced && !isPrebundled ? { optimizeDeps: { force: true } } : {})
+            }));
+            await server.listen();
+            server.printUrls();
+            if (options.touch === true)
+                await openTouchWindow(config.dir, server.resolvedUrls?.local[0], log);
+            await new Promise((done) => {
+                onInterrupt(() => {
+                    void server.close().then(done);
+                });
+            });
+        }
+    }),
+    prebundle: forgebook.command({
+        summary: "Pre-bundle the catalogue's dependencies: what dev does on a first start.",
+        options: {
+            force: { type: "boolean", description: "Pre-bundle them again, ignoring Vite's cache." }
+        },
+        examples: [
+            { command: `${COMMAND} prebundle`, description: "Before the first start, in CI or an image." }
+        ],
+        run: async ({ options }) => prebundle(await configOf(options.config), options.force === true)
+    })
+});

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

@@ -24,4 +24,3 @@ export declare const askErrors: (ask: CatalogueClient["ask"], since: number) =>
  * @returns why it stopped, when the catalogue could not answer.
  */
 export declare const followErrors: (ask: CatalogueClient["ask"], since: number, onErrors: (document: ErrorsDocument) => void, signal?: AbortSignal) => Promise<string | undefined>;
-//# sourceMappingURL=errorsRun.d.ts.map

package/dist/bin/forgebook/errorsRun.js

@@ -70,4 +70,3 @@ export const followErrors = async (ask, since, onErrors, signal) => {
     }
     return undefined;
 };
-//# sourceMappingURL=errorsRun.js.map

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

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=forgebook.d.mts.map