@zintrust/core 0.1.26 → 0.1.28

package/src/cli/commands/StartCommand.ts

@@ -0,0 +1,448 @@
+import { BaseCommand, type CommandOptions, type IBaseCommand } from '@cli/BaseCommand';
+import { DENO_RUNNER_SOURCE, LAMBDA_RUNNER_SOURCE } from '@cli/commands/runner';
+import { EnvFileLoader } from '@cli/utils/EnvFileLoader';
+import { SpawnUtil } from '@cli/utils/spawn';
+import { readEnvString } from '@common/ExternalServiceUtils';
+import { resolveNpmPath } from '@common/index';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+import type { Command } from 'commander';
+
+type StartMode = 'development' | 'production' | 'testing';
+
+type StartModeInput = 'development' | 'dev' | 'production' | 'pro' | 'prod' | 'testing';
+
+type StartCommandOptions = CommandOptions & {
+  wrangler?: boolean;
+  wg?: boolean;
+  deno?: boolean;
+  lambda?: boolean;
+  watch?: boolean;
+  mode?: string;
+  runtime?: string;
+  port?: string;
+};
+
+type StartVariant = 'node' | 'wrangler' | 'deno' | 'lambda';
+
+const isValidModeInput = (value: string): value is StartModeInput =>
+  value === 'development' ||
+  value === 'dev' ||
+  value === 'production' ||
+  value === 'pro' ||
+  value === 'prod' ||
+  value === 'testing';
+
+const normalizeMode = (value: StartModeInput): StartMode => {
+  if (value === 'production' || value === 'pro' || value === 'prod') return 'production';
+  if (value === 'testing') return 'testing';
+  return 'development';
+};
+
+const resolveModeFromAppMode = (): StartMode => {
+  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: StartCommandOptions): StartMode => {
+  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: StartCommandOptions): number | undefined => {
+  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: StartCommandOptions): string | undefined => {
+  const raw = typeof options.runtime === 'string' ? options.runtime.trim() : '';
+  return raw === '' ? undefined : raw;
+};
+
+const resolveStartVariant = (options: StartCommandOptions): StartVariant => {
+  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: string): boolean => process.argv.includes(flag);
+
+const resolveWatchPreference = (options: StartCommandOptions, mode: StartMode): boolean => {
+  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: string): { name?: unknown; scripts?: Record<string, unknown> } => {
+  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) as { name?: unknown; scripts?: Record<string, unknown> };
+  } catch (error) {
+    throw ErrorFactory.createTryCatchError('Failed to read package.json', error);
+  }
+};
+
+const isFrameworkRepo = (packageJson: { name?: unknown }): boolean =>
+  packageJson.name === '@zintrust/core';
+
+const hasDevScript = (packageJson: { scripts?: Record<string, unknown> }): boolean => {
+  const scripts = packageJson.scripts;
+  if (!scripts) return false;
+  return typeof scripts['dev'] === 'string' && scripts['dev'] !== '';
+};
+
+const findWranglerConfig = (cwd: string): string | undefined => {
+  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: string): string | undefined => {
+  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: string): string | undefined => {
+  const boot = path.join(cwd, 'src/boot/bootstrap.ts');
+  if (existsSync(boot)) return 'src/boot/bootstrap.ts';
+  return undefined;
+};
+
+const resolveNodeDevCommand = (
+  cwd: string,
+  packageJson: { name?: unknown; scripts?: Record<string, unknown> }
+): { command: string; args: string[] } => {
+  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: string): { command: string; args: string[] } => {
+  const compiledBoot = path.join(cwd, 'dist/src/boot/bootstrap.js');
+
+  let compiled: string | undefined;
+  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: IBaseCommand,
+  cwd: string,
+  port: number | undefined,
+  runtime: string | undefined
+): Promise<void> => {
+  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: string[] = ['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: string, filename: string, content: string): string => {
+  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: IBaseCommand,
+  cwd: string,
+  mode: StartMode,
+  watchEnabled: boolean,
+  _port: number | undefined,
+  runtime: string | undefined
+): Promise<void> => {
+  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: string[] = [];
+  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: IBaseCommand,
+  cwd: string,
+  mode: StartMode,
+  watchEnabled: boolean,
+  _port: number | undefined,
+  runtime: string | undefined
+): Promise<void> => {
+  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: string[] = [];
+  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: IBaseCommand,
+  cwd: string,
+  mode: StartMode,
+  watchEnabled: boolean
+): Promise<void> => {
+  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: StartCommandOptions, cmd: IBaseCommand): Promise<void> => {
+  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(): IBaseCommand {
+    const addOptions = (command: Command): void => {
+      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: IBaseCommand = BaseCommand.create({
+      name: 'start',
+      description: 'Start the application (dev watch, production, or Wrangler mode)',
+      addOptions,
+      execute: async (options: CommandOptions): Promise<void> =>
+        executeStart(options as StartCommandOptions, cmd),
+    });
+
+    return cmd;
+  },
+});

package/src/cli/commands/TemplatesCommand.ts

@@ -0,0 +1,72 @@
+import { BaseCommand } from '@cli/BaseCommand';
+import { ErrorHandler } from '@cli/ErrorHandler';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { listTemplates as listMail, renderTemplate as renderMail } from '@mail/templates';
+import {
+  listTemplates as listNotification,
+  renderTemplate as renderNotification,
+} from '@notification/templates/markdown';
+
+const listForScope = (scope: string): string[] => {
+  let items: string[] = [];
+  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: string, scope: string): ReturnType<typeof renderMail> => {
+  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] as string;
+    const scope = (options.args?.[1] as string) ?? 'all';
+    const name = options.args?.[2];
+
+    const handleList = (sc: string): void => {
+      const items = listForScope(sc);
+      items.forEach((it) => ErrorHandler.info(it));
+    };
+
+    const handleRender = (nm: string | undefined, sc: string): void => {
+      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.ts

@@ -0,0 +1,128 @@
+/**
+ * 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, type CommandOptions, type IBaseCommand } from '@cli/BaseCommand';
+import { ErrorHandler } from '@cli/ErrorHandler';
+import { type EnvBackfillResult, EnvFileBackfill } from '@cli/env/EnvFileBackfill';
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+import type { Command } from 'commander';
+
+type UpgradeCommandOptions = CommandOptions & {
+  cwd?: string;
+  dryRun?: boolean;
+};
+
+const ensureEnvFileExists = (envPath: string): void => {
+  const dir = path.dirname(envPath);
+  mkdirSync(dir, { recursive: true });
+  try {
+    readFileSync(envPath, 'utf8');
+  } catch {
+    writeFileSync(envPath, '\n', 'utf8');
+  }
+};
+
+const resolveCwd = (cwd?: string): string => {
+  if (typeof cwd === 'string' && cwd.trim() !== '') return cwd;
+  return process.cwd();
+};
+
+const getEnvDefaults = (): Record<string, string> =>
+  Object.freeze({
+    HOST: 'localhost',
+    PORT: '7777',
+    LOG_LEVEL: 'debug',
+  });
+
+const envFileExists = (envPath: string): boolean => {
+  try {
+    readFileSync(envPath, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const formatBackfillSummary = (result: EnvBackfillResult): string => {
+  const filled = result.filledKeys.join(', ') || '(none)';
+  const appended = result.appendedKeys.join(', ') || '(none)';
+  return `filled=${filled}; appended=${appended}`;
+};
+
+const runDryRun = (envPath: string, defaults: Record<string, string>): void => {
+  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: string, defaults: Record<string, string>): EnvBackfillResult => {
+  ensureEnvFileExists(envPath);
+  return EnvFileBackfill.backfillEnvDefaults(envPath, defaults);
+};
+
+export const UpgradeCommand = Object.freeze({
+  create(): IBaseCommand {
+    return BaseCommand.create({
+      name: 'upgrade',
+      description: 'Upgrade an existing ZinTrust project in-place (safe, non-destructive)',
+      addOptions: (command: Command) => {
+        command.option('--cwd <path>', 'Project directory (default: current working directory)');
+        command.option('--dry-run', 'Print planned changes without writing files');
+      },
+      execute: (options: UpgradeCommandOptions): void => {
+        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;