@px-lsp/protocol 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @px-lsp/protocol
+
+The wire contract of the [px-lsp language server](https://github.com/JDeffner/paradox-modding-toolkit):
+custom LSP request/notification names, their payload types, the settings and
+initialization-option shapes, plus a few pure helpers shared between the
+server and its clients (tiger report parsing, `.mod` descriptor parsing,
+diagnostic suppression, localization helpers).
+
+The published package ships compiled JavaScript with type declarations, so it
+works from plain Node and from any bundler:
+
+```ts
+// The root export is the wire contract (request/notification names + payload types):
+import { modOverviewRequest, type ModOverview } from "@px-lsp/protocol";
+// The helpers live in named modules:
+import { parseTigerJson } from "@px-lsp/protocol/tigerParser";
+import { parseDescriptor } from "@px-lsp/protocol/descriptorMod";
+```
+
+Clients in other languages should code against the documented contract instead:
+see [`docs/PROTOCOL.md`](https://github.com/JDeffner/paradox-modding-toolkit/blob/main/docs/PROTOCOL.md)
+in the repository. Changes to the wire contract are treated as API changes
+and versioned with the packages.
+
+License: GPL-3.0-or-later.

package/dist/arrays.d.ts

@@ -0,0 +1,13 @@
+/** Array helpers shared by the server and the client. */
+/**
+ * Append every element of `source` to `target`.
+ *
+ * `target.push(...source)` passes one argument per element and throws
+ * `RangeError: Maximum call stack size exceeded` past ~125k elements (measured,
+ * node 24, default stack). On the index paths that is a size-triggered crash:
+ * one engine/vanilla root already carries ~460k definitions and one generated
+ * mod file can carry six figures on its own. The loop has no ceiling and
+ * measures the same as the spread (2M elements appended in 10k pieces: 23 ms
+ * loop vs 22 ms spread; as one 500k piece: 5.5 ms loop vs 9.6 ms spread).
+ */
+export declare function pushAll<T>(target: T[], source: readonly T[]): void;

package/dist/arrays.js

@@ -0,0 +1,19 @@
+"use strict";
+/** Array helpers shared by the server and the client. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushAll = pushAll;
+/**
+ * Append every element of `source` to `target`.
+ *
+ * `target.push(...source)` passes one argument per element and throws
+ * `RangeError: Maximum call stack size exceeded` past ~125k elements (measured,
+ * node 24, default stack). On the index paths that is a size-triggered crash:
+ * one engine/vanilla root already carries ~460k definitions and one generated
+ * mod file can carry six figures on its own. The loop has no ceiling and
+ * measures the same as the spread (2M elements appended in 10k pieces: 23 ms
+ * loop vs 22 ms spread; as one 500k piece: 5.5 ms loop vs 9.6 ms spread).
+ */
+function pushAll(target, source) {
+    for (let i = 0; i < source.length; i++)
+        target.push(source[i]);
+}

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Constants needed on both sides of the LSP boundary.
+ */
+import type { TokenKind } from "./types";
+/** The script_docs log files and the token kind each one contributes. */
+export declare const LOG_FILES: Array<{
+    file: string;
+    kind: TokenKind;
+}>;

package/dist/constants.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_FILES = void 0;
+/** The script_docs log files and the token kind each one contributes. */
+exports.LOG_FILES = [
+    { file: "triggers.log", kind: "trigger" },
+    { file: "effects.log", kind: "effect" },
+    { file: "event_targets.log", kind: "event_target" },
+    { file: "modifiers.log", kind: "modifier" },
+];

package/dist/descriptorMetadata.d.ts

@@ -0,0 +1,51 @@
+/** Mod-root-relative path of the descriptor, forward slashes. */
+export declare const METADATA_REL_PATH = ".metadata/metadata.json";
+/** One entry of `relationships`: a link to another mod. */
+export interface MetadataRelationship {
+    /** "dependency", "incompatible_with", "load_before", "load_after". */
+    rel_type: string;
+    /** The other mod's `id` field (NOT its Workshop number). */
+    id: string;
+    /** Shown when the other mod is not on disk. */
+    display_name?: string;
+    /** Only "mod" is supported by the launcher today. */
+    resource_type: string;
+    /** Version of the other mod, `*` for any. */
+    version?: string;
+}
+/** The fields of a mod's metadata.json this toolkit reads or writes. */
+export interface ModMetadata {
+    name?: string;
+    id?: string;
+    version?: string;
+    supported_game_version?: string;
+    short_description?: string;
+    tags?: string[];
+    relationships?: MetadataRelationship[];
+    game_custom_data?: {
+        multiplayer_synchronized?: boolean;
+        replace_paths?: string[];
+    };
+}
+/** The parsed `<dir>/.metadata/metadata.json`, or null when absent/unreadable. */
+export declare function readMetadata(dir: string): ModMetadata | null;
+/** The mod's display name from `<dir>/.metadata/metadata.json`, or null. */
+export declare function readMetadataName(dir: string): string | null;
+/** True when `dir` carries a metadata-style descriptor. */
+export declare function hasMetadataDescriptor(dir: string): boolean;
+export interface MetadataScaffold {
+    name: string;
+    /** Stable identifier other mods point their relationships at. */
+    id: string;
+    /** The mod's own version, not the game's. */
+    version?: string;
+    /** Game version the mod is for, `*` when unknown. */
+    supportedGameVersion: string;
+    shortDescription?: string;
+    tags?: string[];
+    relationships?: MetadataRelationship[];
+    /** Vanilla folders the mod unloads wholesale (total conversions). */
+    replacePaths?: string[];
+}
+/** A launcher-correct starter metadata.json, in the corpus's field order. */
+export declare function scaffoldMetadata(opts: MetadataScaffold): string;

package/dist/descriptorMetadata.js

@@ -0,0 +1,98 @@
+"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.METADATA_REL_PATH = void 0;
+exports.readMetadata = readMetadata;
+exports.readMetadataName = readMetadataName;
+exports.hasMetadataDescriptor = hasMetadataDescriptor;
+exports.scaffoldMetadata = scaffoldMetadata;
+/**
+ * Reader and writer for the newer Paradox mod descriptor convention:
+ * `<mod>/.metadata/metadata.json` (newer titles) instead of the launcher
+ * `.mod` file. Fail-soft on read: any read/parse problem yields null.
+ *
+ * The field set is copied from three real workshop mods (2026-08-12: name, id,
+ * version, supported_game_version, tags, relationships, game_custom_data;
+ * `game_id` appears in one of the three and is left out here because the other
+ * two load without it). The relationship shape is the one the Community Mod
+ * Framework documents for the mods that depend on it.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Mod-root-relative path of the descriptor, forward slashes. */
+exports.METADATA_REL_PATH = ".metadata/metadata.json";
+/** The parsed `<dir>/.metadata/metadata.json`, or null when absent/unreadable. */
+function readMetadata(dir) {
+    try {
+        const file = path.join(dir, ".metadata", "metadata.json");
+        if (!fs.existsSync(file))
+            return null;
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** The mod's display name from `<dir>/.metadata/metadata.json`, or null. */
+function readMetadataName(dir) {
+    const name = readMetadata(dir)?.name;
+    return typeof name === "string" && name.trim() !== "" ? name : null;
+}
+/** True when `dir` carries a metadata-style descriptor. */
+function hasMetadataDescriptor(dir) {
+    try {
+        return fs.existsSync(path.join(dir, ".metadata", "metadata.json"));
+    }
+    catch {
+        return false;
+    }
+}
+/** A launcher-correct starter metadata.json, in the corpus's field order. */
+function scaffoldMetadata(opts) {
+    const body = {
+        name: opts.name,
+        id: opts.id,
+        version: opts.version ?? "0.1.0",
+        supported_game_version: opts.supportedGameVersion,
+        ...(opts.shortDescription ? { short_description: opts.shortDescription } : {}),
+        tags: opts.tags ?? [],
+        relationships: opts.relationships ?? [],
+        game_custom_data: {
+            multiplayer_synchronized: true,
+            ...(opts.replacePaths && opts.replacePaths.length > 0 ? { replace_paths: opts.replacePaths } : {}),
+        },
+    };
+    return JSON.stringify(body, null, 2) + "\n";
+}

package/dist/descriptorMod.d.ts

@@ -0,0 +1,66 @@
+export interface DescriptorField {
+    key: string;
+    /** Launcher refuses/misbehaves without it. */
+    required: boolean;
+    /** May appear multiple times (replace_path). */
+    repeatable: boolean;
+    /** Only meaningful in the outer `<name>.mod` file, ignored in descriptor.mod. */
+    outerOnly: boolean;
+    /** One-line label shown next to the completion item. */
+    summary: string;
+    /** Markdown: what the value means and what to put in. */
+    doc: string;
+    /** VS Code snippet inserted on completion (placeholder = example value). */
+    snippet: string;
+}
+export declare const DESCRIPTOR_FIELDS: DescriptorField[];
+export declare const DESCRIPTOR_FIELD_MAP: ReadonlyMap<string, DescriptorField>;
+/** The launcher's fixed tag categories (Mod_structure wiki page, launcher UI). */
+export declare const LAUNCHER_TAGS: string[];
+export interface DescriptorEntry {
+    key: string;
+    /** 0-based line of the key. */
+    line: number;
+    /** Column range of the key on its line. */
+    startCol: number;
+    endCol: number;
+    /** Raw text right of `=` (trimmed, quotes kept), "" when the value is a block. */
+    value: string;
+}
+/**
+ * Line-based parse of the flat key=value format. Only top-level keys are
+ * entries; lines inside a `{ }` block (tags, dependencies) are skipped.
+ */
+export declare function parseDescriptor(text: string): DescriptorEntry[];
+export interface DescriptorIssue {
+    code: "descriptor-missing-field" | "descriptor-unknown-key" | "descriptor-duplicate-key" | "descriptor-path-ignored";
+    severity: "error" | "warning";
+    line: number;
+    startCol: number;
+    endCol: number;
+    message: string;
+}
+/**
+ * Structural checks on a .mod file. Everything here is certain: the key set is
+ * closed (launcher docs) and required-ness is the launcher's own behavior.
+ */
+export declare function validateDescriptor(text: string, opts: {
+    isDescriptorFile: boolean;
+}): DescriptorIssue[];
+/**
+ * The mod's display name from `<dir>/descriptor.mod` (`name="..."`), or null
+ * when the file or field is missing/unreadable. Lets UI surfaces say WHICH mod
+ * something comes from ("Community Flavor Pack") instead of a generic "mod".
+ */
+export declare function readDescriptorName(dir: string): string | null;
+/**
+ * The mod names inside `<dir>/descriptor.mod`'s `dependencies={ "A" "B" }`
+ * block, in file order; empty when the file or the block is missing. The
+ * launcher matches these against the other mods' `name=`, not against their
+ * Workshop id, so that is what the caller compares them with.
+ */
+export declare function readDescriptorDependencies(dir: string): string[];
+/** "1.19.0.6" -> "1.19.*" (the wildcard form that survives hotfixes). */
+export declare function wildcardVersion(raw: string): string | null;
+/** A launcher-correct starter descriptor.mod. */
+export declare function scaffoldDescriptor(modName: string, supportedVersion: string): string;

package/dist/descriptorMod.js

@@ -0,0 +1,335 @@
+"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.LAUNCHER_TAGS = exports.DESCRIPTOR_FIELD_MAP = exports.DESCRIPTOR_FIELDS = void 0;
+exports.parseDescriptor = parseDescriptor;
+exports.validateDescriptor = validateDescriptor;
+exports.readDescriptorName = readDescriptorName;
+exports.readDescriptorDependencies = readDescriptorDependencies;
+exports.wildcardVersion = wildcardVersion;
+exports.scaffoldDescriptor = scaffoldDescriptor;
+/**
+ * Knowledge table + validator for Paradox launcher `.mod` descriptor files
+ * (`descriptor.mod` inside the mod folder, `<name>.mod` next to it).
+ *
+ * The key set and tag list come from the official launcher docs
+ * (the Mod_structure page on the official wiki) cross-checked against 86 real .mod
+ * files (launcher-generated + Workshop). No vscode imports: unit-testable.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.DESCRIPTOR_FIELDS = [
+    {
+        key: "name",
+        required: true,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Display name in the launcher and on Steam Workshop",
+        doc: "The name players see in the launcher's mod list and on the Workshop page. " +
+            "Needs at least 3 characters for a Workshop upload.\n\n" +
+            '```\nname="My Mod"\n```',
+        snippet: 'name="${1:My Mod}"',
+    },
+    {
+        key: "version",
+        required: true,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Your mod's own version number (NOT the game version)",
+        doc: "Free-form version string shown in the launcher. Bump it when you release " +
+            "an update so players can tell versions apart. This is about your mod, " +
+            "not the game - the game version goes in `supported_version`.\n\n" +
+            '```\nversion="0.1.0"\n```',
+        snippet: 'version="${1:0.1.0}"',
+    },
+    {
+        key: "supported_version",
+        required: true,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Newest game version the mod works with",
+        doc: "The launcher compares this against the installed game and marks the mod " +
+            "out of date when the game is newer. A `*` wildcard keeps the mod valid " +
+            "for every hotfix of a patch.\n\n" +
+            '```\nsupported_version="1.19.*"\n```',
+        snippet: 'supported_version="${1:1.19.*}"',
+    },
+    {
+        key: "tags",
+        required: false,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Launcher / Workshop category tags (one quoted tag per line)",
+        doc: "Categories players can filter by in the launcher and on the Workshop. " +
+            "Pick from the launcher's list (completion inside the block offers all of " +
+            "them); a Workshop upload needs at least one.\n\n" +
+            '```\ntags={\n\t"Gameplay"\n\t"Events"\n}\n```',
+        snippet: 'tags={\n\t"${1:Gameplay}"\n}',
+    },
+    {
+        key: "path",
+        required: false,
+        repeatable: false,
+        outerOnly: true,
+        summary: "Where the mod folder is - outer <name>.mod file only",
+        doc: "Tells the launcher where the mod's files live. Absolute or relative to " +
+            "the game's user directory, forward slashes only.\n\n" +
+            "**Leave this line out of `descriptor.mod`** - it is ignored there, and a " +
+            "copied absolute path breaks when the mod is shared.\n\n" +
+            '```\npath="mod/my_mod"\n```',
+        snippet: 'path="${1:mod/my_mod}"',
+    },
+    {
+        key: "remote_file_id",
+        required: false,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Steam Workshop item ID (set automatically on first upload)",
+        doc: "Links the local mod to its Workshop page so updates go to the same item. " +
+            "The launcher fills this in when you first upload - you only ever set it " +
+            "by hand to reconnect a mod to an existing Workshop item. Digits only.\n\n" +
+            '```\nremote_file_id="2962333032"\n```',
+        snippet: 'remote_file_id="${1:123456789}"',
+    },
+    {
+        key: "picture",
+        required: false,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Launcher thumbnail image (file inside the mod folder)",
+        doc: "Image shown next to the mod in the launcher. Steam Workshop ignores it " +
+            "and always uses `thumbnail.png` in the mod root instead (1:1, max 1 MB).\n\n" +
+            '```\npicture="thumbnail.png"\n```',
+        snippet: 'picture="${1:thumbnail.png}"',
+    },
+    {
+        key: "replace_path",
+        required: false,
+        repeatable: true,
+        outerOnly: false,
+        summary: "Unload an entire vanilla folder (repeat per folder)",
+        doc: "The game skips every vanilla file under this folder, so only your mod's " +
+            "version of it exists. One line per folder, forward slashes, relative to " +
+            "the game root. Used by total conversions to drop vanilla history, " +
+            "titles, cultures etc. wholesale - do not use it for ordinary overrides.\n\n" +
+            '```\nreplace_path="history/characters"\nreplace_path="common/landed_titles"\n```',
+        snippet: 'replace_path="${1:history/characters}"',
+    },
+    {
+        key: "dependencies",
+        required: false,
+        repeatable: false,
+        outerOnly: false,
+        summary: "Mods that must load BEFORE this one",
+        doc: "The launcher sorts every listed mod above this one in the load order. " +
+            "Use the exact `name` of the other mod, one quoted name per line. Mostly " +
+            "for submods and compatibility patches.\n\n" +
+            '```\ndependencies={\n\t"A Game of Thrones"\n}\n```',
+        snippet: 'dependencies={\n\t"${1:Name of the parent mod}"\n}',
+    },
+];
+exports.DESCRIPTOR_FIELD_MAP = new Map(exports.DESCRIPTOR_FIELDS.map((f) => [f.key, f]));
+/** The launcher's fixed tag categories (Mod_structure wiki page, launcher UI). */
+exports.LAUNCHER_TAGS = [
+    "Alternative History",
+    "Balance",
+    "Bookmarks",
+    "Character Focuses",
+    "Character Interactions",
+    "Culture",
+    "Decisions",
+    "Events",
+    "Fixes",
+    "Gameplay",
+    "Graphics",
+    "Historical",
+    "Map",
+    "Portraits",
+    "Religion",
+    "Schemes",
+    "Sound",
+    "Total Conversion",
+    "Translation",
+    "Utilities",
+    "Warfare",
+];
+/**
+ * Line-based parse of the flat key=value format. Only top-level keys are
+ * entries; lines inside a `{ }` block (tags, dependencies) are skipped.
+ */
+function parseDescriptor(text) {
+    const entries = [];
+    let depth = 0;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const noComment = line.replace(/#.*$/, "");
+        if (depth === 0) {
+            // Tolerate a UTF-8 BOM on the first line.
+            const m = /^(\uFEFF?\s*)([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(noComment);
+            if (m) {
+                const startCol = m[1].length;
+                entries.push({
+                    key: m[2],
+                    line: i,
+                    startCol,
+                    endCol: startCol + m[2].length,
+                    value: m[3].trim().startsWith("{") ? "" : m[3].trim(),
+                });
+            }
+        }
+        for (const ch of noComment) {
+            if (ch === "{")
+                depth++;
+            else if (ch === "}")
+                depth = Math.max(0, depth - 1);
+        }
+    }
+    return entries;
+}
+/**
+ * Structural checks on a .mod file. Everything here is certain: the key set is
+ * closed (launcher docs) and required-ness is the launcher's own behavior.
+ */
+function validateDescriptor(text, opts) {
+    const issues = [];
+    const entries = parseDescriptor(text);
+    const seen = new Map();
+    for (const e of entries) {
+        const field = exports.DESCRIPTOR_FIELD_MAP.get(e.key);
+        const at = { line: e.line, startCol: e.startCol, endCol: e.endCol };
+        if (!field) {
+            issues.push({
+                code: "descriptor-unknown-key",
+                severity: "warning",
+                ...at,
+                message: `'${e.key}' is not a .mod descriptor key; the launcher ignores it.`,
+            });
+            continue;
+        }
+        if (seen.has(e.key) && !field.repeatable) {
+            issues.push({
+                code: "descriptor-duplicate-key",
+                severity: "warning",
+                ...at,
+                message: `'${e.key}' appears more than once; only the last value counts.`,
+            });
+        }
+        seen.set(e.key, e);
+        if (e.key === "path" && opts.isDescriptorFile) {
+            issues.push({
+                code: "descriptor-path-ignored",
+                severity: "warning",
+                ...at,
+                message: "path= belongs in the outer <name>.mod file; inside descriptor.mod the launcher ignores it, " +
+                    "and a machine-specific path leaks when the mod is shared.",
+            });
+        }
+    }
+    for (const field of exports.DESCRIPTOR_FIELDS) {
+        if (!field.required || seen.has(field.key))
+            continue;
+        // supported_version: the launcher still lists the mod, it just cannot
+        // check compatibility - a warning, not an error.
+        const isHard = field.key !== "supported_version";
+        issues.push({
+            code: "descriptor-missing-field",
+            severity: isHard ? "error" : "warning",
+            line: 0,
+            startCol: 0,
+            endCol: 200,
+            message: isHard
+                ? `Missing ${field.key}= - the launcher needs it to list the mod.`
+                : "Missing supported_version= - the launcher cannot tell which game version the mod is for.",
+        });
+    }
+    return issues;
+}
+/**
+ * The mod's display name from `<dir>/descriptor.mod` (`name="..."`), or null
+ * when the file or field is missing/unreadable. Lets UI surfaces say WHICH mod
+ * something comes from ("Community Flavor Pack") instead of a generic "mod".
+ */
+function readDescriptorName(dir) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(dir, "descriptor.mod"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const entry = parseDescriptor(text).find((e) => e.key === "name");
+    if (!entry)
+        return null;
+    const value = entry.value.replace(/^"([^]*)"$/, "$1").trim();
+    return value === "" ? null : value;
+}
+/**
+ * The mod names inside `<dir>/descriptor.mod`'s `dependencies={ "A" "B" }`
+ * block, in file order; empty when the file or the block is missing. The
+ * launcher matches these against the other mods' `name=`, not against their
+ * Workshop id, so that is what the caller compares them with.
+ */
+function readDescriptorDependencies(dir) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(dir, "descriptor.mod"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    // Comments first: a commented-out dependency is not a dependency.
+    const block = /(?:^|\n)[ \t]*dependencies[ \t]*=[ \t]*\{([^}]*)\}/.exec(text.replace(/#[^\n]*/g, ""));
+    if (!block)
+        return [];
+    return [...block[1].matchAll(/"([^"]*)"/g)].map((m) => m[1].trim()).filter((s) => s !== "");
+}
+/** "1.19.0.6" -> "1.19.*" (the wildcard form that survives hotfixes). */
+function wildcardVersion(raw) {
+    const m = /^(\d+)\.(\d+)/.exec(raw.trim());
+    return m ? `${m[1]}.${m[2]}.*` : null;
+}
+/** A launcher-correct starter descriptor.mod. */
+function scaffoldDescriptor(modName, supportedVersion) {
+    return [
+        'version="0.1.0"',
+        "tags={",
+        '\t"Gameplay"',
+        "}",
+        `name="${modName.replace(/"/g, "'")}"`,
+        `supported_version="${supportedVersion}"`,
+        "",
+    ].join("\n");
+}

package/dist/errorLogParser.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Best-effort parsing of the game's logs/error.log lines. Pure (no vscode),
+ * so it stays unit-testable; the tailing/diagnostics wiring lives in the
+ * client.
+ */
+export interface ParsedGameError {
+    message: string;
+    relFile: string;
+    /** 0-based, or null for file-level entries. */
+    line: number | null;
+    severity: "error" | "warning";
+}
+/** Parse one error.log line; null when it names no file. */
+export declare function parseErrorLogLine(raw: string): ParsedGameError | null;
+/**
+ * Stateful line parser: same as `parseErrorLogLine`, but additionally stitches
+ * multi-line `Script system error!` blocks together, where the actual error
+ * text and the file location sit on separate indented continuation lines:
+ *
+ *     [18:14:55][E][jomini_script_system.cpp:303]: Script system error!
+ *       Error: is_cultivator trigger [ Scoped object ... is not valid ]
+ *       Script location: file: common/script_values/x.txt line: 25 (name)
+ *
+ * Line-by-line, the location line would become the diagnostic message and the
+ * error text would be dropped. Feed EVERY line through `push` in order (state
+ * carries across reads); call `reset` when the log is cleared or replaced.
+ */
+export declare class ErrorLogParser {
+    private pendingSeverity;
+    private pendingError;
+    push(raw: string): ParsedGameError | null;
+    reset(): void;
+}