stonyx 0.2.3-alpha.8 → 0.2.3-alpha.80

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

@@ -1,195 +0,0 @@
-# Cron Conventions
-
-Scheduling conventions for `@stonyx/cron`. Covers the legacy interval API and the advanced scheduling system.
-
-## Legacy API (Simple Intervals)
-
-For basic recurring callbacks, use the `Cron` class directly:
-
-```js
-import Cron from '@stonyx/cron';
-
-const cron = new Cron();
-
-// register(key, callback, intervalSeconds, runOnInit?)
-cron.register('health-check', async () => {
-  await checkHealth();
-}, 300, true);
-
-// Unregister when done
-cron.unregister('health-check');
-```
-
-`Cron` is a singleton — only one instance per process.
-
-## Advanced Scheduling (CronService)
-
-For jobs with cron expressions, one-shot scheduling, AI input normalization, and run history:
-
-```js
-import CronService from '@stonyx/cron/service';
-
-const service = new CronService();
-
-service.onJobDue = async (job) => {
-  // Execute the job's work
-  return { status: 'ok', summary: 'completed' };
-};
-
-await service.start();
-```
-
-### Schedule Kinds
-
-Three schedule types, specified in `schedule.kind`:
-
-| Kind | Purpose | Required fields |
-|------|---------|----------------|
-| `every` | Recurring interval | `everyMs` (milliseconds) |
-| `cron` | Cron expression | `expr` (5-field), optional `tz` |
-| `at` | One-shot | `at` (ISO-8601 string) |
-
-```js
-// Recurring every 60 seconds
-await service.add({
-  name: 'Diagnostics',
-  schedule: { kind: 'every', everyMs: 60_000 },
-  payload: { kind: 'agentTurn', message: 'run diagnostics' },
-});
-
-// Daily at 9am Eastern
-await service.add({
-  name: 'Morning Report',
-  schedule: { kind: 'cron', expr: '0 9 * * *', tz: 'America/New_York' },
-  payload: { kind: 'agentTurn', message: 'generate morning report' },
-});
-
-// One-shot reminder (auto-deletes after run)
-await service.add({
-  name: 'Reminder',
-  schedule: { kind: 'at', at: '2026-07-01T12:00:00Z' },
-  payload: { kind: 'agentTurn', message: 'follow up on PR' },
-});
-```
-
-### Payload Kinds
-
-| Kind | Target | Key field |
-|------|--------|-----------|
-| `agentTurn` | Isolated agent session | `message` |
-| `systemEvent` | Main session | `text` |
-
-`sessionTarget` is inferred automatically: `agentTurn` → `isolated`, `systemEvent` → `main`.
-
-### CRUD
-
-```js
-const job = await service.add({ ... });    // Create
-const found = service.get(job.id);         // Read
-const updated = await service.update(job.id, { name: 'Renamed' }); // Update
-await service.remove(job.id);              // Delete
-
-// List (excludes disabled by default)
-const jobs = service.list();
-const all = service.list({ includeDisabled: true });
-```
-
-### Manual Execution
-
-```js
-// Force-run regardless of schedule
-await service.run(job.id, 'force');
-
-// Only run if due
-await service.run(job.id, 'due');
-```
-
-### Run History
-
-```js
-const history = service.runs(job.id);
-// [{ status, error?, summary?, runAtMs, durationMs, nextRunAtMs, ts }]
-```
-
-### AI Input Normalization
-
-CronService accepts loose input from AI tool calls and normalizes it:
-
-- Missing `schedule.kind` is inferred from fields (`everyMs` → `every`, `expr` → `cron`, `at` → `at`)
-- Bare `message` or `text` at the top level is wrapped into a `payload`
-- `deleteAfterRun` is auto-set for one-shot (`at`) jobs
-- `delivery: { mode: 'announce' }` is auto-set for isolated `agentTurn` jobs
-
-```js
-// AI might send this flat structure
-await service.add({
-  name: 'Weather Check',
-  schedule: { everyMs: 120000 },
-  message: 'check the weather',
-});
-
-// Normalized to:
-// {
-//   schedule: { kind: 'every', everyMs: 120000 },
-//   payload: { kind: 'agentTurn', message: 'check the weather' },
-//   sessionTarget: 'isolated',
-//   delivery: { mode: 'announce' },
-// }
-```
-
-## ORM Data Model
-
-When persisting cron data with `@stonyx/orm`, use the following model structure. Reference implementations are in `@stonyx/cron`'s `test/sample/`.
-
-### Models
-
-```
-models/
-  cron-job.js              # name, enabled, deleteAfterRun, sessionTarget, wakeMode, timestamps
-  cron-job/
-    schedule.js            # kind, at, everyMs, anchorMs, expr, tz
-    payload.js             # kind, message, text
-    state.js               # nextRunAtMs, lastRunAtMs, lastStatus, consecutiveErrors, etc.
-    delivery.js            # mode
-  cron-run.js              # jobId, status, error, summary, runAtMs, durationMs, ts
-```
-
-**Property ordering:** `attr()` → `belongsTo()` (on parent model)
-
-The parent `cron-job` model uses `belongsTo` for schedule, payload, state, and delivery sub-models. This follows the property flattening rule — no passthrough objects.
-
-### DB Schema
-
-```js
-import { Model, hasMany } from '@stonyx/orm';
-
-export default class DBModel extends Model {
-  cronJobs = hasMany('cron-job');
-  cronJobSchedules = hasMany('cron-job/schedule');
-  cronJobPayloads = hasMany('cron-job/payload');
-  cronJobStates = hasMany('cron-job/state');
-  cronJobDeliveries = hasMany('cron-job/delivery');
-  cronRuns = hasMany('cron-run');
-}
-```
-
-### Serializers
-
-Identity maps for all cron models — field names match the model attributes directly.
-
-## Configuration
-
-```js
-// config/environment.js
-export default {
-  cron: {
-    log: true,       // enable cron logging (uses stonyx/log)
-  },
-}
-```
-
-## When to Use Which
-
-- **Simple recurring callback** → `Cron.register(key, callback, interval)`
-- **Scheduled jobs with history, CRUD, AI input** → `CronService`
-- **Never use raw `setInterval` or `setTimeout`** for recurring work

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,140 +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.
-
-**Legacy API** — simple recurring callbacks:
-
-- `register(key, callback, interval, runOnInit?)` — schedule a recurring job
-- `unregister(key)` — cancel a job
-
-**Advanced API** (`@stonyx/cron/service`) — full scheduling with CRUD, run history, and AI normalization:
-
-- `add(input)` / `get(id)` / `update(id, patch)` / `remove(id)` / `list(opts?)` — CRUD
-- `run(id, mode?)` — manual execution (`'force'` or `'due'`)
-- `runs(id, limit?)` — run history
-- `onJobDue` — callback for job execution
-
-Three schedule kinds: `every` (interval), `cron` (expression), `at` (one-shot).
-
-See [Cron Conventions](./cron-conventions.md) for full details.
-
-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,25 +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
-- [Cron Conventions](./cron-conventions.md) — scheduling, job model, CronService API, ORM data model
-- [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