create-volt 0.1.0 → 0.3.0

package/README.md

@@ -27,12 +27,31 @@ Edit `public/app.js` and save — the page hot-reloads itself.
 
 ## Options
 
-| Flag             | Effect                                                  |
-| ---------------- | ------------------------------------------------------- |
-| `--skip-install` | Don't run the install step (scaffold files only)        |
-| `--force`        | Scaffold into an existing non-empty directory           |
-| `-h`, `--help`   | Show help                                               |
-| `-v`, `--version`| Print the create-volt version                           |
+| Flag              | Effect                                                  |
+| ----------------- | ------------------------------------------------------- |
+| `--port <number>` | Dev port for the app (default: derived from today's date)|
+| `--skip-install`  | Don't run the install step (scaffold files only)        |
+| `--no-git`        | Don't initialize a git repository                       |
+| `--dry-run`       | Show what would be created without writing anything      |
+| `--force`         | Scaffold into an existing non-empty directory           |
+| `-h`, `--help`    | Show help                                               |
+| `-v`, `--version` | Print the create-volt version                           |
+
+By default the new project is initialized as a git repository with one initial
+commit (skip with `--no-git`).
+
+### Dev port
+
+Each app's dev port is baked into its `server.js`. By default it's derived from
+**today's date** — two-digit year + month + two-digit day (e.g. `2026-06-28` →
+`26628`) — so apps created on different days never collide. Scaffolding more than
+one app on the same day? Give them distinct ports with `--port`:
+
+```bash
+npm create volt@latest api-app -- --port 26630
+```
+
+The runtime `PORT` env var still overrides it at launch.
 
 The installer auto-detects whichever package manager invoked it
 (npm / pnpm / yarn / bun) and uses it for `install`.

package/index.js

@@ -36,7 +36,10 @@ ${bold("Usage")}
   npx create-volt <project-directory> [options]
 
 ${bold("Options")}
+  --port <number>  Dev port for the app (default: derived from today's date)
   --skip-install   Don't run the package manager install step
+  --no-git         Don't initialize a git repository
+  --dry-run        Show what would be created without writing anything
   --force          Scaffold into an existing non-empty directory
   -h, --help       Show this help
   -v, --version    Show the create-volt version
@@ -46,10 +49,18 @@ ${bold("Example")}
   cd my-app && npm run dev
 `;
 
-// --- arg parsing ---
+// --- arg parsing (supports `--port <n>` and `--port=<n>`) ---
 const argv = process.argv.slice(2);
-const flags = new Set(argv.filter((a) => a.startsWith("-")));
-const positionals = argv.filter((a) => !a.startsWith("-"));
+const flags = new Set();
+const positionals = [];
+let portArg = null;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--port") portArg = argv[++i];
+  else if (a.startsWith("--port=")) portArg = a.slice("--port=".length);
+  else if (a.startsWith("-")) flags.add(a);
+  else positionals.push(a);
+}
 
 if (flags.has("-h") || flags.has("--help")) {
   console.log(HELP);
@@ -62,6 +73,30 @@ if (flags.has("-v") || flags.has("--version")) {
 
 const skipInstall = flags.has("--skip-install");
 const force = flags.has("--force");
+const dryRun = flags.has("--dry-run");
+const noGit = flags.has("--no-git");
+
+// Resolve the dev port: --port wins, else derive it from today's date as
+// two-digit-year + month (no leading zero) + two-digit-day (house convention),
+// so apps scaffolded on different days don't collide on the same port.
+function datePort(d) {
+  const yy = String(d.getFullYear()).slice(-2);
+  const mm = String(d.getMonth() + 1);
+  const dd = String(d.getDate()).padStart(2, "0");
+  return Number(`${yy}${mm}${dd}`);
+}
+let port;
+if (portArg != null) {
+  port = Number(portArg);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    die(`Invalid --port "${portArg}" — use a whole number between 1 and 65535.`);
+  }
+} else {
+  port = datePort(new Date());
+  if (port > 65535) {
+    die(`The date-derived port (${port}) is above 65535 — pass --port <1-65535>.`);
+  }
+}
 
 const rawName = positionals[0];
 if (!rawName) die(`Please specify a project directory:\n    ${cyan("npm create volt@latest")} ${green("<project-directory>")}`);
@@ -79,16 +114,43 @@ const targetDir = path.resolve(process.cwd(), projectName);
 const appName = path.basename(targetDir);
 const templateDir = path.join(__dirname, "template");
 
+// List every file in the template, relative to its root (for dry-run preview).
+function listTemplateFiles(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listTemplateFiles(full, base));
+    else out.push(path.relative(base, full));
+  }
+  return out;
+}
+
 // --- target directory checks ---
 if (fs.existsSync(targetDir)) {
   const existing = fs.readdirSync(targetDir).filter((f) => f !== ".git");
   if (existing.length && !force) {
     die(`Directory ${green(projectName)} already exists and is not empty.\n  Pass ${cyan("--force")} to scaffold into it anyway.`);
   }
-} else {
-  fs.mkdirSync(targetDir, { recursive: true });
 }
 
+// --- dry run: print the plan and exit without writing anything ---
+if (dryRun) {
+  console.log(`\n${bold("⚡ Dry run")} — would create a Volt app in ${cyan(targetDir)}\n`);
+  console.log("Would write:");
+  for (const f of listTemplateFiles(templateDir).sort()) {
+    // the shipped "gitignore" is renamed to ".gitignore" on scaffold
+    console.log("  " + dim(f === "gitignore" ? ".gitignore" : f));
+  }
+  console.log("");
+  console.log(dim(`Would ${skipInstall ? "skip dependency install" : "install dependencies"}.`));
+  console.log(dim(`Would ${noGit ? "skip git init" : "initialize a git repository with an initial commit"}.`));
+  console.log(dim(`Would set the dev port to ${port}.`));
+  console.log(`\n${green("✔")} Dry run complete — nothing was written.\n`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
+
 console.log(`\n${bold("⚡ Creating a new Volt app in")} ${cyan(targetDir)}\n`);
 
 // --- copy the template tree (recursive, cross-platform) ---
@@ -107,6 +169,17 @@ const appPkg = JSON.parse(fs.readFileSync(appPkgPath, "utf8"));
 appPkg.name = appName;
 fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2) + "\n");
 
+// --- stamp the chosen dev port into server.js + README ---
+const serverPath = path.join(targetDir, "server.js");
+fs.writeFileSync(
+  serverPath,
+  fs.readFileSync(serverPath, "utf8").replace(/(Number\(process\.env\.PORT\)\s*\|\|\s*)\d+/, `$1${port}`),
+);
+const appReadme = path.join(targetDir, "README.md");
+if (fs.existsSync(appReadme)) {
+  fs.writeFileSync(appReadme, fs.readFileSync(appReadme, "utf8").replace(/localhost:\d+/g, `localhost:${port}`));
+}
+
 const created = [
   "public/volt.js   — the Volt library (no build step)",
   "public/app.js    — your app (Counter + Todos demo)",
@@ -143,6 +216,31 @@ if (!skipInstall) {
   }
 }
 
+// --- initialize a git repository (unless skipped or already inside one) ---
+if (!noGit) {
+  const git = (gitArgs) =>
+    spawnSync("git", gitArgs, {
+      cwd: targetDir,
+      stdio: "ignore",
+      shell: process.platform === "win32",
+    });
+  const gitAvailable = git(["--version"]).status === 0;
+  const insideRepo = gitAvailable && git(["rev-parse", "--is-inside-work-tree"]).status === 0;
+  if (gitAvailable && !insideRepo) {
+    const initOk = git(["init", "-b", "main"]).status === 0 || git(["init"]).status === 0;
+    if (initOk) {
+      git(["add", "-A"]);
+      const committed = git(["commit", "-m", "Initial commit from create-volt"]).status === 0;
+      console.log(
+        green("✔") +
+          (committed
+            ? " Initialized a git repository (1 commit)\n"
+            : " Initialized a git repository (commit skipped — set git user.name/email)\n"),
+      );
+    }
+  }
+}
+
 // --- next steps ---
 const runCmd = pm === "npm" ? "npm run dev" : `${pm} dev`;
 const installCmd = pm === "yarn" ? "yarn" : `${pm} install`;
@@ -150,4 +248,4 @@ console.log(`\n${green("✔")} ${bold("Done!")} Next steps:\n`);
 console.log(`  ${cyan("cd")} ${projectName}`);
 if (!installed) console.log(`  ${cyan(installCmd)}`);
 console.log(`  ${cyan(runCmd)}`);
-console.log(`\nThen open ${cyan("http://localhost:26628")} and edit ${bold("public/app.js")}.\n`);
+console.log(`\nThen open ${cyan("http://localhost:" + port)} and edit ${bold("public/app.js")}.\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-volt",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scaffold a new Volt app — no-build, signals-based UI with Socket.io hot reload.",
   "type": "module",
   "bin": {