@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.
- package/README.md +1 -1
- package/commands.md +13 -11
- package/dist/main.cjs +213 -90
- package/dist/main.cjs.map +3 -3
- package/error-code.md +75 -81
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -219,7 +219,7 @@ These appear **before** the subcommand (everything after the first non-flag toke
|
|
|
219
219
|
| ---- | ------ |
|
|
220
220
|
| `--cwd <dir>` | Repository root for git resolution and paths (default: current working directory). |
|
|
221
221
|
| `--ci` | Non-interactive mode; affects merged settings (e.g. Factory outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
|
|
222
|
-
| `--json` | On supported exits, one JSON summary line on stdout. On **non-zero** exits, the line includes **`exitCode`** (number) and **`exitMeaning`** (one-line classification) alongside any command-specific fields.
|
|
222
|
+
| `--json` | On supported exits, one JSON summary line on stdout. On **non-zero** exits, the line includes **`exitCode`** (number) and **`exitMeaning`** (one-line classification) alongside any command-specific fields. Factory / pipeline failures include **`factoryFailures`** (per failed phase), **`failurePhase`**, and **`validationExitId`** (legacy alias of **`failureExitId`**). See [error-code.md](./error-code.md) — OS exit **`5`** is **not** used (**SRS-70**). |
|
|
223
223
|
| `--verbose` | Extra stderr logging where implemented. |
|
|
224
224
|
| `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
|
|
225
225
|
| `--session-path <file>` | Session JSON path for **this process only** (overrides **`easyspecs.cliSessionPath`**); does not rewrite **`config.json`** unless you use **`auth login`** tail **`--session-path`** as documented under **Auth**. |
|
package/commands.md
CHANGED
|
@@ -24,21 +24,21 @@ Quick usage:
|
|
|
24
24
|
easyspecs-cli help
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
### Factory
|
|
27
|
+
### Factory failure reporting (**SRS-57** / **SRS-70**)
|
|
28
28
|
|
|
29
|
-
When `**easyspecs-cli analysis`** exits
|
|
29
|
+
When `**easyspecs-cli analysis`** exits **non-zero** with factory failures, human stderr prints a short banner and **one bullet per failed factory phase** (readable label, `**failureExitId**`, normative `**title**`, optional `**detail**`). **OS exit `5` is never used** — each phase maps to a dedicated code (**50–58**), **59** when multiple distinct phases fail in one run, or **49** when unattributed. `**--json**` adds:
|
|
30
30
|
|
|
31
31
|
|
|
32
32
|
| JSON key | Meaning |
|
|
33
33
|
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
34
|
-
| `**factoryFailures**` | Array of `**{ factory, phase, exitCode, failureExitId, title, validationExitId
|
|
34
|
+
| `**factoryFailures**` | Array of `**{ factory, phase, exitCode, failureExitId, title, validationExitId?, detail?, validationSubcode? }**` — `**failureExitId**` is the canonical `**major.minor**` id (**SRS-58**); `**major**` matches **`process.exit`** (**SRS-70**). See `[error-code.md](./error-code.md)`. |
|
|
35
35
|
| `**failurePhase**` | Last failed phase in macro order (alias for scripts). |
|
|
36
|
-
| `**validationExitId**` |
|
|
36
|
+
| `**validationExitId**` | Legacy alias: same string as `**failureExitId**` when present. |
|
|
37
37
|
| `**exitMeaning**` | First failure `**title**`, or that title plus “and *N* other pipeline phases failed”. |
|
|
38
|
-
| `**error**` | Orchestrator message; if several phases failed, a short appendix lists extra `**
|
|
38
|
+
| `**error**` | Orchestrator message; if several phases failed, a short appendix lists extra `**failureExitId`**s (see `[factoryValidationFailures.ts](../../src/factory/factoryValidationFailures.ts)`). |
|
|
39
39
|
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
**Phase → OS exit (generate_context):** **50** `create_analysis_worktree`, **51** `materialize_opencode_agents`, **52** `synthesis_convergence`, **53** `reference_coverage`, **54** `zero_reference_remediation_convergence`, **55** `reference_coverage_execution_report`, **56** `link_mapping_pipeline`, **57** `assemble_application_context_index`, **58** `backend_context_sync`, **49** unknown / unattributed. Full table: `[error-code.md](./error-code.md)`.
|
|
42
42
|
|
|
43
43
|
**Optional `validationSubcode` (v1):** `**R5_MACRO_PING_PONG`** when synthesis `**detail**` notes **R5** unstable convergence; `**COVERAGE_PERCENT_THRESHOLD`** when reference-coverage `**detail**` matches the strict percent gate pattern.
|
|
44
44
|
|
|
@@ -53,7 +53,7 @@ These flags may appear **before** the subcommand. Parsing and command registrati
|
|
|
53
53
|
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
54
54
|
| `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
|
|
55
55
|
| `--ci` | Non-interactive mode; feeds into merged settings (e.g. Factory outer-iteration default when unlimited). `**EASYSPECS_CI` is not read** — use this flag in CI. |
|
|
56
|
-
| `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. On `**analysis
|
|
56
|
+
| `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. On `**analysis**` factory failure, the JSON line includes `**factoryFailures`** (**SRS-57** — one object per `**failed`** factory phase) plus `**failurePhase**`, `**validationExitId**`, composed `**error**`, and `**exitMeaning**` tailored to the first failure. **Exit codes:** **[SRS-70](../../.gluecharm/docs/srs/srs-70.md)** — OS **5** is not used; see `[error-code.md](./error-code.md)`. |
|
|
57
57
|
| `--verbose` | Extra stderr logging where implemented. |
|
|
58
58
|
| `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
|
|
59
59
|
| `--environment production` | `--environment staging` | Alias: `**--env**`. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
|
|
@@ -68,9 +68,11 @@ Environment (stderr styling): `**NO_COLOR`** (any non-empty value) disables ANSI
|
|
|
68
68
|
|
|
69
69
|
---
|
|
70
70
|
|
|
71
|
-
## Workstation host inventory (**SRS-
|
|
71
|
+
## Workstation host inventory (**SRS-69** / **SRS-62**)
|
|
72
72
|
|
|
73
|
-
`**easyspecs-cli workstation info**` prints the CPU count used for the **SRS-
|
|
73
|
+
`**easyspecs-cli workstation info**` prints the CPU count used for the **SRS-69 §4** heuristic, total installed RAM, **`N_sys`** (JSON key **`maxSystemConcurrentAiWorkstations`**), and **`hostHardMaxConcurrentAi`** = **`min(N_sys, 64)`** (product agent ceiling per **SRS-62**). **macOS** (`darwin`) and **Linux** only; on other platforms the CLI exits **non-zero**, writes a short message to stderr, and does **not** print JSON on stdout (even if **`--json`** was passed).
|
|
74
|
+
|
|
75
|
+
**Formula (SRS-69 §4 — supersedes SRS-64 §4.1):** `N_float = min(P, R_GiB / 8)` where **`P`** is the physical CPU count and **`R_GiB`** is total installed RAM in GiB. Then **`N_sys = max(1, Math.round(N_float))`** and **`hostHardMax = min(64, N_sys)`**. In plain English: **one AI workstation per physical core, but never more than one per 8 GiB of installed RAM** — whichever dimension is tighter wins. **Worked example:** **`P=11, R=44 GiB → N_sys = 6 → hostHardMax = 6`** (was 100 under SRS-64). Operators on shared / interactive hosts (laptops also running an IDE + browser + chat apps) should set **`easyspecs.workstations.maxConcurrentAi`** *below* the reported `hostHardMax`. See live signals via **`[host-pool]`** / **`[host-pool-rec]`** (**SRS-68**).
|
|
74
76
|
|
|
75
77
|
Use the **global** **`--json`** flag (before the subcommand) for one parseable summary line. JSON includes **`totalMemBytes`**, **`platform`**, **`cpusForCap`**, **`cpusForCapSource`**, **`physicalCpus`** (integer when physical cores are known, else **`null`**), **`maxSystemConcurrentAiWorkstations`**, and **`hostHardMaxConcurrentAi`**.
|
|
76
78
|
|
|
@@ -83,7 +85,7 @@ When Analysis (or other callers) passes a **`diagnosticLog`** sink into the exte
|
|
|
83
85
|
- **`scope=host`** — machine-wide **RAM** (**total** / **free** / **used** bytes) plus **1-minute load average**, logical **CPU** count, and **load / CPUs** (not the same metric as the **SRS-62** runtime pool **CPU guard** — see **[SRS-65](../../.gluecharm/docs/srs/srs-65.md)**).
|
|
84
86
|
- **`scope=child`** — once per run: **child CPU time** (milliseconds) and **RSS** bytes for that **PID** (**Linux**: **`/proc`**, **macOS**: **`ps`**), or **`childRssBytes=unknown`** on unsupported platforms / read errors.
|
|
85
87
|
|
|
86
|
-
Tune concurrent agents with **`easyspecs.workstations.maxConcurrentAi`**, **`applyHostConcurrencyCap`**, and **`easyspecs-cli workstation info`** (**SRS-62** / **SRS-
|
|
88
|
+
Tune concurrent agents with **`easyspecs.workstations.maxConcurrentAi`**, **`applyHostConcurrencyCap`**, and **`easyspecs-cli workstation info`** (**SRS-62** / **SRS-69**); these lines help interpret **live** pressure alongside that configuration.
|
|
87
89
|
|
|
88
90
|
### Workstation pool host pressure (**SRS-68**)
|
|
89
91
|
|
|
@@ -183,7 +185,7 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
|
|
|
183
185
|
| `diagnose coverage-report` | Same `**--root**` / `**--worktree**` | Uses repo/worktree paths only; no extra env in `main.ts`. |
|
|
184
186
|
| `diagnose missing-artefacts` | Same `**--root**` / `**--worktree**` | Reads artefact snapshot from workspace state; no OpenCode. |
|
|
185
187
|
| `diagnose zero-reference` | Optional `**--worktree <path>**` (no `--root` branch in this handler) | `**requireOpenCode**`; `**merged.pipelineOpenCode**` for pool concurrency/argv/timeout. Checkout from `**--worktree**` or snapshot (`[resolveAdHocCheckoutRoot](../../src/cli/main.ts)`). On full success, runs **SRS-51** markdown link graph on `**<checkout>/.gluecharm/context`** before exit (**non-zero** if link validation fails). |
|
|
186
|
-
| `context link-graph` | `**--root workspace`** | `**--root worktree**`, optional `**--worktree <path>**` | **SRS-51:** deterministic navigation sections in context markdown under `**<root>/.gluecharm/context`**. No OpenCode. `**--json**`: `**ok**`, `**contextDir**`, `**error**`, `**brokenLinks**`. Exit
|
|
188
|
+
| `context link-graph` | `**--root workspace`** | `**--root worktree**`, optional `**--worktree <path>**` | **SRS-51:** deterministic navigation sections in context markdown under `**<root>/.gluecharm/context`**. No OpenCode. `**--json**`: `**ok**`, `**contextDir**`, `**error**`, `**brokenLinks**`. Exit **78** on broken relative links inside EasySpecs nav regions (**SRS-70**). |
|
|
187
189
|
| `context drift <referencePath>` | `**--label <slug>**`, `**--index <path>**`, `**--dry-run**`. Optional `**--root**` / `**--worktree**` tail tokens are accepted and ignored for v1 routing. | **SRS-56:** analysis worktree → OpenCode drift agent → `**.gluecharm/context/drift/drift-<slug>-<date>.md`** + reference index patch → global `**--promote` / `--no-promote**`. Success stdout: drift report path. |
|
|
188
190
|
| `download context` | Optional `**--force**`, `**--replace-from-cloud**` | **SRS-49:** requires `**auth`** session. `**GET /api/content/application/:id**` → `**srs_discovery**` ids → `**POST /api/batch/content/srs_discovery/get**` → writes files under `**<repoRoot>/.gluecharm/context**`. `**--force**` overwrites existing paths; `**--replace-from-cloud**` deletes local context files first (preserves root `**easyspecs-upload-target.json**`). `**--json**` stdout: `**downloaded**`, `**skipped**`, `**failed**`, `**localRemoved**`. Exit `**upload**` when any row fails. |
|
|
189
191
|
| `upload context` | — | Requires `**auth**` session. Context dir: `**<repoRoot>/.gluecharm/context**`. Project id: `**easyspecs.easyspecsProjectId**` in `**config.json**` only. **SRS-46:** on full success, optional cloud status GET (see `**fetchContextAnalyzedInCloud`**); `**--json**` may add `**contextAnalyzedInCloud**` / `**contextAnalyzedInCloudAt**`; updates `**easyspecs.factory.cloudContext***` when fetch is enabled (legacy `**easyspecs.analysis.cloudContext***`). |
|