@iislee/opencodex 2.11.0

package/src/pi/home.ts

@@ -0,0 +1,42 @@
+/**
+ * Pi agent home paths.
+ *
+ * Default root is `~/.pi/agent` (Pi's documented global agent dir). `PI_HOME` may
+ * override the parent `~/.pi` (so `PI_HOME=/tmp/pi` → `/tmp/pi/agent/...`), matching
+ * the "home of the product" pattern used by Grok's `GROK_HOME`.
+ *
+ * We never invent a second state root under `~/.opencodex` for Pi files: Pi owns
+ * these paths; opencodex only reads/writes well-known keys inside them.
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function resolvePiRoot(piHome?: string): string {
+  return piHome ?? process.env.PI_HOME ?? join(homedir(), ".pi");
+}
+
+export function resolvePiAgentDir(piHome?: string): string {
+  return join(resolvePiRoot(piHome), "agent");
+}
+
+export function piModelsPath(piHome?: string): string {
+  return join(resolvePiAgentDir(piHome), "models.json");
+}
+
+export function piSettingsPath(piHome?: string): string {
+  return join(resolvePiAgentDir(piHome), "settings.json");
+}
+
+export function piExtensionsDir(piHome?: string): string {
+  return join(resolvePiAgentDir(piHome), "extensions");
+}
+
+export function piAgentDirExists(piHome?: string): boolean {
+  const dir = resolvePiAgentDir(piHome);
+  try {
+    return existsSync(dir) && statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/pi/index.ts

@@ -0,0 +1,40 @@
+export {
+  resolvePiRoot,
+  resolvePiAgentDir,
+  piModelsPath,
+  piSettingsPath,
+  piExtensionsDir,
+  piAgentDirExists,
+} from "./home";
+export {
+  buildPiOpencodexProvider,
+  injectPiModels,
+  removePiModels,
+  readPiModelsStatus,
+  type PiInjectModel,
+  type PiInjectResult,
+  type PiModelsStatus,
+} from "./models";
+export {
+  readPiSettings,
+  writePiSettings,
+  validatePiSettingsPatch,
+  projectPiSettings,
+  type PiCuratedSettings,
+  type PiSettingsStatus,
+  type PiSettingsWriteResult,
+} from "./settings";
+export {
+  validatePiPackageSource,
+  resolvePiBinary,
+  readPiPackages,
+  listPiPackagesDetailed,
+  installPiPackage,
+  removePiPackage,
+  type PiPackageEntry,
+  type PiPackagesStatus,
+  type PiPackageCommandResult,
+} from "./packages";
+export { readPiExtensions, type PiExtensionEntry, type PiExtensionsStatus } from "./extensions";
+export { readPiStatus, piInstallHint, type PiStatus } from "./status";
+export { syncPiConfig, type PiSyncDeps } from "./sync";

package/src/pi/models.ts

@@ -0,0 +1,278 @@
+/**
+ * Inject / remove the managed `providers.opencodex` block in Pi's models.json.
+ *
+ * Ownership model (user choice: managed block only):
+ * - We own ONLY the provider key `opencodex`.
+ * - Other providers, top-level keys, and formatting of the rest of the file are
+ *   preserved as far as JSON round-trip allows (re-pretty-printed with 2-space
+ *   indent; unknown sibling keys stay).
+ * - Apply upserts `providers.opencodex`; remove deletes that key alone.
+ *
+ * Non-loopback binds refuse to write: the emitted apiKey is an env reference, and
+ * a remote baseUrl would silently send traffic somewhere the local dashboard
+ * cannot prove is this proxy (same policy as Grok inject).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWriteFile } from "../config";
+import {
+  OPENCODE_PROVIDER_ID,
+  PI_API_KEY_ENV_REF,
+  buildClientConfig,
+  type ExportModel,
+  type PiGeneratedConfig,
+  type PiProviderBlock,
+} from "../clients/config-export";
+import { isLoopbackHostname, providerBaseHost } from "../codex/inject";
+import { piAgentDirExists, piModelsPath, resolvePiAgentDir } from "./home";
+
+export interface PiInjectModel {
+  namespaced: string;
+  provider: string;
+  id: string;
+  native?: boolean;
+  displayName?: string;
+  contextWindow?: number;
+  inputModalities?: string[];
+}
+
+export interface PiInjectResult {
+  ok: boolean;
+  changed: boolean;
+  message: string;
+  modelsPath: string;
+  modelCount: number;
+  skippedReason?: "no-pi-home" | "non-loopback" | "invalid-file";
+}
+
+export interface PiModelsStatus {
+  modelsPath: string;
+  present: boolean;
+  baseUrl: string | null;
+  modelCount: number;
+  models: Array<{ id: string; name?: string; contextWindow?: number }>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readModelsDocument(path: string): { ok: true; doc: Record<string, unknown> } | { ok: false; error: string } {
+  if (!existsSync(path)) return { ok: true, doc: {} };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  if (raw.trim() === "") return { ok: true, doc: {} };
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isRecord(parsed)) return { ok: false, error: "models.json root must be an object" };
+    return { ok: true, doc: parsed };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function providersOf(doc: Record<string, unknown>): Record<string, unknown> {
+  const providers = doc.providers;
+  if (isRecord(providers)) return { ...providers };
+  return {};
+}
+
+function asPiProviderBlock(value: unknown): PiProviderBlock | null {
+  if (!isRecord(value)) return null;
+  const baseUrl = typeof value.baseUrl === "string" ? value.baseUrl : null;
+  const api = typeof value.api === "string" ? value.api : null;
+  const apiKey = typeof value.apiKey === "string" ? value.apiKey : null;
+  const models = Array.isArray(value.models) ? value.models : null;
+  if (!baseUrl || !api || !apiKey || !models) return null;
+  return value as unknown as PiProviderBlock;
+}
+
+/** Build the opencodex provider block using the shared Pi export serializer. */
+export function buildPiOpencodexProvider(
+  baseUrl: string,
+  models: readonly PiInjectModel[],
+): PiProviderBlock {
+  const exportModels: ExportModel[] = models.map(model => ({
+    namespaced: model.namespaced,
+    provider: model.provider,
+    id: model.id,
+    ...(model.native !== undefined ? { native: model.native } : {}),
+    ...(model.displayName !== undefined ? { displayName: model.displayName } : {}),
+    ...(model.contextWindow !== undefined ? { contextWindow: model.contextWindow } : {}),
+    ...(model.inputModalities !== undefined ? { inputModalities: model.inputModalities } : {}),
+  }));
+  const generated = buildClientConfig("pi", { baseUrl, models: exportModels }) as PiGeneratedConfig;
+  const block = generated.providers[OPENCODE_PROVIDER_ID];
+  if (!block) {
+    // Defensive: the exporter always emits OPENCODE_PROVIDER_ID.
+    return {
+      baseUrl,
+      api: "openai-completions",
+      apiKey: PI_API_KEY_ENV_REF,
+      models: [],
+    };
+  }
+  return block;
+}
+
+export function readPiModelsStatus(opts: { piHome?: string } = {}): PiModelsStatus {
+  const modelsPath = piModelsPath(opts.piHome);
+  const empty: PiModelsStatus = { modelsPath, present: false, baseUrl: null, modelCount: 0, models: [] };
+  const loaded = readModelsDocument(modelsPath);
+  if (!loaded.ok) return empty;
+  const block = asPiProviderBlock(providersOf(loaded.doc)[OPENCODE_PROVIDER_ID]);
+  if (!block) return empty;
+  const models = block.models.map(entry => ({
+    id: entry.id,
+    ...(entry.name ? { name: entry.name } : {}),
+    ...(typeof entry.contextWindow === "number" ? { contextWindow: entry.contextWindow } : {}),
+  }));
+  return {
+    modelsPath,
+    present: true,
+    baseUrl: block.baseUrl,
+    modelCount: models.length,
+    models,
+  };
+}
+
+/**
+ * Upsert providers.opencodex. Refuses non-loopback hostnames and missing agent dir
+ * (we create models.json, but not a whole ~/.pi tree the user never installed).
+ */
+export function injectPiModels(
+  port: number,
+  models: readonly PiInjectModel[],
+  opts: { hostname?: string; piHome?: string } = {},
+): PiInjectResult {
+  const modelsPath = piModelsPath(opts.piHome);
+  const host = providerBaseHost(opts.hostname);
+  if (!isLoopbackHostname(host)) {
+    return {
+      ok: true,
+      changed: false,
+      message: `Pi models inject skipped: hostname ${host} is not loopback.`,
+      modelsPath,
+      modelCount: 0,
+      skippedReason: "non-loopback",
+    };
+  }
+  if (!piAgentDirExists(opts.piHome)) {
+    return {
+      ok: true,
+      changed: false,
+      message: `Pi models inject skipped: ${resolvePiAgentDir(opts.piHome)} does not exist (install Pi first).`,
+      modelsPath,
+      modelCount: 0,
+      skippedReason: "no-pi-home",
+    };
+  }
+
+  const baseUrl = `http://${host}:${port}/v1`;
+  const block = buildPiOpencodexProvider(baseUrl, models);
+  const loaded = readModelsDocument(modelsPath);
+  if (!loaded.ok) {
+    return {
+      ok: false,
+      changed: false,
+      message: `Pi models inject failed: ${loaded.error}`,
+      modelsPath,
+      modelCount: 0,
+      skippedReason: "invalid-file",
+    };
+  }
+
+  const previous = JSON.stringify(loaded.doc);
+  const providers = providersOf(loaded.doc);
+  providers[OPENCODE_PROVIDER_ID] = block;
+  const nextDoc: Record<string, unknown> = { ...loaded.doc, providers };
+  const next = `${JSON.stringify(nextDoc, null, 2)}\n`;
+  if (next === `${previous.trim() === "" ? "{}" : JSON.stringify(loaded.doc, null, 2)}\n`) {
+    // Compare structured equality instead of string form of the read file (may lack trailing newline).
+    const same = JSON.stringify(loaded.doc) === JSON.stringify(nextDoc);
+    if (same) {
+      return {
+        ok: true,
+        changed: false,
+        message: `Pi models unchanged (${block.models.length} model${block.models.length === 1 ? "" : "s"}).`,
+        modelsPath,
+        modelCount: block.models.length,
+      };
+    }
+  }
+
+  mkdirSync(dirname(modelsPath), { recursive: true });
+  if (existsSync(modelsPath)) {
+    try {
+      copyFileSync(modelsPath, `${modelsPath}.opencodex.bak`);
+    } catch {
+      // Backup is best-effort; write still proceeds.
+    }
+  }
+  atomicWriteFile(modelsPath, next);
+  return {
+    ok: true,
+    changed: true,
+    message: `Pi models updated: ${block.models.length} model${block.models.length === 1 ? "" : "s"} → ${modelsPath}`,
+    modelsPath,
+    modelCount: block.models.length,
+  };
+}
+
+/** Delete only providers.opencodex; leave the rest of models.json alone. */
+export function removePiModels(opts: { piHome?: string } = {}): PiInjectResult {
+  const modelsPath = piModelsPath(opts.piHome);
+  if (!existsSync(modelsPath)) {
+    return {
+      ok: true,
+      changed: false,
+      message: "Pi models: nothing to remove (file absent).",
+      modelsPath,
+      modelCount: 0,
+    };
+  }
+  const loaded = readModelsDocument(modelsPath);
+  if (!loaded.ok) {
+    return {
+      ok: false,
+      changed: false,
+      message: `Pi models remove failed: ${loaded.error}`,
+      modelsPath,
+      modelCount: 0,
+      skippedReason: "invalid-file",
+    };
+  }
+  const providers = providersOf(loaded.doc);
+  if (!(OPENCODE_PROVIDER_ID in providers)) {
+    return {
+      ok: true,
+      changed: false,
+      message: "Pi models: opencodex provider not present.",
+      modelsPath,
+      modelCount: 0,
+    };
+  }
+  delete providers[OPENCODE_PROVIDER_ID];
+  // Pi requires a top-level `providers` object even when empty — bare `{}` fails schema
+  // validation ("must have required properties providers"). Always keep the key.
+  const nextDoc: Record<string, unknown> = { ...loaded.doc, providers };
+  if (existsSync(modelsPath)) {
+    try {
+      copyFileSync(modelsPath, `${modelsPath}.opencodex.bak`);
+    } catch {
+      // best-effort
+    }
+  }
+  atomicWriteFile(modelsPath, `${JSON.stringify(nextDoc, null, 2)}\n`);
+  return {
+    ok: true,
+    changed: true,
+    message: `Pi models: removed providers.opencodex from ${modelsPath}`,
+    modelsPath,
+    modelCount: 0,
+  };
+}

package/src/pi/packages.ts

@@ -0,0 +1,219 @@
+/**
+ * Pi package management via the real `pi` CLI.
+ *
+ * We deliberately do not re-implement npm/git install: packages run with full
+ * system access (Pi docs). Spawning `pi install|remove|list` keeps the same
+ * trust model the user already accepts when using Pi interactively, and avoids
+ * inventing a second installer that could diverge from Pi's pin/reconcile rules.
+ *
+ * Source strings are validated before spawn (no shell metacharacters; argv only).
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter } from "node:path";
+import { readPiSettings } from "./settings";
+
+export interface PiPackageEntry {
+  /** Canonical source string as stored in settings (string form or object.source). */
+  source: string;
+  /** When settings used object form, optional resource filters. */
+  filters?: {
+    skills?: string[];
+    extensions?: string[];
+    prompts?: string[];
+    themes?: string[];
+  };
+}
+
+export interface PiPackagesStatus {
+  packages: PiPackageEntry[];
+  /** Output of `pi list` when available (may be empty if pi is missing). */
+  listOutput: string | null;
+  piBinary: string | null;
+}
+
+export interface PiPackageCommandResult {
+  ok: boolean;
+  message: string;
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+}
+
+const SOURCE_MAX = 512;
+const RUN_TIMEOUT_MS = 120_000;
+
+/**
+ * Accept Pi's documented source forms only. Reject anything that looks like shell
+ * composition — we always pass argv, but defense in depth still matters.
+ */
+export function validatePiPackageSource(source: string): string | null {
+  const trimmed = source.trim();
+  if (!trimmed || trimmed.length > SOURCE_MAX) return "package source is empty or too long";
+  if (/[\0\n\r;|&`$]/.test(trimmed)) return "package source contains forbidden characters";
+  if (
+    trimmed.startsWith("npm:")
+    || trimmed.startsWith("git:")
+    || trimmed.startsWith("https://")
+    || trimmed.startsWith("http://")
+    || trimmed.startsWith("ssh://")
+    || trimmed.startsWith("git://")
+    || trimmed.startsWith("./")
+    || trimmed.startsWith("../")
+    || trimmed.startsWith("/")
+    || /^[A-Za-z]:[\\/]/.test(trimmed) // Windows path
+  ) {
+    return null;
+  }
+  // Bare npm package name / @scope/name (Pi accepts these inside packages array).
+  if (/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*(@[^\s]+)?$/i.test(trimmed)) {
+    return null;
+  }
+  return "unsupported package source form";
+}
+
+function packageEntriesFromSettings(packages: unknown[] | undefined): PiPackageEntry[] {
+  if (!packages) return [];
+  const out: PiPackageEntry[] = [];
+  for (const entry of packages) {
+    if (typeof entry === "string" && entry.trim()) {
+      out.push({ source: entry.trim() });
+      continue;
+    }
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      const rec = entry as Record<string, unknown>;
+      const source = typeof rec.source === "string" ? rec.source.trim() : "";
+      if (!source) continue;
+      const filters: PiPackageEntry["filters"] = {};
+      for (const key of ["skills", "extensions", "prompts", "themes"] as const) {
+        const value = rec[key];
+        if (Array.isArray(value) && value.every(v => typeof v === "string")) {
+          filters[key] = value as string[];
+        }
+      }
+      out.push({
+        source,
+        ...(Object.keys(filters).length > 0 ? { filters } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/** Resolve `pi` on PATH (and common nvm locations are already on PATH when the user runs ocx). */
+export function resolvePiBinary(env: NodeJS.ProcessEnv = process.env): string | null {
+  const pathEnv = env.PATH ?? env.Path ?? "";
+  const names = process.platform === "win32" ? ["pi.cmd", "pi.exe", "pi"] : ["pi"];
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = `${dir.replace(/[/\\]$/, "")}${process.platform === "win32" ? "\\" : "/"}${name}`;
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function readPiPackages(opts: { piHome?: string } = {}): PiPackagesStatus {
+  const settings = readPiSettings(opts);
+  return {
+    packages: packageEntriesFromSettings(settings.settings.packages),
+    listOutput: null,
+    piBinary: resolvePiBinary(),
+  };
+}
+
+export async function listPiPackagesDetailed(opts: { piHome?: string } = {}): Promise<PiPackagesStatus> {
+  const base = readPiPackages(opts);
+  if (!base.piBinary) return base;
+  const result = await runPiCli(base.piBinary, ["list"]);
+  return {
+    ...base,
+    listOutput: result.ok || result.stdout ? result.stdout.trim() || result.stderr.trim() : null,
+  };
+}
+
+function runPiCli(
+  binary: string,
+  args: string[],
+  opts: { timeoutMs?: number } = {},
+): Promise<PiPackageCommandResult> {
+  const timeoutMs = opts.timeoutMs ?? RUN_TIMEOUT_MS;
+  return new Promise(resolve => {
+    const child = spawn(binary, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      resolve({
+        ok: false,
+        message: `pi ${args[0]} timed out after ${timeoutMs}ms`,
+        stdout,
+        stderr,
+        exitCode: null,
+      });
+    }, timeoutMs);
+    child.stdout?.on("data", chunk => { stdout += String(chunk); });
+    child.stderr?.on("data", chunk => { stderr += String(chunk); });
+    child.on("error", error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        message: error.message,
+        stdout,
+        stderr,
+        exitCode: null,
+      });
+    });
+    child.on("close", code => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const exitCode = code ?? null;
+      const ok = exitCode === 0;
+      resolve({
+        ok,
+        message: ok
+          ? (stdout.trim() || `pi ${args.join(" ")} ok`)
+          : (stderr.trim() || stdout.trim() || `pi exited ${exitCode}`),
+        stdout,
+        stderr,
+        exitCode,
+      });
+    });
+  });
+}
+
+export async function installPiPackage(source: string): Promise<PiPackageCommandResult> {
+  const error = validatePiPackageSource(source);
+  if (error) {
+    return { ok: false, message: error, stdout: "", stderr: "", exitCode: null };
+  }
+  const binary = resolvePiBinary();
+  if (!binary) {
+    return { ok: false, message: "pi binary not found on PATH", stdout: "", stderr: "", exitCode: null };
+  }
+  // Global install only (matches dashboard scope). Project-local needs a cwd we do not own.
+  return runPiCli(binary, ["install", source.trim()]);
+}
+
+export async function removePiPackage(source: string): Promise<PiPackageCommandResult> {
+  const error = validatePiPackageSource(source);
+  if (error) {
+    return { ok: false, message: error, stdout: "", stderr: "", exitCode: null };
+  }
+  const binary = resolvePiBinary();
+  if (!binary) {
+    return { ok: false, message: "pi binary not found on PATH", stdout: "", stderr: "", exitCode: null };
+  }
+  return runPiCli(binary, ["remove", source.trim()]);
+}