@gluecharm-lab/easyspecs-cli 0.0.16 → 0.0.18

package/error-code.md

@@ -0,0 +1,113 @@
+# EasySpecs CLI — error codes
+
+Single reference for **process exit codes**, structured **`failureExitId`** subcodes, and how they appear in **`--json`** and stderr. **Normative requirements:** umbrella CLI exit taxonomy **[SRS-39](../../.gluecharm/docs/srs/srs-39.md)** (**R1.3**) is implemented in [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts); factory-phase validation ids **[SRS-57](../../.gluecharm/docs/srs/srs-57.md)**; cross-factory structured errors **[SRS-58](../../.gluecharm/docs/srs/srs-58.md)** and **[PLAN-SRS-58](../../.gluecharm/docs/srs/PLAN-SRS-58.md)**.
+
+**Maintenance:** When you add a **`failureExitId`** or change **`describeExitCode`**, update this file **in the same change** as [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts) and the central registry (**[`failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts)** when SRS-58 lands). **Do not** change numeric OS exit codes without an SRS amendment (**SRS-39 R1.3**).
+
+---
+
+## 1. Process exit codes (OS / `process.exit`)
+
+These are the **only** integers the CLI returns. Everything else (**`5.3`**, **`3.1`**, …) is **metadata** in JSON or stderr, **not** a second process exit status.
+
+| Code | Name (internal) | Meaning |
+|:----:|-----------------|--------|
+| **0** | `ok` | Success. |
+| **2** | `usage` | Invalid arguments, unknown subcommand, or help could not be shown as requested. |
+| **3** | `misconfiguration` | Configuration, repo layout, missing prerequisites, or paths that prevent starting work. |
+| **4** | `opencode` | OpenCode (agent runner) failed — install, credentials, or tool run. |
+| **5** | `validation` | Validation or factory pipeline did not succeed (synthesis, coverage, index, drift write, etc.). |
+| **6** | `auth` | Authentication failed or session missing. |
+| **7** | `upload` | Upload or cloud sync failed. |
+| **8** | `cancelled` | Operation cancelled (abort/stop). |
+| **99** | `internal` | Unexpected internal CLI error. |
+| **other** | — | Treated as unknown failure; see stderr and JSON **`error`**. |
+
+**Default human line** when **`factoryFailures`** is absent (from **`describeExitCode`** in **`exitCodes.ts`**):
+
+| Code | One-line summary |
+|------|------------------|
+| 2 | Invalid arguments, unknown command, or help was not applicable — see message above or run `easyspecs-cli help`. |
+| 3 | Configuration or repo layout problem — fix `.easyspecs/config.json`, paths, or prerequisites, then retry. |
+| 4 | OpenCode (agent runner) failed — check `opencode` install, credentials, and stderr from the tool run. |
+| 5 | Validation or factory pipeline did not succeed — see `error` above and logs for the failing phase. |
+| 6 | Authentication failed or session missing — run `easyspecs-cli auth login` or fix CI credentials in config. |
+| 7 | Upload or cloud sync failed — check network, project id, and session; see `error` above. |
+| 8 | Operation was cancelled (abort/stop). |
+| 99 | Unexpected internal CLI error — retry; if it persists, report with full stderr and `--verbose` output. |
+
+When **`factoryFailures`** is present, **`exitMeaning`** in **`--json`** and the primary stderr summary should be driven by **`factoryFailures[0].title`** (per SRS-57 / SRS-58), not only the generic row above.
+
+---
+
+## 2. Structured IDs: `failureExitId`
+
+Format: **`{major}.{minor}`** where:
+
+- **`major`** = decimal string of the **same** OS exit code used for **`process.exit`** (e.g. **`5`**, **`3`**).
+- **`minor`** = stable integer assigned **per major** in the registry (no reuse for unrelated meanings).
+
+**Aliases:**
+
+- For **`exitCode === 5`**, **`validationExitId`** (SRS-57) **must** equal **`failureExitId`** on that row.
+
+**JSON shape (each element of `factoryFailures`):**
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `factory` | yes | e.g. `generate_context`, `context_drift` |
+| `phase` | yes | Pipeline key within that factory |
+| `exitCode` | yes | Same as top-level exit when single-cause |
+| `failureExitId` | yes | `major.minor` |
+| `title` | yes | Normative one-line explanation |
+| `validationExitId` | when exit 5 | Same as `failureExitId` |
+| `detail` | no | Technical tail |
+| `validationSubcode` | no | Non-localized token (e.g. threshold class) |
+
+---
+
+## 3. `failureExitId` tables by scope
+
+### 3.1 Generate Context factory (`analysis`)
+
+**`5.0`–`5.9`** — pipeline phases (synthesis worktree through cloud sync). Full **`phase` ↔ id ↔ title** table: **[SRS-57 §6.1–6.2](../../.gluecharm/docs/srs/srs-57.md)** and [commands.md](./commands.md) (Factory validation reporting).
+
+### 3.2 Context drift factory (`context drift`)
+
+Implementation: [`failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts). **`INVALID_REFERENCE_PATH`** resolves to **`3.1`** or **`3.2`** (bad **`--index`**) using the error text.
+
+| Drift `code` | Phase | OS exit | `failureExitId` |
+|--------------|-------|---------|-----------------|
+| `INVALID_REFERENCE_PATH` | `resolve_reference_bundle` or `resolve_reference_root` | 3 | **3.1** / **3.2** |
+| `WORKTREE_PREP_FAILED` | `prepare_analysis_worktree` | 3 | **3.3** |
+| `AGENT_FAILED` | `run_drift_analysis` | 4 | **4.1** |
+| `INVALID_AGENT_PAYLOAD` | `validate_and_render_report` | 4 | **4.2** |
+| `EMPTY_BUNDLE` | `resolve_reference_bundle` | 5 | **5.10** |
+| `UNRESOLVED_REFERENCE_ROOT` | `resolve_reference_root` | 5 | **5.11** |
+| `MANIFEST_FAILED` | `build_comparison_manifest` | 5 | **5.12** |
+| `REPORT_WRITE_FAILED` | `validate_and_render_report` | 5 | **5.13** |
+| `INDEX_PATCH_FAILED` | `update_reference_index` | 5 | **5.14** |
+| `PROMOTE_FAILED` | `promote_drift_artefacts` | 7 | **7.1** |
+
+### 3.3 Other commands
+
+Diagnostics, **`context link-graph`**, **`upload`**, etc. may exit **2–7** or **99** without **`factoryFailures`**. Use **§1** and the stderr **`error`** field. Reserved **`5.10`–`5.99`** for non–Generate-Context validation is described in **SRS-57 §6.3** and **SRS-58**.
+
+---
+
+## 4. Related files
+
+| File | Role |
+|------|------|
+| [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts) | `ExitCode`, `describeExitCode` |
+| [`src/factory/factoryValidationFailures.ts`](../../src/factory/factoryValidationFailures.ts) | Generate Context **`factoryFailures`** build + titles **5.0–5.9** |
+| [`src/cli/jsonReporter.ts`](../../src/cli/jsonReporter.ts) | JSON envelope typing |
+| [commands.md](./commands.md) | Per-command behaviour and flags |
+
+---
+
+## 5. Revision history
+
+| Date | Notes |
+|------|--------|
+| 2026-05-06 | Initial **`error-code.md`**: OS codes + **`failureExitId`** rules + pointers; sub-tables to be filled from registry as SRS-58 ships. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gluecharm-lab/easyspecs-cli",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "EasySpecs headless CLI (synthesis, analysis, diagnose, download/upload context, auth, ACE)",
   "license": "Elastic-2.0",
   "homepage": "https://easyspecs.ai/",
@@ -17,6 +17,7 @@
     "LICENSE",
     "README.md",
     "commands.md",
+    "error-code.md",
     "dist",
     "resources"
   ],