# Steps

Shared steps for knotless workflows. Each is a file under
`.knotless/steps/`, released on its own as `@step/<name>`.

Use one in place of a `run` step, then pin it with `knotless uses update`:

```yaml
steps:
  - uses: chadtmiller.com/steps/npm-ci@1
    with: {dir: web}
```

Commit the `.knotless/uses.lock` it writes. Runs read it.

| Step | What it does | Inputs | Cache |
| --- | --- | --- | --- |
| `node` | Installs Node.js at a version and puts `node`, `npm` and `npx` on the path. | `version` (required), `dir` | `/opt/node` |
| `npm-ci` | Runs `npm ci` only when `package-lock.json` has changed since the last install. | `dir`, `omit` | `<dir>/node_modules` |
| `rust-lint` | Runs `cargo fmt --check`, then clippy with warnings denied. | `clippy` | `target`, `/usr/local/cargo/registry`, `/usr/local/rustup` |
| `cargo-llvm-cov` | Installs cargo-llvm-cov at a version, with llvm-tools. | `version` (required), `dir` | `/opt/tools`, `/usr/local/rustup` |
| `ssh-key` | Writes the SSH key from the secret `SSH_KEY` to `~/.ssh`. | `name`, `known-hosts` | |
| `wait-for-checks` | Waits for this commit's checks of other workflows to pass. Use it before deploying. | `workflows` (required), `minutes` | |
| `publish-lexicons` | Publishes the lexicons whose authority is in a zone: schema records in an account, and `_lexicon` TXT records naming it. Plans only unless `write` is `true`. | `did` (required), `zone` (required), `dir`, `write` | |

`ssh-key` needs the secret passed to it by name:

```yaml
secrets: [SSH_KEY]
steps:
  - uses: chadtmiller.com/steps/ssh-key@1
    with: {known-hosts: "example.com ssh-ed25519 AAAA…"}
    secrets: [SSH_KEY]
```

`wait-for-checks` waits wherever it runs. To wait only where a later
step deploys, give it the same `on`:

```yaml
steps:
  - uses: chadtmiller.com/steps/wait-for-checks@2
    on: {refs: [refs/heads/main]}
    with: {workflows: check test}
```

`publish-lexicons` takes the account's app password as `LEX_PASSWORD`,
and `CLOUDFLARE_API_TOKEN`, with Zone:DNS:Edit on the zone, to change the
DNS. Planning needs neither:

```yaml
secrets: [LEX_PASSWORD, CLOUDFLARE_API_TOKEN]
steps:
  - uses: chadtmiller.com/steps/publish-lexicons@1
    with: {did: "did:plc:…", zone: example.com, write: "true"}
    secrets: [LEX_PASSWORD, CLOUDFLARE_API_TOKEN]
```

Each step's `needs` lists the commands it expects in the image, checked
before it runs. A new version of a step is released with:

```sh
knotless publish knotless://chadtmiller.com/steps @step/<name> <version> \
  .knotless/steps/<name>.yml --commit <sha>
```