@plannotator/pi-extension 0.16.2 → 0.16.3

package/README.md

@@ -63,6 +63,87 @@ When the agent calls `plannotator_submit_plan`, the Plannotator UI opens in your
 
 The agent iterates on the plan until you approve, then executes with full tool access. On resubmission, Plan Diff highlights what changed since the previous version.
 
+### Configuring per-phase behavior
+
+Plannotator loads configuration in three layers:
+
+1. Built-in base config shipped with the package: `plannotator.json`
+2. Global user config: `~/.pi/agent/plannotator.json`
+3. Project-local config: `<cwd>/.pi/plannotator.json`
+
+Later layers overwrite earlier ones. If a field is omitted, it inherits the value from lower-precedence layers. If a value is set to `null`, an empty string, or an empty array, it clears the inherited value instead of merging it. You can also set `defaults` or an entire phase object to `null` to clear all inherited settings from lower-precedence layers.
+
+#### Top-level shape
+
+```json
+{
+  "defaults": {
+    "model": { "provider": "anthropic", "id": "claude-sonnet-4-5" },
+    "thinking": "medium",
+    "activeTools": ["read", "bash"],
+    "statusLabel": "Ready",
+    "systemPrompt": "Optional prompt template"
+  },
+  "phases": {
+    "planning": {
+      "model": null,
+      "thinking": null,
+      "activeTools": ["grep", "find", "ls", "plannotator_submit_plan"],
+      "statusLabel": "⏸ plan",
+      "systemPrompt": "[PLANNING]\nPlan file: ${planFilePath}"
+    },
+    "executing": {
+      "model": { "provider": "anthropic", "id": "claude-sonnet-4-5" },
+      "thinking": "high",
+      "activeTools": [],
+      "statusLabel": "",
+      "systemPrompt": "[EXECUTING]\nRemaining steps:\n${todoList}"
+    },
+    "reviewing": {
+      "systemPrompt": "..."
+    }
+  }
+}
+```
+
+#### Option reference
+
+| Option | Type | Meaning |
+|--------|------|---------|
+| `defaults` | object | Base values applied to every phase before phase-specific overrides |
+| `phases` | object | Phase-specific overrides |
+| `phases.planning` | object | Settings for planning mode |
+| `phases.executing` | object | Settings for execution mode |
+| `phases.reviewing` | object | Reserved for future review-mode customization |
+| `model` | `{ provider, id }` \| `null` | Sets the model for the phase; `null` leaves the current model unchanged |
+| `thinking` | `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `null` | Sets the thinking level; `null` leaves the current level unchanged |
+| `activeTools` | string[] \| `null` | Extra tools to enable for the phase; `[]` or `null` means no extra phase tools |
+| `statusLabel` | string \| `null` | Optional UI label for the phase; empty/null clears it |
+| `systemPrompt` | string \| `null` | Phase system prompt template; empty/null disables prompt injection |
+
+#### Prompt variables
+
+Use these inside `systemPrompt` strings:
+
+- `${planFilePath}` — current plan file path
+- `${todoList}` — remaining checklist items as markdown checkboxes
+- `${completedCount}` — completed checklist count
+- `${totalCount}` — total checklist count
+- `${remainingCount}` — remaining checklist count
+- `${phase}` — current runtime phase (`planning`, `executing`, `reviewing`, or `idle`)
+
+#### Behavior notes
+
+- Unknown template variables trigger a warning in the UI and are rendered as empty strings.
+- `activeTools` are additive with the tools currently active in the session, so Plannotator still preserves tools provided by other extensions.
+- Execution progress remains dynamic (`[DONE:n]` + checklist tracking), even if `statusLabel` is set.
+
+#### Example files
+
+- Built-in base config shipped with the package: `apps/pi-extension/plannotator.json`
+- Global user override: `~/.pi/agent/plannotator.json`
+- Project-local override: `<cwd>/.pi/plannotator.json`
+
 ### Code review
 
 Run `/plannotator-review` to open your current git changes in the code review UI. Annotate specific lines, switch between diff views (uncommitted, staged, last commit, branch), and submit feedback that gets sent to the agent.

package/config.ts

@@ -0,0 +1,318 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
+
+export type PhaseName = "planning" | "executing" | "reviewing";
+export type RuntimePhase = PhaseName | "idle";
+
+export interface PhaseModelRef {
+  provider: string;
+  id: string;
+}
+
+/**
+ * Config values loaded from JSON can intentionally clear inherited values.
+ *
+ * - `null` clears a value from a parent config.
+ * - `[]` clears active tools.
+ * - `""` clears string values.
+ */
+export interface PhaseProfile {
+  model?: PhaseModelRef | null;
+  thinking?: ThinkingLevel | null;
+  activeTools?: string[] | null;
+  statusLabel?: string | null;
+  systemPrompt?: string | null;
+}
+
+export interface PlannotatorConfig {
+  defaults?: PhaseProfile | null;
+  phases?: Partial<Record<PhaseName, PhaseProfile | null>>;
+}
+
+export interface LoadedPlannotatorConfig {
+  config: PlannotatorConfig;
+  warnings: string[];
+}
+
+export interface ResolvedPhaseProfile {
+  model?: PhaseModelRef;
+  thinking?: ThinkingLevel;
+  activeTools?: string[];
+  statusLabel?: string;
+  systemPrompt?: string;
+}
+
+export interface PromptVariables {
+  planFilePath: string;
+  todoList: string;
+  completedCount: number;
+  totalCount: number;
+  remainingCount: number;
+  phase: RuntimePhase;
+}
+
+export interface PromptRenderResult {
+  text: string;
+  unknownVariables: string[];
+}
+
+const INTERNAL_CONFIG_PATH = join(dirname(fileURLToPath(import.meta.url)), "plannotator.json");
+const PHASES: PhaseName[] = ["planning", "executing", "reviewing"];
+const THINKING_LEVELS = new Set<string>(["minimal", "low", "medium", "high", "xhigh"]);
+
+function getAgentConfigDir(): string {
+  const envDir = process.env.PI_CODING_AGENT_DIR;
+  if (envDir) return envDir;
+  return join(process.env.HOME || process.env.USERPROFILE || homedir(), ".pi", "agent");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readJsonFile(path: string): { data?: unknown; error?: string } {
+  if (!existsSync(path)) return {};
+
+  try {
+    return { data: JSON.parse(readFileSync(path, "utf-8")) };
+  } catch (error) {
+    return { error: `Failed to parse ${path}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
+function normalizeModel(value: unknown): PhaseModelRef | null | undefined {
+  if (value === null) return null;
+  if (!isRecord(value)) return undefined;
+
+  const provider = typeof value.provider === "string" ? value.provider.trim() : "";
+  const id = typeof value.id === "string" ? value.id.trim() : "";
+  if (!provider || !id) return undefined;
+  return { provider, id };
+}
+
+function normalizeThinking(value: unknown): ThinkingLevel | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  return THINKING_LEVELS.has(trimmed as ThinkingLevel) ? (trimmed as ThinkingLevel) : undefined;
+}
+
+function normalizeTools(value: unknown): string[] | null | undefined {
+  if (value === null) return null;
+  if (!Array.isArray(value)) return undefined;
+  if (value.length === 0) return [];
+
+  const tools = value.filter((tool): tool is string => typeof tool === "string" && tool.trim().length > 0);
+  return tools.length > 0 ? tools : undefined;
+}
+
+function normalizeLabel(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizePrompt(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  if (typeof value !== "string") return undefined;
+  return value.length > 0 ? value : null;
+}
+
+function normalizeProfile(raw: unknown): PhaseProfile | null | undefined {
+  if (raw === null) return null;
+  if (!isRecord(raw)) return undefined;
+
+  const profile: PhaseProfile = {};
+
+  if ("model" in raw) profile.model = normalizeModel(raw.model);
+  if ("thinking" in raw) profile.thinking = normalizeThinking(raw.thinking);
+  if ("thinkingLevel" in raw && profile.thinking === undefined) profile.thinking = normalizeThinking(raw.thinkingLevel);
+  if ("activeTools" in raw) profile.activeTools = normalizeTools(raw.activeTools);
+  if ("statusLabel" in raw) profile.statusLabel = normalizeLabel(raw.statusLabel);
+  if ("systemPrompt" in raw) profile.systemPrompt = normalizePrompt(raw.systemPrompt);
+
+  return profile;
+}
+
+function cloneProfile(profile: PhaseProfile | null | undefined): PhaseProfile | null | undefined {
+  if (profile === null || profile === undefined) return profile;
+  return { ...profile, activeTools: profile.activeTools ? [...profile.activeTools] : profile.activeTools };
+}
+
+function mergeProfile(base: PhaseProfile | null | undefined, override: PhaseProfile | null | undefined): PhaseProfile | null | undefined {
+  if (override === null) return null;
+  if (override === undefined) return cloneProfile(base);
+  if (base === null || base === undefined) return cloneProfile(override);
+
+  const merged: PhaseProfile = {
+    model: override.model !== undefined ? override.model : base.model,
+    thinking: override.thinking !== undefined ? override.thinking : base.thinking,
+    activeTools: override.activeTools !== undefined ? override.activeTools : base.activeTools,
+    statusLabel: override.statusLabel !== undefined ? override.statusLabel : base.statusLabel,
+    systemPrompt: override.systemPrompt !== undefined ? override.systemPrompt : base.systemPrompt,
+  };
+
+  return merged;
+}
+
+function mergeConfig(base: PlannotatorConfig, override: PlannotatorConfig): PlannotatorConfig {
+  const phases: Partial<Record<PhaseName, PhaseProfile | null>> = {};
+  for (const phase of PHASES) {
+    const merged = mergeProfile(base.phases?.[phase], override.phases?.[phase]);
+    if (merged !== undefined) phases[phase] = merged;
+  }
+
+  return {
+    defaults: mergeProfile(base.defaults, override.defaults),
+    phases: Object.keys(phases).length > 0 ? phases : undefined,
+  };
+}
+
+function loadConfigSource(path: string): { config: PlannotatorConfig; warning?: string } {
+  const parsed = readJsonFile(path);
+  if (parsed.error) {
+    return { config: {}, warning: parsed.error };
+  }
+
+  const raw = parsed.data;
+  if (!isRecord(raw)) return { config: {} };
+
+  const config: PlannotatorConfig = {};
+  if ("defaults" in raw) config.defaults = normalizeProfile(raw.defaults);
+
+  if ("phases" in raw && isRecord(raw.phases)) {
+    const phases: Partial<Record<PhaseName, PhaseProfile | null>> = {};
+    for (const phase of PHASES) {
+      const normalized = normalizeProfile(raw.phases[phase]);
+      if (normalized !== undefined) phases[phase] = normalized;
+    }
+    if (Object.keys(phases).length > 0) config.phases = phases;
+  }
+
+  return { config };
+}
+
+export function loadPlannotatorConfig(cwd: string): LoadedPlannotatorConfig {
+  const warnings: string[] = [];
+
+  const internal = loadConfigSource(INTERNAL_CONFIG_PATH);
+  if (internal.warning) warnings.push(internal.warning);
+
+  const globalPath = join(getAgentConfigDir(), "plannotator.json");
+  const globalConfig = loadConfigSource(globalPath);
+  if (globalConfig.warning) warnings.push(globalConfig.warning);
+
+  const projectPath = join(cwd, ".pi", "plannotator.json");
+  const projectConfig = loadConfigSource(projectPath);
+  if (projectConfig.warning) warnings.push(projectConfig.warning);
+
+  const merged = mergeConfig(mergeConfig(internal.config, globalConfig.config), projectConfig.config);
+  return { config: merged, warnings };
+}
+
+export function resolvePhaseProfile(config: PlannotatorConfig, phase: PhaseName): ResolvedPhaseProfile {
+  const defaults = config.defaults ?? {};
+  const phaseConfig = config.phases?.[phase] ?? {};
+
+  return {
+    model: resolveModel(defaults.model, phaseConfig.model),
+    thinking: resolveThinking(defaults.thinking, phaseConfig.thinking),
+    activeTools: resolveTools(defaults.activeTools, phaseConfig.activeTools),
+    statusLabel: resolveString(defaults.statusLabel, phaseConfig.statusLabel),
+    systemPrompt: resolveString(defaults.systemPrompt, phaseConfig.systemPrompt),
+  };
+}
+
+function resolveModel(base: PhaseModelRef | null | undefined, override: PhaseModelRef | null | undefined): PhaseModelRef | undefined {
+  if (override !== undefined) {
+    return override ?? undefined;
+  }
+  return base ?? undefined;
+}
+
+function resolveThinking(base: ThinkingLevel | null | undefined, override: ThinkingLevel | null | undefined): ThinkingLevel | undefined {
+  if (override !== undefined) {
+    return override ?? undefined;
+  }
+  return base ?? undefined;
+}
+
+function resolveTools(base: string[] | null | undefined, override: string[] | null | undefined): string[] | undefined {
+  if (override !== undefined) {
+    if (override === null) return [];
+    return [...override];
+  }
+  if (base === null) return [];
+  return base ? [...base] : undefined;
+}
+
+function resolveString(base: string | null | undefined, override: string | null | undefined): string | undefined {
+  if (override !== undefined) {
+    if (override === null || override === "") return undefined;
+    return override;
+  }
+  return base ?? undefined;
+}
+
+export function buildPromptVariables(options: {
+  planFilePath: string;
+  phase: RuntimePhase;
+  totalCount: number;
+  completedCount: number;
+  remainingCount?: number;
+  todoList?: string;
+}): PromptVariables {
+  const totalCount = options.totalCount;
+  const completedCount = options.completedCount;
+  const remainingCount = options.remainingCount ?? Math.max(totalCount - completedCount, 0);
+
+  return {
+    planFilePath: options.planFilePath,
+    todoList: options.todoList ?? "",
+    completedCount,
+    totalCount,
+    remainingCount,
+    phase: options.phase,
+  };
+}
+
+export function renderTemplate(template: string, vars: PromptVariables): PromptRenderResult {
+  const unknownVariables = new Set<string>();
+  const text = template.replace(/\$\{([a-zA-Z0-9_]+)\}/g, (_match, key: string) => {
+    if (key in vars) {
+      const value = vars[key as keyof PromptVariables];
+      return value === undefined || value === null ? "" : String(value);
+    }
+    unknownVariables.add(key);
+    return "";
+  });
+
+  return { text, unknownVariables: [...unknownVariables] };
+}
+
+export function formatTodoList(items: Array<{ step: number; text: string; completed: boolean }>): {
+  todoList: string;
+  completedCount: number;
+  totalCount: number;
+  remainingCount: number;
+} {
+  const totalCount = items.length;
+  const completedCount = items.filter((item) => item.completed).length;
+  const remainingItems = items.filter((item) => !item.completed);
+  const todoList = remainingItems.length
+    ? remainingItems.map((item) => `- [ ] ${item.step}. ${item.text}`).join("\n")
+    : "";
+
+  return {
+    todoList,
+    completedCount,
+    totalCount,
+    remainingCount: remainingItems.length,
+  };
+}

package/generated/review-core.ts

@@ -175,9 +175,20 @@ async function getUntrackedFileDiffs(
   dstPrefix = "b/",
   cwd?: string,
 ): Promise<string> {
+  // git ls-files scopes to the CWD subtree and returns CWD-relative paths,
+  // unlike git diff HEAD which always covers the full repo with root-relative
+  // paths.  Resolve the repo root so untracked files from the entire repo are
+  // included and their paths match the tracked-diff output.
+  const toplevelResult = await runtime.runGit(
+    ["rev-parse", "--show-toplevel"],
+    { cwd },
+  );
+  const rootCwd =
+    toplevelResult.exitCode === 0 ? toplevelResult.stdout.trim() : cwd;
+
   const lsResult = await runtime.runGit(
     ["ls-files", "--others", "--exclude-standard"],
-    { cwd },
+    { cwd: rootCwd },
   );
   if (lsResult.exitCode !== 0) return "";
 
@@ -200,7 +211,7 @@ async function getUntrackedFileDiffs(
           "/dev/null",
           file,
         ],
-        { cwd },
+        { cwd: rootCwd },
       );
       return diffResult.stdout;
     }),