create-octane-xplat 0.0.0-nightly.g2e22171

package/README.md

@@ -0,0 +1,90 @@
+# create-octane-xplat
+
+> Get a TypeScript app running, then build its first useful flow with your
+> coding agent.
+
+Xplat's target direction spans web, iOS, Android, macOS, Windows, and Linux.
+This starter configures **web, iOS, and Android**. macOS, Windows, and Linux
+are separate experiments — an AppKit host, a WinUI 3 scaffold with runtime
+verification pending, and a WebKitGTK webview host. See
+[target support](https://octane-xplat.goddardai.org/spec#choose-your-targets).
+The framework is `0.x` and its API surface is still changing.
+
+With Node.js and pnpm 11.24.0 installed:
+
+```sh
+pnpm create octane-xplat my-app
+```
+
+## Start a library package
+
+To start a reusable package instead of an app, select the library template:
+
+```sh
+pnpm create octane-xplat my-controls --template library
+cd my-controls
+pnpm typecheck
+pnpm typegen
+pnpm test:packed
+```
+
+The library starter publishes source for web, iOS, and Android, which the
+consuming app compiles. It includes conditional exports, generated `.d.ts`
+declarations, lint and unit-test
+scripts, and a packed-consumer check. Pass `--name @acme/my-controls` to set a
+scoped npm package name; otherwise the folder name becomes the package name.
+Library creation installs dependencies but does not start an app dev server.
+Desktop targets are not included in this starter.
+
+The creator asks which platforms to target — web, iOS, and Android are all
+pre-selected. Pass `--targets` to skip the prompt:
+
+```sh
+pnpm create octane-xplat my-app --targets web          # web only
+pnpm create octane-xplat my-app --targets web,android  # web + Android
+```
+
+Platforms skipped here can be enabled later with `pnpm xplat add <platform>`
+inside the app. (Non-interactive runs without `--targets` scaffold all
+three.)
+
+The creator copies the template, installs dependencies with pnpm, and starts
+the web dev server when the web target is included. Open the printed URL and
+open `my-app` in your agent.
+Ask it to read `AGENTS.md` and `.agents/skills/xplat/SKILL.md`, then build a
+packing checklist with add, pack, and remove actions using in-memory state.
+Check the result before asking for the next feature: add “Passport” and
+“Charger,” pack Passport, and confirm that one item remains. Reloading should
+clear the list in this in-memory version. The
+[first-flow guide](https://octane-xplat.goddardai.org/toolchain#build-and-check-your-first-flow)
+includes the full prompt and failure checks.
+
+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.
+
+Leave the server running while you edit. After stopping it, restart from the
+app directory:
+
+```sh
+cd my-app
+pnpm dev            # web
+```
+
+From that directory, these commands run other targets or check the app — the
+`dev:*`/`build:*` entries exist only for platforms chosen at create time
+(`pnpm xplat add` adds the rest later):
+
+```sh
+pnpm dev:ios        # needs macOS, Xcode, and NativeScript setup
+pnpm dev:android    # needs Android SDK, compatible JDK, and NativeScript setup
+pnpm lint
+pnpm typecheck      # tsconfig.json + every declared environment
+pnpm build          # web production bundle
+```
+
+[Get a working app and iterate](https://octane-xplat.goddardai.org/toolchain)
+provides prerequisites, live-update boundaries, and version guidance. The
+starter's Xplat skill is included; NativeScript's official skills are optional
+and installed separately. Ask your agent to report checks and targets actually
+run. [llms.txt](https://octane-xplat.goddardai.org/llms.txt) indexes the docs.

package/index.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import {
+	composeLibrary,
+	composeTargets,
+	defaultTargets,
+	resolveTargets,
+	selectableTargets,
+	targets,
+} from './scaffold.mjs'
+
+const argv = process.argv.slice(2)
+const noInstall = argv.includes('--no-install')
+const templateIndex = argv.findIndex((arg) => arg === '--template' || arg.startsWith('--template='))
+const templateValueIndex =
+	templateIndex !== -1 && argv[templateIndex] === '--template' ? templateIndex + 1 : -1
+
+const templateArg =
+	templateIndex === -1
+		? 'app'
+		: templateValueIndex !== -1
+			? argv[templateValueIndex]
+			: argv[templateIndex].slice('--template='.length)
+
+const nameIndex = argv.findIndex((arg) => arg === '--name' || arg.startsWith('--name='))
+const nameValueIndex = nameIndex !== -1 && argv[nameIndex] === '--name' ? nameIndex + 1 : -1
+const nameArg =
+	nameIndex === -1
+		? undefined
+		: nameValueIndex !== -1
+			? argv[nameValueIndex]
+			: argv[nameIndex].slice('--name='.length)
+
+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)
+}
+
+const targetsIndex = argv.findIndex((arg) => arg === '--targets' || arg.startsWith('--targets='))
+const targetsValueIndex =
+	targetsIndex !== -1 && argv[targetsIndex] === '--targets' ? targetsIndex + 1 : -1
+
+const targetsArg =
+	targetsIndex === -1
+		? undefined
+		: targetsValueIndex !== -1
+			? argv[targetsValueIndex]
+			: argv[targetsIndex].slice('--targets='.length)
+
+if (targetsIndex !== -1 && (targetsArg === undefined || targetsArg.startsWith('-'))) {
+	console.error(`✗ --targets needs a comma list: ${selectableTargets.join(', ')}`)
+	process.exit(1)
+}
+
+const optionValues = new Set(
+	[targetsValueIndex, templateValueIndex, nameValueIndex].filter((index) => index !== -1),
+)
+
+const positional = argv.filter((arg, i) => !arg.startsWith('-') && !optionValues.has(i))
+const defaultDir = templateArg === 'library' ? 'octane-xplat-library' : 'octane-xplat-app'
+const 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)
+}
+
+const 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)
+}
+
+let 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 !== undefined) {
+		try {
+			ids = parseTargets(targetsArg)
+		} catch (error) {
+			console.error(`✗ ${error.message}`)
+			process.exit(1)
+		}
+	} else if (process.stdout.isTTY) {
+		// Lazy: the extracted tarball has no installed deps — only the interactive
+		// path needs @clack/prompts (verify-consumer runs the bin dep-free).
+		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)
+}
+
+const 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 {
+		// No web entry — `xplat dev` discovers whichever native targets exist.
+		console.log('  pnpm xplat dev')
+	}
+}

package/library-template/.oxlintrc.json

@@ -0,0 +1,24 @@
+{
+	"jsPlugins": ["@octane-xplat/lint/oxlint-plugin"],
+	"rules": {
+		"curly": "error",
+		"xplat/no-dom-globals": "error",
+		"xplat/no-web-only-api": "error",
+		"xplat/element-vocabulary": "error",
+		"xplat/no-nativescript-import": "error",
+		"xplat/no-ns-deep-import": "error",
+		"xplat/no-native-dead-style": "error",
+		"xplat/no-line-height-unitless": "error",
+		"xplat/no-style-string": "error",
+		"xplat/no-unknown-class": "warn",
+		"xplat/no-ts-imports-tsrx": "error",
+		"xplat/signal-dollar-suffix": "error",
+		"xplat/require-signals-runtime": "warn",
+		"xplat/no-view-onpress": "error",
+		"xplat/no-console-debug": "error",
+		"xplat/hooks-in-plain-ts": "warn",
+		"xplat/native-pragma-first-line": "error",
+		"xplat/no-jsx-text-breakers": "error",
+		"xplat/no-root-logical-render": "error"
+	}
+}

package/library-template/AGENTS.md

@@ -0,0 +1,16 @@
+# Library package notes
+
+- Use pnpm for package management.
+- Keep the public API in `src/index.ts` and `src/index.web.ts`; both barrels
+  must export the same names and types.
+- Put shared prop contracts in `src/props.ts` and document public exports.
+- The unsuffixed `.tsx` file is the NativeScript implementation. Add a
+  `.web.tsx` sibling when browser behavior or markup needs to differ. Native
+  files start with `/** @jsxImportSource @nativescript-community/octane */`.
+- Keep DOM globals out of native files. Use the shared `@octane-xplat/ui`
+  elements when behavior can be shared.
+- Declare every imported package. Runtime plugins belong in `dependencies`;
+  Octane and renderer packages belong in `peerDependencies` when consumers
+  supply the runtime.
+- Before publishing, run `pnpm typecheck`, `pnpm lint`, `pnpm test`,
+  `pnpm typegen`, and `pnpm test:packed`.

package/library-template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [copyright holder]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/library-template/README.md

@@ -0,0 +1,64 @@
+# octane-xplat-library
+
+A cross-platform component library for Octane Xplat. The starter includes a
+small `Badge` component and a packed-consumer check so you can build a package
+and check the artifact that will be published.
+
+## Start here
+
+Install this package in an Octane Xplat app:
+
+```sh
+pnpm add octane-xplat-library
+```
+
+Render the example component from your app:
+
+```tsx
+import { Badge } from 'octane-xplat-library'
+
+export function Welcome() {
+	return <Badge label="Ready" />
+}
+```
+
+## Develop and check
+
+Run these commands from the package directory:
+
+```sh
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm typegen
+pnpm test:packed
+```
+
+The package publishes authored source for the app's bundler to compile.
+`pnpm typegen` generates `.d.ts` files so consumers' type checkers use
+declarations. `pnpm test:packed` packs the package, places that artifact into
+small web and native TypeScript consumers, and checks both export conditions.
+
+The package sets `nodeLinker: hoisted` in `pnpm-workspace.yaml` because the
+NativeScript bundler expects a flat dependency tree.
+
+## Platform files
+
+`src/Badge.tsx` is the shared iOS and Android implementation. The
+`src/Badge.web.tsx` sibling supplies the web implementation. Keep their props
+and exports aligned in `src/props.ts` and the two `src/index` barrels. Add
+`.ios.tsx`, `.android.tsx`, or `.mobile.tsx` files only when a behavior needs
+to differ on those targets.
+
+The starter supports web, iOS, and Android. It does not include app shells or
+desktop runtime entries. If the package uses a NativeScript plugin, declare it
+as a runtime dependency and add the plugin's required platform files and
+metadata to this package.
+
+## Prepare to publish
+
+Before publishing, replace the generated package name and repository metadata
+in `package.json`, fill in the year and copyright holder in `LICENSE`, and
+confirm that every runtime import is declared. `pnpm test:packed` checks the
+package tarball's web and native type exports; it does not build or launch a
+consuming app on a device.

package/library-template/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+types/
+coverage/
+.turbo/

package/library-template/package.json

@@ -0,0 +1,89 @@
+{
+	"name": "octane-xplat-library",
+	"version": "0.1.0",
+	"description": "A cross-platform component library for Octane Xplat",
+	"keywords": [
+		"android",
+		"cross-platform",
+		"ios",
+		"octane",
+		"octane-xplat",
+		"ui",
+		"web"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/your-org/your-library",
+		"directory": "."
+	},
+	"files": [
+		"src",
+		"types",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": {
+			"macos": null,
+			"linux": null,
+			"windows": null,
+			"web": {
+				"types": "./types/index.web.d.ts",
+				"default": "./src/index.web.ts"
+			},
+			"native": {
+				"types": "./types/index.d.ts",
+				"default": "./src/index.ts"
+			},
+			"types": "./types/index.d.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"typegen": "tsrx-typegen --project tsconfig.types.json",
+		"typecheck": "xplat typecheck",
+		"lint": "xplat-lint",
+		"lint:fix": "xplat-lint --fix",
+		"test": "vitest run",
+		"test:packed": "node tests/packed-consumer.mjs",
+		"prepack": "pnpm typegen && tsrx-typegen --pack-check",
+		"pack:check": "pnpm test:packed",
+		"format": "xplat fmt"
+	},
+	"devDependencies": {
+		"@nativescript-community/octane": "catalog:",
+		"@nativescript/core": "catalog:",
+		"@nativescript/types": "catalog:",
+		"@octane-xplat/cli": "^0.0.0-nightly.g2e22171",
+		"@octane-xplat/lint": "^0.0.0-nightly.g2e22171",
+		"@octane-xplat/ui": "^0.0.0-nightly.g2e22171",
+		"@octanejs/vite-plugin": "catalog:",
+		"@tsrx/oxc": "0.20.0",
+		"@tsrx/typescript-plugin": "catalog:",
+		"octane": "catalog:",
+		"oxlint": "^1.74.0",
+		"tsrx-typegen": "^0.2.2",
+		"typescript": "catalog:",
+		"vite": "catalog:",
+		"vitest": "catalog:"
+	},
+	"peerDependencies": {
+		"@nativescript-community/octane": ">=0.2.1 <1",
+		"@nativescript/core": ">=9.1.0 <10",
+		"@octane-xplat/ui": "^0.0.0-nightly.g2e22171",
+		"octane": ">=0.6.3 <1"
+	},
+	"peerDependenciesMeta": {
+		"@nativescript-community/octane": {
+			"optional": true
+		},
+		"@nativescript/core": {
+			"optional": true
+		}
+	},
+	"packageManager": "pnpm@11.24.0"
+}

package/library-template/pnpm-workspace.yaml

@@ -0,0 +1,17 @@
+# NativeScript's bundler resolves dependencies from the flat package tree.
+nodeLinker: hoisted
+allowBuilds:
+  esbuild: true
+  '@parcel/watcher': true
+  '@nativescript/core': false
+# Shared version pins — bump these here, every dependency field reads them.
+catalog:
+  octane: 0.11.0
+  '@nativescript-community/octane': 0.2.4
+  '@nativescript/core': 9.1.3
+  '@nativescript/types': 9.1.4
+  typescript: 5.9.3
+  vite: 8.3.0
+  '@octanejs/vite-plugin': 0.1.61
+  '@tsrx/typescript-plugin': 0.4.11
+  vitest: 4.1.11

package/library-template/src/Badge.tsx

@@ -0,0 +1,21 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { Text, View } from '@octane-xplat/ui'
+import { normalizeBadgeLabel } from './normalizeBadgeLabel'
+import type { BadgeProps } from './props'
+
+/**
+ * Render a short label using Octane's NativeScript elements.
+ * @example
+ * ```tsx
+ * import { Badge } from 'octane-xplat-library'
+ *
+ * <Badge label="Ready" />
+ * ```
+ */
+export function Badge(props: BadgeProps) {
+	return (
+		<View className={props.className}>
+			<Text>{normalizeBadgeLabel(props.label)}</Text>
+		</View>
+	)
+}

package/library-template/src/Badge.web.tsx

@@ -0,0 +1,21 @@
+/** @jsxImportSource octane */
+import { Text, View } from '@octane-xplat/ui'
+import { normalizeBadgeLabel } from './normalizeBadgeLabel'
+import type { BadgeProps } from './props'
+
+/**
+ * Render a short label using Octane's web elements.
+ * @example
+ * ```tsx
+ * import { Badge } from 'octane-xplat-library'
+ *
+ * <Badge label="Ready" />
+ * ```
+ */
+export function Badge(props: BadgeProps) {
+	return (
+		<View className={props.className}>
+			<Text>{normalizeBadgeLabel(props.label)}</Text>
+		</View>
+	)
+}

package/library-template/src/index.ts

@@ -0,0 +1,3 @@
+export { Badge } from './Badge'
+export { normalizeBadgeLabel } from './normalizeBadgeLabel'
+export type { BadgeProps } from './props'

package/library-template/src/index.web.ts

@@ -0,0 +1,3 @@
+export { Badge } from './Badge'
+export { normalizeBadgeLabel } from './normalizeBadgeLabel'
+export type { BadgeProps } from './props'

package/library-template/src/normalizeBadgeLabel.ts

@@ -0,0 +1,12 @@
+/**
+ * Trim surrounding whitespace from a badge label.
+ * @example
+ * ```ts
+ * import { normalizeBadgeLabel } from 'octane-xplat-library'
+ *
+ * normalizeBadgeLabel('  Ready  ')
+ * ```
+ */
+export function normalizeBadgeLabel(label: string): string {
+	return label.trim()
+}

package/library-template/src/props.ts

@@ -0,0 +1,14 @@
+/** Props for the starter badge component. */
+export interface BadgeProps {
+	/** Text displayed inside the badge.
+	 * @example
+	 * ```tsx
+	 * import { Badge } from 'octane-xplat-library'
+	 *
+	 * <Badge label="Ready" />
+	 * ```
+	 */
+	label: string
+	/** Optional class name forwarded to the outer view. */
+	className?: string
+}

package/library-template/tests/normalizeBadgeLabel.test.ts

@@ -0,0 +1,6 @@
+import { expect, it } from 'vitest'
+import { normalizeBadgeLabel } from '../src/normalizeBadgeLabel'
+
+it('trims surrounding whitespace from a badge label', () => {
+	expect(normalizeBadgeLabel('  Ready  ')).toBe('Ready')
+})