onveloz 0.0.0-beta.24 → 0.0.0-beta.26

package/dist/index.mjs

@@ -85,17 +85,17 @@ const DISK_ENGINE_SIZES = {
 	},
 	nitro: {
 		label: "Nitro",
-		cpu: "2",
+		cpu: "1",
 		memory: "4Gi",
-		cpuLabel: "2 vCPU",
+		cpuLabel: "1 vCPU",
 		memoryLabel: "4 GB"
 	},
 	"nitro-plus": {
 		label: "Nitro Plus",
-		cpu: "4",
-		memory: "8Gi",
-		cpuLabel: "4 vCPU",
-		memoryLabel: "8 GB"
+		cpu: "2",
+		memory: "4Gi",
+		cpuLabel: "2 vCPU",
+		memoryLabel: "4 GB"
 	}
 };
 /** Redis size tiers — memory-heavy since Redis is purely in-memory, CPU stays minimal. */
@@ -138,9 +138,9 @@ const REDIS_SIZES = {
 	"nitro-plus": {
 		label: "Nitro Plus",
 		cpu: "1",
-		memory: "4Gi",
+		memory: "3Gi",
 		cpuLabel: "1 vCPU",
-		memoryLabel: "4 GB"
+		memoryLabel: "3 GB"
 	}
 };
 /** Per-engine size tier maps. */
@@ -179,6 +179,14 @@ function resolveDatabaseSize(cpu, memory, engine) {
 	for (const [key, tier] of Object.entries(sizes)) if (tier.cpu === cpu && tier.memory === memory) return key;
 	return null;
 }
+/**
+* Returns the rank (0-based index) of a database size key.
+* Higher rank = bigger tier. Returns -1 if unknown.
+*/
+function getDatabaseSizeRank(size, engine) {
+	const sizes = engine ? DATABASE_SIZES_BY_ENGINE[engine] : DISK_ENGINE_SIZES;
+	return Object.keys(sizes).indexOf(size);
+}
 const SERVICE_SIZES = {
 	basico: {
 		label: "Básico",
@@ -1106,9 +1114,29 @@ async function resolveService(serviceFlag) {
 	};
 }
 async function resolveServiceId(serviceFlag) {
+	if (serviceFlag) {
+		const config = loadConfig();
+		if (config) {
+			const dbFound = Object.entries(config.databases ?? {}).find(([key, db]) => key === serviceFlag || db.name !== void 0 && db.name === serviceFlag || db.id === serviceFlag);
+			if (dbFound) {
+				const [key, db] = dbFound;
+				if (!db.id) throw new Error(`Banco "${db.name ?? key}" não possui ID. Execute 'veloz deploy' para vincular.`);
+				return db.id;
+			}
+		}
+	}
 	const { service } = await resolveService(serviceFlag);
 	return service.id;
 }
+/** Check if a service flag refers to a database in the config */
+function isDatabaseService(serviceFlag) {
+	const config = loadConfig();
+	if (!config) return false;
+	if (serviceFlag) return Object.entries(config.databases ?? {}).some(([key, db]) => key === serviceFlag || db.name !== void 0 && db.name === serviceFlag || db.id === serviceFlag);
+	const entries = Object.entries(config.services);
+	if (entries.length === 1) return entries[0][1].type === "database";
+	return false;
+}
 function resolveAllServices(serviceFlag) {
 	const config = requireConfig();
 	const entries = Object.entries(config.services);
@@ -2974,52 +3002,142 @@ function printSparkline(label, values, suffix, width) {
 	const latest = latestValue(values);
 	console.log(`  ${label.padEnd(width)} ${sparkline(values)}  ${chalk.bold(`${formatCompact(latest)}${suffix}`)}`);
 }
+function formatUptime(seconds) {
+	if (seconds < 60) return `${Math.round(seconds)}s`;
+	if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+	if (seconds < 86400) return `${Math.round(seconds / 3600)}h`;
+	return `${Math.round(seconds / 86400)}d`;
+}
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes.toFixed(0)} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function formatPercent(value) {
+	return `${value.toFixed(1)}%`;
+}
+function printInsightsHint() {
+	console.log();
+	info(`Ative insights para métricas detalhadas do banco: ${chalk.bold("veloz db update <nome> --insights")}`);
+}
 const metricsGroup = Cli.create("metrics", { description: "Visualizar métricas dos serviços" });
 metricsGroup.command("show", {
 	description: "Exibir métricas atuais do serviço",
 	middleware: [requireAuth],
-	options: z.object({ service: z.string().optional().describe("Filtrar por serviço") }),
+	options: z.object({ service: z.string().optional().describe("Filtrar por serviço ou banco de dados") }),
 	output: z.object({
 		requestRate: z.number(),
 		errorRate: z.number(),
 		latencyP95: z.number(),
 		statusCodes: z.record(z.string(), z.number()),
-		grafanaDashboardUrl: z.string().nullable()
+		grafanaDashboardUrl: z.string().nullable(),
+		resource: z.object({
+			restarts: z.number(),
+			uptimeSeconds: z.number(),
+			oomEvents: z.number(),
+			cpuThrottlePercent: z.number()
+		}).nullable(),
+		database: z.object({
+			activeConnections: z.number(),
+			queriesPerSec: z.number(),
+			cacheHitRatio: z.number(),
+			totalConnections: z.number(),
+			idleConnections: z.number(),
+			databaseSize: z.number(),
+			insightsEnabled: z.boolean()
+		}).nullable(),
+		hint: z.string()
 	}),
 	async run(c) {
 		const serviceId = await resolveServiceId(c.options.service);
 		const client = await getClient();
-		const metrics = await withSpinner({
+		const isDb = isDatabaseService(c.options.service);
+		const { metrics, resource, database } = await withSpinner({
 			text: "Carregando métricas...",
-			fn: () => client.metrics.getServiceMetrics({ serviceId })
+			fn: async () => {
+				const [metrics$1, resource$1, database$1] = await Promise.all([
+					client.metrics.getServiceMetrics({ serviceId }),
+					client.metrics.getResourceMetricsInstant({ serviceId }),
+					isDb ? client.databaseInsights.getMetrics({ serviceId }) : null
+				]);
+				return {
+					metrics: metrics$1,
+					resource: resource$1,
+					database: database$1
+				};
+			}
 		});
 		if (process.stdout.isTTY) {
+			const W = 22;
 			console.log();
-			console.log(chalk.bold("  Métricas do Serviço"));
+			if (!isDb) {
+				console.log(chalk.bold("  Métricas de Tráfego"));
+				console.log();
+				console.log(`  ${"Requisições/min".padEnd(W)} ${chalk.bold(formatCompact(metrics.requestRate))}`);
+				console.log(`  ${"Erros/min".padEnd(W)} ${rateColor(metrics.errorRate)(formatCompact(metrics.errorRate))}`);
+				console.log(`  ${"Latência P95".padEnd(W)} ${chalk.bold(formatCompact(metrics.latencyP95, "s"))}`);
+				const codes = Object.entries(metrics.statusCodes);
+				if (codes.length > 0) {
+					console.log();
+					console.log(chalk.dim("  Status HTTP:"));
+					for (const [code, count] of codes.sort(([a], [b]) => a.localeCompare(b))) console.log(`    ${statusColor$1(code)(code)}  ${formatCompact(count)}`);
+				}
+				console.log();
+			}
+			console.log(chalk.bold("  Recursos"));
 			console.log();
-			console.log(`  Requisições/min   ${chalk.bold(formatCompact(metrics.requestRate))}`);
-			console.log(`  Erros/min         ${rateColor(metrics.errorRate)(formatCompact(metrics.errorRate))}`);
-			console.log(`  Latência P95      ${chalk.bold(formatCompact(metrics.latencyP95, "s"))}`);
-			const codes = Object.entries(metrics.statusCodes);
-			if (codes.length > 0) {
+			console.log(`  ${"Restarts".padEnd(W)} ${chalk.bold(String(resource.restarts))}`);
+			console.log(`  ${"Uptime".padEnd(W)} ${chalk.bold(formatUptime(resource.uptimeSeconds))}`);
+			console.log(`  ${"OOM Events".padEnd(W)} ${resource.oomEvents > 0 ? chalk.red(String(resource.oomEvents)) : chalk.green("0")}`);
+			console.log(`  ${"CPU Throttle".padEnd(W)} ${resource.cpuThrottlePercent > 10 ? chalk.yellow(formatPercent(resource.cpuThrottlePercent)) : chalk.green(formatPercent(resource.cpuThrottlePercent))}`);
+			if (isDb && database) {
+				console.log();
+				console.log(chalk.bold("  Banco de Dados"));
 				console.log();
-				console.log(chalk.dim("  Status HTTP:"));
-				for (const [code, count] of codes.sort(([a], [b]) => a.localeCompare(b))) console.log(`    ${statusColor$1(code)(code)}  ${formatCompact(count)}`);
+				if (database.insightsEnabled) {
+					console.log(`  ${"Conexões Ativas".padEnd(W)} ${chalk.bold(String(database.activeConnections))}`);
+					console.log(`  ${"Conexões Total".padEnd(W)} ${chalk.bold(String(database.totalConnections))}`);
+					console.log(`  ${"Conexões Idle".padEnd(W)} ${chalk.bold(String(database.idleConnections))}`);
+					console.log(`  ${"Queries/s".padEnd(W)} ${chalk.bold(formatCompact(database.queriesPerSec))}`);
+					console.log(`  ${"Cache Hit Ratio".padEnd(W)} ${database.cacheHitRatio > .9 ? chalk.green(formatPercent(database.cacheHitRatio * 100)) : chalk.yellow(formatPercent(database.cacheHitRatio * 100))}`);
+					console.log(`  ${"Tamanho".padEnd(W)} ${chalk.bold(formatBytes(database.databaseSize))}`);
+				} else printInsightsHint();
 			}
 			if (metrics.grafanaDashboardUrl) {
 				console.log();
 				info(`Dashboard: ${chalk.underline(metrics.grafanaDashboardUrl)}`);
 			}
 			console.log();
+			console.log(chalk.dim("  Dicas:"));
+			console.log(chalk.dim(`    veloz metrics range              Sparklines ao longo do tempo`));
+			console.log(chalk.dim(`    veloz metrics list               Descobrir métricas disponíveis`));
+			console.log(chalk.dim(`    veloz metrics query '<consulta>'  Consulta MetricsQL personalizada`));
+			console.log(chalk.dim(`    veloz metrics query-help          Referência completa de MetricsQL`));
+			console.log();
 		}
-		return metrics;
+		const hints = [
+			"Use 'veloz metrics range' para sparklines ao longo do tempo.",
+			"Use 'veloz metrics list' para descobrir métricas disponíveis.",
+			"Use 'veloz metrics query <metricsql>' para consultas MetricsQL personalizadas.",
+			"Use 'veloz metrics labels' para descobrir labels e seus valores.",
+			"Use 'veloz metrics series <seletor>' para encontrar séries por seletor.",
+			"Use 'veloz metrics query-help' para referência completa de MetricsQL."
+		];
+		if (isDb && database && !database.insightsEnabled) hints.unshift("Ative insights para métricas detalhadas do banco: 'veloz db update <nome> --insights'.");
+		return {
+			...metrics,
+			resource,
+			database,
+			hint: hints.join("\n")
+		};
 	}
 });
 metricsGroup.command("range", {
 	description: "Exibir métricas em intervalo de tempo com sparklines",
 	middleware: [requireAuth],
 	options: z.object({
-		service: z.string().optional().describe("Filtrar por serviço"),
+		service: z.string().optional().describe("Filtrar por serviço ou banco de dados"),
 		range: z.enum([
 			"1h",
 			"6h",
@@ -3031,100 +3149,508 @@ metricsGroup.command("range", {
 	async run(c) {
 		const serviceId = await resolveServiceId(c.options.service);
 		const client = await getClient();
-		const data = await withSpinner({
-			text: `Carregando métricas (${c.options.range})...`,
-			fn: () => client.metrics.getServiceMetricsRange({
-				serviceId,
-				range: c.options.range
-			})
+		const isDb = isDatabaseService(c.options.service);
+		const range = c.options.range;
+		const { data, dbData } = await withSpinner({
+			text: `Carregando métricas (${range})...`,
+			fn: async () => {
+				const [data$1, dbData$1] = await Promise.all([client.metrics.getServiceMetricsRange({
+					serviceId,
+					range
+				}), isDb ? client.databaseInsights.getMetricsRange({
+					serviceId,
+					range
+				}) : null]);
+				return {
+					data: data$1,
+					dbData: dbData$1
+				};
+			}
 		});
 		if (process.stdout.isTTY) {
 			const W = 20;
-			const rangeLabel = chalk.dim(`(últimas ${c.options.range})`);
+			const rangeLabel = chalk.dim(`(últimas ${range})`);
 			console.log();
 			console.log(chalk.bold(`  Métricas ${rangeLabel}`));
 			console.log();
-			if (data.requestRate.length > 0) {
-				const v = seriesValues(data.requestRate);
-				console.log(`  ${"Req/min".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v)))}`);
-			}
-			if (data.latencyP95.length > 0) {
-				const v = seriesValues(data.latencyP95);
-				console.log(`  ${"Latência P95".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v), "s"))}`);
-			}
-			if (data.latencyP50.length > 0) {
-				const v = seriesValues(data.latencyP50);
-				console.log(`  ${"Latência P50".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v), "s"))}`);
+			if (!isDb) {
+				if (data.requestRate.length > 0) {
+					const v = seriesValues(data.requestRate);
+					console.log(`  ${"Req/min".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v)))}`);
+				}
+				if (data.latencyP95.length > 0) {
+					const v = seriesValues(data.latencyP95);
+					console.log(`  ${"Latência P95".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v), "s"))}`);
+				}
+				if (data.latencyP50.length > 0) {
+					const v = seriesValues(data.latencyP50);
+					console.log(`  ${"Latência P50".padEnd(W)} ${sparkline(v)}  ${chalk.bold(formatCompact(latestValue(v), "s"))}`);
+				}
 			}
 			for (const series of data.cpuUsage) printSparkline(`CPU (${series.label})`, labeledValues(series), "m", W);
 			for (const series of data.memoryUsage) printSparkline(`Memória (${series.label})`, labeledValues(series), "Mi", W);
 			if (data.networkIn.length > 0) printSparkline("Rede ↓", seriesValues(data.networkIn), "KB/s", W);
 			if (data.networkOut.length > 0) printSparkline("Rede ↑", seriesValues(data.networkOut), "KB/s", W);
+			if (isDb && dbData) if (dbData.insightsEnabled) {
+				console.log();
+				console.log(chalk.bold("  Banco de Dados"));
+				console.log();
+				if (dbData.activeConnections.length > 0) printSparkline("Conexões Ativas", seriesValues(dbData.activeConnections), "", W);
+				if (dbData.queriesPerSec.length > 0) printSparkline("Queries/s", seriesValues(dbData.queriesPerSec), "", W);
+				if (dbData.cacheHitRatio.length > 0) printSparkline("Cache Hit", seriesValues(dbData.cacheHitRatio).map((r) => r * 100), "%", W);
+			} else printInsightsHint();
+			console.log();
+		}
+		const hint = isDb && dbData && !dbData.insightsEnabled ? "Ative insights para métricas detalhadas do banco: 'veloz db update <nome> --insights'. Use 'veloz metrics query <metricsql>' para consultas personalizadas." : "Use 'veloz metrics query <metricsql>' para consultas MetricsQL personalizadas. Use 'veloz metrics list' para descobrir métricas disponíveis.";
+		return {
+			...data,
+			database: dbData,
+			hint
+		};
+	}
+});
+metricsGroup.command("query", {
+	description: "Executar consulta MetricsQL personalizada",
+	middleware: [requireAuth],
+	args: z.object({ query: z.string().describe("Consulta MetricsQL (ex: up, rate(http_requests[5m]))") }),
+	options: z.object({
+		service: z.string().optional().describe("Serviço para contexto de autenticação"),
+		start: z.string().optional().describe("Início do intervalo (ISO 8601, unix timestamp, ou relativo: 1h, 6h, 24h, 7d)"),
+		end: z.string().optional().describe("Fim do intervalo (padrão: agora)"),
+		step: z.string().optional().describe("Resolução (ex: 30s, 1m, 5m). Padrão: auto")
+	}),
+	output: z.object({
+		resultType: z.string(),
+		results: z.array(z.object({
+			metric: z.record(z.string(), z.string()),
+			values: z.array(z.object({
+				timestamp: z.number(),
+				value: z.number()
+			}))
+		}))
+	}),
+	async run(c) {
+		const client = await getClient();
+		let start = c.options.start;
+		if (start && /^\d+[smhdw]$/.test(start)) start = `-${start}`;
+		let step = c.options.step;
+		if (start && !step) {
+			const durationMatch = start.replace(/^-/, "").match(/^(\d+)([smhdw])$/);
+			if (durationMatch) {
+				const duration = parseInt(durationMatch[1], 10) * ({
+					s: 1,
+					m: 60,
+					h: 3600,
+					d: 86400,
+					w: 604800
+				}[durationMatch[2]] ?? 1);
+				if (duration <= 3600) step = "30s";
+				else if (duration <= 21600) step = "60s";
+				else if (duration <= 86400) step = "300s";
+				else step = "1800s";
+			} else step = "60s";
+		}
+		const result = await withSpinner({
+			text: "Executando consulta...",
+			fn: () => client.metrics.queryMetrics({
+				query: c.args.query,
+				start,
+				end: c.options.end,
+				step
+			})
+		});
+		if (process.stdout.isTTY) {
+			console.log();
+			if (result.results.length === 0) info("Nenhum resultado para esta consulta.");
+			else {
+				console.log(chalk.dim(`  Tipo: ${result.resultType}  |  ${result.results.length} série(s)`));
+				console.log();
+				for (const series of result.results) {
+					const labels = Object.entries(series.metric).map(([k, v]) => `${chalk.dim(k)}=${chalk.cyan(`"${v}"`)}`).join(" ");
+					if (series.values.length === 1) {
+						const val = series.values[0];
+						console.log(`  ${labels}  ${chalk.bold(formatCompact(val.value))}`);
+					} else if (series.values.length > 1) {
+						const values = series.values.map((point) => point.value);
+						const latest = latestValue(values);
+						console.log(`  ${labels}`);
+						console.log(`    ${sparkline(values)}  ${chalk.bold(formatCompact(latest))}`);
+					}
+				}
+			}
+			console.log();
+			info(`Execute ${chalk.bold("veloz metrics query-help")} para ver a referência completa de MetricsQL.`);
+			console.log();
+		}
+		return {
+			...result,
+			hint: "Use 'veloz metrics list' para descobrir métricas. Use 'veloz metrics labels --label <nome>' para ver valores de labels. Use 'veloz metrics series <seletor>' para encontrar séries. Use 'veloz metrics query-help' para referência completa de MetricsQL."
+		};
+	}
+});
+metricsGroup.command("list", {
+	description: "Listar nomes de métricas disponíveis",
+	middleware: [requireAuth],
+	options: z.object({
+		match: z.string().optional().describe("Filtrar por seletor (ex: \"{job=\\\"node\\\"}\", \"traefik_.*\")"),
+		limit: z.number().default(500).describe("Número máximo de resultados")
+	}),
+	output: z.object({ names: z.array(z.string()) }),
+	async run(c) {
+		const client = await getClient();
+		const result = await withSpinner({
+			text: "Listando métricas...",
+			fn: () => client.metrics.listMetricNames({
+				match: c.options.match,
+				limit: c.options.limit
+			})
+		});
+		if (process.stdout.isTTY) {
+			console.log();
+			if (result.names.length === 0) info("Nenhuma métrica encontrada.");
+			else {
+				console.log(chalk.dim(`  ${result.names.length} métrica(s) encontrada(s)`));
+				console.log();
+				for (const name of result.names) console.log(`  ${name}`);
+			}
+			console.log();
+		}
+		return {
+			...result,
+			hint: "Use 'veloz metrics labels --label <nome>' para ver valores de um label. Use 'veloz metrics series <nome_da_metrica>' para encontrar séries. Use 'veloz metrics query <metricsql>' para consultar dados."
+		};
+	}
+});
+metricsGroup.command("labels", {
+	description: "Listar labels disponíveis ou valores de um label específico",
+	middleware: [requireAuth],
+	options: z.object({
+		label: z.string().optional().describe("Nome do label para listar valores (ex: pod, namespace)"),
+		match: z.string().optional().describe("Filtrar por seletor de métrica (ex: \"container_cpu_usage_seconds_total\")"),
+		limit: z.number().default(500).describe("Número máximo de resultados")
+	}),
+	output: z.object({
+		values: z.array(z.string()),
+		type: z.string()
+	}),
+	async run(c) {
+		const client = await getClient();
+		const result = await withSpinner({
+			text: c.options.label ? `Listando valores de "${c.options.label}"...` : "Listando labels...",
+			fn: () => client.metrics.listLabels({
+				label: c.options.label,
+				match: c.options.match,
+				limit: c.options.limit
+			})
+		});
+		if (process.stdout.isTTY) {
+			console.log();
+			if (result.values.length === 0) info("Nenhum resultado encontrado.");
+			else {
+				const heading = result.type === "names" ? "Labels disponíveis" : `Valores de "${result.type}"`;
+				console.log(chalk.dim(`  ${heading} (${result.values.length})`));
+				console.log();
+				for (const val of result.values) console.log(`  ${val}`);
+			}
+			console.log();
+		}
+		return {
+			...result,
+			hint: "Use 'veloz metrics series <nome_da_metrica>' para encontrar séries com labels. Use 'veloz metrics query <metricsql>' para consultar dados. Use 'veloz metrics query-help' para referência MetricsQL."
+		};
+	}
+});
+metricsGroup.command("series", {
+	description: "Encontrar séries de métricas por seletor",
+	middleware: [requireAuth],
+	args: z.object({ match: z.string().describe("Seletor de séries (ex: \"traefik_service_requests_total\", '{__name__=~\"pg_.*\"}')") }),
+	options: z.object({ limit: z.number().default(100).describe("Número máximo de séries") }),
+	output: z.object({
+		series: z.array(z.record(z.string(), z.string())),
+		count: z.number()
+	}),
+	async run(c) {
+		const client = await getClient();
+		const result = await withSpinner({
+			text: "Buscando séries...",
+			fn: () => client.metrics.findSeries({
+				match: c.args.match,
+				limit: c.options.limit
+			})
+		});
+		if (process.stdout.isTTY) {
+			console.log();
+			if (result.series.length === 0) info("Nenhuma série encontrada para este seletor.");
+			else {
+				console.log(chalk.dim(`  ${result.count} série(s) encontrada(s)`));
+				console.log();
+				for (const s of result.series) {
+					const name = s.__name__ ?? "";
+					const labels = Object.entries(s).filter(([k]) => k !== "__name__").map(([k, v]) => `${chalk.dim(k)}=${chalk.cyan(`"${v}"`)}`).join(", ");
+					console.log(`  ${chalk.bold(name)}${labels ? ` {${labels}}` : ""}`);
+				}
+			}
 			console.log();
 		}
-		return data;
+		return {
+			...result,
+			hint: "Use 'veloz metrics query <metricsql>' para consultar os dados dessas séries. Use 'veloz metrics labels --label <nome>' para ver valores de um label específico."
+		};
 	}
 });
-const METRICS_HELP_SECTIONS = [
+const QUERY_HELP_SECTIONS$1 = [
 	{
-		title: "Métricas disponíveis",
-		content: `  metrics show                Snapshot instantâneo do serviço
-  metrics range               Séries temporais com sparklines no terminal`
+		title: "Comandos disponíveis",
+		content: `  metrics show                     Snapshot instantâneo do serviço
+  metrics range                    Séries temporais com sparklines
+  metrics query <consulta>         Consulta MetricsQL personalizada
+  metrics list                     Listar nomes de métricas disponíveis
+  metrics labels                   Listar labels ou seus valores
+  metrics series <seletor>         Encontrar séries por seletor
+  metrics query-help               Esta referência`
 	},
 	{
 		title: "metrics show — campos retornados",
-		content: `  requestRate                Requisições por minuto (req/min)
-  errorRate                  Erros 5xx por minuto
-  latencyP95                 Latência percentil 95 (segundos)
-  statusCodes                Mapa de código HTTP → contagem (ex: {"200": 1500, "404": 12})
-  grafanaDashboardUrl        URL do dashboard Grafana (pode ser null)`
+		content: `  Tráfego (serviços web/worker):
+    requestRate                    Requisições por minuto (req/min)
+    errorRate                      Erros 5xx por minuto
+    latencyP95                     Latência percentil 95 (segundos)
+    statusCodes                    Mapa de código HTTP → contagem
+
+  Recursos (todos os serviços):
+    restarts                       Número de restarts
+    uptimeSeconds                  Tempo de atividade em segundos
+    oomEvents                      Eventos de falta de memória (OOM)
+    cpuThrottlePercent             Porcentagem de throttle de CPU
+
+  Banco de dados (requer insights ativado):
+    activeConnections              Conexões ativas
+    totalConnections               Total de conexões
+    idleConnections                Conexões ociosas
+    queriesPerSec                  Consultas por segundo
+    cacheHitRatio                  Taxa de acerto do cache (0-1)
+    databaseSize                   Tamanho do banco em bytes`
 	},
 	{
 		title: "metrics range — séries temporais retornadas",
 		content: `  Tráfego (Traefik):
-    requestRate              [{timestamp, value}]  — req/min ao longo do tempo
-    latencyP50               [{timestamp, value}]  — latência mediana
-    latencyP95               [{timestamp, value}]  — latência P95
-    latencyP99               [{timestamp, value}]  — latência P99
-    statusCodes              [{label, data}]       — série por código HTTP
+    requestRate                    [{timestamp, value}]  — req/min
+    latencyP50 / P95 / P99         [{timestamp, value}]  — latência
+    statusCodes                    [{label, data}]       — por código HTTP
 
   Recursos (por instância):
-    cpuUsage                 [{label, data}]       — millicores por instância
-    memoryUsage              [{label, data}]       — MiB por instância
-    networkIn                [{timestamp, value}]  — KB/s entrada
-    networkOut               [{timestamp, value}]  — KB/s saída`
+    cpuUsage                       [{label, data}]       — millicores
+    memoryUsage                    [{label, data}]       — MiB
+    networkIn / networkOut         [{timestamp, value}]  — KB/s
+
+  Banco de dados (requer insights):
+    activeConnections              [{timestamp, value}]  — conexões ativas
+    queriesPerSec                  [{timestamp, value}]  — queries/s
+    cacheHitRatio                  [{timestamp, value}]  — taxa de cache`
+	},
+	{
+		title: "metrics query — consultas MetricsQL",
+		content: `  Consulta instantânea (sem --start):
+    veloz metrics query "up"
+    veloz metrics query 'sum(rate(traefik_service_requests_total[5m]))'
+
+  Consulta com intervalo (range query):
+    veloz metrics query "rate(traefik_service_requests_total[5m])" --start 1h
+    veloz metrics query "container_memory_working_set_bytes" --start 6h --step 5m
+    veloz metrics query "pg_stat_activity_count" --start 24h`
+	},
+	{
+		title: "Seletores de métricas",
+		content: `  nome_da_metrica                  Seleciona todas as séries
+  nome{label="valor"}              Filtro por label exato
+  nome{label=~"regex"}             Filtro por regex
+  nome{label!="valor"}             Exclusão por valor
+  nome{label!~"regex"}             Exclusão por regex
+  nome{a="x", b="y"}              Múltiplos filtros (AND)`
+	},
+	{
+		title: "Vetores de intervalo (range vectors)",
+		content: `  metrica[5m]                      Últimos 5 minutos de amostras
+  metrica[1h]                      Última hora
+  metrica[1d]                      Último dia
+  metrica[5m] offset 1h            Amostras de 1h atrás`
+	},
+	{
+		title: "Funções de taxa e incremento",
+		content: `  rate(metrica[5m])                Taxa por segundo (para counters)
+  irate(metrica[5m])               Taxa instantânea (últimas 2 amostras)
+  increase(metrica[5m])            Incremento total no período
+  delta(metrica[5m])               Diferença (para gauges)
+  deriv(metrica[5m])               Derivada (para gauges)`
+	},
+	{
+		title: "Funções de agregação",
+		content: `  sum(metrica) by (label)          Soma agrupada por label
+  avg(metrica) by (label)          Média agrupada
+  min(metrica) by (label)          Mínimo
+  max(metrica) by (label)          Máximo
+  count(metrica) by (label)        Contagem
+  topk(5, metrica)                 Top 5 séries por valor
+  bottomk(3, metrica)              Bottom 3 séries
+  quantile(0.95, metrica)          Percentil 95 entre séries`
+	},
+	{
+		title: "Funções de rollup (over time)",
+		content: `  avg_over_time(m[5m])             Média no período
+  max_over_time(m[5m])             Máximo no período
+  min_over_time(m[5m])             Mínimo no período
+  sum_over_time(m[5m])             Soma no período
+  count_over_time(m[5m])           Contagem no período
+  quantile_over_time(0.95, m[5m])  Percentil no período
+  stddev_over_time(m[5m])          Desvio padrão no período
+  last_over_time(m[5m])            Último valor no período`
+	},
+	{
+		title: "Funções de histograma",
+		content: `  histogram_quantile(0.95, sum(rate(metrica_bucket[5m])) by (le))
+    Calcula percentil 95 de histograma (ex: latência P95)
+
+  histogram_quantile(0.50, ...)    Mediana (P50)
+  histogram_quantile(0.99, ...)    P99`
+	},
+	{
+		title: "Operadores e funções matemáticas",
+		content: `  Aritméticos:  + - * / % ^
+  Comparação:   == != > < >= <=
+  Lógicos:      and or unless
+  Funções:      abs() ceil() floor() round()
+                clamp(m, min, max) clamp_min(m, min) clamp_max(m, max)
+                ln() log2() log10() exp() sqrt()`
+	},
+	{
+		title: "MetricsQL — extensões sobre PromQL",
+		content: `  MetricsQL é compatível com PromQL, com extensões extras:
+
+  range_median(m[5m])              Mediana no intervalo
+  range_avg(m[5m])                 Média no intervalo (alias de avg_over_time)
+  share_gt_over_time(m[5m], 100)   % de amostras acima de 100
+  count_gt_over_time(m[5m], 100)   Contagem de amostras acima de 100
+  duration_over_time(m[5m], max)   Duração máxima contínua
+  lag(m[5m])                       Tempo desde última amostra
+  lifetime(m[5m])                  Duração total da série
+  scrape_interval(m[5m])           Intervalo médio entre amostras`
 	},
 	{
-		title: "Intervalos de tempo (--range)",
-		content: `  1h                         Última hora (padrão)
-  6h                         Últimas 6 horas
-  24h                        Últimas 24 horas
-  7d                         Últimos 7 dias`
+		title: "Métricas disponíveis na Veloz",
+		content: `  Tráfego (Traefik — serviços web):
+    traefik_service_requests_total          Requisições HTTP (counter)
+    traefik_service_request_duration_seconds_bucket  Latência (histogram)
+
+  Recursos (cAdvisor — todos os serviços):
+    container_cpu_usage_seconds_total       CPU usado (counter)
+    container_memory_working_set_bytes      Memória em uso (gauge)
+    container_network_receive_bytes_total   Rede entrada (counter)
+    container_network_transmit_bytes_total  Rede saída (counter)
+    container_cpu_cfs_throttled_periods_total  Períodos com throttle
+    container_cpu_cfs_periods_total         Total de períodos CFS
+    container_threads                       Threads por container
+    container_file_descriptors              File descriptors abertos
+    container_oom_events_total              Eventos OOM (counter)
+
+  Kubernetes:
+    kube_pod_container_status_restarts_total  Restarts (counter)
+    container_start_time_seconds             Timestamp de início
+
+  Banco de dados (PostgreSQL — requer insights):
+    pg_stat_activity_count                  Conexões por estado
+    pg_stat_database_xact_commit            Transactions commit
+    pg_stat_database_xact_rollback          Transactions rollback
+    pg_stat_database_blks_hit               Blocos do cache (buffer)
+    pg_stat_database_blks_read              Blocos lidos do disco
+    pg_database_size_bytes                  Tamanho do banco
+
+  Plataforma (métricas internas):
+    veloz_rpc_requests_total                Chamadas RPC (counter)
+    veloz_rpc_request_duration_seconds      Latência RPC (histogram)
+    veloz_http_requests_total               Requisições HTTP internas
+    veloz_job_total                         Jobs processados (counter)
+    veloz_job_duration_seconds              Duração de jobs (histogram)
+    veloz_job_active                        Jobs ativos (gauge)
+    veloz_dlq_depth                         Profundidade da DLQ (gauge)`
 	},
 	{
-		title: "Tipos de dados",
-		content: `  TimeSeriesPoint            { timestamp: number, value: number }
-  LabeledTimeSeries          { label: string, data: TimeSeriesPoint[] }
-                             label identifica a instância (ex: "web-abc12")`
+		title: "Descoberta de métricas (list, labels, series)",
+		content: `  Listar todas as métricas:
+    veloz metrics list
+    veloz metrics list --match '{job="node"}'
+
+  Listar labels disponíveis:
+    veloz metrics labels
+    veloz metrics labels --match "container_cpu_usage_seconds_total"
+
+  Listar valores de um label:
+    veloz metrics labels --label pod
+    veloz metrics labels --label namespace
+    veloz metrics labels --label state --match "pg_stat_activity_count"
+
+  Encontrar séries:
+    veloz metrics series "traefik_service_requests_total"
+    veloz metrics series '{__name__=~"pg_.*"}'
+    veloz metrics series '{namespace="proj-meu-projeto"}'`
 	},
 	{
-		title: "Exemplos de uso",
-		content: `  veloz metrics show                          Métricas atuais (serviço padrão)
-  veloz metrics show --service api             Métricas da API
-  veloz metrics range                          Sparklines última hora
-  veloz metrics range --range 24h              Sparklines últimas 24h
-  veloz metrics range --range 7d --service web Sparklines 7 dias do frontend`
+		title: "Exemplos práticos",
+		content: `  Tráfego:
+    veloz metrics query 'sum(rate(traefik_service_requests_total[5m])) * 60'
+    veloz metrics query 'histogram_quantile(0.95, sum(rate(traefik_service_request_duration_seconds_bucket[5m])) by (le))'
+    veloz metrics query 'sum(rate(traefik_service_requests_total[5m])) by (code) * 60'
+
+  Recursos:
+    veloz metrics query 'sum by (pod) (rate(container_cpu_usage_seconds_total[5m])) * 1000'
+    veloz metrics query 'sum by (pod) (container_memory_working_set_bytes) / 1024 / 1024'
+    veloz metrics query 'sum(container_oom_events_total) by (pod)' --start 24h
+
+  Banco de dados:
+    veloz metrics query 'pg_stat_activity_count{state="active"}' --start 1h
+    veloz metrics query 'rate(pg_stat_database_xact_commit[5m]) + rate(pg_stat_database_xact_rollback[5m])' --start 6h
+    veloz metrics query 'pg_database_size_bytes' --start 7d
+
+  Range queries com sparklines:
+    veloz metrics query 'rate(traefik_service_requests_total[5m]) * 60' --start 1h
+    veloz metrics query 'container_memory_working_set_bytes / 1024 / 1024' --start 24h --step 5m
+
+  Referência completa:
+    https://docs.victoriametrics.com/metricsql/`
 	},
 	{
-		title: "Workflow para agentes IA",
-		content: `  1. veloz metrics show          → verificar saúde geral
-  2. Se errorRate > 0:
-     veloz logs search "error"   → investigar causa dos erros
-  3. veloz metrics range --range 1h → verificar tendência recente
-  4. Se latencyP95 alto:
-     veloz metrics range --range 24h → comparar com padrão do dia`
+		title: "Dica: insights para bancos de dados",
+		content: `  As métricas pg_stat_* e pg_database_* requerem insights ativado.
+  Para ativar: veloz db update <nome> --insights
+
+  Após ativar, o exporter coleta métricas do PostgreSQL
+  automaticamente. As métricas ficam disponíveis em ~2 minutos.`
 	}
 ];
+metricsGroup.command("query-help", {
+	description: "Referência de MetricsQL para consultas de métricas",
+	output: z.object({ sections: z.array(z.object({
+		title: z.string(),
+		content: z.string()
+	})) }),
+	async run() {
+		if (process.stdout.isTTY) {
+			console.log();
+			console.log(chalk.bold("  Referência MetricsQL"));
+			console.log(chalk.dim("  Sintaxe de consulta para métricas VictoriaMetrics"));
+			console.log();
+			for (const section of QUERY_HELP_SECTIONS$1) {
+				console.log(chalk.bold.underline(`  ${section.title}`));
+				console.log();
+				console.log(section.content);
+				console.log();
+			}
+			console.log(chalk.dim("  Uso: veloz metrics query '<consulta>' [--start 1h|6h|24h|7d] [--step 30s|1m|5m]"));
+			console.log(chalk.dim("  Docs: https://docs.victoriametrics.com/metricsql/"));
+			console.log();
+		}
+		return { sections: QUERY_HELP_SECTIONS$1 };
+	}
+});
 metricsGroup.command("help", {
 	description: "Referência de métricas disponíveis e seus campos",
 	output: z.object({ sections: z.array(z.object({
@@ -3135,18 +3661,18 @@ metricsGroup.command("help", {
 		if (process.stdout.isTTY) {
 			console.log();
 			console.log(chalk.bold("  Referência de Métricas"));
-			console.log(chalk.dim("  Dados disponíveis via metrics show e metrics range"));
+			console.log(chalk.dim("  Dica: use 'veloz metrics query-help' para a referência completa de MetricsQL"));
 			console.log();
-			for (const section of METRICS_HELP_SECTIONS) {
+			for (const section of QUERY_HELP_SECTIONS$1.slice(0, 4)) {
 				console.log(chalk.bold.underline(`  ${section.title}`));
 				console.log();
 				console.log(section.content);
 				console.log();
 			}
-			console.log(chalk.dim("  Uso: veloz metrics show [--service NOME] | veloz metrics range [--range 1h|6h|24h|7d]"));
+			console.log(chalk.dim("  Para referência completa de MetricsQL: veloz metrics query-help"));
 			console.log();
 		}
-		return { sections: METRICS_HELP_SECTIONS };
+		return { sections: QUERY_HELP_SECTIONS$1.slice(0, 4) };
 	}
 });
 
@@ -3233,11 +3759,13 @@ logsGroup.command("show", {
 			spin.stop();
 			info("Streaming de logs ativo. Pressione Ctrl+C para sair.\n");
 			const lines$1 = await streamFollow(services, maxNameLen, tailLines);
-			return lines$1.length > 0 ? lines$1.join("\n") : "Nenhum log encontrado.";
+			const hint$1 = "\nDica: para consultas avançadas (filtros, regex, agregações), use `veloz logs search <consulta>`. Execute `veloz logs query-help` para ver a referência completa de sintaxe LogsQL.";
+			return lines$1.length > 0 ? lines$1.join("\n") + hint$1 : "Nenhum log encontrado." + hint$1;
 		}
 		spin.stop();
 		const lines = await fetchRecent(services, maxNameLen, tailLines);
-		return lines.length > 0 ? lines.join("\n") : "Nenhum log encontrado.";
+		const hint = "\nDica: para consultas avançadas (filtros, regex, agregações), use `veloz logs search <consulta>`. Execute `veloz logs query-help` para ver a referência completa de sintaxe LogsQL.";
+		return lines.length > 0 ? lines.join("\n") + hint : "Nenhum log encontrado." + hint;
 	}
 });
 logsGroup.command("search", {
@@ -3259,14 +3787,21 @@ logsGroup.command("search", {
 	})),
 	async run(c) {
 		const serviceId = await resolveServiceId(c.options.service);
-		const entries = await (await getClient()).logs.search({
-			serviceId,
-			query: c.args.query,
-			start: c.options.start,
-			end: c.options.end,
-			limit: c.options.limit,
-			deploymentId: c.options.deployment
-		});
+		const client = await getClient();
+		let entries;
+		try {
+			entries = await client.logs.search({
+				serviceId,
+				query: c.args.query,
+				start: c.options.start,
+				end: c.options.end,
+				limit: c.options.limit,
+				deploymentId: c.options.deployment
+			});
+		} catch (err) {
+			warn(err instanceof Error ? err.message : "Erro ao pesquisar logs");
+			return [];
+		}
 		if (process.stdout.isTTY) if (entries.length === 0) info("Nenhum log encontrado para essa consulta.");
 		else {
 			console.log();
@@ -4748,7 +5283,7 @@ const LOGO_LINES = [
 ];
 const BRAND_COLOR = "#FF4D00";
 function getVersion() {
-	return "0.0.0-beta.24";
+	return "0.0.0-beta.26";
 }
 function printBanner(subtitle) {
 	const version = getVersion();
@@ -4975,7 +5510,14 @@ async function deployMultipleServices(services, options) {
 		urls: []
 	}));
 	output.printSummary(successful, failed);
-	if (successful.length > 0) output.printFollowUp();
+	if (successful.length > 0) {
+		let hasGithub = false;
+		try {
+			const projectId = services[0]?.projectId;
+			if (projectId) hasGithub = !!(await client.projects.get({ projectId })).githubInstallationId;
+		} catch {}
+		output.printFollowUp({ hasGithub });
+	}
 	const results = [];
 	for (const [serviceId, progress] of progressMap) results.push({
 		deploymentId: deploymentIdMap.get(serviceId) ?? "",
@@ -5088,7 +5630,7 @@ var TtyOutput = class {
 			}
 		}
 	}
-	printFollowUp() {
+	printFollowUp(_context) {
 		console.log(chalk.cyan("\nℹ Use 'veloz logs -f' para acompanhar os logs de execução."));
 		console.log(chalk.dim("  Use 'veloz builds list' para ver o histórico de builds."));
 	}
@@ -5144,7 +5686,7 @@ var PlainOutput = class {
 			}
 		}
 	}
-	printFollowUp() {
+	printFollowUp(_context) {
 		process.stdout.write("Use 'veloz logs -f' para acompanhar os logs de execução.\n");
 		process.stdout.write("Use 'veloz builds list' para ver o histórico de builds.\n");
 	}
@@ -5204,7 +5746,7 @@ var GhaOutput = class {
 			}
 		}
 	}
-	printFollowUp() {
+	printFollowUp(_context) {
 		process.stdout.write("Use 'veloz logs -f' para acompanhar os logs de execução.\n");
 		process.stdout.write("Use 'veloz builds list' para ver o histórico de builds.\n");
 	}
@@ -5259,9 +5801,10 @@ var McpOutput = class {
 			}
 		}
 	}
-	printFollowUp() {
+	printFollowUp(context) {
 		log("[deploy] Use 'veloz logs -f' para acompanhar os logs de execução.");
 		log("[deploy] Use 'veloz builds list' para ver o histórico de builds.");
+		if (context?.hasGithub) log("[deploy] Dica: este projeto tem deploys automaticos via GitHub configurados. Pushes para o branch configurado fazem deploy automaticamente — não é necessário rodar 'veloz deploy' manualmente.");
 	}
 };
 
@@ -5794,7 +6337,7 @@ async function autoUpdate() {
 	if (process.env.VELOZ_MCP === "true") return;
 	const pm = detectPackageManager();
 	if (!pm) return;
-	const currentVersion = "0.0.0-beta.24";
+	const currentVersion = "0.0.0-beta.26";
 	const latestVersion = await fetchLatestVersion();
 	if (!latestVersion || latestVersion === currentVersion) return;
 	const installCmd = getInstallCommand(pm, latestVersion);
@@ -5921,7 +6464,16 @@ async function provisionDatabases(config, opts) {
 async function updateDatabaseResources(client, key, dbConfig, existing, serviceId, isLive) {
 	const desiredSize = dbConfig.size;
 	if (!desiredSize) return;
-	if ((existing.size ?? resolveDatabaseSize(existing.cpuLimit, existing.memoryLimit, existing.engine)) === desiredSize) return;
+	const currentSize = existing.size ?? resolveDatabaseSize(existing.cpuLimit, existing.memoryLimit, existing.engine);
+	if (currentSize === desiredSize) return;
+	if (currentSize) {
+		const currentRank = getDatabaseSizeRank(currentSize, existing.engine);
+		const desiredRank = getDatabaseSizeRank(desiredSize, existing.engine);
+		if (desiredRank >= 0 && currentRank >= 0 && desiredRank < currentRank) {
+			info(`Banco de dados "${key}" já está em ${DATABASE_SIZES[currentSize]?.label ?? currentSize} — tamanho não pode ser reduzido via deploy.`);
+			return;
+		}
+	}
 	if (!isLive) {
 		warn(`Banco de dados "${key}" não está LIVE — não é possível alterar recursos agora.`);
 		return;
@@ -6111,13 +6663,13 @@ async function findServicesFromConfig() {
 	if (missingIds.length > 0 && config.project.id) {
 		const client = await getClient();
 		const remoteServicesByProject = /* @__PURE__ */ new Map();
-		async function getRemoteServices(pid) {
+		const getRemoteServices = async (pid) => {
 			const cached = remoteServicesByProject.get(pid);
 			if (cached) return cached;
 			const services$1 = await withRetry(() => client.services.list({ projectId: pid }));
 			remoteServicesByProject.set(pid, services$1);
 			return services$1;
-		}
+		};
 		let configUpdated = false;
 		for (const [key, serviceConfig] of missingIds) {
 			const effectiveProjectId = serviceConfig.projectId ?? config.project.id;
@@ -7407,7 +7959,7 @@ async function pruneRemovedEntries(config, existingConfig, services, databases)
 //#region src/index.ts
 if (process.argv.includes("--mcp")) process.env.VELOZ_MCP = "true";
 const cli = Cli.create("veloz", {
-	version: "0.0.0-beta.24",
+	version: "0.0.0-beta.26",
 	description: "CLI da plataforma Veloz — deploy rápido para o Brasil",
 	env: z.object({ VELOZ_ENV: z.string().optional().describe("Ambiente alvo (ex: preview, staging)") })
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onveloz",
-  "version": "0.0.0-beta.24",
+  "version": "0.0.0-beta.26",
   "description": "CLI da plataforma Veloz — deploy rápido para o Brasil",
   "keywords": [
     "brasil",