gitea-nova/README.md

# Gitea for Nova

Gitea Actions, pull requests, reviews, secrets, and variables in the Nova
sidebar. This extension aims to give Nova the same day-to-day coverage the
official [Gitea for VS Code](https://gitea.com/gitea/gitea-vscode) extension
gives VS Code.

## Requirements

- Nova 9 or later, on macOS.
- Gitea 1.24 or later for the workflow runs API. Older servers still work: the
  extension falls back to `/actions/tasks` and shows a flat **Recent Runs** list.
- A personal access token, created in Gitea under **Settings → Applications →
  Access Tokens**.

### Token scopes

| Scope | Needed for |
| --- | --- |
| `read:repository` | Repositories, branches, pull requests |
| `read:issue` | Pull request timelines and comments |
| `write:repository` | Approving, merging, closing, review comments |
| `read:user` | Identifying the signed-in account |
| Actions read | Workflow runs, jobs, logs, artifacts |
| Actions write | Re-running and cancelling runs |
| Secrets / variables | Managing repository secrets and variables |

Read-only tokens work fine; the write-only features simply report a clear
permission error when used.

## Getting started

1. Open **Extensions → Gitea → Open Gitea Preferences** and set your instance
   URL (it defaults to `https://gitea.com`).
2. Run **Extensions → Gitea → Set Token…** and paste a personal access token.
   Tokens are stored in the macOS Keychain, one per instance.
3. Open the **Gitea** sidebar.

Repositories are discovered from the git remotes of the folders in your
workspace. A remote is matched to an instance by its host, so
`[email protected]:acme/widget.git` routes to the configured instance at
`https://gitea.example.com`. Set **Discovery Mode** to *All Accessible
Repositories* to list everything your token can reach instead.

## Sidebar sections

**Current Branch** — pull requests and workflow runs for the branch checked out
in the workspace. Use the branch button in the section header (or **Change
Branch Filter…**) to follow all branches or pin a specific one.

**Workflows** — every run in the repository, grouped by workflow file. Expand a
run for its jobs, each job for its steps, and open the run's artifacts.

**Pull Requests** — open pull requests across all discovered repositories, each
expanding into its reviews, review comments, and changed files.

**Settings** — connection state per instance, plus repository Actions secrets
and variables. Secrets and variables load only when you expand them.

## What you can do

- **Runs** — re-run a run, re-run only its failed jobs, re-run a single job, or
  cancel a run in progress.
- **Logs** — double-click a job to open its logs. With **Save Job Logs to
  Repository** on, logs are written to `.tmp/gitea-logs/` so they open as real
  files; otherwise they open in an untitled tab.
- **Artifacts** — download to `.tmp/gitea-artifacts/`, reveal in Finder, or open
  (single-file artifacts are unzipped and opened directly).
- **Pull requests** — open a Markdown overview, open the unified diff, jump to a
  changed file, check out the branch, create a pull request, merge with any of
  Gitea's four strategies, or close.
- **Reviews** — approve, request changes, or comment; reply to a review comment;
  resolve and unresolve threads.
- **Inline comments** — review comments on the current branch's pull requests
  appear as issues in the editor gutter and the Issues sidebar, anchored to the
  line the comment was left on. Comments from a *request changes* review show as
  errors, others as warnings, resolved ones as info.
- **Add a review comment from the editor** — put the cursor on a line and use
  **Editor → Add Gitea Review Comment…**.
- **Secrets and variables** — add, update, and delete, per repository.

Polling adapts to activity: every 15 seconds while runs are queued or running,
every 60 seconds otherwise. Both intervals are configurable, and a run that
finishes in a failed state posts a notification.

## Multiple instances

Add extra instances under **Additional Instances** in preferences, or with
**Add Gitea Instance…**. Each keeps its own Keychain token, and repositories
route to whichever instance matches their remote host. The default instance is
used for anything that does not match.

## Differences from the VS Code extension

Nova's extension API does not expose everything VS Code's does, so a few
features are shaped differently:

| Gitea for VS Code | Here |
| --- | --- |
| Webview pull request timeline | Markdown overview opened in an editor tab |
| Native side-by-side diff editor | Unified `.diff` document, per file or whole PR |
| Inline comment threads on the diff | Review comments published as editor issues |
| Status bar run summary | Notification when a run fails |
| OAuth sign-in | Personal access tokens only — Nova extensions cannot run the local HTTP listener an OAuth redirect needs |
| `tls.insecureSkipVerify` | Not available; Nova's `fetch` has no TLS override |

## Preferences

| Setting | Default | What it does |
| --- | --- | --- |
| Default Instance URL | `https://gitea.com` | Instance used when no other matches a remote |
| Additional Instances | — | Extra instance URLs |
| Discovery Mode | `workspace` | Workspace git remotes, or all accessible repositories |
| Max Runs per Repository | 20 | How many runs to load |
| Max Jobs per Run | 50 | How many jobs to load |
| Active Interval | 15s | Poll rate while runs are in progress |
| Idle Interval | 60s | Poll rate when nothing is running |
| Notify on Failed Runs | on | Post a notification when a run fails |
| Show Review Comments Inline | on | Publish review comments as editor issues |
| Save Job Logs to Repository | on | Write logs to `.tmp/gitea-logs/` |
| Artifact Download Path | `.tmp/gitea-artifacts/` | Where artifacts land |
| Enable Debug Logging | off | Verbose extension console output |

Instance URL and branch filter can also be set per workspace under **Project
Settings**.

You will probably want to add `.tmp/` to the repository's `.gitignore`.

## Development

Symlink or copy this folder into Nova's extension directory and open the
**Extensions → Extension Library** to load it:

```sh
ln -s "$PWD" ~/Library/Application\ Support/Nova/Extensions/unsupervised.giteanova
```

Turn on **Enable Debug Logging** and watch the extension console
(**Extensions → Extension Library → Gitea → Console**) while working.

### Tests

```sh
Tests/run.sh
```

Two suites run the extension's real code under plain Node against a stubbed Nova
runtime and a canned Gitea instance — no install step, no network, and nothing
written inside the repository. See [Tests/README.md](Tests/README.md).

### Images

`Images/` is generated. To change an icon, edit the shapes in
`Tools/make-icons.py` and re-run it from the extension root:

```sh
python3 Tools/make-icons.py
```

## License

MIT