@napisani/scute 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nick
+
+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.

package/README.md

@@ -0,0 +1,327 @@
+# scute - AI Shell Assistant
+
+## Purpose / Goal
+
+`scute` is a CLI companion for your shell. It adds fast, context-aware command generation, suggestion, and explanation directly in your terminal workflow. The goal is to reduce friction when crafting commands by:
+
+- Generating commands from natural language prompts
+- Suggesting completions for partially typed commands
+- Explaining commands without disrupting your prompt
+- Integrating through lightweight keybindings and shell hooks
+
+The name comes from the scute, the protective shell plate on a turtle, and the tool itself is meant to assist with shell commands.
+Scute is built as a single native binary (via Bun) so it can be distributed and updated easily.
+
+## Installation
+
+Supported platforms: macOS and Linux (x86_64 only for now).
+
+### A. Install via curl (install.sh)
+
+Convenience installer (requires `curl` and `tar`):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/napisani/scute/main/scripts/install.sh | bash
+```
+
+By default it installs into `/usr/local/bin` and pulls the latest release. Pass `vX.Y.Z` and a custom directory to override.
+
+### B. Homebrew
+
+```sh
+brew tap napisani/scute https://github.com/napisani/scute
+brew install scute
+```
+
+### C. npm / npx
+
+Install globally:
+
+```sh
+npm install -g @napisani/scute
+```
+
+Or run once with:
+
+```sh
+npx @napisani/scute --help
+```
+
+> The npm package runs a Bun-based `postinstall` script to download the matching release binary, so Bun must be available on your `PATH`.
+
+### D. Nix
+
+Add the repo as an input and use it in your Home Manager flake:
+
+```nix
+inputs.scute.url = "github:napisani/scute";
+
+outputs = { self, nixpkgs, scute, ... }: {
+  homeConfigurations.me = nixpkgs.lib.homeManagerConfiguration {
+    # ...
+    packages = [ scute.packages.${pkgs.system}.default ];
+  };
+};
+```
+
+> The repository ships an intentionally minimal `flake.nix`. Run `nix flake lock --update-input scute` inside your own workspace to pin exact revisions.
+
+### E. Prebuilt binaries (manual)
+
+Every Git tag publishes `x86_64` macOS and Linux archives on the [GitHub Releases](https://github.com/napisani/scute/releases) page. Download the archive for your platform, unpack it, and move the `scute` binary onto your `PATH`:
+
+```sh
+curl -L -o scute.tar.gz "https://github.com/napisani/scute/releases/download/vX.Y.Z/scute-vX.Y.Z-macos-x86_64.tar.gz"
+tar -xzf scute.tar.gz
+sudo mv scute /usr/local/bin/
+```
+
+Verify downloads with the checksums shipped alongside each release:
+
+```sh
+curl -LO https://github.com/napisani/scute/releases/download/vX.Y.Z/checksums.txt
+grep scute-vX.Y.Z-macos-x86_64.tar.gz checksums.txt | shasum -a 256 -c -
+```
+
+### F. Install from source
+
+```sh
+git clone https://github.com/napisani/scute.git
+cd scute
+bun install --frozen-lockfile
+bun run build:bin
+sudo mv dist/scute /usr/local/bin/
+```
+
+If you prefer Make targets:
+
+```sh
+make build
+sudo mv dist/scute /usr/local/bin/
+```
+
+## Configuration
+
+Scute reads configuration from `~/.config/scute/config.yaml` by default. You can override it per invocation with `--config <path>`.
+
+### Precedence
+
+1. `--config <path>` (explicit CLI override)
+2. Environment variables (provider keys, defaults)
+3. Config file defaults (schema defaults)
+
+Notes:
+- `dotenv/config` is loaded at startup, so values in `.env` will be respected.
+- Provider env vars (e.g., `OPENAI_API_KEY`) merge into `providers` and override matching entries.
+
+### Minimal config example
+
+```yaml
+# ~/.config/scute/config.yaml
+
+# Use a compact view for the token editor
+viewMode: horizontal
+
+# Define at least one provider for prompts
+providers:
+  - name: openai
+    apiKey: ${OPENAI_API_KEY}
+
+# Optional: adjust shell keybindings (universal syntax)
+shellKeybindings:
+  explain: "Ctrl+E"
+  build: "Ctrl+G"
+  suggest: "Ctrl+Shift+E"
+```
+
+### Fully configured example
+
+```yaml
+# ~/.config/scute/config.yaml
+
+# Layout for the interactive token editor
+viewMode: horizontal # horizontal -> annotated view, vertical -> list view
+
+# Clipboard command for output channel "clipboard"
+clipboardCommand: "pbcopy"
+
+# Providers used by prompts (env vars override these)
+providers:
+  - name: openai
+    apiKey: ${OPENAI_API_KEY}
+  - name: anthropic
+    apiKey: ${ANTHROPIC_API_KEY}
+  - name: gemini
+    apiKey: ${GEMINI_API_KEY}
+  - name: ollama
+    baseUrl: ${OLLAMA_BASE_URL}
+
+# Keybindings for the interactive token editor UI
+keybindings:
+  up: ["up"]
+  down: ["down"]
+  left: ["left", "h"]
+  right: ["right", "l"]
+  wordForward: ["w"]
+  wordBackward: ["b"]
+  lineStart: ["0", "^"]
+  lineEnd: ["$"]
+  firstToken: ["g"]
+  lastToken: ["G"]
+  appendLine: ["A"]
+  explain: ["e"]
+  toggleView: ["m"]
+  insert: ["i"]
+  append: ["a"]
+  change: ["c"]
+  exitInsert: ["escape"]
+  save: ["return"]
+
+# Shell keybindings in universal syntax (rendered by scute init)
+shellKeybindings:
+  explain: "Ctrl+E"
+  build: "Ctrl+G"
+  suggest: "Ctrl+Shift+E"
+  generate: [] # disable if you do not want a binding
+
+# Theme colors (catppuccin defaults shown)
+theme:
+  tokenColors:
+    command: "#A6E3A1"
+    option: "#FAB387"
+    argument: "#89B4FA"
+    assignment: "#CBA6F7"
+    pipe: "#94E2D5"
+    controlOperator: "#F38BA8"
+    redirect: "#CDD6F4"
+    unknown: "#6C7086"
+  tokenDescription: "#CDD6F4"
+  markerColor: "#CDD6F4"
+
+# Prompt behavior per command
+prompts:
+  explain:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+    maxTokens: 128000
+    userPrompt: ""
+    systemPromptOverride: ""
+  suggest:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+    maxTokens: 128000
+  generate:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+    maxTokens: 128000
+  describeTokens:
+    provider: openai
+    model: gpt-4
+    temperature: 0.7
+    maxTokens: 128000
+```
+
+### Environment variables
+
+Provider credentials and defaults:
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY`
+- `OLLAMA_BASE_URL`
+- `SCUTE_DEFAULT_PROVIDER`
+- `SCUTE_DEFAULT_MODEL`
+
+Runtime behavior:
+
+- `SCUTE_DEBUG` (set to `1` or `true` for verbose logging)
+- `SCUTE_SHELL` (override detected shell name)
+- `SHELL` (standard shell env var)
+- `READLINE_LINE` (readline current line, when present)
+
+## Shell Integration
+
+`scute` integrates with your shell via a script that needs to be loaded by your shell's configuration file (e.g., `.bashrc`).
+
+### For Bash
+
+Add the following line to the end of your `~/.bashrc` file:
+
+```sh
+eval "$(scute init bash)"
+```
+
+After adding the line, restart your terminal or run `source ~/.bashrc` to apply the changes.
+
+### For Nix/home-manager Users
+
+If you use `home-manager` to manage your dotfiles, you cannot edit `.bashrc` directly. Instead, add the following to your `home.nix` configuration:
+
+```nix
+programs.bash = {
+  enable = true;
+  bashrcExtra = ''
+    eval "$(scute init bash)"
+  '';
+};
+```
+
+Then, run `home-manager switch` to apply the configuration.
+
+## Debug Logging
+
+Set `SCUTE_DEBUG=1` to enable verbose logs. When enabled, `scute` writes detailed traces to `/tmp/scute.log`:
+
+```sh
+export SCUTE_DEBUG=1
+tail -f /tmp/scute.log
+```
+
+### Inspect Resolved Configuration
+
+Use the `config-debug` subcommand to print the fully resolved configuration (including environment overrides). This is useful when troubleshooting provider settings or custom config files:
+
+```sh
+scute --config configs/ollama-config.yml config-debug
+```
+
+The command prints a JSON payload containing the merged configuration and relevant environment variables.
+
+## Testing
+
+Test files use the `.test.ts` suffix. Evaluation tests use `.eval.test.ts` and live in the `evals/` directory.
+
+```sh
+# Run standard unit tests
+bun run test
+
+# Run evaluation tests
+bun run evals
+
+# Or via Make targets
+make test
+```
+
+## Usage
+
+Once installed and configured, you can use the following keyboard shortcuts in your terminal:
+
+- **`Ctrl + G`**: **Suggest Completion**. Takes the current command you are typing, sends it to the AI for completion, and replaces the line with the AI's suggestion.
+- **`Ctrl + P`**: **Suggest from Prompt**. Replaces your current line with a command generated by the AI based on a prompt. (Note: The current implementation is a stub).
+- **`Ctrl + E`**: **Explain Command**. Reads the command on the current line and displays a helpful, non-interfering explanation on the line below your prompt.
+
+## Release Process (Maintainers)
+
+1. Update `package.json` version.
+2. Ensure your working tree is clean and Bun is installed.
+3. Run `make release`.
+   - Runs lint and tests, builds the binary, tags `vX.Y.Z`, pushes the tag, and publishes to npm.
+4. GitHub Actions builds macOS/Linux archives and uploads them to the release.
+5. Refresh Homebrew checksums:
+
+```sh
+make update-brew VERSION=vX.Y.Z
+```

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@napisani/scute",
+  "version": "0.0.1",
+  "description": "AI-powered shell assistant",
+  "module": "index.ts",
+  "type": "module",
+  "keywords": [
+    "shell",
+    "ai",
+    "explain",
+    "bash",
+    "zsh",
+    "suggestion",
+    "tui"
+  ],
+  "homepage": "https://github.com/napisani/scute",
+  "bugs": {
+    "url": "https://github.com/napisani/scute/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/napisani/scute.git"
+  },
+  "license": "MIT",
+  "author": "Nick Pisani",
+  "main": "index.js",
+  "bin": {
+    "scute": "dist/scute"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "files": [
+    "dist/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run build:bin",
+    "build:bin": "bun build ./src/index.ts --compile --outfile dist/scute",
+    "clean": "rm -rf dist",
+    "lint": "bunx tsc --noEmit",
+    "test": "bun test tests/",
+    "coverage": "bun test tests/ --coverage",
+    "evals": "bun test evals --pattern \\\"\\.eval\\.test\\.ts$\\\"",
+    "prepublishOnly": "bun run clean && bun install --frozen-lockfile && bun run lint && bun run test",
+    "postinstall": "bun scripts/postinstall.ts"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.75",
+    "@opentui/react": "^0.1.75",
+    "@tanstack/ai": "^0.2.2",
+    "@tanstack/ai-anthropic": "^0.2.0",
+    "@tanstack/ai-gemini": "^0.3.2",
+    "@tanstack/ai-ollama": "^0.3.0",
+    "@tanstack/ai-openai": "^0.2.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "js-yaml": "^4.1.1",
+    "react": "^19.2.4",
+    "shell-quote": "^1.8.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.12",
+    "@testing-library/react": "^16.3.2",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^25.0.10",
+    "@types/react": "^19.2.9",
+    "@types/shell-quote": "^1.7.5",
+    "happy-dom": "^20.5.0",
+    "jsdom": "^28.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
+}

package/scripts/install.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="napisani/scute"
+
+if ! command -v curl >/dev/null 2>&1; then
+	echo "curl is required" >&2
+	exit 1
+fi
+
+case "$VERSION" in
+v*) ;;
+*) VERSION="v$VERSION" ;;
+esac
+
+if ! command -v tar >/dev/null 2>&1; then
+	echo "tar is required" >&2
+	exit 1
+fi
+
+if [ "${1:-}" = "--help" ]; then
+	cat <<EOF
+Usage: install.sh [version] [install-dir]
+
+version     Git tag to install (default: latest release)
+install-dir Directory to place the scute binary (default: /usr/local/bin)
+EOF
+	exit 0
+fi
+
+VERSION="${1:-latest}"
+INSTALL_DIR="${2:-/usr/local/bin}"
+
+if [ "$VERSION" = "latest" ]; then
+	VERSION=$(curl -fsSL https://api.github.com/repos/${REPO}/releases/latest | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
+	if [ -z "$VERSION" ]; then
+		echo "Unable to determine latest release tag" >&2
+		exit 1
+	fi
+fi
+
+ARCH=$(uname -m)
+OS=$(uname -s)
+
+case "$OS" in
+Linux) PLATFORM="linux" ;;
+Darwin) PLATFORM="macos" ;;
+*)
+	echo "Unsupported OS: $OS" >&2
+	exit 1
+	;;
+esac
+
+if [ "$ARCH" != "x86_64" ]; then
+	echo "Currently only x86_64 binaries are published." >&2
+	exit 1
+fi
+
+TARBALL="scute-${VERSION}-${PLATFORM}-${ARCH}.tar.gz"
+URL="https://github.com/${REPO}/releases/download/${VERSION}/${TARBALL}"
+
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+echo "Downloading ${URL}"
+curl -fsSL "$URL" -o "$TMP_DIR/$TARBALL"
+
+tar -xzf "$TMP_DIR/$TARBALL" -C "$TMP_DIR"
+
+mkdir -p "$INSTALL_DIR"
+install -m 755 "$TMP_DIR/scute" "$INSTALL_DIR/scute"
+
+echo "scute installed to $INSTALL_DIR/scute"

package/scripts/postinstall.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env bun
+
+import { access, chmod, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+async function buildFromSource(distDir: string, binaryPath: string) {
+	console.warn(
+		`[scute] No prebuilt binary available for ${process.platform}/${process.arch}. Building from source...`,
+	);
+	await mkdir(distDir, { recursive: true });
+	const build = Bun.spawn(["bun", "run", "build:bin"], {
+		stdout: "inherit",
+		stderr: "inherit",
+	});
+	const exitCode = await build.exited;
+	if (exitCode !== 0) {
+		build.kill();
+		throw new Error("Failed to build binary from source.");
+	}
+	try {
+		await access(binaryPath);
+	} catch {
+		throw new Error(
+			"Build completed but the scute binary was not created at dist/scute.",
+		);
+	}
+	await chmod(binaryPath, 0o755);
+}
+
+async function main() {
+	const version = Bun.env.npm_package_version;
+	if (!version || version === "0.0.0-development") {
+		console.warn("[scute] Skipping postinstall: unknown package version.");
+		return;
+	}
+
+	const platform = process.platform;
+	if (platform !== "darwin" && platform !== "linux") {
+		throw new Error(
+			`Unsupported platform '${platform}'. scute distributes binaries for macOS and Linux only.`,
+		);
+	}
+
+	// Ensure tar is available
+	const tarCheck = Bun.spawn(["tar", "--version"], {
+		stdout: "ignore",
+		stderr: "ignore",
+	});
+	if ((await tarCheck.exited) !== 0) {
+		tarCheck.kill();
+		throw new Error(
+			"`tar` is required to install scute. Please ensure it is available on PATH.",
+		);
+	}
+
+	const archMap: Record<string, string> = {
+		x64: "x86_64",
+	};
+	const distDir = join(import.meta.dir, "..", "dist");
+	await mkdir(distDir, { recursive: true });
+
+	const binaryPath = join(distDir, "scute");
+	try {
+		await access(binaryPath);
+		return; // Already present (e.g. local install)
+	} catch {
+		// continue
+	}
+
+	const detected = archMap[process.arch] ?? null;
+	if (!detected) {
+		await buildFromSource(distDir, binaryPath);
+		return;
+	}
+
+	const osName = platform === "darwin" ? "macos" : "linux";
+	const tag = version.startsWith("v") ? version : `v${version}`;
+	const tarball = `scute-${tag}-${osName}-${detected}.tar.gz`;
+	const url = `https://github.com/napisani/scute/releases/download/${tag}/${tarball}`;
+
+	console.log(`[scute] Downloading ${url}`);
+	const response = await fetch(url);
+	if (!response.ok) {
+		if (response.status === 404) {
+			await buildFromSource(distDir, binaryPath);
+			return;
+		}
+		throw new Error(
+			`[scute] Failed to download binary from ${url} (${response.status} ${response.statusText})`,
+		);
+	}
+
+	const tmpFile = join(tmpdir(), `${tarball}.${process.pid}.tmp`);
+	const buffer = await response.arrayBuffer();
+	await Bun.write(tmpFile, buffer);
+
+	const extract = Bun.spawn(["tar", "-xzf", tmpFile, "-C", distDir]);
+	const exitCode = await extract.exited;
+	if (exitCode !== 0) {
+		extract.kill();
+		throw new Error("[scute] Failed to extract downloaded archive.");
+	}
+
+	await chmod(binaryPath, 0o755);
+	await rm(tmpFile, { force: true });
+}
+
+await main().catch((error) => {
+	console.error(`[scute] Postinstall error: ${error.message}`);
+	process.exit(1);
+});

package/scripts/update-brew.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+	echo "Usage: $0 <version>" >&2
+	exit 1
+fi
+
+VERSION="$1"
+case "$VERSION" in
+v*) TAG="$VERSION" ;;
+*) TAG="v$VERSION" ;;
+esac
+
+if ! command -v curl >/dev/null 2>&1; then
+	echo "curl is required" >&2
+	exit 1
+fi
+
+if ! command -v sha256sum >/dev/null 2>&1; then
+	if command -v shasum >/dev/null 2>&1; then
+		sha256sum() { shasum -a 256 "$@"; }
+	else
+		echo "sha256sum or shasum is required" >&2
+		exit 1
+	fi
+fi
+
+REPO="napisani/scute"
+
+download_and_sha() {
+	local platform="$1"
+	local arch="x86_64"
+	local url="https://github.com/${REPO}/releases/download/${TAG}/scute-${TAG}-${platform}-${arch}.tar.gz"
+	local tmp
+	tmp=$(mktemp)
+	curl -fsSL "$url" -o "$tmp"
+	local sum
+	sum=$(sha256sum "$tmp" | awk '{print $1}')
+	rm -f "$tmp"
+	echo "$sum"
+}
+
+MAC_SHA=$(download_and_sha macos)
+LINUX_SHA=$(download_and_sha linux)
+
+FORMULA="Formula/scute.rb"
+
+perl -0pi -e 's/version "[^"]+"/version "'"${TAG#v}"'"/' "$FORMULA"
+perl -0pi -e 's/(on_macos do\n\s+url ".*"\n\s+sha256 ")[^"]+("/\1'"$MAC_SHA"'\2/' "$FORMULA"
+perl -0pi -e 's/(on_linux do\n\s+url ".*"\n\s+sha256 ")[^"]+("/\1'"$LINUX_SHA"'\2/' "$FORMULA"
+
+echo "Updated $FORMULA with version ${TAG#v}"