stonyx 0.2.3-alpha.7 → 0.2.3-alpha.71

package/README.md

@@ -1,26 +1,45 @@
+[![CI](https://github.com/abofs/stonyx/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/stonyx.svg)](https://www.npmjs.com/package/stonyx)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # Stonyx
 
 **Stonyx** is a lightweight, modular framework for building modern Node.js applications. It provides a plug-and-play architecture, centralized color-coded logging, and seamless async module integration.
 
-- 100% JavaScript (ES Modules)
 - Drop-in module system — no boilerplate
 - Automatic async module loading and initialization
-- Built-in CLI for bootstrapping and testing
+- Built-in CLI for scaffolding, bootstrapping, and testing
 
 ## Quick Start
 
 ```bash
-npm install stonyx
+npm install -g stonyx
+stonyx new my-app
+cd my-app
+stonyx serve
 ```
 
-The CLI handles everything — no manual `new Stonyx()` calls needed:
+The `new` command walks you through module selection and generates a ready-to-run project. From there, the CLI handles bootstrapping:
 
 ```bash
-stonyx serve    # Bootstrap + run app.js
+stonyx serve    # Bootstrap + run app.ts (or 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.
+Stonyx reads `config/environment.ts` (preferred) or `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
+
+## Exports
+
+| Import | Exports |
+|--------|---------|
+| `stonyx` | `Stonyx` class (default), `waitForModule(name)`; type `StoynxConfig` |
+| `stonyx/config` | The Stonyx config object (default), bound at first import |
+| `stonyx/log` | The Chronicle logger (default), bound at first import |
+| `stonyx/lifecycle` | `runStartupHooks(modules)`, `runShutdownHooks(modules)` |
+| `stonyx/test-helpers` | `setupIntegrationTests(hooks)` |
+
+`stonyx/config` and `stonyx/log` throw at import time if Stonyx is not yet initialized, so a static `import` of either fails the importing module even if the value is never read. Import them only from code that loads after bootstrap (your app code under `stonyx serve`, or a module's `init()` path). Their default export is bound once, at first import, so it does not follow an in-process reboot (see [Testing](docs/testing.md#booting-stonyx-more-than-once-in-one-process)). See the [API Reference](docs/api.md) for details.
 
 ## Documentation
 
@@ -40,8 +59,12 @@ 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/rest-server](https://github.com/abofs/stonyx-rest-server) | Dynamic REST server with auto-route registration |
+| [@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 |
 
 ## License
 

package/config/{environment.js → environment copy.ts }

@@ -1,12 +1,16 @@
-// project configuration, override-able by listed environment variables
-const {
-  DEBUG,
-  NODE_ENV,
-} = process.env;
-
-const environment = NODE_ENV ?? 'development';
-
-export default {
-  environment,
-  debug: DEBUG ?? environment === 'development',
-}
+import type { StoynxConfig } from 'stonyx';
+
+// project configuration, override-able by listed environment variables
+const {
+  DEBUG,
+  NODE_ENV,
+} = process.env;
+
+const environment = NODE_ENV ?? 'development';
+
+const config: StoynxConfig = {
+  environment,
+  debug: DEBUG ?? environment === 'development',
+};
+
+export default config;

package/dist/cli/help.d.ts

@@ -0,0 +1,8 @@
+import type { CommandDefinition } from './load-commands.js';
+interface HelpOptions {
+    args?: string[];
+    builtInCommands?: Record<string, CommandDefinition>;
+    loadModuleCommands?: () => Promise<Record<string, CommandDefinition>>;
+}
+export default function help({ args, builtInCommands, loadModuleCommands }?: HelpOptions): Promise<void>;
+export {};

package/dist/cli/help.js

@@ -0,0 +1,43 @@
+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.ts (or app.js)');
+    console.log('  Config:            config/environment.ts (or .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/dist/cli/load-commands.d.ts

@@ -0,0 +1,10 @@
+export interface CommandDefinition {
+    description: string;
+    run: (ctx: {
+        args: string[];
+        cwd?: string;
+    }) => Promise<void>;
+    bootstrap?: boolean;
+    module?: string;
+}
+export default function loadModuleCommands(): Promise<Record<string, CommandDefinition>>;

package/dist/cli/load-commands.js

@@ -0,0 +1,49 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+export default async function loadModuleCommands() {
+    const cwd = process.cwd();
+    const commands = {};
+    let projectPackage;
+    try {
+        const raw = await readFile(path.join(cwd, 'package.json'), 'utf8');
+        projectPackage = JSON.parse(raw);
+    }
+    catch {
+        return commands;
+    }
+    const allDeps = {
+        ...projectPackage.dependencies,
+        ...projectPackage.devDependencies
+    };
+    const stonyxModules = Object.keys(allDeps).filter(name => name.startsWith('@stonyx/'));
+    for (const moduleName of stonyxModules) {
+        let modulePackage;
+        try {
+            const raw = await readFile(path.join(cwd, 'node_modules', moduleName, 'package.json'), 'utf8');
+            modulePackage = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const moduleExports = modulePackage.exports;
+        if (!moduleExports || !moduleExports['./commands'])
+            continue;
+        try {
+            const commandsModule = await import(path.join(cwd, 'node_modules', moduleName, moduleExports['./commands']));
+            if (!commandsModule.default || typeof commandsModule.default !== 'object')
+                continue;
+            const moduleCommands = commandsModule.default;
+            for (const [name, command] of Object.entries(moduleCommands)) {
+                if (commands[name]) {
+                    console.warn(`Warning: Command "${name}" from ${moduleName} conflicts with existing command. Skipping.`);
+                    continue;
+                }
+                commands[name] = { ...command, module: moduleName };
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return commands;
+}

package/dist/cli/new.d.ts

@@ -0,0 +1,72 @@
+interface ModuleOption {
+    question: string;
+    package: string;
+    dirs?: string[];
+    files?: Record<string, () => string>;
+}
+export declare const MODULE_OPTIONS: ModuleOption[];
+export declare function generateDbSchema(): string;
+/**
+ * The version of the `stonyx` package running this generator, read from its own
+ * `package.json` at call time.
+ *
+ * Read rather than hardcoded on purpose: a literal would be correct on the day
+ * it was written and silently stale on every day after (abofs/stonyx#113).
+ */
+export declare function readCoreVersion(): string;
+/**
+ * The npm dist-tag naming the release line a version belongs to:
+ * `0.2.3-beta.96` -> `beta`, `0.2.3-alpha.4` -> `alpha`, `0.2.2` -> `latest`.
+ *
+ * Every scaffolded `@stonyx/*` module is requested on the same line as the core
+ * that scaffolded it, so the generated project cannot mix a prerelease core with
+ * modules from the stable line (or the reverse).
+ *
+ * Throws, rather than guessing, when the prerelease identifier is not usable as a
+ * dist-tag. Returning it verbatim was only safe for *alphabetic* identifiers: npm
+ * parses a numeric or wildcard identifier as a version **range**, so `0.2.3-0`
+ * emitted `"0"` and `0.2.3-x` emitted `"x"`, both of which install with rc=0 and
+ * silently resolve the module's `latest` release -- for `@stonyx/orm` that is
+ * `0.3.1`, which pins `stonyx@0.2.3-beta.11` and so reproduces abofs/stonyx#113
+ * through a different door, with no error. `0.2.3-0` is reachable from this
+ * repo's own `publish.yml` `custom-version` dispatch input, which accepts any
+ * semver string and also expands the keyword `prerelease` to `x.y.z-0`.
+ *
+ * Two bounds remain, both loud rather than silent:
+ *
+ * - An alphabetic identifier is assumed to also be a published dist-tag name.
+ *   True for `beta` and `alpha`, the only two lines the fleet publishes; a core
+ *   released as e.g. `0.2.3-rc.1` with no `rc` dist-tag scaffolds an unresolvable
+ *   module specifier, which fails `pnpm install` with
+ *   `ERR_PNPM_NO_MATCHING_VERSION`. The tag has to exist on every package in
+ *   `MODULE_OPTIONS`, not only on the core.
+ * - On the stable line this returns `latest`, the correct tag for that line -- but
+ *   only useful once the *modules* have advanced their own `latest` tags. Today
+ *   `@stonyx/orm@latest` is `0.3.1` and pins `stonyx@0.2.3-beta.11`, so the module
+ *   `latest` tags must advance before the core's does (abofs/stonyx#115).
+ */
+export declare function releaseTagFor(version: string): string;
+export declare function generatePackageJson(name: string, selectedModules: ModuleOption[], coreVersion?: string): string;
+export declare function generateAppTs(): string;
+export declare function generateEnvironmentTs(): string;
+export declare function generateTestEnvironmentTs(): string;
+export declare function generateSetupTs(): string;
+export declare function generateZzExitTestTs(): string;
+export declare function generateEnvironmentExampleTs(): string;
+export declare function generateGitignore(): string;
+export declare function generateTsConfig(): string;
+/**
+ * Rejects when `pnpm install` fails, either by exiting non-zero or by failing to
+ * spawn. Exported so the rejection path is testable without a network round-trip.
+ */
+export declare function runPnpmInstall(projectDir: string): Promise<void>;
+/**
+ * Write every scaffolded file to disk given a resolved project directory,
+ * app name, and pre-selected module options. Factored out of `newCommand`
+ * so tests can exercise the file-writing path without interactive prompts.
+ */
+export declare function scaffoldProject(projectDir: string, appName: string, selectedModules: ModuleOption[]): Promise<void>;
+export default function newCommand({ args }: {
+    args: string[];
+}): Promise<void>;
+export {};