@noego/app 0.0.1

package/src/args.js

@@ -0,0 +1,180 @@
+import { exit } from 'node:process';
+
+const FLAG_MAP = new Map([
+  ['root', 'root'],
+  ['out', 'out'],
+  ['server', 'server'],
+  ['page', 'page'],
+  ['server-root', 'serverRoot'],
+  ['ui-root', 'uiRoot'],
+  ['ui-options', 'uiOptions'],
+  ['controllers', 'controllers'],
+  ['middleware', 'middleware'],
+  ['openapi', 'openapi'],
+  ['ui-openapi', 'uiOpenapi'],
+  ['sql-glob', 'sqlGlob'],
+  ['assets', 'assets'],
+  ['client-exclude', 'clientExclude'],
+  ['client-vite-config', 'clientViteConfig'],
+  ['client-vite-override', 'clientViteOverride'],
+  ['ssr-vite-config', 'ssrViteConfig'],
+  ['ssr-vite-override', 'ssrViteOverride'],
+  ['config', 'configFile'],
+  ['watch', 'watch'],
+  ['watch-path', 'watchPath'],
+  ['split-serve', 'splitServe'],
+  ['frontend-cmd', 'frontendCmd'],
+  ['mode', 'mode'],
+  ['help', 'help'],
+  ['version', 'version']
+]);
+
+const MULTI_VALUE_FLAGS = new Set(['sqlGlob', 'assets', 'clientExclude', 'watchPath']);
+const BOOLEAN_FLAGS = new Set(['watch', 'splitServe']);
+
+export function parseCliArgs(argv) {
+  const result = {
+    command: null,
+    options: Object.create(null)
+  };
+
+  const tokens = Array.from(argv);
+  while (tokens.length > 0) {
+    const token = tokens.shift();
+    if (!token) continue;
+
+    if (token.startsWith('--')) {
+      parseLongFlag(token, tokens, result.options);
+      continue;
+    }
+
+    if (!result.command) {
+      result.command = token;
+      continue;
+    }
+
+    pushOption(result.options, '_', token);
+  }
+
+  return result;
+}
+
+function parseLongFlag(token, tokens, options) {
+  const eqIndex = token.indexOf('=');
+  const rawFlag = eqIndex >= 0 ? token.slice(2, eqIndex) : token.slice(2);
+  const mapped = FLAG_MAP.get(rawFlag);
+
+  if (!mapped) {
+    throwCliError(`Unknown option --${rawFlag}`);
+  }
+
+  if (mapped === 'help') {
+    options.help = true;
+    return;
+  }
+
+  if (mapped === 'version') {
+    options.version = true;
+    return;
+  }
+
+  if (BOOLEAN_FLAGS.has(mapped)) {
+    if (eqIndex >= 0) {
+      pushOption(options, mapped, coerceBoolean(token.slice(eqIndex + 1), rawFlag));
+    } else {
+      pushOption(options, mapped, true);
+    }
+    return;
+  }
+
+  const value =
+    eqIndex >= 0
+      ? token.slice(eqIndex + 1)
+      : tokens.length > 0
+        ? tokens.shift()
+        : throwCliError(`Missing value for --${rawFlag}`);
+
+  pushOption(options, mapped, value);
+}
+
+function pushOption(storage, key, value) {
+  if (MULTI_VALUE_FLAGS.has(key)) {
+    if (!storage[key]) {
+      storage[key] = [];
+    }
+    storage[key].push(value);
+    return;
+  }
+
+  if (storage[key] !== undefined) {
+    throwCliError(`Option ${formatFlag(key)} specified multiple times`);
+  }
+
+  storage[key] = value;
+}
+
+function formatFlag(key) {
+  for (const [raw, mapped] of FLAG_MAP.entries()) {
+    if (mapped === key) {
+      return `--${raw}`;
+    }
+  }
+  return `--${key}`;
+}
+
+export function printHelpAndExit({ stdout = process.stdout } = {}) {
+  stdout.write(`Usage:
+  app build [options]
+  app serve [options]
+  app preview [options]
+
+Options (shared):
+  --root <dir>            Project root (default: .)
+  --out <dir>             Output directory root (default: dist)
+  --server <file>         Server entry (default: index.ts)
+  --server-root <dir>     Base directory for server entry (default: --root)
+  --page <file>           HTML page entry (default: ui/index.html)
+  --ui-root <dir>         Base directory for UI assets (default: dirname(--page))
+  --ui-options <file>     Forge options module (default: ui/options.ts)
+  --controllers <dir>     Controller directory (default: server/controller)
+  --middleware <dir>      Middleware directory (default: middleware)
+  --openapi <file>        Server OpenAPI entry (default: server/stitch.yaml)
+  --ui-openapi <file>     UI OpenAPI entry (default: ui/stitch.yaml)
+  --sql-glob <pattern>    Glob(s) for SQL files to copy (default: server/repo/**/*.sql)
+  --assets <pattern>      Additional asset glob(s) to copy (default: ui/resources/**)
+  --client-exclude <pattern>
+                         Exclude glob(s) from client bundle (default: server/**, middleware/**)
+  --client-vite-config <path>
+                         Alternate Vite config for client build
+  --client-vite-override <json>
+                         JSON override merged into client Vite config
+  --ssr-vite-config <path>
+                         Alternate Vite config for SSR build
+  --ssr-vite-override <json>
+                         JSON override merged into SSR Vite config
+  --watch                 Enable server restart on change (serve only)
+  --watch-path <pattern>  Additional watch glob(s) to trigger restarts (repeatable)
+  --split-serve           Run frontend dev server in a separate process (watch mode only)
+  --frontend-cmd <name>   Frontend command: currently supports 'vite' (default when split-serve)
+  --mode <value>          Build mode forwarded to Vite (default: production)
+  --help                  Show this message
+  --version               Show App version
+
+Paths are resolved relative to --root unless supplied as absolute.
+`);
+  exit(0);
+}
+
+function coerceBoolean(value, flag) {
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  throwCliError(`Invalid boolean for --${flag}: ${value}`);
+}
+
+function throwCliError(message) {
+  const error = new Error(message);
+  error.code = 'CLI_USAGE';
+  throw error;
+}

package/src/build/bootstrap.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Generates a bootstrap wrapper (hammer.js) that sets up the runtime environment
+ * before importing the compiled application entry.
+ *
+ * This ensures:
+ * - 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)
+ * - Environment-agnostic (staging, QA, production all work identically)
+ */
+export async function generateBootstrap(context) {
+  const { config, logger } = context;
+
+  // 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 template = `import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Set Forge root explicitly (highest priority in resolveRuntimeRoot)
+process.env.FORGE_ROOT = __dirname;
+
+// Signal that we're running from a built environment (for Forge auto-detection)
+process.env.FORGE_BUILT = 'true';
+
+// Import and execute the application
+await import('./${entryRel}');
+`;
+
+  const targetPath = path.join(config.outDir, 'no_ego.js');
+  await fs.writeFile(targetPath, template, 'utf8');
+
+  logger.info(`Generated bootstrap: ${path.relative(config.rootDir, targetPath)}`);
+  return targetPath;
+}

package/src/build/client-modules.js

@@ -0,0 +1,9 @@
+export async function resolveClientModulesConfig() {
+  return { config: null, components: [], missing: [] };
+}
+
+export async function buildClientModules(context) {
+  const { logger } = context;
+  logger.debug('Client module artifacts are emitted by the primary UI build; skipping duplicate build step.');
+  return { components: [] };
+}

package/src/build/client.js

@@ -0,0 +1,206 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { createUiBuildConfig } from './ui-common.js';
+import { buildWithVite } from './vite.js';
+
+export async function resolveClientEntry(context) {
+  const { config } = context;
+  const htmlTemplate = await fs.readFile(config.ui.page.absolute, 'utf8');
+  const scriptInfo = extractClientScript(htmlTemplate);
+  const entryAbsolute = resolveEntryAbsolute(config, scriptInfo);
+  return {
+    html: htmlTemplate,
+    scriptInfo,
+    entryAbsolute
+  };
+}
+
+export async function resolveClientBuildConfig(context, discovery) {
+  const { config } = context;
+  const { html, scriptInfo, entryAbsolute } = await resolveClientEntry(context);
+  const shared = await createUiBuildConfig(context, {
+    discovery,
+    entryAbsolute,
+    outDir: config.layout.clientOutDir,
+    ssr: false,
+    configFileOption: config.vite.client.configFile,
+    overrideOption: config.vite.client.override,
+    emptyOutDir: true,
+    manifest: true
+  });
+  return {
+    config: shared.config,
+    scriptInfo,
+    entryAbsolute,
+    html,
+    components: shared.components,
+    missing: shared.missing
+  };
+}
+
+export async function buildClient(context, discovery) {
+  const { config, logger } = context;
+
+  logger.info('Bundling client assets with Vite');
+
+  const {
+    config: inlineConfig,
+    scriptInfo,
+    entryAbsolute,
+    missing
+  } = await resolveClientBuildConfig(context, discovery);
+
+  if (Array.isArray(missing) && missing.length > 0) {
+    missing.forEach((component) => {
+      logger.warn(`Skipping missing UI component: ${component}`);
+    });
+  }
+
+  await buildWithVite(context, inlineConfig);
+
+  const manifestPath = await resolveManifestPath(config.layout.clientOutDir);
+  const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+
+  const scriptKey = resolveManifestKeyForScript(context, manifest, scriptInfo, entryAbsolute);
+  const entryGraph = buildClientGraph(manifest, scriptKey);
+
+  return {
+    manifestPath,
+    manifest,
+    scriptKey,
+    entryGraph,
+    scriptInfo,
+    entryAbsolute,
+    bundleRoot: config.layout.clientOutDir
+  };
+}
+
+function extractClientScript(html) {
+  const scriptRegex = /<script[^>]*type=["']module["'][^>]*src=["']([^"']+)["'][^>]*><\/script>/gi;
+  let match;
+  while ((match = scriptRegex.exec(html))) {
+    const src = match[1];
+    if (!src) continue;
+    if (src.includes('/@vite/client')) continue;
+    return {
+      raw: match[0],
+      src
+    };
+  }
+  return null;
+}
+
+function resolveManifestKeyForScript(context, manifest, scriptInfo, entryAbsolute) {
+  const keys = Object.keys(manifest);
+  if (!scriptInfo) {
+    // Fallback: attempt to find ui/client.ts
+    const fallbackCandidates = ['ui/client.ts', 'client.ts', path.relative(context.config.ui.rootDir, entryAbsolute)];
+    for (const candidate of fallbackCandidates) {
+      const key = findMatchingKey(keys, candidate);
+      if (key) return key;
+    }
+    throw new Error('Unable to locate client entry in manifest (expected ui/client.ts)');
+  }
+
+  const candidates = buildScriptCandidates(context, scriptInfo, entryAbsolute);
+  for (const candidate of candidates) {
+    const key = findMatchingKey(keys, candidate);
+    if (key) return key;
+  }
+
+  throw new Error(`Unable to resolve Vite manifest entry for script ${scriptInfo.src}`);
+}
+
+function buildClientGraph(manifest, entryKey) {
+  const visited = new Set();
+  const jsFiles = new Set();
+  const cssFiles = new Set();
+
+  function traverse(key, isRoot = false) {
+    if (!manifest[key] || visited.has(key)) return;
+    visited.add(key);
+
+    const entry = manifest[key];
+    if (entry.file) {
+      jsFiles.add(entry.file);
+    }
+    if (Array.isArray(entry.css)) {
+      entry.css.forEach((file) => cssFiles.add(file));
+    }
+    if (Array.isArray(entry.assets)) {
+      entry.assets.forEach((file) => jsFiles.add(file));
+    }
+    if (Array.isArray(entry.imports)) {
+      entry.imports.forEach((importKey) => traverse(importKey));
+    }
+  }
+
+  traverse(entryKey, true);
+
+  return {
+    entry: manifest[entryKey],
+    js: Array.from(jsFiles),
+    css: Array.from(cssFiles)
+  };
+}
+
+function findMatchingKey(keys, candidate) {
+  const normalized = toPosix(candidate);
+  const direct = keys.find((key) => toPosix(key) === normalized);
+  if (direct) return direct;
+  return keys.find((key) => toPosix(key).endsWith(`/${normalized}`) || toPosix(key).endsWith(normalized));
+}
+
+function buildScriptCandidates(context, scriptInfo, entryAbsolute) {
+  const { config } = context;
+  const src = scriptInfo.src;
+  const candidates = [];
+
+  const trimmed = src.startsWith('/') ? src.slice(1) : src;
+  candidates.push(trimmed);
+
+  const htmlDir = path.dirname(config.ui.page.absolute);
+  const resolved = src.startsWith('/')
+    ? path.resolve(config.rootDir, trimmed)
+    : path.resolve(htmlDir, src);
+
+  const relativeToUi = path.relative(config.ui.rootDir, resolved);
+  candidates.push(relativeToUi);
+  candidates.push(path.relative(config.ui.rootDir, entryAbsolute));
+
+  return candidates.filter(Boolean).map(toPosix);
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function resolveEntryAbsolute(config, scriptInfo) {
+  if (scriptInfo?.src) {
+    const src = scriptInfo.src;
+    if (src.startsWith('/')) {
+      return path.resolve(config.rootDir, src.slice(1));
+    }
+    const htmlDir = path.dirname(config.ui.page.absolute);
+    return path.resolve(htmlDir, src);
+  }
+  // Default: ui/client.ts
+  return path.resolve(config.ui.rootDir, 'client.ts');
+}
+
+async function resolveManifestPath(clientOutDir) {
+  const candidates = [
+    path.join(clientOutDir, 'manifest.json'),
+    path.join(clientOutDir, '.vite', 'manifest.json')
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {}
+  }
+
+  throw new Error(`Vite manifest not found in ${clientOutDir}`);
+}

package/src/build/context.js

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

package/src/build/fix-imports.js

@@ -0,0 +1,99 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const RELATIVE_IMPORT_RE =
+  /((?:import|export)\s[^'"`]*from\s*|import\s*)(['"])(\.{1,2}\/[^'"`]*)(\2)/g;
+
+export async function fixImportExtensions(rootDir) {
+  await recurse(rootDir);
+}
+
+async function recurse(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await recurse(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        await fixFile(fullPath);
+      }
+    })
+  );
+}
+
+async function fixFile(filePath) {
+  let source = await fs.readFile(filePath, 'utf8');
+  let changed = false;
+
+  source = await replaceAsync(
+    source,
+    RELATIVE_IMPORT_RE,
+    async (match, prefix, quote, spec) => {
+      const updated = await withJsExtension(filePath, spec);
+      if (updated === spec) {
+        return match;
+      }
+      changed = true;
+      return `${prefix}${quote}${updated}${quote}`;
+    }
+  );
+
+  // Handle dynamic import("...") separately
+  source = await replaceAsync(
+    source,
+    /(import\s*\(\s*)(['"])(\.{1,2}\/[^'"`]*)(\2)/g,
+    async (match, prefix, quote, spec) => {
+      const updated = await withJsExtension(filePath, spec);
+      if (updated === spec) {
+        return match;
+      }
+      changed = true;
+      return `${prefix}${quote}${updated}${quote}`;
+    }
+  );
+
+  if (changed) {
+    await fs.writeFile(filePath, source, 'utf8');
+  }
+}
+
+async function withJsExtension(filePath, specifier) {
+  if (!specifier.startsWith('.')) {
+    return specifier;
+  }
+  if (hasExtension(specifier)) {
+    return specifier;
+  }
+
+  const candidate = path.resolve(path.dirname(filePath), specifier);
+  const jsCandidate = `${candidate}.js`;
+  try {
+    await fs.access(jsCandidate);
+    return `${specifier}.js`;
+  } catch {}
+
+  // Support directory imports with index.js
+  const indexCandidate = path.join(candidate, 'index.js');
+  try {
+    await fs.access(indexCandidate);
+    return `${specifier}/index.js`;
+  } catch {}
+
+  return specifier;
+}
+
+function hasExtension(specifier) {
+  return /\.[\w-]+($|\?)/.test(specifier);
+}
+
+async function replaceAsync(str, regex, asyncFn) {
+  const matches = [];
+  str.replace(regex, (...args) => {
+    matches.push(asyncFn(...args));
+    return args[0];
+  });
+  const replacements = await Promise.all(matches);
+  let i = 0;
+  return str.replace(regex, () => replacements[i++]);
+}

package/src/build/helpers.js

@@ -0,0 +1,29 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function resolveConfigFile(preferred, fallback) {
+  if (preferred) {
+    const absolutePreferred = path.resolve(preferred);
+    if (await fileExists(absolutePreferred)) {
+      return absolutePreferred;
+    }
+  }
+
+  if (fallback) {
+    const absoluteFallback = path.resolve(fallback);
+    if (await fileExists(absoluteFallback)) {
+      return absoluteFallback;
+    }
+  }
+
+  return undefined;
+}
+
+export async function fileExists(target) {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/build/html.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function rewriteHtmlTemplate(context, clientArtifacts) {
+  const { config, logger } = context;
+  const templatePath = config.ui.page.absolute;
+  const targetPath = path.join(
+    config.outDir,
+    path.relative(config.rootDir, templatePath)
+  );
+
+  let html = await fs.readFile(templatePath, 'utf8');
+
+  // Strip development-only scripts
+  html = html.replace(/\s*<script[^>]*src="\/@vite\/client"[^>]*><\/script>\s*/gi, '');
+  html = html.replace(/\s*<script[^>]*>[^<]*import\(['\"]\/@vite\/client['\"]\)[\s\S]*?<\/script>\s*/gi, '');
+  if (clientArtifacts.scriptInfo?.raw) {
+    const escaped = escapeRegExp(clientArtifacts.scriptInfo.raw);
+    const pattern = new RegExp(`\\s*${escaped}\\s*`, 'g');
+    html = html.replace(pattern, '');
+  }
+  // Client bundle public base served at '/assets'
+  const clientBase = '/assets';
+  html = html.replace(/(href|src)=(['"])\/assets\//g, `$1=$2${clientBase}/`);
+  // Remove inline dev loader blocks ( import('<whatever>/client.ts') ) and related comments
+  html = html.replace(/\s*<!--[^>]*Development[^>]*-->\s*/gi, '');
+  html = html.replace(/\s*<script[^>]*>[^<]*import\(['\"][^'\"]*client\.ts['\"][^)]*\)[\s\S]*?<\/script>\s*/gi, '');
+
+  const entryFile = clientArtifacts.entryGraph.entry?.file;
+  if (!entryFile) {
+    throw new Error('Client build completed without an entry file in manifest.');
+  }
+
+  const preloadFiles = new Set(
+    clientArtifacts.entryGraph.js.filter((file) => file !== entryFile)
+  );
+  const cssFiles = new Set(clientArtifacts.entryGraph.css);
+
+  const makeClientPublicPath = (file) => `${clientBase}/${toPosix(file)}`;
+  const headInjections = [];
+  for (const file of preloadFiles) {
+    headInjections.push(
+      `<link rel="modulepreload" href="${makeClientPublicPath(file)}">`
+    );
+  }
+  for (const file of cssFiles) {
+    headInjections.push(
+      `<link rel="stylesheet" href="${makeClientPublicPath(file)}">`
+    );
+  }
+
+  if (headInjections.length > 0) {
+    html = injectBeforeClose(html, '</head>', headInjections.join('\n  '));
+  }
+
+  const scriptTag = `<script type="module" src="${makeClientPublicPath(entryFile)}"></script>`;
+  html = injectBeforeClose(html, '</body>', scriptTag);
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.writeFile(targetPath, html, 'utf8');
+
+  logger.info(`Wrote production HTML template to ${path.relative(config.rootDir, targetPath)}`);
+}
+
+// clientPublicPath no longer needed; use makeClientPublicPath closure above
+
+function injectBeforeClose(html, marker, injection) {
+  const index = html.lastIndexOf(marker);
+  if (index === -1) {
+    return `${html}\n${injection}\n`;
+  }
+  const before = html.slice(0, index);
+  const after = html.slice(index);
+  return `${before}  ${injection}\n${after}`;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}