@iislee/opencodex 2.11.0 → 2.35.0

package/src/integrations/omp-yaml-source.ts

@@ -0,0 +1,358 @@
+/**
+ * Source-preserving mutation for one plain block-map YAML fragment.
+ *
+ * Shared client settings are not ours to re-render. This scanner accepts only
+ * the small, unambiguous source shape we can patch byte-for-byte around the
+ * owned leaf. Every candidate is parsed again and compared with the complete
+ * expected document; unsupported YAML fails closed and never falls back to a
+ * whole-document serializer.
+ */
+import { renderYaml } from "./serialize";
+
+interface SourceLine {
+  start: number;
+  end: number;
+  body: string;
+}
+
+interface LocatedEntry {
+  lines: readonly SourceLine[];
+  index: number;
+  indent: number;
+  endIndex: number;
+}
+
+interface MissingEntry {
+  lines: readonly SourceLine[];
+  missingDepth: number;
+  indent: number;
+  insertAt: number;
+}
+
+type LocatedPath = { kind: "existing"; entry: LocatedEntry } | { kind: "missing"; entry: MissingEntry };
+
+export type YamlFragmentMutation =
+  | { kind: "upsert"; value: unknown }
+  | { kind: "remove"; createdContainers: readonly string[] };
+
+export type OmpYamlMutation =
+  | { kind: "upsert"; value: unknown }
+  | { kind: "remove"; removeEmptyProviders: boolean };
+
+function sourceLines(text: string): SourceLine[] {
+  const lines: SourceLine[] = [];
+  const matcher = /[^\r\n]*(?:\r\n|\n|$)/gu;
+  for (const match of text.matchAll(matcher)) {
+    const raw = match[0];
+    if (raw.length === 0) continue;
+    const start = match.index;
+    const body = raw.endsWith("\r\n")
+      ? raw.slice(0, -2)
+      : raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    lines.push({ start, end: start + raw.length, body });
+  }
+  return lines;
+}
+
+function leadingSpaces(line: string): number | null {
+  const leading = line.match(/^[ \t]*/u)?.[0] ?? "";
+  return leading.includes("\t") ? null : leading.length;
+}
+
+function isBlank(line: string): boolean {
+  return line.trim().length === 0;
+}
+
+function isComment(line: string): boolean {
+  return line.trimStart().startsWith("#");
+}
+
+function hasInlineComment(line: string): boolean {
+  return line.includes("#");
+}
+
+function regexpEscape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function isPlainBlockKey(line: string, indent: number, key: string): boolean {
+  const spaces = leadingSpaces(line);
+  if (spaces !== indent) return false;
+  const rest = line.slice(indent);
+  return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
+}
+
+function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (isBlank(body)) continue;
+    if (isComment(body)) {
+      if (spaces <= indent) return index;
+      continue;
+    }
+    if (spaces <= indent) return index;
+  }
+  return lines.length;
+}
+
+function childEnd(
+  lines: readonly SourceLine[],
+  start: number,
+  parentEnd: number,
+  indent: number,
+): number | null {
+  for (let index = start + 1; index < parentEnd; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    // Blank lines and same-level comments remain outside our replacement.
+    // Deeper comments belong to the leaf and would be destroyed, so refuse.
+    if (isBlank(body)) return index;
+    if (isComment(body)) return spaces <= indent ? index : null;
+    if (spaces <= indent) return index;
+    if (hasInlineComment(body)) return null;
+  }
+  return parentEnd;
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalValue(child)]),
+    );
+  }
+  return value;
+}
+
+function semanticallyMatches(text: string, expected: unknown): boolean {
+  try {
+    const parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+    return JSON.stringify(canonicalValue(parsed)) === JSON.stringify(canonicalValue(expected));
+  } catch {
+    return false;
+  }
+}
+
+function lineEnding(text: string): "\n" | "\r\n" {
+  return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor = doc;
+  for (const key of path) {
+    if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+    if (cursor === undefined) return undefined;
+  }
+  return cursor;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function immediateIndent(
+  lines: readonly SourceLine[],
+  start: number,
+  end: number,
+  parentIndent: number,
+): number | null {
+  let indent: number | null = null;
+  for (let index = start; index < end; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (isBlank(body) || isComment(body) || spaces <= parentIndent) continue;
+    indent = indent === null ? spaces : Math.min(indent, spaces);
+  }
+  return indent ?? parentIndent + 2;
+}
+
+/** Locate a path only when every present segment is a plain block-map key. */
+function locatePath(text: string, parsed: unknown, path: readonly string[]): LocatedPath | null {
+  if (path.length === 0 || !isPlainRecord(parsed)) return null;
+  const lines = sourceLines(text);
+  if (lines.some(line => leadingSpaces(line.body) === null)) return null;
+
+  let rangeStart = 0;
+  let rangeEnd = lines.length;
+  let parentIndent = -2;
+  const prefix: string[] = [];
+  for (let depth = 0; depth < path.length; depth += 1) {
+    const indent = depth === 0 ? 0 : immediateIndent(lines, rangeStart, rangeEnd, parentIndent);
+    if (indent === null) return null;
+    const matches: number[] = [];
+    for (let index = rangeStart; index < rangeEnd; index += 1) {
+      if (isPlainBlockKey(lines[index]!.body, indent, path[depth]!)) matches.push(index);
+    }
+    if (matches.length > 1) return null;
+    prefix.push(path[depth]!);
+    if (matches.length === 0) {
+      // The parser saw this key through syntax we do not patch (quoted/flow,
+      // merge aliases, or an ambiguous indentation shape).
+      if (readPath(parsed, prefix) !== undefined) return null;
+      const insertAt = rangeEnd < lines.length ? lines[rangeEnd]!.start : text.length;
+      return { kind: "missing", entry: { lines, missingDepth: depth, indent, insertAt } };
+    }
+
+    const index = matches[0]!;
+    const end = containerEnd(lines, index, indent);
+    if (end === null) return null;
+    if (depth === path.length - 1) {
+      if (hasInlineComment(lines[index]!.body)) return null;
+      const leafEnd = childEnd(lines, index, end, indent);
+      if (leafEnd === null) return null;
+      return { kind: "existing", entry: { lines, index, indent, endIndex: leafEnd } };
+    }
+    if (!isPlainRecord(readPath(parsed, prefix))) return null;
+    rangeStart = index + 1;
+    rangeEnd = end;
+    parentIndent = indent;
+  }
+  return null;
+}
+
+function nestedValue(path: readonly string[], value: unknown): Record<string, unknown> {
+  let nested: unknown = value;
+  for (let index = path.length - 1; index >= 0; index -= 1) nested = { [path[index]!]: nested };
+  return nested as Record<string, unknown>;
+}
+
+function rendered(value: unknown, indent: number, eol: "\n" | "\r\n"): string {
+  return renderYaml(value as Record<string, unknown>, indent).replaceAll("\n", eol);
+}
+
+function preserveFinalNewline(candidate: string, original: string, eol: "\n" | "\r\n"): string {
+  if (original.length > 0 && !original.endsWith("\n") && candidate.endsWith(eol)) {
+    return candidate.slice(0, -eol.length);
+  }
+  return candidate;
+}
+
+function upsertSource(
+  text: string,
+  parsed: unknown,
+  path: readonly string[],
+  value: unknown,
+): string | null {
+  const located = locatePath(text, parsed, path);
+  if (located === null) return null;
+  const eol = lineEnding(text);
+  if (located.kind === "existing") {
+    const { lines, index, indent, endIndex } = located.entry;
+    const startOffset = lines[index]!.start;
+    const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+    const candidate = `${text.slice(0, startOffset)}${rendered({ [path[path.length - 1]!]: value }, indent, eol)}${text.slice(endOffset)}`;
+    return preserveFinalNewline(candidate, text, eol);
+  }
+
+  const { missingDepth, indent, insertAt } = located.entry;
+  const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
+  const insertion = rendered(nestedValue(path.slice(missingDepth), value), indent, eol);
+  const candidate = `${text.slice(0, insertAt)}${prefix}${insertion}${text.slice(insertAt)}`;
+  return preserveFinalNewline(candidate, text, eol);
+}
+
+function removeExactPath(text: string, path: readonly string[], requireEmpty: boolean): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
+  }
+  const located = locatePath(text, parsed, path);
+  if (located === null || located.kind !== "existing") return null;
+  const { lines, index, endIndex } = located.entry;
+  const startOffset = lines[index]!.start;
+  const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+  if (requireEmpty) {
+    const sourceBody = text.slice(lines[index]!.end, endOffset);
+    if (sourceBody.trim().length > 0) return null;
+  }
+  return `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
+}
+
+function planSourceRemoval(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): { text: string; prunedContainers: string[] } | null {
+  let next = removeExactPath(text, path, false);
+  if (next === null) return null;
+  const created = new Set(createdContainers);
+  const prunedContainers: string[] = [];
+  for (let depth = path.length - 1; depth >= 1; depth -= 1) {
+    const containerPath = path.slice(0, depth);
+    const encoded = containerPath.join("\u0000");
+    if (!created.has(encoded)) continue;
+    const pruned = removeExactPath(next, containerPath, true);
+    // A user-added sibling/comment makes this ancestor source-owned now. Keep
+    // it (and every parent) while still removing our leaf.
+    if (pruned === null) break;
+    next = pruned;
+    prunedContainers.push(encoded);
+  }
+  return { text: next, prunedContainers };
+}
+
+/** Containers whose source ranges are still empty and safe to prune. */
+export function sourcePrunableYamlContainers(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): readonly string[] | null {
+  return planSourceRemoval(text, path, createdContainers)?.prunedContainers ?? null;
+}
+
+function removeSource(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): string | null {
+  return planSourceRemoval(text, path, createdContainers)?.text ?? null;
+}
+
+/**
+ * Patch one arbitrary plain block-map path, preserving every other byte.
+ */
+export function patchYamlFragmentSource(
+  text: string,
+  path: readonly string[],
+  mutation: YamlFragmentMutation,
+  expected: unknown,
+): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
+  }
+  const patched = mutation.kind === "upsert"
+    ? upsertSource(text, parsed, path, mutation.value)
+    : removeSource(text, path, mutation.createdContainers);
+  return patched !== null && semanticallyMatches(patched, expected) ? patched : null;
+}
+
+/** Backward-compatible OMP wrapper around the generic path patcher. */
+export function patchOmpYamlSource(
+  text: string,
+  mutation: OmpYamlMutation,
+  expected: unknown,
+): string | null {
+  return patchYamlFragmentSource(
+    text,
+    ["providers", "opencodex"],
+    mutation.kind === "upsert"
+      ? mutation
+      : {
+          kind: "remove",
+          createdContainers: mutation.removeEmptyProviders ? ["providers"] : [],
+        },
+    expected,
+  );
+}

package/src/integrations/owned-refresh.ts

@@ -0,0 +1,74 @@
+/**
+ * Refresh a file integration only when OpenCodex already owns its block.
+ *
+ * This is the safe bridge between an implicit operation such as `ocx sync`
+ * and the explicit integration writer. An implicit sync may update a block
+ * the user previously enabled, but it must never claim an unowned block,
+ * recreate one the user removed, or overwrite edits made after our write.
+ */
+import type { ExportModel } from "../clients/config-export";
+import type { OcxConfig } from "../types";
+import type { IntegrationIO } from "./config-io";
+import type { IntegrationClientId } from "./registry";
+import { runIntegrationMutationFlight } from "./mutation-flight";
+import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
+import {
+  refreshIntegrationCoordinated,
+  type CoordinatedIntegrationOptions,
+} from "./writer";
+
+export interface OwnedIntegrationRefreshInput {
+  clientId: IntegrationClientId;
+  /** Lazy in `ocx sync`, so an unowned client does not even load the catalog. */
+  models: readonly ExportModel[] | (() => Promise<readonly ExportModel[]>);
+  config: OcxConfig;
+  port: number;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  store?: IntegrationStateStore;
+  io?: IntegrationIO;
+}
+
+export interface OwnedIntegrationRefreshOutcome {
+  readonly client: IntegrationClientId;
+  readonly ok: boolean;
+  readonly changed?: boolean;
+  readonly reason?: string;
+}
+
+/**
+ * Returns `null` when the client has never been connected by OpenCodex.
+ * Callers use that distinction to report "left alone" rather than "skipped".
+ */
+export async function refreshOwnedIntegration(
+  input: OwnedIntegrationRefreshInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<OwnedIntegrationRefreshOutcome | null> {
+  const store = input.store ?? createIntegrationStateStore();
+
+  // The ownership record is the user's durable opt-in. Do this check before
+  // reading or classifying the target so an implicit sync can never turn an
+  // unowned provider block into one of ours.
+  const record = store.readRecords()[input.clientId];
+  if (!record || record.clientId !== input.clientId) return null;
+
+  const { models: suppliedModels, ...rest } = input;
+  const models = typeof suppliedModels === "function"
+    ? await suppliedModels()
+    : suppliedModels;
+  const bound = { ...rest, models, store };
+  const result = await runIntegrationMutationFlight(
+    input.clientId,
+    "refresh",
+    input.io?.now ?? Date.now,
+    () => refreshIntegrationCoordinated(bound, options),
+  );
+  return result.ok
+    ? {
+        client: input.clientId,
+        ok: true,
+        changed: result.changed,
+        ...(result.state === "absent" ? { reason: result.message } : {}),
+      }
+    : { client: input.clientId, ok: false, reason: result.message };
+}

package/src/integrations/ownership-policy.ts

@@ -0,0 +1,160 @@
+/**
+ * Client-scoped exceptions to strict managed-fragment ownership.
+ *
+ * Most clients must preserve every byte represented by their managed
+ * contribution. A client that persists runtime-derived fields back into an
+ * OpenCodex-owned fragment needs a narrower contract: name the exact paths it
+ * may rewrite, then fingerprint everything else. Keeping that policy here
+ * prevents a client quirk from weakening the shared classifier.
+ */
+import {
+  OPENCODE_PROVIDER_ID,
+  type ManagedContribution,
+  type ManagedFragment,
+} from "../clients/config-export";
+import { canonicalContribution, fingerprint, semanticContribution } from "./ownership";
+
+type JsonObject = Record<string, unknown>;
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
+  return prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
+}
+
+/** Delete one nested object member and prune only the empty ancestors created by that deletion. */
+function deletePath(root: unknown, path: readonly string[]): void {
+  if (!isObject(root) || path.length === 0) return;
+  const parents: Array<{ parent: JsonObject; key: string }> = [];
+  let cursor: JsonObject = root;
+  for (let index = 0; index < path.length - 1; index += 1) {
+    const key = path[index]!;
+    const next = cursor[key];
+    if (!isObject(next)) return;
+    parents.push({ parent: cursor, key });
+    cursor = next;
+  }
+  delete cursor[path[path.length - 1]!];
+  for (let index = parents.length - 1; index >= 0; index -= 1) {
+    if (Object.keys(cursor).length > 0) break;
+    const { parent, key } = parents[index]!;
+    delete parent[key];
+    cursor = parent;
+  }
+}
+
+function cloneFragment(fragment: ManagedFragment): ManagedFragment {
+  return {
+    path: [...fragment.path],
+    value: structuredClone(fragment.value),
+  };
+}
+
+/**
+ * Paths a client is documented to derive after OpenCodex writes its block.
+ *
+ * ZCode 3.8.1 persists reasoning and output defaults for every generated
+ * model. It may also fill a context default when OpenCodex intentionally
+ * omitted one; an authoritative context emitted by OpenCodex remains
+ * protected and is never listed here.
+ */
+export function refreshablePathsOf(
+  contribution: ManagedContribution,
+): readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode") return [];
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return [];
+
+  const paths: string[][] = [];
+  for (const modelId of Object.keys(fragment.value.models).sort()) {
+    const entry = fragment.value.models[modelId];
+    if (!isObject(entry)) continue;
+    const base = [...fragment.path, "models", modelId];
+    paths.push([...base, "reasoning"]);
+    paths.push([...base, "limit", "output"]);
+    const limit = entry.limit;
+    if (!isObject(limit) || typeof limit.context !== "number") {
+      paths.push([...base, "limit", "context"]);
+    }
+  }
+  return paths;
+}
+
+export function validRefreshablePaths(
+  contribution: ManagedContribution,
+  value: unknown,
+): value is readonly (readonly string[])[] {
+  if (contribution.clientId !== "zcode" || !Array.isArray(value) || value.length === 0) {
+    return false;
+  }
+  const fragment = contribution.fragments.find(candidate => (
+    candidate.path.length === 2
+    && candidate.path[0] === "provider"
+    && candidate.path[1] === OPENCODE_PROVIDER_ID
+  ));
+  if (!fragment || !isObject(fragment.value) || !isObject(fragment.value.models)) return false;
+
+  const modelIds = new Set(Object.keys(fragment.value.models));
+  const seen = new Set<string>();
+  return value.every(path => {
+    if (!Array.isArray(path) || !path.every(part => typeof part === "string")) return false;
+    const modelId = path[3];
+    const isReasoning = path.length === 5 && path[4] === "reasoning";
+    const isLimitDefault = path.length === 6
+      && path[4] === "limit"
+      && (path[5] === "output" || path[5] === "context");
+    const key = path.join("\u0000");
+    if (
+      path[0] !== "provider"
+      || path[1] !== OPENCODE_PROVIDER_ID
+      || path[2] !== "models"
+      || typeof modelId !== "string"
+      || !modelIds.has(modelId)
+      || (!isReasoning && !isLimitDefault)
+      || seen.has(key)
+    ) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function contributionWithoutRefreshablePaths(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): ManagedContribution {
+  const fragments = contribution.fragments.map(cloneFragment);
+  for (const refreshablePath of refreshablePaths) {
+    for (const fragment of fragments) {
+      if (!pathStartsWith(refreshablePath, fragment.path)) continue;
+      deletePath(fragment.value, refreshablePath.slice(fragment.path.length));
+      break;
+    }
+  }
+  return { ...contribution, fragments };
+}
+
+/** Fingerprint a contribution after removing only its explicitly refreshable paths. */
+export function protectedContributionFingerprint(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): string {
+  return fingerprint(canonicalContribution(
+    contributionWithoutRefreshablePaths(contribution, refreshablePaths),
+  ));
+}
+
+/** Semantic protected fingerprint that ignores JSON object-key order only. */
+export function semanticProtectedContributionFingerprint(
+  contribution: ManagedContribution,
+  refreshablePaths: readonly (readonly string[])[],
+): string {
+  return fingerprint(semanticContribution(
+    contributionWithoutRefreshablePaths(contribution, refreshablePaths),
+  ));
+}