stonyx 0.2.3-alpha.0 → 0.2.3-alpha.2

package/.claude/index.md

@@ -0,0 +1,94 @@
+# Stonyx CLI Guide
+
+## Installation
+
+Stonyx is the core framework package. The CLI is provided by the `stonyx` binary defined in `package.json`.
+
+In a project that depends on `stonyx`:
+
+```bash
+pnpm add -D stonyx
+```
+
+The CLI is then available as `npx stonyx` or via pnpm scripts.
+
+## Commands
+
+### `stonyx serve` (alias: `s`)
+
+Bootstrap Stonyx and run the application.
+
+```bash
+stonyx serve              # loads app.js by default
+stonyx serve --entry custom.js  # custom entry point
+```
+
+Behavior:
+1. Loads `.env` file
+2. Imports `config/environment.js`
+3. Initializes Stonyx with all detected `@stonyx/*` modules
+4. Runs startup lifecycle hooks
+5. Imports and instantiates the entry point class
+6. Registers SIGTERM/SIGINT handlers for graceful shutdown
+
+### `stonyx test` (alias: `t`)
+
+Bootstrap Stonyx in test mode and run QUnit tests.
+
+```bash
+stonyx test                          # runs test/**/*-test.js
+stonyx test test/unit/foo-test.js    # specific file
+stonyx test "test/integration/**/*-test.js"  # glob pattern
+```
+
+Sets `NODE_ENV=test` and auto-loads test setup which merges `test/config/environment.js` overrides.
+
+### `stonyx help` (alias: `h`)
+
+Show available commands including built-in and module-provided commands.
+
+```bash
+stonyx help
+stonyx --help
+stonyx -h
+```
+
+### `stonyx new <app-name>`
+
+Scaffold a new Stonyx project with interactive module selection.
+
+```bash
+stonyx new my-backend
+```
+
+Prompts for:
+- Package name
+- Which `@stonyx/*` modules to include (REST server, WebSockets, ORM, cron, OAuth, events)
+
+Creates:
+- `package.json` with selected dependencies
+- `app.js` entry point
+- `config/environment.js` and `config/environment.example.js`
+- Module-specific directories (`models/`, `requests/`, `crons/`, etc.)
+- `test/` structure with `unit/`, `integration/`, `acceptance/`
+- `.gitignore` and `.nvmrc`
+- Runs `pnpm install`
+
+## Module Command System
+
+Stonyx modules can register CLI commands by exporting a `./commands` entry in their `package.json` exports map. The CLI auto-discovers these from installed `@stonyx/*` packages.
+
+Module commands appear under "Module commands" in `stonyx help` output. They can optionally request Stonyx bootstrap before running (via `bootstrap: true`).
+
+## Creating a Stonyx Project Manually
+
+If not using `stonyx new`:
+
+1. Create project directory
+2. Add `.nvmrc` with current LTS Node version
+3. `pnpm init` and set `"type": "module"`
+4. `pnpm add -D stonyx` plus desired `@stonyx/*` modules
+5. Create `config/environment.js` with module config
+6. Create `app.js` entry point class
+7. Create standard directories per selected modules
+8. Add `@abofs/code-conventions` for linting

package/.github/workflows/ci.yml

@@ -2,35 +2,15 @@ name: CI
 
 on:
   pull_request:
-    branches:
-      - dev
-      - main
+    branches: [dev, main]
 
 concurrency:
   group: ci-${{ github.head_ref || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
+    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,7 +1,8 @@
 name: Publish to NPM
 
 on:
-  # Manual trigger (kept for flexibility)
+  repository_dispatch:
+    types: [cascade-publish]
   workflow_dispatch:
     inputs:
       version-type:
@@ -9,7 +10,6 @@ on:
         required: true
         type: choice
         options:
-          - alpha
           - patch
           - minor
           - major
@@ -17,127 +17,35 @@ on:
         description: 'Custom version (optional, overrides version-type)'
         required: false
         type: string
-
-  # Auto-publish alpha on PR
   pull_request:
     types: [opened, synchronize, reopened]
-    branches: [main, dev]
-
-  # Auto-publish stable on merge to main
+    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  # Required for npm provenance
-  pull-requests: write  # For PR comments
+  id-token: write
+  pull-requests: write
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-          # For PR events, check out the PR branch
-          ref: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref }}
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 24.13.0
-          cache: 'pnpm'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      # Determine version type based on trigger
-      - name: Determine version bump type
-        id: version-type
-        run: |
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
-            echo "type=alpha" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event_name }}" = "push" ]; then
-            echo "type=patch" >> $GITHUB_OUTPUT
-          elif [ "${{ github.event.inputs.custom-version }}" != "" ]; then
-            echo "type=custom" >> $GITHUB_OUTPUT
-          else
-            echo "type=${{ github.event.inputs.version-type }}" >> $GITHUB_OUTPUT
-          fi
-
-      # Version bumping
-      - name: Bump version (custom)
-        if: steps.version-type.outputs.type == 'custom'
-        run: pnpm version ${{ github.event.inputs.custom-version }} --no-git-tag-version
-
-      - name: Bump version (alpha)
-        if: steps.version-type.outputs.type == 'alpha'
-        run: pnpm version prerelease --preid=alpha --no-git-tag-version
-
-      - name: Bump version (patch/minor/major)
-        if: steps.version-type.outputs.type == 'patch' || steps.version-type.outputs.type == 'minor' || steps.version-type.outputs.type == 'major'
-        run: pnpm version ${{ steps.version-type.outputs.type }} --no-git-tag-version
-
-      - name: Get package version
-        id: package-version
-        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
-
-      # Publishing
-      - name: Publish to NPM (alpha)
-        if: contains(steps.package-version.outputs.version, 'alpha')
-        run: pnpm publish --tag alpha --access public --no-git-checks
-
-      - name: Publish to NPM (stable)
-        if: "!contains(steps.package-version.outputs.version, 'alpha')"
-        run: pnpm publish --access public
-
-      # Only commit and tag for stable releases (push to main or manual stable)
-      - name: Commit version bump and create tag
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        run: |
-          git add package.json
-          git commit -m "chore: release v${{ steps.package-version.outputs.version }}"
-          git tag v${{ steps.package-version.outputs.version }}
-          git push origin main --tags
-
-      - name: Create GitHub Release
-        if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && !contains(steps.package-version.outputs.version, 'alpha'))
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: v${{ steps.package-version.outputs.version }}
-          release_name: v${{ steps.package-version.outputs.version }}
-          draft: false
-          prerelease: false
-
-      # Add PR comment with alpha version info
-      - name: Comment on PR with alpha version
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const version = '${{ steps.package-version.outputs.version }}';
-            const packageName = require('./package.json').name;
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: `## 🚀 Alpha Version Published\n\n**Version:** \`${version}\`\n\n**Install:**\n\`\`\`bash\npnpm add ${packageName}@${version}\n# or\npnpm add ${packageName}@alpha  # latest alpha\n\`\`\`\n\nThis alpha version is now available for testing!`
-            });
+    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.