pi-x-ide 0.1.0

package/src/pi/ui.ts

@@ -0,0 +1,85 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent" with { "resolution-mode": "import" };
+import { describeRanges } from "../shared/format";
+import { toRelativeDisplayPath } from "../shared/paths";
+import type { PiIdeRuntime } from "./state";
+
+export function updateIdeUi(runtime: PiIdeRuntime, ctx: ExtensionContext | undefined = runtime.ctx): void {
+  if (!ctx?.hasUI) return;
+
+  ctx.ui.setWidget(
+    "pi-x-ide",
+    (_tui, theme) => ({
+      render(width: number): string[] {
+        const status = buildStatusLine(runtime, ctx.cwd);
+        const text = truncatePlainStatus(status, width);
+        const pad = " ".repeat(Math.max(0, width - text.length));
+        const color = isPendingEditorContext(runtime) ? "success" : "dim";
+        return [pad + theme.fg(color, text)];
+      },
+      invalidate() {},
+    }),
+    { placement: "aboveEditor" },
+  );
+}
+
+export function clearIdeUi(runtime: PiIdeRuntime, ctx: ExtensionContext | undefined = runtime.ctx): void {
+  if (!ctx?.hasUI) return;
+  ctx.ui.setWidget("pi-x-ide", undefined);
+}
+
+function truncatePlainStatus(text: string, width: number): string {
+  if (width <= 0) return "";
+  if (text.length <= width) return text;
+  if (width <= 3) return ".".repeat(width);
+  return `${text.slice(0, width - 3)}...`;
+}
+
+function isPendingEditorContext(runtime: PiIdeRuntime): boolean {
+  return !!runtime.latestSelection && runtime.attachState === "pending";
+}
+
+export function buildStatusLine(runtime: PiIdeRuntime, cwd?: string): string {
+  if (!runtime.enabled || runtime.connectionStatus === "disabled") return "IDE: off";
+  if (runtime.connectionStatus === "connecting") return "IDE: connecting";
+  if (runtime.connectionStatus === "error")
+    return `IDE: error${runtime.connectionMessage ? ` ${runtime.connectionMessage}` : ""}`;
+  if (runtime.connectionStatus !== "connected") return "IDE: disconnected";
+
+  const ide = runtime.connectedServer?.ide ?? runtime.currentCandidate?.lock.ide ?? "ide";
+  const selection = runtime.latestSelection;
+  if (!selection) return `IDE: ${ide} ✓`;
+  const rel = toRelativeDisplayPath(selection.filePath, selection.workspaceFolder, cwd);
+  const range = describeRanges(selection.ranges);
+  return `IDE: ${ide} ✓ ${rel}${range === "open file" ? "" : range} ${runtime.attachState}`;
+}
+
+export function buildWidget(runtime: PiIdeRuntime, cwd?: string): string[] | undefined {
+  if (!runtime.enabled || runtime.connectionStatus === "disabled") return undefined;
+  if (
+    runtime.connectionStatus !== "connected" &&
+    runtime.connectionStatus !== "connecting" &&
+    runtime.connectionStatus !== "error"
+  ) {
+    return undefined;
+  }
+
+  const lines: string[] = [];
+  const ide = runtime.connectedServer?.name ?? runtime.currentCandidate?.lock.name ?? "IDE";
+  lines.push(`IDE: ${ide} (${runtime.connectionStatus})`);
+
+  if (runtime.currentCandidate) {
+    lines.push(`Workspace: ${runtime.currentCandidate.workspaceFolder}`);
+  }
+
+  if (runtime.latestSelection) {
+    const selection = runtime.latestSelection;
+    lines.push(`File: ${toRelativeDisplayPath(selection.filePath, selection.workspaceFolder, cwd)}`);
+    lines.push(`Range: ${describeRanges(selection.ranges)}`);
+    lines.push(`Attach: ${runtime.attachState}`);
+    if (selection.receivedAt) lines.push(`Updated: ${new Date(selection.receivedAt).toLocaleTimeString()}`);
+  } else if (runtime.connectionMessage) {
+    lines.push(runtime.connectionMessage);
+  }
+
+  return lines;
+}

package/src/shared/format.ts

@@ -0,0 +1,95 @@
+import type { EditorSelectionSnapshot, SelectionRange } from "./protocol";
+import { toRelativeDisplayPath } from "./paths";
+
+export type RangeFormat = "comma" | "dash";
+
+export function rangeToLineSpan(range: SelectionRange): { startLine: number; endLine: number } {
+  return {
+    startLine: range.selection.start.line + 1,
+    endLine: range.selection.end.line + 1,
+  };
+}
+
+export function formatLineSpan(range: SelectionRange, format: RangeFormat = "comma"): string {
+  const { startLine, endLine } = rangeToLineSpan(range);
+  if (startLine === endLine) return `#L${startLine}`;
+  return format === "dash" ? `#L${startLine}-L${endLine}` : `#L${startLine},${endLine}`;
+}
+
+export function formatRangeMention(
+  snapshot: EditorSelectionSnapshot,
+  options: { cwd?: string; format?: RangeFormat } = {},
+): string {
+  const rel = toRelativeDisplayPath(snapshot.filePath, snapshot.workspaceFolder, options.cwd);
+  const first = snapshot.ranges[0];
+  return first ? `@${rel}${formatLineSpan(first, options.format)}` : `@${rel}`;
+}
+
+export interface ParsedRangeMention {
+  path: string;
+  startLine?: number;
+  endLine?: number;
+}
+
+export function parseRangeMention(input: string): ParsedRangeMention | undefined {
+  const match = input.trim().match(/^@(.+?)(?:#L(\d+)(?:(?:,|-L?)(\d+))?)?$/);
+  if (!match) return undefined;
+  const startLine = match[2] ? Number(match[2]) : undefined;
+  const endLine = match[3] ? Number(match[3]) : startLine;
+  if (startLine !== undefined && (!Number.isInteger(startLine) || startLine < 1)) return undefined;
+  if (endLine !== undefined && (!Number.isInteger(endLine) || endLine < 1)) return undefined;
+  return { path: match[1], startLine, endLine };
+}
+
+export function describeRanges(ranges: SelectionRange[], format: RangeFormat = "comma"): string {
+  if (ranges.length === 0) return "open file";
+  if (ranges.length === 1) return formatLineSpan(ranges[0], format);
+  return ranges.map((range, index) => `${index + 1}:${formatLineSpan(range, format)}`).join(" ");
+}
+
+export function snapshotKey(snapshot: EditorSelectionSnapshot): string {
+  return JSON.stringify({
+    source: snapshot.source,
+    filePath: snapshot.filePath,
+    workspaceFolder: snapshot.workspaceFolder,
+    ranges: snapshot.ranges.map((range) => ({
+      start: range.selection.start,
+      end: range.selection.end,
+      textLength: range.text.length,
+    })),
+  });
+}
+
+export function formatEditorContext(
+  snapshot: EditorSelectionSnapshot,
+  options: { cwd?: string; maxChars?: number } = {},
+): string {
+  const rel = toRelativeDisplayPath(snapshot.filePath, snapshot.workspaceFolder, options.cwd);
+  const maxChars = options.maxChars ?? 24_000;
+
+  if (snapshot.ranges.length === 0) {
+    return `<system-reminder>\nThe user currently has \`${rel}\` open in ${snapshot.source}. This may or may not be relevant.\n</system-reminder>`;
+  }
+
+  const sections: string[] = [];
+  let remaining = maxChars;
+  let truncated = false;
+
+  for (const [index, range] of snapshot.ranges.entries()) {
+    const { startLine, endLine } = rangeToLineSpan(range);
+    const label = snapshot.ranges.length === 1 ? "The user selected" : `Selection ${index + 1}`;
+    let text = range.text;
+    if (text.length > remaining) {
+      text = text.slice(0, Math.max(0, remaining));
+      truncated = true;
+    }
+    remaining -= text.length;
+    sections.push(
+      `${label} lines ${startLine}-${endLine} from \`${rel}\` in ${snapshot.source}:\n\n\`\`\`\n${text}\n\`\`\``,
+    );
+    if (remaining <= 0) break;
+  }
+
+  const suffix = truncated ? "\n\n[Selection text truncated to keep the prompt size bounded.]" : "";
+  return `<system-reminder>\n${sections.join("\n\n")}\n\nThis may or may not be relevant.${suffix}\n</system-reminder>`;
+}

package/src/shared/paths.ts

@@ -0,0 +1,47 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { LOCK_DIR_ENV } from "./protocol";
+
+export function resolveLockDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env[LOCK_DIR_ENV] && env[LOCK_DIR_ENV].trim()
+    ? resolve(env[LOCK_DIR_ENV])
+    : resolve(homedir(), ".pi", "pi-x-ide");
+}
+
+export function normalizePath(input: string): string {
+  return resolve(input);
+}
+
+export function isPathInsideOrEqual(parent: string, child: string): boolean {
+  const normalizedParent = normalizePath(parent);
+  const normalizedChild = normalizePath(child);
+  if (normalizedParent === normalizedChild) return true;
+  const rel = relative(normalizedParent, normalizedChild);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+export function relationshipMatchLength(workspaceFolder: string, cwd: string): number {
+  const workspace = normalizePath(workspaceFolder);
+  const active = normalizePath(cwd);
+
+  // Best case: Pi is started inside the IDE workspace.
+  if (isPathInsideOrEqual(workspace, active)) {
+    return workspace.length + 10_000;
+  }
+
+  // Accept the inverse relationship for monorepos where Pi starts above a nested workspace,
+  // but rank it lower than a workspace containing cwd.
+  if (isPathInsideOrEqual(active, workspace)) {
+    return active.length;
+  }
+
+  return 0;
+}
+
+export function toRelativeDisplayPath(filePath: string, workspaceFolder?: string, cwd?: string): string {
+  const base = workspaceFolder ?? cwd;
+  if (!base) return filePath;
+  const rel = relative(base, filePath);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) return filePath;
+  return rel.split(sep).join("/");
+}

package/src/shared/protocol.ts

@@ -0,0 +1,107 @@
+export const PROTOCOL_VERSION = 1;
+export const LOCK_DIR_ENV = "PI_X_IDE_LOCK_DIR";
+export const AUTH_HEADER = "x-pi-x-ide-authorization";
+export const LOCK_FILE_EXTENSION = ".lock";
+
+export type IdeSource = "vscode" | "zed" | "unknown";
+export type Transport = "ws";
+
+export interface IdeLockFile {
+  version: 1;
+  ide: IdeSource;
+  name: string;
+  transport: Transport;
+  host: string;
+  port: number;
+  authToken: string;
+  workspaceFolders: string[];
+  pid?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface LockFileCandidate {
+  path: string;
+  lock: IdeLockFile;
+  mtimeMs: number;
+  matchLength: number;
+  workspaceFolder: string;
+}
+
+export interface JsonRpcRequest<TParams = unknown> {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: TParams;
+}
+
+export interface JsonRpcResponse<TResult = unknown> {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: TResult;
+  error?: { code: number; message: string };
+}
+
+export interface JsonRpcNotification<TParams = unknown> {
+  jsonrpc: "2.0";
+  method: string;
+  params?: TParams;
+}
+
+export interface InitializeParams {
+  protocolVersion: number;
+  client: {
+    name: "pi-x-ide";
+    version: string;
+  };
+  cwd: string;
+}
+
+export interface InitializeResult {
+  protocolVersion: number;
+  server: {
+    name: string;
+    version?: string;
+    ide: IdeSource;
+  };
+}
+
+export interface Position {
+  line: number;
+  character: number;
+}
+
+export interface SelectionRange {
+  text: string;
+  selection: {
+    start: Position;
+    end: Position;
+  };
+}
+
+export interface EditorSelectionSnapshot {
+  source: IdeSource;
+  filePath: string;
+  workspaceFolder?: string;
+  ranges: SelectionRange[];
+  receivedAt?: number;
+}
+
+export interface SelectionChangedParams extends EditorSelectionSnapshot {}
+
+export interface SelectionClearedParams {
+  source: IdeSource;
+  reason: "no-active-editor";
+  receivedAt?: number;
+}
+
+export interface AtMentionedParams extends EditorSelectionSnapshot {
+  rangeText: string;
+}
+
+export type IdeNotification =
+  | JsonRpcNotification<SelectionChangedParams>
+  | JsonRpcNotification<SelectionClearedParams>
+  | JsonRpcNotification<AtMentionedParams>;
+
+export type AttachState = "pending" | "sent" | "idle";

package/src/shared/schema.ts

@@ -0,0 +1,113 @@
+import type {
+  AtMentionedParams,
+  EditorSelectionSnapshot,
+  IdeLockFile,
+  IdeSource,
+  JsonRpcRequest,
+  SelectionChangedParams,
+  SelectionClearedParams,
+  SelectionRange,
+} from "./protocol";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isIdeSource(value: unknown): value is IdeSource {
+  return value === "vscode" || value === "zed" || value === "unknown";
+}
+
+export function isIdeLockFile(value: unknown): value is IdeLockFile {
+  if (!isRecord(value)) return false;
+  return (
+    value.version === 1 &&
+    isIdeSource(value.ide) &&
+    isString(value.name) &&
+    value.transport === "ws" &&
+    isString(value.host) &&
+    isFiniteNumber(value.port) &&
+    value.port > 0 &&
+    value.port <= 65_535 &&
+    isString(value.authToken) &&
+    Array.isArray(value.workspaceFolders) &&
+    value.workspaceFolders.every(isString) &&
+    (value.pid === undefined || isFiniteNumber(value.pid)) &&
+    isString(value.createdAt) &&
+    isString(value.updatedAt)
+  );
+}
+
+function isPosition(value: unknown): value is { line: number; character: number } {
+  return (
+    isRecord(value) &&
+    isFiniteNumber(value.line) &&
+    isFiniteNumber(value.character) &&
+    value.line >= 0 &&
+    value.character >= 0
+  );
+}
+
+function isSelectionRange(value: unknown): value is SelectionRange {
+  if (!isRecord(value) || !isString(value.text) || !isRecord(value.selection)) return false;
+  return isPosition(value.selection.start) && isPosition(value.selection.end);
+}
+
+export function isEditorSelectionSnapshot(value: unknown): value is EditorSelectionSnapshot {
+  if (!isRecord(value)) return false;
+  return (
+    isIdeSource(value.source) &&
+    isString(value.filePath) &&
+    (value.workspaceFolder === undefined || isString(value.workspaceFolder)) &&
+    Array.isArray(value.ranges) &&
+    value.ranges.every(isSelectionRange) &&
+    (value.receivedAt === undefined || isFiniteNumber(value.receivedAt))
+  );
+}
+
+export function isSelectionChangedParams(value: unknown): value is SelectionChangedParams {
+  return isEditorSelectionSnapshot(value);
+}
+
+export function isSelectionClearedParams(value: unknown): value is SelectionClearedParams {
+  return (
+    isRecord(value) &&
+    isIdeSource(value.source) &&
+    value.reason === "no-active-editor" &&
+    (value.receivedAt === undefined || isFiniteNumber(value.receivedAt))
+  );
+}
+
+export function isAtMentionedParams(value: unknown): value is AtMentionedParams {
+  return isEditorSelectionSnapshot(value) && isString((value as unknown as Record<string, unknown>).rangeText);
+}
+
+export function parseJsonObject(input: string): Record<string, unknown> | undefined {
+  try {
+    const parsed = JSON.parse(input) as unknown;
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function parseLockFileContent(content: string): IdeLockFile | undefined {
+  const parsed = parseJsonObject(content);
+  return isIdeLockFile(parsed) ? parsed : undefined;
+}
+
+export function isJsonRpcRequest(value: unknown): value is JsonRpcRequest {
+  return (
+    isRecord(value) &&
+    value.jsonrpc === "2.0" &&
+    (isString(value.id) || isFiniteNumber(value.id)) &&
+    isString(value.method)
+  );
+}

package/src/shared/ws.ts

@@ -0,0 +1,8 @@
+import { Buffer } from "node:buffer";
+import type { RawData } from "ws";
+
+export function decodeRawData(raw: RawData): string {
+  if (Array.isArray(raw)) return Buffer.concat(raw).toString("utf8");
+  if (Buffer.isBuffer(raw)) return raw.toString("utf8");
+  return Buffer.from(raw).toString("utf8");
+}