stonyx 0.2.3-beta.0 → 0.2.3-beta.2

package/.github/workflows/publish.yml

@@ -1,6 +1,8 @@
 name: Publish to NPM
 
 on:
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -17,10 +19,14 @@ on:
         type: string
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
+    branches: [main]
   push:
     branches: [main]
 
+concurrency:
+  group: ${{ github.event_name == 'repository_dispatch' && 'cascade-update' || format('publish-{0}', github.ref) }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
   id-token: write
@@ -28,8 +34,18 @@ permissions:
 
 jobs:
   publish:
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
     uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
     with:
       version-type: ${{ github.event.inputs.version-type }}
       custom-version: ${{ github.event.inputs.custom-version }}
+      cascade-source: ${{ github.event.client_payload.source_package || '' }}
+    secrets: inherit
+
+  cascade:
+    needs: publish
+    uses: abofs/stonyx-workflows/.github/workflows/cascade.yml@main
+    with:
+      package-name: ${{ needs.publish.outputs.package-name }}
+      published-version: ${{ needs.publish.outputs.published-version }}
     secrets: inherit

package/README.md

@@ -1,206 +1,48 @@
 # Stonyx
 
-**Stonyx** is a lightweight, modular framework for building modern Node.js applications. It provides a **plug-and-play architecture**, centralized color-coded logging, and seamless integration of asynchronous modules, making development faster, cleaner, and more maintainable.
+**Stonyx** is a lightweight, modular framework for building modern Node.js applications. It provides a plug-and-play architecture, centralized color-coded logging, and seamless async module integration.
 
-### Highlights
-
-* ✅ 100% JavaScript
-* ✅ Drop-in file system for most modules
-* ✅ Don’t even hit the ground — just fly
-* ✅ High performance
-
-Stonyx acts as a **base application host**, allowing you to add official modules (`@stonyx/*`) or your own custom modules without boilerplate initialization.
-
----
+- 100% JavaScript (ES Modules)
+- Drop-in module system — no boilerplate
+- Automatic async module loading and initialization
+- Built-in CLI for bootstrapping and testing
 
 ## Quick Start
 
-### ESM Usage (Application Startup)
-
-For standard applications, the **bootstrap file** ensures that the Stonyx framework and all submodules are fully loaded before your application code runs:
-
-```js
-// index.js - your project's entry point
-import Stonyx from './stonyx-bootstrap.cjs';
-await Stonyx.ready; // wait until all modules are initialized
-
-const { default: App } = await import('./app.js'); // your application
-new App();
-```
-
-### CommonJS Bootstrap Helper
-Auto-generated and added to your project post installation
-
-```js
-// stonyx-bootstrap.cjs
-const Stonyx = require('stonyx').default;
-const config = require('./config/environment.js').default;
-
-new Stonyx(config, __dirname);
-```
-
----
-
-## Core Features
-
-### 1. **Modular Architecture**
-
-* Automatically detects modules in `devDependencies` prefixed with `@stonyx/`.
-* Supports async initialization with `stonyx-async` modules.
-* Safe module sequencing for submodule development with `waitForModule()`.
-
-### 2. **Color-Coded Logging**
-
-* Centralized logging via [Chronicle](https://github.com/abofs/chronicle).
-* Module-specific logs configurable in `environment.js`:
-
-```js
-restServer: { logColor: 'yellow', logMethod: 'api', logTimestamp: true }
-```
-
-* Create custom logs for any class with minimal configuration.
-
-### 3. **Singleton Design**
-
-* Only one instance of Stonyx exists per project.
-* Ensures consistent access to modules, logs, and configuration.
-
-### 4. **Plug-and-Play Module Loading**
-
-* Modules with `stonyx-module` keyword in `package.json` are auto-initialized.
-* Modules with `stonyx-async` keyword are awaited automatically before usage.
-
----
-
-## Official Modules
-
-### **[@stonyx/cron](https://github.com/abofs/stonyx-cron)**
-
-Lightweight asynchronous job scheduling utility.
-
-```js
-import Cron from '@stonyx/cron';
-
-const cron = new Cron();
-cron.register('exampleJob', async () => console.log('Job executed!'), 5, true);
-```
-
-* Efficient scheduling using a min-heap.
-* Optional logging via `config.cron`.
-
----
-
-### **[@stonyx/events](https://github.com/abofs/stonyx-events)**
-
-Lightweight pub/sub event system for application-wide event handling.
-
-```js
-import Events from '@stonyx/events';
-
-const events = new Events();
-
-// Register available events
-events.setup(['userLogin', 'userLogout', 'dataChange']);
-
-// Subscribe to events
-events.subscribe('userLogin', (user) => {
-  console.log(`${user.name} logged in`);
-});
-
-// Emit events
-events.emit('userLogin', { name: 'Alice' });
-```
-
-* Singleton pattern for shared event bus
-* Async support with error isolation
-* Type-safe event registration
-
----
-
-### **[@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server)**
-
-Dynamic REST server module with auto-route registration.
-
-```js
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
-
-new Stonyx(config);
-```
-
-* Zero configuration for routes: drop request classes into the `requests` directory.
-* Automatic path generation, JSON parsing, and CORS handling.
-* Supports per-route authentication hooks.
-
----
-
-### **[@stonyx/orm](https://github.com/abofs/stonyx-orm)**
-
-Lightweight ORM with model definitions, relationships, serializers, and optional REST integration.
-
-```js
-import Stonyx from 'stonyx';
-import config from './config/environment.js';
-
-new Stonyx(config);
-
-// Define models
-import { Model, attr, hasMany, belongsTo } from '@stonyx/orm';
-
-class Owner extends Model {
-  id = attr('string');
-  pets = hasMany('animal');
-}
-```
-
-* Auto-loads models, serializers, transforms, and access classes.
-* Optional JSON file persistence with auto-save intervals.
-* Integrates with `@stonyx/rest-server` for automatic route setup.
-
----
-
-## Configuration
-
-All modules are configurable via `config/environment.js`:
-
-```js
-export default {
-  restServer: { logColor: 'yellow', port: 3000 },
-  orm: { logColor: 'white', db: { file: './db.json', autosave: true } },
-  cron: { log: true }
-};
+```bash
+npm install stonyx
 ```
 
----
-
-## Running the Application
+The CLI handles everything — no manual `new Stonyx()` calls needed:
 
 ```bash
-node .        # Start the main app
-npm start     # Run using npm script
+stonyx serve    # Bootstrap + run app.js
+stonyx test     # Bootstrap + run tests
 ```
 
----
-
-## Developing Submodules
+Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
 
-For developers building new Stonyx modules or experimenting with async modules:
+## Documentation
 
-```js
-import Stonyx, { waitForModule } from 'stonyx';
-import config from './config/environment.js';
+| Section | Description |
+|---------|-------------|
+| [CLI](docs/cli.md) | Commands, aliases, and module commands |
+| [Configuration](docs/configuration.md) | Environment config, module config, test overrides |
+| [Modules](docs/modules.md) | Module architecture, async loading, official modules |
+| [Logging](docs/logging.md) | Chronicle integration and custom log types |
+| [Lifecycle](docs/lifecycle.md) | Startup and shutdown hooks |
+| [Testing](docs/testing.md) | Test runner, helpers, and conventions |
+| [Developing Modules](docs/developing-modules.md) | Guide for building custom Stonyx modules |
+| [API Reference](docs/api.md) | Public exports and class documentation |
 
-const app = new Stonyx(config, __dirname);
-
-// Wait for specific async module readiness
-await waitForModule('restServer');
-```
-
-* Use `waitForModule()` **only for submodule development**, testing, or when you need to ensure a specific module is fully initialized before continuing.
-* Official modules automatically initialize during normal application startup, so end-users do **not** need to call `waitForModule()`.
+## Official Modules
 
----
+| Module | Description |
+|--------|-------------|
+| [@stonyx/cron](https://github.com/abofs/stonyx-cron) | Lightweight async job scheduling |
+| [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
+| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, and serializers |
 
 ## License
 
-Apache 2.0 — do what you want, just keep attribution.
+Apache 2.0

package/config/environment copy.js

@@ -4,8 +4,7 @@ const {
   NODE_ENV,
 } = process.env;
 
-const isTest = typeof QUnit !== 'undefined';
-const environment = isTest ? 'test' : (NODE_ENV ?? 'development');
+const environment = NODE_ENV ?? 'development';
 
 export default {
   environment,

package/config/environment.js

@@ -4,8 +4,7 @@ const {
   NODE_ENV,
 } = process.env;
 
-const isTest = typeof QUnit !== 'undefined';
-const environment = isTest ? 'test' : (NODE_ENV ?? 'development');
+const environment = NODE_ENV ?? 'development';
 
 export default {
   environment,

package/docs/api.md

@@ -0,0 +1,89 @@
+# API Reference
+
+Public exports available from the `stonyx` package.
+
+## Exports Map
+
+| Import Path | Export | Description |
+|-------------|--------|-------------|
+| `stonyx` | `default` (Stonyx class) | Main framework class (singleton) |
+| `stonyx` | `waitForModule(name)` | Wait for an async module to be ready |
+| `stonyx/config` | `default` (config object) | Live reference to Stonyx configuration |
+| `stonyx/log` | `default` (Chronicle instance) | Live reference to Chronicle logger |
+| `stonyx/lifecycle` | `runStartupHooks(modules)` | Run startup hooks on a module array |
+| `stonyx/lifecycle` | `runShutdownHooks(modules)` | Run shutdown hooks in reverse order |
+| `stonyx/test-helpers` | `setupIntegrationTests(hooks)` | QUnit hook for integration test setup |
+
+## Stonyx Class
+
+```js
+import Stonyx from 'stonyx';
+```
+
+### Constructor
+
+```js
+new Stonyx(config, rootPath)
+```
+
+- **config** — Full environment configuration object
+- **rootPath** — Absolute path to the project root
+
+Returns the existing instance if one already exists (singleton pattern).
+
+### Static Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Stonyx.instance` | `Stonyx` | The singleton instance |
+| `Stonyx.ready` | `Promise` | Resolves when all modules are initialized |
+| `Stonyx.initialized` | `boolean` | Whether Stonyx has started initialization |
+
+### Static Getters
+
+| Getter | Returns | Throws |
+|--------|---------|--------|
+| `Stonyx.config` | Config object | If not initialized |
+| `Stonyx.log` | Chronicle instance | If not initialized |
+
+### Instance Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `instance.config` | `object` | Merged environment configuration |
+| `instance.chronicle` | `Chronicle` | Logger instance |
+| `instance.modules` | `Array` | Loaded module instances |
+
+## waitForModule
+
+```js
+import { waitForModule } from 'stonyx';
+
+await waitForModule('rest-server');
+```
+
+Waits for a specific `@stonyx/*` module to complete initialization. Pass the module name **without** the `@stonyx/` prefix.
+
+Throws if the module is not registered in project dependencies.
+
+## Lifecycle Functions
+
+```js
+import { runStartupHooks, runShutdownHooks } from 'stonyx/lifecycle';
+```
+
+### runStartupHooks(modules)
+
+Calls `startup()` on each module in array order. Skips modules without a `startup` method.
+
+### runShutdownHooks(modules)
+
+Calls `shutdown()` on each module in **reverse** array order. Errors are caught and logged — one failing hook does not prevent others from running.
+
+## setupIntegrationTests
+
+```js
+import { setupIntegrationTests } from 'stonyx/test-helpers';
+```
+
+Registers a QUnit `before` hook that waits for `Stonyx.ready`. Use within a `module()` block to ensure Stonyx is fully initialized before tests run.

package/docs/cli.md

@@ -0,0 +1,78 @@
+# CLI
+
+Stonyx includes a CLI that handles bootstrapping, module initialization, and application execution.
+
+## Usage
+
+```bash
+stonyx <command> [...args]
+```
+
+## Built-in Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `serve` | `s` | Bootstrap Stonyx and run the app |
+| `test` | `t` | Bootstrap Stonyx in test mode and run tests |
+| `help` | `h` | Show available commands |
+
+### serve
+
+Bootstraps Stonyx (loads config, initializes modules, runs lifecycle hooks), then imports your application entry point.
+
+```bash
+stonyx serve                    # Runs app.js by default
+stonyx serve --entry custom.js  # Runs a custom entry file
+```
+
+The serve command also registers `SIGTERM` and `SIGINT` handlers that run [shutdown hooks](lifecycle.md) before exiting.
+
+### test
+
+Runs your test suite using [QUnit](https://qunitjs.com/) with automatic Stonyx bootstrapping. Sets `NODE_ENV=test` and applies any [test config overrides](configuration.md#test-environment-overrides).
+
+```bash
+stonyx test                     # Runs test/**/*-test.js by default
+stonyx test "test/unit/**/*.js" # Custom test glob
+```
+
+### help
+
+Displays all available commands, including any [module commands](#module-commands).
+
+```bash
+stonyx help
+```
+
+## Module Commands
+
+Stonyx modules can register custom CLI commands by exporting a `./commands` entry in their `package.json`. These are automatically discovered and available through the CLI.
+
+```json
+{
+  "exports": {
+    "./commands": "./src/commands.js"
+  }
+}
+```
+
+The commands file should export an object mapping command names to definitions:
+
+```js
+export default {
+  'db:migrate': {
+    description: 'Run database migrations',
+    bootstrap: true,
+    run: async ({ args, cwd }) => { /* ... */ }
+  }
+};
+```
+
+- **`bootstrap: true`** — Stonyx will be fully initialized before the command runs
+- **`bootstrap: false`** — The command runs without Stonyx initialization
+
+Module commands appear under "Module commands" in `stonyx help` output. If two modules register the same command name, the first one loaded wins and a warning is printed.
+
+## Environment Variables
+
+The CLI automatically loads `.env` files via `process.loadEnvFile()` before executing any command.

package/docs/configuration.md

@@ -0,0 +1,72 @@
+# Configuration
+
+Stonyx uses a centralized configuration file that all modules read from at startup.
+
+## Environment Config
+
+Your project's configuration lives at `config/environment.js`:
+
+```js
+const { DEBUG, NODE_ENV } = process.env;
+
+const environment = NODE_ENV ?? 'development';
+
+export default {
+  environment,
+  debug: DEBUG ?? environment === 'development',
+
+  // Module-specific configuration
+  restServer: { logColor: 'yellow', port: 3000 },
+  cron: { log: true },
+};
+```
+
+This file is auto-generated on `npm install` via the postinstall script if it doesn't already exist.
+
+> **Note:** `config/environment.js` is gitignored by default so each environment can have its own settings.
+
+## Module Configuration
+
+Each Stonyx module reads its configuration from a top-level key matching its camelCase name. For example, `@stonyx/rest-server` reads from `config.restServer`.
+
+Async modules ship with their own default config at `config/environment.js` inside the module package. Your project config is merged on top of these defaults — you only need to specify overrides.
+
+## Logging Configuration
+
+Any config key with a `logColor` property automatically creates a [Chronicle](logging.md) log type:
+
+```js
+export default {
+  myService: {
+    logColor: 'purple',      // Required — enables log creation
+    logMethod: 'highlight',  // Optional — custom method name (defaults to key name)
+    logTimestamp: true,       // Optional — include timestamps
+  },
+};
+```
+
+This works for both module configs and custom service configs. See [Logging](logging.md) for details.
+
+## Test Environment Overrides
+
+When `NODE_ENV=test`, Stonyx automatically looks for `test/config/environment.js` in your project root:
+
+```js
+// test/config/environment.js
+export default {
+  debug: false,
+  restServer: { port: 0 },
+};
+```
+
+These overrides are deep-merged into the main config using in-place mutation, so any existing references (like `stonyx/config` exports) stay valid.
+
+## Accessing Config at Runtime
+
+```js
+import config from 'stonyx/config';
+
+console.log(config.environment); // 'development', 'test', etc.
+```
+
+The `stonyx/config` export is a live reference to the Stonyx instance config. It will throw if accessed before Stonyx is initialized.

package/docs/developing-modules.md

@@ -0,0 +1,108 @@
+# Developing Modules
+
+Guide for building custom Stonyx modules.
+
+## Package Setup
+
+Your module's `package.json` must include:
+
+```json
+{
+  "name": "@stonyx/my-module",
+  "keywords": ["stonyx-module"],
+  "main": "src/index.js"
+}
+```
+
+Add `stonyx-async` to keywords if your module requires asynchronous initialization.
+
+## Module Class
+
+Export a default class. Optionally define `init()`, `startup()`, and `shutdown()` methods:
+
+```js
+export default class MyModule {
+  // Called during module loading (async modules only)
+  async init() {
+    // Connect to services, load resources, etc.
+  }
+
+  // Called after ALL modules are initialized, before app entry runs
+  async startup() {
+    // Register routes, start listeners, etc.
+  }
+
+  // Called on SIGTERM/SIGINT, in reverse load order
+  async shutdown() {
+    // Close connections, flush data, etc.
+  }
+}
+```
+
+## Default Configuration
+
+Async modules must include `config/environment.js` with sensible defaults:
+
+```js
+export default {
+  logColor: 'cyan',
+  logMethod: 'myModule',
+  logTimestamp: true,
+  // Module-specific defaults...
+};
+```
+
+User project config is merged on top of these defaults.
+
+## Waiting for Other Modules
+
+If your module depends on another async module being ready:
+
+```js
+import { waitForModule } from 'stonyx';
+
+export default class MyModule {
+  async init() {
+    await waitForModule('rest-server');
+    // @stonyx/rest-server is now fully initialized
+  }
+}
+```
+
+Pass the module name without the `@stonyx/` prefix.
+
+## Standalone Development
+
+When running a module standalone (project path contains `stonyx-`), Stonyx auto-transforms the config structure. Your module's config is wrapped under its camelCase name:
+
+```js
+// If your module is @stonyx/rest-server and config is { port: 3000 }
+// Stonyx transforms it to: { restServer: { port: 3000 } }
+```
+
+## Custom CLI Commands
+
+Modules can register CLI commands by adding a `./commands` export:
+
+```json
+{
+  "exports": {
+    "./commands": "./src/commands.js"
+  }
+}
+```
+
+```js
+// src/commands.js
+export default {
+  'my-module:setup': {
+    description: 'Initialize module resources',
+    bootstrap: true,
+    run: async ({ args, cwd }) => {
+      // Command implementation
+    }
+  }
+};
+```
+
+Use namespaced command names (e.g., `my-module:setup`) to avoid conflicts with other modules. See [CLI](cli.md#module-commands) for details.

package/docs/index.md

@@ -0,0 +1,15 @@
+# Stonyx Documentation
+
+## Guides
+
+- [CLI](cli.md) — Commands, usage, and module-contributed commands
+- [Configuration](configuration.md) — Environment config, module config, and test overrides
+- [Modules](modules.md) — Module discovery, sync vs async, and official modules
+- [Lifecycle](lifecycle.md) — Startup/shutdown hooks and signal handling
+- [Logging](logging.md) — Color-coded logging via Chronicle
+- [Testing](testing.md) — Running tests, config overrides, and integration helpers
+- [Developing Modules](developing-modules.md) — Guide for building custom Stonyx modules
+
+## Reference
+
+- [API Reference](api.md) — Public exports and class documentation

package/docs/lifecycle.md

@@ -0,0 +1,47 @@
+# Lifecycle Hooks
+
+Stonyx modules can define `startup()` and `shutdown()` methods that run at specific points in the application lifecycle.
+
+## Startup Hooks
+
+Called sequentially (in module load order) after all modules have been initialized, right before your application entry point runs.
+
+```js
+export default class MyModule {
+  async startup() {
+    // Called after all modules are init'd, before app.js runs
+  }
+}
+```
+
+## Shutdown Hooks
+
+Called sequentially in **reverse** module load order when the process receives `SIGTERM` or `SIGINT`. Errors in one hook do not prevent other hooks from running.
+
+```js
+export default class MyModule {
+  async shutdown() {
+    // Clean up connections, flush buffers, etc.
+  }
+}
+```
+
+## Signal Handling
+
+The `stonyx serve` command registers signal handlers automatically:
+
+- **SIGTERM** — triggers shutdown hooks, then `process.exit(0)`
+- **SIGINT** — triggers shutdown hooks, then `process.exit(0)`
+
+Shutdown is idempotent — calling the handler multiple times only runs hooks once.
+
+## Using Lifecycle Hooks Directly
+
+For advanced use cases, the lifecycle functions are available as a public export:
+
+```js
+import { runStartupHooks, runShutdownHooks } from 'stonyx/lifecycle';
+
+await runStartupHooks(modules);   // Calls startup() on each module in order
+await runShutdownHooks(modules);  // Calls shutdown() on each module in reverse order
+```

package/docs/logging.md

@@ -0,0 +1,52 @@
+# Logging
+
+Stonyx provides centralized, color-coded logging via [Chronicle](https://github.com/abofs/chronicle).
+
+## Overview
+
+Every Stonyx instance creates a Chronicle logger with a default `title` log type (green). Modules and user services can register additional log types with custom colors.
+
+## Module Logs
+
+Modules that specify `logColor` in their configuration automatically get a Chronicle log type:
+
+```js
+// config/environment.js
+export default {
+  restServer: {
+    logColor: 'yellow',
+    logMethod: 'api',        // Optional — defaults to the config key name
+    logTimestamp: true,       // Optional — adds timestamps to log output
+  },
+};
+```
+
+This creates a `chronicle.api()` method that outputs in yellow with timestamps.
+
+## Custom Logs
+
+You can define logs for any class or service in your project — not just Stonyx modules:
+
+```js
+export default {
+  myWorker: {
+    logColor: 'cyan',
+    logMethod: 'worker',
+    logTimestamp: true,
+  },
+};
+```
+
+Any top-level config key with a `logColor` property will have a log type created automatically.
+
+## Accessing the Logger
+
+```js
+import log from 'stonyx/log';
+
+log.title('Application started');
+log.api('Request received');       // If restServer config defines logMethod: 'api'
+log.worker('Processing job');      // If myWorker config defines logMethod: 'worker'
+```
+
+The `stonyx/log` export is a live reference to the Chronicle instance. It will throw if accessed before Stonyx is initialized.

package/docs/modules.md

@@ -0,0 +1,78 @@
+# Module System
+
+Stonyx uses a plug-and-play module architecture. Modules are automatically detected, loaded, and initialized at startup.
+
+## How Modules Are Discovered
+
+Stonyx scans your project's `devDependencies` for packages prefixed with `@stonyx/`. Each matching package must include the `stonyx-module` keyword in its `package.json` to be loaded.
+
+```json
+{
+  "name": "@stonyx/my-module",
+  "keywords": ["stonyx-module"],
+  "main": "src/index.js"
+}
+```
+
+## Sync vs Async Modules
+
+### Sync Modules
+
+Modules with only the `stonyx-module` keyword are treated as synchronous. They are instantiated but their promise resolves immediately — no init phase is awaited.
+
+### Async Modules
+
+Modules that also include the `stonyx-async` keyword require initialization before they're ready:
+
+```json
+{
+  "keywords": ["stonyx-module", "stonyx-async"]
+}
+```
+
+Async modules **must** include a `config/environment.js` with default configuration. This is merged with the user's project config before initialization.
+
+Async modules can define an `init()` method that Stonyx awaits:
+
+```js
+export default class MyModule {
+  async init() {
+    // Connect to database, start server, etc.
+  }
+}
+```
+
+All module `init()` calls run concurrently via `Promise.all`.
+
+## Module Lifecycle
+
+1. **Discovery** — scan `devDependencies` for `@stonyx/*` packages
+2. **Validation** — verify `stonyx-module` keyword exists
+3. **Config merge** — async module defaults merged with user config
+4. **Log setup** — module-specific Chronicle log created if `logColor` is set
+5. **Instantiation** — module class is `new`'d
+6. **Initialization** — `init()` called (async modules only)
+7. **Startup hooks** — `startup()` called after all modules init (see [Lifecycle](lifecycle.md))
+8. **Shutdown hooks** — `shutdown()` called on process exit (see [Lifecycle](lifecycle.md))
+
+## waitForModule
+
+For submodule developers who need to ensure another async module is ready:
+
+```js
+import { waitForModule } from 'stonyx';
+
+await waitForModule('rest-server'); // Waits for @stonyx/rest-server
+```
+
+> **Note:** `waitForModule` is only needed during submodule development or testing. End-user applications don't need it — the CLI ensures all modules are initialized before running your app.
+
+## Official Modules
+
+| Module | Description |
+|--------|-------------|
+| [@stonyx/cron](https://github.com/abofs/stonyx-cron) | Lightweight async job scheduling with min-heap |
+| [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
+| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, serializers, and optional REST integration |
+
+See each module's repository for its specific documentation.

package/docs/testing.md

@@ -0,0 +1,64 @@
+# Testing
+
+Stonyx includes built-in test infrastructure using [QUnit](https://qunitjs.com/).
+
+## Running Tests
+
+```bash
+stonyx test                     # Runs test/**/*-test.js by default
+stonyx test "test/unit/**/*.js" # Custom glob pattern
+```
+
+The test command:
+1. Sets `NODE_ENV=test`
+2. Bootstraps Stonyx via a `--require` setup file
+3. Applies [test config overrides](configuration.md#test-environment-overrides)
+4. Runs QUnit with the specified glob
+
+## Test Config Overrides
+
+Create `test/config/environment.js` to override configuration during tests:
+
+```js
+export default {
+  debug: false,
+  restServer: { port: 0 },
+};
+```
+
+These are deep-merged into the main config. See [Configuration](configuration.md#test-environment-overrides).
+
+## Integration Test Helper
+
+For tests that need Stonyx fully initialized (e.g., testing modules with database connections):
+
+```js
+import { setupIntegrationTests } from 'stonyx/test-helpers';
+
+const { module, test } = QUnit;
+
+module('My Integration Test', function(hooks) {
+  setupIntegrationTests(hooks);
+
+  test('can access modules', function(assert) {
+    // Stonyx is fully initialized here
+    assert.ok(true);
+  });
+});
+```
+
+`setupIntegrationTests` adds a `before` hook that waits for `Stonyx.ready` to resolve.
+
+## Test File Convention
+
+Place tests under `test/` with the `-test.js` suffix:
+
+```
+test/
+  unit/
+    my-feature-test.js
+    cli/
+      serve-test.js
+  integration/
+    api-test.js
+```

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-beta.0",
+  "version": "0.2.3-beta.2",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",
+  "bin": {
+    "stonyx": "./src/cli.js"
+  },
   "exports": {
     ".": "./src/main.js",
     "./config": "./src/exports/config.js",
     "./log": "./src/exports/log.js",
-    "./test-helpers": "./src/exports/test-helpers.js"
+    "./test-helpers": "./src/exports/test-helpers.js",
+    "./lifecycle": "./src/lifecycle.js"
   },
   "repository": {
     "type": "git",
@@ -29,7 +33,7 @@
     "node-chronicle": "^0.2.0"
   },
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
+    "@stonyx/utils": "0.2.3-beta.3",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/scripts/postinstall.js

@@ -2,7 +2,6 @@ import { copyFile, createDirectory } from '@stonyx/utils/file';
 
 const projectDir = process.env.INIT_CWD;
 const configDir = `${projectDir}/config`;
-const bootstrapFile = 'stonyx-bootstrap.cjs';
 const envFile = 'environment.js';
 
 createDirectory(configDir);
@@ -10,7 +9,3 @@ createDirectory(configDir);
 copyFile(`./config/environment copy.js`, `${configDir}/${envFile}`).then(result => {
   if (result) console.log(`Stonyx: ${envFile} has been successfully created. Please see README.md for more information.`);
 });
-
-copyFile(`./src/bootstrap.cjs`, `${projectDir}/${bootstrapFile}`).then(result => {
-  if (result) console.log(`Stonyx: ${bootstrapFile} has been successfully created. Please see README.md for more information.`);
-});

package/src/cli/help.js

@@ -0,0 +1,29 @@
+export default async function help({ args, builtInCommands, loadModuleCommands } = {}) {
+  console.log('\nUsage: stonyx <command> [...args]\n');
+  console.log('Commands:\n');
+
+  if (builtInCommands) {
+    for (const [name, { description }] of Object.entries(builtInCommands)) {
+      console.log(`  ${name.padEnd(20)} ${description}`);
+    }
+  }
+
+  if (loadModuleCommands) {
+    try {
+      const moduleCommands = await loadModuleCommands();
+      const entries = Object.entries(moduleCommands);
+
+      if (entries.length) {
+        console.log('\nModule commands:\n');
+
+        for (const [name, { description }] of entries) {
+          console.log(`  ${name.padEnd(20)} ${description}`);
+        }
+      }
+    } catch {
+      // Module commands not available (e.g., no project context)
+    }
+  }
+
+  console.log('\nAliases: s=serve, t=test, h=help\n');
+}

package/src/cli/load-commands.js

@@ -0,0 +1,56 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+
+export default async function loadModuleCommands() {
+  const cwd = process.cwd();
+  const commands = {};
+
+  let projectPackage;
+
+  try {
+    const raw = await readFile(path.join(cwd, 'package.json'), 'utf8');
+    projectPackage = JSON.parse(raw);
+  } catch {
+    return commands;
+  }
+
+  const allDeps = {
+    ...projectPackage.dependencies,
+    ...projectPackage.devDependencies
+  };
+
+  const stonyxModules = Object.keys(allDeps).filter(name => name.startsWith('@stonyx/'));
+
+  for (const moduleName of stonyxModules) {
+    let modulePackage;
+
+    try {
+      const raw = await readFile(path.join(cwd, 'node_modules', moduleName, 'package.json'), 'utf8');
+      modulePackage = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+
+    const { exports: moduleExports } = modulePackage;
+
+    if (!moduleExports || !moduleExports['./commands']) continue;
+
+    try {
+      const commandsModule = await import(path.join(cwd, 'node_modules', moduleName, moduleExports['./commands']));
+      const moduleCommands = commandsModule.default;
+
+      for (const [name, command] of Object.entries(moduleCommands)) {
+        if (commands[name]) {
+          console.warn(`Warning: Command "${name}" from ${moduleName} conflicts with existing command. Skipping.`);
+          continue;
+        }
+
+        commands[name] = { ...command, module: moduleName };
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return commands;
+}

package/src/cli/serve.js

@@ -0,0 +1,38 @@
+import { runStartupHooks, runShutdownHooks } from '../lifecycle.js';
+
+export function createShutdownHandler(modules) {
+  let shuttingDown = false;
+  return async () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    await runShutdownHooks(modules);
+    process.exit(0);
+  };
+}
+
+export default async function serve({ args }) {
+  const cwd = process.cwd();
+  const entryFlag = args.indexOf('--entry');
+  const entryPoint = entryFlag !== -1 ? args[entryFlag + 1] : 'app.js';
+
+  const { default: config } = await import(`${cwd}/config/environment.js`);
+  const { default: Stonyx } = await import('../main.js');
+
+  new Stonyx(config, cwd);
+  await Stonyx.ready;
+
+  const { modules } = Stonyx.instance;
+  await runStartupHooks(modules);
+
+  const shutdown = createShutdownHandler(modules);
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  const entryModule = await import(`${cwd}/${entryPoint}`);
+
+  if (entryModule.default) {
+    new entryModule.default();
+  }
+}

package/src/cli/test-setup.js

@@ -0,0 +1,8 @@
+import { pathToFileURL } from 'url';
+
+const cwd = process.cwd();
+
+const { default: Stonyx } = await import('stonyx');
+const { default: config } = await import(pathToFileURL(`${cwd}/config/environment.js`));
+
+new Stonyx(config, cwd);

package/src/cli/test.js

@@ -0,0 +1,27 @@
+import { spawn } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'path';
+
+export default async function test({ args }) {
+  const cwd = process.cwd();
+  const setupFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'test-setup.js');
+  const setupFileUrl = pathToFileURL(setupFile).href;
+  const qunitBin = path.resolve(cwd, 'node_modules/qunit/bin/qunit.js');
+
+  // Default to conventional test glob if no args provided
+  const testArgs = args.length > 0 ? args : ['test/**/*-test.js'];
+
+  const child = spawn(process.execPath, [
+    '--import', setupFileUrl,
+    qunitBin,
+    ...testArgs
+  ], {
+    cwd,
+    stdio: 'inherit',
+    env: { ...process.env, NODE_ENV: 'test' }
+  });
+
+  child.on('close', (code) => {
+    process.exit(code);
+  });
+}

package/src/cli.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import serve from './cli/serve.js';
+import test from './cli/test.js';
+import help from './cli/help.js';
+import loadModuleCommands from './cli/load-commands.js';
+
+try { process.loadEnvFile(); } catch { /* no .env file */ }
+
+const aliases = { s: 'serve', t: 'test', h: 'help' };
+
+const builtInCommands = {
+  serve: { description: 'Bootstrap Stonyx and run the app', run: serve },
+  test: { description: 'Bootstrap Stonyx in test mode and run tests', run: test },
+  help: { description: 'Show available commands', run: help }
+};
+
+const args = process.argv.slice(2);
+const commandName = aliases[args[0]] || args[0];
+const commandArgs = args.slice(1);
+
+async function main() {
+  if (!commandName || commandName === 'help') {
+    await help({ args: commandArgs, builtInCommands, loadModuleCommands });
+    return;
+  }
+
+  const builtIn = builtInCommands[commandName];
+
+  if (builtIn) {
+    await builtIn.run({ args: commandArgs });
+    return;
+  }
+
+  // Search module commands
+  const moduleCommands = await loadModuleCommands();
+  const moduleCommand = moduleCommands[commandName];
+
+  if (moduleCommand) {
+    const cwd = process.cwd();
+
+    if (moduleCommand.bootstrap) {
+      const { default: config } = await import(`${cwd}/config/environment.js`);
+      const { default: Stonyx } = await import('./main.js');
+      new Stonyx(config, cwd);
+      await Stonyx.ready;
+    }
+
+    await moduleCommand.run({ args: commandArgs, cwd });
+    return;
+  }
+
+  console.error(`Unknown command: ${args[0]}\n`);
+  await help({ args: [], builtInCommands, loadModuleCommands });
+  process.exit(1);
+}
+
+main().catch(error => {
+  console.error(error);
+  process.exit(1);
+});

package/src/lifecycle.js

@@ -0,0 +1,17 @@
+export async function runStartupHooks(modules) {
+  for (const module of modules) {
+    if (typeof module.startup === 'function') await module.startup();
+  }
+}
+
+export async function runShutdownHooks(modules) {
+  for (const module of [...modules].reverse()) {
+    if (typeof module.shutdown === 'function') {
+      try {
+        await module.shutdown();
+      } catch (error) {
+        console.error('Error during module shutdown:', error);
+      }
+    }
+  }
+}

package/src/main.js

@@ -17,6 +17,7 @@
 import Chronicle from 'node-chronicle';
 import loadModules from './modules.js';
 import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
 
 export default class Stonyx {
   static initialized = false
@@ -45,6 +46,16 @@ export default class Stonyx {
 
     Stonyx.initialized = true;
 
+    // Auto-merge test environment overrides (after initialized flag, before modules load)
+    // Uses in-place mutation to preserve existing references (e.g. stonyx/config export cache)
+    if (process.env.NODE_ENV === 'test') {
+      try {
+        const { default: testOverrides } = await import(`${rootPath}/test/config/environment.js`);
+        const merged = mergeObject(config, testOverrides);
+        Object.assign(config, merged);
+      } catch { /* no test overrides found */ }
+    }
+
     this.modules = await loadModules(config, rootPath, this.chronicle);
     this.configureUserLogs();
   }

package/src/bootstrap.cjs

@@ -1,9 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;

package/stonyx-bootstrap.cjs

@@ -1,9 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;