feat(connector-openapi): resolve providerConfig.spec from a package-relative file path (#3016)

ADR-0096 follow-up: complete the spec union (inline object | file path |
remote URL) for the declarative openapi provider.

- spec: ConnectorProviderContext gains an optional host-injected
  loadPackageFile capability (pure type)
- service-automation: packageRoot option + createPackageFileLoader with a
  root-confinement guard (rejects absolute and ..-escaping paths; lazy
  node:fs/node:path imports); capability injected into every provider ctx;
  failures follow the reconcile policy (fatal at boot, soft on reload)
- connector-openapi: non-URL string specs are read via ctx.loadPackageFile
  and parsed as OpenAPI JSON with clear errors
- cli: serve/dev anchor packageRoot to the objectstack.config.ts directory
- tests: file-path happy path, missing file (fatal at boot / skipped on
  reload), traversal rejection; ADR-0096 scope-boundary note updated

Closes #3016

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016eY7byWABTUPtJG7R2AEFU

Author: claude

.changeset/adr-0096-openapi-spec-file-path.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-automation': minor
+'@objectstack/connector-openapi': minor
+'@objectstack/cli': minor
+---
+
+feat(connector-openapi): resolve `providerConfig.spec` from a package-relative file path (#3016, ADR-0096 follow-up)
+
+ADR-0096's canonical example authors an OpenAPI-backed instance as
+`providerConfig: { spec: './billing-openapi.json' }`, but the landed `openapi`
+provider factory only accepted an inline document object or an http(s) URL.
+The spec union is now complete: **inline object | file path | remote URL**.
+
+- **`@objectstack/spec`.** `ConnectorProviderContext` gains an optional
+  host-injected `loadPackageFile(relativePath)` capability (pure type): reads a
+  UTF-8 file resolved against the declaring stack/package root, confined to
+  that root. `undefined` on hosts without a filesystem.
+
+- **`@objectstack/service-automation`.** New `packageRoot` plugin option (the
+  base for relative file refs; defaults to `process.cwd()`) and an exported
+  `createPackageFileLoader(packageRoot)` that implements the confinement
+  guard — absolute paths and `..`-escaping paths are rejected — with lazy
+  `node:fs`/`node:path` imports so non-Node hosts only fail if a file ref is
+  actually dereferenced. The materializer injects the capability into every
+  provider factory's context. Failures follow the existing reconcile policy:
+  **fatal at boot, entry skipped on reload**.
+
+- **`@objectstack/connector-openapi`.** A string `providerConfig.spec` that is
+  not an http(s) URL is now read via `ctx.loadPackageFile` and parsed as an
+  OpenAPI JSON document (clear errors for missing/unreadable files, unparseable
+  JSON, and hosts without package file access).
+
+- **`@objectstack/cli`.** `serve`/`dev` pass the project folder (the
+  `objectstack.config.ts` directory) as the automation service's `packageRoot`,
+  mirroring how the standalone sqlite default is anchored.

docs/adr/0096-declarative-connector-instances.md

@@ -134,6 +134,6 @@ keeps serving until its replacement materializes successfully. Boot keeps the
 
 ### Deliberate scope boundaries
 
-- **`providerConfig.spec` (openapi)** accepts an inline document or an http(s) URL; resolving a `./file.json` ref relative to the stack is the stack loader's job, not the connector's.
+- **`providerConfig.spec` (openapi)** accepts an inline document, an http(s) URL, **or a package-relative file path** (#3016 follow-up). The connector still owns no filesystem access: the automation service injects a `loadPackageFile` capability into `ConnectorProviderContext` that resolves the ref against the declaring stack/package root (`packageRoot`, CLI default: the `objectstack.config.ts` directory) and **confines reads to that root** — absolute and `..`-escaping paths are rejected. Read/parse failures follow the reconcile policy above: fatal at boot, skipped on reload.
 - **MCP credentials** ride the transport (ADR-0024); for an http transport a resolved `auth` is folded into the request headers.
 - **MCP at boot** connects during materialization, so an unreachable server fails boot; a fail-soft "optional" marker for boot-time materialization is a possible future refinement (runtime reloads are already soft).

packages/cli/src/commands/serve.ts

@@ -1855,7 +1855,14 @@ export default class Serve extends Command {
           }
           // analytics needs cubes from config, others take no args
           let arg: any;
-          if (spec.configKey === 'analyticsCubes') {
+          if (cap === 'automation') {
+            // #3016 — anchor declarative connector file refs (e.g. the openapi
+            // provider's `providerConfig.spec: './billing-openapi.json'`) to the
+            // project folder (next to objectstack.config.ts), mirroring how the
+            // standalone sqlite default is anchored above. Reads are confined to
+            // this root by the automation service's package file loader.
+            arg = { packageRoot: path.dirname(absolutePath) };
+          } else if (spec.configKey === 'analyticsCubes') {
             const cubes = (config as any).analyticsCubes ?? (config as any).cubes ?? [];
             arg = { cubes };
           } else if (cap === 'email') {

packages/connectors/connector-openapi/src/openapi-provider.test.ts

@@ -52,10 +52,47 @@ describe('openapi provider factory (ADR-0096)', () => {
         await expect(factory(ctx({ providerConfig: {} }))).rejects.toThrow(/providerConfig\.spec/);
     });
 
-    it('rejects a bare file-path spec with a clear message', async () => {
+    // ── File-path specs (#3016 — ADR-0096 follow-up) ────────────────────────
+
+    it('reads a file-path spec through the host loadPackageFile capability', async () => {
+        const requested: string[] = [];
+        const loadPackageFile = async (rel: string) => {
+            requested.push(rel);
+            return JSON.stringify(petstore);
+        };
+        const factory = createOpenApiProviderFactory();
+        const { def, handlers } = await factory(
+            ctx({ providerConfig: { spec: './specs/petstore.json' }, loadPackageFile }),
+        );
+        expect(requested).toEqual(['./specs/petstore.json']);
+        expect(def.actions?.map((a) => a.key)).toEqual(['listPets']);
+        expect(Object.keys(handlers)).toEqual(['listPets']);
+    });
+
+    it('surfaces a loader failure (missing file / traversal rejection) with the connector name', async () => {
+        const loadPackageFile = async (rel: string) => {
+            throw new Error(`package file ref '${rel}' could not be read`);
+        };
+        const factory = createOpenApiProviderFactory();
+        await expect(
+            factory(ctx({ providerConfig: { spec: './missing.json' }, loadPackageFile })),
+        ).rejects.toThrow(/'pets' failed to read providerConfig\.spec '\.\/missing\.json'.*could not be read/s);
+    });
+
+    it('rejects an unparseable file-path spec with a clear message', async () => {
+        const factory = createOpenApiProviderFactory();
+        await expect(
+            factory(ctx({ providerConfig: { spec: './broken.json' }, loadPackageFile: async () => 'not-json{' })),
+        ).rejects.toThrow(/not a parseable.*OpenAPI JSON document/s);
+        await expect(
+            factory(ctx({ providerConfig: { spec: './array.json' }, loadPackageFile: async () => '[1,2]' })),
+        ).rejects.toThrow(/not a parseable.*OpenAPI JSON document/s);
+    });
+
+    it('rejects a file-path spec with a clear message when the host has no package file access', async () => {
         const factory = createOpenApiProviderFactory();
         await expect(
             factory(ctx({ providerConfig: { spec: './petstore.json' } })),
-        ).rejects.toThrow(/not an http\(s\) URL/);
+        ).rejects.toThrow(/no package file access/);
     });
 });

packages/connectors/connector-openapi/src/openapi-provider.ts

@@ -1,6 +1,10 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { ConnectorProviderFactory, ResolvedConnectorAuth } from '@objectstack/spec/integration';
+import type {
+  ConnectorProviderContext,
+  ConnectorProviderFactory,
+  ResolvedConnectorAuth,
+} from '@objectstack/spec/integration';
 import {
   createOpenApiConnector,
   type OpenApiDocument,
@@ -21,24 +25,32 @@ export interface OpenApiProviderDeps {
 
 /** Shape of `providerConfig` for a `provider: 'openapi'` declarative instance. */
 interface OpenApiProviderConfig {
-  /** The OpenAPI 3.x document: an inline object, or an http(s) URL to fetch at boot. */
+  /**
+   * The OpenAPI 3.x document: an inline object, an http(s) URL to fetch at
+   * boot, or a file path resolved relative to the declaring stack/package root
+   * (`'./billing-openapi.json'`, #3016).
+   */
   spec?: unknown;
   /** Override the base URL (else the document's `servers[0].url`). */
   baseUrl?: unknown;
 }
 
 /**
- * Resolve `providerConfig.spec` into a parsed OpenAPI document. Accepts an inline
- * document object (the reliable, no-network-at-boot form used by the showcase) or
- * an http(s) URL fetched at materialization. A bare file path is rejected with a
- * clear message: resolving `./x.json` relative to the stack is the stack loader's
- * job, not the connector's — inline the document or serve it over HTTP.
+ * Resolve `providerConfig.spec` into a parsed OpenAPI document (ADR-0096;
+ * union per #3016): an inline document object (the reliable, no-I/O-at-boot
+ * form used by the showcase), an http(s) URL fetched at materialization, or a
+ * **file path** read through the host's `ctx.loadPackageFile` — which resolves
+ * it relative to the declaring stack/package root and confines the read to
+ * that root (absolute / `..`-escaping paths are rejected there). Every failure
+ * throws, so the materializer's reconcile policy applies: fatal at boot, the
+ * entry is skipped on reload.
  */
 async function loadOpenApiDocument(
   spec: unknown,
   fetchImpl: typeof fetch | undefined,
-  connectorName: string,
+  ctx: ConnectorProviderContext,
 ): Promise<OpenApiDocument> {
+  const connectorName = ctx.name;
   if (spec && typeof spec === 'object' && !Array.isArray(spec)) {
     return spec as OpenApiDocument;
   }
@@ -53,13 +65,39 @@ async function loadOpenApiDocument(
       }
       return (await res.json()) as OpenApiDocument;
     }
-    throw new Error(
-      `connector-openapi provider: connector '${connectorName}' providerConfig.spec '${spec}' is not an http(s) URL. ` +
-        `Provide an inline OpenAPI document object or an http(s) URL — file-path refs are resolved by the stack loader, not the connector.`,
-    );
+    // File path — dereferenced through the host capability so resolution stays
+    // anchored to (and confined within) the declaring stack/package root.
+    if (!ctx.loadPackageFile) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' providerConfig.spec '${spec}' is a file path, ` +
+          `but this host provides no package file access — inline the OpenAPI document or use an http(s) URL.`,
+      );
+    }
+    let text: string;
+    try {
+      text = await ctx.loadPackageFile(spec);
+    } catch (err) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' failed to read providerConfig.spec '${spec}': ` +
+          `${(err as Error).message}`,
+      );
+    }
+    try {
+      const parsed: unknown = JSON.parse(text);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+      }
+      return parsed as OpenApiDocument;
+    } catch (err) {
+      throw new Error(
+        `connector-openapi provider: connector '${connectorName}' providerConfig.spec '${spec}' is not a parseable ` +
+          `OpenAPI JSON document: ${(err as Error).message}`,
+      );
+    }
   }
   throw new Error(
-    `connector-openapi provider: connector '${connectorName}' requires providerConfig.spec — an inline OpenAPI 3.x document object or an http(s) URL.`,
+    `connector-openapi provider: connector '${connectorName}' requires providerConfig.spec — an inline OpenAPI 3.x ` +
+      `document object, an http(s) URL, or a package-relative file path.`,
   );
 }
 
@@ -82,7 +120,7 @@ export function createOpenApiProviderFactory(deps: OpenApiProviderDeps = {}): Co
         `connector-openapi provider: connector '${ctx.name}' providerConfig.baseUrl must be a string when set.`,
       );
     }
-    const document = await loadOpenApiDocument(cfg.spec, deps.fetchImpl, ctx.name);
+    const document = await loadOpenApiDocument(cfg.spec, deps.fetchImpl, ctx);
     const auth = ctx.auth as ResolvedConnectorAuth | undefined as RestAuth | undefined;
     return createOpenApiConnector({
       name: ctx.name,

packages/services/service-automation/src/connector-materialization.test.ts

@@ -9,14 +9,17 @@
 // Boot fails loudly for unknown provider / unresolvable credentialRef / name
 // conflict / factory failure.
 
-import { describe, it, expect } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import * as path from 'node:path';
+import { describe, it, expect, afterAll } from 'vitest';
 import { LiteKernel } from '@objectstack/core';
 import type {
     ConnectorProviderContext,
     ConnectorProviderFactory,
     ConnectorInstanceAuth,
 } from '@objectstack/spec/integration';
-import { AutomationServicePlugin, type CredentialResolver } from './plugin.js';
+import { AutomationServicePlugin, createPackageFileLoader, type CredentialResolver } from './plugin.js';
 import type { AutomationEngine } from './engine.js';
 
 const flush = () => new Promise<void>((r) => setTimeout(r, 0));
@@ -81,6 +84,8 @@ interface BootOptions {
     /** Names registered as plugin connectors during init() (for the conflict rule). */
     registerLivePlugin?: string[];
     credentialResolver?: CredentialResolver;
+    /** Stack/package root that relative file refs resolve against (#3016). */
+    packageRoot?: string;
 }
 
 /**
@@ -92,7 +97,7 @@ interface BootOptions {
  */
 async function boot(declared: unknown[], opts: BootOptions = {}): Promise<LiteKernel> {
     const kernel = new LiteKernel({ logger: { level: 'silent' } } as never);
-    kernel.use(new AutomationServicePlugin({ credentialResolver: opts.credentialResolver }));
+    kernel.use(new AutomationServicePlugin({ credentialResolver: opts.credentialResolver, packageRoot: opts.packageRoot }));
     const harness = {
         name: 'test.harness',
         type: 'standard' as const,
@@ -160,12 +165,12 @@ function makeClosableProvider() {
  */
 async function bootReloadable(
     initial: unknown[],
-    opts: { providerFactory: ConnectorProviderFactory; credentialResolver?: CredentialResolver },
+    opts: { providerFactory: ConnectorProviderFactory; credentialResolver?: CredentialResolver; packageRoot?: string },
 ) {
     const state = { declared: initial };
     let captured: any;
     const kernel = new LiteKernel({ logger: { level: 'silent' } } as never);
-    kernel.use(new AutomationServicePlugin({ credentialResolver: opts.credentialResolver }));
+    kernel.use(new AutomationServicePlugin({ credentialResolver: opts.credentialResolver, packageRoot: opts.packageRoot }));
     const harness = {
         name: 'test.harness',
         type: 'standard' as const,
@@ -427,3 +432,105 @@ describe('ADR-0096 — runtime re-materialization on metadata:reloaded (F1)', ()
         await kernel.shutdown();
     });
 });
+
+// ── #3016 — package file refs (loadPackageFile) ─────────────────────────────
+//
+// The `loadPackageFile` capability lets a provider factory dereference a
+// relative file ref (the openapi provider's `providerConfig.spec:
+// './billing-openapi.json'`) against the declaring stack/package root, with
+// reads CONFINED to that root. Failures follow the reconcile policy above:
+// fatal at boot, skipped on reload.
+
+const fixtureRoot = mkdtempSync(path.join(tmpdir(), 'adr96-pkgfile-'));
+mkdirSync(path.join(fixtureRoot, 'specs'), { recursive: true });
+writeFileSync(path.join(fixtureRoot, 'specs', 'billing.json'), JSON.stringify({ openapi: '3.0.0' }));
+afterAll(() => rmSync(fixtureRoot, { recursive: true, force: true }));
+
+/** A provider whose factory reads `providerConfig.spec` via ctx.loadPackageFile. */
+function makeFileReadingProvider() {
+    const reads: string[] = [];
+    const factory: ConnectorProviderFactory = async (ctx) => {
+        const text = await ctx.loadPackageFile!(String(ctx.providerConfig.spec));
+        reads.push(text);
+        return {
+            def: { name: ctx.name, label: ctx.label, type: 'api', authentication: { type: 'none' }, actions: [{ key: 'ping', label: 'Ping' }] },
+            handlers: { ping: async () => ({ ok: true }) },
+        };
+    };
+    return { factory, reads };
+}
+
+describe('#3016 — package file loader (createPackageFileLoader)', () => {
+    const load = createPackageFileLoader(fixtureRoot);
+
+    it('reads a root-relative file (happy path)', async () => {
+        await expect(load('./specs/billing.json')).resolves.toBe(JSON.stringify({ openapi: '3.0.0' }));
+        // Plain relative form (no leading ./) resolves identically.
+        await expect(load('specs/billing.json')).resolves.toContain('openapi');
+    });
+
+    it('rejects absolute paths (posix and windows-drive)', async () => {
+        await expect(load(path.join(fixtureRoot, 'specs', 'billing.json'))).rejects.toThrow(/absolute/);
+        await expect(load('C:\\evil\\creds.json')).rejects.toThrow(/absolute/);
+    });
+
+    it('rejects paths that escape the package root after resolution', async () => {
+        await expect(load('../outside.json')).rejects.toThrow(/escapes the stack\/package root/);
+        await expect(load('specs/../../outside.json')).rejects.toThrow(/escapes the stack\/package root/);
+    });
+
+    it('rejects empty refs and reports unreadable files with the resolved path', async () => {
+        await expect(load('')).rejects.toThrow(/non-empty relative path/);
+        await expect(load('./specs/missing.json')).rejects.toThrow(/could not be read/);
+    });
+});
+
+describe('#3016 — file-ref materialization policy (fatal at boot, soft on reload)', () => {
+    it('hands every provider factory a working loadPackageFile anchored to packageRoot', async () => {
+        const { factory, reads } = makeFileReadingProvider();
+        const kernel = await boot(
+            [providerConnector('billing', { providerConfig: { spec: './specs/billing.json' } })],
+            { providerFactory: factory, packageRoot: fixtureRoot },
+        );
+        expect(automationOf(kernel).getRegisteredConnectors()).toContain('billing');
+        expect(reads).toEqual([JSON.stringify({ openapi: '3.0.0' })]);
+        await kernel.shutdown();
+    });
+
+    it('fails boot loudly when the file ref is missing', async () => {
+        const { factory } = makeFileReadingProvider();
+        await expect(
+            boot([providerConnector('billing', { providerConfig: { spec: './specs/missing.json' } })], {
+                providerFactory: factory,
+                packageRoot: fixtureRoot,
+            }),
+        ).rejects.toThrow(/failed to materialize connector instance 'billing'.*could not be read/s);
+    });
+
+    it('fails boot loudly when the file ref escapes the package root', async () => {
+        const { factory } = makeFileReadingProvider();
+        await expect(
+            boot([providerConnector('billing', { providerConfig: { spec: '../outside.json' } })], {
+                providerFactory: factory,
+                packageRoot: fixtureRoot,
+            }),
+        ).rejects.toThrow(/escapes the stack\/package root/);
+    });
+
+    it('reload is soft: a bad file ref skips the entry, keeps the old connector serving', async () => {
+        const { factory } = makeFileReadingProvider();
+        const { engine, reload, kernel } = await bootReloadable(
+            [providerConnector('billing', { providerConfig: { spec: './specs/billing.json' } })],
+            { providerFactory: factory, packageRoot: fixtureRoot },
+        );
+        expect(engine.getRegisteredConnectors()).toContain('billing');
+
+        // A publish that points billing at a missing file must not crash the
+        // server; the previously materialized connector keeps serving.
+        await expect(
+            reload([providerConnector('billing', { providerConfig: { spec: './specs/missing.json' } })]),
+        ).resolves.toBeUndefined();
+        expect(engine.getRegisteredConnectors()).toContain('billing');
+        await kernel.shutdown();
+    });
+});

packages/services/service-automation/src/index.ts

@@ -45,7 +45,7 @@ export { SysAutomationRun } from './sys-automation-run.object.js';
 
 // Kernel plugin — seeds all built-in nodes; this is the only plugin needed for
 // a fully-functional automation capability.
-export { AutomationServicePlugin } from './plugin.js';
+export { AutomationServicePlugin, createPackageFileLoader } from './plugin.js';
 export type { AutomationServicePluginOptions } from './plugin.js';
 
 // Run identity (ADR-0049 / #1888). Maps a flow run's effective `runAs` to the