# 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

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

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

### Advanced example

```ts
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.