UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

376 lines (355 loc) • 15.2 kB
/** * Additive merge and surgical removal of the fragments opencodex owns. * * The rule that shapes this file: we insert exactly the paths our builder * named, and we delete exactly the paths a record says we wrote. Nothing here * ever scans for a prefix — a user's own `opencodex/...` entry is not ours to * remove, and inferring ownership from a name is how a config editor destroys * work it did not create. * * Design of record: devlog/_fin/260802_client_toggle_api/031_wp3_writer_impl.md. */ import type { ManagedContribution } from "../clients/config-export/contracts"; function isPlainRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); } /** Structured clone via JSON: our documents are plain data by construction. */ function clone<T>(value: T): T { return value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T); } /** * `[field=value]` addresses the ONE element of a sequence whose `field` equals * `value`, and `[v2:field=value,field=value]` the one whose every named field * matches. Raycast keeps its providers as a YAML list, so the element is the * smallest thing we can own there; an index would move under us the moment * the user reordered their own entries. Any other segment is a plain key. * * A conjunction exists because one field is not always the identity. ZCode * keys a model rule in its provider store by the PAIR `(providerId, modelId)`, * so a `[modelId=…]` selector alone would match another provider's rule for the * same model and then replace it, in a file holding every provider the user * has. Addressing an element by less than what identifies it is the same * defect as addressing it by index. * * The single-criterion spelling keeps its original grammar, where the value may * itself contain commas and equals signs. A conjunction uses an explicit v2 * marker, so no path already written into an ownership record on disk changes * meaning. Once the marker is present the whole segment must be valid; falling * back to a key or v1 selector would recreate the silent reselection hazard. */ const ARRAY_SELECTOR = /^\[([A-Za-z_][A-Za-z0-9_]*)=([^\]]+)\]$/u; const SELECTOR_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/u; const SELECTOR_CONJUNCTION_PREFIX = "[v2:"; /** One `field=value` equality a selector requires of the element it names. */ export interface SelectorCriterion { field: string; value: string; } export type PathSegment = | { kind: "key"; key: string } | { kind: "select"; criteria: readonly SelectorCriterion[] }; /** A reserved v2 selector marker was present, but its complete grammar was not. */ export class InvalidSelectorError extends Error { constructor() { super("invalid versioned selector"); this.name = "InvalidSelectorError"; } } function validConjunctionCriteria(criteria: readonly SelectorCriterion[]): boolean { return criteria.length >= 2 && criteria.every(criterion => ( SELECTOR_FIELD.test(criterion.field) && criterion.value.length > 0 && !criterion.value.includes(",") && !criterion.value.includes("]") )); } /** Spell a multi-field selector without colliding with persisted v1 paths. */ export function formatSelectorConjunction(criteria: readonly SelectorCriterion[]): string | null { if (!validConjunctionCriteria(criteria)) return null; return `${SELECTOR_CONJUNCTION_PREFIX}${criteria .map(criterion => `${criterion.field}=${criterion.value}`) .join(",")}]`; } export function parseSegment(raw: string): PathSegment { if (raw.startsWith(SELECTOR_CONJUNCTION_PREFIX)) { if (!raw.endsWith("]")) throw new InvalidSelectorError(); const parts = raw.slice(SELECTOR_CONJUNCTION_PREFIX.length, -1).split(","); const criteria = parts.map(part => { const equals = part.indexOf("="); return equals < 0 ? { field: "", value: "" } : { field: part.slice(0, equals), value: part.slice(equals + 1) }; }); if (!validConjunctionCriteria(criteria)) throw new InvalidSelectorError(); return { kind: "select", criteria, }; } const match = ARRAY_SELECTOR.exec(raw); if (!match) return { kind: "key", key: raw }; return { kind: "select", criteria: [{ field: match[1]!, value: match[2]! }] }; } /** The `field=value` list a selector segment spells, for messages and seeding. */ export function selectorPairs(criteria: readonly SelectorCriterion[]): string { return criteria.map(criterion => `${criterion.field}=${criterion.value}`).join(", "); } /** * Thrown when a selector matches more than one element. Picking either one * would silently rewrite an entry the user may have written; the writer maps * this to an `unsafe` refusal instead. */ export class AmbiguousSelectorError extends Error { constructor(criteria: readonly SelectorCriterion[]) { super(`more than one entry has ${selectorPairs(criteria)}`); this.name = "AmbiguousSelectorError"; } } /** The index of the element a selector names, -1 when none matches. */ export function selectIndex(items: readonly unknown[], criteria: readonly SelectorCriterion[]): number { const matches: number[] = []; items.forEach((item, index) => { if (isPlainRecord(item) && criteria.every(criterion => item[criterion.field] === criterion.value)) { matches.push(index); } }); if (matches.length > 1) throw new AmbiguousSelectorError(criteria); return matches[0] ?? -1; } 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.criteria)]; } /** * Read `path` through the same segment grammar `setPath` writes through. * * It belongs here rather than beside the classifier because the grammar does: a * reader that resolved a selector differently from the writer would report one * element as ours and then rewrite another. `state` re-exports it for the * callers that have always imported it from there. */ export function readPath(doc: unknown, path: readonly string[]): unknown { let cursor: unknown = doc; // Validate the complete persisted grammar before document shape can short-circuit // the walk. Otherwise an absent early key can hide a malformed later selector, // making an unreadable ownership record look absent and move the operation to a // different file. const segments = path.map(parseSegment); for (const segment of segments) { 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; } /** * Write `value` at `path`, creating intermediate containers. Returns a new document. * * A `key` segment descends through a record, creating `{}` where the slot is * absent or holds something else. A `select` segment descends through an * array the same way, creating `[]`; a missing element is pushed, a matching * one is replaced in place so the user's ordering survives. */ export function setPath(doc: unknown, path: readonly string[], value: unknown): unknown { if (path.length === 0) throw new Error("setPath needs a non-empty path"); /* * `parent[slot]` is the position the segment just consumed addresses. The * root sits in a one-key holder so the first segment needs no special case: * a non-record document is replaced by `{}` exactly as before. */ const holder: Record<string, unknown> = { root: isPlainRecord(doc) ? clone(doc) : {} }; let parent: Record<string, unknown> | unknown[] = holder; let slot: string | number = "root"; const read = (): unknown => (Array.isArray(parent) ? parent[slot as number] : parent[slot as string]); const write = (next: unknown): void => { if (Array.isArray(parent)) parent[slot as number] = next; else parent[slot as string] = next; }; for (const raw of path) { const segment = parseSegment(raw); switch (segment.kind) { case "key": { if (!isPlainRecord(read())) write({}); parent = read() as Record<string, unknown>; slot = segment.key; break; } case "select": { if (!Array.isArray(read())) write([]); const items = read() as unknown[]; const found = selectIndex(items, segment.criteria); parent = items; if (found >= 0) { slot = found; } else { // Seed the element so the selector stays true for whatever a deeper // segment writes into it; a last-position select replaces it whole. slot = items.length; items.push(Object.fromEntries(segment.criteria.map(criterion => [criterion.field, criterion.value]))); } break; } default: return assertNever(segment); } } write(clone(value)); return holder.root; } /** * Delete `path`, optionally pruning containers that WE created. * * Two properties have to hold at once, and they pull in opposite directions. * A user who wrote `providers: {}` before we existed still has it after a * disable — pruning it because our entry left it empty would delete their * line. But a container we conjured ourselves (Kimi's `models` map exists only * because our aliases need somewhere to live) must not survive as empty * residue in a file the user never asked us to restructure. * * `createdContainers` is the difference: paths recorded at apply time as * absent beforehand. Anything not in that set is treated as the user's. */ export function deletePath( doc: unknown, path: readonly string[], createdContainers: ReadonlySet<string> = new Set(), ): { doc: unknown; removed: boolean } { if (!isPlainRecord(doc) || path.length === 0) return { doc, removed: false }; const root = clone(doc) as Record<string, unknown>; // `chain[i]` is the container segment `i` is resolved against; `slots[i]` is // the key or index it resolved to, so the prune walk can delete by position. const chain: (Record<string, unknown> | unknown[])[] = [root]; const slots: (string | number)[] = []; for (let depth = 0; depth < path.length; depth += 1) { const container = chain[depth]!; const segment = parseSegment(path[depth]!); switch (segment.kind) { case "key": { if (Array.isArray(container) || !(segment.key in container)) return { doc: root, removed: false }; slots.push(segment.key); chain.push(container[segment.key] as Record<string, unknown> | unknown[]); break; } case "select": { if (!Array.isArray(container)) return { doc: root, removed: false }; const found = selectIndex(container, segment.criteria); if (found < 0) return { doc: root, removed: false }; slots.push(found); chain.push(container[found] as Record<string, unknown> | unknown[]); break; } default: return assertNever(segment); } // Only the leaf may be a scalar; walking into one means the path is absent. if (depth < path.length - 1) { const next = chain[depth + 1]; if (!isPlainRecord(next) && !Array.isArray(next)) return { doc: root, removed: false }; } } const remove = (container: Record<string, unknown> | unknown[], slot: string | number): void => { if (Array.isArray(container)) container.splice(slot as number, 1); else delete container[slot as string]; }; remove(chain[path.length - 1]!, slots[path.length - 1]!); /* * Walk back up, pruning only containers this deletion emptied AND that we * created. The root is never pruned. */ for (let index = path.length - 1; index >= 1; index -= 1) { const container = chain[index]!; const empty = Array.isArray(container) ? container.length === 0 : Object.keys(container).length === 0; if (!empty) break; const containerPath = path.slice(0, index).join("\u0000"); if (!createdContainers.has(containerPath)) break; remove(chain[index - 1]!, slots[index - 1]!); } return { doc: root, removed: true }; } /** Insert every fragment. Everything else in the document is preserved. */ export function mergeContribution(doc: unknown, contribution: ManagedContribution): unknown { let next = doc; for (const fragment of contribution.fragments) next = setPath(next, fragment.path, fragment.value); return next; } /** * Remove exactly the RECORDED paths — never a prefix scan. An entry that * matches our naming but has no recorded path is not ours: it reads as * `conflict` and survives untouched. */ export function removeFragments( doc: unknown, paths: readonly (readonly string[])[], createdContainers: ReadonlySet<string> = new Set(), ): { doc: unknown; removed: boolean } { let next = doc; let removed = false; for (const path of paths) { const result = deletePath(next, path, createdContainers); next = result.doc; removed = removed || result.removed; } return { doc: next, removed }; } /** * Container paths a contribution would have to CREATE in `doc`. * * Computed before the merge, because afterwards every container exists and the * question is unanswerable. Recorded on the ownership record so a later * disable can tell its own scaffolding from the user's structure. */ export function createdContainerPaths( doc: unknown, contribution: ManagedContribution, ): string[] { const created = new Set<string>(); for (const fragment of contribution.fragments) { let cursor: unknown = doc; for (let depth = 0; depth < fragment.path.length - 1; depth += 1) { const segment = parseSegment(fragment.path[depth]!); let next: unknown; switch (segment.kind) { case "key": { /* * The container this key must hold is whatever the NEXT segment * descends into: an array when that is a selector, a record * otherwise. Either one is ours to create when absent. */ const nextSegment = parseSegment(fragment.path[depth + 1]!); next = isPlainRecord(cursor) ? cursor[segment.key] : undefined; if (nextSegment.kind === "select" ? !Array.isArray(next) : !isPlainRecord(next)) next = undefined; break; } case "select": { // A selector that matches nothing means setPath will push the element. next = Array.isArray(cursor) ? cursor[selectIndex(cursor, segment.criteria)] : undefined; break; } default: return assertNever(segment); } if (next === undefined) { created.add(fragment.path.slice(0, depth + 1).join("\u0000")); cursor = undefined; continue; } cursor = next; } } return [...created]; }