@kirchdev/duxt 0.3.4-dev-main.41-23ded41 → 0.3.5-dev-main.43-3310f4b

package/bruno-zip.ts

@@ -0,0 +1,195 @@
+/**
+ * The collection, as the ZIP a reader downloads.
+ *
+ * THE CANONICAL ACQUISITION ROUTE, and the reason it exists: the pages are a
+ * reference, and a Bruno collection is a thing you OPEN. A reader who wants the
+ * requests wants the files, at the exact version and locale the page they are
+ * reading was built from — which a link to the repository's default branch
+ * cannot give them and a "Fetch in Bruno" link, which clones whatever HEAD is
+ * today, cannot either.
+ *
+ * WRITTEN BY HAND, and the ~90 lines are the point. A ZIP with no compression
+ * is a header, the bytes, and a table saying where each one started; the three
+ * archivers that would have supplied it are all a dependency this layer's
+ * consumers would carry into every build, for a file that is already a tree of
+ * small text files where compression buys a few kilobytes. The repository's own
+ * rule about a heavy browser dependency says the same thing one level up.
+ *
+ * STORED, NOT DEFLATED, for that reason: method 0 needs no compressor at all,
+ * and `unzip`, macOS Archive Utility, Windows Explorer and Bruno's own import
+ * all read it.
+ *
+ * DETERMINISTIC. Every timestamp is the DOS epoch rather than "now", so a site
+ * that rebuilds nightly does not publish a new download for a collection nobody
+ * changed — the archive is a function of the files, and of nothing else.
+ */
+import type { DuxtSectionInput } from './sections-resolve';
+import { BRUNO_UNPUBLISHED } from './bruno-parse';
+
+/** One file in the archive. */
+export interface DuxtZipEntry {
+  /** The path inside the archive, `/`-separated. */
+  name: string;
+  data: string;
+}
+
+/**
+ * Where a section's archive is served.
+ *
+ * By COLLECTION rather than by prefix: two languages deliberately claim one
+ * prefix, so a prefix names two archives and would serve the wrong one to the
+ * second. The collection name is unique per version and per locale, and both
+ * the type writing the link and the module emitting the file compute it from
+ * here so the two cannot drift.
+ */
+export function brunoZipPath(collection: string): string {
+  return `${DUXT_BRUNO_ASSETS}/${brunoZipName(collection)}`;
+}
+
+/**
+ * The directory the archives are served from.
+ *
+ * Exported because the module that WRITES them needs the same two halves the
+ * page's link is built from. Composed rather than spelled out twice: the two
+ * agreeing by coincidence is how a download 404s after somebody renames one.
+ */
+export const DUXT_BRUNO_ASSETS = '/_duxt/bruno';
+
+/** One archive's file name inside that directory. */
+export function brunoZipName(collection: string): string {
+  return `${collection}.zip`;
+}
+
+/**
+ * The files of the collection that are published, in order.
+ *
+ * `environments/` is left out, and that is not a default a consumer can turn
+ * off. An environment file is where a Bruno collection keeps its hosts, tokens
+ * and keys — the real one in the wild that this type was written against has
+ * `JWT_SECRET` in it — and this archive is served on the open web. The pages
+ * already refuse to read one; an archive that shipped it would be the same leak
+ * by the other route.
+ */
+export function brunoZipEntries(input: DuxtSectionInput): DuxtZipEntry[] {
+  return input
+    .files()
+    .filter((file) => !file.startsWith(`${BRUNO_UNPUBLISHED}/`))
+    .map((file) => ({ name: file, data: input.read(file) }));
+}
+
+/** The archive, as bytes. */
+export function zipStore(entries: DuxtZipEntry[]): Uint8Array {
+  const encoder = new TextEncoder();
+  const locals: Uint8Array[] = [];
+  const central: Uint8Array[] = [];
+
+  let offset = 0;
+
+  for (const entry of entries) {
+    const name = encoder.encode(entry.name);
+    const data = encoder.encode(entry.data);
+    const crc = crc32(data);
+
+    const local = new Uint8Array(30 + name.length);
+    const view = new DataView(local.buffer);
+
+    view.setUint32(0, 0x04034b50, true); // local file header
+    view.setUint16(4, 20, true); // version needed — 2.0, stored
+    view.setUint16(6, 0x0800, true); // the name is UTF-8
+    view.setUint16(8, 0, true); // method 0: stored
+    view.setUint16(10, 0, true); // time — the DOS epoch, see the file header
+    view.setUint16(12, 0x0021, true); // date — 1980-01-01
+    view.setUint32(14, crc, true);
+    view.setUint32(18, data.length, true);
+    view.setUint32(22, data.length, true);
+    view.setUint16(26, name.length, true);
+    view.setUint16(28, 0, true); // no extra field
+
+    local.set(name, 30);
+    locals.push(local, data);
+
+    const record = new Uint8Array(46 + name.length);
+    const entryView = new DataView(record.buffer);
+
+    entryView.setUint32(0, 0x02014b50, true); // central directory header
+    entryView.setUint16(4, 20, true); // version made by
+    entryView.setUint16(6, 20, true); // version needed
+    entryView.setUint16(8, 0x0800, true);
+    entryView.setUint16(10, 0, true);
+    entryView.setUint16(12, 0, true);
+    entryView.setUint16(14, 0x0021, true);
+    entryView.setUint32(16, crc, true);
+    entryView.setUint32(20, data.length, true);
+    entryView.setUint32(24, data.length, true);
+    entryView.setUint16(28, name.length, true);
+    entryView.setUint16(30, 0, true); // extra
+    entryView.setUint16(32, 0, true); // comment
+    entryView.setUint16(34, 0, true); // disk number
+    entryView.setUint16(36, 0, true); // internal attributes
+    entryView.setUint32(38, 0o100644 << 16, true); // external: a regular file
+    entryView.setUint32(42, offset, true);
+
+    record.set(name, 46);
+    central.push(record);
+
+    offset += local.length + data.length;
+  }
+
+  const directory = concat(central);
+  const end = new Uint8Array(22);
+  const endView = new DataView(end.buffer);
+
+  endView.setUint32(0, 0x06054b50, true); // end of central directory
+  endView.setUint16(8, entries.length, true);
+  endView.setUint16(10, entries.length, true);
+  endView.setUint32(12, directory.length, true);
+  endView.setUint32(16, offset, true);
+
+  return concat([...locals, directory, end]);
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+
+  return out;
+}
+
+/**
+ * The table, built once.
+ *
+ * A ZIP entry carries a CRC-32 of its own contents and readers check it, so
+ * this is not optional — an archive with a wrong one extracts with a warning in
+ * the best case and is refused in the worst.
+ */
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+
+  for (let index = 0; index < 256; index++) {
+    let value = index;
+
+    for (let bit = 0; bit < 8; bit++) {
+      value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1;
+    }
+
+    table[index] = value >>> 0;
+  }
+
+  return table;
+})();
+
+function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff;
+
+  for (const byte of data) {
+    crc = CRC_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+  }
+
+  return (crc ^ 0xffffffff) >>> 0;
+}

package/cli.ts

@@ -0,0 +1,240 @@
+import { defineCommand, renderUsage } from 'citty';
+import type { ArgsDef, CommandDef } from 'citty';
+import { duxtReportOutput } from './report';
+import type { DuxtReport, DuxtReportFormat, DuxtReportOptions } from './report';
+
+/**
+ * The `duxt` command line, as a function of its arguments.
+ *
+ * NOT citty's `runMain`, and that is the design rather than an oversight. Its
+ * entry point reads `process.argv`, prints to the console and exits the
+ * process, which makes every question worth asking here — what did it print,
+ * what did it exit with, did it touch the site at all — unaskable from a test.
+ * So citty is used for the two things it is genuinely good at, holding the
+ * command tree and rendering usage out of it, and the dispatch is ours.
+ *
+ * The other half of the design is that NOTHING here reads the site. The report
+ * arrives through a loader the caller passes in, so every path that prints
+ * usage answers before a config or a parse cache is touched — which is the
+ * point of a `--help` on a command whose reader has, by definition, not got a
+ * working site yet.
+ */
+export interface DuxtCliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/** How the command gets its data — a seam, so help never needs a built site. */
+export type DuxtReportLoader = (options?: DuxtReportOptions) => DuxtReport;
+
+/**
+ * `2` is the command line, `1` is the documentation.
+ *
+ * Conflating them is what makes a report command unusable in CI: a pipeline
+ * that treats every non-zero exit as "the docs are broken" reports a typo in
+ * its own script as a documentation failure, and the person who wrote the
+ * script is not the person who gets paged.
+ */
+const USAGE_ERROR = 2;
+
+/* -------------------------------------------------------------------------- */
+/* The command tree                                                            */
+/* -------------------------------------------------------------------------- */
+
+const help = {
+  type: 'boolean',
+  alias: 'h',
+  description: 'Show this help.'
+} as const;
+
+const reportCommand = defineCommand({
+  meta: {
+    name: 'report',
+    description:
+      'Print what your sources became, and what is wrong with them, as Markdown.'
+  },
+  args: {
+    json: {
+      type: 'boolean',
+      description: 'Print the same data unrendered, as JSON.'
+    },
+    help
+  }
+});
+
+const rootCommand = defineCommand({
+  meta: {
+    name: 'duxt',
+    description: 'The duxt documentation layer, from the command line.'
+  },
+  args: { help },
+  subCommands: { report: reportCommand }
+});
+
+/**
+ * What the usage citty renders from the tree above cannot say.
+ *
+ * citty renders a command's arguments; it has no section for the two facts
+ * that actually stop somebody — what an exit code meant, and why the report is
+ * empty on a site nobody has built. Both are the reason this command grew a
+ * `--help` at all, so they are appended here rather than left to the README,
+ * which is exactly where the reader of this text has already failed to look.
+ */
+const REPORT_NOTES = `EXIT CODES
+
+  0  the documentation has no errors — warnings and translation notes
+     are what a source going stale looks like, and do not fail
+  1  the report found errors in the documentation
+  2  the command line could not be understood
+
+THE PARSE CACHE
+
+  The pages come from Content's parse cache, so the site has to have been
+  parsed once: run \`nuxt build\` or \`nuxt dev\` first. Without it the sources,
+  the collections and the redirects are still printed, and everything that
+  needs pages is reported as missing rather than as empty.
+`;
+
+const usage = async (command: CommandDef, notes = ''): Promise<string> => {
+  const rendered = await renderUsage(
+    command,
+    command === rootCommand ? undefined : rootCommand
+  );
+
+  return notes ? `${rendered}\n\n${notes}` : rendered;
+};
+
+/* -------------------------------------------------------------------------- */
+/* Reading the command line                                                    */
+/* -------------------------------------------------------------------------- */
+
+const toArray = (value: string | string[] | undefined): string[] =>
+  value === undefined ? [] : Array.isArray(value) ? value : [value];
+
+/**
+ * Every spelling a command accepts, mapped to the one it means.
+ *
+ * Read off the command tree rather than written out a second time: the usage
+ * a reader is shown and the options the parser accepts are then the same list
+ * by construction, and cannot drift into a flag that is documented but refused
+ * or — the worse direction — accepted but undocumented.
+ */
+function spellings(command: CommandDef): Map<string, string> {
+  const declared = (command.args ?? {}) as ArgsDef;
+  const found = new Map<string, string>();
+
+  for (const [name, definition] of Object.entries(declared)) {
+    found.set(`--${name}`, name);
+    for (const alias of toArray(
+      (definition as { alias?: string | string[] }).alias
+    )) {
+      found.set(`-${alias}`, name);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * The flags an invocation set, or the first thing wrong with it.
+ *
+ * Strict on purpose, and the strictness is the feature: citty — like every
+ * other argument parser in this family — collects what it does not recognise
+ * rather than refusing it, so `--jsno` parsed, was ignored, and the command
+ * printed a confident Markdown report that was not the one that had been asked
+ * for. An option that does nothing has to say so.
+ */
+function readOptions(
+  tokens: string[],
+  command: CommandDef
+): { flags: Set<string> } | { diagnostic: string } {
+  const accepted = spellings(command);
+  const flags = new Set<string>();
+
+  for (const token of tokens) {
+    if (!token.startsWith('-') || token === '-') {
+      return { diagnostic: `Unexpected argument '${token}'.` };
+    }
+
+    // `--json=true` on a flag that carries no value is not a spelling of
+    // `--json`; it is somebody expecting a different option to exist.
+    const [spelling, ...value] = token.split('=');
+    const name = accepted.get(spelling!);
+
+    if (!name) return { diagnostic: `Unknown option '${spelling}'.` };
+    if (value.length) {
+      return { diagnostic: `Option '${spelling}' takes no value.` };
+    }
+    if (flags.has(name)) {
+      return { diagnostic: `Duplicate option '${spelling}'.` };
+    }
+
+    flags.add(name);
+  }
+
+  return { flags };
+}
+
+const refuse = async (
+  diagnostic: string,
+  command: CommandDef
+): Promise<DuxtCliResult> => {
+  const name = command === rootCommand ? 'duxt' : 'duxt report';
+
+  return {
+    stdout: '',
+    // The diagnostic, not the usage. A wall of text under a one-line mistake
+    // buries the line that says what the mistake was, and the reader is one
+    // documented keystroke away from the wall if they want it.
+    stderr: `${diagnostic}\nRun \`${name} --help\` to see what it takes.`,
+    exitCode: USAGE_ERROR
+  };
+};
+
+/* -------------------------------------------------------------------------- */
+/* The command                                                                 */
+/* -------------------------------------------------------------------------- */
+
+export async function runDuxtCli(
+  argv: string[],
+  load: DuxtReportLoader
+): Promise<DuxtCliResult> {
+  const [name] = argv;
+
+  if (name !== undefined && !name.startsWith('-') && name !== 'report') {
+    return refuse(`Unknown command '${name}'.`, rootCommand);
+  }
+
+  const command = name === 'report' ? reportCommand : rootCommand;
+  const read = readOptions(name === 'report' ? argv.slice(1) : argv, command);
+
+  if ('diagnostic' in read) return refuse(read.diagnostic, command);
+
+  // Before `--help` is acted on rather than after: an invocation has to be
+  // well formed before anything is done with it, and `--json --help` asks for
+  // two different outputs at once. Silently dropping one of them is the
+  // behaviour this command was reported for.
+  if (read.flags.has('help') && read.flags.size > 1) {
+    return refuse(`'--help' cannot be combined with another option.`, command);
+  }
+
+  if (command === rootCommand) {
+    // Bare `duxt` prints usage rather than an error: a command run with no
+    // arguments at all is somebody asking what it does.
+    return { stdout: await usage(rootCommand), stderr: '', exitCode: 0 };
+  }
+
+  if (read.flags.has('help')) {
+    return {
+      stdout: await usage(reportCommand, REPORT_NOTES),
+      stderr: '',
+      exitCode: 0
+    };
+  }
+
+  const format: DuxtReportFormat = read.flags.has('json') ? 'json' : 'markdown';
+  const { output, exitCode } = duxtReportOutput(load(), format);
+
+  return { stdout: output, stderr: '', exitCode };
+}

package/duxt-app-config.ts

@@ -54,6 +54,16 @@ export interface DuxtBuildConfig {
    * pays for that one grammar.
    */
   sampleLanguages?: string[];
+  /**
+   * The landing page — read here for the LANGUAGES of its code demos only.
+   *
+   * They are highlighted by the same runtime highlighter as the samples, so
+   * `modules/config.ts` adds each named language to its grammar set. Typed
+   * structurally for the reason `requestSamples` is.
+   */
+  landing?: {
+    showcase?: { demo?: { files?: { language?: string }[] } }[];
+  };
 }
 
 /**
@@ -76,7 +86,14 @@ export interface DuxtBuildConfig {
 export function readDuxtBuildConfig(
   dirs: string[]
 ): DuxtBuildConfig | undefined {
-  const jiti = createJiti(import.meta.url, { interopDefault: true });
+  // NO MODULE CACHE. `nuxi dev` restarts Nuxt inside the same process when a
+  // config file changes, and jiti's default hands every later read the module
+  // it loaded first — so an edited `app.config.ts` kept building collections
+  // from the options the dev server started with, until the process was killed.
+  const jiti = createJiti(import.meta.url, {
+    interopDefault: true,
+    moduleCache: false
+  });
 
   // `defineAppConfig` is a Nuxt auto-import that does not exist in plain Node.
   // It is the identity function, so a stub is the whole of it.

package/frontmatter.ts

@@ -0,0 +1,49 @@
+/**
+ * A frontmatter block, written and taken off again.
+ *
+ * Both halves live here because both sides of the layer need one of them and
+ * neither may drift from the other: the generated sections WRITE every page's
+ * block, and the copy button, `llms-full.txt`, the `.md` twin and the MCP tools
+ * READ the prose back out from under it. Before this the writer existed three
+ * times — one copy already disagreed about empty values — and the reader twice,
+ * once with a comment claiming it was the other.
+ *
+ * Pure and dependency-free, so the app bundle can import it as well as Nitro
+ * and the build.
+ */
+
+/**
+ * A frontmatter block YAML can read back.
+ *
+ * Every value is written as a JSON string, which is also a YAML double-quoted
+ * scalar — so a title carrying a colon cannot end the mapping early, the exact
+ * failure `tests/frontmatter-yaml.test.ts` exists over. `GET /pets/{petId}: not
+ * found` is the shape that breaks an unquoted one.
+ *
+ * An absent or empty value writes no key at all: `title: ""` is not a title,
+ * and Content would read it as one rather than falling back to the heading.
+ */
+export function frontmatterBlock(
+  fields: Record<string, string | undefined>
+): string {
+  return [
+    '---',
+    ...Object.entries(fields)
+      .filter(([, value]) => value !== undefined && value !== '')
+      .map(([key, value]) => `${key}: ${JSON.stringify(value)}`),
+    '---'
+  ].join('\n');
+}
+
+/**
+ * The Markdown body without its frontmatter block.
+ *
+ * Content's `rawbody` is the file as it sits on disk, frontmatter included. A
+ * reader wants the prose; a model handed `---\ntitle: …\n---` reads a page
+ * whose first heading is a YAML fence.
+ */
+export function stripFrontmatter(body: string): string {
+  const match = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(body);
+
+  return match ? body.slice(match[0].length) : body;
+}