stonyx 0.2.3-alpha.2 → 0.2.3-alpha.21

package/dist/main.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Chronicle from '@stonyx/logs';
+import loadModules from './modules.js';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
+export default class Stonyx {
+    static initialized = false;
+    static modulePromises = {};
+    static instance;
+    static ready;
+    config;
+    chronicle;
+    modules;
+    constructor(config, rootPath) {
+        if (Stonyx.instance)
+            return Stonyx.instance;
+        Stonyx.instance = this;
+        Stonyx.ready = this.start(config, rootPath);
+    }
+    async start(config, rootPath) {
+        if (!config)
+            throw new Error('Stonyx requires full environment configuration on startup');
+        if (!rootPath)
+            throw new Error('Stonyx requires root project\'s path on startup');
+        // Transform config from stonyx-modules running as a standalone
+        if (rootPath.includes('stonyx-')) {
+            const dirName = rootPath.split('/').pop() ?? '';
+            const moduleName = kebabCaseToCamelCase(dirName.replace('stonyx-', ''));
+            config = { [moduleName]: config, ...(config.modules || {}) };
+            delete config.modules;
+        }
+        this.config = config;
+        this.chronicle = new Chronicle({ additionalLogs: { title: 'green' } });
+        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();
+    }
+    /**
+     * Allows users to define their own log for any extra class via environment config
+     */
+    configureUserLogs() {
+        const { chronicle } = this;
+        for (const [className, config] of Object.entries(this.config)) {
+            if (!config || typeof config !== 'object')
+                continue;
+            if (className in chronicle)
+                continue;
+            const { logColor, logMethod, logTimestamp } = config;
+            if (!logColor)
+                continue;
+            chronicle.defineType(logMethod || className, logColor, { logTimestamp: !!logTimestamp });
+        }
+    }
+    static get log() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.chronicle;
+    }
+    static get config() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.config;
+    }
+}
+export { waitForModule } from './modules.js';

package/dist/modules.d.ts

@@ -0,0 +1,5 @@
+import type { StoynxModule } from './lifecycle.js';
+import type Chronicle from '@stonyx/logs';
+export type StoynxConfig = Record<string, Record<string, unknown> | unknown>;
+export default function loadModules(config: StoynxConfig, rootPath: string, chronicle: Chronicle): Promise<StoynxModule[]>;
+export declare function waitForModule(moduleName: string): Promise<void>;

package/dist/modules.js

@@ -0,0 +1,92 @@
+/**
+ * Validates and initializes stonyx modules
+ * TODO: Refactor into a ModuleLoader class (good coding exercise)
+ */
+import { readFile } from '@stonyx/utils/file';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
+const modulePromises = {};
+// Configure module-specific logging
+function configureLog(chronicle, module, config) {
+    const { logColor, logMethod, logTimestamp } = config;
+    if (!logColor)
+        return;
+    chronicle.defineType(logMethod || module, logColor, { logTimestamp: !!logTimestamp });
+}
+function initializeModule(moduleName, moduleClass, modules, initPromises) {
+    const moduleInstance = new moduleClass();
+    modules.push(moduleInstance);
+    if (!moduleInstance.init)
+        return;
+    initPromises.push((async () => {
+        await moduleInstance.init();
+        modulePromises[moduleName]?.resolve();
+    })());
+}
+export default async function loadModules(config, rootPath, chronicle) {
+    const modules = [];
+    const initPromises = [];
+    const rootPackage = await readFile(`${rootPath}/package.json`, { json: true });
+    const dependencies = (rootPackage.devDependencies || {});
+    const projectName = typeof rootPackage.name === 'string' ? rootPackage.name : '';
+    // Expose rootPath to public configuration
+    config.rootPath = rootPath;
+    const moduleDependencies = Object.keys(dependencies).filter((moduleName) => moduleName.startsWith('@stonyx/'));
+    // Setup module promises prior to initialization
+    for (const moduleName of moduleDependencies) {
+        const promise = {};
+        modulePromises[moduleName] = promise;
+        promise.ready = new Promise(resolve => promise.resolve = resolve);
+    }
+    // Standalone module configuration
+    if (Array.isArray(rootPackage.keywords) && rootPackage.keywords.includes('stonyx-module')) {
+        configureLog(chronicle, projectName, config);
+        const entryPoint = typeof rootPackage.main === 'string' ? rootPackage.main : '';
+        const { default: moduleClass } = await import(`${rootPath}/${entryPoint}`);
+        initializeModule(projectName, moduleClass, modules, initPromises);
+    }
+    for (const moduleName of moduleDependencies) {
+        const modulePackage = await readFile(`${rootPath}/node_modules/${moduleName}/package.json`, { json: true, missingFileCallback: (_filePath) => {
+                console.warn(`Warning: Could not locate stonyx module: "${moduleName}". Module was not loaded`);
+                return '';
+            } });
+        if (!modulePackage)
+            continue;
+        const keywords = Array.isArray(modulePackage.keywords) ? modulePackage.keywords : [];
+        if (!keywords.includes('stonyx-module')) {
+            console.warn(`Warning: Stonyx modules must contain the "stonyx-module" keyword. Module was not loaded`);
+            continue;
+        }
+        if (!keywords.includes('stonyx-async')) {
+            modulePromises[moduleName].resolve();
+            continue;
+        }
+        try {
+            // Load & Configure Async Modules
+            const { default: moduleConfig } = await import(`${rootPath}/node_modules/${moduleName}/config/environment.js`);
+            const module = kebabCaseToCamelCase(moduleName.split('/').pop() ?? moduleName);
+            const userConfig = config[module] || {};
+            const finalConfig = mergeObject(moduleConfig, userConfig);
+            config[module] = finalConfig;
+            // Configure module-specific logging
+            configureLog(chronicle, module, finalConfig);
+            const entryPoint = modulePackage.main;
+            const { default: moduleClass } = await import(`${rootPath}/node_modules/${moduleName}/${entryPoint}`);
+            initializeModule(moduleName, moduleClass, modules, initPromises);
+        }
+        catch (error) {
+            console.error(error);
+            throw new Error(`Stonyx modules with async loading must have a config/environment.js file with default configurations. Module "${moduleName}" failed to load.`);
+        }
+    }
+    // Wait until all modules are initialized
+    await Promise.all(initPromises);
+    return modules;
+}
+export async function waitForModule(moduleName) {
+    const fullName = `@stonyx/${moduleName}`;
+    const modulePromise = modulePromises[fullName];
+    if (!modulePromise)
+        throw new Error(`Could wait for module: ${fullName}. Module was not registered in project dependencies`);
+    await modulePromises[fullName].ready;
+}

package/package.json

@@ -1,23 +1,44 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.2",
+  "version": "0.2.3-alpha.21",
   "description": "Base stonyx framework module",
-  "main": "main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "bin": {
-    "stonyx": "./src/cli.js"
+    "stonyx": "./dist/cli.js"
   },
   "exports": {
-    ".": "./src/main.js",
-    "./config": "./src/exports/config.js",
-    "./log": "./src/exports/log.js",
-    "./test-helpers": "./src/exports/test-helpers.js",
-    "./lifecycle": "./src/lifecycle.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./config": {
+      "types": "./dist/exports/config.d.ts",
+      "default": "./dist/exports/config.js"
+    },
+    "./log": {
+      "types": "./dist/exports/log.d.ts",
+      "default": "./dist/exports/log.js"
+    },
+    "./test-helpers": {
+      "types": "./dist/exports/test-helpers.d.ts",
+      "default": "./dist/exports/test-helpers.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "default": "./dist/lifecycle.js"
+    }
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx.git"
   },
+  "files": [
+    "dist",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "provenance": true
   },
@@ -30,16 +51,22 @@
     "url": "https://github.com/abofs/stonyx/issues"
   },
   "dependencies": {
-    "node-chronicle": "^0.2.0"
+    "@stonyx/utils": "0.2.3-beta.20",
+    "@stonyx/logs": "1.0.1-beta.13"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.5",
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
     "start": "node .",
-    "test": "qunit",
+    "test": "pnpm build && pnpm build:test && qunit 'dist-test/test/**/*-test.js'",
     "error": "echo \"Error: no error handling\" && exit 1",
     "postinstall": "node scripts/postinstall.js"
   }

package/.claude/index.md

@@ -1,94 +0,0 @@
-# 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

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,51 +0,0 @@
-name: Publish to NPM
-
-on:
-  repository_dispatch:
-    types: [cascade-publish]
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    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
-  pull-requests: write
-
-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/docs/api.md

@@ -1,89 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,72 +0,0 @@
-# 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.