wand-decks-kit 0.8.0

package/tools/extract.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+extract.py — Phase 0 + Phase 1 in one pass.
+
+    python tools/extract.py source.pptx -o work/
+
+Writes into the output directory:
+    visible_dump.txt   every verbatim string, one per line — the Phase 4 contract
+    all_text.json      per-slide, per-frame, per-paragraph structure
+    geometry.txt       every shape, normalised to the 10" x 5.625" grid
+    deck.skeleton.json a spec stub with one entry per slide, layout: "TODO"
+
+Why normalisation matters: source decks are usually 13.333" x 7.5" (Google
+Slides / PowerPoint widescreen default). The Wand system is 10" x 5.625". Every
+measurement taken off a source deck must be divided by the scale factor before
+it means anything, and doing that by hand is where errors come from.
+"""
+
+import argparse, json, os, re, sys, zipfile
+
+def _brand_lib():
+    """brand/lib in the repo, or lib/ beside the kit once packaged."""
+    import os
+    here = os.path.dirname(os.path.abspath(__file__))
+    for d in filter(None, [os.environ.get("WAND_BRAND_DIR"),
+                           os.path.join(here, "lib"),
+                           os.path.join(here, "..", "lib"),
+                           os.path.join(here, "..", "..", "..", "..", "brand", "lib"),
+                           os.path.join(here, "..", "..", "..", "brand", "lib")]):
+        if os.path.isfile(os.path.join(d, "wandxml.py")):
+            return os.path.normpath(d)
+    raise SystemExit("brand/lib not found")
+
+sys.path.insert(0, _brand_lib())
+import wandxml
+
+EMU = 914400.0
+TARGET_W, TARGET_H = 10.0, 5.625
+
+
+def slide_names(z):
+    return sorted(
+        (n for n in z.namelist() if re.fullmatch(r"ppt/slides/slide\d+\.xml", n)),
+        key=lambda n: int(re.findall(r"\d+", n)[0]),
+    )
+
+
+def canvas(z):
+    d = wandxml.parse(z.read("ppt/presentation.xml"))
+    sz = d.getElementsByTagName("p:sldSz")[0]
+    return int(sz.getAttribute("cx")) / EMU, int(sz.getAttribute("cy")) / EMU
+
+
+def para_text(p):
+    return "".join(t.firstChild.nodeValue for t in p.getElementsByTagName("a:t") if t.firstChild)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("pptx")
+    ap.add_argument("-o", "--out", default="work")
+    a = ap.parse_args()
+    os.makedirs(a.out, exist_ok=True)
+
+    z = zipfile.ZipFile(a.pptx)
+    cw, ch = canvas(z)
+    scale = TARGET_W / cw
+    names = slide_names(z)
+
+    print(f"source canvas : {cw:.3f}\" x {ch:.3f}\"")
+    if abs(scale - 1.0) > 1e-6:
+        print(f"scale to grid : x{scale:.4f}  (divide every source measurement by {1/scale:.4f})")
+    else:
+        print("scale to grid : 1.0 — already on the Wand grid")
+
+    all_text, dump, geo, analysis = {}, [], [], []
+    hidden = 0
+
+    for name in names:
+        i = int(re.findall(r"\d+", name)[0])
+        d = wandxml.parse(z.read(name))
+        is_hidden = d.documentElement.getAttribute("show") == "0"
+        if is_hidden:
+            hidden += 1
+
+        frames = []
+        for b in d.getElementsByTagName("p:txBody"):
+            paras = [para_text(p) for p in b.getElementsByTagName("a:p")]
+            paras = [p for p in paras if p.strip()]
+            if paras:
+                frames.append(paras)
+                if not is_hidden:
+                    dump.extend(p.strip() for p in paras)
+        all_text[i] = {"hidden": is_hidden, "frames": frames}
+
+        shapes = []
+        for tag in ("p:sp", "p:pic"):
+            for sp in d.getElementsByTagName(tag):
+                off = sp.getElementsByTagName("a:off")
+                ext = sp.getElementsByTagName("a:ext")
+                if not off or not ext:
+                    continue
+                try:
+                    x = int(off[0].getAttribute("x")) / EMU * scale
+                    y = int(off[0].getAttribute("y")) / EMU * scale
+                    w = int(ext[0].getAttribute("cx")) / EMU * scale
+                    h = int(ext[0].getAttribute("cy")) / EMU * scale
+                except ValueError:
+                    continue   # a placeholder inherits its box; nothing to measure here
+                prst = sp.getElementsByTagName("a:prstGeom")
+                g = prst[0].getAttribute("prst") if prst else ("pic" if tag == "p:pic" else "?")
+                t = "".join(para_text(p) for p in sp.getElementsByTagName("a:p"))[:48]
+                shapes.append((round(x, 2), round(y, 2), round(w, 2), round(h, 2), g, t.replace("\n", " ")))
+        geo.append((i, is_hidden, sorted(shapes, key=lambda s: (s[1], s[0]))))
+
+        # Phase 2 input: text frames with the geometry and size that make a
+        # title a title. Classification without this is guessing from word
+        # count, which is how a stat slide becomes a bullet list.
+        tf, pics = [], 0
+        for sp in d.getElementsByTagName("p:pic"):
+            pics += 1
+        for sp in d.getElementsByTagName("p:sp"):
+            bodies = sp.getElementsByTagName("p:txBody")
+            if not bodies:
+                continue
+            paras = [t for t in (para_text(p) for p in bodies[0].getElementsByTagName("a:p")) if t.strip()]
+            if not paras:
+                continue
+            off = sp.getElementsByTagName("a:off")
+            ext = sp.getElementsByTagName("a:ext")
+            box = None
+            if off and ext:
+                try:
+                    box = [round(int(off[0].getAttribute("x")) / EMU * scale, 2),
+                           round(int(off[0].getAttribute("y")) / EMU * scale, 2),
+                           round(int(ext[0].getAttribute("cx")) / EMU * scale, 2),
+                           round(int(ext[0].getAttribute("cy")) / EMU * scale, 2)]
+                except ValueError:
+                    box = None
+            sizes = [int(r.getAttribute("sz")) / 100.0 * scale
+                     for r in sp.getElementsByTagName("a:rPr") if r.getAttribute("sz")]
+            bold = any(r.getAttribute("b") == "1" for r in sp.getElementsByTagName("a:rPr"))
+            tf.append({"box": box, "pt": round(max(sizes), 1) if sizes else None,
+                       "bold": bold, "paras": paras})
+        # theme, read rather than guessed: a Wand dark slide is a solid
+        # 0F0C26 background, a light one F8F6FB with no art
+        bg = None
+        for b in d.getElementsByTagName("p:bg"):
+            for c in b.getElementsByTagName("a:srgbClr"):
+                bg = c.getAttribute("val").upper()
+                break
+        analysis.append({"slide": i, "hidden": is_hidden, "pics": pics, "bg": bg,
+                         "shapes": len(shapes), "frames": tf})
+
+    # de-duplicate the dump while preserving order
+    seen, ded = set(), []
+    for s in dump:
+        if s not in seen:
+            seen.add(s)
+            ded.append(s)
+
+    with open(os.path.join(a.out, "visible_dump.txt"), "w", encoding="utf-8") as f:
+        f.write("\n".join(ded))
+    with open(os.path.join(a.out, "all_text.json"), "w", encoding="utf-8") as f:
+        json.dump(all_text, f, indent=1, ensure_ascii=False)
+    with open(os.path.join(a.out, "geometry.txt"), "w", encoding="utf-8") as f:
+        f.write(f"# normalised to {TARGET_W}\" x {TARGET_H}\" (source {cw:.3f}\" x {ch:.3f}\", scale x{scale:.4f})\n")
+        for i, hid, shapes in geo:
+            f.write(f"\n--- slide{i}{'  [HIDDEN]' if hid else ''}  ({len(shapes)} shapes)\n")
+            for s in shapes:
+                f.write(f"   x{s[0]:<6}y{s[1]:<6}w{s[2]:<6}h{s[3]:<6}{s[4]:<12}{s[5]}\n")
+
+    skeleton = {
+        "deck": os.path.splitext(os.path.basename(a.pptx))[0].replace("_", " ").upper(),
+        "confidential": "CONFIDENTIAL",
+        "slides": [
+            {
+                "layout": "TODO",
+                "_source": i,
+                "_shapes": len(sh),
+                "_text": [p for fr in all_text[i]["frames"] for p in fr][:6],
+            }
+            for i, hid, sh in geo if not hid
+        ],
+    }
+    with open(os.path.join(a.out, "deck.skeleton.json"), "w", encoding="utf-8") as f:
+        json.dump(skeleton, f, indent=2, ensure_ascii=False)
+    with open(os.path.join(a.out, "analysis.json"), "w", encoding="utf-8") as f:
+        json.dump({"source": os.path.basename(a.pptx),
+                   "canvas": [round(cw, 3), round(ch, 3)], "scale": round(scale, 4),
+                   "slides": analysis}, f, indent=1, ensure_ascii=False)
+
+    print(f"slides        : {len(names)} in source, {len(names) - hidden} visible")
+    print(f"strings       : {len(ded)} unique verbatim")
+    print(f"written       : {a.out}/  visible_dump.txt  all_text.json  geometry.txt  analysis.json  deck.skeleton.json")
+
+
+if __name__ == "__main__":
+    main()

package/wand.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+/**
+ * wand.js - the engine's front door.
+ *
+ * The kit is meant to arrive as a zip next to a .pptx, in a container that may
+ * have nothing installed and will be thrown away afterwards. Everything below
+ * assumes that: no global installs, no network, no LibreOffice, and an operator
+ * who has read one file.
+ *
+ *   node wand.js doctor                      what works here, and what does not
+ *   node wand.js rebuild source.pptx         phases 0-3: extract, then the worksheet
+ *   node wand.js layouts [name]              the catalog, with every field
+  node wand.js glyphs  [search]            the named icon set
+ *   node wand.js validate work/deck.json     fields and counts, before the build
+ *   node wand.js preview  work/deck.json     browser preview at the 10in grid
+ *   node wand.js ship     work/deck.json     build .pptx and .pdf, then every gate
+  node wand.js spec     deck.pptx          read back the spec a built deck carries
+ *
+ * `rebuild` and `ship` are the two that matter. Everything else is a stage of
+ * one of them, exposed so a failure can be re-run on its own.
+ *
+ * Output is deliberately plain text: this runs as often through a pipe or a
+ * transcript as through a terminal, and escape codes only survive one of those.
+ */
+
+const { execFileSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const KIT = __dirname;
+const rel = (p) => path.relative(process.cwd(), p) || ".";
+const rule = (s) => `\n== ${s} ${"=".repeat(Math.max(0, 60 - s.length))}`;
+
+function die(msg, code = 2) { console.error(`\n${msg}\n`); process.exit(code); }
+
+/* ------------------------------------------------------------------ python */
+
+/** The first python3 that runs. Phases 0 and 6 need one; nothing else does. */
+function python() {
+  for (const c of ["python3", "python"]) {
+    const r = spawnSync(c, ["-c", "import sys;print(sys.version_info[0])"], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout.trim() === "3") return c;
+  }
+  return null;
+}
+
+function runPython(args) {
+  const py = python();
+  if (!py) die("no python3 on PATH - extract and font embedding both need one.\n" +
+               "Everything else (validate, check, preview, build) is pure Node and still works.");
+  return spawnSync(py, args, { stdio: "inherit", cwd: KIT }).status;
+}
+
+/* ------------------------------------------------------------------ doctor */
+
+function doctor() {
+  const rows = [];
+  const py = python();
+  rows.push(["node", process.version, "ok"]);
+  rows.push(["python3", py ? execFileSync(py, ["-V"], { encoding: "utf8" }).trim() : "MISSING",
+             py ? "ok" : "extract and font embedding unavailable"]);
+
+  let deps = "ok", where = "bundled";
+  try {
+    require.resolve("pptxgenjs"); require.resolve("fontkit");
+    if (!fs.existsSync(path.join(KIT, "node_modules", "pptxgenjs"))) where = "resolved outside the kit";
+  } catch {
+    deps = "MISSING - this zip should have shipped with them. `npm install` in " + rel(KIT);
+    where = "-";
+  }
+  rows.push(["dependencies", where, deps]);
+
+  for (const b of ["fonts", "assets"]) {
+    let where = "MISSING", st = "brand payload not found - see lib/brand.js";
+    try { where = rel(require("./lib/brand").resolve(b)); st = "ok"; } catch {}
+    rows.push([`brand/${b}`, where, st]);
+  }
+
+  const soffice = ["soffice", "libreoffice"].some((c) => spawnSync("which", [c]).status === 0);
+  rows.push(["libreoffice", soffice ? "found" : "absent",
+             soffice ? "ok" : "no PDF render - use `preview` for the visual gate instead"]);
+
+  if (py) {
+    const opt = spawnSync(py, ["-c",
+      "import importlib.util as u;print(','.join(m for m in ('defusedxml','fontTools') if u.find_spec(m)) or 'none')"],
+      { encoding: "utf8" });
+    const extras = (opt.stdout || "").trim() || "none";
+    rows.push(["python extras", extras === "none" ? "none (fine)" : extras, "ok"]);
+  }
+
+  const w = Math.max(...rows.map((r) => r[0].length));
+  console.log("");
+  for (const [k, v, s] of rows) {
+    console.log(`${s === "ok" ? "  " : "! "}${k.padEnd(w)}  ${String(v).padEnd(26)}${s === "ok" ? "" : s}`);
+  }
+  const blocked = rows.some((r) => r[2].startsWith("MISSING") || r[2].includes("npm install"));
+  console.log(blocked ? "\nBLOCKED - fix the rows marked !\n"
+                      : "\nready - node wand.js rebuild <source.pptx>\n");
+  return blocked ? 1 : 0;
+}
+
+/* ----------------------------------------------------------- phases 0 to 2 */
+
+function extract(src, out) {
+  if (!fs.existsSync(src)) die(`no such file: ${src}`);
+  if (runPython([path.join(KIT, "tools", "extract.py"), path.resolve(src), "-o", path.resolve(out)])) {
+    die("extract failed");
+  }
+}
+
+function plan(work) {
+  const a = path.join(work, "analysis.json");
+  if (!fs.existsSync(a)) die(`no ${rel(a)} - run \`node wand.js extract <source.pptx> -o ${rel(work)}\` first`);
+  const { worksheet } = require("./lib/plan");
+  const out = path.join(work, "PLAN.md");
+  fs.writeFileSync(out, worksheet(JSON.parse(fs.readFileSync(a, "utf8"))));
+  console.log(`wrote ${rel(out)}`);
+  return out;
+}
+
+/* --------------------------------------------------------------- catalogue */
+
+function layouts(name) {
+  const { LAYOUTS, COMMON } = require("./lib/schema");
+  if (name) {
+    const d = LAYOUTS[name];
+    if (!d) die(`no layout "${name}". Run \`node wand.js layouts\` for the list.`);
+    console.log(`\n${name}${d.bleed ? "   (full bleed - no footer)" : ""}\n  ${d.use}\n`);
+    const line = (k, f, ind) => {
+      const card = f.min || f.max ? ` [${f.min || 1}-${f.max || "n"}]` : "";
+      console.log(`${ind}${(k + (f.required ? "*" : "")).padEnd(16)} ${f.type}${card}${f.note ? "   " + f.note : ""}`);
+      if (f.of) for (const [k2, f2] of Object.entries(f.of)) line(k2, f2, ind + "    ");
+    };
+    for (const [k, f] of Object.entries(d.fields)) line(k, f, "  ");
+    console.log(`\n* required. Every layout also takes: ${Object.keys(COMMON).join(", ")}\n`);
+    return 0;
+  }
+  const names = Object.keys(LAYOUTS);
+  console.log(`\n${names.length} layouts - \`node wand.js layouts <name>\` for the fields\n`);
+  for (const n of names) console.log(`  ${n.padEnd(16)} ${LAYOUTS[n].use}`);
+  console.log("");
+  return 0;
+}
+
+/* ---------------------------------------------------------------- validate */
+
+function loadSpec(p) {
+  if (!fs.existsSync(p)) die(`no such spec: ${p}`);
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch (e) { die(`${rel(p)} is not valid JSON - ${e.message}`); }
+}
+
+function validate(specPath, quiet) {
+  const { validate: v } = require("./lib/schema");
+  const { errors, warnings } = v(loadSpec(specPath));
+  warnings.forEach((w) => console.log(`  warn  ${w}`));
+  errors.forEach((e) => console.log(`  ERROR ${e}`));
+  if (!quiet || errors.length) {
+    console.log(`spec        : ${errors.length ? `${errors.length} error(s)` : "valid"}` +
+                (warnings.length ? `, ${warnings.length} warning(s)` : ""));
+  }
+  return errors.length;
+}
+
+/* -------------------------------------------------------------------- ship */
+
+const node = (args) => spawnSync(process.execPath, args, { stdio: "inherit", cwd: KIT }).status;
+const has = (c) => spawnSync("which", [c]).status === 0;
+
+function ship(specPath, outArg) {
+  const spec = loadSpec(specPath);
+  const work = path.dirname(path.resolve(specPath));
+  const base = (spec.deck || "deck").replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "") || "deck";
+  const raw = path.join(work, `${base}.raw.pptx`);
+  const out = path.resolve(outArg || path.join(work, `${base}.pptx`));
+
+  console.log(rule("1 spec"));
+  if (validate(specPath, true)) die("spec has errors - fix them before building", 1);
+  console.log("spec        : valid");
+
+  console.log(rule("2 fit and bounds"));
+  const bad = node([path.join(KIT, "build.js"), path.resolve(specPath), "--check"]);
+
+  console.log(rule("3 build"));
+  if (node([path.join(KIT, "build.js"), path.resolve(specPath), raw])) die("build failed", 1);
+
+  console.log(rule("4 pdf"));
+  const pdfOut = out.replace(/\.pptx$/, ".pdf");
+  node([path.join(KIT, "build.js"), path.resolve(specPath), pdfOut]);
+
+  console.log(rule("5 embed fonts"));
+  if (runPython([path.join(KIT, "embed_fonts.py"), raw, "-o", out,
+                 "--spec", path.resolve(specPath)]) !== 0) die("font embedding failed", 1);
+  fs.rmSync(raw, { force: true });
+
+  console.log(rule("6 coverage"));
+  const dump = path.join(work, "visible_dump.txt");
+  let cov = null;
+  if (fs.existsSync(dump)) cov = runPython([path.join(KIT, "qa_coverage.py"), dump, out]);
+  else console.log(`no ${rel(dump)} - skipped. An authored deck has no source to cover;\n` +
+                   "a rebuild without this number is not QA'd.");
+
+  console.log(rule("7 file"));
+  const fileErrs = inspect(out);
+
+  console.log(rule("8 visual"));
+  node([path.join(KIT, "build.js"), path.resolve(specPath), "--preview"]);
+  let shots = 0;
+  if (has("pdftoppm") && fs.existsSync(pdfOut)) {
+    const dir = path.join(work, "slides");
+    fs.mkdirSync(dir, { recursive: true });
+    spawnSync("pdftoppm", ["-r", "96", "-png", pdfOut, path.join(dir, "slide")], { stdio: "inherit" });
+    shots = fs.readdirSync(dir).filter((f) => f.endsWith(".png")).length;
+    console.log(`rendered    : ${shots} slide(s) to ${rel(dir)}/ - look at every one`);
+  } else {
+    console.log(`open ${rel(path.join(KIT, "preview", "preview.html"))} and look at every slide.`);
+  }
+
+  const gates = [["fit + bounds", bad === 0], ["coverage", cov === null ? null : cov === 0],
+                 ["file", fileErrs === 0], ["renders", shots > 0 ? true : null]];
+  console.log(rule("gates"));
+  for (const [n, ok] of gates) console.log(`  ${ok === null ? "skip" : ok ? " ok " : "FAIL"}  ${n}`);
+  console.log(`\n${rel(out)}${fs.existsSync(pdfOut) ? "\n" + rel(pdfOut) : ""}\n`);
+  return gates.some(([, ok]) => ok === false) ? 1 : 0;
+}
+
+/**
+ * File-level check, in-process. `validate.py` from the pptx skill is not in the
+ * zip and LibreOffice may not be installed, so the kit carries its own: the
+ * parts a .pptx must have, a relationship target for every r:embed, and the
+ * subset flag that decides whether digits garble in an exported PDF.
+ */
+function inspect(file) {
+  const errs = [];
+  const z = readZip(file);
+  for (const need of ["[Content_Types].xml", "_rels/.rels", "ppt/presentation.xml"]) {
+    if (!z.has(need)) errs.push(`missing part ${need}`);
+  }
+  const slides = z.names.filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n));
+  const media = z.names.filter((n) => n.startsWith("ppt/media/"));
+  const fonts = z.names.filter((n) => n.startsWith("ppt/fonts/"));
+
+  for (const s of slides) {
+    const xml = z.text(s);
+    const ids = [...new Set([...xml.matchAll(/r:(?:embed|id|link)="([^"]+)"/g)].map((m) => m[1]))];
+    if (!ids.length) continue;
+    const relsName = s.replace("slides/", "slides/_rels/") + ".rels";
+    if (!z.has(relsName)) { errs.push(`${s} references ${ids.length} rel(s) but has no .rels part`); continue; }
+    const rels = z.text(relsName);
+    for (const id of ids) if (!rels.includes(`Id="${id}"`)) errs.push(`${s} references ${id}, undefined in its .rels`);
+  }
+  const pres = z.has("ppt/presentation.xml") ? z.text("ppt/presentation.xml") : "";
+  const families = (pres.match(/<p:embeddedFont>/g) || []).length;
+  if (fonts.length && !/saveSubsetFonts="0"/.test(pres)) {
+    errs.push('fonts embedded but saveSubsetFonts is not "0" - digits garble in exported PDFs');
+  }
+  if (!fonts.length) errs.push("no embedded fonts - this renders as Arial on the client's machine");
+  errs.forEach((e) => console.log(`  ERROR ${e}`));
+  console.log(`file        : ${slides.length} slides, ${media.length} media, ${fonts.length} font parts / ` +
+              `${families} families` + (errs.length ? ` - ${errs.length} problem(s) above` : " - clean"));
+  return errs.length;
+}
+
+/** Minimal zip reader, so `inspect` needs no dependency of its own. */
+function readZip(file) {
+  const zlib = require("zlib");
+  const buf = fs.readFileSync(file);
+  let end = buf.length - 22;
+  while (end >= 0 && buf.readUInt32LE(end) !== 0x06054b50) end--;
+  if (end < 0) die(`${rel(file)} is not a zip - is it really a .pptx?`);
+  let off = buf.readUInt32LE(end + 16);
+  const count = buf.readUInt16LE(end + 10);
+  const entries = new Map();
+  for (let i = 0; i < count; i++) {
+    const nameLen = buf.readUInt16LE(off + 28);
+    const extraLen = buf.readUInt16LE(off + 30);
+    const commentLen = buf.readUInt16LE(off + 32);
+    entries.set(buf.toString("utf8", off + 46, off + 46 + nameLen), {
+      method: buf.readUInt16LE(off + 10), local: buf.readUInt32LE(off + 42), size: buf.readUInt32LE(off + 20),
+    });
+    off += 46 + nameLen + extraLen + commentLen;
+  }
+  const read = (name) => {
+    const e = entries.get(name);
+    const start = e.local + 30 + buf.readUInt16LE(e.local + 26) + buf.readUInt16LE(e.local + 28);
+    const raw = buf.subarray(start, start + e.size);
+    return e.method === 0 ? raw : zlib.inflateRawSync(raw);
+  };
+  return { names: [...entries.keys()], has: (n) => entries.has(n), text: (n) => read(n).toString("utf8") };
+}
+
+/* ------------------------------------------------------------------ driver */
+
+const [, , cmd, ...rest] = process.argv;
+const flag = (name, def) => { const i = rest.indexOf(name); return i < 0 ? def : rest[i + 1]; };
+const positional = rest.filter((a, i) => !a.startsWith("-") && !["-o", "--out"].includes(rest[i - 1]));
+
+switch (cmd) {
+  case "doctor": process.exit(doctor());
+
+  case "extract":
+    if (!positional[0]) die("usage: node wand.js extract <source.pptx> [-o work/]");
+    extract(positional[0], flag("-o", flag("--out", "work")));
+    break;
+
+  case "plan": plan(positional[0] || "work"); break;
+
+  case "rebuild": {
+    if (!positional[0]) die("usage: node wand.js rebuild <source.pptx> [-o work/]");
+    const work = flag("-o", flag("--out", "work"));
+    console.log(rule("1 normalise and extract (phases 0-1)"));
+    extract(positional[0], work);
+    console.log(rule("2 classify and map (phases 2-3)"));
+    plan(work);
+    console.log(`
+NEXT - the part no script does for you:
+
+  1. Read ${rel(path.join(work, "PLAN.md"))}. Per slide it has the source's shape,
+     a shortlist of layouts with the reason for each, every verbatim string, and
+     a stub for the top candidate.
+  2. Choose a layout per slide by section 6 Phase 3. The shortlist is ranked by
+     shape and cannot see meaning. Vary them; alternate dark and light.
+  3. Emit the mapping plan, one line per slide, before writing any JSON.
+  4. Write ${rel(path.join(work, "deck.json"))} - verbatim text, no coordinates,
+     no colours, no font sizes.
+  5. node wand.js validate ${rel(path.join(work, "deck.json"))}
+  6. node wand.js ship ${rel(path.join(work, "deck.json"))}
+
+FAITHFUL MEANS VERBATIM. Reflow to fit; never reword. Paraphrase is invisible to
+every gate except coverage, and it is the failure this pipeline is most exposed
+to.
+`);
+    break;
+  }
+
+  case "layouts": process.exit(layouts(positional[0]));
+
+  case "glyphs": {
+    const G = require("./lib/shared").glyphs;
+    const idx = G.index();
+    if (positional[0]) {
+      const q = positional[0].toLowerCase();
+      const hits = G.names().filter((n) => n.includes(q));
+      console.log(hits.length ? "\n  " + hits.join("\n  ") + "\n"
+                              : `\nno glyph matches "${positional[0]}". Closest: ${G.suggest(positional[0]).join(", ")}\n`);
+      process.exit(0);
+    }
+    console.log(`\n${idx.count} glyphs - ${idx.set} ${idx.version}, ${idx.license}. Recoloured per theme, so there is no light/dark variant to pick.\n`);
+    for (const [g, list] of Object.entries(idx.groups)) {
+      console.log(`  ${g}`);
+      for (let i = 0; i < list.length; i += 6) console.log("    " + list.slice(i, i + 6).map((n) => n.padEnd(17)).join(""));
+    }
+    console.log("");
+    process.exit(0);
+  }
+
+  case "validate":
+    if (!positional[0]) die("usage: node wand.js validate <spec.json>");
+    process.exit(validate(positional[0]) ? 1 : 0);
+
+  case "check":
+  case "preview":
+  case "build": {
+    if (!positional[0]) die(`usage: node wand.js ${cmd} <spec.json>`);
+    const a = [path.join(KIT, "build.js"), path.resolve(positional[0])];
+    if (cmd === "check") a.push("--check");
+    else if (cmd === "preview") a.push("--preview");
+    else if (positional[1]) a.push(path.resolve(positional[1]));
+    process.exit(node(a) || 0);
+  }
+
+  case "spec": {
+    if (!positional[0]) die("usage: node wand.js spec <deck.pptx> [out.json]");
+    const z = readZip(path.resolve(positional[0]));
+    if (!z.has("wand/spec.json")) {
+      die(`${rel(positional[0])} carries no spec.\n` +
+          "Only decks this kit built do. For anything else, run `rebuild` on it.");
+    }
+    const json = z.text("wand/spec.json");
+    if (positional[1]) { fs.writeFileSync(positional[1], json); console.log(`wrote ${rel(positional[1])}`); }
+    else process.stdout.write(json);
+    process.exit(0);
+  }
+
+  case "inspect":
+    if (!positional[0]) die("usage: node wand.js inspect <deck.pptx>");
+    process.exit(inspect(path.resolve(positional[0])) ? 1 : 0);
+
+  case "ship":
+    if (!positional[0]) die("usage: node wand.js ship <spec.json> [out.pptx]");
+    process.exit(ship(positional[0], positional[1]));
+
+  default:
+    console.log(fs.readFileSync(__filename, "utf8").split("*/")[0]
+      .split("\n").filter((l) => l.startsWith(" *")).map((l) => l.slice(2).replace(/^ /, "")).join("\n"));
+    process.exit(cmd ? 2 : 0);
+}