Register the penpot tests in npm test, complete the extension README, and roll out #217

New issue

Closed

opened 2026-09-14 23:15:47 +00:00 by david · 1 comment

david commented

2026-09-14 23:15:47 +00:00

Owner

Summary

Register the penpot unit tests in the root npm test script, complete extensions/penpot/README.md (tool reference, environment variables, safety model), and roll the whole feature out per AGENTS.md: full suite green, install:local preflight passing, /reload showing the tools and the skill, then the tracking issue → branch → commits → PR with a per-file summary.

Background

Depends on: #213, #215, #206, #196

This is the last step and the only one that touches the package as a whole. Three loose ends converge here:

Tests are not yet part of the suite. Every step added node --test files, but package.json's test script only runs scripts/local-install.test.mjs and extensions/learn-repo/*.test.ts. A test that is not in the script does not exist as far as CI and reviewers are concerned. The globs must be added only for directories that actually contain test files, because a glob matching nothing makes node --test fail.
The extension README is still a placeholder. The plan's deliverables call for a tool reference plus the environment variables and the safety model. Each earlier step documented only what existed at the time; this step completes it against the shipped tool surface.
Rollout. Per AGENTS.md, this feature is issue-driven: tracking issue, feature/issue-<N>/<kebab-slug> branch, commits issue-<N>: <summary>, PR titled issue-<N>: … with Closes #<N> and a per-file summary. Merging is the repo owner's decision, not the agent's — open the PR and ask; never merge on your own initiative, and in a non-interactive run (pi --print) stop at the PR rather than asking. An unanswered or ambiguous prompt is not consent.

Documentation Required

A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting.

docs/reference/pi-coding-agent/

https://pi.dev/docs/latest/packages — the package manifest (pi.extensions, pi.skills) and how npm scripts interact with a pi package, so the test script edit and the README claims stay accurate.
https://pi.dev/docs/latest/extensions — the tool surface being documented (names, parameters, result shapes) and the extension lifecycle (/reload).
https://pi.dev/docs/latest/skills — skill discovery, for the /skills verification step.
https://pi.dev/docs/latest/environment-variables — environment variables available to tools/extensions, confirming the README's variable table matches pi's conventions.

docs/reference/nodejs/

https://nodejs.org/api/test.html — node --test file/glob arguments, and the failure mode when a glob matches nothing. This is why the added globs must correspond to real directories.

docs/reference/penpot-api/

https://help.penpot.app/technical-guide/integration/ — access-token auth and base-URL shape, for the README's configuration section.
https://help.penpot.app/user-guide/design-systems/libraries/ — the import/link behaviour, for the README's library section.

Implementation Details

1. Register the tests

List what actually exists: ls extensions/penpot/src/*.test.ts extensions/penpot/src/tools/*.test.ts 2>/dev/null.
Append the surviving globs to scripts.test in the root package.json, e.g.:
```
"test": "node --test scripts/local-install.test.mjs extensions/learn-repo/*.test.ts extensions/penpot/src/*.test.ts extensions/penpot/src/tools/*.test.ts"
```
Add a directory's glob only when that directory contains at least one *.test.ts; otherwise the runner fails on the empty match.
Run npm test and fix anything it uncovers. A test that fails here is a real defect: fix the code, not the assertion, unless the assertion itself is wrong — in which case say so explicitly in the PR body.

2. Complete `extensions/penpot/README.md`

Configuration: PENPOT_URL (base URL, no /api suffix; a trailing /api is normalised away), PENPOT_TOKEN (personal access token, presented as Authorization: Token <token>), where the token is created, that writes need project edit rights, and that the vendored reference is pinned to a specific Penpot version (skills/penpot/docs/VERSION).
Tool reference: one table of every registered penpot_* tool with a one-line purpose and its key parameters. Generate the list from the code (grep -n 'name: "penpot_' extensions/penpot/src/tools/*.ts) rather than from memory, so the README cannot drift.
Write model: assets and shapes are staged and applied by penpot_commit as a single update-file call (one screen = one revision); revn is tracked by the extension because lagged writes are accepted by the server; penpot_discard clears staged work; success is confirmed by re-reading the file.
Safety model: the designated-target guard — writes are permitted only to files the extension created in a nominated project or to a file the user explicitly named via penpot_authorize_target; refusals happen before any request; media uploads and library imports are immediate HTTP calls and say so.
Known limitations: the SVG subset and its svg-raw fallback, single-level component instancing, no add-component over the API, no native design tokens, and font substitution when the instance lacks a family. Cross-reference findings.md for the validated behaviour.

3. Verify the package

npm test — green.
npm run install:local — preflight still passes (it may warn about missing fj/rg/tokens; warnings are fine, failures are not).
In pi: /reload, then confirm the penpot tools are callable and /skills lists penpot with its description.
Confirm the manifest contains the extension path and that skills/penpot/ (including docs/ and assets/) is packaged.

4. Roll out

Follow AGENTS.md for the feature flow: create (or reuse) the tracking issue for this feature, branch feature/issue-<N>/penpot-skill-extension, commit in coherent units with issue-<N>: <summary> messages, push, and open the PR titled issue-<N>: … whose body has Closes #<N> and a per-file summary of the change. .env must never be committed and PENPOT_TOKEN must not appear in any committed file — check git diff --cached before committing. Then ask the user whether to merge; skip the prompt only if merging was already requested explicitly, and in a non-interactive run stop at the PR.

Acceptance Criteria

package.json's test script includes globs for exactly the penpot test directories that exist, and npm test passes.
npm run install:local completes without a hard failure.
extensions/penpot/README.md documents configuration, the full tool table, the staged-commit write model, the designated-target safety model, and the known limitations.
The tool table lists every registered penpot_* tool and no tool that does not exist (verified by grepping the code).
After /reload, the penpot tools are callable and /skills lists penpot.
No secret is committed: git diff --cached and the repo contain no PENPOT_TOKEN value or .env file.
The PR is open with Closes #<N>, an issue-<N>: … title and a per-file summary in the body.
Merging was left to the repo owner (prompted, or skipped only when merging was explicitly requested, or stopped at the PR in a non-interactive run).

Test Plan

# 1. Full suite
npm test

# 2. Install preflight
npm run install:local

# 3. Tool table vs code
grep -n 'name: "penpot_' extensions/penpot/src/tools/*.ts | wc -l
grep -c '^| `penpot_' extensions/penpot/README.md

# 4. No secrets staged
git diff --cached --name-only | grep -E '^\.env$' && echo "STOP: .env staged" || echo "no .env staged"
git diff --cached | grep -i "PENPOT_TOKEN=" && echo "STOP: token in diff" || echo "no token in diff"

Then in pi:

# /reload
# /skills          -> expect penpot listed
# penpot_whoami    -> expect the token owner's profile

## Summary Register the penpot unit tests in the root `npm test` script, complete `extensions/penpot/README.md` (tool reference, environment variables, safety model), and roll the whole feature out per `AGENTS.md`: full suite green, `install:local` preflight passing, `/reload` showing the tools and the skill, then the tracking issue → branch → commits → PR with a per-file summary. ## Background **Depends on:** #213, #215, #206, #196 This is the last step and the only one that touches the package as a whole. Three loose ends converge here: 1. **Tests are not yet part of the suite.** Every step added `node --test` files, but `package.json`'s `test` script only runs `scripts/local-install.test.mjs` and `extensions/learn-repo/*.test.ts`. A test that is not in the script does not exist as far as CI and reviewers are concerned. The globs must be added **only** for directories that actually contain test files, because a glob matching nothing makes `node --test` fail. 2. **The extension README is still a placeholder.** The plan's deliverables call for a tool reference plus the environment variables and the safety model. Each earlier step documented only what existed at the time; this step completes it against the shipped tool surface. 3. **Rollout.** Per `AGENTS.md`, this feature is issue-driven: tracking issue, `feature/issue-<N>/<kebab-slug>` branch, commits `issue-<N>: <summary>`, PR titled `issue-<N>: …` with `Closes #<N>` and a per-file summary. **Merging is the repo owner's decision, not the agent's** — open the PR and ask; never merge on your own initiative, and in a non-interactive run (`pi --print`) stop at the PR rather than asking. An unanswered or ambiguous prompt is not consent. ## Documentation Required A separate process downloads these into the listed folders before this issue is implemented. Check the folders for the actual reference material before starting. **`docs/reference/pi-coding-agent/`** - https://pi.dev/docs/latest/packages — the package manifest (`pi.extensions`, `pi.skills`) and how npm scripts interact with a pi package, so the `test` script edit and the README claims stay accurate. - https://pi.dev/docs/latest/extensions — the tool surface being documented (names, parameters, result shapes) and the extension lifecycle (`/reload`). - https://pi.dev/docs/latest/skills — skill discovery, for the `/skills` verification step. - https://pi.dev/docs/latest/environment-variables — environment variables available to tools/extensions, confirming the README's variable table matches pi's conventions. **`docs/reference/nodejs/`** - https://nodejs.org/api/test.html — `node --test` file/glob arguments, and the failure mode when a glob matches nothing. This is why the added globs must correspond to real directories. **`docs/reference/penpot-api/`** - https://help.penpot.app/technical-guide/integration/ — access-token auth and base-URL shape, for the README's configuration section. - https://help.penpot.app/user-guide/design-systems/libraries/ — the import/link behaviour, for the README's library section. ## Implementation Details ### 1. Register the tests - List what actually exists: `ls extensions/penpot/src/*.test.ts extensions/penpot/src/tools/*.test.ts 2>/dev/null`. - Append the surviving globs to `scripts.test` in the root `package.json`, e.g.: ```jsonc "test": "node --test scripts/local-install.test.mjs extensions/learn-repo/*.test.ts extensions/penpot/src/*.test.ts extensions/penpot/src/tools/*.test.ts" ``` Add a directory's glob only when that directory contains at least one `*.test.ts`; otherwise the runner fails on the empty match. - Run `npm test` and fix anything it uncovers. A test that fails here is a real defect: fix the code, not the assertion, unless the assertion itself is wrong — in which case say so explicitly in the PR body. ### 2. Complete `extensions/penpot/README.md` - **Configuration**: `PENPOT_URL` (base URL, no `/api` suffix; a trailing `/api` is normalised away), `PENPOT_TOKEN` (personal access token, presented as `Authorization: Token <token>`), where the token is created, that writes need project **edit** rights, and that the vendored reference is pinned to a specific Penpot version (`skills/penpot/docs/VERSION`). - **Tool reference**: one table of every registered `penpot_*` tool with a one-line purpose and its key parameters. Generate the list from the code (`grep -n 'name: "penpot_' extensions/penpot/src/tools/*.ts`) rather than from memory, so the README cannot drift. - **Write model**: assets and shapes are **staged** and applied by `penpot_commit` as a single `update-file` call (one screen = one revision); `revn` is tracked by the extension because lagged writes are accepted by the server; `penpot_discard` clears staged work; success is confirmed by re-reading the file. - **Safety model**: the designated-target guard — writes are permitted only to files the extension created in a nominated project or to a file the user explicitly named via `penpot_authorize_target`; refusals happen before any request; media uploads and library imports are immediate HTTP calls and say so. - **Known limitations**: the SVG subset and its `svg-raw` fallback, single-level component instancing, no `add-component` over the API, no native design tokens, and font substitution when the instance lacks a family. Cross-reference `findings.md` for the validated behaviour. ### 3. Verify the package - `npm test` — green. - `npm run install:local` — preflight still passes (it may warn about missing `fj`/`rg`/tokens; warnings are fine, failures are not). - In pi: `/reload`, then confirm the penpot tools are callable and `/skills` lists `penpot` with its description. - Confirm the manifest contains the extension path and that `skills/penpot/` (including `docs/` and `assets/`) is packaged. ### 4. Roll out Follow `AGENTS.md` for the `feature` flow: create (or reuse) the tracking issue for this feature, branch `feature/issue-<N>/penpot-skill-extension`, commit in coherent units with `issue-<N>: <summary>` messages, push, and open the PR titled `issue-<N>: …` whose body has `Closes #<N>` and a **per-file summary** of the change. `.env` must never be committed and `PENPOT_TOKEN` must not appear in any committed file — check `git diff --cached` before committing. Then **ask the user whether to merge**; skip the prompt only if merging was already requested explicitly, and in a non-interactive run stop at the PR. ## Acceptance Criteria - [ ] `package.json`'s `test` script includes globs for exactly the penpot test directories that exist, and `npm test` passes. - [ ] `npm run install:local` completes without a hard failure. - [ ] `extensions/penpot/README.md` documents configuration, the full tool table, the staged-commit write model, the designated-target safety model, and the known limitations. - [ ] The tool table lists every registered `penpot_*` tool and no tool that does not exist (verified by grepping the code). - [ ] After `/reload`, the penpot tools are callable and `/skills` lists `penpot`. - [ ] No secret is committed: `git diff --cached` and the repo contain no `PENPOT_TOKEN` value or `.env` file. - [ ] The PR is open with `Closes #<N>`, an `issue-<N>: …` title and a per-file summary in the body. - [ ] Merging was left to the repo owner (prompted, or skipped only when merging was explicitly requested, or stopped at the PR in a non-interactive run). ## Test Plan ```bash # 1. Full suite npm test # 2. Install preflight npm run install:local # 3. Tool table vs code grep -n 'name: "penpot_' extensions/penpot/src/tools/*.ts | wc -l grep -c '^| `penpot_' extensions/penpot/README.md # 4. No secrets staged git diff --cached --name-only | grep -E '^\.env$' && echo "STOP: .env staged" || echo "no .env staged" git diff --cached | grep -i "PENPOT_TOKEN=" && echo "STOP: token in diff" || echo "no token in diff" ``` Then in pi: ```bash # /reload # /skills -> expect penpot listed # penpot_whoami -> expect the token owner's profile ```

david added this to the Penpot: M9 - README and rollout milestone

2026-09-14 23:15:47 +00:00

david added the

feature

label

2026-09-14 23:15:47 +00:00

david referenced this issue from a pull request that will close it,

2026-09-15 08:11:14 +00:00

issue-217: Register the penpot tests in npm test, complete the extension README, and roll out #249

david closed this issue

2026-09-15 08:11:15 +00:00

david commented