create-octane-xplat 0.15.0 → 0.16.0

package/README.md

@@ -16,6 +16,20 @@ With Node.js and pnpm 11.24.0 installed:
 pnpm create octane-xplat my-app
 ```
 
+The starter's `tsconfig.json` selects the shared native JSX types from its
+direct `@octane-xplat/jsx` dependency. Browser JSX leaves select DOM types on
+their first line, as `src/main.web.tsrx` does:
+
+```tsx
+/** @jsxImportSource @octane-xplat/jsx/dom */
+export function BrowserMessage() {
+	return <p>Ready</p>
+}
+```
+
+See [platform files and JSX types](https://octane-xplat.goddardai.org/platform/module-resolution#typescript)
+when adding a native or browser implementation.
+
 ## Start a library package
 
 To start a reusable package instead of an app, select the library template:
@@ -63,6 +77,49 @@ The generated app pins pnpm 11.24.0. Its `pnpm-workspace.yaml` loads
 `@octane-xplat/patches` as a `configDependencies` package, making the
 framework patches available during the first install.
 
+Apps start with the runtime, build packages, and tests their selected platforms
+need. Feature packages are added when you use them.
+
+## Run app tests
+
+New apps include Vitest, configuration, sample tests, and scripts. From your
+app's folder, run the command for a platform you enabled:
+
+```sh
+pnpm test:web            # when web is enabled
+pnpm test:ios -- --device DEVICE_UDID  # when iOS is enabled
+pnpm test:android -- --device DEVICE_SERIAL  # when Android is enabled
+```
+
+Web tests use jsdom, which simulates a browser's
+document on your computer; phone tests use NativeScript's test runner on a
+selected simulator or device. The runners are explicit development dependencies
+with framework-managed versions in `catalog:xplat`. Adapt the sample tests to
+your app as you replace the starter screen.
+
+Platforms added later also receive their test setup. The library template
+includes its component tests and publishing checks.
+See [checking an app](../../docs/verify/testing.md#add-automated-tests) for the
+commands, file conventions, and checks that still need a browser or phone.
+
+## Keep compatible versions
+
+App and library starters share the framework's compatible compiler, runtime,
+and tool versions through `catalog:xplat`. To update an existing project,
+preview and apply a published CLI release's set, then check the installed
+packages:
+
+```sh
+pnpm dlx @octane-xplat/cli@latest upgrade --check
+pnpm dlx @octane-xplat/cli@latest upgrade
+pnpm xplat doctor
+```
+
+An upgrade covers the workspace's managed dependencies and patches. Your
+app-specific packages and library consumer peer ranges remain yours. See
+[compatible versions](../cli/README.md#compatible-versions) for local links,
+custom patches, deferred installs, and failure recovery.
+
 Leave the server running while you edit. After stopping it, restart from the
 app directory:
 

package/compatibility.json

@@ -0,0 +1,199 @@
+{
+	"$comment": "Release compatibility set, shared by create-octane-xplat and xplat doctor/upgrade. Edit external pins here, then run pnpm sync:compatibility. Framework package names are generated from the lockstep release set. Optional packages are managed only when declared; library consumer peer ranges remain app-owned.",
+	"schemaVersion": 1,
+	"frameworkVersion": "0.16.0",
+	"tools": {
+		"nodeMinimum": "22.18.0",
+		"pnpm": "11.24.0"
+	},
+	"frameworkPackages": [
+		"@octane-xplat/audio",
+		"@octane-xplat/auth",
+		"@octane-xplat/bamboo",
+		"@octane-xplat/biometrics",
+		"@octane-xplat/camera",
+		"@octane-xplat/canvas",
+		"@octane-xplat/charts",
+		"@octane-xplat/cli",
+		"@octane-xplat/context-menu",
+		"@octane-xplat/date-picker",
+		"@octane-xplat/desktop-webview",
+		"@octane-xplat/dnd-kit",
+		"@octane-xplat/effects",
+		"@octane-xplat/files",
+		"@octane-xplat/geolocation",
+		"@octane-xplat/gif",
+		"@octane-xplat/haptics",
+		"@octane-xplat/icons",
+		"@octane-xplat/image",
+		"@octane-xplat/image-crop",
+		"@octane-xplat/intersection-observer",
+		"@octane-xplat/jsx",
+		"@octane-xplat/lexical",
+		"@octane-xplat/lib",
+		"@octane-xplat/lingui",
+		"@octane-xplat/lint",
+		"@octane-xplat/lottie",
+		"@octane-xplat/macos-renderer",
+		"@octane-xplat/mcp",
+		"@octane-xplat/media",
+		"@octane-xplat/motion",
+		"@octane-xplat/nano-icons",
+		"@octane-xplat/notifications",
+		"@octane-xplat/pager",
+		"@octane-xplat/patches",
+		"@octane-xplat/picker",
+		"@octane-xplat/platform",
+		"@octane-xplat/push",
+		"@octane-xplat/recorder",
+		"@octane-xplat/richtext",
+		"@octane-xplat/rolling-text",
+		"@octane-xplat/secure-storage",
+		"@octane-xplat/shaders",
+		"@octane-xplat/share",
+		"@octane-xplat/sheet",
+		"@octane-xplat/smooth-corners",
+		"@octane-xplat/sounds",
+		"@octane-xplat/sqlite",
+		"@octane-xplat/table",
+		"@octane-xplat/tiptap",
+		"@octane-xplat/ui",
+		"@octane-xplat/updates",
+		"@octane-xplat/video",
+		"@octane-xplat/workshop",
+		"create-octane-xplat"
+	],
+	"packages": {
+		"octane": {
+			"version": "0.11.0",
+			"group": "runtime",
+			"singleton": true
+		},
+		"@nativescript-community/octane": {
+			"version": "0.2.5",
+			"group": "runtime",
+			"singleton": true
+		},
+		"@nativescript/core": {
+			"version": "9.1.3",
+			"group": "runtime",
+			"singleton": true
+		},
+		"typescript": {
+			"version": "5.9.3",
+			"group": "compiler"
+		},
+		"@tsrx/oxc": {
+			"version": "0.20.0",
+			"group": "compiler"
+		},
+		"@tsrx/typescript-plugin": {
+			"version": "0.4.11",
+			"group": "compiler"
+		},
+		"tsrx-typegen": {
+			"version": "0.2.2",
+			"group": "compiler"
+		},
+		"vite": {
+			"version": "8.3.0",
+			"group": "bundler"
+		},
+		"@octanejs/vite-plugin": {
+			"version": "0.1.61",
+			"group": "bundler"
+		},
+		"@nativescript-community/vite-octane": {
+			"version": "0.2.1",
+			"group": "bundler"
+		},
+		"@nativescript/vite": {
+			"version": "8.0.17",
+			"group": "bundler"
+		},
+		"nativescript": {
+			"version": "9.1.1",
+			"group": "native-toolchain"
+		},
+		"@nativescript/ios": {
+			"version": "9.1.0",
+			"group": "native-toolchain"
+		},
+		"@nativescript/android": {
+			"version": "9.1.1",
+			"group": "native-toolchain"
+		},
+		"@nativescript/types": {
+			"version": "9.1.4",
+			"group": "native-toolchain"
+		},
+		"@nativescript/types-ios": {
+			"version": "9.1.3",
+			"group": "native-toolchain"
+		},
+		"@nativescript/types-android": {
+			"version": "9.1.1",
+			"group": "native-toolchain"
+		},
+		"@nativescript/macos-node-api": {
+			"version": "0.4.4-next.2026-08-09-31292056208",
+			"group": "native-toolchain"
+		},
+		"@nativescript/windows": {
+			"version": "0.1.0-alpha.144",
+			"group": "native-toolchain"
+		},
+		"vitest": {
+			"version": "4.1.11",
+			"group": "testing"
+		},
+		"@nativescript/unit-test-runner": {
+			"version": "5.0.0",
+			"group": "testing"
+		},
+		"@nativescript-community/gesturehandler": {
+			"version": "2.0.45",
+			"group": "plugin"
+		},
+		"@nativescript-community/ui-drawer": {
+			"version": "0.1.32",
+			"group": "plugin"
+		},
+		"@nativescript-community/ui-image": {
+			"version": "5.0.17",
+			"group": "plugin"
+		},
+		"@valor/nativescript-websockets": {
+			"version": "2.0.3",
+			"group": "plugin"
+		},
+		"@triniwiz/nativescript-masonkit": {
+			"version": "1.0.0-beta.110",
+			"group": "runtime"
+		},
+		"jsdom": {
+			"version": "30.1.1",
+			"group": "testing"
+		}
+	},
+	"profiles": {
+		"windows": {
+			"@nativescript/core": {
+				"version": "9.1.3-next.2",
+				"specifier": "https://pkg.pr.new/@nativescript/core@7d0adce"
+			},
+			"@nativescript/vite": {
+				"version": "8.0.13",
+				"specifier": "https://pkg.pr.new/@nativescript/vite@7d0adce"
+			},
+			"nativescript": {
+				"version": "9.1.2-dev.2026-09-24-36031892256"
+			}
+		}
+	},
+	"overrides": {
+		"@nativescript/vite>esbuild": "0.27.7",
+		"@nativescript-community/vite-octane>esbuild": "0.27.7",
+		"vite>esbuild": "0.27.7"
+	}
+}

package/compatibility.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseDocument } from 'yaml'
+
+/** One supported external version, optionally using a preview tarball specifier. */
+export type ManagedPackage = {
+	version: string
+	specifier?: string
+	group: string
+	singleton?: boolean
+}
+
+/** The release-owned pins used by creator, doctor, and upgrade. */
+export type Compatibility = {
+	schemaVersion: number
+	frameworkVersion: string
+	tools: { nodeMinimum: string; pnpm: string }
+	frameworkPackages: string[]
+	packages: Record<string, ManagedPackage>
+	profiles: Record<string, Record<string, Partial<ManagedPackage>>>
+	overrides: Record<string, string>
+}
+
+const dir = dirname(fileURLToPath(import.meta.url))
+const root = basename(dir) === 'dist' ? dirname(dir) : dir
+// Keep JSON on disk: Vite's asset URL transform produces a data URL here.
+export const compatibility: Compatibility = createRequire(import.meta.url)(
+	join(root, 'compatibility.json'),
+)
+
+/** Look up a known framework package or a profile's external dependency pin. */
+export function managedPackage(name: string, profile = 'default'): ManagedPackage | undefined {
+	if (compatibility.frameworkPackages.includes(name)) {
+		return {
+			version: compatibility.frameworkVersion,
+			group: 'framework',
+			singleton: name === '@octane-xplat/ui',
+		}
+	}
+
+	const base = compatibility.packages[name]
+	return base ? { ...base, ...compatibility.profiles[profile]?.[name] } : undefined
+}
+
+/** Return the pnpm specifier, keeping preview URLs separate from package versions. */
+export function managedSpecifier(name: string, profile = 'default') {
+	const entry = managedPackage(name, profile)
+	return entry?.specifier ?? entry?.version
+}
+
+/** Named pnpm catalog reserved for this compatibility profile. */
+export const managedCatalog = (profile = 'default') =>
+	profile === 'default' ? 'xplat' : `xplat-${profile}`
+
+/** Installed dependency fields; library consumer peers intentionally keep their ranges. */
+export const dependencySections = [
+	'dependencies',
+	'devDependencies',
+	'optionalDependencies',
+] as const
+
+/** Select Windows preview pins, rejecting a package that also needs mobile pins. */
+export function projectProfile(pkg: Record<string, any>): string {
+	const deps = Object.assign({}, ...dependencySections.map((section) => pkg[section]))
+	const windows = deps['@nativescript/windows'] || pkg.xplat?.targets?.windows
+	if (windows && (deps['@nativescript/ios'] || deps['@nativescript/android'])) {
+		throw new Error(
+			'Windows preview and mobile need separate workspace packages: their NativeScript pins differ',
+		)
+	}
+
+	return windows ? 'windows' : 'default'
+}
+
+/** Add missing pins when enabling a target in an older scaffold. Existing pins stay intact. */
+export function ensureCompatibilityCatalog(appRoot: string, pkg: Record<string, any>) {
+	let at = resolve(appRoot)
+	while (!existsSync(join(at, 'pnpm-workspace.yaml')) && dirname(at) !== at) {
+		at = dirname(at)
+	}
+	const workspace = existsSync(join(at, 'pnpm-workspace.yaml')) ? at : appRoot
+	const path = join(workspace, 'pnpm-workspace.yaml')
+	const before = existsSync(path) ? readFileSync(path, 'utf8') : ''
+	const doc = parseDocument(before || '{}\n')
+	if (doc.errors.length) {
+		throw new Error(`${path}: ${doc.errors[0].message}`)
+	}
+
+	const profile = projectProfile(pkg)
+	for (const section of dependencySections) {
+		for (const [name, spec] of Object.entries(pkg[section] ?? {})) {
+			if (spec !== `catalog:${managedCatalog(profile)}`) {
+				continue
+			}
+
+			const key = ['catalogs', managedCatalog(profile), name]
+			if (!doc.hasIn(key)) {
+				doc.setIn(key, managedSpecifier(name, profile))
+			}
+		}
+	}
+
+	const after = String(doc)
+	if (after !== before) {
+		writeFileSync(path, after)
+	}
+}

package/dist/compatibility.js

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "yaml";
+import { createRequire } from "node:module";
+//#region compatibility.ts
+var dir = dirname(fileURLToPath(import.meta.url));
+var root = basename(dir) === "dist" ? dirname(dir) : dir;
+var compatibility = createRequire(import.meta.url)(join(root, "compatibility.json"));
+/** Look up a known framework package or a profile's external dependency pin. */
+function managedPackage(name, profile = "default") {
+	if (compatibility.frameworkPackages.includes(name)) return {
+		version: compatibility.frameworkVersion,
+		group: "framework",
+		singleton: name === "@octane-xplat/ui"
+	};
+	const base = compatibility.packages[name];
+	return base ? {
+		...base,
+		...compatibility.profiles[profile]?.[name]
+	} : void 0;
+}
+/** Return the pnpm specifier, keeping preview URLs separate from package versions. */
+function managedSpecifier(name, profile = "default") {
+	const entry = managedPackage(name, profile);
+	return entry?.specifier ?? entry?.version;
+}
+/** Named pnpm catalog reserved for this compatibility profile. */
+var managedCatalog = (profile = "default") => profile === "default" ? "xplat" : `xplat-${profile}`;
+/** Installed dependency fields; library consumer peers intentionally keep their ranges. */
+var dependencySections = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies"
+];
+/** Select Windows preview pins, rejecting a package that also needs mobile pins. */
+function projectProfile(pkg) {
+	const deps = Object.assign({}, ...dependencySections.map((section) => pkg[section]));
+	const windows = deps["@nativescript/windows"] || pkg.xplat?.targets?.windows;
+	if (windows && (deps["@nativescript/ios"] || deps["@nativescript/android"])) throw new Error("Windows preview and mobile need separate workspace packages: their NativeScript pins differ");
+	return windows ? "windows" : "default";
+}
+/** Add missing pins when enabling a target in an older scaffold. Existing pins stay intact. */
+function ensureCompatibilityCatalog(appRoot, pkg) {
+	let at = resolve(appRoot);
+	while (!existsSync(join(at, "pnpm-workspace.yaml")) && dirname(at) !== at) at = dirname(at);
+	const workspace = existsSync(join(at, "pnpm-workspace.yaml")) ? at : appRoot;
+	const path = join(workspace, "pnpm-workspace.yaml");
+	const before = existsSync(path) ? readFileSync(path, "utf8") : "";
+	const doc = parseDocument(before || "{}\n");
+	if (doc.errors.length) throw new Error(`${path}: ${doc.errors[0].message}`);
+	const profile = projectProfile(pkg);
+	for (const section of dependencySections) for (const [name, spec] of Object.entries(pkg[section] ?? {})) {
+		if (spec !== `catalog:${managedCatalog(profile)}`) continue;
+		const key = [
+			"catalogs",
+			managedCatalog(profile),
+			name
+		];
+		if (!doc.hasIn(key)) doc.setIn(key, managedSpecifier(name, profile));
+	}
+	const after = String(doc);
+	if (after !== before) writeFileSync(path, after);
+}
+//#endregion
+export { compatibility, dependencySections, ensureCompatibilityCatalog, managedCatalog, managedPackage, managedSpecifier, projectProfile };

package/dist/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { composeLibrary, composeTargets, defaultTargets, resolveTargets, selectableTargets, targets } from "./scaffold.js";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+//#region index.ts
+var argv = process.argv.slice(2);
+var noInstall = argv.includes("--no-install");
+var templateIndex = argv.findIndex((arg) => arg === "--template" || arg.startsWith("--template="));
+var templateValueIndex = templateIndex !== -1 && argv[templateIndex] === "--template" ? templateIndex + 1 : -1;
+var templateArg = templateIndex === -1 ? "app" : templateValueIndex !== -1 ? argv[templateValueIndex] : argv[templateIndex].slice(11);
+var nameIndex = argv.findIndex((arg) => arg === "--name" || arg.startsWith("--name="));
+var nameValueIndex = nameIndex !== -1 && argv[nameIndex] === "--name" ? nameIndex + 1 : -1;
+var nameArg = nameIndex === -1 ? void 0 : nameValueIndex !== -1 ? argv[nameValueIndex] : argv[nameIndex].slice(7);
+if (templateIndex !== -1 && (!templateArg || templateArg.startsWith("-"))) {
+	console.error("✗ --template needs a value: app or library");
+	process.exit(1);
+}
+if (!["app", "library"].includes(templateArg)) {
+	console.error(`✗ unknown template "${templateArg}" — expected app or library`);
+	process.exit(1);
+}
+if (nameIndex !== -1 && (!nameArg || nameArg.startsWith("-"))) {
+	console.error("✗ --name needs an npm package name");
+	process.exit(1);
+}
+var targetsIndex = argv.findIndex((arg) => arg === "--targets" || arg.startsWith("--targets="));
+var targetsValueIndex = targetsIndex !== -1 && argv[targetsIndex] === "--targets" ? targetsIndex + 1 : -1;
+var targetsArg = targetsIndex === -1 ? void 0 : targetsValueIndex !== -1 ? argv[targetsValueIndex] : argv[targetsIndex].slice(10);
+if (targetsIndex !== -1 && (targetsArg === void 0 || targetsArg.startsWith("-"))) {
+	console.error(`✗ --targets needs a comma list: ${selectableTargets.join(", ")}`);
+	process.exit(1);
+}
+var optionValues = new Set([
+	targetsValueIndex,
+	templateValueIndex,
+	nameValueIndex
+].filter((index) => index !== -1));
+var positional = argv.filter((arg, i) => !arg.startsWith("-") && !optionValues.has(i));
+var defaultDir = templateArg === "library" ? "octane-xplat-library" : "octane-xplat-app";
+var dir = resolve(positional[0] ?? defaultDir);
+if (templateArg === "library" && targetsIndex !== -1) {
+	console.error("✗ --targets applies to the app template; libraries start with web and native builds");
+	process.exit(1);
+}
+if (templateArg === "app" && nameIndex !== -1) {
+	console.error("✗ --name applies only to the library template");
+	process.exit(1);
+}
+if (existsSync(dir) && readdirSync(dir).length > 0) {
+	console.error(`✗ ${dir} exists and is not empty`);
+	process.exit(1);
+}
+var parseTargets = (value) => {
+	const ids = value.split(",").map((s) => s.trim()).filter(Boolean);
+	if (ids.length === 0) throw new Error(`--targets needs a comma list: ${selectableTargets.join(", ")}`);
+	for (const id of ids) if (!selectableTargets.includes(id)) throw new Error(`unknown target "${id}" — expected a comma list of: ${selectableTargets.join(", ")}`);
+	return resolveTargets(ids);
+};
+var ids = [];
+if (templateArg === "library") {
+	const packageName = nameArg ?? basename(dir);
+	try {
+		composeLibrary(dir, packageName);
+	} catch (error) {
+		console.error(`✗ ${error.message}`);
+		process.exit(1);
+	}
+	console.log(`\n✓ scaffolded ${dir} (library: ${packageName}; web + iOS + Android)`);
+} else {
+	if (targetsArg !== void 0) try {
+		ids = parseTargets(targetsArg);
+	} catch (error) {
+		console.error(`✗ ${error.message}`);
+		process.exit(1);
+	}
+	else if (process.stdout.isTTY) {
+		const p = await import("@clack/prompts");
+		p.intro("create-octane-xplat");
+		const picked = await p.multiselect({
+			message: "Target platforms",
+			options: selectableTargets.map((id) => ({
+				value: id,
+				label: targets[id].label,
+				hint: targets[id].note
+			})),
+			initialValues: [...defaultTargets],
+			required: true
+		});
+		if (p.isCancel(picked)) {
+			p.cancel("Cancelled");
+			process.exit(0);
+		}
+		ids = picked;
+	} else ids = defaultTargets;
+	composeTargets(ids, dir);
+	console.log(`\n✓ scaffolded ${dir} (${[...new Set(resolveTargets(ids))].filter((id) => !targets[id].hidden).join(", ")})`);
+}
+if (noInstall) {
+	console.log("\nSkipped install (--no-install). To run manually:");
+	printNextSteps(dir, ids, templateArg);
+	process.exit(0);
+}
+var install = spawnSync("pnpm", ["install"], {
+	cwd: dir,
+	stdio: "inherit"
+});
+if (install.status !== 0) {
+	console.log(`\nInstall didn't finish (pnpm missing?). To run manually:`);
+	printNextSteps(dir, ids, templateArg);
+	process.exit(install.status ?? 1);
+}
+if (templateArg === "app" && ids.includes("web")) {
+	console.log("\n✓ installed — starting dev server (Ctrl+C to stop)\n");
+	spawnSync("pnpm", ["dev"], {
+		cwd: dir,
+		stdio: "inherit"
+	});
+} else {
+	console.log("\n✓ installed. Next steps:");
+	printNextSteps(dir, ids, templateArg);
+}
+function printNextSteps(dir, ids, template) {
+	console.log(`  cd ${dir}\n  pnpm install`);
+	if (template === "library") {
+		console.log("  pnpm typecheck\n  pnpm lint\n  pnpm typegen\n  pnpm test\n  pnpm test:packed");
+		return;
+	}
+	if (ids.includes("web")) console.log("  pnpm dev");
+	else console.log("  pnpm xplat dev");
+}
+//#endregion