@distilled.cloud/core 0.30.3 → 1.0.0-rc.2

package/lib/api.d.ts

@@ -0,0 +1,165 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as S from "effect/Schema";
+import type * as AST from "effect/SchemaAST";
+import type * as Stream from "effect/Stream";
+import * as Pagination from "./pagination.ts";
+import { type Policy as RetryPolicy } from "./retry.ts";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
+import type * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
+/**
+ * The view of an operation's config that protocols receive on every
+ * encode/decode call. The object is the same memoized config instance for
+ * every call to a given operation, so protocols can key per-operation
+ * preprocessing (handler construction, error maps) off its identity in a
+ * WeakMap.
+ */
+export interface ProtocolOperationConfig {
+    readonly input?: S.Top;
+    readonly output?: S.Top;
+    readonly errors?: ReadonlyArray<ApiErrorClass>;
+    /**
+     * The wire operation name (e.g. the Smithy operation shape name). RPC-style
+     * protocols address operations by name (AWS JSON's `X-Amz-Target`, AWS
+     * Query's `Action=`) and unwrap responses by it; REST protocols ignore it.
+     */
+    readonly operationName?: string;
+    /**
+     * The smithy `smithy.api#endpoint` hostPrefix (e.g. `sync-` for Step
+     * Functions' StartSyncExecution). Protocols prepend it to the resolved
+     * endpoint host, substituting `{memberName}` labels from the input.
+     */
+    readonly endpointHostPrefix?: string;
+    readonly pagination?: Pagination.PaginatedTrait;
+}
+declare const Protocol_base: Context.ServiceClass<Protocol, "Protocol", {
+    readonly encode: (args: {
+        readonly input: unknown;
+        readonly inputAst: AST.AST;
+        /** The operation's config (memoized per operation — see {@link ProtocolOperationConfig}). */
+        readonly config: ProtocolOperationConfig;
+    }) => Effect.Effect<HttpClientRequest.HttpClientRequest>;
+    readonly decode: (args: {
+        readonly response: HttpClientResponse.HttpClientResponse;
+        readonly outputAst: AST.AST;
+        /**
+         * The operation's declared error classes (from `OperationConfig.errors`).
+         * Protocols use these to surface wire failures as the operation's typed
+         * errors — e.g. by consulting matcher metadata stamped on the class.
+         */
+        readonly errors: ReadonlyArray<ApiErrorClass>;
+        /** The operation's config (memoized per operation — see {@link ProtocolOperationConfig}). */
+        readonly config: ProtocolOperationConfig;
+    }) => Effect.Effect<unknown>;
+}>;
+/**
+ * The Protocol service knows how to turn a value into an HTTP request using
+ * only the input schema's trait annotations, and how to turn a response back
+ * into an output value using the output schema's trait annotations.
+ *
+ * Swap implementations by providing a different `Layer<Protocol>`.
+ */
+export declare class Protocol extends Protocol_base {
+}
+export type ApiErrorClass = {
+    new (...args: any[]): {
+        readonly _tag: string;
+        readonly message: string;
+    };
+};
+/**
+ * The shape of a generated SDK operation — usable two ways (mirrors the
+ * distilled repo's OperationMethod):
+ *
+ * 1. Direct call: `yield* operation(input)` — an Effect with requirements.
+ * 2. Yield first: `const fn = yield* operation` — captures the current
+ *    context and returns a requirement-free call function.
+ *
+ * Generated service files annotate every exported operation with this type
+ * explicitly (against their hand-emitted interfaces), so the compiler never
+ * has to infer it back out of the schema generics.
+ */
+export type OperationMethod<I, O, E, R> = Effect.Effect<(input: I) => Effect.Effect<O, E, never>, never, R> & ((input: I) => Effect.Effect<O, E, R>);
+export interface OperationConfig<I extends S.Top, O extends S.Top, PE, PR, E extends readonly ApiErrorClass[] = readonly ApiErrorClass[]> {
+    input?: I;
+    output?: O;
+    errors?: E;
+    /**
+     * The protocol layer that knows how to encode/decode this operation's wire
+     * format. Built once per process and shared across all operations that
+     * reference the same layer value — it must resolve call-dependent services
+     * (credentials etc.) inside encode/decode, not at build time.
+     */
+    protocol: Layer.Layer<Protocol, PE, PR>;
+    /**
+     * SDK-specific retry service tag (see `core/retry`). When provided and the
+     * caller's context carries a policy under this tag, every call is retried
+     * per that policy (e.g. `Layer.succeed(Cloudflare.Retry.Retry, factory)`).
+     */
+    retry?: Context.Key<any, RetryPolicy>;
+    /**
+     * The wire operation name for RPC-style protocols (see
+     * {@link ProtocolOperationConfig.operationName}).
+     */
+    operationName?: string;
+    /**
+     * Host prefix from the smithy endpoint trait (see
+     * {@link ProtocolOperationConfig.endpointHostPrefix}).
+     */
+    endpointHostPrefix?: string;
+}
+export declare function make<I extends S.Top, O extends S.Top, PE, PR, const E extends readonly ApiErrorClass[] = readonly []>(configFn: () => OperationConfig<I, O, PE, PR, E>): OperationMethod<S.Schema.Type<I>, S.Schema.Type<O>, InstanceType<E[number]> | PE | HttpClientError.HttpClientError, PR | HttpClient.HttpClient>;
+/**
+ * STRUCTURAL fallback for the element type `.items()` yields: the array
+ * element of the page response itself, or of its `result` member.
+ *
+ * It can only see shapes it was taught, so any other envelope
+ * (`{ branches: […] }`, `{ data: […] }`, …) lands on `unknown` — which is
+ * why generators pass the item type EXPLICITLY as
+ * {@link PaginatedOperationMethod}'s `Item` argument, resolved from the
+ * pagination trait's `items` path against the response shape. This default
+ * only applies to hand-written operations.
+ */
+export type PaginatedItem<A> = A extends ReadonlyArray<infer Item> ? Item : A extends {
+    result: ReadonlyArray<infer Item>;
+} ? Item : A extends {
+    result?: ReadonlyArray<infer Item> | null | undefined;
+} ? Item : unknown;
+/**
+ * The callable half of a paginated operation: the operation call itself, plus
+ * `.pages(input)` streaming every page response and `.items(input)` streaming
+ * the individual items across pages.
+ *
+ * Used twice in {@link PaginatedOperationMethod} — once with the operation's
+ * requirements (`R`) for the direct-call style, once with `R = never` for the
+ * value `yield* operation` hands back, which has the caller's context baked in.
+ */
+export interface PaginatedCall<I, O, E, R, Item> {
+    (input: I): Effect.Effect<O, E, R>;
+    readonly pages: (input: I) => Stream.Stream<O, E, R>;
+    readonly items: (input: I) => Stream.Stream<Item, E, R>;
+}
+/**
+ * A paginated operation: usable both ways an {@link OperationMethod} is, with
+ * `.pages` / `.items` on BOTH — the operation object for
+ * `yield* op.items(input)`, and the requirement-free call function for
+ * `const op = yield* operation; yield* op.items(input)` (distilled #145).
+ */
+export type PaginatedOperationMethod<I, O, E, R, Item = PaginatedItem<O>> = Effect.Effect<PaginatedCall<I, O, E, never, Item>, never, R> & PaginatedCall<I, O, E, R, Item>;
+export interface PaginatedOperationConfig<I extends S.Top, O extends S.Top, PE, PR, E extends readonly ApiErrorClass[] = readonly ApiErrorClass[]> extends OperationConfig<I, O, PE, PR, E> {
+    /** How to advance between pages (mirrors the `smithy.api#paginated` trait). */
+    pagination: Pagination.PaginatedTrait;
+}
+/**
+ * Like {@link make}, plus `.pages()` / `.items()` streaming built on the
+ * operation's pagination trait. The SDK can pass a provider-specific
+ * {@link Pagination.PaginationStrategy} (e.g. Cloudflare stops page-mode
+ * traversal on the first empty page); the default dispatches on
+ * `pagination.mode`.
+ */
+export declare function makePaginated<I extends S.Top, O extends S.Top, PE, PR, const E extends readonly ApiErrorClass[] = readonly []>(configFn: () => PaginatedOperationConfig<I, O, PE, PR, E>, strategy?: Pagination.PaginationStrategy): PaginatedOperationMethod<S.Schema.Type<I>, S.Schema.Type<O>, InstanceType<E[number]> | PE | HttpClientError.HttpClientError, PR | HttpClient.HttpClient>;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/lib/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/lib/api.js

@@ -0,0 +1,178 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as S from "effect/Schema";
+import { pipeArguments } from "effect/Pipeable";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import { SingleShotGen } from "effect/Utils";
+import * as Pagination from "./pagination.js";
+import { makeDefault } from "./retry.js";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+/**
+ * The Protocol service knows how to turn a value into an HTTP request using
+ * only the input schema's trait annotations, and how to turn a response back
+ * into an output value using the output schema's trait annotations.
+ *
+ * Swap implementations by providing a different `Layer<Protocol>`.
+ */
+export class Protocol extends Context.Service()("Protocol") {
+}
+// NOTE: request/response ASTs are handed to the protocol RAW (Suspend nodes
+// included). Pre-resolving Suspends here would drop annotations that sit on
+// intermediate nodes — e.g. a bare-payload response whose payload type is
+// itself a suspended schema carries its EnvelopePayloadRoot marker on the
+// inner Suspend, and unwrapping it silently degrades decode to the struct
+// path. The protocol helpers (core/protocol-http getAnn/getProps) descend
+// Suspends themselves, and `Suspend.thunk` memoizes, so raw ASTs cost
+// nothing extra.
+/**
+ * Protocol layers are built once per process and shared by every operation
+ * call (keyed by layer value identity — generated operations all reference the
+ * same module-level layer const). The build runs against a process-lifetime
+ * scope, and concurrent first calls are deduplicated through a private
+ * MemoMap.
+ *
+ * Contract for protocol implementations: the layer build must not capture
+ * per-call context. Anything call-dependent — credentials, per-request
+ * options — must be resolved inside `encode`/`decode`, which execute on the
+ * calling fiber and therefore see the caller's services on every request.
+ */
+const protocolMemoMap = Layer.makeMemoMapUnsafe();
+const protocolScope = Scope.makeUnsafe();
+const protocolContexts = new WeakMap();
+const protocolContext = (layer) => {
+    const cached = protocolContexts.get(layer);
+    if (cached)
+        return Effect.succeed(cached);
+    return Effect.map(Layer.buildWithMemoMap(layer, protocolMemoMap, protocolScope), (ctx) => {
+        protocolContexts.set(layer, ctx);
+        return ctx;
+    });
+};
+/**
+ * Wrap one operation call with the caller-provided retry policy, if the
+ * operation declares a retry tag and the context carries a policy for it.
+ */
+const applyRetry = (base, retryKey) => retryKey === undefined
+    ? base
+    : Effect.flatMap(Effect.serviceOption(retryKey), (opt) => Effect.gen(function* () {
+        const lastError = yield* Ref.make(undefined);
+        // No policy in context → makeDefault (transient/throttling/server
+        // errors, capped exponential backoff + jitter, honors server
+        // retryAfter hints). Mirrors the distilled client.
+        const policy = Option.isSome(opt) ? opt.value : makeDefault;
+        const opts = typeof policy === "function" ? policy(lastError) : policy;
+        if (!opts.while)
+            return yield* base;
+        return yield* base.pipe(Effect.tapError((e) => Ref.set(lastError, e)), Effect.retry({
+            while: (e) => opts.while(e),
+            ...(opts.schedule ? { schedule: opts.schedule } : {}),
+        }));
+    }));
+export function make(configFn) {
+    let prepared;
+    const prepare = () => {
+        if (prepared)
+            return prepared;
+        const cfg = configFn();
+        prepared = {
+            cfg,
+            inputAst: cfg.input.ast,
+            outputAst: cfg.output.ast,
+        };
+        return prepared;
+    };
+    const fn = (input) => Effect.suspend(() => {
+        const { cfg, inputAst, outputAst } = prepare();
+        const call = Effect.flatMap(protocolContext(cfg.protocol), (protocolCtx) => Effect.gen(function* () {
+            const protocol = yield* Protocol;
+            const client = yield* HttpClient.HttpClient;
+            const request = yield* protocol.encode({
+                input,
+                inputAst,
+                config: cfg,
+            });
+            const response = yield* client.execute(request);
+            return yield* protocol.decode({
+                response,
+                outputAst,
+                errors: cfg.errors ?? [],
+                config: cfg,
+            });
+        }).pipe(Effect.provideContext(protocolCtx)));
+        return applyRetry(call, cfg.retry);
+    });
+    // Make the operation itself yieldable: `yield* operation` captures the
+    // current context and returns a requirement-free call function (mirrors
+    // the distilled repo's OperationMethod).
+    const Proto = {
+        [Symbol.iterator]() {
+            return new SingleShotGen(this.asEffect());
+        },
+        pipe() {
+            return pipeArguments(this.asEffect(), arguments);
+        },
+        asEffect() {
+            return Effect.map(Effect.context(), (context) => (input) => Effect.provideContext(fn(input), context));
+        },
+    };
+    Object.assign(fn, Proto);
+    // Debug/introspection surface carried over from the distilled client:
+    // the operation's metadata is readable off the exported callable
+    // (e.g. `iam.listRoles.input` / `.output` / `.errors` / `.operationName`
+    // / `.pagination`). Lazy getters, so importing a service module doesn't
+    // force its suspended schemas.
+    Object.defineProperties(fn, {
+        input: { get: () => prepare().cfg.input, configurable: true },
+        output: { get: () => prepare().cfg.output, configurable: true },
+        errors: { get: () => prepare().cfg.errors ?? [], configurable: true },
+        operationName: {
+            get: () => prepare().cfg.operationName,
+            configurable: true,
+        },
+        pagination: {
+            get: () => prepare().cfg.pagination,
+            configurable: true,
+        },
+    });
+    return fn;
+}
+/**
+ * Like {@link make}, plus `.pages()` / `.items()` streaming built on the
+ * operation's pagination trait. The SDK can pass a provider-specific
+ * {@link Pagination.PaginationStrategy} (e.g. Cloudflare stops page-mode
+ * traversal on the first empty page); the default dispatches on
+ * `pagination.mode`.
+ */
+export function makePaginated(configFn, strategy) {
+    const fn = make(configFn);
+    // configFn is a cheap object literal over already-constructed consts —
+    // re-invoking it here just reads the pagination trait (memoized).
+    let pagination;
+    const pag = () => (pagination ??= configFn().pagination);
+    const paginate = strategy ?? Pagination.paginateWithDefaults;
+    // The streams are built over a CALL FUNCTION, so the same code serves both
+    // call styles: the operation itself (requirements intact), and the
+    // context-bound function `yield* operation` hands back — whose streams
+    // inherit that captured context and so need nothing after the yield.
+    const withStreams = (call) => {
+        const pages = (input) => paginate(call, input, pag());
+        const items = (input) => {
+            const p = pag();
+            return p.items
+                ? Pagination.extractItems(pages(input), p.items)
+                : pages(input);
+        };
+        return Object.assign(call, { pages, items });
+    };
+    // `yield* operation` runs through `make`'s Proto.asEffect, which builds a
+    // fresh arrow and would drop `.pages` / `.items` (distilled #145). Override
+    // it here — Proto's `[Symbol.iterator]`/`pipe` dispatch on `this`, so both
+    // pick this up. Only paginated operations pay for it.
+    fn.asEffect = () => Effect.map(Effect.context(), (context) => withStreams((input) => Effect.provideContext(fn(input), context)));
+    return withStreams(fn);
+}
+//#endregion
+//# sourceMappingURL=api.js.map

package/lib/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/lib/codegen/cli.d.ts

@@ -0,0 +1,29 @@
+import { type SdkSpec } from "./generator.ts";
+export interface GeneratorCliOptions {
+    /** Command description shown in --help. */
+    readonly description: string;
+    /** Absolute package root (usually `path.resolve(import.meta.dir, "..")`). */
+    readonly root: string;
+    /** Model directory default (relative to root). Default `.generated-specs`. */
+    readonly smithyDir?: string;
+    /** Output directory default (relative to root). Default `src/services`. */
+    readonly outDir?: string;
+    /** Model files to skip (e.g. a shared protocols model). */
+    readonly excludeModel?: (file: string) => boolean;
+    /** Directory of hand-authored models merged after the generated ones. */
+    readonly manualSpecsDir?: string;
+    /** RFC-6902 patch chain root. Default `patches`; `false` disables. */
+    readonly patchesDir?: string | false;
+    /**
+     * Model transform applied AFTER the patch chain, before generation —
+     * for whole-model rewrites that must see post-patch shape names (e.g.
+     * cloudflare's scope-twin structural dedup). May mutate the model;
+     * a returned log line is printed.
+     */
+    readonly transformModel?: (model: any, resource: string) => string | void;
+    /** The provider spec — built per model (metadata may vary per model). */
+    readonly spec: (model: any) => SdkSpec;
+}
+/** Run the generator CLI (BunRuntime main — call at module top level). */
+export declare const runGeneratorCli: (options: GeneratorCliOptions) => void;
+//# sourceMappingURL=cli.d.ts.map

package/lib/codegen/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/codegen/cli.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAClD,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACrC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC1E,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;CACxC;AAED,0EAA0E;AAC1E,eAAO,MAAM,eAAe,YAAa,mBAAmB,KAAG,IAoN9D,CAAC"}

package/lib/codegen/cli.js

@@ -0,0 +1,165 @@
+/**
+ * The generic generator CLI harness (dev-time only).
+ *
+ * Owns the smithy-model pipeline every SDK package shares: scan the model
+ * directory (plus optional hand-authored manual specs), apply the RFC-6902
+ * patch chain (`patches/<resource>/*.json`, `*.manual.json` last; stale
+ * targets warn, malformed patches fail the run), compile each model through
+ * {@link generateService} with the provider's {@link SdkSpec}, write the
+ * service modules and the namespaced barrel.
+ *
+ * A provider's `scripts/generate.ts` is: trait consts + an SdkSpec + a
+ * `runGeneratorCli` call.
+ */
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Console, Effect } from "effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import { Flag } from "effect/unstable/cli";
+import { Command } from "effect/unstable/cli";
+import { applyOperation, isStaleTargetError, } from "../json-patch.js";
+import { barrel } from "./emit.js";
+import { formatGenerated } from "./format.js";
+import { generateService } from "./generator.js";
+/** Run the generator CLI (BunRuntime main — call at module top level). */
+export const runGeneratorCli = (options) => {
+    const command = Command.make("generate", {
+        smithy: Flag.string("smithy").pipe(Flag.withDefault(options.smithyDir ?? ".generated-specs"), Flag.withDescription("Directory of Smithy JSON models")),
+        out: Flag.string("out").pipe(Flag.withDefault(options.outDir ?? "src/services"), Flag.withDescription("Output directory for generated service modules")),
+        resource: Flag.string("resource").pipe(Flag.withDefault(""), Flag.withDescription("Only generate this resource (e.g. ai)")),
+    }, (config) => Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = options.root;
+        const smithyDir = path.resolve(root, config.smithy);
+        const outDir = path.resolve(root, config.out);
+        yield* Console.log("⚙️  generate");
+        yield* Console.log(`   Smithy: ${smithyDir}`);
+        yield* Console.log(`   Output: ${outDir}`);
+        // Generated models plus optional manual-specs (hand-authored models
+        // for APIs the provider's spec source doesn't cover). A manual model
+        // must not shadow a generated one.
+        const generated = (yield* fs.readDirectory(smithyDir))
+            .filter((f) => f.endsWith(".json") && !(options.excludeModel?.(f) ?? false))
+            .map((f) => ({ file: f, dir: smithyDir }));
+        const manualDir = options.manualSpecsDir
+            ? path.resolve(root, options.manualSpecsDir)
+            : undefined;
+        const manual = manualDir && (yield* fs.exists(manualDir))
+            ? (yield* fs.readDirectory(manualDir))
+                .filter((f) => f.endsWith(".json"))
+                .map((f) => ({ file: f, dir: manualDir }))
+            : [];
+        for (const m of manual) {
+            if (generated.some((g) => g.file === m.file)) {
+                return yield* Effect.die(new Error(`${options.manualSpecsDir}/${m.file} shadows a generated model — rename or delete it`));
+            }
+        }
+        const entries = [...generated, ...manual].sort((a, b) => a.file.localeCompare(b.file));
+        yield* fs.makeDirectory(outDir, { recursive: true });
+        const written = [];
+        let totalOps = 0;
+        let totalPatches = 0;
+        let staleOps = 0;
+        const badPatches = [];
+        // Orphan check: a patch directory matching no smithy model would be
+        // silently dropped — flag it instead.
+        const patchRoot = options.patchesDir === false
+            ? undefined
+            : path.join(root, options.patchesDir ?? "patches");
+        if (patchRoot && (yield* fs.exists(patchRoot))) {
+            const resources = new Set(entries.map((e) => e.file.replace(/\.json$/, "")));
+            for (const dir of yield* fs.readDirectory(patchRoot)) {
+                if (!resources.has(dir)) {
+                    yield* Console.warn(`⚠️  patches/${dir}/ matches no smithy model — orphaned?`);
+                }
+            }
+        }
+        for (const { file, dir } of entries) {
+            const resource = file.replace(/\.json$/, "");
+            if (config.resource && resource !== config.resource)
+                continue;
+            const model = JSON.parse(yield* fs.readFileString(path.join(dir, file)));
+            // Apply the RFC-6902 patch chain before generating. Hand-written
+            // *.manual.json patches apply after the generated ones — they
+            // usually target post-rename shape names.
+            const patchDir = patchRoot && path.join(patchRoot, resource);
+            if (patchDir && (yield* fs.exists(patchDir))) {
+                const patchFiles = (yield* fs.readDirectory(patchDir))
+                    .filter((f) => f.endsWith(".json"))
+                    .sort((a, b) => Number(a.endsWith(".manual.json")) -
+                    Number(b.endsWith(".manual.json")) || a.localeCompare(b));
+                for (const pf of patchFiles) {
+                    const parsed = JSON.parse(yield* fs.readFileString(path.join(patchDir, pf)));
+                    for (const patchOp of parsed.patches ?? []) {
+                        try {
+                            applyOperation(model, patchOp);
+                        }
+                        catch (e) {
+                            const msg = e instanceof Error ? e.message : String(e);
+                            if (isStaleTargetError(msg)) {
+                                staleOps++;
+                                yield* Console.warn(`   ⚠️  stale: ${resource}/${pf} [${patchOp.op} ${patchOp.path}]`);
+                            }
+                            else {
+                                badPatches.push(`${resource}/${pf} [${patchOp.op} ${patchOp.path}]: ${msg}`);
+                            }
+                        }
+                    }
+                    totalPatches++;
+                }
+            }
+            if (options.transformModel) {
+                const note = options.transformModel(model, resource);
+                if (note)
+                    yield* Console.log(`   ${note}`);
+            }
+            const { code, operations } = generateService(model, options.spec(model));
+            if (operations === 0)
+                continue;
+            yield* fs.writeFileString(path.join(outDir, `${resource}.ts`), code);
+            written.push(resource);
+            totalOps += operations;
+        }
+        if (badPatches.length) {
+            for (const b of badPatches) {
+                yield* Console.error(`❌ bad patch: ${b}`);
+            }
+            return yield* Effect.die(new Error(`${badPatches.length} malformed patch operation(s) — fix or remove them`));
+        }
+        // Barrel — namespace per resource to avoid op-name collisions.
+        //
+        // A FULL run is authoritative: the barrel is exactly what was
+        // generated, so a resource whose model went away drops out of it.
+        //
+        // A `--resource` run only knows about the resource it generated, so
+        // rewriting the barrel from that would delete every other export —
+        // which is how #397 shipped a cloudflare barrel exporting `workers`
+        // and nothing else, silently dropping 119 services. Merge into the
+        // existing barrel instead, so `--resource` can still ADD a brand-new
+        // resource without removing anything.
+        const barrelPath = path.join(outDir, "index.ts");
+        const filtered = config.resource !== "";
+        let resources = written;
+        if (filtered && (yield* fs.exists(barrelPath))) {
+            const existing = (yield* fs.readFileString(barrelPath))
+                .split("\n")
+                .map((line) => /^export \* as (\S+) from/.exec(line)?.[1])
+                .filter((name) => name !== undefined);
+            // Ordered exactly as a full run orders it: by MODEL FILENAME, so
+            // the `.json` takes part in the collation (`ai_gateway.json` sorts
+            // before `ai.json`, where the bare names sort the other way).
+            // Otherwise a filtered run reshuffles the barrel into diff noise.
+            resources = [...new Set([...existing, ...written])].sort((a, b) => `${a}.json`.localeCompare(`${b}.json`));
+        }
+        yield* fs.writeFileString(barrelPath, barrel(`// AUTO-GENERATED by scripts/generate.ts. Do not edit.\n`, resources.map((r) => ({ name: r, path: `./${r}.ts` }))));
+        yield* formatGenerated(outDir);
+        yield* Console.log(`\n✅ Generated ${totalOps} operations across ${written.length} resource modules` +
+            (totalPatches
+                ? ` (${totalPatches} patch files applied${staleOps ? `, ${staleOps} stale op(s) skipped` : ""}).`
+                : "."));
+        yield* Console.log(`   ${path.join(outDir, "index.ts")}`);
+    })).pipe(Command.withDescription(options.description));
+    BunRuntime.runMain(Effect.provide(Command.run(command, { version: "1.0.0" }), BunServices.layer));
+};
+//# sourceMappingURL=cli.js.map

package/lib/codegen/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/codegen/cli.ts"],"names":[],"mappings":"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"}