forgebook 0.3.2 → 0.4.0

package/dist/bin/forgebook/newProject/newProject.types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * What `forgebook init` answers: the document `--json` prints when it wrote a catalogue's files, the one it prints when
+ * it refused, and the named steps left to the person or the agent.
+ *
+ * @module
+ */
+import type { AgentSteps } from "../agentSetup/initAgentSteps.ts";
+import type { AppBuildPlan } from "../appBuild/appBuild.ts";
+import type { ImportedFramework } from "../importers/storybookFrameworks.ts";
+/** The way a catalogue's files were made: from the project's dependencies, or from its Storybook. */
+export type InitRoute = "new-project" | "storybook";
+/** The package managers `forgebook init` writes commands for. */
+export type PackageManagerName = "npm" | "pnpm" | "yarn" | "bun";
+/** What kind of thing a next step is about, so an agent can tell them apart without reading the sentence. */
+export type NextStepKind = "style-sheet" | "provider" | "portal" | "head" | "font" | "postcss" | "setup" | "version" | "storybook";
+/** Something `forgebook init` could not do alone, named so it is not found later as a story that looks wrong. */
+export type NextStep = {
+    /** What it is about. */
+    readonly kind: NextStepKind;
+    /** The project's file it was read from; none when it comes from no one file. */
+    readonly file: string | undefined;
+    /** What to do, one sentence. */
+    readonly message: string;
+};
+/** The state of the packages the written configuration needs. */
+export type InitInstall = {
+    /** The packages the project declares nowhere and cannot load. */
+    readonly missing: readonly string[];
+    /** The command that gets them; none when everything is there. */
+    readonly command: string | undefined;
+    /** Whether nothing is needed, the command is left to run, `--install` ran it, or it failed. */
+    readonly status: "not-needed" | "to-run" | "ran" | "failed";
+    /** Why it failed; none unless it did. */
+    readonly error: string | undefined;
+};
+/** A command to run next, with what it is for. */
+export type InitCommand = {
+    /** The command, as the project's package manager runs it. */
+    readonly command: string;
+    /** What it does. */
+    readonly description: string;
+    /** The placeholder in the command to fill before running it (`<component file>`); none when it runs as it is. */
+    readonly placeholder: string | undefined;
+};
+/**
+ * What `forgebook init --json` prints when it wrote the files. The exit code is 0, or 1 with `install.status` `"failed"`,
+ * `browser.status` `"failed"` or a `draw.status` other than `"drawn"`: the files are written either way.
+ */
+export type InitDocument = {
+    /** The document's version. */
+    readonly schema: 1;
+    /** How the files were made. */
+    readonly route: InitRoute;
+    /** The framework the stories are written for. */
+    readonly framework: ImportedFramework;
+    /** The package manager the commands are for. */
+    readonly packageManager: {
+        /** Its name. */
+        readonly name: PackageManagerName;
+        /** The file that says so; none when no file does and npm was assumed. */
+        readonly detectedFrom: string | undefined;
+    };
+    /** The files written, from the project's folder. */
+    readonly written: readonly string[];
+    /** Those of them that replaced a file, with `--force`. */
+    readonly replaced: readonly string[];
+    /** The story globs written; none when a catalogue already there was kept (`--agents`). */
+    readonly stories: readonly string[];
+    /** What the configuration needs installed. */
+    readonly install: InitInstall;
+    /** What the catalogue will read of the app's build when it starts; `init` itself runs none of it. */
+    readonly appBuild: AppBuildPlan;
+    /** What was left to do, each named. */
+    readonly nextSteps: readonly NextStep[];
+    /** The commands to run next, in order. */
+    readonly commands: readonly InitCommand[];
+} & AgentSteps;
+/** Why `forgebook init` wrote nothing. */
+export type InitRefusalCode = "no-package" | "unreadable-package" | "unknown-framework" | "ambiguous-framework" | "existing-files" | "symlink" | "versions" | "storybook-found" | "storybook" | "failed";
+/**
+ * What `forgebook init --json` prints when it stopped, with exit code 1: nothing was written, unless `refused` is
+ * `"failed"`, an error while reading or writing. A wrong command line is exit code 2, with no document.
+ */
+export type InitRefusal = {
+    /** The document's version. */
+    readonly schema: 1;
+    /** Why. */
+    readonly refused: InitRefusalCode;
+    /** The reason, one sentence. */
+    readonly message: string;
+    /** What to do about it; none when there is nothing to add. */
+    readonly hint: string | undefined;
+    /** The frameworks `--framework` takes; none when the framework is not the reason. */
+    readonly supported: readonly ImportedFramework[] | undefined;
+    /** The files or packages concerned; none when no one of them is. */
+    readonly concerned: readonly string[] | undefined;
+};

package/dist/bin/forgebook/newProject/newProject.types.js

@@ -0,0 +1,6 @@
+/**
+ * What `forgebook init` answers: the document `--json` prints when it wrote a catalogue's files, the one it prints when
+ * it refused, and the named steps left to the person or the agent.
+ *
+ * @module
+ */

package/dist/bin/forgebook/newProject/packageManagers.d.ts

@@ -0,0 +1,51 @@
+import type { PackageManagerName } from "./newProject.types.ts";
+/** A project's package manager, with what says so. */
+export type DetectedPackageManager = {
+    /** Its name. */
+    readonly name: PackageManagerName;
+    /** The file that says so, from the project's folder; none when none does and npm was assumed. */
+    readonly detectedFrom: string | undefined;
+};
+/**
+ * The package manager of a project.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @returns the one its files name; npm when none does.
+ */
+export declare const detectPackageManager: (projectDir: string) => DetectedPackageManager;
+/**
+ * What a package manager must be told to add a package at a workspace's root: pnpm and Yarn 1 stop otherwise. Yarn 2 and
+ * later have no such flag, and keep a `.yarnrc.yml`.
+ *
+ * @param name - the package manager.
+ * @param dir - the folder the command runs in.
+ */
+export declare const workspaceRootFlags: (name: PackageManagerName, dir: string) => readonly string[];
+/**
+ * The arguments that add packages for development, or install what is declared when there are none to add.
+ *
+ * @param name - the package manager.
+ * @param packages - the packages to add.
+ * @param rootFlags - what it must be told at a workspace's root (`workspaceRootFlags`).
+ */
+export declare const installArguments: (name: PackageManagerName, packages: readonly string[], rootFlags: readonly string[]) => readonly string[];
+/**
+ * How a project's package manager runs the `forgebook` it installed.
+ *
+ * @param name - the package manager.
+ */
+export declare const forgebookRunner: (name: PackageManagerName) => string;
+/**
+ * A package manager's command as a process starts it: on Windows it is a `.cmd`, which only a shell starts. The shell is
+ * named by its full path, and told not to look in the current folder first, or a project's own `npm.cmd` would run.
+ *
+ * @param name - the package manager.
+ * @param args - its arguments: names from Forgebook's own tables, so nothing a shell would read.
+ * @param env - the environment it runs in.
+ * @param platform - the system; the running one unless a test names another.
+ */
+export declare const spawnedCommand: (name: PackageManagerName, args: readonly string[], env: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform) => {
+    readonly program: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+};

package/dist/bin/forgebook/newProject/packageManagers.js

@@ -0,0 +1,121 @@
+/**
+ * Which package manager a project uses, and its commands: what `forgebook init` prints, and runs with `--install`.
+ *
+ * @remarks
+ * The project's files decide, never who started the command: `npx` starts it in a pnpm project too. `packageManager` is
+ * what Corepack obeys, so it comes before a lock file. A workspace package's lock file is at the workspace's root, so the
+ * search goes up, but only a folder that declares a workspace counts: a stray lock file in a parent folder decides
+ * nothing. It stops at the repository's root.
+ *
+ * @module
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { VITE_PATHS } from "../../../src/vite/vitePaths.js";
+/** The lock files, in the order they are looked for in one folder. */
+const LOCK_FILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+    ["npm-shrinkwrap.json", "npm"]
+];
+/** The manager a `packageManager` field names (`pnpm@10.19.0`), read from a `package.json`'s text. */
+const managerField = (text) => {
+    const name = text.match(/"packageManager"\s*:\s*"(npm|pnpm|yarn|bun)@/)?.[1];
+    return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : undefined;
+};
+/** A `package.json`'s text in a folder; empty when it has none. */
+const manifestText = (dir) => {
+    const manifest = join(dir, "package.json");
+    return existsSync(manifest) ? readFileSync(manifest, "utf8") : "";
+};
+/** Whether a folder declares a workspace. */
+const isWorkspace = (dir) => existsSync(join(dir, "pnpm-workspace.yaml")) || /"workspaces"\s*:/.test(manifestText(dir));
+/** What one folder says of its manager, in the order of trust, with the file that says so. */
+const managerIn = (dir) => {
+    const field = managerField(manifestText(dir));
+    if (field !== undefined)
+        return [field, "package.json"];
+    for (const [file, name] of LOCK_FILES)
+        if (existsSync(join(dir, file)))
+            return [name, file];
+    if (existsSync(join(dir, "pnpm-workspace.yaml")))
+        return ["pnpm", "pnpm-workspace.yaml"];
+    return existsSync(join(dir, ".yarnrc.yml")) ? ["yarn", ".yarnrc.yml"] : undefined;
+};
+/**
+ * The package manager of a project.
+ *
+ * @param projectDir - the project's folder, absolute.
+ * @returns the one its files name; npm when none does.
+ */
+export const detectPackageManager = (projectDir) => {
+    let dir = projectDir;
+    while (true) {
+        const found = dir === projectDir || isWorkspace(dir) ? managerIn(dir) : undefined;
+        if (found !== undefined)
+            return {
+                name: found[0],
+                detectedFrom: VITE_PATHS.normalize(relative(projectDir, join(dir, found[1])))
+            };
+        const parent = dirname(dir);
+        if (parent === dir || existsSync(join(dir, ".git")))
+            return { name: "npm", detectedFrom: undefined };
+        dir = parent;
+    }
+};
+/**
+ * What a package manager must be told to add a package at a workspace's root: pnpm and Yarn 1 stop otherwise. Yarn 2 and
+ * later have no such flag, and keep a `.yarnrc.yml`.
+ *
+ * @param name - the package manager.
+ * @param dir - the folder the command runs in.
+ */
+export const workspaceRootFlags = (name, dir) => {
+    if (!isWorkspace(dir))
+        return [];
+    if (name === "pnpm")
+        return ["--workspace-root"];
+    const isClassicYarn = name === "yarn" &&
+        !existsSync(join(dir, ".yarnrc.yml")) &&
+        !/"packageManager"\s*:\s*"yarn@[2-9]/.test(manifestText(dir));
+    return isClassicYarn ? ["-W"] : [];
+};
+/**
+ * The arguments that add packages for development, or install what is declared when there are none to add.
+ *
+ * @param name - the package manager.
+ * @param packages - the packages to add.
+ * @param rootFlags - what it must be told at a workspace's root (`workspaceRootFlags`).
+ */
+export const installArguments = (name, packages, rootFlags) => {
+    if (packages.length === 0)
+        return ["install"];
+    if (name === "npm")
+        return ["install", "--save-dev", ...packages];
+    return ["add", name === "pnpm" ? "--save-dev" : "--dev", ...rootFlags, ...packages];
+};
+/**
+ * How a project's package manager runs the `forgebook` it installed.
+ *
+ * @param name - the package manager.
+ */
+export const forgebookRunner = (name) => ({ npm: "npx forgebook", pnpm: "pnpm exec forgebook", yarn: "yarn forgebook", bun: "bunx forgebook" })[name];
+/**
+ * A package manager's command as a process starts it: on Windows it is a `.cmd`, which only a shell starts. The shell is
+ * named by its full path, and told not to look in the current folder first, or a project's own `npm.cmd` would run.
+ *
+ * @param name - the package manager.
+ * @param args - its arguments: names from Forgebook's own tables, so nothing a shell would read.
+ * @param env - the environment it runs in.
+ * @param platform - the system; the running one unless a test names another.
+ */
+export const spawnedCommand = (name, args, env, platform = process.platform) => platform === "win32"
+    ? {
+        program: env["ComSpec"] ?? "cmd.exe",
+        args: ["/d", "/s", "/c", name, ...args],
+        env: { ...env, NoDefaultCurrentDirectoryInExePath: "1" }
+    }
+    : { program: name, args, env };

package/dist/bin/forgebook/newProject/projectEntries.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Whether a path or a specifier names a style sheet: what a page or `angular.json` says is one is not taken on trust, as
+ * a preview's import of it would run a script.
+ *
+ * @param specifier - the path or the specifier.
+ */
+export declare const isStyleSheet: (specifier: string) => boolean;
+/**
+ * The style sheets a script loads for everything it draws: `import "./x.css"`, not `import styles from "./x.module.css"`,
+ * whose classes belong to that file.
+ *
+ * @param text - the script, or the script block of a `.svelte` or `.vue` file.
+ */
+export declare const styleSheetImports: (text: string) => readonly string[];
+/**
+ * The components an entry's markup wraps the app in, in JSX or in a Svelte file: the tags that close.
+ *
+ * @param text - the file's text.
+ */
+export declare const markupWrappers: (text: string) => readonly string[];
+/**
+ * What a Vue entry installs on the app: `app.use(router)`, `createApp(App).use(createPinia())`.
+ *
+ * @param text - the file's text.
+ */
+export declare const vueInstalls: (text: string) => readonly string[];
+/**
+ * What an Angular entry or its `app.config` provides: `provideRouter(routes)`.
+ *
+ * @param text - the file's text.
+ */
+export declare const angularProviders: (text: string) => readonly string[];
+/** What a page's HTML says. */
+export type PageFacts = {
+    /** The local scripts it starts, as written. */
+    readonly scripts: readonly string[];
+    /** The local style sheets it links, as written. */
+    readonly styleSheets: readonly string[];
+    /** The remote addresses its links load (a font's, a CDN's style sheet). */
+    readonly remoteLinks: readonly string[];
+    /** The ids in its body. */
+    readonly bodyIds: readonly string[];
+};
+/**
+ * The ids in a page's body, or in all of a text that has none (a layout's markup with no `<body>` of its own).
+ *
+ * @param html - the page or the markup.
+ */
+export declare const bodyIds: (html: string) => readonly string[];
+/**
+ * What a page's HTML says about the app it starts.
+ *
+ * @param html - the page.
+ */
+export declare const pageFacts: (page: string) => PageFacts;
+/**
+ * The global style sheets of an Angular project: the first project's build `styles` in `angular.json`, those that are
+ * injected only. The builder's option is the one place Angular names them.
+ *
+ * @param parsed - `angular.json`, parsed.
+ */
+export declare const angularStyles: (parsed: unknown) => readonly string[];

package/dist/bin/forgebook/newProject/projectEntries.js

@@ -0,0 +1,191 @@
+/**
+ * What an application's entry files say about how it is drawn, read from their text: the global style sheets, what wraps
+ * the app, the elements beside its root and what its page's head links to.
+ *
+ * @remarks
+ * Pure: text in, names out. Regular expressions instead of a parser because the entries are TSX, Vue, Svelte, HTML and
+ * JSON alike, and a name missed here costs one line less in a report the person reads, never a wrong file: only a style
+ * sheet is acted on, and `projectLook.ts` checks it before it is written. A wrapper is told from a leaf by its closing tag, so a layout's
+ * `<Header />` is not reported as something a story needs.
+ *
+ * @module
+ */
+/** The extensions of a style sheet Vite compiles. */
+const STYLE_SHEET = /\.(?:css|scss|sass|less|styl|stylus|pcss|postcss)$/;
+/**
+ * Whether a path or a specifier names a style sheet: what a page or `angular.json` says is one is not taken on trust, as
+ * a preview's import of it would run a script.
+ *
+ * @param specifier - the path or the specifier.
+ */
+export const isStyleSheet = (specifier) => STYLE_SHEET.test(specifier);
+/**
+ * A script's lines outside block comments that start their line, so a commented-out import is not read as a live one. A
+ * `/*` inside a line is left alone: it is as likely a glob in a string.
+ */
+const liveLines = (text) => {
+    let isInComment = false;
+    const lines = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trimStart();
+        if (isInComment)
+            isInComment = !line.includes("*/") && !line.includes("-->");
+        else if (trimmed.startsWith("/*"))
+            isInComment = !line.includes("*/");
+        else if (trimmed.startsWith("<!--"))
+            isInComment = !line.includes("-->");
+        else
+            lines.push(line);
+    }
+    return lines.join("\n");
+};
+/** A page without its comments: found by position, so an unclosed one costs one pass. */
+const withoutHtmlComments = (html) => {
+    let kept = "";
+    let position = 0;
+    while (position < html.length) {
+        const start = html.indexOf("<!--", position);
+        if (start === -1)
+            return kept + html.slice(position);
+        kept += html.slice(position, start);
+        const end = html.indexOf("-->", start + 4);
+        if (end === -1)
+            return kept;
+        position = end + 3;
+    }
+    return kept;
+};
+/** A statement that only loads a module: `import "./index.css";`, at the start of a line so a comment's is left out. */
+const BARE_IMPORT = /^[ \t]*import\s+["']([^"'\n]+)["']/gm;
+/** The wrappers that change nothing a story needs: React's and Solid's own, and the app itself. */
+const NEUTRAL_WRAPPERS = new Set([
+    "App",
+    "StrictMode",
+    "Suspense",
+    "Fragment",
+    "React.StrictMode",
+    "React.Suspense",
+    "React.Fragment"
+]);
+/** What Angular's bootstrap provides that a story gets anyway or does not notice. */
+const NEUTRAL_PROVIDERS = new Set([
+    "provideBrowserGlobalErrorListeners",
+    "provideClientHydration",
+    "provideZoneChangeDetection",
+    "provideZonelessChangeDetection"
+]);
+/**
+ * The style sheets a script loads for everything it draws: `import "./x.css"`, not `import styles from "./x.module.css"`,
+ * whose classes belong to that file.
+ *
+ * @param text - the script, or the script block of a `.svelte` or `.vue` file.
+ */
+export const styleSheetImports = (text) => [...liveLines(text).matchAll(BARE_IMPORT)].flatMap((match) => {
+    const specifier = match[1] ?? "";
+    return STYLE_SHEET.test(specifier) ? [specifier] : [];
+});
+/**
+ * The components an entry's markup wraps the app in, in JSX or in a Svelte file: the tags that close.
+ *
+ * @param text - the file's text.
+ */
+export const markupWrappers = (text) => [
+    ...new Set([...text.matchAll(/<\/([A-Z][\w.]*)\s*>/g)]
+        .map((match) => match[1] ?? "")
+        .filter((name) => !NEUTRAL_WRAPPERS.has(name)))
+];
+/**
+ * What a Vue entry installs on the app: `app.use(router)`, `createApp(App).use(createPinia())`.
+ *
+ * @param text - the file's text.
+ */
+export const vueInstalls = (text) => [
+    ...new Set([...text.matchAll(/\.use\(\s*([A-Za-z_$][\w$.]*)/g)].map((match) => match[1] ?? ""))
+];
+/**
+ * What an Angular entry or its `app.config` provides: `provideRouter(routes)`.
+ *
+ * @param text - the file's text.
+ */
+export const angularProviders = (text) => [
+    ...new Set([...text.matchAll(/\b(provide[A-Z]\w*)\(/g)]
+        .map((match) => match[1] ?? "")
+        .filter((name) => !NEUTRAL_PROVIDERS.has(name)))
+];
+/** One attribute of a tag's text. */
+const attribute = (tag, name) => tag.match(new RegExp(`\\b${name}=["']([^"']*)["']`))?.[1];
+/** A page's `<link>` and `<script>` tags as text. */
+const tags = (html, name) => 
+// no `<` inside a tag, so a page full of unclosed tags stays linear
+[...html.matchAll(new RegExp(`<${name}\\b[^<>]*>`, "g"))].map((match) => match[0]);
+/** Whether an address leaves the project (`https://…`, `//…`, `data:…`). */
+const isRemote = (address) => /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(address);
+/** An address fit to name in a report: a web address, with nothing a sentence could hide in it. */
+const isWebAddress = (address) => /^(?:https?:)?\/\/[^\s<>"'`]+$/i.test(address);
+/**
+ * The ids in a page's body, or in all of a text that has none (a layout's markup with no `<body>` of its own).
+ *
+ * @param html - the page or the markup.
+ */
+export const bodyIds = (html) => {
+    const start = html.search(/<body\b/i);
+    const ids = [...(start === -1 ? html : html.slice(start)).matchAll(/\bid=["']([\w-]+)["']/g)];
+    return ids.map((match) => match[1] ?? "");
+};
+/**
+ * What a page's HTML says about the app it starts.
+ *
+ * @param html - the page.
+ */
+export const pageFacts = (page) => {
+    const html = withoutHtmlComments(page);
+    const links = tags(html, "link");
+    const addresses = links.flatMap((tag) => {
+        const href = attribute(tag, "href");
+        return href === undefined ? [] : [{ href, rel: attribute(tag, "rel") ?? "" }];
+    });
+    return {
+        scripts: tags(html, "script").flatMap((tag) => {
+            const source = attribute(tag, "src");
+            return source === undefined || isRemote(source) ? [] : [source];
+        }),
+        styleSheets: addresses.flatMap(({ href, rel }) => rel === "stylesheet" && !isRemote(href) ? [href] : []),
+        remoteLinks: addresses.flatMap(({ href, rel }) => isWebAddress(href) && (rel === "stylesheet" || rel === "preload") ? [href] : []),
+        bodyIds: bodyIds(html)
+    };
+};
+/**
+ * The global style sheets of an Angular project: the first project's build `styles` in `angular.json`, those that are
+ * injected only. The builder's option is the one place Angular names them.
+ *
+ * @param parsed - `angular.json`, parsed.
+ */
+export const angularStyles = (parsed) => {
+    const projects = recordAt(parsed, "projects");
+    const all = Object.values(projects ?? {});
+    // a workspace may list a library first: the app's styles are the ones its stories miss
+    const project = all.find((each) => recordField(each, "projectType") === "application") ?? all[0];
+    const targets = recordAt(project, "architect") ?? recordAt(project, "targets");
+    const styles = recordAt(recordAt(targets, "build"), "options")?.["styles"];
+    if (!Array.isArray(styles))
+        return [];
+    return styles.flatMap((style) => {
+        if (typeof style === "string")
+            return [style];
+        const input = recordAt({ style }, "style");
+        return input?.["inject"] !== false && typeof input?.["input"] === "string" ? [input["input"]] : [];
+    });
+};
+/** A field of a value, whatever it holds. */
+const recordField = (value, name) => typeof value === "object" && value !== null
+    ? Object.entries(value).find(([key]) => key === name)?.[1]
+    : undefined;
+/** A field of a value, when both are plain objects. */
+const recordAt = (value, name) => {
+    if (typeof value !== "object" || value === null || !(name in value))
+        return undefined;
+    const field = Object.entries(value).find(([key]) => key === name)?.[1];
+    if (typeof field !== "object" || field === null || Array.isArray(field))
+        return undefined;
+    return Object.fromEntries(Object.entries(field));
+};

package/dist/bin/forgebook/newProject/projectFrameworks.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The frameworks `forgebook init` can start a catalogue for, and which one a project's `package.json` says it is on.
+ *
+ * @remarks
+ * Detection reads declared packages only, never the code: a design system lists its framework as a peer, so peers count
+ * too. A framework built on another (Next.js on React) takes its place, so a Next.js project is never asked to choose;
+ * two that stand on their own (React and Lit) are a question only the project can answer, so the command stops and
+ * names both instead of guessing. An adapter already declared settles it first: Forgebook's shell makes every project
+ * declare React beside Vue, say, once the install command has run, and that must not read as two frameworks. The peer floors repeat the adapters' `package.json` because the adapter is usually not
+ * installed yet when they are read; a test keeps the two equal.
+ *
+ * @module
+ */
+import type { ImportedFramework } from "../importers/storybookFrameworks.ts";
+/** What `forgebook init` knows of a framework. */
+export type ProjectFramework = {
+    /** Its name, for a person. */
+    readonly label: string;
+    /** The packages whose presence says a project is on it; none for a framework never detected. */
+    readonly markers: readonly string[];
+    /** The frameworks it is built on, which it takes the place of. */
+    readonly builtOn: readonly ImportedFramework[];
+    /** The packages its adapter asks the project for, each with the lowest version it takes. */
+    readonly peers: Readonly<Record<string, string>>;
+    /** The extension of the story files `forgebook new` writes for it. */
+    readonly storyExtension: "ts" | "tsx";
+    /** The folders components are usually in, in the order a title is best made from. */
+    readonly sourceFolders: readonly string[];
+};
+/** The packages `forgebook` itself asks the project for: its shell is React. Vite is its own. */
+export declare const FORGEBOOK_PEERS: Readonly<Record<string, string>>;
+/** The names `--framework` takes, the order of the supported list. */
+export declare const FRAMEWORK_NAMES: readonly ImportedFramework[];
+/** Every framework, by its adapter's name. */
+export declare const PROJECT_FRAMEWORKS: Readonly<Record<ImportedFramework, ProjectFramework>>;
+/** What a project's dependencies say about its framework. */
+export type FrameworkDetection = 
+/** One framework. */
+{
+    readonly kind: "found";
+    readonly framework: ImportedFramework;
+}
+/** None Forgebook knows. */
+ | {
+    readonly kind: "unknown";
+}
+/** Several that stand on their own. */
+ | {
+    readonly kind: "ambiguous";
+    readonly candidates: readonly ImportedFramework[];
+};
+/**
+ * The framework a project is on.
+ *
+ * @param declared - the packages it declares, with their versions as written.
+ */
+export declare const detectFramework: (declared: ReadonlyMap<string, string>) => FrameworkDetection;