feat: initial release v0.1.0

This commit refactors the `stackerr` package into an open-source library
with the following changes:

- Configurable stack trace formatting (strip sequences, path replacements, max depth).
- Added `ThrowPanic` and `Recover` for robust error handling.
- Introduced `GetStack` helper and made `callStackErr` internal for better encapsulation.
- Added comprehensive unit tests and examples.
- Added GitHub Actions CI workflow.
- Added MIT License and CHANGELOG.md.
- Updated module path to `github.com/LZStock-OS/stackerr`.

Closes #1

Author: DanielLin9406

.github/workflows/go.yml

@@ -0,0 +1,25 @@
+name: Go
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.25'
+
+    - name: Build
+      run: go build -v ./...
+
+    - name: Test
+      run: go test -v ./...

.gitignore

@@ -0,0 +1,15 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-01
+
+### Added
+- Initial release of `stackerr` library.
+- `Recover` function to handle panics and wrap errors with stack traces.
+- `ThrowPanic` function to explicitly panic with a wrapped error containing the current stack trace.
+- Internal `callStackErr` type implementing `error` and `Unwrap` interface.
+- Configuration support via `stackerr.Config`:
+  - `StripSequences`: Custom strings to strip from function names (e.g., `(0`, `({`).
+  - `PathReplacements`: Custom file path cleanup (e.g., replacing `$GOPATH` with `[Proj]`).
+  - `MaxStackDepth`: Configurable stack trace depth limit (default: 10).
+  - `Output`: Configurable `io.Writer` for panic logs (default: `os.Stderr`).
+- Unit tests (`stackerr_test.go`) and usage examples (`example_test.go`).
+- GitHub Actions CI workflow for automated testing.
+- MIT License.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LZStock-OS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,109 @@
+# stackerr
+
+`stackerr` is a lightweight Go library for panic recovery and error handling with customizable stack traces. It simplifies debugging by capturing clean, readable stack traces when panics occur or when errors are explicitly thrown.
+
+## Features
+
+- **Panic Recovery**: Easily recover from panics and wrap them into errors with stack traces.
+- **Clean Stack Traces**: Automatically strips noisy arguments and simplifies file paths (e.g., replacing `$GOPATH` with `[Proj]`).
+- **Customizable**: Configure which strings to strip from function names, define custom path replacements, and set stack depth limits.
+- **Error Wrapping**: Supports standard Go error wrapping (`Unwrap()`).
+
+## Installation
+
+```bash
+go get github.com/LZStock-OS/stackerr
+```
+
+## Usage
+
+### Basic Recovery
+
+Use `stackerr.Recover` in a `defer` statement to catch panics and populate an error return variable.
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/LZStock-OS/stackerr"
+)
+
+func riskyOperation() (err error) {
+	defer stackerr.Recover(&err)
+
+	// Simulating a panic
+	panic("something went wrong")
+}
+
+func main() {
+	if err := riskyOperation(); err != nil {
+		fmt.Printf("Caught error: %v\n", err)
+		
+		if stack := stackerr.GetStack(err); stack != "" {
+			fmt.Println("Stack Trace:")
+			fmt.Println(stack)
+		}
+	}
+}
+```
+
+### Throwing Errors with Stack Traces
+
+Use `stackerr.ThrowPanic` to explicitly panic with a wrapped error containing the current stack trace.
+
+```go
+func doSomething() {
+    err := someInternalFunction()
+    if err != nil {
+        // This will panic and be caught by a defer stackerr.Recover up the chain
+        stackerr.ThrowPanic(fmt.Errorf("operation failed: %w", err))
+    }
+}
+```
+
+### Configuration
+
+You can customize the library's behavior by modifying the global `stackerr.Config` variable. It is recommended to do this in your `init()` function or main setup.
+
+```go
+import (
+    "os"
+    "github.com/LZStock-OS/stackerr"
+)
+
+func init() {
+    // Customize string sequences to strip from function names
+    stackerr.Config.StripSequences = []string{"(0", "({", "(*"}
+    
+    // Set maximum stack depth (default: 10)
+    stackerr.Config.MaxStackDepth = 20
+    
+    // Customize path replacements to hide sensitive paths or make logs shorter
+    stackerr.Config.PathReplacements = map[string]string{
+        "/home/user/go/src/": "[Src]",
+        "github.com/my/project/": "", 
+    }
+    
+    // Redirect log output (default: os.Stderr)
+    // Set to nil to disable automatic logging on recovery
+    stackerr.Config.Output = os.Stdout 
+}
+```
+
+## API Reference
+
+### `func Recover(err *error)`
+
+Catches panics, wraps them in a `callStackErr`, and assigns it to `*err`. It also logs the panic and stack trace to the configured output.
+
+### `func ThrowPanic(err error)`
+
+Wraps the given error with the current stack trace and panics. Use this when you want to abort execution but preserve context for the recovery handler.
+
+### `func GetStack(err error) string`
+Retrieves the stack trace from an error if it was created by `Recover` or `ThrowPanic`. Returns an empty string otherwise.
+
+## License
+
+MIT

example_test.go

@@ -0,0 +1,85 @@
+package stackerr_test
+
+import (
+	"errors"
+	"fmt"
+	"os"
+
+	"github.com/LZStock-OS/stackerr"
+)
+
+// ExampleRecover demonstrates how to use Recover to catch panics and wrap them with a stack trace.
+func ExampleRecover() {
+	// Disable default logging to stderr for this example to keep output clean
+	stackerr.Config.Output = nil
+	defer func() { stackerr.Config.Output = os.Stderr }() // Restore default
+
+	// Function that might panic
+	riskyFunction := func() (err error) {
+		// Defer Recover to catch panics and populate err
+		defer stackerr.Recover(&err)
+
+		// Simulating a panic
+		panic("something went wrong")
+	}
+
+	err := riskyFunction()
+	if err != nil {
+		fmt.Printf("Error caught: %v\n", err)
+		// Access the stack trace if needed
+		if stack := stackerr.GetStack(err); stack != "" {
+			fmt.Println("Stack trace captured.")
+		}
+	}
+
+	// Output:
+	// Error caught: panic: something went wrong
+	// Stack trace captured.
+}
+
+// ExampleThrowPanic demonstrates how to use ThrowPanic to panic with a stack trace.
+func ExampleThrowPanic() {
+	// Disable default logging
+	stackerr.Config.Output = nil
+	defer func() { stackerr.Config.Output = os.Stderr }()
+
+	// Function that throws a panic
+	thrower := func() (err error) {
+		defer stackerr.Recover(&err)
+		
+		// ThrowPanic wraps the error and panics
+		stackerr.ThrowPanic(errors.New("critical failure"))
+		return nil
+	}
+
+	err := thrower()
+	if err != nil {
+		fmt.Printf("Error caught: %v\n", err)
+	}
+
+	// Output:
+	// Error caught: critical failure
+}
+
+// Example_configuration demonstrates how to configure the library.
+func Example_configuration() {
+	// Configure global settings
+	stackerr.Config.StripSequences = []string{"(0", "({", "(*"}
+	stackerr.Config.MaxStackDepth = 5
+	// Disable logging for this example to avoid output mismatch
+	stackerr.Config.Output = nil
+
+	var err error
+	func() {
+		defer stackerr.Recover(&err)
+		panic("custom config panic")
+	}()
+
+	// Reset config for other tests
+	stackerr.Config.Output = os.Stderr
+	
+	fmt.Println("Done")
+	
+	// Output:
+	// Done
+}

go.mod

@@ -0,0 +1,3 @@
+module github.com/LZStock-OS/stackerr
+
+go 1.25.5