stackloom-cli 1.0.0

package/src/blueprint/__tests__/blueprint.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { Blueprint, BlueprintLoader, BlueprintLoadError, blueprintLoader } from "../index.js";
+
+const tmp = (label) =>
+  path.join(os.tmpdir(), `${label}-${Math.random().toString(36).slice(2)}`);
+const writeJSON = (file, obj) => {
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(obj, null, 2));
+};
+const readJSON = (file) => JSON.parse(readFileSync(file, "utf-8"));
+
+describe("BlueprintLoader", () => {
+  it("falls back to the built-in MERN blueprint when a project has none", async () => {
+    const bp = await blueprintLoader.load(os.tmpdir());
+    expect(bp).toBeInstanceOf(Blueprint);
+    expect(bp.id).toBe("mern");
+    expect(bp.schemaVersion).toBe("1.0");
+    expect(bp.source).toBe(blueprintLoader.builtinPath);
+  });
+
+  it("rejects a blueprint that fails schema validation", async () => {
+    const file = `${tmp("bp-bad")}.json`;
+    writeJSON(file, { schemaVersion: "1.0", architecture: { id: "x" } });
+    await expect(blueprintLoader.loadFile(file)).rejects.toThrow(BlueprintLoadError);
+    rmSync(file, { force: true });
+  });
+
+  it("rejects an unsupported schemaVersion", async () => {
+    const file = `${tmp("bp-ver")}.json`;
+    writeJSON(file, { ...readJSON(blueprintLoader.builtinPath), schemaVersion: "99.0" });
+    await expect(blueprintLoader.loadFile(file)).rejects.toThrow(/schemaVersion/);
+    rmSync(file, { force: true });
+  });
+
+  it("prefers a project-local blueprint over the built-in", async () => {
+    const projectRoot = tmp("bp-proj");
+    const builtin = readJSON(blueprintLoader.builtinPath);
+    writeJSON(path.join(projectRoot, ".loom", "blueprint.json"), {
+      ...builtin,
+      architecture: { ...builtin.architecture, id: "custom" },
+    });
+
+    const bp = await new BlueprintLoader().load(projectRoot);
+    expect(bp.id).toBe("custom");
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+});
+
+describe("Blueprint", () => {
+  let projectRoot;
+  let bp;
+
+  beforeEach(async () => {
+    projectRoot = tmp("bp-test");
+    writeJSON(path.join(projectRoot, "backend", "package.json"), { name: "backend" });
+    mkdirSync(path.join(projectRoot, "frontend", "src"), { recursive: true });
+    writeFileSync(path.join(projectRoot, "frontend", "src", "main.jsx"), "");
+    bp = await blueprintLoader.load(projectRoot);
+  });
+
+  afterEach(() => {
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  it("resolves named roots via detect + marker", () => {
+    expect(bp.resolveRoot("backend", projectRoot)).toBe("backend");
+    expect(bp.resolveRoot("frontend", projectRoot)).toBe("frontend");
+  });
+
+  it("falls back to a root's default when no candidate matches", () => {
+    expect(bp.resolveRoot("frontend", tmp("bp-bare"))).toBe("frontend");
+  });
+
+  it("throws for an unknown root", () => {
+    expect(() => bp.resolveRoot("database", projectRoot)).toThrow(/no root named "database"/);
+  });
+
+  it("expands root tokens in path templates", () => {
+    expect(bp.resolvePath("backend.modules", projectRoot)).toBe(
+      path.join(projectRoot, "backend", "src", "modules"),
+    );
+  });
+
+  it("substitutes extra vars into path templates", () => {
+    expect(bp.expand("{backend}/src/modules/{kebab}", projectRoot, { kebab: "order" })).toBe(
+      "backend/src/modules/order",
+    );
+  });
+
+  it("throws for an unknown token", () => {
+    expect(() => bp.expand("{frontend}/{mystery}", projectRoot)).toThrow(/Unknown token/);
+  });
+
+  it("looks up injection anchors", () => {
+    expect(bp.hasAnchor("backend.routes")).toBe(true);
+    expect(bp.getAnchor("backend.routes").strategy).toBe("before-line");
+    expect(bp.resolveAnchorFile("backend.routes", projectRoot)).toBe(
+      path.join(projectRoot, "backend", "src", "routes", "index.js"),
+    );
+  });
+
+  it("detects language per the blueprint convention", () => {
+    expect(bp.usesTypeScript(projectRoot)).toBe(false);
+    writeFileSync(path.join(projectRoot, "frontend", "tsconfig.json"), "{}");
+    expect(new Blueprint(bp.data, bp.source).usesTypeScript(projectRoot)).toBe(true);
+  });
+});

package/src/blueprint/blueprint.js

@@ -0,0 +1,181 @@
+/**
+ * Blueprint — a validated architecture contract with behavior.
+ *
+ * Wraps the parsed `.loom/blueprint.json` data and exposes the operations the
+ * generation engine needs: resolving named roots/paths against a concrete
+ * project, looking up injection anchors, and detecting the project language.
+ *
+ * The engine talks only to this object — never to hardcoded "backend"/"frontend"
+ * strings — which is what lets a single engine serve many architectures.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export class Blueprint {
+  /**
+   * @param {import('./schema.js').BlueprintData} data - validated blueprint data
+   * @param {string} source - absolute path the blueprint was loaded from
+   */
+  constructor(data, source = "unknown") {
+    this.data = data;
+    this.source = source;
+    this._rootCache = new Map();
+  }
+
+  get schemaVersion() {
+    return this.data.schemaVersion;
+  }
+
+  get architecture() {
+    return this.data.architecture;
+  }
+
+  /** Short architecture id, e.g. "mern". */
+  get id() {
+    return this.data.architecture.id;
+  }
+
+  get conventions() {
+    return this.data.conventions;
+  }
+
+  /**
+   * Resolve a named root directory (e.g. "backend") to its concrete folder name
+   * within `projectRoot`. Walks `detect` candidates, confirms each with the
+   * root's `marker` file, and falls back to `default`.
+   * @returns {string} the resolved directory name (relative to projectRoot)
+   */
+  resolveRoot(name, projectRoot) {
+    const cacheKey = `${projectRoot}::${name}`;
+    if (this._rootCache.has(cacheKey)) return this._rootCache.get(cacheKey);
+
+    const root = this.data.roots[name];
+    if (!root) {
+      throw new Error(
+        `Blueprint "${this.id}" has no root named "${name}". ` +
+          `Known roots: ${Object.keys(this.data.roots).join(", ") || "(none)"}.`,
+      );
+    }
+
+    let resolved = root.default;
+    for (const candidate of root.detect) {
+      if (existsSync(path.join(projectRoot, candidate, root.marker))) {
+        resolved = candidate;
+        break;
+      }
+    }
+
+    this._rootCache.set(cacheKey, resolved);
+    return resolved;
+  }
+
+  /**
+   * Expand `{token}` placeholders in a template string. A token resolves from
+   * `vars` first, then from the blueprint's named roots.
+   */
+  expand(template, projectRoot, vars = {}) {
+    return template.replace(/\{([\w.]+)\}/g, (_match, token) => {
+      if (Object.prototype.hasOwnProperty.call(vars, token)) return vars[token];
+      if (this.data.roots[token]) return this.resolveRoot(token, projectRoot);
+      throw new Error(
+        `Unknown token "{${token}}" in blueprint template "${template}". ` +
+          `Provide it via vars or declare a root named "${token}".`,
+      );
+    });
+  }
+
+  /**
+   * Render a free-form template that may reference named blueprint paths as
+   * `{@path.name}`, directory roots as `{root}`, and caller-supplied `{vars}`.
+   * Returns a project-relative string (recipes join it onto the project root).
+   *
+   * Lets recipes say `{@backend.modules}/{kebab}/{Name}.js` instead of
+   * re-spelling `src/modules` — the blueprint stays the single source of truth.
+   */
+  renderTemplate(template, projectRoot, vars = {}) {
+    const withPaths = template.replace(/\{@([\w.-]+)\}/g, (_match, name) => {
+      const pathTemplate = this.data.paths[name];
+      if (!pathTemplate) {
+        throw new Error(
+          `Unknown blueprint path "@${name}" in template "${template}". ` +
+            `Known paths: ${Object.keys(this.data.paths).join(", ") || "(none)"}.`,
+        );
+      }
+      return pathTemplate;
+    });
+    return this.expand(withPaths, projectRoot, vars);
+  }
+
+  /**
+   * Resolve a named path template (e.g. "backend.modules") to an absolute path
+   * within `projectRoot`. Extra `vars` are substituted into `{token}` slots.
+   */
+  resolvePath(name, projectRoot, vars = {}) {
+    const template = this.data.paths[name];
+    if (!template) {
+      throw new Error(
+        `Blueprint "${this.id}" has no path named "${name}". ` +
+          `Known paths: ${Object.keys(this.data.paths).join(", ") || "(none)"}.`,
+      );
+    }
+    return path.join(projectRoot, this.expand(template, projectRoot, vars));
+  }
+
+  hasPath(name) {
+    return Boolean(this.data.paths[name]);
+  }
+
+  /** Look up a named injection anchor; throws if it is not declared. */
+  getAnchor(name) {
+    const anchor = this.data.anchors[name];
+    if (!anchor) {
+      throw new Error(
+        `Blueprint "${this.id}" has no anchor named "${name}". ` +
+          `Known anchors: ${Object.keys(this.data.anchors).join(", ") || "(none)"}.`,
+      );
+    }
+    return anchor;
+  }
+
+  hasAnchor(name) {
+    return Boolean(this.data.anchors[name]);
+  }
+
+  /** Resolve a named anchor's target file to an absolute path. */
+  resolveAnchorFile(name, projectRoot, vars = {}) {
+    return path.join(projectRoot, this.expand(this.getAnchor(name).file, projectRoot, vars));
+  }
+
+  /** Path to a named recipe manifest (relative to project root), or null. */
+  getRecipe(name) {
+    return this.data.recipes[name] || null;
+  }
+
+  /**
+   * Detect the language a project is written in, per the blueprint's
+   * `conventions.language` policy. Looks for a `tsconfig.json` in any root.
+   * @returns {"javascript"|"typescript"}
+   */
+  detectLanguage(projectRoot) {
+    const { detect, default: fallback } = this.data.conventions.language;
+    if (detect === "typescript") {
+      for (const name of Object.keys(this.data.roots)) {
+        const rootDir = this.resolveRoot(name, projectRoot);
+        if (existsSync(path.join(projectRoot, rootDir, "tsconfig.json"))) {
+          return "typescript";
+        }
+      }
+    }
+    return fallback;
+  }
+
+  /** True when the project resolved to TypeScript. */
+  usesTypeScript(projectRoot) {
+    return this.detectLanguage(projectRoot) === "typescript";
+  }
+
+  /** A compact, log-friendly summary. */
+  describe() {
+    return `${this.architecture.name} (id: ${this.id}, schema: ${this.schemaVersion}) from ${this.source}`;
+  }
+}

package/src/blueprint/default.blueprint.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": "1.0",
+  "architecture": {
+    "id": "mern",
+    "name": "MERN Fullstack Starter",
+    "description": "Express + MongoDB API with httpOnly refresh-token auth, React + Vite + Tailwind frontend."
+  },
+  "engine": {
+    "minCliVersion": "0.1.0"
+  },
+  "roots": {
+    "backend": {
+      "detect": ["backend", "api", "server", "be"],
+      "marker": "package.json",
+      "default": "backend"
+    },
+    "frontend": {
+      "detect": ["frontend", "client", "web", "app"],
+      "marker": "src/main.jsx",
+      "default": "frontend"
+    }
+  },
+  "conventions": {
+    "naming": {
+      "module": "kebab",
+      "component": "pascal",
+      "route": "kebab"
+    },
+    "language": {
+      "detect": "typescript",
+      "default": "javascript"
+    }
+  },
+  "paths": {
+    "backend.modules": "{backend}/src/modules",
+    "backend.routesIndex": "{backend}/src/routes/index.js",
+    "backend.validators": "{backend}/src/utils/validators",
+    "frontend.pages": "{frontend}/src/pages",
+    "frontend.adminPages": "{frontend}/src/pages/admin",
+    "frontend.components": "{frontend}/src/components",
+    "frontend.api": "{frontend}/src/api",
+    "frontend.hooks": "{frontend}/src/hooks",
+    "frontend.router": "{frontend}/src/routes/AppRouter.jsx",
+    "frontend.navConfig": "{frontend}/src/config/app-preset.js"
+  },
+  "anchors": {
+    "backend.routes": {
+      "file": "{backend}/src/routes/index.js",
+      "strategy": "before-line",
+      "pattern": "module.exports = router;",
+      "comment": "loom:anchor backend.routes"
+    },
+    "frontend.lazyImports": {
+      "file": "{frontend}/src/routes/AppRouter.jsx",
+      "strategy": "after-last-match",
+      "pattern": "^const \\w+ = lazy\\(.*\\);",
+      "comment": "loom:anchor frontend.lazyImports"
+    },
+    "frontend.routes": {
+      "file": "{frontend}/src/routes/AppRouter.jsx",
+      "strategy": "before-match",
+      "pattern": "<Route\\s+path=\"\\*\"",
+      "comment": "loom:anchor frontend.routes"
+    },
+    "frontend.nav": {
+      "file": "{frontend}/src/config/app-preset.js",
+      "strategy": "array-append",
+      "pattern": "navigation\\s*:\\s*\\[",
+      "comment": "loom:anchor frontend.nav"
+    }
+  },
+  "recipes": {},
+  "presets": {
+    "themes": "{frontend}/src/config/design-themes.js",
+    "layouts": "{frontend}/src/config/design-layouts.js",
+    "dataDisplay": "{frontend}/src/config/data-display-templates.js"
+  }
+}

package/src/blueprint/index.js

@@ -0,0 +1,10 @@
+/**
+ * Blueprint subsystem — the architecture contract layer.
+ *
+ * A blueprint describes *where things go* for a given stack so the generation
+ * engine stays architecture-agnostic. Adding support for a new architecture is
+ * a new `blueprint.json`, not an engine change.
+ */
+export { Blueprint } from "./blueprint.js";
+export { BlueprintLoader, BlueprintLoadError, blueprintLoader } from "./loader.js";
+export { blueprintSchema, SUPPORTED_SCHEMA_VERSIONS } from "./schema.js";

package/src/blueprint/loader.js

@@ -0,0 +1,101 @@
+/**
+ * BlueprintLoader — resolves, reads, and validates a blueprint for a project.
+ *
+ * Resolution is three-tier, highest priority first:
+ *   1. <project>/.loom/blueprint.json   — the template's own contract
+ *   2. ~/.loom/blueprint.json           — a user-global override
+ *   3. <cli>/default.blueprint.json    — the shipped MERN fallback
+ *
+ * Every blueprint is schema-validated before use, so a malformed manifest fails
+ * fast with a path-pointed error instead of producing broken code downstream.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { blueprintSchema, SUPPORTED_SCHEMA_VERSIONS } from "./schema.js";
+import { Blueprint } from "./blueprint.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HOME = os.homedir();
+const BUILTIN = path.join(__dirname, "default.blueprint.json");
+
+/** Raised when a blueprint cannot be read, fails schema validation, or is incompatible. */
+export class BlueprintLoadError extends Error {
+  constructor(message, { source, issues } = {}) {
+    super(message);
+    this.name = "BlueprintLoadError";
+    this.source = source;
+    this.issues = issues;
+  }
+}
+
+export class BlueprintLoader {
+  /** Candidate blueprint locations for a project, highest priority first. */
+  locations(projectRoot) {
+    return [
+      path.join(projectRoot, ".loom", "blueprint.json"),
+      path.join(HOME, ".loom", "blueprint.json"),
+      BUILTIN,
+    ];
+  }
+
+  /** Absolute path to the CLI's built-in fallback blueprint. */
+  get builtinPath() {
+    return BUILTIN;
+  }
+
+  /** First existing blueprint file for a project. Built-in is the guaranteed floor. */
+  resolve(projectRoot = process.cwd()) {
+    for (const loc of this.locations(projectRoot)) {
+      if (existsSync(loc)) return loc;
+    }
+    throw new BlueprintLoadError(
+      `No blueprint found and the built-in default is missing (expected at ${BUILTIN}).`,
+    );
+  }
+
+  /** Load + validate the effective blueprint for a project. */
+  async load(projectRoot = process.cwd()) {
+    return this.loadFile(this.resolve(projectRoot));
+  }
+
+  /** Load + validate a blueprint from an explicit file path. */
+  async loadFile(source) {
+    let raw;
+    try {
+      raw = JSON.parse(await readFile(source, "utf-8"));
+    } catch (err) {
+      throw new BlueprintLoadError(
+        `Could not read blueprint JSON at ${source}: ${err.message}`,
+        { source },
+      );
+    }
+
+    const parsed = blueprintSchema.safeParse(raw);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map(
+        (i) => `  • ${i.path.join(".") || "(root)"}: ${i.message}`,
+      );
+      throw new BlueprintLoadError(
+        `Invalid blueprint at ${source}:\n${issues.join("\n")}`,
+        { source, issues: parsed.error.issues },
+      );
+    }
+
+    if (!SUPPORTED_SCHEMA_VERSIONS.includes(parsed.data.schemaVersion)) {
+      throw new BlueprintLoadError(
+        `Blueprint at ${source} declares schemaVersion "${parsed.data.schemaVersion}", ` +
+          `but this CLI supports: ${SUPPORTED_SCHEMA_VERSIONS.join(", ")}. ` +
+          `Upgrade the CLI or the project's blueprint.`,
+        { source },
+      );
+    }
+
+    return new Blueprint(parsed.data, source);
+  }
+}
+
+/** Shared loader instance for convenience. */
+export const blueprintLoader = new BlueprintLoader();

package/src/blueprint/schema-kit.js

@@ -0,0 +1,161 @@
+/**
+ * schema-kit — a tiny, dependency-free schema validator.
+ *
+ * Scoped deliberately to what the CLI needs (objects, strings, enums, arrays,
+ * string-keyed records, optionals, defaults, path-pointed errors). The public
+ * surface — `.optional()`, `.default()`, `.safeParse()` returning
+ * `{ success, data, error: { issues } }` — mirrors zod, so a future swap to a
+ * heavier validation library is mechanical rather than invasive.
+ */
+
+const clone = (value) =>
+  value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+
+const typeOf = (value) =>
+  value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+
+class Schema {
+  /**
+   * @param {(value:any, path:Array<string|number>, ctx:{issues:Array}) => any} check
+   *   Validates/coerces a *present* value, pushing `{ path, message }` issues.
+   */
+  constructor(check) {
+    this._check = check;
+    this._isOptional = false;
+    this._hasDefault = false;
+    this._default = undefined;
+  }
+
+  optional() {
+    const next = this._copy();
+    next._isOptional = true;
+    return next;
+  }
+
+  default(value) {
+    const next = this._copy();
+    next._hasDefault = true;
+    next._default = value;
+    return next;
+  }
+
+  _copy() {
+    const next = new Schema(this._check);
+    next._isOptional = this._isOptional;
+    next._hasDefault = this._hasDefault;
+    next._default = this._default;
+    return next;
+  }
+
+  /** Resolve a value, applying default/optional rules before delegating to `_check`. */
+  _resolve(value, path, ctx) {
+    if (value === undefined) {
+      if (this._hasDefault) return this._check(clone(this._default), path, ctx);
+      if (this._isOptional) return undefined;
+      ctx.issues.push({ path: [...path], message: "Required" });
+      return undefined;
+    }
+    return this._check(value, path, ctx);
+  }
+
+  /** zod-shaped entry point: never throws, returns a discriminated result. */
+  safeParse(value) {
+    const ctx = { issues: [] };
+    const data = this._resolve(value, [], ctx);
+    if (ctx.issues.length) return { success: false, error: { issues: ctx.issues } };
+    return { success: true, data };
+  }
+}
+
+export function string() {
+  return new Schema((value, path, ctx) => {
+    if (typeof value !== "string") {
+      ctx.issues.push({ path: [...path], message: `Expected string, got ${typeOf(value)}` });
+    }
+    return value;
+  });
+}
+
+export function boolean() {
+  return new Schema((value, path, ctx) => {
+    if (typeof value !== "boolean") {
+      ctx.issues.push({ path: [...path], message: `Expected boolean, got ${typeOf(value)}` });
+    }
+    return value;
+  });
+}
+
+export function number() {
+  return new Schema((value, path, ctx) => {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      ctx.issues.push({ path: [...path], message: `Expected number, got ${typeOf(value)}` });
+    }
+    return value;
+  });
+}
+
+/** Accepts any present value as-is. Use sparingly — only where the shape is genuinely open. */
+export function any() {
+  return new Schema((value) => value);
+}
+
+export function enumOf(...values) {
+  return new Schema((value, path, ctx) => {
+    if (!values.includes(value)) {
+      ctx.issues.push({
+        path: [...path],
+        message: `Expected one of ${values.map((v) => `"${v}"`).join(", ")}, got ${JSON.stringify(value)}`,
+      });
+    }
+    return value;
+  });
+}
+
+export function arrayOf(item, { min = 0 } = {}) {
+  return new Schema((value, path, ctx) => {
+    if (!Array.isArray(value)) {
+      ctx.issues.push({ path: [...path], message: `Expected array, got ${typeOf(value)}` });
+      return value;
+    }
+    if (value.length < min) {
+      ctx.issues.push({
+        path: [...path],
+        message: `Expected at least ${min} item(s), got ${value.length}`,
+      });
+    }
+    return value.map((entry, i) => item._resolve(entry, [...path, i], ctx));
+  });
+}
+
+/** A string-keyed map where every value matches `valueSchema`. */
+export function record(valueSchema) {
+  return new Schema((value, path, ctx) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      ctx.issues.push({ path: [...path], message: `Expected object, got ${typeOf(value)}` });
+      return value;
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+      out[key] = valueSchema._resolve(entry, [...path, key], ctx);
+    }
+    return out;
+  });
+}
+
+/** A fixed-shape object. Unknown keys are dropped; missing keys defer to each field's rules. */
+export function object(shape) {
+  return new Schema((value, path, ctx) => {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      ctx.issues.push({ path: [...path], message: `Expected object, got ${typeOf(value)}` });
+      return value;
+    }
+    const out = {};
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      const resolved = fieldSchema._resolve(value[key], [...path, key], ctx);
+      if (resolved !== undefined) out[key] = resolved;
+    }
+    return out;
+  });
+}
+
+export { Schema };