@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
272 lines (263 loc) • 13.1 kB
text/typescript
/**
* 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, zcodeLegacyHomeDir, zcodeProviderStorePath, 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, resolveIntegrationPaths, type ResolvedIntegrationPaths, 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;
/**
* The one YAML leaf patched in place in that file, or null when the writer
* re-renders the document. A client's config file and its store have
* different shapes, so this belongs to the target rather than the client.
*/
readonly sourcePreservingYaml: { readonly path: readonly string[] } | null;
/**
* 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;
/** Active root unknown; the named config is only a historical removal target. */
readonly pathError?: string;
}
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.
*
* `missing-store` — the store does not exist, but the client already manages it
* (DSH: a Desktop profile manifest is present). DSH renames `settings.yaml` to
* `settings.yaml.imported` and imports it on startup, so a config-file write would
* orphan our ownership record. `remedy` says how to bring the store back, and
* `emptyDocument` is what to create it with.
*/
readonly why: IneffectiveWriteReason;
readonly remedy?: string;
readonly emptyDocument?: string;
}
export type IneffectiveWriteReason = "owned-config-file" | "unestablished-schema" | "missing-store";
function configFileTarget(
clientId: IntegrationClientId,
configPath: string,
ineffective: IneffectiveWrite | null,
): IntegrationTarget {
const exportSpec = EXPORT_CLIENTS[clientId];
return {
configPath,
format: exportSpec.format,
buildContribution: exportSpec.buildContribution,
sourcePreservingYaml: INTEGRATION_CLIENTS[clientId].sourcePreservingYaml ?? null,
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,
sourcePreservingYaml: declared.sourcePreservingYaml ?? null,
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;
resolvedPaths?: ResolvedIntegrationPaths;
}): IntegrationTarget {
const { clientId, configPath, io, record } = args;
const declared = INTEGRATION_CLIENTS[clientId].currentStore;
if (!declared) return configFileTarget(clientId, configPath, null);
const paths = clientId === "zcode"
? args.resolvedPaths ?? resolveIntegrationPaths(clientId, args.env, args.home, undefined, io)
: undefined;
const storePath = paths?.storePath ?? declared.path(args.env, args.home, io);
const kind = io.statKind(storePath);
const owned = record !== null && record.clientId === clientId ? record : null;
const historicalStore = clientId === "zcode"
? zcodeProviderStorePath({ ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, io)
: null;
if (clientId === "zcode" && owned && owned.configPath !== configPath && owned.configPath !== storePath
&& owned.configPath !== historicalStore
&& INTEGRATION_CLIENTS[clientId].bindsDriftedRecord?.(owned.configPath, args.env, args.home) !== true
&& io.statKind(owned.configPath) !== "missing") {
throw new ClientPathError(`ZCode ownership remains at ${owned.configPath}. Its location cannot be bound to the current home or selectors; restore the original selectors and disable it before enabling a different data root. Ownership and recovery evidence are retained.`);
}
// An explicit provider-file selector can establish the active target even
// when the bootstrap is unreadable, but absence cannot justify a legacy write.
if (paths?.pathError && (!(args.env ?? process.env).ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim() || kind !== "file")) {
const removal = owned?.configPath === historicalStore
? storeTarget(declared, historicalStore)
: configFileTarget(clientId, configPath, null);
return { ...removal, pathError: paths.pathError };
}
if (historicalStore && owned?.configPath === historicalStore && historicalStore !== storePath
&& recordedBlockStillPresent(io, declared.format, historicalStore, owned)) {
return storeTarget(declared, historicalStore, { store: storePath, why: "owned-config-file" });
}
// Relocation must not orphan a block at the default historical path, even
// when the relocated store has not been created yet.
if (clientId === "zcode" && owned?.configPath === configPath && configPath !== paths?.configPath
&& recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)) {
return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
}
if (kind === "missing") {
const missing = declared.missingStore;
return missing?.readsStore(storePath, path => io.statKind(path)) === true
? configFileTarget(clientId, configPath, { store: storePath, why: "missing-store", remedy: missing.remedy, emptyDocument: missing.emptyDocument })
: 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.
*/
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;
io?: Pick<IntegrationIO, "readText">;
}): IntegrationTarget | null {
const { clientId, configPath, resolvedConfigPath } = args;
if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
if (INTEGRATION_CLIENTS[clientId].bindsDriftedRecord?.(configPath, args.env, args.home) === true) {
return configFileTarget(clientId, configPath, null);
}
const declared = INTEGRATION_CLIENTS[clientId].currentStore;
if (!declared) return null;
if (clientId === "zcode" && configPath === zcodeProviderStorePath(
{ ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, args.io,
)) return storeTarget(declared, configPath);
try {
if (declared.path(args.env, args.home, args.io) !== 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);
}