stackloom-cli 1.0.0

package/src/services/__tests__/reporter.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import { Reporter, Clock, FixedClock, createServices, reporterFromOptions } from "../index.js";
+
+const fakeStream = () => ({
+  chunks: [],
+  isTTY: true,
+  write(s) {
+    this.chunks.push(s);
+    return true;
+  },
+  get text() {
+    return this.chunks.join("");
+  },
+});
+
+describe("Reporter", () => {
+  it("writes info to stdout and errors to stderr in normal mode", () => {
+    const out = fakeStream();
+    const err = fakeStream();
+    const r = new Reporter({ stdout: out, stderr: err, isTTY: true, env: {} });
+    expect(r.quiet).toBe(false);
+    r.info("hello");
+    r.success("done");
+    r.error("boom");
+    expect(out.text).toMatch(/hello/);
+    expect(out.text).toMatch(/done/);
+    expect(err.text).toMatch(/boom/);
+  });
+
+  it("suppresses info/success in quiet mode but keeps warn/error", () => {
+    const out = fakeStream();
+    const err = fakeStream();
+    const r = new Reporter({ stdout: out, stderr: err, quiet: true, isTTY: true, env: {} });
+    r.info("hidden");
+    r.success("hidden");
+    r.warn("careful");
+    r.error("boom");
+    expect(out.text).toBe("");
+    expect(err.text).toMatch(/careful/);
+    expect(err.text).toMatch(/boom/);
+  });
+
+  it("auto-enables quiet under CI and when piped (non-TTY)", () => {
+    expect(new Reporter({ stdout: fakeStream(), isTTY: true, env: { CI: "true" } }).quiet).toBe(true);
+    expect(new Reporter({ stdout: fakeStream(), isTTY: false, env: {} }).quiet).toBe(true);
+  });
+
+  it("emits structured output only through flush() in json mode", () => {
+    const out = fakeStream();
+    const err = fakeStream();
+    const r = new Reporter({ stdout: out, stderr: err, json: true, isTTY: true, env: {} });
+    r.info("hello");
+    r.error("boom");
+    r.result({ files: 3 });
+    expect(out.text).toBe("");
+    expect(err.text).toBe("");
+    r.flush();
+    const parsed = JSON.parse(out.text);
+    expect(parsed.result).toEqual({ files: 3 });
+    expect(parsed.events.some((e) => e.type === "info" && e.message === "hello")).toBe(true);
+    expect(parsed.events.some((e) => e.type === "error")).toBe(true);
+  });
+
+  it("colours for a TTY but not for NO_COLOR, json, or explicit off", () => {
+    expect(new Reporter({ stdout: fakeStream(), isTTY: true, env: {} }).color).toBe(true);
+    expect(new Reporter({ stdout: fakeStream(), isTTY: true, env: { NO_COLOR: "1" } }).color).toBe(false);
+    expect(new Reporter({ stdout: fakeStream(), isTTY: true, json: true, env: {} }).color).toBe(false);
+    expect(new Reporter({ stdout: fakeStream(), isTTY: true, color: false, env: {} }).color).toBe(false);
+  });
+
+  it("shows debug lines only when debug is enabled", () => {
+    const off = fakeStream();
+    new Reporter({ stdout: fakeStream(), stderr: off, isTTY: true, env: {} }).debug("trace");
+    expect(off.text).toBe("");
+    const on = fakeStream();
+    new Reporter({ stdout: fakeStream(), stderr: on, isTTY: true, debug: true, env: {} }).debug("trace");
+    expect(on.text).toMatch(/trace/);
+  });
+});
+
+describe("Clock", () => {
+  it("Clock.now() returns a Date; FixedClock is frozen", () => {
+    expect(new Clock().now()).toBeInstanceOf(Date);
+    expect(new FixedClock("2026-05-14T00:00:00.000Z").iso()).toBe("2026-05-14T00:00:00.000Z");
+  });
+});
+
+describe("service container", () => {
+  it("createServices builds a reporter + clock", () => {
+    const svc = createServices({ reporterOptions: { isTTY: true, env: {} } });
+    expect(svc.reporter).toBeInstanceOf(Reporter);
+    expect(svc.clock).toBeInstanceOf(Clock);
+  });
+
+  it("reporterFromOptions maps commander-style flags", () => {
+    expect(reporterFromOptions({ json: true }).jsonMode).toBe(true);
+  });
+});

package/src/services/clock.js

@@ -0,0 +1,31 @@
+/**
+ * Clock — an injectable time source.
+ *
+ * Generation records timestamps (marker headers, rollback state). Routing them
+ * through a Clock keeps those deterministic in tests instead of depending on
+ * the wall clock.
+ */
+export class Clock {
+  now() {
+    return new Date();
+  }
+
+  iso() {
+    return new Date().toISOString();
+  }
+}
+
+/** A Clock frozen at a fixed instant — for tests and reproducible runs. */
+export class FixedClock {
+  constructor(iso = "2026-01-01T00:00:00.000Z") {
+    this._iso = iso;
+  }
+
+  now() {
+    return new Date(this._iso);
+  }
+
+  iso() {
+    return this._iso;
+  }
+}

package/src/services/index.js

@@ -0,0 +1,43 @@
+/**
+ * Services — the CLI's injectable collaborators.
+ *
+ * Commands and the generation engine receive these rather than reaching for
+ * `console` / `process` / the wall clock directly. That keeps the core logic
+ * testable with fakes (composition over globals) and is the seam the
+ * transactional pipeline builds on.
+ */
+import { Reporter } from "./reporter.js";
+import { Clock } from "./clock.js";
+
+export { Reporter } from "./reporter.js";
+export { Clock, FixedClock } from "./clock.js";
+
+/**
+ * Build a service container. Pass overrides for tests; otherwise sensible
+ * real-world defaults are constructed.
+ * @param {object} [options]
+ * @param {Reporter} [options.reporter]
+ * @param {Clock} [options.clock]
+ * @param {object} [options.reporterOptions] - forwarded to `new Reporter(...)`
+ * @returns {{ reporter: Reporter, clock: Clock }}
+ */
+export function createServices(options = {}) {
+  return {
+    reporter: options.reporter ?? new Reporter(options.reporterOptions ?? {}),
+    clock: options.clock ?? new Clock(),
+  };
+}
+
+/**
+ * Build a Reporter from a command's parsed global options (commander style).
+ * `--no-color` arrives as `color: false`; CI/non-TTY still auto-quiets.
+ * @param {{ quiet?: boolean, json?: boolean, debug?: boolean, color?: boolean }} [opts]
+ */
+export function reporterFromOptions(opts = {}) {
+  return new Reporter({
+    quiet: Boolean(opts.quiet),
+    json: Boolean(opts.json),
+    debug: Boolean(opts.debug),
+    color: opts.color,
+  });
+}

package/src/services/reporter.js

@@ -0,0 +1,136 @@
+/**
+ * Reporter — the CLI's single output channel.
+ *
+ * Replaces scattered console.log / chalk / ora. Every command writes through a
+ * Reporter, so output respects --quiet, --json, --no-color and CI/non-TTY
+ * auto-detection uniformly. It is injectable: tests pass fake streams + env, so
+ * output is asserted, never captured from the real console.
+ *
+ * Behaviour:
+ *   - normal      → info+ to stdout, success/step shown, ANSI colour on a TTY
+ *   - --quiet     → only warnings + errors (to stderr); also auto-on for CI / non-TTY
+ *   - --json      → no human lines at all; structured events collected, emitted by flush()
+ *   - --debug     → debug lines shown (also via LOOM_DEBUG=true)
+ *
+ * Colour uses inline ANSI — no chalk dependency — keeping the CLI lightweight.
+ */
+
+const ANSI = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  gray: "\x1b[90m",
+};
+
+export class Reporter {
+  /**
+   * @param {object} [options]
+   * @param {NodeJS.WritableStream} [options.stdout]
+   * @param {NodeJS.WritableStream} [options.stderr]
+   * @param {boolean} [options.quiet]   - errors + warnings only
+   * @param {boolean} [options.json]    - structured output mode
+   * @param {boolean} [options.debug]   - show debug lines
+   * @param {boolean} [options.color]   - force colour on/off (default: auto)
+   * @param {boolean} [options.isTTY]   - override TTY detection (default: auto)
+   * @param {Record<string,string>} [options.env]
+   */
+  constructor({
+    stdout = process.stdout,
+    stderr = process.stderr,
+    quiet = false,
+    json = false,
+    debug = false,
+    color,
+    isTTY,
+    env = process.env,
+  } = {}) {
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.jsonMode = Boolean(json);
+    this.events = [];
+    this._result = null;
+
+    const ci = Boolean(env.CI && env.CI !== "false");
+    this.isTTY = isTTY ?? Boolean(stdout && stdout.isTTY);
+    // Quiet when asked, in JSON mode, under CI, or when piped (non-TTY).
+    this.quiet = this.jsonMode || quiet || ci || !this.isTTY;
+    this.debugEnabled = Boolean(debug) || env.LOOM_DEBUG === "true";
+    this.color = color ?? (!this.jsonMode && this.isTTY && !env.NO_COLOR);
+  }
+
+  _paint(code, text) {
+    return this.color ? `${code}${text}${ANSI.reset}` : text;
+  }
+
+  _line(stream, text) {
+    if (!this.jsonMode) stream.write(`${text}\n`);
+  }
+
+  _record(type, message, data) {
+    this.events.push({
+      type,
+      ...(message !== undefined ? { message } : {}),
+      ...(data !== undefined ? { data } : {}),
+    });
+  }
+
+  /** Normal informational output. Hidden in quiet/json mode. */
+  info(message, data) {
+    this._record("info", message, data);
+    if (!this.quiet) this._line(this.stdout, `${this._paint(ANSI.blue, "i")} ${message}`);
+  }
+
+  /** A positive outcome. Hidden in quiet/json mode. */
+  success(message, data) {
+    this._record("success", message, data);
+    if (!this.quiet) this._line(this.stdout, `${this._paint(ANSI.green, "✓")} ${message}`);
+  }
+
+  /** A progress step. Hidden in quiet/json mode. */
+  step(message, data) {
+    this._record("step", message, data);
+    if (!this.quiet) this._line(this.stdout, `${this._paint(ANSI.gray, "→")} ${message}`);
+  }
+
+  /** A warning — shown even in quiet mode (suppressed visually only in json mode). */
+  warn(message, data) {
+    this._record("warn", message, data);
+    this._line(this.stderr, `${this._paint(ANSI.yellow, "!")} ${message}`);
+  }
+
+  /** An error — shown even in quiet mode (suppressed visually only in json mode). */
+  error(message, data) {
+    this._record("error", message, data);
+    this._line(this.stderr, `${this._paint(ANSI.red, "✗")} ${message}`);
+  }
+
+  /** Diagnostic detail — shown only when debug is enabled. */
+  debug(message, data) {
+    this._record("debug", message, data);
+    if (this.debugEnabled && !this.quiet) {
+      this._line(this.stderr, this._paint(ANSI.gray, `· ${message}`));
+    }
+  }
+
+  /** Record a structured event with no human-facing line. */
+  event(type, data) {
+    this._record(type, undefined, data);
+  }
+
+  /** Set the command's final structured result (the payload for --json consumers). */
+  result(data) {
+    this._result = data;
+    this._record("result", undefined, data);
+  }
+
+  /** In --json mode, emit the collected structured output. Call once at command end. */
+  flush() {
+    if (this.jsonMode) {
+      this.stdout.write(
+        `${JSON.stringify({ events: this.events, result: this._result }, null, 2)}\n`,
+      );
+    }
+  }
+}

package/src/templates/resource/api.js.ejs

@@ -0,0 +1,39 @@
+import axiosInstance from './axiosInstance';
+
+/**
+ * <%= resource.pascalName %> API
+ * Auto-generated by Stackloom CLI
+ */
+
+export const getAll<%= resource.pluralPascal %> = async (params = {}) => {
+  const response = await axiosInstance.get('/<%= resource.pluralKebab %>', { params });
+  return response.data;
+};
+
+export const get<%= resource.pascalName %>ById = async (id) => {
+  const response = await axiosInstance.get(`/<%= resource.pluralKebab %>/${id}`);
+  return response.data;
+};
+
+export const create<%= resource.pascalName %> = async (data) => {
+  const response = await axiosInstance.post('/<%= resource.pluralKebab %>', data);
+  return response.data;
+};
+
+export const update<%= resource.pascalName %> = async (id, data) => {
+  const response = await axiosInstance.put(`/<%= resource.pluralKebab %>/${id}`, data);
+  return response.data;
+};
+
+export const delete<%= resource.pascalName %> = async (id) => {
+  const response = await axiosInstance.delete(`/<%= resource.pluralKebab %>/${id}`);
+  return response.data;
+};
+
+export default {
+  getAll: getAll<%= resource.pluralPascal %>,
+  getById: get<%= resource.pascalName %>ById,
+  create: create<%= resource.pascalName %>,
+  update: update<%= resource.pascalName %>,
+  delete: delete<%= resource.pascalName %>,
+};

package/src/templates/resource/components/form.jsx.ejs

@@ -0,0 +1,81 @@
+import React from 'react';
+import { useForm } from "react-hook-form";
+import { Button } from "@/components/ui/button";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+
+// NOTE: the EJS loop variable is `f` (the resource field definition); the
+// react-hook-form render prop is `field` (the runtime form field). Keeping them
+// distinct avoids the shadowing bug where `f.type` checks silently read the RHF
+// object instead of the field definition.
+export const <%= resource.pascalName %>Form = ({ initialData, onSubmit, onCancel, isLoading }) => {
+  const form = useForm({
+    defaultValues: initialData || {
+<% resource.fields.forEach(function(f) { -%>
+      <%- f.name %>: <%- f.type === 'boolean' ? 'false' : f.type === 'number' ? '0' : "''" %>,
+<% }); -%>
+    },
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+<% resource.fields.forEach(function(f) { -%>
+        <FormField
+          control={form.control}
+          name="<%- f.name %>"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel><%- f.name.charAt(0).toUpperCase() + f.name.slice(1) %></FormLabel>
+              <FormControl>
+<% if (f.type === 'boolean') { -%>
+                <Checkbox checked={field.value} onCheckedChange={field.onChange} />
+<% } else if ((f.type === 'select' || f.type === 'multiselect') && f.special && f.special.options) { -%>
+                <Select onValueChange={field.onChange} defaultValue={field.value}>
+                  <SelectTrigger>
+                    <SelectValue placeholder="Select <%- f.name %>" />
+                  </SelectTrigger>
+                  <SelectContent>
+<% f.special.options.forEach(function(opt) { -%>
+                    <SelectItem value="<%- opt %>"><%- opt %></SelectItem>
+<% }); -%>
+                  </SelectContent>
+                </Select>
+<% } else { -%>
+                <Input type="<%- f.formInputType %>" {...field} disabled={isLoading} />
+<% } -%>
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+<% }); -%>
+        <div className="flex justify-end gap-2 pt-4">
+          {onCancel && (
+            <Button type="button" variant="outline" onClick={onCancel} disabled={isLoading}>
+              Cancel
+            </Button>
+          )}
+          <Button type="submit" disabled={isLoading}>
+            {initialData ? 'Update' : 'Create'} <%= resource.name %>
+          </Button>
+        </div>
+      </form>
+    </Form>
+  );
+};

package/src/templates/resource/components/table.jsx.ejs

@@ -0,0 +1,68 @@
+import React from 'react';
+import { 
+  Table, 
+  TableBody, 
+  TableCell, 
+  TableHead, 
+  TableHeader, 
+  TableRow 
+} from "@/components/ui/table";
+import { Button } from "@/components/ui/button";
+import { Edit, Trash2, Eye } from "lucide-react";
+
+export const <%= resource.pascalName %>Table = ({ data, onEdit, onDelete, onView }) => {
+  if (!data || data.length === 0) {
+    return <div className="text-center py-10 text-muted-foreground">No <%= resource.pluralPascal.toLowerCase() %> found.</div>;
+  }
+
+  return (
+    <div className="rounded-md border">
+      <Table>
+         <TableHeader>
+           <TableRow>
+             <% resource.fields.filter(f => f.ui.showInTable !== false).forEach(function(field) { %>
+             <TableHead><%- field.name.charAt(0).toUpperCase() + field.name.slice(1) %></TableHead>
+             <% }); %>
+             <TableHead className="text-right">Actions</TableHead>
+           </TableRow>
+         </TableHeader>
+         <TableBody>
+           {data.map((item) => (
+             <TableRow key={item._id}>
+               <% resource.fields.filter(f => f.ui.showInTable !== false).forEach(function(field) { %>
+               <TableCell>
+                 {<% if (field.type === 'boolean') { %>
+                   item.<%- field.name %> ? 'Yes' : 'No'
+                 <% } else if (field.type === 'date' || field.type === 'datetime') { %>
+                   new Date(item.<%- field.name %>).toLocaleDateString()
+                 <% } else { %>
+                   item.<%- field.name %>
+                 <% } %>}
+               </TableCell>
+               <% }); %>
+              <TableCell className="text-right">
+                <div className="flex justify-end gap-2">
+                  {onView && (
+                    <Button variant="ghost" size="icon" onClick={() => onView(item)}>
+                      <Eye className="h-4 w-4" />
+                    </Button>
+                  )}
+                  {onEdit && (
+                    <Button variant="ghost" size="icon" onClick={() => onEdit(item)}>
+                      <Edit className="h-4 w-4" />
+                    </Button>
+                  )}
+                  {onDelete && (
+                    <Button variant="ghost" size="icon" className="text-destructive" onClick={() => onDelete(item)}>
+                      <Trash2 className="h-4 w-4" />
+                    </Button>
+                  )}
+                </div>
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+};

package/src/templates/resource/controller.js.ejs

@@ -0,0 +1,154 @@
+<% if (options.architecture === 'lightweight') { -%>
+// Lightweight architecture — CRUD logic lives inline here; no separate service layer.
+const <%= resource.pascalName %> = require('../models/<%= resource.name %>');
+const ApiResponse = require('../../../utils/ApiResponse');
+const ApiError = require('../../../utils/ApiError');
+
+// ── Create ───────────────────────────────────────────────────────────────────
+const create = async (req, res, next) => {
+  try {
+<% if (resource.features && resource.features.auditLog) { -%>
+    req.body.createdBy = req.user?._id;
+<% } -%>
+    const result = await <%= resource.pascalName %>.create(req.body);
+    return res.status(201).json(new ApiResponse(201, '<%= resource.pascalName %> created', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── List (paginated) ─────────────────────────────────────────────────────────
+const list = async (req, res, next) => {
+  try {
+    const page = parseInt(req.query.page, 10) || 1;
+    const limit = parseInt(req.query.limit, 10) || 20;
+    const [data, total] = await Promise.all([
+      <%= resource.pascalName %>.find()
+        .sort({ [req.query.sort || 'createdAt']: req.query.order === 'asc' ? 1 : -1 })
+        .skip((page - 1) * limit)
+        .limit(limit)
+        .lean(),
+      <%= resource.pascalName %>.countDocuments(),
+    ]);
+    return res.status(200).json(
+      new ApiResponse(200, 'Fetched', { data, total, page, limit, pages: Math.ceil(total / limit) }).body,
+    );
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Get One ──────────────────────────────────────────────────────────────────
+const getOne = async (req, res, next) => {
+  try {
+    const result = await <%= resource.pascalName %>.findById(req.params.id);
+    if (!result) throw new ApiError(404, '<%= resource.pascalName %> not found');
+    return res.status(200).json(new ApiResponse(200, 'Fetched', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Update ───────────────────────────────────────────────────────────────────
+const update = async (req, res, next) => {
+  try {
+<% if (resource.features && resource.features.auditLog) { -%>
+    req.body.updatedBy = req.user?._id;
+<% } -%>
+    const result = await <%= resource.pascalName %>.findByIdAndUpdate(req.params.id, req.body, {
+      new: true,
+      runValidators: true,
+    });
+    if (!result) throw new ApiError(404, '<%= resource.pascalName %> not found');
+    return res.status(200).json(new ApiResponse(200, 'Updated', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Delete ───────────────────────────────────────────────────────────────────
+const remove = async (req, res, next) => {
+  try {
+    const result = await <%= resource.pascalName %>.findByIdAndDelete(req.params.id);
+    if (!result) throw new ApiError(404, '<%= resource.pascalName %> not found');
+    return res.status(200).json(new ApiResponse(200, 'Deleted').body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+module.exports = { create, list, getOne, update, remove };
+<% } else { -%>
+// Layered architecture — the controller is thin; domain logic lives in the service.
+const service = require('../services/<%= resource.name %>.service');
+const ApiResponse = require('../../../utils/ApiResponse');
+
+// ── Create ───────────────────────────────────────────────────────────────────
+const create = async (req, res, next) => {
+  try {
+<% if (resource.features && resource.features.auditLog) { -%>
+    req.body.createdBy = req.user?._id;
+<% } -%>
+    const result = await service.create<%= resource.pascalName %>(req.body);
+    return res.status(201).json(new ApiResponse(201, '<%= resource.pascalName %> created', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── List (with pagination, filtering, sorting) ───────────────────────────────
+const list = async (req, res, next) => {
+  try {
+    const { page = 1, limit = 20, sort = 'createdAt', order = 'desc' } = req.query;
+    const filters = {
+      page: parseInt(page, 10),
+      limit: parseInt(limit, 10),
+      sort,
+      order,
+<% resource.fields.forEach(function(f) { -%>
+      <%= f.name %>: req.query.<%= f.name %>,
+<% }); -%>
+      populate: req.query.populate ? req.query.populate.split(',') : [],
+    };
+    const result = await service.getAll<%= resource.pascalName %>s(filters);
+    return res.status(200).json(new ApiResponse(200, 'Fetched', result).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Get One ──────────────────────────────────────────────────────────────────
+const getOne = async (req, res, next) => {
+  try {
+    const result = await service.get<%= resource.pascalName %>ById(req.params.id);
+    return res.status(200).json(new ApiResponse(200, 'Fetched', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Update ───────────────────────────────────────────────────────────────────
+const update = async (req, res, next) => {
+  try {
+<% if (resource.features && resource.features.auditLog) { -%>
+    req.body.updatedBy = req.user?._id;
+<% } -%>
+    const result = await service.update<%= resource.pascalName %>(req.params.id, req.body);
+    return res.status(200).json(new ApiResponse(200, 'Updated', { data: result }).body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+// ── Delete ───────────────────────────────────────────────────────────────────
+const remove = async (req, res, next) => {
+  try {
+    await service.delete<%= resource.pascalName %>(req.params.id);
+    return res.status(200).json(new ApiResponse(200, 'Deleted').body);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+module.exports = { create, list, getOne, update, remove };
+<% } -%>