@iislee/opencodex 2.11.0

package/src/pi/settings.ts

@@ -0,0 +1,365 @@
+/**
+ * Curated read/patch of Pi's global settings.json.
+ *
+ * Only a allowlisted subset is writable through opencodex. `packages` and path
+ * resource arrays are managed by the packages/extensions modules (which shell out
+ * to `pi` or list directories), never by free-form JSON merge here — that keeps
+ * shell-source injection and arbitrary extension paths out of a single PUT body.
+ *
+ * Unknown keys already on disk are always preserved.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { atomicWriteFile } from "../config";
+import { piAgentDirExists, piSettingsPath, resolvePiAgentDir } from "./home";
+
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const TRUST_VALUES = new Set(["ask", "always", "never"]);
+
+export interface PiCuratedSettings {
+  defaultProvider?: string;
+  defaultModel?: string;
+  defaultThinkingLevel?: string;
+  hideThinkingBlock?: boolean;
+  theme?: string;
+  quietStartup?: boolean;
+  defaultProjectTrust?: string;
+  enabledModels?: string[];
+  compaction?: {
+    enabled?: boolean;
+    reserveTokens?: number;
+    keepRecentTokens?: number;
+  };
+  retry?: {
+    enabled?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+  };
+  /** Present in the file; packages are managed separately but shown for context. */
+  packages?: unknown[];
+  extensions?: string[];
+  skills?: string[];
+  prompts?: string[];
+  themes?: string[];
+}
+
+export interface PiSettingsStatus {
+  settingsPath: string;
+  present: boolean;
+  settings: PiCuratedSettings;
+  /** Raw top-level keys we did not map — count only, never values (may hold secrets). */
+  otherKeyCount: number;
+}
+
+export interface PiSettingsWriteResult {
+  ok: boolean;
+  changed: boolean;
+  message: string;
+  settingsPath: string;
+  settings?: PiCuratedSettings;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readDoc(path: string): { ok: true; doc: Record<string, unknown> } | { ok: false; error: string } {
+  if (!existsSync(path)) return { ok: true, doc: {} };
+  try {
+    const raw = readFileSync(path, "utf8");
+    if (raw.trim() === "") return { ok: true, doc: {} };
+    const parsed = JSON.parse(raw) as unknown;
+    if (!isRecord(parsed)) return { ok: false, error: "settings.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 positiveInt(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && Number.isInteger(value)
+    ? value
+    : undefined;
+}
+
+function nonNegInt(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && Number.isInteger(value)
+    ? value
+    : undefined;
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  if (!value.every(entry => typeof entry === "string")) return undefined;
+  return value as string[];
+}
+
+/** Project a raw settings object onto the curated surface. */
+export function projectPiSettings(doc: Record<string, unknown>): { settings: PiCuratedSettings; otherKeyCount: number } {
+  const known = new Set([
+    "defaultProvider",
+    "defaultModel",
+    "defaultThinkingLevel",
+    "hideThinkingBlock",
+    "theme",
+    "quietStartup",
+    "defaultProjectTrust",
+    "enabledModels",
+    "compaction",
+    "retry",
+    "packages",
+    "extensions",
+    "skills",
+    "prompts",
+    "themes",
+  ]);
+  const settings: PiCuratedSettings = {};
+  if (typeof doc.defaultProvider === "string") settings.defaultProvider = doc.defaultProvider;
+  if (typeof doc.defaultModel === "string") settings.defaultModel = doc.defaultModel;
+  if (typeof doc.defaultThinkingLevel === "string") settings.defaultThinkingLevel = doc.defaultThinkingLevel;
+  if (typeof doc.hideThinkingBlock === "boolean") settings.hideThinkingBlock = doc.hideThinkingBlock;
+  if (typeof doc.theme === "string") settings.theme = doc.theme;
+  if (typeof doc.quietStartup === "boolean") settings.quietStartup = doc.quietStartup;
+  if (typeof doc.defaultProjectTrust === "string") settings.defaultProjectTrust = doc.defaultProjectTrust;
+  const enabledModels = asStringArray(doc.enabledModels);
+  if (enabledModels) settings.enabledModels = enabledModels;
+  if (isRecord(doc.compaction)) {
+    const c: NonNullable<PiCuratedSettings["compaction"]> = {};
+    if (typeof doc.compaction.enabled === "boolean") c.enabled = doc.compaction.enabled;
+    const reserve = positiveInt(doc.compaction.reserveTokens);
+    if (reserve !== undefined) c.reserveTokens = reserve;
+    const keep = positiveInt(doc.compaction.keepRecentTokens);
+    if (keep !== undefined) c.keepRecentTokens = keep;
+    if (Object.keys(c).length > 0) settings.compaction = c;
+  }
+  if (isRecord(doc.retry)) {
+    const r: NonNullable<PiCuratedSettings["retry"]> = {};
+    if (typeof doc.retry.enabled === "boolean") r.enabled = doc.retry.enabled;
+    const maxRetries = nonNegInt(doc.retry.maxRetries);
+    if (maxRetries !== undefined) r.maxRetries = maxRetries;
+    const baseDelayMs = nonNegInt(doc.retry.baseDelayMs);
+    if (baseDelayMs !== undefined) r.baseDelayMs = baseDelayMs;
+    if (Object.keys(r).length > 0) settings.retry = r;
+  }
+  if (Array.isArray(doc.packages)) settings.packages = doc.packages;
+  const extensions = asStringArray(doc.extensions);
+  if (extensions) settings.extensions = extensions;
+  const skills = asStringArray(doc.skills);
+  if (skills) settings.skills = skills;
+  const prompts = asStringArray(doc.prompts);
+  if (prompts) settings.prompts = prompts;
+  const themes = asStringArray(doc.themes);
+  if (themes) settings.themes = themes;
+
+  let otherKeyCount = 0;
+  for (const key of Object.keys(doc)) {
+    if (!known.has(key)) otherKeyCount += 1;
+  }
+  return { settings, otherKeyCount };
+}
+
+export function readPiSettings(opts: { piHome?: string } = {}): PiSettingsStatus {
+  const settingsPath = piSettingsPath(opts.piHome);
+  const loaded = readDoc(settingsPath);
+  if (!loaded.ok) {
+    return { settingsPath, present: false, settings: {}, otherKeyCount: 0 };
+  }
+  const present = existsSync(settingsPath);
+  const { settings, otherKeyCount } = projectPiSettings(loaded.doc);
+  return { settingsPath, present, settings, otherKeyCount };
+}
+
+/**
+ * Validate and apply a partial patch. Returns a user-facing error string on bad input.
+ * `null` fields clear the key when the property is present with value null.
+ */
+export function validatePiSettingsPatch(patch: unknown): { ok: true; patch: Record<string, unknown> } | { ok: false; error: string } {
+  if (!isRecord(patch)) return { ok: false, error: "body must be an object" };
+  const out: Record<string, unknown> = {};
+
+  const stringOrNull = (key: string, max = 200): string | null | undefined | false => {
+    if (!(key in patch)) return undefined;
+    const value = patch[key];
+    if (value === null) return null;
+    if (typeof value !== "string" || value.length === 0 || value.length > max) return false;
+    return value;
+  };
+
+  for (const key of ["defaultProvider", "defaultModel", "theme"] as const) {
+    const value = stringOrNull(key);
+    if (value === false) return { ok: false, error: `${key} must be a non-empty string or null` };
+    if (value !== undefined) out[key] = value;
+  }
+
+  if ("defaultThinkingLevel" in patch) {
+    const value = patch.defaultThinkingLevel;
+    if (value === null) out.defaultThinkingLevel = null;
+    else if (typeof value !== "string" || !THINKING_LEVELS.has(value)) {
+      return { ok: false, error: `defaultThinkingLevel must be one of ${[...THINKING_LEVELS].join(", ")} or null` };
+    } else out.defaultThinkingLevel = value;
+  }
+
+  if ("defaultProjectTrust" in patch) {
+    const value = patch.defaultProjectTrust;
+    if (value === null) out.defaultProjectTrust = null;
+    else if (typeof value !== "string" || !TRUST_VALUES.has(value)) {
+      return { ok: false, error: `defaultProjectTrust must be one of ${[...TRUST_VALUES].join(", ")} or null` };
+    } else out.defaultProjectTrust = value;
+  }
+
+  for (const key of ["hideThinkingBlock", "quietStartup"] as const) {
+    if (!(key in patch)) continue;
+    const value = patch[key];
+    if (value === null) out[key] = null;
+    else if (typeof value !== "boolean") return { ok: false, error: `${key} must be a boolean or null` };
+    else out[key] = value;
+  }
+
+  if ("enabledModels" in patch) {
+    const value = patch.enabledModels;
+    if (value === null) out.enabledModels = null;
+    else {
+      const arr = asStringArray(value);
+      if (!arr || arr.length > 500) return { ok: false, error: "enabledModels must be a string array (max 500) or null" };
+      out.enabledModels = arr;
+    }
+  }
+
+  if ("compaction" in patch) {
+    const value = patch.compaction;
+    if (value === null) out.compaction = null;
+    else if (!isRecord(value)) return { ok: false, error: "compaction must be an object or null" };
+    else {
+      const c: Record<string, unknown> = {};
+      if ("enabled" in value) {
+        if (typeof value.enabled !== "boolean") return { ok: false, error: "compaction.enabled must be boolean" };
+        c.enabled = value.enabled;
+      }
+      if ("reserveTokens" in value) {
+        const n = positiveInt(value.reserveTokens);
+        if (n === undefined) return { ok: false, error: "compaction.reserveTokens must be a positive integer" };
+        c.reserveTokens = n;
+      }
+      if ("keepRecentTokens" in value) {
+        const n = positiveInt(value.keepRecentTokens);
+        if (n === undefined) return { ok: false, error: "compaction.keepRecentTokens must be a positive integer" };
+        c.keepRecentTokens = n;
+      }
+      out.compaction = c;
+    }
+  }
+
+  if ("retry" in patch) {
+    const value = patch.retry;
+    if (value === null) out.retry = null;
+    else if (!isRecord(value)) return { ok: false, error: "retry must be an object or null" };
+    else {
+      const r: Record<string, unknown> = {};
+      if ("enabled" in value) {
+        if (typeof value.enabled !== "boolean") return { ok: false, error: "retry.enabled must be boolean" };
+        r.enabled = value.enabled;
+      }
+      if ("maxRetries" in value) {
+        const n = nonNegInt(value.maxRetries);
+        if (n === undefined || n > 20) return { ok: false, error: "retry.maxRetries must be an integer 0–20" };
+        r.maxRetries = n;
+      }
+      if ("baseDelayMs" in value) {
+        const n = nonNegInt(value.baseDelayMs);
+        if (n === undefined || n > 600_000) return { ok: false, error: "retry.baseDelayMs must be an integer 0–600000" };
+        r.baseDelayMs = n;
+      }
+      out.retry = r;
+    }
+  }
+
+  // Reject unknown top-level patch keys so clients cannot smuggle packages/extensions.
+  const allowed = new Set([
+    "defaultProvider",
+    "defaultModel",
+    "defaultThinkingLevel",
+    "hideThinkingBlock",
+    "theme",
+    "quietStartup",
+    "defaultProjectTrust",
+    "enabledModels",
+    "compaction",
+    "retry",
+  ]);
+  for (const key of Object.keys(patch)) {
+    if (!allowed.has(key)) return { ok: false, error: `unsupported settings key: ${key}` };
+  }
+
+  return { ok: true, patch: out };
+}
+
+function applyPatch(doc: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown> {
+  const next = { ...doc };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete next[key];
+      continue;
+    }
+    if ((key === "compaction" || key === "retry") && isRecord(value) && isRecord(next[key])) {
+      next[key] = { ...next[key], ...value };
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+}
+
+export function writePiSettings(
+  patchInput: unknown,
+  opts: { piHome?: string } = {},
+): PiSettingsWriteResult {
+  const settingsPath = piSettingsPath(opts.piHome);
+  if (!piAgentDirExists(opts.piHome)) {
+    return {
+      ok: false,
+      changed: false,
+      message: `Pi settings write skipped: ${resolvePiAgentDir(opts.piHome)} does not exist.`,
+      settingsPath,
+    };
+  }
+  const validated = validatePiSettingsPatch(patchInput);
+  if (!validated.ok) {
+    return { ok: false, changed: false, message: validated.error, settingsPath };
+  }
+  if (Object.keys(validated.patch).length === 0) {
+    return { ok: true, changed: false, message: "No settings changes.", settingsPath, settings: readPiSettings(opts).settings };
+  }
+
+  const loaded = readDoc(settingsPath);
+  if (!loaded.ok) {
+    return { ok: false, changed: false, message: loaded.error, settingsPath };
+  }
+  const nextDoc = applyPatch(loaded.doc, validated.patch);
+  if (JSON.stringify(loaded.doc) === JSON.stringify(nextDoc)) {
+    const projected = projectPiSettings(nextDoc);
+    return {
+      ok: true,
+      changed: false,
+      message: "Pi settings unchanged.",
+      settingsPath,
+      settings: projected.settings,
+    };
+  }
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  if (existsSync(settingsPath)) {
+    try {
+      copyFileSync(settingsPath, `${settingsPath}.opencodex.bak`);
+    } catch {
+      // best-effort
+    }
+  }
+  atomicWriteFile(settingsPath, `${JSON.stringify(nextDoc, null, 2)}\n`);
+  const projected = projectPiSettings(nextDoc);
+  return {
+    ok: true,
+    changed: true,
+    message: `Pi settings updated → ${settingsPath}`,
+    settingsPath,
+    settings: projected.settings,
+  };
+}

package/src/pi/status.ts

@@ -0,0 +1,68 @@
+/**
+ * Aggregate Pi integration status for CLI + management API + GUI.
+ * Never reads auth.json body (credentials).
+ */
+import { existsSync } from "node:fs";
+import {
+  piAgentDirExists,
+  piModelsPath,
+  piSettingsPath,
+  resolvePiAgentDir,
+  resolvePiRoot,
+} from "./home";
+import { readPiModelsStatus, type PiModelsStatus } from "./models";
+import { readPiSettings, type PiSettingsStatus } from "./settings";
+import {
+  listPiPackagesDetailed,
+  readPiPackages,
+  resolvePiBinary,
+  type PiPackagesStatus,
+} from "./packages";
+import { readPiExtensions, type PiExtensionsStatus } from "./extensions";
+
+export interface PiStatus {
+  piRoot: string;
+  agentDir: string;
+  agentDirPresent: boolean;
+  piBinary: string | null;
+  modelsPath: string;
+  settingsPath: string;
+  models: PiModelsStatus;
+  settings: PiSettingsStatus;
+  packages: PiPackagesStatus;
+  extensions: PiExtensionsStatus;
+}
+
+export async function readPiStatus(opts: { piHome?: string; includePackageList?: boolean } = {}): Promise<PiStatus> {
+  const packages: PiPackagesStatus = opts.includePackageList === false
+    ? readPiPackages(opts)
+    : await listPiPackagesDetailed(opts);
+
+  return {
+    piRoot: resolvePiRoot(opts.piHome),
+    agentDir: resolvePiAgentDir(opts.piHome),
+    agentDirPresent: piAgentDirExists(opts.piHome),
+    piBinary: resolvePiBinary(),
+    modelsPath: piModelsPath(opts.piHome),
+    settingsPath: piSettingsPath(opts.piHome),
+    models: readPiModelsStatus(opts),
+    settings: readPiSettings(opts),
+    packages,
+    extensions: readPiExtensions(opts),
+  };
+}
+
+/** Cheap existence probe for status lines that should not shell out. */
+export function piInstallHint(status: Pick<PiStatus, "agentDirPresent" | "piBinary">): string | null {
+  if (status.piBinary && status.agentDirPresent) return null;
+  if (!status.piBinary && !status.agentDirPresent) {
+    return "Pi is not installed (binary missing and ~/.pi/agent absent). Install: npm i -g @earendil-works/pi-coding-agent";
+  }
+  if (!status.piBinary) return "pi binary not on PATH; package install/remove will be unavailable.";
+  if (!status.agentDirPresent) return "Pi agent dir missing; run `pi` once to create ~/.pi/agent.";
+  return null;
+}
+
+export function modelsFileExists(opts: { piHome?: string } = {}): boolean {
+  return existsSync(piModelsPath(opts.piHome));
+}

package/src/pi/sync.ts

@@ -0,0 +1,75 @@
+/**
+ * Gather the visible catalog and inject providers.opencodex into Pi models.json.
+ * Mirrors grok/sync.ts: used by management apply route and CLI.
+ */
+import {
+  filterCatalogVisibleModels,
+  nativeOpenAiContextWindow,
+  visibleNativeSlugs,
+  type CatalogModel,
+} from "../codex/catalog";
+import type { OcxConfig } from "../types";
+import { injectPiModels, type PiInjectModel, type PiInjectResult } from "./models";
+
+export interface PiSyncDeps {
+  fetchAllModels: (config: OcxConfig) => Promise<CatalogModel[]>;
+  injectPiModels: typeof injectPiModels;
+}
+
+async function defaultFetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+  const { fetchAllModels } = await import("../server/management-api");
+  return fetchAllModels(config);
+}
+
+function catalogToPiModels(config: OcxConfig, routed: CatalogModel[]): PiInjectModel[] {
+  const native: PiInjectModel[] = visibleNativeSlugs(config).map(id => {
+    const contextWindow = nativeOpenAiContextWindow(id);
+    return {
+      namespaced: id,
+      provider: "openai",
+      id,
+      native: true,
+      ...(contextWindow !== undefined ? { contextWindow } : {}),
+      inputModalities: ["text", "image"],
+    };
+  });
+  const fromRouted: PiInjectModel[] = routed.map(m => {
+    const namespaced = m.alias ?? `${m.provider}/${m.id}`;
+    return {
+      namespaced,
+      provider: m.provider,
+      id: m.id,
+      ...(m.displayName !== undefined ? { displayName: m.displayName } : {}),
+      ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
+      inputModalities: m.inputModalities && m.inputModalities.length > 0
+        ? [...m.inputModalities]
+        : ["text"],
+    };
+  });
+  return [...native, ...fromRouted];
+}
+
+export async function syncPiConfig(
+  port: number,
+  config: OcxConfig,
+  opts: { hostname?: string; piHome?: string } = {},
+  deps: PiSyncDeps = { fetchAllModels: defaultFetchAllModels, injectPiModels },
+): Promise<PiInjectResult> {
+  let models: PiInjectModel[];
+  try {
+    const routed = filterCatalogVisibleModels(await deps.fetchAllModels(config), config);
+    models = catalogToPiModels(config, routed);
+  } catch (err) {
+    return {
+      ok: false,
+      changed: false,
+      message: `Pi config sync skipped: model catalog unavailable (${err instanceof Error ? err.message : String(err)})`,
+      modelsPath: "",
+      modelCount: 0,
+    };
+  }
+  return deps.injectPiModels(port, models, {
+    ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    ...(opts.piHome !== undefined ? { piHome: opts.piHome } : {}),
+  });
+}

package/src/providers/alibaba-region-backup.ts

@@ -0,0 +1,75 @@
+import { copyFileSync, existsSync, linkSync, readFileSync, rmSync } from "node:fs";
+import { getConfigPath } from "../config";
+
+export interface AlibabaBackupIO {
+  exists: (path: string) => boolean;
+  read: (path: string) => Buffer;
+  copy: (source: string, destination: string) => void;
+  /** Publish with no-replace semantics: fails with EEXIST if the destination exists. */
+  publishNoReplace: (temp: string, destination: string) => void;
+  remove: (path: string) => void;
+}
+
+const DEFAULT_IO: AlibabaBackupIO = {
+  exists: existsSync,
+  read: path => readFileSync(path),
+  copy: (source, destination) => copyFileSync(source, destination),
+  publishNoReplace: linkSync,
+  remove: path => rmSync(path, { force: true }),
+};
+
+export class AlibabaBackupIntegrityError extends Error {}
+
+/**
+ * Immutable pre-migration snapshot of `config.json`.
+ *
+ * Written to a temp file first and published by `link`, which fails with EEXIST
+ * rather than replacing. Exclusive *creation* alone is not enough: a crash
+ * mid-copy can leave a truncated destination that the next run would accept as a
+ * valid rollback point. Copy-verify-link means a published snapshot is always a
+ * complete one.
+ *
+ * An existing snapshot is NOT required to equal the current config. Demanding
+ * that has a false positive that would brick a working install: a run that
+ * created the snapshot and then aborted for an unrelated reason leaves a
+ * perfectly valid snapshot, the user then edits `config.json` legitimately, and
+ * every subsequent start would throw out of `startServer` and refuse to boot. A
+ * safety net must never become the thing that stops the product.
+ *
+ * So an existing snapshot is reused as-is — it is the earliest one, which is
+ * exactly what a rollback point should be. Integrity is carried by publication.
+ *
+ * Deliberately not built on `backupConfigBeforeOpenAiTierMigration`: that
+ * function's stale/rollback classification exists for a repeatable migration and
+ * would be wrong here.
+ */
+export function backupConfigBeforeAlibabaRegionMigration(
+  configPath = getConfigPath(),
+  io: AlibabaBackupIO = DEFAULT_IO,
+): "absent" | "created" | "reused" {
+  if (!io.exists(configPath)) return "absent";
+  const backup = `${configPath}.pre-alibaba-region-v1.bak`;
+  // The earliest snapshot is the most valuable one: it predates every migration
+  // this config has been through.
+  if (io.exists(backup)) return "reused";
+
+  const source = io.read(configPath);
+  const temp = `${backup}.${process.pid}.tmp`;
+  try {
+    io.copy(configPath, temp);
+    // Verify before publishing: a short copy must never become the snapshot.
+    if (!io.read(temp).equals(source)) {
+      throw new AlibabaBackupIntegrityError(`failed to write a complete backup to ${temp}`);
+    }
+    io.publishNoReplace(temp, backup);
+    return "created";
+  } catch (error) {
+    // Another process published between our `exists` check and the link. It went
+    // through the same copy-verify-link sequence, so it is complete by
+    // construction — nothing else writes this filename.
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return "reused";
+    throw error;
+  } finally {
+    io.remove(temp);
+  }
+}