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.
Files changed (67) hide show
  1. package/README.md +16 -5
  2. package/config/{environment.js → environment copy.ts } +16 -12
  3. package/dist/cli/help.d.ts +8 -0
  4. package/dist/cli/help.js +43 -0
  5. package/dist/cli/load-commands.d.ts +10 -0
  6. package/dist/cli/load-commands.js +49 -0
  7. package/dist/cli/new.d.ts +26 -0
  8. package/dist/cli/new.js +293 -0
  9. package/dist/cli/serve.d.ts +6 -0
  10. package/dist/cli/serve.js +49 -0
  11. package/dist/cli/test-setup.d.ts +1 -0
  12. package/dist/cli/test-setup.js +30 -0
  13. package/dist/cli/test.d.ts +4 -0
  14. package/dist/cli/test.js +23 -0
  15. package/dist/cli.d.ts +2 -0
  16. package/dist/cli.js +53 -0
  17. package/dist/exports/config.d.ts +2 -0
  18. package/dist/exports/config.js +2 -0
  19. package/dist/exports/log.d.ts +2 -0
  20. package/{src → dist}/exports/log.js +1 -2
  21. package/dist/exports/test-helpers.d.ts +5 -0
  22. package/dist/exports/test-helpers.js +7 -0
  23. package/dist/lifecycle.d.ts +7 -0
  24. package/dist/lifecycle.js +18 -0
  25. package/dist/main.d.ts +22 -0
  26. package/dist/main.js +98 -0
  27. package/dist/modules.d.ts +5 -0
  28. package/dist/modules.js +93 -0
  29. package/dist/util/import-config.d.ts +1 -0
  30. package/dist/util/import-config.js +10 -0
  31. package/dist/util/resolve-entry-point.d.ts +1 -0
  32. package/dist/util/resolve-entry-point.js +14 -0
  33. package/dist/util/resolve-module-name.d.ts +14 -0
  34. package/dist/util/resolve-module-name.js +33 -0
  35. package/package.json +41 -12
  36. package/scripts/postinstall.js +24 -2
  37. package/.claude/index.md +0 -96
  38. package/.github/workflows/ci.yml +0 -16
  39. package/.github/workflows/publish.yml +0 -51
  40. package/docs/api.md +0 -89
  41. package/docs/cli.md +0 -78
  42. package/docs/configuration.md +0 -72
  43. package/docs/conventions/discord-conventions.md +0 -62
  44. package/docs/conventions/framework-modules.md +0 -127
  45. package/docs/conventions/index.md +0 -24
  46. package/docs/conventions/orm-conventions.md +0 -158
  47. package/docs/conventions/project-structure.md +0 -105
  48. package/docs/conventions/rest-conventions.md +0 -96
  49. package/docs/conventions/testing-conventions.md +0 -56
  50. package/docs/developing-modules.md +0 -108
  51. package/docs/index.md +0 -15
  52. package/docs/lifecycle.md +0 -47
  53. package/docs/logging.md +0 -52
  54. package/docs/modules.md +0 -78
  55. package/docs/testing.md +0 -64
  56. package/src/cli/help.js +0 -48
  57. package/src/cli/load-commands.js +0 -56
  58. package/src/cli/new.js +0 -237
  59. package/src/cli/serve.js +0 -38
  60. package/src/cli/test-setup.js +0 -8
  61. package/src/cli/test.js +0 -27
  62. package/src/cli.js +0 -63
  63. package/src/exports/config.js +0 -3
  64. package/src/exports/test-helpers.js +0 -8
  65. package/src/lifecycle.js +0 -17
  66. package/src/main.js +0 -101
  67. 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,2 @@
1
+ declare const _default: import("stonyx").StoynxConfig;
2
+ export default _default;
@@ -0,0 +1,2 @@
1
+ import Stonyx from 'stonyx';
2
+ export default Stonyx.config;
@@ -0,0 +1,2 @@
1
+ declare const _default: import("@stonyx/logs").default;
2
+ export default _default;
@@ -1,3 +1,2 @@
1
1
  import Stonyx from 'stonyx';
2
-
3
- export default Stonyx.log;
2
+ export default Stonyx.log;
@@ -0,0 +1,5 @@
1
+ interface TestHooks {
2
+ before(fn: () => Promise<void>): void;
3
+ }
4
+ export declare function setupIntegrationTests(hooks: TestHooks): void;
5
+ export {};
@@ -0,0 +1,7 @@
1
+ import Stonyx from 'stonyx';
2
+ export function setupIntegrationTests(hooks) {
3
+ hooks.before(async function () {
4
+ await Stonyx.ready;
5
+ console.log('Stonyx ready');
6
+ });
7
+ }
@@ -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>;
@@ -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.9",
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": "./src/cli.js"
9
+ "stonyx": "./dist/cli.js"
9
10
  },
10
11
  "exports": {
11
- ".": "./src/main.js",
12
- "./config": "./src/exports/config.js",
13
- "./log": "./src/exports/log.js",
14
- "./test-helpers": "./src/exports/test-helpers.js",
15
- "./lifecycle": "./src/lifecycle.js"
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
- "node-chronicle": "^0.2.0"
55
+ "@stonyx/utils": "0.2.3-beta.26",
56
+ "@stonyx/logs": "1.0.1-beta.21"
34
57
  },
35
58
  "devDependencies": {
36
- "@stonyx/utils": "0.2.3-beta.5",
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
  }
@@ -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
- const envFile = 'environment.js';
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/environment copy.js`, `${configDir}/${envFile}`).then(result => {
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
@@ -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