pi-code 0.8.0 → 0.9.0

package/README.md

@@ -36,7 +36,7 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 | Feature | Reads / provides | Extension |
 |---|---|---|
 | Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
-| Custom slash commands | `.claude/commands/*.md` → pi prompt templates | `commands.ts` |
+| Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`), `$ARGUMENTS`/`$1`, `` !`cmd` `` bash output, `@file` inlining, `allowed-tools`/`model`/`argument-hint` frontmatter; project commands gated on approval | `commands.ts` |
 | Skills | `.claude/skills` → pi skill discovery (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
 | Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd; Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort | `hooks.ts` |
 | Output styles | `.claude/output-styles` + active `outputStyle`; Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |

package/extensions/commands.ts

@@ -1,15 +1,18 @@
 /**
  * Claude Commands Extension
  *
- * Bridges Claude Code's custom slash commands into pi. On resources_discover
- * it hands pi the existing `.claude/commands` directories (user then project)
- * as prompt-template paths, so `/name` invokes `.claude/commands/name.md` the
- * same way pi loads its own `.pi/prompts`. pi's `$ARGUMENTS` / `$1` / `${1:-x}`
- * substitution overlaps Claude Code's, so most command files work unchanged.
+ * Registers Claude Code's custom slash commands with pi directly, rather than
+ * handing `.claude/commands` to pi's prompt-template loader. Owning registration
+ * is what makes the rest of Claude's command contract reachable: namespaced
+ * subdirectories (`frontend/build.md` is `/frontend:build`), `$ARGUMENTS` and
+ * positional substitution, `` !`cmd` `` bash output, `@file` inlining, and the
+ * `allowed-tools` / `model` / `argument-hint` / `disable-model-invocation`
+ * frontmatter.
  *
- * Not bridged (pi's prompt engine ignores them): `!` bash execution, `@` file
- * refs, `allowed-tools`/`model` frontmatter, and namespaced subdirectories
- * (discovery is non-recursive).
+ * A project command body is repository-controlled text that can now run shell
+ * commands and read files, so project commands load only once the project is
+ * approved. That closes the "skills / commands are not trust-gated" limitation
+ * for commands; skills remain pi-loader territory.
  *
  * Docs: https://code.claude.com/docs/en/slash-commands.md
  */
@@ -17,7 +20,13 @@
 import * as fs from 'node:fs'
 import * as os from 'node:os'
 import * as path from 'node:path'
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
+
+import { type DiscoveredCommand, discoverCommandFiles, expandDynamicContent, type ParsedCommand, parseCommandFile, substituteArgs } from './internal/command-file.js'
+import { isProjectApproved } from './internal/project-approval.js'
+
+/** Wall-clock budget for one `` !`cmd` `` span; a hung command must not wedge a turn. */
+const BASH_TIMEOUT_MS = 30_000
 
 function isDirectory(target: string): boolean {
   try {
@@ -27,9 +36,11 @@ function isDirectory(target: string): boolean {
   }
 }
 
-/** Existing `.claude/commands` directories, user first then project. */
-export function commandDirs(cwd: string, home: string): string[] {
-  const candidates = [path.join(home, '.claude', 'commands'), path.join(cwd, '.claude', 'commands')]
+/** Existing `.claude/commands` directories, user first then project. The project
+ * directory is included only for approved projects. */
+export function commandDirs(cwd: string, home: string, trusted: boolean): string[] {
+  const candidates = [path.join(home, '.claude', 'commands')]
+  if (trusted) candidates.push(path.join(cwd, '.claude', 'commands'))
   const dirs: string[] = []
   for (const dir of candidates) {
     if (!dirs.includes(dir) && isDirectory(dir)) dirs.push(dir)
@@ -37,9 +48,64 @@ export function commandDirs(cwd: string, home: string): string[] {
   return dirs
 }
 
+/** All commands across the given directories, later directories winning by name. */
+export function collectCommands(dirs: string[]): DiscoveredCommand[] {
+  const byName = new Map<string, DiscoveredCommand>()
+  for (const dir of dirs) {
+    for (const found of discoverCommandFiles(dir)) byName.set(found.name, found)
+  }
+  return [...byName.values()]
+}
+
 export default function commandsExtension(pi: ExtensionAPI) {
-  pi.on('resources_discover', async (_event, ctx) => {
-    const promptPaths = commandDirs(ctx.cwd, os.homedir())
-    return promptPaths.length > 0 ? { promptPaths } : undefined
+  const registered = new Set<string>()
+
+  async function runCommand(parsed: ParsedCommand, args: string, ctx: ExtensionCommandContext): Promise<void> {
+    const withArgs = substituteArgs(parsed.body, args)
+    const expanded = await expandDynamicContent(withArgs, ctx.cwd, async (shell) => {
+      const result = await pi.exec('/bin/sh', ['-c', shell], { timeout: BASH_TIMEOUT_MS })
+      return { stdout: result.stdout, stderr: result.stderr, code: result.code }
+    })
+
+    // allowed-tools restricts the turn the command drives, then the previous set is
+    // restored: the restriction belongs to the command, not to the rest of the session.
+    const saved = parsed.allowedTools ? pi.getActiveTools() : undefined
+    if (parsed.allowedTools && saved) {
+      pi.setActiveTools(parsed.allowedTools.filter((tool) => saved.includes(tool)))
+    }
+    try {
+      pi.sendUserMessage(expanded)
+    } finally {
+      if (saved) pi.setActiveTools(saved)
+    }
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    const trusted = await isProjectApproved(ctx)
+    for (const command of collectCommands(commandDirs(ctx.cwd, os.homedir(), trusted))) {
+      // pi has no unregister, so a command already registered this process keeps its
+      // original file binding; re-registering would only add a numbered duplicate.
+      if (registered.has(command.name)) continue
+      let parsed: ParsedCommand
+      try {
+        parsed = parseCommandFile(fs.readFileSync(command.filePath, 'utf-8'))
+      } catch {
+        continue // an unreadable command file must not take down session start
+      }
+      registered.add(command.name)
+      pi.registerCommand(command.name, {
+        description: parsed.argumentHint ? `${parsed.description} ${parsed.argumentHint}` : parsed.description,
+        handler: async (args, commandCtx) => {
+          // Re-read on invocation so an edited command file takes effect without a reload.
+          let current = parsed
+          try {
+            current = parseCommandFile(fs.readFileSync(command.filePath, 'utf-8'))
+          } catch {
+            // fall back to what was parsed at registration
+          }
+          await runCommand(current, args, commandCtx)
+        },
+      })
+    }
   })
 }

package/extensions/internal/command-file.ts

@@ -0,0 +1,170 @@
+/**
+ * Parsing and discovery for Claude Code slash-command files.
+ *
+ * pi's own prompt-template loader reads only `description` and `argument-hint`
+ * from one flat directory, so the rest of Claude's command contract (namespaced
+ * subdirectories, `allowed-tools`, `model`, `!` bash blocks, `@file` refs) lives
+ * here and is applied by commands.ts when it registers each command itself.
+ *
+ * Docs: https://code.claude.com/docs/en/slash-commands.md
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+export interface ParsedCommand {
+  description: string
+  argumentHint?: string
+  allowedTools?: string[]
+  model?: string
+  disableModelInvocation: boolean
+  body: string
+}
+
+export interface DiscoveredCommand {
+  /** Claude's namespaced name: a nested file is `dir:name`. */
+  name: string
+  filePath: string
+}
+
+/** Claude tool names are PascalCase; pi's are lowercase. */
+function normalizeToolName(name: string): string {
+  return name.trim().toLowerCase()
+}
+
+function field(frontmatter: string, key: string): string {
+  const match = new RegExp(String.raw`^\s*${key}\s*:\s*(.+)$`, 'm').exec(frontmatter)
+  return match ? match[1].trim().replace(/^["']|["']$/g, '') : ''
+}
+
+export function parseCommandFile(content: string): ParsedCommand {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content)
+  const frontmatter = match ? match[1] : ''
+  const body = (match ? content.slice(match[0].length) : content).trim()
+  const tools = field(frontmatter, 'allowed-tools')
+  const firstLine = body.split('\n').find((line) => line.trim().length > 0) ?? ''
+  return {
+    description: field(frontmatter, 'description') || firstLine.slice(0, 60),
+    argumentHint: field(frontmatter, 'argument-hint') || undefined,
+    allowedTools: tools ? tools.split(',').map(normalizeToolName).filter(Boolean) : undefined,
+    model: field(frontmatter, 'model') || undefined,
+    disableModelInvocation: field(frontmatter, 'disable-model-invocation') === 'true',
+    body,
+  }
+}
+
+/** Split a raw argument string, keeping quoted runs together. */
+export function splitArgs(args: string): string[] {
+  const out: string[] = []
+  const pattern = /"([^"]*)"|'([^']*)'|(\S+)/g
+  let match = pattern.exec(args)
+  while (match !== null) {
+    out.push(match[1] ?? match[2] ?? match[3])
+    match = pattern.exec(args)
+  }
+  return out
+}
+
+/** Claude's substitutions: `$ARGUMENTS`, `$@`, `$1`..`$n`, `${n:-default}`. An
+ * unfilled positional becomes empty rather than leaking its literal token. */
+export function substituteArgs(body: string, args: string): string {
+  const parts = splitArgs(args)
+  return body
+    .replaceAll(/\$\{(\d+):-([^}]*)\}/g, (_m, index: string, fallback: string) => parts[Number(index) - 1] ?? fallback)
+    .replaceAll(/\$\{ARGUMENTS:-([^}]*)\}/g, (_m, fallback: string) => (args.trim() ? args.trim() : fallback))
+    .replaceAll(/\$ARGUMENTS\b/g, args.trim())
+    .replaceAll('$@', args.trim())
+    .replaceAll(/\$(\d+)/g, (_m, index: string) => parts[Number(index) - 1] ?? '')
+}
+
+/** `a/b/c.md` becomes Claude's `a:b:c`. */
+export function commandNameFor(relativePath: string): string {
+  return relativePath.replace(/\.md$/, '').split(path.sep).join(':')
+}
+
+/** Every `*.md` under a commands directory, including nested ones. */
+export function discoverCommandFiles(root: string): DiscoveredCommand[] {
+  const found: DiscoveredCommand[] = []
+  const walk = (dir: string, prefix: string): void => {
+    let entries: fs.Dirent[]
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) walk(full, path.join(prefix, entry.name))
+      else if (entry.name.endsWith('.md')) found.push({ name: commandNameFor(path.join(prefix, entry.name)), filePath: full })
+    }
+  }
+  walk(root, '')
+  return found
+}
+
+export type CommandExec = (command: string) => Promise<{ stdout: string; stderr: string; code: number }>
+
+/** Spans of a body that are inside a fenced code block, where Claude's dynamic
+ * syntax is literal text rather than an instruction. */
+function fencedRanges(body: string): Array<[number, number]> {
+  const ranges: Array<[number, number]> = []
+  const fence = /^(```|~~~)[^\n]*$/gm
+  let open: number | undefined
+  let match = fence.exec(body)
+  while (match !== null) {
+    if (open === undefined) open = match.index
+    else {
+      ranges.push([open, match.index + match[0].length])
+      open = undefined
+    }
+    match = fence.exec(body)
+  }
+  if (open !== undefined) ranges.push([open, body.length])
+  return ranges
+}
+
+const inRanges = (ranges: Array<[number, number]>, index: number): boolean => ranges.some(([start, end]) => index >= start && index < end)
+
+/** Read a `@path` reference, confined to the working directory. Returns undefined
+ * when the path escapes it or cannot be read, so the reference stays literal. */
+function readReference(cwd: string, reference: string): string | undefined {
+  const resolved = path.resolve(cwd, reference)
+  const root = path.resolve(cwd)
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) return undefined
+  try {
+    if (!fs.statSync(resolved).isFile()) return undefined
+    return fs.readFileSync(resolved, 'utf-8')
+  } catch {
+    return undefined
+  }
+}
+
+/** Claude's dynamic command content: `` !`cmd` `` runs a shell command and pastes
+ * its output, `@path` inlines a file. Both are skipped inside fenced code blocks. */
+export async function expandDynamicContent(body: string, cwd: string, exec: CommandExec): Promise<string> {
+  const fenced = fencedRanges(body)
+
+  const commands: Array<{ span: string; command: string; index: number }> = []
+  const bashPattern = /!`([^`]+)`/g
+  let bashMatch = bashPattern.exec(body)
+  while (bashMatch !== null) {
+    if (!inRanges(fenced, bashMatch.index)) commands.push({ span: bashMatch[0], command: bashMatch[1], index: bashMatch.index })
+    bashMatch = bashPattern.exec(body)
+  }
+
+  let expanded = body
+  for (const entry of commands) {
+    const result = await exec(entry.command)
+    const output = result.code === 0 ? result.stdout.trimEnd() : `(command failed: ${entry.command})\n${result.stderr.trim() || result.stdout.trim()}`
+    expanded = expanded.replace(entry.span, output)
+  }
+
+  // Ranges are recomputed: command output can change offsets.
+  const fencedAfter = fencedRanges(expanded)
+  return expanded.replaceAll(/(^|\s)@(\S+)/g, (whole, lead: string, reference: string, offset: number) => {
+    if (inRanges(fencedAfter, offset)) return whole
+    const content = readReference(cwd, reference)
+    if (content === undefined) return whole
+    return `${lead}\n<file path="${reference}">\n${content.trimEnd()}\n</file>\n`
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-code",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Claude Code experience for the pi coding agent: reads your .claude config (rules, commands, skills, hooks, output styles, MCP servers, agents) and adds todo, checkpoints, memory, web, and subagents",
   "keywords": [
     "pi",