adonia 0.1.0

package/build/wire.js

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const REQUIRED_IMPORTS = {
+    '#modules/*': './modules/*.js',
+    '#modules/types': './modules/types/index.js',
+    '#modules/contracts': './modules/contracts/index.js',
+    '#constants': './modules/constants/index.js',
+    '#constants/*': './modules/constants/*.js',
+    '#adapters/*': './app/adapters/*.js',
+};
+const EMPTY_MODULES_CONFIG = `const modulesConfig: Record<string, { description: string; emits: string[] }> = {}
+
+export default modulesConfig
+`;
+const EXCEPTION_HANDLER_REEXPORT = `export { default } from '#modules/api/exception_handler'
+`;
+export function printWireChecklist() {
+    console.log(`
+Host wiring checklist (run \`init --wire\` to apply automatically):
+  1. Merge #modules/*, #modules/types, #modules/contracts,
+     #constants, #constants/*, #adapters/* into package.json "imports".
+  2. Append () => import('#modules/api/provider') to adonisrc.ts providers.
+  3. Set server.errorHandler(() => import('#modules/api/exception_handler')) in start/kernel.ts.
+  4. Create app/exceptions/handler.ts re-export of #modules/api/exception_handler.
+  5. Create config/modules.ts with an empty Record if missing.
+`);
+}
+export function applyWire(cwd, dryRun = false) {
+    const actions = [];
+    actions.push(...mergePackageImports(cwd, dryRun));
+    actions.push(...ensureProvider(cwd, dryRun));
+    actions.push(...ensureErrorHandler(cwd, dryRun));
+    actions.push(...ensureExceptionHandlerFile(cwd, dryRun));
+    actions.push(...ensureModulesConfig(cwd, dryRun));
+    return actions;
+}
+function mergePackageImports(cwd, dryRun) {
+    const pkgPath = join(cwd, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    pkg.imports ??= {};
+    const added = [];
+    for (const [key, value] of Object.entries(REQUIRED_IMPORTS)) {
+        if (pkg.imports[key] === value)
+            continue;
+        if (!(key in pkg.imports)) {
+            pkg.imports[key] = value;
+            added.push(key);
+        }
+        else if (pkg.imports[key] !== value) {
+            // leave host override; only fill missing
+            continue;
+        }
+    }
+    if (added.length && !dryRun) {
+        writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+    return added.map((k) => `imports: ${k}`);
+}
+function ensureProvider(cwd, dryRun) {
+    const path = join(cwd, 'adonisrc.ts');
+    if (!existsSync(path))
+        return [];
+    let content = readFileSync(path, 'utf8');
+    if (content.includes('#modules/api/provider'))
+        return [];
+    const providerLine = `    () => import('#modules/api/provider'),`;
+    if (/providers:\s*\[/.test(content)) {
+        content = content.replace(/providers:\s*\[/, (m) => `${m}\n${providerLine}`);
+    }
+    else {
+        content += `\nexport const providers = [\n${providerLine}\n]\n`;
+    }
+    if (!dryRun)
+        writeFileSync(path, content);
+    return ['adonisrc.ts providers'];
+}
+function ensureErrorHandler(cwd, dryRun) {
+    const path = join(cwd, 'start/kernel.ts');
+    if (!existsSync(path)) {
+        if (!dryRun) {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, `import server from '@adonisjs/core/services/server'\n\nserver.errorHandler(() => import('#modules/api/exception_handler'))\n`);
+        }
+        return ['start/kernel.ts (created)'];
+    }
+    const original = readFileSync(path, 'utf8');
+    if (original.includes('#modules/api/exception_handler'))
+        return [];
+    // Decide before appending the errorHandler line — that line contains
+    // `server.` and would otherwise hide a missing import.
+    const needsServerImport = !original.includes("from '@adonisjs/core/services/server'") &&
+        !original.includes('server.');
+    let content = original + `\nserver.errorHandler(() => import('#modules/api/exception_handler'))\n`;
+    if (needsServerImport) {
+        content = `import server from '@adonisjs/core/services/server'\n${content}`;
+    }
+    if (!dryRun)
+        writeFileSync(path, content);
+    return ['start/kernel.ts errorHandler'];
+}
+function ensureExceptionHandlerFile(cwd, dryRun) {
+    const path = join(cwd, 'app/exceptions/handler.ts');
+    if (existsSync(path)) {
+        const content = readFileSync(path, 'utf8');
+        const isDefault = content.includes('@adonisjs/core/exceptions') ||
+            content.trim().length < 40 ||
+            /export default class HttpExceptionHandler/.test(content);
+        if (!isDefault && content.includes('#modules/api/exception_handler'))
+            return [];
+        if (!isDefault)
+            return [];
+    }
+    if (!dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, EXCEPTION_HANDLER_REEXPORT);
+    }
+    return ['app/exceptions/handler.ts'];
+}
+function ensureModulesConfig(cwd, dryRun) {
+    const path = join(cwd, 'config/modules.ts');
+    if (existsSync(path))
+        return [];
+    if (!dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, EMPTY_MODULES_CONFIG);
+    }
+    return ['config/modules.ts'];
+}
+export { REQUIRED_IMPORTS, EMPTY_MODULES_CONFIG };
+/**
+ * Append a side-effect import of `start/routes/<module>.ts` into
+ * `start/routes.ts`. Idempotent. Does not create the module route file.
+ */
+export function wireModuleRoute(cwd, moduleName, dryRun = false) {
+    const routeFile = join(cwd, 'start/routes', `${moduleName}.ts`);
+    if (!existsSync(routeFile)) {
+        return {
+            ok: false,
+            error: `Cannot --wire-routes for "${moduleName}": missing start/routes/${moduleName}.ts. ` +
+                `Pass --with-routes first, or create the file.`,
+        };
+    }
+    const routesPath = join(cwd, 'start/routes.ts');
+    const importRelative = `./routes/${moduleName}.js`;
+    const importLine = `import '${importRelative}'`;
+    let content = existsSync(routesPath) ? readFileSync(routesPath, 'utf8') : '';
+    if (content.includes(`'${importRelative}'`) ||
+        content.includes(`"${importRelative}"`) ||
+        content.includes(`'#start/routes/${moduleName}'`) ||
+        content.includes(`"#start/routes/${moduleName}"`)) {
+        return { ok: true, actions: [] };
+    }
+    content = content.length ? `${content.trimEnd()}\n${importLine}\n` : `${importLine}\n`;
+    if (!dryRun) {
+        mkdirSync(dirname(routesPath), { recursive: true });
+        writeFileSync(routesPath, content);
+    }
+    return {
+        ok: true,
+        actions: [`start/routes.ts → ${importRelative}`],
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "adonia",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Adonia modules for AdonisJS \u2014 CLI and bundled registry",
+  "bin": {
+    "adonia": "./build/cli.js"
+  },
+  "exports": {
+    ".": "./build/cli.js",
+    "./schema/adonia.schema.json": "./schema/adonia.schema.json"
+  },
+  "files": [
+    "build",
+    "schema",
+    "registry"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "sync-registry": "node --import tsx scripts/sync-registry.ts",
+    "prepack": "npm run sync-registry && npm run build",
+    "test": "npm run sync-registry && npm run build && node --import tsx --test tests/*.test.ts",
+    "adonia": "node build/cli.js"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "fast-glob": "^3.3.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/britzdylan/adonia.git",
+    "directory": "packages/modules"
+  },
+  "homepage": "https://github.com/britzdylan/adonia#readme",
+  "bugs": {
+    "url": "https://github.com/britzdylan/adonia/issues"
+  },
+  "license": "MIT"
+}

package/registry/README.md

@@ -0,0 +1,86 @@
+# Modules package (authoring fixture)
+
+This directory is the **authoring source** for Adonia modules. It lives
+inside a fixture Adonis app used to design and test slices. Hosts do
+**not** copy from here — they run:
+
+```bash
+npx adonia@latest init --wire
+npx adonia@latest add auth
+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
+```
+
+Local authors iterating on a module can point the CLI at this tree:
+
+```bash
+npx adonia add auth --registry .
+# or from the monorepo root:
+node packages/modules/build/cli.js add auth \
+  --registry apps/adonis-api-stater/modules
+```
+
+`npm run sync-registry -w adonia` copies this tree into
+`packages/modules/registry/` for the npm tarball.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `types/`, `constants/`, `contracts/` | Shared core (always copy with `api`) |
+| `api/` | Envelopes, `ApiService`, `ctx.respond`, exception handler |
+| `auth/`, `account/`, `notification/`, `creem/`, `subscription/` | Feature modules |
+
+Import path: `#modules/<name>/…` (for example `#modules/auth/service`).
+
+Public names are listed in `registry.json`.
+
+## `module.json` schema
+
+Each feature module (and `api`) ships a manifest:
+
+- **files** — domain slice copy set (relative to the module folder).
+- **stubs** — host files under `stubs/` (`models`, `migrations`,
+  `controllers`, `validators`, `adapters`, `providers`, `start`,
+  `routes`). Opt-in via CLI `--with-*` flags; plain `add` does not copy
+  them. `--with-adapters` copies Lucid/SDK adapters to `app/adapters/`.
+  `--with-controllers` and `--with-stubs` imply adapters. `--with-validators`
+  also copies `providers/`; `--with-routes` and `--with-stubs` also copy
+  `start/` (limiter example). Adonis kits (`@adonisjs/mail`,
+  `@adonisjs/drive`, `@adonisjs/limiter`) are not stubbed with no-ops.
+  `add` and `check` warn when a copied stub needs a kit that is missing
+  from `package.json` and print `node ace add @adonisjs/<pkg>`.
+- **dependencies** — npm packages this module imports.
+- **registryDependencies** — other modules that must already be present.
+- **peerModels** — `#models/*` aliases Lucid adapters expect.
+- **configKeys** — keys under `config/modules.ts`.
+- **env** — environment variables the host must provide.
+- **events** — names to list in `config/modules.ts` `emits`.
+- **hostFacingExceptions** — codes kept for middleware/hosts (see
+  `constants/exceptions.ts`).
+- **hostTests** — integration specs that stay in the host `tests/` tree.
+
+## Install checklist (manual / without CLI)
+
+Prefer `npx adonia`. If installing by hand:
+
+1. Aliases: `#modules/*`, `#modules/types`, `#constants`, `#adapters/*`.
+2. Copy `api` + `types` + `constants` + `contracts`.
+3. Register `#modules/api/provider` and `#modules/api/exception_handler`.
+4. Copy feature modules in `registryDependencies` order.
+5. Optionally copy stubs (`--with-stubs` / `--with-adapters` /
+   `--with-routes`) into `app/`, `app/adapters/`, `database/`,
+   `providers/`, `start/`, and `start/routes/`. Register
+   `providers/vine_provider.ts` in `adonisrc.ts`. If a copied stub
+   imports `@adonisjs/mail`, `@adonisjs/drive`, or `@adonisjs/limiter`,
+   run `node ace add` for that package (the CLI prints the command).
+6. Fill `config/modules.ts` from each module's `events` list.
+
+## Authoring a new module
+
+See [Adding a feature module](../../../docs/architecture/adding-modules.md)
+for the service API, contracts, events, stubs, and `module.json`
+checklist.

package/registry/account/contracts/avatar_storage.ts

@@ -0,0 +1,7 @@
+/**
+ * Optional avatar file cleanup. Host wires Drive / S3 / local disk.
+ * AccountService never imports Adonis Drive or MultipartFile.
+ */
+export interface AvatarStorage {
+  delete(key: string): Promise<void>
+}

package/registry/account/contracts/index.ts

@@ -0,0 +1,7 @@
+export type {
+  UpdateProfileInput,
+  ReplaceEmailInput,
+  ReplacePasswordInput,
+} from './types.ts'
+
+export type { AvatarStorage } from './avatar_storage.ts'

package/registry/account/contracts/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Account module input types.
+ * User persistence uses shared #modules/contracts UserStore / User.
+ */
+
+export type UpdateProfileInput = {
+  firstName?: string
+  lastName?: string
+  /**
+   * New avatar storage key after the host uploaded the file.
+   * Pass null to clear. Omit to leave unchanged.
+   */
+  avatarKey?: string | null
+}
+
+export type ReplaceEmailInput = {
+  email: string
+}
+
+export type ReplacePasswordInput = {
+  currentPassword: string
+  newPassword: string
+}

package/registry/account/events.ts

@@ -0,0 +1,14 @@
+/**
+ * Account module events. Import this file so the EventsList augmentation loads.
+ */
+import type { User } from '#modules/contracts/index'
+
+declare module '@adonisjs/core/types' {
+  interface EventsList {
+    'Account:UpdateUserProfile': User
+    'Account:UpdateUserEmail': { user: User; newEmail: string }
+    'Account:ConfirmEmailChange': User
+    'Account:UpdateUserPassword': User
+    'Account:DeleteAccount': { userId: number }
+  }
+}

package/registry/account/module.json

@@ -0,0 +1,31 @@
+{
+  "name": "account",
+  "description": "Authenticated profile, email change, password change, account deletion",
+  "files": [
+    "service.ts",
+    "events.ts",
+    "options.ts",
+    "contracts/**",
+    "module.json"
+  ],
+  "stubs": [
+    "stubs/controllers/account_controller.ts",
+    "stubs/validators/account.ts",
+    "stubs/adapters/**/*",
+    "stubs/routes/account.ts"
+  ],
+  "dependencies": {},
+  "registryDependencies": ["api", "auth"],
+  "peerModels": ["#models/user"],
+  "configKeys": ["modules.account"],
+  "env": ["APP_KEY"],
+  "events": [
+    "Account:UpdateUserProfile",
+    "Account:UpdateUserEmail",
+    "Account:ConfirmEmailChange",
+    "Account:UpdateUserPassword",
+    "Account:DeleteAccount"
+  ],
+  "hostFacingExceptions": ["PAYLOAD_TOO_LARGE"],
+  "hostTests": ["tests/integration/lucid_adapters.spec.ts"]
+}

package/registry/account/options.ts

@@ -0,0 +1,11 @@
+/**
+ * Host-editable defaults for AccountService.
+ */
+export type AccountOptions = {
+  /** Duration passed to encryption.encrypt for pending-email tokens. */
+  emailChangeTtl: string
+}
+
+export const defaultAccountOptions: AccountOptions = {
+  emailChangeTtl: '2 Hours',
+}

package/registry/account/service.ts

@@ -0,0 +1,155 @@
+/**
+ * AccountService
+ *
+ * Authenticated account actions: profile, email, password, delete.
+ * Returns DTOs / void; controllers build HTTP envelopes.
+ */
+import encryption from '@adonisjs/core/services/encryption'
+import ApiService from '#modules/api/service'
+import ApiException from '#modules/api/exception'
+import { exceptions } from '#constants/exceptions'
+import type { User, UserStore } from '#modules/contracts/index'
+import type {
+  AvatarStorage,
+  ReplaceEmailInput,
+  ReplacePasswordInput,
+  UpdateProfileInput,
+} from '#modules/account/contracts/index'
+import { defaultAccountOptions, type AccountOptions } from '#modules/account/options'
+import '#modules/account/events'
+
+const noopAvatars: AvatarStorage = {
+  async delete() {},
+}
+
+export class AccountService extends ApiService {
+  namespace = 'account'
+
+  constructor(
+    private users: UserStore,
+    private avatars: AvatarStorage = noopAvatars,
+    private options: AccountOptions = defaultAccountOptions
+  ) {
+    super()
+  }
+
+  private invalidTokenException() {
+    return ApiException.from(exceptions.INVALID_TOKEN)
+  }
+
+  private tokensMatch(incoming: string, stored: string): boolean {
+    const storedToken = encryption.decrypt(stored)
+    return encryption.decrypt(incoming) === storedToken && storedToken != null
+  }
+
+  private issuePendingEmailToken(user: User, pendingEmail: string): User {
+    return {
+      ...user,
+      pendingEmail,
+      emailVerificationToken: encryption.encrypt(pendingEmail, this.options.emailChangeTtl),
+    }
+  }
+
+  public async updateProfile(userId: number, data: UpdateProfileInput): Promise<User> {
+    const user = await this.users.findOrFail(userId)
+    const previousAvatarKey = user.avatarKey
+
+    if (data.firstName !== undefined) {
+      user.firstName = data.firstName
+    }
+    if (data.lastName !== undefined) {
+      user.lastName = data.lastName
+    }
+    if (data.avatarKey !== undefined) {
+      user.avatarKey = data.avatarKey
+    }
+
+    const saved = await this.users.save(user)
+
+    if (
+      data.avatarKey !== undefined &&
+      previousAvatarKey &&
+      previousAvatarKey !== data.avatarKey
+    ) {
+      await this.avatars.delete(previousAvatarKey)
+    }
+
+    this.emitSafe('Account:UpdateUserProfile', saved)
+    return saved
+  }
+
+  /**
+   * Stages a new email on pendingEmail. Current email stays valid until
+   * confirmEmailChange succeeds.
+   */
+  public async replaceEmail(userId: number, data: ReplaceEmailInput): Promise<User> {
+    const user = await this.users.findOrFail(userId)
+
+    if (user.email === data.email) {
+      throw ApiException.from(exceptions.SAME_EMAIL)
+    }
+
+    const existing = await this.users.findByEmail(data.email)
+    if (existing) {
+      throw ApiException.from(exceptions.EMAIL_EXISTS)
+    }
+
+    const updated = await this.users.save(this.issuePendingEmailToken(user, data.email))
+
+    this.emitSafe('Account:UpdateUserEmail', {
+      user: updated,
+      newEmail: data.email,
+    })
+
+    return updated
+  }
+
+  /**
+   * Confirms a pending email change using the verification token.
+   */
+  public async confirmEmailChange(token: string): Promise<User> {
+    const user = await this.users.findByVerificationToken(token)
+    if (!user || !user.pendingEmail) {
+      throw this.invalidTokenException()
+    }
+    if (!user.emailVerificationToken || !this.tokensMatch(token, user.emailVerificationToken)) {
+      throw this.invalidTokenException()
+    }
+
+    const taken = await this.users.findByEmail(user.pendingEmail)
+    if (taken && taken.id !== user.id) {
+      throw ApiException.from(exceptions.EMAIL_EXISTS)
+    }
+
+    const confirmed = await this.users.save({
+      ...user,
+      email: user.pendingEmail,
+      pendingEmail: null,
+      emailVerifiedAt: new Date(),
+      emailVerificationToken: null,
+    })
+
+    this.emitSafe('Account:ConfirmEmailChange', confirmed)
+    return confirmed
+  }
+
+  public async replacePassword(userId: number, data: ReplacePasswordInput): Promise<void> {
+    const user = await this.users.findOrFail(userId)
+    const valid = await this.users.verifyPassword(userId, data.currentPassword)
+    if (!valid) {
+      throw ApiException.from(exceptions.INVALID_PASSWORD)
+    }
+
+    await this.users.updatePassword(user, data.newPassword)
+    this.emitSafe('Account:UpdateUserPassword', user)
+  }
+
+  public async deleteAccount(userId: number): Promise<void> {
+    const user = await this.users.findOrFail(userId)
+    if (user.avatarKey) {
+      await this.avatars.delete(user.avatarKey)
+    }
+    await this.users.delete(userId)
+    this.emitSafe('Account:DeleteAccount', { userId })
+  }
+}

package/registry/account/stubs/adapters/account.ts

@@ -0,0 +1,21 @@
+/**
+ * Host Lucid factory for account. Copied to app/adapters/account.ts.
+ * Import as `#adapters/account`.
+ *
+ * Reuses `#adapters/lucid_user_store` from the auth adapter stubs.
+ * Avatar cleanup uses Drive (`node ace add @adonisjs/drive`).
+ */
+import { AccountService } from '#modules/account/service'
+import { LucidUserStore } from '#adapters/lucid_user_store'
+import { DriveAvatarStorage } from './drive_avatar_storage.ts'
+import { defaultAccountOptions, type AccountOptions } from '#modules/account/options'
+import type { AvatarStorage } from '#modules/account/contracts/index'
+
+export { DriveAvatarStorage } from './drive_avatar_storage.ts'
+
+export function createAccountService(
+  avatars: AvatarStorage = new DriveAvatarStorage(),
+  options: AccountOptions = defaultAccountOptions
+) {
+  return new AccountService(new LucidUserStore(), avatars, options)
+}

package/registry/account/stubs/adapters/drive_avatar_storage.ts

@@ -0,0 +1,15 @@
+/**
+ * Drive-backed AvatarStorage. Copied to app/adapters/drive_avatar_storage.ts.
+ * Requires `@adonisjs/drive` (`node ace add @adonisjs/drive`).
+ */
+import drive from '@adonisjs/drive/services/main'
+import type { AvatarStorage } from '#modules/account/contracts/index'
+
+export class DriveAvatarStorage implements AvatarStorage {
+  constructor(private diskName?: string) {}
+
+  async delete(key: string): Promise<void> {
+    const disk = this.diskName ? drive.use(this.diskName) : drive.use()
+    await disk.delete(key)
+  }
+}