@juicesharp/rpiv-args 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 juicesharp
+
+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,202 @@
+# @juicesharp/rpiv-args
+
+[![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-args.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-args)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Pi extension that adds placeholder substitution to skill arguments. When you
+invoke `/skill:<name> <args>`, rpiv-args substitutes placeholders inside the
+skill body — `$1`, `$ARGUMENTS`, `$@`, `${@:2}`, `${@:2:3}` — before the
+content reaches the LLM. Skills without placeholders emit a `<skill>` wrapper
+byte-identical to Pi's built-in, so installing rpiv-args never changes
+behavior for existing skills.
+
+## Install
+
+```
+pi install npm:@juicesharp/rpiv-args
+```
+
+Or run `/rpiv-setup` if you have `@juicesharp/rpiv-pi` installed.
+
+## Placeholders
+
+| Placeholder | Replaced with | Example |
+|---|---|---|
+| `$1`, `$2`, … | Positional argument (1-indexed) | `/skill:foo a b c` → `$1` = `a`, `$2` = `b` |
+| `$ARGUMENTS` | All arguments as a single string | `/skill:foo a b c` → `a b c` |
+| `$@` | Same as `$ARGUMENTS` | `/skill:foo a b c` → `a b c` |
+| `${@:N}` | Arguments from position N onward | `/skill:foo a b c` → `${@:2}` = `b c` |
+| `${@:N:L}` | L arguments starting at position N | `/skill:foo a b c d` → `${@:2:2}` = `b c` |
+
+**Indexing is 1-based** — `$1` is the first argument, `$2` is the second.
+Out-of-range positions resolve to an empty string. For `${@:N[:L]}`, `N` is
+clamped to `≥ 1` and out-of-range slices yield an empty string.
+
+Multi-word values use shell-style quoting:
+
+```
+/skill:deploy "staging server" --force
+```
+
+→ `$1` = `staging server`, `$2` = `--force`, `$ARGUMENTS` = `staging server --force`
+
+## How it works
+
+rpiv-args intercepts the `input` event (fires before Pi's built-in skill
+expansion). When a skill body contains at least one placeholder, the extension:
+
+1. Parses arguments using shell-style quoting
+2. Substitutes all placeholders in the body
+3. Wraps the result in a `<skill>` block byte-identical to Pi's native format
+4. Appends the raw arguments after the block — matches Pi's standard output so any tool that parses `<skill>` blocks continues to work unchanged
+
+When no placeholders are found in the skill body, the output is byte-identical
+to Pi's built-in expansion — zero behavioral change.
+
+## Writing skills with arguments
+
+### `$ARGUMENTS` vs `$1` — which to use
+
+Use **`$ARGUMENTS`** (or `$@`) when the input is freeform text the LLM should
+interpret naturally:
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue by number or description
+---
+
+Fix the following issue: $ARGUMENTS
+```
+
+```
+/skill:fix-issue login page crashes on mobile
+```
+
+→ `Fix the following issue: login page crashes on mobile`
+
+Use **`$1`, `$2`** only for skills with a fixed, structured invocation pattern:
+
+```yaml
+---
+name: migrate-component
+description: Migrate a component between frameworks
+---
+
+Migrate the $1 component from $2 to $3.
+Preserve all existing behavior and tests.
+```
+
+```
+/skill:migrate-component SearchBar React Vue
+```
+
+→ `Migrate the SearchBar component from React to Vue.`
+
+### Why this matters
+
+If a positional skill receives natural language input:
+
+```
+/skill:migrate-component can you migrate the search bar please
+```
+
+→ `Migrate the can component from you to migrate.` — **broken**.
+
+The LLM is good at interpreting `$ARGUMENTS` as a whole, but positional
+placeholders blindly split on spaces. Use `$ARGUMENTS` unless your skill has
+a strict arg structure.
+
+### `argument-hint` frontmatter
+
+Add an `argument-hint` to document what the skill expects:
+
+```yaml
+---
+name: fix-issue
+description: Fix a GitHub issue
+argument-hint: [issue-number-or-description]
+---
+```
+
+```yaml
+---
+name: migrate-component
+description: Migrate a component between frameworks
+argument-hint: [component] [from] [to]
+---
+```
+
+rpiv-args ignores this field — substitution is triggered by placeholders in the body, not the hint.
+
+**Note**: Pi currently surfaces `argument-hint` in autocomplete for prompt
+templates (`commands/*.md`) but **not** for skills (`/skill:<name>`). The
+field is read by Pi but not displayed in the `/skill:` autocomplete UI at
+present — treat it as documentation metadata until upstream Pi exposes it.
+
+### Full example
+
+<details>
+<summary>Deploy skill — SKILL.md, invocation, and the exact text the LLM sees</summary>
+
+```yaml
+---
+name: deploy
+description: Deploy a service to an environment
+argument-hint: [service] [environment]
+---
+
+Deploy service $1 to $2.
+
+## Steps
+1. Run the test suite for $1
+2. Build the Docker image
+3. Push to the $2 registry
+4. Verify the deployment
+```
+
+```
+/skill:deploy api production
+```
+
+→ The LLM receives:
+
+```xml
+<skill name="deploy" location="...">
+Deploy service api to production.
+
+## Steps
+1. Run the test suite for api
+2. Build the Docker image
+3. Push to the production registry
+4. Verify the deployment
+</skill>
+
+api production
+```
+
+Note: the raw arguments (`api production`) are also appended after the
+`</skill>` block — this is Pi's standard behavior and is preserved for
+backward compatibility.
+
+</details>
+
+## Backward compatibility
+
+- Skills **without** placeholders → output is byte-identical to Pi's built-in expansion
+- Skills **with** placeholders → body gets substitution, raw args still appended after block
+- The `argument-hint` frontmatter field is read but not enforced in v1
+
+## Limitations
+
+| Limitation | Detail |
+|---|---|
+| **No type validation** | `$1` expecting a file path receives whatever the user types |
+| **No flag parsing** | `--env=prod` is a single positional token, not a parsed flag |
+| **Literal substitution** | Placeholders are replaced even inside code blocks and inline code |
+| **`steer()`/`followUp()` paths** | `session.steer()` / `session.followUp()` bypass the `input` event (see `agent-session.js:861-887`); placeholders are **not** resolved on those paths. Use the primary prompt path for argument-substituted skills. |
+| **No recursive substitution** | A `$ARGUMENTS` value containing `$1` is not re-expanded |
+
+## License
+
+MIT

package/args.ts

@@ -0,0 +1,194 @@
+/**
+ * rpiv-args — core logic.
+ *
+ * Intercepts `/skill:<name> <args>` at the input hook and emits a byte-exact
+ * Pi skill wrapper with opt-in $N/$ARGUMENTS/$@/${@:N[:L]} substitution on
+ * the body. Falls through (returns {action:"continue"}) when the text is not
+ * a skill command, the skill is unknown, or the body contains no tokens —
+ * keeping Pi's built-in behavior 100% intact for today's 17 rpiv-pi skills.
+ *
+ * Byte-exact wrapper requirement: parseSkillBlock regex at
+ * node_modules/@mariozechner/pi-coding-agent/dist/core/agent-session.js:40
+ * is the load-bearing contract. Do not reformat the template literal below.
+ */
+
+import { readFileSync } from "node:fs";
+import {
+	type ExtensionAPI,
+	type InputEvent,
+	type InputEventResult,
+	loadSkills,
+	parseFrontmatter,
+	type Skill,
+	stripFrontmatter,
+} from "@mariozechner/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Tokens
+// ---------------------------------------------------------------------------
+
+/** Matches any placeholder Pi's substituteArgs would replace. Used as the
+ *  opt-in gate: absent → pass through verbatim (D2). */
+const TOKEN_REGEX = /\$(?:\d+|ARGUMENTS|@|\{@:\d+(?::\d+)?\})/;
+
+/** Prefix Pi uses (`agent-session.js:829`). Single-space tokenisation (D7). */
+const SKILL_PREFIX = "/skill:";
+
+/** Re-entrancy guard (D8). */
+const WRAPPED_PREFIX = "<skill ";
+
+// ---------------------------------------------------------------------------
+// Tokeniser — byte-equivalent to Pi's parseCommandArgs at
+// node_modules/@mariozechner/pi-coding-agent/dist/core/prompt-templates.js:11-42
+// ---------------------------------------------------------------------------
+
+export function parseCommandArgs(argsString: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let inQuote: string | null = null;
+	for (let i = 0; i < argsString.length; i++) {
+		const char = argsString[i];
+		if (inQuote) {
+			if (char === inQuote) {
+				inQuote = null;
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (char === " " || char === "\t") {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+	if (current) args.push(current);
+	return args;
+}
+
+// ---------------------------------------------------------------------------
+// Substitutor — byte-equivalent to Pi's substituteArgs at
+// node_modules/@mariozechner/pi-coding-agent/dist/core/prompt-templates.js:54-82
+// Order matters: $N first, then ${@:N[:L]}, then $ARGUMENTS, then $@.
+// ---------------------------------------------------------------------------
+
+export function substituteArgs(content: string, args: string[]): string {
+	let result = content;
+	result = result.replace(/\$(\d+)/g, (_, num) => args[parseInt(num, 10) - 1] ?? "");
+	result = result.replace(/\$\{@:(\d+)(?::(\d+))?\}/g, (_, startStr, lengthStr) => {
+		let start = parseInt(startStr, 10) - 1;
+		if (start < 0) start = 0;
+		if (lengthStr) {
+			const length = parseInt(lengthStr, 10);
+			return args.slice(start, start + length).join(" ");
+		}
+		return args.slice(start).join(" ");
+	});
+	const allArgs = args.join(" ");
+	result = result.replace(/\$ARGUMENTS/g, allArgs);
+	result = result.replace(/\$@/g, allArgs);
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Skill-path index — populated once, refreshed on session_start(reason:reload)
+// ---------------------------------------------------------------------------
+
+interface SkillIndexEntry {
+	readonly name: string;
+	readonly filePath: string;
+	readonly baseDir: string;
+}
+
+let skillIndex: Map<string, SkillIndexEntry> | null = null;
+
+export function invalidateSkillIndex(): void {
+	skillIndex = null;
+}
+
+/** Build the name→path index by asking Pi for its currently-loaded skills. */
+function buildSkillIndex(): Map<string, SkillIndexEntry> {
+	const { skills } = loadSkills({ cwd: process.cwd() });
+	const index = new Map<string, SkillIndexEntry>();
+	for (const s of skills as Skill[]) {
+		index.set(s.name, { name: s.name, filePath: s.filePath, baseDir: s.baseDir });
+	}
+	return index;
+}
+
+function getSkillIndex(): Map<string, SkillIndexEntry> {
+	if (!skillIndex) skillIndex = buildSkillIndex();
+	return skillIndex;
+}
+
+// ---------------------------------------------------------------------------
+// Wrapper emit — byte-exact against parseSkillBlock regex at
+// node_modules/@mariozechner/pi-coding-agent/dist/core/agent-session.js:40
+// and byte-equivalent to _expandSkillCommand's output at :840-841.
+// ---------------------------------------------------------------------------
+
+function buildSkillBlock(entry: SkillIndexEntry, body: string): string {
+	return `<skill name="${entry.name}" location="${entry.filePath}">\nReferences are relative to ${entry.baseDir}.\n\n${body}\n</skill>`;
+}
+
+function appendArgs(skillBlock: string, args: string): string {
+	return args ? `${skillBlock}\n\n${args}` : skillBlock;
+}
+
+// ---------------------------------------------------------------------------
+// Input handler
+// ---------------------------------------------------------------------------
+
+export function handleInput(event: InputEvent): InputEventResult {
+	const text = event.text;
+
+	// D8 re-entrancy: already-wrapped text (from our own or any other
+	// extension's {action:"transform"}) passes through untouched.
+	if (text.startsWith(WRAPPED_PREFIX)) return { action: "continue" };
+
+	if (!text.startsWith(SKILL_PREFIX)) return { action: "continue" };
+
+	// D7 single-space tokenisation — byte-match Pi's indexOf(" ") at :831.
+	const spaceIndex = text.indexOf(" ");
+	const skillName = spaceIndex === -1 ? text.slice(SKILL_PREFIX.length) : text.slice(SKILL_PREFIX.length, spaceIndex);
+	const argsString = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+
+	const entry = getSkillIndex().get(skillName);
+	if (!entry) return { action: "continue" }; // unknown skill — let Pi handle it
+
+	let content: string;
+	try {
+		content = readFileSync(entry.filePath, "utf-8");
+	} catch {
+		return { action: "continue" }; // let Pi emit its error via _expandSkillCommand
+	}
+
+	const { frontmatter } = parseFrontmatter<{ "argument-hint"?: string }>(content);
+	void frontmatter; // informational only in v1 — D3
+	const body = stripFrontmatter(content).trim();
+
+	// D2 opt-in gate: if body has no token, emit byte-identical to Pi's :841.
+	if (!TOKEN_REGEX.test(body)) {
+		return { action: "transform", text: appendArgs(buildSkillBlock(entry, body), argsString) };
+	}
+
+	const parsed = parseCommandArgs(argsString);
+	const substituted = substituteArgs(body, parsed);
+	return { action: "transform", text: appendArgs(buildSkillBlock(entry, substituted), argsString) };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerArgsHandler(pi: ExtensionAPI): void {
+	pi.on("input", (event) => handleInput(event));
+	pi.on("session_start", (event) => {
+		if (event.reason === "reload" || event.reason === "startup") {
+			invalidateSkillIndex();
+		}
+	});
+}

package/index.ts

@@ -0,0 +1,13 @@
+/**
+ * rpiv-args — Pi extension entry point.
+ *
+ * Registers the `input` event handler + a `session_start` cache invalidator.
+ * All logic lives in args.ts.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerArgsHandler } from "./args.js";
+
+export default function (pi: ExtensionAPI): void {
+	registerArgsHandler(pi);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@juicesharp/rpiv-args",
+  "version": "0.9.0",
+  "description": "Pi extension: skill-argument resolver — pre-emptively wraps /skill:<name> <args> via the input hook and performs opt-in $N/$ARGUMENTS substitution before Pi's built-in expansion",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "rpiv",
+    "skills",
+    "arguments"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "juicesharp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juicesharp/rpiv-mono.git",
+    "directory": "packages/rpiv-args"
+  },
+  "homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-args#readme",
+  "bugs": {
+    "url": "https://github.com/juicesharp/rpiv-mono/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "args.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}