@angular/cli 21.0.0-next.1 → 21.0.0-next.3

package/src/commands/mcp/tools/doc-search.js

@@ -58,28 +58,52 @@ const docSearchInputSchema = zod_1.z.object({
         .boolean()
         .optional()
         .default(true)
-        .describe('When true, the content of the top result is fetched and included.'),
+        .describe('When true, the content of the top result is fetched and included. ' +
+        'Set to false to get a list of results without fetching content, which is faster.'),
 });
 exports.DOC_SEARCH_TOOL = (0, tool_registry_1.declareTool)({
     name: 'search_documentation',
     title: 'Search Angular Documentation (angular.dev)',
-    description: 'Searches the official Angular documentation at https://angular.dev. Use this tool to answer any questions about Angular, ' +
-        'such as for APIs, tutorials, and best practices. Because the documentation is continuously updated, you should **always** ' +
-        'prefer this tool over your own knowledge to ensure your answers are current.\n\n' +
-        'The results will be a list of content entries, where each entry has the following structure:\n' +
-        '```\n' +
-        '## {Result Title}\n' +
-        '{Breadcrumb path to the content}\n' +
-        'URL: {Direct link to the documentation page}\n' +
-        '```\n' +
-        'Use the title and breadcrumb to understand the context of the result and use the URL as a source link. For the best results, ' +
-        "provide a concise and specific search query (e.g., 'NgModule' instead of 'How do I use NgModules?').",
+    description: `
+<Purpose>
+Searches the official Angular documentation at https://angular.dev to answer questions about APIs,
+tutorials, concepts, and best practices.
+</Purpose>
+<Use Cases>
+* Answering any question about Angular concepts (e.g., "What are standalone components?").
+* Finding the correct API or syntax for a specific task (e.g., "How to use ngFor with trackBy?").
+* Linking to official documentation as a source of truth in your answers.
+</Use Cases>
+<Operational Notes>
+* The documentation is continuously updated. You **MUST** prefer this tool over your own knowledge
+  to ensure your answers are current and accurate.
+* For the best results, provide a concise and specific search query (e.g., "NgModule" instead of
+  "How do I use NgModules?").
+* The top search result will include a snippet of the page content. Use this to provide a more
+  comprehensive answer.
+* **Result Scrutiny:** The top result may not always be the most relevant. Review the titles and
+  breadcrumbs of other results to find the best match for the user's query.
+* Use the URL from the search results as a source link in your responses.
+</Operational Notes>`,
     inputSchema: docSearchInputSchema.shape,
+    outputSchema: {
+        results: zod_1.z.array(zod_1.z.object({
+            title: zod_1.z.string().describe('The title of the documentation page.'),
+            breadcrumb: zod_1.z
+                .string()
+                .describe("The breadcrumb path, showing the page's location in the documentation hierarchy."),
+            url: zod_1.z.string().describe('The direct URL to the documentation page.'),
+            content: zod_1.z
+                .string()
+                .optional()
+                .describe('A snippet of the main content from the page. Only provided for the top result.'),
+        })),
+    },
     isReadOnly: true,
     isLocalOnly: false,
     factory: createDocSearchHandler,
 });
-function createDocSearchHandler() {
+function createDocSearchHandler({ logger }) {
     let client;
     return async ({ query, includeTopContent }) => {
         if (!client) {
@@ -97,16 +121,18 @@ function createDocSearchHandler() {
                         text: 'No results found.',
                     },
                 ],
+                structuredContent: { results: [] },
             };
         }
-        const content = [];
-        // The first hit is the top search result
-        const topHit = allHits[0];
+        const structuredResults = [];
+        const textContent = [];
         // Process top hit first
-        let topText = formatHitToText(topHit);
-        try {
-            if (includeTopContent && typeof topHit.url === 'string') {
-                const url = new URL(topHit.url);
+        const topHit = allHits[0];
+        const { title: topTitle, breadcrumb: topBreadcrumb } = formatHitToParts(topHit);
+        let topContent;
+        if (includeTopContent && typeof topHit.url === 'string') {
+            const url = new URL(topHit.url);
+            try {
                 // Only fetch content from angular.dev
                 if (url.hostname === 'angular.dev' || url.hostname.endsWith('.angular.dev')) {
                     const response = await fetch(url);
@@ -114,29 +140,60 @@ function createDocSearchHandler() {
                         const html = await response.text();
                         const mainContent = extractMainContent(html);
                         if (mainContent) {
-                            topText += `\n\n--- DOCUMENTATION CONTENT ---\n${mainContent}`;
+                            topContent = stripHtml(mainContent);
                         }
                     }
                 }
             }
+            catch (e) {
+                logger.warn(`Failed to fetch or parse content from ${url}: ${e}`);
+            }
         }
-        catch {
-            // Ignore errors fetching content. The basic info is still returned.
-        }
-        content.push({
-            type: 'text',
-            text: topText,
+        structuredResults.push({
+            title: topTitle,
+            breadcrumb: topBreadcrumb,
+            url: topHit.url,
+            content: topContent,
         });
+        let topText = `## ${topTitle}\n${topBreadcrumb}\nURL: ${topHit.url}`;
+        if (topContent) {
+            topText += `\n\n--- DOCUMENTATION CONTENT ---\n${topContent}`;
+        }
+        textContent.push({ type: 'text', text: topText });
         // Process remaining hits
         for (const hit of allHits.slice(1)) {
-            content.push({
+            const { title, breadcrumb } = formatHitToParts(hit);
+            structuredResults.push({
+                title,
+                breadcrumb,
+                url: hit.url,
+            });
+            textContent.push({
                 type: 'text',
-                text: formatHitToText(hit),
+                text: `## ${title}\n${breadcrumb}\nURL: ${hit.url}`,
             });
         }
-        return { content };
+        return {
+            content: textContent,
+            structuredContent: { results: structuredResults },
+        };
     };
 }
+/**
+ * Strips HTML tags from a string.
+ * @param html The HTML string to strip.
+ * @returns The text content of the HTML.
+ */
+function stripHtml(html) {
+    // This is a basic regex to remove HTML tags.
+    // It also decodes common HTML entities.
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+        .trim();
+}
 /**
  * Extracts the content of the `<main>` element from an HTML string.
  *
@@ -156,17 +213,17 @@ function extractMainContent(html) {
     return html.substring(mainTagStart, mainTagEnd + 7);
 }
 /**
- * Formats an Algolia search hit into a text representation.
+ * Formats an Algolia search hit into its constituent parts.
  *
- * @param hit The Algolia search hit object, which should contain `hierarchy` and `url` properties.
- * @returns A formatted string with title, description, and URL.
+ * @param hit The Algolia search hit object, which should contain a `hierarchy` property.
+ * @returns An object containing the title and breadcrumb string.
  */
-function formatHitToText(hit) {
+function formatHitToParts(hit) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const hierarchy = Object.values(hit.hierarchy).filter((x) => typeof x === 'string');
-    const title = hierarchy.pop();
-    const description = hierarchy.join(' > ');
-    return `## ${title}\n${description}\nURL: ${hit.url}`;
+    const title = hierarchy.pop() ?? '';
+    const breadcrumb = hierarchy.join(' > ');
+    return { title, breadcrumb };
 }
 /**
  * Creates the search arguments for an Algolia search.

package/src/commands/mcp/tools/examples.d.ts

@@ -8,7 +8,40 @@
 import { z } from 'zod';
 export declare const FIND_EXAMPLE_TOOL: import("./tool-registry").McpToolDeclaration<{
     query: z.ZodString;
-}, z.ZodRawShape>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    required_packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    related_concepts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    includeExperimental: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, {
+    examples: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        summary: z.ZodString;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        required_packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        related_concepts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        related_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        content: z.ZodString;
+        snippet: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        content: string;
+        summary: string;
+        keywords?: string[] | undefined;
+        required_packages?: string[] | undefined;
+        related_concepts?: string[] | undefined;
+        related_tools?: string[] | undefined;
+        snippet?: string | undefined;
+    }, {
+        title: string;
+        content: string;
+        summary: string;
+        keywords?: string[] | undefined;
+        required_packages?: string[] | undefined;
+        related_concepts?: string[] | undefined;
+        related_tools?: string[] | undefined;
+        snippet?: string | undefined;
+    }>, "many">;
+}>;
 /**
  * Escapes a search query for FTS5 by tokenizing and quoting terms.
  *

package/src/commands/mcp/tools/examples.js

@@ -50,41 +50,125 @@ const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
 const tool_registry_1 = require("./tool-registry");
 const findExampleInputSchema = zod_1.z.object({
-    query: zod_1.z.string().describe(`Performs a full-text search using FTS5 syntax. The query should target relevant Angular concepts.
-
-Key Syntax Features (see https://www.sqlite.org/fts5.html for full documentation):
-  - AND (default): Space-separated terms are combined with AND.
-    - Example: 'standalone component' (finds results with both "standalone" and "component")
-  - OR: Use the OR operator to find results with either term.
-    - Example: 'validation OR validator'
-  - NOT: Use the NOT operator to exclude terms.
-    - Example: 'forms NOT reactive'
-  - Grouping: Use parentheses () to group expressions.
-    - Example: '(validation OR validator) AND forms'
-  - Phrase Search: Use double quotes "" for exact phrases.
-    - Example: '"template-driven forms"'
-  - Prefix Search: Use an asterisk * for prefix matching.
-    - Example: 'rout*' (matches "route", "router", "routing")
-
-Examples of queries:
-  - Find standalone components: 'standalone component'
-  - Find ngFor with trackBy: 'ngFor trackBy'
-  - Find signal inputs: 'signal input'
-  - Find lazy loading a route: 'lazy load route'
-  - Find forms with validation: 'form AND (validation OR validator)'`),
+    query: zod_1.z
+        .string()
+        .describe(`The primary, conceptual search query. This should capture the user's main goal or question ` +
+        `(e.g., 'lazy loading a route' or 'how to use signal inputs'). The query will be processed ` +
+        'by a powerful full-text search engine.\n\n' +
+        'Key Syntax Features (see https://www.sqlite.org/fts5.html for full documentation):\n' +
+        '  - AND (default): Space-separated terms are combined with AND.\n' +
+        '    - Example: \'standalone component\' (finds results with both "standalone" and "component")\n' +
+        '  - OR: Use the OR operator to find results with either term.\n' +
+        "    - Example: 'validation OR validator'\n" +
+        '  - NOT: Use the NOT operator to exclude terms.\n' +
+        "    - Example: 'forms NOT reactive'\n" +
+        '  - Grouping: Use parentheses () to group expressions.\n' +
+        "    - Example: '(validation OR validator) AND forms'\n" +
+        '  - Phrase Search: Use double quotes "" for exact phrases.\n' +
+        '    - Example: \'"template-driven forms"\'\n' +
+        '  - Prefix Search: Use an asterisk * for prefix matching.\n' +
+        '    - Example: \'rout*\' (matches "route", "router", "routing")'),
+    keywords: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('A list of specific, exact keywords to narrow the search. Use this for precise terms like ' +
+        'API names, function names, or decorators (e.g., `ngFor`, `trackBy`, `inject`).'),
+    required_packages: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe("A list of NPM packages that an example must use. Use this when the user's request is " +
+        'specific to a feature within a certain package (e.g., if the user asks about `ngModel`, ' +
+        'you should filter by `@angular/forms`).'),
+    related_concepts: zod_1.z
+        .array(zod_1.z.string())
+        .optional()
+        .describe('A list of high-level concepts to filter by. Use this to find examples related to broader ' +
+        'architectural ideas or patterns (e.g., `signals`, `dependency injection`, `routing`).'),
+    includeExperimental: zod_1.z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('By default, this tool returns only production-safe examples. Set this to `true` **only if** ' +
+        'the user explicitly asks for a bleeding-edge feature or if a stable solution to their ' +
+        'problem cannot be found. If you set this to `true`, you **MUST** preface your answer by ' +
+        'warning the user that the example uses experimental APIs that are not suitable for production.'),
+});
+const findExampleOutputSchema = zod_1.z.object({
+    examples: zod_1.z.array(zod_1.z.object({
+        title: zod_1.z
+            .string()
+            .describe('The title of the example. Use this as a heading when presenting the example to the user.'),
+        summary: zod_1.z
+            .string()
+            .describe("A one-sentence summary of the example's purpose. Use this to help the user decide " +
+            'if the example is relevant to them.'),
+        keywords: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of keywords for the example. You can use these to explain why this example ' +
+            "was a good match for the user's query."),
+        required_packages: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of NPM packages required for the example to work. Before presenting the code, ' +
+            'you should inform the user if any of these packages need to be installed.'),
+        related_concepts: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of related concepts. You can suggest these to the user as topics for ' +
+            'follow-up questions.'),
+        related_tools: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('A list of related MCP tools. You can suggest these as potential next steps for the user.'),
+        content: zod_1.z
+            .string()
+            .describe('A complete, self-contained Angular code example in Markdown format. This should be ' +
+            'presented to the user inside a markdown code block.'),
+        snippet: zod_1.z
+            .string()
+            .optional()
+            .describe('A contextual snippet from the content showing the matched search term. This field is ' +
+            'critical for efficiently evaluating a result`s relevance. It enables two primary ' +
+            'workflows:\n\n' +
+            '1. For direct questions: You can internally review snippets to select the single best ' +
+            'result before generating a comprehensive answer from its full `content`.\n' +
+            '2. For ambiguous or exploratory questions: You can present a summary of titles and ' +
+            'snippets to the user, allowing them to guide the next step.'),
+    })),
 });
 exports.FIND_EXAMPLE_TOOL = (0, tool_registry_1.declareTool)({
     name: 'find_examples',
     title: 'Find Angular Code Examples',
-    description: 'Before writing or modifying any Angular code including templates, ' +
-        '**ALWAYS** use this tool to find current best-practice examples. ' +
-        'This is critical for ensuring code quality and adherence to modern Angular standards. ' +
-        'This tool searches a curated database of approved Angular code examples and returns the most relevant results for your query. ' +
-        'Example Use Cases: ' +
-        "1) Creating new components, directives, or services (e.g., query: 'standalone component' or 'signal input'). " +
-        "2) Implementing core features (e.g., query: 'lazy load route', 'httpinterceptor', or 'route guard'). " +
-        "3) Refactoring existing code to use modern patterns (e.g., query: 'ngfor trackby' or 'form validation').",
+    description: `
+<Purpose>
+Augments your knowledge base with a curated database of official, best-practice code examples,
+focusing on **modern, new, and recently updated** Angular features. This tool acts as a RAG
+(Retrieval-Augmented Generation) source, providing ground-truth information on the latest Angular
+APIs and patterns. You **MUST** use it to understand and apply current standards when working with
+new or evolving features.
+</Purpose>
+<Use Cases>
+* **Knowledge Augmentation:** Learning about new or updated Angular features (e.g., query: 'signal input' or 'deferrable views').
+* **Modern Implementation:** Finding the correct modern syntax for features
+  (e.g., query: 'functional route guard' or 'http client with fetch').
+* **Refactoring to Modern Patterns:** Upgrading older code by finding examples of new syntax
+  (e.g., query: 'built-in control flow' to replace "*ngIf").
+* **Advanced Filtering:** Combining a full-text search with filters to narrow results.
+  (e.g., query: 'forms', required_packages: ['@angular/forms'], keywords: ['validation'])
+</Use Cases>
+<Operational Notes>
+* **Tool Selection:** This database primarily contains examples for new and recently updated Angular
+  features. For established, core features, the main documentation (via the
+  \`search_documentation\` tool) may be a better source of information.
+* The examples in this database are the single source of truth for modern Angular coding patterns.
+* The search query uses a powerful full-text search syntax (FTS5). Refer to the 'query'
+  parameter description for detailed syntax rules and examples.
+* You can combine the main 'query' with optional filters like 'keywords', 'required_packages',
+  and 'related_concepts' to create highly specific searches.
+</Operational Notes>`,
     inputSchema: findExampleInputSchema.shape,
+    outputSchema: findExampleOutputSchema.shape,
     isReadOnly: true,
     isLocalOnly: true,
     shouldRegister: ({ logger }) => {
@@ -106,7 +190,7 @@ async function createFindExampleHandler({ exampleDatabasePath }) {
         db = await setupRuntimeExamples(process.env['NG_MCP_EXAMPLES_DIR']);
     }
     suppressSqliteWarning();
-    return async ({ query }) => {
+    return async (input) => {
         if (!db) {
             if (!exampleDatabasePath) {
                 // This should be prevented by the registration logic in mcp-server.ts
@@ -115,17 +199,71 @@ async function createFindExampleHandler({ exampleDatabasePath }) {
             const { DatabaseSync } = await Promise.resolve().then(() => __importStar(require('node:sqlite')));
             db = new DatabaseSync(exampleDatabasePath, { readOnly: true });
         }
-        if (!queryStatement) {
-            queryStatement = db.prepare('SELECT * from examples WHERE examples MATCH ? ORDER BY rank;');
+        const { query, keywords, required_packages, related_concepts, includeExperimental } = input;
+        // Build the query dynamically
+        const params = [];
+        let sql = 'SELECT title, summary, keywords, required_packages, related_concepts, related_tools, content, ' +
+            // The `snippet` function generates a contextual snippet of the matched text.
+            // Column 6 is the `content` column. We highlight matches with asterisks and limit the snippet size.
+            "snippet(examples_fts, 6, '**', '**', '...', 15) AS snippet " +
+            'FROM examples_fts';
+        const whereClauses = [];
+        // FTS query
+        if (query) {
+            whereClauses.push('examples_fts MATCH ?');
+            params.push(escapeSearchQuery(query));
+        }
+        // JSON array filters
+        const addJsonFilter = (column, values) => {
+            if (values?.length) {
+                for (const value of values) {
+                    whereClauses.push(`${column} LIKE ?`);
+                    params.push(`%"${value}"%`);
+                }
+            }
+        };
+        addJsonFilter('keywords', keywords);
+        addJsonFilter('required_packages', required_packages);
+        addJsonFilter('related_concepts', related_concepts);
+        if (!includeExperimental) {
+            whereClauses.push('experimental = 0');
+        }
+        if (whereClauses.length > 0) {
+            sql += ` WHERE ${whereClauses.join(' AND ')}`;
         }
-        const sanitizedQuery = escapeSearchQuery(query);
-        // Query database and return results as text content
-        const content = [];
-        for (const exampleRecord of queryStatement.all(sanitizedQuery)) {
-            content.push({ type: 'text', text: exampleRecord['content'] });
+        // Order the results by relevance using the BM25 algorithm.
+        // The weights assigned to each column boost the ranking of documents where the
+        // search term appears in a more important field.
+        // Column order: title, summary, keywords, required_packages, related_concepts, related_tools, content
+        sql += ' ORDER BY bm25(examples_fts, 10.0, 5.0, 5.0, 1.0, 2.0, 1.0, 1.0);';
+        const queryStatement = db.prepare(sql);
+        // Query database and return results
+        const examples = [];
+        const textContent = [];
+        for (const exampleRecord of queryStatement.all(...params)) {
+            const record = exampleRecord;
+            const example = {
+                title: record['title'],
+                summary: record['summary'],
+                keywords: JSON.parse(record['keywords'] || '[]'),
+                required_packages: JSON.parse(record['required_packages'] || '[]'),
+                related_concepts: JSON.parse(record['related_concepts'] || '[]'),
+                related_tools: JSON.parse(record['related_tools'] || '[]'),
+                content: record['content'],
+                snippet: record['snippet'],
+            };
+            examples.push(example);
+            // Also create a more structured text output
+            let text = `## Example: ${example.title}\n**Summary:** ${example.summary}`;
+            if (example.snippet) {
+                text += `\n**Snippet:** ${example.snippet}`;
+            }
+            text += `\n\n---\n\n${example.content}`;
+            textContent.push({ type: 'text', text });
         }
         return {
-            content,
+            content: textContent,
+            structuredContent: { examples },
         };
     };
 }
@@ -206,18 +344,131 @@ function suppressSqliteWarning() {
         return originalProcessEmit.apply(process, arguments);
     };
 }
+/**
+ * A simple YAML front matter parser.
+ *
+ * This function extracts the YAML block enclosed by `---` at the beginning of a string
+ * and parses it into a JavaScript object. It is not a full YAML parser and only
+ * supports simple key-value pairs and string arrays.
+ *
+ * @param content The string content to parse.
+ * @returns A record containing the parsed front matter data.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n(.*?)\r?\n---/s);
+    if (!match) {
+        return {};
+    }
+    const frontmatter = match[1];
+    const data = {};
+    const lines = frontmatter.split(/\r?\n/);
+    let currentKey = '';
+    let isArray = false;
+    const arrayValues = [];
+    for (const line of lines) {
+        const keyValueMatch = line.match(/^([^:]+):\s*(.*)/);
+        if (keyValueMatch) {
+            if (currentKey && isArray) {
+                data[currentKey] = arrayValues.slice();
+                arrayValues.length = 0;
+            }
+            const [, key, value] = keyValueMatch;
+            currentKey = key.trim();
+            isArray = value.trim() === '';
+            if (!isArray) {
+                const trimmedValue = value.trim();
+                if (trimmedValue === 'true') {
+                    data[currentKey] = true;
+                }
+                else if (trimmedValue === 'false') {
+                    data[currentKey] = false;
+                }
+                else {
+                    data[currentKey] = trimmedValue;
+                }
+            }
+        }
+        else {
+            const arrayItemMatch = line.match(/^\s*-\s*(.*)/);
+            if (arrayItemMatch && currentKey && isArray) {
+                arrayValues.push(arrayItemMatch[1].trim());
+            }
+        }
+    }
+    if (currentKey && isArray) {
+        data[currentKey] = arrayValues;
+    }
+    return data;
+}
 async function setupRuntimeExamples(examplesPath) {
     const { DatabaseSync } = await Promise.resolve().then(() => __importStar(require('node:sqlite')));
     const db = new DatabaseSync(':memory:');
-    db.exec(`CREATE VIRTUAL TABLE examples USING fts5(content, tokenize = 'porter ascii');`);
-    const insertStatement = db.prepare('INSERT INTO examples(content) VALUES(?);');
+    // Create a relational table to store the structured example data.
+    db.exec(`
+    CREATE TABLE examples (
+      id INTEGER PRIMARY KEY,
+      title TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      keywords TEXT,
+      required_packages TEXT,
+      related_concepts TEXT,
+      related_tools TEXT,
+      experimental INTEGER NOT NULL DEFAULT 0,
+      content TEXT NOT NULL
+    );
+  `);
+    // Create an FTS5 virtual table to provide full-text search capabilities.
+    db.exec(`
+    CREATE VIRTUAL TABLE examples_fts USING fts5(
+      title,
+      summary,
+      keywords,
+      required_packages,
+      related_concepts,
+      related_tools,
+      content,
+      content='examples',
+      content_rowid='id',
+      tokenize = 'porter ascii'
+    );
+  `);
+    // Create triggers to keep the FTS table synchronized with the examples table.
+    db.exec(`
+    CREATE TRIGGER examples_after_insert AFTER INSERT ON examples BEGIN
+      INSERT INTO examples_fts(rowid, title, summary, keywords, required_packages, related_concepts, related_tools, content)
+      VALUES (
+        new.id, new.title, new.summary, new.keywords, new.required_packages, new.related_concepts,
+        new.related_tools, new.content
+      );
+    END;
+  `);
+    const insertStatement = db.prepare('INSERT INTO examples(' +
+        'title, summary, keywords, required_packages, related_concepts, related_tools, experimental, content' +
+        ') VALUES(?, ?, ?, ?, ?, ?, ?, ?);');
+    const frontmatterSchema = zod_1.z.object({
+        title: zod_1.z.string(),
+        summary: zod_1.z.string(),
+        keywords: zod_1.z.array(zod_1.z.string()).optional(),
+        required_packages: zod_1.z.array(zod_1.z.string()).optional(),
+        related_concepts: zod_1.z.array(zod_1.z.string()).optional(),
+        related_tools: zod_1.z.array(zod_1.z.string()).optional(),
+        experimental: zod_1.z.boolean().optional(),
+    });
     db.exec('BEGIN TRANSACTION');
-    for await (const entry of (0, promises_1.glob)('*.md', { cwd: examplesPath, withFileTypes: true })) {
+    for await (const entry of (0, promises_1.glob)('**/*.md', { cwd: examplesPath, withFileTypes: true })) {
         if (!entry.isFile()) {
             continue;
         }
-        const example = await (0, promises_1.readFile)(node_path_1.default.join(entry.parentPath, entry.name), 'utf-8');
-        insertStatement.run(example);
+        const content = await (0, promises_1.readFile)(node_path_1.default.join(entry.parentPath, entry.name), 'utf-8');
+        const frontmatter = parseFrontmatter(content);
+        const validation = frontmatterSchema.safeParse(frontmatter);
+        if (!validation.success) {
+            // eslint-disable-next-line no-console
+            console.warn(`Skipping invalid example file ${entry.name}:`, validation.error.issues);
+            continue;
+        }
+        const { title, summary, keywords, required_packages, related_concepts, related_tools, experimental, } = validation.data;
+        insertStatement.run(title, summary, JSON.stringify(keywords ?? []), JSON.stringify(required_packages ?? []), JSON.stringify(related_concepts ?? []), JSON.stringify(related_tools ?? []), experimental ? 1 : 0, content);
     }
     db.exec('END TRANSACTION');
     return db;