create-textmode 1.0.6 → 1.0.7

package/README.md

@@ -1,86 +1,120 @@
-# create-textmode (✿◠‿◠)
-
-<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
-
-All templates ship with Vite, `textmode.js`, Prettier, ESLint, and a `.gitignore`. TypeScript variants add `tsconfig` and a `typecheck` script. Below are the extras that differ by template:
-
-| Template | Flavor | Extras |
-|:---------|:-------|:-------|
-| `vanilla-js` | JavaScript | Base starter sketch |
-| `vanilla-ts` | TypeScript | Base starter sketch + TS config |
-| `vanilla-js-fxhash` | JavaScript + fx(hash) | Bundled `fxhash.min.js`, starter sketch using `$fx` API and features |
-| `vanilla-ts-fxhash` | TypeScript + fx(hash) | Bundled `fxhash.min.js`, `$fx` typings, starter sketch using `$fx` API and features |
-| `vanilla-js-tweakpane` | JavaScript + Tweakpane | UI controls wired with Tweakpane |
-| `vanilla-ts-tweakpane` | TypeScript + Tweakpane | UI controls wired with Tweakpane + TS config |
-
-Adding new templates? Keep the shared tooling note above and only list what’s unique in the table.
-
-## 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
-# ...
-```
+# create-textmode (✿◠‿◠)
+
+<div align="center">
+
+<img alt="create-textmode — scaffold textmode.js with zero friction" src=".github/assets/readme-og.png" />
+
+| [![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` 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!
+
+## Features
+
+- **One-command scaffolding** - Start a new project with `npm create textmode@latest` or your package manager's equivalent
+- **Interactive prompts** - Choose project name, template, textmode.js version, official add-ons, dependency installation, and dev server startup
+- **JavaScript and TypeScript templates** - Vanilla starters plus Tweakpane-controlled UI variants
+- **Package-manager aware** - Auto-detect npm, pnpm, yarn, or bun
+- **Non-interactive flags** - Full CLI options for scripts and CI
+- **Sensible defaults** - Vite, `textmode.js`, Prettier, ESLint, and a `.gitignore`; TypeScript variants add `tsconfig` and a `typecheck` script
+
+## Try it online first
+
+Open [editor.textmode.art](https://editor.textmode.art/), a browser-based live-coding environment for the complete official `textmode.js` ecosystem, to try textmode.js before or alongside scaffolding; sketches run as you edit, with no local toolchain required.
+
+## Requirements
+
+- Node.js 18+ *(per `engines`)*
+- One of: npm, pnpm, yarn, or bun on your PATH
+
+## Quick start
+
+```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, official add-ons, 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.17.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
+
+# Pre-install the synth and export add-ons and wire their plugins into the starter sketch
+npm create textmode@latest audio-art -- --template vanilla-js --addons synth,export --install --no-run
+```
+
+## Options
+
+- `--template <name>`: choose a template *(prompts if omitted)*
+- `--addons <name1,name2,...>`: pre-install official textmode.js add-ons and wire their plugins into the starter sketch *(prompts via multi-select 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 >= 0.17.1; 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
+
+All templates ship with Vite, `textmode.js`, Prettier, ESLint, and a `.gitignore`. TypeScript variants add `tsconfig` and a `typecheck` script. Below are the extras that differ by template:
+
+| Template | Flavor | Extras |
+|:---------|:-------|:-------|
+| `vanilla-js` | JavaScript | Base starter sketch |
+| `vanilla-ts` | TypeScript | Base starter sketch + TS config |
+| `vanilla-js-tweakpane` | JavaScript + Tweakpane | UI controls wired with Tweakpane |
+| `vanilla-ts-tweakpane` | TypeScript + Tweakpane | UI controls wired with Tweakpane + TS config |
+
+Adding new templates? Keep the shared tooling note above and only list what’s unique in the table.
+
+## Add-ons
+
+All official textmode.js add-on libraries are supported. When selected, the CLI adds the package (always at its latest version) to your `dependencies` and registers its plugin on the `textmode.create({ ... })` call in the starter sketch.
+
+| Id | Package | Latest plugin export |
+|:---|:--------|:---------------------|
+| `export` | `textmode.export.js` | `ExportPlugin` |
+| `synth` | `textmode.synth.js` | `SynthPlugin` |
+| `figlet` | `textmode.figlet.js` | `FigletPlugin` |
+| `filters` | `textmode.filters.js` | `FiltersPlugin` |
+
+## Local development
+
+```bash
+npm install        # also installs git hooks (commitlint, lint-staged, pre-push protection)
+npm run check      # lint + test
+npm run lint       # node --check syntax gate
+npm test           # vitest (run once)
+
+# 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
+# ...
+```
+
+## Contributing
+
+Thank you for considering contributing to this project! (✿◠‿◠)
+
+Please read the [Contributing Guide](https://code.textmode.art/docs/contributing/code) to get started, and follow the [Code of Conduct](./CODE_OF_CONDUCT.md) in all community spaces.
+
+## License
+
+`create-textmode` is licensed under the [AGPL-3.0 License](./LICENSE).

package/bin/index.js

@@ -1,8 +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);
-});
+#!/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

@@ -1,54 +1,70 @@
-{
-  "name": "create-textmode",
-  "version": "1.0.6",
-  "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#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/humanbydefinition/create-textmode.git"
-  },
-  "bugs": {
-    "url": "https://github.com/humanbydefinition/create-textmode/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"
-  }
-}
+{
+  "name": "create-textmode",
+  "version": "1.0.7",
+  "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": "AGPL-3.0",
+  "homepage": "https://github.com/humanbydefinition/create-textmode#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/humanbydefinition/create-textmode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/humanbydefinition/create-textmode/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:verbose": "vitest run --reporter=verbose",
+    "lint": "node --check bin/index.js && node --check src/*.js && node --check tests/*.js",
+    "check": "npm run lint && npm run test",
+    "prepare": "install-git-hooks"
+  },
+  "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": {
+    "@commitlint/cli": "^21.2.1",
+    "@textmode/commitlint-config": "^0.1.1",
+    "@textmode/tooling-scripts": "^0.5.0",
+    "lint-staged": "^17.0.8",
+    "textmode.js": "^0.8.1",
+    "vitest": "^4.1.10"
+  },
+  "commitlint": {
+    "extends": [
+      "@textmode/commitlint-config"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs}": "node --check"
+  }
+}

package/src/args.js

@@ -1,30 +1,57 @@
-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);
-}
+import minimist from 'minimist';
+import kleur from 'kleur';
+import { addons, 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', 'addons'],
+    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);
+}
+
+export function ensureKnownAddons(names) {
+  if (!names) return;
+  const requested = names.split(',').map((s) => s.trim()).filter(Boolean);
+  const unknown = requested.filter((name) => !addons.find((a) => a.name === name));
+  if (unknown.length === 0) return;
+
+  console.error(kleur.red(`Unknown add-on(s): ${unknown.join(', ')}`));
+  console.error(kleur.gray(`Valid add-ons: ${addons.map((a) => a.name).join(', ')}`));
+  printUsage();
+  process.exit(1);
+}
+
+export function parseAddons(names) {
+  if (!names) return [];
+
+  const uniqueNames = [...new Set(
+    names
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  )];
+
+  return uniqueNames
+    .map((name) => addons.find((a) => a.name === name))
+    .filter(Boolean);
+}

package/src/banner.js

@@ -1,57 +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('');
-}
+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('');
+}