@gluecharm-lab/easyspecs-cli 0.0.27 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +1 -1
  2. package/commands.md +13 -11
  3. package/dist/main.cjs +213 -90
  4. package/dist/main.cjs.map +3 -3
  5. package/error-code.md +75 -81
  6. package/package.json +1 -1
package/error-code.md CHANGED
@@ -1,99 +1,91 @@
1
1
  # EasySpecs CLI — error codes
2
2
 
3
- 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)**.
3
+ Single reference for **process exit codes**, structured **`failureExitId`** subcodes, and how they appear in **`--json`** and stderr. **Normative:** **[SRS-39](../../.gluecharm/docs/srs/srs-39.md)** (**R1.3**), **[SRS-70](../../.gluecharm/docs/srs/srs-70.md)** / **[PLAN-SRS-70](../../.gluecharm/docs/srs/PLAN-SRS-70.md)** (retired OS **5**; dedicated integers **49–83**), **[SRS-57](../../.gluecharm/docs/srs/srs-57.md)**, **[SRS-58](../../.gluecharm/docs/srs/srs-58.md)**.
4
4
 
5
- **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**).
5
+ **Maintenance:** When you add an **`OsExit`** value or change **`describeExitCode`**, update this file **in the same change** as [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts), [`src/factory/factoryValidationFailures.ts`](../../src/factory/factoryValidationFailures.ts), and [`src/cli/failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts).
6
6
 
7
7
  ---
8
8
 
9
9
  ## 1. Process exit codes (OS / `process.exit`)
10
10
 
11
- 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.
12
-
13
- | Code | Name (internal) | Meaning |
14
- |:----:|-----------------|--------|
15
- | **0** | `ok` | Success. |
16
- | **2** | `usage` | Invalid arguments, unknown subcommand, or help could not be shown as requested. |
17
- | **3** | `misconfiguration` | Configuration, repo layout, missing prerequisites, or paths that prevent starting work. |
18
- | **4** | `opencode` | OpenCode (agent runner) failed — install, credentials, or tool run. |
19
- | **5** | `validation` | Validation or factory pipeline did not succeed (synthesis, coverage, index, drift write, etc.). |
20
- | **6** | `auth` | Authentication failed or session missing. |
21
- | **7** | `upload` | Upload or cloud sync failed. |
22
- | **8** | `cancelled` | Operation cancelled (abort/stop). |
23
- | **99** | `internal` | Unexpected internal CLI error. |
24
- | **other** | — | Treated as unknown failure; see stderr and JSON **`error`**. |
25
-
26
- **SRS-61:** Failures thrown as plain-object **`HttpApiError`** from authenticated **`requestJson`** (HTTP non-OK, missing **`apiBaseUrl`**, etc.) are formatted with a readable **`error`** string (never **`[object Object]`**). When the value includes a numeric **`status`**, the CLI may exit **6** (**auth**, e.g. **401**), **7** (**upload**, **400–599** except **401**), or **3** (**misconfiguration**, **`status === 0`**) instead of **99**. **99** remains for throws that are not that shape (true unexpected errors). |
27
-
28
- **Default human line** when **`factoryFailures`** is absent (from **`describeExitCode`** in **`exitCodes.ts`**):
29
-
30
- | Code | One-line summary |
31
- |------|------------------|
32
- | 2 | Invalid arguments, unknown command, or help was not applicable — see message above or run `easyspecs-cli help`. |
33
- | 3 | Configuration or repo layout problem — fix `.easyspecs/config.json`, paths, or prerequisites, then retry. |
34
- | 4 | OpenCode (agent runner) failed — check `opencode` install, credentials, and stderr from the tool run. |
35
- | 5 | Validation or factory pipeline did not succeed — see `error` above and logs for the failing phase. |
36
- | 6 | Authentication failed or session missing — run `easyspecs-cli auth login` or fix CI credentials in config. |
37
- | 7 | Upload or cloud sync failed — check network, project id, and session; see `error` above. |
38
- | 8 | Operation was cancelled (abort/stop). |
39
- | 99 | Unexpected internal CLI error — retry; if it persists, report with full stderr and `--verbose` output. |
40
-
41
- 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.
11
+ **Breaking (SRS-70):** The CLI **never** exits with **OS code `5`**. Former “validation / factory pipeline” outcomes use **dedicated integers** (**49–83**) so **`$?`** in CI is actionable without parsing JSON.
12
+
13
+ **`failureExitId`:** string **`{major}.{minor}`** where **`major`** is the **decimal digits of the same integer** passed to **`process.exit`**.
14
+
15
+ | Code | Meaning |
16
+ |:----:|--------|
17
+ | **0** | Success. |
18
+ | **2** | Usage — invalid arguments, unknown subcommand, help not applicable. |
19
+ | **3** | Misconfiguration — config, repo layout, prerequisites, paths. |
20
+ | **4** | OpenCode (agent runner) failed. |
21
+ | **6** | Auth — session / token / login. |
22
+ | **7** | Upload / cloud sync failed. |
23
+ | **8** | Cancelled. |
24
+ | **99** | Internal unexpected error. |
25
+ | **49** | Factory unknown / unclassified failure. |
26
+ | **50–58** | Generate Context — one code per pipeline phase (worktree → cloud sync). |
27
+ | **59** | Multiple failed generate_context phases with **distinct** phase codes in one run (rollup). |
28
+ | **60–64** | Context drift — validation-class drift outcomes (see §3.2). |
29
+ | **70–79** | `diagnose` / `context link-graph` / `run synthesis resume-*` index failures (see **PLAN-SRS-70 §2.4**). |
30
+ | **80** | `run synthesis` (standalone pipeline) failed. |
31
+ | **81–82** | `ace learn` / `ace auto-learn` failures. |
32
+ | **83** | `update context` factory failure. |
33
+
34
+ **SRS-61:** HTTP **`HttpApiError`** handling unchanged — may map to **3**, **6**, **7**, or **99** per existing rules.
35
+
36
+ One-line summaries for **49–83** live in **`describeExitCode`** in **`exitCodes.ts`**.
42
37
 
43
38
  ---
44
39
 
45
- ## 2. Structured IDs: `failureExitId`
40
+ ## 2. Structured IDs: `failureExitId` / `validationExitId`
46
41
 
47
- Format: **`{major}.{minor}`** where:
42
+ - **`failureExitId`:** required; **`major`** = OS exit for this invocation (after finalize all `factoryFailures[].exitCode` match **`process.exit`** per PLAN-SRS-58).
43
+ - **`validationExitId`:** legacy JSON alias; **mirrors `failureExitId`** when present (SRS-70).
48
44
 
49
- - **`major`** = decimal string of the **same** OS exit code used for **`process.exit`** (e.g. **`5`**, **`3`**).
50
- - **`minor`** = stable integer assigned **per major** in the registry (no reuse for unrelated meanings).
51
-
52
- **Aliases:**
53
-
54
- - For **`exitCode === 5`**, **`validationExitId`** (SRS-57) **must** equal **`failureExitId`** on that row.
55
-
56
- **JSON shape (each element of `factoryFailures`):**
57
-
58
- | Field | Required | Notes |
59
- |-------|----------|--------|
60
- | `factory` | yes | e.g. `generate_context`, `context_drift` |
61
- | `phase` | yes | Pipeline key within that factory |
62
- | `exitCode` | yes | Same as top-level exit when single-cause |
63
- | `failureExitId` | yes | `major.minor` |
64
- | `title` | yes | Normative one-line explanation |
65
- | `validationExitId` | when exit 5 | Same as `failureExitId` |
66
- | `detail` | no | Technical tail |
67
- | `validationSubcode` | no | Non-localized token (e.g. threshold class) |
45
+ **JSON `factoryFailures[]` row:** `factory`, `phase`, `exitCode`, `failureExitId`, `title`, optional `detail`, `validationSubcode`, optional `validationExitId` (duplicate).
68
46
 
69
47
  ---
70
48
 
71
- ## 3. `failureExitId` tables by scope
72
-
73
- ### 3.1 Generate Context factory (`analysis`)
74
-
75
- **`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).
76
-
77
- ### 3.2 Context drift factory (`context drift`)
78
-
79
- Implementation: [`failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts). **`INVALID_REFERENCE_PATH`** resolves to **`3.1`** or **`3.2`** (bad **`--index`**) using the error text.
80
-
81
- | Drift `code` | Phase | OS exit | `failureExitId` |
82
- |--------------|-------|---------|-----------------|
83
- | `INVALID_REFERENCE_PATH` | `resolve_reference_bundle` or `resolve_reference_root` | 3 | **3.1** / **3.2** |
84
- | `WORKTREE_PREP_FAILED` | `prepare_analysis_worktree` | 3 | **3.3** |
85
- | `AGENT_FAILED` | `run_drift_analysis` | 4 | **4.1** |
86
- | `INVALID_AGENT_PAYLOAD` | `validate_and_render_report` | 4 | **4.2** |
87
- | `EMPTY_BUNDLE` | `resolve_reference_bundle` | 5 | **5.10** |
88
- | `UNRESOLVED_REFERENCE_ROOT` | `resolve_reference_root` | 5 | **5.11** |
89
- | `MANIFEST_FAILED` | `build_comparison_manifest` | 5 | **5.12** |
90
- | `REPORT_WRITE_FAILED` | `validate_and_render_report` | 5 | **5.13** |
91
- | `INDEX_PATCH_FAILED` | `update_reference_index` | 5 | **5.14** |
92
- | `PROMOTE_FAILED` | `promote_drift_artefacts` | 7 | **7.1** |
49
+ ## 3. Tables by scope
50
+
51
+ ### 3.1 Generate Context (`analysis`)
52
+
53
+ | Phase (`factoryFailures[].phase`) | OS exit | `failureExitId` (single-phase) |
54
+ |-----------------------------------|--------:|-------------------------------|
55
+ | `unknown_factory_phase` | **49** | `49.0` |
56
+ | `create_analysis_worktree` | **50** | `50.0` |
57
+ | `materialize_opencode_agents` | **51** | `51.0` |
58
+ | `synthesis_convergence` | **52** | `52.0` |
59
+ | `reference_coverage` | **53** | `53.0` |
60
+ | `zero_reference_remediation_convergence` | **54** | `54.0` |
61
+ | `reference_coverage_execution_report` | **55** | `55.0` |
62
+ | `link_mapping_pipeline` | **56** | `56.0` |
63
+ | `assemble_application_context_index` | **57** | `57.0` |
64
+ | `backend_context_sync` | **58** | `58.0` |
65
+
66
+ Multiple distinct failures → **`process.exit(59)`**, **`failureExitId`** `59.0`, `59.1`, …
67
+
68
+ ### 3.2 Context drift (`context drift`)
69
+
70
+ [`failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts). **`INVALID_REFERENCE_PATH`** resolves to **3.1** / **3.2** via error text.
71
+
72
+ | Drift `code` | OS exit | `failureExitId` |
73
+ |--------------|--------:|-----------------|
74
+ | `INVALID_REFERENCE_PATH` (bundle) | 3 | **3.1** |
75
+ | `INVALID_REFERENCE_PATH` (`--index`) | 3 | **3.2** |
76
+ | `WORKTREE_PREP_FAILED` | 3 | **3.3** |
77
+ | `AGENT_FAILED` | 4 | **4.1** |
78
+ | `INVALID_AGENT_PAYLOAD` | 4 | **4.2** |
79
+ | `EMPTY_BUNDLE` | **60** | **60.0** |
80
+ | `UNRESOLVED_REFERENCE_ROOT` | **61** | **61.0** |
81
+ | `MANIFEST_FAILED` | **62** | **62.0** |
82
+ | `REPORT_WRITE_FAILED` | **63** | **63.0** |
83
+ | `INDEX_PATCH_FAILED` | **64** | **64.0** |
84
+ | `PROMOTE_FAILED` | 7 | **7.1** |
93
85
 
94
86
  ### 3.3 Other commands
95
87
 
96
- 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**.
88
+ See **PLAN-SRS-70 §2.4–2.6** for **`diagnose`**, **`run synthesis`**, **`ace`**, **`update context`** integers **70–83**.
97
89
 
98
90
  ---
99
91
 
@@ -101,10 +93,11 @@ Diagnostics, **`context link-graph`**, **`upload`**, etc. may exit **2–7** or
101
93
 
102
94
  | File | Role |
103
95
  |------|------|
104
- | [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts) | `ExitCode`, `describeExitCode` |
105
- | [`src/factory/factoryValidationFailures.ts`](../../src/factory/factoryValidationFailures.ts) | Generate Context **`factoryFailures`** build + titles **5.0–5.9** |
96
+ | [`src/cli/exitCodes.ts`](../../src/cli/exitCodes.ts) | `ExitCode`, `OsExit`, `describeExitCode`, `failureExitIdFromParts`, `isSrs70FactoryOrDiagnoseExit` |
97
+ | [`src/factory/factoryValidationFailures.ts`](../../src/factory/factoryValidationFailures.ts) | Generate Context **`factoryFailures`**, rollup **59** |
98
+ | [`src/cli/failureExitRegistry.ts`](../../src/cli/failureExitRegistry.ts) | Context drift registry |
106
99
  | [`src/cli/jsonReporter.ts`](../../src/cli/jsonReporter.ts) | JSON envelope typing |
107
- | [commands.md](./commands.md) | Per-command behaviour and flags |
100
+ | [commands.md](./commands.md) | Per-command behaviour |
108
101
 
109
102
  ---
110
103
 
@@ -112,4 +105,5 @@ Diagnostics, **`context link-graph`**, **`upload`**, etc. may exit **2–7** or
112
105
 
113
106
  | Date | Notes |
114
107
  |------|--------|
115
- | 2026-05-06 | Initial **`error-code.md`**: OS codes + **`failureExitId`** rules + pointers; sub-tables to be filled from registry as SRS-58 ships. |
108
+ | 2026-05-06 | Initial **`error-code.md`**. |
109
+ | 2026-05-13 | **SRS-70:** retire OS **5**; document **49–83**; drift **60–64**; rollup **59**. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gluecharm-lab/easyspecs-cli",
3
- "version": "0.0.27",
3
+ "version": "0.1.1",
4
4
  "description": "EasySpecs headless CLI (synthesis, analysis, diagnose, download/upload context, auth, ACE)",
5
5
  "license": "Elastic-2.0",
6
6
  "homepage": "https://easyspecs.ai/",