@arcforge/err 2.0.103 → 2.0.105

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.103",
+    "version": "2.0.105",
     "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.103"
+        "@arcforge/types": "2.0.105"
     },
     "devDependencies": {
         "@types/bun": "latest",

package/src/map.ts

@@ -210,7 +210,7 @@ export const errorMap = {
         severity: "fatal",
     },
 
-    // ── Project (build/project/dependencies.ts) ─────────────────────────────
+    // ── Project (build/project/) ────────────────────────────────────────────
     MODULE_SPECIFIER_INVALID: {
         code: "AX-PROJECT-005",
         title: "Invalid Module Specifier",
@@ -249,12 +249,19 @@ export const errorMap = {
         severity: "fatal",
     },
     CORRUPT_JSON: {
-        code: "AX-PROJECT-004",
+        code: "AX-PROJECT-016",
         title: "Corrupt JSON File",
         description: "A stored JSON file failed to parse — it may have been hand-edited into an invalid state, or a write was interrupted mid-flight.",
         source: "manifest",
         severity: "fatal",
     },
+    FILE_UNREADABLE: {
+        code: "AX-PROJECT-032",
+        title: "File Could Not Be Read",
+        description: "A file exists but could not be read — most often a permissions problem, a directory where a file was expected, or a disk error. Distinct from a missing file, which is an ordinary absent-surface state.",
+        source: "manifest",
+        severity: "fatal",
+    },
     PROVIDER_NOT_CONNECTED: {
         code: "AX-TUI-011",
         title: "Provider Not Connected",
@@ -279,7 +286,7 @@ export const errorMap = {
 
     // ── Project (build/project/*.ts) ────────────────────────────────────────
     PROJECT_NOT_FOUND: {
-        code: "AX-PROJECT-005",
+        code: "AX-PROJECT-017",
         title: "Project Not Found",
         description: "No axon.config.ts, module.config.ts, cognet.config.ts, bench.config.ts, or prompt.config.ts was found at this path — it isn't a recognized project directory.",
         source: "manifest",
@@ -293,7 +300,7 @@ export const errorMap = {
         severity: "fatal",
     },
     PROJECT_EXISTS: {
-        code: "AX-PROJECT-006",
+        code: "AX-PROJECT-018",
         title: "Project Already Exists",
         description: "Scaffolding refused to overwrite a directory that already exists — remove it or pick a different name first.",
         source: "manifest",
@@ -349,7 +356,7 @@ export const errorMap = {
         severity: "fatal",
     },
     BUNDLE_MODULE_COLLISION: {
-        code: "AX-PROJECT-009",
+        code: "AX-PROJECT-019",
         title: "Module Name Collision",
         description: "A hard-imported source module's name collides with an already-installed registry module of the same name.",
         source: "manifest",
@@ -363,14 +370,14 @@ export const errorMap = {
         severity: "fatal",
     },
     BUNDLE_TAR_MISSING: {
-        code: "AX-PROJECT-011",
+        code: "AX-PROJECT-020",
         title: "tar Not Found",
         description: "Bundling shells out to the system's tar binary, which isn't on PATH — install Git for Windows or use WSL on that platform.",
         source: "manifest",
         severity: "fatal",
     },
     BUNDLE_TAR_FAILED: {
-        code: "AX-PROJECT-012",
+        code: "AX-PROJECT-021",
         title: "tar Failed",
         description: "The tar subprocess exited non-zero while building a bundle archive.",
         source: "manifest",
@@ -923,7 +930,7 @@ export const errorMap = {
         severity: "degraded",
     },
 
-    // ── TUI (useAgents.ts / platform/build/agent / platform/store / platform/services/cloud) ──
+    // ── TUI (useAgents.ts / platform/build/runtime / platform/store / platform/services/cloud) ──
     NOT_BOOTED: {
         code: "AX-TUI-001",
         title: "No Agent Running",
@@ -1136,6 +1143,221 @@ export const errorMap = {
         source: "runtime",
         severity: "fatal",
     },
+
+    // ── Registry retrieval (build/registry.ts) ──────────────────────────────
+    CLONE_REF_REQUIRED: {
+        code: "AX-PROJECT-022",
+        title: "No Artifact Named",
+        description: "`axon clone` was run without an artifact to clone. Name one, for example: axon clone @axon/arxiv",
+        source: "cli",
+        severity: "fatal",
+    },
+    FORK_REF_REQUIRED: {
+        code: "AX-PROJECT-023",
+        title: "No Artifact Named",
+        description: "`axon fork` was run without an artifact to fork. Name one, for example: axon fork @axon/arxiv --as @you/arxiv",
+        source: "cli",
+        severity: "fatal",
+    },
+    FORK_NAME_REQUIRED: {
+        code: "AX-PROJECT-024",
+        title: "Fork Needs A New Name",
+        description: "A fork is published under your own namespace, so it needs a name: pass --as <package-name>, for example: axon fork @axon/arxiv --as @you/arxiv",
+        source: "cli",
+        severity: "fatal",
+    },
+    CLONE_TARGET_EXISTS: {
+        code: "AX-PROJECT-025",
+        title: "Clone Target Not Empty",
+        description: "The directory the artifact would be cloned into already has files in it. Clone into a new directory, or clear this one first.",
+        source: "cli",
+        severity: "fatal",
+    },
+    ARTIFACT_DOWNLOAD_FAILED: {
+        code: "AX-PROJECT-026",
+        title: "Artifact Download Failed",
+        description: "The registry did not serve the artifact's source archive. The version may have been unpublished, or the network request failed.",
+        source: "cli",
+        severity: "fatal",
+    },
+    ARTIFACT_EXTRACT_FAILED: {
+        code: "AX-PROJECT-027",
+        title: "Artifact Extract Failed",
+        description: "The downloaded archive could not be unpacked. It may be truncated, or `tar` is unavailable on this machine.",
+        source: "cli",
+        severity: "fatal",
+    },
+
+    // ── Project frame (build/project/) ──────────────────────────────────────
+    VERSION_INVALID: {
+        code: "AX-PROJECT-028",
+        title: "Invalid Version",
+        description: "The project's package.json version is not valid semver, so the next version cannot be derived from it. Fix the version field by hand.",
+        source: "cli",
+        severity: "fatal",
+    },
+    FRAMEWORK_NOT_INSTALLED: {
+        code: "AX-PROJECT-029",
+        title: "Framework Packages Not Installed",
+        description: "The generated type frame references @arcforge/types, @arcforge/engines and h3, none of which resolve from this project. Run `bun install` before `axon prepare`.",
+        source: "cli",
+        severity: "fatal",
+    },
+    CONFIG_EVALUATION_ESCAPED: {
+        code: "AX-PROJECT-030",
+        title: "defineAgent() Called Outside Config Evaluation",
+        description: "defineAgent() ran outside the loader that evaluates axon.config.ts — it is a declaration helper, not a runtime function, and cannot be called from application code.",
+        source: "cli",
+        severity: "fatal",
+    },
+    PORT_UNAVAILABLE: {
+        code: "AX-PROJECT-031",
+        title: "No Free Port",
+        description: "Every port in the range the agent scanned is already in use. Stop whatever is holding them, or start the agent on a different port.",
+        source: "cli",
+        severity: "fatal",
+    },
+
+    // ── Subagents (build/agent/agents.ts) ───────────────────────────────────
+    PARENT_INSTANCE_NOT_RUNNING: {
+        code: "AX-RUNTIME-005",
+        title: "Parent Agent Not Running",
+        description: "A subagent was requested against a parent session that is no longer live — the parent shut down, crashed, or was never booted by this process.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SUBAGENT_DEPTH_EXCEEDED: {
+        code: "AX-RUNTIME-006",
+        title: "Subagent Depth Limit Reached",
+        description: "An agent tried to spawn a subagent beyond the maximum nesting depth. The limit exists so a recursive delegation cannot spawn processes without bound.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SUBAGENT_CHILD_LIMIT_EXCEEDED: {
+        code: "AX-RUNTIME-007",
+        title: "Subagent Child Limit Reached",
+        description: "One agent tried to hold more live children than the limit allows. Existing children must finish before more can be spawned.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SUBAGENT_DESCENDANT_LIMIT_EXCEEDED: {
+        code: "AX-RUNTIME-008",
+        title: "Subagent Descendant Limit Reached",
+        description: "The whole subagent tree beneath one root exceeded its live-descendant budget. The limit bounds total concurrent processes, not just direct children.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SUBAGENT_REQUEST_INVALID: {
+        code: "AX-RUNTIME-009",
+        title: "Malformed Subagent Request",
+        description: "A subagent request did not carry a usable prompt. It must be an object with `prompt` as a string or an array of strings.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    INSTANCE_NOT_LOCAL: {
+        code: "AX-RUNTIME-010",
+        title: "Agent Instance Is Not Local",
+        description: "An operation that only works against a locally booted agent was given a remote one. Subagent spawning and the managed base workspace both require a local process.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    HOST_METHOD_UNKNOWN: {
+        code: "AX-RUNTIME-011",
+        title: "Unknown Host Method",
+        description: "A booted agent called a host method this platform does not implement. The agent's framework version is likely newer than the CLI running it.",
+        source: "runtime",
+        severity: "fatal",
+    },
+
+    // ── Self-update (update/) ───────────────────────────────────────────────
+    UPDATE_CURRENT_VERSION_INVALID: {
+        code: "AX-TUI-029",
+        title: "Running Version Is Not Semver",
+        description: "The version this app reports for itself is not valid semver, so it cannot be compared against the latest release.",
+        source: "cli",
+        severity: "fatal",
+    },
+    UPDATE_RELEASE_INVALID: {
+        code: "AX-TUI-030",
+        title: "Malformed Release Record",
+        description: "The backend's release record did not describe a valid @arcforge/axon `latest` version, so there is nothing safe to update to.",
+        source: "cli",
+        severity: "fatal",
+    },
+    UPDATE_UNAVAILABLE_IN_DEVELOPMENT: {
+        code: "AX-TUI-031",
+        title: "Update Not Available Here",
+        description: "Self-update needs the packaged update helper and a supervisor request path, neither of which exists in a source checkout. Update the installed app instead.",
+        source: "cli",
+        severity: "fatal",
+    },
+    UPDATE_SUPERVISOR_UNAVAILABLE: {
+        code: "AX-TUI-032",
+        title: "Update Supervisor Unavailable",
+        description: "The running app has no supervisor request path, so it cannot hand an update off to be applied after exit.",
+        source: "cli",
+        severity: "fatal",
+    },
+    UPDATE_HELPER_ARGS_INVALID: {
+        code: "AX-TUI-033",
+        title: "Malformed Update Helper Arguments",
+        description: "The update helper was invoked without the --from/--to/--bun/--axon/--state arguments it requires. It is spawned by the app, not run by hand.",
+        source: "cli",
+        severity: "fatal",
+    },
+    UPDATE_HELPER_VERSION_INVALID: {
+        code: "AX-TUI-034",
+        title: "Update Helper Given Bad Versions",
+        description: "The update helper received a --from or --to value that is not valid semver, so it refused to install anything.",
+        source: "cli",
+        severity: "fatal",
+    },
+
+    // ── Test runner (test/) ─────────────────────────────────────────────────
+    TEST_FILES_NOT_FOUND: {
+        code: "AX-TUI-035",
+        title: "No Test Files Matched",
+        description: "No files matched the requested test patterns, so there was nothing to run. Check the pattern, or the directory it was resolved against.",
+        source: "cli",
+        severity: "fatal",
+    },
+    // ── Ollama (services/ollama/) ───────────────────────────────────────────
+    OLLAMA_UNAVAILABLE: {
+        code: "AX-TUI-037",
+        title: "Ollama Is Not Running",
+        description: "No Ollama daemon answered on this machine. Start it with `ollama serve`, or install Ollama from https://ollama.com to run models locally.",
+        source: "cli",
+        severity: "fatal",
+    },
+    OLLAMA_REQUEST_FAILED: {
+        code: "AX-TUI-038",
+        title: "Ollama Request Failed",
+        description: "The local Ollama daemon is running but refused a request — most often an unknown model name. The daemon's own message is included.",
+        source: "cli",
+        severity: "fatal",
+    },
+    OLLAMA_REGISTRY_UNREACHABLE: {
+        code: "AX-TUI-039",
+        title: "Ollama Registry Unreachable",
+        description: "Could not reach the Ollama model registry to look a model up. Downloading needs a network connection; models already on disk still work offline.",
+        source: "cli",
+        severity: "fatal",
+    },
+    OLLAMA_PULL_FAILED: {
+        code: "AX-TUI-040",
+        title: "Model Download Failed",
+        description: "Ollama could not finish downloading the model. The name may not exist in the registry, or the transfer was interrupted — a retry resumes from whatever was already fetched.",
+        source: "cli",
+        severity: "fatal",
+    },
+
+    TEST_PRELOAD_MISSING: {
+        code: "AX-TUI-036",
+        title: "Test API Loaded Without Its Preload",
+        description: "The instrumented test API was imported without the preload that installs it. Tests must run through `axon test`, which wires the preload.",
+        source: "cli",
+        severity: "fatal",
+    },
 } as const satisfies Record<string, AxonErrorMapEntry>
 
 export type AxonErrorMap = typeof errorMap