@jtakeit/kit 0.8.0 → 0.10.0

package/README.md

@@ -131,10 +131,36 @@ import { writeMeta } from '@jtakeit/kit/meta';
 await writeMeta('dist', {
   collections, blocks, locales,      // the declaration: the specimens are derived from it
   immutable: ['/_next/static/'],     // where this generator keeps its hashed files; absent, the edge assumes Astro's
+  cache: [{ prefix: '/clips/', maxAge: 86400 }], // files that keep their names, kept a day; see below
   redirects: [{ from: '/old', to: '/new', status: 301 }],
 });
 ```
 
+### A file a script picks by name
+
+A film or a photograph a script addresses has no attribute pointing at it, so
+the generator does not hash it and it lives in `public/`, which the edge
+serves for a minute. `keepByName` gives it a name that carries its bytes,
+after the build and before `writeMeta`:
+
+```js
+import { keepByName } from '@jtakeit/kit/kept';
+
+const { kept, unreferenced } = keepByName('dist', { dirs: ['clips', 'scenes'] });
+// /clips/einsatz.mp4 → /_astro/kept/clips/einsatz.3f9a1c2b.mp4, kept for a year
+```
+
+Every address the build wrote whole — in a script, `src`, `data-src`,
+`url(…)` — is pointed at the copy; the originals stay, and `unreferenced`
+names the ones a script assembles and that therefore still go by name.
+
+Or keep the names and declare how long: `cache: [{ prefix: '/clips/', maxAge:
+86400 }]` beside `immutable`. The platform then holds every such name to its
+contents for that long once the site has an address — other bytes under it are
+refused, `JTK_E_CACHED_FILE_CHANGED`, and lowering `maxAge` frees nothing
+sooner. A day for names that may be reused; a year only for names that carry
+their version.
+
 The **specimen pages** are the one thing in that list a site has to build as
 well as declare: one page per block a post may hold, at
 `<collection prefix>/_fl-<type>[-<view>]/` and per extra language — the panel

package/lib/devdiary.mjs

@@ -0,0 +1,199 @@
+/**
+ * The diary on the dev server — so a booking form can be walked on localhost.
+ *
+ * On the platform `/api/availability`, `/api/book` and the rest are the edge's;
+ * on `astro dev` there was nothing there, and every booking form on localhost
+ * said nothing at all: no times, no button that did anything (Schorem, 15
+ * October 2026). A developer judging a page by walking it could not walk the
+ * one thing the page is for.
+ *
+ * This answers the same requests, in the same shape, from the site's own files:
+ * the hours, the zone and the slot length in `jtk/bookings.json`, the services
+ * and the people in `jtk/content` (the collections `jtk/catalogue.json` names
+ * for the bookings module). A booking is kept in memory until the server
+ * stops — so the time it took is taken — and nothing ever leaves the machine.
+ * It is not the platform's diary: no buffers between visits, no resource's own
+ * hours, no rates by the hour of the week. Close enough to walk; `preflight`
+ * with `try_booking` is still the test of the real one.
+ *
+ *   import { devDiary } from '@jtakeit/kit/devdiary';
+ *   server.middlewares.use('/api', devDiary(process.cwd()));
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+
+async function json(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Every content file under jtk/content, with its slug. */
+async function entries(root) {
+  const out = [];
+  const walk = async (dir) => {
+    let names = [];
+    try {
+      names = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const one of names) {
+      const full = join(dir, one.name);
+      if (one.isDirectory()) await walk(full);
+      else if (one.name.endsWith('.json')) {
+        const doc = await json(full);
+        if (doc?.collection) out.push({ ...doc, slug: String(doc.path ?? one.name).split('/').filter(Boolean).pop()?.replace(/\.json$/, '') });
+      }
+    }
+  };
+  await walk(join(root, 'jtk', 'content'));
+  return out;
+}
+
+/** Minutes a zone is ahead of UTC on a given day, from the platform's own Intl. */
+function offsetOf(zone, at) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone: zone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' }).formatToParts(at);
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    const local = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour'), get('minute'));
+    return Math.round((local - at.getTime()) / 60000);
+  } catch {
+    return 0;
+  }
+}
+
+/** What the site's files say, read fresh on every request so an edit shows at once. */
+async function read(root) {
+  const catalogue = (await json(join(root, 'jtk', 'catalogue.json'))) ?? {};
+  const roles = catalogue.modules?.bookings ?? {};
+  const settings = (await json(join(root, 'jtk', 'bookings.json')))?.blocks?.[0] ?? {};
+  const all = await entries(root);
+  const servicesOf = all.filter((e) => e.collection === (roles.services ?? 'services'));
+  const peopleOf = all.filter((e) => e.collection === (roles.resources ?? 'masters'));
+  const services = servicesOf.map((e) => {
+    const b = e.blocks?.[0] ?? {};
+    return { slug: e.slug, takes: Number(b.takes) || 0, costs: Number(b.costs) || 0, title: b.title ?? e.slug };
+  });
+  const people = peopleOf.map((e) => ({ slug: e.slug, does: e.blocks?.[0]?.does ?? null }));
+  return { settings, services, people };
+}
+
+const send = (res, status, body) => {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  res.setHeader('Cache-Control', 'no-store');
+  res.setHeader('X-Jtk-Dev-Diary', '1');
+  res.end(JSON.stringify(body));
+};
+
+const bodyOf = (req) =>
+  new Promise((done) => {
+    let raw = '';
+    req.on('data', (chunk) => (raw += chunk));
+    req.on('end', () => {
+      try {
+        done(JSON.parse(raw || '{}'));
+      } catch {
+        done({});
+      }
+    });
+  });
+
+/** @param {string} root the site's directory */
+export function devDiary(root) {
+  /** start ISO → slugs of the people taken then */
+  const taken = new Map();
+  let made = 0;
+
+  return async (req, res, next) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname.replace(/^\/api/, '') || '/';
+
+    if (path === '/turnstile') return send(res, 200, { sitekey: '' });
+
+    if (path === '/lead' && req.method === 'POST') {
+      const body = await bodyOf(req);
+      console.log(`[dev diary] an enquiry, kept on this machine: ${JSON.stringify(body).slice(0, 200)}`);
+      return send(res, 200, { ok: true, dev: true });
+    }
+
+    if (path === '/availability') {
+      const { settings, services, people } = await read(root);
+      if (!settings.zone || !Array.isArray(settings.hours) || settings.hours.length === 0) {
+        return send(res, 412, {
+          code: 'failed_precondition',
+          message: !settings.zone ? 'nobody has said which timezone this business keeps' : 'nobody has said when this business is open',
+          details: { code: 'JTK_E_DIARY_NOT_READY', means: 'jtk/bookings.json needs `zone` and `hours`.' },
+        });
+      }
+      const asked = (url.searchParams.get('service') ?? '').split(',').concat(url.searchParams.getAll('services')).filter(Boolean);
+      const chosen = services.filter((s) => asked.includes(s.slug));
+      const takes = chosen.reduce((sum, s) => sum + s.takes, 0) || Number(settings.slot_every) || 30;
+      const costs = chosen.reduce((sum, s) => sum + s.costs, 0);
+      const every = Number(settings.slot_every) || 15;
+      const lead = Number(settings.lead) || 0;
+      const zone = settings.zone;
+      const from = new Date(url.searchParams.get('from') ?? Date.now());
+      const to = new Date(url.searchParams.get('to') ?? Date.now() + 86400000);
+      const resource = url.searchParams.get('resource') ?? '';
+      const able = people.filter((p) => (!resource || p.slug === resource) && (!p.does || chosen.every((s) => p.does.includes(s.slug))));
+      const earliest = Date.now() + lead * 60000;
+      const slots = [];
+      // Walk the days in the business's own zone, from its local midnight.
+      for (let day = new Date(from.getTime()); day < to; day = new Date(day.getTime() + 86400000)) {
+        const offset = offsetOf(zone, day);
+        const local = new Date(day.getTime() + offset * 60000);
+        const midnightUtc = Date.UTC(local.getUTCFullYear(), local.getUTCMonth(), local.getUTCDate()) - offset * 60000;
+        const weekday = DAYS[new Date(Date.UTC(local.getUTCFullYear(), local.getUTCMonth(), local.getUTCDate())).getUTCDay()];
+        for (const span of settings.hours.filter((h) => h.day === weekday)) {
+          for (let m = Number(span.opens); m + takes <= Number(span.closes); m += every) {
+            const start = midnightUtc + m * 60000;
+            if (start < earliest || start < from.getTime() || start >= to.getTime()) continue;
+            const iso = new Date(start).toISOString();
+            const busy = taken.get(iso) ?? [];
+            const free = (able.length ? able : [{ slug: '' }]).map((p) => p.slug).filter((s) => !busy.includes(s));
+            slots.push({ start: iso, ends: new Date(start + takes * 60000).toISOString(), free: free.filter(Boolean), costs_minor: costs });
+          }
+        }
+      }
+      return send(res, 200, {
+        zone,
+        slots: slots.filter((s) => s.free.length > 0 || people.length === 0),
+        party_max: 0,
+        quantity_max: 1,
+        scale: settings.scale ?? 'hourly',
+        currency: settings.currency ?? '',
+        services: services.map((s) => ({ slug: s.slug, scale: settings.scale ?? 'hourly', takes: s.takes, fewest: 1, most: 1 })),
+        dev: true,
+      });
+    }
+
+    if (path === '/book' && req.method === 'POST') {
+      const body = await bodyOf(req);
+      const { people, services, settings } = await read(root);
+      const start = body.start ? new Date(body.start).toISOString() : '';
+      if (!start) return send(res, 400, { code: 'invalid_argument', message: 'a booking needs a start' });
+      const busy = taken.get(start) ?? [];
+      const who = body.resource || people.map((p) => p.slug).find((s) => !busy.includes(s)) || '';
+      taken.set(start, [...busy, who]);
+      made += 1;
+      console.log(`[dev diary] booked ${body.service ?? (body.services ?? []).join('+')} at ${start}${who ? ` with ${who}` : ''} for ${body.name ?? 'somebody'} — on this machine only, nothing reached the platform`);
+      // The answer the form draws its last screen from: when, until when, with
+      // whom — without `start` and `ends` it cannot say the time, and says
+      // the booking failed instead.
+      const names = [body.service, ...(Array.isArray(body.services) ? body.services : [])].filter(Boolean);
+      const takes = services.filter((s) => names.includes(s.slug)).reduce((sum, s) => sum + s.takes, 0) || Number(settings.slot_every) || 30;
+      const ends = new Date(new Date(start).getTime() + takes * 60000).toISOString();
+      return send(res, 200, { id: `dev-${made}`, state: 'confirmed', start, ends, amount_minor: 0, currency: settings.currency ?? '', token: `dev-${made}`, manage_path: '', telegram_url: '', resource: who, dev: true });
+    }
+
+    if (path === '/booking/cancel' && req.method === 'POST') return send(res, 200, { ok: true, dev: true });
+
+    return next();
+  };
+}

package/lib/kept.mjs

@@ -0,0 +1,121 @@
+/**
+ * Files a script addresses by name, given a name that carries their contents.
+ *
+ * ── why ─────────────────────────────────────────────────────────────────────
+ *
+ * The generator hashes what the HTML refers to — a stylesheet, an `<img>` —
+ * and puts it under `/_astro/`, which the edge keeps in browsers for a year.
+ * A film or a photograph a script picks by name is not referred to by any
+ * attribute, so it has to live in `public/`, and `public/` keeps its names:
+ * the edge serves it for a minute, and every returning visitor downloads the
+ * hero film again (railtec, 19 October 2026: two megabytes).
+ *
+ * Declaring a lifetime for the directory (`cache` in `_meta.json`) is one
+ * answer, and it costs the names: the platform then holds each one to its
+ * contents for as long as was declared. This is the other answer, and the one
+ * that costs nothing later — after the build, each file under the named
+ * directories is copied under `/_astro/kept/` with a hash of its bytes in its
+ * name, and every place the build wrote its address as a literal is pointed
+ * at the copy. A new photograph is a new name by construction.
+ *
+ * ── what it does not do ─────────────────────────────────────────────────────
+ *
+ * It rewrites an address only where the build wrote it whole — `"/clips/
+ * einsatz.mp4"` in a script, `src`, `data-src`, `url(…)`. An address a script
+ * assembles (`'/scenes/scene-' + i + '.webp'`) cannot be found, so the
+ * original stays where it was and keeps working, at its minute; the result
+ * names every file nothing pointed at, so the site can write those addresses
+ * out in full. The originals are never removed.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, sep } from 'node:path';
+
+/** Where the copies go: under Astro's hashed directory, which the edge keeps for a year. */
+export const KEPT_DIR = '_astro/kept';
+
+/** The files whose text may name an address. */
+const TEXT = new Set(['.html', '.js', '.mjs', '.css']);
+
+const posix = (path) => path.split(sep).join('/');
+
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith('.')) continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+/** `scene-1.webp` and its bytes → `scene-1.3f9a1c2b.webp`. */
+export function keptName(name, bytes) {
+  const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+  const ext = extname(name);
+  return `${name.slice(0, name.length - ext.length)}.${hash}${ext}`;
+}
+
+/**
+ * Copies the files under `dirs` of a build directory to hashed names and
+ * points the build's literal references at them.
+ *
+ * @param {string} dist  the build directory
+ * @param {{ dirs: string[]; base?: string }} options
+ *   `dirs`, as they sit under `public/` — `['clips', 'scenes']`; `base`, the
+ *   site's base path when it is not `/` (Astro's `base`)
+ * @returns {{ kept: { from: string; to: string }[]; rewritten: number; unreferenced: string[] }}
+ *   every copy as addresses, how many references were pointed at one, and the
+ *   addresses no file named whole — still served by name, at the edge's minute
+ */
+export function keepByName(dist, { dirs, base = '/' } = {}) {
+  if (!Array.isArray(dirs) || dirs.length === 0) return { kept: [], rewritten: 0, unreferenced: [] };
+  const root = `/${base.replace(/^\/+|\/+$/g, '')}/`.replace(/^\/\/$/, '/');
+
+  const kept = [];
+  for (const one of dirs) {
+    const dir = one.replace(/^\/+|\/+$/g, '');
+    if (dir === '' || dir.startsWith('_astro') || dir.startsWith('.')) {
+      throw new TypeError(`keepByName: "${one}" is not a directory of public/ (not the root, not _astro, not hidden)`);
+    }
+    const from = join(dist, dir);
+    if (!existsSync(from)) continue;
+    for (const file of walk(from)) {
+      if (extname(file).toLowerCase() === '.html') continue;
+      const inside = posix(relative(from, file));
+      const hashed = posix(join(dirname(inside), keptName(inside.split('/').pop(), readFileSync(file))));
+      const to = join(dist, KEPT_DIR, dir, hashed);
+      mkdirSync(dirname(to), { recursive: true });
+      copyFileSync(file, to);
+      kept.push({ from: `${root}${dir}/${inside}`, to: `${root}${KEPT_DIR}/${dir}/${hashed.replace(/^\.\//, '')}` });
+    }
+  }
+  if (kept.length === 0) return { kept, rewritten: 0, unreferenced: [] };
+
+  // One pattern for every address, longest first, bounded the way an address
+  // is written: after a quote, a bracket, a space, `=` or `,` — or `&quot;`,
+  // which is how a JSON list in a `data-` attribute reaches the HTML — and
+  // before a quote, a bracket, a space, `,`, `?`, `#` or `&`. `/clips/a.mp4`
+  // must not match inside `/clips/a.mp4.old` or `/x/clips/a.mp4`.
+  const to = new Map(kept.map((one) => [one.from, one.to]));
+  const escaped = [...to.keys()].sort((a, b) => b.length - a.length).map((one) => one.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const pattern = new RegExp(`(?<=["'\`(\\s=,]|&quot;|&#34;|&#39;)(${escaped.join('|')})(?=["'\`)\\s,?#&])`, 'g');
+
+  const used = new Set();
+  let rewritten = 0;
+  const copies = join(dist, KEPT_DIR) + sep;
+  for (const file of walk(dist)) {
+    if (file.startsWith(copies) || !TEXT.has(extname(file).toLowerCase())) continue;
+    const text = readFileSync(file, 'utf8');
+    let changed = false;
+    const next = text.replace(pattern, (address) => {
+      used.add(address);
+      rewritten += 1;
+      changed = true;
+      return to.get(address);
+    });
+    if (changed) writeFileSync(file, next);
+  }
+
+  return { kept, rewritten, unreferenced: kept.map((one) => one.from).filter((one) => !used.has(one)) };
+}

package/lib/meta.mjs

@@ -133,15 +133,56 @@ export async function hiddenEntries(root = join(process.cwd(), 'jtk', 'content')
  * @param {string[]} [what.locales]
  * @param {string[]} [what.immutable]          e.g. `['/_astro/']`
  * @param {{ from: string; to: string; status?: number }[]} [what.redirects]
- * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[] }>}
+ * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[]; cache?: { prefix: string; maxAge: number }[] }>}
  */
-export async function buildMeta({ root, collections = [], blocks = [], locales = [], immutable, redirects = [] } = {}) {
+export async function buildMeta({ root, collections = [], blocks = [], locales = [], immutable, cache, redirects = [] } = {}) {
   const drafts = [...(await hiddenEntries(root)), ...specimenAddresses(collections, blocks, locales)].sort();
   const meta = { redirects, drafts };
   if (Array.isArray(immutable) && immutable.length > 0) meta.immutable = immutable;
+  const lifetimes = cacheRules(cache);
+  if (lifetimes.length > 0) meta.cache = lifetimes;
   return meta;
 }
 
+/** A year: the most the edge keeps anything for. */
+const YEAR = 31_536_000;
+
+/**
+ * The lifetimes a build declares for directories of files that keep their own
+ * names — `public/clips/`, a film or a photograph a script addresses — read
+ * the way the edge reads them (jtakeit-core edge/src/meta.ts): each prefix as
+ * `/dir/`, never `/`, a whole number of seconds, at most a year.
+ *
+ * Thrown on rather than dropped, unlike the edge: the edge reads somebody
+ * else's file and must not fall over, the build is ours and should be told.
+ *
+ * Every name under such a directory is then held by the platform to its
+ * contents, once the site has an address, until the last visitor's copy may
+ * have run out: other bytes under it are refused (JTK_E_CACHED_FILE_CHANGED),
+ * and lowering `maxAge` frees nothing sooner. A day for names that may be
+ * reused; a year only for names that carry their version — or put the files
+ * under a hashed name with `keepByName` (`@jtakeit/kit/kept`) and declare
+ * nothing.
+ *
+ * @param {{ prefix: string; maxAge: number }[] | undefined} cache
+ * @returns {{ prefix: string; maxAge: number }[]}
+ */
+export function cacheRules(cache) {
+  if (cache === undefined || cache === null) return [];
+  if (!Array.isArray(cache)) throw new TypeError('cache is a list of { prefix, maxAge }');
+  return cache.map((one, i) => {
+    if (one === null || typeof one !== 'object' || typeof one.prefix !== 'string') {
+      throw new TypeError(`cache[${i}] needs a prefix, like "/clips/"`);
+    }
+    const trimmed = one.prefix.replace(/^\/+|\/+$/g, '');
+    if (trimmed === '') throw new TypeError(`cache[${i}]: a prefix of "/" would cover the whole site, pages included`);
+    if (typeof one.maxAge !== 'number' || !Number.isFinite(one.maxAge) || one.maxAge < 0) {
+      throw new TypeError(`cache[${i}]: maxAge is a number of seconds, like 86400 for a day`);
+    }
+    return { prefix: `/${trimmed}/`, maxAge: Math.min(Math.floor(one.maxAge), YEAR) };
+  });
+}
+
 /**
  * Writes `_meta.json` into a build directory — whatever happens, empty lists
  * and all, because a missing file and an empty one mean different things to
@@ -149,7 +190,7 @@ export async function buildMeta({ root, collections = [], blocks = [], locales =
  *
  * @param {string} dir   the build directory, `dist/`
  * @param {Parameters<typeof buildMeta>[0]} what
- * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[] }>}
+ * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[]; cache?: { prefix: string; maxAge: number }[] }>}
  */
 export async function writeMeta(dir, what = {}) {
   const meta = await buildMeta(what);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtakeit/kit",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The framework-free half of a site on jtakeit: the booking form as an element and as markup, for Astro through @jtakeit/astro and for any other generator directly",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,16 @@
       "types": "./types/meta.d.ts",
       "default": "./lib/meta.mjs"
     },
+    "./kept": {
+      "types": "./types/kept.d.ts",
+      "default": "./lib/kept.mjs"
+    },
     "./kits": {
       "types": "./types/kits.d.ts",
       "default": "./lib/kits.mjs"
     },
     "./catalogue": "./lib/catalogue.mjs",
+    "./devdiary": "./lib/devdiary.mjs",
     "./codes": "./lib/codes.mjs",
     "./elements/booking": {
       "types": "./types/elements-booking.d.ts",

package/types/kept.d.ts

@@ -0,0 +1,21 @@
+/** Where the copies go: under Astro's hashed directory, which the edge keeps for a year. */
+export const KEPT_DIR: string;
+
+/** `scene-1.webp` and its bytes → `scene-1.3f9a1c2b.webp`. */
+export function keptName(name: string, bytes: Uint8Array): string;
+
+export interface Kept {
+  /** Every copy, as addresses: `/clips/a.mp4` → `/_astro/kept/clips/a.3f9a1c2b.mp4`. */
+  kept: { from: string; to: string }[];
+  /** How many references in the build were pointed at a copy. */
+  rewritten: number;
+  /** Addresses no file of the build named whole — still served by name, at the edge's minute. */
+  unreferenced: string[];
+}
+
+/**
+ * Copies the files under `dirs` of a build directory to names that carry a
+ * hash of their bytes, under `/_astro/kept/`, and points the build's literal
+ * references at them. The originals stay.
+ */
+export function keepByName(dist: string, options: { dirs: string[]; base?: string }): Kept;

package/types/meta.d.ts

@@ -2,6 +2,15 @@ export interface Meta {
   redirects: { from: string; to: string; status?: number }[];
   drafts: string[];
   immutable?: string[];
+  cache?: CacheRule[];
+}
+
+/** How long browsers keep the files under a directory whose names carry no hash. */
+export interface CacheRule {
+  /** The directory, e.g. `/clips/`. Never `/`. */
+  prefix: string;
+  /** Seconds, at most a year. Pages under the directory are never covered. */
+  maxAge: number;
 }
 
 export interface MetaInput {
@@ -12,6 +21,12 @@ export interface MetaInput {
   locales?: string[];
   /** The directories whose file names carry a content hash, e.g. `['/_astro/']`. */
   immutable?: string[];
+  /**
+   * Lifetimes for directories of files that keep their names. Each name is
+   * then held to its contents by the platform for that long: new contents
+   * take a new name (JTK_E_CACHED_FILE_CHANGED).
+   */
+  cache?: CacheRule[];
   redirects?: { from: string; to: string; status?: number }[];
 }
 
@@ -22,5 +37,6 @@ export function specimenAddresses(
   locales?: string[],
 ): string[];
 export function hiddenEntries(root?: string, now?: number): Promise<string[]>;
+export function cacheRules(cache?: CacheRule[]): CacheRule[];
 export function buildMeta(what?: MetaInput): Promise<Meta>;
 export function writeMeta(dir: string, what?: MetaInput): Promise<Meta>;