geeknative 0.0.0-stage → 0.1.0

package/src/lib/exec.js

@@ -0,0 +1,77 @@
+// @ts-check
+import { spawn, spawnSync } from 'node:child_process'
+import { createWriteStream, mkdirSync } from 'node:fs'
+import path from 'node:path'
+
+/**
+ * Runs a command, writing all of its output to `logFile`.
+ * Agents get a short summary on screen and can open the log when they need detail.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, logFile: string, env?: Record<string, string> }} options
+ * @returns {Promise<{ code: number, lines: string[] }>}
+ */
+export function runLogged(cmd, args, { cwd, logFile, env }) {
+  mkdirSync(path.dirname(logFile), { recursive: true })
+  return new Promise((resolve) => {
+    const out = createWriteStream(logFile)
+    out.write(`$ ${[cmd, ...args].join(' ')}\n\n`)
+    const child = spawn(cmd, args, { cwd, env: { ...process.env, ...env } })
+    /** @type {string[]} */
+    const lines = []
+    let pending = ''
+    /** @param {Buffer} chunk */
+    const collect = (chunk) => {
+      // Plain text: easier for agents to read, and for us to match.
+      // eslint-disable-next-line no-control-regex
+      const text = chunk.toString().replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
+      out.write(text)
+      pending += text
+      const parts = pending.split('\n')
+      pending = parts.pop() ?? ''
+      lines.push(...parts)
+    }
+    child.stdout.on('data', collect)
+    child.stderr.on('data', collect)
+    child.on('error', (error) => {
+      out.end()
+      resolve({ code: 127, lines: [String(error)] })
+    })
+    child.on('close', (code) => {
+      if (pending) lines.push(pending)
+      out.end()
+      resolve({ code: code ?? 1, lines })
+    })
+  })
+}
+
+/**
+ * Runs a command attached to this terminal (for dev servers and interactive tools).
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, env?: Record<string, string> }} [options]
+ * @returns {Promise<number>}
+ */
+export function runInherit(cmd, args, { cwd, env } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: 'inherit', env: { ...process.env, ...env } })
+    child.on('error', () => resolve(127))
+    child.on('close', (code) => resolve(code ?? 1))
+  })
+}
+
+/**
+ * Runs a command and returns its trimmed stdout, or null when it fails or isn't installed.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd?: string, input?: string, timeout?: number }} [options]
+ */
+export function capture(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, { encoding: 'utf8', ...options })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+/** @param {string} cmd */
+export function which(cmd) {
+  return capture('which', [cmd])
+}

package/src/lib/fsutil.js

@@ -0,0 +1,92 @@
+// @ts-check
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
+import path from 'node:path'
+import { CliError } from './log.js'
+
+/** Build output and local state that never belongs in a template copy. */
+const ARTIFACTS = new Set([
+  'node_modules',
+  '.build',
+  'build',
+  '.gradle',
+  '.kotlin',
+  '.idea',
+  'DerivedData',
+  'xcuserdata',
+  '.output',
+  '.tanstack',
+  '.nitro',
+  '.vinxi',
+  'dist',
+  '.DS_Store',
+  'local.properties',
+  'package-lock.json',
+])
+
+/**
+ * Reads and parses a JSON file, with an error message an agent can act on.
+ * @param {string} file
+ * @param {string} label shown in errors, e.g. "contracts/app.json"
+ */
+export function readJson(file, label) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    throw new CliError(`${label} is missing.`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new CliError(`${label} is not valid JSON: ${/** @type {Error} */ (error).message}`)
+  }
+}
+
+/**
+ * Writes `content` only if it differs from what's on disk. Returns true when the file changed.
+ * @param {string} file
+ * @param {string | Buffer} content
+ */
+export function writeIfChanged(file, content) {
+  const next = typeof content === 'string' ? Buffer.from(content) : content
+  if (existsSync(file) && readFileSync(file).equals(next)) return false
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, next)
+  return true
+}
+
+/**
+ * Lists files under `dir` recursively, skipping build artifacts and dependencies.
+ * @param {string} dir
+ * @returns {string[]} absolute paths
+ */
+export function walk(dir) {
+  if (!existsSync(dir)) return []
+  /** @type {string[]} */
+  const files = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (ARTIFACTS.has(entry.name)) continue
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) files.push(...walk(full))
+    else files.push(full)
+  }
+  return files
+}
+
+/**
+ * Copies the template into a new project. Files named `_gitignore` become `.gitignore`
+ * (npm drops real .gitignore files from published packages).
+ * @param {string} from
+ * @param {string} to
+ * @param {{ keepGitignoreNames?: boolean }} [options]
+ */
+export function copyTemplate(from, to, { keepGitignoreNames = false } = {}) {
+  for (const file of walk(from)) {
+    const relative = path.relative(from, file)
+    if (relative.startsWith(`.geeknative${path.sep}logs${path.sep}`)) continue
+    const renamed = keepGitignoreNames ? relative : relative.replace(/(^|[\\/])_gitignore$/, '$1.gitignore')
+    const target = path.join(to, renamed)
+    mkdirSync(path.dirname(target), { recursive: true })
+    copyFileSync(file, target)
+  }
+}

package/src/lib/log.js

@@ -0,0 +1,37 @@
+// @ts-check
+
+const useColor = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+
+/** @param {number} code */
+const paint = (code) => /** @param {unknown} text */ (text) =>
+  useColor ? `\x1b[${code}m${text}\x1b[0m` : String(text)
+
+export const color = {
+  bold: paint(1),
+  dim: paint(2),
+  red: paint(31),
+  green: paint(32),
+  yellow: paint(33),
+  cyan: paint(36),
+}
+
+/** @param {string} mark @param {string} label @param {string} message */
+const line = (mark, label, message) => console.log(`${mark} ${label.padEnd(10)} ${message}`)
+
+export const log = {
+  /** @param {string} message */
+  info: (message) => console.log(message),
+  /** @param {string} label @param {string} message */
+  step: (label, message) => line(color.cyan('▸'), label, message),
+  /** @param {string} label @param {string} message */
+  ok: (label, message) => line(color.green('✔'), label, message),
+  /** @param {string} label @param {string} message */
+  warn: (label, message) => line(color.yellow('!'), label, message),
+  /** @param {string} label @param {string} message */
+  fail: (label, message) => line(color.red('✖'), label, message),
+  /** @param {string} message */
+  detail: (message) => console.log(`             ${message}`),
+}
+
+/** An expected failure: printed without a stack trace. */
+export class CliError extends Error {}

package/src/lib/managed.js

@@ -0,0 +1,80 @@
+// @ts-check
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { walk } from './fsutil.js'
+import { rel } from './project.js'
+
+/*
+ * Every file in a geeknative project has one owner:
+ * - Framework: the files and AGENTS.md blocks listed here. `geeknative upgrade` replaces them.
+ * - Project: everything else (docs, spec, contracts, app code). Upgrades never touch it.
+ * - Generated: output of `geeknative gen`, rebuilt from contracts.
+ * The lockfile records a hash of each framework-owned piece as installed, so an upgrade can
+ * tell untouched files (safe to replace) from locally edited ones (merge instead).
+ */
+
+export const MANAGED_DIRS = [
+  '.geeknative/playbooks',
+  '.geeknative/templates',
+  '.geeknative/hooks',
+]
+
+export const MANAGED_FILES = [
+  '.geeknative/framework.mk',
+  '.claude/agents/ios-engineer.md',
+  '.claude/agents/android-engineer.md',
+  '.claude/agents/web-engineer.md',
+]
+
+/** Files with a framework-owned block between the markers below; the rest of the file is the project's. */
+export const MANAGED_BLOCK_FILES = ['AGENTS.md', 'CLAUDE.md', 'apps/ios/AGENTS.md', 'apps/android/AGENTS.md', 'apps/web/AGENTS.md']
+
+const BLOCK = /<!-- geeknative:begin[^>]*-->[\s\S]*?<!-- geeknative:end -->/
+
+/** @param {string} text */
+export function extractBlock(text) {
+  return text.match(BLOCK)?.[0] ?? null
+}
+
+/** @param {string | Buffer} content */
+const hash = (content) => `sha256-${createHash('sha256').update(content).digest('hex')}`
+
+/**
+ * Hashes every framework-owned file and block in a project.
+ * @param {string} root
+ */
+export function managedHashes(root) {
+  /** @type {Record<string, string>} */
+  const files = {}
+  for (const dir of MANAGED_DIRS) {
+    for (const file of walk(path.join(root, dir))) files[rel(root, file)] = hash(readFileSync(file))
+  }
+  for (const file of MANAGED_FILES) {
+    const full = path.join(root, file)
+    if (existsSync(full)) files[file] = hash(readFileSync(full))
+  }
+  /** @type {Record<string, string>} */
+  const blocks = {}
+  for (const file of MANAGED_BLOCK_FILES) {
+    const full = path.join(root, file)
+    const block = existsSync(full) ? extractBlock(readFileSync(full, 'utf8')) : null
+    if (block) blocks[file] = hash(block)
+  }
+  return { files: sortKeys(files), blocks: sortKeys(blocks) }
+}
+
+/**
+ * Writes .geeknative/lock.json: the framework version and the hashes of what it installed.
+ * @param {string} root
+ * @param {string} version
+ */
+export function writeLock(root, version) {
+  const lock = { geeknative: version, ...managedHashes(root) }
+  writeFileSync(path.join(root, '.geeknative', 'lock.json'), `${JSON.stringify(lock, null, 2)}\n`)
+}
+
+/** @param {Record<string, string>} object */
+function sortKeys(object) {
+  return Object.fromEntries(Object.entries(object).sort(([a], [b]) => a.localeCompare(b)))
+}

package/src/lib/project.js

@@ -0,0 +1,52 @@
+// @ts-check
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { CliError } from './log.js'
+
+/** Root of the geeknative npm package. */
+export const PACKAGE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
+
+/** The repo's template/ folder, which exists only when running from a git checkout. */
+const REPO_TEMPLATE_DIR = path.resolve(PACKAGE_DIR, '../../template')
+
+/** True when this CLI runs from a checkout of the geeknative repo rather than from npm. */
+export function isLocalCheckout() {
+  return !existsSync(path.join(PACKAGE_DIR, 'template')) && existsSync(REPO_TEMPLATE_DIR)
+}
+
+/** The project template: bundled in the npm package, or the repo's template/ in a checkout. */
+export function templateDir() {
+  const bundled = path.join(PACKAGE_DIR, 'template')
+  if (existsSync(bundled)) return bundled
+  if (existsSync(REPO_TEMPLATE_DIR)) return REPO_TEMPLATE_DIR
+  throw new CliError('Could not find the geeknative template.')
+}
+
+export function packageVersion() {
+  return JSON.parse(readFileSync(path.join(PACKAGE_DIR, 'package.json'), 'utf8')).version
+}
+
+/** Walks up from `start` to the project root: the folder that contains contracts/app.json. */
+export function findProjectRoot(start = process.cwd()) {
+  let dir = path.resolve(start)
+  for (;;) {
+    if (existsSync(path.join(dir, 'contracts', 'app.json'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) {
+      throw new CliError(
+        'Not inside a geeknative project (no contracts/app.json found). Run this from your project folder.',
+      )
+    }
+    dir = parent
+  }
+}
+
+/**
+ * Path relative to the project root, with forward slashes.
+ * @param {string} root
+ * @param {string} file
+ */
+export function rel(root, file) {
+  return path.relative(root, file).split(path.sep).join('/')
+}

package/src/lib/toolchains.js

@@ -0,0 +1,126 @@
+// @ts-check
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { capture } from './exec.js'
+
+/** Android API level the app compiles against (apps/android/app/build.gradle.kts). */
+export const ANDROID_COMPILE_SDK = 37
+
+// ---------- Android ----------
+
+/** @param {string} root */
+function localPropertiesPath(root) {
+  return path.join(root, 'apps', 'android', 'local.properties')
+}
+
+/**
+ * Finds an Android SDK: local.properties, then ANDROID_HOME / ANDROID_SDK_ROOT, then common install locations.
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findAndroidSdk(root) {
+  const local = localPropertiesPath(root)
+  if (existsSync(local)) {
+    const match = readFileSync(local, 'utf8').match(/^sdk\.dir=(.+)$/m)
+    if (match && existsSync(match[1].trim())) return match[1].trim()
+  }
+  const home = os.homedir()
+  const candidates = [
+    process.env.ANDROID_HOME,
+    process.env.ANDROID_SDK_ROOT,
+    path.join(home, 'Library', 'Android', 'sdk'),
+    '/opt/homebrew/share/android-commandlinetools',
+    '/usr/local/share/android-commandlinetools',
+    path.join(home, 'Android', 'Sdk'),
+  ]
+  for (const candidate of candidates) {
+    if (candidate && existsSync(path.join(candidate, 'platform-tools'))) return candidate
+    if (candidate && existsSync(path.join(candidate, 'platforms'))) return candidate
+  }
+  return null
+}
+
+/**
+ * Points Gradle at the SDK. local.properties is machine-specific and git-ignored.
+ * @param {string} root
+ * @param {string} sdk
+ */
+export function writeLocalProperties(root, sdk) {
+  writeFileSync(localPropertiesPath(root), `sdk.dir=${sdk}\n`)
+}
+
+/** @param {string} sdk */
+export function hasCompilePlatform(sdk) {
+  const platforms = path.join(sdk, 'platforms')
+  if (!existsSync(platforms)) return false
+  return readdirSync(platforms).some((name) => name === `android-${ANDROID_COMPILE_SDK}` || name.startsWith(`android-${ANDROID_COMPILE_SDK}.`))
+}
+
+/** @param {string} sdk */
+export function sdkManager(sdk) {
+  const bundled = path.join(sdk, 'cmdline-tools', 'latest', 'bin', 'sdkmanager')
+  return existsSync(bundled) ? bundled : 'sdkmanager'
+}
+
+/** @param {string} sdk */
+export function adb(sdk) {
+  const bundled = path.join(sdk, 'platform-tools', 'adb')
+  return existsSync(bundled) ? bundled : 'adb'
+}
+
+/** @param {string} sdk */
+export function emulator(sdk) {
+  const bundled = path.join(sdk, 'emulator', 'emulator')
+  return existsSync(bundled) ? bundled : 'emulator'
+}
+
+// ---------- iOS ----------
+
+/**
+ * @typedef {{ udid: string, name: string, state: string, runtime: string, version: number[] }} Simulator
+ */
+
+/**
+ * Picks the simulator to build and test on: GEEKNATIVE_IOS_SIMULATOR (name or UDID) if set,
+ * otherwise a booted iPhone, otherwise an iPhone on the newest installed iOS runtime.
+ * @returns {Simulator | null}
+ */
+export function pickSimulator() {
+  const json = capture('xcrun', ['simctl', 'list', 'devices', 'available', '--json'])
+  if (!json) return null
+  /** @type {Simulator[]} */
+  const all = []
+  for (const [runtime, devices] of Object.entries(JSON.parse(json).devices ?? {})) {
+    const match = runtime.match(/iOS-(\d+)-(\d+)(?:-(\d+))?$/)
+    if (!match) continue
+    const version = match.slice(1).filter(Boolean).map(Number)
+    for (const device of /** @type {any[]} */ (devices)) {
+      if (device.isAvailable === false) continue
+      all.push({ udid: device.udid, name: device.name, state: device.state, runtime: `iOS ${version.join('.')}`, version })
+    }
+  }
+  const wanted = process.env.GEEKNATIVE_IOS_SIMULATOR
+  if (wanted) return all.find((sim) => sim.udid === wanted || sim.name === wanted) ?? null
+  const iphones = all.filter((sim) => sim.name.startsWith('iPhone'))
+  const booted = iphones.find((sim) => sim.state === 'Booted')
+  if (booted) return booted
+  iphones.sort((a, b) => compareVersions(b.version, a.version))
+  return iphones[0] ?? null
+}
+
+/** @param {number[]} a @param {number[]} b */
+function compareVersions(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] ?? 0) - (b[i] ?? 0)
+    if (diff) return diff
+  }
+  return 0
+}
+
+/** Xcode's major version, or null when Xcode isn't installed. */
+export function xcodeMajorVersion() {
+  const out = capture('xcodebuild', ['-version'])
+  const match = out?.match(/^Xcode (\d+)/m)
+  return match ? Number(match[1]) : null
+}

package/template/.claude/agents/android-engineer.md

@@ -0,0 +1,15 @@
+---
+name: android-engineer
+description: Implements and verifies changes in the Android app (apps/android, Kotlin and Jetpack Compose). Use for the Android part of any change to the apps, in parallel with ios-engineer and web-engineer.
+---
+
+You build the Android app in apps/android. You're one of three platform engineers implementing the same spec; the lead agent coordinates.
+
+Your brief from the lead has the spec path, the acceptance criteria IDs and what changed in contracts/. The Android conventions are in apps/android/AGENTS.md (given to you at start).
+
+1. Read the spec. Look at an existing feature (features/settings) and follow the same patterns.
+2. Implement from the spec. Don't port code from apps/ios or apps/web.
+3. Edit only files under apps/android/. Never edit spec/, contracts/, PRODUCT.md, DESIGN.md or generated files. If the spec is ambiguous or missing something, build what's clear and report the gap instead of guessing.
+4. Add or update tests named after the acceptance criteria: ``fun `AC-<id>-<n> ...`()``.
+5. Run `make check-android` until it passes.
+6. Report: the files you changed, the acceptance criteria your tests cover, the check result, and any spec gaps or questions.

package/template/.claude/agents/ios-engineer.md

@@ -0,0 +1,15 @@
+---
+name: ios-engineer
+description: Implements and verifies changes in the iOS app (apps/ios, SwiftUI). Use for the iOS part of any change to the apps, in parallel with android-engineer and web-engineer.
+---
+
+You build the iOS app in apps/ios. You're one of three platform engineers implementing the same spec; the lead agent coordinates.
+
+Your brief from the lead has the spec path, the acceptance criteria IDs and what changed in contracts/. The iOS conventions are in apps/ios/AGENTS.md (given to you at start).
+
+1. Read the spec. Look at an existing feature (App/Features/Settings) and follow the same patterns.
+2. Implement from the spec. Don't port code from apps/android or apps/web.
+3. Edit only files under apps/ios/. Never edit spec/, contracts/, PRODUCT.md, DESIGN.md or generated files. If the spec is ambiguous or missing something, build what's clear and report the gap instead of guessing.
+4. Add or update tests named after the acceptance criteria: `@Test("AC-<id>-<n>: ...")`.
+5. Run `make check-ios` until it passes.
+6. Report: the files you changed, the acceptance criteria your tests cover, the check result, and any spec gaps or questions.

package/template/.claude/agents/web-engineer.md

@@ -0,0 +1,15 @@
+---
+name: web-engineer
+description: Implements and verifies changes in the web app (apps/web, React with TanStack Start). Use for the web part of any change to the apps, in parallel with ios-engineer and android-engineer.
+---
+
+You build the web app in apps/web. You're one of three platform engineers implementing the same spec; the lead agent coordinates.
+
+Your brief from the lead has the spec path, the acceptance criteria IDs and what changed in contracts/. The web conventions are in apps/web/AGENTS.md (given to you at start).
+
+1. Read the spec. Look at an existing feature (src/features/settings) and follow the same patterns.
+2. Implement from the spec. Don't port code from apps/ios or apps/android.
+3. Edit only files under apps/web/. Never edit spec/, contracts/, PRODUCT.md, DESIGN.md or generated files. If the spec is ambiguous or missing something, build what's clear and report the gap instead of guessing.
+4. Add or update tests named after the acceptance criteria: `test('AC-<id>-<n>: ...')`.
+5. Run `make check-web` until it passes.
+6. Report: the files you changed, the acceptance criteria your tests cover, the check result, and any spec gaps or questions.

package/template/.claude/settings.json

@@ -0,0 +1,65 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(make *)",
+      "Bash(npx geeknative *)",
+      "Bash(./node_modules/.bin/geeknative *)",
+      "Bash(npm run *)",
+      "Bash(xcodebuild *)",
+      "Bash(xcrun simctl *)",
+      "Bash(./gradlew *)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.geeknative/hooks/after-edit.mjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "ios-engineer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.geeknative/hooks/subagent-context.mjs\" ios"
+          }
+        ]
+      },
+      {
+        "matcher": "android-engineer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.geeknative/hooks/subagent-context.mjs\" android"
+          }
+        ]
+      },
+      {
+        "matcher": "web-engineer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.geeknative/hooks/subagent-context.mjs\" web"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.geeknative/hooks/parity-guard.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.geeknative/framework.mk

@@ -0,0 +1,41 @@
+# Managed by geeknative: replaced on upgrade. Add your own targets to the root Makefile.
+
+GEEKNATIVE ?= ./node_modules/.bin/geeknative
+
+.PHONY: help doctor gen check check-contracts check-ios check-android check-web parity run-ios run-android run-web
+
+help: ## List the commands
+	@grep -hE '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-16s %s\n", $$1, $$2}'
+
+doctor: ## Check toolchains (FIX=1 installs what it can)
+	@$(GEEKNATIVE) doctor $(if $(FIX),--fix)
+
+gen: ## Regenerate app code from contracts/
+	@$(GEEKNATIVE) gen
+
+check: ## Validate contracts, then build and test all three apps
+	@$(GEEKNATIVE) check all
+
+check-contracts: ## Validate contracts and check generated code is current
+	@$(GEEKNATIVE) check contracts
+
+check-ios: ## Build and test the iOS app
+	@$(GEEKNATIVE) check ios
+
+check-android: ## Build and test the Android app
+	@$(GEEKNATIVE) check android
+
+check-web: ## Type-check, test and build the web app
+	@$(GEEKNATIVE) check web
+
+parity: ## Update spec/parity.md from feature specs and tests
+	@$(GEEKNATIVE) parity
+
+run-ios: ## Build and launch the iOS app in a simulator
+	@$(GEEKNATIVE) run ios
+
+run-android: ## Build and launch the Android app on an emulator or device
+	@$(GEEKNATIVE) run android
+
+run-web: ## Start the web dev server
+	@$(GEEKNATIVE) run web

package/template/.geeknative/hooks/after-edit.mjs

@@ -0,0 +1,28 @@
+// Claude Code PostToolUse hook (managed by geeknative).
+// When a file in contracts/ is edited, regenerate app code right away, so the next build
+// sees the change and mistakes in the contract are reported immediately.
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+
+let input = ''
+for await (const chunk of process.stdin) input += chunk
+const file = JSON.parse(input || '{}').tool_input?.file_path
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+
+if (!file || !path.resolve(root, file).startsWith(path.join(root, 'contracts') + path.sep)) process.exit(0)
+
+const result = spawnSync(path.join(root, 'node_modules', '.bin', 'geeknative'), ['gen'], { cwd: root, encoding: 'utf8' })
+const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+
+if (result.error || result.status !== 0) {
+  console.error(`\`make gen\` failed after editing ${path.relative(root, file)}. Fix the contract:\n${output || result.error}`)
+  process.exit(2)
+}
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: `Contracts changed, so geeknative regenerated the app code:\n${output}`,
+    },
+  }),
+)