geeknative 0.0.0-stage → 0.1.0

package/template/apps/web/src/generated/icons.ts

@@ -0,0 +1,9 @@
+// GENERATED by geeknative from contracts/icons.json. Do not edit: change the contract, then run `make gen`.
+import { ArrowLeft, House, Settings } from 'lucide-react'
+
+/** Icons as Lucide components. Use as `<AppIcons.settings className="size-6" />`. */
+export const AppIcons = {
+  back: ArrowLeft,
+  home: House,
+  settings: Settings,
+} as const

package/template/apps/web/src/generated/strings.ts

@@ -0,0 +1,88 @@
+// GENERATED by geeknative from contracts/strings. Do not edit: change the contract, then run `make gen`.
+
+export const locales = ["en"] as const
+export type Locale = (typeof locales)[number]
+export const defaultLocale: Locale = "en"
+
+type Plural = Partial<Record<Intl.LDMLPluralRule, string>> & { other: string }
+
+const messages: Record<Locale, Record<string, string | Plural>> = {
+  "en": {
+    "common.back": "Back",
+    "home.openSettings": "Settings",
+    "home.welcomeBody": "This app is built natively for iOS, Android and the web from one shared spec. Describe what you want to build to your coding agent, and it will build it for all three.",
+    "home.welcomeTitle": "You're all set",
+    "settings.about.title": "About",
+    "settings.about.version": "Version {version} ({build:int})",
+    "settings.appearance.dark": "Dark",
+    "settings.appearance.light": "Light",
+    "settings.appearance.system": "System",
+    "settings.appearance.title": "Appearance",
+    "settings.title": "Settings",
+  },
+}
+
+let currentLocale: Locale = defaultLocale
+
+/** Switches the language `strings` returns. */
+export function setLocale(locale: Locale) {
+  currentLocale = locale
+}
+
+function lookup(key: string) {
+  return messages[currentLocale][key] ?? messages[defaultLocale][key]
+}
+
+function text(key: string, args: Record<string, string | number> = {}): string {
+  return fill(lookup(key) as string, args)
+}
+
+function fill(template: string, args: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)(?::\w+)?\}/g, (_, name: string) => String(args[name]))
+}
+
+/** User-facing copy. Keys and placeholders match the iOS and Android apps. */
+export const strings = {
+  /** Back */
+  get commonBack() {
+    return text("common.back")
+  },
+  /** Settings */
+  get homeOpenSettings() {
+    return text("home.openSettings")
+  },
+  /** This app is built natively for iOS, Android and the web from one shared spec. Describe what you want to build to your coding agent, and it will build it for all three. */
+  get homeWelcomeBody() {
+    return text("home.welcomeBody")
+  },
+  /** You're all set */
+  get homeWelcomeTitle() {
+    return text("home.welcomeTitle")
+  },
+  /** About */
+  get settingsAboutTitle() {
+    return text("settings.about.title")
+  },
+  /** Version {version} ({build}) */
+  settingsAboutVersion: (args: { version: string; build: number }) => text("settings.about.version", args),
+  /** Dark */
+  get settingsAppearanceDark() {
+    return text("settings.appearance.dark")
+  },
+  /** Light */
+  get settingsAppearanceLight() {
+    return text("settings.appearance.light")
+  },
+  /** System */
+  get settingsAppearanceSystem() {
+    return text("settings.appearance.system")
+  },
+  /** Appearance */
+  get settingsAppearanceTitle() {
+    return text("settings.appearance.title")
+  },
+  /** Settings */
+  get settingsTitle() {
+    return text("settings.title")
+  },
+}

package/template/apps/web/src/generated/tokens.css

@@ -0,0 +1,86 @@
+/* GENERATED by geeknative from contracts/tokens.json. Do not edit: change the contract, then run `make gen`. */
+
+/*
+ * Tailwind theme: bg-primary, text-on-surface, p-md, gap-lg, rounded-lg, text-title, ...
+ * Dark values apply when <html> has the "dark" class (see AppearanceEffect).
+ */
+@theme {
+  --color-background: #ffffff;
+  --color-on-background: #0f172a;
+  --color-surface: #f4f5f8;
+  --color-on-surface: #0f172a;
+  --color-surface-variant: #e9ebf1;
+  --color-on-surface-variant: #566074;
+  --color-primary: #4f46e5;
+  --color-on-primary: #ffffff;
+  --color-outline: #d8dce5;
+  --color-error: #dc2626;
+  --color-on-error: #ffffff;
+
+  /* shadcn/ui names, mapped onto the tokens above */
+  --color-foreground: var(--color-on-background);
+  --color-card: var(--color-surface);
+  --color-card-foreground: var(--color-on-surface);
+  --color-popover: var(--color-surface);
+  --color-popover-foreground: var(--color-on-surface);
+  --color-primary-foreground: var(--color-on-primary);
+  --color-secondary: var(--color-surface-variant);
+  --color-secondary-foreground: var(--color-on-surface);
+  --color-muted: var(--color-surface-variant);
+  --color-muted-foreground: var(--color-on-surface-variant);
+  --color-accent: var(--color-surface-variant);
+  --color-accent-foreground: var(--color-on-surface);
+  --color-destructive: var(--color-error);
+  --color-destructive-foreground: var(--color-on-error);
+  --color-border: var(--color-outline);
+  --color-input: var(--color-outline);
+  --color-ring: var(--color-primary);
+
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --spacing-md: 12px;
+  --spacing-lg: 16px;
+  --spacing-xl: 24px;
+  --spacing-xxl: 32px;
+
+  --radius-sm: 6px;
+  --radius-md: 10px;
+  --radius-lg: 16px;
+  --radius-full: calc(infinity * 1px);
+
+  --text-display: 2.125rem;
+  --text-display--line-height: 2.5625rem;
+  --text-display--font-weight: 700;
+  --text-headline: 1.75rem;
+  --text-headline--line-height: 2.125rem;
+  --text-headline--font-weight: 700;
+  --text-title: 1.25rem;
+  --text-title--line-height: 1.625rem;
+  --text-title--font-weight: 600;
+  --text-body: 1rem;
+  --text-body--line-height: 1.5rem;
+  --text-body--font-weight: 400;
+  --text-label: 0.875rem;
+  --text-label--line-height: 1.25rem;
+  --text-label--font-weight: 500;
+  --text-caption: 0.75rem;
+  --text-caption--line-height: 1rem;
+  --text-caption--font-weight: 400;
+
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+}
+
+.dark {
+  color-scheme: dark;
+  --color-background: #0b0d12;
+  --color-on-background: #e6e8ee;
+  --color-surface: #161a23;
+  --color-on-surface: #e6e8ee;
+  --color-surface-variant: #222735;
+  --color-on-surface-variant: #a3abbd;
+  --color-primary: #a5b4fc;
+  --color-on-primary: #1e1b4b;
+  --color-outline: #2d3343;
+  --color-error: #f87171;
+  --color-on-error: #450a0a;
+}

package/template/apps/web/src/routeTree.gen.ts

@@ -0,0 +1,86 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as SettingsRouteImport } from './routes/settings'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const SettingsRoute = SettingsRouteImport.update({
+  id: '/settings',
+  path: '/settings',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/settings': typeof SettingsRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/settings': typeof SettingsRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/settings': typeof SettingsRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/settings'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/settings'
+  id: '__root__' | '/' | '/settings'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  SettingsRoute: typeof SettingsRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/settings': {
+      id: '/settings'
+      path: '/settings'
+      fullPath: '/settings'
+      preLoaderRoute: typeof SettingsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  SettingsRoute: SettingsRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}

package/template/apps/web/src/router.tsx

@@ -0,0 +1,23 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createRouter } from '@tanstack/react-router'
+import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
+import { createAppContainer } from './core/AppContainer'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const queryClient = new QueryClient()
+  const router = createRouter({
+    routeTree,
+    context: { queryClient, container: createAppContainer() },
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+  })
+  setupRouterSsrQueryIntegration({ router, queryClient })
+  return router
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}

package/template/apps/web/src/routes/__root.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react'
+import type { QueryClient } from '@tanstack/react-query'
+import { HeadContent, Link, Outlet, ScriptOnce, Scripts, createRootRouteWithContext } from '@tanstack/react-router'
+import type { AppContainer } from '#/core/AppContainer'
+import { AppearanceEffect, appearanceScript } from '#/core/AppearanceEffect'
+import { AppIdentity } from '#/generated/app'
+import { AppIcons } from '#/generated/icons'
+import { defaultLocale, strings } from '#/generated/strings'
+import appCss from '../styles.css?url'
+
+export interface RouterContext {
+  queryClient: QueryClient
+  container: AppContainer
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: AppIdentity.name },
+    ],
+    links: [
+      { rel: 'stylesheet', href: appCss },
+      { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' },
+    ],
+  }),
+  shellComponent: RootDocument,
+  component: AppShell,
+})
+
+function RootDocument({ children }: { children: ReactNode }) {
+  return (
+    <html lang={defaultLocale} suppressHydrationWarning>
+      <head>
+        {/* Applies the stored appearance before the first paint, so there's no flash of the wrong theme. */}
+        <ScriptOnce children={appearanceScript} />
+        <HeadContent />
+      </head>
+      <body className="bg-background text-on-background antialiased">
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+
+function AppShell() {
+  return (
+    <>
+      <AppearanceEffect />
+      <header className="border-b border-outline">
+        <nav className="mx-auto flex max-w-2xl items-center justify-between px-lg py-md">
+          <Link to="/" className="text-title">
+            {AppIdentity.name}
+          </Link>
+          <Link
+            to="/settings"
+            aria-label={strings.homeOpenSettings}
+            data-testid="home.openSettings"
+            className="rounded-full p-sm text-on-surface-variant hover:bg-surface-variant focus-visible:outline-2 focus-visible:outline-primary"
+          >
+            <AppIcons.settings aria-hidden className="size-6" />
+          </Link>
+        </nav>
+      </header>
+      <main className="mx-auto max-w-2xl px-lg py-xl">
+        <Outlet />
+      </main>
+    </>
+  )
+}

package/template/apps/web/src/routes/index.tsx

@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { HomeScreen } from '#/features/home/HomeScreen'
+
+export const Route = createFileRoute('/')({
+  component: HomeScreen,
+})

package/template/apps/web/src/routes/settings.tsx

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { SettingsScreen } from '#/features/settings/SettingsScreen'
+import { AppIdentity } from '#/generated/app'
+import { strings } from '#/generated/strings'
+
+export const Route = createFileRoute('/settings')({
+  head: () => ({ meta: [{ title: `${strings.settingsTitle} · ${AppIdentity.name}` }] }),
+  component: SettingsScreen,
+})

package/template/apps/web/src/styles.css

@@ -0,0 +1,9 @@
+@import 'tailwindcss';
+@import './generated/tokens.css';
+
+/* `dark:` utilities follow the "dark" class on <html>, which AppearanceEffect sets. */
+@custom-variant dark (&:where(.dark, .dark *));
+
+html {
+  font-family: var(--font-sans);
+}

package/template/apps/web/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", ".output"],
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "paths": {
+      "#/*": ["./src/*"]
+    },
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

package/template/apps/web/tsr.config.json

@@ -0,0 +1,3 @@
+{
+  "target": "react"
+}

package/template/apps/web/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+import tailwindcss from '@tailwindcss/vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+
+export default defineConfig({
+  resolve: { tsconfigPaths: true },
+  plugins: [tailwindcss(), tanstackStart(), viteReact()],
+})

package/template/apps/web/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+// Unit tests run in Node without the TanStack Start plugin.
+export default defineConfig({
+  resolve: { tsconfigPaths: true },
+  test: {
+    include: ['src/**/*.test.{ts,tsx}'],
+  },
+})

package/template/contracts/app.json

@@ -0,0 +1,7 @@
+{
+  "name": "GeekNative",
+  "id": "com.example.geeknative",
+  "version": "1.0.0",
+  "build": 1,
+  "defaultLocale": "en"
+}

package/template/contracts/icons.json

@@ -0,0 +1,5 @@
+{
+  "back": { "ios": "chevron.backward", "android": "Icons.AutoMirrored.Filled.ArrowBack", "web": "ArrowLeft" },
+  "home": { "ios": "house", "android": "Icons.Filled.Home", "web": "House" },
+  "settings": { "ios": "gearshape", "android": "Icons.Filled.Settings", "web": "Settings" }
+}

package/template/contracts/strings/en.json

@@ -0,0 +1,13 @@
+{
+  "common.back": "Back",
+  "home.openSettings": "Settings",
+  "home.welcomeTitle": "You're all set",
+  "home.welcomeBody": "This app is built natively for iOS, Android and the web from one shared spec. Describe what you want to build to your coding agent, and it will build it for all three.",
+  "settings.title": "Settings",
+  "settings.appearance.title": "Appearance",
+  "settings.appearance.system": "System",
+  "settings.appearance.light": "Light",
+  "settings.appearance.dark": "Dark",
+  "settings.about.title": "About",
+  "settings.about.version": "Version {version} ({build:int})"
+}

package/template/contracts/tokens.json

@@ -0,0 +1,40 @@
+{
+  "color": {
+    "background": { "light": "#FFFFFF", "dark": "#0B0D12" },
+    "onBackground": { "light": "#0F172A", "dark": "#E6E8EE" },
+    "surface": { "light": "#F4F5F8", "dark": "#161A23" },
+    "onSurface": { "light": "#0F172A", "dark": "#E6E8EE" },
+    "surfaceVariant": { "light": "#E9EBF1", "dark": "#222735" },
+    "onSurfaceVariant": { "light": "#566074", "dark": "#A3ABBD" },
+    "primary": { "light": "#4F46E5", "dark": "#A5B4FC" },
+    "onPrimary": { "light": "#FFFFFF", "dark": "#1E1B4B" },
+    "outline": { "light": "#D8DCE5", "dark": "#2D3343" },
+    "error": { "light": "#DC2626", "dark": "#F87171" },
+    "onError": { "light": "#FFFFFF", "dark": "#450A0A" }
+  },
+  "spacing": {
+    "xs": 4,
+    "sm": 8,
+    "md": 12,
+    "lg": 16,
+    "xl": 24,
+    "xxl": 32
+  },
+  "radius": {
+    "sm": 6,
+    "md": 10,
+    "lg": 16,
+    "full": 9999
+  },
+  "typography": {
+    "display": { "size": 34, "lineHeight": 41, "weight": 700, "ios": "largeTitle", "android": "displaySmall" },
+    "headline": { "size": 28, "lineHeight": 34, "weight": 700, "ios": "title", "android": "headlineMedium" },
+    "title": { "size": 20, "lineHeight": 26, "weight": 600, "ios": "title3", "android": "titleLarge" },
+    "body": { "size": 16, "lineHeight": 24, "weight": 400, "ios": "body", "android": "bodyLarge" },
+    "label": { "size": 14, "lineHeight": 20, "weight": 500, "ios": "subheadline", "android": "labelLarge" },
+    "caption": { "size": 12, "lineHeight": 16, "weight": 400, "ios": "caption", "android": "bodySmall" }
+  },
+  "font": {
+    "family": "system"
+  }
+}

package/template/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "geeknative-app",
+  "private": true,
+  "workspaces": [
+    "apps/web"
+  ],
+  "scripts": {
+    "gen": "geeknative gen",
+    "check": "geeknative check",
+    "doctor": "geeknative doctor",
+    "parity": "geeknative parity",
+    "dev": "npm run dev --workspace apps/web"
+  },
+  "devDependencies": {
+    "geeknative": "file:../packages/geeknative"
+  }
+}

package/template/spec/decisions.md

@@ -0,0 +1,10 @@
+# Decisions
+
+A dated log of product and technical decisions, and of assumptions made along the way. Newest first.
+
+## 2026-10-10: Starter app
+
+- The starter app has two screens, Home and Settings, implemented the same way on all three platforms as a reference for new features.
+- The appearance setting is stored locally under `settings.appearance` as `system`, `light` or `dark`, on every platform.
+- There's no backend yet. Each feature reads and writes through a repository interface with a local implementation.
+- Dependencies are wired by hand in an `AppContainer` on every platform, with no DI framework.

package/template/spec/features/home.md

@@ -0,0 +1,39 @@
+---
+id: home
+title: Home
+status:
+  ios: done
+  android: done
+  web: done
+---
+
+# Home
+
+## Summary
+
+The first screen. It names the app, welcomes the user and leads to Settings. It's a starting point: replace its content as the product takes shape.
+
+## Screens and states
+
+**Home**
+
+- Title: the app name, from contracts/app.json.
+- A welcome card with `home.welcomeTitle` and `home.welcomeBody`.
+- An entry point to Settings, labeled `home.openSettings`.
+- Static content, so there are no loading, empty or error states.
+
+## Acceptance criteria
+
+- AC-home-1: Home shows the app name as its title.
+- AC-home-2: Home shows the welcome card's title and text.
+- AC-home-3: Home has an entry point that opens Settings.
+
+## Platform notes
+
+- iOS: large navigation title; the Settings entry is a gear button in the toolbar.
+- Android: top app bar with the app name; the Settings entry is a gear action in the app bar.
+- Web: the page heading is the app name; Settings is a gear link in the site header, on every page.
+
+## Test IDs
+
+- `home.openSettings`: the Settings entry point.

package/template/spec/features/settings.md

@@ -0,0 +1,50 @@
+---
+id: settings
+title: Settings
+status:
+  ios: done
+  android: done
+  web: done
+---
+
+# Settings
+
+## Summary
+
+Lets the user choose the app's appearance and see which version they're running.
+
+## Screens and states
+
+**Settings**, opened from Home.
+
+- Section `settings.appearance.title` with three choices: System, Light and Dark. The current choice is selected.
+- Section `settings.about.title` showing `settings.about.version` with the app version and build number.
+
+## Behavior and rules
+
+- The appearance applies to the whole app as soon as it's chosen. There's no save button.
+- System follows the device's light or dark setting, including changes while the app is open.
+- The choice is stored locally under the key `settings.appearance`, as `system`, `light` or `dark`. The key and values are the same on every platform.
+- A missing or unknown stored value counts as `system`.
+
+## Acceptance criteria
+
+- AC-settings-1: Appearance defaults to System.
+- AC-settings-2: Choosing an appearance applies it to the whole app immediately.
+- AC-settings-3: The chosen appearance is still applied after the app restarts.
+- AC-settings-4: Settings shows the app version and build number.
+
+## Platform notes
+
+- iOS: a `Form`, with the appearance as an inline `Picker` (checkmarks).
+- Android: radio buttons in a selectable group; the top app bar has a back button.
+- Web: a radio group in a card. The stored appearance is applied before the first paint, so there's no flash of the wrong theme.
+
+## Test IDs
+
+- `settings.appearance`: the appearance choices.
+- `settings.version`: the version text.
+
+## Assumptions
+
+- No "reset to defaults" action yet.

package/template/spec/navigation.md

@@ -0,0 +1,16 @@
+# Navigation
+
+The app's screens, their route names, and how each platform presents them. Route names are the same in every app: `Route.settings` on iOS, `Route.Settings` on Android and `/settings` on web.
+
+| Screen | Route | Web path | Reached from |
+|---|---|---|---|
+| Home | `home` | `/` | App start |
+| Settings | `settings` | `/settings` | Home's Settings entry |
+
+## Per platform
+
+- **iOS:** one `NavigationStack` rooted at Home. Screens are pushed by appending a `Route` (apps/ios/App/Core/Navigation/Route.swift).
+- **Android:** one Navigation 3 back stack starting at `Route.Home`. Screens are pushed with `backStack.add(...)` (apps/android/.../core/navigation).
+- **Web:** TanStack Router file routes in apps/web/src/routes. Every screen has a URL.
+
+When you add a screen, add a row here. Use the web path as the mobile deep link path when deep links are added.