create-grist-widget 0.3.7 → 0.3.9

package/bin/create-grist-widget.mjs

@@ -1,105 +1,500 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readdirSync, cpSync, readFileSync, writeFileSync, renameSync } from "node:fs"
+// create-grist-widget — scaffold a Grist custom widget, fully offline.
+//
+// Four verbs (batch H, docs/planning/2026-08-execution-plan.md §98-105):
+//   create <name> [--example <id>]   scaffold a new widget into ./<name>
+//   init [--example <id>]            scaffold into the current directory
+//   use <example-id>                 swap the current project's widget
+//   list [--json]                    print the available starting examples
+//
+// `create`/`init`/`use` share one compose engine — see
+// packages/create-grist-widget/vendor/compose-example.mjs (a verbatim,
+// path-free copy of scripts/compose-example.mjs, embedded by
+// scripts/build-template.mjs alongside the template itself, along with
+// examples/, ui-source/, and manifest.json — see that script for why).
+// Nothing here ever hits the network: everything list/use/create --example
+// need already shipped in the tarball.
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { execFileSync } from "node:child_process"
+import * as clack from "@clack/prompts"
 
-const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "template")
+import { createComposer } from "../vendor/compose-example.mjs"
+import { checkGitGate } from "../src/git-gate.mjs"
 
-const rawName = process.argv[2]
-if (!rawName) {
-  console.error("Usage: npm create grist-widget <widget-name>")
-  process.exit(1)
+const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
+const TEMPLATE_DIR = path.join(PKG_ROOT, "template")
+
+const cliPkg = JSON.parse(readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"))
+
+const composer = createComposer({
+  templateDir: TEMPLATE_DIR,
+  examplesDir: path.join(PKG_ROOT, "examples"),
+  uiDir: path.join(PKG_ROOT, "ui-source"),
+  manifestPath: path.join(PKG_ROOT, "manifest.json"),
+})
+
+function loadManifest() {
+  return JSON.parse(readFileSync(path.join(PKG_ROOT, "manifest.json"), "utf8"))
 }
 
 // Mirrors npm's own unscoped package name rule, kept intentionally loose.
-if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(rawName)) {
-  console.error(`"${rawName}" is not a valid name — use lowercase letters, digits, and hyphens.`)
-  process.exit(1)
+function isValidName(name) {
+  return /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(name || "")
 }
 
-const target = path.resolve(process.cwd(), rawName)
-if (existsSync(target) && readdirSync(target).length > 0) {
-  console.error(`"${rawName}" already exists and is not empty.`)
-  process.exit(1)
+function titleCase(name) {
+  return name
+    .split("-")
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(" ")
+}
+
+function detectPackageManager() {
+  // e.g. "pnpm/9.1.0 npm-node/..." -> "pnpm". Set by every package manager's
+  // own `npm create`-equivalent invocation. Falls back to npm, matching
+  // what a bare `node bin/create-grist-widget.mjs` (no wrapping pm) should do.
+  const ua = process.env.npm_config_user_agent || ""
+  return ua.split("/")[0] || "npm"
+}
+
+function parseArgs(argv) {
+  const out = { _: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith("--")) {
+      const key = a.slice(2)
+      const next = argv[i + 1]
+      if (next === undefined || next.startsWith("--")) out[key] = true
+      else {
+        out[key] = next
+        i++
+      }
+    } else out._.push(a)
+  }
+  return out
+}
+
+function printHelp() {
+  console.log(`create-grist-widget — scaffold a Grist custom widget, offline
+
+Usage:
+  npm create grist-widget <name> [options]       Scaffold into ./<name>
+  create-grist-widget create <name> [options]    Same as above, explicit
+  create-grist-widget init [options]             Scaffold into the current directory
+  create-grist-widget use <example-id>           Swap the current project's widget
+  create-grist-widget list [--json]              List available starting examples
+
+Options (create / init):
+  --example <id>   Start from a named example instead of the blank template
+                    (see "list" for ids)
+  --yes            Skip interactive prompts, use defaults/flags only
+  --no-install     Don't run the package manager install automatically
+  --pm <name>      Package manager for install (default: detected from how
+                    you invoked this — npm/pnpm/yarn/bun)
+  --name <name>    (init only) Widget name — default: the current directory's name
+  --force          (init only) Overwrite files that already exist and differ
+                    from the template
+
+  --help, -h       Show this help
+  --version, -v    Show this CLI's version
+
+Note: "create", "init", "use", and "list" are themselves valid widget names.
+A bare "create-grist-widget list" runs the list command, not "scaffold a
+widget named list" — use "create-grist-widget create list" for that.`)
+}
+
+/** Same four placeholder-identity edits every scaffold gets, whichever verb produced it. */
+function applyIdentityEdits(target, rawName) {
+  const title = titleCase(rawName)
+  const edits = [
+    ["package.json", [["grist-widget-template-vite", rawName]]],
+    ["README.md", [["grist-widget-template-vite", rawName]]],
+    ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
+    ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
+  ]
+  for (const [file, subs] of edits) {
+    const p = path.join(target, file)
+    if (!existsSync(p)) continue
+    let content = readFileSync(p, "utf8")
+    for (const [search, replace] of subs) content = content.split(search).join(replace)
+    writeFileSync(p, content)
+  }
+  return title
 }
-mkdirSync(target, { recursive: true })
-cpSync(TEMPLATE_DIR, target, { recursive: true })
 
 // npm strips a literal `.gitignore` from the published package (see
-// build-template.mjs), so it ships as `_gitignore` — restore the real name.
-const gitignorePath = path.join(target, "_gitignore")
-if (existsSync(gitignorePath)) renameSync(gitignorePath, path.join(target, ".gitignore"))
-
-const title = rawName
-  .split("-")
-  .map((w) => w[0].toUpperCase() + w.slice(1))
-  .join(" ")
-
-// Small, fixed set of files carry the template's own identity — swap it for the user's.
-const edits = [
-  ["package.json", [["grist-widget-template-vite", rawName]]],
-  ["README.md", [["grist-widget-template-vite", rawName]]],
-  ["index.html", [["<title>Grist Widget</title>", `<title>${title}</title>`]]],
-  ["src/App.tsx", [['title: "Grist Widget Template",', `title: "${title}",`]]],
-]
-for (const [file, subs] of edits) {
-  const p = path.join(target, file)
-  let content = readFileSync(p, "utf8")
-  for (const [search, replace] of subs) content = content.split(search).join(replace)
-  writeFileSync(p, content)
-}
-
-// Record which create-grist-widget release produced this scaffold -- purely
-// informational (shown in a small landing-page footer), never read by the
-// deploy pipeline's own version/release logic. Every scaffold gets this,
-// including the ones the template-canary workflow generates for its `dev`
-// and `canary/latest` branches -- so it survives even if that content is
-// later promoted into a reference repo's `main` and copied again via
-// GitHub's "Use this template".
-const cliPkg = JSON.parse(
-  readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"),
-)
-const pkgJsonPath = path.join(target, "package.json")
-const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"))
-pkgJson.createGristWidgetVersion = cliPkg.version
-writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n")
-
-// Initialize git on `main` with the scaffold as its first commit, and a
-// `dev` branch ready to push for live-preview later. Doing this here (not
-// leaving it to whoever/whatever runs next) is what actually prevents the
-// scaffold from ending up on some other branch — the deploy workflow only
-// ever releases from `main`, so committing anywhere else silently never
-// deploys. Degrades gracefully: if there's no git identity configured yet,
-// `main` still exists locally, just without a commit.
-function git(args) {
-  execFileSync("git", args, { cwd: target, stdio: "ignore" })
-}
-let committed = false
-try {
-  git(["init", "-q", "-b", "main"])
-  git(["add", "-A"])
-  git(["commit", "-q", "-m", "scaffold: initial widget"])
-  git(["branch", "dev"])
-  committed = true
-} catch {
-  // No git identity configured (or git unavailable) — leave it to the
-  // printed next steps below.
-}
-
-console.log(`Created ${rawName}/\n`)
-console.log(`  cd ${rawName}`)
-console.log("  pnpm install   # or npm/yarn")
-console.log("  pnpm dev")
-if (committed) {
-  console.log("\nGit is initialized on main (first commit done) with a dev branch ready.")
-  console.log("To push to GitHub:")
-  console.log("  git remote add origin https://github.com/<owner>/<repo>.git")
-  console.log("  git push -u origin main")
-  console.log("  git push origin dev   # optional, for the live-preview channel")
-} else {
-  console.log("\nCould not create the initial git commit automatically (no git identity")
-  console.log('configured?) — run `git config user.name`/`user.email`, then:')
-  console.log("  git init -b main && git add -A && git commit -m 'scaffold: initial widget'")
-  console.log("  git branch dev")
+// scripts/build-template.mjs), so it ships as `_gitignore` — restore the real name.
+function restoreGitignore(target) {
+  const gitignorePath = path.join(target, "_gitignore")
+  if (existsSync(gitignorePath)) renameSync(gitignorePath, path.join(target, ".gitignore"))
+}
+
+// Purely informational (a small landing-page footer), never read by the
+// deploy pipeline's own version/release logic.
+function stampCreateGristWidgetVersion(target) {
+  const pkgJsonPath = path.join(target, "package.json")
+  const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"))
+  pkgJson.createGristWidgetVersion = cliPkg.version
+  writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n")
+}
+
+/** Initialize git on `main` with a first commit and a `dev` branch, if a git identity is configured. */
+function gitInitCommit(target) {
+  function git(args) {
+    execFileSync("git", args, { cwd: target, stdio: "ignore" })
+  }
+  try {
+    git(["init", "-q", "-b", "main"])
+    git(["add", "-A"])
+    git(["commit", "-q", "-m", "scaffold: initial widget"])
+    git(["branch", "dev"])
+    return true
+  } catch {
+    // No git identity configured (or git unavailable) — leave it to the
+    // printed next steps.
+    return false
+  }
+}
+
+function maybeInstall(target, { noInstall, pm }) {
+  if (noInstall) return false
+  const manager = pm || detectPackageManager()
+  try {
+    execFileSync(manager, ["install"], { cwd: target, stdio: "inherit" })
+    return true
+  } catch {
+    console.warn(`\nCould not run "${manager} install" automatically — run it yourself.`)
+    return false
+  }
+}
+
+function listFilesRecursive(dir, base = dir) {
+  const out = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...listFilesRecursive(full, base))
+    else out.push(path.relative(base, full).split(path.sep).join("/"))
+  }
+  return out
+}
+
+/** Interactive "which example?" picker, shared by `create` and `init` — reads the same manifest.json `list` does. */
+async function pickExampleInteractively(manifest) {
+  const choice = await clack.select({
+    message: "Start from an example?",
+    options: [
+      { value: null, label: "Blank template (two-field editor)" },
+      ...manifest.map((e) => ({ value: e.id, label: e.title, hint: e.description })),
+    ],
+  })
+  if (clack.isCancel(choice)) {
+    clack.cancel("Cancelled.")
+    process.exit(1)
+  }
+  return choice
+}
+
+function resolveExampleFlag(exampleFlag, manifest) {
+  if (exampleFlag === undefined || exampleFlag === true) return { ok: true, exampleId: null }
+  if (exampleFlag === "blank") return { ok: true, exampleId: null }
+  if (!manifest.some((e) => e.id === exampleFlag)) {
+    return { ok: false }
+  }
+  return { ok: true, exampleId: exampleFlag }
+}
+
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+
+async function cmdCreate(argv) {
+  const args = parseArgs(argv)
+  const manifest = loadManifest()
+  const interactive = Boolean(process.stdout.isTTY) && !args.yes && !args._[0]
+
+  let rawName = args._[0]
+  let exampleId = null
+
+  if (args.example !== undefined) {
+    const resolved = resolveExampleFlag(args.example, manifest)
+    if (!resolved.ok) {
+      console.error(`Unknown example "${args.example}". Run "create-grist-widget list" to see available examples.`)
+      process.exit(1)
+    }
+    exampleId = resolved.exampleId
+  }
+
+  if (interactive) {
+    clack.intro("create-grist-widget")
+    if (!rawName) {
+      const nameAnswer = await clack.text({
+        message: "Widget name",
+        placeholder: "my-widget",
+        validate: (v) => (isValidName(v) ? undefined : "lowercase letters, digits, hyphens only"),
+      })
+      if (clack.isCancel(nameAnswer)) {
+        clack.cancel("Cancelled.")
+        process.exit(1)
+      }
+      rawName = nameAnswer
+    }
+    if (args.example === undefined) {
+      exampleId = await pickExampleInteractively(manifest)
+    }
+    clack.outro("Scaffolding...")
+  }
+
+  if (!rawName) {
+    console.error("Usage: npm create grist-widget <widget-name> [--example <id>] [--yes] [--no-install] [--pm <pm>]")
+    process.exit(1)
+  }
+  if (!isValidName(rawName)) {
+    console.error(`"${rawName}" is not a valid name — use lowercase letters, digits, and hyphens.`)
+    process.exit(1)
+  }
+
+  const target = path.resolve(process.cwd(), rawName)
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`"${rawName}" already exists and is not empty.`)
+    process.exit(1)
+  }
+  mkdirSync(target, { recursive: true })
+  cpSync(TEMPLATE_DIR, target, { recursive: true })
+  restoreGitignore(target)
+  applyIdentityEdits(target, rawName)
+
+  if (exampleId) {
+    composer.overlayExampleSrc({ exampleId, destDir: target })
+    composer.mergeExtraDependencies({ exampleId, destDir: target })
+  }
+
+  stampCreateGristWidgetVersion(target)
+
+  const committed = gitInitCommit(target)
+  const installed = maybeInstall(target, {
+    noInstall: Boolean(args["no-install"]),
+    pm: typeof args.pm === "string" ? args.pm : null,
+  })
+
+  console.log(`\nCreated ${rawName}/${exampleId ? ` (starting from "${exampleId}")` : ""}\n`)
+  console.log(`  cd ${rawName}`)
+  if (!installed) console.log("  pnpm install   # or npm/yarn")
+  console.log("  pnpm dev")
+  if (committed) {
+    console.log("\nGit is initialized on main (first commit done) with a dev branch ready.")
+    console.log("To push to GitHub:")
+    console.log("  git remote add origin https://github.com/<owner>/<repo>.git")
+    console.log("  git push -u origin main")
+    console.log("  git push origin dev   # optional, for the live-preview channel")
+  } else {
+    console.log("\nCould not create the initial git commit automatically (no git identity")
+    console.log('configured?) — run `git config user.name`/`user.email`, then:')
+    console.log("  git init -b main && git add -A && git commit -m 'scaffold: initial widget'")
+    console.log("  git branch dev")
+  }
+}
+
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+
+async function cmdInit(argv) {
+  const args = parseArgs(argv)
+  const manifest = loadManifest()
+  const cwd = process.cwd()
+
+  let exampleId = null
+  if (args.example !== undefined) {
+    const resolved = resolveExampleFlag(args.example, manifest)
+    if (!resolved.ok) {
+      console.error(`Unknown example "${args.example}". Run "create-grist-widget list" to see available examples.`)
+      process.exit(1)
+    }
+    exampleId = resolved.exampleId
+  }
+
+  const interactive = Boolean(process.stdout.isTTY) && !args.yes && args.example === undefined
+  if (interactive) {
+    clack.intro("create-grist-widget init")
+    exampleId = await pickExampleInteractively(manifest)
+    clack.outro("Initializing...")
+  }
+
+  const rawName = typeof args.name === "string" ? args.name : path.basename(cwd)
+  if (!isValidName(rawName)) {
+    console.error(
+      `"${rawName}" is not a valid widget name (derived from the current directory) — pass --name.`
+    )
+    process.exit(1)
+  }
+
+  // File-collision policy: identity-bearing files always get edited in place
+  // (naturally a no-op wherever the placeholder text is already gone — the
+  // common case, a pristine "Use this template" clone); anything else that
+  // already exists and differs from the template's own pristine copy blocks
+  // the run, listed, unless --force.
+  const IDENTITY_FILES = new Set(["package.json", "README.md", "index.html", "src/App.tsx"])
+  const templateFiles = listFilesRecursive(TEMPLATE_DIR)
+  if (!args.force) {
+    const conflicts = []
+    for (const rel of templateFiles) {
+      if (IDENTITY_FILES.has(rel)) continue
+      const destPath = path.join(cwd, rel)
+      if (!existsSync(destPath)) continue
+      const same = readFileSync(path.join(TEMPLATE_DIR, rel)).equals(readFileSync(destPath))
+      if (!same) conflicts.push(rel)
+    }
+    if (conflicts.length > 0) {
+      console.error(
+        `init: refusing to overwrite the following files (already exist and differ from the template) — remove them or re-run with --force:\n` +
+          conflicts.map((f) => `  ${f}`).join("\n")
+      )
+      process.exit(1)
+    }
+  }
+
+  for (const rel of templateFiles) {
+    const destPath = path.join(cwd, rel)
+    mkdirSync(path.dirname(destPath), { recursive: true })
+    cpSync(path.join(TEMPLATE_DIR, rel), destPath)
+  }
+  restoreGitignore(cwd)
+  applyIdentityEdits(cwd, rawName)
+
+  if (exampleId) {
+    composer.overlayExampleSrc({ exampleId, destDir: cwd })
+    composer.mergeExtraDependencies({ exampleId, destDir: cwd })
+  }
+
+  stampCreateGristWidgetVersion(cwd)
+
+  // Never auto-commit into a pre-existing repo's history — only take over
+  // git entirely when cwd had none to begin with (a fresh, non-git directory,
+  // or a real git clone where .git already carries whatever history it has).
+  const gitAlreadyExists = existsSync(path.join(cwd, ".git"))
+  const committed = gitAlreadyExists ? false : gitInitCommit(cwd)
+  const installed = maybeInstall(cwd, {
+    noInstall: Boolean(args["no-install"]),
+    pm: typeof args.pm === "string" ? args.pm : null,
+  })
+
+  console.log(`\nInitialized ${rawName}/${exampleId ? ` (starting from "${exampleId}")` : ""} in the current directory.\n`)
+  if (!installed) console.log("  pnpm install   # or npm/yarn")
+  console.log("  pnpm dev")
+  if (gitAlreadyExists) {
+    console.log("\nExisting git repository detected — no commit was made automatically.")
+    console.log("Review the changes (git status) and commit when ready.")
+  } else if (committed) {
+    console.log("\nGit is initialized on main (first commit done) with a dev branch ready.")
+  } else {
+    console.log("\nCould not create the initial git commit automatically (no git identity")
+    console.log('configured?) — run `git config user.name`/`user.email`, then commit yourself.')
+  }
+}
+
+// ---------------------------------------------------------------------------
+// use
+// ---------------------------------------------------------------------------
+
+function cmdUse(argv) {
+  const args = parseArgs(argv)
+  const exampleId = args._[0]
+  if (!exampleId) {
+    console.error('Usage: create-grist-widget use <example-id>\nRun "create-grist-widget list" to see available examples.')
+    process.exit(1)
+  }
+  const manifest = loadManifest()
+  if (!manifest.some((e) => e.id === exampleId)) {
+    console.error(`Unknown example "${exampleId}". Run "create-grist-widget list" to see available examples.`)
+    process.exit(1)
+  }
+
+  const cwd = process.cwd()
+  const gate = checkGitGate(cwd)
+  if (!gate.ok) {
+    if (gate.reason === "no-repo") {
+      console.error(
+        'use: this command overwrites src/App.tsx and must run inside a git repository so the change is easy to review and undo. Run "git init" first.'
+      )
+    } else {
+      console.error(
+        "use: working tree has uncommitted changes — commit or stash them first, so this swap is easy to diff and undo."
+      )
+    }
+    process.exit(1)
+  }
+
+  composer.overlayExampleSrc({ exampleId, destDir: cwd })
+  const { merged } = composer.mergeExtraDependencies({ exampleId, destDir: cwd })
+
+  console.log(`Swapped in "${exampleId}".`)
+  console.log("\n  git diff       # review what changed")
+  if (merged) console.log("  pnpm install   # new dependencies were added")
+  console.log("  pnpm dev")
+}
+
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+
+function cmdList(argv) {
+  const args = parseArgs(argv)
+  const manifest = loadManifest()
+
+  if (args.json) {
+    // A projected, public subset — not the raw manifest, which carries
+    // monorepo-internal fields (columns, usesUi, sourcePath,
+    // hasExampleDocument) that shouldn't become an accidental CLI contract.
+    const projected = manifest.map((e) => ({ id: e.id, title: e.title, description: e.description }))
+    console.log(JSON.stringify(projected, null, 2))
+    return
+  }
+
+  const idWidth = Math.max(2, ...manifest.map((e) => e.id.length))
+  for (const e of manifest) {
+    console.log(`${e.id.padEnd(idWidth)}  ${e.title} — ${e.description}`)
+  }
 }
+
+// ---------------------------------------------------------------------------
+// dispatch
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const rawArgv = process.argv.slice(2)
+  const [first, ...rest] = rawArgv
+
+  if (first === "--help" || first === "-h") {
+    printHelp()
+    return
+  }
+  if (first === "--version" || first === "-v") {
+    console.log(cliPkg.version)
+    return
+  }
+  if (first === "list") return cmdList(rest)
+  if (first === "use") return cmdUse(rest)
+  if (first === "init") return cmdInit(rest)
+  if (first === "create") return cmdCreate(rest)
+  // Bare invocation — `npm create grist-widget my-widget` (npm's `create`
+  // convention passes argv straight through, no `create` keyword), or no
+  // args at all (interactive). Treat the whole argv as arguments to `create`.
+  return cmdCreate(rawArgv)
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err))
+  process.exit(1)
+})