create-stator 1.3.0 → 1.5.0

package/index.js

@@ -42,13 +42,18 @@ const TEMPLATES = [
     label: 'With auth',
     hint: 'accounts, guarded login, roles, session rotation (Node 24+)',
   },
+  {
+    value: 'weather',
+    label: 'Weather',
+    hint: 'live forecasts over SSE, entry-effect data loading, a canvas island',
+  },
 ]
 
 /** 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 STATOR_RANGE = '^1.4.0'
 
 const { values: flags, positionals } = parseArgs({
   allowPositionals: true,
@@ -142,8 +147,18 @@ if (!template) {
 }
 
 // --- fetch ---
-const ref = flags.ref ? `#${flags.ref}` : ''
-const source = isRemoteSource(template) ? template : `${FIRST_PARTY}/${template}${ref}`
+// Source and ref are held separately so provenance can record them apart:
+// community sources may embed a ref (`github:user/repo/path#branch`), while
+// first-party templates take it from --ref.
+const sourceBase = (isRemoteSource(template) ? template : `${FIRST_PARTY}/${template}`).split(
+  '#',
+)[0]
+const refName = isRemoteSource(template)
+  ? template.includes('#')
+    ? template.slice(template.indexOf('#') + 1)
+    : null
+  : (flags.ref ?? null)
+const source = refName ? `${sourceBase}#${refName}` : sourceBase
 const s = p.spinner()
 s.start(`Fetching ${template}`)
 try {
@@ -170,6 +185,18 @@ try {
     pkg.dependencies['@statorjs/stator'] = STATOR_RANGE
   }
   delete pkg.private
+  // Record where this scaffold came from. The commit is the merge base for a
+  // later template update (docs: recipes/updating-from-a-template) — the one
+  // fact that can only be captured now. Best-effort: null when offline.
+  pkg.stator = {
+    template: {
+      v: 1,
+      source: sourceBase,
+      ref: refName,
+      commit: resolveTemplateCommit(sourceBase, refName),
+      scaffoldedAt: new Date().toISOString(),
+    },
+  }
   await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
   s.stop(`Scaffolded ${name} (${template})`)
 } catch {
@@ -231,3 +258,30 @@ function bailIfCancelled(v) {
     process.exit(0)
   }
 }
+
+/** Resolve the template ref to a commit sha for provenance. Best-effort by
+ *  design: no git, no network, or an unknown provider all return null rather
+ *  than slow down or fail the scaffold. Annotated tags resolve to the peeled
+ *  commit (`^{}`) when the host lists one. */
+function resolveTemplateCommit(src, refName) {
+  if (refName && /^[0-9a-f]{40}$/.test(refName)) return refName
+  // giget providers that are also plain git hosts, for `git ls-remote`.
+  const hosts = {
+    gh: 'github.com',
+    github: 'github.com',
+    gitlab: 'gitlab.com',
+    bitbucket: 'bitbucket.org',
+  }
+  const m = src.match(/^([a-z]+):([^/]+\/[^/#]+)/)
+  const host = m && hosts[m[1]]
+  if (!host) return null
+  const out = spawnSync('git', ['ls-remote', `https://${host}/${m[2]}`, refName ?? 'HEAD'], {
+    encoding: 'utf8',
+    timeout: 15_000,
+  })
+  if (out.status !== 0 || !out.stdout) return null
+  const lines = out.stdout.trim().split('\n')
+  const line = lines.find((l) => l.includes('^{}')) ?? lines[0]
+  const sha = line?.split(/\s+/)[0]
+  return sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-stator",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Scaffold a new Stator app: pnpm create stator my-app",
   "license": "MIT",
   "type": "module",