@lovrozagar/honey 0.7.2 → 1.0.0-rc.1

package/dist/build/artifacts.js

@@ -0,0 +1,123 @@
+/**
+ * An app's artifacts as text (bit 19 h2): the route tree, the manifest, each OpenAPI document (JSON and YAML, Q7) and
+ * the types; bit 21 e: the MCP handler the app mounts, from its own unsanitized document of the routes `filterRoutes`
+ * keeps, honey-clients's generateMcpHandler writing its entry and the companion directory's runtime and SDK. This module runs inside the app's module graph: generate.ts loads it through the loader that loads the
+ * app, and it imports the app itself, so the app and the core reading it are one instance (core's symbols are
+ * per module). source.ts says which tree is written and which app is documented.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateOpenApi } from "../openapi/generate.js";
+import { generateManifest } from "../openapi/manifest.js";
+import { toYaml } from "../openapi/yaml.js";
+import { routeId } from "../routing/pattern.js";
+import { sanitizeOpenApiSpec } from "../schema/sanitize-spec.js";
+import { mcpPaths, openApiOutputPaths, } from "./config.js";
+import { effectConverter } from "./loaders.js";
+import { sourceOf } from "./source.js";
+/** This module's path, which generate.ts loads into the app's graph. */
+export const ARTIFACTS = /* @__PURE__ */ fileURLToPath(import.meta.url);
+/** The document `entry` describes, sanitized as it asks. */
+export function documentOf(app, entry, invalidate, effect) {
+    const document = generateOpenApi(app, {
+        converters: { effect },
+        filterRoutes: entry.filterRoutes,
+        info: { description: entry.description, title: entry.title, version: entry.version },
+        invalidate,
+        profile: entry.profile,
+        securitySchemes: entry.securitySchemes,
+    });
+    return entry.sanitize === undefined ? document : sanitizeOpenApiSpec(document, entry.sanitize);
+}
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** The types file: the unfiltered document (built once, its check already reported) joined with the extracted ctx. */
+async function typesOf(config, source, run, path) {
+    if (source.exportName === undefined)
+        throw new Error("codegen.types with codegen.mergeTree needs a gateway app: config.app, or the merge entry's app export");
+    const outputs = config.codegen.openApi;
+    const document = generateOpenApi(source.app, {
+        converters: { effect: await effectConverter() },
+        info: { title: outputs[0]?.title ?? "API", version: outputs[0]?.version ?? "0.0.0" },
+        invalidate: outputs.length > 0 ? "off" : config.codegen.invalidate,
+        /* the first output's scheme wins a name, so a route naming any declared scheme is not reported */
+        securitySchemes: Object.assign({}, ...outputs.map((entry) => entry.securitySchemes ?? {}).reverse()),
+    });
+    const extracted = run.codegen.extractTypes({
+        entryPath: source.entry,
+        exportName: source.exportName,
+        outputDir: dirname(resolve(run.root, path)),
+        report: run.report,
+        routeId,
+        tsMorph: await run.codegen.loadTsMorph(),
+    });
+    const { baseCtxName } = config.codegen.types;
+    return run.codegen.generateTypes({ baseCtxName, document, extracted, report: run.report, tree: source.tree });
+}
+/**
+ * What a generation reads, and, on a `first` pass whose documented app loads the tree it writes, that tree when it
+ * changed: to be written first and the pass redone over it on a fresh graph.
+ */
+export async function prepare(config, run) {
+    const source = await sourceOf(config, run.root, run.first);
+    const { tree } = config.codegen;
+    if (!run.first || !source.loadsTree || tree === false)
+        return { rewrite: undefined, source };
+    const text = run.codegen.generateRouteTree(source.tree);
+    const path = resolve(run.root, tree);
+    const current = existsSync(path) && readFileSync(path, "utf8") === text;
+    return { rewrite: current ? undefined : [tree, text], source };
+}
+/** The MCP handler's files for `app` as `mcp` asks, each by its path from the project root. */
+function mcpFiles(app, mcp, outputs, { codegen, effect }) {
+    const document = generateOpenApi(app, {
+        converters: { effect },
+        filterRoutes: mcp.filterRoutes,
+        info: { title: outputs[0]?.title ?? "API", version: outputs[0]?.version ?? "0.0.0" },
+        invalidate: "off",
+        /* the first output's scheme wins a name, as the types' document has it */
+        securitySchemes: mcp.securitySchemes ?? Object.assign({}, ...outputs.map((entry) => entry.securitySchemes ?? {}).reverse()),
+    });
+    const { entry, files } = codegen.generateMcpHandler(document, {
+        dir: mcp.dir,
+        ...(mcp.name === undefined ? {} : { name: mcp.name }),
+    });
+    const [path, ...companions] = mcpPaths(mcp);
+    return [[path, entry], ...companions.map((at) => [at, files[basename(at)]])];
+}
+/** Every artifact `config` asks for from `source`, by its path from the project root. */
+export async function artifactsOf(config, run, source) {
+    const { manifest, mcp, openApi, tree, types } = config.codegen;
+    const files = [];
+    if (tree !== false)
+        files.push([tree, run.codegen.generateRouteTree(source.tree)]);
+    const documented = await source.documented();
+    if (manifest !== false)
+        files.push([manifest, json(generateManifest(documented.app))]);
+    const effect = openApi.length > 0 || mcp !== false ? await effectConverter() : undefined;
+    for (const [index, entry] of openApi.entries()) {
+        /* one report per generation, not one per document */
+        const published = documentOf(documented.app, entry, index === 0 ? config.codegen.invalidate : "off", effect);
+        const { json: jsonPath, yaml } = openApiOutputPaths(entry.path);
+        if (jsonPath !== null)
+            files.push([jsonPath, json(published)]);
+        files.push([yaml, toYaml(published)]);
+    }
+    if (mcp !== false)
+        files.push(...mcpFiles(documented.app, mcp, openApi, { codegen: run.codegen, effect }));
+    if (types !== false)
+        files.push([types.path, await typesOf(config, { ...documented, tree: source.tree }, run, types.path)]);
+    return files;
+}
+/** A virtual module's code: the route tree, the manifest, or the first OpenAPI document. */
+export async function virtualCode(kind, config, run) {
+    const source = await sourceOf(config, run.root);
+    if (kind === "routes")
+        return (await run.codegen()).generateRouteTree(source.tree);
+    const { app } = await source.documented();
+    /* the generation reported the invalidate check; a module load must not again */
+    const value = kind === "manifest"
+        ? generateManifest(app)
+        : documentOf(app, config.codegen.openApi[0], "off", await effectConverter());
+    return `export default ${JSON.stringify(value)}`;
+}

package/dist/build/cli-args.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `honey` CLI's arguments: `generate` (the app-side artifacts, Q1) and `init`. Strict, with honey-clients's
+ * rules and wording (gen src/gen/args.ts; tests/integration/cli-args-parity.test.ts holds them alike): `--k v` and
+ * `--k=v`; a value is never the next flag; a boolean is bare, `true` or `false`; an unknown flag or a stray argument
+ * is a usage error. Not a package export.
+ */
+export declare const USAGE = "usage: honey generate [options]\n       honey init [--cf] [--force]\n\ngenerate options:\n  --config <path>      the Vite config holding honey() (default: vite.config.{ts,mts,js,mjs})\n  --plugin <n>         which honey() plugin in the config, 0-based, when there are several\n  --app <path>         the app entry; overrides the config's app, or replaces the config\n  --watch              generate again when files next to the app change\n  --tree --types --manifest\n                       turn an output on\n  --merge-tree <path>  the route tree source of a gateway\n  -h, --help           this text\n\nThe SDKs, the CLI and the MCP server are honey-clients's: honey-clients generate --app <path>.";
+/** A mistake in how the CLI was called: printed with the usage text. */
+export declare class UsageError extends Error {
+}
+export type CliFlags = {
+    app?: string;
+    config?: string;
+    help?: boolean;
+    manifest?: boolean;
+    mergeTree?: string;
+    plugin?: number;
+    tree?: boolean;
+    types?: boolean;
+    watch?: boolean;
+};
+/** `argv` after `generate` as its flags, or a usage error. */
+export declare function parseGenerateArgs(argv: readonly string[]): CliFlags;
+/** `honey init`'s flags: `--cloudflare` is `--cf`. */
+export type InitFlags = {
+    cf: boolean;
+    force: boolean;
+};
+/** `argv` after `init` as its flags, or a usage error. */
+export declare function parseInitFlags(argv: readonly string[]): InitFlags;

package/dist/build/cli-args.js

@@ -0,0 +1,97 @@
+/**
+ * The `honey` CLI's arguments: `generate` (the app-side artifacts, Q1) and `init`. Strict, with honey-clients's
+ * rules and wording (gen src/gen/args.ts; tests/integration/cli-args-parity.test.ts holds them alike): `--k v` and
+ * `--k=v`; a value is never the next flag; a boolean is bare, `true` or `false`; an unknown flag or a stray argument
+ * is a usage error. Not a package export.
+ */
+export const USAGE = `usage: honey generate [options]
+       honey init [--cf] [--force]
+
+generate options:
+  --config <path>      the Vite config holding honey() (default: vite.config.{ts,mts,js,mjs})
+  --plugin <n>         which honey() plugin in the config, 0-based, when there are several
+  --app <path>         the app entry; overrides the config's app, or replaces the config
+  --watch              generate again when files next to the app change
+  --tree --types --manifest
+                       turn an output on
+  --merge-tree <path>  the route tree source of a gateway
+  -h, --help           this text
+
+The SDKs, the CLI and the MCP server are honey-clients's: honey-clients generate --app <path>.`;
+/** A mistake in how the CLI was called: printed with the usage text. */
+export class UsageError extends Error {
+}
+const BOOLEAN_FLAGS = {
+    help: "help",
+    manifest: "manifest",
+    tree: "tree",
+    types: "types",
+    watch: "watch",
+};
+const VALUE_FLAGS = {
+    app: "app",
+    config: "config",
+    "merge-tree": "mergeTree",
+    plugin: "plugin",
+};
+/** A flag's value: inline after `=`, else the next argument, which may not be another flag. */
+function valueOf(flag, inline, rest) {
+    const value = inline ?? rest.shift();
+    if (value === undefined || value === "" || (inline === undefined && value.startsWith("--")))
+        throw new UsageError(`--${flag} requires a value`);
+    return value;
+}
+/** A boolean flag's value: bare is true; inline `true` or `false`, else a usage error. */
+function booleanOf(flag, inline) {
+    if (inline === undefined || inline === "true")
+        return true;
+    if (inline === "false")
+        return false;
+    throw new UsageError(`--${flag} takes true or false, not ${JSON.stringify(inline)}`);
+}
+/** One flag of `generate` into `flags`. */
+function takeFlag(arg, rest, flags) {
+    const [flag, inline] = arg.slice(2).split(/=(.*)/s, 2);
+    const bool = Object.hasOwn(BOOLEAN_FLAGS, flag) ? BOOLEAN_FLAGS[flag] : undefined;
+    if (bool !== undefined) {
+        flags[bool] = booleanOf(flag, inline);
+        return;
+    }
+    const key = Object.hasOwn(VALUE_FLAGS, flag) ? VALUE_FLAGS[flag] : undefined;
+    if (key === undefined)
+        throw new UsageError(`unknown option --${flag}`);
+    const value = valueOf(flag, inline, rest);
+    if (key === "plugin" && !/^\d+$/.test(value))
+        throw new UsageError(`--plugin takes a non-negative integer, not ${JSON.stringify(value)}`);
+    flags[key] = key === "plugin" ? Number(value) : value;
+}
+/** `argv` after `generate` as its flags, or a usage error. */
+export function parseGenerateArgs(argv) {
+    const rest = [...argv];
+    const flags = {};
+    while (rest.length > 0) {
+        const arg = rest.shift();
+        if (arg === "-h")
+            flags.help = true;
+        else if (!arg.startsWith("--") || arg === "--")
+            throw new UsageError(`unexpected argument ${JSON.stringify(arg)}`);
+        else
+            takeFlag(arg, rest, flags);
+    }
+    return flags;
+}
+/** `argv` after `init` as its flags, or a usage error. */
+export function parseInitFlags(argv) {
+    const flags = { cf: false, force: false };
+    for (const arg of argv) {
+        if (arg === "--cf" || arg === "--cloudflare")
+            flags.cf = true;
+        else if (arg === "--force")
+            flags.force = true;
+        else if (arg.startsWith("-"))
+            throw new UsageError(`unknown option ${arg}`);
+        else
+            throw new UsageError(`unexpected argument ${JSON.stringify(arg)}`);
+    }
+    return flags;
+}

package/dist/build/cli.d.ts

@@ -0,0 +1,11 @@
+export type Io = {
+    readonly err: (text: string) => void;
+    readonly out: (text: string) => void;
+};
+export type RunOptions = {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly signal?: AbortSignal;
+};
+/** Runs `honey <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
+export declare function main(argv: readonly string[], io: Io, options?: RunOptions): Promise<number>;

package/dist/build/cli.js

@@ -0,0 +1,150 @@
+/**
+ * The `honey` CLI (bit 19 h2): `honey generate [--watch]` writes the app's artifacts as the plugin does, from the
+ * `honey()` config in the Vite config (else `--app` alone), and `honey init` scaffolds a project. A generation runs
+ * once and the bin then exits, whatever the app left running; `--watch` runs each generation in a fresh child, after
+ * the one before it, on each edit next to the app. The SDKs, the CLI and MCP are honey-clients's (Q1).
+ */
+import { existsSync, statSync, watch } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parseGenerateArgs, parseInitFlags, USAGE, UsageError } from "./cli-args.js";
+import { generatedOutputs, isGeneratedOutput, resolveHoneyConfig, } from "./config.js";
+import { generateAndWrite } from "./generate.js";
+import { WATCH_IGNORE_RE } from "./glob.js";
+import { runInit } from "./init.js";
+import { createModuleLoader, findViteConfig, loadPluginConfigs } from "./loaders.js";
+import { runGenerate, serialized } from "./plugin.js";
+/** One honey() config: `--plugin` by index, else the only one, else the one whose app is `--app`. */
+function pick(configs, flags, path, cwd) {
+    if (flags.plugin !== undefined) {
+        const picked = configs[flags.plugin];
+        if (picked === undefined)
+            throw new UsageError(`--plugin ${flags.plugin}: ${path} has ${configs.length} honey() plugin(s)`);
+        return picked;
+    }
+    if (configs.length <= 1)
+        return configs[0];
+    const app = flags.app === undefined ? undefined : resolve(cwd, flags.app);
+    const byApp = configs.filter((config) => config.app !== undefined && resolve(cwd, config.app) === app);
+    if (byApp.length === 1)
+        return byApp[0];
+    const apps = configs.map((config, index) => `  ${index}: ${config.app ?? "(no app)"}`).join("\n");
+    throw new UsageError(`${path} has ${configs.length} honey() plugins; pick one with --plugin <n>:\n${apps}`);
+}
+/** The honey() configs of the Vite config at `path`; none is an error unless `--app` stands in for them. */
+async function configsIn(path, flags, env, load) {
+    const command = env.HONEY_VITE_COMMAND === "serve" ? "serve" : "build";
+    const mode = env.HONEY_VITE_MODE ?? (command === "serve" ? "development" : "production");
+    const configs = await loadPluginConfigs(path, load, { command, mode });
+    if (configs.length === 0 && (flags.config !== undefined || flags.plugin !== undefined || flags.app === undefined))
+        throw new UsageError(`no honey() plugin found in ${path}; add honey() to it or pass --app`);
+    return configs;
+}
+/** The config a run generates by: the Vite config's honey(), with the flags over it. */
+async function configOf(cwd, flags, env, load) {
+    const path = flags.config === undefined ? findViteConfig(cwd) : resolve(cwd, flags.config);
+    if (flags.config !== undefined && !existsSync(path))
+        throw new UsageError(`config file not found: ${flags.config}`);
+    const raw = path === undefined ? undefined : pick(await configsIn(path, flags, env, load), flags, path, cwd);
+    if (raw === undefined && flags.app === undefined)
+        throw new UsageError("no config found: add honey() to a vite.config.ts, or pass --app");
+    return resolveHoneyConfig(withFlags(raw ?? {}, flags));
+}
+/** `raw` with the flags over it: `--app` replaces its app, and each output flag turns that output on. */
+function withFlags(raw, flags) {
+    const on = Object.fromEntries(["manifest", "tree", "types"].filter((key) => flags[key]).map((key) => [key, true]));
+    const mergeTree = flags.mergeTree === undefined ? {} : { mergeTree: flags.mergeTree };
+    return { ...raw, app: flags.app ?? raw.app, codegen: { ...raw.codegen, ...mergeTree, ...on } };
+}
+const mtimeOf = (path) => (existsSync(path) ? statSync(path).mtimeMs : 0);
+/** Each generation a child after the one before it, on each edit beside the entry; ends 0 once `signal` aborts. */
+function watchApp(config, argv, io, options) {
+    const { cwd, signal } = options;
+    const entryRel = config.codegen.mergeTree ?? config.app;
+    if (entryRel === undefined)
+        throw new UsageError("--watch requires --app or a honey() config with app");
+    const args = argv.filter((arg) => arg !== "--watch" && !arg.startsWith("--watch="));
+    const outputs = generatedOutputs(config, cwd);
+    const regenerate = serialized(() => 
+    /* the child printed why on the inherited stderr; the watch goes on to the next edit */
+    runGenerate(args, { cwd, env: { HONEY_WATCH_CHILD: "1" } }).catch(() => undefined));
+    let latest = Promise.resolve();
+    const generate = () => {
+        latest = regenerate();
+    };
+    let timer;
+    const schedule = () => {
+        clearTimeout(timer);
+        timer = setTimeout(generate, 100);
+    };
+    /* armed before the first generation: an edit made while it runs queues one more */
+    const entry = resolve(cwd, entryRel);
+    const dir = dirname(entry);
+    const watcher = watch(dir, { recursive: true }, (_event, name) => {
+        const file = resolve(dir, String(name));
+        if (!WATCH_IGNORE_RE.test(file) && !isGeneratedOutput(file, outputs) && !outputs.dirs.includes(file))
+            schedule();
+    });
+    /* a recursive watch can miss a save that renames over the file: the entry is polled too */
+    let seen = mtimeOf(entry);
+    const poll = setInterval(() => {
+        if (mtimeOf(entry) === seen)
+            return;
+        seen = mtimeOf(entry);
+        schedule();
+    }, 250);
+    io.out(`honey: watching ${dir}\n`);
+    generate();
+    return new Promise((settle) => signal?.addEventListener("abort", () => {
+        watcher.close();
+        clearInterval(poll);
+        clearTimeout(timer);
+        void latest.then(() => settle(0));
+    }, { once: true }));
+}
+/** Runs `honey <argv>`: the exit code it ends with (a watch ends only by `options.signal`). */
+export async function main(argv, io, options = {}) {
+    const [cwd, env] = [options.cwd ?? process.cwd(), options.env ?? process.env];
+    try {
+        if (argv[0] === "-h" || argv[0] === "--help") {
+            io.out(`${USAGE}\n`);
+            return 0;
+        }
+        if (argv[0] === "init") {
+            runInit(cwd, parseInitFlags(argv.slice(1)), (line) => io.out(`${line}\n`));
+            return 0;
+        }
+        if (argv[0] !== "generate")
+            throw new UsageError(argv[0] === undefined ? "missing command" : `unknown command: ${argv[0]}`);
+        const flags = parseGenerateArgs(argv.slice(1));
+        if (flags.help === true) {
+            io.out(`${USAGE}\n`);
+            return 0;
+        }
+        const load = await createModuleLoader({ fresh: true, from: resolve(cwd, "index.ts") });
+        const config = await configOf(cwd, flags, env, load);
+        if (flags.watch === true) {
+            if (env.HONEY_WATCH_CHILD === "1")
+                throw new UsageError("--watch is not allowed in a generation child");
+            return await watchApp(config, argv.slice(1), io, { cwd, signal: options.signal });
+        }
+        await generateAndWrite(config, cwd, { load, report: (message) => io.err(`honey: ${message}\n`) });
+        io.out("honey: generated\n");
+        return 0;
+    }
+    catch (error) {
+        /* reported on the CLI's stderr, and the exit code says it failed */
+        io.err(error instanceof UsageError
+            ? `honey: ${error.message}\n\n${USAGE}\n`
+            : `honey: generation failed: ${error.message}\n${framesOf(error)}`);
+        return 1;
+    }
+}
+/** The stack frames of `error`, a line each after the message, so a failure names where it was thrown. */
+function framesOf(error) {
+    /* only frame lines survive: a missing stack's "undefined" and the stack's own message line are dropped */
+    return String(error.stack)
+        .split("\n")
+        .filter((line) => /^\s+at /.test(line))
+        .map((line) => `${line}\n`)
+        .join("");
+}

package/dist/build/config.d.ts

@@ -0,0 +1,102 @@
+import type { OpenApiRouteInfo } from "../openapi/generate.ts";
+import type { InvalidateCheckConfig } from "../routing/invalidate-check.ts";
+import type { OpenApiSanitizeOptions } from "../schema/sanitize-spec.ts";
+/** One OpenAPI document a generation writes. */
+export type HoneyOpenApiOutputConfig = {
+    readonly description?: string;
+    /** leave out every route this answers false for */
+    readonly filterRoutes?: (route: OpenApiRouteInfo) => boolean;
+    /** default `src/_gen/openapi.gen.json` */
+    readonly path?: string;
+    /** the metaSpec profile this document carries */
+    readonly profile?: string;
+    /** what the published document leaves out */
+    readonly sanitize?: OpenApiSanitizeOptions;
+    readonly securitySchemes?: Readonly<Record<string, unknown>>;
+    readonly title: string;
+    readonly version: string;
+};
+/** The MCP handler an app mounts with `mcp(app, path, mcpHandler)` from @lovrozagar/honey/mcp. */
+export type HoneyMcpOutputConfig = {
+    /** leave out every route this answers false for; a tool is a route whose meta has `mcp: true` */
+    readonly filterRoutes?: (route: OpenApiRouteInfo) => boolean;
+    /** the server's name; by default the first OpenAPI output's title's */
+    readonly name?: string;
+    /** default `src/_gen/mcp.gen.ts`; its runtime and SDK go in the directory its stem names beside it */
+    readonly path?: string;
+    /** the schemes the routes' `security` names; by default the OpenAPI outputs' */
+    readonly securitySchemes?: Readonly<Record<string, unknown>>;
+};
+export type HoneyCodegenConfig = {
+    /** mutations that declare no `invalidate`, reported once per generation; default `"warn"` */
+    readonly invalidate?: InvalidateCheckConfig;
+    /** the route manifest; `true` is `src/_gen/manifest.gen.json` */
+    readonly manifest?: boolean | string;
+    /** the MCP handler the app mounts; `true` is `src/_gen/mcp.gen.ts` */
+    readonly mcp?: boolean | string | HoneyMcpOutputConfig;
+    /** a gateway's route tree source: a module exporting its services' merged tree */
+    readonly mergeTree?: string;
+    /** one document, or several from the same routes */
+    readonly openApi?: HoneyOpenApiOutputConfig | readonly HoneyOpenApiOutputConfig[];
+    /** the route tree module; on by default at `src/_gen/routes.gen.ts` */
+    readonly tree?: boolean | string;
+    /** the app's types; `true` is `src/_gen/types.gen.d.ts` */
+    readonly types?: boolean | string | {
+        readonly baseCtxName?: string;
+        readonly path?: string;
+    };
+};
+export type HoneyVitePluginConfig = {
+    /** the module exporting the app (`app`, else the default export) */
+    readonly app?: string;
+    readonly codegen?: HoneyCodegenConfig;
+    /** globs, from the project root, whose edits regenerate in dev */
+    readonly watch?: readonly string[];
+};
+export type ResolvedOpenApiOutput = Omit<HoneyOpenApiOutputConfig, "path"> & {
+    readonly path: string;
+};
+export type ResolvedMcpOutput = Omit<HoneyMcpOutputConfig, "path"> & {
+    readonly path: string;
+    /** the companion directory's name, the path's stem */
+    readonly dir: string;
+};
+export type ResolvedHoneyConfig = {
+    readonly app: string | undefined;
+    readonly codegen: {
+        readonly invalidate: InvalidateCheckConfig | undefined;
+        readonly manifest: false | string;
+        readonly mcp: false | ResolvedMcpOutput;
+        readonly mergeTree: string | undefined;
+        readonly openApi: readonly ResolvedOpenApiOutput[];
+        readonly tree: false | string;
+        readonly types: false | {
+            readonly baseCtxName: string | undefined;
+            readonly path: string;
+        };
+    };
+    readonly watch: readonly string[];
+};
+/**
+ * The files honey-clients's generateMcpHandler writes in the companion directory: its portable runtime and the API's
+ * TS SDK (plugin.test holds a generation to exactly these).
+ */
+export declare const MCP_COMPANIONS: readonly ["api.client.gen.ts", "api.index.gen.ts", "api.map.gen.ts", "api.runtime.gen.ts", "api.types.gen.ts", "runtime.gen.ts"];
+/** `raw` with its defaults; a key honey-clients owns is an error naming where it went. */
+export declare function resolveHoneyConfig(raw: HoneyVitePluginConfig): ResolvedHoneyConfig;
+/** Where an OpenAPI output configured at `path` goes: a `.yaml`/`.yml` path is YAML alone, else JSON plus `.yaml`. */
+export declare function openApiOutputPaths(path: string): {
+    json: string | null;
+    yaml: string;
+};
+/** The MCP output's files, from the project root: its entry, then each companion. */
+export declare const mcpPaths: (mcp: false | ResolvedMcpOutput) => string[];
+/** Every file a generation writes, absolute, and the directories it creates them in. */
+export declare function generatedOutputs(config: ResolvedHoneyConfig, root: string): {
+    dirs: string[];
+    files: string[];
+};
+/** Whether `file` is one a generation writes (its atomic write's temp file is WATCH_IGNORE_RE's `.tmp`). */
+export declare const isGeneratedOutput: (file: string, outputs: {
+    files: readonly string[];
+}) => boolean;

package/dist/build/config.js

@@ -0,0 +1,89 @@
+/**
+ * The `honey()` plugin's config (bit 19 h2): what it takes, resolved with its defaults (the route tree on, every
+ * other artifact off), and every path a generation writes, which a watcher must never take for an edit. An OpenAPI
+ * output path ending `.yaml` or `.yml` is that YAML file alone; any other is JSON there plus its `.yaml` sibling
+ * (Q7: core's openapi/yaml.ts writes it). The SDKs, the CLI and the MCP server package are honey-clients's (Q1), so
+ * their keys are refused. Bit 21 e: `mcp` writes the handler an app mounts (`_gen/mcp.gen.ts`, its runtime and SDK in
+ * the companion directory named by its stem, `_gen/mcp/`), H24.3.
+ */
+import { dirname, join, resolve } from "node:path";
+const TYPES = "src/_gen/types.gen.d.ts";
+const MCP = "src/_gen/mcp.gen.ts";
+/**
+ * The files honey-clients's generateMcpHandler writes in the companion directory: its portable runtime and the API's
+ * TS SDK (plugin.test holds a generation to exactly these).
+ */
+export const MCP_COMPANIONS = [
+    "api.client.gen.ts",
+    "api.index.gen.ts",
+    "api.map.gen.ts",
+    "api.runtime.gen.ts",
+    "api.types.gen.ts",
+    "runtime.gen.ts",
+];
+/** `value` as the MCP output: off, or its path (a `.ts` module) and companion directory with its options. */
+function mcpOf(value) {
+    if (value === undefined || value === false)
+        return false;
+    const options = typeof value === "object" ? value : { path: typeof value === "string" ? value : undefined };
+    const path = options.path ?? MCP;
+    const dir = /([^/\\]+?)(?:\.gen)?\.ts$/.exec(path)?.[1];
+    if (dir === undefined)
+        throw new Error(`codegen.mcp: ${JSON.stringify(path)} is no .ts module`);
+    return { ...options, dir, path };
+}
+/** `value` as a path: `true` (or nothing, when on by default) is `fallback`, `false` is off. */
+function pathOf(value, fallback, on) {
+    if (typeof value === "string")
+        return value;
+    return value === true || (value === undefined && on) ? fallback : false;
+}
+/** `raw` with its defaults; a key honey-clients owns is an error naming where it went. */
+export function resolveHoneyConfig(raw) {
+    const c = raw.codegen ?? {};
+    for (const key of ["sdk", "cli"])
+        if (Object.hasOwn(c, key))
+            throw new Error(`codegen.${key}: the SDKs, the CLI and MCP are honey-clients's: honey-clients generate --app`);
+    const types = typeof c.types === "object" ? c.types : { path: pathOf(c.types, TYPES, false) || undefined };
+    const outputs = c.openApi === undefined ? [] : Array.isArray(c.openApi) ? c.openApi : [c.openApi];
+    return {
+        app: raw.app,
+        codegen: {
+            invalidate: c.invalidate,
+            manifest: pathOf(c.manifest, "src/_gen/manifest.gen.json", false),
+            mcp: mcpOf(c.mcp),
+            mergeTree: c.mergeTree,
+            openApi: outputs.map((entry) => ({
+                ...entry,
+                path: entry.path ?? "src/_gen/openapi.gen.json",
+            })),
+            tree: pathOf(c.tree, "src/_gen/routes.gen.ts", true),
+            types: c.types === undefined || c.types === false
+                ? false
+                : { baseCtxName: "baseCtxName" in types ? types.baseCtxName : undefined, path: types.path ?? TYPES },
+        },
+        watch: raw.watch ?? [],
+    };
+}
+/** Where an OpenAPI output configured at `path` goes: a `.yaml`/`.yml` path is YAML alone, else JSON plus `.yaml`. */
+export function openApiOutputPaths(path) {
+    if (/\.ya?ml$/.test(path))
+        return { json: null, yaml: path };
+    return { json: path, yaml: path.endsWith(".json") ? `${path.slice(0, -5)}.yaml` : `${path}.yaml` };
+}
+/** The MCP output's files, from the project root: its entry, then each companion. */
+export const mcpPaths = (mcp) => mcp === false ? [] : [mcp.path, ...MCP_COMPANIONS.map((name) => join(dirname(mcp.path), mcp.dir, name))];
+/** Every file a generation writes, absolute, and the directories it creates them in. */
+export function generatedOutputs(config, root) {
+    const { manifest, mcp, openApi, tree, types } = config.codegen;
+    const files = [tree, types === false ? false : types.path, manifest, ...mcpPaths(mcp)]
+        .filter((path) => path !== false)
+        .map((path) => resolve(root, path));
+    for (const entry of openApi) {
+        const { json, yaml } = openApiOutputPaths(resolve(root, entry.path));
+        files.push(...(json === null ? [] : [json]), yaml);
+    }
+    return { dirs: [...new Set(files.map((file) => dirname(file)))], files };
+}
+/** Whether `file` is one a generation writes (its atomic write's temp file is WATCH_IGNORE_RE's `.tmp`). */
+export const isGeneratedOutput = (file, outputs) => outputs.files.includes(resolve(file));

package/dist/build/generate.d.ts

@@ -0,0 +1,19 @@
+import type * as Artifacts from "./artifacts.ts";
+import { type Clients, type Report } from "./artifacts.ts";
+import type { ResolvedHoneyConfig } from "./config.ts";
+import { type ModuleLoader } from "./loaders.ts";
+export type { Report } from "./artifacts.ts";
+/** honey-clients, or a named error when it is not installed. */
+export declare function loadClients(load?: () => Promise<typeof import("@lovrozagar/honey-clients")>): Promise<Clients>;
+/**
+ * artifacts.ts as the app at `root` resolves @lovrozagar/honey (node_modules up from it), at the path it has in this
+ * package, so it shares the app's core even when the plugin was loaded from another copy; else this package's own.
+ */
+export declare function artifactsFor(root: string, own?: string): string;
+/** artifacts.ts as `load` evaluates it, so the app it imports shares its core; a fresh loader from `root` by default. */
+export declare function inAppGraph(root: string, load?: ModuleLoader): Promise<typeof Artifacts>;
+/** Every artifact `config` asks for, written under `root`; the files it rewrote. */
+export declare function generateAndWrite(config: ResolvedHoneyConfig, root: string, options?: {
+    load?: ModuleLoader;
+    report?: Report;
+}): Promise<string[]>;