@gluecharm-lab/easyspecs-cli 0.0.9 → 0.0.11

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 (5) hide show
  1. package/README.md +166 -148
  2. package/commands.md +15 -16
  3. package/dist/main.cjs +373 -329
  4. package/dist/main.cjs.map +2 -2
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,14 +1,14 @@
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 logic as the [EasySpecs VS Code extension](https://easyspecs.ai), without an editor.
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.
4
4
 
5
- Published as `**@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is `**easyspecs-cli`**.
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](https://opencode.ai)** on `PATH` for flows that run agents
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 from OpenCode’s own documentation
11
+ - A **git repository** with **`.gluecharm/`** (documentation + context layout) when running analysis, diagnose, or upload against a project
12
12
 
13
13
  ## Install
14
14
 
@@ -40,7 +40,7 @@ easyspecs-cli doctor --inspect-config
40
40
  easyspecs-cli help
41
41
  ```
42
42
 
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 come from `**<repo>/.easyspecs/config.json**`, not ad-hoc environment-variable overrides for product settings.
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
44
 
45
45
  ```bash
46
46
  easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
@@ -48,170 +48,188 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
48
48
 
49
49
  ## Commands (overview)
50
50
 
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` |
51
61
 
52
- | Area | Examples |
53
- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
54
- | **Health** | `doctor` (`--readiness`, `--inspect-config`), `version` |
55
- | **Config** | `doctor --inspect-config` (inspect merged settings), `config init`, `config set-project-id`, `config set-git-remote` |
56
- | **Auth** | `auth login --email … --password …`, `auth logout`, `auth status` |
57
- | **Run synthesis** | `run synthesis`; `**run synthesis resume-missing`** / `**resume-synthesis**` |
58
- | **Analysis** (full macro pipeline) | `analysis` (optional `**--upload`** after login; `**--synthesis-only**` stops after synthesis) |
59
- | **Diagnose** | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, … |
60
- | **Upload** | `upload context`, `upload republish` |
61
- | **ACE** | `ace clear`, `ace learn`, `ace auto-learn` |
62
-
63
-
64
- Run `**easyspecs-cli help`** and `**easyspecs-cli <command> --help**` for the full tree and flags.
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.
65
63
 
66
64
  ## Configuration
67
65
 
68
- 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**`).
69
-
70
- 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.
71
-
72
- ## Global flags
73
-
74
- `--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, `**--session-path**`, `--environment`, `--promote` / `--no-promote` (see `**--help**`).
75
-
76
- ## Website & documentation
77
-
78
- - **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).
79
- - **Command reference** (flags, env, merge rules): `[commands.md](./commands.md)` in this npm package.
80
- - **CLI:** run `**easyspecs-cli help`** for the full command tree.
81
-
82
- Engineering source for this CLI is maintained privately; use **easyspecs.ai** and the docs bundled here for support and usage.
83
-
84
- ## License
85
-
86
- Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
87
-
88
- 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.
89
-
90
-
91
-
92
- ```markdown
93
- # EasySpecs CLI — commands, flags, and configuration
94
-
95
- 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**).
96
-
97
- Quick usage:
98
-
99
- ```bash
100
- easyspecs-cli help
66
+ 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`**).
67
+
68
+ 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`**.
69
+
70
+ ### Default **`config.json`** (from **`easyspecs-cli config init`**)
71
+
72
+ 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:
73
+
74
+ ```json
75
+ {
76
+ "schemaVersion": 2,
77
+ "easyspecs": {
78
+ "deploymentEnvironment": "production",
79
+ "apiBaseUrl": "https://api.easyspecs.ai",
80
+ "easyspecsProjectId": "",
81
+ "defaultGitRemoteUrl": "",
82
+ "cliSessionPath": "",
83
+ "openCode": {
84
+ "executable": "opencode",
85
+ "skipCredentialsCheck": false
86
+ },
87
+ "analysis": {
88
+ "promoteContextToWorkspace": true
89
+ },
90
+ "orchestration": {},
91
+ "openCodeRuntime": {
92
+ "executable": "opencode",
93
+ "skipCredentialsCheck": false,
94
+ "credentialsPath": ".opencode/auth.json",
95
+ "providers": {},
96
+ "run": {
97
+ "argvTemplate": [
98
+ "run",
99
+ "--agent",
100
+ "{agentId}",
101
+ "Execute the task described in the attached EasySpecs prompt file.",
102
+ "-f",
103
+ "{promptFile}"
104
+ ],
105
+ "timeoutMs": 600000
106
+ },
107
+ "coordinationRepairs": {
108
+ "listJsonSchemaRepairAttempts": 1,
109
+ "markdownEvidenceRepairAttempts": 2,
110
+ "markdownOpenQuestionIterations": 5
111
+ },
112
+ "pool": {
113
+ "maxConcurrentAgents": 30
114
+ },
115
+ "projectConfigOverlay": {}
116
+ },
117
+ "diagnose": {
118
+ "zeroReference": {
119
+ "maxPercentNonReferenced": null
120
+ },
121
+ "coordinationDuplicates": {
122
+ "strict": true
123
+ }
124
+ },
125
+ "upload": {
126
+ "contextDirectory": ""
127
+ },
128
+ "macro": {
129
+ "debug": false
130
+ },
131
+ "cli": {
132
+ "bundledResourcesRoot": ""
133
+ },
134
+ "auth": {
135
+ "ciLogin": {}
136
+ }
137
+ }
138
+ }
101
139
  ```
102
140
 
103
- ---
104
-
105
- ## Global options
106
-
107
- 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)).
108
-
109
- | Flag | Effect |
110
- |------|--------|
111
- | `--cwd <dir>` | Repository root for git resolution and file paths (default: current working directory). |
112
- | `--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. |
113
- | `--json` | On supported exits, prints one JSON summary line on stdout; suppresses some human-oriented stderr unless `--verbose`. |
114
- | `--verbose` | Extra stderr logging where implemented. |
115
- | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl` in config). |
116
- | `--environment production` \| `--environment staging` | Alias: **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
117
- | `--promote` | After a successful `run synthesis`, copy generated `.gluecharm/context` from the analysis worktree into the workspace repo (when promotion is applicable). |
118
- | `--no-promote` | Disable that promotion step for this run. |
119
- | `--help`, `-h` | Show built-in help (also `help` as first positional). Does **not** create `.easyspecs/config.json`. |
120
- | `--version`, `-V` | Print CLI package version (also `version` as first positional). Does **not** create config. |
121
- | `--config <path>` | Parsed but **unused** by `main.ts` today; configuration is read from `<repoRoot>/.easyspecs/config.json`. |
141
+ ### Config keys (reference)
122
142
 
123
- ---
124
-
125
- ## Shared configuration (SRS-43)
126
-
127
- ### File: `<repoRoot>/.easyspecs/config.json`
128
-
129
- 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.
130
-
131
- Merge uses **this file + global CLI flags only** — no `EASYSPECS_`* / `VITE_*` product overrides on *`*easyspecs-cli`** (**R34**).
143
+ 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.
132
144
 
133
145
  | Path | Purpose |
134
- |------|---------|
135
- | `schemaVersion` | Integer (e.g. `1`) for future migrations. |
146
+ | ---- | ------- |
147
+ | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
136
148
  | `easyspecs.deploymentEnvironment` | `production` or `staging` (default `production`). Used with built-in System Manager URLs when `apiBaseUrl` is empty. |
137
- | `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. |
138
- | `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). |
139
- | `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`. |
140
- | `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)). |
141
- | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
142
- | `easyspecs.analysis.`* | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
143
- | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
144
- | `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). |
145
-
146
- ### Resolved System Manager URL (`easyspecs-cli`)
149
+ | `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. |
150
+ | `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. |
151
+ | `easyspecs.defaultGitRemoteUrl` | Optional primary **`git remote`** URL (HTTPS or SSH) for reference; analysis still uses the live repo. |
152
+ | `easyspecs.cliSessionPath` | Repo-relative or absolute path to **`cli-session.json`**. Empty **`""`** → **`~/.easyspecs/cli-session.json`**. Precedence: global **`--session-path`** → **`cliSessionPath`** → home default. |
153
+ | `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (shortcut; see **`openCodeRuntime`**). |
154
+ | `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
155
+ | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap. |
156
+ | `easyspecs.openCodeRuntime` | Providers (`apiKey`, `defaultModel` per provider), `run`, `coordinationRepairs`, `pool`, `projectConfigOverlay`. |
157
+ | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | Number or **`null`**. **`null`** means **`diagnose reference-coverage`** does not fail on percentage alone. |
158
+ | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). |
159
+ | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`**; empty **`""`** → automatic resolution from the analysis snapshot. |
160
+ | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log extra lines to stderr. |
161
+ | `easyspecs.cli.bundledResourcesRoot` | Optional absolute or repo-relative path to the bundled **`resources/`** directory. Empty → resolve next to the installed CLI package. |
162
+ | `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. |
163
+
164
+ **Resolved API base URL:** `--api-base-url` → non-empty **`easyspecs.apiBaseUrl`** → built-in URL from **`--environment`** or **`easyspecs.deploymentEnvironment`** or **`production`**.
165
+
166
+ **OpenCode providers:** put API keys under **`easyspecs.openCodeRuntime.providers`** in **`config.json`**. They are passed to the **`opencode`** child process and are redacted in **`doctor --inspect-config`** output.
147
167
 
148
- **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**).
168
+ ## Global flags
149
169
 
150
- Built-in defaults ship in [`src/easyspecsBuiltInApiUrls.ts`](../../src/easyspecsBuiltInApiUrls.ts).
170
+ `--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, **`--session-path`**, `--environment`, `--promote` / `--no-promote` — details in **`easyspecs-cli --help`**.
151
171
 
152
- ### Environment variables still used by the CLI
172
+ ### Global options (table)
153
173
 
154
- | Variable | Purpose |
155
- |----------|---------|
156
- | `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). |
157
- | `EASYSPECS_EXTENSION_ROOT` | Extension/monorepo root for bundled resources. |
158
- | `EASYSPECS_CLI_RESOURCES` | Override directory containing **`opencode-agents/`**. |
159
- | `EASYSPECS_UPLOAD_CONTEXT_DIR` | Upload republish context dir bridging. |
160
- | `EASYSPECS_CLI_MACRO_DEBUG` | Macro extra logging ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
161
- | OS-level (e.g. `PATH`) | Finding `node`, `opencode`, `git`. |
174
+ | Flag | Effect |
175
+ | ---- | ------ |
176
+ | `--cwd <dir>` | Repository root for git resolution and paths (default: current working directory). |
177
+ | `--ci` | Non-interactive mode; affects merged settings (e.g. macro outer-iteration default). **`EASYSPECS_CI` is not read** — use this flag. |
178
+ | `--json` | On supported exits, one JSON summary line on stdout. |
179
+ | `--verbose` | Extra stderr logging where implemented. |
180
+ | `--api-base-url <url>` | System Manager API origin for this process (overrides `easyspecs.apiBaseUrl`). |
181
+ | `--environment production` \| `staging` | Alias **`--env`**. Overrides `easyspecs.deploymentEnvironment` for built-in URL selection when no explicit URL is set. |
182
+ | `--promote` | After **`run synthesis`**, copy generated **`.gluecharm/context`** from the analysis worktree into the workspace repo when applicable. |
183
+ | `--no-promote` | Disable that promotion for this run. |
184
+ | `--help`, `-h` | Built-in help. Does **not** create **`.easyspecs/config.json`**. |
185
+ | `--version`, `-V` | CLI package version. Does **not** create config. |
186
+ | `--config <path>` | Reserved / unused in current releases; read **`<repo>/.easyspecs/config.json`** instead. |
162
187
 
163
- 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**).
188
+ ### Diagnose-only flags
164
189
 
165
- ---
190
+ Used after **`diagnose <subcommand>`**:
166
191
 
167
- ## Diagnose-only flags
192
+ | Flag | Values | Meaning |
193
+ | ---- | ------ | ------- |
194
+ | `--root` | `workspace` or `worktree` | Resolve paths against the workspace repo root or an analysis checkout. |
195
+ | `--worktree` | path | Analysis git checkout (use with **`--root worktree`** when needed). |
168
196
 
169
- Used after `diagnose <subcommand>`:
197
+ ## Command reference
170
198
 
171
- | Flag | Values | Meaning |
172
- |------|--------|---------|
173
- | `--root` | `workspace` or `worktree` | Whether paths resolve against the workspace repo root or an analysis checkout ([`parseTailFlags`](../../src/cli/parseTailFlags.ts)). |
174
- | `--worktree` | path | Analysis git checkout (required for `--root worktree` when no path embedded in `--root` flow; combined with explicit `--worktree` — see `main.ts`). |
199
+ | Command | Tokens / notes | Behaviour summary |
200
+ | ------- | ---------------- | ------------------ |
201
+ | `help`, `--help` | — | Prints usage. |
202
+ | `version` | — | Prints the CLI package version string. |
203
+ | `doctor` | **`--readiness`**, **`--inspect-config`** | Does **not** create **`config.json`**. Default (no flags) behaves like **`--readiness`**. **`--inspect-config`** prints redacted merged settings and config. |
204
+ | `config init` | **`--overwrite`** optional | Writes full defaults; may import legacy **`.easyspecs/cli.json`** once if present. |
205
+ | `config set-project-id <id>` | — | Sets **`easyspecs.easyspecsProjectId`**. |
206
+ | `config set-git-remote <url>` | — | Sets **`easyspecs.defaultGitRemoteUrl`**. |
207
+ | `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. |
208
+ | `auth logout` | — | Clears the effective session file. |
209
+ | `auth status` | — | Shows whether a session file exists / looks populated. |
210
+ | `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. |
211
+ | `run synthesis resume-missing`, `resume-synthesis` | **`--worktree`** | Resumes remediation / synthesis on a known checkout. |
212
+ | `analysis` | **`--synthesis-only`**, **`--upload`** | Full macro loop; **`--upload`** needs **`auth login`** and project id in config. |
213
+ | `diagnose reference-coverage` | **`--root`**, **`--worktree`** | Optional percent gate via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
214
+ | `diagnose coordination-duplicates` | same | **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
215
+ | `diagnose coverage-report` | same | Coverage report path on disk. |
216
+ | `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state. |
217
+ | `diagnose zero-reference` | **`--worktree`** | Zero-reference remediation pool (**OpenCode**). |
218
+ | `upload context` | — | Requires auth session and **`easyspecs.easyspecsProjectId`**. |
219
+ | `upload republish` | — | Same auth rules; context dir from **`easyspecs.upload.contextDirectory`** or analysis snapshot. |
220
+ | `ace clear` | — | Deletes learnings under **`.gluecharm/context/learnings`**. |
221
+ | `ace learn`, `ace auto-learn` | **`--worktree`** | ACE offline learning pools (**OpenCode**). |
222
+
223
+ ## Product information
224
+
225
+ **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.
175
226
 
176
- ---
227
+ ## License
177
228
 
178
- ## Command reference
229
+ Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
179
230
 
180
- Each row lists **command-specific CLI tokens**, then **what configuration applies**.
181
-
182
- | Command | Command-specific flags / tokens | Configuration & notes |
183
- |---------|--------------------------------|----------------------|
184
- | `help`, `--help` | — | Global options only; prints usage. |
185
- | `version` | — | Prints [`PKG_VERSION`](../../src/cli/main.ts) from the bundle. |
186
- | `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`**). |
187
- | `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. |
188
- | `config set-project-id <id>` | — | Writes **`easyspecs.easyspecsProjectId`** to **`config.json`**, replacing any previous value. Creates **`config.json`** (defaults + legacy import) if missing. |
189
- | `config set-git-remote <url>` | — | Writes **`easyspecs.defaultGitRemoteUrl`** to **`config.json`**, replacing any previous value. Same bootstrap-if-missing behaviour as **`set-project-id`**. |
190
- | `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`**. |
191
- | `auth logout` | — | Deletes the effective session file (same path rules as **`auth login`**). |
192
- | `auth status` | — | Reads session file. |
193
- | `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. |
194
- | `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`**. |
195
- | `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`**. |
196
- | `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. |
197
- | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`EASYSPECS_DUPLICATES_STRICT`**: unless `0`, duplicate/orphan issues fail the exit code. |
198
- | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
199
- | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
200
- | `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)). |
201
- | `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. |
202
- | `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`**. |
203
- | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
204
- | `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. |
205
- | `ace auto-learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; checkout = `--worktree` if valid git dir, else **`repoRoot`**. **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`** caps parallelism. |
206
-
207
- ---
208
-
209
- ## Notes
210
-
211
- - 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)).
212
- - **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or legacy **`--ci`** + env).
213
- - Unknown commands print help and exit with a usage error.
214
- - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).
231
+ 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.
215
232
 
216
- ```
233
+ ## Bundled documentation
217
234
 
235
+ 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).
package/commands.md CHANGED
@@ -40,7 +40,7 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
40
40
 
41
41
  | Path | Purpose |
42
42
  |------|---------|
43
- | `schemaVersion` | Integer (e.g. `1`) for future migrations. |
43
+ | `schemaVersion` | Integer (e.g. `2`) for future migrations. |
44
44
  | `easyspecs.deploymentEnvironment` | `production` or `staging` (default `production`). Used with built-in System Manager URLs when `apiBaseUrl` is empty. |
45
45
  | `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. |
46
46
  | `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). |
@@ -50,6 +50,12 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
50
50
  | `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
51
51
  | `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
52
52
  | `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). |
53
+ | `easyspecs.diagnose.zeroReference.maxPercentNonReferenced` | `number` \| **`null`**. When **`null`**, `diagnose reference-coverage` does not fail on percent alone (**SRS-44**). |
54
+ | `easyspecs.diagnose.coordinationDuplicates.strict` | Boolean (default **`true`**). When **`true`**, duplicate/orphan rows fail `diagnose coordination-duplicates`. |
55
+ | `easyspecs.upload.contextDirectory` | Repo-relative or absolute override for **`upload republish`** context dir; empty **`""`** → automatic (analysis snapshot). |
56
+ | `easyspecs.macro.debug` | When **`true`**, macro phase transitions log to stderr ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
57
+ | `easyspecs.cli.bundledResourcesRoot` | Optional path to bundled **`resources/`** (folder containing **`opencode-agents/`**). Empty → infer next to the CLI package. |
58
+ | `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. |
53
59
 
54
60
  ### Resolved System Manager URL (`easyspecs-cli`)
55
61
 
@@ -57,16 +63,9 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*`
57
63
 
58
64
  Built-in defaults ship in [`src/easyspecsBuiltInApiUrls.ts`](../../src/easyspecsBuiltInApiUrls.ts).
59
65
 
60
- ### Environment variables still used by the CLI
66
+ ### No EasySpecs `EASYSPECS_*` configuration env (**SRS-44**)
61
67
 
62
- | Variable | Purpose |
63
- |----------|---------|
64
- | `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). |
65
- | `EASYSPECS_EXTENSION_ROOT` | Extension/monorepo root for bundled resources. |
66
- | `EASYSPECS_CLI_RESOURCES` | Override directory containing **`opencode-agents/`**. |
67
- | `EASYSPECS_UPLOAD_CONTEXT_DIR` | Upload republish context dir bridging. |
68
- | `EASYSPECS_CLI_MACRO_DEBUG` | Macro extra logging ([`macroHeadlessHost`](../../src/analysis/macroHeadlessHost.ts)). |
69
- | OS-level (e.g. `PATH`) | Finding `node`, `opencode`, `git`. |
68
+ **`easyspecs-cli`** does **not** read **`EASYSPECS_*`**, **`VITE_*`**, or **`.env`** for product settings — use **`.easyspecs/config.json`** (+ global CLI flags) only. OS-level variables such as **`PATH`** still apply for finding **`node`**, **`opencode`**, **`git`**.
70
69
 
71
70
  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**).
72
71
 
@@ -95,19 +94,19 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
95
94
  | `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. |
96
95
  | `config set-project-id <id>` | — | Writes **`easyspecs.easyspecsProjectId`** to **`config.json`**, replacing any previous value. Creates **`config.json`** (defaults + legacy import) if missing. |
97
96
  | `config set-git-remote <url>` | — | Writes **`easyspecs.defaultGitRemoteUrl`** to **`config.json`**, replacing any previous value. Same bootstrap-if-missing behaviour as **`set-project-id`**. |
98
- | `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`**. |
97
+ | `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`**. **`easyspecs-cli --ci auth login`** without argv credentials uses **`easyspecs.auth.ciLogin`** in **`config.json`**. **`--password`** on argv is visible to **`ps`**. |
99
98
  | `auth logout` | — | Deletes the effective session file (same path rules as **`auth login`**). |
100
99
  | `auth status` | — | Reads session file. |
101
100
  | `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. |
102
101
  | `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`**. |
103
- | `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`**. |
104
- | `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. |
105
- | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`EASYSPECS_DUPLICATES_STRICT`**: unless `0`, duplicate/orphan issues fail the exit code. |
102
+ | `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`**. |
103
+ | `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. |
104
+ | `diagnose coordination-duplicates` | Same **`--root`** / **`--worktree`** | **`easyspecs.diagnose.coordinationDuplicates.strict`**: when **`true`** (default), duplicate/orphan issues fail the exit code. |
106
105
  | `diagnose coverage-report` | Same **`--root`** / **`--worktree`** | Uses repo/worktree paths only; no extra env in `main.ts`. |
107
106
  | `diagnose missing-artefacts` | Same **`--root`** / **`--worktree`** | Reads artefact snapshot from workspace state; no OpenCode. |
108
107
  | `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)). |
109
108
  | `upload context` | — | Requires **`auth`** session. Context dir: **`<repoRoot>/.gluecharm/context`**. Project id: **`easyspecs.easyspecsProjectId`** in **`config.json`** only. |
110
- | `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`**. |
109
+ | `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`**. |
111
110
  | `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
112
111
  | `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. |
113
112
  | `ace auto-learn` | Optional **`--worktree <path>`** | **`requireOpenCode`**; checkout = `--worktree` if valid git dir, else **`repoRoot`**. **`merged.pipelineOpenCode.maxConcurrentOpenCodeAgents`** caps parallelism. |
@@ -117,6 +116,6 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
117
116
  ## Notes
118
117
 
119
118
  - 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)).
120
- - **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or legacy **`--ci`** + env).
119
+ - **`upload`** / **`analysis --upload`** require a prior **`auth login`** session (**`--email`** / **`--password`**, or **`--ci`** with **`easyspecs.auth.ciLogin`** in **`config.json`**).
121
120
  - Unknown commands print help and exit with a usage error.
122
121
  - Git subprocesses may set **`GIT_TERMINAL_PROMPT=0`** on the child environment ([`coverageReferenceValidation`](../../src/analysis/coverageReferenceValidation.ts)).