@gluecharm-lab/easyspecs-cli 0.0.3 → 0.0.7

package/LICENSE

@@ -0,0 +1,95 @@
+Copyright (c) Spaii Edutainment SL, Barcelona, Spain. All rights reserved.
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+Definitions
+
+The licensor is the entity offering these terms, and the software is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+you refers to the individual or entity agreeing to these terms.
+
+your company is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. control means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+your licenses are all the licenses granted to you for the software under
+these terms.
+
+use means anything you do with the software requiring one of your licenses.
+
+trademark means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,86 @@
+# EasySpecs CLI
+
+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`**.
+
+## 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  
+
+## Install
+
+```bash
+npm install -g @gluecharm-lab/easyspecs-cli
+```
+
+Check:
+
+```bash
+easyspecs-cli version
+easyspecs-cli help
+```
+
+Run without a global install:
+
+```bash
+npx @gluecharm-lab/easyspecs-cli@latest help
+```
+
+**Uninstall:** `npm uninstall -g @gluecharm-lab/easyspecs-cli`
+
+## Quick start
+
+```bash
+cd /your/repo
+easyspecs-cli doctor
+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.
+
+```bash
+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.
+
+## 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`**).
+
+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`**).
+
+## Source & documentation
+
+Built from the **easyspecs.ai-vsc-extension** monorepo:
+
+- **Repository:** [gitlab.com/…/easyspecs.ai-vsc-extension](https://gitlab.com/glue-charm-extended/gluecharm-extended/easyspecs.ai-vsc-extension) — directory **`packages/cli`**
+- **Command reference (flags, env, merge rules):** [`commands.md`](./commands.md) in this package  
+- **Further guides** (install variants, CI examples, exit codes): browse **`.gluecharm/docs/`** on the default branch in the repository above.
+
+## License
+
+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.

package/commands.md

@@ -0,0 +1,122 @@
+# 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)).