Add structured exit codes for different failure categories

[aidandaly24]

Problem

The CLI currently exits with generic exit code 1 for all failures. This makes it hard to programmatically distinguish between different failure types in CI/CD pipelines or scripts that wrap agentcore commands.

Proposed Solution

Define and export named exit codes in src/cli/errors.ts (or a new src/cli/exit-codes.ts) that map to specific failure categories:

Exit Code	Constant	Meaning
0	EXIT_SUCCESS	Command succeeded
1	EXIT_GENERAL_ERROR	Unknown/unhandled error
2	EXIT_INVALID_ARGS	Invalid CLI arguments or missing required flags
3	EXIT_AUTH_EXPIRED	AWS credentials expired or invalid (maps to EXPIRED_TOKEN_ERROR_CODES in errors.ts)
4	EXIT_ACCESS_DENIED	IAM permission error (maps to isAccessDeniedError())
5	EXIT_AGENT_NOT_FOUND	Requested agent doesn't exist
6	EXIT_DEPLOY_FAILED	Deployment/CloudFormation failure

Requirements

• Export a ExitCode enum or const object from src/cli/exit-codes.ts
• Update getErrorMessage() flow or add a getExitCode(err: unknown): number function that maps errors to the correct exit code
• Update the top-level CLI error handler (likely in src/cli/cli.ts or src/cli/index.ts) to use the mapped exit code instead of hardcoded process.exit(1)
• Add unit tests in src/cli/__tests__/ for the exit code mapping

Acceptance Criteria

• Exit codes enum/object exported from new file
• getExitCode() correctly maps isAccessDeniedError() → EXIT_ACCESS_DENIED
• getExitCode() correctly maps expired token errors → EXIT_AUTH_EXPIRED
• Top-level error handler uses getExitCode() instead of hardcoded 1
• Unit tests cover all exit code mappings
• Unknown errors default to EXIT_GENERAL_ERROR (1)

[aidandaly24]

Implementation Plan

Summary

Create a new src/cli/exit-codes.ts file that exports structured exit codes and a getExitCode() function that maps error types to specific exit codes. Update the top-level CLI error handler in src/cli/index.ts to use getExitCode() instead of hardcoded process.exit(1). Add comprehensive unit tests in src/cli/__tests__/exit-codes.test.ts.

Files to Modify

File	Action	Description
src/cli/exit-codes.ts	CREATE	Exit code constants and getExitCode() mapping function
src/cli/index.ts	MODIFY	Update 3 process.exit(1) calls to use getExitCode()
src/cli/__tests__/exit-codes.test.ts	CREATE	Unit tests for exit code mapping

Implementation Approach

1. Create src/cli/exit-codes.ts

a) Exit code constants as a const object (matches codebase style — see DISTRO_CONFIG in constants.ts):

export const ExitCode = {
  SUCCESS: 0,
  GENERAL_ERROR: 1,
  INVALID_ARGS: 2,
  AUTH_EXPIRED: 3,
  ACCESS_DENIED: 4,
  AGENT_NOT_FOUND: 5,
  DEPLOY_FAILED: 6,
} as const;

export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

b) getExitCode(err: unknown): number function that checks errors in priority order:

1. isAccessDeniedError(err) → ExitCode.ACCESS_DENIED (4)
2. isExpiredTokenError(err) → ExitCode.AUTH_EXPIRED (3)
3. isNoCredentialsError(err) → ExitCode.AUTH_EXPIRED (3) — no credentials is also an auth issue
4. Commander errors (check (err as Record<string, unknown>).code === 'commander.invalidArgument' or .exitCode === 2) → ExitCode.INVALID_ARGS (2)
5. isStackInProgressError(err) or isChangesetInProgressError(err) → ExitCode.DEPLOY_FAILED (6)
6. Error message contains "agent" + ("not found" | "not defined" | "not deployed") → ExitCode.AGENT_NOT_FOUND (5)
7. Default → ExitCode.GENERAL_ERROR (1)

Key design decisions:

• Imports at top of file per AGENTS.md rules (no inline imports)
• Uses existing error checker functions from ./errors.js (isAccessDeniedError, isExpiredTokenError, isNoCredentialsError, isStackInProgressError, isChangesetInProgressError, getErrorMessage)
• Parameter is err: unknown matching existing pattern in errors.ts
• No any types or @ts-ignore
• Access denied checked before expired token (they are mutually exclusive per errors.ts design, but order matters for clarity)

2. Modify src/cli/index.ts

Current (3 hardcoded process.exit(1) calls):

import { main } from './cli.js';
import { getErrorMessage } from './errors.js';

process.on('uncaughtException', err => {
  console.error(`Error: ${getErrorMessage(err)}`);
  process.exit(1);
});
process.on('unhandledRejection', reason => {
  console.error(`Error: ${getErrorMessage(reason)}`);
  process.exit(1);
});
main(process.argv).catch(err => {
  console.error(getErrorMessage(err));
  process.exit(1);
});

After:

• Add import: import { getExitCode } from './exit-codes.js';
• Replace all 3 process.exit(1) with process.exit(getExitCode(err)) / process.exit(getExitCode(reason))

3. Create src/cli/__tests__/exit-codes.test.ts

Follow the exact testing pattern from src/cli/__tests__/errors.test.ts (import from vitest, describe/it blocks).

Test coverage:

Category	Test Cases	Expected Exit Code
Access Denied	{ name: 'AccessDeniedException' }, { name: 'AccessDenied' }	4
Auth Expired	{ name: 'ExpiredToken' }, { name: 'ExpiredTokenException' }, all EXPIRED_TOKEN_ERROR_CODES members, message patterns	3
No Credentials	{ name: 'AwsCredentialsError' }, new Error('no aws credentials found')	3
Invalid Args	{ code: 'commander.invalidArgument' }, { exitCode: 2 }	2
Agent Not Found	new Error("Agent 'x' not found"), new Error("Agent 'x' is not deployed"), new Error("No agents defined")	5
Deploy Failed	Stack in-progress errors, changeset in-progress errors	6
Default	new Error('random'), null, undefined, 'string', {}	1
Priority	Access denied not misclassified as expired token; expired token not misclassified as agent-not-found	correct codes
Constants	All ExitCode values match expected numbers 0-6	—

Edge Cases & Risks

1. Commander error detection: Uses (err as Record<string, unknown>).code property check (not instanceof) since Commander errors may not be directly importable. This follows the existing errors.ts pattern for AWS SDK errors.

2. Agent-not-found false positives: Message-based detection requires both "agent" and "not found"/"not defined"/"not deployed". Most agent-not-found errors are caught within command handlers before reaching the top-level handler, so false positives are unlikely.

3. Backward compatibility: For unknown errors, getExitCode() returns 1 (same as before), so this is fully backward-compatible.

4. Scope: Only the top-level handler in src/cli/index.ts is modified. Individual command handlers (deploy, invoke, etc.) have their own process.exit(1) calls that are out of scope for this issue.

5. Import style: Must use .js extension in imports per ESM module resolution (matching existing './cli.js', './errors.js' pattern).

Testing Strategy

1. Unit tests in src/cli/__tests__/exit-codes.test.ts — all mappings covered
2. Existing tests: npm test to verify no regressions
3. Type checking: npm run typecheck
4. Linting: npm run lint
5. Format: npm run format:check

Tests are self-contained with no mocking needed — getExitCode() is a pure function delegating to existing pure error-checking functions from errors.ts.

[aidandaly24]

I'll start by exploring the repository structure and understanding the codebase to create a thorough implementation plan.[MEMORY: repo] Root-level structure includes src/, e2e-tests/, integ-tests/, uses vitest, esbuild, TypeScript, eslint, prettier.

Now let me explore the key source files:[MEMORY: repo] CLI structure: src/cli/cli.ts is the main CLI entry, src/cli/errors.ts has error handling, src/cli/index.ts is the CLI module entry. Uses Commander for CLI commands.

Now let me read the critical files:[MEMORY: issue] The top-level error handler is in src/cli/index.ts — it has 3 places that call process.exit(1): uncaughtException, unhandledRejection, and the main().catch(). All use hardcoded exit code 1.

[MEMORY: pattern] src/cli/errors.ts already has: getErrorMessage(), isAccessDeniedError(), isExpiredTokenError(), isNoCredentialsError(), isStackInProgressError(), isChangesetInProgressError(), and EXPIRED_TOKEN_ERROR_CODES (private Set). Also has AgentAlreadyExistsError class.

Now let me look at the existing tests and commands to understand patterns better:[MEMORY: pattern] Existing test file: src/cli/__tests__/errors.test.ts. Tests should follow the same pattern. Constants are in src/cli/constants.ts.

Now let me look at the existing errors test and the deploy command to understand how errors are thrown:Let me look at the deploy actions to understand how errors are thrown during deployment, and also look at how Commander handles argument errors:[MEMORY: pattern] Deploy command uses process.exit(1) for failures and process.exit(0) for success. The handleDeploy function returns { success: boolean, error?: string } pattern — errors are caught and returned, not thrown. The deploy command.tsx has its own process.exit(1) calls.

[MEMORY: issue] Key observation: Many commands call process.exit(1) directly within their action handlers. The top-level handler in src/cli/index.ts catches unhandled errors. We need to understand all the process.exit(1) call sites.

Let me search for all process.exit(1) calls and also look at how Commander handles invalid args:Let me search for process.exit calls using GitHub search:GitHub code search seems to not return results for this repo. Let me look at the key files that likely have process.exit calls:Let me look at a few more command files to understand the process.exit(1) patterns, and also look at the invoke command and the tui guards:[MEMORY: pattern] requireProject() in src/cli/tui/guards/project.tsx calls process.exit(1) when no project found. Many command handlers also call process.exit(1) directly.

Now let me look at the vitest config and the AGENTS.md in src/cli for testing patterns:[MEMORY: repo] Tests run with vitest run --project unit, test files are src/**/*.test.ts. Uses @commander-js/extra-typings for CLI. Entry point for CLI binary is dist/cli/index.mjs.

Now let me look at the src/cli/aws/account.ts to understand how credential errors are thrown:[MEMORY: pattern] Commands follow two patterns: (1) Actions return { success: boolean, error?: string } and the command handler calls process.exit(result.success ? 0 : 1), (2) Errors are caught and process.exit(1) is called directly. The errors that bubble up to the top-level handler in src/cli/index.ts are unhandled exceptions.

[MEMORY: issue] The issue scope is focused: create exit codes, create getExitCode() function, and update the top-level error handler in src/cli/index.ts. The issue does NOT ask to update individual command handlers (deploy, invoke, etc.) — those have their own process.exit(1) calls that are out of scope. The focus is on the 3 process.exit(1) calls in src/cli/index.ts.

Now let me check if there are any Commander error handling patterns (Commander's exitOverride etc.):Now I have a thorough understanding of the codebase. Let me also check the Commander error handling to understand how invalid arguments are currently handled:I now have a comprehensive understanding of the codebase. Let me also check the src/cli/AGENTS.md code style note about { success: Boolean, error?: string } pattern and look at the eslint config to understand any constraints:[MEMORY: repo] TypeScript strict mode enabled. Uses verbatimModuleSyntax: true which means imports must use import type for type-only imports.

Now I have a thorough understanding. Let me formulate the plan.

---

Implementation Plan

Summary

Create a new src/cli/exit-codes.ts file that exports structured exit codes and a getExitCode() function that maps error types to specific exit codes. Then update the top-level CLI error handler in src/cli/index.ts to use getExitCode() instead of hardcoded process.exit(1). Add comprehensive unit tests in src/cli/__tests__/exit-codes.test.ts.

Files to Modify

1. src/cli/exit-codes.ts — NEW FILE — Exit code constants and getExitCode() mapping function
2. src/cli/index.ts — MODIFY — Update 3 process.exit(1) calls to use getExitCode()
3. src/cli/__tests__/exit-codes.test.ts — NEW FILE — Unit tests for exit code mapping

Implementation Approach

1. Create src/cli/exit-codes.ts

This new file should contain:

a) Exit code constants as a const object (not an enum, to match the codebase's style of using const objects like DISTRO_CONFIG in constants.ts):

/**
 * Structured exit codes for different CLI failure categories.
 * These enable programmatic distinction between failure types
 * in CI/CD pipelines and wrapper scripts.
 */
export const ExitCode = {
  /** Command succeeded */
  SUCCESS: 0,
  /** Unknown/unhandled error */
  GENERAL_ERROR: 1,
  /** Invalid CLI arguments or missing required flags */
  INVALID_ARGS: 2,
  /** AWS credentials expired or invalid */
  AUTH_EXPIRED: 3,
  /** IAM permission error */
  ACCESS_DENIED: 4,
  /** Requested agent doesn't exist */
  AGENT_NOT_FOUND: 5,
  /** Deployment/CloudFormation failure */
  DEPLOY_FAILED: 6,
} as const;

Also export the type: export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

b) A getExitCode(err: unknown): number function that checks errors in priority order:

1. Check isAccessDeniedError(err) from ./errors.js → return ExitCode.ACCESS_DENIED (4)
2. Check isExpiredTokenError(err) from ./errors.js → return ExitCode.AUTH_EXPIRED (3)
3. Check isNoCredentialsError(err) from ./errors.js → return ExitCode.AUTH_EXPIRED (3) — no credentials is also an auth issue
4. Check if error is a Commander InvalidArgumentError or has code === 'commander.invalidArgument' or exitCode === 2 (Commander sets these for argument validation errors) → return ExitCode.INVALID_ARGS (2)
5. Check isStackInProgressError(err) or isChangesetInProgressError(err) from ./errors.js → return ExitCode.DEPLOY_FAILED (6)
6. Check if error message contains "not found" + "agent" patterns (e.g., Agent '...' not found) → return ExitCode.AGENT_NOT_FOUND (5)
7. Default → return ExitCode.GENERAL_ERROR (1)

Important design decisions:

• Import error checker functions from ./errors.js at the top of the file (per AGENTS.md: "Never use inline imports")
• Use import { isAccessDeniedError, isExpiredTokenError, isNoCredentialsError, isStackInProgressError, isChangesetInProgressError, getErrorMessage } from './errors.js';
• The function parameter is err: unknown to match the existing pattern in errors.ts
• No any types or @ts-ignore
• For Commander errors, check for (err as Record<string, unknown>).code === 'commander.invalidArgument' or (err as Record<string, unknown>).exitCode === 2 — this matches how Commander.js signals argument errors. Also check the error constructor name for CommanderError.
• For agent-not-found, check the error message with getErrorMessage(err).toLowerCase() for patterns like "agent" combined with "not found" or "not defined" or "not deployed".
• For deploy failures, also check for CloudFormation-related error patterns in the message (e.g., "cloudformation", "stack", "deploy") combined with failure indicators.

Priority order matters: Check isAccessDeniedError before isExpiredTokenError because the issue explicitly notes that AccessDenied errors are NOT in EXPIRED_TOKEN_ERROR_CODES and should map to a different exit code.

2. Modify src/cli/index.ts

Current file (lines to change):

import { main } from './cli.js';
import { getErrorMessage } from './errors.js';

process.on('uncaughtException', err => {
  console.error(`Error: ${getErrorMessage(err)}`);
  process.exit(1);  // ← Change this
});
process.on('unhandledRejection', reason => {
  console.error(`Error: ${getErrorMessage(reason)}`);
  process.exit(1);  // ← Change this
});

main(process.argv).catch(err => {
  console.error(getErrorMessage(err));
  process.exit(1);  // ← Change this
});

Changes:

• Add import: import { getExitCode } from './exit-codes.js';
• Replace all 3 process.exit(1) calls with process.exit(getExitCode(err)) / process.exit(getExitCode(reason))

The updated file should look like:

#!/usr/bin/env node
import { main } from './cli.js';
import { getErrorMessage } from './errors.js';
import { getExitCode } from './exit-codes.js';

process.on('uncaughtException', err => {
  console.error(`Error: ${getErrorMessage(err)}`);
  process.exit(getExitCode(err));
});
process.on('unhandledRejection', reason => {
  console.error(`Error: ${getErrorMessage(reason)}`);
  process.exit(getExitCode(reason));
});

main(process.argv).catch(err => {
  console.error(getErrorMessage(err));
  process.exit(getExitCode(err));
});

3. Create src/cli/__tests__/exit-codes.test.ts

Follow the exact testing pattern from src/cli/__tests__/errors.test.ts:

• Import from ../exit-codes.js
• Import from vitest (describe, expect, it)
• Use describe/it blocks

Test cases to cover:

a) ExitCode constants:

• Verify all values match the expected numbers (0-6)
• Verify all expected keys exist

b) getExitCode() — Access Denied mapping (→ 4):

• { name: 'AccessDeniedException' } → 4
• { name: 'AccessDenied' } → 4

c) getExitCode() — Expired Token mapping (→ 3):

• { name: 'ExpiredToken' } → 3
• { name: 'ExpiredTokenException' } → 3
• { name: 'TokenRefreshRequired' } → 3
• new Error('security token included in the request is expired') → 3
• All other codes from EXPIRED_TOKEN_ERROR_CODES

d) getExitCode() — No Credentials mapping (→ 3):

• { name: 'AwsCredentialsError' } → 3
• new Error('no aws credentials found') → 3

e) getExitCode() — Commander/Invalid Args mapping (→ 2):

• Error with code: 'commander.invalidArgument' → 2
• Error with exitCode: 2 (Commander convention) → 2

f) getExitCode() — Agent Not Found mapping (→ 5):

• new Error("Agent 'my-agent' not found") → 5
• new Error("Agent 'my-agent' is not deployed") → 5
• new Error("No agents defined in agentcore.json") → 5

g) getExitCode() — Deploy Failed mapping (→ 6):

• Stack in progress errors (e.g., new Error('Stack is in UPDATE_IN_PROGRESS state and cannot be updated')) → 6
• Changeset in progress errors → 6

h) getExitCode() — Default/General Error mapping (→ 1):

• new Error('some random error') → 1
• null → 1
• undefined → 1
• 'string error' → 1
• {} → 1

i) Priority tests:

• Verify isAccessDeniedError takes priority over message-based matching
• Verify isExpiredTokenError takes priority over agent-not-found message matching

Edge Cases & Risks

1. Commander error detection: Commander.js uses CommanderError class with a code property. The @commander-js/extra-typings package wraps this. We need to check for code property on the error object rather than relying on instanceof (since Commander errors may not be directly importable). Using (err as Record<string, unknown>).code is safe and follows the existing pattern in errors.ts.

2. Agent-not-found false positives: The message-based detection for "agent" + "not found" could theoretically match unrelated errors. However, this is a best-effort mapping for the top-level handler — most agent-not-found errors are caught and handled within command handlers before reaching the top level. Keep the pattern narrow (require both "agent" and "not found"/"not defined"/"not deployed" in the message).

3. Deploy-failed detection: The isStackInProgressError and isChangesetInProgressError functions from errors.ts already handle CloudFormation-specific patterns. These are the most likely deploy-related errors to bubble up to the top-level handler.

4. No breaking changes: The only behavioral change is that process.exit(1) becomes process.exit(getExitCode(err)) — for unknown errors, getExitCode returns 1 (same as before), so this is backward-compatible.

5. Type safety: The ExitCode type should be (typeof ExitCode)[keyof typeof ExitCode] to get a union of the literal number types. The getExitCode function should return number (not ExitCode) since it's used directly in process.exit().

6. Import style: Must use .js extension in imports per the ESM module resolution in the project (see existing imports in index.ts: './cli.js', './errors.js').

Testing Strategy

1. Unit tests in src/cli/__tests__/exit-codes.test.ts covering all mappings as described above
2. Run existing tests to ensure no regressions: npm test (vitest run --project unit)
3. Type checking: npm run typecheck (tsc --noEmit)
4. Linting: npm run lint to ensure no ESLint violations
5. Format check: npm run format:check to ensure Prettier compliance

The tests should be self-contained and not require mocking — getExitCode() is a pure function that delegates to the existing error-checking functions from errors.ts, which are also pure functions. This makes the tests simple and reliable.

---

Now let me post this plan as a comment on the issue:The implementation plan has been posted to the issue. Here's a summary of what was explored and planned:

Key Findings

1. Top-level error handler (src/cli/index.ts, lines 4-15): Has exactly 3 process.exit(1) calls — uncaughtException, unhandledRejection, and main().catch(). These are the only places that need modification.

2. Existing error infrastructure (src/cli/errors.ts): Already has all the error classification functions needed:

   • isAccessDeniedError() → maps to exit code 4
   • isExpiredTokenError() → maps to exit code 3
   • isNoCredentialsError() → maps to exit code 3
   • isStackInProgressError() / isChangesetInProgressError() → maps to exit code 6
   • getErrorMessage() → used for message-based pattern matching

3. Scope is narrow and safe: Only 3 files touched (1 new module, 1 new test file, 1 small modification). Individual command handlers have their own process.exit(1) calls but those are out of scope.

4. Backward compatible: Unknown errors still return exit code 1 (same behavior as before).