`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

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

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.

2.9 KiB Raw Blame History

error-codes