ppt-template-reuse 0.4.0-rc.2

package/src/core/io.mjs

@@ -0,0 +1,81 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function exists(candidate) {
+  return Boolean(await fs.stat(candidate).catch(() => undefined));
+}
+
+export async function readJson(candidate) {
+  return JSON.parse(await fs.readFile(candidate, "utf8"));
+}
+
+export async function writeJsonAtomic(candidate, value) {
+  await fs.mkdir(path.dirname(candidate), { recursive: true });
+  const temporary = `${candidate}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  await fs.rename(temporary, candidate);
+}
+
+export async function sha256File(candidate) {
+  return crypto
+    .createHash("sha256")
+    .update(await fs.readFile(candidate))
+    .digest("hex");
+}
+
+export function fingerprint(value) {
+  const stable = (input) => {
+    if (Array.isArray(input)) return input.map(stable);
+    if (input && typeof input === "object") {
+      return Object.fromEntries(
+        Object.keys(input)
+          .sort()
+          .map((key) => [key, stable(input[key])]),
+      );
+    }
+    return input;
+  };
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(stable(value)))
+    .digest("hex");
+}
+
+export function normalizePath(candidate) {
+  return path.resolve(String(candidate));
+}
+
+export function isWithin(candidate, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function assertAllowedPath(candidate, allowedRoots) {
+  const resolved = path.resolve(candidate);
+  if (!allowedRoots.some((root) => isWithin(resolved, root))) {
+    const error = new Error(`Path is outside allowed roots: ${resolved}`);
+    error.code = "PATH_NOT_ALLOWED";
+    throw error;
+  }
+  return resolved;
+}
+
+export function parseCliArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      result._.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) result[key] = true;
+    else {
+      result[key] = next;
+      index += 1;
+    }
+  }
+  return result;
+}

package/src/core/legacy-capsule-import.mjs

@@ -0,0 +1,382 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { fingerprint, readJson, sha256File, writeJsonAtomic } from "./io.mjs";
+import { resolveLibraryDir } from "./paths.mjs";
+import { inspectTemplate } from "./template-inspector.mjs";
+import { buildTemplateIntelligence } from "./template-intelligence.mjs";
+
+function normalized(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function exists(candidate) {
+  return fs.stat(candidate).then(
+    () => true,
+    () => false,
+  );
+}
+
+function effectiveRecipe(recipe, correction = {}) {
+  const next = structuredClone(recipe);
+  for (const key of [
+    "layoutFamily",
+    "layoutVariant",
+    "narrativeRole",
+    "confidence",
+    "autoUseStatus",
+    "approvedForAutoUse",
+    "excludedFromAutoUse",
+    "exclusionReason",
+  ]) {
+    if (correction[key] !== undefined) next[key] = correction[key];
+  }
+  if (correction.slots) {
+    next.slots = (next.slots || []).map((slot) => ({
+      ...slot,
+      ...(correction.slots[slot.slotId] || {}),
+    }));
+  }
+  return next;
+}
+
+function familyForUniversalProfile(value) {
+  const family = normalized(value);
+  if (["text-content", "statement", "quote"].includes(family)) return "analysis";
+  if (
+    ["two-column", "three-column", "four-column", "multi-column", "matrix"].includes(
+      family,
+    )
+  ) {
+    return "comparison";
+  }
+  if (family === "image-led") return "image";
+  if (family === "references") return "reference";
+  return family || "analysis";
+}
+
+function scaleBox(box, sourceCanvas, targetCanvas) {
+  if (!Array.isArray(box) || box.length !== 4) return undefined;
+  const sourceWidth = Number(sourceCanvas?.width || targetCanvas.width);
+  const sourceHeight = Number(sourceCanvas?.height || targetCanvas.height);
+  return {
+    x: (Number(box[0]) * targetCanvas.width) / sourceWidth,
+    y: (Number(box[1]) * targetCanvas.height) / sourceHeight,
+    width: (Number(box[2]) * targetCanvas.width) / sourceWidth,
+    height: (Number(box[3]) * targetCanvas.height) / sourceHeight,
+  };
+}
+
+function capabilityInventory(slides) {
+  const result = {};
+  const add = (name, slide) => {
+    if (!name) return;
+    result[name] ||= { count: 0, safeCount: 0, sourceSlides: [] };
+    result[name].count += 1;
+    if (slide.safetyStatus === "automatic") result[name].safeCount += 1;
+    result[name].sourceSlides.push(slide.sourceSlide);
+  };
+  for (const slide of slides) {
+    const capabilities = new Set([
+      slide.layoutFamily,
+      ...(slide.communicationFunctions || []),
+      ...(slide.narrativeRoles || []),
+    ]);
+    if (slide.layoutFamily === "cover") capabilities.add("cover");
+    if (slide.layoutFamily === "closing") capabilities.add("closing");
+    if (slide.layoutFamily === "agenda") capabilities.add("roadmap");
+    if (slide.layoutFamily === "divider") capabilities.add("section");
+    if (slide.layoutFamily === "timeline") {
+      capabilities.add("timeline");
+      capabilities.add("chronology");
+      capabilities.add("process");
+      capabilities.add("evidence");
+    }
+    if (
+      ["analysis", "comparison", "table", "process", "reference"].includes(
+        slide.layoutFamily,
+      )
+    ) {
+      for (const capability of [
+        "analysis",
+        "issue",
+        "counterargument",
+        "conclusion",
+        "summary",
+        "evidence",
+        "background",
+        "problem",
+        "solution",
+        "comparison",
+      ]) {
+        capabilities.add(capability);
+      }
+    }
+    if (["chart", "table"].includes(slide.layoutFamily)) capabilities.add("data");
+    if (slide.layoutFamily === "image") {
+      capabilities.add("imagery");
+      capabilities.add("image-evidence");
+      capabilities.add("evidence");
+    }
+    for (const capability of capabilities) add(normalized(capability), slide);
+  }
+  for (const capability of Object.values(result)) {
+    capability.sourceSlides = [...new Set(capability.sourceSlides)].sort(
+      (left, right) => left - right,
+    );
+  }
+  return result;
+}
+
+function reviewSummary(slides) {
+  return {
+    automaticSlides: slides
+      .filter((slide) => slide.safetyStatus === "automatic")
+      .map((slide) => slide.sourceSlide),
+    reviewSlides: slides
+      .filter((slide) => slide.safetyStatus === "review")
+      .map((slide) => slide.sourceSlide),
+    blockedSlides: slides
+      .filter((slide) => slide.safetyStatus === "blocked")
+      .map((slide) => slide.sourceSlide),
+  };
+}
+
+export async function importLegacyCapsule({
+  capsuleDir,
+  templatePath,
+  approvedSourceSlides = [],
+  openingSourceSlide,
+  closingSourceSlide,
+  home,
+  persist = true,
+}) {
+  const resolvedCapsule = path.resolve(capsuleDir);
+  const resolvedTemplate = path.resolve(templatePath);
+  const [manifest, recipeDoc, inspection] = await Promise.all([
+    readJson(path.join(resolvedCapsule, "manifest.json")),
+    readJson(path.join(resolvedCapsule, "slide-recipes.json")),
+    inspectTemplate(resolvedTemplate),
+  ]);
+  const correctionsPath = path.join(resolvedCapsule, "user-corrections.json");
+  const grammarPath = path.join(resolvedCapsule, "deck-grammar.json");
+  const corrections = (await exists(correctionsPath))
+    ? await readJson(correctionsPath)
+    : { slides: {} };
+  const deckGrammar = (await exists(grammarPath))
+    ? await readJson(grammarPath)
+    : {};
+  const actualSha256 = await sha256File(resolvedTemplate);
+  const legacySha256 =
+    manifest.source?.sha256 || manifest.sourceSha256 || manifest.sha256;
+  if (!legacySha256 || legacySha256 !== actualSha256) {
+    const error = new Error(
+      "Legacy capsule does not match the selected template SHA256",
+    );
+    error.code = "LEGACY_CAPSULE_SOURCE_MISMATCH";
+    throw error;
+  }
+
+  const intelligence = buildTemplateIntelligence({
+    manifest,
+    recipeDoc,
+    deckGrammar,
+    corrections,
+  });
+  const approved = new Set(
+    approvedSourceSlides.map(Number).filter(Number.isFinite),
+  );
+  for (const [slideNumber, correction] of Object.entries(
+    corrections.slides || {},
+  )) {
+    if (correction.approvedForAutoUse === true) approved.add(Number(slideNumber));
+  }
+  if (openingSourceSlide) approved.add(Number(openingSourceSlide));
+  if (closingSourceSlide) approved.add(Number(closingSourceSlide));
+
+  const recipeBySlide = new Map(
+    (recipeDoc.recipes || []).map((recipe) => [
+      Number(recipe.sourceSlide),
+      effectiveRecipe(
+        recipe,
+        corrections.slides?.[String(recipe.sourceSlide)] || {},
+      ),
+    ]),
+  );
+  const intelligenceBySlide = new Map(
+    intelligence.slides.map((slide) => [Number(slide.sourceSlide), slide]),
+  );
+  const sourceCanvas =
+    manifest.styleProfile?.slideSize || manifest.slideSize || inspection.canvas;
+  const slides = inspection.slides.map((baseSlide) => {
+    const sourceSlide = Number(baseSlide.sourceSlide);
+    const recipe = recipeBySlide.get(sourceSlide);
+    const semantic = intelligenceBySlide.get(sourceSlide);
+    if (!recipe || !semantic) {
+      return {
+        ...baseSlide,
+        safetyStatus: "blocked",
+        confidence: 0,
+        legacyImport: { available: false },
+      };
+    }
+    const correction = corrections.slides?.[String(sourceSlide)] || {};
+    const hardBlocked =
+      recipe.excludedFromAutoUse === true ||
+      (recipe.hardBlockReasons || []).length > 0;
+    const safetyStatus =
+      !hardBlocked && approved.has(sourceSlide) ? "automatic" : "blocked";
+    const slotSchema = (recipe.slots || []).map((slot) => ({
+      slotId: slot.slotId,
+      sourceShapeId: slot.sourceShapeId,
+      sourceElementName: slot.name,
+      type: slot.type || "text",
+      semanticType: slot.semanticType || slot.type || "text",
+      purpose: slot.purpose || "body",
+      required:
+        slot.required === true ||
+        !["pageNumber", "date", "footer"].includes(slot.purpose),
+      maxChars: slot.maxChars,
+      maxTextUnits: slot.maxTextUnits,
+      maxLines: slot.maxLines,
+      rows: slot.rows,
+      columns: slot.columns,
+      sourceText: slot.originalText || "",
+      bbox: scaleBox(slot.bbox, sourceCanvas, inspection.canvas),
+      operation: slot.operation || slot.action || "rewrite",
+    }));
+    const correctedFamily = familyForUniversalProfile(
+      correction.layoutFamily || recipe.layoutFamily,
+    );
+    const correctedRole = normalized(
+      correction.narrativeRole || recipe.narrativeRole,
+    );
+    return {
+      ...baseSlide,
+      sourceSlide,
+      sourcePart: baseSlide.sourcePart,
+      layoutFamily: correctedFamily,
+      layoutVariant:
+        correction.layoutVariant ||
+        recipe.layoutVariant ||
+        `${correctedFamily}-${slotSchema.length}`,
+      communicationFunctions: semantic.communicationFunctions,
+      narrativeRoles: [
+        ...new Set([
+          correctedRole,
+          ...(semantic.narrativeRoles || []),
+          ...(sourceSlide === Number(openingSourceSlide) ? ["opening"] : []),
+          ...(sourceSlide === Number(closingSourceSlide) ? ["closing"] : []),
+        ]),
+      ].filter(Boolean),
+      slotSchema,
+      assetRequirements: (recipe.visualRequirements || []).map((item) => ({
+        requirementId: item.requirementId,
+        type: item.type,
+        required: item.required !== false,
+        status: item.status,
+        slotId: item.slotId,
+      })),
+      contentRecipe: semantic.contentRecipe,
+      safetyStatus,
+      confidence: safetyStatus === "automatic" ? 1 : Number(semantic.confidence || 0),
+      editability: "native-ooxml",
+      protectedElements: baseSlide.protectedElements,
+      legacyImport: {
+        available: true,
+        capsulePath: resolvedCapsule,
+        recipeFingerprint: recipe.recipeFingerprint,
+        previewSha256: recipe.previewSha256,
+        reviewBinding: correction.reviewBinding || null,
+        explicitlyApproved: approved.has(sourceSlide),
+      },
+    };
+  });
+
+  const openingCandidates = slides.filter(
+    (slide) =>
+      slide.safetyStatus === "automatic" &&
+      (slide.layoutFamily === "cover" ||
+        slide.narrativeRoles.includes("opening")),
+  );
+  const closingCandidates = slides.filter(
+    (slide) =>
+      slide.safetyStatus === "automatic" &&
+      (slide.layoutFamily === "closing" ||
+        slide.narrativeRoles.includes("closing")),
+  );
+  if (openingCandidates.length !== 1 || closingCandidates.length !== 1) {
+    const error = new Error(
+      `Strict capsule import requires exactly one approved opening and closing; opening=${openingCandidates
+        .map((slide) => slide.sourceSlide)
+        .join(",")}, closing=${closingCandidates
+        .map((slide) => slide.sourceSlide)
+        .join(",")}`,
+    );
+    error.code = "LEGACY_CAPSULE_VARIANT_UNRESOLVED";
+    throw error;
+  }
+
+  const profile = {
+    ...inspection,
+    schemaVersion: 4,
+    engine: "ppt-template-reuse-legacy-capsule-import",
+    source: {
+      ...inspection.source,
+      path: resolvedTemplate,
+      sha256: actualSha256,
+    },
+    templateKind: intelligence.templateKind,
+    templateKindConfidence: intelligence.templateKindConfidence,
+    purposeProfile: intelligence.purposeProfile,
+    densityRange: intelligence.densityRange,
+    visualBalance: intelligence.visualBalance,
+    slides,
+    capabilities: capabilityInventory(slides),
+    variantSelections: {},
+    reviewSummary: reviewSummary(slides),
+    actionRequired: null,
+    legacyImport: {
+      capsulePath: resolvedCapsule,
+      sourceSha256: actualSha256,
+      importedAt: new Date().toISOString(),
+      strictDenyByDefault: true,
+      approvedSourceSlides: [...approved].sort((left, right) => left - right),
+      openingSourceSlide: openingCandidates[0].sourceSlide,
+      closingSourceSlide: closingCandidates[0].sourceSlide,
+    },
+  };
+  profile.profileFingerprint = fingerprint({
+    source: profile.source,
+    slides: profile.slides,
+    purposeProfile: profile.purposeProfile,
+    legacyImport: {
+      sourceSha256: profile.legacyImport.sourceSha256,
+      strictDenyByDefault: true,
+      approvedSourceSlides: profile.legacyImport.approvedSourceSlides,
+      openingSourceSlide: profile.legacyImport.openingSourceSlide,
+      closingSourceSlide: profile.legacyImport.closingSourceSlide,
+    },
+  });
+
+  let persisted;
+  if (persist) {
+    const capsuleDirectory = path.join(resolveLibraryDir(home), actualSha256);
+    await fs.mkdir(capsuleDirectory, { recursive: true });
+    const profilePath = path.join(
+      capsuleDirectory,
+      "template-profile.lock.json",
+    );
+    await writeJsonAtomic(profilePath, profile);
+    await writeJsonAtomic(path.join(capsuleDirectory, "manifest.json"), {
+      schemaVersion: 2,
+      engine: "ppt-template-reuse-legacy-capsule-import",
+      sourceSha256: actualSha256,
+      profileFingerprint: profile.profileFingerprint,
+      importedFrom: resolvedCapsule,
+      updatedAt: new Date().toISOString(),
+    });
+    persisted = { capsuleDirectory, profilePath };
+  }
+  return { profile, persisted };
+}