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

package/README.md

@@ -1,8 +1,11 @@
+[![CI](https://github.com/abofs/stonyx/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/stonyx.svg)](https://www.npmjs.com/package/stonyx)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # Stonyx
 
 **Stonyx** is a lightweight, modular framework for building modern Node.js applications. It provides a plug-and-play architecture, centralized color-coded logging, and seamless async module integration.
 
-- 100% JavaScript (ES Modules)
 - Drop-in module system — no boilerplate
 - Automatic async module loading and initialization
 - Built-in CLI for scaffolding, bootstrapping, and testing
@@ -19,12 +22,12 @@ stonyx serve
 The `new` command walks you through module selection and generates a ready-to-run project. From there, the CLI handles bootstrapping:
 
 ```bash
-stonyx serve    # Bootstrap + run app.js
+stonyx serve    # Bootstrap + run app.ts (or app.js)
 stonyx test     # Bootstrap + run tests
 stonyx help     # Show all available commands
 ```
 
-Stonyx reads `config/environment.js`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
+Stonyx reads `config/environment.ts` (preferred) or `config/environment.js`, loads the `@stonyx/*` modules declared in your `dependencies` or `devDependencies` (initializing the async ones), and runs your application.
 
 ## Documentation
 

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

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

package/dist/cli/help.d.ts

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

package/dist/cli/help.js

@@ -0,0 +1,43 @@
+export default async function help({ args, builtInCommands, loadModuleCommands } = {}) {
+    console.log('\nUsage: stonyx <command> [...args]\n');
+    console.log('Commands:\n');
+    if (builtInCommands) {
+        for (const [name, { description }] of Object.entries(builtInCommands)) {
+            console.log(`  ${name.padEnd(20)} ${description}`);
+        }
+    }
+    if (loadModuleCommands) {
+        try {
+            const moduleCommands = await loadModuleCommands();
+            const entries = Object.entries(moduleCommands);
+            if (entries.length) {
+                console.log('\nModule commands:\n');
+                for (const [name, { description }] of entries) {
+                    console.log(`  ${name.padEnd(20)} ${description}`);
+                }
+            }
+        }
+        catch {
+            // Module commands not available (e.g., no project context)
+        }
+    }
+    console.log('\nAliases: s=serve, t=test, n=new, h=help\n');
+    console.log('Project conventions:\n');
+    console.log('  Entry point:       app.ts (or app.js)');
+    console.log('  Config:            config/environment.ts (or .js)');
+    console.log('  DB schema:         config/db-schema.js');
+    console.log('  Models:            models/');
+    console.log('  Serializers:       serializers/');
+    console.log('  Access control:    access/');
+    console.log('  Transforms:        transforms/');
+    console.log('  Hooks:             hooks/');
+    console.log('  REST requests:     requests/');
+    console.log('  Cron jobs:         crons/');
+    console.log('  Tests:             test/{unit,integration,acceptance}/');
+    console.log('');
+    console.log('  Logging:           import log from \'stonyx/log\' (never console.log)');
+    console.log('  Utilities:         import from \'@stonyx/utils/*\' (never raw fs)');
+    console.log('  Lint config:       import from \'@abofs/code-conventions\'');
+    console.log('  Package manager:   pnpm');
+    console.log('');
+}

package/dist/cli/load-commands.d.ts

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

package/dist/cli/load-commands.js

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

package/dist/cli/new.d.ts

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

package/dist/cli/new.js

@@ -0,0 +1,426 @@
+import { confirm, prompt } from '@stonyx/utils/prompt';
+import { createFile, createDirectory, copyFile, fileExists } from '@stonyx/utils/file';
+import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+export 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.ts': 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']
+    }
+];
+export function generateDbSchema() {
+    return `import { Model, hasMany, type HasMany } from '@stonyx/orm';
+
+export default class DBModel extends Model {
+  // Define your collections here
+  // examples: HasMany = hasMany('example');
+}
+`;
+}
+/**
+ * The npm dist-tag that points at a package's stable release line. Only ever
+ * used as a *release line* selector for `@stonyx/*` modules (see
+ * `releaseTagFor`) -- never as the specifier for the core, which is always
+ * pinned exactly.
+ */
+const STABLE_DIST_TAG = 'latest';
+/** Absolute path to this package's own root, from both `src/` and `dist/`. */
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/** A full semver version: `major.minor.patch`, optional prerelease, optional build. */
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * A string npm accepts as a *dist-tag* and never reinterprets as a version range.
+ * npm requires a tag to be non-numeric, and `x`/`X` are semver wildcards rather
+ * than tag names, so both are rejected in `releaseTagFor`.
+ */
+const DIST_TAG = /^[A-Za-z][0-9A-Za-z-]*$/;
+/**
+ * Rejects any version this generator must not emit.
+ *
+ * `readCoreVersion` used to check only that the field was a non-empty string, so
+ * `"garbage"`, `"0.2"` and `"latest"` all flowed through to the manifest verbatim
+ * and made `releaseTagFor` fall through to `latest` -- the one specifier
+ * abofs/stonyx#113 exists to stop emitting.
+ */
+function assertVersionShape(version, source) {
+    if (typeof version !== 'string' || !version) {
+        throw new Error(`Could not read the stonyx version from ${source}`);
+    }
+    if (!SEMVER.test(version)) {
+        throw new Error(`The stonyx version from ${source} is not a semver version: "${version}"`);
+    }
+}
+/**
+ * The version of the `stonyx` package running this generator, read from its own
+ * `package.json` at call time.
+ *
+ * Read rather than hardcoded on purpose: a literal would be correct on the day
+ * it was written and silently stale on every day after (abofs/stonyx#113).
+ */
+export function readCoreVersion() {
+    const manifest = path.join(packageRoot, 'package.json');
+    const raw = readFileSync(manifest, 'utf8');
+    const version = JSON.parse(raw).version;
+    assertVersionShape(version, manifest);
+    return version;
+}
+/**
+ * The npm dist-tag naming the release line a version belongs to:
+ * `0.2.3-beta.96` -> `beta`, `0.2.3-alpha.4` -> `alpha`, `0.2.2` -> `latest`.
+ *
+ * Every scaffolded `@stonyx/*` module is requested on the same line as the core
+ * that scaffolded it, so the generated project cannot mix a prerelease core with
+ * modules from the stable line (or the reverse).
+ *
+ * Throws, rather than guessing, when the prerelease identifier is not usable as a
+ * dist-tag. Returning it verbatim was only safe for *alphabetic* identifiers: npm
+ * parses a numeric or wildcard identifier as a version **range**, so `0.2.3-0`
+ * emitted `"0"` and `0.2.3-x` emitted `"x"`, both of which install with rc=0 and
+ * silently resolve the module's `latest` release -- for `@stonyx/orm` that is
+ * `0.3.1`, which pins `stonyx@0.2.3-beta.11` and so reproduces abofs/stonyx#113
+ * through a different door, with no error. `0.2.3-0` is reachable from this
+ * repo's own `publish.yml` `custom-version` dispatch input, which accepts any
+ * semver string and also expands the keyword `prerelease` to `x.y.z-0`.
+ *
+ * Two bounds remain, both loud rather than silent:
+ *
+ * - An alphabetic identifier is assumed to also be a published dist-tag name.
+ *   True for `beta` and `alpha`, the only two lines the fleet publishes; a core
+ *   released as e.g. `0.2.3-rc.1` with no `rc` dist-tag scaffolds an unresolvable
+ *   module specifier, which fails `pnpm install` with
+ *   `ERR_PNPM_NO_MATCHING_VERSION`. The tag has to exist on every package in
+ *   `MODULE_OPTIONS`, not only on the core.
+ * - On the stable line this returns `latest`, the correct tag for that line -- but
+ *   only useful once the *modules* have advanced their own `latest` tags. Today
+ *   `@stonyx/orm@latest` is `0.3.1` and pins `stonyx@0.2.3-beta.11`, so the module
+ *   `latest` tags must advance before the core's does (abofs/stonyx#115).
+ */
+export function releaseTagFor(version) {
+    // Fail closed, not open. Without this the exported function still answered
+    // `latest` for `"garbage"`, `"0.2"`, `""` and `"latest"` itself -- the same
+    // fall-through-to-`latest` shape this change exists to remove, one level down
+    // from the emission path that `generatePackageJson` already guards.
+    assertVersionShape(version, 'the supplied version');
+    const prerelease = /^\d+\.\d+\.\d+-(.*)$/.exec(version);
+    if (!prerelease)
+        return STABLE_DIST_TAG;
+    const identifier = prerelease[1].split('.')[0];
+    if (!DIST_TAG.test(identifier) || /^[xX]$/.test(identifier)) {
+        throw new Error(`Cannot derive a dist-tag from the prerelease identifier "${identifier}" in version "${version}": ` +
+            'npm reads it as a version range, not a tag.');
+    }
+    if (identifier === STABLE_DIST_TAG) {
+        throw new Error(`A prerelease core must not request modules at "${STABLE_DIST_TAG}" (version "${version}").`);
+    }
+    return identifier;
+}
+export function generatePackageJson(name, selectedModules, coreVersion = readCoreVersion()) {
+    // Resolved first, before anything is emitted, and unconditionally -- deliberately
+    // not inside the module loop below. `releaseTagFor` asserts the version's shape as
+    // its first act, so this one call is also what stops an injected non-semver
+    // `coreVersion` from reaching the manifest verbatim.
+    //
+    // A second `assertVersionShape(coreVersion, ...)` stood at the top of this function
+    // until abofs/stonyx#118's review: deleting it left the suite green, because this
+    // call already rejects the same value on every path. It was removed rather than
+    // left as decoration. The invariant that replaces it is positional -- keep this
+    // call above the emission and the guard stays load-bearing; push it under an
+    // `if (selectedModules.length)` and the core becomes unvalidated again.
+    const moduleTag = releaseTagFor(coreVersion);
+    // The framework is a runtime dependency of the application, pinned exactly to
+    // the core that generated the project.
+    const dependencies = { stonyx: coreVersion };
+    const devDependencies = {
+        qunit: '^2.24.1',
+        tsx: '^4.21.0',
+        typescript: '^5.8.3'
+    };
+    // The scaffolder writes modules to `devDependencies` because that remains
+    // the conventional placement for an application — NOT because it is the only
+    // one discovery sees. Since abofs/stonyx#106 rule 3 the loader scans the
+    // de-duplicated union of `dependencies` and `devDependencies`, so either
+    // placement is discovered (see docs/modules.md). Requested on the core's own
+    // release line rather than at `latest`.
+    for (const mod of selectedModules) {
+        devDependencies[mod.package] = moduleTag;
+    }
+    // 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: {
+            build: 'tsc',
+            serve: 'stonyx serve',
+            start: 'stonyx serve',
+            test: "NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
+        },
+        dependencies,
+        devDependencies: sorted
+    }, null, 2) + '\n';
+}
+export function generateAppTs() {
+    return `import log from 'stonyx/log';
+
+export default class App {
+  static instance: App;
+  ready: Promise<void>;
+
+  constructor() {
+    if (App.instance) return App.instance;
+    App.instance = this;
+
+    this.ready = this.init();
+  }
+
+  async init(): Promise<void> {
+    log.info('Initializing Application');
+
+    // Application setup here
+
+    log.info('Application has been initialized');
+  }
+}
+`;
+}
+export function generateEnvironmentTs() {
+    return `import type { StoynxConfig } from 'stonyx';
+
+const config: StoynxConfig = {
+};
+
+export default config;
+`;
+}
+export function generateTestEnvironmentTs() {
+    return `import type { StoynxConfig } from 'stonyx';
+
+// Test-specific config overrides
+const config: Partial<StoynxConfig> = {
+};
+
+export default config;
+`;
+}
+export function generateSetupTs() {
+    return `// Test setup: bootstrap Stonyx with the consumer config before qunit runs.
+// Sprint 44 pattern — loaded via \`node --import ./test/setup.ts\`.
+import { pathToFileURL } from 'url';
+
+const cwd = process.cwd();
+
+const { default: Stonyx } = await import('stonyx');
+const { default: config } = await import(pathToFileURL(\`\${cwd}/config/environment.ts\`).href);
+
+new Stonyx(config, cwd);
+
+await Stonyx.ready;
+`;
+}
+export function generateZzExitTestTs() {
+    return `// Force-exit hook for qunit runs.
+//
+// Stonyx modules may keep listeners/servers open that would otherwise
+// block the process from exiting after tests complete, causing CI to
+// hit timeouts even though all tests passed.
+//
+// Named \`zz-\` so alphabetical test-file order places it last, after
+// all real test files have registered with QUnit.
+import QUnit from 'qunit';
+
+QUnit.on('runEnd', () => {
+  setImmediate(() => process.exit(process.exitCode ?? 0));
+});
+`;
+}
+export function generateEnvironmentExampleTs() {
+    return `// Copy this file to environment.ts and fill in your values
+// All values should use environment variables with ?? fallback defaults
+
+const {
+  NODE_ENV,
+} = process.env;
+
+const environment: string = NODE_ENV ?? 'development';
+
+export default {
+}
+`;
+}
+export function generateGitignore() {
+    return `node_modules/
+.env
+db.json
+*.log
+
+# Compiled TypeScript output (tsc compiles .ts to .js in-place)
+*.js
+*.d.ts
+*.js.map
+`;
+}
+export function generateTsConfig() {
+    return JSON.stringify({
+        compilerOptions: {
+            strict: true,
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            outDir: '.',
+            rootDir: '.',
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true
+        },
+        include: ['**/*.ts'],
+        exclude: ['node_modules', 'test']
+    }, null, 2) + '\n';
+}
+/**
+ * Rejects when `pnpm install` fails, either by exiting non-zero or by failing to
+ * spawn. Exported so the rejection path is testable without a network round-trip.
+ */
+export 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);
+    });
+}
+/**
+ * Write every scaffolded file to disk given a resolved project directory,
+ * app name, and pre-selected module options. Factored out of `newCommand`
+ * so tests can exercise the file-writing path without interactive prompts.
+ */
+export async function scaffoldProject(projectDir, appName, selectedModules) {
+    // 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.ts'), generateAppTs());
+    await createFile(path.join(projectDir, 'tsconfig.json'), generateTsConfig());
+    await createFile(path.join(projectDir, '.gitignore'), generateGitignore());
+    // Create config directory and files
+    await createFile(path.join(projectDir, 'config', 'environment.ts'), generateEnvironmentTs());
+    await createFile(path.join(projectDir, 'config', 'environment.example.ts'), generateEnvironmentExampleTs());
+    // 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 (TS)
+    await createFile(path.join(projectDir, 'test', 'config', 'environment.ts'), generateTestEnvironmentTs());
+    // Create Sprint 44 test harness files (setup bootstraps Stonyx, zz-exit-test drains event loop)
+    await createFile(path.join(projectDir, 'test', 'setup.ts'), generateSetupTs());
+    await createFile(path.join(projectDir, 'test', 'zz-exit-test.ts'), generateZzExitTestTs());
+}
+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');
+    await scaffoldProject(projectDir, appName, selectedModules);
+    console.log('Installing dependencies...\n');
+    try {
+        await runPnpmInstall(projectDir);
+    }
+    catch (error) {
+        // `pnpm`'s own diagnostic already reached the terminal via stdio: 'inherit'.
+        // What used to be missing is the exit code: this catch discarded `error` and
+        // fell through to the success banner, so `stonyx new` announced success and
+        // exited 0 on a project with no node_modules -- loud to a human, silent to any
+        // supervisor, CI job or wrapper reading the status.
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error(`\n✗ Project "${appName}" was created, but its dependencies are NOT installed.`);
+        console.error(`\n  cd ${appName}`);
+        console.error('  pnpm install\n');
+        process.exitCode = 1;
+        return;
+    }
+    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,6 @@
+import { type StoynxModule } from '../lifecycle.js';
+export declare function createShutdownHandler(modules: StoynxModule[]): () => Promise<void>;
+export declare function maybeRegisterAppShutdown(modules: StoynxModule[], appInstance: unknown, originalShutdown: () => Promise<void>): void;
+export default function serve({ args }: {
+    args: string[];
+}): Promise<void>;