@zintrust/core 0.1.40 → 0.1.42

package/src/cli/commands/MigrateCommand.js

@@ -8,6 +8,7 @@ import { WranglerConfig } from '../d1/WranglerConfig.js';
 import { WranglerD1 } from '../d1/WranglerD1.js';
 import { PromptHelper } from '../PromptHelper.js';
 import { confirmProductionRun, mapConnectionToOrmConfig, parseRollbackSteps, } from '../utils/DatabaseCliUtils.js';
+import { EnvFileLoader } from '../utils/EnvFileLoader.js';
 import { readEnvString } from '../../common/ExternalServiceUtils.js';
 import { databaseConfig } from '../../config/database.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
@@ -52,7 +53,7 @@ const getServiceArgs = (options) => {
     return { service: serviceArg, includeGlobal };
 };
 const isDestructiveAction = (options) => options['fresh'] === true || options['reset'] === true || options['rollback'] === true;
-const isD1Driver = (driver) => driver === 'd1' || driver === 'd1-remote';
+const isWranglerD1Driver = (driver) => driver === 'd1';
 const describeTargetDatabase = (conn) => {
     switch (conn.driver) {
         case 'sqlite':
@@ -189,33 +190,47 @@ const runD1Actions = async (params) => {
         cmd.info(output);
     cmd.success('D1 migrations completed successfully');
 };
-const processConnection = async (conn, options, cmd, interactive) => {
-    // Avoid confusion: `--database` is a D1-only option (Wrangler binding name), not DB_DATABASE.
-    if (isD1Driver(conn.driver)) {
+const logOptionsForConn = (cmd, conn, options) => {
+    if (isWranglerD1Driver(conn.driver)) {
         cmd.debug(`Migrate command executed with options: ${JSON.stringify(options)}`);
+        return;
     }
-    else {
-        const optionsForLog = { ...options };
-        delete optionsForLog['database'];
-        delete optionsForLog['local'];
-        delete optionsForLog['remote'];
-        cmd.debug(`Migrate command executed with options: ${JSON.stringify(optionsForLog)}`);
+    const optionsForLog = { ...options };
+    delete optionsForLog['database'];
+    delete optionsForLog['local'];
+    delete optionsForLog['remote'];
+    cmd.debug(`Migrate command executed with options: ${JSON.stringify(optionsForLog)}`);
+};
+const warnIfAdapterMissing = (cmd, conn) => {
+    if (conn.driver === 'mysql' && DatabaseAdapterRegistry.get('mysql') === undefined) {
+        cmd.warn('MySQL adapter is not installed/registered; migrations may not hit a real MySQL DB.');
+        cmd.warn('Install via `zin plugin install adapter:mysql` (or `zin add db:mysql`).');
+        cmd.debug('[debug] Expected a side-effect import in src/zintrust.plugins.ts like: import "@zintrust/db-mysql/register";');
     }
-    const { globalDir, extension, separateTracking } = getMigrationDirs();
-    const { service, includeGlobal } = getServiceArgs(options);
-    if (isD1Driver(conn.driver)) {
-        await runD1Actions({
-            options,
-            cmd,
-            projectRoot: process.cwd(),
-            globalDir,
-            extension,
-            separateTracking,
-            service,
-            includeGlobal,
-        });
-        return;
+    if (conn.driver === 'postgresql' && DatabaseAdapterRegistry.get('postgresql') === undefined) {
+        cmd.warn('PostgreSQL adapter is not installed/registered; migrations may not hit a real PostgreSQL DB.');
+        cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
     }
+};
+const withD1RemoteSqlMode = async (fn) => {
+    if (typeof process === 'undefined' || process.env === undefined)
+        return fn();
+    const prev = process.env['D1_REMOTE_MODE'];
+    process.env['D1_REMOTE_MODE'] = 'sql';
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined) {
+            delete process.env['D1_REMOTE_MODE'];
+        }
+        else {
+            process.env['D1_REMOTE_MODE'] = prev;
+        }
+    }
+};
+const runOrmMigrationsForConn = async (params) => {
+    const { conn, options, cmd, interactive, globalDir, extension, separateTracking, service, includeGlobal, } = params;
     const ormConfig = mapConnectionToOrmConfig(conn);
     const destructive = isDestructiveAction(options);
     const force = options['force'] === true;
@@ -231,18 +246,7 @@ const processConnection = async (conn, options, cmd, interactive) => {
     cmd.info(`[i] Target database: ${describeTargetDatabase(conn)}`);
     cmd.info('[i] Migration tracking table: migrations');
     cmd.debug(`[debug] Registered database adapters: ${DatabaseAdapterRegistry.list().join(', ')}`);
-    // Warn only when the adapter truly isn't registered.
-    // Adapters are registered via side-effect imports in src/zintrust.plugins.ts
-    // (generated by `zin plugin install`) and are loaded at CLI startup.
-    if (conn.driver === 'mysql' && DatabaseAdapterRegistry.get('mysql') === undefined) {
-        cmd.warn('MySQL adapter is not installed/registered; migrations may not hit a real MySQL DB.');
-        cmd.warn('Install via `zin plugin install adapter:mysql` (or `zin add db:mysql`).');
-        cmd.debug('[debug] Expected a side-effect import in src/zintrust.plugins.ts like: import "@zintrust/db-mysql/register";');
-    }
-    if (conn.driver === 'postgresql' && DatabaseAdapterRegistry.get('postgresql') === undefined) {
-        cmd.warn('PostgreSQL adapter is not installed/registered; migrations may not hit a real PostgreSQL DB.');
-        cmd.warn('Install via `zin plugin install adapter:postgres` (or `zin add db:postgres`).');
-    }
+    warnIfAdapterMissing(cmd, conn);
     const db = Database.create(ormConfig);
     await db.connect();
     try {
@@ -261,7 +265,45 @@ const processConnection = async (conn, options, cmd, interactive) => {
         await db.disconnect();
     }
 };
+const processConnection = async (conn, options, cmd, interactive) => {
+    // Avoid confusion: `--database` is a D1-only option (Wrangler binding name), not DB_DATABASE.
+    logOptionsForConn(cmd, conn, options);
+    const { globalDir, extension, separateTracking } = getMigrationDirs();
+    const { service, includeGlobal } = getServiceArgs(options);
+    if (isWranglerD1Driver(conn.driver)) {
+        await runD1Actions({
+            options,
+            cmd,
+            projectRoot: process.cwd(),
+            globalDir,
+            extension,
+            separateTracking,
+            service,
+            includeGlobal,
+        });
+        return;
+    }
+    const run = async () => runOrmMigrationsForConn({
+        conn,
+        options,
+        cmd,
+        interactive,
+        globalDir,
+        extension,
+        separateTracking,
+        service,
+        includeGlobal,
+    });
+    if (conn.driver === 'd1-remote') {
+        cmd.info('[i] d1-remote migrations: using SQL mode automatically for this CLI run');
+        await withD1RemoteSqlMode(run);
+        return;
+    }
+    await run();
+};
 const executeMigrate = async (options, cmd) => {
+    // Ensure .env overlays are loaded for CLI runs (needed for d1-remote signing fallbacks).
+    EnvFileLoader.ensureLoaded();
     const interactive = getInteractive(options);
     const targets = [];
     if (options['all'] === true) {

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

@@ -1 +1 @@
-{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAqKrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}
+{"version":3,"file":"MigrateWorkerCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MigrateWorkerCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiNrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAUtB,CAAC"}

package/src/cli/commands/MigrateWorkerCommand.js

@@ -9,6 +9,19 @@ import { Migrator } from '../../migrations/Migrator.js';
 import * as path from '../../node-singletons/path.js';
 import { Database } from '../../orm/Database.js';
 import { DatabaseAdapterRegistry } from '../../orm/DatabaseAdapterRegistry.js';
+const isBuiltInDriver = (driver) => driver === 'sqlite' ||
+    driver === 'mysql' ||
+    driver === 'postgresql' ||
+    driver === 'sqlserver' ||
+    driver === 'd1' ||
+    driver === 'd1-remote';
+const getWorkerPersistenceConnectionName = () => {
+    if (typeof process === 'undefined')
+        return 'default';
+    const raw = process.env?.['WORKER_PERSISTENCE_DB_CONNECTION'];
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    return value.length > 0 ? value : 'default';
+};
 const addOptions = (command) => {
     command
         .option('--status', 'Display migration status (applied, pending, failed)')
@@ -80,10 +93,16 @@ const runForConnection = async (conn, options, cmd, interactive) => {
     });
     if (!proceed)
         return;
-    if (!DatabaseAdapterRegistry.has(conn.driver)) {
+    if (!isBuiltInDriver(conn.driver) && !DatabaseAdapterRegistry.has(conn.driver)) {
         cmd.warn(`Missing adapter for driver: ${conn.driver}`);
         cmd.warn(`Install via 'zin plugin install adapter:${conn.driver}' (or 'zin add db:${conn.driver}').`);
     }
+    const previousD1RemoteMode = typeof process === 'undefined' ? undefined : process.env['D1_REMOTE_MODE'];
+    if (conn.driver === 'd1-remote' && typeof process !== 'undefined') {
+        // Important: set BEFORE Database.create() so D1RemoteAdapter is constructed in SQL mode.
+        // Registry mode uses /zin/d1/statement, which is not appropriate for migrations.
+        process.env['D1_REMOTE_MODE'] = 'sql';
+    }
     const ormConfig = mapConnectionToOrmConfig(conn);
     const db = Database.create(ormConfig);
     await db.connect();
@@ -98,6 +117,14 @@ const runForConnection = async (conn, options, cmd, interactive) => {
         await runActions(migrator, options, cmd, conn.driver);
     }
     finally {
+        if (conn.driver === 'd1-remote' && typeof process !== 'undefined') {
+            if (previousD1RemoteMode === undefined) {
+                delete process.env['D1_REMOTE_MODE'];
+            }
+            else {
+                process.env['D1_REMOTE_MODE'] = previousD1RemoteMode;
+            }
+        }
         await db.disconnect();
     }
 };
@@ -110,7 +137,14 @@ const executeMigrateWorker = async (options, cmd) => {
         }
     }
     else {
-        targets.push({ name: 'default', config: databaseConfig.getConnection() });
+        const selected = getWorkerPersistenceConnectionName();
+        const hasSelected = selected.length > 0;
+        const connections = databaseConfig.connections;
+        const configured = hasSelected ? connections[selected] : undefined;
+        targets.push({
+            name: hasSelected ? selected : 'default',
+            config: configured ?? databaseConfig.getConnection(),
+        });
     }
     let sequence = Promise.resolve();
     for (const { name, config } of targets) {

package/src/cli/commands/MongoDBProxyCommand.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+export declare const MongoDBProxyCommand: Readonly<{
+    create(): Command;
+}>;
+//# sourceMappingURL=MongoDBProxyCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MongoDBProxyCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MongoDBProxyCommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4DpC,eAAO,MAAM,mBAAmB;cACpB,OAAO;EAoEjB,CAAC"}

package/src/cli/commands/MongoDBProxyCommand.js

@@ -0,0 +1,98 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { Command } from 'commander';
+const startWatchMode = async (options) => {
+    Logger.info('Starting MongoDB proxy in watch mode...');
+    const { watch } = await import('node:fs');
+    const { spawn } = await import('node:child_process');
+    let child = null;
+    const optionFlagMap = {
+        host: '--host',
+        port: '--port',
+        mongoUri: '--mongo-uri',
+        mongoDb: '--mongo-db',
+        keyId: '--key-id',
+        secret: '--secret',
+        requireSigning: '--require-signing',
+        signingWindowMs: '--signing-window-ms',
+    };
+    const startProxy = () => {
+        if (child) {
+            child.kill();
+        }
+        const args = ['run', 'cli', 'proxy:mongodb'];
+        Object.entries(options).forEach(([key, value]) => {
+            if (key !== 'watch') {
+                const flag = optionFlagMap[key] ?? `--${key}`;
+                if (typeof value === 'boolean') {
+                    if (value) {
+                        args.push(flag);
+                    }
+                    return;
+                }
+                if (value !== undefined && value !== null) {
+                    args.push(flag, String(value));
+                }
+            }
+        });
+        child = spawn('npm', args, { stdio: 'inherit' });
+    };
+    const watcher = watch('./src', { recursive: true }, (_eventType, filename) => {
+        if (filename !== null && (filename.endsWith('.ts') || filename.endsWith('.js'))) {
+            Logger.info(`File changed: ${String(filename)}, restarting proxy...`);
+            startProxy();
+        }
+    });
+    startProxy();
+    process.on('SIGINT', () => {
+        watcher.close();
+        if (child)
+            child.kill();
+        process.exit(0);
+    });
+};
+export const MongoDBProxyCommand = Object.freeze({
+    create() {
+        const cmd = new Command('proxy:mongodb');
+        cmd.description('Start MongoDB HTTP proxy server');
+        const configureOptions = () => {
+            cmd.option('--host <host>', 'Proxy host', Env.get('MONGODB_PROXY_HOST', '127.0.0.1'));
+            cmd.option('--port <port>', 'Proxy port', String(Env.getInt('MONGODB_PROXY_PORT', 8792)));
+            cmd.option('--mongo-uri <uri>', 'MongoDB connection URI', Env.get('MONGO_URI', ''));
+            cmd.option('--mongo-db <database>', 'MongoDB database name', Env.get('MONGO_DB', ''));
+            cmd.option('--key-id <keyId>', 'Signing key ID', Env.get('MONGODB_PROXY_KEY_ID', 'default'));
+            cmd.option('--secret <secret>', 'Signing secret', Env.get('MONGODB_PROXY_SECRET', ''));
+            cmd.option('--require-signing', 'Require request signing', Env.MONGODB_PROXY_REQUIRE_SIGNING);
+            cmd.option('--signing-window-ms <ms>', 'Signing window in milliseconds', String(Env.getInt('MONGODB_PROXY_SIGNING_WINDOW_MS', 60000)));
+            cmd.option('--watch', 'Watch mode: restart on file changes');
+        };
+        const buildServerConfig = (options) => ({
+            host: String(options['host']),
+            port: Number(options['port']),
+            mongoUri: String(options['mongoUri']),
+            mongoDb: String(options['mongoDb']),
+            keyId: String(options['keyId']),
+            secret: String(options['secret']),
+            requireSigning: Boolean(options['requireSigning']),
+            signingWindowMs: Number(options['signingWindowMs']),
+        });
+        const startNormalMode = async (options) => {
+            const { MongoDBProxyServer } = await import('../../proxy/mongodb/MongoDBProxyServer.js');
+            if (options['mongoUri'] === undefined || options['mongoDb'] === undefined) {
+                throw ErrorFactory.createValidationError('MongoDB URI and database name are required. Set MONGO_URI and MONGO_DB or pass --mongo-uri and --mongo-db');
+            }
+            await MongoDBProxyServer.start(buildServerConfig(options));
+        };
+        const execute = async (options) => {
+            if (options['watch'] === true) {
+                await startWatchMode(options);
+                return;
+            }
+            await startNormalMode(options);
+        };
+        configureOptions();
+        cmd.action(execute);
+        return cmd;
+    },
+});

package/src/cli/commands/MySqlProxyCommand.d.ts

@@ -0,0 +1,6 @@
+import type { IBaseCommand } from '../BaseCommand';
+export declare const MySqlProxyCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default MySqlProxyCommand;
+//# sourceMappingURL=MySqlProxyCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MySqlProxyCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/MySqlProxyCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrE,eAAO,MAAM,iBAAiB;cAClB,YAAY;EAatB,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/cli/commands/MySqlProxyCommand.js

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { addSqlProxyOptions, runSqlProxyCommand, } from '../commands/SqlProxyCommandUtils.js';
+import { Env } from '../../config/env.js';
+import { MySqlProxyServer } from '../../proxy/mysql/MySqlProxyServer.js';
+const addOptions = (command) => {
+    addSqlProxyOptions(command, {
+        hostDefault: Env.MYSQL_PROXY_HOST,
+        portDefault: Env.MYSQL_PROXY_PORT,
+        maxBodyBytesDefault: Env.MYSQL_PROXY_MAX_BODY_BYTES,
+        dbVendorLabel: 'MySQL',
+        requireSigningDefault: Env.MYSQL_PROXY_REQUIRE_SIGNING,
+        keyIdDefault: Env.MYSQL_PROXY_KEY_ID,
+        secretDefault: Env.MYSQL_PROXY_SECRET,
+        signingWindowMsDefault: Env.MYSQL_PROXY_SIGNING_WINDOW_MS,
+    });
+};
+export const MySqlProxyCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'proxy:mysql',
+            aliases: ['mysql:proxy', 'mysql-proxy', 'proxy:my'],
+            description: 'Start the MySQL HTTP proxy for Cloudflare Workers',
+            addOptions,
+            execute: async (options) => {
+                await runSqlProxyCommand(options, async (input) => {
+                    await MySqlProxyServer.start(input);
+                });
+            },
+        });
+    },
+});
+export default MySqlProxyCommand;

package/src/cli/commands/PostgresProxyCommand.d.ts

@@ -0,0 +1,6 @@
+import type { IBaseCommand } from '../BaseCommand';
+export declare const PostgresProxyCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default PostgresProxyCommand;
+//# sourceMappingURL=PostgresProxyCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresProxyCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/PostgresProxyCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAatB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/src/cli/commands/PostgresProxyCommand.js

@@ -0,0 +1,32 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { addSqlProxyOptions, runSqlProxyCommand, } from '../commands/SqlProxyCommandUtils.js';
+import { Env } from '../../config/env.js';
+import { PostgresProxyServer } from '../../proxy/postgres/PostgresProxyServer.js';
+const addOptions = (command) => {
+    addSqlProxyOptions(command, {
+        hostDefault: Env.POSTGRES_PROXY_HOST,
+        portDefault: Env.POSTGRES_PROXY_PORT,
+        maxBodyBytesDefault: Env.POSTGRES_PROXY_MAX_BODY_BYTES,
+        dbVendorLabel: 'PostgreSQL',
+        requireSigningDefault: Env.POSTGRES_PROXY_REQUIRE_SIGNING,
+        keyIdDefault: Env.POSTGRES_PROXY_KEY_ID,
+        secretDefault: Env.POSTGRES_PROXY_SECRET,
+        signingWindowMsDefault: Env.POSTGRES_PROXY_SIGNING_WINDOW_MS,
+    });
+};
+export const PostgresProxyCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'proxy:postgres',
+            aliases: ['postgres:proxy', 'postgres-proxy', 'proxy:pg', 'pg:proxy', 'pg-proxy'],
+            description: 'Start the PostgreSQL HTTP proxy for Cloudflare Workers',
+            addOptions,
+            execute: async (options) => {
+                await runSqlProxyCommand(options, async (input) => {
+                    await PostgresProxyServer.start(input);
+                });
+            },
+        });
+    },
+});
+export default PostgresProxyCommand;

package/src/cli/commands/ProxyCommand.d.ts

@@ -0,0 +1,12 @@
+import type { IBaseCommand } from '../BaseCommand';
+import '../../proxy/d1/register';
+import '../../proxy/kv/register';
+import '../../proxy/mysql/register';
+import '../../proxy/postgres/register';
+import '../../proxy/redis/register';
+import '../../proxy/smtp/register';
+export declare const ProxyCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default ProxyCommand;
+//# sourceMappingURL=ProxyCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ProxyCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAMrE,OAAO,oBAAoB,CAAC;AAC5B,OAAO,oBAAoB,CAAC;AAC5B,OAAO,uBAAuB,CAAC;AAC/B,OAAO,0BAA0B,CAAC;AAClC,OAAO,uBAAuB,CAAC;AAC/B,OAAO,sBAAsB,CAAC;AAyD9B,eAAO,MAAM,YAAY;cACb,YAAY;EAyBtB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/cli/commands/ProxyCommand.js

@@ -0,0 +1,80 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { SpawnUtil } from '../utils/spawn.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import * as path from '../../node-singletons/path.js';
+import { ProxyRegistry } from '../../proxy/ProxyRegistry.js';
+import '../../proxy/d1/register.js';
+import '../../proxy/kv/register.js';
+import '../../proxy/mysql/register.js';
+import '../../proxy/postgres/register.js';
+import '../../proxy/redis/register.js';
+import '../../proxy/smtp/register.js';
+const PROXY_TARGET_MAP = Object.freeze({
+    mysql: 'proxy:mysql',
+    my: 'proxy:mysql',
+    postgres: 'proxy:postgres',
+    postgresql: 'proxy:postgres',
+    pg: 'proxy:postgres',
+    redis: 'proxy:redis',
+    smtp: 'proxy:smtp',
+    mail: 'proxy:smtp',
+    mongodb: 'proxy:mongodb',
+    mongo: 'proxy:mongodb',
+    sqlserver: 'proxy:sqlserver',
+    mssql: 'proxy:sqlserver',
+});
+const addOptions = (command) => {
+    command.argument('[target]', 'Proxy target (e.g. postgres, mysql, redis, smtp)');
+};
+const parseForwardArgs = () => {
+    const argv = process.argv.slice(2);
+    const proxyIndex = argv.indexOf('proxy');
+    if (proxyIndex < 0) {
+        return { target: null, extra: [] };
+    }
+    const target = argv[proxyIndex + 1] ?? null;
+    const extra = argv.slice(proxyIndex + 2);
+    return { target, extra };
+};
+const dispatchProxyTarget = async (targetRaw) => {
+    const target = targetRaw.trim().toLowerCase();
+    const mapped = PROXY_TARGET_MAP[target];
+    if (!mapped) {
+        throw ErrorFactory.createCliError(`Unknown proxy target '${targetRaw}'. Use one of: ${Object.keys(PROXY_TARGET_MAP).join(', ')}`);
+    }
+    const { extra } = parseForwardArgs();
+    const exitCode = await SpawnUtil.spawnAndWait({
+        command: 'tsx',
+        args: [path.join('bin', 'zin.ts'), mapped, ...extra],
+        env: {
+            ...process.env,
+        },
+        forwardSignals: false,
+    });
+    process.exit(exitCode);
+};
+export const ProxyCommand = Object.freeze({
+    create() {
+        const cmd = BaseCommand.create({
+            name: 'proxy',
+            description: 'List available proxy servers',
+            addOptions,
+            execute: async (options) => {
+                const firstArg = Array.isArray(options.args) ? options.args[0] : undefined;
+                if (typeof firstArg === 'string' && firstArg.trim() !== '') {
+                    await dispatchProxyTarget(firstArg);
+                    return;
+                }
+                const list = ProxyRegistry.list();
+                if (list.length === 0) {
+                    throw ErrorFactory.createCliError('No proxies registered');
+                }
+                for (const proxy of list) {
+                    cmd.info(`${proxy.name}: ${proxy.description}`);
+                }
+            },
+        });
+        return cmd;
+    },
+});
+export default ProxyCommand;

package/src/cli/commands/ProxyCommandUtils.d.ts

@@ -0,0 +1,6 @@
+type NumberExpectation = 'positive' | 'non-negative';
+export declare const parseIntOption: (raw: string | undefined, name: string, expectation?: NumberExpectation) => number | undefined;
+export declare const trimOption: (value: string | undefined) => string | undefined;
+export declare const maybeRunProxyWatchMode: (watch: boolean | undefined) => Promise<void>;
+export {};
+//# sourceMappingURL=ProxyCommandUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyCommandUtils.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ProxyCommandUtils.ts"],"names":[],"mappings":"AAIA,KAAK,iBAAiB,GAAG,UAAU,GAAG,cAAc,CAAC;AAErD,eAAO,MAAM,cAAc,GACzB,KAAK,MAAM,GAAG,SAAS,EACvB,MAAM,MAAM,EACZ,cAAa,iBAA8B,KAC1C,MAAM,GAAG,SAeX,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAA0B,CAAC;AAU3F,eAAO,MAAM,sBAAsB,GAAU,OAAO,OAAO,GAAG,SAAS,KAAG,OAAO,CAAC,IAAI,CAerF,CAAC"}

package/src/cli/commands/ProxyCommandUtils.js

@@ -0,0 +1,38 @@
+import { SpawnUtil } from '../utils/spawn.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import * as path from '../../node-singletons/path.js';
+export const parseIntOption = (raw, name, expectation = 'positive') => {
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    const isValid = expectation === 'non-negative'
+        ? Number.isFinite(parsed) && parsed >= 0
+        : Number.isFinite(parsed) && parsed > 0;
+    if (!isValid) {
+        const expected = expectation === 'non-negative' ? 'a non-negative number' : 'a positive number';
+        throw ErrorFactory.createCliError(`Invalid --${name} '${raw}'. Expected ${expected}.`);
+    }
+    return parsed;
+};
+export const trimOption = (value) => value?.trim();
+const isWatchChild = () => process.env['ZINTRUST_PROXY_WATCH_CHILD'] === '1';
+const buildWatchArgs = () => {
+    const rawArgs = process.argv.slice(2);
+    const filtered = rawArgs.filter((arg) => arg !== '--watch');
+    return ['watch', path.join('bin', 'zin.ts'), ...filtered];
+};
+export const maybeRunProxyWatchMode = async (watch) => {
+    if (watch !== true || isWatchChild())
+        return;
+    const args = buildWatchArgs();
+    const exitCode = await SpawnUtil.spawnAndWait({
+        command: 'tsx',
+        args,
+        env: {
+            ...process.env,
+            ZINTRUST_PROXY_WATCH_CHILD: '1',
+        },
+        forwardSignals: false,
+    });
+    process.exit(exitCode);
+};

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

@@ -0,0 +1,6 @@
+import { type IBaseCommand } from '../BaseCommand';
+export declare const PutCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default PutCommand;
+//# sourceMappingURL=PutCommand.d.ts.map

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

@@ -0,0 +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"}