create-stator 1.1.0 → 1.3.0

package/index.js

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
-// Stator scaffolder. Interactive (clack) when run bare; every prompt has a
-// flag so CI and scripts stay prompt-free:
-//   pnpm create stator            → prompts for directory + template
-//   pnpm create stator my-app --template minimal   → no prompts
-import { cp, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+// Stator scaffolder. First-party templates live in the monorepo's
+// `examples/` directory and are FETCHED at scaffold time (create-astro
+// style) — they update with every push, and `--template` accepts any giget
+// source (`github:user/repo/path`) so community templates work for free.
+//
+// Interactive (clack) when run bare; every prompt has a flag so CI and
+// scripts stay prompt-free:
+//   pnpm create stator                                → prompts
+//   pnpm create stator my-app --template todomvc      → no prompts
+//   pnpm create stator my-app -t github:you/your-template
+import { spawn, spawnSync } from 'node:child_process'
+import { readdir, readFile, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import * as p from '@clack/prompts'
+import { downloadTemplate } from 'giget'
 
 const TEMPLATES = [
   {
@@ -15,20 +22,81 @@ const TEMPLATES = [
     label: 'Minimal',
     hint: 'one machine, one page — the smallest real app',
   },
+  {
+    value: 'todomvc',
+    label: 'TodoMVC',
+    hint: 'the classic, with server-owned todos and zero-JS editing',
+  },
+  {
+    value: 'desksmith',
+    label: 'Desksmith',
+    hint: "the tutorial's finished app — catalog, cart, checkout, theme island",
+  },
+  {
+    value: 'live-poll',
+    label: 'Live poll',
+    hint: 'shared app-machine state, pushed to every visitor over SSE',
+  },
+  {
+    value: 'with-auth',
+    label: 'With auth',
+    hint: 'accounts, guarded login, roles, session rotation (Node 24+)',
+  },
 ]
 
+/** First-party templates resolve into the monorepo's examples/. */
+const FIRST_PARTY = 'gh:statorjs/stator/examples'
+/** Scaffolded apps get a real semver for the framework (the examples
+ *  themselves use workspace linking in-repo). Bumped with releases. */
+const STATOR_RANGE = '^1.1.0'
+
 const { values: flags, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     template: { type: 'string', short: 't' },
+    ref: { type: 'string' },
+    install: { type: 'boolean' },
+    'no-install': { type: 'boolean' },
+    git: { type: 'boolean' },
+    'no-git': { type: 'boolean' },
+    yes: { type: 'boolean', short: 'y' },
     help: { type: 'boolean', short: 'h' },
   },
 })
 
+/** The package manager that LAUNCHED us (`pnpm create stator` → pnpm), via
+ *  the standard npm_config_user_agent header. Defaults to npm. */
+function detectPackageManager() {
+  const agent = process.env.npm_config_user_agent ?? ''
+  if (agent.startsWith('pnpm')) return 'pnpm'
+  if (agent.startsWith('yarn')) return 'yarn'
+  if (agent.startsWith('bun')) return 'bun'
+  return 'npm'
+}
+const pm = detectPackageManager()
+const runCmd = (script) => (pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`)
+
+/** Resolve a yes/no choice: explicit flag > --yes > prompt (TTY) > safe
+ *  default for non-interactive runs. */
+async function decide({ yesFlag, noFlag, message, fallback }) {
+  if (yesFlag) return true
+  if (noFlag) return false
+  if (flags.yes) return true
+  if (!process.stdout.isTTY) return fallback
+  const answer = await p.confirm({ message, initialValue: true })
+  bailIfCancelled(answer)
+  return answer
+}
+
 if (flags.help) {
   console.log(
     `Usage: pnpm create stator [directory] [--template ${TEMPLATES.map((t) => t.value).join('|')}]`,
   )
+  console.log('       pnpm create stator my-app --template github:user/repo/path')
+  console.log('       --ref <branch|tag>     fetch first-party templates from a specific ref')
+  console.log('       --install/--no-install install dependencies after scaffolding')
+  console.log('       --git/--no-git         initialize a git repository')
+  console.log('       -y, --yes              accept all defaults (install + git)')
   process.exit(0)
 }
 
@@ -59,44 +127,102 @@ try {
 
 // --- template ---
 let template = flags.template
-if (template && !TEMPLATES.some((t) => t.value === template)) {
-  p.cancel(`Unknown template "${template}". Available: ${TEMPLATES.map((t) => t.value).join(', ')}`)
+const isRemoteSource = (t) => t.includes(':') || t.includes('/')
+if (template && !isRemoteSource(template) && !TEMPLATES.some((t) => t.value === template)) {
+  p.cancel(
+    `Unknown template "${template}". Available: ${TEMPLATES.map((t) => t.value).join(', ')} ` +
+      `(or any giget source, e.g. github:user/repo/path)`,
+  )
   process.exit(1)
 }
 if (!template) {
-  if (TEMPLATES.length === 1) {
-    template = TEMPLATES[0].value
-  } else {
-    const answer = await p.select({ message: 'Which template?', options: TEMPLATES })
-    bailIfCancelled(answer)
-    template = answer
-  }
+  const answer = await p.select({ message: 'Which template?', options: TEMPLATES })
+  bailIfCancelled(answer)
+  template = answer
 }
 
-// --- scaffold ---
+// --- fetch ---
+const ref = flags.ref ? `#${flags.ref}` : ''
+const source = isRemoteSource(template) ? template : `${FIRST_PARTY}/${template}${ref}`
 const s = p.spinner()
-s.start('Copying template')
-const templateDir = fileURLToPath(new URL(`./templates/${template}`, import.meta.url))
-await cp(templateDir, dest, { recursive: true })
-
-// npm strips dotfiles from published packages; ship as _gitignore and rename.
+s.start(`Fetching ${template}`)
 try {
-  await stat(join(dest, '_gitignore'))
-  await rename(join(dest, '_gitignore'), join(dest, '.gitignore'))
-} catch {
-  // already named .gitignore (running from the repo)
+  await downloadTemplate(source, { dir: dest, force: true })
+} catch (err) {
+  s.stop('Fetch failed')
+  p.cancel(
+    `Could not download "${source}" — scaffolding needs network access.\n   ${String(err?.message ?? err)}`,
+  )
+  process.exit(1)
 }
 
+// --- stamp ---
 const name = basename(dest)
   .toLowerCase()
   .replace(/[^a-z0-9-]/g, '-')
 const pkgPath = join(dest, 'package.json')
-const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
-pkg.name = name
-await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
-s.stop(`Scaffolded ${name} (${template})`)
+try {
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+  pkg.name = name
+  // In-repo examples link the framework via the workspace; a scaffolded
+  // app pins the published release instead.
+  if (pkg.dependencies?.['@statorjs/stator'] === 'workspace:*') {
+    pkg.dependencies['@statorjs/stator'] = STATOR_RANGE
+  }
+  delete pkg.private
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+  s.stop(`Scaffolded ${name} (${template})`)
+} catch {
+  s.stop(`Scaffolded ${name} (${template}) — no package.json to stamp`)
+}
+
+// --- install? ---
+const wantInstall = await decide({
+  yesFlag: flags.install,
+  noFlag: flags['no-install'],
+  message: `Install dependencies with ${pm}?`,
+  fallback: false,
+})
+let installed = false
+if (wantInstall) {
+  const si = p.spinner()
+  si.start(`Installing with ${pm}`)
+  installed = await new Promise((done) => {
+    const child = spawn(pm, ['install'], { cwd: dest, stdio: 'ignore', shell: true })
+    child.on('close', (code) => done(code === 0))
+    child.on('error', () => done(false))
+  })
+  si.stop(installed ? 'Dependencies installed' : `${pm} install failed — run it yourself`)
+}
+
+// --- git? ---
+const wantGit = await decide({
+  yesFlag: flags.git,
+  noFlag: flags['no-git'],
+  message: 'Initialize a git repository?',
+  fallback: false,
+})
+if (wantGit) {
+  const hasGit = spawnSync('git', ['--version'], { stdio: 'ignore' }).status === 0
+  if (hasGit) {
+    spawnSync('git', ['init', '-q'], { cwd: dest, stdio: 'ignore' })
+    spawnSync('git', ['add', '-A'], { cwd: dest, stdio: 'ignore' })
+    // May no-op if user.name/email are unset — an initialized repo without
+    // a first commit is still a win.
+    spawnSync('git', ['commit', '-q', '-m', 'Initial commit from create-stator'], {
+      cwd: dest,
+      stdio: 'ignore',
+    })
+    p.log.success('Initialized a git repository')
+  } else {
+    p.log.warn('git not found — skipped repository setup')
+  }
+}
 
-p.note([`cd ${target}`, 'pnpm install', 'pnpm dev'].join('\n'), 'Next steps')
+p.note(
+  [`cd ${target}`, ...(installed ? [] : [`${pm} install`]), runCmd('dev')].join('\n'),
+  'Next steps',
+)
 p.outro('Docs: https://docs.statorjs.dev · Demo: https://demo.statorjs.dev')
 
 function bailIfCancelled(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stator",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Scaffold a new Stator app: pnpm create stator my-app",
   "license": "MIT",
   "type": "module",
@@ -8,8 +8,7 @@
     "create-stator": "./index.js"
   },
   "files": [
-    "index.js",
-    "templates"
+    "index.js"
   ],
   "repository": {
     "type": "git",
@@ -21,6 +20,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0"
+    "@clack/prompts": "^1.7.0",
+    "giget": "^1.2.3"
   }
 }

package/templates/minimal/README.md

@@ -1,31 +0,0 @@
-# A Stator app
-
-```sh
-pnpm install
-pnpm dev        # dev server with live reload + the wire inspector
-pnpm typecheck  # sync generated component types, then tsc
-pnpm build      # production build into dist/
-pnpm start      # serve the production build
-```
-
-## The mental model
-
-State lives **on the server**, in machines. Pages declare what they read;
-when an event changes a machine, the server diffs and sends small JSON
-patches to the browser. There is no client renderer and no API layer.
-
-- `machines/counter.ts` — a session-scoped machine: typed events, guarded
-  transitions, selectors. Session state survives a page reload because the
-  server owns it.
-- `routes/index.stator` — a page: frontmatter declares `Stator.reads`, the
-  template calls `read(machine, selector)` wherever live values render.
-- `templates/layout.stator` — a component with a `<children />` slot.
-
-Try it: run `pnpm dev`, click **+1**, then reload the page — the count
-persists. Open the inspector (bottom of the page) and click again to watch
-the patch arrive on the wire.
-
-## Learn more
-
-- Docs: https://docs.statorjs.dev — start with the tutorial
-- Reference app: https://demo.statorjs.dev ([source](https://github.com/statorjs/stator/tree/main/apps/store))

package/templates/minimal/_gitignore

@@ -1,3 +0,0 @@
-node_modules/
-dist/
-.stator/

package/templates/minimal/build.ts

@@ -1,7 +0,0 @@
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { buildApp } from '@statorjs/stator/build'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const result = await buildApp({ root: here, outDir: resolve(here, 'dist') })
-console.log(`stator: built ${result.compiled} components → ${result.outDir}`)

package/templates/minimal/machines/counter.ts

@@ -1,27 +0,0 @@
-import { defineMachine } from '@statorjs/stator/server'
-
-type Events = { type: 'INCREMENT' } | { type: 'RESET' }
-
-export default defineMachine({
-  name: 'CounterMachine',
-  lifecycle: 'session',
-  events: {} as Events,
-  context: { count: 0 },
-  initial: 'idle',
-  states: {
-    idle: {
-      on: {
-        INCREMENT: (ctx) => {
-          ctx.count += 1
-        },
-        RESET: (ctx) => {
-          ctx.count = 0
-        },
-      },
-    },
-  },
-  selectors: {
-    count: (ctx) => ctx.count,
-    label: (ctx) => `count is ${ctx.count}`,
-  },
-})

package/templates/minimal/package.json

@@ -1,23 +0,0 @@
-{
-  "name": "my-stator-app",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "sync": "tsx sync.ts",
-    "typecheck": "tsx sync.ts && tsc --noEmit",
-    "dev": "tsx watch server.ts",
-    "build": "tsx build.ts",
-    "start": "tsx start.ts"
-  },
-  "dependencies": {
-    "@statorjs/stator": "^1.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.7.0",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.0",
-    "vite": "^6.0.0",
-    "pino-pretty": "^13.1.3"
-  }
-}

package/templates/minimal/routes/index.stator

@@ -1,14 +0,0 @@
----
-import Counter from '../machines/counter.ts'
-import Layout from '../templates/layout.stator'
-
-const [counter] = Stator.reads([Counter])
----
-<Layout>
-  <section class="counter">
-    <h1>Hello, Stator</h1>
-    <p class="count">{read(counter, (c) => c.label)}</p>
-    <button on:click={() => counter.send({ type: 'INCREMENT' })}>+1</button>
-    <button on:click={() => counter.send({ type: 'RESET' })}>reset</button>
-  </section>
-</Layout>

package/templates/minimal/server.ts

@@ -1,19 +0,0 @@
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { createDevApp } from '@statorjs/stator/dev'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const port = Number(process.env.PORT ?? 3000)
-
-// Dev server: Vite compiles `.stator` on the way in, with live reload and the
-// inspector toolbar. Production runs `pnpm build && pnpm start` instead.
-// Sessions default to the in-memory store — swap in RedisStore (from
-// '@statorjs/stator/server') to survive restarts.
-const app = await createDevApp({
-  root: here,
-  machinesDir: resolve(here, 'machines'),
-  routesDir: resolve(here, 'routes'),
-  staticDir: resolve(here, 'static'),
-})
-
-await app.listen(port)

package/templates/minimal/start.ts

@@ -1,25 +0,0 @@
-import { stat } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { loadProductionHead } from '@statorjs/stator/build'
-import { createApp, logger } from '@statorjs/stator/server'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const dist = resolve(here, 'dist')
-const port = Number(process.env.PORT ?? 3000)
-
-try {
-  await stat(resolve(dist, 'routes'))
-} catch {
-  logger.error({}, 'no dist/ found — run `pnpm build` first')
-  process.exit(1)
-}
-
-const app = await createApp({
-  machinesDir: resolve(dist, 'machines'),
-  routesDir: resolve(dist, 'routes'),
-  staticDir: resolve(dist, 'static'),
-  headExtras: await loadProductionHead(dist),
-})
-
-await app.listen(port)

package/templates/minimal/static/app.css

@@ -1,5 +0,0 @@
-:root { font-family: system-ui, sans-serif; color-scheme: light dark; }
-body { margin: 0; display: grid; place-items: center; min-height: 100vh; }
-.counter { text-align: center; }
-.count { font-size: 1.5rem; font-variant-numeric: tabular-nums; }
-button { font: inherit; padding: 0.4rem 1rem; margin: 0 0.25rem; cursor: pointer; }

package/templates/minimal/stator-env.d.ts

@@ -1,11 +0,0 @@
-/**
- * Ambient type for `.stator` single-file components, for this app's TypeScript
- * project. (Stator apps include one of these, like Vite apps include env.d.ts.)
- */
-declare module '*.stator' {
-  import type { HtmlFragment } from '@statorjs/stator/template'
-
-  // biome-ignore lint/suspicious/noExplicitAny: the wildcard fallback must admit every component's props — `Record<string, unknown>` would reject interfaces without index signatures
-  const component: (props?: any) => HtmlFragment
-  export default component
-}

package/templates/minimal/sync.ts

@@ -1,7 +0,0 @@
-import { dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { syncTypes } from '@statorjs/stator/build'
-
-const here = dirname(fileURLToPath(import.meta.url))
-const { written } = await syncTypes(here)
-console.log(`stator: wrote ${written} .stator.d.ts files`)

package/templates/minimal/templates/layout.stator

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>stator app</title>
-    <link rel="stylesheet" href="/static/app.css" />
-  </head>
-  <body>
-    <main><children /></main>
-  </body>
-</html>

package/templates/minimal/tsconfig.json

@@ -1,33 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "lib": [
-      "ES2022",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "isolatedModules": true,
-    "allowImportingTsExtensions": true,
-    "noEmit": true,
-    "rootDirs": [
-      ".",
-      ".stator/types"
-    ],
-    "jsx": "preserve"
-  },
-  "include": [
-    "**/*.ts",
-    "**/*.stator"
-  ],
-  "exclude": [
-    "node_modules",
-    "static",
-    "dist"
-  ]
-}