# GoTask Task Libraries

This directory contains GoTask task libraries for the AI Toolkit project. Tasks are organized by functionality into separate YAML files.

## Task Files

### Main Taskfile ([../Taskfile.yml](../Taskfile.yml))

Primary task runner configuration that includes all other task libraries.

**Core Tasks** (flattened from [bun.yml](bun.yml)):

| Task                        | Alias  | Description                                       |
| --------------------------- | ------ | ------------------------------------------------- |
| `task setup`                | -      | Setup development environment (run after cloning) |
| `task install`              | `i`    | Install dependencies                              |
| `task build`                | `b`    | Build the project                                 |
| `task rebuild`              | `rb`   | Clean and rebuild project                         |
| `task clean`                | `c`    | Clean build artifacts and temporary files         |
| `task dev`                  | `d`    | Run in development mode                           |
| `task test`                 | `t`    | Run unit tests                                    |
| `task test:integration`     | `ti`   | Run integration tests                             |
| `task test:coverage`        | `cov`  | Run tests with coverage                           |
| `task test:coverage:report` | `covr` | Display coverage report                           |
| `task lint`                 | `l`    | Run linter                                        |
| `task lint:fix`             | `lf`   | Run linter with auto-fix                          |
| `task format`               | `f`    | Format code                                       |
| `task typecheck`            | `tc`   | Type check TypeScript                             |
| `task ci`                   | -      | Run CI checks (lint, typecheck, test, build)      |

**Included Task Libraries:**

The main Taskfile includes these specialized task libraries (access via namespaces like `task git:pr:create`):

- **gotask** (`task gotask:*` or `task gt:*`) - Task development utilities
- **claude** (`task claude:*` or `task cd:*`) - Claude Code & MCP management
- **docs** (`task docs:*`) - API documentation generation
- **op** (`task op:*` or `task 1p:*`) - 1Password secret management
- **git** (`task git:*`) - Git & GitHub operations
- **yaml** (`task yaml:*` or `task yml:*`) - YAML linting & validation
- **markdown** (`task markdown:*` or `task md:*`) - Markdown linting
- **json** (`task json:*`) - JSON linting & validation
- **bash** (`task bash:*`) - Bash linting & formatting
- **security** (`task security:*` or `task s:*`) - Security scanning
- **sonar** (`task sonar:*`) - SonarQube code quality
- **aws** (`task aws:*`) - AWS CLI operations

### GoTask Utilities ([gotask.yml](gotask.yml))

Development tools and utilities for creating and managing task files.

**Task Development:**

| Task                     | Alias | Description                         |
| ------------------------ | ----- | ----------------------------------- |
| `task gotask:format`     | `f`   | Format default task in Taskfile     |
| `task gotask:new:task`   | `nt`  | Create new task in Taskfile.yml     |
| `task gotask:new:script` | `ns`  | Create new TypeScript task script   |
| `task gotask:validate`   | `v`   | Validate all Taskfile.yml syntax    |
| `task gotask:deps:check` | `dc`  | Check for missing task dependencies |

**Setup & Configuration:**

| Task                           | Alias | Description                                  |
| ------------------------------ | ----- | -------------------------------------------- |
| `task gotask:setup:extensions` | `se`  | Install recommended VSCode/Cursor extensions |

**Documentation:**

| Task                        | Alias | Description                 |
| --------------------------- | ----- | --------------------------- |
| `task gotask:docs:generate` | `dg`  | Generate task documentation |
| `task gotask:docs:view`     | `dv`  | View best practices guide   |
| `task gotask:docs:edit`     | `de`  | Edit best practices guide   |

**Templates:**

| Task                         | Alias | Description                  |
| ---------------------------- | ----- | ---------------------------- |
| `task gotask:template:basic` | `tb`  | Generate basic task template |
| `task gotask:template:build` | `tbu` | Generate build task template |
| `task gotask:template:test`  | `tt`  | Generate test task template  |

### Claude Code & MCP ([claude.yml](claude.yml))

Tasks for managing Claude Code integration and MCP server installations.

**MCP Server Management:**

| Task                      | Alias | Description                    |
| ------------------------- | ----- | ------------------------------ |
| `task claude:mcp:install` | `mi`  | Install MCP server globally    |
| `task claude:mcp:verify`  | `mv`  | Verify MCP server installation |
| `task claude:mcp:status`  | `ms`  | Show MCP server status         |
| `task claude:mcp:remove`  | `mr`  | Remove MCP server              |

**Installer Testing:**

| Task                               | Alias | Description                       |
| ---------------------------------- | ----- | --------------------------------- |
| `task claude:installer:test`       | `it`  | Run complete installer test suite |
| `task claude:installer:test:force` | `itf` | Test force reinstall              |
| `task claude:installer:test:clean` | `itc` | Clean up test installations       |

### 1Password Secret Management ([onepassword.yml](onepassword.yml))

Secure secret management using 1Password CLI. Secrets are automatically loaded by tasks that need them.

**Secret Loading:**

| Command                          | Alias   | Description                             |
| -------------------------------- | ------- | --------------------------------------- |
| `source $(task op:export)`       | `op:x`  | Load secrets into shell (interactive)   |
| `source $(task op:export:force)` | `op:xf` | Force reload all secrets from 1Password |
| `task op:cleanup`                | `op:c`  | Clean up temp secret files              |
| `task op:validate`               | `op:v`  | Validate exported secrets               |
| `task op:test`                   | `op:t`  | Test GitHub token permissions           |

**How It Works:**

Tasks that require secrets (like `semgrep`) automatically source secrets via secure temp files:

```bash
# Just run the task - secrets loaded automatically
task semgrep

# For interactive shell use:
source $(task op:export)
```

**Security Features:**

- Secrets stored in secure temp file (`chmod 600`)
- 1-hour cache (idempotent, avoids repeated prompts)
- No secrets printed to terminal
- Unique path per repository
- Automatic cleanup on reboot (stored in `/tmp`)

### YAML Linting & Validation ([yaml.yml](yaml.yml))

YAML file validation, linting, and auto-formatting with global tool installation.

**Implementation:** Task logic is in TypeScript ([src/tasks/yaml/](../src/tasks/yaml/)) following best practices for maintainability and testability.

**Commands:**

| Task                 | Alias | Description                 |
| -------------------- | ----- | --------------------------- |
| `task yaml:lint`     | `l`   | Lint YAML files             |
| `task yaml:lint:fix` | `lf`  | Auto-fix YAML formatting    |
| `task yaml:validate` | `v`   | Validate YAML syntax only   |
| `task yaml:setup`    | `s`   | Install YAML tools globally |

**Usage:**

```bash
# Lint all YAML files (auto-detects prettier or yamllint)
task yaml:lint

# Lint specific pattern
task yaml:lint FILES="*.yml"
task yaml:lint FILES="config/*.yml,tasks/*.yml"

# Force specific linter
task yaml:lint LINTER=prettier
task yaml:lint LINTER=yamllint

# Auto-fix formatting issues
task yaml:lint:fix

# Validate syntax only
task yaml:validate

# Install tools globally (one-time setup)
task yaml:setup
```

**Features:**

- Auto-detection of available linters (prettier, yamllint)
- Global tool installation via `task yaml:setup`
- File pattern support with glob expansion
- Auto-fix with prettier or yq fallback
- Default config creation (`.yamllint.yml`, `.prettierrc.yml`)
- Cross-platform support (macOS, Linux)
- Idempotent setup (checks existing installations)

**Tools Installed by `setup`:**

- **js-yaml** - YAML syntax validation
- **prettier** - Auto-formatting (recommended)
- **yamllint** - Style linting with rules

**How It Works:**

Tools are installed globally once and shared across all projects:

```bash
# First project
cd ~/projects/ai-toolkit
task yaml:setup          # Installs tools globally

# Other projects - tools already available
cd ~/projects/other-project
task yaml:lint           # Works immediately
```

### Markdown Linting & Validation ([markdown.yml](markdown.yml))

Markdown file validation, linting, and auto-formatting using markdownlint.

**Implementation:** Task logic is in TypeScript ([src/tasks/markdown/](../src/tasks/markdown/)) for maintainability.

**Commands:**

| Task                     | Alias | Description                          |
| ------------------------ | ----- | ------------------------------------ |
| `task markdown:lint`     | `l`   | Lint markdown files                  |
| `task markdown:lint:fix` | `lf`  | Auto-fix markdown formatting         |
| `task markdown:setup`    | `s`   | Install markdownlint & create config |

**Usage:**

```bash
# Lint all markdown files (quiet on success)
task markdown:lint

# Lint specific pattern
task markdown:lint FILES="*.md"
task markdown:lint FILES="docs/**/*.md"

# Show output even on success
VERBOSE=1 task markdown:lint

# Auto-fix formatting issues
task markdown:lint:fix

# Install markdownlint globally (one-time setup)
task markdown:setup
```

**Features:**

- Quiet output on success (use `VERBOSE=1` for details)
- File pattern support with glob expansion
- Auto-fix capability
- Default config creation (`.markdownlint.yaml`)
- Cross-platform support

**Default Patterns:**

`*.md,docs/**/*.md,.github/**/*.md,tasks/**/*.md`

### JSON Linting & Validation ([json.yml](json.yml))

JSON file validation, linting, and auto-formatting with built-in JSON parser.

**Implementation:** Task logic is in TypeScript ([src/tasks/json/](../src/tasks/json/)) for maintainability.

**Commands:**

| Task                 | Alias | Description              |
| -------------------- | ----- | ------------------------ |
| `task json:lint`     | `l`   | Lint JSON files          |
| `task json:lint:fix` | `lf`  | Auto-fix JSON formatting |

**Usage:**

```bash
# Lint all JSON files (quiet on success)
task json:lint

# Lint specific pattern
task json:lint FILES="*.json"
task json:lint FILES="config/**/*.json"

# Show output even on success
VERBOSE=1 task json:lint

# Auto-fix formatting (pretty-print with 2-space indent)
task json:lint:fix
```

**Features:**

- Quiet output on success (use `VERBOSE=1` for details)
- File pattern support with glob expansion
- Auto-fix with 2-space indentation
- Excludes node_modules, dist, and .taskmaster directories
- Built-in JSON parser (no external dependencies)

**Default Patterns:**

`*.json,**/*.json,!node_modules/**,!dist/**,!.taskmaster/**`

### Bash Linting & Formatting ([bash.yml](bash.yml))

Bash script validation, linting, and auto-formatting with global tool installation.

**Implementation:** Task logic is in TypeScript ([src/tasks/bash/](../src/tasks/bash/)) for maintainability and testability.

**Commands:**

| Task                     | Alias | Description                      |
| ------------------------ | ----- | -------------------------------- |
| `task bash:lint`         | `l`   | Lint bash files with shellcheck  |
| `task bash:format`       | `f`   | Format bash files with shfmt     |
| `task bash:format:check` | `fc`  | Check formatting without changes |
| `task bash:setup`        | `s`   | Install bash tools globally      |

**Usage:**

```bash
# Lint all bash files (quiet on success)
task bash:lint

# Lint specific pattern
task bash:lint FILES="*.sh"
task bash:lint FILES="scripts/**/*.sh"

# Show output even on success
VERBOSE=1 task bash:lint

# Format all bash files
task bash:format

# Check formatting without making changes
task bash:format:check

# Install tools globally (one-time setup)
task bash:setup
```

**Features:**

- Quiet output on success (use `VERBOSE=1` for details)
- File pattern support with glob expansion
- Auto-formatting with shfmt
- Global tool installation via `task bash:setup`
- Cross-platform support (macOS, Linux)

**Tools Installed by `setup`:**

- **shellcheck** - Bash linting and validation
- **shfmt** - Bash script formatting

**Default Patterns:**

`*.sh,**/*.sh,bin/*,scripts/**/*.sh`

### Bun Development Tasks ([bun.yml](bun.yml))

Core development tasks for building, testing, and maintaining the project.

**Commands:**

| Task                        | Alias  | Description                                  |
| --------------------------- | ------ | -------------------------------------------- |
| `task install`              | `i`    | Install dependencies                         |
| `task build`                | `b`    | Build the project                            |
| `task rebuild`              | `rb`   | Clean and rebuild project                    |
| `task clean`                | `c`    | Clean build artifacts and temporary files    |
| `task dev`                  | `d`    | Run in development mode                      |
| `task lint`                 | `l`    | Run linter                                   |
| `task lint:fix`             | `lf`   | Run linter with auto-fix                     |
| `task format`               | `f`    | Format code                                  |
| `task typecheck`            | `tc`   | Type check TypeScript                        |
| `task test`                 | `t`    | Run unit tests                               |
| `task test:integration`     | `ti`   | Run integration tests                        |
| `task test:coverage`        | `cov`  | Run tests with coverage                      |
| `task test:coverage:report` | `covr` | Display coverage report                      |
| `task ci`                   | -      | Run CI checks (lint, typecheck, test, build) |

**Usage:**

```bash
# Development workflow
task install
task build
task test

# Lint and auto-fix
task lint:fix

# Run tests with coverage
task test:coverage

# Show coverage report with files below threshold
task test:coverage:report THRESHOLD=80

# Clean everything including git worktrees
task clean

# Full rebuild
task rebuild

# Run CI checks locally
task ci
```

**Features:**

- Auto-detection of ESLint, Biome, and Prettier
- Coverage tracking with low-coverage file highlighting
- Git worktree cleanup in clean task
- Integration with 1Password for secrets
- Parallel test execution support

### API Documentation ([docs.yml](docs.yml))

TypeDoc-based API documentation generation in Markdown format.

**Commands:**

| Task                 | Alias | Description                       |
| -------------------- | ----- | --------------------------------- |
| `task docs:generate` | `g`   | Generate API docs from TypeScript |
| `task docs:clean`    | `c`   | Remove generated documentation    |
| `task docs:watch`    | `w`   | Watch for changes and regenerate  |
| `task docs:view`     | `v`   | Open generated docs               |
| `task docs:rebuild`  | `r`   | Clean and regenerate docs         |

**Usage:**

```bash
# Generate API documentation
task docs:generate

# Watch and auto-regenerate on changes
task docs:watch

# View generated docs
task docs:view

# Clean and regenerate
task docs:rebuild
```

**Features:**

- TypeDoc integration for TypeScript documentation
- Markdown output format
- Auto-open in VSCode or system viewer
- Watch mode for development

**Output:**

Documentation generated in `docs/api/` directory.

### Git & GitHub Operations ([git.yml](git.yml))

Tasks for Git operations, GitHub PR management, and repository utilities.

**Repository Utilities:**

| Task                      | Alias    | Description                          |
| ------------------------- | -------- | ------------------------------------ |
| `task git:repo:root`      | `root`   | Get repository root path             |
| `task git:repo:url`       | `url`    | Get repository HTTPS URL             |
| `task git:branch:current` | `branch` | Get current branch name              |
| `task git:branch:default` | `main`   | Get default branch (main/master)     |
| `task git:branch:prune`   | `prune`  | Delete local branches gone on remote |
| `task git:token`          | `token`  | Get GitHub authentication token      |

**Pull Request Management:**

| Task                   | Alias | Description                      |
| ---------------------- | ----- | -------------------------------- |
| `task git:pr:create`   | `pr`  | Create/update draft PR from file |
| `task git:pr:open`     | `pro` | Open current PR in browser       |
| `task git:pr:list`     | `prl` | List pull requests               |
| `task git:pr:comments` | `com` | Get all comments from current PR |

**GitHub Actions:**

| Task                   | Alias  | Description                |
| ---------------------- | ------ | -------------------------- |
| `task git:runs:log`    | `logs` | Download workflow run logs |
| `task git:actions:pin` | `pin`  | Pin actions to commit SHAs |

**Security:**

| Task             | Alias   | Description                    |
| ---------------- | ------- | ------------------------------ |
| `task git:leaks` | `leaks` | Scan for secrets with gitleaks |
| `task git:cve`   | `cve`   | Download CVEs for repository   |

**Usage:**

```bash
# Repository utilities
REPO_ROOT=$(task git:repo:root)
REPO_URL=$(task git:repo:url)
CURRENT_BRANCH=$(task git:branch:current)
DEFAULT_BRANCH=$(task git:branch:default)

# Create PR from default file (.pr.local.md)
task git:pr:create

# Create PR from custom file
task git:pr:create FILE=.pr.custom.md

# List open PRs
task git:pr:list LIMIT=20 STATE=open

# Get all PR comments
task git:pr:comments

# Download workflow run logs
task git:runs:log                              # Latest failed run
task git:runs:log STATE=all ALL=true           # All runs (any state)
task git:runs:log RUN_ID=12345678              # Specific run
task git:runs:log WORKFLOW="Tests" STATE=all   # All test runs

# Pin GitHub Actions to commit SHAs
task git:actions:pin                           # Check for unpinned actions
task git:actions:pin UPGRADE=1                 # Upgrade and pin actions
task git:actions:pin CHECK=1                   # Check only (no changes)

# Security scanning
task git:leaks                                 # Scan for secrets
task git:cve MIN_SEVERITY=medium               # Download CVEs
```

**Features:**

- Automatically pushes branch if not on remote
- Loads GitHub token from 1Password if configured
- Parses title from `# Heading` in markdown file
- Opens PR in browser after creation
- Cross-platform browser opening (macOS, Linux, Windows)
- Workflow log aggregation and filtering
- GitHub Actions pinning for security

**Requirements:**

- GitHub CLI (`gh`) must be installed: `brew install gh`
- `GITHUB_TOKEN` or `GH_TOKEN` environment variable must be set
- PR file must exist with format:

  ```markdown
  # PR Title

  PR body content here...
  ```

### Security Scanning ([security.yml](security.yml))

Local SAST (Static Application Security Testing) scanning with semgrep and secret detection.

**Commands:**

| Task                       | Alias | Description                      |
| -------------------------- | ----- | -------------------------------- |
| `task security:scan`       | `s`   | Run semgrep security scanner     |
| `task security:fix`        | `f`   | Auto-fix security issues         |
| `task security:trufflehog` | `th`  | Scan for secrets with truffleHog |

**Usage:**

```bash
# Run security scanner
task security:scan

# Auto-fix security issues
task security:fix

# Scan for secrets
task security:trufflehog
```

**Features:**

- Semgrep integration for SAST scanning
- Auto-fix capability for common security issues
- Secret scanning with truffleHog
- Automatic tool installation if not present
- Integration with 1Password for API tokens

**Requirements:**

- Semgrep installed: `pip install semgrep` or `brew install semgrep`
- truffleHog installed: `brew install trufflehog` (auto-installed if missing)

### SonarQube Code Quality ([sonar.yml](sonar.yml))

SonarQube/SonarCloud integration for code quality analysis and issue management.

**Commands:**

| Task                  | Alias | Description                    |
| --------------------- | ----- | ------------------------------ |
| `task sonar:scan`     | `s`   | Run SonarQube analysis locally |
| `task sonar:download` | `dl`  | Download issues from SonarQube |
| `task sonar:issues`   | `i`   | Display downloaded findings    |
| `task sonar:setup`    | -     | Install sonar-scanner CLI      |

**Usage:**

```bash
# Download analysis results
task sonar:download

# View downloaded findings
task sonar:issues

# Run local scan
task sonar:scan

# Install sonar-scanner
task sonar:setup
```

**Features:**

- Downloads complete analysis results from SonarQube/SonarCloud
- Generates human-readable reports in `.logs/sonar/`
- PR-specific analysis support
- Quality gate status tracking
- Security hotspot reporting
- Coverage metrics integration
- Auto-opens reports in VSCode

**Configuration:**

- Set `SONAR_TOKEN` in `.env` file
- Supports 1Password references: `op://vault/item/field`
- Project key read from `sonar-project.properties`

**Requirements:**

- SonarQube/SonarCloud project configured
- `SONAR_TOKEN` environment variable set
- `sonar-project.properties` file in repository root
- GitHub CLI (`gh`) for PR detection

### AWS CLI Operations ([aws.yml](aws.yml))

Utilities for AWS SSO authentication and credential management.

**Commands:**

| Task             | Alias | Description                           |
| ---------------- | ----- | ------------------------------------- |
| `task aws:login` | `l`   | Check and refresh AWS SSO credentials |

**Usage:**

```bash
# Login with profile from environment or .env
task aws:login

# Login with specific profile
task aws:login PROFILE=my-profile

# Using AWS_PROFILE environment variable
export AWS_PROFILE=my-profile
task aws:login
```

**Features:**

- Checks if credentials are valid before prompting
- Loads profile from parameter, environment, or `.env` file
- Integrates with 1Password for secret management
- Only prompts for SSO login if credentials expired

**Requirements:**

- AWS CLI v2 must be installed
- AWS SSO must be configured in `~/.aws/config`
- `AWS_PROFILE` must be set via parameter, environment, or `.env` file

## Environment Setup

Tasks assume the following tools are available:

- **bun** >= 1.0.0 (primary runtime)
- **Node.js** >= 18.0.0 (fallback)
- **Git** >= 2.0.0
- **1Password CLI** (optional, for secret management)
- **Claude CLI** (optional, for MCP tasks)
- **GoTask** >= 3.0.0

Install GoTask:

```bash
# macOS
brew install go-task

# Linux
sh -c "$(curl -fsSL https://taskfile.dev/install.sh)" -- -d

# Windows
choco install go-task
```

## Troubleshooting

### Task not found

```bash
# Verify task exists
task --list | grep task-name

# Check task file is included in main Taskfile.yml
cat Taskfile.yml | grep "includes:"
```

### Script execution fails

```bash
# Check file permissions
ls -la tasks/scripts/category/script.ts

# Make executable if needed
chmod +x tasks/scripts/category/script.ts

# Run script directly to see errors
bun run tasks/scripts/category/script.ts
```

### 1Password tasks fail

```bash
# Check 1Password CLI is installed
which op
op --version

# Verify authentication
op account list

# Sign in if needed
op signin
```

## Related Documentation

- [Main README](../README.md) - Project overview
- [CONTRIBUTING](../CONTRIBUTING.md) - Development guidelines
- [Installation Guide](../docs/installer.md) - AI Toolkit usage
- [1Password Integration](../docs/1password.md) - Secret management setup
- [CLAUDE.md](../CLAUDE.md) - Project instructions for Claude Code

---

**Need help?** Run `task` to see all available task categories, or `task <category>` to see category-specific tasks.