@dmthepm/commune 0.2.0 → 0.4.0

package/lib/cli/related.js

@@ -12,15 +12,19 @@
  *
  * Fuzzy and semantic similarity are out of scope on purpose. They are product
  * direction, not a build decision, and inventing a ranking here would freeze it
- * into the contract before anyone chose it.
+ * into the contract before anyone chose it. What #69 added is not similarity:
+ * whitespace inside a name is not information, so a dictated "noon tide" and a
+ * written `Noontide` are the same name spelled two ways, and matching them is
+ * still an exact match — just of the right string.
  */
-import { readFile, stat } from 'node:fs/promises';
-import path from 'node:path';
-import matter from 'gray-matter';
 import { buildGraph, buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, stripCode, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./render.js";
-import { EXIT_OK, failure } from "./errors.js";
-/** Shortest name worth matching. Below this, a mention is noise. */
+import { SCHEMA, writeJson, writeLines } from "./output.js";
+import { EXIT_OK } from "./errors.js";
+import { readSource } from "./source.js";
+/**
+ * Shortest name worth matching, measured after normalisation. Below this, a
+ * mention is noise — `B` would make every capital B a connection.
+ */
 const MIN_MENTION_LENGTH = 3;
 function toReference(entry) {
     return {
@@ -30,78 +34,73 @@ function toReference(entry) {
         file: entry.file,
     };
 }
+const WHITESPACE = /\s/;
+const WORD = /\w/;
 /**
- * Work out whether the positional is a path, stdin, or literal prose.
+ * Reduce a string to the form mentions are matched in.
+ *
+ * Whitespace is removed rather than collapsed, which is what makes "noon tide"
+ * and `Noontide` the same string — the distortion dictation reliably produces
+ * (#69), and the reason a whole-word matcher over the raw text missed the
+ * titles it most needed to find. The offsets are what keep the answer honest:
+ * the word boundaries removed *inside* a name are still there in the original
+ * at its *edges*, so `Cake` can be found in "pan cake" and refused in
+ * "pancake".
  *
- * A path is tried against the root before the cwd, because the root is the
- * vault being asked about and the cwd is wherever the operator happens to be
- * standing. `-` is stdin, which is how a draft that is not a file yet gets
- * asked "what does this connect to".
+ * Built one output character at a time because `toLowerCase()` is not always
+ * length-preserving (`'İ'.toLowerCase()` is two code units), and one offset per
+ * emitted unit is what keeps the map exact for any input.
  */
-async function readSource(input, root) {
-    if (input === '-') {
-        const text = await readStdin();
-        const { content, data } = matter(text);
-        return { kind: 'stdin', text: content, frontmatter: data };
-    }
-    const candidates = path.isAbsolute(input)
-        ? [input]
-        : [path.join(root, input), path.resolve(input)];
-    for (const candidate of candidates) {
-        if (!(await isFile(candidate)))
+function normalize(text) {
+    let normalized = '';
+    const offsets = [];
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (WHITESPACE.test(char))
             continue;
-        let source;
-        try {
-            source = await readFile(candidate, 'utf8');
-        }
-        catch (error) {
-            throw failure('EPARSE', `cannot read ${candidate}: ${error.message}`);
+        const lowered = char.toLowerCase();
+        for (let unit = 0; unit < lowered.length; unit += 1) {
+            normalized += lowered[unit];
+            offsets.push(index);
         }
-        let parsed;
-        try {
-            parsed = matter(source);
-        }
-        catch (error) {
-            throw failure('EPARSE', `cannot parse frontmatter in ${candidate}: ${error.message}`);
-        }
-        const relative = path.relative(root, candidate).split(path.sep).join('/');
-        return {
-            kind: 'file',
-            file: relative,
-            text: parsed.content,
-            frontmatter: parsed.data,
-        };
     }
-    return { kind: 'text', text: input, frontmatter: {} };
-}
-async function isFile(candidate) {
-    try {
-        return (await stat(candidate)).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString('utf8');
-}
-/** Escape a title so it can be matched literally: real titles contain `,`, `'`, `(`. */
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return { text: normalized, offsets };
 }
 /**
- * Count whole-word occurrences of `name` in `text`.
+ * Find every whole-word occurrence of `name`, across whitespace and case.
  *
- * Lookarounds rather than `\b`, because `\b` is defined relative to the
- * character next to it: a title ending in `?` or `)` puts a non-word character
- * where `\b` expects a word one, and the match silently stops happening.
+ * The search runs on the normalised text and the boundary check on the original,
+ * because the two questions want different strings: "is this the same name"
+ * ignores the spaces, "is this a whole word" is only about the characters
+ * outside it. A character index either side is enough — `\w` is asked directly
+ * rather than through `\b`, which is defined relative to its neighbour and so
+ * silently stops matching a title that ends in `?` or `)`.
  */
-function countMentions(text, name) {
-    const pattern = new RegExp(`(?<!\\w)${escapeRegExp(name)}(?!\\w)`, 'gi');
-    return text.match(pattern)?.length ?? 0;
+function findMentions(prose, haystack, name) {
+    const needle = normalize(name).text;
+    if (needle.length < MIN_MENTION_LENGTH)
+        return { count: 0 };
+    let count = 0;
+    let matched;
+    for (let at = haystack.text.indexOf(needle); at !== -1; at = haystack.text.indexOf(needle, at + 1)) {
+        const start = haystack.offsets[at];
+        const end = haystack.offsets[at + needle.length - 1];
+        if (WORD.test(prose[start - 1] ?? ''))
+            continue;
+        if (WORD.test(prose[end + 1] ?? ''))
+            continue;
+        count += 1;
+        // The surface form, not the title: the connect step offers the candidate
+        // back with the words Devon actually said, so he can see which phrase in
+        // his dump the link would replace. Lowercased because that is what the
+        // field has always carried, and case is not what distinguishes one
+        // surface form from another here.
+        matched ??= prose
+            .slice(start, end + 1)
+            .toLowerCase()
+            .replace(/\s+/g, ' ');
+    }
+    return { count, matched };
 }
 export async function relatedCommand(root, input, json) {
     const entries = await loadContentEntries({ root });
@@ -109,7 +108,7 @@ export async function relatedCommand(root, input, json) {
     const byName = buildLinkLookup(entries);
     const byUrl = buildUrlLookup(entries);
     const byUrlPath = new Map(entries.map((entry) => [entry.urlPath, entry]));
-    const source = await readSource(input, root);
+    const source = await readSource(input, root, { allowText: true });
     // A file that happens to be a graph entry gets its inbound links too; a
     // draft outside the vault, or raw text, has none by definition.
     const self = source.file ? entries.find((entry) => entry.file === source.file) : undefined;
@@ -123,18 +122,18 @@ export async function relatedCommand(root, input, json) {
         };
     });
     const prose = stripCode(source.text);
+    const haystack = normalize(prose);
     const mentions = entries
         .filter((entry) => entry.urlPath !== self?.urlPath)
         .map((entry) => {
-        const names = [entry.title, ...entry.aliases].filter((name) => name.length >= MIN_MENTION_LENGTH);
         let count = 0;
         let matched;
-        for (const name of names) {
-            const hits = countMentions(prose, name);
-            if (!hits)
+        for (const name of [entry.title, ...entry.aliases]) {
+            const hits = findMentions(prose, haystack, name);
+            if (!hits.count)
                 continue;
-            count += hits;
-            matched ??= name.toLowerCase();
+            count += hits.count;
+            matched ??= hits.matched;
         }
         return { ...toReference(entry), matched, count };
     })

package/lib/cli/render.d.ts

@@ -1,20 +1,22 @@
 /**
- * How a command's result reaches the caller.
+ * `commune render` — a draft as the site will render it.
  *
- * One rule, and everything else follows from it: in `--json` mode stdout holds
- * exactly one JSON document and nothing else. Progress, warnings and errors go
- * to stderr, so `commune check --json > findings.json` yields a parseable file
- * even on the run that fails.
- */
-import type { CliError } from './errors.ts';
-/** Every payload carries the contract version, so #10's skills can pin it. */
-export declare const SCHEMA = 1;
-export declare function writeJson(payload: unknown): void;
-export declare function writeLines(lines: string[]): void;
-/**
- * Render a failure, on stderr, in whichever mode the caller asked for.
+ * The review surface the map listed as "not yet specified" needs one thing the
+ * rest of the CLI does not provide: the actual HTML, with `[[WikiLinks]]`
+ * resolved against the real content tree and external links marked, for a
+ * document that is not a page yet and may never be committed. Astro can produce
+ * that, but only by building the whole site, which is a per-turn cost nobody
+ * pays to look at one paragraph.
+ *
+ * So the pipeline is borrowed rather than reimplemented: `communeMarkdown` is
+ * the same processor `astro.config.mjs` hands to `markdown.processor`, and this
+ * verb drives it directly. The rule that keeps it honest is that this file adds
+ * no plugin, no option and no post-processing of its own — anything that made
+ * the CLI's HTML differ from the site's would make the review surface a liar.
  *
- * `json` is read from the raw argv rather than the parsed options, because the
- * errors most worth rendering as JSON are the ones thrown while parsing.
+ * `links` and `unresolved` come from the graph core rather than from the
+ * rendered tree. An unresolved wikilink renders as plain text on purpose, so by
+ * the time there is HTML the broken link is indistinguishable from a sentence,
+ * and the one thing a reviewer most needs to be told is gone.
  */
-export declare function writeError(error: CliError, json: boolean): void;
+export declare function renderCommand(root: string, input: string, siteFlag: string | undefined, json: boolean): Promise<number>;

package/lib/cli/render.js

@@ -1,32 +1,74 @@
 /**
- * How a command's result reaches the caller.
+ * `commune render` — a draft as the site will render it.
  *
- * One rule, and everything else follows from it: in `--json` mode stdout holds
- * exactly one JSON document and nothing else. Progress, warnings and errors go
- * to stderr, so `commune check --json > findings.json` yields a parseable file
- * even on the run that fails.
- */
-/** Every payload carries the contract version, so #10's skills can pin it. */
-export const SCHEMA = 1;
-export function writeJson(payload) {
-    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-}
-export function writeLines(lines) {
-    if (lines.length)
-        process.stdout.write(lines.join('\n') + '\n');
-}
-/**
- * Render a failure, on stderr, in whichever mode the caller asked for.
+ * The review surface the map listed as "not yet specified" needs one thing the
+ * rest of the CLI does not provide: the actual HTML, with `[[WikiLinks]]`
+ * resolved against the real content tree and external links marked, for a
+ * document that is not a page yet and may never be committed. Astro can produce
+ * that, but only by building the whole site, which is a per-turn cost nobody
+ * pays to look at one paragraph.
+ *
+ * So the pipeline is borrowed rather than reimplemented: `communeMarkdown` is
+ * the same processor `astro.config.mjs` hands to `markdown.processor`, and this
+ * verb drives it directly. The rule that keeps it honest is that this file adds
+ * no plugin, no option and no post-processing of its own — anything that made
+ * the CLI's HTML differ from the site's would make the review surface a liar.
  *
- * `json` is read from the raw argv rather than the parsed options, because the
- * errors most worth rendering as JSON are the ones thrown while parsing.
+ * `links` and `unresolved` come from the graph core rather than from the
+ * rendered tree. An unresolved wikilink renders as plain text on purpose, so by
+ * the time there is HTML the broken link is indistinguishable from a sentence,
+ * and the one thing a reviewer most needs to be told is gone.
  */
-export function writeError(error, json) {
+import { communeMarkdown } from "../markdown.js";
+import { buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, } from "../lib/graph.js";
+import { SCHEMA, writeJson } from "./output.js";
+import { EXIT_OK } from "./errors.js";
+import { readSource } from "./source.js";
+import { resolveSite } from "./site.js";
+export async function renderCommand(root, input, siteFlag, json) {
+    // Read before anything else: `-` has to consume stdin before a slow scan of
+    // the content tree, or a producer writing into the pipe waits on us.
+    const source = await readSource(input, root, { allowText: false });
+    const { site, source: siteSource } = await resolveSite(siteFlag, root);
+    if (siteSource === 'default') {
+        // On stderr, and only when nothing named an origin: `site` decides which
+        // links are the wiki's own, so a caller who did not supply one is
+        // looking at every absolute link marked external and deserves to know
+        // why. In `--json` the field says it too, without the noise.
+        process.stderr.write(`commune: no --site and none found in the Astro config; rendering against ${site}, ` +
+            `so every absolute link counts as external\n`);
+    }
+    const entries = await loadContentEntries({ root });
+    const byName = buildLinkLookup(entries);
+    const byUrl = buildUrlLookup(entries);
+    const byUrlPath = new Map(entries.map((entry) => [entry.urlPath, entry]));
+    const links = extractLinks(source.text, source.frontmatter).map((link) => {
+        const target = resolveLink(link, byName, byUrl);
+        const entry = target ? byUrlPath.get(target.urlPath) : undefined;
+        return {
+            kind: link.kind,
+            target: link.target,
+            resolved: entry
+                ? { urlPath: entry.urlPath, title: entry.title, collection: entry.collection }
+                : null,
+        };
+    });
+    const renderer = await communeMarkdown({ site, root }).createRenderer({});
+    const { code } = await renderer.render(source.text, { frontmatter: source.frontmatter });
     if (json) {
-        process.stderr.write(JSON.stringify({ error: { code: error.code, message: error.message } }, null, 2) + '\n');
-        return;
+        writeJson({
+            schema: SCHEMA,
+            root,
+            site,
+            source: { kind: source.kind, ...(source.file ? { file: source.file } : {}) },
+            html: code,
+            links,
+            // The projection a reviewer acts on: the names in the draft that
+            // point at nothing, which the HTML has already turned into prose.
+            unresolved: links.filter((link) => !link.resolved).map((link) => link.target),
+        });
+        return EXIT_OK;
     }
-    process.stderr.write(`commune: ${error.message}\n`);
-    if (error.detail)
-        process.stderr.write(`${error.detail}\n`);
+    process.stdout.write(code.endsWith('\n') ? code : `${code}\n`);
+    return EXIT_OK;
 }

package/lib/cli/site.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Finding the site's own origin, without starting Astro.
+ *
+ * `site` is what tells the rehype plugin which links are the wiki's own, so
+ * rendering with the wrong one marks every internal absolute link as external.
+ * The value lives in the consumer's `astro.config.*` — but importing that file
+ * would load Astro, the integrations and whatever else the config pulls in,
+ * which is exactly the process this CLI exists to avoid, and would execute the
+ * consumer's code to answer a question about a string.
+ *
+ * So the config is read as text and searched for the two spellings that
+ * actually occur: the property inside `defineConfig`, and the `const` above it
+ * that the property is a shorthand for. Both real wikis use the second. This is
+ * a best effort by construction: `--site` overrides it, and when neither
+ * produces an answer the fallback is announced on stderr rather than assumed.
+ */
+/**
+ * The origin used when nothing else names one.
+ *
+ * A reserved example domain, so a link to it can never collide with a real
+ * host: with this in force, every absolute link renders as external, which is
+ * the safe way to be wrong.
+ */
+export declare const DEFAULT_SITE = "https://example.com";
+export type SiteSource = 'flag' | 'config' | 'default';
+export interface ResolvedSite {
+    site: string;
+    source: SiteSource;
+}
+export declare function resolveSite(flag: string | undefined, root: string): Promise<ResolvedSite>;

package/lib/cli/site.js

@@ -0,0 +1,57 @@
+/**
+ * Finding the site's own origin, without starting Astro.
+ *
+ * `site` is what tells the rehype plugin which links are the wiki's own, so
+ * rendering with the wrong one marks every internal absolute link as external.
+ * The value lives in the consumer's `astro.config.*` — but importing that file
+ * would load Astro, the integrations and whatever else the config pulls in,
+ * which is exactly the process this CLI exists to avoid, and would execute the
+ * consumer's code to answer a question about a string.
+ *
+ * So the config is read as text and searched for the two spellings that
+ * actually occur: the property inside `defineConfig`, and the `const` above it
+ * that the property is a shorthand for. Both real wikis use the second. This is
+ * a best effort by construction: `--site` overrides it, and when neither
+ * produces an answer the fallback is announced on stderr rather than assumed.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The origin used when nothing else names one.
+ *
+ * A reserved example domain, so a link to it can never collide with a real
+ * host: with this in force, every absolute link renders as external, which is
+ * the safe way to be wrong.
+ */
+export const DEFAULT_SITE = 'https://example.com';
+const CONFIG_FILES = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts'];
+/** `site: 'https://…'` inside the config object, or `const site = 'https://…'` above it. */
+const SITE_PATTERNS = [/\bsite\s*:\s*['"`]([^'"`]+)['"`]/, /\bsite\s*=\s*['"`]([^'"`]+)['"`]/];
+/** Read `site` out of a project's Astro config, if it declares one this way. */
+async function readSiteFromConfig(root) {
+    for (const name of CONFIG_FILES) {
+        let source;
+        try {
+            source = await readFile(path.join(root, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of SITE_PATTERNS) {
+            const value = pattern.exec(source)?.[1];
+            // Only a real origin: `site: undefined` and a templated string are
+            // both better answered by the default than by a guess.
+            if (value && URL.canParse(value))
+                return value;
+        }
+    }
+    return undefined;
+}
+export async function resolveSite(flag, root) {
+    if (flag !== undefined)
+        return { site: flag, source: 'flag' };
+    const configured = await readSiteFromConfig(root);
+    if (configured !== undefined)
+        return { site: configured, source: 'config' };
+    return { site: DEFAULT_SITE, source: 'default' };
+}

package/lib/cli/source.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a verb's markdown comes from: a file, stdin, or the argument itself.
+ *
+ * One reader for `graph related` and `render`, because they take the same
+ * positional and have to agree about what it means — including the part that is
+ * easy to get subtly different, which is that a path is tried against `--root`
+ * before the cwd. The root is the vault being asked about; the cwd is wherever
+ * the operator happens to be standing.
+ *
+ * The one difference between the two callers is what a string that names no
+ * file means. `graph related` answers questions about prose, so it is text.
+ * `render` renders a document, and a mistyped path silently rendering as its
+ * own filename would be a wrong answer with no error anywhere, so it fails.
+ */
+export interface Source {
+    kind: 'file' | 'text' | 'stdin';
+    /** Root-relative and POSIX-separated, for a file. */
+    file?: string;
+    /** The markdown body, with any frontmatter split off. */
+    text: string;
+    frontmatter: Record<string, unknown>;
+}
+export interface ReadSourceOptions {
+    /** Whether a string naming no file is prose (`graph related`) or an error (`render`). */
+    allowText: boolean;
+}
+/**
+ * Resolve the positional into markdown and its frontmatter.
+ *
+ * `-` is stdin, which is how a draft that is not a file yet gets asked about —
+ * and it is frontmatter-aware there too, so piping a whole note in behaves the
+ * same as naming it.
+ */
+export declare function readSource(input: string, root: string, { allowText }: ReadSourceOptions): Promise<Source>;

package/lib/cli/source.js

@@ -0,0 +1,74 @@
+/**
+ * Where a verb's markdown comes from: a file, stdin, or the argument itself.
+ *
+ * One reader for `graph related` and `render`, because they take the same
+ * positional and have to agree about what it means — including the part that is
+ * easy to get subtly different, which is that a path is tried against `--root`
+ * before the cwd. The root is the vault being asked about; the cwd is wherever
+ * the operator happens to be standing.
+ *
+ * The one difference between the two callers is what a string that names no
+ * file means. `graph related` answers questions about prose, so it is text.
+ * `render` renders a document, and a mistyped path silently rendering as its
+ * own filename would be a wrong answer with no error anywhere, so it fails.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { failure } from "./errors.js";
+async function isFile(candidate) {
+    try {
+        return (await stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Resolve the positional into markdown and its frontmatter.
+ *
+ * `-` is stdin, which is how a draft that is not a file yet gets asked about —
+ * and it is frontmatter-aware there too, so piping a whole note in behaves the
+ * same as naming it.
+ */
+export async function readSource(input, root, { allowText }) {
+    if (input === '-') {
+        const { content, data } = matter(await readStdin());
+        return { kind: 'stdin', text: content, frontmatter: data };
+    }
+    const candidates = path.isAbsolute(input) ? [input] : [path.join(root, input), path.resolve(input)];
+    for (const candidate of candidates) {
+        if (!(await isFile(candidate)))
+            continue;
+        let source;
+        try {
+            source = await readFile(candidate, 'utf8');
+        }
+        catch (error) {
+            throw failure('EPARSE', `cannot read ${candidate}: ${error.message}`);
+        }
+        let parsed;
+        try {
+            parsed = matter(source);
+        }
+        catch (error) {
+            throw failure('EPARSE', `cannot parse frontmatter in ${candidate}: ${error.message}`);
+        }
+        return {
+            kind: 'file',
+            file: path.relative(root, candidate).split(path.sep).join('/'),
+            text: parsed.content,
+            frontmatter: parsed.data,
+        };
+    }
+    if (!allowText) {
+        throw failure('EPARSE', `cannot read ${input}: no such file under ${root} or the cwd`);
+    }
+    return { kind: 'text', text: input, frontmatter: {} };
+}

package/lib/cli/update.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `commune update` — a dated update entry, scaffolded from what changed.
+ *
+ * The one verb here that can write. Everything else in this CLI answers
+ * questions about a content tree; this one drafts a file into it, so the
+ * writing is opt-in: without `--write` it prints the entry on stdout, which is
+ * both a preview and a redirect away from a file of your choosing. With
+ * `--write` it refuses to overwrite an existing entry — a scaffold that
+ * clobbers a day's writing is worse than no scaffold.
+ *
+ * What it produces is a draft and says so: `summary` is empty, because a
+ * one-line summary of a week is a judgement and this command has no taste.
+ * The parts it can be trusted with — which pages moved, what they are called,
+ * what date it is — are filled in.
+ */
+export declare function updateCommand(root: string, since: string, day: string, write: boolean, json: boolean): Promise<number>;

package/lib/cli/update.js

@@ -0,0 +1,91 @@
+/**
+ * `commune update` — a dated update entry, scaffolded from what changed.
+ *
+ * The one verb here that can write. Everything else in this CLI answers
+ * questions about a content tree; this one drafts a file into it, so the
+ * writing is opt-in: without `--write` it prints the entry on stdout, which is
+ * both a preview and a redirect away from a file of your choosing. With
+ * `--write` it refuses to overwrite an existing entry — a scaffold that
+ * clobbers a day's writing is worse than no scaffold.
+ *
+ * What it produces is a draft and says so: `summary` is empty, because a
+ * one-line summary of a week is a judgement and this command has no taste.
+ * The parts it can be trusted with — which pages moved, what they are called,
+ * what date it is — are filled in.
+ */
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CONTENT_DIRS, loadContentEntries } from "../lib/graph.js";
+import { SCHEMA, writeJson, writeLines } from "./output.js";
+import { EXIT_OK, failure } from "./errors.js";
+/**
+ * The entry, as markdown.
+ *
+ * `links:` carries the urlPaths and the body carries the titles, which is the
+ * same edge written twice on purpose: the frontmatter is what the graph reads
+ * without rendering anything, and the prose is what a reader reads. They
+ * deduplicate into one edge, so writing both costs nothing.
+ */
+function scaffold(day, changed) {
+    const lines = [
+        '---',
+        `title: "Updates for ${day}"`,
+        `date: ${day}`,
+        'summary: ""',
+        'aiGenerated: false',
+    ];
+    if (changed.length) {
+        lines.push('links:', ...changed.map((entry) => `  - ${entry.urlPath}`));
+    }
+    lines.push('---', '');
+    lines.push(...(changed.length
+        ? changed.map((entry) => `- [[${entry.title}]]${entry.summary ? ` — ${entry.summary}` : ''}`)
+        : ['Nothing changed in this window.']));
+    return `${lines.join('\n')}\n`;
+}
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function updateCommand(root, since, day, write, json) {
+    const entries = await loadContentEntries({ root });
+    // Updates are excluded from their own roll-up: an update that lists last
+    // week's update says nothing about the wiki.
+    const changed = entries.filter((entry) => entry.collection !== 'updates' && entry.updated !== undefined && entry.updated >= since);
+    const file = `${CONTENT_DIRS.updates}/${day}.md`;
+    const content = scaffold(day, changed);
+    if (write) {
+        const destination = path.join(root, file);
+        if (await exists(destination)) {
+            throw failure('EEXISTS', `${file} already exists. Edit it, or delete it first — this command does not overwrite an update that has been written.`);
+        }
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, content);
+    }
+    if (json) {
+        writeJson({
+            schema: SCHEMA,
+            root,
+            since,
+            date: day,
+            file,
+            written: write,
+            entries: changed.map((entry) => ({
+                urlPath: entry.urlPath,
+                title: entry.title,
+                collection: entry.collection,
+                updated: entry.updated,
+                updatedSource: entry.updatedSource,
+            })),
+            content,
+        });
+        return EXIT_OK;
+    }
+    writeLines(write ? [`wrote ${file} — ${changed.length} entries since ${since}`] : [content.trimEnd()]);
+    return EXIT_OK;
+}