@noego/app 0.0.3 → 0.0.4

package/.claude/settings.local.json

@@ -1,17 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "Read(//Users/shavauhngabay/dev/noego/dinner/**)",
-      "Read(//Users/shavauhngabay/dev/ego/sqlstack/**)",
-      "Read(//Users/shavauhngabay/dev/ego/forge/**)",
-      "Read(//Users/shavauhngabay/dev/noblelaw/ui/**)",
-      "Read(//Users/shavauhngabay/dev/noblelaw/**)",
-      "mcp__chrome-devtools__take_screenshot",
-      "Bash(npm run build:ui:ssr:*)",
-      "mcp__chrome-devtools__navigate_page",
-      "Bash(node dist/hammer.js:*)",
-      "Bash(tee:*)",
-      "mcp__chrome-devtools__list_console_messages"
+      "Bash(cat:*)",
+      "Bash(curl:*)",
+      "Bash(noego dev)"
     ],
     "deny": [],
     "ask": []

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@noego/app",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Production build tool for Dinner/Forge apps.",
   "type": "module",
   "bin": {
     "app": "./bin/app.js",
     "noego": "./bin/app.js"
   },
+  "exports": {
+    ".": {
+      "import": "./src/index.js"
+    },
+    "./client": {
+      "import": "./src/client.js",
+      "types": "./types/client.d.ts"
+    }
+  },
   "scripts": {
     "build": "node ./bin/app.js build"
   },
@@ -20,5 +29,10 @@
     "picomatch": "^2.3.1",
     "yaml": "^2.6.0"
   },
+  "peerDependencies": {
+    "@noego/dinner": "*",
+    "@noego/forge": "*",
+    "express": "*"
+  },
   "devDependencies": {}
 }

package/src/args.js

@@ -125,6 +125,7 @@ function formatFlag(key) {
 export function printHelpAndExit({ stdout = process.stdout } = {}) {
   stdout.write(`Usage:
   app build [options]
+  app dev [options]
   app serve [options]
   app preview [options]
 

package/src/build/bootstrap.js

@@ -2,29 +2,123 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 /**
- * Generates a bootstrap wrapper (hammer.js) that sets up the runtime environment
+ * Generates a bootstrap wrapper (no_ego.js) that sets up the runtime environment
  * before importing the compiled application entry.
  *
  * This ensures:
+ * - NOEGO_CONFIGURATION is set with full resolved config
  * - FORGE_ROOT is set to the dist directory (for consistent asset resolution)
- * - Application works regardless of invocation directory (node dist/hammer.js vs cd dist && node hammer.js)
+ * - Application works regardless of invocation directory (node dist/no_ego.js vs cd dist && node no_ego.js)
  * - Environment-agnostic (staging, QA, production all work identically)
  */
 export async function generateBootstrap(context) {
   const { config, logger } = context;
 
+  // Build the config object that will be serialized to NOEGO_CONFIGURATION
+  // Paths are relative to project root, mirrored in dist (so dist/server/server.js mirrors src/server/server.ts)
+  const runtimeConfig = {
+    root: '__dirname', // Will be replaced in template with actual __dirname (dist directory)
+    mode: 'production',
+    outDir: config.outDir ? path.basename(config.outDir) : 'dist',
+    outDir_abs: '__dirname', // Will be replaced
+    app: {
+      boot: config.app?.boot,
+      boot_abs: config.app?.boot ? './' + path.relative(config.rootDir, config.app.boot_abs).replace(/\.ts$/, '.js') : null
+    },
+    server: config.server ? {
+      main: config.server.entry?.raw,
+      main_abs: config.server.entry?.absolute ? './' + path.relative(config.rootDir, config.server.entry.absolute).replace(/\.ts$/, '.js') : null,
+      controllers: config.server?.controllers,
+      controllers_abs: config.server?.controllersDir ? './' + path.relative(config.rootDir, config.server.controllersDir) : null,
+      controllers_base_path: config.server?.controllersDir ? './' + path.relative(config.rootDir, config.server.controllersDir) : null,
+      middleware: config.server?.middleware,
+      middleware_abs: config.server?.middlewareDir ? './' + path.relative(config.rootDir, config.server.middlewareDir) : null,
+      middleware_path: config.server?.middlewareDir ? './' + path.relative(config.rootDir, config.server.middlewareDir) : null,
+      openapi: config.server?.openapi,
+      openapi_abs: config.server?.openapiFile ? './' + path.relative(config.rootDir, config.server.openapiFile) : null,
+      openapi_path: config.server?.openapiFile ? './' + path.relative(config.rootDir, config.server.openapiFile) : null
+    } : undefined,
+    client: config.ui ? {
+      main: config.client?.main,
+      main_abs: config.client?.main_abs ? './' + path.relative(config.rootDir, config.client.main_abs).replace(/\.ts$/, '.js') : null,
+      shell: config.client?.shell,
+      shell_abs: config.client?.shell_abs ? './' + path.relative(config.rootDir, config.client.shell_abs) : null,
+      shell_path: config.client?.shell,
+      openapi: config.client?.openapi,
+      openapi_abs: config.client?.openapi_abs ? './' + path.relative(config.rootDir, config.client.openapi_abs) : null,
+      openapi_path: config.client?.openapi,
+      component_dir: config.client?.component_dir,
+      componentDir_abs: config.client?.componentDir_abs ? './' + path.relative(config.rootDir, config.client.componentDir_abs) : null,
+      assetDirs: config.client?.assetDirs || []
+    } : undefined,
+    dev: {
+      port: config.dev?.port || 3000,
+      backendPort: config.dev?.backendPort || 3001
+    },
+    assets: []
+  };
+
   // Compute relative path from outDir to compiled entry
   // The entry is copied to outDir root by syncRootEntry in server.js
-  const entryRel = path.relative(
-    config.rootDir,
-    config.server.entry.absolute
-  ).replace(/\.ts$/, '.js');
+  const entryRel = config.server?.entry?.absolute
+    ? path.relative(config.rootDir, config.server.entry.absolute).replace(/\.ts$/, '.js')
+    : 'server/index.js';
+
+  // Serialize config, then replace __dirname placeholders
+  let configJson = JSON.stringify(runtimeConfig, null, 2);
+  configJson = configJson.replace(/"__dirname"/g, '__dirname');
 
   const template = `import path from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+// Set full configuration in environment
+const runtimeConfig = ${configJson};
+
+// Resolve all relative paths to absolute based on __dirname
+if (runtimeConfig.app?.boot_abs) {
+  runtimeConfig.app.boot_abs = path.resolve(__dirname, runtimeConfig.app.boot_abs);
+}
+if (runtimeConfig.server) {
+  if (runtimeConfig.server.main_abs) {
+    runtimeConfig.server.main_abs = path.resolve(__dirname, runtimeConfig.server.main_abs);
+  }
+  if (runtimeConfig.server.controllers_abs) {
+    runtimeConfig.server.controllers_abs = path.resolve(__dirname, runtimeConfig.server.controllers_abs);
+    runtimeConfig.server.controllers_base_path = runtimeConfig.server.controllers_abs;
+  }
+  if (runtimeConfig.server.middleware_abs) {
+    runtimeConfig.server.middleware_abs = path.resolve(__dirname, runtimeConfig.server.middleware_abs);
+    runtimeConfig.server.middleware_path = runtimeConfig.server.middleware_abs;
+  }
+  if (runtimeConfig.server.openapi_abs) {
+    runtimeConfig.server.openapi_abs = path.resolve(__dirname, runtimeConfig.server.openapi_abs);
+    runtimeConfig.server.openapi_path = runtimeConfig.server.openapi_abs;
+  }
+}
+if (runtimeConfig.client) {
+  if (runtimeConfig.client.main_abs) {
+    runtimeConfig.client.main_abs = path.resolve(__dirname, runtimeConfig.client.main_abs);
+  }
+  if (runtimeConfig.client.shell_abs) {
+    runtimeConfig.client.shell_abs = path.resolve(__dirname, runtimeConfig.client.shell_abs);
+  }
+  if (runtimeConfig.client.openapi_abs) {
+    runtimeConfig.client.openapi_abs = path.resolve(__dirname, runtimeConfig.client.openapi_abs);
+  }
+  if (runtimeConfig.client.componentDir_abs) {
+    runtimeConfig.client.componentDir_abs = path.resolve(__dirname, runtimeConfig.client.componentDir_abs);
+  }
+  // Resolve assetDirs paths
+  if (runtimeConfig.client.assetDirs) {
+    runtimeConfig.client.assetDirs = runtimeConfig.client.assetDirs.map(assetDir => ({
+      ...assetDir,
+      absolutePath: path.resolve(__dirname, assetDir.absolutePath)
+    }));
+  }
+}
+
 // Set Forge root explicitly (highest priority in resolveRuntimeRoot)
 process.env.FORGE_ROOT = __dirname;
 
@@ -35,8 +129,20 @@ process.env.NOEGO_BUILT = 'true';
 // Indicate Dinner is running in the built environment
 process.env.DINNER_SERVED = 'true';
 
-// Import and execute the application
-await import('./${entryRel}');
+// Force production mode in config (not via NODE_ENV)
+runtimeConfig.mode = 'production';
+
+// Store config in env for @noego/app/client.js to read
+process.env.NOEGO_CONFIGURATION = JSON.stringify(runtimeConfig);
+
+// Import and run the runtime directly
+import { runCombinedServices } from '@noego/app';
+
+// Determine what services to run
+const hasBackend = !!runtimeConfig.server?.main_abs;
+const hasFrontend = !!runtimeConfig.client?.main_abs;
+
+await runCombinedServices(runtimeConfig, { hasBackend, hasFrontend });
 `;
 
   const targetPath = path.join(config.outDir, 'no_ego.js');

package/src/build/context.js

@@ -3,8 +3,8 @@ import { createRequire } from 'node:module';
 
 import { createLogger } from '../logger.js';
 
-export function createBuildContext(config, options = {}) {
-  const logger = options.logger ?? createLogger(options);
+export function createBuildContext(config) {
+  const logger = createLogger();
   const requireFromRoot = createRequire(path.join(config.rootDir, 'package.json'));
 
   return {

package/src/build/helpers.js

@@ -1,6 +1,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+export function resolvePath(input, baseDir) {
+  if (input == null || input === '') {
+    return path.resolve(baseDir);
+  }
+  if (path.isAbsolute(input)) {
+    return path.normalize(input);
+  }
+  return path.resolve(baseDir, input);
+}
+
 export async function resolveConfigFile(preferred, fallback) {
   if (preferred) {
     const absolutePreferred = path.resolve(preferred);

package/src/build/openapi.js

@@ -16,9 +16,11 @@ const HTTP_METHODS = new Set([
 ]);
 
 export async function discoverProject(context) {
+  const serverOpenApiPath = context.config.server?.openapiFile;
+  const uiOpenApiPath = context.config.ui?.openapiFile;
   const [serverDoc, uiDoc] = await Promise.all([
-    loadOpenApiDocumentIfPresent(context, context.config.server.openapiFile),
-    loadOpenApiDocumentIfPresent(context, context.config.ui.openapiFile)
+    loadOpenApiDocumentIfPresent(context, serverOpenApiPath),
+    loadOpenApiDocumentIfPresent(context, uiOpenApiPath)
   ]);
 
   const serverRoutes = collectRoutes(serverDoc);
@@ -114,6 +116,9 @@ async function loadOpenApiDocumentIfPresent(context, filePath) {
 }
 
 function collectRoutes(document) {
+  if (!document) {
+    return [];
+  }
   const routes = [];
   const inheritedMiddleware = ensureArray(document?.paths?.['x-middleware']);
 
@@ -123,7 +128,7 @@ function collectRoutes(document) {
   return routes;
 }
 
-function parseModules(document, inheritedMiddleware = []) {
+function parseModules(document = {}, inheritedMiddleware = []) {
   const modulesConfig = document.modules || document.module;
   if (!modulesConfig) return [];
 
@@ -151,7 +156,7 @@ function parseModules(document, inheritedMiddleware = []) {
   return routes;
 }
 
-function parsePaths(document, inheritedMiddleware = []) {
+function parsePaths(document = {}, inheritedMiddleware = []) {
   const paths = document.paths;
   if (!paths || typeof paths !== 'object') {
     return [];

package/src/build/runtime-manifest.js

@@ -10,41 +10,31 @@ export async function writeRuntimeManifest(context, artifacts) {
     mode: config.mode,
     rootDir: config.rootDir,
     outDir: config.outDir,
-    server: {
-      entry: config.server.entry.relativeToRoot,
-      controllersDir: path.relative(config.rootDir, config.server.controllersDir),
-      middlewareDir: path.relative(config.rootDir, config.server.middlewareDir),
-      openapi: path.relative(config.rootDir, config.server.openapiFile),
-      sqlGlobs: config.server.sqlGlobs.map((spec) => spec.pattern)
-    },
-    ui: {
-      page: config.ui.page.relativeToRoot,
-      openapi: path.relative(config.rootDir, config.ui.openapiFile),
-      assets: config.assets.map((spec) => spec.pattern),
-      clientExclude: config.ui.clientExclude.map((spec) => spec.pattern)
-    },
-    discovery: {
-      server: {
-        controllers: artifacts.discovery.server.controllers,
-        middleware: artifacts.discovery.server.middleware
-      },
-      ui: {
-        views: artifacts.discovery.ui.views,
-        layouts: artifacts.discovery.ui.layouts,
-        middleware: artifacts.discovery.ui.middleware
-      }
-    },
-    client: {
-      manifest: relativeToOut(config, artifacts.client.manifestPath),
-      entry: artifacts.client.entryGraph.entry?.file
+    server: config.server ? {
+      entry: config.server.entry?.relativeToRoot ?? null,
+      controllersDir: config.server.controllersDir ? path.relative(config.rootDir, config.server.controllersDir) : null,
+      middlewareDir: config.server.middlewareDir ? path.relative(config.rootDir, config.server.middlewareDir) : null,
+      openapi: config.server.openapiFile ? path.relative(config.rootDir, config.server.openapiFile) : null,
+      sqlGlobs: Array.isArray(config.server.sqlGlobs) ? config.server.sqlGlobs.map((spec) => spec.pattern) : []
+    } : null,
+    ui: config.ui ? {
+      page: config.ui.page?.relativeToRoot ?? null,
+      openapi: config.ui.openapiFile ? path.relative(config.rootDir, config.ui.openapiFile) : null,
+      assets: Array.isArray(config.assets) ? config.assets.map((spec) => spec.pattern) : [],
+      clientExclude: Array.isArray(config.ui.clientExclude) ? config.ui.clientExclude.map((spec) => spec.pattern) : []
+    } : null,
+    discovery: artifacts.discovery ?? null,
+    client: artifacts.client ? {
+      manifest: artifacts.client.manifestPath ? relativeToOut(config, artifacts.client.manifestPath) : null,
+      entry: artifacts.client.entryGraph?.entry?.file
         ? `/assets/${toPosix(artifacts.client.entryGraph.entry.file)}`
         : null
-    },
-    ssr: {
+    } : null,
+    ssr: artifacts.ssr ? {
       manifest: artifacts.ssr.manifestPath
         ? relativeToOut(config, artifacts.ssr.manifestPath)
         : null
-    }
+    } : null
   };
 
   await fs.writeFile(targetPath, JSON.stringify(payload, null, 2));
@@ -52,10 +42,12 @@ export async function writeRuntimeManifest(context, artifacts) {
 }
 
 function relativeToRoot(config, absolutePath) {
+  if (!absolutePath) return null;
   return path.relative(config.rootDir, absolutePath);
 }
 
 function relativeToOut(config, absolutePath) {
+  if (!absolutePath) return null;
   return path.relative(config.outDir, absolutePath);
 }
 

package/src/build/server.js

@@ -13,6 +13,7 @@ export async function buildServer(context, discovery) {
   await reorganizeServerOutputs(context);
   await mirrorUiModules(context);
   await syncRootEntry(context);
+  await syncAppBoot(context);
   await copyServerAssets(context);
   await fixImportExtensions(context.config.outDir);
 }
@@ -70,7 +71,7 @@ async function reorganizeServerOutputs(context) {
   }
 
   const compiledEntryRel = replaceExtension(
-    path.relative(config.rootDir, config.server.entry.absolute),
+    path.relative(config.server.rootDir, config.server.entry.absolute),
     '.js'
   );
   const compiledEntryPath = path.join(serverOutDir, compiledEntryRel);
@@ -172,15 +173,44 @@ async function mirrorUiModules(context) {
 
 async function syncRootEntry(context) {
   const { config } = context;
-  const compiledEntryRel = replaceExtension(
+  const compiledEntryRelFromServerRoot = replaceExtension(
+    path.relative(config.server.rootDir, config.server.entry.absolute),
+    '.js'
+  );
+  const compiledEntryRelFromProjectRoot = replaceExtension(
     path.relative(config.rootDir, config.server.entry.absolute),
     '.js'
   );
-  const sourcePath = path.join(config.layout.serverOutDir, compiledEntryRel);
+  const sourcePath = path.join(config.layout.serverOutDir, compiledEntryRelFromServerRoot);
   if (!(await pathExists(sourcePath))) {
     return;
   }
-  const destinationPath = path.join(config.outDir, compiledEntryRel);
+  const destinationPath = path.join(config.outDir, compiledEntryRelFromProjectRoot);
+  await ensureParentDir(destinationPath);
+  await fs.copyFile(sourcePath, destinationPath);
+  await copyIfExists(`${sourcePath}.map`, `${destinationPath}.map`);
+}
+
+async function syncAppBoot(context) {
+  const { config } = context;
+
+  // Copy app.boot (e.g., index.ts -> dist/index.js) to maintain project structure
+  if (!config.app?.boot_abs) {
+    return;
+  }
+
+  const compiledBootRelFromProjectRoot = replaceExtension(
+    path.relative(config.rootDir, config.app.boot_abs),
+    '.js'
+  );
+
+  // The compiled boot file should be in the tsOutDir, mirroring project structure
+  const sourcePath = path.join(config.layout.tsOutDir, compiledBootRelFromProjectRoot);
+  if (!(await pathExists(sourcePath))) {
+    return;
+  }
+
+  const destinationPath = path.join(config.outDir, compiledBootRelFromProjectRoot);
   await ensureParentDir(destinationPath);
   await fs.copyFile(sourcePath, destinationPath);
   await copyIfExists(`${sourcePath}.map`, `${destinationPath}.map`);

package/src/cli.js

@@ -7,10 +7,11 @@ import { loadBuildConfig } from './config.js';
 import { runBuild } from './commands/build.js';
 import { runServe } from './commands/serve.js';
 import { runPreview } from './commands/preview.js';
+import { runDev } from './commands/dev.js';
 
-async function main() {
+export async function runCli(argv = process.argv.slice(2)) {
   try {
-    const { command, options } = parseCliArgs(process.argv.slice(2));
+    const { command, options } = parseCliArgs(argv);
 
     if (options.help || !command) {
       printHelpAndExit();
@@ -24,8 +25,7 @@ async function main() {
 
     switch (command) {
       case 'build': {
-        const config = await loadBuildConfig(options, { cwd: process.cwd() });
-        await runBuild(config);
+        await runBuild(options);
         break;
       }
       case 'serve': {
@@ -33,6 +33,11 @@ async function main() {
         await runServe(config);
         break;
       }
+      case 'dev': {
+        const config = await loadBuildConfig(options, { cwd: process.cwd() });
+        await runDev(config);
+        break;
+      }
       case 'preview': {
         const config = await loadBuildConfig(options, { cwd: process.cwd() });
         await runPreview(config);
@@ -69,4 +74,4 @@ function cliError(message) {
   return error;
 }
 
-await main();
+await runCli();

package/src/client.js

@@ -0,0 +1,141 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+// Runtime context - set by the runtime before calling server.main
+let runtimeContext = null;
+
+/**
+ * Sets the runtime context (called by the runtime before server.main).
+ * 
+ * @param {import('express').Express} app - Express application instance
+ * @param {object} config - Configuration object with resolved paths
+ * @param {import('http').Server} [httpServer] - HTTP server instance for WebSocket upgrades
+ */
+export function setContext(app, config, httpServer = null) {
+  runtimeContext = { app, config, httpServer };
+}
+
+/**
+ * Boots the backend server with Dinner (API) integration.
+ * 
+ * @param {object} assets - Dinner asset mappings
+ * @param {object} [options] - Optional configuration
+ * @param {function} [options.controller_builder] - Controller builder function
+ * @param {function} [options.controller_args_provider] - Controller args provider function
+ * @returns {Promise<object>} Dinner server instance
+ */
+export async function boot(assets, options = {}) {
+  if (!runtimeContext) {
+    throw new Error('Runtime context not set. Call setContext() before boot().');
+  }
+
+  const { app, config } = runtimeContext;
+
+  // Resolve dependencies from user's project context
+  const root = config.root || process.cwd();
+  const require = createRequire(path.join(root, 'package.json'));
+  const { Server } = require('@noego/dinner');
+
+  // Setup Dinner (API server) only
+  const server = await Server.createServer({
+    openapi_path: config.server.openapi_path,
+    controllers_base_path: config.server.controllers_base_path,
+    middleware_path: config.server.middleware_path,
+    server: app,
+    ajv_formats: true,
+    assets: assets,
+    controller_builder: options.controller_builder || (async (Controller) => {
+      // Default: try to instantiate with new
+      return new Controller();
+    }),
+    controller_args_provider: options.controller_args_provider || (async (req, res) => ({ req, res })),
+  });
+
+  return server;
+}
+
+/**
+ * Boots the frontend server with Forge (SSR) integration.
+ * 
+ * @returns {Promise<void>}
+ */
+export async function clientBoot() {
+  if (!runtimeContext) {
+    throw new Error('Runtime context not set. Call setContext() before client.boot().');
+  }
+
+  const { app, config } = runtimeContext;
+
+  // Resolve dependencies from user's project context
+  const root = config.root || process.cwd();
+  const require = createRequire(path.join(root, 'package.json'));
+  const { createServer: createForgeServer } = require('@noego/forge/server');
+
+  // Setup Forge (SSR)
+  // Forge expects paths relative to viteOptions.root
+  const forgeOptions = {
+    viteOptions: {
+      root: root,
+      // Configure Vite server: use Express app (middleware mode) in development
+      server: config.mode !== 'production'
+        ? {
+            middlewareMode: true, // Use Vite as middleware in Express, don't create separate server
+            hmr: {
+              clientPort: config.dev?.port || 3000,
+              // Pass HTTP server to Vite for WebSocket upgrades
+              server: runtimeContext.httpServer
+            }
+          }
+        : undefined
+    },
+    component_dir: config.client?.component_dir,
+    open_api_path: config.client?.openapi_path,
+    renderer: config.client?.shell_path,
+    middleware_path: config.server?.middleware_path,
+    development: config.mode !== 'production',
+  };
+  
+  await createForgeServer(app, forgeOptions);
+}
+
+/**
+ * Browser-side client initialization.
+ * Reads window.__CONFIGURATION__ and initializes the Forge app.
+ * This function works in the browser and should be called from client.ts.
+ * 
+ * @returns {Promise<void>}
+ */
+export async function clientInit() {
+  // Check if we're in a browser environment
+  if (typeof window === 'undefined') {
+    throw new Error('client.init() can only be called in the browser');
+  }
+
+  // Get configuration from window (injected by Forge HTML renderer)
+  const options = window.__CONFIGURATION__;
+  if (!options) {
+    console.warn('window.__CONFIGURATION__ not found. Forge app may not initialize correctly.');
+    return;
+  }
+
+  // Find root element
+  const root = document.getElementById('app');
+  if (!root) {
+    console.warn('Root element with id="app" not found.');
+    return;
+  }
+
+  // Dynamically import createApp from @noego/forge/client
+  // This will work because Vite bundles it properly
+  const { createApp } = await import('@noego/forge/client');
+  
+  // Initialize the app
+  await createApp(root, options);
+}
+
+// Export client.boot as a named export (server-side)
+export const client = {
+  boot: clientBoot,
+  init: clientInit  // Browser-side initialization
+};
+