create-textmode 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 humanbydefinition
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# create-textmode.js (✿◠‿◠)
+
+<div align="center">
+
+A zero-friction scaffolder for `textmode.js`.
+
+| [![JavaScript](https://img.shields.io/badge/JavaScript-323330?logo=javascript&logoColor=F7DF1E)](https://developer.mozilla.org/docs/Web/JavaScript) [![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)](https://vitejs.dev/) | [![textmode.js](https://img.shields.io/badge/github-textmode.js-111827?logo=github&logoColor=white)](https://github.com/humanbydefinition/textmode.js) [![docs](https://img.shields.io/badge/docs-vitepress-646cff?logo=vitepress&logoColor=white)](https://code.textmode.art/) [![Discord](https://img.shields.io/discord/1357070706181017691?color=5865F2&label=Discord&logo=discord&logoColor=white)](https://discord.gg/sjrw8QXNks) | [![ko-fi](https://shields.io/badge/ko--fi-donate-ff5f5f?logo=ko-fi)](https://ko-fi.com/V7V8JG2FY) [![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?logo=GitHub-Sponsors&logoColor=#EA4AAA)](https://github.com/sponsors/humanbydefinition) |
+|:-------------|:-------------|:-------------|
+
+</div>
+
+`create-textmode.js` is a command-line tool to quickly scaffold new projects using `textmode.js` with sensible defaults and minimal friction.
+
+Just run the CLI via `npm create textmode@latest` or your package manager's equivalent command, answer a few prompts, and you're ready to start building!
+
+> [!NOTE]
+> The CLI is still fresh out of the oven, so please report any issues or feature requests on the GitHub repo!
+
+## Requirements
+
+- Node.js 18+ *(per `engines`)*
+- One of: npm, pnpm, yarn, or bun on your PATH
+
+## Quick start *(interactive)*
+
+```bash
+npm create textmode@latest
+# or
+pnpm create textmode@latest
+# or
+yarn create textmode
+# ...
+```
+
+The CLI will prompt for project name, template, textmode.js version, installing dependencies, and starting the dev server.
+
+## Non-interactive examples
+
+```bash
+# TypeScript template, pin textmode.js, auto-install, do not run dev server
+npm create textmode@latest my-textmode-app -- --template vanilla-ts --textmode-version 0.7.1 --install --no-run
+
+# JavaScript template with pnpm, skip install and run
+pnpm create textmode@latest demo -- --template vanilla-js --pm pnpm --no-install --no-run
+```
+
+## Options
+
+- `--template <name>`: choose a template *(prompts if omitted)*
+- `--name <projectName>` or first positional arg: directory/package name *(default suggestion if omitted)*
+- `--textmode-version <ver>`: pin textmode.js *(prompts from fetched stable versions; defaults to `latest`)*
+- `--pm <npm|pnpm|yarn|bun>`: force a package manager *(auto-detected otherwise)*
+- `--install` / `--no-install`: install dependencies after scaffold *(prompts if neither is provided)*
+- `--run` / `--no-run`: start the dev server after install *(prompts if neither is provided)*
+- `--force`: allow using a non-empty directory without prompting
+- `--help`: show usage
+- `--version`: show the CLI version
+
+## Templates
+
+| Template | Stack | Tooling |
+|:---------|:------|:--------|
+| `vanilla-js` | Vite + JavaScript + `textmode.js` | ESLint *(JS rules)*, Prettier, `.gitignore` |
+| `vanilla-ts` | Vite + TypeScript + `textmode.js` | `tsconfig`, ESLint *(@typescript-eslint)*, Prettier, `.gitignore`, `typecheck` |
+
+Adding new templates? Follow the same table format so details stay consistent and easy to scan.
+
+## Local development
+
+```bash
+npm install
+npm test          # vitest
+npm run test:verbose
+
+# Run CLI directly (no npm-create shim); no "--" needed
+node bin/index.js demo --template vanilla-js --pm pnpm --no-install --no-run
+# or
+node bin/index.js
+# ...
+```

package/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import kleur from 'kleur';
+import { run } from '../src/cli.js';
+
+run().catch((err) => {
+  console.error(kleur.red(err.stack || err.message || err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "create-textmode",
+  "version": "1.0.3",
+  "description": "Scaffold textmode.js projects with zero friction",
+  "type": "module",
+  "bin": {
+    "create-textmode": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "textmode",
+    "textmode.js",
+    "create",
+    "scaffold",
+    "template"
+  ],
+  "author": "humanbydefinition",
+  "license": "MIT",
+  "homepage": "https://github.com/humanbydefinition/create-textmode.js#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/humanbydefinition/create-textmode.js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/humanbydefinition/create-textmode.js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:verbose": "vitest run --reporter=verbose"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "boxen": "^7.1.1",
+    "kleur": "^4.1.5",
+    "minimist": "^1.2.8",
+    "unique-names-generator": "^4.7.1"
+  },
+  "devDependencies": {
+    "textmode.js": "^0.7.1",
+    "vitest": "^4.0.15"
+  }
+}

package/src/args.js

@@ -0,0 +1,30 @@
+import minimist from 'minimist';
+import kleur from 'kleur';
+import { templates } from './constants.js';
+import { printUsage } from './usage.js';
+
+export function parseArgv(rawArgs) {
+  return minimist(rawArgs, {
+    alias: {
+      h: 'help',
+      t: 'template',
+      n: 'name',
+      f: 'force',
+      v: 'version',
+      tv: 'textmode-version'
+    },
+    string: ['template', 'name', 'pm', 'textmode-version'],
+    boolean: ['help', 'force', 'version', 'install', 'run', 'no-install', 'no-run'],
+    default: { install: null, run: null }
+  });
+}
+
+export function ensureKnownTemplate(name) {
+  if (!name) return;
+  const found = templates.find((t) => t.name === name);
+  if (found) return;
+
+  console.error(kleur.red(`Unknown template: ${name}`));
+  printUsage();
+  process.exit(1);
+}

package/src/banner.js

@@ -0,0 +1,57 @@
+import kleur from 'kleur';
+import { HEADER } from './constants.js';
+
+const SPLIT_FLAP_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#@%&/\\<>[]=+*';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function randomFlapChar() {
+  const idx = Math.floor(Math.random() * SPLIT_FLAP_CHARS.length);
+  return SPLIT_FLAP_CHARS[idx];
+}
+
+async function animateSplitFlap(lines, { flips = 16, frameDelay = 32, columnStagger = 6 } = {}) {
+  const canAnimate = process.stdout.isTTY && process.env.CI !== 'true';
+  if (!canAnimate) {
+    console.log(kleur.cyan(lines.join('\n')));
+    return;
+  }
+
+  const lineCount = lines.length;
+  const blankFrame = lines.map((line) => line.replace(/[^\s]/g, ' '));
+  let firstRender = true;
+
+  const render = (frame) => {
+    if (!firstRender) {
+      process.stdout.write(`\x1b[${lineCount}F`);
+    } else {
+      firstRender = false;
+    }
+    process.stdout.write(frame.join('\n'));
+    process.stdout.write('\n');
+  };
+
+  render(blankFrame);
+
+  for (let flip = 0; flip < flips; flip++) {
+    const frameLines = lines.map((line) => {
+      const chars = line.split('').map((ch, idx) => {
+        if (ch === ' ') return ' ';
+        const shouldSettle = flip >= flips - 2 || flip > Math.floor(idx / columnStagger);
+        return shouldSettle ? ch : randomFlapChar();
+      });
+      return kleur.cyan(chars.join(''));
+    });
+    render(frameLines);
+    await sleep(frameDelay + flip * 6);
+  }
+
+  render(lines.map((line) => kleur.cyan(line)));
+}
+
+export async function printHeader() {
+  const headerLines = HEADER.trim().split('\n');
+  console.log('');
+  await animateSplitFlap(headerLines);
+  console.log('');
+}

package/src/cli.js

@@ -0,0 +1,154 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { readFile } from 'fs/promises';
+import kleur from 'kleur';
+import { intro, outro, spinner, log } from '@clack/prompts';
+import { detectPackageManager, pmCommands } from './packageManager.js';
+import { isEmptyDir, pathExists, scaffoldTemplate } from './fs-utils.js';
+import { runCommand, runCommandLogged } from './runCommand.js';
+import { printUsage } from './usage.js';
+import { templates } from './constants.js';
+import {
+  promptInstall,
+  promptProjectName,
+  promptRun,
+  promptTemplate,
+  promptOverwrite,
+  suggestProjectName,
+  promptTextmodeVersion
+} from './prompts.js';
+import { printHeader } from './banner.js';
+import { parseArgv, ensureKnownTemplate } from './args.js';
+import { resolveTextmodeVersion } from './textmodeVersion.js';
+import { printSummary } from './summary.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function run() {
+  await printHeader();
+  intro(
+    kleur.cyan('Welcome to textmode.js - let’s scaffold a new project! ✿  ') +
+      kleur.gray('(Press Ctrl+C at any time to cancel.)')
+  );
+
+  const argv = parseArgv(process.argv.slice(2));
+
+  if (argv.help) {
+    printUsage();
+    return;
+  }
+
+  if (argv.version) {
+    const pkgJson = JSON.parse(await readFile(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    console.log(pkgJson.version);
+    return;
+  }
+
+  // --- Gather project info ---
+  let projectName = argv._[0] || argv.name;
+  if (!projectName) {
+    const suggested = suggestProjectName();
+    projectName = await promptProjectName(suggested);
+  }
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  ensureKnownTemplate(argv.template);
+  let templateName = argv.template;
+  if (!templateName) {
+    templateName = await promptTemplate();
+  }
+
+  const template = templates.find((t) => t.name === templateName);
+  const templateDir = path.join(__dirname, '..', 'templates', template.dir);
+
+  // --- Resolve textmode.js version ---
+  const requestedTextmodeVersion = argv['textmode-version'];
+  const { textmodeVersion } = await resolveTextmodeVersion(
+    requestedTextmodeVersion,
+    promptTextmodeVersion
+  );
+
+  // --- Pre-scaffold checks ---
+  const pm = argv.pm || detectPackageManager();
+  const pmCmds = pmCommands(pm);
+
+  const targetExists = await pathExists(targetDir);
+  if (targetExists && !(await isEmptyDir(targetDir)) && !argv.force) {
+    const overwrite = await promptOverwrite(targetDir);
+    if (!overwrite) {
+      outro('Aborted.');
+      return;
+    }
+  }
+
+  // --- Scaffold project ---
+  const scaffoldSpin = spinner();
+  scaffoldSpin.start('Scaffolding project...');
+  await scaffoldTemplate({ templateDir, targetDir, projectName, textmodeVersion });
+  scaffoldSpin.stop('Scaffold complete.');
+
+  // --- Install dependencies ---
+  let installDone = false;
+
+  const userInstall = argv.install;
+  const userNoInstall = argv['no-install'];
+  const hasInstallFlag = userInstall !== null || userNoInstall === true;
+  let doInstall = userInstall === true;
+
+  if (!hasInstallFlag) {
+    doInstall = await promptInstall(pm);
+  }
+
+  if (doInstall) {
+    const installSpin = spinner();
+    installSpin.start(`Installing dependencies with ${pm}...`);
+    let seenOutput = false;
+    try {
+      await runCommandLogged(pm, pmCmds.install, targetDir, (line) => {
+        if (!seenOutput) {
+          installSpin.stop(`Installing dependencies with ${pm}...`);
+          seenOutput = true;
+        }
+        console.log(`│  ${line}`);
+      });
+      installDone = true;
+      if (!seenOutput) installSpin.stop('Dependencies installed.');
+      log.success('Dependencies installed.');
+    } catch (err) {
+      installSpin.stop('Dependency installation failed.');
+      log.error(`Dependency installation failed: ${err.message || err}`);
+    }
+  }
+
+  // --- Run dev server ---
+  let runDone = false;
+
+  if (installDone) {
+    const userRun = argv.run;
+    const userNoRun = argv['no-run'];
+    const hasRunFlag = userRun !== null || userNoRun === true;
+    let doRun = userRun === true;
+
+    if (!hasRunFlag) {
+      doRun = await promptRun(pm);
+    }
+
+    if (doRun) {
+      log.step('Starting dev server...');
+      try {
+        await runCommand(pm, pmCmds.runDev, targetDir);
+        runDone = true;
+      } catch (err) {
+        log.error(err.message || String(err));
+      }
+    }
+  }
+
+  // --- Summary ---
+  log.message('');
+  printSummary({ projectName, pm, pmCmds, installDone, runDone });
+  outro(kleur.green('Enjoy textmode.js! ツ'));
+}
+
+export default run;

package/src/constants.js

@@ -0,0 +1,19 @@
+export const HEADER = `
+████████╗███████╗██╗  ██╗████████╗███╗   ███╗ ██████╗ ██████╗ ███████╗        ██╗███████╗
+╚══██╔══╝██╔════╝╚██╗██╔╝╚══██╔══╝████╗ ████║██╔═══██╗██╔══██╗██╔════╝        ██║██╔════╝
+   ██║   █████╗   ╚███╔╝    ██║   ██╔████╔██║██║   ██║██║  ██║█████╗          ██║███████╗
+   ██║   ██╔══╝   ██╔██╗    ██║   ██║╚██╔╝██║██║   ██║██║  ██║██╔══╝     ██   ██║╚════██║
+   ██║   ███████╗██╔╝ ██╗   ██║   ██║ ╚═╝ ██║╚██████╔╝██████╔╝███████╗██╗╚█████╔╝███████║
+   ╚═╝   ╚══════╝╚═╝  ╚═╝   ╚═╝   ╚═╝     ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚════╝ ╚══════╝                                                     
+`;
+
+export const templates = [
+  { name: 'vanilla-js', label: 'Vanilla JavaScript (vite)', dir: 'vanilla-js' },
+  { name: 'vanilla-ts', label: 'Vanilla TypeScript (vite)', dir: 'vanilla-ts' },
+];
+
+// File name patterns considered text for placeholder replacement.
+export const TEXT_FILE_REGEX = /\.(json|js|jsx|ts|tsx|vue|md|html|txt|cjs|mjs)$/i;
+
+// Entries ignored when deciding if a directory is empty enough to reuse.
+export const IGNORED_DIR_ENTRIES = ['.git', '.gitkeep'];

package/src/fs-utils.js

@@ -0,0 +1,85 @@
+import path from 'path';
+import { cp, mkdir, readdir, readFile, rename, stat, writeFile } from 'fs/promises';
+import { IGNORED_DIR_ENTRIES, TEXT_FILE_REGEX } from './constants.js';
+
+export async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+export async function isEmptyDir(dir) {
+  try {
+    const entries = await readdir(dir);
+    const filtered = entries.filter((name) => !IGNORED_DIR_ENTRIES.includes(name));
+    return filtered.length === 0;
+  } catch (err) {
+    if (err.code === 'ENOENT') return true;
+    throw err;
+  }
+}
+
+async function replacePlaceholders(root, projectName) {
+  const entries = await readdir(root, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+
+    if (entry.isDirectory()) {
+      await replacePlaceholders(fullPath, projectName);
+      continue;
+    }
+
+    if (entry.name === '_gitignore') {
+      await rename(fullPath, path.join(root, '.gitignore'));
+      continue;
+    }
+
+    if (!TEXT_FILE_REGEX.test(entry.name)) continue;
+
+    const data = await readFile(fullPath, 'utf8');
+    if (!data.includes('{{name}}')) continue;
+
+    const next = data.replace(/{{name}}/g, projectName);
+    await writeFile(fullPath, next, 'utf8');
+  }
+}
+
+export async function setPackageName(targetDir, projectName) {
+  const pkgPath = path.join(targetDir, 'package.json');
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    pkg.name = projectName;
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+  } catch (err) {
+    // If no package.json exists, ignore; templates without package.json are allowed.
+  }
+}
+
+export async function setTextmodeVersion(targetDir, textmodeVersion) {
+  if (!textmodeVersion) return;
+  const pkgPath = path.join(targetDir, 'package.json');
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    if (!pkg.dependencies) pkg.dependencies = {};
+    if (pkg.dependencies['textmode.js'] !== undefined) {
+      pkg.dependencies['textmode.js'] = textmodeVersion;
+      await writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+    }
+  } catch (err) {
+    // Ignore templates without package.json or invalid JSON.
+  }
+}
+
+export async function scaffoldTemplate({ templateDir, targetDir, projectName, textmodeVersion }) {
+  await mkdir(targetDir, { recursive: true });
+  await cp(templateDir, targetDir, { recursive: true, force: true });
+
+  await replacePlaceholders(targetDir, projectName);
+  await setPackageName(targetDir, projectName);
+  await setTextmodeVersion(targetDir, textmodeVersion);
+}

package/src/packageManager.js

@@ -0,0 +1,18 @@
+export function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent || '';
+  if (ua.includes('pnpm')) return 'pnpm';
+  if (ua.includes('yarn')) return 'yarn';
+  if (ua.includes('bun')) return 'bun';
+  return 'npm';
+}
+
+export function pmCommands(pm) {
+  switch (pm) {
+    case 'pnpm':
+    case 'yarn':
+    case 'bun':
+      return { install: ['install'], runDev: ['run', 'dev'] };
+    default:
+      return { install: ['install'], runDev: ['run', 'dev'] };
+  }
+}

package/src/prompts.js

@@ -0,0 +1,90 @@
+import path from 'path';
+import { confirm, isCancel, cancel, select, text } from '@clack/prompts';
+import kleur from 'kleur';
+import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
+import { templates } from './constants.js';
+
+/**
+ * Handle user cancellation uniformly.
+ * @param {unknown} value - The value returned from a prompt.
+ * @returns {boolean} True if the user cancelled.
+ */
+export function handleCancel(value) {
+  if (isCancel(value)) {
+    cancel('Operation cancelled.');
+    process.exit(0);
+  }
+  return false;
+}
+
+export async function promptTemplate() {
+  const choice = await select({
+    message: `${kleur.cyan('Select a template')} ${kleur.gray('(↑↓ move, ↵ confirm)')}`,
+    options: templates.map((t) => ({ value: t.name, label: t.label })),
+    initialValue: templates[0].name
+  });
+
+  handleCancel(choice);
+  return choice;
+}
+
+export function suggestProjectName() {
+  return uniqueNamesGenerator({
+    dictionaries: [adjectives, colors, animals],
+    separator: '-',
+    length: 3
+  });
+}
+
+export async function promptProjectName(defaultName) {
+  const name = await text({
+    message: `${kleur.cyan('Project name')} ${kleur.gray('(enter to accept default)')}`,
+    initialValue: defaultName,
+    validate: (value) => (value && value.trim().length > 0 ? undefined : 'Name cannot be empty')
+  });
+
+  handleCancel(name);
+  return name.trim();
+}
+
+export async function promptOverwrite(targetDir) {
+  const response = await confirm({
+    message: `Directory ${path.basename(targetDir)} is not empty. Continue?`,
+    initialValue: false
+  });
+
+  handleCancel(response);
+  return response;
+}
+
+export async function promptInstall(pm) {
+  const decision = await confirm({
+    message: `Install dependencies with ${pm}?`,
+    initialValue: true
+  });
+
+  handleCancel(decision);
+  return decision;
+}
+
+export async function promptRun(pm) {
+  const decision = await confirm({
+    message: `Run dev server now with ${pm}?`,
+    initialValue: false
+  });
+
+  handleCancel(decision);
+  return decision;
+}
+
+export async function promptTextmodeVersion(options) {
+  const choice = await select({
+    message: `${kleur.cyan('Select textmode.js version')} ${kleur.gray('(latest recommended)')}`,
+    options,
+    initialValue: options[0]?.value,
+    maxItems: 5
+  });
+
+  handleCancel(choice);
+  return choice;
+}

package/src/runCommand.js

@@ -0,0 +1,46 @@
+import { spawn } from 'child_process';
+import readline from 'readline';
+
+export function runCommand(cmd, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32'
+    });
+
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+    });
+
+    child.on('error', reject);
+  });
+}
+
+export function runCommandLogged(cmd, args, cwd, onLine) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      shell: process.platform === 'win32'
+    });
+
+    const forward = (stream) => {
+      if (!stream) return;
+      const rl = readline.createInterface({ input: stream });
+      rl.on('line', (line) => onLine(line));
+      rl.on('error', () => {});
+    };
+
+    forward(child.stdout);
+    forward(child.stderr);
+
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+    });
+
+    child.on('error', reject);
+  });
+}

package/src/summary.js

@@ -0,0 +1,33 @@
+import kleur from 'kleur';
+import boxen from 'boxen';
+
+export function printSummary({ projectName, pm, pmCmds, installDone, runDone }) {
+  const installCmd = `${pm} ${pmCmds.install.join(' ')}`;
+  const runCmd = `${pm} ${pmCmds.runDev.join(' ')}`;
+
+  const steps = [
+    `cd ${projectName}`,
+    installDone ? `✓ already ran ${installCmd}` : installCmd,
+    runDone ? `✓ dev server is running (${runCmd})` : runCmd
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  const infoLines = [
+    '',
+    '',
+    kleur.bold().cyan('Helpful links:'),
+    `${kleur.cyan('  Documentation:')} https://code.textmode.art`,
+    `${kleur.cyan('  Community:')} https://discord.gg/sjrw8QXNks`,
+    `${kleur.cyan('  CLI issues:')} https://github.com/humanbydefinition/create-textmode.js/issues`
+  ].join('\n');
+
+  const boxed = boxen(`${kleur.bold().cyan('Next steps:')}\n${steps}${infoLines}`, {
+    padding: { top: 0, bottom: 0, left: 2, right: 2 },
+    margin: { top: 0, bottom: 0 },
+    borderStyle: 'round',
+    borderColor: 'cyan'
+  });
+
+  console.log(boxed);
+}

package/src/textmodeVersion.js

@@ -0,0 +1,45 @@
+import { spinner, log } from '@clack/prompts';
+import { getTextmodeVersions } from './versions.js';
+
+export async function resolveTextmodeVersion(requestedTextmodeVersion, promptTextmodeVersion) {
+  let textmodeVersion = 'latest';
+  let stableVersions = [];
+
+  const versionSpinner = spinner();
+  versionSpinner.start('Fetching textmode.js versions...');
+  try {
+    stableVersions = await getTextmodeVersions();
+    if (stableVersions.length === 0) throw new Error('No versions found');
+    versionSpinner.stop('Fetched textmode.js versions.');
+  } catch (err) {
+    versionSpinner.stop('Could not fetch versions.');
+    log.warn('Using latest version as fallback.');
+    stableVersions = [];
+    textmodeVersion = 'latest';
+  }
+
+  const latestVersion = stableVersions[0];
+  const availableOptions = [
+    {
+      value: 'latest',
+      label: latestVersion ? `latest (${latestVersion})` : 'latest (recommended)'
+    },
+    ...stableVersions.slice(1).map((v) => ({ value: v, label: v }))
+  ];
+
+  if (requestedTextmodeVersion) {
+    const found = availableOptions.find((opt) => opt.value === requestedTextmodeVersion);
+    if (found) {
+      textmodeVersion = requestedTextmodeVersion;
+    } else if (stableVersions.includes(requestedTextmodeVersion)) {
+      textmodeVersion = requestedTextmodeVersion;
+    } else {
+      log.warn(`Requested textmode.js@${requestedTextmodeVersion} not found; using latest instead.`);
+      textmodeVersion = 'latest';
+    }
+  } else if (stableVersions.length > 0) {
+    textmodeVersion = await promptTextmodeVersion(availableOptions);
+  }
+
+  return { textmodeVersion, stableVersions, availableOptions };
+}

package/src/usage.js

@@ -0,0 +1,18 @@
+import { templates } from './constants.js';
+
+export function printUsage() {
+  const list = templates.map((t) => `  - ${t.name}`).join('\n');
+
+  console.log(`Usage: npm create textmode@latest [project-name] -- [options]\n`);
+  console.log('Options:');
+  console.log('  --template <name>          Choose a template');
+  console.log('  --name <name>              Project directory name (alias: positional arg)');
+  console.log('  --pm <npm|pnpm|yarn|bun>   Force package manager (auto-detected if omitted)');
+  console.log('  --textmode-version <ver>   Pin textmode.js version (default: latest, prompts if omitted)');
+  console.log('  --install / --no-install   Install dependencies after scaffold');
+  console.log('  --run / --no-run           Run dev server after install');
+  console.log('  --force                    Allow using a non-empty directory');
+  console.log('  --help                     Show this help');
+  console.log('  --version                  Show CLI version');
+  console.log('\nTemplates:\n' + list);
+}

package/src/versions.js

@@ -0,0 +1,52 @@
+import https from 'https';
+
+let cachedVersions = null;
+
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (res) => {
+        let data = '';
+        res.on('data', (chunk) => {
+          data += chunk;
+        });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data));
+          } catch (err) {
+            reject(err);
+          }
+        });
+      })
+      .on('error', reject);
+  });
+}
+
+export function isStable(version) {
+  // Exclude prerelease tags like -beta, -rc, etc.
+  return !version.includes('-');
+}
+
+export function compareSemverDesc(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const va = pa[i] || 0;
+    const vb = pb[i] || 0;
+    if (va > vb) return -1;
+    if (va < vb) return 1;
+  }
+  return 0;
+}
+
+export async function getTextmodeVersions(limit = 20) {
+  if (cachedVersions) return cachedVersions.slice(0, limit);
+
+  const data = await fetchJson('https://registry.npmjs.org/textmode.js');
+  const versions = Object.keys(data.versions || {})
+    .filter(isStable)
+    .sort(compareSemverDesc);
+
+  cachedVersions = versions;
+  return versions.slice(0, limit);
+}

package/templates/vanilla-js/.eslintrc.json

@@ -0,0 +1,13 @@
+{
+  "root": true,
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "extends": ["eslint:recommended", "prettier"],
+  "ignorePatterns": ["dist/", "node_modules/"]
+}

package/templates/vanilla-js/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "semi": true
+}

package/templates/vanilla-js/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/vanilla-js/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+
+    <style>
+        html,
+        body {
+            margin: 0;
+            padding: 0;
+        }
+
+        canvas {
+            display: block;
+        }
+    </style>
+</head>
+
+<body>
+    <div id="app"></div>
+    <script type="module" src="/src/sketch.js"></script>
+</body>
+
+</html>

package/templates/vanilla-js/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "format": "prettier --write \"src/**/*.{js,ts}\"",
+    "format:check": "prettier --check \"src/**/*.{js,ts}\"",
+    "lint": "eslint src --ext .js",
+    "lint:fix": "eslint src --ext .js --fix"
+  },
+  "dependencies": {
+    "textmode.js": "latest"
+  },
+  "devDependencies": {
+    "prettier": "^3.7.4",
+    "vite": "^7.2.7",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8"
+  }
+}

package/templates/vanilla-js/src/sketch.js

@@ -0,0 +1,28 @@
+import { textmode } from 'textmode.js';
+
+const tm = textmode.create({ width: window.innerWidth, height: window.innerHeight });
+
+tm.draw(() => {
+    tm.background(0);
+
+    const halfCols = (tm.grid.cols / 2) + 1;
+    const halfRows = (tm.grid.rows / 2) + 1;
+
+    for (let y = -halfRows; y < halfRows; y++) {
+        for (let x = -halfCols; x < halfCols; x++) {
+            const dist = Math.sqrt(x * x + y * y);
+            const wave = Math.sin(dist * 0.2 - tm.frameCount * 0.1);
+
+            tm.push();
+            tm.translate(x, y, 0);
+            tm.char(wave > 0.5 ? '▓' : wave > 0 ? '▒' : '░');
+            tm.charColor(0, 150 + wave * 100, 255);
+            tm.point();
+            tm.pop();
+        }
+    }
+});
+
+tm.windowResized(() => {
+    tm.resizeCanvas(window.innerWidth, window.innerHeight);
+});

package/templates/vanilla-js/vite.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  server: {
+    open: true
+  }
+});

package/templates/vanilla-ts/.eslintrc.json

@@ -0,0 +1,19 @@
+{
+  "root": true,
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "ignorePatterns": ["dist/", "node_modules/"]
+}

package/templates/vanilla-ts/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "semi": true
+}

package/templates/vanilla-ts/_gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

package/templates/vanilla-ts/index.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{name}}</title>
+
+    <style>
+        html,
+        body {
+            margin: 0;
+            padding: 0;
+        }
+
+        canvas {
+            display: block;
+        }
+    </style>
+
+</head>
+
+<body>
+    <div id="app"></div>
+    <script type="module" src="/src/sketch.ts"></script>
+</body>
+
+</html>

package/templates/vanilla-ts/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "format": "prettier --write \"src/**/*.{js,ts}\"",
+    "format:check": "prettier --check \"src/**/*.{js,ts}\"",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "textmode.js": "latest"
+  },
+  "devDependencies": {
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.7",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "@types/node": "^24.10.2",
+    "@typescript-eslint/parser": "^8.49.0",
+    "@typescript-eslint/eslint-plugin": "^8.49.0"
+  }
+}

package/templates/vanilla-ts/src/sketch.ts

@@ -0,0 +1,28 @@
+import { textmode } from 'textmode.js';
+
+const tm = textmode.create({ width: window.innerWidth, height: window.innerHeight });
+
+tm.draw(() => {
+  tm.background(0);
+
+  const halfCols = tm.grid.cols / 2 + 1;
+  const halfRows = tm.grid.rows / 2 + 1;
+
+  for (let y = -halfRows; y < halfRows; y++) {
+    for (let x = -halfCols; x < halfCols; x++) {
+      const dist = Math.sqrt(x * x + y * y);
+      const wave = Math.sin(dist * 0.2 - tm.frameCount * 0.1);
+
+      tm.push();
+      tm.translate(x, y, 0);
+      tm.char(wave > 0.5 ? '▓' : wave > 0 ? '▒' : '░');
+      tm.charColor(0, 150 + wave * 100, 255);
+      tm.point();
+      tm.pop();
+    }
+  }
+});
+
+tm.windowResized(() => {
+  tm.resizeCanvas(window.innerWidth, window.innerHeight);
+});

package/templates/vanilla-ts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "jsx": "preserve",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"],
+  "references": []
+}

package/templates/vanilla-ts/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  server: {
+    open: true
+  }
+});