From f0a4617f0cf20e2aa10d2666c65bf4016ba435ab Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:37:58 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 13 + README.md | 3 + plugin.lock.json | 184 ++++++ skills/go-cli-builder/LICENSE.txt | 21 + skills/go-cli-builder/SKILL.md | 407 ++++++++++++ .../assets/templates/Makefile.template | 63 ++ .../assets/templates/ci.yml.template | 45 ++ .../assets/templates/command.go.template | 36 ++ .../assets/templates/config.go.template | 17 + .../assets/templates/config.yaml.example | 21 + .../assets/templates/constants.go.template | 12 + .../assets/templates/database.go.template | 127 ++++ .../assets/templates/default.md.template | 14 + .../assets/templates/gitignore.template | 43 ++ .../assets/templates/go.mod.template | 10 + .../assets/templates/init.go.template | 113 ++++ .../go-cli-builder/assets/templates/main.go | 7 + .../assets/templates/migrations.go.template | 73 +++ .../assets/templates/release.yml.template | 126 ++++ .../templates/rolling-release.yml.template | 135 ++++ .../assets/templates/root.go.template | 126 ++++ .../assets/templates/schema.sql.template | 24 + .../assets/templates/templates.go.template | 13 + .../assets/templates/version.go.template | 27 + .../references/cobra-viper-integration.md | 129 ++++ .../references/internal-organization.md | 231 +++++++ .../references/template-patterns.md | 410 ++++++++++++ skills/go-cli-builder/scripts/add_command.py | 78 +++ .../scripts/scaffold_project.py | 209 ++++++ .../weeknotes-blog-post-composer/.gitignore | 9 + skills/weeknotes-blog-post-composer/README.md | 186 ++++++ skills/weeknotes-blog-post-composer/SKILL.md | 603 ++++++++++++++++++ .../config/.gitkeep | 0 .../scripts/calculate-week.py | 56 ++ .../scripts/download-binaries.sh | 89 +++ .../scripts/fetch-sources.sh | 178 ++++++ .../scripts/prepare-sources.py | 102 +++ .../scripts/setup.sh | 226 +++++++ 38 files changed, 4166 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/go-cli-builder/LICENSE.txt create mode 100644 skills/go-cli-builder/SKILL.md create mode 100644 skills/go-cli-builder/assets/templates/Makefile.template create mode 100644 skills/go-cli-builder/assets/templates/ci.yml.template create mode 100644 skills/go-cli-builder/assets/templates/command.go.template create mode 100644 skills/go-cli-builder/assets/templates/config.go.template create mode 100644 skills/go-cli-builder/assets/templates/config.yaml.example create mode 100644 skills/go-cli-builder/assets/templates/constants.go.template create mode 100644 skills/go-cli-builder/assets/templates/database.go.template create mode 100644 skills/go-cli-builder/assets/templates/default.md.template create mode 100644 skills/go-cli-builder/assets/templates/gitignore.template create mode 100644 skills/go-cli-builder/assets/templates/go.mod.template create mode 100644 skills/go-cli-builder/assets/templates/init.go.template create mode 100644 skills/go-cli-builder/assets/templates/main.go create mode 100644 skills/go-cli-builder/assets/templates/migrations.go.template create mode 100644 skills/go-cli-builder/assets/templates/release.yml.template create mode 100644 skills/go-cli-builder/assets/templates/rolling-release.yml.template create mode 100644 skills/go-cli-builder/assets/templates/root.go.template create mode 100644 skills/go-cli-builder/assets/templates/schema.sql.template create mode 100644 skills/go-cli-builder/assets/templates/templates.go.template create mode 100644 skills/go-cli-builder/assets/templates/version.go.template create mode 100644 skills/go-cli-builder/references/cobra-viper-integration.md create mode 100644 skills/go-cli-builder/references/internal-organization.md create mode 100644 skills/go-cli-builder/references/template-patterns.md create mode 100755 skills/go-cli-builder/scripts/add_command.py create mode 100755 skills/go-cli-builder/scripts/scaffold_project.py create mode 100644 skills/weeknotes-blog-post-composer/.gitignore create mode 100644 skills/weeknotes-blog-post-composer/README.md create mode 100644 skills/weeknotes-blog-post-composer/SKILL.md create mode 100644 skills/weeknotes-blog-post-composer/config/.gitkeep create mode 100755 skills/weeknotes-blog-post-composer/scripts/calculate-week.py create mode 100755 skills/weeknotes-blog-post-composer/scripts/download-binaries.sh create mode 100755 skills/weeknotes-blog-post-composer/scripts/fetch-sources.sh create mode 100755 skills/weeknotes-blog-post-composer/scripts/prepare-sources.py create mode 100755 skills/weeknotes-blog-post-composer/scripts/setup.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9790226 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "lmorchard-agent-skills", + "description": "Collection of miscellaneous skills built by lmorchard", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Les Orchard", + "email": "me@lmorchard.com" + }, + "skills": [ + "./skills/go-cli-builder", + "./skills/weeknotes-blog-post-composer" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..ff879a0 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# lmorchard-agent-skills + +Collection of miscellaneous skills built by lmorchard diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5163c5c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,184 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:lmorchard/lmorchard-agent-skills:lmorchard-agent-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "6e3d0a03e78a8f42719ef7f4782db093b49e6da9", + "treeHash": "a9e0a4cd8498144314f4b93bae64934cd8ea9b9f944415c72309511bab7b1a5c", + "generatedAt": "2025-11-28T10:20:21.017448Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "lmorchard-agent-skills", + "description": "Collection of miscellaneous skills built by lmorchard" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "407b60eeba7c49bce52a7b58b2abc7dd96743177ad396470656135c9f438ec8f" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "9e4672ae872b40e29473436fed803fe6fdc34cb2515a5025dbaa825bd32d612e" + }, + { + "path": "skills/weeknotes-blog-post-composer/README.md", + "sha256": "4a3366e12b8947969d3006254dc54e79a8519962329efee2c6aaf9f1563241ed" + }, + { + "path": "skills/weeknotes-blog-post-composer/.gitignore", + "sha256": "13a44b4fd25e4bc8e32bf1b8a656300d3b30d0c744455b395a40744d5737cc95" + }, + { + "path": "skills/weeknotes-blog-post-composer/SKILL.md", + "sha256": "bd26128f9c588e7672dda5d10f0979a6eaeab967ab24d4d993e3afb3eb3c80a5" + }, + { + "path": "skills/weeknotes-blog-post-composer/config/.gitkeep", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "skills/weeknotes-blog-post-composer/scripts/setup.sh", + "sha256": "27d4edeaea43a14217251e92051c6de70a5481945fb16e1e20e74debc7393887" + }, + { + "path": "skills/weeknotes-blog-post-composer/scripts/prepare-sources.py", + "sha256": "87d0b811086023c78019c04ca19e11c59c588918a0f8e21da9b781b8e6c3211b" + }, + { + "path": "skills/weeknotes-blog-post-composer/scripts/calculate-week.py", + "sha256": "33b998d9bdcd6981d9b00e8526f498768e833ad2a2c3e3bd49fec29c7d27c5cd" + }, + { + "path": "skills/weeknotes-blog-post-composer/scripts/download-binaries.sh", + "sha256": "3f90bc5f7c01f66b30c66e72287d9e8070afcf890c93d89ba0da192d1a181a61" + }, + { + "path": "skills/weeknotes-blog-post-composer/scripts/fetch-sources.sh", + "sha256": "76d3628a65f089c3b6f0e28f0d8f69e3701a12a642369ba97d9192a16700163c" + }, + { + "path": "skills/weeknotes-blog-post-composer/data/.gitkeep", + "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" + }, + { + "path": "skills/go-cli-builder/SKILL.md", + "sha256": "f061342f9e9605a9eb80df609c089ea05fe0d11678dd50516fbc7a9d4912a09d" + }, + { + "path": "skills/go-cli-builder/LICENSE.txt", + "sha256": "937358f72515cd09b0121939ef09d4efa4219caa94bda9ba3462d38ee4ca254d" + }, + { + "path": "skills/go-cli-builder/references/internal-organization.md", + "sha256": "556a8677b07d2376a74757a597a438e13bbc98ad622d7bbd229ffd1b8511265f" + }, + { + "path": "skills/go-cli-builder/references/template-patterns.md", + "sha256": "1a54e6a2fcc3210ff39dd30fb786ced716e0248ee9ace2239d99d067e34da34e" + }, + { + "path": "skills/go-cli-builder/references/cobra-viper-integration.md", + "sha256": "af9f0637228be636e06395004feccac264981822de71ebcf7dc9facd29184ae1" + }, + { + "path": "skills/go-cli-builder/scripts/scaffold_project.py", + "sha256": "a4bc549db26220f9a5163921cddeb5290bef1def36961a03530825a348b8ecb2" + }, + { + "path": "skills/go-cli-builder/scripts/add_command.py", + "sha256": "1dc693ad5585ef56d36310e50d13ce1b6dc2d04a362756e8d3c0da047cc7833b" + }, + { + "path": "skills/go-cli-builder/assets/templates/config.yaml.example", + "sha256": "f2b46f6c933b68b23f89b6ab721cf41bf01119a1070bf9b322bc7e9ff39817a9" + }, + { + "path": "skills/go-cli-builder/assets/templates/ci.yml.template", + "sha256": "14cd2640e4db644f9c179d1788717270d1863872049831c05ff8478e69cae8c1" + }, + { + "path": "skills/go-cli-builder/assets/templates/default.md.template", + "sha256": "9ca570e3b5d4f70ca0188061f4af38dcda8dd52e5159e1ac5fcaee571e6b9eec" + }, + { + "path": "skills/go-cli-builder/assets/templates/go.mod.template", + "sha256": "84ca89406c806ae810ea2e4e8c8e89fd86c26cf52967a339aa78d219b23ced30" + }, + { + "path": "skills/go-cli-builder/assets/templates/Makefile.template", + "sha256": "53347ee4231da1242fb7abc0ffdf6619008559dab33939ae1961f5c5a35e84e9" + }, + { + "path": "skills/go-cli-builder/assets/templates/schema.sql.template", + "sha256": "624576312915a59c51a3f389ae994276a5b4a88a34a8a2e1e767214c6366dcfb" + }, + { + "path": "skills/go-cli-builder/assets/templates/config.go.template", + "sha256": "d36d201cb9ec8f56d3bde606bc9512051746f9d6f20ad964a0bab62fa6b5a995" + }, + { + "path": "skills/go-cli-builder/assets/templates/constants.go.template", + "sha256": "7b86999b9e1e75195ee88e1607cde18e679831ae8a12488563fb447788c0d94b" + }, + { + "path": "skills/go-cli-builder/assets/templates/gitignore.template", + "sha256": "b72b2196674e6bb473cbcb5b82072d0e793ea3236ee92b95aec572ec34e8a205" + }, + { + "path": "skills/go-cli-builder/assets/templates/database.go.template", + "sha256": "a338acec75b539445b1b96a279abb1e15c8ae02d40ceb7f241a59051f651a932" + }, + { + "path": "skills/go-cli-builder/assets/templates/migrations.go.template", + "sha256": "b6652ce52524887de447b1d6c5e66a4e2e65081ab42aa25ac274ed175cbc962a" + }, + { + "path": "skills/go-cli-builder/assets/templates/release.yml.template", + "sha256": "b097c216edb6953444f759dd29089b4c8631f968cfbb09f65783b6660885dc94" + }, + { + "path": "skills/go-cli-builder/assets/templates/init.go.template", + "sha256": "e06cdb7dcfb4a92d0a296ed038d311bd0189a2e43cb508f77ce8d43526ca1422" + }, + { + "path": "skills/go-cli-builder/assets/templates/version.go.template", + "sha256": "82c6edf682d26fd0f9cf2c48cba4b4e5cfe6387ebb6453a4237c7c3bc8ed83c8" + }, + { + "path": "skills/go-cli-builder/assets/templates/root.go.template", + "sha256": "0633b8076216872f0dca91082bc20f36031e59bf0a320a0c85988ec7996dbea2" + }, + { + "path": "skills/go-cli-builder/assets/templates/templates.go.template", + "sha256": "4d86b2fd86aa4e75e8aeea8f12f7e08a4d792e7a007df7eabfc8dea324427190" + }, + { + "path": "skills/go-cli-builder/assets/templates/command.go.template", + "sha256": "3e056822e69526ec047906b8de0e3e317fed67c84e03a7d9d406853e64d5abb0" + }, + { + "path": "skills/go-cli-builder/assets/templates/rolling-release.yml.template", + "sha256": "5f0042679cc0ba27a65662fe788c90f7f0a3dd6192921ce2bdd968299fdc7b74" + }, + { + "path": "skills/go-cli-builder/assets/templates/main.go", + "sha256": "f1dab0b7821efce75ace34908072b80e8b27783315992450ece53e86ce15feff" + } + ], + "dirSha256": "a9e0a4cd8498144314f4b93bae64934cd8ea9b9f944415c72309511bab7b1a5c" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/go-cli-builder/LICENSE.txt b/skills/go-cli-builder/LICENSE.txt new file mode 100644 index 0000000..cfc930b --- /dev/null +++ b/skills/go-cli-builder/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Les Orchard + +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. diff --git a/skills/go-cli-builder/SKILL.md b/skills/go-cli-builder/SKILL.md new file mode 100644 index 0000000..ca91ca7 --- /dev/null +++ b/skills/go-cli-builder/SKILL.md @@ -0,0 +1,407 @@ +--- +name: go-cli-builder +description: Build Go-based command-line tools following established patterns with Cobra CLI framework, Viper configuration, SQLite database, and automated GitHub Actions workflows for releases. Use when creating new Go CLI projects or adding features to existing ones that follow the Cobra/Viper/SQLite stack. +--- + +# Go CLI Builder + +## Overview + +This skill provides templates, scripts, and patterns for building production-ready Go command-line tools. It follows established patterns from projects like feedspool-go, feed-to-mastodon, and linkding-to-opml. + +The skill generates projects with: +- **Cobra** for CLI framework +- **Viper** for configuration management (YAML files with CLI overrides) +- **SQLite** with a naive migration system +- **Logrus** for structured logging +- **Makefile** for common tasks (lint, format, test, build) +- **GitHub Actions** workflows for CI, tagged releases, and rolling releases +- Strict code formatting with gofumpt and linting with golangci-lint + +## When to Use This Skill + +Use this skill when: +- Creating a new Go CLI tool from scratch +- Adding commands to an existing Go CLI project that follows these patterns +- Needing reference material about Cobra/Viper integration +- Setting up GitHub Actions workflows for multi-platform Go releases + +Example user requests: +- "Create a new Go CLI tool called feed-analyzer" +- "Scaffold a Go project for processing log files" +- "Add a new 'export' command to my Go CLI project" +- "Help me set up GitHub Actions for releasing my Go tool" + +## Quick Start + +### Creating a New Project + +To scaffold a complete new project: + +```bash +# With database support (default) +python scripts/scaffold_project.py my-cli-tool + +# Without database support +python scripts/scaffold_project.py my-cli-tool --no-database + +# With template support for generating output +python scripts/scaffold_project.py my-cli-tool --templates + +# Combining options +python scripts/scaffold_project.py my-cli-tool --no-database --templates +``` + +**Project Options:** + +- **Database Support** (default: included) + - Includes SQLite with migrations system + - Use `--no-database` to exclude if you don't need persistent storage + - Examples: CLI tools that only fetch/transform data, API clients + +- **Template Support** (default: excluded) + - Includes embedded template system with init command + - Use `--templates` to include for tools that generate formatted output + - Examples: Markdown generators, OPML exporters, report generators + +**What gets created:** + +Base structure (always): +- Entry point (`main.go`) +- Root command with Cobra/Viper integration (`cmd/root.go`) +- Version command (`cmd/version.go`) +- Configuration system (`internal/config/`) +- Makefile with standard targets +- GitHub Actions workflows (CI, release, rolling-release) + +Optional additions: +- Database layer with migrations (`internal/database/`) - if database enabled +- Template system (`internal/templates/`, `cmd/init.go`) - if templates enabled + +**Next steps after scaffolding:** +1. Update `go.mod` with the actual module name +2. Customize the example config file +3. If using database: Define initial schema in `internal/database/schema.sql` +4. Run `make setup` to install development tools +5. Run `go mod tidy` to download dependencies + +### Adding Commands to Existing Projects + +To add a new command to an existing project: + +```bash +python scripts/add_command.py fetch +``` + +This creates `cmd/fetch.go` with: +- Command boilerplate +- Access to logger and config +- Flag binding examples +- TODO comments for implementation + +## Project Structure + +Generated projects follow this structure: + +``` +my-cli-tool/ +├── main.go # Entry point +├── go.mod # Dependencies +├── Makefile # Build automation +├── my-cli-tool.yaml.example # Example configuration +├── cmd/ # Command definitions +│ ├── root.go # Root command + Cobra/Viper setup +│ ├── version.go # Version command +│ ├── constants.go # Application constants +│ └── [command].go # Individual commands +├── internal/ +│ ├── config/ +│ │ └── config.go # Configuration struct +│ ├── database/ +│ │ ├── database.go # Connection + initialization +│ │ ├── migrations.go # Migration system +│ │ └── schema.sql # Initial schema (embedded) +│ └── templates/ # Optional: For tools that generate output +│ ├── templates.go # Embedded template loader +│ └── default.md # Default template (embedded) +└── .github/workflows/ + ├── ci.yml # PR linting and testing + ├── release.yml # Tagged releases + └── rolling-release.yml # Main branch rolling releases +``` + +## Configuration System + +Projects use a three-tier configuration hierarchy: + +1. **Config file** (`my-tool.yaml`): Base configuration in YAML +2. **Environment variables**: Automatic via Viper +3. **CLI flags**: Override everything + +See `references/cobra-viper-integration.md` for detailed patterns on: +- Binding flags to Viper keys +- Adding new configuration options +- Command-specific vs. global configuration +- Environment variable mapping + +## Database Layer + +The generated database layer includes: + +1. **Initial schema** (`internal/database/schema.sql`): Embedded SQL for first-time setup +2. **Migration tracking**: `schema_migrations` table tracks applied versions +3. **Migration execution**: Automatic on database initialization +4. **Idempotent operations**: Safe to run multiple times + +**To add a new migration:** + +1. Edit `internal/database/migrations.go` +2. Add to the `getMigrations()` map with the next version number: + ```go + func getMigrations() map[int]string { + return map[int]string{ + 2: `CREATE TABLE IF NOT EXISTS settings ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL + );`, + } + } + ``` +3. Migrations run automatically on next database initialization + +## Init Command Pattern + +For tools that generate output files (markdown, OPML, etc.), the `init` command pattern provides a great user experience by generating both configuration and customizable templates. + +### When to Use Init Command + +Use the init command when your CLI tool: +- Generates formatted output (markdown, HTML, XML, etc.) +- Benefits from user-customizable templates +- Has configuration that users need to set up before first use + +### Init Command Components + +**Available templates:** +- `init.go.template` - Complete init command implementation +- `templates.go.template` - Template loader with embedded default +- `default.md.template` - Example embedded markdown template + +**The init command:** +1. Creates a YAML configuration file with all options documented +2. Creates a customizable template file (using embedded default) +3. Supports `--force` flag to overwrite existing files +4. Supports `--template-file` flag to specify custom template filename +5. Provides helpful next steps after initialization + +### Embedded Templates + +Go's `//go:embed` directive allows embedding template files directly in the binary: + +```go +package templates + +import ( + _ "embed" +) + +//go:embed default.md +var defaultTemplate string + +func GetDefaultTemplate() (string, error) { + return defaultTemplate, nil +} +``` + +**Benefits:** +- Single binary distribution (no external template files needed) +- Users can still customize by running `init` to get a copy +- Template always available as fallback + +### Integration with Other Commands + +Commands that generate output should support both: +1. **Built-in template** (default) - uses embedded template +2. **Custom template** (via `--template` flag or config) - loads from file + +Example pattern: +```go +templatePath := viper.GetString("command.template") +var generator *Generator +if templatePath != "" { + generator, err = NewGeneratorFromFile(templatePath) +} else { + generator, err = NewGenerator() // uses embedded default +} +``` + +### Example Projects Using This Pattern + +- `linkding-to-markdown` - Fetches bookmarks and generates markdown +- `mastodon-to-markdown` - Exports Mastodon posts to markdown + +## Makefile Targets + +All generated projects include these targets: + +- `make setup`: Install development tools (gofumpt, golangci-lint) +- `make build`: Build the binary with version information +- `make run`: Build and run the application +- `make lint`: Run golangci-lint +- `make format`: Format code with go fmt and gofumpt +- `make test`: Run tests with race detection +- `make clean`: Remove build artifacts + +## GitHub Actions Workflows + +Three workflows are included: + +### 1. CI (`ci.yml`) +- **Triggers**: Pull requests to main, manual workflow calls +- **Actions**: Lint with golangci-lint, test with race detection +- **Skip**: Commits starting with `[noci]` + +### 2. Release (`release.yml`) +- **Triggers**: Tags matching `v*` (e.g., `v1.0.0`) +- **Platforms**: Linux (amd64, arm64), macOS (amd64, arm64), Windows (amd64) +- **Outputs**: Compressed binaries, checksums, GitHub release +- **Docker**: Optional (commented out by default) + +### 3. Rolling Release (`rolling-release.yml`) +- **Triggers**: Pushes to main branch +- **Actions**: Same as Release but creates a "latest" prerelease +- **Purpose**: Testing builds from the latest commit + +**To customize:** +- Update Docker Hub username in workflows if using Docker +- Adjust Go version if needed (default: 1.21) +- Modify build matrix to add/remove platforms + +## Typical Workflow + +### Starting a New Project + +1. Use this skill to scaffold the project +2. Customize the initial schema in `internal/database/schema.sql` +3. Update configuration struct in `internal/config/config.go` +4. Add domain-specific packages in `internal/` (see `references/internal-organization.md`) +5. Add commands using the add_command script +6. Implement command logic, calling into `internal/` packages + +### Adding a Feature + +1. Determine if it needs a new command or extends existing one +2. If new command: use `add_command.py` script +3. Add any required configuration to config struct and root flags +4. Implement logic in `internal/` packages +5. Update command to call the internal logic +6. Add tests +7. Run `make format && make lint && make test` + +## Reference Documentation + +For detailed patterns and guidelines, refer to: + +- **`references/cobra-viper-integration.md`**: Complete guide to configuration system + - Flag binding patterns + - Adding new configuration options + - Environment variable mapping + - Best practices + +- **`references/internal-organization.md`**: Internal package structure + - Package organization principles + - Dependency rules + - Common patterns (Option pattern, error wrapping) + - When to create new packages + +- **`references/template-patterns.md`**: Template-based output generation + - When and how to use embedded templates + - Init command implementation + - Generator/renderer patterns + - Template functions and testing + - User workflow and best practices + +## Templates Available + +All templates are in `assets/templates/`: + +**Core Files:** +- `main.go`: Minimal entry point +- `go.mod.template`: Pre-configured dependencies +- `Makefile.template`: Standard build targets +- `gitignore.template`: Go-specific ignores +- `config.yaml.example`: Example configuration + +**Commands:** +- `root.go.template`: Cobra/Viper integration +- `version.go.template`: Version command +- `constants.go.template`: Application constants +- `command.go.template`: New command template +- `init.go.template`: Init command for config/template generation + +**Internal Packages:** +- `config.go.template`: Configuration struct +- `database.go.template`: Database layer +- `migrations.go.template`: Migration system +- `schema.sql.template`: Initial schema +- `templates.go.template`: Embedded template loader +- `default.md.template`: Example embedded template + +**CI/CD:** +- `ci.yml.template`: CI workflow +- `release.yml.template`: Release workflow +- `rolling-release.yml.template`: Rolling release workflow + +## Best Practices + +1. **Keep commands thin**: Business logic belongs in `internal/` packages +2. **Use the config struct**: Access configuration through `GetConfig()` rather than calling Viper directly +3. **Wrap errors**: Always add context with `fmt.Errorf("context: %w", err)` +4. **Format before committing**: Run `make format && make lint` +5. **Test with race detection**: `go test -race ./...` +6. **Version your releases**: Use semantic versioning tags (v1.0.0, v1.1.0, etc.) +7. **Document in .yaml.example**: Keep example config updated +8. **Handle errors explicitly**: Use `_ = ` for intentionally ignored errors (e.g., `_ = viper.BindPFlag(...)`) +9. **Defer cleanup safely**: Use `defer func() { _ = tx.Rollback() }()` instead of `defer tx.Rollback()` to avoid linter warnings + +## Common Customizations + +After scaffolding, projects typically need: + +1. **Module name update**: Change `github.com/yourusername/project` in `go.mod` to actual path +2. **Additional dependencies**: Add with `go get` and run `go mod tidy` +3. **Custom schema**: Define tables in `internal/database/schema.sql` +4. **Domain packages**: Create packages in `internal/` for business logic +5. **Command implementations**: Fill in the TODOs in command files +6. **Docker configuration**: Uncomment Docker sections in workflows if needed + +## Recent Improvements + +### Linter Compliance (2025-11-11) + +- **Fixed viper.BindPFlag warnings**: All `viper.BindPFlag()` calls now use `_ = ` prefix to explicitly ignore errors, satisfying the `errcheck` linter +- **Fixed defer Rollback warnings**: Database transaction cleanup now uses `defer func() { _ = tx.Rollback() }()` pattern +- **Removed static linking**: Removed `-linkmode external -extldflags "-static"` flags from Makefile to eliminate getaddrinfo warnings when using CGO with SQLite +- **Updated templates**: All templates now generate linter-clean code out of the box + +These changes ensure that projects scaffolded with this skill pass `golangci-lint` without warnings. + +## Troubleshooting + +**"gofumpt not found" or "golangci-lint not found"** +- Run `make setup` to install development tools + +**"Failed to initialize schema"** +- Check database file path and permissions +- Ensure directory exists or is creatable + +**"Missing migration for version N"** +- Migrations must be sequential; add any missing versions + +**"getaddrinfo warning during build"** +- This warning has been resolved in recent versions by removing static linking flags +- If you see this in an older project, remove the static linking lines from your Makefile (see Recent Improvements section) + +**GitHub Actions failing on cross-compilation** +- Ensure CGO is enabled for SQLite +- Linux ARM64 builds require cross-compilation tools (handled in workflow) diff --git a/skills/go-cli-builder/assets/templates/Makefile.template b/skills/go-cli-builder/assets/templates/Makefile.template new file mode 100644 index 0000000..30d6545 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/Makefile.template @@ -0,0 +1,63 @@ +.PHONY: setup build run clean lint format test + +# Build variables +VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev") +COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown") +BUILD_DATE := $(shell date -u +"%Y-%m-%dT%H:%M:%SZ") +LDFLAGS := -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(BUILD_DATE) + +# Note: Static linking is not used because SQLite requires CGO, which links dynamically +# to system libraries. Attempting static linking causes getaddrinfo warnings and +# potential runtime compatibility issues. + +# Default target +all: build + +# Install development tools +setup: + @echo "Installing development tools..." + @go install mvdan.cc/gofumpt@latest + @go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest + @echo "✅ Development tools installed" + +# Build the application +build: + @echo "Building {{PROJECT_NAME}}..." + @CGO_ENABLED=1 go build -ldflags "$(LDFLAGS)" -o {{PROJECT_NAME}} . + @echo "✅ Built: {{PROJECT_NAME}}" + +# Run the application +run: build + ./{{PROJECT_NAME}} + +# Clean build artifacts +clean: + @rm -f {{PROJECT_NAME}} + @rm -f *.db + @echo "✅ Cleaned" + +# Lint code +lint: + @test -f $(HOME)/go/bin/golangci-lint || { \ + echo "❌ golangci-lint not found. Install with: make setup"; \ + exit 1; \ + } + @echo "Running linters..." + @$(HOME)/go/bin/golangci-lint run --timeout 5m + @echo "✅ Lint complete" + +# Format code +format: + @go fmt ./... + @test -f $(HOME)/go/bin/gofumpt || { \ + echo "❌ gofumpt not found. Install with: make setup"; \ + exit 1; \ + } + @$(HOME)/go/bin/gofumpt -l -w . + @echo "✅ Format complete" + +# Run tests +test: + @echo "Running tests..." + @go test ./... + @echo "✅ Tests complete" diff --git a/skills/go-cli-builder/assets/templates/ci.yml.template b/skills/go-cli-builder/assets/templates/ci.yml.template new file mode 100644 index 0000000..832b472 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/ci.yml.template @@ -0,0 +1,45 @@ +name: CI + +on: + pull_request: + branches: [ main ] + workflow_call: + +jobs: + lint-test: + name: CI (Lint, Test) + runs-on: ubuntu-latest + steps: + - name: Check for [noci] in commit message + id: check_commit + run: | + if [[ "${{ github.event.head_commit.message }}" == "[noci]"* ]]; then + echo "skip=true" >> $GITHUB_OUTPUT + else + echo "skip=false" >> $GITHUB_OUTPUT + fi + + - name: Checkout code + if: steps.check_commit.outputs.skip != 'true' + uses: actions/checkout@v4 + + - name: Set up Go + if: steps.check_commit.outputs.skip != 'true' + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Download dependencies + if: steps.check_commit.outputs.skip != 'true' + run: go mod download + + - name: Run golangci-lint + if: steps.check_commit.outputs.skip != 'true' + uses: golangci/golangci-lint-action@v6 + with: + version: latest + args: --timeout=5m + + - name: Run tests + if: steps.check_commit.outputs.skip != 'true' + run: go test -race ./... diff --git a/skills/go-cli-builder/assets/templates/command.go.template b/skills/go-cli-builder/assets/templates/command.go.template new file mode 100644 index 0000000..222c7b0 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/command.go.template @@ -0,0 +1,36 @@ +package cmd + +import ( + "github.com/spf13/cobra" + "github.com/spf13/viper" +) + +// {{COMMAND_NAME}}Cmd represents the {{COMMAND_NAME}} command +var {{COMMAND_NAME}}Cmd = &cobra.Command{ + Use: "{{COMMAND_NAME}}", + Short: "A brief description of the {{COMMAND_NAME}} command", + Long: `A longer description of the {{COMMAND_NAME}} command that explains +what it does and how to use it. + +Example usage: + {{PROJECT_NAME}} {{COMMAND_NAME}} [flags]`, + RunE: func(cmd *cobra.Command, args []string) error { + log := GetLogger() + cfg := GetConfig() + + log.Info("Running {{COMMAND_NAME}} command") + + // TODO: Implement command logic here + + return nil + }, +} + +func init() { + rootCmd.AddCommand({{COMMAND_NAME}}Cmd) + + // Add command-specific flags here + // Example: + // {{COMMAND_NAME}}Cmd.Flags().StringP("option", "o", "", "An option for this command") + // _ = viper.BindPFlag("{{COMMAND_NAME}}.option", {{COMMAND_NAME}}Cmd.Flags().Lookup("option")) +} diff --git a/skills/go-cli-builder/assets/templates/config.go.template b/skills/go-cli-builder/assets/templates/config.go.template new file mode 100644 index 0000000..c6fbdd6 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/config.go.template @@ -0,0 +1,17 @@ +package config + +// Config holds application configuration +type Config struct { + // Core settings + Database string + Verbose bool + Debug bool + LogJSON bool + + // Add command-specific configuration fields here as needed + // Example: + // Fetch struct { + // Concurrency int + // Timeout time.Duration + // } +} diff --git a/skills/go-cli-builder/assets/templates/config.yaml.example b/skills/go-cli-builder/assets/templates/config.yaml.example new file mode 100644 index 0000000..6a42143 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/config.yaml.example @@ -0,0 +1,21 @@ +# Configuration file for {{PROJECT_NAME}} +# Copy this to {{PROJECT_NAME}}.yaml and customize as needed + +# Database configuration +database: "{{PROJECT_NAME}}.db" + +# Logging configuration +verbose: false +debug: false +log_json: false + +# Example command-specific configuration +# Uncomment and customize as needed for your commands +# +# fetch: +# concurrency: 10 +# timeout: 30s +# +# serve: +# port: 8080 +# host: "localhost" diff --git a/skills/go-cli-builder/assets/templates/constants.go.template b/skills/go-cli-builder/assets/templates/constants.go.template new file mode 100644 index 0000000..705b250 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/constants.go.template @@ -0,0 +1,12 @@ +package cmd + +// Application constants and defaults +const ( + // DefaultDatabasePath is the default database file path + DefaultDatabasePath = "{{PROJECT_NAME}}.db" + + // DefaultConcurrency is the default number of concurrent operations + DefaultConcurrency = 10 + + // Add other application constants here +) diff --git a/skills/go-cli-builder/assets/templates/database.go.template b/skills/go-cli-builder/assets/templates/database.go.template new file mode 100644 index 0000000..e767168 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/database.go.template @@ -0,0 +1,127 @@ +package database + +import ( + "database/sql" + _ "embed" + "fmt" + "os" + "path/filepath" + + _ "github.com/mattn/go-sqlite3" +) + +//go:embed schema.sql +var schemaSQL string + +// DB wraps a SQLite database connection +type DB struct { + conn *sql.DB +} + +// New creates and initializes a new database connection +func New(dbPath string) (*DB, error) { + // Ensure directory exists + dir := filepath.Dir(dbPath) + if dir != "." && dir != "/" { + if err := os.MkdirAll(dir, 0755); err != nil { + return nil, fmt.Errorf("failed to create database directory: %w", err) + } + } + + // Open database connection + conn, err := sql.Open("sqlite3", fmt.Sprintf("%s?_foreign_keys=ON&_journal_mode=WAL", dbPath)) + if err != nil { + return nil, fmt.Errorf("failed to open database: %w", err) + } + + // Set connection pool limits (SQLite works best with limited concurrency) + conn.SetMaxOpenConns(1) + conn.SetMaxIdleConns(1) + + db := &DB{conn: conn} + + // Initialize schema and run migrations + if err := db.InitSchema(); err != nil { + conn.Close() + return nil, fmt.Errorf("failed to initialize schema: %w", err) + } + + if err := db.RunMigrations(); err != nil { + conn.Close() + return nil, fmt.Errorf("failed to run migrations: %w", err) + } + + return db, nil +} + +// Close closes the database connection +func (db *DB) Close() error { + if db.conn != nil { + return db.conn.Close() + } + return nil +} + +// InitSchema creates the initial database schema +func (db *DB) InitSchema() error { + _, err := db.conn.Exec(schemaSQL) + if err != nil { + return fmt.Errorf("failed to execute schema: %w", err) + } + return nil +} + +// IsInitialized checks if the database has been initialized +func (db *DB) IsInitialized() (bool, error) { + // Check if schema_migrations table exists + var count int + err := db.conn.QueryRow(` + SELECT COUNT(*) + FROM sqlite_master + WHERE type='table' AND name='schema_migrations' + `).Scan(&count) + + if err != nil { + return false, fmt.Errorf("failed to check initialization: %w", err) + } + + return count > 0, nil +} + +// GetMigrationVersion returns the current migration version +func (db *DB) GetMigrationVersion() (int, error) { + var version int + err := db.conn.QueryRow("SELECT COALESCE(MAX(version), 0) FROM schema_migrations").Scan(&version) + if err != nil { + return 0, fmt.Errorf("failed to get migration version: %w", err) + } + return version, nil +} + +// ApplyMigration applies a specific migration +func (db *DB) ApplyMigration(version int, sql string) error { + tx, err := db.conn.Begin() + if err != nil { + return fmt.Errorf("failed to begin transaction: %w", err) + } + defer func() { _ = tx.Rollback() }() + + // Execute migration SQL + if _, err := tx.Exec(sql); err != nil { + return fmt.Errorf("failed to execute migration %d: %w", version, err) + } + + // Record migration + if _, err := tx.Exec( + "INSERT INTO schema_migrations (version) VALUES (?)", + version, + ); err != nil { + return fmt.Errorf("failed to record migration %d: %w", version, err) + } + + if err := tx.Commit(); err != nil { + return fmt.Errorf("failed to commit migration %d: %w", version, err) + } + + return nil +} diff --git a/skills/go-cli-builder/assets/templates/default.md.template b/skills/go-cli-builder/assets/templates/default.md.template new file mode 100644 index 0000000..968ed05 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/default.md.template @@ -0,0 +1,14 @@ +# {{"{{"}} .Title {{"}}"}} + +_Generated: {{"{{"}} .Generated {{"}}"}}_ + +--- + +{{"{{"}} range .Items -{{"}}"}} +## {{"{{"}} .Name {{"}}"}} + +{{"{{"}} .Description {{"}}"}} + +--- + +{{"{{"}} end -{{"}}"}} diff --git a/skills/go-cli-builder/assets/templates/gitignore.template b/skills/go-cli-builder/assets/templates/gitignore.template new file mode 100644 index 0000000..431aa2a --- /dev/null +++ b/skills/go-cli-builder/assets/templates/gitignore.template @@ -0,0 +1,43 @@ +# Binaries for programs and plugins +*.exe +*.exe~ +*.dll +*.so +*.dylib +{{PROJECT_NAME}} + +# Test binary, built with `go test -c` +*.test + +# Output of the go coverage tool +*.out + +# Dependency directories +vendor/ + +# Go workspace file +go.work + +# IDEs +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS files +.DS_Store +Thumbs.db + +# Database files +*.db +*.sqlite +*.sqlite3 + +# Config files (keep examples) +*.yaml +!*.yaml.example + +# Build artifacts +build/ +dist/ diff --git a/skills/go-cli-builder/assets/templates/go.mod.template b/skills/go-cli-builder/assets/templates/go.mod.template new file mode 100644 index 0000000..9796c77 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/go.mod.template @@ -0,0 +1,10 @@ +module {{MODULE_NAME}} + +go 1.21 + +require ( + github.com/mattn/go-sqlite3 v1.14.32 + github.com/sirupsen/logrus v1.9.3 + github.com/spf13/cobra v1.9.1 + github.com/spf13/viper v1.20.1 +) diff --git a/skills/go-cli-builder/assets/templates/init.go.template b/skills/go-cli-builder/assets/templates/init.go.template new file mode 100644 index 0000000..9412fad --- /dev/null +++ b/skills/go-cli-builder/assets/templates/init.go.template @@ -0,0 +1,113 @@ +package cmd + +import ( + "fmt" + "os" + + "{{.ModuleName}}/internal/templates" + "github.com/spf13/cobra" +) + +const defaultConfigContent = `# Configuration file for {{.ProjectName}} +# Copy this to {{.ProjectName}}.yaml and customize as needed + +# Database configuration +database: "{{.ProjectName}}.db" + +# Logging configuration +verbose: false +debug: false +log_json: false + +# Add your application-specific configuration here +# Example: +# myapp: +# api_url: "https://api.example.com" +# api_token: "your-token-here" +# timeout: 30s +` + +// initCmd represents the init command +var initCmd = &cobra.Command{ + Use: "init", + Short: "Initialize configuration and template files", + Long: ` + "`" + `Create default configuration file and custom template file for customization. + +This command generates: + - {{.ProjectName}}.yaml (configuration file) + - {{.ProjectName}}.md (customizable template, or use --template-file to specify) + +Use --force to overwrite existing files. + +Example: + {{.ProjectName}} init + {{.ProjectName}} init --template-file my-template.md + {{.ProjectName}} init --force` + "`" + `, + RunE: func(cmd *cobra.Command, args []string) error { + log := GetLogger() + force, _ := cmd.Flags().GetBool("force") + templateFile, _ := cmd.Flags().GetString("template-file") + + configFile := "{{.ProjectName}}.yaml" + + // Check if config file exists + configExists := fileExists(configFile) + if configExists && !force { + return fmt.Errorf("config file %s already exists (use --force to overwrite)", configFile) + } + + // Check if template file exists + templateExists := fileExists(templateFile) + if templateExists && !force { + return fmt.Errorf("template file %s already exists (use --force to overwrite)", templateFile) + } + + // Create config file + if err := os.WriteFile(configFile, []byte(defaultConfigContent), 0o644); err != nil { + return fmt.Errorf("failed to create config file: %w", err) + } + + if configExists { + log.Infof("Overwrote %s", configFile) + } else { + log.Infof("Created %s", configFile) + } + + // Get default template content + templateContent, err := templates.GetDefaultTemplate() + if err != nil { + return fmt.Errorf("failed to get default template: %w", err) + } + + // Create template file + if err := os.WriteFile(templateFile, []byte(templateContent), 0o644); err != nil { + return fmt.Errorf("failed to create template file: %w", err) + } + + if templateExists { + log.Infof("Overwrote %s", templateFile) + } else { + log.Infof("Created %s", templateFile) + } + + fmt.Printf("\n✅ Initialization complete!\n\n") + fmt.Printf("Next steps:\n") + fmt.Printf(" 1. Edit %s and add your configuration\n", configFile) + fmt.Printf(" 2. (Optional) Customize %s for your preferred output format\n", templateFile) + fmt.Printf(" 3. Run: {{.ProjectName}} --help for usage information\n\n") + + return nil + }, +} + +func init() { + rootCmd.AddCommand(initCmd) + initCmd.Flags().Bool("force", false, "Overwrite existing files") + initCmd.Flags().String("template-file", "{{.ProjectName}}.md", "Name of custom template file to create") +} + +// fileExists checks if a file exists +func fileExists(path string) bool { + _, err := os.Stat(path) + return err == nil +} diff --git a/skills/go-cli-builder/assets/templates/main.go b/skills/go-cli-builder/assets/templates/main.go new file mode 100644 index 0000000..91b92d1 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/main.go @@ -0,0 +1,7 @@ +package main + +import "{{MODULE_NAME}}/cmd" + +func main() { + cmd.Execute() +} diff --git a/skills/go-cli-builder/assets/templates/migrations.go.template b/skills/go-cli-builder/assets/templates/migrations.go.template new file mode 100644 index 0000000..af9a4a7 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/migrations.go.template @@ -0,0 +1,73 @@ +package database + +import ( + "fmt" +) + +// getMigrations returns all available migrations +// Add new migrations here with incrementing version numbers +func getMigrations() map[int]string { + return map[int]string{ + // Example migration: + // 2: ` + // CREATE TABLE IF NOT EXISTS settings ( + // key TEXT PRIMARY KEY, + // value TEXT NOT NULL, + // updated_at DATETIME DEFAULT CURRENT_TIMESTAMP + // ); + // `, + // Add your migrations here starting from version 2 + // (version 1 is the initial schema in schema.sql) + } +} + +// RunMigrations executes all pending migrations +func (db *DB) RunMigrations() error { + // Ensure schema_migrations table exists (created by InitSchema) + initialized, err := db.IsInitialized() + if err != nil { + return fmt.Errorf("failed to check initialization: %w", err) + } + + if !initialized { + return fmt.Errorf("database not initialized") + } + + // Get current version + currentVersion, err := db.GetMigrationVersion() + if err != nil { + return fmt.Errorf("failed to get current version: %w", err) + } + + // Get all migrations + migrations := getMigrations() + + // Find maximum version + maxVersion := currentVersion + for version := range migrations { + if version > maxVersion { + maxVersion = version + } + } + + // Apply pending migrations in order + appliedCount := 0 + for version := currentVersion + 1; version <= maxVersion; version++ { + migrationSQL, exists := migrations[version] + if !exists { + return fmt.Errorf("missing migration for version %d", version) + } + + if err := db.ApplyMigration(version, migrationSQL); err != nil { + return fmt.Errorf("failed to apply migration %d: %w", version, err) + } + + appliedCount++ + } + + if appliedCount > 0 { + fmt.Printf("Applied %d migration(s), current version: %d\n", appliedCount, maxVersion) + } + + return nil +} diff --git a/skills/go-cli-builder/assets/templates/release.yml.template b/skills/go-cli-builder/assets/templates/release.yml.template new file mode 100644 index 0000000..3dd20a0 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/release.yml.template @@ -0,0 +1,126 @@ +name: Release + +on: + push: + tags: + - 'v*' + +jobs: + ci: + uses: ./.github/workflows/ci.yml + + build: + needs: ci + strategy: + matrix: + include: + - os: ubuntu-latest + goos: linux + goarch: amd64 + - os: ubuntu-latest + goos: linux + goarch: arm64 + - os: macos-latest + goos: darwin + goarch: amd64 + - os: macos-latest + goos: darwin + goarch: arm64 + - os: windows-latest + goos: windows + goarch: amd64 + runs-on: ${{ matrix.os }} + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Build + shell: bash + env: + GOOS: ${{ matrix.goos }} + GOARCH: ${{ matrix.goarch }} + run: | + VERSION="${GITHUB_REF#refs/tags/}" + COMMIT="${GITHUB_SHA:0:7}" + BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + LDFLAGS="-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$BUILD_DATE" + + go build -ldflags "$LDFLAGS" -o {{PROJECT_NAME}}${{ matrix.goos == 'windows' && '.exe' || '' }} + + - name: Package (Unix) + if: matrix.goos != 'windows' + run: | + tar czf {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz {{PROJECT_NAME}} + + - name: Package (Windows) + if: matrix.goos == 'windows' + run: | + 7z a {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }}.zip {{PROJECT_NAME}}.exe + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }} + path: | + {{PROJECT_NAME}}-*.tar.gz + {{PROJECT_NAME}}-*.zip + + release: + needs: build + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download all artifacts + uses: actions/download-artifact@v4 + + - name: Generate checksums + run: | + find . -name "{{PROJECT_NAME}}-*" -type f \( -name "*.tar.gz" -o -name "*.zip" \) -exec sha256sum {} \; > checksums.txt + + - name: Create Release + uses: softprops/action-gh-release@v2 + with: + files: | + {{PROJECT_NAME}}-*/*.tar.gz + {{PROJECT_NAME}}-*/*.zip + checksums.txt + generate_release_notes: true + + # Uncomment to build and push Docker image + # docker: + # needs: build + # runs-on: ubuntu-latest + # steps: + # - name: Checkout code + # uses: actions/checkout@v4 + # + # - name: Set up Docker Buildx + # uses: docker/setup-buildx-action@v3 + # + # - name: Login to Docker Hub + # uses: docker/login-action@v3 + # with: + # username: ${{ secrets.DOCKER_USERNAME }} + # password: ${{ secrets.DOCKER_PASSWORD }} + # + # - name: Extract version + # id: version + # run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT + # + # - name: Build and push + # uses: docker/build-push-action@v5 + # with: + # context: . + # push: true + # tags: | + # yourusername/{{PROJECT_NAME}}:${{ steps.version.outputs.VERSION }} + # yourusername/{{PROJECT_NAME}}:latest diff --git a/skills/go-cli-builder/assets/templates/rolling-release.yml.template b/skills/go-cli-builder/assets/templates/rolling-release.yml.template new file mode 100644 index 0000000..3a925a3 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/rolling-release.yml.template @@ -0,0 +1,135 @@ +name: Rolling Release + +on: + push: + branches: [ main ] + +jobs: + ci: + uses: ./.github/workflows/ci.yml + + build: + needs: ci + strategy: + matrix: + include: + - os: ubuntu-latest + goos: linux + goarch: amd64 + - os: ubuntu-latest + goos: linux + goarch: arm64 + - os: macos-latest + goos: darwin + goarch: amd64 + - os: macos-latest + goos: darwin + goarch: arm64 + - os: windows-latest + goos: windows + goarch: amd64 + runs-on: ${{ matrix.os }} + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + + - name: Build + shell: bash + env: + GOOS: ${{ matrix.goos }} + GOARCH: ${{ matrix.goarch }} + run: | + VERSION="rolling-${GITHUB_SHA:0:7}" + COMMIT="${GITHUB_SHA:0:7}" + BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" + LDFLAGS="-X main.version=$VERSION -X main.commit=$COMMIT -X main.date=$BUILD_DATE" + + go build -ldflags "$LDFLAGS" -o {{PROJECT_NAME}}${{ matrix.goos == 'windows' && '.exe' || '' }} + + - name: Package (Unix) + if: matrix.goos != 'windows' + run: | + tar czf {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz {{PROJECT_NAME}} + + - name: Package (Windows) + if: matrix.goos == 'windows' + run: | + 7z a {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }}.zip {{PROJECT_NAME}}.exe + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: {{PROJECT_NAME}}-${{ matrix.goos }}-${{ matrix.goarch }} + path: | + {{PROJECT_NAME}}-*.tar.gz + {{PROJECT_NAME}}-*.zip + + release: + needs: build + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Download all artifacts + uses: actions/download-artifact@v4 + + - name: Generate checksums + run: | + find . -name "{{PROJECT_NAME}}-*" -type f \( -name "*.tar.gz" -o -name "*.zip" \) -exec sha256sum {} \; > checksums.txt + + - name: Delete existing rolling release + env: + GH_TOKEN: ${{ github.token }} + run: | + gh release delete latest --yes || true + git push origin :refs/tags/latest || true + + - name: Create Rolling Release + uses: softprops/action-gh-release@v2 + with: + tag_name: latest + name: Rolling Release + body: | + **Automated rolling release built from the latest commit on the main branch.** + + ⚠️ This release may be unstable and is intended for testing purposes only. + + **Commit:** ${{ github.sha }} + **Built:** ${{ github.event.head_commit.timestamp }} + prerelease: true + files: | + {{PROJECT_NAME}}-*/*.tar.gz + {{PROJECT_NAME}}-*/*.zip + checksums.txt + + # Uncomment to build and push Docker image + # docker: + # needs: build + # runs-on: ubuntu-latest + # steps: + # - name: Checkout code + # uses: actions/checkout@v4 + # + # - name: Set up Docker Buildx + # uses: docker/setup-buildx-action@v3 + # + # - name: Login to Docker Hub + # uses: docker/login-action@v3 + # with: + # username: ${{ secrets.DOCKER_USERNAME }} + # password: ${{ secrets.DOCKER_PASSWORD }} + # + # - name: Build and push + # uses: docker/build-push-action@v5 + # with: + # context: . + # push: true + # tags: yourusername/{{PROJECT_NAME}}:latest diff --git a/skills/go-cli-builder/assets/templates/root.go.template b/skills/go-cli-builder/assets/templates/root.go.template new file mode 100644 index 0000000..e4ef6ef --- /dev/null +++ b/skills/go-cli-builder/assets/templates/root.go.template @@ -0,0 +1,126 @@ +package cmd + +import ( + "fmt" + "os" + + "{{MODULE_NAME}}/internal/config" + "github.com/sirupsen/logrus" + "github.com/spf13/cobra" + "github.com/spf13/viper" +) + +var ( + cfgFile string + log = logrus.New() + cfg *config.Config +) + +// rootCmd represents the base command when called without any subcommands +var rootCmd = &cobra.Command{ + Use: "{{PROJECT_NAME}}", + Short: "A brief description of your application", + Long: `A longer description of what your application does and how it works. + +This can be multiple lines and should provide helpful context about the +purpose and usage of your CLI tool.`, + PersistentPreRun: func(cmd *cobra.Command, args []string) { + initConfig() + setupLogging() + }, +} + +// Execute adds all child commands to the root command and sets appropriate flags. +func Execute() { + if err := rootCmd.Execute(); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func init() { + // Configuration file flag + rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is ./{{PROJECT_NAME}}.yaml)") + + // Logging flags + rootCmd.PersistentFlags().BoolP("verbose", "v", false, "verbose output") + rootCmd.PersistentFlags().Bool("debug", false, "debug output") + rootCmd.PersistentFlags().Bool("log-json", false, "output logs in JSON format") + + // Database flag + rootCmd.PersistentFlags().String("database", "{{PROJECT_NAME}}.db", "database file path") + + // Bind flags to viper + _ = viper.BindPFlag("verbose", rootCmd.PersistentFlags().Lookup("verbose")) + _ = viper.BindPFlag("debug", rootCmd.PersistentFlags().Lookup("debug")) + _ = viper.BindPFlag("log_json", rootCmd.PersistentFlags().Lookup("log-json")) + _ = viper.BindPFlag("database", rootCmd.PersistentFlags().Lookup("database")) +} + +// initConfig reads in config file and ENV variables if set. +func initConfig() { + if cfgFile != "" { + // Use config file from the flag + viper.SetConfigFile(cfgFile) + } else { + // Search for config in current directory + viper.AddConfigPath(".") + viper.SetConfigType("yaml") + viper.SetConfigName("{{PROJECT_NAME}}") + } + + // Set defaults + viper.SetDefault("database", "{{PROJECT_NAME}}.db") + viper.SetDefault("verbose", false) + viper.SetDefault("debug", false) + viper.SetDefault("log_json", false) + + // Read in environment variables that match + viper.AutomaticEnv() + + // If a config file is found, read it in + if err := viper.ReadInConfig(); err != nil { + if cfgFile != "" { + // Only error if config was explicitly specified + fmt.Fprintf(os.Stderr, "Error reading config file: %v\n", err) + os.Exit(1) + } + } +} + +// setupLogging configures the logger based on configuration +func setupLogging() { + if viper.GetBool("log_json") { + log.SetFormatter(&logrus.JSONFormatter{}) + } else { + log.SetFormatter(&logrus.TextFormatter{ + FullTimestamp: true, + }) + } + + if viper.GetBool("debug") { + log.SetLevel(logrus.DebugLevel) + } else if viper.GetBool("verbose") { + log.SetLevel(logrus.InfoLevel) + } else { + log.SetLevel(logrus.WarnLevel) + } +} + +// GetConfig returns the application configuration, loading it if necessary +func GetConfig() *config.Config { + if cfg == nil { + cfg = &config.Config{ + Database: viper.GetString("database"), + Verbose: viper.GetBool("verbose"), + Debug: viper.GetBool("debug"), + LogJSON: viper.GetBool("log_json"), + } + } + return cfg +} + +// GetLogger returns the configured logger +func GetLogger() *logrus.Logger { + return log +} diff --git a/skills/go-cli-builder/assets/templates/schema.sql.template b/skills/go-cli-builder/assets/templates/schema.sql.template new file mode 100644 index 0000000..4d8d5b7 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/schema.sql.template @@ -0,0 +1,24 @@ +-- Initial database schema for {{PROJECT_NAME}} +-- This is version 1 of the schema + +-- Migration tracking table +CREATE TABLE IF NOT EXISTS schema_migrations ( + version INTEGER PRIMARY KEY, + applied_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +-- Insert initial version +INSERT OR IGNORE INTO schema_migrations (version) VALUES (1); + +-- Example table - customize for your application +-- CREATE TABLE IF NOT EXISTS items ( +-- id INTEGER PRIMARY KEY AUTOINCREMENT, +-- name TEXT NOT NULL, +-- description TEXT, +-- created_at DATETIME DEFAULT CURRENT_TIMESTAMP, +-- updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +-- ); +-- +-- CREATE INDEX IF NOT EXISTS idx_items_name ON items(name); + +-- Add your initial schema tables here diff --git a/skills/go-cli-builder/assets/templates/templates.go.template b/skills/go-cli-builder/assets/templates/templates.go.template new file mode 100644 index 0000000..c232bbe --- /dev/null +++ b/skills/go-cli-builder/assets/templates/templates.go.template @@ -0,0 +1,13 @@ +package templates + +import ( + _ "embed" +) + +//go:embed default.md +var defaultTemplate string + +// GetDefaultTemplate returns the embedded default template content +func GetDefaultTemplate() (string, error) { + return defaultTemplate, nil +} diff --git a/skills/go-cli-builder/assets/templates/version.go.template b/skills/go-cli-builder/assets/templates/version.go.template new file mode 100644 index 0000000..d733f34 --- /dev/null +++ b/skills/go-cli-builder/assets/templates/version.go.template @@ -0,0 +1,27 @@ +package cmd + +import ( + "fmt" + + "github.com/spf13/cobra" +) + +var ( + version = "dev" + commit = "unknown" + date = "unknown" +) + +// versionCmd represents the version command +var versionCmd = &cobra.Command{ + Use: "version", + Short: "Print version information", + Long: `Print the version, commit hash, and build date of this application.`, + Run: func(cmd *cobra.Command, args []string) { + fmt.Printf("{{PROJECT_NAME}} %s (commit: %s, built: %s)\n", version, commit, date) + }, +} + +func init() { + rootCmd.AddCommand(versionCmd) +} diff --git a/skills/go-cli-builder/references/cobra-viper-integration.md b/skills/go-cli-builder/references/cobra-viper-integration.md new file mode 100644 index 0000000..4a1a41d --- /dev/null +++ b/skills/go-cli-builder/references/cobra-viper-integration.md @@ -0,0 +1,129 @@ +# Cobra + Viper Integration Pattern + +This document explains how Cobra (CLI framework) and Viper (configuration management) are integrated in the generated Go CLI projects. + +## Architecture Overview + +The integration follows these principles: + +1. **Configuration Priority** (highest to lowest): + - Command-line flags + - Environment variables + - Config file values + - Default values + +2. **Lazy Loading**: Configuration is loaded once in `PersistentPreRun`, before any command executes + +3. **Centralized Access**: The `GetConfig()` and `GetLogger()` functions in `cmd/root.go` provide access to configuration and logging + +## Key Components + +### Root Command (`cmd/root.go`) + +The root command sets up the entire configuration system: + +```go +var rootCmd = &cobra.Command{ + PersistentPreRun: func(cmd *cobra.Command, args []string) { + initConfig() + setupLogging() + }, +} +``` + +### Configuration Initialization (`initConfig()`) + +This function: +1. Determines config file location (from flag or default) +2. Sets default values +3. Enables environment variable reading +4. Reads the config file (if it exists) + +### Flag Binding + +Flags are bound to Viper keys using `viper.BindPFlag()`: + +```go +rootCmd.PersistentFlags().StringP("verbose", "v", false, "verbose output") +viper.BindPFlag("verbose", rootCmd.PersistentFlags().Lookup("verbose")) +``` + +This creates the hierarchy: CLI flag → Viper key → Config struct + +## Adding New Configuration + +To add a new configuration option: + +1. **Add to config struct** (`internal/config/config.go`): + ```go + type Config struct { + MyNewOption string + } + ``` + +2. **Add flag** (`cmd/root.go` or command-specific file): + ```go + rootCmd.PersistentFlags().String("my-option", "default", "description") + viper.BindPFlag("my_option", rootCmd.PersistentFlags().Lookup("my-option")) + ``` + +3. **Set default** (`cmd/root.go` in `initConfig()`): + ```go + viper.SetDefault("my_option", "default_value") + ``` + +4. **Add to config example** (`.yaml.example`): + ```yaml + my_option: "default_value" + ``` + +5. **Access in commands**: + ```go + cfg := GetConfig() + value := cfg.MyNewOption + // or directly from viper: + value := viper.GetString("my_option") + ``` + +## Command-Specific Configuration + +For configuration specific to a single command: + +1. Add the flag to the command's `init()` function, not the root command +2. Use a nested structure in the config struct: + ```go + type Config struct { + Fetch struct { + Concurrency int + Timeout time.Duration + } + } + ``` + +3. Bind with a namespaced key: + ```go + viper.BindPFlag("fetch.concurrency", fetchCmd.Flags().Lookup("concurrency")) + ``` + +## Environment Variables + +Viper automatically maps environment variables when you call `viper.AutomaticEnv()`. + +By default, environment variables are matched by converting the key to uppercase and replacing `.` with `_`: + +- Config key: `fetch.concurrency` +- Environment variable: `FETCH_CONCURRENCY` + +## Best Practices + +1. **Use PersistentFlags for global options**: Options that apply to all commands should be on `rootCmd.PersistentFlags()` + +2. **Use command-specific Flags for local options**: Options specific to one command should be on that command's `Flags()` + +3. **Provide sensible defaults**: Always set defaults in `initConfig()` so the tool works without a config file + +4. **Document in .yaml.example**: Keep the example config file up to date + +5. **Keep flag names kebab-case**: Use hyphens in CLI flags (`--my-option`) and underscores in Viper keys (`my_option`) + +6. **Use GetConfig() for structured access**: Prefer accessing configuration through the typed Config struct rather than calling viper.Get* directly in commands diff --git a/skills/go-cli-builder/references/internal-organization.md b/skills/go-cli-builder/references/internal-organization.md new file mode 100644 index 0000000..c197bee --- /dev/null +++ b/skills/go-cli-builder/references/internal-organization.md @@ -0,0 +1,231 @@ +# Internal Package Organization + +This document explains how to organize code in the `internal/` directory of Go CLI projects. + +## The `internal/` Directory + +The `internal/` directory is a special Go convention. Packages inside `internal/` can only be imported by code in the parent tree. This enforces encapsulation and prevents external projects from depending on internal implementation details. + +## Standard Package Structure + +A typical Go CLI project has this structure: + +``` +project/ +├── cmd/ # Command definitions (public API of the CLI) +├── internal/ # Private implementation +│ ├── config/ # Configuration structures +│ ├── database/ # Database access layer +│ └── [domain packages] # Business logic packages +├── main.go # Entry point +└── go.mod # Dependencies +``` + +## Package Guidelines + +### `cmd/` Package + +**Purpose**: Define the CLI commands and their flags + +**Contents**: +- `root.go`: Root command and configuration initialization +- `version.go`: Version command +- `constants.go`: CLI-level constants +- One file per command (e.g., `fetch.go`, `export.go`) + +**Responsibilities**: +- Parse and validate user input +- Set up configuration and logging +- Call into `internal/` packages to do the work +- Format and display output + +**Anti-patterns**: +- Heavy business logic in command handlers +- Direct database access +- Complex algorithms + +### `internal/config/` Package + +**Purpose**: Define configuration structures + +**Contents**: +- `config.go`: Config struct definitions + +**Example**: +```go +package config + +type Config struct { + Database string + Verbose bool + + Fetch struct { + Concurrency int + Timeout time.Duration + } +} +``` + +### `internal/database/` Package + +**Purpose**: Encapsulate all database operations + +**Contents**: +- `database.go`: Connection management, initialization +- `migrations.go`: Migration system +- `schema.sql`: Initial schema (embedded) +- Optional: `queries.go` for complex queries + +**Responsibilities**: +- Database connection lifecycle +- Schema initialization and migrations +- Data access methods +- Transaction management + +**Anti-patterns**: +- Business logic in database layer +- Exposing `*sql.DB` directly +- SQL in command files + +### Domain-Specific Packages + +Create additional packages in `internal/` for each major domain or feature: + +``` +internal/ +├── feeds/ # Feed parsing and processing +├── fetcher/ # HTTP fetching logic +├── renderer/ # Output rendering +└── exporter/ # Export functionality +``` + +**Guidelines**: +- One package per cohesive responsibility +- Packages should be importable by `cmd/` and by each other +- Keep packages focused and single-purpose +- Use clear, descriptive names + +## Layering and Dependencies + +Follow these dependency rules: + +``` +main.go + └─> cmd/ + └─> internal/config/ + └─> internal/database/ + └─> internal/[domain]/ + └─> internal/[other domains]/ +``` + +**Rules**: +1. `cmd/` can import any `internal/` package +2. `internal/` packages can import each other as needed +3. Avoid circular dependencies between `internal/` packages +4. Keep `cmd/` thin - it orchestrates but doesn't implement + +## Example: Adding a New Feature + +Let's say you want to add feed fetching functionality: + +1. **Create the package**: + ``` + internal/fetcher/ + ├── fetcher.go # Main fetching logic + └── fetcher_test.go # Tests + ``` + +2. **Define the API**: + ```go + package fetcher + + type Fetcher struct { + client *http.Client + // ... + } + + func New(opts ...Option) *Fetcher { ... } + func (f *Fetcher) Fetch(url string) ([]byte, error) { ... } + ``` + +3. **Use in command**: + ```go + // cmd/fetch.go + package cmd + + import "yourproject/internal/fetcher" + + var fetchCmd = &cobra.Command{ + RunE: func(cmd *cobra.Command, args []string) error { + f := fetcher.New() + data, err := f.Fetch(url) + // ... + }, + } + ``` + +## Common Patterns + +### Option Pattern for Configuration + +```go +type Fetcher struct { + timeout time.Duration +} + +type Option func(*Fetcher) + +func WithTimeout(d time.Duration) Option { + return func(f *Fetcher) { + f.timeout = d + } +} + +func New(opts ...Option) *Fetcher { + f := &Fetcher{timeout: 30 * time.Second} + for _, opt := range opts { + opt(f) + } + return f +} +``` + +### Embedding Resources + +For SQL, templates, or other resources: + +```go +import _ "embed" + +//go:embed schema.sql +var schemaSQL string +``` + +### Error Wrapping + +Always wrap errors with context: + +```go +if err != nil { + return fmt.Errorf("failed to fetch feed %s: %w", url, err) +} +``` + +## Testing + +- Put tests in `_test.go` files alongside the code +- Use table-driven tests for multiple cases +- Consider using `internal/database/database_test.go` with in-memory SQLite for database tests + +## When to Create a New Package + +Create a new `internal/` package when: +- You have a cohesive set of related functionality +- The code would make commands cleaner and more focused +- You want to unit test logic separately from CLI interaction +- Multiple commands need to share the same functionality + +Don't create a package when: +- It would only have one small function +- It's tightly coupled to a single command +- It would create circular dependencies diff --git a/skills/go-cli-builder/references/template-patterns.md b/skills/go-cli-builder/references/template-patterns.md new file mode 100644 index 0000000..ee56160 --- /dev/null +++ b/skills/go-cli-builder/references/template-patterns.md @@ -0,0 +1,410 @@ +# Template Patterns for Go CLI Tools + +This guide covers patterns for implementing customizable output templates in Go CLI tools, based on successful patterns from `linkding-to-markdown` and `mastodon-to-markdown`. + +## Overview + +CLI tools that generate formatted output (Markdown, HTML, XML, etc.) benefit from: +1. **Embedded default templates** - Work out of the box, single binary +2. **User customization** - Users can modify templates for their needs +3. **Init command** - Easy way to get started with configuration and templates + +## Architecture + +### Directory Structure + +``` +my-cli-tool/ +├── cmd/ +│ ├── init.go # Init command to bootstrap config/templates +│ └── fetch.go # Command that uses templates +├── internal/ +│ ├── templates/ +│ │ ├── templates.go # Template loader with embedded defaults +│ │ └── default.md # Default template (embedded via //go:embed) +│ └── generator/ # Or markdown/, formatter/, etc. +│ └── generator.go # Template renderer and data structures +``` + +## Implementation Steps + +### 1. Create Template Package + +**File: `internal/templates/templates.go`** + +```go +package templates + +import ( + _ "embed" +) + +//go:embed default.md +var defaultTemplate string + +// GetDefaultTemplate returns the embedded default template content +func GetDefaultTemplate() (string, error) { + return defaultTemplate, nil +} +``` + +**File: `internal/templates/default.md`** + +Create your default template using Go's `text/template` syntax: + +```markdown +# {{ .Title }} + +_Generated: {{ .Generated }}_ + +--- + +{{ range .Items -}} +## {{ .Name }} + +{{ .Description }} + +{{ if .Tags -}} +Tags: {{ join .Tags ", " }} +{{ end -}} + +--- +{{ end -}} +``` + +### 2. Create Generator/Renderer + +**File: `internal/generator/generator.go`** + +```go +package generator + +import ( + "fmt" + "io" + "os" + "strings" + "text/template" + "time" + + "yourproject/internal/templates" +) + +type Generator struct { + template *template.Template +} + +// NewGenerator creates a generator with the default embedded template +func NewGenerator() (*Generator, error) { + defaultTmpl, err := templates.GetDefaultTemplate() + if err != nil { + return nil, fmt.Errorf("failed to get default template: %w", err) + } + return NewGeneratorWithTemplate(defaultTmpl) +} + +// NewGeneratorFromFile creates a generator from a template file +func NewGeneratorFromFile(templatePath string) (*Generator, error) { + content, err := os.ReadFile(templatePath) + if err != nil { + return nil, fmt.Errorf("failed to read template file: %w", err) + } + return NewGeneratorWithTemplate(string(content)) +} + +// NewGeneratorWithTemplate creates a generator with a custom template string +func NewGeneratorWithTemplate(tmplStr string) (*Generator, error) { + // Define template functions + funcMap := template.FuncMap{ + "formatDate": func(t time.Time, format string) string { + return t.Format(format) + }, + "join": strings.Join, + "hasContent": func(s string) bool { + return strings.TrimSpace(s) != "" + }, + } + + tmpl, err := template.New("output").Funcs(funcMap).Parse(tmplStr) + if err != nil { + return nil, fmt.Errorf("failed to parse template: %w", err) + } + + return &Generator{template: tmpl}, nil +} + +// TemplateData holds data passed to templates +type TemplateData struct { + Title string + Generated string + Items []Item + // Add your domain-specific fields here +} + +// Generate executes the template with data and writes to writer +func (g *Generator) Generate(w io.Writer, data TemplateData) error { + if err := g.template.Execute(w, data); err != nil { + return fmt.Errorf("failed to execute template: %w", err) + } + return nil +} +``` + +### 3. Create Init Command + +Use the `init.go.template` from the skill, customizing the `defaultConfigContent` for your project's needs. + +Key features: +- Creates config file with documented options +- Creates customizable template file from embedded default +- Supports `--force` to overwrite +- Supports `--template-file` to specify custom filename +- Provides helpful next steps + +### 4. Integrate with Commands + +**In your command that generates output:** + +```go +func runFetch(cmd *cobra.Command, args []string) error { + logger := GetLogger() + + // ... fetch your data ... + + // Create generator with custom template or default + templatePath := viper.GetString("fetch.template") + var generator *generator.Generator + var err error + + if templatePath != "" { + logger.Infof("Using custom template: %s", templatePath) + generator, err = generator.NewGeneratorFromFile(templatePath) + if err != nil { + return fmt.Errorf("failed to load custom template: %w", err) + } + } else { + generator, err = generator.NewGenerator() + if err != nil { + return fmt.Errorf("failed to create generator: %w", err) + } + } + + // Prepare template data + data := generator.TemplateData{ + Title: viper.GetString("fetch.title"), + Generated: time.Now().Format(time.RFC3339), + Items: fetchedItems, + } + + // Determine output destination + outputPath := viper.GetString("fetch.output") + var output *os.File + if outputPath != "" { + output, err = os.Create(outputPath) + if err != nil { + return fmt.Errorf("failed to create output file: %w", err) + } + defer output.Close() + logger.Infof("Writing output to %s", outputPath) + } else { + output = os.Stdout + } + + // Generate output + if err := generator.Generate(output, data); err != nil { + return fmt.Errorf("failed to generate output: %w", err) + } + + return nil +} +``` + +### 5. Add Configuration Support + +**In `internal/config/config.go`:** + +```go +type Config struct { + // ... other config ... + + Fetch struct { + Output string + Title string + Template string // Path to custom template file + } +} +``` + +**In your command's flags:** + +```go +fetchCmd.Flags().String("template", "", "Custom template file (default: built-in template)") +_ = viper.BindPFlag("fetch.template", fetchCmd.Flags().Lookup("template")) +``` + +**In config YAML:** + +```yaml +fetch: + output: "output.md" + title: "My Output" + template: "my-custom-template.md" # Optional +``` + +## Template Functions + +Provide helpful template functions for common operations: + +```go +funcMap := template.FuncMap{ + // Date formatting + "formatDate": func(t time.Time, format string) string { + return t.Format(format) + }, + + // String operations + "join": strings.Join, + "hasContent": func(s string) bool { + return strings.TrimSpace(s) != "" + }, + "truncate": func(s string, length int) string { + if len(s) <= length { + return s + } + return s[:length] + "..." + }, + + // Conditional helpers + "default": func(defaultVal, val interface{}) interface{} { + if val == nil || val == "" { + return defaultVal + } + return val + }, +} +``` + +## User Workflow + +### First-Time Setup + +```bash +# User initializes config and template +$ my-tool init +✅ Initialization complete! + +Next steps: + 1. Edit my-tool.yaml and add your configuration + 2. (Optional) Customize my-tool.md for your preferred output format + 3. Run: my-tool fetch --help for usage information +``` + +### Using Default Template + +```bash +# Just works with embedded default +$ my-tool fetch --output result.md +``` + +### Using Custom Template + +```bash +# After editing my-tool.md +$ my-tool fetch --template my-tool.md --output result.md + +# Or via config file +$ cat my-tool.yaml +fetch: + template: "my-tool.md" + +$ my-tool fetch --output result.md +``` + +## Best Practices + +1. **Always provide a sensible default template** - Tool should work without customization +2. **Document template variables** - In README and/or generated template comments +3. **Validate templates early** - Parse template when creating generator, not during execution +4. **Provide helpful error messages** - Template parse errors should show line numbers +5. **Include examples** - Show template snippets in documentation +6. **Support both stdout and file output** - Enables piping and integration +7. **Make template optional** - Config file should work without template field set + +## Template Documentation + +In your README, document: + +### Available Variables + +```markdown +### Template Variables + +- `.Title` - Document title (string) +- `.Generated` - Generation timestamp (string) +- `.Items` - Array of items to include + +### Item Fields + +Each item has: +- `.Name` - Item name (string) +- `.Description` - Item description (string) +- `.Tags` - Array of tags ([]string) +``` + +### Available Functions + +```markdown +### Template Functions + +- `formatDate