@octane-xplat/cli 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,35 @@
+# @octane-xplat/cli
+
+> `xplat` — the dev/build toolchain for Octane xplat apps (one Octane
+> codebase → web + iOS + Android).
+>
+> Status: `0.x` — the API surface is still moving. iOS/Android targets need
+> the NativeScript toolchain (Xcode/JDK + `ns`).
+
+```sh
+pnpm add -D @octane-xplat/cli
+```
+
+```sh
+pnpm xplat dev          # pick targets (web, ios, android) or --targets web,ios
+pnpm xplat build        # production builds
+pnpm xplat doctor       # environment check
+pnpm xplat typecheck    # web + native tsconfigs
+```
+
+The scaffolded app's `pnpm dev` / `pnpm build` / `pnpm dev:ios` scripts drive
+the same pieces directly; `xplat` is the multi-target front end.
+
+Also exports the native vite preset — it absorbs the app-owned native config
+(renderer rules, octane→universal alias, `.ios`/`.android` extension chain,
+HMR watchdog, `px→dip` rewrite):
+
+```ts
+// vite.config.native.mts
+import { defineConfig } from 'vite'
+import { xplatNative } from '@octane-xplat/cli/vite'
+
+export default defineConfig(({ mode }) => xplatNative(mode))
+```
+
+Docs: [Running and checking an app](https://octane-xplat.goddardai.org/toolchain)

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@octane-xplat/cli",
-  "version": "0.3.0",
-  "type": "module",
+  "version": "0.4.0",
   "description": "xplat — dev/build/doctor for octane-xplat apps (web + iOS + Android from one codebase)",
   "bin": {
     "xplat": "./src/cli.mjs"
@@ -9,11 +8,18 @@
   "files": [
     "src"
   ],
-  "dependencies": {
-    "@alloc/cmd-ts": "0.17.1",
-    "@clack/prompts": "1.8.1"
+  "type": "module",
+  "exports": {
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "default": "./src/vite.mjs"
+    }
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@alloc/cmd-ts": "0.17.1",
+    "@clack/prompts": "1.8.1"
   }
 }

package/src/cli.mjs

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { binary, subcommands, run } from '@alloc/cmd-ts';
-import { dev } from './commands/dev.mjs';
-import { build } from './commands/build.mjs';
-import { typecheck } from './commands/typecheck.mjs';
-import { doctor } from './commands/doctor.mjs';
-import { clean } from './commands/clean.mjs';
+import { binary, subcommands, run } from '@alloc/cmd-ts'
+import { dev } from './commands/dev.mjs'
+import { build } from './commands/build.mjs'
+import { typecheck } from './commands/typecheck.mjs'
+import { doctor } from './commands/doctor.mjs'
+import { clean } from './commands/clean.mjs'
+import { routes } from './commands/routes.mjs'
 
 const cli = subcommands({
 	name: 'xplat',
 	description: 'One Octane codebase → web + iOS + Android',
-	cmds: { dev, build, typecheck, doctor, clean },
-});
+	cmds: { dev, build, typecheck, doctor, clean, routes },
+})
 
-await run(binary(cli), process.argv);
+await run(binary(cli), process.argv)

package/src/commands/build.mjs

@@ -1,13 +1,19 @@
-import { command, flag, option, optional, string } from '@alloc/cmd-ts';
-import * as p from '@clack/prompts';
-import { buildTargets } from '../targets.mjs';
-import { runTagged } from '../procs.mjs';
+import { command, flag, option, optional, string } from '@alloc/cmd-ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import * as p from '@clack/prompts'
+import { buildTargets } from '../targets.mjs'
+import { runTagged } from '../procs.mjs'
+import { generateRoutes } from './routes.mjs'
 
 export const build = command({
 	name: 'build',
 	description: 'Build for web, iOS, Android',
 	args: {
-		release: flag({ long: 'release', description: 'Native release builds (signed where configured)' }),
+		release: flag({
+			long: 'release',
+			description: 'Native release builds (signed where configured)',
+		}),
 		targets: option({
 			long: 'targets',
 			short: 't',
@@ -16,42 +22,58 @@ export const build = command({
 		}),
 	},
 	handler: async (args) => {
-		const cwd = process.cwd();
-		const all = buildTargets(cwd);
+		const cwd = process.cwd()
+		const all = buildTargets(cwd)
 		if (all.length === 0) {
-			p.log.error('Nothing to build — no vite.config.ts or nativescript.config.ts found.');
-			process.exit(1);
+			p.log.error('Nothing to build — no vite.config.ts or nativescript.config.ts found.')
+			process.exit(1)
 		}
 
-		let chosen;
+		let chosen
 		if (args.targets) {
-			const kinds = args.targets.split(',').map((s) => s.trim());
-			chosen = all.filter((t) => kinds.includes(t.kind));
+			const kinds = args.targets.split(',').map((s) => s.trim())
+			chosen = all.filter((t) => kinds.includes(t.kind))
 		} else if (!process.stdout.isTTY) {
-			chosen = all;
+			chosen = all
 		} else {
-			p.intro('xplat build');
+			p.intro('xplat build')
 			const picked = await p.multiselect({
 				message: 'Build targets',
 				options: all.map((t) => ({ value: t.id, label: t.name })),
 				initialValues: all.map((t) => t.id),
 				required: true,
-			});
-			if (p.isCancel(picked)) { p.cancel('Cancelled'); process.exit(0); }
-			chosen = all.filter((t) => picked.includes(t.id));
+			})
+
+			if (p.isCancel(picked)) {
+				p.cancel('Cancelled')
+				process.exit(0)
+			}
+
+			chosen = all.filter((t) => picked.includes(t.id))
+		}
+
+		// Route codegen is automatic when a route dir exists — the generated
+		// manifest is committed like a lockfile; a stale one is a silent bug.
+		const routeDir = ['app', 'src/app'].find((d) => existsSync(join(cwd, d)))
+		if (routeDir) {
+			const n = generateRoutes(cwd, routeDir)
+			p.log.info(`routes.gen regenerated — ${n} route${n === 1 ? '' : 's'}`)
 		}
 
 		for (const t of chosen) {
-			const argv = t.kind === 'web'
-				? ['exec', 'vite', 'build']
-				: ['exec', 'ns', 'build', t.kind, ...(args.release ? ['--release'] : [])];
+			const argv =
+				t.kind === 'web'
+					? ['exec', 'vite', 'build']
+					: ['exec', 'ns', 'build', t.kind, ...(args.release ? ['--release'] : [])]
+
 			try {
-				await runTagged(t.kind, 'pnpm', argv, cwd);
+				await runTagged(t.kind, 'pnpm', argv, cwd)
 			} catch (e) {
-				p.log.error(String(e));
-				process.exit(1);
+				p.log.error(String(e))
+				process.exit(1)
 			}
 		}
-		p.log.success('Build complete');
+
+		p.log.success('Build complete')
 	},
-});
+})

package/src/commands/clean.mjs

@@ -1,23 +1,33 @@
-import { command } from '@alloc/cmd-ts';
-import { existsSync, rmSync } from 'node:fs';
-import * as p from '@clack/prompts';
+import { command } from '@alloc/cmd-ts'
+import { existsSync, rmSync } from 'node:fs'
+import * as p from '@clack/prompts'
 
-const DIRS = ['dist', 'platforms', '.ns-vite-build', 'node_modules/.vite'];
+const DIRS = ['dist', 'platforms', '.ns-vite-build', 'node_modules/.vite']
 
 export const clean = command({
 	name: 'clean',
 	description: 'Remove build outputs (dist, platforms, vite caches)',
 	args: {},
 	handler: async () => {
-		const cwd = process.cwd();
-		const found = DIRS.filter((d) => existsSync(`${cwd}/${d}`));
-		if (found.length === 0) { p.log.info('Nothing to clean'); return; }
+		const cwd = process.cwd()
+		const found = DIRS.filter((d) => existsSync(`${cwd}/${d}`))
+		if (found.length === 0) {
+			p.log.info('Nothing to clean')
+			return
+		}
 
 		if (process.stdout.isTTY) {
-			const ok = await p.confirm({ message: `Remove ${found.join(', ')}?` });
-			if (p.isCancel(ok) || !ok) { p.cancel('Cancelled'); return; }
+			const ok = await p.confirm({ message: `Remove ${found.join(', ')}?` })
+			if (p.isCancel(ok) || !ok) {
+				p.cancel('Cancelled')
+				return
+			}
+		}
+
+		for (const d of found) {
+			rmSync(`${cwd}/${d}`, { recursive: true, force: true })
 		}
-		for (const d of found) rmSync(`${cwd}/${d}`, { recursive: true, force: true });
-		p.log.success(`Cleaned ${found.join(', ')}`);
+
+		p.log.success(`Cleaned ${found.join(', ')}`)
 	},
-});
+})

package/src/commands/dev.mjs

@@ -1,12 +1,15 @@
-import { command, option, optional, string } from '@alloc/cmd-ts';
-import * as p from '@clack/prompts';
-import { discoverTargets } from '../targets.mjs';
-import { spawnTagged } from '../procs.mjs';
+import { command, option, optional, string } from '@alloc/cmd-ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import * as p from '@clack/prompts'
+import { discoverTargets } from '../targets.mjs'
+import { spawnTagged } from '../procs.mjs'
+import { generateRoutes } from './routes.mjs'
 
 const spawnFor = (t, cwd) =>
 	t.kind === 'web'
 		? spawnTagged('web', 'pnpm', ['exec', 'vite'], cwd)
-		: spawnTagged(t.kind, 'pnpm', ['exec', 'ns', 'run', t.kind, '--device', t.device], cwd);
+		: spawnTagged(t.kind, 'pnpm', ['exec', 'ns', 'run', t.kind, '--device', t.device], cwd)
 
 export const dev = command({
 	name: 'dev',
@@ -20,36 +23,58 @@ export const dev = command({
 		}),
 	},
 	handler: async (args) => {
-		const cwd = process.cwd();
-		const all = discoverTargets(cwd);
+		const cwd = process.cwd()
+		const all = discoverTargets(cwd)
 		if (all.length === 0) {
-			p.log.error('No targets found — need vite.config.ts (web) or nativescript.config.ts (native).');
-			process.exit(1);
+			p.log.error(
+				'No targets found — need vite.config.ts (web) or nativescript.config.ts (native).',
+			)
+
+			process.exit(1)
 		}
 
-		let chosen;
+		let chosen
 		if (args.targets) {
-			const kinds = args.targets.split(',').map((s) => s.trim());
-			chosen = all.filter((t) => kinds.includes(t.kind));
+			const kinds = args.targets.split(',').map((s) => s.trim())
+			chosen = all.filter((t) => kinds.includes(t.kind))
 			if (chosen.length === 0) {
-				p.log.error(`No targets matched "${args.targets}". Available: ${all.map((t) => t.kind).join(', ')}`);
-				process.exit(1);
+				p.log.error(
+					`No targets matched "${args.targets}". Available: ${all.map((t) => t.kind).join(', ')}`,
+				)
+
+				process.exit(1)
 			}
 		} else if (!process.stdout.isTTY) {
-			chosen = all; // non-interactive: everything detected
+			chosen = all // non-interactive: everything detected
 		} else {
-			p.intro('xplat dev');
+			p.intro('xplat dev')
 			const picked = await p.multiselect({
 				message: 'Dev targets',
 				options: all.map((t) => ({ value: t.id, label: t.name })),
 				initialValues: all.map((t) => t.id),
 				required: true,
-			});
-			if (p.isCancel(picked)) { p.cancel('Cancelled'); process.exit(0); }
-			chosen = all.filter((t) => picked.includes(t.id));
+			})
+
+			if (p.isCancel(picked)) {
+				p.cancel('Cancelled')
+				process.exit(0)
+			}
+
+			chosen = all.filter((t) => picked.includes(t.id))
+		}
+
+		// Route codegen is automatic when a route dir exists — the generated
+		// manifest is committed like a lockfile; a stale one is a silent bug.
+		const routeDir = ['app', 'src/app'].find((d) => existsSync(join(cwd, d)))
+		if (routeDir) {
+			const n = generateRoutes(cwd, routeDir)
+			p.log.info(`routes.gen regenerated — ${n} route${n === 1 ? '' : 's'}`)
+		}
+
+		for (const t of chosen) {
+			spawnFor(t, cwd)
 		}
 
-		for (const t of chosen) spawnFor(t, cwd);
-		p.log.success(`${chosen.length} target(s) running — Ctrl+C stops all`);
+		p.log.success(`${chosen.length} target(s) running — Ctrl+C stops all`)
 	},
-});
+})

package/src/commands/doctor.mjs

@@ -1,14 +1,23 @@
-import { command } from '@alloc/cmd-ts';
-import { execFileSync } from 'node:child_process';
-import * as p from '@clack/prompts';
+import { command } from '@alloc/cmd-ts'
+import { execFileSync } from 'node:child_process'
+import * as p from '@clack/prompts'
 
 const check = (cmd, args) => {
 	try {
-		return { ok: true, out: execFileSync(cmd, args, { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe'] }).trim().split('\n')[0] };
+		return {
+			ok: true,
+			out: execFileSync(cmd, args, {
+				encoding: 'utf8',
+				timeout: 15000,
+				stdio: ['ignore', 'pipe', 'pipe'],
+			})
+				.trim()
+				.split('\n')[0],
+		}
 	} catch {
-		return { ok: false, out: '' };
+		return { ok: false, out: '' }
 	}
-};
+}
 
 /** env checks — the things that have actually bitten this stack. */
 export const doctor = command({
@@ -16,33 +25,72 @@ export const doctor = command({
 	description: 'Check the toolchain for web + native builds',
 	args: {},
 	handler: async () => {
-		p.intro('xplat doctor');
-		const rows = [];
-		const row = (name, ok, detail, hint) => rows.push({ name, ok, detail, hint });
-
-		row('node', check('node', ['--version']).ok, check('node', ['--version']).out);
-		row('pnpm', check('pnpm', ['--version']).ok, check('pnpm', ['--version']).out);
-		row('ns CLI', check('pnpm', ['exec', 'ns', '--version']).ok, check('pnpm', ['exec', 'ns', '--version']).out,
-			'add the nativescript devDep (the starter ships it)');
-		row('xcodebuild', check('xcodebuild', ['-version']).ok, check('xcodebuild', ['-version']).out,
-			'iOS needs Xcode — App Store install + xcode-select');
-		row('xcodeproj gem', check('ruby', ['-e', 'require "xcodeproj"']).ok, '',
-			'gem install --user-install xcodeproj');
-		const sims = check('xcrun', ['simctl', 'list', 'devices', 'booted']);
-		row('iOS simulator', sims.ok, sims.out || 'none booted');
-		const adb = check('adb', ['devices']);
-		const devices = adb.ok ? adb.out.split('\n').slice(1).filter((l) => l.includes('\tdevice')).length : 0;
-		row('adb', adb.ok, `${devices} device(s)`, 'Android SDK platform-tools on PATH');
-		row('ANDROID_HOME', !!process.env.ANDROID_HOME, process.env.ANDROID_HOME || 'unset',
-			'export ANDROID_HOME=$HOME/Library/Android/sdk');
-		row('JAVA_HOME', !!process.env.JAVA_HOME, process.env.JAVA_HOME || 'unset',
-			'JDK 17 (JDK 25 breaks the Android toolchain)');
-
-		let bad = 0;
+		p.intro('xplat doctor')
+		const rows = []
+		const row = (name, ok, detail, hint) => rows.push({ name, ok, detail, hint })
+
+		row('node', check('node', ['--version']).ok, check('node', ['--version']).out)
+		row('pnpm', check('pnpm', ['--version']).ok, check('pnpm', ['--version']).out)
+		row(
+			'ns CLI',
+			check('pnpm', ['exec', 'ns', '--version']).ok,
+			check('pnpm', ['exec', 'ns', '--version']).out,
+			'add the nativescript devDep (the starter ships it)',
+		)
+
+		row(
+			'xcodebuild',
+			check('xcodebuild', ['-version']).ok,
+			check('xcodebuild', ['-version']).out,
+			'iOS needs Xcode — App Store install + xcode-select',
+		)
+
+		row(
+			'xcodeproj gem',
+			check('ruby', ['-e', 'require "xcodeproj"']).ok,
+			'',
+			'gem install --user-install xcodeproj',
+		)
+
+		const sims = check('xcrun', ['simctl', 'list', 'devices', 'booted'])
+		row('iOS simulator', sims.ok, sims.out || 'none booted')
+		const adb = check('adb', ['devices'])
+		const devices = adb.ok
+			? adb.out
+					.split('\n')
+					.slice(1)
+					.filter((l) => l.includes('\tdevice')).length
+			: 0
+
+		row('adb', adb.ok, `${devices} device(s)`, 'Android SDK platform-tools on PATH')
+		row(
+			'ANDROID_HOME',
+			!!process.env.ANDROID_HOME,
+			process.env.ANDROID_HOME || 'unset',
+			'export ANDROID_HOME=$HOME/Library/Android/sdk',
+		)
+
+		row(
+			'JAVA_HOME',
+			!!process.env.JAVA_HOME,
+			process.env.JAVA_HOME || 'unset',
+			'JDK 17 (JDK 25 breaks the Android toolchain)',
+		)
+
+		let bad = 0
 		for (const r of rows) {
-			if (r.ok) p.log.success(`${r.name} — ${r.detail || 'ok'}`);
-			else { bad++; p.log.warn(`${r.name} — missing${r.hint ? ` (${r.hint})` : ''}`); }
+			if (r.ok) {
+				p.log.success(`${r.name} — ${r.detail || 'ok'}`)
+			} else {
+				bad++
+				p.log.warn(`${r.name} — missing${r.hint ? ` (${r.hint})` : ''}`)
+			}
 		}
-		p.outro(bad === 0 ? 'All checks pass' : `${bad} missing — web still works, native targets need the above`);
+
+		p.outro(
+			bad === 0
+				? 'All checks pass'
+				: `${bad} missing — web still works, native targets need the above`,
+		)
 	},
-});
+})

package/src/commands/routes.mjs

@@ -0,0 +1,203 @@
+import { command, option, optional, string } from '@alloc/cmd-ts'
+import { existsSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import * as p from '@clack/prompts'
+
+// Mirror of packages/ui/src/route-table.ts conventions — the CLI walks the
+// route dir off disk (no vite glob), so the derivation is re-implemented
+// here. Keep the two in sync: same suffix strip order, same index/_layout
+// rules. All platform variants count — the union is cross-platform.
+const EXT = /\.(tsrx|tsx|ts|mts|cts|js|mjs|cjs|jsx)$/
+const SUFFIX = /\.(web|native|ios|android)$/
+const PARAM = /^\[(.+)\]$/
+const PRESENT = /\+(modal|fade|push)$/
+
+function walk(dir, out = []) {
+	for (const name of readdirSync(dir).sort()) {
+		const full = join(dir, name)
+		if (statSync(full).isDirectory()) {
+			walk(full, out)
+		} else if (EXT.test(name)) {
+			out.push(full)
+		}
+	}
+
+	return out
+}
+
+function routeFor(rel) {
+	rel = rel.split(sep).join('/').replace(EXT, '')
+	const parts = rel.split('/')
+	let base = parts[parts.length - 1]
+	const sm = SUFFIX.exec(base)
+	if (sm) {
+		base = base.slice(0, base.length - sm[0].length)
+	}
+
+	const pm = PRESENT.exec(base)
+	const presentation = pm ? pm[1] : undefined
+	if (pm) {
+		base = base.slice(0, base.length - pm[0].length)
+	}
+
+	if (base === '_layout') {
+		return null
+	}
+
+	const segs = parts.slice(0, -1).concat(base)
+	if (segs[segs.length - 1] === 'index') {
+		segs.pop()
+	}
+
+	const segments = segs.map((s) => {
+		const m = PARAM.exec(s)
+		return m ? ':' + m[1] : s
+	})
+
+	return {
+		name: segments.join('/') || 'index',
+		params: segments.filter((s) => s.startsWith(':')).map((s) => s.slice(1)),
+		presentation,
+	}
+}
+
+/** Generates routes.gen.types.ts + platform manifest glue for a route dir.
+ *  Returns true when a dir was found and files written; false when no route
+ *  dir exists (callers that run this implicitly — dev/build — stay quiet). */
+export function generateRoutes(cwd, dir, out) {
+	if (!dir) {
+		return false
+	}
+
+	// `out` is the module basename — three files are emitted:
+	//   <out>.types.ts    shared types (RouteName/Params/Presentations)
+	//   <out>.web.ts      web glob + registerRoutes
+	//   <out>.native.ts   native glob + registerRoutes (Device.os prefer)
+	// Importing '<out>' resolves the platform leaf automatically.
+	const base = (out ?? join(dir, '..', 'routes.gen')).replace(/\.ts$/, '')
+
+	// name → {params, presentation}; platform variants of one route
+	// collapse to a single entry (union across platforms).
+	const seen = new Map()
+	for (const file of walk(join(cwd, dir))) {
+		const r = routeFor(relative(join(cwd, dir), file))
+		if (!r) {
+			continue
+		}
+
+		if (!seen.has(r.name)) {
+			seen.set(r.name, r)
+		}
+	}
+
+	const list = [...seen.values()].sort((a, b) => a.name.localeCompare(b.name))
+
+	const union = list.length ? list.map((r) => `\n\t| '${r.name}'`).join('') : 'never'
+
+	const params = list
+		.map((r) => `\t'${r.name}': { ${r.params.map((k) => `${k}: string`).join('; ')} }`)
+
+	const presents = list
+		.filter((r) => r.presentation)
+		.map((r) => `\t'${r.name}': '${r.presentation}'`)
+
+	const src = `// Generated by \`xplat routes\` — do not edit. Re-run after
+// touching the route dir (add/remove/rename route files).
+export type RouteName =${union}
+
+export interface RouteParams {
+${params.length ? params.join('\n') : '\t// no param routes'}
+}
+
+export interface RoutePresentations {
+${presents.length ? presents.join('\n') : '\t// no +modal/+fade routes'}
+}
+`
+
+	writeFileSync(join(cwd, base + '.types.ts'), src)
+
+	// Platform-suffixed twins carry the actual manifest derivation +
+	// registration — routes.gen.web.ts / routes.gen.native.ts resolve
+	// through the platform extension chain, so importing './routes.gen'
+	// gets the right glob for the platform with no app-side leaf file.
+	// Types live in '.types.ts' — './routes.gen' inside a .web.ts sibling
+	// would self-resolve.
+	const outDir = join(cwd, base, '..')
+	const rel = relative(outDir, join(cwd, dir)).split(sep).join('/')
+	const globDir = rel.startsWith('.') ? rel : './' + rel
+	const baseName = base.split('/').pop()
+	const typesRef = `export type { RouteName, RouteParams, RoutePresentations } from './${baseName}.types'`
+
+	const shared = (prelude, globs, prefer) => `// Generated by \`xplat routes\` — do not edit.
+${prelude}import { deriveRouteManifest, registerRoutes } from '@octane-xplat/ui'
+${typesRef}
+
+const files = import.meta.glob(
+	[
+		'${globDir}/**/*.{tsrx,tsx}',
+${globs}
+	],
+	{ eager: true },
+)
+
+export const routes = deriveRouteManifest(files, ${prefer})
+registerRoutes(routes)
+export const screens = routes.screens
+`
+
+	writeFileSync(
+		join(cwd, base + '.web.ts'),
+		shared(
+			'',
+			[
+				`\t\t'!${globDir}/**/*.native.{tsrx,tsx}'`,
+				`\t\t'!${globDir}/**/*.ios.{tsrx,tsx}'`,
+				`\t\t'!${globDir}/**/*.android.{tsrx,tsx}'`,
+			].join(',\n'),
+			`['web']`,
+		),
+	)
+
+	writeFileSync(
+		join(cwd, base + '.native.ts'),
+		shared(
+			`import { Device } from '@nativescript/core'\n`,
+			`\t\t'!${globDir}/**/*.web.{tsrx,tsx}'`,
+			`Device.os === 'Android' ? ['android', 'native'] : ['ios', 'native']`,
+		),
+	)
+
+	return list.length
+}
+
+export const routes = command({
+	name: 'routes',
+	description: 'Generate routes.gen.ts (typed RouteName/params) from the route dir',
+	args: {
+		dir: option({
+			long: 'dir',
+			short: 'd',
+			type: optional(string),
+			description: 'Route dir — default: first of ./app, ./src/app',
+		}),
+		out: option({
+			long: 'out',
+			short: 'o',
+			type: optional(string),
+			description: 'Output file — default: <route dir>/../routes.gen.ts',
+		}),
+	},
+	handler: async (args) => {
+		const cwd = process.cwd()
+		const dir = args.dir ?? ['app', 'src/app'].find((d) => existsSync(join(cwd, d)))
+		if (!dir) {
+			p.log.error('No route dir found — expected ./app or ./src/app (or pass --dir).')
+			process.exit(1)
+		}
+
+		const count = generateRoutes(cwd, dir, args.out)
+		p.log.success(
+			`Wrote routes.gen.{types,web,native}.ts — ${count} route${count === 1 ? '' : 's'}`,
+		)
+	},
+})

package/src/commands/typecheck.mjs

@@ -1,23 +1,34 @@
-import { command } from '@alloc/cmd-ts';
-import { existsSync } from 'node:fs';
-import * as p from '@clack/prompts';
-import { runTagged } from '../procs.mjs';
+import { command } from '@alloc/cmd-ts'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import * as p from '@clack/prompts'
+import { runTagged } from '../procs.mjs'
+import { generateRoutes } from './routes.mjs'
 
 export const typecheck = command({
 	name: 'typecheck',
 	description: 'tsrx-tsc --noEmit for every tsconfig present',
 	args: {},
 	handler: async () => {
-		const cwd = process.cwd();
-		const configs = ['tsconfig.json', 'tsconfig.native.json'].filter((f) => existsSync(`${cwd}/${f}`));
+		const cwd = process.cwd()
+		const routeDir = ['app', 'src/app'].find((d) => existsSync(join(cwd, d)))
+		if (routeDir) {
+			generateRoutes(cwd, routeDir)
+		}
+
+		const configs = ['tsconfig.json', 'tsconfig.native.json'].filter((f) =>
+			existsSync(`${cwd}/${f}`),
+		)
+
 		for (const c of configs) {
 			try {
-				await runTagged('tsc', 'pnpm', ['exec', 'tsrx-tsc', '--noEmit', '-p', c], cwd);
+				await runTagged('tsc', 'pnpm', ['exec', 'tsrx-tsc', '--noEmit', '-p', c], cwd)
 			} catch (e) {
-				p.log.error(String(e));
-				process.exit(1);
+				p.log.error(String(e))
+				process.exit(1)
 			}
 		}
-		p.log.success('Typecheck clean');
+
+		p.log.success('Typecheck clean')
 	},
-});
+})

package/src/procs.mjs

@@ -1,33 +1,39 @@
 // Prefixed process plumbing — dev runs several tools side by side, so each
 // gets a short tag on its output lines. SIGINT fans out to every child.
-import { spawn } from 'node:child_process';
+import { spawn } from 'node:child_process'
 
-const children = new Set();
+const children = new Set()
 
 process.on('SIGINT', () => {
-	for (const p of children) p.kill('SIGINT');
-	process.exit(130);
-});
+	for (const p of children) {
+		p.kill('SIGINT')
+	}
+
+	process.exit(130)
+})
 
 /** Spawn long-running, output prefixed `[tag]`. */
 export function spawnTagged(tag, cmd, args, cwd) {
-	const p = spawn(cmd, args, { cwd, env: process.env });
-	children.add(p);
+	const p = spawn(cmd, args, { cwd, env: process.env })
+	children.add(p)
 	const prefix = (chunk) => {
 		for (const line of chunk.toString().split('\n')) {
-			if (line.trim()) process.stdout.write(`[${tag}] ${line}\n`);
+			if (line.trim()) {
+				process.stdout.write(`[${tag}] ${line}\n`)
+			}
 		}
-	};
-	p.stdout.on('data', prefix);
-	p.stderr.on('data', prefix);
-	p.on('exit', () => children.delete(p));
-	return p;
+	}
+
+	p.stdout.on('data', prefix)
+	p.stderr.on('data', prefix)
+	p.on('exit', () => children.delete(p))
+	return p
 }
 
 /** Spawn to completion, output prefixed `[tag]`. Resolves on exit 0. */
 export function runTagged(tag, cmd, args, cwd) {
 	return new Promise((resolve, reject) => {
-		const p = spawnTagged(tag, cmd, args, cwd);
-		p.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${tag} exited ${code}`))));
-	});
+		const p = spawnTagged(tag, cmd, args, cwd)
+		p.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`${tag} exited ${code}`))))
+	})
 }

package/src/targets.mjs

@@ -1,78 +1,110 @@
 // Target + device discovery. Everything degrades quietly — a missing
 // toolchain means the target is absent from prompts, not an error.
-import { existsSync } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
 
 const run = (cmd, args) => {
 	try {
-		return execFileSync(cmd, args, { encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'] });
+		return execFileSync(cmd, args, {
+			encoding: 'utf8',
+			timeout: 15000,
+			stdio: ['ignore', 'pipe', 'ignore'],
+		})
 	} catch {
-		return null;
+		return null
 	}
-};
+}
+
+export const hasWeb = (cwd) =>
+	existsSync(`${cwd}/vite.config.ts`) || existsSync(`${cwd}/vite.config.mts`)
 
-export const hasWeb = (cwd) => existsSync(`${cwd}/vite.config.ts`) || existsSync(`${cwd}/vite.config.mts`);
-export const hasNative = (cwd) => existsSync(`${cwd}/nativescript.config.ts`);
+export const hasNative = (cwd) => existsSync(`${cwd}/nativescript.config.ts`)
 
 /** iOS targets: booted sims first, then other available sims, then physical devices. */
 export function iosTargets() {
-	const out = run('xcrun', ['simctl', 'list', 'devices', 'available', '-j']);
-	if (!out) return [];
+	const out = run('xcrun', ['simctl', 'list', 'devices', 'available', '-j'])
+	if (!out) {
+		return []
+	}
+
 	try {
-		const j = JSON.parse(out);
-		const sims = [];
+		const j = JSON.parse(out)
+		const sims = []
 		for (const list of Object.values(j.devices ?? {})) {
 			for (const d of list) {
-				if (!d.isAvailable) continue;
+				if (!d.isAvailable) {
+					continue
+				}
+
 				sims.push({
 					kind: 'ios',
 					id: d.udid,
 					name: d.name + (d.state === 'Booted' ? ' (booted)' : ''),
 					device: d.udid,
 					booted: d.state === 'Booted',
-				});
+				})
 			}
 		}
+
 		// Booted first — that's almost always the one you mean.
-		return sims.sort((a, b) => (b.booted ? 1 : 0) - (a.booted ? 1 : 0));
+		return sims.sort((a, b) => (b.booted ? 1 : 0) - (a.booted ? 1 : 0))
 	} catch {
-		return [];
+		return []
 	}
 }
 
 /** Android targets: emulators + physical devices from adb. */
 export function androidTargets() {
-	const out = run('adb', ['devices']);
-	if (!out) return [];
+	const out = run('adb', ['devices'])
+	if (!out) {
+		return []
+	}
+
 	return out
 		.split('\n')
 		.slice(1)
 		.map((l) => l.trim())
 		.filter((l) => l.endsWith('\tdevice'))
 		.map((l) => {
-			const serial = l.split('\t')[0];
-			const emu = serial.startsWith('emulator-');
-			return { kind: 'android', id: serial, name: emu ? `${serial} (emulator)` : `${serial} (device)`, device: serial };
-		});
+			const serial = l.split('\t')[0]
+			const emu = serial.startsWith('emulator-')
+			return {
+				kind: 'android',
+				id: serial,
+				name: emu ? `${serial} (emulator)` : `${serial} (device)`,
+				device: serial,
+			}
+		})
 }
 
 /** Every launchable target for this project + machine. */
 export function discoverTargets(cwd) {
-	const targets = [];
-	if (hasWeb(cwd)) targets.push({ kind: 'web', id: 'web', name: 'Web (vite :5200)' });
+	const targets = []
+	if (hasWeb(cwd)) {
+		targets.push({ kind: 'web', id: 'web', name: 'Web (vite :5200)' })
+	}
+
 	if (hasNative(cwd)) {
-		targets.push(...iosTargets(), ...androidTargets());
+		targets.push(...iosTargets(), ...androidTargets())
 	}
-	return targets;
+
+	return targets
 }
 
 /** Distinct platform buckets for `build` — one entry per platform, no device picks. */
 export function buildTargets(cwd) {
-	const t = [];
-	if (hasWeb(cwd)) t.push({ kind: 'web', id: 'web', name: 'Web (vite build)' });
+	const t = []
+	if (hasWeb(cwd)) {
+		t.push({ kind: 'web', id: 'web', name: 'Web (vite build)' })
+	}
+
 	if (hasNative(cwd)) {
-		if (iosTargets().length || run('xcrun', ['--version'])) t.push({ kind: 'ios', id: 'ios', name: 'iOS (ns build ios)' });
-		t.push({ kind: 'android', id: 'android', name: 'Android (ns build android)' });
+		if (iosTargets().length || run('xcrun', ['--version'])) {
+			t.push({ kind: 'ios', id: 'ios', name: 'iOS (ns build ios)' })
+		}
+
+		t.push({ kind: 'android', id: 'android', name: 'Android (ns build android)' })
 	}
-	return t;
+
+	return t
 }

package/src/vite.d.ts

@@ -0,0 +1,20 @@
+import type { UserConfig } from 'vite'
+
+export const nativeExtensions: string[]
+
+export interface XplatNativeOptions {
+	/** Extra optimizeDeps.exclude entries — app-shipped @nativescript plugins. */
+	deps?: string[]
+	/** Renderer rules override — defaults cover src/ + linked package source. */
+	rules?: unknown[]
+	/** App-specific config merged in last (plugins, server, …). */
+	extra?: UserConfig
+}
+
+/** Full native (iOS/Android) Vite config — the shared preset. Resolves the
+ *  app's own vite/vite-octane/octane toolchain (async because it loads
+ *  through the app's node_modules). */
+export function xplatNative(
+	env: { mode: string } | string,
+	opts?: XplatNativeOptions,
+): Promise<UserConfig>

package/src/vite.mjs

@@ -0,0 +1,271 @@
+// @octane-xplat/cli/vite — the shared native Vite preset.
+//
+// Everything in here was previously per-app boilerplate (copied between
+// vite.config.native.mts files) or an app-owned workaround: the nativescript
+// renderer rules, the octane→universal/native alias, the platform-suffix
+// extension chain, the deps-bundle plugin exclusions, the HMR watchdog, and
+// the px→dip CSS rewrite. Apps now write:
+//
+//   import { defineConfig } from 'vite'
+//   import { xplatNative } from '@octane-xplat/cli/vite'
+//   export default defineConfig(({ mode }) => xplatNative(mode))
+//
+// The preset calls octaneConfig itself — consumers only merge in
+// app-specific extras via the `extra` option or a vite mergeConfig wrapper.
+
+import { createRequire } from 'node:module'
+import { realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// The toolchain modules (vite, vite-octane, the nativescript renderer)
+// belong to the CONSUMING app, not to this package — under pnpm's isolated
+// linker a bare import here would miss them entirely. createRequire from
+// the app's cwd makes the preset use the app's own pinned versions.
+// realpathSync matters: resolve() returns the symlinked node_modules path
+// and ESM import() does not realpath — loading vite through the symlink
+// leaves its internal 'rolldown' bare-import stranded outside its .pnpm
+// peer dir.
+const req = createRequire(join(process.cwd(), 'package.json'))
+const importApp = (spec) => import(pathToFileURL(realpathSync(req.resolve(spec))).href)
+
+/** CSS that NS parses but silently ignores or misreads — the app looks
+ *  identical in source but diverges at runtime. Warned at build time so the
+ *  divergence is loud instead of invisible. Each entry: pattern + the
+ *  portable alternative. */
+const CSS_DIVERGENCES = [
+	[
+		/margin-(?:left|right|top|bottom)\s*:\s*auto|margin\s*:[^;{}]*\bauto\b/,
+		'auto margins are ignored on native — use justify-content, alignSelf, or a <Spacer/>',
+	],
+	[
+		/position\s*:\s*(fixed|sticky)\b/,
+		'position: fixed/sticky does not exist on native — overlays go through Overlay/Modal services, not positioning',
+	],
+	[/\bz-index\s*:/, 'z-index is inert on native — paint order follows document order'],
+	[/\bfloat\s*:/, 'float is unsupported on native — use flex rows'],
+	[
+		/\bbox-shadow\s*:/,
+		'box-shadow is inert on native — Android elevation and iOS shadows do not map to it (framework mapping is a TODO)',
+	],
+	[
+		/white-space\s*:\s*pre-wrap\b/,
+		'Label rejects white-space:pre-wrap — "wrap" is the native wrap value (no space/newline preservation)',
+	],
+]
+
+/**
+ * Shared stylesheets are authored in web units and web semantics. For the
+ * native bundle this transform (a) rewrites `px` lengths to `dip` — NS CSS
+ * reads `px` as _device_ pixels, not dips (`width:88px` measures 29 dips on
+ * a 3x device); inline `style` props are already dips and untouched — and
+ * (b) warns once per file on declarations NS silently ignores, so the
+ * divergence is loud at build time.
+ */
+function pxToDip() {
+	const warned = new Set()
+	const process = (code, id, warn) => {
+		// Framework authors mark web-only rule blocks — overlays, popovers,
+		// dialog modals render through RootLayout/showModal natively, so
+		// their CSS is dead weight (and would trip the divergence warnings).
+		// Stripped before the warn pass.
+		code = code.replace(
+			/\/\*\s*xplat-web-only:start[\s\S]*?\*\/[\s\S]*?\/\*\s*xplat-web-only:end[\s\S]*?\*\//g,
+			'',
+		)
+
+		for (const [re, hint] of CSS_DIVERGENCES) {
+			const key = id + '|' + hint
+			if (re.test(code) && !warned.has(key)) {
+				warned.add(key)
+				warn(`${id}: ${hint}`)
+			}
+		}
+
+		return code.replace(/(-?\d+(?:\.\d+)?)px\b/g, '$1dip')
+	}
+
+	return {
+		name: 'xplat-native-css',
+		enforce: 'pre',
+		// Per-file pass — covers dev serving where css is transformed
+		// per module (the /ns/m bridge path).
+		transform(code, id) {
+			if (!id.split('?')[0].endsWith('.css')) {
+				return
+			}
+
+			return process(code, id, (m) => this.warn(m))
+		},
+		// Build pass — @nativescript/vite collects emitted .css assets in
+		// generateBundle and serializes them via addTaggedAdditionalCSS;
+		// @import inlining bypasses the transform hook, so the asset text
+		// must be rewritten here. 'pre' ordering lands us before it.
+		generateBundle(_opts, bundle) {
+			for (const file of Object.values(bundle)) {
+				if (file.type === 'asset' && file.fileName.endsWith('.css')) {
+					const src =
+						typeof file.source === 'string' ? file.source : new TextDecoder().decode(file.source)
+
+					file.source = process(src, file.fileName, (m) => this.warn(m))
+				}
+			}
+		},
+	}
+}
+
+/**
+ * On-device HMR needs the app's websocket client to attach to /ns-hmr after
+ * the HTTP boot. When it never does — the websockets polyfill missing from
+ * the bundle, `adb reverse` not covering the vite port, or a boot error
+ * before the client import — every save logs `recipients=0` and the device
+ * silently stays stale. Warn once when a dev session was fetched but no
+ * client ever attached.
+ */
+function nsHmrClientWatchdog() {
+	return {
+		name: 'xplat-ns-hmr-client-watchdog',
+		configureServer(server) {
+			let everConnected = false
+			let timer
+			// Hook the raw 'request' event — middlewares.use() appends after
+			// the ns plugin's session handler, which ends the response without
+			// next(), so a connect middleware never observes /__ns_dev__/session.
+			server.httpServer?.on('request', (req) => {
+				if (!everConnected && req.url?.startsWith('/__ns_dev__/session')) {
+					clearTimeout(timer)
+					timer = setTimeout(() => {
+						if (!everConnected) {
+							console.warn(
+								'[xplat] the app fetched its dev session but no /ns-hmr ' +
+									'websocket client connected — edits will not reach the ' +
+									'device. Check that @valor/nativescript-websockets is ' +
+									'installed, `adb reverse tcp:<port>` covers this vite ' +
+									'port (physical Android), and the device log for ' +
+									'hmr-client errors.',
+							)
+						}
+					}, 15_000)
+				}
+			})
+
+			server.httpServer?.on('upgrade', (req) => {
+				if (req.url?.startsWith('/ns-hmr')) {
+					everConnected = true
+					clearTimeout(timer)
+				}
+			})
+		},
+	}
+}
+
+/** The full extension chain, most-specific first: .ios/.android → .native →
+ *  shared. NS's own file qualifiers (.land, .minWH600…) still apply to
+ *  assets on top of this. */
+export const nativeExtensions = [
+	'.ios.tsrx',
+	'.android.tsrx',
+	'.native.tsrx',
+	'.tsrx',
+	'.ios.tsx',
+	'.android.tsx',
+	'.native.tsx',
+	'.tsx',
+	'.ios.ts',
+	'.android.ts',
+	'.native.ts',
+	'.mjs',
+	'.mts',
+	'.ts',
+	'.jsx',
+	'.js',
+	'.json',
+]
+
+/** Default renderer rules: every component file the native graph can reach —
+ *  src plus linked package source — compiles under the nativescript
+ *  renderer. `.web.*` leaves legitimately use DOM globals; they're
+ *  unreachable from the native entry but must not fail validation, so each
+ *  rule excludes them. */
+const nativeRules = [
+	{
+		include: 'src/**/*.{ts,tsx,tsrx}',
+		exclude: 'src/**/*.web.*',
+		renderer: 'nativescript',
+	},
+	{
+		include: '**/packages/**/*.{ts,tsx,tsrx}',
+		exclude: '**/*.web.*',
+		renderer: 'nativescript',
+	},
+]
+
+/**
+ * Native (iOS/Android) Vite config. `env` is defineConfig's { mode }; `extra`
+ * is merged in last for app-specific additions (own plugins, extra
+ * optimizeDeps, server options).
+ *
+ * opts:
+ *   - deps: extra optimizeDeps.exclude entries (app-shipped NS plugins)
+ *   - rules: renderer rules override (defaults cover src + packages source)
+ */
+export async function xplatNative(env, opts = {}) {
+	const mode = typeof env === 'string' ? env : env.mode
+	const [{ mergeConfig }, { octaneConfig }, { nativeScriptRenderer }] = await Promise.all([
+		importApp('vite'),
+		importApp('@nativescript-community/vite-octane'),
+		importApp('@nativescript-community/octane/config'),
+	])
+
+	return mergeConfig(
+		octaneConfig(
+			{ mode },
+			{
+				octane: {
+					renderers: {
+						// The stock renderer ships validation.forbiddenGlobals/Imports
+						// by default since 0.2.1 (upstream #6).
+						registry: { nativescript: nativeScriptRenderer },
+						rules: opts.rules ?? nativeRules,
+					},
+				},
+			},
+		),
+		{
+			plugins: [pxToDip(), nsHmrClientWatchdog()],
+			optimizeDeps: {
+				// Flattened optimizeDeps chunks get mangled by the /ns/m device
+				// transform (`import import "/ns/core/utils"`) and miss the vendor
+				// manifest — serve @nativescript plugins per-module instead.
+				exclude: [
+					'@nativescript/biometrics',
+					'@nativescript/geolocation',
+					'@nativescript/haptics',
+					'@nativescript/imagepicker',
+					'@nativescript/local-notifications',
+					'@nativescript-community/ui-document-picker',
+					'@nativescript/secure-storage',
+					'@nativescript/social-share',
+					'@nativescript-community/ui-svg',
+					'nativescript-clipboard',
+					...(opts.deps ?? []),
+				],
+			},
+			resolve: {
+				conditions: ['native'],
+				// The compiler retargets hook imports to @nativescript-community/
+				// octane, but the deps-bundle scanner sees source-level 'octane'
+				// first — without this it vendors octane/dist/index.js (the full
+				// DOM runtime). Exact-match only: 'octane/universal/native' itself
+				// must not be rewritten.
+				alias: [{ find: /^octane$/, replacement: 'octane/universal/native' }],
+				// ns-vite sets preserveSymlinks:true; under pnpm's isolated layout
+				// that resolves a dep's imports from the symlink path instead of
+				// its real .pnpm dir, so declared transitive deps can't be found.
+				preserveSymlinks: false,
+				extensions: nativeExtensions,
+			},
+		},
+		opts.extra ?? {},
+	)
+}