@mechasm/cli 0.1.3 → 0.1.5

package/AGENT_GUIDE.md

@@ -2,8 +2,20 @@
 
 Use Node.js 22 or newer. Install `@mechasm/cli`, sign in with `mechasm login`, then check `mechasm doctor`.
 
+When signing in again with a valid session and the same account, review the preselected project and team approvals before approving.
+
 Keep each test request in Markdown. Name the project ID, target URL, expected result, and limits. Reuse configured test accounts; do not ask agents to expose credentials or change data outside the named test scope.
 
+Before creating a test, list the project's existing tests and inspect likely matches. If the target and requirements match, run the existing test and inspect the new run. An app change alone does not require a new test. Edit a test when its requirements change; create one only for missing coverage. Never reuse an old result as verification of a new app version.
+
+```sh
+mechasm tests list --project PROJECT_ID --json
+mechasm tests get TEST_ID --project PROJECT_ID --json
+mechasm tests run TEST_ID --project PROJECT_ID --json
+```
+
+For missing coverage:
+
 ```sh
 mechasm tests create --project PROJECT_ID --name "Sign-in" --prompt-file prompt.md --json
 ```
@@ -22,8 +34,21 @@ mechasm runs status RUN_ID --project PROJECT_ID --json
 
 Log streaming alone does not report pass/fail through its exit code. Do not infer success from a closed stream or an individual log line. For scripts that only need the final result, `--wait` on create/edit/run or `runs wait` waits silently and returns the final result without displaying live logs. With `--json`, it returns one final JSON result.
 
+Let Mechasm's healer work while the run is active. Failed actions, unexpected pages and recovery attempts can be corrected automatically. Wait for the overall run to reach `passed` or `failed`; do not cancel because a few minutes passed or one step failed. Stop when the user requests it, or when you deliberately need to change the prompt before continuing. `runs status` includes `terminal`, the current `progress` phase/start time when available, and safe failure details with a suggested next step. Missing progress is not proof the run is stuck.
+
+Before reporting the outcome, review the logs and available evidence against the user's intended result:
+
+```sh
+mechasm runs trace RUN_ID --project PROJECT_ID --out run-trace.zip
+mechasm runs video RUN_ID --project PROJECT_ID --out run.webm
+```
+
+Check artifact availability in `runs status`; uploads can finish after the run result. Inspect trace screenshots/page snapshots, actions and errors, using video as supporting evidence. Verify that the expected behavior really happened; do not treat an existing file as proof of success. If evidence is unavailable or cannot be opened, report that limit.
+
+If evidence shows a genuine failure of the user's requirement, accept and report the failure. If your prompt introduced an unsupported assumption or was ambiguous, clarify it without weakening the user's requirement, then use `tests edit --prompt-file FILE` and inspect the new run. Ask the user if their intended result is unclear. Do not repeatedly rerun or remove assertions just to get a pass. A manually stopped run proves cancellation, not what the natural result would have been.
+
 Use explicit project, test, and run IDs. Do not assume a default project. Use `--json` for scripts; stdout contains JSON and errors go to stderr. Log following emits JSON lines. Save run IDs and log cursors in workflow state. Resume logs with `--after CURSOR` after reconnecting.
 
 Exit code `5` from a status/get/wait command or a test command using `--wait` means the run failed or was stopped. Code `2` means invalid arguments, `3` authentication failed, and `4` permission was denied. The optional npm update notice runs only in interactive non-JSON sessions; CI skips it.
 
-See [CLI documentation](https://mechasm.ai/docs/mechasm-cli/getting-started) for full command details.
+See [CLI documentation](https://mechasm.ai/docs/mechasm-cli/getting-started) and [agent workflows](https://mechasm.ai/docs/mechasm-cli/agent-workflows) for full command details.

package/README.md

@@ -31,6 +31,8 @@ mechasm projects list
 
 Approve the existing projects and actions this device needs. Project access and permission to create projects in a team are separate. Team project-creation access does not grant access to existing projects in that team. If a project or team is missing, sign in again and approve access; your account must already have access to it.
 
+When signing in again with a valid session and the same account, your previous approvals are preselected. Review them before approving. If your session has expired or was revoked, select access again.
+
 Pass project IDs explicitly to test, run, variable, and local-app commands. The CLI does not select a default project.
 
 ## Create a project and run a test
@@ -43,6 +45,8 @@ mechasm tests create --project PROJECT_ID --name "Home page" --prompt "Open the
 
 Replace `TEAM_ID`, `PROJECT_ID`, and the example URL with your values. `--team` is optional when exactly one team is approved. The project creation response contains the project ID to use in later commands.
 
+For later app changes, inspect existing tests and run matching ones with `mechasm tests run TEST_ID --project PROJECT_ID`. Edit tests when requirements change; create tests only for missing coverage. Always inspect the new run's result. See the bundled [Agent Guide](./AGENT_GUIDE.md) for the full workflow.
+
 Commands that start a run return its `runId` and workspace `runUrl`. Use the returned run ID to follow execution:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechasm/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Mechasm command line client",
   "homepage": "https://mechasm.ai/docs/mechasm-cli/getting-started",
   "license": "SEE LICENSE IN LICENSE",

package/src/api-client.js

@@ -228,7 +228,19 @@ export function createCliClient(rawApiUrl) {
     async login({ deviceName = hostname().slice(0, 120), noBrowser = false, json = false } = {}) {
       deviceName = String(deviceName).trim();
       if (!deviceName || deviceName.length > 120) throw new CliError('--device-name must be 1 to 120 characters.', 2);
-      const device = (await request('/auth/device', { method: 'POST', body: { deviceName } })).data;
+      let previousToken;
+      try {
+        if (await readCredentials(path)) previousToken = (await accessToken()).token;
+      } catch (error) {
+        if (error.exitCode !== 3) throw error;
+      }
+      let device;
+      try {
+        device = (await request('/auth/device', { method: 'POST', body: { deviceName }, token: previousToken })).data;
+      } catch (error) {
+        if (!previousToken || error.exitCode !== 3) throw error;
+        device = (await request('/auth/device', { method: 'POST', body: { deviceName } })).data;
+      }
       if (typeof device?.deviceCode !== 'string' || !/^mcd_[A-Za-z0-9_-]{43}$/.test(device.deviceCode) ||
           typeof device?.userCode !== 'string' || !device.userCode || typeof device?.verificationUrl !== 'string' ||
           !Number.isInteger(device.expiresIn) || device.expiresIn < 1 || device.expiresIn > 1800) {

package/src/cli.js

@@ -181,7 +181,10 @@ function output(value, json) {
     console.log(`Signed in${identity ? ` as ${identity}` : ''}${value.deviceName ? ` (${value.deviceName})` : ''}.`);
   }
   else if (Array.isArray(value?.projects)) {
-    if (!value.projects.length) console.log('No projects available.');
+    if (!value.projects.length) {
+      console.log(value.message || 'No projects available to this device.');
+      if (value.suggestedNextStep) console.log(value.suggestedNextStep);
+    }
     else for (const project of value.projects) console.log(`${project.id}  ${project.name}  ${project.url}`);
   } else if (Array.isArray(value?.tests)) {
     if (!value.tests.length) console.log('No tests found.');