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

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.`);
-});

package/src/cli/help.js

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

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

@@ -1,232 +0,0 @@
-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'
-  }
-];
-
-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

@@ -1,38 +0,0 @@
-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.js

@@ -1,27 +0,0 @@
-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);
-  });
-}