stonyx 0.2.3-alpha.0 → 0.2.3-alpha.10

package/README.md

@@ -1,206 +1,56 @@
 # 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 scaffolding, 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 -g stonyx
+stonyx new my-app
+cd my-app
+stonyx serve
 ```
 
----
-
-## Running the Application
+The `new` command walks you through module selection and generates a ready-to-run project. From there, the CLI handles bootstrapping:
 
 ```bash
-node .        # Start the main app
-npm start     # Run using npm script
+stonyx serve    # Bootstrap + run app.js
+stonyx test     # Bootstrap + run tests
+stonyx help     # Show all available commands
 ```
 
----
-
-## 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/discord](https://github.com/abofs/stonyx-discord) | Discord bot with command and event handler auto-discovery |
+| [@stonyx/events](https://github.com/abofs/stonyx-events) | Pub/sub event system |
+| [@stonyx/oauth](https://github.com/abofs/stonyx-oauth) | OAuth provider integration |
+| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, and serializers |
+| [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
+| [@stonyx/sockets](https://github.com/abofs/stonyx-sockets) | WebSocket server and client |
 
 ## 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/package.json

@@ -1,19 +1,28 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.0",
+  "version": "0.2.3-alpha.10",
   "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",
     "url": "git+https://github.com/abofs/stonyx.git"
   },
+  "files": [
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "provenance": true
   },
@@ -26,10 +35,10 @@
     "url": "https://github.com/abofs/stonyx/issues"
   },
   "dependencies": {
-    "node-chronicle": "^0.2.0"
+    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/logs": "^1.0.0"
   },
   "devDependencies": {
-    "@stonyx/utils": "^0.2.2",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/cli/help.js

@@ -0,0 +1,48 @@
+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, n=new, h=help\n');
+
+  console.log('Project conventions:\n');
+  console.log('  Entry point:       app.js');
+  console.log('  Config:            config/environment.js');
+  console.log('  DB schema:         config/db-schema.js');
+  console.log('  Models:            models/');
+  console.log('  Serializers:       serializers/');
+  console.log('  Access control:    access/');
+  console.log('  Transforms:        transforms/');
+  console.log('  Hooks:             hooks/');
+  console.log('  REST requests:     requests/');
+  console.log('  Cron jobs:         crons/');
+  console.log('  Tests:             test/{unit,integration,acceptance}/');
+  console.log('');
+  console.log('  Logging:           import log from \'stonyx/log\' (never console.log)');
+  console.log('  Utilities:         import from \'@stonyx/utils/*\' (never raw fs)');
+  console.log('  Lint config:       import from \'@abofs/code-conventions\'');
+  console.log('  Package manager:   pnpm');
+  console.log('');
+}

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/new.js

@@ -0,0 +1,237 @@
+import { confirm, prompt } from '@stonyx/utils/prompt';
+import { createFile, createDirectory, copyFile, fileExists } from '@stonyx/utils/file';
+import { spawn } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const MODULE_OPTIONS = [
+  {
+    question: 'Will this project need a REST server?',
+    package: '@stonyx/rest-server',
+    dirs: ['requests']
+  },
+  {
+    question: 'Will this project need WebSockets?',
+    package: '@stonyx/sockets',
+    dirs: ['socket-handlers']
+  },
+  {
+    question: 'Will this project need data management?',
+    package: '@stonyx/orm',
+    dirs: ['models', 'serializers', 'access', 'transforms', 'hooks'],
+    files: { 'config/db-schema.js': generateDbSchema }
+  },
+  {
+    question: 'Will this project need scheduled tasks (cron)?',
+    package: '@stonyx/cron',
+    dirs: ['crons']
+  },
+  {
+    question: 'Will this project need OAuth?',
+    package: '@stonyx/oauth'
+  },
+  {
+    question: 'Will this project need pub/sub events?',
+    package: '@stonyx/events'
+  },
+  {
+    question: 'Will this project need a Discord bot?',
+    package: '@stonyx/discord',
+    dirs: ['discord-commands', 'discord-events']
+  }
+];
+
+function generateDbSchema() {
+  return `import { Model, hasMany } from '@stonyx/orm';
+
+export default class DBModel extends Model {
+  // Define your collections here
+  // examples = hasMany('example');
+}
+`;
+}
+
+function generatePackageJson(name, selectedModules) {
+  const devDependencies = { stonyx: 'latest' };
+
+  for (const mod of selectedModules) {
+    devDependencies[mod.package] = 'latest';
+  }
+
+  // Sort dependencies alphabetically
+  const sorted = Object.fromEntries(
+    Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b))
+  );
+
+  return JSON.stringify({
+    name,
+    version: '0.1.0',
+    type: 'module',
+    private: true,
+    scripts: {
+      start: 'stonyx serve',
+      test: 'stonyx test'
+    },
+    devDependencies: sorted
+  }, null, 2) + '\n';
+}
+
+function generateAppJs() {
+  return `import log from 'stonyx/log';
+
+export default class App {
+  constructor() {
+    if (App.instance) return App.instance;
+    App.instance = this;
+
+    this.ready = this.init();
+  }
+
+  async init() {
+    log.info('Initializing Application');
+
+    // Application setup here
+
+    log.info('Application has been initialized');
+  }
+}
+`;
+}
+
+function generateEnvironmentJs() {
+  return `export default {
+}
+`;
+}
+
+function generateEnvironmentExampleJs() {
+  return `// Copy this file to environment.js and fill in your values
+// All values should use environment variables with ?? fallback defaults
+
+const {
+  NODE_ENV,
+} = process.env;
+
+const environment = NODE_ENV ?? 'development';
+
+export default {
+}
+`;
+}
+
+function generateGitignore() {
+  return `node_modules/
+.env
+db.json
+*.log
+`;
+}
+
+function runPnpmInstall(projectDir) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('pnpm', ['install'], {
+      cwd: projectDir,
+      stdio: 'inherit'
+    });
+
+    child.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`pnpm install exited with code ${code}`));
+    });
+
+    child.on('error', reject);
+  });
+}
+
+export default async function newCommand({ args }) {
+  let appName = args[0];
+
+  if (!appName) {
+    appName = await prompt('Project name:');
+  }
+
+  if (!appName) {
+    console.error('Project name is required.');
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(process.cwd(), appName);
+
+  if (await fileExists(projectDir)) {
+    console.error(`Directory "${appName}" already exists.`);
+    process.exit(1);
+  }
+
+  console.log(`\nScaffolding new Stonyx project: ${appName}\n`);
+
+  // Prompt for module selection
+  const selectedModules = [];
+
+  for (const mod of MODULE_OPTIONS) {
+    if (await confirm(mod.question)) {
+      selectedModules.push(mod);
+    }
+  }
+
+  console.log('\nCreating project structure...\n');
+
+  // Create project directory
+  await createDirectory(projectDir);
+
+  // Copy .nvmrc from monorepo root
+  const monorepoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+  const nvmrcSource = path.join(monorepoRoot, '.nvmrc');
+
+  if (await fileExists(nvmrcSource)) {
+    await copyFile(nvmrcSource, path.join(projectDir, '.nvmrc'));
+  }
+
+  // Generate core files
+  await createFile(path.join(projectDir, 'package.json'), generatePackageJson(appName, selectedModules));
+  await createFile(path.join(projectDir, 'app.js'), generateAppJs());
+  await createFile(path.join(projectDir, '.gitignore'), generateGitignore());
+
+  // Create config directory and files
+  await createFile(path.join(projectDir, 'config', 'environment.js'), generateEnvironmentJs());
+  await createFile(path.join(projectDir, 'config', 'environment.example.js'), generateEnvironmentExampleJs());
+
+  // Create module-specific directories and files
+  for (const mod of selectedModules) {
+    if (mod.dirs) {
+      for (const dir of mod.dirs) {
+        await createDirectory(path.join(projectDir, dir));
+        // Create .gitkeep so empty dirs are tracked
+        await createFile(path.join(projectDir, dir, '.gitkeep'), '');
+      }
+    }
+
+    if (mod.files) {
+      for (const [filePath, generator] of Object.entries(mod.files)) {
+        await createFile(path.join(projectDir, filePath), generator());
+      }
+    }
+  }
+
+  // Create test structure
+  await createDirectory(path.join(projectDir, 'test', 'unit'));
+  await createFile(path.join(projectDir, 'test', 'unit', '.gitkeep'), '');
+  await createDirectory(path.join(projectDir, 'test', 'integration'));
+  await createFile(path.join(projectDir, 'test', 'integration', '.gitkeep'), '');
+  await createDirectory(path.join(projectDir, 'test', 'acceptance'));
+  await createFile(path.join(projectDir, 'test', 'acceptance', '.gitkeep'), '');
+
+  // Create test config
+  await createFile(path.join(projectDir, 'test', 'config', 'environment.js'), `export default {\n  // Test-specific config overrides\n}\n`);
+
+  console.log('Installing dependencies...\n');
+
+  try {
+    await runPnpmInstall(projectDir);
+  } catch (error) {
+    console.error('Failed to install dependencies. Run `pnpm install` manually in the project directory.');
+  }
+
+  console.log(`\n✓ Project "${appName}" created successfully!`);
+  console.log(`\n  cd ${appName}`);
+  console.log(`  stonyx serve\n`);
+}

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,63 @@
+#!/usr/bin/env node
+
+import serve from './cli/serve.js';
+import test from './cli/test.js';
+import help from './cli/help.js';
+import newCommand from './cli/new.js';
+import loadModuleCommands from './cli/load-commands.js';
+
+try { process.loadEnvFile(); } catch { /* no .env file */ }
+
+const aliases = { s: 'serve', t: 'test', h: 'help', n: 'new' };
+
+const builtInCommands = {
+  serve: { description: 'Bootstrap Stonyx and run the app', run: serve },
+  test: { description: 'Bootstrap Stonyx in test mode and run tests', run: test },
+  new: { description: 'Scaffold a new Stonyx project', run: newCommand },
+  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

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-import Chronicle from 'node-chronicle';
+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
@@ -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/.github/workflows/ci.yml

@@ -1,36 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches:
-      - dev
-      - main
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-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

package/.github/workflows/publish.yml

@@ -1,143 +0,0 @@
-name: Publish to NPM
-
-on:
-  # Manual trigger (kept for flexibility)
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - alpha
-          - patch
-          - minor
-          - major
-      custom-version:
-        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
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-  id-token: write  # Required for npm provenance
-  pull-requests: write  # For PR comments
-
-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!`
-            });

package/scripts/postinstall.js

@@ -1,16 +0,0 @@
-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);
-
-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/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;