boilercraft 1.0.0

package/cli/ui.js

@@ -0,0 +1,356 @@
+const readline = require('readline');
+
+// Terminal UI primitives: colors, banner, boxes, menus, prompts, spinner.
+// No dependencies; falls back to plain numbered prompts when not in a TTY.
+
+const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const trueColor = useColor && (process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit' ||
+  !!process.env.WT_SESSION || process.env.TERM_PROGRAM === 'vscode' || process.platform === 'win32');
+
+const paint = code => s => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const c = {
+  bold: paint(1), dim: paint(2), italic: paint(3),
+  red: paint(31), green: paint(32), yellow: paint(33), blue: paint(34), magenta: paint(35), cyan: paint(36), gray: paint(90)
+};
+
+function rgb(r, g, b, s) {
+  if (!useColor) return s;
+  return trueColor ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m` : c.cyan(s);
+}
+
+function swatch(hex) {
+  if (!useColor) return '';
+  const [r, g, b] = [1, 3, 5].map(i => parseInt(hex.slice(i, i + 2), 16));
+  return trueColor ? `\x1b[48;2;${r};${g};${b}m  \x1b[0m` : '';
+}
+
+const stripAnsi = s => String(s).replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+const width = s => [...stripAnsi(s)].length;
+const columns = () => process.stdout.columns || 80;
+
+// Truncates to a visible width, keeping ANSI styling intact.
+function truncate(s, max) {
+  if (width(s) <= max) return s;
+  let out = '';
+  let visible = 0;
+  for (const part of String(s).split(/(\x1b\[[0-9;?]*[A-Za-z])/)) {
+    if (/^\x1b\[/.test(part)) {
+      out += part;
+      continue;
+    }
+    for (const ch of part) {
+      if (visible >= max - 1) return out + '…' + (useColor ? '\x1b[0m' : '');
+      out += ch;
+      visible++;
+    }
+  }
+  return out;
+}
+
+// Brand gradient: cyan → blue → violet.
+const STOPS = [[34, 211, 238], [59, 130, 246], [139, 92, 246]];
+function gradientAt(t) {
+  const seg = t < 0.5 ? 0 : 1;
+  const local = t < 0.5 ? t * 2 : (t - 0.5) * 2;
+  const [a, b] = [STOPS[seg], STOPS[seg + 1]];
+  return a.map((v, i) => Math.round(v + (b[i] - v) * local));
+}
+function gradient(text) {
+  const chars = [...text];
+  return chars.map((ch, i) => (ch === ' ' ? ch : rgb(...gradientAt(chars.length > 1 ? i / (chars.length - 1) : 0), ch))).join('');
+}
+
+// "ANSI Shadow" glyphs for the banner.
+const GLYPHS = {
+  B: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██████╔╝', '╚═════╝ '],
+  O: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+  I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+  L: ['██╗     ', '██║     ', '██║     ', '██║     ', '███████╗', '╚══════╝'],
+  E: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '███████╗', '╚══════╝'],
+  R: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██║  ██║', '╚═╝  ╚═╝'],
+  C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+  A: [' █████╗ ', '██╔══██╗', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+  F: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '██║     ', '╚═╝     '],
+  T: ['████████╗', '╚══██╔══╝', '   ██║   ', '   ██║   ', '   ██║   ', '   ╚═╝   ']
+};
+
+function banner({ version, tagline, author }) {
+  const word = 'BOILERCRAFT';
+  const rows = GLYPHS.B.map((_, r) => [...word].map(ch => GLYPHS[ch][r]).join(''));
+  const artWidth = width(rows[0]);
+  const out = [''];
+
+  if (columns() >= artWidth + 4) {
+    for (const row of rows) out.push('  ' + gradient(row));
+  } else {
+    out.push('  ' + c.bold(gradient('◆ B O I L E R C R A F T')));
+  }
+  const byline = `${c.dim('by')} ${c.bold(author)}   ${c.gray('·')}   ${c.dim(`v${version}`)}`;
+  out.push('');
+  out.push(`  ${byline}`);
+  out.push(`  ${c.gray(tagline)}`);
+  out.push('');
+  return out.join('\n');
+}
+
+function box(lines, { title, color = c.cyan, padding = 1 } = {}) {
+  const maxLine = Math.max(20, columns() - 8 - padding * 2);
+  lines = lines.map(l => truncate(l, maxLine));
+  const inner = Math.max(...lines.map(width), title ? width(title) + 2 : 0) + padding * 2;
+  const pad = ' '.repeat(padding);
+  const top = title
+    ? `${color('╭─')} ${c.bold(title)} ${color('─'.repeat(Math.max(0, inner - width(title) - 3)) + '╮')}`
+    : color(`╭${'─'.repeat(inner)}╮`);
+  const body = lines.map(l => `${color('│')}${pad}${l}${' '.repeat(inner - padding * 2 - width(l))}${pad}${color('│')}`);
+  return ['  ' + top, ...body.map(b => '  ' + b), '  ' + color(`╰${'─'.repeat(inner)}╯`)].join('\n');
+}
+
+function divider(label = '') {
+  const w = Math.min(columns() - 4, 72);
+  if (!label) return '  ' + c.gray('─'.repeat(w));
+  return '  ' + c.gray('── ') + c.bold(label) + ' ' + c.gray('─'.repeat(Math.max(0, w - width(label) - 4)));
+}
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+// Buffered line reader for non-TTY input (piped answers), so answers sent
+// ahead of time aren't lost while async work (version lookups) runs.
+let queue;
+function nextLine() {
+  if (!queue) {
+    queue = { lines: [], waiters: [], closed: false };
+    const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    rl.on('line', l => (queue.waiters.length ? queue.waiters.shift()(l) : queue.lines.push(l)));
+    rl.on('close', () => {
+      queue.closed = true;
+      while (queue.waiters.length) queue.waiters.shift()('');
+    });
+  }
+  if (queue.lines.length) return Promise.resolve(queue.lines.shift());
+  if (queue.closed) return Promise.resolve(null);
+  return new Promise(resolve => queue.waiters.push(resolve));
+}
+
+class CancelError extends Error {
+  constructor() {
+    super('Cancelled');
+    this.name = 'CancelError';
+  }
+}
+
+async function input(question, { initial, validate } = {}) {
+  for (;;) {
+    const prompt = `  ${c.cyan('?')} ${c.bold(question)}${initial ? c.gray(` (${initial})`) : ''} ${c.gray('›')} `;
+    let answer;
+    if (isTTY) {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      answer = await new Promise(resolve => {
+        rl.on('SIGINT', () => {
+          rl.close();
+          process.stdout.write('\n');
+          resolve(null);
+        });
+        rl.question(prompt, resolve);
+      });
+      rl.close();
+      if (answer === null) throw new CancelError();
+    } else {
+      process.stdout.write(prompt);
+      answer = await nextLine();
+      if (answer === null) throw new CancelError();
+      process.stdout.write(`${answer}\n`);
+    }
+    const value = answer.trim() || initial || '';
+    const error = validate ? validate(value) : null;
+    if (!error) {
+      if (isTTY) {
+        // Replace the prompt line with a compact answered line.
+        process.stdout.write('\x1b[1A\x1b[2K');
+        console.log(`  ${c.green('✔')} ${c.bold(question)} ${c.gray('·')} ${c.cyan(value)}`);
+      }
+      return value;
+    }
+    console.log(`    ${c.red('✖')} ${c.red(error)}`);
+  }
+}
+
+/**
+ * options: [{ value, label, hint, short, disabled }]
+ * Arrow keys / j k / number keys; Enter selects; Esc or Ctrl+C cancels.
+ */
+async function select(question, options, { initial = 0 } = {}) {
+  const enabled = options.map((o, i) => (o.disabled ? -1 : i)).filter(i => i >= 0);
+  let index = enabled.includes(initial) ? initial : enabled[0];
+  if (!isTTY) return selectPlain(question, options, index);
+
+  return new Promise((resolve, reject) => {
+    const out = process.stdout;
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    out.write('\x1b[?25l');
+
+    const header = truncate(`  ${c.cyan('?')} ${c.bold(question)} ${c.gray('· ↑↓ to move, enter to select')}`, columns() - 1);
+    const lineFor = (o, i) => {
+      const active = i === index;
+      const pointer = active ? c.cyan('❯') : ' ';
+      const label = o.disabled ? c.gray(o.label) : active ? c.cyan(c.bold(o.label)) : o.label;
+      const hint = o.hint ? `  ${c.gray(o.hint)}` : '';
+      // Never wrap: a wrapped line would break the redraw (cursor-up count).
+      const full = `    ${pointer} ${label}${hint}`;
+      const fit = width(full) <= columns() - 1 ? full : truncate(`    ${pointer} ${label}`, columns() - 1);
+      return `\x1b[2K${fit}`;
+    };
+    out.write(header + '\n');
+    const render = first => {
+      if (!first) out.write(`\x1b[${options.length}A`);
+      options.forEach((o, i) => out.write(lineFor(o, i) + '\n'));
+    };
+    render(true);
+
+    const move = step => {
+      const pos = enabled.indexOf(index);
+      index = enabled[(pos + step + enabled.length) % enabled.length];
+    };
+    const finish = () => {
+      process.stdin.removeListener('keypress', onKey);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      out.write(`\x1b[${options.length + 1}A\x1b[0J\x1b[?25h`);
+    };
+    const onKey = (str, key = {}) => {
+      if ((key.ctrl && key.name === 'c') || key.name === 'escape') {
+        finish();
+        return reject(new CancelError());
+      }
+      if (key.name === 'up' || key.name === 'k') move(-1);
+      else if (key.name === 'down' || key.name === 'j' || key.name === 'tab') move(1);
+      else if (/^[1-9]$/.test(str || '') && enabled.includes(+str - 1)) index = +str - 1;
+      else if (key.name === 'return' || key.name === 'enter') {
+        finish();
+        const chosen = options[index];
+        out.write(`  ${c.green('✔')} ${c.bold(question)} ${c.gray('·')} ${c.cyan(chosen.short || stripAnsi(chosen.label).trim())}\n`);
+        return resolve(chosen.value);
+      }
+      render(false);
+    };
+    process.stdin.on('keypress', onKey);
+  });
+}
+
+async function selectPlain(question, options, initial) {
+  console.log(`  ${c.cyan('?')} ${c.bold(question)}`);
+  options.forEach((o, i) => {
+    if (o.disabled) return console.log(c.gray(`     -  ${stripAnsi(o.label)}`));
+    console.log(`    ${String(i + 1).padStart(2)}) ${o.label}${o.hint ? c.gray(`  ${o.hint}`) : ''}`);
+  });
+  for (let attempt = 0; attempt < 5; attempt++) {
+    process.stdout.write(`    ${c.gray(`choose [${initial + 1}]:`)} `);
+    const answer = await nextLine();
+    if (answer === null) throw new CancelError();
+    process.stdout.write(`${answer}\n`);
+    if (!answer.trim()) return options[initial].value;
+    const n = parseInt(answer, 10);
+    if (n >= 1 && n <= options.length && !options[n - 1].disabled) return options[n - 1].value;
+    console.log(`    ${c.red('✖ Invalid choice')}`);
+  }
+  throw new CancelError();
+}
+
+async function confirm(question, initial = true) {
+  return select(question, [
+    { value: true, label: 'Yes', short: 'Yes' },
+    { value: false, label: 'No', short: 'No' }
+  ], { initial: initial ? 0 : 1 });
+}
+
+async function spinner(text, fn) {
+  if (!isTTY) return fn();
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  process.stdout.write('\x1b[?25l');
+  const timer = setInterval(() => process.stdout.write(`\r  ${c.cyan(frames[i++ % frames.length])} ${c.dim(text)}`), 80);
+  try {
+    return await fn();
+  } finally {
+    clearInterval(timer);
+    process.stdout.write('\r\x1b[2K\x1b[?25h');
+  }
+}
+
+/**
+ * Checklist-style progress: each update() ticks off the previous step and
+ * spins on the new one. pause()/resume() let interactive child processes
+ * (installers asking for a password) use the terminal in between.
+ */
+function tasks() {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let current = null;
+  let detail = '';
+  let timer = null;
+  let i = 0;
+  const started = Date.now();
+
+  const draw = () => {
+    const extra = detail ? `  ${c.gray(detail.length > 60 ? detail.slice(0, 57) + '…' : detail)}` : '';
+    process.stdout.write(`\r\x1b[2K  ${c.cyan(frames[i++ % frames.length])} ${current}${extra}`);
+  };
+  const startTimer = () => {
+    if (!isTTY || !current || timer) return;
+    process.stdout.write('\x1b[?25l');
+    timer = setInterval(draw, 80);
+  };
+  const stopTimer = () => {
+    if (!timer) return;
+    clearInterval(timer);
+    timer = null;
+    process.stdout.write('\r\x1b[2K\x1b[?25h');
+  };
+  const complete = mark => {
+    if (!current) return;
+    stopTimer();
+    console.log(`  ${mark} ${current}`);
+    current = null;
+    detail = '';
+  };
+
+  return {
+    update(text) {
+      complete(c.green('✔'));
+      current = text;
+      if (isTTY) startTimer();
+    },
+    detail(text) {
+      detail = text;
+    },
+    warn(text) {
+      const wasRunning = !!timer;
+      stopTimer();
+      log.warn(text);
+      if (wasRunning) startTimer();
+    },
+    pause: stopTimer,
+    resume: startTimer,
+    done() {
+      complete(c.green('✔'));
+      return ((Date.now() - started) / 1000).toFixed(1);
+    },
+    fail() {
+      complete(c.red('✖'));
+    }
+  };
+}
+
+const log = {
+  step: msg => console.log(`  ${c.cyan('›')} ${msg}`),
+  cmd: msg => console.log(`    ${c.gray(msg)}`),
+  ok: msg => console.log(`  ${c.green('✔')} ${msg}`),
+  warn: msg => console.log(`  ${c.yellow('▲')} ${c.yellow(msg)}`),
+  error: msg => console.log(`  ${c.red('✖')} ${c.red(msg)}`),
+  info: msg => console.log(`  ${c.blue('ℹ')} ${msg}`)
+};
+
+module.exports = { truncate, c, isTTY, swatch, gradient, banner, box, divider, input, select, confirm, spinner, tasks, log, width, stripAnsi, CancelError };

package/docs/STACK_ENGINE.md

@@ -0,0 +1,93 @@
+# Stack engine: how versions are handled
+
+BoilerCraft does not ship a hand-written copy of each framework. For Laravel, Next.js, Node + Express and .NET it:
+
+1. **Lists versions live** from the upstream registry (Packagist, npm, the .NET release index), so a new major shows up in the UI without a code change.
+2. **Creates the base project with the framework's official tool** for the chosen version:
+   | Stack | Official creator |
+   |---|---|
+   | Laravel | `composer create-project laravel/laravel:^N.0` |
+   | Next.js | `npx create-next-app@N` |
+   | Node + Express | `npm init` + `npm install express@N` |
+   | .NET | `dotnet new webapi --framework netN.0` + `dotnet new sln` |
+3. **Applies BoilerCraft overlays** on top: auth, DB wiring, theme, landing page. Any step can be limited to certain versions.
+
+Raw PHP has no upstream framework, so it still uses `templates/raw-php-mysql`.
+
+If a required tool is missing, the CLI offers to install it (`services/engine/toolInstaller.js`):
+- .NET SDK and Composer go into `~/.boilercraft/tools`, no admin rights needed.
+- PHP comes from winget, brew or apt/dnf/pacman.
+
+That folder is put first on PATH for every command BoilerCraft runs, and is added to the user PATH for new terminals. If the user declines, generation falls back to the old template generator. A `requires` entry's `tool` field (defaulting to `cmd`) links it to an installer recipe: `php`, `composer` or `dotnet`.
+
+## Where things live
+
+```
+stacks/<id>/stack.json     manifest: versions, required tools, steps
+stacks/<id>/overlays/…     files copied into the project ({{PLACEHOLDERS}} filled in)
+stacks/<id>/snippets/…     text appended or inserted into generated files
+services/engine/           scaffoldEngine.js (runs manifests), versionCatalog.js (live versions)
+```
+
+## A new framework version is released: what to do
+
+**Usually nothing.** It appears in the dropdown labelled *Untested*, and users can already generate with it. The base comes from the official tool, so it matches that version exactly.
+
+To verify it:
+
+1. Generate a project with the new version and run it (the `BOILERCRAFT.md` in the output lists the start commands).
+2. If it works, raise `versions.testedUpTo` in `stack.json`. The *Untested* label goes away and the version becomes the recommended default.
+3. If one of our overlays breaks, add a version-scoped step. Don't edit the existing one:
+
+```json
+{ "when": { "version": "<13" },  "copy": "overlays/auth" },
+{ "when": { "version": ">=13" }, "copy": "overlays/auth-v13" }
+```
+
+Real example, from `stacks/dotnet-core/stack.json`: Swashbuckle 10 needs OpenAPI 2.x, which only .NET 10+ uses. So the package version is a version-scoped var:
+
+```json
+{ "name": "SWASHBUCKLE_VERSION", "when": { "version": "<10" },  "value": "9.*" },
+{ "name": "SWASHBUCKLE_VERSION", "when": { "version": ">=10" }, "value": "10.*" }
+```
+
+To drop an old version, raise `versions.minMajor`.
+
+## Manifest reference
+
+**Stack-specific questions.** A manifest can declare extra choices in `options`. The CLI asks them automatically, and they can be used in `when` and `vars` like any other filter. Next.js uses this for App Router vs Pages Router:
+
+```json
+"options": [{
+  "id": "router", "label": "Router", "default": "app",
+  "choices": [
+    { "value": "app",   "label": "App Router",   "hint": "recommended" },
+    { "value": "pages", "label": "Pages Router", "hint": "classic" }
+  ]
+}]
+```
+```json
+{ "name": "NEXT_ROUTER_FLAG", "when": { "router": "pages" }, "value": "--no-app" },
+{ "when": { "router": "pages" }, "copy": "overlays/router-pages" }
+```
+
+`when` filters (all optional, combined with AND):
+`version` (`"11"`, `">=11"`, `"<11"`, `"10-12"`, `">=9 <11"`), `database`, `styling` (a value or an array), `auth`, `roles`, `platform`.
+
+| Step | What it does |
+|---|---|
+| `run: [cmd, ...args]` | Runs a command in the project folder (`cwd: "parent"` runs it one level up, for creators). `optional: true` turns a failure into a warning. |
+| `copy: "overlays/x"` | Copies a folder into the project and fills in placeholders. |
+| `write: "path", content` | Writes a file. |
+| `append: "path", from/content` | Appends text to a file. |
+| `insertBefore: "path", marker, from/content` | Inserts text before the last occurrence of `marker`. |
+| `replace: "path", find / findRegex, with, skipIfContains` | Replaces the first match. `find` is plain text, so no escaping is needed. Use `findRegex` only when you need a pattern (remember to double backslashes in JSON). `$&` in `with` inserts the matched text. If nothing matches you get a warning, not a failure. |
+| `env: {KEY: value}`, `files` | Sets or uncomments keys in `.env` / `.env.example`. |
+| `json: "path", merge` | Deep-merges into a JSON file (for example `package.json` scripts). |
+| `remove: "path"` | Deletes a file or folder. |
+
+Built-in placeholders: `PROJECT_NAME`, `NAMESPACE`, `APP_TITLE`, `APP_DESC`, `AUTHOR` (HTML-escaped), `APP_TITLE_JS`, `APP_DESC_JS`, `AUTHOR_JS` (JSON strings), `DB_NAME`, `DB_TYPE`, `DATABASE`, `STYLING`, `THEME`, `COLOR_MODE`, `PORT`, `VERSION` (the major), `AUTH_ENABLED`, `LOGO_HTML`, `STYLESHEET_LINK`, `UI_COMPONENTS`, `THEME_CSS`, `THEME_JS`, `DB_ENV`, `DB_ENV_EXAMPLE`, `RANDOM_SECRET`, `RANDOM_PASSWORD`. Stack-specific ones go in the manifest's `vars` array; each entry can have its own `when`.
+
+## Adding a new stack
+
+Create `stacks/<id>/stack.json` with `versions`, `requires` and `steps`. The API (`GET /api/stacks`) and generation pick it up automatically. The only UI change needed is a backend card and a version `<select>` mapped in `VERSION_SELECTS` in `public/index.html`.

package/docs/assets/cli-create.svg

@@ -0,0 +1,52 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="880" height="600" viewBox="0 0 880 600" role="img" aria-label="Creating a Laravel project with BoilerCraft">
+  <defs>
+    <filter id="shadow" x="-5%" y="-5%" width="110%" height="115%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <style>
+    .mono { font-family: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", Menlo, monospace; font-size: 15px; }
+    .dim { fill: #7d8590; }
+    .txt { fill: #e6edf3; }
+    .cyan { fill: #22d3ee; }
+    .green { fill: #3fb950; }
+    .bold { font-weight: 700; }
+  </style>
+
+  <rect x="10" y="6" width="860" height="584" rx="12" fill="#0d1117" stroke="#30363d" filter="url(#shadow)"/>
+  <rect x="10" y="6" width="860" height="38" rx="12" fill="#161b22"/>
+  <rect x="10" y="32" width="860" height="12" fill="#161b22"/>
+  <circle cx="36" cy="25" r="6" fill="#ff5f57"/>
+  <circle cx="56" cy="25" r="6" fill="#febc2e"/>
+  <circle cx="76" cy="25" r="6" fill="#28c840"/>
+  <text x="440" y="30" text-anchor="middle" class="mono dim" font-size="13">Terminal</text>
+
+  <!-- answered questions -->
+  <text x="40" y="82" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Project name</tspan><tspan class="dim"> · </tspan><tspan class="cyan">shop</tspan></text>
+  <text x="40" y="108" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Framework</tspan><tspan class="dim"> · </tspan><tspan class="cyan">Laravel</tspan></text>
+  <text x="40" y="134" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Laravel version</tspan><tspan class="dim"> · </tspan><tspan class="cyan">13.x</tspan></text>
+  <text x="40" y="160" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Frontend</tspan><tspan class="dim"> · </tspan><tspan class="cyan">Vue 3 (Inertia)</tspan></text>
+  <text x="40" y="186" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Authentication</tspan><tspan class="dim"> · </tspan><tspan class="cyan">Included</tspan></text>
+  <text x="40" y="212" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> Theme</tspan><tspan class="dim"> · </tspan><tspan class="cyan">Cyber Emerald</tspan></text>
+
+  <!-- summary box -->
+  <rect x="40" y="234" width="470" height="170" rx="8" fill="none" stroke="#22d3ee" stroke-opacity="0.7"/>
+  <rect x="56" y="226" width="86" height="16" fill="#0d1117"/>
+  <text x="62" y="239" class="mono txt bold">Summary</text>
+  <text x="60" y="266" class="mono"><tspan class="dim">Framework  </tspan><tspan class="txt">Laravel 13.x</tspan></text>
+  <text x="60" y="290" class="mono"><tspan class="dim">Frontend   </tspan><tspan class="txt">Vue 3 (Inertia)</tspan></text>
+  <text x="60" y="314" class="mono"><tspan class="dim">Auth       </tspan><tspan class="txt">Included</tspan></text>
+  <text x="60" y="338" class="mono"><tspan class="dim">Theme      </tspan></text>
+  <rect x="160" y="326" width="16" height="14" rx="2" fill="#10b981"/>
+  <text x="184" y="338" class="mono txt">Cyber Emerald · Dark + Light</text>
+  <text x="60" y="362" class="mono"><tspan class="dim">Database   </tspan><tspan class="txt">MySQL</tspan></text>
+  <text x="60" y="386" class="mono"><tspan class="dim">Location   </tspan><tspan class="dim">./shop</tspan></text>
+
+  <!-- progress -->
+  <text x="40" y="440" class="mono"><tspan class="green">✔</tspan><tspan class="txt"> Running official composer create-project laravel/laravel:^13.0</tspan></text>
+  <text x="40" y="466" class="mono"><tspan class="green">✔</tspan><tspan class="txt"> Installing Laravel Breeze (vue) with authentication</tspan></text>
+  <text x="40" y="492" class="mono"><tspan class="green">✔</tspan><tspan class="txt"> Running php artisan breeze:install vue</tspan></text>
+
+  <text x="40" y="534" class="mono"><tspan class="green">✔</tspan><tspan class="txt bold"> shop</tspan><tspan class="txt"> is ready</tspan></text>
+  <text x="40" y="566" class="mono"><tspan class="cyan">?</tspan><tspan class="txt bold"> What next?</tspan><tspan class="cyan bold">  ❯ Start the dev server</tspan><tspan class="dim">   Open in VS Code   Exit</tspan></text>
+</svg>

package/docs/assets/cli-menu.svg

@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="880" height="500" viewBox="0 0 880 500" role="img" aria-label="BoilerCraft CLI main menu">
+  <defs>
+    <linearGradient id="brand" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#22d3ee"/>
+      <stop offset="0.5" stop-color="#3b82f6"/>
+      <stop offset="1" stop-color="#8b5cf6"/>
+    </linearGradient>
+    <filter id="shadow" x="-5%" y="-5%" width="110%" height="115%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <style>
+    .mono { font-family: ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", Menlo, monospace; font-size: 15px; }
+    .dim { fill: #7d8590; }
+    .txt { fill: #e6edf3; }
+    .cyan { fill: #22d3ee; }
+    .green { fill: #3fb950; }
+    .bold { font-weight: 700; }
+  </style>
+
+  <rect x="10" y="6" width="860" height="484" rx="12" fill="#0d1117" stroke="#30363d" filter="url(#shadow)"/>
+  <rect x="10" y="6" width="860" height="38" rx="12" fill="#161b22"/>
+  <rect x="10" y="32" width="860" height="12" fill="#161b22"/>
+  <circle cx="36" cy="25" r="6" fill="#ff5f57"/>
+  <circle cx="56" cy="25" r="6" fill="#febc2e"/>
+  <circle cx="76" cy="25" r="6" fill="#28c840"/>
+  <text x="440" y="30" text-anchor="middle" class="mono dim" font-size="13">Terminal</text>
+
+  <text x="40" y="80" class="mono"><tspan class="green">$</tspan><tspan class="txt"> npx boilercraft</tspan></text>
+
+  <text x="40" y="150" font-family="'Segoe UI', Inter, Helvetica, Arial, sans-serif" font-size="58" font-weight="900" letter-spacing="7" fill="url(#brand)">BOILERCRAFT</text>
+
+  <text x="42" y="186" class="mono"><tspan class="dim">by </tspan><tspan class="txt bold">ARG RABBI</tspan><tspan class="dim">   ·   v1.0.0</tspan></text>
+  <text x="42" y="210" class="mono dim">Production-ready projects on the official tooling · any version · auth · themes</text>
+
+  <text x="42" y="258" class="mono"><tspan class="cyan">?</tspan><tspan class="txt bold"> What would you like to do?</tspan><tspan class="dim"> · ↑↓ to move, enter to select</tspan></text>
+
+  <text x="62" y="292" class="mono"><tspan class="cyan bold">❯ Create a new project</tspan></text>
+  <text x="400" y="292" class="mono dim">Laravel · Next.js · Express · .NET · PHP</text>
+  <text x="62" y="320" class="mono txt">  Check &amp; install tools</text>
+  <text x="400" y="320" class="mono dim">PHP · Composer · .NET SDK</text>
+  <text x="62" y="348" class="mono txt">  Browse frameworks &amp; versions</text>
+  <text x="62" y="376" class="mono txt">  Open the web studio</text>
+  <text x="400" y="376" class="mono dim">same features in your browser</text>
+  <text x="62" y="404" class="mono txt">  About BoilerCraft</text>
+  <text x="62" y="432" class="mono txt">  Exit</text>
+</svg>

package/docs/stacks/dotnet-core.md

@@ -0,0 +1,69 @@
+# 🟣 .NET Core 8 Web API Full Documentation & Maintenance Guide
+
+## 📌 Overview
+High-performance **.NET Core 8 Web API** with **Entity Framework Core**, **Swagger / OpenAPI Documentation**, **JWT Bearer Token Authentication**, and pre-wired CSS systems (Tailwind CSS or Bootstrap 5).
+
+---
+
+## 📂 Architecture & Directory Tree
+```text
+├── Controllers/
+│   ├── ProductsController.cs     # CRUD Web API Controller
+│   └── AuthController.cs         # JWT Authentication & Role Claims
+├── Models/
+│   └── Product.cs                # Entity Model
+├── Data/
+│   └── ApplicationDbContext.cs   # EF Core DbContext with Seeding
+├── Program.cs                    # Dependency Injection, Middleware, Swagger
+└── {ProjectName}.csproj          # Project file with Nuget packages
+```
+
+---
+
+## ⚡ Quick Start & Running
+1. Restore packages and run migrations:
+```bash
+dotnet restore
+dotnet build
+```
+
+2. Start the API server:
+```bash
+dotnet run
+```
+
+3. Open Swagger UI in your browser:
+```text
+http://localhost:5000/swagger
+```
+
+---
+
+## 🗄️ Database Migrations (EF Core)
+
+### Creating Migrations:
+Whenever you change or add models in `Models/`:
+```bash
+dotnet ef migrations add AddNewEntity
+```
+
+### Applying Migrations to Database:
+```bash
+dotnet ef database update
+```
+
+---
+
+## 🔐 JWT Authentication
+- Endpoint: `POST /api/auth/login`
+- Sample Body:
+```json
+{
+  "email": "admin@example.com",
+  "password": "admin123"
+}
+```
+- In Swagger or Postman, include the returned Bearer token in the `Authorization` header:
+```text
+Authorization: Bearer <your_jwt_token>
+```

package/docs/stacks/laravel-vue.md

@@ -0,0 +1,46 @@
+# 🔴 Laravel 11 + Vue 3 Full Documentation & Maintenance Guide
+
+## 📌 Overview
+Full-stack enterprise framework combining **Laravel 11**, **Vue 3 Composition API**, **Inertia.js**, and **Vite**, with database support for **MySQL** and **MSSQL**.
+
+---
+
+## 📂 Architecture & Directory Tree
+```text
+├── app/
+│   └── Http/
+│       └── Controllers/
+│           ├── HomeController.php
+│           └── Auth/AuthenticatedSessionController.php
+├── resources/
+│   ├── js/
+│   │   ├── Pages/
+│   │   │   ├── Home.vue           # Vue 3 Composition API Landing
+│   │   │   └── Auth/Login.vue     # Vue Login Component
+│   │   └── Components/            # Skeletons, Modals, Offcanvas
+│   └── css/                       # Theme styles
+├── routes/
+│   └── web.php                    # Inertia web routes
+├── vite.config.js
+└── composer.json
+```
+
+---
+
+## ⚡ Quick Start & Running
+1. Install backend and frontend dependencies:
+```bash
+composer install
+npm install
+```
+
+2. Start the Vite asset compiler and Laravel artisan server:
+```bash
+# Terminal 1:
+npm run dev
+
+# Terminal 2:
+php artisan serve
+```
+
+3. Open in browser: `http://localhost:8000`