@px-lsp/protocol 0.2.0 → 0.2.1

package/dist/calendar.d.ts

@@ -10,12 +10,6 @@
  * hover) and the extension (the Insert Date command), unit-tested in plain
  * Node.
  */
-export interface CalendarMonth {
-    /** Display name ("March", "Narvinye"). */
-    name: string;
-    /** Day count; the engine has no leap years, so one number per month. */
-    days: number;
-}
 export interface CalendarSetting {
     /** Script year displayed as year 1 of the `after` era (no year zero). */
     epoch: number;
@@ -24,12 +18,20 @@ export interface CalendarSetting {
     /** Era label for script years < epoch ("BC"). Omitted = single-era
      * calendar: years before the epoch get no display form. */
     before?: string;
-    /** Custom month names and day counts, first month first. Omitted = the
-     * standard 12 months (Feb 28: the engine has no leap years). */
-    months?: CalendarMonth[];
+    /**
+     * The engine's twelve months under the mod's own names, first month first.
+     * Omitted = January to December. Only the NAMES are the mod's: the game has
+     * twelve months of fixed length (31 28 31 30 31 30 31 31 30 31 30 31, no
+     * leap years) and no script can change that, so a date's month and day are
+     * always the engine's and only read differently.
+     */
+    months?: string[];
 }
-export declare const GREGORIAN_MONTHS: CalendarMonth[];
-export declare function monthsOf(cal: CalendarSetting): CalendarMonth[];
+/** Days per engine month; what a script date's day is bounded by. */
+export declare const ENGINE_MONTH_DAYS: number[];
+export declare const GREGORIAN_MONTHS: string[];
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+export declare function monthNames(cal: CalendarSetting): string[];
 /**
  * Validate a calendar straight out of JSON settings (any client, any hand-
  * edited settings file). Returns a clean copy, or undefined when the value is
@@ -42,8 +44,8 @@ export declare function parseScriptDate(text: string): {
     m: number;
     d: number;
 } | null;
-/** Month/day within the calendar's bounds (year just has to be positive). */
-export declare function isValidScriptDate(cal: CalendarSetting, y: number, m: number, d: number): boolean;
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+export declare function isValidScriptDate(y: number, m: number, d: number): boolean;
 /** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
 export declare function displayYear(cal: CalendarSetting, y: number): string | null;
 /**

package/dist/calendar.js

@@ -12,15 +12,16 @@
  * Node.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GREGORIAN_MONTHS = void 0;
-exports.monthsOf = monthsOf;
+exports.GREGORIAN_MONTHS = exports.ENGINE_MONTH_DAYS = void 0;
+exports.monthNames = monthNames;
 exports.sanitizeCalendar = sanitizeCalendar;
 exports.parseScriptDate = parseScriptDate;
 exports.isValidScriptDate = isValidScriptDate;
 exports.displayYear = displayYear;
 exports.displayDate = displayDate;
 exports.convertDisplayInput = convertDisplayInput;
-const DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/** Days per engine month; what a script date's day is bounded by. */
+exports.ENGINE_MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 exports.GREGORIAN_MONTHS = [
     "January",
     "February",
@@ -34,8 +35,9 @@ exports.GREGORIAN_MONTHS = [
     "October",
     "November",
     "December",
-].map((name, i) => ({ name, days: DAYS[i] }));
-function monthsOf(cal) {
+];
+/** The month names a date reads with: the mod's twelve, or the engine's. */
+function monthNames(cal) {
     return cal.months ?? exports.GREGORIAN_MONTHS;
 }
 /**
@@ -61,21 +63,22 @@ function sanitizeCalendar(raw) {
     if (cal.before && cal.before.toLowerCase() === cal.after.toLowerCase())
         return undefined;
     if (Array.isArray(o.months) && o.months.length > 0) {
+        // Exactly the engine's twelve. A name may still arrive as the older
+        // `{ name, days }` object; its day count never meant anything to the
+        // game and is dropped.
+        if (o.months.length !== exports.GREGORIAN_MONTHS.length)
+            return undefined;
         const months = [];
         const seen = new Set();
         for (const m of o.months) {
-            if (typeof m !== "object" || m === null)
-                return undefined;
-            const { name, days } = m;
+            const name = typeof m === "string" ? m : (m?.name ?? null);
             if (typeof name !== "string" || name.trim() === "")
                 return undefined;
-            if (typeof days !== "number" || !Number.isInteger(days) || days < 1 || days > 999)
-                return undefined;
             const key = name.trim().toLowerCase();
             if (seen.has(key))
                 return undefined;
             seen.add(key);
-            months.push({ name: name.trim(), days });
+            months.push(name.trim());
         }
         cal.months = months;
     }
@@ -88,10 +91,9 @@ function parseScriptDate(text) {
         return null;
     return { y: Number(match[1]), m: Number(match[2]), d: Number(match[3]) };
 }
-/** Month/day within the calendar's bounds (year just has to be positive). */
-function isValidScriptDate(cal, y, m, d) {
-    const months = monthsOf(cal);
-    return y >= 1 && m >= 1 && m <= months.length && d >= 1 && d <= months[m - 1].days;
+/** A date the engine reads: a positive year, one of its twelve months, a day that month has. */
+function isValidScriptDate(y, m, d) {
+    return y >= 1 && m >= 1 && m <= exports.ENGINE_MONTH_DAYS.length && d >= 1 && d <= exports.ENGINE_MONTH_DAYS[m - 1];
 }
 /** Era-mapped year: "1000 BC". Null for pre-epoch years of a single-era calendar. */
 function displayYear(cal, y) {
@@ -105,25 +107,23 @@ function displayYear(cal, y) {
  * date does not fit the calendar.
  */
 function displayDate(cal, y, m, d) {
-    if (!isValidScriptDate(cal, y, m, d))
+    if (!isValidScriptDate(y, m, d))
         return null;
     const year = displayYear(cal, y);
     if (!year)
         return null;
     if (m === 1 && d === 1)
         return year;
-    return `${d} ${monthsOf(cal)[m - 1].name} ${year}`;
+    return `${d} ${monthNames(cal)[m - 1]} ${year}`;
 }
 /** Case-insensitive month lookup: exact name, else unique prefix. */
 function monthByName(cal, text) {
     const needle = text.toLowerCase();
-    const months = monthsOf(cal);
-    const exact = months.findIndex((m) => m.name.toLowerCase() === needle);
+    const months = monthNames(cal);
+    const exact = months.findIndex((m) => m.toLowerCase() === needle);
     if (exact >= 0)
         return exact + 1;
-    const prefixed = months
-        .map((m, i) => ({ m, i }))
-        .filter(({ m }) => m.name.toLowerCase().startsWith(needle));
+    const prefixed = months.map((m, i) => ({ m, i })).filter(({ m }) => m.toLowerCase().startsWith(needle));
     return prefixed.length === 1 ? prefixed[0].i + 1 : null;
 }
 /**
@@ -173,11 +173,10 @@ function convertDisplayInput(cal, input) {
     const y = era === cal.after ? year + cal.epoch - 1 : cal.epoch - year;
     if (y < 1)
         return { ok: false, error: `${year} ${era} is before script year 1 (epoch ${cal.epoch})` };
-    if (!isValidScriptDate(cal, y, m, d)) {
-        const months = monthsOf(cal);
-        return m >= 1 && m <= months.length
-            ? { ok: false, error: `${months[m - 1].name} has ${months[m - 1].days} days` }
-            : { ok: false, error: `this calendar has ${months.length} months` };
+    if (!isValidScriptDate(y, m, d)) {
+        return m >= 1 && m <= exports.ENGINE_MONTH_DAYS.length
+            ? { ok: false, error: `${monthNames(cal)[m - 1]} has ${exports.ENGINE_MONTH_DAYS[m - 1]} days` }
+            : { ok: false, error: `the game has ${exports.ENGINE_MONTH_DAYS.length} months` };
     }
     return { ok: true, script: `${y}.${m}.${d}`, display: displayDate(cal, y, m, d) };
 }

package/dist/calendarFile.d.ts

@@ -0,0 +1,26 @@
+import { type CalendarSetting } from "./calendar";
+import { type ConfigDirNames } from "./configDir";
+export declare const CALENDAR_FILE = "calendar.json";
+export interface CalendarFile {
+    /** Where the declaration was read from (or would be written to). */
+    file: string;
+    /** The declared calendar, when the file parses and sanitizes. */
+    calendar?: CalendarSetting;
+    /** Why an existing file yields no calendar: unparsable JSON or an unusable shape. */
+    error?: string;
+}
+/** The path the file is read from: the mod's config dir (legacy name included). */
+export declare function calendarFilePath(modRoot: string, names: ConfigDirNames): string;
+/**
+ * Read `<mod>/.px-toolkit/calendar.json`. Null when the file does not exist;
+ * a `CalendarFile` without `calendar` when it exists but is not usable, so a
+ * client can say so instead of silently showing no dates.
+ */
+export declare function readCalendarFile(modRoot: string, names: ConfigDirNames): CalendarFile | null;
+/**
+ * Write the declaration into the mod (renaming a legacy config dir first,
+ * like every other config-dir write). Returns the file path.
+ */
+export declare function writeCalendarFile(modRoot: string, names: ConfigDirNames, cal: CalendarSetting): string;
+/** True when `fsPath` is a calendar declaration file (any config dir name). */
+export declare function isCalendarFile(fsPath: string, names: ConfigDirNames): boolean;

package/dist/calendarFile.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALENDAR_FILE = void 0;
+exports.calendarFilePath = calendarFilePath;
+exports.readCalendarFile = readCalendarFile;
+exports.writeCalendarFile = writeCalendarFile;
+exports.isCalendarFile = isCalendarFile;
+/**
+ * The per-mod calendar declaration: `<mod>/.px-toolkit/calendar.json`, the
+ * JSON form of calendar.ts `CalendarSetting`. A display calendar is a fact
+ * about the mod, so it travels with the mod (committed, one per mod, read by
+ * every client and by the server itself) instead of living in one editor's
+ * window-scoped `px.calendar` setting. The setting stays as the fallback for
+ * a mod without the file.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const calendar_1 = require("./calendar");
+const configDir_1 = require("./configDir");
+exports.CALENDAR_FILE = "calendar.json";
+/** The path the file is read from: the mod's config dir (legacy name included). */
+function calendarFilePath(modRoot, names) {
+    return path.join((0, configDir_1.resolveConfigDir)(modRoot, names), exports.CALENDAR_FILE);
+}
+/**
+ * Read `<mod>/.px-toolkit/calendar.json`. Null when the file does not exist;
+ * a `CalendarFile` without `calendar` when it exists but is not usable, so a
+ * client can say so instead of silently showing no dates.
+ */
+function readCalendarFile(modRoot, names) {
+    const file = calendarFilePath(modRoot, names);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
+    }
+    catch (err) {
+        return { file, error: `not valid JSON (${err.message})` };
+    }
+    const calendar = (0, calendar_1.sanitizeCalendar)(raw);
+    if (!calendar) {
+        return {
+            file,
+            error: 'not a usable calendar: needs a whole-number "epoch" (1 or more), a non-empty "after" era label, ' +
+                'a "before" label different from "after" when present, and, when "months" is given, exactly twelve distinct names',
+        };
+    }
+    return { file, calendar };
+}
+/**
+ * Write the declaration into the mod (renaming a legacy config dir first,
+ * like every other config-dir write). Returns the file path.
+ */
+function writeCalendarFile(modRoot, names, cal) {
+    const dir = (0, configDir_1.migrateConfigDir)(modRoot, names);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, exports.CALENDAR_FILE);
+    fs.writeFileSync(file, JSON.stringify(cal, null, 2) + "\n", "utf8");
+    return file;
+}
+/** True when `fsPath` is a calendar declaration file (any config dir name). */
+function isCalendarFile(fsPath, names) {
+    const parts = fsPath.split(/[\\/]/);
+    if (parts.length < 2 || parts[parts.length - 1].toLowerCase() !== exports.CALENDAR_FILE)
+        return false;
+    const dir = parts[parts.length - 2].toLowerCase();
+    return dir === names.configDirName.toLowerCase() || dir === names.legacyConfigDirName?.toLowerCase();
+}

package/dist/calendarLoc.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CAL_ERA_KEY = exports.CAL_YEAR_KEY = void 0;
 exports.generateCalendarLoc = generateCalendarLoc;
-const calendar_1 = require("./calendar");
 /** Keys the generated files define; exported so tests and docs stay in sync. */
 exports.CAL_YEAR_KEY = "PX_CAL_YEAR";
 exports.CAL_ERA_KEY = "PX_CAL_ERA";
@@ -72,23 +71,20 @@ function generateCalendarLoc(cal, spec, lang) {
         overrideLines.push(` ${key}:0 "${value}"`);
     }
     if (cal.months) {
-        const months = (0, calendar_1.monthsOf)(cal);
+        const months = cal.months;
         if (!spec.monthKeys) {
             notes.push("This game's month-name keys are not mapped yet; custom month names were not generated.");
         }
-        else if (months.length !== spec.monthKeys.length) {
-            notes.push(`The engine has exactly ${spec.monthKeys.length} months; your calendar declares ${months.length}, ` +
-                "so month names were not generated (the month count itself cannot be modded).");
-        }
         else {
+            // The calendar carries the engine's twelve names (sanitizeCalendar); the
+            // spec lists the keys of the months it knows, first month first.
             overrideLines.push(" # Engine month names (long and abbreviated forms both get the custom name).");
-            months.forEach((m, i) => {
-                const [long, short] = spec.monthKeys[i];
-                overrideLines.push(` ${long}:0 "${m.name.replace(/"/g, '\\"')}"`);
+            spec.monthKeys.forEach(([long, short], i) => {
+                const name = months[i].replace(/"/g, '\\"');
+                overrideLines.push(` ${long}:0 "${name}"`);
                 if (short !== long)
-                    overrideLines.push(` ${short}:0 "${m.name.replace(/"/g, '\\"')}"`);
+                    overrideLines.push(` ${short}:0 "${name}"`);
             });
-            notes.push("Month day counts are engine-fixed (31/28/31...); custom day counts only affect the editor's display.");
         }
     }
     notes.push(`Generated for '${lang}' only; other languages the mod ships need the same overrides in their replace folder.`);

package/dist/configDir.d.ts

@@ -0,0 +1,17 @@
+export declare const PX_CONFIG_DIR = ".px-toolkit";
+export interface ConfigDirNames {
+    configDirName: string;
+    /** The pre-0.4.0 per-game name, still read as a fallback. */
+    legacyConfigDirName?: string;
+}
+/**
+ * The config dir to READ from: the current name when it exists, else the
+ * legacy one when that exists, else the current name. Never touches disk.
+ */
+export declare function resolveConfigDir(root: string, names: ConfigDirNames): string;
+/**
+ * The config dir to WRITE to. Renames a legacy dir to the current name first;
+ * if the rename fails (locked file, read-only parent) the legacy dir stays in
+ * use so the write still lands where reads look.
+ */
+export declare function migrateConfigDir(root: string, names: ConfigDirNames): string;

package/dist/configDir.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PX_CONFIG_DIR = void 0;
+exports.resolveConfigDir = resolveConfigDir;
+exports.migrateConfigDir = migrateConfigDir;
+/**
+ * The toolkit's per-mod config dir: `<mod>/.px-toolkit/`, holding
+ * `workshop.json`, `schema.json`, `playset.json`, the tiger baseline, the GUI
+ * preview values and the Workshop listing folder. Mods created before 0.4.0
+ * have a per-game name instead (each GameMeta's `legacyConfigDirName`);
+ * reads keep finding it, and the first write renames it.
+ *
+ * No `vscode` imports: unit-tested in plain Node.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.PX_CONFIG_DIR = ".px-toolkit";
+/**
+ * The config dir to READ from: the current name when it exists, else the
+ * legacy one when that exists, else the current name. Never touches disk.
+ */
+function resolveConfigDir(root, names) {
+    const current = path.join(root, names.configDirName);
+    if (!names.legacyConfigDirName || fs.existsSync(current))
+        return current;
+    const legacy = path.join(root, names.legacyConfigDirName);
+    return fs.existsSync(legacy) ? legacy : current;
+}
+/**
+ * The config dir to WRITE to. Renames a legacy dir to the current name first;
+ * if the rename fails (locked file, read-only parent) the legacy dir stays in
+ * use so the write still lands where reads look.
+ */
+function migrateConfigDir(root, names) {
+    const current = path.join(root, names.configDirName);
+    const resolved = resolveConfigDir(root, names);
+    if (resolved === current)
+        return current;
+    try {
+        fs.renameSync(resolved, current);
+        return current;
+    }
+    catch {
+        return resolved;
+    }
+}