|
| 1 | +import {readFileSync} from 'node:fs'; |
| 2 | +import {join} from 'node:path'; |
| 3 | +import {AGENT_ENTRIES, type AgentEntry} from '../../packages/devtools/src/config.ts'; |
| 4 | +import {createSlugger, headingText, slugify} from './src/app/utils/heading-slug.ts'; |
| 5 | + |
| 6 | +/** |
| 7 | + * Builds `src/content/agents/tool-index.md` from `AGENT_ENTRIES` in |
| 8 | + * `packages/devtools/src/config.ts`, the list the server registers its agent |
| 9 | + * tools and resources from. `scripts/docs-agent-tools.mjs` writes the page, |
| 10 | + * and `agent-tool-index.spec.ts` fails when the committed page is stale or a |
| 11 | + * tool has no place in `tools.md` or `resources.md`. |
| 12 | + */ |
| 13 | + |
| 14 | +export const TOOL_INDEX_PATH = 'src/content/agents/tool-index.md'; |
| 15 | + |
| 16 | +const INSPECTOR_LABELS: Record<string, string> = { |
| 17 | + components: 'Components', |
| 18 | + signals: 'Signals', |
| 19 | + injectors: 'Injectors', |
| 20 | + ngrx: 'NgRx Store', |
| 21 | + tanstackQuery: 'TanStack Query', |
| 22 | + forms: 'Forms', |
| 23 | + router: 'Router', |
| 24 | + pipes: 'Pipes', |
| 25 | + http: 'SSR & HTTP', |
| 26 | + analog: 'Analog', |
| 27 | + capacitor: 'Capacitor', |
| 28 | + errors: 'Errors', |
| 29 | + plugins: 'Plugins', |
| 30 | +}; |
| 31 | + |
| 32 | +/** Sections that mention every tool in passing, so they are not where a tool is described. */ |
| 33 | +const PASSING_SECTIONS = new Set(['before-you-call-a-tool', 'renamed-tools', 'shared-state']); |
| 34 | + |
| 35 | +interface Heading { |
| 36 | + slug: string; |
| 37 | + text: string; |
| 38 | + section: string; |
| 39 | +} |
| 40 | + |
| 41 | +/** Each line's heading, with slugs computed the way the link guard and the TOC do. */ |
| 42 | +function headingsByLine(markdown: string): (Heading | null)[] { |
| 43 | + const slug = createSlugger(); |
| 44 | + const out: (Heading | null)[] = []; |
| 45 | + let current: Heading | null = null; |
| 46 | + let section = ''; |
| 47 | + let fence: string | null = null; |
| 48 | + for (const line of markdown.split(/\r?\n/)) { |
| 49 | + const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1]; |
| 50 | + if (marker && (fence === null || marker.startsWith(fence))) { |
| 51 | + fence = fence === null ? marker : null; |
| 52 | + } else if (fence === null) { |
| 53 | + const m = /^ {0,3}(#{1,6})\s+(.+?)\s*$/.exec(line); |
| 54 | + if (m) { |
| 55 | + const text = headingText(m[2]); |
| 56 | + const id = m[1].length === 1 ? slugify(text) : slug(text); |
| 57 | + if (m[1].length <= 2) section = id; |
| 58 | + current = {slug: id, text, section}; |
| 59 | + } |
| 60 | + } |
| 61 | + out.push(current); |
| 62 | + } |
| 63 | + return out; |
| 64 | +} |
| 65 | + |
| 66 | +/** The heading a name is described under: its own heading, or the first section that names it. */ |
| 67 | +export function findSection(markdown: string, name: string): Heading | null { |
| 68 | + const lines = markdown.split(/\r?\n/); |
| 69 | + const headings = headingsByLine(markdown); |
| 70 | + const own = headings.find((h) => h?.text === name); |
| 71 | + if (own) return own; |
| 72 | + const needle = '`' + name + '`'; |
| 73 | + // The header row of the table each line is in, so a row in a table of limits doesn't count. |
| 74 | + const tableHeaders: string[] = []; |
| 75 | + lines.forEach((line, i) => { |
| 76 | + const inTable = line.startsWith('|'); |
| 77 | + tableHeaders.push(!inTable ? '' : lines[i - 1]?.startsWith('|') ? tableHeaders[i - 1] : line); |
| 78 | + }); |
| 79 | + const isLimits = (i: number) => /^\|\s*\S+\s*\|\s*(Cap|Limit)\s*\|/.test(tableHeaders[i]); |
| 80 | + // A table row that defines it, then a paragraph that starts with it, then any mention. |
| 81 | + const tests = [ |
| 82 | + (line: string, i: number) => line.startsWith(`| ${needle} `) && !isLimits(i), |
| 83 | + (line: string) => line.startsWith(needle), |
| 84 | + (line: string) => line.includes(needle), |
| 85 | + ]; |
| 86 | + for (const test of tests) { |
| 87 | + for (let i = 0; i < lines.length; i++) { |
| 88 | + const heading = headings[i]; |
| 89 | + if (!heading || PASSING_SECTIONS.has(heading.section)) continue; |
| 90 | + if (test(lines[i], i)) return heading; |
| 91 | + } |
| 92 | + } |
| 93 | + return null; |
| 94 | +} |
| 95 | + |
| 96 | +function tier(entry: AgentEntry): string { |
| 97 | + const base = entry.safety ?? 'read'; |
| 98 | + return entry.readOnlyVariant ? `${base} (read under \`agent.readOnly\`)` : base; |
| 99 | +} |
| 100 | + |
| 101 | +function inspectorOf(entry: AgentEntry): string { |
| 102 | + const first = entry.inspectors?.[0]; |
| 103 | + if (!first) return 'Shared'; |
| 104 | + return entry.anyInspector ? `${INSPECTOR_LABELS[first]} and others` : INSPECTOR_LABELS[first]; |
| 105 | +} |
| 106 | + |
| 107 | +function turnedOffBy(entry: AgentEntry): string { |
| 108 | + if (!entry.inspectors?.length) return 'None'; |
| 109 | + const keys = entry.anyInspector ? entry.inspectors : entry.inspectors.slice(0, 1); |
| 110 | + const parts = keys.map((key) => `\`inspectors.${key}\``); |
| 111 | + const joined = entry.anyInspector ? `${parts.join(', ')} (all of them)` : parts[0]; |
| 112 | + return entry.actions?.length |
| 113 | + ? `${joined}, or blocking ${entry.actions.map((a) => `\`actions.${a}\``).join(' and ')}` |
| 114 | + : joined; |
| 115 | +} |
| 116 | + |
| 117 | +export interface IndexProblem { |
| 118 | + name: string; |
| 119 | + problem: string; |
| 120 | +} |
| 121 | + |
| 122 | +/** The markdown of the page, and the entries that have no place in the docs. */ |
| 123 | +export function renderToolIndex(docsRoot: string): {markdown: string; problems: IndexProblem[]} { |
| 124 | + const tools = readFileSync(join(docsRoot, 'src/content/agents/tools.md'), 'utf8'); |
| 125 | + const resources = readFileSync(join(docsRoot, 'src/content/agents/resources.md'), 'utf8'); |
| 126 | + const problems: IndexProblem[] = []; |
| 127 | + const toolRows: string[] = []; |
| 128 | + const resourceRows: string[] = []; |
| 129 | + |
| 130 | + const order = ['Shared', ...Object.values(INSPECTOR_LABELS)]; |
| 131 | + const entries = Object.entries(AGENT_ENTRIES).sort( |
| 132 | + ([a, x], [b, y]) => |
| 133 | + order.indexOf(inspectorOf(x).replace(/ and others$/, '')) - |
| 134 | + order.indexOf(inspectorOf(y).replace(/ and others$/, '')) || a.localeCompare(b), |
| 135 | + ); |
| 136 | + |
| 137 | + for (const [name, entry] of entries) { |
| 138 | + const isResource = entry.kind === 'resource'; |
| 139 | + const page = isResource ? './resources.md' : './tools.md'; |
| 140 | + const section = findSection(isResource ? resources : tools, name); |
| 141 | + if (!section) { |
| 142 | + problems.push({name, problem: `not named in ${isResource ? 'resources.md' : 'tools.md'}`}); |
| 143 | + continue; |
| 144 | + } |
| 145 | + const link = `[${section.text}](${page}#${section.slug})`; |
| 146 | + const stdio = entry.page ? 'No' : 'Yes'; |
| 147 | + if (isResource) { |
| 148 | + resourceRows.push(`| \`pangular:${name}\` | ${inspectorOf(entry)} | ${stdio} | ${link} |`); |
| 149 | + } else { |
| 150 | + toolRows.push( |
| 151 | + `| \`${name}\` | ${inspectorOf(entry)} | ${tier(entry)} | ${stdio} | ${turnedOffBy(entry)} | ${link} |`, |
| 152 | + ); |
| 153 | + } |
| 154 | + } |
| 155 | + |
| 156 | + const markdown = `--- |
| 157 | +title: Tool index |
| 158 | +description: Every built-in agent tool and resource with its inspector, safety tier, transports and the option that turns it off, generated from the server's own list. |
| 159 | +--- |
| 160 | +
|
| 161 | +<ngmd-hero title="Tool index" gradient> |
| 162 | + Every built-in agent tool and resource on one page, generated from the list the server registers them from. |
| 163 | +</ngmd-hero> |
| 164 | +
|
| 165 | +# Tool index |
| 166 | +
|
| 167 | +This page is generated from \`AGENT_ENTRIES\` in \`packages/devtools/src/config.ts\`, the list the server registers its tools and resources from, so it can't drift from the code. [Tools](./tools.md) and [Resources](./resources.md) describe the arguments and answers of each one. Run \`pnpm docs:agent-tools\` after you add or change an entry. |
| 168 | +
|
| 169 | +Clients see each tool as \`pangular_<name>\`. See [Names](./tools.md#names). Plugin tools, \`pangular:plugin:<id>:<tool>\`, come from the plugins and are not listed here. See [A plugin's own tools](./tools.md#a-plugin-s-own-tools). |
| 170 | +
|
| 171 | +## Columns |
| 172 | +
|
| 173 | +| Column | Meaning | |
| 174 | +| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | |
| 175 | +| Inspector | The inspector the entry belongs to. Shared entries belong to none. | |
| 176 | +| Tier | \`read\`, \`action\` or \`destructive\`. See [Action tools](./tools.md#action-tools). | |
| 177 | +| Over stdio | Whether the stdio server offers it. Entries that need a connected page, the app's dev server or the panel are HTTP only. | |
| 178 | +| Turned off by | The [configuration](../getting-started/configuration.md#inspectors-and-agent-tools) that removes it. \`agent.tools.<inspector>: false\` also hides an inspector's entries, and \`agent.readOnly\` drops the \`action\` and \`destructive\` tools. | |
| 179 | +
|
| 180 | +## Tools |
| 181 | +
|
| 182 | +| Tool | Inspector | Tier | Over stdio | Turned off by | Described in | |
| 183 | +| ---- | --------- | ---- | ---------- | ------------- | ------------ | |
| 184 | +${toolRows.join('\n')} |
| 185 | +
|
| 186 | +## Resources |
| 187 | +
|
| 188 | +| Resource | Inspector | Over stdio | Described in | |
| 189 | +| -------- | --------- | ---------- | ------------ | |
| 190 | +${resourceRows.join('\n')} |
| 191 | +
|
| 192 | +## Where to next |
| 193 | +
|
| 194 | +<ngmd-pill-row> |
| 195 | + <ngmd-pill href="/agents/tools" title="Tools"></ngmd-pill> |
| 196 | + <ngmd-pill href="/agents/resources" title="Resources"></ngmd-pill> |
| 197 | + <ngmd-pill href="/agents/recipes" title="Recipes for agents"></ngmd-pill> |
| 198 | +</ngmd-pill-row> |
| 199 | +`; |
| 200 | + return {markdown, problems}; |
| 201 | +} |
0 commit comments