stonyx 0.2.3-beta.9 → 0.2.3-beta.90

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/conventions/discord-conventions.md

@@ -1,62 +0,0 @@
-# Discord Conventions
-
-Conventions for projects using `@stonyx/discord`.
-
-## Command Files
-
-- One class per file in the configured command directory (default: `discord-commands/`)
-- Each file default-exports a class extending `Command` from `@stonyx/discord`
-- Class must define a `data` property (a `SlashCommandBuilder` instance) and an `async execute(interaction)` method
-- Class ordering: static properties → `data` → `execute()`
-- Filenames use kebab-case; `forEachFileImport` converts to camelCase for internal registration
-- Permission checks belong in the consuming application, not in the module
-
-```js
-import { Command } from '@stonyx/discord';
-import { SlashCommandBuilder } from 'discord.js';
-
-export default class PingCommand extends Command {
-  data = new SlashCommandBuilder()
-    .setName('ping')
-    .setDescription('Replies with Pong!');
-
-  async execute(interaction) {
-    await interaction.reply('Pong!');
-  }
-}
-```
-
-## Event Handler Files
-
-- One class per file in the configured event directory (default: `discord-events/`)
-- Each file default-exports a class extending `EventHandler` from `@stonyx/discord`
-- Class must set `static event` to a valid Discord.js event name (e.g., `'messageCreate'`, `'voiceStateUpdate'`)
-- Class must implement a `handle(...args)` method matching the Discord.js event signature
-- Class ordering: static properties → `handle()`
-
-```js
-import { EventHandler } from '@stonyx/discord';
-
-export default class WelcomeHandler extends EventHandler {
-  static event = 'guildMemberAdd';
-
-  handle(member) {
-    // Welcome new member
-  }
-}
-```
-
-## Configuration
-
-- Config namespace: `config.discord`
-- Environment variables prefixed with `DISCORD_`
-- Logging: `log.discord()` — configured via `logColor: '#7289da'` and `logMethod: 'discord'`
-- Intent auto-derivation: the module computes required gateway intents from discovered event handlers; use `additionalIntents` in config for edge cases
-
-## Module Keywords
-
-```json
-"keywords": ["stonyx-async", "stonyx-module"]
-```
-
-`stonyx-async` indicates the module's `init()` is async and must be awaited by the framework.

package/docs/conventions/framework-modules.md

@@ -1,127 +0,0 @@
-# Framework Modules
-
-When to use which `@stonyx/*` module. Always check these before reaching for Node built-ins or npm packages.
-
-## `stonyx/log`
-
-All logging goes through `stonyx/log`. Never use `console.log`, `console.warn`, or `console.error`.
-
-```js
-import log from 'stonyx/log';
-
-log.info('Server started');
-log.error('Connection failed', error);
-```
-
-Custom log types can be configured in `config/environment.js`:
-
-```js
-export default {
-  socket: { logColor: 'magenta' }
-}
-```
-
-## `@stonyx/utils`
-
-Utility library organized by domain. Always check here before using Node built-ins or adding npm dependencies.
-
-### File I/O (`@stonyx/utils/file`)
-
-**`fs` is explicitly prohibited.** Use these instead:
-
-- `createFile(filePath, data, options?)` — write a new file (creates parent dirs)
-- `updateFile(filePath, data, options?)` — atomic update via swap file
-- `copyFile(sourcePath, targetPath, options?)` — copy with optional overwrite
-- `readFile(filePath, options?)` — read file, supports `{ json: true }` and `{ missingFileCallback }`
-- `deleteFile(filePath, options?)` — delete file, supports `{ ignoreAccessFailure: true }`
-- `createDirectory(dir)` — recursive mkdir
-- `deleteDirectory(dir)` — recursive rm
-- `forEachFileImport(dir, callback, options?)` — iterate and dynamically import all `.js` files in a directory
-- `fileExists(filePath)` — check existence
-
-### Object Manipulation (`@stonyx/utils/object`)
-
-- `deepCopy(obj)` — deep clone via JSON
-- `objToJson(obj, format?)` — stringify with formatting
-- `makeArray(obj)` — wrap in array if not already
-- `mergeObject(obj1, obj2, options?)` — deep merge objects, supports `{ ignoreNewKeys: true }`
-- `get(obj, path)` — dot-path property access (e.g., `get(obj, 'a.b.c')`)
-- `getOrSet(map, key, defaultValue)` — get from Map or set default (supports factory functions)
-
-### String Transforms (`@stonyx/utils/string`)
-
-- `kebabCaseToCamelCase(str)` — `'my-thing'` → `'myThing'`
-- `kebabCaseToPascalCase(str)` — `'my-thing'` → `'MyThing'`
-- `camelCaseToKebabCase(str)` — `'myThing'` → `'my-thing'`
-- `generateRandomString(length?)` — alphanumeric random string (default 8 chars)
-- `pluralize(str)` — basic pluralization
-
-### Date / Timestamp (`@stonyx/utils/date`)
-
-- `getTimestamp(dateObject?)` — Unix timestamp in seconds (current time if no arg)
-
-### Promises (`@stonyx/utils/promise`)
-
-- `sleep(seconds)` — async delay
-
-### Interactive Prompts (`@stonyx/utils/prompt`)
-
-- `confirm(question)` — yes/no prompt, returns boolean
-- `prompt(question)` — free-text input, returns string
-
-File issues on `stonyx-utils` for any gaps rather than adding workarounds or npm dependencies.
-
-## `@stonyx/events`
-
-All pub/sub event handling. Never create custom event emitters.
-
-- `setup(eventNames)` — register valid event names
-- `subscribe(event, callback)` — listen for events
-- `once(event, callback)` — single-fire listener
-- `unsubscribe(event, callback)` — remove listener
-- `emit(event, ...args)` — fire event
-- `clear(event)` / `reset()` — cleanup
-
-## `@stonyx/cron`
-
-All scheduled and interval tasks. Never use raw `setInterval` or `setTimeout` for recurring work.
-
-- `register(key, callback, interval, runOnInit?)` — schedule a recurring job
-- `unregister(key)` — cancel a job
-
-Configurable via `config/environment.js`:
-
-```js
-export default {
-  cron: { log: true }
-}
-```
-
-## `@stonyx/sockets`
-
-WebSocket handlers. Class ordering: static properties → `server()` method → `client()` method.
-
-Exports: `SocketServer`, `SocketClient`, `Handler`, `Sockets`
-
-## `@stonyx/discord`
-
-Discord bot with command and event handler auto-discovery. Class ordering: static properties → `data` / `static event` → `execute()` / `handle()`.
-
-Exports: `DiscordBot`, `Command`, `EventHandler`, `Discord`, `chunkMessage`
-
-## `@stonyx/oauth`
-
-OAuth providers. Class ordering: constructor with `super()` → async methods → transform methods.
-
-Key methods: `getAuthorizationUrl()`, `handleCallback()`, `getSession()`, `logout()`
-
-## `@abofs/code-conventions`
-
-Shared lint and formatting config. Import and spread; never define local rules.
-
-Exports:
-- `@abofs/code-conventions/eslint` — ESLint config
-- `@abofs/code-conventions/prettier` — Prettier config
-- `@abofs/code-conventions/eslint-ember` — Ember-specific ESLint
-- `@abofs/code-conventions/template-lint` — Template linting
-- `@abofs/code-conventions/lint-staged` — Lint-staged config

package/docs/conventions/index.md

@@ -1,24 +0,0 @@
-# Stonyx Framework Conventions
-
-Universal rules that apply to every Stonyx project. Section-specific conventions are linked below.
-
-## Universal Rules
-
-- **One class per file** — each file exports a single default class (or function for transforms)
-- **Constants**: shared across files → dedicated constants file; single-use → top of the consuming file
-- **No `console.log` / `.warn` / `.error`** — use `log` from `stonyx/log` for all logging
-- **Check `@stonyx/utils` first** — before reaching for Node built-ins or npm packages, check if `@stonyx/utils` already provides what you need (file I/O, object manipulation, string transforms, date/timestamp, promises, prompts). File issues on stonyx-utils for gaps rather than working around them
-- **`fs` is prohibited** — use file utilities from `@stonyx/utils/file` instead
-- **Always LTS Node or higher** — version specified in `.nvmrc`
-- **Always pnpm** — never npm or yarn
-- **Lint config**: import from `@abofs/code-conventions`; never define local lint rules
-- **ES Modules** — all projects use `"type": "module"` and ESM imports
-
-## Section Conventions
-
-- [Project Structure](./project-structure.md) — directory layout, file organization, config conventions
-- [Framework Modules](./framework-modules.md) — when to use which `@stonyx/*` module
-- [ORM Conventions](./orm-conventions.md) — models, serializers, access control, transforms, hooks
-- [REST Conventions](./rest-conventions.md) — REST server request classes and handlers
-- [Discord Conventions](./discord-conventions.md) — Discord bot commands and event handlers
-- [Testing Conventions](./testing-conventions.md) — test organization, patterns, and tooling

package/docs/conventions/orm-conventions.md

@@ -1,158 +0,0 @@
-# ORM Conventions
-
-## Models
-
-Models define the data structure with attributes and relationships. One model per file in `models/`.
-
-**Property ordering:** `attr()` → `belongsTo()` / `hasMany()` → computed getters
-
-```js
-import { Model, attr, belongsTo, hasMany } from '@stonyx/orm';
-import { ANIMALS } from '../constants.js';
-
-export default class AnimalModel extends Model {
-  type = attr('animal');
-  age = attr('number');
-  size = attr('string');
-
-  owner = belongsTo('owner');
-  traits = hasMany('trait');
-
-  get tag() {
-    const { owner, size } = this;
-
-    if (!owner) {
-      return `Unowned ${size} ${ANIMALS[this.type]}`;
-    }
-
-    return `${owner.id}'s ${size} ${ANIMALS[this.type]}`;
-  }
-}
-```
-
-### Property Flattening
-
-Every property must resolve to a final data type — no passthrough objects. If an API returns a nested object, create a sub-model with `belongsTo` rather than storing the raw object.
-
-### Nested Models
-
-Use nested directories for `belongsTo` children:
-
-```
-models/
-  character.js
-  character/
-    relationship.js
-```
-
-## Serializers
-
-Serializers map raw external data to the model shape. One serializer per model in `serializers/`.
-
-The serializer has a single `map` property. It is responsible for mapping only, not fetching.
-
-```js
-import { Serializer } from '@stonyx/orm';
-
-const COLOR_TRAIT_MAP = {
-  'black': 2,
-  'white': 3,
-}
-
-export default class AnimalSerializer extends Serializer {
-  map = {
-    age: 'details.age',
-    size: 'details.c',
-    color: 'details.x',
-    owner: 'details.location.owner',
-
-    // Array value: [sourcePath, customHandler]
-    traits: ['details', ({ x:color }) => {
-      const traits = [{ id: 1, type: 'habitat', value: 'farm', category: 'physical' }];
-
-      const id = COLOR_TRAIT_MAP[color];
-      if (id) traits.push({ id, type: 'color', value: color, category: 'appearance' });
-
-      return traits;
-    }]
-  }
-}
-```
-
-### Clients vs Serializers
-
-- **Clients** fetch, decrypt, and provide raw data from external sources
-- **Serializers** map that raw data to the model shape
-
-Clients handle I/O; serializers handle structure. Never mix the two.
-
-## Access Control
-
-Access classes define which models they govern and implement an `access()` method. One access file per logical access boundary in `access/`.
-
-**Structure:** `models` property → `access()` method
-
-```js
-export default class GlobalAccess {
-  models = ['owner', 'animal', 'trait', 'category', 'phone-number'];
-
-  access(request) {
-    const { originalUrl: url } = request;
-
-    // Return false to deny
-    if (url.endsWith('/owners/angela')) return false;
-
-    // Return a filter function for conditional access
-    if (url.endsWith('/owners')) return record => record.id !== 'angela';
-    if (url.endsWith('/animals')) return record => record.owner !== 'angela';
-
-    // Return permission array for full access
-    return ['read', 'create', 'update', 'delete'];
-  }
-}
-```
-
-The `models` property accepts an array of model names, or `'*'` to match all models.
-
-`access()` return values:
-- `false` — deny access
-- `function` — filter function applied to response records
-- `string[]` — allowed operations (e.g., `['read', 'create', 'update', 'delete']`)
-
-## Transforms
-
-Transforms are default-exported functions (not classes) that convert values. One transform per model in `transforms/`.
-
-```js
-import { ANIMALS } from '../constants.js';
-
-const codeEnumMap = {}
-
-for (let i = 0; i < ANIMALS.length; i++) codeEnumMap[ANIMALS[i]] = i;
-
-export default function(value) {
-  return codeEnumMap[value] || 0;
-}
-```
-
-## Hooks
-
-Use `beforeHook` / `afterHook` from `@stonyx/orm/hooks`. Place hook files in `hooks/`.
-
-## DB Schema
-
-The database schema extends `Model` and uses `hasMany` for each collection:
-
-```js
-import { Model, hasMany } from '@stonyx/orm';
-
-export default class DBModel extends Model {
-  owners = hasMany('owner');
-  animals = hasMany('animal');
-  traits = hasMany('trait');
-  categories = hasMany('category');
-  phoneNumbers = hasMany('phone-number');
-}
-```
-
-Located at `config/db-schema.js`, referenced from `config/environment.js`.