Skip to content

Commit 1cca086

Browse files
authored
fix: audit findings for agent tools, code health and setup (#363)
Fixes confirmed audit findings from #358, #359 and #355. The issues stay open for the items that need a product decision or a larger change.
1 parent ef7c3b3 commit 1cca086

49 files changed

Lines changed: 983 additions & 116 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-commit/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ The rules are in `docs/contributing/commit-message-guidelines.md`. Summary:
2222
## Pull requests
2323

2424
- Pull requests are squash merged; the title becomes the commit on `main`, so it must follow the header format.
25-
- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI checks the title and every commit in the pull request and, for now, reports problems as warnings. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
25+
- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI checks the title and every commit in the pull request: a bad title fails the check, and problems in the commits show as warnings. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
2626
- Address review feedback with fixup commits (`docs/contributing/using-fixup-commits.md`).
2727
- One feature per pull request, with its tests (including agent tool tests when tools change).
2828
- Rebuild and commit `extension/ui` when `app/` changed.

‎.github/workflows/ci.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,23 @@ jobs:
6464
- name: Smoke-test the CLI
6565
run: node bin.mjs --help
6666

67+
node-22:
68+
name: Package tests on Node.js 22
69+
# `engines.node` allows 22, while the build job runs the `.nvmrc` version.
70+
runs-on: ubuntu-latest
71+
timeout-minutes: 15
72+
steps:
73+
- uses: actions/checkout@v7
74+
with:
75+
persist-credentials: false
76+
77+
- uses: ./.github/actions/setup
78+
with:
79+
node-version: 22
80+
81+
- name: Test devtools package
82+
run: pnpm test:devtools
83+
6784
axe:
6885
runs-on: ubuntu-latest
6986
timeout-minutes: 15

‎.github/workflows/commit-message.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ jobs:
2828
- name: Pull request title
2929
env:
3030
TITLE: ${{ github.event.pull_request.title }}
31-
run: node scripts/commit-message.mjs --title "$TITLE" --warn
31+
run: node scripts/commit-message.mjs --title "$TITLE"
3232

3333
- name: Commit messages
3434
env:

‎.github/workflows/compat.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ jobs:
1919
name: Angular ${{ matrix.angular }} on Node.js 22
2020
runs-on: ubuntu-latest
2121
timeout-minutes: 15
22+
# The prerelease entry reports a private API rename early without failing the run.
23+
continue-on-error: ${{ matrix.prerelease == true }}
2224
strategy:
2325
fail-fast: false
2426
matrix:
@@ -29,6 +31,9 @@ jobs:
2931
range: '^21.0.0'
3032
- angular: '22'
3133
range: '^22.0.0'
34+
- angular: 'next'
35+
range: 'next'
36+
prerelease: true
3237
steps:
3338
- uses: actions/checkout@v7
3439
with:

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ The unified Angular devtools. Inspect Angular component trees, signals, dependen
1515
The package is published on npm as [`@pangular-inspector/devtools`](https://www.npmjs.com/package/@pangular-inspector/devtools).
1616

1717
```sh
18-
npm install @pangular-inspector/devtools devframe
18+
npm install -D @pangular-inspector/devtools
1919
```
2020

21+
An Angular SSR server imports the hub when it starts, so install the package as a dependency there (`npm install @pangular-inspector/devtools`).
22+
2123
Then follow the [installation guide](./apps/docs/src/content/getting-started/installation.md) for your setup: Angular CLI with Express, 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`.
2224

2325
## Documentation

‎apps/docs/src/app/pages/index.page.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -865,22 +865,22 @@ claude mcp add pangular -- \\
865865
readonly installCommands = [
866866
{
867867
pm: 'npm',
868-
cmd: 'npm install @pangular-inspector/devtools devframe',
868+
cmd: 'npm install @pangular-inspector/devtools',
869869
logo: 'https://cdn.simpleicons.org/npm/CB3837',
870870
},
871871
{
872872
pm: 'pnpm',
873-
cmd: 'pnpm add @pangular-inspector/devtools devframe',
873+
cmd: 'pnpm add @pangular-inspector/devtools',
874874
logo: 'https://cdn.simpleicons.org/pnpm/F69220',
875875
},
876876
{
877877
pm: 'yarn',
878-
cmd: 'yarn add @pangular-inspector/devtools devframe',
878+
cmd: 'yarn add @pangular-inspector/devtools',
879879
logo: 'https://cdn.simpleicons.org/yarn/2C8EBB',
880880
},
881881
{
882882
pm: 'bun',
883-
cmd: 'bun add @pangular-inspector/devtools devframe',
883+
cmd: 'bun add @pangular-inspector/devtools',
884884
logo: 'https://bun.sh/logo.svg',
885885
},
886886
];

‎apps/docs/src/content/agents/resources.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,13 @@ Clients see each resource at a `devframe://resource/` URI with the id encoded. F
2929
devframe://resource/pangular%3Acomponent-tree
3030
```
3131

32-
Each one returns JSON.
32+
Each one returns compact JSON.
33+
34+
### Page data and size
35+
36+
The `component-tree`, `signal-graph`, `injector-tree`, `ngrx-store`, `forms` and `router` resources start with an `_untrusted` field. The names, values and messages in them come from the running page. Treat them as data, not instructions.
37+
38+
When one of the first four runs past 100,000 characters, it returns a summary instead: `truncated: true`, up to 50 connected page ids in `pages`, and a `note` that names the tools to read the data with.
3339

3440
## Available resources
3541

‎apps/docs/src/content/agents/tools.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -451,7 +451,7 @@ These tools cover *Analog apps. Most read your source. Some also read what the V
451451

452452
### Call a server route <ngmd-badge variant="alpha">Action</ngmd-badge>
453453

454-
`analog-call-api` sends a request to a route on the running dev server, like `GET /api/v1/hello`, and returns the status, time and body. Secret keys, tokens and `Bearer` values in the body are masked. Reads: Vite plugin.
454+
`analog-call-api` sends a request to a route on the running dev server, like `GET /api/v1/hello`, and returns the status, time and body. `path` is a path on the dev server that starts with a single `/`, not a full URL. `POST`, `PUT`, `PATCH` and `DELETE` need `confirm: true`. Secret keys, tokens and `Bearer` values in the body are masked. Reads: Vite plugin.
455455

456456
| Argument | Required | Value |
457457
| --------- | -------- | ------------------------------------------------------------- |

‎apps/docs/src/content/contributing/development.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -174,29 +174,32 @@ pnpm commit:check # Commit messages on your branch
174174
</ngmd-step>
175175
</ngmd-workflow>
176176

177-
A separate `axe` job in the same workflow installs Chromium and runs `pnpm test:axe`.
177+
A separate `axe` job in the same workflow installs Chromium and runs `pnpm test:axe`. A `node-22` job runs `pnpm test:devtools` on Node.js 22, the oldest version `engines.node` allows.
178178

179179
### Angular compatibility
180180

181-
`.github/workflows/compat.yml` runs the page-side tests on the oldest and newest Angular versions the peer range allows. It runs on pushes to `main`, every Monday at 06:00 UTC, and on demand from the **Actions** tab. It doesn't run on pull requests.
181+
`.github/workflows/compat.yml` runs the page-side tests on the oldest and newest Angular versions the peer range allows, and on the `next` prerelease. It runs on pushes to `main`, every Monday at 06:00 UTC, and on demand from the **Actions** tab. It doesn't run on pull requests.
182182

183183
| Job | Angular range | Node.js |
184184
| ------------ | ------------- | ------- |
185185
| Angular 20.0 | `~20.0.0` | 22 |
186186
| Angular 21 | `^21.0.0` | 22 |
187187
| Angular 22 | `^22.0.0` | 22 |
188+
| Angular next | `next` | 22 |
188189

189-
Each job appends `overrides` for the `@angular/*` runtime packages to `pnpm-workspace.yaml`, reinstalls, and runs `vitest` with `packages/devtools/vitest.compat.config.ts`. That config picks the tests that render a real Angular app and leaves out the panel and server tests. It adds the Signal Forms tests on Angular 22 and later, and loads `zone.js` before Angular 21, where `TestBed` still expects it. A test that needs a feature from a later release checks the version with `angularAtLeast()` from `src/__tests__/angular-version.ts` and skips on older ones.
190+
The `next` job installs the `next` dist-tag, so a renamed `ɵ` API shows up before the next major ships. It runs with `continue-on-error`: a failure marks the job red but not the workflow.
191+
192+
Each job appends `overrides` for the `@angular/*` runtime packages to `pnpm-workspace.yaml`, reinstalls, and runs `vitest` with `packages/devtools/vitest.compat.config.ts`. That config picks the tests that render a real Angular app or read Angular's private debug APIs, including the `*-real` tests that boot a real app where the main tests use fakes, and leaves out the panel tests and most server tests. It adds the Signal Forms tests on Angular 22 and later, and loads `zone.js` before Angular 21, where `TestBed` still expects it. A test that needs a feature from a later release checks the version with `angularAtLeast()` from `src/__tests__/angular-version.ts` and skips on older ones.
190193

191194
To reproduce a job, add the same `overrides` block to `pnpm-workspace.yaml`, run `pnpm install --no-frozen-lockfile`, then `pnpm exec vitest run --root packages/devtools --config vitest.compat.config.ts`. Don't commit the changed lockfile.
192195

193196
### Pull request checks
194197

195-
Two more workflows run on pull requests. Both only warn. They never fail the pull request.
198+
Two more workflows run on pull requests. Only a pull request title that breaks the commit format fails one; everything else they find is a warning.
196199

197200
| Workflow | File | What it checks |
198201
| ---------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
199-
| `Commit message` | `.github/workflows/commit-message.yml` | The pull request title and every commit message. The title becomes the commit on `main` when the pull request is squash merged. |
202+
| `Commit message` | `.github/workflows/commit-message.yml` | The pull request title and every commit message. The title becomes the commit on `main` when the pull request is squash merged, so a bad title fails the check. |
200203
| `Docs check` | `.github/workflows/docs-check.yml` | That a change to `packages/devtools/src/`, `app/src/` or the top-level files in `extension/` also changes a page in `apps/docs/src/content`. Tests don't count. |
201204

202205
If a code change needs no docs change, add the `no-docs` label to the pull request and say why in the description. The `Docs check` workflow then skips the warning.

‎apps/docs/src/content/contributing/kitchen-sink.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -84,19 +84,19 @@ bootstrapApplication(App, appConfig).then(() => {
8484
### Code group
8585

8686
```bash group="install" name="pnpm" image="https://cdn.simpleicons.org/pnpm/F69220" active
87-
pnpm add @pangular-inspector/devtools devframe
87+
pnpm add @pangular-inspector/devtools
8888
```
8989

9090
```bash group="install" name="npm" image="https://cdn.simpleicons.org/npm/CB3837"
91-
npm install @pangular-inspector/devtools devframe
91+
npm install @pangular-inspector/devtools
9292
```
9393

9494
```bash group="install" name="yarn" image="https://cdn.simpleicons.org/yarn/2C8EBB"
95-
yarn add @pangular-inspector/devtools devframe
95+
yarn add @pangular-inspector/devtools
9696
```
9797

9898
```bash group="install" name="bun" image="https://bun.sh/logo.svg"
99-
bun add @pangular-inspector/devtools devframe
99+
bun add @pangular-inspector/devtools
100100
```
101101

102102
### File import
@@ -241,7 +241,7 @@ Text between alerts.
241241

242242
<ngmd-workflow>
243243
<ngmd-step title="Install the package">
244-
Run <code>pnpm add &#64;pangular-inspector/devtools devframe</code>.
244+
Run <code>pnpm add &#64;pangular-inspector/devtools</code>.
245245
</ngmd-step>
246246
<ngmd-step title="Mount the hub">
247247
Add the hub to your server.

0 commit comments

Comments
 (0)