texlite 0.9.1 → 0.9.3

package/dist/server/app.js

@@ -29,6 +29,7 @@ import { registerCitationRoutes } from "./routes/citations.js";
 import { registerCommentRoutes } from "./routes/comments.js";
 import { registerProjectMemberRoutes } from "./routes/projectMembers.js";
 import { registerProjectFileRoutes } from "./routes/projectFiles.js";
+import { registerProjectReferenceRoutes } from "./routes/projectReferences.js";
 import { registerProjectHistoryRoutes } from "./routes/projectHistory.js";
 import { registerProjectGitRoutes } from "./routes/projectGit.js";
 import { registerProjectCatalogRoutes } from "./routes/projects.js";
@@ -37,10 +38,36 @@ import { registerUserManagementRoutes } from "./routes/users.js";
 import { registerWordCountRoutes } from "./routes/wordCount.js";
 import { HarperService } from "./harper.js";
 import { TexcountService } from "./texcount.js";
+import { basePathHref, basePathPrefix, withoutBasePath } from "../shared/basePath.js";
 // Retained public helper for callers and tests; implementation lives with the file routes.
 export { escapeGlobPattern } from "./routes/projectShared.js";
 const SESSION_CLEANUP_INTERVAL_MS = 15 * 60_000;
 const now = () => new Date().toISOString();
+/** Inject the runtime mount point into a single, path-independent Vite build. */
+export function renderClientIndex(source, basePath) {
+    const href = escapeHtmlAttribute(basePathHref(basePath));
+    const value = escapeHtmlAttribute(basePath);
+    const baseElement = `<base href="${href}" />`;
+    const metaElement = `<meta name="texlite-base-path" content="${value}" />`;
+    let hadBase = false;
+    let rendered = source.replace(/<base\s+href=(?:"[^"]*"|'[^']*')\s*\/?\s*>/i, () => {
+        hadBase = true;
+        return baseElement;
+    });
+    if (!hadBase)
+        rendered = rendered.replace(/<head(?:\s[^>]*)?>/i, (head) => `${head}\n    ${baseElement}`);
+    let hadMeta = false;
+    rendered = rendered.replace(/<meta\s+name=(?:"texlite-base-path"|'texlite-base-path')\s+content=(?:"[^"]*"|'[^']*')\s*\/?\s*>/i, () => {
+        hadMeta = true;
+        return metaElement;
+    });
+    if (!hadMeta)
+        rendered = rendered.replace(baseElement, `${baseElement}\n    ${metaElement}`);
+    return rendered;
+}
+function escapeHtmlAttribute(value) {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
 export async function buildApp(config, db, options = {}) {
     const app = Fastify({
         logger: options.logger ?? true,
@@ -161,7 +188,10 @@ export async function buildApp(config, db, options = {}) {
         const startedAt = requestStarts.get(request);
         if (startedAt === undefined)
             return;
-        const route = request.routeOptions.url;
+        const registeredRoute = request.routeOptions.url;
+        const route = registeredRoute
+            ? withoutBasePath(config.basePath, registeredRoute) ?? registeredRoute
+            : null;
         if (!route)
             return;
         const metric = {
@@ -193,93 +223,110 @@ export async function buildApp(config, db, options = {}) {
             void apiError(reply, 500, "SERVER_ERROR");
         }
     });
-    registerSystemRoutes(app, {
-        config,
-        db,
-        queue,
-        collaboration,
-        latexCompletions,
-        projectOutlines,
-        metrics,
-        eventLoopDelay
-    });
-    registerCollaborationRoutes(app, { db, collaboration, metrics });
-    registerAuthRoutes(app, { config, db, loginLimiter });
-    registerCitationRoutes(app, { db });
-    registerUserManagementRoutes(app, {
-        config,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines
-    });
-    registerCommentRoutes(app, { config, db, collaboration, projectMutations });
-    registerProjectMemberRoutes(app, { db, collaboration, projectMutations });
-    registerProjectFileRoutes(app, {
-        config,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines,
-        metrics,
-        recordHistory
-    });
-    registerProjectHistoryRoutes(app, { config, db, history, editHistory, projectMutations, recordHistory,
-        clearPendingEdits: (id) => { editRetry.clear(id); failedEdits.delete(id); signalHistory(id); },
-        scheduleHistoryRetention: (id) => historyRetention.schedule(id) });
-    registerProjectGitRoutes(app, { config, db, collaboration, projectMutations, projectGit, recordHistory });
-    registerProjectCatalogRoutes(app, {
-        config,
-        db,
-        collaboration,
-        projectMutations,
-        latexCompletions,
-        projectOutlines,
-        harper,
-        recordHistory
-    });
-    registerWordCountRoutes(app, { config, db, projectMutations, texcount });
-    registerCompileRoutes(app, { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns });
-    // The factory owns shared services and lifecycle hooks; route modules own endpoint behavior.
-    app.addHook("onRequest", async (request) => {
-        if (request.url.startsWith("/api/") && request.url !== "/api/auth/login" && request.url !== "/api/health" && request.url !== "/api/config") {
-            const token = request.cookies.texlite_session;
-            if (token && !currentUser(request, db)) {
-                db.prepare("DELETE FROM sessions WHERE id = ?").run(digestToken(token));
-            }
-        }
-    });
     app.addHook("onClose", async () => collaboration.destroy());
-    if (fs.existsSync(config.clientDir)) {
-        await app.register(staticPlugin, {
-            root: config.clientDir,
-            wildcard: false,
-            // Vite fingerprints everything under assets/. These large JS/WASM files
-            // are safe to cache indefinitely; a new build produces a new URL. Keep
-            // index.html fresh so it always points at the current fingerprints.
-            cacheControl: false,
-            setHeaders(reply, filePath) {
-                const relativePath = path.relative(config.clientDir, filePath).split(path.sep).join("/");
-                if (relativePath === "index.html") {
-                    reply.header("Cache-Control", "no-store");
-                }
-                else if (relativePath.startsWith("assets/")) {
-                    reply.header("Cache-Control", "public, max-age=31536000, immutable");
-                }
-                else {
-                    reply.header("Cache-Control", "public, max-age=3600");
+    const indexPath = path.join(config.clientDir, "index.html");
+    const renderedIndex = fs.existsSync(indexPath)
+        ? renderClientIndex(fs.readFileSync(indexPath, "utf8"), config.basePath)
+        : null;
+    const routePrefix = basePathPrefix(config.basePath);
+    await app.register(async (routes) => {
+        routes.addHook("onRequest", async (request) => {
+            const requestPath = withoutBasePath(config.basePath, request.url) ?? request.url;
+            if (requestPath.startsWith("/api/")
+                && requestPath !== "/api/auth/login"
+                && requestPath !== "/api/health"
+                && requestPath !== "/api/config") {
+                const token = request.cookies.texlite_session;
+                if (token && !currentUser(request, db)) {
+                    db.prepare("DELETE FROM sessions WHERE id = ?").run(digestToken(token));
                 }
             }
         });
-        app.get("/*", async (request, reply) => {
-            if (request.url.startsWith("/api/"))
-                return apiError(reply, 404, "API_NOT_FOUND");
-            reply.header("Cache-Control", "no-store");
-            return reply.sendFile("index.html");
+        registerSystemRoutes(routes, {
+            config,
+            db,
+            queue,
+            collaboration,
+            latexCompletions,
+            projectOutlines,
+            metrics,
+            eventLoopDelay
         });
-    }
+        registerCollaborationRoutes(routes, { db, collaboration, metrics });
+        registerAuthRoutes(routes, { config, db, loginLimiter });
+        registerCitationRoutes(routes, { db });
+        registerUserManagementRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines
+        });
+        registerCommentRoutes(routes, { config, db, collaboration, projectMutations });
+        registerProjectMemberRoutes(routes, { db, collaboration, projectMutations });
+        registerProjectFileRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines,
+            metrics,
+            recordHistory
+        });
+        registerProjectReferenceRoutes(routes, { config, db, projectMutations });
+        registerProjectHistoryRoutes(routes, { config, db, history, editHistory, projectMutations, recordHistory,
+            clearPendingEdits: (id) => { editRetry.clear(id); failedEdits.delete(id); signalHistory(id); },
+            scheduleHistoryRetention: (id) => historyRetention.schedule(id) });
+        registerProjectGitRoutes(routes, { config, db, collaboration, projectMutations, projectGit, recordHistory });
+        registerProjectCatalogRoutes(routes, {
+            config,
+            db,
+            collaboration,
+            projectMutations,
+            latexCompletions,
+            projectOutlines,
+            harper,
+            recordHistory
+        });
+        registerWordCountRoutes(routes, { config, db, projectMutations, texcount });
+        registerCompileRoutes(routes, { config, db, collaboration, projectMutations, compileCoordinator, metrics, pruneCompileRuns });
+        // The factory owns shared services and lifecycle hooks; route modules own endpoint behavior.
+        if (renderedIndex !== null) {
+            await routes.register(staticPlugin, {
+                root: config.clientDir,
+                wildcard: false,
+                index: false,
+                globIgnore: ["index.html"],
+                // Vite fingerprints everything under assets/. These large JS/WASM
+                // files are safe to cache indefinitely; a new build produces a new
+                // URL. The rendered SPA shell below always remains fresh.
+                cacheControl: false,
+                setHeaders(reply, filePath) {
+                    const relativePath = path.relative(config.clientDir, filePath).split(path.sep).join("/");
+                    if (relativePath.startsWith("assets/")) {
+                        reply.header("Cache-Control", "public, max-age=31536000, immutable");
+                    }
+                    else {
+                        reply.header("Cache-Control", "public, max-age=3600");
+                    }
+                }
+            });
+            const sendIndex = async (_request, reply) => {
+                reply.header("Cache-Control", "no-store");
+                return reply.type("text/html; charset=utf-8").send(renderedIndex);
+            };
+            routes.get("/", sendIndex);
+            routes.get("/index.html", sendIndex);
+            routes.get("/*", async (request, reply) => {
+                const requestPath = withoutBasePath(config.basePath, request.url) ?? request.url;
+                if (requestPath.startsWith("/api/"))
+                    return apiError(reply, 404, "API_NOT_FOUND");
+                return sendIndex(request, reply);
+            });
+        }
+    }, { prefix: routePrefix });
     const cleanupExpiredSessions = () => {
         try {
             pruneExpiredSessions(db, now());

package/dist/server/cli.js

@@ -12,6 +12,7 @@ import { assertEnvironment, hostRequirementsSatisfied, inspectHostEnvironment, i
 import { serve } from "./index.js";
 import { processStatus, restartManaged, startManaged, stopManaged, streamLogs, waitForOnline } from "./pm2.js";
 import { defaultDataDirectory, resolveConfigPath } from "./runtimePaths.js";
+import { basePathHref } from "../shared/basePath.js";
 const HELP = `TexLite ${packageVersion()}
 
 Usage:
@@ -106,7 +107,7 @@ function writeInitialConfig(configPath, siteName, adminEmail) {
         siteName,
         adminEmail,
         sessionDays: CONFIG_DEFAULTS.sessionDays,
-        server: { host: CONFIG_DEFAULTS.host, port: CONFIG_DEFAULTS.port },
+        server: { host: CONFIG_DEFAULTS.host, port: CONFIG_DEFAULTS.port, basePath: CONFIG_DEFAULTS.basePath },
         storage: { dataDir: dataDirectory },
         uploads: { maxFileSizeMB: CONFIG_DEFAULTS.maxFileSizeMB },
         pdf: {
@@ -277,6 +278,7 @@ async function printConfig(options) {
         siteName: config.siteName,
         host: config.host,
         port: config.port,
+        basePath: config.basePath,
         dataDir: config.dataDir,
         databasePath: config.databasePath,
         projectsDir: config.projectsDir,
@@ -304,7 +306,7 @@ async function start(options, restart = false) {
     const managed = await waitForOnline(config);
     const status = managed.description?.pm2_env?.status ?? "unknown";
     output(`TexLite ${status}: ${config.siteName}`);
-    output(`Address: http://${config.host}:${config.port}`);
+    output(`Address: http://${config.host}:${config.port}${basePathHref(config.basePath)}`);
     output(`Configuration file: ${configPath}`);
     output(`PM2 process: ${managed.name}`);
 }

package/dist/server/collaboration.js

@@ -12,26 +12,14 @@ import { listProjectFilesAsync, outputRoot, resolveSourcePath, safeRelativePath,
 import { collaborationProjectAccessFromStatement, canEdit, prepareCollaborationProjectAccessStatement } from "./projects.js";
 import { reanchorFileComments } from "./anchors.js";
 import { hashText } from "./editHistory.js";
-const MESSAGE_SYNC = 0;
-const MESSAGE_AWARENESS = 1;
-const MESSAGE_QUERY_AWARENESS = 3;
-const MESSAGE_FLUSH = 4;
-const MESSAGE_PROTOCOL = 5;
-const MESSAGE_MAINTENANCE = 6;
-const MESSAGE_PERMISSION = 7;
-// A small, non-Yjs handshake message used for ephemeral compile metadata.
-// Source text still uses the normal Yjs sync protocol; this message prevents
-// an old IndexedDB metadata entry from being treated as an active compile.
-const MESSAGE_COMPILE_STATES = 8;
-// Ephemeral, per-file formatter leases. These are deliberately kept out of
-// the Yjs document and source persistence state.
-const MESSAGE_FORMAT_LEASE = 9;
+import { COLLABORATION_PROTOCOL_VERSION, CollaborationMessageType, isCollaborationCleanMode, isCollaborationCompileStatus } from "../shared/collaborationProtocol.js";
+export { COLLABORATION_PROTOCOL_VERSION } from "../shared/collaborationProtocol.js";
+const { Sync: MESSAGE_SYNC, Awareness: MESSAGE_AWARENESS, QueryAwareness: MESSAGE_QUERY_AWARENESS, Flush: MESSAGE_FLUSH, Protocol: MESSAGE_PROTOCOL, Maintenance: MESSAGE_MAINTENANCE, Permission: MESSAGE_PERMISSION, CompileStates: MESSAGE_COMPILE_STATES, FormatLease: MESSAGE_FORMAT_LEASE } = CollaborationMessageType;
 /**
  * Increment this when a wire-level collaboration change cannot be decoded by
  * an older browser. The epoch marker is rotated at the same time, which makes
  * already-open older pages discard their local draft and reload safely.
  */
-export const COLLABORATION_PROTOCOL_VERSION = 3;
 const VERSIONED_EPOCH_PREFIX = `${COLLABORATION_PROTOCOL_VERSION}:`;
 const SOURCE_PREFIX = "source:";
 const MAX_PROJECT_SESSIONS = 10;
@@ -1576,7 +1564,7 @@ export function maxCollaborativeFileBytes(config) {
     return Math.min(config.maxUploadBytes, MAX_COLLABORATIVE_FILE_BYTES);
 }
 export function isCollaborativeTextFile(filePath) {
-    return /(?:\.tex|\.bib|\.sty|\.cls|\.txt|\.md|latexmkrc)$/i.test(filePath);
+    return /(?:\.tex|\.bib|\.bst|\.sty|\.cls|\.txt|\.md|latexmkrc)$/i.test(filePath);
 }
 function collaborativeEntrySignature(entry) {
     return `${entry.path}\0${entry.size ?? 0}\0${entry.mtimeMs ?? 0}`;
@@ -1760,9 +1748,8 @@ function isSharedCompileState(mainFile, value) {
     const requestedBy = state.requestedBy;
     return state.mainFile === mainFile
         && typeof state.runId === "string" && state.runId.length > 0
-        && (state.status === "queued" || state.status === "running" || state.status === "succeeded"
-            || state.status === "failed" || state.status === "cleaned")
-        && (state.status !== "cleaned" || state.cleanMode === "cache" || state.cleanMode === "artifacts")
+        && isCollaborationCompileStatus(state.status)
+        && (state.status !== "cleaned" || isCollaborationCleanMode(state.cleanMode))
         && (state.stale === undefined || typeof state.stale === "boolean")
         && typeof state.updatedAt === "string"
         && Boolean(requestedBy && typeof requestedBy === "object"

package/dist/server/compileArtifacts.js

@@ -4,6 +4,7 @@ import { publishedCompileArtifacts } from "./compiler.js";
 import { outputRoot, resolveSourcePath, safeRelativePath, sourceRoot, texFileStem } from "./files.js";
 import { isMainDocumentCandidateSync } from "./latexRoot.js";
 import { MAX_TEXT_PREVIEW_BYTES } from "./limits.js";
+import { withBasePath } from "../shared/basePath.js";
 export function pdfLoadingMode(config, pdfSizeBytes) {
     if (config.pdfLoadingStrategy === "full" || config.pdfLoadingStrategy === "range") {
         return config.pdfLoadingStrategy;
@@ -77,8 +78,8 @@ export function compileMainFile(config, projectId, defaultMainFile, value) {
     }
     return mainFile;
 }
-export function compilePdfUrl(projectId, mainFile, version) {
-    return `/api/projects/${projectId}/pdf?mainFile=${encodeURIComponent(mainFile)}&run=${encodeURIComponent(version)}`;
+export function compilePdfUrl(config, projectId, mainFile, version) {
+    return withBasePath(config.basePath, `/api/projects/${projectId}/pdf?mainFile=${encodeURIComponent(mainFile)}&run=${encodeURIComponent(version)}`);
 }
 export function listCompileArtifacts(directory) {
     const artifacts = [];

package/dist/server/config.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { defaultDataDirectory, packageClientDirectory, resolveConfigPath } from "./runtimePaths.js";
+import { normalizeBasePath, ROOT_BASE_PATH } from "../shared/basePath.js";
 export const LATEX_ENGINES = ["pdflatex", "xelatex", "lualatex"];
 export const PDF_LOADING_STRATEGIES = ["auto", "full", "range"];
 /** Effective values used when the corresponding file/env setting is omitted. */
@@ -9,6 +10,7 @@ export const CONFIG_DEFAULTS = {
     adminEmail: "",
     host: "127.0.0.1",
     port: 3000,
+    basePath: ROOT_BASE_PATH,
     dataDir: defaultDataDirectory(),
     clientDir: packageClientDirectory(),
     sessionDays: 14,
@@ -74,12 +76,14 @@ export function loadConfig(configPathOverride) {
     const historyMaxStorageMB = integerSetting("history.maxStorageMB", process.env.TEXLITE_HISTORY_MAX_STORAGE_MB, fileConfig.history?.maxStorageMB, CONFIG_DEFAULTS.historyMaxStorageMB, CONFIG_LIMITS.historyMaxStorageMB);
     const editHistoryMaxStorageMB = integerSetting("editHistory.maxStorageMB", process.env.TEXLITE_EDIT_HISTORY_MAX_STORAGE_MB, fileConfig.editHistory?.maxStorageMB, CONFIG_DEFAULTS.editHistoryMaxStorageMB, CONFIG_LIMITS.editHistoryMaxStorageMB);
     const gitOperationTimeoutSeconds = integerSetting("git.operationTimeoutSeconds", process.env.TEXLITE_GIT_TIMEOUT, fileConfig.git?.operationTimeoutSeconds, CONFIG_DEFAULTS.gitOperationTimeoutSeconds, CONFIG_LIMITS.gitOperationTimeoutSeconds);
+    const basePath = resolveBasePath(fileConfig);
     const config = {
         configPath,
         siteName: stringSetting("siteName", process.env.TEXLITE_SITE_NAME, fileConfig.siteName, CONFIG_DEFAULTS.siteName, { min: 1, max: 120 }),
         adminEmail: stringSetting("adminEmail", process.env.TEXLITE_ADMIN_EMAIL, fileConfig.adminEmail, CONFIG_DEFAULTS.adminEmail, { min: 0, max: 320 }),
         host: stringSetting("server.host", process.env.TEXLITE_HOST, fileConfig.server?.host, CONFIG_DEFAULTS.host, { min: 1, max: 255 }),
         port: integerSetting("server.port", process.env.TEXLITE_PORT, fileConfig.server?.port, CONFIG_DEFAULTS.port, CONFIG_LIMITS.port),
+        basePath,
         dataDir,
         databasePath: path.join(dataDir, "texlite.db"),
         projectsDir: path.join(dataDir, "projects"),
@@ -105,6 +109,17 @@ export function loadConfig(configPathOverride) {
     validateConfig(config);
     return config;
 }
+/**
+ * Read only the configured public mount path. Vite uses this during local UI
+ * development, where checking server data paths would be unnecessary and can
+ * prevent the frontend from starting before the API server is configured.
+ */
+export function loadBasePath(configPathOverride) {
+    const configPath = resolveConfigPath(configPathOverride);
+    const fileConfig = readConfigFile(configPath);
+    validateFileConfig(fileConfig);
+    return resolveBasePath(fileConfig);
+}
 /** Validate an already materialized configuration (useful for startup/tests). */
 export function validateConfig(config) {
     if (!config.dataDir || path.parse(config.dataDir).root === config.dataDir) {
@@ -126,6 +141,9 @@ export function validateConfig(config) {
         throw configurationError("latex.defaultEngine", "must be one of the engines listed in latex.allowedEngines");
     }
     validateInteger("server.port", config.port, CONFIG_LIMITS.port);
+    if (normalizeBasePath(config.basePath) !== config.basePath) {
+        throw configurationError("server.basePath", "must be / or a normalized URL path such as /texlite or /tools/texlite");
+    }
     validateInteger("sessionDays", config.sessionDays, CONFIG_LIMITS.sessionDays);
     validateInteger("latex.compileTimeoutSeconds", config.compileTimeoutMs / 1000, CONFIG_LIMITS.compileTimeoutSeconds);
     validateInteger("latex.maxCompileJobs", config.maxCompileJobs, CONFIG_LIMITS.maxCompileJobs);
@@ -139,6 +157,14 @@ export function validateConfig(config) {
     validateInteger("editHistory.maxStorageMB", config.editHistoryMaxStorageBytes / (1024 * 1024), CONFIG_LIMITS.editHistoryMaxStorageMB);
     validateInteger("git.operationTimeoutSeconds", config.gitOperationTimeoutMs / 1000, CONFIG_LIMITS.gitOperationTimeoutSeconds);
 }
+function resolveBasePath(fileConfig) {
+    const configuredBasePath = stringSetting("server.basePath", process.env.TEXLITE_BASE_PATH, fileConfig.server?.basePath, CONFIG_DEFAULTS.basePath, { min: 1, max: 1_024 });
+    const basePath = normalizeBasePath(configuredBasePath);
+    if (!basePath) {
+        throw configurationError("server.basePath", `must be / or a URL path such as /texlite or /tools/texlite; received ${displayValue(configuredBasePath)}`);
+    }
+    return basePath;
+}
 function isEngine(value) {
     return typeof value === "string" && LATEX_ENGINES.includes(value);
 }
@@ -168,6 +194,7 @@ function validateFileConfig(config) {
     const server = optionalSection(config.server, "server");
     optionalString(server?.host, "server.host", { min: 1, max: 255 });
     optionalInteger(server?.port, "server.port", CONFIG_LIMITS.port);
+    optionalString(server?.basePath, "server.basePath", { min: 1, max: 1_024 });
     const storage = optionalSection(config.storage, "storage");
     optionalString(storage?.dataDir, "storage.dataDir", { min: 1, max: 4_096 });
     const uploads = optionalSection(config.uploads, "uploads");

package/dist/server/db.js

@@ -1,5 +1,20 @@
 import fs from "node:fs";
 import Database from "better-sqlite3";
+const migrationsTable = "texlite_schema_migrations";
+/**
+ * Keep this list append-only. Existing migration bodies must never be changed
+ * after release: a database records the version only after that migration's
+ * transaction has committed.
+ *
+ * Version 1 deliberately folds the untracked historical schema setup into a
+ * single baseline. It upgrades every database released before versioned
+ * migrations while preserving the current schema for new installations.
+ */
+const databaseMigrations = [
+    // Append future migrations below this entry. Never insert before or modify
+    // the released baseline: recorded databases will intentionally skip it.
+    { version: 1, name: "baseline_schema_and_legacy_upgrade", apply: applyBaselineMigration }
+];
 export function openDatabase(config) {
     fs.mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
     fs.mkdirSync(config.projectsDir, { recursive: true, mode: 0o700 });
@@ -8,10 +23,67 @@ export function openDatabase(config) {
     // per-transaction WAL fsync: a sudden host failure can lose the most recent
     // acknowledged transaction, but the database remains consistent.
     db.exec("PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA synchronous = NORMAL; PRAGMA busy_timeout = 5000;");
-    migrate(db);
+    try {
+        migrate(db);
+    }
+    catch (error) {
+        // A failed migration must not leave an open SQLite handle holding a lock
+        // while startup unwinds. Its transaction has already been rolled back.
+        db.close();
+        throw error;
+    }
     return db;
 }
 function migrate(db) {
+    const context = {
+        migrateLegacyProjectTags: tableExists(db, "project_tags") && !tableExists(db, "user_tags"),
+        backfillAdminCanCreateProjects: missingColumn(db, "users", "can_create_projects"),
+        backfillProjectLastModifiedBy: missingColumn(db, "projects", "last_modified_by"),
+        backfillCompileRunMainFile: missingColumn(db, "compile_runs", "main_file"),
+        backfillEditSegmentBytes: missingColumn(db, "project_edit_segments", "steps_bytes")
+    };
+    db.exec(`CREATE TABLE IF NOT EXISTS ${migrationsTable} (
+    version INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    applied_at TEXT NOT NULL
+  )`);
+    const applied = db.prepare(`SELECT version, name FROM ${migrationsTable}`).all()
+        .map((migration) => ({ version: Number(migration.version), name: migration.name }));
+    const knownMigrations = new Map(databaseMigrations.map((migration) => [migration.version, migration]));
+    const unknownMigration = applied.find((migration) => !knownMigrations.has(migration.version));
+    if (unknownMigration !== undefined) {
+        const latestVersion = databaseMigrations.at(-1)?.version ?? 0;
+        const direction = unknownMigration.version > latestVersion ? "newer than" : "not recognized by";
+        throw new Error(`Database schema version ${unknownMigration.version} is ${direction} this TexLite release.`);
+    }
+    const renamedMigration = applied.find((migration) => knownMigrations.get(migration.version)?.name !== migration.name);
+    if (renamedMigration) {
+        throw new Error(`Database migration ${renamedMigration.version} does not match this TexLite release.`);
+    }
+    const appliedVersions = new Set(applied.map((migration) => migration.version));
+    const missingBeforeApplied = databaseMigrations.find((migration) => !appliedVersions.has(migration.version)
+        && applied.some((appliedMigration) => appliedMigration.version > migration.version));
+    if (missingBeforeApplied) {
+        throw new Error(`Database migration ${missingBeforeApplied.version} is missing before a later migration.`);
+    }
+    const record = db.prepare(`INSERT INTO ${migrationsTable} (version, name, applied_at) VALUES (?, ?, ?)`);
+    for (const migration of databaseMigrations) {
+        if (appliedVersions.has(migration.version))
+            continue;
+        db.transaction(() => {
+            migration.apply(db, context);
+            record.run(migration.version, migration.name, new Date().toISOString());
+        })();
+    }
+}
+function tableExists(db, table) {
+    return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table));
+}
+function missingColumn(db, table, column) {
+    return tableExists(db, table)
+        && !db.prepare("SELECT 1 FROM pragma_table_info(?) WHERE name = ?").get(table, column);
+}
+function applyBaselineMigration(db, context) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS users (
       id TEXT PRIMARY KEY,
@@ -282,10 +354,10 @@ function migrate(db) {
   `);
     const editColumns = db.prepare("PRAGMA table_info(project_edit_segments)").all();
     if (!editColumns.some((column) => column.name === "steps_bytes")) {
-        db.transaction(() => {
-            db.exec("ALTER TABLE project_edit_segments ADD COLUMN steps_bytes INTEGER NOT NULL DEFAULT 0");
+        db.exec("ALTER TABLE project_edit_segments ADD COLUMN steps_bytes INTEGER NOT NULL DEFAULT 0");
+        if (context.backfillEditSegmentBytes) {
             db.exec("UPDATE project_edit_segments SET steps_bytes = LENGTH(CAST(steps_json AS BLOB))");
-        })();
+        }
     }
     const projectColumns = db.prepare("PRAGMA table_info(projects)").all();
     if (!projectColumns.some((column) => column.name === "latexmkrc")) {
@@ -328,14 +400,23 @@ function migrate(db) {
         db.exec("ALTER TABLE citation_library_entries ADD COLUMN revision INTEGER NOT NULL DEFAULT 1");
     }
     db.exec(`
-    UPDATE users SET can_create_projects = 1 WHERE role = 'admin';
-    UPDATE projects SET last_modified_by = owner_id WHERE last_modified_by IS NULL;
-    UPDATE compile_runs SET main_file = COALESCE(
-      (SELECT project.main_file FROM projects project WHERE project.id = compile_runs.project_id), ''
-    ) WHERE main_file = '';
     CREATE INDEX IF NOT EXISTS compile_runs_project_main_created
       ON compile_runs(project_id, main_file, created_at DESC);
-
+  `);
+    if (context.backfillProjectLastModifiedBy) {
+        db.exec("UPDATE projects SET last_modified_by = owner_id WHERE last_modified_by IS NULL");
+    }
+    if (context.backfillAdminCanCreateProjects) {
+        db.exec("UPDATE users SET can_create_projects = 1 WHERE role = 'admin'");
+    }
+    if (context.backfillCompileRunMainFile) {
+        db.exec(`UPDATE compile_runs SET main_file = COALESCE(
+      (SELECT project.main_file FROM projects project WHERE project.id = compile_runs.project_id), ''
+    ) WHERE main_file = ''`);
+    }
+    if (!context.migrateLegacyProjectTags)
+        return;
+    db.exec(`
     INSERT OR IGNORE INTO tags (id, name, color, created_by, created_at, updated_at)
     SELECT legacy.id, legacy.name, legacy.color, p.owner_id, legacy.created_at, legacy.created_at
     FROM project_tags legacy

package/dist/server/index.js

@@ -6,6 +6,7 @@ import { buildApp } from "./app.js";
 import { assertEnvironment } from "./environment.js";
 import { acquireDataDirectoryLock } from "./instanceLock.js";
 import { LogRotation } from "./logRotation.js";
+import { basePathHref } from "../shared/basePath.js";
 export async function startServer(configPath) {
     const config = loadConfig(configPath);
     const lock = acquireDataDirectoryLock(config);
@@ -23,11 +24,12 @@ export async function startServer(configPath) {
         app = await buildApp(config, db);
         await app.listen({ host: config.host, port: config.port });
         app.log.info(`Environment ready: ${environment.map((item) => `${item.name} ${item.version}`).join(", ")}`);
-        app.log.info(`${config.siteName} running at http://${config.host}:${config.port}`);
+        const address = `http://${config.host}:${config.port}${basePathHref(config.basePath)}`;
+        app.log.info(`${config.siteName} running at ${address}`);
         if (typeof process.send === "function")
             process.send("ready");
         return {
-            address: `http://${config.host}:${config.port}`,
+            address,
             close: async () => {
                 try {
                     if (app)

package/dist/server/instanceLock.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
+import { basePathHref } from "../shared/basePath.js";
 export const LOCK_FILE_NAME = ".texlite.lock";
 export function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
@@ -45,7 +46,8 @@ export function acquireDataDirectoryLock(config) {
         token: randomUUID(),
         configPath: config.configPath,
         host: config.host,
-        port: config.port
+        port: config.port,
+        basePath: config.basePath
     };
     for (let attempt = 0; attempt < 2; attempt += 1) {
         try {
@@ -103,7 +105,7 @@ export function acquireDataDirectoryLock(config) {
                 throw new Error(`The data directory is already locked by another TexLite instance:\n` +
                     `  - PID: ${existing.pid}\n` +
                     `  - Config: ${existing.configPath}\n` +
-                    `  - Address: http://${existing.host}:${existing.port}\n` +
+                    `  - Address: http://${existing.host}:${existing.port}${basePathHref(existing.basePath ?? "/")}\n` +
                     `  - Started: ${existing.startedAt}\n` +
                     `  - Data directory: ${config.dataDir}\n` +
                     `Do not run multiple TexLite instances with the same data directory.`);