@zintrust/core 0.1.42 → 0.1.44

package/src/cli/commands/InitContainersProxyCommand.js

@@ -0,0 +1,159 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { PromptHelper } from '../PromptHelper.js';
+import { Logger } from '../../config/logger.js';
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from '../../node-singletons/fs.js';
+import { join } from '../../node-singletons/path.js';
+const WRANGLER_CONTAINERS_PROXY_TEMPLATE = `/**
+ * ============================================================================
+ * ZinTrust Cloudflare Containers Proxy
+ * ============================================================================
+ * This Worker acts as the "gateway" for the DB/KV/SMTP proxy stack.
+ *
+ * Requests are routed by path prefix:
+ *   /mysql/*     -> ZintrustMySqlProxyContainer (port 8789)
+ *   /postgres/*  -> ZintrustPostgresProxyContainer (port 8790)
+ *   /redis/*     -> ZintrustRedisProxyContainer (port 8791)
+ *   /mongodb/*   -> ZintrustMongoDbProxyContainer (port 8792)
+ *   /sqlserver/* -> ZintrustSqlServerProxyContainer (port 8793)
+ *   /smtp/*      -> ZintrustSmtpProxyContainer (port 8794)
+ *
+ * Notes:
+ * - You must install the runtime package: "@zintrust/cloudflare-containers-proxy".
+ * - Secrets should be uploaded with the same config file.
+ * ============================================================================
+ */
+
+{
+  "name": "zintrust-containers-proxy",
+  "main": "./src/containers-proxy.ts",
+
+  "compatibility_date": "2025-04-21",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "workers_dev": true,
+  "minify": false,
+
+  "containers": [
+    { "class_name": "ZintrustMySqlProxyContainer", "image": "./Dockerfile", "max_instances": 10 },
+    { "class_name": "ZintrustPostgresProxyContainer", "image": "./Dockerfile", "max_instances": 10 },
+    { "class_name": "ZintrustRedisProxyContainer", "image": "./Dockerfile", "max_instances": 10 },
+    { "class_name": "ZintrustMongoDbProxyContainer", "image": "./Dockerfile", "max_instances": 10 },
+    { "class_name": "ZintrustSqlServerProxyContainer", "image": "./Dockerfile", "max_instances": 10 },
+    { "class_name": "ZintrustSmtpProxyContainer", "image": "./Dockerfile", "max_instances": 10 }
+  ],
+
+  "durable_objects": {
+    "bindings": [
+      { "name": "ZT_PROXY_MYSQL", "class_name": "ZintrustMySqlProxyContainer" },
+      { "name": "ZT_PROXY_POSTGRES", "class_name": "ZintrustPostgresProxyContainer" },
+      { "name": "ZT_PROXY_REDIS", "class_name": "ZintrustRedisProxyContainer" },
+      { "name": "ZT_PROXY_MONGODB", "class_name": "ZintrustMongoDbProxyContainer" },
+      { "name": "ZT_PROXY_SQLSERVER", "class_name": "ZintrustSqlServerProxyContainer" },
+      { "name": "ZT_PROXY_SMTP", "class_name": "ZintrustSmtpProxyContainer" }
+    ]
+  },
+
+  "migrations": [
+    {
+      "tag": "containers-proxy-v1",
+      "new_sqlite_classes": [
+        "ZintrustMySqlProxyContainer",
+        "ZintrustPostgresProxyContainer",
+        "ZintrustRedisProxyContainer",
+        "ZintrustMongoDbProxyContainer",
+        "ZintrustSqlServerProxyContainer",
+        "ZintrustSmtpProxyContainer"
+      ]
+    }
+  ],
+
+  "env": {
+    "staging": {
+      "name": "zintrust-containers-proxy-staging",
+      "minify": false,
+      "vars": {
+        "ENVIRONMENT": "staging",
+        "APP_NAME": "ZinTrust",
+        "CSRF_SKIP_PATHS": "/api/*,/queue-monitor/*"
+      },
+      // Add routes here when ready:
+      // "routes": [{ "pattern": "proxy-staging.example.com", "custom_domain": true }]
+    },
+    "production": {
+      "name": "zintrust-containers-proxy-production",
+      "minify": true,
+      "vars": {
+        "ENVIRONMENT": "production",
+        "APP_NAME": "ZinTrust",
+        "CSRF_SKIP_PATHS": "/api/*,/queue-monitor/*"
+      },
+      // Add routes here when ready:
+      // "routes": [{ "pattern": "proxy.example.com", "custom_domain": true }]
+    }
+  }
+}
+`;
+const WORKER_ENTRY_TEMPLATE = `export { default } from '@zintrust/cloudflare-containers-proxy';
+export * from '@zintrust/cloudflare-containers-proxy';
+`;
+const backupSuffix = () => new Date().toISOString().replaceAll(/[:.]/g, '-');
+const backupFileIfExists = (filePath) => {
+    if (!existsSync(filePath))
+        return;
+    const backupPath = `${filePath}.bak.${backupSuffix()}`;
+    copyFileSync(filePath, backupPath);
+    Logger.info(`🗂️ Backup created: ${backupPath}`);
+};
+async function writeWranglerConfig(cwd) {
+    const configPath = join(cwd, 'wrangler.containers-proxy.jsonc');
+    let shouldWrite = true;
+    if (existsSync(configPath)) {
+        shouldWrite = await PromptHelper.confirm('wrangler.containers-proxy.jsonc already exists. Overwrite?', false);
+    }
+    if (!shouldWrite) {
+        Logger.info('Skipped wrangler.containers-proxy.jsonc');
+        return;
+    }
+    backupFileIfExists(configPath);
+    writeFileSync(configPath, WRANGLER_CONTAINERS_PROXY_TEMPLATE);
+    Logger.info('✅ Created wrangler.containers-proxy.jsonc');
+}
+async function writeWorkerEntry(cwd) {
+    const srcDir = join(cwd, 'src');
+    const entryPath = join(srcDir, 'containers-proxy.ts');
+    if (!existsSync(srcDir)) {
+        mkdirSync(srcDir, { recursive: true });
+    }
+    let shouldWrite = true;
+    if (existsSync(entryPath)) {
+        shouldWrite = await PromptHelper.confirm('src/containers-proxy.ts already exists. Overwrite?', false);
+    }
+    if (!shouldWrite) {
+        Logger.info('Skipped src/containers-proxy.ts');
+        return;
+    }
+    backupFileIfExists(entryPath);
+    writeFileSync(entryPath, WORKER_ENTRY_TEMPLATE);
+    Logger.info('✅ Created src/containers-proxy.ts');
+}
+export const InitContainersProxyCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'init:containers-proxy',
+            aliases: ['init:ccp', 'init:cf-containers-proxy'],
+            description: 'Scaffold Cloudflare Containers proxy Worker (wrangler.containers-proxy.jsonc)',
+            async execute() {
+                Logger.info('Initializing Cloudflare Containers proxy scaffolding...');
+                const cwd = process.cwd();
+                await writeWranglerConfig(cwd);
+                await writeWorkerEntry(cwd);
+                Logger.info('✅ Containers proxy scaffolding complete.');
+                Logger.info('Install runtime: npm i @zintrust/cloudflare-containers-proxy');
+                Logger.info('Dev (Wrangler + Docker): zin docker --wrangler-config wrangler.containers-proxy.jsonc --env staging');
+                Logger.info('Dev (short): zin dk -e staging');
+                Logger.info('Deploy (short): zin d:ccp');
+                await Promise.resolve();
+            },
+        });
+    },
+});

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

@@ -1 +1 @@
-{"version":3,"file":"NewCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/NewCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAerE,KAAK,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,cAAc,GAAG,WAAW,CAAC;AACnE,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AAYhF,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwPhD,UAAU,WAAY,SAAQ,YAAY;IACxC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACxF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,EAAE,CAAC;IACjF,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpE;AAwOD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;cACO,WAAW;EAGrB,CAAC"}
+{"version":3,"file":"NewCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/NewCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAgBrE,KAAK,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,cAAc,GAAG,WAAW,CAAC;AACnE,KAAK,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AAYhF,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwPhD,UAAU,WAAY,SAAQ,YAAY;IACxC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACxF,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,gBAAgB,EAAE,CAAC;IACjF,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC;IAChC,YAAY,IAAI,MAAM,CAAC;IACvB,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,sBAAsB,EAC9B,SAAS,CAAC,EAAE,OAAO,GAClB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACpE;AA0RD;;;GAGG;AACH,eAAO,MAAM,UAAU;IACrB;;OAEG;cACO,WAAW;EAGrB,CAAC"}

package/src/cli/commands/NewCommand.js

@@ -8,6 +8,7 @@ import { extractErrorMessage, resolvePackageManager } from '../../common/index.j
 import { appConfig } from '../../config/app.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
 import { execFileSync } from '../../node-singletons/child-process.js';
+import fs from '../../node-singletons/fs.js';
 import * as path from '../../node-singletons/path.js';
 import chalk from 'chalk';
 const getGitBinary = () => 'git';
@@ -233,9 +234,39 @@ const addOptions = (command) => {
     command.option('--install', 'Force dependency installation (useful to override CI defaults)');
     command.option('--package-manager <manager>', 'Package manager to use (npm, yarn, pnpm)');
     command.option('--governance', 'Install governance tooling (ESLint + architecture tests)', false);
+    command.option('--with-d1-proxy', 'Add @zintrust/cloudflare-d1-proxy to package.json (for deploying the D1 proxy worker)', false);
     command.option('--force', 'Overwrite existing directory');
     command.option('--overwrite', 'Overwrite existing directory');
 };
+const maybeAddD1ProxyDependency = (projectPath, options, log) => {
+    const enabled = options['withD1Proxy'] === true || options['with-d1-proxy'] === true;
+    if (!enabled)
+        return;
+    const packageJsonPath = path.join(projectPath, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        log.warn(`Could not add @zintrust/cloudflare-d1-proxy (missing package.json at ${packageJsonPath})`);
+        return;
+    }
+    try {
+        const raw = fs.readFileSync(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        const dependencies = { ...pkg.dependencies };
+        if (typeof dependencies['@zintrust/cloudflare-d1-proxy'] !== 'string') {
+            // Avoid pinning to core version (they can differ). Use a safe caret range.
+            dependencies['@zintrust/cloudflare-d1-proxy'] = '^0.1.42';
+        }
+        const next = {
+            ...pkg,
+            dependencies,
+        };
+        fs.writeFileSync(packageJsonPath, JSON.stringify(next, null, 2) + '\n');
+        log.info('✅ Added @zintrust/cloudflare-d1-proxy to dependencies');
+    }
+    catch (error) {
+        ErrorFactory.createCliError('Failed to update package.json with D1 proxy dependency', error);
+        log.warn('Please add @zintrust/cloudflare-d1-proxy manually if you need the proxy worker.');
+    }
+};
 const resolveProjectName = async (options) => {
     const argName = options.args?.[0];
     const projectName = argName ?? (await PromptHelper.projectName('my-zintrust-app', true));
@@ -285,6 +316,8 @@ const createProject = async (target, options, command) => {
             throw ErrorFactory.createCliError(gov.message ?? 'Governance scaffolding failed', gov);
         }
     }
+    // Optional dependency injection must happen before `npm/yarn/pnpm install`.
+    maybeAddD1ProxyDependency(target.projectPath, options, command);
 };
 const maybeInitializeGit = (options, command, target) => {
     if (options['git'] !== false) {

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

@@ -1 +1 @@
-{"version":3,"file":"PutCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/PutCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAmNvF,eAAO,MAAM,UAAU;cACX,YAAY;EAWtB,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"PutCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/PutCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0OvF,eAAO,MAAM,UAAU;cACX,YAAY;EAWtB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/cli/commands/PutCommand.js

@@ -74,9 +74,14 @@ const getPutTimeoutMs = () => {
         return 120000;
     return parsed;
 };
-const putSecret = (wranglerEnv, key, value) => {
+const putSecret = (wranglerEnv, key, value, configPath) => {
     const npmPath = resolveNpmPath();
-    execFileSync(npmPath, ['exec', '--yes', '--', 'wrangler', 'secret', 'put', key, '--env', wranglerEnv], {
+    const args = ['exec', '--yes', '--', 'wrangler'];
+    if (typeof configPath === 'string' && configPath.trim().length > 0) {
+        args.push('--config', configPath.trim());
+    }
+    args.push('secret', 'put', key, '--env', wranglerEnv);
+    execFileSync(npmPath, args, {
         stdio: ['pipe', 'inherit', 'inherit'],
         input: value,
         encoding: 'utf8',
@@ -91,6 +96,7 @@ const addOptions = (command) => {
         .option('--wg <env...>', 'Wrangler environment target(s), e.g. d1-proxy kv-proxy')
         .option('--var <configKey...>', 'Config array key(s) from .zintrust.json (e.g. d1_env kv_env)')
         .option('--env_path <path>', 'Path to env file used as source values', '.env')
+        .option('-c, --config <path>', 'Wrangler config file to target (optional)')
         .option('--dry-run', 'Show what would be uploaded without calling wrangler');
 };
 const ensureCloudflareProvider = (providerRaw) => {
@@ -122,7 +128,7 @@ const reportResult = (cmd, pushed, failures) => {
         cmd.warn(`${item.key} -> ${item.wranglerEnv}: ${item.reason}`);
     }
 };
-const processPut = (cmd, wranglerEnvs, selectedKeys, envMap, dryRun) => {
+const processPut = (cmd, wranglerEnvs, selectedKeys, envMap, dryRun, configPath) => {
     let pushed = 0;
     const failures = [];
     for (const wranglerEnv of wranglerEnvs) {
@@ -135,7 +141,7 @@ const processPut = (cmd, wranglerEnvs, selectedKeys, envMap, dryRun) => {
             try {
                 if (!dryRun) {
                     cmd.info(`putting ${key} -> ${wranglerEnv}...`);
-                    putSecret(wranglerEnv, key, value);
+                    putSecret(wranglerEnv, key, value, configPath);
                 }
                 pushed += 1;
                 cmd.info(`${dryRun ? '[dry-run] ' : ''}put ${key} -> ${wranglerEnv}`);
@@ -156,7 +162,11 @@ const execute = async (cmd, options) => {
     const envMap = await EnvFile.read({ cwd, path: envFilePath });
     const wranglerEnvs = resolveWranglerEnvs(options);
     const dryRun = options.dryRun === true;
-    const result = processPut(cmd, wranglerEnvs, selectedKeys, envMap, dryRun);
+    const configPath = typeof options.config === 'string' ? options.config.trim() : '';
+    if (configPath !== '' && !existsSync(path.join(cwd, configPath))) {
+        throw ErrorFactory.createCliError(`Wrangler config not found: ${configPath}`);
+    }
+    const result = processPut(cmd, wranglerEnvs, selectedKeys, envMap, dryRun, configPath === '' ? undefined : configPath);
     reportResult(cmd, result.pushed, result.failures);
 };
 export const PutCommand = Object.freeze({

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;AAqkBvF,eAAO,MAAM,YAAY;cACb,YAAY;EA0BtB,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;AAwnBvF,eAAO,MAAM,YAAY;cACb,YAAY;EA6BtB,CAAC"}

package/src/cli/commands/StartCommand.js

@@ -132,6 +132,20 @@ const resolveWatchPreference = (options, mode) => {
         return options.watch;
     return mode === 'development';
 };
+const resolveCacheEnabledPreference = (options) => {
+    const hasCache = hasFlag('--cache');
+    const hasNoCache = hasFlag('--no-cache');
+    if (hasCache && hasNoCache) {
+        throw ErrorFactory.createCliError('Error: Cannot use both --cache and --no-cache.');
+    }
+    if (hasCache)
+        return true;
+    if (hasNoCache)
+        return false;
+    if (typeof options.cache === 'boolean')
+        return options.cache;
+    return undefined;
+};
 const readPackageJson = (cwd) => {
     const packagePath = path.join(cwd, 'package.json');
     if (!existsSync(packagePath)) {
@@ -227,16 +241,29 @@ const resolveNodeProdCommand = (cwd) => {
     }
     return { command: 'node', args: [compiled] };
 };
-const executeWranglerStart = async (cmd, cwd, port, runtime, envName) => {
+const executeWranglerStart = async (cmd, cwd, port, runtime, envName, wranglerConfig) => {
     if (runtime !== undefined) {
         throw ErrorFactory.createCliError('Error: --runtime is not supported with --wrangler (Wrangler controls Workers runtime).');
     }
-    const configPath = findWranglerConfig(cwd);
+    const normalizedConfig = typeof wranglerConfig === 'string' ? wranglerConfig.trim() : '';
+    const explicitConfigFullPath = normalizedConfig.length > 0 ? path.join(cwd, normalizedConfig) : undefined;
+    const configPath = explicitConfigFullPath ?? findWranglerConfig(cwd);
     const entry = resolveWranglerEntry(cwd);
+    if (explicitConfigFullPath !== undefined) {
+        if (existsSync(explicitConfigFullPath)) {
+            // ok
+        }
+        else {
+            throw ErrorFactory.createCliError(`Error: Wrangler config not found: ${normalizedConfig}`);
+        }
+    }
     if (configPath === undefined && entry === undefined) {
         throw ErrorFactory.createCliError("Error: wrangler config not found (wrangler.toml/json). Run 'wrangler init' first.");
     }
     const wranglerArgs = ['dev'];
+    if (normalizedConfig !== '') {
+        wranglerArgs.push('--config', normalizedConfig);
+    }
     if (configPath === undefined && entry !== undefined) {
         wranglerArgs.push(entry);
     }
@@ -407,9 +434,18 @@ const executeStart = async (options, cmd) => {
         await executeSplitStart(cmd, cwd, options);
         return;
     }
-    EnvFileLoader.applyCliOverrides({ nodeEnv: mode, port, runtime: effectiveRuntime });
+    const cacheEnabled = resolveCacheEnabledPreference(options);
+    EnvFileLoader.applyCliOverrides({
+        nodeEnv: mode,
+        port,
+        runtime: effectiveRuntime,
+        ...(typeof cacheEnabled === 'boolean' ? { cacheEnabled } : {}),
+    });
     if (variant === 'wrangler') {
-        await executeWranglerStart(cmd, cwd, port, runtime, envName === '' ? undefined : envName);
+        const wranglerConfig = typeof options.wranglerConfig === 'string' && options.wranglerConfig.trim() !== ''
+            ? options.wranglerConfig.trim()
+            : undefined;
+        await executeWranglerStart(cmd, cwd, port, runtime, envName === '' ? undefined : envName, wranglerConfig);
         return;
     }
     if (envName !== '') {
@@ -435,10 +471,13 @@ export const StartCommand = Object.freeze({
                 .option('--wg', 'Alias for --wrangler')
                 .option('--deno', 'Start a local server using the Deno runtime adapter')
                 .option('--lambda', 'Start a local server using the AWS Lambda runtime adapter')
+                .option('--cache', 'Enable cache functionality')
+                .option('--no-cache', 'Disable cache functionality')
                 .option('--watch', 'Force watch mode (Node only)')
                 .option('--no-watch', 'Disable watch mode (Node only)')
                 .option('--mode <development|production|testing>', 'Override app mode')
                 .option('--env <name>', 'Wrangler environment name (Wrangler mode only)')
+                .option('--wrangler-config <path>', 'Wrangler config path (Wrangler mode only)')
                 .option('--runtime <nodejs|cloudflare|lambda|deno|auto>', 'Set RUNTIME for spawned Node')
                 .option('-p, --port <number>', 'Override server port');
         };

package/src/cli/scaffolding/ProjectScaffolder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AA+eD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA4ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}
+{"version":3,"file":"ProjectScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ProjectScaffolder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtD,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,eAAe,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IACpE,cAAc,IAAI,MAAM,CAAC;IACzB,sBAAsB,IAAI,OAAO,CAAC;IAClC,iBAAiB,IAAI,MAAM,CAAC;IAC5B,WAAW,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CAAC;IACtD,gBAAgB,IAAI,OAAO,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3E;AA8eD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAsBrE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG;IAChE,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAsBA;AA4ID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,GAAE,MAAsB,GAAG,kBAAkB,CAsB/F;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/cli/scaffolding/ProjectScaffolder.js

@@ -125,41 +125,56 @@ const toSafeDbBasename = (raw) => {
     }
     return out === '' ? 'zintrust' : out;
 };
-const buildDatabaseEnvLinesWithName = (database, name) => {
-    if (database === 'postgresql' || database === 'postgres') {
-        return [
-            'DB_HOST=localhost',
-            'DB_PORT=5432',
-            'DB_DATABASE=zintrust',
-            'DB_USERNAME=postgres',
-            'DB_PASSWORD=',
-        ];
+const readEnvScaffoldTemplate = () => {
+    const templateUrl = new URL('./templates/env.scaffold.dotenv.tpl', import.meta.url);
+    return fs.readFileSync(templateUrl, 'utf8');
+};
+const renderEnvScaffold = (template, vars) => {
+    let out = template;
+    for (const [key, value] of Object.entries(vars)) {
+        out = out.replaceAll(`{{${key}}}`, value);
     }
-    if (database === 'mysql') {
-        return [
-            'DB_HOST=localhost',
-            'DB_PORT=3306',
-            'DB_DATABASE=zintrust',
-            'DB_USERNAME=root',
-            'DB_PASSWORD=',
-        ];
+    // Normalize: if a placeholder resolves to empty, prevent excessive blank blocks.
+    out = out.replaceAll('\n\n\n', '\n\n');
+    return out;
+};
+const buildDbOverrides = (dbConnection) => {
+    const normalized = dbConnection.trim().toLowerCase();
+    if (normalized === 'mysql') {
+        return {
+            dbLines: [
+                'DB_HOST=localhost',
+                'DB_PORT=3306',
+                'DB_DATABASE=zintrust',
+                'DB_USERNAME=root',
+                'DB_PASSWORD=',
+            ],
+        };
     }
-    if (database === 'sqlite') {
-        // Provide both DB_DATABASE (used by the framework) and DB_PATH (common alias)
-        const base = toSafeDbBasename(name);
-        return [`DB_DATABASE=.zintrust/dbs/${base}.sqlite`, `DB_PATH=.zintrust/dbs/${base}.sqlite`];
+    if (normalized === 'postgres' || normalized === 'postgresql') {
+        return {
+            dbLines: [
+                'DB_HOST=localhost',
+                'DB_PORT=5432',
+                'DB_DATABASE=zintrust',
+                'DB_USERNAME=postgres',
+                'DB_PASSWORD=',
+            ],
+        };
     }
-    if (database === 'd1-remote' || database === 'd1-proxy') {
-        return [
-            '# Cloudflare D1 Remote Proxy (HTTPS)',
-            'D1_REMOTE_URL=',
-            'D1_REMOTE_KEY_ID=',
-            'D1_REMOTE_SECRET=',
-            'D1_REMOTE_MODE=registry',
-            'ZT_PROXY_TIMEOUT_MS=15000',
-        ];
+    if (normalized === 'sqlserver' || normalized === 'mssql') {
+        return {
+            dbLines: [
+                'DB_HOST_MSSQL=localhost',
+                'DB_PORT_MSSQL=1433',
+                'DB_DATABASE_MSSQL=zintrust',
+                'DB_USERNAME_MSSQL=sa',
+                'DB_PASSWORD_MSSQL=',
+            ],
+        };
     }
-    return [];
+    // sqlite/d1/d1-remote/etc: no overrides here (DB_PATH is handled via SQLITE_DB_PATH placeholder)
+    return { dbLines: [] };
 };
 const createEnvFile = (projectPath, variables) => {
     try {
@@ -174,56 +189,33 @@ const createEnvFile = (projectPath, variables) => {
                 HOST: 'localhost',
                 PORT: String(Number(variables['port'] ?? 7777)),
                 LOG_LEVEL: 'debug',
-                CSRF_SKIP_PATHS: '/api/*,/queue-monitor/*',
+                CSRF_SKIP_PATHS: '/api/*,/queue-monitor/*,/api/_sys/queue/*,/api/_sys/schedule/*',
             });
             return true;
         }
         const name = typeof variables['projectName'] === 'string' ? variables['projectName'] : 'zintrust-app';
         const port = Number(variables['port'] ?? 7777);
         const database = typeof variables['database'] === 'string' ? variables['database'] : 'sqlite';
+        const baseUrl = `http://localhost:${port}`;
+        const dbConnection = database.trim().toLowerCase();
+        const sqliteDbPath = `.zintrust/dbs/${toSafeDbBasename(name)}.sqlite`;
         // Generate a secure APP_KEY (32 bytes = 256-bit, base64 encoded)
         const appKeyBytes = randomBytes(32);
-        const appKey = appKeyBytes.toString('base64');
-        const baseLines = [
-            'NODE_ENV=development',
-            'STARTUP_REQUIRE_ENV=true',
-            `APP_NAME=${name}`,
-            'HOST=localhost',
-            `PORT=${port}`,
-            'APP_DEBUG=true',
-            // Auto-generated secure key for storage signing and encryption
-            `APP_KEY=${appKey}`,
-            `DB_CONNECTION=${database}`,
-        ];
-        const dbLines = buildDatabaseEnvLinesWithName(database, name);
-        const placeholderLines = [
-            '',
-            '# Logging',
-            'LOG_LEVEL=debug',
-            'LOG_CHANNEL=file',
-            'LOG_FORMAT=text',
-            '',
-            '# Auth / Security',
-            'JWT_SECRET=',
-            'JWT_EXPIRES_IN=1h',
-            'CSRF_SECRET=',
-            'CSRF_SKIP_PATHS=/api/*,/queue-monitor/*',
-            'ENCRYPTION_CIPHER=aes-256-cbc',
-            'APP_PREVIOUS_KEYS=',
-            '',
-            '# Cache / Queue',
-            'CACHE_DRIVER=memory',
-            'CACHE_TTL=300',
-            'QUEUE_DRIVER=sync',
-            '',
-            '# Microservices',
-            'SERVICE_DISCOVERY_ENABLED=false',
-            'SERVICE_DISCOVERY_TYPE=filesystem',
-            'SERVICE_NAME=',
-            'SERVICE_VERSION=1.0.0',
-        ];
-        const lines = [...baseLines, ...dbLines, ...placeholderLines];
-        fs.writeFileSync(fullPath, lines.join('\n') + '\n');
+        // Keep consistent with `zin key:generate` output.
+        const appKey = `base64:${appKeyBytes.toString('base64')}`;
+        const { dbLines } = buildDbOverrides(dbConnection);
+        const dbLinesBlock = dbLines.join('\n');
+        const template = readEnvScaffoldTemplate();
+        const content = renderEnvScaffold(template, {
+            APP_NAME: name,
+            PORT: String(port),
+            BASE_URL: baseUrl,
+            APP_KEY: appKey,
+            DB_CONNECTION: dbConnection,
+            SQLITE_DB_PATH: sqliteDbPath,
+            DB_LINES: dbLinesBlock,
+        });
+        fs.writeFileSync(fullPath, content.endsWith('\n') ? content : content + '\n');
         return true;
     }
     catch {

package/src/cli/utils/DistPackager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DistPackager.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/DistPackager.ts"],"names":[],"mappings":"AAoIA,eAAO,MAAM,YAAY;IACvB;;;OAGG;sBACe,MAAM,aAAY,MAAM,GAAmB,IAAI;EAgBjE,CAAC"}
+{"version":3,"file":"DistPackager.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/DistPackager.ts"],"names":[],"mappings":"AAsLA,eAAO,MAAM,YAAY;IACvB;;;OAGG;sBACe,MAAM,aAAY,MAAM,GAAmB,IAAI;EAgBjE,CAAC"}

package/src/cli/utils/DistPackager.js

@@ -49,6 +49,31 @@ const buildDistPackageJson = (rootPkg) => {
                 types: './start.d.ts',
                 default: './start.js',
             },
+            './cli': {
+                types: './src/cli.d.ts',
+                default: './src/cli.js',
+            },
+            './proxy': {
+                types: './src/proxy.d.ts',
+                default: './src/proxy.js',
+            },
+            './collections': {
+                types: './src/collections/index.d.ts',
+                default: './src/collections/index.js',
+            },
+            './helper': {
+                types: './src/helper/index.d.ts',
+                default: './src/helper/index.js',
+            },
+            './node': {
+                types: './src/node.d.ts',
+                default: './src/node.js',
+            },
+            './routes/*': {
+                types: './routes/*.d.ts',
+                default: './routes/*.js',
+            },
+            './package.json': './package.json',
         },
         dependencies: coerceDependencies(rootPkg.dependencies),
     };

package/src/cli/utils/EnvFileLoader.d.ts

@@ -11,6 +11,7 @@ type CliOverrides = {
     nodeEnv?: node_env;
     port?: number;
     runtime?: string;
+    cacheEnabled?: boolean;
 };
 export declare const EnvFileLoader: Readonly<{
     load: (options?: LoadOptions) => LoadState;

package/src/cli/utils/EnvFileLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvFileLoader.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/EnvFileLoader.ts"],"names":[],"mappings":"AAQA,KAAK,QAAQ,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;AAwHzD,KAAK,WAAW,GAAG;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AA2FF,eAAO,MAAM,aAAa;qBAlEH,WAAW,KAAQ,SAAS;wBAmC1B,SAAS;mCAEI,YAAY,KAAG,IAAI;oBA2BpC,SAAS;EAO5B,CAAC"}
+{"version":3,"file":"EnvFileLoader.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/EnvFileLoader.ts"],"names":[],"mappings":"AAQA,KAAK,QAAQ,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,CAAC;AAmIzD,KAAK,WAAW,GAAG;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,KAAK,SAAS,GAAG;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AA+FF,eAAO,MAAM,aAAa;qBAtEH,WAAW,KAAQ,SAAS;wBAmC1B,SAAS;mCAEI,YAAY,KAAG,IAAI;oBA+BpC,SAAS;EAO5B,CAAC"}

package/src/cli/utils/EnvFileLoader.js

@@ -75,6 +75,13 @@ const parseEnvFile = (raw) => {
         const rhs = withoutExport.slice(eq + 1);
         const withoutComment = stripInlineComment(rhs);
         const value = unquote(withoutComment);
+        // DX: treat empty assignments as "no-op" if the key already had a non-empty value earlier
+        // in the same file. This prevents accidental overrides like:
+        //   KV_NAMESPACE_ID=abc
+        //   ...
+        //   KV_NAMESPACE_ID=
+        if (value.trim() === '' && (result[key]?.trim() ?? '') !== '')
+            continue;
         result[key] = value;
     }
     return result;
@@ -83,6 +90,10 @@ const applyToProcessEnv = (values, overrideExisting) => {
     for (const [key, value] of Object.entries(values)) {
         if (!overrideExisting && safeEnvGet(key, '') !== '')
             continue;
+        // DX: don't wipe an already-populated env var with an empty value from an env file.
+        // This avoids surprising behavior when env templates include duplicate keys with blanks.
+        if (value.trim() === '' && safeEnvGet(key, '').trim() !== '')
+            continue;
         safeEnvSet(key, value);
     }
     // Compatibility helpers
@@ -169,6 +180,9 @@ const applyCliOverrides = (overrides) => {
         safeEnvSet('PORT', String(overrides.port));
         safeEnvSet('APP_PORT', String(overrides.port));
     }
+    if (typeof overrides.cacheEnabled === 'boolean') {
+        safeEnvSet('CACHE_ENABLED', String(overrides.cacheEnabled));
+    }
     // Keep PORT/APP_PORT in sync if only one exists.
     if (safeEnvGet('PORT', '') === '' && safeEnvGet('APP_PORT', '') !== '') {
         safeEnvSet('PORT', safeEnvGet('APP_PORT', ''));