@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/integrations/registry.ts

@@ -43,6 +43,11 @@ import {
   raycastConfigPath,
   zcodeConfigPath,
   zcodeHomeDir,
+  zcodeProviderStorePath,
+  buildZcodeStoreContribution,
+  zcodeStoreSchemaEstablished,
+  type BuildContribution,
+  type ConfigFormat,
   type ExportClientId,
 } from "../clients/config-export";
 
@@ -58,6 +63,28 @@ 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;
+  /**
+   * The provider store this client reads INSTEAD of `configPath`.
+   *
+   * A client that moves its store between releases usually keeps a one-shot
+   * import from the old location, and that import is exactly what makes the old
+   * write look like it still works: it runs once, on an install that has never
+   * created the new file, and never again. Everything after it lands in a file
+   * the client does not open.
+   *
+   * A declaration carries everything needed to write the store, not only its
+   * location: the text format, the contribution shape its reader understands,
+   * and the predicate that says whether a document on disk is a version whose
+   * shape has been observed. The last one is what keeps this honest — a store
+   * we cannot establish is reported as the reason the write cannot reach the
+   * client, never merged into on a guess.
+   */
+  currentStore?: {
+    path: (env?: NodeJS.ProcessEnv, home?: string) => string;
+    format: ConfigFormat;
+    establishes: (parsed: unknown) => boolean;
+    buildContribution: BuildContribution;
+  };
   /** 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. */
@@ -231,6 +258,17 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     id: "zcode",
     configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
     detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+    /*
+     * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches
+     * `v2/config.json` only through the import that seeded it. Where the new
+     * file exists the import is spent, so our write is read by nobody (#5348).
+     */
+    currentStore: {
+      path: (env = process.env, home = homedir()) => zcodeProviderStorePath(env, home),
+      format: "json",
+      establishes: zcodeStoreSchemaEstablished,
+      buildContribution: buildZcodeStoreContribution,
+    },
   },
   prime: {
     id: "prime",

package/src/integrations/state.ts

@@ -11,10 +11,18 @@
 import { createClineIO } from "./cline-io";
 import { parseClineDocument } from "./cline-document";
 import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel, type ManagedContribution } from "../clients/config-export";
+import type { ConfigFormat } from "../clients/config-export";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { SNAPSHOT_RETENTION } from "./journal";
-import { AmbiguousSelectorError, parseSegment, selectIndex, type PathSegment } from "./merge";
+import {
+  AmbiguousSelectorError,
+  InvalidSelectorError,
+  parseSegment,
+  readPath,
+  selectIndex,
+  type PathSegment,
+} from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
   protectedContributionFingerprint,
@@ -28,6 +36,7 @@ import {
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
+import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
 export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
@@ -50,6 +59,21 @@ export interface IntegrationStatus {
   appliedAt?: string;
   lastOpId?: string;
   reason?: StateReason;
+  /**
+   * The store this client reads instead of `configPath`.
+   *
+   * Present only when the integration is NOT writing that store: either our
+   * block is still in the config file, or the store is not a document whose
+   * shape has been observed. Where the store is written, `configPath` names it
+   * and there is nothing to report beside the state.
+   *
+   * Orthogonal to `state`, which answers "what is on disk, and did we put it
+   * there?" — and answers it correctly here: the block can be byte-for-byte
+   * current in a file the client stopped opening. That pair is not a
+   * contradiction, it is the whole of #5348, so the surface that reports
+   * `current` has to be able to report this beside it.
+   */
+  supersededBy?: string;
   /** Snapshot files retained for this client; -1 when they cannot be inspected. */
   snapshotCount: number;
   /** Pruning is behind, so older (possibly credential-bearing) snapshots remain. */
@@ -64,37 +88,14 @@ function assertNever(segment: never): never {
   throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
 }
 
-/** The element a selector names, or `undefined` when none matches. */
-function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
-  return items[selectIndex(items, segment.field, segment.value)];
-}
-
 /**
- * Same segment grammar as `setPath`: a plain key reads through a record, a
- * `[field=value]` selector reads through an array. Because the classifier and
- * the writer share this one function, status and mutation cannot disagree
- * about which element is ours.
+ * The path reader lives with the path grammar, in `merge`, and is re-exported
+ * here because the classifier was its original home and every caller imports
+ * it from this module. One implementation is the point: a reader that resolved
+ * a selector differently from the writer would report one element as ours and
+ * then rewrite another.
  */
-export function readPath(doc: unknown, path: readonly string[]): unknown {
-  let cursor: unknown = doc;
-  for (const raw of path) {
-    const segment = parseSegment(raw);
-    switch (segment.kind) {
-      case "key":
-        if (!isPlainRecord(cursor)) return undefined;
-        cursor = cursor[segment.key];
-        break;
-      case "select":
-        if (!Array.isArray(cursor)) return undefined;
-        cursor = selectElement(cursor, segment);
-        break;
-      default:
-        return assertNever(segment);
-    }
-    if (cursor === undefined) return undefined;
-  }
-  return cursor;
-}
+export { readPath };
 
 /** Does the document carry any fragment we would write? */
 export function hasOurFragments(doc: unknown, contribution: ManagedContribution): boolean {
@@ -136,7 +137,7 @@ export function blockedContainerPath(
       case "key":
         return (value as Record<string, unknown>)[segment.key];
       case "select":
-        return selectElement(value as readonly unknown[], segment);
+        return (value as readonly unknown[])[selectIndex(value as readonly unknown[], segment.criteria)];
       default:
         return assertNever(segment);
     }
@@ -285,6 +286,14 @@ export function classifyIntegration(input: {
    */
   configPath?: string;
   clientId?: IntegrationClientId;
+  /**
+   * Text format of the file being classified, which is not always the client's
+   * config format: a client that moved its providers keeps a second document
+   * whose format is declared with the store. Only the comment-capability of the
+   * format is read here, and reading the wrong one would decide a sibling edit
+   * the wrong way.
+   */
+  format?: ConfigFormat;
 }): { state: IntegrationState; reason?: StateReason } {
   if (input.fileText !== null && !input.fileIsRegular) {
     return { state: "unsafe", reason: "not-regular-file" };
@@ -310,8 +319,13 @@ export function classifyIntegration(input: {
       }
     }
   } catch (error) {
-    if (!(error instanceof AmbiguousSelectorError)) throw error;
-    return { state: "unsafe", reason: "ambiguous-selector" };
+    if (error instanceof AmbiguousSelectorError) {
+      return { state: "unsafe", reason: "ambiguous-selector" };
+    }
+    if (error instanceof InvalidSelectorError) {
+      return { state: "unsafe", reason: "unparseable" };
+    }
+    throw error;
   }
   if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
 
@@ -393,7 +407,7 @@ export function classifyIntegration(input: {
      * stands and re-owns the file. This also lets disable proceed on a
      * drifted file — removal still touches only the recorded fragment paths.
      */
-    if (EXPORT_CLIENTS[clientId].format !== "json") {
+    if ((input.format ?? EXPORT_CLIENTS[clientId].format) !== "json") {
       return { state: "conflict", reason: "foreign-edit" };
     }
     return { state: "stale" };
@@ -491,7 +505,6 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   retryPendingPrunesOnce(store);
   let io = input.io ?? store.io();
   const spec = INTEGRATION_CLIENTS[input.clientId];
-  const exportSpec = EXPORT_CLIENTS[input.clientId];
   const retention = retentionOf(input.clientId, store);
   /*
    * Resolution can refuse — a relative OPENCLAW_* selector names a file whose
@@ -499,14 +512,25 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
    * every client for its state, so letting that escape would answer 500 for
    * the whole Integrations page because one client is misconfigured.
    */
-  let configPath: string;
   let installed: boolean;
+  let effective: IntegrationTarget;
+  let record: OwnershipRecord | null;
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
     const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home);
-    configPath = paths.configPath;
     installed = io.statKind(paths.detectDir) === "dir";
+    if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
+    /*
+     * The record is one of the inputs the target is chosen from, so it is read
+     * here rather than after the file. The status this function reports is about
+     * whichever file the next mutation would act on; reading a different one
+     * would let the badge and the switch disagree.
+     */
+    record = store.readRecords()[input.clientId] ?? null;
+    effective = resolveIntegrationTarget({
+      clientId: input.clientId, configPath: paths.configPath, io, record, env: input.env, home: input.home,
+    });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     /*
@@ -531,30 +555,32 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     };
   }
 
-  if (input.clientId === "cline") io = createClineIO(io, configPath, store);
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
+  const configPath = effective.configPath;
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) {
     return {
       clientId: input.clientId,
       state: "unsafe",
       installed,
       configPath,
-      reason: target.why === "read-failed" ? "unparseable" : "not-regular-file",
+      reason: loaded.why === "read-failed" ? "unparseable" : "not-regular-file",
       ...retention,
     };
   }
 
-  const parsed = input.clientId === "cline" ? parseClineDocument(target.before) : parseConfig(target.before, exportSpec.format);
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
-  const record = store.readRecords()[input.clientId] ?? null;
+  const parsed = input.clientId === "cline"
+    ? parseClineDocument(loaded.before)
+    : parseConfig(loaded.before, effective.format);
+  const contribution = effective.buildContribution(exportContextOf(input));
   const { state, reason } = classifyIntegration({
-    fileText: target.before,
+    fileText: loaded.before,
     fileIsRegular: true,
     parsed,
     record,
     contribution,
     configPath,
     clientId: input.clientId,
+    format: effective.format,
   });
 
   return {
@@ -563,6 +589,13 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     installed,
     configPath,
     ...(reason ? { reason } : {}),
+    /*
+     * Only when the client reads a DIFFERENT file than the one this status is
+     * about. A store we are writing needs no notice; the path already names it.
+     */
+    ...(effective.ineffective && effective.ineffective.store !== configPath
+      ? { supersededBy: effective.ineffective.store }
+      : {}),
     ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
     ...retention,
   };

package/src/integrations/target.ts

@@ -0,0 +1,208 @@
+/**
+ * Which file an integration operation reads, writes and records — and, when
+ * that is not the file the client reads, which file is.
+ *
+ * A client may move its provider list between releases and keep the old file
+ * reachable only through a one-shot import. Everything the integration checks
+ * still passes against the old file: it is writable, the block merges, the
+ * ownership record describes it correctly. The only thing that changed is
+ * whether anything reads it (#5348).
+ *
+ * So the target is chosen before anything is classified, and it is chosen by
+ * three facts in this order:
+ *
+ * 1. No declared store, or no store on disk — the config file, exactly as
+ *    before. A client that has never run still imports what we write there.
+ * 2. Our own block already sits in the config file this record names. Stay
+ *    there. Disable removes what we wrote from where we wrote it, and the
+ *    caller reports the write as ineffective rather than orphaning a block in
+ *    one file while writing another.
+ * 3. Otherwise the store, but only when its schema can be established. A store
+ *    we cannot parse or whose version we have not observed is reported as the
+ *    reason the write cannot reach the client, because merging an invented
+ *    nesting into a file holding the user's other providers would trade a
+ *    silent no-op for a silent loss.
+ */
+import { EXPORT_CLIENTS, ClientPathError, type BuildContribution, type ConfigFormat } from "../clients/config-export";
+import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { AmbiguousSelectorError, InvalidSelectorError, readPath } from "./merge";
+import type { OwnershipRecord } from "./ownership";
+import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+
+export interface IntegrationTarget {
+  /** The file this operation reads, writes, journals and records ownership for. */
+  readonly configPath: string;
+  /** Text format of that file, which is not always the client's config format. */
+  readonly format: ConfigFormat;
+  /** The contribution shape that file's reader understands. */
+  readonly buildContribution: BuildContribution;
+  /**
+   * Set when a write to the file above would not reach the client.
+   *
+   * `why` is carried rather than re-derived because the cases have different
+   * remedies and only this function knows which one it took. Disable is not
+   * gated on it: removing bytes this project wrote from the file it wrote them
+   * to is as effective as it ever was.
+   */
+  readonly ineffective: IneffectiveWrite | null;
+}
+
+export interface IneffectiveWrite {
+  /** The provider store the client reads. */
+  readonly store: string;
+  /**
+   * `owned-config-file` — this project's block is still in the config file, so
+   * the operation stays there and the remedy is to remove it first, rather than
+   * leave a block in one file while writing another.
+   *
+   * `unestablished-schema` — the store is not a document whose shape has been
+   * observed, so there is nothing safe to merge into it. This one is reachable
+   * with the store itself as the target: a client that bumps its schema after
+   * we wrote the store leaves our block there, removable, and the file no
+   * longer one we may merge into.
+   */
+  readonly why: "owned-config-file" | "unestablished-schema";
+}
+
+function configFileTarget(
+  clientId: IntegrationClientId,
+  configPath: string,
+  ineffective: IneffectiveWrite | null,
+): IntegrationTarget {
+  const exportSpec = EXPORT_CLIENTS[clientId];
+  return {
+    configPath,
+    format: exportSpec.format,
+    buildContribution: exportSpec.buildContribution,
+    ineffective,
+  };
+}
+
+function storeTarget(
+  declared: NonNullable<(typeof INTEGRATION_CLIENTS)[IntegrationClientId]["currentStore"]>,
+  configPath: string,
+  ineffective: IneffectiveWrite | null = null,
+): IntegrationTarget {
+  return {
+    configPath,
+    format: declared.format,
+    buildContribution: declared.buildContribution,
+    ineffective,
+  };
+}
+
+/**
+ * Does the file this record names still hold any fragment it claims?
+ *
+ * Uncertainty answers yes. An unreadable or unparseable config file is a state
+ * the classifier is about to refuse on, and it must refuse on the file our
+ * record is about rather than silently move the operation to a different one.
+ * An ambiguous or invalid selector is the same kind of answer.
+ */
+function recordedBlockStillPresent(
+  io: IntegrationIO,
+  format: ConfigFormat,
+  configPath: string,
+  record: OwnershipRecord,
+): boolean {
+  const loaded = loadTarget(io, configPath);
+  if (!loaded.ok) return true;
+  const parsed = parseConfig(loaded.before, format);
+  if (parsed === PARSE_FAILED) return true;
+  try {
+    return record.fragmentPaths.some(path => readPath(parsed, path) !== undefined);
+  } catch (error) {
+    if (error instanceof AmbiguousSelectorError || error instanceof InvalidSelectorError) return true;
+    throw error;
+  }
+}
+
+/**
+ * Resolve the target for one operation.
+ *
+ * `configPath` is the client's config file as the registry resolves it now, and
+ * `record` is the stored ownership as read, before any path filtering — the
+ * filtering depends on the answer this function returns.
+ *
+ * The store is observed through the caller's own `IntegrationIO`, never the
+ * real filesystem directly, so status and mutation cannot disagree about
+ * whether a write can land.
+ */
+export function resolveIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  io: IntegrationIO;
+  record: OwnershipRecord | null;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget {
+  const { clientId, configPath, io, record } = args;
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return configFileTarget(clientId, configPath, null);
+  const storePath = declared.path(args.env, args.home);
+  const kind = io.statKind(storePath);
+  if (kind === "missing") return configFileTarget(clientId, configPath, null);
+  // Only proven absence permits a legacy write. Unreadable or non-file stores
+  // cannot establish what the client reads; preserve the recorded removal target.
+  if (kind !== "file") {
+    const ineffective: IneffectiveWrite = { store: storePath, why: "unestablished-schema" };
+    return record?.clientId === clientId && record.configPath === storePath
+      ? storeTarget(declared, storePath, ineffective)
+      : configFileTarget(clientId, configPath, ineffective);
+  }
+  const loaded = loadTarget(io, storePath);
+  const parsed = loaded.ok ? parseConfig(loaded.before, declared.format) : PARSE_FAILED;
+  const established = parsed !== PARSE_FAILED && declared.establishes(parsed);
+  const unestablished: IneffectiveWrite = { store: storePath, why: "unestablished-schema" };
+  /*
+   * Our own block decides the target before the store's schema does, whichever
+   * file holds it. Disable has to remove what we wrote from where we wrote it,
+   * and an apply must never leave a block in one file while writing another.
+   */
+  const owned = record !== null && record.clientId === clientId ? record : null;
+  if (owned?.configPath === storePath && recordedBlockStillPresent(io, declared.format, storePath, owned)) {
+    return storeTarget(declared, storePath, established ? null : unestablished);
+  }
+  if (
+    owned?.configPath === configPath
+    && recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)
+  ) {
+    return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
+  }
+  if (!established) {
+    return configFileTarget(clientId, configPath, unestablished);
+  }
+  return storeTarget(declared, storePath);
+}
+
+/**
+ * The target a path NAMES, or null when this client may not write there.
+ *
+ * Undo acts on the file its journal row recorded, so it needs the meaning of a
+ * historical path rather than the choice above: which contribution shape
+ * describes those bytes, and whether this client still resolves that location
+ * at all. Resolving a path the client no longer names is what would let a row
+ * recorded for one home delete a file in another, so an unrecognised path is
+ * null and the caller refuses.
+ */
+export function declaredIntegrationTarget(args: {
+  clientId: IntegrationClientId;
+  configPath: string;
+  resolvedConfigPath: string;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+}): IntegrationTarget | null {
+  const { clientId, configPath, resolvedConfigPath } = args;
+  if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
+  const declared = INTEGRATION_CLIENTS[clientId].currentStore;
+  if (!declared) return null;
+  try {
+    if (declared.path(args.env, args.home) !== configPath) return null;
+  } catch (error) {
+    // A store the operator relocated with a path we cannot resolve proves
+    // nothing about the row, so the row is not a legal target.
+    if (error instanceof ClientPathError) return null;
+    throw error;
+  }
+  return storeTarget(declared, configPath);
+}