stonyx 0.2.3-beta.95 → 0.2.3-beta.97

package/README.md

@@ -22,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`, initializes all `@stonyx/*` modules from your `devDependencies`, and runs your application.
 
 ## Documentation
 

package/dist/cli/help.js

@@ -23,8 +23,8 @@ export default async function help({ args, builtInCommands, loadModuleCommands }
     }
     console.log('\nAliases: s=serve, t=test, n=new, h=help\n');
     console.log('Project conventions:\n');
-    console.log('  Entry point:       app.js');
-    console.log('  Config:            config/environment.js');
+    console.log('  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/');

package/dist/cli/new.d.ts

@@ -4,8 +4,49 @@ interface ModuleOption {
     dirs?: string[];
     files?: Record<string, () => string>;
 }
+export declare const MODULE_OPTIONS: ModuleOption[];
 export declare function generateDbSchema(): string;
-export declare function generatePackageJson(name: string, selectedModules: ModuleOption[]): 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;
@@ -14,6 +55,11 @@ 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`

package/dist/cli/new.js

@@ -1,9 +1,10 @@
 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';
-const MODULE_OPTIONS = [
+export const MODULE_OPTIONS = [
     {
         question: 'Will this project need a REST server?',
         package: '@stonyx/rest-server',
@@ -48,15 +49,128 @@ export default class DBModel extends Model {
 }
 `;
 }
-export function generatePackageJson(name, selectedModules) {
+/**
+ * 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',
-        stonyx: 'latest',
         tsx: '^4.21.0',
         typescript: '^5.8.3'
     };
+    // Modules are discovered from devDependencies (see docs/modules.md), and are
+    // requested on the core's own release line rather than at `latest`.
     for (const mod of selectedModules) {
-        devDependencies[mod.package] = 'latest';
+        devDependencies[mod.package] = moduleTag;
     }
     // Sort dependencies alphabetically
     const sorted = Object.fromEntries(Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b)));
@@ -71,6 +185,7 @@ export function generatePackageJson(name, selectedModules) {
             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';
 }
@@ -191,7 +306,11 @@ export function generateTsConfig() {
         exclude: ['node_modules', 'test']
     }, null, 2) + '\n';
 }
-function runPnpmInstall(projectDir) {
+/**
+ * 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,
@@ -285,7 +404,17 @@ export default async function newCommand({ args }) {
         await runPnpmInstall(projectDir);
     }
     catch (error) {
-        console.error('Failed to install dependencies. Run `pnpm install` manually in the project directory.');
+        // `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}`);

package/dist/main.js

@@ -16,7 +16,7 @@
 import Chronicle from '@stonyx/logs';
 import loadModules from './modules.js';
 import { mergeObject } from '@stonyx/utils/object';
-import { importConfig } from './util/import-config.js';
+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;
@@ -60,8 +60,12 @@ export default class Stonyx {
                 Object.assign(config, merged);
             }
             catch (err) {
-                // Missing test override is non-fatal; re-throw import errors that aren't "not found"
-                if (!(err instanceof Error) || !err.message.startsWith('Config not found:'))
+                // 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;
             }
         }

package/dist/util/import-config.d.ts

@@ -1 +1,52 @@
+/**
+ * "There is no config here." Callers are allowed to treat this as benign —
+ * `src/main.ts` does, for the optional `test/config/environment.*` override.
+ *
+ * `main.ts` matches on this exact string, so it is exported rather than
+ * duplicated: the swallow and the thrower must not be able to drift apart.
+ */
+export declare const CONFIG_NOT_FOUND_PREFIX = "Config not found:";
+/**
+ * "There is a config here and I declined to load it." Deliberately NOT prefixed
+ * with `CONFIG_NOT_FOUND_PREFIX`, because `main.ts`'s `NODE_ENV=test` catch
+ * swallows that prefix and must not swallow this.
+ *
+ * This is invariant I2 of the Sprint 93 install-and-boot cluster — "no silent
+ * decline". Before #105 the two states were literally indistinguishable:
+ * measured against `stonyx@0.2.3-beta.95`, a consumer with `config/environment.ts`
+ * and the same consumer after `mv config/environment.js config/environment.xyz`
+ * both produced the byte-identical `Config not found: .../config/environment.js`.
+ */
+export declare const CONFIG_NOT_LOADABLE_PREFIX = "Config present but not loadable:";
+/**
+ * Did this runtime refuse OUR config file, or something our config imported?
+ *
+ * `FILE_TYPE_REFUSAL_CODES.has(code)` alone cannot tell. A config that loaded
+ * and ran perfectly well, but whose own nested `import()` hit a `.ts` under
+ * `node_modules`, throws the SAME code — and was reported as "this Node runtime
+ * refused to load your config", naming a file that is fine. That misdirection
+ * points the consumer at the one file that is not the problem, and the likeliest
+ * instance of it is the exact `.ts`-under-node_modules case this loader's own
+ * docs tell people to look for.
+ *
+ * FAIL DIRECTION — this is the property, not an implementation detail.
+ * `true` means "re-frame this as a refusal of the config", which is exactly the
+ * F-3 misdirection above. So when no path can be extracted this returns
+ * `false`, and the caller rethrows Node's own error untouched, `cause` and all.
+ * The consumer then reads what actually happened instead of a friendly sentence
+ * about the wrong file. This is what makes every future gap in the two patterns
+ * harmless: an unparseable message costs the I2 re-framing, not correctness.
+ *
+ * It previously returned `true` here, on the reasoning that keeping the loud
+ * re-frame mattered more than getting the filename right. Measured, that is
+ * backwards: the raw error is loud too — `main.ts`'s `NODE_ENV=test` swallow
+ * only absorbs `CONFIG_NOT_FOUND_PREFIX`, which a Node refusal never starts
+ * with — so failing this way loses nothing and stops naming the wrong file.
+ *
+ * Exported ONLY so its branches can be reached directly. Driving it through
+ * `importConfig` reaches the two path-comparison outcomes and nothing else.
+ * A predicate inside the guard that makes failures loud does not get to have
+ * branches no test can reach.
+ */
+export declare function refusalIsAboutTheConfig(message: string, configPath: string): boolean;
 export declare function importConfig<T = unknown>(basePath: string): Promise<T>;

package/dist/util/import-config.js

@@ -1,10 +1,256 @@
-import { existsSync } from 'fs';
-import { pathToFileURL } from 'url';
+import { existsSync, realpathSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+/**
+ * Extensions `importConfig` will load, in preference order.
+ *
+ * `.ts` first. `stonyx@0.2.3-beta.62` shipped exactly this list; some release in
+ * `(beta.62, beta.82]` reduced it to a hard-coded `.js`, which is the regression
+ * abofs/stonyx#105 reports. Three places in this repo disagreed with that
+ * reduction and none were changed with it:
+ *   - `docs/configuration.md:7,24` documents `.ts` as preferred and describes
+ *     this exact algorithm verbatim;
+ *   - `scripts/postinstall.js` writes `config/environment.ts` whenever the
+ *     consumer has a `tsconfig.json` — the framework wrote the file its own
+ *     loader then refused to read, which is how every TypeScript consumer (the
+ *     shape `docs/cli.md:29` calls the default) failed to boot at all;
+ *   - `src/util/resolve-entry-point.ts` — the sibling resolver, for `app.{ts,js}`
+ *     — still prefers `.ts` today.
+ */
+const LOADABLE_EXTENSIONS = ['ts', 'js'];
+/**
+ * Extensions a consumer plausibly writes a config as, that this loader does not
+ * RESOLVE. Their only purpose is to be DETECTED: see `CONFIG_NOT_LOADABLE_PREFIX`.
+ *
+ * Named for what is actually true of them. `.mjs`, `.cjs` and `.json` are all
+ * perfectly readable by Node — `import()` handles every one of them today.
+ * Nothing here is unreadable; they are simply not in `LOADABLE_EXTENSIONS`, so
+ * this loader never forms a path with them, and a consumer who writes one gets
+ * "config present but not loadable" instead of a silent "not found". The old
+ * name, UNREADABLE_EXTENSIONS, asserted a property of Node that is false, and
+ * invited a future reader to "fix" it by adding them to the resolver.
+ */
+const UNRESOLVED_EXTENSIONS = ['mts', 'cts', 'tsx', 'jsx', 'mjs', 'cjs', 'json'];
+/**
+ * "There is no config here." Callers are allowed to treat this as benign —
+ * `src/main.ts` does, for the optional `test/config/environment.*` override.
+ *
+ * `main.ts` matches on this exact string, so it is exported rather than
+ * duplicated: the swallow and the thrower must not be able to drift apart.
+ */
+export const CONFIG_NOT_FOUND_PREFIX = 'Config not found:';
+/**
+ * "There is a config here and I declined to load it." Deliberately NOT prefixed
+ * with `CONFIG_NOT_FOUND_PREFIX`, because `main.ts`'s `NODE_ENV=test` catch
+ * swallows that prefix and must not swallow this.
+ *
+ * This is invariant I2 of the Sprint 93 install-and-boot cluster — "no silent
+ * decline". Before #105 the two states were literally indistinguishable:
+ * measured against `stonyx@0.2.3-beta.95`, a consumer with `config/environment.ts`
+ * and the same consumer after `mv config/environment.js config/environment.xyz`
+ * both produced the byte-identical `Config not found: .../config/environment.js`.
+ */
+export const CONFIG_NOT_LOADABLE_PREFIX = 'Config present but not loadable:';
+/**
+ * Node error codes that mean "I can see this file and I refuse to load it",
+ * as distinct from "your config threw" or "your config imports something
+ * missing". Only these are re-framed; everything else propagates untouched so a
+ * genuine syntax error in a consumer's config still reads as one.
+ *
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` is the load-bearing member:
+ * Node refuses to type-strip anything under `node_modules`, so a `@stonyx/*`
+ * module that ships `config/environment.ts` crashes every consumer. That rule
+ * is unchanged by this fix and is why `docs/conventions/framework-modules.md`
+ * still requires modules to ship `.js` — but the failure is now named.
+ */
+const FILE_TYPE_REFUSAL_CODES = new Set([
+    'ERR_UNKNOWN_FILE_EXTENSION',
+    'ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING',
+]);
+/**
+ * The absolute POSIX path a Node refusal names, in the two shapes it names it.
+ *
+ * Both refusal codes name the file they refused, but differently — measured on
+ * node v24.13.0 at this head:
+ *
+ *   ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING
+ *     Stripping types is currently unsupported for files under node_modules,
+ *     for "/private/tmp/x/node_modules/dep/thing.ts"
+ *   ERR_UNKNOWN_FILE_EXTENSION
+ *     Unknown file extension ".ts" for /private/tmp/x/environment.ts
+ *
+ * In BOTH shapes the path is the last thing in the message, and both patterns
+ * are GREEDY, so each runs to the message tail rather than being bounded by a
+ * character class on the path body: the quoted one to the message-final quote,
+ * the bare one to the last `.ext` in the message. That is the whole mechanism —
+ * measured, an explicit `\s*$` anchor on either one is an equivalent mutant,
+ * so it is not there. The previous single pattern instead excluded space, `(`,
+ * `)`, `'` and `"` from the body,
+ * which meant a config under `~/My Project/` either failed extraction outright
+ * or backtracked onto an earlier `.` and yielded a truncated non-path.
+ * Measured end-to-end through `dist/` before this change, two consumers one
+ * character apart, each with a good `.js` config that nested-imports a `.ts`
+ * under `node_modules`:
+ *
+ *   .../plain/config/environment.js       -> raw ERR_UNSUPPORTED_...
+ *                                            naming node_modules/dep/thing.ts
+ *   .../My Project/config/environment.js  -> "Config present but not loadable:
+ *                                            .../My Project/config/environment.js"
+ *
+ * The second names a `.js` that loaded and ran perfectly. Anchoring on the
+ * tail extracts both, and the quoted form tolerates quotes inside the path
+ * because it runs to the message-final quote rather than to the first one.
+ *
+ * `(?:file:\/\/)?` is not defensive padding. Node names the refused file as a
+ * `file://` URL whenever the package scope containing it declares a `type`,
+ * and as a bare path when it does not -- one function
+ * (`stripTypeScriptModuleTypes`) reached from two call sites,
+ * `internal/modules/esm/translators:654,663` with the URL and
+ * `internal/modules/esm/get_format:148` with `fileURLToPath(url)`. Scope
+ * lookup stops at `node_modules`, so for `src/modules.ts:103` the deciding
+ * file is the MODULE's `package.json` -- and every `@stonyx/*` module declares
+ * `type: 'module'`, as does the app `src/cli/new.ts:81` scaffolds. The URL
+ * shape is the default case. See `test/unit/import-config-test.ts` for the
+ * measured matrix.
+ *
+ * Still POSIX-only, and still not exhaustive — a Windows path is not extracted,
+ * and neither is a message with trailing text after the path. That is now SAFE
+ * rather than merely degraded: see `refusalIsAboutTheConfig`.
+ */
+const QUOTED_REFUSED_PATH = /["']((?:file:\/\/)?\/.+)["']/;
+const BARE_REFUSED_PATH = /(?:^|\s)((?:file:\/\/)?\/.+\.[A-Za-z0-9]+)/;
+/** Resolves symlinks so `/tmp/...` and `/private/tmp/...` compare equal. */
+function realPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * The path a refusal names, or `null` when no path can be extracted from it.
+ *
+ * `fileURLToPath` is contained for the same reason `realPath` is: this runs
+ * INSIDE `importConfig`'s catch handler, so anything it throws replaces the
+ * refusal being handled and takes its `cause` with it — the exact loss
+ * invariant I2 exists to prevent. Regex-matchable inputs that throw exist and
+ * were measured at this head: `file:///a%2Fb.ts` -> `ERR_INVALID_FILE_URL_PATH`,
+ * `file:///%.ts` and `file:///a%zz.ts` -> bare `URIError: URI malformed`.
+ *
+ * Node's own emissions never produce them — `pathToFileURL` percent-encodes a
+ * literal `%` and never emits a bare `%2F` for a POSIX filename — but the
+ * message is only USUALLY Node's. `refusalIsAboutTheConfig` is exported public
+ * API with no input validation, and a `register()` / `--import` loader hook
+ * (this suite itself runs under `tsx`) can throw `ERR_UNKNOWN_FILE_EXTENSION`
+ * with any message it likes. Driven end-to-end through `dist/` with such a
+ * hook before this containment, the consumer got `ERR_INVALID_FILE_URL_PATH:
+ * File URL path must not include encoded / characters` with `cause` undefined,
+ * and the refusal it was actually handling was gone.
+ *
+ * An unparseable URL returns `null`, which the predicate reads as "cannot
+ * tell" -> `false` -> the original error propagates untouched. Same fail
+ * direction as every other unknown in here.
+ *
+ * Quoted shape first: it is the more specific of the two. Measured at this
+ * head the order is an EQUIVALENT mutant — swapping it leaves the suite at
+ * 130/0, because neither measured message shape matches both patterns — so the
+ * order is a statement of intent, not a load-bearing branch. Recorded here so
+ * the next mutation run does not re-chase it.
+ */
+function refusedPathFrom(message) {
+    const refused = QUOTED_REFUSED_PATH.exec(message)?.[1] ?? BARE_REFUSED_PATH.exec(message)?.[1];
+    if (!refused)
+        return null;
+    if (!refused.startsWith('file://'))
+        return refused;
+    try {
+        return fileURLToPath(refused);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Did this runtime refuse OUR config file, or something our config imported?
+ *
+ * `FILE_TYPE_REFUSAL_CODES.has(code)` alone cannot tell. A config that loaded
+ * and ran perfectly well, but whose own nested `import()` hit a `.ts` under
+ * `node_modules`, throws the SAME code — and was reported as "this Node runtime
+ * refused to load your config", naming a file that is fine. That misdirection
+ * points the consumer at the one file that is not the problem, and the likeliest
+ * instance of it is the exact `.ts`-under-node_modules case this loader's own
+ * docs tell people to look for.
+ *
+ * FAIL DIRECTION — this is the property, not an implementation detail.
+ * `true` means "re-frame this as a refusal of the config", which is exactly the
+ * F-3 misdirection above. So when no path can be extracted this returns
+ * `false`, and the caller rethrows Node's own error untouched, `cause` and all.
+ * The consumer then reads what actually happened instead of a friendly sentence
+ * about the wrong file. This is what makes every future gap in the two patterns
+ * harmless: an unparseable message costs the I2 re-framing, not correctness.
+ *
+ * It previously returned `true` here, on the reasoning that keeping the loud
+ * re-frame mattered more than getting the filename right. Measured, that is
+ * backwards: the raw error is loud too — `main.ts`'s `NODE_ENV=test` swallow
+ * only absorbs `CONFIG_NOT_FOUND_PREFIX`, which a Node refusal never starts
+ * with — so failing this way loses nothing and stops naming the wrong file.
+ *
+ * Exported ONLY so its branches can be reached directly. Driving it through
+ * `importConfig` reaches the two path-comparison outcomes and nothing else.
+ * A predicate inside the guard that makes failures loud does not get to have
+ * branches no test can reach.
+ */
+export function refusalIsAboutTheConfig(message, configPath) {
+    const refusedPath = refusedPathFrom(message);
+    if (refusedPath === null)
+        return false;
+    return refusedPath === configPath || realPath(refusedPath) === realPath(configPath);
+}
 export async function importConfig(basePath) {
-    const path = `${basePath}.js`;
-    if (!existsSync(path)) {
-        throw new Error(`Config not found: ${path}`);
+    const matches = LOADABLE_EXTENSIONS.filter(ext => existsSync(`${basePath}.${ext}`));
+    if (matches.length === 0) {
+        const declined = UNRESOLVED_EXTENSIONS.filter(ext => existsSync(`${basePath}.${ext}`));
+        if (declined.length > 0) {
+            throw new Error(`${CONFIG_NOT_LOADABLE_PREFIX} ${basePath}.${declined.join(` and ${basePath}.`)} ` +
+                `exists, but Stonyx loads ${basePath}.ts or ${basePath}.js only. ` +
+                `Rename or compile it — this is not a missing config.`);
+        }
+        throw new Error(`${CONFIG_NOT_FOUND_PREFIX} ${basePath}.{ts,js}`);
+    }
+    if (matches.length > 1) {
+        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).`);
+    }
+    const path = `${basePath}.${matches[0]}`;
+    try {
+        const mod = await import(pathToFileURL(path).href);
+        return mod.default;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code && FILE_TYPE_REFUSAL_CODES.has(code) && refusalIsAboutTheConfig(error.message, path)) {
+            // Both files exist AND the `.ts` was refused. This is the one state where
+            // the both-present warning printed a few lines above is actively wrong
+            // advice: it says "delete the .js", and here the `.js` is the only file
+            // this runtime can read. Say so explicitly rather than leaving the
+            // consumer to reconcile two messages from the same call.
+            //
+            // It is also a deliberate behaviour change. `stonyx@0.2.3-beta.95`
+            // resolved `${basePath}.js` unconditionally, so this exact state LOADED
+            // and booted; measured against that loader, same fixture, plain node:
+            // it returned the `.js` default export with no warning. Preferring `.ts`
+            // is the point of #105, and the population most likely to hold both
+            // files is the one that worked around #105 by renaming to `.js` while
+            // the postinstall kept writing the `.ts` stub. So this message has to
+            // carry the "this used to work" fact, not just the remedy.
+            const sibling = matches.length > 1
+                ? ` ${basePath}.js also exists and this runtime CAN read it, but .ts wins the preference order` +
+                    ` so the .js is never reached. Disregard the "delete the .js" warning above — in THIS state the` +
+                    ` fix is the opposite one: remove or compile ${basePath}.ts.` +
+                    ` (stonyx@0.2.3-beta.95 loaded the .js here; preferring .ts is a deliberate change — abofs/stonyx#105.)`
+                : '';
+            throw new Error(`${CONFIG_NOT_LOADABLE_PREFIX} ${path} exists, but this Node runtime refused to load it ` +
+                `(${code}): ${error.message}.${sibling}`, { cause: error });
+        }
+        throw error;
     }
-    const mod = await import(pathToFileURL(path).href);
-    return mod.default;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-beta.95",
+  "version": "0.2.3-beta.97",
   "description": "Base stonyx framework module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",