@event4u/agent-config 6.0.0 → 7.0.0

package/src/scripts/generate_pack_manifests.ts

@@ -0,0 +1,1025 @@
+#!/usr/bin/env node
+/**
+ * Generate `pack.yaml` + `README.md` for every pack home.
+ *
+ * TypeScript twin of `src/scripts/generate_pack_manifests.py` (ADR-200 —
+ * Python→TS migration, Phase 8 / Wave 8a). The CLI contract is mirrored
+ * EXACTLY: same flag (`--check`), same exit codes, same stdout/stderr
+ * split, same byte-identical generated `pack.yaml` + `README.md`. WRITER
+ * — both outputs match the Python output byte-for-byte, including the
+ * PyYAML `safe_dump(meta, sort_keys=True, allow_unicode=True)` block-style
+ * emission (`_py_safe_dump` below reproduces PyYAML's scalar-quoting +
+ * block-collection layout for the value shapes this script emits). No
+ * behaviour changes — latent bugs replicated.
+ *
+ * Phase 4.4 of the monorepo migration (ADR-017). The manifests are
+ * *derived* from frontmatter + `src/config/discovery/packs.yml`; they are
+ * regenerated on every `task sync` and must never be hand-edited.
+ *
+ * For each pack home we emit:
+ *   - `<home>/pack.yaml` — id, label, owner, requires, version, artefact_count, …
+ *   - `<home>/README.md` — pack description + per-artefact description table
+ *
+ * CLI:
+ *   --check     exit non-zero if any output would change (CI gate)
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { parse as parseYaml } from 'yaml';
+
+import { SRC_AGENT, iter_all_sources, resolve_logical } from './_lib/agent_src.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+// src/scripts/generate_pack_manifests.ts → parents[2] is the repo root (mirrors
+// `Path(__file__).resolve().parents[2]` in the .py).
+const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const PACKAGES = path.join(ROOT, 'packages');
+const SRC_DOMAINS = path.join(ROOT, 'src', 'domains');
+const SRC_PACKS = path.join(ROOT, 'src', 'packs');
+const PACKS_VOCAB = path.join(ROOT, 'src', 'config', 'discovery', 'packs.yml');
+const PACKAGE_JSON = path.join(ROOT, 'package.json');
+const GENERATED_HEADER =
+    '# Generated by scripts/generate_pack_manifests.py — DO NOT EDIT BY HAND\n';
+
+type Json = unknown;
+type Dict = Record<string, unknown>;
+
+interface Artefact {
+    path: string;
+    name: string;
+    description: string;
+    category: string;
+    skills: string[];
+    rules: string[];
+}
+
+// resolve_logical may need the SRC_AGENT accessor; keep an explicit reference
+// so the import is not pruned (parity with the Python `from … import` list).
+void resolve_logical;
+
+function _load_yaml(p: string): Json {
+    if (!_exists(p)) {
+        return null;
+    }
+    return parseYaml(fs.readFileSync(p, 'utf-8'), { version: '1.1' }) ?? null;
+}
+
+function _read_frontmatter(p: string): Dict {
+    const text = fs.readFileSync(p, 'utf-8');
+    if (!text.startsWith('---')) {
+        return {};
+    }
+    const end = text.indexOf('\n---', 4);
+    if (end === -1) {
+        return {};
+    }
+    let data: Json;
+    try {
+        data = parseYaml(text.slice(4, end), { version: '1.1' });
+    } catch {
+        return {};
+    }
+    return _isPlainObject(data) ? (data as Dict) : {};
+}
+
+function _pack_id_from_dir(pkgDir: string): string {
+    const name = path.basename(pkgDir);
+    return name === 'core' ? 'core' : _removePrefix(name, 'pack-');
+}
+
+/** Every pack home as `[pack_id, home_dir, mode]`. Mirrors `_pack_homes`. */
+function _pack_homes(): Array<[string, string, string]> {
+    const homes: Array<[string, string, string]> = [];
+    const seen = new Set<string>();
+    if (_isDir(SRC_AGENT())) {
+        homes.push(['core', path.join(SRC_PACKS, 'core'), 'core']);
+        seen.add('core');
+    }
+    for (const parent of [SRC_PACKS, SRC_DOMAINS]) {
+        if (!_isDir(parent)) {
+            continue;
+        }
+        for (const d of _iterdirSorted(parent)) {
+            if (!_isDir(d) || path.basename(d).startsWith('_')) {
+                continue;
+            }
+            const pid = path.basename(d);
+            if (seen.has(pid)) {
+                continue;
+            }
+            homes.push([pid, d, 'flat']);
+            seen.add(pid);
+        }
+    }
+    if (_exists(PACKAGES)) {
+        for (const pkg of _iterdirSorted(PACKAGES)) {
+            if (!_isDir(pkg)) {
+                continue;
+            }
+            const pid = _pack_id_from_dir(pkg);
+            if (seen.has(pid)) {
+                continue;
+            }
+            homes.push([pid, pkg, 'physical']);
+            seen.add(pid);
+        }
+    }
+    return homes;
+}
+
+function _vocab_lookup(packsVocab: Dict[]): Record<string, Dict> {
+    const out: Record<string, Dict> = {};
+    for (const p of packsVocab ?? []) {
+        out[String(p.id)] = p;
+    }
+    return out;
+}
+
+function _package_version(): string {
+    if (!_exists(PACKAGE_JSON)) {
+        return '0.0.0';
+    }
+    const pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf-8')) as Dict;
+    return _pyTruthy(pkg.version) ? String(pkg.version) : '0.0.0';
+}
+
+function _artefact_record(p: string, logicalRel: string, fm: Dict): Artefact {
+    const name = _pyTruthy(fm.name)
+        ? String(fm.name)
+        : path.basename(p) === 'SKILL.md'
+          ? path.basename(path.dirname(p))
+          : _stem(p);
+    return {
+        path: logicalRel,
+        name,
+        description: _pyStrip(_pyTruthy(fm.description) ? String(fm.description) : ''),
+        category: _category_from_logical(logicalRel),
+        skills: ((fm.skills as unknown[]) ?? []).filter((s) => typeof s === 'string') as string[],
+        rules: ((fm.rules as unknown[]) ?? []).filter((r) => typeof r === 'string') as string[],
+    };
+}
+
+function _collect_physical(pkgDir: string): Artefact[] {
+    const srcRoot = path.join(pkgDir, '.agent-src.uncondensed');
+    if (!_isDir(srcRoot)) {
+        return [];
+    }
+    const items: Artefact[] = [];
+    for (const p of _rglobSortedMd(srcRoot)) {
+        if (!_isFile(p)) {
+            continue;
+        }
+        const fm = _read_frontmatter(p);
+        if (!_pyTruthy(fm)) {
+            continue;
+        }
+        items.push(_artefact_record(p, _relativeToPosix(p, srcRoot), fm));
+    }
+    return items;
+}
+
+function _collect_core(): Artefact[] {
+    const items: Artefact[] = [];
+    const seen = new Set<string>();
+    if (_isDir(SRC_AGENT())) {
+        for (const p of _rglobSortedMd(SRC_AGENT())) {
+            if (!_isFile(p)) {
+                continue;
+            }
+            const fm = _read_frontmatter(p);
+            if (!_pyTruthy(fm)) {
+                continue;
+            }
+            const logical = _relativeToPosix(p, SRC_AGENT());
+            seen.add(logical);
+            items.push(_artefact_record(p, logical, fm));
+        }
+    }
+    for (const rec of _collect_flat('core')) {
+        if (!seen.has(rec.path)) {
+            seen.add(rec.path);
+            items.push(rec);
+        }
+    }
+    return items;
+}
+
+function _collect_flat(pid: string): Artefact[] {
+    const items: Artefact[] = [];
+    const seen = new Set<string>();
+    for (const [phys, logical] of iter_all_sources()) {
+        if (!logical.endsWith('.md') || seen.has(logical)) {
+            continue;
+        }
+        const fm = _read_frontmatter(phys);
+        if (!_pyTruthy(fm)) {
+            continue;
+        }
+        const packs = (fm.packs as unknown[]) ?? [];
+        if (packs.includes(pid)) {
+            seen.add(logical);
+            items.push(_artefact_record(phys, logical, fm));
+        }
+    }
+    return items.slice().sort((a, b) => _cmpStr(a.path, b.path));
+}
+
+function _collect_artefacts(pid: string, homeDir: string, mode: string): Artefact[] {
+    if (mode === 'core') {
+        return _collect_core();
+    }
+    if (mode === 'physical') {
+        return _collect_physical(homeDir);
+    }
+    return _collect_flat(pid);
+}
+
+function _category_from_logical(logicalRel: string): string {
+    const top = logicalRel.split('/', 1)[0] as string;
+    const mapping: Record<string, string> = {
+        skills: 'skill',
+        rules: 'rule',
+        commands: 'command',
+        personas: 'persona',
+        guidelines: 'guideline',
+        contexts: 'context',
+        presets: 'preset',
+        profiles: 'profile',
+    };
+    return mapping[top] ?? top;
+}
+
+/**
+ * Build the pack.yaml meta dict. Mirrors `_build_pack_yaml`. Insertion
+ * order here is irrelevant — `_py_safe_dump` sorts keys (sort_keys=True).
+ */
+function _build_pack_yaml(
+    pid: string,
+    vocab: Record<string, Dict>,
+    artefacts: Artefact[],
+    version: string,
+): Dict {
+    const meta = vocab[pid] ?? {};
+    const label = _pyTruthy(meta.label)
+        ? String(meta.label)
+        : pid === 'core'
+          ? _capitalizeTitle(pid)
+          : pid;
+    const out: Dict = {
+        id: pid,
+        label,
+        description: _pyTruthy(meta.description)
+            ? String(meta.description)
+            : pid === 'core'
+              ? 'Core framework-neutral artefacts.'
+              : '',
+        owner: _pyTruthy(meta.workspaces)
+            ? (meta.workspaces as unknown)
+            : pid === 'core'
+              ? ['agent-config-maintainer']
+              : [],
+        requires: _pyTruthy(meta.requires)
+            ? (meta.requires as unknown)
+            : _pyTruthy(meta.requires_hint)
+              ? (meta.requires_hint as unknown)
+              : [],
+        trust_level_default: _pyTruthy(meta.trust_level_default)
+            ? (meta.trust_level_default as unknown)
+            : 'core',
+        version,
+        artefact_count: artefacts.length,
+    };
+    if (_isPlainObject(meta.onboarding)) {
+        out.onboarding = meta.onboarding;
+    }
+    if (_pyTruthy(meta.slug_prefix)) {
+        out.slug_prefix = meta.slug_prefix;
+    }
+    if (_pyTruthy(meta.size_class)) {
+        out.size_class = meta.size_class;
+    }
+    // surface_tier — core | lab (road-to-install-contract-stability Phase 2).
+    // `core` = the lean stable multi-host engine (rules + skills + install +
+    // condensation). `lab` = experimental / pilot domain tooling that must not
+    // destabilise the core install surface. Default core; sourced from the
+    // discovery vocab when a pack is explicitly lab.
+    out.surface_tier = _pyTruthy(meta.surface_tier) ? (meta.surface_tier as unknown) : 'core';
+    out.suggests = _pyTruthy(meta.suggests) ? (meta.suggests as unknown) : [];
+    const depSkills = new Set<string>();
+    const depRules = new Set<string>();
+    for (const a of artefacts) {
+        for (const s of a.skills ?? []) depSkills.add(s);
+        for (const r of a.rules ?? []) depRules.add(r);
+    }
+    out.dependencies = {
+        skills: [...depSkills].sort(_cmpStr),
+        rules: [...depRules].sort(_cmpStr),
+    };
+    return out;
+}
+
+function _render_readme(packMeta: Dict, artefacts: Artefact[]): string {
+    const lines: string[] = [GENERATED_HEADER, `# ${String(packMeta.label)}`, ''];
+    if (_pyTruthy(packMeta.description)) {
+        lines.push(String(packMeta.description), '');
+    }
+    const owner = (packMeta.owner as unknown[]) ?? [];
+    const requires = (packMeta.requires as unknown[]) ?? [];
+    lines.push(
+        `- **id**: \`${String(packMeta.id)}\``,
+        `- **version**: \`${String(packMeta.version)}\``,
+        `- **owner**: ${owner.map(String).join(', ') || '—'}`,
+        `- **requires**: ${requires.map(String).join(', ') || '—'}`,
+        `- **artefacts**: ${String(packMeta.artefact_count)}`,
+        '',
+    );
+    const byCat = new Map<string, Artefact[]>();
+    for (const a of artefacts) {
+        if (!byCat.has(a.category)) byCat.set(a.category, []);
+        (byCat.get(a.category) as Artefact[]).push(a);
+    }
+    for (const cat of [...byCat.keys()].sort(_cmpStr)) {
+        const group = byCat.get(cat) as Artefact[];
+        lines.push(`## ${_capitalizeTitle(cat)}s (${group.length})`, '');
+        for (const a of group.slice().sort((x, y) => _cmpStr(x.name, y.name))) {
+            const desc = a.description || '_(no description)_';
+            lines.push(`- **\`${a.name}\`** — ${desc}`);
+        }
+        lines.push('');
+    }
+    return _pyRstripWs(lines.join('\n')) + '\n';
+}
+
+function _write_if_changed(p: string, content: string, check: boolean): boolean {
+    const existing = _exists(p) ? fs.readFileSync(p, 'utf-8') : null;
+    if (existing === content) {
+        return false;
+    }
+    if (check) {
+        return true;
+    }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content, 'utf-8');
+    return true;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const check = argv.includes('--check');
+    const vocab = _vocab_lookup((_load_yaml(PACKS_VOCAB) as Dict[]) ?? []);
+    const version = _package_version();
+    const homes = _pack_homes();
+    if (homes.length === 0) {
+        process.stderr.write(
+            'no pack homes (src/agent-src, src/packs, src/domains, packages/) — nothing to generate\n',
+        );
+        return 0;
+    }
+    let drift = 0;
+    for (const [pid, homeDir, mode] of homes) {
+        const artefacts = _collect_artefacts(pid, homeDir, mode);
+        const meta = _build_pack_yaml(pid, vocab, artefacts, version);
+        const yamlBody = GENERATED_HEADER + _py_safe_dump(meta);
+        const readmeBody = _render_readme(meta, artefacts);
+        const label = _relativeToPosix(homeDir, ROOT);
+        if (_write_if_changed(path.join(homeDir, 'pack.yaml'), yamlBody, check)) {
+            drift += 1;
+            process.stdout.write(`${check ? 'drift' : 'wrote'}: ${label}/pack.yaml\n`);
+        }
+        if (_write_if_changed(path.join(homeDir, 'README.md'), readmeBody, check)) {
+            drift += 1;
+            process.stdout.write(`${check ? 'drift' : 'wrote'}: ${label}/README.md\n`);
+        }
+    }
+    if (check && drift) {
+        process.stderr.write(
+            `pack manifests out of date (${drift} file(s)) — run \`task generate-pack-manifests\`\n`,
+        );
+        return 1;
+    }
+    return 0;
+}
+
+// === PyYAML safe_dump emitter (block style, sort_keys, allow_unicode) =======
+//
+// Reproduces the byte output of
+//   yaml.safe_dump(value, sort_keys=True, allow_unicode=True)
+// for the value shapes this script emits: dicts (string keys), strings,
+// ints, bools, None, lists, and nested dicts. PyYAML's default block style,
+// 2-space indent, best_width=80 plain-scalar line folding (now triggered by
+// the two long pack descriptions on main), and implicit-resolver-driven
+// scalar quoting are mirrored.
+
+// PyYAML Emitter defaults: best_width=80, best_indent=2. A plain block scalar
+// folds at column 80 — when a single-space word boundary would push the
+// running column past 80, the space is replaced by a line break + the value
+// node's block indent (the continuation indent). Only PLAIN scalars fold here;
+// quoted scalars have their own folding rules (not exercised by pack data,
+// where no quoted value approaches 80 columns).
+const BEST_WIDTH = 80;
+
+export function _py_safe_dump(value: unknown): string {
+    // Top-level document. PyYAML's emitter prints an empty mapping/sequence
+    // inline and a non-empty one in block style at indent 0.
+    const out: string[] = [];
+    _emitBlockNode(value, 0, out, true);
+    return out.join('');
+}
+
+/**
+ * Fold a PLAIN scalar the way PyYAML's `Emitter.write_plain` does, starting
+ * at `startColumn` (the column of the scalar's first character) and breaking
+ * to `contIndent` (the value node's block indent) when a word boundary would
+ * push the running column past `best_width` (80).
+ *
+ * Faithful to PyYAML: a fold happens only at a SINGLE-space word boundary
+ * (`start + 1 === end`) once `column > best_width`; that one space is dropped
+ * and replaced by a newline + `contIndent` spaces. Multi-space runs are
+ * written literally (never the fold point). The first word is always emitted
+ * on the opening line — a fold can never produce an empty leading line nor
+ * break before the first space. The pack data carries no line breaks inside
+ * a scalar, so the break-run branch of `write_plain` is unreachable here.
+ *
+ * Returns the text fragment for the scalar (no trailing newline).
+ */
+function _foldPlainScalar(text: string, startColumn: number, contIndent: number): string {
+    if (text === '') {
+        return '';
+    }
+    let outStr = '';
+    let column = startColumn;
+    let spaces = false;
+    let start = 0;
+    let end = 0;
+    while (end <= text.length) {
+        const ch: string | null = end < text.length ? (text[end] as string) : null;
+        if (spaces) {
+            if (ch !== ' ') {
+                if (start + 1 === end && column > BEST_WIDTH) {
+                    // Fold: replace the single space with break + continuation
+                    // indent. PyYAML's writeIndent resets the column to the
+                    // indent and primes whitespace=false so the next word
+                    // attaches with no extra leading space.
+                    outStr += '\n' + ' '.repeat(contIndent);
+                    column = contIndent;
+                } else {
+                    const data = text.slice(start, end);
+                    column += data.length;
+                    outStr += data;
+                }
+                start = end;
+            }
+        } else {
+            if (ch === null || ch === ' ') {
+                const data = text.slice(start, end);
+                column += data.length;
+                outStr += data;
+                start = end;
+            }
+        }
+        if (ch !== null) {
+            spaces = ch === ' ';
+        }
+        end += 1;
+    }
+    return outStr;
+}
+
+/**
+ * Emit a node in block context. `indent` is the current indent column for
+ * children. `topLevel` toggles the document-root behaviour. Appends to
+ * `out` (a list of string chunks). The contract: each call leaves a
+ * complete set of lines ending in `\n` for the lines it owns.
+ */
+function _emitBlockNode(value: unknown, indent: number, out: string[], topLevel: boolean): void {
+    if (_isPlainObject(value)) {
+        const obj = value as Dict;
+        const keys = Object.keys(obj).sort(_cmpStr);
+        if (keys.length === 0) {
+            out.push(`${' '.repeat(indent)}{}\n`);
+            return;
+        }
+        for (const k of keys) {
+            const keyScalar = _scalarRepr(k);
+            const v = obj[k];
+            if (_isPlainObject(v) && Object.keys(v as Dict).length > 0) {
+                out.push(`${' '.repeat(indent)}${keyScalar}:\n`);
+                _emitBlockNode(v, indent + 2, out, false);
+            } else if (Array.isArray(v) && v.length > 0) {
+                out.push(`${' '.repeat(indent)}${keyScalar}:\n`);
+                _emitBlockSeq(v, indent, out);
+            } else {
+                // scalar, empty dict, or empty list → inline value. A plain
+                // string value folds at best_width=80; the value's first char
+                // sits at column `indent + key + ": "`, continuation indent is
+                // the value node's block indent (`indent + 2`).
+                const startColumn = indent + keyScalar.length + 2;
+                out.push(`${' '.repeat(indent)}${keyScalar}: ${_scalarValueAt(v, startColumn, indent + 2)}\n`);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            out.push(`${' '.repeat(indent)}[]\n`);
+            return;
+        }
+        _emitBlockSeq(value, indent, out);
+        return;
+    }
+    // bare scalar document
+    void topLevel;
+    out.push(`${_inlineValue(value)}\n`);
+}
+
+/**
+ * Emit a block sequence. PyYAML aligns the `-` markers at the SAME indent
+ * as the parent key (block sequences are not extra-indented under a key in
+ * default safe_dump): `owner:\n- engineering`. Nested under a 2-space key
+ * (`dependencies:\n  skills:\n  - x`) the items sit at the key's indent.
+ */
+function _emitBlockSeq(seq: unknown[], indent: number, out: string[]): void {
+    for (const item of seq) {
+        if (_isPlainObject(item) && Object.keys(item as Dict).length > 0) {
+            // First key on the dash line, rest indented. (Not exercised by
+            // this script's data, but kept faithful.)
+            const obj = item as Dict;
+            const keys = Object.keys(obj).sort(_cmpStr);
+            const firstKey = keys[0] as string;
+            out.push(`${' '.repeat(indent)}- ${_scalarRepr(firstKey)}: ${_inlineValue(obj[firstKey])}\n`);
+            for (const k of keys.slice(1)) {
+                out.push(`${' '.repeat(indent + 2)}${_scalarRepr(k)}: ${_inlineValue(obj[k])}\n`);
+            }
+        } else if (Array.isArray(item) && item.length > 0) {
+            out.push(`${' '.repeat(indent)}-\n`);
+            _emitBlockSeq(item, indent + 2, out);
+        } else {
+            // Plain string item folds at best_width=80; first char sits at
+            // column `indent + "- "`, continuation indent is `indent + 2`.
+            out.push(`${' '.repeat(indent)}- ${_scalarValueAt(item, indent + 2, indent + 2)}\n`);
+        }
+    }
+}
+
+/**
+ * Block-context representation of a scalar value at a known column. For a
+ * string that PyYAML would emit as a PLAIN scalar, fold it at best_width=80
+ * with `contIndent` continuation. Quoted scalars / numbers / bools / null /
+ * empty collections are not subject to plain folding here, so they fall back
+ * to the inline writer unchanged.
+ */
+function _scalarValueAt(value: unknown, startColumn: number, contIndent: number): string {
+    if (typeof value === 'string') {
+        const repr = _scalarRepr(value);
+        // A plain scalar is returned verbatim by _scalarRepr (no surrounding
+        // quote indicators). Only those fold; quoted reprs keep their own form.
+        if (repr === value) {
+            return _foldPlainScalar(value, startColumn, contIndent);
+        }
+        return repr;
+    }
+    return _inlineValue(value);
+}
+
+/** Inline (flow-on-one-line) representation of a scalar / empty collection. */
+function _inlineValue(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'true' : 'false';
+    }
+    if (typeof value === 'number') {
+        return _numberRepr(value);
+    }
+    if (typeof value === 'string') {
+        return _scalarRepr(value);
+    }
+    if (Array.isArray(value)) {
+        // Only empty lists reach here (non-empty handled in block context).
+        return '[]';
+    }
+    if (_isPlainObject(value)) {
+        return '{}';
+    }
+    return _scalarRepr(String(value));
+}
+
+function _numberRepr(n: number): string {
+    if (Number.isInteger(n)) return String(n);
+    return String(n);
+}
+
+// --- PyYAML scalar analysis / quoting ----------------------------------------
+//
+// Mirrors PyYAML's `Emitter.analyze_scalar` + `choose_scalar_style` for the
+// block context, plus the `SafeRepresenter`/`Resolver` implicit type check
+// that forces quoting when a plain scalar would re-resolve as a non-string
+// (bool / int / float / null / timestamp / merge / value).
+
+/** Return the YAML scalar token for a string, quoting per PyYAML rules. */
+function _scalarRepr(s: string): string {
+    if (s === '') {
+        return "''";
+    }
+    const analysis = _analyzeScalar(s);
+    // PyYAML default flow_level=-1 (block). Plain allowed unless the analysis
+    // forbids it OR the implicit resolver would re-type it.
+    const plainOk = analysis.allowBlockPlain && !_resolvesToNonStr(s);
+    if (plainOk) {
+        return s;
+    }
+    if (analysis.allowSingleQuoted) {
+        return _singleQuoted(s);
+    }
+    return _doubleQuoted(s);
+}
+
+interface ScalarAnalysis {
+    allowBlockPlain: boolean;
+    allowSingleQuoted: boolean;
+}
+
+/**
+ * Port of PyYAML `Emitter.analyze_scalar` restricted to the flags this
+ * emitter consults (block-plain + single-quoted permission). Faithful to
+ * the indicator / spacing / special-character rules.
+ */
+function _analyzeScalar(scalar: string): ScalarAnalysis {
+    const chars = [...scalar];
+
+    let blockIndicators = false;
+    let flowIndicators = false;
+    let lineBreaks = false;
+    let specialCharacters = false;
+
+    let leadingSpace = false;
+    let leadingBreak = false;
+    let trailingSpace = false;
+    let trailingBreak = false;
+    let breakSpace = false;
+    let spaceBreak = false;
+
+    // First character indicators.
+    if (scalar.startsWith('---') || scalar.startsWith('...')) {
+        blockIndicators = true;
+        flowIndicators = true;
+    }
+    let precededByWhitespace = true;
+    let followedByWhitespace = chars.length === 1 || _isBreakOrSpace(chars[1]);
+
+    let previousSpace = false;
+    let previousBreak = false;
+
+    let index = 0;
+    while (index < chars.length) {
+        const ch = chars[index] as string;
+        const cp = ch.codePointAt(0) as number;
+        if (index === 0) {
+            if ('#,[]{}&*!|>\'"%@`'.includes(ch)) {
+                flowIndicators = true;
+                blockIndicators = true;
+            }
+            if (ch === '?' || ch === ':') {
+                flowIndicators = true;
+                if (followedByWhitespace) {
+                    blockIndicators = true;
+                }
+            }
+            if (ch === '-' && followedByWhitespace) {
+                flowIndicators = true;
+                blockIndicators = true;
+            }
+        } else {
+            if (',?[]{}'.includes(ch)) {
+                flowIndicators = true;
+            }
+            if (ch === ':') {
+                flowIndicators = true;
+                if (followedByWhitespace) {
+                    blockIndicators = true;
+                }
+            }
+            if (ch === '#' && precededByWhitespace) {
+                flowIndicators = true;
+                blockIndicators = true;
+            }
+        }
+
+        if (_isLineBreak(ch)) {
+            lineBreaks = true;
+        }
+        if (!_isPrintableAllowUnicode(cp)) {
+            specialCharacters = true;
+        }
+
+        if (ch === ' ') {
+            if (index === 0) leadingSpace = true;
+            if (index === chars.length - 1) trailingSpace = true;
+            if (previousBreak) breakSpace = true;
+            previousSpace = true;
+            previousBreak = false;
+        } else if (_isLineBreak(ch)) {
+            if (index === 0) leadingBreak = true;
+            if (index === chars.length - 1) trailingBreak = true;
+            if (previousSpace) spaceBreak = true;
+            previousSpace = false;
+            previousBreak = true;
+        } else {
+            previousSpace = false;
+            previousBreak = false;
+        }
+
+        index += 1;
+        precededByWhitespace = ch === '\0' || ' \t'.includes(ch) || _isLineBreak(ch);
+        followedByWhitespace =
+            index + 1 >= chars.length || _isBreakOrSpaceCh(chars[index + 1]);
+        // PyYAML uses index+1 lookahead with a sentinel; for our scalars the
+        // simpler check above is sufficient (no embedded breaks in pack data).
+    }
+
+    let allowFlowPlain = true;
+    let allowBlockPlain = true;
+    let allowSingleQuoted = true;
+    let allowBlockScalarUnused = true;
+    void allowFlowPlain;
+    void allowBlockScalarUnused;
+
+    if (leadingSpace || leadingBreak || trailingSpace || trailingBreak) {
+        allowFlowPlain = false;
+        allowBlockPlain = false;
+    }
+    if (trailingSpace) {
+        allowBlockScalarUnused = false;
+    }
+    if (breakSpace) {
+        allowFlowPlain = false;
+        allowBlockPlain = false;
+        allowSingleQuoted = false;
+    }
+    if (spaceBreak || specialCharacters) {
+        allowFlowPlain = false;
+        allowBlockPlain = false;
+        allowSingleQuoted = false;
+        allowBlockScalarUnused = false;
+    }
+    if (lineBreaks) {
+        allowFlowPlain = false;
+        allowBlockPlain = false;
+    }
+    if (flowIndicators) {
+        allowFlowPlain = false;
+    }
+    if (blockIndicators) {
+        allowBlockPlain = false;
+    }
+
+    return { allowBlockPlain, allowSingleQuoted };
+}
+
+function _isLineBreak(ch: string): boolean {
+    const cp = ch.codePointAt(0);
+    // \n (0x0A), NEL (0x85), LS (0x2028), PS (0x2029) — PyYAML line breaks.
+    return cp === 0x0a || cp === 0x85 || cp === 0x2028 || cp === 0x2029;
+}
+
+/**
+ * allow_unicode=True printable test (PyYAML analyze_scalar). Printable:
+ * tab, newline, 0x20-0x7E, NEL, 0xA0-0xD7FF, 0xE000-0xFFFD (excl. BOM),
+ * and any astral code point.
+ */
+function _isPrintableAllowUnicode(cp: number): boolean {
+    if (cp === 0x09 || cp === 0x0a) return true;
+    if (cp >= 0x20 && cp <= 0x7e) return true;
+    if (cp === 0x85) return true;
+    if (cp >= 0xa0 && cp <= 0xd7ff) return true;
+    if (cp >= 0xe000 && cp <= 0xfffd && cp !== 0xfeff) return true;
+    if (cp >= 0x10000 && cp <= 0x10ffff) return true;
+    return false;
+}
+function _isBreakOrSpace(ch: string | undefined): boolean {
+    return ch === undefined || ch === ' ' || _isLineBreak(ch);
+}
+function _isBreakOrSpaceCh(ch: string | undefined): boolean {
+    return ch === undefined || '\0 \t'.includes(ch) || _isLineBreak(ch);
+}
+
+/**
+ * PyYAML resolver: would this plain string re-resolve as a non-`str` type
+ * (bool / int / float / null / timestamp / merge / value / yes-no-on-off)?
+ * If so, safe_dump quotes it. Regexes ported from
+ * `yaml.resolver.Resolver.add_implicit_resolver` (YAML 1.1 defaults).
+ */
+function _resolvesToNonStr(s: string): boolean {
+    // bool
+    if (
+        /^(?:yes|Yes|YES|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF)$/.test(s)
+    ) {
+        return true;
+    }
+    // null
+    if (/^(?:~|null|Null|NULL|)$/.test(s)) {
+        return true;
+    }
+    // int (YAML 1.1)
+    if (
+        /^[-+]?0b[0-1_]+$/.test(s) ||
+        /^[-+]?0[0-7_]+$/.test(s) ||
+        /^[-+]?(?:0|[1-9][0-9_]*)$/.test(s) ||
+        /^[-+]?0x[0-9a-fA-F_]+$/.test(s) ||
+        /^[-+]?[1-9][0-9_]*(?::[0-5]?[0-9])+$/.test(s)
+    ) {
+        return true;
+    }
+    // float (YAML 1.1)
+    if (
+        /^[-+]?(?:[0-9][0-9_]*)\.[0-9_]*(?:[eE][-+]?[0-9]+)?$/.test(s) ||
+        /^\.[0-9][0-9_]*(?:[eE][-+]?[0-9]+)?$/.test(s) ||
+        /^[-+]?[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*$/.test(s) ||
+        /^[-+]?\.(?:inf|Inf|INF)$/.test(s) ||
+        /^\.(?:nan|NaN|NAN)$/.test(s)
+    ) {
+        return true;
+    }
+    // timestamp (YAML 1.1)
+    if (
+        /^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$/.test(s) ||
+        /^[0-9][0-9][0-9][0-9]-[0-9][0-9]?-[0-9][0-9]?(?:[Tt]|[ \t]+)[0-9][0-9]?:[0-9][0-9]:[0-9][0-9](?:\.[0-9]*)?(?:[ \t]*(?:Z|[-+][0-9][0-9]?(?::[0-9][0-9])?))?$/.test(
+            s,
+        )
+    ) {
+        return true;
+    }
+    // value / merge
+    if (s === '=' || s === '<<') {
+        return true;
+    }
+    return false;
+}
+
+/** PyYAML single-quoted style — double inner apostrophes, wrap in `'`. */
+function _singleQuoted(s: string): string {
+    return `'${s.replace(/'/g, "''")}'`;
+}
+
+/** PyYAML double-quoted style (used only when single-quoting is forbidden). */
+function _doubleQuoted(s: string): string {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        if (ch === '"') out += '\\"';
+        else if (ch === '\\') out += '\\\\';
+        else if (ch === '\0') out += '\\0';
+        else if (ch === '\x07') out += '\\a';
+        else if (ch === '\b') out += '\\b';
+        else if (ch === '\t') out += '\\t';
+        else if (ch === '\n') out += '\\n';
+        else if (ch === '\x0b') out += '\\v';
+        else if (ch === '\f') out += '\\f';
+        else if (ch === '\r') out += '\\r';
+        else if (ch === '\x1b') out += '\\e';
+        else if (ch === '\x85') out += '\\N';
+        else if (ch === '\xa0') out += '\\_';
+        else if (ch === '
') out += '\\L';
+        else if (ch === '
') out += '\\P';
+        else if (code >= 0x20 && code <= 0x7e) out += ch;
+        else if (code <= 0xff) out += '\\x' + code.toString(16).padStart(2, '0').toUpperCase();
+        else if (code <= 0xffff) out += '\\u' + code.toString(16).padStart(4, '0').toUpperCase();
+        else out += '\\U' + code.toString(16).padStart(8, '0').toUpperCase();
+    }
+    return out + '"';
+}
+
+// --- generic helpers ---------------------------------------------------------
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function _isPlainObject(v: unknown): v is Dict {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Sorted immediate children as absolute paths (mirrors `sorted(p.iterdir())`). */
+function _iterdirSorted(p: string): string[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(p);
+    } catch {
+        return [];
+    }
+    names.sort();
+    return names.map((n) => path.join(p, n));
+}
+
+/** Mirror `root.rglob("*.md")` → SORTED absolute paths. */
+function _rglobSortedMd(root: string): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const ent of entries) {
+            const full = path.join(dir, ent.name);
+            if (ent.name.endsWith('.md')) {
+                out.push(full);
+            }
+            if (ent.isDirectory() || (ent.isSymbolicLink() && _isDir(full))) {
+                walk(full);
+            }
+        }
+    };
+    walk(root);
+    out.sort();
+    return out;
+}
+
+function _relativeToPosix(child: string, root: string): string {
+    return path.relative(root, child).split(path.sep).join('/');
+}
+
+function _stem(p: string): string {
+    const base = path.basename(p);
+    const dot = base.lastIndexOf('.');
+    return dot <= 0 ? base : base.slice(0, dot);
+}
+
+function _removePrefix(s: string, prefix: string): string {
+    return s.startsWith(prefix) ? s.slice(prefix.length) : s;
+}
+
+/** Python `str.title()` for the single-word category / "Core" cases. */
+function _capitalizeTitle(s: string): string {
+    return s.replace(/[A-Za-z]+/g, (w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+}
+
+// Python str.strip() whitespace cohort.
+const _PY_WS = [
+    0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x85, 0xa0, 0x1680, 0x2000,
+    0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x2028,
+    0x2029, 0x202f, 0x205f, 0x3000,
+];
+function _isPyWs(cp: number | undefined): boolean {
+    return cp !== undefined && _PY_WS.includes(cp);
+}
+function _pyStrip(s: string): string {
+    let start = 0;
+    let end = s.length;
+    while (start < end && _isPyWs(s.codePointAt(start))) start += 1;
+    while (end > start && _isPyWs(s.codePointAt(end - 1))) end -= 1;
+    return s.slice(start, end);
+}
+function _pyRstripWs(s: string): string {
+    let end = s.length;
+    while (end > 0 && _isPyWs(s.codePointAt(end - 1))) end -= 1;
+    return s.slice(0, end);
+}
+
+function _pyTruthy(value: unknown): boolean {
+    if (value === null || value === undefined) return false;
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'number') return value !== 0;
+    if (typeof value === 'string') return value.length > 0;
+    if (Array.isArray(value)) return value.length > 0;
+    if (typeof value === 'object') return Object.keys(value).length > 0;
+    return true;
+}
+
+function _cmpStr(a: string, b: string): number {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+}
+
+const _isCliEntry =
+    process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+if (_isCliEntry || process.argv[1] === _HERE) {
+    process.exit(main());
+}