@tanstack/cli 0.60.1 → 0.61.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @tanstack/cli
 
+## 0.61.1
+
+### Patch Changes
+
+- Auto-generated changeset from semantic commits on main.
+
+  - fix(ci): use direct changeset publish args (b6f5ff5)
+
+- Updated dependencies []:
+  - @tanstack/create@0.62.3
+
+## 0.61.0
+
+### Minor Changes
+
+- Remove the built-in MCP server from the CLI by dropping `tanstack mcp` and all MCP transport/tooling code. ([`78e3734`](https://github.com/TanStack/cli/commit/78e373444c5bcaf2ab59d2142e8b8b0cab415bbb))
+
+  Add CLI-native agent introspection commands (`libraries`, `doc`, `search-docs`, `ecosystem`) and JSON output for `create --list-add-ons` / `create --addon-details` so AI agents can rely on CLI commands directly.
+
+### Patch Changes
+
+- Make the default base starter minimal (Home + About) for React and Solid, and add a new `blog` template option for both frameworks. ([`f33f8d4`](https://github.com/TanStack/cli/commit/f33f8d4954d9ad6771871257a4e1e58feee9b34d))
+
+  Interactive `create` now prompts for a template when one is not provided, and template id resolution prefers the selected framework when ids overlap.
+
+- Updated dependencies [[`f33f8d4`](https://github.com/TanStack/cli/commit/f33f8d4954d9ad6771871257a4e1e58feee9b34d), [`16fcd67`](https://github.com/TanStack/cli/commit/16fcd674c0f74c1c62cf97b0042060d5a51981ef)]:
+  - @tanstack/create@0.62.2
+
 ## 0.60.1
 
 ### Patch Changes

package/dist/cli.js

@@ -5,7 +5,7 @@ import { cancel, confirm, intro, isCancel, log } from '@clack/prompts';
 import chalk from 'chalk';
 import semver from 'semver';
 import { SUPPORTED_PACKAGE_MANAGERS, addToApp, compileAddOn, compileStarter, createApp, devAddOn, getAllAddOns, getFrameworkByName, getFrameworks, initAddOn, initStarter, } from '@tanstack/create';
-import { runMCPServer } from './mcp.js';
+import { LIBRARY_GROUPS, fetchDocContent, fetchLibraries, fetchPartners, searchTanStackDocs, } from './discovery.js';
 import { promptForAddOns, promptForCreateOptions } from './options.js';
 import { normalizeOptions, validateDevWatchOptions, validateLegacyCreateFlags, } from './command-line.js';
 import { createUIEnvironment } from './ui-environment.js';
@@ -125,6 +125,33 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
     }
     // Mode is always file-router (TanStack Start)
     const defaultMode = 'file-router';
+    const categoryAliases = {
+        db: 'database',
+        postgres: 'database',
+        sql: 'database',
+        login: 'auth',
+        authentication: 'auth',
+        hosting: 'deployment',
+        deploy: 'deployment',
+        serverless: 'deployment',
+        errors: 'monitoring',
+        logging: 'monitoring',
+        content: 'cms',
+        'api-keys': 'api',
+        grid: 'data-grid',
+        review: 'code-review',
+        courses: 'learning',
+    };
+    function printJson(data) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    function parsePositiveInteger(value) {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+            throw new InvalidArgumentError('Value must be a positive integer');
+        }
+        return parsed;
+    }
     program
         .name(name)
         .description(`${appName} CLI`)
@@ -141,8 +168,26 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         }
         if (options.listAddOns) {
             const addOns = await getAllAddOns(getFrameworkByName(options.framework || defaultFramework || 'React'), defaultMode);
+            const visibleAddOns = addOns.filter((a) => !forcedAddOns.includes(a.id));
+            if (options.json) {
+                printJson(visibleAddOns.map((addOn) => ({
+                    id: addOn.id,
+                    name: addOn.name,
+                    description: addOn.description,
+                    type: addOn.type,
+                    category: addOn.category,
+                    phase: addOn.phase,
+                    modes: addOn.modes,
+                    link: addOn.link,
+                    warning: addOn.warning,
+                    exclusive: addOn.exclusive,
+                    dependsOn: addOn.dependsOn,
+                    options: addOn.options,
+                })));
+                return;
+            }
             let hasConfigurableAddOns = false;
-            for (const addOn of addOns.filter((a) => !forcedAddOns.includes(a.id))) {
+            for (const addOn of visibleAddOns) {
                 const hasOptions = addOn.options && Object.keys(addOn.options).length > 0;
                 const optionMarker = hasOptions ? '*' : ' ';
                 if (hasOptions)
@@ -162,6 +207,33 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
                 console.error(`Add-on '${options.addonDetails}' not found`);
                 process.exit(1);
             }
+            if (options.json) {
+                const files = await addOn.getFiles();
+                printJson({
+                    id: addOn.id,
+                    name: addOn.name,
+                    description: addOn.description,
+                    type: addOn.type,
+                    category: addOn.category,
+                    phase: addOn.phase,
+                    modes: addOn.modes,
+                    link: addOn.link,
+                    warning: addOn.warning,
+                    exclusive: addOn.exclusive,
+                    dependsOn: addOn.dependsOn,
+                    options: addOn.options,
+                    routes: addOn.routes,
+                    packageAdditions: addOn.packageAdditions,
+                    shadcnComponents: addOn.shadcnComponents,
+                    integrations: addOn.integrations,
+                    readme: addOn.readme,
+                    files,
+                    author: addOn.author,
+                    version: addOn.version,
+                    license: addOn.license,
+                });
+                return;
+            }
             console.log(`${chalk.bold.cyan('Add-on Details:')} ${chalk.bold(addOn.name)}`);
             console.log(`${chalk.bold('ID:')} ${addOn.id}`);
             console.log(`${chalk.bold('Description:')} ${addOn.description}`);
@@ -177,7 +249,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
             if (addOn.options && Object.keys(addOn.options).length > 0) {
                 console.log(`\n${chalk.bold.yellow('Configuration Options:')}`);
                 for (const [optionName, option] of Object.entries(addOn.options)) {
-                    if (option && typeof option === 'object' && 'type' in option) {
+                    if ('type' in option) {
                         const opt = option;
                         console.log(`  ${chalk.bold(optionName)}:`);
                         console.log(`    Label: ${opt.label}`);
@@ -335,6 +407,7 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         })
             .option('--list-add-ons', 'list all available add-ons', false)
             .option('--addon-details <addon-id>', 'show detailed information about a specific add-on')
+            .option('--json', 'output JSON for automation', false)
             .option('--git', 'create a git repository')
             .option('--no-git', 'do not create a git repository')
             .option('--target-dir <path>', 'the target directory for the application root')
@@ -371,16 +444,198 @@ export function cli({ name, appName, forcedAddOns = [], forcedDeployment, defaul
         };
         await startDevWatchMode(projectName, devOptions);
     });
-    // === MCP SUBCOMMAND ===
+    // === LIBRARIES SUBCOMMAND ===
     program
-        .command('mcp')
-        .description('Run the MCP (Model Context Protocol) server')
-        .option('--sse', 'Run in SSE mode instead of stdio', false)
+        .command('libraries')
+        .description('List TanStack libraries')
+        .option('--group <group>', `filter by group (${LIBRARY_GROUPS.join(', ')})`)
+        .option('--json', 'output JSON for automation', false)
         .action(async (options) => {
-        await runMCPServer(options.sse, {
-            forcedAddOns,
-            appName,
-        });
+        try {
+            const data = await fetchLibraries();
+            let libraries = data.libraries;
+            if (options.group &&
+                Object.prototype.hasOwnProperty.call(data.groups, options.group)) {
+                const groupIds = data.groups[options.group];
+                libraries = libraries.filter((lib) => groupIds.includes(lib.id));
+            }
+            const groupName = options.group
+                ? data.groupNames[options.group] || options.group
+                : 'All Libraries';
+            const payload = {
+                group: groupName,
+                count: libraries.length,
+                libraries: libraries.map((lib) => ({
+                    id: lib.id,
+                    name: lib.name,
+                    tagline: lib.tagline,
+                    description: lib.description,
+                    frameworks: lib.frameworks,
+                    latestVersion: lib.latestVersion,
+                    docsUrl: lib.docsUrl,
+                    githubUrl: lib.githubUrl,
+                })),
+            };
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            console.log(chalk.bold(groupName));
+            for (const lib of payload.libraries) {
+                console.log(`${chalk.bold(lib.id)} (${lib.latestVersion}) - ${lib.tagline}`);
+            }
+        }
+        catch (error) {
+            log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    // === DOC SUBCOMMAND ===
+    program
+        .command('doc')
+        .description('Fetch a TanStack documentation page')
+        .argument('<library>', 'library ID (eg. query, router, table)')
+        .argument('<path>', 'documentation path (eg. framework/react/overview)')
+        .option('--docs-version <version>', 'docs version (default: latest)', 'latest')
+        .option('--json', 'output JSON for automation', false)
+        .action(async (libraryId, path, options) => {
+        try {
+            const data = await fetchLibraries();
+            const library = data.libraries.find((l) => l.id === libraryId);
+            if (!library) {
+                throw new Error(`Library "${libraryId}" not found. Use \`tanstack libraries\` to see available libraries.`);
+            }
+            if (options.docsVersion !== 'latest' &&
+                !library.availableVersions.includes(options.docsVersion)) {
+                throw new Error(`Version "${options.docsVersion}" not found for ${library.name}. Available: ${library.availableVersions.join(', ')}`);
+            }
+            const branch = options.docsVersion === 'latest' ||
+                options.docsVersion === library.latestVersion
+                ? library.latestBranch || 'main'
+                : options.docsVersion;
+            const docsRoot = library.docsRoot || 'docs';
+            const filePath = `${docsRoot}/${path}.md`;
+            const content = await fetchDocContent(library.repo, branch, filePath);
+            if (!content) {
+                throw new Error(`Document not found: ${library.name} / ${path} (version: ${options.docsVersion})`);
+            }
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            let title = path.split('/').pop() || 'Untitled';
+            let docContent = content;
+            if (frontmatterMatch && frontmatterMatch[1]) {
+                const frontmatter = frontmatterMatch[1];
+                const titleMatch = frontmatter.match(/title:\s*['"]?([^'"\n]+)['"]?/);
+                if (titleMatch && titleMatch[1]) {
+                    title = titleMatch[1];
+                }
+                docContent = content.slice(frontmatterMatch[0].length).trim();
+            }
+            const payload = {
+                title,
+                content: docContent,
+                url: `https://tanstack.com/${libraryId}/${options.docsVersion}/docs/${path}`,
+                library: library.name,
+                version: options.docsVersion === 'latest'
+                    ? library.latestVersion
+                    : options.docsVersion,
+            };
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            console.log(chalk.bold(payload.title));
+            console.log(chalk.blue(payload.url));
+            console.log('');
+            console.log(payload.content);
+        }
+        catch (error) {
+            log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    // === SEARCH-DOCS SUBCOMMAND ===
+    program
+        .command('search-docs')
+        .description('Search TanStack documentation')
+        .argument('<query>', 'search query')
+        .option('--library <id>', 'filter to specific library')
+        .option('--framework <name>', 'filter to specific framework')
+        .option('--limit <n>', 'max results (default: 10, max: 50)', parsePositiveInteger, 10)
+        .option('--json', 'output JSON for automation', false)
+        .action(async (query, options) => {
+        try {
+            const payload = await searchTanStackDocs({
+                query,
+                library: options.library,
+                framework: options.framework,
+                limit: options.limit,
+            });
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            for (const result of payload.results) {
+                console.log(`${chalk.bold(result.title)} [${result.library}]\n${chalk.blue(result.url)}\n${result.snippet}\n`);
+            }
+        }
+        catch (error) {
+            log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
+    // === ECOSYSTEM SUBCOMMAND ===
+    program
+        .command('ecosystem')
+        .description('List TanStack ecosystem partners')
+        .option('--category <category>', 'filter by category')
+        .option('--library <id>', 'filter by TanStack library')
+        .option('--json', 'output JSON for automation', false)
+        .action(async (options) => {
+        try {
+            const data = await fetchPartners();
+            let resolvedCategory;
+            if (options.category) {
+                const normalized = options.category.toLowerCase().trim();
+                resolvedCategory = categoryAliases[normalized] || normalized;
+                if (!data.categories.includes(resolvedCategory)) {
+                    resolvedCategory = undefined;
+                }
+            }
+            const library = options.library?.toLowerCase().trim();
+            const partners = data.partners
+                .filter((partner) => resolvedCategory ? partner.category === resolvedCategory : true)
+                .filter((partner) => library ? partner.libraries.some((l) => l === library) : true)
+                .map((partner) => ({
+                id: partner.id,
+                name: partner.name,
+                tagline: partner.tagline,
+                description: partner.description,
+                category: partner.category,
+                categoryLabel: partner.categoryLabel,
+                url: partner.url,
+                libraries: partner.libraries,
+            }));
+            const payload = {
+                query: {
+                    category: options.category,
+                    categoryResolved: resolvedCategory,
+                    library: options.library,
+                },
+                count: partners.length,
+                partners,
+            };
+            if (options.json) {
+                printJson(payload);
+                return;
+            }
+            for (const partner of partners) {
+                console.log(`${chalk.bold(partner.name)} [${partner.category}] - ${partner.description}\n${chalk.blue(partner.url)}`);
+            }
+        }
+        catch (error) {
+            log.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
     });
     // === PIN-VERSIONS SUBCOMMAND ===
     program

package/dist/command-line.js

@@ -26,6 +26,13 @@ function slugifyStarterName(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+function humanizeStarterId(value) {
+    return value
+        .split(/[-_]/g)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join(' ');
+}
 function isLikelyStarterUrlOrPath(value) {
     return (/^https?:\/\//i.test(value) ||
         /^file:\/\//i.test(value) ||
@@ -53,7 +60,7 @@ function getStarterIdsFromUrl(starterUrl) {
     }
     return ids;
 }
-function resolveMonorepoStarterById(starterId) {
+function resolveMonorepoStarterById(starterId, preferredFramework) {
     const normalized = starterId.toLowerCase().trim();
     const idVariants = Array.from(new Set([
         normalized,
@@ -67,8 +74,11 @@ function resolveMonorepoStarterById(starterId) {
         resolve(cwd, '../..'),
         resolve(cwd, '../../..'),
     ];
+    const frameworkOrder = preferredFramework
+        ? [preferredFramework, ...['react', 'solid'].filter((f) => f !== preferredFramework)]
+        : ['react', 'solid'];
     for (const root of rootCandidates) {
-        for (const framework of ['react', 'solid']) {
+        for (const framework of frameworkOrder) {
             for (const id of idVariants) {
                 const templatePath = resolve(root, 'examples', framework, id, 'template.json');
                 if (fs.existsSync(templatePath)) {
@@ -83,7 +93,7 @@ function resolveMonorepoStarterById(starterId) {
     }
     return undefined;
 }
-async function resolveStarterSpecifier(starterSpecifier) {
+export async function resolveStarterSpecifier(starterSpecifier, preferredFramework) {
     const normalized = starterSpecifier.trim();
     if (!normalized || isLikelyStarterUrlOrPath(normalized)) {
         return normalized;
@@ -91,7 +101,7 @@ async function resolveStarterSpecifier(starterSpecifier) {
     const registry = await getRawRegistry();
     if (registry && registry.starters?.length) {
         const lookup = normalized.toLowerCase();
-        const match = registry.starters.find((starter) => {
+        const matches = registry.starters.filter((starter) => {
             const candidateIds = new Set();
             candidateIds.add(starter.name.toLowerCase());
             candidateIds.add(slugifyStarterName(starter.name));
@@ -100,11 +110,17 @@ async function resolveStarterSpecifier(starterSpecifier) {
             }
             return candidateIds.has(lookup);
         });
-        if (match) {
-            return match.url;
+        const frameworkMatch = preferredFramework
+            ? matches.find((starter) => starter.framework.toLowerCase() === preferredFramework)
+            : undefined;
+        if (frameworkMatch) {
+            return frameworkMatch.url;
+        }
+        if (matches.length > 0) {
+            return matches[0].url;
         }
     }
-    const monorepoStarterPath = resolveMonorepoStarterById(normalized);
+    const monorepoStarterPath = resolveMonorepoStarterById(normalized, preferredFramework);
     if (monorepoStarterPath) {
         return monorepoStarterPath;
     }
@@ -120,6 +136,84 @@ async function resolveStarterSpecifier(starterSpecifier) {
         .sort();
     throw new Error(`Unknown template id "${normalized}". Available built-in templates: ${availableIds.join(', ')}`);
 }
+export async function listTemplateChoices(preferredFramework) {
+    const frameworkFilter = preferredFramework?.toLowerCase();
+    const deduped = new Map();
+    const registry = await getRawRegistry();
+    for (const starter of registry?.starters || []) {
+        const framework = starter.framework.toLowerCase();
+        if (frameworkFilter && framework !== frameworkFilter) {
+            continue;
+        }
+        const ids = Array.from(getStarterIdsFromUrl(starter.url));
+        const id = ids[0] || slugifyStarterName(starter.name);
+        if (!id) {
+            continue;
+        }
+        const key = `${framework}:${id}`;
+        if (!deduped.has(key)) {
+            deduped.set(key, {
+                id,
+                name: starter.name,
+                description: starter.description,
+                framework,
+            });
+        }
+    }
+    const cwd = process.cwd();
+    const rootCandidates = [
+        cwd,
+        resolve(cwd, '..'),
+        resolve(cwd, '../..'),
+        resolve(cwd, '../../..'),
+    ];
+    const frameworks = frameworkFilter ? [frameworkFilter] : ['react', 'solid'];
+    for (const root of rootCandidates) {
+        for (const framework of frameworks) {
+            const frameworkDir = resolve(root, 'examples', framework);
+            if (!fs.existsSync(frameworkDir) || !fs.statSync(frameworkDir).isDirectory()) {
+                continue;
+            }
+            for (const entry of fs.readdirSync(frameworkDir, { withFileTypes: true })) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const id = entry.name;
+                const key = `${framework}:${id}`;
+                if (deduped.has(key)) {
+                    continue;
+                }
+                const templatePath = resolve(frameworkDir, id, 'template.json');
+                const starterPath = resolve(frameworkDir, id, 'starter.json');
+                if (!fs.existsSync(templatePath) && !fs.existsSync(starterPath)) {
+                    continue;
+                }
+                let name = humanizeStarterId(id);
+                let description;
+                const templateInfoPath = resolve(frameworkDir, id, 'template-info.json');
+                if (fs.existsSync(templateInfoPath)) {
+                    try {
+                        const info = JSON.parse(fs.readFileSync(templateInfoPath, 'utf8'));
+                        if (info.name) {
+                            name = info.name;
+                        }
+                        description = info.description;
+                    }
+                    catch {
+                        // Ignore malformed template-info files and use fallback values.
+                    }
+                }
+                deduped.set(key, {
+                    id,
+                    name,
+                    description,
+                    framework,
+                });
+            }
+        }
+    }
+    return Array.from(deduped.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
 export function validateLegacyCreateFlags(cliOptions) {
     const warnings = [];
     const legacyTemplate = getLegacyTemplateValue(cliOptions.template);
@@ -209,8 +303,9 @@ export async function normalizeOptions(cliOptions, forcedAddOns, opts) {
     if (!cliOptions.starter && cliOptions.templateId) {
         cliOptions.starter = cliOptions.templateId;
     }
+    const preferredFramework = (cliOptions.framework || 'react').toLowerCase();
     const starter = !routerOnly && cliOptions.starter
-        ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter))
+        ? await loadStarter(await resolveStarterSpecifier(cliOptions.starter, preferredFramework))
         : undefined;
     // TypeScript and Tailwind are always enabled with TanStack Start
     const typescript = true;

package/dist/discovery.js

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+const TANSTACK_API_BASE = 'https://tanstack.com/api/data';
+const LibrarySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    tagline: z.string(),
+    description: z.string().optional(),
+    frameworks: z.array(z.string()),
+    latestVersion: z.string(),
+    latestBranch: z.string().optional(),
+    availableVersions: z.array(z.string()),
+    repo: z.string(),
+    docsRoot: z.string().optional(),
+    defaultDocs: z.string().optional(),
+    docsUrl: z.string().optional(),
+    githubUrl: z.string().optional(),
+});
+const LibrariesResponseSchema = z.object({
+    libraries: z.array(LibrarySchema),
+    groups: z.record(z.array(z.string())),
+    groupNames: z.record(z.string()),
+});
+const PartnerSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    tagline: z.string().optional(),
+    description: z.string(),
+    category: z.string(),
+    categoryLabel: z.string(),
+    libraries: z.array(z.string()),
+    url: z.string(),
+});
+const PartnersResponseSchema = z.object({
+    partners: z.array(PartnerSchema),
+    categories: z.array(z.string()),
+    categoryLabels: z.record(z.string()),
+});
+export const LIBRARY_GROUPS = ['state', 'headlessUI', 'performance', 'tooling'];
+// Algolia config (public read-only keys)
+const ALGOLIA_APP_ID = 'FQ0DQ6MA3C';
+const ALGOLIA_API_KEY = '10c34d6a5c89f6048cf644d601e65172';
+const ALGOLIA_INDEX = 'tanstack-test';
+export async function fetchLibraries() {
+    const response = await fetch(`${TANSTACK_API_BASE}/libraries`);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch libraries: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return LibrariesResponseSchema.parse(data);
+}
+export async function fetchPartners() {
+    const response = await fetch(`${TANSTACK_API_BASE}/partners`);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch partners: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return PartnersResponseSchema.parse(data);
+}
+export async function fetchDocContent(repo, branch, filePath) {
+    const url = `https://raw.githubusercontent.com/${repo}/${branch}/${filePath}`;
+    const response = await fetch(url, {
+        headers: { 'User-Agent': 'tanstack-cli' },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            return null;
+        }
+        throw new Error(`Failed to fetch doc: ${response.statusText}`);
+    }
+    return response.text();
+}
+export async function searchTanStackDocs({ query, library, framework, limit = 10, }) {
+    const ALL_LIBRARIES = [
+        'config',
+        'form',
+        'optimistic',
+        'pacer',
+        'query',
+        'ranger',
+        'react-charts',
+        'router',
+        'start',
+        'store',
+        'table',
+        'virtual',
+        'db',
+        'devtools',
+    ];
+    const ALL_FRAMEWORKS = ['react', 'vue', 'solid', 'svelte', 'angular'];
+    const filterParts = ['version:latest'];
+    if (library) {
+        const otherLibraries = ALL_LIBRARIES.filter((l) => l !== library);
+        const exclusions = otherLibraries.map((l) => `NOT library:${l}`).join(' AND ');
+        if (exclusions)
+            filterParts.push(`(${exclusions})`);
+    }
+    if (framework) {
+        const otherFrameworks = ALL_FRAMEWORKS.filter((f) => f !== framework);
+        const exclusions = otherFrameworks.map((f) => `NOT framework:${f}`).join(' AND ');
+        if (exclusions)
+            filterParts.push(`(${exclusions})`);
+    }
+    const searchParams = {
+        requests: [
+            {
+                indexName: ALGOLIA_INDEX,
+                query,
+                hitsPerPage: Math.min(limit, 50),
+                filters: filterParts.join(' AND '),
+                attributesToRetrieve: ['hierarchy', 'url', 'content', 'library'],
+                attributesToSnippet: ['content:80'],
+            },
+        ],
+    };
+    const response = await fetch(`https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/*/queries`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Algolia-Application-Id': ALGOLIA_APP_ID,
+            'X-Algolia-API-Key': ALGOLIA_API_KEY,
+        },
+        body: JSON.stringify(searchParams),
+    });
+    if (!response.ok) {
+        throw new Error(`Algolia search failed: ${response.statusText}`);
+    }
+    const searchResponse = (await response.json());
+    const searchResult = searchResponse.results[0];
+    const results = searchResult.hits.map((hit) => {
+        const breadcrumb = Object.values(hit.hierarchy).filter((v) => Boolean(v));
+        return {
+            title: hit.hierarchy.lvl1 || hit.hierarchy.lvl0 || 'Untitled',
+            url: hit.url,
+            snippet: hit._snippetResult?.content?.value || hit.content || '',
+            library: hit.library || 'unknown',
+            breadcrumb,
+        };
+    });
+    return {
+        query,
+        totalHits: searchResult.nbHits || results.length,
+        results,
+    };
+}