@seeed-studio/solution-cli 0.0.0-stage → 0.1.0

package/skills/sensecraft/references/diagnose.md

@@ -0,0 +1,133 @@
+# Diagnose a failed or misbehaving deployment
+
+Follow the rules in `SKILL.md` (what needs the user's OK, at most 3 rounds).
+If the user runs the desktop app and deployed from it, `app-only.md` §3 covers
+the app's own deployment list and logs.
+
+## 1. Find the deployment
+
+If you started it, you already have the `deployment_id`. Otherwise:
+
+```
+sensecraft-engine api GET "/api/deployments?limit=20"   # newest first: id, solution_id, status
+```
+
+## 2. Collect evidence
+
+Start with the status. **The real error is usually in the failing step's
+`message`** (`devices[].steps[]` with `status: failed`); top-level errors may
+only say "Device X deployment failed".
+
+```
+sensecraft-engine status <deployment_id> --json
+sensecraft-engine api GET /api/deployments/<deployment_id>/summary
+```
+
+Then the error-level events, and the full log of the failing device:
+
+```
+sensecraft-engine logs <deployment_id>                 # NDJSON; look at type=log, level=error
+sensecraft-engine api GET "/api/deployments/<deployment_id>/logs?device_id=<device_id>&limit=300"
+```
+
+If the logs are empty or end abruptly (status `interrupted`: the engine
+instance stopped during the deployment), read the engine log
+`~/.sensecraft/logs/engine.log` (Windows: `%USERPROFILE%\.sensecraft\logs\engine.log`),
+last ~200 lines. `sensecraft-engine daemon status` prints JSON (`--json` is
+accepted and changes nothing; exit 1 with `"running": false` when no instance
+is running). A running instance shows `busy` (a deployment is running),
+`python_backend` (null: no desktop-app backend involved) and
+`python_supervisor.state`.
+
+Note the failing device, step and the first error — later errors are usually
+consequences of the first.
+
+## 3. Check the device (read-only, no need to ask)
+
+Which containers belong to the solution: in the solution folder
+(`~/.sensecraft/content/solutions/<id>/`) the step's `devices/<x>.yaml` names
+the compose file (`docker.compose_file`) and project
+(`docker.options.project_name`); the compose file may set `container_name`.
+
+Through the engine (no separate SSH client needed):
+
+```
+SC_SSH_PASSWORD=<password> sensecraft-engine docker ps --host <ip> --username <user> --json
+SC_SSH_PASSWORD=<password> sensecraft-engine docker logs <container> --host <ip> --username <user> --tail 100
+# SSH key (engines with --key-file; older engines accept a password only):
+sensecraft-engine docker ps --host <ip> --username <user> --key-file ~/.ssh/id_ed25519 --json
+```
+
+Omit `--host` for this computer's Docker. With an SSH client, the same
+read-only commands as before:
+
+```
+docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
+docker logs --tail 100 <container>
+df -h /
+ss -ltnp            # who holds a port (use: sudo ss -ltnp if names are hidden)
+ping -c 2 8.8.8.8   # internet reachability
+```
+
+For local targets and USB devices also run `sensecraft-engine doctor --json`
+(serial permission, Docker, disk, network) and
+`sensecraft-engine device ports` (is the USB device visible).
+
+## 4. Classify, then act
+
+Match the evidence against `error-catalog.md`. Every problem falls in one of
+three classes:
+
+| Class | Example | What you do |
+|---|---|---|
+| **Device / environment** | port taken, disk full, Docker missing, network blocked, wrong password, serial permission | Propose the exact fix commands → user OK → run them → retry |
+| **Solution configuration** | timeout too short, wrong port/env in compose, health check endpoint 404, minor syntax/transfer glitch | **CLI / Engine mode (Auto-healing patch)**: Copy the solution from `~/.sensecraft/content/solutions/<id>` to `./.sensecraft-work/solutions/<id>`, apply the minimal required fix. Stop the previous engine instance (`sensecraft-engine daemon stop`) so it reloads the new solution directory, and redeploy with `--solutions-dir ./.sensecraft-work/solutions` so the user succeeds immediately! Show the user the patch diff. Desktop app running: fix it in the edit copy (`app-only.md` §4) → validate → apply → retry. |
+| **Engine bug** | exit code 5, a panic in `engine.log`, a step that fails the same way on any device, behaviour contradicting the solution's own config | Stop. Prepare the issue report below |
+
+If the evidence does not fit any row, say so and show the user the first error
+with your best hypothesis and what would confirm it. Do not guess-and-retry.
+
+## 5. Retry
+
+Restart only the failed device (`selected_devices` = that device, see
+`deploy.md` §6). First retry without asking; later ones need the user's OK.
+After 3 rounds without success, stop and report.
+
+## 6. Report
+
+Always finish with: what failed, the evidence (first error line), what you
+changed (commands run, files edited with a diff), and the result.
+
+### Engine bug: issue report
+
+Engine bugs are reported on the public repository
+`suharvest/sensecraft-solutions` with the **App / engine bug** form; the
+maintainers move them on from there. Do not submit it yourself — give the user
+a link to open in the browser and submit with their own GitHub account.
+
+1. Fill these fields (passwords, tokens and IP addresses removed):
+
+   | Field id | Content |
+   |---|---|
+   | `title` | `[engine] <step type> fails: <first error, one line>` |
+   | `app_version` | `engine <version>` from `sensecraft-engine --version` (or the app's version when deployed from the app) |
+   | `os` | this computer's OS and version |
+   | `device` | target device model, OS, CPU architecture (or "this computer (local Docker)") |
+   | `solution` | `<solution_id> / <preset_id> / <step id> (<type>)` |
+   | `edited` | `No` or `Yes (diff below)` |
+   | `what_happened` | first error and the 10–20 log lines around it |
+   | `reproduce` | numbered steps (the `sensecraft-engine` commands, password removed) |
+   | `ruled_out` | device checks that passed |
+   | `diff` | the edit copy's diff (`app-only.md` §4.5), only if edited |
+
+2. Build the link, URL-encoding every value:
+
+   ```
+   https://github.com/suharvest/sensecraft-solutions/issues/new?template=engine-bug.yml&title=<...>&app_version=<...>&os=<...>&device=<...>&solution=<...>&edited=<...>&what_happened=<...>&reproduce=<...>&ruled_out=<...>
+   ```
+
+   Keep the link under about 7,000 characters: if the log excerpt or diff is
+   longer, leave those fields out of the link and give the user that text
+   separately to paste into the form.
+3. Show the user the filled fields and the link, and say the report will be
+   public.

package/skills/sensecraft/references/error-catalog.md

@@ -0,0 +1,33 @@
+# Error catalog
+
+Match the **first** error of the failing step. Class: **Env** = device /
+environment, **Config** = solution configuration, **Engine** = engine / app bug.
+
+| Evidence | Class | Cause | Action |
+|---|---|---|---|
+| Exit 3, "no solutions" / hint to run `content pull` | Env | Solutions not downloaded yet | `sensecraft-engine content pull`, then run the command again |
+| Exit 2, `{"type":"error","code":"missing_params","missing":[...]}` | Env | A required value is not in the request | Ask the user for each `missing` field (`preset_id`, `device_connections.<id>.<key>`) |
+| Exit 3, HTTP 409 with `busy: [...]` | Env | Another deployment is using the same device | Wait for it (`status <id>`), or ask the user whether to cancel it |
+| Exit 4, `requires_desktop_app` | Env | This step's deployer is not in the engine | Tell the user to deploy the solution from the SenseCraft Solution app |
+| `key_file` refused (outside `~/.ssh`) | Env | The engine only reads SSH keys inside `~/.ssh` or its data directory | Use a key under `~/.ssh` (copying a key there needs the user's OK) |
+| `the offline package was prepared with different values: ...` | Env | Deploy parameters differ from the ones the offline package was prepared with | Plan / prepare again with the deploy's values (`offline.md`), or deploy with the prepared values |
+| `doctor` serial check: not a member of `dialout`; serial port permission denied | Env | User may not open USB serial ports (Linux) | Propose the `fix` from `doctor` (`sudo usermod -aG dialout <user>`, then log out and in) — user OK |
+| `port_busy` from `counting` / `face` / `wizard` | Env | A deployment or another session holds the serial port | Wait until it finishes; do not force it |
+| `Missing host` / connection fields empty | Env | `host` not given in `device_connections` | Ask the user for the device IP, redeploy |
+| SSH `Authentication failed` / `Permission denied (publickey,password)` | Env | Wrong username or password | Ask the user to re-check; the solution's default user is in `request_template` |
+| SSH timeout / `No route to host` | Env | Device off, wrong IP, other network | `ping` it; ask the user to check power and that both are on the same LAN |
+| `port is already allocated` / `address already in use`; pre-check `port_available` failed | Env | Another process or container holds the port | `ss -ltnp` / `docker ps` to find it; propose stopping it (user OK), or change the port in config |
+| `Conflict. The container name ... is already in use` | Env | Leftover container from an earlier deployment | Redeploy with `"auto_replace_containers": true` after the user agrees |
+| `no space left on device`; pre-check `disk_space` failed | Env | Disk full | `df -h`, `docker system df`; propose `docker image prune` (user OK) |
+| `docker: command not found`; pre-check `docker_version` failed | Env | Docker not installed / too old | Tell the user; installing needs their OK |
+| `permission denied while trying to connect to the Docker daemon socket` | Env | User not in `docker` group | Propose `sudo usermod -aG docker <user>` then re-login (user OK) |
+| Image pull: `TLS handshake timeout`, `i/o timeout`, `toomanyrequests` | Env | Registry unreachable or rate-limited | Look for `Mirror context resolved` in the logs: absent → mirror detection failed; retry once, then report network status to the user |
+| `manifest unknown` / `not found` for an image | Config | Image name or tag wrong, or not built for the device's CPU (arm64 vs amd64) | `docker manifest inspect <image>` (read-only): "no such manifest" → the tag does not exist, fix it; it exists but lists no platform matching the device's `uname -m` → wrong architecture, pick an image built for it |
+| Container `Restarting` / `Exited (1)`; error in `docker logs` | Config (usually) | App inside the container misconfigured: env var, mounted path, port, timeout | Read `docker logs`; CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix compose / env / timeout, and redeploy with `--solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
+| Container `(healthy)` but the step reports health-check failure | Config | `health_check_endpoint` points at a URL that returns 401/404 | Fix the endpoint in the device YAML (`docker.services[].health_check_endpoint`) via local patch copy or app edit copy |
+| Containers up, but the page / port does not answer from another machine | Env | Device firewall | Check `sudo iptables -L -n` / `ufw status`; propose opening the port (user OK) |
+| USB device not detected (`No device found`, `detect` returns nothing) | Env | Cable is charge-only, wrong port, driver missing | Ask the user to replug with a data cable; on Windows check Device Manager for a COM port |
+| YAML / validation error naming a solution file | Config | Broken solution file, syntax typo, or timeout too short | CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix typo/timeout, and redeploy with `--solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
+| Python traceback mentioning `provisioning_station/` | Engine | App bug | Issue report (`diagnose.md` §6) |
+| `sensecraft-engine` exits 5, or a panic in `~/.sensecraft/logs/engine.log` | Engine | Engine bug | Issue report (`diagnose.md` §6) |
+| Same step fails identically on two different devices after the environment checks pass | Engine (likely) | App bug | Issue report (`diagnose.md` §6) |

package/skills/sensecraft/references/offline.md

@@ -0,0 +1,78 @@
+# Deploy where there is no internet (offline package)
+
+Prepare on a computer that has internet, deploy on site without it. The unit
+is **step × target**: you can prepare one step only, or several device models
+for the same step. The engine has no separate command for this; use
+`sensecraft-engine api` (run `sensecraft-engine api --help` for the same notes).
+
+Ask the user first: preparing downloads container images and files, which can
+take several GB of disk space.
+
+## 1. Plan: what is needed, what is already here
+
+Write the request to a file, e.g. `./.sensecraft-work/plan.json`:
+
+```json
+{
+  "solution_id": "<id>",
+  "preset_id": "<preset>",
+  "targets": {"<step_id>": "<target_id>"},
+  "arch": {"<step_id>": "aarch64"},
+  "params": {"username": "<the username the deploy will use>"},
+  "lang": "en"
+}
+```
+
+- `targets`: only the steps listed are prepared; leave it out for every step.
+- `arch`: needed when the target names no device type (`aarch64` for
+  ARM boards such as Jetson, Raspberry Pi, RK3588).
+- `params`: **the same connection values the later deploy will use** (from
+  `deploy-info`'s `request_template`, e.g. `username`). The package records
+  them; a deploy with different values is refused before anything runs on the
+  device (`the offline package was prepared with different values: ...`), and
+  you have to plan and prepare again with the right `params`.
+
+```
+sensecraft-engine api POST /api/staging/plan --data "$(cat ./.sensecraft-work/plan.json)"
+```
+
+The response lists each item and whether it is already here. Items marked
+`partial` still need internet on site (for example a model the container
+downloads at start); tell the user which.
+
+## 2. Prepare: download it here
+
+```
+sensecraft-engine api POST /api/staging/prepare --data "$(cat ./.sensecraft-work/plan.json)"
+sensecraft-engine api GET /api/staging/jobs/<id>      # repeat every 5–10 s until status is not "running"
+```
+
+`prepare` returns a job with `id` and `status: running`. Cancel it with
+`sensecraft-engine api POST /api/staging/jobs/<id>/cancel`.
+
+## 3. Check, carry, clean up
+
+```
+sensecraft-engine api GET /api/staging/entries                                   # what is prepared
+sensecraft-engine api POST /api/staging/export --data '{"path": "/path/kit.tar"}' # pack it
+sensecraft-engine api POST /api/staging/import --data '{"path": "/path/kit.tar"}' # on the deploying computer
+```
+
+Deleting prepared entries (`POST /api/staging/entries/delete`) frees disk space;
+ask the user first.
+
+## 4. Deploy on site
+
+Deploy as in `deploy.md`, with `"force_offline": true` in the step's
+connection:
+
+```json
+"device_connections": {
+  "<step_id>": {"target": "<target_id>", "target_type": "remote",
+                "host": "<ip>", "username": "<same as params>",
+                "password": "<password>", "force_offline": true}
+}
+```
+
+The engine checks the offline package before connecting to the device and
+stops with a list of what is missing.

package/skills/sensecraft/references/verify.md

@@ -0,0 +1,136 @@
+# Finish a `verify_required` step
+
+The engine does not run verification steps that need a person or a browser.
+When a deployment reaches one, it writes a `verify_required` event to the
+deployment's log, marks that step `step_skipped` (`reason: verify_required`)
+and carries on. Read the events with
+`sensecraft-engine logs <deployment_id> --since <N>`.
+
+Fields every `verify_required` event has:
+
+| Field | Content |
+|---|---|
+| `device_id` / `step_id` | The step |
+| `kind` | The step type (`web_dashboard`, `serial_camera`, `serial_wizard`, `robot_inspect`, `preview`, `image_predict`, ...) |
+| `name`, `required` | Display name; whether the solution counts it as required |
+| `url`, `endpoint` | Where to check, with `{{host}}` already filled in (may be null) |
+| `sample_request` | Request to send to `endpoint`: `{method, url, headers?, content_type?, file_field?, body?, curl}`, `curl` being a ready command line (may be null) |
+| `mode` | Steps with several check modes: the mode the event describes (the step's default) |
+| `instructions` | What to check, in the solution's words |
+| `expected_status` | `web_dashboard` only: 200 |
+
+Steps for hardware sessions add `port` / `db_port` / `host` (filled from the
+step that flashed or deployed the device; null when the connection did not
+include it), `commands {...}` with the exact CLI commands, and `confirm`
+(how to tell it worked). `deploy-info` lists the same commands in advance as
+`counting_cli`, `face_cli`, `wizard_cli` or `robot_cli` on that step.
+
+General rules:
+
+- Replace `<PORT>`, `<DB_PORT>`, `<HOST>` in `commands` with the event's `port`,
+  `db_port`, `host`. If one is null, take it from the connection you gave the
+  step named in `port_from_device` / `db_port_from_device` /
+  `host_from_device`, or ask the user (`sensecraft-engine device ports` lists
+  serial ports).
+- Anything a person must do with their hands — plugging a cable, connecting a
+  servo, sitting in front of a camera, walking past it, standing clear of a
+  robot arm — is the user's job. Say exactly what to do, then **wait for the
+  user to confirm** before running the next command.
+- These commands print a JSON result on stdout. Exit codes: 0 confirmed by the
+  device; 1 the device did not confirm (timeout, error, read-back mismatch);
+  2 bad arguments; 3 port busy or cannot be opened, or (robot) the status
+  service is unreachable; 5 internal error. On 3 with `port_busy`, another
+  deployment or session holds the port: wait for it, do not force it.
+- At most 3 rounds per problem, as in `SKILL.md`.
+
+## 1. Dashboards and interactive checks (`web_dashboard`, `preview`, `image_predict`, `text_chat`, `voice_chat`, ...)
+
+- `web_dashboard`: `curl -s -o /dev/null -w "%{http_code}" <url>` must return
+  `expected_status` (200). Then give the user the `url` to open.
+- `endpoint` + `sample_request` present: run `sample_request.curl` and show
+  the user the relevant part of the response. In a multipart request
+  (`-F <file_field>=@IMAGE.jpg`) replace `IMAGE.jpg` with a real picture
+  (a photo the user gave you, or one downloaded into `./.sensecraft-work/`);
+  a JSON response with results (for example detections with labels and
+  scores, possibly an empty list for a picture without matching objects)
+  means the service works. An HTTP error or no answer goes to `diagnose.md`.
+  These events also come for verify steps that only describe a check in the
+  guide (no separate config file), with the default mode's endpoint.
+- Otherwise follow `instructions`. When they say to run the check in the
+  SenseCraft Solution app, tell the user: that check needs the desktop app.
+
+## 2. People counting lines (`serial_camera` with `counting_cli`)
+
+1. Ask the user where the counting lines / zones should be, in camera
+   coordinates 0–1000 (0,0 top left, 1000,1000 bottom right): a line is two
+   points `X1,Y1,X2,Y2`, a zone four corners. Direction: crossing from the
+   right side of the line (looking from point 1 to point 2) to the left counts
+   as `in`; swap the two points to reverse it.
+2. Write them:
+   `sensecraft-engine counting set --port <PORT> --line 0=100,500,900,500 [--roi 1=X1,Y1,...,X4,Y4] [--anchor-mode foot]`
+   (`foot` for a camera tilted down from above, `center` otherwise). The result
+   must have `verified: true`; `mismatches[]` lists slots that read back
+   differently.
+3. Start counting from zero and keep the camera running:
+   `sensecraft-engine counting reset --port <PORT> --keep-running`.
+4. Ask the user to walk across each line (and into each zone) and tell you when
+   done.
+5. `sensecraft-engine counting get --port <PORT>`: each line's `in` / `out` and
+   each zone's `cur` / `entered` must have changed as expected. Show the user.
+
+## 3. Face enrollment (`serial_camera` with `face_cli`, SenseCAP Watcher)
+
+The Watcher has two USB serial ports: the camera (`--port`) and the face
+database (`--db-port`).
+
+1. Ask the user whose face to enroll (name: ASCII up to 31 characters, Chinese
+   up to 4 characters).
+2. Ask that person to sit in front of the camera, facing it, and to tell you
+   when ready.
+3. `sensecraft-engine face enroll --port <PORT> --db-port <DB_PORT> --name <NAME> --no-prompt`.
+   Success: `stored: true`, `verified: true`. Too few samples
+   (`samples_collected` below the minimum): ask for better light / a closer,
+   straight-on face, then run it again.
+4. `sensecraft-engine face list --db-port <DB_PORT>` and show the names to the
+   user. Fix mistakes with `face rename --db-port <DB_PORT> --name OLD --new-name NEW`
+   or `face delete --db-port <DB_PORT> --name NAME` (deleting needs the user's OK).
+5. Ask an enrolled person to stand in front of the camera and confirm the
+   device recognizes them by name.
+
+## 4. Servo ID setup (`serial_wizard` with `wizard_cli`)
+
+The firmware sets one servo ID at a time and prints prompts.
+
+1. Tell the user to connect **only** the servo for the current ID (the
+   event's `instructions` name them, e.g. ID 1 front wheel, 2 left rear, 3 right
+   rear) and to confirm.
+2. `sensecraft-engine wizard action --port <PORT> --name enter`. Pass the
+   firmware's `prompt` text on to the user.
+3. `step_error` set: ask the user to check the wiring, then
+   `sensecraft-engine wizard action --port <PORT> --name retry`.
+4. Repeat for each servo until the result has `step_done: true`
+   (`wizard read --port <PORT> --until done` waits for it). Then ask the user
+   to power off, connect all servos and power on again.
+
+## 5. Robot arm check (`robot_inspect` with `robot_cli`)
+
+Commands that move the arm need the user's OK each time.
+
+1. `sensecraft-engine robot observe --host <HOST>`: every joint has a value.
+2. Ask the user's OK, then `robot torque off --host <HOST>`; ask the user to
+   turn one joint by hand; `robot observe` again — the reading must follow.
+   Show the user the numbers.
+3. Recording a motion: for each pose the user sets by hand, run `robot observe`
+   and add the `observation` to a frame file
+   (`[{"joints": {...}, "delay": 0.4}, ...]`).
+4. Before `robot actions test --host <HOST> --frames <file>`, ask the user to
+   stand clear of the arm and confirm. Afterwards ask whether the motion was
+   right.
+5. Only after the user approves it:
+   `robot actions save --host <HOST> --name <name> --frames <file>`.
+   `robot actions cancel --host <HOST>` stops a running motion.
+
+## 6. Report
+
+For each verify step tell the user: what you checked, the command result
+(the relevant fields, not the whole JSON), and anything left for them to do.