@engineeros/connector 1.36.8 → 1.39.0

package/README.md

@@ -344,6 +344,24 @@ Unknown runtime failures may use one read-only LLM diagnosis per run through the
 
 Verification results are cached per commit and role. Completed checks are reused. An interrupted check requires inspection before a new revision; it is not automatically billed again. Existing workers must load the new connector code before these protections apply.
 
+## Integrations: GitHub, GitLab, Jira, Linear and monday.com
+
+EngineerOS holds no credentials for these services and none of them calls EngineerOS. When EngineerOS needs one (pull request review, Goal pull requests, repository import, backlog triage, filing defects in Linear), it asks the connector, which makes the call with this machine's own sign-in and sends back only the answer.
+
+```sh
+engineeros-connector integrations              # what this machine is signed in to
+gh auth login                                  # GitHub, through the GitHub CLI
+glab auth login                                # GitLab, through the GitLab CLI
+engineeros-connector connect linear            # prompts for a Linear API key
+engineeros-connector connect jira --site https://acme.atlassian.net --email you@acme.com
+engineeros-connector connect monday            # prompts for a monday.com API token
+engineeros-connector disconnect linear         # removes the key from this machine
+```
+
+The GitHub and GitLab CLIs need not be installed beforehand. **Install** beside the machine in Admin → Integrations, or `connect github` / `connect gitlab` here, has the connector download the release it pins (GitHub CLI 2.102.0, GitLab CLI 1.120.0) from the vendor's own release page, refuse it unless it matches the SHA-256 recorded in `src/integration-install.mjs`, and unpack it into `~/.engineeros/tools/<tool>/<version>`. Only the connector uses that copy, and only when the tool is not already on PATH; nothing is installed system-wide. Then sign in: **Sign in** beside the machine in Admin → Integrations starts the CLI's own device sign-in here (`gh auth login --web`, `glab auth login --device`) and shows its one-time code and page in EngineerOS. Whoever approves the code becomes the machine's GitHub or GitLab identity, so only the machine's owner can start it; the CLI keeps the token in the system keyring, and an unapproved code is abandoned after 15 minutes. `gh auth login`, `glab auth login` or `connect github` / `connect gitlab` in a terminal work too.
+
+A token is read without echo (or from stdin when piped), checked with the provider, and kept in the platform's protected store: Windows Data Protection, the macOS login Keychain, or the Linux Secret Service (install `secret-tool` and run a keyring such as GNOME Keyring). Sign-ins belong to the machine's user, so every workspace connected on the machine shares them. The running connector reads them on each request; no restart is needed. EngineerOS can ask only for the operations the connector lists (`src/integration-requests.mjs`), each with checked arguments, and answers travel back over the connector's authenticated HTTP channel.
+
 ## Optional tool and plugin inventory
 
 Connector 1.7 advertises a curated candidate catalog alongside the operator-managed inventory. The catalog covers code intelligence, design, work management, source control, documentation, research, API development, browser testing, quality and security, data, infrastructure, observability and development environments. Candidate entries are metadata only: they are not installed, authenticated, admitted, started or exposed to coding agents.
@@ -385,4 +403,43 @@ Manifests are strict internal JSON configuration with these required fields:
 | `evidence` | `metadata-only`. |
 | `evaluation` | `status` (`experimental` or `standard`) and a real evidence `reference`. Standard status requires completed comparative evaluation. |
 
-At most 16 providers may be registered per workspace even though the read-only catalog is larger. Local files must be regular files (resolve symlinks before registration). Inspection compares installed package metadata and entrypoint bytes; it does not verify the entire dependency tree. Local version/hash mismatches and unavailable files report preparation actions. Registered HTTPS providers may use connector-managed OAuth: open **Tools and plugins**, choose **Sign in**, and complete consent in the browser opened on the connected machine. The connector follows MCP authorization discovery, uses PKCE with a loopback callback, and advertises only status, scopes and expiry. Windows protects the credential payload with current-user DPAPI outside the repository; unsupported platform keychains fail closed. Sign out deletes the local credential but does not remove the provider registration. MCP protocol, runtime and index health remain unchecked until a provider pilot implements them. Every entry remains execution-disabled, even if authentication succeeds. Launch paths, endpoints, tokens, authorization codes and raw file errors are excluded from advertised inventory. Do not put secrets in labels, URLs, descriptions or evidence references.
+At most 16 providers may be registered per workspace even though the read-only catalog is larger. Local files must be regular files (resolve symlinks before registration). Inspection compares installed package metadata and entrypoint bytes; it does not verify the entire dependency tree. Local version/hash mismatches and unavailable files report preparation actions. Registered HTTPS providers may use connector-managed OAuth: open **Tools and plugins**, choose **Sign in**, and complete consent in the browser opened on the connected machine. The connector follows MCP authorization discovery, uses PKCE with a loopback callback, and advertises only status, scopes and expiry. Windows protects the credential payload with current-user DPAPI outside the repository; unsupported platform keychains fail closed. Sign out deletes the local credential but does not remove the provider registration. MCP protocol, runtime and index health remain unchecked until a provider pilot implements them. Every entry remains execution-disabled, even if authentication succeeds. Launch paths, endpoints, tokens, authorization codes and raw file errors are excluded from advertised inventory. Do not put secrets in labels, URLs, descriptions or evidence references.
+
+## Record CI test results
+
+Your CI can record each test suite's results in EngineerOS, where they sit beside manual and scheduled results on the project's Quality page, link to the test inventory, and open or resolve defects. No pairing is needed. Have your test runner write JUnit XML (pytest `--junitxml`, Vitest `--reporter=junit`, `jest-junit`, Playwright's `junit` reporter, `node --test --test-reporter=junit`, Maven Surefire, `go-junit-report`, `dotnet test --logger junit`), then run this after the tests, also when they failed:
+
+```sh
+npx --yes @engineeros/connector@latest results upload --label backend --junit "reports/**/*.xml" --coverage coverage.xml
+```
+
+Set three variables in the CI system: `ENGINEEROS_URL` (your EngineerOS address), `ENGINEEROS_API_TOKEN` (an organization API token with write access, from **Organization admin → API tokens**; keep it secret) and `ENGINEEROS_PROJECT_ID` (shown on the Quality page under **CI and schedules**). `--url`, `--token` and `--project-id` override them. The branch, commit and run link are read from GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, CircleCI and Bitbucket Pipelines; `--branch`, `--commit` and `--run-url` override them.
+
+`--junit` and `--coverage` take paths or globs (`*`, `?`, `[abc]`, `**`) and can be repeated; quote globs so the command expands them the same way on every platform. Coverage is a Cobertura XML or lcov report. One upload takes at most 50 JUnit and 20 coverage reports of up to 20 MB each.
+
+Recording results never fails your build: without the variables (a fork's pull request has no secrets) the command says so and exits 0, and a missing report or a failed upload is printed as a warning (a GitHub Actions or Azure Pipelines annotation where available) with exit code 0. Pass `--strict` to exit non-zero instead. The token is never printed.
+
+### GitHub Action
+
+The `github-action` folder of this package is a composite action that runs the same command. It is published from a public repository rather than with the npm package:
+
+```yaml
+- name: Record test results in EngineerOS
+  if: ${{ !cancelled() }}
+  uses: engineeros/connector/github-action@v1
+  with:
+    label: backend
+    junit: |
+      reports/junit.xml
+      reports/e2e/*.xml
+    coverage: coverage.xml
+    url: ${{ vars.ENGINEEROS_URL }}
+    token: ${{ secrets.ENGINEEROS_API_TOKEN }}
+    project-id: ${{ vars.ENGINEEROS_PROJECT_ID }}
+```
+
+Inputs: `label` and `junit` (required; one path or glob per line), `coverage`, `url`, `token`, `project-id` (each defaults to its `ENGINEEROS_*` variable), `strict` (`"true"` fails the step when the results cannot be recorded) and `connector-version` (defaults to the connector release the action belongs to). The action sets up Node.js 22 only when the runner does not already have it.
+
+## Scheduled regression runs
+
+A project can schedule a test command on the Quality page (**CI and schedules**): a plain command line, the folder it runs in, a cron expression and its time zone, and optionally a test environment. When a run is due, EngineerOS sends it to an online connector of the person who last saved the schedule. The connector runs it exactly like a Goal's command Proof - without a shell, stopped after 15 minutes unless `ENGINEEROS_TEST_COMMAND_TIMEOUT_MS` says otherwise, with the output redacted - collects the JUnit and coverage reports the command wrote, and reports what it measured, together with the checked-out branch and commit. Scheduled runs on one connector run one at a time. When no connector is online the run is recorded as skipped, with the reason, and is not queued.