Skip to content

Commit 905701d

Browse files
authored
docs: add troubleshooting, platforms and setup pages, and merge the setup guides (#470)
Refs #373
1 parent 159d69c commit 905701d

77 files changed

Lines changed: 5045 additions & 689 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/devtools-docs/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Reviewers reject changes that break these.
2727
1. **No em dashes.** Use a period, comma or parentheses.
2828
2. **No first person** ("we", "our").
2929
3. **No future tense** ("will").
30-
4. **No time-relative claims** ("new", "recently", "upcoming", "now supports"). Use a sidebar `status` badge in `ngmd.config.ts` and the changelog instead.
30+
4. **No time-relative claims** ("new", "recently", "upcoming", "now supports"). Use a sidebar `status` badge in `ngmd.config.ts` and the changelog instead. A `new` or `updated` badge needs `until`: the minor after the release that ships the page (`until: '1.2.0'` for a page in 1.1), so it expires.
3131
5. **No comparisons with other devtools products.** Describe this project on its own terms.
3232
6. **No marketing words**: powerful, seamless, blazingly fast, simply, just, easy.
3333
7. **No invented features.** Every name, label, option, default, tool and argument must exist in the code.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ npm install -D @pangular-inspector/devtools
2020

2121
An Angular SSR server imports the hub when it starts, so install the package as a dependency there (`npm install @pangular-inspector/devtools`).
2222

23-
For an Angular CLI app with SSR, the [quick start](./apps/docs/src/content/getting-started/quick-start.md) takes you from install to a live panel. For other setups, follow the [installation guide](./apps/docs/src/content/getting-started/installation.md): a client-only Angular CLI app, Vite and Analog, the standalone CLI, [Angular Native](./apps/docs/src/content/guides/angular-native.md), or [Capacitor](./apps/docs/src/content/guides/capacitor.md). For a coding agent, run `npx @pangular-inspector/devtools mcp`.
23+
For an Angular CLI app with SSR, the [quick start](./apps/docs/src/content/getting-started/quick-start.md) takes you from install to a live panel. For other setups, follow the [installation guide](./apps/docs/src/content/getting-started/installation.md): a client-only Angular CLI app, Vite and Analog, the standalone CLI, [Angular Native](./apps/docs/src/content/getting-started/angular-native.md), or [Capacitor](./apps/docs/src/content/guides/capacitor.md). For a coding agent, run `npx @pangular-inspector/devtools mcp`.
2424

2525
## Documentation
2626

‎app/src/__tests__/angular-native-view.test.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,9 @@ describe('Angular Native view', () => {
101101
expect(text).toContain('No Angular Native app is connected');
102102
const link = host(fixture).querySelector<HTMLAnchorElement>('a.cta');
103103
expect(link?.textContent).toContain('Set up Angular Native');
104-
expect(link?.href).toContain('guides/angular-native/');
104+
expect(link?.href).toContain('getting-started/angular-native/');
105+
const platforms = host(fixture).querySelector<HTMLAnchorElement>('.platforms a');
106+
expect(platforms?.href).toBe('https://pangular-inspector.dev/getting-started/platforms/');
105107
expect(tabNames(fixture)).toEqual([]);
106108
});
107109

‎app/src/__tests__/capacitor-view.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,10 @@ describe('Capacitor view', () => {
158158
expect(link?.textContent).toContain('Capacitor setup guide');
159159
expect(link?.href).toBe('https://pangular-inspector.dev/guides/capacitor/');
160160
expect(link?.target).toBe('_blank');
161+
const platforms = el.querySelector<HTMLAnchorElement>('.platforms a');
162+
expect(platforms?.textContent).toContain('Supported and planned platforms');
163+
expect(platforms?.href).toBe('https://pangular-inspector.dev/getting-started/platforms/');
164+
expect(platforms?.target).toBe('_blank');
161165
expect(el.textContent).not.toContain('Coming Soon');
162166
expect(tabNames(fixture)).toEqual([]);
163167
});

‎app/src/app.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ const NATIVESCRIPT_SETUP: ComingSoonInfo = {
131131
],
132132
link: {
133133
label: 'NativeScript setup guide',
134-
href: 'https://pangular-inspector.dev/guides/nativescript/',
134+
href: 'https://pangular-inspector.dev/getting-started/nativescript/',
135135
},
136136
};
137137

@@ -186,7 +186,7 @@ const NO_ANGULAR_NATIVE: ComingSoonInfo = {
186186
],
187187
link: {
188188
label: 'Set up Angular Native',
189-
href: 'https://pangular-inspector.dev/guides/angular-native/',
189+
href: 'https://pangular-inspector.dev/getting-started/angular-native/',
190190
},
191191
};
192192

‎app/src/pages/coming-soon.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ export interface ComingSoonInfo {
1212
link?: { label: string; href: string };
1313
}
1414

15+
/** The docs page that lists the supported platforms and the planned ones, with their issues. */
16+
export const PLATFORMS_URL = 'https://pangular-inspector.dev/getting-started/platforms/';
17+
1518
@Component({
1619
selector: 'app-coming-soon',
1720
host: { '[style.--brand]': 'info().color' },
@@ -111,6 +114,14 @@ export interface ComingSoonInfo {
111114
<li [style.animation-delay.ms]="200 + i * 120">{{ plan }}</li>
112115
}
113116
</ul>
117+
118+
@if (info().id !== 'analog') {
119+
<p class="platforms">
120+
<a [href]="platformsUrl" target="_blank" rel="noopener noreferrer"
121+
>Supported and planned platforms<span class="sr-only"> (opens in a new tab)</span></a
122+
>
123+
</p>
124+
}
114125
</section>
115126
`,
116127
styles: `
@@ -352,6 +363,24 @@ export interface ComingSoonInfo {
352363
background: var(--brand);
353364
box-shadow: 0 0 0 3px color-mix(in srgb, var(--brand) 20%, transparent);
354365
}
366+
.platforms {
367+
width: 100%;
368+
max-width: 440px;
369+
margin: 16px auto 0;
370+
font-size: 13px;
371+
text-align: left;
372+
}
373+
.platforms a {
374+
color: var(--accent-text);
375+
text-decoration: underline;
376+
text-underline-offset: 2px;
377+
}
378+
.platforms a:hover {
379+
color: var(--text-strong);
380+
}
381+
.platforms a:focus-visible {
382+
@include m.focus-ring;
383+
}
355384
@media (max-height: 640px) {
356385
.soon {
357386
padding-top: 12px;
@@ -449,6 +478,7 @@ export interface ComingSoonInfo {
449478
})
450479
export class ComingSoon {
451480
readonly info = input.required<ComingSoonInfo>();
481+
protected readonly platformsUrl = PLATFORMS_URL;
452482
readonly plansTitle = computed(() => {
453483
const info = this.info();
454484
return info.plansTitle ?? (info.link ? `In an ${info.name} app` : 'On the roadmap');

‎apps/docs/agent-tool-index.spec.ts‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
import {readFileSync} from 'node:fs';
2+
import {join} from 'node:path';
3+
import * as prettier from 'prettier';
4+
import {TOOL_INDEX_PATH, findSection, renderToolIndex} from './agent-tool-index';
5+
6+
const docsRoot = import.meta.dirname;
7+
8+
describe('agent tool index', () => {
9+
it('names every agent tool and resource in tools.md or resources.md', () => {
10+
expect(renderToolIndex(docsRoot).problems).toEqual([]);
11+
});
12+
13+
it('matches the page in the repository; run pnpm docs:agent-tools when it fails', async () => {
14+
const file = join(docsRoot, TOOL_INDEX_PATH);
15+
const options = (await prettier.resolveConfig(file)) ?? {};
16+
const expected = await prettier.format(renderToolIndex(docsRoot).markdown, {
17+
...options,
18+
filepath: file,
19+
});
20+
expect(readFileSync(file, 'utf8')).toBe(expected);
21+
}, 30_000);
22+
23+
it('links a tool to its own heading, then to the table that defines it', () => {
24+
const markdown = [
25+
'## Before you call a tool',
26+
'Use `explain-field` and `explain-form-changes`.',
27+
'## Forms',
28+
'### Read',
29+
'| Tool | What it answers |',
30+
'| --- | --- |',
31+
'| `explain-field` | One field |',
32+
'',
33+
'| Tool | Cap |',
34+
'| --- | --- |',
35+
'| `explain-form-changes` | 100 fields |',
36+
'### Track',
37+
'| Tool | What it answers |',
38+
'| --- | --- |',
39+
'| `explain-form-changes` | The net change |',
40+
'### wait-for',
41+
].join('\n');
42+
expect(findSection(markdown, 'explain-field')?.slug).toBe('read');
43+
expect(findSection(markdown, 'explain-form-changes')?.slug).toBe('track');
44+
expect(findSection(markdown, 'wait-for')?.slug).toBe('wait-for');
45+
expect(findSection(markdown, 'missing-tool')).toBeNull();
46+
});
47+
});

‎apps/docs/agent-tool-index.ts‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
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

Comments
 (0)