feat(errors): PRO-UX.1 + PRO-UX.2 — Pro CLI error UX bridge + root-cause fix #775
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,83 @@ | ||
| // PRO-UX.1 / PRO-UX.2 — Pro-specific error registry for the AIOX Pro CLI. | ||
| // Extends the canonical error-governance infra (EPIC-AIOX-ERROR-GOVERNANCE): | ||
| // reuses AIOXError + ErrorRegistry, maps to EXISTING ErrorCategory values | ||
| // (no new categories — constants.js is Object.freeze), and mirrors the | ||
| // license-server ErrorCodes (no AIOX_ prefix — deliberate, validated by the | ||
| // /^[A-Z0-9_]+$/ regex in ErrorRegistry._normalizeDefinition). | ||
| // | ||
| // userMessage holds the warm G3-approved PT-BR copy (fallback when the server | ||
| // envelope omits message_pt). recovery holds actionable PT-BR steps. | ||
|
|
||
| const { ErrorRegistry } = require('./error-registry'); | ||
| const { ErrorCategory, ErrorSeverity } = require('./constants'); | ||
|
|
||
| const PRO_ERROR_DEFINITIONS = Object.freeze([ | ||
| { | ||
| code: 'SEAT_LIMIT_EXCEEDED', | ||
| category: ErrorCategory.PERMISSION, // license-server "auth says no" → permission | ||
| severity: ErrorSeverity.ERROR, | ||
| retryable: false, | ||
| exitCode: 13, | ||
| userMessage: | ||
| 'Opa! Você já está usando o Pro no número máximo de máquinas. Pega o código de suporte aqui embaixo e fala com a gente que a gente libera rapidinho.', | ||
| recovery: [ | ||
| 'Pega o código de suporte abaixo', | ||
| 'Cola no chat com o suporte', | ||
| 'Depois que liberarem, roda o comando de instalação de novo', | ||
| ], | ||
| }, | ||
| { | ||
| code: 'NOT_A_BUYER', | ||
| category: ErrorCategory.PERMISSION, | ||
| severity: ErrorSeverity.ERROR, | ||
| retryable: false, | ||
| exitCode: 13, | ||
| userMessage: | ||
| 'Hmm, sua licença Pro não está ativa no momento. Pega o código de suporte aqui embaixo e fala com a gente que resolvemos rapidinho.', | ||
| recovery: [ | ||
| 'Pega o código de suporte abaixo', | ||
| 'Cola no chat com o suporte', | ||
| 'Aguarda a verificação da sua compra', | ||
| ], | ||
| }, | ||
| { | ||
| code: 'REVOKED_KEY', | ||
| category: ErrorCategory.PERMISSION, | ||
| severity: ErrorSeverity.ERROR, | ||
| retryable: false, | ||
| exitCode: 13, | ||
| userMessage: | ||
| 'Hmm, sua licença Pro não está ativa no momento. Pega o código de suporte aqui embaixo e fala com a gente que a gente verifica pra você.', | ||
| recovery: [ | ||
| 'Pega o código de suporte abaixo', | ||
| 'Cola no chat com o suporte', | ||
| 'Aguarda o retorno do financeiro', | ||
| ], | ||
| }, | ||
| { | ||
| code: 'RATE_LIMITED', | ||
| category: ErrorCategory.NETWORK, // throttling → network layer | ||
| severity: ErrorSeverity.WARNING, | ||
| retryable: true, | ||
| userMessage: | ||
| 'Calma! Foram muitas tentativas em pouco tempo. Espera uns minutinhos e tenta de novo.', | ||
| recovery: ['Aguarda 5 minutos', 'Tenta o comando de novo'], | ||
| }, | ||
| { | ||
| code: 'PRO_ARTIFACT_UNAVAILABLE', | ||
| category: ErrorCategory.EXTERNAL_EXECUTOR, // npm/tarball fetch → external executor | ||
| severity: ErrorSeverity.ERROR, | ||
| retryable: true, | ||
| userMessage: | ||
| 'Tivemos um probleminha pra baixar o componente Pro. Limpa o cache e tenta de novo em alguns minutos que deve rolar.', | ||
| recovery: [ | ||
| 'Aguarda 5 minutos (o servidor pode estar reiniciando)', | ||
| 'Roda `aiox install --recover-cache` para limpar o cache local', | ||
| 'Tenta de novo', | ||
| ], | ||
| }, | ||
| ]); | ||
|
|
||
| const proErrorRegistry = new ErrorRegistry(PRO_ERROR_DEFINITIONS); | ||
|
|
||
| module.exports = { proErrorRegistry, PRO_ERROR_DEFINITIONS }; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| // PRO-UX.1 — bridges the license-server error envelope into a canonical | ||
| // AIOXError, using the Pro-specific registry with graceful fallback. | ||
| // | ||
| // 3-tier message fallback: envelope.message_pt → registry.userMessage → | ||
| // envelope.message (server EN technical). Envelopes without the PRO-16 fields | ||
| // (older server) still produce a valid AIOXError via the registry. | ||
|
|
||
| const { AIOXError, defaultErrorRegistry } = require('../../../.aiox-core/core/errors'); | ||
| const { proErrorRegistry } = require('../../../.aiox-core/core/errors/pro-error-registry'); | ||
|
Comment on lines
+8
to
+9
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win Switch to absolute imports in the bridge module. Please replace these relative imports with absolute paths per repository standards. As per coding guidelines, 🤖 Prompt for AI Agents |
||
|
|
||
| const DEFAULT_CODE = 'AIOX_UNKNOWN_ERROR'; | ||
|
|
||
| /** | ||
| * @param {object} envelope - { error: { code, message, message_pt?, recovery_hint?, support_code?, details? } } | ||
| * @param {object} [options] - { httpStatus?: number } | ||
| * @returns {AIOXError} | ||
| */ | ||
| function parseEnvelopeToAIOXError(envelope, options = {}) { | ||
| const httpStatus = options.httpStatus; | ||
| const errorBody = envelope && typeof envelope === 'object' ? envelope.error : null; | ||
|
|
||
| if (!errorBody || typeof errorBody !== 'object' || !errorBody.code) { | ||
| return new AIOXError('Erro inesperado ao falar com o servidor.', { | ||
| code: DEFAULT_CODE, | ||
| metadata: { httpStatus, malformedEnvelope: true }, | ||
| }); | ||
| } | ||
|
|
||
| const code = errorBody.code; | ||
|
|
||
| // Tier lookup: Pro registry → default registry → unknown fallback. | ||
| let definition = null; | ||
| if (proErrorRegistry.has(code)) { | ||
| definition = proErrorRegistry.lookup(code); | ||
| } else if (defaultErrorRegistry.has(code)) { | ||
| definition = defaultErrorRegistry.lookup(code); | ||
| } else { | ||
| definition = defaultErrorRegistry.lookup(DEFAULT_CODE); | ||
| } | ||
|
|
||
| // 3-tier message fallback. | ||
| const userMessage = | ||
| errorBody.message_pt || | ||
| definition.userMessage || | ||
| errorBody.message || | ||
| 'Erro inesperado.'; | ||
|
|
||
| return new AIOXError(userMessage, { | ||
| code, | ||
| category: definition.category, | ||
| severity: definition.severity, | ||
| retryable: definition.retryable, | ||
| recovery: definition.recovery, | ||
| exitCode: definition.exitCode, | ||
| userMessage, | ||
| metadata: { | ||
| support_code: errorBody.support_code, | ||
| recovery_hint: errorBody.recovery_hint, | ||
| serverMessage: errorBody.message, | ||
| serverDetails: errorBody.details, | ||
| httpStatus, | ||
| }, | ||
| }); | ||
| } | ||
|
|
||
| module.exports = { parseEnvelopeToAIOXError }; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| // PRO-UX.2 — conditional recovery actions keyed by recovery_hint. | ||
| // OS-aware cache cleanup (PowerShell vs bash) — fixes the exact failure mode | ||
| // from the anchor incident (Robert ran bash `find/rm` in PowerShell). | ||
|
|
||
| /** | ||
| * Returns the cache-cleanup commands appropriate for the current OS. | ||
| * Windows → PowerShell; macOS/Linux → bash. | ||
| * @param {string} [platform] - defaults to process.platform (injectable for tests) | ||
| * @returns {string[]} | ||
| */ | ||
| function getCacheCleanCommands(platform = process.platform) { | ||
| if (platform === 'win32') { | ||
| return [ | ||
| 'Get-ChildItem -Path . -Recurse -Filter "pro" -Directory -ErrorAction SilentlyContinue | Where-Object { $_.FullName -match "node_modules\\\\@aiox-squads\\\\pro$" } | Remove-Item -Recurse -Force', | ||
| 'Remove-Item -Recurse -Force $env:USERPROFILE\\.npm\\_npx -ErrorAction SilentlyContinue', | ||
| ]; | ||
| } | ||
| // darwin / linux | ||
| return [ | ||
| 'find . -maxdepth 5 -path "*/node_modules/@aiox-squads/pro" -type d 2>/dev/null -exec rm -rf {} + 2>/dev/null', | ||
| 'rm -rf ~/.npm/_npx 2>/dev/null', | ||
| ]; | ||
| } | ||
|
|
||
| /** | ||
| * Dispatches a recovery action based on recovery_hint. | ||
| * Returns { action, commands?, waitSeconds? } describing what the CLI should do. | ||
| * Pure/declarative — the CLI shell decides whether to auto-run or just print. | ||
| * | ||
| * @param {string} recoveryHint | ||
| * @param {object} [context] - { platform?, waitSeconds? } | ||
| */ | ||
| function planRecoveryAction(recoveryHint, context = {}) { | ||
| switch (recoveryHint) { | ||
| case 'wait_and_retry': | ||
| return { action: 'wait', waitSeconds: context.waitSeconds || 300 }; | ||
| case 'retry_install_cache_clean': | ||
| return { | ||
| action: 'clean_cache', | ||
| commands: getCacheCleanCommands(context.platform), | ||
| }; | ||
| case 'contact_support_seat_reset': | ||
| case 'contact_support_grant': | ||
| case 'contact_support_billing': | ||
| return { action: 'contact_support' }; | ||
| case 'verify_email': | ||
| return { action: 'verify_email' }; | ||
| case 'check_credentials': | ||
| return { action: 'check_credentials' }; | ||
| default: | ||
| return { action: 'none' }; | ||
| } | ||
| } | ||
|
|
||
| module.exports = { getCacheCleanCommands, planRecoveryAction }; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| // PRO-UX.2 — renders an AIOXError (from error-bridge) as warm, actionable CLI | ||
| // output. Shows userMessage + numbered recovery steps + support_code (when | ||
| // present) + support link (only for contact_support_* hints) + a discreet | ||
| // technical footer. Writer is injectable for testability. | ||
|
|
||
| const SUPPORT_URL = 'https://suporte.aiox.dev'; | ||
|
|
||
| /** | ||
| * @param {AIOXError} err | ||
| * @param {(line: string) => void} [write] - defaults to stderr writer | ||
| */ | ||
| function renderError(err, write) { | ||
| const out = write || ((line) => process.stderr.write(line + '\n')); | ||
| const meta = (err && err.metadata) || {}; | ||
| const recovery = Array.isArray(err && err.recovery) ? err.recovery : []; | ||
| const recoveryHint = meta.recovery_hint; | ||
| const supportCode = meta.support_code; | ||
| const httpStatus = meta.httpStatus; | ||
|
|
||
| out(`✗ ${err.userMessage || err.message}`); | ||
|
|
||
| if (recovery.length > 0) { | ||
| out(''); | ||
| out('Para resolver:'); | ||
| recovery.forEach((step, i) => out(` ${i + 1}. ${step}`)); | ||
| } | ||
|
|
||
| if (supportCode) { | ||
| out(''); | ||
| out(`Código de suporte: ${supportCode}`); | ||
| if (typeof recoveryHint === 'string' && recoveryHint.startsWith('contact_support_')) { | ||
| out(`Suporte: ${SUPPORT_URL}`); | ||
| } | ||
| } | ||
|
|
||
| // Discreet technical footer for debugging — not the student-facing message. | ||
| out(''); | ||
| const statusPart = httpStatus ? ` — HTTP ${httpStatus}` : ''; | ||
| out(`(${err.code}${statusPart})`); | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
| } | ||
|
|
||
| module.exports = { renderError, SUPPORT_URL }; | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Use absolute imports for core error modules.
Please switch these
require('./...')statements to the project’s absolute import form to align with repository standards.As per coding guidelines,
**/*.{js,jsx,ts,tsx}: Use absolute imports instead of relative imports in all code.🤖 Prompt for AI Agents