@package-broker/adapter-node 0.3.9 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@package-broker/adapter-node",
-  "version": "0.3.9",
+  "version": "0.5.0",
   "type": "module",
   "keywords": [],
   "scripts": {

package/scripts/migrate.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+/**
+ * Database Migration Script
+ * Runs Drizzle migrations for SQLite database
+ * 
+ * Usage:
+ *   node scripts/migrate.js <db_path> [migrations_path]
+ * 
+ * Example:
+ *   node scripts/migrate.js /data/database.sqlite
+ *   node scripts/migrate.js /data/database.sqlite /app/packages/main/migrations
+ */
+
+const { SqliteDriver } = require('../dist/drivers/sqlite-driver.cjs');
+const path = require('path');
+
+const dbPath = process.argv[2];
+const migrationsPath = process.argv[3] || 'packages/main/migrations';
+
+if (!dbPath) {
+    console.error('❌ Error: Database path is required');
+    console.error('Usage: node scripts/migrate.js <db_path> [migrations_path]');
+    process.exit(1);
+}
+
+async function runMigrations() {
+    try {
+        console.log(`Initializing database at: ${dbPath}`);
+        const driver = new SqliteDriver(dbPath);
+        
+        const absoluteMigrationsPath = path.isAbsolute(migrationsPath)
+            ? migrationsPath
+            : path.join(process.cwd(), migrationsPath);
+        
+        console.log(`Running migrations from: ${absoluteMigrationsPath}`);
+        await driver.runMigrations(absoluteMigrationsPath);
+        
+        console.log('✅ Database migrations completed successfully');
+        process.exit(0);
+    } catch (error) {
+        console.error('❌ Migration failed:', error.message);
+        console.error(error.stack);
+        process.exit(1);
+    }
+}
+
+runMigrations();

package/src/drivers/sqlite-driver.ts

@@ -1,23 +1,76 @@
-
 import Database from 'better-sqlite3';
 import { drizzle } from 'drizzle-orm/better-sqlite3';
 import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
-import { schema, type DatabasePort } from '@package-broker/core';
+import { schema, type DatabasePort, type DatabaseDriver } from '@package-broker/core';
+import path from 'node:path';
+
+export interface SqliteConnection {
+    db: DatabasePort;
+    sqlite: Database.Database;
+}
 
-export function createSqliteDatabase(dbPath: string): DatabasePort {
+/**
+ * Create a SQLite database connection
+ */
+export function createSqliteDatabase(dbPath: string): SqliteConnection {
     const sqlite = new Database(dbPath);
     const db = drizzle(sqlite, { schema });
 
-    // Create method to satisfy the DatabasePort interface if strictly typed, 
-    // but usually generic ORM usages work fine. 
-    // Note: DatabasePort in core is currently aliased to DrizzleD1Database<typeof schema>.
-    // We need to make sure core/db/index.ts types are flexible enough.
-    // Ideally, core should export a generic Drizzle type.
-
-    return db as any;
+    return { db: db as any, sqlite };
 }
 
-export async function migrateSqliteDatabase(db: ReturnType<typeof drizzle>, migrationsFolder: string) {
-    // This helper runs migrations on startup
-    await migrate(db, { migrationsFolder });
+/**
+ * SQLite Database Driver
+ * Implements DatabaseDriver interface for SQLite using Drizzle ORM
+ */
+export class SqliteDriver implements DatabaseDriver {
+    private connection: SqliteConnection;
+
+    constructor(dbPath: string) {
+        this.connection = createSqliteDatabase(dbPath);
+    }
+
+    /**
+     * Check if database is initialized by checking for Drizzle's migrations table
+     * This is database-agnostic as Drizzle uses __drizzle_migrations for all databases
+     */
+    async isInitialized(): Promise<boolean> {
+        const { sqlite } = this.connection;
+        try {
+            // Check for Drizzle's migration tracking table (database-agnostic approach)
+            const result = sqlite.prepare(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='__drizzle_migrations'"
+            ).get();
+            return !!result;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Run migrations using Drizzle's migrator
+     * Uses migration files from the specified path (e.g., packages/main/migrations)
+     */
+    async runMigrations(migrationsPath: string): Promise<void> {
+        const { db } = this.connection;
+        const absolutePath = path.isAbsolute(migrationsPath) 
+            ? migrationsPath 
+            : path.join(process.cwd(), migrationsPath);
+        
+        await migrate(db as any, { migrationsFolder: absolutePath });
+    }
+
+    /**
+     * Get the database connection/ORM instance
+     */
+    getConnection(): DatabasePort {
+        return this.connection.db;
+    }
+
+    /**
+     * Get the raw SQLite connection (for driver-specific operations if needed)
+     */
+    getSqliteConnection(): Database.Database {
+        return this.connection.sqlite;
+    }
 }

package/src/index.ts

@@ -1,8 +1,8 @@
-
 import { serve } from '@hono/node-server';
-import { createApp, type AppInstance } from '@package-broker/core';
+import { Hono } from 'hono';
+import { createApp, type AppInstance, type DatabaseDriver } from '@package-broker/core';
 import { config } from 'dotenv';
-import { createSqliteDatabase, migrateSqliteDatabase } from './drivers/sqlite-driver.js';
+import { SqliteDriver } from './drivers/sqlite-driver.js';
 import { FileSystemDriver } from './drivers/fs-driver.js';
 import { RedisDriver } from './drivers/redis-driver.js';
 import { MemoryCacheDriver, MemoryQueueDriver } from '@package-broker/core';
@@ -23,21 +23,51 @@ const STORAGE_PATH = process.env.STORAGE_PATH || './storage';
 const CACHE_DRIVER = process.env.CACHE_DRIVER || 'memory';
 const CACHE_URL = process.env.CACHE_URL || 'redis://localhost:6379';
 const QUEUE_DRIVER = process.env.QUEUE_DRIVER || 'memory';
+const MIGRATIONS_PATH = process.env.MIGRATIONS_PATH || 'packages/main/migrations';
+
+const DOCS_URL = 'https://package-broker.github.io/docs/installation/docker';
 
 console.log('Starting PACKAGE.broker Node Adapter...');
 console.log(`Configuration: DB=${DB_DRIVER}, STORAGE=${STORAGE_DRIVER}, CACHE=${CACHE_DRIVER}, QUEUE=${QUEUE_DRIVER}`);
 
+/**
+ * Get the database not initialized error response
+ * DRY: Single source of truth for error response structure
+ */
+function getDatabaseNotInitializedError() {
+    return {
+        error: 'DATABASE_NOT_INITIALIZED',
+        message: 'Database not initialized. Please run migrations.',
+        docsUrl: DOCS_URL
+    };
+}
+
 async function start() {
-    // Initialize Drivers
-    let database;
+    // Initialize Database Driver (Port-Adapter pattern)
+    let databaseDriver: DatabaseDriver;
+    
     if (DB_DRIVER === 'sqlite') {
         console.log(`Initializing SQLite at ${DB_URL}`);
-        database = createSqliteDatabase(DB_URL);
-        // Auto-migrate on start (simplified for MVP)
-        // In real deployment, migrations should be separate step
+        databaseDriver = new SqliteDriver(DB_URL);
     } else {
         throw new Error(`Unsupported DB_DRIVER: ${DB_DRIVER}`);
     }
+    
+    // Check if database needs initialization (database-agnostic check)
+    const isDatabaseReady = await databaseDriver.isInitialized();
+    
+    if (!isDatabaseReady) {
+        console.warn('');
+        console.warn('⚠️  DATABASE NOT INITIALIZED');
+        console.warn('   The database tables have not been created yet.');
+        console.warn('   A warning page will be shown to users until migrations are run.');
+        console.warn(`   📖 Documentation: ${DOCS_URL}`);
+        console.warn('');
+    } else {
+        console.log('Database initialized and ready.');
+    }
+    
+    const database = databaseDriver.getConnection();
 
     let storage;
     if (STORAGE_DRIVER === 'fs') {
@@ -70,40 +100,73 @@ async function start() {
         queue = new MemoryQueueDriver();
     }
 
-    // Create App
+    // If database is not ready, return error for API requests
+    if (!isDatabaseReady) {
+        const warningApp = new Hono();
+        const errorResponse = getDatabaseNotInitializedError();
+        
+        // Health endpoint returns warning status (200 OK with error status in body for CI compatibility)
+        warningApp.get('/health', (c) => {
+            return c.json({ 
+                status: 'error', 
+                ...errorResponse
+            }, 200); // Return 200 for CI health checks, but include error status
+        });
+        
+        // All API requests return JSON error (BEFORE static files)
+        warningApp.all('/api/*', (c) => {
+            return c.json(errorResponse, 503);
+        });
+        
+        // Serve static files if PUBLIC_DIR is set (UI will display the error)
+        if (process.env.PUBLIC_DIR) {
+            warningApp.use('/*', serveStatic({ root: process.env.PUBLIC_DIR }));
+            warningApp.get('*', async (c) => {
+                try {
+                    return c.html(await readFile(path.join(process.env.PUBLIC_DIR!, 'index.html'), 'utf-8'));
+                } catch (e) {
+                    return c.text('Not Found', 404);
+                }
+            });
+        }
+        
+        console.log(`Server listening on port ${PORT} (WARNING: Database not initialized)`);
+        serve({
+            fetch: warningApp.fetch,
+            port: PORT
+        });
+        return;
+    }
+
+    // Create App (API routes are registered inside createApp)
     const app = createApp({
         database,
         storage,
-        onInit: (appInstance: AppInstance) => {
-            // Inject non-standard drivers if needed or custom middleware
-            appInstance.use('*', async (c: Context, next: Next) => {
-                // We already passed database/storage to createApp, but we can set extra vars here
-                // Note: createApp factory handles database/storage injection if passed in options
-                await next();
-            });
+        cache,
+    });
 
-            // Serve config.js dynamically
-            appInstance.get('/config.js', (c: Context) => {
-                return c.text(`window.env = { API_URL: "${process.env.API_URL || '/'}" };`, 200, {
-                    'Content-Type': 'application/javascript',
-                });
-            });
+    // Serve config.js dynamically (AFTER API routes)
+    app.get('/config.js', (c: Context) => {
+        return c.text(`window.env = { API_URL: "${process.env.API_URL || '/'}" };`, 200, {
+            'Content-Type': 'application/javascript',
+        });
+    });
 
-            if (process.env.PUBLIC_DIR) {
-                console.log(`Serving static files from ${process.env.PUBLIC_DIR}`);
-                appInstance.use('/*', serveStatic({ root: process.env.PUBLIC_DIR }));
-
-                // SPA Fallback
-                appInstance.get('*', async (c: Context) => {
-                    try {
-                        return c.html(await readFile(path.join(process.env.PUBLIC_DIR!, 'index.html'), 'utf-8'));
-                    } catch (e) {
-                        return c.text('Not Found', 404);
-                    }
-                });
+    // Static file serving and SPA fallback (MUST be AFTER API routes)
+    if (process.env.PUBLIC_DIR) {
+        console.log(`Serving static files from ${process.env.PUBLIC_DIR}`);
+        app.use('/*', serveStatic({ root: process.env.PUBLIC_DIR }));
+
+        // SPA Fallback for client-side routing
+        // This catches any routes that weren't handled by API routes or static files
+        app.get('*', async (c: Context) => {
+            try {
+                return c.html(await readFile(path.join(process.env.PUBLIC_DIR!, 'index.html'), 'utf-8'));
+            } catch (e) {
+                return c.text('Not Found', 404);
             }
-        }
-    });
+        });
+    }
 
     console.log(`Server listening on port ${PORT}`);
     serve({