@arcforge/err 2.0.121 → 2.0.123

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.121",
+    "version": "2.0.123",
     "description": "Structured Axon errors — the code map every user-facing failure is rendered from.",
     "type": "module",
     "private": false,
@@ -15,7 +15,7 @@
         "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
     },
     "dependencies": {
-        "@arcforge/types": "2.0.121"
+        "@arcforge/types": "2.0.123"
     },
     "devDependencies": {
         "@types/bun": "latest",

package/src/map.ts

@@ -385,8 +385,8 @@ export const errorMap = {
     },
     PUBLISH_UNSUPPORTED_KIND: {
         code: "AX-PROJECT-009",
-        title: "This Project Kind Cannot Publish Yet",
-        description: "Only agents and modules publish to the registry today. Cognets and benches become first-class registry artifacts in the unified artifact work — until then, publishing one would register it under the wrong kind and claim its name in the shared namespace.",
+        title: "This Project Kind Cannot Publish",
+        description: "The registry accepts agents, modules, cognets, benches and prompts. Extensions are not accepted yet — the `registry_artifact_kind` enum needs the value first, and publishing before then would register under the wrong kind and claim the name in the shared namespace. A profile is never publishable: it holds one person's credentials, history and agents. See KINDS[kind].publishable.",
         source: "manifest",
         severity: "fatal",
     },
@@ -440,14 +440,14 @@ export const errorMap = {
         severity: "fatal",
     },
     DEPLOY_RUNTIME_FAILED: {
-        code: "AX-PROJECT-013",
+        code: "AX-PROJECT-035",
         title: "Agent Failed To Start",
         description: "Cloud infrastructure was provisioned, but the agent process failed during boot. The reported runtime diagnostic identifies the immediate cause.",
         source: "runtime",
         severity: "fatal",
     },
     DEPLOY_ENV_RESERVED: {
-        code: "AX-PROJECT-014",
+        code: "AX-PROJECT-036",
         title: "Reserved Deployment Variable",
         description: "The production .env file attempts to override a variable owned by the Axon runtime or Cloud Run.",
         source: "manifest",
@@ -1336,7 +1336,7 @@ export const errorMap = {
         severity: "fatal",
     },
     MODULE_SETUP_FAILED: {
-        code: "AX-MODULE-003",
+        code: "AX-MODULE-007",
         title: "Module Setup Failed",
         description: "A module's setup() threw during agent boot. Setup runs sequentially in blueprint order and a failure is total — no later module is wired, and the agent does not boot half-configured.",
         source: "runtime",
@@ -1441,7 +1441,7 @@ export const errorMap = {
         severity: "fatal",
     },
     PROMPT_NOT_INSTALLABLE: {
-        code: "AX-PROJECT-032",
+        code: "AX-PROJECT-037",
         title: "Prompts Are Not Installed Into Agents",
         description: "A prompt is content, not a capability: it resolves from the global cache and renders on demand, so every agent can already use it without declaring anything. Installing one into an agent would put content through the code path — an ABI check, a node_modules link, an agent reload — for something that needs none of it.",
         source: "manifest",
@@ -1616,6 +1616,223 @@ export const errorMap = {
         source: "cli",
         severity: "fatal",
     },
+
+    // ── Extensions ──────────────────────────────────────────────────────────
+    //
+    // The TUI config surface: a profile's main.ts and plugins/, and the
+    // extensions it loads. Almost every entry here is `expected` and
+    // `degraded`, and both flags are deliberate.
+    //
+    // EXPECTED, because this is code the USER wrote. A stack trace through our
+    // loader tells someone to debug software they did not write; the file and
+    // the reason are the entire actionable content.
+    //
+    // DEGRADED, because a broken config must never cost someone their
+    // terminal. One bad file disables itself and everything else still loads —
+    // a user whose plugin has a typo needs a working Axon to go fix it in.
+    // The one FATAL entry is PROFILE_CONFIG_INVALID, and only because it is
+    // thrown by the CLI verbs that edit that file, where continuing would mean
+    // writing over a config we could not read.
+
+    PROFILE_CONFIG_INVALID: {
+        code: "AX-EXT-001",
+        title: "profile.config.ts Did Not Call defineProfile()",
+        description: "A profile's config must default-export defineProfile({ ... }). Without it there is no extension list to read, so nothing can be installed, enabled or disabled. The rest of the profile — main.ts and plugins/ — still loads.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PROFILE_CONFIG_FAILED: {
+        code: "AX-EXT-002",
+        title: "profile.config.ts Failed to Load",
+        description: "The file threw while being evaluated, so its extension list could not be read and no extensions were loaded. The profile's own main.ts and plugins/ are unaffected — a typo in an extension list must not cost you the config you already had working.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_ENTRY_INVALID: {
+        code: "AX-EXT-003",
+        title: "Malformed Extension Entry",
+        description: "An entry in profile.config.ts's `extensions` array is neither a string nor an object with a `source`. Accepted forms are \"@scope/name\" for a registry extension and \"./extensions/name\" for a local one.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_NOT_FOUND: {
+        code: "AX-EXT-004",
+        title: "Extension Not Found",
+        description: "An extension listed in profile.config.ts is not on disk. A local path may have moved or been deleted; a registry name may never have been installed. Everything else in the list still loads.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_INSTALL_FAILED: {
+        code: "AX-EXT-005",
+        title: "Extension Install Failed",
+        description: "A registry extension could not be fetched or prepared — most often no network, or a name that does not exist in the registry. It is skipped for this session and retried on the next launch.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_NOT_AN_EXTENSION: {
+        code: "AX-EXT-006",
+        title: "Not an Extension",
+        description: "The directory has no extension.config.ts, which is the file that marks a directory as an extension. A path pointing at an agent, a module, or an ordinary folder is not loadable as one.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    EXTENSION_LOAD_FAILED: {
+        code: "AX-EXT-007",
+        title: "Extension Failed to Load",
+        description: "An extension's main.ts threw while it was being loaded, so whatever it had not yet registered is missing. Its commands, keys and palettes are removed and the rest of your config loads normally.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PROFILE_MAIN_FAILED: {
+        code: "AX-EXT-008",
+        title: "main.ts Failed to Load",
+        description: "Your profile's main.ts threw while being evaluated. Anything it registered before the error survives; everything after it did not run. Plugins and extensions still load.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PLUGIN_FAILED: {
+        code: "AX-EXT-009",
+        title: "Plugin Failed to Load",
+        description: "A file in plugins/ threw while being imported, so its hooks were not registered. Other plugins in the same folder are unaffected — each file is loaded independently.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    HOOK_FAILED: {
+        code: "AX-EXT-010",
+        title: "Lifecycle Hook Failed",
+        description: "A tui.hook() handler threw while the event it listens for was firing. For a notification hook nothing else is affected; for a gating hook (tui:boot, tui:shutdown) the operation continues anyway rather than leaving the terminal stuck.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    HOOK_TIMED_OUT: {
+        code: "AX-EXT-011",
+        title: "Hook Blocked Too Long",
+        description: "A gating hook (tui:boot or tui:shutdown) did not finish within its budget, so the TUI continued without waiting. A config must never be able to hang the terminal silently — whatever the handler was doing may not have completed.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    COMMAND_NOT_FOUND: {
+        code: "AX-EXT-012",
+        title: "No Such Command",
+        description: "commands.run() was given a path that resolves to nothing in the command tree. The path must name a leaf, spelled exactly as it appears in the `:` palette.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PALETTE_NOT_FOUND: {
+        code: "AX-EXT-013",
+        title: "No Such Palette",
+        description: "palette.open() was given a name no palette was registered under. Palettes are created with palette.create(name, ...) — a name is only openable once its registration has run.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PALETTE_NAME_TAKEN: {
+        code: "AX-EXT-014",
+        title: "Palette Name Already Registered",
+        description: "Two palettes tried to claim the same name. Names are how palette.open() addresses one, so they have to be unique — silently replacing the first would make whichever loaded last win, invisibly.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    PALETTE_ALREADY_OPEN: {
+        code: "AX-EXT-015",
+        title: "A Palette Is Already Open",
+        description: "Something tried to open a palette, or ask a question, while the user was already navigating one. Stealing it mid-navigation would drop whatever they were doing, so the call fails instead — check palette.isOpen first.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    KEY_CHORD_UNBOUND: {
+        code: "AX-EXT-022",
+        title: "No Such Key Binding",
+        description: "keys.send() was given a chord nothing is bound to — neither a mode key nor a registered binding. Sending it would do nothing at all, which is indistinguishable from a binding that ran and had no effect.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    AGENT_SPAWN_NO_INSTANCE: {
+        code: "AX-EXT-023",
+        title: "Agent Started but No Instance Appeared",
+        description: "A spawn reported success without producing a focused instance, so there is no id to hand back. This is a fault in Axon rather than in your config — the agent may or may not be running.",
+        source: "tui",
+        severity: "fatal",
+    },
+    PROFILE_CONFIG_MISSING: {
+        code: "AX-EXT-025",
+        title: "No profile.config.ts",
+        description: "The profile has no config file to record the extension in. It is normally created on first launch — starting Axon once will scaffold it.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    PROFILE_CONFIG_UNEDITABLE: {
+        code: "AX-EXT-026",
+        title: "profile.config.ts Could Not Be Edited",
+        description: "The `extensions` array could not be located, or editing it would have produced invalid TypeScript. Nothing was written — this file is yours, and a botched edit costs your whole TUI config. Add or remove the entry by hand.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    COMMAND_PATH_TAKEN: {
+        code: "AX-EXT-020",
+        title: "Command Already Registered",
+        description: "Two sources registered the same command path. The first one loaded keeps it — your own config beats any extension, and between extensions the one listed earlier in profile.config.ts wins. Rename one of them.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    KEY_CHORD_TAKEN: {
+        code: "AX-EXT-021",
+        title: "Key Chord Already Bound",
+        description: "Two sources bound the same key chord. The first one loaded keeps it. A silently shadowed binding is unbearable to debug in someone else's config, so the second registration fails instead of replacing it.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    MODE_KEY_TAKEN: {
+        code: "AX-EXT-016",
+        title: "Mode Key Already Bound",
+        description: "A palette asked for a mode key that is already in use — either by a built-in mode or by another extension. A silently shadowed key is unbearable to debug in someone else's config, so the registration fails loudly instead.",
+        source: "tui",
+        severity: "degraded",
+        expected: true,
+    },
+    MODE_UNKNOWN: {
+        code: "AX-EXT-017",
+        title: "No Such Mode",
+        description: "mode.set() was given a name that is neither a built-in mode nor a registered palette. Doing nothing would look identical to a mode that simply does not render, so this fails instead.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    NO_FOCUSED_AGENT: {
+        code: "AX-EXT-018",
+        title: "No Agent Focused",
+        description: "A verb that acts on the focused agent — send, stop, reboot — was called while nothing was running. Start one with agents.spawn(name) or tui.nav(name) first.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
+    INSTANCE_NOT_RUNNING: {
+        code: "AX-EXT-019",
+        title: "Instance Not Running",
+        description: "An instance id was given for a conversation that is not live — it may already have been stopped, or it belongs to an earlier session. agents.list() returns what is currently running.",
+        source: "tui",
+        severity: "fatal",
+        expected: true,
+    },
 } as const satisfies Record<string, AxonErrorMapEntry>
 
 export type AxonErrorMap = typeof errorMap