Support persisted OpenAPI spec overrides

Author: RhysSullivan

.changeset/persist-openapi-spec-overrides.md

@@ -0,0 +1,5 @@
+---
+"@executor-js/plugin-openapi": patch
+---
+
+Apply persisted RFC 6902 overrides to OpenAPI specifications during preview, import, and refresh so upstream documents can be corrected without maintaining a fork.

packages/plugins/openapi/src/api/group.ts

@@ -9,8 +9,14 @@ import {
   IntegrationSlug,
 } from "@executor-js/sdk/shared";
 
-import { OpenApiParseError, OpenApiExtractionError, OpenApiOAuthError } from "../sdk/errors";
+import {
+  OpenApiParseError,
+  OpenApiExtractionError,
+  OpenApiOAuthError,
+  OpenApiSpecOverrideError,
+} from "../sdk/errors";
 import { SpecPreviewSummary } from "../sdk/preview";
+import { SpecOverridesSchema } from "../sdk/spec-overrides";
 
 // ---------------------------------------------------------------------------
 // Errors — the plugin-domain tagged errors flow directly to clients
@@ -25,6 +31,7 @@ const DomainErrors = [
   OpenApiParseError,
   OpenApiExtractionError,
   OpenApiOAuthError,
+  OpenApiSpecOverrideError,
   IntegrationAlreadyExistsError,
 ] as const;
 
@@ -35,6 +42,7 @@ const UpdateSpecErrors = [
   OpenApiParseError,
   OpenApiExtractionError,
   OpenApiOAuthError,
+  OpenApiSpecOverrideError,
   IntegrationNotFound,
 ] as const;
 
@@ -79,11 +87,13 @@ const AddSpecPayload = Schema.Struct({
   family: Schema.optional(Schema.String),
   healthCheck: Schema.optional(HealthCheckSpec),
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationPayload)),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 const PreviewSpecPayload = Schema.Struct({
   spec: Schema.String,
   specFormat: Schema.optional(Schema.String),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 // The `configure` payload — the new/updated auth methods to merge onto the
@@ -109,6 +119,7 @@ const AddSpecResponse = Schema.Struct({
 // "re-fetch from the stored source URL".
 const UpdateSpecPayload = Schema.Struct({
   spec: Schema.optional(OpenApiSpecInputPayload),
+  specOverrides: Schema.optional(SpecOverridesSchema),
 });
 
 const UpdateSpecResponse = Schema.Struct({
@@ -138,6 +149,7 @@ const OpenApiConfigView = Schema.Struct({
   baseUrl: Schema.optional(Schema.String),
   headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
   queryParams: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  specOverrides: Schema.optional(SpecOverridesSchema),
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationResponse)),
 });
 

packages/plugins/openapi/src/api/handlers.ts

@@ -47,6 +47,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
           const preview = yield* ext.previewSpec({
             spec: payload.spec,
             specFormat: payload.specFormat,
+            specOverrides: payload.specOverrides,
           });
           return specPreviewSummary(preview);
         }),
@@ -68,6 +69,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
             family: payload.family,
             healthCheck: payload.healthCheck,
             authenticationTemplate: payload.authenticationTemplate,
+            specOverrides: payload.specOverrides,
           });
         }),
       ),
@@ -100,6 +102,7 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
                 baseUrl: config.baseUrl,
                 headers: config.headers ? { ...config.headers } : undefined,
                 queryParams: config.queryParams ? { ...config.queryParams } : undefined,
+                specOverrides: config.specOverrides ? [...config.specOverrides] : undefined,
                 authenticationTemplate: config.authenticationTemplate
                   ? [...config.authenticationTemplate]
                   : undefined,
@@ -127,6 +130,9 @@ export const OpenApiHandlers = HttpApiBuilder.group(ExecutorApiWithOpenApi, "ope
           const ext = yield* OpenApiExtensionService;
           const result = yield* ext.updateSpec(params.slug, {
             ...(payload.spec !== undefined ? { spec: payload.spec } : {}),
+            ...(payload.specOverrides !== undefined
+              ? { specOverrides: payload.specOverrides }
+              : {}),
           });
           return {
             slug: result.slug,

packages/plugins/openapi/src/promise.ts

@@ -6,6 +6,7 @@ export type {
   OpenApiSpecInput,
   OpenApiPreviewInput,
 } from "./sdk/plugin";
+export type { JsonPatchOperation, SpecOverrides } from "./sdk/spec-overrides";
 
 // Auth-template authoring helpers. Author apikey methods as canonical
 // placements, or request-shaped: `headers: { Authorization: ["Bearer ",

packages/plugins/openapi/src/react/AddOpenApiIntegration.tsx

@@ -49,6 +49,8 @@ import type { SpecPreviewSummary } from "../sdk/preview";
 import { type Authentication } from "../sdk/types";
 import { resolveServerUrl } from "../sdk/openapi-utils";
 import { detectedAuthenticationTemplates } from "../sdk/derive-auth";
+import { parseSpecOverridesText } from "../sdk/spec-overrides";
+import { SpecOverridesEditor } from "./SpecOverridesEditor";
 
 const normalizePresetUrl = (url: string): string => {
   const trimmed = url.trim();
@@ -154,6 +156,7 @@ export default function AddOpenApiIntegration(props: {
   const openApiPresets = openApiPlugin?.presets;
   const initialPreset = openApiPresets?.find((preset) => preset.id === props.initialPreset) ?? null;
   const [specUrl, setSpecUrl] = useState(props.initialUrl ?? "");
+  const [specOverridesText, setSpecOverridesText] = useState("");
   const [analyzing, setAnalyzing] = useState(false);
   const [analyzeError, setAnalyzeError] = useState<string | null>(null);
 
@@ -233,6 +236,10 @@ export default function AddOpenApiIntegration(props: {
       : resolvedIntegrationId);
   const resolvedDescription =
     descriptionDraft ?? (preview ? Option.getOrElse(preview.description, () => "") : "");
+  const parsedSpecOverrides = useMemo(
+    () => parseSpecOverridesText(specOverridesText),
+    [specOverridesText],
+  );
 
   // Register EVERY spec-detected auth method, not just a single selected one.
   // Keyed off `preview` (stable per analysis) so the memo doesn't re-run on the
@@ -333,6 +340,7 @@ export default function AddOpenApiIntegration(props: {
   // args filled (an empty draft, `hcOperation === ""`, imposes no constraint).
   const canAdd =
     preview !== null &&
+    parsedSpecOverrides.ok &&
     !slugAlreadyExists &&
     (!previewHasNoServers || resolvedBaseUrl.length > 0) &&
     !(hcOperation.length > 0 && hcMissingRequired);
@@ -343,8 +351,19 @@ export default function AddOpenApiIntegration(props: {
     setAnalyzing(true);
     setAnalyzeError(null);
     setAddError(null);
+    if (!parsedSpecOverrides.ok) {
+      setAnalyzeError(parsedSpecOverrides.message);
+      setAnalyzing(false);
+      return;
+    }
     const exit = await doPreview({
-      payload: { spec: specUrl, specFormat: initialPreset?.specFormat },
+      payload: {
+        spec: specUrl,
+        specFormat: initialPreset?.specFormat,
+        ...(parsedSpecOverrides.value.length > 0
+          ? { specOverrides: parsedSpecOverrides.value }
+          : {}),
+      },
     });
     if (Exit.isFailure(exit)) {
       setAnalyzeError(errorMessageFromExit(exit, "Failed to parse spec"));
@@ -375,6 +394,9 @@ export default function AddOpenApiIntegration(props: {
         specFormat: initialPreset?.specFormat,
         family: initialPreset?.family,
         healthCheck: initialPreset?.healthCheck,
+        ...(parsedSpecOverrides.ok && parsedSpecOverrides.value.length > 0
+          ? { specOverrides: parsedSpecOverrides.value }
+          : {}),
         // Always send the edited method list (even empty) when the user has
         // inspected a preview: an explicit [] means "no auth methods", while
         // OMITTING the field tells the server to derive defaults from the
@@ -399,6 +421,7 @@ export default function AddOpenApiIntegration(props: {
     resolvedDescription,
     resolvedBaseUrl,
     editedAuthenticationTemplate,
+    parsedSpecOverrides,
     initialPreset?.family,
     initialPreset?.healthCheck,
     initialPreset?.specFormat,
@@ -539,6 +562,17 @@ export default function AddOpenApiIntegration(props: {
         />
       ) : null}
 
+      <SpecOverridesEditor
+        value={specOverridesText}
+        onChange={(value) => {
+          setSpecOverridesText(value);
+          setAnalyzeError(null);
+          setPreview(null);
+          setBaseUrl("");
+        }}
+        disabled={analyzing || adding}
+      />
+
       {preview && (
         <AuthMethodListEditor
           list={authMethodList}

packages/plugins/openapi/src/react/SpecOverridesEditor.tsx

@@ -0,0 +1,50 @@
+import { useState } from "react";
+import { ChevronDown } from "lucide-react";
+
+import { cn } from "@executor-js/react/lib/utils";
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@executor-js/react/components/collapsible";
+import { FieldLabel } from "@executor-js/react/components/field";
+import { Textarea } from "@executor-js/react/components/textarea";
+
+import { parseSpecOverridesText } from "../sdk/spec-overrides";
+
+export function SpecOverridesEditor(props: {
+  readonly value: string;
+  readonly onChange: (value: string) => void;
+  readonly disabled?: boolean;
+}) {
+  const [open, setOpen] = useState(props.value.trim().length > 0);
+  const parsed = parseSpecOverridesText(props.value);
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen}>
+      <CollapsibleTrigger className="flex items-center gap-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground">
+        Spec overrides
+        <ChevronDown
+          className={cn("size-3.5 transition-transform", open && "rotate-180")}
+          aria-hidden="true"
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent>
+        <div className="mt-3 space-y-2">
+          <FieldLabel>JSON Patch (RFC 6902)</FieldLabel>
+          <Textarea
+            value={props.value}
+            onChange={(event) => props.onChange((event.target as HTMLTextAreaElement).value)}
+            placeholder={'[{"op":"replace","path":"/info/title","value":"My API"}]'}
+            rows={5}
+            maxRows={14}
+            className="font-mono text-xs"
+            disabled={props.disabled}
+            aria-invalid={!parsed.ok}
+          />
+          {!parsed.ok && <p className="text-xs text-destructive">{parsed.message}</p>}
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}

packages/plugins/openapi/src/react/UpdateSpecSection.tsx

@@ -13,6 +13,8 @@ import { Label } from "@executor-js/react/components/label";
 import { Textarea } from "@executor-js/react/components/textarea";
 
 import { openApiConfigAtom, updateOpenApiSpec } from "./atoms";
+import { SpecOverridesEditor } from "./SpecOverridesEditor";
+import { formatSpecOverridesText, parseSpecOverridesText } from "../sdk/spec-overrides";
 
 // ---------------------------------------------------------------------------
 // Update spec — the openapi plugin's section of the integration Edit sheet.
@@ -47,22 +49,34 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
   const doUpdate = useAtomSet(updateOpenApiSpec, { mode: "promiseExit" });
   const [refetchStaged, setRefetchStaged] = useState(false);
   const [pasted, setPasted] = useState("");
+  const [specOverridesDraft, setSpecOverridesDraft] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   const config =
     AsyncResult.isSuccess(configResult) && configResult.value ? configResult.value : null;
 
   const specUrl = config?.specUrl;
+  const specOverridesText = specOverridesDraft ?? formatSpecOverridesText(config?.specOverrides);
 
   // The staged apply, rebuilt whenever the staged inputs change. Reported to
   // the sheet through a ref-stable callback so Save can run it.
   const applyStaged = useCallback(async (): Promise<EditSheetApplyResult> => {
     const spec = pasted.trim().length > 0 ? { kind: "blob" as const, value: pasted } : undefined;
-    if (!spec && !refetchStaged) return { ok: true, summary: null };
+    const parsedOverrides = parseSpecOverridesText(specOverridesText);
+    if (!parsedOverrides.ok) {
+      setError(parsedOverrides.message);
+      return { ok: false };
+    }
+    if (!spec && !refetchStaged && specOverridesDraft === null) {
+      return { ok: true, summary: null };
+    }
     setError(null);
     const exit = await doUpdate({
       params: { slug },
-      payload: spec ? { spec } : {},
+      payload: {
+        ...(spec ? { spec } : {}),
+        ...(specOverridesDraft !== null ? { specOverrides: parsedOverrides.value } : {}),
+      },
       reactivityKeys: integrationWriteKeys,
     });
     if (Exit.isFailure(exit)) {
@@ -71,12 +85,13 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
     }
     setRefetchStaged(false);
     setPasted("");
+    setSpecOverridesDraft(null);
     return { ok: true, summary: outcomeSummary(exit.value) };
-  }, [doUpdate, pasted, refetchStaged, slug]);
+  }, [doUpdate, pasted, refetchStaged, slug, specOverridesDraft, specOverridesText]);
 
   const onPendingChangeRef = useRef(props.onPendingChange);
   onPendingChangeRef.current = props.onPendingChange;
-  const hasStagedChange = refetchStaged || pasted.trim().length > 0;
+  const hasStagedChange = refetchStaged || pasted.trim().length > 0 || specOverridesDraft !== null;
   useEffect(() => {
     onPendingChangeRef.current?.(hasStagedChange ? applyStaged : null);
     // Clear the staged apply if this section unmounts mid-edit.
@@ -129,6 +144,8 @@ export default function UpdateSpecSection(props: EditSheetSectionProps) {
         </div>
       )}
 
+      <SpecOverridesEditor value={specOverridesText} onChange={setSpecOverridesDraft} />
+
       {error && <FormErrorAlert message={error} />}
     </div>
   );

packages/plugins/openapi/src/sdk/config.ts

@@ -7,6 +7,7 @@ import {
 } from "@executor-js/sdk/http-auth";
 
 import type { Authentication } from "./types";
+import { SpecOverridesSchema, type SpecOverrides } from "./spec-overrides";
 
 // ---------------------------------------------------------------------------
 // OpenAPI integration config — the opaque blob stored on the catalog
@@ -17,6 +18,7 @@ import type { Authentication } from "./types";
 // StoredSource credential config. The config carries only:
 //   - the content hash of the spec blob and/or the source URL to (re)fetch
 //     from,
+//   - optional RFC 6902 overrides and the raw source hash they apply to,
 //   - the optional base URL override,
 //   - the auth templates a connection's value is rendered through.
 // The resolved spec text itself lives in the plugin blob store, keyed
@@ -43,6 +45,8 @@ export const OpenApiIntegrationConfigSchema = Schema.Struct({
   /** Hex SHA-256 of the resolved spec text — the content address of the spec
    *  blob (`spec/<hash>` in the plugin blob store). */
   specHash: Schema.optional(Schema.String),
+  /** Hex SHA-256 of the unmodified source text when spec overrides are active. */
+  sourceSpecHash: Schema.optional(Schema.String),
   /** Origin URL the spec was fetched from, when known. Enables refresh. */
   specUrl: Schema.optional(Schema.String),
   /** Optional base URL override. */
@@ -55,17 +59,20 @@ export const OpenApiIntegrationConfigSchema = Schema.Struct({
   specFormat: Schema.optional(Schema.String),
   /** Catalog family for grouped integration display. */
   family: Schema.optional(Schema.String),
+  /** Ordered RFC 6902 operations reapplied whenever the source spec is refreshed. */
+  specOverrides: Schema.optional(SpecOverridesSchema),
   /** The auth methods a connection's value can be applied through. */
   authenticationTemplate: Schema.optional(Schema.Array(AuthenticationSchema)),
 });
 
 export type OpenApiIntegrationConfig = Omit<
   typeof OpenApiIntegrationConfigSchema.Type,
-  "authenticationTemplate"
+  "authenticationTemplate" | "specOverrides"
 > & {
   /** Branded over the schema's structural form so the template renderer can
    *  treat `slug` as an `AuthTemplateSlug`. */
   readonly authenticationTemplate?: readonly Authentication[];
+  readonly specOverrides?: SpecOverrides;
 };
 
 const decodeConfig = Schema.decodeUnknownOption(OpenApiIntegrationConfigSchema);

packages/plugins/openapi/src/sdk/errors.ts

@@ -25,6 +25,17 @@ export class OpenApiExtractionError extends Schema.TaggedErrorClass<OpenApiExtra
   { httpApiStatus: 400 },
 ) {}
 
+export class OpenApiSpecOverrideError extends Schema.TaggedErrorClass<OpenApiSpecOverrideError>()(
+  "OpenApiSpecOverrideError",
+  {
+    operationIndex: Schema.Number,
+    operation: Schema.String,
+    path: Schema.String,
+    message: Schema.String,
+  },
+  { httpApiStatus: 400 },
+) {}
+
 export class OpenApiInvocationError extends Data.TaggedError("OpenApiInvocationError")<{
   readonly message: string;
   readonly statusCode: Option.Option<number>;