@alfredmouelle/create-stack 0.1.1 → 0.2.0

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

@@ -1,20 +1,19 @@
 #!/usr/bin/env node
-// create-stack — deterministic installer for the personal reference stack.
-// The non-LLM counterpart of the bootstrap skill's CREATE mode: fork a base
-// app, strip it to the selection, stamp identity, verify.
-//
-// Interactive by default. Non-interactive when any selection flag (or --yes) is
-// passed — useful for scripts/CI and for headless end-to-end testing:
+// create-stack — fork a base app, strip to selection, stamp identity, verify.
+// Interactive by default; non-interactive when any selection flag (or --yes) is passed:
 //   create-stack my-app --framework next --foundations drizzle,trpc --mailer ses --no-install
 
 import { resolve } from 'node:path'
 import * as p from '@clack/prompts'
 import { buildProject } from './lib/build.mjs'
-import { loadCapabilities, loadPatterns } from './lib/manifests.mjs'
+import {
+  adapterChoices,
+  CAPABILITIES,
+  capabilityChoices,
+  resolveAdapter,
+} from './lib/capabilities.mjs'
 import { isDirEmpty, run } from './lib/util.mjs'
 
-// Capabilities baked into the base apps vs. the ones add-capability supplies.
-const BAKED_CAPS = new Set(['mailer', 'email-kit'])
 const ALL_FOUNDATIONS = ['drizzle', 'trpc', 'better-auth', 'data-table']
 
 const cancelled = (v) => {
@@ -54,7 +53,7 @@ const csv = (v) =>
         .filter(Boolean)
     : []
 
-/** Resolve hard deps + the mailer's better-auth requirement. */
+/** Resolve hard deps + mailer's better-auth requirement. */
 function normalize(picked, mailer) {
   const kept = new Set(picked.filter((f) => ALL_FOUNDATIONS.includes(f)))
   if (kept.has('trpc') || kept.has('better-auth')) kept.add('drizzle')
@@ -63,19 +62,27 @@ function normalize(picked, mailer) {
   return { kept, mailerProvider }
 }
 
-function collectFromFlags(args, capabilities) {
+/** 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 validCaps = new Set(Object.keys(capabilities).filter((c) => !BAKED_CAPS.has(c)))
-  const extraCaps = csv(args.flags.caps).filter((c) => validCaps.has(c))
+  const capabilities = collectCapabilityFlags(args.flags)
   const doInstall = !args.flags['no-install']
-  return { argDir, projectName: argDir, framework, kept, mailerProvider, extraCaps, doInstall }
+  return { argDir, projectName: argDir, framework, kept, mailerProvider, capabilities, doInstall }
 }
 
-async function collectFromPrompts(argDir, capabilities) {
+async function collectFromPrompts(argDir) {
   p.intro('create-stack — fork a base app, strip it to your selection')
 
   const name = cancelled(
@@ -127,26 +134,59 @@ async function collectFromPrompts(argDir, capabilities) {
     }),
   )
 
-  const extraCaps = cancelled(
+  const capPicked = cancelled(
     await p.multiselect({
-      message: 'Extra capabilities (optional — added via add-capability)',
+      message: 'Capabilities (space to toggle, swappable behind a port)',
       required: false,
       initialValues: [],
-      options: Object.keys(capabilities)
-        .filter((c) => !BAKED_CAPS.has(c))
-        .map((c) => ({ value: c, label: c, hint: capabilities[c].description?.slice(0, 40) })),
+      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, extraCaps, doInstall }
+  return { argDir, projectName, framework, kept, mailerProvider, capabilities, doInstall }
 }
 
-function execute(a, patterns) {
+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) {
   const projectDir = resolve(process.cwd(), a.argDir ?? a.projectName)
   if (!isDirEmpty(projectDir)) {
     p.cancel(`Target directory is not empty: ${projectDir}`)
@@ -155,44 +195,40 @@ function execute(a, patterns) {
 
   const s = p.spinner()
   s.start('Forking + stripping the base app')
-  buildProject({ ...a, projectDir, patterns })
+  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)
 
-  // Initialize a fresh repo (also satisfies Biome's vcs.useIgnoreFile).
-  if (run('git', ['init', '-q'], { cwd: projectDir })) {
+  // fresh repo + initial commit (also satisfies Biome vcs.useIgnoreFile).
+  // commit is best-effort: skipped if git identity unset, staged tree left in place.
+  if (run('git', ['-C', projectDir, 'init', '-q'])) {
     run('git', ['-C', projectDir, 'add', '-A'])
-    p.log.step('git initialized')
+    const committed = run(
+      'git',
+      ['-C', projectDir, 'commit', '-q', '-m', 'chore: initial commit from create-stack'],
+      { stdio: 'ignore' },
+    )
+    p.log.step(
+      committed
+        ? 'git repository initialized (initial commit created)'
+        : 'git repository initialized — set git user.name/email, then commit',
+    )
   }
 
   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 later with the add-capability skill.',
+    '',
+    'Next:',
+    `  cd ${a.argDir ?? a.projectName}`,
   ]
-  if (a.extraCaps.length) {
-    lines.push(
-      '',
-      'Add the extra capabilities with the add-capability skill:',
-      ...a.extraCaps.map((c) => `  • ${c}`),
-    )
-  }
-  lines.push('', 'Next:', `  cd ${a.argDir ?? a.projectName}`)
   if (!a.doInstall) lines.push('  pnpm install')
   lines.push('  cp .env.example .env   # fill in the values', '  pnpm dev')
   p.note(lines.join('\n'), 'Done')
@@ -200,20 +236,18 @@ function execute(a, patterns) {
 }
 
 async function main() {
-  const patterns = loadPatterns()
-  const capabilities = loadCapabilities()
   const args = parseArgs(process.argv.slice(2))
 
   const nonInteractive =
     args.flags.yes ||
     args.flags.y ||
-    ['framework', 'foundations', 'mailer', 'caps', '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, capabilities)
-    : await collectFromPrompts(args._[0], capabilities)
+  const answers = nonInteractive ? collectFromFlags(args) : await collectFromPrompts(args._[0])
 
-  execute(answers, patterns)
+  execute(answers)
 }
 
 main().catch((err) => {

package/lib/build.mjs

@@ -1,6 +1,7 @@
-// Pure build phase (no prompts, no install) — fork → strip → mailer → env →
-// identity. Shared by index.mjs (after the wizard) and the test harness.
+// 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'
@@ -13,10 +14,10 @@ import { join, pkgAddDeps, pkgRemoveDeps, pkgRemoveScripts, readJSON, writeJSON
  * @param {string} o.projectDir  absolute target dir (must be empty)
  * @param {string} o.projectName
  * @param {'next'|'tanstack'} o.framework
- * @param {Set<string>} o.kept   logical foundations to keep (deps pre-resolved)
+ * @param {Set<string>} o.kept   foundations to keep (deps pre-resolved)
  * @param {'resend'|'brevo'|'ses'|'none'} o.mailerProvider
- * @param {object} o.patterns    loadPatterns()
- * @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,
@@ -24,7 +25,7 @@ export function buildProject({
   framework,
   kept,
   mailerProvider,
-  patterns,
+  capabilities = {},
 }) {
   const authKept = kept.has('better-auth')
   const keptMailer = mailerProvider !== 'none'
@@ -32,17 +33,26 @@ export function buildProject({
   forkBase(framework, projectDir)
   makeStandalone(projectDir, projectName, framework)
 
-  const strip = stripFoundations({ projectDir, framework, kept, keptMailer, patterns })
+  const strip = stripFoundations({ projectDir, framework, kept, keptMailer })
   const mailer = keptMailer
     ? 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} — bootstrapped from the personal reference stack.`
+  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 = []
@@ -55,10 +65,10 @@ export function buildProject({
       '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 }
 }