aegisnode 0.0.4 → 0.1.0

package/README.md

@@ -43,6 +43,7 @@ It keeps the development model simple, but adds enough structure and tooling to
 Core features:
 
 - CLI generators (`startproject`, `createapp`, `runserver`)
+- App scaffold repair command (`fix`)
 - Startup entry generator (`generateloader`)
 - Project health checker (`doctor`)
 - Dependency updater (`updatedeps`)
@@ -61,15 +62,16 @@ Core features:
 - Root route file `routes.js` (not `routes/` folder)
 - Automatic default confirmation page on `/` when no custom `/` route exists
 - App folder uses `views.js` (not `controllers/` folder)
-- `createapp` uses file modules: `views.js`, `models.js`, `validators.js`, `routes.js`, `subscribers.js`, `services.js`
+- `createapp` uses file modules: `views.js`, `models.js`, `validators.js`, `routes.js`, `subscribers.js`, `services.js`, `utils.js`
 - `createapp` also generates app tests in `apps/<app>/tests`
 - EJS templates configurable in `settings.js` with Django-style base layout flow
 - Built-in runtime helpers (`money`, `number`, `dateTime`, `timeElapsed`, `toObjectId`) + `jlive` bridge
 
 `startproject` creates `app.js`, `loader.cjs`, `.env`, `settings.js`, and `routes.js` without creating any default app.
-It does not create `public/` or `logs/`; create your own folders and set them in `settings.js`.
+Use `startproject --typescript` to generate `app.ts`, `settings.ts`, `routes.ts`, app `*.ts` files, and `tsconfig.json` instead.
+It does not create `public/` or `logs/`; create your own folders and set them in `settings.js` or `settings.ts`.
 
-Environment files are loaded automatically before `settings.js` is imported.
+Environment files are loaded automatically before `settings.js` or `settings.ts` is imported.
 Supported files:
 - `.env`
 - `.env.local`
@@ -86,20 +88,36 @@ Shell or hosting-panel environment variables win over values from `.env` files.
 npm install -g aegisnode
 
 aegisnode startproject blog
+aegisnode startproject blog-ts --typescript
 npm --prefix blog install
 aegisnode runserver --project blog
 
 aegisnode createapp users --project blog
+aegisnode fix --app users --project blog
 aegisnode generate view profile --app users --project blog
 aegisnode generate route profile --app users --project blog
 aegisnode generateloader --project blog
 aegisnode doctor --project blog
+aegisnode doctor --app users --project blog
 aegisnode updatedeps --project blog
 ```
 
 `cd blog` is optional. You can run commands from parent folder with `--project blog`.
 
-`createapp`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
+Use `--typescript` on `startproject` when you want a TypeScript scaffold. That generates `app.ts`, `settings.ts`, `routes.ts`, `tsconfig.json`, app files like `views.ts`/`services.ts`, and generated artifacts such as `profile.view.ts`.
+
+### JavaScript vs TypeScript Projects
+
+The project type is chosen once at `startproject` time:
+- `aegisnode startproject blog` creates a JavaScript project
+- `aegisnode startproject blog --typescript` creates a TypeScript project
+
+After that, the rest of the CLI follows the project automatically:
+- `createapp` generates `views.js` / `services.js` / `routes.js` in JavaScript projects, or `views.ts` / `services.ts` / `routes.ts` in TypeScript projects
+- `generate` creates artifacts with the same extension as the project, for example `profile.view.js` or `profile.view.ts`
+- `fix`, `doctor`, and `generateloader` also check and repair the matching project file type automatically
+
+`createapp`, `fix`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
 Run them from the project root; do not `cd` into `apps/<app>`.
 Startup mode rules:
 - Development (`env === development`): start with `aegisnode runserver` only.
@@ -107,6 +125,20 @@ Startup mode rules:
 - `node app.js` and `node loader.cjs` are rejected in development mode.
 - `aegisnode runserver` is rejected outside development mode.
 
+### Trust Proxy
+
+If your app runs behind Nginx, Apache, Passenger, or another reverse proxy that terminates HTTPS before the Node process, set top-level `trustProxy` in `settings.js`:
+
+```js
+export default {
+  trustProxy: 1,
+};
+```
+
+This is the AegisNode equivalent of `app.set('trust proxy', 1)` in raw Express. It makes `req.secure`, `req.protocol`, client IP detection, secure cookies, and HTTPS-aware auth logic behave correctly behind the proxy.
+
+Prefer an exact value such as `1`, `'loopback'`, or a subnet string instead of `true`.
+
 ### Deploy On Phusion Passenger
 
 AegisNode supports Passenger-style startup using the generated `loader.cjs`.
@@ -125,8 +157,8 @@ HTTPS note:
 - Only enable `https` in `settings.js` when Node itself should serve TLS directly.
 
 How it works:
-- `loader.cjs` imports `app.js`.
-- `app.js` starts AegisNode with project root resolved from its own file location, so it works correctly under Passenger.
+- `loader.cjs` imports `app.js` in JavaScript projects or `app.ts` in TypeScript projects.
+- `app.js` / `app.ts` starts AegisNode with project root resolved from its own file location, so it works correctly under Passenger.
 
 
 Generated routes are auto-wired into `apps/<app>/routes.js`.
@@ -145,10 +177,8 @@ By default, new app routes are API-ready:
 
 Default flow is `route -> validator -> service -> model`.
 Default app tests generated by `createapp`:
-- `apps/<app>/tests/models.test.js`
-- `apps/<app>/tests/validators.test.js`
-- `apps/<app>/tests/services.test.js`
-- `apps/<app>/tests/routes.test.js`
+- JavaScript projects: `apps/<app>/tests/models.test.js`, `validators.test.js`, `services.test.js`, `routes.test.js`
+- TypeScript projects: `apps/<app>/tests/models.test.ts`, `validators.test.ts`, `services.test.ts`, `routes.test.ts`
 
 Run all project tests:
 
@@ -170,6 +200,26 @@ aegisnode doctor
 - Auth safety checks (JWT secret, OAuth2 `allowHttp` in production)
 - Template directory availability
 
+Run app-level scaffold checks for one app:
+
+```bash
+aegisnode doctor --app users
+```
+
+App-level doctor focuses on the named app:
+- Missing `views.js`, `models.js`, `services.js`, `validators.js`, `routes.js`, `subscribers.js`, `utils.js`
+- Missing generated test files under `apps/<app>/tests`
+- Missing `settings.apps` declaration for that app
+- Missing central `routes.js` import/mount when `autoMountApps` is off
+
+Repair a partially missing app scaffold:
+
+```bash
+aegisnode fix --app users
+```
+
+`fix` recreates missing default app files and tests without overwriting existing files. If the app is missing from `settings.apps` or central `routes.js`, it restores those registrations too.
+
 Regenerate project startup entry files if needed:
 
 ```bash
@@ -241,7 +291,7 @@ export default {
 
 Injected app layers also receive `env`, so views/services/models/validators/controllers/subscribers/loaders can use `env.MY_NAME` without importing `process.env`.
 
-`settings.js` (generated shape):
+`settings.js` (generated shape, or `settings.ts` in TypeScript mode):
 
 ```js
 export default {
@@ -288,16 +338,26 @@ Each generated app usually contains:
 - `apps/<app>/views.js`
 - `apps/<app>/models.js`
 - `apps/<app>/services.js`
+- `apps/<app>/utils.js`
 - `apps/<app>/subscribers.js`
 - `apps/<app>/routes.js`
 
+If the project was created with `--typescript`, the same generated files use `.ts` instead of `.js`.
+
 Usage by file:
 - `views.js`: HTTP handlers (`req`, `res`, `next`). Default signature can be context-first: `handler({ service, validator, services, validators, ... }, req, res, next)`.
+  Keep `views.js` thin: prefer only the view class and its imports. Avoid defining extra local helper/utility functions in the view file. Move reusable pure logic to `utils.js` and app workflows to `services.js`.
 - `models.js`: data access layer only (SQL/NoSQL operations).
-- `services.js`: business logic layer; orchestrates models.
+- `services.js`: business logic layer; orchestrates models and uses injected runtime objects when needed.
+- `utils.js`: app-local pure utility functions. Use this for small reusable helpers that belong only to the app. Do not put DB access, request validation, or business workflows here.
+  `utils.js` is a plain module, not an injected runtime layer. If a utility needs `jlive`, `helpers`, `i18n`, or another injected runtime object, inject that object into a view/service/model first and pass it into the utility function as an argument.
 - `subscribers.js`: event listeners (for example `app.booted`, `ws.connection`, custom events).
 - `routes.js`: route mapping only (`route.get(...)`, `route.post(...)`, `route.use(...)`) to view handlers.
 
+Short rule for `utils.js` vs `services.js`:
+- Use `utils.js` for pure app-local helpers such as string formatting, slug generation, payload shaping, or small mappers.
+- Use `services.js` for application behavior: anything that coordinates models, injected runtime objects, or feature rules.
+
 Route modules are mapping-only (`register(route)`).
 Framework context is injected into handlers as first argument (when handler uses 4 args): `{ service, validator, services, models, validators, auth, mail, helpers, i18n, events, ... }`.
 `req.aegis` is also available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegisnode",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "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",
@@ -55,6 +55,7 @@
     "nodemailer": "^8.0.2",
     "querymesh": "^0.0.7",
     "socket.io": "^4.8.1",
-    "swagger-ui-express": "^5.0.1"
+    "swagger-ui-express": "^5.0.1",
+    "tsx": "^4.21.0"
   }
 }

package/scripts/smoke-test.js

@@ -7,6 +7,7 @@ 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';
@@ -16,6 +17,7 @@ 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';
 
@@ -134,6 +136,7 @@ async function main() {
   const dotenvSandboxRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aegisnode-dotenv-'));
   const httpsSandboxRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aegisnode-https-'));
   const proxySandboxRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aegisnode-proxy-'));
+  const typescriptSandboxRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aegisnode-ts-'));
 
   await startProject({ projectName, cwd: sandboxRoot });
   const generatedProjectEnv = await fs.readFile(path.join(projectRoot, '.env'), 'utf8');
@@ -153,6 +156,66 @@ async function main() {
     /started with "aegisnode runserver"/,
   );
 
+  const tsProjectName = 'forumts';
+  const tsProjectRoot = path.join(typescriptSandboxRoot, tsProjectName);
+  await startProject({ projectName: tsProjectName, cwd: typescriptSandboxRoot, typescript: true });
+  await fs.access(path.join(tsProjectRoot, 'app.ts'));
+  await fs.access(path.join(tsProjectRoot, 'settings.ts'));
+  await fs.access(path.join(tsProjectRoot, 'routes.ts'));
+  await fs.access(path.join(tsProjectRoot, 'tsconfig.json'));
+  const tsPackageJson = JSON.parse(await fs.readFile(path.join(tsProjectRoot, 'package.json'), 'utf8'));
+  assert.equal(tsPackageJson.scripts.test, 'node --import tsx/esm --test');
+  assert.equal(tsPackageJson.scripts.typecheck, 'tsc --noEmit');
+  assert.equal(tsPackageJson.devDependencies.tsx, '^4.21.0');
+  assert.equal(tsPackageJson.devDependencies.typescript, '^5.9.3');
+  const tsConfig = await loadProjectConfig(tsProjectRoot);
+  assert.equal(tsConfig.appName, 'forumts');
+  await createApp({
+    appName: 'users',
+    projectRoot: tsProjectRoot,
+    mount: '/users',
+  });
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'routes.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'views.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'models.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'validators.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'services.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'utils.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'subscribers.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'tests', 'models.test.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'tests', 'validators.test.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'tests', 'services.test.ts'));
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'tests', 'routes.test.ts'));
+  await generateArtifact({
+    type: 'view',
+    name: 'profile',
+    appName: 'users',
+    projectRoot: tsProjectRoot,
+  });
+  await fs.access(path.join(tsProjectRoot, 'apps', 'users', 'profile.view.ts'));
+  await generateArtifact({
+    type: 'route',
+    name: 'profile',
+    appName: 'users',
+    projectRoot: tsProjectRoot,
+  });
+  const tsUsersRoutesFile = await fs.readFile(path.join(tsProjectRoot, 'apps', 'users', 'routes.ts'), 'utf8');
+  assert.match(tsUsersRoutesFile, /import ProfileView from '\.\/profile\.view\.ts';/);
+  assert.match(tsUsersRoutesFile, /route\.get\('\/profile', ProfileView\.index\);/);
+  const tsDoctorReport = await runDoctor({
+    projectRoot: tsProjectRoot,
+    failOnError: true,
+    output: {
+      log() {},
+    },
+  });
+  assert.equal(tsDoctorReport.summary.errors, 0);
+  const tsServer = await runServer({
+    projectRoot: tsProjectRoot,
+    port: 0,
+  });
+  await tsServer.stop();
+
   const envProjectName = 'envdemo';
   const envProjectRoot = path.join(envSandboxRoot, envProjectName);
   await startProject({ projectName: envProjectName, cwd: envSandboxRoot });
@@ -590,6 +653,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'));
@@ -605,6 +669,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',

package/src/cli/commands/createapp.js

@@ -1,191 +1,29 @@
-import fs from 'fs/promises';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import { ensureDir, ensureValidName, exists, normalizeMountPath, writeFile } from '../utils/fs.js';
-import { resolveProjectRoot } from '../utils/project.js';
+import { ensureValidName, normalizeMountPath } from '../utils/fs.js';
+import { getProjectSourceExtension, 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 sourceExtension = getProjectSourceExtension(resolvedRoot);
   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 updateProjectRoutesFile(resolvedRoot, appName, normalizedMount);
+  await ensureAppScaffold(resolvedRoot, appName, { sourceExtension });
+  await updateAppRegistry(resolvedRoot, [...existingApps, { name: appName, mount: normalizedMount }], settingsMode);
+  await updateProjectRoutesFile(resolvedRoot, appName, normalizedMount, sourceExtension);
 
-  console.log(`App \"${appName}\" created at ${path.join(resolvedRoot, 'apps', appName)}`);
+  console.log(`App "${appName}" created at ${resolvedRoot}/apps/${appName}`);
 }