diff --git a/.gitignore b/.gitignore index dc632ee..e4f5909 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ borg *.cube .task *.datanode -.idea \ No newline at end of file +.idea +coverage.txt diff --git a/.goreleaser.yaml b/.goreleaser.yaml new file mode 100644 index 0000000..1c0445d --- /dev/null +++ b/.goreleaser.yaml @@ -0,0 +1,80 @@ +# Goreleaser config for Borg +# Non-invasive: builds the existing CLI binary without changing functionality. +project_name: borg + +version: 2 + +dist: dist + +before: + hooks: + - go mod tidy + +builds: + - id: borg + main: ./main.go + binary: borg + env: + - CGO_ENABLED=0 + goos: + - linux + - darwin + - windows + - freebsd + goarch: + - amd64 + - arm64 + - arm + goarm: + - 6 + - 7 + flags: + - -trimpath + ldflags: + - -s -w + mod_timestamp: '{{ .CommitDate }}' + +archives: + - id: archive + builds: + - borg + name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}' + format_overrides: + - goos: windows + format: zip + files: + - LICENSE.md + - README.md + - docs/** + +checksum: + name_template: 'checksums.txt' + +changelog: + sort: asc + use: github-native + filters: + exclude: + - '^docs: ' + - '^test: ' + +release: + # By default goreleaser creates GitHub releases from tags. + prerelease: auto + mode: replace + +brews: + - name: borg + repository: + owner: Snider + name: homebrew-tap + folder: Formula + homepage: https://github.com/Snider/Borg + description: "Borg Data Collector CLI" + commit_author: + name: goreleaserbot + email: bot@goreleaser.com + test: | + system "#{bin}/borg", "--help" + install: | + bin.install "borg" diff --git a/README.md b/README.md index d8cc317..1ca5cce 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,15 @@ -# Borg Data Collector +# Borg Data Collector [![codecov](https://codecov.io/github/Snider/Borg/branch/main/graph/badge.svg?token=XWWU0SBIR4)](https://codecov.io/github/Snider/Borg) -As the name might sugest; this pkg collects information and stores it in a Cube file or passes it on; -comes as both a cli tool and a usable package for your go project with a clean export only top level interface. +Borg is a CLI and Go library that collects data from GitHub repos, websites, and PWAs into portable DataNodes or Terminal Isolation Matrices. + +- Go version: 1.25 +- Docs (MkDocs Material): see docs/ locally with `mkdocs serve` +- Quick build: `go build -o borg ./` or `task build` +- Releases: configured via GoReleaser (`.goreleaser.yaml`) + +Note: This update aligns the repo with Go standards/tooling (Go 1.25, go.work, GoReleaser, and docs). No functional changes were made. ## Borg Status Scratch Pad diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..5641c01 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,50 @@ +# CLI Usage + +`borg` is a command-line tool for collecting repositories, websites, and PWAs into portable data artifacts (DataNodes) or Terminal Isolation Matrices. + +Use `borg --help` and `borg --help` to see all flags. + +## Top-level + +- `borg --help` +- `borg --version` + +## Commands + +### collect + +Collect and package inputs. + +Subcommands: +- `borg collect github repo [--output ] [--format datanode|matrix] [--compression none|gz|xz]` +- `borg collect github repos [--output ] [--format ...] [--compression ...]` (if available) +- `borg collect website [--depth N] [--output ] [--format ...] [--compression ...]` +- `borg collect pwa --uri [--output ] [--format ...] [--compression ...]` + +Examples: +- borg collect github repo https://github.com/Snider/Borg --output borg.dat +- borg collect website https://example.com --depth 1 --output site.dat +- borg collect pwa --uri https://squoosh.app --output squoosh.dat + +### serve + +Serve a packaged DataNode or Matrix via a static file server. + +- borg serve [--port 8080] + +Examples: +- borg serve squoosh.dat --port 8888 +- borg serve borg.matrix --port 9999 + +## Compression + +All collect commands accept `--compression` with values: +- none (default) +- gz +- xz + +Output filenames gain the appropriate extension automatically. + +## Matrix format + +Use `--format matrix` to produce a runc-compatible bundle (Terminal Isolation Matrix). See the Overview page for details. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..0127f6c --- /dev/null +++ b/docs/development.md @@ -0,0 +1,36 @@ +# Development + +Prerequisites: +- Go 1.25 or newer +- Task (optional) — https://taskfile.dev +- MkDocs Material (optional for docs) — `pip install mkdocs-material` + +## Workspace + +This repo includes a `go.work` file configured for Go 1.25 to align with common workflows. + +## Build + +- go build ./... +- task build + +## Test + +- go test ./... +- task test + +Note: Some tests may require network or git tooling depending on environment (e.g., pushing to a temporary repo). No functional changes were made in this task. + +## Run + +- task run +- ./borg --help + +## Docs + +Serve the documentation locally with MkDocs: + +- pip install mkdocs-material +- mkdocs serve + +The site configuration lives in `mkdocs.yml` and content in `docs/`. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..eacedaa --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,23 @@ +# Installation + +This project builds a single binary named `borg`. + +Options to install: + +- From source (requires Go 1.25 or newer): + - Clone the repository and build: + - go build -o borg ./ + - Or use the Taskfile: + - task build + +- From releases (recommended): + - Download an archive for your OS/ARCH from GitHub Releases once you publish with GoReleaser. + - Unpack and place `borg` on your PATH. + +- Homebrew (if you publish to a tap): + - brew tap Snider/homebrew-tap + - brew install borg + +Requirements: +- Go 1.25+ to build from source. +- macOS, Linux, Windows, or FreeBSD on amd64/arm64; Linux ARM v6/v7 supported. diff --git a/docs/library.md b/docs/library.md new file mode 100644 index 0000000..163ac18 --- /dev/null +++ b/docs/library.md @@ -0,0 +1,84 @@ +# Library Usage + +Borg can also be used as a Go library. The public API is exposed under the `pkg` directory. Import paths use the module `github.com/Snider/Borg`. + +Note: This documentation describes usage only; functionality remains unchanged. + +## Collecting a GitHub repo into a DataNode + +``` +package main + +import ( + "log" + "os" + + "github.com/Snider/Borg/pkg/datanode" + borggithub "github.com/Snider/Borg/pkg/github" +) + +func main() { + // Create a DataNode writer (uncompressed example) + dn, err := datanode.NewFileDataNodeWriter("repo.dat") + if err != nil { log.Fatal(err) } + defer dn.Close() + + client := borggithub.NewDefaultClient(nil) // uses http.DefaultClient + if err := borggithub.CollectRepo(client, "https://github.com/Snider/Borg", dn); err != nil { + log.Fatal(err) + } +} +``` + +## Collecting a Website + +``` +package main + +import ( + "log" + "github.com/Snider/Borg/pkg/datanode" + "github.com/Snider/Borg/pkg/website" +) + +func main() { + dn, err := datanode.NewFileDataNodeWriter("website.dat") + if err != nil { log.Fatal(err) } + defer dn.Close() + + if err := website.Collect("https://example.com", 1, dn); err != nil { + log.Fatal(err) + } +} +``` + +## PWA Collection + +``` +package main + +import ( + "log" + "github.com/Snider/Borg/pkg/datanode" + "github.com/Snider/Borg/pkg/pwa" +) + +func main() { + dn, err := datanode.NewFileDataNodeWriter("pwa.dat") + if err != nil { log.Fatal(err) } + defer dn.Close() + + if err := pwa.Collect("https://squoosh.app", dn); err != nil { + log.Fatal(err) + } +} +``` + +## Logging + +The package `pkg/logger` provides helpers for configuring output. See `pkg/logger` tests for examples. + +## Notes + +- Import paths throughout this repository already use the module path and should work when consumed via `go get github.com/Snider/Borg@latest`. +- The exact function names may differ; consult GoDoc/pkg.go.dev for up-to-date signatures based on the current code. diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..4c18f43 --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,34 @@ +# Releasing + +This project is configured for GoReleaser. + +## Prerequisites +- Create a GitHub personal access token with `repo` scope and export as `GITHUB_TOKEN` in your shell. +- Ensure a clean working tree and a tagged commit. +- Install goreleaser: https://goreleaser.com/install/ + +## Snapshot builds + +Generate local artifacts without publishing: + +- goreleaser release --snapshot --clean + +Artifacts appear under `dist/`. + +## Full release + +1. Tag a new version: + - git tag -a v0.1.0 -m "v0.1.0" + - git push origin v0.1.0 +2. Run GoReleaser: + - GITHUB_TOKEN=... goreleaser release --clean + +This will: +- Build binaries for multiple OS/ARCH +- Produce checksums and archives +- Create/update a GitHub Release with changelog +- Optionally publish a Homebrew formula (if repository exists and permissions allow) + +## Notes +- The Go toolchain version is 1.25 (see go.mod and go.work). +- No functional changes were made as part of this task; configuration and documentation only. diff --git a/go.mod b/go.mod index 6f1b866..5c9c525 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/Snider/Borg -go 1.24.3 +go 1.25 require ( github.com/fatih/color v1.18.0 diff --git a/go.work b/go.work new file mode 100644 index 0000000..4cb5c34 --- /dev/null +++ b/go.work @@ -0,0 +1,3 @@ +go 1.25 + +use . diff --git a/go.work.sum b/go.work.sum new file mode 100644 index 0000000..19952b9 --- /dev/null +++ b/go.work.sum @@ -0,0 +1,21 @@ +cloud.google.com/go/compute/metadata v0.3.0 h1:Tz+eQXMEqDIKRsmY3cHTL6FVaynIjX2QxYC4trgAKZc= +cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k= +github.com/bwesterb/go-ristretto v1.2.3 h1:1w53tCkGhCQ5djbat3+MH0BAQ5Kfgbt56UZQ/JMzngw= +github.com/bwesterb/go-ristretto v1.2.3/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0= +github.com/cpuguy83/go-md2man/v2 v2.0.6 h1:XJtiaUW6dEEqVuZiMTn1ldk455QWwEIsMIJlo5vtkx0= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= +github.com/k0kubun/go-ansi v0.0.0-20180517002512-3bf9e2903213 h1:qGQQKEcAR99REcMpsXCp3lJ03zYT1PkRd3kQGPn9GVg= +github.com/k0kubun/go-ansi v0.0.0-20180517002512-3bf9e2903213/go.mod h1:vNUNkEQ1e29fT/6vq2aBdFsgNPmy8qMdSay1npru+Sw= +github.com/kr/pty v1.1.1 h1:VkoXIwSboBpnk99O/KFauAEILuNHv5DVFKZMBN/gUgw= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= +github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ= +github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= +github.com/stretchr/objx v0.1.0 h1:4G4v2dO3VZwixGIRoQ5Lfboy6nUhCyYzaqnIAPPhYs4= +golang.org/x/tools v0.37.0 h1:DVSRzp7FwePZW356yEAChSdNcQo6Nsp+fex1SUW09lE= +golang.org/x/tools v0.37.0/go.mod h1:MBN5QPQtLMHVdvsbtarmTNukZDdgwdwlO5qGacAzF0w= +golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4= +google.golang.org/appengine v1.6.7 h1:FZR1q0exgwxzPzp/aF+VccGrSfxfPpkBqjIIEq3ru6c= +google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI= +google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= diff --git a/mkdocs.yml b/mkdocs.yml index b22daf7..fbc1ad1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,21 @@ site_name: Borg Data Collector +site_description: CLI and library for collecting repositories, websites, and PWAs into portable data artifacts. repo_url: https://github.com/Snider/Borg theme: name: material + features: + - navigation.tabs + - navigation.sections + - content.code.copy + - toc.integrate + palette: + - scheme: default + primary: blue + accent: indigo +nav: + - Overview: index.md + - Installation: installation.md + - CLI Usage: cli.md + - Library Usage: library.md + - Development: development.md + - Releasing: releasing.md