@seanmozeik/vicon 0.1.0

package/README.md

@@ -0,0 +1,207 @@
+# vicon
+
+Describe what you want. Get the shell commands.
+
+Vicon is a CLI that turns plain-English media requests into executable ffmpeg and ImageMagick commands. It detects your installed tools and their capabilities, sends your request to an AI provider, and presents the generated commands for review before running them.
+
+```bash
+vicon "convert video.mp4 to gif at 15fps"
+```
+
+```
+╭──────────── What this does ────────────╮
+│                                        │
+│  Converts your MP4 to an animated GIF  │
+│  at 15 frames per second.              │
+│                                        │
+╰────────────────────────────────────────╯
+
+╭ Commands ──────────────────────────────╮
+│ [1] ffmpeg -i video.mp4 -vf "fps=15,  │
+│     scale=480:-1" video_converted.gif  │
+╰────────────────────────────────────────╯
+
+◆  What would you like to do?
+│  ● Run all
+│  ○ Edit commands
+│  ○ Retry
+│  ○ Edit prompt
+│  ○ Copy
+│  ○ Cancel
+└
+```
+
+## Install
+
+Requires [Bun](https://bun.sh).
+
+**Homebrew:**
+
+```bash
+brew install seanmozeik/tap/vicon
+```
+
+**npm:**
+
+```bash
+bun add -g @seanmozeik/vicon
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/seanmozeik/vicon.git
+cd vicon
+bun install
+bun run build          # compiled binary → ./vicon
+bun run install-local  # moves binary to ~/.local/bin
+```
+
+## Setup
+
+Run `vicon setup` to configure your AI provider.
+
+**Cloudflare AI** requires an account ID and API token. Credentials are stored in your system keychain (macOS Keychain, Linux libsecret).
+
+**Claude Code CLI** requires the `claude` binary on your PATH. No additional credentials needed.
+
+```bash
+vicon setup
+```
+
+```
+◆  Which AI provider?
+│  ● Cloudflare AI (requires Account ID + API token)
+│  ○ Claude Code CLI (requires claude CLI installed)
+└
+```
+
+For headless or CI environments, set the `VICON_CONFIG` environment variable:
+
+```bash
+export VICON_CONFIG='{"defaultProvider":"cloudflare","cloudflare":{"accountId":"...","apiToken":"..."}}'
+```
+
+Linux users need libsecret for keychain storage:
+
+```bash
+# Ubuntu/Debian
+sudo apt install libsecret-1-0 libsecret-tools
+
+# Fedora
+sudo dnf install libsecret
+
+# Arch
+sudo pacman -S libsecret
+```
+
+## Usage
+
+```bash
+vicon "<your request>"
+```
+
+Vicon detects ffmpeg and ImageMagick on startup, inventories their encoders, decoders, and supported formats, and feeds this context to the AI. The generated commands match your actual environment.
+
+### Examples
+
+```bash
+# Video
+vicon "convert video.mp4 to gif at 15fps"
+vicon "extract audio from interview.mov as flac"
+vicon "compress this 4K video to 1080p h265 with good quality"
+
+# Images
+vicon "resize all jpgs in this folder to 800px wide"
+vicon "convert logo.png to webp and avif"
+vicon "strip EXIF data from every image in ./photos"
+
+# Audio
+vicon "split podcast.mp3 into 30-minute chunks"
+vicon "normalize volume across all wav files here"
+```
+
+### Actions
+
+After generation, you choose what happens next:
+
+| Action | Effect |
+|---|---|
+| **Run all** | Executes each command in sequence with live terminal output |
+| **Edit commands** | Opens the commands in a text editor for manual tweaks |
+| **Retry** | Regenerates with the same prompt |
+| **Edit prompt** | Modifies your request and regenerates |
+| **Copy** | Copies all commands to clipboard |
+| **Cancel** | Exits |
+
+### Provider override
+
+Force a specific provider for one invocation:
+
+```bash
+vicon "resize photo.jpg to 50%" --provider claude
+```
+
+### Post-run cleanup
+
+After commands finish, vicon scans for media files referenced in the commands and offers to delete the originals. The default is No.
+
+```
+ℹ  Input files detected:
+     video.mp4
+◆  Delete original files?
+│  ○ Yes / ● No
+└
+```
+
+### Error recovery
+
+If the AI returns an unparseable response, vicon shows the raw output and offers three paths: retry with the same prompt, edit your prompt and retry, or cancel. This loop continues until you get a valid result or walk away.
+
+## Flags
+
+```
+--provider cloudflare|claude   Override the default provider
+--help, -h                     Show usage and examples
+--version, -v                  Print version
+```
+
+## Subcommands
+
+```
+setup       Configure AI provider credentials
+teardown    Remove saved credentials from keychain
+```
+
+## Tool detection
+
+On each run, vicon probes for:
+
+- **ffmpeg**: version, full encoder list, full decoder list
+- **ImageMagick**: version, supported format list
+
+This context goes into the system prompt so the AI only generates commands your system can execute. If a tool is missing, vicon warns you and the AI works around it.
+
+## How it works
+
+1. Parse your request and detect installed tools
+2. Build a system prompt containing tool versions, codecs, and formats
+3. Send the request to Cloudflare AI or Claude Code CLI
+4. Parse the JSON response into commands and a plain-English explanation
+5. Display both in separate panels for review
+6. Execute, edit, retry, copy, or cancel
+
+Generated commands use safe defaults: output files get a `_converted` suffix, existing files are never overwritten silently.
+
+## Development
+
+```bash
+bun install
+bun --hot src/index.ts    # dev mode with hot reload
+bun test                  # run tests
+bun run build             # compile to standalone binary
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@seanmozeik/vicon",
+  "version": "0.1.0",
+  "description": "AI-powered media conversion CLI — describe what you want, get the commands",
+  "type": "module",
+  "bin": {
+    "vicon": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "package.json"
+  ],
+  "keywords": [
+    "media",
+    "conversion",
+    "ffmpeg",
+    "imagemagick",
+    "cli",
+    "ai",
+    "bun"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanmozeik/vicon.git"
+  },
+  "dependencies": {
+    "@clack/prompts": "latest",
+    "boxen": "latest",
+    "gradient-string": "latest",
+    "picocolors": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --compile --outfile vicon --minify",
+    "bundle": "bun build ./src/index.ts --outdir dist --target=bun --bytecode --minify",
+    "dev": "bun --hot src/index.ts",
+    "install-local": "bun run build && mkdir -p ~/.local/bin && mv vicon ~/.local/bin/vicon && chmod +x ~/.local/bin/vicon",
+    "test": "bun test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,523 @@
+import * as p from "@clack/prompts";
+import boxen from "boxen";
+import { generate, ValidationError } from "./lib/ai.js";
+import { copyToClipboard } from "./lib/clipboard.js";
+import type { Provider, ViconConfig } from "./lib/config.js";
+import { deleteConfig, getConfig, setConfig } from "./lib/config.js";
+import { buildSystemPrompt, buildUserPrompt } from "./lib/prompt.js";
+import { runCommands } from "./lib/run.js";
+import { detectContext } from "./lib/tools.js";
+import type { GenerateResult } from "./types.js";
+import { showBanner } from "./ui/banner.js";
+import { boxColors, frappe, theme } from "./ui/theme.js";
+
+// ── Arg parsing ──────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+function popFlag(flags: string[]): string | undefined {
+	for (const flag of flags) {
+		const i = args.indexOf(flag);
+		if (i !== -1) {
+			args.splice(i, 1);
+			return flag;
+		}
+	}
+	return undefined;
+}
+
+function popFlagValue(flag: string): string | undefined {
+	const i = args.indexOf(flag);
+	if (i !== -1 && i + 1 < args.length) {
+		const val = args[i + 1];
+		args.splice(i, 2);
+		return val;
+	}
+	return undefined;
+}
+
+const helpFlag = popFlag(["--help", "-h"]);
+const versionFlag = popFlag(["--version", "-v"]);
+const providerOverride = popFlagValue("--provider") as Provider | undefined;
+
+// ── Help & Version ────────────────────────────────────────────────────────────
+
+if (versionFlag) {
+	const pkg = (await import("../package.json")) as { version: string };
+	console.log(`vicon v${pkg.version}`);
+	process.exit(0);
+}
+
+if (helpFlag) {
+	showBanner();
+	console.log(
+		[
+			"",
+			`  ${theme.heading("Usage:")} vicon <request> [--provider cloudflare|claude]`,
+			"",
+			`  ${theme.heading("Subcommands:")}`,
+			`    ${frappe.sky("setup")}      Configure AI provider credentials`,
+			`    ${frappe.sky("teardown")}   Remove saved credentials`,
+			"",
+			`  ${theme.heading("Flags:")}`,
+			`    ${frappe.sky("--provider")}  Override provider for this invocation`,
+			`    ${frappe.sky("--help")}      Show this help`,
+			`    ${frappe.sky("--version")}   Print version`,
+			"",
+			`  ${theme.heading("Examples:")}`,
+			`    vicon "convert video.mp4 to gif at 15fps"`,
+			`    vicon "resize all jpgs in this folder to 800px wide"`,
+			`    vicon "extract audio from interview.mov as flac" --provider claude`,
+			"",
+		].join("\n"),
+	);
+	process.exit(0);
+}
+
+// ── Subcommands ───────────────────────────────────────────────────────────────
+
+async function setupCloudflare(): Promise<void> {
+	const accountId = await p.text({
+		message: "Cloudflare Account ID:",
+		validate: (v) => (v?.trim() ? undefined : "Required"),
+	});
+	if (p.isCancel(accountId)) {
+		p.cancel("Setup cancelled.");
+		process.exit(0);
+	}
+
+	const apiToken = await p.password({
+		message: "Cloudflare AI API token:",
+		validate: (v) => (v?.trim() ? undefined : "Required"),
+	});
+	if (p.isCancel(apiToken)) {
+		p.cancel("Setup cancelled.");
+		process.exit(0);
+	}
+
+	const config: ViconConfig = {
+		defaultProvider: "cloudflare",
+		cloudflare: {
+			accountId: (accountId as string).trim(),
+			apiToken: (apiToken as string).trim(),
+		},
+	};
+	try {
+		await setConfig(config);
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	p.outro("Cloudflare AI configured and saved.");
+}
+
+async function runSetup(): Promise<void> {
+	showBanner();
+	p.intro("Configure vicon AI provider");
+
+	const provider = await p.select<Provider>({
+		message: "Which AI provider?",
+		options: [
+			{
+				value: "cloudflare" as Provider,
+				label: "Cloudflare AI",
+				hint: "requires Account ID + API token",
+			},
+			{
+				value: "claude" as Provider,
+				label: "Claude Code CLI",
+				hint: "requires claude CLI installed",
+			},
+		],
+	});
+
+	if (p.isCancel(provider)) {
+		p.cancel("Setup cancelled.");
+		process.exit(0);
+	}
+
+	if ((provider as Provider) === "cloudflare") {
+		await setupCloudflare();
+		return;
+	}
+
+	// claude — verify CLI is available
+	const proc = Bun.spawn(["which", "claude"], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	await proc.exited;
+	if (proc.exitCode !== 0) {
+		p.log.error(
+			"claude CLI not found. Install it from https://claude.ai/code and re-run setup.",
+		);
+		process.exit(1);
+	}
+
+	const config: ViconConfig = { defaultProvider: "claude" };
+	try {
+		await setConfig(config);
+	} catch (err) {
+		p.log.error(err instanceof Error ? err.message : String(err));
+		process.exit(1);
+	}
+	p.outro("Claude Code CLI configured and saved.");
+}
+
+async function runTeardown(): Promise<void> {
+	showBanner();
+
+	const confirm = await p.confirm({
+		message: "Delete vicon config from keychain?",
+		initialValue: false,
+	});
+
+	if (p.isCancel(confirm) || !confirm) {
+		p.outro("Teardown cancelled.");
+		process.exit(0);
+	}
+
+	await deleteConfig();
+	p.outro("Config deleted.");
+}
+
+// ── Tool summary line ─────────────────────────────────────────────────────────
+
+type ToolCtx = Awaited<ReturnType<typeof detectContext>>;
+
+function renderToolSummary(ctx: ToolCtx): string {
+	const parts: string[] = [];
+
+	if (ctx.ffmpeg.installed) {
+		const ver = ctx.ffmpeg.version ?? "?";
+		const enc = ctx.ffmpeg.encoders.length;
+		const dec = ctx.ffmpeg.decoders.length;
+		parts.push(
+			theme.muted(`ffmpeg ${ver} (${enc} encoders · ${dec} decoders)`),
+		);
+	} else {
+		parts.push(frappe.yellow("ffmpeg not found"));
+	}
+
+	if (ctx.magick.installed) {
+		const ver = ctx.magick.version ?? "?";
+		const fmt = ctx.magick.formats.length;
+		parts.push(theme.muted(`magick ${ver} (${fmt} formats)`));
+	} else {
+		parts.push(frappe.yellow("magick not found"));
+	}
+
+	return parts.join(theme.muted("  ·  "));
+}
+
+// ── Display panels ────────────────────────────────────────────────────────────
+
+function renderPanels(result: GenerateResult): void {
+	const explanationBox = boxen(result.explanation, {
+		borderColor: boxColors.primary,
+		borderStyle: "round",
+		padding: { top: 1, bottom: 1, left: 2, right: 2 },
+		title: "What this does",
+		titleAlignment: "center",
+	});
+	console.log(`\n${explanationBox}`);
+
+	const numberedCmds = result.commands
+		.map((cmd, i) => `${frappe.sky(`[${i + 1}]`)} ${cmd}`)
+		.join("\n");
+
+	const commandsBox = boxen(numberedCmds, {
+		borderColor: boxColors.default,
+		dimBorder: true,
+		borderStyle: "round",
+		padding: { top: 0, bottom: 0, left: 1, right: 1 },
+		title: "Commands",
+		titleAlignment: "left",
+	});
+	console.log(`\n${commandsBox}\n`);
+}
+
+// ── Post-run cleanup ──────────────────────────────────────────────────────────
+
+const MEDIA_EXT_RE =
+	/\S+\.(?:png|jpg|jpeg|gif|webp|avif|mp4|mov|mkv|mp3|wav|flac|aac)/gi;
+
+function inferInputFiles(commands: string[]): string[] {
+	const files = new Set<string>();
+	for (const cmd of commands) {
+		const matches = cmd.match(MEDIA_EXT_RE);
+		if (matches) {
+			for (const m of matches) files.add(m);
+		}
+	}
+	return [...files];
+}
+
+async function runCleanup(files: string[]): Promise<void> {
+	if (files.length === 0) return;
+
+	p.log.info(`Input files detected:\n  ${files.join("\n  ")}`);
+
+	const confirm = await p.confirm({
+		message: "Delete original files?",
+		initialValue: false,
+	});
+
+	if (p.isCancel(confirm) || !confirm) return;
+
+	for (const file of files) {
+		try {
+			await Bun.$`rm ${file}`;
+			p.log.success(`Deleted ${file}`);
+		} catch {
+			p.log.error(`Failed to delete ${file}`);
+		}
+	}
+}
+
+// ── Conversion helpers ────────────────────────────────────────────────────────
+
+async function tryGenerate(
+	userRequest: string,
+	ctx: ToolCtx,
+	config: ViconConfig,
+): Promise<GenerateResult | null> {
+	const s = p.spinner();
+	s.start("Generating command…");
+	try {
+		const result = await generate(
+			buildSystemPrompt(ctx),
+			buildUserPrompt(userRequest),
+			config,
+		);
+		s.stop("Done.");
+		return result;
+	} catch (err) {
+		s.stop("Failed.");
+		if (err instanceof ValidationError) {
+			p.log.error("Could not parse AI response:");
+			console.log(err.raw);
+		} else {
+			p.log.error(err instanceof Error ? err.message : String(err));
+		}
+		return null;
+	}
+}
+
+// Returns updated request string (same or edited) on retry, null on cancel.
+async function promptErrorRecovery(
+	currentRequest: string,
+): Promise<string | null> {
+	const recovery = await p.select({
+		message: "What would you like to do?",
+		options: [
+			{ value: "retry", label: "Retry", hint: "regenerate with same prompt" },
+			{
+				value: "edit-prompt",
+				label: "Edit prompt",
+				hint: "modify your request and retry",
+			},
+			{ value: "cancel", label: "Cancel" },
+		],
+	});
+	if (p.isCancel(recovery) || recovery === "cancel") return null;
+	if (recovery !== "edit-prompt") return currentRequest;
+
+	const edited = await p.text({
+		message: "Edit your request:",
+		initialValue: currentRequest,
+	});
+	if (p.isCancel(edited)) return null;
+	return edited as string;
+}
+
+// Retries until a successful GenerateResult is obtained or the user cancels.
+async function generateUntilSuccess(
+	initialRequest: string,
+	ctx: ToolCtx,
+	config: ViconConfig,
+): Promise<{ result: GenerateResult; userRequest: string }> {
+	let userRequest = initialRequest;
+	for (;;) {
+		const result = await tryGenerate(userRequest, ctx, config);
+		if (result !== null) return { result, userRequest };
+		const next = await promptErrorRecovery(userRequest);
+		if (next === null) {
+			p.outro("Cancelled.");
+			process.exit(0);
+		}
+		userRequest = next;
+	}
+}
+
+async function handleEditPromptAction(
+	userRequest: string,
+	ctx: ToolCtx,
+	config: ViconConfig,
+): Promise<{ result: GenerateResult; userRequest: string }> {
+	const edited = await p.text({
+		message: "Edit your request:",
+		initialValue: userRequest,
+	});
+	if (p.isCancel(edited)) {
+		p.outro("Cancelled.");
+		process.exit(0);
+	}
+	return generateUntilSuccess(edited as string, ctx, config);
+}
+
+async function handleCopyAction(commands: string[]): Promise<void> {
+	const ok = await copyToClipboard(commands.join("\n"));
+	if (ok) {
+		p.log.success("Commands copied to clipboard.");
+	} else {
+		p.log.warn("No clipboard tool found. Install xclip, xsel, or wl-copy.");
+	}
+	process.exit(0);
+}
+
+async function handleEditCommandsAction(
+	current: GenerateResult,
+): Promise<GenerateResult> {
+	const edited = await p.text({
+		message: "Edit commands (one per line):",
+		initialValue: current.commands.join("\n"),
+	});
+	if (p.isCancel(edited)) {
+		p.outro("Cancelled.");
+		process.exit(0);
+	}
+	const newCommands = (edited as string)
+		.split("\n")
+		.map((l) => l.trim())
+		.filter(Boolean);
+	return { ...current, commands: newCommands };
+}
+
+async function handleRunAction(commands: string[]): Promise<void> {
+	const success = await runCommands(commands, {
+		onBefore: (cmd, i, total) => p.log.step(`▶ [${i + 1}/${total}] ${cmd}`),
+		onSuccess: () => p.log.success("All commands completed successfully."),
+		onError: (cmd, exitCode) =>
+			p.log.error(`Command exited with code ${exitCode}: ${cmd}`),
+	});
+	await runCleanup(inferInputFiles(commands));
+	process.exit(success ? 0 : 1);
+}
+
+// ── Conversion flow ───────────────────────────────────────────────────────────
+
+async function runConversion(
+	initialRequest: string,
+	config: ViconConfig,
+): Promise<void> {
+	const toolSpinner = p.spinner();
+	toolSpinner.start("Detecting tools…");
+	const ctx = await detectContext();
+	toolSpinner.stop("Tools detected.");
+	p.log.info(renderToolSummary(ctx));
+
+	let { result: currentResult, userRequest } = await generateUntilSuccess(
+		initialRequest,
+		ctx,
+		config,
+	);
+	renderPanels(currentResult);
+
+	while (true) {
+		const action = await p.select({
+			message: "What would you like to do?",
+			options: [
+				{ value: "run", label: "Run all" },
+				{
+					value: "edit",
+					label: "Edit commands",
+					hint: "tweak the generated commands",
+				},
+				{ value: "retry", label: "Retry", hint: "regenerate with same prompt" },
+				{
+					value: "edit-prompt",
+					label: "Edit prompt",
+					hint: "modify request and retry",
+				},
+				{ value: "copy", label: "Copy" },
+				{ value: "cancel", label: "Cancel" },
+			],
+		});
+
+		if (p.isCancel(action) || action === "cancel") {
+			p.outro("Cancelled.");
+			process.exit(0);
+		}
+
+		if (action === "retry") {
+			({ result: currentResult, userRequest } = await generateUntilSuccess(
+				userRequest,
+				ctx,
+				config,
+			));
+			renderPanels(currentResult);
+		} else if (action === "edit-prompt") {
+			({ result: currentResult, userRequest } = await handleEditPromptAction(
+				userRequest,
+				ctx,
+				config,
+			));
+			renderPanels(currentResult);
+		} else if (action === "copy") {
+			await handleCopyAction(currentResult.commands);
+		} else if (action === "edit") {
+			currentResult = await handleEditCommandsAction(currentResult);
+			renderPanels(currentResult);
+		} else if (action === "run") {
+			await handleRunAction(currentResult.commands);
+		}
+	}
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const subcommand = args[0];
+
+if (subcommand === "setup") {
+	await runSetup();
+	process.exit(0);
+} else if (subcommand === "teardown") {
+	await runTeardown();
+	process.exit(0);
+} else {
+	// First non-flag positional arg is the conversion request
+	const request = args.find((a) => !a.startsWith("-"));
+
+	// Config is loaded here so --provider override can be applied
+	let config = await getConfig();
+
+	if (providerOverride) {
+		if (config) {
+			config = { ...config, defaultProvider: providerOverride };
+		} else {
+			config = { defaultProvider: providerOverride };
+		}
+	}
+
+	if (!config) {
+		showBanner();
+		p.log.error("No provider configured. Run: vicon setup");
+		process.exit(1);
+	}
+
+	if (config.defaultProvider === "cloudflare" && !config.cloudflare) {
+		showBanner();
+		p.log.error("Cloudflare credentials missing. Run: vicon setup");
+		process.exit(1);
+	}
+
+	showBanner();
+
+	if (!request) {
+		p.log.info("Usage: vicon <request>  |  vicon --help for more");
+		process.exit(0);
+	}
+
+	await runConversion(request, config);
+}

package/src/lib/ai.ts

@@ -0,0 +1,112 @@
+import type { GenerateResult } from "../types.js";
+import type { CloudflareCredentials, ViconConfig } from "./config.js";
+
+export const CF_MODEL = "@cf/openai/gpt-oss-120b";
+export const CLAUDE_MODEL = "sonnet";
+
+export class ValidationError extends Error {
+	constructor(
+		message: string,
+		public readonly raw: string,
+	) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+export function validateResponse(raw: string): GenerateResult {
+	const cleaned = raw
+		.trim()
+		.replace(/^```(?:json)?\n?/, "")
+		.replace(/\n?```$/, "");
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(cleaned);
+	} catch {
+		throw new ValidationError("Invalid JSON response from AI", raw);
+	}
+
+	const obj = parsed as { commands?: unknown; explanation?: unknown };
+	if (
+		!Array.isArray(obj.commands) ||
+		!obj.commands.every((c: unknown) => typeof c === "string") ||
+		typeof obj.explanation !== "string"
+	) {
+		throw new ValidationError(
+			"Response missing required fields: commands (string[]) and explanation (string)",
+			raw,
+		);
+	}
+
+	return { commands: obj.commands as string[], explanation: obj.explanation };
+}
+
+export async function generateWithCloudflare(
+	systemPrompt: string,
+	userPrompt: string,
+	credentials: CloudflareCredentials,
+): Promise<GenerateResult> {
+	const response = await fetch(
+		`https://api.cloudflare.com/client/v4/accounts/${credentials.accountId}/ai/v1/chat/completions`,
+		{
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${credentials.apiToken}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({
+				model: CF_MODEL,
+				messages: [
+					{ role: "system", content: systemPrompt },
+					{ role: "user", content: userPrompt },
+				],
+				response_format: { type: "json_object" },
+				max_tokens: 2048,
+			}),
+		},
+	);
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new Error(`Cloudflare API error ${response.status}: ${error}`);
+	}
+
+	const data = (await response.json()) as {
+		choices?: { message?: { content?: string } }[];
+	};
+
+	const raw = data.choices?.[0]?.message?.content ?? "";
+	return validateResponse(raw);
+}
+
+export async function generateWithClaude(
+	systemPrompt: string,
+	userPrompt: string,
+): Promise<GenerateResult> {
+	const combinedPrompt = `${systemPrompt}\n\n${userPrompt}`;
+	const proc = Bun.spawn(
+		["claude", "--model", CLAUDE_MODEL, "-p", combinedPrompt],
+		{
+			stdout: "pipe",
+		},
+	);
+	const raw = (await new Response(proc.stdout).text()).trim();
+	return validateResponse(raw);
+}
+
+export async function generate(
+	systemPrompt: string,
+	userPrompt: string,
+	config: ViconConfig,
+): Promise<GenerateResult> {
+	if (config.defaultProvider === "cloudflare") {
+		if (!config.cloudflare) {
+			throw new Error(
+				"Cloudflare credentials not configured. Run: vicon setup",
+			);
+		}
+		return generateWithCloudflare(systemPrompt, userPrompt, config.cloudflare);
+	}
+	return generateWithClaude(systemPrompt, userPrompt);
+}

package/src/lib/clipboard.ts

@@ -0,0 +1,40 @@
+import { $ } from "bun";
+
+/**
+ * Copy text to clipboard (cross-platform)
+ * Returns true if successful, false if no clipboard tool available
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+	// macOS
+	if (process.platform === "darwin") {
+		const proc = Bun.spawn(["pbcopy"], { stdin: "pipe" });
+		proc.stdin.write(text);
+		proc.stdin.end();
+		await proc.exited;
+		return true;
+	}
+
+	// Linux: try available clipboard tools in order of preference
+	const tools: string[][] = [
+		["xclip", "-selection", "clipboard"],
+		["xsel", "--clipboard", "--input"],
+		["wl-copy"], // Wayland
+	];
+
+	for (const cmd of tools) {
+		try {
+			const which = await $`which ${cmd[0]}`.quiet();
+			if (which.exitCode === 0) {
+				const proc = Bun.spawn(cmd, { stdin: "pipe" });
+				proc.stdin.write(text);
+				proc.stdin.end();
+				await proc.exited;
+				return true;
+			}
+		} catch {
+			// Tool not found, try next
+		}
+	}
+
+	return false;
+}

package/src/lib/config.ts

@@ -0,0 +1,83 @@
+import { CONFIG_KEY, SECRETS_SERVICE } from "./secrets.js";
+
+export type Provider = "cloudflare" | "claude";
+
+export interface CloudflareCredentials {
+	accountId: string;
+	apiToken: string;
+}
+
+export interface ViconConfig {
+	defaultProvider: Provider;
+	cloudflare?: CloudflareCredentials;
+}
+
+// Three-state cache: undefined = not yet loaded, null = nothing found, object = valid config
+let _cache: ViconConfig | null | undefined;
+
+export async function getConfig(): Promise<ViconConfig | null> {
+	if (_cache !== undefined) return _cache;
+
+	// Check env var first
+	const envVal = process.env[CONFIG_KEY];
+	if (envVal) {
+		try {
+			_cache = JSON.parse(envVal) as ViconConfig;
+			return _cache;
+		} catch {
+			// Invalid JSON in env var — fall through
+		}
+	}
+
+	// Try Bun.secrets
+	try {
+		const val = await Bun.secrets.get({
+			service: SECRETS_SERVICE,
+			name: CONFIG_KEY,
+		});
+		if (val) {
+			_cache = JSON.parse(val) as ViconConfig;
+			return _cache;
+		}
+	} catch {
+		// Secret store unavailable — fall through
+	}
+
+	_cache = null;
+	return null;
+}
+
+export async function setConfig(config: ViconConfig): Promise<void> {
+	try {
+		await Bun.secrets.set({
+			service: SECRETS_SERVICE,
+			name: CONFIG_KEY,
+			value: JSON.stringify(config),
+		});
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (
+			msg.toLowerCase().includes("libsecret") ||
+			msg.toLowerCase().includes("secret service")
+		) {
+			throw new Error(
+				`Failed to store config in keychain: ${msg}\n` +
+					`Install libsecret:\n` +
+					`  Ubuntu/Debian: sudo apt install libsecret-1-0 libsecret-tools\n` +
+					`  Fedora:        sudo dnf install libsecret\n` +
+					`  Arch:          sudo pacman -S libsecret`,
+			);
+		}
+		throw err;
+	}
+	_cache = config;
+}
+
+export async function deleteConfig(): Promise<void> {
+	_cache = undefined;
+	try {
+		await Bun.secrets.delete({ service: SECRETS_SERVICE, name: CONFIG_KEY });
+	} catch {
+		// Not found — no-op
+	}
+}

package/src/lib/prompt.ts

@@ -0,0 +1,28 @@
+import type { ToolContext } from "../types.js";
+
+export function buildSystemPrompt(ctx: ToolContext): string {
+	const ffmpegLine = ctx.ffmpeg.installed
+		? `ffmpeg ${ctx.ffmpeg.version ?? "unknown"} | encoders: [${ctx.ffmpeg.encoders.join(", ")}] | decoders: [${ctx.ffmpeg.decoders.join(", ")}]`
+		: "ffmpeg: not installed";
+
+	const magickLine = ctx.magick.installed
+		? `magick ${ctx.magick.version ?? "unknown"} | formats: [${ctx.magick.formats.join(", ")}]`
+		: "magick: not installed";
+
+	const environment = `## Environment\n${ffmpegLine}\n${magickLine}`;
+
+	const rules = `## Rules
+Return ONLY valid JSON in this exact shape: { "commands": string[], "explanation": string }
+- explanation: plain prose only — no shell syntax, no backticks, no code
+- commands: complete, copy-pasteable shell strings — no placeholders, no &&, no loops
+- Only use tools that are listed as installed above
+- Prefer non-destructive output: append _converted to output filenames, use -n flag to avoid overwriting
+- For batch tasks, emit one command per file
+IMPORTANT: Reply with ONLY the JSON object — no markdown fences, no extra text`;
+
+	return [environment, rules].join("\n\n");
+}
+
+export function buildUserPrompt(request: string): string {
+	return request;
+}

package/src/lib/run.ts

@@ -0,0 +1,35 @@
+export type RunCallbacks = {
+	onBefore?: (cmd: string, index: number, total: number) => void;
+	onSuccess?: () => void;
+	onError?: (cmd: string, exitCode: number) => void;
+};
+
+/**
+ * Run commands in series via sh -c, streaming stdout/stderr to the terminal.
+ * Returns true if all commands exit 0, false on first non-zero exit.
+ */
+export async function runCommands(
+	commands: string[],
+	callbacks: RunCallbacks = {},
+): Promise<boolean> {
+	const total = commands.length;
+
+	for (const [i, cmd] of commands.entries()) {
+		callbacks.onBefore?.(cmd, i, total);
+
+		const proc = Bun.spawn(["sh", "-c", cmd], {
+			stdout: "inherit",
+			stderr: "inherit",
+		});
+
+		await proc.exited;
+
+		if (proc.exitCode !== 0) {
+			callbacks.onError?.(cmd, proc.exitCode ?? 1);
+			return false;
+		}
+	}
+
+	callbacks.onSuccess?.();
+	return true;
+}

package/src/lib/secrets.ts

@@ -0,0 +1,2 @@
+export const SECRETS_SERVICE = "com.vicon.cli";
+export const CONFIG_KEY = "VICON_CONFIG";

package/src/lib/tools.ts

@@ -0,0 +1,67 @@
+import type { ToolContext } from "../types.js";
+
+let cached: ToolContext | undefined;
+
+async function run(cmd: string[]): Promise<string> {
+	try {
+		const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+		return (await new Response(proc.stdout).text()).trim();
+	} catch {
+		return "";
+	}
+}
+
+async function probeFfmpeg(): Promise<ToolContext["ffmpeg"]> {
+	const versionOut = await run(["ffmpeg", "-version"]);
+	if (!versionOut) return { installed: false, encoders: [], decoders: [] };
+
+	const versionMatch = versionOut.split("\n")[0]?.match(/ffmpeg version (\S+)/);
+	const version = versionMatch?.[1];
+
+	const encodersOut = await run(["ffmpeg", "-encoders"]);
+	const decodersOut = await run(["ffmpeg", "-decoders"]);
+
+	const encoders = encodersOut
+		.split("\n")
+		.slice(1)
+		.filter((l) => /^ [VAS.]+\s/.test(l))
+		.map((l) => l.trim().split(/\s+/)[1] ?? "")
+		.filter(Boolean);
+
+	const decoders = decodersOut
+		.split("\n")
+		.slice(1)
+		.filter((l) => /^ [VAS.]+\s/.test(l))
+		.map((l) => l.trim().split(/\s+/)[1] ?? "")
+		.filter(Boolean);
+
+	return { installed: true, version, encoders, decoders };
+}
+
+async function probeMagick(): Promise<ToolContext["magick"]> {
+	const versionOut = await run(["magick", "-version"]);
+	if (!versionOut) return { installed: false, formats: [] };
+
+	const versionMatch = versionOut
+		.split("\n")[0]
+		?.match(/Version: ImageMagick (\S+)/);
+	const version = versionMatch?.[1];
+
+	const formatsOut = await run(["magick", "-list", "format"]);
+
+	const formats = formatsOut
+		.split("\n")
+		.filter((l) => /^\s+[A-Z0-9]+\*?\s/.test(l))
+		.map((l) => l.trim().split(/\s+/)[0]?.replace("*", "") ?? "")
+		.filter(Boolean);
+
+	return { installed: true, version, formats };
+}
+
+export async function detectContext(): Promise<ToolContext> {
+	if (cached) return cached;
+
+	const [ffmpeg, magick] = await Promise.all([probeFfmpeg(), probeMagick()]);
+	cached = { ffmpeg, magick };
+	return cached;
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+export interface GenerateResult {
+	commands: string[];
+	explanation: string;
+}
+
+export interface ToolContext {
+	ffmpeg: {
+		installed: boolean;
+		version?: string;
+		encoders: string[];
+		decoders: string[];
+	};
+	magick: {
+		installed: boolean;
+		version?: string;
+		formats: string[];
+	};
+}

package/src/ui/banner.ts

@@ -0,0 +1,25 @@
+import gradient from "gradient-string";
+import { gradientColors } from "./theme.js";
+
+const bannerGradient = gradient([...gradientColors.banner]);
+
+const BANNER = `
+
+           d8,                         
+          \`8P                          
+                                       
+?88   d8P  88b d8888b d8888b   88bd88b 
+d88  d8P'  88Pd8P' \`Pd8P' ?88  88P' ?8b
+?8b ,88'  d88 88b    88b  d88 d88   88P
+\`?888P'  d88' \`?888P'\`?8888P'd88'   88b
+                                       
+                                       
+                                       
+`;
+
+/**
+ * Display the ASCII art banner with gradient colors
+ */
+export function showBanner(): void {
+	console.log(bannerGradient(BANNER));
+}

package/src/ui/theme.ts

@@ -0,0 +1,162 @@
+import pc from "picocolors";
+
+// Catppuccin Frappe palette
+// https://github.com/catppuccin/catppuccin
+const palette = {
+	base: "#303446",
+	blue: "#8caaee",
+	crust: "#232634",
+	flamingo: "#eebebe",
+	green: "#a6d189",
+	lavender: "#babbf1",
+	mantle: "#292c3c",
+	maroon: "#ea999c",
+	mauve: "#ca9ee6",
+	overlay0: "#737994",
+	overlay1: "#838ba7",
+	overlay2: "#949cbb",
+	peach: "#ef9f76",
+	pink: "#f4b8e4",
+	red: "#e78284",
+	rosewater: "#f2d5cf",
+	sapphire: "#85c1dc",
+	sky: "#99d1db",
+	subtext0: "#a5adce",
+	subtext1: "#b5bfe2",
+	surface0: "#414559",
+	surface1: "#51576d",
+	surface2: "#626880",
+	teal: "#81c8be",
+	text: "#c6d0f5",
+	yellow: "#e5c890",
+} as const;
+
+// ANSI 256-color approximations for Catppuccin Frappe
+// These are the closest matches in the 256-color palette
+const ansi = {
+	base: 236,
+	blue: 111,
+	crust: 234,
+	flamingo: 217,
+	green: 150,
+	lavender: 147,
+	mantle: 235,
+	maroon: 217,
+	mauve: 183,
+	overlay0: 60,
+	overlay1: 103,
+	overlay2: 103,
+	peach: 216,
+	pink: 218,
+	red: 210,
+	rosewater: 224,
+	sapphire: 110,
+	sky: 117,
+	subtext0: 146,
+	subtext1: 146,
+	surface0: 59,
+	surface1: 59,
+	surface2: 60,
+	teal: 116,
+	text: 189,
+	yellow: 223,
+} as const;
+
+// Color functions using ANSI 256 colors
+function ansiColor(code: number): (text: string) => string {
+	return (text: string) => `\x1b[38;5;${code}m${text}\x1b[0m`;
+}
+
+function ansiBg(code: number): (text: string) => string {
+	return (text: string) => `\x1b[48;5;${code}m${text}\x1b[0m`;
+}
+
+// Theme colors as functions
+export const frappe = {
+	// Base colors
+	base: ansiColor(ansi.base),
+
+	// Background variants
+	bg: {
+		base: ansiBg(ansi.base),
+		surface0: ansiBg(ansi.surface0),
+		surface1: ansiBg(ansi.surface1),
+	},
+	blue: ansiColor(ansi.blue),
+	crust: ansiColor(ansi.crust),
+	flamingo: ansiColor(ansi.flamingo),
+	green: ansiColor(ansi.green),
+	lavender: ansiColor(ansi.lavender),
+	mantle: ansiColor(ansi.mantle),
+	maroon: ansiColor(ansi.maroon),
+	mauve: ansiColor(ansi.mauve),
+	overlay0: ansiColor(ansi.overlay0),
+	overlay1: ansiColor(ansi.overlay1),
+
+	// Overlay colors
+	overlay2: ansiColor(ansi.overlay2),
+	peach: ansiColor(ansi.peach),
+	pink: ansiColor(ansi.pink),
+	red: ansiColor(ansi.red),
+	// Primary accent colors
+	rosewater: ansiColor(ansi.rosewater),
+	sapphire: ansiColor(ansi.sapphire),
+	sky: ansiColor(ansi.sky),
+	subtext0: ansiColor(ansi.subtext0),
+	subtext1: ansiColor(ansi.subtext1),
+	surface0: ansiColor(ansi.surface0),
+	surface1: ansiColor(ansi.surface1),
+
+	// Surface colors
+	surface2: ansiColor(ansi.surface2),
+	teal: ansiColor(ansi.teal),
+
+	// Text colors
+	text: ansiColor(ansi.text),
+	yellow: ansiColor(ansi.yellow),
+} as const;
+
+// Semantic aliases for common use cases
+export const theme = {
+	accent: frappe.flamingo,
+
+	// Diff colors
+	added: frappe.green,
+	body: frappe.subtext1,
+	dim: frappe.surface2,
+	error: frappe.red,
+
+	// Text
+	heading: frappe.text,
+	info: frappe.blue,
+	modified: frappe.yellow,
+	muted: frappe.overlay1,
+
+	// UI elements
+	primary: frappe.mauve,
+	removed: frappe.red,
+	secondary: frappe.pink,
+	subtle: frappe.subtext0,
+	// Status colors
+	success: frappe.green,
+	warning: frappe.yellow,
+} as const;
+
+// Gradient colors for banner (hex values for gradient-string)
+export const gradientColors = {
+	banner: [palette.mauve, palette.pink, palette.flamingo],
+	error: [palette.red, palette.maroon],
+	success: [palette.green, palette.teal],
+} as const;
+
+// Box border color (hex for boxen)
+export const boxColors = {
+	default: palette.surface2,
+	error: palette.red,
+	info: palette.blue,
+	primary: palette.mauve,
+	success: palette.green,
+} as const;
+
+// Re-export picocolors for basic formatting
+export { pc };