@zintrust/core 0.4.2 → 0.4.3

package/bin/zintrust-main.js

@@ -105,7 +105,7 @@ export async function run() {
         try {
             ({ OptionalCliExtensions: optionalCliExtensions } =
                 await import('../src/cli/OptionalCliExtensions.js'));
-            optionalCliStatuses = await optionalCliExtensions.tryImportInstalledExtensions();
+            optionalCliStatuses = await optionalCliExtensions.loadForArgs(args0);
         }
         catch {
             // best-effort; missing optional extensions must not block the CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/cli/OptionalCliExtensions.d.ts

@@ -13,20 +13,29 @@ export type OptionalCliExtensionStatus = Readonly<{
     loaded: boolean;
     source: OptionalCliExtensionLoadSource;
 }>;
+type OptionalCliExtensionLoadOptions = Readonly<{
+    logFailures?: boolean;
+}>;
 export declare const OptionalCliExtensions: Readonly<{
     tryImportInstalledExtensions(): Promise<OptionalCliExtensionStatus[]>;
+    loadForArgs(args: string[]): Promise<OptionalCliExtensionStatus[]>;
     findMissingExtensionForArgs(args: string[], statuses: ReadonlyArray<OptionalCliExtensionStatus>): OptionalCliExtensionStatus | undefined;
     getMissingExtensionMessage(status: OptionalCliExtensionStatus): string;
+    findRequestedExtension: (args: string[]) => OptionalCliExtension | undefined;
 }>;
 export declare const OptionalCliExtensionsInternal: Readonly<{
     getProjectCwd: () => string;
     resolveProjectRoot: () => string;
-    resolveProjectInstalledUrl: (entry: OptionalCliExtension) => string | null;
-    tryImportProjectInstalledPackage: (entry: OptionalCliExtension) => Promise<boolean>;
-    tryImportLocalCandidate: (entry: OptionalCliExtension) => Promise<boolean>;
-    tryImportPackageSpecifier: (entry: OptionalCliExtension) => Promise<boolean>;
-    tryImportExtension: (entry: OptionalCliExtension) => Promise<OptionalCliExtensionStatus>;
+    resolveProjectInstalledUrl: (entry: OptionalCliExtension, options?: OptionalCliExtensionLoadOptions) => string | null;
+    shouldLogFailures: (options?: OptionalCliExtensionLoadOptions) => boolean;
+    debugFailure: (message: string, meta: Record<string, unknown>, options?: OptionalCliExtensionLoadOptions) => void;
+    tryImportProjectInstalledPackage: (entry: OptionalCliExtension, options?: OptionalCliExtensionLoadOptions) => Promise<boolean>;
+    tryImportLocalCandidate: (entry: OptionalCliExtension, options?: OptionalCliExtensionLoadOptions) => Promise<boolean>;
+    tryImportPackageSpecifier: (entry: OptionalCliExtension, options?: OptionalCliExtensionLoadOptions) => Promise<boolean>;
+    tryImportExtension: (entry: OptionalCliExtension, options?: OptionalCliExtensionLoadOptions) => Promise<OptionalCliExtensionStatus>;
     getRequestedCommand: (args: string[]) => string | undefined;
+    findRequestedExtension: (args: string[]) => OptionalCliExtension | undefined;
+    isRootHelpRequest: (args: string[]) => boolean;
 }>;
 export {};
 //# sourceMappingURL=OptionalCliExtensions.d.ts.map

package/src/cli/OptionalCliExtensions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OptionalCliExtensions.d.ts","sourceRoot":"","sources":["../../../src/cli/OptionalCliExtensions.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,8BAA8B,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE3F,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AA2LH,eAAO,MAAM,qBAAqB;oCACM,OAAO,CAAC,0BAA0B,EAAE,CAAC;sCAKnE,MAAM,EAAE,YACJ,aAAa,CAAC,0BAA0B,CAAC,GAClD,0BAA0B,GAAG,SAAS;uCASN,0BAA0B,GAAG,MAAM;EAOtE,CAAC;AAEH,eAAO,MAAM,6BAA6B;yBAhNhB,MAAM;8BAQD,MAAM;wCAuCM,oBAAoB,KAAG,MAAM,GAAG,IAAI;8CAiBxB,oBAAoB,KAAG,OAAO,CAAC,OAAO,CAAC;qCAqBhD,oBAAoB,KAAG,OAAO,CAAC,OAAO,CAAC;uCA2BrC,oBAAoB,KAAG,OAAO,CAAC,OAAO,CAAC;gCAmB9E,oBAAoB,KAC1B,OAAO,CAAC,0BAA0B,CAAC;gCAwCH,MAAM,EAAE,KAAG,MAAM,GAAG,SAAS;EA6C9D,CAAC"}
+{"version":3,"file":"OptionalCliExtensions.d.ts","sourceRoot":"","sources":["../../../src/cli/OptionalCliExtensions.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,oBAAoB,GAAG;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,8BAA8B,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAE3F,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,+BAA+B,GAAG,QAAQ,CAAC;IAC9C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC,CAAC;AAoPH,eAAO,MAAM,qBAAqB;oCACM,OAAO,CAAC,0BAA0B,EAAE,CAAC;sBAQnD,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,EAAE,CAAC;sCAmBhE,MAAM,EAAE,YACJ,aAAa,CAAC,0BAA0B,CAAC,GAClD,0BAA0B,GAAG,SAAS;uCASN,0BAA0B,GAAG,MAAM;mCArDlC,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;EA8D/E,CAAC;AAEH,eAAO,MAAM,6BAA6B;yBAjShB,MAAM;8BAQD,MAAM;wCAsD5B,oBAAoB,YACjB,+BAA+B,KACxC,MAAM,GAAG,IAAI;kCAlDqB,+BAA+B,KAAG,OAAO;4BAMnE,MAAM,QACT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YACnB,+BAA+B,KACxC,IAAI;8CA+DE,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;qCA0BV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;uCAgCV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,OAAO,CAAC;gCAuBV,oBAAoB,YACjB,+BAA+B,KACxC,OAAO,CAAC,0BAA0B,CAAC;gCAwCH,MAAM,EAAE,KAAG,MAAM,GAAG,SAAS;mCAU1B,MAAM,EAAE,KAAG,oBAAoB,GAAG,SAAS;8BAOhD,MAAM,EAAE,KAAG,OAAO;EAsEjD,CAAC"}

package/src/cli/OptionalCliExtensions.js

@@ -19,6 +19,16 @@ const resolveProjectRoot = () => {
         return configured;
     return getProjectCwd();
 };
+const shouldLogFailures = (options) => {
+    if (options?.logFailures === true)
+        return true;
+    return readEnvString('ZINTRUST_DEBUG_OPTIONAL_CLI_EXTENSIONS').trim() === '1';
+};
+const debugFailure = (message, meta, options) => {
+    if (!shouldLogFailures(options))
+        return;
+    Logger.debug(message, meta);
+};
 const OPTIONAL_CLI_EXTENSIONS = Object.freeze([
     {
         packageName: '@zintrust/d1-migrator',
@@ -51,7 +61,7 @@ const OPTIONAL_CLI_EXTENSIONS = Object.freeze([
         ],
     },
 ]);
-const resolveProjectInstalledUrl = (entry) => {
+const resolveProjectInstalledUrl = (entry, options) => {
     try {
         const projectRoot = resolveProjectRoot();
         const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
@@ -59,17 +69,17 @@ const resolveProjectInstalledUrl = (entry) => {
         return pathToFileURL(resolved).href;
     }
     catch (error) {
-        Logger.debug('[cli] Optional CLI extension not resolved from project root', {
+        debugFailure('[cli] Optional CLI extension not resolved from project root', {
             packageName: entry.packageName,
             specifier: entry.specifier,
             projectRoot: resolveProjectRoot(),
             error: error instanceof Error ? error.message : String(error),
-        });
+        }, options);
         return null;
     }
 };
-const tryImportProjectInstalledPackage = async (entry) => {
-    const resolvedUrl = resolveProjectInstalledUrl(entry);
+const tryImportProjectInstalledPackage = async (entry, options) => {
+    const resolvedUrl = resolveProjectInstalledUrl(entry, options);
     if (resolvedUrl === null)
         return false;
     try {
@@ -81,15 +91,15 @@ const tryImportProjectInstalledPackage = async (entry) => {
         return true;
     }
     catch (error) {
-        Logger.debug('[cli] Optional CLI extension project import failed', {
+        debugFailure('[cli] Optional CLI extension project import failed', {
             packageName: entry.packageName,
             resolvedUrl,
             error: error instanceof Error ? error.message : String(error),
-        });
+        }, options);
         return false;
     }
 };
-const tryImportLocalCandidate = async (entry) => {
+const tryImportLocalCandidate = async (entry, options) => {
     const existingCandidates = entry.localCandidates.filter((candidate) => existsSync(candidate));
     if (existingCandidates.length === 0)
         return false;
@@ -103,17 +113,17 @@ const tryImportLocalCandidate = async (entry) => {
             return true;
         }
         catch (error) {
-            Logger.debug('[cli] Optional CLI extension local fallback failed', {
+            debugFailure('[cli] Optional CLI extension local fallback failed', {
                 packageName: entry.packageName,
                 candidate,
                 error: error instanceof Error ? error.message : String(error),
-            });
+            }, options);
             return false;
         }
     }));
     return results.some(Boolean);
 };
-const tryImportPackageSpecifier = async (entry) => {
+const tryImportPackageSpecifier = async (entry, options) => {
     try {
         await import(entry.specifier);
         Logger.debug('[cli] Loaded optional CLI extension package', {
@@ -123,16 +133,16 @@ const tryImportPackageSpecifier = async (entry) => {
         return true;
     }
     catch (error) {
-        Logger.debug('[cli] Optional CLI extension package not loaded', {
+        debugFailure('[cli] Optional CLI extension package not loaded', {
             packageName: entry.packageName,
             specifier: entry.specifier,
             error: error instanceof Error ? error.message : String(error),
-        });
+        }, options);
         return false;
     }
 };
-const tryImportExtension = async (entry) => {
-    if (await tryImportProjectInstalledPackage(entry)) {
+const tryImportExtension = async (entry, options) => {
+    if (await tryImportProjectInstalledPackage(entry, options)) {
         return {
             packageName: entry.packageName,
             commands: [...entry.commands],
@@ -141,7 +151,7 @@ const tryImportExtension = async (entry) => {
             source: 'project',
         };
     }
-    if (await tryImportPackageSpecifier(entry)) {
+    if (await tryImportPackageSpecifier(entry, options)) {
         return {
             packageName: entry.packageName,
             commands: [...entry.commands],
@@ -150,7 +160,7 @@ const tryImportExtension = async (entry) => {
             source: 'package',
         };
     }
-    if (await tryImportLocalCandidate(entry)) {
+    if (await tryImportLocalCandidate(entry, options)) {
         return {
             packageName: entry.packageName,
             commands: [...entry.commands],
@@ -175,9 +185,33 @@ const getRequestedCommand = (args) => {
     }
     return typeof args[0] === 'string' && args[0].trim() !== '' ? args[0].trim() : undefined;
 };
+const findRequestedExtension = (args) => {
+    const requestedCommand = getRequestedCommand(args);
+    if (requestedCommand === undefined)
+        return undefined;
+    return OPTIONAL_CLI_EXTENSIONS.find((entry) => entry.commands.includes(requestedCommand));
+};
+const isRootHelpRequest = (args) => {
+    if (args.length === 0)
+        return true;
+    const first = typeof args[0] === 'string' ? args[0].trim() : '';
+    if (first === '' || first === '-h' || first === '--help')
+        return true;
+    return first === 'help' && getRequestedCommand(args) === undefined;
+};
 export const OptionalCliExtensions = Object.freeze({
     async tryImportInstalledExtensions() {
-        return Promise.all(OPTIONAL_CLI_EXTENSIONS.map(tryImportExtension));
+        return Promise.all(OPTIONAL_CLI_EXTENSIONS.map(async (entry) => tryImportExtension(entry, { logFailures: false })));
+    },
+    async loadForArgs(args) {
+        const requestedExtension = findRequestedExtension(args);
+        if (requestedExtension !== undefined) {
+            return [await tryImportExtension(requestedExtension, { logFailures: false })];
+        }
+        if (isRootHelpRequest(args)) {
+            return Promise.all(OPTIONAL_CLI_EXTENSIONS.map(async (entry) => tryImportExtension(entry, { logFailures: false })));
+        }
+        return [];
     },
     findMissingExtensionForArgs(args, statuses) {
         const requestedCommand = getRequestedCommand(args);
@@ -192,14 +226,19 @@ export const OptionalCliExtensions = Object.freeze({
             `Install it and try again: ${status.installCommand}`,
         ].join(' ');
     },
+    findRequestedExtension,
 });
 export const OptionalCliExtensionsInternal = Object.freeze({
     getProjectCwd,
     resolveProjectRoot,
     resolveProjectInstalledUrl,
+    shouldLogFailures,
+    debugFailure,
     tryImportProjectInstalledPackage,
     tryImportLocalCandidate,
     tryImportPackageSpecifier,
     tryImportExtension,
     getRequestedCommand,
+    findRequestedExtension,
+    isRootHelpRequest,
 });

package/src/cli/commands/StartCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAwnBvF,eAAO,MAAM,YAAY;cACb,YAAY;EA6BtB,CAAC"}
+{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAspBvF,eAAO,MAAM,YAAY;cACb,YAAY;EA6BtB,CAAC"}

package/src/cli/commands/StartCommand.js

@@ -79,6 +79,28 @@ const resolveRuntime = (options) => {
     const raw = typeof options.runtime === 'string' ? options.runtime.trim() : '';
     return raw === '' ? undefined : raw;
 };
+const resolveConfiguredRuntime = (options) => {
+    const cliRuntime = resolveRuntime(options);
+    if (cliRuntime !== undefined && cliRuntime !== 'auto')
+        return cliRuntime;
+    const envRuntime = readEnvString('RUNTIME').trim();
+    if (envRuntime === '' || envRuntime === 'auto')
+        return undefined;
+    return envRuntime;
+};
+const isCloudflareRuntimeRequest = (runtime) => {
+    if (typeof runtime !== 'string')
+        return false;
+    const normalized = runtime.trim().toLowerCase();
+    return normalized === 'cloudflare' || normalized === 'cloudflare-workers';
+};
+const assertCompatibleStartVariant = (variant, configuredRuntime) => {
+    if (variant !== 'node')
+        return;
+    if (!isCloudflareRuntimeRequest(configuredRuntime))
+        return;
+    throw ErrorFactory.createCliError('Error: Cloudflare runtime requires Wrangler dev mode. Run "zin start --wg" (or "zin s --wg") instead of plain "zin start".');
+};
 const resolveStartVariant = (options) => {
     const wantWrangler = options.wrangler === true || options.wg === true;
     const wantDeno = options.deno === true;
@@ -423,6 +445,7 @@ const executeStart = async (options, cmd) => {
     const mode = resolveMode(options);
     const port = resolvePort(options);
     const runtime = resolveRuntime(options);
+    const configuredRuntime = resolveConfiguredRuntime(options);
     const variant = resolveStartVariant(options);
     const envName = typeof options.env === 'string' ? options.env.trim() : '';
     let effectiveRuntime = runtime;
@@ -434,6 +457,7 @@ const executeStart = async (options, cmd) => {
         await executeSplitStart(cmd, cwd, options);
         return;
     }
+    assertCompatibleStartVariant(variant, configuredRuntime);
     const cacheEnabled = resolveCacheEnabledPreference(options);
     EnvFileLoader.applyCliOverrides({
         nodeEnv: mode,

package/src/index.js

@@ -1,11 +1,11 @@
 /**
- * @zintrust/core v0.4.2
+ * @zintrust/core v0.4.3
  *
  * ZinTrust Framework - Production-Grade TypeScript Backend
  * Built for performance, type safety, and exceptional developer experience
  *
  * Build Information:
- *   Built: 2026-03-20T09:35:09.203Z
+ *   Built: 2026-03-20T12:13:34.410Z
  *   Node: >=20.0.0
  *   License: MIT
  *
@@ -21,7 +21,7 @@
  * Available at runtime for debugging and health checks
  */
 export const ZINTRUST_VERSION = '0.1.41';
-export const ZINTRUST_BUILD_DATE = '2026-03-20T09:35:09.174Z'; // Replaced during build
+export const ZINTRUST_BUILD_DATE = '2026-03-20T12:13:34.378Z'; // Replaced during build
 export { Application } from './boot/Application.js';
 export { AwsSigV4 } from './common/index.js';
 export { SignedRequest } from './security/SignedRequest.js';