@beignet/cli 0.0.37 → 0.0.39

package/src/provider-add.ts

@@ -1,9 +1,9 @@
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
-  type IntegrationName,
   type ProviderPresetName,
   providerPresetChoices,
+  type StarterProviderName,
 } from "./choices.js";
 import {
   directoryPath,
@@ -72,6 +72,18 @@ type PlannedFile = {
   result: "created" | "updated" | "skipped";
 };
 
+type ProviderPlanFile = {
+  path: string;
+  content: string;
+};
+
+type ProviderSourceReader = (filePath: string) => Promise<string | undefined>;
+
+export type CreateProviderPresetPlan = {
+  files: ProviderPlanFile[];
+  presets: AddProviderPresetResult[];
+};
+
 const presets: Record<ProviderPresetName, ProviderPreset> = {
   "flags-openfeature": {
     name: "flags-openfeature",
@@ -97,7 +109,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-flags-openfeature`",
       "- Peer dependency: `@openfeature/server-sdk`",
-      "- The preset wires `createOpenFeatureFlagsProvider()` in `server/providers.ts` and defers `flags` in `infra/app-ports.ts`.",
+      "- The preset wires `createOpenFeatureFlagsProvider()` in `server/providers.ts` and defers `flags` in `infra/port-wiring.ts`.",
       "- Configure the OpenFeature provider globally or replace this preset with `createOpenFeatureFlagsProvider(...)` when the app needs provider-specific setup.",
       "- Use `ctx.ports.flags` in app code; `ctx.ports.openFeature` is available as an escape hatch.",
       "",
@@ -105,7 +117,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Configure an OpenFeature provider before relying on non-default flag values.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
   "jobs-bullmq": {
@@ -138,7 +150,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-jobs-bullmq`",
       "- Peer dependency: `bullmq`",
-      "- The preset wires `createBullMQJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/app-ports.ts`.",
+      "- The preset wires `createBullMQJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/port-wiring.ts`.",
       "- Set `BULLMQ_REDIS_URL` before booting the app; the default points at local Redis.",
       "- Dispatching enqueues jobs, but nothing executes them until a worker entrypoint runs `createBullMQJobWorker(...)` in a worker process. See the jobs docs page.",
       "- Use `ctx.ports.jobs.dispatch(...)` in app code; `ctx.ports.bullMQJobs` is available as an escape hatch.",
@@ -148,7 +160,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Run your package manager install command.",
       "Set BULLMQ_REDIS_URL in .env.local or your deployment environment.",
       "Add a worker entrypoint that runs createBullMQJobWorker(...) in a worker process; dispatched jobs do not execute without one. See the jobs docs page.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: ["createInngestJobsProvider"],
   },
@@ -180,7 +192,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-jobs-inngest`",
       "- Peer dependency: `inngest`",
-      "- The preset wires `createInngestJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/app-ports.ts`.",
+      "- The preset wires `createInngestJobsProvider()` in `server/providers.ts` and defers `jobs` in `infra/port-wiring.ts`.",
       "- Define jobs with `defineJob(...)` and dispatch them through `ctx.ports.jobs.dispatch(...)`.",
       "- Execution needs an Inngest serve route built from `createInngestJobFunction(...)` and `serve(...)`. See the jobs docs page.",
       "- Use `ctx.ports.inngest` only as an escape hatch for Inngest-specific workflow APIs; prefer `ctx.ports.jobs.dispatch(...)` for Beignet jobs.",
@@ -190,7 +202,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Run your package manager install command.",
       "Set INNGEST_APP_NAME and, for Inngest cloud, INNGEST_EVENT_KEY in .env.local or your deployment environment.",
       "Expose an Inngest serve route with createInngestJobFunction(...) so dispatched jobs execute. See the jobs docs page.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: ["createBullMQJobsProvider"],
   },
@@ -222,7 +234,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-mail-resend`",
       "- Peer dependency: `resend`",
-      "- The preset wires `createResendMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/app-ports.ts`.",
+      "- The preset wires `createResendMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `RESEND_API_KEY` and `RESEND_FROM` values before sending mail.",
       "- Use `ctx.ports.mailer` in app code; `ctx.ports.resend` is available as an escape hatch.",
       "",
@@ -230,7 +242,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set RESEND_API_KEY and RESEND_FROM in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
       "createSmtpMailProvider",
@@ -268,7 +280,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-mail-smtp`",
       "- Peer dependency: `nodemailer`",
-      "- The preset wires `createSmtpMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/app-ports.ts`.",
+      "- The preset wires `createSmtpMailProvider()` in `server/providers.ts` and defers `mailer` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `MAIL_*` values before sending mail.",
       "- Use `ctx.ports.mailer` in app code; `ctx.ports.smtp` is available as an escape hatch.",
       "",
@@ -276,7 +288,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
       "createResendMailProvider",
@@ -317,7 +329,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-payments-stripe`",
       "- Peer dependency: `stripe`",
-      "- The preset wires `createStripePaymentsProvider()` in `server/providers.ts` and defers `payments` in `infra/app-ports.ts`.",
+      "- The preset wires `createStripePaymentsProvider()` in `server/providers.ts` and defers `payments` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` values before taking payments.",
       "- Stripe requires a webhook route: run `beignet make payments` for the full billing slice, including a `createPaymentWebhookRoute(...)` route.",
       "- Use `ctx.ports.payments` in app code; `ctx.ports.stripe` is available as an escape hatch.",
@@ -327,7 +339,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Run your package manager install command.",
       "Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET in .env.local or your deployment environment.",
       "Run beignet make payments for the full billing slice; Stripe needs its webhook route before subscription state can sync.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: ["createMemoryPaymentsProvider"],
   },
@@ -360,7 +372,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "## Meilisearch search",
       "",
       "- Package: `@beignet/provider-search-meilisearch`",
-      "- The preset wires `createMeilisearchSearchProvider()` in `server/providers.ts` and defers `search` in `infra/app-ports.ts`.",
+      "- The preset wires `createMeilisearchSearchProvider()` in `server/providers.ts` and defers `search` in `infra/port-wiring.ts`.",
       "- Set `MEILISEARCH_HOST` before booting the app; set `MEILISEARCH_API_KEY` when your Meilisearch server requires one.",
       "- Use `ctx.ports.search` in app code; `ctx.ports.meilisearch` is available as an escape hatch.",
       "",
@@ -368,11 +380,11 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set MEILISEARCH_HOST and any needed MEILISEARCH_* values in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
-  sentry: {
-    name: "sentry",
+  "error-reporting-sentry": {
+    name: "error-reporting-sentry",
     displayName: "Sentry error reporting",
     importName: "createSentryErrorReportingProvider",
     importFrom: "@beignet/provider-error-reporting-sentry",
@@ -403,11 +415,11 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set SENTRY_DSN in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
-  "redis-cache": {
-    name: "redis-cache",
+  "cache-redis": {
+    name: "cache-redis",
     displayName: "Redis cache",
     importName: "createRedisCacheProvider",
     importFrom: "@beignet/provider-cache-redis",
@@ -434,7 +446,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-cache-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisCacheProvider()` in `server/providers.ts` and defers `cache` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisCacheProvider()` in `server/providers.ts` and defers `cache` in `infra/port-wiring.ts`.",
       "- Set `REDIS_URL` before booting the app.",
       "- Use `ctx.ports.cache` in app code; `ctx.ports.redis` is available as an escape hatch.",
       "",
@@ -442,7 +454,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set REDIS_URL in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
   "event-bus-redis": {
@@ -475,7 +487,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-event-bus-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisEventBusProvider()` in `server/providers.ts` and defers `eventBus` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisEventBusProvider()` in `server/providers.ts` and defers `eventBus` in `infra/port-wiring.ts`.",
       "- Set `REDIS_EVENT_BUS_URL` before booting the app.",
       "- Redis Pub/Sub delivery is best-effort and cross-process, but not durable: use outbox/jobs for side effects that need retry, replay, or dead-letter handling.",
       "- Use `ctx.ports.eventBus` in app code; `ctx.ports.redisEventBus` is available as an escape hatch.",
@@ -485,12 +497,12 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "Run your package manager install command.",
       "Set REDIS_EVENT_BUS_URL in .env.local or your deployment environment.",
       "Keep durable side effects on the outbox/jobs path; Redis Pub/Sub does not replay missed events.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: ["createMemoryEventBusProvider"],
   },
-  "redis-locks": {
-    name: "redis-locks",
+  "locks-redis": {
+    name: "locks-redis",
     displayName: "Redis locks",
     importName: "createRedisLocksProvider",
     importFrom: "@beignet/provider-locks-redis",
@@ -518,7 +530,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-locks-redis`",
       "- Peer dependency: `ioredis`",
-      "- The preset wires `createRedisLocksProvider()` in `server/providers.ts` and defers `locks` in `infra/app-ports.ts`.",
+      "- The preset wires `createRedisLocksProvider()` in `server/providers.ts` and defers `locks` in `infra/port-wiring.ts`.",
       "- Set `REDIS_LOCKS_URL` before booting the app.",
       "- Use `ctx.ports.locks` in app code; `ctx.ports.redisLocks` is available as an escape hatch.",
       "",
@@ -526,11 +538,11 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set REDIS_LOCKS_URL in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
-  "s3-storage": {
-    name: "s3-storage",
+  "storage-s3": {
+    name: "storage-s3",
     displayName: "S3-compatible storage",
     importName: "createS3StorageProvider",
     importFrom: "@beignet/provider-storage-s3",
@@ -579,7 +591,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-storage-s3`",
       "- Peer dependencies: `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`",
-      "- The preset wires `createS3StorageProvider()` in `server/providers.ts` and defers `storage` in `infra/app-ports.ts`.",
+      "- The preset wires `createS3StorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
       "- Set `STORAGE_S3_BUCKET` before booting the app; set endpoint and credentials when using an S3-compatible host outside AWS defaults.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.s3Storage` is available as an escape hatch.",
       "",
@@ -587,15 +599,15 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set STORAGE_S3_BUCKET and any needed STORAGE_S3_* credentials in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
       "createLocalStorageProvider",
       "createVercelBlobStorageProvider",
     ],
   },
-  "vercel-blob-storage": {
-    name: "vercel-blob-storage",
+  "storage-vercel-blob": {
+    name: "storage-vercel-blob",
     displayName: "Vercel Blob storage",
     importName: "createVercelBlobStorageProvider",
     importFrom: "@beignet/provider-storage-vercel-blob",
@@ -625,7 +637,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-storage-vercel-blob`",
       "- Peer dependency: `@vercel/blob`",
-      "- The preset wires `createVercelBlobStorageProvider()` in `server/providers.ts` and defers `storage` in `infra/app-ports.ts`.",
+      "- The preset wires `createVercelBlobStorageProvider()` in `server/providers.ts` and defers `storage` in `infra/port-wiring.ts`.",
       "- On Vercel, connect a Blob store to the project and `BLOB_READ_WRITE_TOKEN` is set automatically; set it manually elsewhere.",
       "- The store is uniform-visibility (`BLOB_ACCESS`, default `private`): Vercel Blob does not report per-object access back, so mixed visibility needs a second store.",
       "- Use `ctx.ports.storage` in app code; `ctx.ports.vercelBlob` is available as an escape hatch.",
@@ -634,15 +646,15 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Connect a Vercel Blob store to the project (or set BLOB_READ_WRITE_TOKEN manually).",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
     conflictingProviderEntries: [
       "createLocalStorageProvider",
       "createS3StorageProvider",
     ],
   },
-  "upstash-rate-limit": {
-    name: "upstash-rate-limit",
+  "rate-limit-upstash": {
+    name: "rate-limit-upstash",
     displayName: "Upstash rate limit",
     importName: "createUpstashRateLimitProvider",
     importFrom: "@beignet/provider-rate-limit-upstash",
@@ -673,7 +685,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
       "",
       "- Package: `@beignet/provider-rate-limit-upstash`",
       "- Peer dependencies: `@upstash/ratelimit` and `@upstash/redis`",
-      "- The preset wires `createUpstashRateLimitProvider()` in `server/providers.ts` and defers `rateLimit` in `infra/app-ports.ts`.",
+      "- The preset wires `createUpstashRateLimitProvider()` in `server/providers.ts` and defers `rateLimit` in `infra/port-wiring.ts`.",
       "- `.env.example` ships dev placeholders so the app boots; set real `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` values before rate limiting requests.",
       "- Use `ctx.ports.rateLimit` in app code; `ctx.ports.upstash` is available as an escape hatch.",
       "",
@@ -681,7 +693,7 @@ const presets: Record<ProviderPresetName, ProviderPreset> = {
     nextSteps: [
       "Run your package manager install command.",
       "Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN in .env.local or your deployment environment.",
-      "Run beignet providers audit and beignet doctor --strict.",
+      "Run beignet provider audit and beignet doctor --strict.",
     ],
   },
 };
@@ -690,12 +702,12 @@ const providerPresetSet = new Set<string>(providerPresetChoices);
 
 /**
  * Provider entries the starter template wires for each create-time
- * integration, used to pre-validate preset selections at create time.
+ * provider, used to pre-validate preset selections at create time.
  */
-const integrationProviderEntries: Record<IntegrationName, string> = {
-  inngest: "createInngestJobsProvider",
-  resend: "createResendMailProvider",
-  "upstash-rate-limit": "createUpstashRateLimitProvider",
+const starterProviderEntries: Record<StarterProviderName, string> = {
+  "jobs-inngest": "createInngestJobsProvider",
+  "mail-resend": "createResendMailProvider",
+  "rate-limit-upstash": "createUpstashRateLimitProvider",
 };
 
 /**
@@ -707,15 +719,18 @@ export function providerPresetNeedsEnv(name: ProviderPresetName): boolean {
 
 /**
  * Fail fast when a create-time selection combines presets or template
- * integrations that fill the same app port, before any files are written.
+ * starter providers that fill the same app port, before any files are written.
  */
 export function assertCompatibleCreatePresets(
   presetNames: readonly ProviderPresetName[],
-  integrations: readonly IntegrationName[],
+  starterProviders: readonly StarterProviderName[],
 ): void {
   const selectedEntries = new Map<string, string>();
-  for (const integration of integrations) {
-    selectedEntries.set(integrationProviderEntries[integration], integration);
+  for (const starterProvider of starterProviders) {
+    selectedEntries.set(
+      starterProviderEntries[starterProvider],
+      starterProvider,
+    );
   }
   for (const name of presetNames) {
     selectedEntries.set(presets[name].importName, name);
@@ -726,7 +741,7 @@ export function assertCompatibleCreatePresets(
       const other = selectedEntries.get(conflict);
       if (other !== undefined && other !== name) {
         throw new Error(
-          `--integrations selections "${name}" and "${other}" fill the same app port. Pick one of them.`,
+          `--providers selections "${name}" and "${other}" fill the same app port. Pick one of them.`,
         );
       }
     }
@@ -747,18 +762,85 @@ export async function addProviderPreset(
   const preset = presets[options.name as ProviderPresetName];
   const targetDir = path.resolve(options.cwd ?? process.cwd());
   const config = await loadBeignetConfig(targetDir);
-  const packageJsonPath = "package.json";
-  const providersPath = serverProvidersPath(config);
-  const integrationsPath = "docs/integrations.md";
+  const readSource: ProviderSourceReader = (filePath) =>
+    readOptionalAppFile(targetDir, filePath);
+  const filesToPlan = await providerPresetFiles(preset, config, readSource);
+  const plannedFiles = await planFiles(filesToPlan, readSource);
 
-  const packageJsonSource = await readRequiredAppFile(
+  if (!options.dryRun) {
+    for (const file of plannedFiles) {
+      await writePlannedFile(targetDir, file);
+    }
+  }
+
+  return providerPresetResult(
+    preset,
     targetDir,
+    Boolean(options.dryRun),
+    plannedFiles,
+  );
+}
+
+/**
+ * Apply provider presets to an in-memory fresh scaffold. Each preset reads the
+ * previous preset's output so dry runs model the real sequential create path.
+ */
+export async function planProviderPresetsForCreate(options: {
+  targetDir: string;
+  files: readonly ProviderPlanFile[];
+  names: readonly ProviderPresetName[];
+}): Promise<CreateProviderPresetPlan> {
+  const sources = new Map(
+    options.files.map((file) => [file.path, file.content] as const),
+  );
+  const config = await loadBeignetConfig(options.targetDir);
+  const presetResults: AddProviderPresetResult[] = [];
+  const readSource: ProviderSourceReader = async (filePath) => {
+    const generatedSource = sources.get(filePath);
+    return generatedSource ?? readOptionalAppFile(options.targetDir, filePath);
+  };
+
+  for (const name of options.names) {
+    const preset = presets[name];
+    const filesToPlan = await providerPresetFiles(preset, config, readSource);
+    const plannedFiles = await planFiles(filesToPlan, readSource);
+
+    for (const file of plannedFiles) {
+      sources.set(file.path, file.content);
+    }
+
+    presetResults.push(
+      providerPresetResult(preset, options.targetDir, true, plannedFiles),
+    );
+  }
+
+  return {
+    files: [...sources].map(([filePath, content]) => ({
+      path: filePath,
+      content,
+    })),
+    presets: presetResults,
+  };
+}
+
+async function providerPresetFiles(
+  preset: ProviderPreset,
+  config: ResolvedBeignetConfig,
+  readSource: ProviderSourceReader,
+): Promise<ProviderPlanFile[]> {
+  const packageJsonPath = "package.json";
+  const providersPath = serverProvidersPath(config);
+  const providersDocsPath = "docs/providers.md";
+  const packageJsonSource = await readRequiredSource(
+    readSource,
     packageJsonPath,
   );
   const packageJson = parsePackageJson(packageJsonSource);
-  const envExampleSource = await readOptionalAppFile(targetDir, ".env.example");
-  const envExampleContent = updateEnvExample(envExampleSource, preset);
-  const filesToPlan = [
+  const envExampleContent = updateEnvExample(
+    await readSource(".env.example"),
+    preset,
+  );
+  const files = [
     {
       path: packageJsonPath,
       content: updatePackageJson(packageJsonSource, packageJson, preset),
@@ -766,53 +848,51 @@ export async function addProviderPreset(
     {
       path: providersPath,
       content: updateServerProviders(
-        await readRequiredAppFile(targetDir, providersPath),
+        await readRequiredSource(readSource, providersPath),
         preset,
       ),
     },
     {
       path: config.paths.ports,
       content: updatePortsFile(
-        await readRequiredAppFile(targetDir, config.paths.ports),
+        await readRequiredSource(readSource, config.paths.ports),
         preset.appPort,
       ),
     },
     {
-      path: config.paths.infrastructurePorts,
+      path: config.paths.portWiring,
       content: updateInfrastructurePortsFile(
-        await readRequiredAppFile(targetDir, config.paths.infrastructurePorts),
+        await readRequiredSource(readSource, config.paths.portWiring),
         preset.appPort.key,
       ),
     },
     {
-      path: integrationsPath,
-      content: updateIntegrationsDoc(
-        await readOptionalAppFile(targetDir, integrationsPath),
-        preset,
-      ),
+      path: providersDocsPath,
+      content: updateProvidersDoc(await readSource(providersDocsPath), preset),
     },
   ];
 
   if (envExampleContent !== undefined) {
-    filesToPlan.splice(filesToPlan.length - 1, 0, {
+    files.splice(files.length - 1, 0, {
       path: ".env.example",
       content: envExampleContent,
     });
   }
 
-  const plannedFiles = await planFiles(targetDir, filesToPlan);
-
-  if (!options.dryRun) {
-    for (const file of plannedFiles) {
-      await writePlannedFile(targetDir, file);
-    }
-  }
+  return files;
+}
 
+function providerPresetResult(
+  preset: ProviderPreset,
+  targetDir: string,
+  dryRun: boolean,
+  plannedFiles: readonly PlannedFile[],
+): AddProviderPresetResult {
   return {
     schemaVersion: 1,
     name: preset.name,
     targetDir,
-    dryRun: Boolean(options.dryRun),
+    dryRun,
     files: plannedFiles.map((file) => file.path),
     createdFiles: plannedFiles
       .filter((file) => file.result === "created")
@@ -827,6 +907,19 @@ export async function addProviderPreset(
   };
 }
 
+async function readRequiredSource(
+  readSource: ProviderSourceReader,
+  filePath: string,
+): Promise<string> {
+  const content = await readSource(filePath);
+  if (content === undefined) {
+    throw new Error(
+      `Could not find ${filePath}. Run this command in a Beignet app.`,
+    );
+  }
+  return content;
+}
+
 function beignetDependencyVersion(packageJson: PackageJson): string {
   return (
     packageJson.dependencies?.["@beignet/core"] ??
@@ -959,14 +1052,14 @@ function updateEnvExample(
   return appendSection(current, preset.envExample);
 }
 
-function updateIntegrationsDoc(
+function updateProvidersDoc(
   source: string | undefined,
   preset: ProviderPreset,
 ): string {
   const current =
     source ??
     [
-      "# Integrations",
+      "# Providers",
       "",
       "This file tracks app-level provider setup added after the initial scaffold.",
       "",
@@ -1056,13 +1149,17 @@ function ensureTypeProperty(
 function ensureDeferredPort(source: string, portKey: string): string {
   const match = /\bdeferred\s*:\s*\[/.exec(source);
   if (!match) {
-    throw new Error("Could not find `deferred: [...]` in infra/app-ports.ts.");
+    throw new Error(
+      "Could not find `deferred: [...]` in infra/port-wiring.ts.",
+    );
   }
 
   const openBracket = source.indexOf("[", match.index);
   const closeBracket = matchingDelimiterIndex(source, openBracket, "[", "]");
   if (closeBracket === -1) {
-    throw new Error("Could not parse `deferred` array in infra/app-ports.ts.");
+    throw new Error(
+      "Could not parse `deferred` array in infra/port-wiring.ts.",
+    );
   }
 
   const arrayText = source.slice(openBracket, closeBracket + 1);
@@ -1140,13 +1237,13 @@ function sortRecord(record: Record<string, string>): Record<string, string> {
 }
 
 async function planFiles(
-  targetDir: string,
-  files: Array<{ path: string; content: string }>,
+  files: ProviderPlanFile[],
+  readSource: ProviderSourceReader,
 ): Promise<PlannedFile[]> {
   const planned: PlannedFile[] = [];
 
   for (const file of files) {
-    const existing = await readOptionalAppFile(targetDir, file.path);
+    const existing = await readSource(file.path);
     planned.push({
       ...file,
       result:
@@ -1172,19 +1269,6 @@ async function writePlannedFile(
   await writeFile(destination, file.content);
 }
 
-async function readRequiredAppFile(
-  targetDir: string,
-  filePath: string,
-): Promise<string> {
-  const content = await readOptionalAppFile(targetDir, filePath);
-  if (content === undefined) {
-    throw new Error(
-      `Could not find ${filePath}. Run this command in a Beignet app.`,
-    );
-  }
-  return content;
-}
-
 async function readOptionalAppFile(
   targetDir: string,
   filePath: string,

package/src/provider-audit.ts

@@ -149,7 +149,7 @@ export async function auditProviders(
     ? await readCachedSource(targetDir, config.paths.ports, sourceCache)
     : "";
   const infrastructurePath = directoryPath(
-    path.dirname(config.paths.infrastructurePorts),
+    path.dirname(config.paths.portWiring),
   );
   const schemaDir = `${infrastructurePath}/db/schema`;
 
@@ -1679,13 +1679,13 @@ function isInfraOrServerFile(
 ): boolean {
   const serverDir = directoryPath(path.dirname(config.paths.server));
   const infrastructureDir = directoryPath(
-    path.dirname(config.paths.infrastructurePorts),
+    path.dirname(config.paths.portWiring),
   );
 
   return (
     file === config.paths.server ||
     file.startsWith(`${serverDir}/`) ||
-    file === config.paths.infrastructurePorts ||
+    file === config.paths.portWiring ||
     file.startsWith(`${infrastructureDir}/`)
   );
 }