stoke/README.md

# stoke

> CLI for the heavy-duty forge ([Forgejo](https://forgejo.org/)). Named for feeding a fire — the operator’s hand on the forge.

`stoke` turns real forge work into commands: auth, repos, issues, PRs, releases, labels, orgs, and a raw API escape hatch. Default instance: [`https://forgejo.heavyduty.builders`](https://forgejo.heavyduty.builders).

Built with [Commander.js](https://github.com/tj/commander.js/). Node.js **≥ 22.12** required.

---

## Install

**Debian / Ubuntu (recommended)**

```bash
curl -fsSL https://forgejo.heavyduty.builders/heavy-duty/stoke/raw/branch/main/scripts/install-apt.sh | bash
```

That script adds the forge’s Debian registry, bootstraps Node 22 when the distro package is too old, and installs `stoke`. Upgrades then come with `apt-get upgrade`.

**From source**

```bash
npm install && npm link
# or: node src/cli.js <command>
```

**Notes**

- On some apt versions (`sqv` / Debian 13+), Forgejo’s registry signature is rejected (upstream bug). The installer falls back to `[trusted=yes]` over HTTPS; once the forge signature is fixed, the signed source is preferred again.
- Each release also attaches a `.deb` for `sudo dpkg -i stoke_<version>_all.deb`.

---

## Quick start

```bash
stoke auth login          # interactive; or use STOKE_USERNAME / STOKE_PASSWORD
stoke auth status
stoke issue list -o heavy-duty -r stoke
stoke pr review -o heavy-duty -r stoke -n 3 --event approve -b "LGTM"
```

Full options and examples for every command: **[docs/COMMANDS.md](docs/COMMANDS.md)**.

---

## What you can do

| Area | Commands |
| --- | --- |
| **Auth** | `login`, `logout`, `status` |
| **Repos** | `clone`, `create`, `list`, `import`, `import-batch`, `rename`, `transfer` |
| **Issues** | `list`, `create`, `show`, `comment` |
| **PRs** | `list`, `create`, `show`, `comment`, `review`, `merge` |
| **Releases** | `list`, `view`, `create` |
| **Labels** | `list`, `create`, `delete`, `add`, `remove` |
| **Branches** | `list` |
| **Collaborators** | `add` |
| **Orgs / teams** | `create`, `repos`, `avatar`, team list/create/members |
| **Users** | `list`, `show` |
| **Escape hatch** | `stoke api <endpoint>` — any Forgejo REST path with the stored token |

Read commands support **`--json`** for machine-readable API output (see [COMMANDS.md](docs/COMMANDS.md)).

---

## Configuration

| | |
| --- | --- |
| Default path | `~/.config/stoke/config.json` (or `$XDG_CONFIG_HOME/stoke/config.json`) |
| Override | `--config <path>` (before the subcommand) or `STOKE_CONFIG_FILE` |
| Permissions | directory `0700`, file `0600` |

Stored fields: `url`, `login`, `username`, `email`, `token`, `tokenId`.

**Token scopes** — `auth login` mints a least-privilege token by default (`issue` R/W, `repository` R/W, `user` R, `organization` R). Use `--full-scopes` or `--scopes <csv>` for org admin / package publish. Details in [COMMANDS.md → Auth](docs/COMMANDS.md#auth).

### Environment

| Variable | Purpose |
| --- | --- |
| `STOKE_URL` | Default Forgejo base URL |
| `STOKE_USERNAME` / `STOKE_PASSWORD` | Defaults for `auth login` |
| `STOKE_CONFIG_FILE` / `STOKE_CONFIG_DIR` | Config location |
| `XDG_CONFIG_HOME` | Default config directory parent |
| `GITHUB_TOKEN` | Source token for `repo import` when `--github-token` is omitted |

`FORGEJO_*` names still work as fallbacks.

---

## Develop

```text
src/cli.js      commands and I/O
src/api.js      Forgejo client (Basic auth for tokens; token auth elsewhere)
src/config.js   secure config paths and persistence
```

```bash
npm test                  # Node built-in test runner
scripts/build-deb.sh      # -> dist/stoke_<version>_all.deb
scripts/publish-deb.sh dist/stoke_<version>_all.deb heavy-duty stable main
```

Tag `v*` to release: CI runs tests, builds the `.deb`, publishes to the `heavy-duty` Debian registry, and attaches the package to the release (needs a runner + `RELEASE_TOKEN` with package/repo write).

1. Bump `version` in `package.json` / lockfile  
2. Commit, tag `v<version>`, push the tag  
3. Consumers: `apt-get update && apt-get upgrade`

---

## Security

- Tokens on disk: mode `0600`. Passwords are never stored.
- Prefer `--password-file` or `STOKE_PASSWORD` over `-p` (shell history / `!` expansion).
- Interactive password prompts do not echo.
- `stoke api` is a full authenticated passthrough — never feed it untrusted strings in the path or body.
- `stoke repo clone` never writes the token into the remote URL or `.git/config`.

---

## Docs

| Doc | Contents |
| --- | --- |
| [docs/COMMANDS.md](docs/COMMANDS.md) | Full command reference |
| [docs/DESIGN.md](docs/DESIGN.md) | Brand system and landing design |

---

## Why “stoke”?

Heavy-duty tools are **one syllable**, plain English, industrial, and often a verb⇄noun: `cast`, `rig`, `jig`, `boss`, `hand`. The Forgejo instance is **the forge**. *To stoke* a fire is to tend it and keep it burning — this CLI does that for issues, PRs, imports, and org setup.

Rejected names included `forge` (the platform, not the tool), `weld` / `quench` (wrong metaphor), and `flux` (reads as chemistry, not the shop floor).