pi-superwhisper-paste 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -1,115 +1,127 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-This project follows semantic versioning.
-
-## [0.1.14] - 2026-06-05
-
-### Changed
-
-- Re-add `Code` / `Cursor` host processes to the clipboard-owner denylist so editor-hosted clipboard updates are blocked again during debugging.
-
-## [0.1.13] - 2026-06-05
-
-### Fixed
-
-- Remove `Code.exe` / `Cursor.exe` from the terminal-owner denylist so editor-hosted Superwhisper clipboard updates are not blocked just because Pi is running inside Code/Cursor.
-
-## [0.1.12] - 2026-06-05
-
-### Changed
-
-- Add an explicit `v0.1.12` marker to the status text so stale package loads are visible during live debugging.
-
-## [0.1.11] - 2026-06-05
-
-### Fixed
-
-- Broaden the terminal clipboard-owner denylist with `OpenConsole` / explicit `.exe` variants.
-- Surface the last clipboard decision in the Pi status text (`blocked ...`, `... via ...`) so real-machine owner mismatches can be diagnosed quickly.
-
-## [0.1.10] - 2026-06-05
-
-### Fixed
-
-- Fix the Windows PowerShell clipboard-owner probe script so the owner-aware bridge works in real Pi sessions instead of failing on multiline `Add-Type` syntax.
-
-## [0.1.9] - 2026-06-05
-
-### Fixed
-
-- Replace the strict Superwhisper owner allowlist with a terminal-owner denylist so unknown Superwhisper owner names still auto-paste while terminal/CLI clipboard owners stay blocked.
-
-## [0.1.8] - 2026-06-05
-
-### Fixed
-
-- Filter clipboard updates by clipboard-owner process so Pi auto-pastes only when the clipboard owner looks like Superwhisper.
-- Keep local terminal copy suppression as a fallback for forwarded copy shortcuts while blocking mouse/right-click terminal copies via owner filtering.
-
-## [0.1.7] - 2026-06-05
-
-### Fixed
-
-- Suppress auto-paste for a short window after local terminal copy shortcuts so copying inside the active CLI no longer pastes into Pi.
-- Refresh the clipboard baseline after local copy intent so the bridge keeps waiting for the next Superwhisper clipboard update.
-
-## [0.1.6] - 2026-06-04
-
-### Changed
-
-- Added `version:check` PR guard support: package script + `scripts/check-version-bump.mjs`.
-- Added CI verification that publishable changes must bump `package.json` and update `CHANGELOG.md` in the same PR.
-
-### Fixed
-
-- Truncate clipboard text in PowerShell before writing stdout so huge clipboards no longer exceed Node `maxBuffer` on extension load.
-- Treat clipboard read failures (including `maxBuffer`) as empty reads so `session_start` never surfaces as an extension error.
-
-## [0.1.5] - 2026-06-03
-
-## [0.1.4] - 2026-06-03
-
-### Changed
-
-- Clarify that `pi-superwhisper-paste` is the Windows clipboard-based package.
-- Point users to `@superwhisper/pi` only for the official deeplink/macOS flow.
-- Update npm package metadata to match the revived Windows-focused positioning.
-
-## [0.1.3] - 2026-06-03
-
-### Changed
-
-- Mark the package as archived in README and `package.json` description.
-- Point new installs to the official Superwhisper Pi extension: `pi install npm:@superwhisper/pi`.
-
-## [0.1.2] - 2026-06-01
-
-### Fixed
-
-- Register `/sw-paste:on` and `/sw-paste:off` as Pi slash commands so they appear in command autocomplete.
-
-### Changed
-
-- Clarify that the Superwhisper paste controls are slash-autocomplete commands.
-
-## [0.1.1] - 2026-05-31
-
-### Added
-
-- Add automatic GitHub release creation for version bumps on `main`.
-- Add manual and release-published npm publish entrypoints for Trusted Publishing.
-
-### Changed
-
-- Align CI and publish workflows with the maintained Pi OSS release pattern.
-- Skip npm publish when the exact package version is already published.
-
-## [0.1.0] - YYYY-MM-DD
-
-### Added
-
-- Initial Superwhisper paste bridge extension for Pi on Windows.
-- Default-on clipboard watcher with `/sw-paste:on` and `/sw-paste:off` controls.
-- CI and npm Trusted Publishing workflow from the Pi extension template.
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.1.16] - 2026-06-27
+
+### Changed
+
+- Align README with the current Pi extension template structure while preserving Windows install guidance and behavior notes.
+
+## [0.1.15] - 2026-06-05
+
+### Changed
+
+- Remove stale template-maintenance docs (`github-template.md`, `repository-settings.md`, `typescript.md`) from the published package.
+
+## [0.1.14] - 2026-06-05
+
+### Changed
+
+- Re-add `Code` / `Cursor` host processes to the clipboard-owner denylist so editor-hosted clipboard updates are blocked again during debugging.
+
+## [0.1.13] - 2026-06-05
+
+### Fixed
+
+- Remove `Code.exe` / `Cursor.exe` from the terminal-owner denylist so editor-hosted Superwhisper clipboard updates are not blocked just because Pi is running inside Code/Cursor.
+
+## [0.1.12] - 2026-06-05
+
+### Changed
+
+- Add an explicit `v0.1.12` marker to the status text so stale package loads are visible during live debugging.
+
+## [0.1.11] - 2026-06-05
+
+### Fixed
+
+- Broaden the terminal clipboard-owner denylist with `OpenConsole` / explicit `.exe` variants.
+- Surface the last clipboard decision in the Pi status text (`blocked ...`, `... via ...`) so real-machine owner mismatches can be diagnosed quickly.
+
+## [0.1.10] - 2026-06-05
+
+### Fixed
+
+- Fix the Windows PowerShell clipboard-owner probe script so the owner-aware bridge works in real Pi sessions instead of failing on multiline `Add-Type` syntax.
+
+## [0.1.9] - 2026-06-05
+
+### Fixed
+
+- Replace the strict Superwhisper owner allowlist with a terminal-owner denylist so unknown Superwhisper owner names still auto-paste while terminal/CLI clipboard owners stay blocked.
+
+## [0.1.8] - 2026-06-05
+
+### Fixed
+
+- Filter clipboard updates by clipboard-owner process so Pi auto-pastes only when the clipboard owner looks like Superwhisper.
+- Keep local terminal copy suppression as a fallback for forwarded copy shortcuts while blocking mouse/right-click terminal copies via owner filtering.
+
+## [0.1.7] - 2026-06-05
+
+### Fixed
+
+- Suppress auto-paste for a short window after local terminal copy shortcuts so copying inside the active CLI no longer pastes into Pi.
+- Refresh the clipboard baseline after local copy intent so the bridge keeps waiting for the next Superwhisper clipboard update.
+
+## [0.1.6] - 2026-06-04
+
+### Changed
+
+- Added `version:check` PR guard support: package script + `scripts/check-version-bump.mjs`.
+- Added CI verification that publishable changes must bump `package.json` and update `CHANGELOG.md` in the same PR.
+
+### Fixed
+
+- Truncate clipboard text in PowerShell before writing stdout so huge clipboards no longer exceed Node `maxBuffer` on extension load.
+- Treat clipboard read failures (including `maxBuffer`) as empty reads so `session_start` never surfaces as an extension error.
+
+## [0.1.5] - 2026-06-03
+
+## [0.1.4] - 2026-06-03
+
+### Changed
+
+- Clarify that `pi-superwhisper-paste` is the Windows clipboard-based package.
+- Point users to `@superwhisper/pi` only for the official deeplink/macOS flow.
+- Update npm package metadata to match the revived Windows-focused positioning.
+
+## [0.1.3] - 2026-06-03
+
+### Changed
+
+- Mark the package as archived in README and `package.json` description.
+- Point new installs to the official Superwhisper Pi extension: `pi install npm:@superwhisper/pi`.
+
+## [0.1.2] - 2026-06-01
+
+### Fixed
+
+- Register `/sw-paste:on` and `/sw-paste:off` as Pi slash commands so they appear in command autocomplete.
+
+### Changed
+
+- Clarify that the Superwhisper paste controls are slash-autocomplete commands.
+
+## [0.1.1] - 2026-05-31
+
+### Added
+
+- Add automatic GitHub release creation for version bumps on `main`.
+- Add manual and release-published npm publish entrypoints for Trusted Publishing.
+
+### Changed
+
+- Align CI and publish workflows with the maintained Pi OSS release pattern.
+- Skip npm publish when the exact package version is already published.
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+
+- Initial Superwhisper paste bridge extension for Pi on Windows.
+- Default-on clipboard watcher with `/sw-paste:on` and `/sw-paste:off` controls.
+- CI and npm Trusted Publishing workflow from the Pi extension template.

package/README.md

@@ -1,21 +1,64 @@
 # Pi Superwhisper Paste
 
-> Windows-focused Pi bridge for Superwhisper clipboard input.
->
-> The official Superwhisper Pi package (`@superwhisper/pi`) targets the deeplink/macOS flow. If you need the clipboard-based Windows workaround, use this package.
-
 [![CI](https://github.com/eiei114/pi-superwhisper-paste/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-superwhisper-paste/actions/workflows/ci.yml)
 [![Publish](https://github.com/eiei114/pi-superwhisper-paste/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-superwhisper-paste/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pi-superwhisper-paste.svg)](https://www.npmjs.com/package/pi-superwhisper-paste)
+[![npm downloads](https://img.shields.io/npm/dm/pi-superwhisper-paste.svg)](https://www.npmjs.com/package/pi-superwhisper-paste)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+
+> Windows-focused Pi bridge that pastes Superwhisper clipboard output into Pi's TUI editor.
+
+## What this is
+
+Superwhisper can paste dictated text into normal Windows apps, but terminal TUIs can be a rough edge. In the original case, dictation worked in Notepad and PowerShell, and Typeless worked in Pi, but Superwhisper's automatic paste did not reliably reach Pi's TUI editor without a manual `Ctrl+V`.
+
+This package bridges that gap from the Pi side: it watches the Windows clipboard, detects new Superwhisper output, and inserts it into the active Pi editor with Pi's extension API.
+
+The official Superwhisper Pi package (`@superwhisper/pi`) targets the deeplink/macOS flow. If you need the clipboard-based Windows workaround, use this package.
+
+## Features
+
+- Default-on after the extension loads on Windows.
+- Slash commands: `/sw-paste:on` and `/sw-paste:off`.
+- Windows clipboard polling with active-tab gating.
+- Brief copy-suppression window so local terminal copy actions do not get auto-pasted back into Pi.
+- Clipboard-owner filtering so terminal/CLI-owned clipboard updates stay blocked by default.
+
+## Install
 
-## Recommended install on Windows
+Install the published npm package with Pi:
 
 ```bash
 pi install npm:pi-superwhisper-paste
 ```
 
-## Official package
+Pin a specific version when you want reproducible installs:
+
+```bash
+pi install npm:pi-superwhisper-paste@0.1.16
+```
+
+Install into the current project instead of your user Pi settings:
+
+```bash
+pi install npm:pi-superwhisper-paste -l
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/eiei114/pi-superwhisper-paste
+```
+
+Try it without permanently installing:
+
+```bash
+pi -e npm:pi-superwhisper-paste
+```
+
+### Official Superwhisper package
 
 If you are using the official Superwhisper Pi integration instead:
 
@@ -25,40 +68,63 @@ pi install npm:@superwhisper/pi
 
 Docs: https://superwhisper.com/pi
 
-## Why this package exists
+## Quick start
 
-Superwhisper can paste dictated text into normal Windows apps, but terminal TUIs can be a rough edge. In the original case, dictation worked in Notepad and PowerShell, and Typeless worked in Pi, but Superwhisper's automatic paste did not reliably reach Pi's TUI editor without a manual `Ctrl+V`.
+After install, start Pi and dictate with Superwhisper. New Superwhisper clipboard output should auto-paste into the active Pi editor when the bridge is on.
 
-This package bridges that gap from the Pi side: it watches the Windows clipboard, detects new Superwhisper output, and inserts it into the active Pi editor with Pi's extension API.
+Toggle the bridge at runtime:
 
-## Install
+```txt
+/sw-paste:off
+/sw-paste:on
+```
 
-From npm:
+Try this package locally from a clone:
 
 ```bash
-pi install npm:pi-superwhisper-paste
+pi -e .
 ```
 
-From GitHub:
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/index.ts` | Pi TypeScript extension entrypoint |
+| `docs/examples.md` | Usage examples |
+| `docs/release.md` | Trusted Publishing release flow |
+| `docs/template-checklist.md` | Maintainer template checklist |
+| `CHANGELOG.md` | Version history |
+| `LICENSE` | MIT license |
+
+## Development
 
 ```bash
-pi install git:github.com/eiei114/pi-superwhisper-paste
+npm install
+npm run ci
 ```
 
-## Current behavior
+## Release
 
-- Default-on after the extension loads.
-- Slash commands: `/sw-paste:on` and `/sw-paste:off`.
-- Windows clipboard polling with active-tab gating.
-- Brief copy-suppression window so local terminal copy actions do not get auto-pasted back into Pi.
-- Clipboard-owner filtering so terminal/CLI-owned clipboard updates stay blocked by default.
+This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
+
+```bash
+npm version patch
+git push
+```
+
+See [`docs/release.md`](docs/release.md) for setup details.
+
+## Security
+
+Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
 
-See [CHANGELOG.md](CHANGELOG.md) for version history.
+For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
 
 ## Links
 
-- Windows package: https://www.npmjs.com/package/pi-superwhisper-paste
+- npm: https://www.npmjs.com/package/pi-superwhisper-paste
 - GitHub: https://github.com/eiei114/pi-superwhisper-paste
+- Issues: https://github.com/eiei114/pi-superwhisper-paste/issues
 - Official Superwhisper Pi package: https://superwhisper.com/pi — `@superwhisper/pi` on npm (`pi install npm:@superwhisper/pi`)
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-superwhisper-paste",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Superwhisper clipboard bridge for Pi on Windows.",
   "type": "module",
   "license": "MIT",

package/docs/github-template.md

@@ -1,43 +0,0 @@
-# GitHub Template Repository
-
-Enable template mode on the source repository:
-
-```txt
-GitHub repo → Settings → General → Template repository
-```
-
-Create a public repository from the template:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --public \
-  --template OWNER/pi-extension-template \
-  --clone
-```
-
-Create a private repository from the template:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --private \
-  --template OWNER/pi-extension-template \
-  --clone
-```
-
-Include all branches if needed:
-
-```bash
-gh repo create OWNER/new-pi-extension \
-  --public \
-  --template OWNER/pi-extension-template \
-  --include-all-branches \
-  --clone
-```
-
-After creation:
-
-```bash
-cd new-pi-extension
-npm install
-npm run ci
-```

package/docs/repository-settings.md

@@ -1,40 +0,0 @@
-# Repository Settings
-
-Use this file after creating a real repository from the template.
-
-## GitHub About
-
-Suggested fields:
-
-- Description: Bridge Superwhisper clipboard dictation into the Pi TUI editor on Windows.
-- Website: npm package URL or project docs URL
-- Topics:
-  - `pi`
-  - `pi-package`
-  - `pi-extension`
-  - `superwhisper`
-  - `clipboard`
-  - `windows`
-  - `typescript`
-
-## Template mode
-
-This repository is a concrete package, not a template. Do not enable template mode unless it is intentionally turned into a reusable starter.
-
-## Branch protection
-
-Recommended for public packages:
-
-- Require pull request before merging
-- Require status checks to pass
-- Require `CI` workflow
-- Block force pushes on the default branch
-
-## npm package page
-
-After first publish:
-
-- Confirm README renders correctly
-- Confirm package provenance appears
-- Confirm package contents are intentional
-- Add npm URL to GitHub About and README

package/docs/typescript.md

@@ -1,75 +0,0 @@
-# TypeScript Guide
-
-This is a TypeScript-first Pi package template.
-
-## Layout
-
-```txt
-extensions/*.ts      Pi extension entrypoints
-lib/*.ts             Shared TypeScript helpers
-skills/*/SKILL.md    Agent Skills
-prompts/*.md         Prompt templates
-themes/*.json        Themes
-tests/*.test.mjs     Smoke tests
-tests/*.test.ts      Optional TypeScript tests if you add a TS test runner
-```
-
-Pi loads TypeScript extensions directly, so no build step is required for normal use.
-
-## Strict mode
-
-`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
-
-## Extension entrypoints
-
-Two entrypoint styles are shown:
-
-- `extensions/hello.ts`: single-file extension
-- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
-
-For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
-
-## TypeBox schemas
-
-Use TypeBox schemas for custom tool parameters.
-
-```ts
-import { Type } from "typebox";
-
-const parameters = Type.Object({
-  name: Type.String({ description: "Name to greet" }),
-});
-```
-
-## String enums
-
-For string choices, use the local `StringEnum` helper from `lib/schema.ts`.
-
-```ts
-import { StringEnum } from "../lib/schema.ts";
-
-const mode = StringEnum(["short", "friendly"], {
-  description: "Greeting style",
-});
-```
-
-This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
-
-## Runtime dependencies vs peer dependencies
-
-Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
-
-Use `peerDependencies` for:
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-ai`
-- `@earendil-works/pi-tui`
-- `typebox`
-
-Use `dependencies` for runtime packages your extension imports that Pi does not provide.
-
-Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
-
-## Package contents
-
-Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.