@qodalis/mcp-cli 0.0.0-stage → 0.2.0

package/dist/src/dev/scaffold.js

@@ -0,0 +1,213 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * `qcli_scaffold_plugin`: runs `@qodalis/create-cli-plugin` non-interactively. Inside a
+ * web-cli checkout it creates `packages/plugins/<name>`; anywhere else a standalone
+ * `qodalis-cli-<name>` project (and installs its dependencies).
+ */
+export const SCAFFOLD_PACKAGE = '@qodalis/create-cli-plugin@latest';
+export const SCAFFOLD_TIMEOUT_MS = 5 * 60_000;
+const OUTPUT_LIMIT = 6000;
+export class ScaffoldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScaffoldError';
+    }
+}
+const toPascalCase = (name) => name
+    .split(/[-_\s]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+/** The web-cli monorepo root above `dir` (same rule as create-cli-plugin), if any. */
+export const detectMonorepo = (dir) => {
+    let current = path.resolve(dir);
+    for (;;) {
+        const workspace = path.join(current, 'pnpm-workspace.yaml');
+        if (existsSync(workspace) &&
+            existsSync(path.join(current, 'packages', 'plugins')) &&
+            readFileSync(workspace, 'utf8').includes('packages/plugins')) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+};
+/** Validates the arguments and works out where the plugin goes; throws {@link ScaffoldError}. */
+export const planScaffold = (input, cwd = process.cwd()) => {
+    const name = (input.name ?? '').trim();
+    if (!/^[a-z][a-z0-9-]*$/.test(name) || name.endsWith('-') || name.includes('--')) {
+        throw new ScaffoldError(`Invalid plugin name "${name}": use lowercase letters, digits and single hyphens, starting with a letter (e.g. "weather" or "json-tools").`);
+    }
+    if (name.startsWith('cli-')) {
+        throw new ScaffoldError(`Invalid plugin name "${name}": leave out the "cli-" prefix, it is added to the package name (@qodalis/cli-${name.slice(4)}).`);
+    }
+    if (name.length > 50) {
+        throw new ScaffoldError('Invalid plugin name: at most 50 characters.');
+    }
+    const processorName = input.processorName?.trim() || toPascalCase(name);
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(processorName)) {
+        throw new ScaffoldError(`Invalid processorName "${processorName}": PascalCase letters and digits (e.g. "Weather"; the class becomes Cli${processorName}CommandProcessor).`);
+    }
+    const description = input.description?.trim();
+    if (description !== undefined &&
+        (description.length > 200 || /[\0-\x1f"`$\\]/.test(description))) {
+        throw new ScaffoldError('Invalid description: one line of at most 200 characters, without quotes, backticks, $ or backslashes.');
+    }
+    const dir = path.resolve(cwd, input.directory?.trim() || '.');
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+        throw new ScaffoldError(`Directory ${dir} does not exist.`);
+    }
+    const monorepo = detectMonorepo(dir);
+    const target = monorepo
+        ? path.join(monorepo, 'packages', 'plugins', name)
+        : path.join(dir, `qodalis-cli-${name}`);
+    if (existsSync(target)) {
+        throw new ScaffoldError(`${target} already exists; pick another name or directory.`);
+    }
+    const args = ['-y', SCAFFOLD_PACKAGE, '--name', name, '--processor-name', processorName];
+    if (description) {
+        args.push('--description', description);
+    }
+    return { args, cwd: dir, monorepo, name, processorName, target };
+};
+/** Runs a command without a TTY, stdin closed, capturing stdout and stderr together. */
+export const runCommand = (command, args, options) => new Promise((resolve, reject) => {
+    const windows = process.platform === 'win32';
+    // npx is a .cmd on Windows, which needs a shell; the arguments are validated
+    // (no quotes or shell metacharacters) and quoted.
+    const viaShell = windows && command === 'npx';
+    const child = spawn(viaShell ? 'npx.cmd' : command, viaShell ? args.map((a) => `"${a}"`) : args, {
+        cwd: options.cwd,
+        // Own process group on POSIX, so a timeout also stops npm install below npx.
+        detached: !windows,
+        env: { ...process.env, CI: 'true', npm_config_yes: 'true' },
+        shell: viaShell,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let output = '';
+    let timedOut = false;
+    const append = (chunk) => {
+        output += chunk.toString();
+        if (output.length > OUTPUT_LIMIT * 4) {
+            output = output.slice(-OUTPUT_LIMIT * 2);
+        }
+    };
+    child.stdout.on('data', append);
+    child.stderr.on('data', append);
+    const signalTree = (signal) => {
+        try {
+            if (!windows && child.pid) {
+                process.kill(-child.pid, signal);
+            }
+            else {
+                child.kill(signal);
+            }
+        }
+        catch {
+            // already gone
+        }
+    };
+    const kill = () => {
+        signalTree('SIGTERM');
+        setTimeout(() => signalTree('SIGKILL'), 3000).unref();
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        kill();
+    }, options.timeoutMs);
+    options.signal?.addEventListener('abort', kill, { once: true });
+    child.on('error', (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', kill);
+        resolve({ code, output, timedOut });
+    });
+});
+/** Files under `dir`, relative, without node_modules / dist / .git. */
+export const listFiles = (dir, limit = 200) => {
+    const files = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (files.length >= limit) {
+                return;
+            }
+            if (['node_modules', 'dist', '.git'].includes(entry.name)) {
+                continue;
+            }
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else {
+                files.push(path.relative(dir, full).split(path.sep).join('/'));
+            }
+        }
+    };
+    if (existsSync(dir)) {
+        walk(dir);
+    }
+    return files.sort();
+};
+const stripAnsi = (text) => text.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+const tail = (text) => {
+    const clean = stripAnsi(text).trim();
+    return clean.length > OUTPUT_LIMIT ? `…${clean.slice(-OUTPUT_LIMIT)}` : clean;
+};
+/** Runs create-cli-plugin for a validated plan and describes what it created. */
+export const scaffoldPlugin = async (plan, options = {}) => {
+    const timeoutMs = options.timeoutMs ?? SCAFFOLD_TIMEOUT_MS;
+    const result = await (options.runner ?? runCommand)('npx', plan.args, {
+        cwd: plan.cwd,
+        signal: options.signal,
+        timeoutMs,
+    });
+    const command = `npx ${plan.args.join(' ')}`;
+    if (result.timedOut || result.code !== 0) {
+        const why = result.timedOut
+            ? `timed out after ${Math.round(timeoutMs / 1000)} s`
+            : `exited with code ${result.code}`;
+        return {
+            isError: true,
+            text: `\`${command}\` (in ${plan.cwd}) ${why}.\n\nOutput:\n${tail(result.output)}`,
+        };
+    }
+    const files = listFiles(plan.target);
+    const className = `Cli${plan.processorName}CommandProcessor`;
+    const steps = plan.monorepo
+        ? [
+            `Implement the command in ${plan.target}/src/lib/processors/ (class ${className}).`,
+            `Build: \`pnpm nx build ${plan.name}\`; test: \`pnpm nx test ${plan.name}\`.`,
+            'Register the module in a demo app (e.g. apps/demo-angular) to try it.',
+        ]
+        : [
+            `Implement the command in ${plan.target}/src/lib/processors/ (class ${className}).`,
+            `Build with \`npx tsup\` in ${plan.target}.`,
+            'Register the exported module in your host app (`modules` input/prop, or engine.registerModule()).',
+            'Publish with `npm publish --access public` when ready.',
+        ];
+    return {
+        isError: false,
+        text: [
+            `Created the ${plan.name} plugin in ${plan.target}${plan.monorepo ? ` (web-cli monorepo at ${plan.monorepo})` : ''}.`,
+            '',
+            `Files (${files.length}):`,
+            ...files.map((f) => `- ${f}`),
+            '',
+            'Next steps:',
+            ...steps.map((s, i) => `${i + 1}. ${s}`),
+            '',
+            'Look up the APIs with qcli_api (ICliCommandProcessor, ICliExecutionContext, ICliModule) and the guide with qcli_docs_search.',
+            '',
+            `Output of \`${command}\`:`,
+            tail(result.output),
+        ].join('\n'),
+    };
+};
+//# sourceMappingURL=scaffold.js.map

package/dist/src/dev/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/dev/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/src/dev/tools.d.ts

@@ -0,0 +1,170 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/server';
+import type { Config } from '../config.js';
+import { ApiSource, type ApiSourceOptions } from './api.js';
+import { DocsSource, type DocsSourceOptions } from './docs.js';
+import { type Runner } from './scaffold.js';
+export declare const DOCS_RESOURCE_SCHEME = "qcli-docs://";
+/** The local plugin-development tools, served without a Qodalis CLI server. */
+export declare const DEV_TOOLS: Tool[];
+export declare const DEV_TOOL_NAMES: Set<string>;
+export type DevToolsOptions = {
+    api?: ApiSourceOptions;
+    docs?: Partial<DocsSourceOptions>;
+    log?: (message: string) => void;
+    /** Runs npx (tests) */
+    runner?: Runner;
+    scaffoldTimeoutMs?: number;
+};
+/** Docs, API and scaffold tools plus the prompts and docs resources, filtered by the config. */
+export declare class DevTools {
+    private readonly config;
+    private readonly options;
+    readonly docs: DocsSource;
+    readonly api: ApiSource;
+    constructor(config: Config, options?: DevToolsOptions);
+    /** The dev tools that pass QCLI_READ_ONLY / QCLI_TOOLS / QCLI_EXCLUDE. */
+    tools(): Tool[];
+    has(name: string): boolean;
+    /** Why a dev tool is hidden, or undefined when it is available. */
+    hiddenReason(name: string): string | undefined;
+    call(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<CallToolResult>;
+    private search;
+    private read;
+    private lookup;
+    private scaffold;
+    prompts(): {
+        name: string;
+        description?: string | undefined;
+        arguments?: {
+            name: string;
+            description?: string | undefined;
+            required?: boolean | undefined;
+        }[] | undefined;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined;
+            sizes?: string[] | undefined;
+            theme?: "light" | "dark" | undefined;
+        }[] | undefined;
+        title?: string | undefined;
+    }[];
+    getPrompt(name: string, args: Record<string, string> | undefined): {
+        [x: string]: unknown;
+        messages: {
+            role: "user" | "assistant";
+            content: {
+                type: "text";
+                text: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                type: "image";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                type: "audio";
+                data: string;
+                mimeType: string;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            } | {
+                uri: string;
+                name: string;
+                type: "resource_link";
+                description?: string | undefined;
+                mimeType?: string | undefined;
+                size?: number | undefined;
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            } | {
+                type: "resource";
+                resource: {
+                    uri: string;
+                    text: string;
+                    mimeType?: string | undefined;
+                    _meta?: {
+                        [x: string]: unknown;
+                    } | undefined;
+                } | {
+                    uri: string;
+                    blob: string;
+                    mimeType?: string | undefined;
+                    _meta?: {
+                        [x: string]: unknown;
+                    } | undefined;
+                };
+                annotations?: {
+                    audience?: ("user" | "assistant")[] | undefined;
+                    priority?: number | undefined;
+                    lastModified?: string | undefined;
+                } | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+            };
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/serverInfo"?: {
+                version: string;
+                name: string;
+                websiteUrl?: string | undefined;
+                description?: string | undefined;
+                icons?: {
+                    src: string;
+                    mimeType?: string | undefined;
+                    sizes?: string[] | undefined;
+                    theme?: "light" | "dark" | undefined;
+                }[] | undefined;
+                title?: string | undefined;
+            } | undefined;
+        } | undefined;
+        description?: string | undefined;
+    };
+    resources(): Promise<{
+        description: string;
+        mimeType: string;
+        name: string;
+        title: string;
+        uri: string;
+    }[]>;
+    /** The markdown of a `qcli-docs://<section>/<topic>` resource, or undefined. */
+    readResource(uri: string): Promise<string | undefined>;
+}
+//# sourceMappingURL=tools.d.ts.map

package/dist/src/dev/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/dev/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EACH,SAAS,EAIT,KAAK,gBAAgB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EACH,UAAU,EAKV,KAAK,iBAAiB,EACzB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAE1E,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,SAAS,EAAE,IAAI,EA4F3B,CAAC;AAEF,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE,MAAM,MAAM,eAAe,GAAG;IAC1B,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAyBF,gGAAgG;AAChG,qBAAa,QAAQ;IAKb,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;gBAGH,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB;IAUlD,0EAA0E;IAC1E,KAAK,IAAI,IAAI,EAAE;IAIf,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,mEAAmE;IACnE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUxC,IAAI,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,cAAc,CAAC;YAmBZ,MAAM;YAuBN,IAAI;YAwBJ,MAAM;YAmBN,QAAQ;IA2BtB,OAAO;;;;;;;;;;;;;;;;;;;IAIP,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAO1D,SAAS;;;;;;;IAWf,gFAAgF;IAC1E,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAQ/D"}

package/dist/src/dev/tools.js

@@ -0,0 +1,258 @@
+import { isToolAllowed } from '../filters.js';
+import { ApiSource, formatLookup, lookupSymbol, normalizePackageName, } from './api.js';
+import { DocsSource, listTopics, readDocs, searchDocs, } from './docs.js';
+import { getPrompt, PROMPTS } from './prompts.js';
+import { planScaffold, scaffoldPlugin } from './scaffold.js';
+export const DOCS_RESOURCE_SCHEME = 'qcli-docs://';
+/** The local plugin-development tools, served without a Qodalis CLI server. */
+export const DEV_TOOLS = [
+    {
+        annotations: { openWorldHint: true, readOnlyHint: true, title: 'Search the plugin docs' },
+        description: 'Search the Qodalis CLI plugin-development guide (web plugins, server plugins, recipes). Returns the best matching topics as "Section › Topic" with their summary and an excerpt; read one in full with qcli_docs_read.',
+        inputSchema: {
+            properties: {
+                limit: {
+                    description: 'Maximum number of topics (default 5, at most 20)',
+                    maximum: 20,
+                    minimum: 1,
+                    type: 'integer',
+                },
+                query: {
+                    description: 'Keywords, e.g. "read user input", "register module", "ICliExecutionContext"',
+                    type: 'string',
+                },
+            },
+            required: ['query'],
+            type: 'object',
+        },
+        name: 'qcli_docs_search',
+    },
+    {
+        annotations: { openWorldHint: true, readOnlyHint: true, title: 'Read a plugin docs topic' },
+        description: 'Read a topic of the Qodalis CLI plugin-development guide in full (markdown with code samples). Pass a topic heading (case-insensitive), "Section › Topic" when a heading exists in several sections, or a section name ("Web plugins") for the whole section. Lists the topics when nothing matches.',
+        inputSchema: {
+            properties: {
+                topic: {
+                    description: 'Topic heading, "Section › Topic", or a section name',
+                    type: 'string',
+                },
+            },
+            required: ['topic'],
+            type: 'object',
+        },
+        name: 'qcli_docs_read',
+    },
+    {
+        annotations: { openWorldHint: true, readOnlyHint: true, title: 'Look up a Qodalis API' },
+        description: "TypeScript declaration (with JSDoc) of an interface, type, class, function, enum or constant from the published @qodalis packages: the project's node_modules when installed, else the latest version on npm. Use it for exact member names and signatures, e.g. ICliCommandProcessor, ICliExecutionContext, ICliModule, ICliInputReader, CliProcessCommand.",
+        inputSchema: {
+            properties: {
+                package: {
+                    description: 'Package to read (default @qodalis/cli-core; also @qodalis/cli, @qodalis/angular-cli, ...). "cli-core" is short for @qodalis/cli-core.',
+                    type: 'string',
+                },
+                symbol: { description: 'Exported name, case-sensitive', type: 'string' },
+            },
+            required: ['symbol'],
+            type: 'object',
+        },
+        name: 'qcli_api',
+    },
+    {
+        annotations: {
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+            readOnlyHint: false,
+            title: 'Scaffold a Qodalis CLI plugin',
+        },
+        description: 'Create a new web CLI plugin with @qodalis/create-cli-plugin (npx): processor, module, build config and tests. Inside a web-cli checkout it goes to packages/plugins/<name>; elsewhere to a standalone qodalis-cli-<name> project with its dependencies installed. Returns the created files and next steps.',
+        inputSchema: {
+            properties: {
+                description: { description: 'One-line description of the plugin', type: 'string' },
+                directory: {
+                    description: 'Directory to run in (default: the current working directory of the MCP server)',
+                    type: 'string',
+                },
+                name: {
+                    description: 'Plugin name: lowercase letters, digits and hyphens, without a "cli-" prefix (package @qodalis/cli-<name>)',
+                    type: 'string',
+                },
+                processorName: {
+                    description: 'PascalCase processor name (class Cli<processorName>CommandProcessor); default derived from name',
+                    type: 'string',
+                },
+            },
+            required: ['name'],
+            type: 'object',
+        },
+        name: 'qcli_scaffold_plugin',
+    },
+];
+export const DEV_TOOL_NAMES = new Set(DEV_TOOLS.map((t) => t.name));
+const text = (value, isError = false) => ({
+    content: [{ text: value, type: 'text' }],
+    ...(isError ? { isError: true } : {}),
+});
+const stringArg = (args, name, required = false) => {
+    const value = args[name];
+    if (value === undefined || value === null || value === '') {
+        if (required) {
+            throw new Error(`Missing required argument "${name}".`);
+        }
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Argument "${name}" must be a string.`);
+    }
+    return value;
+};
+/** Docs, API and scaffold tools plus the prompts and docs resources, filtered by the config. */
+export class DevTools {
+    config;
+    options;
+    docs;
+    api;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.options = options;
+        this.docs = new DocsSource({
+            url: config.docsUrl,
+            ...(options.log ? { log: options.log } : {}),
+            ...options.docs,
+        });
+        this.api = new ApiSource({ ...(options.log ? { log: options.log } : {}), ...options.api });
+    }
+    /** The dev tools that pass QCLI_READ_ONLY / QCLI_TOOLS / QCLI_EXCLUDE. */
+    tools() {
+        return DEV_TOOLS.filter((tool) => isToolAllowed(tool, this.config));
+    }
+    has(name) {
+        return DEV_TOOL_NAMES.has(name);
+    }
+    /** Why a dev tool is hidden, or undefined when it is available. */
+    hiddenReason(name) {
+        const tool = DEV_TOOLS.find((t) => t.name === name);
+        if (!tool || isToolAllowed(tool, this.config)) {
+            return undefined;
+        }
+        return this.config.readOnly && tool.annotations?.readOnlyHint !== true
+            ? `Tool ${name} is not available: QCLI_READ_ONLY allows only read-only tools.`
+            : `Tool ${name} is not available: excluded by QCLI_TOOLS / QCLI_EXCLUDE.`;
+    }
+    async call(name, args, signal) {
+        try {
+            switch (name) {
+                case 'qcli_docs_search':
+                    return await this.search(args);
+                case 'qcli_docs_read':
+                    return await this.read(args);
+                case 'qcli_api':
+                    return await this.lookup(args);
+                case 'qcli_scaffold_plugin':
+                    return await this.scaffold(args, signal);
+                default:
+                    return text(`Unknown tool: ${name}`, true);
+            }
+        }
+        catch (error) {
+            return text(error instanceof Error ? error.message : String(error), true);
+        }
+    }
+    async search(args) {
+        const query = stringArg(args, 'query', true);
+        const rawLimit = args['limit'];
+        const limit = typeof rawLimit === 'number' && Number.isFinite(rawLimit)
+            ? Math.min(20, Math.max(1, Math.floor(rawLimit)))
+            : 5;
+        const docs = await this.docs.get();
+        const hits = searchDocs(docs, query, limit);
+        if (hits.length === 0) {
+            return text(`No topic matches "${query}". Topics in the guide (${docs.source}):\n\n${listTopics(docs)}`);
+        }
+        const lines = hits.map((hit, i) => `${i + 1}. **${hit.topic.section} › ${hit.topic.title}** (score ${hit.score})\n   ${hit.topic.summary}${hit.excerpt && hit.excerpt !== hit.topic.summary ? `\n   > ${hit.excerpt}` : ''}`);
+        return text(`${hits.length} topic(s) for "${query}" (source: ${docs.source}). Read one with qcli_docs_read and its "Section › Topic".\n\n${lines.join('\n')}`);
+    }
+    async read(args) {
+        const topic = stringArg(args, 'topic', true);
+        const docs = await this.docs.get();
+        const result = readDocs(docs, topic);
+        if (result.kind === 'section') {
+            return text(result.section.content);
+        }
+        if (result.kind === 'topics') {
+            return text(result.topics
+                .map((t) => result.topics.length > 1
+                ? `<!-- ${t.section} › ${t.title} -->\n${t.content}`
+                : t.content)
+                .join('\n\n---\n\n'));
+        }
+        return text(`No topic or section "${topic}" in the guide (${docs.source}). Available topics:\n\n${listTopics(docs)}`, true);
+    }
+    async lookup(args) {
+        const symbol = stringArg(args, 'symbol', true).trim();
+        if (!/^[A-Za-z_$][\w$]*$/.test(symbol)) {
+            return text(`"${symbol}" is not an identifier (e.g. ICliCommandProcessor).`, true);
+        }
+        const pkg = normalizePackageName(stringArg(args, 'package'));
+        let types;
+        try {
+            types = await this.api.get(pkg);
+        }
+        catch (error) {
+            return text(`Could not load the declarations of ${pkg}: ${error.message}. Install the package in the project (npm install ${pkg}) to work offline.`, true);
+        }
+        const lookup = lookupSymbol(types, symbol);
+        return text(formatLookup(symbol, lookup), lookup.declarations.length === 0);
+    }
+    async scaffold(args, signal) {
+        const reason = this.hiddenReason('qcli_scaffold_plugin');
+        if (reason) {
+            return text(reason, true);
+        }
+        const plan = planScaffold({
+            description: stringArg(args, 'description'),
+            directory: stringArg(args, 'directory'),
+            name: stringArg(args, 'name', true),
+            processorName: stringArg(args, 'processorName'),
+        });
+        this.options.log?.(`scaffold: npx ${plan.args.join(' ')} in ${plan.cwd}`);
+        const result = await scaffoldPlugin(plan, {
+            ...(this.options.runner ? { runner: this.options.runner } : {}),
+            ...(this.options.scaffoldTimeoutMs
+                ? { timeoutMs: this.options.scaffoldTimeoutMs }
+                : {}),
+            signal,
+        });
+        return text(result.text, result.isError);
+    }
+    // ------------------------------------------------------------ prompts
+    prompts() {
+        return PROMPTS;
+    }
+    getPrompt(name, args) {
+        const ctx = { canScaffold: !this.hiddenReason('qcli_scaffold_plugin') };
+        return getPrompt(name, args, ctx);
+    }
+    // ------------------------------------------------------------ resources
+    async resources() {
+        const docs = await this.docs.get();
+        return docs.topics.map((t) => ({
+            description: t.summary,
+            mimeType: 'text/markdown',
+            name: `${t.section} › ${t.title}`,
+            title: t.title,
+            uri: `${DOCS_RESOURCE_SCHEME}${t.uri}`,
+        }));
+    }
+    /** The markdown of a `qcli-docs://<section>/<topic>` resource, or undefined. */
+    async readResource(uri) {
+        if (!uri.startsWith(DOCS_RESOURCE_SCHEME)) {
+            return undefined;
+        }
+        const docs = await this.docs.get();
+        const path = uri.slice(DOCS_RESOURCE_SCHEME.length);
+        return docs.topics.find((t) => t.uri === path)?.content;
+    }
+}
+//# sourceMappingURL=tools.js.map