stackloom-cli 1.0.0

package/src/commands/customize.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+import path from "path";
+import fs from "fs-extra";
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+
+const DESIGN_THEMES = [
+  "executiveBlue",
+  "clinicSoft",
+  "studioElevated",
+  "operationsDense",
+  "commerceWarm",
+];
+
+const DESIGN_LAYOUTS = [
+  "hybridSaas",
+  "sidebarWorkspace",
+  "topbarPortal",
+  "rightRailStudio",
+];
+
+const DATA_TEMPLATES = ["dashboard", "denseOps", "editorial", "commerce"];
+
+/**
+ * @param {string} projectRoot
+ */
+function getPresetPath(projectRoot) {
+  return path.join(projectRoot, "frontend/src/config/app-preset.js");
+}
+
+/**
+ * @param {string} projectRoot
+ */
+async function ensureProject(projectRoot) {
+  const presetPath = getPresetPath(projectRoot);
+  if (!fs.existsSync(presetPath)) {
+    console.log(
+      chalk.red("✖  Not a MERN Starter Kit project (missing app-preset.js)."),
+    );
+    process.exit(1);
+  }
+  return await fs.readFile(presetPath, "utf-8");
+}
+
+// ── THEME ──
+/**
+ * @param {string} theme
+ * @param {any} _options
+ */
+export async function customizeThemeSet(theme, _options) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  let presetCode = await ensureProject(projectRoot);
+
+  let selectedTheme = theme;
+  if (!selectedTheme) {
+    const answers = await inquirer.prompt([
+      {
+        type: "list",
+        name: "theme",
+        message: "Select a theme:",
+        choices: DESIGN_THEMES,
+      },
+    ]);
+    selectedTheme = answers.theme;
+  }
+
+  if (DESIGN_THEMES.includes(selectedTheme)) {
+    presetCode = presetCode.replace(
+      /theme:\s*designThemes\.\w+/,
+      `theme: designThemes.${selectedTheme}`,
+    );
+    await fs.writeFile(getPresetPath(projectRoot), presetCode);
+    spinner.succeed(`Theme set to "${selectedTheme}"`);
+  } else {
+    spinner.fail(`Invalid theme. Available: ${DESIGN_THEMES.join(", ")}`);
+  }
+}
+
+/**
+ * @param {any} options
+ */
+export async function customizeThemeImport(options) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  await ensureProject(projectRoot);
+
+  const css = options.file
+    ? fs.existsSync(options.file)
+      ? await fs.readFile(options.file, "utf-8")
+      : (console.log(chalk.red(`✖  File not found: ${options.file}`)),
+        process.exit(1))
+    : options.paste;
+
+  if (!css) {
+    console.log(chalk.red('✖  Must provide --file <path> or --paste "<css>"'));
+    process.exit(1);
+  }
+
+  const cssPath = path.join(
+    projectRoot,
+    "frontend/src/config/imported-shadcn-theme.css",
+  );
+  await fs.writeFile(cssPath, css);
+  spinner.succeed(
+    "Theme CSS saved to frontend/src/config/imported-shadcn-theme.css",
+  );
+
+  console.log(
+    chalk.green(
+      "\n✓  Apply it in your app-preset.js using installShadcnDesignPreset:\n",
+    ),
+  );
+  console.log(
+    chalk.white(
+      `import { installShadcnDesignPreset } from "@/lib/shadcn-theme";`,
+    ),
+  );
+  console.log(
+    chalk.white(`import customCss from "./imported-shadcn-theme.css";`),
+  );
+  console.log("");
+  console.log(chalk.white(`theme: installShadcnDesignPreset(customCss, {`));
+  console.log(
+    chalk.white(`  fallback: "${options.fallback || "executiveBlue"}",`),
+  );
+  console.log(chalk.white(`  appearance: "${options.appearance || "quiet"}"`));
+  console.log(chalk.white(`});`));
+}
+
+// ── LAYOUT ──
+/**
+ * @param {string} layout
+ */
+export async function customizeLayoutSet(layout) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  let presetCode = await ensureProject(projectRoot);
+
+  let selectedLayout = layout;
+  if (!selectedLayout) {
+    const answers = await inquirer.prompt([
+      {
+        type: "list",
+        name: "layout",
+        message: "Select a layout:",
+        choices: DESIGN_LAYOUTS,
+      },
+    ]);
+    selectedLayout = answers.layout;
+  }
+
+  if (DESIGN_LAYOUTS.includes(selectedLayout)) {
+    presetCode = presetCode.replace(
+      /layout:\s*designLayouts\.\w+/,
+      `layout: designLayouts.${selectedLayout}`,
+    );
+    await fs.writeFile(getPresetPath(projectRoot), presetCode);
+    spinner.succeed(`Layout set to "${selectedLayout}"`);
+  } else {
+    spinner.fail(`Invalid layout. Available: ${DESIGN_LAYOUTS.join(", ")}`);
+  }
+}
+
+// ── BRAND ──
+/**
+ * @param {any} options 
+ */
+export async function customizeBrandSet(options) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  let presetCode = await ensureProject(projectRoot);
+
+  const name = options.name || options.n;
+  const tagline = options.tagline || options.t;
+
+  if (!name && !tagline) {
+    console.log(chalk.red("✖  Must provide at least --name or --tagline"));
+    process.exit(1);
+  }
+
+  if (name) {
+    presetCode = presetCode.replace(
+      /brand:\s*\{\s*name:\s*["'][^"']+["']/,
+      `brand: { name: "${name}"`,
+    );
+  }
+  if (tagline) {
+    presetCode = presetCode.replace(
+      /tagline:\s*["'][^"']+["']/,
+      `tagline: "${tagline}"`,
+    );
+  }
+
+  await fs.writeFile(getPresetPath(projectRoot), presetCode);
+  const parts = [];
+  if (name) parts.push("name=" + name);
+  if (tagline) parts.push("tagline=" + tagline);
+  spinner.succeed(`Brand updated (${parts.join(", ")})`);
+}
+
+// ── DATA DISPLAY ──
+/**
+ * @param {string} template 
+ */
+export async function customizeDataSet(template) {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  let presetCode = await ensureProject(projectRoot);
+
+  let selectedTemplate = template;
+  if (!selectedTemplate) {
+    const answers = await inquirer.prompt([
+      {
+        type: "list",
+        name: "template",
+        message: "Select a data display template:",
+        choices: DATA_TEMPLATES,
+      },
+    ]);
+    selectedTemplate = answers.template;
+  }
+
+  if (DATA_TEMPLATES.includes(selectedTemplate)) {
+    presetCode = presetCode.replace(
+      /dataDisplay:\s*dataDisplayTemplates\.\w+/,
+      `dataDisplay: dataDisplayTemplates.${selectedTemplate}`,
+    );
+    await fs.writeFile(getPresetPath(projectRoot), presetCode);
+    spinner.succeed(`Data display template set to "${selectedTemplate}"`);
+  } else {
+    spinner.fail(`Invalid template. Available: ${DATA_TEMPLATES.join(", ")}`);
+  }
+}
+
+// ── LISTERS ──
+export function customizeListThemes() {
+  console.log(chalk.cyan("\nAvailable themes:\n"));
+  DESIGN_THEMES.forEach((t) => console.log(`  ${chalk.white("•")} ${t}`));
+}
+
+export function customizeListLayouts() {
+  console.log(chalk.cyan("\nAvailable layouts:\n"));
+  DESIGN_LAYOUTS.forEach((l) => console.log(`  ${chalk.white("•")} ${l}`));
+}
+
+export function customizeListData() {
+  console.log(chalk.cyan("\nAvailable data display templates:\n"));
+  DATA_TEMPLATES.forEach((d) => console.log(`  ${chalk.white("•")} ${d}`));
+}
+
+export default {
+  customizeThemeSet,
+  customizeThemeImport,
+  customizeLayoutSet,
+  customizeBrandSet,
+  customizeDataSet,
+  customizeListThemes,
+  customizeListLayouts,
+  customizeListData,
+};

package/src/commands/doctor.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import ora from 'ora';
+import { execSync } from 'child_process';
+
+/**
+ * Doctor Command — checks environment and project health
+ */
+export default async function doctorCmd() {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+  // Track hard failures so the command exits non-zero — a doctor that always
+  // exits 0 is useless in CI and scripts.
+  let failures = 0;
+
+  console.log(chalk.cyan.bold('\n🏥 Stackloom Doctor — System Health Check\n'));
+
+  // 1. Environment Checks
+  spinner.start('Checking Node.js version...');
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1).split('.')[0]);
+  if (major < 18) {
+    spinner.fail(`Node.js version ${nodeVersion} is too old. Required: >=18.0.0`);
+    failures++;
+  } else {
+    spinner.succeed(`Node.js ${nodeVersion} detected`);
+  }
+
+  spinner.start('Checking pnpm...');
+  try {
+    const pnpmVersion = execSync('pnpm -v').toString().trim();
+    spinner.succeed(`pnpm ${pnpmVersion} detected`);
+  } catch {
+    spinner.warn('pnpm not found. It is recommended for this starter kit.');
+  }
+
+  // 2. Project Checks
+  spinner.start('Checking project structure...');
+  const isProject = await fs.pathExists(path.join(projectRoot, 'backend')) && 
+                    await fs.pathExists(path.join(projectRoot, 'frontend'));
+  
+  if (!isProject) {
+    spinner.fail('Not a MERN Starter Kit project. Run this inside the project root.');
+    failures++;
+  } else {
+    spinner.succeed('Project structure valid');
+  }
+
+  // 3. Dependencies
+  if (isProject) {
+    spinner.start('Checking backend dependencies...');
+    if (await fs.pathExists(path.join(projectRoot, 'backend/node_modules'))) {
+      spinner.succeed('Backend dependencies installed');
+    } else {
+      spinner.warn('Backend dependencies missing. Run `pnpm install`');
+    }
+
+    spinner.start('Checking frontend dependencies...');
+    if (await fs.pathExists(path.join(projectRoot, 'frontend/node_modules'))) {
+      spinner.succeed('Frontend dependencies installed');
+    } else {
+      spinner.warn('Frontend dependencies missing. Run `pnpm install`');
+    }
+
+    // 4. Configuration
+    spinner.start('Checking environment files...');
+    const hasBackendEnv = await fs.pathExists(path.join(projectRoot, 'backend/.env'));
+    if (hasBackendEnv) {
+      spinner.succeed('Backend .env found');
+    } else {
+      spinner.warn('Backend .env missing (use .env.example)');
+    }
+  }
+
+  if (failures > 0) {
+    console.log(chalk.red(`\n✖ Health check found ${failures} issue(s).\n`));
+    process.exitCode = 1;
+  } else {
+    console.log(chalk.green('\n✓ Health check complete — all good.\n'));
+  }
+}

package/src/commands/env.js

@@ -0,0 +1,75 @@
+/**
+ * `loom env` — keep `.env` in sync with `.env.example`.
+ *
+ * The most common "works on my machine" bug is a missing env var. This diffs
+ * the two files and, with `--sync`, appends any keys the example declares but
+ * `.env` is missing (values left blank for the developer to fill).
+ *
+ * Pure dotenv-style parsing — no dependency on the `dotenv` package.
+ */
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import path from "node:path";
+import { reporterFromOptions } from "../services/index.js";
+
+/** Parse `KEY=value` lines into an ordered list of keys (comments/blanks skipped). */
+export function parseEnvKeys(content) {
+  const keys = [];
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq > 0) keys.push(line.slice(0, eq).trim());
+  }
+  return keys;
+}
+
+/**
+ * @param {object} [options] - global flags plus:
+ * @param {boolean} [options.sync] - append missing keys to .env
+ * @param {string} [options.projectRoot]
+ * @param {object} [options.reporter]
+ */
+export default async function env(options = {}) {
+  const reporter = options.reporter ?? reporterFromOptions(options);
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const examplePath = path.join(projectRoot, ".env.example");
+  const envPath = path.join(projectRoot, ".env");
+
+  if (!existsSync(examplePath)) {
+    reporter.warn("No .env.example found — nothing to compare against.");
+    reporter.result({ missing: [], synced: false });
+    reporter.flush();
+    return { missing: [], synced: false };
+  }
+
+  const exampleKeys = parseEnvKeys(readFileSync(examplePath, "utf-8"));
+  const currentKeys = existsSync(envPath)
+    ? new Set(parseEnvKeys(readFileSync(envPath, "utf-8")))
+    : new Set();
+  const missing = exampleKeys.filter((key) => !currentKeys.has(key));
+
+  if (missing.length === 0) {
+    reporter.success(".env is in sync with .env.example");
+    reporter.result({ missing: [], synced: false });
+    reporter.flush();
+    return { missing: [], synced: false };
+  }
+
+  reporter.warn(`${missing.length} key(s) missing from .env: ${missing.join(", ")}`);
+
+  let synced = false;
+  if (options.sync) {
+    const block = `${missing.map((key) => `${key}=`).join("\n")}\n`;
+    if (existsSync(envPath)) appendFileSync(envPath, `\n# Added by 'loom env --sync'\n${block}`);
+    else writeFileSync(envPath, `# Generated by 'loom env --sync'\n${block}`);
+    synced = true;
+    reporter.success(`Appended ${missing.length} key(s) to .env — fill in the values.`);
+  } else {
+    reporter.info("Run 'loom env --sync' to append the missing keys.");
+    process.exitCode = 1;
+  }
+
+  reporter.result({ missing, synced });
+  reporter.flush();
+  return { missing, synced };
+}

package/src/commands/finalize.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import ora from 'ora';
+import { execSync } from 'child_process';
+
+/**
+ * Finalize Command — prepares the project for production
+ */
+export default async function finalizeCmd() {
+  const spinner = ora();
+  const projectRoot = process.cwd();
+
+  console.log(chalk.cyan.bold('\n🚀 Finalizing Project for Production\n'));
+
+  // 1. Linting
+  spinner.start('Running linting checks...');
+  try {
+    execSync('pnpm lint', { cwd: projectRoot, stdio: 'pipe' });
+    spinner.succeed('Linting passed');
+  } catch {
+    spinner.fail('Linting failed. Please fix errors before finalizing.');
+    process.exit(1);
+  }
+
+  // 2. Type Checking
+  spinner.start('Running type checks...');
+  try {
+    execSync('pnpm -C backend exec tsc --noEmit', { cwd: projectRoot, stdio: 'pipe' });
+    execSync('pnpm -C frontend exec tsc --noEmit', { cwd: projectRoot, stdio: 'pipe' });
+    spinner.succeed('Type checks passed');
+  } catch {
+    spinner.warn('Type checks failed or tsc not found. Skipping.');
+  }
+
+  // 3. Tests
+  spinner.start('Running all tests...');
+  try {
+    execSync('pnpm test', { cwd: projectRoot, stdio: 'pipe' });
+    spinner.succeed('All tests passed');
+  } catch {
+    spinner.fail('Tests failed. Please fix before production.');
+    process.exit(1);
+  }
+
+  // 4. Build
+  spinner.start('Building for production...');
+  try {
+    execSync('pnpm build', { cwd: projectRoot, stdio: 'pipe' });
+    spinner.succeed('Production build successful');
+  } catch {
+    spinner.fail('Build failed.');
+    process.exit(1);
+  }
+
+  // 5. Security Audit
+  spinner.start('Running security audit...');
+  try {
+    execSync('npm audit', { cwd: projectRoot, stdio: 'pipe' });
+    spinner.succeed('Security audit passed');
+  } catch {
+    spinner.warn('Security vulnerabilities detected. Run `npm audit fix`.');
+  }
+
+  console.log(chalk.green.bold('\n✨ Project is production-ready!\n'));
+}