Initial Commit

packages/devtools/tooling/installer/src/errors/errors.md

@@ -0,0 +1,66 @@
+# `errors`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Re-export shim for the `./errors` subpath. Exposes `INSTALLER_CODES`,
+`InstallerError`, and the `InstallerErrorCode` type from the canonical
+`error-codes.ts` so callers who import via the `./errors` package subpath
+get the same surface as `import { InstallerError } from "@suaveplan/installer"`. This keeps the spec's `./errors` subpath
+documented in one place even though the implementation lives under
+`error-codes.ts`.
+
+## Features
+
+- Stable subpath surface: every consumer who imports `@suaveplan/installer/errors` gets the same trio.
+- No runtime cost — pure re-export, tree-shaken by Vite when unused.
+- Keeps the canonical implementation in `error-codes.ts` so test, doc,
+  and conformance suites all point at the same file.
+
+## Basic Example
+
+```ts
+import {
+    INSTALLER_CODES,
+    InstallerError,
+} from "@suaveplan/installer/errors";
+
+throw new InstallerError(
+    INSTALLER_CODES.ABORTED,
+    "installer.aborted"
+);
+```
+
+## Advanced Example
+
+```ts
+import type { InstallerErrorCode } from "@suaveplan/installer/errors";
+import { InstallerError } from "@suaveplan/installer/errors";
+
+function classify(err: unknown): InstallerErrorCode | "other" {
+    return err instanceof InstallerError ? err.code : "other";
+}
+```
+
+## API Reference
+
+- `INSTALLER_CODES` — re-export of the frozen registry.
+- `class InstallerError extends SuaveplanError<InstallerErrorCode>`.
+- `type InstallerErrorCode` — union of every `INSTALLER.*` literal.
+
+## Implementation Notes
+
+The re-export pattern is deliberate — the spec's `./errors` subpath maps
+to a sub-folder so future error utilities (e.g. an OpenTelemetry
+formatter, a redaction helper, an error-code-to-exit-code mapping for
+the bin) can land in `errors/` without breaking the import path. Today
+the file is a one-line shim; once additional helpers move in, this
+barrel becomes the canonical bundle. The same trio is also re-exported
+from the package root (`@suaveplan/installer`), so callers can pick
+whichever subpath best matches their import boundary policy. Subpath
+imports are useful when consuming code wants narrower tree-shaking or
+when a downstream lint rule restricts non-error utilities from being
+imported alongside error types. Bundlers see the re-export as a no-op
+and emit no extra modules in the dist output.