@formfeed/devkit 0.2.0 → 0.3.0

package/index.js

@@ -70,10 +70,15 @@ function writeProjectConfig(root, config) {
 // packages/devkit/src/lib/project.ts
 import { createHash } from "node:crypto";
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, readdirSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { basename, dirname as dirname2, join as join2 } from "node:path";
+import { basename, dirname as dirname2, extname, join as join2 } from "node:path";
+import {
+  isOfficeKind,
+  normalisePartialName as normalisePartialName2,
+  officeKinds
+} from "@formfeed/engine";
 
 // packages/devkit/src/lib/partials.ts
-import { getEngine } from "@formfeed/engine";
+import { getEngine, normalisePartialName } from "@formfeed/engine";
 function includeNames(engine, source) {
   try {
     return getEngine(engine).analyze(source).includes.map((include) => include.name);
@@ -83,8 +88,10 @@ function includeNames(engine, source) {
 }
 function collectPartials(project, engine, sources) {
   const resolve3 = partialResolver(project);
+  const sharedNames = sharedPartialNames(project, engine);
   const partials = {};
   const missing = /* @__PURE__ */ new Set();
+  const shared = /* @__PURE__ */ new Set();
   const queue = sources.filter((source) => Boolean(source));
   const seen = /* @__PURE__ */ new Set();
   while (queue.length) {
@@ -92,6 +99,11 @@ function collectPartials(project, engine, sources) {
       if (seen.has(name)) continue;
       seen.add(name);
       const source = resolve3(name);
+      if (sharedNames.has(normalisePartialName(name))) {
+        shared.add(normalisePartialName(name));
+        if (source !== void 0) queue.push(source);
+        continue;
+      }
       if (source === void 0) {
         missing.add(name);
         continue;
@@ -100,65 +112,86 @@ function collectPartials(project, engine, sources) {
       queue.push(source);
     }
   }
-  return { partials, missing: [...missing].sort() };
+  return { partials, missing: [...missing].sort(), shared: [...shared].sort() };
 }
 
 // packages/devkit/src/lib/project.ts
 var readText = (path) => existsSync2(path) ? readFileSync2(path, "utf8") : null;
 function readJson(path, what) {
-  const text = readText(path);
-  if (text === null) return null;
+  const text2 = readText(path);
+  if (text2 === null) return null;
   try {
-    return JSON.parse(text);
+    return JSON.parse(text2);
   } catch (e) {
     throw new DevkitError(`${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
   }
 }
+var templateFileName = (kind) => isOfficeKind(kind) ? `template.${kind}` : "template.html";
+function sourceFilesIn(dir) {
+  return ["template.html", ...officeKinds.map((k) => `template.${k}`)].filter((name) => existsSync2(join2(dir, name)));
+}
 function listTemplateSlugs(project) {
   if (!existsSync2(project.templatesDir)) return [];
-  return readdirSync(project.templatesDir).filter((name) => existsSync2(join2(project.templatesDir, name, "template.html"))).sort();
+  return readdirSync(project.templatesDir).filter((name) => sourceFilesIn(join2(project.templatesDir, name)).length > 0).sort();
 }
 function templateDir(project, slug) {
   return join2(project.templatesDir, slug);
 }
+var sha256Of = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function readOfficeFile(dir, name) {
+  const path = join2(dir, name);
+  const bytes = new Uint8Array(readFileSync2(path));
+  return { format: extname(name).slice(1), path, bytes, sha256: sha256Of(bytes) };
+}
 function readTemplate(project, slug) {
   const dir = templateDir(project, slug);
-  const html = readText(join2(dir, "template.html"));
-  if (html === null) throw new DevkitError(`No template "${slug}" in ${project.templatesDir} (template.html missing)`);
+  const sources = sourceFilesIn(dir);
+  if (sources.length === 0)
+    throw new DevkitError(`No template "${slug}" in ${project.templatesDir} (template.html, template.docx or template.pptx missing)`);
+  if (sources.length > 1)
+    throw new DevkitError(`${dir} holds ${sources.join(" and ")}; a template folder has one of them`, "validation");
+  const file = sources[0] === "template.html" ? null : readOfficeFile(dir, sources[0]);
+  const html = file ? "" : readText(join2(dir, "template.html")) ?? "";
   const metaFile = readJson(join2(dir, "template.json"), "template.json") ?? {};
+  if (file && metaFile.kind && metaFile.kind !== file.format)
+    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds ${basename(file.path)}`, "validation");
+  if (!file && isOfficeKind(metaFile.kind))
+    throw new DevkitError(`${slug}: template.json says kind "${metaFile.kind}", but the folder holds template.html instead of template.${metaFile.kind}`, "validation");
   const meta = {
     name: metaFile.name ?? titleFromSlug(slug),
-    kind: metaFile.kind ?? "pdf",
+    kind: file?.format ?? metaFile.kind ?? "pdf",
     engine: metaFile.engine ?? project.config.engine,
     description: metaFile.description ?? null,
     tags: metaFile.tags ?? []
   };
   const settings = { ...readJson(join2(dir, "settings.json"), "settings.json") ?? {} };
-  const header = readText(join2(dir, "header.html"));
-  const footer = readText(join2(dir, "footer.html"));
+  const header = file ? null : readText(join2(dir, "header.html"));
+  const footer = file ? null : readText(join2(dir, "footer.html"));
   if (header !== null && header.trim()) settings.header = { ...settings.header ?? {}, html: header };
   if (footer !== null && footer.trim()) settings.footer = { ...settings.footer ?? {}, html: footer };
   const dataSets = {};
   const dataDir = join2(dir, "data");
   if (existsSync2(dataDir)) {
-    for (const file of readdirSync(dataDir).filter((f) => f.endsWith(".json")).sort()) {
-      dataSets[basename(file, ".json")] = readJson(join2(dataDir, file), `data/${file}`);
+    for (const file2 of readdirSync(dataDir).filter((f) => f.endsWith(".json")).sort()) {
+      dataSets[basename(file2, ".json")] = readJson(join2(dataDir, file2), `data/${file2}`);
     }
   }
-  const { partials, missing } = collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
+  const { partials, missing, shared } = file ? { partials: {}, missing: [], shared: [] } : collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
   return {
     slug,
     dir,
     meta,
+    file,
     html,
-    css: readText(join2(dir, "style.css")) ?? "",
-    head: readText(join2(dir, "head.html")) ?? "",
+    css: file ? "" : readText(join2(dir, "style.css")) ?? "",
+    head: file ? "" : readText(join2(dir, "head.html")) ?? "",
     settings,
     dataSets,
     dataSchema: readJson(join2(dir, "schema.json"), "schema.json"),
     i18n: readJson(join2(dir, "i18n.json"), "i18n.json"),
     partials,
-    missingPartials: missing
+    missingPartials: missing,
+    sharedPartials: shared
   };
 }
 function defaultData(tpl, name) {
@@ -168,18 +201,23 @@ function defaultData(tpl, name) {
     throw new DevkitError(`Data set "${name}" not found; available: ${names.join(", ") || "none"}`);
   return chosen ? { name: chosen, data: tpl.dataSets[chosen] } : { name: "empty", data: {} };
 }
-function writeTemplate(project, slug, meta, version) {
+function writeTemplate(project, slug, meta, version, file) {
   const dir = templateDir(project, slug);
+  const office = isOfficeKind(meta.kind);
+  if (office && !file) throw new DevkitError(`${slug} is a ${meta.kind} template; its document is needed to write the folder`);
   mkdirSync(join2(dir, "data"), { recursive: true });
   const settings = { ...version.settings ?? {} };
-  const header = settings.header?.html ?? "";
-  const footer = settings.footer?.html ?? "";
+  const header = office ? "" : settings.header?.html ?? "";
+  const footer = office ? "" : settings.footer?.html ?? "";
   if (settings.header) settings.header = stripHtml(settings.header);
   if (settings.footer) settings.footer = stripHtml(settings.footer);
   writeFileSync2(join2(dir, "template.json"), JSON.stringify(meta, null, 2) + "\n");
-  writeFileSync2(join2(dir, "template.html"), version.html ?? "");
-  writeOrRemove(join2(dir, "style.css"), version.css ?? "");
-  writeOrRemove(join2(dir, "head.html"), version.head ?? "");
+  for (const name of ["template.html", ...officeKinds.map((k) => `template.${k}`)])
+    if (name !== templateFileName(meta.kind) && existsSync2(join2(dir, name))) rmSync(join2(dir, name));
+  if (office) writeFileSync2(join2(dir, templateFileName(meta.kind)), file);
+  else writeFileSync2(join2(dir, "template.html"), version.html ?? "");
+  writeOrRemove(join2(dir, "style.css"), office ? "" : version.css ?? "");
+  writeOrRemove(join2(dir, "head.html"), office ? "" : version.head ?? "");
   writeOrRemove(join2(dir, "header.html"), header);
   writeOrRemove(join2(dir, "footer.html"), footer);
   writeFileSync2(join2(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
@@ -214,25 +252,38 @@ function writeOrRemove(path, content) {
   if (content) writeFileSync2(path, content);
   else if (existsSync2(path)) rmSync(path);
 }
-function versionPayload(tpl) {
+function commonPayload(tpl) {
   const sample = tpl.dataSets["default"] ?? Object.values(tpl.dataSets)[0] ?? {};
   const named = Object.fromEntries(
     Object.entries(tpl.dataSets).filter(([name]) => name !== "default")
   );
   return {
-    html: tpl.html,
-    css: tpl.css,
-    head: tpl.head,
     settings: tpl.settings,
     sample_data: sample ?? {},
     data_sets: named,
     data_schema: tpl.dataSchema,
-    i18n: tpl.i18n,
+    i18n: tpl.i18n
+  };
+}
+function officeVersionPayload(tpl) {
+  return commonPayload(tpl);
+}
+function versionPayload(tpl) {
+  return {
+    html: tpl.html,
+    css: tpl.css,
+    head: tpl.head,
+    ...commonPayload(tpl),
     // only when the template includes one, so a project without partials sends what it always sent
     ...Object.keys(tpl.partials).length ? { partials: tpl.partials } : {}
   };
 }
 function contentHash(tpl) {
+  if (tpl.file) {
+    const payload2 = officeVersionPayload(tpl);
+    const parts2 = [tpl.file.format, tpl.file.sha256, payload2.settings, payload2.sample_data, payload2.data_sets, payload2.data_schema, payload2.i18n];
+    return createHash("sha256").update(JSON.stringify(parts2)).digest("hex");
+  }
   const payload = versionPayload(tpl);
   const parts = [payload.html, payload.css, payload.head, payload.settings, payload.sample_data, payload.data_sets, payload.data_schema, payload.i18n];
   if (payload.partials) parts.push(payload.partials);
@@ -253,6 +304,7 @@ function recordSync(project, slug, version, tpl) {
     number: version.number,
     status: version.status,
     contentHash: contentHash(tpl),
+    ...tpl.file ? { fileSha256: tpl.file.sha256 } : {},
     syncedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   writeState(project, state);
@@ -261,27 +313,92 @@ function titleFromSlug(slug) {
   return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
 function partialResolver(project) {
+  let shared = null;
   return (name) => {
     for (const candidate of [name, `${name}.html`]) {
       const path = join2(project.partialsDir, candidate);
       if (existsSync2(path) && statSync(path).isFile()) return readFileSync2(path, "utf8");
     }
-    return void 0;
+    shared ??= new Set(Object.keys(readState(project).sharedPartials ?? {}));
+    const normalised = normalisePartialName2(name);
+    if (!shared.has(normalised)) return void 0;
+    return readText(sharedPartialPath(project, normalised)) ?? void 0;
+  };
+}
+function sharedPartialPath(project, name) {
+  return join2(project.partialsDir, `${name}.html`);
+}
+function sharedPartialNames(project, engine) {
+  return new Set(
+    Object.entries(readState(project).sharedPartials ?? {}).filter(([, partial]) => partial.engine === engine).map(([name]) => normalisePartialName2(name))
+  );
+}
+var partialContentHash = (source) => createHash("sha256").update(source).digest("hex");
+function recordSharedPartial(project, name, remote, source) {
+  const state = readState(project);
+  state.sharedPartials = {
+    ...state.sharedPartials ?? {},
+    [name]: { version: remote.version, engine: remote.engine, contentHash: partialContentHash(source), syncedAt: (/* @__PURE__ */ new Date()).toISOString() }
+  };
+  writeState(project, state);
+}
+
+// packages/devkit/src/lib/brand.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+import { emptyBrand } from "@formfeed/engine";
+var brandPath = (project) => join3(project.root, ".formfeed", "brand.json");
+var text = (value) => typeof value === "string" ? value : null;
+var record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+function brandFromJson(json) {
+  const body = record(json);
+  const empty = emptyBrand();
+  const colors = Object.fromEntries(Object.entries(record(body["colors"])).filter((entry) => typeof entry[1] === "string"));
+  const fonts = record(body["fonts"]);
+  const logo = record(body["logo"]);
+  return {
+    version: typeof body["version"] === "number" ? body["version"] : empty.version,
+    name: text(body["name"]),
+    colors,
+    fonts: { heading: text(fonts["heading"]), body: text(fonts["body"]) },
+    font_size: text(body["font_size"]),
+    logo: { primary: text(logo["primary"]), inverse: text(logo["inverse"]), mark: text(logo["mark"]) },
+    legal_footer: text(body["legal_footer"])
   };
 }
+function readBrand(project) {
+  const path = brandPath(project);
+  if (!existsSync3(path)) return emptyBrand();
+  try {
+    return brandFromJson(JSON.parse(readFileSync3(path, "utf8")));
+  } catch (e) {
+    throw new DevkitError(`.formfeed/brand.json is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
+  }
+}
+function writeBrand(project, brand) {
+  mkdirSync2(join3(project.root, ".formfeed"), { recursive: true });
+  const path = brandPath(project);
+  writeFileSync3(path, JSON.stringify(brand, null, 2) + "\n");
+  return path;
+}
 
 // packages/devkit/src/lib/local-render.ts
 import {
   EngineSyntaxError,
+  analyzeOffice,
   defaultHelpers,
   defaultLimits,
   flowDocument,
   getEngine as getEngine2,
+  isOfficeKind as isOfficeKind2,
   mergeSettings,
+  officeTextParts,
   pagedDocument,
+  renderOffice,
   renderVersion
 } from "@formfeed/engine";
 function diagnose(tpl, sampleData) {
+  if (tpl.file) return diagnoseOffice(tpl, tpl.file.bytes, sampleData);
   const engine = getEngine2(tpl.meta.engine);
   const diagnostics = [];
   try {
@@ -313,7 +430,59 @@ function diagnose(tpl, sampleData) {
     });
   return diagnostics;
 }
-function renderContext(project, tpl, assetBaseUrl) {
+var nowhere = { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } };
+function diagnoseOffice(tpl, file, sampleData) {
+  let analysis;
+  try {
+    analysis = analyzeOffice(file, { engine: tpl.meta.engine, sampleData });
+  } catch (e) {
+    const code = e.code;
+    return [{ severity: "error", code: typeof code === "string" ? code : "office-document-invalid", message: e instanceof Error ? e.message : String(e), range: nowhere }];
+  }
+  return analysis.diagnostics.map((d) => ({
+    severity: d.severity,
+    code: d.code,
+    message: d.text ? `${d.message} (${d.text})` : d.message,
+    range: nowhere,
+    part: d.part,
+    paragraph: d.paragraph
+  }));
+}
+async function renderOfficeLocal(project, tpl, data, options = {}) {
+  if (!tpl.file) throw new DevkitError(`${tpl.slug} is not a Word or PowerPoint template`, "validation");
+  const context = renderContext(project, tpl, options.assetBaseUrl, options.brand);
+  if (options.locale) context.locale = options.locale;
+  return renderOffice(tpl.file.bytes, { engine: tpl.meta.engine, data, context, images: options.images, random: options.random });
+}
+function officeSnapshot(filled) {
+  return officeTextParts(filled).map((part) => `--- ${part.name} ---
+${prettyXml(part.xml)}`).join("\n");
+}
+function prettyXml(xml) {
+  const lines = [];
+  let depth = 0;
+  let open = false;
+  for (const token of xml.match(/<[^>]*>|[^<]+/g) ?? []) {
+    if (token.startsWith("</")) {
+      depth = Math.max(0, depth - 1);
+      if (open && lines.length) lines[lines.length - 1] += token;
+      else lines.push("  ".repeat(depth) + token);
+      open = false;
+    } else if (token.startsWith("<?") || token.startsWith("<!")) {
+      lines.push("  ".repeat(depth) + token);
+      open = false;
+    } else if (token.startsWith("<")) {
+      lines.push("  ".repeat(depth) + token);
+      open = !token.endsWith("/>");
+      if (open) depth++;
+    } else if (token.trim() || open) {
+      if (lines.length) lines[lines.length - 1] += token;
+      else lines.push(token);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+function renderContext(project, tpl, assetBaseUrl, brand) {
   const settings = mergeSettings(tpl.settings);
   return {
     locale: settings.locale ?? "en",
@@ -323,35 +492,43 @@ function renderContext(project, tpl, assetBaseUrl) {
     helpers: defaultHelpers(),
     limits: defaultLimits,
     i18n: tpl.i18n ?? void 0,
-    assetBaseUrl
+    assetBaseUrl,
+    // the organisation's kit from `formfeed brand pull`, else the empty kit the server uses too
+    brand: brand ?? readBrand(project)
   };
 }
 async function renderLocal(project, tpl, data, options) {
-  const ctx = renderContext(project, tpl, options.assetBaseUrl);
+  const kind = htmlKind(tpl);
+  const ctx = renderContext(project, tpl, options.assetBaseUrl, options.brand);
   if (options.locale) ctx.locale = options.locale;
   return renderVersion(
-    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: mergeSettings(tpl.settings), kind: tpl.meta.kind },
+    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: mergeSettings(tpl.settings), kind },
     data,
     ctx,
     options.mode,
     options.vendor ? { vendor: options.vendor } : {}
   );
 }
+function htmlKind(tpl) {
+  if (isOfficeKind2(tpl.meta.kind)) throw new DevkitError(`${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`, "validation");
+  return tpl.meta.kind;
+}
 function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
+  const kind = htmlKind(tpl);
   const draft = {
     document: rendered.document,
     headerHtml: rendered.headerHtml,
     footerHtml: rendered.footerHtml,
     settings: rendered.settings,
-    kind: tpl.meta.kind
+    kind
   };
-  return mode === "paged" && tpl.meta.kind === "pdf" ? pagedDocument(draft, { pagedScriptUrl }) : flowDocument(draft);
+  return mode === "paged" && kind === "pdf" ? pagedDocument(draft, { pagedScriptUrl }) : flowDocument(draft);
 }
 
 // packages/devkit/src/lib/files.ts
 import { createHash as createHash2 } from "node:crypto";
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join3, relative, resolve as resolve2, sep } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname3, join as join4, relative, resolve as resolve2, sep } from "node:path";
 
 // packages/api-types/src/lib/assets.ts
 var SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
@@ -383,13 +560,13 @@ function sha256File(bytes) {
 }
 function listLocalFiles(project) {
   const listing = { files: [], skipped: [] };
-  if (!existsSync3(project.filesDir)) return listing;
-  const walk = (dir) => {
+  if (!existsSync4(project.filesDir)) return listing;
+  const walk2 = (dir) => {
     for (const entry of readdirSync2(dir, { withFileTypes: true })) {
       if (entry.name.startsWith(".")) continue;
-      const path = join3(dir, entry.name);
+      const path = join4(dir, entry.name);
       if (entry.isDirectory()) {
-        walk(path);
+        walk2(path);
         continue;
       }
       if (!entry.isFile()) continue;
@@ -401,11 +578,11 @@ function listLocalFiles(project) {
         listing.skipped.push({ path, reason });
         continue;
       }
-      const bytes = readFileSync3(path);
+      const bytes = readFileSync4(path);
       listing.files.push({ name, path, bytes: size, sha256: sha256File(bytes), contentType });
     }
   };
-  walk(project.filesDir);
+  walk2(project.filesDir);
   listing.files.sort((a, b) => a.name.localeCompare(b.name));
   return listing;
 }
@@ -417,35 +594,609 @@ function localFilePath(project, name) {
 }
 function writeLocalFile(project, name, bytes) {
   const path = localFilePath(project, name);
-  mkdirSync2(dirname3(path), { recursive: true });
-  writeFileSync3(path, bytes);
+  mkdirSync3(dirname3(path), { recursive: true });
+  writeFileSync4(path, bytes);
   return path;
 }
+
+// packages/devkit/src/lib/redact.ts
+function redactData(value, paths) {
+  if (!paths || paths.length === 0) return redactAll(value);
+  return walk(value, paths.map(parseRedactPath));
+}
+function redactString(text2) {
+  let out = "";
+  for (const ch of text2) {
+    if (/\p{Lu}/u.test(ch)) out += "A";
+    else if (/\p{L}/u.test(ch)) out += "a";
+    else if (/\p{N}/u.test(ch)) out += "0";
+    else out += ch;
+  }
+  return out;
+}
+function parseRedactPath(path) {
+  const segments = [];
+  for (const part of path.trim().split(".")) {
+    if (part === "") continue;
+    const match = /^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(part);
+    if (!match) {
+      segments.push(part);
+      continue;
+    }
+    if (match[1]) segments.push(match[1]);
+    for (const index of match[2].match(/\[[^\]]*\]/g) ?? []) {
+      const inner = index.slice(1, -1).trim();
+      segments.push(inner === "" || inner === "*" ? "*" : inner);
+    }
+  }
+  return segments;
+}
+function redactAll(value) {
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) return value.map(redactAll);
+  if (isRecord(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactAll(v)]));
+  return value;
+}
+function walk(value, patterns) {
+  if (patterns.some((p) => p.length === 0)) return redactAll(value);
+  if (Array.isArray(value)) {
+    return value.map((item, index) => {
+      const next = advance(patterns, String(index));
+      return next.length ? walk(item, next) : item;
+    });
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => {
+        const next = advance(patterns, key);
+        return [key, next.length ? walk(item, next) : item];
+      })
+    );
+  }
+  return value;
+}
+function advance(patterns, key) {
+  return patterns.filter((p) => p[0] === "*" || p[0] === key).map((p) => p.slice(1));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/devkit/src/lib/types/index.ts
+import { inferSchemaFromDataSets } from "@formfeed/engine";
+
+// packages/devkit/src/lib/types/model.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var UNSUPPORTED = [
+  "not",
+  "if",
+  "then",
+  "else",
+  "patternProperties",
+  "prefixItems",
+  "contains",
+  "dependentSchemas",
+  "dependentRequired",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "propertyNames"
+];
+function pascalCase(text2) {
+  const words = text2.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const joined = words.map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+  if (!joined) return "Field";
+  return /^[0-9]/.test(joined) ? `T${joined}` : joined;
+}
+function singular(word) {
+  if (/ies$/i.test(word) && word.length > 3) return word.slice(0, -3) + "y";
+  if (/(ss|x|ch|sh)es$/i.test(word)) return word.slice(0, -2);
+  if (/[^su]s$/i.test(word)) return word.slice(0, -1);
+  return null;
+}
+var NameRegistry = class {
+  used = /* @__PURE__ */ new Set();
+  constructor(reserved = []) {
+    for (const name of reserved) this.used.add(name);
+  }
+  claim(wanted) {
+    let name = wanted;
+    for (let i = 2; this.used.has(name); i++) name = `${wanted}${i}`;
+    this.used.add(name);
+    return name;
+  }
+};
+function relaxRequired(schema) {
+  if (Array.isArray(schema)) return schema.map(relaxRequired);
+  if (!isObject(schema)) return schema;
+  const out = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "required") continue;
+    if (key === "properties" || key === "$defs" || key === "definitions") {
+      out[key] = isObject(value) ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, relaxRequired(v)])) : value;
+    } else if (key === "examples" || key === "enum" || key === "const" || key === "default") {
+      out[key] = value;
+    } else {
+      out[key] = relaxRequired(value);
+    }
+  }
+  return out;
+}
+function docOf(schema) {
+  const lines = [];
+  if (typeof schema["title"] === "string" && schema["title"] !== schema["description"]) lines.push(schema["title"]);
+  if (typeof schema["description"] === "string") lines.push(...schema["description"].split("\n"));
+  if (typeof schema["format"] === "string") lines.push(`Format: ${schema["format"]}`);
+  const unsupported = UNSUPPORTED.filter((k) => k in schema);
+  if (unsupported.length) lines.push(`Not expressed in the types: ${unsupported.join(", ")}`);
+  if (Array.isArray(schema["examples"]) && schema["examples"].length)
+    lines.push(`@example ${JSON.stringify(schema["examples"][0])}`);
+  if (schema["deprecated"] === true) lines.push("@deprecated");
+  return lines;
+}
+var Builder = class {
+  constructor(root, base, names) {
+    this.root = root;
+    this.base = base;
+    this.names = names;
+  }
+  objects = [];
+  defs = /* @__PURE__ */ new Map();
+  rootName = "";
+  /**
+   * A plain object schema becomes the interface `rootName` itself; anything else (a nullable object,
+   * a union, an array) becomes an alias of that name, so the root never names two things.
+   */
+  build(rootName) {
+    this.rootName = rootName;
+    const s = this.root;
+    const plainObject = (s["type"] === "object" || s["type"] === void 0 && isObject(s["properties"])) && isObject(s["properties"]) && Object.keys(s["properties"]).length > 0 && !["$ref", "const", "enum", "anyOf", "oneOf", "allOf"].some((k) => k in s);
+    return this.convert(s, null, null, plainObject ? rootName : void 0);
+  }
+  /**
+   * `owner` + `key` name the objects found below: property `customer` of `Invoice` is
+   * `InvoiceCustomer`, an element of `items` is `InvoiceItem`. `exact` forces a name (the root).
+   */
+  convert(raw, owner, key, exact, depth = 0) {
+    if (raw === true || raw === void 0) return { kind: "unknown" };
+    if (raw === false) return { kind: "never" };
+    if (!isObject(raw) || depth > 48) return { kind: "unknown" };
+    const schema = raw;
+    if (typeof schema["$ref"] === "string") return this.reference(schema["$ref"]);
+    if ("const" in schema) return literal(schema["const"]);
+    if (Array.isArray(schema["enum"])) {
+      const members2 = schema["enum"].map(literal);
+      return members2.length === 1 ? members2[0] : { kind: "union", members: members2 };
+    }
+    for (const combinator of ["anyOf", "oneOf"]) {
+      const list = schema[combinator];
+      if (Array.isArray(list) && list.length) {
+        const members2 = list.map(
+          (option, i) => this.convert(option, owner, key === null ? `Option${i + 1}` : `${key}Option${i + 1}`, void 0, depth + 1)
+        );
+        return union(members2);
+      }
+    }
+    if (Array.isArray(schema["allOf"]) && schema["allOf"].length) {
+      const members2 = schema["allOf"].map(
+        (part, i) => this.convert(part, owner, key === null ? `Part${i + 1}` : `${key}Part${i + 1}`, void 0, depth + 1)
+      );
+      return members2.length === 1 ? members2[0] : { kind: "intersection", members: members2 };
+    }
+    const declared = typeof schema["type"] === "string" ? [schema["type"]] : Array.isArray(schema["type"]) ? schema["type"] : null;
+    const types = declared ?? (isObject(schema["properties"]) || isObject(schema["additionalProperties"]) ? ["object"] : "items" in schema ? ["array"] : null);
+    if (!types) {
+      const unsupported = UNSUPPORTED.filter((k) => k in schema);
+      return unsupported.length ? { kind: "unknown", note: unsupported.join(", ") } : { kind: "unknown" };
+    }
+    const members = types.map((type) => {
+      switch (type) {
+        case "object":
+          return this.object(schema, owner, key, exact, depth);
+        case "array":
+          return { kind: "array", items: this.convert(schema["items"], owner, itemKey(key), void 0, depth + 1) };
+        case "string":
+        case "number":
+        case "integer":
+        case "boolean":
+        case "null":
+          return { kind: "primitive", name: type };
+        default:
+          return { kind: "unknown" };
+      }
+    });
+    return union(members);
+  }
+  object(schema, owner, key, exact, depth) {
+    const properties = isObject(schema["properties"]) ? schema["properties"] : {};
+    const additional = schema["additionalProperties"];
+    const extra = isObject(additional) ? this.convert(additional, owner, `${key ?? ""}Value`, void 0, depth + 1) : null;
+    if (Object.keys(properties).length === 0) return { kind: "record", values: extra ?? { kind: "unknown" } };
+    const name = exact ?? this.names.claim(`${owner ?? this.base}${key === null ? "" : pascalCase(key)}`);
+    const target = { name, doc: docOf(schema), fields: [], extra };
+    this.objects.push(target);
+    const required = new Set(Array.isArray(schema["required"]) ? schema["required"] : []);
+    const nestedOwner = name === this.rootName ? this.base : name;
+    for (const [field, child] of Object.entries(properties)) {
+      target.fields.push({
+        key: field,
+        type: this.convert(child, nestedOwner, field, void 0, depth + 1),
+        required: required.has(field),
+        doc: isObject(child) ? docOf(child) : []
+      });
+    }
+    return { kind: "ref", name };
+  }
+  reference(ref) {
+    const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref);
+    if (!match) return { kind: "unknown", note: `$ref ${ref}` };
+    const known = this.defs.get(ref);
+    if (known) return { kind: "ref", name: known };
+    const section = this.root[match[1]];
+    const target = isObject(section) ? section[decodePointer(match[2])] : void 0;
+    if (!isObject(target)) return { kind: "unknown", note: `$ref ${ref}` };
+    const hasProperties = isObject(target["properties"]) && Object.keys(target["properties"]).length > 0;
+    if (!hasProperties) return this.convert(target, this.base, decodePointer(match[2]));
+    const name = this.names.claim(`${this.base}${pascalCase(decodePointer(match[2]))}`);
+    this.defs.set(ref, name);
+    this.convert(target, null, null, name);
+    return { kind: "ref", name };
+  }
+};
+var decodePointer = (part) => part.replace(/~1/g, "/").replace(/~0/g, "~");
+function itemKey(key) {
+  if (key === null) return "Item";
+  return singular(key) ?? `${key}Item`;
+}
+function literal(value) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+    return { kind: "literal", value };
+  return { kind: "unknown" };
+}
+function union(members) {
+  const flat = [];
+  for (const member of members) {
+    if (member.kind === "union") flat.push(...member.members);
+    else flat.push(member);
+  }
+  if (flat.some((m) => m.kind === "unknown")) return { kind: "unknown" };
+  const unique = flat.filter((m, i) => flat.findIndex((n) => JSON.stringify(n) === JSON.stringify(m)) === i);
+  return unique.length === 1 ? unique[0] : { kind: "union", members: unique };
+}
+function buildTypes(sources, reserved = []) {
+  const names = new NameRegistry(reserved);
+  return [...sources].sort((a, b) => a.slug.localeCompare(b.slug)).map((source) => {
+    const schema = source.origin === "inferred" ? relaxRequired(source.schema) : source.schema;
+    const base = pascalCase(source.slug);
+    const rootName = names.claim(`${base}Data`);
+    const builder = new Builder(schema, base, names);
+    const root = builder.build(rootName);
+    return {
+      slug: source.slug,
+      origin: source.origin,
+      version: source.version ?? null,
+      channel: source.channel ?? null,
+      rootName,
+      root,
+      objects: builder.objects
+    };
+  });
+}
+function originNote(t) {
+  switch (t.origin) {
+    case "local":
+      return "schema.json of the project";
+    case "stored":
+      return `stored schema of version ${t.version ?? "?"}${t.channel ? ` (channel ${t.channel})` : ""}`;
+    case "inferred":
+      return "inferred from sample data, every field optional: store a schema to make this a contract";
+  }
+}
+
+// packages/devkit/src/lib/types/emit-python.ts
+var KEYWORDS = /* @__PURE__ */ new Set([
+  "False",
+  "None",
+  "True",
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "break",
+  "class",
+  "continue",
+  "def",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "finally",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "nonlocal",
+  "not",
+  "or",
+  "pass",
+  "raise",
+  "return",
+  "try",
+  "while",
+  "with",
+  "yield"
+]);
+var isIdentifier = (key) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) && !KEYWORDS.has(key);
+function methodName(slug) {
+  const name = slug.replace(/[^A-Za-z0-9_]+/g, "_").toLowerCase();
+  return isIdentifier(name) ? name : `${/^[0-9]/.test(name) ? "t_" : ""}${name}${KEYWORDS.has(name) ? "_" : ""}`;
+}
+function expression(node, quoteRefs) {
+  switch (node.kind) {
+    case "unknown":
+      return "Any";
+    case "never":
+      return "Never";
+    case "primitive":
+      return { string: "str", number: "float", integer: "int", boolean: "bool", null: "None" }[node.name];
+    case "literal":
+      return node.value === null ? "None" : `Literal[${pythonLiteral(node.value)}]`;
+    case "array":
+      return `list[${expression(node.items, quoteRefs)}]`;
+    case "record":
+      return `dict[str, ${expression(node.values, quoteRefs)}]`;
+    case "ref":
+      return quoteRefs ? JSON.stringify(node.name) : node.name;
+    case "union": {
+      const literals = node.members.filter(
+        (m) => m.kind === "literal" && m.value !== null
+      );
+      const rest = node.members.filter((m) => !(m.kind === "literal" && m.value !== null));
+      const parts = [
+        ...literals.length ? [`Literal[${literals.map((l) => pythonLiteral(l.value)).join(", ")}]`] : [],
+        ...rest.map((m) => expression(m, quoteRefs))
+      ];
+      if (quoteRefs && rest.some((m) => m.kind === "ref")) return `Union[${parts.join(", ")}]`;
+      return parts.join(" | ");
+    }
+    case "intersection":
+      return expression(node.members[0] ?? { kind: "unknown" }, quoteRefs);
+  }
+}
+function pythonLiteral(value) {
+  if (value === null) return "None";
+  if (typeof value === "boolean") return value ? "True" : "False";
+  return JSON.stringify(value);
+}
+function docstring(lines, indent) {
+  if (lines.length === 0) return [];
+  const safe = lines.map((line) => line.replace(/\\/g, "\\\\").replace(/"""/g, '\\"\\"\\"'));
+  if (safe.length === 1) return [`${indent}"""${safe[0]}"""`];
+  return [`${indent}"""${safe[0]}`, ...safe.slice(1).map((line) => `${indent}${line}`.trimEnd()), `${indent}"""`];
+}
+function emitObject(object) {
+  const functional = object.fields.some((f) => !isIdentifier(f.key));
+  const field = (type, required, quote) => {
+    const text2 = expression(type, quote);
+    return required ? text2 : `NotRequired[${text2}]`;
+  };
+  if (functional) {
+    const out2 = [`${object.name} = TypedDict(`, `    ${JSON.stringify(object.name)},`, "    {"];
+    for (const f of object.fields) out2.push(`        ${JSON.stringify(f.key)}: ${field(f.type, f.required, true)},`);
+    out2.push("    },", ")");
+    if (object.doc.length) out2.unshift(...object.doc.map((line) => `# ${line}`));
+    return out2;
+  }
+  const out = [`class ${object.name}(TypedDict):`, ...docstring(object.doc, "    ")];
+  for (const f of object.fields) {
+    out.push(`    ${f.key}: ${field(f.type, f.required, false)}`);
+    out.push(...docstring(f.doc, "    "));
+  }
+  if (object.fields.length === 0) out.push("    pass");
+  return out;
+}
+function emitPython(templates) {
+  const lines = [
+    "# Generated by `formfeed types`. Do not edit: run it again when a template schema changes.",
+    "#",
+    ...templates.map((t) => `# ${t.slug}: ${originNote(t)}`),
+    "",
+    "from __future__ import annotations",
+    "",
+    "from typing import Any, Literal, Union, cast",
+    "",
+    "from typing_extensions import Never, NotRequired, TypedDict",
+    "",
+    "from formfeed import AsyncFormfeed, Formfeed, Render",
+    "",
+    "__all__ = [",
+    ...templates.map((t) => `    ${JSON.stringify(t.rootName)},`),
+    '    "TypedRenders",',
+    '    "AsyncTypedRenders",',
+    '    "typed",',
+    '    "typed_async",',
+    "]"
+  ];
+  for (const template of templates) {
+    lines.push("", "", `# --- ${template.slug}`);
+    for (const object of [...template.objects].reverse()) lines.push("", ...emitObject(object));
+    const isClass = template.root.kind === "ref" && template.root.name === template.rootName;
+    if (!isClass) lines.push("", `${template.rootName} = ${expression(template.root, true)}`);
+  }
+  const wrapper = (name, isAsync) => {
+    const example = templates[0] ? methodName(templates[0].slug) : "invoice";
+    const out = [
+      "",
+      "",
+      `class ${name}:`,
+      `    """Renders with \`data\` checked per template: \`${isAsync ? "await typed_async(client)" : "typed(client)"}.${example}(data, **options)\`."""`,
+      "",
+      `    def __init__(self, client: ${isAsync ? "AsyncFormfeed" : "Formfeed"}) -> None:`,
+      "        self._renders: Any = client.renders"
+    ];
+    for (const t of templates) {
+      out.push(
+        "",
+        `    ${isAsync ? "async " : ""}def ${methodName(t.slug)}(self, data: ${t.rootName}, **options: Any) -> Render:`,
+        `        return cast(Render, ${isAsync ? "await " : ""}self._renders.create(template=${JSON.stringify(t.slug)}, data=data, **options))`
+      );
+    }
+    return out;
+  };
+  lines.push(...wrapper("TypedRenders", false), ...wrapper("AsyncTypedRenders", true));
+  lines.push(
+    "",
+    "",
+    "def typed(client: Formfeed) -> TypedRenders:",
+    "    return TypedRenders(client)",
+    "",
+    "",
+    "def typed_async(client: AsyncFormfeed) -> AsyncTypedRenders:",
+    "    return AsyncTypedRenders(client)"
+  );
+  return lines.join("\n") + "\n";
+}
+
+// packages/devkit/src/lib/types/emit-ts.ts
+var identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var quoteKey = (key) => identifier.test(key) ? key : JSON.stringify(key);
+function expression2(node, nested = false) {
+  switch (node.kind) {
+    case "unknown":
+      return "unknown";
+    case "never":
+      return "never";
+    case "primitive":
+      return node.name === "integer" ? "number" : node.name;
+    case "literal":
+      return JSON.stringify(node.value);
+    case "array": {
+      const inner = expression2(node.items, true);
+      return /[|&]/.test(inner) ? `Array<${expression2(node.items)}>` : `${inner}[]`;
+    }
+    case "record":
+      return `Record<string, ${expression2(node.values)}>`;
+    case "ref":
+      return node.name;
+    case "union": {
+      const text2 = node.members.map((m) => expression2(m, true)).join(" | ");
+      return nested ? `(${text2})` : text2;
+    }
+    case "intersection": {
+      const text2 = node.members.map((m) => expression2(m, true)).join(" & ");
+      return nested ? `(${text2})` : text2;
+    }
+  }
+}
+function docBlock(lines, indent) {
+  if (lines.length === 0) return [];
+  const safe = lines.map((line) => line.replace(/\*\//g, "*\\/"));
+  if (safe.length === 1) return [`${indent}/** ${safe[0]} */`];
+  return [`${indent}/**`, ...safe.map((line) => `${indent} * ${line}`.trimEnd()), `${indent} */`];
+}
+function emitObject2(object) {
+  const out = [...docBlock(object.doc, ""), `export interface ${object.name} {`];
+  for (const field of object.fields) {
+    out.push(...docBlock(field.doc, "  "));
+    out.push(`  ${quoteKey(field.key)}${field.required ? "" : "?"}: ${expression2(field.type)};`);
+  }
+  if (object.extra) {
+    out.push(`  /** Further fields: ${expression2(object.extra).replace(/\*\//g, "*\\/")} */`);
+    out.push("  [key: string]: unknown;");
+  }
+  out.push("}");
+  return out;
+}
+function emitTypeScript(templates, options = {}) {
+  const sdk = options.sdkModule ?? "@formfeed/sdk";
+  const lines = [
+    "// Generated by `formfeed types`. Do not edit: run it again when a template schema changes.",
+    "//",
+    ...templates.map((t) => `// ${t.slug}: ${originNote(t)}`),
+    "",
+    `declare module ${JSON.stringify(sdk)} {`,
+    "  interface FormfeedTemplates {",
+    ...templates.map((t) => `    ${JSON.stringify(t.slug)}: ${t.rootName};`),
+    "  }",
+    "}"
+  ];
+  for (const template of templates) {
+    lines.push("", `// --- ${template.slug}`);
+    const isInterface = template.root.kind === "ref" && template.root.name === template.rootName;
+    if (!isInterface) lines.push("", `export type ${template.rootName} = ${expression2(template.root)};`);
+    for (const object of template.objects) lines.push("", ...emitObject2(object));
+  }
+  if (templates.length === 0) lines.push("", "export {};");
+  return lines.join("\n") + "\n";
+}
+
+// packages/devkit/src/lib/types/index.ts
+var defaultTypesFile = {
+  ts: "formfeed.d.ts",
+  python: "formfeed_templates.py"
+};
+function localTypeSource(tpl) {
+  if (tpl.dataSchema) return { slug: tpl.slug, schema: tpl.dataSchema, origin: "local" };
+  const sets = Object.values(tpl.dataSets);
+  return {
+    slug: tpl.slug,
+    schema: inferSchemaFromDataSets(sets.length ? sets : [{}]),
+    origin: "inferred"
+  };
+}
+function generateTypes(sources, language, options = {}) {
+  const reserved = language === "python" ? ["TypedRenders", "AsyncTypedRenders", "Formfeed", "AsyncFormfeed", "Render", "Any", "Literal", "Union", "Never", "NotRequired", "TypedDict"] : ["FormfeedTemplates"];
+  const model = buildTypes(sources, reserved);
+  return language === "python" ? emitPython(model) : emitTypeScript(model, options);
+}
 export {
   DevkitError,
+  brandFromJson,
+  brandPath,
   collectPartials,
   contentHash,
   contentTypeFor,
   defaultData,
   defaultProjectConfig,
+  defaultTypesFile,
   diagnose,
   findProject,
+  generateTypes,
   listLocalFiles,
   listTemplateSlugs,
   loadProject,
   localFilePath,
+  localTypeSource,
+  officeSnapshot,
+  officeVersionPayload,
+  parseRedactPath,
+  partialContentHash,
   partialResolver,
+  prettyXml,
   previewDocument,
   projectAround,
+  readBrand,
   readState,
   readTemplate,
+  recordSharedPartial,
   recordSync,
+  redactData,
+  redactString,
   renderContext,
   renderLocal,
+  renderOfficeLocal,
   sha256File,
+  sharedPartialNames,
+  sharedPartialPath,
   templateDir,
+  templateFileName,
   titleFromSlug,
   versionPayload,
+  writeBrand,
   writeLocalFile,
   writePartials,
   writeProjectConfig,