summon-open 1.0.0 → 1.1.0

package/cli.js

@@ -8,12 +8,13 @@ import clipboard from 'clipboardy';
 import {temporaryWrite} from 'tempy';
 import {fileTypeFromBuffer} from 'file-type';
 import {
-	readConfig,
 	readBookmarks,
 	saveBookmark,
 	removeBookmark,
 	readHistory,
 	addHistory,
+	readSearchEngines,
+	defaultSearchEngineName,
 } from './lib/config.js';
 import {
 	isUrl,
@@ -38,6 +39,8 @@ const cli = meow(`
 	  --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
+	  --engine, -e        Search engine to use with --search (see --engines)
+	  --engines           List available search engines
 	  --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
@@ -53,6 +56,7 @@ const cli = meow(`
 	  $ summon @docs                      # open a saved bookmark
 	  $ summon https://docs.example.com --save docs
 	  $ summon -s "rust async traits"
+	  $ summon -s "flatMap" -e mdn
 	  $ echo '<h1>Hi</h1>' | summon --extension=html
 	  $ summon report.pdf --reveal
 	  $ summon --recent
@@ -64,6 +68,8 @@ const cli = meow(`
 		extension: {type: 'string'},
 		dryRun: {type: 'boolean', default: false, shortFlag: 'n'},
 		search: {type: 'boolean', default: false, shortFlag: 's'},
+		engine: {type: 'string', shortFlag: 'e'},
+		engines: {type: 'boolean', default: false},
 		clipboard: {type: 'boolean', default: false, shortFlag: 'c'},
 		reveal: {type: 'boolean', default: false, shortFlag: 'r'},
 		recent: {type: 'boolean', default: false},
@@ -94,20 +100,43 @@ 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 (handleManagementCommand()) {
+		return;
+	}
+
+	const bookmarks = readBookmarks();
+	const plan = await collectInputs(bookmarks);
+	if (plan.done) {
+		return;
+	}
+
+	if (plan.stdinMode) {
+		await handleStdin();
+		return;
+	}
+
+	await act(plan.rawInputs, bookmarks);
+}
+
+// Handle commands that never open anything. Returns true when one ran.
+function handleManagementCommand() {
 	if (flags.bookmarks) {
 		listBookmarks();
-		return;
+		return true;
+	}
+
+	if (flags.engines) {
+		listSearchEngines();
+		return true;
 	}
 
 	if (flags.removeBookmark !== undefined) {
-		const removed = removeBookmark(flags.removeBookmark);
-		if (!removed) {
+		if (!removeBookmark(flags.removeBookmark)) {
 			throw new SummonError(`No such bookmark: ${flags.removeBookmark}`, 3);
 		}
 
 		stdout(`Removed bookmark: ${flags.removeBookmark}`);
-		return;
+		return true;
 	}
 
 	if (flags.save !== undefined) {
@@ -118,14 +147,14 @@ async function main() {
 		const value = resolveTarget(targets[0], readBookmarks());
 		saveBookmark(flags.save, value);
 		stdout(`Saved bookmark ${flags.save} → ${value}`);
-		return;
+		return true;
 	}
 
-	// --- Figure out what to open ---
-	const bookmarks = readBookmarks();
-	let rawInputs;
-	let stdinMode = false;
+	return false;
+}
 
+// Decide what to open. Returns {rawInputs} | {stdinMode:true} | {done:true}.
+async function collectInputs(bookmarks) {
 	if (flags.clipboard) {
 		const clipboardText = await clipboard.read();
 		const text = clipboardText.trim();
@@ -133,39 +162,46 @@ async function main() {
 			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);
-		}
+		return {rawInputs: text.split(/\s+/v).filter(Boolean)};
+	}
+
+	if (flags.search) {
+		return {rawInputs: [searchUrlFromTargets()]};
+	}
 
-		rawInputs = [buildSearchUrl(targets.join(' '), readConfig().searchEngine)];
-	} else if (flags.recent) {
+	if (flags.recent) {
 		const chosen = await pick('Recently opened', readHistory().map(item => ({label: item, value: item})));
-		if (!chosen) {
-			return;
-		}
+		return chosen ? {rawInputs: [chosen]} : {done: true};
+	}
 
-		rawInputs = [chosen];
-	} else if (targets.length > 0) {
-		rawInputs = targets;
-	} else if (process.stdin.isTTY) {
+	if (targets.length > 0) {
+		return {rawInputs: targets};
+	}
+
+	if (process.stdin.isTTY) {
 		const chosen = await interactivePicker(bookmarks);
-		if (!chosen) {
-			return;
-		}
+		return chosen ? {rawInputs: [chosen]} : {done: true};
+	}
+
+	return {stdinMode: true};
+}
 
-		rawInputs = [chosen];
-	} else {
-		stdinMode = true;
+function searchUrlFromTargets() {
+	if (targets.length === 0) {
+		throw new SummonError('Provide a search query, e.g. `summon -s "hello world"`', 4);
 	}
 
-	if (stdinMode) {
-		await handleStdin();
-		return;
+	const engines = readSearchEngines();
+	const engineName = flags.engine ?? defaultSearchEngineName();
+	const template = engines[engineName];
+	if (!template) {
+		throw new SummonError(`Unknown search engine: ${engineName}. Available: ${Object.keys(engines).toSorted().join(', ')}`, 4);
 	}
 
-	// --- Resolve and act ---
+	return buildSearchUrl(targets.join(' '), template);
+}
+
+async function act(rawInputs, bookmarks) {
 	const expanded = rawInputs.map(input => expandBookmark(input, bookmarks));
 
 	if (flags.reveal) {
@@ -249,6 +285,20 @@ function listBookmarks() {
 	}
 }
 
+function listSearchEngines() {
+	const engines = readSearchEngines();
+	const defaultName = defaultSearchEngineName();
+	const names = Object.keys(engines).toSorted();
+	const width = Math.max(...names.map(name => name.length));
+
+	for (const name of names) {
+		const marker = name === defaultName ? '*' : ' ';
+		stdout(`${marker} ${name.padEnd(width)}  ${engines[name]}`);
+	}
+
+	stdout('\n* = default. Choose another with: summon -s "query" -e <name>');
+}
+
 async function interactivePicker(bookmarks) {
 	const items = [
 		...Object.entries(bookmarks).map(([name, target]) => ({label: `@${name} → ${target}`, value: `@${name}`})),

package/lib/config.js

@@ -10,11 +10,30 @@ import {
 
 const HISTORY_LIMIT = 50;
 
+// Built-in search engines. Each value is a URL template where `%s` is replaced
+// by the URL-encoded query. Users can add/override these in config.json.
+const DEFAULT_SEARCH_ENGINES = {
+	google: 'https://www.google.com/search?q=%s',
+	ddg: 'https://duckduckgo.com/?q=%s',
+	bing: 'https://www.bing.com/search?q=%s',
+	brave: 'https://search.brave.com/search?q=%s',
+	npm: 'https://www.npmjs.com/search?q=%s',
+	gh: 'https://github.com/search?q=%s&type=repositories',
+	mdn: 'https://developer.mozilla.org/en-US/search?q=%s',
+	so: 'https://stackoverflow.com/search?q=%s',
+	yt: 'https://www.youtube.com/results?search_query=%s',
+	wiki: 'https://en.wikipedia.org/w/index.php?search=%s',
+};
+
 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',
+	// Named search engines, merged with the built-ins above.
+	searchEngines: {},
+	// Which engine `--search` uses when `--engine` isn't given.
+	defaultSearchEngine: 'google',
+	// Legacy single-engine field, still honored as a fallback.
+	searchEngine: undefined,
 };
 
 /**
@@ -68,12 +87,44 @@ function writeJson(filePath, data) {
 /**
 Read the full config, merged with defaults.
 
-@returns {{bookmarks: Record<string, string>, searchEngine: string}}
+@returns {{bookmarks: Record<string, string>, searchEngines: Record<string, string>, defaultSearchEngine: string, searchEngine?: string}}
 */
 export function readConfig() {
 	return {...DEFAULT_CONFIG, ...readJson(configPath(), {})};
 }
 
+/**
+All available search engines: built-ins merged with the user's `searchEngines`.
+A legacy top-level `searchEngine` is exposed as the `custom` engine.
+
+@returns {Record<string, string>}
+*/
+export function readSearchEngines() {
+	const config = readConfig();
+	const engines = {...DEFAULT_SEARCH_ENGINES, ...config.searchEngines};
+
+	if (typeof config.searchEngine === 'string' && config.searchEngine.length > 0) {
+		engines.custom = config.searchEngine;
+	}
+
+	return engines;
+}
+
+/**
+The name of the engine `--search` uses when `--engine` isn't provided.
+
+@returns {string}
+*/
+export function defaultSearchEngineName() {
+	const config = readConfig();
+
+	if (typeof config.searchEngine === 'string' && config.searchEngine.length > 0 && !config.defaultSearchEngine) {
+		return 'custom';
+	}
+
+	return config.defaultSearchEngine ?? 'google';
+}
+
 /** @returns {Record<string, string>} */
 export function readBookmarks() {
 	return readConfig().bookmarks ?? {};

package/lib/fuzzy.js

@@ -0,0 +1,68 @@
+// Word-boundary characters that earn a scoring bonus when a match starts there.
+const BOUNDARY = /[\s\-_\/.@:]/v;
+
+/**
+Score how well `query` fuzzy-matches `target`.
+
+Returns a non-negative score (higher is better) when every character of the
+query appears in order within the target, or `-1` when there's no match.
+Consecutive matches and matches at word boundaries score higher.
+
+@param {string} query
+@param {string} target
+@returns {number}
+*/
+export function fuzzyScore(query, target) {
+	const q = query.toLowerCase();
+	const t = target.toLowerCase();
+
+	if (q === '') {
+		return 0;
+	}
+
+	let score = 0;
+	let index = 0;
+	let consecutive = 0;
+
+	for (const char of q) {
+		const found = t.indexOf(char, index);
+		if (found === -1) {
+			return -1;
+		}
+
+		let bonus = 1;
+
+		if (found === index && index > 0) {
+			consecutive += 1;
+			bonus += consecutive * 2;
+		} else {
+			consecutive = 0;
+		}
+
+		if (found === 0 || BOUNDARY.test(t[found - 1])) {
+			bonus += 3;
+		}
+
+		score += bonus;
+		index = found + 1;
+	}
+
+	return score;
+}
+
+/**
+Filter and rank items by fuzzy match against a label.
+
+@template T
+@param {string} query
+@param {T[]} items
+@param {(item: T) => string} toLabel
+@returns {T[]} Matching items, best first.
+*/
+export function fuzzyFilter(query, items, toLabel = String) {
+	return items
+		.map(item => ({item, score: fuzzyScore(query, toLabel(item))}))
+		.filter(entry => entry.score >= 0)
+		.toSorted((a, b) => b.score - a.score)
+		.map(entry => entry.item);
+}

package/lib/picker.js

@@ -1,12 +1,35 @@
 import process from 'node:process';
 import readline from 'node:readline/promises';
+import {fuzzyFilter} from './fuzzy.js';
+
+const PAGE_SIZE = 15;
+
+function render(title, items) {
+	process.stderr.write(`\n${title}\n\n`);
+
+	const shown = items.slice(0, PAGE_SIZE);
+	for (const [index, item] of shown.entries()) {
+		process.stderr.write(`  ${String(index + 1).padStart(2)}. ${item.label}\n`);
+	}
+
+	if (items.length > shown.length) {
+		process.stderr.write(`  … ${items.length - shown.length} more (type to filter)\n`);
+	}
+
+	process.stderr.write('\n');
+	return shown;
+}
 
 /**
-Show a numbered interactive menu and return the chosen value.
+Show an interactive fuzzy picker and return the chosen value.
+
+Type to fuzzy-filter, enter a number to select from the visible list, or press
+Enter on an empty line to cancel. When a filter narrows results to one, it's
+selected automatically.
 
 @param {string} title
 @param {Array<{label: string, value: string}>} items
-@returns {Promise<string | undefined>} The chosen value, or undefined if cancelled/empty.
+@returns {Promise<string | undefined>}
 */
 export async function pick(title, items) {
 	if (items.length === 0) {
@@ -14,29 +37,40 @@ export async function pick(title, items) {
 	}
 
 	const rl = readline.createInterface({input: process.stdin, output: process.stderr});
+	let current = items;
 
 	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`);
-		}
+		for (;;) {
+			const shown = render(title, current);
+			// eslint-disable-next-line no-await-in-loop
+			const response = await rl.question('Type to filter, number to select, Enter to cancel: ');
+			const answer = response.trim();
 
-		process.stderr.write('\n');
+			if (answer === '') {
+				return undefined;
+			}
 
-		const response = await rl.question('Select a number (or press Enter to cancel): ');
-		const answer = response.trim();
+			if (/^\d+$/v.test(answer)) {
+				const index = Number.parseInt(answer, 10) - 1;
+				if (index >= 0 && index < shown.length) {
+					return shown[index].value;
+				}
 
-		if (answer === '') {
-			return undefined;
-		}
+				process.stderr.write('Invalid selection.\n');
+				continue;
+			}
 
-		const index = Number.parseInt(answer, 10) - 1;
-		if (Number.isInteger(index) && index >= 0 && index < items.length) {
-			return items[index].value;
-		}
+			const filtered = fuzzyFilter(answer, items, item => item.label);
 
-		process.stderr.write('Invalid selection.\n');
-		return undefined;
+			if (filtered.length === 0) {
+				process.stderr.write('No matches.\n');
+				current = items;
+			} else if (filtered.length === 1) {
+				return filtered[0].value;
+			} else {
+				current = filtered;
+			}
+		}
 	} finally {
 		rl.close();
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "summon-open",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "Open URLs, files, folders, and apps from one cross-platform command — with bookmarks, search, clipboard, reveal, dry-run, and stdin support.",
 	"license": "MIT",
 	"repository": {

package/readme.md

@@ -21,9 +21,10 @@ Bookmarks, search, clipboard, reveal-in-file-manager, dry-run, multiple targets,
 </div>
 
 <!--
-  DEMO: drop a terminal recording here for maximum impact.
-  Record with https://github.com/charmbracelet/vhs or https://asciinema.org
-  then reference it, e.g.:
+  DEMO: a ready-to-run VHS script lives at media/demo.tape.
+    1. Install VHS: https://github.com/charmbracelet/vhs
+    2. From the repo root, run:  vhs media/demo.tape
+    3. It writes media/demo.gif — then uncomment the line below.
   <div align="center"><img src="media/demo.gif" alt="summon demo" width="700"></div>
 -->
 
@@ -107,10 +108,10 @@ summon "$url"
 - **Multiple targets** — `summon a.pdf b.png https://x.com` opens them all.
 - **Smart URL normalization** — `summon github.com` just works; the `https://` is added for you.
 - **Bookmarks** — save aliases (`summon @docs`) and turn `summon` into a daily driver.
-- **Web search** — `summon -s "query"` opens a search with your configured engine.
+- **Web search** — `summon -s "query"` searches with a configurable engine (`-e mdn`, `-e npm`, …).
 - **Clipboard mode** — `summon -c` opens whatever URL/path you just copied.
 - **Reveal** — `summon -r file` highlights it in Finder/Explorer/your file manager.
-- **Recent + interactive picker** — re-open recent items or pick from a menu.
+- **Recent + fuzzy picker** — re-open recent items or fuzzy-search a menu of bookmarks/history.
 - **Dry run** — `--dry-run` prints exactly what would happen without doing it.
 - **Pick the app** — force a specific app and pass it arguments.
 - **Pipe-friendly** — stream data over stdin; the file type is auto-detected.
@@ -130,12 +131,19 @@ This installs the `summon` command. Or run it once without installing:
 npx summon-open https://github.com
 ```
 
-<details>
-<summary>Other install channels</summary>
+**Homebrew** (macOS/Linux):
 
-Homebrew and Scoop manifests are planned. In the meantime, `npm`/`npx` work on every platform. If you maintain a package repo and want to help, contributions are welcome.
+```sh
+brew install --formula https://raw.githubusercontent.com/Aditya060806/summon/main/dist/homebrew/summon-open.rb
+```
+
+**Scoop** (Windows):
+
+```powershell
+scoop install https://raw.githubusercontent.com/Aditya060806/summon/main/dist/scoop/summon-open.json
+```
 
-</details>
+Both channels install the same `summon` command and depend on Node.js. The manifests live in [`dist/`](dist).
 
 ## Quick start
 
@@ -191,6 +199,8 @@ The whole tool at a glance — task on the left, command on the right.
 | List bookmarks | `summon --bookmarks` |
 | Remove a bookmark | `summon --remove-bookmark docs` |
 | Search the web | `summon -s "query here"` |
+| Search with a specific engine | `summon -s "flatMap" -e mdn` |
+| List search engines | `summon --engines` |
 | Open clipboard URL | `summon -c` |
 | Reveal in file manager | `summon report.pdf -r` |
 | Re-open something recent | `summon --recent` |
@@ -243,6 +253,8 @@ $ summon --help
 | `--extension` | | string | auto | Extension to use for piped stdin when the type can't be auto-detected. |
 | `--dry-run` | `-n` | boolean | `false` | Print what would be opened without launching anything. |
 | `--search` | `-s` | boolean | `false` | Treat the input as a web search query. |
+| `--engine <name>` | `-e` | string | config | Search engine to use with `--search`. See `--engines`. |
+| `--engines` | | boolean | `false` | List available search engines (`*` marks the default). |
 | `--clipboard` | `-c` | boolean | `false` | Open the URL/path currently on the clipboard. |
 | `--reveal` | `-r` | boolean | `false` | Reveal/highlight the file or folder in the file manager. |
 | `--recent` | | boolean | `false` | Interactively pick from recently opened items. |
@@ -292,7 +304,15 @@ Bookmarks live in your [config file](#configuration) and can also be edited by h
 summon -s "how to exit vim"
 ```
 
-The engine is configurable — see [Configuration](#configuration). The default is Google.
+Pick an engine per search with `--engine`/`-e`, and list what's available with `--engines`:
+
+```sh
+summon -s "flatMap" -e mdn
+summon -s "left-pad" -e npm
+summon --engines
+```
+
+Built-in engines include `google` (default), `ddg`, `bing`, `brave`, `npm`, `gh`, `mdn`, `so`, `yt`, and `wiki`. Add your own or change the default in [Configuration](#configuration).
 
 ### Clipboard
 
@@ -326,7 +346,7 @@ summon report.pdf --reveal
 summon --recent
 ```
 
-Run `summon` with no arguments in a terminal and it shows an interactive menu of your bookmarks and recent items.
+Run `summon` with no arguments in a terminal and it shows an interactive **fuzzy picker** of your bookmarks and recent items. Just start typing to filter (fuzzy, so `ghb` matches `github`), enter a number to select from the visible list, or press Enter on an empty line to cancel. When your filter narrows to a single match, it's selected automatically.
 
 ### Dry run
 
@@ -436,14 +456,19 @@ You can override it with the `SUMMON_CONFIG_DIR` environment variable (also hand
 		"docs": "https://docs.example.com",
 		"repo": "https://github.com/Aditya060806/summon"
 	},
-	"searchEngine": "https://www.google.com/search?q=%s"
+	"defaultSearchEngine": "ddg",
+	"searchEngines": {
+		"work": "https://intranet.example.com/search?q=%s",
+		"scholar": "https://scholar.google.com/scholar?q=%s"
+	}
 }
 ```
 
 - `bookmarks` — map of alias → target. Managed via `--save` / `--remove-bookmark`, or edited by hand.
-- `searchEngine` — a URL template where `%s` is replaced by the URL-encoded query. Examples:
-  - DuckDuckGo: `https://duckduckgo.com/?q=%s`
-  - Brave: `https://search.brave.com/search?q=%s`
+- `searchEngines` — map of engine name → URL template, where `%s` is replaced by the URL-encoded query. These are **merged** with the built-ins (`google`, `ddg`, `bing`, `brave`, `npm`, `gh`, `mdn`, `so`, `yt`, `wiki`), so you can add new ones or override existing ones.
+- `defaultSearchEngine` — the engine `--search` uses when `--engine` isn't given (default: `google`).
+
+> A legacy single `"searchEngine": "…"` string is still honored and appears as the `custom` engine.
 
 **`history.json`** stores your most recently opened targets (capped, de-duplicated) and powers `--recent`.
 
@@ -528,6 +553,8 @@ How `summon` stacks up against common alternatives:
 | Auto `https://` for bare domains | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Bookmarks / aliases | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Web search shortcut | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Configurable search engines | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Fuzzy interactive picker | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Open from clipboard | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Reveal in file manager | ✅ | ❌ | ⚠️ `-R` | ⚠️ | ❌ |
 | Recent / interactive picker | ✅ | ❌ | ❌ | ❌ | ❌ |
@@ -641,6 +668,20 @@ git config --global core.editor "summon --wait"
 **A non-existent `report.pdf` didn't open a website — good?**
 Yes. Names ending in a known file extension are treated as files, so typos give a clear "not found" (exit code 2) instead of launching a browser.
 
+## Releasing
+
+Maintainers: releases publish to npm automatically when a version tag is pushed (see [`.github/workflows/release.yml`](.github/workflows/release.yml)).
+
+1. One-time: add an npm automation token as the `NPM_TOKEN` repository secret.
+2. Cut a release:
+
+   ```sh
+   npm version patch   # or minor / major — bumps package.json and tags
+   git push --follow-tags
+   ```
+
+The workflow runs the tests, then publishes with npm provenance. See the [changelog](changelog.md) for release history.
+
 ## Related
 
 - [open](https://github.com/sindresorhus/open) — the programmatic API that powers this CLI.