@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/mcp-docs.mjs

@@ -1,168 +1,168 @@
-// The MCP server's `docs` tool: the bridge README, the UI kit README, the CLI README, the hawk-app.json schema and the showcase app (one
-// app that uses every feature), split into sections an assistant can search and read. Each source is found in the
-// app's own node_modules first (the bridge it really uses), then in this repo (when the CLI runs from source, so a
-// leftover packed copy can't be stale), then in the copy the CLI ships (docs/, copied on prepack).
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const CLI_DIR = fileURLToPath(new URL('..', import.meta.url));
-const REPO_DIR = join(CLI_DIR, '..', '..');
-const MAX_SECTION = 8000;
-
-const firstExisting = (...paths) => paths.find((p) => p && existsSync(p)) ?? null;
-
-/** Where each source is, for an app in `appDir`. */
-export function docSources(appDir) {
-    return {
-        bridge: firstExisting(
-            appDir && join(appDir, 'node_modules', '@bridgeline-digital', 'hawk-app-bridge', 'README.md'),
-            join(REPO_DIR, 'packages', 'bridge', 'README.md'),
-            join(CLI_DIR, 'docs', 'bridge', 'README.md'),
-        ),
-        ui: firstExisting(
-            appDir && join(appDir, 'node_modules', '@bridgeline-digital', 'hawk-app-ui', 'README.md'),
-            join(REPO_DIR, 'packages', 'ui', 'README.md'),
-            join(CLI_DIR, 'docs', 'ui', 'README.md'),
-        ),
-        cli: firstExisting(join(CLI_DIR, 'README.md')),
-        schema: firstExisting(join(REPO_DIR, 'schemas', 'hawk-app.schema.json'), join(CLI_DIR, 'schema', 'hawk-app.schema.json')),
-        showcase: firstExisting(join(REPO_DIR, 'examples', 'showcase'), join(CLI_DIR, 'docs', 'showcase')),
-    };
-}
-
-/** A Markdown file as one section per ## / ### heading, titled "<source>: <h2> > <h3>". */
-export function markdownSections(source, text) {
-    const sections = [];
-    let h2 = null;
-    let current = { title: `${source}: introduction`, lines: [] };
-    let fence = false;
-    for (const line of text.replace(/\r\n/g, '\n').split('\n')) {
-        if (/^\s*```/.test(line)) fence = !fence;
-        const heading = fence ? null : /^(#{2,3})\s+(.*)$/.exec(line);
-        if (heading) {
-            sections.push(current);
-            if (heading[1] === '##') h2 = heading[2].trim();
-            current = { title: `${source}: ${heading[1] === '##' ? h2 : `${h2} > ${heading[2].trim()}`}`, lines: [line] };
-        } else {
-            current.lines.push(line);
-        }
-    }
-    sections.push(current);
-    return sections.map((s) => ({ title: s.title, text: s.lines.join('\n').trim() })).filter((s) => s.text);
-}
-
-const DECLARATION = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\s+(\w+)|const\s+(\w+)\s*[:=])/;
-
-/** A source file of the showcase app as one section per top-level declaration (small files stay whole). */
-function codeSections(file, text) {
-    const lines = text.replace(/\r\n/g, '\n').split('\n');
-    if (text.length <= MAX_SECTION) return [{ title: `showcase: ${file}`, text: `// ${file}\n${text.trim()}` }];
-    const sections = [];
-    let current = { title: `showcase: ${file} (top)`, lines: [] };
-    for (const line of lines) {
-        const match = DECLARATION.exec(line);
-        if (!match) {
-            current.lines.push(line);
-            continue;
-        }
-        // The comment lines right above a declaration belong to it.
-        let start = current.lines.length;
-        while (start > 0 && /^(\/\*\*|\s\*|\/\/)/.test(current.lines[start - 1])) start--;
-        const comment = current.lines.splice(start);
-        sections.push(current);
-        current = { title: `showcase: ${file} > ${match[1] ?? match[2]}`, lines: [...comment, line] };
-    }
-    sections.push(current);
-    return sections.map((s) => ({ title: s.title, text: `// ${file}\n${s.lines.join('\n').trim()}` })).filter((s) => s.text.split('\n').length > 1);
-}
-
-/** The hawk-app.json schema as one section per field (plus one for the whole file's rules), so a search finds the field. */
-function schemaSections(text) {
-    let schema;
-    try {
-        schema = JSON.parse(text);
-    } catch {
-        return [{ title: 'schema: hawk-app.json', text: text.trim() }];
-    }
-    const { properties = {}, ...rest } = schema;
-    return [
-        { title: 'schema: hawk-app.json', text: `${schema.description ?? ''}\nFields: ${Object.keys(properties).join(', ')}.\n${JSON.stringify({ ...rest, $defs: undefined }, null, 2)}`.trim() },
-        ...Object.entries(properties).map(([name, definition]) => ({ title: `schema: ${name}`, text: `"${name}" in hawk-app.json:\n${JSON.stringify(definition, null, 2)}` })),
-    ];
-}
-
-function walk(dir) {
-    const files = [];
-    for (const name of readdirSync(dir)) {
-        if (name.startsWith('.') || name === 'node_modules' || name === 'dist') continue;
-        const full = join(dir, name);
-        if (statSync(full).isDirectory()) files.push(...walk(full));
-        else files.push(full);
-    }
-    return files;
-}
-
-/** Every section of every source: [{ title, text }]. */
-export function loadDocs(appDir) {
-    const sources = docSources(appDir);
-    const sections = [];
-    if (sources.bridge) sections.push(...markdownSections('bridge', readFileSync(sources.bridge, 'utf8')));
-    if (sources.ui) sections.push(...markdownSections('ui', readFileSync(sources.ui, 'utf8')));
-    if (sources.cli) sections.push(...markdownSections('cli', readFileSync(sources.cli, 'utf8')));
-    if (sources.schema) sections.push(...schemaSections(readFileSync(sources.schema, 'utf8')));
-    if (sources.showcase) {
-        for (const full of walk(sources.showcase)) {
-            const file = relative(sources.showcase, full).split(sep).join('/');
-            if (!/\.(tsx?|mjs|json|sql|md)$/.test(file) || file === 'package.json' || file.startsWith('tsconfig')) continue;
-            const text = readFileSync(full, 'utf8');
-            if (file === 'README.md') sections.push(...markdownSections('showcase', text));
-            else sections.push(...codeSections(file, text));
-        }
-    }
-    return sections;
-}
-
-const cap = (text) => (text.length > MAX_SECTION ? `${text.slice(0, MAX_SECTION)}\n… (cut at ${MAX_SECTION} characters; ask for this section by its title to read on with "offset")` : text);
-
-/**
- * The docs tool: no arguments lists the sections; `section` returns one by its title (from `offset` on, for long
- * ones); `query` returns the best matching sections (all of the query's words must appear).
- */
-export function searchDocs({ appDir, query, section, offset = 0, limit = 4 }) {
-    const sections = loadDocs(appDir);
-    if (!sections.length) return 'No documentation found. Is @bridgeline-digital/hawk-app-cli installed correctly?';
-
-    if (section) {
-        const found = sections.find((s) => s.title === section) ?? sections.find((s) => s.title.toLowerCase().includes(section.toLowerCase()));
-        if (!found) return `No section "${section}". Call docs without arguments to list them.`;
-        const rest = found.text.slice(offset);
-        return `# ${found.title}\n\n${rest.length > MAX_SECTION ? `${rest.slice(0, MAX_SECTION)}\n… (more: call again with offset ${offset + MAX_SECTION})` : rest}`;
-    }
-
-    if (query) {
-        const words = query.toLowerCase().split(/[^a-z0-9_:.@/-]+/).filter((w) => w.length > 1);
-        const scored = sections
-            .map((s) => {
-                const title = s.title.toLowerCase();
-                const text = s.text.toLowerCase();
-                if (!words.every((w) => title.includes(w) || text.includes(w))) return null;
-                // Title matches count most; mentions count up to 5 each, so a long section can't win on length alone.
-                const score = words.reduce((sum, w) => sum + (title.includes(w) ? 10 : 0) + Math.min(text.split(w).length - 1, 5), 0);
-                return { s, score };
-            })
-            .filter(Boolean)
-            .sort((a, b) => b.score - a.score)
-            .slice(0, limit);
-        if (!scored.length) return `Nothing matches all of "${query}". Try fewer or other words, or call docs without arguments to list the sections.`;
-        return scored.map(({ s }) => `# ${s.title}\n\n${cap(s.text)}`).join('\n\n---\n\n');
-    }
-
-    const bySource = new Map();
-    for (const s of sections) {
-        const source = s.title.split(':')[0];
-        bySource.set(source, [...(bySource.get(source) ?? []), s.title.slice(source.length + 2)]);
-    }
-    const labels = { bridge: 'Bridge (app.* APIs, scopes, errors)', cli: 'CLI (commands, deploy, review)', schema: 'hawk-app.json schema', showcase: 'Showcase app (working examples of every feature)' };
-    return [...bySource.entries()].map(([source, titles]) => `## ${labels[source] ?? source} — section titles start with "${source}: "\n${titles.map((t) => `- ${t}`).join('\n')}`).join('\n\n');
-}
+// The MCP server's `docs` tool: the bridge README, the UI kit README, the CLI README, the hawk-app.json schema and the showcase app (one
+// app that uses every feature), split into sections an assistant can search and read. Each source is found in the
+// app's own node_modules first (the bridge it really uses), then in this repo (when the CLI runs from source, so a
+// leftover packed copy can't be stale), then in the copy the CLI ships (docs/, copied on prepack).
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CLI_DIR = fileURLToPath(new URL('..', import.meta.url));
+const REPO_DIR = join(CLI_DIR, '..', '..');
+const MAX_SECTION = 8000;
+
+const firstExisting = (...paths) => paths.find((p) => p && existsSync(p)) ?? null;
+
+/** Where each source is, for an app in `appDir`. */
+export function docSources(appDir) {
+    return {
+        bridge: firstExisting(
+            appDir && join(appDir, 'node_modules', '@bridgeline-digital', 'hawk-app-bridge', 'README.md'),
+            join(REPO_DIR, 'packages', 'bridge', 'README.md'),
+            join(CLI_DIR, 'docs', 'bridge', 'README.md'),
+        ),
+        ui: firstExisting(
+            appDir && join(appDir, 'node_modules', '@bridgeline-digital', 'hawk-app-ui', 'README.md'),
+            join(REPO_DIR, 'packages', 'ui', 'README.md'),
+            join(CLI_DIR, 'docs', 'ui', 'README.md'),
+        ),
+        cli: firstExisting(join(CLI_DIR, 'README.md')),
+        schema: firstExisting(join(REPO_DIR, 'schemas', 'hawk-app.schema.json'), join(CLI_DIR, 'schema', 'hawk-app.schema.json')),
+        showcase: firstExisting(join(REPO_DIR, 'examples', 'showcase'), join(CLI_DIR, 'docs', 'showcase')),
+    };
+}
+
+/** A Markdown file as one section per ## / ### heading, titled "<source>: <h2> > <h3>". */
+export function markdownSections(source, text) {
+    const sections = [];
+    let h2 = null;
+    let current = { title: `${source}: introduction`, lines: [] };
+    let fence = false;
+    for (const line of text.replace(/\r\n/g, '\n').split('\n')) {
+        if (/^\s*```/.test(line)) fence = !fence;
+        const heading = fence ? null : /^(#{2,3})\s+(.*)$/.exec(line);
+        if (heading) {
+            sections.push(current);
+            if (heading[1] === '##') h2 = heading[2].trim();
+            current = { title: `${source}: ${heading[1] === '##' ? h2 : `${h2} > ${heading[2].trim()}`}`, lines: [line] };
+        } else {
+            current.lines.push(line);
+        }
+    }
+    sections.push(current);
+    return sections.map((s) => ({ title: s.title, text: s.lines.join('\n').trim() })).filter((s) => s.text);
+}
+
+const DECLARATION = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\s+(\w+)|const\s+(\w+)\s*[:=])/;
+
+/** A source file of the showcase app as one section per top-level declaration (small files stay whole). */
+function codeSections(file, text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    if (text.length <= MAX_SECTION) return [{ title: `showcase: ${file}`, text: `// ${file}\n${text.trim()}` }];
+    const sections = [];
+    let current = { title: `showcase: ${file} (top)`, lines: [] };
+    for (const line of lines) {
+        const match = DECLARATION.exec(line);
+        if (!match) {
+            current.lines.push(line);
+            continue;
+        }
+        // The comment lines right above a declaration belong to it.
+        let start = current.lines.length;
+        while (start > 0 && /^(\/\*\*|\s\*|\/\/)/.test(current.lines[start - 1])) start--;
+        const comment = current.lines.splice(start);
+        sections.push(current);
+        current = { title: `showcase: ${file} > ${match[1] ?? match[2]}`, lines: [...comment, line] };
+    }
+    sections.push(current);
+    return sections.map((s) => ({ title: s.title, text: `// ${file}\n${s.lines.join('\n').trim()}` })).filter((s) => s.text.split('\n').length > 1);
+}
+
+/** The hawk-app.json schema as one section per field (plus one for the whole file's rules), so a search finds the field. */
+function schemaSections(text) {
+    let schema;
+    try {
+        schema = JSON.parse(text);
+    } catch {
+        return [{ title: 'schema: hawk-app.json', text: text.trim() }];
+    }
+    const { properties = {}, ...rest } = schema;
+    return [
+        { title: 'schema: hawk-app.json', text: `${schema.description ?? ''}\nFields: ${Object.keys(properties).join(', ')}.\n${JSON.stringify({ ...rest, $defs: undefined }, null, 2)}`.trim() },
+        ...Object.entries(properties).map(([name, definition]) => ({ title: `schema: ${name}`, text: `"${name}" in hawk-app.json:\n${JSON.stringify(definition, null, 2)}` })),
+    ];
+}
+
+function walk(dir) {
+    const files = [];
+    for (const name of readdirSync(dir)) {
+        if (name.startsWith('.') || name === 'node_modules' || name === 'dist') continue;
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) files.push(...walk(full));
+        else files.push(full);
+    }
+    return files;
+}
+
+/** Every section of every source: [{ title, text }]. */
+export function loadDocs(appDir) {
+    const sources = docSources(appDir);
+    const sections = [];
+    if (sources.bridge) sections.push(...markdownSections('bridge', readFileSync(sources.bridge, 'utf8')));
+    if (sources.ui) sections.push(...markdownSections('ui', readFileSync(sources.ui, 'utf8')));
+    if (sources.cli) sections.push(...markdownSections('cli', readFileSync(sources.cli, 'utf8')));
+    if (sources.schema) sections.push(...schemaSections(readFileSync(sources.schema, 'utf8')));
+    if (sources.showcase) {
+        for (const full of walk(sources.showcase)) {
+            const file = relative(sources.showcase, full).split(sep).join('/');
+            if (!/\.(tsx?|mjs|json|sql|md)$/.test(file) || file === 'package.json' || file.startsWith('tsconfig')) continue;
+            const text = readFileSync(full, 'utf8');
+            if (file === 'README.md') sections.push(...markdownSections('showcase', text));
+            else sections.push(...codeSections(file, text));
+        }
+    }
+    return sections;
+}
+
+const cap = (text) => (text.length > MAX_SECTION ? `${text.slice(0, MAX_SECTION)}\n… (cut at ${MAX_SECTION} characters; ask for this section by its title to read on with "offset")` : text);
+
+/**
+ * The docs tool: no arguments lists the sections; `section` returns one by its title (from `offset` on, for long
+ * ones); `query` returns the best matching sections (all of the query's words must appear).
+ */
+export function searchDocs({ appDir, query, section, offset = 0, limit = 4 }) {
+    const sections = loadDocs(appDir);
+    if (!sections.length) return 'No documentation found. Is @bridgeline-digital/hawk-app-cli installed correctly?';
+
+    if (section) {
+        const found = sections.find((s) => s.title === section) ?? sections.find((s) => s.title.toLowerCase().includes(section.toLowerCase()));
+        if (!found) return `No section "${section}". Call docs without arguments to list them.`;
+        const rest = found.text.slice(offset);
+        return `# ${found.title}\n\n${rest.length > MAX_SECTION ? `${rest.slice(0, MAX_SECTION)}\n… (more: call again with offset ${offset + MAX_SECTION})` : rest}`;
+    }
+
+    if (query) {
+        const words = query.toLowerCase().split(/[^a-z0-9_:.@/-]+/).filter((w) => w.length > 1);
+        const scored = sections
+            .map((s) => {
+                const title = s.title.toLowerCase();
+                const text = s.text.toLowerCase();
+                if (!words.every((w) => title.includes(w) || text.includes(w))) return null;
+                // Title matches count most; mentions count up to 5 each, so a long section can't win on length alone.
+                const score = words.reduce((sum, w) => sum + (title.includes(w) ? 10 : 0) + Math.min(text.split(w).length - 1, 5), 0);
+                return { s, score };
+            })
+            .filter(Boolean)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        if (!scored.length) return `Nothing matches all of "${query}". Try fewer or other words, or call docs without arguments to list the sections.`;
+        return scored.map(({ s }) => `# ${s.title}\n\n${cap(s.text)}`).join('\n\n---\n\n');
+    }
+
+    const bySource = new Map();
+    for (const s of sections) {
+        const source = s.title.split(':')[0];
+        bySource.set(source, [...(bySource.get(source) ?? []), s.title.slice(source.length + 2)]);
+    }
+    const labels = { bridge: 'Bridge (app.* APIs, scopes, errors)', cli: 'CLI (commands, deploy, review)', schema: 'hawk-app.json schema', showcase: 'Showcase app (working examples of every feature)' };
+    return [...bySource.entries()].map(([source, titles]) => `## ${labels[source] ?? source} — section titles start with "${source}: "\n${titles.map((t) => `- ${t}`).join('\n')}`).join('\n\n');
+}