@jtakeit/kit 0.2.0 → 0.4.0

package/README.md

@@ -165,6 +165,11 @@ scaffold.
 
 ## Also here
 
+- `@jtakeit/kit/progress` — where the site is, read off the files: the brief's
+  fill, the pages written, the entries, the settings, what is missing. The
+  scaffold's dev server serves it as `/_jtk/progress.json` for the panel, and
+  `jtkit progress` prints the same list for the agent; a rule in one is a
+  rule in both, and nothing in it is declared.
 - `@jtakeit/kit/money` — a price as the page says it: «2 300 ₴», no kopecks
   on a whole price, no sign where the site has not said its currency.
 - `@jtakeit/kit/booking/words` — the form's words per language, the salon's

package/bin/jtkit.mjs

@@ -7,6 +7,10 @@
  *       kit's types, collections and module into jtk/catalogue.json
  *   jtkit catalogue [--declaration src/content/blocks.ts] [--emit-only] [--dist ./dist] [--judge]
  *       write jtk/catalogue.json from a declaration and check it against the built pages
+ *   jtkit lint [--dist dist] [--root .] [--site-url https://…]
+ *       the annotation lint the platform's build runs, on this working tree
+ *   jtkit progress [--root .] [--json]
+ *       where the site is, read off the files: the brief, the pages, the entries, what is missing
  */
 import { pathToFileURL } from 'node:url';
 import { join, dirname, resolve } from 'node:path';
@@ -44,6 +48,30 @@ switch (command) {
     }
     break;
   }
+  case 'progress': {
+    // The same reading the scaffold's dev server serves the panel as
+    // /_jtk/progress.json — what the owner sees as missing is what this
+    // prints (jtakeit-core, wiki/73).
+    const { readProgress, sayProgress } = await import(pathToFileURL(join(HERE, '..', 'lib', 'progress.mjs')).href);
+    const progress = await readProgress(resolve(flag('root', '.')));
+    console.log(has('json') ? JSON.stringify(progress, null, 2) : sayProgress(progress));
+    process.exit(progress.missing.length === 0 ? 0 : 1);
+  }
+  case 'lint': {
+    // The annotation lint the platform's build runs, on this working tree:
+    // `dist/` against `jtk/` and the catalogue, every finding at once,
+    // before any push (core wiki/71 · §3.2).
+    const { lintCommand } = await import(pathToFileURL(join(HERE, '..', 'lib', 'lint.mjs')).href);
+    const root = resolve(flag('root', process.cwd()));
+    const dist = resolve(root, flag('dist', 'dist'));
+    try {
+      process.exit(await lintCommand({ root, dist, siteURL: flag('site-url', process.env.SITE_URL ?? '') }));
+    } catch (why) {
+      console.error(`jtkit lint: ${why.message}`);
+      process.exit(1);
+    }
+    break;
+  }
   case 'catalogue':
   case 'catalog': {
     process.argv = [process.argv[0], process.argv[1], ...rest];

package/lib/build-codes.mjs

@@ -0,0 +1,29 @@
+/**
+ * The codes the annotation lint may say.
+ *
+ * A copy of the platform's `backend/api/sitebuild/errcodes.mjs`, which is
+ * generated from the one declaration of the codes (`registry/errcode.go`), for
+ * the same reason `codes.mjs` is a copy: a local lint that needs the network to
+ * name a fault is a local lint nobody runs. What keeps it honest is the
+ * platform's own parity test, which reads the lint it stages from this package
+ * against the Go table on every builder change.
+ */
+export const CODES = Object.freeze({
+  UNANNOTATED_FIELD: 'JTK_E_UNANNOTATED_FIELD',
+  PAGE_NOT_BUILT: 'JTK_E_PAGE_NOT_BUILT',
+  ROBOTS_DISALLOW: 'JTK_E_ROBOTS_DISALLOW',
+  SITEMAP_EMPTY: 'JTK_E_SITEMAP_EMPTY',
+  CANONICAL_ELSEWHERE: 'JTK_E_CANONICAL_ELSEWHERE',
+  NOINDEX: 'JTK_E_NOINDEX',
+  SHARED_NOT_RENDERED: 'JTK_E_SHARED_NOT_RENDERED',
+  ANNOTATION_UNKNOWN: 'JTK_E_ANNOTATION_UNKNOWN',
+  CATALOGUE_MISSING: 'JTK_E_CATALOGUE_MISSING',
+  FORM_INCOMPLETE: 'JTK_E_FORM_INCOMPLETE',
+  FORM_FIELD_UNDECLARED: 'JTK_E_FORM_FIELD_UNDECLARED',
+  FORM_UNDECLARED: 'JTK_E_FORM_UNDECLARED',
+});
+
+/** One line of the lint's output, with its code in front of it. */
+export function said(code, message) {
+  return `${code} ${message}`;
+}

package/lib/catalogue.mjs

@@ -735,7 +735,35 @@ for (const file of sourceFiles(join(root, 'src'))) {
  */
 
 /** The credential, presented the way the admin API reads it. */
-function judgeRequest(text) {
+/**
+ * The working tree's other jtk/ files, sent beside the catalogue so the
+ * second judge — the settings, the entries, a price table's gaps, an add-on
+ * nobody can take — answers in the same call, before any push (core
+ * wiki/71 · §3.2). Everything under jtk/ but the catalogue itself, as
+ * `{path, text}`; a site with no jtk/ yet sends none.
+ * @param {string} root
+ * @returns {{ path: string, text: string }[]}
+ */
+export function filesBeside(root) {
+  const dir = join(root, 'jtk');
+  if (!existsSync(dir)) return [];
+  /** @type {{ path: string, text: string }[]} */
+  const out = [];
+  const walk = (/** @type {string} */ at) => {
+    for (const entry of readdirSync(at, { withFileTypes: true })) {
+      const full = join(at, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      if (!entry.name.endsWith('.json')) continue;
+      const rel = relative(root, full).split(sep).join('/');
+      if (rel === 'jtk/catalogue.json') continue;
+      out.push({ path: rel, text: readFileSync(full, 'utf8') });
+    }
+  };
+  walk(dir);
+  return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function judgeRequest(text, files) {
   const api = (process.env.JTK_API ?? '').trim().replace(/\/+$/, '');
   const token = (process.env.JTK_TOKEN ?? '').trim();
   return {
@@ -753,7 +781,7 @@ function judgeRequest(text) {
         accept: 'application/json',
         'content-type': 'application/json',
       },
-      body: JSON.stringify({ catalogue: text }),
+      body: JSON.stringify(files.length > 0 ? { catalogue: text, files } : { catalogue: text }),
     },
   };
 }
@@ -782,13 +810,14 @@ as a bearer; anything else is taken for the \`sid\` cookie of a person signed in
 to the admin. The MCP server itself reads neither variable — it is hosted, and
 an agent connects to it through the browser.
 
-An agent with the MCP server needs neither: push, then \`validate_catalogue\`
-with the site and the ref judges the whole commit — this catalogue, the
-settings, the content — with the same judge and every finding at once.`);
+An agent with the MCP server needs neither: \`validate_catalogue\` with the
+catalogue and the jtk/ files beside it judges the whole working tree — this
+catalogue, the settings, the content — before any push, every finding at once.`);
     process.exit(1);
   }
 
-  const { url, init } = judgeRequest(text);
+  const files = filesBeside(root);
+  const { url, init } = judgeRequest(text, files);
 
   let response;
   try {
@@ -822,7 +851,18 @@ settings, the content — with the same judge and every finding at once.`);
     return 0;
   }
 
-  const findings = verdict.findings ?? [];
+  const all = verdict.findings ?? [];
+  // The files' findings — the settings, an entry, a price table — are the
+  // judge's alone, about files this checker never reads: printed as what
+  // they are, and not examined. The catalogue's own are the exam.
+  const ofFiles = all.filter((one) => /^jtk\//.test(one.path ?? ''));
+  const findings = all.filter((one) => !ofFiles.includes(one));
+  for (const one of ofFiles) {
+    console.error(`  ✗ ${one.code}  ${one.path}: ${one.says}`);
+  }
+  if (ofFiles.length > 0) {
+    console.error(`  ${ofFiles.length} finding(s) in the files beside the catalogue (${files.length} sent) — refused at import until fixed.\n`);
+  }
   // Advice is the judge's alone — rules about the bookings module it runs,
   // which this checker has no copy of — so it is printed and not examined.
   const advice = [...(verdict.advice ?? []), ...findings.filter((one) => isAdvice(one.code))];
@@ -845,10 +885,10 @@ settings, the content — with the same judge and every finding at once.`);
 
   if (missed.length === 0 && invented.length === 0) {
     console.log(
-      `judged by ${url} — contract ${verdict.contract}, ${findings.length} finding(s), ` +
-        'and this checker said the same',
+      `judged by ${url} — contract ${verdict.contract}, ${findings.length} finding(s) in the catalogue, ` +
+        `${ofFiles.length} in the ${files.length} file(s) beside it, and this checker said the same of the catalogue`,
     );
-    return 0;
+    return ofFiles.length;
   }
 
   console.error(`\njtk catalogue: the judge and this checker do not agree (contract ${verdict.contract})\n`);

package/lib/content.mjs

@@ -0,0 +1,101 @@
+/**
+ * The published content as one document, from the files in `jtk/`.
+ *
+ * The content lives in the repository as one file per page, because that is
+ * what makes a diff readable; everything that reads it — the build, the
+ * annotation lint — wants one document, because that is what a template
+ * renders from. This is the seam between the two, the same one the platform's
+ * build runs (`collect-content.mjs`), here so that `jtkit lint` can read a
+ * working tree the way the build will. Nothing over the network.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** @param {string} path */
+async function readJSON(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`${path}: ${error.message}`);
+  }
+}
+
+/** Every content file under a directory, at any depth, sorted. @param {string} root */
+async function contentFiles(root) {
+  /** @type {string[]} */
+  const found = [];
+  async function walk(/** @type {string} */ current) {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch (error) {
+      if (error.code === 'ENOENT') return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.name.endsWith('.json')) found.push(path);
+    }
+  }
+  await walk(root);
+  return found.sort();
+}
+
+/**
+ * Which language a shared file is, out of its name: `shared.json` the site's
+ * own, `shared.de.json` German; null for a file that is not one.
+ * @param {string} name
+ */
+export function sharedLocaleOf(name) {
+  const match = /^shared(?:\.([a-z]{2}(?:-[a-z]{2})?))?\.json$/.exec(name);
+  return match === null ? null : (match[1] ?? '');
+}
+
+/**
+ * The document the build renders from. `jtk/site.json` is what publish writes;
+ * a working tree before its first publish has none, and the lint reads it
+ * anyway with the site's facts left empty — the annotations do not depend on
+ * them.
+ * @param {string} root the site's root, holding `jtk/`
+ * @param {{ dir?: string }} [options] `dir`: where `jtk/` is, relative to the root
+ */
+export async function collectContent(root, options = {}) {
+  const dir = join(root, options.dir ?? 'jtk');
+  const site = (await readJSON(join(dir, 'site.json'))) ?? {};
+  const pages = [];
+  for (const file of await contentFiles(join(dir, 'content'))) {
+    const page = await readJSON(file);
+    if (page === null) continue;
+    if (typeof page.path !== 'string') throw new Error(`${file}: no "path" — cannot tell which page this is`);
+    const collected = { path: page.path, seo: page.seo ?? {}, blocks: page.blocks ?? [] };
+    if (typeof page.collection === 'string' && page.collection !== '') {
+      collected.collection = page.collection;
+      collected.visible = page.visible !== false;
+    }
+    pages.push(collected);
+  }
+  pages.sort((a, b) => (a.path === '/' ? -1 : b.path === '/' ? 1 : a.path.localeCompare(b.path)));
+
+  const shared = [];
+  for (const name of (await readdir(dir).catch(() => [])).sort()) {
+    const locale = sharedLocaleOf(name);
+    if (locale === null) continue;
+    const file = await readJSON(join(dir, name));
+    if (file?.blocks?.length) shared.push({ ...(locale === '' ? {} : { locale }), blocks: file.blocks });
+  }
+
+  return {
+    schema_version: site.schema_version ?? 1,
+    content_rev: site.content_rev ?? 0,
+    site: {
+      slug: site.slug ?? '',
+      locale: site.locale ?? 'uk',
+      media_base: site.media_base ?? '',
+      business: site.business ?? {},
+    },
+    pages,
+    ...(shared.length > 0 ? { shared } : {}),
+  };
+}

package/lib/lint.mjs

@@ -0,0 +1,369 @@
+/**
+ * The annotation lint: the built pages against the content and the catalogue.
+ *
+ * «Every content field carries data-jtk-path» is not a convention — it is a
+ * gate. An element that loses its annotation breaks the visual editor
+ * SILENTLY: the sheet stops opening when the client taps that heading, and
+ * nobody finds out for a week. The lint compares two things it did not write
+ * — the content and the HTML the site produced — never the component source,
+ * so it works with any template, including one an agent wrote this afternoon.
+ *
+ * The platform's build runs this lint on every demo build. It is here so that
+ * a site can run it on its own `dist/` before any push (`jtkit lint`, core
+ * wiki/71 · §3.2): the same checks, the same codes, the same sentences, and
+ * every finding at once rather than one build round each.
+ *
+ * `lint()` returns findings rather than printing and exiting, so a script, a
+ * test and the build can each do what they do with them. The order and the
+ * early stops are the build's: a page that says noindex stops the lint, as it
+ * stops the build.
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { CODES, said } from './build-codes.mjs';
+import { collectContent } from './content.mjs';
+
+export { CODES, said };
+
+/**
+ * The kinds a person edits by tapping the thing itself. A URL, a boolean or
+ * an alt text is edited in the panel beside it, so requiring an annotated
+ * element for those would fail every honest template.
+ */
+export const TAPPABLE = new Set(['text', 'textarea', 'richtext_lite', 'markdown', 'media']);
+
+/** @param {any} field */
+function tappable(field) {
+  if (!TAPPABLE.has(field.kind)) return false;
+  if (field.client_editable === false) return false;
+  if (field.no_tap_target === true) return false;
+  return true;
+}
+
+/** @param {string} url */
+function hostOf(url) {
+  try {
+    return new URL(url).host.toLowerCase();
+  } catch {
+    return '';
+  }
+}
+
+/** A robots.txt whose `User-agent: *` group says `Disallow: /` and nothing narrower. @param {string} text */
+function disallowsEverybody(text) {
+  let everybody = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (line === '') continue;
+    const [key, ...rest] = line.split(':');
+    const value = rest.join(':').trim();
+    if (key.trim().toLowerCase() === 'user-agent') everybody = value === '*';
+    else if (everybody && key.trim().toLowerCase() === 'disallow' && value === '/') return true;
+  }
+  return false;
+}
+
+/** @param {string} path */
+async function readOrEmpty(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** @param {string} dir */
+async function htmlFiles(dir) {
+  /** @type {string[]} */
+  const out = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await htmlFiles(path)));
+    else if (entry.name.endsWith('.html')) out.push(path);
+  }
+  return out;
+}
+
+/** Every path a built page is expected to carry, for one page's blocks. */
+export function expectedPaths(blocks, typeOf) {
+  /** @type {string[]} */
+  const paths = [];
+  blocks.forEach((block, index) => {
+    const blockType = typeOf(block.type);
+    if (blockType === undefined) return;
+    for (const field of blockType.fields ?? []) {
+      const value = block[field.key];
+      if (value === undefined || value === null || value === '') continue;
+      if (field.kind === 'media' && field.multiple === true) {
+        if (!Array.isArray(value) || !tappable(field)) continue;
+        value.forEach((item, itemIndex) => {
+          if (item === null || typeof item !== 'object' || !item.src) return;
+          paths.push(`blocks[${index}].${field.key}[${itemIndex}].src`);
+        });
+        continue;
+      }
+      if (field.kind === 'list') {
+        if (!Array.isArray(value)) continue;
+        value.forEach((item, itemIndex) => {
+          for (const sub of field.of ?? []) {
+            const subValue = item[sub.key];
+            if (!tappable(sub)) continue;
+            if (subValue === undefined || subValue === null || subValue === '') continue;
+            paths.push(`blocks[${index}].${field.key}[${itemIndex}].${sub.key}`);
+          }
+        });
+        continue;
+      }
+      if (tappable(field)) paths.push(`blocks[${index}].${field.key}`);
+    }
+  });
+  return paths;
+}
+
+/** Every form on the page that posts to the platform's enquiry endpoint. @param {string} html */
+function leadForms(html) {
+  const out = [];
+  for (const [form] of html.matchAll(/<form\b[^>]*>[\s\S]*?<\/form>/gi)) {
+    const action = attrOf(form.slice(0, form.indexOf('>') + 1), 'action') ?? '';
+    if (/(^|\/)api\/lead\/?(\?|#|$)/.test(action)) out.push(form);
+  }
+  return out;
+}
+
+/** The names of a form's controls, buttons left out. @param {string} form */
+function controlsOf(form) {
+  const names = new Set();
+  for (const [tag] of form.matchAll(/<(?:input|select|textarea)\b[^>]*>/gi)) {
+    const type = (attrOf(tag, 'type') ?? '').toLowerCase();
+    if (type === 'submit' || type === 'button' || type === 'reset' || type === 'image') continue;
+    const name = attrOf(tag, 'name');
+    if (name !== undefined && name !== '') names.add(name);
+  }
+  return names;
+}
+
+/** @param {string} tag @param {string} name */
+function attrOf(tag, name) {
+  const quoted = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag);
+  if (quoted === null) return undefined;
+  return quoted[1] ?? quoted[2] ?? quoted[3];
+}
+
+/**
+ * Whether a block collects enquiries — as the API judges it, not only as the
+ * file says: a catalogue written before `collects` existed says nothing, and
+ * a block with a `form` switch is one that can put a form on the page.
+ * @param {any} blockType
+ */
+function collectsEnquiry(blockType) {
+  if (blockType === undefined) return false;
+  if (blockType.collects === 'enquiry') return true;
+  if (blockType.collects !== undefined && blockType.collects !== '') return false;
+  return (blockType.fields ?? []).some((field) => field.key === 'form' && field.kind === 'bool');
+}
+
+const OWN_CONTROLS = new Set(['name', 'phone', 'email', 'contact', 'message', 'website']);
+
+/**
+ * @typedef {{ code: string, says: string }} Finding
+ * @typedef {{ findings: Finding[], ok: boolean, pages: number, shared: boolean, line: string }} Verdict
+ */
+
+/**
+ * Lint a built site.
+ *
+ * @param {object} options
+ * @param {string} [options.root]      the site's root, holding `jtk/` — the working directory by default
+ * @param {string} [options.dist]      the built pages — `dist` under the root by default
+ * @param {string} [options.siteURL]   the address the build is for (`SITE_URL`); empty skips the host checks
+ * @param {any}    [options.catalogue] the catalogue, read from `jtk/catalogue.json` when left out
+ * @param {any}    [options.content]   the content document, collected from `jtk/` when left out
+ * @returns {Promise<Verdict>}
+ */
+export async function lint(options = {}) {
+  const root = options.root ?? process.cwd();
+  const distDir = options.dist ?? join(root, 'dist');
+  /** @type {Finding[]} */
+  const findings = [];
+  const fault = (code, says) => findings.push({ code, says });
+  const verdict = (line = '') => ({ findings, ok: findings.length === 0, pages: 0, shared: false, line });
+
+  // The catalogue: refused rather than skipped when missing. A lint that
+  // quietly passes when it cannot find its catalogue is worse than no lint.
+  let registry = options.catalogue;
+  if (registry === undefined) {
+    const file = join(root, 'jtk', 'catalogue.json');
+    try {
+      registry = JSON.parse(await readFile(file, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`could not read ${file}: ${error.message}`);
+      fault(CODES.CATALOGUE_MISSING, `no jtk/catalogue.json — this site has no block catalogue, so nothing can check that its content is annotated`);
+      return verdict();
+    }
+  }
+  const typeOf = (name) => registry?.blocks?.find((block) => block.type === name);
+  const content = options.content ?? (await collectContent(root));
+
+  // What every build promises search engines, read off the files themselves.
+  {
+    const host = hostOf(options.siteURL ?? '');
+    const front = await readOrEmpty(join(distDir, 'index.html'));
+    if (/<meta[^>]+name=["']robots["'][^>]*noindex/i.test(front) || /<meta[^>]+content=["'][^"']*noindex[^"']*["'][^>]*name=["']robots["']/i.test(front)) {
+      fault(CODES.NOINDEX, "the front page says noindex — nothing in a page decides whether it is indexed; the edge keeps a preview out of the index, and a build is always made for the site's address");
+      return verdict();
+    }
+    if (disallowsEverybody(await readOrEmpty(join(distDir, 'robots.txt')))) {
+      fault(CODES.ROBOTS_DISALLOW, 'robots.txt says Disallow: / for every crawler');
+      return verdict();
+    }
+    const sitemap = await readOrEmpty(join(distDir, 'sitemap.xml'));
+    if (sitemap !== '') {
+      const locs = [...sitemap.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]);
+      const foreign = host === '' ? [] : locs.filter((loc) => hostOf(loc) !== host);
+      if (locs.length === 0 || foreign.length > 0) {
+        fault(CODES.SITEMAP_EMPTY, locs.length === 0 ? 'sitemap.xml lists no pages' : `sitemap.xml lists pages on ${hostOf(foreign[0])}, and this build is for ${host} (SITE_URL)`);
+        return verdict();
+      }
+    }
+    const canonical = /<link[^>]+rel=["']canonical["'][^>]*href=["']([^"']+)["']/i.exec(front)?.[1] ?? /<link[^>]+href=["']([^"']+)["'][^>]*rel=["']canonical["']/i.exec(front)?.[1];
+    if (host !== '' && canonical !== undefined && hostOf(canonical) !== '' && hostOf(canonical) !== host) {
+      fault(CODES.CANONICAL_ELSEWHERE, `the front page's canonical is on ${hostOf(canonical)}, and this build is for ${host} (SITE_URL)`);
+      return verdict();
+    }
+  }
+
+  const htmlByPath = new Map();
+  for (const file of await htmlFiles(distDir)) {
+    const rel = '/' + relative(distDir, file).replaceAll('\\', '/');
+    htmlByPath.set(rel.replace(/\/index\.html$/, '').replace(/\.html$/, '') || '/', await readFile(file, 'utf8'));
+  }
+
+  // The form against the contract of an enquiry.
+  const sharedBlocks = (content.shared ?? []).flatMap((document) => document.blocks ?? []);
+  const siteCollects = (registry?.blocks ?? []).some(collectsEnquiry);
+  const pageByPath = new Map((content.pages ?? []).map((page) => [page.path, page]));
+  const asksOf = (blocks) => {
+    const keys = new Set();
+    for (const block of blocks) {
+      const blockType = typeOf(block.type);
+      if (!collectsEnquiry(blockType)) continue;
+      for (const ask of blockType.asks ?? []) keys.add(ask.key);
+    }
+    return keys;
+  };
+  let formFaults = 0;
+  for (const [where, html] of htmlByPath) {
+    for (const form of leadForms(html)) {
+      const controls = controlsOf(form);
+      const page = pageByPath.get(where);
+      const near = [...(page?.blocks ?? []), ...sharedBlocks];
+      const nearCollects = near.some((block) => collectsEnquiry(typeOf(block.type)));
+      if (!nearCollects && !siteCollects) {
+        fault(CODES.FORM_UNDECLARED, `${where}: a form posts to /api/lead and no block says collects: "enquiry"`);
+        formFaults++;
+        continue;
+      }
+      const asks = nearCollects ? asksOf(near) : asksOf((registry?.blocks ?? []).map((block) => ({ type: block.type })));
+      const lacking = [];
+      if (!controls.has('name')) lacking.push('a name control');
+      if (!controls.has('contact') && !controls.has('phone') && !controls.has('email')) lacking.push('a contact, phone or email control');
+      if (!controls.has('website')) lacking.push('the honeypot website');
+      if (lacking.length > 0) {
+        fault(CODES.FORM_INCOMPLETE, `${where}: the enquiry form has no ${lacking.join(', no ')}`);
+        formFaults++;
+      }
+      for (const control of controls) {
+        if (OWN_CONTROLS.has(control) || asks.has(control)) continue;
+        fault(CODES.FORM_FIELD_UNDECLARED, `${where}: the enquiry form asks for "${control}" and no block declares it in asks — the inbox would show a key, not a label`);
+        formFaults++;
+      }
+    }
+  }
+  if (formFaults > 0) return verdict(`${formFaults} enquiry form fault(s)`);
+
+  // The text that is on every page: a shared field the whole site annotates nowhere.
+  for (const document of content.shared ?? []) {
+    const language = document.locale === undefined ? '' : ` (${document.locale})`;
+    for (const path of expectedPaths(document.blocks ?? [], typeOf)) {
+      const shared = `shared:${path}`;
+      if (![...htmlByPath.values()].some((html) => html.includes(`data-jtk-path="${shared}"`))) {
+        fault(CODES.SHARED_NOT_RENDERED, `${shared}${language} is on no page — a shared field nothing renders is a control that edits nothing`);
+      }
+    }
+  }
+
+  // Entries of a collection without pages: on their listing, annotated there.
+  const pageless = new Set((registry?.collections ?? []).filter((one) => one.pages === false).map((one) => one.name));
+  const everywhere = [...htmlByPath.values()].join('\n');
+  const listable = (page) => page.visible !== false;
+  for (const one of registry?.collections ?? []) {
+    if (one.pages !== false) continue;
+    const hasEntries = (content.pages ?? []).some((page) => page.collection === one.name && listable(page));
+    if (hasEntries && !htmlByPath.has(one.prefix)) {
+      fault(CODES.PAGE_NOT_BUILT, `${one.prefix}: the collection "${one.name}" has no pages of its own and lists its entries here, and the build did not produce this page — make the prefix the page that lists them, or build one there`);
+    }
+  }
+  for (const page of content.pages ?? []) {
+    if (page.collection !== undefined && pageless.has(page.collection)) {
+      if (!listable(page)) continue;
+      for (const path of expectedPaths(page.blocks ?? [], typeOf)) {
+        if (!everywhere.includes(`data-jtk-path="page:${page.path}:${path}"`)) {
+          fault(CODES.UNANNOTATED_FIELD, `${page.path}: ${path} is on no page — an entry without a page of its own has to be annotated on its listing`);
+        }
+      }
+      continue;
+    }
+    const html = htmlByPath.get(page.path);
+    if (html === undefined) {
+      const listedOnly = (registry?.collections ?? []).find((one) => one.pages === false && page.path.startsWith(`${one.prefix}/`));
+      const hint = page.collection === undefined && listedOnly !== undefined
+        ? ` — it sits under the "${listedOnly.name}" collection's prefix and names no collection; an entry says "collection": "${listedOnly.name}" and is annotated on the listing instead`
+        : '';
+      fault(CODES.PAGE_NOT_BUILT, `${page.path}: the content has this page and the build did not produce it${hint}`);
+      continue;
+    }
+    for (const path of expectedPaths(page.blocks ?? [], typeOf)) {
+      if (!html.includes(`data-jtk-path="${path}"`)) fault(CODES.UNANNOTATED_FIELD, `${page.path}: ${path} is not annotated`);
+    }
+  }
+
+  // A tile that names a page nobody has, or a field that page has not got.
+  const CROSS = /data-jtk-path="page:([^:"]*):([^"]+)"/g;
+  for (const [where, html] of htmlByPath) {
+    for (const [, address, inner] of html.matchAll(CROSS)) {
+      const named = pageByPath.get(address);
+      if (named === undefined) {
+        fault(CODES.ANNOTATION_UNKNOWN, `${where}: annotates page:${address}: and this site has no such page`);
+        continue;
+      }
+      if (!expectedPaths(named.blocks ?? [], typeOf).includes(inner)) {
+        fault(CODES.ANNOTATION_UNKNOWN, `${where}: annotates ${inner} on ${address}, which that page's document has no field for`);
+      }
+    }
+  }
+
+  const withShared = content.shared === undefined ? '' : ' and the shared text';
+  const out = verdict(findings.length > 0
+    ? `${findings.length} unannotated field(s) — the visual editor would silently stop working on them`
+    : `every content field on ${content.pages?.length ?? 0} page(s)${withShared} is annotated`);
+  out.pages = content.pages?.length ?? 0;
+  out.shared = content.shared !== undefined;
+  return out;
+}
+
+/**
+ * The command: print the findings the way the build does, and exit 1 on any.
+ * @param {{ root?: string, dist?: string, siteURL?: string }} options
+ */
+export async function lintCommand(options) {
+  const out = await lint(options);
+  for (const one of out.findings) console.error('  ' + said(one.code, one.says));
+  if (out.line !== '') (out.ok ? console.log : console.error)('  ' + out.line);
+  return out.ok ? 0 : 1;
+}

package/lib/progress.mjs

@@ -0,0 +1,317 @@
+/**
+ * Progress is a function of the files (jtakeit-core, wiki/73).
+ *
+ * Between «connect an agent» and the first preview a person sees nothing for
+ * an hour while the site is written. What they should see is not what the
+ * agent says it is doing but what the site *is*: this module reads the
+ * working tree and says, for the person and the agent alike, what is written
+ * and what is still missing. It declares nothing and believes nothing — the
+ * brief's own checklist is read out as the agent's words, apart from the
+ * files', and the rest is counted.
+ *
+ * One implementation, two readers: the scaffold's dev server serves this as
+ * `/_jtk/progress.json` (jtakeit-meta.mjs) for the panel, and `jtkit
+ * progress` prints it for the agent. A rule here is a rule in both.
+ *
+ * ── what «written» means ───────────────────────────────────────────────────
+ *
+ * The scaffold's content leaves every text empty (`jtk/content/index.json`),
+ * so a page is being written when any of its text fields is filled, and is
+ * written when every field the catalogue marks `required` is — the exact
+ * rule where there is a catalogue, and the weaker one («has text») where a
+ * site on another generator has none yet, said as such in `rule`.
+ */
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { collectContent } from './content.mjs';
+
+/** Under the weaker rule, a key named like one of these is not words. */
+const NOT_WORDS = /(^|_)(image|picture|photo|media|video|url|href|link|icon|src)(_|$)|_href$|_url$/;
+/** The field kinds a person writes words into. */
+const TEXT = new Set(['text', 'textarea', 'richtext_lite', 'markdown']);
+/** The brief's headings, in the order the guide writes them. */
+export const BRIEF_SECTIONS = ['In one sentence', 'The one action', 'Facts', 'Bookings', 'Decisions', 'Open — NEEDS CLIENT', 'Done when'];
+
+/**
+ * Read the working tree and say where the site is.
+ * @param {string} root the site's root, holding `BRIEF.md`, `jtk/` and `src/`
+ * @param {{ dir?: string }} [options] `dir`: where `jtk/` is, relative to the root
+ */
+export async function readProgress(root, options = {}) {
+  const dir = options.dir ?? 'jtk';
+  const seen = [];
+  const note = (file) => stat(file).then((s) => seen.push(s.mtime), () => {});
+
+  const brief = await readBrief(join(root, 'BRIEF.md'));
+  await note(join(root, 'BRIEF.md'));
+  const catalogue = await readJSON(join(root, dir, 'catalogue.json'));
+  await note(join(root, dir, 'catalogue.json'));
+  const settings = await readJSON(join(root, dir, 'bookings.json'));
+  await note(join(root, dir, 'bookings.json'));
+  const facts = await readFacts(join(root, 'src', 'data', 'site.ts'));
+  await note(join(root, 'src', 'data', 'site.ts'));
+  let content = { pages: [] };
+  try {
+    content = await collectContent(root, { dir });
+  } catch {
+    // No jtk/ yet, or a document that is not a page: nothing is written.
+  }
+  for (const file of await contentFiles(join(root, dir, 'content'))) await note(file);
+
+  const fields = fieldsOf(catalogue);
+  const rule = catalogue ? 'exact' : 'has-text';
+  const pages = [];
+  const entries = {};
+  let media = 0;
+  for (const page of content.pages) {
+    const counted = countFields(page, fields, rule);
+    media += counted.media;
+    if (page.collection !== undefined) {
+      entries[page.collection] = (entries[page.collection] ?? 0) + 1;
+      continue;
+    }
+    pages.push({
+      path: page.path,
+      written: counted.filled > 0 && counted.requiredMissing === 0,
+      filled: counted.filled,
+      of: counted.of,
+      ...(counted.requiredMissing > 0 ? { missing: counted.requiredMissing } : {}),
+    });
+  }
+  pages.sort((a, b) => (a.path === '/' ? -1 : b.path === '/' ? 1 : a.path.localeCompare(b.path)));
+
+  const collections = {};
+  const bookings = catalogue?.modules?.bookings ?? null;
+  for (const one of catalogue?.collections ?? []) {
+    const expected = bookings !== null && (bookings.services === one.name || bookings.resources === one.name) ? 1 : 0;
+    collections[one.name] = { entries: entries[one.name] ?? 0, expected };
+  }
+  for (const [name, count] of Object.entries(entries)) {
+    if (collections[name] === undefined) collections[name] = { entries: count, expected: 0 };
+  }
+
+  const block = settings?.blocks?.[0] ?? null;
+  const settingsRead =
+    block === null
+      ? null
+      : {
+          kit: typeof block.kit === 'string' ? block.kit : '',
+          kit_version: typeof block.kit_version === 'string' ? block.kit_version : '',
+          hours: Array.isArray(block.hours) && block.hours.length > 0,
+          zone: typeof block.zone === 'string' && block.zone !== '',
+          payment: typeof block.payment === 'string' ? block.payment : '',
+        };
+
+  const missing = [];
+  if (brief === null) missing.push('BRIEF.md is not written yet');
+  else {
+    if (brief.open > 0) missing.push(`${brief.open} question${brief.open === 1 ? '' : 's'} for the client (Open — NEEDS CLIENT)`);
+    if (!brief.sections['Decisions']) missing.push('the brief has no Decisions yet');
+  }
+  if (!catalogue) missing.push('jtk/catalogue.json is not written yet (npx @jtakeit/astro catalogue)');
+  if (pages.length === 0) missing.push('no page has content yet');
+  for (const page of pages) {
+    if (page.written) continue;
+    missing.push(page.filled === 0 ? `${page.path} is not written yet` : `${page.path}: ${page.filled} of ${page.of} fields, ${page.missing ?? 0} required missing`);
+  }
+  for (const [name, one] of Object.entries(collections)) {
+    if (one.entries < one.expected) missing.push(`${name}: no entry yet`);
+  }
+  if (bookings !== null) {
+    if (settingsRead === null) missing.push('jtk/bookings.json is not written yet');
+    else {
+      if (!settingsRead.hours) missing.push('the opening hours are not set (jtk/bookings.json)');
+      if (!settingsRead.zone) missing.push('the time zone is not set (jtk/bookings.json)');
+    }
+  }
+  if (facts !== null && facts.placeholders > 0) missing.push(`src/data/site.ts still carries ${facts.placeholders} placeholder${facts.placeholders === 1 ? '' : 's'}`);
+  if (pages.length > 0 && media === 0) missing.push('no picture yet');
+
+  const changedAt = seen.length > 0 ? new Date(Math.max(...seen.map((d) => d.getTime()))).toISOString() : null;
+  return {
+    version: 1,
+    rule,
+    kit: settingsRead === null ? null : { kind: settingsRead.kit, version: settingsRead.kit_version },
+    brief,
+    catalogue: catalogue !== null,
+    pages,
+    collections,
+    settings: settingsRead === null ? null : { hours: settingsRead.hours, zone: settingsRead.zone, payment: settingsRead.payment },
+    facts,
+    media,
+    missing,
+    changedAt,
+  };
+}
+
+/**
+ * The brief as a document: which sections have words, how many facts carry a
+ * source, how many questions are open, and the agent's own checklist under
+ * «Done when» — read out, never believed.
+ */
+export async function readBrief(file) {
+  let text;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const sections = {};
+  const bodies = {};
+  let current = null;
+  for (const line of text.split('\n')) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1];
+      bodies[current] = [];
+      continue;
+    }
+    if (current !== null) bodies[current].push(line);
+  }
+  // A section has words when a line of it is neither empty, nor a table's
+  // header or separator, nor the skeleton's own sentence (the kit's line
+  // under Bookings is written by `jtk create`, not by the agent).
+  for (const name of BRIEF_SECTIONS) {
+    sections[name] = rowsOf(bodies[name] ?? []).some((l) => !/^\|/.test(l) ? !/^The kit: .*, whole/.test(l) : true);
+  }
+  const factRows = rowsOf(bodies['Facts'] ?? []).filter((l) => /^\|/.test(l));
+  const open = (bodies['Open — NEEDS CLIENT'] ?? []).filter((l) => /^\s*[-*]\s+\S/.test(l)).length;
+  const items = (bodies['Done when'] ?? []).filter((l) => /^\s*[-*]\s+\[[ xX]\]/.test(l));
+  const done = items.filter((l) => /\[[xX]\]/.test(l)).length;
+  // Gaps are marked in the tables: a fact or a default whose value is still
+  // the client's to give. The heading and the checklist's own words are not
+  // gaps.
+  const needsClient = [...rowsOf(bodies['Facts'] ?? []), ...rowsOf(bodies['Bookings'] ?? [])]
+    .filter((l) => /^\|/.test(l) && /NEEDS CLIENT/.test(l)).length;
+  return {
+    sections,
+    facts: factRows.length,
+    open,
+    needsClient: Math.max(needsClient, 0),
+    doneWhen: { done, of: items.length, items: items.map((l) => ({ done: /\[[xX]\]/.test(l), says: l.replace(/^\s*[-*]\s+\[[ xX]\]\s*/, '').trim() })) },
+  };
+}
+
+/** The lines of a section that carry words: not blank, not a table's header or its separator. */
+function rowsOf(body) {
+  const out = [];
+  for (let i = 0; i < body.length; i++) {
+    const line = body[i];
+    if (line.trim() === '') continue;
+    if (/^\|?\s*:?-+:?\s*\|/.test(line)) continue;
+    if (/^\|/.test(line) && /^\|?\s*:?-+:?\s*\|/.test(body[i + 1] ?? '')) continue;
+    out.push(line);
+  }
+  return out;
+}
+
+async function readFacts(file) {
+  let text;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  return { placeholders: (text.match(/\{\{[A-Z_]+\}\}/g) ?? []).length };
+}
+
+function fieldsOf(catalogue) {
+  const byType = new Map();
+  for (const block of catalogue?.blocks ?? []) {
+    byType.set(block.type, block.fields ?? []);
+  }
+  return byType;
+}
+
+/** How much of a document is written: the text fields filled, the required ones missing, the pictures in it. */
+function countFields(page, fields, rule) {
+  let filled = 0;
+  let of = 0;
+  let requiredMissing = 0;
+  let media = 0;
+  for (const block of page.blocks ?? []) {
+    const defs = fields.get(block.type);
+    if (rule === 'exact' && defs !== undefined) {
+      for (const def of defs) {
+        if (def.kind === 'media') {
+          if (hasText(block[def.key]) || (Array.isArray(block[def.key]) && block[def.key].length > 0)) media++;
+          continue;
+        }
+        if (!TEXT.has(def.kind)) continue;
+        of++;
+        if (hasText(block[def.key])) filled++;
+        else if (def.required) requiredMissing++;
+      }
+      continue;
+    }
+    // The weaker rule, with no catalogue to say what a field is: every
+    // string is words unless its name or its value says it is an address
+    // or a picture.
+    for (const [key, value] of Object.entries(block)) {
+      if (key === '_key' || key === 'type' || key === 'v') continue;
+      if (typeof value !== 'string') continue;
+      if (NOT_WORDS.test(key)) {
+        if (hasText(value) && /image|picture|photo|media|video/.test(key)) media++;
+        continue;
+      }
+      if (/^(https?:|#|\/)/.test(value)) continue;
+      of++;
+      if (hasText(value)) filled++;
+    }
+  }
+  return { filled, of, requiredMissing, media };
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+async function readJSON(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function contentFiles(dir) {
+  const out = [];
+  let names;
+  try {
+    names = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const one of names) {
+    const path = join(dir, one.name);
+    if (one.isDirectory()) out.push(...(await contentFiles(path)));
+    else if (one.name.endsWith('.json')) out.push(path);
+  }
+  return out;
+}
+
+/** The list as a person reads it in a terminal. */
+export function sayProgress(progress) {
+  const lines = [];
+  if (progress.brief === null) lines.push('brief: not written');
+  else {
+    const b = progress.brief;
+    lines.push(`brief: ${b.facts} fact(s), ${b.open} open for the client, done when ${b.doneWhen.done}/${b.doneWhen.of}`);
+  }
+  lines.push(`catalogue: ${progress.catalogue ? 'written' : 'not yet'}`);
+  for (const page of progress.pages) {
+    lines.push(`${page.written ? 'ok   ' : 'todo '}${page.path}  ${page.filled}/${page.of} fields${page.missing ? `, ${page.missing} required missing` : ''}`);
+  }
+  for (const [name, one] of Object.entries(progress.collections)) {
+    lines.push(`${one.entries >= one.expected ? 'ok   ' : 'todo '}${name}: ${one.entries} entr${one.entries === 1 ? 'y' : 'ies'}${one.expected ? ` (≥ ${one.expected})` : ''}`);
+  }
+  if (progress.settings) lines.push(`settings: hours ${progress.settings.hours ? 'set' : 'not set'}, zone ${progress.settings.zone ? 'set' : 'not set'}`);
+  lines.push(`pictures: ${progress.media}`);
+  lines.push('');
+  if (progress.missing.length === 0) lines.push('nothing missing — judge it, push, attach, build');
+  else {
+    lines.push('missing:');
+    for (const one of progress.missing) lines.push(`  - ${one}`);
+  }
+  return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtakeit/kit",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -51,7 +51,19 @@
       "default": "./elements/alive.js"
     },
     "./booking.css": "./booking.css",
-    "./lead.css": "./lead.css"
+    "./lead.css": "./lead.css",
+    "./lint": {
+      "types": "./types/lint.d.ts",
+      "default": "./lib/lint.mjs"
+    },
+    "./progress": {
+      "types": "./types/progress.d.ts",
+      "default": "./lib/progress.mjs"
+    },
+    "./content": {
+      "types": "./types/content.d.ts",
+      "default": "./lib/content.mjs"
+    }
   },
   "files": [
     "index.mjs",
@@ -68,7 +80,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jtakeit/jtakeit-kit.git",
+    "url": "git+https://github.com/jtakeit/jtakeit-kit.git",
     "directory": "kit"
   },
   "keywords": [

package/types/content.d.ts

@@ -0,0 +1,9 @@
+/** The published content as one document, from the files in `jtk/` — what the build renders from. */
+export function collectContent(root: string, options?: { dir?: string }): Promise<{
+  schema_version: number;
+  content_rev: number;
+  site: { slug: string; locale: string; media_base: string; business: Record<string, unknown> };
+  pages: { path: string; seo: Record<string, unknown>; blocks: Record<string, unknown>[]; collection?: string; visible?: boolean }[];
+  shared?: { locale?: string; blocks: Record<string, unknown>[] }[];
+}>;
+export function sharedLocaleOf(name: string): string | null;

package/types/lint.d.ts

@@ -0,0 +1,19 @@
+export interface Finding { code: string; says: string }
+export interface Verdict { findings: Finding[]; ok: boolean; pages: number; shared: boolean; line: string }
+export interface LintOptions {
+  /** The site's root, holding `jtk/`; the working directory by default. */
+  root?: string;
+  /** The built pages; `dist` under the root by default. */
+  dist?: string;
+  /** The address the build is for (`SITE_URL`); empty skips the host checks. */
+  siteURL?: string;
+  catalogue?: unknown;
+  content?: unknown;
+}
+/** The annotation lint the platform's build runs: the built pages against the content and the catalogue. */
+export function lint(options?: LintOptions): Promise<Verdict>;
+/** Print the findings the way the build does; 0 when clean, 1 otherwise. */
+export function lintCommand(options?: LintOptions): Promise<number>;
+export const TAPPABLE: Set<string>;
+export const CODES: Readonly<Record<string, string>>;
+export function said(code: string, message: string): string;

package/types/progress.d.ts

@@ -0,0 +1,50 @@
+/** The brief's headings, in the order the guide writes them. */
+export const BRIEF_SECTIONS: readonly string[];
+
+export interface BriefRead {
+  /** Which sections have words in them. */
+  sections: Record<string, boolean>;
+  /** Rows in the Facts table. */
+  facts: number;
+  /** Items under «Open — NEEDS CLIENT». */
+  open: number;
+  /** How often `NEEDS CLIENT` appears outside its heading. */
+  needsClient: number;
+  /** The agent's own checklist under «Done when» — read out, never believed. */
+  doneWhen: { done: number; of: number; items: { done: boolean; says: string }[] };
+}
+
+export interface PageProgress {
+  path: string;
+  /** Written: some text, and every required text field filled (the exact rule); or any text (has-text). */
+  written: boolean;
+  filled: number;
+  of: number;
+  /** Required text fields still empty, under the exact rule. */
+  missing?: number;
+}
+
+export interface Progress {
+  version: 1;
+  /** `exact` with a catalogue, `has-text` without one — a weaker rule, said as such. */
+  rule: 'exact' | 'has-text';
+  kit: { kind: string; version: string } | null;
+  brief: BriefRead | null;
+  catalogue: boolean;
+  pages: PageProgress[];
+  collections: Record<string, { entries: number; expected: number }>;
+  settings: { hours: boolean; zone: boolean; payment: string } | null;
+  facts: { placeholders: number } | null;
+  media: number;
+  /** What is still to do, as sentences — the same list the panel shows. */
+  missing: string[];
+  /** The newest change among the files read, ISO 8601; null when none exist. */
+  changedAt: string | null;
+}
+
+/** Read the working tree and say where the site is. */
+export function readProgress(root: string, options?: { dir?: string }): Promise<Progress>;
+/** The brief as a document, or null where there is none. */
+export function readBrief(file: string): Promise<BriefRead | null>;
+/** The list as a person reads it in a terminal. */
+export function sayProgress(progress: Progress): string;