stonyx 0.2.3-alpha.6 → 0.2.3-alpha.60

package/dist/cli/serve.js

@@ -0,0 +1,49 @@
+import { resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { runStartupHooks, runShutdownHooks } from '../lifecycle.js';
+import { importConfig } from '../util/import-config.js';
+import { resolveEntryPoint } from '../util/resolve-entry-point.js';
+export function createShutdownHandler(modules) {
+    let shuttingDown = false;
+    return async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await runShutdownHooks(modules);
+        process.exit(0);
+    };
+}
+export function maybeRegisterAppShutdown(modules, appInstance, originalShutdown) {
+    if (appInstance &&
+        typeof appInstance.shutdown === 'function') {
+        const appShutdown = createShutdownHandler([
+            ...modules,
+            appInstance
+        ]);
+        process.removeListener('SIGTERM', originalShutdown);
+        process.removeListener('SIGINT', originalShutdown);
+        process.on('SIGTERM', appShutdown);
+        process.on('SIGINT', appShutdown);
+    }
+}
+export default async function serve({ args }) {
+    const cwd = process.cwd();
+    const entryFlag = args.indexOf('--entry');
+    const entryArg = (entryFlag !== -1 && entryFlag + 1 < args.length) ? args[entryFlag + 1] : null;
+    const entryPoint = entryArg !== null ? resolve(cwd, entryArg) : resolveEntryPoint(`${cwd}/app`);
+    const config = await importConfig(`${cwd}/config/environment`);
+    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(pathToFileURL(entryPoint).href);
+    let appInstance;
+    if (entryModule.default) {
+        appInstance = new entryModule.default();
+    }
+    maybeRegisterAppShutdown(modules, appInstance, shutdown);
+}

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

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

package/dist/cli/test-setup.js

@@ -0,0 +1,30 @@
+import { createRequire } from 'module';
+import { importConfig } from '../util/import-config.js';
+const cwd = process.cwd();
+const { default: Stonyx } = await import('stonyx');
+const config = await importConfig(`${cwd}/config/environment`);
+new Stonyx(config, cwd);
+// Drain the event loop once qunit finishes. Modules loaded by Stonyx
+// (e.g. @stonyx/rest-server) may keep listeners/servers open that would
+// otherwise block the process from exiting, causing CI to hit timeouts
+// even though all tests passed.
+//
+// qunit's CLI bin does `delete require.cache[qunitPath]` and re-requires
+// qunit before running, so any qunit instance we grab synchronously from
+// this --import setup is a DIFFERENT object than the one qunit's CLI
+// actually uses. We defer the hook registration with setImmediate so it
+// runs AFTER the qunit bin has populated require.cache with its own
+// instance; grabbing qunit via CJS require at that point returns the
+// instance the tests are running on.
+//
+// See: https://github.com/abofs/stonyx/issues/55
+const require = createRequire(import.meta.url);
+setImmediate(() => {
+    const qunitPath = require.resolve('qunit', {
+        paths: [`${cwd}/node_modules`, cwd]
+    });
+    const QUnit = require(qunitPath);
+    QUnit.on('runEnd', () => {
+        setImmediate(() => process.exit(process.exitCode ?? 0));
+    });
+});

package/dist/cli/test.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_TEST_GLOB = "test/**/*-test.{js,ts}";
+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 const DEFAULT_TEST_GLOB = 'test/**/*-test.{js,ts}';
+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');
+    const testArgs = args.length > 0 ? args : [DEFAULT_TEST_GLOB];
+    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,53 @@
+#!/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';
+import { importConfig } from './util/import-config.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 config = await importConfig(`${cwd}/config/environment`);
+            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("stonyx").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,22 @@
+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';
+export type { StoynxConfig } from './modules.js';

package/dist/main.js

@@ -0,0 +1,102 @@
+/*
+ * 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 { mergeObject } from '@stonyx/utils/object';
+import { importConfig, CONFIG_NOT_FOUND_PREFIX } from './util/import-config.js';
+import { resolveModuleName } from './util/resolve-module-name.js';
+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.
+        // Signal is the consumer's `package.json#name` (see resolveModuleName);
+        // this replaces the brittle `rootPath.includes('stonyx-')` heuristic so
+        // non-canonical rootPaths (worktrees, forks, renames) still work.
+        const moduleName = resolveModuleName(rootPath);
+        if (moduleName) {
+            const flatConfig = config;
+            const siblingModules = flatConfig.modules || {};
+            config = { [moduleName]: config, ...siblingModules };
+            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 testOverrides = await importConfig(`${rootPath}/test/config/environment`);
+                const merged = mergeObject(config, testOverrides);
+                Object.assign(config, merged);
+            }
+            catch (err) {
+                // A test override that is genuinely ABSENT is non-fatal. Everything else
+                // re-throws — including `CONFIG_NOT_LOADABLE_PREFIX`, which is the whole
+                // point of that prefix existing (abofs/stonyx#105, invariant I2). A
+                // config the consumer wrote and this loader declined must never reach
+                // the caller as "you have no test overrides".
+                if (!(err instanceof Error) || !err.message.startsWith(CONFIG_NOT_FOUND_PREFIX))
+                    throw err;
+            }
+        }
+        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 (className in chronicle)
+                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,30 @@
+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[]>;
+/**
+ * Blocks until `@stonyx/<moduleName>` has finished initializing.
+ *
+ * TWO failure sentences, because one sentence stopped being able to carry both
+ * facts. Until PR #120 fix round 1 `modulePromises` held every DECLARED
+ * `@stonyx/*` name, so "absent from the map" and "absent from the manifest"
+ * were the same fact and the single inherited sentence was true. Registration
+ * is now scoped to the DISCOVERED set — which is what removes the boot hang,
+ * see the registration loop in `loadModules` — so absence from the map has two
+ * causes, and the inherited sentence is FALSE for one of them: it tells the
+ * operator the package is not in their dependencies while it is sitting in
+ * their manifest.
+ *
+ * Not hypothetical, and not a shape this repo has to imagine: `@stonyx/logs`
+ * ships without the `stonyx-module` keyword and is an ordinary `dependencies`
+ * entry of THIS package.json. An app in the same shape calling
+ * `waitForModule('logs')` would be sent to grep a manifest that already
+ * contains the answer. Naming the wrong cause is the defect abofs/stonyx#108
+ * was filed over, and it is not made acceptable by being one line long.
+ *
+ * The declared branch does not say WHICH of the two causes applies, because
+ * this function does not know. Discovery does, and it already `console.warn`s
+ * the specific reason at load time, so the message points at that warning
+ * rather than guessing between them.
+ */
+export declare function waitForModule(moduleName: string): Promise<void>;