@shipworthy/openapi-generator 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipworthy AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,297 @@
-# Temporary Holding Version
+# @shipworthy/openapi-generator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Load, bundle, and parse an OpenAPI 3.x document, then run one generator plugin on the result. `generate` takes a document (a file path, a URL, file URL, JSON/YAML text, `Buffer`, Node `Readable`, or plain object). It resolves external `$ref`s, upgrades OpenAPI 3.0 to 3.1, decodes the document into the `ParsedService` model from `@shipworthy/openapi-transformer`, loads a plugin by module specifier and export name, and returns whatever the plugin's `generate` returns. Use this package to drive an existing `@shipworthy/*` generator from code, such as `@shipworthy/openapi-typescript` (export `typescript`) or `@shipworthy/openapi-zod` (export `zod`), or to write your own generator against the `Generator` interface. The `openapi` CLI (`@shipworthy/openapi-cli`) is built on this package. If you only want generated files on disk, use the CLI.
+
+The API is built on [Effect](https://effect.website) 4. `generate` returns an `Effect`, not a `Promise`.
+
+## Installation
+
+```sh
+bun add @shipworthy/openapi-generator effect @effect/platform-node
+```
+
+Requirements:
+
+- **`effect` `^4.0.0`.** This is a peer dependency, so install it yourself. Every package then shares one copy of `effect`, which you use to build, run, and provide services to the returned `Effect`.
+- **`@effect/platform-node` `^4.0.0`**, only because the examples below import `NodeServices` from it. `@shipworthy/openapi-parser` already depends on it, but your own code needs it in your `package.json` to import it.
+- **A platform layer.** `generate` requires the `FileSystem`, `Path`, and `HttpClient` services. Provide them with `NodeServices.layer` from `@effect/platform-node` or `BunServices.layer` from `@effect/platform-bun`, plus `FetchHttpClient.layer` from `effect/http`. `HttpClient` is required even when the source is inline, because it's part of the effect's type.
+- **ESM only.** The package is `"type": "module"` and ships compiled ESM JavaScript with `.d.ts` declarations. It has no CommonJS build, and it needs no TypeScript loader or bundler.
+- **Node.js `>=22.19.0` or Bun.** The loader uses Node APIs (`Buffer`, `node:stream`) through its `@shipworthy/openapi-parser` dependency. It doesn't run in browsers.
+- **The plugin package.** Each plugin is loaded with dynamic `import()` when `generate` runs. Install it too, for example `@shipworthy/openapi-typescript`.
+
+## Quick start
+
+Write a generator plugin:
+
+```ts
+// operation-ids.ts
+import type { Generator } from "@shipworthy/openapi-generator";
+
+export const operationIds: Generator<string[]> = {
+  id: "operation-ids",
+  generate: (model) => model.operations.map((op) => `${op.method.toUpperCase()} ${op.path}`),
+};
+```
+
+Then run it on an OpenAPI document:
+
+```yaml
+# openapi.yaml
+openapi: 3.0.3
+info: { title: Pets, version: "1.0.0" }
+paths:
+  /pets:
+    get:
+      operationId: listPets
+      responses:
+        "200": { description: OK }
+```
+
+```ts
+// main.ts
+import { NodeServices } from "@effect/platform-node";
+import { generate } from "@shipworthy/openapi-generator";
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+
+const program = generate({
+  // Pass a local plugin as an absolute file URL.
+  specifier: new URL("./operation-ids.ts", import.meta.url).href,
+  exportName: "operationIds",
+  // A path string is resolved against process.cwd() (see "Sources").
+  source: "./openapi.yaml",
+}).pipe(
+  Effect.tap((output) => Effect.log(output)), // ["GET /pets"]
+  Effect.catchTags({
+    ResolveError: (error) => Effect.logError(`Invalid document: ${error.message}`),
+    TransformError: (error) => Effect.logError(`Generation failed: ${error.message}`),
+    MissingPlugin: (error) => Effect.logError(error.message),
+    InvalidPlugin: (error) => Effect.logError(error.message),
+  }),
+  Effect.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)),
+);
+
+Effect.runPromise(program);
+```
+
+On Bun, swap `NodeServices` for `BunServices` from `@effect/platform-bun`.
+
+## API
+
+The package has a single entry point, `@shipworthy/openapi-generator`. It exports:
+
+| Export                                                             | Kind                           | Purpose                                                                  |
+| ------------------------------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------ |
+| `generate`                                                         | function returning an `Effect` | Runs the full pipeline: load, bundle, decode, import the plugin, render. |
+| `GenerateOptions`                                                  | type                           | Options for `generate`.                                                  |
+| `GenerateError`                                                    | type                           | Union of every error `generate` can fail with.                           |
+| `Generator<A, E>`                                                  | type                           | The interface a plugin export implements.                                |
+| `importPlugin`                                                     | function returning an `Effect` | Loads and checks a plugin without running it.                            |
+| `ModuleLoader`                                                     | `Context.Reference`            | The service that imports plugin modules. You can replace it.             |
+| `ResolveError`, `TransformError`, `MissingPlugin`, `InvalidPlugin` | tagged error classes           | Typed failures.                                                          |
+
+### `generate(options)`
+
+```ts
+function generate(
+  options: GenerateOptions,
+): Effect.Effect<unknown, GenerateError, FileSystem.FileSystem | Path.Path | HttpClient.HttpClient>;
+
+interface GenerateOptions {
+  readonly specifier: string;
+  readonly exportName: string;
+  readonly source: unknown;
+  readonly cwd?: URL | string;
+  readonly pluginOptions?: Readonly<Record<string, unknown>>;
+}
+```
+
+| Option          | Required | Default         | Description                                                                                                                                                                                                                                                     |
+| --------------- | -------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `specifier`     | yes      | —               | Module to import the plugin from: a package name such as `"@shipworthy/openapi-typescript"`, or an absolute `file://` URL string. Passed to `ModuleLoader.load`.                                                                                                |
+| `exportName`    | yes      | —               | Named export of that module that holds the `Generator`, for example `"typescript"` or `"zod"`.                                                                                                                                                                  |
+| `source`        | yes      | —               | The OpenAPI document. See [Sources](#sources).                                                                                                                                                                                                                  |
+| `cwd`           | no       | `process.cwd()` | Base location for a relative path `source` and for relative `$ref`s when `source` is inline (text, `Buffer`, stream, or object). A string is resolved as a directory path. A `URL` is used as is. File and URL sources resolve refs against their own location. |
+| `pluginOptions` | no       | `{}`            | Passed unchanged as the second argument of the plugin's `generate`. Each plugin defines its own keys.                                                                                                                                                           |
+
+`generate` runs these steps in order:
+
+1. **Load and bundle** the source with `@shipworthy/openapi-parser`. This parses JSON or YAML, inlines external `$ref`s, and upgrades OpenAPI 3.0 to 3.1. Any failure here becomes a `ResolveError`.
+2. **Decode** the bundled document into a `ParsedService` with `@shipworthy/openapi-transformer`'s `decode`. A failure becomes a `TransformError`.
+3. **Import the plugin** with `importPlugin(specifier, exportName)`. This can fail with `MissingPlugin` or `InvalidPlugin`. The plugin is imported only after steps 1 and 2 succeed, so an invalid document never loads plugin code.
+4. **Render** by calling `plugin.generate(model, pluginOptions ?? {})`. If the plugin returns a plain value, the effect succeeds with it. If it returns an `Effect`, that effect runs and its success value is the result. A synchronous throw, or a failure in the returned `Effect`, becomes a `TransformError` whose `cause` is the original error.
+
+**Returns** `unknown`, whatever the plugin produced. Narrow or decode it yourself. For example, `@shipworthy/openapi-typescript`'s `typescript` plugin returns an array of TypeScript AST nodes.
+
+**Errors:** `GenerateError = ResolveError | TransformError | MissingPlugin | InvalidPlugin`.
+
+The source object you pass is not mutated. Object input is also not serialized, so values such as `bigint` extensions reach the model unchanged.
+
+#### Example: running a published plugin with options
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { generate } from "@shipworthy/openapi-generator";
+import { Effect, Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+
+const nodes = await Effect.runPromise(
+  generate({
+    specifier: "@shipworthy/openapi-typescript",
+    exportName: "typescript",
+    source: new URL("https://example.com/openapi.yaml"),
+    pluginOptions: {/* options defined by @shipworthy/openapi-typescript */},
+  }).pipe(Effect.provide(Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer))),
+);
+```
+
+### Sources
+
+`source` accepts:
+
+| Value                                                    | Treatment                                                                                                                                                        |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `URL` with `file:` protocol                              | Read from disk with `FileSystem`.                                                                                                                                |
+| `URL` with `http:`/`https:` protocol                     | Fetched with `HttpClient`. A non-2xx status fails.                                                                                                               |
+| String starting with `http://`, `https://`, or `file://` | Converted to a `URL` and handled as above.                                                                                                                       |
+| File path string (see below)                             | Resolved against `cwd` and read from disk with `FileSystem`. Relative `$ref`s resolve against the file.                                                          |
+| Any other string                                         | Parsed as document text. Text starting with `{` or `[` is tried as JSON first, with a YAML fallback. Anything else is parsed as YAML. A leading BOM is stripped. |
+| `Buffer`                                                 | Decoded as UTF-8 text.                                                                                                                                           |
+| Node `Readable` stream                                   | Read to the end as text.                                                                                                                                         |
+| Plain object                                             | Used directly as the document.                                                                                                                                   |
+
+A string is a file path when, after trimming, it is a single line and either is absolute according to Effect's `Path` service on the current platform, starts with `./`, `../`, `.\`, or `..\`, or ends in `.json`, `.yaml`, or `.yml`, contains no `: `, and doesn't start with `{` or `[`. So `"./openapi.yaml"`, `"/srv/openapi.json"`, and `"specs/openapi.yml"` are read from disk, while inline JSON and YAML documents are still parsed as text. A missing file fails with a `ResolveError` that carries the `FileSystem` error, such as `NotFound: FileSystem.readFile (/abs/openapi.yaml)`.
+
+### `Generator<A, E>`
+
+```ts
+interface Generator<A, E = never> {
+  readonly id: string;
+  generate(
+    model: ParsedService,
+    options: Readonly<Record<string, unknown>>,
+  ): A | Effect.Effect<A, E>;
+}
+```
+
+A plugin is a named export that implements this interface. `model` is the decoded `ParsedService` from `@shipworthy/openapi-transformer`, which includes `operations`, `paths`, `webhooks`, `components`, `servers`, `securitySchemes`, and `info` fields such as `name` and `version`. `options` is `GenerateOptions.pluginOptions`. `generate` can return a value or an `Effect`, synchronously or not.
+
+```ts
+import type { Generator } from "@shipworthy/openapi-generator";
+import type { ParsedService } from "@shipworthy/openapi-transformer";
+import { Effect } from "effect";
+
+class RouteError extends Error {}
+
+export const routes: Generator<string, RouteError> = {
+  id: "routes",
+  generate: (model: ParsedService, options) =>
+    Effect.gen(function* () {
+      if (model.operations.length === 0) return yield* Effect.fail(new RouteError("No operations"));
+      const prefix = typeof options.prefix === "string" ? options.prefix : "";
+      return model.operations.map((op) => `${prefix}${op.path}`).join("\n");
+    }),
+};
+```
+
+Type `model` with `ParsedService` and the other `Parsed*` types from `@shipworthy/openapi-transformer`, not with an ad-hoc document type.
+
+### `importPlugin(specifier, exportName)`
+
+```ts
+function importPlugin(
+  specifier: string,
+  exportName: string,
+): Effect.Effect<Generator<unknown>, MissingPlugin | InvalidPlugin>;
+```
+
+Loads `specifier` through `ModuleLoader` and returns `module[exportName]`. `generate` calls it for you. Call it directly to check that a plugin is installed and valid without running the pipeline.
+
+- If the module can't be loaded (the import rejects), it fails with `MissingPlugin`. The message is `Install <specifier> to load <exportName>.` and `cause` is the import error.
+- If the export is missing, doesn't have a function `generate`, or doesn't have a string `id`, it fails with `InvalidPlugin`. The message is `Module <specifier> does not export <exportName>.`
+
+### `ModuleLoader`
+
+```ts
+const ModuleLoader: Context.Reference<{ readonly load: (specifier: string) => Promise<unknown> }>;
+```
+
+The service that imports plugin modules. By default it calls `import(specifier)` from inside this package, so bare specifiers resolve from this package's install location. Override it when plugins must resolve from your project, or to inject a module in tests:
+
+```ts
+import { generate, ModuleLoader } from "@shipworthy/openapi-generator";
+import { Effect } from "effect";
+
+// Resolve plugin specifiers from the calling module (this is what the openapi CLI does).
+generate(options).pipe(
+  Effect.provideService(ModuleLoader, { load: (specifier) => import(specifier) }),
+);
+
+// Inject an in-memory plugin in tests.
+const plugin = { id: "fixture", generate: (model: unknown) => model };
+generate({ specifier: "fixture", exportName: "plugin", source: document }).pipe(
+  Effect.provideService(ModuleLoader, { load: () => Promise.resolve({ plugin }) }),
+);
+```
+
+### Errors
+
+All errors are `Schema.TaggedError` classes. Each one has a `_tag` and a `message`. Handle them with `Effect.catchTag` or `Effect.catchTags`.
+
+| Class (`_tag`)   | Fields                                        | When                                                                                                                                                                                                                                                                                           |
+| ---------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ResolveError`   | `message`, optional `cause`                   | The source couldn't be loaded, parsed, bundled, or validated. Examples: an empty source, unreadable file, failed fetch, invalid JSON/YAML, a non-object document, Swagger 2.0, an OpenAPI version outside 3.x, an unresolvable `$ref`, or a schema violation such as a missing `info.version`. |
+| `TransformError` | `message`, `cause`                            | The bundled document couldn't be decoded into `ParsedService`, or the plugin threw or failed. `cause` is the original error.                                                                                                                                                                   |
+| `MissingPlugin`  | `specifier`, `exportName`, `message`, `cause` | `ModuleLoader.load(specifier)` rejected.                                                                                                                                                                                                                                                       |
+| `InvalidPlugin`  | `specifier`, `exportName`, `message`          | The module loaded, but `exportName` isn't a valid `Generator`.                                                                                                                                                                                                                                 |
+
+Example messages:
+
+```text
+ResolveError    Unsupported Swagger version: 2.x. Use OpenAPI 3.x instead.
+ResolveError    Expected an OpenAPI document object. Got string
+MissingPlugin   Install @shipworthy/openapi-zod to load zod.
+InvalidPlugin   Module example-generator does not export generate.
+```
+
+Defects, such as an `Effect.die` inside a plugin's effect, aren't converted to `TransformError`. They propagate as defects.
+
+## Supported OpenAPI versions
+
+- **OpenAPI 3.1.x:** used as is.
+- **OpenAPI 3.0.x:** upgraded to 3.1 before decoding. The model's `openapi` is `"3.1.0"`. For example, `{ type: "string", nullable: true }` becomes `{ type: ["string", "null"] }`.
+- **Swagger 2.0 and OpenAPI 4+:** rejected with `ResolveError`.
+
+## Related packages
+
+| Package                           | Relation                                                                                                  |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@shipworthy/openapi-cli`         | The `openapi generate …` commands, which call `generate`.                                                 |
+| `@shipworthy/openapi-parser`      | Loads and bundles the source (step 1).                                                                    |
+| `@shipworthy/openapi-transformer` | Defines `ParsedService` and decodes into it (step 2). Import model types from it when you write a plugin. |
+| `@shipworthy/openapi-typescript`  | Plugin, export `typescript`.                                                                              |
+| `@shipworthy/openapi-zod`         | Plugin, export `zod`.                                                                                     |
+
+## Troubleshooting
+
+- **Type error or runtime failure about missing `FileSystem`, `Path`, or `HttpClient` services**: Provide `Layer.mergeAll(NodeServices.layer, FetchHttpClient.layer)`, or use `BunServices.layer` on Bun.
+- **`ResolveError: Expected an OpenAPI document object. Got string`**: You passed a file path string. Pass a `URL` instead.
+- **`MissingPlugin` for a plugin that is installed**: The default loader resolves specifiers from this package's location. Pass an absolute `file://` URL, or provide `ModuleLoader` with `{ load: (s) => import(s) }` from your own module.
+- **`InvalidPlugin`**: Check `exportName`. It must be a named export, not `default`, and the object must have both `id` and a `generate` function.
+- **Relative `$ref`s fail for inline sources**: Set `cwd` to the directory that the refs are relative to.
+
+## Key facts (for AI agents)
+
+- Entry point: `import { generate, importPlugin, ModuleLoader, ResolveError, TransformError, MissingPlugin, InvalidPlugin, type Generator, type GenerateOptions, type GenerateError } from "@shipworthy/openapi-generator"`.
+- `generate({ specifier, exportName, source, cwd?, pluginOptions? })` returns `Effect<unknown, GenerateError, FileSystem | Path | HttpClient>`. It's not a Promise. Run it with `Effect.runPromise` after providing `NodeServices.layer` (or `BunServices.layer`) and `FetchHttpClient.layer`.
+- Requires `effect` `^4.0.0` (peer dependency). ESM only, compiled JavaScript. Runs on Node.js `>=22.19.0` or Bun.
+- Pipeline: bundle (`ResolveError`), then decode to `ParsedService` (`TransformError`), then import the plugin (`MissingPlugin` / `InvalidPlugin`), then `plugin.generate(model, pluginOptions ?? {})` (plugin failures become `TransformError`).
+- File-path strings are parsed as YAML text. Pass `URL` objects for files. Strings starting with `http(s)://` or `file://` are fetched or read.
+- OpenAPI 3.0 is upgraded to 3.1. Swagger 2.0 is rejected.
+- A plugin is a named export `{ id: string, generate(model: ParsedService, options) => A | Effect<A, E> }`.
+- Override `ModuleLoader` with `Effect.provideService(ModuleLoader, { load })` to control plugin resolution or inject test plugins.
+- The return value is `unknown`. Validate or cast it to the plugin's output type.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+import { Schema } from "effect";
+declare const ResolveError_base: Schema.Class<ResolveError, Schema.TaggedStruct<"ResolveError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class ResolveError extends ResolveError_base {
+}
+declare const TransformError_base: Schema.Class<TransformError, Schema.TaggedStruct<"TransformError", {
+    readonly message: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class TransformError extends TransformError_base {
+}
+declare const MissingPlugin_base: Schema.Class<MissingPlugin, Schema.TaggedStruct<"MissingPlugin", {
+    readonly specifier: Schema.String;
+    readonly exportName: Schema.String;
+    readonly message: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class MissingPlugin extends MissingPlugin_base {
+}
+declare const InvalidPlugin_base: Schema.Class<InvalidPlugin, Schema.TaggedStruct<"InvalidPlugin", {
+    readonly specifier: Schema.String;
+    readonly exportName: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidPlugin extends InvalidPlugin_base {
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+export class ResolveError extends Schema.TaggedError()("ResolveError", {
+    message: Schema.String,
+    cause: Schema.optionalKey(Schema.Defect()),
+}) {
+}
+export class TransformError extends Schema.TaggedError()("TransformError", {
+    message: Schema.String,
+    cause: Schema.Defect(),
+}) {
+}
+export class MissingPlugin extends Schema.TaggedError()("MissingPlugin", {
+    specifier: Schema.String,
+    exportName: Schema.String,
+    message: Schema.String,
+    cause: Schema.Defect(),
+}) {
+}
+export class InvalidPlugin extends Schema.TaggedError()("InvalidPlugin", {
+    specifier: Schema.String,
+    exportName: Schema.String,
+    message: Schema.String,
+}) {
+}

package/dist/generate.d.ts

@@ -0,0 +1,14 @@
+import { Effect, FileSystem, Path } from "effect";
+import { HttpClient } from "effect/http";
+import { ResolveError, TransformError, type InvalidPlugin, type MissingPlugin } from "./errors.ts";
+export interface GenerateOptions {
+    readonly specifier: string;
+    readonly exportName: string;
+    readonly source: unknown;
+    readonly cwd?: URL | string;
+    readonly pluginOptions?: Readonly<Record<string, unknown>>;
+}
+type GenerateServices = FileSystem.FileSystem | Path.Path | HttpClient.HttpClient;
+export declare const generate: (options: GenerateOptions) => Effect.Effect<unknown, GenerateError, GenerateServices>;
+export type GenerateError = ResolveError | TransformError | MissingPlugin | InvalidPlugin;
+export {};

package/dist/generate.js

@@ -0,0 +1,29 @@
+import { bundleDocument } from "@shipworthy/openapi-parser";
+import { decode } from "@shipworthy/openapi-transformer";
+import { Effect, Predicate } from "effect";
+import { ResolveError, TransformError } from "./errors.js";
+import { importPlugin } from "./plugins.js";
+export const generate = Effect.fn("generate")(function* (options) {
+    const document = yield* bundleDocument(options.source, { cwd: options.cwd }).pipe(Effect.mapError((cause) => new ResolveError({ message: cause.message, cause })));
+    const model = yield* decode(document).pipe(Effect.mapError((cause) => new TransformError({ message: cause.message, cause })));
+    const plugin = yield* importPlugin(options.specifier, options.exportName);
+    return yield* render(plugin, model, options.pluginOptions ?? {});
+});
+function failureMessage(cause) {
+    return Predicate.isError(cause) ? cause.message : String(cause);
+}
+function pluginFailure(cause) {
+    return new TransformError({ message: failureMessage(cause), cause });
+}
+function isPluginEffect(value) {
+    return Effect.isEffect(value);
+}
+const render = Effect.fnUntraced(function* (plugin, model, options) {
+    const value = yield* Effect.try({
+        try: () => plugin.generate(model, options),
+        catch: pluginFailure,
+    });
+    if (!isPluginEffect(value))
+        return value;
+    return yield* Effect.mapError(value, pluginFailure);
+});

package/dist/generator.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedService } from "@shipworthy/openapi-transformer";
+import type { Effect } from "effect";
+export interface Generator<A, E = never> {
+    readonly id: string;
+    generate(model: ParsedService, options: Readonly<Record<string, unknown>>): A | Effect.Effect<A, E>;
+}

package/dist/generator.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { InvalidPlugin, MissingPlugin, ResolveError, TransformError } from "./errors.ts";
+export { generate, type GenerateError, type GenerateOptions } from "./generate.ts";
+export { type Generator } from "./generator.ts";
+export { importPlugin, ModuleLoader } from "./plugins.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { InvalidPlugin, MissingPlugin, ResolveError, TransformError } from "./errors.js";
+export { generate } from "./generate.js";
+export { importPlugin, ModuleLoader } from "./plugins.js";

package/dist/plugins.d.ts

@@ -0,0 +1,7 @@
+import type { Generator } from "./generator.ts";
+import { Context, Effect } from "effect";
+import { InvalidPlugin, MissingPlugin } from "./errors.ts";
+export declare const ModuleLoader: Context.Reference<{
+    readonly load: (specifier: string) => Promise<unknown>;
+}>;
+export declare const importPlugin: (specifier: string, exportName: string) => Effect.Effect<Generator<unknown, never>, InvalidPlugin | MissingPlugin, never>;

package/dist/plugins.js

@@ -0,0 +1,51 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { Context, Effect, Predicate, Schema } from "effect";
+import { InvalidPlugin, MissingPlugin } from "./errors.js";
+export const ModuleLoader = Context.Reference("@shipworthy/openapi-generator/plugins/ModuleLoader", {
+    defaultValue: () => ({ load: (specifier) => import(__rewriteRelativeImportExtension(specifier)) }),
+});
+const generatorShape = Schema.Struct({
+    id: Schema.String,
+    generate: Schema.declare((value) => Predicate.isFunction(value)),
+});
+// Keep plugin identity and prototype methods while validating its callable interface.
+const generatorSchema = Schema.declare(Schema.is(generatorShape));
+const moduleSchema = Schema.Record(Schema.String, Schema.Unknown);
+/** Whether `cause` reports `specifier`'s own package as missing, not one of its imports. */
+function isPackageNotFound(cause, specifier) {
+    if (!Predicate.isError(cause) || !Predicate.hasProperty(cause, "code"))
+        return false;
+    if (cause.code !== "ERR_MODULE_NOT_FOUND" && cause.code !== "MODULE_NOT_FOUND")
+        return false;
+    const [scope = "", name = ""] = specifier.split("/");
+    const packageName = scope.startsWith("@") ? `${scope}/${name}` : scope;
+    return cause.message.includes(`'${packageName}'`);
+}
+export const importPlugin = Effect.fn("importPlugin")(function* (specifier, exportName) {
+    const loader = yield* ModuleLoader;
+    const loaded = yield* Effect.tryPromise({
+        try: () => loader.load(specifier),
+        catch: (cause) => new MissingPlugin({
+            specifier,
+            exportName,
+            message: isPackageNotFound(cause, specifier)
+                ? `Install ${specifier} to load ${exportName}.`
+                : `Could not load ${specifier}: ${Predicate.isError(cause) ? cause.message : String(cause)}`,
+            cause,
+        }),
+    });
+    const invalid = () => new InvalidPlugin({
+        specifier,
+        exportName,
+        message: `Module ${specifier} does not export ${exportName}.`,
+    });
+    const module = yield* Schema.decodeUnknownEffect(moduleSchema)(loaded).pipe(Effect.mapError(invalid));
+    return yield* Schema.decodeUnknownEffect(generatorSchema)(module[exportName]).pipe(Effect.mapError(invalid));
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@shipworthy/openapi-generator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@shipworthy/openapi-parser": "0.0.1",
+    "@shipworthy/openapi-transformer": "0.0.1"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "description": "Load, resolve, and parse an OpenAPI document, then run one generator plugin.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipWorthyAI/openapi.git",
+    "directory": "packages/openapi-generator"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0",
+    "@shipworthy/typescript-config": "0.0.1",
+    "@types/node": "^24.10.3",
+    "effect": "^4.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "5.0.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}