# CLAUDE.md

Context for future agent work in this repo. The README covers consumer-facing
usage; this file covers things that aren't obvious from reading the code.

## Where this action runs

Hosted on a self-hosted Gitea at `git.lair.cafe` (remote name `origin`,
SSH url `gitea@git.internal:actions/copr-publish.git`). Consumers reference
it by fully-qualified URL (`uses: https://git.lair.cafe/actions/copr-publish@v1`)
because Gitea's `DEFAULT_ACTIONS_URL` points at github.com.

There is **no CI on this repo itself**. The action is tested by running it
from a consumer repo (primarily `helexa/cortex`). When debugging, fetch job
logs via the `gitea-mcp` tools against the consumer repo, not this one —
e.g. `mcp__gitea-mcp__actions_run_read` with `owner=helexa`, `repo=cortex`.

## Tagging & release workflow

We use a **floating major tag** alongside specific semver tags:

- `v1.0.0`, `v1.0.1`, ... — immutable, annotated, per release.
- `v1` — floating annotated tag, moved forward to the latest `v1.x.y` on
  every v1 release. This is what `@v1` consumers resolve to.

When cutting a patch/minor release within v1:

```bash
git tag -a v1.0.N -m "v1.0.N\n\n<summary>" <sha>
git tag -a v1 -f -m "v1 (floating): latest v1.x release" <sha>
git push origin main v1.0.N
git push origin v1 --force     # floating tag move requires --force
```

The `--force` on the `v1` push is expected and authorized — that's how the
floating tag works. Do **not** force-push `main` or immutable `vX.Y.Z` tags.

A `v2` is reserved for the live-streaming behaviour change tracked in
issue #1 (stdout timing differs enough that consumers should opt in). Do
not quietly land that on `v1`.

## The COPR builder-live.log gotcha

The on-mirror file served by `copr-cli download-build` is
`builder-live.log.gz` for completed builds — not plain `builder-live.log`.
The script in `scripts/copr-build.sh` handles both, preferring `.gz` with
`zcat`. If you add log handling for other COPR artifacts (`build.log`,
`root.log`, `backend.log`), assume they are gzipped too.

The **HTTP live endpoint** at
`https://download.copr.fedorainfracloud.org/results/<owner>/<project>/<chroot>/<build_id>-<pkg>/builder-live.log`
serves plaintext during and after the build — that's the path issue #1's
live-streaming approach would use, sidestepping the `.gz`-on-disk issue.

## Testing a change

There is no local harness. To verify a change end-to-end:

1. Commit + push + tag as above (or push a branch and reference it by
   commit SHA from the consumer).
2. Trigger a workflow in the consumer repo (e.g. push to `helexa/cortex`).
3. Inspect the job log via `gitea-mcp` — note that job logs come back
   base64-ish wrapped in a JSON envelope and with `\r`/`\n` escapes; pipe
   through `jq -r '.[].text'` then `sed 's/\\r/\n/g; s/\\n/\n/g'` to get
   something greppable.

Syntax-only check locally: `bash -n scripts/copr-build.sh`.