@gluecharm-lab/easyspecs-cli 0.0.8 → 0.0.9

package/README.md

@@ -2,13 +2,13 @@
 
 Headless **EasySpecs** command-line tool for **context analysis**, **diagnoses**, **macro pipelines**, **upload to EasySpecs**, **auth**, and **ACE** — the same orchestration logic as the [EasySpecs VS Code extension](https://easyspecs.ai), without an editor.
 
-Published as **`@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is **`easyspecs-cli`**.
+Published as `**@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is `**easyspecs-cli`**.
 
 ## Requirements
 
 - **Node.js** ≥ 18  
 - **[OpenCode](https://opencode.ai)** on `PATH` for flows that run agents  
-- A **git repository** with **`.gluecharm/`** (documentation + context layout) when running analysis, diagnose, or upload against a project  
+- A **git repository** with `**.gluecharm/`** (documentation + context layout) when running analysis, diagnose, or upload against a project
 
 ## Install
 
@@ -40,7 +40,7 @@ easyspecs-cli doctor --inspect-config
 easyspecs-cli help
 ```
 
-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 come from **`<repo>/.easyspecs/config.json`**, not ad-hoc environment-variable overrides for product settings.
+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 come from `**<repo>/.easyspecs/config.json**`, not ad-hoc environment-variable overrides for product settings.
 
 ```bash
 easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
@@ -48,36 +48,36 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
 
 ## Commands (overview)
 
-| Area | Examples |
-|------|-----------|
-| **Health** | `doctor` (`--readiness`, `--inspect-config`), `version` |
-| **Config** | `doctor --inspect-config` (inspect merged settings), `config init`, `config set-project-id`, `config set-git-remote` |
-| **Auth** | `auth login --email … --password …`, `auth logout`, `auth status` |
-| **Run synthesis** | `run synthesis`; **`run synthesis resume-missing`** / **`resume-synthesis`** |
-| **Analysis** (full macro pipeline) | `analysis` (optional **`--upload`** after login; **`--synthesis-only`** stops after synthesis) |
-| **Diagnose** | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, … |
-| **Upload** | `upload context`, `upload republish` |
-| **ACE** | `ace clear`, `ace learn`, `ace auto-learn` |
 
-Run **`easyspecs-cli help`** and **`easyspecs-cli <command> --help`** for the full tree and flags.
+| Area                               | Examples                                                                                                             |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Health**                         | `doctor` (`--readiness`, `--inspect-config`), `version`                                                              |
+| **Config**                         | `doctor --inspect-config` (inspect merged settings), `config init`, `config set-project-id`, `config set-git-remote` |
+| **Auth**                           | `auth login --email … --password …`, `auth logout`, `auth status`                                                    |
+| **Run synthesis**                  | `run synthesis`; `**run synthesis resume-missing`** / `**resume-synthesis**`                                         |
+| **Analysis** (full macro pipeline) | `analysis` (optional `**--upload`** after login; `**--synthesis-only**` stops after synthesis)                       |
+| **Diagnose**                       | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, …                                       |
+| **Upload**                         | `upload context`, `upload republish`                                                                                 |
+| **ACE**                            | `ace clear`, `ace learn`, `ace auto-learn`                                                                           |
+
+
+Run `**easyspecs-cli help`** and `**easyspecs-cli <command> --help**` for the full tree and flags.
 
 ## Configuration
 
-Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed). See **[`commands.md`](./commands.md)** for flags and merge rules. **`auth login --email … --password …`** stores tokens for upload commands (optional **`--session-path`** tail updates **`easyspecs.cliSessionPath`** in **`config.json`**).
+Primary configuration file: `**<repo>/.easyspecs/config.json**` (auto-created when needed). See `**[commands.md](./commands.md)**` for flags and merge rules. `**auth login --email … --password …**` stores tokens for upload commands (optional `**--session-path**` tail updates `**easyspecs.cliSessionPath**` in `**config.json**`).
 
-After **`auth login`**, session data is stored at **`easyspecs.cliSessionPath`** in **`config.json`** when set (otherwise **`~/.easyspecs/cli-session.json`**). When the VS Code extension delegates with a temp session file, it passes global **`--session-path <file>`** on the spawned **`easyspecs-cli`** process.
+After `**auth login**`, session data is stored at `**easyspecs.cliSessionPath**` in `**config.json**` when set (otherwise `**~/.easyspecs/cli-session.json**`). When the VS Code extension delegates with a temp session file, it passes global `**--session-path <file>**` on the spawned `**easyspecs-cli**` process.
 
 ## Global flags
 
-`--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, **`--session-path`**, `--environment`, `--promote` / `--no-promote` (see **`--help`**).
+`--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, `**--session-path**`, `--environment`, `--promote` / `--no-promote` (see `**--help**`).
 
 ## Website & documentation
 
 - **Product website:** **[easyspecs.ai](https://easyspecs.ai/)** — sign in, projects, documentation in the browser, and product information. This is the public EasySpecs site (not a source-code host).
-
-- **Command reference** (flags, env, merge rules): [`commands.md`](./commands.md) in this npm package.
-
-- **CLI:** run **`easyspecs-cli help`** for the full command tree.
+- **Command reference** (flags, env, merge rules): `[commands.md](./commands.md)` in this npm package.
+- **CLI:** run `**easyspecs-cli help`** for the full command tree.
 
 Engineering source for this CLI is maintained privately; use **easyspecs.ai** and the docs bundled here for support and usage.
 
@@ -85,4 +85,133 @@ Engineering source for this CLI is maintained privately; use **easyspecs.ai** an
 
 Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
 
-This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX **`Elastic-2.0`**). See **[`LICENSE`](./LICENSE)** in this package for the full text and [Elastic’s licensing overview](https://www.elastic.co/licensing/elastic-license). Other artifacts in the monorepo may use different licenses.
+This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX `**Elastic-2.0`**). See `**[LICENSE](./LICENSE)**` in this package for the full text and [Elastic’s licensing overview](https://www.elastic.co/licensing/elastic-license). Other artifacts in the monorepo may use different licenses.
+
+
+
+```markdown
+# EasySpecs CLI — commands, flags, and configuration
+
+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**).
+
+Quick usage:
+
+```bash
+easyspecs-cli help
+```
+
+---
+
+## Global options
+
+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)).
+
+| Flag | Effect |
+|------|--------|
+| `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
+| `--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. |
+| `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. |
+| `--verbose` | Extra stderr logging where implemented. |
+| `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
+| `--environment production` \| `--environment staging` | Alias: **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
+| `--promote` | After a successful `run synthesis`, copy generated `.gluecharm/context` from the analysis worktree into the workspace repo (when promotion is applicable). |
+| `--no-promote` | Disable that promotion step for this run. |
+| `--help`, `-h` | Show built-in help (also `help` as first positional). Does **not** create `.easyspecs/config.json`. |
+| `--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`. |
+
+---
+
+## 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.
+
+Merge uses **this file + global CLI flags only** — no `EASYSPECS_`* / `VITE_*` product overrides on *`*easyspecs-cli`** (**R34**).
+
+| Path | Purpose |
+|------|---------|
+| `schemaVersion` | Integer (e.g. `1`) for future migrations. |
+| `easyspecs.deploymentEnvironment` | `production` or `staging` (default `production`). Used with built-in System Manager URLs when `apiBaseUrl` is empty. |
+| `easyspecs.apiBaseUrl` | Explicit System Manager origin; wins after `--api-base-url`. Generated defaults use **`https://api.easyspecs.ai`** (production). Use **`""`** only if you want the built-in URL from **`deploymentEnvironment`** / **`--environment`** instead. |
+| `easyspecs.easyspecsProjectId` | Optional EasySpecs **project** id (Content application UUID). **Only** store for uploads / Sync — set via **`Send context`**, **`Changes → Sync`**, **`config set-project-id`**, or **`easyspecs-cli`**. **`upload`** / **`analysis --upload`** read **only** this field (merged **`easyspecs.applicationId`** legacy key maps here). |
+| `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.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). |
+
+### Resolved System Manager URL (`easyspecs-cli`)
+
+**Order:** `--api-base-url` → non-empty `easyspecs.apiBaseUrl` → built-in URL from effective environment (*`*--environment`** \|\| **`easyspecs.deploymentEnvironment`** \|\| **`production`**). No `.env` / `process.env` product keys (**R30**).
+
+Built-in defaults ship in [`src/easyspecsBuiltInApiUrls.ts`](../../src/easyspecsBuiltInApiUrls.ts).
+
+### Environment variables still used by the CLI
+
+| Variable | Purpose |
+|----------|---------|
+| `EASYSPECS_EMAIL` / `EASYSPECS_PASSWORD` | Optional legacy **`auth login`** when **`--ci`** is set and **`--email` / `--password`** are omitted (**SRS-43 §5.3**). Prefer explicit **`--email`** / **`--password`** on the command line for scripts (credentials appear in process listings — avoid shared machines). |
+| `EASYSPECS_EXTENSION_ROOT` | Extension/monorepo root for bundled resources. |
+| `EASYSPECS_CLI_RESOURCES` | Override directory containing **`opencode-agents/`**. |
+| `EASYSPECS_UPLOAD_CONTEXT_DIR` | Upload republish context dir bridging. |
+| `EASYSPECS_CLI_MACRO_DEBUG` | Macro extra logging ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
+| OS-level (e.g. `PATH`) | Finding `node`, `opencode`, `git`. |
+
+Provider API keys for OpenCode runs should live under **`easyspecs.openCodeRuntime.providers`** in **`config.json`**; they are injected into the **child** OpenCode process (**R13**) and redacted in **`doctor --inspect-config`** (**R17**).
+
+---
+
+## Diagnose-only flags
+
+Used after `diagnose <subcommand>`:
+
+| Flag | Values | Meaning |
+|------|--------|---------|
+| `--root` | `workspace` or `worktree` | Whether paths resolve against the workspace repo root or an analysis checkout ([`parseTailFlags`](../../src/cli/parseTailFlags.ts)). |
+| `--worktree` | path | Analysis git checkout (required for `--root worktree` when no path embedded in `--root` flow; combined with explicit `--worktree` — see `main.ts`). |
+
+---
+
+## Command reference
+
+Each row lists **command-specific CLI tokens**, then **what configuration applies**.
+
+| Command | Command-specific flags / tokens | Configuration & notes |
+|---------|--------------------------------|----------------------|
+| `help`, `--help` | — | Global options only; prints usage. |
+| `version` | — | Prints [`PKG_VERSION`](../../src/cli/main.ts) from the bundle. |
+| `doctor` | Optional **`--readiness`**, **`--inspect-config`** | **Does not** create `config.json`. Default (no flags) = **`--readiness`**: repo root, resolved API URL, OpenCode installed/credentials, agents dir. **`--inspect-config`** alone: redacted **`merged`** + **`easyspecsConfig`**. **`--readiness --inspect-config`**: both. Global flags apply (**`--cwd`**, **`--ci`**, **`--api-base-url`**, **`--session-path`**, **`--environment`**, **`--promote`** / **`--no-promote`**). |
+| `config init` | Optional **`--overwrite`** | Creates **`<repo>/.easyspecs/config.json`** with full defaults if missing; imports legacy **`cli.json`** / **`settings.json`** (ACE) when present, same as first-time bootstrap. If the file already exists, does nothing unless **`--overwrite`** (replaces with that bootstrap content). Does not run other commands. |
+| `config set-project-id <id>` | — | Writes **`easyspecs.easyspecsProjectId`** to **`config.json`**, replacing any previous value. Creates **`config.json`** (defaults + legacy import) if missing. |
+| `config set-git-remote <url>` | — | Writes **`easyspecs.defaultGitRemoteUrl`** to **`config.json`**, replacing any previous value. Same bootstrap-if-missing behaviour as **`set-project-id`**. |
+| `auth login` | **`--email <email> --password <password>`**, optional **`--session-path <path>`** (tail; updates **`config.json`**) | Calls **`POST /api/authentication/login`**. On success prints **`OK`** (stdout), exit **0**, and writes tokens + **`apiBaseUrl`** to the session file. Tail **`--session-path`** updates **`easyspecs.cliSessionPath`** in **`config.json`** (normalized repo-relative when under the repo) and writes the session there for this run; omit it to use the existing **`easyspecs.cliSessionPath`** / default **`~/.easyspecs/cli-session.json`**. Global **`--session-path`** (before the command) overrides the effective session file for any command without changing **`config.json`**. On failure prints **`KO: …`** (stderr), exit **`auth`**. Legacy: **`easyspecs-cli --ci auth login`** with **`EASYSPECS_`*** when CLI credentials omitted. **`--password`** on argv is visible to **`ps`**. |
+| `auth logout` | — | Deletes the effective session file (same path rules as **`auth login`**). |
+| `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. **`EASYSPECS_CLI_MACRO_DEBUG`**. OpenCode options from **`merged.pipelineOpenCode`**. |
+| `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | **`EASYSPECS_MAX_PERCENT_NON_REFERENCED`**: if set to a finite number, failure when metric exceeds it. |
+| `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`EASYSPECS_DUPLICATES_STRICT`**: unless `0`, 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_CONTEXT_DIR`** if set and valid, else analysis worktree **`…/.gluecharm/context`** from snapshot, else error. Same project id rule 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. |
+
+---
+
+## Notes
+
+- 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)).
+- **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or legacy **`--ci`** + env).
+- Unknown commands print help and exit with a usage error.
+- Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).
+
+```
+

package/dist/main.cjs

@@ -19457,7 +19457,7 @@ function parseAuthLoginTail(tail) {
 }
 
 // src/cli/main.ts
-var PKG_VERSION = "0.0.8";
+var PKG_VERSION = "0.0.9";
 function logErr(flags, ...a) {
   if (!flags.json) {
     console.error(...a);