@alfredmouelle/create-stack 0.1.2 → 0.2.0

package/_stack/packages/jobs/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alfredmouelle/jobs",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@alfredmouelle/http": "workspace:*",
+    "@trigger.dev/sdk": "^4.4.6",
+    "inngest": "^4.7.0",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/jobs/src/adapters/inngest/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const InngestConfigSchema = v.object({
+  id: v.pipe(v.string(), v.minLength(1, 'Inngest app id is required')),
+  eventKey: v.optional(v.string()),
+})
+
+export type InngestConfig = v.InferOutput<typeof InngestConfigSchema>

package/_stack/packages/jobs/src/adapters/inngest/index.ts

@@ -0,0 +1,93 @@
+import type { FetchHandler } from '@alfredmouelle/http'
+import { Inngest } from 'inngest'
+import * as v from 'valibot'
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+import { JobsError } from '../../core/port.js'
+import { InngestConfigSchema } from './config.js'
+
+/** Opaque Inngest function from `createFunction`. */
+export type InngestFunction = unknown
+
+/** Structural view of the Inngest client; real `Inngest` satisfies it, tests mock it. */
+export interface InngestLike {
+  send(payload: { name: string; data: unknown }): Promise<unknown>
+  createFunction(
+    config: { id: string },
+    trigger: { event: string },
+    handler: (ctx: { event: { name: string; data: unknown } }) => Promise<void> | void,
+  ): InngestFunction
+}
+
+export interface InngestAdapterOptions {
+  /** Inngest app id (`new Inngest({ id })`). */
+  id: string
+  /** Inject custom/mock client. Defaults to real `Inngest`. */
+  client?: InngestLike
+  /** Event key for sending in production. */
+  eventKey?: string
+}
+
+export interface InngestJobsAdapter extends JobsPort {
+  /** Functions from `defineJob`, for Inngest's `serve`. */
+  readonly functions: InngestFunction[]
+  /** Underlying client for advanced use (steps, cron, concurrency, …). */
+  readonly client: InngestLike
+}
+
+export function inngestAdapter(options: InngestAdapterOptions): InngestJobsAdapter {
+  // Validate early: bad id fails at construction, not trigger().
+  const config = v.parse(InngestConfigSchema, { id: options.id, eventKey: options.eventKey })
+  const client: InngestLike =
+    options.client ??
+    (new Inngest({ id: config.id, eventKey: config.eventKey }) as unknown as InngestLike)
+
+  const functions: InngestFunction[] = []
+
+  return {
+    name: 'inngest',
+    functions,
+    client,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const fn = client.createFunction({ id: def.id }, { event: def.event }, ({ event }) =>
+        def.handler(event as JobEvent<T>),
+      )
+      functions.push(fn)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      try {
+        await client.send({ name: event.name, data: event.data })
+      } catch (cause) {
+        throw new JobsError('Failed to send event to Inngest', { adapter: 'inngest', cause })
+      }
+    },
+  }
+}
+
+/** Collect functions for `serve({ client, functions })`. */
+export function inngestFunctions(adapter: InngestJobsAdapter): InngestFunction[] {
+  return adapter.functions
+}
+
+/**
+ * Inngest's framework-agnostic `serve` (e.g. `inngest/edge`). Loosely typed so
+ * the real `serve` (richer options than our `InngestLike`) is accepted.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: accepts the real serve whose options are richer than InngestLike
+export type InngestServe = (options: any) => FetchHandler
+
+/**
+ * {@link FetchHandler} serving the adapter's functions. Pass Inngest's `serve`
+ * (from `inngest/edge`); the handler mounts in Next.js or TanStack Start unchanged.
+ */
+export function inngestServeHandler<TServe extends InngestServe>(
+  adapter: InngestJobsAdapter,
+  serve: TServe,
+  options: { signingKey?: string } = {},
+): FetchHandler {
+  return serve({
+    client: adapter.client,
+    functions: adapter.functions,
+    signingKey: options.signingKey,
+  } as Parameters<TServe>[0])
+}

package/_stack/packages/jobs/src/adapters/memory/index.ts

@@ -0,0 +1,31 @@
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+
+export interface MemoryJobsAdapter extends JobsPort {
+  /** Registered jobs, keyed by subscribed event name. */
+  readonly jobs: ReadonlyMap<string, JobDefinition[]>
+}
+
+/**
+ * In-process jobs adapter for dev/tests. `trigger` runs every matching handler
+ * inline (awaiting async) — no queue, no network. Unit-test jobs without Inngest.
+ */
+export function memoryAdapter(): MemoryJobsAdapter {
+  const jobs = new Map<string, JobDefinition[]>()
+
+  return {
+    name: 'memory',
+    jobs,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const existing = jobs.get(def.event) ?? []
+      existing.push(def as JobDefinition)
+      jobs.set(def.event, existing)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      const handlers = jobs.get(event.name) ?? []
+      for (const def of handlers) {
+        await def.handler(event)
+      }
+    },
+  }
+}

package/_stack/packages/jobs/src/adapters/trigger/config.ts

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const TriggerDevConfigSchema = v.object({
+  /** Trigger auth key. Falls back to `TRIGGER_SECRET_KEY`. */
+  secretKey: v.optional(v.string()),
+})
+
+export type TriggerDevConfig = v.InferOutput<typeof TriggerDevConfigSchema>

package/_stack/packages/jobs/src/adapters/trigger/index.ts

@@ -0,0 +1,85 @@
+import { configure, task, tasks } from '@trigger.dev/sdk'
+import * as v from 'valibot'
+import type { JobDefinition, JobEvent, JobsPort } from '../../core/port.js'
+import { JobsError } from '../../core/port.js'
+import { TriggerDevConfigSchema } from './config.js'
+
+/** Opaque Trigger.dev task from `task()`. */
+export type TriggerTask = unknown
+
+/** Structural view of the Trigger.dev SDK; real `task`/`tasks.trigger` satisfy it, tests mock it. */
+export interface TriggerDevLike {
+  task(config: { id: string; run: (payload: unknown) => Promise<void> | void }): TriggerTask
+  trigger(id: string, payload: unknown): Promise<unknown>
+}
+
+export interface TriggerDevAdapterOptions {
+  /** Trigger auth key. Defaults to `TRIGGER_SECRET_KEY`. */
+  secretKey?: string
+  /** Inject custom/mock SDK. Defaults to real `@trigger.dev/sdk`. */
+  client?: TriggerDevLike
+}
+
+export interface TriggerDevJobsAdapter extends JobsPort {
+  /** Tasks from `defineJob`, to re-export from your Trigger.dev `dirs`. */
+  readonly tasks: TriggerTask[]
+}
+
+/** Bridge real SDK to {@link TriggerDevLike}; richer signatures narrowed here. */
+function defaultClient(secretKey?: string): TriggerDevLike {
+  if (secretKey) configure({ secretKey })
+  return {
+    task: task as unknown as TriggerDevLike['task'],
+    trigger: (id, payload) =>
+      (tasks.trigger as (id: string, payload: unknown) => Promise<unknown>)(id, payload),
+  }
+}
+
+/**
+ * Trigger.dev jobs adapter. Each {@link JobDefinition} becomes a task; `trigger`
+ * routes an event to every task subscribed to its `name`.
+ *
+ * No event bus (tasks trigger by id), so the adapter keeps an event → task-ids
+ * map and fans out on `trigger`. Created tasks collect on `adapter.tasks` for
+ * re-export from a file under your `dirs` (how the CLI discovers them).
+ */
+export function triggerDevAdapter(options: TriggerDevAdapterOptions = {}): TriggerDevJobsAdapter {
+  const config = v.parse(TriggerDevConfigSchema, { secretKey: options.secretKey })
+  const client: TriggerDevLike = options.client ?? defaultClient(config.secretKey)
+
+  const createdTasks: TriggerTask[] = []
+  // event name -> subscribed task ids
+  const routes = new Map<string, string[]>()
+
+  return {
+    name: 'trigger.dev',
+    tasks: createdTasks,
+    defineJob<T>(def: JobDefinition<T>): JobDefinition<T> {
+      const created = client.task({
+        id: def.id,
+        run: (payload) => def.handler({ name: def.event, data: payload } as JobEvent<T>),
+      })
+      createdTasks.push(created)
+      const ids = routes.get(def.event) ?? []
+      ids.push(def.id)
+      routes.set(def.event, ids)
+      return def
+    },
+    async trigger<T>(event: JobEvent<T>): Promise<void> {
+      const ids = routes.get(event.name) ?? []
+      try {
+        await Promise.all(ids.map((id) => client.trigger(id, event.data)))
+      } catch (cause) {
+        throw new JobsError('Failed to trigger Trigger.dev task', {
+          adapter: 'trigger.dev',
+          cause,
+        })
+      }
+    },
+  }
+}
+
+/** Collect tasks to re-export from a file under your `dirs`. */
+export function triggerDevTasks(adapter: TriggerDevJobsAdapter): TriggerTask[] {
+  return adapter.tasks
+}

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

@@ -0,0 +1,37 @@
+/** Event through the jobs system. `name` routes to subscribed jobs; `data` is the serializable payload. */
+export interface JobEvent<T = unknown> {
+  name: string
+  data: T
+}
+
+/** Background work unit. Subscribes to one `event` name; `handler` runs on a matching event. */
+export interface JobDefinition<T = unknown> {
+  id: string
+  event: string
+  handler: (event: JobEvent<T>) => Promise<void> | void
+}
+
+/**
+ * The port the app depends on. Swap provider = swap adapter; this never changes.
+ *
+ * Minimal and event-driven. Rich provider features (steps, concurrency, cron,
+ * fan-out) are NOT modeled — use the underlying SDK directly. See the README.
+ */
+export interface JobsPort {
+  readonly name: string
+  /** Register a job. Returns the definition for collection/export. */
+  defineJob<T>(def: JobDefinition<T>): JobDefinition<T>
+  /** Emit an event, triggering every job subscribed to `event.name`. */
+  trigger<T>(event: JobEvent<T>): Promise<void>
+}
+
+/** Normalized adapter error so callers never catch provider types. */
+export class JobsError extends Error {
+  readonly adapter: string
+
+  constructor(message: string, options: { adapter: string; cause?: unknown }) {
+    super(message, { cause: options.cause })
+    this.name = 'JobsError'
+    this.adapter = options.adapter
+  }
+}

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

@@ -0,0 +1,23 @@
+export { type InngestConfig, InngestConfigSchema } from './adapters/inngest/config.js'
+export {
+  type InngestAdapterOptions,
+  type InngestFunction,
+  type InngestJobsAdapter,
+  type InngestLike,
+  type InngestServe,
+  inngestAdapter,
+  inngestFunctions,
+  inngestServeHandler,
+} from './adapters/inngest/index.js'
+export { type MemoryJobsAdapter, memoryAdapter } from './adapters/memory/index.js'
+export { type TriggerDevConfig, TriggerDevConfigSchema } from './adapters/trigger/config.js'
+export {
+  type TriggerDevAdapterOptions,
+  type TriggerDevJobsAdapter,
+  type TriggerDevLike,
+  type TriggerTask,
+  triggerDevAdapter,
+  triggerDevTasks,
+} from './adapters/trigger/index.js'
+export type { JobDefinition, JobEvent, JobsPort } from './core/port.js'
+export { JobsError } from './core/port.js'

package/_stack/packages/logger/capability.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "logger",
+  "description": "Structured logging behind a swappable port. Application code depends only on the Logger interface; pick an adapter (pino, console) at the composition root.",
+  "port": "src/core/port.ts",
+  "defaultAdapter": "pino",
+  "adapters": {
+    "pino": {
+      "deps": ["pino"],
+      "env": [],
+      "files": ["src/adapters/pino"]
+    },
+    "console": {
+      "deps": [],
+      "env": [],
+      "files": ["src/adapters/console"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/logger/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@alfredmouelle/logger",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pino": "^10.3.1",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/_stack/packages/logger/src/adapters/console/config.ts

@@ -0,0 +1,7 @@
+import * as v from 'valibot'
+
+export const ConsoleConfigSchema = v.object({
+  level: v.optional(v.picklist(['trace', 'debug', 'info', 'warn', 'error'] as const), 'info'),
+})
+
+export type ConsoleConfig = v.InferOutput<typeof ConsoleConfigSchema>

package/_stack/packages/logger/src/adapters/console/index.ts

@@ -0,0 +1,69 @@
+import * as v from 'valibot'
+import type { LogFields, Logger, LogLevel } from '../../core/port.js'
+import { ConsoleConfigSchema } from './config.js'
+
+export interface ConsoleAdapterOptions {
+  /** Min level to emit; lower-severity dropped. Defaults to `'info'`. */
+  level?: LogLevel
+  /** Fields pinned onto every line. */
+  bindings?: LogFields
+}
+
+const ORDER: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+}
+
+const SINK: Record<LogLevel, (...args: unknown[]) => void> = {
+  // biome-ignore lint/suspicious/noConsole: console adapter
+  trace: (...args) => console.debug(...args),
+  // biome-ignore lint/suspicious/noConsole: console adapter
+  debug: (...args) => console.debug(...args),
+  // biome-ignore lint/suspicious/noConsole: console adapter
+  info: (...args) => console.info(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args),
+}
+
+function format(level: LogLevel, msg: string, fields: LogFields): string {
+  const hasFields = Object.keys(fields).length > 0
+  return hasFields ? `[${level}] ${msg} ${JSON.stringify(fields)}` : `[${level}] ${msg}`
+}
+
+function build(min: number, bindings: LogFields): Logger {
+  const log = (level: LogLevel, msg: string, fields: LogFields = {}) => {
+    if (ORDER[level] < min) return
+    const merged = { ...bindings, ...fields }
+    SINK[level](format(level, msg, merged))
+  }
+
+  return {
+    name: 'console',
+    trace(msg, fields) {
+      log('trace', msg, fields)
+    },
+    debug(msg, fields) {
+      log('debug', msg, fields)
+    },
+    info(msg, fields) {
+      log('info', msg, fields)
+    },
+    warn(msg, fields) {
+      log('warn', msg, fields)
+    },
+    error(msg, fields) {
+      log('error', msg, fields)
+    },
+    child(childBindings) {
+      return build(min, { ...bindings, ...childBindings })
+    },
+  }
+}
+
+export function consoleAdapter(options: ConsoleAdapterOptions = {}): Logger {
+  const config = v.parse(ConsoleConfigSchema, { level: options.level })
+  return build(ORDER[config.level], options.bindings ?? {})
+}

package/_stack/packages/logger/src/adapters/pino/index.ts

@@ -0,0 +1,54 @@
+import pino from 'pino'
+import type { LogFields, Logger, LogLevel } from '../../core/port.js'
+
+/**
+ * Minimal structural view of a pino logger (eases testing).
+ * Level methods follow pino's `(mergingObject, message)` convention.
+ */
+export interface PinoLike {
+  trace(obj: LogFields, msg: string): void
+  debug(obj: LogFields, msg: string): void
+  info(obj: LogFields, msg: string): void
+  warn(obj: LogFields, msg: string): void
+  error(obj: LogFields, msg: string): void
+  child(bindings: LogFields): PinoLike
+}
+
+export interface PinoAdapterOptions {
+  /** Min level to emit; defaults to `'info'`. */
+  level?: LogLevel
+  /** Fields pinned onto every line. */
+  bindings?: LogFields
+  /** Inject a custom/mock pino; defaults to a real `pino()`. */
+  client?: PinoLike
+}
+
+function wrap(client: PinoLike): Logger {
+  return {
+    name: 'pino',
+    trace(msg, fields = {}) {
+      client.trace(fields, msg)
+    },
+    debug(msg, fields = {}) {
+      client.debug(fields, msg)
+    },
+    info(msg, fields = {}) {
+      client.info(fields, msg)
+    },
+    warn(msg, fields = {}) {
+      client.warn(fields, msg)
+    },
+    error(msg, fields = {}) {
+      client.error(fields, msg)
+    },
+    child(bindings) {
+      return wrap(client.child(bindings))
+    },
+  }
+}
+
+export function pinoAdapter(options: PinoAdapterOptions = {}): Logger {
+  const base = options.client ?? (pino({ level: options.level ?? 'info' }) as unknown as PinoLike)
+  const client = options.bindings ? base.child(options.bindings) : base
+  return wrap(client)
+}

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

@@ -0,0 +1,21 @@
+/** Severity levels, from most to least verbose. */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error'
+
+/** Arbitrary structured context attached to a log line. */
+export type LogFields = Record<string, unknown>
+
+/**
+ * App-facing port; swap adapters at the composition root, never this interface.
+ * Each method takes a message + optional fields; `child` merges `bindings` into every line.
+ */
+export interface Logger {
+  /** Adapter name (`'pino'`, `'console'`, …). */
+  readonly name: string
+  trace(msg: string, fields?: LogFields): void
+  debug(msg: string, fields?: LogFields): void
+  info(msg: string, fields?: LogFields): void
+  warn(msg: string, fields?: LogFields): void
+  error(msg: string, fields?: LogFields): void
+  /** Derive a logger pinning `bindings` onto subsequent lines. */
+  child(bindings: LogFields): Logger
+}

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

@@ -0,0 +1,12 @@
+export { type ConsoleConfig, ConsoleConfigSchema } from './adapters/console/config.js'
+
+export {
+  type ConsoleAdapterOptions,
+  consoleAdapter,
+} from './adapters/console/index.js'
+export {
+  type PinoAdapterOptions,
+  type PinoLike,
+  pinoAdapter,
+} from './adapters/pino/index.js'
+export type { LogFields, Logger, LogLevel } from './core/port.js'

package/_stack/packages/storage/capability.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "../../capability.schema.json",
+  "name": "storage",
+  "description": "Object storage behind a swappable port: put/get/delete/exists plus signed URLs. Adapters for S3, Cloudflare R2, Google Cloud Storage and the local filesystem.",
+  "port": "src/core/port.ts",
+  "factory": "src/index.ts",
+  "defaultAdapter": "s3",
+  "adapters": {
+    "s3": {
+      "deps": ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+      "env": ["S3_BUCKET", "S3_REGION", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+      "files": ["src/adapters/s3"]
+    },
+    "r2": {
+      "deps": ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+      "env": ["R2_BUCKET", "R2_ACCOUNT_ID", "R2_ACCESS_KEY_ID", "R2_SECRET_ACCESS_KEY"],
+      "files": ["src/adapters/r2", "src/adapters/s3"]
+    },
+    "gcs": {
+      "deps": ["@google-cloud/storage"],
+      "env": ["GCS_BUCKET", "GOOGLE_CLOUD_PROJECT"],
+      "files": ["src/adapters/gcs"]
+    },
+    "local": {
+      "deps": [],
+      "env": ["STORAGE_LOCAL_DIR"],
+      "files": ["src/adapters/local"]
+    }
+  },
+  "sharedDeps": ["valibot"],
+  "sharedFiles": ["src/core", "src/index.ts"]
+}

package/_stack/packages/storage/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@alfredmouelle/storage",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1073.0",
+    "@aws-sdk/s3-request-presigner": "^3.1073.0",
+    "@google-cloud/storage": "^7.21.0",
+    "valibot": "^1.4.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

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

@@ -0,0 +1,8 @@
+import * as v from 'valibot'
+
+export const GcsConfigSchema = v.object({
+  bucket: v.pipe(v.string(), v.minLength(1, 'GCS_BUCKET is required')),
+  projectId: v.optional(v.string()),
+})
+
+export type GcsConfig = v.InferOutput<typeof GcsConfigSchema>