@moifort/stack 0.0.0-stage → 0.1.0

package/templates/backend/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "{{APP_SLUG}}",
+  "private": true,
+  "scripts": {
+    "prepare": "bun run generate:assets && nitro prepare",
+    "build": "bun run generate:assets && nitro build",
+    "dev": "bun run generate:assets && nitro dev --host 0.0.0.0",
+    "typecheck": "bunx nitro prepare && bunx tsc --noEmit",
+    "test": "bun run generate:assets && bun test",
+    "test:unit": "bun run generate:assets && bun test .unit.test",
+    "test:int": "bun run generate:assets && bun test .int.test",
+    "test:feat": "bun run generate:assets && bun test .feat.test",
+    "test:coverage": "bun run generate:assets && bun test --coverage",
+    "lint": "bunx biome check",
+    "lint:fix": "bunx biome check --write",
+    "preflight": "bun run typecheck && bun run lint && bun run test:unit && bun run test:int && bun run test:feat",
+    "generate:assets": "bun scripts/generate-changelog-asset.ts",
+    "generate:graphql": "bun scripts/export-graphql-schema.ts",
+    "generate": "bun run generate:assets && bun run generate:graphql",
+    "deprecations": "bun scripts/deprecations.ts",
+    "schema:check": "graphql-inspector diff \"git:${SCHEMA_BASE:-origin/main}:shared/schema.graphql\" shared/schema.graphql --rule suppressRemovalOfDeprecatedField --rule ./scripts/deprecations/inspector-rule.ts",
+    "stack:check": "bunx stack check",
+    "infra:build": "bun install --frozen-lockfile && bunx nitro prepare && bun run generate:graphql && bun run build",
+    "infra:init": "cd infra && ../scripts/tf init",
+    "infra:plan": "bun run infra:build && cd infra && ../scripts/tf plan"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@graphql-inspector/cli": "7.0.2",
+    "@moifort/stack": "{{STACK_VERSION}}",
+    "@types/bun": "1.4.3",
+    "@types/lodash-es": "4.17.12",
+    "@types/node": "26.6.5",
+    "bun-types": "1.4.3",
+    "h3": "1.15.11",
+    "nitropack": "2.13.5",
+    "ts-brand": "0.2.0",
+    "typescript": "7.0.2"
+  },
+  "dependencies": {
+    "@apollo/server": "5.5.1",
+    "@pothos/core": "4.15.1",
+    "@sentry/node": "11.8.0",
+    "consola": "3.4.2",
+    "firebase-admin": "13.10.0",
+    "graphql": "16.14.2",
+    "lodash-es": "4.18.1",
+    "ts-pattern": "5.9.2",
+    "zod": "4.6.7"
+  }
+}

package/templates/backend/scripts/deprecations/inspector-rule.ts

@@ -0,0 +1,29 @@
+import type { GraphQLSchema } from 'graphql'
+
+type Change = {
+  type: string
+  path?: string
+  message: string
+  criticality: { level: string; reason?: string }
+}
+
+/** graphql-inspector's `suppressRemovalOfDeprecatedField` spares a removed field
+ *  that was deprecated, not a removed argument. This rule does the same for
+ *  arguments, so the deprecation routine can retire one without a red run. */
+export default ({ changes, oldSchema }: { changes: Change[]; oldSchema: GraphQLSchema }) =>
+  changes.map((change) => {
+    if (change.type !== 'FIELD_ARGUMENT_REMOVED' || !change.path) return change
+    const [typeName, fieldName, argumentName] = change.path.split('.')
+    const type = oldSchema.getType(typeName)
+    const field = type && 'getFields' in type ? type.getFields()[fieldName] : undefined
+    const argument =
+      field && 'args' in field ? field.args.find((arg) => arg.name === argumentName) : undefined
+    if (argument?.deprecationReason == null) return change
+    return {
+      ...change,
+      criticality: {
+        level: 'DANGEROUS',
+        reason: 'Removing a deprecated argument is a step of the deprecation routine',
+      },
+    }
+  })

package/templates/backend/scripts/deprecations/status.ts

@@ -0,0 +1,50 @@
+/** How long a build that no longer asks for an element must have been on the
+ *  App Store before the builds that still ask are sent to update: iOS automatic
+ *  updates have reached nearly everyone by then. */
+export const GRACE_DAYS = 14
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/** The build on sale on the App Store, and the day it was released. */
+export type LiveBuild = { build: number; releasedOn: Date }
+
+/** The first build that no longer asks for the element — `0` when no build ever
+ *  did — or `still-asked` when an operation of the app still selects it. */
+export type Since = number | 'still-asked'
+
+export type Status =
+  | { kind: 'still-asked' }
+  | { kind: 'removable' }
+  | { kind: 'in-grace'; until: Date }
+  | { kind: 'waiting-release' }
+  | { kind: 'unknown' }
+
+export const statusOf = ({
+  since,
+  live,
+  today,
+}: {
+  since: Since
+  live: LiveBuild | undefined | 'unknown'
+  today: Date
+}): Status => {
+  if (since === 'still-asked') return { kind: 'still-asked' }
+  if (since === 0) return { kind: 'removable' }
+  if (live === 'unknown') return { kind: 'unknown' }
+  if (!live || live.build < since) return { kind: 'waiting-release' }
+  const until = new Date(live.releasedOn.getTime() + GRACE_DAYS * DAY_MS)
+  return until <= today ? { kind: 'removable' } : { kind: 'in-grace', until }
+}
+
+/** The floor the removal commit sets: the highest build among the elements
+ *  that can go, never below the floor already in force. */
+export const proposedFloorOf = (
+  rows: readonly { since: Since; status: Status }[],
+  current: number,
+): number =>
+  Math.max(
+    current,
+    ...rows.flatMap((row) =>
+      row.status.kind === 'removable' && typeof row.since === 'number' ? [row.since] : [],
+    ),
+  )

package/templates/backend/scripts/deprecations/status.unit.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test'
+import { proposedFloorOf, statusOf } from './status'
+
+const today = new Date('2026-11-20')
+const live = { build: 1500, releasedOn: new Date('2026-11-01') }
+
+describe('whether a deprecated element can go', () => {
+  test('not while an operation of the app still asks for it', () => {
+    expect(statusOf({ since: 'still-asked', live, today })).toEqual({ kind: 'still-asked' })
+  })
+
+  test('at once when no build ever asked for it', () => {
+    expect(statusOf({ since: 0, live: undefined, today })).toEqual({ kind: 'removable' })
+  })
+
+  test('once a build without it has been on the App Store for two weeks', () => {
+    expect(statusOf({ since: 1400, live, today })).toEqual({ kind: 'removable' })
+  })
+
+  test('not before the two weeks are over', () => {
+    expect(statusOf({ since: 1400, live, today: new Date('2026-11-10') })).toEqual({
+      kind: 'in-grace',
+      until: new Date('2026-11-15'),
+    })
+  })
+
+  test('not while the App Store still sells a build that asks for it', () => {
+    expect(statusOf({ since: 1600, live, today })).toEqual({ kind: 'waiting-release' })
+  })
+
+  test('not before anything is on the App Store', () => {
+    expect(statusOf({ since: 1400, live: undefined, today })).toEqual({ kind: 'waiting-release' })
+  })
+
+  test('is unknown without App Store Connect credentials', () => {
+    expect(statusOf({ since: 1400, live: 'unknown', today })).toEqual({ kind: 'unknown' })
+  })
+})
+
+describe('the proposed floor', () => {
+  test('is the highest build among the removable elements', () => {
+    expect(
+      proposedFloorOf(
+        [
+          { since: 1400, status: { kind: 'removable' } },
+          { since: 1450, status: { kind: 'removable' } },
+          { since: 1600, status: { kind: 'waiting-release' } },
+        ],
+        1,
+      ),
+    ).toBe(1450)
+  })
+
+  test('never goes below the current floor', () => {
+    expect(proposedFloorOf([{ since: 0, status: { kind: 'removable' } }], 1200)).toBe(1200)
+  })
+})

package/templates/backend/scripts/deprecations/usage.ts

@@ -0,0 +1,79 @@
+import {
+  type GraphQLSchema,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+  parse,
+  TypeInfo,
+  visit,
+  visitWithTypeInfo,
+} from 'graphql'
+
+/** A deprecated element of the schema, named by its schema coordinate. Only a
+ *  field or an argument can be traced through the app's operations: an input
+ *  field is filled from Swift through a variable, and an enum value travels in
+ *  responses, so neither shows in the `.graphql` files. */
+export type DeprecatedElement = { coordinate: string; traceable: boolean }
+
+export const deprecatedElementsOf = (schema: GraphQLSchema): DeprecatedElement[] =>
+  Object.values(schema.getTypeMap())
+    .filter((type) => !type.name.startsWith('__'))
+    .flatMap((type): DeprecatedElement[] => {
+      if (isObjectType(type) || isInterfaceType(type)) {
+        return Object.values(type.getFields()).flatMap((field) => [
+          ...field.args
+            .filter((arg) => arg.deprecationReason != null)
+            .map((arg) => ({
+              coordinate: `${type.name}.${field.name}(${arg.name}:)`,
+              traceable: true,
+            })),
+          ...(field.deprecationReason != null
+            ? [{ coordinate: `${type.name}.${field.name}`, traceable: true }]
+            : []),
+        ])
+      }
+      if (isInputObjectType(type)) {
+        return Object.values(type.getFields())
+          .filter((field) => field.deprecationReason != null)
+          .map((field) => ({ coordinate: `${type.name}.${field.name}`, traceable: false }))
+      }
+      if (isEnumType(type)) {
+        return type
+          .getValues()
+          .filter((value) => value.deprecationReason != null)
+          .map((value) => ({ coordinate: `${type.name}.${value.name}`, traceable: false }))
+      }
+      return []
+    })
+
+/** Every field and argument coordinate the operations select. The files are
+ *  read as one document, since a fragment may be spread from another file. A
+ *  name the schema does not know — an old operation read against today's
+ *  schema — is skipped. */
+export const coordinatesUsedBy = (
+  schema: GraphQLSchema,
+  documents: readonly string[],
+): Set<string> => {
+  const used = new Set<string>()
+  const typeInfo = new TypeInfo(schema)
+  visit(
+    parse(documents.join('\n')),
+    visitWithTypeInfo(typeInfo, {
+      Field: () => {
+        const parent = typeInfo.getParentType()
+        const field = typeInfo.getFieldDef()
+        if (parent && field) used.add(`${parent.name}.${field.name}`)
+      },
+      Argument: () => {
+        const parent = typeInfo.getParentType()
+        const field = typeInfo.getFieldDef()
+        const argument = typeInfo.getArgument()
+        if (parent && field && argument) {
+          used.add(`${parent.name}.${field.name}(${argument.name}:)`)
+        }
+      },
+    }),
+  )
+  return used
+}

package/templates/backend/scripts/deprecations/usage.unit.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from 'bun:test'
+import { buildSchema } from 'graphql'
+import { coordinatesUsedBy, deprecatedElementsOf } from './usage'
+
+const schema = buildSchema(`
+  type Query {
+    library(rated: Boolean @deprecated(reason: "gone"), favorite: Boolean): [Book!]!
+    book(id: ID!): Book
+  }
+  type Mutation { addBook(input: BookInput!): Book! }
+  type Book {
+    id: ID!
+    title: String!
+    pages: Int @deprecated(reason: "gone")
+    series: Series
+  }
+  type Series { id: ID! pages: Int }
+  input BookInput { title: String! legacy: String @deprecated(reason: "gone") }
+  enum Status { READ TO_READ @deprecated(reason: "gone") }
+`)
+
+describe('the deprecated elements of a schema', () => {
+  test('are listed by coordinate, and only fields and arguments can be traced', () => {
+    expect(deprecatedElementsOf(schema)).toEqual([
+      { coordinate: 'Query.library(rated:)', traceable: true },
+      { coordinate: 'Book.pages', traceable: true },
+      { coordinate: 'BookInput.legacy', traceable: false },
+      { coordinate: 'Status.TO_READ', traceable: false },
+    ])
+  })
+})
+
+describe('the coordinates an operation uses', () => {
+  test('match the exact type, so two types sharing a field name are not confused', () => {
+    const used = coordinatesUsedBy(schema, ['query { book(id: "1") { series { pages } } }'])
+
+    expect(used.has('Series.pages')).toBe(true)
+    expect(used.has('Book.pages')).toBe(false)
+  })
+
+  test('include the arguments an operation passes', () => {
+    const used = coordinatesUsedBy(schema, ['query($r: Boolean) { library(rated: $r) { id } }'])
+
+    expect(used.has('Query.library(rated:)')).toBe(true)
+    expect(used.has('Query.library(favorite:)')).toBe(false)
+  })
+
+  // Apollo iOS lets a fragment live in one file and the query that spreads it in another.
+  test('follow a fragment defined in another file', () => {
+    const used = coordinatesUsedBy(schema, [
+      'query { library { ...Row } }',
+      'fragment Row on Book { pages }',
+    ])
+
+    expect(used.has('Book.pages')).toBe(true)
+  })
+
+  // An old operation may name a field the schema has since lost: it is skipped, not fatal.
+  test('ignore what the schema no longer knows', () => {
+    const used = coordinatesUsedBy(schema, ['query { book(id: "1") { vanished title } }'])
+
+    expect(used.has('Book.title')).toBe(true)
+  })
+})

package/templates/backend/scripts/deprecations.ts

@@ -0,0 +1,224 @@
+/**
+ * What the deprecation routine can remove, and the build floor that goes with it — see
+ * docs/api-evolution.md.
+ *
+ *   bun scripts/deprecations.ts
+ *     One row per deprecated element of shared/schema.graphql: the first build that no
+ *     longer asks for it, and whether it can go. Ends with the proposed
+ *     MINIMUM_SUPPORTED_IOS_BUILD.
+ *
+ *   bun scripts/deprecations.ts check-floor
+ *     Fails when MINIMUM_SUPPORTED_IOS_BUILD is above the build on sale on the App Store:
+ *     a reader would be blocked with no update to install. Run by the Deploy workflow.
+ *
+ * Reads ASC_KEY_ID, ASC_ISSUER_ID and the key itself from ASC_KEY_P8 (its contents) or
+ * ASC_KEY_PATH (a .p8 file). Without them the report still traces the builds and marks
+ * every status unknown; check-floor fails unless the floor is still 1.
+ */
+
+import { createPrivateKey, sign } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { buildSchema } from 'graphql'
+import { MINIMUM_SUPPORTED_IOS_BUILD } from '../server/system/app-support'
+import {
+  type LiveBuild,
+  proposedFloorOf,
+  type Since,
+  type Status,
+  statusOf,
+} from './deprecations/status'
+import { coordinatesUsedBy, deprecatedElementsOf } from './deprecations/usage'
+
+const APP_ID = '{{APP_STORE_ID}}'
+const OPERATIONS = 'ios/*.graphql'
+
+const git = (...args: string[]): string => {
+  const result = Bun.spawnSync(['git', ...args], { stdout: 'pipe', stderr: 'pipe' })
+  if (result.exitCode !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString().trim()}`)
+  }
+  return result.stdout.toString()
+}
+
+const lines = (text: string) => text.split('\n').filter((line) => line.length > 0)
+
+/** The app's operations as they stood at a commit. */
+const operationsAt = (commit: string): string[] =>
+  lines(git('ls-tree', '-r', '--name-only', commit, '--', 'ios'))
+    .filter((path) => path.endsWith('.graphql'))
+    .map((path) => git('show', `${commit}:${path}`))
+
+const buildOf = (commit: string) => Number(git('rev-list', '--count', commit).trim())
+
+// MARK: - App Store Connect
+
+const credentials = () => {
+  const { ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_P8, ASC_KEY_PATH } = process.env
+  const key = ASC_KEY_P8 || (ASC_KEY_PATH ? readFileSync(ASC_KEY_PATH, 'utf8') : undefined)
+  if (!ASC_KEY_ID || !ASC_ISSUER_ID || !key) return undefined
+  return { keyId: ASC_KEY_ID, issuerId: ASC_ISSUER_ID, key }
+}
+
+const apiToken = ({ keyId, issuerId, key }: NonNullable<ReturnType<typeof credentials>>) => {
+  const encode = (value: object) => Buffer.from(JSON.stringify(value)).toString('base64url')
+  const now = Math.floor(Date.now() / 1000)
+  const unsigned = `${encode({ alg: 'ES256', kid: keyId, typ: 'JWT' })}.${encode({
+    iss: issuerId,
+    iat: now,
+    exp: now + 15 * 60,
+    aud: 'appstoreconnect-v1',
+  })}`
+  const signature = sign('sha256', Buffer.from(unsigned), {
+    key: createPrivateKey(key),
+    dsaEncoding: 'ieee-p1363',
+  })
+  return `${unsigned}.${signature.toString('base64url')}`
+}
+
+type Resource = {
+  id: string
+  type: string
+  attributes: Record<string, unknown>
+  relationships?: Record<string, { data?: { id: string } }>
+}
+
+/** The build on sale on the App Store and the day it was released — the date of
+ *  its `ios-v<version>` tag, which the release workflow submits for automatic
+ *  release. Undefined before the first release. */
+const liveBuild = async (): Promise<LiveBuild | undefined | 'unknown'> => {
+  const found = credentials()
+  if (!found) return 'unknown'
+  const response = await fetch(
+    `https://api.appstoreconnect.apple.com/v1/apps/${APP_ID}/appStoreVersions` +
+      '?filter[appStoreState]=READY_FOR_SALE&filter[platform]=IOS&include=build' +
+      '&fields[appStoreVersions]=versionString,build&fields[builds]=version',
+    { headers: { authorization: `Bearer ${apiToken(found)}` } },
+  )
+  if (!response.ok) {
+    throw new Error(`App Store Connect answered ${response.status}: ${await response.text()}`)
+  }
+  const { data, included = [] } = (await response.json()) as {
+    data: Resource[]
+    included?: Resource[]
+  }
+  const [version] = data
+  if (!version) return undefined
+  const buildId = version.relationships?.build?.data?.id
+  const build = included.find((resource) => resource.type === 'builds' && resource.id === buildId)
+  if (!build) throw new Error(`The version on sale lists no build: ${JSON.stringify(version)}`)
+  const tag = `ios-v${version.attributes.versionString}`
+  const tagged = git('log', '-1', '--format=%cI', `refs/tags/${tag}`).trim()
+  return { build: Number(build.attributes.version), releasedOn: new Date(tagged) }
+}
+
+// MARK: - Commands
+
+const describe = (status: Status): string => {
+  switch (status.kind) {
+    case 'still-asked':
+      return 'still asked by the app'
+    case 'removable':
+      return 'removable'
+    case 'in-grace':
+      return `in grace until ${status.until.toISOString().slice(0, 10)}`
+    case 'waiting-release':
+      return 'waiting for a release'
+    case 'unknown':
+      return 'unknown (no App Store credentials)'
+  }
+}
+
+const report = async () => {
+  const schema = buildSchema(readFileSync('shared/schema.graphql', 'utf8'))
+  const elements = deprecatedElementsOf(schema)
+  const traceable = elements.filter((element) => element.traceable)
+  const askedNow = coordinatesUsedBy(schema, operationsAt('HEAD'))
+
+  // Walk back through the commits that touched the operations until each element
+  // is found in use: the newer commit walked just before stopped asking for it.
+  const since = new Map<string, Since>()
+  for (const { coordinate } of traceable) {
+    if (askedNow.has(coordinate)) since.set(coordinate, 'still-asked')
+  }
+  let newer: string | undefined
+  for (const commit of lines(git('log', '--format=%H', 'HEAD', '--', OPERATIONS))) {
+    const pending = traceable.filter(({ coordinate }) => !since.has(coordinate))
+    if (pending.length === 0) break
+    let used: Set<string>
+    try {
+      used = coordinatesUsedBy(schema, operationsAt(commit))
+    } catch (error) {
+      process.stderr.write(`Skipping ${commit.slice(0, 7)}, unparsable: ${error}\n`)
+      newer = commit
+      continue
+    }
+    for (const { coordinate } of pending) {
+      if (used.has(coordinate) && newer) since.set(coordinate, buildOf(newer))
+    }
+    newer = commit
+  }
+
+  const live = await liveBuild()
+  const today = new Date()
+  const rows = traceable.map(({ coordinate }) => {
+    const first = since.get(coordinate) ?? 0
+    return { coordinate, since: first, status: statusOf({ since: first, live, today }) }
+  })
+  const width = Math.max(40, ...elements.map((element) => element.coordinate.length + 2))
+  const out = [`${'element'.padEnd(width)}${'no longer asked since'.padEnd(24)}status`]
+  for (const row of rows) {
+    const build = typeof row.since === 'number' ? `build ${row.since}` : '—'
+    out.push(`${row.coordinate.padEnd(width)}${build.padEnd(24)}${describe(row.status)}`)
+  }
+  for (const element of elements.filter((element) => !element.traceable)) {
+    out.push(`${element.coordinate.padEnd(width)}${'—'.padEnd(24)}check by hand`)
+  }
+  if (elements.length === 0) out.push('(nothing is deprecated)')
+  out.push(
+    '',
+    `Live on the App Store: ${
+      live === 'unknown'
+        ? 'unknown (no App Store credentials)'
+        : live
+          ? `build ${live.build}, released ${live.releasedOn.toISOString().slice(0, 10)}`
+          : 'nothing yet'
+    }`,
+    `Proposed MINIMUM_SUPPORTED_IOS_BUILD: ${proposedFloorOf(rows, MINIMUM_SUPPORTED_IOS_BUILD)} ` +
+      `(today ${MINIMUM_SUPPORTED_IOS_BUILD})`,
+  )
+  process.stdout.write(`${out.join('\n')}\n`)
+}
+
+const checkFloor = async () => {
+  if (MINIMUM_SUPPORTED_IOS_BUILD <= 1) {
+    process.stdout.write('The floor is 1: every build is supported.\n')
+    return
+  }
+  const live = await liveBuild()
+  if (live === 'unknown')
+    throw new Error('App Store Connect credentials are needed to check the floor')
+  if (!live) {
+    throw new Error(
+      `MINIMUM_SUPPORTED_IOS_BUILD is ${MINIMUM_SUPPORTED_IOS_BUILD} but nothing is on the App Store`,
+    )
+  }
+  if (MINIMUM_SUPPORTED_IOS_BUILD > live.build) {
+    throw new Error(
+      `MINIMUM_SUPPORTED_IOS_BUILD is ${MINIMUM_SUPPORTED_IOS_BUILD}, above build ${live.build} ` +
+        'on sale on the App Store: readers would be blocked with no update to install',
+    )
+  }
+  process.stdout.write(
+    `The floor ${MINIMUM_SUPPORTED_IOS_BUILD} is at or below build ${live.build} on sale.\n`,
+  )
+}
+
+const [command] = process.argv.slice(2)
+try {
+  if (command === undefined) await report()
+  else if (command === 'check-floor') await checkFloor()
+  else throw new Error(`Unknown command ${command}: expected none or check-floor`)
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : error}\n`)
+  process.exit(1)
+}

package/templates/backend/scripts/export-graphql-schema.ts

@@ -0,0 +1,11 @@
+// Standalone script that exports the Pothos schema as SDL into shared/schema.graphql.
+// Usage: bun run generate:graphql
+// Run after any change to a domain's GraphQL types/queries/mutations so that
+// the iOS Apollo codegen picks up the new shape.
+import { printSchema } from 'graphql'
+import { schema } from '../server/domain/shared/graphql/schema'
+
+const sdl = printSchema(schema)
+await Bun.write('shared/schema.graphql', sdl)
+
+process.stdout.write('Exported GraphQL schema to shared/schema.graphql\n')

package/templates/backend/scripts/generate-changelog-asset.ts

@@ -0,0 +1,27 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+const root = resolve(import.meta.dir, '..')
+const target = resolve(root, 'server/system/changelog-content.ts')
+
+// CHANGELOG.md is the English source; every other language is served to the app
+// in its own file, picked at request time from `Accept-Language`. Keep this list
+// in sync with SUPPORTED_LANGUAGES in server/domain/shared/language.ts.
+const files: Record<string, string> = {
+  en: 'CHANGELOG.md',
+  fr: 'CHANGELOG.fr.md',
+}
+
+const byLanguage: Record<string, string> = {}
+for (const [language, file] of Object.entries(files)) {
+  const path = resolve(root, file)
+  if (!existsSync(path)) continue
+  byLanguage[language] = readFileSync(path, 'utf8')
+}
+
+const banner =
+  '// Generated from the CHANGELOG.*.md files by scripts/generate-changelog-asset.ts. Do not edit.\n'
+const body = `export const changelogMarkdownByLanguage: Record<string, string> = ${JSON.stringify(byLanguage, null, 2)}\n`
+
+mkdirSync(dirname(target), { recursive: true })
+writeFileSync(target, banner + body)

package/templates/backend/scripts/install-terraform.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# install-terraform.sh — downloads a pinned, checksum-verified terraform
+# binary into infra/.bin/terraform. Idempotent: a no-op if the target
+# version is already installed.
+#
+# This removes the need for users to install terraform system-wide before
+# running `bun run bootstrap` or `bun run infra:plan|infra:apply|destroy`.
+
+set -euo pipefail
+
+TF_VERSION="1.10.0"
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BIN_DIR="$REPO_ROOT/infra/.bin"
+TF_BIN="$BIN_DIR/terraform"
+
+log() { printf "\033[1;34m▸ %s\033[0m\n" "$*" >&2; }
+fail() { printf "\033[1;31m✗\033[0m %s\n" "$*" >&2; exit 1; }
+
+# Fast path: already installed at the right version.
+if [[ -x "$TF_BIN" ]] && "$TF_BIN" version 2>/dev/null | head -n1 | grep -q "v${TF_VERSION}"; then
+  exit 0
+fi
+
+command -v curl >/dev/null 2>&1   || fail "curl is required to download terraform"
+command -v unzip >/dev/null 2>&1  || fail "unzip is required to extract the terraform archive"
+command -v shasum >/dev/null 2>&1 || fail "shasum is required to verify the terraform checksum"
+
+case "$(uname -s)" in
+  Darwin) OS="darwin" ;;
+  Linux)  OS="linux"  ;;
+  *) fail "unsupported OS: $(uname -s)" ;;
+esac
+
+case "$(uname -m)" in
+  arm64|aarch64) ARCH="arm64" ;;
+  x86_64|amd64)  ARCH="amd64" ;;
+  *) fail "unsupported arch: $(uname -m)" ;;
+esac
+
+ARCHIVE="terraform_${TF_VERSION}_${OS}_${ARCH}.zip"
+SUMS="terraform_${TF_VERSION}_SHA256SUMS"
+BASE_URL="https://releases.hashicorp.com/terraform/${TF_VERSION}"
+
+log "Installing terraform ${TF_VERSION} (${OS}_${ARCH}) into infra/.bin/"
+
+mkdir -p "$BIN_DIR"
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+curl -fsSL "$BASE_URL/$ARCHIVE" -o "$TMP_DIR/$ARCHIVE"
+curl -fsSL "$BASE_URL/$SUMS"    -o "$TMP_DIR/$SUMS"
+
+(cd "$TMP_DIR" && grep " $ARCHIVE\$" "$SUMS" | shasum -a 256 -c -) >/dev/null \
+  || fail "terraform checksum verification failed"
+
+unzip -q -o "$TMP_DIR/$ARCHIVE" -d "$BIN_DIR"
+chmod +x "$TF_BIN"
+
+log "terraform ${TF_VERSION} installed at $TF_BIN"

package/templates/backend/scripts/tf

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#
+# tf — thin wrapper that ensures the pinned terraform binary exists,
+# then execs it with the passed arguments. Used by the package.json scripts
+# so `bun run infra:plan|infra:apply|infra:init|destroy` work on a fresh machine.
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+"$ROOT/scripts/install-terraform.sh"
+exec "$ROOT/infra/.bin/terraform" "$@"