stonyx 0.2.3-beta.5 → 0.2.3-beta.7

package/.claude/index.md

@@ -0,0 +1,96 @@
+# Stonyx CLI Guide
+
+See [docs/index.md](../docs/index.md) for full documentation including conventions, modules, lifecycle, and API reference.
+
+## Installation
+
+Stonyx is the core framework package. The CLI is provided by the `stonyx` binary defined in `package.json`.
+
+In a project that depends on `stonyx`:
+
+```bash
+pnpm add -D stonyx
+```
+
+The CLI is then available as `npx stonyx` or via pnpm scripts.
+
+## Commands
+
+### `stonyx serve` (alias: `s`)
+
+Bootstrap Stonyx and run the application.
+
+```bash
+stonyx serve              # loads app.js by default
+stonyx serve --entry custom.js  # custom entry point
+```
+
+Behavior:
+1. Loads `.env` file
+2. Imports `config/environment.js`
+3. Initializes Stonyx with all detected `@stonyx/*` modules
+4. Runs startup lifecycle hooks
+5. Imports and instantiates the entry point class
+6. Registers SIGTERM/SIGINT handlers for graceful shutdown
+
+### `stonyx test` (alias: `t`)
+
+Bootstrap Stonyx in test mode and run QUnit tests.
+
+```bash
+stonyx test                          # runs test/**/*-test.js
+stonyx test test/unit/foo-test.js    # specific file
+stonyx test "test/integration/**/*-test.js"  # glob pattern
+```
+
+Sets `NODE_ENV=test` and auto-loads test setup which merges `test/config/environment.js` overrides.
+
+### `stonyx help` (alias: `h`)
+
+Show available commands including built-in and module-provided commands.
+
+```bash
+stonyx help
+stonyx --help
+stonyx -h
+```
+
+### `stonyx new <app-name>`
+
+Scaffold a new Stonyx project with interactive module selection.
+
+```bash
+stonyx new my-backend
+```
+
+Prompts for:
+- Package name
+- Which `@stonyx/*` modules to include (REST server, WebSockets, ORM, cron, OAuth, events)
+
+Creates:
+- `package.json` with selected dependencies
+- `app.js` entry point
+- `config/environment.js` and `config/environment.example.js`
+- Module-specific directories (`models/`, `requests/`, `crons/`, etc.)
+- `test/` structure with `unit/`, `integration/`, `acceptance/`
+- `.gitignore` and `.nvmrc`
+- Runs `pnpm install`
+
+## Module Command System
+
+Stonyx modules can register CLI commands by exporting a `./commands` entry in their `package.json` exports map. The CLI auto-discovers these from installed `@stonyx/*` packages.
+
+Module commands appear under "Module commands" in `stonyx help` output. They can optionally request Stonyx bootstrap before running (via `bootstrap: true`).
+
+## Creating a Stonyx Project Manually
+
+If not using `stonyx new`:
+
+1. Create project directory
+2. Add `.nvmrc` with current LTS Node version
+3. `pnpm init` and set `"type": "module"`
+4. `pnpm add -D stonyx` plus desired `@stonyx/*` modules
+5. Create `config/environment.js` with module config
+6. Create `app.js` entry point class
+7. Create standard directories per selected modules
+8. Add `@abofs/code-conventions` for linting

package/docs/conventions/discord-conventions.md

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

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

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

@@ -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,105 @@
+# 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 |
+| `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).

package/docs/conventions/testing-conventions.md

@@ -0,0 +1,56 @@
+# Testing Conventions
+
+## Directory Structure
+
+```
+test/
+  unit/
+  integration/
+  acceptance/
+  config/
+    environment.js    # test config overrides
+  sample/             # fixtures and mocks (alternative: test/mocks/)
+```
+
+## File Naming
+
+All test files use the `*-test.js` suffix: `animal-test.js`, `public-request-test.js`.
+
+## Test Framework
+
+- **QUnit** — test framework
+- **Sinon** — stubs, spies, and mocks
+
+Run tests with `stonyx test` (alias: `stonyx t`), which:
+1. Sets `NODE_ENV=test`
+2. Loads test setup (bootstrap with test config overrides)
+3. Runs QUnit against `test/**/*-test.js`
+
+## Test Config Overrides
+
+Place test-specific config at `test/config/environment.js`. Stonyx auto-merges these overrides when running in test mode.
+
+## Sample / Fixture Files
+
+Each stonyx module's `test/sample/` directory contains reference implementations. Mirror this structure in your project tests:
+
+- `test/sample/models/` — model fixtures
+- `test/sample/serializers/` — serializer fixtures
+- `test/sample/access/` — access control fixtures
+- `test/sample/transforms/` — transform fixtures
+- `test/sample/requests/` — request handler fixtures
+
+The file ordering in tests should mirror the sample files from each module's `test/sample/` directory.
+
+## Running Tests
+
+```bash
+# Run all tests
+stonyx test
+
+# Run specific test file
+stonyx test test/unit/animal-test.js
+
+# Run specific glob
+stonyx test "test/integration/**/*-test.js"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-beta.5",
+  "version": "0.2.3-beta.7",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",
@@ -33,7 +33,7 @@
     "node-chronicle": "^0.2.0"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.4",
+    "@stonyx/utils": "0.2.3-beta.5",
     "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

@@ -3,15 +3,17 @@
 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 }
 };