aiwg
Version:
Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo
118 lines • 4.74 kB
TypeScript
/**
* AIWG Structured Errors
*
* Every intentional error thrown by CLI code should be an `AiwgError` with:
* - `code` — stable UPPER_SNAKE_CASE identifier (ERR_CATEGORY_REASON)
* - `exitCode` — process exit code (see EXIT_CODES table below)
* - `hint` — optional one-line user-facing hint with a suggested next action
* - `cause` — optional underlying error for chain preservation (ES2022)
*
* The top-level formatter in `bin/aiwg.mjs` prints a single-line message and
* only reveals stack traces when `AIWG_DEBUG=1` or `--verbose` is set.
*
* Code naming: category-prefixed uppercase snake_case.
* ERR_CONFIG_* — problems reading/writing .aiwg/aiwg.config
* ERR_NETWORK_* — timeouts, unreachable services, HTTP errors
* ERR_USAGE_* — bad flags, unknown commands, missing required args
* ERR_FS_* — filesystem errors (permission, ENOENT outside config)
* ERR_SANDBOX_* — sandbox-specific failures
* ERR_INTERNAL — unexpected bugs (last resort; prefer a specific code)
*
* Phase 4 of the CLI Stabilization Epic (#921).
*/
/**
* Process exit codes used by the CLI. Pragmatic subset of sysexits.h —
* enough categorization for scripts to branch on without full sysexits
* ceremony.
*/
export declare const EXIT_CODES: {
/** Command completed successfully. */
readonly OK: 0;
/** General / uncategorized failure. */
readonly GENERAL: 1;
/** User error: unknown command, bad flag, missing required argument. */
readonly USAGE: 2;
/** Filesystem write failure: permission denied, disk full, read-only. */
readonly CANT_CREATE: 73;
/** Config file missing, malformed, or otherwise unusable. */
readonly CONFIG: 78;
/** Interrupted by SIGINT (Ctrl-C). 128 + 2. */
readonly INTERRUPTED: 130;
/** Terminated by SIGTERM. 128 + 15. */
readonly TERMINATED: 143;
};
export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
export interface AiwgErrorInit {
/** Stable UPPER_SNAKE_CASE error code (ERR_CATEGORY_REASON). */
code: string;
/** Human-readable single-line message. */
message: string;
/** Process exit code. Defaults to EXIT_CODES.GENERAL (1). */
exitCode?: number;
/** Optional next-action hint printed after the error line. */
hint?: string;
/** Optional underlying cause for chain preservation. */
cause?: unknown;
}
/**
* Structured CLI error with a stable code and a prescribed exit code.
*
* Always throw these from handler code instead of bare `Error` so the
* top-level formatter can render consistent output and so tests can assert
* on the error code rather than brittle message strings.
*/
export declare class AiwgError extends Error {
readonly code: string;
readonly exitCode: number;
readonly hint?: string;
constructor(init: AiwgErrorInit);
}
/**
* Convenience checker — ts-narrows an unknown to AiwgError. Avoids importing
* the class just for a typeof-like check at catch sites.
*/
export declare function isAiwgError(err: unknown): err is AiwgError;
/**
* Format an error for terminal output. Always returns a single-line primary
* message; `hint` (if present) is returned as a second line; `stack` and the
* `cause` chain are included only when verbose is true.
*
* Does NOT color the output — caller chooses whether to apply ui.red() etc.
* so non-TTY stderr paths stay ANSI-clean.
*/
export declare function formatError(err: unknown, opts?: {
verbose?: boolean;
}): string;
/**
* Resolve the exit code to use for an error. Non-AiwgError throws and plain
* strings map to EXIT_CODES.GENERAL.
*/
export declare function exitCodeFor(err: unknown): number;
/**
* Convert any thrown value into a uniform HandlerResult shape, preserving
* AiwgError's semantic fields (code, exitCode, hint) where present.
*
* This is the bridge between the in-handler `try { ... } catch (err) { ... }`
* pattern and the HandlerResult contract the router expects. Use it in every
* handler's top-level catch:
*
* try {
* await doWork(ctx);
* return { exitCode: 0 };
* } catch (err) {
* return handlerResultFromError(err);
* }
*
* Non-AiwgError throws map to `{ exitCode: 1, message, error }`. AiwgError
* throws carry their `exitCode` (USAGE=2, CONFIG=78, CANT_CREATE=73, etc.)
* plus the `hint` merged into the message for single-line output.
*
* Phase 5 of the CLI Stabilization Epic (#922) — unblocks the exit-code
* propagation from Phase 4 (#921) that was previously flattened to 1.
*/
export declare function handlerResultFromError(err: unknown): {
exitCode: number;
message: string;
error: Error;
};
//# sourceMappingURL=errors.d.ts.map