create-stator 1.0.0 → 1.2.0

package/index.js

@@ -1,54 +1,139 @@
 #!/usr/bin/env node
-// Minimal Stator scaffolder: copies the embedded template into a new
-// directory and stamps the project name. No prompts, no network.
-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 { 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 target = process.argv[2]
-if (!target) {
-  console.log('Usage: pnpm create stator <directory>')
-  console.log('       npm create stator@latest <directory>')
-  process.exit(1)
+const TEMPLATES = [
+  {
+    value: 'minimal',
+    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',
+  },
+]
+
+/** 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' },
+    help: { type: 'boolean', short: 'h' },
+  },
+})
+
+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')
+  process.exit(0)
 }
 
+p.intro('create-stator')
+
+// --- target directory ---
+let target = positionals[0]
+if (!target) {
+  const answer = await p.text({
+    message: 'Where should the project live?',
+    placeholder: './my-stator-app',
+    validate: (v) => (v.trim() === '' ? 'A directory is required.' : undefined),
+  })
+  bailIfCancelled(answer)
+  target = answer
+}
 const dest = resolve(process.cwd(), target)
+
 try {
   const existing = await readdir(dest)
   if (existing.length > 0) {
-    console.error(`create-stator: ${target} exists and is not empty — refusing to overwrite.`)
+    p.cancel(`${target} exists and is not empty — refusing to overwrite.`)
     process.exit(1)
   }
 } catch {
   // does not exist — fine
 }
 
-const templateDir = fileURLToPath(new URL('./template', import.meta.url))
-await cp(templateDir, dest, { recursive: true })
+// --- template ---
+let template = flags.template
+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) {
+  const answer = await p.select({ message: 'Which template?', options: TEMPLATES })
+  bailIfCancelled(answer)
+  template = answer
+}
 
-// npm strips dotfiles from published packages; ship as _gitignore and rename.
+// --- fetch ---
+const ref = flags.ref ? `#${flags.ref}` : ''
+const source = isRemoteSource(template) ? template : `${FIRST_PARTY}/${template}${ref}`
+const s = p.spinner()
+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`)
-
-console.log(`
-  Scaffolded ${name} into ${dest}
+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`)
+}
 
-  Next steps:
-    cd ${target}
-    pnpm install
-    pnpm dev        # http://localhost:3000
+p.note([`cd ${target}`, 'pnpm install', 'pnpm dev'].join('\n'), 'Next steps')
+p.outro('Docs: https://docs.statorjs.dev · Demo: https://demo.statorjs.dev')
 
-  Other scripts: pnpm typecheck · pnpm build · pnpm start
-`)
+function bailIfCancelled(v) {
+  if (p.isCancel(v)) {
+    p.cancel('Cancelled.')
+    process.exit(0)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stator",
-  "version": "1.0.0",
+  "version": "1.2.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",
-    "template"
+    "index.js"
   ],
   "repository": {
     "type": "git",
@@ -19,5 +18,9 @@
   "homepage": "https://github.com/statorjs/stator#readme",
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "giget": "^1.2.3"
   }
 }

package/template/_gitignore

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

package/template/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/template/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/template/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.0.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/template/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/template/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/template/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/template/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/template/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/template/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/template/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/template/tsconfig.json

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