@gluecharm-lab/easyspecs-cli 0.0.12 → 0.0.14

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 +89 -68
  2. package/commands.md +11 -6
  3. package/dist/main.cjs +10844 -9595
  4. package/dist/main.cjs.map +4 -4
  5. package/package.json +2 -2
  6. package/resources/schemas/srs-46-config.schema.json +89 -0
package/README.md CHANGED
@@ -1,14 +1,13 @@
1
1
  # EasySpecs CLI
2
2
 
3
- Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, **macro pipelines**, **upload to EasySpecs**, **auth**, and **ACE** — the same orchestration ideas as the **EasySpecs VS Code extension**, without an editor.
3
+ Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, **macro pipelines**, **download/upload context** to EasySpecs, **auth**, and **ACE** — the same orchestration ideas as the **EasySpecs VS Code extension**, without an editor.
4
4
 
5
5
  Published as **`@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is **`easyspecs-cli`**.
6
6
 
7
7
  ## Requirements
8
8
 
9
9
  - **Node.js** ≥ 18
10
- - **OpenCode** (`opencode` on `PATH`) for flows that run agents — install from OpenCode’s own documentation
11
- - A **git repository** with **`.gluecharm/`** (documentation + context layout) when running analysis, diagnose, or upload against a project
10
+ - **OpenCode** (`opencode` on `PATH`) for flows that run agents — install OpenCode using its own install instructions
12
11
 
13
12
  ## Install
14
13
 
@@ -33,57 +32,68 @@ npx @gluecharm-lab/easyspecs-cli@latest help
33
32
 
34
33
  ## Quick start
35
34
 
35
+ From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for **analysis**, **diagnose**, **upload**, and **download context**:
36
+
36
37
  ```bash
37
38
  cd /your/repo
38
39
  easyspecs-cli doctor
39
- easyspecs-cli doctor --inspect-config
40
- easyspecs-cli help
40
+ easyspecs-cli config init
41
+ easyspecs-cli analysis
41
42
  ```
42
43
 
43
- Use **`config init`** to create **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). Set **`easyspecs.easyspecsProjectId`** and **`easyspecs.defaultGitRemoteUrl`** from the shell with **`config set-project-id <id>`** and **`config set-git-remote <url>`** (each overwrites that field). Use **`--ci`** for non-interactive CI: no prompts, stricter defaults (e.g. macro outer-iteration cap). Tunables belong in **`<repo>/.easyspecs/config.json`** — do not rely on **`EASYSPECS_*`** environment variables for product settings.
44
+ **`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). **`analysis`** runs the full macro loop (synthesis convergence, coverage, reporting, indexing); add **`--synthesis-only`** to stop after the synthesis phase. Add **`--upload`** only after **`auth login`** and **`config set-project-id <id>`**. Use **`download context`** (same auth + project id) to pull context from EasySpecs into **`.gluecharm/context`**. Use **`--ci`** in automation for non-interactive behaviour and stricter defaults (e.g. macro outer-iteration cap).
45
+
46
+ Set **`easyspecs.defaultGitRemoteUrl`** with **`config set-git-remote <url>`** when you want that recorded in config. Tunables belong in **`<repo>/.easyspecs/config.json`** — do not rely on **`EASYSPECS_*`** environment variables for product settings.
47
+
48
+ Optional checks:
44
49
 
45
50
  ```bash
51
+ easyspecs-cli doctor --inspect-config
52
+ easyspecs-cli help
46
53
  easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
47
54
  ```
48
55
 
49
- ## Commands (overview)
56
+ ## Download context (pull from EasySpecs)
57
+
58
+ Use this when you want the **application context** that is already stored in EasySpecs (CMS **`srs_discovery`** rows) written into your repo’s **`.gluecharm/context`**, for example after a fresh clone or to align with the cloud.
50
59
 
51
- | Area | Examples |
52
- | ---- | ---------- |
53
- | **Health** | `doctor` (`--readiness`, `--inspect-config`), `version` |
54
- | **Config** | `doctor --inspect-config`, `config init`, `config set-project-id`, `config set-git-remote` |
55
- | **Auth** | `auth login --email … --password …`, `auth logout`, `auth status` |
56
- | **Run synthesis** | `run synthesis`; **`run synthesis resume-missing`** / **`resume-synthesis`** |
57
- | **Analysis** (full macro pipeline) | `analysis` (optional **`--upload`** after login; **`--synthesis-only`** stops after synthesis) |
58
- | **Diagnose** | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, … |
59
- | **Upload** | `upload context`, `upload republish` |
60
- | **ACE** | `ace clear`, `ace learn`, `ace auto-learn` |
60
+ **Prerequisites:** same as **`upload context`**: a prior **`auth login`**, and **`easyspecs.easyspecsProjectId`** set (e.g. **`easyspecs-cli config set-project-id <uuid>`**). The CLI creates minimal **`.gluecharm/`** layout when needed, including **`.gluecharm/context`**.
61
61
 
62
- Run **`easyspecs-cli help`** for the full command tree. This README does not duplicate every flag; the built-in help matches the installed package version.
62
+ **Behaviour:** the CLI **GET**s the application, reads linked **`srs_discovery`** ids, then **POST**s **batch get** to **`/api/batch/content/srs_discovery/get`** and writes one file per row under **`<repo>/.gluecharm/context`**, using each row’s **`name`** as a safe relative path (path traversal is rejected). Rows named **`easyspecs-upload-target.json`** are skipped. When files are written, ids are merged into **`index-application-context.json`** the same way as after upload, if that index file exists.
63
63
 
64
- ## Terminal diagnostics (colors)
64
+ ```bash
65
+ cd /your/repo
66
+ easyspecs-cli auth login --email you@example.com --password '…'
67
+ easyspecs-cli config set-project-id <your-easyspecs-project-uuid>
68
+ easyspecs-cli download context
69
+ ```
65
70
 
66
- Long-running commands (**`run synthesis`**, **`analysis`**, **`diagnose`** with **`--verbose`**, etc.) print **structured lines** on stderr with bracket prefixes such as **`[pool]`**, **`[queue]`**, **`[setup]`**, **`[AgentCode]`**, **`[context]`**, **`[index]`** — same vocabulary as the EasySpecs Analysis output in VS Code. Logs say **AgentCode** for the agent subprocess; the executable on your machine may still be **`opencode`** on **`PATH`**.
71
+ | Flag | Meaning |
72
+ | ---- | ------- |
73
+ | *(none)* | Skip any local file that already exists (no silent overwrite). |
74
+ | `--force` | Overwrite existing files that map to cloud rows. |
75
+ | `--replace-from-cloud` | Delete local files under **`.gluecharm/context`** first, then write from the cloud. Root **`easyspecs-upload-target.json`** is preserved when present. Implies a full replace of downloaded content; pair with care. |
67
76
 
68
- When **stderr** is an interactive **TTY**, those prefixes are **colorized** (ANSI) for faster scanning.
77
+ **`--json`:** prints one summary line on stdout with **`ok`**, **`downloaded`**, **`skipped`**, **`failed`** (count), and **`localRemoved`** (files deleted when **`--replace-from-cloud`** was used). With **`--verbose`**, if **`failed` > 0`**, the line may include a **`failures`** array. A non-zero exit is used when **`failed` > 0`**.
69
78
 
70
- | Mechanism | Effect |
71
- | --------- | ------ |
72
- | **`NO_COLOR`** set to any non-empty value | Colors **disabled** ([no-color.org](https://no-color.org/)). |
73
- | **`FORCE_COLOR`** set to any non-empty value | Colors **allowed** even if stderr is **not** a TTY (e.g. piping to **`tee`**). |
74
- | **`--json`** | Normal runs **suppress** stderr diagnostics; stderr never receives ANSI in that mode so JSON on stdout stays machine-safe. With **`--json --verbose`**, stderr lines are **plain text** (no ANSI). |
79
+ **Examples:**
75
80
 
76
- **Behaviour:** bracket tags are colorized; **`[pool]`** lines bold the work-item id and dim **`(active n/m)`**; **`[AgentCode]`** lines dim **`prompt` / `command` / `cwd` / `argv`** labels; multi-line **`stderr`/`stdout`** dumps are indented and dimmed; **blank lines** appear when the phase family changes (e.g. **`[setup]`** → **`[pool]`**, **`[pool]`** → **`[AgentCode]`**). Purely visual — message text is unchanged for grep.
81
+ ```bash
82
+ easyspecs-cli download context
83
+ easyspecs-cli download context --force
84
+ easyspecs-cli download context --replace-from-cloud
85
+ easyspecs-cli --json download context
86
+ ```
77
87
 
78
88
  ## Configuration
79
89
 
80
- Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed, except for **`help`**, **`version`**, and **`doctor`** which do not create the file on first run). **`auth login --email … --password …`** stores tokens for upload commands (optional **`--session-path`** on the command tail updates **`easyspecs.cliSessionPath`** in **`config.json`**).
90
+ Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed, except for **`help`**, **`version`**, and **`doctor`** which do not create the file on first run). **`auth login --email … --password …`** stores tokens for **upload** and **download context** commands. You may append **`--session-path <file>`** at the **end** of the **`auth login`** argument list to update **`easyspecs.cliSessionPath`** in **`config.json`** for that login flow.
81
91
 
82
92
  After **`auth login`**, session data is stored at **`easyspecs.cliSessionPath`** in **`config.json`** when that path is set (otherwise **`~/.easyspecs/cli-session.json`**). Tools such as the VS Code extension may spawn **`easyspecs-cli`** with global **`--session-path <file>`** so this process uses a temporary session file without editing **`config.json`**.
83
93
 
84
94
  ### Default **`config.json`** (from **`easyspecs-cli config init`**)
85
95
 
86
- Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to replace an existing file). A fresh install writes **`.easyspecs/config.json`** equivalent to the following default shape:
96
+ Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to replace an existing file). A fresh install writes **`.easyspecs/config.json`** with a shape similar to:
87
97
 
88
98
  ```json
89
99
  {
@@ -152,6 +162,8 @@ Run **`easyspecs-cli config init`** in your repo (add **`--overwrite`** to repla
152
162
  }
153
163
  ```
154
164
 
165
+ Your file may gain additional keys over time (for example cloud-analysis cache fields under **`easyspecs.analysis`**); validate against the schema your package version documents.
166
+
155
167
  ### Config keys (reference)
156
168
 
157
169
  Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CLI flags (for example **`--api-base-url`**, **`--environment`**). The CLI does **not** read **`EASYSPECS_*`** or **`VITE_*`** for product settings.
@@ -161,19 +173,21 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
161
173
  | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
162
174
  | `easyspecs.deploymentEnvironment` | `production` or `staging` (default `production`). Used with built-in System Manager URLs when `apiBaseUrl` is empty. |
163
175
  | `easyspecs.apiBaseUrl` | Explicit System Manager origin; wins after `--api-base-url`. Default non-empty value uses the production API host. Use **`""`** if you want the built-in URL from **`deploymentEnvironment`** / **`--environment`** only. |
164
- | `easyspecs.easyspecsProjectId` | EasySpecs **project** id (Content application UUID) for uploads. Set with **`config set-project-id`** or the EasySpecs app; legacy **`applicationId`** in older files may be migrated into this field. |
176
+ | `easyspecs.easyspecsProjectId` | EasySpecs **project** id (Content application UUID) for **`upload context`**, **`upload republish`**, and **`download context`**. Set with **`config set-project-id`** or the EasySpecs app; legacy **`applicationId`** in older files may be migrated into this field. |
165
177
  | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for reference; analysis still uses the live repo. |
166
178
  | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Precedence: global **`--session-path`** → **`cliSessionPath`** → home default. |
167
179
  | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (shortcut; see **`openCodeRuntime`**). |
168
- | `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
180
+ | `easyspecs.analysis.*` | Pipeline settings, **`promoteContextToWorkspace`**, and optional **`cloudContextAnalyzed`** / **`cloudContextAnalyzedAt`** (when **`cloudContextAnalyzed`** is **`true`**, **`cloudContextAnalyzedAt`** should be a non-null ISO timestamp). |
169
181
  | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap. |
170
182
  | `easyspecs.openCodeRuntime` | Providers (`apiKey`, `defaultModel` per provider), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay`. |
171
183
  | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | Number or **`null`**. **`null`** means **`diagnose reference-coverage`** does not fail on percentage alone. |
172
184
  | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). |
173
185
  | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`**; empty **`""`** → automatic resolution from the analysis snapshot. |
186
+ | `easyspecs.upload.fetchContextAnalyzedInCloud` | Boolean, default **`true`**. When **`true`**, after a successful **`upload context`** / **`upload republish`**, the CLI may **`GET`** application status and emit **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`** on **`--json`**, and update **`easyspecs.analysis.cloudContext*`** cache. When **`false`**, skips that fetch. |
187
+ | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms) for that GET; default **15000** if omitted. |
174
188
  | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log extra lines to stderr. |
175
189
  | `easyspecs.cli.bundledResourcesRoot` | Optional absolute or repo-relative path to the bundled **`resources/`** directory. Empty → resolve next to the installed CLI package. |
176
- | `easyspecs.auth.ciLogin.email` / `password` | Used with **`--ci`** when **`--email` / `--password`** are omitted on the command line. Prefer CI-generated **`config.json`**; avoid committing secrets. |
190
+ | `easyspecs.auth.ciLogin.email` / `password` | Used with **`--ci`** when **`--email` / `--password`** are omitted on **`auth login`**. Prefer CI-generated **`config.json`**; avoid committing secrets. |
177
191
 
178
192
  **Resolved API base URL:** `--api-base-url` → non-empty **`easyspecs.apiBaseUrl`** → built-in URL from **`--environment`** or **`easyspecs.deploymentEnvironment`** or **`production`**.
179
193
 
@@ -181,9 +195,7 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
181
195
 
182
196
  ## Global flags
183
197
 
184
- `--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, **`--session-path`**, `--environment`, `--promote` / `--no-promote` — details in **`easyspecs-cli --help`**.
185
-
186
- ### Global options (table)
198
+ These appear **before** the subcommand (everything after the first non-flag token is the command and its arguments).
187
199
 
188
200
  | Flag | Effect |
189
201
  | ---- | ------ |
@@ -192,58 +204,67 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
192
204
  | `--json` | On supported exits, one JSON summary line on stdout. |
193
205
  | `--verbose` | Extra stderr logging where implemented. |
194
206
  | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
207
+ | `--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**. |
195
208
  | `--environment production` \| `staging` | Alias **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
196
209
  | `--promote` | After **`run synthesis`**, copy generated **`.gluecharm/context`** from the analysis worktree into the workspace repo when applicable. |
197
210
  | `--no-promote` | Disable that promotion for this run. |
198
211
  | `--help`, `-h` | Built-in help. Does **not** create **`.easyspecs/config.json`**. |
199
212
  | `--version`, `-V` | CLI package version. Does **not** create config. |
200
- | `--config <path>` | Reserved / unused in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
213
+ | `--config <path>` | Parsed but **unused** in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
201
214
 
202
- ### Diagnose-only flags
215
+ ## Diagnose-only flags
203
216
 
204
- Used after **`diagnose <subcommand>`**:
217
+ Used on the tail of **`diagnose <subcommand>`** (after the subcommand name):
205
218
 
206
219
  | Flag | Values | Meaning |
207
220
  | ---- | ------ | ------- |
208
- | `--root` | `workspace` or `worktree` | Resolve paths against the workspace repo root or an analysis checkout. |
209
- | `--worktree` | path | Analysis git checkout (use with **`--root worktree`** when needed). |
221
+ | `--root` | `workspace` or `worktree` | Resolve paths against the workspace repo root or an analysis checkout (**required** for **`reference-coverage`**, **`coordination-duplicates`**, **`coverage-report`**, **`missing-artefacts`**). |
222
+ | `--worktree` | path | Analysis git checkout (use with **`--root worktree`**, or alone where documented below). |
223
+
224
+ ## Commands and flags (complete)
210
225
 
211
- ## Command reference
226
+ Every command the CLI accepts, with command-specific tokens. Global flags above apply to all of these unless noted.
212
227
 
213
- | Command | Tokens / notes | Behaviour summary |
214
- | ------- | ---------------- | ------------------ |
215
- | `help`, `--help` | — | Prints usage. |
228
+ | Command | Command-specific flags / tokens | Behaviour summary |
229
+ | ------- | ------------------------------- | ------------------ |
230
+ | `help` or first token `--help` | — | Prints usage (same as **`--help`** before the command). |
216
231
  | `version` | — | Prints the CLI package version string. |
217
- | `doctor` | **`--readiness`**, **`--inspect-config`** | Does **not** create **`config.json`**. Default (no flags) behaves like **`--readiness`**. **`--inspect-config`** prints redacted merged settings and config. |
218
- | `config init` | **`--overwrite`** optional | Writes full defaults; may import legacy **`.easyspecs/cli.json`** once if present. |
219
- | `config set-project-id <id>` | — | Sets **`easyspecs.easyspecsProjectId`**. |
220
- | `config set-git-remote <url>` | — | Sets **`easyspecs.defaultGitRemoteUrl`**. |
221
- | `auth login` | **`--email`**, **`--password`**, optional tail **`--session-path`** | Login against the resolved API; writes session file. With **`--ci`**, credentials may come from **`easyspecs.auth.ciLogin`** in **`config.json`** if argv omits email/password. |
222
- | `auth logout` | — | Clears the effective session file. |
223
- | `auth status` | — | Shows whether a session file exists / looks populated. |
224
- | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. |
225
- | `run synthesis resume-missing`, `resume-synthesis` | **`--worktree`** | Resumes remediation / synthesis on a known checkout. |
226
- | `analysis` | **`--synthesis-only`**, **`--upload`** | Full macro loop; **`--upload`** needs **`auth login`** and project id in config. |
227
- | `diagnose reference-coverage` | **`--root`**, **`--worktree`** | Optional percent gate via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
228
- | `diagnose coordination-duplicates` | same | **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
229
- | `diagnose coverage-report` | same | Coverage report path on disk. |
230
- | `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state. |
231
- | `diagnose zero-reference` | **`--worktree`** | Zero-reference remediation pool (**OpenCode**). |
232
- | `upload context` | — | Requires auth session and **`easyspecs.easyspecsProjectId`**. |
233
- | `upload republish` | — | Same auth rules; context dir from **`easyspecs.upload.contextDirectory`** or analysis snapshot. |
232
+ | `doctor` | **`--readiness`**, **`--inspect-config`** (optional; default if none → readiness-style check) | Does **not** create **`config.json`**. **`--readiness`**: repo root, API URL, OpenCode, agents dir. **`--inspect-config`**: redacted merged settings + config JSON. Both flags together runs both. |
233
+ | `config init` | **`--overwrite`** (optional) | Writes **`.easyspecs/config.json`** with defaults; may import legacy **`.easyspecs/cli.json`** once if present. Existing file unchanged unless **`--overwrite`**. |
234
+ | `config set-project-id <easyspecsProjectId>` | — | Sets **`easyspecs.easyspecsProjectId`** (creates config with defaults if missing). |
235
+ | `config set-git-remote <url>` | — | Sets **`easyspecs.defaultGitRemoteUrl`** (same bootstrap-if-missing behaviour). |
236
+ | `config dump` | — | **Deprecated.** Prints the same redacted payload as **`doctor --inspect-config`** and stderr warns to use **`doctor --inspect-config`**. |
237
+ | `auth login` | **`--email <email> --password <password>`**, optional tail **`--session-path <path>`** | Login to resolved API; writes session file. With **`--ci`**, credentials may come from **`easyspecs.auth.ciLogin`** in **`config.json`** if argv omits email/password. Tail **`--session-path`** updates **`easyspecs.cliSessionPath`** in **`config.json`**. Global **`--session-path`** overrides effective session file without editing **`config.json`**. |
238
+ | `auth logout` | — | Deletes the effective session file. |
239
+ | `auth status` | — | Reports whether a session file exists / looks populated. |
240
+ | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. **`--promote` / `--no-promote`** affect promotion after success. |
241
+ | `run synthesis resume-missing` | **`--worktree <path>`** (optional) | Parallel missing-artefact remediation pool on an existing checkout (from **`--worktree`** or last snapshot). **`requireOpenCode`**. |
242
+ | `run synthesis resume-synthesis` | **`--worktree <path>`** (optional) | Same implementation as **`resume-missing`** (alias command path). |
243
+ | `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full macro loop unless **`--synthesis-only`**. **`--upload`** runs backend sync after macro (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.analysis.cloudContextAnalyzed`** is **`true`** and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
244
+ | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Reference coverage gate; optional percent limit via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
245
+ | `diagnose coordination-duplicates` | same | Duplicate/orphan reporting; **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
246
+ | `diagnose coverage-report` | same | Writes coverage execution report path. |
247
+ | `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state (JSON on stdout in human mode). |
248
+ | `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). |
249
+ | `download context` | **`--force`**, **`--replace-from-cloud`** (optional; any order after **`download context`**) | Requires **`auth login`** session + **`easyspecs.easyspecsProjectId`**. Fetches **`srs_discovery`** ids from **`GET /api/content/application/:id`**, hydrates rows with **`POST /api/batch/content/srs_discovery/get`**, writes UTF-8 files under **`<repo>/.gluecharm/context`**. Default skips existing paths; **`--force`** overwrites; **`--replace-from-cloud`** wipes local context files first (preserves root **`easyspecs-upload-target.json`**). **`--json`**: **`downloaded`**, **`skipped`**, **`failed`**, **`localRemoved`**. Non-zero exit if **`failed` > 0`. Full narrative under **Download context (pull from EasySpecs)** above. |
250
+ | `upload context` | — | Requires auth session + **`easyspecs.easyspecsProjectId`**. Context dir: **`<repo>/.gluecharm/context`**. Optional cloud status GET per **`easyspecs.upload.fetchContextAnalyzedInCloud`**. |
251
+ | `upload republish` | — | Same auth + project id; context dir from **`easyspecs.upload.contextDirectory`** or analysis worktree snapshot. Same optional cloud status behaviour as **`upload context`**. |
234
252
  | `ace clear` | — | Deletes learnings under **`.gluecharm/context/learnings`**. |
235
- | `ace learn`, `ace auto-learn` | **`--worktree`** | ACE offline learning pools (**OpenCode**). |
253
+ | `ace learn` | **`--worktree <path>`** (optional) | Offline ACE learn from traces; **`requireOpenCode`**. Worktree = **`--worktree`** if it contains **`.opencode/schemas/ace`**, else workspace root. |
254
+ | `ace auto-learn` | **`--worktree <path>`** (optional) | ACE auto-learn pool; **`requireOpenCode`**. Worktree = **`--worktree`** if valid git dir, else workspace root. Concurrency capped by **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`**. |
255
+
256
+ **OpenCode:** commands that spawn agents require **`opencode`** (or configured executable) on **`PATH`** and credentials unless **`skipCredentialsCheck`** or provider keys in **`config.json`** apply (**`requireOpenCode`**).
257
+
258
+ **EasySpecs API session:** **`download context`**, **`upload context`**, **`upload republish`**, and **`analysis --upload`** need a prior **`auth login`** (or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`** when argv omits email/password on login), plus **`easyspecs.easyspecsProjectId`** for the upload/download commands.
259
+
260
+ **Unknown command:** prints help and exits with a usage error.
236
261
 
237
262
  ## Product information
238
263
 
239
- **EasySpecs** is a product for agentic documentation and requirements: use the public marketing and app entry at **easyspecs.ai** (sign-in, projects, browser workspace). This npm package is the **headless CLI** only; it does not bundle the web app.
264
+ **EasySpecs** is a product for agentic documentation and requirements. The public site and app live at **easyspecs.ai** (sign-in, projects, browser workspace). This npm package is the **headless CLI** only; it does not bundle the web app.
240
265
 
241
266
  ## License
242
267
 
243
268
  Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
244
269
 
245
- This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX **`Elastic-2.0`**). The complete license text is included in the **`LICENSE`** file published inside **`@gluecharm-lab/easyspecs-cli`**. Other artifacts outside this tarball may use different licenses.
246
-
247
- ## Bundled documentation
248
-
249
- This package also ships **`commands.md`** in the same directory as this **`README.md`**, with an extended command and configuration reference (same scope as this file, in alternate layout).
270
+ This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX **`Elastic-2.0`**). The complete license text ships in the **`LICENSE`** file inside the published **`@gluecharm-lab/easyspecs-cli`** package on npm.
package/commands.md CHANGED
@@ -36,10 +36,12 @@ Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI
36
36
 
37
37
  ### File: `<repoRoot>/.easyspecs/config.json`
38
38
 
39
- Canonical JSON created on first need (except **`help`**, **`version`**, and **`doctor`** — no auto-create). Invalid JSON fails with a clear path (**R6**). If **`config.json`** is missing and **`.easyspecs/cli.json`** exists, settings are imported once (**§6 M2**) into the new file.
39
+ Canonical JSON created on first need (except **`help`**, **`version`**, and **`doctor`** — no auto-create). Invalid JSON fails with a clear path (**R6**). Merged documents are also validated against **SRS-46** JSON Schema ([`srs-46-config.schema.json`](../../.gluecharm/docs/srs/srs-46-config.schema.json)) — see [`USER-MANUAL-SRS-46.md`](../../.gluecharm/docs/srs/USER-MANUAL-SRS-46.md). If **`config.json`** is missing and **`.easyspecs/cli.json`** exists, settings are imported once (**§6 M2**) into the new file.
40
40
 
41
41
  Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*` product overrides on **`easyspecs-cli`** (**R34**).
42
42
 
43
+ **Workspace layout (SRS-48):** For **`analysis`**, **`diagnose`**, **`upload`**, and **`download context`**, the CLI creates the minimal **`.gluecharm/`** directories (**`docs/srs`**, **`content`**, **`logs`**, **`context`**) under the relevant filesystem root when they are missing. You do not need to copy a Gluecharm template tree before first use.
44
+
43
45
  | Path | Purpose |
44
46
  |------|---------|
45
47
  | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
@@ -49,12 +51,14 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
49
51
  | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for documentation / tooling; analysis still uses the live repo. Related: **`index-application-context.json`** `repository`, **`.easyspecs/analysis-worktree.json`** `repositoryRoot`. |
50
52
  | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`** written by **`auth login`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Effective path: global **`--session-path`** (if passed) → **`cliSessionPath`** → default home path ([`cliSession.ts`](../../src/cli/cliSession.ts)). |
51
53
  | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
52
- | `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
54
+ | `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. **SRS-46:** `cloudContextAnalyzed` (boolean), `cloudContextAnalyzedAt` (`null` or ISO `date-time` string; when `cloudContextAnalyzed` is `true`, `At` must be non-null). |
53
55
  | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
54
56
  | `easyspecs.openCodeRuntime` | Annex-aligned block: `providers` (per-provider `apiKey`, `defaultModel`), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay` — see [`srs-43-opencode.schema.json`](../../.gluecharm/docs/srs/srs-43-opencode.schema.json). |
55
57
  | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | `number` \| **`null`**. When **`null`**, `diagnose reference-coverage` does not fail on percent alone (**SRS-44**). |
56
58
  | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). When **`true`**, duplicate/orphan rows fail `diagnose coordination-duplicates`. |
57
59
  | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`** context dir; empty **`""`** → automatic (analysis snapshot). |
60
+ | `easyspecs.upload.fetchContextAnalyzedInCloud` | Boolean, default **`true`**. When **`true`**, after a fully successful **`upload context`** / **`upload republish`**, the CLI performs **`GET /api/content/application/:id`** and emits **`contextAnalyzedInCloud`** / **`contextAnalyzedInCloudAt`** on **`--json`**; updates **`easyspecs.analysis.cloudContext*`** cache. When **`false`**, skips that GET and omits those JSON keys. |
61
+ | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms). GET timeout; default **15000** if omitted. |
58
62
  | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log to stderr ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
59
63
  | `easyspecs.cli.bundledResourcesRoot` | Optional path to bundled **`resources/`** (folder containing **`opencode-agents/`**). Empty → infer next to the CLI package. |
60
64
  | `easyspecs.auth.ciLogin.email` / `password` | Used only with **`--ci`** when **`--email` / `--password`** are omitted (**SRS-44**). Prefer CI-generated **`config.json`**; do not commit secrets. |
@@ -101,14 +105,15 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
101
105
  | `auth status` | — | Reads session file. |
102
106
  | `run synthesis` | — | Single SRS-9 context pass (same as extension **Run Analysis**). **`requireOpenCode`** → executable + credentials unless skip flag. Uses **`merged.pipelineOpenCode`** from **`config.json`**. **`--promote` / `--no-promote`** controls promotion after success. |
103
107
  | `run synthesis resume-missing`, `run synthesis resume-synthesis` | Optional **`--worktree <path>`** | Same implementation: resolves checkout via `--worktree` or stored snapshot ([`resolveAdHocCheckoutRoot`](../../src/cli/main.ts)). OpenCode + **`merged.pipelineOpenCode`**. |
104
- | `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`** | **SRS-32** full loop: synthesis convergence (until no missing artefacts), then coverage, zero-ref, report, index, optional backend sync. **`merged.macroOrchestration`** from config + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Macro debug: **`easyspecs.macro.debug`**. OpenCode options from **`merged.pipelineOpenCode`**. |
108
+ | `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full loop: synthesis convergence (until no missing artefacts), then coverage, zero-ref, report, index, optional backend sync. **`merged.macroOrchestration`** from config + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Macro debug: **`easyspecs.macro.debug`**. OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.analysis.cloudContextAnalyzed`** is **`true`** and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the macro or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). |
105
109
  | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Gate when **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`** is a finite number (not **`null`**): failure when metric exceeds it. |
106
110
  | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
107
111
  | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
108
112
  | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
109
113
  | `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)). |
110
- | `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. |
111
- | `upload republish` | — | Same auth + upload pipeline; context dir from **`easyspecs.upload.contextDirectory`** if non-empty and valid, else analysis worktree **`…/.gluecharm/context`** from snapshot, else error. Same project id rule as **`upload context`**. |
114
+ | `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. |
115
+ | `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.analysis.cloudContext*`** when fetch is enabled. |
116
+ | `upload republish` | — | Same auth + upload pipeline; context dir from **`easyspecs.upload.contextDirectory`** if non-empty and valid, else analysis worktree **`…/.gluecharm/context`** from snapshot, else error. Same project id rule as **`upload context`**. Same **SRS-46** JSON + cache behaviour as **`upload context`**. |
112
117
  | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
113
118
  | `ace learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; worktree chosen if `--worktree` points at checkout with **`.opencode/schemas/ace`**, else **`repoRoot`** ([`main.ts`](../../src/cli/main.ts)). **`merged.pipelineOpenCode`** for spawn argv/timeout. |
114
119
  | `ace auto-learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; checkout = `--worktree` if valid git dir, else **`repoRoot`**. **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`** caps parallelism. |
@@ -118,6 +123,6 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
118
123
  ## Notes
119
124
 
120
125
  - Commands that **spawn OpenCode** call **`requireOpenCode`**: binary must respond (`easyspecs.openCode.executable` / `opencode` on **`PATH`**), and credentials must look ready unless **`easyspecs.openCode.skipCredentialsCheck`**, or provider keys exist in **`config.json`**, or the parent shell already has provider env (probe behaviour in [`opencodeCli`](../../src/opencodeCli.ts)).
121
- - **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
126
+ - **`download context`** / **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
122
127
  - Unknown commands print help and exit with a usage error.
123
128
  - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).