@gluecharm-lab/easyspecs-cli 0.0.11 → 0.0.13

package/README.md

@@ -61,6 +61,20 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
 
 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.
 
+## Terminal diagnostics (colors)
+
+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`**.
+
+When **stderr** is an interactive **TTY**, those prefixes are **colorized** (ANSI) for faster scanning.
+
+| Mechanism | Effect |
+| --------- | ------ |
+| **`NO_COLOR`** set to any non-empty value | Colors **disabled** ([no-color.org](https://no-color.org/)). |
+| **`FORCE_COLOR`** set to any non-empty value | Colors **allowed** even if stderr is **not** a TTY (e.g. piping to **`tee`**). |
+| **`--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). |
+
+**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.
+
 ## Configuration
 
 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`**).

package/commands.md

@@ -28,13 +28,15 @@ These flags may appear **before** the subcommand. Anything after the first non-f
 | `--version`, `-V` | Print CLI package version (also `version` as first positional). Does **not** create config. |
 | `--config <path>` | Parsed but **unused** by `main.ts` today; configuration is read from `<repoRoot>/.easyspecs/config.json`. |
 
+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).
+
 ---
 
 ## Shared configuration (SRS-43)
 
 ### File: `<repoRoot>/.easyspecs/config.json`
 
-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.
+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.
 
 Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*` product overrides on **`easyspecs-cli`** (**R34**).
 
@@ -47,12 +49,14 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
 | `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`. |
 | `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)). |
 | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
-| `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
+| `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). |
 | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
 | `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). |
 | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | `number` \| **`null`**. When **`null`**, `diagnose reference-coverage` does not fail on percent alone (**SRS-44**). |
 | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). When **`true`**, duplicate/orphan rows fail `diagnose coordination-duplicates`. |
 | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`** context dir; empty **`""`** → automatic (analysis snapshot). |
+| `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. |
+| `easyspecs.upload.contextAnalyzedStatusTimeoutMs` | Optional positive integer (ms). GET timeout; default **15000** if omitted. |
 | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log to stderr ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
 | `easyspecs.cli.bundledResourcesRoot` | Optional path to bundled **`resources/`** (folder containing **`opencode-agents/`**). Empty → infer next to the CLI package. |
 | `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. |
@@ -99,14 +103,14 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
 | `auth status` | — | Reads session file. |
 | `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. |
 | `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`**. |
-| `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`**. |
+| `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`**). |
 | `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. |
 | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
 | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
 | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
 | `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)). |
-| `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. |
-| `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`**. |
+| `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. |
+| `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`**. |
 | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
 | `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. |
 | `ace auto-learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; checkout = `--worktree` if valid git dir, else **`repoRoot`**. **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`** caps parallelism. |