create-dashral 0.1.0 → 0.2.1

package/README.md

@@ -8,9 +8,21 @@ cd my-app
 pnpm dev
 ```
 
-It clones Dashral's newest release into `my-app`, installs the dependencies and runs `pnpm dashral init`. That asks
-which template to keep (Classic, Inset or both), demo pages or a blank page, the languages, your app's name and its
-look. You need **Node.js 20+**, **Git** and **pnpm** (`corepack enable pnpm`).
+Leave out the folder and it asks for the project's name first (Enter takes `my-app`). Then it asks which template to keep (Classic, Inset or both), demo pages or a blank page, the languages, your app's name
+and its look, then makes a Next.js project laid out like a new Next.js app, with its own Git history:
+
+```
+my-app/
+├── app/            pages
+├── components/     the app's own components
+├── lib/  messages/  public/
+├── package.json    "@dashral/ui" from npm
+└── next.config.ts  tsconfig.json
+```
+
+The UI components come from [`@dashral/ui`](https://www.npmjs.com/package/@dashral/ui)
+(`import { Button } from "@dashral/ui/components/button"`): `pnpm up @dashral/ui` brings in new ones and fixes. You need
+**Node.js 20+**, **Git** and **pnpm** (`corepack enable pnpm`).
 
 Every answer is also a flag, so it can run without questions:
 
@@ -22,14 +34,12 @@ The theme customizer's **Copy setup command** in the [live demo](https://demo.da
 
 | Option | |
 | --- | --- |
-| `--pro` | Start from Dashral Pro (your GitHub account needs access to it) |
+| `--monorepo` | Keep Dashral's whole repository (`apps/`, `packages/`) and history instead, so `pnpm dashral update` can bring in later releases, pages too ([Getting updates](https://github.com/hasralgana/dashral#getting-updates)) |
+| `--pro` | Start from Dashral Pro (your GitHub account needs access to it; monorepo for now) |
 | `--release v1.2.0` | An earlier release instead of the newest |
 | `--from <url>` | Clone another repository, e.g. a fork, or Pro over SSH |
 | `--no-install` | Skip `pnpm install` |
 
 Any other option goes to `pnpm dashral init`; `npx create-dashral --help` lists them.
 
-The project keeps the release's Git history, so later releases come in with `pnpm dashral update`. See
-[Getting updates](https://github.com/hasralgana/dashral#getting-updates).
-
 MIT licensed.

package/index.mjs

@@ -1,33 +1,39 @@
 #!/usr/bin/env node
-// `npx create-dashral my-app`: a new dashboard from Dashral's newest release, in one command. It clones the repository
-// at the release's tag (with its history, so `pnpm dashral update` can merge later releases), installs the
-// dependencies, then runs the repository's own `pnpm dashral init` with every other flag you passed. Nothing about the
-// setup lives here: the release's scripts/dashral.mjs does it, so this file rarely needs a new version.
+// `npx create-dashral my-app`: a new dashboard from Dashral's newest release, in one command. By default it makes a
+// Next.js project of its own, like `create-next-app`: the release is cloned, `pnpm dashral init --layout flat` keeps
+// only the app (the components come from npm as @dashral/ui), the project starts a Git history of its own and its
+// dependencies are installed. With --monorepo it keeps the repository's layout and history instead, for
+// `pnpm dashral update`. Nothing about the setup lives here: the release's scripts/dashral.mjs does it, so this file
+// rarely needs a new version.
 //
 //   npx create-dashral my-app
 //   npx create-dashral my-app --template inset --pages blank --languages en --name "Acme" --primary indigo
+//   npx create-dashral my-app --monorepo                                   (the whole repository, for pnpm dashral update)
 //   npx create-dashral my-app --pro --apps crm,kanban --name "Acme"        (Dashral Pro: needs your GitHub access)
 
 import { spawnSync } from "node:child_process"
-import { existsSync, readdirSync } from "node:fs"
-import { resolve } from "node:path"
-import { argv, exit, platform, versions } from "node:process"
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { argv, exit, platform, stdin, stdout, versions } from "node:process"
+import { createInterface } from "node:readline/promises"
 
 const repos = {
   free: "https://github.com/hasralgana/dashral.git",
   pro: "https://github.com/hasralgana/dashral-pro.git",
 }
 
-const help = `Usage: npx create-dashral <folder> [options]
+const help = `Usage: npx create-dashral [folder] [options]
 
-  Starts a new dashboard in <folder> from Dashral's newest release: clones it, installs the dependencies and runs
-  \`pnpm dashral init\`, which asks a few questions (or reads them from the flags below).
+  Starts a new Next.js dashboard in [folder] (asked for when left out) from Dashral's newest release, as a project of its own (the components
+  come from npm as @dashral/ui), and runs \`pnpm dashral init\`, which asks a few questions (or reads the flags below).
 
 Options of create-dashral:
-  --pro                Start from Dashral Pro (your GitHub account needs access to the repository)
+  --monorepo           Keep the whole repository (apps/, packages/) and its history, to bring in later releases
+                       with \`pnpm dashral update\`
+  --pro                Start from Dashral Pro (your GitHub account needs access to the repository; monorepo for now)
   --release v1.2.0     An earlier release instead of the newest
   --from <url>         Clone another repository (a fork, or Pro over SSH: git@github.com:hasralgana/dashral-pro.git)
-  --no-install         Clone and set up only; run \`pnpm install\` yourself
+  --no-install         Set up only; run \`pnpm install\` yourself
 
 Every other option goes to \`pnpm dashral init\`:
   --template classic|inset|both  --pages demo|blank  --languages all|en  --customizer keep|remove
@@ -39,9 +45,13 @@ Docs: https://dashral.com/docs/installation`
 
 // ── Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────
 
+/** Flags that take no value: a word after one of these can be the folder; after any other flag, it's that flag's value. */
+const switches = new Set(["help", "pro", "monorepo", "no-install", "yes", "force"])
+
 /** This script's own flags, and the rest passed to `dashral init` as they were typed. */
 function parseArgs(args) {
-  const own = { pro: false, install: true, release: null, from: null, help: false }
+  const takesValue = (previous) => Boolean(previous?.startsWith("--") && !previous.includes("=") && !switches.has(previous.slice(2)))
+  const own = { pro: false, monorepo: false, install: true, release: null, from: null, help: false }
   const rest = []
   let folder = null
   for (let i = 0; i < args.length; i++) {
@@ -50,11 +60,13 @@ function parseArgs(args) {
     const value = () => (inline !== undefined ? inline : args[++i])
     if (arg === "-h" || key === "help") own.help = true
     else if (key === "pro") own.pro = true
+    else if (key === "monorepo") own.monorepo = true
     else if (key === "no-install") own.install = false
     else if (key === "release" || key === "from") {
       own[key] = value()
       if (!own[key] || own[key].startsWith("--")) fail(`--${key} needs a value.`)
-    } else if (key === null && folder === null) folder = arg
+    } else if (key === "layout") fail("Use --monorepo for the repository's layout; the project is flat without it.")
+    else if (key === null && folder === null && !takesValue(args[i - 1])) folder = arg
     else rest.push(arg)
   }
   return { folder, own, rest }
@@ -68,9 +80,10 @@ function fail(message) {
 }
 
 /** Runs a command in the terminal (its output and questions shown as they come); its exit code, or null. */
-function run(command, args, cwd) {
-  // Windows runs pnpm through a .cmd shim, which needs a shell.
-  const result = spawnSync(command, args, { cwd, stdio: "inherit", shell: platform === "win32" })
+function run(command, args, cwd, quiet = false) {
+  // Windows runs pnpm through a .cmd shim, which needs a shell. DASHRAL_CREATE: init leaves the next steps to us.
+  const env = { ...process.env, DASHRAL_CREATE: "1" }
+  const result = spawnSync(command, args, { cwd, env, stdio: quiet ? "ignore" : "inherit", shell: platform === "win32" })
   return result.error ? null : result.status
 }
 
@@ -89,10 +102,31 @@ const newer = (a, b) => {
 
 // ── Main ─────────────────────────────────────────────────────────────────────────────────────────────────────────
 
-const { folder, own, rest } = parseArgs(argv.slice(2))
-if (own.help || !folder) {
+const parsed = parseArgs(argv.slice(2))
+const { own, rest } = parsed
+let folder = parsed.folder
+if (own.help) {
   console.log(help)
-  exit(own.help ? 0 : 1)
+  exit(0)
+}
+// No folder given: ask for one in a terminal, as create-next-app does (Enter takes my-app); elsewhere, say how.
+if (!folder) {
+  if (!stdin.isTTY) {
+    console.log(help)
+    exit(1)
+  }
+  const rl = createInterface({ input: stdin, output: stdout })
+  for (;;) {
+    const answer = (await rl.question("What is your project named? (my-app) ")).trim() || "my-app"
+    const path = resolve(answer)
+    if (existsSync(path) && readdirSync(path).length) {
+      console.log(`  ${answer} isn't empty. Pick a new name.`)
+      continue
+    }
+    folder = answer
+    break
+  }
+  rl.close()
 }
 
 if (Number(versions.node.split(".")[0]) < 20) fail(`Dashral needs Node.js 20 or newer (this is ${versions.node}).`)
@@ -123,23 +157,55 @@ if (own.release) {
 }
 if (!release) fail(`${url} has no releases yet.`)
 
-// The whole history, not a shallow copy: `pnpm dashral update` merges later releases into it.
-console.log(`\nCloning Dashral ${release} into ${folder}…`)
-if (run("git", ["clone", "--quiet", "--branch", release, url, target]) !== 0) fail(`Couldn't clone ${url}.${access}`)
-// A tag checks out without a branch: start yours, so your commits have one.
-if (run("git", ["switch", "--quiet", "-c", "main"], target) !== 0) fail("Couldn't start the main branch.")
-
-if (own.install) {
-  console.log("\nInstalling the dependencies…")
-  if (run("pnpm", ["install"], target) !== 0) fail(`pnpm install stopped. Fix what it says, then in ${folder}: pnpm install && pnpm dashral init`)
+let flat = !own.monorepo
+if (flat && own.pro) {
+  console.log("  Dashral Pro starts as the monorepo for now (a project of its own is coming).")
+  flat = false
 }
 
-console.log("")
-if (run("node", ["scripts/dashral.mjs", "init", ...rest], target) !== 0) {
-  fail(`The setup stopped. It's a fresh clone, so you can delete ${folder} and start again, or fix what it says and run \`pnpm dashral init\` in it.`)
+// Flat: the files are enough. The monorepo keeps the whole history: `pnpm dashral update` merges later releases into it.
+console.log(`\nCloning Dashral ${release} into ${folder}…`)
+const depth = flat ? ["--depth", "1"] : []
+if (run("git", ["-c", "advice.detachedHead=false", "clone", "--quiet", ...depth, "--branch", release, url, target]) !== 0) fail(`Couldn't clone ${url}.${access}`)
+if (flat && !readFileSync(join(target, "scripts/dashral.mjs"), "utf8").includes("--layout")) {
+  // A release from before the flat layout: set it up as the monorepo.
+  console.log(`  ${release} predates the flat layout, so it's set up as the monorepo.`)
+  flat = false
+  rmSync(target, { recursive: true, force: true })
+  if (run("git", ["-c", "advice.detachedHead=false", "clone", "--quiet", "--branch", release, url, target]) !== 0) fail(`Couldn't clone ${url}.${access}`)
 }
-
-console.log(`
+const restart = `It's a fresh copy, so you can delete ${folder} and start again.`
+
+if (flat) {
+  // Setting up needs no dependencies: install once, in the project as it ends up.
+  console.log("")
+  if (run("node", ["scripts/dashral.mjs", "init", "--layout", "flat", ...rest], target) !== 0) fail(`The setup stopped. ${restart}`)
+  // The project's own history, from its first commit.
+  rmSync(join(target, ".git"), { recursive: true, force: true })
+  run("git", ["init", "--quiet", "-b", "main"], target)
+  if (own.install) {
+    console.log("\nInstalling the dependencies…")
+    if (run("pnpm", ["install"], target) !== 0) fail(`pnpm install stopped. Fix what it says, then run \`pnpm install\` in ${folder}.`)
+  }
+  run("git", ["add", "-A"], target, true)
+  const committed = run("git", ["commit", "--quiet", "-m", "Initial commit from create-dashral"], target, true) === 0
+  console.log(`
+Your dashboard is in ${folder}:
+  cd ${folder}${own.install ? "" : "\n  pnpm install"}
+  pnpm dev${committed ? "" : "\n\n(Git has no name and email here yet, so nothing was committed: commit when you're ready.)"}`)
+} else {
+  // A tag checks out without a branch: start yours, so your commits have one.
+  if (run("git", ["switch", "--quiet", "-c", "main"], target) !== 0) fail("Couldn't start the main branch.")
+  if (own.install) {
+    console.log("\nInstalling the dependencies…")
+    if (run("pnpm", ["install"], target) !== 0) fail(`pnpm install stopped. Fix what it says, then in ${folder}: pnpm install && pnpm dashral init`)
+  }
+  console.log("")
+  if (run("node", ["scripts/dashral.mjs", "init", ...rest], target) !== 0) {
+    fail(`The setup stopped. ${restart} Or fix what it says and run \`pnpm dashral init\` in it.`)
+  }
+  console.log(`
 Your dashboard is in ${folder}:
   cd ${folder}${own.install ? "" : "\n  pnpm install"}
   pnpm dev`)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dashral",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Start a new Dashral admin dashboard (Next.js, React, Tailwind CSS) in one command.",
   "license": "MIT",
   "type": "module",