tour/finish
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

-init-

Browse Source
This commit is contained in:
mike
2025-12-11 01:53:06 +01:00
parent 56bc1cb21b
commit 3f9acb08ec
4 changed files with 4 additions and 707 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
PUBLISHING.md
View File

@@ -1,365 +0,0 @@
# Publishing Guide for finish.sh
This guide explains how to publish and distribute finish.sh through various channels.
## Overview
finish.sh can be distributed through multiple channels:
1. **Direct installation script** - One-line curl install
2. **Debian/Ubuntu packages** - APT repository
3. **Homebrew** - macOS package manager
4. **Docker** - Container images
5. **GitHub Releases** - Direct downloads
## Prerequisites
Before publishing, ensure:
- [ ] All tests pass (`./run_tests.sh`)
- [ ] Version numbers are updated in all files
- [ ] CHANGELOG.md is updated
- [ ] Documentation is complete and accurate
## Version Management
Update version numbers in these files:
1. `finish.sh` - Line 34: `export ACSH_VERSION=0.5.0`
2. `debian/changelog` - Add new entry
3. `homebrew/finish.rb` - Line 6: `version "0.5.0"`
4. `docs/install.sh` - Line 7: `ACSH_VERSION="v0.5.0"`
5. `Dockerfile` - Line 6: `LABEL version="0.5.0"`
## 1. Direct Installation Script
The install script at `docs/install.sh` enables one-line installation:
```bash
curl -sSL https://git.appmodel.nl/tour/finish/raw/branch/main/docs/install.sh | bash
```
### Setup:
- Host the script on a reliable server or GitHub/GitLab
- Ensure the URL is accessible and supports HTTPS
- Test the installation on clean systems
### Testing:
```bash
# Test in Docker
docker run --rm -it ubuntu:22.04 bash
curl -sSL YOUR_URL/install.sh | bash
```
## 2. Debian/Ubuntu Packages
### Building the Package
```bash
# Install build tools
sudo apt-get install debhelper devscripts
# Build the package
dpkg-buildpackage -us -uc -b
# This creates:
# ../finish_0.5.0-1_all.deb
```
### Testing the Package
```bash
# Install locally
sudo dpkg -i ../finish_*.deb
sudo apt-get install -f # Fix dependencies
# Test installation
finish --help
finish install
```
### Creating an APT Repository
#### Option A: Using Packagecloud (Recommended for beginners)
1. Sign up at https://packagecloud.io
2. Create a repository
3. Upload your .deb file:
```bash
gem install package_cloud
package_cloud push yourname/finish/ubuntu/jammy ../finish_*.deb
```
Users install with:
```bash
curl -s https://packagecloud.io/install/repositories/yourname/finish/script.deb.sh | sudo bash
sudo apt-get install finish
```
#### Option B: Using GitHub Pages + reprepro
1. Create a repository structure:
```bash
mkdir -p apt-repo/{conf,pool,dists}
```
2. Create `apt-repo/conf/distributions`:
```
Origin: finish.sh
Label: finish
Codename: stable
Architectures: all
Components: main
Description: APT repository for finish.sh
```
3. Add packages:
```bash
reprepro -b apt-repo includedeb stable ../finish_*.deb
```
4. Host on GitHub Pages or your server
Users install with:
```bash
echo "deb https://your-domain.com/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/finish.list
curl -fsSL https://your-domain.com/apt-repo/key.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install finish
```
## 3. Homebrew Formula
### Creating a Homebrew Tap
1. Create a GitHub repository: `homebrew-finish`
2. Add the formula to `Formula/finish.rb`
3. Create a release tarball and calculate SHA256:
```bash
git archive --format=tar.gz --prefix=finish-0.5.0/ v0.5.0 > finish-0.5.0.tar.gz
sha256sum finish-0.5.0.tar.gz
```
4. Update the formula with the correct URL and SHA256
5. Test the formula:
```bash
brew install --build-from-source ./homebrew/finish.rb
brew test finish
brew audit --strict finish
```
### Publishing the Tap
Users can install with:
```bash
brew tap yourname/finish
brew install finish
```
Or directly:
```bash
brew install yourname/finish/finish
```
## 4. Docker Images
### Building Images
```bash
# Production image
docker build -t finish:0.5.0 -t finish:latest .
# Test image
docker build -f Dockerfile.test -t finish:test .
```
### Publishing to GitHub Container Registry
The GitHub Actions workflow automatically publishes Docker images when you push a tag:
```bash
git tag -a v0.5.0 -m "Release v0.5.0"
git push origin v0.5.0
```
Images will be available at:
```
ghcr.io/appmodel/finish:0.5.0
ghcr.io/appmodel/finish:latest
```
### Publishing to Docker Hub
```bash
# Login
docker login
# Tag and push
docker tag finish:latest yourname/finish:0.5.0
docker tag finish:latest yourname/finish:latest
docker push yourname/finish:0.5.0
docker push yourname/finish:latest
```
## 5. GitHub Releases
### Automated Release Process
The `.github/workflows/release.yml` workflow automatically:
1. Creates release artifacts when you push a tag
2. Builds Debian packages
3. Publishes Docker images
4. Creates a GitHub release with downloads
### Manual Release Process
1. Create a release tarball:
```bash
git archive --format=tar.gz --prefix=finish-0.5.0/ v0.5.0 > finish-0.5.0.tar.gz
```
2. Create release on GitHub:
- Go to Releases → Draft a new release
- Tag: `v0.5.0`
- Title: `finish.sh v0.5.0`
- Upload: tarball and .deb file
- Write release notes
## Release Checklist
Before releasing a new version:
- [ ] Update all version numbers
- [ ] Update CHANGELOG.md
- [ ] Run all tests
- [ ] Test installation script
- [ ] Build and test Debian package
- [ ] Test Docker images
- [ ] Update documentation
- [ ] Create git tag
- [ ] Push tag to trigger CI/CD
- [ ] Verify GitHub release created
- [ ] Verify Docker images published
- [ ] Update Homebrew formula with new SHA256
- [ ] Test installation from all sources
- [ ] Announce release (if applicable)
## Distribution URLs
After publishing, users can install from:
**Quick Install:**
```bash
curl -sSL https://git.appmodel.nl/tour/finish/raw/branch/main/docs/install.sh | bash
```
**Homebrew:**
```bash
brew tap appmodel/finish
brew install finish
```
**APT (if configured):**
```bash
sudo apt-get install finish
```
**Docker:**
```bash
docker pull ghcr.io/appmodel/finish:latest
```
**Direct Download:**
```
https://git.appmodel.nl/tour/finish/releases/latest
```
## Troubleshooting
### Debian Package Issues
**Problem:** Package won't install
```bash
# Check dependencies
dpkg-deb -I finish_*.deb
# Test installation
sudo dpkg -i finish_*.deb
sudo apt-get install -f
```
**Problem:** Lintian warnings
```bash
lintian finish_*.deb
# Fix issues in debian/ files
```
### Homebrew Issues
**Problem:** Formula audit fails
```bash
brew audit --strict ./homebrew/finish.rb
# Fix issues reported
```
**Problem:** Installation fails
```bash
brew install --verbose --debug ./homebrew/finish.rb
```
### Docker Issues
**Problem:** Build fails
```bash
docker build --no-cache -t finish:test .
```
**Problem:** Image too large
```bash
# Use multi-stage builds
# Remove unnecessary files
# Combine RUN commands
```
## Continuous Integration
The project includes three GitHub Actions workflows:
1. **test.yml** - Runs on every push/PR
- Runs BATS tests
- Tests installation
- Runs shellcheck
- Tests Docker builds
2. **docker.yml** - Builds and publishes Docker images
- Triggered by tags and main branch
- Publishes to GitHub Container Registry
3. **release.yml** - Creates releases
- Triggered by version tags
- Builds all artifacts
- Creates GitHub release
- Publishes packages
## Support and Documentation
- Update the README.md with installation instructions
- Maintain CHANGELOG.md with version history
- Create issue templates for bug reports and feature requests
- Set up discussions for community support
## Security Considerations
- Always use HTTPS for installation scripts
- Sign Debian packages with GPG
- Use checksums for release artifacts
- Regularly update dependencies
- Monitor for security vulnerabilities
## Next Steps
After initial publication:
1. Monitor GitHub issues for user feedback
2. Set up analytics if desired
3. Create documentation site
4. Announce on relevant forums/communities
5. Consider submitting to package manager directories

201
SUMMARY.md
View File

@@ -1,201 +0,0 @@
# Publication Setup Summary
This document summarizes the publication setup completed for finish.sh.
## Files Created
### 1. Installation Script
- **`docs/install.sh`** - Enhanced one-line installer with:
- Dependency checking
- Shell detection (bash/zsh)
- Color-coded output
- Error handling
- PATH management
- Usage: `curl -sSL <URL>/install.sh | bash`
### 2. Debian Package Structure
Complete Debian packaging in `debian/` directory:
- **`control`** - Package metadata and dependencies
- **`rules`** - Build instructions
- **`changelog`** - Version history
- **`copyright`** - License information
- **`compat`** - Debhelper compatibility level
- **`postinst`** - Post-installation script
- **`source/format`** - Package format specification
Build command: `dpkg-buildpackage -us -uc -b`
### 3. Homebrew Formula
- **`homebrew/finish.rb`** - Homebrew formula for macOS
- Includes dependencies, installation steps, and caveats
- Update SHA256 after creating releases
### 4. Docker Configuration
- **`Dockerfile`** - Production container image
- **`Dockerfile.test`** - Testing container with BATS
- **`docker-compose.yml`** - Multi-service Docker setup
- **`.dockerignore`** - Excludes unnecessary files from builds
### 5. GitHub Actions Workflows
CI/CD automation in `.github/workflows/`:
- **`test.yml`** - Runs tests on every push/PR
- **`release.yml`** - Creates releases and builds packages
- **`docker.yml`** - Builds and publishes Docker images
### 6. Documentation
- **`PUBLISHING.md`** - Comprehensive publishing guide
- **`README.md`** - Updated with installation methods
- **`.gitignore`** - Updated to exclude build artifacts
## Distribution Channels
### 1. Quick Install (Recommended)
```bash
curl -sSL https://git.appmodel.nl/tour/finish/raw/branch/main/docs/install.sh | bash
```
### 2. Debian/Ubuntu Package
Users can install the `.deb` file:
```bash
sudo dpkg -i finish_*.deb
sudo apt-get install -f
```
Or from an APT repository (when configured):
```bash
sudo apt-get install finish
```
### 3. Homebrew (macOS)
```bash
brew tap closedloop-technologies/finish
brew install finish
```
### 4. Docker
```bash
docker pull ghcr.io/closedloop-technologies/finish:latest
docker run -it ghcr.io/closedloop-technologies/finish:latest
```
### 5. From Source
```bash
git clone https://git.appmodel.nl/tour/finish.git
cd finish
./finish.sh install
```
## Next Steps
### Immediate Actions
1. **Test the installation script** on clean systems
2. **Build and test the Debian package**:
```bash
dpkg-buildpackage -us -uc -b
sudo dpkg -i ../finish_*.deb
```
3. **Test Docker builds**:
```bash
docker build -t finish:test .
docker run -it finish:test
```
### For First Release
1. **Update version numbers** in:
- `finish.sh` (line 34)
- `debian/changelog`
- `homebrew/finish.rb`
- `docs/install.sh`
- `Dockerfile`
2. **Create release tarball**:
```bash
git archive --format=tar.gz --prefix=finish-0.5.0/ v0.5.0 > finish-0.5.0.tar.gz
```
3. **Calculate SHA256** for Homebrew:
```bash
sha256sum finish-0.5.0.tar.gz
```
4. **Create and push tag**:
```bash
git tag -a v0.5.0 -m "Release v0.5.0"
git push origin v0.5.0
```
This triggers GitHub Actions to build everything automatically.
### Setting Up Package Repositories
#### APT Repository Options:
1. **Packagecloud** (easiest):
- Sign up at https://packagecloud.io
- Upload .deb file
- Users get one-line install
2. **GitHub Pages** (free):
- Use `reprepro` to create repository
- Host on GitHub Pages
- Users add your repository to sources
See `PUBLISHING.md` for detailed instructions.
#### Homebrew Tap:
1. Create GitHub repo: `homebrew-finish`
2. Add formula to `Formula/finish.rb`
3. Users install with: `brew tap yourname/finish && brew install finish`
## Testing Checklist
Before releasing:
- [ ] Test install script on Ubuntu 22.04
- [ ] Test install script on Debian 12
- [ ] Test install script on macOS
- [ ] Build Debian package successfully
- [ ] Install and test Debian package
- [ ] Build Docker image successfully
- [ ] Run BATS tests in Docker
- [ ] Test Homebrew formula (if applicable)
- [ ] Verify all version numbers match
- [ ] Test GitHub Actions workflows
## Automation
The GitHub Actions workflows handle:
- **On every push/PR**: Run tests, lint code, build Docker images
- **On version tag push**: Build packages, create release, publish Docker images
This means once set up, releasing a new version is as simple as:
```bash
git tag -a v0.5.1 -m "Release v0.5.1"
git push origin v0.5.1
```
Everything else happens automatically!
## Support Channels
Consider setting up:
- GitHub Issues for bug reports
- GitHub Discussions for Q&A
- Documentation website (GitHub Pages)
- Discord/Slack community (optional)
## Resources
- Debian Packaging Guide: https://www.debian.org/doc/manuals/maint-guide/
- Homebrew Formula Cookbook: https://docs.brew.sh/Formula-Cookbook
- GitHub Actions Documentation: https://docs.github.com/en/actions
- Docker Best Practices: https://docs.docker.com/develop/dev-best-practices/
## Conclusion
Your project is now fully set up for publication with:
- ✅ One-line installation script
- ✅ Debian/Ubuntu package support
- ✅ Homebrew formula for macOS
- ✅ Docker containers
- ✅ Automated CI/CD with GitHub Actions
- ✅ Comprehensive documentation
All distribution channels are ready. Follow the "Next Steps" section above to test and publish your first release!

140
USAGE.md
View File

@@ -1,140 +0,0 @@
# Usage Guide
## Installation
Install and set up finish:
```bash
finish install
source ~/.bashrc
```
## Configuration
View current settings:
```bash
finish config
```
Change settings:
```bash
finish config set temperature 0.5
finish config set endpoint http://plato.lan:1234/v1/chat/completions
finish config set model your-model-name
```
Reset to defaults:
```bash
finish config reset
```
## Model Selection
Select a model interactively:
```bash
finish model
```
Use arrow keys to navigate, Enter to select, or 'q' to quit.
## Basic Commands
Show help:
```bash
finish --help
```
Test completions without caching:
```bash
finish command "your command here"
```
Preview the prompt sent to the model:
```bash
finish command --dry-run "your command here"
```
View system information:
```bash
finish system
```
## Usage Statistics
Check your usage stats and costs:
```bash
finish usage
```
## Cache Management
Clear cached completions and logs:
```bash
finish clear
```
## Enable/Disable
Temporarily disable:
```bash
finish disable
```
Re-enable:
```bash
finish enable
```
## Uninstallation
Remove finish completely:
```bash
finish remove
```
## Using finish
Once enabled, just type a command and press `Tab` twice to get suggestions:
```bash
git <TAB><TAB>
docker <TAB><TAB>
find <TAB><TAB>
```
Natural language also works:
```bash
# convert video to mp4 <TAB><TAB>
# list all processes using port 8080 <TAB><TAB>
# compress this folder to tar.gz <TAB><TAB>
```
## Configuration File
The config file is located at `~/.finish/config` and contains:
- `provider`: Model provider (lmstudio, ollama)
- `model`: Model name
- `temperature`: Response randomness (0.0 - 1.0)
- `endpoint`: API endpoint URL
- `api_prompt_cost`: Cost per input token
- `api_completion_cost`: Cost per output token
- `max_history_commands`: Number of recent commands to include in context
- `max_recent_files`: Number of recent files to include in context
- `cache_dir`: Directory for cached completions
- `cache_size`: Maximum number of cached items
- `log_file`: Path to usage log file

5
finish.sh
View File

@@ -228,7 +228,10 @@ $prompt"
}')
;;
*)
payload=$(echo "$base_payload" | jq '. + {response_format: {type: "json_object"}}')
# Default OpenAI-compatible providers increasingly expect
# response_format.type to be either "text" or a json_schema.
# Use "text" for maximum compatibility to avoid 400 errors.
payload=$(echo "$base_payload" | jq '. + {response_format: {type: "text"}}')
;;
esac
echo "$payload"