adonia 0.1.0 → 0.2.0

package/README.md

@@ -1,64 +1,110 @@
-# `@adonia` CLI (`packages/modules`)
+# adonia
 
-npm package name: `adonia`. Bin: `adonia`.
+Your AdonisJS app owns the files. Adonia only copies them in.
 
-In this monorepo, module sources are authored in
-`apps/adonis-api-stater/modules/`. Sync before pack/test:
+**Requirements:** Node.js 24+, npm 11+, an AdonisJS app (`adonisrc.ts` and
+`@adonisjs/core`).
 
 ```bash
-npm run sync-registry -w adonia
-npm test -w adonia
+npx adonia@latest init --wire
+npx adonia@latest add auth
 ```
 
-## Host install
+## Quick start
+
+From an AdonisJS API app:
 
 ```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
+npx adonia init --wire
+npx adonia add auth
+npx adonia add auth --with-adapters
+npx adonia add auth --with-routes --wire-routes
+npx adonia check
+```
+
+Plain `add` copies the domain slice under `modules/` only. Models,
+migrations, controllers, validators, adapters, and routes are
+opt-in.
+
+Every module in one command:
+
+```bash
+npx adonia init --scaffold
 ```
 
+That wires the host and copies every feature module with stubs and
+routes.
+
 ## Commands
 
 | Command | Role |
 |---------|------|
-| `init` / `init --wire` | `adonia.json` + core; optional host wiring |
+| `init` | Write `adonia.json` and copy the API core |
+| `init --wire` | Also set import aliases, `ctx.respond`, and the JSON exception handler |
 | `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 <name…>` | Copy one or more modules (and optional stubs) |
+| `list` | Registry names and install status |
+| `diff <name>` | Compare host files to the registry |
+| `check` | Validate the host install |
 
-### `add` scaffolding flags
+`check` fails after a plain `add auth` until `#models/user` and
+`#models/password_reset` exist. Pass `--with-models` / `--with-stubs`,
+or add those files yourself.
 
-| Flag | Effect |
+## Bundled modules
+
+| Name | Role |
+|------|------|
+| `api` | Shared envelopes, `ApiService`, `ctx.respond`, exception handler |
+| `types`, `constants`, `contracts` | Core types and the shared `UserStore` port (installed with `api`) |
+| `auth` | Registration, login, verification, password reset |
+| `account` | Profile, email change, password change, deletion |
+| `notification` | Multi-channel dispatcher with a host-owned registry |
+| `creem` | Creem checkout, portal, invoices, webhooks |
+| `subscription` | Subscription state synced from Creem webhooks |
+
+`add` walks `registryDependencies`. For example,
+`adonia add subscription` installs `creem` and core first when they
+are missing.
+
+## `add` flags
+
+| Flag | Copies |
 |------|--------|
-| `--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 |
+| `--with-models` | `stubs/models/` → `app/models/` |
+| `--with-migrations` | `stubs/migrations/` → `database/migrations/` |
+| `--with-controllers` | Controllers (implies adapters) |
+| `--with-validators` | Validators and the Vine provider |
+| `--with-adapters` | Lucid/SDK adapters → `app/adapters/` |
+| `--with-stubs` | Models, migrations, controllers, validators, adapters, Vine provider, limiter stub. **Not** routes |
+| `--with-routes` | `start/routes/<name>.ts` and `start/limiter.ts` |
+| `--wire-routes` | Import that route file from `start/routes.ts` |
+| `--with-tests` | Colocated tests under `modules/<name>/tests/` |
 
-`diff` accepts the same `--with-*` flags; without them it diffs the
-module tree only.
+`--with-stubs` does not copy routes. Combine with `--with-routes`.
 
-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>`.
+Adonis packages used by stubs (`@adonisjs/mail`, `@adonisjs/drive`,
+`@adonisjs/limiter`) are not installed for you. `add` and `check`
+print `node ace add @adonisjs/<pkg>` when a copied stub needs a
+missing package.
 
-Shared flags: `--yes`, `--dry-run`, `--cwd`, `--registry`, `--overwrite`.
+## Shared flags
 
-## Developing in the monorepo
+| Flag | Effect |
+|------|--------|
+| `--cwd <dir>` | Host app directory |
+| `-y`, `--yes` | Hide “continuing” log lines (does not prompt) |
+| `--dry-run` | Print the plan; write nothing |
+| `--registry <dir>` | Local registry path |
+| `--overwrite` | Replace host files whose contents differ |
 
-```bash
-node packages/modules/build/cli.js add auth \
-  --registry apps/adonis-api-stater/modules
-```
+## Documentation
+
+- [Getting started](https://github.com/britzdylan/adonia/blob/main/apps/docs/guide/getting-started.md)
+- [CLI](https://github.com/britzdylan/adonia/blob/main/apps/docs/cli/overview.md)
+- [Modules](https://github.com/britzdylan/adonia/blob/main/apps/docs/modules/overview.md)
+- [Source](https://github.com/britzdylan/adonia)
+
+## License
+
+MIT

package/build/cli.js

@@ -10,7 +10,7 @@ import { packageVersion } from './host.js';
 const program = new Command();
 program
     .name('adonia')
-    .description('Adonia modules for AdonisJS')
+    .description('A CLI that copies AdonisJS modules from a registry into your app.')
     .version(packageVersion());
 function shared(cmd) {
     const opts = cmd.optsWithGlobals();

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "adonia",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
-  "description": "Adonia modules for AdonisJS \u2014 CLI and bundled registry",
+  "description": "A CLI that copies AdonisJS modules from a registry into your app.",
   "bin": {
     "adonia": "./build/cli.js"
   },
@@ -17,7 +17,8 @@
     "registry"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24",
+    "npm": ">=11"
   },
   "scripts": {
     "build": "tsc",

package/registry/README.md

@@ -10,7 +10,7 @@ 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:
+# or every module:
 npx adonia@latest init --scaffold
 ```
 
@@ -49,9 +49,9 @@ Each feature module (and `api`) ships a manifest:
   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`,
+  `start/` (limiter example). Adonis packages (`@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
+  `add` and `check` warn when a copied stub needs a package 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.