forgebook 0.3.3 → 0.4.0

package/dist/bin/forgebook/agents.md

@@ -1,206 +1,35 @@
 ## Stories (Forgebook)
 
 This project's components have stories, shown by [Forgebook](https://github.com/ensiria/forgebook) (`forgebook dev`).
-When you add or change a component, add or change its stories, then check them with the commands below: they answer
-in JSON with `--json`, and every answer about a story carries the links that open it for a person.
+A component you add or change gets its stories added or changed in the same change, whether or not a check asks for them.
 
-### Writing a story file
-
-- One file per component, beside it: `Badge.tsx` and `Badge.stories.tsx`, in CSF 3 (Storybook's format; Forgebook
-  reads it, never MDX or addons). Files with the same title are one component, as in Storybook: each story keeps its
-  own file (`file` in `forgebook stories --json`), and the component lists them all (`files`).
-- Every named export of a story file is a story; leave helpers and data out with the meta's `excludeStories`.
-- The catalogue lists the files its `stories` globs name in `forgebook.config.ts`; a glob that starts with `!` leaves
-  files out (`"!src/**/drafts/**"`), whatever its place in the list. A new story file that `forgebook stories` does not
-  list is outside the globs, left out by a `!` one, or refused by Vite's `server.fs.deny` (the dev server warns): put it
-  where they list it, or change the globs on purpose.
-- Story ids are Storybook's (`inputs-readmore--open-by-default`, prefixed by the source's id); the commands also take
-  the ids Forgebook gave before (`inputs-read-more--open-by-default`) and answer with the current one.
-- The meta is the default export; the stories are named exports, each with a one-line TSDoc saying what it shows (the
-  catalogue shows that sentence):
-
-  ```tsx
-  import type { Meta, Story } from "@forgebook/react";
-
-  import { Badge } from "./Badge";
-
-  export default { title: "Data/Badge", component: Badge } satisfies Meta<typeof Badge>;
-
-  /** The label as most pages use it. */
-  export const Default: Story<typeof Badge> = { args: { label: "New" }, parameters: { main: true } };
-  ```
-
-- In a Vue project, the same with `Badge.vue` and `Badge.stories.ts`: the types from `@forgebook/vue`, the component by its
-  default import, a slot as the arg `#name` (`"#default": "Text"`) and an event as its listener (`onRemove`). Open a `.vue`
-  file's script with its TSDoc block: that comment is the component's.
-- In a Svelte project, the same with `Badge.svelte` and `Badge.stories.ts`: the types from `@forgebook/svelte`, the
-  component by its default import, a snippet's text as the arg `#name` (`"#children": "Text"`), a callback prop as it is
-  (`onremove`), and a render returning `{ Component, props }`. The `<!-- @component -->` comment is the component's.
-- In a Solid or Preact project, the same as React's, with the types from `@forgebook/solid` or `@forgebook/preact`. In
-  Solid a render runs once: read the args inside its JSX (`<Badge label={args.label} />`) or spread them
-  (`<Badge {...args} />`), never destructured, so a new value reaches the story without starting it over.
-- With custom elements, `my-badge.ts` and `MyBadge.stories.ts`: the types from `@forgebook/web-components`, the element by
-  its tag (`component: "my-badge"`, the module imported for its definition) or its class. An arg's prefix says what it
-  sets: `label` the attribute, `.items` the property, `#icon` a slot (`#default` the unnamed one), `@change` an event the
-  catalogue records, which a render does not bind. A render returns a Lit template. The props come from the package's
-  `custom-elements.json`: run its analyzer after changing an element, or the docs show the old one.
-- With no framework, `button.ts` and `button.stories.ts`: the types from `@forgebook/html`, the meta's `component` the
-  function that draws (`createButton(args)`, returning an HTML string or a DOM node) and `satisfies
-  Meta<typeof createButton>`, so the args are its first parameter, documented by that type's TSDoc; a story without a
-  render calls it with the args. A story that only has a render types it with `Meta<ButtonArgs>`, or describes its args
-  in `argTypes` (plain JavaScript). A text arg written into HTML is the story's to escape; a shared link hands it only
-  plain words.
-- In a Nuxt project, the same, the types from `@forgebook/nuxt`: a component's auto-imports, aliases and Nuxt's
-  components work as in the app. Set what Nuxt would have given it with `parameters.nuxt`: `route` (a path, or
-  `{ name, params }` of a page), `data` (what `useAsyncData` and `useFetch` return, by key; `useFetch`'s key is the
-  request as made, `/api/products?page=2`), `state`, `cookies`, `runtimeConfig.public` and `appConfig`. A story's
-  `nuxt` replaces the meta's, whole. Its router moves and `navigateTo` calls are listed among the story's events; a
-  play reads them with `storyNuxt()` from `@forgebook/nuxt/story`.
-- In an Angular or Analog project, `badge.component.ts` and `Badge.stories.ts`: the types and Storybook's helpers
-  (`applicationConfig`, `moduleMetadata`, `componentWrapperDecorator`, `argsToTemplate`) from `@forgebook/angular`, the
-  class by its name, an input or an output by the name a template binds (its alias), an output's arg a handler, projected
-  content as `#default` or `#<selector>` (`"#[icon]": "*"`), and a template in a render as
-  `({ props: args, template: "…" })`. The Code tab writes the story by the component's selector.
-- In a SvelteKit app (`framework: sveltekit()`), the types come from `@forgebook/sveltekit`, and a story sets the page its
-  components read with `parameters.sveltekit`: `page: { url: "/blog/hello" }` (the route and params are read from
-  `src/routes`), `page.data` or the page's own `load` (run before the story is drawn, its fetch answered by
-  `parameters.msw` in the frame and in the server tests, where a fetch of the page's origin that no handler answers
-  fails the story), and `forms.result` for what an enhanced form's action answers. Links and `goto` move the story's page and are listed among
-  its events; in a play, `storyPage()` from `@forgebook/sveltekit/page` reads where it went and the calls it made. A
-  component that imports `$app/env/private` or `$app/server` fails in its frame by design: give it what it reads instead.
-- `parameters.main: true` marks the one real, well-made use drawn at the top of the component's page.
-- `parameters.group` puts a story under a heading of the page (`"states"`, `"worst-case"`); keep one story per
-  meaningful state, not one per prop value.
-- Add a worst case: very long text, words without spaces, huge numbers (`forgebook new` writes one).
-- To try a component as on a phone, the catalogue's Touch switch (`touch=touch` in a view: `--view "touch=touch"`)
-  sends the story a finger's events and a phone's hover and pointer media; a tap on a text field focuses it and puts the
-  caret there. It is a simulation: native scrolling, the
-  virtual keyboard and real Safari still need a device, or `forgebook dev --touch` (Chromium's real touch).
-  A story reads it as `context.globals.touch` (`"mouse"` or `"touch"`) or fixes it with
-  `globals: { touch: "touch" }`. A story meant for a phone writes `parameters.touch: true` (or its meta does): the
-  catalogue draws it with a finger and offers a toggle to turn that off.
-- In a React Native project (`reactNativeWeb()` in `forgebook.config.ts`), stories are written as React's, their
-  types from `@forgebook/react-native-web`, and drawn in the browser through react-native-web. A screen that fills
-  the window (`style={{ flex: 1 }}`) needs `parameters.layout: "fullscreen"`; the app's root providers
-  (`SafeAreaProvider`, a theme) go in the preview's decorators. A component that calls a native module or a gesture
-  of native code does not draw in a browser: give it a `.web.tsx` file, or mock what it calls in the preview.
-- A link or an embed may carry the Props tab's values (`args=` in the address, JSON). The catalogue applies only the
-  props the story's panel can set, with a value of their type; to show a story with other values, write a story with
-  those args rather than a link.
-- `parameters.height` gives the frame the room an overlay the story opens needs (a menu, a popover), in CSS px.
-- A screen meant for a phone or a tablet can be shown in a drawn device by default:
-  `parameters: { device: { frame: true, model: "iphone-16" } }` (on the meta for every story; `orientation:
-  "landscape"` turns it; a story in a device is touched as a phone is, unless `touch: false`). The models: `iphone-16`, `iphone-16-pro-max`, `iphone-16e`, `pixel-9`, `galaxy-s24`, `phone`
-  (generic), `ipad-mini`, `ipad-pro-13`. The status bar, the camera's cut and the home indicator sit
-  around it: the story is drawn inside the safe areas. A screen drawn edge to edge says `edgeToEdge: true` and pads
-  itself with `var(--forgebook-safe-area-top, env(safe-area-inset-top))` (and `-bottom`, `-left`, `-right`). `get_story` returns the setting as `device`. Pictures and
-  tests stay unframed unless a view names a model: `forgebook shot <id> --view "iphone-16"` (or `"dark pixel-9
-  landscape"`) gives a framed picture.
-- A hook or a function gets stories about logic: `parameters: { logic: true }` on the meta, its `component` the hook
-  (`satisfies LogicMeta<typeof useUndo>` in React), each story a `render` with a small scene using it and a `play`
-  that tries it. The catalogue documents its signature from its types and TSDoc (`@param`, `@returns`), and the tests
-  check it once instead of in every look. A title like `Hooks/useUndo` puts it in a Hooks section.
-- `parameters.design: { figma: "<node link>" }` on the meta links a component to its design in Figma; a story writes its
-  own over it. `forgebook story` returns it as `design` (the link, `fileKey`, `nodeId`, and the `address` to hand a
-  person); with `@forgebook/plugin-figma` listed the panel adds a Design tab.
-- `parameters.msw: { handlers: [...] }` answers a story's requests, with `@forgebook/plugin-msw` listed in the
-  configuration's `plugins`, which also adds a Network tab; without the plugin the parameter does nothing.
-- Texts a person reads come from the source's texts, not from the story: `args: { label: storyText("badge.new") }`
-  (`@forgebook/story-format/texts`), or `useStoryText()` inside a `render`. A source gives each language's table, or a
-  loader of it (`texts: { en: () => import("./locales/en.json") }`), which keeps the texts out of the catalogue's page.
-- Write `title`, `parameters.main`, `group`, `height`, `touch`, `logic`, `requiredFirst` and `design.figma` as plain
-  values: the catalogue reads them without running the file.
-- In a Next.js project (`framework: nextjs()`), stories take their types from `@forgebook/nextjs`. A story says where
-  its component is with `parameters.nextjs.navigation` (`pathname`, `query`, `params`; `router` for the Pages Router),
-  and what its server code reads with `nextjs.cookies`, `headers` and `draftMode`. A link or a router call moves the
-  story's route and is listed among its events; a `play` reads where it went with `storyRoute()`
-  (`@forgebook/nextjs/route`). Async server components are drawn; what they reach on a server (a database, the file
-  system) is not there: fetch it and mock it with `parameters.msw`. In the server tests a server component's `fetch` never
-  reaches the network, whatever its address: a fetch no handler answers fails the story, naming the address.
-
-- Say when a component is for and when it is not, in its TSDoc: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`,
-  `@replacedBy`. `forgebook story` returns them as `docs.guidance`: read them before using a component, and never use a
-  deprecated one.
-- A component with many props names their groups in its TSDoc (`@group Paging`): `forgebook story` returns each
-  prop's `group`, and a prop typed with a documented object (`texts?: FinderTexts`) its `members`, each with its type,
-  default and TSDoc: read them to know every text a component takes before passing one.
-- `forgebook story --json` and `get_story` give `requiredProps` at the top, the names of the component's props every
-  use must set (events among them; a subcomponent's say it with their own `isRequired`); `docs.props` stays in the
-  order of the source, whatever the catalogue's `requiredFirst` shows a person.
-  Set every name in `requiredProps` when you use the component or write its story.
-
-### Docs pages
-
-Guides live in Markdown files, listed in the catalogue's Docs section. Read one before writing against it
-(`npx forgebook page <id>`). When you write one: front matter with `title` (`Guides/Theming`), `order` and `description`, a
-fence named `story <id>` for a live story and `props <component id>` for an API table, and links to other pages by their
-file (`./colours.md#brand`). A page never holds a story's code: show the story. Blocks are `:::note`, `:::tip`,
-`:::important`, `:::caution`, `:::danger` (or GitHub's `> [!NOTE]`), `::::tabs{syncKey="…"}` around `:::tab[Label]`,
-`:::steps` around a numbered list, `::::cards` around `:::card[Title]` and `::link-card[Title]{href="…"}`; a block inside
-another has fewer colons. A code fence takes `title="…"`, `{1,4-6}`, `ins={…}`, `del={…}`, `wrap`, and `diff lang="tsx"`.
-After writing one, run `npx forgebook pages`: it fails with each problem's line and column.
-
-The catalogue's home may be written too (`forgebook.home.md`): `npx forgebook page home` reads it, and its values
-(`{{components}}`) and pieces (`::families`, `::libraries`, `::recent`, `::pages`) are listed in the README.
-
-### Links for a person
-
-Every story's `links` hold its page (`address`), its frame (`frame`), its component's page (`component`) and its
-embed (`embed`). A component's
-page can be drawn for who reads it: add an audience to the view, and send that link. `designer` shows usage guidance first
-and no code, `coder` the API first with the code open, `tester` what the stories cover and their accessibility check:
+### Before you say a change is done
 
 ```sh
-npx forgebook story <id> --view audience=designer --json   # links.component opens the page for a designer
+npx forgebook verify --json       # every changed UI file in stories that ran, every variant, and check-code
+npx forgebook check-code --json   # what the change adds against the design system, tokens file or not
 ```
 
-Each story also says whether a `play` function acts on it (`hasPlay`), and `tags` holds `!test` when the generated tests
-leave it out.
+A non-zero exit (`not-verified`, `failed`) means not done, and a UI file with no stories, or `unseen`, is `not-verified`: `fix` names the
+next step, usually writing them; do it and run it again. Report `partly-verified` with what `skipped` says, never as verified. To look at one story, `npx forgebook check <id> --json`
+and `npx forgebook shot <id> --view "dark 360"`.
 
-### Commands
+### Look it up when you need it
 
-| Command | What it is for |
+| Command | What it answers |
 |---|---|
-| `npx forgebook find "selectable card" --json` | Whether what you need already exists, in your own words: ask before writing a component |
-| `npx forgebook search onValueChange --json` | The whole catalogue by its text: which component has a prop, where the docs say something, with the address of the exact heading or prop |
-| `npx forgebook new src/Badge.tsx` | A component's first stories, from its typed props (`Badge.vue` or `badge.component.ts` writes `Badge.stories.ts`) |
-| `npx forgebook stories --component badge --json` | The stories and their ids; fails when a story file is broken |
-| `npx forgebook story <id> --json` | One story: the props every use must set (`requiredProps`), its args, its component's props, the components whose stories use it, its design |
-| `npx forgebook pages --json` | The docs pages, with their ids and addresses; fails when a page names what is not there |
-| `npx forgebook page <id> --json` | One docs page: its Markdown, its headings, the address that opens it |
-| `npx forgebook check <id> --json` | The catalogue's checks on one story: accessibility, spills, overlays, a modal's focus, errors, a failed play |
-| `npx forgebook check <id> --json` | The catalogue's checks on one story: accessibility, spills, overlays, errors, a failed play |
-| `npx forgebook plugins --json` | The plugins the catalogue lists: their tabs (`tab=<id>` in a view opens one), switches and docs fences |
-| `npx forgebook tokens --category color --json` | The design tokens, of the catalogue and of the libraries it shows; `clashes` says whose value stands where two disagree |
-| `npx forgebook tokens --nearest "#1c1b1b" --json` | The token to write instead of a raw value; the type comes from the value, or `--type padding` |
-| `npx forgebook check-page http://localhost:3000/checkout --json` | The same checks on a real page of the application: the screen you built, not only its stories |
-| `npx forgebook changed --json` | The stories your change touches, through what they import |
-| `npx forgebook verify --json` | The checks on all of them, with one exit code: run it before you say a change is done |
-| `npx forgebook check-code --json` | What your change adds against the design system: raw values, with the token to use, turned-off checks, deleted tests |
-| `npx forgebook errors --json` | What the open frames reported while you edited: render errors, failed plays |
-| `npx forgebook shot <id> --view "dark 360"` | The story as a picture, to look at it (a view as words, or `theme=dark&width=360`); a model's id in the view (`iphone-16`) frames it in that device |
-| `npx forgebook story <id> --json` | Its `links`: `address` in the catalogue, `frame` alone, `embed` with no chrome, for a wiki or an iframe |
-| `npx forgebook shot <id> --update` then `npx forgebook diff <id> --json` | Baselines, then what changed against them: the region, the percentage, a marked picture |
-
-Never write a raw colour or size when a token exists: ask `tokens --nearest` first, and use a match only when it says
-`isClose` or `isExact`. A match that is not close means no token fits: say so, do not force one.
-
-A catalogue may turn off its accessibility check (`a11y: false`) or its component docs (`componentDocs: false`). Then a
-check's report says `"a11y": "off"` (it ran no axe: a pass says nothing of accessibility), and `story` says
-`"componentDocs": "off"` with no `docs` and no required props: read the component's source for its props, and the
-story's args for what it sets; `changed` finds no story through the imports, so check the stories you touched by name.
+| `npx forgebook find "selectable card" --json` | Whether it already exists: ask before writing a component |
+| `npx forgebook story <id> --json` | `requiredProps` (set every name), props, `docs.guidance` (never use a deprecated component), the `links` a person opens |
+| `npx forgebook tokens --nearest "#1c1b1b" --json` | The token to write instead of a raw colour or size; only when it says `isClose` or `isExact` |
+| `npx forgebook search onValueChange --json` | A prop or a sentence anywhere in the catalogue |
+| `npx forgebook guide <topic>` | The full text on demand: `stories`, `devices`, `switches`, `docs-pages`, `links`, `commands`, `setup`, a framework's name, or `all`; with no topic, the list |
 
-A story's frame runs on its own origin (the dev server's second port), unless the catalogue keeps it on its own
-(`frames: "same-origin"`, `forgebook dev --frames same-origin`): open a story by the `page` or `frame` link an answer
-gives, never by building a frame's address yourself, and do not expect a story's code to reach the catalogue's page or
-its API.
+`npx forgebook <command> --help` gives the options. With an MCP client, `npx forgebook mcp` offers the same as tools:
+`find_component`, `get_story`, `nearest_token`, `check_story`, `story_shot`, `get_guide`.
 
-An edit you save reaches the open story at once, a story file's in tens of milliseconds. One that the open story does
-not show may not have reached the dev server: in a container, a Windows drive under WSL or a network drive, run it
-with `forgebook dev --poll`.
+### Writing a story
 
-Run `npx forgebook <command> --help` for the options. With an MCP client, `npx forgebook mcp` offers the same as tools.
+One file per component, beside it, in CSF 3 (`npx forgebook new <component file>` writes the first). Every named export is a
+story, with a one-line TSDoc. Add a worst case: very long text, words without spaces, huge numbers.
 
-A client that renders MCP Apps also gets `story_preview`, which shows a story to the person, live, inside the conversation.
-You do not see what it shows: to look at a story yourself, use `shot` (`story_shot`). Where the tool is not listed, the
-client cannot show one: give the person the story's link, or its picture.
+{{framework}}

package/dist/bin/forgebook/agentsText.js

@@ -29,7 +29,8 @@ export const withAgentsSection = (existing, section) => {
         const after = existing.slice(end + AGENTS_END.length).replace(/^\n/, "");
         return `${existing.slice(0, start)}${block}${after}`;
     }
-    return `${existing.replace(/\n*$/, "")}\n\n${block}`;
+    // not a pattern anchored at the end, which backtracks on a long run of blank lines
+    return `${existing.trimEnd()}\n\n${block}`;
 };
 /**
  * Where the skill is written, from the project's root: `.agents/skills` is the Agent Skills standard's folder, which

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

@@ -0,0 +1,59 @@
+import type { ConfigEnv, PluginOption } from "vite";
+import type { ResolvedConfig } from "../../../src/vite/configFile.ts";
+/** What a catalogue read of the app's build, for the line it prints and for tools. */
+export type AppBuildReport = {
+    /** The Vite configuration it loaded, from the catalogue's folder; none when it loaded none. */
+    readonly viteConfig: string | undefined;
+    /** The names of the plugins of it the catalogue runs. */
+    readonly plugins: readonly string[];
+    /** The names of the plugins of it the catalogue leaves out. */
+    readonly leftOutPlugins: readonly string[];
+    /** Whether `tsconfig.json`'s `paths` are read. */
+    readonly tsconfigPaths: boolean;
+    /** Whether the project's PostCSS runs. */
+    readonly postcss: boolean;
+    /** What could not be read, each with what to do. */
+    readonly problems: readonly string[];
+};
+/** A catalogue's Vite plugins for the app's build, and what they read. */
+export type AppBuild = {
+    /** The plugins; none for a project with nothing to read. */
+    readonly plugins: readonly PluginOption[];
+    /** What they read. */
+    readonly report: AppBuildReport;
+};
+/**
+ * The sentence for a Vite configuration that did not load.
+ *
+ * @param file - the file.
+ * @param error - what it threw.
+ */
+export declare const viteConfigProblem: (file: string, error: unknown) => string;
+/** The line a catalogue prints of what it read; none when it read nothing. */
+export declare const appBuildLine: (report: AppBuildReport) => string | undefined;
+/** What a catalogue will read of a project's build, as a command that runs none of it tells. */
+export type AppBuildPlan = {
+    /** The Vite configuration it will load, from the project's folder; none when there is nothing to load. */
+    readonly viteConfig: string | undefined;
+    /** Whether it will read `tsconfig.json`'s `paths`, which runs nothing. */
+    readonly tsconfigPaths: boolean;
+    /** The PostCSS configuration it will run, as a path; none when there is none. */
+    readonly postcss: string | undefined;
+    /** The files whose code runs when the catalogue starts, from the project's folder. */
+    readonly runsCode: readonly string[];
+};
+/**
+ * What a catalogue will read of a project's build, from the files alone: nothing here runs any of it.
+ *
+ * @param dir - the project's folder.
+ * @param framework - the adapter's name.
+ */
+export declare const appBuildPlan: (dir: string, framework: string) => AppBuildPlan;
+/**
+ * What a catalogue reads of the app's build.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param environment - the command and the mode the catalogue runs for.
+ * @param isOneShot - whether the server is a one-shot command's, which leaves out the plugins' `configureServer`.
+ */
+export declare const appBuildOf: (config: ResolvedConfig, environment: ConfigEnv, isOneShot?: boolean) => Promise<AppBuild>;

package/dist/bin/forgebook/appBuild/appBuild.js

@@ -0,0 +1,213 @@
+/**
+ * The app's own build, as a catalogue draws its stories with it: the Vite plugins that give the catalogue the project's
+ * `tsconfig` paths, what its `vite.config` keeps, and its PostCSS.
+ *
+ * @remarks
+ * A project with none of these pays a few file checks, and nothing is imported. A framework whose adapter reads a part
+ * itself keeps doing so: Next.js has no Vite configuration and runs PostCSS itself, Nuxt and SvelteKit bring their
+ * aliases from their own configuration, SvelteKit reads its `vite.config` for its options, and React Native runs its
+ * own PostCSS. What could not be read never stops a catalogue: the stories that do not need it still draw, and each
+ * problem is said once with what to do.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { PostcssConfigError, postcssConfigPlace, projectPostcss, watchedFiles } from "../../../src/vite/projectPostcss.js";
+import { isWorthLoading, loadAppViteConfig, viteConfigFile } from "./appViteConfig.js";
+import { hasTsconfigPaths } from "./tsconfigPaths.js";
+/** The names of a Nuxt config, whose modules the Nuxt adapter loads. */
+const NUXT_CONFIGS = ["nuxt.config.ts", "nuxt.config.js", "nuxt.config.mjs"];
+/** What each framework's adapter reads itself, by the adapter's name. */
+const READ_BY_ADAPTER = {
+    nextjs: ["vite-config", "postcss", "tsconfig-paths"],
+    nuxt: ["vite-config", "tsconfig-paths"],
+    sveltekit: ["vite-config"],
+    angular: ["vite-config"],
+    "react-native-web": ["postcss"]
+};
+/** A style sheet PostCSS runs on: plain CSS, a component's style block among them; Sass compiles its own first. */
+const CSS_FILE = /\.(?:css|pcss|postcss)(?:\?.*)?$/;
+/**
+ * Whether a sheet is one nobody sees: a global sheet on the server, which loads a preview for its args and parameters.
+ * Run through Tailwind 3 there, it scanned every component, most of a command's start. A module's sheet keeps its class
+ * names, which a component reads wherever it runs.
+ *
+ * @param consumer - who the environment serves.
+ * @param id - the sheet.
+ */
+const isUnseenOnServer = (consumer, id) => consumer === "server" && !CSS_MODULE.test(id);
+/** A CSS module, whose class names a component reads wherever it runs. */
+const CSS_MODULE = /\.module\.[a-z]+(?:\?.*)?$/;
+/** A style sheet's imports that are not compiled, which Vite's own CSS pipeline leaves alone too. */
+const NOT_COMPILED = /[?&](?:raw|url)\b/;
+/**
+ * The plugin that runs the project's PostCSS before Lightning CSS.
+ *
+ * @param dir - the catalogue's folder.
+ * @param inlinePlugins - what the app's `css.postcss` makes; the project's file is read when none.
+ * @returns the plugin, or none for a project with no PostCSS.
+ */
+const postcssPlugin = (dir, inlinePlugins) => {
+    const run = projectPostcss(dir, inlinePlugins === undefined ? {} : { plugins: inlinePlugins });
+    if (run === undefined)
+        return undefined;
+    let isSaid = false;
+    // Vite runs the project's PostCSS itself when the catalogue's CSS goes through PostCSS rather than Lightning CSS (an
+    // app's configuration may ask for it): a second run would cost every style sheet as much again, for the same output
+    let isRunByVite = false;
+    const isLeftAlone = (id) => isRunByVite || NOT_COMPILED.test(id);
+    return {
+        name: "forgebook:app-postcss",
+        enforce: "pre",
+        configResolved(resolved) {
+            isRunByVite = resolved.css.transformer !== "lightningcss";
+        },
+        transform: {
+            filter: { id: CSS_FILE },
+            async handler(code, id) {
+                if (isLeftAlone(id))
+                    return undefined;
+                if (isUnseenOnServer(this.environment.config.consumer, id))
+                    return { code: "", map: null };
+                let result;
+                try {
+                    result = await run(code, id.split("?")[0] ?? id);
+                }
+                catch (error) {
+                    if (!(error instanceof PostcssConfigError))
+                        throw error;
+                    if (!isSaid)
+                        this.warn(`The project's PostCSS could not be loaded: ${error.message}. Set appBuild: { postcss: false } to leave it out`);
+                    isSaid = true;
+                    return undefined;
+                }
+                // the files a plugin read (Tailwind CSS reads the components for their classes) renew the style sheet
+                for (const watched of watchedFiles(result.messages))
+                    this.addWatchFile(watched);
+                return { code: result.css, map: null };
+            }
+        }
+    };
+};
+/**
+ * The sentence for a Vite configuration that did not load.
+ *
+ * @param file - the file.
+ * @param error - what it threw.
+ */
+export const viteConfigProblem = (file, error) => `${file} could not be loaded, so its aliases and plugins are not in the catalogue: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}. Fix it, or set \`appBuild: { viteConfig: false }\` in the catalogue's configuration`;
+/** The line a catalogue prints of what it read; none when it read nothing. */
+export const appBuildLine = (report) => {
+    const parts = [
+        ...(report.viteConfig === undefined
+            ? []
+            : [`${report.viteConfig}${report.plugins.length === 0 ? "" : ` (${report.plugins.join(", ")})`}`]),
+        ...(report.tsconfigPaths ? ["tsconfig paths"] : []),
+        ...(report.postcss ? ["PostCSS"] : [])
+    ];
+    return parts.length === 0 ? undefined : `Drawing with the app's build: ${parts.join(", ")}`;
+};
+/**
+ * What a catalogue will read of a project's build, from the files alone: nothing here runs any of it.
+ *
+ * @param dir - the project's folder.
+ * @param framework - the adapter's name.
+ */
+export const appBuildPlan = (dir, framework) => {
+    const readByAdapter = READ_BY_ADAPTER[framework] ?? [];
+    const file = readByAdapter.includes("vite-config") ? undefined : viteConfigFile(dir, undefined);
+    const viteConfig = file !== undefined && isWorthLoading(dir, file) ? file : undefined;
+    const place = readByAdapter.includes("postcss") ? undefined : postcssConfigPlace(dir);
+    const postcss = place === undefined ? undefined : relative(dir, place.file);
+    return {
+        viteConfig,
+        tsconfigPaths: !readByAdapter.includes("tsconfig-paths") && hasTsconfigPaths(dir),
+        postcss,
+        // a JSON file too: the plugins it names run, and a path in it can name a file of the project's
+        runsCode: [
+            ...(viteConfig === undefined ? [] : [viteConfig]),
+            ...(postcss === undefined ? [] : [postcss]),
+            // Nuxt's adapter loads the project's modules through its nuxt.config
+            ...(framework === "nuxt" ? NUXT_CONFIGS.filter((name) => existsSync(join(dir, name))) : [])
+        ]
+    };
+};
+/**
+ * The plugin that gives Vite what was read, and says what it read and what it could not.
+ *
+ * @param fields - what the app's configuration keeps, and the `paths` reading.
+ * @param report - what was read.
+ */
+const settingsPlugin = (fields, report) => ({
+    name: "forgebook:app-build",
+    config: () => fields,
+    configResolved: (resolved) => {
+        const line = appBuildLine(report);
+        if (line !== undefined)
+            resolved.logger.info(`[forgebook] ${line}`);
+        // an error's level: a command's server logs nothing less, and the run must not pass this over in silence
+        for (const problem of report.problems)
+            resolved.logger.error(`[forgebook] ${problem}`);
+    }
+});
+/**
+ * Loads the app's Vite configuration, when the catalogue reads it and it has something to give.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param environment - the command and the mode the catalogue runs for.
+ * @param isReadingPaths - whether Vite reads `tsconfig` paths here.
+ * @param isOneShot - whether the server is a one-shot command's.
+ * @returns what it gives; why it could not be loaded.
+ */
+const appViteConfigOf = async (config, environment, isReadingPaths, isOneShot) => {
+    const isOwn = READ_BY_ADAPTER[config.framework.name]?.includes("vite-config") === true;
+    const file = isOwn ? undefined : viteConfigFile(config.dir, config.appBuild.viteConfig);
+    if (file === undefined || !isWorthLoading(config.dir, file))
+        return {};
+    try {
+        return {
+            app: await loadAppViteConfig(config.dir, file, environment, config.framework.name, config.appBuild, isReadingPaths, isOneShot)
+        };
+    }
+    catch (error) {
+        return { problem: viteConfigProblem(file, error) };
+    }
+};
+/**
+ * What a catalogue reads of the app's build.
+ *
+ * @param config - the catalogue's configuration, read.
+ * @param environment - the command and the mode the catalogue runs for.
+ * @param isOneShot - whether the server is a one-shot command's, which leaves out the plugins' `configureServer`.
+ */
+export const appBuildOf = async (config, environment, isOneShot = false) => {
+    const options = config.appBuild;
+    const readByAdapter = READ_BY_ADAPTER[config.framework.name] ?? [];
+    const tsconfigPaths = options.tsconfigPaths && !readByAdapter.includes("tsconfig-paths") && hasTsconfigPaths(config.dir);
+    const { app, problem } = await appViteConfigOf(config, environment, tsconfigPaths, isOneShot);
+    const postcss = options.postcss && !readByAdapter.includes("postcss")
+        ? postcssPlugin(config.dir, app?.postcssPlugins)
+        : undefined;
+    const report = {
+        viteConfig: app?.file,
+        plugins: (app?.plugins ?? []).map((plugin) => plugin.name),
+        leftOutPlugins: app?.leftOut ?? [],
+        tsconfigPaths,
+        postcss: postcss !== undefined,
+        problems: [...(problem === undefined ? [] : [problem]), ...(app?.notes ?? [])]
+    };
+    const fields = app?.fields ?? {};
+    const settings = tsconfigPaths
+        ? { ...fields, resolve: { ...fields.resolve, tsconfigPaths: true } }
+        : fields;
+    const isEmpty = Object.keys(settings).length === 0 && report.problems.length === 0 && appBuildLine(report) === undefined;
+    return {
+        plugins: [
+            ...(isEmpty ? [] : [settingsPlugin(settings, report)]),
+            ...(app?.plugins ?? []),
+            ...(postcss === undefined ? [] : [postcss])
+        ],
+        report
+    };
+};

package/dist/bin/forgebook/appBuild/appViteConfig.d.ts

@@ -0,0 +1,96 @@
+import type { ConfigEnv, Plugin, UserConfig } from "vite";
+import type { ResolvedAppBuild } from "../../../src/vite/appBuildOption.ts";
+/**
+ * Whether a `vite.config` can hold nothing for a catalogue, as its text shows: it loads only Vite and the framework's
+ * plugin, and names none of the settings taken nor anything a plugin written in the file would hold.
+ *
+ * @remarks
+ * The usual configuration of a new project is exactly this, and loading it means bundling it and starting the module
+ * graph it imports, which a project with nothing to read must not pay. The check only ever errs towards loading: a word
+ * in a comment loads a file that gives nothing.
+ *
+ * @param text - the file's text.
+ */
+export declare const holdsNothingForCatalogue: (text: string) => boolean;
+/** The app's Vite configuration, as a catalogue takes it. */
+export type AppViteConfig = {
+    /** The file, from the catalogue's folder. */
+    readonly file: string;
+    /** What is about how its modules and style sheets resolve and compile. */
+    readonly fields: UserConfig;
+    /** The plugins kept. */
+    readonly plugins: readonly Plugin[];
+    /** The names of the plugins left out, each once. */
+    readonly leftOut: readonly string[];
+    /** The PostCSS plugins its `css.postcss` makes; none when it makes none. */
+    readonly postcssPlugins: readonly unknown[] | undefined;
+    /** What it sets that a catalogue cannot do, each said. */
+    readonly notes: readonly string[];
+};
+/**
+ * The app's Vite configuration file, from the catalogue's folder, or none.
+ *
+ * @param dir - the catalogue's folder.
+ * @param asked - `appBuild.viteConfig`.
+ */
+export declare const viteConfigFile: (dir: string, asked: string | false | undefined) => string | undefined;
+/**
+ * Whether the app's Vite configuration is worth loading.
+ *
+ * @param dir - the catalogue's folder.
+ * @param file - the file, from there.
+ */
+export declare const isWorthLoading: (dir: string, file: string) => boolean;
+/**
+ * Whether one of the app's plugins goes into the catalogue.
+ *
+ * @param name - the plugin's name.
+ * @param framework - the adapter's name.
+ * @param options - what the catalogue's configuration asks.
+ * @param isReadingPaths - whether Vite reads `tsconfig` paths here, which a plugin that does the same is then not needed for.
+ */
+export declare const keepsAppPlugin: (name: string, framework: string, options: ResolvedAppBuild, isReadingPaths?: boolean) => boolean;
+/**
+ * A `define` without a whole environment written out: a catalogue bundles code the app does not (Testing Library reads
+ * `process.env`), so what the app kept out of its bundles would reach the catalogue's.
+ *
+ * @param define - the configuration's.
+ */
+export declare const withoutWholeEnvironment: (define: NonNullable<UserConfig["define"]>) => NonNullable<UserConfig["define"]>;
+/**
+ * What a catalogue takes of the app's configuration besides its plugins: what decides how a module resolves and
+ * compiles. `root`, `base`, `build`, `server`, `preview` and `test` are about the app's page and output.
+ *
+ * @param config - the configuration, loaded.
+ * @param dir - the catalogue's folder, which its relative paths are read against when it names no root.
+ */
+export declare const appConfigFields: (config: UserConfig, dir: string) => UserConfig;
+/**
+ * One of the app's plugins, kept from reaching past what a catalogue takes of an app.
+ *
+ * @remarks
+ * What its `config` returns goes through the same filter as the file's, or a plugin could set the host, `fs.strict` or the
+ * output. Its `configureServer` runs at the normal time, after the middlewares that keep each origin to itself: `order: "pre"`
+ * would answer ahead of them. Its `transformIndexHtml` reaches the frames and not the catalogue's page, whose origin holds the
+ * agent API: a story's frame is what the app's page stands for. A one-shot command's server runs no `configureServer` at all:
+ * that hook is where a plugin starts a backend or a watcher of its own, whose output on an inherited stdout would break a
+ * command's `--json`, and nothing a story asks for in the moment it is checked needs what it sets up for edits.
+ *
+ * @param plugin - the plugin.
+ * @param dir - the folder its relative paths are read against.
+ * @param isOneShot - whether the server is a one-shot command's.
+ */
+export declare const guardedAppPlugin: (plugin: Plugin, dir: string, isOneShot?: boolean) => Plugin;
+/**
+ * Loads the app's Vite configuration, and takes what a catalogue takes of it.
+ *
+ * @param dir - the catalogue's folder.
+ * @param file - the file, from there.
+ * @param environment - the command and the mode it is loaded for: a configuration may be a function of them.
+ * @param framework - the adapter's name.
+ * @param options - what the catalogue's configuration asks.
+ * @param isReadingPaths - whether Vite reads `tsconfig` paths here.
+ * @param isOneShot - whether the server is a one-shot command's.
+ * @throws what the file throws when it loads.
+ */
+export declare const loadAppViteConfig: (dir: string, file: string, environment: ConfigEnv, framework: string, options: ResolvedAppBuild, isReadingPaths: boolean, isOneShot: boolean) => Promise<AppViteConfig>;