boilercraft 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARG RABBI (https://github.com/itrabbi24)
+
+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,171 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/itrabbi24/BoilerCraft/main/assets/icon.png" alt="BoilerCraft" width="140" />
+
+# BoilerCraft
+
+**Production-ready projects in one command, built on each framework's official tooling.**
+<br />
+Any version · Authentication · Themes · Windows, macOS & Linux
+
+[![npm](https://img.shields.io/npm/v/boilercraft?color=22d3ee&label=npm)](https://www.npmjs.com/package/boilercraft)
+[![node](https://img.shields.io/badge/node-%E2%89%A518.3-3b82f6)](https://nodejs.org)
+[![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8b5cf6)](#)
+[![license](https://img.shields.io/badge/license-MIT-10b981)](LICENSE)
+
+```bash
+npx boilercraft
+```
+
+<img src="https://raw.githubusercontent.com/itrabbi24/BoilerCraft/main/docs/assets/cli-menu.svg" alt="BoilerCraft main menu" width="760" />
+
+</div>
+
+---
+
+## Why BoilerCraft
+
+Most boilerplates are a frozen copy of someone's project. They go stale the day a new framework version ships. BoilerCraft works differently:
+
+- **Always the real thing.** The base project is created by the framework's own creator (`composer create-project`, `create-next-app`, `dotnet new`, `npm`), so it matches the version you pick exactly.
+- **Any version, including future ones.** Versions are fetched live from npm, Packagist and the .NET release index. A new release shows up in the menu without an update to BoilerCraft.
+- **Ready to build on.** Auth, database wiring, a themed landing page and UI components are added on top, so you start with a working app instead of a blank one.
+- **One command, zero setup.** Everything happens inside `npx boilercraft`. Missing PHP, Composer or the .NET SDK? It offers to install them for you.
+
+## Quick start
+
+```bash
+npx boilercraft
+```
+
+Choose **Create a new project** and answer a few questions (↑/↓ to move, Enter to select):
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/itrabbi24/BoilerCraft/main/docs/assets/cli-create.svg" alt="Creating a Laravel project" width="760" />
+</div>
+
+When it's done, pick **Start the dev server** or **Open in VS Code** from the same menu. You don't need to type `cd` or any other command.
+
+## What you can create
+
+| Framework | Versions | Choices | Databases | Auth |
+|---|---|---|---|---|
+| **Laravel** | 10 – 13 | Blade · Vue 3 (Inertia) · React (Inertia) | MySQL · SQL Server | Sanctum API tokens, or full Breeze UI (login, register, profile) for Vue/React |
+| **Next.js** | 14 – 16 | App Router · Pages Router | MongoDB · MySQL · SQL Server | JWT register/login API routes |
+| **.NET** | 8 – 10 | MVC (Model · View · Controller) · Web API | SQL Server · MySQL | MVC: cookie login/register pages · API: JWT + Swagger |
+| **Node.js + Express** | 4 – 5 | — | MySQL · MongoDB · SQL Server | JWT middleware with roles |
+| **Raw PHP (MVC)** | — | — | MySQL | Session auth |
+
+Every project also gets:
+- A **theme**: Slate Midnight, Cyber Emerald, Royal Indigo or Crimson Amber, in dark, light or both with a toggle.
+- **Styling** with Tailwind CSS, Bootstrap 5 or plain CSS.
+- Optional **UI components**: skeleton loaders, spinners, modals, off-canvas drawers.
+
+The version list above is just what's verified today. Newer releases appear automatically and are marked *preview support* until verified.
+
+## Missing a toolchain?
+
+BoilerCraft checks what's installed and offers to set up the rest. You can also do it any time from **Check & install tools** in the menu.
+
+| Tool | Needed for | How BoilerCraft installs it |
+|---|---|---|
+| .NET SDK | .NET | Microsoft's official `dotnet-install` script, exact version, user folder, **no admin rights** |
+| Composer | Laravel | Official installer, signature-verified, user folder |
+| PHP | Laravel, Raw PHP | `winget` (Windows) · Homebrew (macOS) · apt / dnf / pacman (Linux) |
+| Node.js | Next.js, Express | Already there, since `npx` runs on it |
+
+Tools installed into the user folder live in `~/.boilercraft/tools` and are added to your user PATH.
+
+## Web studio
+
+Prefer a browser? Choose **Open the web studio** in the menu. You get the same generator as a visual form at `http://localhost:4800`.
+
+<details>
+<summary><b>Automation (scripts and CI)</b></summary>
+
+<br />
+
+Every question has a flag. Anything you leave out is asked interactively, or takes its default with `-y`.
+
+```bash
+npx boilercraft new shop  -s laravel -v 13 --frontend vue -t emerald -d mysql -y
+npx boilercraft new web   -s nextjs --router pages --no-auth -d mongodb -y
+npx boilercraft new admin -s dotnet-core -v 10 --template mvc -y --install-tools
+npx boilercraft --help
+```
+
+</details>
+
+<details>
+<summary><b>How new framework versions are handled</b></summary>
+
+<br />
+
+Each framework is described by a small manifest in [`stacks/<id>/stack.json`](stacks). It covers where versions come from, which official creator to run, and which BoilerCraft files to add, and each step can be limited to certain versions. In practice:
+
+- **A new release usually needs nothing.** It appears in the menu automatically.
+- **If a release changes something BoilerCraft relies on,** one version-scoped rule is added to the manifest. No code change is needed.
+
+Full reference: [docs/STACK_ENGINE.md](docs/STACK_ENGINE.md).
+
+</details>
+
+<details>
+<summary><b>Project structure</b></summary>
+
+<br />
+
+```text
+BoilerCraft/
+├── bin/boilercraft.js        # CLI entry (npx boilercraft)
+├── cli/                      # Interactive menus, banner and prompts
+├── stacks/<id>/              # One folder per framework
+│   ├── stack.json            #   versions, official creator, version-scoped steps
+│   └── overlays/             #   files BoilerCraft adds on top
+├── services/
+│   ├── engine/               # Manifest runner, live version catalog, tool installer
+│   ├── generate.js           # Shared entry for the CLI and web studio
+│   ├── themeGenerator.js     # Theme palettes and dark/light CSS
+│   └── componentGenerator.js # Skeleton, spinner, modal and drawer components
+├── templates/                # Offline fallback templates (and Raw PHP)
+├── public/index.html         # Web studio
+└── server.js                 # Web studio API
+```
+
+</details>
+
+<details>
+<summary><b>Working on BoilerCraft</b></summary>
+
+<br />
+
+```bash
+git clone https://github.com/itrabbi24/BoilerCraft.git
+cd BoilerCraft
+npm install
+node bin/boilercraft.js
+```
+
+To test exactly what npm users get: run `npm pack`, then `npx --package=./boilercraft-<version>.tgz boilercraft` in an empty folder.
+
+**Releasing:** bump `version` in `package.json`, then run `npm publish`. Alternatively, push a `vX.Y.Z` tag: GitHub Actions smoke-tests on Windows, macOS and Linux and then publishes (requires the `NPM_TOKEN` repository secret).
+
+</details>
+
+## Contributing
+
+Issues and pull requests are welcome. Please see the [issues page](https://github.com/itrabbi24/BoilerCraft/issues).
+
+1. Fork the repository.
+2. Create a branch: `git checkout -b feature/my-feature`.
+3. Commit your changes and open a pull request.
+
+## Author
+
+**ARG RABBI** · [@itrabbi24](https://github.com/itrabbi24)
+
+If BoilerCraft saves you time, a ⭐ on [GitHub](https://github.com/itrabbi24/BoilerCraft) is appreciated.
+
+## License
+
+[MIT](LICENSE) © 2026 ARG RABBI

package/bin/boilercraft.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * BoilerCraft CLI — cross-platform (Windows / macOS / Linux).
+ *
+ * Everything is reachable from one command:
+ *
+ *   npx boilercraft
+ *
+ * which opens an interactive menu (create project, install tools, browse
+ * versions, web studio). Flags exist only for scripts/CI, e.g.
+ *   npx boilercraft new my-app -s laravel -v 12 -y
+ * See `npx boilercraft --help`.
+ */
+process.env.BOILERCRAFT_CLI = '1';
+
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 18 || (major === 18 && minor < 3)) {
+  console.error(`BoilerCraft needs Node.js 18.3 or newer (you have ${process.version}). Get it at https://nodejs.org`);
+  process.exit(1);
+}
+
+const { parseArgs } = require('util');
+const ui = require('../cli/ui');
+const app = require('../cli/app');
+const pkg = require('../package.json');
+
+const { c } = ui;
+
+const HELP = `
+  ${ui.gradient('BoilerCraft')} ${c.gray(`v${pkg.version}`)} ${c.gray('· by')} ${c.bold(app.AUTHOR)}
+
+  ${c.bold('Usage')}
+    ${c.cyan('npx boilercraft')}            Opens the interactive menu. This is all you need.
+
+  ${c.bold('Automation')} ${c.gray('(scripts / CI, no prompts)')}
+    npx boilercraft new <name> [flags]
+
+    -s, --stack <id>        laravel | nextjs | node-express | dotnet-core | raw-php
+    -v, --version <major>   Framework major version (default: recommended)
+        --auth / --no-auth  Authentication module (default: on)
+        --router <type>     app | pages          (Next.js, default: app)
+        --frontend <name>   blade | vue | react  (Laravel, default: blade)
+        --template <type>   mvc | api            (.NET, default: mvc)
+    -t, --theme <name>      midnight | emerald | royal | crimson
+    -m, --mode <mode>       all | dark | light
+    -d, --db <name>         mysql | mssql | mongodb
+        --styling <name>    tailwind | bootstrap | vanilla
+    -o, --out <dir>         Parent folder (default: current directory)
+    -y, --yes               Defaults for anything not given
+        --install-tools     Install missing PHP / Composer / .NET SDK automatically
+        --no-fallback       Fail instead of using offline templates
+    -h, --help              This help
+`;
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    allowNegative: true,
+    options: {
+      stack: { type: 'string', short: 's' },
+      version: { type: 'string', short: 'v' },
+      auth: { type: 'boolean' },
+      theme: { type: 'string', short: 't' },
+      mode: { type: 'string', short: 'm' },
+      router: { type: 'string' },
+      frontend: { type: 'string' },
+      template: { type: 'string' },
+      db: { type: 'string', short: 'd' },
+      styling: { type: 'string' },
+      port: { type: 'string' },
+      title: { type: 'string' },
+      author: { type: 'string' },
+      out: { type: 'string', short: 'o' },
+      yes: { type: 'boolean', short: 'y' },
+      'install-tools': { type: 'boolean' },
+      fallback: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  });
+
+  if (values.help || positionals[0] === 'help') return console.log(HELP);
+
+  const [command, name] = positionals;
+  if (!command) return app.home();
+
+  // Non-interactive / scripted use.
+  if (command === 'new' || command === 'create') {
+    app.printBanner();
+    const given = { ...values, name, installTools: values['install-tools'], noFallback: values.fallback === false };
+    await app.createFlow(given);
+    return app.goodbye();
+  }
+  if (command === 'list') return app.browseFlow();
+  if (command === 'doctor' || command === 'tools') return app.toolsFlow();
+
+  // `npx boilercraft my-app` → menu-free create with the name filled in.
+  app.printBanner();
+  await app.createFlow({ ...values, name: command });
+  app.goodbye();
+}
+
+main().catch(err => {
+  if (err instanceof ui.CancelError) {
+    console.log(`\n  ${c.gray('Cancelled.')}\n`);
+    return;
+  }
+  ui.log.error(err.message);
+  console.log('');
+  process.exitCode = 1;
+});