texlite 0.9.1 → 0.9.2

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/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/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.`);