@formfeed/devkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Staudt IT-Dienstleistungen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @formfeed/devkit
+
+The local half of the [Formfeed](https://formfeed.dev) development kit: template folders, project
+configuration (`formfeed.json`) and offline rendering with the same engine the API uses. The
+[`formfeed` CLI](https://www.npmjs.com/package/formfeed) and
+[`@formfeed/testing`](https://www.npmjs.com/package/@formfeed/testing) are built on it; use it
+directly when you write your own tooling around a template repository.
+
+```bash
+npm install @formfeed/devkit
+```
+
+```ts
+import { defaultData, diagnose, projectAround, readTemplate, renderLocal } from '@formfeed/devkit';
+
+// a folder with template.html, template.json, styles.css, data/*.json (see the project layout docs)
+const project = projectAround('templates/invoice-de');
+const tpl = readTemplate(project, 'invoice-de');
+const { data } = defaultData(tpl); // data/default.json, or the first data set
+
+console.log(diagnose(tpl, data)); // the editor's diagnostics: syntax errors, unknown variables
+const { document } = await renderLocal(project, tpl, data, { mode: 'print' }); // complete HTML, no browser
+```
+
+Errors are `DevkitError` instances with a `code`, which the CLI maps to its exit codes.
+
+## Documentation
+
+- [Development kit overview](https://docs.formfeed.dev/devkit/overview)
+- [Project layout](https://docs.formfeed.dev/devkit/project-layout)
+
+## Licence
+
+MIT

package/index.cjs

@@ -0,0 +1,341 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/devkit/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DevkitError: () => DevkitError,
+  contentHash: () => contentHash,
+  defaultData: () => defaultData,
+  defaultProjectConfig: () => defaultProjectConfig,
+  diagnose: () => diagnose,
+  findProject: () => findProject,
+  listTemplateSlugs: () => listTemplateSlugs,
+  loadProject: () => loadProject,
+  partialResolver: () => partialResolver,
+  previewDocument: () => previewDocument,
+  projectAround: () => projectAround,
+  readState: () => readState,
+  readTemplate: () => readTemplate,
+  recordSync: () => recordSync,
+  renderContext: () => renderContext,
+  renderLocal: () => renderLocal,
+  templateDir: () => templateDir,
+  titleFromSlug: () => titleFromSlug,
+  versionPayload: () => versionPayload,
+  writeProjectConfig: () => writeProjectConfig,
+  writeState: () => writeState,
+  writeTemplate: () => writeTemplate
+});
+module.exports = __toCommonJS(index_exports);
+
+// packages/devkit/src/lib/errors.ts
+var DevkitError = class extends Error {
+  constructor(message, code = "usage") {
+    super(message);
+    this.code = code;
+  }
+  name = "DevkitError";
+};
+
+// packages/devkit/src/lib/project-config.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var defaultProjectConfig = {
+  templatesDir: "templates",
+  partialsDir: "partials",
+  engine: "jinja2",
+  ignore: ["**/drafts/**"]
+};
+function findProject(cwd = process.cwd()) {
+  let dir = (0, import_node_path.resolve)(cwd);
+  for (; ; ) {
+    const candidate = (0, import_node_path.join)(dir, "formfeed.json");
+    if ((0, import_node_fs.existsSync)(candidate)) return loadProject(candidate);
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function loadProject(configPath) {
+  let raw;
+  try {
+    raw = JSON.parse((0, import_node_fs.readFileSync)(configPath, "utf8"));
+  } catch {
+    throw new DevkitError(`${configPath} is not valid JSON`);
+  }
+  const config = { ...defaultProjectConfig, ...raw };
+  const root = (0, import_node_path.dirname)(configPath);
+  return { root, configPath, config, templatesDir: (0, import_node_path.resolve)(root, config.templatesDir), partialsDir: (0, import_node_path.resolve)(root, config.partialsDir) };
+}
+function projectAround(templateFolder) {
+  const dir = (0, import_node_path.resolve)(templateFolder);
+  const found = findProject(dir);
+  if (found) return found;
+  const templatesDir = (0, import_node_path.dirname)(dir);
+  const root = (0, import_node_path.dirname)(templatesDir);
+  return {
+    root,
+    configPath: null,
+    config: { ...defaultProjectConfig, templatesDir, partialsDir: (0, import_node_path.join)(root, "partials") },
+    templatesDir,
+    partialsDir: (0, import_node_path.join)(root, "partials")
+  };
+}
+function writeProjectConfig(root, config) {
+  const path = (0, import_node_path.join)(root, "formfeed.json");
+  const full = { ...defaultProjectConfig, ...config };
+  (0, import_node_fs.writeFileSync)(path, JSON.stringify(full, null, 2) + "\n");
+  return path;
+}
+
+// packages/devkit/src/lib/project.ts
+var import_node_crypto = require("node:crypto");
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var readText = (path) => (0, import_node_fs2.existsSync)(path) ? (0, import_node_fs2.readFileSync)(path, "utf8") : null;
+function readJson(path, what) {
+  const text = readText(path);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new DevkitError(`${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
+  }
+}
+function listTemplateSlugs(project) {
+  if (!(0, import_node_fs2.existsSync)(project.templatesDir)) return [];
+  return (0, import_node_fs2.readdirSync)(project.templatesDir).filter((name) => (0, import_node_fs2.existsSync)((0, import_node_path2.join)(project.templatesDir, name, "template.html"))).sort();
+}
+function templateDir(project, slug) {
+  return (0, import_node_path2.join)(project.templatesDir, slug);
+}
+function readTemplate(project, slug) {
+  const dir = templateDir(project, slug);
+  const html = readText((0, import_node_path2.join)(dir, "template.html"));
+  if (html === null) throw new DevkitError(`No template "${slug}" in ${project.templatesDir} (template.html missing)`);
+  const metaFile = readJson((0, import_node_path2.join)(dir, "template.json"), "template.json") ?? {};
+  const meta = {
+    name: metaFile.name ?? titleFromSlug(slug),
+    kind: metaFile.kind ?? "pdf",
+    engine: metaFile.engine ?? project.config.engine,
+    description: metaFile.description ?? null,
+    tags: metaFile.tags ?? []
+  };
+  const settings = { ...readJson((0, import_node_path2.join)(dir, "settings.json"), "settings.json") ?? {} };
+  const header = readText((0, import_node_path2.join)(dir, "header.html"));
+  const footer = readText((0, import_node_path2.join)(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 = (0, import_node_path2.join)(dir, "data");
+  if ((0, import_node_fs2.existsSync)(dataDir)) {
+    for (const file of (0, import_node_fs2.readdirSync)(dataDir).filter((f) => f.endsWith(".json")).sort()) {
+      dataSets[(0, import_node_path2.basename)(file, ".json")] = readJson((0, import_node_path2.join)(dataDir, file), `data/${file}`);
+    }
+  }
+  return {
+    slug,
+    dir,
+    meta,
+    html,
+    css: readText((0, import_node_path2.join)(dir, "style.css")) ?? "",
+    head: readText((0, import_node_path2.join)(dir, "head.html")) ?? "",
+    settings,
+    dataSets,
+    dataSchema: readJson((0, import_node_path2.join)(dir, "schema.json"), "schema.json"),
+    i18n: readJson((0, import_node_path2.join)(dir, "i18n.json"), "i18n.json")
+  };
+}
+function defaultData(tpl, name) {
+  const names = Object.keys(tpl.dataSets);
+  const chosen = name ?? (names.includes("default") ? "default" : names[0]);
+  if (name && !(name in tpl.dataSets))
+    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) {
+  const dir = templateDir(project, slug);
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.join)(dir, "data"), { recursive: true });
+  const settings = { ...version.settings ?? {} };
+  const header = settings.header?.html ?? "";
+  const footer = settings.footer?.html ?? "";
+  if (settings.header) settings.header = stripHtml(settings.header);
+  if (settings.footer) settings.footer = stripHtml(settings.footer);
+  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "template.json"), JSON.stringify(meta, null, 2) + "\n");
+  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "template.html"), version.html ?? "");
+  writeOrRemove((0, import_node_path2.join)(dir, "style.css"), version.css ?? "");
+  writeOrRemove((0, import_node_path2.join)(dir, "head.html"), version.head ?? "");
+  writeOrRemove((0, import_node_path2.join)(dir, "header.html"), header);
+  writeOrRemove((0, import_node_path2.join)(dir, "footer.html"), footer);
+  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
+  (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "data", "default.json"), JSON.stringify(version.sample_data ?? {}, null, 2) + "\n");
+  for (const [name, data] of Object.entries(version.data_sets ?? {}))
+    if (name !== "default" && /^[\w.-]+$/.test(name))
+      (0, import_node_fs2.writeFileSync)((0, import_node_path2.join)(dir, "data", `${name}.json`), JSON.stringify(data ?? {}, null, 2) + "\n");
+  writeOrRemove((0, import_node_path2.join)(dir, "schema.json"), version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : "");
+  writeOrRemove((0, import_node_path2.join)(dir, "i18n.json"), version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : "");
+  return dir;
+}
+function stripHtml(part) {
+  const { html: _html, ...rest } = part;
+  void _html;
+  return Object.keys(rest).length ? rest : null;
+}
+function writeOrRemove(path, content) {
+  if (content) (0, import_node_fs2.writeFileSync)(path, content);
+  else if ((0, import_node_fs2.existsSync)(path)) (0, import_node_fs2.rmSync)(path);
+}
+function versionPayload(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
+  };
+}
+function contentHash(tpl) {
+  const payload = versionPayload(tpl);
+  return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify([payload.html, payload.css, payload.head, payload.settings, payload.sample_data, payload.data_sets, payload.data_schema, payload.i18n])).digest("hex");
+}
+var statePath = (project) => (0, import_node_path2.join)(project.root, ".formfeed", "state.json");
+function readState(project) {
+  return readJson(statePath(project), ".formfeed/state.json") ?? { templates: {} };
+}
+function writeState(project, state) {
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.join)(project.root, ".formfeed"), { recursive: true });
+  (0, import_node_fs2.writeFileSync)(statePath(project), JSON.stringify(state, null, 2) + "\n");
+}
+function recordSync(project, slug, version, tpl) {
+  const state = readState(project);
+  state.templates[slug] = {
+    checksum: version.checksum,
+    number: version.number,
+    status: version.status,
+    contentHash: contentHash(tpl),
+    syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeState(project, state);
+}
+function titleFromSlug(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function partialResolver(project) {
+  return (name) => {
+    for (const candidate of [name, `${name}.html`]) {
+      const path = (0, import_node_path2.join)(project.partialsDir, candidate);
+      if ((0, import_node_fs2.existsSync)(path) && (0, import_node_fs2.statSync)(path).isFile()) return (0, import_node_fs2.readFileSync)(path, "utf8");
+    }
+    return void 0;
+  };
+}
+
+// packages/devkit/src/lib/local-render.ts
+var import_engine = require("@formfeed/engine");
+function diagnose(tpl, sampleData) {
+  const engine = (0, import_engine.getEngine)(tpl.meta.engine);
+  const diagnostics = [];
+  try {
+    engine.compile(tpl.html, { name: tpl.slug });
+  } catch (e) {
+    if (e instanceof import_engine.EngineSyntaxError) {
+      diagnostics.push({
+        severity: "error",
+        code: "syntax-error",
+        message: e.message,
+        range: { start: { line: e.line ?? 1, column: e.column ?? 1 }, end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 } }
+      });
+    } else throw e;
+  }
+  diagnostics.push(...engine.analyze(tpl.html, { sampleData }).diagnostics);
+  for (const [part, source] of [
+    ["header", tpl.settings.header?.html],
+    ["footer", tpl.settings.footer?.html]
+  ]) {
+    if (!source) continue;
+    for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
+  }
+  return diagnostics;
+}
+function renderContext(project, tpl) {
+  const settings = (0, import_engine.mergeSettings)(tpl.settings);
+  return {
+    locale: settings.locale ?? "en",
+    timezone: settings.timezone ?? "UTC",
+    currency: settings.currency ?? "EUR",
+    partials: partialResolver(project),
+    helpers: (0, import_engine.defaultHelpers)(),
+    limits: import_engine.defaultLimits,
+    i18n: tpl.i18n ?? void 0
+  };
+}
+async function renderLocal(project, tpl, data, options) {
+  const ctx = renderContext(project, tpl);
+  if (options.locale) ctx.locale = options.locale;
+  return (0, import_engine.renderVersion)(
+    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: (0, import_engine.mergeSettings)(tpl.settings), kind: tpl.meta.kind },
+    data,
+    ctx,
+    options.mode,
+    options.vendor ? { vendor: options.vendor } : {}
+  );
+}
+function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
+  const draft = {
+    document: rendered.document,
+    headerHtml: rendered.headerHtml,
+    footerHtml: rendered.footerHtml,
+    settings: rendered.settings,
+    kind: tpl.meta.kind
+  };
+  return mode === "paged" && tpl.meta.kind === "pdf" ? (0, import_engine.pagedDocument)(draft, { pagedScriptUrl }) : (0, import_engine.flowDocument)(draft);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DevkitError,
+  contentHash,
+  defaultData,
+  defaultProjectConfig,
+  diagnose,
+  findProject,
+  listTemplateSlugs,
+  loadProject,
+  partialResolver,
+  previewDocument,
+  projectAround,
+  readState,
+  readTemplate,
+  recordSync,
+  renderContext,
+  renderLocal,
+  templateDir,
+  titleFromSlug,
+  versionPayload,
+  writeProjectConfig,
+  writeState,
+  writeTemplate
+});

package/index.js

@@ -0,0 +1,302 @@
+// packages/devkit/src/lib/errors.ts
+var DevkitError = class extends Error {
+  constructor(message, code = "usage") {
+    super(message);
+    this.code = code;
+  }
+  name = "DevkitError";
+};
+
+// packages/devkit/src/lib/project-config.ts
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+var defaultProjectConfig = {
+  templatesDir: "templates",
+  partialsDir: "partials",
+  engine: "jinja2",
+  ignore: ["**/drafts/**"]
+};
+function findProject(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    const candidate = join(dir, "formfeed.json");
+    if (existsSync(candidate)) return loadProject(candidate);
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function loadProject(configPath) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    throw new DevkitError(`${configPath} is not valid JSON`);
+  }
+  const config = { ...defaultProjectConfig, ...raw };
+  const root = dirname(configPath);
+  return { root, configPath, config, templatesDir: resolve(root, config.templatesDir), partialsDir: resolve(root, config.partialsDir) };
+}
+function projectAround(templateFolder) {
+  const dir = resolve(templateFolder);
+  const found = findProject(dir);
+  if (found) return found;
+  const templatesDir = dirname(dir);
+  const root = dirname(templatesDir);
+  return {
+    root,
+    configPath: null,
+    config: { ...defaultProjectConfig, templatesDir, partialsDir: join(root, "partials") },
+    templatesDir,
+    partialsDir: join(root, "partials")
+  };
+}
+function writeProjectConfig(root, config) {
+  const path = join(root, "formfeed.json");
+  const full = { ...defaultProjectConfig, ...config };
+  writeFileSync(path, JSON.stringify(full, null, 2) + "\n");
+  return path;
+}
+
+// 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, join as join2 } from "node:path";
+var readText = (path) => existsSync2(path) ? readFileSync2(path, "utf8") : null;
+function readJson(path, what) {
+  const text = readText(path);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new DevkitError(`${what} is not valid JSON: ${path} (${e instanceof Error ? e.message : e})`, "validation");
+  }
+}
+function listTemplateSlugs(project) {
+  if (!existsSync2(project.templatesDir)) return [];
+  return readdirSync(project.templatesDir).filter((name) => existsSync2(join2(project.templatesDir, name, "template.html"))).sort();
+}
+function templateDir(project, slug) {
+  return join2(project.templatesDir, slug);
+}
+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 metaFile = readJson(join2(dir, "template.json"), "template.json") ?? {};
+  const meta = {
+    name: metaFile.name ?? titleFromSlug(slug),
+    kind: 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"));
+  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}`);
+    }
+  }
+  return {
+    slug,
+    dir,
+    meta,
+    html,
+    css: readText(join2(dir, "style.css")) ?? "",
+    head: readText(join2(dir, "head.html")) ?? "",
+    settings,
+    dataSets,
+    dataSchema: readJson(join2(dir, "schema.json"), "schema.json"),
+    i18n: readJson(join2(dir, "i18n.json"), "i18n.json")
+  };
+}
+function defaultData(tpl, name) {
+  const names = Object.keys(tpl.dataSets);
+  const chosen = name ?? (names.includes("default") ? "default" : names[0]);
+  if (name && !(name in tpl.dataSets))
+    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) {
+  const dir = templateDir(project, slug);
+  mkdirSync(join2(dir, "data"), { recursive: true });
+  const settings = { ...version.settings ?? {} };
+  const header = settings.header?.html ?? "";
+  const footer = 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 ?? "");
+  writeOrRemove(join2(dir, "header.html"), header);
+  writeOrRemove(join2(dir, "footer.html"), footer);
+  writeFileSync2(join2(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
+  writeFileSync2(join2(dir, "data", "default.json"), JSON.stringify(version.sample_data ?? {}, null, 2) + "\n");
+  for (const [name, data] of Object.entries(version.data_sets ?? {}))
+    if (name !== "default" && /^[\w.-]+$/.test(name))
+      writeFileSync2(join2(dir, "data", `${name}.json`), JSON.stringify(data ?? {}, null, 2) + "\n");
+  writeOrRemove(join2(dir, "schema.json"), version.data_schema ? JSON.stringify(version.data_schema, null, 2) + "\n" : "");
+  writeOrRemove(join2(dir, "i18n.json"), version.i18n ? JSON.stringify(version.i18n, null, 2) + "\n" : "");
+  return dir;
+}
+function stripHtml(part) {
+  const { html: _html, ...rest } = part;
+  void _html;
+  return Object.keys(rest).length ? rest : null;
+}
+function writeOrRemove(path, content) {
+  if (content) writeFileSync2(path, content);
+  else if (existsSync2(path)) rmSync(path);
+}
+function versionPayload(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
+  };
+}
+function contentHash(tpl) {
+  const payload = versionPayload(tpl);
+  return createHash("sha256").update(JSON.stringify([payload.html, payload.css, payload.head, payload.settings, payload.sample_data, payload.data_sets, payload.data_schema, payload.i18n])).digest("hex");
+}
+var statePath = (project) => join2(project.root, ".formfeed", "state.json");
+function readState(project) {
+  return readJson(statePath(project), ".formfeed/state.json") ?? { templates: {} };
+}
+function writeState(project, state) {
+  mkdirSync(join2(project.root, ".formfeed"), { recursive: true });
+  writeFileSync2(statePath(project), JSON.stringify(state, null, 2) + "\n");
+}
+function recordSync(project, slug, version, tpl) {
+  const state = readState(project);
+  state.templates[slug] = {
+    checksum: version.checksum,
+    number: version.number,
+    status: version.status,
+    contentHash: contentHash(tpl),
+    syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeState(project, state);
+}
+function titleFromSlug(slug) {
+  return slug.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function partialResolver(project) {
+  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;
+  };
+}
+
+// packages/devkit/src/lib/local-render.ts
+import {
+  EngineSyntaxError,
+  defaultHelpers,
+  defaultLimits,
+  flowDocument,
+  getEngine,
+  mergeSettings,
+  pagedDocument,
+  renderVersion
+} from "@formfeed/engine";
+function diagnose(tpl, sampleData) {
+  const engine = getEngine(tpl.meta.engine);
+  const diagnostics = [];
+  try {
+    engine.compile(tpl.html, { name: tpl.slug });
+  } catch (e) {
+    if (e instanceof EngineSyntaxError) {
+      diagnostics.push({
+        severity: "error",
+        code: "syntax-error",
+        message: e.message,
+        range: { start: { line: e.line ?? 1, column: e.column ?? 1 }, end: { line: e.line ?? 1, column: (e.column ?? 1) + 1 } }
+      });
+    } else throw e;
+  }
+  diagnostics.push(...engine.analyze(tpl.html, { sampleData }).diagnostics);
+  for (const [part, source] of [
+    ["header", tpl.settings.header?.html],
+    ["footer", tpl.settings.footer?.html]
+  ]) {
+    if (!source) continue;
+    for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
+  }
+  return diagnostics;
+}
+function renderContext(project, tpl) {
+  const settings = mergeSettings(tpl.settings);
+  return {
+    locale: settings.locale ?? "en",
+    timezone: settings.timezone ?? "UTC",
+    currency: settings.currency ?? "EUR",
+    partials: partialResolver(project),
+    helpers: defaultHelpers(),
+    limits: defaultLimits,
+    i18n: tpl.i18n ?? void 0
+  };
+}
+async function renderLocal(project, tpl, data, options) {
+  const ctx = renderContext(project, tpl);
+  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 },
+    data,
+    ctx,
+    options.mode,
+    options.vendor ? { vendor: options.vendor } : {}
+  );
+}
+function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
+  const draft = {
+    document: rendered.document,
+    headerHtml: rendered.headerHtml,
+    footerHtml: rendered.footerHtml,
+    settings: rendered.settings,
+    kind: tpl.meta.kind
+  };
+  return mode === "paged" && tpl.meta.kind === "pdf" ? pagedDocument(draft, { pagedScriptUrl }) : flowDocument(draft);
+}
+export {
+  DevkitError,
+  contentHash,
+  defaultData,
+  defaultProjectConfig,
+  diagnose,
+  findProject,
+  listTemplateSlugs,
+  loadProject,
+  partialResolver,
+  previewDocument,
+  projectAround,
+  readState,
+  readTemplate,
+  recordSync,
+  renderContext,
+  renderLocal,
+  templateDir,
+  titleFromSlug,
+  versionPayload,
+  writeProjectConfig,
+  writeState,
+  writeTemplate
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@formfeed/devkit",
+  "version": "0.1.0",
+  "description": "Formfeed template folders, project config and local rendering, shared by the CLI and @formfeed/testing.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./index.js"
+      },
+      "require": {
+        "types": "./types/index.d.cts",
+        "default": "./index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "*.js",
+    "*.cjs",
+    "types",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@formfeed/engine": "0.1.0",
+    "@formfeed/sdk": "0.1.0"
+  },
+  "keywords": [
+    "formfeed",
+    "templates",
+    "pdf",
+    "devkit"
+  ],
+  "homepage": "https://docs.formfeed.dev/devkit/overview",
+  "author": {
+    "name": "Formfeed",
+    "email": "support@formfeed.dev",
+    "url": "https://formfeed.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/formfeed-dev/formfeed.git",
+    "directory": "packages/devkit"
+  },
+  "bugs": {
+    "url": "https://github.com/formfeed-dev/formfeed/issues",
+    "email": "support@formfeed.dev"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/types/index.d.cts

@@ -0,0 +1,7 @@
+export { DevkitError } from './lib/errors.cjs';
+export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.cjs';
+export type { Project, ProjectConfig } from './lib/project-config.cjs';
+export { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writeState, writeTemplate, } from './lib/project.cjs';
+export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.cjs';
+export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.cjs';
+export type { LocalRenderOptions } from './lib/local-render.cjs';

package/types/index.d.ts

@@ -0,0 +1,7 @@
+export { DevkitError } from './lib/errors.js';
+export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.js';
+export type { Project, ProjectConfig } from './lib/project-config.js';
+export { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writeState, writeTemplate, } from './lib/project.js';
+export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.js';
+export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.js';
+export type { LocalRenderOptions } from './lib/local-render.js';

package/types/lib/errors.d.cts

@@ -0,0 +1,6 @@
+/** Errors of the development kit; the CLI maps `code` to its exit codes. */
+export declare class DevkitError extends Error {
+    readonly code: 'usage' | 'validation';
+    readonly name = "DevkitError";
+    constructor(message: string, code?: 'usage' | 'validation');
+}

package/types/lib/errors.d.ts

@@ -0,0 +1,6 @@
+/** Errors of the development kit; the CLI maps `code` to its exit codes. */
+export declare class DevkitError extends Error {
+    readonly code: 'usage' | 'validation';
+    readonly name = "DevkitError";
+    constructor(message: string, code?: 'usage' | 'validation');
+}

package/types/lib/local-render.d.cts

@@ -0,0 +1,15 @@
+import { type AssembleVendor, type Diagnostic, type RenderContext, type RenderedDocument } from '@formfeed/engine';
+import type { Project } from './project-config.cjs';
+import { type LocalTemplate } from './project.cjs';
+/** The same diagnostics the editor shows: analysis of the body against the sample data plus compile errors. */
+export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): Diagnostic[];
+export declare function renderContext(project: Project, tpl: LocalTemplate): RenderContext;
+export interface LocalRenderOptions {
+    mode: 'preview' | 'print';
+    locale?: string;
+    vendor?: AssembleVendor;
+}
+/** Assembles the complete document with the shared engine; no browser involved. */
+export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;
+/** Wraps a preview render for the screen the way the editor does. */
+export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

package/types/lib/local-render.d.ts

@@ -0,0 +1,15 @@
+import { type AssembleVendor, type Diagnostic, type RenderContext, type RenderedDocument } from '@formfeed/engine';
+import type { Project } from './project-config.js';
+import { type LocalTemplate } from './project.js';
+/** The same diagnostics the editor shows: analysis of the body against the sample data plus compile errors. */
+export declare function diagnose(tpl: LocalTemplate, sampleData: unknown): Diagnostic[];
+export declare function renderContext(project: Project, tpl: LocalTemplate): RenderContext;
+export interface LocalRenderOptions {
+    mode: 'preview' | 'print';
+    locale?: string;
+    vendor?: AssembleVendor;
+}
+/** Assembles the complete document with the shared engine; no browser involved. */
+export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;
+/** Wraps a preview render for the screen the way the editor does. */
+export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

package/types/lib/project-config.d.cts

@@ -0,0 +1,28 @@
+import type { EngineId } from '@formfeed/engine';
+/** `formfeed.json` of a project (spec 15 §2). */
+export interface ProjectConfig {
+    workspace?: string;
+    region?: 'eu' | 'us';
+    templatesDir: string;
+    partialsDir: string;
+    engine: EngineId;
+    ignore: string[];
+}
+export interface Project {
+    root: string;
+    /** Null for an ad-hoc project built around a template folder without formfeed.json. */
+    configPath: string | null;
+    config: ProjectConfig;
+    templatesDir: string;
+    partialsDir: string;
+}
+export declare const defaultProjectConfig: ProjectConfig;
+/** Walks up from `cwd` to the nearest `formfeed.json`. */
+export declare function findProject(cwd?: string): Project | null;
+export declare function loadProject(configPath: string): Project;
+/**
+ * A project for one template folder when no formfeed.json is around (test helpers): the folder's
+ * parent is the templates dir, `partials` next to it holds the partials.
+ */
+export declare function projectAround(templateFolder: string): Project;
+export declare function writeProjectConfig(root: string, config: Partial<ProjectConfig>): string;

package/types/lib/project-config.d.ts

@@ -0,0 +1,28 @@
+import type { EngineId } from '@formfeed/engine';
+/** `formfeed.json` of a project (spec 15 §2). */
+export interface ProjectConfig {
+    workspace?: string;
+    region?: 'eu' | 'us';
+    templatesDir: string;
+    partialsDir: string;
+    engine: EngineId;
+    ignore: string[];
+}
+export interface Project {
+    root: string;
+    /** Null for an ad-hoc project built around a template folder without formfeed.json. */
+    configPath: string | null;
+    config: ProjectConfig;
+    templatesDir: string;
+    partialsDir: string;
+}
+export declare const defaultProjectConfig: ProjectConfig;
+/** Walks up from `cwd` to the nearest `formfeed.json`. */
+export declare function findProject(cwd?: string): Project | null;
+export declare function loadProject(configPath: string): Project;
+/**
+ * A project for one template folder when no formfeed.json is around (test helpers): the folder's
+ * parent is the templates dir, `partials` next to it holds the partials.
+ */
+export declare function projectAround(templateFolder: string): Project;
+export declare function writeProjectConfig(root: string, config: Partial<ProjectConfig>): string;

package/types/lib/project.d.cts

@@ -0,0 +1,72 @@
+import type { EngineId, TemplateKind, TemplateSettings } from '@formfeed/engine';
+import type { TemplateVersion } from '@formfeed/sdk';
+import type { Project } from './project-config.cjs';
+/**
+ * The template folder of spec 15 §2. `template.json` (name, kind, engine, description, tags) is
+ * the one addition to the spec's layout: `push` needs it to create a template that does not exist
+ * remotely, `pull` writes it. Header and footer live in their own files and fold back into
+ * `settings.header.html` / `settings.footer.html`, as the editor's tabs do.
+ */
+export interface TemplateMeta {
+    name: string;
+    kind: TemplateKind;
+    engine: EngineId;
+    description?: string | null;
+    tags?: string[];
+}
+export interface LocalTemplate {
+    slug: string;
+    dir: string;
+    meta: TemplateMeta;
+    html: string;
+    css: string;
+    head: string;
+    /** Settings with header/footer html folded in. */
+    settings: TemplateSettings;
+    /** `data/<name>.json`, `default` first when present. */
+    dataSets: Record<string, unknown>;
+    dataSchema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+}
+export interface TemplateState {
+    /** Checksum of the remote version the folder was pulled from or pushed as. */
+    checksum: string;
+    number: number;
+    status: string;
+    /** Hash of the local files at that moment; a different hash means local edits. */
+    contentHash: string;
+    syncedAt: string;
+}
+export interface ProjectState {
+    templates: Record<string, TemplateState>;
+}
+export declare function listTemplateSlugs(project: Project): string[];
+export declare function templateDir(project: Project, slug: string): string;
+export declare function readTemplate(project: Project, slug: string): LocalTemplate;
+/** The sample data set the preview and validation use: `default`, else the first file, else `{}`. */
+export declare function defaultData(tpl: LocalTemplate, name?: string): {
+    name: string;
+    data: unknown;
+};
+export declare function writeTemplate(project: Project, slug: string, meta: TemplateMeta, version: Pick<TemplateVersion, 'html' | 'css' | 'head' | 'settings' | 'sample_data' | 'data_schema' | 'i18n'> & {
+    data_sets?: Record<string, unknown> | null;
+}): string;
+/** Files of a push request: what the API's TemplateVersionCreate takes. */
+export declare function versionPayload(tpl: LocalTemplate): {
+    html: string;
+    css: string;
+    head: string;
+    settings: Record<string, unknown>;
+    sample_data: Record<string, unknown>;
+    data_sets: Record<string, unknown>;
+    data_schema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+};
+/** Stable hash of the local files; compared with the state to detect local edits. */
+export declare function contentHash(tpl: LocalTemplate): string;
+export declare function readState(project: Project): ProjectState;
+export declare function writeState(project: Project, state: ProjectState): void;
+export declare function recordSync(project: Project, slug: string, version: Pick<TemplateVersion, 'checksum' | 'number' | 'status'>, tpl: LocalTemplate): void;
+export declare function titleFromSlug(slug: string): string;
+/** Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`). */
+export declare function partialResolver(project: Project): (name: string) => string | undefined;

package/types/lib/project.d.ts

@@ -0,0 +1,72 @@
+import type { EngineId, TemplateKind, TemplateSettings } from '@formfeed/engine';
+import type { TemplateVersion } from '@formfeed/sdk';
+import type { Project } from './project-config.js';
+/**
+ * The template folder of spec 15 §2. `template.json` (name, kind, engine, description, tags) is
+ * the one addition to the spec's layout: `push` needs it to create a template that does not exist
+ * remotely, `pull` writes it. Header and footer live in their own files and fold back into
+ * `settings.header.html` / `settings.footer.html`, as the editor's tabs do.
+ */
+export interface TemplateMeta {
+    name: string;
+    kind: TemplateKind;
+    engine: EngineId;
+    description?: string | null;
+    tags?: string[];
+}
+export interface LocalTemplate {
+    slug: string;
+    dir: string;
+    meta: TemplateMeta;
+    html: string;
+    css: string;
+    head: string;
+    /** Settings with header/footer html folded in. */
+    settings: TemplateSettings;
+    /** `data/<name>.json`, `default` first when present. */
+    dataSets: Record<string, unknown>;
+    dataSchema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+}
+export interface TemplateState {
+    /** Checksum of the remote version the folder was pulled from or pushed as. */
+    checksum: string;
+    number: number;
+    status: string;
+    /** Hash of the local files at that moment; a different hash means local edits. */
+    contentHash: string;
+    syncedAt: string;
+}
+export interface ProjectState {
+    templates: Record<string, TemplateState>;
+}
+export declare function listTemplateSlugs(project: Project): string[];
+export declare function templateDir(project: Project, slug: string): string;
+export declare function readTemplate(project: Project, slug: string): LocalTemplate;
+/** The sample data set the preview and validation use: `default`, else the first file, else `{}`. */
+export declare function defaultData(tpl: LocalTemplate, name?: string): {
+    name: string;
+    data: unknown;
+};
+export declare function writeTemplate(project: Project, slug: string, meta: TemplateMeta, version: Pick<TemplateVersion, 'html' | 'css' | 'head' | 'settings' | 'sample_data' | 'data_schema' | 'i18n'> & {
+    data_sets?: Record<string, unknown> | null;
+}): string;
+/** Files of a push request: what the API's TemplateVersionCreate takes. */
+export declare function versionPayload(tpl: LocalTemplate): {
+    html: string;
+    css: string;
+    head: string;
+    settings: Record<string, unknown>;
+    sample_data: Record<string, unknown>;
+    data_sets: Record<string, unknown>;
+    data_schema: Record<string, unknown> | null;
+    i18n: Record<string, Record<string, string>> | null;
+};
+/** Stable hash of the local files; compared with the state to detect local edits. */
+export declare function contentHash(tpl: LocalTemplate): string;
+export declare function readState(project: Project): ProjectState;
+export declare function writeState(project: Project, state: ProjectState): void;
+export declare function recordSync(project: Project, slug: string, version: Pick<TemplateVersion, 'checksum' | 'number' | 'status'>, tpl: LocalTemplate): void;
+export declare function titleFromSlug(slug: string): string;
+/** Resolves `{% include %}` / partials from the project's partials folder (`name` or `name.html`). */
+export declare function partialResolver(project: Project): (name: string) => string | undefined;