geeknative 0.0.0-stage → 0.1.1

package/src/commands/check.js

@@ -0,0 +1,148 @@
+// @ts-check
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { runLogged } from '../lib/exec.js'
+import { CliError, color, log } from '../lib/log.js'
+import { findAndroidSdk, pickSimulator, writeLocalProperties } from '../lib/toolchains.js'
+import { gen } from './gen.js'
+
+export const PLATFORMS = ['ios', 'android', 'web']
+
+/**
+ * Verifies the contracts, then builds and tests the requested apps.
+ * Prints a short summary per platform; full output goes to .geeknative/logs/<platform>.log.
+ * @param {string} root
+ * @param {string[]} targets "all", "contracts", or platform names
+ */
+export async function check(root, targets) {
+  const everything = !targets.length || targets.includes('all')
+  const wanted = everything ? PLATFORMS : targets
+  for (const target of wanted) {
+    if (target !== 'contracts' && !PLATFORMS.includes(target)) {
+      throw new CliError(`Unknown check "${target}". Use: all, contracts, ${PLATFORMS.join(', ')}.`)
+    }
+  }
+
+  let failed = false
+  try {
+    gen(root, { check: true })
+  } catch (error) {
+    log.fail('contracts', /** @type {Error} */ (error).message)
+    failed = true
+  }
+
+  for (const platform of wanted.filter((t) => t !== 'contracts')) {
+    if (everything && platform === 'ios' && process.platform !== 'darwin') {
+      log.warn('ios', 'skipped: iOS builds need macOS with Xcode')
+      continue
+    }
+    const started = Date.now()
+    const result = await CHECKS[platform](root)
+    const seconds = `${Math.round((Date.now() - started) / 1000)}s`
+    if (result.ok) {
+      log.ok(platform, `${result.summary} ${color.dim(`(${seconds})`)}`)
+    } else {
+      failed = true
+      log.fail(platform, `${result.summary} ${color.dim(`(${seconds}, full log: ${result.log})`)}`)
+      for (const line of result.details.slice(0, 25)) log.detail(line)
+      if (result.details.length > 25) log.detail(`… ${result.details.length - 25} more in the log`)
+    }
+  }
+  if (failed) process.exitCode = 1
+}
+
+/** @typedef {{ ok: boolean, summary: string, details: string[], log: string }} CheckResult */
+
+/** @param {string} root @param {string} platform */
+const logPath = (root, platform) => path.join(root, '.geeknative', 'logs', `${platform}.log`)
+
+/** @param {string} root @param {string} file */
+const shown = (root, file) => path.relative(root, file)
+
+/** @type {Record<string, (root: string) => Promise<CheckResult>>} */
+const CHECKS = {
+  async ios(root) {
+    const logFile = logPath(root, 'ios')
+    if (process.platform !== 'darwin') return fail('iOS builds need macOS with Xcode', [], root, logFile)
+    const simulator = pickSimulator()
+    if (!simulator) return fail('no iPhone simulator found; run `make doctor`', [], root, logFile)
+    const firstBuild = !existsSync(path.join(root, 'apps', 'ios', '.build'))
+    log.step('ios', `building and testing on ${simulator.name} (${simulator.runtime})…${firstBuild ? ' (first build: allow a few minutes)' : ''}`)
+    const { code, lines } = await runLogged(
+      'xcodebuild',
+      [
+        'test',
+        '-project', 'App.xcodeproj',
+        '-scheme', 'App',
+        '-destination', `id=${simulator.udid}`,
+        '-derivedDataPath', '.build/DerivedData',
+        '-quiet',
+      ],
+      { cwd: path.join(root, 'apps', 'ios'), logFile },
+    )
+    const passed = lines.filter((l) => /^Test case '.*' passed/.test(l)).length
+    if (code === 0) return { ok: true, summary: `build and ${passed} tests passed`, details: [], log: shown(root, logFile) }
+    const details = unique(
+      lines.filter((l) => /(error:|✘|failed|\*\* (BUILD|TEST) FAILED)/.test(l) && !/^\s*$/.test(l)).map((l) => l.trim()),
+    )
+    return fail(details.length ? 'build or tests failed' : `xcodebuild exited with ${code}`, details, root, logFile)
+  },
+
+  async android(root) {
+    const logFile = logPath(root, 'android')
+    const sdk = findAndroidSdk(root)
+    if (!sdk) return fail('Android SDK not found; run `make doctor`', [], root, logFile)
+    if (!existsSync(path.join(root, 'apps', 'android', 'local.properties'))) writeLocalProperties(root, sdk)
+    const firstBuild = !existsSync(path.join(root, 'apps', 'android', 'app', 'build'))
+    log.step('android', `building and running unit tests…${firstBuild ? ' (the first build downloads Gradle, JDK 21 and dependencies: allow several minutes)' : ''}`)
+    const { code, lines } = await runLogged(
+      './gradlew',
+      [':app:testDebugUnitTest', ':app:assembleDebug', '--console=plain', '--warning-mode=summary'],
+      { cwd: path.join(root, 'apps', 'android'), logFile },
+    )
+    if (code === 0) {
+      const tests = junitCount(path.join(root, 'apps', 'android', 'app', 'build', 'test-results', 'testDebugUnitTest'))
+      return { ok: true, summary: `build and ${tests} unit tests passed`, details: [], log: shown(root, logFile) }
+    }
+    const details = unique(
+      lines
+        .filter((l) => /^(e: |\s*[A-Za-z]+Test > .* FAILED|.*FAILED$|\* What went wrong|.*error:)/.test(l) || /^> /.test(l))
+        .map((l) => l.trim())
+        .filter((l) => !/^> Task /.test(l) && !/^> Configure project/.test(l)),
+    )
+    return fail('build or tests failed', details, root, logFile)
+  },
+
+  async web(root) {
+    const logFile = logPath(root, 'web')
+    if (!existsSync(path.join(root, 'node_modules'))) return fail('dependencies missing; run `npm install`', [], root, logFile)
+    log.step('web', 'type-checking, testing and building…')
+    const { code, lines } = await runLogged('npm', ['run', 'check', '--workspace', 'apps/web', '--silent'], {
+      cwd: root,
+      logFile,
+      env: { NO_COLOR: '1', CI: '1' },
+    })
+    const tests = lines.map((l) => l.match(/^\s*Tests\s+(\d+) passed/)?.[1]).filter(Boolean).pop()
+    if (code === 0) return { ok: true, summary: tests ? `types, ${tests} tests and build passed` : 'checks passed', details: [], log: shown(root, logFile) }
+    const details = unique(
+      lines.filter((l) => /(error TS\d+|✗|×|FAIL|Error:|AssertionError|expected)/.test(l)).map((l) => l.trim()),
+    )
+    return fail('type-check, tests or build failed', details, root, logFile)
+  },
+}
+
+/** @param {string} summary @param {string[]} details @param {string} root @param {string} logFile @returns {CheckResult} */
+function fail(summary, details, root, logFile) {
+  return { ok: false, summary, details, log: shown(root, logFile) }
+}
+
+/** Total test count from Gradle's JUnit XML reports. @param {string} dir */
+function junitCount(dir) {
+  if (!existsSync(dir)) return 0
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.xml'))
+    .reduce((sum, file) => sum + Number(readFileSync(path.join(dir, file), 'utf8').match(/<testsuite[^>]* tests="(\d+)"/)?.[1] ?? 0), 0)
+}
+
+/** @param {string[]} lines */
+const unique = (lines) => [...new Set(lines)]

package/src/commands/create.js

@@ -0,0 +1,82 @@
+// @ts-check
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { capture, runInherit } from '../lib/exec.js'
+import { copyTemplate } from '../lib/fsutil.js'
+import { CliError, color, log } from '../lib/log.js'
+import { writeLock } from '../lib/managed.js'
+import { isLocalCheckout, PACKAGE_DIR, packageVersion, templateDir } from '../lib/project.js'
+import { findAndroidSdk, writeLocalProperties } from '../lib/toolchains.js'
+import { validateApp } from '../codegen/app.js'
+import { gen } from './gen.js'
+
+/**
+ * Creates a new project from the template.
+ * @param {string} dir
+ * @param {{ name?: string, id?: string, install?: boolean, git?: boolean }} options
+ */
+export async function create(dir, { name, id, install = true, git = true }) {
+  if (!dir) throw new CliError('Usage: geeknative create <folder> [--name "My App"] [--id com.example.myapp]')
+  const root = path.resolve(dir)
+  if (existsSync(root) && readdirSync(root).length) throw new CliError(`${dir} already exists and isn't empty.`)
+
+  const slug = path.basename(root).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app'
+  const appName = name?.trim() || titleCase(slug)
+  const appId = id ?? `com.example.${slug.replace(/-/g, '')}`
+  const version = packageVersion()
+
+  // Fail before writing anything if the name or ID can't work on every platform.
+  validateApp({ name: appName, id: appId, version: '1.0.0', build: 1 })
+
+  log.step('create', `${appName} (${appId}) in ${dir}`)
+  copyTemplate(templateDir(), root)
+
+  // App identity: the one place the name and ID live. Everything else is generated from it.
+  const appFile = path.join(root, 'contracts', 'app.json')
+  const app = JSON.parse(readFileSync(appFile, 'utf8'))
+  writeFileSync(appFile, `${JSON.stringify({ ...app, name: appName, id: appId }, null, 2)}\n`)
+
+  const pkgFile = path.join(root, 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'))
+  pkg.name = slug
+  pkg.devDependencies.geeknative = isLocalCheckout() ? `file:${PACKAGE_DIR}` : `^${version}`
+  writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`)
+
+  for (const doc of ['README.md']) {
+    const file = path.join(root, doc)
+    if (existsSync(file)) writeFileSync(file, readFileSync(file, 'utf8').replaceAll('{{APP_NAME}}', appName))
+  }
+
+  gen(root, { quiet: true })
+  writeLock(root, version)
+  const sdk = findAndroidSdk(root)
+  if (sdk) writeLocalProperties(root, sdk)
+  log.ok('create', 'project files written')
+
+  if (install) {
+    log.step('install', 'npm install…')
+    if ((await runInherit('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: root })) !== 0) {
+      log.warn('install', 'npm install failed; run it again inside the project')
+    } else log.ok('install', 'dependencies installed')
+  }
+
+  if (git && capture('git', ['--version'])) {
+    capture('git', ['init', '-q'], { cwd: root })
+    capture('git', ['add', '-A'], { cwd: root })
+    const committed = capture('git', ['commit', '-q', '-m', 'Initial commit from geeknative'], { cwd: root }) !== null
+    log.ok('git', committed ? 'repository initialized with a first commit' : 'repository initialized (commit skipped: set git user.name and user.email)')
+  }
+
+  log.info(`
+${color.bold('Next steps')}
+  cd ${dir}
+  make doctor          ${color.dim('# checks Xcode, the Android SDK and Node; FIX=1 installs what is missing')}
+  make check           ${color.dim('# builds and tests all three apps')}
+
+Then open the folder in your coding agent (Claude Code, Codex, Cursor, Gemini CLI, ...)
+and describe the app you want. AGENTS.md tells it how to build it for iOS, Android and web.
+`)
+}
+
+/** @param {string} slug */
+const titleCase = (slug) => slug.split('-').map((w) => w[0].toUpperCase() + w.slice(1)).join(' ')

package/src/commands/doctor.js

@@ -0,0 +1,108 @@
+// @ts-check
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { capture, runInherit, runLogged } from '../lib/exec.js'
+import { log } from '../lib/log.js'
+import {
+  ANDROID_COMPILE_SDK,
+  findAndroidSdk,
+  hasCompilePlatform,
+  pickSimulator,
+  sdkManager,
+  writeLocalProperties,
+  xcodeMajorVersion,
+} from '../lib/toolchains.js'
+import { gen } from './gen.js'
+
+const MIN_XCODE = 26
+const MIN_NODE = 22
+
+/**
+ * Checks everything the three apps need to build. With `fix`, installs what it safely can.
+ * @param {string} root
+ * @param {{ fix?: boolean }} options
+ */
+export async function doctor(root, { fix = false }) {
+  let problems = 0
+  /** @param {string} label @param {string} message @param {string} [hint] */
+  const problem = (label, message, hint) => {
+    problems++
+    log.fail(label, message)
+    if (hint) log.detail(hint)
+  }
+
+  // Node and dependencies
+  const nodeMajor = Number(process.versions.node.split('.')[0])
+  if (nodeMajor >= MIN_NODE) log.ok('node', `v${process.versions.node}`)
+  else problem('node', `v${process.versions.node} is too old`, `Install Node ${MIN_NODE} or later (24 LTS recommended).`)
+
+  if (existsSync(path.join(root, 'node_modules'))) log.ok('deps', 'installed')
+  else if (fix) {
+    log.step('deps', 'running npm install…')
+    if ((await runInherit('npm', ['install'], { cwd: root })) === 0) log.ok('deps', 'installed')
+    else problem('deps', 'npm install failed')
+  } else problem('deps', 'not installed', 'Run `npm install` (or `make doctor FIX=1`).')
+
+  // Contracts
+  try {
+    gen(root, { check: true })
+  } catch (error) {
+    problem('contracts', /** @type {Error} */ (error).message)
+  }
+
+  // iOS
+  if (process.platform !== 'darwin') {
+    log.warn('ios', 'skipped: iOS builds need macOS with Xcode')
+  } else {
+    const xcode = xcodeMajorVersion()
+    if (!xcode) problem('xcode', 'not found', 'Install Xcode from the App Store, then run `sudo xcode-select -s /Applications/Xcode.app`.')
+    else if (xcode < MIN_XCODE) problem('xcode', `Xcode ${xcode} is too old`, `Install Xcode ${MIN_XCODE} or later.`)
+    else {
+      log.ok('xcode', capture('xcodebuild', ['-version'])?.split('\n')[0] ?? `Xcode ${xcode}`)
+      const simulator = pickSimulator()
+      if (simulator) log.ok('simulator', `${simulator.name} (${simulator.runtime})`)
+      else problem('simulator', 'no iPhone simulator', 'Run `xcodebuild -downloadPlatform iOS` to install the iOS simulator runtime.')
+    }
+  }
+
+  // Android
+  const java = capture('java', ['-version'], { input: '' }) !== null || existsSync(process.env.JAVA_HOME ?? '/nonexistent')
+  if (java) log.ok('java', 'found (Gradle downloads JDK 21 for the build itself)')
+  else problem('java', 'no JDK found', 'Install a JDK 17 or later (for example `brew install --cask temurin`) so Gradle can start.')
+
+  const sdk = findAndroidSdk(root)
+  if (!sdk) {
+    problem('android', 'Android SDK not found', 'Install Android Studio, or `brew install --cask android-commandlinetools`, then rerun.')
+  } else {
+    writeLocalProperties(root, sdk)
+    log.ok('android', `SDK at ${sdk}`)
+    if (hasCompilePlatform(sdk)) log.ok('platform', `Android API ${ANDROID_COMPILE_SDK} installed`)
+    else if (fix) {
+      const pkg = compilePlatformPackage(sdk)
+      log.step('platform', `installing ${pkg}…`)
+      const manager = sdkManager(sdk)
+      const logFile = path.join(root, '.geeknative', 'logs', 'sdkmanager.log')
+      await runLogged('sh', ['-c', `yes | "${manager}" --sdk_root="${sdk}" --licenses`], { logFile })
+      if ((await runLogged(manager, [`--sdk_root=${sdk}`, pkg], { logFile })).code === 0) {
+        log.ok('platform', `Android API ${ANDROID_COMPILE_SDK} installed`)
+      } else problem('platform', `could not install ${pkg}`, `See ${path.relative(root, logFile)}.`)
+    } else {
+      problem('platform', `Android API ${ANDROID_COMPILE_SDK} is not installed`, 'Run `make doctor FIX=1` to install it.')
+    }
+  }
+
+  log.info('')
+  if (problems) {
+    log.info(`${problems} problem${problems === 1 ? '' : 's'} found.${fix ? '' : ' `make doctor FIX=1` fixes what it can.'}`)
+    process.exitCode = 1
+  } else {
+    log.info('All set. Try `make check`, then describe what you want to build to your coding agent.')
+  }
+}
+
+/** The sdkmanager package for the compile SDK: newer platforms carry a minor version ("android-37.0"). @param {string} sdk */
+function compilePlatformPackage(sdk) {
+  const listing = capture(sdkManager(sdk), [`--sdk_root=${sdk}`, '--list'], { timeout: 120_000 }) ?? ''
+  const exact = `platforms;android-${ANDROID_COMPILE_SDK}.0`
+  return listing.includes(exact) ? exact : `platforms;android-${ANDROID_COMPILE_SDK}`
+}

package/src/commands/gen.js

@@ -0,0 +1,44 @@
+// @ts-check
+import { existsSync, readFileSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { generate, staleFiles } from '../codegen/index.js'
+import { writeIfChanged } from '../lib/fsutil.js'
+import { CliError, log } from '../lib/log.js'
+
+/**
+ * Regenerates platform code from contracts/. With `check`, writes nothing and fails if
+ * anything is out of date (used by `geeknative check`).
+ * @param {string} root
+ * @param {{ check?: boolean, quiet?: boolean }} [options]
+ * @returns {{ changed: string[], removed: string[] }}
+ */
+export function gen(root, { check = false, quiet = false } = {}) {
+  const outputs = generate(root)
+  /** @type {string[]} */
+  const changed = []
+  for (const output of outputs) {
+    const file = path.join(root, output.path)
+    if (check) {
+      const next = typeof output.content === 'string' ? Buffer.from(output.content) : output.content
+      if (!existsSync(file) || !readFileSync(file).equals(next)) changed.push(output.path)
+    } else if (writeIfChanged(file, output.content)) {
+      changed.push(output.path)
+    }
+  }
+  const removed = staleFiles(root, new Set(outputs.map((o) => o.path)))
+  if (!check) for (const file of removed) rmSync(path.join(root, file))
+
+  if (check && (changed.length || removed.length)) {
+    throw new CliError(
+      `Generated files are out of date:\n${[...changed, ...removed].map((f) => `  ${f}`).join('\n')}\nRun \`make gen\`, and never edit generated files by hand.`,
+    )
+  }
+  if (!quiet) {
+    if (check) log.ok('contracts', 'valid, generated files up to date')
+    else if (changed.length || removed.length) {
+      log.ok('gen', `${changed.length} file${changed.length === 1 ? '' : 's'} updated${removed.length ? `, ${removed.length} removed` : ''}`)
+      for (const file of [...changed, ...removed]) log.detail(file)
+    } else log.ok('gen', 'already up to date')
+  }
+  return { changed, removed }
+}

package/src/commands/parity.js

@@ -0,0 +1,134 @@
+// @ts-check
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { walk } from '../lib/fsutil.js'
+import { color, log } from '../lib/log.js'
+import { rel } from '../lib/project.js'
+
+const PLATFORMS = /** @type {const} */ (['ios', 'android', 'web'])
+const LABELS = { ios: 'iOS', android: 'Android', web: 'Web' }
+const STATUS = { done: '✅ done', 'in-progress': '🚧 in progress', planned: '⏳ planned', 'n/a': '➖ n/a' }
+const AC_ID = /AC-[a-z0-9]+(?:-[a-z0-9]+)*-\d+/g
+
+/** Where each app's tests live. */
+const TEST_FILE = {
+  ios: /^apps\/ios\/[^/]*Tests\/.*\.swift$/,
+  android: /^apps\/android\/app\/src\/(test|androidTest)\/.*\.kt$/,
+  web: /^apps\/web\/(src\/.*\.(test|spec)\.tsx?|e2e\/.*\.tsx?)$/,
+}
+
+/**
+ * @typedef {{ id: string, text: string }} Criterion
+ * @typedef {{ id: string, title: string, file: string, status: Record<string, string>, criteria: Criterion[] }} Feature
+ */
+
+/**
+ * Builds spec/parity.md: each feature's status per platform, and which acceptance
+ * criteria each platform's tests cover (tests mention AC IDs in their names).
+ * @param {string} root
+ */
+export function parity(root) {
+  const features = readFeatures(root)
+  /** @type {Record<string, Set<string>>} */
+  const tested = { ios: new Set(), android: new Set(), web: new Set() }
+  for (const file of walk(path.join(root, 'apps'))) {
+    const relative = rel(root, file)
+    for (const platform of PLATFORMS) {
+      if (!TEST_FILE[platform].test(relative)) continue
+      for (const id of readFileSync(file, 'utf8').match(AC_ID) ?? []) tested[platform].add(id)
+    }
+  }
+
+  const rows = features.map((f) => {
+    const cells = PLATFORMS.map((p) => {
+      const status = STATUS[/** @type {keyof typeof STATUS} */ (f.status[p])] ?? f.status[p] ?? '—'
+      if (f.status[p] === 'n/a' || !f.criteria.length) return status
+      const covered = f.criteria.filter((c) => tested[p].has(c.id)).length
+      return `${status} · ${covered}/${f.criteria.length} tested`
+    })
+    return `| [${f.title}](features/${f.file}) | ${cells.join(' | ')} |`
+  })
+
+  const coverage = features
+    .filter((f) => f.criteria.length)
+    .map((f) => {
+      const lines = f.criteria.map((c) => {
+        const cells = PLATFORMS.map((p) => (f.status[p] === 'n/a' ? '➖' : tested[p].has(c.id) ? '✅' : '❌'))
+        return `| ${c.id}: ${c.text.replace(/\|/g, '\\|')} | ${cells.join(' | ')} |`
+      })
+      return `### ${f.title}\n\n| Criterion | iOS | Android | Web |\n|---|---|---|---|\n${lines.join('\n')}`
+    })
+
+  const markdown = `<!-- GENERATED by \`make parity\` from spec/features and each app's tests. Do not edit. -->
+# Parity
+
+Status comes from each feature spec's front matter. "Tested" counts acceptance criteria whose ID
+(like \`AC-settings-2\`) appears in that platform's tests.
+
+| Feature | iOS | Android | Web |
+|---|---|---|---|
+${rows.join('\n')}
+
+## Acceptance criteria coverage
+
+${coverage.join('\n\n')}
+`
+  writeFileSync(path.join(root, 'spec', 'parity.md'), markdown)
+
+  for (const f of features) {
+    const parts = PLATFORMS.map((p) => {
+      const covered = f.criteria.filter((c) => tested[p].has(c.id)).length
+      return `${LABELS[p]} ${f.status[p] ?? '?'} ${f.criteria.length ? `${covered}/${f.criteria.length}` : ''}`.trim()
+    })
+    const gaps = PLATFORMS.flatMap((p) =>
+      f.status[p] === 'n/a' ? [] : f.criteria.filter((c) => !tested[p].has(c.id)).map((c) => `${c.id} untested on ${LABELS[p]}`),
+    )
+    ;(gaps.length ? log.warn : log.ok)(f.id, parts.join(color.dim(' · ')))
+    for (const gap of gaps) log.detail(color.dim(gap))
+  }
+  log.info(color.dim('Wrote spec/parity.md'))
+}
+
+/** @param {string} root @returns {Feature[]} */
+function readFeatures(root) {
+  const dir = path.join(root, 'spec', 'features')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('_'))
+    .sort()
+    .map((file) => {
+      const text = readFileSync(path.join(dir, file), 'utf8')
+      const meta = frontMatter(text)
+      const id = meta.id ?? file.replace(/\.md$/, '')
+      /** @type {Criterion[]} */
+      const criteria = []
+      for (const match of text.matchAll(/^\s*[-*]\s*\**(AC-[a-z0-9]+(?:-[a-z0-9]+)*-\d+)\**\s*[:.]?\s*(.*)$/gm)) {
+        if (!criteria.some((c) => c.id === match[1])) criteria.push({ id: match[1], text: match[2].trim() })
+      }
+      return { id, title: meta.title ?? id, file, status: meta.status ?? {}, criteria }
+    })
+}
+
+/**
+ * Reads the small YAML subset used in spec front matter: `key: value` and one level of nesting.
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+function frontMatter(text) {
+  const match = text.match(/^---\n([\s\S]*?)\n---/)
+  /** @type {Record<string, any>} */
+  const meta = {}
+  if (!match) return meta
+  let parent = ''
+  for (const raw of match[1].split('\n')) {
+    const line = raw.replace(/\s+#.*$/, '')
+    const nested = line.match(/^\s+([\w-]+):\s*(.+)$/)
+    const top = line.match(/^([\w-]+):\s*(.*)$/)
+    if (nested && parent) meta[parent][nested[1]] = nested[2].trim()
+    else if (top) {
+      parent = top[2].trim() ? '' : top[1]
+      meta[top[1]] = top[2].trim() || {}
+    }
+  }
+  return meta
+}

package/src/commands/run.js

@@ -0,0 +1,91 @@
+// @ts-check
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { readApp } from '../codegen/app.js'
+import { capture, runInherit, runLogged } from '../lib/exec.js'
+import { CliError, log } from '../lib/log.js'
+import { adb, emulator, findAndroidSdk, pickSimulator, writeLocalProperties } from '../lib/toolchains.js'
+
+/**
+ * Builds and launches one app: on a simulator, an emulator or device, or the web dev server.
+ * @param {string} root
+ * @param {string} platform
+ */
+export async function run(root, platform) {
+  if (platform === 'web') return runWeb(root)
+  if (platform === 'ios') return runIos(root)
+  if (platform === 'android') return runAndroid(root)
+  throw new CliError('Usage: geeknative run <ios|android|web>')
+}
+
+/** @param {string} root */
+async function runWeb(root) {
+  process.exitCode = await runInherit('npm', ['run', 'dev', '--workspace', 'apps/web'], { cwd: root })
+}
+
+/** @param {string} root */
+async function runIos(root) {
+  const simulator = pickSimulator()
+  if (!simulator) throw new CliError('No iPhone simulator found. Run `make doctor`.')
+  const { id } = readApp(root)
+  const logFile = path.join(root, '.geeknative', 'logs', 'ios-run.log')
+
+  if (simulator.state !== 'Booted') {
+    log.step('ios', `booting ${simulator.name}…`)
+    capture('xcrun', ['simctl', 'boot', simulator.udid])
+  }
+  capture('open', ['-a', 'Simulator'])
+
+  log.step('ios', 'building…')
+  const build = await runLogged(
+    'xcodebuild',
+    ['build', '-project', 'App.xcodeproj', '-scheme', 'App', '-destination', `id=${simulator.udid}`, '-derivedDataPath', '.build/DerivedData', '-quiet'],
+    { cwd: path.join(root, 'apps', 'ios'), logFile },
+  )
+  if (build.code !== 0) throw new CliError(`Build failed. Run \`make check-ios\` for details (log: ${path.relative(root, logFile)}).`)
+
+  const app = path.join(root, 'apps', 'ios', '.build', 'DerivedData', 'Build', 'Products', 'Debug-iphonesimulator', 'App.app')
+  if (capture('xcrun', ['simctl', 'install', simulator.udid, app]) === null) throw new CliError('Could not install the app on the simulator.')
+  if (capture('xcrun', ['simctl', 'launch', simulator.udid, id]) === null) throw new CliError(`Could not launch ${id}.`)
+  log.ok('ios', `running on ${simulator.name} (${simulator.runtime})`)
+}
+
+/** @param {string} root */
+async function runAndroid(root) {
+  const sdk = findAndroidSdk(root)
+  if (!sdk) throw new CliError('Android SDK not found. Run `make doctor`.')
+  writeLocalProperties(root, sdk)
+  const { id } = readApp(root)
+  const adbPath = adb(sdk)
+
+  if (!connectedDevice(adbPath)) {
+    const avds = (capture(emulator(sdk), ['-list-avds']) ?? '').split('\n').filter(Boolean)
+    if (!avds.length) {
+      throw new CliError(
+        'No device or emulator. Connect a device with USB debugging on, or create an emulator in Android Studio (Device Manager), then rerun.',
+      )
+    }
+    log.step('android', `starting emulator ${avds[0]}…`)
+    spawn(emulator(sdk), ['-avd', avds[0]], { detached: true, stdio: 'ignore' }).unref()
+    capture(adbPath, ['wait-for-device'], { timeout: 180_000 })
+    for (let i = 0; i < 90 && capture(adbPath, ['shell', 'getprop', 'sys.boot_completed']) !== '1'; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 2000))
+    }
+  }
+
+  log.step('android', 'building and installing…')
+  const logFile = path.join(root, '.geeknative', 'logs', 'android-run.log')
+  const install = await runLogged('./gradlew', [':app:installDebug', '--console=plain'], {
+    cwd: path.join(root, 'apps', 'android'),
+    logFile,
+  })
+  if (install.code !== 0) throw new CliError(`Install failed. Run \`make check-android\` for details (log: ${path.relative(root, logFile)}).`)
+  capture(adbPath, ['shell', 'am', 'start', '-n', `${id}/app.MainActivity`])
+  log.ok('android', `running ${id}`)
+}
+
+/** @param {string} adbPath */
+function connectedDevice(adbPath) {
+  const out = capture(adbPath, ['devices']) ?? ''
+  return out.split('\n').slice(1).some((line) => /\tdevice$/.test(line))
+}