79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# `error-codes`
|
|
|
|
## Purpose
|
|
|
|
Defines the canonical error-code registry for `@suaveplan/install-agent-skills`. Every plugin-side failure path
|
|
(invalid bundled manifest, unknown skill id under `--only`/`--exclude`,
|
|
empty/invalid target directory) surfaces as an `InstallSkillsError`
|
|
carrying a literal-typed `code` from this registry. The host's plan-stage
|
|
catch (`runPlan`) re-throws any `SuaveplanError` unchanged, so these codes
|
|
reach the caller without being wrapped in `INSTALLER.PLAN_FAILED`.
|
|
|
|
## Features
|
|
|
|
- Frozen registry built via `defineCodes("INSTALL_SKILLS", [...])`.
|
|
- `InstallSkillsError` extends `SuaveplanError<InstallSkillsErrorCode>`
|
|
with a public widened constructor.
|
|
- Three codes in the minimum surface: `MANIFEST_INVALID`, `UNKNOWN_SKILL`,
|
|
`TARGET_DIR_INVALID`.
|
|
- Stable `error.name === "InstallSkillsError"` so serialised payloads
|
|
carry a recognisable name across bundlers.
|
|
|
|
## Basic Example
|
|
|
|
```ts
|
|
import {
|
|
INSTALL_SKILLS_CODES,
|
|
InstallSkillsError,
|
|
} from "@suaveplan/install-agent-skills";
|
|
|
|
throw new InstallSkillsError(
|
|
INSTALL_SKILLS_CODES.UNKNOWN_SKILL,
|
|
"install_skills.unknown_skill",
|
|
{ context: { id: "nonexistent" } }
|
|
);
|
|
```
|
|
|
|
## Advanced Example
|
|
|
|
```ts
|
|
import { InstallSkillsError } from "@suaveplan/install-agent-skills";
|
|
|
|
function classify(err: unknown): string {
|
|
if (!(err instanceof InstallSkillsError)) return "other";
|
|
switch (err.code) {
|
|
case "INSTALL_SKILLS.MANIFEST_INVALID":
|
|
return "rebuild bundle";
|
|
case "INSTALL_SKILLS.UNKNOWN_SKILL":
|
|
return "fix --only/--exclude";
|
|
case "INSTALL_SKILLS.TARGET_DIR_INVALID":
|
|
return "supply targetDir";
|
|
default:
|
|
return "unhandled";
|
|
}
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
- `INSTALL_SKILLS_CODES` — frozen `{ [K]: "INSTALL_SKILLS.K" }` map.
|
|
- `type InstallSkillsErrorCode` — union of every literal in the registry.
|
|
- `class InstallSkillsError extends SuaveplanError<InstallSkillsErrorCode>`.
|
|
|
|
## Implementation Notes
|
|
|
|
The host's plan stage uses `instanceof SuaveplanError` (the shared base
|
|
class) to decide whether to re-throw or wrap, so codes from this
|
|
registry flow through the host's plan-stage catch unchanged and reach
|
|
the caller with their original `INSTALL_SKILLS.*` code intact.
|
|
`MANIFEST_INVALID` covers parse, read, and schema errors — callers
|
|
don't have to handle three variants and the underlying cause is always
|
|
available via `err.cause` for log-and-continue paths. `UNKNOWN_SKILL`
|
|
is emitted by the plan stage when an `--only` or `--exclude` entry
|
|
doesn't match any id in the bundled manifest, with the offending id
|
|
captured in `err.context.id` so error reporters can show useful
|
|
suggestions. `TARGET_DIR_INVALID` guards against empty or non-string
|
|
answers; under normal use the prompt schema's default value
|
|
(`.suaveplan/skills`) prevents this path entirely, but defensive
|
|
validation ensures programmatic callers can't slip past it.
|