@bitkyc08/opencodex 2.11.1 → 2.12.0

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

@@ -0,0 +1,225 @@
+/**
+ * Source-preserving mutation for the one YAML fragment managed by OMP.
+ *
+ * The general integration writer operates on parsed documents. Re-rendering a
+ * shared YAML file would preserve values but destroy comments and formatting
+ * outside `providers.opencodex`. OMP is the only client whose ownership model
+ * deliberately permits those unrelated source edits, so its writer replaces
+ * or removes only the exact block-style mapping entry it owns.
+ *
+ * Unsupported or ambiguous YAML returns `null`. The caller treats that as an
+ * unsafe refusal instead of falling back to whole-document serialization.
+ */
+import { renderYaml } from "./serialize";
+
+interface SourceLine {
+  start: number;
+  end: number;
+  body: 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 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(`^${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 are conservatively outside the
+    // managed entry. Deeper comments would be destroyed by replacement, so
+    // refuse rather than guessing whether the user meant to keep them.
+    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 renderedEntry(value: unknown, indent: number, eol: "\n" | "\r\n"): string {
+  return renderYaml({ opencodex: value }, indent).replaceAll("\n", eol);
+}
+
+/**
+ * Patch `providers.opencodex` while preserving every byte outside that entry.
+ * The returned text is parsed and compared with `expected` before it is
+ * accepted, so a scanner mistake fails closed rather than writing bad YAML.
+ */
+export function patchOmpYamlSource(
+  text: string,
+  mutation: OmpYamlMutation,
+  expected: unknown,
+): string | null {
+  const lines = sourceLines(text);
+  const eol = lineEnding(text);
+  const providerIndexes = lines
+    .map((line, index) => isPlainBlockKey(line.body, 0, "providers") ? index : -1)
+    .filter(index => index >= 0);
+
+  if (providerIndexes.length === 0) {
+    if (mutation.kind === "remove") return null;
+    const separator = text.length === 0 || text.endsWith("\n") ? "" : eol;
+    const patched = `${text}${separator}providers:${eol}${renderedEntry(mutation.value, 2, eol)}`;
+    return semanticallyMatches(patched, expected) ? patched : null;
+  }
+  if (providerIndexes.length !== 1) return null;
+
+  const providersIndex = providerIndexes[0]!;
+  const providersEnd = containerEnd(lines, providersIndex, 0);
+  if (providersEnd === null) return null;
+
+  let inferredIndent: number | null = null;
+  for (let index = providersIndex + 1; index < providersEnd; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (!isBlank(body) && !isComment(body) && spaces > 0) {
+      inferredIndent = inferredIndent === null ? spaces : Math.min(inferredIndent, spaces);
+    }
+  }
+  const childIndexes = inferredIndent === null
+    ? []
+    : lines.slice(providersIndex + 1, providersEnd)
+      .map((line, offset) => (
+        isPlainBlockKey(line.body, inferredIndent!, "opencodex")
+          ? providersIndex + 1 + offset
+          : -1
+      ))
+      .filter(index => index >= 0);
+  if (childIndexes.length > 1) return null;
+
+  const childIndex = childIndexes[0];
+  if (childIndex === undefined) {
+    if (mutation.kind === "remove") return null;
+    const indent = inferredIndent ?? 2;
+    const insertAt = providersEnd < lines.length ? lines[providersEnd]!.start : text.length;
+    const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
+    const patched = `${text.slice(0, insertAt)}${prefix}${renderedEntry(mutation.value, indent, eol)}${text.slice(insertAt)}`;
+    return semanticallyMatches(patched, expected) ? patched : null;
+  }
+
+  const childIndent = leadingSpaces(lines[childIndex]!.body);
+  if (childIndent === null || childIndent <= 0) return null;
+  if (hasInlineComment(lines[childIndex]!.body)) return null;
+  const endIndex = childEnd(lines, childIndex, providersEnd, childIndent);
+  if (endIndex === null) return null;
+  const startOffset = lines[childIndex]!.start;
+  const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+
+  if (mutation.kind === "upsert") {
+    const patched = `${text.slice(0, startOffset)}${renderedEntry(mutation.value, childIndent, eol)}${text.slice(endOffset)}`;
+    return semanticallyMatches(patched, expected) ? patched : null;
+  }
+
+  let patched = `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
+  if (mutation.removeEmptyProviders) {
+    const remaining = Bun.YAML.parse(patched) as { providers?: unknown } | null;
+    if (remaining && Object.hasOwn(remaining, "providers")) {
+      const provider = remaining.providers;
+      const empty = provider === null || (
+        provider && typeof provider === "object" && !Array.isArray(provider)
+        && Object.keys(provider as Record<string, unknown>).length === 0
+      );
+      if (!empty) return semanticallyMatches(patched, expected) ? patched : null;
+      if (hasInlineComment(lines[providersIndex]!.body)) return null;
+
+      const providerStart = lines[providersIndex]!.start;
+      // Removing a container we created is safe only when nothing but our
+      // entry occupied its source range. Comments or blank formatting make
+      // that range user-owned and therefore ambiguous.
+      for (let index = providersIndex + 1; index < providersEnd; index += 1) {
+        if (index >= childIndex && index < endIndex) continue;
+        if (lines[index]!.body.length > 0) return null;
+      }
+      patched = `${text.slice(0, providerStart)}${text.slice(endOffset)}`;
+    }
+  }
+  return semanticallyMatches(patched, expected) ? patched : null;
+}

package/src/integrations/ownership.ts

@@ -2,10 +2,10 @@
  * What opencodex remembers about a client between operations.
  *
  * Two hashes, because the two questions are genuinely independent: the FILE
- * hash answers "did anyone touch this after us", and the BLOCK hash answers "is
- * our content still what we would write today". One hash cannot do both, and
- * conflating them is what lets a foreign edit read as ordinary drift — which
- * would then be silently overwritten.
+ * hash identifies the exact result for restore and for clients whose writer
+ * re-serializes the whole document. The BLOCK hash identifies OMP's surgically
+ * patched fragment and detects catalog drift. One hash cannot safely answer
+ * both questions in a shared client config.
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §2.
  */
@@ -37,7 +37,7 @@ export function canonicalContribution(contribution: ManagedContribution): string
 export interface OwnershipRecord {
   clientId: IntegrationClientId;
   configPath: string;
-  /** Hash of the WHOLE file as we left it — detects foreign edits after us. */
+  /** Hash of the WHOLE file as we left it — protects whole-file restore. */
   fileFingerprint: string;
   /** Hash of our contribution — detects catalog/port drift. */
   blockFingerprint: string;

package/src/integrations/state.ts

@@ -2,9 +2,9 @@
  * "What is on disk, and did we put it there?"
  *
  * The classifier is deliberately ordered, and the order is load-bearing: an
- * unreadable file can never be reported as absent, and a foreign edit can never
- * be reported as ordinary drift. Getting that wrong would let `disable` delete
- * a user's own edits.
+ * unreadable file can never be reported as absent, and an edit to a fragment
+ * we own can never be reported as ordinary drift. Getting that wrong would let
+ * `disable` delete a user's own edits.
  *
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §3.
  */
@@ -100,8 +100,43 @@ export function blockedContainerPath(
 }
 
 /**
- * The two-axis rule: the FILE hash proves nobody touched the file after us, and
- * the BLOCK hash proves our content is still what we would write today.
+ * Fingerprint the recorded fragments as they appear in the document now.
+ *
+ * The record intentionally names every path we own. Comparing just those
+ * values lets another integration or a user add a sibling without blocking a
+ * later refresh, while a change inside our block still fails closed.
+ */
+function recordedFragmentFingerprint(
+  doc: unknown,
+  record: OwnershipRecord,
+): string | null {
+  if (
+    !Array.isArray(record.fragmentPaths)
+    || record.fragmentPaths.length === 0
+    || !record.fragmentPaths.every(path => (
+      Array.isArray(path)
+      && path.length > 0
+      && path.every(key => typeof key === "string")
+    ))
+  ) return null;
+  const fragments = [];
+  for (const path of record.fragmentPaths) {
+    const value = readPath(doc, path);
+    if (value === undefined) return null;
+    fragments.push({ path, value });
+  }
+  return fingerprint(canonicalContribution({
+    clientId: record.clientId,
+    fragments,
+  }));
+}
+
+/**
+ * The two-axis rule: the recorded bytes or fragments prove nobody changed
+ * what we may rewrite, and the contribution hash proves our catalog has not
+ * moved on. OMP is the sole fragment-scoped client because its writer patches
+ * only `providers.opencodex`; every whole-document serializer retains the
+ * whole-file fingerprint guard.
  */
 export function classifyIntegration(input: {
   fileText: string | null;
@@ -144,7 +179,11 @@ export function classifyIntegration(input: {
   if (input.configPath !== undefined && input.record.configPath !== input.configPath) {
     return { state: "conflict", reason: "unowned-key" };
   }
-  if (fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+  const clientId = input.clientId ?? input.record.clientId;
+  if (clientId !== "omp" && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+    return { state: "conflict", reason: "foreign-edit" };
+  }
+  if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
     return { state: "conflict", reason: "foreign-edit" };
   }
   return input.record.blockFingerprint === fingerprint(canonicalContribution(input.contribution))

package/src/integrations/writer.ts

@@ -10,7 +10,7 @@
  * Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
  */
 import { dirname } from "node:path";
-import { EXPORT_CLIENTS, type ExportModel } from "../clients/config-export";
+import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { isLoopbackHostname } from "../codex/inject";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
@@ -23,6 +23,7 @@ import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
+import { patchOmpYamlSource } from "./omp-yaml-source";
 
 export type RefusalReason =
   | "not_installed"
@@ -168,6 +169,15 @@ function snapshotAbsPath(store: IntegrationStateStore, entry: JournalEntry): str
   return snapshot.kind === "stored" ? snapshot.path : undefined;
 }
 
+function ompFragmentValue(contribution: ManagedContribution): unknown | undefined {
+  const fragment = contribution.fragments.find(item => (
+    item.path.length === 2
+    && item.path[0] === "providers"
+    && item.path[1] === "opencodex"
+  ));
+  return fragment?.value;
+}
+
 /** Shared preflight: detect, gate, read, parse and classify. */
 function preflight(input: IntegrationWriteInput) {
   const store = input.store ?? createIntegrationStateStore();
@@ -280,9 +290,22 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
    * user as a 500 with no path and no advice; it is a refusal like any other,
    * and the file is untouched because this happens before any write.
    */
+  const nextDocument = mergeContribution(base, contribution);
   let text: string;
   try {
-    text = serializeDocument(mergeContribution(base, contribution), exportSpec.format);
+    if (clientId === "omp" && before !== null) {
+      const value = ompFragmentValue(contribution);
+      const patched = value === undefined
+        ? null
+        : patchOmpYamlSource(before, { kind: "upsert", value }, nextDocument);
+      if (patched === null) {
+        return refuse(clientId, "unsafe", "unsafe",
+          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so it was left alone`);
+      }
+      text = patched;
+    } else {
+      text = serializeDocument(nextDocument, exportSpec.format);
+    }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
     return refuse(clientId, "unsafe", "unsafe",
@@ -357,7 +380,19 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   }
   let text: string;
   try {
-    text = serializeDocument(doc, exportSpec.format);
+    if (clientId === "omp" && before !== null) {
+      const patched = patchOmpYamlSource(before, {
+        kind: "remove",
+        removeEmptyProviders: record!.createdContainers?.includes("providers") === true,
+      }, doc);
+      if (patched === null) {
+        return refuse(clientId, "unsafe", "unsafe",
+          `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so nothing was removed`);
+      }
+      text = patched;
+    } else {
+      text = serializeDocument(doc, exportSpec.format);
+    }
   } catch (error) {
     if (!(error instanceof UnserializableValueError)) throw error;
     return refuse(clientId, "unsafe", "unsafe",