@toolfactory.dev/core 1.0.0-rc

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Annette Pohl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# core2ai
+
+> Shared runtime, code generation infrastructure, and documentation for the api2ai ecosystem.
+
+## Ecosystem
+
+| Repository                                            | Purpose                                                |
+| ----------------------------------------------------- | ------------------------------------------------------ |
+| [core2ai](https://github.com/annettedorothea/core2ai) | Shared runtime, architecture, and documentation        |
+| [api2ai](https://github.com/annettedorothea/api2ai)   | Generate curated MCP tools from OpenAPI specifications |
+| [db2ai](https://github.com/annettedorothea/db2ai)     | Generate curated MCP tools from relational databases   |
+
+`core2ai` provides the common foundation used by the other projects in the ecosystem.
+
+It contains the shared infrastructure for:
+
+- code generation
+- validation
+- MCP host generation
+- authentication bootstrap
+- runtime components
+- architecture and documentation
+
+If you want to generate MCP tools, you will usually start with one of the sibling projects instead.
+
+---
+
+## Documentation
+
+The shared documentation for the ecosystem lives in this repository.
+
+Topics include:
+
+- Architecture
+- Tool Factory
+- Tool Authoring
+- AI Runtime
+- Personas
+- Authentication
+- Integrations
+- Development Guides
+
+Start here:
+
+- [Documentation](docs/README.md)
+
+---
+
+## Related Projects
+
+- [api2ai](https://github.com/annettedorothea/api2ai) — Generate curated MCP tools from OpenAPI specifications.
+- [db2ai](https://github.com/annettedorothea/db2ai) — Generate curated MCP tools from relational databases.
+
+---
+
+## Development
+
+`core2ai` is currently consumed as a local dependency by `api2ai` and `db2ai` and is not published to npm.
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Whenever you make changes, rebuild the package so the dependent repositories can pick up the latest version:
+
+```bash
+npm run build
+```
+
+Although a watch mode exists, rebuilding after changes is currently the recommended workflow.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Questions, ideas, bug reports, and feature requests are always welcome through GitHub Discussions or Issues.
+
+---
+
+> _Whatever you do, work heartily, as for the Lord and not for men._
+>
+> **— Colossians 3:23**
+>
+> _Created by Annette Pohl_

package/out/codegen/access-stubs.d.ts

@@ -0,0 +1,2 @@
+export declare function authorizeExportName(toolName: string): string;
+export declare function prepareInputExportName(toolName: string): string;

package/out/codegen/access-stubs.js

@@ -0,0 +1,6 @@
+export function authorizeExportName(toolName) {
+    return `authorize${toolName.charAt(0).toUpperCase()}${toolName.slice(1)}`;
+}
+export function prepareInputExportName(toolName) {
+    return `prepare${toolName.charAt(0).toUpperCase()}${toolName.slice(1)}Input`;
+}

package/out/codegen/auth-module-names.d.ts

@@ -0,0 +1,11 @@
+export type ModuleCredentialNames = {
+    pascalBase: string;
+    className: string;
+    toFunctionName: string;
+    verifyFunctionName: string;
+    fileBase: string;
+};
+/** Derive per-module credential type/file names from `generated/{product}/tools/<module>-tools.ts`. */
+export declare function resolveModuleCredentialNames(toolsModuleTsPath: string): ModuleCredentialNames;
+export declare function resolveVerifyCredentialsStubFileName(toolsModuleTsPath: string): string;
+export declare function resolveVerifyCredentialsStubPath(projectRoot: string, toolsModuleTsPath: string): string;

package/out/codegen/auth-module-names.js

@@ -0,0 +1,34 @@
+import * as path from 'node:path';
+import { resolveHostProductFromGeneratedToolsPath } from './generated-layout.js';
+function kebabSegmentToPascal(segment) {
+    if (segment.length === 0) {
+        return '';
+    }
+    return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+function kebabToPascal(kebab) {
+    return kebab.split('-').map(kebabSegmentToPascal).join('');
+}
+/** Derive per-module credential type/file names from `generated/{product}/tools/<module>-tools.ts`. */
+export function resolveModuleCredentialNames(toolsModuleTsPath) {
+    let base = path.parse(toolsModuleTsPath).name;
+    if (base.endsWith('-tools')) {
+        base = base.slice(0, -'-tools'.length);
+    }
+    const pascalBase = kebabToPascal(base);
+    return {
+        pascalBase,
+        className: `${pascalBase}Credentials`,
+        toFunctionName: `to${pascalBase}Credentials`,
+        verifyFunctionName: `verify${pascalBase}Credentials`,
+        fileBase: `verify${pascalBase}Credentials`
+    };
+}
+export function resolveVerifyCredentialsStubFileName(toolsModuleTsPath) {
+    return `${resolveModuleCredentialNames(toolsModuleTsPath).fileBase}.ts`;
+}
+export function resolveVerifyCredentialsStubPath(projectRoot, toolsModuleTsPath) {
+    const hostProduct = resolveHostProductFromGeneratedToolsPath(toolsModuleTsPath);
+    const mcpModuleName = path.parse(toolsModuleTsPath).name;
+    return path.join(projectRoot, 'src', 'auth', hostProduct, mcpModuleName, resolveVerifyCredentialsStubFileName(toolsModuleTsPath));
+}

package/out/codegen/auth-pipeline-render.d.ts

@@ -0,0 +1,10 @@
+export type AuthPipelineTier = 'none' | 'credential' | 'full';
+export type HookStubMaps = {
+    authorizers: boolean;
+    preparers: boolean;
+};
+/** @deprecated Use HookStubMaps */
+export type AuthStubMaps = HookStubMaps;
+export type AuthPipelineProfile = 'api2ai' | 'db2ai';
+export declare function resolveAuthPipelineTier(hasAuthPipeline: boolean, authorizeToolNames: readonly string[], prepareToolNames: readonly string[]): AuthPipelineTier;
+export declare function renderInvokeAuthPipeline(profile: AuthPipelineProfile, tier: AuthPipelineTier, hasVerifyCredential: boolean, stubMaps: HookStubMaps): string;

package/out/codegen/auth-pipeline-render.js

@@ -0,0 +1,157 @@
+const MISSING_CREDENTIAL_ERROR = `
+            throw new Error(
+                'Missing host credential. stdio: set env for --auth-env on stdio-mcp-server; passthrough HTTP: MCP auth header (e.g. x-api-token); OAuth HTTP: complete MCP login (Authorization Bearer from Cursor).'
+            );`;
+function renderUrlAndHeadersPreamble() {
+    return `
+    const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    const pathParams = { ...(optionsResolved.pathParams ?? {}) };
+    let resolvedPath = tool.path;
+    for (const [key, value] of Object.entries(pathParams)) {
+        resolvedPath = resolvedPath.split('{' + key + '}').join(encodeURIComponent(String(value)));
+    }
+
+    const url = new URL(normalizedBaseUrl + resolvedPath);
+    appendSerializedQueryParams(url.searchParams, tool.toolName, optionsResolved.query);
+    const requestHeaders: Record<string, string> = {
+        'content-type': 'application/json',
+        ...(optionsResolved.headers ?? {})
+    };`;
+}
+function renderInvokeCredentialPipeline(profile, hasVerifyCredential) {
+    if (profile === 'api2ai') {
+        const verifyBlock = hasVerifyCredential
+            ? `
+        if (upstreamCredential === undefined) {
+            const verified = await verifyCredential({ inboundCredential: String(inbound).trim() });
+            upstreamCredential = verified.upstreamCredential;
+        }`
+            : '';
+        return `
+    let upstreamCredential = host.upstreamCredential;
+    let authCredential = host.credential;
+
+    if (tool.access === 'protected') {
+        const inbound = host.credential;
+        if (!inbound || !String(inbound).trim()) {${MISSING_CREDENTIAL_ERROR}
+        }${verifyBlock}
+        authCredential = upstreamCredential ?? String(inbound).trim();
+    }${renderUrlAndHeadersPreamble()}`;
+    }
+    const verifyBlock = hasVerifyCredential
+        ? `
+        await verifyCredential({ inboundCredential: String(inbound).trim() });`
+        : '';
+    return `
+    if (toolMeta.access === 'protected') {
+        const inbound = host.credential;
+        if (!inbound || !String(inbound).trim()) {${MISSING_CREDENTIAL_ERROR}
+        }${verifyBlock}
+    }`;
+}
+export function resolveAuthPipelineTier(hasAuthPipeline, authorizeToolNames, prepareToolNames) {
+    if (!hasAuthPipeline) {
+        return 'none';
+    }
+    if (authorizeToolNames.length > 0 || prepareToolNames.length > 0) {
+        return 'full';
+    }
+    return 'credential';
+}
+export function renderInvokeAuthPipeline(profile, tier, hasVerifyCredential, stubMaps) {
+    if (tier === 'credential') {
+        return renderInvokeCredentialPipeline(profile, hasVerifyCredential);
+    }
+    if (tier !== 'full') {
+        throw new Error('renderInvokeAuthPipeline: tier must be credential or full');
+    }
+    const toolRef = profile === 'api2ai' ? 'tool' : 'toolMeta';
+    const verifyBlock = profile === 'api2ai'
+        ? hasVerifyCredential
+            ? `
+        if (credentialsForStubs === undefined || upstreamCredential === undefined) {
+            const verified = await verifyCredential({ inboundCredential: String(inbound).trim() });
+            upstreamCredential = verified.upstreamCredential;
+            credentialsForStubs = verified.credentials;
+        }`
+            : ''
+        : hasVerifyCredential
+            ? `
+        if (credentialsForStubs === undefined) {
+            const verified = await verifyCredential({ inboundCredential: String(inbound).trim() });
+            credentialsForStubs = verified.credentials;
+        }`
+            : '';
+    const authorizeBlock = stubMaps.authorizers
+        ? `
+        if (${toolRef}.hasAuthorize) {
+            const authorize = authorizers[toolName];
+            if (typeof authorize !== 'function') {
+                throw new Error('No authorizer for tool: ' + toolName);
+            }
+            await Promise.resolve(authorize(credentialsForStubs!));
+        }`
+        : '';
+    const needsCredentials = hasVerifyCredential || stubMaps.authorizers;
+    const prepareBlock = stubMaps.preparers
+        ? needsCredentials
+            ? `
+    if (${toolRef}.hasPrepare) {
+        const prepare = preparers[toolName];
+        if (typeof prepare !== 'function') {
+            throw new Error('No preparer for tool: ' + toolName);
+        }
+        if (${toolRef}.access === 'protected') {
+            if (credentialsForStubs === undefined) {
+                throw new Error('Prepare requires credentials; verify credential or pass host.credentials.');
+            }
+            optionsResolved = await Promise.resolve(prepare(optionsResolved, credentialsForStubs));
+        } else {
+            optionsResolved = await Promise.resolve(prepare(optionsResolved));
+        }
+    }`
+            : `
+    if (${toolRef}.hasPrepare) {
+        const prepare = preparers[toolName];
+        if (typeof prepare !== 'function') {
+            throw new Error('No preparer for tool: ' + toolName);
+        }
+        optionsResolved = await Promise.resolve(prepare(optionsResolved));
+    }`
+        : '';
+    const api2aiCredentialsPreamble = needsCredentials
+        ? `
+    let upstreamCredential = host.upstreamCredential;
+    const credentialsPlain = host.credentials;
+    let credentialsForStubs: ModuleCredentials | undefined =
+        credentialsPlain != null
+            ? toModuleCredentials(credentialsPlain as Record<string, unknown>)
+            : undefined;
+    let authCredential = host.credential;
+
+    if (tool.access === 'protected') {
+        const inbound = host.credential;
+        if (!inbound || !String(inbound).trim()) {${MISSING_CREDENTIAL_ERROR}
+        }${verifyBlock}
+        authCredential = upstreamCredential ?? String(inbound).trim();${authorizeBlock}
+    }${prepareBlock}${renderUrlAndHeadersPreamble()}`
+        : `
+${prepareBlock}${renderUrlAndHeadersPreamble()}`;
+    const db2aiCredentialsPreamble = needsCredentials
+        ? `
+    const credentialsPlain = host.credentials;
+    let credentialsForStubs: ModuleCredentials | undefined =
+        credentialsPlain != null
+            ? toModuleCredentials(credentialsPlain as Record<string, unknown>)
+            : undefined;
+
+    if (toolMeta.access === 'protected') {
+        const inbound = host.credential;
+        if (!inbound || !String(inbound).trim()) {${MISSING_CREDENTIAL_ERROR}
+        }${verifyBlock}${authorizeBlock}
+    }${prepareBlock}`
+        : `
+${prepareBlock}`;
+    const api2aiPreamble = profile === 'api2ai' ? api2aiCredentialsPreamble : db2aiCredentialsPreamble;
+    return api2aiPreamble;
+}

package/out/codegen/auth-stub-bootstrap.d.ts

@@ -0,0 +1,42 @@
+export type ToolHookStubSpec = {
+    toolName: string;
+    authorize: boolean;
+    prepare: boolean;
+    access: 'public' | 'protected';
+};
+/** @deprecated Use ToolHookStubSpec */
+export type ToolAuthStubSpec = ToolHookStubSpec;
+/** Basename of `generated/{product}/tools/<name>-tools.ts` — matches exported `mcpServerName`. */
+export declare function resolveMcpModuleNameFromToolsModule(toolsModuleTsPath: string): string;
+export declare function resolveHookStubDir(projectRoot: string, toolsModuleTsPath: string): string;
+/** @deprecated Use resolveHookStubDir */
+export declare const resolveAuthStubDir: typeof resolveHookStubDir;
+export declare function renderToolHookStubFileContent(toolName: string, spec: ToolHookStubSpec, hookStubTsPath: string, toolsModuleTsPath: string): string;
+/** @deprecated Use renderToolHookStubFileContent */
+export declare const renderToolAuthStubFileContent: typeof renderToolHookStubFileContent;
+export declare function ensureToolHookStubsAtProjectRoot(projectRoot: string, toolSpecs: readonly ToolHookStubSpec[], toolsModuleTsPath: string): Promise<Map<string, string>>;
+/** @deprecated Use ensureToolHookStubsAtProjectRoot */
+export declare const ensureToolAuthStubsAtProjectRoot: typeof ensureToolHookStubsAtProjectRoot;
+export declare function ensureToolHookStubsFromSource(source: string, toolSpecs: readonly ToolHookStubSpec[], toolsModuleTsPath: string): Promise<Map<string, string>>;
+/** @deprecated Use ensureToolHookStubsFromSource */
+export declare const ensureToolAuthStubsFromSource: typeof ensureToolHookStubsFromSource;
+export declare function renderVerifyCredentialsStubFileContent(toolsModuleTsPath: string): string;
+export declare function resolveVerifyCredentialStubPath(projectRoot: string, toolsModuleTsPath: string): string;
+/** Write-once \`src/hooks/{product}/<module>/verify*Credentials.ts\` when DSL has auth. */
+export declare function ensureVerifyCredentialStubAtProjectRoot(projectRoot: string, toolsModuleTsPath: string): Promise<string | undefined>;
+export declare function ensureVerifyCredentialStubFromSource(source: string, toolsModuleTsPath: string): Promise<string | undefined>;
+export declare function renderVerifyCredentialReExport(toolsModuleTsPath: string, verifyStubTsPath: string): string;
+export declare function renderVerifyCredentialImport(toolsModuleTsPath: string, verifyStubTsPath: string, options?: {
+    includeVerify?: boolean;
+    includeModuleCredentials?: boolean;
+}): string;
+export declare function renderAuthorizersMap(toolNames: readonly string[]): string;
+export declare function renderPreparersMap(toolNames: readonly string[], options?: {
+    includeCredentials?: boolean;
+}): string;
+/** @deprecated Use renderPreparersMap */
+export declare const renderValidatorsMap: typeof renderPreparersMap;
+export declare function renderAuthorizerImports(tsPath: string, stubPaths: Map<string, string>, authorizeToolNames: readonly string[]): string;
+export declare function renderPreparerImports(tsPath: string, stubPaths: Map<string, string>): string;
+/** @deprecated Use renderPreparerImports */
+export declare const renderValidatorImports: typeof renderPreparerImports;

package/out/codegen/auth-stub-bootstrap.js

@@ -0,0 +1,252 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveModuleCredentialNames } from './auth-module-names.js';
+import { authorizeExportName, prepareInputExportName } from './access-stubs.js';
+import { relativeJsImportPath, resolveHostProductFromGeneratedToolsPath } from './generated-layout.js';
+import { resolveBootstrapProjectRootFromSource } from './project-bootstrap.js';
+/** Basename of `generated/{product}/tools/<name>-tools.ts` — matches exported `mcpServerName`. */
+export function resolveMcpModuleNameFromToolsModule(toolsModuleTsPath) {
+    return path.parse(toolsModuleTsPath).name;
+}
+export function resolveHookStubDir(projectRoot, toolsModuleTsPath) {
+    const hostProduct = resolveHostProductFromGeneratedToolsPath(toolsModuleTsPath);
+    const mcpModuleName = resolveMcpModuleNameFromToolsModule(toolsModuleTsPath);
+    return path.join(projectRoot, 'src', 'hooks', hostProduct, mcpModuleName);
+}
+/** @deprecated Use resolveHookStubDir */
+export const resolveAuthStubDir = resolveHookStubDir;
+function hookStubRelativePath(toolsModuleTsPath, fileBase) {
+    const hostProduct = resolveHostProductFromGeneratedToolsPath(toolsModuleTsPath);
+    const mcpModuleName = resolveMcpModuleNameFromToolsModule(toolsModuleTsPath);
+    return `src/hooks/${hostProduct}/${mcpModuleName}/${fileBase}.ts`;
+}
+function resolveVerifyStubRelPath(toolsModuleTsPath) {
+    const names = resolveModuleCredentialNames(toolsModuleTsPath);
+    return hookStubRelativePath(toolsModuleTsPath, names.fileBase);
+}
+function renderToolHookStubBody(toolName, spec, toolsModuleTsPath) {
+    const lines = [];
+    if (spec.authorize) {
+        const fn = authorizeExportName(toolName);
+        lines.push(`export function ${fn}(credentials: ModuleCredentials): void {
+    void credentials;
+}`);
+    }
+    if (spec.prepare) {
+        const fn = prepareInputExportName(toolName);
+        if (spec.access === 'public') {
+            lines.push(`export function ${fn}(options: InvokeOptions): InvokeOptions {
+    void options;
+    throw new Error('Implement ${fn} in ${hookStubRelativePath(toolsModuleTsPath, toolName)}');
+}`);
+        }
+        else {
+            lines.push(`export function ${fn}(options: InvokeOptions, credentials?: ModuleCredentials): InvokeOptions {
+    void options;
+    void credentials;
+    throw new Error('Implement ${fn} in ${hookStubRelativePath(toolsModuleTsPath, toolName)}');
+}`);
+        }
+    }
+    return lines.join('\n\n');
+}
+export function renderToolHookStubFileContent(toolName, spec, hookStubTsPath, toolsModuleTsPath) {
+    const importSpec = relativeJsImportPath(hookStubTsPath, toolsModuleTsPath);
+    const hookDir = path.dirname(hookStubTsPath);
+    const verifyStubPath = path.join(hookDir, `${resolveModuleCredentialNames(toolsModuleTsPath).fileBase}.ts`);
+    const verifyImportSpec = relativeJsImportPath(hookStubTsPath, verifyStubPath);
+    const header = spec.authorize && spec.prepare
+        ? `/**
+ * Authorize + prepare hooks for "${toolName}" (write-once — implement authorize / prepareInput).
+ */`
+        : spec.authorize
+            ? `/**
+ * Authorize hook for "${toolName}" (write-once — override ${authorizeExportName(toolName)} for role gates).
+ */`
+            : `/**
+ * Prepare hook for "${toolName}" (write-once — implement ${prepareInputExportName(toolName)}).
+ */`;
+    const needsModuleCredentials = spec.authorize || (spec.prepare && spec.access === 'protected');
+    const credentialsImport = needsModuleCredentials
+        ? `import type { ModuleCredentials } from '${verifyImportSpec}';\n`
+        : '';
+    return `${header}
+${credentialsImport}import type { InvokeOptions } from '${importSpec}';
+
+${renderToolHookStubBody(toolName, spec, toolsModuleTsPath)}
+`;
+}
+/** @deprecated Use renderToolHookStubFileContent */
+export const renderToolAuthStubFileContent = renderToolHookStubFileContent;
+export async function ensureToolHookStubsAtProjectRoot(projectRoot, toolSpecs, toolsModuleTsPath) {
+    const hookDir = resolveHookStubDir(projectRoot, toolsModuleTsPath);
+    if (!fs.existsSync(hookDir)) {
+        fs.mkdirSync(hookDir, { recursive: true });
+    }
+    const importPaths = new Map();
+    for (const spec of toolSpecs) {
+        if (!spec.authorize && !spec.prepare) {
+            continue;
+        }
+        const tsPath = path.join(hookDir, `${spec.toolName}.ts`);
+        if (!fs.existsSync(tsPath)) {
+            fs.writeFileSync(tsPath, renderToolHookStubFileContent(spec.toolName, spec, tsPath, toolsModuleTsPath), 'utf-8');
+        }
+        importPaths.set(spec.toolName, tsPath);
+    }
+    return importPaths;
+}
+/** @deprecated Use ensureToolHookStubsAtProjectRoot */
+export const ensureToolAuthStubsAtProjectRoot = ensureToolHookStubsAtProjectRoot;
+export async function ensureToolHookStubsFromSource(source, toolSpecs, toolsModuleTsPath) {
+    const projectRoot = resolveBootstrapProjectRootFromSource(source);
+    return ensureToolHookStubsAtProjectRoot(projectRoot, toolSpecs, toolsModuleTsPath);
+}
+/** @deprecated Use ensureToolHookStubsFromSource */
+export const ensureToolAuthStubsFromSource = ensureToolHookStubsFromSource;
+export function renderVerifyCredentialsStubFileContent(toolsModuleTsPath) {
+    const names = resolveModuleCredentialNames(toolsModuleTsPath);
+    const verifyPath = resolveVerifyStubRelPath(toolsModuleTsPath);
+    return `/**
+ * MCP credential verification (write-once — implement ${names.verifyFunctionName}).
+ * Used by oauth-http gate and by invokeTool for protected tools (stdio/relay/OAuth).
+ */
+export type ModuleCredentials = Record<string, unknown>;
+
+export class ${names.className} implements ModuleCredentials {
+    [key: string]: unknown;
+
+    constructor(init: ModuleCredentials) {
+        Object.assign(this, init);
+    }
+
+    toString(): string {
+        return '[${names.pascalBase} credentials]';
+    }
+}
+
+export function ${names.toFunctionName}(data: ModuleCredentials | Record<string, unknown>): ${names.className} {
+    return new ${names.className}(data as ModuleCredentials);
+}
+
+export type VerifyCredentialInput = {
+    inboundCredential: string;
+};
+
+export type VerifyCredentialResult = {
+    upstreamCredential: string;
+    credentials: ${names.className};
+};
+
+export async function ${names.verifyFunctionName}(input: VerifyCredentialInput): Promise<VerifyCredentialResult> {
+    void input;
+    throw new Error('Implement ${names.verifyFunctionName} in ${verifyPath}');
+}
+
+export { ${names.verifyFunctionName} as verifyCredential, ${names.toFunctionName} as toModuleCredentials };
+`;
+}
+export function resolveVerifyCredentialStubPath(projectRoot, toolsModuleTsPath) {
+    const hookDir = resolveHookStubDir(projectRoot, toolsModuleTsPath);
+    const names = resolveModuleCredentialNames(toolsModuleTsPath);
+    return path.join(hookDir, `${names.fileBase}.ts`);
+}
+/** Write-once \`src/hooks/{product}/<module>/verify*Credentials.ts\` when DSL has auth. */
+export async function ensureVerifyCredentialStubAtProjectRoot(projectRoot, toolsModuleTsPath) {
+    const hookDir = resolveHookStubDir(projectRoot, toolsModuleTsPath);
+    if (!fs.existsSync(hookDir)) {
+        fs.mkdirSync(hookDir, { recursive: true });
+    }
+    const tsPath = resolveVerifyCredentialStubPath(projectRoot, toolsModuleTsPath);
+    if (!fs.existsSync(tsPath)) {
+        fs.writeFileSync(tsPath, renderVerifyCredentialsStubFileContent(toolsModuleTsPath), 'utf-8');
+    }
+    return tsPath;
+}
+export async function ensureVerifyCredentialStubFromSource(source, toolsModuleTsPath) {
+    const projectRoot = resolveBootstrapProjectRootFromSource(source);
+    return ensureVerifyCredentialStubAtProjectRoot(projectRoot, toolsModuleTsPath);
+}
+export function renderVerifyCredentialReExport(toolsModuleTsPath, verifyStubTsPath) {
+    const rel = relativeJsImportPath(toolsModuleTsPath, verifyStubTsPath);
+    const names = resolveModuleCredentialNames(toolsModuleTsPath);
+    return `export {
+    verifyCredential,
+    toModuleCredentials
+} from '${rel}';
+export type {
+    VerifyCredentialInput,
+    VerifyCredentialResult,
+    ModuleCredentials,
+    ${names.className}
+} from '${rel}';`;
+}
+export function renderVerifyCredentialImport(toolsModuleTsPath, verifyStubTsPath, options) {
+    const rel = relativeJsImportPath(toolsModuleTsPath, verifyStubTsPath);
+    const includeVerify = options?.includeVerify !== false;
+    const includeModuleCredentials = options?.includeModuleCredentials !== false;
+    if (!includeVerify) {
+        return `import { toModuleCredentials, type ModuleCredentials } from '${rel}';`;
+    }
+    if (!includeModuleCredentials) {
+        return `import { verifyCredential } from '${rel}';`;
+    }
+    return `import { verifyCredential, toModuleCredentials, type ModuleCredentials } from '${rel}';`;
+}
+export function renderAuthorizersMap(toolNames) {
+    const typeAnnotation = ': Record<string, (credentials: ModuleCredentials) => void | Promise<void>>';
+    if (toolNames.length === 0) {
+        return `const authorizers${typeAnnotation} = {};`;
+    }
+    const entries = toolNames.map((toolName) => {
+        const fn = authorizeExportName(toolName);
+        return `    ${JSON.stringify(toolName)}: ${fn}`;
+    });
+    return `const authorizers${typeAnnotation} = {\n${entries.join(',\n')}\n};`;
+}
+export function renderPreparersMap(toolNames, options) {
+    const includeCredentials = options?.includeCredentials !== false;
+    const typeAnnotation = includeCredentials
+        ? ': Record<string, (options: InvokeOptions, credentials?: ModuleCredentials) => InvokeOptions | Promise<InvokeOptions>>'
+        : ': Record<string, (options: InvokeOptions) => InvokeOptions | Promise<InvokeOptions>>';
+    if (toolNames.length === 0) {
+        return `const preparers${typeAnnotation} = {};`;
+    }
+    const entries = toolNames.map((toolName) => {
+        const fn = prepareInputExportName(toolName);
+        return `    ${JSON.stringify(toolName)}: ${fn}`;
+    });
+    return `const preparers${typeAnnotation} = {\n${entries.join(',\n')}\n};`;
+}
+/** @deprecated Use renderPreparersMap */
+export const renderValidatorsMap = renderPreparersMap;
+export function renderAuthorizerImports(tsPath, stubPaths, authorizeToolNames) {
+    const allowed = new Set(authorizeToolNames);
+    const lines = [];
+    for (const [toolName, absStub] of stubPaths) {
+        if (!allowed.has(toolName)) {
+            continue;
+        }
+        const rel = relativeJsImportPath(tsPath, absStub);
+        const fn = authorizeExportName(toolName);
+        const stubContent = fs.existsSync(absStub) ? fs.readFileSync(absStub, 'utf-8') : '';
+        if (stubContent.includes(`export function ${fn}`)) {
+            lines.push(`import { ${fn} } from '${rel}';`);
+        }
+    }
+    return lines.join('\n');
+}
+export function renderPreparerImports(tsPath, stubPaths) {
+    const lines = [];
+    for (const [toolName, absStub] of stubPaths) {
+        const rel = relativeJsImportPath(tsPath, absStub);
+        const fn = prepareInputExportName(toolName);
+        const stubContent = fs.existsSync(absStub) ? fs.readFileSync(absStub, 'utf-8') : '';
+        if (stubContent.includes(`export function ${fn}`)) {
+            lines.push(`import { ${fn} } from '${rel}';`);
+        }
+    }
+    return lines.join('\n');
+}
+/** @deprecated Use renderPreparerImports */
+export const renderValidatorImports = renderPreparerImports;

package/out/codegen/document-validation.d.ts

@@ -0,0 +1,22 @@
+import type { CliLangiumDocument, CliLangiumServices } from './langium-cli-types.js';
+export type CliLangiumValidationDiagnostic = {
+    severity?: number;
+    message: string;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+};
+export type AssertDocumentValidOptions = {
+    beforeBuild?: () => void;
+    extraErrors?: (document: CliLangiumDocument) => Promise<CliLangiumValidationDiagnostic[]> | CliLangiumValidationDiagnostic[];
+};
+export declare function collectLangiumDocumentErrors(document: CliLangiumDocument): CliLangiumValidationDiagnostic[];
+export declare function printDocumentValidationErrors(document: CliLangiumDocument, errors: CliLangiumValidationDiagnostic[]): void;
+export declare function assertDocumentValidForGenerate(fileName: string, services: CliLangiumServices, options?: AssertDocumentValidOptions): Promise<CliLangiumDocument>;