create-dashral 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# create-dashral
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start a new [Dashral](https://dashral.com) admin dashboard (Next.js, React, TypeScript, Tailwind CSS) in one command:
+
+```bash
+npx create-dashral my-app
+cd my-app
+pnpm dev
+```
+
+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:
+
+```bash
+npx create-dashral my-app --template inset --pages blank --languages en --name "Acme" --primary indigo
+```
+
+The theme customizer's **Copy setup command** in the [live demo](https://demo.dashral.com) writes these flags for you.
+
+| Option | |
+| --- | --- |
+| `--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.
+
+MIT licensed.

package/index.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// `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, readFileSync, rmSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { argv, exit, platform, versions } from "node:process"
+
+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]
+
+  Starts a new Next.js dashboard in <folder> 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:
+  --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         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
+  --name "Your App"  --primary  --light  --dark  --card  --radius  --font  --yes
+  Pro: --apps all|crm,kanban,…  --samples keep|remove
+
+The theme customizer's "Copy setup command" at https://demo.dashral.com writes these flags for you.
+Docs: https://dashral.com/docs/installation`
+
+// ── Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** This script's own flags, and the rest passed to `dashral init` as they were typed. */
+function parseArgs(args) {
+  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++) {
+    const arg = args[i]
+    const [key, inline] = arg.startsWith("--") ? arg.slice(2).split(/=(.*)/s) : [null]
+    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 === "layout") fail("Use --monorepo for the repository's layout; the project is flat without it.")
+    else if (key === null && folder === null) folder = arg
+    else rest.push(arg)
+  }
+  return { folder, own, rest }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+function fail(message) {
+  console.error(`\n✖ ${message}`)
+  exit(1)
+}
+
+/** Runs a command in the terminal (its output and questions shown as they come); its exit code, or null. */
+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
+}
+
+/** A command's output, or null when it can't run. */
+function output(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8", shell: platform === "win32" })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+const versionOf = (tag) => tag.slice(1).split(".").map(Number)
+const newer = (a, b) => {
+  const [x, y] = [versionOf(a), versionOf(b)]
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i]
+  return 0
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+const { folder, own, rest } = parseArgs(argv.slice(2))
+if (own.help || !folder) {
+  console.log(help)
+  exit(own.help ? 0 : 1)
+}
+
+if (Number(versions.node.split(".")[0]) < 20) fail(`Dashral needs Node.js 20 or newer (this is ${versions.node}).`)
+if (output("git", ["--version"]) === null) fail("Git wasn't found. Install it from https://git-scm.com and run this again.")
+if (own.install && output("pnpm", ["--version"]) === null) {
+  fail("pnpm wasn't found. Turn it on with `corepack enable pnpm` (or `npm install -g pnpm`) and run this again.")
+}
+
+const target = resolve(folder)
+if (existsSync(target) && readdirSync(target).length) fail(`${folder} isn't empty. Pick a new folder.`)
+
+const url = own.from ?? (own.pro ? repos.pro : repos.free)
+const access = own.pro ? " Check that your GitHub account has access to Dashral Pro (accept the invitation GitHub emailed you)." : ""
+
+// The release: the newest version tag, or the one --release names.
+console.log(`Looking for the releases of ${url}…`)
+const listed = output("git", ["ls-remote", "--tags", "--refs", url, "v*"])
+if (listed === null) fail(`Couldn't reach ${url}.${access}`)
+const tags = listed
+  .split("\n")
+  .map((line) => line.split("refs/tags/")[1])
+  .filter((tag) => /^v\d+\.\d+\.\d+$/.test(tag ?? ""))
+  .sort(newer)
+let release = tags.at(-1)
+if (own.release) {
+  release = own.release.startsWith("v") ? own.release : `v${own.release}`
+  if (!tags.includes(release)) fail(`There's no release ${release}. The releases: ${tags.join(", ") || "none yet"}.`)
+}
+if (!release) fail(`${url} has no releases yet.`)
+
+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
+}
+
+// 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}`)
+}
+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,33 @@
 {
   "name": "create-dashral",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Start a new Dashral admin dashboard (Next.js, React, Tailwind CSS) in one command.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-dashral": "index.mjs"
+  },
+  "files": [
+    "index.mjs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "homepage": "https://dashral.com/docs/installation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasralgana/dashral.git",
+    "directory": "packages/create-dashral"
+  },
+  "bugs": "https://github.com/hasralgana/dashral/issues",
+  "keywords": [
+    "dashral",
+    "dashboard",
+    "admin",
+    "template",
+    "nextjs",
+    "react",
+    "tailwindcss",
+    "shadcn"
+  ]
+}