@gluecharm-lab/easyspecs-cli 0.0.9 → 0.0.10
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.
- package/README.md +16 -32
- package/dist/main.cjs +274 -274
- package/dist/main.cjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
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.
|
|
4
4
|
|
|
5
|
-
Published as
|
|
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
10
|
- **[OpenCode](https://opencode.ai)** on `PATH` for flows that run agents
|
|
11
|
-
- A **git repository** with
|
|
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
|
|
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.
|
|
44
44
|
|
|
45
45
|
```bash
|
|
46
46
|
easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
|
|
@@ -54,30 +54,29 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
|
|
|
54
54
|
| **Health** | `doctor` (`--readiness`, `--inspect-config`), `version` |
|
|
55
55
|
| **Config** | `doctor --inspect-config` (inspect merged settings), `config init`, `config set-project-id`, `config set-git-remote` |
|
|
56
56
|
| **Auth** | `auth login --email … --password …`, `auth logout`, `auth status` |
|
|
57
|
-
| **Run synthesis** | `run synthesis`;
|
|
58
|
-
| **Analysis** (full macro pipeline) | `analysis` (optional
|
|
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
59
|
| **Diagnose** | `diagnose reference-coverage`, `coordination-duplicates`, `coverage-report`, … |
|
|
60
60
|
| **Upload** | `upload context`, `upload republish` |
|
|
61
61
|
| **ACE** | `ace clear`, `ace learn`, `ace auto-learn` |
|
|
62
62
|
|
|
63
63
|
|
|
64
|
-
Run
|
|
64
|
+
Run **`easyspecs-cli help`** and **`easyspecs-cli <command> --help`** for the full tree and flags.
|
|
65
65
|
|
|
66
66
|
## Configuration
|
|
67
67
|
|
|
68
|
-
Primary configuration file:
|
|
68
|
+
Primary configuration file: **`<repo>/.easyspecs/config.json`** (auto-created when needed). **`auth login --email … --password …`** stores tokens for upload commands (optional **`--session-path`** tail updates **`easyspecs.cliSessionPath`** in **`config.json`**).
|
|
69
69
|
|
|
70
|
-
After
|
|
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
71
|
|
|
72
72
|
## Global flags
|
|
73
73
|
|
|
74
|
-
`--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`,
|
|
74
|
+
`--cwd`, `--ci`, `--json`, `--verbose`, `--api-base-url`, **`--session-path`**, `--environment`, `--promote` / `--no-promote` (see **`--help`**).
|
|
75
75
|
|
|
76
76
|
## Website & documentation
|
|
77
77
|
|
|
78
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
|
-
- **
|
|
80
|
-
- **CLI:** run `**easyspecs-cli help`** for the full command tree.
|
|
79
|
+
- **CLI:** run **`easyspecs-cli help`** for the full command tree.
|
|
81
80
|
|
|
82
81
|
Engineering source for this CLI is maintained privately; use **easyspecs.ai** and the docs bundled here for support and usage.
|
|
83
82
|
|
|
@@ -85,12 +84,9 @@ Engineering source for this CLI is maintained privately; use **easyspecs.ai** an
|
|
|
85
84
|
|
|
86
85
|
Copyright © **Spaii Edutainment SL** (Barcelona, Spain).
|
|
87
86
|
|
|
88
|
-
This package is licensed under the **Elastic License 2.0** (**ELv2**, SPDX
|
|
87
|
+
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
88
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
```markdown
|
|
93
|
-
# EasySpecs CLI — commands, flags, and configuration
|
|
89
|
+
## Commands, flags, and configuration
|
|
94
90
|
|
|
95
91
|
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
92
|
|
|
@@ -128,7 +124,7 @@ These flags may appear **before** the subcommand. Anything after the first non-f
|
|
|
128
124
|
|
|
129
125
|
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
126
|
|
|
131
|
-
Merge uses **this file + global CLI flags only** — no `EASYSPECS_
|
|
127
|
+
Merge uses **this file + global CLI flags only** — no `EASYSPECS_*` / `VITE_*` product overrides on **`easyspecs-cli`** (**R34**).
|
|
132
128
|
|
|
133
129
|
| Path | Purpose |
|
|
134
130
|
|------|---------|
|
|
@@ -139,13 +135,13 @@ Merge uses **this file + global CLI flags only** — no `EASYSPECS_`* / `VITE_*`
|
|
|
139
135
|
| `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
136
|
| `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
137
|
| `easyspecs.openCode` | `executable`, `skipCredentialsCheck` (legacy shortcut; see also `openCodeRuntime`). |
|
|
142
|
-
| `easyspecs.analysis
|
|
138
|
+
| `easyspecs.analysis.*` | Pipeline: argv template, timeouts, repair attempts, concurrency, `promoteContextToWorkspace`. |
|
|
143
139
|
| `easyspecs.orchestration.*` | Macro delays, outer iterations, ping-pong cap, etc. |
|
|
144
140
|
| `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
141
|
|
|
146
142
|
### Resolved System Manager URL (`easyspecs-cli`)
|
|
147
143
|
|
|
148
|
-
**Order:** `--api-base-url` → non-empty `easyspecs.apiBaseUrl` → built-in URL from effective environment (
|
|
144
|
+
**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**).
|
|
149
145
|
|
|
150
146
|
Built-in defaults ship in [`src/easyspecsBuiltInApiUrls.ts`](../../src/easyspecsBuiltInApiUrls.ts).
|
|
151
147
|
|
|
@@ -187,7 +183,7 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
|
|
|
187
183
|
| `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
184
|
| `config set-project-id <id>` | — | Writes **`easyspecs.easyspecsProjectId`** to **`config.json`**, replacing any previous value. Creates **`config.json`** (defaults + legacy import) if missing. |
|
|
189
185
|
| `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_
|
|
186
|
+
| `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
187
|
| `auth logout` | — | Deletes the effective session file (same path rules as **`auth login`**). |
|
|
192
188
|
| `auth status` | — | Reads session file. |
|
|
193
189
|
| `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. |
|
|
@@ -203,15 +199,3 @@ Each row lists **command-specific CLI tokens**, then **what configuration applie
|
|
|
203
199
|
| `ace clear` | — | Deletes **`<repoRoot>/.gluecharm/context/learnings`**. |
|
|
204
200
|
| `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
201
|
| `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)).
|
|
215
|
-
|
|
216
|
-
```
|
|
217
|
-
|