@dijji/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dijitales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# dijji CLI (`@dijji/cli`)
+
+`dijji` runs the mobile E2E jobs of a Dijji pipeline on a developer machine. The cloud container cannot run an
+Android emulator or an iOS simulator, so a stage with an `ios`/`android` E2E target parks until a subscribed machine
+takes the job, builds the app with the recipe your team wrote, installs it, runs the Maestro flows and reports the
+result back.
+
+## Install
+
+```bash
+npm i -g @dijji/cli
+dijji --version
+dijji doctor
+```
+
+The package is a single bundled file (`dist/dijji.js`) with no runtime dependencies and no install scripts. Node.js 24
+or later is required. Every release is published from `packages/cli` by a GitHub Actions workflow on a `cli-v*` tag
+(npm trusted publishing with provenance); nothing is published from a laptop.
+
+The CLI talks to `https://app.dijji.ai` by default. A self-hosted or non-production control plane is given at
+login and remembered for the device: `dijji login --api <api-url> --frontend <frontend-url>`.
+
+### From the repository (development)
+
+```bash
+pnpm --filter @dijji/cli build
+pnpm --filter @dijji/cli pack --pack-destination packages/cli   # writes packages/cli/dijji-cli-<version>.tgz
+npm i -g ./packages/cli/dijji-cli-<version>.tgz
+```
+
+Without `--pack-destination`, `pnpm --filter ... pack` writes the tarball into the directory it is run from.
+
+## Requirements
+
+| Runner | Needs |
+|---|---|
+| all | git, Java 17+ (`java -version` must work, not just exist), Maestro 2.7.0+ |
+| android | adb and a running emulator or connected device (APK artifacts; AAB is not supported) |
+| ios | macOS with Xcode (`xcode-select -p`, `xcodebuild -version`) and an installed iOS simulator runtime |
+
+`dijji doctor` checks all of this from each tool's own version output. Supported platforms: macOS (Android and iOS),
+Linux (Android). Windows is not supported.
+
+## Commands
+
+```text
+dijji login [--runners android,ios] [--api <url> --frontend <url>]
+dijji logout
+dijji subscribe [<projectId>] [--runners android,ios] [--yes] [--android-device <serial>] [--ios-device <udid>]
+dijji unsubscribe <projectId> [--purge]
+dijji status
+dijji doctor [--json] [--runners android,ios]
+dijji run [--once] [--yes] [--keep-workdir] [--allow-scripts] [--fresh]
+          [--android-device <serial>] [--ios-device <udid>] [--print-service-template launchd|systemd]
+```
+
+- **login** opens `/cli/authorize` in the browser and prints a verification code (`XXXX-XXXX`). Approve only if the
+  browser shows the same code. The browser returns to a listener on `127.0.0.1`; nothing is sent to the API before
+  that. `--api`/`--frontend` point a self-hosted installation (both are required together). A dijji process that is
+  already running keeps the session it started with: once `dijji login` writes another session it stops with exit
+  code 4 at its next token refresh instead of switching; start it again.
+- **subscribe** checks three gates before it writes anything: every repository is readable with your own git
+  credentials (`git ls-remote`, no prompts), the tools for the selected runners pass `doctor`, and every build recipe
+  the project's stages use for the selected runners is printed with the stages that use it and approved (a recipe
+  whose paths could never run on this machine is refused). A device holds at most 5 subscriptions.
+- **run** polls for jobs, keeps the lease alive with a heartbeat, and runs one job at a time. Each heartbeat also
+  renews the artifact upload URL, which is never valid beyond the lease, so a job uploads its evidence however long it
+  runs. `--once` handles at most
+  one poll. A network or server error while polling does not stop the worker: it retries, backing off from 5 s to
+  60 s (`--once` exits with the error instead). If the server can no longer resolve a subscribed project (it was
+  deleted, or you are no longer in its team), `dijji run` names the subscription and exits with code 2; remove it with
+  `dijji unsubscribe <projectId>`. `--print-service-template` prints a launchd/systemd definition; it does not install
+  it.
+- **status** shows local state only and never prints secrets.
+
+Exit codes: `0` ok, `1` error, `2` usage, `3` upgrade required (the server rejected this CLI version; the message names
+the minimum version), `4` login required, `5` doctor failed, `130` interrupted.
+
+## What a job does
+
+1. Validates the job payload (clone URLs are recomputed from the provider, commit SHAs, app id, recipe paths, `E2E_`
+   environment names).
+2. Checks the tools and the device, and `git ls-remote` for every repository.
+3. Downloads the flow bundle and opens it safely (no paths outside the bundle, no links, size limits); the bundle's
+   `manifest.json` must match the job's runner, app id and case ids.
+4. Rejects flows that use `runScript`/`evalScript` unless `--allow-scripts` is given.
+5. Asks for approval when the build recipe (command, artifact glob, workdir, repository) is new on this machine.
+   `--yes` approves recipe changes without asking — anyone who can edit the pipeline can then run commands on this
+   machine.
+6. Brings the persistent workspace to the job's commit: `fetch`, `checkout --detach`, `reset --hard`, `clean -dff`.
+   Git hooks never run. Gitignored files (`local.properties`, `google-services.json`, `.env`, build caches) are kept.
+7. Deletes the previous artifact, runs the build (40 minute limit), finds exactly one artifact produced by this build.
+   The recipe's `workdir` is a folder inside its repository (relative, never above the repository root, symlinks
+   included); the artifact glob stays inside the workdir. The pipeline editor refuses a recipe that breaks these rules.
+8. Installs the app and compares the hash of what the device actually runs with the local build.
+9. Runs each flow in its own `maestro --device <id> test` process with one retry; test credentials are passed only in
+   that process's environment.
+10. Writes the result to disk first, uploads the artifacts (up to 20 MB) with the latest upload URL the heartbeat
+    renewed, and posts the result with a deterministic id, so a crash-and-restart repost is recognised as a duplicate.
+
+## Files
+
+```text
+~/.dijji/                              0700
+  credentials.json                     0600  refresh token only; access tokens stay in memory
+  credentials.lock                     0600  lets one dijji process at a time rotate or rewrite the credentials
+  projects/<projectId>.json            0600  subscription, selected devices, approved recipe fingerprints
+  workspaces/<projectId>/<subfolder>/        persistent clones (kept by unsubscribe unless --purge)
+  jobs/<jobRef>.p<publishSeq>/               one job: bundle/, out/ (JUnit, Maestro output, logcat), result.json
+  logs/<jobRef>.p<publishSeq>.log            redacted job log
+  run.lock                                   the running `dijji run`
+```
+
+A result the server did not accept stays in its job directory:
+
+- `posted: false` (the server could not be reached): the unchanged result is posted again when `dijji run` starts and
+  whenever the server hands the same publication back; the job is not run a second time for it.
+- rejected (the job is no longer this device's): the result is kept for inspection.
+- refused outright (for example a contract mismatch after a server upgrade): `dijji run` stops, keeps the result
+  unposted and asks you to upgrade the CLI.
+
+`dijji status` lists all of them.
+
+## Git providers
+
+GitHub, GitLab (including self-managed) and Bitbucket Cloud. The CLI recomputes each clone URL from the provider and
+refuses a job whose URL does not match. A provider added on the server later is unknown to older CLIs, so adding one
+must raise the server's minimum supported CLI version. The persistent clone keeps the clone URL in its own git config;
+`url.<base>.insteadOf` rewrites in your git config (for example https to ssh) are applied by git and do not make the
+clone look foreign.
+
+## Known limits
+
+- Submodules are not fetched; a build that needs them fails.
+- Windows is not supported.
+- Android artifacts must be a single `.apk`; AAB is not supported. iOS artifacts must be a simulator `.app`.
+- The Gradle cache (`~/.gradle`) is shared with your other projects; there is no per-project cache isolation.
+- A polluted workspace is reset with `dijji run --fresh` (it re-clones the project).
+
+## Development
+
+```bash
+pnpm --filter @dijji/cli typecheck
+pnpm --filter @dijji/cli test
+pnpm --filter @dijji/cli build && node packages/cli/dist/dijji.js --version
+```