feat: Update project configuration and documentation for Go 1.25 compatibility

2025-11-04 11:46:49 +00:00 · 2025-11-04 11:46:49 +00:00 · 4529aba089
commit 4529aba089
parent 02993fe87b
12 changed files with 360 additions and 5 deletions
--- a/.gitignore
+++ b/.gitignore
@ -2,4 +2,5 @@ borg
 *.cube
 .task
 *.datanode
-.idea
+.idea
+coverage.txt
--- a/.goreleaser.yaml
+++ 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"
--- 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
--- a/docs/cli.md
+++ 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 <command> --help` to see all flags.
+
+## Top-level
+
+- `borg --help`
+- `borg --version`
+
+## Commands
+
+### collect
+
+Collect and package inputs.
+
+Subcommands:
+- `borg collect github repo <repo-url> [--output <file>] [--format datanode|matrix] [--compression none|gz|xz]`
+- `borg collect github repos <org-or-user> [--output <file>] [--format ...] [--compression ...]` (if available)
+- `borg collect website <url> [--depth N] [--output <file>] [--format ...] [--compression ...]`
+- `borg collect pwa --uri <url> [--output <file>] [--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 <file> [--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.
--- a/docs/development.md
+++ 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/`.
--- a/docs/installation.md
+++ 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.
--- a/docs/library.md
+++ 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.
--- a/docs/releasing.md
+++ 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.
--- 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
--- a/go.work
+++ b/go.work
@ -0,0 +1,3 @@
+go 1.25
+
+use .
--- a/go.work.sum
+++ 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=
--- 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