@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/routes/scripts.routes.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Scripts Routes — Serve client scripts for download
+ * Routes: GET /scripts, GET /scripts/:name
+ *
+ * Provides downloadable REST client scripts for agents and users
+ * that lack MCP tool access and need to interact via HTTP.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createScriptsRoutes = createScriptsRoutes;
+const express_1 = require("express");
+const promises_1 = require("fs/promises");
+const path_1 = __importDefault(require("path"));
+/** Allowed script files with metadata */
+const AVAILABLE_SCRIPTS = {
+    'index-server-client.ps1': {
+        file: 'index-server-client.ps1',
+        contentType: 'application/octet-stream',
+        description: 'PowerShell REST client for Index Server (agents without MCP)',
+    },
+    'index-server-client.sh': {
+        file: 'index-server-client.sh',
+        contentType: 'application/octet-stream',
+        description: 'Bash REST client for Index Server (agents without MCP)',
+    },
+};
+function createScriptsRoutes() {
+    const router = (0, express_1.Router)();
+    /**
+     * GET /api/scripts — List available client scripts with download URLs
+     */
+    router.get('/scripts', (_req, res) => {
+        const scripts = Object.entries(AVAILABLE_SCRIPTS).map(([name, meta]) => ({
+            name,
+            description: meta.description,
+            downloadUrl: `/api/scripts/${name}`,
+        }));
+        res.setHeader('Cache-Control', 'no-store');
+        res.json({ scripts });
+    });
+    /**
+     * GET /api/scripts/:name — Download a specific client script
+     */
+    router.get('/scripts/:name', async (req, res) => {
+        const name = req.params.name;
+        // Validate against allowlist (no path traversal)
+        const meta = AVAILABLE_SCRIPTS[name];
+        if (!meta) {
+            res.status(404).json({
+                error: `Script not found: ${name}`,
+                available: Object.keys(AVAILABLE_SCRIPTS),
+            });
+            return;
+        }
+        try {
+            const scriptsDir = path_1.default.join(process.cwd(), 'scripts');
+            const filePath = path_1.default.join(scriptsDir, meta.file);
+            // Verify resolved path is within scripts directory (defense in depth)
+            const resolved = path_1.default.resolve(filePath);
+            if (!resolved.startsWith(path_1.default.resolve(scriptsDir))) {
+                res.status(400).json({ error: 'Invalid script path' });
+                return;
+            }
+            const content = await (0, promises_1.readFile)(resolved, 'utf-8');
+            res.setHeader('Content-Type', meta.contentType);
+            res.setHeader('Content-Disposition', `attachment; filename="${meta.file}"`);
+            res.setHeader('X-Content-Type-Options', 'nosniff');
+            res.send(content);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('ENOENT')) {
+                res.status(404).json({ error: `Script file not found on disk: ${name}` });
+            }
+            else {
+                res.status(500).json({ error: `Failed to read script: ${message}` });
+            }
+        }
+    });
+    return router;
+}

package/dist/dashboard/server/routes/sqlite.routes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SQLite dashboard routes — DB info, ad-hoc query, maintenance,
+ * backup/restore, WAL management, grooming, migration & export.
+ *
+ * Only active when INDEX_SERVER_STORAGE_BACKEND=sqlite.
+ * All routes prefixed with /sqlite/.
+ */
+import { Router } from 'express';
+export declare function createSqliteRoutes(): Router;

package/dist/dashboard/server/routes/sqlite.routes.js

@@ -0,0 +1,569 @@
+"use strict";
+/**
+ * SQLite dashboard routes — DB info, ad-hoc query, maintenance,
+ * backup/restore, WAL management, grooming, migration & export.
+ *
+ * Only active when INDEX_SERVER_STORAGE_BACKEND=sqlite.
+ * All routes prefixed with /sqlite/.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSqliteRoutes = createSqliteRoutes;
+const express_1 = require("express");
+const runtimeConfig_js_1 = require("../../../config/runtimeConfig.js");
+const node_sqlite_1 = require("node:sqlite");
+const migrationEngine_js_1 = require("../../../services/storage/migrationEngine.js");
+const sqliteSchema_js_1 = require("../../../services/storage/sqliteSchema.js");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function getSqlitePath() {
+    return (0, runtimeConfig_js_1.getRuntimeConfig)().storage?.sqlitePath ?? '';
+}
+function assertSqliteActive() {
+    if (((0, runtimeConfig_js_1.getRuntimeConfig)().storage?.backend ?? 'json') !== 'sqlite') {
+        throw Object.assign(new Error('SQLite backend not active'), { statusCode: 400 });
+    }
+}
+function getBackupsDir() {
+    return (0, runtimeConfig_js_1.getRuntimeConfig)().dashboard.admin.backupsDir;
+}
+function createSqliteRoutes() {
+    const router = (0, express_1.Router)();
+    /** GET /sqlite/info — Database stats and config */
+    router.get('/sqlite/info', (_req, res) => {
+        try {
+            const config = (0, runtimeConfig_js_1.getRuntimeConfig)();
+            const backend = config.storage?.backend ?? 'json';
+            const sqlitePath = config.storage?.sqlitePath ?? '';
+            const walEnabled = config.storage?.sqliteWal ?? true;
+            if (backend !== 'sqlite') {
+                return res.json({
+                    success: true,
+                    active: false,
+                    backend: 'json',
+                    message: 'SQLite backend is not active. Set INDEX_SERVER_STORAGE_BACKEND=sqlite to enable.',
+                });
+            }
+            // Get file size if DB exists
+            let fileSize = 0;
+            let walSize = 0;
+            let shmSize = 0;
+            let exists = false;
+            try {
+                if (fs_1.default.existsSync(sqlitePath)) {
+                    exists = true;
+                    fileSize = fs_1.default.statSync(sqlitePath).size;
+                    const walPath = sqlitePath + '-wal';
+                    const shmPath = sqlitePath + '-shm';
+                    if (fs_1.default.existsSync(walPath))
+                        walSize = fs_1.default.statSync(walPath).size;
+                    if (fs_1.default.existsSync(shmPath))
+                        shmSize = fs_1.default.statSync(shmPath).size;
+                }
+            }
+            catch { /* ignore */ }
+            // Query DB stats using node:sqlite
+            const tableStats = {};
+            const pragmas = {};
+            try {
+                const db = new node_sqlite_1.DatabaseSync(sqlitePath, { readOnly: true });
+                try {
+                    // Count rows in key tables
+                    for (const table of ['instructions', 'messages', 'usage', 'metadata']) {
+                        try {
+                            const row = db.prepare(`SELECT COUNT(*) as cnt FROM ${table}`).get();
+                            tableStats[table] = row?.cnt ?? 0;
+                        }
+                        catch { /* table may not exist */ }
+                    }
+                    // Read pragmas
+                    try {
+                        const jm = db.prepare('PRAGMA journal_mode').get();
+                        pragmas.journalMode = jm?.journal_mode ?? 'unknown';
+                    }
+                    catch { /* ignore */ }
+                    try {
+                        const ps = db.prepare('PRAGMA page_size').get();
+                        pragmas.pageSize = ps?.page_size ?? 0;
+                    }
+                    catch { /* ignore */ }
+                    try {
+                        const pc = db.prepare('PRAGMA page_count').get();
+                        pragmas.pageCount = pc?.page_count ?? 0;
+                    }
+                    catch { /* ignore */ }
+                    try {
+                        const fl = db.prepare('PRAGMA freelist_count').get();
+                        pragmas.freelistCount = fl?.freelist_count ?? 0;
+                    }
+                    catch { /* ignore */ }
+                }
+                finally {
+                    db.close();
+                }
+            }
+            catch { /* node:sqlite not available */ }
+            return res.json({
+                success: true,
+                active: true,
+                backend: 'sqlite',
+                dbPath: sqlitePath,
+                exists,
+                fileSize,
+                walSize,
+                shmSize,
+                walEnabled,
+                tableStats,
+                pragmas,
+            });
+        }
+        catch (err) {
+            return res.status(500).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/query — Execute read-only SQL query */
+    router.post('/sqlite/query', (req, res) => {
+        try {
+            assertSqliteActive();
+            const { sql } = req.body;
+            if (!sql || typeof sql !== 'string') {
+                return res.status(400).json({ success: false, error: 'Missing "sql" field in request body' });
+            }
+            // Safety: only allow SELECT and PRAGMA
+            const trimmed = sql.trim().toUpperCase();
+            if (!trimmed.startsWith('SELECT') && !trimmed.startsWith('PRAGMA') && !trimmed.startsWith('EXPLAIN')) {
+                return res.status(403).json({
+                    success: false,
+                    error: 'Only SELECT, PRAGMA, and EXPLAIN queries are allowed',
+                });
+            }
+            // Reject multi-statement queries and enforce length limit
+            if (sql.length > 10000) {
+                return res.status(400).json({ success: false, error: 'Query exceeds maximum length (10000 chars)' });
+            }
+            if (/;\s*\S/.test(sql)) {
+                return res.status(403).json({ success: false, error: 'Multi-statement queries are not allowed' });
+            }
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath, { readOnly: true });
+            try {
+                const rows = db.prepare(sql).all();
+                const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+                return res.json({
+                    success: true,
+                    columns,
+                    rows,
+                    rowCount: rows.length,
+                });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 400;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/vacuum — Run VACUUM to reclaim space */
+    router.post('/sqlite/vacuum', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                db.exec('VACUUM');
+                const sizeAfter = fs_1.default.existsSync(sqlitePath) ? fs_1.default.statSync(sqlitePath).size : 0;
+                return res.json({ success: true, message: 'VACUUM completed', sizeAfter });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/optimize — Run FTS5 optimize */
+    router.post('/sqlite/optimize', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                db.exec("INSERT INTO instructions_fts(instructions_fts) VALUES('optimize')");
+                return res.json({ success: true, message: 'FTS5 index optimized' });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/integrity-check — Run SQLite integrity check */
+    router.post('/sqlite/integrity-check', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath, { readOnly: true });
+            try {
+                const rows = db.prepare('PRAGMA integrity_check').all();
+                const ok = rows.length === 1 && rows[0].integrity_check === 'ok';
+                return res.json({ success: true, ok, results: rows });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    // ── Backup / Restore ──────────────────────────────────────────────────
+    /** POST /sqlite/backup — Create manual backup of the SQLite DB */
+    router.post('/sqlite/backup', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            if (!fs_1.default.existsSync(sqlitePath)) {
+                return res.status(404).json({ success: false, error: 'Database file not found' });
+            }
+            const backupsRoot = getBackupsDir();
+            fs_1.default.mkdirSync(backupsRoot, { recursive: true });
+            const stamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15);
+            const backupDir = path_1.default.join(backupsRoot, `manual-backup-${stamp}`);
+            fs_1.default.mkdirSync(backupDir, { recursive: true });
+            // Checkpoint WAL before backup for consistency
+            try {
+                const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+                try {
+                    db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+                }
+                finally {
+                    db.close();
+                }
+            }
+            catch { /* best-effort checkpoint */ }
+            fs_1.default.copyFileSync(sqlitePath, path_1.default.join(backupDir, 'index.db'));
+            if (fs_1.default.existsSync(sqlitePath + '-wal'))
+                fs_1.default.copyFileSync(sqlitePath + '-wal', path_1.default.join(backupDir, 'index.db-wal'));
+            if (fs_1.default.existsSync(sqlitePath + '-shm'))
+                fs_1.default.copyFileSync(sqlitePath + '-shm', path_1.default.join(backupDir, 'index.db-shm'));
+            const backupSize = fs_1.default.statSync(path_1.default.join(backupDir, 'index.db')).size;
+            return res.json({ success: true, message: 'Backup created', backupDir, backupSize });
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** GET /sqlite/backups — List available backups */
+    router.get('/sqlite/backups', (_req, res) => {
+        try {
+            const backupsRoot = getBackupsDir();
+            if (!fs_1.default.existsSync(backupsRoot)) {
+                return res.json({ success: true, backups: [] });
+            }
+            const dirs = fs_1.default.readdirSync(backupsRoot)
+                .filter(d => {
+                const full = path_1.default.join(backupsRoot, d);
+                return fs_1.default.statSync(full).isDirectory() && fs_1.default.existsSync(path_1.default.join(full, 'index.db'));
+            })
+                .map(d => {
+                const full = path_1.default.join(backupsRoot, d);
+                const dbSize = fs_1.default.statSync(path_1.default.join(full, 'index.db')).size;
+                const created = fs_1.default.statSync(full).mtime.toISOString();
+                return { name: d, path: full, dbSize, created };
+            })
+                .sort((a, b) => b.created.localeCompare(a.created));
+            return res.json({ success: true, backups: dirs });
+        }
+        catch (err) {
+            return res.status(500).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/restore — Restore from a named backup */
+    router.post('/sqlite/restore', (req, res) => {
+        try {
+            assertSqliteActive();
+            const { backupName } = req.body;
+            if (!backupName || typeof backupName !== 'string') {
+                return res.status(400).json({ success: false, error: 'Missing "backupName" field' });
+            }
+            // Sanitize: no path traversal
+            if (backupName.includes('..') || backupName.includes('/') || backupName.includes('\\')) {
+                return res.status(400).json({ success: false, error: 'Invalid backup name' });
+            }
+            const backupsRoot = getBackupsDir();
+            const backupDir = path_1.default.join(backupsRoot, backupName);
+            const backupDb = path_1.default.join(backupDir, 'index.db');
+            if (!fs_1.default.existsSync(backupDb)) {
+                return res.status(404).json({ success: false, error: 'Backup not found: ' + backupName });
+            }
+            const sqlitePath = getSqlitePath();
+            // Auto-backup current DB before overwriting
+            if (fs_1.default.existsSync(sqlitePath)) {
+                const stamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15);
+                const preRestoreDir = path_1.default.join(backupsRoot, `pre-restore-${stamp}`);
+                fs_1.default.mkdirSync(preRestoreDir, { recursive: true });
+                fs_1.default.copyFileSync(sqlitePath, path_1.default.join(preRestoreDir, 'index.db'));
+                if (fs_1.default.existsSync(sqlitePath + '-wal'))
+                    fs_1.default.copyFileSync(sqlitePath + '-wal', path_1.default.join(preRestoreDir, 'index.db-wal'));
+                if (fs_1.default.existsSync(sqlitePath + '-shm'))
+                    fs_1.default.copyFileSync(sqlitePath + '-shm', path_1.default.join(preRestoreDir, 'index.db-shm'));
+            }
+            // Restore: copy backup files over current DB
+            fs_1.default.copyFileSync(backupDb, sqlitePath);
+            const walFile = path_1.default.join(backupDir, 'index.db-wal');
+            const shmFile = path_1.default.join(backupDir, 'index.db-shm');
+            if (fs_1.default.existsSync(walFile)) {
+                fs_1.default.copyFileSync(walFile, sqlitePath + '-wal');
+            }
+            else {
+                // Remove stale WAL/SHM from previous DB
+                try {
+                    fs_1.default.unlinkSync(sqlitePath + '-wal');
+                }
+                catch { /* ok */ }
+            }
+            if (fs_1.default.existsSync(shmFile)) {
+                fs_1.default.copyFileSync(shmFile, sqlitePath + '-shm');
+            }
+            else {
+                try {
+                    fs_1.default.unlinkSync(sqlitePath + '-shm');
+                }
+                catch { /* ok */ }
+            }
+            return res.json({ success: true, message: 'Restored from ' + backupName });
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    // ── Reset / Migrate ───────────────────────────────────────────────────
+    /** POST /sqlite/reset — Drop all tables and reinitialize schema */
+    router.post('/sqlite/reset', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            // Auto-backup before reset
+            if (fs_1.default.existsSync(sqlitePath)) {
+                const backupsRoot = getBackupsDir();
+                fs_1.default.mkdirSync(backupsRoot, { recursive: true });
+                const stamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 15);
+                const preResetDir = path_1.default.join(backupsRoot, `pre-reset-${stamp}`);
+                fs_1.default.mkdirSync(preResetDir, { recursive: true });
+                fs_1.default.copyFileSync(sqlitePath, path_1.default.join(preResetDir, 'index.db'));
+            }
+            // Delete the DB file and WAL/SHM — fresh start
+            try {
+                fs_1.default.unlinkSync(sqlitePath);
+            }
+            catch { /* ok */ }
+            try {
+                fs_1.default.unlinkSync(sqlitePath + '-wal');
+            }
+            catch { /* ok */ }
+            try {
+                fs_1.default.unlinkSync(sqlitePath + '-shm');
+            }
+            catch { /* ok */ }
+            // Reinitialize schema
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                db.exec(sqliteSchema_js_1.PRAGMAS);
+                db.exec(sqliteSchema_js_1.INSTRUCTIONS_DDL);
+                try {
+                    db.exec(sqliteSchema_js_1.FTS5_DDL);
+                }
+                catch { /* FTS5 may already exist */ }
+                return res.json({ success: true, message: 'Database reset — schema reinitialized' });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/migrate — Migrate instructions from JSON files to SQLite */
+    router.post('/sqlite/migrate', async (_req, res) => {
+        try {
+            assertSqliteActive();
+            const instrDir = (0, runtimeConfig_js_1.getRuntimeConfig)().index.baseDir;
+            const sqlitePath = getSqlitePath();
+            const result = await (0, migrationEngine_js_1.migrateJsonToSqlite)(instrDir, sqlitePath);
+            return res.json({
+                success: true,
+                message: `Migrated ${result.migrated} instructions`,
+                migrated: result.migrated,
+                errors: result.errors,
+            });
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/export — Export SQLite instructions back to JSON files */
+    router.post('/sqlite/export', async (_req, res) => {
+        try {
+            assertSqliteActive();
+            const instrDir = (0, runtimeConfig_js_1.getRuntimeConfig)().index.baseDir;
+            const sqlitePath = getSqlitePath();
+            const result = await (0, migrationEngine_js_1.migrateSqliteToJson)(sqlitePath, instrDir);
+            return res.json({
+                success: true,
+                message: `Exported ${result.exported} instructions to JSON`,
+                exported: result.exported,
+                errors: result.errors,
+            });
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    // ── WAL Management ────────────────────────────────────────────────────
+    /** POST /sqlite/wal-checkpoint — Flush WAL to main database file */
+    router.post('/sqlite/wal-checkpoint', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                const row = db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get();
+                const walSizeAfter = fs_1.default.existsSync(sqlitePath + '-wal') ? fs_1.default.statSync(sqlitePath + '-wal').size : 0;
+                return res.json({
+                    success: true,
+                    message: 'WAL checkpoint completed (TRUNCATE)',
+                    checkpoint: row,
+                    walSizeAfter,
+                });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/analyze — Update query planner statistics */
+    router.post('/sqlite/analyze', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                db.exec('ANALYZE');
+                return res.json({ success: true, message: 'ANALYZE completed — query planner stats updated' });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    /** POST /sqlite/reindex — Rebuild all indexes */
+    router.post('/sqlite/reindex', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            try {
+                db.exec('REINDEX');
+                return res.json({ success: true, message: 'REINDEX completed — all indexes rebuilt' });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    // ── Grooming ──────────────────────────────────────────────────────────
+    /** POST /sqlite/groom — Clean up orphans, stale data, run optimizations */
+    router.post('/sqlite/groom', (_req, res) => {
+        try {
+            assertSqliteActive();
+            const sqlitePath = getSqlitePath();
+            const db = new node_sqlite_1.DatabaseSync(sqlitePath);
+            const results = [];
+            try {
+                // 1. Remove orphaned messages (messages referencing non-existent instructions)
+                try {
+                    const orphanMsgs = db.prepare(`
+            DELETE FROM messages WHERE id IN (
+              SELECT m.id FROM messages m
+              LEFT JOIN instructions i ON m.recipient = i.id
+              WHERE m.recipient IS NOT NULL AND i.id IS NULL
+            )
+          `).run();
+                    results.push(`Orphaned messages removed: ${orphanMsgs.changes}`);
+                }
+                catch {
+                    results.push('Messages table: skipped (may not exist)');
+                }
+                // 2. Remove orphaned usage records
+                try {
+                    const orphanUsage = db.prepare(`
+            DELETE FROM usage WHERE instruction_id NOT IN (SELECT id FROM instructions)
+          `).run();
+                    results.push(`Orphaned usage records removed: ${orphanUsage.changes}`);
+                }
+                catch {
+                    results.push('Usage table: skipped (may not exist)');
+                }
+                // 3. Remove deprecated instructions (status = 'deprecated' and older than 90 days)
+                try {
+                    const deprecated = db.prepare(`
+            DELETE FROM instructions WHERE json_extract(data, '$.governanceStatus') = 'deprecated'
+            AND updated_at < datetime('now', '-90 days')
+          `).run();
+                    results.push(`Deprecated instructions removed (>90 days): ${deprecated.changes}`);
+                }
+                catch {
+                    results.push('Deprecated cleanup: skipped');
+                }
+                // 4. Optimize FTS5
+                try {
+                    db.exec("INSERT INTO instructions_fts(instructions_fts) VALUES('optimize')");
+                    results.push('FTS5 index optimized');
+                }
+                catch {
+                    results.push('FTS5 optimize: skipped');
+                }
+                // 5. ANALYZE for query planner
+                db.exec('ANALYZE');
+                results.push('ANALYZE completed');
+                return res.json({ success: true, message: 'Grooming completed', results });
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (err) {
+            const code = err.statusCode ?? 500;
+            return res.status(code).json({ success: false, error: err.message });
+        }
+    });
+    return router;
+}

package/dist/dashboard/server/routes/status.routes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Status & Health Routes
+ * Routes: GET /status, GET /health, GET /system/health, GET /system/resources
+ */
+import { Router } from 'express';
+import { MetricsCollector } from '../MetricsCollector.js';
+export declare function createStatusRoutes(metricsCollector: MetricsCollector): Router;