@napisani/scute 0.0.2 → 0.0.4

package/README.md

@@ -10,13 +10,21 @@
 - 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.
+
+Scute is built with Bun and can be installed via npm (requires Bun), Homebrew, or downloaded as a prebuilt binary.
 
 ## Installation
 
-Supported platforms: macOS and Linux (x86_64 only for now).
+Supported platforms: macOS and Linux (x86_64 and arm64).
+
+### A. Homebrew (Recommended - Prebuilt Binary)
 
-### A. Install via curl (install.sh)
+```sh
+brew tap napisani/scute https://github.com/napisani/scute
+brew install scute
+```
+
+### B. Install via curl (install.sh)
 
 Convenience installer (requires `curl` and `tar`):
 
@@ -26,14 +34,23 @@ curl -fsSL https://raw.githubusercontent.com/napisani/scute/main/scripts/install
 
 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
+### C. bunx / bun (Requires Bun)
+
+Install globally:
 
 ```sh
-brew tap napisani/scute https://github.com/napisani/scute
-brew install scute
+bun install -g @napisani/scute
 ```
 
-### C. npm / npx
+Or run once with:
+
+```sh
+bunx @napisani/scute --help
+```
+
+> **Note:** The npm package requires Bun to be installed on your system. Install Bun from [bun.sh](https://bun.sh).
+
+### D. npm / npx (Requires Bun)
 
 Install globally:
 
@@ -47,9 +64,9 @@ Or run once with:
 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`.
+> **Note:** The npm package requires Bun to be installed on your system.
 
-### D. Nix
+### E. Nix
 
 Add the repo as an input and use it in your Home Manager flake:
 
@@ -66,12 +83,12 @@ outputs = { self, nixpkgs, scute, ... }: {
 
 > 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)
+### F. 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`:
+Every Git tag publishes macOS (x86_64, arm64) and Linux (x86_64) 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"
+curl -L -o scute.tar.gz "https://github.com/napisani/scute/releases/download/vX.Y.Z/scute-vX.Y.Z-macos-arm64.tar.gz"
 tar -xzf scute.tar.gz
 sudo mv scute /usr/local/bin/
 ```
@@ -80,10 +97,10 @@ 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 -
+grep scute-vX.Y.Z-macos-arm64.tar.gz checksums.txt | shasum -a 256 -c -
 ```
 
-### F. Install from source
+### G. Install from Source
 
 ```sh
 git clone https://github.com/napisani/scute.git
@@ -93,7 +110,7 @@ bun run build:bin
 sudo mv dist/scute /usr/local/bin/
 ```
 
-If you prefer Make targets:
+Or use Make targets:
 
 ```sh
 make build
@@ -315,13 +332,53 @@ Once installed and configured, you can use the following keyboard shortcuts in y
 
 ## 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:
+### Creating a New Release
+
+1. **Update the version** in `package.json` (e.g., `"version": "0.0.4"`)
+2. **Commit the version change**: `git commit -am "Bump version to 0.0.4"`
+3. **Create the release** (this creates the git tag and triggers CI):
+   ```sh
+   make release-create
+   ```
+   This will:
+   - Run lint and tests
+   - Create and push git tag `v0.0.4`
+   - Trigger GitHub Actions to build binaries
+
+4. **Wait for CI** to complete (GitHub Actions builds and uploads binaries to the release)
+
+5. **Publish to npm**:
+   ```sh
+   make release-publish
+   ```
+
+6. **Update Homebrew formula** (after CI finishes):
+   ```sh
+   make update-brew-latest
+   ```
+   Or specify a version explicitly:
+   ```sh
+   make update-brew VERSION=v0.0.4
+   ```
+
+### Full Release (Create + Publish)
+
+To do it all in one command:
+```sh
+make release
+```
+
+### What Gets Published
+
+- **npm**: Source code (TypeScript/Bun) - users need Bun installed
+- **GitHub Release**: Prebuilt binaries for macOS (x86_64, arm64) and Linux (x86_64)
+- **Homebrew**: Points to the GitHub release binaries
+
+### Pre-release Testing
 
+For testing before publishing:
 ```sh
-make update-brew VERSION=vX.Y.Z
+# Create a prerelease tag (contains '-')
+make release-create
+# CI will mark it as prerelease automatically
 ```

package/bin/scute

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/index.ts";

package/package.json

@@ -1,87 +1,86 @@
 {
-  "name": "@napisani/scute",
-  "version": "0.0.2",
-  "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"
-  ]
+	"name": "@napisani/scute",
+	"version": "0.0.4",
+	"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": "src/index.ts",
+	"bin": {
+		"scute": "bin/scute"
+	},
+	"directories": {
+		"test": "tests"
+	},
+	"files": [
+		"bin/",
+		"src/",
+		"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 lint && bun run test"
+	},
+	"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": {
+		"bun": ">=1.0.0"
+	},
+	"os": [
+		"darwin",
+		"linux"
+	]
 }

package/src/commands/build.tsx

@@ -0,0 +1,69 @@
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { emitOutput, type OutputChannel } from "../core/output";
+import { getReadlineLine, hasReadlineLine } from "../core/shells";
+import { BuildApp } from "../pages/build";
+import { promptForLine } from "../utils/prompt";
+
+export interface BuildOptions {
+	output: OutputChannel;
+}
+
+export function resolveBuildCommand(
+	inputParts: string[],
+	options: { hasReadlineLine: boolean; readlineLine: string | null },
+): string {
+	const positionalCommand = inputParts.join(" ").trim();
+	if (positionalCommand.length > 0) {
+		return positionalCommand;
+	}
+	if (options.hasReadlineLine && options.readlineLine) {
+		return options.readlineLine;
+	}
+	return "";
+}
+
+export async function build(
+	inputParts: string[] = [],
+	{ output }: BuildOptions,
+) {
+	const isLine = hasReadlineLine();
+	const readlineLine = getReadlineLine();
+	let command = resolveBuildCommand(inputParts, {
+		hasReadlineLine: isLine,
+		readlineLine,
+	});
+	if (command.length === 0) {
+		if (process.stdin.isTTY) {
+			command = await promptForLine({
+				message: "Enter a command to start building: ",
+			});
+		} else {
+			command = await readAllStdin();
+		}
+	}
+	const renderer = await createCliRenderer();
+	let didSubmit = false;
+	const handleSubmit = (nextCommand: string) => {
+		if (didSubmit) {
+			return;
+		}
+		didSubmit = true;
+		renderer.destroy();
+		emitOutput({
+			channel: output,
+			text: nextCommand,
+		});
+	};
+	createRoot(renderer).render(
+		<BuildApp command={command} onSubmit={handleSubmit} />,
+	);
+}
+
+async function readAllStdin(): Promise<string> {
+	let input = "";
+	for await (const chunk of process.stdin) {
+		input += chunk;
+	}
+	return input.trim();
+}

package/src/commands/config-debug.ts

@@ -0,0 +1,33 @@
+import { getConfigSnapshot } from "../config";
+import { getEnv, SUPPORTED_ENV_VARS } from "../core/environment";
+import { emitOutput, type OutputChannel } from "../core/output";
+
+type DebugOutput = {
+	config: ReturnType<typeof getConfigSnapshot>;
+	environment: Record<string, string | undefined>;
+};
+
+export interface ConfigDebugOptions {
+	output: OutputChannel;
+}
+
+export function configDebug({ output }: ConfigDebugOptions): void {
+	const resolvedConfig = getConfigSnapshot();
+	const environment: DebugOutput["environment"] = SUPPORTED_ENV_VARS.reduce(
+		(acc, varName) => {
+			acc[varName] = getEnv(varName);
+			return acc;
+		},
+		{} as Record<string, string | undefined>,
+	);
+
+	const payload: DebugOutput = {
+		config: resolvedConfig,
+		environment,
+	};
+
+	emitOutput({
+		channel: output,
+		text: JSON.stringify(payload, null, 2),
+	});
+}

package/src/commands/explain.ts

@@ -0,0 +1,35 @@
+// src/commands/explain.ts
+import { explain as explainCommand } from "../core";
+import { logDebug } from "../core/logger";
+import { emitOutput, type OutputChannel } from "../core/output";
+
+/**
+ * Handles the 'explain' command by calling the AI service.
+ * Renders a non-interfering hint at the bottom of the terminal.
+ * @param line The current READLINE_LINE content.
+ * @param point The current READLINE_POINT (cursor position).
+ */
+export interface ExplainOptions {
+	output: OutputChannel;
+}
+
+export async function explain(
+	line: string,
+	point: string,
+	{ output }: ExplainOptions,
+) {
+	logDebug(`command:explain line="${line}" point=${point}`);
+
+	const explanation = await explainCommand(line);
+	if (explanation === null) {
+		logDebug("command:explain result=null");
+		return;
+	}
+	logDebug("command:explain hint ready");
+	emitOutput({
+		channel: output,
+		text: explanation,
+		promptPrefix: "[scute] ",
+	});
+	logDebug("command:explain output written");
+}

package/src/commands/generate.ts

@@ -0,0 +1,47 @@
+// src/commands/generate.ts
+import { generateCommand } from "../core";
+import { logDebug } from "../core/logger";
+import { emitOutput, type OutputChannel } from "../core/output";
+import { promptForLine } from "../utils/prompt";
+
+export interface GenerateOptions {
+	output: OutputChannel;
+}
+
+export async function generate(
+	inputParts: string[] = [],
+	{ output }: GenerateOptions,
+): Promise<void> {
+	const prompt = await resolvePrompt(inputParts);
+	if (!prompt) {
+		logDebug("command:generate empty prompt");
+		return;
+	}
+	logDebug(`command:generate prompt="${prompt}"`);
+	const suggestion = await generateCommand(prompt);
+	if (suggestion === null) {
+		logDebug("command:generate result=null");
+		return;
+	}
+	emitOutput({
+		channel: output,
+		text: suggestion,
+	});
+	logDebug("command:generate output written");
+}
+
+async function resolvePrompt(inputParts: string[]): Promise<string> {
+	if (inputParts.length) {
+		return inputParts.join(" ").trim();
+	}
+	if (process.stdin.isTTY) {
+		return await promptForLine({
+			message: "Enter a command request: ",
+		});
+	}
+	let input = "";
+	for await (const chunk of process.stdin) {
+		input += chunk;
+	}
+	return input.trim();
+}

package/src/commands/init.ts

@@ -0,0 +1,29 @@
+// src/commands/init.ts
+
+import { getShellKeybindings } from "../config";
+import { emitOutput, type OutputChannel } from "../core/output";
+import { getShellHelperByName, supportedShells } from "../core/shells";
+import type { ShellName } from "../core/shells/common";
+
+export interface InitOptions {
+	output: OutputChannel;
+}
+
+export function init(shell: string, { output }: InitOptions) {
+	if (!supportedShells.includes(shell as ShellName)) {
+		console.error(
+			`Error: Unsupported shell '${shell}'. Supported shells: ${supportedShells.join(
+				", ",
+			)}.`,
+		);
+		process.exit(1);
+	}
+
+	const shellHelper = getShellHelperByName(shell as ShellName);
+	const initScript = shellHelper.getInitScript(getShellKeybindings());
+
+	emitOutput({
+		channel: output,
+		text: initScript,
+	});
+}

package/src/commands/suggest.ts

@@ -0,0 +1,26 @@
+// src/commands/suggest.ts
+import { suggest as suggestCommand } from "../core";
+import { logDebug } from "../core/logger";
+import { emitOutput, type OutputChannel } from "../core/output";
+
+/**
+ * Handles the 'suggest' command by calling the AI service.
+ * @param line The current text from the READLINE_LINE environment variable.
+ */
+export interface SuggestOptions {
+	output: OutputChannel;
+}
+
+export async function suggest(line: string, { output }: SuggestOptions) {
+	logDebug(`command:suggest line="${line}"`);
+	const suggestion = await suggestCommand(line);
+	if (suggestion === null) {
+		logDebug("command:suggest result=null");
+		return;
+	}
+	logDebug(`command:suggest result="${suggestion}"`);
+	emitOutput({
+		channel: output,
+		text: suggestion,
+	});
+}

package/src/components/Footer.tsx

@@ -0,0 +1,41 @@
+import { getKeybindings } from "../config";
+import type { ViewMode, VimMode } from "../hooks/useVimMode";
+import { Spinner } from "./Spinner";
+
+interface FooterProps {
+	mode: VimMode;
+	viewMode: ViewMode;
+	isLoading?: boolean;
+	error?: string | null;
+}
+
+export function Footer({
+	mode,
+	viewMode,
+	isLoading = false,
+	error = null,
+}: FooterProps) {
+	const modeColor = mode === "insert" ? "#00FF00" : "#888";
+	const modeText = mode === "insert" ? "-- INSERT --" : "-- NORMAL --";
+	const toggleViewKey = getKeybindings("toggleView")[0] ?? "m";
+
+	const viewModeHelp =
+		viewMode === "annotated"
+			? "h/l: move, w/b: word, 0/$: line"
+			: "j/k: move, gg/G: jump";
+
+	return (
+		<box height={1} flexDirection="row" gap={2}>
+			<text fg={modeColor}>{modeText}</text>
+			{error ? (
+				<text fg="#F38BA8">{error}</text>
+			) : (
+				<>
+					<text fg="#888">Press '{toggleViewKey}' to toggle view</text>
+					<text fg="#888">{viewModeHelp}</text>
+					<Spinner isActive={isLoading} />
+				</>
+			)}
+		</box>
+	);
+}

package/src/components/Spinner.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+import { getThemeColorFor } from "../config";
+
+type SpinnerProps = {
+	isActive: boolean;
+};
+
+function getSpinnerFrame(index: number): string {
+	const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	return frames[index % frames.length]!;
+}
+
+export function Spinner({ isActive }: SpinnerProps) {
+	const [spinnerIndex, setSpinnerIndex] = useState(0);
+	const markerColor = getThemeColorFor("markerColor");
+
+	useEffect(() => {
+		if (!isActive) {
+			setSpinnerIndex(0);
+			return undefined;
+		}
+		const timer = setInterval(() => {
+			setSpinnerIndex((index) => index + 1);
+		}, 120);
+		return () => clearInterval(timer);
+	}, [isActive]);
+
+	if (!isActive) {
+		return null;
+	}
+
+	return (
+		<box
+			style={{
+				flexDirection: "row",
+				justifyContent: "flex-end",
+				width: "100%",
+			}}
+		>
+			<text fg={markerColor}>{getSpinnerFrame(spinnerIndex)}</text>
+		</box>
+	);
+}