# Development

## Requirements

- Go 1.24 or later

## Setup

```sh
git clone https://git.rumginger.org/agent/dataxl.git
cd dataxl
go mod download
```

## Common Commands

Format code:

```sh
gofmt -w cmd/dataxl/*.go
```

Run tests:

```sh
go test ./...
```

Build:

```sh
go build ./cmd/dataxl
```

Run locally:

```sh
go run ./cmd/dataxl -from yaml -to tsv -i examples/people.yaml
```

Build release archives locally:

```sh
scripts/build-release.sh
```

## Test Coverage

The current tests cover:

- YAML -> TSV flattening
- TSV -> JSON path restoration
- JSON -> XLSX -> JSON round trip

When adding a new format or path rule, add tests around both directions where
possible.

## CI/CD

Gitea Actions workflows live under `.gitea/workflows`.

- `ci.yml`: runs on pushes to `main`, pull requests, and manual dispatch.
- `release.yml`: runs on `v*` tag pushes and manual dispatch with a `tag` input.

The CI workflow checks formatting, runs tests, builds the CLI, and performs a
small YAML -> TSV -> JSON smoke test.

The release workflow runs tests, cross-builds release archives for Linux,
macOS, and Windows on amd64/arm64, writes `checksums.txt`, creates or reuses a
Gitea Release, and uploads the generated assets. It uses the built-in
`${{ secrets.GITEA_TOKEN }}` provided by Gitea Actions.

## Release Notes

Create a release by pushing a version tag:

```sh
go test ./...
git tag v0.1.0
git push origin main --tags
```

The same workflow can also be started manually from Gitea Actions by providing
the target tag as the `tag` input.

After tags exist, users can install a specific version:

```sh
go install git.rumginger.org/agent/dataxl/cmd/dataxl@v0.1.0
```

## Design Guidelines

- Keep stdin/stdout usable for shell pipelines.
- Keep TSV behavior predictable because it is the main Excel clipboard format.
- Preserve headers as the contract between spreadsheet data and structured data.
- Prefer explicit errors over silent best-effort conversion when a format is unsupported.
- Keep dependencies small unless a format needs a mature parser/writer.