stonyx 0.2.3-alpha.4 → 0.2.3-alpha.40

package/scripts/acceptance-ratchet.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/*
+ * Expected-failures ratchet for the fresh-clone scaffold acceptance harness.
+ *
+ * The harness (abofs/stonyx#89) is RED BY DESIGN until #90, #91 and #92 land.
+ * Running it bare in CI produces a permanently-red check, which is the highest-
+ * leverage place for a vacuous check to hide: nobody re-examines a check that is
+ * always red, and it cannot signal a NEW failure because it is already failing.
+ *
+ * This wrapper diffs the observed red set against
+ * `test/acceptance/expected-failures.json` IN BOTH DIRECTIONS:
+ *
+ *   green today  — the known reds are the baseline, so nobody is trained to
+ *                  ignore a red check;
+ *   red on new   — an unlisted failure is a regression;
+ *   red on fixed — an assertion that starts PASSING while still listed fails the
+ *                  job, which mechanically forces each of #90-#92 to shrink the
+ *                  baseline in its own PR.
+ *
+ * Usage: pnpm test:acceptance:ratchet
+ */
+import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BASELINE = path.join(REPO_ROOT, 'test', 'acceptance', 'expected-failures.json');
+
+// The control flags hand-patch the generated project, so a controlled run says
+// nothing about the baseline. Refuse rather than silently ratchet against it.
+if (process.env.STONYX_ACCEPTANCE_CONTROL) {
+  console.error(
+    'STONYX_ACCEPTANCE_CONTROL is set. The ratchet compares an UNMODIFIED run against the\n' +
+    'baseline; a control run hand-patches the generated project and would falsify it.\n' +
+    'Run `pnpm test:acceptance` directly to exercise a control.'
+  );
+  process.exit(2);
+}
+
+const baseline = JSON.parse(readFileSync(BASELINE, 'utf8'));
+const modulePrefix = `${baseline.module} > `;
+const expected = new Map(baseline.expectedFailures.map(entry => [entry.name, entry.issue]));
+
+const child = spawn(
+  process.execPath,
+  ['--import', 'tsx', 'node_modules/qunit/bin/qunit.js', 'test/acceptance/**/*-test.ts'],
+  { cwd: REPO_ROOT, env: { ...process.env, STONYX_ACCEPTANCE: '1' }, stdio: ['inherit', 'pipe', 'inherit'] }
+);
+
+let tap = '';
+
+child.stdout.on('data', chunk => {
+  tap += String(chunk);
+  process.stdout.write(chunk);
+});
+
+child.on('close', () => {
+  const observed = new Map();
+
+  for (const line of tap.split('\n')) {
+    const match = /^(not ok|ok) \d+ (.*)$/.exec(line.trim());
+    if (!match) continue;
+
+    const name = match[2].startsWith(modulePrefix) ? match[2].slice(modulePrefix.length) : match[2];
+    observed.set(name, match[1] === 'ok');
+  }
+
+  if (observed.size === 0) {
+    fail(['The acceptance run produced no TAP assertions at all. This is a harness or setup failure, not a result.']);
+  }
+
+  const problems = [];
+
+  for (const [name, passed] of observed) {
+    if (!passed && !expected.has(name)) {
+      problems.push(`NEW FAILURE (not in the baseline): ${name}\n    A regression, or an assertion that needs an owning issue before it is baselined.`);
+    }
+
+    if (passed && expected.has(name)) {
+      problems.push(
+        `NOW PASSING but still baselined (issue #${expected.get(name)}): ${name}\n` +
+        '    Delete this entry from test/acceptance/expected-failures.json in the PR that fixed it.'
+      );
+    }
+  }
+
+  for (const name of expected.keys()) {
+    if (!observed.has(name)) {
+      problems.push(`BASELINED ASSERTION NOT FOUND: ${name}\n    It was renamed or removed. Update the baseline in the same PR.`);
+    }
+  }
+
+  if (problems.length) fail(problems);
+
+  const stillRed = [...expected.keys()].filter(name => observed.get(name) === false);
+
+  console.log(`\n# acceptance ratchet: OK — ${observed.size} assertions, ${stillRed.length} expected failures, 0 unexpected.`);
+  for (const name of stillRed) console.log(`#   expected red (#${expected.get(name)}): ${name}`);
+  process.exit(0);
+});
+
+function fail(problems) {
+  console.error('\n# acceptance ratchet: FAILED\n');
+  for (const problem of problems) console.error(`  - ${problem}\n`);
+  console.error('See test/acceptance/expected-failures.json and docs/testing.md.');
+  process.exit(1);
+}

package/scripts/postinstall.js

@@ -1,11 +1,37 @@
-import { copyFile, createDirectory } from '@stonyx/utils/file';
+// Skip postinstall for global installations
+const isGlobal = !process.env.INIT_CWD || process.env.npm_config_global === 'true';
+if (isGlobal) process.exit(0);
+
+const { existsSync } = await import('node:fs');
+const { copyFile, createDirectory } = await import('@stonyx/utils/file');
 
 const projectDir = process.env.INIT_CWD;
 const configDir = `${projectDir}/config`;
-const envFile = 'environment.js';
+
+// Detect consumer project type: presence of `tsconfig.json` in the consumer
+// root signals a TypeScript project (see abofs/stonyx#62). TS consumers can't
+// use the `.js` stub, so we ship both templates and copy the matching one.
+const isTypeScriptConsumer = existsSync(`${projectDir}/tsconfig.json`);
+const extension = isTypeScriptConsumer ? 'ts' : 'js';
+const envFile = `environment.${extension}`;
+const templateFile = `environment copy.${extension}`;
+
+// Skip if the consumer ships its own `config/environment copy.{ts,js}` template —
+// they manage their own bootstrap (see abofs/stonyx#54, extended in abofs/stonyx#62
+// to honor either extension).
+if (
+  existsSync(`${configDir}/environment copy.ts`) ||
+  existsSync(`${configDir}/environment copy.js`)
+) process.exit(0);
+
+// Don't overwrite an existing consumer config (either extension).
+if (
+  existsSync(`${configDir}/environment.ts`) ||
+  existsSync(`${configDir}/environment.js`)
+) process.exit(0);
 
 createDirectory(configDir);
 
-copyFile(`./config/environment copy.js`, `${configDir}/${envFile}`).then(result => {
+copyFile(`./config/${templateFile}`, `${configDir}/${envFile}`).then(result => {
   if (result) console.log(`Stonyx: ${envFile} has been successfully created. Please see README.md for more information.`);
 });

package/.claude/index.md

@@ -1,96 +0,0 @@
-# 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/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

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.