@ilya-lesikov/pi-pi 0.1.0

package/3p/pi-plannotator/packages/server/vcs.ts

@@ -0,0 +1,80 @@
+import {
+  type DiffType,
+  type GitDiffOptions,
+  type VcsProvider,
+  createGitProvider,
+  createJjProvider,
+  createVcsApi,
+  resolveInitialDiffType,
+} from "@plannotator/shared/vcs-core";
+import {
+  detectP4Workspace,
+  getP4Context,
+  getP4FileContentsForDiff,
+  runP4Diff,
+} from "./p4";
+import { runtime as gitRuntime } from "./git";
+import { runtime as jjRuntime } from "./jj";
+
+const p4Provider: VcsProvider = {
+  id: "p4",
+
+  async detect(cwd?: string): Promise<boolean> {
+    return (await detectP4Workspace(cwd)) !== null;
+  },
+
+  ownsDiffType(diffType: string): boolean {
+    return diffType === "p4-default" || diffType.startsWith("p4-changelist:");
+  },
+
+  getContext: getP4Context,
+
+  runDiff(diffType: DiffType, _defaultBranch: string, cwd?: string, _options?: GitDiffOptions) {
+    return runP4Diff(diffType, cwd);
+  },
+
+  getFileContents(diffType, _defaultBranch, filePath, _oldPath?, cwd?) {
+    return getP4FileContentsForDiff(diffType, filePath, cwd);
+  },
+};
+
+const api = createVcsApi([
+  createJjProvider(jjRuntime),
+  createGitProvider(gitRuntime),
+  p4Provider,
+]);
+
+export const {
+  detectVcs,
+  detectManagedVcs,
+  getVcsContext,
+  detectRemoteDefaultCompareTarget,
+  prepareLocalReviewDiff,
+  runVcsDiff,
+  getVcsFileContentsForDiff,
+  canStageFiles,
+  stageFile,
+  unstageFile,
+  resolveVcsCwd,
+} = api;
+
+export { resolveInitialDiffType, gitRuntime };
+
+export type {
+  DiffOption,
+  DiffType,
+  GitContext,
+  GitDiffOptions,
+  VcsProvider,
+  VcsSelection,
+  WorktreeInfo,
+} from "@plannotator/shared/vcs-core";
+
+export {
+  JJ_TRUNK_REVSET,
+  jjCompareTargetRevset,
+  jjLineBaseRevset,
+  parseRemoteBookmark,
+  parseWorktreeDiffType,
+  validateFilePath,
+} from "@plannotator/shared/vcs-core";

package/3p/pi-plannotator/packages/shared/agent-jobs.ts

@@ -0,0 +1,132 @@
+/**
+ * Agent Jobs — shared types, state machine, and SSE helpers.
+ *
+ * Runtime-agnostic: no node:fs, no node:http, no Bun APIs.
+ * Both the Bun server handler and (future) Node handler import
+ * this module and wrap it with their respective HTTP transport layers.
+ *
+ * Mirrors packages/shared/external-annotation.ts in structure.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type AgentJobStatus = "starting" | "running" | "done" | "failed" | "killed";
+
+/**
+ * Snapshot of the diff the reviewer was looking at when this job was launched.
+ * Carried on the job so downstream UIs (agent-result panel "Copy All") export
+ * the same `**Diff:** ...` header the job was actually run against — if the
+ * reviewer switches the UI to a different diff afterwards, the job's snapshot
+ * still reflects truth. Structurally compatible with the UI-side
+ * `FeedbackDiffContext` in `packages/review-editor/utils/exportFeedback.ts`.
+ */
+export interface AgentJobDiffContext {
+  mode: string;
+  base?: string;
+  worktreePath?: string | null;
+}
+
+export interface AgentJobInfo {
+  /** Unique job identifier (UUID). */
+  id: string;
+  /** Source identifier for external annotations — "agent-{id prefix}". */
+  source: string;
+  /** Provider that spawned this job — "claude", "codex", "tour", "shell", etc. */
+  provider: string;
+  /** Underlying engine used (e.g., "claude" or "codex"). Set when provider is "tour". */
+  engine?: string;
+  /** Model used (e.g., "sonnet", "opus"). Set when provider is "tour" with Claude engine. */
+  model?: string;
+  /** Claude --effort level (e.g., "low", "medium", "high", "xhigh", "max"). */
+  effort?: string;
+  /** Codex reasoning effort level (e.g., "high", "medium"). */
+  reasoningEffort?: string;
+  /** Whether Codex fast mode (service_tier=fast) was enabled. */
+  fastMode?: boolean;
+  /** Human-readable label for the job. */
+  label: string;
+  /** Current lifecycle status. */
+  status: AgentJobStatus;
+  /** Timestamp when the job was created. */
+  startedAt: number;
+  /** Timestamp when the job reached a terminal state. */
+  endedAt?: number;
+  /** Process exit code (set on done/failed). */
+  exitCode?: number;
+  /** Last ~500 chars of stderr on failure. */
+  error?: string;
+  /** The actual command that was spawned (for display/debug). */
+  command: string[];
+  /** Working directory where the process was spawned. */
+  cwd?: string;
+  /** The review prompt text (system + user message). Stored separately from command for providers that use stdin. */
+  prompt?: string;
+  /** Review summary set by the agent on completion. */
+  summary?: {
+    correctness: string;
+    explanation: string;
+    confidence: number;
+  };
+  /** PR URL at launch time — used to attribute findings to the correct PR. */
+  prUrl?: string;
+  /** PR diff scope at launch time — "layer" or "full-stack". */
+  diffScope?: string;
+  /** Diff context at launch time (see AgentJobDiffContext). */
+  diffContext?: AgentJobDiffContext;
+}
+
+export interface AgentCapability {
+  id: string;
+  name: string;
+  available: boolean;
+}
+
+export interface AgentCapabilities {
+  mode: "plan" | "review" | "annotate";
+  providers: AgentCapability[];
+  /** True if at least one provider is available. */
+  available: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// SSE event types
+// ---------------------------------------------------------------------------
+
+export type AgentJobEvent =
+  | { type: "snapshot"; jobs: AgentJobInfo[] }
+  | { type: "job:started"; job: AgentJobInfo }
+  | { type: "job:updated"; job: AgentJobInfo }
+  | { type: "job:completed"; job: AgentJobInfo }
+  | { type: "job:log"; jobId: string; delta: string }
+  | { type: "jobs:cleared" };
+
+// ---------------------------------------------------------------------------
+// SSE helpers
+// ---------------------------------------------------------------------------
+
+/** Heartbeat comment to keep SSE connections alive (sent every 30s). */
+export const AGENT_HEARTBEAT_COMMENT = ":\n\n";
+
+/** Interval in ms between heartbeat comments. */
+export const AGENT_HEARTBEAT_INTERVAL_MS = 30_000;
+
+/** Encode an event as an SSE `data:` line. */
+export function serializeAgentSSEEvent(event: AgentJobEvent): string {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a status is terminal (no further transitions). */
+export function isTerminalStatus(status: AgentJobStatus): boolean {
+  return status === "done" || status === "failed" || status === "killed";
+}
+
+/** Generate the source identifier for a job from its ID. */
+export function jobSource(id: string): string {
+  return "agent-" + id.slice(0, 8);
+}

package/3p/pi-plannotator/packages/shared/agents.ts

@@ -0,0 +1,53 @@
+/**
+ * Centralized agent configuration — single source of truth for all supported agents.
+ *
+ * To add a new agent:
+ *   1. Add an entry to AGENT_CONFIG below (origin key, display name, badge CSS classes,
+ *      optional AI provider types)
+ *   2. If detection is via environment variable, add it to the detection chain
+ *      in apps/hook/server/index.ts (detectedOrigin constant)
+ *   3. That's it — all UI components read from this config automatically
+ */
+
+type AgentConfigEntry = {
+  name: string;
+  badge: string;
+  /** AI provider type(s) that naturally match this origin, in preference order. */
+  aiProviderTypes?: readonly string[];
+};
+
+export const AGENT_CONFIG = {
+  'claude-code': { name: 'Claude Code', badge: 'bg-orange-500/15 text-orange-400', aiProviderTypes: ['claude-agent-sdk'] },
+  'amp':         { name: 'Amp',         badge: 'bg-lime-500/15 text-lime-400' },
+  'droid':       { name: 'Droid',       badge: 'bg-cyan-500/15 text-cyan-400' },
+  'kiro-cli':    { name: 'Kiro CLI',    badge: 'bg-amber-500/15 text-amber-400' },
+  'opencode':    { name: 'OpenCode',    badge: 'bg-emerald-500/15 text-emerald-400', aiProviderTypes: ['opencode-sdk'] },
+  'copilot-cli': { name: 'GitHub Copilot', badge: 'bg-blue-500/15 text-blue-400' },
+  'pi':          { name: 'Pi',          badge: 'bg-violet-500/15 text-violet-400', aiProviderTypes: ['pi-sdk'] },
+  'codex':       { name: 'Codex',       badge: 'bg-purple-500/15 text-purple-400', aiProviderTypes: ['codex-sdk'] },
+  'gemini-cli':  { name: 'Gemini CLI', badge: 'bg-sky-500/15 text-sky-400' },
+} as const satisfies Record<string, AgentConfigEntry>;
+
+/** All recognized origin values. */
+export type Origin = keyof typeof AGENT_CONFIG;
+
+/** Resolve an origin to a human-readable agent name. */
+export function getAgentName(origin: Origin | null | undefined): string {
+  if (origin && origin in AGENT_CONFIG) return AGENT_CONFIG[origin as Origin].name;
+  return 'Coding Agent';
+}
+
+/** Resolve an origin to Tailwind badge classes. */
+export function getAgentBadge(origin: Origin | null | undefined): string {
+  if (origin && origin in AGENT_CONFIG) return AGENT_CONFIG[origin as Origin].badge;
+  return 'bg-zinc-500/20 text-zinc-400';
+}
+
+/** Resolve an origin to matching AI provider types, in preference order. */
+export function getAgentAIProviderTypes(origin: Origin | null | undefined): readonly string[] {
+  if (origin && origin in AGENT_CONFIG) {
+    const config = AGENT_CONFIG[origin as Origin];
+    return 'aiProviderTypes' in config ? config.aiProviderTypes : [];
+  }
+  return [];
+}

package/3p/pi-plannotator/packages/shared/annotate-args.test.ts

@@ -0,0 +1,386 @@
+import { describe, test, expect } from "bun:test";
+import { parseAnnotateArgs } from "./annotate-args";
+
+describe("parseAnnotateArgs", () => {
+  test("path only", () => {
+    expect(parseAnnotateArgs("spec.md")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("path with --gate at end", () => {
+    expect(parseAnnotateArgs("spec.md --gate")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--gate before path", () => {
+    expect(parseAnnotateArgs("--gate spec.md")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("path with both flags", () => {
+    expect(parseAnnotateArgs("spec.md --gate --json")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: true,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("flags only, no path", () => {
+    expect(parseAnnotateArgs("--gate --json")).toEqual({
+      filePath: "",
+      rawFilePath: "",
+      gate: true,
+      json: true,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("path with spaces rejoins with single space", () => {
+    expect(parseAnnotateArgs("my file.md --gate")).toEqual({
+      filePath: "my file.md",
+      rawFilePath: "my file.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  // `@` is the reference-mode marker (Claude Code / OpenCode / Pi convention),
+  // not part of the filename. The parser strips it on `filePath` as the primary
+  // behavior — that's the common case. `rawFilePath` preserves the original
+  // for callers that want to try the literal form as a fallback (scoped-package-
+  // style names). See at-reference.ts for the combined helper.
+
+  test("leading @ is stripped (reference-mode primary) and rawFilePath preserves it", () => {
+    expect(parseAnnotateArgs("@spec.md --gate")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "@spec.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("scoped-package-style path: filePath stripped, rawFilePath literal", () => {
+    expect(parseAnnotateArgs("@plannotator/ui/README.md")).toEqual({
+      filePath: "plannotator/ui/README.md",
+      rawFilePath: "@plannotator/ui/README.md",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("@ stripped on filePath when combined with --gate --json, raw preserved", () => {
+    expect(parseAnnotateArgs("@docs/spec.md --gate --json")).toEqual({
+      filePath: "docs/spec.md",
+      rawFilePath: "@docs/spec.md",
+      gate: true,
+      json: true,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("URL passes through", () => {
+    expect(parseAnnotateArgs("https://example.com/docs --gate")).toEqual({
+      filePath: "https://example.com/docs",
+      rawFilePath: "https://example.com/docs",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--no-jina is stripped from URL args", () => {
+    expect(parseAnnotateArgs("https://example.com/docs --no-jina --gate")).toEqual({
+      filePath: "https://example.com/docs",
+      rawFilePath: "https://example.com/docs",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: true,
+    });
+  });
+
+  test("--no-jina before path is stripped", () => {
+    expect(parseAnnotateArgs("--no-jina https://example.com/docs")).toEqual({
+      filePath: "https://example.com/docs",
+      rawFilePath: "https://example.com/docs",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: true,
+    });
+  });
+
+  test("extra whitespace is collapsed", () => {
+    expect(parseAnnotateArgs("  spec.md   --gate  ")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("empty string produces empty result", () => {
+    expect(parseAnnotateArgs("")).toEqual({
+      filePath: "",
+      rawFilePath: "",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("nullish input is tolerated", () => {
+    expect(parseAnnotateArgs(undefined as unknown as string)).toEqual({
+      filePath: "",
+      rawFilePath: "",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("folder path with trailing slash", () => {
+    expect(parseAnnotateArgs("./specs/ --gate --json")).toEqual({
+      filePath: "./specs/",
+      rawFilePath: "./specs/",
+      gate: true,
+      json: true,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  // Regressions from the initial parser: the tokenize-and-rejoin approach
+  // collapsed consecutive whitespace in file paths. Before this branch,
+  // OpenCode and Pi passed the raw args string straight through, so files
+  // with double-spaces or tabs in their names worked fine. These tests pin
+  // that behavior so we don't regress it again.
+
+  test("double-space inside a file path is preserved (flag at end)", () => {
+    expect(parseAnnotateArgs("My  Notes.md --gate")).toEqual({
+      filePath: "My  Notes.md",
+      rawFilePath: "My  Notes.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("double-space inside a file path is preserved (flag at start)", () => {
+    expect(parseAnnotateArgs("--gate My  Notes.md")).toEqual({
+      filePath: "My  Notes.md",
+      rawFilePath: "My  Notes.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("tab inside a file path is preserved", () => {
+    expect(parseAnnotateArgs("My\tNotes.md --gate")).toEqual({
+      filePath: "My\tNotes.md",
+      rawFilePath: "My\tNotes.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("multi-whitespace path with no flags passes through untouched", () => {
+    expect(parseAnnotateArgs("/tmp/My  Notes.md")).toEqual({
+      filePath: "/tmp/My  Notes.md",
+      rawFilePath: "/tmp/My  Notes.md",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  // OpenCode and Pi don't go through a shell, so users who quote paths
+  // (shell muscle memory, copy-paste from docs) have literal quote
+  // characters reach the parser. Strip them at the tokenization layer
+  // so downstream callers don't have to reason about quoting.
+
+  test("wrapping double quotes are stripped from both filePath and rawFilePath", () => {
+    expect(parseAnnotateArgs(`"@foo.md" --gate`)).toEqual({
+      filePath: "foo.md",
+      rawFilePath: "@foo.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("wrapping single quotes are stripped", () => {
+    expect(parseAnnotateArgs(`'@foo.md' --gate`)).toEqual({
+      filePath: "foo.md",
+      rawFilePath: "@foo.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("wrapping quotes around a path with spaces", () => {
+    expect(parseAnnotateArgs(`"@My Notes.md" --gate`)).toEqual({
+      filePath: "My Notes.md",
+      rawFilePath: "@My Notes.md",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("wrapping quotes without @ still get stripped", () => {
+    expect(parseAnnotateArgs(`"My Notes.md"`)).toEqual({
+      filePath: "My Notes.md",
+      rawFilePath: "My Notes.md",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  // --hook emits hook-native JSON ({"decision":"block","reason":"..."}) for
+  // annotations and empty stdout for approve/close. It implies --gate in the
+  // binary, but the parser is a pure tokenizer — it reports which flags were
+  // present without applying implication logic.
+
+  test("--hook alongside --gate", () => {
+    expect(parseAnnotateArgs("spec.md --gate --hook")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: true,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--hook with all three flags", () => {
+    expect(parseAnnotateArgs("spec.md --gate --json --hook")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: true,
+      hook: true,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--hook alone implies gate", () => {
+    expect(parseAnnotateArgs("spec.md --hook")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: true,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--hook before path", () => {
+    expect(parseAnnotateArgs("--hook --gate spec.md")).toEqual({
+      filePath: "spec.md",
+      rawFilePath: "spec.md",
+      gate: true,
+      json: false,
+      hook: true,
+      renderHtml: false,
+      noJina: false,
+    });
+  });
+
+  test("--render-html with HTML file and --gate", () => {
+    expect(parseAnnotateArgs("plan.html --render-html --gate")).toEqual({
+      filePath: "plan.html",
+      rawFilePath: "plan.html",
+      gate: true,
+      json: false,
+      hook: false,
+      renderHtml: true,
+      noJina: false,
+    });
+  });
+
+  test("--render-html alone", () => {
+    expect(parseAnnotateArgs("plan.html --render-html")).toEqual({
+      filePath: "plan.html",
+      rawFilePath: "plan.html",
+      gate: false,
+      json: false,
+      hook: false,
+      renderHtml: true,
+      noJina: false,
+    });
+  });
+});