@gluecharm-lab/easyspecs-cli 0.0.15 → 0.0.16
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 +25 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,21 @@
|
|
|
1
1
|
# EasySpecs CLI
|
|
2
2
|
|
|
3
|
-
Headless **EasySpecs** command-line tool
|
|
3
|
+
Headless **EasySpecs** command-line tool: same orchestration ideas as the **EasySpecs VS Code extension**, without an editor. **`easyspecs-cli help`** is organized around three **factory-level** jobs on **application context**; the rest of the commands and flags exist to tune **where** the work runs (**`--cwd`**, **`--worktree`**, **`--root`**), **how** it behaves (**`--ci`**, **`--json`**, **OpenCode** and **`config.json`** settings), optional **cloud sync**, and **step-level** escapes (partial pipelines, resumes, deterministic checks).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## The three factory-level commands
|
|
6
|
+
|
|
7
|
+
1. **`easyspecs-cli analysis` — create new context**
|
|
8
|
+
Runs the full **Generate Context** factory end to end (synthesis until stable, coverage, remediation, reporting, link mapping, index assembly). Use this when you need a fresh or full rebuild of **`.gluecharm/context`** from the repo. Optional **`--upload`** pushes resulting context to EasySpecs after **`auth login`** and **`config set-project-id`**. **`--synthesis-only`** stops after synthesis; **`--force-new-context-analysis`** overrides skip-when-already-analyzed behavior when the factory would otherwise exit early.
|
|
9
|
+
|
|
10
|
+
2. **`easyspecs-cli update context` — update context from code churn**
|
|
11
|
+
Incremental refresh from a **git delta** since the stored baseline (**`easyspecs.factory.updateContext.lastRunAt`**) or, when that is absent, inferred from workspace context mtimes: materialises **`changes-since-date.md`**, runs **scoped** remediation when commits and touched paths warrant it, then optional promotion and **`--upload`**. Use this day to day after **`analysis`** when the codebase moved but specs did not restart from zero.
|
|
12
|
+
|
|
13
|
+
3. **`easyspecs-cli context drift <referencePath>` — analyze drift against specs**
|
|
14
|
+
**`referencePath`** is a **file or directory** of truth documents (requirements, specs, PRD, architecture notes — whatever your team treats as ground truth relative to repo root). The CLI compares **repository / analysis worktree** context against that reference (OpenCode-assisted), writes **`drift-<label>-<date>.md`** under **`.gluecharm/context/drift/`**, and can update the reference index markdown. **`--label <slug>`** names the report file; **`--index <path>`** overrides which root markdown anchors the comparison; **`--dry-run`** validates references only (**no worktree, agent, or writes**).
|
|
15
|
+
|
|
16
|
+
**Supporting commands (not substitutes for those three goals):** **`auth`** and **`config`** wire API access and **`easyspecs.easyspecsProjectId`**; **`download context`** / **`upload context`** / **`upload republish`** move artefacts between disk and EasySpecs; **`doctor`** checks readiness and redacted merged settings; **`diagnose`** and **`context link-graph`** are deterministic gates and link maintenance; **`run synthesis`** and **`run synthesis resume-*`** run single stages or catch-up without the full factory; **`ace *`** manages optional learnings under **`.gluecharm/context/learnings`**.
|
|
17
|
+
|
|
18
|
+
**Vocabulary:** A **Factory** is the full ordered **`analysis`** run. A **Pipeline** is one major stage inside it (synthesis, coverage, remediation, link mapping, upload, download). A **Workstation** is one atomic OpenCode or programmatic step inside a pipeline. Canonical **`config.json`** keys live under **`easyspecs.factory.*`**, **`easyspecs.workstations.*`**, and **`easyspecs.pipelines.upload.*`**; legacy **`easyspecs.orchestration.*`**, **`easyspecs.macro.debug`**, and several **`easyspecs.analysis.*`** tunables still work for one deprecation cycle and may log **`[deprecated-setting]`** on stderr when read. Human stderr may tag lines **`[factory]`**, **`[pipeline:…]`**, **`[workstation:…]`**, **`[pool]`**, **`[ace]`**.
|
|
6
19
|
|
|
7
20
|
Published as **`@gluecharm-lab/easyspecs-cli`** (npm org **gluecharm-lab**; **EasySpecs** is the product). The executable on your `PATH` is **`easyspecs-cli`**.
|
|
8
21
|
|
|
@@ -34,7 +47,7 @@ npx @gluecharm-lab/easyspecs-cli@latest help
|
|
|
34
47
|
|
|
35
48
|
## Quick start
|
|
36
49
|
|
|
37
|
-
From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for
|
|
50
|
+
From a git repo (**OpenCode** on **`PATH`** for agent steps). The CLI creates minimal **`.gluecharm/`** directories when needed for **`analysis`**, **`update context`**, **diagnose**, **upload**, and **`download context`**:
|
|
38
51
|
|
|
39
52
|
```bash
|
|
40
53
|
cd /your/repo
|
|
@@ -43,7 +56,7 @@ easyspecs-cli config init
|
|
|
43
56
|
easyspecs-cli analysis
|
|
44
57
|
```
|
|
45
58
|
|
|
46
|
-
**`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). **`analysis`**
|
|
59
|
+
**`config init`** creates **`.easyspecs/config.json`** with defaults (add **`--overwrite`** to replace an existing file). After the first **`analysis`**, typical follow-ups are **`update context`** (incremental sync with git) and **`context drift`** when you hold truth in specs files/folders elsewhere in the repo. Use **`download context`** (**`auth login`** + **`config set-project-id`**) to pull stored context from EasySpecs into **`.gluecharm/context`**. Append **`analysis --upload`** or **`update context --upload`** to sync edits back after login + project id. Use **`--ci`** in automation for non-interactive behaviour and stricter defaults (e.g. Factory outer-iteration cap).
|
|
47
60
|
|
|
48
61
|
Set **`easyspecs.defaultGitRemoteUrl`** with **`config set-git-remote <url>`** when you want that recorded in config. Tunables belong in **`<repo>/.easyspecs/config.json`** — do not rely on **`EASYSPECS_*`** environment variables for product settings.
|
|
49
62
|
|
|
@@ -57,11 +70,11 @@ easyspecs-cli diagnose coordination-duplicates --cwd /your/repo --ci --json
|
|
|
57
70
|
|
|
58
71
|
## Download context (pull from EasySpecs)
|
|
59
72
|
|
|
60
|
-
Use this when you want
|
|
73
|
+
Use this when you want **application context** already stored for the EasySpecs **project** written into **`<repo>/.gluecharm/context`** (after a clone, environment switch, or to match cloud contents).
|
|
61
74
|
|
|
62
75
|
**Prerequisites:** same as **`upload context`**: a prior **`auth login`**, and **`easyspecs.easyspecsProjectId`** set (e.g. **`easyspecs-cli config set-project-id <uuid>`**). The CLI creates minimal **`.gluecharm/`** layout when needed, including **`.gluecharm/context`**.
|
|
63
76
|
|
|
64
|
-
**Behaviour:** the CLI **GET**s the application, reads linked
|
|
77
|
+
**Behaviour:** the CLI **GET**s the application, reads linked identifiers for persisted context fragments, batches a content **GET**, and writes one UTF‑8 file per row under **`<repo>/.gluecharm/context`**, using each row’s **`name`** as a safe relative path (path traversal is rejected). Rows named **`easyspecs-upload-target.json`** are skipped. When files are written, ids are merged into **`index-application-context.json`** the same way as after upload, if that index file exists.
|
|
65
78
|
|
|
66
79
|
```bash
|
|
67
80
|
cd /your/repo
|
|
@@ -245,15 +258,16 @@ Every command the CLI accepts, with command-specific tokens. Global flags above
|
|
|
245
258
|
| `run synthesis` | — | Context artefact pipeline pass; **`requireOpenCode`** applies. **`--promote` / `--no-promote`** affect promotion after success. |
|
|
246
259
|
| `run synthesis resume-missing` | **`--worktree <path>`** (optional) | Parallel missing-artefact remediation pool on an existing checkout (from **`--worktree`** or last snapshot). **`requireOpenCode`**. |
|
|
247
260
|
| `run synthesis resume-synthesis` | **`--worktree <path>`** (optional) | Same implementation as **`resume-missing`** (alias command path). |
|
|
248
|
-
| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only
|
|
249
|
-
| `update context` | **`--upload`** (optional; any order in tail) | **
|
|
261
|
+
| `analysis` | **`--synthesis-only`**, **`--upload`**, **`--skip-upload`**, **`--force-new-context-analysis`** (any order among argv tokens after **`analysis`**) | Full **Generate Context** factory unless **`--synthesis-only`** — **create new context** trajectory. **`--upload`** runs backend sync after the factory (needs **`auth login`** + **`easyspecs.easyspecsProjectId`**). Without **`--upload`**, backend sync is skipped. **`--skip-upload`** appears in **`easyspecs-cli help`**; omit **`--upload`** to skip upload. If **`easyspecs.factory.cloudContextAnalyzed`** is **`true`** (legacy **`easyspecs.analysis.cloudContextAnalyzed`**) and neither **`--synthesis-only`** nor **`--force-new-context-analysis`** is set, exits **0** early with **`analysisSkipped`** (machine JSON fields). |
|
|
262
|
+
| `update context` | **`--upload`** (optional; any order in tail) | **Update context** trajectory: git window after baseline → worktree → **`changes-since-date.md`** → optional remediation → **`--promote` / `--no-promote`** → optional **`--upload`** (mtime-scoped files) → **`easyspecs.factory.updateContext.lastRunAt`**. Seed context should exist on **HEAD** in the checkout (the factory may copy from workspace when the worktree lacks context). |
|
|
250
263
|
| `diagnose reference-coverage` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Reference coverage gate; optional percent limit via **`easyspecs.diagnose.zeroReference.maxPercentNonReferenced`**. |
|
|
251
264
|
| `diagnose coordination-duplicates` | same | Duplicate/orphan reporting; **`easyspecs.diagnose.coordinationDuplicates.strict`**. |
|
|
252
265
|
| `diagnose coverage-report` | same | Writes coverage execution report path. |
|
|
253
266
|
| `diagnose missing-artefacts` | same | Lists missing artefacts from workspace state (JSON on stdout in human mode). |
|
|
254
|
-
| `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). After a successful pool run, applies
|
|
255
|
-
| `context link-graph` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** |
|
|
256
|
-
| `
|
|
267
|
+
| `diagnose zero-reference` | **`--worktree <path>`** (optional; no **`--root`** branch) | Zero-reference remediation pool (**OpenCode**). After a successful pool run, applies context markdown navigation links under the analysis checkout context directory (fails the command if that step reports broken links). |
|
|
268
|
+
| `context link-graph` | **`--root workspace`** \| **`--root worktree`**, optional **`--worktree <path>`** | Refreshes EasySpecs navigation marker blocks in **`.gluecharm/context/**/*.md`** from coordination JSON only (no agents). **`--json`** may include **`contextDir`**, **`error`**, **`brokenLinks`**. |
|
|
269
|
+
| `context drift <referencePath>` | **`--label <slug>`**, **`--index <path>`**, **`--dry-run`**; **`--root` / `--worktree`** tail tokens are accepted and ignored for current routing | **Analyze drift against specs** trajectory: **`referencePath`** = file or directory of reference docs. Uses analysis worktree + OpenCode drift agent → **`.gluecharm/context/drift/drift-<slug>-<date>.md`** and reference index maintenance; global **`--promote` / `--no-promote`** apply when not **`--dry-run`**. Success stdout: drift report path. |
|
|
270
|
+
| `download context` | **`--force`**, **`--replace-from-cloud`** (optional; any order after **`download context`**) | Requires **`auth login`** session + **`easyspecs.easyspecsProjectId`**. Resolves linked context documents from **`GET /api/content/application/:id`**, batch-fetches content, writes UTF-8 files under **`<repo>/.gluecharm/context`**. Default skips existing paths; **`--force`** overwrites; **`--replace-from-cloud`** wipes local context files first (preserves root **`easyspecs-upload-target.json`**). **`--json`**: **`downloaded`**, **`skipped`**, **`failed`**, **`localRemoved`**. Non-zero exit if **`failed` > 0`. Full narrative under **Download context (pull from EasySpecs)** above. |
|
|
257
271
|
| `upload context` | — | Requires auth session + **`easyspecs.easyspecsProjectId`**. Context dir: **`<repo>/.gluecharm/context`**. Optional cloud status GET per **`easyspecs.upload.fetchContextAnalyzedInCloud`**. |
|
|
258
272
|
| `upload republish` | — | Same auth + project id; context dir from **`easyspecs.upload.contextDirectory`** or analysis worktree snapshot. Same optional cloud status behaviour as **`upload context`**. |
|
|
259
273
|
| `ace clear` | — | Deletes learnings under **`.gluecharm/context/learnings`**. |
|
package/package.json
CHANGED