adonia 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# `@adonia` CLI (`packages/modules`)
+
+npm package name: `adonia`. Bin: `adonia`.
+
+In this monorepo, module sources are authored in
+`apps/adonis-api-stater/modules/`. Sync before pack/test:
+
+```bash
+npm run sync-registry -w adonia
+npm test -w adonia
+```
+
+## Host install
+
+```bash
+npx adonia@latest init --wire
+npx adonia@latest add auth
+# optional host scaffolding:
+npx adonia@latest add auth --with-adapters
+npx adonia@latest add auth --with-stubs
+npx adonia@latest add auth --with-routes --wire-routes
+# or full kit:
+npx adonia@latest init --scaffold
+```
+
+## Commands
+
+| Command | Role |
+|---------|------|
+| `init` / `init --wire` | `adonia.json` + core; optional host wiring |
+| `init --scaffold` | Core + all feature modules with stubs and routes (implies `--wire`) |
+| `add [names…]` | Copy module files under `modules/`, merge config (no app stubs by default) |
+| `list` / `diff` / `check` | Discovery, drift, validation |
+
+### `add` scaffolding flags
+
+| Flag | Effect |
+|------|--------|
+| `--with-models` | Copy `stubs/models/**` |
+| `--with-migrations` | Copy `stubs/migrations/**` |
+| `--with-controllers` | Copy `stubs/controllers/**` (implies `--with-adapters`) |
+| `--with-validators` | Copy `stubs/validators/**` and `stubs/providers/**` |
+| `--with-adapters` | Copy Lucid/SDK adapters → `app/adapters/` |
+| `--with-stubs` | Models, migrations, controllers, validators, adapters, Vine provider, limiter stub (not routes) |
+| `--with-routes` | Copy `stubs/routes/**` → `start/routes/` and `stubs/start/**` → `start/` |
+| `--wire-routes` | Append `import './routes/<name>.js'` in `start/routes.ts` |
+| `--with-tests` | Copy colocated module tests |
+
+`diff` accepts the same `--with-*` flags; without them it diffs the
+module tree only.
+
+Adonis kits used by stubs (`@adonisjs/mail`, `@adonisjs/drive`,
+`@adonisjs/limiter`) are not installed by `adonia add`. The CLI assumes
+they are already configured, or `add` / `check` prints
+`node ace add @adonisjs/<pkg>`.
+
+Shared flags: `--yes`, `--dry-run`, `--cwd`, `--registry`, `--overwrite`.
+
+## Developing in the monorepo
+
+```bash
+node packages/modules/build/cli.js add auth \
+  --registry apps/adonis-api-stater/modules
+```

package/build/adonis_peers.d.ts

@@ -0,0 +1,14 @@
+export interface AdonisPeer {
+    pkg: string;
+    reason: string;
+    /** Host-relative path that means this Adonis kit is actually in use. */
+    whenFile?: string;
+}
+/** Adonis kits we assume are configured, or we tell the host to `ace add`. */
+export declare const ADONIS_PEERS: Record<string, AdonisPeer[]>;
+export declare function hostPackageNames(cwd: string): Set<string>;
+export declare function missingAdonisPeers(cwd: string, moduleName: string, opts?: {
+    plannedFiles?: Iterable<string>;
+}): AdonisPeer[];
+export declare function aceAddHint(pkg: string): string;
+export declare function formatMissingPeer(peer: AdonisPeer): string;

package/build/adonis_peers.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Adonis kits we assume are configured, or we tell the host to `ace add`. */
+export const ADONIS_PEERS = {
+    auth: [
+        {
+            pkg: '@adonisjs/limiter',
+            reason: 'rate-limit auth routes',
+            whenFile: 'start/limiter.ts',
+        },
+    ],
+    account: [
+        {
+            pkg: '@adonisjs/drive',
+            reason: 'avatar file cleanup',
+            whenFile: 'app/adapters/drive_avatar_storage.ts',
+        },
+    ],
+    notification: [
+        {
+            pkg: '@adonisjs/mail',
+            reason: 'email notification channel',
+            whenFile: 'app/adapters/adonis_mail_transport.ts',
+        },
+    ],
+};
+export function hostPackageNames(cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return new Set();
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    return new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+}
+export function missingAdonisPeers(cwd, moduleName, opts) {
+    const have = hostPackageNames(cwd);
+    const planned = new Set(opts?.plannedFiles ?? []);
+    return (ADONIS_PEERS[moduleName] ?? []).filter((peer) => {
+        if (have.has(peer.pkg))
+            return false;
+        if (peer.whenFile) {
+            const dest = join(cwd, peer.whenFile);
+            if (!planned.has(dest) && !existsSync(dest))
+                return false;
+        }
+        return true;
+    });
+}
+export function aceAddHint(pkg) {
+    return `node ace add ${pkg}`;
+}
+export function formatMissingPeer(peer) {
+    return `Missing ${peer.pkg} (${peer.reason}). Run: ${aceAddHint(peer.pkg)}`;
+}

package/build/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import { runAdd } from './commands/add.js';
+import { runCheck } from './commands/check.js';
+import { runDiff } from './commands/diff.js';
+import { runInit } from './commands/init.js';
+import { runList } from './commands/list.js';
+import { packageVersion } from './host.js';
+const program = new Command();
+program
+    .name('adonia')
+    .description('Adonia modules for AdonisJS')
+    .version(packageVersion());
+function shared(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        cwd: resolve(opts.cwd ?? process.cwd()),
+        yes: Boolean(opts.yes),
+        dryRun: Boolean(opts.dryRun),
+        registry: opts.registry,
+        overwrite: Boolean(opts.overwrite),
+    };
+}
+function scaffoldFromOpts(opts) {
+    return {
+        withModels: Boolean(opts.withModels),
+        withMigrations: Boolean(opts.withMigrations),
+        withControllers: Boolean(opts.withControllers),
+        withValidators: Boolean(opts.withValidators),
+        withAdapters: Boolean(opts.withAdapters),
+        withStubs: Boolean(opts.withStubs),
+        withRoutes: Boolean(opts.withRoutes),
+        wireRoutes: Boolean(opts.wireRoutes),
+        withTests: Boolean(opts.withTests),
+    };
+}
+function addScaffoldOptions(cmd) {
+    return cmd
+        .option('--with-models', 'copy stubs/models into the host', false)
+        .option('--with-migrations', 'copy stubs/migrations into the host', false)
+        .option('--with-controllers', 'copy stubs/controllers (implies --with-adapters)', false)
+        .option('--with-validators', 'copy stubs/validators and Vine provider into the host', false)
+        .option('--with-adapters', 'copy Lucid/SDK adapters into app/adapters/', false)
+        .option('--with-stubs', 'copy models, migrations, controllers, validators, adapters, Vine provider, and limiter stub', false)
+        .option('--with-routes', 'copy stubs/routes and start/limiter into the host', false)
+        .option('--wire-routes', 'append imports in start/routes.ts for module route files', false)
+        .option('--with-tests', 'copy colocated module tests', false);
+}
+program
+    .option('--cwd <dir>', 'host app directory', process.cwd())
+    .option('-y, --yes', 'skip prompts', false)
+    .option('--dry-run', 'print plan without writing', false)
+    .option('--registry <dir>', 'local registry path (fixture testing)')
+    .option('--overwrite', 'replace differing host files', false);
+program
+    .command('init')
+    .description('Write adonia.json and install shared API core')
+    .option('--wire', 'apply host aliases / provider / exception handler', false)
+    .option('--skip-core', 'do not copy api + core packages', false)
+    .option('--scaffold', 'install all feature modules with stubs + routes (implies --wire)', false)
+    .action(async (_args, cmd) => {
+    const flags = shared(cmd);
+    const opts = cmd.opts();
+    await runInit({
+        ...flags,
+        wire: Boolean(opts.wire),
+        skipCore: Boolean(opts.skipCore),
+        scaffold: Boolean(opts.scaffold),
+    });
+});
+addScaffoldOptions(program
+    .command('add')
+    .description('Add one or more modules from the registry')
+    .argument('[names...]', 'module names')
+    .option('--overwrite', 'replace differing host files', false)).action(async (names, _opts, cmd) => {
+    const flags = shared(cmd);
+    const opts = cmd.opts();
+    await runAdd(names, {
+        ...flags,
+        overwrite: flags.overwrite || Boolean(opts.overwrite),
+        ...scaffoldFromOpts(opts),
+    });
+});
+program
+    .command('list')
+    .description('List registry modules and install status')
+    .action(async (_args, cmd) => {
+    await runList(shared(cmd));
+});
+addScaffoldOptions(program
+    .command('diff')
+    .description('Diff host files against the registry (module files; stubs only with --with-*)')
+    .argument('[name]', 'module name')).action(async (name, _opts, cmd) => {
+    const flags = shared(cmd);
+    const opts = cmd.opts();
+    await runDiff(name, { ...flags, ...scaffoldFromOpts(opts) });
+});
+program
+    .command('check')
+    .description('Validate host modules install')
+    .option('--strict', 'treat warnings as failures', false)
+    .action(async (_args, cmd) => {
+    const flags = shared(cmd);
+    const opts = cmd.opts();
+    await runCheck({ ...flags, strict: Boolean(opts.strict) });
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exitCode = 1;
+});

package/build/commands/add.d.ts

@@ -0,0 +1,18 @@
+import { type Registry } from '../registry/index.js';
+import { type PlannedCopy } from '../registry/plan.js';
+import type { HostModulesConfig } from '../schema.js';
+import type { ScaffoldFlags, SharedFlags } from '../types.js';
+export interface AddFlags extends SharedFlags, ScaffoldFlags {
+    /** Hide the post-install next-steps footer (used by init core). */
+    suppressNextSteps?: boolean;
+}
+export declare function runAdd(names: string[], flags: AddFlags): Promise<void>;
+export declare function installModules(opts: {
+    names: string[];
+    flags: AddFlags;
+    config: HostModulesConfig;
+    registry: Registry;
+}): Promise<{
+    conflicts: PlannedCopy[];
+    wireErrors: string[];
+}>;

package/build/commands/add.js

@@ -0,0 +1,246 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mergeModulesConfig } from '../config_merge.js';
+import { mergeConstantsCatalogs } from '../constants_merge.js';
+import { detectPackageManager, loadHostConfig, writeHostConfig } from '../host.js';
+import { expandDependencies, loadManifest, moduleDir, resolveRegistry, } from '../registry/index.js';
+import { anyAppStubsSelected, describePlan, executePlan, hostRouteFile, manifestHasRouteStubs, planModuleFiles, planStubs, planTests, resolveStubSelect, } from '../registry/plan.js';
+import { formatMissingPeer, missingAdonisPeers } from '../adonis_peers.js';
+import { wireModuleRoute } from '../wire.js';
+export async function runAdd(names, flags) {
+    if (!names.length) {
+        console.error('Usage: adonia add <name…>');
+        process.exitCode = 1;
+        return;
+    }
+    let config;
+    try {
+        config = loadHostConfig(flags.cwd);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    let registry;
+    try {
+        registry = await resolveRegistry({
+            registryFlag: flags.registry,
+            hostRegistry: config.registry,
+            ref: config.ref,
+            cwd: flags.cwd,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    let ordered;
+    try {
+        ordered = expandDependencies(registry, names, new Set(config.installed), flags.overwrite);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    if (!ordered.length) {
+        console.log('Nothing to install (already in adonia.json installed). Use --overwrite to recopy.');
+        return;
+    }
+    console.log(`Plan: ${ordered.join(' → ')}`);
+    if (!flags.yes && !flags.dryRun) {
+        console.log('(continuing; pass --yes to silence)');
+    }
+    const result = await installModules({ names: ordered, flags, config, registry });
+    if (result.conflicts.length) {
+        console.error('\nConflicts (use --overwrite to replace). Not recorded in adonia.json\n' +
+            'installed until all planned files for the module copy cleanly.');
+        for (const c of result.conflicts) {
+            console.error(`  ${describePlan(c, flags.cwd)}`);
+        }
+        process.exitCode = 1;
+    }
+    if (result.wireErrors.length) {
+        for (const e of result.wireErrors)
+            console.error(e);
+        process.exitCode = 1;
+    }
+}
+export async function installModules(opts) {
+    const { names, flags, registry } = opts;
+    let config = opts.config;
+    const allConflicts = [];
+    const wireErrors = [];
+    const warnings = [];
+    const npmDeps = new Map();
+    const plannedDests = new Set();
+    const stubSelect = resolveStubSelect(flags);
+    const requestedNames = new Set(names);
+    for (const name of names) {
+        const manifest = loadManifest(registry, name);
+        const plans = [];
+        plans.push(...planModuleFiles(registry, name, manifest, config, flags.cwd));
+        if (stubSelect) {
+            plans.push(...planStubs(registry, name, manifest, config, flags.cwd, warnings, stubSelect));
+        }
+        if (flags.withTests) {
+            plans.push(...planTests(registry, name, config, flags.cwd));
+        }
+        for (const p of plans)
+            plannedDests.add(p.dest);
+        if (flags.dryRun) {
+            for (const p of plans) {
+                console.log(`would process ${describePlan(p, flags.cwd)}`);
+            }
+        }
+        const { results, conflicts: moduleConflicts } = executePlan(plans, {
+            overwrite: flags.overwrite,
+            dryRun: flags.dryRun,
+        });
+        allConflicts.push(...moduleConflicts);
+        for (const { plan, result } of results) {
+            if (result === 'copied' || result === 'would-copy') {
+                console.log(`${result}: ${describePlan(plan, flags.cwd)}`);
+            }
+        }
+        for (const [pkg, version] of Object.entries(manifest.dependencies)) {
+            npmDeps.set(pkg, version);
+        }
+        // Constants merge after core is present: re-merge registry constants into host
+        if (name !== 'constants' && !flags.dryRun) {
+            const hostConstants = join(flags.cwd, config.paths.modules, 'constants');
+            const regConstants = join(moduleDir(registry, 'constants'));
+            if (existsSync(hostConstants) && existsSync(regConstants)) {
+                warnings.push(...mergeConstantsCatalogs(regConstants, hostConstants, flags.dryRun));
+            }
+        }
+        // Merge config/modules.ts for feature modules with events
+        if (manifest.events.length &&
+            name !== 'api' &&
+            !['types', 'constants', 'contracts'].includes(name)) {
+            const configPath = join(flags.cwd, 'config/modules.ts');
+            const merged = mergeModulesConfig(configPath, name, manifest.description, manifest.events, flags.dryRun);
+            if (!merged.ok) {
+                console.warn(`Could not merge config/modules.ts for ${name}. Add manually:\n${merged.snippet}`);
+            }
+            else {
+                console.log(`${flags.dryRun ? 'Would update' : 'Updated'} config/modules.ts (${name})`);
+            }
+        }
+        // Env hints
+        if (manifest.env.length) {
+            const missing = missingEnvKeys(flags.cwd, manifest.env);
+            if (missing.length) {
+                console.log(`Missing env keys for ${name} (not written): ${missing.join(', ')}`);
+            }
+        }
+        if (flags.wireRoutes && manifestHasRouteStubs(manifest)) {
+            const routeDest = hostRouteFile(flags.cwd, name);
+            const plannedRoute = plans.some((p) => p.dest === routeDest);
+            const haveRoute = existsSync(routeDest) || plannedRoute;
+            if (!haveRoute) {
+                wireErrors.push(`Cannot --wire-routes for "${name}": missing start/routes/${name}.ts. ` +
+                    `Pass --with-routes first, or create the file.`);
+            }
+            else if (flags.dryRun && !existsSync(routeDest)) {
+                console.log(`Would wire routes: start/routes.ts → ./routes/${name}.js`);
+            }
+            else {
+                const wired = wireModuleRoute(flags.cwd, name, flags.dryRun);
+                if (!wired.ok) {
+                    wireErrors.push(wired.error);
+                }
+                else if (wired.actions.length) {
+                    console.log(`${flags.dryRun ? 'Would wire' : 'Wired'} routes: ${wired.actions.join(', ')}`);
+                }
+            }
+        }
+        if (!flags.dryRun && moduleConflicts.length === 0 && !config.installed.includes(name)) {
+            config = {
+                ...config,
+                installed: [...config.installed, name],
+            };
+        }
+    }
+    if (!flags.dryRun) {
+        writeHostConfig(flags.cwd, config);
+    }
+    if (npmDeps.size && !flags.dryRun) {
+        installNpmDeps(flags.cwd, npmDeps);
+    }
+    else if (npmDeps.size && flags.dryRun) {
+        console.log(`Would install npm deps: ${[...npmDeps.keys()].join(', ')}`);
+    }
+    for (const name of names) {
+        for (const peer of missingAdonisPeers(flags.cwd, name, { plannedFiles: plannedDests })) {
+            warnings.push(formatMissingPeer(peer));
+        }
+    }
+    for (const w of warnings) {
+        if (w)
+            console.warn(w);
+    }
+    printNextSteps(flags, stubSelect, [...requestedNames][0] ?? 'auth');
+    return { conflicts: allConflicts, wireErrors };
+}
+function printNextSteps(flags, stubSelect, exampleName) {
+    if (flags.suppressNextSteps)
+        return;
+    console.log('\nNext steps (not run by the CLI):');
+    if (!anyAppStubsSelected(stubSelect) && !stubSelect?.routes) {
+        console.log('Models/migrations/controllers/validators/adapters/routes were not copied.');
+        console.log(`  adonia add ${exampleName} --with-stubs`);
+        console.log(`  adonia add ${exampleName} --with-adapters`);
+        console.log(`  adonia add ${exampleName} --with-routes --wire-routes`);
+    }
+    else {
+        if (stubSelect?.routes && !flags.wireRoutes) {
+            console.log(`  adonia add ${exampleName} --wire-routes  # mount start/routes/${exampleName}.ts`);
+        }
+        if (stubSelect?.providers) {
+            console.log('  Register providers/vine_provider.ts in adonisrc.ts providers.');
+        }
+        if (stubSelect?.start) {
+            console.log('  After limiter is installed, uncomment .use(authLimiter) / .use(accountLimiter) on sensitive routes.');
+        }
+        console.log('  1. Run migrations: node ace migration:run');
+        console.log('  2. Listen for module events as needed');
+    }
+}
+function missingEnvKeys(cwd, keys) {
+    const sources = [];
+    for (const f of ['.env', '.env.example', 'start/env.ts']) {
+        const p = join(cwd, f);
+        if (existsSync(p))
+            sources.push(readFileSync(p, 'utf8'));
+    }
+    const blob = sources.join('\n');
+    return keys.filter((k) => !blob.includes(k));
+}
+function installNpmDeps(cwd, deps) {
+    const pkgPath = join(cwd, 'package.json');
+    if (!existsSync(pkgPath))
+        return;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const have = { ...pkg.dependencies, ...pkg.devDependencies };
+    const missing = [...deps.entries()].filter(([name]) => !have[name]);
+    if (!missing.length) {
+        console.log('npm dependencies already satisfied.');
+        return;
+    }
+    const pm = detectPackageManager(cwd);
+    const specs = missing.map(([name, version]) => `${name}@${version}`);
+    console.log(`Installing with ${pm}: ${specs.join(' ')}`);
+    const args = pm === 'yarn'
+        ? ['add', ...specs]
+        : pm === 'pnpm'
+            ? ['add', ...specs]
+            : ['install', ...specs];
+    const result = spawnSync(pm, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' });
+    if (result.status !== 0) {
+        console.warn(`Package install exited ${result.status}; install manually: ${specs.join(' ')}`);
+    }
+}

package/build/commands/check.d.ts

@@ -0,0 +1,4 @@
+import type { SharedFlags } from '../types.js';
+export declare function runCheck(flags: SharedFlags & {
+    strict?: boolean;
+}): Promise<void>;

package/build/commands/check.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { formatMissingPeer, missingAdonisPeers } from '../adonis_peers.js';
+import { loadHostConfig } from '../host.js';
+import { loadManifest, resolveRegistry } from '../registry/index.js';
+import { CORE_PACKAGES } from '../schema.js';
+import { REQUIRED_IMPORTS } from '../wire.js';
+// Reserved manifest fields (not checked yet): hostTests, hostFacingExceptions.
+export async function runCheck(flags) {
+    let config;
+    try {
+        config = loadHostConfig(flags.cwd);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    const errors = [];
+    const warnings = [];
+    const installed = new Set(config.installed);
+    for (const [key, rel] of Object.entries(config.paths)) {
+        const p = join(flags.cwd, rel);
+        if (!existsSync(p)) {
+            // paths may not exist until first add — warn for empty dirs
+            warnings.push(`path.${key} missing: ${rel}`);
+        }
+    }
+    let registry;
+    try {
+        registry = await resolveRegistry({
+            registryFlag: flags.registry,
+            hostRegistry: config.registry,
+            ref: config.ref,
+            cwd: flags.cwd,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exitCode = 1;
+        return;
+    }
+    for (const name of config.installed) {
+        const folder = join(flags.cwd, config.paths.modules, name);
+        if (!existsSync(folder)) {
+            errors.push(`installed module folder missing: ${folder}`);
+            continue;
+        }
+        const manifestPath = join(folder, 'module.json');
+        if (existsSync(manifestPath)) {
+            try {
+                const local = JSON.parse(readFileSync(manifestPath, 'utf8'));
+                if (local.name && local.name !== name) {
+                    errors.push(`module.json name mismatch in ${name}: ${local.name}`);
+                }
+            }
+            catch {
+                warnings.push(`could not parse ${manifestPath}`);
+            }
+        }
+        try {
+            const manifest = loadManifest(registry, name);
+            const requiredDeps = [...manifest.registryDependencies];
+            if (name === 'api') {
+                for (const core of CORE_PACKAGES) {
+                    if (!requiredDeps.includes(core))
+                        requiredDeps.push(core);
+                }
+            }
+            for (const dep of requiredDeps) {
+                if (!installed.has(dep)) {
+                    errors.push(`installed module "${name}" requires "${dep}" (not in adonia.json installed)`);
+                }
+            }
+            for (const peer of manifest.peerModels) {
+                const file = peerModelToPath(peer, config.paths.models, flags.cwd);
+                if (!existsSync(file)) {
+                    errors.push(`peerModel missing: ${peer} → ${file}`);
+                }
+            }
+            if (manifest.events.length) {
+                const configPath = join(flags.cwd, 'config/modules.ts');
+                if (!existsSync(configPath)) {
+                    warnings.push(`config/modules.ts missing (events for ${name})`);
+                }
+                else {
+                    const text = readFileSync(configPath, 'utf8');
+                    for (const ev of manifest.events) {
+                        if (!text.includes(ev)) {
+                            warnings.push(`config/modules.ts missing event ${ev} for ${name}`);
+                        }
+                    }
+                }
+            }
+            for (const peer of missingAdonisPeers(flags.cwd, name)) {
+                warnings.push(formatMissingPeer(peer));
+            }
+            if (manifest.configKeys.length) {
+                const configPath = join(flags.cwd, 'config/modules.ts');
+                if (!existsSync(configPath)) {
+                    warnings.push(`config/modules.ts missing (configKeys for ${name})`);
+                }
+                else {
+                    const text = readFileSync(configPath, 'utf8');
+                    for (const key of manifest.configKeys) {
+                        const leaf = key.includes('.') ? key.slice(key.lastIndexOf('.') + 1) : key;
+                        if (!hasConfigKey(text, leaf)) {
+                            warnings.push(`config/modules.ts missing key ${leaf} (${key}) for ${name}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            warnings.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    // aliases
+    const pkgPath = join(flags.cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const imports = pkg.imports ?? {};
+        for (const key of Object.keys(REQUIRED_IMPORTS)) {
+            if (!(key in imports)) {
+                warnings.push(`package.json imports missing ${key}`);
+            }
+        }
+    }
+    const adonisrc = join(flags.cwd, 'adonisrc.ts');
+    if (existsSync(adonisrc) && !readFileSync(adonisrc, 'utf8').includes('#modules/api/provider')) {
+        warnings.push('adonisrc.ts missing #modules/api/provider (run init --wire)');
+    }
+    const kernel = join(flags.cwd, 'start/kernel.ts');
+    if (existsSync(kernel) && !readFileSync(kernel, 'utf8').includes('#modules/api/exception_handler')) {
+        warnings.push('start/kernel.ts missing exception_handler (run init --wire)');
+    }
+    for (const w of warnings)
+        console.warn(`warn: ${w}`);
+    for (const e of errors)
+        console.error(`error: ${e}`);
+    if (errors.length)
+        process.exitCode = 1;
+    else if (flags.strict && warnings.length)
+        process.exitCode = 1;
+    else if (!errors.length)
+        console.log('check passed' + (warnings.length ? ` (${warnings.length} warnings)` : ''));
+}
+function hasConfigKey(text, leaf) {
+    const re = new RegExp(`\\b${escapeRegExp(leaf)}\\s*:`);
+    return re.test(text);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function peerModelToPath(alias, modelsPath, cwd) {
+    // #models/user → app/models/user.ts
+    const name = alias.replace(/^#models\//, '');
+    return join(cwd, modelsPath, `${name}.ts`);
+}

package/build/commands/diff.d.ts

@@ -0,0 +1,2 @@
+import type { ScaffoldFlags, SharedFlags } from '../types.js';
+export declare function runDiff(name: string | undefined, flags: SharedFlags & ScaffoldFlags): Promise<void>;