rpg-engine 0.0.0-stage → 0.1.0

package/dist/campaign/settings.js

@@ -0,0 +1,399 @@
+import { join } from "node:path";
+import { isMap, isScalar, isSeq, parseDocument } from "yaml";
+import { z } from "zod";
+import { unitSystems } from "../core/length.js";
+import { files } from "../core/store.js";
+import { comparableText } from "../core/text.js";
+import { readYamlFile, readYamlValues, writeYamlFile } from "../core/yaml-file.js";
+import { campaignFileName } from "./find-campaign.js";
+const settingsHold = 'settings, such as "name: ..."';
+/** How hard the world plays (D-13, D-141). */
+export const difficulties = ["story", "easy", "normal", "hard", "brutal"];
+/** What a fall means (D-13, D-141): the character never dies, dies only when it matters, or as the dice say. */
+export const lethalities = ["narrative", "epic", "dice"];
+/** When the game may go back (D-55): never, to the last end of a scene once the player character dies, or to any save, which the player may also ask for. */
+export const saveModes = ["permadeath", "checkpoint", "free"];
+/** How closely the rules are followed, apart from difficulty (D-42): the master glosses over them, as they are written, or beyond them. */
+export const rigors = ["smooth", "rules", "simulation"];
+/** What each difficulty means in play, from the GDD's table, which status and config give for the chosen one (D-263); fights in the words of a budget of low, moderate and high (D-266). */
+export const difficultyMeanings = {
+    story: "fights low; foes naive, at their weakest, quick to flee; clues obvious, four or more; resources plentiful; random encounters rare; threat clocks slow; you may soften your own rolls",
+    easy: "fights low to moderate; foes with simple tactics, below average toughness; three clues or more; resources generous; random encounters rare; threat clocks slow",
+    normal: "fights moderate to high; foes with sensible tactics, average toughness, normal morale; three clues to every conclusion; resources standard (treasure, supplies, prices); "
+        + "random encounters normal; threat clocks at their pace",
+    hard: "fights high and beyond; foes smart (focus, control), above average toughness, tenacious; three subtle clues; resources scarce; random encounters frequent; threat clocks fast",
+    brutal: "fights far beyond high; foes optimized (retreats, ambushes, finishing the fallen), at their toughest, fanatical; three subtle clues; resources very scarce; "
+        + "random encounters frequent; threat clocks fast; rests at their harshest",
+};
+/** What each rigor means in play (D-42, D-263): what the master counts, which status and config give for the chosen one. */
+export const rigorMeanings = {
+    smooth: "you gloss over food and water, light, encumbrance, fatigue, spell components and the like: count them only when the story turns on them",
+    rules: "as written: charge with change what is used up, food and water each day, light as it burns (the count, and an effect for as long as it lasts), lifestyle and wages; "
+        + "encumbrance, fatigue and spell components as the rules say; warn before something runs out, and once it has, the rule applies",
+    simulation: "as rules, and beyond what is written: wear, spoilage, weather and the like",
+};
+/** How much the master teaches the game, out of the story (D-347): the story alone, a hint now and then, or each rule as it first comes up. */
+export const mentorWays = ["off", "hints", "tutorial"];
+/** What each way of the mentor means to the master, which config gives for the chosen one, and the player's change of it on the dashboard (D-347). */
+export const mentorMeanings = {
+    off: "the story alone: no tips or explanations of yours, only your answers to what the player asks between brackets",
+    hints: "a tip of a sentence or two, in brackets, before a choice that matters and when a rule slips by, as the mentor's part of your instructions says; no lessons",
+    tutorial: "each mechanic explained the first time it comes up, the whole sum of a roll shown, a debrief after fights and at the end of a session, "
+        + "as the mentor's part of your instructions says",
+};
+/** What the chosen difficulty, rigor or mentor means, as status and config give it; undefined for another setting or a value it does not take. */
+export function settingMeaning(name, value) {
+    const meanings = { difficulty: difficultyMeanings, rigor: rigorMeanings, mentor: mentorMeanings, ...styleMeanings };
+    const own = Object.hasOwn(meanings, name) ? meanings[name] : undefined;
+    return typeof value === "string" && own !== undefined && Object.hasOwn(own, value) ? own[value] : undefined;
+}
+/** Who rolls the player character's dice (D-241): rpg, or the player with their own, telling the values; the master's are always rolled by rpg. */
+export const diceWays = ["digital", "physical"];
+export { unitSystems };
+/** Which pictures the engine has made, where it can (D-308, D-388, D-420): none, only those the player asks for, or one for each new place, quest and one met. */
+export const pictureWays = ["none", "on request", "new elements"];
+/** How the companions come (D-76, D-221): none, made in session zero with the player or by the master, or met in play. */
+export const companionWays = ["none", "made with the player", "made by the master", "met in play"];
+/** How far ahead a world without a written campaign is made (D-80): as it is needed, or all at the start. */
+export const preparations = ["on the fly", "all at the start"];
+/** How the master writes (D-395): plain, the core's own, literary, pulp or wry; the tone stays in the premise, and an author takes its place. */
+export const proseWays = ["plain", "literary", "pulp", "wry"];
+/** How the master builds what they invent (D-395): situations, the core's own, arcs, episodes or a mystery; a written adventure keeps its own. */
+export const storyWays = ["situations", "arcs", "episodes", "mystery"];
+/** The longest text the player's own words of how the master writes may be, by setting (D-395). */
+export const styleTextLengths = { author: 80, style: 300 };
+/** What each way of writing and of building the story means to the master, which config gives for the chosen one (D-395). */
+const styleMeanings = {
+    prose: {
+        plain: "short sentences, one concrete detail a thing, as your instructions write",
+        literary: "more room at the high points, images and subtext, as the prose part of your instructions says",
+        pulp: "tense action, strong colours, every message ending on a threat or a hook, as the prose part of your instructions says",
+        wry: "a narrator with a half smile at the world, never at the character, as the prose part of your instructions says",
+    },
+    story: {
+        situations: "a world of factions, threats with their clocks and places with secrets, no main plot, as your instructions write",
+        arcs: "a central threat that advances by stages, the party's own arcs woven in, as the story part of your instructions says",
+        episodes: "a story that closes each session, with a thread that comes back, as the story part of your instructions says",
+        mystery: "every story an investigation, its truth written first in the secrets, as the story part of your instructions says",
+    },
+};
+/** An item of a list setting. Written by hand without quotes, "Poisoned: la benda…" is YAML for a pair: it is read as the text it was meant to be (D-179). */
+const listItem = z.preprocess((item) => pairText(item) ?? item, z.string().min(1));
+/** A list setting; an empty item written by hand, as - "", holds nothing and is left out, so that it never stops the game. */
+const listSetting = z.preprocess((items) => (Array.isArray(items) ? items.filter((item) => item !== null && String(item).trim() !== "") : items), z.array(listItem)).nullish();
+/** The player's own words in a setting, on one line: a line break in them would be read as a heading of the instructions they go into (D-395). */
+function oneLine(most) {
+    return z.preprocess((value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : value), z.string().min(1).max(most));
+}
+/** The settings of a campaign, kept in campaign.yaml. Other keys are kept: systems and extensions will add their own. */
+export const settingsSchema = z.object({
+    name: z.string().min(1).describe("name of the campaign"),
+    language: z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/, "use a language code such as it, en or pt-BR").optional().describe("language of the game, as a code such as it or en"),
+    system: z.string().min(1).optional().describe("game system of the campaign: one of those installed, such as 5e"),
+    mentor: z.enum(mentorWays).optional().describe("how much the master teaches the game, out of the story: off, hints or tutorial; asked as how well the player knows the game: never played (tutorial), a little (hints), well (off)"),
+    premise: z.string().min(1).optional().describe("without a written campaign: the genre, the tone and a few elements of the world, in the player's words"),
+    preparation: z.enum(preparations).optional().describe("without a written campaign: on the fly (the master makes the world just before it is needed) or all at the start"),
+    prose: z.enum(proseWays).optional().describe("how the master writes, as the player chose it: plain, literary, pulp or wry; the tone stays in the premise; an author takes its place"),
+    story: z.enum(storyWays).optional().describe("how the master builds what they invent: situations, arcs, episodes or mystery; a written adventure keeps its own"),
+    author: oneLine(styleTextLengths.author).optional().describe("an author the master writes like, as the player named them: their way, never their sentences, names or places"),
+    style: oneLine(styleTextLengths.style).optional().describe("the player's own wishes for how the master writes, in a few words, such as third person, past tense"),
+    difficulty: z.enum(difficulties).optional().describe(`how hard the world plays: ${difficulties.join(", ")}`),
+    lethality: z.enum(lethalities).optional().describe("what a fall means: narrative (the character never dies), epic (only when it matters) or dice (the dice decide)"),
+    saves: z.enum(saveModes).optional().describe("when the game may go back: permadeath (never, but to the start, the campaign starting over), checkpoint (to the last end of a scene, once the player character dies) or free (to any save, and saves when the player asks)"),
+    rigor: z.enum(rigors).optional().describe("how closely travel, fatigue, food, spell components and the like follow the rules: smooth (the master glosses over them), rules (as written) or simulation (beyond them)"),
+    dice: z.enum(diceWays).optional().describe("the player character's dice: digital (rpg rolls them) or physical (the player rolls their own and tells the values)"),
+    units: z.enum(unitSystems).optional().describe("the units of measure of the story: metric or imperial"),
+    companions: z.enum(companionWays).optional().describe("how the companions come: none, made with the player or made by the master in session zero, or met in play"),
+    // new places and new places and quests, as campaigns wrote it before quests and then those met had pictures, are read as the value that took their place (D-388, D-420).
+    pictures: z.preprocess((value) => (value === "new places" || value === "new places and quests" ? "new elements" : value), z.enum(pictureWays)).optional().describe("the pictures of places, quests and those met the engine has made on this computer, which spend the player's plan, Codex's or Claude's: none, on request (those the player asks for) "
+        + "or new elements (one for each new place and quest, and for each character and kind of creature the character meets)"),
+    lines: listSetting.describe("what never appears in the game"),
+    veils: listSetting.describe("what happens only off screen, without details"),
+    table: listSetting.describe("the table's agreements: what the master promised about how the game is played"),
+    precedents: listSetting.describe("the rulings made without the text, each starting with the name of the rule in the system's language: Poisoned: …"),
+    learned: listSetting.describe("the game's mechanics the master has explained, by their names in the system's language: explained again only when the player gets one wrong"),
+    // Checked by the money module (MON-1): coins written wrongly by hand must not stop the other settings from being read.
+    coins: z.unknown().optional().describe("the coins, for a game with money: each with its value in the smallest coin, such as gp 100, sp 10, cp 1"),
+    // What the campaign adds to its game system (CAM-1): checked by the systems module when it reads the system with them, so that a mistake there never hides the
+    // other settings.
+    fields: z.unknown().optional().describe("fields the campaign adds to its game system, by name with their kind, such as portent: rolls"),
+    tables: z.unknown().optional().describe("tables the campaign adds to its game system, by name, such as superiority-dice-by-level: {3: 4, 7: 5, 15: 6}"),
+    computed: z.unknown().optional().describe("formulas the campaign adds to its game system or puts in place of its own, as a house rule, by field"),
+    counters: z.unknown().optional().describe("counters the campaign adds to its game system or changes: their limits and what comes back with a rest, by name"),
+    recipes: z.unknown().optional().describe("what the campaign adds to the rests of its game system, by recipe, such as short rest: {set: {superiority-dice: max}}"),
+    "status-line": z.unknown().optional().describe("fields the campaign adds to the line of the player character and the companions, such as portent?"),
+    travel: z.unknown().optional().describe("what the campaign adds to how its game system travels, by key: paces, hours, terrain and kinds of road, such as kinds: {canal: {}}"),
+}).loose();
+/** The settings that the config command shows and changes. */
+export const settingNames = Object.keys(settingsSchema.shape);
+/** The settings that hold a list, changed one item at a time; none of them is ever missing in play. */
+export const listSettingNames = ["lines", "veils", "table", "precedents", "learned", "status-line"];
+/** The settings that hold entries by name, what the campaign adds to its game system (CAM-1): given or removed one entry at a time. */
+export const mapSettingNames = ["fields", "tables", "computed", "counters", "recipes", "travel"];
+/** What only the setup asks (D-241, MOD-3, D-347): how much the master teaches the game, how the companions come, and the lines and veils, which "none" answers too. */
+export const setupSettingNames = ["mentor", "companions", "lines", "veils"];
+/** What the setup asks only of a campaign without a written world (D-79, D-80, MOD-3). */
+export const premiseSettingNames = ["premise", "preparation"];
+// Settings that only some games have, or that only the setup asks: never asked for in play when missing.
+// The pictures: status asks for them once, only where they can be made (D-308).
+// How the master writes: the core's own until the player chooses (D-395).
+const styleSettingNames = ["prose", "story", "author", "style"];
+const optionalSettingNames = ["coins", "pictures", ...mapSettingNames, ...setupSettingNames, ...premiseSettingNames, ...styleSettingNames];
+export function readSettings(root) {
+    return validateSettings(readYamlValues(join(root, campaignFileName), settingsHold));
+}
+/** The coins as campaign.yaml writes them, unchecked and read on their own, so that a mistake in another setting does not hide them; the money module checks them (MON-1). */
+export function readCoinsSetting(root) {
+    return readOneSetting(root, "coins");
+}
+/**
+ * A text setting as campaign.yaml writes it, such as the system or the language, read even when another setting breaks the file: YAML still gives the keys it can (SYS-1).
+ * Undefined when it is missing, not text, or the file cannot be read.
+ */
+export function readTextSetting(root, name) {
+    try {
+        const value = parseDocument(files().text(join(root, campaignFileName)) ?? "").get(name);
+        return typeof value === "string" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A list setting as campaign.yaml writes it, read even when another setting breaks the file, as the system is (SYS-1): what rules reads. Empty when it cannot be read. */
+export function readListSetting(root, name) {
+    try {
+        const value = parseDocument(files().text(join(root, campaignFileName)) ?? "").toJS()?.[name];
+        return Array.isArray(value) ? value.map((item) => pairText(item) ?? item).filter((item) => typeof item === "string" && item.trim() !== "") : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function readOneSetting(root, name) {
+    const values = readYamlValues(join(root, campaignFileName), settingsHold);
+    return values !== null && typeof values === "object" ? values[name] : undefined;
+}
+/**
+ * Changes one setting and keeps the rest of campaign.yaml, comments included, as it is. Nothing is written if the setting already has that value, or if the settings would not be valid.
+ * Returns whether it changed. The value is text, or for coins the list already read.
+ */
+export function changeSetting(root, name, value) {
+    const setting = checkSettingName(name);
+    if (listSettingNames.includes(setting)) {
+        throw new Error(`"${setting}" is a list: change it one item at a time with add and remove, or give the value none when the player wants none.`);
+    }
+    const parsed = settingsSchema.shape[setting].safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`"${String(value)}" is not a valid ${setting}:\n${z.prettifyError(parsed.error)}`);
+    }
+    const document = readSettingsDocument(root);
+    if (JSON.stringify(document.toJS()?.[setting]) === JSON.stringify(parsed.data)) {
+        return false;
+    }
+    document.set(setting, parsed.data);
+    saveSettings(root, document);
+    return true;
+}
+/** Takes away a setting the player may leave unset again, as the author the master writes like (D-395). Returns whether it changed. */
+export function clearSetting(root, name) {
+    const setting = checkSettingName(name);
+    const document = readSettingsDocument(root);
+    if (!document.has(setting)) {
+        return false;
+    }
+    document.delete(setting);
+    saveSettings(root, document);
+    return true;
+}
+/**
+ * Writes a setting that is not the campaign's own but one a game system adds (DAT-10), as text, keeping the rest of campaign.yaml as it is; its value is checked by
+ * who knows the system. Returns whether it changed.
+ */
+export function changeOtherSetting(root, name, value) {
+    if (settingNames.some((setting) => comparableText(setting) === comparableText(name))) {
+        throw new Error(`${name} is a setting of the campaign: change it as one.`);
+    }
+    const document = readSettingsDocument(root);
+    if (document.toJS()?.[name] === value) {
+        return false;
+    }
+    document.set(name, value);
+    saveSettings(root, document);
+    return true;
+}
+/** Adds items to a list setting, or removes them, keeping the rest of campaign.yaml as it is. Returns whether it changed. */
+export function changeListSetting(root, name, change) {
+    const setting = checkSettingName(name);
+    if (!listSettingNames.includes(setting)) {
+        throw new Error(`"${setting}" holds one value: give the new value instead of add or remove.`);
+    }
+    if ([...(change.add ?? []), ...(change.remove ?? [])].some((item) => item.trim() === "")) {
+        throw new Error("Give the text of each item to add or remove.");
+    }
+    const document = readSettingsDocument(root);
+    const list = listNode(document, setting);
+    const before = JSON.stringify(list.toJSON());
+    const items = () => list.items.map((node) => String(isScalar(node) ? node.value : node));
+    const held = items();
+    const missing = (change.remove ?? []).find((item) => !held.some((other) => sameText(other, item)));
+    if (missing !== undefined) {
+        throw new Error(`"${setting}" does not hold "${missing}", so nothing changed. It holds: ${held.length > 0 ? held.join("; ") : "nothing"}.`);
+    }
+    list.items = list.items.filter((_, index) => !(change.remove ?? []).some((item) => sameText(held[index], item)));
+    for (const item of change.add ?? []) {
+        if (!items().some((other) => sameText(other, item))) {
+            list.add(document.createNode(item.trim().normalize("NFC")));
+        }
+    }
+    // A list emptied stays, as []: it still answers the setup (MOD-3).
+    if (JSON.stringify(list.toJSON()) === before) {
+        return false;
+    }
+    saveSettings(root, document);
+    return true;
+}
+/** Answers a list setting with none (MOD-3): an empty list, refused while it holds items, which are removed one by one. Returns whether it changed. */
+export function changeListSettingToNone(root, name) {
+    const setting = checkSettingName(name);
+    if (!listSettingNames.includes(setting)) {
+        throw new Error(`"${setting}" holds one value: give one of its values, not none.`);
+    }
+    const document = readSettingsDocument(root);
+    const before = document.toJS()?.[setting];
+    const held = listNode(document, setting).items.map((node) => String(isScalar(node) ? node.value : node));
+    if (held.length > 0) {
+        throw new Error(`"${setting}" holds ${held.join("; ")}: remove each one with remove, if the player no longer wants it. Nothing changed.`);
+    }
+    if (Array.isArray(before)) {
+        return false;
+    }
+    saveSettings(root, document);
+    return true;
+}
+/** What campaign.yaml adds to the game system, as it writes it, read even when another setting breaks the file (CAM-1); empty when it cannot be read. */
+export function readCampaignData(root) {
+    try {
+        const values = parseDocument(files().text(join(root, campaignFileName)) ?? "").toJS();
+        const names = [...mapSettingNames, "status-line"];
+        return values !== null && typeof values === "object" ? Object.fromEntries(Object.entries(values).filter(([name]) => names.includes(name))) : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Gives entries by name to a setting that holds them, such as counters, each in place of one with that name, or removes entries by name (CAM-1); keeps the
+ * rest of campaign.yaml as it is. Returns whether it changed.
+ */
+export function changeMapSetting(root, name, change) {
+    const setting = checkSettingName(name);
+    if (!mapSettingNames.includes(setting)) {
+        throw new Error(`"${setting}" holds no entries by name: ${listSettingNames.includes(setting) ? "change it with add and remove" : "give the new value"}.`);
+    }
+    const document = readSettingsDocument(root);
+    const held = document.get(setting);
+    const before = (held !== null && typeof held === "object" && "toJSON" in held ? held.toJSON() : held) ?? {};
+    if (typeof before !== "object" || Array.isArray(before)) {
+        throw new Error(`"${setting}" in ${campaignFileName} is not entries by name; write it by hand as ${setting}: {name: value}.`);
+    }
+    const entries = { ...before };
+    const named = (wanted) => Object.keys(entries).find((key) => sameText(key, wanted));
+    const missing = (change.remove ?? []).find((item) => named(item) === undefined);
+    if (missing !== undefined) {
+        const keys = Object.keys(entries);
+        throw new Error(`"${setting}" has no entry "${missing}", so nothing changed. It has: ${keys.length > 0 ? keys.join(", ") : "none"}.`);
+    }
+    for (const item of change.remove ?? []) {
+        delete entries[named(item)];
+    }
+    for (const [key, value] of Object.entries(change.set ?? {})) {
+        delete entries[named(key) ?? key];
+        entries[key] = value;
+    }
+    if (JSON.stringify(entries) === JSON.stringify(before)) {
+        return false;
+    }
+    if (Object.keys(entries).length === 0) {
+        document.delete(setting);
+    }
+    else {
+        document.set(setting, document.createNode(entries, { flow: false }));
+    }
+    saveSettings(root, document);
+    return true;
+}
+/** What is wrong in campaign.yaml, one problem for each setting, with how to fix it. */
+export function checkSettings(root) {
+    const fix = "fix campaign.yaml by hand (a list is written as [item, item]), or set a single value with the config command";
+    let values;
+    try {
+        values = readYamlValues(join(root, campaignFileName), settingsHold);
+    }
+    catch (error) {
+        return [{ path: campaignFileName, message: error instanceof Error ? error.message : String(error) }];
+    }
+    const parsed = settingsSchema.safeParse(values);
+    return parsed.success ? [] : parsed.error.issues.map((issue) => ({ path: campaignFileName, message: `${issue.path.join(".") || "the settings"}: ${issue.message}.`, fix }));
+}
+/** The settings that are still missing: the AI asks the player for them. */
+export function missingSettings(settings) {
+    return settingNames.filter((name) => !listSettingNames.includes(name) && !optionalSettingNames.includes(name) && settings[name] === undefined);
+}
+/**
+ * The settings the setup still has to ask, in order (MOD-3): those every campaign needs, how the companions come, the lines and veils until answered, even
+ * with none, and, for a campaign without a written world, its premise and preparation.
+ */
+export function unansweredSettings(settings, writtenWorld) {
+    const asked = [...setupSettingNames, ...(writtenWorld ? [] : premiseSettingNames)];
+    return settingNames.filter((name) => missingSettings(settings).includes(name) || (asked.includes(name) && (settings[name] === undefined || settings[name] === null)));
+}
+export function checkSettingName(name) {
+    if (!settingNames.includes(name)) {
+        throw new Error(`There is no setting "${name}". The settings are: ${settingNames.join(", ")}.`);
+    }
+    return name;
+}
+/** The YAML list of a list setting, edited in place so that its comments stay; created when missing. */
+function listNode(document, setting) {
+    const node = document.get(setting, true);
+    if (node === undefined || node === null || (isScalar(node) && node.value === null)) {
+        const list = document.createNode([]);
+        document.set(setting, list);
+        return list;
+    }
+    if (isSeq(node)) {
+        // Items written by hand as pairs become the text they were meant to be, and are written back in quotes.
+        node.items = node.items.map((item) => (isMap(item) && pairText(item.toJSON()) !== undefined ? document.createNode(pairText(item.toJSON())) : item));
+    }
+    if (!isSeq(node) || !node.items.every((item) => isScalar(item) && typeof item.value === "string")) {
+        throw new Error(`"${setting}" in ${campaignFileName} is not a list of text; write it by hand as ${setting}: [item, item].`);
+    }
+    return node;
+}
+/** Writes campaign.yaml, if the settings are still valid; long values stay on one line. */
+function saveSettings(root, document) {
+    validateSettings(document.toJS());
+    writeYamlFile(join(root, campaignFileName), document);
+}
+/** "Poisoned: la benda…" for the YAML pair { Poisoned: "la benda…" } that a list item written without quotes becomes; undefined for anything else. */
+function pairText(item) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+        return undefined;
+    }
+    const entries = Object.entries(item);
+    return entries.length === 1 && ["string", "number", "boolean"].includes(typeof entries[0][1]) ? `${entries[0][0]}: ${String(entries[0][1])}` : undefined;
+}
+/** The same item of a list setting, ignoring case, accents written either way and the spaces around it. */
+function sameText(one, other) {
+    return comparableText(one.trim()) === comparableText(other.trim());
+}
+function validateSettings(values) {
+    const parsed = settingsSchema.safeParse(values);
+    if (!parsed.success) {
+        throw new Error(`${campaignFileName} is not valid:\n${z.prettifyError(parsed.error)}\nFix it by hand (a list is written as [item, item]); a single value can also be set with the config command.`);
+    }
+    return parsed.data;
+}
+function readSettingsDocument(root) {
+    return readYamlFile(join(root, campaignFileName), settingsHold);
+}

package/dist/campaign/state.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** The present of the game, kept in state.yaml. Other keys are kept: the scene will add its own. An empty date is no date. */
+declare const stateSchema: z.ZodObject<{
+    date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type CampaignState = z.infer<typeof stateSchema>;
+/** The present of the game; empty before it has one, or when state.yaml is missing. */
+export declare function readState(root: string): CampaignState;
+/** The values of state.yaml as they are written, without checking the game date: what the scene reads, so that a wrong date does not hide it. */
+export declare function readStateValues(root: string): Record<string, unknown>;
+/** Changes the present, keeping the rest of state.yaml, comments included, as it is; an undefined value removes its key. */
+export declare function changeState(root: string, values: Partial<CampaignState>): void;
+/** Changes values inside state.yaml, each at its path, such as ["scene", "round"]; the rest, comments included, stays as it is. An undefined value removes its key. */
+export declare function changeStateAt(root: string, changes: [string[], unknown][]): void;
+export {};

package/dist/campaign/state.js

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { Document, visit } from "yaml";
+import { z } from "zod";
+import { files } from "../core/store.js";
+import { readYamlFile, readYamlValues, writeYamlFile } from "../core/yaml-file.js";
+const stateFileName = "state.yaml";
+const holds = 'the present of the game, such as "date: day 1, 18:00"';
+/** The present of the game, kept in state.yaml. Other keys are kept: the scene will add its own. An empty date is no date. */
+const stateSchema = z.object({
+    date: z.string({ error: "write the game date as text, such as day 1, 18:00" }).nullish(),
+}).loose();
+/** The present of the game; empty before it has one, or when state.yaml is missing. */
+export function readState(root) {
+    const parsed = stateSchema.safeParse(readStateValues(root));
+    if (!parsed.success) {
+        throw new Error(`${stateFileName} is not valid: ${parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}. Fix it by hand.`);
+    }
+    return parsed.data;
+}
+/** The values of state.yaml as they are written, without checking the game date: what the scene reads, so that a wrong date does not hide it. */
+export function readStateValues(root) {
+    const path = join(root, stateFileName);
+    const values = files().exists(path) ? readYamlValues(path, holds) : {};
+    return values !== null && typeof values === "object" ? values : {};
+}
+/** Changes the present, keeping the rest of state.yaml, comments included, as it is; an undefined value removes its key. */
+export function changeState(root, values) {
+    changeStateAt(root, Object.entries(values).map(([key, value]) => [[key], value]));
+}
+/** Changes values inside state.yaml, each at its path, such as ["scene", "round"]; the rest, comments included, stays as it is. An undefined value removes its key. */
+export function changeStateAt(root, changes) {
+    const path = join(root, stateFileName);
+    const document = files().exists(path) ? readYamlFile(path, holds) : new Document({});
+    for (const [keys, value] of changes) {
+        if (value === undefined) {
+            document.deleteIn(keys);
+        }
+        else {
+            document.setIn(keys, value);
+        }
+    }
+    // Collections written from empty ones, such as {}, would stay on one line: state.yaml is written by the engine, in blocks. An empty one stays [] or {}.
+    visit(document, {
+        Map: (_, node) => {
+            node.flow = node.items.length === 0;
+        },
+        Seq: (_, node) => {
+            node.flow = node.items.length === 0;
+        },
+    });
+    writeYamlFile(path, document);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { runCommandLine } from "./command-line.js";
+const args = process.argv.slice(2);
+// "rpg mcp" turns the process into a server for an AI host; everything else is a command.
+if (args.length === 1 && args[0] === "mcp") {
+    // The server and its SDK load only here: every other command starts faster without them (D-194).
+    const { startMcpServer } = await import("./mcp-server.js");
+    await startMcpServer();
+}
+else {
+    const { output, exitCode } = await runCommandLine(args);
+    if (exitCode === 0) {
+        console.log(output);
+    }
+    else {
+        console.error(output);
+    }
+    process.exitCode = exitCode;
+}

package/dist/command-line.d.ts

@@ -0,0 +1,7 @@
+import { type Context } from "./core/context.ts";
+export interface CommandLineResult {
+    output: string;
+    exitCode: number;
+}
+/** The `rpg` command line: finds the command, validates its input, runs it and renders the result. */
+export declare function runCommandLine(argv: string[], context?: Context): Promise<CommandLineResult>;

package/dist/command-line.js

@@ -0,0 +1,140 @@
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { commands } from "./commands/index.js";
+import { defaultContext } from "./core/context.js";
+import { baseType, isBoolean, isList } from "./core/registry.js";
+import { firstSentence } from "./core/text.js";
+import { getVersion } from "./core/version.js";
+import { hostPictures } from "./pictures/index.js";
+// The one command that exists only on the command line: cli.ts starts the server when it comes alone.
+const mcpDescription = "Start the MCP server for an AI host. Through it the host uses these commands as tools; the host starts it, with no options.";
+/** The `rpg` command line: finds the command, validates its input, runs it and renders the result. */
+export async function runCommandLine(argv, context = { ...defaultContext(), pictures: hostPictures(() => undefined) }) {
+    const [commandName, ...args] = argv;
+    if (commandName === undefined || commandName === "--help" || commandName === "-h") {
+        return success(generalHelp());
+    }
+    if (commandName === "--version" || commandName === "-v") {
+        return success(getVersion());
+    }
+    if (commandName === "mcp") {
+        return success(`rpg mcp\n\n${mcpDescription}`);
+    }
+    const command = commands.find((candidate) => candidate.name === commandName);
+    if (!command) {
+        return failure(`Unknown command "${commandName}".\n\n${generalHelp()}`);
+    }
+    if (command.needsPlayer) {
+        return failure(`${command.name} works only in an AI app that shows the player a form; here, ask the player in words.`);
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        return success(commandHelp(command));
+    }
+    try {
+        return success(await runCommand(command, args, context));
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}
+async function runCommand(command, args, context) {
+    const { input, asJson } = readArguments(command, args);
+    const parsed = command.input.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`Invalid input for "${command.name}":\n${z.prettifyError(parsed.error)}\nUsage: ${usage(command)}`);
+    }
+    const result = await command.run(parsed.data, context);
+    return asJson ? JSON.stringify(result, null, 2) : command.format(result);
+}
+function readArguments(command, args) {
+    const positionals = command.positionals ?? [];
+    const options = { json: { type: "boolean" } };
+    for (const [name, field] of inputFields(command)) {
+        if (!positionals.includes(name)) {
+            options[name] = { type: isBoolean(field) ? "boolean" : "string", multiple: isList(field) };
+        }
+    }
+    const parsed = parseArgs({ args, options, allowPositionals: true, strict: true, tokens: true });
+    // The last positional, when it is a list, takes the arguments left before the first option, as in rpg move Ettore Lena --to Ossario.
+    const last = positionals.at(-1);
+    const takesRest = last !== undefined && isList(command.input.shape[last]);
+    const firstOption = parsed.tokens.findIndex((token) => token.kind === "option");
+    const valuesOf = (tokens) => tokens.flatMap((token) => (token.kind === "positional" ? [token.value] : []));
+    const given = takesRest && firstOption !== -1 ? valuesOf(parsed.tokens.slice(0, firstOption)) : parsed.positionals;
+    const extra = takesRest ? valuesOf(parsed.tokens.slice(firstOption === -1 ? parsed.tokens.length : firstOption)) : parsed.positionals.slice(positionals.length);
+    if (extra.length > 0) {
+        const quoted = [...given.slice(positionals.length - 1, positionals.length), ...extra].join(" ");
+        // A text given in several words: quote it. A word from a list, such as open, is not a text.
+        const freeText = last !== undefined && baseType(command.input.shape[last]) === "string";
+        const how = takesRest
+            ? ` Give the ${last} before the options, and repeat an option for each of its values, such as --to A --to B.`
+            : freeText
+                ? ` Put a value with spaces in quotes, such as "${quoted}".`
+                : "";
+        throw new Error(`Unexpected argument: ${extra.join(" ")}.${how}`);
+    }
+    checkRepeatedOptions(parsed.tokens, options);
+    const input = {};
+    for (const [name, value] of Object.entries(parsed.values)) {
+        if (name !== "json") {
+            input[name] = value;
+        }
+    }
+    positionals.forEach((name, index) => {
+        if (given[index] !== undefined) {
+            input[name] = takesRest && name === last ? given.slice(index) : given[index];
+        }
+    });
+    return { input, asJson: parsed.values.json === true };
+}
+/** An option that takes one value must not be given twice: the first value would be lost without a word. */
+function checkRepeatedOptions(tokens, options) {
+    const given = [];
+    for (const token of tokens) {
+        if (token.kind !== "option" || token.name === undefined || options[token.name]?.multiple === true) {
+            continue;
+        }
+        if (given.includes(token.name)) {
+            throw new Error(`Give --${token.name} only once.`);
+        }
+        given.push(token.name);
+    }
+}
+function inputFields(command) {
+    return Object.entries(command.input.shape);
+}
+/** The commands in two groups, each with the first sentence of its description. */
+function generalHelp() {
+    const width = Math.max(...commands.map((command) => command.name.length));
+    const line = (name, description) => `  ${name.padEnd(width)} ${firstSentence(description)}`;
+    const groupLines = (group) => commands.filter((command) => command.group === group && !command.needsPlayer).map((command) => line(command.name, command.description));
+    return [
+        `rpg-engine ${getVersion()}`,
+        "",
+        "Campaign:",
+        ...groupLines("campaign"),
+        line("mcp", mcpDescription),
+        "",
+        "Game:",
+        ...groupLines("game"),
+        "",
+        "Run `rpg <command> --help` for its options.",
+    ].join("\n");
+}
+function commandHelp(command) {
+    const positionals = command.positionals ?? [];
+    const optionLines = inputFields(command).map(([name, field]) => {
+        const flag = positionals.includes(name) ? `<${name}>${isList(field) ? "..." : ""}` : `--${name}${isBoolean(field) ? "" : " <value>"}${isList(field) ? "..." : ""}`;
+        return `  ${flag.padEnd(20)} ${field.description ?? ""}`;
+    });
+    return [usage(command), "", command.description, "", ...optionLines, `  ${"--json".padEnd(20)} print the result as JSON`].join("\n");
+}
+function usage(command) {
+    return ["rpg", command.name, ...(command.positionals ?? []).map((name) => `<${name}>${isList(command.input.shape[name]) ? "..." : ""}`), "[options]"].join(" ");
+}
+function success(output) {
+    return { output, exitCode: 0 };
+}
+function failure(output) {
+    return { output, exitCode: 1 };
+}