summon-open 1.0.0

package/cli.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import {existsSync} from 'node:fs';
+import * as streamConsumers from 'node:stream/consumers';
+import meow from 'meow';
+import open from 'open';
+import clipboard from 'clipboardy';
+import {temporaryWrite} from 'tempy';
+import {fileTypeFromBuffer} from 'file-type';
+import {
+	readConfig,
+	readBookmarks,
+	saveBookmark,
+	removeBookmark,
+	readHistory,
+	addHistory,
+} from './lib/config.js';
+import {
+	isUrl,
+	looksLikeDomain,
+	normalizeTarget,
+	expandBookmark,
+	resolveTarget,
+	buildSearchUrl,
+	SummonError,
+} from './lib/resolve.js';
+import {revealInFileManager} from './lib/reveal.js';
+import {pick} from './lib/picker.js';
+
+const cli = meow(`
+	Usage
+	  $ summon <file|url|@bookmark> … [options] [-- <app> [args]]
+	  $ cat <file> | summon [--extension] [options] [-- <app> [args]]
+
+	Options
+	  --wait, -w          Wait for the app to exit
+	  --background        Do not bring the app to the foreground (macOS only)
+	  --extension         File extension for when stdin file type cannot be detected
+	  --dry-run, -n       Print what would be opened without opening it
+	  --search, -s        Treat the input as a search query
+	  --clipboard, -c     Open the URL/path currently on the clipboard
+	  --reveal, -r        Reveal the file/folder in your file manager
+	  --recent            Pick from recently opened items
+	  --save <name>       Save the given target as a bookmark (does not open)
+	  --remove-bookmark   Remove a saved bookmark by name
+	  --bookmarks         List saved bookmarks
+
+	Examples
+	  $ summon https://sindresorhus.com
+	  $ summon github.com                 # scheme added automatically
+	  $ summon report.pdf photo.png notes.txt
+	  $ summon https://github.com -- 'google chrome' --incognito
+	  $ summon @docs                      # open a saved bookmark
+	  $ summon https://docs.example.com --save docs
+	  $ summon -s "rust async traits"
+	  $ echo '<h1>Hi</h1>' | summon --extension=html
+	  $ summon report.pdf --reveal
+	  $ summon --recent
+`, {
+	importMeta: import.meta,
+	flags: {
+		wait: {type: 'boolean', default: false, shortFlag: 'w'},
+		background: {type: 'boolean', default: false},
+		extension: {type: 'string'},
+		dryRun: {type: 'boolean', default: false, shortFlag: 'n'},
+		search: {type: 'boolean', default: false, shortFlag: 's'},
+		clipboard: {type: 'boolean', default: false, shortFlag: 'c'},
+		reveal: {type: 'boolean', default: false, shortFlag: 'r'},
+		recent: {type: 'boolean', default: false},
+		save: {type: 'string'},
+		removeBookmark: {type: 'string'},
+		bookmarks: {type: 'boolean', default: false},
+	},
+});
+
+const {flags} = cli;
+
+// Split off a trailing `-- <app> [args]` section from the raw arguments so it
+// never gets confused with the (now possibly multiple) targets.
+const rawArguments = process.argv.slice(2);
+const separatorIndex = rawArguments.indexOf('--');
+const appTokens = separatorIndex === -1 ? [] : rawArguments.slice(separatorIndex + 1);
+const targets = appTokens.length > 0
+	? cli.input.slice(0, cli.input.length - appTokens.length)
+	: cli.input;
+
+const openOptions = {wait: flags.wait, background: flags.background};
+if (appTokens.length > 0) {
+	const [name, ...appArguments] = appTokens;
+	openOptions.app = {name, arguments: appArguments};
+}
+
+const stderr = message => process.stderr.write(`${message}\n`);
+const stdout = message => process.stdout.write(`${message}\n`);
+
+async function main() {
+	// --- Bookmark management (these never open anything) ---
+	if (flags.bookmarks) {
+		listBookmarks();
+		return;
+	}
+
+	if (flags.removeBookmark !== undefined) {
+		const removed = removeBookmark(flags.removeBookmark);
+		if (!removed) {
+			throw new SummonError(`No such bookmark: ${flags.removeBookmark}`, 3);
+		}
+
+		stdout(`Removed bookmark: ${flags.removeBookmark}`);
+		return;
+	}
+
+	if (flags.save !== undefined) {
+		if (targets.length === 0) {
+			throw new SummonError('Specify a target to save, e.g. `summon https://example.com --save name`', 4);
+		}
+
+		const value = resolveTarget(targets[0], readBookmarks());
+		saveBookmark(flags.save, value);
+		stdout(`Saved bookmark ${flags.save} → ${value}`);
+		return;
+	}
+
+	// --- Figure out what to open ---
+	const bookmarks = readBookmarks();
+	let rawInputs;
+	let stdinMode = false;
+
+	if (flags.clipboard) {
+		const clipboardText = await clipboard.read();
+		const text = clipboardText.trim();
+		if (!text) {
+			throw new SummonError('Clipboard is empty', 4);
+		}
+
+		rawInputs = text.split(/\s+/v).filter(Boolean);
+	} else if (flags.search) {
+		if (targets.length === 0) {
+			throw new SummonError('Provide a search query, e.g. `summon -s "hello world"`', 4);
+		}
+
+		rawInputs = [buildSearchUrl(targets.join(' '), readConfig().searchEngine)];
+	} else if (flags.recent) {
+		const chosen = await pick('Recently opened', readHistory().map(item => ({label: item, value: item})));
+		if (!chosen) {
+			return;
+		}
+
+		rawInputs = [chosen];
+	} else if (targets.length > 0) {
+		rawInputs = targets;
+	} else if (process.stdin.isTTY) {
+		const chosen = await interactivePicker(bookmarks);
+		if (!chosen) {
+			return;
+		}
+
+		rawInputs = [chosen];
+	} else {
+		stdinMode = true;
+	}
+
+	if (stdinMode) {
+		await handleStdin();
+		return;
+	}
+
+	// --- Resolve and act ---
+	const expanded = rawInputs.map(input => expandBookmark(input, bookmarks));
+
+	if (flags.reveal) {
+		for (const target of expanded) {
+			if (flags.dryRun) {
+				stdout(`[dry-run] reveal: ${target}`);
+				continue;
+			}
+
+			await revealInFileManager(target); // eslint-disable-line no-await-in-loop
+		}
+
+		return;
+	}
+
+	for (const input of expanded) {
+		await openOne(input); // eslint-disable-line no-await-in-loop
+	}
+}
+
+// Prefer an existing file over domain normalization, then URLs, then bare domains.
+function classify(input) {
+	if (existsSync(input)) {
+		return {target: input};
+	}
+
+	if (isUrl(input)) {
+		return {target: input};
+	}
+
+	if (looksLikeDomain(input)) {
+		return {target: normalizeTarget(input)};
+	}
+
+	return {target: input, missing: true};
+}
+
+async function openOne(input) {
+	const {target, missing} = classify(input);
+	if (missing) {
+		throw new SummonError(`File or URL not found: ${input}`, 2);
+	}
+
+	if (flags.dryRun) {
+		const via = openOptions.app ? ` (via ${openOptions.app.name})` : '';
+		stdout(`[dry-run] open: ${target}${via}`);
+		return;
+	}
+
+	await open(target, openOptions);
+	addHistory(target);
+}
+
+async function handleStdin() {
+	const buffer = await streamConsumers.buffer(process.stdin);
+	const type = await fileTypeFromBuffer(buffer);
+	const extension = flags.extension ?? type?.ext ?? 'txt';
+
+	if (flags.dryRun) {
+		stdout(`[dry-run] open piped stdin as .${extension} file`);
+		return;
+	}
+
+	const filePath = await temporaryWrite(buffer, {extension});
+	await open(filePath, openOptions);
+	addHistory(filePath);
+}
+
+function listBookmarks() {
+	const bookmarks = readBookmarks();
+	const names = Object.keys(bookmarks);
+
+	if (names.length === 0) {
+		stdout('No bookmarks yet. Add one with: summon <target> --save <name>');
+		return;
+	}
+
+	const width = Math.max(...names.map(name => name.length));
+	for (const name of names.toSorted()) {
+		stdout(`  ${name.padEnd(width)}  ${bookmarks[name]}`);
+	}
+}
+
+async function interactivePicker(bookmarks) {
+	const items = [
+		...Object.entries(bookmarks).map(([name, target]) => ({label: `@${name} → ${target}`, value: `@${name}`})),
+		...readHistory().map(item => ({label: item, value: item})),
+	];
+
+	if (items.length === 0) {
+		throw new SummonError('Specify a file path or URL', 4);
+	}
+
+	return pick('What would you like to open?', items);
+}
+
+try {
+	await main();
+} catch (error) {
+	if (error instanceof SummonError) {
+		stderr(`summon: ${error.message}`);
+		process.exit(error.exitCode);
+	}
+
+	stderr(`summon: ${error.message ?? error}`);
+	process.exit(1);
+}

package/completions/summon.bash

@@ -0,0 +1,37 @@
+# summon bash completion
+# Install: source this file from your ~/.bashrc, e.g.
+#   source /path/to/summon/completions/summon.bash
+
+_summon_completions() {
+	local cur prev flags
+	cur="${COMP_WORDS[COMP_CWORD]}"
+	prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+	flags="--wait --background --extension --dry-run --search --clipboard --reveal --recent --save --remove-bookmark --bookmarks --help --version"
+
+	# Complete bookmark names after `@`.
+	if [[ "$cur" == @* ]]; then
+		local names
+		names=$(summon --bookmarks 2>/dev/null | awk '{print "@"$1}')
+		COMPREPLY=($(compgen -W "$names" -- "$cur"))
+		return 0
+	fi
+
+	# Complete bookmark names for --remove-bookmark.
+	if [[ "$prev" == "--remove-bookmark" ]]; then
+		local names
+		names=$(summon --bookmarks 2>/dev/null | awk '{print $1}')
+		COMPREPLY=($(compgen -W "$names" -- "$cur"))
+		return 0
+	fi
+
+	if [[ "$cur" == -* ]]; then
+		COMPREPLY=($(compgen -W "$flags" -- "$cur"))
+		return 0
+	fi
+
+	# Default to file completion.
+	COMPREPLY=($(compgen -f -- "$cur"))
+}
+
+complete -F _summon_completions summon

package/completions/summon.fish

@@ -0,0 +1,20 @@
+# summon fish completion
+# Install: copy to ~/.config/fish/completions/summon.fish
+
+function __summon_bookmarks
+	summon --bookmarks 2>/dev/null | string trim | string replace -r '\s.*' ''
+end
+
+complete -c summon -s w -l wait -d 'Wait for the app to exit'
+complete -c summon -l background -d 'Do not bring the app to the foreground (macOS)'
+complete -c summon -l extension -r -d 'File extension for stdin'
+complete -c summon -s n -l dry-run -d 'Print what would be opened'
+complete -c summon -s s -l search -d 'Treat input as a search query'
+complete -c summon -s c -l clipboard -d 'Open URL/path from the clipboard'
+complete -c summon -s r -l reveal -d 'Reveal file/folder in file manager'
+complete -c summon -l recent -d 'Pick from recently opened items'
+complete -c summon -l save -r -d 'Save target as a bookmark'
+complete -c summon -l remove-bookmark -x -a '(__summon_bookmarks)' -d 'Remove a bookmark'
+complete -c summon -l bookmarks -d 'List saved bookmarks'
+complete -c summon -l help -d 'Show help'
+complete -c summon -l version -d 'Show version'

package/completions/summon.ps1

@@ -0,0 +1,30 @@
+# summon PowerShell completion
+# Install: add this line to your PowerShell profile ($PROFILE):
+#   . /path/to/summon/completions/summon.ps1
+
+Register-ArgumentCompleter -Native -CommandName summon -ScriptBlock {
+	param($wordToComplete, $commandAst, $cursorPosition)
+
+	$flags = @(
+		'--wait', '--background', '--extension', '--dry-run', '--search',
+		'--clipboard', '--reveal', '--recent', '--save', '--remove-bookmark',
+		'--bookmarks', '--help', '--version'
+	)
+
+	if ($wordToComplete -like '--*') {
+		$flags | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+			[System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterName', $_)
+		}
+		return
+	}
+
+	# Bookmark completion after `@`.
+	if ($wordToComplete -like '@*') {
+		$prefix = $wordToComplete.TrimStart('@')
+		(summon --bookmarks 2>$null) | ForEach-Object {
+			($_ -split '\s+', 2)[0].Trim()
+		} | Where-Object { $_ -like "$prefix*" } | ForEach-Object {
+			[System.Management.Automation.CompletionResult]::new("@$_", "@$_", 'ParameterValue', "@$_")
+		}
+	}
+}

package/completions/summon.zsh

@@ -0,0 +1,38 @@
+#compdef summon
+# summon zsh completion
+# Install: place this file in a directory on your $fpath (named `_summon`),
+# or source it from your ~/.zshrc.
+
+_summon() {
+	local -a flags
+	flags=(
+		'--wait[Wait for the app to exit]'
+		'-w[Wait for the app to exit]'
+		'--background[Do not bring the app to the foreground (macOS)]'
+		'--extension[File extension for stdin]:extension:'
+		'--dry-run[Print what would be opened]'
+		'-n[Print what would be opened]'
+		'--search[Treat input as a search query]'
+		'-s[Treat input as a search query]'
+		'--clipboard[Open URL/path from the clipboard]'
+		'-c[Open URL/path from the clipboard]'
+		'--reveal[Reveal file/folder in file manager]'
+		'-r[Reveal file/folder in file manager]'
+		'--recent[Pick from recently opened items]'
+		'--save[Save target as a bookmark]:name:'
+		'--remove-bookmark[Remove a bookmark]:name:_summon_bookmarks'
+		'--bookmarks[List saved bookmarks]'
+		'--help[Show help]'
+		'--version[Show version]'
+	)
+
+	_arguments -s $flags '*:target:_files'
+}
+
+_summon_bookmarks() {
+	local -a names
+	names=(${(f)"$(summon --bookmarks 2>/dev/null | awk '{print $1}')"})
+	compadd -a names
+}
+
+_summon "$@"

package/lib/config.js

@@ -0,0 +1,127 @@
+import process from 'node:process';
+import {homedir} from 'node:os';
+import path from 'node:path';
+import {
+	mkdirSync,
+	readFileSync,
+	writeFileSync,
+	existsSync,
+} from 'node:fs';
+
+const HISTORY_LIMIT = 50;
+
+const DEFAULT_CONFIG = {
+	// Map of alias -> target. Resolved when you run `summon @alias` or `summon alias`.
+	bookmarks: {},
+	// Search URL template. `%s` is replaced with the URL-encoded query.
+	searchEngine: 'https://www.google.com/search?q=%s',
+};
+
+/**
+Resolve the directory where summon stores its config and history.
+
+Priority:
+1. `SUMMON_CONFIG_DIR` (used by tests and power users)
+2. `XDG_CONFIG_HOME/summon`
+3. Windows: `%APPDATA%/summon`
+4. `~/.config/summon`
+
+@returns {string}
+*/
+export function configDirectory() {
+	if (process.env.SUMMON_CONFIG_DIR) {
+		return process.env.SUMMON_CONFIG_DIR;
+	}
+
+	if (process.env.XDG_CONFIG_HOME) {
+		return path.join(process.env.XDG_CONFIG_HOME, 'summon');
+	}
+
+	if (process.platform === 'win32' && process.env.APPDATA) {
+		return path.join(process.env.APPDATA, 'summon');
+	}
+
+	return path.join(homedir(), '.config', 'summon');
+}
+
+const configPath = () => path.join(configDirectory(), 'config.json');
+const historyPath = () => path.join(configDirectory(), 'history.json');
+
+function readJson(filePath, fallback) {
+	try {
+		if (!existsSync(filePath)) {
+			return fallback;
+		}
+
+		return JSON.parse(readFileSync(filePath, 'utf8'));
+	} catch {
+		// A corrupt file should never crash the CLI; fall back to defaults.
+		return fallback;
+	}
+}
+
+function writeJson(filePath, data) {
+	mkdirSync(path.dirname(filePath), {recursive: true});
+	writeFileSync(filePath, JSON.stringify(data, null, '\t') + '\n');
+}
+
+/**
+Read the full config, merged with defaults.
+
+@returns {{bookmarks: Record<string, string>, searchEngine: string}}
+*/
+export function readConfig() {
+	return {...DEFAULT_CONFIG, ...readJson(configPath(), {})};
+}
+
+/** @returns {Record<string, string>} */
+export function readBookmarks() {
+	return readConfig().bookmarks ?? {};
+}
+
+/**
+Save (or overwrite) a bookmark.
+
+@param {string} name
+@param {string} target
+*/
+export function saveBookmark(name, target) {
+	const config = readConfig();
+	config.bookmarks = {...config.bookmarks, [name]: target};
+	writeJson(configPath(), config);
+}
+
+/**
+Remove a bookmark.
+
+@param {string} name
+@returns {boolean} Whether the bookmark existed.
+*/
+export function removeBookmark(name) {
+	const config = readConfig();
+
+	if (!config.bookmarks || !(name in config.bookmarks)) {
+		return false;
+	}
+
+	delete config.bookmarks[name];
+	writeJson(configPath(), config);
+	return true;
+}
+
+/** @returns {string[]} Most-recent-first list of opened targets. */
+export function readHistory() {
+	const history = readJson(historyPath(), []);
+	return Array.isArray(history) ? history : [];
+}
+
+/**
+Prepend a target to the history, de-duplicated and capped.
+
+@param {string} target
+*/
+export function addHistory(target) {
+	const existing = readHistory().filter(item => item !== target);
+	const history = [target, ...existing].slice(0, HISTORY_LIMIT);
+	writeJson(historyPath(), history);
+}

package/lib/picker.js

@@ -0,0 +1,43 @@
+import process from 'node:process';
+import readline from 'node:readline/promises';
+
+/**
+Show a numbered interactive menu and return the chosen value.
+
+@param {string} title
+@param {Array<{label: string, value: string}>} items
+@returns {Promise<string | undefined>} The chosen value, or undefined if cancelled/empty.
+*/
+export async function pick(title, items) {
+	if (items.length === 0) {
+		return undefined;
+	}
+
+	const rl = readline.createInterface({input: process.stdin, output: process.stderr});
+
+	try {
+		process.stderr.write(`${title}\n\n`);
+		for (const [index, item] of items.entries()) {
+			process.stderr.write(`  ${String(index + 1).padStart(2)}. ${item.label}\n`);
+		}
+
+		process.stderr.write('\n');
+
+		const response = await rl.question('Select a number (or press Enter to cancel): ');
+		const answer = response.trim();
+
+		if (answer === '') {
+			return undefined;
+		}
+
+		const index = Number.parseInt(answer, 10) - 1;
+		if (Number.isInteger(index) && index >= 0 && index < items.length) {
+			return items[index].value;
+		}
+
+		process.stderr.write('Invalid selection.\n');
+		return undefined;
+	} finally {
+		rl.close();
+	}
+}