Merge pull request #20 from Snider/update-docs

Update documentation to match current codebase state

docs/cli.md

@@ -16,35 +16,77 @@ Use `borg --help` and `borg <command> --help` to see all flags.
 Collect and package inputs.
 
 Subcommands:
-- `borg collect github repo <repo-url> [--output <file>] [--format datanode|matrix] [--compression none|gz|xz]`
+- `borg collect github repo <repo-url> [--output <file>] [--format datanode|tim|trix] [--compression none|gz|xz]`
-- `borg collect github repos <org-or-user> [--output <file>] [--format ...] [--compression ...]` (if available)
+- `borg collect github release <release-url> [--output <file>]`
+- `borg collect github repos <org-or-user> [--output <file>] [--format ...] [--compression ...]`
 - `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 github repo https://github.com/Snider/Borg --output borg.dat`
-- borg collect website https://example.com --depth 1 --output site.dat
+- `borg collect website https://example.com --depth 1 --output site.dat`
-- borg collect pwa --uri https://squoosh.app --output squoosh.dat
+- `borg collect pwa --uri https://squoosh.app --output squoosh.dat`
+
+### all
+
+Collect all public repositories from a GitHub user or organization.
+
+- `borg all <url> [--output <file>]`
+
+Example:
+- `borg all https://github.com/Snider --output snider.dat`
+
+### compile
+
+Compile a Borgfile into a Terminal Isolation Matrix (TIM).
+
+- `borg compile [--file <Borgfile>] [--output <file>]`
+
+Example:
+- `borg compile --file Borgfile --output a.tim`
+
+### run
+
+Execute a Terminal Isolation Matrix (TIM).
+
+- `borg run <tim-file>`
+
+Example:
+- `borg run a.tim`
 
 ### serve
 
-Serve a packaged DataNode or Matrix via a static file server.
+Serve a packaged DataNode or TIM via a static file server.
 
-- borg serve <file> [--port 8080]
+- `borg serve <file> [--port 8080]`
 
 Examples:
-- borg serve squoosh.dat --port 8888
+- `borg serve squoosh.dat --port 8888`
-- borg serve borg.matrix --port 9999
+- `borg serve borg.tim --port 9999`
+
+### decode
+
+Decode a `.trix` or `.tim` file back into a DataNode (`.dat`).
+
+- `borg decode <file> [--output <file>] [--password <password>]`
+
+Examples:
+- `borg decode borg.trix --output borg.dat --password "secret"`
+- `borg decode borg.tim --output borg.dat --i-am-in-isolation`
 
 ## Compression
 
 All collect commands accept `--compression` with values:
-- none (default)
+- `none` (default)
-- gz
+- `gz`
-- xz
+- `xz`
 
 Output filenames gain the appropriate extension automatically.
 
-## Matrix format
+## Formats
 
-Use `--format matrix` to produce a runc-compatible bundle (Terminal Isolation Matrix). See the Overview page for details.
+Borg supports three output formats via the `--format` flag:
+
+- `datanode`: A simple tarball containing the collected resources. (Default)
+- `tim`: Terminal Isolation Matrix, a runc-compatible bundle.
+- `trix`: Encrypted and structured file format.

docs/development.md

@@ -11,26 +11,26 @@ This repo includes a `go.work` file configured for Go 1.25 to align with common
 
 ## Build
 
-- go build ./...
+- `go build ./...`
-- task build
+- `task build`
 
 ## Test
 
-- go test ./...
+- `go test ./...`
-- task 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.
+Note: Some tests may require network or git tooling depending on environment (e.g., pushing to a temporary repo).
 
 ## Run
 
-- task run
+- `task run`
-- ./borg --help
+- `./borg --help`
 
 ## Docs
 
 Serve the documentation locally with MkDocs:
 
-- pip install mkdocs-material
+- `pip install mkdocs-material`
-- mkdocs serve
+- `mkdocs serve`
 
 The site configuration lives in `mkdocs.yml` and content in `docs/`.

docs/installation.md

@@ -6,17 +6,17 @@ Options to install:
 
 - From source (requires Go 1.25 or newer):
   - Clone the repository and build:
-    - go build -o borg ./
+    - `go build -o borg ./`
   - Or use the Taskfile:
-    - task build
+    - `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 tap Snider/homebrew-tap`
-  - brew install borg
+  - `brew install borg`
 
 Requirements:
 - Go 1.25+ to build from source.

docs/library.md

@@ -2,29 +2,32 @@
 
 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
 
-```
+```go
 package main
 
 import (
     "log"
     "os"
 
-    "github.com/Snider/Borg/pkg/datanode"
+    "github.com/Snider/Borg/pkg/vcs"
-    borggithub "github.com/Snider/Borg/pkg/github"
 )
 
 func main() {
-    // Create a DataNode writer (uncompressed example)
+    // Clone and package the repository
-    dn, err := datanode.NewFileDataNodeWriter("repo.dat")
+    cloner := vcs.NewGitCloner()
-    if err != nil { log.Fatal(err) }
+    dn, err := cloner.CloneGitRepository("https://github.com/Snider/Borg", nil)
-    defer dn.Close()
+    if err != nil {
+        log.Fatal(err)
+    }
 
-    client := borggithub.NewDefaultClient(nil) // uses http.DefaultClient
+    // Save to disk
-    if err := borggithub.CollectRepo(client, "https://github.com/Snider/Borg", dn); err != nil {
+    tarBytes, err := dn.ToTar()
+    if err != nil {
+        log.Fatal(err)
+    }
+    if err := os.WriteFile("repo.dat", tarBytes, 0644); err != nil {
         log.Fatal(err)
     }
 }
@@ -32,21 +35,30 @@ func main() {
 
 ## Collecting a Website
 
-```
+```go
 package main
 
 import (
     "log"
-    "github.com/Snider/Borg/pkg/datanode"
+    "os"
+
     "github.com/Snider/Borg/pkg/website"
 )
 
 func main() {
-    dn, err := datanode.NewFileDataNodeWriter("website.dat")
+    // Download and package the website
-    if err != nil { log.Fatal(err) }
+    // 1 is the depth (0 = just the page, 1 = page + links on page)
-    defer dn.Close()
+    dn, err := website.DownloadAndPackageWebsite("https://example.com", 1, nil)
+    if err != nil {
+        log.Fatal(err)
+    }
 
-    if err := website.Collect("https://example.com", 1, dn); err != nil {
+    // Save to disk
+    tarBytes, err := dn.ToTar()
+    if err != nil {
+        log.Fatal(err)
+    }
+    if err := os.WriteFile("website.dat", tarBytes, 0644); err != nil {
         log.Fatal(err)
     }
 }
@@ -54,21 +66,38 @@ func main() {
 
 ## PWA Collection
 
-```
+```go
 package main
 
 import (
     "log"
-    "github.com/Snider/Borg/pkg/datanode"
+    "os"
+
     "github.com/Snider/Borg/pkg/pwa"
 )
 
 func main() {
-    dn, err := datanode.NewFileDataNodeWriter("pwa.dat")
+    client := pwa.NewPWAClient()
-    if err != nil { log.Fatal(err) }
+    pwaURL := "https://squoosh.app"
-    defer dn.Close()
 
-    if err := pwa.Collect("https://squoosh.app", dn); err != nil {
+    // Find the manifest
+    manifestURL, err := client.FindManifest(pwaURL)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Download and package the PWA
+    dn, err := client.DownloadAndPackagePWA(pwaURL, manifestURL, nil)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Save to disk
+    tarBytes, err := dn.ToTar()
+    if err != nil {
+        log.Fatal(err)
+    }
+    if err := os.WriteFile("pwa.dat", tarBytes, 0644); err != nil {
         log.Fatal(err)
     }
 }

docs/releasing.md

@@ -11,17 +11,17 @@ This project is configured for GoReleaser.
 
 Generate local artifacts without publishing:
 
-- goreleaser release --snapshot --clean
+- `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 tag -a v0.1.0 -m "v0.1.0"`
-   - git push origin v0.1.0
+   - `git push origin v0.1.0`
 2. Run GoReleaser:
-   - GITHUB_TOKEN=... goreleaser release --clean
+   - `GITHUB_TOKEN=... goreleaser release --clean`
 
 This will:
 - Build binaries for multiple OS/ARCH
@@ -31,4 +31,3 @@ This will:
 
 ## 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.