stonyx 0.2.3-alpha.6 → 0.2.3-alpha.8

package/README.md

@@ -5,23 +5,19 @@
 - 100% JavaScript (ES Modules)
 - Drop-in module system — no boilerplate
 - Automatic async module loading and initialization
-- Built-in CLI for scaffolding, bootstrapping, and testing
+- Built-in CLI for bootstrapping and testing
 
 ## Quick Start
 
 ```bash
-npm install -g stonyx
-stonyx new my-app
-cd my-app
-stonyx serve
+npm install stonyx
 ```
 
-The `new` command walks you through module selection and generates a ready-to-run project. From there, the CLI handles bootstrapping:
+The CLI handles everything — no manual `new Stonyx()` calls needed:
 
 ```bash
 stonyx serve    # Bootstrap + run app.js
 stonyx test     # Bootstrap + run tests
-stonyx help     # Show all available commands
 ```
 
 Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
@@ -44,12 +40,8 @@ Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from y
 | Module | Description |
 |--------|-------------|
 | [@stonyx/cron](https://github.com/abofs/stonyx-cron) | Lightweight async job scheduling |
-| [@stonyx/discord](https://github.com/abofs/stonyx-discord) | Discord bot with command and event handler auto-discovery |
-| [@stonyx/events](https://github.com/abofs/stonyx-events) | Pub/sub event system |
-| [@stonyx/oauth](https://github.com/abofs/stonyx-oauth) | OAuth provider integration |
-| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, and serializers |
 | [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
-| [@stonyx/sockets](https://github.com/abofs/stonyx-sockets) | WebSocket server and client |
+| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, and serializers |
 
 ## License
 

package/docs/cli.md

@@ -12,20 +12,10 @@ stonyx <command> [...args]
 
 | Command | Alias | Description |
 |---------|-------|-------------|
-| `new` | `n` | Scaffold a new Stonyx project |
 | `serve` | `s` | Bootstrap Stonyx and run the app |
 | `test` | `t` | Bootstrap Stonyx in test mode and run tests |
 | `help` | `h` | Show available commands |
 
-### new
-
-Scaffolds a new Stonyx project in the current directory. Prompts for a project name and which modules to include, then generates the project structure and runs `pnpm install`.
-
-```bash
-stonyx new              # Prompts for project name
-stonyx new my-app       # Creates my-app/ in the current directory
-```
-
 ### serve
 
 Bootstraps Stonyx (loads config, initializes modules, runs lifecycle hooks), then imports your application entry point.

package/docs/conventions/cron-conventions.md

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

@@ -86,9 +86,22 @@ All pub/sub event handling. Never create custom event emitters.
 
 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

package/docs/conventions/index.md

@@ -18,6 +18,7 @@ Universal rules that apply to every Stonyx project. Section-specific 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

package/docs/conventions/orm-conventions.md

@@ -156,3 +156,35 @@ export default class DBModel extends Model {
 ```
 
 Located at `config/db-schema.js`, referenced from `config/environment.js`.
+
+## Store
+
+The store is the in-memory data layer. Use it for internal app logic (not REST API consumers).
+
+```js
+import Orm, { store, createRecord, updateRecord } from '@stonyx/orm';
+
+// Read — sync, from memory (requires memory: true on model, which is the default)
+const record = store.get('animal', 1);
+const allAnimals = store.data.get('animals');
+
+// Read — async, queries DB if memory: false
+const record = await store.find('animal', 1);
+const all = await store.findAll('animal');
+
+// Create — adds to store and returns the record
+const animal = createRecord('animal', { type: 'dog', age: 3, owner: 'angela' });
+
+// Update — patches fields on an existing record
+updateRecord(animal, { age: 4 });
+
+// Delete
+store.remove('animal', 1);
+
+// Persist to disk — required when not using REST-triggered autosave
+await Orm.db.save();
+```
+
+**When to use `Orm.db.save()`**: The `autosave: 'onUpdate'` config only triggers on REST POST/PATCH/DELETE. When modifying data directly via `createRecord` / `updateRecord` in app code (not through REST), call `Orm.db.save()` explicitly to persist.
+
+**Store vs REST**: Use `store` for internal app logic (session tracking, state management). Use REST request handlers for external API consumers. Both operate on the same in-memory data.

package/docs/modules.md

@@ -72,11 +72,7 @@ await waitForModule('rest-server'); // Waits for @stonyx/rest-server
 | Module | Description |
 |--------|-------------|
 | [@stonyx/cron](https://github.com/abofs/stonyx-cron) | Lightweight async job scheduling with min-heap |
-| [@stonyx/discord](https://github.com/abofs/stonyx-discord) | Discord bot with command and event handler auto-discovery |
-| [@stonyx/events](https://github.com/abofs/stonyx-events) | Pub/sub event system |
-| [@stonyx/oauth](https://github.com/abofs/stonyx-oauth) | OAuth provider integration |
-| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, serializers, and optional REST integration |
 | [@stonyx/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
-| [@stonyx/sockets](https://github.com/abofs/stonyx-sockets) | WebSocket server and client |
+| [@stonyx/orm](https://github.com/abofs/stonyx-orm) | ORM with models, relationships, serializers, and optional REST integration |
 
 See each module's repository for its specific documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-alpha.6",
+  "version": "0.2.3-alpha.8",
   "description": "Base stonyx framework module",
   "main": "main.js",
   "type": "module",
@@ -30,10 +30,10 @@
     "url": "https://github.com/abofs/stonyx/issues"
   },
   "dependencies": {
-    "@stonyx/utils": "0.2.3-beta.5",
     "node-chronicle": "^0.2.0"
   },
   "devDependencies": {
+    "@stonyx/utils": "0.2.3-beta.7",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0"
   },

package/src/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import serve from './cli/serve.js';
 import test from './cli/test.js';