forgebook 0.1.8 → 0.3.0

package/dist/src/vite/agentIds.d.ts

@@ -0,0 +1,25 @@
+import type { AgentComponent, AgentStory, StoriesDocument } from "./agent.types.ts";
+/**
+ * The component an id names: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export declare const namedComponent: (document: StoriesDocument, id: string) => AgentComponent | undefined;
+/**
+ * The story an id names, with its component: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export declare const namedStory: (document: StoriesDocument, id: string) => {
+    readonly component: AgentComponent;
+    readonly story: AgentStory;
+} | undefined;
+/**
+ * The id the former rule gave a story of the document, when it differs from its id: its pictures may still carry it.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export declare const formerIdOf: (component: AgentComponent, story: AgentStory) => string | undefined;

package/dist/src/vite/agentIds.js

@@ -0,0 +1,41 @@
+/**
+ * Finds a component or a story of the stories' document by an id, the id an earlier rule gave it included, for the
+ * commands that read the document rather than the tree (`forgebook check`, `forgebook shot`, `forgebook diff`, the
+ * `story_links` tool).
+ *
+ * @remarks
+ * The tree finds a former id itself (`findStory`); the document carries only the current ids, so the former ones are
+ * worked out from each component's source and title and each story's export, by the same rule. Pure.
+ *
+ * @module
+ */
+import { formerComponentId, formerStoryId } from "../storyTree.js";
+/**
+ * The component an id names: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export const namedComponent = (document, id) => document.components.find((component) => component.id === id) ??
+    document.components.find((component) => formerComponentId(component.source, component.title) === id);
+/**
+ * The story an id names, with its component: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export const namedStory = (document, id) => {
+    const stories = document.components.flatMap((component) => component.stories.map((story) => ({ component, story })));
+    return (stories.find(({ story }) => story.id === id) ??
+        stories.find(({ component, story }) => formerStoryId(component.source, component.title, story.exportName) === id));
+};
+/**
+ * The id the former rule gave a story of the document, when it differs from its id: its pictures may still carry it.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export const formerIdOf = (component, story) => {
+    const former = formerStoryId(component.source, component.title, story.exportName);
+    return former === story.id ? undefined : former;
+};

package/dist/src/vite/agentIndex.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The catalogue as a file, for `forgebook mcp --from`: what its read-only tools answer with no dev server and no repository.
+ *
+ * @remarks
+ * `forgebook build --agent-index` writes it beside the pages. It holds what the dev server's answers hold (stories, their
+ * props and docs, tokens), and the links are made when it is read, since only the reader knows where the catalogue is
+ * served. The questions run the code the dev server runs, so a built catalogue answers as a running one does.
+ *
+ * @module
+ */
+import type { UsageGuidance } from "../componentDocs.ts";
+import type { StoriesDocument, StoryDocument } from "./agent.types.ts";
+import { type CataloguePages } from "./agentApi.ts";
+import type { AgentAnswer } from "./agentRoutes.ts";
+import { type FindableComponent } from "./findComponent.ts";
+import { type TokenReading } from "./tokenAnswers.ts";
+/** The file's name in the built catalogue. */
+export declare const AGENT_INDEX_FILE = "forgebook-agent.json";
+/** A component as a search finds it, with what its answer carries. */
+export type IndexedComponent = FindableComponent & {
+    /** Its first story's id. */
+    readonly story: string | undefined;
+    /** When to use it and when not, when its TSDoc says. */
+    readonly guidance?: UsageGuidance;
+};
+/** The file. */
+export type AgentIndex = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** The list of stories, with "Used in" where the catalogue offers it. */
+    readonly stories: StoriesDocument;
+    /** Each story in detail, by id. */
+    readonly details: Readonly<Record<string, StoryDocument>>;
+    /** What the intent search reads. */
+    readonly findable: readonly IndexedComponent[];
+    /** The tokens. */
+    readonly tokens: TokenReading;
+    /** The stories that could not be read when it was written. */
+    readonly problems: readonly string[];
+};
+/**
+ * Everything the index says went wrong while it was written, for whoever builds it: a story that failed to load is an
+ * answer with problems, not a missing one.
+ *
+ * @param index - the file.
+ */
+export declare const indexProblems: (index: AgentIndex) => readonly string[];
+/**
+ * Whether a value is an index this version reads.
+ *
+ * @param value - the parsed file.
+ */
+export declare const isAgentIndex: (value: unknown) => value is AgentIndex;
+/**
+ * Answers one of the API's paths from the file.
+ *
+ * @param index - the file.
+ * @param pages - where the catalogue is served, for the links.
+ * @param route - the path, as a dev server takes it.
+ * @param params - the query.
+ * @returns the same answer a dev server gives, or a 404 for what only a dev server can do.
+ */
+export declare const indexAnswer: (index: AgentIndex, pages: CataloguePages, route: string, params: URLSearchParams) => AgentAnswer;

package/dist/src/vite/agentIndex.js

@@ -0,0 +1,91 @@
+import { storyLinks } from "./agentApi.js";
+import { findComponents } from "./findComponent.js";
+import { TOKEN_ANSWERS } from "./tokenAnswers.js";
+/** The file's name in the built catalogue. */
+export const AGENT_INDEX_FILE = "forgebook-agent.json";
+/**
+ * Everything the index says went wrong while it was written, for whoever builds it: a story that failed to load is an
+ * answer with problems, not a missing one.
+ *
+ * @param index - the file.
+ */
+export const indexProblems = (index) => [
+    ...index.problems,
+    ...index.stories.problems,
+    ...index.tokens.unread,
+    ...index.tokens.problems,
+    ...Object.entries(index.details).flatMap(([id, detail]) => detail.problems.map((problem) => `${id}: ${problem}`))
+];
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is an index this version reads.
+ *
+ * @param value - the parsed file.
+ */
+export const isAgentIndex = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    isRecord(value["stories"]) &&
+    isRecord(value["details"]) &&
+    Array.isArray(value["findable"]) &&
+    isRecord(value["tokens"]) &&
+    Array.isArray(value["problems"]);
+/** The list with the links of where the reader finds the catalogue, and "Used in" only when asked for. */
+const storiesAnswer = ({ stories }, pages, params) => {
+    const view = params.get("view") ?? "";
+    const isUsageAsked = params.get("usedIn") === "true";
+    const components = stories.components.map(({ usedIn, ...component }) => ({
+        ...component,
+        ...(isUsageAsked && usedIn !== undefined ? { usedIn } : {}),
+        stories: component.stories.map((story) => ({ ...story, links: storyLinks(pages, story.id, view) }))
+    }));
+    return { status: 200, body: { ...stories, components } };
+};
+/** One story, with the same links. */
+const storyAnswer = ({ details }, pages, params) => {
+    const id = params.get("id") ?? "";
+    const detail = Object.hasOwn(details, id) ? details[id] : undefined;
+    if (detail === undefined)
+        return { status: 404, body: { error: `No story "${id}"` } };
+    const links = storyLinks(pages, id, params.get("view") ?? "");
+    return { status: 200, body: { ...detail, story: { ...detail.story, links } } };
+};
+/** The components a description fits. */
+const findAnswer = ({ findable }, pages, params) => {
+    const query = params.get("query") ?? "";
+    if (query.trim() === "")
+        return { status: 400, body: { error: "No words to look for" } };
+    const components = findComponents(findable, query).map((found) => {
+        const component = findable.find((each) => each.id === found.id);
+        const story = component?.story;
+        return {
+            ...found,
+            story,
+            links: story === undefined ? undefined : storyLinks(pages, story, ""),
+            ...(component?.guidance === undefined ? {} : { guidance: component.guidance })
+        };
+    });
+    const body = { schema: 1, query, components };
+    return { status: 200, body };
+};
+/**
+ * Answers one of the API's paths from the file.
+ *
+ * @param index - the file.
+ * @param pages - where the catalogue is served, for the links.
+ * @param route - the path, as a dev server takes it.
+ * @param params - the query.
+ * @returns the same answer a dev server gives, or a 404 for what only a dev server can do.
+ */
+export const indexAnswer = (index, pages, route, params) => {
+    if (route === "stories")
+        return storiesAnswer(index, pages, params);
+    if (route === "story")
+        return storyAnswer(index, pages, params);
+    if (route === "find")
+        return findAnswer(index, pages, params);
+    const tokenAnswer = Object.hasOwn(TOKEN_ANSWERS, route) ? TOKEN_ANSWERS[route] : undefined;
+    if (tokenAnswer !== undefined)
+        return tokenAnswer(index.tokens, params);
+    return { status: 404, body: { error: `A built catalogue cannot answer "${route}"` } };
+};

package/dist/src/vite/agentIndexRoute.d.ts

@@ -0,0 +1,10 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+import type { TokenReading } from "./tokenAnswers.ts";
+/**
+ * The whole catalogue, as one document.
+ *
+ * @param context - what the routes read.
+ * @param tokens - the tokens, read.
+ * @returns the index, with the stories that could not be answered at all in its problems.
+ */
+export declare const agentIndexAnswer: (context: RouteContext, tokens: TokenReading) => Promise<AgentAnswer>;

package/dist/src/vite/agentIndexRoute.js

@@ -0,0 +1,35 @@
+import { isStoriesDocument, isStoryDocument } from "./agentApi.js";
+import { storiesAnswer, storyAnswer } from "./agentRoutes.js";
+import { indexedComponents } from "./findRoute.js";
+/**
+ * The whole catalogue, as one document.
+ *
+ * @param context - what the routes read.
+ * @param tokens - the tokens, read.
+ * @returns the index, with the stories that could not be answered at all in its problems.
+ */
+export const agentIndexAnswer = async (context, tokens) => {
+    const listed = await storiesAnswer({ ...context, params: new URLSearchParams({ usedIn: "true" }) });
+    if (!isStoriesDocument(listed.body))
+        return listed;
+    const stories = listed.body;
+    const ids = stories.components.flatMap((component) => component.stories.map((story) => story.id));
+    const details = {};
+    const problems = [];
+    for (const id of ids) {
+        const answer = await storyAnswer({ ...context, params: new URLSearchParams({ id }) });
+        if (answer.status === 200 && isStoryDocument(answer.body))
+            details[id] = answer.body;
+        else
+            problems.push(`${id}: ${JSON.stringify(answer.body)}`);
+    }
+    const body = {
+        schema: 1,
+        stories,
+        details,
+        findable: await indexedComponents(context),
+        tokens,
+        problems
+    };
+    return { status: 200, body };
+};

package/dist/src/vite/agentRoutes.d.ts

@@ -1,21 +1,53 @@
-/**
- * The dev server's answers to tools and agents, under `/__forgebook/api/`: `stories` (every story) and `story?id=…`
- * (one in detail), each with an optional `view` (the view's query, `theme=dark&lang=it`) the links open in.
- *
- * @remarks
- * The server loads the sources and the previews with the same imports the pages use (`AGENT_SOURCES_FILE`), so a tool
- * sees what the shell shows. A story module that fails on Node (it reads `window` while it loads) gives its story a
- * problem in the answer instead of an error. Served by the dev server only, where Vite listens (localhost by default);
- * a build has none of it.
- *
- * @module
- */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { ViteDevServer } from "vite";
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ViteDevServer } from "vite";
+import { type LoadedPreview } from "../frame/storyModule.ts";
+import type { FramesPlacement, PageOrigins } from "../frameOrigins.ts";
 import type { LiveErrors } from "../liveErrors.ts";
+import { type StoryTree } from "../storyTree.ts";
+import { type CataloguePages, type LoadedStoryParts } from "./agentApi.ts";
 import type { ResolvedConfig } from "./configFile.ts";
 /** The path the answers live under. */
 export declare const AGENT_API = "/__forgebook/api/";
+/**
+ * The pages under `AGENT_API` another origin's page may frame: a client's inline preview. They show a story and act on
+ * nothing, so the catalogue's guard lets another origin open them, as it does the catalogue's page.
+ */
+export declare const FRAMED_AGENT_PAGES: ReadonlySet<string>;
+/** What the agent module gives: the sources and the previews merged. */
+type AgentModule = {
+    /** The catalogue's sources, in its order. */
+    readonly sources: readonly StorySource[];
+    /** Its previews merged. */
+    readonly preview: LoadedPreview;
+    /** Why a preview was left out: it could not load on the server. */
+    readonly problems: readonly string[];
+};
+/**
+ * The agent module read with the catalogue's previews, or why it is not what the plugin generates.
+ *
+ * @param module - the module of `AGENT_SOURCES_FILE`, as the server loaded it.
+ * @param previews - what loads each preview, in the configuration's order.
+ */
+export declare const agentModuleOf: (module: unknown, previews: readonly (() => Promise<unknown>)[]) => Promise<AgentModule>;
+/** A loader's value, or why it failed. */
+export declare const settled: (load: (() => Promise<unknown>) | undefined) => Promise<LoadedStoryParts["docs"]>;
+/** What an answer asks of the dev server. */
+export type AgentServer = {
+    /** Loads a module on the server. */
+    readonly load: (id: string) => Promise<unknown>;
+    /** Loads a preview on the server, with what only a browser can load left as placeholders (`previewRunner.ts`). */
+    readonly loadPreview: (file: string) => Promise<unknown>;
+    /** The file a source's module specifier leads to, as the pages' imports find it; none when nothing does. */
+    readonly resolveSource: (specifier: string) => Promise<string | undefined>;
+};
+/**
+ * What the answers ask of a dev server.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration, whose generated module the sources are imported from.
+ */
+export declare const agentServer: (server: ViteDevServer, config: ResolvedConfig) => AgentServer;
 /** An answer: its HTTP status and its JSON body. */
 export type AgentAnswer = {
     /** 200, 404 for a story or a path that does not exist, 500 when the sources fail to load. */
@@ -32,26 +64,55 @@ export declare const ROOT_HEADER = "forgebook-root";
  * @param dir - the catalogue's folder.
  */
 export declare const rootHeaderValue: (dir: string) => string;
+/** What every route reads: the catalogue's sources and tree, its configuration, the query and the links' pages. */
+export type RouteContext = {
+    /** The sources and the preview, as the dev server loaded them. */
+    readonly loaded: AgentModule;
+    /** The sources' story tree. */
+    readonly tree: StoryTree;
+    /** The catalogue's configuration. */
+    readonly config: ResolvedConfig;
+    /** The query. */
+    readonly params: URLSearchParams;
+    /** Where the catalogue is served, for the links. */
+    readonly pages: CataloguePages;
+    /** The view the links open in; empty for the default view. */
+    readonly view: string;
+};
+/**
+ * The stories, with each component's "Used in" when asked for and offered.
+ *
+ * @param context - what the routes read.
+ */
+export declare const storiesAnswer: (context: RouteContext) => Promise<AgentAnswer>;
+/**
+ * One story in detail, its component's "Used in" when offered.
+ *
+ * @param context - what the routes read.
+ */
+export declare const storyAnswer: (context: RouteContext) => Promise<AgentAnswer>;
 /**
  * Answers one of the API's paths.
  *
- * @param load - loads a module on the server (the dev server's `ssrLoadModule`).
+ * @param server - what the answers ask of the dev server.
  * @param config - the catalogue's configuration.
  * @param route - the path under `AGENT_API` (`stories`, `story`).
- * @param params - the query: `id` for a story, `view` for the links, `usedIn=true` for the list's "Used in" (a
+ * @param params - the query: `id` for a story, `view` for the links, `category`, `name`, `value` and `type` for the
+ *   tokens, `query` and `limit` for a search, `usedIn=true` for the list's "Used in" (a
  *   story's comes with it when the catalogue offers it).
- * @param origin - where the catalogue is served (`http://localhost:5173`), for the links.
+ * @param origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.
  * @param live - the errors the open frames reported, on a dev server a browser uses; none for a server of the
  *   command's own, which no frame reports to.
  */
-export declare const agentAnswer: (load: (id: string) => Promise<unknown>, config: ResolvedConfig, route: string, params: URLSearchParams, origin: string, live?: LiveErrors) => Promise<AgentAnswer>;
+export declare const agentAnswer: (server: AgentServer, config: ResolvedConfig, route: string, params: URLSearchParams, origins: PageOrigins, live?: LiveErrors) => Promise<AgentAnswer>;
 /**
  * The middleware that answers under `AGENT_API`, for a catalogue's dev server.
  *
  * @param server - the dev server, which loads the modules.
  * @param config - the catalogue's configuration.
  * @param live - the errors the open frames report.
+ * @param placement - where the frames run, for the links to them.
  * @returns a Connect middleware: it answers its own paths and passes every other request on.
  */
-export declare const agentMiddleware: (server: ViteDevServer, config: ResolvedConfig, live: LiveErrors) => (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
-//# sourceMappingURL=agentRoutes.d.ts.map
+export declare const agentMiddleware: (server: ViteDevServer, config: ResolvedConfig, live: LiveErrors, placement: () => Promise<FramesPlacement>) => (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
+export {};