evan/glimpse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(config): add TypeScript build and config support

Browse Source
This commit is contained in:
Evan Reichard
2026-04-27 08:53:17 -04:00
parent 2f83fa3117
commit 6b3ec32b3a
12 changed files with 1043 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
src/config.ts Normal file
View File

@@ -0,0 +1,117 @@
import { existsSync, readFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
export interface GlimpseConfig {
search?: {
provider?: "kagi";
};
providers?: {
kagi?: {
token?: string;
};
};
}
export class ConfigError extends Error {
code: string;
constructor(code: string, message: string) {
super(message);
this.code = code;
}
}
export function defaultConfigPath(
env: NodeJS.ProcessEnv = process.env,
): string {
const configHome = env.XDG_CONFIG_HOME || join(homedir(), ".config");
return join(configHome, "glimpse", "config.json");
}
function errorMessage(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
function isObject(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
function validateObject(
value: unknown,
path: string,
name: string,
): asserts value is Record<string, unknown> | undefined {
if (value !== undefined && !isObject(value)) {
throw new ConfigError(
"INVALID_CONFIG",
`${name} must be an object: ${path}`,
);
}
}
function validateString(
value: unknown,
path: string,
name: string,
): asserts value is string | undefined {
if (value !== undefined && typeof value !== "string") {
throw new ConfigError(
"INVALID_CONFIG",
`${name} must be a string: ${path}`,
);
}
}
function validateConfig(
config: unknown,
path: string,
): asserts config is GlimpseConfig {
if (!isObject(config)) {
throw new ConfigError(
"INVALID_CONFIG",
`Config file must contain a JSON object: ${path}`,
);
}
// Validate Search Config
validateObject(config.search, path, "search");
validateString(config.search?.provider, path, "search.provider");
if (config.search?.provider && !["kagi"].includes(config.search.provider)) {
throw new ConfigError(
"INVALID_CONFIG",
`Unsupported search.provider value: ${config.search.provider}. Expected kagi: ${path}`,
);
}
// Validate Provider Config
validateObject(config.providers, path, "providers");
validateObject(config.providers?.kagi, path, "providers.kagi");
validateString(config.providers?.kagi?.token, path, "providers.kagi.token");
}
export function loadConfig({
path = defaultConfigPath(),
}: { path?: string } = {}): GlimpseConfig {
if (!existsSync(path)) {
return {};
}
let parsed: unknown;
// Parse Config File
try {
parsed = JSON.parse(readFileSync(path, "utf-8"));
} catch (err) {
throw new ConfigError(
"CONFIG_READ_FAILED",
`Failed to read config file ${path}: ${errorMessage(err)}`,
);
}
// Validate Config Shape
validateConfig(parsed, path);
return parsed;
}

32
src/driver.js → src/driver.ts
View File

@@ -1,13 +1,13 @@
import { execFileSync } from "node:child_process";
import { Builder } from "selenium-webdriver";
import { Builder, type WebDriver } from "selenium-webdriver";
import firefox from "selenium-webdriver/firefox.js";
/**
* Resolve the geckodriver path from $PATH.
*
* @returns {string}
*/
function findGeckodriver() {
export interface DriverOptions {
headless?: boolean;
existingUrl?: string;
}
function findGeckodriver(): string {
try {
return execFileSync("which", ["geckodriver"], { encoding: "utf-8" }).trim();
} catch {
@@ -17,16 +17,10 @@ function findGeckodriver() {
}
}
/**
* Create a Firefox WebDriver instance.
*
* @param {object} opts
* @param {boolean} [opts.headless=false] - Run Firefox in headless mode.
* @param {string} [opts.existingUrl] - Connect to an already-running
* WebDriver server (e.g. "http://localhost:4444").
* @returns {Promise<import("selenium-webdriver").WebDriver>}
*/
export async function createDriver({ headless = false, existingUrl } = {}) {
export async function createDriver({
headless = false,
existingUrl,
}: DriverOptions = {}): Promise<WebDriver> {
const options = new firefox.Options();
// Configure Headless
@@ -34,7 +28,9 @@ export async function createDriver({ headless = false, existingUrl } = {}) {
options.addArguments("--headless");
}
const builder = new Builder().forBrowser("firefox").setFirefoxOptions(options);
const builder = new Builder()
.forBrowser("firefox")
.setFirefoxOptions(options);
// Connect to Existing Server
if (existingUrl) {

51
src/index.js → src/index.ts
View File

@@ -1,5 +1,6 @@
#!/usr/bin/env node
import { loadConfig, type GlimpseConfig } from "./config.js";
import { createDriver } from "./driver.js";
import { searchKagi } from "./providers/kagi.js";
import { readFileSync, writeFileSync } from "node:fs";
@@ -8,7 +9,7 @@ import TurndownService from "turndown";
const DEFAULT_TIMEOUT_MS = 10000;
const POLL_INTERVAL_MS = 200;
const startTime = Date.now();
const runContext = {};
const runContext: { targetUrl?: string; currentUrl?: string } = {};
// Parse CLI Args
const [command, ...args] = process.argv.slice(2);
@@ -18,6 +19,8 @@ const inlineJs = getOption("--js");
const scriptPath = getOption("--script");
const waitJs = getOption("--wait-js");
const waitUntil = getOption("--wait-until") ?? "none";
const configPath = getOption("--config");
let appConfig: GlimpseConfig = {};
let timeoutMs = DEFAULT_TIMEOUT_MS;
function getOption(name) {
@@ -50,6 +53,9 @@ function printResult(result) {
}
class CliError extends Error {
code: string;
details: Record<string, unknown>;
constructor(code, message, details = {}) {
super(message);
this.code = code;
@@ -84,6 +90,7 @@ Common Options:
--wait-until=<state> Wait for readiness: none, interactive, complete (default: none)
--js=<code> Execute inline JS before command logic
--script=<file> Execute JS from a file before command logic
--config=<file> Read config from a custom path
Exec Options:
--js=<code> Return the top-level JS result
@@ -97,8 +104,8 @@ Reader Options:
--output=<file> Write output to a file
Search Options:
--provider=<provider> Search provider: kagi (default: kagi)
--token=<token> Kagi token (default: KAGI_TOKEN)
--provider=<provider> Search provider: kagi (default: config or kagi)
--token=<token> Kagi token (default: KAGI_TOKEN or config)
Examples:
glimpse snapshot https://example.com
@@ -114,7 +121,10 @@ function printHelp() {
}
function usage() {
cliError("USAGE_ERROR", "Usage: glimpse <command> <url> [options]. Run glimpse --help for details.");
cliError(
"USAGE_ERROR",
"Usage: glimpse <command> <url> [options]. Run glimpse --help for details.",
);
}
function parseTimeout() {
@@ -179,7 +189,9 @@ async function waitForReadyState(driver) {
try {
await driver.wait(async () => {
const readyState = await driver.executeScript("return document.readyState");
const readyState = await driver.executeScript(
"return document.readyState",
);
return waitUntil === "interactive"
? ["interactive", "complete"].includes(readyState)
: readyState === "complete";
@@ -214,7 +226,10 @@ async function waitForJs(driver) {
await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
}
cliError("WAIT_TIMEOUT", `Timed out after ${timeoutMs}ms waiting for --wait-js`);
cliError(
"WAIT_TIMEOUT",
`Timed out after ${timeoutMs}ms waiting for --wait-js`,
);
}
async function runPreludeScript(driver) {
@@ -417,7 +432,8 @@ function renderReaderOutput(article, format) {
}
async function searchCommand() {
const provider = getOption("--provider") ?? "kagi";
const provider =
getOption("--provider") ?? appConfig.search?.provider ?? "kagi";
const query = getPositionalArgs().join(" ");
if (!query) usage();
@@ -428,6 +444,7 @@ async function searchCommand() {
return searchKagi({
query,
token: getOption("--token"),
config: appConfig,
headless,
existingUrl,
timeoutMs,
@@ -458,8 +475,9 @@ async function readerCommand() {
// Wait For Reader Content
let article;
try {
article = await driver.wait(async () => {
return driver.executeScript(`
article = await driver.wait(
async () => {
return driver.executeScript(`
const content = document.querySelector("#moz-reader-content, .moz-reader-content");
const error = document.querySelector(".reader-error");
const text = content?.innerText?.trim() || "";
@@ -481,7 +499,10 @@ async function readerCommand() {
return null;
`);
}, timeoutMs, `No readable article content found for URL: ${targetUrl}`);
},
timeoutMs,
`No readable article content found for URL: ${targetUrl}`,
);
} catch (err) {
cliError("TIMEOUT", err.message);
}
@@ -517,6 +538,9 @@ async function main() {
validateCommonOptions();
// Load Config
appConfig = loadConfig({ path: configPath });
switch (command) {
case "snapshot":
return snapshotCommand();
@@ -537,7 +561,12 @@ main()
.then(printResult)
.catch((err) => {
const code = err.code || "COMMAND_FAILED";
const output = {
const output: {
ok: false;
error: { code: string; message: string };
elapsedMs: number;
url?: string;
} = {
ok: false,
error: {
code,

52
src/providers/kagi.js → src/providers/kagi.ts
View File

@@ -1,7 +1,26 @@
import { createDriver } from "../driver.js";
import type { GlimpseConfig } from "../config.js";
export interface SearchResult {
title: string;
url: string;
description: string;
}
export interface SearchKagiOptions {
query?: string;
token?: string;
config?: GlimpseConfig;
headless?: boolean;
existingUrl?: string;
timeoutMs?: number;
intervalMs?: number;
}
export class SearchProviderError extends Error {
constructor(code, message) {
code: string;
constructor(code: string, message: string) {
super(message);
this.code = code;
}
@@ -17,28 +36,36 @@ export const kagiSearchScript = `return Array.from(document.querySelectorAll("di
}));`;
// Build Kagi Search Url
export function buildKagiSearchUrl(query, token) {
export function buildKagiSearchUrl(query: string, token: string): string {
return `https://kagi.com/search?token=${encodeURIComponent(token)}&q=${encodeURIComponent(query)}`;
}
// Resolve Config Token
function configToken(config: GlimpseConfig): string | undefined {
return config.providers?.kagi?.token;
}
// Search Kagi
export async function searchKagi({
query,
token = process.env.KAGI_TOKEN,
token,
config = {},
headless = true,
existingUrl,
timeoutMs = 5000,
intervalMs = 200,
} = {}) {
}: SearchKagiOptions = {}): Promise<SearchResult[]> {
if (!query) {
throw new SearchProviderError("QUERY_REQUIRED", "query is required");
}
// Validate Kagi Token
if (!token) {
// Resolve Kagi Token
const resolvedToken = token || process.env.KAGI_TOKEN || configToken(config);
if (!resolvedToken) {
throw new SearchProviderError(
"KAGI_TOKEN_REQUIRED",
"Kagi search requires --token or the KAGI_TOKEN environment variable.",
"Kagi search requires --token, the KAGI_TOKEN environment variable, or a config token.",
);
}
@@ -46,15 +73,18 @@ export async function searchKagi({
try {
// Navigate To Kagi
await driver.get(buildKagiSearchUrl(query, token));
await driver.get(buildKagiSearchUrl(query, resolvedToken));
// Poll For Results
let result = [];
let result: SearchResult[] = [];
const start = Date.now();
while (Date.now() - start < timeoutMs) {
result = await driver.executeScript(kagiSearchScript);
if (Array.isArray(result) && result.length > 0) break;
const scriptResult = await driver.executeScript(kagiSearchScript);
result = Array.isArray(scriptResult)
? (scriptResult as SearchResult[])
: [];
if (result.length > 0) break;
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}