stonyx 0.2.3-beta.37 → 0.2.3-beta.38

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.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/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,47 @@
+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']));
+            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,3 @@
+export default function newCommand({ args }: {
+    args: string[];
+}): Promise<void>;

package/dist/cli/new.js

@@ -0,0 +1,204 @@
+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/dist/cli/serve.d.ts

@@ -0,0 +1,5 @@
+import { type StoynxModule } from '../lifecycle.js';
+export declare function createShutdownHandler(modules: StoynxModule[]): () => Promise<void>;
+export default function serve({ args }: {
+    args: string[];
+}): Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,29 @@
+import { runStartupHooks, runShutdownHooks } from '../lifecycle.js';
+export function createShutdownHandler(modules) {
+    let shuttingDown = false;
+    return async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await runShutdownHooks(modules);
+        process.exit(0);
+    };
+}
+export default async function serve({ args }) {
+    const cwd = process.cwd();
+    const entryFlag = args.indexOf('--entry');
+    const entryPoint = entryFlag !== -1 ? args[entryFlag + 1] : 'app.js';
+    const { default: config } = await import(`${cwd}/config/environment.js`);
+    const { default: Stonyx } = await import('../main.js');
+    new Stonyx(config, cwd);
+    await Stonyx.ready;
+    const { modules } = Stonyx.instance;
+    await runStartupHooks(modules);
+    const shutdown = createShutdownHandler(modules);
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    const entryModule = await import(`${cwd}/${entryPoint}`);
+    if (entryModule.default) {
+        new entryModule.default();
+    }
+}

package/dist/cli/test-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/{src → dist}/cli/test-setup.js

@@ -1,8 +1,5 @@
-import { pathToFileURL } from 'url';
-
-const cwd = process.cwd();
-
-const { default: Stonyx } = await import('stonyx');
-const { default: config } = await import(pathToFileURL(`${cwd}/config/environment.js`));
-
-new Stonyx(config, cwd);
+import { pathToFileURL } from 'url';
+const cwd = process.cwd();
+const { default: Stonyx } = await import('stonyx');
+const { default: config } = await import(pathToFileURL(`${cwd}/config/environment.js`).href);
+new Stonyx(config, cwd);

package/dist/cli/test.d.ts

@@ -0,0 +1,3 @@
+export default function test({ args }: {
+    args: string[];
+}): Promise<void>;

package/dist/cli/test.js

@@ -0,0 +1,23 @@
+import { spawn } from 'child_process';
+import { fileURLToPath, pathToFileURL } from 'url';
+import path from 'path';
+export default async function test({ args }) {
+    const cwd = process.cwd();
+    const setupFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'test-setup.js');
+    const setupFileUrl = pathToFileURL(setupFile).href;
+    const qunitBin = path.resolve(cwd, 'node_modules/qunit/bin/qunit.js');
+    // Default to conventional test glob if no args provided
+    const testArgs = args.length > 0 ? args : ['test/**/*-test.js'];
+    const child = spawn(process.execPath, [
+        '--import', setupFileUrl,
+        qunitBin,
+        ...testArgs
+    ], {
+        cwd,
+        stdio: 'inherit',
+        env: { ...process.env, NODE_ENV: 'test' }
+    });
+    child.on('close', (code) => {
+        process.exit(code ?? 1);
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+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', 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 }
+};
+const args = process.argv.slice(2);
+const commandName = aliases[args[0]] || args[0];
+const commandArgs = args.slice(1);
+async function main() {
+    if (!commandName || commandName === 'help') {
+        await help({ args: commandArgs, builtInCommands, loadModuleCommands });
+        return;
+    }
+    const builtIn = builtInCommands[commandName];
+    if (builtIn) {
+        await builtIn.run({ args: commandArgs });
+        return;
+    }
+    // Search module commands
+    const moduleCommands = await loadModuleCommands();
+    const moduleCommand = moduleCommands[commandName];
+    if (moduleCommand) {
+        const cwd = process.cwd();
+        if (moduleCommand.bootstrap) {
+            const { default: config } = await import(`${cwd}/config/environment.js`);
+            const { default: Stonyx } = await import('./main.js');
+            new Stonyx(config, cwd);
+            await Stonyx.ready;
+        }
+        await moduleCommand.run({ args: commandArgs, cwd });
+        return;
+    }
+    console.error(`Unknown command: ${args[0]}\n`);
+    await help({ args: [], builtInCommands, loadModuleCommands });
+    process.exit(1);
+}
+main().catch(error => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/exports/config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../modules.js").StoynxConfig;
+export default _default;

package/dist/exports/config.js

@@ -0,0 +1,2 @@
+import Stonyx from 'stonyx';
+export default Stonyx.config;

package/dist/exports/log.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@stonyx/logs").default;
+export default _default;

package/{src → dist}/exports/log.js

@@ -1,3 +1,2 @@
 import Stonyx from 'stonyx';
-
-export default Stonyx.log;
+export default Stonyx.log;

package/dist/exports/test-helpers.d.ts

@@ -0,0 +1,5 @@
+interface TestHooks {
+    before(fn: () => Promise<void>): void;
+}
+export declare function setupIntegrationTests(hooks: TestHooks): void;
+export {};

package/dist/exports/test-helpers.js

@@ -0,0 +1,7 @@
+import Stonyx from 'stonyx';
+export function setupIntegrationTests(hooks) {
+    hooks.before(async function () {
+        await Stonyx.ready;
+        console.log('Stonyx ready');
+    });
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,7 @@
+export interface StoynxModule {
+    init?(): Promise<void>;
+    startup?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+export declare function runStartupHooks(modules: StoynxModule[]): Promise<void>;
+export declare function runShutdownHooks(modules: StoynxModule[]): Promise<void>;

package/dist/lifecycle.js

@@ -0,0 +1,18 @@
+export async function runStartupHooks(modules) {
+    for (const module of modules) {
+        if (typeof module.startup === 'function')
+            await module.startup();
+    }
+}
+export async function runShutdownHooks(modules) {
+    for (const module of [...modules].reverse()) {
+        if (typeof module.shutdown === 'function') {
+            try {
+                await module.shutdown();
+            }
+            catch (error) {
+                console.error('Error during module shutdown:', error);
+            }
+        }
+    }
+}

package/dist/main.d.ts

@@ -0,0 +1,21 @@
+import Chronicle from '@stonyx/logs';
+import type { StoynxModule } from './lifecycle.js';
+import type { StoynxConfig } from './modules.js';
+export default class Stonyx {
+    static initialized: boolean;
+    static modulePromises: Record<string, unknown>;
+    static instance: Stonyx;
+    static ready: Promise<void>;
+    config: StoynxConfig;
+    chronicle: Chronicle;
+    modules: StoynxModule[];
+    constructor(config: StoynxConfig, rootPath: string);
+    start(config: StoynxConfig, rootPath: string): Promise<void>;
+    /**
+     * Allows users to define their own log for any extra class via environment config
+     */
+    configureUserLogs(): void;
+    static get log(): Chronicle;
+    static get config(): StoynxConfig;
+}
+export { waitForModule } from './modules.js';

package/dist/main.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import Chronicle from '@stonyx/logs';
+import loadModules from './modules.js';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { mergeObject } from '@stonyx/utils/object';
+export default class Stonyx {
+    static initialized = false;
+    static modulePromises = {};
+    static instance;
+    static ready;
+    config;
+    chronicle;
+    modules;
+    constructor(config, rootPath) {
+        if (Stonyx.instance)
+            return Stonyx.instance;
+        Stonyx.instance = this;
+        Stonyx.ready = this.start(config, rootPath);
+    }
+    async start(config, rootPath) {
+        if (!config)
+            throw new Error('Stonyx requires full environment configuration on startup');
+        if (!rootPath)
+            throw new Error('Stonyx requires root project\'s path on startup');
+        // Transform config from stonyx-modules running as a standalone
+        if (rootPath.includes('stonyx-')) {
+            const moduleName = kebabCaseToCamelCase(rootPath.split('/').pop().replace('stonyx-', ''));
+            config = { [moduleName]: config, ...(config.modules || {}) };
+            delete config.modules;
+        }
+        this.config = config;
+        this.chronicle = new Chronicle({ additionalLogs: { title: 'green' } });
+        Stonyx.initialized = true;
+        // Auto-merge test environment overrides (after initialized flag, before modules load)
+        // Uses in-place mutation to preserve existing references (e.g. stonyx/config export cache)
+        if (process.env.NODE_ENV === 'test') {
+            try {
+                const { default: testOverrides } = await import(`${rootPath}/test/config/environment.js`);
+                const merged = mergeObject(config, testOverrides);
+                Object.assign(config, merged);
+            }
+            catch { /* no test overrides found */ }
+        }
+        this.modules = await loadModules(config, rootPath, this.chronicle);
+        this.configureUserLogs();
+    }
+    /**
+     * Allows users to define their own log for any extra class via environment config
+     */
+    configureUserLogs() {
+        const { chronicle } = this;
+        for (const [className, config] of Object.entries(this.config)) {
+            if (!config || typeof config !== 'object')
+                continue;
+            if (chronicle[className])
+                continue;
+            const { logColor, logMethod, logTimestamp } = config;
+            if (!logColor)
+                continue;
+            chronicle.defineType(logMethod || className, logColor, { logTimestamp: !!logTimestamp });
+        }
+    }
+    static get log() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.chronicle;
+    }
+    static get config() {
+        if (!Stonyx.initialized)
+            throw new Error('Stonyx has not been initialized yet');
+        return Stonyx.instance.config;
+    }
+}
+export { waitForModule } from './modules.js';

package/dist/modules.d.ts

@@ -0,0 +1,5 @@
+import type { StoynxModule } from './lifecycle.js';
+import type Chronicle from '@stonyx/logs';
+export type StoynxConfig = Record<string, Record<string, unknown> | unknown>;
+export default function loadModules(config: StoynxConfig, rootPath: string, chronicle: Chronicle): Promise<StoynxModule[]>;
+export declare function waitForModule(moduleName: string): Promise<void>;