aegisnode 0.0.4 → 0.1.0

package/src/cli/utils/apps.js

@@ -0,0 +1,260 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { ensureDir, ensureValidName, exists, normalizeMountPath, writeFile } from './fs.js';
+import { importProjectModule } from '../../runtime/typescript.js';
+import {
+  detectProjectSourceExtension,
+  resolveSourceFile,
+} from '../../utils/source-files.js';
+import {
+  renderAppModelTest,
+  renderAppModelsFile,
+  renderAppRoutes,
+  renderAppRoutesTest,
+  renderAppServiceTest,
+  renderAppServicesFile,
+  renderAppSubscribersFile,
+  renderAppUtilsFile,
+  renderAppValidatorTest,
+  renderAppValidatorsFile,
+  renderAppViewsFile,
+  renderSettingsApps,
+  withSourceExtension,
+} from './scaffolds.js';
+
+export const APPS_START = '// AEGIS_APPS_START';
+export const APPS_END = '// AEGIS_APPS_END';
+
+function renderAppEntries(apps) {
+  return apps
+    .map((app) => `    { name: ${JSON.stringify(app.name)}, mount: ${JSON.stringify(app.mount)} },`)
+    .join('\n');
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function toImportName(appName) {
+  const safe = appName
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+
+  if (!safe) {
+    return 'appRoutes';
+  }
+
+  return `${safe.charAt(0).toLowerCase()}${safe.slice(1)}`;
+}
+
+async function readDefaultExport(filePath) {
+  const loaded = await importProjectModule(filePath);
+  return loaded?.default;
+}
+
+export async function detectSettingsMode(projectRoot) {
+  const single = resolveSourceFile(path.join(projectRoot, 'settings'));
+  const split = resolveSourceFile(path.join(projectRoot, 'settings', 'apps'));
+
+  if (single && await exists(single)) {
+    return { mode: 'single', file: single };
+  }
+
+  if (split && await exists(split)) {
+    return { mode: 'split', file: split };
+  }
+
+  throw new Error(`Not an AegisNode project root: missing settings.js/settings.ts (or legacy settings/apps.js/settings/apps.ts)`);
+}
+
+export async function readAppsConfig(settingsMode) {
+  const normalizeApp = (entry) => {
+    if (!entry || typeof entry !== 'object' || typeof entry.name !== 'string') {
+      return null;
+    }
+
+    ensureValidName(entry.name, 'app');
+    return {
+      name: entry.name,
+      mount: normalizeMountPath(entry.mount || `/${entry.name}`),
+    };
+  };
+
+  if (settingsMode.mode === 'single') {
+    const settings = await readDefaultExport(settingsMode.file);
+    const apps = settings?.apps;
+
+    if (!Array.isArray(apps)) {
+      throw new Error(`settings.js must export { apps: [] }. File: ${settingsMode.file}`);
+    }
+
+    return apps.map(normalizeApp).filter(Boolean);
+  }
+
+  const apps = await readDefaultExport(settingsMode.file);
+  if (!Array.isArray(apps)) {
+    throw new Error(`settings/apps.js must export an array. File: ${settingsMode.file}`);
+  }
+
+  return apps.map(normalizeApp).filter(Boolean);
+}
+
+async function updateSingleSettingsApps(settingsFile, apps) {
+  const current = await fs.readFile(settingsFile, 'utf8');
+
+  if (!current.includes(APPS_START) || !current.includes(APPS_END)) {
+    throw new Error(`settings.js is missing ${APPS_START}/${APPS_END} markers: ${settingsFile}`);
+  }
+
+  const replacement = `${APPS_START}\n${renderAppEntries(apps)}\n    ${APPS_END}`;
+  const updated = current.replace(/\/\/ AEGIS_APPS_START[\s\S]*?\/\/ AEGIS_APPS_END/m, replacement);
+
+  await writeFile(settingsFile, updated);
+}
+
+export async function updateAppRegistry(projectRoot, apps, settingsMode) {
+  const sourceExtension = detectProjectSourceExtension(projectRoot);
+
+  if (settingsMode.mode === 'single') {
+    await updateSingleSettingsApps(settingsMode.file, apps);
+    return;
+  }
+
+  await writeFile(path.join(projectRoot, 'settings', withSourceExtension('apps', sourceExtension)), renderSettingsApps(apps));
+}
+
+export function getAppScaffoldEntries(appName, sourceExtension = '.js') {
+  const appRoot = path.join('apps', appName);
+  return [
+    {
+      target: path.join(appRoot, withSourceExtension('views', sourceExtension)),
+      content: renderAppViewsFile(appName, sourceExtension),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('models', sourceExtension)),
+      content: renderAppModelsFile(appName),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('validators', sourceExtension)),
+      content: renderAppValidatorsFile(appName),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('services', sourceExtension)),
+      content: renderAppServicesFile(appName),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('utils', sourceExtension)),
+      content: renderAppUtilsFile(),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('subscribers', sourceExtension)),
+      content: renderAppSubscribersFile(appName),
+    },
+    {
+      target: path.join(appRoot, withSourceExtension('routes', sourceExtension)),
+      content: renderAppRoutes(appName, sourceExtension),
+    },
+    {
+      target: path.join(appRoot, 'tests', withSourceExtension('models.test', sourceExtension)),
+      content: renderAppModelTest(appName, sourceExtension),
+    },
+    {
+      target: path.join(appRoot, 'tests', withSourceExtension('validators.test', sourceExtension)),
+      content: renderAppValidatorTest(appName, sourceExtension),
+    },
+    {
+      target: path.join(appRoot, 'tests', withSourceExtension('services.test', sourceExtension)),
+      content: renderAppServiceTest(appName, sourceExtension),
+    },
+    {
+      target: path.join(appRoot, 'tests', withSourceExtension('routes.test', sourceExtension)),
+      content: renderAppRoutesTest(appName, sourceExtension),
+    },
+  ];
+}
+
+export async function ensureAppScaffold(projectRoot, appName, { overwrite = false, sourceExtension = '.js' } = {}) {
+  ensureValidName(appName, 'app');
+
+  const appRoot = path.join(projectRoot, 'apps', appName);
+  await ensureDir(appRoot);
+  await ensureDir(path.join(appRoot, 'tests'));
+
+  const written = [];
+  const skipped = [];
+
+  for (const entry of getAppScaffoldEntries(appName, sourceExtension)) {
+    const target = path.join(projectRoot, entry.target);
+    if (!overwrite && await exists(target)) {
+      skipped.push(target);
+      continue;
+    }
+
+    await writeFile(target, entry.content);
+    written.push(target);
+  }
+
+  return {
+    appRoot,
+    written,
+    skipped,
+  };
+}
+
+export async function updateProjectRoutesFile(projectRoot, appName, mountPath, sourceExtension = null) {
+  const effectiveExtension = sourceExtension || detectProjectSourceExtension(projectRoot);
+  const routesFile = resolveSourceFile(path.join(projectRoot, 'routes'), [effectiveExtension]) || resolveSourceFile(path.join(projectRoot, 'routes'));
+  if (!routesFile || !(await exists(routesFile))) {
+    // Keep backward compatibility for legacy projects that still use routes/index.js.
+    return {
+      routesFile: routesFile || path.join(projectRoot, withSourceExtension('routes', effectiveExtension)),
+      updatedImport: false,
+      updatedRoute: false,
+      skipped: true,
+    };
+  }
+
+  const importName = toImportName(appName);
+  const importLine = `import ${importName} from './apps/${appName}/routes${effectiveExtension}';`;
+  const routeLine = `    route.use(${JSON.stringify(mountPath)}, ${importName});`;
+  const routePattern = new RegExp(`route\\.use\\([^\\n]*,\\s*${escapeRegExp(importName)}\\s*\\);`);
+
+  let content = await fs.readFile(routesFile, 'utf8');
+  let updatedImport = false;
+  let updatedRoute = false;
+
+  if (!content.includes(importLine)) {
+    if (content.includes('// AEGIS_APP_IMPORTS_START') && content.includes('// AEGIS_APP_IMPORTS_END')) {
+      content = content.replace('// AEGIS_APP_IMPORTS_END', `${importLine}\n// AEGIS_APP_IMPORTS_END`);
+    } else {
+      content = `${importLine}\n${content}`;
+    }
+    updatedImport = true;
+  }
+
+  if (!routePattern.test(content)) {
+    if (content.includes('// AEGIS_PROJECT_APP_ROUTES_START') && content.includes('// AEGIS_PROJECT_APP_ROUTES_END')) {
+      content = content.replace('    // AEGIS_PROJECT_APP_ROUTES_END', `${routeLine}\n    // AEGIS_PROJECT_APP_ROUTES_END`);
+      updatedRoute = true;
+    } else {
+      const match = content.match(/register\s*\([^)]*\)\s*{[\s\S]*?\n\s*}/m);
+      if (match) {
+        content = content.replace(match[0], `${match[0]}\n${routeLine}`);
+        updatedRoute = true;
+      }
+    }
+  }
+
+  if (updatedImport || updatedRoute) {
+    await writeFile(routesFile, content);
+  }
+
+  return {
+    routesFile,
+    updatedImport,
+    updatedRoute,
+    skipped: false,
+  };
+}

package/src/cli/utils/project.js

@@ -1,16 +1,20 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { exists } from './fs.js';
+import { detectProjectSourceExtension, resolveSourceFile, resolveSourceIndexFile } from '../../utils/source-files.js';
 
 export async function hasRoutesFile(projectRoot) {
-  return (await exists(path.join(projectRoot, 'routes.js')))
-    || (await exists(path.join(projectRoot, 'routes', 'index.js')));
+  return Boolean(
+    resolveSourceFile(path.join(projectRoot, 'routes'))
+    || resolveSourceIndexFile(path.join(projectRoot, 'routes')),
+  );
 }
 
 export async function hasSettingsFile(projectRoot) {
-  return (await exists(path.join(projectRoot, 'settings.js')))
-    || (await exists(path.join(projectRoot, 'settings', 'index.js')))
-    || (await exists(path.join(projectRoot, 'settings', 'apps.js')));
+  return Boolean(
+    resolveSourceFile(path.join(projectRoot, 'settings'))
+    || resolveSourceIndexFile(path.join(projectRoot, 'settings'))
+    || resolveSourceFile(path.join(projectRoot, 'settings', 'apps')),
+  );
 }
 
 export async function isProjectRoot(projectRoot) {
@@ -65,3 +69,7 @@ export async function resolveProjectRoot(projectRootHint) {
 
   throw new Error(`Could not find an AegisNode project from ${startDir}. Run inside project or use --project <path>.`);
 }
+
+export function getProjectSourceExtension(projectRoot) {
+  return detectProjectSourceExtension(projectRoot);
+}

package/src/cli/utils/scaffolds.js

@@ -6,31 +6,42 @@ export function toPascalCase(value) {
     .join('');
 }
 
+export function withSourceExtension(baseName, extension = '.js') {
+  return `${baseName}${extension}`;
+}
+
 function renderAppEntries(apps, indent = '  ') {
   return apps
     .map((app) => `${indent}{ name: ${JSON.stringify(app.name)}, mount: ${JSON.stringify(app.mount)} },`)
     .join('\n');
 }
 
-export function renderProjectPackageJson(projectName) {
-  return `${JSON.stringify(
-    {
-      name: projectName,
-      version: '1.0.0',
-      private: true,
-      type: 'module',
-      scripts: {
-        dev: 'aegisnode runserver',
-        start: 'node loader.cjs',
-        test: 'node --test',
-      },
-      dependencies: {
-        aegisnode: '^0.1.0',
-      },
+export function renderProjectPackageJson(projectName, { typescript = false } = {}) {
+  const packageJson = {
+    name: projectName,
+    version: '1.0.0',
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'aegisnode runserver',
+      start: 'node loader.cjs',
+      test: typescript ? 'node --import tsx/esm --test' : 'node --test',
     },
-    null,
-    2,
-  )}\n`;
+    dependencies: {
+      aegisnode: '^0.1.0',
+    },
+  };
+
+  if (typescript) {
+    packageJson.scripts.typecheck = 'tsc --noEmit';
+    packageJson.devDependencies = {
+      '@types/node': '^24.0.0',
+      tsx: '^4.21.0',
+      typescript: '^5.9.3',
+    };
+  }
+
+  return `${JSON.stringify(packageJson, null, 2)}\n`;
 }
 
 export function renderProjectAppJs() {
@@ -45,7 +56,18 @@ runProject({ rootDir: __dirname });
 `;
 }
 
-export function renderProjectLoaderCjs() {
+export function renderProjectLoaderCjs(sourceExtension = '.js') {
+  if (sourceExtension === '.ts') {
+    return `import('aegisnode').then(async ({ registerTypeScriptRuntime }) => {
+  await registerTypeScriptRuntime();
+  return import('./app.ts');
+}).catch((error) => {
+  console.error(error?.stack || error?.message || String(error));
+  process.exitCode = 1;
+});
+`;
+  }
+
   return `import('./app.js').catch((error) => {
   console.error(error?.stack || error?.message || String(error));
   process.exitCode = 1;
@@ -53,6 +75,33 @@ export function renderProjectLoaderCjs() {
 `;
 }
 
+export function renderTsConfig() {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        forceConsistentCasingInFileNames: true,
+        noEmit: true,
+        allowImportingTsExtensions: true,
+        types: ['node'],
+      },
+      include: [
+        'app.ts',
+        'settings.ts',
+        'routes.ts',
+        'apps/**/*.ts',
+      ],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
 export function renderProjectSettings(projectName, apps, appSecret = '') {
   return `export default {
   appName: '${projectName}',
@@ -177,7 +226,7 @@ export function renderController(appName) {
   return renderView(appName);
 }
 
-export function renderAppViewsFile(appName) {
+export function renderAppViewsFile(appName, sourceExtension = '.js') {
   const className = `${toPascalCase(appName)}View`;
   return `class ${className} {
   static home(_context, req, res, next) {
@@ -403,6 +452,19 @@ export default {
 `;
 }
 
+export function renderAppUtilsFile() {
+  return `/**
+ * App-local pure utilities.
+ *
+ * Use this file for small reusable functions that belong only to this app.
+ * Keep database access in models, business workflows in services, and request
+ * validation/sanitization in validators.
+ */
+
+export {};
+`;
+}
+
 export function renderAppSubscribersFile(appName) {
   return `export default function register${toPascalCase(appName)}Subscribers({ events, logger }) {
   events.subscribe('app.booted', ({ appName }) => {
@@ -457,9 +519,9 @@ export default {
 `;
 }
 
-export function renderAppRoutes(appName) {
+export function renderAppRoutes(appName, sourceExtension = '.js') {
   const viewClass = `${toPascalCase(appName)}View`;
-  return `import ${viewClass} from './views.js';
+  return `import ${viewClass} from './views${sourceExtension}';
 
 export default {
   appName: ${JSON.stringify(appName)},
@@ -479,10 +541,10 @@ export default {
 `;
 }
 
-export function renderAppModelTest(appName) {
+export function renderAppModelTest(appName, sourceExtension = '.js') {
   return `import test from 'node:test';
 import assert from 'node:assert/strict';
-import models from '../models.js';
+import models from '../models${sourceExtension}';
 
 test('${appName} model exposes basic CRUD methods', async () => {
   const Model = models[${JSON.stringify(appName)}];
@@ -504,10 +566,10 @@ test('${appName} model exposes basic CRUD methods', async () => {
 `;
 }
 
-export function renderAppValidatorTest(appName) {
+export function renderAppValidatorTest(appName, sourceExtension = '.js') {
   return `import test from 'node:test';
 import assert from 'node:assert/strict';
-import validators from '../validators.js';
+import validators from '../validators${sourceExtension}';
 
 test('${appName} validator validates id and payload', () => {
   const Validator = validators[${JSON.stringify(appName)}];
@@ -524,10 +586,10 @@ test('${appName} validator validates id and payload', () => {
 `;
 }
 
-export function renderAppServiceTest(appName) {
+export function renderAppServiceTest(appName, sourceExtension = '.js') {
   return `import test from 'node:test';
 import assert from 'node:assert/strict';
-import services from '../services.js';
+import services from '../services${sourceExtension}';
 
 test('${appName} service delegates to model layer', async () => {
   const Service = services[${JSON.stringify(appName)}];
@@ -567,10 +629,10 @@ test('${appName} service delegates to model layer', async () => {
 `;
 }
 
-export function renderAppRoutesTest(appName) {
+export function renderAppRoutesTest(appName, sourceExtension = '.js') {
   return `import test from 'node:test';
 import assert from 'node:assert/strict';
-import routes from '../routes.js';
+import routes from '../routes${sourceExtension}';
 
 test('${appName} routes register expected CRUD endpoints', () => {
   const calls = [];

package/src/index.js

@@ -5,6 +5,7 @@ export { createLogger } from './runtime/logger.js';
 export { deepMerge, normalizeApps } from './runtime/config.js';
 export { createAuthManager, normalizeAuthConfig, createAuthGuard } from './runtime/auth.js';
 export { createMailManager, normalizeMailConfig } from './runtime/mail.js';
+export { registerTypeScriptRuntime } from './runtime/typescript.js';
 export {
   money,
   number,

package/src/runtime/config.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import { pathToFileURL } from 'url';
+import { resolveSourceFile, resolveSourceIndexFile } from '../utils/source-files.js';
+import { importProjectModule } from './typescript.js';
 
 const BASE_PROCESS_ENV = new Map(Object.entries(process.env));
 const FRAMEWORK_LOADED_ENV_KEYS = new Set();
@@ -419,12 +420,11 @@ export function defaultConfig(rootDir) {
 }
 
 async function importDefaultIfExists(filePath) {
-  if (!fs.existsSync(filePath)) {
+  if (!filePath || !fs.existsSync(filePath)) {
     return null;
   }
 
-  const moduleUrl = `${pathToFileURL(filePath).href}?t=${Date.now()}`;
-  const loaded = await import(moduleUrl);
+  const loaded = await importProjectModule(filePath);
   return loaded?.default ?? null;
 }
 
@@ -432,12 +432,12 @@ export async function loadProjectConfig(rootDir, logger = null) {
   loadEnvironmentFiles(rootDir, logger);
   const config = defaultConfig(rootDir);
 
-  const settingsFile = path.join(rootDir, 'settings.js');
+  const settingsFile = resolveSourceFile(path.join(rootDir, 'settings'));
   const settingsDir = path.join(rootDir, 'settings');
-  const indexFile = path.join(settingsDir, 'index.js');
-  const dbFile = path.join(settingsDir, 'db.js');
-  const cacheFile = path.join(settingsDir, 'cache.js');
-  const appsFile = path.join(settingsDir, 'apps.js');
+  const indexFile = resolveSourceIndexFile(settingsDir);
+  const dbFile = resolveSourceFile(path.join(settingsDir, 'db'));
+  const cacheFile = resolveSourceFile(path.join(settingsDir, 'cache'));
+  const appsFile = resolveSourceFile(path.join(settingsDir, 'apps'));
 
   const [settingsConfig, indexConfig, dbConfig, cacheConfig, appsConfig] = await Promise.all([
     importDefaultIfExists(settingsFile),