@bitkyc08/opencodex 2.16.0 → 2.17.0

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

@@ -1,14 +1,11 @@
 /**
- * Source-preserving mutation for the one YAML fragment managed by OMP.
+ * Source-preserving mutation for one plain block-map YAML fragment.
  *
- * 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.
+ * 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";
 
@@ -18,6 +15,26 @@ interface SourceLine {
   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 };
@@ -54,11 +71,15 @@ 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(`^${key}:[ ]*(?:#.*)?$`, "u").test(rest);
+  return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
 }
 
 function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
@@ -86,9 +107,8 @@ function childEnd(
     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.
+    // 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;
@@ -112,8 +132,7 @@ function canonicalValue(value: unknown): unknown {
 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));
+    return JSON.stringify(canonicalValue(parsed)) === JSON.stringify(canonicalValue(expected));
   } catch {
     return false;
   }
@@ -123,108 +142,217 @@ 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;
+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;
   }
-  if (providerIndexes.length !== 1) return null;
+  return cursor;
+}
 
-  const providersIndex = providerIndexes[0]!;
-  const providersEnd = containerEnd(lines, providersIndex, 0);
-  if (providersEnd === null) return null;
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 
-  let inferredIndent: number | null = null;
-  for (let index = providersIndex + 1; index < providersEnd; index += 1) {
+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 > 0) {
-      inferredIndent = inferredIndent === null ? spaces : Math.min(inferredIndent, spaces);
+    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);
   }
-  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;
+  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 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 { 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)}`;
+}
 
-  if (mutation.kind === "upsert") {
-    const patched = `${text.slice(0, startOffset)}${renderedEntry(mutation.value, childIndent, eol)}${text.slice(endOffset)}`;
-    return semanticallyMatches(patched, expected) ? patched : null;
+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 };
+}
 
-  let patched = `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
-  if (mutation.removeEmptyProviders) {
-    let remaining: { providers?: unknown } | null;
-    try {
-      remaining = Bun.YAML.parse(patched) as { providers?: unknown } | null;
-    } catch {
-      return 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)}`;
-    }
+/** 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;
   }
-  return semanticallyMatches(patched, expected) ? patched : 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/registry.ts

@@ -12,6 +12,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import {
   EXPORT_CLIENTS,
+  dshConfigPath,
+  dshHomeDir,
   gajaeConfigPath,
   gajaeHomeDir,
   hermesConfigPath,
@@ -38,6 +40,10 @@ export interface IntegrationClientSpec {
   configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
   detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /** Patch only this block-map YAML leaf; never re-render the shared file. */
+  sourcePreservingYaml?: { path: readonly string[] };
+  /** Coordinate the complete mutation through a sibling config lock. */
+  writerLock?: { suffix: ".lock" };
 }
 
 /**
@@ -74,6 +80,7 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     id: "omp",
     configPath: (env = process.env, home = homedir()) => ompModelsConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => ompAgentDir(env, home),
+    sourcePreservingYaml: { path: ["providers", "opencodex"] },
   },
   hermes: {
     id: "hermes",
@@ -98,6 +105,13 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     configPath: (env = process.env, home = homedir()) => gajaeConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => gajaeHomeDir(env, home),
   },
+  dsh: {
+    id: "dsh",
+    configPath: (env = process.env, home = homedir()) => dshConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => dshHomeDir(env, home),
+    sourcePreservingYaml: { path: ["llm-pi-ai", "providers", "opencodex"] },
+    writerLock: { suffix: ".lock" },
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/integrations/state.ts

@@ -136,8 +136,8 @@ function recordedFragmentFingerprint(
  * what we may rewrite, and the contribution hash proves our catalog has not
  * moved on. Three classes of client (revising the unconditional whole-file
  * rule of devlog 260802_client_toggle_api/021 §3 for json — #1631):
- * OMP is fragment-scoped because its writer patches only
- * `providers.opencodex`, so the whole-file check is skipped entirely;
+ * registry-declared source-preserving YAML clients are fragment-scoped because
+ * their writers patch only the owned leaf, so the whole-file check is skipped;
  * strict-json clients keep the whole-file check but downgrade a drift with
  * intact owned fragments to `stale`, because a rewrite there can lose only
  * formatting (comments cannot parse, non-round-tripping numbers are refused
@@ -194,7 +194,8 @@ export function classifyIntegration(input: {
   if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
     return { state: "conflict", reason: "foreign-edit" };
   }
-  if (clientId !== "omp" && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+  if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml
+    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
     /*
      * The file changed since we wrote it, but every fragment we own is still
      * byte-for-byte what we put there — a sibling edit, not tampering. Apply

package/src/integrations/writer-lock.ts

@@ -0,0 +1,98 @@
+import { rm, writeFile } from "node:fs/promises";
+
+const LOCK_DEADLINE_MS = 2_000;
+const LOCK_DELAYS_MS = [20, 40, 80, 160, 200] as const;
+
+export interface IntegrationWriterLockSeams {
+  writeFile: (
+    path: string,
+    payload: string,
+    options: { flag: "wx"; mode: 0o600 },
+  ) => Promise<void>;
+  removeFile: (path: string) => Promise<void>;
+  now: () => number;
+  delay: (milliseconds: number) => Promise<void>;
+  pid: number;
+}
+
+export class IntegrationWriterLockBusyError extends Error {
+  constructor(readonly lockPath: string) {
+    super("integration_mutation_busy");
+    this.name = "IntegrationWriterLockBusyError";
+  }
+}
+
+export class IntegrationWriterLockIOError extends Error {
+  constructor(readonly lockPath: string, readonly operation: "acquire" | "release", cause: unknown) {
+    // The management route returns Error.message to its caller. Keep the
+    // private config path and OS diagnostic on typed fields/cause, not the wire.
+    super(`integration writer lock ${operation} failed`, { cause });
+    this.name = "IntegrationWriterLockIOError";
+  }
+}
+
+const defaultSeams: IntegrationWriterLockSeams = {
+  writeFile: async (path, payload, options) => { await writeFile(path, payload, options); },
+  // Match DSH rc.6: an already-absent lock is a successful release.
+  removeFile: async path => { await rm(path, { force: true }); },
+  now: () => Date.now(),
+  delay: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+  pid: process.pid,
+};
+
+function errorCode(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+/**
+ * Hold the exact sibling `<settings>.lock` around one complete transaction.
+ * A contender is never deleted: release runs only after our exclusive create
+ * succeeded.
+ */
+export async function withIntegrationWriterLock<T>(
+  configPath: string,
+  operation: () => Promise<T>,
+  seams: IntegrationWriterLockSeams = defaultSeams,
+  suffix: ".lock" = ".lock",
+): Promise<T> {
+  const lockPath = `${configPath}${suffix}`;
+  const startedAt = seams.now();
+  let delayIndex = 0;
+  for (;;) {
+    try {
+      await seams.writeFile(lockPath, `${seams.pid}\n`, { flag: "wx", mode: 0o600 });
+      break;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") {
+        throw new IntegrationWriterLockIOError(lockPath, "acquire", error);
+      }
+      const elapsedMs = seams.now() - startedAt;
+      if (elapsedMs >= LOCK_DEADLINE_MS) {
+        throw new IntegrationWriterLockBusyError(lockPath);
+      }
+      const backoffMs = LOCK_DELAYS_MS[Math.min(delayIndex, LOCK_DELAYS_MS.length - 1)]!;
+      // Keep the final retry inside the advertised two-second deadline.
+      const delayMs = Math.min(backoffMs, LOCK_DEADLINE_MS - elapsedMs);
+      delayIndex += 1;
+      await seams.delay(delayMs);
+    }
+  }
+
+  let outcome: { ok: true; value: T } | { ok: false; error: unknown };
+  try {
+    outcome = { ok: true, value: await operation() };
+  } catch (error) {
+    outcome = { ok: false, error };
+  }
+  try {
+    await seams.removeFile(lockPath);
+  } catch (error) {
+    // Cleanup cannot replace the protected operation's actual failure.
+    if (!outcome.ok) throw outcome.error;
+    throw new IntegrationWriterLockIOError(lockPath, "release", error);
+  }
+  if (!outcome.ok) throw outcome.error;
+  return outcome.value;
+}