stonyx 0.2.3-alpha.0 → 0.2.3-alpha.2

package/docs/cli.md

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

@@ -0,0 +1,72 @@
+# 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/framework-modules.md

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

@@ -0,0 +1,23 @@
+# 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
+- [Testing Conventions](./testing-conventions.md) — test organization, patterns, and tooling

package/docs/conventions/orm-conventions.md

@@ -0,0 +1,158 @@
+# 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`.

package/docs/conventions/project-structure.md

@@ -0,0 +1,106 @@
+# Project Structure
+
+## Entry Point
+
+The application entry point is always `app.js` at the project root. This file exports a default class that initializes the application.
+
+```js
+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');
+  }
+}
+```
+
+## File Layout
+
+Flat file structure at root level — non-directory project files live at the project root.
+
+### Standard Directories
+
+| Directory | Purpose | When to create |
+|-----------|---------|----------------|
+| `config/` | Configuration files | Always |
+| `models/` | ORM model definitions | When using `@stonyx/orm` |
+| `serializers/` | Data serializers | When using `@stonyx/orm` |
+| `access/` | Access control definitions | When using `@stonyx/orm` |
+| `transforms/` | Value transforms | When using `@stonyx/orm` |
+| `hooks/` | Lifecycle hooks | When using `@stonyx/orm` |
+| `requests/` | REST request handlers | When using `@stonyx/rest-server` |
+| `crons/` | Scheduled tasks | When using `@stonyx/cron` |
+| `clients/` | External API clients | When fetching external data |
+| `resources/` | Business logic resources | As needed |
+| `test/` | Tests | Always |
+| `utils.js` or `utils/` | Project-specific reusable logic | As needed (never duplicate `@stonyx/utils`) |
+
+### Nested Model Directories
+
+Use nested directories under `models/` for `belongsTo` child models:
+
+```
+models/
+  character.js
+  character/
+    relationship.js
+```
+
+## Config Conventions
+
+### `config/environment.js`
+
+Destructure env vars at the top, apply defaults with `??`, export a plain object:
+
+```js
+const {
+  CORS_ORIGIN,
+  DB_FILE,
+  NODE_ENV,
+  REST_PORT,
+} = process.env;
+
+const environment = NODE_ENV ?? 'development';
+
+export default {
+  orm: {
+    db: {
+      file: DB_FILE ?? 'db.json',
+      schema: './config/db-schema.js'
+    }
+  },
+  restServer: {
+    origin: CORS_ORIGIN ?? '*',
+    port: REST_PORT ?? 3000
+  }
+}
+```
+
+**Do NOT re-declare module defaults.** Only include config values that differ from the module's built-in defaults.
+
+### `config/db-schema.js`
+
+Extends `Model` and uses `hasMany` to define each collection:
+
+```js
+import { Model, hasMany } from '@stonyx/orm';
+
+export default class DBModel extends Model {
+  owners = hasMany('owner');
+  animals = hasMany('animal');
+}
+```
+
+## Reference Projects
+
+- `smart-lock-backend/` — full example with REST, ORM, sockets, crons, hooks
+- `nextgoal-backend/` — example with models, transforms, filters, bot commands

package/docs/conventions/rest-conventions.md

@@ -0,0 +1,96 @@
+# REST Conventions
+
+## Request Classes
+
+One request class per file in `requests/`. Each class extends `Request` from `@stonyx/rest-server`.
+
+**Class ordering:** properties → `handlers` object → `auth()` hook → validation/middleware methods
+
+### Public Request (no auth)
+
+```js
+import { Request } from '@stonyx/rest-server';
+
+export default class PublicRequest extends Request {
+  testProp = 'stonyx';
+
+  handlers = {
+    get: {
+      '/': (_request, _state) => {
+        return { data: 'foo' };
+      },
+
+      '/url-params/:x/:y/:z': ({ params }, _state) => {
+        return params;
+      },
+
+      // Middleware chaining: [middlewareFn, handlerFn]
+      '/foo': [this.validationSuccessSample, (_request, state) => {
+        return { data: state };
+      }],
+
+      '/fail': [this.validationFailureSample, (_request, _state) => {
+        return { unreachable: 'response' };
+      }],
+    }
+  }
+
+  validationSuccessSample(_request, state) {
+    state.newProp = 'bar';
+  }
+
+  validationFailureSample() {
+    return 504; // returning a status code rejects the request
+  }
+}
+```
+
+### Private Request (with auth)
+
+```js
+import { Request } from '@stonyx/rest-server';
+
+export default class PrivateRequest extends Request {
+  handlers = {
+    get: {
+      '/success': (_request, _state) => {
+        return { data: 'foo' };
+      },
+
+      '/failure': (_request, _state) => {
+        return { data: 'foo' };
+      }
+    }
+  }
+
+  auth(request, _state) {
+    if (request.path === '/failure') return 505;
+  }
+}
+```
+
+## Key Patterns
+
+### `handlers` Object
+
+Keyed by HTTP method (`get`, `post`, `put`, `delete`), each containing route-to-handler mappings.
+
+Handler signature: `(request, state) => responseData`
+
+### Middleware Chaining
+
+Use `[middlewareFn, handlerFn]` arrays to chain middleware before a handler. The middleware function receives `(request, state)` and can:
+- Mutate `state` to pass data to the handler
+- Return a status code number to reject the request early
+
+### `auth()` Hook
+
+Runs before all handlers in the class. Return an error status code to reject the request. If `auth()` returns nothing (undefined), the request proceeds.
+
+### Route Parameters
+
+Express-style route params (`:param`) are available via `request.params`.
+
+### Binding
+
+Handler functions defined as arrow functions or class methods have access to `this` (the request class instance).