@heroiclands/content-language-server 0.1.0

package/README.md

@@ -0,0 +1,11 @@
+# HeroicLands content language server
+
+`@heroiclands/content-language-server` provides definition, reference, and workspace search for Markdown notes in HeroicLands content projects. It reads authored notes and project configuration through one exact `@heroiclands/package-build` dependency.
+
+Start its `heroiclands-content-language-server` executable from the content project root. The server builds a private index when it starts and after saves. The index lives in the platform cache outside the project's `build/` directory, so a clean or package build does not replace editor navigation data.
+
+Install an exact released package version in a directory managed by your editor integration. Configure an LSP client to launch that installation's `node_modules/.bin/heroiclands-content-language-server` executable with the content project as its working directory and Markdown notes as its document scope. The package does not depend on any particular editor.
+
+See the [language server guide](docs/content-language-server.md) for LSP requests, cache locations, error handling, and manual recovery commands.
+
+Maintainers use the [publishing guide](docs/publishing.md) for the first npm release and trusted publisher configuration.

package/bin/heroiclands-content-language-server.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { ContentWorkspace, runLanguageServer } from "../engine/content-language-server.mjs";
+
+if (process.argv[2] === "--print-index-path") {
+    console.log(new ContentWorkspace().indexFile);
+} else if (process.argv[2] === "--rebuild-index") {
+    const workspace = new ContentWorkspace(undefined, {
+        onStatus: (status) => {
+            if (status) console.error(status);
+        },
+    });
+    if (!workspace.rebuild()) process.exitCode = 1;
+    else console.log(workspace.indexFile);
+} else if (process.argv.length === 2) {
+    runLanguageServer();
+} else {
+    console.error(
+        "Usage: heroiclands-content-language-server [--print-index-path | --rebuild-index]",
+    );
+    process.exitCode = 2;
+}

package/docs/content-language-server.md

@@ -0,0 +1,30 @@
+# Content language server
+
+`heroiclands-content-language-server` provides editor navigation for Markdown notes in a HeroicLands content project. It is a stdio Language Server Protocol process. Start it from the project root so it can read `package-build.config.yaml` and the saved content tree.
+
+The server builds a private JSONL index during initialization, before answering navigation requests. It rebuilds after nearby save notifications settle. Unsaved buffer text identifies an Address under the cursor, but workspace search uses saved metadata. A new, renamed, or deleted note enters the index when the editor sends a save or file-operation notification. A successful rebuild replaces the complete snapshot; a failed rebuild reports an editor message and keeps the last complete snapshot available with a stale-results warning.
+
+The index belongs to the editor, outside the project. On macOS it is `~/Library/Caches/HeroicLands/content-language-server/<project-root-hash>/metadata.jsonl`. Linux uses `$XDG_CACHE_HOME` or `~/.cache`; Windows uses `%LOCALAPPDATA%` or the user's `AppData/Local` directory. The hash comes from the canonical project root and stays the same across server versions. `metadata.json` records the package identity, generator version, and checksum. Startup rebuilds even when a cache exists, and an older server cannot replace an index from a newer generator. Cache files are disposable.
+
+Install an exact `@heroiclands/content-language-server` version in an editor-managed directory and launch its executable. This package declares an exact `@heroiclands/package-build` dependency, so the server and index generator come from the same installation. The project supplies its configuration and saved notes. The build's `content-build content-index` command writes its own artifact under `build/` for build consumers; the language server does not read that artifact.
+
+Run these commands from the project root using the editor-managed executable:
+
+```sh
+heroiclands-content-language-server --print-index-path
+heroiclands-content-language-server --rebuild-index
+```
+
+The first prints the private JSONL path. The second is manual recovery when a file operation did not trigger a rebuild; it prints the path on success and exits nonzero on failure. Restarting the server also rebuilds from saved source. A failed rebuild leaves the complete prior snapshot in place. If there is no valid prior snapshot, navigation reports that no index is available.
+
+| LSP request               | Behavior                                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `textDocument/definition` | Follows an Address or wikilink to the indexed note. An anchor lands on its indexed line.                                     |
+| `workspace/symbol`        | Finds notes by name, alias, ASCII name, shortcode, or Address. `tag:myth` searches tags. One result appears per source note. |
+| `textDocument/references` | Finds authored wikilinks, embeds, and declared frontmatter Address values or keys. Ordinary prose is excluded.               |
+
+Reference search scans saved Markdown notes in the configured content tree. The server writes only LSP messages to stdout and uses UTF-16 positions.
+
+## Editor integration
+
+An LSP client starts the executable with the content project as its working directory and associates it with Markdown notes under the configured content directory. The process handles `initialize`, `shutdown`, `exit`, full and incremental document synchronization, save and file-operation notifications, definition, references, and workspace symbols. It does not advertise completion, diagnostics, rename, or document symbols. An editor integration supplies its own installation, project discovery, and UI commands.

package/docs/publishing.md

@@ -0,0 +1,17 @@
+# Publishing
+
+The package releases through `.github/workflows/release.yml`. Merged changesets open a version pull request; merging that pull request publishes the version to npm. The GitHub Actions workflow uses npm trusted publishing with OIDC.
+
+## First publication
+
+A new package name has no npm package settings for a trusted publisher. The maintainer publishes the first version from a clean `main` checkout with an npm account that can create packages under `@heroiclands`:
+
+```sh
+npm ci
+npm test
+npm publish --access public --provenance=false
+```
+
+The initial local publish has no CI provenance attestation. The repository's release workflow recognizes an absent package and leaves the first publication to the maintainer.
+
+On npmjs.com, open the package's settings and add a GitHub Actions trusted publisher with organization `HeroicLands`, repository `content-language-server`, workflow filename `release.yml`, and direct `npm publish` permitted. The workflow uses GitHub-hosted runners and `id-token: write`. Subsequent releases use that connection and receive automatic provenance.

package/engine/content-language-index.mjs

@@ -0,0 +1,155 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import {
+    indexRecordsFor,
+    serializeContentIndex,
+} from "@heroiclands/package-build/engine/content-index";
+import packageBuild from "@heroiclands/package-build/package.json" with { type: "json" };
+
+/** Version of the server package that generates editor index records. */
+export const generatorVersion = packageBuild.version;
+
+function defaultCacheBase() {
+    if (process.platform === "darwin") return path.join(os.homedir(), "Library", "Caches");
+    if (process.platform === "win32")
+        return process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local");
+    return process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache");
+}
+
+/** Keep one cache directory for each canonical project root across server versions. */
+export function languageIndexDirectory(config, cacheBase = defaultCacheBase()) {
+    const root = fs.realpathSync(config.rootDir ?? path.dirname(config.paths.assets));
+    const hash = crypto.createHash("sha256").update(root).digest("hex");
+    return path.join(cacheBase, "HeroicLands", "content-language-server", hash);
+}
+
+function checksum(text) {
+    return crypto.createHash("sha256").update(text).digest("hex");
+}
+
+function compareVersions(left, right) {
+    const a = left.split(".").map(Number);
+    const b = right.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) - (b[i] ?? 0);
+    }
+    return 0;
+}
+
+function withProjectLock(directory, action) {
+    fs.mkdirSync(directory, { recursive: true });
+    const lock = path.join(directory, ".rebuild-lock");
+    const deadline = Date.now() + 30000;
+    while (true) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        } catch (error) {
+            if (error.code !== "EEXIST") throw error;
+            const stat = fs.statSync(lock, { throwIfNoEntry: false });
+            if (!stat) continue;
+            if (Date.now() - stat.mtimeMs > 300000) {
+                fs.rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`Timed out waiting for index lock at ${lock}`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
+    }
+    try {
+        return action();
+    } finally {
+        fs.rmdirSync(lock);
+    }
+}
+
+function readPair(indexFile, manifestFile, contentPackage) {
+    const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+    if (manifest.package !== contentPackage || manifest.generatorVersion !== generatorVersion)
+        throw new Error(`Incompatible editor index at ${indexFile}`);
+    const text = fs.readFileSync(indexFile, "utf8");
+    if (checksum(text) !== manifest.sha256) throw new Error(`Corrupt editor index at ${indexFile}`);
+    return text
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+
+/** Read only a complete snapshot produced by this generator and package. */
+export function readLanguageIndex(directory, contentPackage) {
+    const indexFile = path.join(directory, "metadata.jsonl");
+    const manifestFile = path.join(directory, "metadata.json");
+    try {
+        return readPair(indexFile, manifestFile, contentPackage);
+    } catch (error) {
+        try {
+            return readPair(`${indexFile}.previous`, `${manifestFile}.previous`, contentPackage);
+        } catch {
+            throw error;
+        }
+    }
+}
+
+/** Rebuild from saved inputs, publishing complete files while holding the project lock. */
+export function rebuildLanguageIndex(config, directory) {
+    return withProjectLock(directory, () => {
+        let existing;
+        try {
+            existing = JSON.parse(fs.readFileSync(path.join(directory, "metadata.json"), "utf8"));
+        } catch {
+            existing = null;
+        }
+        if (
+            existing?.generatorVersion &&
+            compareVersions(existing.generatorVersion, generatorVersion) > 0
+        )
+            throw new Error(
+                `Editor index uses newer generator ${existing.generatorVersion}; upgrade this language server`,
+            );
+        const records = indexRecordsFor({ config });
+        if (records.length === 0)
+            throw new Error(`${config.paths.content} yielded no index records`);
+        const text = serializeContentIndex(records);
+        const manifest = JSON.stringify({
+            package: config.contentPackage,
+            generatorVersion,
+            sha256: checksum(text),
+        });
+        const suffix = `${process.pid}-${crypto.randomUUID()}`;
+        const indexTemp = path.join(directory, `metadata.jsonl.${suffix}.tmp`);
+        const manifestTemp = path.join(directory, `metadata.json.${suffix}.tmp`);
+        const indexFile = path.join(directory, "metadata.jsonl");
+        const manifestFile = path.join(directory, "metadata.json");
+        const priorIndex = `${indexFile}.previous`;
+        const priorManifest = `${manifestFile}.previous`;
+        try {
+            fs.writeFileSync(indexTemp, text);
+            fs.writeFileSync(manifestTemp, manifest);
+            try {
+                readPair(indexFile, manifestFile, config.contentPackage);
+                fs.copyFileSync(indexFile, priorIndex);
+                fs.copyFileSync(manifestFile, priorManifest);
+            } catch {
+                // A recovery snapshot, if present, stays available during publication.
+            }
+            fs.renameSync(indexTemp, indexFile);
+            fs.renameSync(manifestTemp, manifestFile);
+            fs.rmSync(priorIndex, { force: true });
+            fs.rmSync(priorManifest, { force: true });
+        } finally {
+            fs.rmSync(indexTemp, { force: true });
+            fs.rmSync(manifestTemp, { force: true });
+        }
+        return text
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    });
+}