@wxxb789/anc 0.0.1

package/scripts/generate-corpus.js

@@ -0,0 +1,421 @@
+/**
+ * A synthetic notes repository of any size, deterministic from a seed.
+ *
+ * This exists because every performance claim in this project was made against
+ * a 32-note fixture. A benchmark needs a corpus large enough to be evidence, and
+ * a corpus of 10,000 identical notes is evidence of nothing: it collapses link
+ * resolution to one bucket, gives Pagefind one document repeated, and hides
+ * every cost that scales with *variety* rather than with count.
+ *
+ * So the shape below is chosen for what it stresses, and each choice is stated
+ * where it is made. What matters most:
+ *
+ * - **The link graph is skewed, not uniform.** Most notes link a few others; a
+ *   small number are hubs linking dozens. A uniform graph makes every backlink
+ *   list the same length, and the one thing a backlink derivation can be
+ *   quadratic in is a hub's in-degree.
+ * - **Basenames collide across directories.** Link resolution buckets by
+ *   lowercase basename, so a corpus of unique names never leaves tier 1 and
+ *   never measures tiers 2 through 5. See {@link BASENAME_POOL}.
+ * - **All five link forms appear**, because they take different paths through
+ *   `resolveLink` — a wikilink is not percent-decoded, a rooted link can end
+ *   resolution at tier 4, and a relative link rewrites its path before tiers 3
+ *   and 5 see it.
+ * - **Some links deliberately do not resolve.** A corpus where every link works
+ *   never exercises the degrade-to-text rewrite, which is the branch that
+ *   allocates.
+ *
+ * ## Workload options
+ *
+ * The defaults are the original corpus — the skewed graph above and no
+ * metadata — so an existing caller's bytes are unchanged. Two alternatives
+ * exist for the benchmark workloads. `topology: 'sparse'` removes the skew
+ * entirely: every note links one or two others and no note is a hub, which is
+ * what lets a measurement separate a cost that follows the graph shape from
+ * one that follows the note count. `metadata: true` gives every note
+ * frontmatter — three tags, at least one CJK, and a per-note alias — and every
+ * 25th note a mixed CJK/Latin heading, which is what a tag, alias, or
+ * non-ASCII search measurement needs. Neither option makes an unseeded choice,
+ * so either corpus is as reproducible as the default.
+ *
+ * ## Nothing here names this project or this repository
+ *
+ * The tool is not for one person, so a fixture that encodes this repository's
+ * layout measures this repository rather than the product. The vocabulary below
+ * is deliberately generic — weather, terrain, and materials — and the directory
+ * names are the shapes a notes repository generally has rather than the ones
+ * this one does. A corpus is written to a caller-supplied directory, never
+ * inside the repository.
+ *
+ * ## Determinism
+ *
+ * One seeded generator drives every choice, and the same seed and count produce
+ * byte-identical files. That is what makes two benchmark runs comparable: a
+ * corpus that varied between runs would put its own variance into every
+ * measurement taken over it.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/**
+ * A small, fast, seeded PRNG (mulberry32).
+ *
+ * `Math.random` is unseedable, so it cannot produce the same corpus twice, and
+ * a benchmark over a corpus that changes per run measures the corpus as much as
+ * the code. Twelve lines of arithmetic rather than a dependency: the statistical
+ * quality needed here is "spreads out and repeats", which this clears easily and
+ * which no property of the benchmark depends on beyond reproducibility.
+ */
+function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Directory names a notes repository plausibly has.
+ *
+ * Depth matters to resolution rather than to taste: tier 2 joins a relative
+ * link onto the source's directory and tier 5 prefers candidates inside the
+ * source's subtree, so a flat corpus leaves both inert. The nested entries here
+ * are what give those tiers something to prefer.
+ */
+const DIRECTORIES = [
+    '',
+    'notes',
+    'notes/daily',
+    'notes/reference',
+    'projects',
+    'projects/archive',
+    'reading',
+    'reading/papers',
+    'inbox',
+];
+/**
+ * The word pool every generated name and body is built from.
+ *
+ * Generic on purpose — see this file's header. Short and repetitive is also what
+ * a real search index sees: Pagefind's cost is dominated by the number of
+ * *distinct* terms, and a corpus of random unique strings would make its index
+ * enormous in a way no real corpus is.
+ */
+const WORDS = [
+    'quiet', 'harbor', 'rolling', 'field', 'still', 'water', 'copper', 'lantern',
+    'winter', 'thicket', 'shallow', 'creek', 'northern', 'ridge', 'open', 'meadow',
+    'grey', 'stone', 'brief', 'thaw', 'salt', 'marsh', 'low', 'cloud',
+    'iron', 'gate', 'long', 'shadow', 'first', 'frost', 'pale', 'ember',
+];
+/**
+ * Basenames deliberately reused across directories.
+ *
+ * `indexCorpus` keys on the lowercase basename, so a corpus of globally unique
+ * filenames puts exactly one candidate in every bucket and every link resolves
+ * at tier 1 — the cheapest path, and the one that proves least. These names are
+ * the ones a real vault repeats in every folder, and each one that appears in
+ * two directories forces a link naming it through tiers 2 to 5 and makes it an
+ * `ambiguous` finding rather than a `resolved` one.
+ */
+const BASENAME_POOL = ['index', 'notes', 'readme', 'log', 'summary'];
+/** Non-Markdown files, which discovery counts and drops rather than reads. */
+const ASSET_EXTENSIONS = ['.png', '.pdf', '.txt', '.canvas', '.json'];
+/**
+ * How many of a note's own words become links, by note rank.
+ *
+ * A power-law-ish skew rather than a constant: in a real vault a handful of
+ * index notes link most of the corpus and the long tail links two or three
+ * things. The two ends cost differently — a hub's out-edges become every
+ * target's backlinks, so the hubs are what make backlink derivation expensive —
+ * and a uniform graph measures neither end.
+ *
+ * Sparse mode skips the skew rather than damping it: one or two links per note,
+ * drawn from the same seeded RNG, so a benchmark can tell a cost that follows
+ * the graph shape from one that follows the note count.
+ */
+function outDegreeFor(rank, total, random, topology) {
+    if (topology === 'sparse')
+        return 1 + Math.floor(random() * 2);
+    // The first 1% of notes are hubs. `Math.max(1, …)` so a tiny corpus still has
+    // one, which is what keeps a 100-note run comparable to a 10,000-note one
+    // rather than differing in kind.
+    const hubs = Math.max(1, Math.floor(total * 0.01));
+    if (rank < hubs)
+        return 20 + Math.floor(random() * 40);
+    if (rank < total * 0.1)
+        return 4 + Math.floor(random() * 6);
+    return Math.floor(random() * 4);
+}
+/**
+ * A note's body length in paragraphs, skewed the way real notes are.
+ *
+ * Most notes are short; a few are long. The long ones matter twice over: the
+ * Markdown renderer's cost is per byte, and `STRING_LIMITS.markdown` caps a note
+ * at 200,000 characters — so a corpus of uniformly short notes would never come
+ * near a limit the contract actually enforces.
+ */
+function paragraphsFor(random) {
+    const roll = random();
+    if (roll < 0.6)
+        return 1 + Math.floor(random() * 3);
+    if (roll < 0.95)
+        return 4 + Math.floor(random() * 10);
+    return 20 + Math.floor(random() * 40);
+}
+/** A sentence of pool words, capitalised. */
+function sentence(random, words) {
+    const picked = Array.from({ length: words }, () => WORDS[Math.floor(random() * WORDS.length)]);
+    const text = picked.join(' ');
+    return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
+/**
+ * Every note's path, decided before any body is written.
+ *
+ * Two passes are forced rather than chosen: a note's links name *other notes*,
+ * so the full path set has to exist before the first body can reference it.
+ * That mirrors the pipeline itself, where link resolution runs after the whole
+ * walk for the same reason.
+ */
+function planPaths(count, random) {
+    const paths = [];
+    const taken = new Set();
+    for (let index = 0; index < count; index += 1) {
+        let directory = DIRECTORIES[Math.floor(random() * DIRECTORIES.length)];
+        // One note in twelve takes a pooled basename, which is what puts more than
+        // one candidate in a resolution bucket. The rest get a unique name, so the
+        // corpus stays mostly unambiguous the way a real one is.
+        const pooled = random() < 1 / 12;
+        const stem = pooled
+            ? BASENAME_POOL[Math.floor(random() * BASENAME_POOL.length)]
+            : `${WORDS[Math.floor(random() * WORDS.length)]}-${WORDS[Math.floor(random() * WORDS.length)]}-${index}`;
+        // A pooled name is never placed at the corpus root, and this is a
+        // measurement rather than a preference: a root-level `notes.md` slugifies to
+        // `notes`, which is in `RESERVED_SLUGS`, and the contract refuses the whole
+        // artifact over it. That is a real defect in the product — a two-note
+        // repository containing `notes.md` does not build — but it is not a *scale*
+        // defect, and a benchmark that trips it measures nothing at any size. It is
+        // reported separately rather than worked around silently. Nesting is also
+        // the more realistic placement: a repeated basename is a folder index.
+        if (pooled && directory === '')
+            directory = DIRECTORIES[1];
+        let path = directory === '' ? `${stem}.md` : `${directory}/${stem}.md`;
+        // A pooled name can collide inside one directory, and two files at one path
+        // is one file. Disambiguating by index keeps the count exact while leaving
+        // the *cross-directory* collisions this pool exists to create.
+        if (taken.has(path))
+            path = path.replace(/\.md$/, `-${index}.md`);
+        taken.add(path);
+        paths.push(path);
+    }
+    return paths;
+}
+/** The relative path from one note's directory to another's, for tier 2. */
+function relativePath(from, to) {
+    const fromParts = from.split('/').slice(0, -1);
+    const toParts = to.split('/');
+    let shared = 0;
+    while (shared < fromParts.length && fromParts[shared] === toParts[shared])
+        shared += 1;
+    const up = Array.from({ length: fromParts.length - shared }, () => '..');
+    const down = toParts.slice(shared);
+    const joined = [...up, ...down].join('/');
+    // A path with no `../` prefix must still be written `./x` to be a *relative*
+    // link — without the prefix `isExternal` never sees one and tier 2 is skipped,
+    // so the form this branch exists to generate would not be generated.
+    return joined.startsWith('..') ? joined : `./${joined}`;
+}
+/**
+ * One link, in one of the five forms the resolver accepts.
+ *
+ * Rotated by index rather than chosen at random, so every form appears in
+ * proportion at any corpus size — a random choice would leave the rarest form
+ * absent from a 100-note run and present at 10,000, which is a difference
+ * between the two measurements that has nothing to do with scale.
+ *
+ * The `.md` extension is dropped from the wikilink forms because that is how
+ * they are written in practice, and tier 0 appends it.
+ */
+function linkTo(form, sourcePath, targetPath) {
+    const stem = targetPath.replace(/\.md$/, '');
+    const basename = stem.slice(stem.lastIndexOf('/') + 1);
+    switch (form % 5) {
+        case 0:
+            return `[[${basename}]]`;
+        case 1:
+            return `[[/${stem}]]`;
+        case 2:
+            return `[[${relativePath(sourcePath, stem)}]]`;
+        case 3:
+            // Percent-encoded, which is the only difference between a Markdown href
+            // and a wikilink anywhere in the resolver.
+            return `[a note](${encodeURI(relativePath(sourcePath, targetPath))})`;
+        default:
+            return `[[${basename}|see the other note]]`;
+    }
+}
+/**
+ * Topic tags a metadata note draws two of, rotated by its index.
+ *
+ * A small colliding pool rather than per-note unique tags: a tag query whose
+ * every answer is one note measures lookup, not grouping, and the generic
+ * vocabulary keeps a generated corpus from naming anyone (see the header).
+ */
+const TOPIC_TAGS = ['field-notes', 'gardening', 'journal', 'reference'];
+/** The CJK tag on every metadata note, so tag workloads include a non-ASCII key. */
+const CJK_TAG = '笔记';
+/**
+ * Mixed CJK/Latin headings for every 25th metadata note.
+ *
+ * A pool rather than one string so a search or preview workload has more than
+ * one non-ASCII title to tokenize. The first is the title the benchmark
+ * snapshot already uses, so both harnesses describe the same corpus shape.
+ */
+const CJK_TITLES = [
+    '星图与笔记：中英混排',
+    '潮汐名录：观测与记录',
+    '码头备忘：标点与行句',
+];
+/**
+ * Three deterministic tags for one note, the last CJK.
+ *
+ * `index % 4` and `(index + 1) % 4` can never agree, so the first two are
+ * distinct without a retry loop. See {@link TOPIC_TAGS}.
+ */
+function tagsFor(index) {
+    return [
+        TOPIC_TAGS[index % TOPIC_TAGS.length],
+        TOPIC_TAGS[(index + 1) % TOPIC_TAGS.length],
+        CJK_TAG,
+    ];
+}
+/** One note's Markdown, links included. */
+function noteBody(index, path, paths, random, withheld, topology, metadata) {
+    const generatedTitle = sentence(random, 3 + Math.floor(random() * 3)).replace(/\.$/, '');
+    // Frontmatter on roughly a third of notes, and on every withheld one. Parsing
+    // and stripping it is per-note work the walk pays for, and a corpus with none
+    // would leave `frontmatterOf` measuring its own early return. Drawn here even
+    // when metadata writes a block regardless, so metadata mode consumes the same
+    // RNG sequence and its bodies differ from the default only by that metadata.
+    const sampledFrontmatter = withheld || random() < 0.3;
+    // Every 25th metadata note gets a mixed-script heading. The sentence above is
+    // still generated and discarded, for the same sequence argument.
+    const title = metadata && index % 25 === 0
+        ? CJK_TITLES[Math.floor(index / 25) % CJK_TITLES.length]
+        : generatedTitle;
+    const lines = [];
+    if (sampledFrontmatter || metadata) {
+        lines.push('---');
+        if (withheld)
+            lines.push('publish: false');
+        else if (sampledFrontmatter)
+            lines.push(`title: ${title}`);
+        if (metadata) {
+            lines.push(`tags: [${tagsFor(index).join(', ')}]`);
+            lines.push(`aliases: ["alias-${index}"]`);
+        }
+        lines.push('---', '');
+    }
+    lines.push(`# ${title}`, '');
+    const degree = outDegreeFor(index, paths.length, random, topology);
+    for (let paragraph = 0, total = paragraphsFor(random); paragraph < total; paragraph += 1) {
+        const parts = [sentence(random, 6 + Math.floor(random() * 14))];
+        // Links are spread across the note's paragraphs rather than listed at the
+        // end, so the traversal's edits land throughout the body. `applyEdits`
+        // replaces spans last-to-first, and a body whose links all sit in one region
+        // would not exercise that ordering across a realistic span distribution.
+        if (paragraph < degree) {
+            let target = paths[Math.floor(random() * paths.length)];
+            // Sparse mode promises every note an out-edge, and a drawn self-target
+            // would silently delete one. Replacing rather than redrawing keeps the
+            // RNG count — and so the default mode's bytes — unchanged.
+            if (target === path && topology === 'sparse') {
+                for (let step = 1; step < paths.length; step += 1) {
+                    const candidate = paths[(index + step) % paths.length];
+                    if (candidate !== path) {
+                        target = candidate;
+                        break;
+                    }
+                }
+            }
+            if (target !== path)
+                parts.push(linkTo(index + paragraph, path, target));
+            // One link in twenty names nothing at all. This is the degrade-to-text
+            // branch, which allocates a replacement where a resolved link does not,
+            // and a corpus without it never runs.
+            if (random() < 0.05)
+                parts.push(`[[${WORDS[Math.floor(random() * WORDS.length)]}-${index}-absent]]`);
+        }
+        lines.push(parts.join(' '), '');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+/**
+ * Write a corpus of `notes` Markdown files, plus assets, into `directory`.
+ *
+ * The directory is the caller's to create and to clean up. Nothing is written
+ * anywhere else, and no path is derived from this repository's own layout.
+ */
+export async function generateCorpus(directory, options) {
+    const random = seededRandom(options.seed ?? 1);
+    const topology = options.topology ?? 'skewed';
+    const metadata = options.metadata ?? false;
+    const paths = planPaths(options.notes, random);
+    const result = {
+        files: 0,
+        published: 0,
+        withheld: 0,
+        assets: 0,
+        bytes: 0,
+    };
+    // Directories are created once rather than per file: `mkdir recursive` on
+    // 10,000 files is 10,000 syscalls measuring the filesystem instead of the
+    // build.
+    const created = new Set();
+    const ensure = async (path) => {
+        const parent = dirname(path);
+        if (created.has(parent))
+            return;
+        await mkdir(parent, { recursive: true });
+        created.add(parent);
+    };
+    for (const [index, path] of paths.entries()) {
+        // One note in twenty-five withholds itself. That exercises rank 1 of the
+        // exclusion precedence and, more usefully for a benchmark, creates link
+        // targets that resolve to a real file this build did not publish — the
+        // `unpublished` outcome, which is the branch that rewrites a label rather
+        // than just replacing a span.
+        const withheld = random() < 0.04;
+        const body = noteBody(index, path, paths, random, withheld, topology, metadata);
+        const destination = join(directory, path);
+        await ensure(destination);
+        await writeFile(destination, body, 'utf8');
+        result.files += 1;
+        result.bytes += Buffer.byteLength(body, 'utf8');
+        if (withheld)
+            result.withheld += 1;
+        else
+            result.published += 1;
+    }
+    // Assets at one per twenty notes, which is the order a notes repository runs
+    // at. They are discovered and dropped as `not-markdown`, and every one is
+    // offered to every exclusion pattern first — so they are not inert filler,
+    // they are what the pattern-matching loop actually spends its time on.
+    const assets = Math.max(1, Math.floor(options.notes / 20));
+    for (let index = 0; index < assets; index += 1) {
+        const directoryName = DIRECTORIES[Math.floor(random() * DIRECTORIES.length)];
+        const extension = ASSET_EXTENSIONS[index % ASSET_EXTENSIONS.length];
+        const name = `asset-${index}${extension}`;
+        const path = join(directory, directoryName === '' ? name : `${directoryName}/${name}`);
+        await ensure(path);
+        // Bytes rather than an empty file: discovery does not read a non-Markdown
+        // file, and an empty one would let a regression that started reading them
+        // go unmeasured.
+        const contents = `${sentence(random, 40)}\n`;
+        await writeFile(path, contents, 'utf8');
+        result.files += 1;
+        result.assets += 1;
+        result.bytes += Buffer.byteLength(contents, 'utf8');
+    }
+    return result;
+}

package/scripts/init-repository.js

@@ -0,0 +1,249 @@
+/**
+ * `anc init`: prepare a notes repository for its first build.
+ *
+ * Two writes, and the argument for the ticket is that both are things a user
+ * cannot discover by running the tool. A build tells you what it published; it
+ * does not tell you that `dist/` is about to be committed, and it does not tell
+ * you that the site it just built points at a loopback origin nobody can reach.
+ *
+ * ## What it does, and what it deliberately does not
+ *
+ * 1. **Seeds `.gitignore`.** {@link ensureIgnored} has shipped since TK-25 with
+ *    no caller — this is the caller. Everything about *how* to append to a
+ *    stranger's `.gitignore` lives there, including the four probe states and
+ *    the three measured ways to corrupt a working file.
+ * 2. **Writes a starter {@link CONFIG_FILENAME}, if there is not one already.**
+ *
+ * Three things the plan's §4.4 names for `init` are **not** written, each for a
+ * reason rather than for want of time:
+ *
+ * - **`.github/workflows/publish.yml`.** A workflow file names the action it
+ *   calls, as `uses: <owner>/<repo>@<commit-sha>`. This repository has no git remote, so
+ *   there is no such coordinate to write — `init` would put a `uses:` line
+ *   naming a repository that does not exist into a stranger's CI, which fails
+ *   on their first push with an error about *our* naming rather than about
+ *   anything they did. It also picks a deploy target for them; the zero-secret
+ *   GitHub Pages path is the documented default and Cloudflare is a supported
+ *   alternative, and a file `init` wrote is the worst place for that choice to
+ *   be made silently. `action.yml` at the root of this repository is the half
+ *   that can exist today, and it does.
+ * - **A starter about and privacy note.** §4.4 ties those to deleting
+ *   `src/pages/about.astro` and `privacy.astro`, which is not this ticket's
+ *   scope, and until that lands a seeded note would sit beside a shipped page
+ *   saying something different about the same subject.
+ * - **Prompts.** §4.4 has `init` fill `title` and `origin` from them. A prompt
+ *   is unanswerable in CI and in a non-interactive shell, and the file this
+ *   writes is one a user edits in the editor they already have open. What the
+ *   template must do instead is make the two keys impossible to miss, which is
+ *   what putting them first and commented does.
+ *
+ * ## Idempotence, which is the property that makes it safe to suggest
+ *
+ * A user will run this twice — after a failed first attempt, or because they
+ * forgot. `ensureIgnored` is idempotent by asking git rather than by searching
+ * for its own marker, so a user who edited or split the block still gets no
+ * duplicate. The config is idempotent by the blunter rule: **an existing file is
+ * never touched, whatever is in it.** Not "merged", not "updated", not
+ * "rewritten with the missing keys" — a configuration file is the one file in a
+ * notes repository whose contents are load-bearing for what stays private, and a
+ * tool that edits it is a tool that can silently drop an exclusion.
+ */
+import { existsSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CONFIG_FILENAME } from "./load-config.js";
+import { ensureIgnored } from "./seed-gitignore.js";
+import { BuildFailure } from "./write-report.js";
+/**
+ * The starter configuration, with every key commented out.
+ *
+ * **An entirely commented file and an absent file produce the same build**, and
+ * that is measured rather than assumed: `parseConfig` over this text returns
+ * `{title: 'Notes', exclude: []}`, byte-identical to what an empty string and a
+ * missing file return. So writing it changes nothing about the site, which is
+ * what makes writing it unconditionally safe — the file is a menu, not a
+ * configuration.
+ *
+ * The three keys are {@link KNOWN_KEYS} in the order `load-config.ts` documents
+ * them, and `origin` carries the longest comment because it is the only key
+ * whose default is *wrong for a deployed site* rather than merely generic: with
+ * no origin every canonical link, the feed id, the sitemap, and `robots.txt`
+ * point at a loopback name. A user learns that from this file or from nowhere.
+ *
+ * Every glob is shown quoted, and the comment says why in one line. YAML's plain
+ * scalars are a language and a glob is not written in it — `!README.md` parses
+ * to the empty string and `! README.md` parses to `README.md`, which *inverts* a
+ * re-include into an exclusion. The loader refuses all of them loudly, so the
+ * cost of not knowing is a failed build rather than a leak; the quoting advice
+ * is what turns the failed build into no build at all.
+ *
+ * The example origin is `notes.example.org`: `example.org` is reserved by
+ * RFC 2606 for exactly this, so it can never become a real host somebody owns.
+ */
+export const CONFIG_TEMPLATE = `# ${CONFIG_FILENAME} — every key is optional, and every key below is commented
+# out. Delete a "#" to use one. With this file exactly as written, the build
+# behaves as though it were not here at all.
+#
+# Everything in this repository publishes unless you exclude it. There is no
+# opt-in; the work is deciding what to withhold.
+
+# The site's name. Reaches the browser tab, page metadata, and the feed.
+# title: My Notes
+
+# The public address the site will be served from, with no path.
+#
+# Set this before you deploy. Without it every canonical link, the feed id, the
+# sitemap, and robots.txt point at a loopback name that reaches nobody — the
+# site builds and looks correct and is unreachable by anything that follows one
+# of those links.
+# origin: https://notes.example.org/
+
+# Paths not to publish, as gitignore-style globs. "!" re-includes.
+#
+# Quote every pattern. YAML reads an unquoted "!" as a tag and discards it,
+# which turns a rule that keeps a file into one that removes it.
+#
+# A pattern matching no files fails the build, with no override: a mistyped
+# exclusion publishes what it was meant to withhold.
+#
+# Do not add "dist/**". Every file in a build's output is already dropped as
+# not-markdown before exclusion is consulted, so the pattern changes a file's
+# reason for being dropped rather than whether it is walked — measured, the
+# discovered count goes up by one, not down, because the config file itself is
+# then discovered too. Keep build output out of git with .gitignore, which
+# this command seeds; exclude is for notes you wrote and do not want published.
+# exclude:
+#   - "drafts/**"
+#   - "private/**"
+
+# The site's default language, as a BCP 47 tag. Every note that declares no
+# "language:" of its own takes it, and so does the site's navigation. It also
+# picks the search index a page lands in, which matters for Chinese and
+# Japanese: an English-indexed Chinese page is searchable only by whole
+# sentences. Without it, the default is English.
+# language: zh-CN
+
+# A single note can also withhold itself, which no glob can re-include:
+#
+#   ---
+#   publish: false
+#   ---
+#
+# Before deployment, run the installed command's "review" subcommand, inspect and
+# commit .publish-set.json, then build with "--release". Ordinary builds remain previews.
+`;
+/**
+ * Parse `init`'s options.
+ *
+ * One flag, and it is `build`'s: the configuration file must land where the
+ * build will look for it. `loadConfig` reads {@link CONFIG_FILENAME} from the
+ * **content** directory rather than from the invocation directory, so an `init`
+ * with no such flag would write the file at the working directory while a user
+ * who then runs `build --content notes` gets a build that silently ignores it.
+ * That is this project's recurring failure exactly — a configuration that looks
+ * applied and is not — installed by the command whose job is to prevent it.
+ *
+ * The rejected token is never echoed, for the reason
+ * `bin/anc.mjs` gives at length: a printed argv token must be
+ * byte-equal to a spelling this tool's own table declares, and an unrecognised
+ * token is by definition not one.
+ */
+export function parseInitArguments(argv) {
+    let content = '.';
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument !== '--content') {
+            throw new BuildFailure('unknown-option', 'unrecognised option for init', argument);
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith('--')) {
+            // `argument` is `--content` by construction — the branch above rejected
+            // everything else — so this is a literal of this file's own source.
+            throw new BuildFailure('missing-value', `${argument} needs a directory`);
+        }
+        content = value;
+        index += 1;
+    }
+    return { content };
+}
+/**
+ * Write the starter config, unless the user already has one.
+ *
+ * **Absent is the only case that writes**, and the check is `existsSync` on the
+ * one filename rather than anything cleverer. A near-miss spelling is
+ * deliberately not consulted: `loadConfig` refuses a build that finds
+ * `publish.config.yml`, by name and with the rename instruction, which is a
+ * better outcome than `init` quietly producing a second file beside the one the
+ * user meant.
+ */
+export function writeStarterConfig(contentDirectory) {
+    const path = join(contentDirectory, CONFIG_FILENAME);
+    // `statSync().isFile()` rather than `existsSync`, which answers true for a
+    // *directory* of that name: measured, `init` then reported the config as
+    // "already present, left unchanged" when there was no config, and the build
+    // failed one command later with `exists but could not be read`. `init` is the
+    // command whose job is to leave the repository buildable, so it is the wrong
+    // command to be silent there.
+    //
+    // Refused rather than worked around. Removing a directory the user made is not
+    // this command's decision, and writing the file beside it is impossible.
+    let existing;
+    try {
+        existing = statSync(path);
+    }
+    catch {
+        existing = undefined;
+    }
+    if (existing !== undefined && !existing.isFile()) {
+        throw new BuildFailure('config-not-a-file', `${CONFIG_FILENAME} exists but is not a file, so no configuration can be written or read there. ` +
+            'Move or remove it.', `${path} is not a regular file`);
+    }
+    if (existing !== undefined)
+        return 'present';
+    writeFileSync(path, CONFIG_TEMPLATE, 'utf8');
+    return 'written';
+}
+/**
+ * Seed the ignore rules and the configuration, in that order.
+ *
+ * The order is the fail-closed one and it is not incidental. `ensureIgnored`
+ * throws when git cannot be asked or a probe cannot be trusted — and on that run
+ * nothing should have been written yet, because a repository holding a config
+ * this tool wrote and no ignore rule is a repository one `git add -A` away from
+ * committing `dist/`. Writing the config second means the failure leaves the
+ * directory as it was found.
+ *
+ * `.gitignore` goes to the **repository root** and the config to the **content
+ * directory**, which are the same place in the ordinary case and deliberately
+ * not the same call: an ignore rule governs a worktree and a config governs the
+ * notes it sits with. `ensureIgnored` resolves the root itself, by asking git.
+ *
+ * **The directory is checked first, before either write.** A mistyped
+ * `--content` otherwise reaches `ensureIgnored`, whose `git -C <missing>` exits
+ * 128 and is reported as "not a repository" — so `init` would write a
+ * `.gitignore` into a directory `writeFileSync` then fails to put the config in,
+ * with a raw `ENOENT` carrying the user's own path onto a stream the disclosure
+ * rule governs. Measured: `mkdir` on the missing directory is the other option
+ * and is worse, because it makes a typo succeed.
+ */
+export function initialise(contentDirectory) {
+    const resolved = resolve(contentDirectory);
+    if (!existsSync(resolved)) {
+        throw new BuildFailure('content-directory-not-found', 'content directory not found: the directory named by --content does not exist', resolved);
+    }
+    // **A content directory in no repository is not refused**, and there is
+    // deliberately no check here for one "outside the repository". A review
+    // proposed it and it cannot be written: `ensureIgnored` resolves the
+    // repository root *from the content directory itself*, so the `.gitignore` it
+    // seeds always governs the notes it was pointed at — a guard comparing the two
+    // would ask whether a directory is inside its own repository, which is true by
+    // construction. Measured with the guard in place: it never fired, on any of
+    // the three shapes tried.
+    //
+    // The reviewed symptom was real but is a different arrangement: content and
+    // invocation directories both under one repository, which is the ordinary
+    // nested case and correctly seeds that repository's root. What that leaves
+    // uncovered is the build output under a subdirectory, and `entriesFor` in
+    // `seed-gitignore.ts` is what closes it.
+    const ignore = ensureIgnored(resolved);
+    return { ignore, config: writeStarterConfig(resolved) };
+}