@typemvc/create 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 coretravis
+
+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/README.md

@@ -0,0 +1,39 @@
+# @typemvc/create
+
+Project initializer for [TypeMVC](https://github.com/coretravis/typemvc). Scaffolds a minimal, ready-to-run app.
+
+## Usage
+
+```bash
+npm create @typemvc@latest my-app
+# or: pnpm create @typemvc my-app
+# or: yarn create @typemvc my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `--name <name>` | Project name (default: target directory name) |
+| `--force`, `-f` | Scaffold into a non-empty directory |
+| `--no-git` | Do not run `git init` |
+| `--help`, `-h` | Show help |
+| `--version`, `-v` | Show the version |
+
+## What you get
+
+A Vite SPA wired for TypeMVC: a typed `tsconfig.json`, the `@typemvc/core/vite` plugin, a bootstrap entry, a Home controller with a reactive counter, a 404 catch-all controller, and matching `.tmvc` views. The generated app installs, typechecks, and builds against the published `@typemvc/core`.
+
+This package has zero runtime dependencies and is non-interactive (flags only), so it works in CI and scripts.
+
+## License
+
+MIT (c) coretravis

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scaffold } from './scaffold.js';
+const here = dirname(fileURLToPath(import.meta.url));
+function parseArgs(argv) {
+    let dir;
+    let name;
+    let force = false;
+    let git = true;
+    let help = false;
+    let version = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+        }
+        else if (arg === '--version' || arg === '-v') {
+            version = true;
+        }
+        else if (arg === '--force' || arg === '-f') {
+            force = true;
+        }
+        else if (arg === '--no-git') {
+            git = false;
+        }
+        else if (arg === '--name') {
+            name = argv[i + 1];
+            i++;
+        }
+        else if (arg.startsWith('--name=')) {
+            name = arg.slice('--name='.length);
+        }
+        else if (!arg.startsWith('-') && dir === undefined) {
+            dir = arg;
+        }
+        else {
+            throw new Error(`[TypeMVC] Unknown argument "${arg}". Run with --help for usage.`);
+        }
+    }
+    return { dir, name, force, git, help, version };
+}
+function readVersion() {
+    const raw = readFileSync(join(here, '..', 'package.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.version ?? '0.0.0';
+}
+function detectPackageManager() {
+    const ua = process.env.npm_config_user_agent;
+    if (ua === undefined || ua === '')
+        return 'npm';
+    const name = ua.split(' ')[0]?.split('/')[0];
+    if (name === 'pnpm' || name === 'yarn' || name === 'bun')
+        return name;
+    return 'npm';
+}
+function printHelp() {
+    console.log([
+        'Create a new TypeMVC app.',
+        '',
+        'Usage:',
+        '  npm create @typemvc@latest <dir> [options]',
+        '',
+        'Options:',
+        '  --name <name>   Project name (default: target directory name)',
+        '  --force, -f     Scaffold into a non-empty directory',
+        '  --no-git        Do not run git init',
+        '  --help, -h      Show this help',
+        '  --version, -v   Show the version',
+    ].join('\n'));
+}
+function tryGitInit(targetDir) {
+    const result = spawnSync('git', ['init'], { cwd: targetDir, stdio: 'ignore' });
+    if (result.status !== 0) {
+        console.warn('[TypeMVC] Skipped git init (git not available or failed).');
+    }
+}
+function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help) {
+        printHelp();
+        return;
+    }
+    if (options.version) {
+        console.log(readVersion());
+        return;
+    }
+    if (options.dir === undefined) {
+        throw new Error('[TypeMVC] Please specify the target directory. ' +
+            'Example: npm create @typemvc@latest my-app');
+    }
+    const targetDir = resolve(process.cwd(), options.dir);
+    const projectName = options.name ?? basename(targetDir);
+    if (projectName === '' || projectName.includes('/') || projectName.includes('\\')) {
+        throw new Error(`[TypeMVC] Invalid project name "${projectName}". ` +
+            `Provide a valid name with --name, or use a directory name without path separators.`);
+    }
+    const result = scaffold({
+        targetDir,
+        projectName,
+        templateDir: join(here, '..', 'template'),
+        force: options.force,
+    });
+    if (options.git) {
+        tryGitInit(targetDir);
+    }
+    const pm = detectPackageManager();
+    console.log(`\nScaffolded ${String(result.files.length)} files into ${targetDir}\n`);
+    console.log('Next steps:');
+    console.log(`  cd ${options.dir}`);
+    console.log(`  ${pm} install`);
+    console.log(`  ${pm} run dev\n`);
+}
+try {
+    main();
+}
+catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    console.error(error.message);
+    process.exitCode = 1;
+}

package/dist/scaffold.js

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+const PROJECT_NAME_TOKEN = '{{projectName}}';
+/**
+ * Copies the template tree into targetDir, replacing the project-name token and
+ * renaming `_gitignore` to `.gitignore`. Throws if the target is non-empty and
+ * force is not set.
+ */
+export function scaffold(options) {
+    const { targetDir, projectName, templateDir, force = false } = options;
+    if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !force) {
+        throw new Error(`[TypeMVC] Target directory "${targetDir}" is not empty. ` +
+            `Pass --force to scaffold into it anyway.`);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    const written = [];
+    copyDir(templateDir, targetDir, targetDir, projectName, written);
+    return { files: written };
+}
+function copyDir(srcDir, destDir, rootDest, projectName, written) {
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = join(srcDir, entry.name);
+        if (entry.isDirectory()) {
+            const subDest = join(destDir, entry.name);
+            mkdirSync(subDest, { recursive: true });
+            copyDir(srcPath, subDest, rootDest, projectName, written);
+            continue;
+        }
+        const destName = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+        const destPath = join(destDir, destName);
+        const content = readFileSync(srcPath, 'utf8').replaceAll(PROJECT_NAME_TOKEN, projectName);
+        writeFileSync(destPath, content);
+        written.push(relative(rootDest, destPath).split(sep).join('/'));
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@typemvc/create",
+  "version": "0.1.0",
+  "description": "Project initializer for TypeMVC. Run with: npm create @typemvc",
+  "type": "module",
+  "license": "MIT",
+  "author": "coretravis",
+  "homepage": "https://github.com/coretravis/typemvc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coretravis/typemvc.git",
+    "directory": "packages/create"
+  },
+  "bugs": {
+    "url": "https://github.com/coretravis/typemvc/issues"
+  },
+  "keywords": [
+    "typemvc",
+    "create",
+    "scaffold",
+    "starter",
+    "init"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-typemvc": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "latest",
+    "@types/node": "^25.9.3",
+    "eslint": "latest",
+    "typescript": "latest",
+    "typescript-eslint": "latest",
+    "vitest": "latest"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "ci": "pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}

package/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.local
+.DS_Store

package/template/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+    <style>
+      body { font-family: system-ui, sans-serif; max-width: 640px; margin: 48px auto; padding: 0 16px; }
+      nav a { margin-right: 12px; }
+      button { font-size: 1rem; padding: 4px 12px; cursor: pointer; }
+      .count { font-size: 2.5rem; font-weight: 700; margin: 8px 0; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@typemvc/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "latest",
+    "vite": "^6.0.0"
+  }
+}

package/template/src/controllers/HomeController.ts

@@ -0,0 +1,41 @@
+import { Controller, controller, get, action, retain, signal, computed, View } from '@typemvc/core';
+import type { IView, ReadonlySignal } from '@typemvc/core';
+
+type HomeData = {
+  title: string;
+  count: ReadonlySignal<number>;
+  doubled: ReadonlySignal<number>;
+};
+
+// '/' is the home route. @retain() keeps this instance, and its signal state,
+// alive across navigations, so the count survives leaving and returning.
+@controller('/')
+@retain()
+class HomeController extends Controller {
+  readonly #count = signal(0);
+  readonly #doubled = computed(() => this.#count.get() * 2);
+
+  // GET '/' renders views/home/index.tmvc (convention: <controller>/<action>).
+  @get()
+  index(): IView<HomeData> {
+    return View({
+      title: 'Hello, TypeMVC',
+      count: this.#count,
+      doubled: this.#doubled,
+    });
+  }
+
+  // @action marks a non-route method exposed to the view as context.increment.
+  // Mutating the signal reactively updates only the DOM nodes that read it.
+  @action
+  increment(): void {
+    this.#count.update((n) => n + 1);
+  }
+
+  @action
+  reset(): void {
+    this.#count.set(0);
+  }
+}
+
+export { HomeController };

package/template/src/controllers/NotFoundController.ts

@@ -0,0 +1,13 @@
+import { Controller, controller, get, View } from '@typemvc/core';
+import type { IView } from '@typemvc/core';
+
+// '*' is the catch-all: any URL no other controller matches lands here.
+@controller('*')
+class NotFoundController extends Controller {
+  @get()
+  notFound(): IView {
+    return View('notfound/notfound');
+  }
+}
+
+export { NotFoundController };

package/template/src/main.ts

@@ -0,0 +1,20 @@
+import { bootstrap } from '@typemvc/core';
+import { HomeController } from './controllers/HomeController.js';
+import { NotFoundController } from './controllers/NotFoundController.js';
+
+const outlet = document.getElementById('app');
+if (outlet === null) throw new Error('[App] No #app element found in index.html');
+
+bootstrap({
+  outlet,
+  viewsRoot: '/src/views/',
+  // Lazy view glob: each .tmvc view is code-split and loaded on navigation.
+  views: import.meta.glob('/src/views/**/*.tmvc'),
+  logging: { level: 'debug' },
+  configure(app) {
+    // Register routed controllers. Add services here too, e.g.
+    //   app.singleton(MY_SERVICE, () => new MyService());
+    app.route(HomeController);
+    app.route(NotFoundController); // @controller('*') catch-all, keep this last.
+  },
+});

package/template/src/views/home/index.tmvc

@@ -0,0 +1,24 @@
+@model from HomeController.index
+
+<main>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/does-not-exist">Broken link (404)</a>
+  </nav>
+
+  <h1>${context.model.title}</h1>
+
+  <p>
+    This number is a <code>signal()</code>. The buttons call
+    <code>@action</code> methods on the controller, and only the text node below
+    re-renders. No page reload, no virtual DOM.
+  </p>
+
+  <p class="count">${context.model.count}</p>
+  <p>x 2 = ${context.model.doubled}</p>
+
+  <div>
+    <button onclick="${context.increment}">+1</button>
+    <button onclick="${context.reset}">Reset</button>
+  </div>
+</main>

package/template/src/views/notfound/notfound.tmvc

@@ -0,0 +1,5 @@
+<main>
+  <h1>404, not found</h1>
+  <p>No route matched <code>${context.router.current}</code>.</p>
+  <p><a href="/">Back home</a></p>
+</main>

package/template/src/vite-env.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+// Teaches TypeScript that importing a .tmvc file yields a view render function.
+declare module '*.tmvc' {
+  import type { TmvcViewFunction } from '@typemvc/core';
+  const template: TmvcViewFunction;
+  export default template;
+}

package/template/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "dom", "dom.iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "experimentalDecorators": true,
+    "ignoreDeprecations": "6.0",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig, type PluginOption } from 'vite';
+import { typemvcPlugin } from '@typemvc/core/vite';
+
+// typemvcPlugin() compiles .tmvc view documents. The framework does not depend
+// on vite's types, so cast its structural plugin to vite's PluginOption.
+export default defineConfig({
+  plugins: [typemvcPlugin() as PluginOption],
+  appType: 'spa',
+});