pi-code 1.0.3 → 1.0.5

package/extensions/init.ts

@@ -0,0 +1,81 @@
+/**
+ * Init Extension
+ *
+ * Claude Code's /init: analyze the codebase and produce a project context file
+ * with build commands, test instructions, and the conventions it discovers; when
+ * a context file already exists, suggest improvements instead of overwriting it.
+ * The handler does no analysis itself. Claude drives /init through the main agent
+ * with tools, and pi's equivalent is pi.sendUserMessage: the handler detects what
+ * exists on disk (existing context file, cursor rules, copilot instructions),
+ * builds one curated prompt, and sends it; the agent then explores the codebase
+ * and writes the file with full tool access. A fresh file is AGENTS.md, the name
+ * pi prefers over CLAUDE.md.
+ *
+ * Docs: https://code.claude.com/docs/en/memory.md
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+import { repoRoot } from './internal/project-root.js'
+
+/** Context files pi recognizes, in its lookup order; the first hit wins. */
+export const CONTEXT_FILE_CANDIDATES = ['AGENTS.override.md', 'AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
+
+function statOf(target: string): fs.Stats | undefined {
+  try {
+    return fs.statSync(target)
+  } catch {
+    return undefined
+  }
+}
+
+/** The name of the first context-file candidate present at the project root. */
+export function findExistingContextFile(root: string): string | undefined {
+  return CONTEXT_FILE_CANDIDATES.find((name) => statOf(path.join(root, name))?.isFile())
+}
+
+export interface InitPromptOptions {
+  /** Name of the context file already at the project root, when one exists. */
+  existingContextFile?: string
+  /** Whether .cursor/rules/ or .cursorrules exists at the project root. */
+  cursorRules?: boolean
+  /** Whether .github/copilot-instructions.md exists at the project root. */
+  copilotRules?: boolean
+}
+
+/** The prompt /init sends to the main agent. Pure so tests can pin its contract. */
+export function buildInitPrompt(opts: InitPromptOptions = {}): string {
+  const parts: string[] = [
+    [
+      'Please analyze this codebase and distill what a coding agent needs to work in it effectively:',
+      '- Build, lint, and test commands, including how to run a single test.',
+      '- Code conventions: formatting, imports, naming, types, error handling.',
+      '- Architecture notes: the big-picture structure that takes reading several files to see.',
+      '- Project layout: the important directories and entry points.',
+    ].join('\n'),
+  ]
+  if (opts.cursorRules) parts.push('Cursor rules exist in this repository (.cursor/rules/ or .cursorrules). Read them and fold the parts that still apply into the context file.')
+  if (opts.copilotRules) parts.push('Copilot instructions exist at .github/copilot-instructions.md. Read them and fold the parts that still apply into the context file.')
+  if (opts.existingContextFile) {
+    parts.push(`A context file already exists at the project root: ${opts.existingContextFile}. Read it, then propose improvements based on what you found and apply the ones that clearly help. Do not overwrite the file wholesale; keep its structure and voice and make targeted edits.`)
+  } else {
+    parts.push('Write the result to AGENTS.md at the project root. Create the file yourself. pi prefers AGENTS.md over CLAUDE.md as its context file, and Claude Code can read it too via an @AGENTS.md import from CLAUDE.md or a symlink.')
+  }
+  parts.push('Keep the file concise and high-signal, under roughly 200 lines. Skip generic advice and anything obvious from a glance at the code.')
+  return parts.join('\n\n')
+}
+
+export default function initExtension(pi: ExtensionAPI) {
+  pi.registerCommand('init', {
+    description: 'Analyze the codebase and create or improve the project context file (AGENTS.md)',
+    handler: async (_args, ctx) => {
+      const root = repoRoot(ctx.cwd) ?? ctx.cwd
+      const existing = findExistingContextFile(root)
+      const cursorRules = statOf(path.join(root, '.cursor', 'rules'))?.isDirectory() === true || statOf(path.join(root, '.cursorrules'))?.isFile() === true
+      const copilotRules = statOf(path.join(root, '.github', 'copilot-instructions.md'))?.isFile() === true
+      pi.sendUserMessage(buildInitPrompt({ ...(existing !== undefined ? { existingContextFile: existing } : {}), cursorRules, copilotRules }))
+    },
+  })
+}

package/extensions/internal/agent-run.ts

@@ -0,0 +1,42 @@
+/**
+ * A one-function seam letting the hooks extension spawn a subagent for Claude's
+ * experimental `type: "agent"` hooks, without importing the subagent extension.
+ *
+ * The subagent extension registers a runner once it is loaded; a hook that needs
+ * to verify a condition with a tool-using agent (Read/Grep/Glob) goes through
+ * runAgent. It is the agentic analogue of the mcp-call seam: if nothing registered
+ * a runner (a stripped-down deployment without the subagent extension), agent hooks
+ * are skipped rather than failing the event.
+ */
+
+export interface AgentRunRequest {
+  /** The agent's task prompt, with `$ARGUMENTS` already substituted. */
+  prompt: string
+  /** Optional model id override; the runner falls back to a fast default. */
+  model?: string
+  /** Optional extra system prompt (Claude's experimental `systemPrompt` field). */
+  systemPrompt?: string
+  /** Aborts the run at the hook's deadline. */
+  signal?: AbortSignal
+}
+
+/** Run a subagent to completion and return its final assistant text. */
+export type AgentRunner = (request: AgentRunRequest) => Promise<string>
+
+let runner: AgentRunner | undefined
+
+/** The subagent extension registers its runner here; pass undefined to clear it. */
+export function setAgentRunner(fn: AgentRunner | undefined): void {
+  runner = fn
+}
+
+/** Whether a runner is registered, so agent hooks can be reported as runnable. */
+export function hasAgentRunner(): boolean {
+  return runner !== undefined
+}
+
+/** Run a subagent for an agent hook. Rejects when no runner is registered. */
+export function runAgent(request: AgentRunRequest): Promise<string> {
+  if (!runner) return Promise.reject(new Error('no subagent runner registered for agent hooks'))
+  return runner(request)
+}

package/extensions/internal/bash-rules.ts

@@ -0,0 +1,27 @@
+/**
+ * Claude's `Bash(...)` argument scopes, enforced at tool_call time.
+ *
+ * A scope like `git add:*` narrows a bash grant to matching commands. pi's
+ * active-tool set has no argument dimension, so commands.ts grants `bash` and
+ * checks each call here instead. Matching follows Claude's documented forms:
+ * a bare specifier is an exact match, `prefix:*` matches any command starting
+ * with the prefix, and `*` elsewhere is a wildcard. Every segment of a compound
+ * command must match some rule, and substitution or an unbalanced quote fails
+ * closed, as plan mode's guard does.
+ */
+
+import { hasSubstitution, splitSegments } from './shell-split.js'
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+
+function matchesRule(segment: string, rule: string): boolean {
+  if (rule.endsWith(':*')) return segment.startsWith(rule.slice(0, -2))
+  if (rule.includes('*')) return new RegExp(`^${rule.split('*').map(escapeRegExp).join('[^]*')}$`).test(segment)
+  return segment === rule
+}
+
+export function matchesBashRules(command: string, rules: string[]): boolean {
+  if (hasSubstitution(command)) return false
+  const segments = splitSegments(command)
+  return segments.length > 0 && segments.every((segment) => rules.some((rule) => matchesRule(segment, rule.trim())))
+}