@alfredmouelle/create-stack 0.1.2 → 0.2.0

package/_stack/packages/storage/src/adapters/gcs/index.ts

@@ -0,0 +1,111 @@
+import { Storage } from '@google-cloud/storage'
+import * as v from 'valibot'
+import {
+  type PutOptions,
+  type SignedUrlOptions,
+  StorageError,
+  type StoragePort,
+} from '../../core/port.js'
+import { GcsConfigSchema } from './config.js'
+
+/** Structural view of a GCS file handle (eases testing). */
+export interface GcsFileLike {
+  save(data: Buffer | string, options?: { contentType?: string }): Promise<void>
+  download(): Promise<[Buffer]>
+  delete(): Promise<unknown>
+  exists(): Promise<[boolean]>
+  getSignedUrl(options: {
+    version: 'v4'
+    action: 'read' | 'write'
+    expires: number
+    contentType?: string
+  }): Promise<[string]>
+}
+
+/** Structural view of a GCS bucket handle. */
+export interface GcsBucketLike {
+  file(key: string): GcsFileLike
+}
+
+/** Structural view of the GCS Storage client. */
+export interface GcsStorageLike {
+  bucket(name: string): GcsBucketLike
+}
+
+export interface GcsAdapterOptions {
+  bucket: string
+  projectId?: string
+  /** Inject custom/mock client. Defaults to real `Storage`. */
+  client?: GcsStorageLike
+}
+
+const DEFAULT_EXPIRES_IN = 900
+
+function isNotFound(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false
+  return (error as { code?: number }).code === 404
+}
+
+export function gcsAdapter(options: GcsAdapterOptions): StoragePort {
+  // Validate early: missing config fails at construction, not use.
+  const config = v.parse(GcsConfigSchema, {
+    bucket: options.bucket,
+    projectId: options.projectId,
+  })
+
+  const client: GcsStorageLike =
+    options.client ?? (new Storage({ projectId: config.projectId }) as unknown as GcsStorageLike)
+
+  const bucket = client.bucket(config.bucket)
+
+  return {
+    name: 'gcs',
+    async put(key: string, data: Uint8Array | string, putOptions?: PutOptions) {
+      const body = typeof data === 'string' ? data : Buffer.from(data)
+      try {
+        await bucket.file(key).save(body, { contentType: putOptions?.contentType })
+      } catch (cause) {
+        throw new StorageError('GCS put failed', { adapter: 'gcs', cause })
+      }
+    },
+    async get(key: string) {
+      try {
+        const [contents] = await bucket.file(key).download()
+        return new Uint8Array(contents)
+      } catch (cause) {
+        if (isNotFound(cause)) return null
+        throw new StorageError('GCS get failed', { adapter: 'gcs', cause })
+      }
+    },
+    async delete(key: string) {
+      try {
+        await bucket.file(key).delete()
+      } catch (cause) {
+        if (isNotFound(cause)) return
+        throw new StorageError('GCS delete failed', { adapter: 'gcs', cause })
+      }
+    },
+    async exists(key: string) {
+      try {
+        const [found] = await bucket.file(key).exists()
+        return found
+      } catch (cause) {
+        throw new StorageError('GCS exists failed', { adapter: 'gcs', cause })
+      }
+    },
+    async getSignedUrl(key: string, urlOptions: SignedUrlOptions) {
+      const expiresInSeconds = urlOptions.expiresInSeconds ?? DEFAULT_EXPIRES_IN
+      try {
+        const [url] = await bucket.file(key).getSignedUrl({
+          version: 'v4',
+          action: urlOptions.operation === 'put' ? 'write' : 'read',
+          expires: Date.now() + expiresInSeconds * 1000,
+          contentType: urlOptions.contentType,
+        })
+        return url
+      } catch (cause) {
+        throw new StorageError('GCS getSignedUrl failed', { adapter: 'gcs', cause })
+      }
+    },
+  }
+}

package/_stack/packages/storage/src/adapters/local/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const LocalConfigSchema = v.object({
+  baseDir: v.pipe(v.string(), v.minLength(1, 'STORAGE_LOCAL_DIR is required')),
+  publicBaseUrl: v.optional(v.string()),
+})
+
+export type LocalConfig = v.InferOutput<typeof LocalConfigSchema>

package/_stack/packages/storage/src/adapters/local/index.ts

@@ -0,0 +1,78 @@
+import { mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import * as v from 'valibot'
+import {
+  type PutOptions,
+  type SignedUrlOptions,
+  StorageError,
+  type StoragePort,
+} from '../../core/port.js'
+import { LocalConfigSchema } from './config.js'
+
+export interface LocalAdapterOptions {
+  /** Root directory for stored objects. */
+  baseDir: string
+  /**
+   * Base URL prefixed to keys by {@link StoragePort.getSignedUrl}. NOT signed —
+   * returns `${publicBaseUrl}/${key}`. Dev/tests only.
+   */
+  publicBaseUrl?: string
+}
+
+function isNotFound(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false
+  return (error as { code?: string }).code === 'ENOENT'
+}
+
+export function localAdapter(options: LocalAdapterOptions): StoragePort {
+  const config = v.parse(LocalConfigSchema, {
+    baseDir: options.baseDir,
+    publicBaseUrl: options.publicBaseUrl,
+  })
+
+  const resolve = (key: string): string => join(config.baseDir, key)
+
+  return {
+    name: 'local',
+    async put(key: string, data: Uint8Array | string, _options?: PutOptions) {
+      const path = resolve(key)
+      try {
+        await mkdir(dirname(path), { recursive: true })
+        await writeFile(path, typeof data === 'string' ? data : Buffer.from(data))
+      } catch (cause) {
+        throw new StorageError('Local put failed', { adapter: 'local', cause })
+      }
+    },
+    async get(key: string) {
+      try {
+        const buffer = await readFile(resolve(key))
+        return new Uint8Array(buffer)
+      } catch (cause) {
+        if (isNotFound(cause)) return null
+        throw new StorageError('Local get failed', { adapter: 'local', cause })
+      }
+    },
+    async delete(key: string) {
+      try {
+        await unlink(resolve(key))
+      } catch (cause) {
+        if (isNotFound(cause)) return
+        throw new StorageError('Local delete failed', { adapter: 'local', cause })
+      }
+    },
+    async exists(key: string) {
+      try {
+        await stat(resolve(key))
+        return true
+      } catch (cause) {
+        if (isNotFound(cause)) return false
+        throw new StorageError('Local exists failed', { adapter: 'local', cause })
+      }
+    },
+    async getSignedUrl(key: string, _options: SignedUrlOptions) {
+      // No real signing; dev/test only.
+      const base = config.publicBaseUrl ?? ''
+      return `${base}/${key}`
+    },
+  }
+}

package/_stack/packages/storage/src/adapters/r2/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const R2ConfigSchema = v.object({
+  bucket: v.pipe(v.string(), v.minLength(1, 'R2_BUCKET is required')),
+  accountId: v.pipe(v.string(), v.minLength(1, 'R2_ACCOUNT_ID is required')),
+})
+
+export type R2Config = v.InferOutput<typeof R2ConfigSchema>

package/_stack/packages/storage/src/adapters/r2/index.ts

@@ -0,0 +1,39 @@
+import * as v from 'valibot'
+import type { StoragePort } from '../../core/port.js'
+import { type S3ClientLike, type S3Presigner, s3Adapter } from '../s3/index.js'
+import { R2ConfigSchema } from './config.js'
+
+/**
+ * R2 is S3-compatible: {@link s3Adapter} with R2's endpoint
+ * (`https://<accountId>.r2.cloudflarestorage.com`) and `auto` region. All behavior inherited.
+ */
+export interface R2AdapterOptions {
+  bucket: string
+  /** Cloudflare account id (forms the R2 endpoint). */
+  accountId: string
+  accessKeyId?: string
+  secretAccessKey?: string
+  /** Inject custom/mock client. Defaults to real `S3Client`. */
+  client?: S3ClientLike
+  /** Inject custom/mock presigner. */
+  presign?: S3Presigner
+}
+
+export function r2Adapter(options: R2AdapterOptions): StoragePort {
+  const config = v.parse(R2ConfigSchema, {
+    bucket: options.bucket,
+    accountId: options.accountId,
+  })
+
+  const s3 = s3Adapter({
+    bucket: config.bucket,
+    region: 'auto',
+    endpoint: `https://${config.accountId}.r2.cloudflarestorage.com`,
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    client: options.client,
+    presign: options.presign,
+  })
+
+  return { ...s3, name: 'r2' }
+}

package/_stack/packages/storage/src/adapters/s3/config.ts

@@ -0,0 +1,11 @@
+import * as v from 'valibot'
+
+export const S3ConfigSchema = v.object({
+  bucket: v.pipe(v.string(), v.minLength(1, 'S3_BUCKET is required')),
+  region: v.pipe(v.string(), v.minLength(1, 'S3_REGION is required')),
+  accessKeyId: v.optional(v.string()),
+  secretAccessKey: v.optional(v.string()),
+  endpoint: v.optional(v.string()),
+})
+
+export type S3Config = v.InferOutput<typeof S3ConfigSchema>

package/_stack/packages/storage/src/adapters/s3/index.ts

@@ -0,0 +1,143 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import * as v from 'valibot'
+import {
+  type PutOptions,
+  type SignedUrlOptions,
+  StorageError,
+  type StoragePort,
+} from '../../core/port.js'
+import { S3ConfigSchema } from './config.js'
+
+/** Structural view of the S3 client (eases testing). */
+export interface S3ClientLike {
+  send(command: unknown): Promise<unknown>
+}
+
+/** Presigner shape, injectable so tests never sign for real. */
+export type S3Presigner = (
+  client: S3ClientLike,
+  command: unknown,
+  options: { expiresIn: number },
+) => Promise<string>
+
+export interface S3AdapterOptions {
+  bucket: string
+  region: string
+  accessKeyId?: string
+  secretAccessKey?: string
+  endpoint?: string
+  /** Inject custom/mock client. Defaults to real `S3Client`. */
+  client?: S3ClientLike
+  /** Inject custom/mock presigner. Defaults to `@aws-sdk/s3-request-presigner`. */
+  presign?: S3Presigner
+}
+
+const DEFAULT_EXPIRES_IN = 900
+
+interface S3GetBody {
+  transformToByteArray(): Promise<Uint8Array>
+}
+
+interface S3GetResult {
+  // biome-ignore lint/style/useNamingConvention: mirrors the S3 SDK response shape (GetObjectCommandOutput.Body)
+  Body?: S3GetBody
+}
+
+function isNotFound(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false
+  const e = error as { name?: string; $metadata?: { httpStatusCode?: number } }
+  return e.name === 'NoSuchKey' || e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404
+}
+
+export function s3Adapter(options: S3AdapterOptions): StoragePort {
+  // Validate early: missing config fails at construction, not use.
+  const config = v.parse(S3ConfigSchema, {
+    bucket: options.bucket,
+    region: options.region,
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    endpoint: options.endpoint,
+  })
+
+  const client: S3ClientLike =
+    options.client ??
+    (new S3Client({
+      region: config.region,
+      endpoint: config.endpoint,
+      credentials:
+        config.accessKeyId && config.secretAccessKey
+          ? { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey }
+          : undefined,
+    }) as unknown as S3ClientLike)
+
+  const presign: S3Presigner = options.presign ?? (getSignedUrl as unknown as S3Presigner)
+
+  return {
+    name: 's3',
+    async put(key: string, data: Uint8Array | string, putOptions?: PutOptions) {
+      try {
+        await client.send(
+          new PutObjectCommand({
+            Bucket: config.bucket,
+            Key: key,
+            Body: data,
+            ContentType: putOptions?.contentType,
+          }),
+        )
+      } catch (cause) {
+        throw new StorageError('S3 put failed', { adapter: 's3', cause })
+      }
+    },
+    async get(key: string) {
+      try {
+        const result = (await client.send(
+          new GetObjectCommand({ Bucket: config.bucket, Key: key }),
+        )) as S3GetResult
+        if (!result.Body) return null
+        return await result.Body.transformToByteArray()
+      } catch (cause) {
+        if (isNotFound(cause)) return null
+        throw new StorageError('S3 get failed', { adapter: 's3', cause })
+      }
+    },
+    async delete(key: string) {
+      try {
+        await client.send(new DeleteObjectCommand({ Bucket: config.bucket, Key: key }))
+      } catch (cause) {
+        throw new StorageError('S3 delete failed', { adapter: 's3', cause })
+      }
+    },
+    async exists(key: string) {
+      try {
+        await client.send(new HeadObjectCommand({ Bucket: config.bucket, Key: key }))
+        return true
+      } catch (cause) {
+        if (isNotFound(cause)) return false
+        throw new StorageError('S3 exists failed', { adapter: 's3', cause })
+      }
+    },
+    async getSignedUrl(key: string, urlOptions: SignedUrlOptions) {
+      const expiresIn = urlOptions.expiresInSeconds ?? DEFAULT_EXPIRES_IN
+      const command =
+        urlOptions.operation === 'put'
+          ? new PutObjectCommand({
+              Bucket: config.bucket,
+              Key: key,
+              ContentType: urlOptions.contentType,
+            })
+          : new GetObjectCommand({ Bucket: config.bucket, Key: key })
+      try {
+        return await presign(client, command, { expiresIn })
+      } catch (cause) {
+        throw new StorageError('S3 getSignedUrl failed', { adapter: 's3', cause })
+      }
+    },
+  }
+}

package/_stack/packages/storage/src/core/port.ts

@@ -0,0 +1,41 @@
+/** Write options. */
+export interface PutOptions {
+  /** MIME type stored with the object (e.g. `image/png`). */
+  contentType?: string
+}
+
+/** Signed-URL options. */
+export interface SignedUrlOptions {
+  /** Download (`get`) or upload (`put`). */
+  operation: 'get' | 'put'
+  /** Validity window. Adapters apply a default. */
+  expiresInSeconds?: number
+  /** Constrain content type for `put` URLs. */
+  contentType?: string
+}
+
+/** The port the app depends on. Swap provider = swap adapter; this never changes. */
+export interface StoragePort {
+  readonly name: string
+  /** Write `data` at `key`, creating or overwriting. */
+  put(key: string, data: Uint8Array | string, options?: PutOptions): Promise<void>
+  /** Read bytes at `key`, or `null` if absent. */
+  get(key: string): Promise<Uint8Array | null>
+  /** Remove `key`. No-op if missing. */
+  delete(key: string): Promise<void>
+  /** Whether `key` exists. */
+  exists(key: string): Promise<boolean>
+  /** Mint a time-limited URL for `key`. */
+  getSignedUrl(key: string, options: SignedUrlOptions): Promise<string>
+}
+
+/** Normalized adapter error so callers never catch provider types. */
+export class StorageError extends Error {
+  readonly adapter: string
+
+  constructor(message: string, options: { adapter: string; cause?: unknown }) {
+    super(message, { cause: options.cause })
+    this.name = 'StorageError'
+    this.adapter = options.adapter
+  }
+}

package/_stack/packages/storage/src/index.ts

@@ -0,0 +1,21 @@
+export { type GcsConfig, GcsConfigSchema } from './adapters/gcs/config.js'
+export {
+  type GcsAdapterOptions,
+  type GcsBucketLike,
+  type GcsFileLike,
+  type GcsStorageLike,
+  gcsAdapter,
+} from './adapters/gcs/index.js'
+export { type LocalConfig, LocalConfigSchema } from './adapters/local/config.js'
+export { type LocalAdapterOptions, localAdapter } from './adapters/local/index.js'
+export { type R2Config, R2ConfigSchema } from './adapters/r2/config.js'
+export { type R2AdapterOptions, r2Adapter } from './adapters/r2/index.js'
+export { type S3Config, S3ConfigSchema } from './adapters/s3/config.js'
+export {
+  type S3AdapterOptions,
+  type S3ClientLike,
+  type S3Presigner,
+  s3Adapter,
+} from './adapters/s3/index.js'
+export type { PutOptions, SignedUrlOptions, StoragePort } from './core/port.js'
+export { StorageError } from './core/port.js'

package/index.mjs

@@ -6,6 +6,12 @@
 import { resolve } from 'node:path'
 import * as p from '@clack/prompts'
 import { buildProject } from './lib/build.mjs'
+import {
+  adapterChoices,
+  CAPABILITIES,
+  capabilityChoices,
+  resolveAdapter,
+} from './lib/capabilities.mjs'
 import { isDirEmpty, run } from './lib/util.mjs'
 
 const ALL_FOUNDATIONS = ['drizzle', 'trpc', 'better-auth', 'data-table']
@@ -56,14 +62,24 @@ function normalize(picked, mailer) {
   return { kept, mailerProvider }
 }
 
+/** Read --<capability> flags into { capability: adapter } (default adapter if bare). */
+function collectCapabilityFlags(flags) {
+  const out = {}
+  for (const cap of CAPABILITIES) {
+    if (cap in flags) out[cap] = resolveAdapter(cap, flags[cap])
+  }
+  return out
+}
+
 function collectFromFlags(args) {
   const argDir = args._[0]
   if (!argDir) throw new Error('Project name is required (positional) in non-interactive mode')
   const framework = args.flags.framework === 'next' ? 'next' : 'tanstack'
   const picked = args.flags.foundations ? csv(args.flags.foundations) : [...ALL_FOUNDATIONS]
   const { kept, mailerProvider } = normalize(picked, args.flags.mailer)
+  const capabilities = collectCapabilityFlags(args.flags)
   const doInstall = !args.flags['no-install']
-  return { argDir, projectName: argDir, framework, kept, mailerProvider, doInstall }
+  return { argDir, projectName: argDir, framework, kept, mailerProvider, capabilities, doInstall }
 }
 
 async function collectFromPrompts(argDir) {
@@ -118,12 +134,56 @@ async function collectFromPrompts(argDir) {
     }),
   )
 
+  const capPicked = cancelled(
+    await p.multiselect({
+      message: 'Capabilities (space to toggle, swappable behind a port)',
+      required: false,
+      initialValues: [],
+      options: capabilityChoices(),
+    }),
+  )
+
+  const capabilities = {}
+  for (const cap of capPicked) {
+    const { defaultAdapter, options } = adapterChoices(cap)
+    capabilities[cap] = cancelled(
+      await p.select({
+        message: `${cap} adapter`,
+        options,
+        initialValue: defaultAdapter,
+      }),
+    )
+  }
+
   const doInstall = cancelled(
     await p.confirm({ message: 'Install dependencies and verify now?', initialValue: true }),
   )
 
   const { kept, mailerProvider } = normalize(picked, mailer)
-  return { argDir, projectName, framework, kept, mailerProvider, doInstall }
+  return { argDir, projectName, framework, kept, mailerProvider, capabilities, doInstall }
+}
+
+const pnpmRun = (script, projectDir, opts = {}) =>
+  run('pnpm', ['--config.verify-deps-before-run=false', 'run', script], {
+    cwd: projectDir,
+    ...opts,
+  })
+
+/** Install deps, normalize vendored imports, then report typecheck + biome status. */
+function installAndVerify(projectDir, capabilities) {
+  p.log.step('pnpm install')
+  run('pnpm', ['install'], { cwd: projectDir })
+  // vendored capabilities rewrite cross-package imports (~/lib/http); let biome
+  // re-sort/normalize them so the initial commit is lint-clean.
+  if (Object.keys(capabilities ?? {}).length) {
+    pnpmRun('check:write', projectDir, { stdio: 'ignore' })
+  }
+  p.log.step('Verifying (typecheck + biome)')
+  const tc = pnpmRun('typecheck', projectDir)
+  const lint = pnpmRun('check', projectDir)
+  p.log[tc && lint ? 'success' : 'warn'](
+    tc && lint ? 'typecheck + biome clean' : 'verify reported issues (see output above)',
+  )
 }
 
 function execute(a) {
@@ -138,20 +198,7 @@ function execute(a) {
   buildProject({ ...a, projectDir })
   s.stop('Project scaffolded')
 
-  if (a.doInstall) {
-    p.log.step('pnpm install')
-    run('pnpm', ['install'], { cwd: projectDir })
-    p.log.step('Verifying (typecheck + biome)')
-    const tc = run('pnpm', ['--config.verify-deps-before-run=false', 'run', 'typecheck'], {
-      cwd: projectDir,
-    })
-    const lint = run('pnpm', ['--config.verify-deps-before-run=false', 'run', 'check'], {
-      cwd: projectDir,
-    })
-    p.log[tc && lint ? 'success' : 'warn'](
-      tc && lint ? 'typecheck + biome clean' : 'verify reported issues (see output above)',
-    )
-  }
+  if (a.doInstall) installAndVerify(projectDir, a.capabilities)
 
   // fresh repo + initial commit (also satisfies Biome vcs.useIgnoreFile).
   // commit is best-effort: skipped if git identity unset, staged tree left in place.
@@ -170,12 +217,14 @@ function execute(a) {
   }
 
   const keptMailer = a.mailerProvider !== 'none'
+  const capEntries = Object.entries(a.capabilities ?? {})
   const lines = [
     `Framework: ${a.framework === 'next' ? 'Next.js' : 'TanStack Start'}`,
     `Foundations: ${[...a.kept].sort().join(', ') || '(none)'}`,
     `Mailer: ${keptMailer ? a.mailerProvider : '(none)'}`,
+    `Capabilities: ${capEntries.map(([c, ad]) => `${c} (${ad})`).join(', ') || '(none)'}`,
     '',
-    'Add more tools (storage, jobs, cache, analytics, …) with the add-capability skill.',
+    'Add more tools later with the add-capability skill.',
     '',
     'Next:',
     `  cd ${a.argDir ?? a.projectName}`,
@@ -192,7 +241,9 @@ async function main() {
   const nonInteractive =
     args.flags.yes ||
     args.flags.y ||
-    ['framework', 'foundations', 'mailer', 'no-install'].some((k) => k in args.flags)
+    ['framework', 'foundations', 'mailer', 'no-install', ...CAPABILITIES].some(
+      (k) => k in args.flags,
+    )
 
   const answers = nonInteractive ? collectFromFlags(args) : await collectFromPrompts(args._[0])
 

package/lib/build.mjs

@@ -1,6 +1,7 @@
 // Pure build phase (no prompts/install): fork → strip → mailer → env → identity.
 // Shared by index.mjs (post-wizard) and the test harness.
 
+import { vendorCapability } from './capabilities.mjs'
 import { writeEnv } from './env.mjs'
 import { stampIdentity } from './identity.mjs'
 import { swapMailer } from './mailer.mjs'
@@ -15,9 +16,17 @@ import { join, pkgAddDeps, pkgRemoveDeps, pkgRemoveScripts, readJSON, writeJSON
  * @param {'next'|'tanstack'} o.framework
  * @param {Set<string>} o.kept   foundations to keep (deps pre-resolved)
  * @param {'resend'|'brevo'|'ses'|'none'} o.mailerProvider
- * @returns {{ kept: string[], keptMailer: boolean, mailerProvider: string, envKeys: string[] }}
+ * @param {Record<string,string>} [o.capabilities]  capability → adapter (e.g. { storage: 's3' })
+ * @returns {{ kept: string[], keptMailer: boolean, mailerProvider: string, capabilities: Record<string,string>, envKeys: string[] }}
  */
-export function buildProject({ projectDir, projectName, framework, kept, mailerProvider }) {
+export function buildProject({
+  projectDir,
+  projectName,
+  framework,
+  kept,
+  mailerProvider,
+  capabilities = {},
+}) {
   const authKept = kept.has('better-auth')
   const keptMailer = mailerProvider !== 'none'
 
@@ -29,12 +38,21 @@ export function buildProject({ projectDir, projectName, framework, kept, mailerP
     ? swapMailer(projectDir, mailerProvider)
     : { addDeps: {}, removeDeps: [], envKeys: [] }
 
+  // vendor each selected capability (core + adapter + composition root) into the fork.
+  const capAddDeps = {}
+  const capEnvKeys = []
+  for (const [cap, adapter] of Object.entries(capabilities)) {
+    const r = vendorCapability({ projectDir, framework, projectName, cap, adapter })
+    Object.assign(capAddDeps, r.addDeps)
+    capEnvKeys.push(...r.envKeys)
+  }
+
   const pkgPath = join(projectDir, 'package.json')
   const pkg = readJSON(pkgPath)
   pkg.description = `${projectName} — scaffolded from the personal reference stack.`
   pkgRemoveDeps(pkg, [...strip.removeDeps, ...mailer.removeDeps])
   pkgRemoveScripts(pkg, strip.removeScripts)
-  pkgAddDeps(pkg, mailer.addDeps)
+  pkgAddDeps(pkg, { ...mailer.addDeps, ...capAddDeps })
   writeJSON(pkgPath, pkg)
 
   const envKeys = []
@@ -47,10 +65,10 @@ export function buildProject({ projectDir, projectName, framework, kept, mailerP
       'BETTER_AUTH_GOOGLE_CLIENT_SECRET',
     )
   }
-  envKeys.push(...mailer.envKeys)
+  envKeys.push(...mailer.envKeys, ...capEnvKeys)
   writeEnv(projectDir, envKeys)
 
   stampIdentity(projectDir, projectName, framework)
 
-  return { kept: [...kept], keptMailer, mailerProvider, envKeys }
+  return { kept: [...kept], keptMailer, mailerProvider, capabilities, envKeys }
 }