stonyx 0.2.3-beta.2 → 0.2.3-beta.21

package/README.md

@@ -5,19 +5,23 @@
 - 100% JavaScript (ES Modules)
 - Drop-in module system — no boilerplate
 - Automatic async module loading and initialization
-- Built-in CLI for bootstrapping and testing
+- Built-in CLI for scaffolding, bootstrapping, and testing
 
 ## Quick Start
 
 ```bash
-npm install stonyx
+npm install -g stonyx
+stonyx new my-app
+cd my-app
+stonyx serve
 ```
 
-The CLI handles everything — no manual `new Stonyx()` calls needed:
+The `new` command walks you through module selection and generates a ready-to-run project. From there, the CLI handles bootstrapping:
 
 ```bash
 stonyx serve    # Bootstrap + run app.js
 stonyx test     # Bootstrap + run tests
+stonyx help     # Show all available commands
 ```
 
 Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
@@ -40,8 +44,12 @@ Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from y
 | 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/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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-beta.2",
+  "version": "0.2.3-beta.21",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",
@@ -18,6 +18,11 @@
     "type": "git",
     "url": "git+https://github.com/abofs/stonyx.git"
   },
+  "files": [
+    "src",
+    "config",
+    "README.md"
+  ],
   "publishConfig": {
     "provenance": true
   },
@@ -30,10 +35,10 @@
     "url": "https://github.com/abofs/stonyx/issues"
   },
   "dependencies": {
-    "node-chronicle": "^0.2.0"
+    "@stonyx/utils": "0.2.3-beta.10",
+    "@stonyx/logs": "1.0.1-beta.5"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.3",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/cli/help.js

@@ -1,29 +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, h=help\n');
-}
+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/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.js

@@ -1,17 +1,19 @@
-#!/usr/bin/env node
+#!/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' };
+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 }
 };
 

package/src/main.js

@@ -14,7 +14,7 @@
  * 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';

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.

package/docs/developing-modules.md

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

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

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

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

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

@@ -1,64 +0,0 @@
-# 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/scripts/postinstall.js

@@ -1,11 +0,0 @@
-import { copyFile, createDirectory } from '@stonyx/utils/file';
-
-const projectDir = process.env.INIT_CWD;
-const configDir = `${projectDir}/config`;
-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.`);
-});