/kdcokenny/ocx

Wiki directory

Browse AI-generated documentation for any repository.

Error Handling & Logging

Relevant source files

The following files were used as context for generating this wiki page:

Introduction

The OCX project implements a robust error handling and logging system built on the "Fail Fast, Fail Loud" principle of the 5 Laws of Elegant Defense. This system ensures that illegal states are unrepresentable, and when errors do occur, they are communicated immediately and descriptively to avoid "half-broken" states.

The architecture separates concerns into custom error classes, a centralized CLI error handler, and standardized logging utilities. In the CLI environment, errors are caught and transformed into user-friendly terminal output or structured JSON, depending on the user's configuration. In the plugin ecosystem, error handling is enforced through Zod schema validation at boundaries and specialized logic for plan validation.

Sources: examples/registry-starter/AGENTS.md:46-51, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:21-23, packages/cli/src/utils/handle-error.ts:1-5

The 5 Laws of Elegant Defense

All code in the OCX registry and CLI follows five core principles that dictate how data flow and errors are managed.

Law	Principle	Description
1. Early Exit	Guard Clauses	Handle edge cases and nulls at the top of functions to reduce indentation and nesting.
2. Parse, Don't Validate	Boundary Checks	Transform unknown data into trusted, typed data once at the entry point using schemas.
3. Atomic Predictability	Purity	Functions should be pure (Same Input → Same Output) with no hidden side effects.
4. Fail Fast, Fail Loud	Immediate Feedback	Throw clear, descriptive errors immediately when an invalid state is detected.
5. Intentional Naming	Self-Documentation	Variable and function names should reveal intent so the logic reads like a sentence.

Sources: examples/registry-starter/AGENTS.md:25-60, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:7-30

CLI Error Architecture

The CLI uses a centralized error handling mechanism to provide consistent exit codes and messaging.

Custom Error Classes

OCX defines a hierarchy of error classes extending a base OCXError. These classes include specific metadata like error codes and corresponding system exit codes.

Generating architecture diagram...

The diagram shows the inheritance structure of the CLI's specialized error classes.

Sources: packages/cli/src/utils/errors.ts:1-75, AGENTS.md:120-143

Exit Codes

The system uses standardized exit codes to communicate the nature of the failure to the shell environment.

Constant	Value	Usage
`SUCCESS`	0	Command completed without error.
`GENERAL`	1	Generic error or integrity failure.
`NOT_FOUND`	66	A requested resource (file, component, profile) does not exist.
`NETWORK`	69	HTTP or fetch failures during registry interaction.
`CONFIG`	78	Invalid configuration files or Zod validation failures.

Sources: packages/cli/src/utils/errors.ts:17-23, AGENTS.md:145-148

Error Processing Flow

When an exception occurs during CLI execution, it is passed to the handleError utility. This utility determines the output format and terminates the process with the correct exit code.

Generating architecture diagram...

The flow shows how different error types (Zod, OCX, or Generic) are processed into final terminal or JSON output.

Sources: packages/cli/src/utils/handle-error.ts:20-53

Validation Error Handling (Zod)

In accordance with "Parse, Don't Validate", Zod is used at boundaries. When validation fails, handleError iterates through the Zod issues to produce a readable path-based error report.

// Example Zod Error Formatting
if (error instanceof ZodError) {
    logger.error("Validation failed:")
    for (const issue of error.issues) {
        const path = issue.path.join(".")
        logger.error(`  ${path}: ${issue.message}`)
    }
    process.exit(EXIT_CODES.CONFIG)
}

Sources: packages/cli/src/utils/handle-error.ts:34-42

Logging and UI Feedback

OCX provides specialized utilities for interacting with the user via the terminal.

Logger Utility

The logger provides standardized methods for different levels of information:

logger.info(): General status updates.
logger.success(): Confirmation of successful operations.
logger.warn(): Non-fatal warnings.
logger.error(): Fatal error messages.

Sources: packages/cli/src/utils/logger.ts, packages/cli/src/utils/handle-error.ts:28

Spinner (Async Feedback)

For long-running operations (like building a registry or fetching files), the CLI uses a spinner utility. If an operation fails, the spinner provides a failure state visual.

const spin = createSpinner({ text: "Processing..." }).start()
try {
    // ... work
    spin.succeed("Done!")
} catch (e) {
    spin.fail("Failed to process")
    throw e
}

Sources: packages/cli/src/utils/spinner.ts, packages/cli/src/commands/update.ts:166-310

Plugin and Plan Validation

Within the WorkspacePlugin, error handling is specialized for implementation plans. The parsePlanMarkdown function implements hierarchical validation.

Plan Validation Logic

Early Exit: Guard against empty or non-string content.
Extraction: Raw extraction of markdown parts (frontmatter, goal, phases).
Schema Validation: Single validation point using a Zod schema (PlanSchema).
Business Rules: Post-parsing checks for logic (e.g., ensuring only one task is marked ← CURRENT).

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:130-184

Structured Plan Errors

The plugin uses a formatZodErrors helper to provide actionable guidance when a plan violates the protocol. It maps complex Zod paths to human-readable field names and provides a "hint" to load the plan-protocol skill.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:107-128, workers/kdco-registry/files/plugin/workspace-plugin.ts:220-224

Summary

Error handling in OCX is a tiered system that begins with strict coding philosophies (The 5 Laws) to prevent errors by design. At runtime, the system uses Zod for boundary parsing and a custom error hierarchy for the CLI. By centralizing error processing in handleError.ts, the project maintains consistent behavior, providing descriptive feedback and appropriate exit codes whether the user is interacting with the CLI directly or via structured JSON automation.

Sources: AGENTS.md:120-148, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:1-35

Error Handling & Logging

Relevant source files

The following files were used as context for generating this wiki page:

Introduction

Sources: examples/registry-starter/AGENTS.md:46-51, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:21-23, packages/cli/src/utils/handle-error.ts:1-5

The 5 Laws of Elegant Defense

All code in the OCX registry and CLI follows five core principles that dictate how data flow and errors are managed.

Law	Principle	Description
1. Early Exit	Guard Clauses	Handle edge cases and nulls at the top of functions to reduce indentation and nesting.
2. Parse, Don't Validate	Boundary Checks	Transform unknown data into trusted, typed data once at the entry point using schemas.
3. Atomic Predictability	Purity	Functions should be pure (Same Input → Same Output) with no hidden side effects.
4. Fail Fast, Fail Loud	Immediate Feedback	Throw clear, descriptive errors immediately when an invalid state is detected.
5. Intentional Naming	Self-Documentation	Variable and function names should reveal intent so the logic reads like a sentence.

Sources: examples/registry-starter/AGENTS.md:25-60, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:7-30

CLI Error Architecture

The CLI uses a centralized error handling mechanism to provide consistent exit codes and messaging.

Custom Error Classes

OCX defines a hierarchy of error classes extending a base OCXError. These classes include specific metadata like error codes and corresponding system exit codes.

Generating architecture diagram...

The diagram shows the inheritance structure of the CLI's specialized error classes.

Sources: packages/cli/src/utils/errors.ts:1-75, AGENTS.md:120-143

Exit Codes

The system uses standardized exit codes to communicate the nature of the failure to the shell environment.

Constant	Value	Usage
`SUCCESS`	0	Command completed without error.
`GENERAL`	1	Generic error or integrity failure.
`NOT_FOUND`	66	A requested resource (file, component, profile) does not exist.
`NETWORK`	69	HTTP or fetch failures during registry interaction.
`CONFIG`	78	Invalid configuration files or Zod validation failures.

Sources: packages/cli/src/utils/errors.ts:17-23, AGENTS.md:145-148

Error Processing Flow

When an exception occurs during CLI execution, it is passed to the handleError utility. This utility determines the output format and terminates the process with the correct exit code.

Generating architecture diagram...

The flow shows how different error types (Zod, OCX, or Generic) are processed into final terminal or JSON output.

Sources: packages/cli/src/utils/handle-error.ts:20-53

Validation Error Handling (Zod)

In accordance with "Parse, Don't Validate", Zod is used at boundaries. When validation fails, handleError iterates through the Zod issues to produce a readable path-based error report.

// Example Zod Error Formatting
if (error instanceof ZodError) {
    logger.error("Validation failed:")
    for (const issue of error.issues) {
        const path = issue.path.join(".")
        logger.error(`  ${path}: ${issue.message}`)
    }
    process.exit(EXIT_CODES.CONFIG)
}

Sources: packages/cli/src/utils/handle-error.ts:34-42

Logging and UI Feedback

OCX provides specialized utilities for interacting with the user via the terminal.

Logger Utility

The logger provides standardized methods for different levels of information:

logger.info(): General status updates.
logger.success(): Confirmation of successful operations.
logger.warn(): Non-fatal warnings.
logger.error(): Fatal error messages.

Sources: packages/cli/src/utils/logger.ts, packages/cli/src/utils/handle-error.ts:28

Spinner (Async Feedback)

For long-running operations (like building a registry or fetching files), the CLI uses a spinner utility. If an operation fails, the spinner provides a failure state visual.

const spin = createSpinner({ text: "Processing..." }).start()
try {
    // ... work
    spin.succeed("Done!")
} catch (e) {
    spin.fail("Failed to process")
    throw e
}

Sources: packages/cli/src/utils/spinner.ts, packages/cli/src/commands/update.ts:166-310

Plugin and Plan Validation

Within the WorkspacePlugin, error handling is specialized for implementation plans. The parsePlanMarkdown function implements hierarchical validation.

Plan Validation Logic

Early Exit: Guard against empty or non-string content.
Extraction: Raw extraction of markdown parts (frontmatter, goal, phases).
Schema Validation: Single validation point using a Zod schema (PlanSchema).
Business Rules: Post-parsing checks for logic (e.g., ensuring only one task is marked ← CURRENT).

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:130-184

Structured Plan Errors

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:107-128, workers/kdco-registry/files/plugin/workspace-plugin.ts:220-224

Summary

Sources: AGENTS.md:120-148, workers/kdco-registry/files/skill/code-philosophy/SKILL.md:1-35