@zintrust/core 0.1.28 → 0.1.30

package/src/cli/commands/SimulateCommand.js

@@ -0,0 +1,79 @@
+/**
+ * Simulate Command
+ * Internal dev tool that generates a simulated ZinTrust app under ./simulate/
+ * IMPORTANT: this uses the same ProjectScaffolder as `zin new`.
+ * Usage: zin -sim my-blog
+ */
+import { ProjectScaffolder } from '../scaffolding/ProjectScaffolder.js';
+import { DistPackager } from '../utils/DistPackager.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import fs from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import chalk from 'chalk';
+import { Command } from 'commander';
+const rewriteSimulatedAppDependencyToDist = (appPath, distPath) => {
+    const packageJsonPath = path.join(appPath, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        throw ErrorFactory.createCliError(`Missing simulated app package.json at: ${packageJsonPath}`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const dependencies = { ...pkg.dependencies };
+    dependencies['@zintrust/core'] = `file:${distPath}`;
+    const nextPkg = {
+        ...pkg,
+        dependencies,
+    };
+    fs.writeFileSync(packageJsonPath, JSON.stringify(nextPkg, null, 2) + '\n');
+};
+/**
+ * SimulateCommand - Generate simulated apps for testing
+ */
+export const SimulateCommand = {
+    name: 'simulate',
+    description: '[INTERNAL] Generate simulated ZinTrust app for testing new developer experience',
+    getCommand() {
+        const command = new Command('simulate')
+            .alias('-sim')
+            .alias('--sim')
+            .description('[INTERNAL DEV] Create a simulated ZinTrust application in simulate/ folder')
+            .argument('<name>', 'Name of the simulated app')
+            .action(async (appName) => {
+            try {
+                const simulateBasePath = path.join(process.cwd(), 'simulate');
+                if (!appName || appName.trim() === '') {
+                    throw ErrorFactory.createValidationError('App name is required');
+                }
+                // Delegate validation + file generation to the same scaffolder used by `zin new`.
+                Logger.info(`Creating simulated app via ProjectScaffolder: ${chalk.cyan(appName)}`);
+                const result = await ProjectScaffolder.scaffold(simulateBasePath, {
+                    name: appName,
+                    template: 'basic',
+                    database: 'sqlite',
+                    author: 'Internal',
+                    description: `Simulated ZinTrust app - ${appName}`,
+                });
+                if (!result.success) {
+                    throw ErrorFactory.createCliError(result.message, result.error);
+                }
+                const appPath = path.join(simulateBasePath, appName);
+                // For simulate apps only: install the locally-built framework from dist/
+                // so the dev experience matches "fresh install" of the current build output.
+                const distPath = path.join(process.cwd(), 'dist');
+                DistPackager.prepare(distPath, process.cwd());
+                rewriteSimulatedAppDependencyToDist(appPath, distPath);
+                Logger.info('✅ Simulated app created successfully!');
+                Logger.info(`📁 Location: ${chalk.cyan(appPath)}`);
+                Logger.info(`\n${chalk.bold('Next steps:')}`);
+                Logger.info(`  cd ${path.relative(process.cwd(), appPath)}`);
+                Logger.info('  npm install');
+                Logger.info('  zin start');
+            }
+            catch (error) {
+                Logger.error('Failed to create simulated app', error);
+                process.exit(1);
+            }
+        });
+        return command;
+    },
+};

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

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

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

@@ -0,0 +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;AAqavF,eAAO,MAAM,YAAY;cACb,YAAY;EAyBtB,CAAC"}

package/src/cli/commands/StartCommand.js

@@ -0,0 +1,326 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { DENO_RUNNER_SOURCE, LAMBDA_RUNNER_SOURCE } from '../commands/runner/index.js';
+import { EnvFileLoader } from '../utils/EnvFileLoader.js';
+import { SpawnUtil } from '../utils/spawn.js';
+import { readEnvString } from '../../common/ExternalServiceUtils.js';
+import { resolveNpmPath } from '../../common/index.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+const isValidModeInput = (value) => value === 'development' ||
+    value === 'dev' ||
+    value === 'production' ||
+    value === 'pro' ||
+    value === 'prod' ||
+    value === 'testing';
+const normalizeMode = (value) => {
+    if (value === 'production' || value === 'pro' || value === 'prod')
+        return 'production';
+    if (value === 'testing')
+        return 'testing';
+    return 'development';
+};
+const resolveModeFromAppMode = () => {
+    const raw = readEnvString('APP_MODE').trim();
+    const normalized = raw.toLowerCase();
+    if (normalized === 'production' || normalized === 'pro' || normalized === 'prod') {
+        return 'production';
+    }
+    // Per spec: any other APP_MODE is treated as development.
+    return 'development';
+};
+const resolveMode = (options) => {
+    const raw = typeof options.mode === 'string' ? options.mode.trim() : '';
+    if (raw !== '') {
+        if (isValidModeInput(raw))
+            return normalizeMode(raw);
+        throw ErrorFactory.createCliError(`Error: Invalid --mode '${raw}'. Expected one of: development, production, testing.`);
+    }
+    return resolveModeFromAppMode();
+};
+const resolvePort = (options) => {
+    const cliPort = typeof options.port === 'string' ? options.port.trim() : '';
+    if (cliPort !== '') {
+        const parsed = Number.parseInt(cliPort, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0 || parsed >= 65536) {
+            throw ErrorFactory.createCliError(`Error: Invalid --port '${cliPort}'. Expected 1-65535.`);
+        }
+        return parsed;
+    }
+    const envPortRaw = process.env['APP_PORT'] ?? process.env['PORT'] ?? '';
+    if (envPortRaw === '')
+        return undefined;
+    const parsed = Number.parseInt(String(envPortRaw), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed >= 65536) {
+        throw ErrorFactory.createCliError(`Error: Invalid APP_PORT/PORT '${envPortRaw}'. Expected 1-65535.`);
+    }
+    return parsed;
+};
+const resolveRuntime = (options) => {
+    const raw = typeof options.runtime === 'string' ? options.runtime.trim() : '';
+    return raw === '' ? undefined : raw;
+};
+const resolveStartVariant = (options) => {
+    const wantWrangler = options.wrangler === true || options.wg === true;
+    const wantDeno = options.deno === true;
+    const wantLambda = options.lambda === true;
+    const enabled = [wantWrangler, wantDeno, wantLambda].filter(Boolean).length;
+    if (enabled > 1) {
+        throw ErrorFactory.createCliError('Error: Choose only one of --wrangler/--wg, --deno, or --lambda.');
+    }
+    if (wantWrangler)
+        return 'wrangler';
+    if (wantDeno)
+        return 'deno';
+    if (wantLambda)
+        return 'lambda';
+    return 'node';
+};
+const hasFlag = (flag) => process.argv.includes(flag);
+const resolveWatchPreference = (options, mode) => {
+    const hasWatch = hasFlag('--watch');
+    const hasNoWatch = hasFlag('--no-watch');
+    if (hasWatch && hasNoWatch) {
+        throw ErrorFactory.createCliError('Error: Cannot use both --watch and --no-watch.');
+    }
+    if (hasWatch)
+        return true;
+    if (hasNoWatch)
+        return false;
+    if (typeof options.watch === 'boolean')
+        return options.watch;
+    return mode === 'development';
+};
+const readPackageJson = (cwd) => {
+    const packagePath = path.join(cwd, 'package.json');
+    if (!existsSync(packagePath)) {
+        throw ErrorFactory.createCliError("Error: No ZinTrust app found. Run 'zin new <project>' or ensure package.json exists.");
+    }
+    try {
+        const raw = readFileSync(packagePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError('Failed to read package.json', error);
+    }
+};
+const isFrameworkRepo = (packageJson) => packageJson.name === '@zintrust/core';
+const hasDevScript = (packageJson) => {
+    const scripts = packageJson.scripts;
+    if (!scripts)
+        return false;
+    return typeof scripts['dev'] === 'string' && scripts['dev'] !== '';
+};
+const findWranglerConfig = (cwd) => {
+    const candidates = ['wrangler.toml', 'wrangler.json', 'wrangler.jsonc'];
+    for (const candidate of candidates) {
+        const full = path.join(cwd, candidate);
+        if (existsSync(full))
+            return full;
+    }
+    return undefined;
+};
+const resolveWranglerEntry = (cwd) => {
+    const indexEntry = path.join(cwd, 'src/index.ts');
+    if (existsSync(indexEntry))
+        return 'src/index.ts';
+    // Legacy fallback
+    const entry = path.join(cwd, 'src/functions/cloudflare.ts');
+    return existsSync(entry) ? 'src/functions/cloudflare.ts' : undefined;
+};
+const resolveBootstrapEntryTs = (cwd) => {
+    const boot = path.join(cwd, 'src/boot/bootstrap.ts');
+    if (existsSync(boot))
+        return 'src/boot/bootstrap.ts';
+    return undefined;
+};
+const resolveNodeDevCommand = (cwd, packageJson) => {
+    if (isFrameworkRepo(packageJson)) {
+        const bootstrap = resolveBootstrapEntryTs(cwd);
+        return { command: 'tsx', args: ['watch', bootstrap ?? 'src/index.ts'] };
+    }
+    const bootstrap = resolveBootstrapEntryTs(cwd);
+    if (bootstrap !== undefined) {
+        return { command: 'tsx', args: ['watch', bootstrap] };
+    }
+    if (existsSync(path.join(cwd, 'src/index.ts'))) {
+        return { command: 'tsx', args: ['watch', 'src/index.ts'] };
+    }
+    // Fallback: if the app provides a dev script, run it.
+    // IMPORTANT: avoid calling `npm run dev` when the dev script itself invokes `zin`/`zintrust`
+    // (e.g. "dev": "zin s"), which would cause infinite recursion.
+    const devScript = typeof packageJson.scripts?.['dev'] === 'string' ? String(packageJson.scripts['dev']) : '';
+    const devScriptCallsZin = /\bzin(?:trust)?\b/.test(devScript);
+    if (hasDevScript(packageJson) && !devScriptCallsZin) {
+        const npm = resolveNpmPath();
+        return { command: npm, args: ['run', 'dev'] };
+    }
+    throw ErrorFactory.createCliError("Error: No entry point found. Expected 'src/index.ts' or 'src/boot/bootstrap.ts'. Ensure your project is correctly scaffolded.");
+};
+const resolveNodeProdCommand = (cwd) => {
+    const compiledBoot = path.join(cwd, 'dist/src/boot/bootstrap.js');
+    let compiled;
+    if (existsSync(compiledBoot)) {
+        compiled = 'dist/src/boot/bootstrap.js';
+    }
+    if (compiled === undefined) {
+        throw ErrorFactory.createCliError("Error: Compiled app not found at dist/src/boot/bootstrap.js Run 'npm run build' first.");
+    }
+    return { command: 'node', args: [compiled] };
+};
+const executeWranglerStart = async (cmd, cwd, port, runtime) => {
+    if (runtime !== undefined) {
+        throw ErrorFactory.createCliError('Error: --runtime is not supported with --wrangler (Wrangler controls Workers runtime).');
+    }
+    const configPath = findWranglerConfig(cwd);
+    const entry = resolveWranglerEntry(cwd);
+    if (configPath === undefined && entry === undefined) {
+        throw ErrorFactory.createCliError("Error: wrangler config not found (wrangler.toml/json). Run 'wrangler init' first.");
+    }
+    const wranglerArgs = ['dev'];
+    if (configPath === undefined && entry !== undefined) {
+        wranglerArgs.push(entry);
+    }
+    if (typeof port === 'number') {
+        wranglerArgs.push('--port', String(port));
+    }
+    cmd.info('Starting in Wrangler dev mode...');
+    const exitCode = await SpawnUtil.spawnAndWait({ command: 'wrangler', args: wranglerArgs });
+    process.exit(exitCode);
+};
+const ensureTmpRunnerFile = (cwd, filename, content) => {
+    const tmpDir = path.join(cwd, 'tmp');
+    try {
+        mkdirSync(tmpDir, { recursive: true });
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError('Failed to create tmp directory', error);
+    }
+    const fullPath = path.join(tmpDir, filename);
+    try {
+        writeFileSync(fullPath, content, 'utf-8');
+    }
+    catch (error) {
+        throw ErrorFactory.createTryCatchError('Failed to write start runner', error);
+    }
+    return fullPath;
+};
+const executeDenoStart = async (cmd, cwd, mode, watchEnabled, _port, runtime) => {
+    if (runtime !== undefined) {
+        throw ErrorFactory.createCliError('Error: --runtime cannot be used with --deno.');
+    }
+    if (mode === 'testing') {
+        throw ErrorFactory.createCliError('Error: Cannot start server in testing mode. Use development or production.');
+    }
+    const denoRunner = ensureTmpRunnerFile(cwd, 'zin-start-deno.ts', DENO_RUNNER_SOURCE);
+    const args = [];
+    if (mode === 'development' && watchEnabled)
+        args.push('watch');
+    args.push(denoRunner);
+    cmd.info('Starting in Deno adapter mode...');
+    const exitCode = await SpawnUtil.spawnAndWait({ command: 'tsx', args });
+    process.exit(exitCode);
+};
+const executeLambdaStart = async (cmd, cwd, mode, watchEnabled, _port, runtime) => {
+    if (runtime !== undefined) {
+        throw ErrorFactory.createCliError('Error: --runtime cannot be used with --lambda.');
+    }
+    if (mode === 'testing') {
+        throw ErrorFactory.createCliError('Error: Cannot start server in testing mode. Use development or production.');
+    }
+    const lambdaRunner = ensureTmpRunnerFile(cwd, 'zin-start-lambda.ts', LAMBDA_RUNNER_SOURCE);
+    const args = [];
+    if (mode === 'development' && watchEnabled)
+        args.push('watch');
+    args.push(lambdaRunner);
+    cmd.info('Starting in Lambda adapter mode...');
+    const exitCode = await SpawnUtil.spawnAndWait({ command: 'tsx', args });
+    process.exit(exitCode);
+};
+const executeNodeStart = async (cmd, cwd, mode, watchEnabled) => {
+    if (mode === 'testing') {
+        throw ErrorFactory.createCliError('Error: Cannot start server in testing mode. Use --force to override (not supported).');
+    }
+    if (mode === 'development') {
+        if (!watchEnabled) {
+            cmd.warn('Watch mode disabled; starting once.');
+            const bootstrap = resolveBootstrapEntryTs(cwd);
+            const args = bootstrap === undefined ? ['src/index.ts'] : [bootstrap];
+            const exitCode = await SpawnUtil.spawnAndWait({
+                command: 'tsx',
+                args,
+                forwardSignals: false,
+            });
+            process.exit(exitCode);
+        }
+        const packageJson = readPackageJson(cwd);
+        const dev = resolveNodeDevCommand(cwd, packageJson);
+        cmd.info('Starting in development mode (watch enabled)...');
+        const exitCode = await SpawnUtil.spawnAndWait({
+            command: dev.command,
+            args: dev.args,
+            forwardSignals: false,
+        });
+        process.exit(exitCode);
+    }
+    const prod = resolveNodeProdCommand(cwd);
+    cmd.info('Starting in production mode...');
+    const exitCode = await SpawnUtil.spawnAndWait({
+        command: prod.command,
+        args: prod.args,
+        forwardSignals: false,
+    });
+    process.exit(exitCode);
+};
+const executeStart = async (options, cmd) => {
+    const cwd = process.cwd();
+    EnvFileLoader.ensureLoaded();
+    const mode = resolveMode(options);
+    const port = resolvePort(options);
+    const runtime = resolveRuntime(options);
+    const variant = resolveStartVariant(options);
+    let effectiveRuntime = runtime;
+    if (variant === 'deno')
+        effectiveRuntime = 'deno';
+    if (variant === 'lambda')
+        effectiveRuntime = 'lambda';
+    EnvFileLoader.applyCliOverrides({ nodeEnv: mode, port, runtime: effectiveRuntime });
+    if (variant === 'wrangler') {
+        await executeWranglerStart(cmd, cwd, port, runtime);
+        return;
+    }
+    const watchEnabled = resolveWatchPreference(options, mode);
+    if (variant === 'deno') {
+        await executeDenoStart(cmd, cwd, mode, watchEnabled, port, runtime);
+        return;
+    }
+    if (variant === 'lambda') {
+        await executeLambdaStart(cmd, cwd, mode, watchEnabled, port, runtime);
+        return;
+    }
+    await executeNodeStart(cmd, cwd, mode, watchEnabled);
+};
+export const StartCommand = Object.freeze({
+    create() {
+        const addOptions = (command) => {
+            command.alias('s');
+            command
+                .option('-w, --wrangler', 'Start with Wrangler dev mode (Cloudflare Workers)')
+                .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('--watch', 'Force watch mode (Node only)')
+                .option('--no-watch', 'Disable watch mode (Node only)')
+                .option('--mode <development|production|testing>', 'Override app mode')
+                .option('--runtime <nodejs|cloudflare|lambda|deno|auto>', 'Set RUNTIME for spawned Node')
+                .option('--port <number>', 'Override server port');
+        };
+        const cmd = BaseCommand.create({
+            name: 'start',
+            description: 'Start the application (dev watch, production, or Wrangler mode)',
+            addOptions,
+            execute: async (options) => executeStart(options, cmd),
+        });
+        return cmd;
+    },
+});

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

@@ -0,0 +1,3 @@
+export declare const TemplatesCommand: import("../BaseCommand").IBaseCommand;
+export default TemplatesCommand;
+//# sourceMappingURL=TemplatesCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TemplatesCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/TemplatesCommand.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,gBAAgB,yCAqC3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/src/cli/commands/TemplatesCommand.js

@@ -0,0 +1,65 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { ErrorHandler } from '../ErrorHandler.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { listTemplates as listMail, renderTemplate as renderMail } from '../../tools/mail/templates/index.js';
+import { listTemplates as listNotification, renderTemplate as renderNotification, } from '../../tools/notification/templates/markdown/index.js';
+const listForScope = (scope) => {
+    let items = [];
+    if (scope === 'mail' || scope === 'all')
+        items = items.concat(listMail());
+    if (scope === 'notification' || scope === 'all')
+        items = items.concat(listNotification());
+    items.sort((a, b) => a.localeCompare(b));
+    return items;
+};
+const renderByScope = (name, scope) => {
+    if (scope === 'mail')
+        return renderMail(name);
+    if (scope === 'notification')
+        return renderNotification(name);
+    try {
+        return renderMail(name);
+    }
+    catch {
+        try {
+            return renderNotification(name);
+        }
+        catch (error_) {
+            throw ErrorFactory.createTryCatchError('Template render failed', error_);
+        }
+    }
+};
+export const TemplatesCommand = BaseCommand.create({
+    name: 'templates',
+    description: 'Manage and render markdown templates (mail & notification)',
+    addOptions: (command) => {
+        command.argument('<action>', 'Action: list|render');
+        command.argument('[scope]', 'Scope: mail|notification|all', 'all');
+        command.argument('[name]', 'Template name when action=render');
+    },
+    execute: (options) => {
+        const action = options.args?.[0];
+        const scope = options.args?.[1] ?? 'all';
+        const name = options.args?.[2];
+        const handleList = (sc) => {
+            const items = listForScope(sc);
+            items.forEach((it) => ErrorHandler.info(it));
+        };
+        const handleRender = (nm, sc) => {
+            if (nm === null || nm === undefined || nm === '')
+                throw ErrorFactory.createValidationError('Template name required');
+            const out = renderByScope(nm, sc);
+            ErrorHandler.info(out.html);
+        };
+        if (action === 'list') {
+            handleList(scope);
+            return;
+        }
+        if (action === 'render') {
+            handleRender(name, scope);
+            return;
+        }
+        throw ErrorFactory.createValidationError(`Unknown action: ${String(action)}`);
+    },
+});
+export default TemplatesCommand;

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

@@ -0,0 +1,16 @@
+/**
+ * Upgrade Command
+ *
+ * Goal: help existing ZinTrust projects adopt new safe defaults without forcing
+ * a full re-scaffold.
+ *
+ * Current scope (minimal/safe):
+ * - Backfill required .env defaults (HOST, PORT, LOG_LEVEL) when missing or blank.
+ * - Never overwrite a non-empty user value.
+ */
+import { type IBaseCommand } from '../BaseCommand';
+export declare const UpgradeCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default UpgradeCommand;
+//# sourceMappingURL=UpgradeCommand.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"UpgradeCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/UpgradeCommand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAoFvF,eAAO,MAAM,cAAc;cACf,YAAY;EA6BtB,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/cli/commands/UpgradeCommand.js

@@ -0,0 +1,107 @@
+/**
+ * Upgrade Command
+ *
+ * Goal: help existing ZinTrust projects adopt new safe defaults without forcing
+ * a full re-scaffold.
+ *
+ * Current scope (minimal/safe):
+ * - Backfill required .env defaults (HOST, PORT, LOG_LEVEL) when missing or blank.
+ * - Never overwrite a non-empty user value.
+ */
+import { BaseCommand } from '../BaseCommand.js';
+import { ErrorHandler } from '../ErrorHandler.js';
+import { EnvFileBackfill } from '../env/EnvFileBackfill.js';
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+const ensureEnvFileExists = (envPath) => {
+    const dir = path.dirname(envPath);
+    mkdirSync(dir, { recursive: true });
+    try {
+        readFileSync(envPath, 'utf8');
+    }
+    catch {
+        writeFileSync(envPath, '\n', 'utf8');
+    }
+};
+const resolveCwd = (cwd) => {
+    if (typeof cwd === 'string' && cwd.trim() !== '')
+        return cwd;
+    return process.cwd();
+};
+const getEnvDefaults = () => Object.freeze({
+    HOST: 'localhost',
+    PORT: '7777',
+    LOG_LEVEL: 'debug',
+});
+const envFileExists = (envPath) => {
+    try {
+        readFileSync(envPath, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const formatBackfillSummary = (result) => {
+    const filled = result.filledKeys.join(', ') || '(none)';
+    const appended = result.appendedKeys.join(', ') || '(none)';
+    return `filled=${filled}; appended=${appended}`;
+};
+const runDryRun = (envPath, defaults) => {
+    const exists = envFileExists(envPath);
+    if (exists === false) {
+        ErrorHandler.info(`[dry-run] Would create ${envPath}`);
+        return;
+    }
+    const raw = readFileSync(envPath, 'utf8');
+    const tmpPath = `${envPath}.zin-upgrade.tmp`;
+    writeFileSync(tmpPath, raw, 'utf8');
+    try {
+        const result = EnvFileBackfill.backfillEnvDefaults(tmpPath, defaults);
+        if (result.changed === false) {
+            ErrorHandler.success('No changes needed.');
+            return;
+        }
+        ErrorHandler.info(`[dry-run] Would backfill .env: ${formatBackfillSummary(result)}`);
+    }
+    finally {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            // ignore
+        }
+    }
+};
+const runUpgrade = (envPath, defaults) => {
+    ensureEnvFileExists(envPath);
+    return EnvFileBackfill.backfillEnvDefaults(envPath, defaults);
+};
+export const UpgradeCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'upgrade',
+            description: 'Upgrade an existing ZinTrust project in-place (safe, non-destructive)',
+            addOptions: (command) => {
+                command.option('--cwd <path>', 'Project directory (default: current working directory)');
+                command.option('--dry-run', 'Print planned changes without writing files');
+            },
+            execute: (options) => {
+                const cwd = resolveCwd(options.cwd);
+                const envPath = path.resolve(cwd, '.env');
+                const defaults = getEnvDefaults();
+                if (options.dryRun === true) {
+                    runDryRun(envPath, defaults);
+                    return;
+                }
+                const result = runUpgrade(envPath, defaults);
+                if (result.changed === false) {
+                    ErrorHandler.success('No changes needed.');
+                    return;
+                }
+                ErrorHandler.success(`Upgraded .env: ${formatBackfillSummary(result)}`);
+            },
+        });
+    },
+});
+export default UpgradeCommand;

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

@@ -0,0 +1,17 @@
+/**
+ * Worker Management CLI Commands
+ * Command-line interface for managing workers
+ */
+import type { IBaseCommand } from '../BaseCommand';
+/**
+ * Export worker command creators
+ */
+export declare const WorkerCommands: {
+    createWorkerListCommand: () => IBaseCommand;
+    createWorkerStatusCommand: () => IBaseCommand;
+    createWorkerStartCommand: () => IBaseCommand;
+    createWorkerStopCommand: () => IBaseCommand;
+    createWorkerRestartCommand: () => IBaseCommand;
+    createWorkerSummaryCommand: () => IBaseCommand;
+};
+//# sourceMappingURL=WorkerCommands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WorkerCommands.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/WorkerCommands.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAmWrD;;GAEG;AACH,eAAO,MAAM,cAAc;mCAjPS,YAAY;qCA4CV,YAAY;oCAiDb,YAAY;mCA+Bb,YAAY;sCAgCT,YAAY;sCAgCZ,YAAY;CA4DlD,CAAC"}