@beignet/cli 0.0.26 → 0.0.27

package/src/provider-add.ts

@@ -0,0 +1,926 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { type ProviderPresetName, providerPresetChoices } from "./choices.js";
+import {
+  directoryPath,
+  loadBeignetConfig,
+  type ResolvedBeignetConfig,
+} from "./config.js";
+import {
+  appendToArrayExpression,
+  appendToNamedArray,
+  arrayInitializerInfo,
+  identifiersFromArrayExpression,
+  insertAfterImports,
+  matchingDelimiterIndex,
+} from "./registry-edits.js";
+import { externalVersions, json } from "./templates/shared.js";
+
+export type AddProviderPresetOptions = {
+  name: ProviderPresetName | string;
+  cwd?: string;
+  dryRun?: boolean;
+};
+
+export type AddProviderPresetResult = {
+  schemaVersion: 1;
+  name: ProviderPresetName;
+  targetDir: string;
+  dryRun: boolean;
+  files: string[];
+  createdFiles: string[];
+  updatedFiles: string[];
+  skippedFiles: string[];
+  nextSteps: string[];
+};
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  [key: string]: unknown;
+};
+
+type AppPortUpdate = {
+  key: string;
+  typeName: string;
+  importName: string;
+  importFrom: string;
+};
+
+type ProviderPreset = {
+  name: ProviderPresetName;
+  displayName: string;
+  importName: string;
+  importFrom: string;
+  providerEntry: string;
+  dependencies: (packageJson: PackageJson) => Record<string, string>;
+  appPort: AppPortUpdate;
+  envVars: string[];
+  envExample: string;
+  docs: string;
+  nextSteps: string[];
+  conflictingProviderEntries?: string[];
+};
+
+type PlannedFile = {
+  path: string;
+  content: string;
+  result: "created" | "updated" | "skipped";
+};
+
+const presets: Record<ProviderPresetName, ProviderPreset> = {
+  "flags-openfeature": {
+    name: "flags-openfeature",
+    displayName: "OpenFeature flags",
+    importName: "openFeatureFlagsProvider",
+    importFrom: "@beignet/provider-flags-openfeature",
+    providerEntry: "openFeatureFlagsProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-flags-openfeature":
+        beignetDependencyVersion(packageJson),
+      "@openfeature/server-sdk": externalVersions.openFeatureServerSdk,
+    }),
+    appPort: {
+      key: "flags",
+      typeName: "FlagsPort",
+      importName: "FlagsPort",
+      importFrom: "@beignet/core/flags",
+    },
+    envVars: [],
+    envExample: "",
+    docs: [
+      "## OpenFeature flags",
+      "",
+      "- Package: `@beignet/provider-flags-openfeature`",
+      "- Peer dependency: `@openfeature/server-sdk`",
+      "- The preset wires `openFeatureFlagsProvider` in `server/providers.ts` and defers `flags` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+  "mail-resend": {
+    name: "mail-resend",
+    displayName: "Resend mail",
+    importName: "mailResendProvider",
+    importFrom: "@beignet/provider-mail-resend",
+    providerEntry: "mailResendProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-mail-resend": beignetDependencyVersion(packageJson),
+      resend: externalVersions.resend,
+    }),
+    appPort: {
+      key: "mailer",
+      typeName: "MailerPort",
+      importName: "MailerPort",
+      importFrom: "@beignet/core/mail",
+    },
+    envVars: ["RESEND_API_KEY", "RESEND_FROM"],
+    envExample: [
+      "# Resend mail provider",
+      "RESEND_API_KEY=dev-placeholder-change-me",
+      "RESEND_FROM=Beignet App <noreply@example.com>",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Resend mail",
+      "",
+      "- Package: `@beignet/provider-mail-resend`",
+      "- Peer dependency: `resend`",
+      "- The preset wires `mailResendProvider` in `server/providers.ts` and defers `mailer` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+    conflictingProviderEntries: [
+      "mailSmtpProvider",
+      "createMemoryMailerProvider",
+    ],
+  },
+  "mail-smtp": {
+    name: "mail-smtp",
+    displayName: "SMTP mail",
+    importName: "mailSmtpProvider",
+    importFrom: "@beignet/provider-mail-smtp",
+    providerEntry: "mailSmtpProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-mail-smtp": beignetDependencyVersion(packageJson),
+      nodemailer: externalVersions.nodemailer,
+    }),
+    appPort: {
+      key: "mailer",
+      typeName: "MailerPort",
+      importName: "MailerPort",
+      importFrom: "@beignet/core/mail",
+    },
+    envVars: ["MAIL_HOST", "MAIL_PORT", "MAIL_USER", "MAIL_PASS", "MAIL_FROM"],
+    envExample: [
+      "# SMTP mail provider",
+      "MAIL_HOST=smtp.example.com",
+      "MAIL_PORT=587",
+      "MAIL_USER=dev-placeholder-change-me",
+      "MAIL_PASS=dev-placeholder-change-me",
+      "MAIL_FROM=Beignet App <noreply@example.com>",
+      "",
+    ].join("\n"),
+    docs: [
+      "## SMTP mail",
+      "",
+      "- Package: `@beignet/provider-mail-smtp`",
+      "- Peer dependency: `nodemailer`",
+      "- The preset wires `mailSmtpProvider` in `server/providers.ts` and defers `mailer` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+    conflictingProviderEntries: [
+      "mailResendProvider",
+      "createMemoryMailerProvider",
+    ],
+  },
+  "search-meilisearch": {
+    name: "search-meilisearch",
+    displayName: "Meilisearch search",
+    importName: "meilisearchSearchProvider",
+    importFrom: "@beignet/provider-search-meilisearch",
+    providerEntry: "meilisearchSearchProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-search-meilisearch":
+        beignetDependencyVersion(packageJson),
+    }),
+    appPort: {
+      key: "search",
+      typeName: "SearchPort",
+      importName: "SearchPort",
+      importFrom: "@beignet/core/search",
+    },
+    envVars: ["MEILISEARCH_HOST"],
+    envExample: [
+      "# Meilisearch search provider",
+      "MEILISEARCH_HOST=http://localhost:7700",
+      "# MEILISEARCH_API_KEY=",
+      "# MEILISEARCH_INDEX_PREFIX=beignet",
+      "# MEILISEARCH_TIMEOUT_MS=5000",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Meilisearch search",
+      "",
+      "- Package: `@beignet/provider-search-meilisearch`",
+      "- The preset wires `meilisearchSearchProvider` in `server/providers.ts` and defers `search` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+  sentry: {
+    name: "sentry",
+    displayName: "Sentry error reporting",
+    importName: "sentryErrorReportingProvider",
+    importFrom: "@beignet/provider-error-reporting-sentry",
+    providerEntry: "sentryErrorReportingProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-error-reporting-sentry":
+        beignetDependencyVersion(packageJson),
+      "@sentry/node": externalVersions.sentryNode,
+    }),
+    appPort: {
+      key: "errorReporter",
+      typeName: "ErrorReporterPort",
+      importName: "ErrorReporterPort",
+      importFrom: "@beignet/core/error-reporting",
+    },
+    envVars: ["SENTRY_DSN"],
+    envExample: ["# Sentry error reporting", "# SENTRY_DSN=", ""].join("\n"),
+    docs: [
+      "## Sentry error reporting",
+      "",
+      "- Package: `@beignet/provider-error-reporting-sentry`",
+      "- Peer dependency: `@sentry/node`",
+      "- The preset wires `sentryErrorReportingProvider` in `server/providers.ts`.",
+      "- Set `SENTRY_DSN` before deploying when captures should be sent to Sentry.",
+      "- Use `ctx.ports.errorReporter` in app code; `ctx.ports.sentry` is available as an escape hatch.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+  "redis-cache": {
+    name: "redis-cache",
+    displayName: "Redis cache",
+    importName: "redisProvider",
+    importFrom: "@beignet/provider-redis",
+    providerEntry: "redisProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-redis": beignetDependencyVersion(packageJson),
+      ioredis: externalVersions.ioredis,
+    }),
+    appPort: {
+      key: "cache",
+      typeName: "CachePort",
+      importName: "CachePort",
+      importFrom: "@beignet/core/ports",
+    },
+    envVars: ["REDIS_URL"],
+    envExample: [
+      "# Redis cache provider",
+      "REDIS_URL=redis://localhost:6379",
+      "# REDIS_DB=0",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Redis cache",
+      "",
+      "- Package: `@beignet/provider-redis`",
+      "- Peer dependency: `ioredis`",
+      "- The preset wires `redisProvider` in `server/providers.ts` and defers `cache` in `infra/app-ports.ts`.",
+      "- Set `REDIS_URL` before booting the app.",
+      "- Use `ctx.ports.cache` in app code; `ctx.ports.redis` is available as an escape hatch.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+  "redis-locks": {
+    name: "redis-locks",
+    displayName: "Redis locks",
+    importName: "redisLocksProvider",
+    importFrom: "@beignet/provider-locks-redis",
+    providerEntry: "redisLocksProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-locks-redis": beignetDependencyVersion(packageJson),
+      ioredis: externalVersions.ioredis,
+    }),
+    appPort: {
+      key: "locks",
+      typeName: "LocksPort",
+      importName: "LocksPort",
+      importFrom: "@beignet/core/locks",
+    },
+    envVars: ["REDIS_LOCKS_URL"],
+    envExample: [
+      "# Redis locks provider",
+      "REDIS_LOCKS_URL=redis://localhost:6379",
+      "# REDIS_LOCKS_DB=0",
+      "# REDIS_LOCKS_PREFIX=beignet:locks",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Redis locks",
+      "",
+      "- Package: `@beignet/provider-locks-redis`",
+      "- Peer dependency: `ioredis`",
+      "- The preset wires `redisLocksProvider` in `server/providers.ts` and defers `locks` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+  "s3-storage": {
+    name: "s3-storage",
+    displayName: "S3-compatible storage",
+    importName: "s3StorageProvider",
+    importFrom: "@beignet/provider-storage-s3",
+    providerEntry: "s3StorageProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-storage-s3": beignetDependencyVersion(packageJson),
+      "@aws-sdk/client-s3": externalVersions.awsSdkS3,
+      "@aws-sdk/s3-request-presigner": externalVersions.awsSdkS3,
+    }),
+    appPort: {
+      key: "storage",
+      typeName: "StoragePort",
+      importName: "StoragePort",
+      importFrom: "@beignet/core/storage",
+    },
+    envVars: ["STORAGE_S3_BUCKET"],
+    envExample: [
+      "# S3-compatible storage provider",
+      "STORAGE_S3_BUCKET=beignet-assets",
+      "STORAGE_S3_REGION=us-east-1",
+      "# STORAGE_S3_ENDPOINT=",
+      "# STORAGE_S3_PUBLIC_BASE_URL=",
+      "# STORAGE_S3_FORCE_PATH_STYLE=false",
+      "# STORAGE_S3_KEY_PREFIX=",
+      "# STORAGE_S3_ACCESS_KEY_ID=",
+      "# STORAGE_S3_SECRET_ACCESS_KEY=",
+      "# STORAGE_S3_SESSION_TOKEN=",
+      "",
+    ].join("\n"),
+    docs: [
+      "## S3-compatible storage",
+      "",
+      "- Package: `@beignet/provider-storage-s3`",
+      "- Peer dependencies: `@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner`",
+      "- The preset wires `s3StorageProvider` in `server/providers.ts` and defers `storage` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+    conflictingProviderEntries: [
+      "localStorageProvider",
+      "createLocalStorageProvider",
+    ],
+  },
+  "upstash-rate-limit": {
+    name: "upstash-rate-limit",
+    displayName: "Upstash rate limit",
+    importName: "upstashRateLimitProvider",
+    importFrom: "@beignet/provider-rate-limit-upstash",
+    providerEntry: "upstashRateLimitProvider",
+    dependencies: (packageJson) => ({
+      "@beignet/provider-rate-limit-upstash":
+        beignetDependencyVersion(packageJson),
+      "@upstash/ratelimit": externalVersions.upstashRateLimit,
+      "@upstash/redis": externalVersions.upstashRedis,
+    }),
+    appPort: {
+      key: "rateLimit",
+      typeName: "RateLimitPort",
+      importName: "RateLimitPort",
+      importFrom: "@beignet/core/ports",
+    },
+    envVars: ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"],
+    envExample: [
+      "# Upstash rate limit provider",
+      "UPSTASH_REDIS_REST_URL=https://dev-placeholder.upstash.io",
+      "UPSTASH_REDIS_REST_TOKEN=dev-placeholder-change-me",
+      "UPSTASH_PREFIX=beignet:ratelimit",
+      "# UPSTASH_ALGORITHM=fixed-window",
+      "",
+    ].join("\n"),
+    docs: [
+      "## Upstash rate limit",
+      "",
+      "- Package: `@beignet/provider-rate-limit-upstash`",
+      "- Peer dependencies: `@upstash/ratelimit` and `@upstash/redis`",
+      "- The preset wires `upstashRateLimitProvider` in `server/providers.ts` and defers `rateLimit` in `infra/app-ports.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.",
+      "",
+    ].join("\n"),
+    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.",
+    ],
+  },
+};
+
+const providerPresetSet = new Set<string>(providerPresetChoices);
+
+export async function addProviderPreset(
+  options: AddProviderPresetOptions,
+): Promise<AddProviderPresetResult> {
+  if (!providerPresetSet.has(options.name)) {
+    throw new Error(
+      `Unknown provider preset "${options.name}". Available presets: ${providerPresetChoices.join(
+        ", ",
+      )}.`,
+    );
+  }
+
+  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 packageJsonSource = await readRequiredAppFile(
+    targetDir,
+    packageJsonPath,
+  );
+  const packageJson = parsePackageJson(packageJsonSource);
+  const envExampleSource = await readOptionalAppFile(targetDir, ".env.example");
+  const envExampleContent = updateEnvExample(envExampleSource, preset);
+  const filesToPlan = [
+    {
+      path: packageJsonPath,
+      content: updatePackageJson(packageJsonSource, packageJson, preset),
+    },
+    {
+      path: providersPath,
+      content: updateServerProviders(
+        await readRequiredAppFile(targetDir, providersPath),
+        preset,
+      ),
+    },
+    {
+      path: config.paths.ports,
+      content: updatePortsFile(
+        await readRequiredAppFile(targetDir, config.paths.ports),
+        preset.appPort,
+      ),
+    },
+    {
+      path: config.paths.infrastructurePorts,
+      content: updateInfrastructurePortsFile(
+        await readRequiredAppFile(targetDir, config.paths.infrastructurePorts),
+        preset.appPort.key,
+      ),
+    },
+    {
+      path: integrationsPath,
+      content: updateIntegrationsDoc(
+        await readOptionalAppFile(targetDir, integrationsPath),
+        preset,
+      ),
+    },
+  ];
+
+  if (envExampleContent !== undefined) {
+    filesToPlan.splice(filesToPlan.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 {
+    schemaVersion: 1,
+    name: preset.name,
+    targetDir,
+    dryRun: Boolean(options.dryRun),
+    files: plannedFiles.map((file) => file.path),
+    createdFiles: plannedFiles
+      .filter((file) => file.result === "created")
+      .map((file) => file.path),
+    updatedFiles: plannedFiles
+      .filter((file) => file.result === "updated")
+      .map((file) => file.path),
+    skippedFiles: plannedFiles
+      .filter((file) => file.result === "skipped")
+      .map((file) => file.path),
+    nextSteps: preset.nextSteps,
+  };
+}
+
+function beignetDependencyVersion(packageJson: PackageJson): string {
+  return (
+    packageJson.dependencies?.["@beignet/core"] ??
+    packageJson.dependencies?.["@beignet/next"] ??
+    packageJson.dependencies?.["@beignet/devtools"] ??
+    packageJson.devDependencies?.["@beignet/cli"] ??
+    "*"
+  );
+}
+
+function serverProvidersPath(config: ResolvedBeignetConfig): string {
+  return path.posix.join(
+    directoryPath(path.posix.dirname(config.paths.server)),
+    "providers.ts",
+  );
+}
+
+function parsePackageJson(source: string): PackageJson {
+  try {
+    const packageJson = JSON.parse(source) as PackageJson;
+    if (typeof packageJson !== "object" || packageJson === null) {
+      throw new Error("package.json must contain a JSON object.");
+    }
+    return packageJson;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid package.json: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+function updatePackageJson(
+  source: string,
+  packageJson: PackageJson,
+  preset: ProviderPreset,
+): string {
+  const dependencies = {
+    ...(packageJson.dependencies ?? {}),
+  };
+  let changed = false;
+
+  for (const [name, version] of Object.entries(
+    preset.dependencies(packageJson),
+  )) {
+    if (dependencies[name] === undefined) {
+      dependencies[name] = version;
+      changed = true;
+    }
+  }
+
+  if (!changed) return source;
+
+  return json({
+    ...packageJson,
+    dependencies: sortRecord(dependencies),
+  });
+}
+
+function updateServerProviders(source: string, preset: ProviderPreset): string {
+  assertNoConflictingProviders(source, preset);
+
+  const importLine = `import { ${preset.importName} } from "${preset.importFrom}";`;
+  const result = appendToNamedArray(
+    source,
+    "providers",
+    preset.providerEntry,
+    hasNamedImport(source, preset.importName, preset.importFrom)
+      ? undefined
+      : importLine,
+  );
+
+  if (result.kind === "missing") {
+    throw new Error(
+      "Could not find `export const providers = [...]` in server/providers.ts.",
+    );
+  }
+
+  return result.kind === "updated" ? result.source : source;
+}
+
+function assertNoConflictingProviders(
+  source: string,
+  preset: ProviderPreset,
+): void {
+  const registry = arrayInitializerInfo(source, "providers");
+  if (!registry) return;
+
+  const identifiers = identifiersFromArrayExpression(registry.text);
+  for (const conflict of preset.conflictingProviderEntries ?? []) {
+    if (identifiers.has(conflict)) {
+      throw new Error(
+        `Provider preset "${preset.name}" conflicts with existing provider ${conflict} in server/providers.ts. Remove or replace that provider before adding this preset.`,
+      );
+    }
+  }
+}
+
+function updatePortsFile(source: string, appPort: AppPortUpdate): string {
+  let next = ensureNamedTypeImport(
+    source,
+    appPort.importName,
+    appPort.importFrom,
+  );
+  next = ensureTypeProperty(next, "AppPorts", appPort.key, appPort.typeName);
+  return next;
+}
+
+function updateInfrastructurePortsFile(
+  source: string,
+  portKey: string,
+): string {
+  if (hasBoundPort(source, portKey)) return source;
+  return ensureDeferredPort(source, portKey);
+}
+
+function updateEnvExample(
+  source: string | undefined,
+  preset: ProviderPreset,
+): string | undefined {
+  if (preset.envVars.length === 0) {
+    return source;
+  }
+
+  const current = source ?? "";
+  if (preset.envVars.every((name) => hasEnvVar(current, name))) {
+    return current;
+  }
+
+  return appendSection(current, preset.envExample);
+}
+
+function updateIntegrationsDoc(
+  source: string | undefined,
+  preset: ProviderPreset,
+): string {
+  const current =
+    source ??
+    [
+      "# Integrations",
+      "",
+      "This file tracks app-level provider setup added after the initial scaffold.",
+      "",
+    ].join("\n");
+
+  if (current.includes(`## ${preset.displayName}`)) {
+    return current;
+  }
+
+  return appendSection(current, preset.docs);
+}
+
+function ensureNamedTypeImport(
+  source: string,
+  importName: string,
+  importFrom: string,
+): string {
+  if (hasNamedImport(source, importName, importFrom)) return source;
+
+  const importPattern = new RegExp(
+    `import\\s+type\\s+\\{([^}]*)\\}\\s+from\\s+["']${escapeRegExp(
+      importFrom,
+    )}["'];`,
+  );
+  const match = importPattern.exec(source);
+
+  if (!match) {
+    return insertAfterImports(
+      source,
+      `import type { ${importName} } from "${importFrom}";`,
+    );
+  }
+
+  const fullImport = match[0];
+  const imports = parseNamedImports(match[1]);
+  if (!imports.includes(importName)) imports.push(importName);
+  imports.sort((a, b) => a.localeCompare(b));
+
+  const replacement = fullImport.includes("\n")
+    ? `import type {\n${imports.map((name) => `\t${name},`).join("\n")}\n} from "${importFrom}";`
+    : `import type { ${imports.join(", ")} } from "${importFrom}";`;
+
+  return `${source.slice(0, match.index)}${replacement}${source.slice(
+    match.index + fullImport.length,
+  )}`;
+}
+
+function ensureTypeProperty(
+  source: string,
+  typeName: string,
+  key: string,
+  propertyType: string,
+): string {
+  const typeMatch = new RegExp(`export\\s+type\\s+${typeName}\\s*=`).exec(
+    source,
+  );
+  if (!typeMatch) {
+    throw new Error(
+      `Could not find \`export type ${typeName}\` in ports file.`,
+    );
+  }
+
+  const openBrace = source.indexOf("{", typeMatch.index);
+  if (openBrace === -1) {
+    throw new Error(
+      `Could not find object body for \`export type ${typeName}\`.`,
+    );
+  }
+
+  const closeBrace = matchingDelimiterIndex(source, openBrace, "{", "}");
+  if (closeBrace === -1) {
+    throw new Error(
+      `Could not parse object body for \`export type ${typeName}\`.`,
+    );
+  }
+
+  const body = source.slice(openBrace + 1, closeBrace);
+  if (new RegExp(`\\b${escapeRegExp(key)}\\s*:`).test(body)) {
+    return source;
+  }
+
+  const indentation = body.match(/\n([\t ]*)[A-Za-z_$]/)?.[1] ?? "\t";
+  const propertyLine = `${indentation}${key}: ${propertyType};\n`;
+  return `${source.slice(0, closeBrace)}${propertyLine}${source.slice(closeBrace)}`;
+}
+
+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.");
+  }
+
+  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.");
+  }
+
+  const arrayText = source.slice(openBracket, closeBracket + 1);
+  if (new RegExp(`["']${escapeRegExp(portKey)}["']`).test(arrayText)) {
+    return source;
+  }
+
+  const nextArray = appendToArrayExpression(arrayText, [`"${portKey}"`]);
+  return `${source.slice(0, openBracket)}${nextArray}${source.slice(
+    closeBracket + 1,
+  )}`;
+}
+
+function hasBoundPort(source: string, portKey: string): boolean {
+  const match = /\bbound\s*:\s*\{/.exec(source);
+  if (!match) return false;
+
+  const openBrace = source.indexOf("{", match.index);
+  const closeBrace = matchingDelimiterIndex(source, openBrace, "{", "}");
+  if (closeBrace === -1) return false;
+
+  const body = source.slice(openBrace + 1, closeBrace);
+  return new RegExp(`\\b${escapeRegExp(portKey)}\\s*:`).test(body);
+}
+
+function hasNamedImport(
+  source: string,
+  importName: string,
+  importFrom: string,
+): boolean {
+  const importPattern = new RegExp(
+    `import\\s+(?:type\\s+)?\\{([^}]*)\\}\\s+from\\s+["']${escapeRegExp(
+      importFrom,
+    )}["'];`,
+    "g",
+  );
+
+  for (const match of source.matchAll(importPattern)) {
+    if (parseNamedImports(match[1]).includes(importName)) return true;
+  }
+
+  return false;
+}
+
+function parseNamedImports(source: string): string[] {
+  return source
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) =>
+      entry
+        .replace(/^type\s+/, "")
+        .split(/\s+as\s+/)[0]
+        .trim(),
+    )
+    .filter(Boolean);
+}
+
+function hasEnvVar(source: string, name: string): boolean {
+  return new RegExp(`^#?\\s*${escapeRegExp(name)}\\s*=`, "m").test(source);
+}
+
+function appendSection(source: string, section: string): string {
+  const trimmedSource = source.replace(/\s*$/, "");
+  const trimmedSection = section.replace(/\s*$/, "");
+
+  if (!trimmedSource) return `${trimmedSection}\n`;
+  return `${trimmedSource}\n\n${trimmedSection}\n`;
+}
+
+function sortRecord(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(record).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+async function planFiles(
+  targetDir: string,
+  files: Array<{ path: string; content: string }>,
+): Promise<PlannedFile[]> {
+  const planned: PlannedFile[] = [];
+
+  for (const file of files) {
+    const existing = await readOptionalAppFile(targetDir, file.path);
+    planned.push({
+      ...file,
+      result:
+        existing === file.content
+          ? "skipped"
+          : existing === undefined
+            ? "created"
+            : "updated",
+    });
+  }
+
+  return planned;
+}
+
+async function writePlannedFile(
+  targetDir: string,
+  file: PlannedFile,
+): Promise<void> {
+  if (file.result === "skipped") return;
+
+  const destination = path.join(targetDir, file.path);
+  await mkdir(path.dirname(destination), { recursive: true });
+  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,
+): Promise<string | undefined> {
+  const absolutePath = path.join(targetDir, filePath);
+
+  try {
+    await stat(absolutePath);
+    return await readFile(absolutePath, "utf8");
+  } catch (error) {
+    if (isNotFoundError(error)) return undefined;
+    throw error;
+  }
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}