stonyx 0.2.3-beta.9 → 0.2.3-beta.91
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -5
- package/config/{environment.js → environment copy.ts } +16 -12
- package/dist/cli/help.d.ts +8 -0
- package/dist/cli/help.js +43 -0
- package/dist/cli/load-commands.d.ts +10 -0
- package/dist/cli/load-commands.js +49 -0
- package/dist/cli/new.d.ts +26 -0
- package/dist/cli/new.js +293 -0
- package/dist/cli/serve.d.ts +6 -0
- package/dist/cli/serve.js +49 -0
- package/dist/cli/test-setup.d.ts +1 -0
- package/dist/cli/test-setup.js +30 -0
- package/dist/cli/test.d.ts +4 -0
- package/dist/cli/test.js +23 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +53 -0
- package/dist/exports/config.d.ts +2 -0
- package/dist/exports/config.js +2 -0
- package/dist/exports/log.d.ts +2 -0
- package/{src → dist}/exports/log.js +1 -2
- package/dist/exports/test-helpers.d.ts +5 -0
- package/dist/exports/test-helpers.js +7 -0
- package/dist/lifecycle.d.ts +7 -0
- package/dist/lifecycle.js +18 -0
- package/dist/main.d.ts +22 -0
- package/dist/main.js +98 -0
- package/dist/modules.d.ts +5 -0
- package/dist/modules.js +93 -0
- package/dist/util/import-config.d.ts +1 -0
- package/dist/util/import-config.js +10 -0
- package/dist/util/resolve-entry-point.d.ts +1 -0
- package/dist/util/resolve-entry-point.js +14 -0
- package/dist/util/resolve-module-name.d.ts +14 -0
- package/dist/util/resolve-module-name.js +33 -0
- package/package.json +41 -12
- package/scripts/postinstall.js +24 -2
- package/.claude/index.md +0 -96
- package/.github/workflows/ci.yml +0 -16
- package/.github/workflows/publish.yml +0 -51
- package/docs/api.md +0 -89
- package/docs/cli.md +0 -78
- package/docs/configuration.md +0 -72
- package/docs/conventions/discord-conventions.md +0 -62
- package/docs/conventions/framework-modules.md +0 -127
- package/docs/conventions/index.md +0 -24
- package/docs/conventions/orm-conventions.md +0 -158
- package/docs/conventions/project-structure.md +0 -105
- package/docs/conventions/rest-conventions.md +0 -96
- package/docs/conventions/testing-conventions.md +0 -56
- package/docs/developing-modules.md +0 -108
- package/docs/index.md +0 -15
- package/docs/lifecycle.md +0 -47
- package/docs/logging.md +0 -52
- package/docs/modules.md +0 -78
- package/docs/testing.md +0 -64
- package/src/cli/help.js +0 -48
- package/src/cli/load-commands.js +0 -56
- package/src/cli/new.js +0 -237
- package/src/cli/serve.js +0 -38
- package/src/cli/test-setup.js +0 -8
- package/src/cli/test.js +0 -27
- package/src/cli.js +0 -63
- package/src/exports/config.js +0 -3
- package/src/exports/test-helpers.js +0 -8
- package/src/lifecycle.js +0 -17
- package/src/main.js +0 -101
- package/src/modules.js +0 -112
package/dist/cli.js
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import serve from './cli/serve.js';
|
|
3
|
+
import test from './cli/test.js';
|
|
4
|
+
import help from './cli/help.js';
|
|
5
|
+
import newCommand from './cli/new.js';
|
|
6
|
+
import loadModuleCommands from './cli/load-commands.js';
|
|
7
|
+
import { importConfig } from './util/import-config.js';
|
|
8
|
+
try {
|
|
9
|
+
process.loadEnvFile();
|
|
10
|
+
}
|
|
11
|
+
catch { /* no .env file */ }
|
|
12
|
+
const aliases = { s: 'serve', t: 'test', h: 'help', n: 'new' };
|
|
13
|
+
const builtInCommands = {
|
|
14
|
+
serve: { description: 'Bootstrap Stonyx and run the app', run: serve },
|
|
15
|
+
test: { description: 'Bootstrap Stonyx in test mode and run tests', run: test },
|
|
16
|
+
new: { description: 'Scaffold a new Stonyx project', run: newCommand },
|
|
17
|
+
help: { description: 'Show available commands', run: help }
|
|
18
|
+
};
|
|
19
|
+
const args = process.argv.slice(2);
|
|
20
|
+
const commandName = aliases[args[0]] || args[0];
|
|
21
|
+
const commandArgs = args.slice(1);
|
|
22
|
+
async function main() {
|
|
23
|
+
if (!commandName || commandName === 'help') {
|
|
24
|
+
await help({ args: commandArgs, builtInCommands, loadModuleCommands });
|
|
25
|
+
return;
|
|
26
|
+
}
|
|
27
|
+
const builtIn = builtInCommands[commandName];
|
|
28
|
+
if (builtIn) {
|
|
29
|
+
await builtIn.run({ args: commandArgs });
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
// Search module commands
|
|
33
|
+
const moduleCommands = await loadModuleCommands();
|
|
34
|
+
const moduleCommand = moduleCommands[commandName];
|
|
35
|
+
if (moduleCommand) {
|
|
36
|
+
const cwd = process.cwd();
|
|
37
|
+
if (moduleCommand.bootstrap) {
|
|
38
|
+
const config = await importConfig(`${cwd}/config/environment`);
|
|
39
|
+
const { default: Stonyx } = await import('./main.js');
|
|
40
|
+
new Stonyx(config, cwd);
|
|
41
|
+
await Stonyx.ready;
|
|
42
|
+
}
|
|
43
|
+
await moduleCommand.run({ args: commandArgs, cwd });
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
console.error(`Unknown command: ${args[0]}\n`);
|
|
47
|
+
await help({ args: [], builtInCommands, loadModuleCommands });
|
|
48
|
+
process.exit(1);
|
|
49
|
+
}
|
|
50
|
+
main().catch(error => {
|
|
51
|
+
console.error(error);
|
|
52
|
+
process.exit(1);
|
|
53
|
+
});
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export interface StoynxModule {
|
|
2
|
+
init?(): Promise<void>;
|
|
3
|
+
startup?(): Promise<void>;
|
|
4
|
+
shutdown?(): Promise<void>;
|
|
5
|
+
}
|
|
6
|
+
export declare function runStartupHooks(modules: StoynxModule[]): Promise<void>;
|
|
7
|
+
export declare function runShutdownHooks(modules: StoynxModule[]): Promise<void>;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export async function runStartupHooks(modules) {
|
|
2
|
+
for (const module of modules) {
|
|
3
|
+
if (typeof module.startup === 'function')
|
|
4
|
+
await module.startup();
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
export async function runShutdownHooks(modules) {
|
|
8
|
+
for (const module of [...modules].reverse()) {
|
|
9
|
+
if (typeof module.shutdown === 'function') {
|
|
10
|
+
try {
|
|
11
|
+
await module.shutdown();
|
|
12
|
+
}
|
|
13
|
+
catch (error) {
|
|
14
|
+
console.error('Error during module shutdown:', error);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
}
|
package/dist/main.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import Chronicle from '@stonyx/logs';
|
|
2
|
+
import type { StoynxModule } from './lifecycle.js';
|
|
3
|
+
import type { StoynxConfig } from './modules.js';
|
|
4
|
+
export default class Stonyx {
|
|
5
|
+
static initialized: boolean;
|
|
6
|
+
static modulePromises: Record<string, unknown>;
|
|
7
|
+
static instance: Stonyx;
|
|
8
|
+
static ready: Promise<void>;
|
|
9
|
+
config: StoynxConfig;
|
|
10
|
+
chronicle: Chronicle;
|
|
11
|
+
modules: StoynxModule[];
|
|
12
|
+
constructor(config: StoynxConfig, rootPath: string);
|
|
13
|
+
start(config: StoynxConfig, rootPath: string): Promise<void>;
|
|
14
|
+
/**
|
|
15
|
+
* Allows users to define their own log for any extra class via environment config
|
|
16
|
+
*/
|
|
17
|
+
configureUserLogs(): void;
|
|
18
|
+
static get log(): Chronicle;
|
|
19
|
+
static get config(): StoynxConfig;
|
|
20
|
+
}
|
|
21
|
+
export { waitForModule } from './modules.js';
|
|
22
|
+
export type { StoynxConfig } from './modules.js';
|
package/dist/main.js
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright 2025 Stone Costa
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
import Chronicle from '@stonyx/logs';
|
|
17
|
+
import loadModules from './modules.js';
|
|
18
|
+
import { mergeObject } from '@stonyx/utils/object';
|
|
19
|
+
import { importConfig } from './util/import-config.js';
|
|
20
|
+
import { resolveModuleName } from './util/resolve-module-name.js';
|
|
21
|
+
export default class Stonyx {
|
|
22
|
+
static initialized = false;
|
|
23
|
+
static modulePromises = {};
|
|
24
|
+
static instance;
|
|
25
|
+
static ready;
|
|
26
|
+
config;
|
|
27
|
+
chronicle;
|
|
28
|
+
modules;
|
|
29
|
+
constructor(config, rootPath) {
|
|
30
|
+
if (Stonyx.instance)
|
|
31
|
+
return Stonyx.instance;
|
|
32
|
+
Stonyx.instance = this;
|
|
33
|
+
Stonyx.ready = this.start(config, rootPath);
|
|
34
|
+
}
|
|
35
|
+
async start(config, rootPath) {
|
|
36
|
+
if (!config)
|
|
37
|
+
throw new Error('Stonyx requires full environment configuration on startup');
|
|
38
|
+
if (!rootPath)
|
|
39
|
+
throw new Error('Stonyx requires root project\'s path on startup');
|
|
40
|
+
// Transform config from stonyx-modules running as a standalone.
|
|
41
|
+
// Signal is the consumer's `package.json#name` (see resolveModuleName);
|
|
42
|
+
// this replaces the brittle `rootPath.includes('stonyx-')` heuristic so
|
|
43
|
+
// non-canonical rootPaths (worktrees, forks, renames) still work.
|
|
44
|
+
const moduleName = resolveModuleName(rootPath);
|
|
45
|
+
if (moduleName) {
|
|
46
|
+
const flatConfig = config;
|
|
47
|
+
const siblingModules = flatConfig.modules || {};
|
|
48
|
+
config = { [moduleName]: config, ...siblingModules };
|
|
49
|
+
delete config.modules;
|
|
50
|
+
}
|
|
51
|
+
this.config = config;
|
|
52
|
+
this.chronicle = new Chronicle({ additionalLogs: { title: 'green' } });
|
|
53
|
+
Stonyx.initialized = true;
|
|
54
|
+
// Auto-merge test environment overrides (after initialized flag, before modules load)
|
|
55
|
+
// Uses in-place mutation to preserve existing references (e.g. stonyx/config export cache)
|
|
56
|
+
if (process.env.NODE_ENV === 'test') {
|
|
57
|
+
try {
|
|
58
|
+
const testOverrides = await importConfig(`${rootPath}/test/config/environment`);
|
|
59
|
+
const merged = mergeObject(config, testOverrides);
|
|
60
|
+
Object.assign(config, merged);
|
|
61
|
+
}
|
|
62
|
+
catch (err) {
|
|
63
|
+
// Missing test override is non-fatal; re-throw import errors that aren't "not found"
|
|
64
|
+
if (!(err instanceof Error) || !err.message.startsWith('Config not found:'))
|
|
65
|
+
throw err;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
this.modules = await loadModules(config, rootPath, this.chronicle);
|
|
69
|
+
this.configureUserLogs();
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Allows users to define their own log for any extra class via environment config
|
|
73
|
+
*/
|
|
74
|
+
configureUserLogs() {
|
|
75
|
+
const { chronicle } = this;
|
|
76
|
+
for (const [className, config] of Object.entries(this.config)) {
|
|
77
|
+
if (!config || typeof config !== 'object')
|
|
78
|
+
continue;
|
|
79
|
+
if (className in chronicle)
|
|
80
|
+
continue;
|
|
81
|
+
const { logColor, logMethod, logTimestamp } = config;
|
|
82
|
+
if (!logColor)
|
|
83
|
+
continue;
|
|
84
|
+
chronicle.defineType(logMethod || className, logColor, { logTimestamp: !!logTimestamp });
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
static get log() {
|
|
88
|
+
if (!Stonyx.initialized)
|
|
89
|
+
throw new Error('Stonyx has not been initialized yet');
|
|
90
|
+
return Stonyx.instance.chronicle;
|
|
91
|
+
}
|
|
92
|
+
static get config() {
|
|
93
|
+
if (!Stonyx.initialized)
|
|
94
|
+
throw new Error('Stonyx has not been initialized yet');
|
|
95
|
+
return Stonyx.instance.config;
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
export { waitForModule } from './modules.js';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { StoynxModule } from './lifecycle.js';
|
|
2
|
+
import type Chronicle from '@stonyx/logs';
|
|
3
|
+
export type StoynxConfig = Record<string, Record<string, unknown> | unknown>;
|
|
4
|
+
export default function loadModules(config: StoynxConfig, rootPath: string, chronicle: Chronicle): Promise<StoynxModule[]>;
|
|
5
|
+
export declare function waitForModule(moduleName: string): Promise<void>;
|
package/dist/modules.js
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Validates and initializes stonyx modules
|
|
3
|
+
* TODO: Refactor into a ModuleLoader class (good coding exercise)
|
|
4
|
+
*/
|
|
5
|
+
import { readFile } from '@stonyx/utils/file';
|
|
6
|
+
import { kebabCaseToCamelCase } from '@stonyx/utils/string';
|
|
7
|
+
import { mergeObject } from '@stonyx/utils/object';
|
|
8
|
+
import { importConfig } from './util/import-config.js';
|
|
9
|
+
const modulePromises = {};
|
|
10
|
+
// Configure module-specific logging
|
|
11
|
+
function configureLog(chronicle, module, config) {
|
|
12
|
+
const { logColor, logMethod, logTimestamp } = config;
|
|
13
|
+
if (!logColor)
|
|
14
|
+
return;
|
|
15
|
+
chronicle.defineType(logMethod || module, logColor, { logTimestamp: !!logTimestamp });
|
|
16
|
+
}
|
|
17
|
+
function initializeModule(moduleName, moduleClass, modules, initPromises) {
|
|
18
|
+
const moduleInstance = new moduleClass();
|
|
19
|
+
modules.push(moduleInstance);
|
|
20
|
+
if (!moduleInstance.init)
|
|
21
|
+
return;
|
|
22
|
+
initPromises.push((async () => {
|
|
23
|
+
await moduleInstance.init();
|
|
24
|
+
modulePromises[moduleName]?.resolve();
|
|
25
|
+
})());
|
|
26
|
+
}
|
|
27
|
+
export default async function loadModules(config, rootPath, chronicle) {
|
|
28
|
+
const modules = [];
|
|
29
|
+
const initPromises = [];
|
|
30
|
+
const rootPackage = await readFile(`${rootPath}/package.json`, { json: true });
|
|
31
|
+
const dependencies = (rootPackage.devDependencies || {});
|
|
32
|
+
const projectName = typeof rootPackage.name === 'string' ? rootPackage.name : '';
|
|
33
|
+
// Expose rootPath to public configuration
|
|
34
|
+
config.rootPath = rootPath;
|
|
35
|
+
const moduleDependencies = Object.keys(dependencies).filter((moduleName) => moduleName.startsWith('@stonyx/'));
|
|
36
|
+
// Setup module promises prior to initialization
|
|
37
|
+
for (const moduleName of moduleDependencies) {
|
|
38
|
+
const promise = {};
|
|
39
|
+
modulePromises[moduleName] = promise;
|
|
40
|
+
promise.ready = new Promise(resolve => promise.resolve = resolve);
|
|
41
|
+
}
|
|
42
|
+
// Standalone module configuration
|
|
43
|
+
if (Array.isArray(rootPackage.keywords) && rootPackage.keywords.includes('stonyx-module')) {
|
|
44
|
+
configureLog(chronicle, projectName, config);
|
|
45
|
+
const entryPoint = typeof rootPackage.main === 'string' ? rootPackage.main : '';
|
|
46
|
+
const { default: moduleClass } = await import(`${rootPath}/${entryPoint}`);
|
|
47
|
+
initializeModule(projectName, moduleClass, modules, initPromises);
|
|
48
|
+
}
|
|
49
|
+
for (const moduleName of moduleDependencies) {
|
|
50
|
+
const modulePackage = await readFile(`${rootPath}/node_modules/${moduleName}/package.json`, { json: true, missingFileCallback: (_filePath) => {
|
|
51
|
+
console.warn(`Warning: Could not locate stonyx module: "${moduleName}". Module was not loaded`);
|
|
52
|
+
return '';
|
|
53
|
+
} });
|
|
54
|
+
if (!modulePackage)
|
|
55
|
+
continue;
|
|
56
|
+
const keywords = Array.isArray(modulePackage.keywords) ? modulePackage.keywords : [];
|
|
57
|
+
if (!keywords.includes('stonyx-module')) {
|
|
58
|
+
console.warn(`Warning: Stonyx modules must contain the "stonyx-module" keyword. Module was not loaded`);
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
if (!keywords.includes('stonyx-async')) {
|
|
62
|
+
modulePromises[moduleName].resolve();
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
try {
|
|
66
|
+
// Load & Configure Async Modules
|
|
67
|
+
const moduleConfig = await importConfig(`${rootPath}/node_modules/${moduleName}/config/environment`);
|
|
68
|
+
const module = kebabCaseToCamelCase(moduleName.split('/').pop() ?? moduleName);
|
|
69
|
+
const userConfig = config[module] || {};
|
|
70
|
+
const finalConfig = mergeObject(moduleConfig, userConfig);
|
|
71
|
+
config[module] = finalConfig;
|
|
72
|
+
// Configure module-specific logging
|
|
73
|
+
configureLog(chronicle, module, finalConfig);
|
|
74
|
+
const entryPoint = modulePackage.main;
|
|
75
|
+
const { default: moduleClass } = await import(`${rootPath}/node_modules/${moduleName}/${entryPoint}`);
|
|
76
|
+
initializeModule(moduleName, moduleClass, modules, initPromises);
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
console.error(error);
|
|
80
|
+
throw new Error(`Stonyx modules with async loading must have a config/environment.js file with default configurations. Module "${moduleName}" failed to load.`);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
// Wait until all modules are initialized
|
|
84
|
+
await Promise.all(initPromises);
|
|
85
|
+
return modules;
|
|
86
|
+
}
|
|
87
|
+
export async function waitForModule(moduleName) {
|
|
88
|
+
const fullName = `@stonyx/${moduleName}`;
|
|
89
|
+
const modulePromise = modulePromises[fullName];
|
|
90
|
+
if (!modulePromise)
|
|
91
|
+
throw new Error(`Could wait for module: ${fullName}. Module was not registered in project dependencies`);
|
|
92
|
+
await modulePromises[fullName].ready;
|
|
93
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function importConfig<T = unknown>(basePath: string): Promise<T>;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { existsSync } from 'fs';
|
|
2
|
+
import { pathToFileURL } from 'url';
|
|
3
|
+
export async function importConfig(basePath) {
|
|
4
|
+
const path = `${basePath}.js`;
|
|
5
|
+
if (!existsSync(path)) {
|
|
6
|
+
throw new Error(`Config not found: ${path}`);
|
|
7
|
+
}
|
|
8
|
+
const mod = await import(pathToFileURL(path).href);
|
|
9
|
+
return mod.default;
|
|
10
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function resolveEntryPoint(basePath: string): string;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { existsSync } from 'fs';
|
|
2
|
+
import { resolve } from 'path';
|
|
3
|
+
const EXTENSIONS = ['ts', 'js'];
|
|
4
|
+
export function resolveEntryPoint(basePath) {
|
|
5
|
+
const matches = EXTENSIONS.filter(ext => existsSync(resolve(`${basePath}.${ext}`)));
|
|
6
|
+
if (matches.length === 0) {
|
|
7
|
+
throw new Error(`Entry point not found: ${basePath}.{ts,js}`);
|
|
8
|
+
}
|
|
9
|
+
if (matches.length > 1) {
|
|
10
|
+
console.warn(`Warning: both ${basePath}.ts and ${basePath}.js exist. Using .ts — delete the .js to silence this warning (it is likely a stale compiled artifact or postinstall stub).`);
|
|
11
|
+
}
|
|
12
|
+
const ext = matches[0];
|
|
13
|
+
return resolve(`${basePath}.${ext}`);
|
|
14
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolve a stonyx standalone module's camelCase name from the consumer's
|
|
3
|
+
* `package.json#name`. Used by the standalone-config transform to wrap a flat
|
|
4
|
+
* config under the module's key when a stonyx module runs its own tests.
|
|
5
|
+
*
|
|
6
|
+
* Recognises:
|
|
7
|
+
* - `@stonyx/<kebab>` → `<camel>`
|
|
8
|
+
* - `stonyx-<kebab>` → `<camel>` (unscoped fallback)
|
|
9
|
+
* - Anything else → `null` (caller should skip the transform)
|
|
10
|
+
*
|
|
11
|
+
* Missing or malformed `package.json` returns `null` silently — matches the
|
|
12
|
+
* fail-safe semantics of the previous `rootPath.includes('stonyx-')` heuristic.
|
|
13
|
+
*/
|
|
14
|
+
export declare function resolveModuleName(rootPath: string): string | null;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { readFileSync } from 'fs';
|
|
2
|
+
import { kebabCaseToCamelCase } from '@stonyx/utils/string';
|
|
3
|
+
/**
|
|
4
|
+
* Resolve a stonyx standalone module's camelCase name from the consumer's
|
|
5
|
+
* `package.json#name`. Used by the standalone-config transform to wrap a flat
|
|
6
|
+
* config under the module's key when a stonyx module runs its own tests.
|
|
7
|
+
*
|
|
8
|
+
* Recognises:
|
|
9
|
+
* - `@stonyx/<kebab>` → `<camel>`
|
|
10
|
+
* - `stonyx-<kebab>` → `<camel>` (unscoped fallback)
|
|
11
|
+
* - Anything else → `null` (caller should skip the transform)
|
|
12
|
+
*
|
|
13
|
+
* Missing or malformed `package.json` returns `null` silently — matches the
|
|
14
|
+
* fail-safe semantics of the previous `rootPath.includes('stonyx-')` heuristic.
|
|
15
|
+
*/
|
|
16
|
+
export function resolveModuleName(rootPath) {
|
|
17
|
+
let pkg;
|
|
18
|
+
try {
|
|
19
|
+
const raw = readFileSync(`${rootPath}/package.json`, 'utf8');
|
|
20
|
+
pkg = JSON.parse(raw);
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
return null;
|
|
24
|
+
}
|
|
25
|
+
const name = typeof pkg.name === 'string' ? pkg.name : '';
|
|
26
|
+
if (name.startsWith('@stonyx/')) {
|
|
27
|
+
return kebabCaseToCamelCase(name.slice('@stonyx/'.length));
|
|
28
|
+
}
|
|
29
|
+
if (name.startsWith('stonyx-')) {
|
|
30
|
+
return kebabCaseToCamelCase(name.slice('stonyx-'.length));
|
|
31
|
+
}
|
|
32
|
+
return null;
|
|
33
|
+
}
|
package/package.json
CHANGED
|
@@ -1,23 +1,45 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "stonyx",
|
|
3
|
-
"version": "0.2.3-beta.
|
|
3
|
+
"version": "0.2.3-beta.91",
|
|
4
4
|
"description": "Base stonyx framework module",
|
|
5
|
-
"main": "main.js",
|
|
5
|
+
"main": "dist/main.js",
|
|
6
|
+
"types": "dist/main.d.ts",
|
|
6
7
|
"type": "module",
|
|
7
8
|
"bin": {
|
|
8
|
-
"stonyx": "./
|
|
9
|
+
"stonyx": "./dist/cli.js"
|
|
9
10
|
},
|
|
10
11
|
"exports": {
|
|
11
|
-
".":
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
"./
|
|
12
|
+
".": {
|
|
13
|
+
"types": "./dist/main.d.ts",
|
|
14
|
+
"default": "./dist/main.js"
|
|
15
|
+
},
|
|
16
|
+
"./config": {
|
|
17
|
+
"types": "./dist/exports/config.d.ts",
|
|
18
|
+
"default": "./dist/exports/config.js"
|
|
19
|
+
},
|
|
20
|
+
"./log": {
|
|
21
|
+
"types": "./dist/exports/log.d.ts",
|
|
22
|
+
"default": "./dist/exports/log.js"
|
|
23
|
+
},
|
|
24
|
+
"./test-helpers": {
|
|
25
|
+
"types": "./dist/exports/test-helpers.d.ts",
|
|
26
|
+
"default": "./dist/exports/test-helpers.js"
|
|
27
|
+
},
|
|
28
|
+
"./lifecycle": {
|
|
29
|
+
"types": "./dist/lifecycle.d.ts",
|
|
30
|
+
"default": "./dist/lifecycle.js"
|
|
31
|
+
}
|
|
16
32
|
},
|
|
17
33
|
"repository": {
|
|
18
34
|
"type": "git",
|
|
19
35
|
"url": "git+https://github.com/abofs/stonyx.git"
|
|
20
36
|
},
|
|
37
|
+
"files": [
|
|
38
|
+
"dist",
|
|
39
|
+
"config",
|
|
40
|
+
"scripts",
|
|
41
|
+
"README.md"
|
|
42
|
+
],
|
|
21
43
|
"publishConfig": {
|
|
22
44
|
"provenance": true
|
|
23
45
|
},
|
|
@@ -30,16 +52,23 @@
|
|
|
30
52
|
"url": "https://github.com/abofs/stonyx/issues"
|
|
31
53
|
},
|
|
32
54
|
"dependencies": {
|
|
33
|
-
"
|
|
55
|
+
"@stonyx/utils": "0.2.3-beta.26",
|
|
56
|
+
"@stonyx/logs": "1.0.1-beta.21"
|
|
34
57
|
},
|
|
35
58
|
"devDependencies": {
|
|
36
|
-
"@
|
|
59
|
+
"@types/node": "^25.5.2",
|
|
60
|
+
"@types/qunit": "^2.19.13",
|
|
61
|
+
"@types/sinon": "^21.0.1",
|
|
37
62
|
"qunit": "^2.24.1",
|
|
38
|
-
"sinon": "^21.0.0"
|
|
63
|
+
"sinon": "^21.0.0",
|
|
64
|
+
"tsx": "^4.21.0",
|
|
65
|
+
"typescript": "^5.8.3"
|
|
39
66
|
},
|
|
40
67
|
"scripts": {
|
|
68
|
+
"build": "tsc",
|
|
69
|
+
"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
|
|
41
70
|
"start": "node .",
|
|
42
|
-
"test": "qunit",
|
|
71
|
+
"test": "pnpm build && node --import tsx node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'",
|
|
43
72
|
"error": "echo \"Error: no error handling\" && exit 1",
|
|
44
73
|
"postinstall": "node scripts/postinstall.js"
|
|
45
74
|
}
|
package/scripts/postinstall.js
CHANGED
|
@@ -2,14 +2,36 @@
|
|
|
2
2
|
const isGlobal = !process.env.INIT_CWD || process.env.npm_config_global === 'true';
|
|
3
3
|
if (isGlobal) process.exit(0);
|
|
4
4
|
|
|
5
|
+
const { existsSync } = await import('node:fs');
|
|
5
6
|
const { copyFile, createDirectory } = await import('@stonyx/utils/file');
|
|
6
7
|
|
|
7
8
|
const projectDir = process.env.INIT_CWD;
|
|
8
9
|
const configDir = `${projectDir}/config`;
|
|
9
|
-
|
|
10
|
+
|
|
11
|
+
// Detect consumer project type: presence of `tsconfig.json` in the consumer
|
|
12
|
+
// root signals a TypeScript project (see abofs/stonyx#62). TS consumers can't
|
|
13
|
+
// use the `.js` stub, so we ship both templates and copy the matching one.
|
|
14
|
+
const isTypeScriptConsumer = existsSync(`${projectDir}/tsconfig.json`);
|
|
15
|
+
const extension = isTypeScriptConsumer ? 'ts' : 'js';
|
|
16
|
+
const envFile = `environment.${extension}`;
|
|
17
|
+
const templateFile = `environment copy.${extension}`;
|
|
18
|
+
|
|
19
|
+
// Skip if the consumer ships its own `config/environment copy.{ts,js}` template —
|
|
20
|
+
// they manage their own bootstrap (see abofs/stonyx#54, extended in abofs/stonyx#62
|
|
21
|
+
// to honor either extension).
|
|
22
|
+
if (
|
|
23
|
+
existsSync(`${configDir}/environment copy.ts`) ||
|
|
24
|
+
existsSync(`${configDir}/environment copy.js`)
|
|
25
|
+
) process.exit(0);
|
|
26
|
+
|
|
27
|
+
// Don't overwrite an existing consumer config (either extension).
|
|
28
|
+
if (
|
|
29
|
+
existsSync(`${configDir}/environment.ts`) ||
|
|
30
|
+
existsSync(`${configDir}/environment.js`)
|
|
31
|
+
) process.exit(0);
|
|
10
32
|
|
|
11
33
|
createDirectory(configDir);
|
|
12
34
|
|
|
13
|
-
copyFile(`./config
|
|
35
|
+
copyFile(`./config/${templateFile}`, `${configDir}/${envFile}`).then(result => {
|
|
14
36
|
if (result) console.log(`Stonyx: ${envFile} has been successfully created. Please see README.md for more information.`);
|
|
15
37
|
});
|
package/.claude/index.md
DELETED
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
# Stonyx CLI Guide
|
|
2
|
-
|
|
3
|
-
See [docs/index.md](../docs/index.md) for full documentation including conventions, modules, lifecycle, and API reference.
|
|
4
|
-
|
|
5
|
-
## Installation
|
|
6
|
-
|
|
7
|
-
Stonyx is the core framework package. The CLI is provided by the `stonyx` binary defined in `package.json`.
|
|
8
|
-
|
|
9
|
-
In a project that depends on `stonyx`:
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
pnpm add -D stonyx
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
The CLI is then available as `npx stonyx` or via pnpm scripts.
|
|
16
|
-
|
|
17
|
-
## Commands
|
|
18
|
-
|
|
19
|
-
### `stonyx serve` (alias: `s`)
|
|
20
|
-
|
|
21
|
-
Bootstrap Stonyx and run the application.
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
stonyx serve # loads app.js by default
|
|
25
|
-
stonyx serve --entry custom.js # custom entry point
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Behavior:
|
|
29
|
-
1. Loads `.env` file
|
|
30
|
-
2. Imports `config/environment.js`
|
|
31
|
-
3. Initializes Stonyx with all detected `@stonyx/*` modules
|
|
32
|
-
4. Runs startup lifecycle hooks
|
|
33
|
-
5. Imports and instantiates the entry point class
|
|
34
|
-
6. Registers SIGTERM/SIGINT handlers for graceful shutdown
|
|
35
|
-
|
|
36
|
-
### `stonyx test` (alias: `t`)
|
|
37
|
-
|
|
38
|
-
Bootstrap Stonyx in test mode and run QUnit tests.
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
stonyx test # runs test/**/*-test.js
|
|
42
|
-
stonyx test test/unit/foo-test.js # specific file
|
|
43
|
-
stonyx test "test/integration/**/*-test.js" # glob pattern
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Sets `NODE_ENV=test` and auto-loads test setup which merges `test/config/environment.js` overrides.
|
|
47
|
-
|
|
48
|
-
### `stonyx help` (alias: `h`)
|
|
49
|
-
|
|
50
|
-
Show available commands including built-in and module-provided commands.
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
stonyx help
|
|
54
|
-
stonyx --help
|
|
55
|
-
stonyx -h
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
### `stonyx new <app-name>`
|
|
59
|
-
|
|
60
|
-
Scaffold a new Stonyx project with interactive module selection.
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
stonyx new my-backend
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
Prompts for:
|
|
67
|
-
- Package name
|
|
68
|
-
- Which `@stonyx/*` modules to include (REST server, WebSockets, ORM, cron, OAuth, events)
|
|
69
|
-
|
|
70
|
-
Creates:
|
|
71
|
-
- `package.json` with selected dependencies
|
|
72
|
-
- `app.js` entry point
|
|
73
|
-
- `config/environment.js` and `config/environment.example.js`
|
|
74
|
-
- Module-specific directories (`models/`, `requests/`, `crons/`, etc.)
|
|
75
|
-
- `test/` structure with `unit/`, `integration/`, `acceptance/`
|
|
76
|
-
- `.gitignore` and `.nvmrc`
|
|
77
|
-
- Runs `pnpm install`
|
|
78
|
-
|
|
79
|
-
## Module Command System
|
|
80
|
-
|
|
81
|
-
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.
|
|
82
|
-
|
|
83
|
-
Module commands appear under "Module commands" in `stonyx help` output. They can optionally request Stonyx bootstrap before running (via `bootstrap: true`).
|
|
84
|
-
|
|
85
|
-
## Creating a Stonyx Project Manually
|
|
86
|
-
|
|
87
|
-
If not using `stonyx new`:
|
|
88
|
-
|
|
89
|
-
1. Create project directory
|
|
90
|
-
2. Add `.nvmrc` with current LTS Node version
|
|
91
|
-
3. `pnpm init` and set `"type": "module"`
|
|
92
|
-
4. `pnpm add -D stonyx` plus desired `@stonyx/*` modules
|
|
93
|
-
5. Create `config/environment.js` with module config
|
|
94
|
-
6. Create `app.js` entry point class
|
|
95
|
-
7. Create standard directories per selected modules
|
|
96
|
-
8. Add `@abofs/code-conventions` for linting
|
package/.github/workflows/ci.yml
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
name: CI
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
pull_request:
|
|
5
|
-
branches: [dev, main]
|
|
6
|
-
|
|
7
|
-
concurrency:
|
|
8
|
-
group: ci-${{ github.head_ref || github.ref }}
|
|
9
|
-
cancel-in-progress: true
|
|
10
|
-
|
|
11
|
-
permissions:
|
|
12
|
-
contents: read
|
|
13
|
-
|
|
14
|
-
jobs:
|
|
15
|
-
test:
|
|
16
|
-
uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main
|