feat: initial release of Go AOC library

- Implement core functionalities for executing Advent of Code challenges.
- Add `Run` function to manage challenge execution with configurable options.
- Provide flexible I/O management through the `IOManager` interface.
- Implement automatic clipboard copying of results, with disable option.
- Document code and usage examples to resemble Go's standard library style.
- Create comprehensive README for installation, usage, and customization guidance.

.gitignore

@@ -0,0 +1,103 @@
+### Go template
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# 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/
+
+# Go workspace file
+go.work
+
+### GoLand template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+internal/**/*.txt

.golangci.yml

@@ -0,0 +1,127 @@
+run:
+  timeout: 5m
+  modules-download-mode: readonly
+  tests: false
+
+linters:
+  disable-all: true
+  enable:
+    - gofmt
+    - goimports
+    - govet
+    - errcheck
+    - gosimple
+    - ineffassign
+    - staticcheck
+    - typecheck
+    - unused
+    - asciicheck
+    - bidichk
+    - bodyclose
+    - containedctx
+    - contextcheck
+    - cyclop
+    - decorder
+    - depguard
+    - dogsled
+    - dupl
+    - durationcheck
+    - errchkjson
+    - errname
+    - errorlint
+    - copyloopvar
+    - forbidigo
+    - forcetypeassert
+    - funlen
+    - gocognit
+    - goconst
+    - gocritic
+    - gocyclo
+    - godot
+    - godox
+    - err113
+    - gofumpt
+    - goheader
+    - gomoddirectives
+    - gomodguard
+    - goprintffuncname
+    - grouper
+    - importas
+    - lll
+    - maintidx
+    - makezero
+    - misspell
+    - nakedret
+    - nestif
+    - nilerr
+    - nilnil
+    - nlreturn
+    - noctx
+    - nolintlint
+    - prealloc
+    - predeclared
+    - rowserrcheck
+    - sqlclosecheck
+    - stylecheck
+    - tagliatelle
+    - tenv
+    - testpackage
+    - thelper
+    - tparallel
+    - unconvert
+    - unparam
+    - varnamelen
+    - wastedassign
+    - whitespace
+    - wsl
+
+linters-settings:
+  lll:
+    line-length: 200
+  dogsled:
+    max-blank-identifiers: 3
+  tagliatelle:
+    case:
+      rules:
+        json: snake
+        mapstructure: snake
+  dupl:
+    ## https://github.com/golangci/golangci-lint/issues/1372 Issue
+    threshold: 250
+  funlen:
+    lines: 100
+    statements: 75
+  cyclop:
+    max-complexity: 15
+  forbidigo:
+    # Forbid the following identifiers
+    forbid:
+      - ^logger.Debug.*$ # -- forbid use of Print statements because they are likely just for debugging
+      - ^spew.Dump$ # -- forbid dumping detailed data to stdout
+      - ^ginkgo.F[A-Z].*$ # -- forbid ginkgo focused commands (used for debug issues)
+  varnamelen:
+    min-name-length: 2
+  depguard:
+    rules:
+      main:
+        allow:
+          - $gostd
+          - github.com/hvpaiva
+          - github.com/pkg/errors
+
+issues:
+  exclude-rules:
+    - path: scripts/skeleton/tmpl
+      linters:
+        - godox
+    - path: _test\.go
+      linters:
+        - funlen
+        - errchkjson
+        - goerr113
+        - dupl
+        - maintidx
+        - contextcheck
+        - goconst
+  exclude-dirs:
+    - internal/test

.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  # Go mod tidy.
+  - repo: local
+    hooks:
+      - id: go-mod-tidy
+        name: Execute go mod tidy
+        stages: [commit]
+        entry: sh -c 'go mod tidy && git add go.mod go.sum'
+        pass_filenames: false
+        always_run: true
+        language: system
+
+  # Ensure that the code is nicely formatted.
+  - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+    rev: v2.14.0
+    hooks:
+      - id: pretty-format-golang
+        args:
+          - --autofix
+
+  # Execute go linters.
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v1.60.3
+    hooks:
+      - id: golangci-lint
+        entry: golangci-lint run
+        args:
+          - --max-issues-per-linter=0
+          - --max-same-issues=0
+          - --config=.golangci.yml
+          - --allow-parallel-runners=true
+
+  # Conventional commits
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.3.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [ commit-msg ]
+        args: [ ]

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [1.0.0] - 2024-08-30
+
+### Added
+
+- Full implementation of the Go AOC library for running Advent of Code challenges.
+- Core functionality encapsulated in the `Run` function for executing challenge parts.
+- IOManager interface for handling input and output flexibly.
+- `DefaultConsoleManager` for standard console-based I/O operations.
+- Option to specify challenge parts through command-line flags, environment variables, or programmatic configuration.
+- Clipboard support to automatically copy challenge results, with an option to disable this feature.
+- Comprehensive in-code documentation to align with Go's standard library style.
+- Detailed README covering installation, basic usage, configuration options, error handling, and customization.