makersclaw 0.1.0

package/src/fsutil.mjs

@@ -0,0 +1,76 @@
+// File helpers. Node's own fs and crypto only — the CLI has no
+// dependencies, so `npx makersclaw` costs one small download.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+
+/** sha256 of the bytes, hex — the same hash `npm run check` pins. */
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** The file's sha256, or null when there is no file. */
+export function hashFile(path) {
+  return existsSync(path) ? sha256(readFileSync(path)) : null;
+}
+
+const WALK_SKIP = new Set(["node_modules", ".next", ".next-check", ".git", ".DS_Store"]);
+
+/** Every file under `root`, relative to it, "/"-separated, sorted. */
+export function walk(root, sub = "") {
+  const out = [];
+  for (const name of readdirSync(join(root, sub))) {
+    if (WALK_SKIP.has(name)) continue;
+    const rel = sub ? `${sub}/${name}` : name;
+    if (statSync(join(root, rel)).isDirectory()) out.push(...walk(root, rel));
+    else out.push(rel);
+  }
+  return out.sort();
+}
+
+export function readJson(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function writeJson(path, value) {
+  writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** Write bytes, making the parent folders. */
+export function writeFile(path, bytes) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, bytes);
+}
+
+/** Remove a file, then every parent folder it leaves empty, stopping at
+ *  `stop` (never removed). */
+export function removeFile(path, stop) {
+  rmSync(path, { force: true });
+  let dir = dirname(path);
+  while (dir.startsWith(stop + sep) && dir !== stop) {
+    try {
+      if (readdirSync(dir).length > 0) break;
+      rmdirSync(dir);
+    } catch {
+      break;
+    }
+    dir = dirname(dir);
+  }
+}
+
+/** A glob with `*` (any run of characters but "/") as an anchored RegExp.
+ *  Everything else is literal — `app/s/[key]/page.jsx` means those brackets. */
+export function globToRegExp(glob) {
+  const body = glob
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[^/]*");
+  return new RegExp(`^${body}$`);
+}
+
+/** "/"-separated path from `root` to `path`. */
+export function rel(root, path) {
+  return relative(root, path).split(sep).join("/");
+}

package/src/install.mjs

@@ -0,0 +1,457 @@
+// What the commands do to an app folder. Every function returns a plain
+// result and prints nothing: src/cli.mjs says it, as text or as --json.
+//
+// Two files record what an app holds:
+//   makersclaw.json   the template and version it was laid from, and each
+//                     block with the version it came from
+//   check/pins.json   sha256 of every fixed file, the template's and the
+//                     blocks' — `npm run check` refuses one that differs
+//
+// Everything this CLI writes is FIXED (ours: pinned, replaced by update),
+// DOCS (ours, not pinned), a STARTER (laid when missing, the app's from
+// then on) or MERGED (package.json). The app's own files — the shell, the
+// surfaces, components/*.jsx — are never written.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hashFile, readJson, removeFile, sha256, walk, writeFile, writeJson } from "./fsutil.mjs";
+import { BLOCK_DIR, loadBlocks, loadItems, loadTemplate, packageInfo, readmeOf, suggest, templateNames } from "./registry.mjs";
+
+export const MANIFEST = "makersclaw.json";
+export const PINS = "check/pins.json";
+
+/** A refusal the user can act on: what is wrong, and what to run instead. */
+export class CliError extends Error {
+  constructor(message, next = null) {
+    super(message);
+    this.next = next;
+  }
+}
+
+const version = () => packageInfo().version;
+
+function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? ""));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+/** Same contract: the same major and — while the major is 0 — the same
+ *  minor. A patch never changes what a screen can rely on. */
+export function compatible(from, to) {
+  const a = parseVersion(from);
+  const b = parseVersion(to);
+  if (!a || !b) return false;
+  return a[0] === b[0] && (a[0] > 0 || a[1] === b[1]);
+}
+
+function newer(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  if (!x || !y) return false;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+}
+
+function sortKeys(obj) {
+  return Object.fromEntries(Object.entries(obj ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+function readState(dir) {
+  return { manifest: readJson(join(dir, MANIFEST)), pins: readJson(join(dir, PINS)) ?? {} };
+}
+
+function requireManifest(dir) {
+  const state = readState(dir);
+  if (!state.manifest) {
+    const hasApp = existsSync(join(dir, "package.json"));
+    throw new CliError(
+      `${dir} has no ${MANIFEST}` + (hasApp ? " — this app was laid before makersclaw, or by hand" : " — there is no app here"),
+      hasApp
+        ? "makersclaw update --adopt takes it on: this version's fixed files laid again and recorded, every screen of yours kept"
+        : "makersclaw init lays the template here",
+    );
+  }
+  return state;
+}
+
+function loadTemplateOrFail(name) {
+  const tpl = loadTemplate(name);
+  if (!tpl) throw new CliError(`this makersclaw has no template "${name}"`, `templates: ${templateNames().join(", ")}`);
+  return tpl;
+}
+
+/** package.json: the template's scripts and dependencies win for the keys
+ *  it names; every other key is the app's. */
+function mergePackage(app, tpl) {
+  const out = { ...app };
+  const changes = [];
+  for (const key of ["scripts", "dependencies", "devDependencies"]) {
+    if (!tpl[key]) continue;
+    out[key] = { ...(app[key] ?? {}) };
+    for (const [name, value] of Object.entries(tpl[key])) {
+      if (out[key][name] === value) continue;
+      changes.push({ key, name, from: out[key][name] ?? null, to: value });
+      out[key][name] = value;
+    }
+  }
+  return { out, changes };
+}
+
+/** Paths a template may remove when a newer version stops shipping them:
+ *  its fixed files and the kit, parts and block folders. Anything else a
+ *  pins.json names is left alone — it is not ours to delete. */
+function ownedPath(path, tpl) {
+  if (/^components\/(?:ui|parts|blocks)\//.test(path) || /^lib\/[^/]+\.js$/.test(path)) return true;
+  return tpl.files.some((f) => f.class === "fixed" && f.path === path);
+}
+
+/**
+ * Lay a template — and the blocks the app already has — over `dir`: the
+ * one routine behind init, init --force and update. Fixed files and docs
+ * are replaced; starters are laid only when missing; package.json is
+ * merged; blocks come again from this version; what an older version
+ * pinned and this one no longer ships is removed.
+ */
+function lay(dir, tpl, before) {
+  const v = version();
+  const written = [];
+  const kept = [];
+  const removed = [];
+  const notes = [];
+  let pkg = [];
+  const pins = {};
+  const fresh = !existsSync(join(dir, "package.json"));
+
+  for (const f of tpl.files) {
+    const to = join(dir, f.path);
+    if (f.class === "starter" && existsSync(to)) {
+      kept.push(f.path);
+      continue;
+    }
+    if (f.class === "merged" && existsSync(to)) {
+      const { out, changes } = mergePackage(readJson(to), readJson(f.from));
+      if (changes.length) {
+        writeJson(to, out);
+        written.push(f.path);
+      }
+      pkg = changes;
+      continue;
+    }
+    const bytes = readFileSync(f.from);
+    const hash = sha256(bytes);
+    if (hashFile(to) !== hash) {
+      writeFile(to, bytes);
+      written.push(f.path);
+    }
+    if (f.class === "fixed") pins[f.path] = hash;
+  }
+
+  const blocks = {};
+  const known = loadBlocks();
+  for (const [name, from] of Object.entries(before.manifest?.blocks ?? {})) {
+    if (!existsSync(join(dir, BLOCK_DIR, name))) {
+      notes.push(`${name}: its folder is gone — dropped from ${MANIFEST}`);
+      continue;
+    }
+    const block = known.find((b) => b.name === name);
+    if (!block) {
+      for (const [p, h] of Object.entries(before.pins)) if (p.startsWith(`${BLOCK_DIR}/${name}/`)) pins[p] = h;
+      blocks[name] = from;
+      notes.push(`${name}: not in makersclaw ${v} — left as installed (${from})`);
+      continue;
+    }
+    for (const f of block.files) {
+      const bytes = readFileSync(f.from);
+      const hash = sha256(bytes);
+      if (hashFile(join(dir, f.to)) !== hash) {
+        writeFile(join(dir, f.to), bytes);
+        written.push(f.to);
+      }
+      pins[f.to] = hash;
+    }
+    blocks[name] = v;
+  }
+
+  for (const p of Object.keys(before.pins)) {
+    if (p in pins) continue;
+    if (p.startsWith(`${BLOCK_DIR}/`) && !(p.split("/")[2] in blocks)) continue;
+    if (!ownedPath(p, tpl)) {
+      notes.push(`${p}: pinned before, not a template file — left alone`);
+      continue;
+    }
+    if (existsSync(join(dir, p))) {
+      removeFile(join(dir, p), dir);
+      removed.push(p);
+    }
+  }
+
+  writeJson(join(dir, PINS), sortKeys(pins));
+  writeJson(join(dir, MANIFEST), { template: tpl.name, version: v, blocks: sortKeys(blocks) });
+  return {
+    template: tpl.name,
+    version: v,
+    from: before.manifest?.version ?? null,
+    written,
+    kept,
+    removed,
+    package: pkg,
+    install: fresh || pkg.some((c) => c.key !== "scripts"),
+    pinned: Object.keys(pins).length,
+    blocks: Object.keys(blocks),
+    notes,
+  };
+}
+
+/** `init [dir] [-t next] [--force]` */
+export function init(dir, { template = "next", force = false } = {}) {
+  const tpl = loadTemplateOrFail(template);
+  const before = readState(dir);
+  if (existsSync(join(dir, "package.json")) && !force) {
+    throw new CliError(
+      `${dir} already holds an app`,
+      before.manifest
+        ? "makersclaw update lays this version over it"
+        : "makersclaw init --force lays the template over it: fixed files and docs are replaced, your own files stay",
+    );
+  }
+  if (before.manifest?.template && before.manifest.template !== template) {
+    throw new CliError(`this app was laid from template "${before.manifest.template}", not "${template}"`, `makersclaw init --force -t ${before.manifest.template}`);
+  }
+  return lay(dir, tpl, before);
+}
+
+/** `update [--major] [--adopt]` — this version's fixed files, docs and
+ *  blocks. `--adopt` takes on an app laid before makersclaw kept a
+ *  manifest — but only one from the kit's era (it has check/pins.json):
+ *  its screens were written against this kit, so laying the fixed files
+ *  again keeps them working. An older app drew its own controls; it needs
+ *  its screens rebuilt, not its files replaced. */
+export function update(dir, { major = false, adopt = false } = {}) {
+  if (adopt && !existsSync(join(dir, MANIFEST)) && existsSync(join(dir, "package.json"))) {
+    if (!existsSync(join(dir, PINS))) {
+      throw new CliError(
+        `${dir} was laid before the kit (no check/pins.json): its screens draw their own controls and colours`,
+        "rebuild it onto the template — its screens need writing again, not just its files replacing",
+      );
+    }
+    return { ...lay(dir, loadTemplateOrFail("next"), readState(dir)), adopted: true };
+  }
+  const before = requireManifest(dir);
+  const tpl = loadTemplateOrFail(before.manifest.template);
+  const v = version();
+  if (newer(before.manifest.version, v) && !major) {
+    throw new CliError(
+      `this app is on makersclaw ${before.manifest.version}, newer than this one (${v})`,
+      `run npx makersclaw@${before.manifest.version}, or update --major to go back`,
+    );
+  }
+  if (!compatible(before.manifest.version, v) && !major) {
+    throw new CliError(
+      `${before.manifest.version} → ${v} changes the template's contract; screens written against ${before.manifest.version} may not build`,
+      "makersclaw diff shows what changes; makersclaw update --major lays it anyway",
+    );
+  }
+  return lay(dir, tpl, before);
+}
+
+function importFor(item) {
+  if (item.type === "block") {
+    const names = item.exports?.length ? item.exports.join(", ") : "…";
+    return `import { ${names} } from "../components/blocks/${item.name}";`;
+  }
+  const folder = item.type === "part" ? "parts" : "ui";
+  return `import { ${item.title.split(",")[0].trim()} } from "../components/${folder}";`;
+}
+
+/** `add <name...>` — install blocks (and what they require), or restore a
+ *  kit component. Refuses an app on another version: a block assumes the
+ *  kit of its own version. */
+export function add(dir, names) {
+  if (names.length === 0) throw new CliError("name a block or a component to add", "makersclaw search <words> finds one by what it does");
+  const { manifest, pins } = requireManifest(dir);
+  const v = version();
+  if (manifest.version !== v) {
+    throw new CliError(
+      `this app is on makersclaw ${manifest.version}; this is ${v}, and a block assumes the kit of its own version`,
+      compatible(manifest.version, v) && !newer(manifest.version, v)
+        ? `makersclaw update first (${manifest.version} → ${v} is compatible), then add`
+        : `npx makersclaw@${manifest.version} add ${names.join(" ")}`,
+    );
+  }
+  const tpl = loadTemplateOrFail(manifest.template);
+  const items = loadItems(tpl);
+  const order = [];
+  const seen = new Set();
+  const visit = (name, by) => {
+    if (seen.has(name)) return;
+    const item = items.find((i) => i.name === name);
+    if (!item) {
+      const close = suggest(items, name);
+      throw new CliError(
+        `no block or component named "${name}"${by ? ` (${by} requires it)` : ""}`,
+        close.length ? `did you mean ${close.join(", ")}? makersclaw search <words> finds by what it does` : "makersclaw search <words> finds by what it does",
+      );
+    }
+    seen.add(name);
+    for (const r of item.requires) visit(r, name);
+    order.push(item);
+  };
+  for (const n of names) visit(n, null);
+
+  const added = [];
+  const deps = {};
+  for (const item of order) {
+    const files = [];
+    let changed = 0;
+    for (const f of item.files) {
+      const bytes = readFileSync(f.from);
+      const hash = sha256(bytes);
+      if (hashFile(join(dir, f.to)) !== hash) {
+        writeFile(join(dir, f.to), bytes);
+        changed++;
+      }
+      pins[f.to] = hash;
+      files.push(f.to);
+    }
+    if (item.type === "block") {
+      for (const p of Object.keys(pins)) {
+        if (p.startsWith(`${BLOCK_DIR}/${item.name}/`) && !files.includes(p)) {
+          removeFile(join(dir, p), dir);
+          delete pins[p];
+        }
+      }
+      manifest.blocks = { ...(manifest.blocks ?? {}), [item.name]: v };
+      Object.assign(deps, item.dependencies);
+    }
+    added.push({
+      name: item.name,
+      type: item.type,
+      files,
+      changed,
+      requested: names.includes(item.name),
+      import: importFor(item),
+    });
+  }
+
+  let pkg = [];
+  if (Object.keys(deps).length) {
+    const path = join(dir, "package.json");
+    const { out, changes } = mergePackage(readJson(path, {}), { dependencies: deps });
+    if (changes.length) writeJson(path, out);
+    pkg = changes;
+  }
+  writeJson(join(dir, PINS), sortKeys(pins));
+  writeJson(join(dir, MANIFEST), { ...manifest, blocks: sortKeys(manifest.blocks) });
+  return {
+    version: v,
+    added,
+    package: pkg,
+    install: pkg.length > 0,
+    usage: order.filter((i) => i.type === "block" && names.includes(i.name)).map((i) => ({ name: i.name, readme: readmeOf(i) })),
+  };
+}
+
+/** Files outside the block that import it: a surface still using a block
+ *  must not lose it. */
+function importersOf(dir, name) {
+  const needle = new RegExp(`blocks/${name}(?:["'/]|$)`, "m");
+  return walk(dir).filter(
+    (p) => /\.(?:jsx?|mjs)$/.test(p) && !p.startsWith(`${BLOCK_DIR}/${name}/`) && needle.test(readFileSync(join(dir, p), "utf8")),
+  );
+}
+
+/** `remove <block...>` — uninstall blocks nothing imports. */
+export function remove(dir, names) {
+  if (names.length === 0) throw new CliError("name a block to remove");
+  const { manifest, pins } = requireManifest(dir);
+  const tpl = loadTemplateOrFail(manifest.template);
+  const installed = manifest.blocks ?? {};
+  const known = loadBlocks();
+  const removed = [];
+  for (const name of names) {
+    if (tpl.components.some((c) => c.name === name)) throw new CliError(`${name} is part of the kit — every app has it`);
+    if (!installed[name]) {
+      throw new CliError(`${name} is not installed here`, `installed: ${Object.keys(installed).join(", ") || "no blocks"}`);
+    }
+    const dependents = Object.keys(installed).filter(
+      (other) => other !== name && !names.includes(other) && known.find((b) => b.name === other)?.requires.includes(name),
+    );
+    if (dependents.length) throw new CliError(`${dependents.join(", ")} requires ${name}`, `remove ${dependents.join(" ")} with it`);
+    const users = importersOf(dir, name);
+    if (users.length) {
+      throw new CliError(`${users.join(", ")} still import${users.length === 1 ? "s" : ""} ${name}`, "remove the import first — a surface that imports a missing block breaks the build");
+    }
+  }
+  for (const name of names) {
+    for (const p of Object.keys(pins)) {
+      if (!p.startsWith(`${BLOCK_DIR}/${name}/`)) continue;
+      removeFile(join(dir, p), dir);
+      delete pins[p];
+      removed.push(p);
+    }
+    delete installed[name];
+  }
+  writeJson(join(dir, PINS), sortKeys(pins));
+  writeJson(join(dir, MANIFEST), { ...manifest, blocks: sortKeys(installed) });
+  return { removed, blocks: Object.keys(installed) };
+}
+
+/**
+ * `diff` — what update would do, file by file, without doing it:
+ *   changed  the app has the old version's copy; this version's differs
+ *   edited   a fixed file no longer matches its pin (someone changed it)
+ *   missing  pinned, and gone from the app
+ *   new      this version ships a file the app never had
+ *   dropped  pinned by the old version, not shipped by this one
+ */
+export function diff(dir) {
+  const { manifest, pins } = requireManifest(dir);
+  const tpl = loadTemplateOrFail(manifest.template);
+  const v = version();
+  const entries = [];
+  const statusOf = (path, have, want, pinned) => {
+    if (have === want) return null;
+    if (have === null) return pinned ? "missing" : "new";
+    if (pinned && have !== pinned) return "edited";
+    return "changed";
+  };
+
+  for (const f of tpl.files) {
+    if (f.class !== "fixed" && f.class !== "docs") continue;
+    const status = statusOf(f.path, hashFile(join(dir, f.path)), sha256(readFileSync(f.from)), f.class === "fixed" ? pins[f.path] : null);
+    if (status) entries.push({ item: "template", path: f.path, status });
+  }
+  const shipped = new Set(tpl.files.map((f) => f.path));
+  for (const p of Object.keys(pins)) {
+    if (!p.startsWith(`${BLOCK_DIR}/`) && !shipped.has(p) && ownedPath(p, tpl)) entries.push({ item: "template", path: p, status: "dropped" });
+  }
+
+  const known = loadBlocks();
+  for (const name of Object.keys(manifest.blocks ?? {})) {
+    const block = known.find((b) => b.name === name);
+    if (!block) {
+      entries.push({ item: name, path: `${BLOCK_DIR}/${name}/`, status: "kept", detail: `not in makersclaw ${v}; update leaves it as installed` });
+      continue;
+    }
+    const files = new Set(block.files.map((f) => f.to));
+    for (const f of block.files) {
+      const status = statusOf(f.to, hashFile(join(dir, f.to)), sha256(readFileSync(f.from)), pins[f.to]);
+      if (status) entries.push({ item: name, path: f.to, status });
+    }
+    for (const p of Object.keys(pins)) {
+      if (p.startsWith(`${BLOCK_DIR}/${name}/`) && !files.has(p)) entries.push({ item: name, path: p, status: "dropped" });
+    }
+  }
+
+  const pkgPath = join(dir, "package.json");
+  const tplPkg = tpl.files.find((f) => f.class === "merged");
+  const pkg = existsSync(pkgPath) && tplPkg ? mergePackage(readJson(pkgPath), readJson(tplPkg.from)).changes : [];
+  return {
+    from: manifest.version,
+    to: v,
+    compatible: compatible(manifest.version, v) && !newer(manifest.version, v),
+    entries,
+    package: pkg,
+    blocks: manifest.blocks ?? {},
+  };
+}