rpg-engine 0.0.0-stage → 0.1.1

package/dist/core/command-reference.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "./registry.ts";
+/**
+ * The reference of the commands in markdown, grouped as the registry groups them, each with the first sentence of its description and each parameter as the
+ * MCP server offers it: npm run docs writes it to docs/commands.md. The whole description, written for the AI, stays in the command.
+ */
+export declare function commandReference(commands: Command<any, any>[]): string;

package/dist/core/command-reference.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { firstSentence } from "./text.js";
+const generatedNotice = "<!-- Generated from the definitions of the commands: do not edit it by hand. After changing a command, run npm run docs. -->";
+/**
+ * The reference of the commands in markdown, grouped as the registry groups them, each with the first sentence of its description and each parameter as the
+ * MCP server offers it: npm run docs writes it to docs/commands.md. The whole description, written for the AI, stays in the command.
+ */
+export function commandReference(commands) {
+    const groups = [...new Set(commands.map((command) => command.group))];
+    const sections = groups.map((group) => [`## ${group[0].toUpperCase()}${group.slice(1)}`, ...commands.filter((command) => command.group === group).map(commandSection)].join("\n\n"));
+    return `${[generatedNotice, "# Commands", ...sections].join("\n\n")}\n`;
+}
+function commandSection(command) {
+    const schema = z.toJSONSchema(command.input, { io: "input" });
+    const required = schema.required ?? [];
+    const parameters = Object.entries(schema.properties ?? {}).map(([name, field]) => parameterLine(name, field, required.includes(name)));
+    const positionals = command.positionals?.length ? ` Positional parameters: ${command.positionals.map(code).join(", ")}.` : "";
+    return [`### ${command.name}`, firstSentence(command.description), `Read-only: ${command.readOnly ? "yes" : "no"}.${positionals}`, parameters.length > 0 ? parameters.join("\n") : "No parameters."].join("\n\n");
+}
+function parameterLine(name, field, required) {
+    const description = typeof field === "object" && field.description ? `: ${field.description}` : "";
+    return `- ${code(name)} (${code(typeText(field))}, ${required ? "required" : "optional"})${description}`;
+}
+/** The type of a parameter from its JSON Schema, such as string | string[]. */
+function typeText(schema) {
+    if (schema === undefined || typeof schema === "boolean") {
+        return "any";
+    }
+    if (schema.enum) {
+        return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+    }
+    if (schema.anyOf) {
+        return schema.anyOf.map(typeText).join(" | ");
+    }
+    if (schema.type === "array") {
+        const items = Array.isArray(schema.items) ? "any" : typeText(schema.items);
+        return items.includes(" ") ? `(${items})[]` : `${items}[]`;
+    }
+    if (schema.type === "object") {
+        const values = typeText(schema.additionalProperties);
+        return values === "any" ? "object" : `{ [key]: ${values} }`;
+    }
+    return typeof schema.type === "string" ? schema.type : "any";
+}
+function code(text) {
+    return `\`${text}\``;
+}

package/dist/core/context.d.ts

@@ -0,0 +1,140 @@
+import type { FileStore } from "./store.ts";
+/** What a command needs from the outside world: tests replace it to get repeatable results. */
+export interface Context {
+    /** Folder the command runs in: commands look for the campaign here and in the folders above. */
+    folder: string;
+    /** Rolls one digital die: an integer from 1 to `sides`. */
+    random(sides: number): number;
+    now(): Date;
+    /** A new short id for a line of the log. */
+    newId(): string;
+    /** A new random salt for a hidden roll. */
+    newSalt(): string;
+    /** Who acts: the master, the player or a companion. For now always the master. */
+    actor: string;
+    /** The operating system, as Node names it (win32, linux, darwin): some files differ by it. */
+    platform: string;
+    /** The player, where the surface can ask them directly, as an AI host that shows forms does (D-148); missing elsewhere. */
+    player?: Player;
+    /** The player through the dashboard's page, when the MCP server serves one (D-279): it comes before the form, while a page is open. */
+    page?: Player;
+    /** The call's cancel, as the host sends it when the user stops the call (ASK-9); MCP only. */
+    signal?: AbortSignal;
+    /** The folders that hold the installed game systems, nearest first (SYS-1). */
+    systemFolders: string[];
+    /** The files as the MCP server keeps them for a whole session (D-137, D-193); without it, each call reads them afresh. */
+    files?: FileStore;
+    /** The parts of the instructions already given in this chat, which the MCP server keeps until instructions starts over (D-97); without it, every call gives them. */
+    told?: Set<string>;
+    /** The link of the player's dashboard, when the MCP server serves one (D-270); status gives it. */
+    dashboard?: string;
+    /** Whether status has already had the master offer the dashboard in this chat, as its first status does (D-353). */
+    dashboardOffered?: boolean;
+    /**
+     * What the player changed on the dashboard since the master's last call, taken for the head of the next call's answer, and given back when that answer
+     * never goes, as for a call the user stopped (D-341).
+     */
+    news?: () => {
+        lines: string[];
+        restore(): void;
+    };
+    /** What makes pictures from words on this computer (D-308), as Codex with the player's login; missing where none can, as in tests. */
+    pictures?: PictureMaker;
+    /** What writes text from a brief on this computer, outside the chat, as Codex or Claude Code with the player's login (D-406); missing where none can. */
+    writer?: TextWriter;
+    /** The folder of this player's data on this computer, apart from any campaign: the page's words translated on the fly (D-406). */
+    home?: string;
+    /** The folder of the dashboard's built page, whose i18n/ lists every phrase it has (D-423). */
+    pageFolder?: string;
+    /** Codex and Claude Code on this computer, installed and signed in with the player's yes (D-424); missing outside the MCP server, as in tests. */
+    helpers?: Helpers;
+}
+/** A program of this computer that writes and draws outside the chat, with the player's own login (D-424). */
+export type HelperName = "codex" | "claude";
+/** How a helper program stands: not on this computer, there without the player's login, signed in with an API key, which the engine never uses, or ready. */
+export type HelperState = "missing" | "logged out" | "api key" | "ready";
+/** The player's sign-in of a helper program: waiting for them in the browser, with the link it gave; done; or failed, and why. */
+export type HelperLogin = {
+    state: "waiting";
+    link?: string;
+} | {
+    state: "done";
+} | {
+    state: "failed";
+    why: string;
+};
+/** Codex and Claude Code on this computer (D-424, D-425): how each stands, installing one in the engine's own folder, and the player's sign-in. */
+export interface Helpers {
+    state(name: HelperName): HelperState;
+    /** Installs a program in the engine's folder: undefined once it answers there, else why not. */
+    install(name: HelperName): Promise<string | undefined>;
+    /** Starts the sign-in once, kept alive for ten minutes, and tells how it stands once it gave its link or ended, or after a few seconds. */
+    login(name: HelperName): Promise<HelperLogin>;
+}
+/** What writes text from a brief outside the chat (D-406): whether it can now, and its answer, none when it gave none. */
+export interface TextWriter {
+    ready(): boolean;
+    write(brief: string): Promise<string | undefined>;
+}
+/**
+ * Whether pictures can be made here, or why not, in words the master can tell the player, and in the player's own with the steps to have them, one a line,
+ * numbered, with the commands between backticks (D-341).
+ */
+export type PicturesReady = {
+    ready: true;
+    maker?: "Codex" | "Claude";
+} | {
+    ready: false;
+    why: string;
+    fix?: string;
+};
+/**
+ * What a picture shows (D-308, D-388, D-408): a place as the party sees it arriving, a quest as the character knows it, or the portrait of one of the party as
+ * the player sees them; never what the table keeps out.
+ */
+export interface PictureSubject {
+    kind: "place" | "quest" | "portrait" | "creature";
+    name: string;
+    /** For a portrait or a creature, what the game says they are, as far as the character knows: what their page derives from, and for the party the line under their name. */
+    who?: string;
+    seen: string;
+    unseen: string[];
+}
+/** A picture made: its file, and what to call once it is copied, which clears the maker's own copy. */
+export interface MadePicture {
+    file: string;
+    done(): void;
+}
+/** What makes a picture from a brief: whether it can, and the picture, or why none came. */
+export interface PictureMaker {
+    /** Asked once; with again, a no a minute old or more is asked once more, as after the player logs in. */
+    ready(again?: boolean): PicturesReady;
+    make(subject: PictureSubject): Promise<MadePicture | {
+        refused: string;
+    }>;
+}
+/**
+ * Asks the player one question with buttons: the index of the label they chose; undefined when no one answered; "unavailable" when the surface turned out
+ * unable to show the buttons, so that from then on the master asks in words; "absent" when no one is there to see them now, as a dashboard with no page open.
+ */
+/** The player's own words in place of a button, as the dashboard's page lets them write (ASK-10). */
+export interface Said {
+    said: string;
+}
+/** Whose sheet a roll's checks read, and by button the field each one rolls, for the page to light that row of the sheet (ASK-12). */
+export interface Rows {
+    who: string;
+    fields: (string | null)[];
+}
+/** A square of a place's map the player touched, by its name, such as E4 (ASK-11). */
+export interface Picked {
+    square: string;
+}
+export interface Player {
+    choose(question: string, title: string, labels: string[], signal?: AbortSignal, rows?: Rows): Promise<number | Said | undefined | "unavailable" | "absent">;
+    /** Asks where the player's character moves on the map of its place (ASK-11): the square, the change of mind as its one button (0), or the player's words; only a page can. */
+    chooseSquare?(question: string, title: string, change: string, signal?: AbortSignal): Promise<Picked | 0 | Said | undefined | "absent">;
+    /** Whether a question waits for the player there now, as on the dashboard's page; a form does not say. */
+    asking?(): boolean;
+}
+export declare function defaultContext(folder?: string): Context;

package/dist/core/context.js

@@ -0,0 +1,28 @@
+import { randomBytes, randomInt, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export function defaultContext(folder = process.cwd()) {
+    return {
+        folder,
+        random: (sides) => randomInt(1, sides + 1),
+        now: () => new Date(),
+        newId: () => randomUUID().replaceAll("-", "").slice(0, 8),
+        newSalt: () => randomBytes(16).toString("hex"),
+        actor: "master",
+        platform: process.platform,
+        // From src/core/ and from dist/core/ alike, the package's systems/ folder is two levels up.
+        systemFolders: [fileURLToPath(new URL("../../systems/", import.meta.url))],
+        home: userDataFolder(),
+        // The built page is in dist/dashboard, two levels up from src/core/ and from dist/core/ alike.
+        pageFolder: fileURLToPath(new URL("../../dist/dashboard/", import.meta.url)),
+    };
+}
+/** Where this player's data is kept on this computer (D-406): the folder the system gives a program's data. */
+function userDataFolder() {
+    const home = homedir();
+    if (process.platform === "win32") {
+        return join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "rpg-engine");
+    }
+    return process.platform === "darwin" ? join(home, "Library", "Application Support", "rpg-engine") : join(process.env.XDG_DATA_HOME ?? join(home, ".local", "share"), "rpg-engine");
+}

package/dist/core/field-kind.d.ts

@@ -0,0 +1,6 @@
+/**
+ * How a game system declares one of its fields (SYS-8): a counter, a number that is never counted, a number shown with its sign (a modifier), a bonus that
+ * effects add up (FOR-5), text, a list, or rolls kept to take the place of a later roll (KEP-1).
+ */
+export declare const fieldKinds: readonly ["counter", "number", "modifier", "bonus", "text", "list", "rolls"];
+export type FieldKind = (typeof fieldKinds)[number];

package/dist/core/field-kind.js

@@ -0,0 +1,5 @@
+/**
+ * How a game system declares one of its fields (SYS-8): a counter, a number that is never counted, a number shown with its sign (a modifier), a bonus that
+ * effects add up (FOR-5), text, a list, or rolls kept to take the place of a later roll (KEP-1).
+ */
+export const fieldKinds = ["counter", "number", "modifier", "bonus", "text", "list", "rolls"];

package/dist/core/files.d.ts

@@ -0,0 +1,4 @@
+/** The full paths of `folder` and of the folders inside it, however deep; none when there is no such folder. */
+export declare function foldersIn(folder: string): string[];
+/** The full paths of the files in `folder` and in the folders inside it whose names `keep` takes; none when there is no such folder. */
+export declare function filesIn(folder: string, keep: (name: string) => boolean): string[];

package/dist/core/files.js

@@ -0,0 +1,30 @@
+// The files of a folder and of the folders inside it, listed one folder at a time: listing a whole tree at once looks at every file again on Windows (D-194).
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/** The full paths of `folder` and of the folders inside it, however deep; none when there is no such folder. */
+export function foldersIn(folder) {
+    const folders = existsSync(folder) && statSync(folder).isDirectory() ? [folder] : [];
+    for (let index = 0; index < folders.length; index++) {
+        for (const entry of readdirSync(folders[index], { withFileTypes: true }).filter((candidate) => candidate.isDirectory())) {
+            folders.push(join(folders[index], entry.name));
+        }
+    }
+    return folders;
+}
+/** The full paths of the files in `folder` and in the folders inside it whose names `keep` takes; none when there is no such folder. */
+export function filesIn(folder, keep) {
+    const files = [];
+    const folders = existsSync(folder) && statSync(folder).isDirectory() ? [folder] : [];
+    for (let index = 0; index < folders.length; index++) {
+        for (const entry of readdirSync(folders[index], { withFileTypes: true })) {
+            const path = join(folders[index], entry.name);
+            if (entry.isDirectory()) {
+                folders.push(path);
+            }
+            else if (entry.isFile() && keep(entry.name)) {
+                files.push(path);
+            }
+        }
+    }
+    return files;
+}

package/dist/core/formula.d.ts

@@ -0,0 +1,164 @@
+/** A formula read from its text (FOR-2). */
+export type Formula = {
+    kind: "number";
+    value: number;
+} | {
+    kind: "field";
+    name: string;
+} | {
+    kind: "negate";
+    operand: Formula;
+} | {
+    kind: "operation";
+    operator: "+" | "-" | "*" | "/";
+    left: Formula;
+    right: Formula;
+} | {
+    kind: "math";
+    name: MathName;
+    operands: Formula[];
+} | {
+    kind: "table";
+    table: string;
+    key: Formula;
+} | {
+    kind: "list";
+    name: ListName;
+    list: string;
+    item?: string;
+    where?: {
+        field: string;
+        value: string;
+    };
+} | {
+    kind: "first";
+    options: Formula[];
+};
+/** A table read by value: by number, the highest row not above the key; by name, the row with that name (FOR-2). */
+export interface Table {
+    rows: [string, number][];
+}
+/** What a formula reads: the value of a field as a page holds it, undefined when it holds none; and the tables of its system. */
+export interface FormulaScope {
+    field(name: string): unknown;
+    table(name: string): Table | undefined;
+    /** The fields of the page an item of a list names, such as the class of [[Fighter]] 3, for sum with a field and a value (D-215). */
+    page?(name: string): Record<string, unknown> | undefined;
+}
+/** A value a formula read to work out its result: a field and the number it read, or the dice a roll took from it, a name looked for in a list, or a row of a table. */
+export type FormulaRead = {
+    field: string;
+    value: number;
+    key?: true;
+} | {
+    field: string;
+    dice: string;
+} | {
+    list: string;
+    item: string;
+    value: number;
+} | {
+    list: string;
+    value: number;
+    where?: string;
+    count?: true;
+} | {
+    table: string;
+    key: string;
+    value: number;
+};
+/** A formula worked out: its value, undefined when the page lacks something it needs (FOR-4), and what it read. */
+export interface WorkedOut {
+    value: number | undefined;
+    reads: FormulaRead[];
+}
+/**
+ * What a game system works out (FOR-1): its computed fields, in the order it gives them, its tables, and the limits of its counters, with how much of each comes
+ * back on an occasion, such as a long rest, where the field max is the counter's maximum (DAT-9).
+ */
+export interface SystemFormulas {
+    computed: [string, Formula][];
+    tables: Record<string, Table>;
+    counters: Record<string, {
+        min?: Formula;
+        max?: Formula;
+        refill?: Record<string, Formula>;
+    }>;
+}
+/** What a system.yaml writes of its formulas: computed fields, each a formula, a number or formulas in order, tables, and the limits of counters. */
+export interface FormulaData {
+    computed?: Record<string, number | string | (number | string)[]>;
+    tables?: Record<string, Record<string, number>>;
+    counters?: Record<string, {
+        min?: number | string;
+        max?: number | string;
+        refill?: string | Record<string, number | string>;
+    }>;
+}
+/**
+ * Reads the formulas of a system (FOR-1, FOR-9): each must read as a formula, name only tables the system has, and computed fields must not read each other
+ * in a circle. Refused with the place of the first that does not.
+ */
+export declare function readFormulas(data: FormulaData): SystemFormulas;
+type MathName = "floor" | "ceil" | "min" | "max" | "best";
+type ListName = "has" | "count" | "item" | "sum";
+/** Reads a formula; refused, with where and why, when it does not read as one (FOR-9). */
+export declare function parseFormula(text: string): Formula;
+/** A formula of a page that may begin with dice and end with words, as a weapon's damage "1d8 + str-mod slashing" (PRO-5): its parts. */
+export interface RollFormula {
+    /** The dice it begins with: one choice for 1d8; several for dice(…), of which the largest counts (PRO-5, D-235). None for a plain formula. */
+    dice?: DiceChoice[];
+    /** The formula after the dice; none for dice alone. */
+    formula?: Formula;
+    /** The words it ends with, such as slashing. */
+    words?: string;
+}
+/** One of the dice a roll may begin with (D-235): dice as written, a number, as an unarmed strike's 1, or a field that holds dice, as a monk's martial-arts. */
+export type DiceChoice = {
+    dice: string;
+} | {
+    number: number;
+} | {
+    field: string;
+};
+/**
+ * Reads a formula that may begin with dice, such as 1d8 or 2d6, or with dice(…), the largest of several, such as dice(1d6, martial-arts) (D-235), and end with
+ * words, such as a damage type: "1d8 + str-mod + bonus slashing". Refused, with why, when what is between does not read as a formula (FOR-9).
+ */
+export declare function parseRollFormula(text: string): RollFormula;
+/**
+ * The dice a roll takes (D-235): of its choices, the largest that has a value, by the average it rolls, the first of two alike; a field gives dice it holds,
+ * such as a monk's martial-arts 1d6, or a number. Undefined when none has a value, as martial-arts for one who is no monk.
+ */
+export declare function chosenDice(choices: DiceChoice[], scope: FormulaScope): {
+    dice?: string;
+    number?: number;
+    reads: FormulaRead[];
+} | undefined;
+/** The fields a roll's dice read, as martial-arts in dice(1d6, martial-arts) (D-235). */
+export declare function diceFields(roll: RollFormula): string[];
+/** A formula given as a number or as text, as system.yaml writes it. */
+export declare function formulaOf(value: number | string): Formula;
+/** Works a formula out on what a page holds (FOR-4): no value when a field it needs is missing, a table has no row for the key, or it divides by zero. */
+export declare function workOut(formula: Formula, scope: FormulaScope): WorkedOut;
+/**
+ * What a result came from (FOR-8): the values it read that change it, a number tried higher, lower and at 0, and a list tried empty; a value multiplied by 0,
+ * as a proficiency without the skill, did not count. The rows of tables, and what gives their keys, always count.
+ */
+export declare function contributingReads(formula: Formula, scope: FormulaScope, worked: WorkedOut): FormulaRead[];
+/** The fields a formula reads, lists included, each once and in order: what it comes from. */
+export declare function fieldsRead(formula: Formula): string[];
+/** The tables a formula reads. */
+export declare function tablesRead(formula: Formula): string[];
+/** A table from its rows as system.yaml writes them, `{1: 2, 5: 3}` or `{troublesome: 12}`. */
+export declare function tableOf(rows: Record<string, number>): Table;
+/** The names of the items of a list field, as has, count and item read them (FOR-2): a link as the page or the section it names, without the number after a name. */
+export declare function listItemNames(value: unknown): string[];
+/** The items of a list field with the number after each name, such as Fighter and 3 for [[Fighter]] 3 (FOR-2); a single value is a list of one. */
+export declare function listItems(value: unknown): {
+    name: string;
+    number?: number;
+}[];
+/** A field's value read as a number (FOR-2): a number, a counter's current value, or text such as +2. Undefined for anything else. */
+export declare function numberOf(value: unknown): number | undefined;
+export {};