error-codes

Purpose

This module declares the frozen, namespaced registry of every failure code the create-suaveplan-plugin scaffold can raise, together with the ScaffoldError subclass that carries those codes. Anchoring every failure path to a single, exhaustive code list lets downstream orchestration scripts and CLI wrappers recover programmatically without parsing error messages — they branch on error.code and the literal type narrows for them.

Features

Frozen SCAFFOLD_CODES registry via defineCodes from @suaveplan/error. Every value is a SCAFFOLD.<REASON> string literal.
ScaffoldError extends SuaveplanError<ScaffoldErrorCode> so instanceof plus .code checks stay exhaustive.
Side-effect import from src/index.ts ensures subpath consumers register codes too.

Usage

Basic example

import { SCAFFOLD_CODES, ScaffoldError } from "create-suaveplan-plugin";

throw new ScaffoldError(
    SCAFFOLD_CODES.INVALID_NAME,
    "scaffold.invalid_name:Foo",
);

Advanced example

import { ScaffoldError } from "create-suaveplan-plugin";

try {
    runScaffold();
} catch (err) {
    if (err instanceof ScaffoldError && err.code === "SCAFFOLD.DIRECTORY_EXISTS") {
        console.error("Target already exists. Re-run with --force.");
        process.exit(2);
    }
    throw err;
}

API Reference

SCAFFOLD_CODES — frozen record of code-name → SCAFFOLD.<NAME>.
ScaffoldErrorCode — union of every value of SCAFFOLD_CODES.
class ScaffoldError extends SuaveplanError<ScaffoldErrorCode> — constructor (code, messageKey, options?).

Implementation Notes

The registry is built at module-load time via defineCodes, which freezes the resulting object so consumers cannot mutate it.
Every code in this registry is thrown by a production code path — see prompt/prompt.ts (INVALID_NAME), generator/generator.ts (DIRECTORY_EXISTS, WRITE_FAILED, UNKNOWN_ENGINE).
The error is intentionally distinct from SuaveplanError so consumer catch clauses can disambiguate scaffold failures from peer-package failures without a code-string match. The class name is set to ScaffoldError so structured loggers serialising via the standard name/message/stack triple emit a recognisable identity.
The conformance script enforces a side-effect import of this module from the package barrel; without it, subpath consumers would not register codes in any global telemetry hook.

2.5 KiB Raw Blame History