stackloom-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niyo Abou Sharif
+
+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,169 @@
+# stackloom
+
+> Weave production-ready full-stack apps from a single command.
+
+`stackloom` is a recipe-driven, transactional code-generation CLI. It scaffolds
+a complete MERN application and then keeps extending it — full-stack resources,
+admin pages, deploy configs — without ever leaving a half-written file behind.
+
+The CLI command is **`loom`**. It is **rebrandable**: run `loom rename <name>`
+to make the whole tool your own.
+
+## Install
+
+```bash
+# one-off
+npx stackloom new my-app
+
+# or global
+pnpm add -g stackloom
+loom new my-app
+```
+
+## How it works
+
+The CLI is a generic engine — it hardcodes nothing about MERN. Three layers:
+
+| Layer | Lives in | Answers |
+|-------|----------|---------|
+| **Blueprint** | a project's `.loom/blueprint.json` | *where* things go — directory roots, path templates, injection anchors |
+| **Recipe** | `src/recipes/builtin/*.json` | *what* gets generated — files, injections, dependencies, gated by `when` conditions |
+| **Engine** | `src/engine/` | *how* — a transactional pipeline: `plan → render → inject → validate → commit` |
+
+Generation is **all-or-nothing**: every file is rendered into a staging
+transaction, syntax-validated, and only a fully-valid set is committed. A
+broken file is never written; on any failure the whole change set rolls back.
+
+Adding support for another stack (Next.js, PERN, …) is a new `blueprint.json` —
+not an engine change.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `loom new [name]` | Create a new project from the starter template |
+| `loom generate resource <Name>` | **Unified, engine-backed generator** — full-stack CRUD resource |
+| `loom generate resource <Name> --recipe module` | Backend-only module |
+| `loom generate resource <Name> --recipe page` | Frontend page wired to an existing resource |
+| `loom generate theme` / `loom generate deploy` | Import a shadcn theme / emit deploy configs |
+| `loom check` | Verify project health — blueprint validity, anchor integrity, env file |
+| `loom env [--sync]` | Diff `.env` against `.env.example`; `--sync` appends missing keys |
+| `loom rename <name>` | Rebrand the CLI itself (bin name, help text, output) |
+| `loom cleanup [preset]` | De-brand a project — `minimal` \| `production` (full) \| `template` |
+| `loom customize` | Theme / layout / brand / data-display |
+| `loom wizard` | Interactive guided setup |
+| `loom doctor` | Environment + project health check |
+| `loom rollback` | Undo the last generation |
+| `loom finalize` | Lint + test + build for production |
+| `loom preset [name]` | Apply a predefined preset |
+| `loom remove <type> <name>` | Remove a generated resource and its references |
+
+> `generate module`, `generate page`, and `make:resource` still work but are
+> **superseded** by `generate resource` — they print a deprecation notice.
+
+`loom init` is kept as an alias for `loom new`.
+
+## Global flags
+
+Every command honors:
+
+- `--quiet` / `-q` — errors and warnings only (auto-on under CI / when piped)
+- `--json` — structured JSON output for scripts
+- `--no-color` — disable ANSI colour
+- `--debug` — diagnostic detail
+- `--yes` / `-y` — assume defaults, never prompt
+
+## Generating a resource
+
+```bash
+# Full-stack CRUD: model, service, controller, routes, validator,
+# admin pages, table/form components, API client, hooks — all mounted and linked.
+loom generate resource Product --fields "name:string:required;price:number;slug:string"
+
+# Choose how the create/edit form is mounted
+loom generate resource Order --fields "total:number" --form-mode modal
+
+# Pick the architecture level (see below)
+loom generate resource Invoice --fields "amount:number" --arch lightweight
+
+# Preview without writing
+loom generate resource Ticket --fields "subject:string" --dry-run
+```
+
+The engine creates the requested files **and links them**: mounts the route in
+`backend/src/routes/index.js`, adds the lazy import + route to
+`AppRouter.jsx`, and appends the nav entry to `app-preset.js`. Injection is
+idempotent — re-running is safe.
+
+### Architecture levels (`--arch`)
+
+| Level | Backend shape |
+|-------|---------------|
+| `lightweight` | Inline controller, no service layer — minimal files |
+| `moderate` *(default)* | Full layering — `models/`, `services/`, `controllers/`, `routes/` |
+| `advanced` | `moderate` + generated tests + batch/transaction operations |
+
+### Form modes (`--form-mode`)
+
+`page` *(default)* · `modal` · `sidepanel` · `inline` — selects the list-page
+shell and how the shared form component is mounted. One form component, four
+thin page shells.
+
+## Field spec
+
+`--fields "name:type:rule|rule;name2:type2"` — e.g.
+`"email:email:required|unique;age:number:min=0;bio:text"`. Types: `string`,
+`text`, `number`, `boolean`, `date`, `email`, `password`, `ref`, `select`,
+`image`, and more. Definitions can also come from a file: `--file resource.js`.
+
+Inputs are schema-validated before generation runs — a bad field type, a
+non-PascalCase name, or duplicate fields fail fast with a clear message.
+
+## Customising templates
+
+Templates resolve in three tiers (first match wins):
+
+1. `<project>/.loom/templates/<path>` — project overrides
+2. `~/.loom/templates/<path>` — user-global overrides
+3. shipped defaults
+
+A project can also override a recipe by pointing `blueprint.recipes.<name>` at
+its own manifest.
+
+## Rebranding the CLI
+
+```bash
+loom rename acme --display-name "ACME"
+```
+
+Updates `branding.json` and `package.json`'s `bin` key. Re-link with
+`pnpm install` and the tool answers to `acme`.
+
+## Preparing a project for handoff
+
+```bash
+loom cleanup production   # full de-brand — see below
+```
+
+`cleanup` refuses to run unless the working directory is a real project root
+(has both `backend/` and `frontend/`). The `production` preset removes `.loom/`,
+the bundled CLI, starter docs and demo content; strips `STARTER-KIT:` /
+`TODO: Customize` comments and AUTO-GENERATED markers; resets package names;
+and rewrites the README — leaving no trace of the starter kit.
+
+## Local development
+
+```bash
+cd packages/cli
+pnpm install
+node bin/cli.js --help
+pnpm test          # vitest — engine, blueprint, recipes, services, schemas
+```
+
+See [`DEVELOPER.md`](./DEVELOPER.md) for engine internals, [`API.md`](./API.md)
+for the programmatic API, and [`SPLIT.md`](./SPLIT.md) for the planned
+`stackloom` / `stackloom-templates` repo split.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import path from "path";
+import fs from "fs-extra";
+import { fileURLToPath } from "url";
+import { readFileSync } from "fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Read version from package.json
+const pkg = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url)),
+);
+
+// Branding — the CLI's own identity (rebrandable via branding.json / `loom rename`)
+import { branding } from "../src/branding/index.js";
+
+// Import commands
+import init from "../src/commands/init.js";
+import generateModule from "../src/commands/generate/module.js";
+import generatePage from "../src/commands/generate/page.js";
+import generateTheme from "../src/commands/generate/theme.js";
+import generateDeploy from "../src/commands/generate/deploy.js";
+import remove from "../src/commands/remove.js";
+import wizard from "../src/commands/wizard.js";
+import customize from "../src/commands/customize.js";
+import cleanup from "../src/commands/cleanup.js";
+import finalize from "../src/commands/finalize.js";
+import rollback from "../src/commands/rollback.js";
+import doctor from "../src/commands/doctor.js";
+import preset from "../src/commands/preset.js";
+import makeResource from "../src/commands/make/resource.js";
+import generateResource from "../src/commands/generate-resource.js";
+import check from "../src/commands/check.js";
+import env from "../src/commands/env.js";
+import rename from "../src/commands/rename.js";
+
+program
+  .name(branding.binName)
+  .description(branding.description)
+  .version(pkg.version)
+  // Global output flags — consumed via reporterFromOptions(program.opts()).
+  .option("-q, --quiet", "Errors and warnings only (auto-on under CI / when piped)")
+  .option("--json", "Structured JSON output for scripts and CI")
+  .option("--no-color", "Disable ANSI colour")
+  .option("--debug", "Show diagnostic detail")
+  .option("-y, --yes", "Assume defaults; never prompt (fails fast on missing input)");
+
+// Init: create fresh project from template (always new copy)
+program
+  .command("init [project-name]")
+  .description("Create a new project from the starter kit template")
+  .option(
+    "--preset <variant>",
+    "Preset: saas|clinic|studio|operations|commerce|custom",
+  )
+  .option(
+    "--theme <theme>",
+    "Design theme: executiveBlue|clinicSoft|studioElevated|operationsDense|commerceWarm",
+  )
+  .option(
+    "--layout <layout>",
+    "Layout: hybridSaas|sidebarWorkspace|topbarPortal|rightRailStudio",
+  )
+  .option("--brand-name <name>", "Brand name")
+  .option("--tagline <text>", "Brand tagline")
+  .option(
+    "--extra-modules <list>",
+    "Comma-separated backend modules to include (e.g., users,products)",
+  )
+  .option(
+    "--deploy-targets <list>",
+    "Comma-separated deploy targets (docker,vercel,railway)",
+  )
+  .option("--no-install", "Skip pnpm install")
+  .option("--target <dir>", "Output directory")
+  .option("--force", "Overwrite existing directory")
+  .action(init);
+
+// Generate commands (inside existing project)
+const generateCmd = program
+  .command("generate")
+  .description("Add features to existing project");
+
+// Unified, engine-backed generation — blueprint + recipe + transactional pipeline.
+generateCmd
+  .command("resource [name]")
+  .description(
+    "Generate a full-stack resource via the engine (recipe-driven, transactional, validated)",
+  )
+  .option("--fields <spec>", "Field spec: 'name:type:rules;...'")
+  .option("--file <path>", "Path to a resource definition file")
+  .option("--recipe <name>", "Recipe to run: resource|module|page", "resource")
+  .option("--arch <level>", "Architecture: lightweight|moderate|advanced", "moderate")
+  .option("--form-mode <mode>", "Form mount mode: page|modal|sidepanel|inline", "page")
+  .option("--with-tests", "Generate test files")
+  .option("--no-frontend", "Skip frontend generation")
+  .option("--dry-run", "Preview the file plan without writing")
+  .action((name, options) =>
+    generateResource(options.recipe || "resource", name, { ...program.opts(), ...options }),
+  );
+
+generateCmd
+  .command("module <name>")
+  .description(
+    "Generate backend module (model, service, controller, routes, validator)",
+  )
+  .option("--force", "Overwrite existing files")
+  .option("--fields <spec>", "Field specification")
+  .option("--interactive", "Prompt for fields interactively")
+  .option(
+    "--architecture <level>",
+    "Architecture: lightweight|moderate|advanced",
+    "moderate",
+  )
+  .option("--with-page", "Generate corresponding frontend page")
+  .option(
+    "--form-mode <mode>",
+    "Form display mode if --with-page: page|modal|sidepanel|inline",
+    "page",
+  )
+  .action(generateModule);
+
+generateCmd
+  .command("page <name>")
+  .description("Generate frontend page with route and nav entry")
+  .option("--route <path>", "Custom route path")
+  .option("--no-nav", "Do not add to navigation")
+  .option("--icon <name>", "Icon name from lucide-react")
+  .option("--force", "Overwrite existing files")
+  .option("--with-form", "Generate form component")
+  .option(
+    "--form-mode <mode>",
+    "Form display mode: page|modal|sidepanel|inline",
+    "page",
+  )
+  .option("--form-fields <spec>", "Form field specification")
+  .option("--interactive", "Prompt for form fields interactively")
+  .action(generatePage);
+
+generateCmd
+  .command("theme")
+  .description("Import a shadcn/ui theme from CSS variables")
+  .option("--file <path>", "Path to CSS file with :root/.dark")
+  .option("--paste <css>", "CSS string directly")
+  .option("--fallback <theme>", "Fallback theme (default: executiveBlue)")
+  .option("--appearance <recipe>", "Appearance: elevated|flat|ux-heavy")
+  .option("--apply", "Update app-preset.js automatically")
+  .action(generateTheme);
+
+generateCmd
+  .command("deploy")
+  .description("Generate deployment configs (Docker, Vercel, Railway)")
+  .option("--target <provider>", "Target: docker|vercel|railway|all")
+  .option("--force", "Overwrite existing files")
+  .action(generateDeploy);
+
+// Remove generated resources (safe, with confirmation)
+program
+  .command("remove <type> <name>")
+  .description("Remove a generated page or module (with cleanup)")
+  .option("--force", "Skip confirmation")
+  .action(remove);
+
+// Cleanup: remove demo files, strip branding, prepare for deployment
+program
+  .command("cleanup [preset]")
+  .description("Clean up / de-brand the project (minimal|production|template)")
+  .action((preset) => cleanup(preset));
+
+// Interactive wizard — guided setup after init or anytime
+program
+  .command("wizard")
+  .description("Interactive guide to extend your project")
+  .option("--skip-confirm", "Skip final confirmation step")
+  .action(wizard);
+
+// Customize existing project: theme/layout/brand/data
+const customizeCmd = program
+  .command("customize")
+  .description("Customize project design & branding");
+
+// ── Theme subcommand group ──
+const themeCmd = customizeCmd.command("theme").description("Theme operations");
+themeCmd
+  .command("set [theme]")
+  .description("Switch to a built-in theme")
+  .action(customize.customizeThemeSet);
+themeCmd
+  .command("import")
+  .description("Import a custom shadcn/ui theme from CSS")
+  .option("--file <path>", "Path to CSS file with :root and .dark")
+  .option("--paste <css>", "CSS string directly")
+  .option("--fallback <theme>", "Fallback theme (default: executiveBlue)")
+  .option("--appearance <recipe>", "Appearance recipe (default: quiet)")
+  .action(customize.customizeThemeImport);
+
+// ── Layout ──
+const layoutCmd = customizeCmd
+  .command("layout")
+  .description("Layout operations");
+layoutCmd
+  .command("set [layout]")
+  .description("Switch layout shell")
+  .action(customize.customizeLayoutSet);
+
+// ── Brand ──
+const brandCmd = customizeCmd.command("brand").description("Brand operations");
+brandCmd
+  .command("set")
+  .description("Update brand name and/or tagline")
+  .option("--name <text>", "New brand name")
+  .option("--tagline <text>", "New tagline")
+  .action(customize.customizeBrandSet);
+
+// ── Data display ──
+const dataCmd = customizeCmd
+  .command("data")
+  .description("Data display template operations");
+dataCmd
+  .command("set [template]")
+  .description("Switch data display template")
+  .action(customize.customizeDataSet);
+
+// ── Discovery helpers ──
+customizeCmd
+  .command("list-themes")
+  .description("List available built-in themes")
+  .action(customize.customizeListThemes);
+customizeCmd
+  .command("list-layouts")
+  .description("List available layout shells")
+  .action(customize.customizeListLayouts);
+customizeCmd
+  .command("list-data")
+  .description("List available data display templates")
+  .action(customize.customizeListData);
+
+// Finalize
+program
+  .command("finalize")
+  .description("Prepare project for production (lint, test, build)")
+  .action(finalize);
+
+// Rollback
+program
+  .command("rollback")
+  .description("Undo the last generation action")
+  .option("-f, --force", "Skip confirmation")
+  .option("-v, --verbose", "Show detailed logs")
+  .action(rollback);
+
+// Doctor
+program
+  .command("doctor")
+  .description("Check environment and project health")
+  .action(doctor);
+
+// Check — structural health: Node, blueprint validity, anchor integrity, env file
+program
+  .command("check")
+  .description("Verify project + environment health (blueprint, anchors, env)")
+  .action((options) => check({ ...program.opts(), ...options }));
+
+// Env — keep .env in sync with .env.example
+program
+  .command("env")
+  .description("Diff .env against .env.example; --sync appends missing keys")
+  .option("--sync", "Append missing keys to .env")
+  .action((options) => env({ ...program.opts(), ...options }));
+
+// Preset
+program
+  .command("preset [name]")
+  .description("Apply a predefined configuration preset (saas, clinic, etc.)")
+  .action(preset);
+
+// Make Resource
+program
+  .command("make:resource [name]")
+  .description("Create a new resource from schema or interactive wizard")
+  .option("-f, --file <path>", "Path to resource definition file")
+  .option("--fields <spec>", "Field specification (name:type:rules;...)")
+  .option("-i, --interactive", "Run interactive wizard")
+  .option("--dry-run", "Preview changes without writing")
+  .option("--force", "Overwrite existing files")
+  .option(
+    "--arch <level>",
+    "Architecture: lightweight|moderate|advanced",
+    "moderate",
+  )
+  .option("--no-frontend", "Skip frontend generation")
+  .option("--with-tests", "Generate test files")
+  .action(makeResource);
+
+// Rename: rebrand the CLI tool itself
+program
+  .command("rename <new-name>")
+  .description("Rebrand this CLI — change the command name used to invoke it")
+  .option("--display-name <name>", "Human-readable display name")
+  .option("--description <text>", "CLI description shown in help")
+  .action(rename);
+
+program.parse();

package/branding.json

@@ -0,0 +1,8 @@
+{
+  "binName": "loom",
+  "displayName": "Stackloom",
+  "description": "Stackloom — weave production-ready full-stack apps from a single command",
+  "tagline": "Weave full-stack apps from a single command",
+  "stateDirName": ".loom",
+  "packageName": "stackloom"
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "stackloom-cli",
+  "version": "1.0.0",
+  "description": "Stackloom CLI — weave production-ready full-stack apps. Recipe-driven, transactional code generation for MERN and beyond.",
+  "type": "module",
+  "bin": {
+    "loom": "./bin/cli.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "dev": "node --watch bin/cli.js",
+    "start": "node bin/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "vitest run"
+  },
+  "keywords": [
+    "stackloom",
+    "loom",
+    "mern",
+    "scaffold",
+    "generator",
+    "cli",
+    "react",
+    "express",
+    "mongodb",
+    "starter",
+    "fullstack"
+  ],
+  "author": "Niyo Abou Sharif <niyoabousharifu@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abou-Sharif/stackloom.git"
+  },
+  "homepage": "https://github.com/Abou-Sharif/stackloom#readme",
+  "bugs": {
+    "url": "https://github.com/Abou-Sharif/stackloom/issues"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^13.1.0",
+    "ejs": "^5.0.2",
+    "fs-extra": "^11.3.0",
+    "inquirer": "^13.3.2",
+    "ora": "^8.0.1",
+    "tar": "^7.5.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "branding.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^25.7.0",
+    "@types/tar": "^7.0.87",
+    "@vitest/coverage-v8": "^4.1.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  }
+}

package/src/__tests__/cli-smoke.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execSync } from "child_process";
+import path from "path";
+import fs from "fs-extra";
+import os from "os";
+
+const CLI_PATH = path.resolve(__dirname, "../../bin/cli.js");
+const TEMP_DIR = path.join(os.tmpdir(), "loom-test-" + Date.now());
+
+describe("Stackloom CLI Smoke Tests", () => {
+  beforeAll(async () => {
+    await fs.ensureDir(TEMP_DIR);
+  });
+
+  afterAll(async () => {
+    await fs.remove(TEMP_DIR);
+  });
+
+  // Spawning a fresh Node process per test is slow on Windows + pnpm symlinks;
+  // give the smoke tests generous timeouts — they assert behaviour, not speed.
+  const SMOKE_TIMEOUT = 30000;
+
+  it("should show version", () => {
+    const output = execSync(`node "${CLI_PATH}" --version`).toString();
+    expect(output).toMatch(/\d+\.\d+\.\d+/);
+  }, SMOKE_TIMEOUT);
+
+  it("should show help", () => {
+    const output = execSync(`node "${CLI_PATH}" --help`).toString();
+    expect(output).toContain("Usage: loom");
+    expect(output).toContain("init");
+    expect(output).toContain("generate");
+  }, SMOKE_TIMEOUT);
+
+  it("should fail when running doctor outside project", () => {
+    let failed = false;
+    try {
+      execSync(`node "${CLI_PATH}" doctor`, { cwd: TEMP_DIR, stdio: "pipe" });
+    } catch (err) {
+      failed = true;
+      const out = `${err.stdout?.toString() ?? ""}${err.stderr?.toString() ?? ""}`;
+      expect(out).toMatch(/not a|MERN|project/i);
+    }
+    expect(failed).toBe(true);
+  }, SMOKE_TIMEOUT);
+});