first commit

docs/api-stack/api/create-suaveplan-plugin/src/error-codes.md

@@ -0,0 +1,73 @@
+# 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.