stackloom-cli 1.0.0

package/src/recipes/condition.js

@@ -0,0 +1,147 @@
+/**
+ * condition — a tiny, safe boolean-expression evaluator for recipe `when` rules.
+ *
+ * Supports identifiers (resolved from a flat context; missing = falsy),
+ * quoted string literals, `&&`, `||`, `!`, `==`, `!=`, and parentheses.
+ * Hand-written recursive-descent parser — no `eval`, no dependencies — so a
+ * recipe manifest can carry conditions without becoming a scripting surface.
+ *
+ *   evaluateCondition('withFrontend && usesTypeScript', ctx)
+ *   evaluateCondition('withTests || architecture == "advanced"', ctx)
+ */
+
+// Sticky tokenizer: leading whitespace, then one operator / paren / quoted
+// string / identifier. Identifiers allow `:`, `.`, `-` so `hasField:slug` works.
+const TOKEN = /\s*(\|\||&&|==|!=|!|\(|\)|"[^"]*"|'[^']*'|[\w:.\-]+)/y;
+
+function tokenize(input) {
+  const tokens = [];
+  let pos = 0;
+  while (pos < input.length) {
+    TOKEN.lastIndex = pos;
+    const match = TOKEN.exec(input);
+    if (!match || match.index !== pos) {
+      if (input.slice(pos).trim() === "") break;
+      throw new Error(`Cannot parse condition near "${input.slice(pos)}"`);
+    }
+    tokens.push(match[1]);
+    pos = TOKEN.lastIndex;
+  }
+  return tokens;
+}
+
+const OPERATORS = new Set(["||", "&&", "==", "!=", "!", "(", ")"]);
+
+function parse(tokens) {
+  let i = 0;
+  const peek = () => tokens[i];
+  const next = () => tokens[i++];
+
+  function parseOr() {
+    let node = parseAnd();
+    while (peek() === "||") {
+      next();
+      node = { op: "||", left: node, right: parseAnd() };
+    }
+    return node;
+  }
+
+  function parseAnd() {
+    let node = parseUnary();
+    while (peek() === "&&") {
+      next();
+      node = { op: "&&", left: node, right: parseUnary() };
+    }
+    return node;
+  }
+
+  function parseUnary() {
+    if (peek() === "!") {
+      next();
+      return { op: "!", operand: parseUnary() };
+    }
+    return parsePrimary();
+  }
+
+  function parsePrimary() {
+    if (peek() === "(") {
+      next();
+      const node = parseOr();
+      if (next() !== ")") throw new Error("Unbalanced parentheses in condition");
+      return node;
+    }
+    const left = parseAtom();
+    if (peek() === "==" || peek() === "!=") {
+      const op = next();
+      return { op, left, right: parseAtom() };
+    }
+    return left;
+  }
+
+  function parseAtom() {
+    const token = next();
+    if (token === undefined) throw new Error("Unexpected end of condition");
+    if (OPERATORS.has(token)) throw new Error(`Unexpected token "${token}" in condition`);
+    if (
+      (token.startsWith('"') && token.endsWith('"')) ||
+      (token.startsWith("'") && token.endsWith("'"))
+    ) {
+      return { type: "literal", value: token.slice(1, -1) };
+    }
+    return { type: "ident", name: token };
+  }
+
+  const ast = parseOr();
+  if (i < tokens.length) {
+    throw new Error(`Unexpected trailing token "${tokens[i]}" in condition`);
+  }
+  return ast;
+}
+
+function valueOf(node, ctx) {
+  if (node.type === "literal") return node.value;
+  if (node.type === "ident") return ctx[node.name];
+  return truthy(node, ctx);
+}
+
+function truthy(node, ctx) {
+  if (node.type === "literal") return Boolean(node.value);
+  if (node.type === "ident") return Boolean(ctx[node.name]);
+  switch (node.op) {
+    case "||":
+      return truthy(node.left, ctx) || truthy(node.right, ctx);
+    case "&&":
+      return truthy(node.left, ctx) && truthy(node.right, ctx);
+    case "!":
+      return !truthy(node.operand, ctx);
+    case "==":
+      return valueOf(node.left, ctx) === valueOf(node.right, ctx);
+    case "!=":
+      return valueOf(node.left, ctx) !== valueOf(node.right, ctx);
+    default:
+      throw new Error("Malformed condition node");
+  }
+}
+
+const astCache = new Map();
+
+/**
+ * Evaluate a recipe `when` expression against a flat context object.
+ * A missing/empty expression means "always" (returns true).
+ * @param {string|boolean|undefined} expr
+ * @param {Record<string, unknown>} ctx
+ * @returns {boolean}
+ */
+export function evaluateCondition(expr, ctx = {}) {
+  if (expr === undefined || expr === null || expr === "") return true;
+  if (typeof expr === "boolean") return expr;
+
+  let ast = astCache.get(expr);
+  if (!ast) {
+    const tokens = tokenize(String(expr).trim());
+    if (tokens.length === 0) return true;
+    ast = parse(tokens);
+    astCache.set(expr, ast);
+  }
+  return truthy(ast, ctx);
+}

package/src/recipes/index.js

@@ -0,0 +1,11 @@
+/**
+ * Recipe subsystem — declarative generation manifests.
+ *
+ * A recipe answers "what gets generated"; the blueprint answers "where it
+ * goes"; the engine just executes. New generation capabilities are new recipe
+ * JSON, not new engine code.
+ */
+export { Recipe } from "./recipe.js";
+export { RecipeLoader, RecipeLoadError, recipeLoader } from "./loader.js";
+export { recipeSchema } from "./schema.js";
+export { evaluateCondition } from "./condition.js";

package/src/recipes/loader.js

@@ -0,0 +1,95 @@
+/**
+ * RecipeLoader — resolves, reads, and validates a recipe by name.
+ *
+ * Resolution order:
+ *   1. A blueprint override — `blueprint.recipes[name]`, resolved relative to
+ *      the blueprint file's directory (lets a project ship custom recipes).
+ *   2. The CLI's built-in recipe — `recipes/builtin/<name>.json`.
+ *
+ * Every recipe is schema-validated before use, so a malformed manifest fails
+ * fast with a path-pointed error rather than producing broken output.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { recipeSchema } from "./schema.js";
+import { Recipe } from "./recipe.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUILTIN_RECIPES = path.join(__dirname, "builtin");
+
+/** Raised when a recipe cannot be found, read, or validated. */
+export class RecipeLoadError extends Error {
+  constructor(message, { source, issues } = {}) {
+    super(message);
+    this.name = "RecipeLoadError";
+    this.source = source;
+    this.issues = issues;
+  }
+}
+
+export class RecipeLoader {
+  /** Absolute path to the CLI's built-in recipe directory. */
+  get builtinDir() {
+    return BUILTIN_RECIPES;
+  }
+
+  /**
+   * Load a recipe by name, honoring any blueprint override.
+   * @param {string} name
+   * @param {import('../blueprint/blueprint.js').Blueprint} [blueprint]
+   */
+  async load(name, blueprint) {
+    const ref = blueprint ? blueprint.getRecipe(name) : null;
+    if (ref) {
+      const resolved = path.isAbsolute(ref)
+        ? ref
+        : path.resolve(path.dirname(blueprint.source), ref);
+      if (!existsSync(resolved)) {
+        throw new RecipeLoadError(
+          `Blueprint "${blueprint.id}" points recipe "${name}" at ${resolved}, which does not exist.`,
+          { source: resolved },
+        );
+      }
+      return this.loadFile(resolved);
+    }
+
+    const builtin = path.join(BUILTIN_RECIPES, `${name}.json`);
+    if (existsSync(builtin)) return this.loadFile(builtin);
+
+    throw new RecipeLoadError(
+      `No recipe named "${name}". Expected a built-in at ${builtin} or a blueprint override.`,
+      { source: builtin },
+    );
+  }
+
+  /** Load + validate a recipe from an explicit file path. */
+  async loadFile(source) {
+    let raw;
+    try {
+      raw = JSON.parse(await readFile(source, "utf-8"));
+    } catch (err) {
+      throw new RecipeLoadError(
+        `Could not read recipe JSON at ${source}: ${err.message}`,
+        { source },
+      );
+    }
+
+    const parsed = recipeSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map(
+        (i) => `  • ${i.path.join(".") || "(root)"}: ${i.message}`,
+      );
+      throw new RecipeLoadError(
+        `Invalid recipe at ${source}:\n${issues.join("\n")}`,
+        { source, issues: parsed.error.issues },
+      );
+    }
+
+    return new Recipe(parsed.data, source);
+  }
+}
+
+/** Shared loader instance for convenience. */
+export const recipeLoader = new RecipeLoader();

package/src/recipes/recipe.js

@@ -0,0 +1,89 @@
+/**
+ * Recipe — a validated generation manifest with behavior.
+ *
+ * `plan()` turns the declarative manifest into a concrete, resolved plan for a
+ * specific invocation: param defaults applied, `when` conditions evaluated,
+ * output paths rendered against the blueprint. The engine then just executes
+ * the plan — it never decides *what* to generate, only *how*.
+ */
+import { evaluateCondition } from "./condition.js";
+
+/** Substitute `{token}` placeholders from `values`; unknown tokens are left intact. */
+function interpolate(str, values) {
+  return str.replace(/\{([\w.-]+)\}/g, (match, key) =>
+    Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match,
+  );
+}
+
+export class Recipe {
+  /**
+   * @param {object} data - validated recipe data
+   * @param {string} source - absolute path the recipe was loaded from
+   */
+  constructor(data, source = "unknown") {
+    this.data = data;
+    this.source = source;
+  }
+
+  get name() {
+    return this.data.name;
+  }
+
+  get description() {
+    return this.data.description || "";
+  }
+
+  get params() {
+    return this.data.params;
+  }
+
+  /**
+   * Merge declared param defaults under a caller-supplied context. Caller values
+   * win; any param the caller omitted falls back to its declared default.
+   */
+  applyParamDefaults(context = {}) {
+    const out = { ...context };
+    for (const [key, spec] of Object.entries(this.data.params)) {
+      if (out[key] === undefined) out[key] = spec.default;
+    }
+    return out;
+  }
+
+  /**
+   * Resolve the manifest into a concrete plan for one invocation.
+   * @param {object} args
+   * @param {Record<string, unknown>} args.context - eval context (params + derived flags)
+   * @param {import('../blueprint/blueprint.js').Blueprint} [args.blueprint] - resolves `out` path tokens
+   * @param {string} [args.projectRoot] - project root for path resolution
+   * @param {Record<string, string>} [args.vars] - extra `{token}` substitutions (kebab, Name, ...)
+   * @returns {{ recipe: string, context: object, files: Array, inject: Array, requires: Array }}
+   */
+  plan({ context = {}, blueprint, projectRoot, vars = {} } = {}) {
+    const ctx = this.applyParamDefaults(context);
+    const keep = (entry) => evaluateCondition(entry.when, ctx);
+    const renderOut = (template) =>
+      blueprint ? blueprint.renderTemplate(template, projectRoot, vars) : template;
+    // Template *paths* may also carry `{token}`s — notably `{formMode}`, so one
+    // recipe entry resolves to the right page-shell variant per invocation.
+    const tokens = { ...ctx, ...vars };
+    const renderTemplatePath = (template) => interpolate(template, tokens);
+
+    const files = this.data.files.filter(keep).map((file) => ({
+      template: renderTemplatePath(file.template),
+      out: renderOut(file.out),
+    }));
+
+    const inject = this.data.inject.filter(keep).map((entry) => ({
+      anchor: entry.anchor,
+      template: renderTemplatePath(entry.template),
+    }));
+
+    const requires = this.data.requires.filter(keep).map((req) => ({
+      scope: req.scope,
+      package: req.package,
+      version: req.version,
+    }));
+
+    return { recipe: this.name, context: ctx, files, inject, requires };
+  }
+}

package/src/recipes/schema.js

@@ -0,0 +1,47 @@
+/**
+ * Recipe schema — a recipe is a *declarative* generation manifest.
+ *
+ * It lists exactly which files to render, which anchors to inject into, and
+ * which dependencies to add — each entry gated by an optional `when` condition.
+ * The engine emits only what a recipe asks for, so "zero bloat" is structural
+ * rather than aspirational.
+ */
+import { object, record, arrayOf, string, any } from "../blueprint/schema-kit.js";
+
+/** A declared input parameter (drives `when` conditions and template context). */
+const paramSchema = object({
+  type: string().default("string"),
+  default: any().optional(),
+  description: string().optional(),
+});
+
+/** One file to render: a template, an output path template, an optional gate. */
+const fileSchema = object({
+  template: string(),
+  out: string(),
+  when: string().optional(),
+});
+
+/** One injection: a blueprint anchor name + a snippet template, optional gate. */
+const injectSchema = object({
+  anchor: string(),
+  template: string(),
+  when: string().optional(),
+});
+
+/** One dependency requirement, scoped to a root (e.g. "backend"), optional gate. */
+const requireSchema = object({
+  scope: string(),
+  package: string(),
+  version: string(),
+  when: string().optional(),
+});
+
+export const recipeSchema = object({
+  name: string(),
+  description: string().optional(),
+  params: record(paramSchema).default({}),
+  files: arrayOf(fileSchema).default([]),
+  inject: arrayOf(injectSchema).default([]),
+  requires: arrayOf(requireSchema).default([]),
+});

package/src/schemas/__tests__/schemas.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { validateResourceDefinition, validateGenerateOptions } from "../index.js";
+
+describe("validateResourceDefinition", () => {
+  it("accepts a valid definition and fills defaults", () => {
+    const r = validateResourceDefinition({
+      name: "Product",
+      fields: [{ name: "title", type: "string", validation: { required: true } }],
+    });
+    expect(r.success).toBe(true);
+    expect(r.data.fields[0].type).toBe("string");
+    expect(r.data.relations).toEqual({});
+  });
+
+  it("rejects a missing name", () => {
+    const r = validateResourceDefinition({ fields: [] });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("name"))).toBe(true);
+  });
+
+  it("rejects a non-PascalCase name", () => {
+    const r = validateResourceDefinition({ name: "product", fields: [] });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("PascalCase"))).toBe(true);
+  });
+
+  it("rejects an unknown field type", () => {
+    const r = validateResourceDefinition({ name: "Product", fields: [{ name: "x", type: "wormhole" }] });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("type"))).toBe(true);
+  });
+
+  it("rejects duplicate field names", () => {
+    const r = validateResourceDefinition({
+      name: "Product",
+      fields: [{ name: "title" }, { name: "title" }],
+    });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("duplicate"))).toBe(true);
+  });
+
+  it("rejects an invalid field identifier", () => {
+    const r = validateResourceDefinition({ name: "Product", fields: [{ name: "2bad" }] });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("identifier"))).toBe(true);
+  });
+});
+
+describe("validateGenerateOptions", () => {
+  it("accepts valid options", () => {
+    expect(
+      validateGenerateOptions({ arch: "moderate", formMode: "modal", recipe: "resource" }).success,
+    ).toBe(true);
+  });
+
+  it("rejects unknown enum values", () => {
+    expect(validateGenerateOptions({ arch: "extreme" }).success).toBe(false);
+    expect(validateGenerateOptions({ formMode: "popover" }).success).toBe(false);
+    expect(validateGenerateOptions({ recipe: "widget" }).success).toBe(false);
+  });
+
+  it("rejects mutually exclusive --fields and --file", () => {
+    const r = validateGenerateOptions({ fields: "a:str", file: "x.js" });
+    expect(r.success).toBe(false);
+    expect(r.issues.some((i) => i.includes("mutually exclusive"))).toBe(true);
+  });
+});

package/src/schemas/index.js

@@ -0,0 +1,18 @@
+/**
+ * Schemas — strict validation for everything that enters the CLI from outside:
+ * resource-definition files, parsed field specs, and command options.
+ *
+ * Every validator returns a discriminated `{ success, ... }` result rather than
+ * throwing, so callers decide how to surface the typed error.
+ */
+export {
+  resourceDefinitionSchema,
+  validateResourceDefinition,
+  FIELD_TYPES,
+} from "./resource.js";
+export {
+  validateGenerateOptions,
+  ARCHITECTURES,
+  FORM_MODES,
+  RECIPES,
+} from "./options.js";

package/src/schemas/options.js

@@ -0,0 +1,38 @@
+/**
+ * Command-option validation — rejects bad CLI flags before any generation runs.
+ *
+ * Commander does presence/type; this does *domain* validity: an `--arch` or
+ * `--form-mode` that the engine doesn't support is caught here with a clear
+ * message, not discovered as a broken render later.
+ */
+
+export const ARCHITECTURES = ["lightweight", "moderate", "advanced"];
+export const FORM_MODES = ["page", "modal", "sidepanel", "inline"];
+export const RECIPES = ["resource", "module", "page"];
+
+/** A reusable "must be one of" check. */
+function oneOf(value, allowed, flag) {
+  if (value === undefined || value === null) return null;
+  if (!allowed.includes(value)) {
+    return `${flag} must be one of: ${allowed.join(", ")} (got "${value}")`;
+  }
+  return null;
+}
+
+/**
+ * Validate the options accepted by `loom generate <type>`.
+ * @returns {{ success: boolean, issues: string[] }}
+ */
+export function validateGenerateOptions(options = {}) {
+  const issues = [
+    oneOf(options.arch, ARCHITECTURES, "--arch"),
+    oneOf(options.formMode, FORM_MODES, "--form-mode"),
+    oneOf(options.recipe, RECIPES, "--recipe"),
+  ].filter(Boolean);
+
+  if (options.fields && options.file) {
+    issues.push("--fields and --file are mutually exclusive");
+  }
+
+  return { success: issues.length === 0, issues };
+}

package/src/schemas/resource.js

@@ -0,0 +1,112 @@
+/**
+ * Resource-definition schema — strict validation for `--file` definitions and
+ * the structures the field-spec parser produces.
+ *
+ * Replaces "parse, maybe warn, generate anyway" with "validate, fail fast with
+ * a path-pointed error". A bad definition never reaches the engine.
+ */
+import {
+  object,
+  record,
+  arrayOf,
+  string,
+  boolean,
+  number,
+  enumOf,
+  any,
+} from "../blueprint/schema-kit.js";
+
+/** Field types the generator understands (kept in sync with resource-definition.js). */
+export const FIELD_TYPES = [
+  "string",
+  "text",
+  "richtext",
+  "number",
+  "range",
+  "boolean",
+  "date",
+  "datetime",
+  "time",
+  "email",
+  "password",
+  "phone",
+  "url",
+  "color",
+  "ref",
+  "reference",
+  "array",
+  "object",
+  "image",
+  "file",
+  "select",
+  "multiselect",
+];
+
+const fieldSchema = object({
+  name: string(),
+  type: enumOf(...FIELD_TYPES).default("string"),
+  validation: object({
+    required: boolean().optional(),
+    unique: boolean().optional(),
+    min: number().optional(),
+    max: number().optional(),
+    minLength: number().optional(),
+    maxLength: number().optional(),
+    pattern: string().optional(),
+    default: any().optional(),
+  }).default({}),
+  special: record(any()).default({}),
+  ui: record(any()).default({}),
+});
+
+export const resourceDefinitionSchema = object({
+  name: string(),
+  collection: string().optional(),
+  fields: arrayOf(fieldSchema).default([]),
+  relations: record(any()).default({}),
+  features: record(any()).default({}),
+  ui: record(any()).default({}),
+  hooks: record(any()).default({}),
+  permissions: record(any()).default({}),
+  options: record(any()).default({}),
+});
+
+const IDENTIFIER = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+const PASCAL_CASE = /^[A-Z][a-zA-Z0-9]*$/;
+
+/**
+ * Validate a raw resource definition. Returns `{ success, data }` or
+ * `{ success: false, issues: string[] }`. Beyond the shape check it enforces
+ * the semantic rules the engine depends on: PascalCase name, identifier-safe
+ * unique field names.
+ */
+export function validateResourceDefinition(raw) {
+  const parsed = resourceDefinitionSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      success: false,
+      issues: parsed.error.issues.map(
+        (i) => `${i.path.join(".") || "(root)"}: ${i.message}`,
+      ),
+    };
+  }
+
+  const issues = [];
+  const { name, fields } = parsed.data;
+
+  if (!PASCAL_CASE.test(name)) {
+    issues.push(`name: "${name}" must be PascalCase (start uppercase, alphanumeric)`);
+  }
+  for (const field of fields) {
+    if (!IDENTIFIER.test(field.name)) {
+      issues.push(`fields: "${field.name}" is not a valid identifier`);
+    }
+  }
+  const names = fields.map((f) => f.name);
+  const duplicates = [...new Set(names.filter((n, i) => names.indexOf(n) !== i))];
+  if (duplicates.length) {
+    issues.push(`fields: duplicate field name(s): ${duplicates.join(", ")}`);
+  }
+
+  return issues.length ? { success: false, issues } : { success: true, data: parsed.data };
+}