pi-files-widget-overlay 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable changes to this extension will be documented in this file.
+
+## [0.3.0] - 2026-09-10
+
+### Fixed
+- Highlight and select every wrapped visual row of a logical line; comments retain logical source-line ranges.
+- Make `c` and `C` share changed-only state while preserving collapsed and expanded changed-path views.
+- Preserve logical cursor and selection groups across width changes and page navigation.
+- Clear agent-modified file markers before a session switch.
+- Keep Diff searches and comments anchored to logical Diff lines across word-wrap and width changes.
+- Reset rendered Markdown selection to the first raw source line before creating a source-aligned comment.
+- Schedule Git line counts by expanded directory instead of queueing every tracked file at startup.
+- Keep confirmed file-viewer searches available to `n` and `N`.
+- Track observed `edit.file` activity alongside `write.path` using normalized paths.
+- Show non-blocking directory-scan and Git-metadata errors in the browser; verify Git metadata paths from repository subdirectories.
+
+### Added
+- Add Vitest coverage for wrapped-row grouping, logical-line navigation, selection, and comments.
+- Add `C` to toggle the expanded changed view.
+- Add `w` to toggle word wrap in the file viewer; wrapping is disabled by default.
+- Show hidden project files such as `.pi/` and `.github/` while keeping `.git/` and common generated directories hidden.
+- Add anonymous Git and non-Git browser performance benchmarks with a recorded baseline.
+
+### Changed
+- Forked `files-widget` as `pi-files-widget-overlay`; retain upstream MIT attribution and add tallshort copyright.
+- Replace Delta's split line-number diff renderer with a compact unified view: explicit `+`/`-` markers and one relevant line number.
+- Highlight the full width of the current line and selection; align the viewer and file-browser default overlay heights.
+- Remove the Delta runtime dependency.
+- Replace the README demo video with a static screenshot and add Pi Packages Gallery image metadata.
+
+### Added
+- `/readfiles` now supports browsing outside the current working directory. Press `u` to re-root to the parent, `.` to jump back to where you started, or pass an explicit starting path (`/readfiles <path>` or `/readfiles ~/somewhere`). The browser header shows the current root so you always know where you are, and comments on files outside the project use absolute paths so the agent can still find them.
+
+### Fixed
+- Git status, diff stats, and untracked-file discovery now work when the browser root is a subdirectory of the git repository (e.g. after `u`, `.`, or `/readfiles <subdir>`, or when pi runs from a repo subdirectory). Previously repo-root-relative git paths were mixed with root-relative node keys, producing phantom tree entries, missing statuses, and unopenable nested paths.
+- Re-rooting the browser while a background directory scan or line-count batch is in flight no longer lets the stale batch mutate the new root's tree, node index, or scan state.
+- Use `where` instead of `which` on Windows to detect `bat`, `delta`, and `glow`, so the dependency check works when running from PowerShell or cmd.exe.
+
+## [0.1.21] - 2026-05-07
+
+### Changed
+- Declare `@earendil-works` Pi development dependencies used by runtime imports.
+- Update Pi extension imports and peer dependencies to the new `@earendil-works` namespace.
+
+
+## [0.1.20] - 2026-04-24
+
+### Removed
+- Remove the external `/readfiles-review` and `/readfiles-diff` commands so files-widget stays focused on the `/readfiles` browser/viewer.
+
+
+## [0.1.18] - 2026-04-19
+
+### Changed
+- Show symlinks with a `↗` marker in the `/readfiles` tree.
+
+### Fixed
+- Let `/readfiles` navigate into directory symlinks in both non-git folders and git repos instead of rendering them as inert files or empty directories.
+- Guard symlink directory scanning against ancestor cycles so links like `foo -> .` or `foo -> ..` don't recurse forever.
+- Treat git-tracked and untracked directory symlinks as lazily scannable directories rather than plain files.
+
+### Thanks
+- Thanks to @xapids for reporting the original macOS symlink navigation issue ([#9](https://github.com/tmustier/pi-extensions/issues/9)).
+
+## [0.1.17] - 2026-04-19
+
+### Changed
+- Make the inline comment editor multiline with wrapped footer rendering, `Enter` for a new line, and `Ctrl+Enter`/`Ctrl+D` to send.
+- Add an `m` toggle for rendered vs raw Markdown in the viewer, and fall back to raw mode before line-based search or selection.
+- Show a sent/queued confirmation toast after returning an inline comment to the agent.
+
+### Thanks
+- Thanks to avg8888 in the Pi Discord for surfacing the comment editor and Markdown review issues fixed in this release.
+
+## [0.1.16] - 2026-04-19
+
+### Fixed
+- Let `/readfiles` browser search accept `j` and `k` as search text instead of hijacking them for navigation.
+- Fix viewer scrolling so the last lines of a file remain reachable.
+- Restore `G` / `Shift+G` navigation to jump to the bottom of the viewer.
+- Refresh an open viewer when the file changes on disk while `/readfiles` is open.
+- Accept pasted, multi-character, and chunked bracketed-paste input in browser search and the inline comment prompt.
+- Keep viewer search results in sync after live refreshes.
+- Pause live refresh while a line selection or inline comment is active so comments stay anchored to what the user selected.
+
+## [0.1.14] - 2026-02-03
+
+### Added
+- Add preview video metadata for the extension listing.
+
+## [0.1.13] - 2026-02-02
+
+### Changed
+- **BREAKING:** Renamed `/files` command to `/readfiles` to avoid conflict with Pi's new built-in `/files` command (Pi v0.50.2+)
+
+## [0.1.11] - 2026-01-26
+
+### Changed
+- Require `bat`, `delta`, and `glow` before opening `/files`
+- Add a postinstall reminder for required system tools
+- Document install commands next to the Pi install steps
+
+## [0.1.10] - 2026-01-26
+
+### Fixed
+- Treat git-reported directory entries as directories to avoid viewer errors
+- Guard the viewer against opening directories directly
+- Wrap delta diff output without breaking gutters and avoid truncation
+- Add a safe fallback when `bat` fails to render with wrapping
+
+## [0.1.9] - 2026-01-26
+
+### Changed
+- Bind render requests to avoid undefined context with the latest pi-tui
+
+## [0.1.8] - 2026-01-26
+
+### Changed
+- Compute line counts asynchronously with loading indicators
+- Build git repo trees from git file lists to avoid filesystem scans
+- Add progressive filesystem scanning with safe mode for large folders
+- Reduce refresh work to git metadata updates
+
+## [0.1.7] - 2026-01-26
+
+### Changed
+- Cache line counts and skip large files to avoid freezes in big folders
+- Avoid recomputing tree stats on every render
+- Preserve line counts for open files across refreshes
+
+## [0.1.6] - 2026-01-24
+
+### Added
+- Clearer install instructions and dependency notes in README
+
+## [0.1.5] - 2026-01-24
+
+### Added
+- Demo recording embedded in README
+
+### Changed
+- Comment sending now queues with follow-up delivery in streaming sessions
+- Split viewer logic into `viewer.ts` and shared helpers
+- Reduced browser render duplication with node format helpers
+
+## [0.1.4] - 2026-01-24
+
+### Changed
+- Split viewer logic into `viewer.ts` and shared helpers
+- Reduced browser render duplication with node format helpers
+
+## [0.1.3] - 2026-01-24
+
+### Changed
+- `c` in viewer now opens an inline comment prompt and sends a follow-up message
+
+## [0.1.2] - 2026-01-24
+
+### Changed
+- `c` in viewer now appends selection to editor input instead of sending immediately
+
+## [0.1.1] - 2026-01-24
+
+### Added
+- README with install steps, dependencies, and keybindings
+
+### Changed
+- Refactored into modular files (browser, git, tree, viewer, utils)
+
+## [0.1.0] - 2026-01-24
+
+### Added
+- `/files` command opens full-screen file browser
+- File tree with j/k navigation, Enter to open, h/l to collapse/expand
+- File viewer with syntax highlighting via `bat`
+- Markdown rendering via `glow`
+- Git diff view via `delta` with line numbers
+- Git status indicators (M, A, D, ?) on files
+- Agent-modified file tracking (🤖 indicator)
+- Changed files filter (`c` to toggle)
+- Jump to next/prev changed file (`]`/`[`)
+- Search in file tree (`/` then type)
+- Search in file viewer (`/` then type, `n`/`N` for next/prev match)
+- Select mode (`v`) to select lines and comment (`c`) to send to agent
+- Line counts and diff stats (+/-) on files and collapsed folders
+- Auto-refresh git status every 3 seconds (preserves expansion state)
+- PageUp/PageDown support in browser and viewer
+- Height adjustment (`+`/`-`)
+- Works in non-git directories (git features gracefully disabled)
+
+### Dependencies
+- `bat` - syntax highlighting (recommended)
+- `glow` - markdown rendering (recommended)
+- `delta` - diff formatting (recommended)
+
+Install with: `brew install bat git-delta glow`

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Thomas Mustier
+Copyright (c) 2026 tallshort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# pi-files-widget-overlay
+
+In-terminal floating-overlay file browser and diff viewer for Pi. Navigate files, view diffs, select code, and send comments to the agent without leaving the terminal and without interrupting your agent.
+
+## Origin
+
+Forked from [tmustier/pi-extensions — files-widget](https://github.com/tmustier/pi-extensions/tree/main/files-widget), distributed under the MIT License. Modifications and overlay-focused maintenance are by tallshort.
+
+Directory symlinks are shown with a `↗` marker and can be expanded like normal folders.
+
+![File browser overlay](demo.png)
+## Install
+
+**Quick install (Pi package manager):**
+
+```bash
+pi install npm:pi-files-widget-overlay
+```
+
+**Local development:** add the repository path to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": [
+    "~/pi-files-widget-overlay"
+  ]
+}
+```
+## Dependencies
+
+- Pi built-in syntax highlighter: code colors follow the active Pi theme
+- Pi built-in Markdown renderer: rendered Markdown follows the active Pi theme
+
+The `/readfiles` browser has no `bat`, `glow`, or `delta` runtime dependency. Code, Markdown, and unified diffs use Pi's theme-aware renderers; Diff mode uses `git` when available.
+
+## Project layout
+
+- `src/`: extension runtime and `/readfiles` entry point
+- `test/`: browser and viewer regression tests
+- `docs/`: design notes and anonymous benchmark baselines
+- `benchmarks/`: locally run benchmark harnesses; excluded from the published package
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+## Commands
+
+- `/readfiles` - open the file browser as a floating overlay in the current directory
+- `/readfiles <path>` - open the floating browser rooted at `<path>` (absolute, relative, or `~`-prefixed)
+
+The overlay is centered at 95% of terminal width with a one-cell margin. Its framed header separates the browser from the agent transcript; `q` or `Esc` closes it and returns focus to Pi.
+Diff viewing is built into the file viewer: open a changed tracked file and press `d` to toggle the git diff view.
+
+## Browser Keybindings
+
+- `j/k` or `↑/↓`: move
+- `Enter`: open file / expand folder
+- `h/l` or `←/→`: collapse/expand folder
+- `PgUp/PgDn`: page up/down
+- `c`: toggle changed-only view
+- `C`: toggle the expanded changed view; enabling it expands every directory containing changes
+- `]` / `[`: next/prev changed file
+- `/`: search (type to filter, `Esc` to exit)
+- `u`: go up one directory (re-root to parent)
+- `.`: jump back to the starting directory
+- `+` / `-`: increase/decrease browser height
+- `q`: close
+
+## Viewer Keybindings
+
+- `j/k` or `↑/↓`: move the line cursor (the viewport follows it)
+- `PgUp/PgDn`: page up/down
+- `g/G`: top/bottom
+- `d`: toggle diff (tracked files only)
+- `m`: toggle rendered/raw view for Markdown files
+- `w`: toggle word wrap (disabled by default)
+- `/`: search (type to search)
+- `n` / `N`: next/prev match
+- `v`: select mode (line selection)
+- `c`: comment on selected lines (inline prompt)
+- `Enter`: new line in the comment editor
+- `Ctrl+Enter` or `Ctrl+D`: send the comment (`Alt+Enter` also works when supported)
+- `]` / `[`: next/prev changed file
+- `+` / `-`: increase/decrease viewer height
+- `q`, `Esc`, or `←`: back to browser
+
+## Notes
+
+- The overlay maximum height is 95% of the terminal; browser and viewer panels start at 85%, and `+` / `-` adjust within that available range.
+- Hidden project files and directories such as `.pi/` and `.github/` are visible; `.git/` and common dependency/build caches remain hidden.
+- Untracked files show as `[UNTRACKED]` and open in normal view.
+- Searching in rendered Markdown switches to raw mode first, and selecting from rendered Markdown first switches you back to raw so line-based matches and comments stay aligned with the source file.
+- When you browse outside the current project directory, inline comments on those files use absolute paths so the agent can still locate them. Files inside the project continue to use project-relative paths.
+- Folder LOCs are shown only when the folder is collapsed (expanded folders would duplicate counts).
+- Line counts load asynchronously; the header shows activity while counts are computed.
+- Large non-git folders load progressively and may show `[partial]` while loading in safe mode.
+- Git status refreshes every 3 seconds while `/readfiles` is open.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-files-widget-overlay",
+  "version": "0.3.0",
+  "description": "In-terminal file browser, viewer, and diff overlay for Pi.",
+  "license": "MIT",
+  "author": "tallshort",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tallshort/pi-files-widget-overlay.git"
+  },
+  "bugs": "https://github.com/tallshort/pi-files-widget-overlay/issues",
+  "homepage": "https://github.com/tallshort/pi-files-widget-overlay#readme",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "benchmark:readfiles": "vite-node benchmarks/readfiles.ts"
+  },
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/tallshort/pi-files-widget-overlay/main/demo.png"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@types/node": "^22.0.0",
+    "@earendil-works/pi-tui": "^0.80.3",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.0"
+  }
+}

package/publish-pi-files-widget-overlay.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+#
+# A wizard walks a human through a manual procedure, step by step.
+# Generated by the /wizard skill.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library: delightful, consistent UX, identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets this at the top of the stages section.
+TOTAL_STAGES=0
+
+_STAGE_INDEX=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear wipes the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" shows the opening frame: what this wizard does.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later, since it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" clears the screen, then announces a stage and shows progress.
+# Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  printf '\n%s%s▸ Stage %s/%s · %s%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET"
+}
+
+# say "..." prints a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." is a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL opens it in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser; visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser, so visit it manually: $url"
+}
+
+# pause "msg" waits for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" is a y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY: current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" reads a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" is like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE upserts KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE sets a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name: gh not ready; set it later"
+}
+
+# set_var NAME VALUE sets a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name, gh not ready; set it later"
+}
+
+# finish clears, then shows a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES: author this section. One stage() per step the human takes.
+# Replace the example below. Set TOTAL_STAGES to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=5
+
+banner "Publish pi-files-widget-overlay"
+
+stage "Create the GitHub repository"
+open_url "https://github.com/new"
+step "Owner: tallshort. Repository name: pi-files-widget-overlay."
+step "Choose Public, and leave README, .gitignore, and license initialization unchecked."
+step "Create the repository; it must be empty because this checkout already has history."
+pause "Press Enter after the repository exists."
+
+stage "Push the existing main branch"
+say "This checkout already uses: https://github.com/tallshort/pi-files-widget-overlay.git"
+step "Run: git ls-remote origin"
+step "Run: git push -u origin main"
+pause "Press Enter after the push succeeds."
+
+stage "Verify the GitHub project"
+open_url "https://github.com/tallshort/pi-files-widget-overlay"
+step "Confirm the default branch is main and the repository shows src/, test/, docs/, README.md, and package.json."
+pause "Press Enter after verification."
+
+stage "Prepare the v0.3.0 Git release"
+step "From the checkout run: npm test && npm run typecheck && npm pack --dry-run"
+step "Review git status --short; it must be empty before tagging."
+step "Run: git tag -a v0.3.0 -m 'Release 0.3.0'"
+step "Run: git push origin main --tags"
+pause "Press Enter after the tag is visible on GitHub."
+
+stage "Publish to npm"
+say "package.json already links the package page to the GitHub repository through its repository field."
+step "Run: npm login"
+step "Run: npm whoami"
+step "Optional availability check: npm view pi-files-widget-overlay version"
+if confirm "Publish version 0.3.0 to npm now?"; then
+  step "Run: npm publish"
+  step "Verify: npm view pi-files-widget-overlay version"
+else
+  note "Skipped npm publish. Re-run this wizard when you are ready."
+fi
+
+finish

package/src/activity.ts

@@ -0,0 +1,10 @@
+import { resolve } from "node:path";
+
+export function getObservedToolActivityPath(toolName: string, input: unknown, cwd: string): string | undefined {
+  if (toolName !== "write" && toolName !== "edit") return undefined;
+  if (!input || typeof input !== "object") return undefined;
+
+  const field = toolName === "write" ? "path" : "file";
+  const path = (input as Record<string, unknown>)[field];
+  return typeof path === "string" && path.trim() ? resolve(cwd, path) : undefined;
+}