@iislee/opencodex 2.11.0 → 2.35.0

package/src/integrations/merge.ts

@@ -0,0 +1,135 @@
+/**
+ * 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";
+
+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);
+}
+
+/** Write `value` at `path`, creating intermediate objects. Returns a new document. */
+export function setPath(doc: unknown, path: readonly string[], value: unknown): unknown {
+  if (path.length === 0) throw new Error("setPath needs a non-empty path");
+  const root: Record<string, unknown> = isPlainRecord(doc) ? clone(doc) : {};
+  let cursor = root;
+  for (const key of path.slice(0, -1)) {
+    const next = cursor[key];
+    if (!isPlainRecord(next)) cursor[key] = {};
+    cursor = cursor[key] as Record<string, unknown>;
+  }
+  cursor[path[path.length - 1]!] = clone(value);
+  return 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>;
+  const chain: Record<string, unknown>[] = [root];
+  let cursor: Record<string, unknown> = root;
+  for (const key of path.slice(0, -1)) {
+    const next = cursor[key];
+    if (!isPlainRecord(next)) return { doc: root, removed: false };
+    cursor = next;
+    chain.push(cursor);
+  }
+  const leaf = path[path.length - 1]!;
+  if (!(leaf in cursor)) return { doc: root, removed: false };
+  delete cursor[leaf];
+  /*
+   * Walk back up, pruning only containers this deletion emptied AND that we
+   * created. The root is never pruned.
+   */
+  for (let index = chain.length - 1; index >= 1; index -= 1) {
+    const container = chain[index]!;
+    if (Object.keys(container).length > 0) break;
+    const containerPath = path.slice(0, index).join("\u0000");
+    if (!createdContainers.has(containerPath)) break;
+    delete chain[index - 1]![path[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 key = fragment.path[depth]!;
+      const next = isPlainRecord(cursor) ? cursor[key] : undefined;
+      if (!isPlainRecord(next)) {
+        created.add(fragment.path.slice(0, depth + 1).join("\u0000"));
+        cursor = undefined;
+        continue;
+      }
+      cursor = next;
+    }
+  }
+  return [...created];
+}

package/src/integrations/mutation-flight.ts

@@ -0,0 +1,71 @@
+import type { IntegrationClientId } from "./registry";
+
+const INTEGRATION_MUTATION_JOIN_MS = 120_000;
+export const INTEGRATION_MUTATION_TERMINAL_MS = 10 * 60_000;
+
+interface IntegrationMutationFlight {
+  key: string;
+  startedAt: number;
+  promise: Promise<unknown>;
+}
+
+export class IntegrationMutationBusyError extends Error {
+  constructor(readonly clientId: IntegrationClientId) {
+    super("integration_mutation_busy");
+  }
+}
+
+const integrationMutationFlights = new Map<IntegrationClientId, IntegrationMutationFlight>();
+let integrationMutationRunTestHook: ((operation: () => Promise<unknown>) => Promise<unknown>) | null = null;
+
+/**
+ * One in-process flight per client, shared by explicit HTTP mutations and
+ * implicit catalog refreshes. Equal operations join; different semantics are
+ * busy instead of, for example, letting an explicit apply join a refresh-only
+ * no-op for an absent block.
+ */
+export function runIntegrationMutationFlight<T>(
+  clientId: IntegrationClientId,
+  key: string,
+  now: () => number,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const startedAt = now();
+  const current = integrationMutationFlights.get(clientId);
+  if (current) {
+    const age = startedAt - current.startedAt;
+    if (current.key === key && age < INTEGRATION_MUTATION_JOIN_MS) {
+      return current.promise as Promise<T>;
+    }
+    if (age <= INTEGRATION_MUTATION_TERMINAL_MS) {
+      return Promise.reject(new IntegrationMutationBusyError(clientId));
+    }
+    if (integrationMutationFlights.get(clientId) === current) {
+      integrationMutationFlights.delete(clientId);
+    }
+  }
+
+  const flight: IntegrationMutationFlight = {
+    key,
+    startedAt,
+    promise: Promise.resolve(),
+  };
+  const run = async (): Promise<unknown> => operation();
+  flight.promise = (integrationMutationRunTestHook
+    ? integrationMutationRunTestHook(run)
+    : run()
+  ).finally(() => {
+    if (integrationMutationFlights.get(clientId) === flight) {
+      integrationMutationFlights.delete(clientId);
+    }
+  });
+  integrationMutationFlights.set(clientId, flight);
+  return flight.promise as Promise<T>;
+}
+
+export function setIntegrationMutationFlightTestHook(
+  run: ((operation: () => Promise<unknown>) => Promise<unknown>) | null,
+): void {
+  integrationMutationRunTestHook = run;
+  integrationMutationFlights.clear();
+}

package/src/integrations/native/ownership-preflight.ts

@@ -0,0 +1,202 @@
+/**
+ * The service-home preflight for native-client teardown (WP2, audit r1 #5;
+ * devlog 260803_integrations_toggle_all/012).
+ *
+ * `ocx stop` has honored `ServiceOwnershipError` since it started catching it
+ * (src/cli/index.ts:464); nothing on the HTTP side ever did. A route that calls
+ * `stripGrokConfig` directly would otherwise pull the fence out from under a
+ * service running from another CODEX_HOME/OPENCODEX_HOME — the installed
+ * service is still live and the shared state belongs to it.
+ *
+ * ENABLE is not gated by this: writing our own fence is not a shared teardown,
+ * and `injectGrokConfig` already runs unguarded from `ocx start`/`ensure`.
+ */
+import {
+  assertServiceEnvironmentMatchesInstall,
+  isServiceOwnershipError,
+} from "../../service";
+import {
+  currentServiceHomes,
+  inspectServiceStateEvidence,
+  serviceHomeMatches,
+  type ServiceStateEvidence,
+} from "../../service";
+import {
+  inspectServiceManagerInstallation,
+  type ProbeDeps,
+  type ServiceManagerClaim,
+} from "../../service-manager-probe";
+
+export type NativeTeardownOwnership = { ok: true } | { ok: false; message: string };
+
+export function assertNativeTeardownOwned(): NativeTeardownOwnership {
+  try {
+    assertServiceEnvironmentMatchesInstall();
+    return { ok: true };
+  } catch (error) {
+    if (isServiceOwnershipError(error)) {
+      // The message names both the recorded and the current home — that is the
+      // refusal text, verbatim, because the user has to act on it.
+      return { ok: false, message: error.message };
+    }
+    // Unrelated failure (corrupt state file, IO): mirror
+    // `serviceEnvironmentOwnedHere` and fail open rather than wedging the route
+    // behind a check whose own input is broken.
+    return { ok: true };
+  }
+}
+
+/**
+ * Tri-state ownership for UNATTENDED writes.
+ *
+ * Deliberately not `assertNativeTeardownOwned`. That one fails OPEN — a corrupt
+ * state file yields `{ok:true}` — which is right for a teardown route a human
+ * just invoked, and catastrophic as an authority for automatic convergence:
+ * "could not read" would become "belongs to me".
+ *
+ * `owned` here means NO PERSISTENT SERVICE CLAIM WAS OBSERVED. It does not mean
+ * this process is the only writer. Two foreground `ocx start` processes on one
+ * home both read `owned`, and correctly so, because neither installs a service —
+ * keeping them apart is the write lock's job, not this function's.
+ */
+export type NativeCodexOwnership = "owned" | "foreign" | "unknown";
+
+export interface OwnershipInspection {
+  readonly ownership: NativeCodexOwnership;
+  /** Why, in the words a refusal message can use. */
+  readonly reason: string;
+}
+
+function claimNamesDifferentHome(
+  claim: ServiceManagerClaim,
+  current: { codexHome: string; opencodexHome: string },
+): boolean {
+  // A definition that OMITS a home is not a definition that disagrees about it:
+  // an install run without CODEX_HOME set writes no such key at all.
+  if (claim.homes.codexHome !== null && !serviceHomeMatches(claim.homes.codexHome, current.codexHome)) return true;
+  if (claim.homes.opencodexHome !== null && !serviceHomeMatches(claim.homes.opencodexHome, current.opencodexHome)) return true;
+  return false;
+}
+
+/**
+ * Map a service-manager claim backend to the `ServiceInstallState.backend`
+ * value it corresponds to. `scheduler` (Task Scheduler) and `winsw` (native)
+ * are the two Windows manager backends; launchd/systemd claims have no Windows
+ * backend and can never mismatch a v2 state file.
+ */
+function claimBackendToStateBackend(backend: ServiceManagerClaim["backend"]): "scheduler" | "native" | null {
+  if (backend === "scheduler") return "scheduler";
+  if (backend === "winsw") return "native";
+  return null;
+}
+
+/** True when the recorded state backend disagrees with the manager claim. Legacy v1 means scheduler. */
+function claimBackendMismatchesState(claim: ServiceManagerClaim, state: { backend?: "scheduler" | "native" }): boolean {
+  const expected = claimBackendToStateBackend(claim.backend);
+  if (expected === null) return false;
+  return (state.backend ?? "scheduler") !== expected;
+}
+
+export interface OwnershipDeps extends ProbeDeps {
+  /**
+   * Which state paths to consult. Injectable because the default set includes
+   * the DEFAULT home mirror, resolved from `homedir()` — which no test sandbox
+   * moves. Without this a fixture reads the developer's real installation and
+   * calls their own machine foreign.
+   */
+  readonly statePaths?: readonly string[];
+  readonly currentHomes?: { codexHome: string; opencodexHome: string };
+}
+
+export function inspectNativeCodexOwnership(deps: OwnershipDeps = {}): OwnershipInspection {
+  const current = deps.currentHomes ?? currentServiceHomes();
+  const evidence = deps.statePaths
+    ? inspectServiceStateEvidence(deps.statePaths)
+    : inspectServiceStateEvidence();
+
+  const unreadable = evidence.find((e): e is Extract<ServiceStateEvidence, { kind: "unreadable" }> => e.kind === "unreadable");
+  if (unreadable) {
+    return { ownership: "unknown", reason: `service state at ${unreadable.path} could not be read (${unreadable.reason})` };
+  }
+  const invalid = evidence.find(e => e.kind === "invalid");
+  if (invalid) {
+    return { ownership: "unknown", reason: `service state at ${invalid.path} is malformed` };
+  }
+
+  const valid = evidence.filter((e): e is Extract<ServiceStateEvidence, { kind: "valid" }> => e.kind === "valid");
+  // Mirrors that disagree with each other are not a majority vote.
+  for (const one of valid) {
+    for (const other of valid) {
+      if (!serviceHomeMatches(one.state.codexHome, other.state.codexHome)
+        || !serviceHomeMatches(one.state.opencodexHome, other.state.opencodexHome)) {
+        return { ownership: "unknown", reason: "two service state files disagree about which homes are installed" };
+      }
+    }
+  }
+
+  const foreign = valid.find(e =>
+    !serviceHomeMatches(e.state.codexHome, current.codexHome)
+    || !serviceHomeMatches(e.state.opencodexHome, current.opencodexHome));
+  if (foreign) {
+    return {
+      ownership: "foreign",
+      reason: `a service is installed for CODEX_HOME=${foreign.state.codexHome} / OPENCODEX_HOME=${foreign.state.opencodexHome}`,
+    };
+  }
+
+  // The manager assets live under the effective OPENCODEX_HOME. Production
+  // callers do not inject ProbeDeps.configDir, so derive it from the same
+  // current-home snapshot used for ownership comparison rather than silently
+  // falling back to <homedir>/.opencodex.
+  const manager = inspectServiceManagerInstallation({
+    ...deps,
+    configDir: deps.configDir ?? current.opencodexHome,
+  });
+  if (manager.kind === "unknown") {
+    return { ownership: "unknown", reason: manager.reason };
+  }
+  if (manager.kind === "conflict") {
+    return { ownership: "unknown", reason: "more than one service manager holds a registration for this proxy" };
+  }
+  if (manager.kind === "present") {
+    const disagreeing = manager.claims.find(claim => claimNamesDifferentHome(claim, current));
+    if (disagreeing) {
+      /*
+       * The state file says this home and the definition says another. An
+       * interrupted reinstall looks exactly like this — installation writes the
+       * definition BEFORE the state file — and picking a winner unattended would
+       * be guessing which half of a half-finished operation to believe.
+       */
+      return {
+        ownership: "unknown",
+        reason: `${disagreeing.backend} is installed from ${disagreeing.definitionPath}, which names different homes than the recorded service state`,
+      };
+    }
+    // A manager backend that disagrees with the recorded state (e.g. state says
+    // native/WinSW but a scheduler task is found) is an interrupted backend
+    // switch: it does not prove which manager owns the installation. v1 state
+    // predates the field and is scheduler by contract.
+    const stateBackendMismatch = valid.find(state => manager.claims.some(claim => claimBackendMismatchesState(claim, state.state)));
+    if (stateBackendMismatch) {
+      return {
+        ownership: "unknown",
+        reason: `the service state records backend ${stateBackendMismatch.state.backend ?? "scheduler"} but ${manager.claims[0]?.backend ?? "a service manager"} is installed`,
+      };
+    }
+    // Definition agrees. Valid state agreeing with it is ownership; no state at
+    // all beside an installed definition is not, because the definition is the
+    // claim and nothing here recorded making it.
+    if (valid.length === 0) {
+      return {
+        ownership: "unknown",
+        reason: `${manager.claims[0]?.backend ?? "a service manager"} holds a registration that no service state file accounts for`,
+      };
+    }
+    return { ownership: "owned", reason: "the installed service names these homes" };
+  }
+
+  // manager.kind === "absent"
+  return valid.length === 0
+    ? { ownership: "owned", reason: "no service state and no service manager claim" }
+    : { ownership: "owned", reason: "the recorded service state names these homes" };
+}