@better-forge/runtime 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @better-forge/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Application bootstrap: Fastify defaults, health, shutdown, update check, app lock and SSE.
+
+Request logs hide secrets: `redactQueryParams` replaces the value of those query parameters (names are compared after decoding), `redactPathTokenPrefixes` the path segment after a prefix such as `/links/`. `redactUrl` does the same for any URL.
+
+`createSse(limits)` serves live event streams. `SseLimits` caps the open anonymous streams in total and per address (`rateLimitKey` groups an IPv6 address by its /64), and the unsent bytes a client may hold before it is disconnected; signed-in streams are not counted. `rateLimitKey(ip)` is the key to use for any per-address limit.
+
+Status: skeleton. Depends on: `@better-forge/db`.

package/dist/appLock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The marker file that tells a restore or a second start that the application is running. `name` is how the
+ * application is called in the refusal, `fileName` the marker inside `dir()` (evaluated on each use).
+ */
+export declare function createAppLock(options: {
+    name: string;
+    fileName: string;
+    dir: () => string;
+}): {
+    assertAppStopped: () => void;
+    acquireAppLock: () => () => void;
+};
+//# sourceMappingURL=appLock.d.ts.map

package/dist/appLock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appLock.d.ts","sourceRoot":"","sources":["../src/appLock.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE;4BAsB7D,IAAI;0BAKN,MAAM,IAAI;EAmBtC"}

package/dist/appLock.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { currentProcessOwner, isOwnerAlive } from './processLiveness.js';
+const FRESH_MS = 30_000;
+/**
+ * A stalled heartbeat (event loop blocked by a long synchronous task) still counts as running
+ * while the recorded pid is alive — but only for this long, so a reused pid cannot block forever.
+ */
+const LIVE_OWNER_MS = 10 * 60_000;
+/**
+ * The marker file that tells a restore or a second start that the application is running. `name` is how the
+ * application is called in the refusal, `fileName` the marker inside `dir()` (evaluated on each use).
+ */
+export function createAppLock(options) {
+    const RUNNING_MESSAGE = `${options.name} is still running. Stop the application before restoring.`;
+    const lockPath = () => path.join(options.dir(), options.fileName);
+    function readOwner(file) {
+        try {
+            return JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Removes a marker whose owner is gone; throws while the app still looks alive. */
+    function clearStaleMarker(options) {
+        const file = lockPath();
+        if (!fs.existsSync(file))
+            return;
+        const age = Date.now() - fs.statSync(file).mtimeMs;
+        const ownerAlive = isOwnerAlive(readOwner(file));
+        // A killed process (Ctrl+C on Windows, tsx watch restart) leaves a fresh marker; startup trusts a dead pid over the heartbeat.
+        if (age < FRESH_MS && (options.checkOwner || ownerAlive))
+            throw new Error(RUNNING_MESSAGE);
+        if (options.checkOwner && age < LIVE_OWNER_MS && ownerAlive)
+            throw new Error(RUNNING_MESSAGE);
+        fs.rmSync(file, { force: true });
+    }
+    /** Used by restore: also refuses while the recorded app process is alive but its heartbeat has stalled. */
+    function assertAppStopped() {
+        clearStaleMarker({ checkOwner: true });
+    }
+    /** Startup uses the heartbeat only, so a restart after a crash is never blocked by an unrelated process that reused the pid. */
+    function acquireAppLock() {
+        clearStaleMarker({ checkOwner: false });
+        fs.mkdirSync(options.dir(), { recursive: true });
+        const file = lockPath();
+        fs.writeFileSync(file, JSON.stringify({ ...currentProcessOwner(), startedAt: Date.now() }), { flag: 'wx', mode: 0o600 });
+        const heartbeat = setInterval(() => {
+            try {
+                fs.utimesSync(file, new Date(), new Date());
+            }
+            catch { /* shutdown race */ }
+        }, 5_000);
+        heartbeat.unref();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            clearInterval(heartbeat);
+            fs.rmSync(file, { force: true });
+        };
+    }
+    return { assertAppStopped, acquireAppLock };
+}
+//# sourceMappingURL=appLock.js.map

package/dist/appLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appLock.js","sourceRoot":"","sources":["../src/appLock.ts"],"names":[],"mappings":"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"}

package/dist/createBetterApp.d.ts

@@ -0,0 +1,63 @@
+import Fastify, { type FastifyInstance } from 'fastify';
+/** How long a signed-in session token lives. */
+export declare const JWT_EXPIRES_IN = "12h";
+/** The secret sessions are signed with: from `JWT_SECRET`, which production insists on being a real one. */
+export declare function resolveJwtSecret(env?: NodeJS.ProcessEnv): string;
+export interface BetterAppOptions {
+    /** Request URLs are logged with the value of these query parameters replaced (capability tokens in links). */
+    redactQueryParams?: readonly string[];
+    /** Request paths whose next segment is a capability token, for example `/links/` (the token is not logged). */
+    redactPathTokenPrefixes?: readonly string[];
+    /** Checks run before anything is created (for example that the encryption key is usable); throw to refuse to start. */
+    validate?: () => void;
+    /** Where uploaded files are kept and served from (`/uploads/`). */
+    uploads: {
+        dir: string;
+        maxFileBytes: number;
+    };
+    /** Whether a response to this request may be shown in a frame of our own origin (anything else is refused). */
+    allowSameOriginFraming?: (request: {
+        path: string;
+        query: URLSearchParams;
+    }) => boolean;
+    /** The database is opened only once the application has been set up. */
+    database: {
+        isReady: () => boolean;
+        open: () => void;
+        migrate: () => void;
+        close: () => void;
+    };
+    /** Registers every route of the application. */
+    routes: (app: FastifyInstance) => Promise<void>;
+    /** Registers the built front-ends; called in production only, after the routes. */
+    frontends?: (app: FastifyInstance) => Promise<void>;
+    /** Takes the lock that keeps a second instance away from the data directory; returns the release. */
+    acquireLock: () => () => void;
+    /** Work that runs only while the application is set up. */
+    backgroundServices?: {
+        start: () => void;
+        stop: () => void;
+        /** Resolves once the work `stop` left running has finished; the shutdown waits for it until its deadline. */
+        drain?: () => Promise<void>;
+    };
+    /** Called when the process is asked to stop, before the server drains (close event streams, say). */
+    stopIntake?: () => void;
+    /** How long a stop waits for the server and the background work to drain before it exits anyway. Default 5 seconds. */
+    shutdownDeadlineMs?: number;
+    /** Name used in the line logged when the server is up. */
+    logName?: string;
+    port?: number;
+}
+/**
+ * Builds the HTTP application the Better products share: logging that hides credentials, proxy trust, CORS and a
+ * cross-site guard, cookies, JWT sessions, rate limiting, uploads, security headers, the database once set up, and the
+ * application's routes. `run` then takes the lock, listens, and wires the shutdown that closes everything in order.
+ */
+export declare function createBetterApp(options: BetterAppOptions): Promise<{
+    app: Fastify.FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, Fastify.FastifyBaseLogger, Fastify.FastifyTypeProviderDefault> & PromiseLike<Fastify.FastifyInstance<import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, Fastify.FastifyBaseLogger, Fastify.FastifyTypeProviderDefault>> & {
+        __linterBrands: "SafePromiseLike";
+    };
+    run: () => Promise<void>;
+}>;
+export type BetterApp = Awaited<ReturnType<typeof createBetterApp>>;
+//# sourceMappingURL=createBetterApp.d.ts.map

package/dist/createBetterApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBetterApp.d.ts","sourceRoot":"","sources":["../src/createBetterApp.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,EAAE,EAAE,KAAK,eAAe,EAAuB,MAAM,SAAS,CAAA;AAmB5E,gDAAgD;AAChD,eAAO,MAAM,cAAc,QAAQ,CAAA;AAEnC,4GAA4G;AAC5G,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAU7E;AAED,MAAM,WAAW,gBAAgB;IAC/B,8GAA8G;IAC9G,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,+GAA+G;IAC/G,uBAAuB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,uHAAuH;IACvH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,mEAAmE;IACnE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,+GAA+G;IAC/G,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,eAAe,CAAA;KAAE,KAAK,OAAO,CAAA;IACvF,wEAAwE;IACxE,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,OAAO,CAAA;QACtB,IAAI,EAAE,MAAM,IAAI,CAAA;QAChB,OAAO,EAAE,MAAM,IAAI,CAAA;QACnB,KAAK,EAAE,MAAM,IAAI,CAAA;KAClB,CAAA;IACD,gDAAgD;IAChD,MAAM,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,mFAAmF;IACnF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnD,qGAAqG;IACrG,WAAW,EAAE,MAAM,MAAM,IAAI,CAAA;IAC7B,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE;QACnB,KAAK,EAAE,MAAM,IAAI,CAAA;QACjB,IAAI,EAAE,MAAM,IAAI,CAAA;QAChB,6GAA6G;QAC7G,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAC5B,CAAA;IACD,qGAAqG;IACrG,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,uHAAuH;IACvH,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB;;;;eAmHvC,OAAO,CAAC,IAAI,CAAC;GAqCpC;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAA"}

package/dist/createBetterApp.js

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import cookie from '@fastify/cookie';
+import jwt from '@fastify/jwt';
+import multipart from '@fastify/multipart';
+import rateLimit from '@fastify/rate-limit';
+import { rateLimitKey } from './rateLimitKey.js';
+import staticFiles from '@fastify/static';
+import { errorHandler } from './errorHandler.js';
+import { redactUrl } from './redactUrl.js';
+import { resolveTrustProxy } from './proxy.js';
+import { createRuntimeShutdown } from './shutdown.js';
+const DEFAULT_JWT_SECRET = 'dev-secret-change-me';
+const EXAMPLE_SECRETS = new Set([
+    'change-me-to-a-long-random-string',
+    'change-me-to-a-64-char-hex-string',
+]);
+/** How long a signed-in session token lives. */
+export const JWT_EXPIRES_IN = '12h';
+/** The secret sessions are signed with: from `JWT_SECRET`, which production insists on being a real one. */
+export function resolveJwtSecret(env = process.env) {
+    const secret = env['JWT_SECRET'];
+    if (env['NODE_ENV'] !== 'production') {
+        if (!secret)
+            console.warn('JWT_SECRET not set - using insecure default (development only)');
+        return secret ?? DEFAULT_JWT_SECRET;
+    }
+    if (!secret || secret.length < 32 || EXAMPLE_SECRETS.has(secret)) {
+        throw new Error('JWT_SECRET must be set to a non-default value of at least 32 characters in production');
+    }
+    return secret;
+}
+/**
+ * Builds the HTTP application the Better products share: logging that hides credentials, proxy trust, CORS and a
+ * cross-site guard, cookies, JWT sessions, rate limiting, uploads, security headers, the database once set up, and the
+ * application's routes. `run` then takes the lock, listens, and wires the shutdown that closes everything in order.
+ */
+export async function createBetterApp(options) {
+    const redaction = { queryParams: options.redactQueryParams, pathTokenPrefixes: options.redactPathTokenPrefixes };
+    const app = Fastify({
+        logger: {
+            level: 'info',
+            redact: {
+                paths: ['req.headers.authorization', 'req.headers.cookie', 'res.headers["set-cookie"]'],
+                censor: '[redacted]',
+            },
+            serializers: {
+                req: (req) => ({
+                    method: req.method,
+                    url: redactUrl(req.url, redaction),
+                    host: req.host,
+                    remoteAddress: req.ip,
+                    ...(req.socket?.remotePort !== undefined ? { remotePort: req.socket.remotePort } : {}),
+                }),
+            },
+        },
+        trustProxy: resolveTrustProxy(),
+    });
+    app.setErrorHandler(errorHandler);
+    // CORS
+    const allowedOrigins = process.env['ALLOWED_ORIGINS']?.split(',').map((o) => o.trim());
+    await app.register(cors, {
+        origin: allowedOrigins
+            ?? (process.env['NODE_ENV'] === 'production' ? false : true),
+        credentials: true,
+    });
+    await app.register(cookie);
+    // Reject unsafe cross-site browser requests before they reach auth or setup routes.
+    app.addHook('onRequest', async (req, reply) => {
+        if (['GET', 'HEAD', 'OPTIONS'].includes(req.method))
+            return;
+        if (process.env['NODE_ENV'] !== 'production')
+            return;
+        if (req.headers['sec-fetch-site'] === 'cross-site') {
+            return reply.code(403).send({ error: 'Cross-site request rejected' });
+        }
+        const origin = req.headers.origin;
+        if (!origin)
+            return;
+        const ownOrigin = `${req.protocol}://${req.headers.host}`;
+        if (origin !== ownOrigin && !allowedOrigins?.includes(origin)) {
+            return reply.code(403).send({ error: 'Origin not allowed' });
+        }
+    });
+    // JWT
+    const jwtSecret = resolveJwtSecret();
+    options.validate?.();
+    await app.register(jwt, {
+        secret: jwtSecret,
+        sign: { expiresIn: JWT_EXPIRES_IN },
+    });
+    // Rate limiting (applied per-route where needed); IPv6 clients are counted per /64
+    await app.register(rateLimit, { global: false, keyGenerator: (req) => rateLimitKey(req.ip) });
+    // Multipart (file uploads)
+    await app.register(multipart, {
+        limits: { fileSize: options.uploads.maxFileBytes },
+    });
+    // Serve uploaded files
+    if (!fs.existsSync(options.uploads.dir)) {
+        fs.mkdirSync(options.uploads.dir, { recursive: true });
+    }
+    await app.register(staticFiles, {
+        root: options.uploads.dir,
+        prefix: '/uploads/',
+        decorateReply: false,
+    });
+    // Security headers
+    app.addHook('onSend', (req, reply, _payload, done) => {
+        const [requestPath = '', query = ''] = req.url.split('?', 2);
+        const framed = options.allowSameOriginFraming?.({ path: requestPath, query: new URLSearchParams(query) }) ?? false;
+        reply.header('X-Content-Type-Options', 'nosniff');
+        reply.header('X-Frame-Options', framed ? 'SAMEORIGIN' : 'DENY');
+        reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+        reply.header('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()');
+        reply.header('Cross-Origin-Opener-Policy', 'same-origin');
+        reply.header('Content-Security-Policy', [
+            "default-src 'self'",
+            "base-uri 'self'",
+            "object-src 'none'",
+            framed ? "frame-ancestors 'self'" : "frame-ancestors 'none'",
+            "form-action 'self'",
+            "script-src 'self'",
+            "style-src 'self' 'unsafe-inline'",
+            "font-src 'self'",
+            "img-src 'self' data: blob:",
+            "connect-src 'self'",
+        ].join('; '));
+        if (process.env['NODE_ENV'] === 'production') {
+            reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+        }
+        done();
+    });
+    // Initialize DB only when setup has been completed
+    if (options.database.isReady()) {
+        options.database.open();
+        options.database.migrate();
+    }
+    await options.routes(app);
+    // Serve built frontend apps in production
+    if (process.env['NODE_ENV'] === 'production')
+        await options.frontends?.(app);
+    /** Takes the lock, listens, and makes the process stop cleanly on SIGTERM and SIGINT. */
+    async function run() {
+        const port = options.port ?? Number(process.env['PORT'] ?? 3000);
+        const releaseLock = options.acquireLock();
+        const runtime = createRuntimeShutdown({
+            stopIntake: () => {
+                options.stopIntake?.();
+                options.backgroundServices?.stop();
+            },
+            closeServer: () => app.close(),
+            ...(options.backgroundServices?.drain ? { drain: options.backgroundServices.drain } : {}),
+            ...(options.shutdownDeadlineMs !== undefined ? { forceExitMs: options.shutdownDeadlineMs } : {}),
+            releaseResources: () => {
+                options.database.close();
+                releaseLock();
+            },
+            exit: (code) => process.exit(code),
+        });
+        // onClose runs after the HTTP server has drained, so the DB is no longer in use.
+        app.addHook('onClose', async () => {
+            runtime.cleanup();
+        });
+        try {
+            await app.listen({ port, host: '0.0.0.0' });
+        }
+        catch (error) {
+            runtime.cleanup();
+            throw error;
+        }
+        console.log(`✓ ${options.logName ?? 'API'} running on http://localhost:${port}`);
+        for (const signal of ['SIGTERM', 'SIGINT']) {
+            process.once(signal, runtime.shutdown);
+        }
+        if (options.database.isReady())
+            options.backgroundServices?.start();
+    }
+    return { app, run };
+}
+//# sourceMappingURL=createBetterApp.js.map

package/dist/createBetterApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBetterApp.js","sourceRoot":"","sources":["../src/createBetterApp.ts"],"names":[],"mappings":"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"}

package/dist/dataPaths.d.ts

@@ -0,0 +1,13 @@
+type Env = NodeJS.ProcessEnv;
+/** Where the application keeps its data: `DATA_DIR`, else `./data` under the working directory. */
+export declare function dataDir(env?: Env): string;
+/** The SQLite file: `DATABASE_PATH`, else `db.sqlite` in the data directory. */
+export declare function databasePath(env?: Env): string;
+/** The file that records the first-run setup was completed: `SETUP_CONFIG_PATH`, else `setup.json` in the data directory. */
+export declare function setupConfigPath(env?: Env): string;
+/** Where backups are written: `BACKUP_DIR`, else `backups` in the data directory. */
+export declare function backupDir(env?: Env): string;
+export declare function isSetupComplete(env?: Env): boolean;
+export declare function writeSetupComplete(dbType?: 'sqlite', env?: Env): void;
+export {};
+//# sourceMappingURL=dataPaths.d.ts.map

package/dist/dataPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataPaths.d.ts","sourceRoot":"","sources":["../src/dataPaths.ts"],"names":[],"mappings":"AAGA,KAAK,GAAG,GAAG,MAAM,CAAC,UAAU,CAAA;AAE5B,mGAAmG;AACnG,wBAAgB,OAAO,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAEtD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAE3D;AAED,6HAA6H;AAC7H,wBAAgB,eAAe,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAE9D;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,GAAG,GAAE,GAAiB,GAAG,MAAM,CAExD;AAOD,wBAAgB,eAAe,CAAC,GAAG,GAAE,GAAiB,GAAG,OAAO,CAU/D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,QAAmB,EAAE,GAAG,GAAE,GAAiB,GAAG,IAAI,CAK5F"}

package/dist/dataPaths.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Where the application keeps its data: `DATA_DIR`, else `./data` under the working directory. */
+export function dataDir(env = process.env) {
+    return path.resolve(env['DATA_DIR'] ?? path.join(process.cwd(), 'data'));
+}
+/** The SQLite file: `DATABASE_PATH`, else `db.sqlite` in the data directory. */
+export function databasePath(env = process.env) {
+    return path.resolve(env['DATABASE_PATH'] ?? path.join(dataDir(env), 'db.sqlite'));
+}
+/** The file that records the first-run setup was completed: `SETUP_CONFIG_PATH`, else `setup.json` in the data directory. */
+export function setupConfigPath(env = process.env) {
+    return path.resolve(env['SETUP_CONFIG_PATH'] ?? path.join(dataDir(env), 'setup.json'));
+}
+/** Where backups are written: `BACKUP_DIR`, else `backups` in the data directory. */
+export function backupDir(env = process.env) {
+    return path.resolve(env['BACKUP_DIR'] ?? path.join(dataDir(env), 'backups'));
+}
+export function isSetupComplete(env = process.env) {
+    try {
+        const file = setupConfigPath(env);
+        if (!fs.existsSync(file))
+            return false;
+        const cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return cfg.setupComplete === true;
+    }
+    catch {
+        // A marker that exists but cannot be read is not a fresh install: refuse setup rather than reopen it.
+        return true;
+    }
+}
+export function writeSetupComplete(dbType = 'sqlite', env = process.env) {
+    const file = setupConfigPath(env);
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ setupComplete: true, dbType }, null, 2));
+}
+//# sourceMappingURL=dataPaths.js.map

package/dist/dataPaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataPaths.js","sourceRoot":"","sources":["../src/dataPaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAI5B,mGAAmG;AACnG,MAAM,UAAU,OAAO,CAAC,MAAW,OAAO,CAAC,GAAG;IAC5C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;AAC1E,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,MAAW,OAAO,CAAC,GAAG;IACjD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC,CAAA;AACnF,CAAC;AAED,6HAA6H;AAC7H,MAAM,UAAU,eAAe,CAAC,MAAW,OAAO,CAAC,GAAG;IACpD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC,CAAA;AACxF,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,SAAS,CAAC,MAAW,OAAO,CAAC,GAAG;IAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC,CAAA;AAC9E,CAAC;AAOD,MAAM,UAAU,eAAe,CAAC,MAAW,OAAO,CAAC,GAAG;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;QACjC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAgB,CAAA;QACrE,OAAO,GAAG,CAAC,aAAa,KAAK,IAAI,CAAA;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,sGAAsG;QACtG,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAAmB,QAAQ,EAAE,MAAW,OAAO,CAAC,GAAG;IACpF,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/D,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;AAClF,CAAC"}

package/dist/errorHandler.d.ts

@@ -0,0 +1,8 @@
+import type { FastifyError, FastifyReply, FastifyRequest } from 'fastify';
+/**
+ * Unexpected failures are logged in full but never echoed to the client: driver errors carry the
+ * SQL and its parameters, which can include encrypted secrets. Client errors (4xx) keep their
+ * message in the `{ error }` shape the admin and status clients read.
+ */
+export declare function errorHandler(error: FastifyError, req: FastifyRequest, reply: FastifyReply): FastifyReply<import("fastify").RouteGenericInterface, import("fastify").RawServerDefault, import("node:http").IncomingMessage, import("node:http").ServerResponse<import("node:http").IncomingMessage>, unknown, import("fastify").FastifySchema, import("fastify").FastifyTypeProviderDefault, unknown>;
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../src/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEzE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,4SAOzF"}

package/dist/errorHandler.js

@@ -0,0 +1,14 @@
+/**
+ * Unexpected failures are logged in full but never echoed to the client: driver errors carry the
+ * SQL and its parameters, which can include encrypted secrets. Client errors (4xx) keep their
+ * message in the `{ error }` shape the admin and status clients read.
+ */
+export function errorHandler(error, req, reply) {
+    const statusCode = error.statusCode && error.statusCode >= 400 ? error.statusCode : 500;
+    if (statusCode >= 500) {
+        req.log.error({ err: error }, 'Unhandled request error');
+        return reply.code(statusCode).send({ error: 'Internal Server Error' });
+    }
+    return reply.code(statusCode).send({ error: error.message });
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/errorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../src/errorHandler.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB,EAAE,GAAmB,EAAE,KAAmB;IACxF,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAA;IACvF,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,yBAAyB,CAAC,CAAA;QACxD,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAA;IACxE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;AAC9D,CAAC"}

package/dist/health.d.ts

@@ -0,0 +1,57 @@
+import type { FastifyInstance } from 'fastify';
+import type { SqliteDatabase } from '@better-forge/db';
+import type { LatestRelease } from './updateCheck.js';
+/** `GET /health` (the process is up) and `GET /ready` (set up and the database answers), for load balancers and probes. */
+export declare function createHealthRoutes(options: {
+    db: SqliteDatabase;
+    isSetupComplete: () => boolean;
+}): (app: FastifyInstance) => Promise<void>;
+export type ComponentStatus = 'ok' | 'attention' | 'error' | 'disabled';
+/** One part of the system the report describes. Its `status` is what the overall status is decided by. */
+export type HealthSection = {
+    status: ComponentStatus;
+} & Record<string, unknown>;
+export interface HealthContributor {
+    /** The key of the section in the report. */
+    key: string;
+    /**
+     * When true, a section in the `error` status makes the whole report `degraded`; otherwise it is only shown.
+     */
+    critical: boolean;
+    /** Builds the section. Called after the database was probed; `now` is the time the report is made for. */
+    collect(context: {
+        now: number;
+        databaseOk: boolean;
+    }): Promise<HealthSection> | HealthSection;
+}
+export interface SystemHealthReport {
+    status: 'healthy' | 'degraded';
+    generatedAt: number;
+    application: {
+        status: 'ok';
+        version: string;
+        uptimeSeconds: number;
+        /** A newer published release, or null when up to date, unknown or the update check is off. */
+        update: LatestRelease | null;
+    };
+    database: {
+        status: 'ok' | 'error';
+        responseMs: number | null;
+    };
+    /** The sections of the contributors, by key. */
+    [section: string]: unknown;
+}
+/**
+ * The protected report of how the instance is doing: the process, the database, and one section per contributor the
+ * application registers (a scheduler, a queue, backups, ...). Exposes state, not raw errors.
+ */
+export declare function createSystemHealth(options: {
+    db: SqliteDatabase;
+    version: () => string;
+    update: () => LatestRelease | null;
+    contributors: readonly HealthContributor[];
+}): {
+    getSystemHealthReport: (now?: number) => Promise<SystemHealthReport>;
+    systemHealthRoutes: (app: FastifyInstance) => Promise<void>;
+};
+//# sourceMappingURL=health.d.ts.map

package/dist/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,2HAA2H;AAC3H,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,eAAe,EAAE,MAAM,OAAO,CAAA;CAAE,IAC7D,KAAK,eAAe,mBAexD;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,WAAW,GAAG,OAAO,GAAG,UAAU,CAAA;AAEvE,0GAA0G;AAC1G,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjF,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAA;IACX;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,0GAA0G;IAC1G,OAAO,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAA;CAC/F;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAA;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE;QACX,MAAM,EAAE,IAAI,CAAA;QACZ,OAAO,EAAE,MAAM,CAAA;QACf,aAAa,EAAE,MAAM,CAAA;QACrB,8FAA8F;QAC9F,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;KAC7B,CAAA;IACD,QAAQ,EAAE;QACR,MAAM,EAAE,IAAI,GAAG,OAAO,CAAA;QACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAC1B,CAAA;IACD,gDAAgD;IAChD,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,EAAE,EAAE,cAAc,CAAA;IAClB,OAAO,EAAE,MAAM,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,aAAa,GAAG,IAAI,CAAA;IAClC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAC3C;6CACyD,OAAO,CAAC,kBAAkB,CAAC;8BA0B5C,eAAe;EAcvD"}

package/dist/health.js

@@ -0,0 +1,62 @@
+import { sql } from 'drizzle-orm';
+/** `GET /health` (the process is up) and `GET /ready` (set up and the database answers), for load balancers and probes. */
+export function createHealthRoutes(options) {
+    return async function healthRoutes(app) {
+        app.get('/health', async () => ({ status: 'ok' }));
+        app.get('/ready', async (_req, reply) => {
+            if (!options.isSetupComplete()) {
+                return reply.code(503).send({ status: 'not_ready' });
+            }
+            try {
+                await options.db.run(sql `SELECT 1`);
+                return { status: 'ready' };
+            }
+            catch {
+                return reply.code(503).send({ status: 'not_ready' });
+            }
+        });
+    };
+}
+/**
+ * The protected report of how the instance is doing: the process, the database, and one section per contributor the
+ * application registers (a scheduler, a queue, backups, ...). Exposes state, not raw errors.
+ */
+export function createSystemHealth(options) {
+    async function getSystemHealthReport(now = Date.now()) {
+        const databaseStartedAt = Date.now();
+        let database = { status: 'error', responseMs: null };
+        try {
+            await options.db.run(sql `SELECT 1`);
+            database = { status: 'ok', responseMs: Date.now() - databaseStartedAt };
+        }
+        catch {
+            // The protected report deliberately exposes state, not raw database errors.
+        }
+        const sections = {};
+        for (const contributor of options.contributors) {
+            sections[contributor.key] = await contributor.collect({ now, databaseOk: database.status === 'ok' });
+        }
+        const failing = options.contributors.some((contributor) => contributor.critical && sections[contributor.key].status === 'error');
+        return {
+            status: database.status === 'ok' && !failing ? 'healthy' : 'degraded',
+            generatedAt: now,
+            application: { status: 'ok', version: options.version(), uptimeSeconds: Math.floor(process.uptime()), update: options.update() },
+            database,
+            ...sections,
+        };
+    }
+    /** Routes: the report at `/` and, at `/update`, only the running version and a newer release, if any. */
+    async function systemHealthRoutes(app) {
+        app.get('/', async (_request, reply) => {
+            reply.header('Cache-Control', 'no-store');
+            return getSystemHealthReport();
+        });
+        /** Cheap enough for a dashboard to ask on every visit. */
+        app.get('/update', async (_request, reply) => {
+            reply.header('Cache-Control', 'no-store');
+            return { version: options.version(), update: options.update() };
+        });
+    }
+    return { getSystemHealthReport, systemHealthRoutes };
+}
+//# sourceMappingURL=health.js.map

package/dist/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../src/health.ts"],"names":[],"mappings":"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"}