@titannio/webtoolkit-cli 1.3.0

package/dist/ready-service.js

@@ -0,0 +1,135 @@
+import http from 'node:http';
+import https from 'node:https';
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+};
+const defaultPollIntervalMs = 1000;
+function colorize(message, color) {
+    return `${color}${message}${colors.reset}`;
+}
+function getArgValue(args, name) {
+    const prefix = `--${name}=`;
+    const index = args.findIndex((arg) => arg === `--${name}`);
+    if (index >= 0)
+        return args[index + 1] ?? null;
+    return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length) ?? null;
+}
+function parseTimeoutMs(rawValue) {
+    if (!rawValue)
+        return null;
+    const normalized = rawValue.trim().toLowerCase();
+    if (normalized === 'never' || normalized === '0')
+        return null;
+    const value = Number(normalized);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`Invalid timeout: ${rawValue}. Use a non-negative integer in milliseconds, 0, or "never".`);
+    }
+    return value;
+}
+function parseIntervalMs(rawValue) {
+    if (!rawValue)
+        return defaultPollIntervalMs;
+    const value = Number(rawValue.trim());
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Invalid interval: ${rawValue}. Use a positive integer in milliseconds.`);
+    }
+    return value;
+}
+function validateUrl(urlString) {
+    const url = new URL(urlString);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Invalid protocol: ${url.protocol}. Only http: and https: are allowed.`);
+    }
+    return url;
+}
+function getReadinessUrl(url) {
+    return `${url.protocol}//${url.host}/ready`;
+}
+function checkReadiness(url) {
+    return new Promise((resolve) => {
+        const readinessUrl = getReadinessUrl(url);
+        const httpModule = url.protocol === 'https:' ? https : http;
+        const req = httpModule.get(readinessUrl, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk.toString();
+            });
+            res.on('end', () => {
+                try {
+                    const readinessStatus = JSON.parse(data);
+                    if (res.statusCode === 200 && readinessStatus.status === 'ok') {
+                        resolve({ success: true, status: 'ok', readinessData: readinessStatus });
+                        return;
+                    }
+                    resolve({
+                        success: false,
+                        status: String(readinessStatus.status ?? 'unknown'),
+                        readinessData: readinessStatus,
+                        error: `HTTP ${res.statusCode}: service status ${String(readinessStatus.status ?? 'unknown')}`,
+                    });
+                }
+                catch (error) {
+                    resolve({ success: false, error: `Invalid JSON response: ${error.message}` });
+                }
+            });
+        });
+        req.on('error', (error) => {
+            resolve({ success: false, error: `Network error: ${error.code || error.message}` });
+        });
+        req.setTimeout(5000, () => {
+            req.destroy();
+            resolve({ success: false, error: 'Request timeout (5s)' });
+        });
+    });
+}
+function formatSeconds(milliseconds) {
+    const seconds = milliseconds / 1000;
+    const formatted = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(1).replace(/\.0$/u, '');
+    return `${formatted} ${seconds === 1 ? 'second' : 'seconds'}`;
+}
+function formatTimeout(timeoutMs) {
+    return timeoutMs === null ? 'no timeout' : `timeout: ${formatSeconds(timeoutMs)}`;
+}
+async function pollService(url, timeoutMs, intervalMs) {
+    const startedAt = Date.now();
+    let attempts = 0;
+    let lastResult = null;
+    while (timeoutMs === null || Date.now() - startedAt < timeoutMs) {
+        attempts += 1;
+        const result = await checkReadiness(url);
+        lastResult = result;
+        if (result.success)
+            return { success: true, attempts, elapsedMs: Date.now() - startedAt, lastResult };
+        const remainingMs = timeoutMs === null ? intervalMs : timeoutMs - (Date.now() - startedAt);
+        if (remainingMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remainingMs)));
+        }
+    }
+    return { success: false, attempts, elapsedMs: Date.now() - startedAt, lastResult };
+}
+export async function runReadyService(_runtime, rawArgs) {
+    if (rawArgs.includes('--skip-ready-check')) {
+        console.info(colorize('Service readiness check skipped; continuing startup.', colors.yellow));
+        return;
+    }
+    const serviceName = getArgValue(rawArgs, 'name') || process.env.READY_SERVICE_NAME || 'Backend';
+    const serviceUrl = getArgValue(rawArgs, 'url') || process.env.BACKEND_READY_URL || process.env.VITE_API_URL || 'http://localhost:3001';
+    const timeoutMs = parseTimeoutMs(getArgValue(rawArgs, 'timeout-ms') ?? process.env.BACKEND_READY_TIMEOUT_MS);
+    const intervalMs = parseIntervalMs(getArgValue(rawArgs, 'interval-ms') ?? process.env.BACKEND_READY_INTERVAL_MS);
+    const url = validateUrl(serviceUrl);
+    console.info(colorize(`Waiting for ${serviceName}: ${getReadinessUrl(url)} (interval: ${formatSeconds(intervalMs)}, ${formatTimeout(timeoutMs)})`, colors.cyan));
+    const result = await pollService(url, timeoutMs, intervalMs);
+    if (result.success) {
+        console.info(colorize(`${serviceName} ready after ${formatSeconds(result.elapsedMs)}; continuing startup.`, colors.green));
+        return;
+    }
+    console.error(colorize(`\nService did not become available after ${result.attempts} attempts.`, colors.red));
+    if (result.lastResult?.error)
+        console.error(colorize(`   ${result.lastResult.error}`, colors.dim));
+    process.exit(1);
+}

package/dist/release-gate.d.ts

@@ -0,0 +1,7 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function runReleaseGate(runtime: Runtime, requestedStages: string[]): void;
+export {};

package/dist/release-gate.js

@@ -0,0 +1,35 @@
+import { buildPackageManagerCommand, runCommandInherited } from './process.js';
+function resolveStageCommand(config, stage) {
+    if (stage.command) {
+        return { command: stage.command, args: stage.args ?? [] };
+    }
+    if (stage.package && stage.script) {
+        return buildPackageManagerCommand(config.packageManager, ['--filter', stage.package, 'run', stage.script, ...(stage.files ?? [])]);
+    }
+    if (stage.package && stage.files?.length) {
+        return buildPackageManagerCommand(config.packageManager, ['--filter', stage.package, 'exec', 'vitest', 'run', ...stage.files]);
+    }
+    throw new Error(`Release gate stage "${stage.name}" must define command/args or package/files.`);
+}
+export function runReleaseGate(runtime, requestedStages) {
+    const stages = runtime.config.releaseGate?.stages;
+    if (!stages?.length) {
+        throw new Error('releaseGate.stages is not configured.');
+    }
+    const selectedStages = requestedStages.length === 0
+        ? stages
+        : stages.filter((stage) => requestedStages.includes(stage.name));
+    if (requestedStages.length > 0 && selectedStages.length !== requestedStages.length) {
+        const knownStages = new Set(stages.map((stage) => stage.name));
+        const unknownStages = requestedStages.filter((stageName) => !knownStages.has(stageName));
+        throw new Error(`[release-gate] unknown stage(s): ${unknownStages.join(', ')}`);
+    }
+    for (const stage of selectedStages) {
+        console.info(`\n[release-gate] running ${stage.name}`);
+        const command = resolveStageCommand(runtime.config, stage);
+        const code = runCommandInherited(command, runtime.cwd);
+        if (code !== 0)
+            process.exit(code);
+    }
+    console.info('\n[release-gate] all critical stages passed');
+}

package/dist/repo-check.d.ts

@@ -0,0 +1,7 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function runRepoCheck(runtime: Runtime): void;
+export {};

package/dist/repo-check.js

@@ -0,0 +1,121 @@
+import { formatCommand, runCommandInherited } from './process.js';
+import { builtinGuards, executeBuiltinGuard } from './guard-runner.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+};
+function colorize(message, color) {
+    return `${color}${message}${colors.reset}`;
+}
+function visibleLength(value) {
+    return value.replace(/\x1B\[[0-9;?]*[ -/]*[@-~]/gu, '').length;
+}
+function padVisible(value, width) {
+    return `${value}${' '.repeat(Math.max(0, width - visibleLength(value)))}`;
+}
+function buildAsciiTable(results) {
+    const rows = results.map((result) => [
+        result.label,
+        result.status === 'OK'
+            ? colorize(result.status, colors.green)
+            : result.status === 'FAIL'
+                ? colorize(result.status, colors.red)
+                : result.status,
+        `${(result.durationMs / 1000).toFixed(2)}s`,
+    ]);
+    const headers = [colorize('Etapa', colors.yellow), colorize('Status', colors.yellow), colorize('Duracao', colors.yellow)];
+    const widths = headers.map((header, index) => Math.max(visibleLength(header), ...rows.map((row) => visibleLength(row[index]))));
+    const separator = `+${widths.map((width) => '-'.repeat(width + 2)).join('+')}+`;
+    const formatRow = (row) => `| ${row.map((cell, index) => padVisible(cell, widths[index])).join(' | ')} |`;
+    return [
+        separator,
+        formatRow(headers),
+        separator,
+        ...rows.map(formatRow),
+        separator,
+    ].join('\n');
+}
+function runCheck(step, runtime) {
+    const args = step.args ?? [];
+    if (step.builtinGuard) {
+        console.info('');
+        console.info(colorize(`Step: ${step.label}`, `${colors.bright}${colors.blue}`));
+        console.info(colorize(`> webtoolkit guard ${step.builtinGuard} ${args.join(' ')}`.trim(), colors.cyan));
+        console.info('');
+        return executeBuiltinGuard(step.builtinGuard, args, runtime.cwd);
+    }
+    const command = step.command;
+    console.info('');
+    console.info(colorize(`Step: ${step.label}`, `${colors.bright}${colors.blue}`));
+    console.info(colorize(`> ${formatCommand(command, args)}`, colors.cyan));
+    console.info('');
+    return runCommandInherited({
+        command,
+        args,
+        cwd: step.cwd,
+        env: step.env,
+    }, runtime.cwd);
+}
+function validateSteps(steps) {
+    for (const step of steps) {
+        const hasCommand = Boolean(step.command?.trim());
+        const hasBuiltinGuard = Boolean(step.builtinGuard?.trim());
+        if (hasCommand === hasBuiltinGuard) {
+            throw new Error(`Repo check step "${step.label}" must define exactly one of command or builtinGuard.`);
+        }
+        if (step.builtinGuard && !Object.hasOwn(builtinGuards, step.builtinGuard)) {
+            throw new Error(`Unknown builtin guard "${step.builtinGuard}". Available guards: ${Object.keys(builtinGuards).sort().join(', ')}.`);
+        }
+    }
+}
+export function runRepoCheck(runtime) {
+    const config = runtime.config.repoCheck;
+    if (!config?.steps?.length) {
+        throw new Error('repoCheck.steps is not configured.');
+    }
+    validateSteps(config.steps);
+    console.info(colorize(config.title ?? 'Starting Quality Assurance Checks...', `${colors.bright}${colors.yellow}`));
+    const failFast = config.failFast ?? false;
+    const results = [];
+    let hasFailure = false;
+    for (const step of config.steps) {
+        if (hasFailure && failFast) {
+            results.push({ label: step.label, status: 'SKIP', durationMs: 0 });
+            continue;
+        }
+        const startedAt = Date.now();
+        try {
+            const code = runCheck(step, runtime);
+            const durationMs = Date.now() - startedAt;
+            const status = code === 0 ? 'OK' : 'FAIL';
+            results.push({ label: step.label, status, durationMs });
+            if (status === 'OK') {
+                console.info(colorize(`[OK] ${step.label}`, colors.green));
+            }
+            else {
+                hasFailure = true;
+                console.error(`\n${colorize(`[FAIL] ${step.label} (exit code ${code})`, colors.red)}`);
+            }
+        }
+        catch (error) {
+            hasFailure = true;
+            results.push({ label: step.label, status: 'FAIL', durationMs: Date.now() - startedAt });
+            console.error(`\n${colorize(`[FAIL] ${step.label}: ${error.message}`, `${colors.bright}${colors.red}`)}`);
+        }
+    }
+    console.info('');
+    console.info(colorize('ASCII Summary', `${colors.bright}${colors.cyan}`));
+    console.info(buildAsciiTable(results));
+    console.info('');
+    if (hasFailure) {
+        console.error(`\n${colorize('One or more checks failed. Please fix the errors above before proceeding.', `${colors.bright}${colors.red}`)}\n`);
+        process.exit(1);
+        return;
+    }
+    console.info(`\n${colorize('All checks passed successfully!', `${colors.bright}${colors.green}`)}\n`);
+}

package/dist/tasks.d.ts

@@ -0,0 +1,17 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function formatTaskStatusLine(options: {
+    action: string;
+    label: string;
+    status?: 'OK' | 'FALHA' | 'SKIP';
+    durationMs?: number;
+}): string;
+export declare function resolveTaskName(command: string): string | null;
+export declare function normalizePassthroughArgs(args: string[]): string[];
+export declare function listTaskCommands(config: WebToolkitCliConfig): string[];
+export declare function printTaskHelp(taskName: string, config: WebToolkitCliConfig): void;
+export declare function runTask(taskName: string, runtime: Runtime, passthroughArgs?: string[]): Promise<void>;
+export {};

package/dist/tasks.js

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { executeBuiltinGuard } from './guard-runner.js';
+const taskAliases = {
+    check: 'check',
+    build: 'build',
+    test: 'test',
+    'test-coverage': 'testCoverage',
+    'release-gate': 'releaseGate',
+    validate: 'validate',
+    'jsdoc-report': 'jsdocReport',
+    upgrade: 'upgrade',
+    performance: 'performanceBundleAudit',
+    'performance-bundle-audit': 'performanceBundleAudit',
+};
+function formatDuration(durationMs) {
+    return `${(durationMs / 1000).toFixed(2)}s`;
+}
+function resolveWorkingDirectory(runtime, step) {
+    if (!step.cwd)
+        return runtime.cwd;
+    if (path.isAbsolute(step.cwd))
+        return step.cwd;
+    return path.join(runtime.cwd, step.cwd);
+}
+function resolveCommand(step, args) {
+    if (!step.command) {
+        throw new Error(`Task step "${step.label}" must define command or builtinGuard.`);
+    }
+    if (process.platform !== 'win32') {
+        return { command: step.command, args, shell: false };
+    }
+    if (step.command === 'node' || step.command === process.execPath) {
+        return { command: step.command, args, shell: false };
+    }
+    return {
+        command: process.env.ComSpec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', step.command, ...args],
+        shell: false,
+    };
+}
+function colorizeResult(status) {
+    if (status === 'OK')
+        return `\x1b[32m${status}\x1b[0m`;
+    if (status === 'FALHA')
+        return `\x1b[31m${status}\x1b[0m`;
+    return `\x1b[90m${status}\x1b[0m`;
+}
+export function formatTaskStatusLine(options) {
+    const duration = options.durationMs === undefined ? '' : ` (${formatDuration(options.durationMs)})`;
+    const status = options.status === undefined ? '' : ` ${colorizeResult(options.status)}${duration}`;
+    return `- ${options.action} \x1b[1m${options.label.padEnd(16)}\x1b[0m...${status}`;
+}
+function getStepAction(step) {
+    return step.args?.includes('build') ? 'Building' : 'Running';
+}
+function runStep(step, runtime, passthroughArgs, defaultOutputMode) {
+    const args = [...(step.args ?? []), ...(step.appendArgs ? normalizePassthroughArgs(passthroughArgs) : [])];
+    const outputMode = step.outputMode ?? defaultOutputMode;
+    if (step.builtinGuard) {
+        return Promise.resolve({ code: executeBuiltinGuard(step.builtinGuard, args, runtime.cwd), output: '' });
+    }
+    const resolved = resolveCommand(step, args);
+    const child = spawn(resolved.command, resolved.args, {
+        cwd: resolveWorkingDirectory(runtime, step),
+        env: {
+            ...process.env,
+            FORCE_COLOR: '1',
+            ...(step.env ?? {}),
+        },
+        shell: resolved.shell,
+        stdio: outputMode === 'inherit' ? 'inherit' : ['inherit', 'pipe', 'pipe'],
+    });
+    let output = '';
+    if (outputMode === 'buffered') {
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+    }
+    return new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code: code ?? 1, output }));
+    });
+}
+export function resolveTaskName(command) {
+    if (command.startsWith('run:'))
+        return command.slice('run:'.length);
+    return taskAliases[command] ?? null;
+}
+export function normalizePassthroughArgs(args) {
+    if (args[0] === '--')
+        return args.slice(1);
+    return args;
+}
+export function listTaskCommands(config) {
+    return Object.keys(config.tasks).sort();
+}
+export function printTaskHelp(taskName, config) {
+    const task = config.tasks[taskName];
+    if (!task) {
+        console.info(`Task "${taskName}" is not configured.`);
+        return;
+    }
+    console.info(task.title ?? `Task: ${taskName}`);
+    console.info('');
+    console.info('Steps:');
+    for (const step of task.steps) {
+        const command = step.builtinGuard ? `webtoolkit guard ${step.builtinGuard}` : step.command ?? '<builtin>';
+        console.info(` - ${step.label}: ${command} ${(step.args ?? []).join(' ')}`.trim());
+    }
+    if (task.steps.some((step) => step.appendArgs)) {
+        console.info('');
+        console.info('Additional arguments are appended to steps marked with appendArgs.');
+    }
+}
+export async function runTask(taskName, runtime, passthroughArgs = []) {
+    const task = runtime.config.tasks[taskName];
+    if (!task) {
+        const available = listTaskCommands(runtime.config);
+        throw new Error(available.length > 0
+            ? `Task "${taskName}" is not configured. Available tasks: ${available.join(', ')}.`
+            : `Task "${taskName}" is not configured.`);
+    }
+    const failFast = task.failFast ?? true;
+    const defaultOutputMode = task.outputMode ?? 'inherit';
+    let hasFailure = false;
+    console.info(task.title ?? `Running task: ${taskName}`);
+    for (const step of task.steps) {
+        const stepOutputMode = step.outputMode ?? defaultOutputMode;
+        if (hasFailure && failFast) {
+            console.info(formatTaskStatusLine({
+                action: getStepAction(step),
+                label: step.label,
+                status: 'SKIP',
+                durationMs: 0,
+            }));
+            continue;
+        }
+        const startLine = formatTaskStatusLine({
+            action: getStepAction(step),
+            label: step.label,
+        });
+        if (stepOutputMode === 'buffered') {
+            process.stdout.write(startLine);
+        }
+        else {
+            console.info('');
+            console.info(startLine);
+            console.info(`> ${step.label}`);
+            const displayCommand = step.builtinGuard ? `webtoolkit guard ${step.builtinGuard}` : step.command ?? '<builtin>';
+            console.info(`$ ${displayCommand} ${[...(step.args ?? []), ...(step.appendArgs ? normalizePassthroughArgs(passthroughArgs) : [])].join(' ')}`.trim());
+        }
+        const startedAt = Date.now();
+        const outcome = await runStep(step, runtime, passthroughArgs, defaultOutputMode);
+        const durationMs = Date.now() - startedAt;
+        if (outcome.code === 0) {
+            const completedLine = formatTaskStatusLine({
+                action: getStepAction(step),
+                label: step.label,
+                status: 'OK',
+                durationMs,
+            });
+            if (stepOutputMode === 'buffered') {
+                console.info(` ${colorizeResult('OK')} (${formatDuration(durationMs)})`);
+            }
+            else {
+                console.info(completedLine);
+            }
+            continue;
+        }
+        hasFailure = true;
+        const failedLine = formatTaskStatusLine({
+            action: getStepAction(step),
+            label: step.label,
+            status: 'FALHA',
+            durationMs,
+        });
+        if (stepOutputMode === 'buffered') {
+            console.info(` ${colorizeResult('FALHA')} (${formatDuration(durationMs)})`);
+        }
+        else {
+            console.info(failedLine);
+        }
+        if (outcome.output.trim()) {
+            console.info('');
+            console.info(outcome.output.trim());
+        }
+    }
+    if (hasFailure) {
+        throw new Error(`Task "${taskName}" failed.`);
+    }
+}

package/dist/upgrade.d.ts

@@ -0,0 +1,10 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function mergeRejectLists(baseRejectList: string[], protectedDependencyNames: string[]): string[];
+export declare function parseYesNo(answer: string, defaultValue: boolean): boolean | null;
+export declare function formatYesNoPrompt(icon: string, question: string, defaultValue: boolean): string;
+export declare function runUpgradeEngine(runtime: Runtime, rawArgs: string[]): Promise<void>;
+export {};