aegisnode 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegisnode",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A view-first Node.js framework for modular web apps and JSON APIs with CLI scaffolding, runtime injection, auth, uploads, i18n, mail, and WebSocket support.",
   "type": "module",
   "main": "./src/index.js",

package/scripts/smoke-test.js

@@ -7,14 +7,17 @@ import path from 'path';
 import fs from 'fs/promises';
 import { startProject } from '../src/cli/commands/startproject.js';
 import { createApp } from '../src/cli/commands/createapp.js';
+import { runCli } from '../src/cli/index.js';
 import { generateArtifact } from '../src/cli/commands/generate.js';
 import { createKernel } from '../src/runtime/kernel.js';
 import { runServer } from '../src/cli/commands/runserver.js';
+import { runGenerateLoader } from '../src/cli/commands/generateloader.js';
 import { runProject } from '../src/index.js';
 import { createAuthManager, normalizeAuthConfig } from '../src/runtime/auth.js';
 import { loadProjectConfig } from '../src/runtime/config.js';
 import { initializeDatabase, closeDatabase } from '../src/runtime/database.js';
 import { runDoctor } from '../src/cli/commands/doctor.js';
+import { runFixApp } from '../src/cli/commands/fixapp.js';
 import { runUpdateDependencies } from '../src/cli/commands/updatedeps.js';
 import { createHelpers } from '../src/runtime/helpers.js';
 
@@ -137,8 +140,10 @@ async function main() {
   await startProject({ projectName, cwd: sandboxRoot });
   const generatedProjectEnv = await fs.readFile(path.join(projectRoot, '.env'), 'utf8');
   assert.match(generatedProjectEnv, /^APP_SECRET=.{16,}$/m);
+  const generatedAppSecret = generatedProjectEnv.match(/^APP_SECRET=(.+)$/m)?.[1]?.trim();
+  assert.ok(generatedAppSecret);
   const generatedSettings = await fs.readFile(path.join(projectRoot, 'settings.js'), 'utf8');
-  assert.match(generatedSettings, /appSecret:\s*process\.env\.APP_SECRET\s*\|\|\s*''/);
+  assert.ok(generatedSettings.includes(`appSecret: process.env.APP_SECRET || ${JSON.stringify(generatedAppSecret)}`));
   await assert.rejects(
     () => runProject({
       rootDir: projectRoot,
@@ -404,6 +409,74 @@ dkcqnJD4SGWVeG+KhA==
     await fs.access(filePath);
   }
 
+  await fs.unlink(path.join(projectRoot, 'app.js'));
+  await fs.unlink(path.join(projectRoot, 'loader.cjs'));
+  const restoredStartupEntries = await runGenerateLoader({
+    projectRoot,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(restoredStartupEntries.createdApp, true);
+  assert.equal(restoredStartupEntries.createdLoader, true);
+  await fs.access(path.join(projectRoot, 'app.js'));
+  await fs.access(path.join(projectRoot, 'loader.cjs'));
+
+  await fs.writeFile(
+    path.join(envProjectRoot, 'settings.js'),
+    `export default {
+  appName: 'envdemo',
+  env: 'production',
+  logging: {
+    level: 'info',
+  },
+  security: {
+    appSecret: process.env.APP_SECRET || '',
+    ddos: {
+      maxRequests: 120,
+    },
+  },
+  environments: {
+    default: {
+      security: {
+        ddos: {
+          windowMs: 45000,
+        },
+      },
+    },
+    production: {
+      logging: { level: 'warn' },
+      security: { ddos: { maxRequests: 80 } },
+    },
+  },
+};
+`,
+    'utf8',
+  );
+  await fs.unlink(path.join(envProjectRoot, 'loader.cjs'));
+  const missingLoaderDoctorReport = await runDoctor({
+    projectRoot: envProjectRoot,
+    failOnError: false,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(missingLoaderDoctorReport.summary.errors, 1);
+  assert.ok(
+    missingLoaderDoctorReport.entries.some((entry) => (
+      entry.level === 'ERROR'
+      && /loader\.cjs is missing for production startup/.test(entry.message)
+    )),
+  );
+  const restoredProductionLoader = await runGenerateLoader({
+    projectRoot: envProjectRoot,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(restoredProductionLoader.createdLoader, true);
+  await fs.access(path.join(envProjectRoot, 'loader.cjs'));
+
   const registryPackages = new Map([
     ['alpha', '2.0.0'],
     ['@scope/bravo', '3.4.0'],
@@ -519,6 +592,7 @@ dkcqnJD4SGWVeG+KhA==
   await fs.access(path.join(projectRoot, 'apps', 'users', 'models.js'));
   await fs.access(path.join(projectRoot, 'apps', 'users', 'validators.js'));
   await fs.access(path.join(projectRoot, 'apps', 'users', 'services.js'));
+  await fs.access(path.join(projectRoot, 'apps', 'users', 'utils.js'));
   await fs.access(path.join(projectRoot, 'apps', 'users', 'subscribers.js'));
   await fs.access(path.join(projectRoot, 'apps', 'users', 'tests', 'models.test.js'));
   await fs.access(path.join(projectRoot, 'apps', 'users', 'tests', 'validators.test.js'));
@@ -534,6 +608,90 @@ dkcqnJD4SGWVeG+KhA==
   assert.equal(doctorReport.summary.errors, 0);
   const projectRoutesFile = await fs.readFile(path.join(projectRoot, 'routes.js'), 'utf8');
   assert.match(projectRoutesFile, /route\.use\((['"])\/users\1, users\);/);
+
+  await fs.unlink(path.join(projectRoot, 'apps', 'users', 'utils.js'));
+  await fs.unlink(path.join(projectRoot, 'apps', 'users', 'tests', 'routes.test.js'));
+  await fs.writeFile(
+    path.join(projectRoot, 'routes.js'),
+    projectRoutesFile
+      .replace(/import users from '\.\/apps\/users\/routes\.js';\n/, '')
+      .replace(/\s*route\.use\((['"])\/users\1, users\);\n/, '\n'),
+    'utf8',
+  );
+  const appDoctorRouteReport = await runDoctor({
+    projectRoot,
+    appName: 'users',
+    failOnError: false,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(
+    appDoctorRouteReport.entries.some((entry) => entry.message.includes('Project routes.js is missing import for app "users".')),
+    true,
+  );
+  assert.equal(
+    appDoctorRouteReport.entries.some((entry) => entry.message.includes('Project routes.js is missing route.use(...) mount for app "users".')),
+    true,
+  );
+
+  const settingsBeforeFix = await fs.readFile(path.join(projectRoot, 'settings.js'), 'utf8');
+  await fs.writeFile(
+    path.join(projectRoot, 'settings.js'),
+    settingsBeforeFix.replace(/\n\s*\{ name: "users", mount: "\/users" \},/, ''),
+    'utf8',
+  );
+
+  const appDoctorReport = await runDoctor({
+    projectRoot,
+    appName: 'users',
+    failOnError: false,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(appDoctorReport.summary.errors, 0);
+  assert.equal(
+    appDoctorReport.entries.some((entry) => entry.message.includes('App "users" is not declared in settings.apps.')),
+    true,
+  );
+  assert.equal(
+    appDoctorReport.entries.some((entry) => entry.message.includes('App "users" missing utils.js.')),
+    true,
+  );
+  assert.equal(
+    appDoctorReport.entries.some((entry) => entry.message.includes('App "users" missing tests/routes.test.js.')),
+    true,
+  );
+
+  const fixAppResult = await runFixApp({
+    appName: 'users',
+    projectRoot,
+  });
+  assert.equal(fixAppResult.registryUpdated, true);
+  assert.equal(fixAppResult.routesUpdated, true);
+  await fs.access(path.join(projectRoot, 'apps', 'users', 'utils.js'));
+  await fs.access(path.join(projectRoot, 'apps', 'users', 'tests', 'routes.test.js'));
+  const fixedSettingsFile = await fs.readFile(path.join(projectRoot, 'settings.js'), 'utf8');
+  assert.match(fixedSettingsFile, /\{ name: "users", mount: "\/users" \},/);
+  const fixedRoutesFile = await fs.readFile(path.join(projectRoot, 'routes.js'), 'utf8');
+  assert.match(fixedRoutesFile, /import users from '\.\/apps\/users\/routes\.js';/);
+  assert.match(fixedRoutesFile, /route\.use\((['"])\/users\1, users\);/);
+  await assert.doesNotReject(
+    () => runCli(['doctor', '--app', 'users', '--project', projectRoot]),
+  );
+  await assert.rejects(
+    () => runCli(['doctor', 'users', '--project', projectRoot]),
+    /Doctor app target must use --app <app-name>/,
+  );
+  await assert.doesNotReject(
+    () => runCli(['fix', '--app', 'users', '--project', projectRoot]),
+  );
+  await assert.rejects(
+    () => runCli(['fix', 'users', '--project', projectRoot]),
+    /Fix app target must use --app <app-name>/,
+  );
+
   await generateArtifact({
     type: 'view',
     name: 'profile',
@@ -1288,7 +1446,7 @@ export default {
   );
   await fs.writeFile(
     path.join(projectRoot, 'routes.js'),
-    `export default {\n  register(route) {\n    route.get('/csrf-token', (req, res) => {\n      res.json({ token: req.csrfToken() });\n    });\n\n    route.get('/csrf-form', (req, res) => {\n      return res.render('csrf-form', { layout: false });\n    });\n\n    route.post('/submit', (req, res) => {\n      res.json({ ok: true, body: req.body || {} });\n    });\n  },\n};\n`,
+    `export default {\n  register(route) {\n    route.get('/csrf-token', (req, res) => {\n      res.json({ token: req.csrfToken() });\n    });\n\n    route.get('/csrf-form', (req, res) => {\n      return res.render('csrf-form', { layout: false });\n    });\n\n    route.post('/submit', (req, res) => {\n      res.json({ ok: true, body: req.body || {} });\n    });\n\n    route.post('/submit-upload', route.upload.none(), (req, res) => {\n      res.json({ ok: true, body: req.body || {} });\n    });\n  },\n};\n`,
     'utf8',
   );
 
@@ -1361,6 +1519,32 @@ export default {
   assert.equal(validJsonTokenJson.ok, true);
   assert.equal(validJsonTokenJson.body.name, 'json-with-token');
 
+  const missingMultipartTokenBody = new FormData();
+  missingMultipartTokenBody.set('name', 'multipart-without-token');
+  const missingMultipartTokenResponse = await fetch(`http://127.0.0.1:${csrfPort}/submit-upload`, {
+    method: 'POST',
+    headers: {
+      cookie: csrfCookie,
+    },
+    body: missingMultipartTokenBody,
+  });
+  assert.equal(missingMultipartTokenResponse.status, 403);
+
+  const validMultipartTokenBody = new FormData();
+  validMultipartTokenBody.set('_csrf', csrfTokenJson.token);
+  validMultipartTokenBody.set('name', 'multipart-with-token');
+  const validMultipartTokenResponse = await fetch(`http://127.0.0.1:${csrfPort}/submit-upload`, {
+    method: 'POST',
+    headers: {
+      cookie: csrfCookie,
+    },
+    body: validMultipartTokenBody,
+  });
+  assert.equal(validMultipartTokenResponse.status, 200);
+  const validMultipartTokenJson = await validMultipartTokenResponse.json();
+  assert.equal(validMultipartTokenJson.ok, true);
+  assert.equal(validMultipartTokenJson.body.name, 'multipart-with-token');
+
   const csrfFormResponse = await fetch(`http://127.0.0.1:${csrfPort}/csrf-form`, {
     headers: {
       cookie: csrfCookie,

package/src/cli/commands/createapp.js

@@ -1,191 +1,28 @@
-import fs from 'fs/promises';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import { ensureDir, ensureValidName, exists, normalizeMountPath, writeFile } from '../utils/fs.js';
+import { ensureValidName, normalizeMountPath } from '../utils/fs.js';
 import { resolveProjectRoot } from '../utils/project.js';
 import {
-  renderAppRoutes,
-  renderAppViewsFile,
-  renderAppModelsFile,
-  renderAppValidatorsFile,
-  renderAppServicesFile,
-  renderAppSubscribersFile,
-  renderAppModelTest,
-  renderAppValidatorTest,
-  renderAppServiceTest,
-  renderAppRoutesTest,
-  renderSettingsApps,
-} from '../utils/scaffolds.js';
-
-const APPS_START = '// AEGIS_APPS_START';
-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 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 moduleUrl = `${pathToFileURL(filePath).href}?t=${Date.now()}`;
-  const loaded = await import(moduleUrl);
-  return loaded?.default;
-}
-
-async function detectSettingsMode(projectRoot) {
-  const single = path.join(projectRoot, 'settings.js');
-  const split = path.join(projectRoot, 'settings', 'apps.js');
-
-  if (await exists(single)) {
-    return { mode: 'single', file: single };
-  }
-
-  if (await exists(split)) {
-    return { mode: 'split', file: split };
-  }
-
-  throw new Error(`Not an AegisNode project root: missing ${single} (or legacy ${split})`);
-}
-
-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);
-}
-
-async function updateAppRegistry(projectRoot, apps, settingsMode) {
-  if (settingsMode.mode === 'single') {
-    await updateSingleSettingsApps(settingsMode.file, apps);
-    return;
-  }
-
-  await writeFile(path.join(projectRoot, 'settings', 'apps.js'), renderSettingsApps(apps));
-}
-
-async function updateProjectRoutesFile(projectRoot, appName, mountPath) {
-  const routesFile = path.join(projectRoot, 'routes.js');
-  if (!(await exists(routesFile))) {
-    // Keep backward compatibility for legacy projects that still use routes/index.js.
-    return;
-  }
-
-  const importName = toImportName(appName);
-  const importLine = `import ${importName} from './apps/${appName}/routes.js';`;
-  const routeLine = `    route.use(${JSON.stringify(mountPath)}, ${importName});`;
-
-  let content = await fs.readFile(routesFile, 'utf8');
-
-  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}`;
-    }
-  }
-
-  if (!content.includes(routeLine)) {
-    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`);
-    } else {
-      const match = content.match(/register\s*\([^)]*\)\s*{[\s\S]*?\n\s*}/m);
-      if (match) {
-        content = content.replace(match[0], `${match[0]}\n${routeLine}`);
-      }
-    }
-  }
-
-  await writeFile(routesFile, content);
-}
-
-async function createScaffold(projectRoot, appName) {
-  const appRoot = path.join(projectRoot, 'apps', appName);
-
-  await ensureDir(appRoot);
-  await ensureDir(path.join(appRoot, 'tests'));
-
-  await writeFile(path.join(appRoot, 'views.js'), renderAppViewsFile(appName));
-  await writeFile(path.join(appRoot, 'models.js'), renderAppModelsFile(appName));
-  await writeFile(path.join(appRoot, 'validators.js'), renderAppValidatorsFile(appName));
-  await writeFile(path.join(appRoot, 'services.js'), renderAppServicesFile(appName));
-  await writeFile(path.join(appRoot, 'subscribers.js'), renderAppSubscribersFile(appName));
-  await writeFile(path.join(appRoot, 'routes.js'), renderAppRoutes(appName));
-  await writeFile(path.join(appRoot, 'tests', 'models.test.js'), renderAppModelTest(appName));
-  await writeFile(path.join(appRoot, 'tests', 'validators.test.js'), renderAppValidatorTest(appName));
-  await writeFile(path.join(appRoot, 'tests', 'services.test.js'), renderAppServiceTest(appName));
-  await writeFile(path.join(appRoot, 'tests', 'routes.test.js'), renderAppRoutesTest(appName));
-}
+  detectSettingsMode,
+  ensureAppScaffold,
+  readAppsConfig,
+  updateAppRegistry,
+  updateProjectRoutesFile,
+} from '../utils/apps.js';
 
 export async function createApp({ appName, projectRoot, mount }) {
   ensureValidName(appName, 'app');
 
   const resolvedRoot = await resolveProjectRoot(projectRoot);
-
   const settingsMode = await detectSettingsMode(resolvedRoot);
   const normalizedMount = normalizeMountPath(mount || `/${appName}`);
   const existingApps = await readAppsConfig(settingsMode);
 
   if (existingApps.some((entry) => entry.name === appName)) {
-    throw new Error(`App \"${appName}\" already exists in project settings`);
+    throw new Error(`App "${appName}" already exists in project settings`);
   }
 
-  const updatedApps = [...existingApps, { name: appName, mount: normalizedMount }];
-
-  await createScaffold(resolvedRoot, appName);
-  await updateAppRegistry(resolvedRoot, updatedApps, settingsMode);
+  await ensureAppScaffold(resolvedRoot, appName);
+  await updateAppRegistry(resolvedRoot, [...existingApps, { name: appName, mount: normalizedMount }], settingsMode);
   await updateProjectRoutesFile(resolvedRoot, appName, normalizedMount);
 
-  console.log(`App \"${appName}\" created at ${path.join(resolvedRoot, 'apps', appName)}`);
+  console.log(`App "${appName}" created at ${resolvedRoot}/apps/${appName}`);
 }

package/src/cli/commands/doctor.js

@@ -1,7 +1,9 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { loadProjectConfig } from '../../runtime/config.js';
+import { ensureValidName } from '../utils/fs.js';
 import { resolveProjectRoot } from '../utils/project.js';
+import { getAppScaffoldEntries, toImportName } from '../utils/apps.js';
 
 function createCollector() {
   const entries = [];
@@ -26,25 +28,47 @@ async function fileExists(filePath) {
   }
 }
 
-async function runAppChecks(rootDir, config, collector) {
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function runAppChecks(rootDir, config, collector, targetAppName = null) {
   const apps = Array.isArray(config.apps) ? config.apps : [];
+  const declaredApps = new Map();
 
-  if (apps.length === 0) {
+  for (const app of apps) {
+    const appName = app?.name;
+    if (typeof appName === 'string' && appName.trim().length > 0) {
+      declaredApps.set(appName, app);
+    }
+  }
+
+  if (!targetAppName && apps.length === 0) {
     collector.warn('No apps declared in settings.apps.');
     return;
   }
 
-  collector.ok(`Declared apps: ${apps.map((app) => app.name).join(', ')}`);
+  if (!targetAppName) {
+    collector.ok(`Declared apps: ${apps.map((app) => app.name).join(', ')}`);
+  }
 
-  for (const app of apps) {
-    const appName = app?.name;
+  const routesFile = path.join(rootDir, 'routes.js');
+  const routesFileExists = await fileExists(routesFile);
+  const routesContent = routesFileExists ? await fs.readFile(routesFile, 'utf8') : '';
+  const targetApps = targetAppName ? [targetAppName] : apps;
+
+  for (const appEntry of targetApps) {
+    const appName = targetAppName || appEntry?.name;
+    const app = targetAppName ? declaredApps.get(appName) || null : appEntry;
     const mount = app?.mount;
     if (typeof appName !== 'string' || appName.trim().length === 0) {
-      collector.error(`Invalid app entry: ${JSON.stringify(app)}`);
+      collector.error(`Invalid app entry: ${JSON.stringify(appEntry)}`);
       continue;
     }
 
-    if (typeof mount !== 'string' || !mount.startsWith('/')) {
+    if (!app) {
+      collector.warn(`App "${appName}" is not declared in settings.apps.`);
+    } else if (typeof mount !== 'string' || !mount.startsWith('/')) {
       collector.error(`App "${appName}" has invalid mount "${String(mount)}" (must start with /).`);
     }
 
@@ -55,21 +79,65 @@ async function runAppChecks(rootDir, config, collector) {
       continue;
     }
 
-    const requiredFiles = ['routes.js', 'views.js', 'services.js', 'models.js', 'validators.js'];
-    for (const fileName of requiredFiles) {
-      const target = path.join(appRoot, fileName);
+    for (const entry of getAppScaffoldEntries(appName)) {
+      const target = path.join(rootDir, entry.target);
       if (!(await fileExists(target))) {
-        collector.warn(`App "${appName}" missing ${fileName}.`);
+        collector.warn(`App "${appName}" missing ${path.relative(appRoot, target)}.`);
       }
     }
 
-    const subscribersFile = path.join(appRoot, 'subscribers.js');
-    if (!(await fileExists(subscribersFile))) {
-      collector.warn(`App "${appName}" missing subscribers.js.`);
+    if (!app) {
+      continue;
+    }
+
+    if (config.autoMountApps === true) {
+      collector.ok(`App "${appName}" will be mounted automatically from settings.apps.`);
+      continue;
+    }
+
+    if (!routesFileExists) {
+      collector.warn(`Project routes.js is missing; app "${appName}" cannot be mounted centrally.`);
+      continue;
+    }
+
+    const importPath = `./apps/${appName}/routes.js`;
+    const importName = toImportName(appName);
+    const routePattern = new RegExp(`route\\.use\\([^\\n]*,\\s*${escapeRegExp(importName)}\\s*\\);`);
+
+    if (!routesContent.includes(importPath)) {
+      collector.warn(`Project routes.js is missing import for app "${appName}".`);
+    }
+
+    if (!routePattern.test(routesContent)) {
+      collector.warn(`Project routes.js is missing route.use(...) mount for app "${appName}".`);
     }
   }
 }
 
+async function runStartupEntryChecks(rootDir, config, collector) {
+  const env = String(config.env || process.env.NODE_ENV || 'development').trim().toLowerCase();
+  const appEntryPath = path.join(rootDir, 'app.js');
+  const loaderEntryPath = path.join(rootDir, 'loader.cjs');
+  const appEntryExists = await fileExists(appEntryPath);
+  const loaderEntryExists = await fileExists(loaderEntryPath);
+
+  if (appEntryExists) {
+    collector.ok('app.js exists.');
+  } else if (env === 'production') {
+    collector.error('app.js is missing for production startup. Run "aegisnode generateloader" to restore startup entry files.');
+  } else {
+    collector.warn('app.js is missing. Run "aegisnode generateloader" to restore startup entry files.');
+  }
+
+  if (loaderEntryExists) {
+    collector.ok('loader.cjs exists.');
+  } else if (env === 'production') {
+    collector.error('loader.cjs is missing for production startup. Run "aegisnode generateloader" to restore it.');
+  } else {
+    collector.warn('loader.cjs is missing. Generate it with "aegisnode generateloader" before non-development startup.');
+  }
+}
+
 function runSecurityChecks(config, collector) {
   const env = String(config.env || process.env.NODE_ENV || 'development');
   const security = config.security || {};
@@ -169,7 +237,12 @@ export async function runDoctor({
   projectRoot,
   failOnError = true,
   output = console,
+  appName = null,
 } = {}) {
+  if (appName) {
+    ensureValidName(appName, 'app');
+  }
+
   const resolvedRoot = await resolveProjectRoot(projectRoot || process.cwd());
   const collector = createCollector();
 
@@ -178,11 +251,17 @@ export async function runDoctor({
   const config = await loadProjectConfig(resolvedRoot);
   collector.ok(`Environment: ${config.env || 'development'}`);
 
-  await runAppChecks(resolvedRoot, config, collector);
-  runSecurityChecks(config, collector);
-  runAuthChecks(config, collector);
-  runApiChecks(config, collector);
-  await runTemplateChecks(resolvedRoot, config, collector);
+  if (appName) {
+    collector.ok(`Doctor scope: app "${appName}"`);
+    await runAppChecks(resolvedRoot, config, collector, appName);
+  } else {
+    await runAppChecks(resolvedRoot, config, collector);
+    await runStartupEntryChecks(resolvedRoot, config, collector);
+    runSecurityChecks(config, collector);
+    runAuthChecks(config, collector);
+    runApiChecks(config, collector);
+    await runTemplateChecks(resolvedRoot, config, collector);
+  }
 
   const summary = printSummary(collector.entries, output);