Skip to content

Commit 2352000

Browse files
1shooperman1shooperman
authored
feat: have claude add the github-docs pages. (#12)
1 parent 3458797 commit 2352000

11 files changed

Lines changed: 372 additions & 0 deletions

File tree

‎docs/Gemfile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
source "https://rubygems.org"
2+
3+
gem "github-pages", group: :jekyll_plugins
4+
gem "jekyll-remote-theme"

‎docs/_config.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
title: cli-tools
2+
description: Personal shell utilities for git hygiene, GPG, video conversion, and Claude plugin static analysis.
3+
remote_theme: just-the-docs/just-the-docs@v0.10.1
4+
url: https://1shooperman.github.io
5+
baseurl: /cli-tools
6+
7+
# Nav order for top-level pages
8+
nav_order_default: 1
9+
10+
plugins:
11+
- jekyll-remote-theme
12+
13+
# Just the Docs config
14+
search_enabled: true
15+
heading_anchors: true
16+
color_scheme: dark
17+
18+
footer_content: "MIT License &mdash; <a href=\"https://github.com/1shooperman/cli-tools\">1shooperman/cli-tools</a>"

‎docs/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
layout: home
3+
title: Home
4+
nav_order: 1
5+
---
6+
7+
# cli-tools
8+
9+
Personal shell utilities for git branch hygiene, GPG cache warming, video conversion, and Claude plugin static analysis.
10+
11+
## Quick install
12+
13+
```sh
14+
brew tap 1shooperman/tap
15+
brew install cli-tools
16+
```
17+
18+
All commands are placed on your `$PATH` automatically. See [Installation](installation) for manual setup and dependencies.
19+
20+
---
21+
22+
## Tools at a glance
23+
24+
| Command | What it does |
25+
|---------|-------------|
26+
| [`gitprune`](tools/gitprune) | Deletes stale local branches and compacts the repo |
27+
| [`gitrefresh`](tools/gitrefresh) | Resets to a clean, up-to-date state against any branch |
28+
| [`cache-gpg`](tools/cache-gpg) | Warms the GPG agent cache before a signing flow |
29+
| [`convert-video`](tools/convert-video) | Converts any video file to H.264/AAC MP4 via ffmpeg |
30+
| [`sast`](tools/sast) | Static analysis for Claude plugin `allowed-tools` frontmatter |
31+
| [`gh-actions-sast`](tools/gh-actions-sast) | Checks GitHub Actions workflows for outdated action pins |

‎docs/installation.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
layout: default
3+
title: Installation
4+
nav_order: 2
5+
---
6+
7+
# Installation
8+
9+
## Homebrew (recommended)
10+
11+
```sh
12+
brew tap 1shooperman/tap
13+
brew install cli-tools
14+
```
15+
16+
All commands are placed on your `$PATH` automatically.
17+
18+
---
19+
20+
## Manual
21+
22+
Clone the repo and add `bin/` to your `$PATH`:
23+
24+
```sh
25+
git clone https://github.com/1shooperman/cli-tools.git
26+
export PATH="$PATH:/path/to/cli-tools/bin"
27+
```
28+
29+
Add the `export` line to your shell rc file (`.zshrc`, `.bashrc`, etc.) to persist it across sessions.
30+
31+
---
32+
33+
## Dependencies
34+
35+
Some commands require external tools. Install only what you need:
36+
37+
| Tool | Required by | Install |
38+
|------|-------------|---------|
39+
| `ffmpeg` | `convert-video` | `brew install ffmpeg` |
40+
| `gpg` | `cache-gpg` | `brew install gnupg` |
41+
| `git` | `gitprune`, `gitrefresh` | ships with macOS |

‎docs/tools/cache-gpg.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: default
3+
title: cache-gpg
4+
parent: Tools
5+
nav_order: 3
6+
---
7+
8+
# cache-gpg
9+
10+
Warms the GPG agent cache by performing a throwaway clearsign operation.
11+
12+
## Usage
13+
14+
```sh
15+
cache-gpg
16+
```
17+
18+
No arguments. No output on success.
19+
20+
## Why
21+
22+
`git commit -S` prompts for your GPG passphrase when the agent cache is cold. Running `cache-gpg` before your commit flow pre-unlocks the key so the signing step doesn't interrupt with a passphrase prompt.
23+
24+
## What it does
25+
26+
Pipes the string `"test"` through `gpg --clearsign` and discards the output. That is enough to unlock the key and populate the agent cache for the configured cache TTL.
27+
28+
## Requirements
29+
30+
| Requirement | Install |
31+
|-------------|---------|
32+
| `gpg` installed and a signing key configured | `brew install gnupg` |
33+
| GPG agent running | started automatically by `gpg` on modern systems |

‎docs/tools/convert-video.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
layout: default
3+
title: convert-video
4+
parent: Tools
5+
nav_order: 4
6+
---
7+
8+
# convert-video
9+
10+
Converts a video file to H.264/AAC MP4 using ffmpeg.
11+
12+
## Usage
13+
14+
```sh
15+
convert-video [--silent] <input-file>
16+
```
17+
18+
## Arguments
19+
20+
| Argument | Description |
21+
|----------|-------------|
22+
| `input-file` | Path to the source video file (any format ffmpeg can read) |
23+
| `--silent` | Suppress ffmpeg output |
24+
25+
## Examples
26+
27+
```sh
28+
convert-video recording.mov # → recording.mp4
29+
convert-video --silent clip.avi # → clip.mp4, no output
30+
```
31+
32+
Output is written to the same directory as the input with the extension replaced by `.mp4`.
33+
34+
## Encoding settings
35+
36+
| Stream | Codec | Settings |
37+
|--------|-------|----------|
38+
| Video | `libx264` | CRF 23, `medium` preset |
39+
| Audio | `aac` | 128k bitrate |
40+
41+
CRF 23 is the ffmpeg default and gives a good quality/size balance for most content.
42+
43+
## Requirements
44+
45+
| Requirement | Install |
46+
|-------------|---------|
47+
| `ffmpeg` | `brew install ffmpeg` |

‎docs/tools/gh-actions-sast.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: default
3+
title: gh-actions-sast
4+
parent: Tools
5+
nav_order: 6
6+
---
7+
8+
# gh-actions-sast
9+
10+
Scans GitHub Actions workflow files for action references pinned below a minimum version.
11+
12+
## Usage
13+
14+
```sh
15+
gh-actions-sast
16+
```
17+
18+
Must be run from the repository root. Scans `.github/workflows/*.yml` automatically — no arguments needed.
19+
20+
## What it does
21+
22+
Walks every `.yml` file under `.github/workflows/` and checks each `uses:` line for `actions/*@vN` references. Any action pinned below `v6` is flagged.
23+
24+
## Output
25+
26+
| Severity | Condition |
27+
|----------|-----------|
28+
| ERROR | Action version is below `v6` |
29+
| WARN | Action is below `v6` but present in the exclude list |
30+
31+
```
32+
ERROR ci.yml: actions/checkout@v4 is below v6
33+
WARN ci.yml: actions/some-action@v3 is below v6 (excluded)
34+
```
35+
36+
## Exit codes
37+
38+
| Code | Meaning |
39+
|------|---------|
40+
| `0` | No ERROR findings |
41+
| `1` | One or more ERROR findings |
42+
43+
## Notes
44+
45+
- Only matches the pattern `actions/<name>@v<number>` — SHA-pinned or tag-pinned refs are not checked
46+
- Passes cleanly when `.github/workflows/` does not exist
47+
- Non-`.yml` files in `.github/workflows/` are skipped
48+
- Pairs with [`sast`](sast) for broader CI security coverage

‎docs/tools/gitprune.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
layout: default
3+
title: gitprune
4+
parent: Tools
5+
nav_order: 1
6+
---
7+
8+
# gitprune
9+
10+
Deletes local git branches that no longer exist on the remote, then runs garbage collection and prunes stale remote-tracking refs.
11+
12+
## Usage
13+
14+
```sh
15+
gitprune # safe delete
16+
gitprune --force # force delete unmerged branches too
17+
```
18+
19+
## Flags
20+
21+
| Flag | Behavior |
22+
|------|----------|
23+
| _(none)_ | Uses `git branch -d` — refuses to delete unmerged branches |
24+
| `--force` | Uses `git branch -D` — deletes unmerged branches regardless |
25+
26+
## What it does
27+
28+
1. Lists remote branches
29+
2. Compares against local tracking branches
30+
3. Deletes any local branch with no matching remote
31+
4. Runs `git gc --prune=now` and `git fetch -p` to clean up stale refs
32+
5. Runs `git gc` again for a final compaction
33+
34+
Output from gc and fetch is collapsed into a single overwriting status line so it doesn't flood your terminal.
35+
36+
## Notes
37+
38+
- Safe to run frequently — without `--force` it will never delete a branch with unmerged commits
39+
- `gitrefresh` calls `gitprune --force` automatically at the end of its flow

‎docs/tools/gitrefresh.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
layout: default
3+
title: gitrefresh
4+
parent: Tools
5+
nav_order: 2
6+
---
7+
8+
# gitrefresh
9+
10+
Resets a local clone to a clean, up-to-date state against any branch, then prunes stale local branches.
11+
12+
## Usage
13+
14+
```sh
15+
gitrefresh # resets to main
16+
gitrefresh dev # resets to dev
17+
```
18+
19+
## Arguments
20+
21+
| Argument | Default | Description |
22+
|----------|---------|-------------|
23+
| `branch` | `main` | Branch to check out and pull |
24+
25+
## What it does
26+
27+
1. Checks out `branch`
28+
2. Fetches from origin
29+
3. Pulls latest
30+
4. Runs `gitprune --force` **twice** — the second pass catches branches whose delete tracking refs were only cleaned up by the first pass
31+
32+
All git output is collapsed into a single overwriting status line.
33+
34+
## Notes
35+
36+
`gitrefresh` is a "nuke and reset" convenience — it force-prunes unmerged branches. Use plain `gitprune` if you want to keep unmerged work.

‎docs/tools/index.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
layout: default
3+
title: Tools
4+
nav_order: 3
5+
has_children: true
6+
---
7+
8+
# Tools
9+
10+
cli-tools provides six commands covering git hygiene, GPG, video conversion, and static analysis.
11+
12+
| Command | Summary |
13+
|---------|---------|
14+
| [gitprune](gitprune) | Delete stale local branches and compact the repo |
15+
| [gitrefresh](gitrefresh) | Reset to a clean, up-to-date state |
16+
| [cache-gpg](cache-gpg) | Warm the GPG agent cache |
17+
| [convert-video](convert-video) | Convert video to H.264/AAC MP4 |
18+
| [sast](sast) | Scan Claude plugin frontmatter for risky tool grants |
19+
| [gh-actions-sast](gh-actions-sast) | Check GitHub Actions for outdated action pins |

0 commit comments

Comments
 (0)