Metadata-Version: 2.5
Name: ikompete
Version: 0.2.0
Summary: Command-line client for the iKompete competition platform
Project-URL: Homepage, https://github.com/GiesDSRS/ikompete-cli
Project-URL: Repository, https://github.com/GiesDSRS/ikompete-cli
Project-URL: Issues, https://github.com/GiesDSRS/ikompete-cli/issues
Author: Gies Data Science Research Services, University of Illinois
License-Expression: MIT
License-File: LICENSE
Keywords: cli,competitions,ikompete
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# ikompete

Command-line client for the [iKompete](https://ikompete.dsrs.illinois.edu) competition platform.

```
 _ _                       _
(_) |_____ _ __  _ __  ___| |_ ___
| | / / _ \ '  \| '_ \/ -_)  _/ -_)
|_|_\_\___/_|_|_| .__/\___|\__\___|
                |_|
```

## Install

Python 3.10 or later:

```
pip install ikompete
ikompete --help
```

Or, to keep it isolated from your other packages: `pipx install ikompete`. To upgrade:
`pip install -U ikompete`.

Make sure the `pip` you use belongs to Python 3.10+ (`pip --version`); otherwise the
`ikompete` command ends up in a different environment than the one on your `PATH`.

To work on the CLI itself, install from a clone instead: see [Development](#development).

## Log in

```
ikompete login
```

Login uses a pairing code, so you never paste a password or token into the terminal:

1. The CLI asks the server for a one-time code and prints a link and the code:

   ```
   To sign in, open:  https://ikompete.dsrs.illinois.edu/cli?code=WDJB-MJHT
   and confirm the code:  WDJB-MJHT
   ```

2. It tries to open the link in your browser. On the website, sign in as usual (SSO or
   password) if you aren't already, check that the code matches, and press **Approve**
   (or **Deny**).
3. The CLI waits for the approval, then saves the session. Codes are single-use and
   expire after 10 minutes. Press Ctrl-C to cancel.

You can approve from any device, including your phone, so login also works on a remote
machine.

Options:

- `--no-browser`: print the link but don't try to open a browser. The browser is also
  skipped automatically over SSH and on Linux/Unix without a display.
- `--force`: log in again even if you're already logged in. The previous session is
  revoked on the server once the new one is saved.

Approving needs a verified iKompete account. Sessions last 30 days.

## Commands

| Command | What it does |
|---|---|
| `ikompete login` | Log in by approving a pairing code in your browser. |
| `ikompete logout` | Revoke this server's session on the server and delete it locally. |
| `ikompete status` | Show the logged-in user, server, session expiry and credentials path. Makes no network call. |
| `ikompete profile` | Show your account: username, first and last name, email and role. |
| `ikompete competitions` | List the competitions you joined, then the open ones you haven't joined. The Kit column says whether a competition has a starter kit. |
| `ikompete pull ID [DEST]` | Download a competition's starter kit into a new folder. |
| `ikompete validate [PATH]` | Check a submission locally and with the server, without using a submission. |
| `ikompete submit [PATH]` | Validate, then upload a submission as your next version. |

`ikompete --version` prints the version.

`profile` doesn't show whether your account is verified, because the server doesn't send
that field yet.

## Starter kits

Some competitions come with a starter kit from the host: instructions, a file to fill
in, the grader's harness, sample data and sometimes a local check.

```
ikompete pull 12
```

creates the kit's folder, for example `./my-competition/` (the folder name comes from the
kit). `DEST` is the parent folder to create the kit folder in, so `ikompete pull 12 work`
creates `work/my-competition/`; it defaults to the current folder.

- `pull` refuses if the kit folder already exists. `--force` replaces it, but only if
  it is a starter kit folder for the same competition.
- You need to be logged in and a competitor in the competition (or one of its hosts).
  A competition without a kit prints `This competition has no starter kit.`
- `--json` prints `{"path", "competition_id", "submit"}`.

## Validate and submit

Inside a kit folder (or any folder below it), neither command needs arguments: the
competition and the file to submit come from the kit's `ikompete.toml`. If PATH is
inside a kit, that kit is used, even when you run the command from another kit's folder.
A kit whose `competition_id` doesn't include `--competition` is ignored.

```
cd my-competition
# edit submission_file.py
ikompete validate
ikompete submit
```

Outside a kit, pass both: `ikompete validate my_file.py --competition 12`. Without
`--competition` outside a kit, both commands stop with `Run this inside a starter kit or
pass --competition ID.` (exit 2).

`validate` runs up to three checks, in order, and stops at the first failure:

1. **Competition checks** (built into the CLI): the file exists, is under 100 MB and,
   for some competitions, has the right shape (for example, the file type, a line limit
   or a required top-level function), mirroring the server's validator.
2. **The starter kit's check**, if the kit has one. It runs the host's script with your
   Python: `--python EXE`, else the kit's `python` setting, else `python3` (or `python`)
   on your `PATH`, so activate the environment that has your packages first. It is
   stopped after 120 seconds.
3. **The server's check** (authoritative, needs login). It runs the same validator as a
   real submission but stores nothing and doesn't use your quota. Skip it with
   `--no-server`. If you aren't logged in, the first two checks still run and the
   server check fails with `Not logged in; run ikompete login, or use --no-server to
   skip the server check.` (exit 3). Server errors (for example too many checks in a
   minute) show as a failed server check, after the earlier checks' results.

Each check prints `PASS` or `FAIL` with its messages; `validate` exits 1 if any fails.
`--json` prints a list of `{"layer", "ok", "messages"}` (layers `competition`, `kit`,
`server`), also when a check fails; the "Running ..." lines go to stderr.

`submit` runs the same checks (all three), then uploads through the same endpoint as
the website, so quotas, access, versions and grading are the website's:

```
Submitted version 3 (status: pending).
```

- `pending` means grading hasn't finished or, for some competitions, that a host starts
  it later.
- For a practice run, it prints `Started a practice run; it doesn't count as a
  submission.`
- `--no-validate` skips the checks and uploads straight away.
- `--json` prints the server's response (`id`, `competition_id`, `user_id`, `team_id`,
  `file_path`, `file_type`, `version`, `status`). If a check fails, nothing is uploaded
  and it prints `{"submitted": false, "results": [...]}` (the same results as
  `validate --json`), with exit 1.
- Errors from the server (no submissions left, not a competitor, competition closed)
  are printed as the server words them, with exit 1.
- Multi-file and URL (HTML or GitHub) competitions can't be submitted from the CLI yet;
  `submit` says so and points you to the website.

If the path to submit is a folder, it is zipped first. The zip leaves out `.git`, any
`.env*` file or folder, virtualenvs (`.venv`, `venv`), `__pycache__`, `*.pyc`,
`.ipynb_checkpoints`, `.DS_Store` and symbolic links.

## Starter kit format (for hosts)

**Creating a new competition for the CLI?** Follow the step-by-step guide in
[`docs/creating-a-competition-kit.md`](https://github.com/GiesDSRS/ikompete-cli/blob/main/docs/creating-a-competition-kit.md): choosing the
submission, building the kit from your competition repo, the three check layers,
testing, uploading and updating.

A kit is a zip with exactly one top-level folder; that folder's name is the folder
`pull` creates. Inside it, `ikompete.toml` plus whatever files you want. The generic
template in `examples/starter-kit-template/` is a working starting point, and
`examples/README.md` shows how to build the zip and where to upload it
(`competitions/public/<path_id>/starter.zip` in the platform's bucket).

`ikompete.toml`:

```toml
competition_id = 12                # required: an integer, or a list of integers
submit = "submission_file.py"      # required: file or folder to submit, relative to the kit root
validate = "checks/validate.py"    # optional: local check script
python = "python3"                 # optional: interpreter for the check script
```

- Paths must stay inside the kit folder. Unknown keys are ignored, so newer kits work
  with older CLIs.
- With a list of competition ids, competitors pass `--competition ID` to `validate` and
  `submit`.

The check script contract:

- The CLI runs `<python> <validate> <absolute path to the submission>` with the kit
  folder as the working directory, and stops it after 120 seconds.
- Exit code 0 means pass; anything else means fail.
- Optionally print one JSON object on stdout, `{"ok": true|false, "messages": ["..."]}`,
  as the whole of stdout or as its last non-empty line. Its messages are shown, and the check passes only if `ok` is true and the exit code
  is 0. Without that JSON, the last 20 lines of output are shown.
- Keep it to the standard library (plus whatever the submission itself imports), since
  it runs in the competitor's environment.

Kits are unpacked safely: absolute paths, `..`, symbolic links and kits larger than
200 MB unpacked are refused.

## JSON output

Add `--json` to get machine-readable output:

```
ikompete --json competitions
ikompete competitions --json
```

`--json` and `--api-url` work before or after the subcommand; a value given after the
subcommand wins. In JSON mode stdout carries only JSON (and nothing if the command
fails, except that `status --json` prints `{"logged_in": false}` when not logged in and
`validate`/`submit --json` print the check results when a check fails);
every message, prompt and error goes to stderr, so you can pipe stdout straight into
`jq`. Tokens are never printed, in any mode.

`competitions --json` prints `{"joined": [...], "open": [...]}`.

## Configuration

| Setting | What it does |
|---|---|
| `--api-url URL` | API server to use. Default `https://ikmpt.dsrs.illinois.edu`. |
| `IKOMPETE_API_URL` | Same as `--api-url`; the option wins if both are set. |
| `IKOMPETE_HOME` | Directory for local state. Default `~/.ikompete`. |

The API URL must use `https://`; `http://` is allowed only for `localhost` and `127.0.0.1`
(any port). Anything else, including a URL without a scheme, is a usage error (exit 2).

## Exit codes

| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Error (network, server error, login denied or expired, `status` when not logged in, a failed check) |
| 2 | Usage error (unknown command or option, an insecure API URL, or `validate`/`submit` outside a kit without `--competition`) |
| 3 | Not logged in, or the session expired or was revoked: run `ikompete login` |

## Credentials and logging out

The session is stored in `~/.ikompete/credentials.json` (or `$IKOMPETE_HOME/credentials.json`).
The directory is created with mode 0700 and the file with mode 0600. Sessions are kept
per server, so you can be logged in to more than one API URL at a time; every command
uses the session for the server it talks to.

```
ikompete logout
```

revokes the session on the server and deletes it from the credentials file. If the
server can't be reached, the local copy is still deleted and a warning is printed.

## Development

Clone the repo, then set up and test:

```
git clone git@github.com:GiesDSRS/ikompete-cli.git && cd ikompete-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m unittest discover -s tests
```

Without installing, run from the source tree with `PYTHONPATH=src`:

```
PYTHONPATH=src python -m unittest discover -s tests
PYTHONPATH=src python -m ikompete --help
```

Server side: the `/auth/cli/*` endpoints live in ikompete-server (`routers/cli_auth.py`),
and the approval page is `/cli` on the website (ikmpt-gui, `src/pages/CliApprove.tsx`).

## Releasing

The package is published to PyPI as [`ikompete`](https://pypi.org/project/ikompete/)
(MIT license). Releases go out through `.github/workflows/release.yml` using PyPI trusted
publishing, so no API token is stored in GitHub.

### First release (manual)

We publish the first release (0.2.0) by hand by choice, so the first upload is checked by a person. Trusted
publishing could do it too: PyPI accepts a "pending publisher" for a project that doesn't
exist yet. From a clean checkout:

```
pip install build twine
python -m build
twine upload dist/*
```

`twine` asks for a PyPI API token (user `__token__`).

Don't push a `v0.2.0` tag for a version you uploaded by hand: the workflow would try to
publish it again and fail, because PyPI never accepts the same version twice. Tag only
versions you release through the workflow (0.2.1 and later).

### Register the trusted publisher

On PyPI, open the `ikompete` project, then **Manage > Publishing > Add a new publisher
(GitHub)**, and enter exactly:

| Field | Value |
|---|---|
| Owner | `GiesDSRS` |
| Repository name | `ikompete-cli` |
| Workflow name | `release.yml` |
| Environment name | `pypi` |

In the GitHub repository, create an environment named `pypi` (**Settings >
Environments**); you can add required reviewers there.

### Later releases

1. Bump `version` in `pyproject.toml` and `__version__` in `src/ikompete/__init__.py`.
2. Commit, then tag and push the tag:

   ```
   git tag v0.2.1
   git push origin v0.2.1
   ```

Pushing a `v*` tag runs the workflow. It first checks that the tag (without the `v`)
equals `version` in `pyproject.toml` and stops if not; then it builds the sdist and wheel with
`python -m build` and publishes them with `pypa/gh-action-pypi-publish`.

## License

MIT. See `LICENSE`.
