@formfeed/devkit 0.1.0 → 0.2.0

package/index.cjs

@@ -21,13 +21,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   DevkitError: () => DevkitError,
+  collectPartials: () => collectPartials,
   contentHash: () => contentHash,
+  contentTypeFor: () => contentTypeFor,
   defaultData: () => defaultData,
   defaultProjectConfig: () => defaultProjectConfig,
   diagnose: () => diagnose,
   findProject: () => findProject,
+  listLocalFiles: () => listLocalFiles,
   listTemplateSlugs: () => listTemplateSlugs,
   loadProject: () => loadProject,
+  localFilePath: () => localFilePath,
   partialResolver: () => partialResolver,
   previewDocument: () => previewDocument,
   projectAround: () => projectAround,
@@ -36,9 +40,12 @@ __export(index_exports, {
   recordSync: () => recordSync,
   renderContext: () => renderContext,
   renderLocal: () => renderLocal,
+  sha256File: () => sha256File,
   templateDir: () => templateDir,
   titleFromSlug: () => titleFromSlug,
   versionPayload: () => versionPayload,
+  writeLocalFile: () => writeLocalFile,
+  writePartials: () => writePartials,
   writeProjectConfig: () => writeProjectConfig,
   writeState: () => writeState,
   writeTemplate: () => writeTemplate
@@ -60,6 +67,7 @@ var import_node_path = require("node:path");
 var defaultProjectConfig = {
   templatesDir: "templates",
   partialsDir: "partials",
+  filesDir: "files",
   engine: "jinja2",
   ignore: ["**/drafts/**"]
 };
@@ -82,7 +90,14 @@ function loadProject(configPath) {
   }
   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) };
+  return {
+    root,
+    configPath,
+    config,
+    templatesDir: (0, import_node_path.resolve)(root, config.templatesDir),
+    partialsDir: (0, import_node_path.resolve)(root, config.partialsDir),
+    filesDir: (0, import_node_path.resolve)(root, config.filesDir)
+  };
 }
 function projectAround(templateFolder) {
   const dir = (0, import_node_path.resolve)(templateFolder);
@@ -93,9 +108,10 @@ function projectAround(templateFolder) {
   return {
     root,
     configPath: null,
-    config: { ...defaultProjectConfig, templatesDir, partialsDir: (0, import_node_path.join)(root, "partials") },
+    config: { ...defaultProjectConfig, templatesDir, partialsDir: (0, import_node_path.join)(root, "partials"), filesDir: (0, import_node_path.join)(root, "files") },
     templatesDir,
-    partialsDir: (0, import_node_path.join)(root, "partials")
+    partialsDir: (0, import_node_path.join)(root, "partials"),
+    filesDir: (0, import_node_path.join)(root, "files")
   };
 }
 function writeProjectConfig(root, config) {
@@ -109,6 +125,39 @@ function writeProjectConfig(root, config) {
 var import_node_crypto = require("node:crypto");
 var import_node_fs2 = require("node:fs");
 var import_node_path2 = require("node:path");
+
+// packages/devkit/src/lib/partials.ts
+var import_engine = require("@formfeed/engine");
+function includeNames(engine, source) {
+  try {
+    return (0, import_engine.getEngine)(engine).analyze(source).includes.map((include) => include.name);
+  } catch {
+    return [];
+  }
+}
+function collectPartials(project, engine, sources) {
+  const resolve3 = partialResolver(project);
+  const partials = {};
+  const missing = /* @__PURE__ */ new Set();
+  const queue = sources.filter((source) => Boolean(source));
+  const seen = /* @__PURE__ */ new Set();
+  while (queue.length) {
+    for (const name of includeNames(engine, queue.shift())) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const source = resolve3(name);
+      if (source === void 0) {
+        missing.add(name);
+        continue;
+      }
+      partials[name] = source;
+      queue.push(source);
+    }
+  }
+  return { partials, missing: [...missing].sort() };
+}
+
+// packages/devkit/src/lib/project.ts
 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);
@@ -150,6 +199,7 @@ function readTemplate(project, slug) {
       dataSets[(0, import_node_path2.basename)(file, ".json")] = readJson((0, import_node_path2.join)(dataDir, file), `data/${file}`);
     }
   }
+  const { partials, missing } = collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
   return {
     slug,
     dir,
@@ -160,7 +210,9 @@ function readTemplate(project, slug) {
     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")
+    i18n: readJson((0, import_node_path2.join)(dir, "i18n.json"), "i18n.json"),
+    partials,
+    missingPartials: missing
   };
 }
 function defaultData(tpl, name) {
@@ -191,8 +243,22 @@ function writeTemplate(project, slug, meta, version) {
       (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" : "");
+  writePartials(project, version.partials ?? null);
   return dir;
 }
+var partialName = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/;
+function writePartials(project, partials) {
+  const changed = [];
+  for (const [name, source] of Object.entries(partials ?? {})) {
+    if (!partialName.test(name)) continue;
+    const path = (0, import_node_path2.join)(project.partialsDir, name.includes(".") ? name : `${name}.html`);
+    if (readText(path) === source) continue;
+    (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(path), { recursive: true });
+    (0, import_node_fs2.writeFileSync)(path, source);
+    changed.push(path);
+  }
+  return changed;
+}
 function stripHtml(part) {
   const { html: _html, ...rest } = part;
   void _html;
@@ -215,12 +281,16 @@ function versionPayload(tpl) {
     sample_data: sample ?? {},
     data_sets: named,
     data_schema: tpl.dataSchema,
-    i18n: tpl.i18n
+    i18n: tpl.i18n,
+    // 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) {
   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");
+  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);
+  return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(parts)).digest("hex");
 }
 var statePath = (project) => (0, import_node_path2.join)(project.root, ".formfeed", "state.json");
 function readState(project) {
@@ -255,14 +325,14 @@ function partialResolver(project) {
 }
 
 // packages/devkit/src/lib/local-render.ts
-var import_engine = require("@formfeed/engine");
+var import_engine2 = require("@formfeed/engine");
 function diagnose(tpl, sampleData) {
-  const engine = (0, import_engine.getEngine)(tpl.meta.engine);
+  const engine = (0, import_engine2.getEngine)(tpl.meta.engine);
   const diagnostics = [];
   try {
     engine.compile(tpl.html, { name: tpl.slug });
   } catch (e) {
-    if (e instanceof import_engine.EngineSyntaxError) {
+    if (e instanceof import_engine2.EngineSyntaxError) {
       diagnostics.push({
         severity: "error",
         code: "syntax-error",
@@ -279,25 +349,33 @@ function diagnose(tpl, sampleData) {
     if (!source) continue;
     for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
   }
+  for (const name of tpl.missingPartials)
+    diagnostics.push({
+      severity: "error",
+      code: "missing-partial",
+      message: `No partial "${name}" in the project's partials folder`,
+      range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }
+    });
   return diagnostics;
 }
-function renderContext(project, tpl) {
-  const settings = (0, import_engine.mergeSettings)(tpl.settings);
+function renderContext(project, tpl, assetBaseUrl) {
+  const settings = (0, import_engine2.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
+    helpers: (0, import_engine2.defaultHelpers)(),
+    limits: import_engine2.defaultLimits,
+    i18n: tpl.i18n ?? void 0,
+    assetBaseUrl
   };
 }
 async function renderLocal(project, tpl, data, options) {
-  const ctx = renderContext(project, tpl);
+  const ctx = renderContext(project, tpl, options.assetBaseUrl);
   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 },
+  return (0, import_engine2.renderVersion)(
+    { engine: tpl.meta.engine, html: tpl.html, css: tpl.css, head: tpl.head, settings: (0, import_engine2.mergeSettings)(tpl.settings), kind: tpl.meta.kind },
     data,
     ctx,
     options.mode,
@@ -312,18 +390,96 @@ function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
     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);
+  return mode === "paged" && tpl.meta.kind === "pdf" ? (0, import_engine2.pagedDocument)(draft, { pagedScriptUrl }) : (0, import_engine2.flowDocument)(draft);
+}
+
+// packages/devkit/src/lib/files.ts
+var import_node_crypto2 = require("node:crypto");
+var import_node_fs3 = require("node:fs");
+var import_node_path3 = require("node:path");
+
+// packages/api-types/src/lib/assets.ts
+var SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
+var ASSET_NAME_PATTERN = new RegExp(`^${SEGMENT}(?:/${SEGMENT})*$`);
+var ASSET_MAX_BYTES = 10 * 1024 * 1024;
+var ASSET_CONTENT_TYPES = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/svg+xml": "svg",
+  "image/avif": "avif",
+  "application/pdf": "pdf"
+};
+function isAssetName(name) {
+  return name.length > 0 && name.length <= 200 && ASSET_NAME_PATTERN.test(name) && !name.split("/").includes("..");
+}
+
+// packages/devkit/src/lib/files.ts
+var byExtension = Object.fromEntries(
+  Object.entries(ASSET_CONTENT_TYPES).map(([type, ext]) => [ext, type])
+);
+byExtension["jpeg"] = "image/jpeg";
+function contentTypeFor(name) {
+  return byExtension[name.split(".").pop()?.toLowerCase() ?? ""] ?? null;
+}
+function sha256File(bytes) {
+  return (0, import_node_crypto2.createHash)("sha256").update(bytes).digest("hex");
+}
+function listLocalFiles(project) {
+  const listing = { files: [], skipped: [] };
+  if (!(0, import_node_fs3.existsSync)(project.filesDir)) return listing;
+  const walk = (dir) => {
+    for (const entry of (0, import_node_fs3.readdirSync)(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const path = (0, import_node_path3.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const name = (0, import_node_path3.relative)(project.filesDir, path).split(import_node_path3.sep).join("/");
+      const size = (0, import_node_fs3.statSync)(path).size;
+      const contentType = contentTypeFor(name);
+      const reason = !isAssetName(name) ? "the name has characters a library name cannot have (letters, digits, dot, dash, underscore)" : !contentType ? "not an image or a PDF" : size === 0 ? "empty" : size > ASSET_MAX_BYTES ? `larger than ${ASSET_MAX_BYTES / 1024 / 1024} MB` : null;
+      if (reason) {
+        listing.skipped.push({ path, reason });
+        continue;
+      }
+      const bytes = (0, import_node_fs3.readFileSync)(path);
+      listing.files.push({ name, path, bytes: size, sha256: sha256File(bytes), contentType });
+    }
+  };
+  walk(project.filesDir);
+  listing.files.sort((a, b) => a.name.localeCompare(b.name));
+  return listing;
+}
+function localFilePath(project, name) {
+  if (!isAssetName(name)) throw new DevkitError(`"${name}" is not a library file name`);
+  const path = (0, import_node_path3.resolve)(project.filesDir, ...name.split("/"));
+  if (!path.startsWith((0, import_node_path3.resolve)(project.filesDir) + import_node_path3.sep)) throw new DevkitError(`"${name}" is not inside the files folder`);
+  return path;
+}
+function writeLocalFile(project, name, bytes) {
+  const path = localFilePath(project, name);
+  (0, import_node_fs3.mkdirSync)((0, import_node_path3.dirname)(path), { recursive: true });
+  (0, import_node_fs3.writeFileSync)(path, bytes);
+  return path;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DevkitError,
+  collectPartials,
   contentHash,
+  contentTypeFor,
   defaultData,
   defaultProjectConfig,
   diagnose,
   findProject,
+  listLocalFiles,
   listTemplateSlugs,
   loadProject,
+  localFilePath,
   partialResolver,
   previewDocument,
   projectAround,
@@ -332,9 +488,12 @@ function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
   recordSync,
   renderContext,
   renderLocal,
+  sha256File,
   templateDir,
   titleFromSlug,
   versionPayload,
+  writeLocalFile,
+  writePartials,
   writeProjectConfig,
   writeState,
   writeTemplate

package/index.js

@@ -13,6 +13,7 @@ import { dirname, join, resolve } from "node:path";
 var defaultProjectConfig = {
   templatesDir: "templates",
   partialsDir: "partials",
+  filesDir: "files",
   engine: "jinja2",
   ignore: ["**/drafts/**"]
 };
@@ -35,7 +36,14 @@ function loadProject(configPath) {
   }
   const config = { ...defaultProjectConfig, ...raw };
   const root = dirname(configPath);
-  return { root, configPath, config, templatesDir: resolve(root, config.templatesDir), partialsDir: resolve(root, config.partialsDir) };
+  return {
+    root,
+    configPath,
+    config,
+    templatesDir: resolve(root, config.templatesDir),
+    partialsDir: resolve(root, config.partialsDir),
+    filesDir: resolve(root, config.filesDir)
+  };
 }
 function projectAround(templateFolder) {
   const dir = resolve(templateFolder);
@@ -46,9 +54,10 @@ function projectAround(templateFolder) {
   return {
     root,
     configPath: null,
-    config: { ...defaultProjectConfig, templatesDir, partialsDir: join(root, "partials") },
+    config: { ...defaultProjectConfig, templatesDir, partialsDir: join(root, "partials"), filesDir: join(root, "files") },
     templatesDir,
-    partialsDir: join(root, "partials")
+    partialsDir: join(root, "partials"),
+    filesDir: join(root, "files")
   };
 }
 function writeProjectConfig(root, config) {
@@ -61,7 +70,40 @@ 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, join as join2 } from "node:path";
+import { basename, dirname as dirname2, join as join2 } from "node:path";
+
+// packages/devkit/src/lib/partials.ts
+import { getEngine } from "@formfeed/engine";
+function includeNames(engine, source) {
+  try {
+    return getEngine(engine).analyze(source).includes.map((include) => include.name);
+  } catch {
+    return [];
+  }
+}
+function collectPartials(project, engine, sources) {
+  const resolve3 = partialResolver(project);
+  const partials = {};
+  const missing = /* @__PURE__ */ new Set();
+  const queue = sources.filter((source) => Boolean(source));
+  const seen = /* @__PURE__ */ new Set();
+  while (queue.length) {
+    for (const name of includeNames(engine, queue.shift())) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const source = resolve3(name);
+      if (source === void 0) {
+        missing.add(name);
+        continue;
+      }
+      partials[name] = source;
+      queue.push(source);
+    }
+  }
+  return { partials, missing: [...missing].sort() };
+}
+
+// packages/devkit/src/lib/project.ts
 var readText = (path) => existsSync2(path) ? readFileSync2(path, "utf8") : null;
 function readJson(path, what) {
   const text = readText(path);
@@ -103,6 +145,7 @@ function readTemplate(project, slug) {
       dataSets[basename(file, ".json")] = readJson(join2(dataDir, file), `data/${file}`);
     }
   }
+  const { partials, missing } = collectPartials(project, meta.engine, [html, settings.header?.html, settings.footer?.html]);
   return {
     slug,
     dir,
@@ -113,7 +156,9 @@ function readTemplate(project, slug) {
     settings,
     dataSets,
     dataSchema: readJson(join2(dir, "schema.json"), "schema.json"),
-    i18n: readJson(join2(dir, "i18n.json"), "i18n.json")
+    i18n: readJson(join2(dir, "i18n.json"), "i18n.json"),
+    partials,
+    missingPartials: missing
   };
 }
 function defaultData(tpl, name) {
@@ -144,8 +189,22 @@ function writeTemplate(project, slug, meta, version) {
       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" : "");
+  writePartials(project, version.partials ?? null);
   return dir;
 }
+var partialName = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/;
+function writePartials(project, partials) {
+  const changed = [];
+  for (const [name, source] of Object.entries(partials ?? {})) {
+    if (!partialName.test(name)) continue;
+    const path = join2(project.partialsDir, name.includes(".") ? name : `${name}.html`);
+    if (readText(path) === source) continue;
+    mkdirSync(dirname2(path), { recursive: true });
+    writeFileSync2(path, source);
+    changed.push(path);
+  }
+  return changed;
+}
 function stripHtml(part) {
   const { html: _html, ...rest } = part;
   void _html;
@@ -168,12 +227,16 @@ function versionPayload(tpl) {
     sample_data: sample ?? {},
     data_sets: named,
     data_schema: tpl.dataSchema,
-    i18n: tpl.i18n
+    i18n: tpl.i18n,
+    // 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) {
   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");
+  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);
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
 }
 var statePath = (project) => join2(project.root, ".formfeed", "state.json");
 function readState(project) {
@@ -213,13 +276,13 @@ import {
   defaultHelpers,
   defaultLimits,
   flowDocument,
-  getEngine,
+  getEngine as getEngine2,
   mergeSettings,
   pagedDocument,
   renderVersion
 } from "@formfeed/engine";
 function diagnose(tpl, sampleData) {
-  const engine = getEngine(tpl.meta.engine);
+  const engine = getEngine2(tpl.meta.engine);
   const diagnostics = [];
   try {
     engine.compile(tpl.html, { name: tpl.slug });
@@ -241,9 +304,16 @@ function diagnose(tpl, sampleData) {
     if (!source) continue;
     for (const d of engine.analyze(source, { sampleData }).diagnostics) diagnostics.push({ ...d, message: `${part}: ${d.message}` });
   }
+  for (const name of tpl.missingPartials)
+    diagnostics.push({
+      severity: "error",
+      code: "missing-partial",
+      message: `No partial "${name}" in the project's partials folder`,
+      range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } }
+    });
   return diagnostics;
 }
-function renderContext(project, tpl) {
+function renderContext(project, tpl, assetBaseUrl) {
   const settings = mergeSettings(tpl.settings);
   return {
     locale: settings.locale ?? "en",
@@ -252,11 +322,12 @@ function renderContext(project, tpl) {
     partials: partialResolver(project),
     helpers: defaultHelpers(),
     limits: defaultLimits,
-    i18n: tpl.i18n ?? void 0
+    i18n: tpl.i18n ?? void 0,
+    assetBaseUrl
   };
 }
 async function renderLocal(project, tpl, data, options) {
-  const ctx = renderContext(project, tpl);
+  const ctx = renderContext(project, tpl, options.assetBaseUrl);
   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 },
@@ -276,15 +347,93 @@ function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
   };
   return mode === "paged" && tpl.meta.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";
+
+// packages/api-types/src/lib/assets.ts
+var SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
+var ASSET_NAME_PATTERN = new RegExp(`^${SEGMENT}(?:/${SEGMENT})*$`);
+var ASSET_MAX_BYTES = 10 * 1024 * 1024;
+var ASSET_CONTENT_TYPES = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/svg+xml": "svg",
+  "image/avif": "avif",
+  "application/pdf": "pdf"
+};
+function isAssetName(name) {
+  return name.length > 0 && name.length <= 200 && ASSET_NAME_PATTERN.test(name) && !name.split("/").includes("..");
+}
+
+// packages/devkit/src/lib/files.ts
+var byExtension = Object.fromEntries(
+  Object.entries(ASSET_CONTENT_TYPES).map(([type, ext]) => [ext, type])
+);
+byExtension["jpeg"] = "image/jpeg";
+function contentTypeFor(name) {
+  return byExtension[name.split(".").pop()?.toLowerCase() ?? ""] ?? null;
+}
+function sha256File(bytes) {
+  return createHash2("sha256").update(bytes).digest("hex");
+}
+function listLocalFiles(project) {
+  const listing = { files: [], skipped: [] };
+  if (!existsSync3(project.filesDir)) return listing;
+  const walk = (dir) => {
+    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const path = join3(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const name = relative(project.filesDir, path).split(sep).join("/");
+      const size = statSync2(path).size;
+      const contentType = contentTypeFor(name);
+      const reason = !isAssetName(name) ? "the name has characters a library name cannot have (letters, digits, dot, dash, underscore)" : !contentType ? "not an image or a PDF" : size === 0 ? "empty" : size > ASSET_MAX_BYTES ? `larger than ${ASSET_MAX_BYTES / 1024 / 1024} MB` : null;
+      if (reason) {
+        listing.skipped.push({ path, reason });
+        continue;
+      }
+      const bytes = readFileSync3(path);
+      listing.files.push({ name, path, bytes: size, sha256: sha256File(bytes), contentType });
+    }
+  };
+  walk(project.filesDir);
+  listing.files.sort((a, b) => a.name.localeCompare(b.name));
+  return listing;
+}
+function localFilePath(project, name) {
+  if (!isAssetName(name)) throw new DevkitError(`"${name}" is not a library file name`);
+  const path = resolve2(project.filesDir, ...name.split("/"));
+  if (!path.startsWith(resolve2(project.filesDir) + sep)) throw new DevkitError(`"${name}" is not inside the files folder`);
+  return path;
+}
+function writeLocalFile(project, name, bytes) {
+  const path = localFilePath(project, name);
+  mkdirSync2(dirname3(path), { recursive: true });
+  writeFileSync3(path, bytes);
+  return path;
+}
 export {
   DevkitError,
+  collectPartials,
   contentHash,
+  contentTypeFor,
   defaultData,
   defaultProjectConfig,
   diagnose,
   findProject,
+  listLocalFiles,
   listTemplateSlugs,
   loadProject,
+  localFilePath,
   partialResolver,
   previewDocument,
   projectAround,
@@ -293,9 +442,12 @@ export {
   recordSync,
   renderContext,
   renderLocal,
+  sha256File,
   templateDir,
   titleFromSlug,
   versionPayload,
+  writeLocalFile,
+  writePartials,
   writeProjectConfig,
   writeState,
   writeTemplate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/devkit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Formfeed template folders, project config and local rendering, shared by the CLI and @formfeed/testing.",
   "license": "MIT",
   "type": "module",
@@ -30,8 +30,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@formfeed/engine": "0.1.0",
-    "@formfeed/sdk": "0.1.0"
+    "@formfeed/engine": "0.2.0",
+    "@formfeed/sdk": "0.2.0"
   },
   "keywords": [
     "formfeed",

package/types/index.d.cts

@@ -1,7 +1,11 @@
 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 { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.cjs';
 export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.cjs';
+export { collectPartials } from './lib/partials.cjs';
+export type { CollectedPartials } from './lib/partials.cjs';
 export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.cjs';
+export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.cjs';
+export type { LocalFile, LocalFileListing } from './lib/files.cjs';
 export type { LocalRenderOptions } from './lib/local-render.cjs';

package/types/index.d.ts

@@ -1,7 +1,11 @@
 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 { contentHash, defaultData, listTemplateSlugs, partialResolver, readState, readTemplate, recordSync, templateDir, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.js';
 export type { LocalTemplate, ProjectState, TemplateMeta, TemplateState } from './lib/project.js';
+export { collectPartials } from './lib/partials.js';
+export type { CollectedPartials } from './lib/partials.js';
 export { diagnose, previewDocument, renderContext, renderLocal } from './lib/local-render.js';
+export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.js';
+export type { LocalFile, LocalFileListing } from './lib/files.js';
 export type { LocalRenderOptions } from './lib/local-render.js';

package/types/lib/files.d.cts

@@ -0,0 +1,32 @@
+import type { Project } from './project-config.cjs';
+/**
+ * The project's `files/` folder: the local copy of the workspace file library (spec 04 §2.3). A
+ * file's path below the folder is its library name, so `files/brand/logo.png` is what a template
+ * reaches with `asset('brand/logo.png')`, locally in `formfeed dev` and remotely after `files push`.
+ */
+export interface LocalFile {
+    /** The library name: the path below the files folder, with `/`. */
+    name: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** From the extension; null for a type the library does not take. */
+    contentType: string | null;
+}
+export interface LocalFileListing {
+    files: LocalFile[];
+    /** Paths the library would refuse: an unusable name, an unknown type, too large or empty. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/** The content type the library stores for a name, going by its extension. */
+export declare function contentTypeFor(name: string): string | null;
+export declare function sha256File(bytes: Uint8Array): string;
+/** Every file below the files folder, with the ones the library would refuse listed apart. */
+export declare function listLocalFiles(project: Project): LocalFileListing;
+/** The path of a library name inside the files folder; refuses a name that would leave it. */
+export declare function localFilePath(project: Project, name: string): string;
+/** Writes a pulled file below the files folder, creating folders for names like `brand/logo.png`. */
+export declare function writeLocalFile(project: Project, name: string, bytes: Uint8Array): string;

package/types/lib/files.d.ts

@@ -0,0 +1,32 @@
+import type { Project } from './project-config.js';
+/**
+ * The project's `files/` folder: the local copy of the workspace file library (spec 04 §2.3). A
+ * file's path below the folder is its library name, so `files/brand/logo.png` is what a template
+ * reaches with `asset('brand/logo.png')`, locally in `formfeed dev` and remotely after `files push`.
+ */
+export interface LocalFile {
+    /** The library name: the path below the files folder, with `/`. */
+    name: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** From the extension; null for a type the library does not take. */
+    contentType: string | null;
+}
+export interface LocalFileListing {
+    files: LocalFile[];
+    /** Paths the library would refuse: an unusable name, an unknown type, too large or empty. */
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/** The content type the library stores for a name, going by its extension. */
+export declare function contentTypeFor(name: string): string | null;
+export declare function sha256File(bytes: Uint8Array): string;
+/** Every file below the files folder, with the ones the library would refuse listed apart. */
+export declare function listLocalFiles(project: Project): LocalFileListing;
+/** The path of a library name inside the files folder; refuses a name that would leave it. */
+export declare function localFilePath(project: Project, name: string): string;
+/** Writes a pulled file below the files folder, creating folders for names like `brand/logo.png`. */
+export declare function writeLocalFile(project: Project, name: string, bytes: Uint8Array): string;

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

@@ -3,11 +3,18 @@ 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;
+/**
+ * `assetBaseUrl` is where `asset()` and relative image paths resolve: the dev server's `/files`
+ * locally, the workspace library's CDN base when the document goes to the API. Without it the
+ * references stay relative, which keeps snapshots independent of any host.
+ */
+export declare function renderContext(project: Project, tpl: LocalTemplate, assetBaseUrl?: string): RenderContext;
 export interface LocalRenderOptions {
     mode: 'preview' | 'print';
     locale?: string;
     vendor?: AssembleVendor;
+    /** Where `asset()` and relative image paths resolve (see `renderContext`). */
+    assetBaseUrl?: string;
 }
 /** 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>;

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

@@ -3,11 +3,18 @@ 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;
+/**
+ * `assetBaseUrl` is where `asset()` and relative image paths resolve: the dev server's `/files`
+ * locally, the workspace library's CDN base when the document goes to the API. Without it the
+ * references stay relative, which keeps snapshots independent of any host.
+ */
+export declare function renderContext(project: Project, tpl: LocalTemplate, assetBaseUrl?: string): RenderContext;
 export interface LocalRenderOptions {
     mode: 'preview' | 'print';
     locale?: string;
     vendor?: AssembleVendor;
+    /** Where `asset()` and relative image paths resolve (see `renderContext`). */
+    assetBaseUrl?: string;
 }
 /** 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>;

package/types/lib/partials.d.cts

@@ -0,0 +1,17 @@
+import { type EngineId } from '@formfeed/engine';
+import type { Project } from './project-config.cjs';
+/**
+ * The partials a template includes, read from the project's `partials/` folder. They travel with
+ * the version (`formfeed templates push`), so a published template resolves `{% include %}` in the
+ * API and the editor, not only in the CLI.
+ *
+ * Includes nest, so every partial is analysed in turn; a name that has no file is reported instead
+ * of failing, and `validate` and `push` show it.
+ */
+export interface CollectedPartials {
+    /** name → source, the shape the API stores. */
+    partials: Record<string, string>;
+    /** Names no file in the partials folder matches. */
+    missing: string[];
+}
+export declare function collectPartials(project: Project, engine: EngineId, sources: Array<string | undefined>): CollectedPartials;

package/types/lib/partials.d.ts

@@ -0,0 +1,17 @@
+import { type EngineId } from '@formfeed/engine';
+import type { Project } from './project-config.js';
+/**
+ * The partials a template includes, read from the project's `partials/` folder. They travel with
+ * the version (`formfeed templates push`), so a published template resolves `{% include %}` in the
+ * API and the editor, not only in the CLI.
+ *
+ * Includes nest, so every partial is analysed in turn; a name that has no file is reported instead
+ * of failing, and `validate` and `push` show it.
+ */
+export interface CollectedPartials {
+    /** name → source, the shape the API stores. */
+    partials: Record<string, string>;
+    /** Names no file in the partials folder matches. */
+    missing: string[];
+}
+export declare function collectPartials(project: Project, engine: EngineId, sources: Array<string | undefined>): CollectedPartials;

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

@@ -5,6 +5,8 @@ export interface ProjectConfig {
     region?: 'eu' | 'us';
     templatesDir: string;
     partialsDir: string;
+    /** The local copy of the workspace file library (`formfeed files push|pull`). */
+    filesDir: string;
     engine: EngineId;
     ignore: string[];
 }
@@ -15,6 +17,7 @@ export interface Project {
     config: ProjectConfig;
     templatesDir: string;
     partialsDir: string;
+    filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */

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

@@ -5,6 +5,8 @@ export interface ProjectConfig {
     region?: 'eu' | 'us';
     templatesDir: string;
     partialsDir: string;
+    /** The local copy of the workspace file library (`formfeed files push|pull`). */
+    filesDir: string;
     engine: EngineId;
     ignore: string[];
 }
@@ -15,6 +17,7 @@ export interface Project {
     config: ProjectConfig;
     templatesDir: string;
     partialsDir: string;
+    filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */

package/types/lib/project.d.cts

@@ -27,6 +27,10 @@ export interface LocalTemplate {
     dataSets: Record<string, unknown>;
     dataSchema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    /** Partials the template includes, read from the project's folder; they travel with the version. */
+    partials: Record<string, string>;
+    /** Included names without a file; `validate` reports them and `push` refuses them. */
+    missingPartials: string[];
 }
 export interface TemplateState {
     /** Checksum of the remote version the folder was pulled from or pushed as. */
@@ -50,9 +54,17 @@ export declare function defaultData(tpl: LocalTemplate, name?: string): {
 };
 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;
+    partials?: Record<string, string> | null;
 }): string;
+/**
+ * Writes the partials of a pulled version into the project's folder (`name` or `name.html`, the
+ * two spellings `partialResolver` reads). Returns the files whose content changed, so `pull` can
+ * say that a partial shared with another template was replaced.
+ */
+export declare function writePartials(project: Project, partials: Record<string, string> | null): string[];
 /** Files of a push request: what the API's TemplateVersionCreate takes. */
 export declare function versionPayload(tpl: LocalTemplate): {
+    partials?: Record<string, string> | undefined;
     html: string;
     css: string;
     head: string;

package/types/lib/project.d.ts

@@ -27,6 +27,10 @@ export interface LocalTemplate {
     dataSets: Record<string, unknown>;
     dataSchema: Record<string, unknown> | null;
     i18n: Record<string, Record<string, string>> | null;
+    /** Partials the template includes, read from the project's folder; they travel with the version. */
+    partials: Record<string, string>;
+    /** Included names without a file; `validate` reports them and `push` refuses them. */
+    missingPartials: string[];
 }
 export interface TemplateState {
     /** Checksum of the remote version the folder was pulled from or pushed as. */
@@ -50,9 +54,17 @@ export declare function defaultData(tpl: LocalTemplate, name?: string): {
 };
 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;
+    partials?: Record<string, string> | null;
 }): string;
+/**
+ * Writes the partials of a pulled version into the project's folder (`name` or `name.html`, the
+ * two spellings `partialResolver` reads). Returns the files whose content changed, so `pull` can
+ * say that a partial shared with another template was replaced.
+ */
+export declare function writePartials(project: Project, partials: Record<string, string> | null): string[];
 /** Files of a push request: what the API's TemplateVersionCreate takes. */
 export declare function versionPayload(tpl: LocalTemplate): {
+    partials?: Record<string, string> | undefined;
     html: string;
     css: string;
     head: string;