pi-dynamic-help 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0
+
+- Refactor the extension into maintainable modules for state, identity, resource indexing, rendering, and extension wiring.
+- Add state v3 canonical identities for command names and package sources.
+- Preserve this package's `/help` and `/help-brief` usage/pins across local, npm, git, and node_modules source forms.
+- Add safe state loading with corrupt-state backups and save-failure warnings.
+- Make markdown rendering pure and escape dynamic resource fields.
+- Expand hermetic tests for migration, state persistence failures, rendering, settings parsing, and pin matching.
+- Tighten Pi peer dependency ranges to `>=0.78.0 <1`.
+
 ## 0.1.0
 
-- Initial package extraction for the dynamic `/help` dashboard.
+- Initial package release for the dynamic `/help` dashboard.

package/README.md

@@ -4,6 +4,10 @@ Dynamic `/help` dashboard for [Pi](https://pi.dev). It summarizes loaded slash c
 
 ## Install
 
+```bash
+pi install npm:pi-dynamic-help
+```
+
 Local development install:
 
 ```bash
@@ -16,18 +20,12 @@ Temporary test run without adding it to settings:
 pi -e /absolute/path/to/pi-dynamic-help
 ```
 
-NPM install:
-
-```bash
-pi install npm:pi-dynamic-help
-```
-
 After installing, run `/reload` or restart Pi if the command is not visible immediately.
 
 ## Commands
 
 - `/help` — open the dynamic help dashboard.
-- `/help refresh` — refresh the resource index and usage counters.
+- `/help refresh` — refresh the resource index and persist state.
 - `/help search <term>` — filter the dashboard by a term.
 - `/help pin <term>` — pin the best matching resource.
 - `/help unpin <term>` — unpin the best matching resource.
@@ -41,6 +39,10 @@ After installing, run `/reload` or restart Pi if the command is not visible imme
 
 The dashboard keeps command/tool/package/MCP sections separate so the resource type is clear.
 
+## Usage counters
+
+Usage counters currently focus on tools and MCP calls, based on Pi session/tool-result data that is available to the extension. Commands are ranked by pinning and known metadata unless Pi exposes reliable command-usage data in the future.
+
 ## State and migration
 
 Runtime metadata is stored under the user's Pi agent state directory:
@@ -55,7 +57,15 @@ The old local-extension state file, if present, is read as a migration source:
 ~/.pi/agent/state/dynamic-help.json
 ```
 
-The old file is not deleted. Migration preserves usage counts, pinned items, and timestamps where possible. The package normalizes source keys idempotently to avoid repeated `local:local:...` prefixes.
+State uses stable identities for resources. Command identities normalize `/help` and `help` to the same item, and this package's own local/npm/git/node_modules sources normalize to `pkg:pi-dynamic-help`, preserving `/help` and `/help-brief` pins and usage across install-source changes.
+
+If the current state file is corrupt, it is moved aside as:
+
+```text
+~/.pi/agent/state/pi-dynamic-help/state.corrupt-<timestamp>.json
+```
+
+Then the extension starts from legacy state or an empty state. State save failures show a warning but should not prevent `/help` from rendering.
 
 Runtime state is not part of the npm package and should not be committed or published.
 
@@ -72,11 +82,14 @@ npm run test
 npm run pack:dry
 ```
 
+Tests are hermetic and use temporary directories for state-store coverage; they should not write to your real `~/.pi/agent/state`.
+
 Useful local smoke test:
 
 ```bash
+npm pack
 TMP_AGENT_DIR=$(mktemp -d /tmp/pi-dynamic-help-agent-XXXXXX)
-PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi install /absolute/path/to/pi-dynamic-help
+PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi install ./pi-dynamic-help-0.2.0.tgz
 PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help"
 PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help refresh"
 PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help search mcp"
@@ -90,3 +103,4 @@ PI_CODING_AGENT_DIR="$TMP_AGENT_DIR" pi --no-session -p "/help unpin bash"
 - State looks stale: run `/help refresh`.
 - A pin targets the wrong resource: use a more specific search term with `/help pin <term>` or undo it with `/help unpin <term>`.
 - Installed package is not shown: confirm it is listed in `~/.pi/agent/settings.json` or project `.pi/settings.json`, then run `/help refresh`.
+- State corruption warning appears: inspect the generated `state.corrupt-*.json` backup and continue using `/help`; the extension will create a fresh state file.