@currents/cmd 1.11.0 → 2.0.0
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 +45 -11
- package/dist/bin/index.js +58 -89
- package/dist/index.js +8 -9
- package/dist/services/upload/discovery/jest/reporter.js +1 -1
- package/dist/skills/currents-cli/SKILL.md +126 -0
- package/dist/skills/currents-cli/references/ci-setup.md +147 -0
- package/dist/skills/currents-cli/references/sessions.md +74 -0
- package/package.json +10 -5
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Sessions
|
|
2
|
+
|
|
3
|
+
A session holds the files of an ad-hoc, one-off agent or browser session, such as screenshots, a Playwright MCP trace and logs, and gives a link to share them. Use it as evidence: a bug before and after a fix, or proof that something works.
|
|
4
|
+
|
|
5
|
+
The session commands need an API key with write access, in `CURRENTS_API_KEY` or `--api-key`.
|
|
6
|
+
|
|
7
|
+
## Flow
|
|
8
|
+
|
|
9
|
+
These are the commands from `currents session --help`:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
currents session start --api-key <api-key> --project-id <id> --title "Checkout fails on empty cart" --status failed
|
|
13
|
+
currents session attach before.png .playwright-mcp/traces
|
|
14
|
+
currents session share --expires-in-days 7
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
### 1. Start
|
|
18
|
+
|
|
19
|
+
`session start` creates the session and saves its ID to `.currents-session/session.json` in the current folder. It also writes `.currents-session/.gitignore`, so git ignores the folder.
|
|
20
|
+
|
|
21
|
+
- `--title` is required. Say what the session shows.
|
|
22
|
+
- `--status` is `passed` (the default) or `failed`. Add `--error` with what went wrong for a failed session.
|
|
23
|
+
- `--pr` takes the URL or the number of the pull request. Without it, the pull request comes from the CI environment, if there is one.
|
|
24
|
+
- The commit and branch come from the git repository in the current folder. Outside a repository the session has none.
|
|
25
|
+
|
|
26
|
+
`attach` and `share` use the saved session. Run them in the same folder, or pass `--session-id` (or set `CURRENTS_SESSION_ID`). A new `session start` replaces the saved session, so share a session before you start the next one.
|
|
27
|
+
|
|
28
|
+
### 2. Attach
|
|
29
|
+
|
|
30
|
+
`session attach` takes files and folders:
|
|
31
|
+
|
|
32
|
+
- A file is uploaded as it is. Its type comes from its name: `.png`, `.jpg`, `.jpeg`, `.webp` and `.gif` are screenshots, `.webm` and `.mp4` are videos, and a `.zip` that holds `trace.trace` is a trace. Anything else is an attachment. `--type` sets the type.
|
|
33
|
+
- A folder that holds `trace-*.trace` files is packed into one trace zip, and nothing else in it is attached. A folder with a `traces/` subfolder that holds them adds the packed trace and its own files. This is how the Playwright MCP output folder is attached.
|
|
34
|
+
- Of any other folder, only the files directly in it are attached. Hidden files, links, subfolders and empty files are skipped, with a warning.
|
|
35
|
+
- A file named `.env` or `.env.*` is refused, and the command fails. So is an empty file named on the command line, and a file larger than 1 GiB.
|
|
36
|
+
- `--caption` adds a short description to each file, and `--meta key=value` adds a label (repeat it for more labels).
|
|
37
|
+
|
|
38
|
+
What to attach:
|
|
39
|
+
|
|
40
|
+
- a screenshot of the state you want to show;
|
|
41
|
+
- the Playwright MCP trace folder (`.playwright-mcp/traces` unless the server runs with `--output-dir`). Empty it before each capture: `attach` packs every trace in it;
|
|
42
|
+
- the accessibility snapshot of the page, saved as a text file;
|
|
43
|
+
- console or server logs, if they show the problem.
|
|
44
|
+
|
|
45
|
+
Do not attach files with keys, passwords or data of real users. Anyone with the share link can open the files.
|
|
46
|
+
|
|
47
|
+
### 3. Share
|
|
48
|
+
|
|
49
|
+
`session share` creates a public link to the session page. `--expires-in-days` takes `1`, `3` or `7`, and is `7` by default.
|
|
50
|
+
|
|
51
|
+
A person opens the page. An agent reads the Markdown version, which says what the page did and what failed:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
curl -sL "<markdown url>"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## What each command prints
|
|
58
|
+
|
|
59
|
+
| Command | Output on stdout |
|
|
60
|
+
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
61
|
+
| `session start` | `Session started: <session-id>` |
|
|
62
|
+
| `session start --json` | `{"sessionId":"<session-id>"}` only; other messages go to stderr |
|
|
63
|
+
| `session attach` | `Attached <file> (<type>)` for each file, and `Failed <file>: <reason>` on stderr for each file that failed |
|
|
64
|
+
| `session share` | the page URL on the first line, then `Markdown: <markdown url>` |
|
|
65
|
+
|
|
66
|
+
- `session attach` and `session share` have no `--json`. To use the links in a script, read the first line of `session share` for the page URL, and the line that starts with `Markdown: ` for the Markdown URL.
|
|
67
|
+
|
|
68
|
+
## Errors
|
|
69
|
+
|
|
70
|
+
- `No session found`: `session start` did not run in this folder. Run it here, or pass `--session-id`.
|
|
71
|
+
- 401 or 403 from `session start`: `CURRENTS_API_KEY` is missing, or the key has no write access.
|
|
72
|
+
- 404 from `session start`: the project ID does not belong to the organization of the key.
|
|
73
|
+
- 403 from `session share`: the organization turned public sharing off. Report the files you have without a link.
|
|
74
|
+
- `<n> of <m> files could not be uploaded`: the other files were attached. Attach only the failed files again.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@currents/cmd",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
4
|
"main": "./dist/index.js",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Currents Software Inc",
|
|
@@ -12,6 +12,9 @@
|
|
|
12
12
|
"url": "https://github.com/currents-dev/currents-reporter"
|
|
13
13
|
},
|
|
14
14
|
"description": "Currents CLI tools",
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=20"
|
|
17
|
+
},
|
|
15
18
|
"scripts": {
|
|
16
19
|
"test": "vitest",
|
|
17
20
|
"rm": "rimraf dist",
|
|
@@ -48,14 +51,14 @@
|
|
|
48
51
|
"vitest": "^4.1.0"
|
|
49
52
|
},
|
|
50
53
|
"dependencies": {
|
|
51
|
-
"@commander-js/extra-typings": "^
|
|
52
|
-
"@currents/commit-info": "
|
|
54
|
+
"@commander-js/extra-typings": "^14.0.0",
|
|
55
|
+
"@currents/commit-info": "2.0.0",
|
|
53
56
|
"archiver": "^7.0.1",
|
|
54
57
|
"async-retry": "^1.3.3",
|
|
55
58
|
"axios": "1.18.1",
|
|
56
59
|
"axios-retry": "4.5.0",
|
|
57
60
|
"chalk": "^4.1.2",
|
|
58
|
-
"commander": "^
|
|
61
|
+
"commander": "^14.0.0",
|
|
59
62
|
"debug": "^4.4.0",
|
|
60
63
|
"dotenv": "^17.4.2",
|
|
61
64
|
"execa": "^9.5.1",
|
|
@@ -119,7 +122,9 @@
|
|
|
119
122
|
},
|
|
120
123
|
"plugins": {
|
|
121
124
|
"@release-it/conventional-changelog": {
|
|
122
|
-
"preset":
|
|
125
|
+
"preset": {
|
|
126
|
+
"name": "conventionalcommits"
|
|
127
|
+
},
|
|
123
128
|
"header": "# Changelog",
|
|
124
129
|
"ignoreVersion": true,
|
|
125
130
|
"infile": "./CHANGELOG.md"
|