slidemind 0.2.3 → 0.2.4

package/src/bridge/engine-download.mjs

@@ -141,6 +141,25 @@ export function resolveAssetExt(mimeType, buf) {
   return extFromBytes(buf) ?? declared;
 }
 
+// The recolour descriptor, with a pane-free TINT REFUSAL folded in: the bytes
+// on disk are then the original ones, so `applied` has to read false and the
+// note has to name the one route that does bake a colour in.
+function describeRecolorWithRefusal(markup, mimeType, iconColor, refusedColor) {
+  const described = describeRecolor(
+    markup,
+    mimeType,
+    refusedColor ? null : (iconColor ?? null),
+  );
+  if (!refusedColor) return described;
+  return {
+    ...described,
+    note:
+      `Saved in its ORIGINAL colours — recolouring to ${refusedColor} runs in the slidemind add-in. ` +
+      "Re-run this download with --to <presId> (a PowerPoint window with the slidemind pane open) " +
+      "to bake the colour in.",
+  };
+}
+
 // Stream one result into assetsDir via the add-in's streaming route.
 //
 // Returns the same shape as `downloadOneResult`, or null when the paired add-in
@@ -156,21 +175,29 @@ async function streamOneResult({
   iconColor,
 }) {
   if (typeof client.engineDownloadToFile !== "function") return null;
+  // `presId: null` + a resolved backendURL is the pane-free route (the client
+  // picks the direct stream); a presId relays through that window's pane.
   // Write under a provisional name: the true extension is only knowable from the
   // bytes, and buffering the image just to sniff its header would defeat the
   // purpose of streaming.
   const tempPath = path.join(assetsDir, `.engine-${searchId}-${selection}.part`);
-  let res;
-  try {
-    res = await client.engineDownloadToFile({
+  const fetchOnce = (color) =>
+    client.engineDownloadToFile({
       presId,
       backendURL,
       searchId,
       selection,
       destPath: tempPath,
-      iconColor: iconColor ?? null,
+      iconColor: color ?? null,
       onProgress: createTransferProgress(`downloading result ${selection}`),
     });
+  let res;
+  // Set when the pane-free route refused the TINT (not the asset): the download
+  // then repeats without a colour so the caller still gets the icon, and the
+  // recolour is reported as not applied instead of silently claimed.
+  let recolorRefused = null;
+  try {
+    res = await fetchOnce(iconColor);
   } catch (err) {
     fs.rmSync(tempPath, { force: true });
     // Route absent → this add-in predates streaming; let the caller fall back.
@@ -178,7 +205,13 @@ async function streamOneResult({
     // for a stale selection), not Express saying "no such path" — retrying that
     // on the capped path would just fail again, more slowly.
     if ((err?.status === 404 && !err?.code) || err?.status === 501) return null;
-    throw err;
+    // The recolour classifier is DOM-based and lives in the add-in, so the
+    // pane-free route refuses a tint rather than guessing at one. Refusing the
+    // whole DOWNLOAD over it would be worse: the icon is fetchable, only the
+    // colour is not. Take the bytes and say so.
+    if (err?.code !== "recolor_needs_host" || !iconColor) throw err;
+    recolorRefused = iconColor;
+    res = await fetchOnce(null);
   }
 
   try {
@@ -193,7 +226,12 @@ async function streamOneResult({
         path: target,
         reference: `./assets/${filename}`,
         mimeType: res.mimeType ?? "image/svg+xml",
-        recolor: describeRecolor(res.svgMarkup, res.mimeType, iconColor ?? null),
+        recolor: describeRecolorWithRefusal(
+          res.svgMarkup,
+          res.mimeType,
+          iconColor,
+          recolorRefused,
+        ),
         size: svgSizeFromMarkup(res.svgMarkup),
       };
     }
@@ -222,7 +260,12 @@ async function streamOneResult({
       path: target,
       reference: `./assets/${filename}`,
       mimeType: res.mimeType ?? null,
-      recolor: describeRecolor(null, res.mimeType, iconColor ?? null),
+      recolor: describeRecolorWithRefusal(
+        null,
+        res.mimeType,
+        iconColor,
+        recolorRefused,
+      ),
       size: imageSizeFromBuffer(probe),
     };
   } catch (err) {
@@ -237,7 +280,7 @@ async function streamOneResult({
 // the rest.
 export async function downloadOneResult({
   client,
-  presId,
+  presId = null,
   backendURL = null,
   searchId,
   assetsDir,
@@ -259,6 +302,16 @@ export async function downloadOneResult({
   });
   if (streamed) return streamed;
 
+  // The capped base64 fallback below is a PANE route. On the pane-free path
+  // there is no window to relay through — and an add-in that serves the direct
+  // routes always serves the direct stream — so a missing stream there is a real
+  // failure, not a reason to reach for a window that may not exist.
+  if (!presId) {
+    throw new Error(
+      "the add-in's engine routes returned no bytes for that result — re-run the search, then pick again",
+    );
+  }
+
   // Fallback for an add-in that predates the streaming route: bytes ride the
   // pane's Socket.IO ack, capped by its 10 MB frame limit.
   const res = await client.engineDownload({

package/src/builders/resolve-skill.mjs

@@ -68,8 +68,11 @@ function firstExistingOr(candidates, fallback) {
   return firstExisting(candidates) ?? fallback;
 }
 
-export function resolveSkillForDeck(deckDir) {
+export function resolveSkillForDeck(deckDir, opts = {}) {
   const planMeta = readPlanFrontmatter(deckDir);
+  if (opts.packDir) {
+    return resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+  }
   const skillName = planMeta.skill || DEFAULT_SKILL;
   const bundleDir = deckDir ? resolveBundleDirForDeck(deckDir) : null;
   return resolveSkill(skillName, planMeta, { deckDir, bundleDir });
@@ -80,7 +83,12 @@ export function resolveSkillForDeck(deckDir) {
 // fill-template) must not pay resolveSkill's design-root requirement — a
 // compose deck with an unmaterialized bundle self-heals inside the render
 // path, and an early resolver throw here would break that.
-export function resolveDeckMode(deckDir) {
+export function resolveDeckMode(deckDir, opts = {}) {
+  if (opts.packDir) {
+    const planMeta = readPlanFrontmatter(deckDir);
+    const pack = resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+    return { skillName: pack.skillName, mode: pack.mode, skillDir: pack.skillDir };
+  }
   try {
     const planMeta = readPlanFrontmatter(deckDir);
     const skillName = planMeta.skill || DEFAULT_SKILL;
@@ -92,6 +100,60 @@ export function resolveDeckMode(deckDir) {
   }
 }
 
+// Resolve a runtime template pack from an explicit directory. This path is
+// deliberately independent of agent/harness installation and of the compose
+// design-bundle resolver below. A plugin can locate its own pack and pass this
+// path to the CLI without the CLI knowing the plugin exists.
+export function resolveTemplatePack(packDir, planMeta = {}, opts = {}) {
+  const skillDir = path.resolve(String(packDir));
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    throw new Error(`template pack directory does not exist: ${skillDir}`);
+  }
+  const manifest = readManifest(skillDir);
+  if (!manifest || typeof manifest !== "object" || !manifest.mode) {
+    throw new Error(`template pack ${skillDir} has no valid skill.json manifest`);
+  }
+
+  let templateKey = null;
+  let templatePath = null;
+  if (manifest.templates) {
+    templateKey =
+      planMeta.template ||
+      manifest.defaultTemplate ||
+      Object.keys(manifest.templates)[0];
+    const rel = templateKey ? manifest.templates[templateKey] : null;
+    if (rel) {
+      const candidate = path.resolve(skillDir, rel);
+      const relative = path.relative(skillDir, candidate);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`template path escapes pack directory: ${rel}`);
+      }
+      if (fs.existsSync(candidate)) templatePath = candidate;
+    }
+  }
+
+  return {
+    skillName: manifest.name || path.basename(skillDir),
+    skillDir,
+    manifest,
+    mode: manifest.mode || "compose",
+    // Fill-template callers only need the pack payload. These legacy design
+    // fields remain null so callers can distinguish this path from compose
+    // skill resolution without paying a design-root requirement.
+    cssFile: null,
+    layoutsDir: null,
+    layoutsCssFile: null,
+    assetsDir: opts.deckDir ? path.join(opts.deckDir, "assets") : null,
+    brand: null,
+    templateKey,
+    templatePath,
+    locale: planMeta.locale || null,
+    planMeta,
+    packageRoot: PACKAGE_ROOT,
+    bundleDir: opts.deckDir ? resolveBundleDirForDeck(opts.deckDir) : null,
+  };
+}
+
 // Skill packs can live outside the npm package: private, org-internal packs
 // (templates, brand-specific assets) are distributed on their own and this
 // package never carries them. Lookup order:

package/src/pptx/fill/engine.mjs

@@ -35,69 +35,11 @@ export async function buildFillTemplateDeck({ deckDir, skill, outPath, onLog })
   const locale = skill.locale || "en";
   const fieldsByNo = pack.fields[locale] ?? {};
   const repeatsByNo = pack.repeats[locale] ?? {};
-
-  if (!skill.templatePath || !fs.existsSync(skill.templatePath)) {
-    throw new Error(
-      `template "${skill.templateKey}" not found in pack ${skill.skillDir} — check plan.md frontmatter and skill.json templates`,
-    );
-  }
-
-  // ---- deck reading ---------------------------------------------------------
-  const slidesDir = path.join(deckDir, "slides");
-  const entries = fs.readdirSync(slidesDir)
-    .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"))
-    .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
-  if (entries.length === 0) throw new Error(`no .jsx or .pptx slides in ${slidesDir}`);
-
-  const problems = [];
-  const warnings = [];
-  const sequence = []; // { kind: "master", no, props, file } | { kind: "insert", file, buf }
-
-  // In-deck freeform pairing: NN-name.jsx (create-slides source) renders to a
-  // sibling NN-name.pptx artifact — when both exist, the .pptx carries the
-  // slide and the .jsx is source only.
-  const renderedStems = new Set(
-    entries.filter((f) => f.endsWith(".pptx")).map((f) => f.replace(/\.pptx$/, "")),
-  );
-
-  for (const file of entries) {
-    if (file.endsWith(".pptx")) {
-      sequence.push({ kind: "insert", file, buf: fs.readFileSync(path.join(slidesDir, file)) });
-      continue;
-    }
-    if (renderedStems.has(file.replace(/\.jsx$/, ""))) continue;
-    const src = fs.readFileSync(path.join(slidesDir, file), "utf8");
-    let parsed;
-    try {
-      parsed = parseSlideFile(src, file);
-    } catch (err) {
-      problems.push(err.message);
-      continue;
-    }
-    const layout = layoutNumber(parsed.component, locale, pack.components);
-    if (!layout) {
-      problems.push(`${file}: <${parsed.component}> is a freeform (create-slides) slide with no ` +
-        `rendered artifact next to it — 'slidemind build-pptx' renders slides/${file.replace(/\.jsx$/, "")}.pptx ` +
-        `automatically when a paired add-in backend is reachable`);
-      continue;
-    }
-    if (layout.warn) warnings.push(`${file}: ${layout.warn}`);
-    const no = String(layout.no);
-
-    if ((pack.policy.freeform ?? []).includes(no)) {
-      if (Object.keys(parsed.props).length > 0) {
-        problems.push(`${file}: slide ${no} is a freeform placeholder — it takes no props. ` +
-          `Keep it bare to keep the master placeholder, or delete the file to drop the slide.`);
-        continue;
-      }
-      warnings.push(`${file}: keeping the master's slide-${no} placeholder (freeform replacement pending)`);
-    }
-
-    validateProps(parsed.props, fieldsByNo[no] ?? {}, repeatsByNo[no] ?? {}, pack.policy, no, file, problems);
-    sequence.push({ kind: "master", no: Number(no), props: parsed.props, file });
-  }
-
-  checkIdentities(sequence, warnings, problems);
+  const { sequence, warnings, problems } = inspectFillTemplateDeck({
+    deckDir,
+    skill,
+    includeBuffers: true,
+  });
   if (problems.length) {
     const err = new Error(`deck has ${problems.length} authoring error(s):\n  - ${problems.join("\n  - ")}`);
     err.problems = problems;
@@ -174,6 +116,113 @@ export async function buildFillTemplateDeck({ deckDir, skill, outPath, onLog })
   return { outPath: finalOut, slideCount: output.length, warnings };
 }
 
+// Parse and structurally validate a fill-template deck without mutating it.
+// External packs use this generic inspection surface to run their own domain
+// checks before invoking build-pptx. Buffers are opt-in because JSON callers
+// must receive a compact, serializable sequence.
+export function inspectFillTemplateDeck({
+  deckDir,
+  skill,
+  allowUnrenderedFreeform = false,
+  includeBuffers = false,
+}) {
+  const pack = loadPack(skill);
+  const locale = skill.locale || "en";
+  const fieldsByNo = pack.fields[locale] ?? {};
+  const repeatsByNo = pack.repeats[locale] ?? {};
+  const slidesDir = path.join(deckDir, "slides");
+  const problems = [];
+  const warnings = [];
+  const sequence = [];
+
+  if (!skill.templatePath || !fs.existsSync(skill.templatePath)) {
+    problems.push(
+      `template "${skill.templateKey}" not found in pack ${skill.skillDir} — check the pack manifest templates`,
+    );
+  }
+  if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
+    problems.push(`expected 'slides/' folder in ${deckDir}`);
+    return { sequence, warnings, problems, locale, templateKey: skill.templateKey };
+  }
+
+  const entries = fs.readdirSync(slidesDir)
+    .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"))
+    .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+  if (entries.length === 0) {
+    problems.push(`no .jsx or .pptx slides in ${slidesDir}`);
+    return { sequence, warnings, problems, locale, templateKey: skill.templateKey };
+  }
+
+  const renderedStems = new Set(
+    entries.filter((f) => f.endsWith(".pptx")).map((f) => f.replace(/\.pptx$/, "")),
+  );
+
+  for (const file of entries) {
+    const full = path.join(slidesDir, file);
+    if (file.endsWith(".pptx")) {
+      sequence.push({
+        kind: "insert",
+        file,
+        ...(includeBuffers ? { buf: fs.readFileSync(full) } : {}),
+      });
+      continue;
+    }
+    if (renderedStems.has(file.replace(/\.jsx$/, ""))) continue;
+
+    const src = fs.readFileSync(full, "utf8");
+    const component = src.match(/<([A-Z][A-Za-z0-9]*)/)?.[1] ?? null;
+    let layout = null;
+    if (component) {
+      try {
+        layout = layoutNumber(component, locale, pack.components);
+      } catch (err) {
+        problems.push(err.message);
+        continue;
+      }
+    }
+
+    // A pack validator needs to see freeform source positions even before the
+    // paired add-in artifact exists. The build path still rejects such a
+    // source until ensureFreeformRenders has produced its .pptx sibling.
+    if (!layout && allowUnrenderedFreeform) {
+      sequence.push({ kind: "freeform", file, component });
+      warnings.push(`${file}: freeform source has no rendered .pptx artifact yet`);
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = parseSlideFile(src, file);
+    } catch (err) {
+      problems.push(err.message);
+      continue;
+    }
+    layout = layoutNumber(parsed.component, locale, pack.components);
+    if (!layout) {
+      problems.push(`${file}: <${parsed.component}> is a freeform (create-slides) slide with no ` +
+        `rendered artifact next to it — render slides/${file.replace(/\.jsx$/, "")}.pptx ` +
+        `through the paired add-in before building`);
+      continue;
+    }
+    if (layout.warn) warnings.push(`${file}: ${layout.warn}`);
+    const no = String(layout.no);
+
+    if ((pack.policy.freeform ?? []).includes(no)) {
+      if (Object.keys(parsed.props).length > 0) {
+        problems.push(`${file}: slide ${no} is a freeform placeholder — it takes no props. ` +
+          `Keep it bare to keep the master placeholder, or delete the file to drop the slide.`);
+        continue;
+      }
+      warnings.push(`${file}: keeping the master's slide-${no} placeholder (freeform replacement pending)`);
+    }
+
+    validateProps(parsed.props, fieldsByNo[no] ?? {}, repeatsByNo[no] ?? {}, pack.policy, no, file, problems);
+    sequence.push({ kind: "master", no: Number(no), props: parsed.props, file });
+  }
+
+  return { sequence, warnings, problems, locale, templateKey: skill.templateKey };
+}
+
 // ---------------------------------------------------------------------------
 // Pack
 // ---------------------------------------------------------------------------
@@ -266,77 +315,6 @@ function editDistance(a, b) {
   return dp[a.length][b.length];
 }
 
-// ---------------------------------------------------------------------------
-// Cross-slide identities (the catalog's consistency table, as code)
-// ---------------------------------------------------------------------------
-
-const asLines = (v) => (Array.isArray(v) ? v : String(v ?? "").split("\n")).map((s) => s.trim()).filter(Boolean);
-
-function checkIdentities(sequence, warnings, problems) {
-  const slide = (no) => sequence.filter((s) => s.kind === "master" && s.no === no);
-  const approach = slide(10)[0];
-  const details = slide(11);
-  const gantt = slide(13)[0];
-  const calc = slide(16)[0];
-
-  const wpItems = approach?.props?.repeat?.workPackages ?? null;
-  const ganttItems = gantt?.props?.repeat?.workPackages ?? null;
-
-  if (wpItems && details.length && wpItems.length !== details.length) {
-    problems.push(`WP count mismatch: slide 10 declares ${wpItems.length} work packages but there are ${details.length} WP-detail files (slide 11)`);
-  }
-  // Every WP detail must carry FULL bullet lists — a section left empty (or a
-  // one-liner) is a defect in a client deliverable, not a style choice.
-  details.forEach((d, i) => {
-    for (const section of ["services", "assumptions", "deliverables"]) {
-      const lines = asLines(d.props?.[section]);
-      if (lines.length === 0) {
-        problems.push(`${d.file}: WP detail ${i + 1} has no "${section}" — every WP detail needs all three bullet lists filled`);
-      } else if (lines.length < 3) {
-        warnings.push(`${d.file}: "${section}" has only ${lines.length} bullet(s) — WP details expect full lists (3–5)`);
-      }
-    }
-  });
-  if (wpItems && ganttItems && wpItems.length !== ganttItems.length) {
-    problems.push(`WP count mismatch: slide 10 has ${wpItems.length} work packages, the project plan (13) has ${ganttItems.length} rows`);
-  }
-  if (ganttItems && details.length === ganttItems.length) {
-    ganttItems.forEach((item, i) => {
-      const canonical = asLines(details[i]?.props?.deliverables);
-      const row = asLines(item.deliverable);
-      if (canonical.length && row.length && canonical.join("\n") !== row.join("\n")) {
-        problems.push(`deliverables drift: gantt row ${i + 1} must repeat WP-${i + 1}'s deliverables verbatim (slide 11 owns them)`);
-      }
-    });
-  }
-  if (wpItems && ganttItems) {
-    ganttItems.forEach((item, i) => {
-      if (item.title && wpItems[i]?.title && item.title !== wpItems[i].title) {
-        problems.push(`WP name drift: slide 10 card ${i + 1} is "${wpItems[i].title}" but gantt row ${i + 1} is "${item.title}"`);
-      }
-    });
-  }
-  for (const [frameId, rows] of Object.entries(calc?.props?.tables ?? {})) {
-    if (!Array.isArray(rows) || !wpItems) continue;
-    const labels = rows.slice(1, -1).map((r) => String(r[0] ?? ""));
-    labels.forEach((label, i) => {
-      if (wpItems[i]?.title && label && label !== wpItems[i].title) {
-        problems.push(`WP name drift: calculation table ${frameId} row ${i + 1} is "${label}" but slide 10 card ${i + 1} is "${wpItems[i].title}"`);
-      }
-    });
-  }
-  // Price echo: the contracted total should appear in the management summary.
-  const costRows = calc?.props?.tables?.["15"];
-  if (Array.isArray(costRows)) {
-    const grand = String(costRows[costRows.length - 1]?.slice(-1)[0] ?? "");
-    const digits = grand.replace(/[^\d.,]/g, "");
-    const summary = slide(7)[0];
-    if (digits && summary?.props?.approach && !String(summary.props.approach).includes(digits)) {
-      warnings.push(`slide 7's approach paragraph does not mention the contracted total ${grand} from table 15`);
-    }
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Per-slide ops
 // ---------------------------------------------------------------------------