create-koppajs 1.0.1 → 1.2.0

package/bin/create-koppajs.js

@@ -1,175 +1,346 @@
-#!/usr/bin/env node
-
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync } from "node:fs";
-import { basename, join, dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const TEMPLATE_DIR = join(__dirname, "..", "template");
-const CLI_PKG = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-
-// ── Args ────────────────────────────────────────────────────────────
-
-function parseArgs(argv) {
-  const raw = argv.slice(2);
-  return {
-    help: raw.includes("--help") || raw.includes("-h"),
-    version: raw.includes("--version") || raw.includes("-v"),
-    projectName: raw.find((a) => !a.startsWith("-")) || null,
-  };
-}
-
-// ── Help / Version ──────────────────────────────────────────────────
-
-function printHelp() {
-  console.log(`
-  create-koppajs v${CLI_PKG.version}
-
-  Scaffold a new KoppaJS project.
-
-  Usage:
-    pnpm create koppajs [project-name]
-    npm create koppajs [project-name]
-    npx create-koppajs [project-name]
-
-  Options:
-    --help, -h       Show this help message
-    --version, -v    Show version number
-
-  Example:
-    pnpm create koppajs my-app
-`);
-}
-
-function printVersion() {
-  console.log(CLI_PKG.version);
-}
-
-// ── Prompt ──────────────────────────────────────────────────────────
-
-function promptProjectName() {
-  return new Promise((res, rej) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let answered = false;
-    rl.on("close", () => {
-      if (!answered) rej(new Error("Input closed before a project name was provided."));
-    });
-    rl.question("  Project name: ", (answer) => {
-      answered = true;
-      rl.close();
-      res(answer.trim());
-    });
-  });
-}
-
-// ── Validation ──────────────────────────────────────────────────────
-
-function validateProjectName(name) {
-  if (!name) {
-    console.error("\n  Error: Project name cannot be empty.\n");
-    process.exit(1);
-  }
-  if (name === "." || name === "..") {
-    console.error(`\n  Error: Invalid project name "${name}".\n`);
-    process.exit(1);
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    console.error("\n  Error: Project name must not contain path separators.\n");
-    process.exit(1);
-  }
-}
-
-// ── Target directory ────────────────────────────────────────────────
-
-function ensureTargetDir(targetPath) {
-  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
-    console.error(`\n  Error: Directory "${basename(targetPath)}" already exists and is not empty.\n`);
-    process.exit(1);
-  }
-  mkdirSync(targetPath, { recursive: true });
-}
-
-// ── Copy ────────────────────────────────────────────────────────────
-
-// npm excludes .gitignore from published packages — ship as _gitignore
-// and rename during scaffolding (same approach as create-vite).
-const RENAME_FILES = { _gitignore: ".gitignore" };
-
-function copyDirRecursive(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    const srcPath = join(src, entry);
-    const destName = RENAME_FILES[entry] || entry;
-    const destPath = join(dest, destName);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-// ── Patch package.json ──────────────────────────────────────────────
-
-function patchPackageJson(destDir, projectName) {
-  const pkgPath = join(destDir, "package.json");
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  pkg.name = projectName;
-  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-}
-
-// ── Patch README ────────────────────────────────────────────────────
-
-function patchReadme(destDir, projectName) {
-  const readmePath = join(destDir, "README.md");
-  let content = readFileSync(readmePath, "utf-8");
-  content = content.replaceAll("__PROJECT_NAME__", projectName);
-  writeFileSync(readmePath, content);
-}
-
-// ── Final output ────────────────────────────────────────────────────
-
-function printNextSteps(projectName) {
-  console.log("  Done! Next steps:\n");
-  console.log(`    cd ${projectName}`);
-  console.log("    pnpm install");
-  console.log("    pnpm dev\n");
-}
-
-// ── Main ────────────────────────────────────────────────────────────
-
-async function main() {
-  const { help, version, projectName: argName } = parseArgs(process.argv);
-
-  if (help) {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (version) {
-    printVersion();
-    process.exit(0);
-  }
-
-  const projectName = argName || (await promptProjectName());
-
-  validateProjectName(projectName);
-
-  const targetDir = resolve(process.cwd(), projectName);
-
-  ensureTargetDir(targetDir);
-
-  console.log(`\n  Scaffolding KoppaJS project: ${projectName}\n`);
-
-  copyDirRecursive(TEMPLATE_DIR, targetDir);
-  patchPackageJson(targetDir, projectName);
-  patchReadme(targetDir, projectName);
-  printNextSteps(projectName);
-}
-
-main().catch((err) => {
-  console.error(`\n  Error: ${err.message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync } from "node:fs";
+import { basename, join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const TEMPLATE_DIR = join(__dirname, "..", "template");
+export const TEMPLATE_OVERLAY_DIRS = Object.freeze({
+  minimal: null,
+  router: join(__dirname, "..", "template-overlays", "router"),
+});
+export const DEFAULT_TEMPLATE = "minimal";
+const CLI_PKG = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+// ── Args ────────────────────────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const raw = argv.slice(2);
+  const parsed = {
+    help: raw.includes("--help") || raw.includes("-h"),
+    version: raw.includes("--version") || raw.includes("-v"),
+    projectName: null,
+    templateName: null,
+    optionError: null,
+  };
+
+  const setTemplateName = (templateName) => {
+    if (!templateName) {
+      parsed.optionError = "Option --template requires a value.";
+      return false;
+    }
+
+    if (parsed.templateName && parsed.templateName !== templateName) {
+      parsed.optionError = "Choose either --router or one --template value.";
+      return false;
+    }
+
+    parsed.templateName = templateName;
+    return true;
+  };
+
+  for (let index = 0; index < raw.length; index++) {
+    const arg = raw[index];
+
+    if (arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v") {
+      continue;
+    }
+
+    if (arg === "--router") {
+      if (!setTemplateName("router")) {
+        break;
+      }
+      continue;
+    }
+
+    if (arg === "--template" || arg === "-t") {
+      const templateName = raw[index + 1];
+
+      if (!templateName || templateName.startsWith("-")) {
+        parsed.optionError = "Option --template requires a value.";
+        break;
+      }
+
+      if (!setTemplateName(templateName)) {
+        break;
+      }
+
+      index++;
+      continue;
+    }
+
+    if (arg.startsWith("--template=")) {
+      if (!setTemplateName(arg.slice("--template=".length))) {
+        break;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("-t=")) {
+      if (!setTemplateName(arg.slice("-t=".length))) {
+        break;
+      }
+      continue;
+    }
+
+    if (!arg.startsWith("-") && parsed.projectName === null) {
+      parsed.projectName = arg;
+    }
+  }
+
+  return parsed;
+}
+
+// ── Help / Version ──────────────────────────────────────────────────
+
+export function printHelp() {
+  console.log(`
+  create-koppajs v${CLI_PKG.version}
+
+  Scaffold a new KoppaJS project.
+
+  Usage:
+    pnpm create koppajs [project-name]
+    npm create koppajs [project-name]
+    npx create-koppajs [project-name]
+
+  Options:
+    --help, -h                Show this help message
+    --version, -v             Show version number
+    --template, -t <name>     Starter template: minimal | router
+    --router                  Shortcut for --template router
+
+  Example:
+    pnpm create koppajs my-app
+    pnpm create koppajs my-app --template router
+`);
+}
+
+export function printVersion() {
+  console.log(CLI_PKG.version);
+}
+
+// ── Prompt ──────────────────────────────────────────────────────────
+
+function promptLine(question, closeErrorMessage, input = process.stdin, output = process.stdout) {
+  return new Promise((res, rej) => {
+    const rl = createInterface({ input, output });
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) rej(new Error(closeErrorMessage));
+    });
+    rl.question(question, (answer) => {
+      answered = true;
+      rl.close();
+      res(answer.trim());
+    });
+  });
+}
+
+export function promptProjectName(input = process.stdin, output = process.stdout) {
+  return promptLine(
+    "  Project name: ",
+    "Input closed before a project name was provided.",
+    input,
+    output,
+  );
+}
+
+export async function promptStarterTemplate(input = process.stdin, output = process.stdout) {
+  const answer = (await promptLine(
+    `  Starter template (minimal/router) [${DEFAULT_TEMPLATE}]: `,
+    "Input closed before a starter template was provided.",
+    input,
+    output,
+  )).toLowerCase();
+
+  if (answer === "" || answer === "m") {
+    return DEFAULT_TEMPLATE;
+  }
+
+  if (answer === "r") {
+    return "router";
+  }
+
+  return answer;
+}
+
+// ── Validation ──────────────────────────────────────────────────────
+
+export function validateProjectName(name) {
+  if (!name) {
+    throw new Error("Project name cannot be empty.");
+  }
+  if (name === "." || name === "..") {
+    throw new Error(`Invalid project name "${name}".`);
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    throw new Error("Project name must not contain path separators.");
+  }
+}
+
+export function validateStarterTemplate(templateName) {
+  if (Object.hasOwn(TEMPLATE_OVERLAY_DIRS, templateName)) {
+    return;
+  }
+
+  throw new Error(
+    `Unknown starter template "${templateName}". Supported templates: ${Object.keys(TEMPLATE_OVERLAY_DIRS).join(", ")}.`,
+  );
+}
+
+// ── Target directory ────────────────────────────────────────────────
+
+export function ensureTargetDir(targetPath) {
+  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
+    throw new Error(`Directory "${basename(targetPath)}" already exists and is not empty.`);
+  }
+  mkdirSync(targetPath, { recursive: true });
+}
+
+// ── Copy ────────────────────────────────────────────────────────────
+
+// npm excludes .gitignore from published packages — ship as _gitignore
+// and rename during scaffolding (same approach as create-vite).
+const RENAME_FILES = {
+  _editorconfig: ".editorconfig",
+  _gitattributes: ".gitattributes",
+  _github: ".github",
+  _gitignore: ".gitignore",
+  _husky: ".husky",
+  _npmrc: ".npmrc",
+  _prettierignore: ".prettierignore",
+};
+
+export function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destName = RENAME_FILES[entry] || entry;
+    const destPath = join(dest, destName);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+export function copyStarterTemplate(templateName, dest) {
+  copyDirRecursive(TEMPLATE_DIR, dest);
+
+  const overlayDir = TEMPLATE_OVERLAY_DIRS[templateName];
+
+  if (overlayDir) {
+    copyDirRecursive(overlayDir, dest);
+  }
+}
+
+// ── Patch package.json ──────────────────────────────────────────────
+
+export function patchPackageJson(destDir, projectName) {
+  const pkgPath = join(destDir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  pkg.name = projectName;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+// ── Patch README ────────────────────────────────────────────────────
+
+function patchTextFile(destDir, relativePath, projectName) {
+  const filePath = join(destDir, relativePath);
+  let content = readFileSync(filePath, "utf-8");
+  content = content.replaceAll("__PROJECT_NAME__", projectName);
+  writeFileSync(filePath, content);
+}
+
+export function patchReadme(destDir, projectName) {
+  patchTextFile(destDir, "README.md", projectName);
+}
+
+export function patchChangelog(destDir, projectName) {
+  patchTextFile(destDir, "CHANGELOG.md", projectName);
+}
+
+export function patchReleaseNotes(destDir, projectName) {
+  patchTextFile(destDir, "RELEASE.md", projectName);
+}
+
+// ── Final output ────────────────────────────────────────────────────
+
+export function printNextSteps(projectName) {
+  console.log("  Done! Next steps:\n");
+  console.log(`    cd ${projectName}`);
+  console.log("    pnpm install");
+  console.log("    pnpm dev\n");
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+export function shouldPromptForTemplateSelection(input = process.stdin, output = process.stdout) {
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+export async function runCli(
+  argv = process.argv,
+  cwd = process.cwd(),
+  io = { input: process.stdin, output: process.stdout },
+) {
+  const { help, version, projectName: argName, templateName: argTemplateName, optionError } =
+    parseArgs(argv);
+
+  if (help) {
+    printHelp();
+    return 0;
+  }
+
+  if (version) {
+    printVersion();
+    return 0;
+  }
+
+  if (optionError) {
+    throw new Error(optionError);
+  }
+
+  const projectName = argName || (await promptProjectName(io.input, io.output));
+
+  validateProjectName(projectName);
+
+  const templateName =
+    argTemplateName ||
+    (shouldPromptForTemplateSelection(io.input, io.output)
+      ? await promptStarterTemplate(io.input, io.output)
+      : DEFAULT_TEMPLATE);
+
+  validateStarterTemplate(templateName);
+
+  const targetDir = resolve(cwd, projectName);
+
+  ensureTargetDir(targetDir);
+
+  console.log(`\n  Scaffolding KoppaJS project: ${projectName} (${templateName} starter)\n`);
+
+  copyStarterTemplate(templateName, targetDir);
+  patchPackageJson(targetDir, projectName);
+  patchReadme(targetDir, projectName);
+  patchChangelog(targetDir, projectName);
+  patchReleaseNotes(targetDir, projectName);
+  printNextSteps(projectName);
+
+  return 0;
+}
+
+function isDirectExecution() {
+  return Boolean(process.argv[1]) && resolve(process.argv[1]) === __filename;
+}
+
+if (isDirectExecution()) {
+  runCli().catch((err) => {
+    console.error(`\n  Error: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,34 +1,55 @@
-{
-  "name": "create-koppajs",
-  "version": "1.0.1",
-  "private": false,
-  "type": "module",
-  "description": "Scaffold a new KoppaJS project in seconds.",
-  "bin": {
-    "create-koppajs": "./bin/create-koppajs.js"
-  },
-  "files": [
-    "bin",
-    "template",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "lint": "node -c bin/create-koppajs.js",
-    "test": "node ./bin/create-koppajs.js --help",
-    "smoke": "node scripts/smoke-test.mjs"
-  },
-  "author": "Bastian Bensch",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/koppajs/create-koppajs"
-  },
-  "homepage": "https://github.com/koppajs/create-koppajs#readme",
-  "bugs": {
-    "url": "https://github.com/koppajs/create-koppajs/issues"
-  }
-}
+{
+  "name": "create-koppajs",
+  "version": "1.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Scaffold a new KoppaJS project in seconds.",
+  "bin": {
+    "create-koppajs": "./bin/create-koppajs.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "template-overlays",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=10"
+  },
+  "scripts": {
+    "check:meta": "node scripts/check-meta-layer.mjs",
+    "lint": "node scripts/lint.mjs",
+    "format:check": "node scripts/format-check.mjs",
+    "check:cli": "node ./bin/create-koppajs.js --help && node ./bin/create-koppajs.js --version",
+    "test:unit": "node scripts/run-unit-tests.mjs",
+    "test:watch": "node scripts/run-unit-tests.mjs --watch",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "test:template-build": "node scripts/template-build-test.mjs",
+    "test": "npm run test:unit && npm run test:smoke",
+    "pack:dry-run": "npm pack --dry-run",
+    "check": "npm run check:meta && npm run lint && npm run format:check && npm run check:cli && npm test && npm run pack:dry-run",
+    "release:check": "npm run check && npm run test:template-build",
+    "prepare": "husky",
+    "clean": "node scripts/clean.mjs"
+  },
+  "author": "Bastian Bensch",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koppajs/create-koppajs"
+  },
+  "homepage": "https://github.com/koppajs/create-koppajs#readme",
+  "bugs": {
+    "url": "https://github.com/koppajs/create-koppajs/issues"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.3"
+  }
+}

package/template/AI_CONSTITUTION.md

@@ -0,0 +1,50 @@
+# AI Constitution
+
+## Purpose
+
+This repository is a KoppaJS starter scaffolded from the official minimal Vite
+and TypeScript baseline. Its job is to stay small, understandable, runnable,
+and trustworthy.
+
+## Core principles
+
+- Optimize for clarity over feature breadth.
+- Keep the bootstrap path obvious: one HTML shell, one TypeScript entrypoint, one root view.
+- Prefer published npm packages over local `file:` links in this repository.
+- Keep the starter close to real production usage, but do not turn it into a framework showcase.
+- Treat the meta layer as part of the product. If architecture or workflow changes, the documentation must change in the same update.
+
+## Architectural philosophy
+
+- `index.html` is the static document shell only.
+- `src/main.ts` is the only bootstrap module and the only place that registers root-level components with `Core.take(...)`.
+- `.kpa` files are the primary unit for simple UI composition, local state, and component-scoped styling.
+- When logic becomes reusable, branch-heavy, or worth unit testing, extract it from `.kpa` blocks into `.ts` modules.
+- Global CSS stays minimal. Component visuals belong inside component-local CSS blocks unless they are true application-wide primitives.
+
+## Collaboration rules for humans and AI
+
+1. Read [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md), [ARCHITECTURE.md](./ARCHITECTURE.md), [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md), [TESTING_STRATEGY.md](./TESTING_STRATEGY.md), and any relevant spec or ADR before editing code.
+2. Follow `spec -> quality plan -> implementation -> documentation` for any non-trivial change.
+3. Do not silently change public component tags, bootstrap flow, dependency sourcing, or the starter's setup instructions.
+4. Prefer existing repository patterns over inventing new structure.
+5. If a change affects architecture, module boundaries, build tooling, testing, or contributor workflow, update the meta layer in the same change.
+6. Record durable architectural decisions in `docs/adr/`.
+7. If code and documentation disagree, resolve the mismatch before merging further changes.
+
+## Change triggers
+
+- New subsystem or folder: update [ARCHITECTURE.md](./ARCHITECTURE.md) and [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+- New enduring technical decision: add or update an ADR in [docs/adr](./docs/adr).
+- New development convention: update [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md).
+- New quality gate or test level: update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md).
+- New user-visible capability: create or update a spec in [docs/specs](./docs/specs).
+
+## Definition of done
+
+A change is not complete until:
+
+- the code or docs are aligned with the actual repository state,
+- applicable specs and ADRs are updated,
+- required quality checks have run,
+- contributor-facing guidance still matches the project.