@gluecharm-lab/easyspecs-cli 0.0.14 → 0.0.16

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 (35) hide show
  1. package/README.md +39 -18
  2. package/commands.md +33 -16
  3. package/dist/main.cjs +24443 -17851
  4. package/dist/main.cjs.map +4 -4
  5. package/package.json +1 -1
  6. package/resources/opencode-agents/agent-ace-curator.md +3 -0
  7. package/resources/opencode-agents/agent-context-drift-compare.md +48 -0
  8. package/resources/opencode-agents/agent-list-data-model.md +4 -0
  9. package/resources/opencode-agents/agent-list-entity-fields.md +4 -0
  10. package/resources/opencode-agents/agent-list-experiences.md +4 -0
  11. package/resources/opencode-agents/agent-list-features.md +4 -0
  12. package/resources/opencode-agents/agent-list-scenarios.md +4 -0
  13. package/resources/opencode-agents/agent-list-services.md +4 -0
  14. package/resources/opencode-agents/agent-list-tech-stack.md +4 -0
  15. package/resources/opencode-agents/agent-list-use-cases.md +8 -0
  16. package/resources/opencode-agents/agent-md-method-detail.md +1 -0
  17. package/resources/opencode-agents/agent-md-tool-detail.md +2 -1
  18. package/resources/opencode-agents/agent-review-data-model-list.md +6 -0
  19. package/resources/opencode-agents/agent-review-entity-fields-list.md +6 -0
  20. package/resources/opencode-agents/agent-review-experiences-list.md +6 -0
  21. package/resources/opencode-agents/agent-review-features-list.md +8 -0
  22. package/resources/opencode-agents/agent-review-scenarios-list.md +5 -0
  23. package/resources/opencode-agents/agent-review-services-list.md +6 -0
  24. package/resources/opencode-agents/agent-review-tech-stack-list.md +6 -0
  25. package/resources/opencode-agents/agent-review-use-cases-list.md +6 -0
  26. package/resources/schemas/context-lists/data-model-list.schema.json +24 -0
  27. package/resources/schemas/context-lists/entity-fields-list.schema.json +24 -0
  28. package/resources/schemas/context-lists/experiences-list.schema.json +24 -0
  29. package/resources/schemas/context-lists/features-list.schema.json +24 -0
  30. package/resources/schemas/context-lists/repo-surface-scan.schema.json +24 -0
  31. package/resources/schemas/context-lists/scenarios-list.schema.json +24 -0
  32. package/resources/schemas/context-lists/services-list.schema.json +24 -0
  33. package/resources/schemas/context-lists/tech-stack-list.schema.json +24 -0
  34. package/resources/schemas/context-lists/use-cases-list.schema.json +24 -0
  35. package/resources/schemas/srs-46-config.schema.json +27 -0
package/README.md CHANGED
@@ -1,6 +1,21 @@
1
1
  # EasySpecs CLI
2
2
 
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.
3
+ Headless **EasySpecs** command-line tool: same orchestration ideas as the **EasySpecs VS Code extension**, without an editor. **`easyspecs-cli help`** is organized around three **factory-level** jobs on **application context**; the rest of the commands and flags exist to tune **where** the work runs (**`--cwd`**, **`--worktree`**, **`--root`**), **how** it behaves (**`--ci`**, **`--json`**, **OpenCode** and **`config.json`** settings), optional **cloud sync**, and **step-level** escapes (partial pipelines, resumes, deterministic checks).
4
+
5
+ ## The three factory-level commands
6
+
7
+ 1. **`easyspecs-cli analysis` — create new context**
8
+ Runs the full **Generate Context** factory end to end (synthesis until stable, coverage, remediation, reporting, link mapping, index assembly). Use this when you need a fresh or full rebuild of **`.gluecharm/context`** from the repo. Optional **`--upload`** pushes resulting context to EasySpecs after **`auth login`** and **`config set-project-id`**. **`--synthesis-only`** stops after synthesis; **`--force-new-context-analysis`** overrides skip-when-already-analyzed behavior when the factory would otherwise exit early.
9
+
10
+ 2. **`easyspecs-cli update context` — update context from code churn**
11
+ Incremental refresh from a **git delta** since the stored baseline (**`easyspecs.factory.updateContext.lastRunAt`**) or, when that is absent, inferred from workspace context mtimes: materialises **`changes-since-date.md`**, runs **scoped** remediation when commits and touched paths warrant it, then optional promotion and **`--upload`**. Use this day to day after **`analysis`** when the codebase moved but specs did not restart from zero.
12
+
13
+ 3. **`easyspecs-cli context drift <referencePath>` — analyze drift against specs**
14
+ **`referencePath`** is a **file or directory** of truth documents (requirements, specs, PRD, architecture notes — whatever your team treats as ground truth relative to repo root). The CLI compares **repository / analysis worktree** context against that reference (OpenCode-assisted), writes **`drift-<label>-<date>.md`** under **`.gluecharm/context/drift/`**, and can update the reference index markdown. **`--label <slug>`** names the report file; **`--index <path>`** overrides which root markdown anchors the comparison; **`--dry-run`** validates references only (**no worktree, agent, or writes**).
15
+
16
+ **Supporting commands (not substitutes for those three goals):** **`auth`** and **`config`** wire API access and **`easyspecs.easyspecsProjectId`**; **`download context`** / **`upload context`** / **`upload republish`** move artefacts between disk and EasySpecs; **`doctor`** checks readiness and redacted merged settings; **`diagnose`** and **`context link-graph`** are deterministic gates and link maintenance; **`run synthesis`** and **`run synthesis resume-*`** run single stages or catch-up without the full factory; **`ace *`** manages optional learnings under **`.gluecharm/context/learnings`**.
17
+
18
+ **Vocabulary:** A **Factory** is the full ordered **`analysis`** run. A **Pipeline** is one major stage inside it (synthesis, coverage, remediation, link mapping, upload, download). A **Workstation** is one atomic OpenCode or programmatic step inside a pipeline. Canonical **`config.json`** keys live under **`easyspecs.factory.*`**, **`easyspecs.workstations.*`**, and **`easyspecs.pipelines.upload.*`**; legacy **`easyspecs.orchestration.*`**, **`easyspecs.macro.debug`**, and several **`easyspecs.analysis.*`** tunables still work for one deprecation cycle and may log **`[deprecated-setting]`** on stderr when read. Human stderr may tag lines **`[factory]`**, **`[pipeline:…]`**, **`[workstation:…]`**, **`[pool]`**, **`[ace]`**.
4
19
 
5
20
  Published as **`@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is **`easyspecs-cli`**.
6
21
 
@@ -32,7 +47,7 @@ npx @gluecharm-lab/easyspecs-cli@latest help
32
47
 
33
48
  ## Quick start
34
49
 
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**:
50
+ From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for **`analysis`**, **`update context`**, **diagnose**, **upload**, and **`download context`**:
36
51
 
37
52
  ```bash
38
53
  cd /your/repo
@@ -41,7 +56,7 @@ easyspecs-cli config init
41
56
  easyspecs-cli analysis
42
57
  ```
43
58
 
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).
59
+ **`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). After the first **`analysis`**, typical follow-ups are **`update context`** (incremental sync with git) and **`context drift`** when you hold truth in specs files/folders elsewhere in the repo. Use **`download context`** (**`auth login`** + **`config set-project-id`**) to pull stored context from EasySpecs into **`.gluecharm/context`**. Append **`analysis --upload`** or **`update context --upload`** to sync edits back after login + project id. Use **`--ci`** in automation for non-interactive behaviour and stricter defaults (e.g. Factory outer-iteration cap).
45
60
 
46
61
  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
62
 
@@ -55,11 +70,11 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
55
70
 
56
71
  ## Download context (pull from EasySpecs)
57
72
 
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.
73
+ Use this when you want **application context** already stored for the EasySpecs **project** written into **`<repo>/.gluecharm/context`** (after a clone, environment switch, or to match cloud contents).
59
74
 
60
75
  **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
76
 
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.
77
+ **Behaviour:** the CLI **GET**s the application, reads linked identifiers for persisted context fragments, batches a content **GET**, and writes one UTF‑8 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
78
 
64
79
  ```bash
65
80
  cd /your/repo
@@ -177,15 +192,18 @@ Merge order for **`easyspecs-cli`**: **`.easyspecs/config.json`** plus global CL
177
192
  | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for reference; analysis still uses the live repo. |
178
193
  | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Precedence: global **`--session-path`** → **`cliSessionPath`** → home default. |
179
194
  | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (shortcut; see **`openCodeRuntime`**). |
180
- | `easyspecs.analysis.*` | Pipeline settings, **`promoteContextToWorkspace`**, and optional **`cloudContextAnalyzed`** / **`cloudContextAnalyzedAt`** (when **`cloudContextAnalyzed`** is **`true`**, **`cloudContextAnalyzedAt`** should be a non-null ISO timestamp). |
181
- | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap. |
195
+ | `easyspecs.analysis.*` | **`promoteContextToWorkspace`**, ACE toggles, and other analysis-only flags. Cloud “already analyzed” cache is canonical under **`easyspecs.factory.cloudContextAnalyzed`** / **`At`** (legacy **`easyspecs.analysis.cloudContext*`** still read once with deprecation stderr). |
196
+ | `easyspecs.factory.*` | Factory debug, backoff, outer-iteration caps, ping-pong cap, cloud cache. Replaces **`easyspecs.orchestration.*`** and **`easyspecs.macro.debug`** (aliases still read). |
197
+ | `easyspecs.workstations.*` | OpenCode argv, timeouts, repair attempts, pool width, coordination lock timeout (canonical; legacy **`easyspecs.analysis.openCodeTest*`** / **`markdown*`** / **`listJsonSchemaRepairAttempts`** / **`maxConcurrentOpenCodeAgents`** aliases). |
198
+ | `easyspecs.pipelines.upload.useBatch` | Upload batching (legacy **`easyspecs.analysis.uploadUseBatch`**). |
199
+ | `easyspecs.orchestration.*` | **Deprecated** — prefer **`easyspecs.factory.*`**. |
182
200
  | `easyspecs.openCodeRuntime` | Providers (`apiKey`, `defaultModel` per provider), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay`. |
183
201
  | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | Number or **`null`**. **`null`** means **`diagnose reference-coverage`** does not fail on percentage alone. |
184
202
  | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). |
185
203
  | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`**; empty **`""`** → automatic resolution from the analysis snapshot. |
186
204
  | `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
205
  | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms) for that GET; default **15000** if omitted. |
188
- | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log extra lines to stderr. |
206
+ | `easyspecs.factory.debug` | When **`true`**, Factory phase transitions log extra lines to stderr. Legacy **`easyspecs.macro.debug`**. |
189
207
  | `easyspecs.cli.bundledResourcesRoot` | Optional absolute or repo-relative path to the bundled **`resources/`** directory. Empty → resolve next to the installed CLI package. |
190
208
  | `easyspecs.auth.ciLogin.email` / `password` | Used with **`--ci`** when **`--email` / `--password`** are omitted on **`auth login`**. Prefer CI-generated **`config.json`**; avoid committing secrets. |
191
209
 
@@ -200,7 +218,7 @@ These appear **before** the subcommand (everything after the first non-flag toke
200
218
  | Flag | Effect |
201
219
  | ---- | ------ |
202
220
  | `--cwd <dir>` | Repository root for git resolution and paths (default: current working directory). |
203
- | `--ci` | Non-interactive mode; affects merged settings (e.g. macro outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
221
+ | `--ci` | Non-interactive mode; affects merged settings (e.g. Factory outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
204
222
  | `--json` | On supported exits, one JSON summary line on stdout. |
205
223
  | `--verbose` | Extra stderr logging where implemented. |
206
224
  | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
@@ -212,14 +230,14 @@ These appear **before** the subcommand (everything after the first non-flag toke
212
230
  | `--version`, `-V` | CLI package version. Does **not** create config. |
213
231
  | `--config <path>` | Parsed but **unused** in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
214
232
 
215
- ## Diagnose-only flags
233
+ ## Diagnose / context flags
216
234
 
217
- Used on the tail of **`diagnose <subcommand>`** (after the subcommand name):
235
+ Used on the tail of **`diagnose <subcommand>`** or **`context link-graph`**:
218
236
 
219
237
  | Flag | Values | Meaning |
220
238
  | ---- | ------ | ------- |
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). |
239
+ | `--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`**, **`context link-graph`**). |
240
+ | `--worktree` | path | Analysis git checkout (use with **`--root worktree`**, or alone where **`diagnose zero-reference`** documents it). |
223
241
 
224
242
  ## Commands and flags (complete)
225
243
 
@@ -240,22 +258,25 @@ Every command the CLI accepts, with command-specific tokens. Global flags above
240
258
  | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. **`--promote` / `--no-promote`** affect promotion after success. |
241
259
  | `run synthesis resume-missing` | **`--worktree <path>`** (optional) | Parallel missing-artefact remediation pool on an existing checkout (from **`--worktree`** or last snapshot). **`requireOpenCode`**. |
242
260
  | `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). |
261
+ | `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only`** — **create new context** trajectory. **`--upload`** runs backend sync after the factory (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.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
262
+ | `update context` | **`--upload`** (optional; any order in tail) | **Update context** trajectory: git window after baseline → worktree → **`changes-since-date.md`** → optional remediation → **`--promote` / `--no-promote`** → optional **`--upload`** (mtime-scoped files) → **`easyspecs.factory.updateContext.lastRunAt`**. Seed context should exist on **HEAD** in the checkout (the factory may copy from workspace when the worktree lacks context). |
244
263
  | `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Reference coverage gate; optional percent limit via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
245
264
  | `diagnose coordination-duplicates` | same | Duplicate/orphan reporting; **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
246
265
  | `diagnose coverage-report` | same | Writes coverage execution report path. |
247
266
  | `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. |
267
+ | `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). After a successful pool run, applies context markdown navigation links under the analysis checkout context directory (fails the command if that step reports broken links). |
268
+ | `context link-graph` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Refreshes EasySpecs navigation marker blocks in **`.gluecharm/context/**/*.md`** from coordination JSON only (no agents). **`--json`** may include **`contextDir`**, **`error`**, **`brokenLinks`**. |
269
+ | `context drift <referencePath>` | **`--label <slug>`**, **`--index <path>`**, **`--dry-run`**; **`--root` / `--worktree`** tail tokens are accepted and ignored for current routing | **Analyze drift against specs** trajectory: **`referencePath`** = file or directory of reference docs. Uses analysis worktree + OpenCode drift agent → **`.gluecharm/context/drift/drift-<slug>-<date>.md`** and reference index maintenance; global **`--promote` / `--no-promote`** apply when not **`--dry-run`**. Success stdout: drift report path. |
270
+ | `download context` | **`--force`**, **`--replace-from-cloud`** (optional; any order after **`download context`**) | Requires **`auth login`** session + **`easyspecs.easyspecsProjectId`**. Resolves linked context documents from **`GET /api/content/application/:id`**, batch-fetches content, 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
271
  | `upload context` | — | Requires auth session + **`easyspecs.easyspecsProjectId`**. Context dir: **`<repo>/.gluecharm/context`**. Optional cloud status GET per **`easyspecs.upload.fetchContextAnalyzedInCloud`**. |
251
272
  | `upload republish` | — | Same auth + project id; context dir from **`easyspecs.upload.contextDirectory`** or analysis worktree snapshot. Same optional cloud status behaviour as **`upload context`**. |
252
273
  | `ace clear` | — | Deletes learnings under **`.gluecharm/context/learnings`**. |
253
274
  | `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`**. |
275
+ | `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.maxConcurrentAgents`** (schema field name; mirrors **`easyspecs.workstations.maxConcurrentAi`** / legacy **`maxConcurrentOpenCodeAgents`**). |
255
276
 
256
277
  **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
278
 
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.
279
+ **EasySpecs API session:** **`download context`**, **`upload context`**, **`upload republish`**, **`analysis --upload`**, and **`update context --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
280
 
260
281
  **Unknown command:** prints help and exits with a usage error.
261
282
 
package/commands.md CHANGED
@@ -1,6 +1,18 @@
1
1
  # EasySpecs CLI — commands, flags, and configuration
2
2
 
3
- Published package: **`@gluecharm-lab/easyspecs-cli`** (`easyspecs-cli`). Source of truth for routing: [`src/cli/main.ts`](../../src/cli/main.ts), argument parsing: [`src/cli/argv.ts`](../../src/cli/argv.ts), merged settings: [`mergeEasyspecsCliSettings`](../../src/cli/cliSettings.ts), per-repo config: [`src/config/easyspecsConfigFile.ts`](../../src/config/easyspecsConfigFile.ts), CLI API URL resolution: [`src/easyspecsApiBaseUrlCli.ts`](../../src/easyspecsApiBaseUrlCli.ts). The VS Code extension resolves API URLs via [`src/apiBaseUrlResolve.ts`](../../src/apiBaseUrlResolve.ts); **`easyspecs-cli` does not use that chain** for System Manager origin (**SRS-43 R30 / R34**).
3
+ Published package: **`@gluecharm-lab/easyspecs-cli`** (`easyspecs-cli`). Source of truth for routing and option registration: [`src/cli/cliProgram.ts`](../../src/cli/cliProgram.ts), command dispatch and business flow wiring: [`src/cli/main.ts`](../../src/cli/main.ts), merged settings: [`mergeEasyspecsCliSettings`](../../src/cli/cliSettings.ts), per-repo config: [`src/config/easyspecsConfigFile.ts`](../../src/config/easyspecsConfigFile.ts), CLI API URL resolution: [`src/easyspecsApiBaseUrlCli.ts`](../../src/easyspecsApiBaseUrlCli.ts). The VS Code extension resolves API URLs via [`src/apiBaseUrlResolve.ts`](../../src/apiBaseUrlResolve.ts); **`easyspecs-cli` does not use that chain** for System Manager origin (**SRS-43 R30 / R34**).
4
+
5
+ ### Vocabulary (SRS-53)
6
+
7
+ End-to-end behaviour and file layout: see the repo root companion **`run-analysis-flow.md`** (no URL; same repository).
8
+
9
+ | Term | One-line meaning |
10
+ |------|------------------|
11
+ | **Factory** | The ordered **Generate Context** run (CLI: **`analysis`**; VS Code: Diagnosis **Run factory** / **Stop factory**). |
12
+ | **Pipeline** | A named stage the Factory composes: Synthesis, Coverage, Remediation, Link Mapping, Upload, or Download. |
13
+ | **Workstation** | One atomic unit inside a Pipeline (OpenCode agent + deterministic validators / repair loop, or a programmatic step). |
14
+
15
+ **Stderr tags (human TTY mode):** phase changes may insert a blank line when the family changes. Tags include **`[factory]`**, **`[pipeline:synthesis]`** (and `coverage`, `remediation`, `link-mapping`, `upload`, `download`), **`[workstation:<id>]`** for OpenCode subprocess lines, **`[pool]`** / **`[queue]`** for work queues, **`[deprecated-setting]`** when a legacy **`config.json`** key was consumed (canonical keys: **`easyspecs.factory.*`**, **`easyspecs.workstations.*`**, **`easyspecs.pipelines.upload.*`** — see SRS-53 alias table). **`[ace]`** and **`[open questions]`** unchanged.
4
16
 
5
17
  Quick usage:
6
18
 
@@ -12,12 +24,12 @@ easyspecs-cli help
12
24
 
13
25
  ## Global options
14
26
 
15
- These flags may appear **before** the subcommand. Anything after the first non-flag token is treated as the command and its arguments ([`parseArgv`](../../src/cli/argv.ts)).
27
+ These flags may appear **before** the subcommand. Parsing and command registration are implemented with Commander in [`src/cli/cliProgram.ts`](../../src/cli/cliProgram.ts), with command execution in [`src/cli/main.ts`](../../src/cli/main.ts).
16
28
 
17
29
  | Flag | Effect |
18
30
  |------|--------|
19
31
  | `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
20
- | `--ci` | Non-interactive mode; feeds into merged settings (e.g. macro outer-iteration default when unlimited). **`EASYSPECS_CI` is not read** — use this flag in CI. |
32
+ | `--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. |
21
33
  | `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. |
22
34
  | `--verbose` | Extra stderr logging where implemented. |
23
35
  | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
@@ -28,7 +40,7 @@ These flags may appear **before** the subcommand. Anything after the first non-f
28
40
  | `--version`, `-V` | Print CLI package version (also `version` as first positional). Does **not** create config. |
29
41
  | `--config <path>` | Parsed but **unused** by `main.ts` today; configuration is read from `<repoRoot>/.easyspecs/config.json`. |
30
42
 
31
- Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI colors. **`FORCE_COLOR`** (any non-empty value) allows colors even when stderr is not a TTY. With **`--json`**, human stderr is normally suppressed; **`--json --verbose`** prints plain stderr **without** ANSI. In human mode, a **blank line** may be printed when the diagnostic **phase** changes (e.g. **`[setup]`** → **`[pool]`** / **`[AgentCode]`**). See **README** (Terminal diagnostics).
43
+ Environment (stderr styling): **`NO_COLOR`** (any non-empty value) disables ANSI colors. **`FORCE_COLOR`** (any non-empty value) allows colors even when stderr is not a TTY. With **`--json`**, human stderr is normally suppressed; **`--json --verbose`** prints plain stderr **without** ANSI. In human mode, a **blank line** may be printed when the diagnostic **phase** changes (e.g. **`[factory]`** → **`[pool]`** / **`[workstation:listFeatures]`**). See **README** (Terminal diagnostics).
32
44
 
33
45
  ---
34
46
 
@@ -40,7 +52,7 @@ Canonical JSON created on first need (except **`help`**, **`version`**, and **`d
40
52
 
41
53
  Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*` product overrides on **`easyspecs-cli`** (**R34**).
42
54
 
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.
55
+ **Workspace layout (SRS-48):** For **`analysis`**, **`update context`**, **`diagnose`**, **`upload`**, **`download context`**, and **`context link-graph`**, 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
56
 
45
57
  | Path | Purpose |
46
58
  |------|---------|
@@ -51,15 +63,17 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
51
63
  | `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`. |
52
64
  | `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)). |
53
65
  | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
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). |
55
- | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
66
+ | `easyspecs.analysis.*` | Remaining analysis flags (e.g. **`promoteContextToWorkspace`**, ACE toggles). **SRS-46 cache** now lives under **`easyspecs.factory.cloudContextAnalyzed`** / **`…At`** (canonical); legacy **`easyspecs.analysis.cloudContext*`** still read for one cycle. |
67
+ | `easyspecs.factory.*` | Factory: **`debug`** (stderr phase transitions; legacy **`easyspecs.macro.debug`**), backoff (`initialDelayMs`, `multiplier`, `maxDelayMs`), `maxOuterIterationsPerPipeline`, `maxPingPongCycles`, `synthesisRemediationShareBackoff`, cloud-context-analyzed cache. Legacy **`easyspecs.orchestration.*`** aliases per SRS-53. |
68
+ | `easyspecs.workstations.*` | OpenCode argv template, timeouts, repair attempts, pool width, coordination lock timeout. Legacy **`easyspecs.analysis.openCodeTest*`** / **`listJsonSchemaRepairAttempts`** / **`markdown*`** / **`maxConcurrentOpenCodeAgents`** / **`coordinationListLockTimeoutMs`** aliases. |
69
+ | `easyspecs.pipelines.upload.useBatch` | Upload batching preference. Legacy **`easyspecs.analysis.uploadUseBatch`**. |
70
+ | `easyspecs.orchestration.*` | **Deprecated** — use **`easyspecs.factory.*`** (SRS-53); still merged when present. |
56
71
  | `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). |
57
72
  | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | `number` \| **`null`**. When **`null`**, `diagnose reference-coverage` does not fail on percent alone (**SRS-44**). |
58
73
  | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). When **`true`**, duplicate/orphan rows fail `diagnose coordination-duplicates`. |
59
74
  | `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. |
75
+ | `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.factory.cloudContext*`** cache (legacy **`easyspecs.analysis.cloudContext*`**). When **`false`**, skips that GET and omits those JSON keys. |
61
76
  | `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms). GET timeout; default **15000** if omitted. |
62
- | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log to stderr ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
63
77
  | `easyspecs.cli.bundledResourcesRoot` | Optional path to bundled **`resources/`** (folder containing **`opencode-agents/`**). Empty → infer next to the CLI package. |
64
78
  | `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. |
65
79
 
@@ -77,9 +91,9 @@ Provider API keys for OpenCode runs should live under **`easyspecs.openCodeRunti
77
91
 
78
92
  ---
79
93
 
80
- ## Diagnose-only flags
94
+ ## Diagnose / context flags
81
95
 
82
- Used after `diagnose <subcommand>`:
96
+ Used after `diagnose <subcommand>` or **`context link-graph`**:
83
97
 
84
98
  | Flag | Values | Meaning |
85
99
  |------|--------|---------|
@@ -105,14 +119,17 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
105
119
  | `auth status` | — | Reads session file. |
106
120
  | `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. |
107
121
  | `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`**. |
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`**). |
122
+ | `analysis` | Optional tokens anywhere in argv: **`--synthesis-only`**, **`--upload`**, **`--force-new-context-analysis`** | **SRS-32** full **Factory** loop: synthesis convergence (until no missing artefacts), coverage, zero-ref, report, **link mapping**, index assembly, optional backend sync. Factory timing from **`merged.factory`** (internal merge shape in [`cliSettings.ts`](../../src/cli/cliSettings.ts)) + **`--ci`** defaults. **`--upload`** requires prior **`auth login`** session. Debug: **`easyspecs.factory.debug`** (legacy **`easyspecs.macro.debug`**). OpenCode options from **`merged.pipelineOpenCode`**. **SRS-46:** if **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** without running the Factory or **`--upload`** (machine fields: **`analysisSkipped`**, **`skipReason`**, **`cloudContextAnalyzedAt`**). |
123
+ | `update context` | Optional **`--upload`** (anywhere in tail, same pattern as **`analysis --upload`**) | **SRS-55:** incremental context refresh — baseline **`easyspecs.factory.updateContext.lastRunAt`** **or** max workspace **`.gluecharm/context`** mtime → git commits after baseline → analysis worktree → seed check (optional copy from workspace if **HEAD** worktree lacks context) → **`changes-since-date.md`** → optional scoped zero-reference remediation → **`--promote` / `--no-promote`** (global) → optional **`--upload`** (files touched this run via mtime gate) → persist **`lastRunAt`**. **`--upload`** requires **`auth`** + **`easyspecs.easyspecsProjectId`**. |
109
124
  | `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. |
110
125
  | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
111
126
  | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
112
127
  | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
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)). |
128
+ | `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). |
129
+ | `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 **`validation`** on broken relative links inside EasySpecs nav regions. |
130
+ | `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. |
114
131
  | `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. |
132
+ | `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*`**). |
116
133
  | `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`**. |
117
134
  | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
118
135
  | `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. |
@@ -123,6 +140,6 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
123
140
  ## Notes
124
141
 
125
142
  - 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)).
126
- - **`download context`** / **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
143
+ - **`download context`** / **`upload`** / **`analysis --upload`** / **`update context --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
127
144
  - Unknown commands print help and exit with a usage error.
128
- - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).
145
+ - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`runCoveragePipeline`](../../src/pipelines/coverage/coveragePipeline.ts)).