@voltro/cli 0.1.0

package/templates/apps/changelog/src/pages/[locale]/mirrors.test.tsx

@@ -0,0 +1,95 @@
+// @vitest-environment jsdom
+//
+// The [locale] mirror pages re-export the bare page and add getStaticPaths,
+// which tells `voltro build` which locale-prefixed paths to emit. The default
+// locale (en) is NOT listed — it lives at the bare path — so only /de is
+// produced. The dynamic release mirror emits the CROSS-PRODUCT of non-default
+// locales × release slugs (here: de × every release).
+
+import { describe, expect, test, vi } from 'vitest'
+
+interface Release {
+  version: string
+  releasedAt: string
+  slug: string
+  tags: ReadonlyArray<string>
+  title: string
+  summary: string
+  html: string
+}
+
+const releases: ReadonlyArray<Release> = [
+  {
+    version: '0.2.0',
+    releasedAt: '2026-06-21',
+    slug: 'v0-2-0',
+    tags: ['feature'],
+    title: 'Typed env',
+    summary: 'Declare your environment once.',
+    html: '<p>body</p>',
+  },
+  {
+    version: '0.1.0',
+    releasedAt: '2026-01-15',
+    slug: 'v0-1-0',
+    tags: ['feature'],
+    title: 'First release',
+    summary: 'The initial cut.',
+    html: '<p>body</p>',
+  },
+]
+
+// The real release source reads .mdx via `import.meta.glob` + node-gated shiki;
+// mock it (used by the [slug] mirror's cross-product getStaticPaths and by the
+// transitively-imported base pages).
+const releaseBySlug = (slug: string): Release | undefined => releases.find((r) => r.slug === slug)
+vi.mock('../../lib/releases', () => ({ releases, releaseBySlug }))
+vi.mock('@voltro/changelog', () => ({
+  highlightRelease: async (r: Release) => r,
+}))
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => ({ release: releases[0] }),
+  notFound: (detail?: string) => {
+    throw new Error(detail)
+  },
+  useLocation: () => '/',
+}))
+vi.mock('@voltro/i18n', () => ({
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  useT: (id: string) => id,
+  T: ({ id }: { id: string }) => id,
+}))
+
+const indexMirror = await import('./index')
+const releaseMirror = await import('./[slug]')
+
+describe('index mirror — getStaticPaths', () => {
+  test('emits only non-default locales (just /de)', async () => {
+    const paths = await indexMirror.getStaticPaths()
+    expect(paths).toEqual([{ params: { locale: 'de' } }])
+  })
+
+  test('re-exports the base page component + its meta function', () => {
+    expect(typeof indexMirror.default).toBe('function')
+    expect(indexMirror.meta({ locale: 'de' }).title).toContain('Changelog')
+  })
+})
+
+describe('release mirror — getStaticPaths (locale × slug cross-product)', () => {
+  test('emits one path per non-default locale × release slug', async () => {
+    const paths = await releaseMirror.getStaticPaths()
+    expect(paths).toEqual(releases.map((r) => ({ params: { locale: 'de', slug: r.slug } })))
+  })
+
+  test('re-exports the base release page + its config exports', () => {
+    expect(typeof releaseMirror.default).toBe('function')
+    expect(releaseMirror.renderMode).toBe('static')
+    expect(releaseMirror.interactive).toBe('none')
+    expect(typeof releaseMirror.loader).toBe('function')
+  })
+})

package/templates/apps/changelog/src/pages/[slug].test.tsx

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+//
+// `/[slug]` per-release page — `getStaticPaths` (one path per release),
+// `loader` (look up the release, shiki-highlight it, `notFound()` on a miss),
+// `meta(loaderData)`, and the render (which injects the highlighted HTML). We
+// mock `../lib/releases` (avoids the node-only glob) and `@voltro/changelog`
+// (`highlightRelease` pulls in shiki) and `@voltro/web` (`notFound`).
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+// Type-only import — erased at runtime, so it does NOT pull @voltro/changelog's
+// node-only glob (the value module stays mocked below). Using the real Release
+// type keeps the mock in lockstep with the framework's shape (tags: ReleaseTag[],
+// draft, body, …) so the test typechecks against what the page actually consumes.
+import type { Release } from '@voltro/changelog'
+
+const releases: ReadonlyArray<Release> = [
+  {
+    version: '0.1.0',
+    releasedAt: '2026-01-15',
+    slug: 'v0-1-0',
+    tags: ['feature'],
+    title: 'First release',
+    summary: 'The initial cut.',
+    draft: false,
+    body: 'The initial cut.',
+    html: '<p>plain</p>',
+  },
+]
+
+const releaseBySlug = (slug: string): Release | undefined => releases.find((r) => r.slug === slug)
+
+vi.mock('../lib/releases', () => ({ releases, releaseBySlug }))
+// `highlightRelease` runs shiki in node; the page only needs it to return a
+// (possibly re-rendered) release — the identity, tagged so we can assert it ran.
+vi.mock('@voltro/changelog', () => ({
+  highlightRelease: async (r: Release) => ({ ...r, html: `<pre>${r.title}</pre>` }),
+}))
+
+const loaderData = vi.fn<() => { release: Release }>()
+class NotFoundError extends Error {}
+vi.mock('@voltro/web', () => ({
+  useLoaderData: () => loaderData(),
+  notFound: (detail?: string) => {
+    throw new NotFoundError(detail)
+  },
+  // `withLocalePrefix` (lib/locale) reads useLocation; the page pins the locale
+  // via useLocale, so any bare path is fine here.
+  useLocation: () => '/',
+}))
+// The back-link chrome comes from @voltro/i18n; stub it (useLocale → en,
+// <T> passes children through).
+vi.mock('@voltro/i18n', () => ({
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  T: ({ id }: { id: string }) => id,
+}))
+
+const { default: ReleasePage, getStaticPaths, loader, meta } = await import('./[slug]')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+beforeEach(() => {
+  loaderData.mockReset()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('changelog [slug] — getStaticPaths', () => {
+  test('enumerates one path per release slug', async () => {
+    const paths = await getStaticPaths()
+    expect(paths.map((p) => p.params.slug)).toEqual(['v0-1-0'])
+  })
+})
+
+describe('changelog [slug] — loader', () => {
+  test('resolves the release and runs it through highlightRelease', async () => {
+    const { release } = await loader({ params: { slug: 'v0-1-0' } } as never)
+    expect(release.slug).toBe('v0-1-0')
+    expect(release.html).toBe('<pre>First release</pre>')
+  })
+
+  test('throws notFound for an unknown slug', async () => {
+    await expect(loader({ params: { slug: 'nope' } } as never)).rejects.toBeInstanceOf(
+      NotFoundError,
+    )
+  })
+})
+
+describe('changelog [slug] — meta', () => {
+  test('builds the per-release title + description from the loader data', () => {
+    const m = meta({ loaderData: { release: releases[0]! } })
+    expect(m.title).toContain('First release')
+    expect(m.description).toBe('The initial cut.')
+  })
+})
+
+describe('changelog [slug] — render', () => {
+  test('renders the title, version, and injects the highlighted HTML body', () => {
+    loaderData.mockReturnValue({ release: { ...releases[0]!, html: '<p>the body html</p>' } })
+    render(createElement(ReleasePage))
+    expect(container.querySelector('h1')?.textContent).toBe('First release')
+    expect(container.textContent).toContain('v0.1.0')
+    expect(container.innerHTML).toContain('the body html')
+  })
+})

package/templates/apps/changelog/src/pages/[slug].tsx

@@ -0,0 +1,52 @@
+// Per-release page. `getStaticPaths` enumerates every release slug so
+// `voltro build` pre-renders one HTML file per release. The loader runs at
+// build time (Node) where `highlightRelease` shiki-highlights the code
+// fences; in the browser it's a no-op and the plain marked HTML is used.
+
+import type { ReactNode } from 'react'
+import { useLoaderData, notFound, type LoaderFn } from '@voltro/web'
+import { highlightRelease } from '@voltro/changelog'
+import { T, useLocale } from '@voltro/i18n'
+import { releases, releaseBySlug, type Release } from '../lib/releases'
+import { withLocalePrefix } from '../lib/locale'
+
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+export const getStaticPaths = async (): Promise<Array<{ params: { slug: string } }>> =>
+  releases.map((release) => ({ params: { slug: release.slug } }))
+
+export const loader: LoaderFn<{ release: Release }> = async ({ params }) => {
+  const release = params.slug ? releaseBySlug(params.slug) : undefined
+  if (!release) return notFound(`release ${params.slug ?? ''}`)
+  return { release: await highlightRelease(release) }
+}
+
+export const meta = ({ loaderData }: { loaderData: { release: Release } }) => ({
+  title: `${loaderData.release.title} — Changelog`,
+  description: loaderData.release.summary,
+})
+
+export default function ReleasePage(): ReactNode {
+  const { release } = useLoaderData<{ release: Release }>()
+  // The active locale (from the layout's URL provider) keeps the back-link on
+  // the current language.
+  const locale = useLocale()
+  return (
+    <article className="changelog-prose">
+      <p className="changelog-meta">
+        <a href={withLocalePrefix('/', locale)}>
+          <T id="post.backToList" />
+        </a>
+      </p>
+      <h1>{release.title}</h1>
+      <p className="changelog-meta">
+        <time dateTime={release.releasedAt}>{release.releasedAt}</time> · v{release.version}
+        {release.tags.map((tag) => (
+          <span key={tag} className="changelog-tag">{tag}</span>
+        ))}
+      </p>
+      <div dangerouslySetInnerHTML={{ __html: release.html }} />
+    </article>
+  )
+}

package/templates/apps/changelog/src/pages/index.test.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+//
+// `/` changelog index — lists every release, newest first. The real release
+// source (`../lib/releases`) reads .mdx via `import.meta.glob` + node-gated
+// shiki, so we mock it with canned releases and assert the observable render:
+// config exports, meta, one entry per release, and its tags + link.
+
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+
+interface Release {
+  version: string
+  releasedAt: string
+  slug: string
+  tags: ReadonlyArray<string>
+  title: string
+  summary: string
+  html: string
+}
+
+const releases: ReadonlyArray<Release> = [
+  {
+    version: '0.2.0',
+    releasedAt: '2026-06-21',
+    slug: 'v0-2-0',
+    tags: ['feature', 'performance'],
+    title: 'Typed env + faster boot',
+    summary: 'Declare your environment once.',
+    html: '<p>body</p>',
+  },
+  {
+    version: '0.1.0',
+    releasedAt: '2026-01-15',
+    slug: 'v0-1-0',
+    tags: ['feature'],
+    title: 'First release',
+    summary: 'The initial cut.',
+    html: '<p>body</p>',
+  },
+]
+
+vi.mock('../lib/releases', () => ({ releases }))
+// `withLocalePrefix` (lib/locale) reads useLocation; the page pins the locale
+// via useLocale, so any bare path is fine here.
+vi.mock('@voltro/web', () => ({ useLocation: () => '/' }))
+// Chrome (meta via getCatalog + the empty state) comes from @voltro/i18n;
+// stub it (identity catalog defs, useLocale → en, <T> passes children through).
+vi.mock('@voltro/i18n', () => ({
+  defineCatalog: <T,>(c: T): T => c,
+  defineLocale:
+    () =>
+    <T,>(c: T): T =>
+      c,
+  useLocale: () => 'en',
+  useT: (id: string) => id,
+  T: ({ id }: { id: string }) => id,
+}))
+
+const { default: ChangelogIndex, meta, renderMode, interactive } = await import('./index')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(node)
+  })
+}
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('changelog index — config + localized meta', () => {
+  test('is a static page with zero client JS', () => {
+    expect(renderMode).toBe('static')
+    expect(interactive).toBe('none')
+  })
+
+  test('meta() returns a localized title + description per locale', () => {
+    expect(meta({ locale: 'en' }).title).toContain('Changelog')
+    expect(meta({ locale: 'en' }).description).toContain('release notes')
+    expect(meta({ locale: 'de' }).description).toContain('Release-Notes')
+  })
+})
+
+describe('changelog index — render', () => {
+  test('renders one entry per release, each linking to /<slug> with its tags', () => {
+    render(createElement(ChangelogIndex))
+    const entries = Array.from(container.querySelectorAll('.changelog-entry'))
+    expect(entries).toHaveLength(2)
+
+    const links = Array.from(container.querySelectorAll('.changelog-entry h2 a'))
+    expect(links.map((a) => a.getAttribute('href'))).toEqual(['/v0-2-0', '/v0-1-0'])
+    expect(links[0]!.textContent).toBe('Typed env + faster boot')
+
+    // The first entry surfaces both of its tags.
+    const firstTags = Array.from(entries[0]!.querySelectorAll('.changelog-tag')).map(
+      (t) => t.textContent,
+    )
+    expect(firstTags).toEqual(['feature', 'performance'])
+    expect(container.textContent).toContain('v0.2.0')
+  })
+})

package/templates/apps/changelog/src/pages/index.tsx

@@ -0,0 +1,55 @@
+// Changelog index — every release, newest first, mounted at `/` (default
+// locale) and mirrored at `/de` by src/pages/[locale]/index.tsx. Pure static
+// render with no client JS (`interactive: 'none'`).
+//
+// `meta` is a FUNCTION of `{ locale }` so each variant's <title>/<description>
+// is localised in the pre-rendered HTML. The release list itself is CONTENT
+// (the .mdx files) and is NOT translated — only the chrome (page meta, the
+// empty state) comes from the catalogs. Entry links are locale-prefixed via
+// `withLocalePrefix` so /de stays on /de.
+
+import type { ReactNode } from 'react'
+import type { PageMeta } from '@voltro/web'
+import { T, useLocale } from '@voltro/i18n'
+import { releases } from '../lib/releases'
+import { getCatalog, withLocalePrefix } from '../lib/locale'
+
+export const renderMode = 'static' as const
+export const interactive = 'none' as const
+
+export const meta = ({ locale }: { locale: string }): PageMeta => {
+  const c = getCatalog(locale)
+  return {
+    title: c['meta.home.title'],
+    description: c['meta.home.description'],
+  }
+}
+
+export default function ChangelogIndex(): ReactNode {
+  const locale = useLocale()
+  if (releases.length === 0) {
+    return (
+      <p>
+        <T id="empty.body" values={{ code: (chunks: ReactNode) => <code>{chunks}</code> }} />
+      </p>
+    )
+  }
+  return (
+    <div>
+      {releases.map((release) => (
+        <article key={release.slug} className="changelog-entry">
+          <p className="changelog-meta">
+            <time dateTime={release.releasedAt}>{release.releasedAt}</time> · v{release.version}
+            {release.tags.map((tag) => (
+              <span key={tag} className="changelog-tag">{tag}</span>
+            ))}
+          </p>
+          <h2>
+            <a href={withLocalePrefix(`/${release.slug}`, locale)}>{release.title}</a>
+          </h2>
+          <p>{release.summary}</p>
+        </article>
+      ))}
+    </div>
+  )
+}

package/templates/apps/changelog/src/pages/layout.tsx

@@ -0,0 +1,84 @@
+// Root layout — wraps every page in the framework's BlogLayout shell inside a
+// URL-driven <I18nProvider> (Strategy B: en at the bare path, de under /de).
+// `voltro build` pre-renders each page once per locale with the right catalog
+// baked in. The language switcher goes in BlogLayout's `headerRight` slot as a
+// plain <a> per locale — a real navigation to that locale's crawlable URL,
+// which is correct for a zero-JS static content site.
+//
+// BlogLayout carries its own inline styles; globals.css only styles the
+// markdown body + the list.
+
+import type { ReactNode } from 'react'
+import { BlogLayout, useLocation } from '@voltro/web'
+import { I18nProvider, T, useLocale, useT } from '@voltro/i18n'
+import {
+  CATALOGS,
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  stripLocalePrefix,
+  useUrlLocale,
+  withLocalePrefix,
+} from '../lib/locale'
+import '../globals.css'
+
+interface LayoutProps {
+  readonly children: ReactNode
+}
+
+// Rendered INSIDE the provider so <T> / useT resolve against the active
+// catalog. topNav labels must be plain strings, so they come from useT.
+function ChangelogShell({ children }: LayoutProps): ReactNode {
+  const locale = useLocale()
+  const pathname = useLocation()
+  const barePath = stripLocalePrefix(pathname)
+  const releasesLabel = useT('nav.releases')
+  const rssLabel = useT('nav.rss')
+
+  return (
+    <BlogLayout
+      brand={
+        <>
+          {{capProjectName}} <T id="nav.changelog" />
+        </>
+      }
+      pathname={pathname}
+      topNav={[
+        { label: releasesLabel, href: withLocalePrefix('/', locale) },
+        // One shared feed for every locale — never locale-prefixed.
+        { label: rssLabel, href: '/rss.xml' },
+      ]}
+      headerRight={
+        <span className="cl-lang">
+          <span className="cl-lang-label">
+            <T id="nav.language" />:
+          </span>
+          {SUPPORTED_LOCALES.map((code) => (
+            <a
+              key={code}
+              href={withLocalePrefix(barePath, code)}
+              aria-current={code === locale ? 'true' : undefined}
+            >
+              {code.toUpperCase()}
+            </a>
+          ))}
+        </span>
+      }
+      footer={
+        <span>
+          <T id="footer.builtWith" />
+        </span>
+      }
+    >
+      {children}
+    </BlogLayout>
+  )
+}
+
+export default function Layout({ children }: LayoutProps): ReactNode {
+  const locale = useUrlLocale()
+  return (
+    <I18nProvider locale={locale} messages={CATALOGS[locale]} defaultLocale={DEFAULT_LOCALE}>
+      <ChangelogShell>{children}</ChangelogShell>
+    </I18nProvider>
+  )
+}

package/templates/apps/changelog/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "changelog",
+  "kind": "web",
+  "summary": "Changelog / release-notes site: MDX releases in content/releases/, a rendered list + per-release pages (shiki-highlighted code), and an RSS feed — powered by @voltro/changelog.",
+  "tags": ["web", "frontend", "changelog", "releases", "rss", "static"]
+}

package/templates/apps/changelog/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", ".framework"]
+}

package/templates/apps/edge-functions/README.md

@@ -0,0 +1,55 @@
+# {{projectName}} / {{appName}}
+
+A library of standalone serverless functions (template: **edge-functions**).
+Each `functions/*.serverless.ts` is bundled + deployed on its own — there is
+no long-running server here and no dev port.
+
+## The functions
+
+| File | Method | Demonstrates |
+|---|---|---|
+| `health.serverless.ts` | GET | simplest diagnostic; `ctx.env`; pure `Effect.sync` |
+| `shareLink.serverless.ts` | POST | pure compute; runtime hints (memory/timeout/region) |
+| `geoGreeting.serverless.ts` | GET | reading `ctx.request.headers` (edge geo) |
+| `slackNotify.serverless.ts` | POST | `ctx.waitUntil` — background work after the response |
+| `currencyConvert.serverless.ts` | POST | outbound HTTP via `HttpClient`; read + transform JSON |
+| `verifySignature.serverless.ts` | POST | Web Crypto HMAC; `ServerlessHttpError` 401 |
+| `aiComplete.serverless.ts` | POST | a third-party API needing a secret (`ctx.env`); 502 mapping |
+| `resolveLink.serverless.ts` | GET | a lookup; 404 via `ServerlessHttpError` |
+
+Every function is **edge-safe** (no `node:*`), so the same code runs on
+Cloudflare Workers, Scaleway Functions, and your own node box.
+
+## Run one locally
+
+```bash
+pnpm install
+voltro serverless list .                                   # what's here
+voltro serverless dev functions/health.serverless.ts       # one function on :8910
+curl http://localhost:8910/
+
+# functions that need config read it from the env:
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... \
+  voltro serverless dev functions/slackNotify.serverless.ts
+```
+
+`voltro serverless serve .` runs ALL of them at once (each mounted at
+`/<name>`) — handy as a single self-hosted sidecar.
+
+## Deploy
+
+```bash
+voltro serverless build .                                  # bundle all → inspect
+voltro serverless deploy --target node                     # self-host kit (Dockerfile + README)
+voltro serverless deploy --target cloudflare               # Cloudflare Workers
+voltro serverless deploy --target scaleway --namespace-id <id>   # Scaleway Functions
+```
+
+Set each function's secrets at deploy time (the host's env / secret store):
+`SLACK_WEBHOOK_URL`, `SIGNING_SECRET`, `OPENAI_API_KEY`, `SHARE_BASE_URL`, …
+
+## Add your own
+
+Drop a new `functions/<name>.serverless.ts` exporting
+`export default defineServerless({ … })`. It's discovered automatically — no
+registry, no config.

package/templates/apps/edge-functions/functions/aiComplete.serverless.ts

@@ -0,0 +1,58 @@
+// aiComplete — a one-shot LLM completion at the edge.
+//
+// Demonstrates: calling a third-party API that needs a SECRET (the key lives in
+// `ctx.env`, never in the bundle), an optional input field, reading the JSON
+// response, and mapping an upstream failure to a 502. Uses the OpenAI
+// chat-completions shape; point it at any compatible endpoint via OPENAI_BASE_URL.
+//
+//   OPENAI_API_KEY=sk-... voltro serverless dev functions/aiComplete.serverless.ts
+//   curl -X POST http://localhost:8910/ -d '{"prompt":"Name three primary colors."}'
+
+import { Effect, Schema } from 'effect'
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+import { defineServerless, ServerlessHttpError } from '@voltro/serverless'
+
+export default defineServerless({
+  name: 'ai-complete',
+  method: 'POST',
+  input: Schema.Struct({
+    prompt: Schema.String.pipe(Schema.minLength(1), Schema.maxLength(4000)),
+    system: Schema.optional(Schema.String),
+  }),
+  output: Schema.Struct({ text: Schema.String }),
+  runtime: { memoryMb: 256, timeoutSeconds: 30 },
+  handler: ({ prompt, system }, ctx) =>
+    Effect.gen(function* () {
+      const apiKey = ctx.env.OPENAI_API_KEY
+      if (!apiKey) {
+        return yield* Effect.fail(
+          new ServerlessHttpError({ status: 503, message: 'ai-not-configured', detail: 'Set OPENAI_API_KEY.' }),
+        )
+      }
+      const baseUrl = ctx.env.OPENAI_BASE_URL ?? 'https://api.openai.com'
+      const model = ctx.env.OPENAI_MODEL ?? 'gpt-4o-mini'
+
+      const http = yield* HttpClient.HttpClient
+      const request = HttpClientRequest.post(`${baseUrl}/v1/chat/completions`).pipe(
+        HttpClientRequest.setHeader('authorization', `Bearer ${apiKey}`),
+        HttpClientRequest.bodyUnsafeJson({
+          model,
+          max_tokens: 400,
+          messages: [
+            ...(system ? [{ role: 'system', content: system }] : []),
+            { role: 'user', content: prompt },
+          ],
+        }),
+      )
+
+      const response = yield* http.execute(request)
+      if (response.status >= 400) {
+        const detail = yield* response.text
+        return yield* Effect.fail(new ServerlessHttpError({ status: 502, message: 'ai-call-failed', detail }))
+      }
+      const body = (yield* response.json) as {
+        choices?: ReadonlyArray<{ message?: { content?: string } }>
+      }
+      return { text: body.choices?.[0]?.message?.content ?? '' }
+    }),
+})