initial commit

Author: nalgeon

.github/workflows/build.yml

@@ -0,0 +1,29 @@
+name: build
+
+on:
+    push:
+        branches: [main]
+        paths-ignore:
+            - README.md
+    pull_request:
+        branches: [main]
+    workflow_dispatch:
+
+jobs:
+    build:
+        name: Build and test
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Setup Go
+              uses: actions/setup-go@v5
+              with:
+                  go-version-file: "go.mod"
+
+            - name: Build and Test
+              run: |
+                  go get .
+                  go build -v .
+                  go test -v ./...

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Zhiyanov <https://github.com/nalgeon/howto>
+
+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.

Makefile

@@ -0,0 +1,14 @@
+BUILD_TAG := $(shell git describe --tags)
+
+.PHONY: build
+build:
+	@go build -ldflags "-X main.version=$(BUILD_TAG)" -o howto
+
+.PHONY: test
+test:
+	@go test ./...
+
+.PHONY: lint
+lint:
+	@go vet ./...
+	@golangci-lint run --print-issued-lines=false --out-format=colored-line-number ./...

README.md

@@ -0,0 +1,173 @@
+## Howto - a humble command-line assistant
+
+Howto helps you solve command-line tasks with AI. Describe the task, and `howto` will suggest a solution:
+
+```text
+$ howto curl example.org but print only the headers
+curl -I example.org
+
+The `curl` command is used to transfer data from or to a server.
+The `-I` option tells `curl` to fetch the HTTP headers only, without the body
+content.
+```
+
+Howto works with any OpenAI-compatible provider and local Ollama models (coming soon). It's a simple tool that doesn't interfere with your terminal. Not an "intelligent terminal" or anything. You ask, and howto answers. That's the deal.
+
+```text
+Usage: howto [-h] [-v] [-run] [question]
+
+A humble command-line assistant.
+
+Options:
+  -h, --help      Show this help message and exit
+  -v, --version   Show version information and exit
+  -run            Run the last suggested command
+  question        Describe the task to get a command suggestion
+                  Use '+' to ask a follow up question
+```
+
+There are some additional features you may find useful. See the Usage section for details.
+
+## Installation
+
+### Go install
+
+This method is preferred if you have Go installed:
+
+```text
+go install github.com/nalgeon/howto@latest
+```
+
+### Manual
+
+`howto` is a binary executable file (`howto.exe` on Windows, `howto` on Linux/macOS). Download it from the link below, unpack and put somewhere in your `PATH` ([what's that?](https://gist.github.com/nex3/c395b2f8fd4b02068be37c961301caa7)), so you can run it from anyhwere on your computer.
+
+[**Download**](https://github.com/nalgeon/howto/releases/latest)
+
+**Note for macOS users**. macOS disables unsigned binaries and prevents the `howto` from running. To resolve this issue, remove the build from quarantine by running the following command in Terminal (replace `/path/to/folder` with an actual path to the folder containing the `howto` binary):
+
+```text
+xattr -d com.apple.quarantine /path/to/folder/howto
+```
+
+## Configuration
+
+Howto is configured using environment variables. It can use cloud AIs or local Ollama models (coming soon).
+
+Cloud AI providers charge for using their API, except for Gemini, which offers a free plan but may use your data in their products. Ollama is free without conditions but uses your machine's CPU or GPU resources.
+
+Here's how to set up an AI provider:
+
+### OpenAI
+
+1. Get an API key from the [OpenAI Settings](https://platform.openai.com/account/api-keys).
+2. Save the key to the `HOWTO_AI_TOKEN` environment variable.
+3. Optionally set the `HOWTO_AI_MODEL` environment variable to the model name you want to use (default is `gpt-4o`).
+
+### OpenAI-compatible provider
+
+Anything like [OpenRouter](https://openrouter.ai/docs/), [Nebius](https://docs.nebius.com/studio/inference/api) or [Gemini](https://ai.google.dev/gemini-api/docs/openai):
+
+1. Obtain an API endpoint from the documentation and save it to the `HOWTO_AI_URL` environment variable. Here are the endpoints for common providers:
+
+-   OpenRouter: `https://openrouter.ai/api/v1/chat/completions`
+-   Nebius: `https://api.studio.nebius.ai/v1/chat/completions`
+-   Gemini: `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`
+
+2. Get an API key from the provider and save it to the `HOWTO_AI_TOKEN` environment variable.
+3. Set the `HOWTO_AI_MODEL` environment variable to the model name you want to use.
+
+### Ollama (coming soon)
+
+Ollama runs AI models locally on your machine. Here's how to set it up:
+
+1. Download and install [Ollama](https://ollama.com/) for your operating system.
+2. Set the [environment variables](https://github.com/ollama/ollama/blob/main/docs/faq.md#how-do-i-configure-ollama-server) to use less memory:
+
+```text
+OLLAMA_KEEP_ALIVE = 1h
+OLLAMA_FLASH_ATTENTION = 1
+```
+
+3. Restart Ollama.
+4. Download the AI model Gemma 2 (or another model of your choice):
+
+```text
+ollama pull gemma2:2b
+```
+
+5. Set the `HOWTO_AI_VENDOR` environment variable to `ollama`.
+6. Set the `HOWTO_AI_MODEL` environment variable to `gemma2:2b` (or another model of your choice).
+
+Gemma 2 is a lightweight model that uses about 1GB of memory and works quickly without a GPU.
+
+### Other settings
+
+-   `HOWTO_AI_TEMPERATURE`. Sampling temperature to use (between 0 and 2). Higher values make the output more random, while lower values make it more focused and predictable. Default: 0
+-   `HOWTO_AI_TIMEOUT`. Timeout for AI API requests in seconds. Default: 30
+-   `HOWTO_PROMPT`. The system prompt for the AI.
+
+To see the system prompt and other settings, run `howto -v`.
+
+## Usage
+
+Describe your task to `howto`, and it will provide an answer:
+
+```text
+$ howto curl example.org but print only the headers
+curl -I example.org
+
+The `-I` option in `curl` is used to fetch the HTTP headers only, without the response body.
+```
+
+### Follow-ups
+
+If you're not satisfied with an answer, refine it or ask a follow-up question by starting with `+`:
+
+```text
+$ howto a command that works kinda like diff but compares differently
+comm file1 file2
+
+The `comm` command compares two sorted files line by line and outputs three
+columns: lines unique to the first file, lines unique to the second file, and
+lines common to both files.
+
+$ howto + yeah right i need only the intersection
+comm -12 file1 file2
+
+The `comm` command compares two sorted files line by line.
+The `-12` option suppresses the first and second columns, showing only lines
+common to both files (the intersection).
+```
+
+If you don't use `+`, howto will forget the previous conversation and treat your question as new.
+
+### Run command
+
+When satisfied with the suggested command, run `howto -run` to execute it without manually copying and pasting:
+
+```text
+$ howto curl example.org but print only the headers
+curl -I example.org
+
+The `curl` command is used to transfer data from or to a server.
+The `-I` option tells `curl` to fetch the HTTP headers only, without the body
+content.
+
+$ howto -run
+curl -I example.org
+
+HTTP/1.1 200 OK
+Content-Type: text/html
+ETag: "84238dfc8092e5d9c0dac8ef93371a07:1736799080.121134"
+Last-Modified: Mon, 13 Jan 2025 20:11:20 GMT
+Cache-Control: max-age=2804
+Date: Sun, 09 Feb 2025 12:54:51 GMT
+Connection: keep-alive
+```
+
+That's it!
+
+## License
+
+Created by [Anton Zhiyanov](https://antonz.org/). Released under the MIT License.

ai/ai.go

@@ -0,0 +1,69 @@
+// Package ai is responsible for interacting with the cloud AI
+// or local Ollama models. It provides a simple vender-agnostic
+// interface to ask questions and get answers.
+package ai
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+)
+
+// AskFunc is a function that sends a question to the AI.
+type AskFunc func(history []string) (string, error)
+
+// Ask sends a question to the AI and returns the answer.
+// It uses the configuration prompt and conversation history
+// to create a message for the AI.
+// Ask is the main interface of the ai package.
+var Ask AskFunc
+
+// Conf describes the AI configuration.
+var Conf Config
+
+// HTTP client used to make requests to the AI.
+var httpClient *http.Client
+
+// message represents a single message in the conversation.
+type message struct {
+	Role    string `json:"role"`
+	Content string `json:"content"`
+}
+
+func init() {
+	// Load the configuration.
+	config, err := loadConfig()
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	Conf = config
+
+	// Set the Ask function based on the vendor.
+	switch config.Vendor {
+	case "openai":
+		Ask = openai{config}.Ask
+	default:
+		fmt.Println("Unknown AI vendor:", config.Vendor)
+		os.Exit(1)
+	}
+
+	// Create an HTTP client with a timeout.
+	httpClient = &http.Client{
+		Timeout: config.Timeout,
+	}
+}
+
+// buildMessages constructs a list of messages from the prompt
+// and the conversation history (a sequence of user and assistant messages).
+func buildMessages(prompt string, history []string) []message {
+	var messages []message
+	messages = append(messages, message{Role: "system", Content: prompt})
+	for i := 0; i < len(history); i += 2 {
+		messages = append(messages, message{Role: "user", Content: history[i]})
+		if i+1 < len(history) {
+			messages = append(messages, message{Role: "assistant", Content: history[i+1]})
+		}
+	}
+	return messages
+}

ai/ai_test.go

@@ -0,0 +1,71 @@
+package ai
+
+import (
+	"reflect"
+	"testing"
+)
+
+func Test_buildMessages(t *testing.T) {
+	prompt := "You are a helpful assistant."
+
+	tests := []struct {
+		name    string
+		history []string
+		want    []message
+	}{
+		{
+			name:    "No history",
+			history: []string{},
+			want: []message{
+				{Role: "system", Content: prompt},
+			},
+		},
+		{
+			name:    "Single user message",
+			history: []string{"Hello"},
+			want: []message{
+				{Role: "system", Content: prompt},
+				{Role: "user", Content: "Hello"},
+			},
+		},
+		{
+			name:    "User and assistant message",
+			history: []string{"Hello", "Hi there!"},
+			want: []message{
+				{Role: "system", Content: prompt},
+				{Role: "user", Content: "Hello"},
+				{Role: "assistant", Content: "Hi there!"},
+			},
+		},
+		{
+			name:    "Multiple user and assistant messages",
+			history: []string{"Hello", "Hi there!", "How are you?", "I'm fine, thank you."},
+			want: []message{
+				{Role: "system", Content: prompt},
+				{Role: "user", Content: "Hello"},
+				{Role: "assistant", Content: "Hi there!"},
+				{Role: "user", Content: "How are you?"},
+				{Role: "assistant", Content: "I'm fine, thank you."},
+			},
+		},
+		{
+			name:    "Odd number of messages",
+			history: []string{"Hello", "Hi there!", "How are you?"},
+			want: []message{
+				{Role: "system", Content: prompt},
+				{Role: "user", Content: "Hello"},
+				{Role: "assistant", Content: "Hi there!"},
+				{Role: "user", Content: "How are you?"},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := buildMessages(prompt, tt.history)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("Expected: %v, got: %v", tt.want, got)
+			}
+		})
+	}
+}