pi-must-have-extension 0.4.0 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.4.3] - 2026-03-04
+
+### Fixed
+- Use GitHub-compatible video embed format (thumbnail image linking to user-attachments video URL)
+
+## [0.4.2] - 2026-03-04
+
+### Fixed
+- Restored missing asset references in README (demo.mp4 video and pi-must-have-extension.png image)
+
+## [0.4.1] - 2026-03-04
+
+### Changed
+- Rewrote README.md with professional documentation standards
+- Added comprehensive feature documentation, configuration reference, and usage examples
+- Improved legacy config path detection with centralized lookup
+- Added migration source tracking to config loader feedback
+
 ## 0.4.0 - 2026-03-02
 
 - Renamed package identity from `pi-must-have-plugin` to `pi-must-have-extension`.

package/README.md

@@ -1,111 +1,177 @@
 # pi-must-have-extension
 
-Normalize RFC 2119 language in Pi prompts by automatically rewriting lowercase modal terms (for example `must`, `should not`, `optional`) into uppercase normative forms (`MUST`, `SHOULD NOT`, `OPTIONAL`).
+Normalize RFC 2119 language in Pi prompts by automatically rewriting lowercase modal terms (`must`, `should not`, `optional`) into uppercase normative forms (`MUST`, `SHOULD NOT`, `OPTIONAL`).
 
-## Origin
-
-This extension originated from the OpenCode plugin project: [ariane-emory/MUST-have-plugin](https://github.com/ariane-emory/MUST-have-plugin).
-
-`pi-must-have-extension` is a Pi-harness adaptation of that original project, converted into a modular TypeScript Pi extension.
-
-## Preview
+![pi-must-have-extension](asset/pi-must-have-extension.png)
 
-![pi-must-have-extension overview](https://raw.githubusercontent.com/MasuRii/pi-must-have-extension/main/asset/pi-must-have-extension.png)
+## Demo
 
 [![Watch demo video](https://raw.githubusercontent.com/MasuRii/pi-must-have-extension/main/asset/pi-must-have-extension.png)](https://github.com/user-attachments/assets/22149125-8976-4d06-98cb-e7cfa180476d)
 
-> npmjs.com README rendering does not reliably support inline `<video>` playback. Use the thumbnail above to play the demo video.
-
-Direct links:
-- Demo video (GitHub attachment): https://github.com/user-attachments/assets/22149125-8976-4d06-98cb-e7cfa180476d
-- Demo video file: https://raw.githubusercontent.com/MasuRii/pi-must-have-extension/main/asset/demo.mp4
-
 ## Features
 
-- Rewrites configurable keywords during normal prompt input.
-- Case-insensitive matching with longest-first phrase replacement.
-- Word-boundary-aware matching (does not replace inside larger words).
-- Leaves slash commands and shell-prefixed input unchanged.
-- Auto-creates a default config when none exists.
-- Supports legacy config path migration warnings.
-- Optional debug notifications in Pi TUI with replacement count/details in console logs.
+- **RFC 2119/8174 compliance** — Transforms modal keywords to standard uppercase notation
+- **Intelligent matching** — Case-insensitive with longest-first phrase replacement
+- **Word-boundary aware** — Does not replace keywords embedded inside larger words
+- **Configurable replacements** — Customize or extend the default keyword mappings
+- **Input filtering** — Leaves slash commands (`/`) and shell input (`!`) unchanged
+- **Auto-configuration** — Creates a default config file when none exists
+- **Legacy migration** — Automatically migrates configs from previous plugin versions
+- **Debug mode** — Optional TUI notifications showing replacement counts
 
 ## Installation
 
-### Local extension folder
+### Local Extension Folder
 
-Copy this repository to:
+Copy this repository to one of the following locations:
 
-- Global: `~/.pi/agent/extensions/pi-must-have-extension`
-- Project: `.pi/extensions/pi-must-have-extension`
+```text
+~/.pi/agent/extensions/pi-must-have-extension     # Global (all projects)
+.pi/extensions/pi-must-have-extension             # Project-specific
+```
 
-Pi will auto-discover it.
+Pi will auto-discover the extension on startup.
 
-### NPM package
+### NPM Package
 
 ```bash
 pi install npm:pi-must-have-extension
 ```
 
-## Configuration
+## Usage
 
-Runtime config path:
+Once installed, the extension works automatically. When you type prompts containing RFC 2119 keywords:
 
+**Input:**
 ```text
-~/.pi/agent/extensions/pi-must-have-extension/config.jsonc
+The function must validate input and should log errors.
+```
+
+**Transformed to:**
+```text
+The function MUST validate input and SHOULD log errors.
 ```
 
-Legacy fallback paths (read-only fallback):
+### Skipped Input
+
+The extension does not transform:
+
+- Slash commands (e.g., `/help`, `/reload`)
+- Shell commands (e.g., `!ls`, `!git status`)
+- Empty input
+
+## Configuration
+
+The extension uses a JSONC configuration file (JSON with comments):
 
 ```text
-~/.pi/agent/extensions/pi-must-have-plugin/config.jsonc
-~/.pi/agent/extensions/must-have-plugin/config.jsonc
-~/.config/opencode/MUST-have-plugin.jsonc
+~/.pi/agent/extensions/pi-must-have-extension/config.jsonc
 ```
 
-Example config template is included at `config/config.example.jsonc`.
+### Default Configuration
 
 ```jsonc
 {
-  "debug": false,
+  // Enable debug notifications in the TUI
+  // "debug": true,
+
   "replacements": {
     "must": "MUST",
     "must not": "MUST NOT",
-    "should": "SHOULD"
+    "required": "REQUIRED",
+    "shall": "SHALL",
+    "shall not": "SHALL NOT",
+    "should": "SHOULD",
+    "should not": "SHOULD NOT",
+    "recommended": "RECOMMENDED",
+    "not recommended": "NOT RECOMMENDED",
+    "may": "MAY",
+    "optional": "OPTIONAL"
   }
 }
 ```
 
-An advanced replacement sample adapted from the original project is also included at:
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Enable TUI notifications showing replacement counts |
+| `replacements` | `object` | RFC 2119 defaults | Key-value map of terms to replace |
+
+### Custom Replacements
+
+You can add custom replacement rules or modify existing ones:
+
+```jsonc
+{
+  "replacements": {
+    // Standard RFC 2119
+    "must": "MUST",
+    "should": "SHOULD",
+    
+    // Custom shortcuts
+    "rfc!": "The key words in this document are to be interpreted as described in RFC 2119.\n\n",
+    "always": "**ALWAYS**",
+    "never": "**NEVER**"
+  }
+}
+```
+
+An advanced replacement sample is included at `config/replacements.custom-sample.jsonc`.
+
+### Legacy Config Paths
+
+The extension supports migration from previous versions. Legacy configs are read from:
 
 ```text
-config/replacements.custom-sample.jsonc
+~/.pi/agent/extensions/pi-must-have-plugin/config.jsonc
+~/.pi/agent/extensions/must-have-plugin/config.jsonc
+~/.config/opencode/MUST-have-plugin.jsonc
 ```
 
-You can copy selected entries from that sample into your runtime `config.jsonc`.
+On first run, legacy configs are automatically migrated to the new location.
+
+## Technical Details
+
+### How It Works
+
+1. **Session start**: Ensures config exists (creates default or migrates legacy)
+2. **Input event**: Intercepts user prompts before sending to the agent
+3. **Pattern matching**: Uses regex with word boundaries and longest-match-first ordering
+4. **Transformation**: Returns modified text while preserving images and other input data
 
-## Development
+### Project Structure
+
+```text
+├── index.ts                 # Pi extension entrypoint
+├── src/
+│   ├── index.ts             # Extension event wiring
+│   ├── constants.ts         # Paths, defaults, and extension name
+│   ├── types.ts             # TypeScript interfaces
+│   ├── config/
+│   │   ├── config-loader.ts # Config loading and migration
+│   │   └── jsonc.ts         # JSONC parser (strips comments)
+│   └── replacements/
+│       └── replacement-engine.ts  # Core replacement logic
+├── config/
+│   ├── config.example.jsonc           # Starter template
+│   └── replacements.custom-sample.jsonc  # Advanced samples
+└── test/
+    └── replacement-engine.test.ts     # Unit tests
+```
+
+### Development
 
 ```bash
-npm install
-npm run build
-npm run lint
-npm run test
-npm run check
+npm install          # Install dependencies
+npm run build        # Type-check with TypeScript
+npm run test         # Run test suite
+npm run check        # Build + test
 ```
 
-## Project Structure
-
-- `index.ts` - Pi auto-discovery entrypoint.
-- `src/index.ts` - extension event wiring.
-- `src/config/` - config loading and JSONC parsing.
-- `src/replacements/` - replacement and input-skip engine.
-- `src/constants.ts` - extension constants and defaults.
-- `src/types.ts` - shared types.
-- `test/` - Node test suite.
-- `config/config.example.jsonc` - starter config template.
-- `config/replacements.custom-sample.jsonc` - advanced custom replacement sample.
-- `asset/` - README media (overview image and demo video).
+## Origin
+
+This extension is a Pi-harness adaptation of [ariane-emory/MUST-have-plugin](https://github.com/ariane-emory/MUST-have-plugin), converted into a modular TypeScript Pi extension.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-must-have-extension",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "RFC 2119 keyword normalizer extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/src/config/config-loader.ts

@@ -52,24 +52,44 @@ function parseConfigFromPath(path: string): Omit<ConfigLoadResult, "source"> {
 	};
 }
 
+const LEGACY_CONFIG_PATHS: readonly string[] = [
+	LEGACY_PI_MUST_HAVE_PLUGIN_CONFIG_PATH,
+	LEGACY_MUST_HAVE_PLUGIN_CONFIG_PATH,
+	LEGACY_OPENCODE_CONFIG_PATH,
+];
+
+function findLegacyConfigPath(): string | undefined {
+	for (const path of LEGACY_CONFIG_PATHS) {
+		if (existsSync(path)) {
+			return path;
+		}
+	}
+
+	return undefined;
+}
+
 export function ensureConfigExists(): EnsureConfigResult {
-	if (
-		existsSync(CONFIG_PATH) ||
-		existsSync(LEGACY_PI_MUST_HAVE_PLUGIN_CONFIG_PATH) ||
-		existsSync(LEGACY_MUST_HAVE_PLUGIN_CONFIG_PATH) ||
-		existsSync(LEGACY_OPENCODE_CONFIG_PATH)
-	) {
+	if (existsSync(CONFIG_PATH)) {
 		return { created: false };
 	}
 
+	const legacyPath = findLegacyConfigPath();
+
 	try {
 		mkdirSync(CONFIG_DIR, { recursive: true });
+
+		if (legacyPath) {
+			const legacyContent = readFileSync(legacyPath, "utf-8");
+			writeFileSync(CONFIG_PATH, legacyContent, "utf-8");
+			return { created: true, migratedFrom: legacyPath };
+		}
+
 		writeFileSync(CONFIG_PATH, DEFAULT_CONFIG, "utf-8");
 		return { created: true };
 	} catch (error) {
 		return {
 			created: false,
-			error: `Failed to create default config at ${CONFIG_PATH}: ${error instanceof Error ? error.message : String(error)}`,
+			error: `Failed to initialize config at ${CONFIG_PATH}: ${error instanceof Error ? error.message : String(error)}`,
 		};
 	}
 }

package/src/index.ts

@@ -49,6 +49,12 @@ export default function mustHaveExtension(pi: ExtensionAPI): void {
 		if (ensureResult.error) {
 			warnOnce(ensureResult.error, ctx);
 		}
+		if (ensureResult.migratedFrom) {
+			warnOnce(
+				`${EXTENSION_NAME}: migrated legacy config from ${ensureResult.migratedFrom} to ${CONFIG_PATH}.`,
+				ctx,
+			);
+		}
 
 		const loaded = loadConfig();
 		if (loaded.warning) {

package/src/types.ts

@@ -11,6 +11,7 @@ export interface ConfigLoadResult {
 
 export interface EnsureConfigResult {
 	created: boolean;
+	migratedFrom?: string;
 	error?: string;
 }