create-stator 1.0.0 → 1.1.0

package/index.js

@@ -1,29 +1,82 @@
 #!/usr/bin/env node
-// Minimal Stator scaffolder: copies the embedded template into a new
-// directory and stamps the project name. No prompts, no network.
+// 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'
 import { basename, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import * as p from '@clack/prompts'
 
-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',
+  },
+]
+
+const { values: flags, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    template: { type: 'string', short: 't' },
+    help: { type: 'boolean', short: 'h' },
+  },
+})
+
+if (flags.help) {
+  console.log(
+    `Usage: pnpm create stator [directory] [--template ${TEMPLATES.map((t) => t.value).join('|')}]`,
+  )
+  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))
+// --- 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(', ')}`)
+  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
+  }
+}
+
+// --- scaffold ---
+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.
@@ -41,14 +94,14 @@ 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})`)
 
-console.log(`
-  Scaffolded ${name} into ${dest}
-
-  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.1.0",
   "description": "Scaffold a new Stator app: pnpm create stator my-app",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,7 @@
   },
   "files": [
     "index.js",
-    "template"
+    "templates"
   ],
   "repository": {
     "type": "git",
@@ -19,5 +19,8 @@
   "homepage": "https://github.com/statorjs/stator#readme",
   "engines": {
     "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
   }
 }

package/templates/minimal/README.md

@@ -0,0 +1,31 @@
+# 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/{template → templates/minimal}/package.json

@@ -11,7 +11,7 @@
     "start": "tsx start.ts"
   },
   "dependencies": {
-    "@statorjs/stator": "^1.0.0"
+    "@statorjs/stator": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.7.0",

package/{template → templates/minimal}/tsconfig.json

@@ -3,7 +3,11 @@
     "target": "ES2022",
     "module": "ESNext",
     "moduleResolution": "Bundler",
-    "lib": ["ES2022", "DOM"],
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
     "strict": true,
     "noUncheckedIndexedAccess": true,
     "esModuleInterop": true,
@@ -11,8 +15,19 @@
     "isolatedModules": true,
     "allowImportingTsExtensions": true,
     "noEmit": true,
-    "rootDirs": [".", ".stator/types"]
+    "rootDirs": [
+      ".",
+      ".stator/types"
+    ],
+    "jsx": "preserve"
   },
-  "include": ["**/*.ts"],
-  "exclude": ["node_modules", "static", "dist"]
+  "include": [
+    "**/*.ts",
+    "**/*.stator"
+  ],
+  "exclude": [
+    "node_modules",
+    "static",
+    "dist"
+  ]
 }