@tks/wayfinder 0.2.1 → 0.2.3

package/README.md

@@ -2,13 +2,19 @@
 
 ## Install
 
-Requires [Bun](https://bun.sh/) runtime.
+Primary install method:
+
+```bash
+brew install tksohishi/tap/wayfinder
+```
+
+Secondary fallback method (requires [Bun](https://bun.sh/) runtime):
 
 ```bash
 bun install -g @tks/wayfinder
 ```
 
-Or install from source:
+Install from source:
 
 ```bash
 git clone https://github.com/tksohishi/wayfinder.git
@@ -19,7 +25,18 @@ bun link
 
 ## Setup
 
-Set API key by environment variable (preferred):
+First run:
+
+```bash
+wayfinder setup
+```
+
+This interactive command explains why the key is needed, where to get it, and saves it to your local config.
+SerpApi is the API provider wayfinder uses to fetch Google Flights and Google Hotels results.
+
+Advanced alternatives:
+
+Set API key by environment variable:
 
 ```bash
 export SERPAPI_API_KEY="your_key"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tks/wayfinder",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Travel search for your terminal and your AI agents",
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -1,9 +1,12 @@
-import { resolveApiKey } from "./config";
+import { getConfigPath, readConfigApiKey, resolveApiKey, writeConfigApiKey } from "./config";
 import { CliError } from "./errors";
 import { renderFlightTable, renderHotelTable } from "./format";
 import { parseCliArgs } from "./parse";
 import { searchFlightBookingOptions, searchFlights, searchHotels } from "./serpapi";
 import { ExitCode } from "./types";
+import { createInterface } from "node:readline/promises";
+import { stdin as defaultStdin, stdout as defaultStdout } from "node:process";
+import { existsSync, unlinkSync } from "node:fs";
 
 interface Output {
   stdout: (message: string) => void;
@@ -15,16 +18,23 @@ interface RunOptions {
   homeDir?: string;
   fetchImpl?: typeof fetch;
   output?: Output;
+  isInteractive?: boolean;
+  promptImpl?: (prompt: string) => Promise<string>;
 }
 
-const HELP_TEXT = `wayfinder v0.2.0 travel search
+const HELP_TEXT = `wayfinder v0.2.1 travel search
 
 Usage:
+  wayfinder setup [--reset]
   wayfinder flights --from SFO --to JFK --date 2026-03-21 [filters]
   wayfinder flights one-way --from SFO --to JFK --date 2026-03-21 [filters]
   wayfinder flights booking --from SFO --to JFK --date 2026-03-21 --token <BOOKING_TOKEN> [--token <BOOKING_TOKEN>] [--json]
   wayfinder hotels --where "New York, NY" --check-in 2026-03-21 --check-out 2026-03-23 [filters]
 
+Setup:
+  Runs interactive key setup and stores your SerpApi key in local config.
+  --reset                   Remove existing local config and reconfigure
+
 Flights required:
   --from <IATA>             Origin airport code
   --to <IATA>               Destination airport code
@@ -62,12 +72,40 @@ export async function runWayfinder(
   argv: string[] = process.argv.slice(2),
   options: RunOptions = {},
 ): Promise<number> {
+  const env = options.env ?? process.env;
+  const homeDir = options.homeDir;
+  const isInteractive = options.isInteractive ?? Boolean(defaultStdin.isTTY && defaultStdout.isTTY);
   const output = options.output ?? {
     stdout: (message: string) => console.log(message),
     stderr: (message: string) => console.error(message),
   };
 
   try {
+    if (argv.length === 0) {
+      try {
+        resolveApiKey(env, homeDir);
+        output.stdout(HELP_TEXT);
+        return ExitCode.Success;
+      } catch (error) {
+        if (error instanceof CliError && error.exitCode === ExitCode.MissingApiKey) {
+          if (!isInteractive) {
+            output.stderr(error.message);
+            return error.exitCode;
+          }
+
+          return await runSetupFlow(output, homeDir, options.promptImpl, isInteractive, false);
+        }
+
+        if (error instanceof CliError) {
+          output.stderr(error.message);
+          return error.exitCode;
+        }
+
+        output.stderr("Unexpected internal error");
+        return ExitCode.InternalError;
+      }
+    }
+
     const parsed = parseCliArgs(argv);
 
     if (parsed.help) {
@@ -75,7 +113,17 @@ export async function runWayfinder(
       return ExitCode.Success;
     }
 
-    const apiKey = resolveApiKey(options.env ?? process.env, options.homeDir);
+    if (parsed.mode === "setup") {
+      return await runSetupFlow(
+        output,
+        homeDir,
+        options.promptImpl,
+        isInteractive,
+        parsed.reset,
+      );
+    }
+
+    const apiKey = resolveApiKey(env, homeDir);
     if (parsed.mode === "flights") {
       const flights = await searchFlights(parsed.query, apiKey, options.fetchImpl ?? fetch);
 
@@ -186,3 +234,78 @@ function renderFlightBookingText(
 
   return lines.join("\n").trimEnd();
 }
+
+async function runSetupFlow(
+  output: Output,
+  homeDir: string | undefined,
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  isInteractive: boolean,
+  forceReset: boolean,
+): Promise<number> {
+  if (!isInteractive) {
+    throw new CliError(
+      "wayfinder setup requires an interactive terminal. Use SERPAPI_API_KEY or write ~/.config/wayfinder/config.json manually.",
+      ExitCode.InvalidInput,
+    );
+  }
+
+  output.stdout("Wayfinder needs a SerpApi API key to fetch live flight and hotel data.");
+  output.stdout("SerpApi is the API provider that returns Google Flights and Google Hotels search results.");
+  output.stdout("Get your key at: https://serpapi.com/manage-api-key");
+  output.stdout("");
+
+  const configPath = getConfigPath(homeDir);
+  if (forceReset) {
+    if (existsSync(configPath)) {
+      unlinkSync(configPath);
+      output.stdout("Existing config removed due to --reset.");
+    } else {
+      output.stdout("No existing config found. Starting fresh setup.");
+    }
+  }
+
+  const existingKey = readConfigApiKey(homeDir);
+  if (existingKey && !forceReset) {
+    const overwrite = await promptWithFallback(promptImpl, "A key already exists. Overwrite? [y/N]: ");
+    if (!/^(y|yes)$/i.test(overwrite.trim())) {
+      output.stdout("Setup cancelled. Existing key kept.");
+      return ExitCode.Success;
+    }
+  }
+
+  let apiKey = "";
+  while (apiKey.length === 0) {
+    apiKey = (await promptWithFallback(promptImpl, "Enter your SerpApi API key: ")).trim();
+    if (apiKey.length === 0) {
+      output.stdout("API key cannot be empty.");
+    }
+  }
+
+  writeConfigApiKey(apiKey, homeDir);
+  output.stdout("");
+  output.stdout(`Setup complete. Saved key to ${configPath}.`);
+  output.stdout("Next step: wayfinder --help");
+  output.stdout("Quick start: wayfinder flights --from SFO --to JFK --date 2026-04-10");
+
+  return ExitCode.Success;
+}
+
+async function promptWithFallback(
+  promptImpl: ((prompt: string) => Promise<string>) | undefined,
+  message: string,
+): Promise<string> {
+  if (promptImpl) {
+    return promptImpl(message);
+  }
+
+  const rl = createInterface({
+    input: defaultStdin,
+    output: defaultStdout,
+  });
+
+  try {
+    return await rl.question(message);
+  } finally {
+    rl.close();
+  }
+}

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { CliError } from "./errors";
@@ -14,10 +14,18 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     return envKey;
   }
 
-  const configPath = path.join(homeDir, ".config", "wayfinder", "config.json");
+  const configKey = readConfigApiKey(homeDir);
+  if (!configKey) {
+    throw missingKeyError();
+  }
+
+  return configKey;
+}
 
+export function readConfigApiKey(homeDir = os.homedir()): string | undefined {
+  const configPath = getConfigPath(homeDir);
   if (!existsSync(configPath)) {
-    throw missingKeyError();
+    return undefined;
   }
 
   let parsed: ConfigFile;
@@ -26,21 +34,49 @@ export function resolveApiKey(env: NodeJS.ProcessEnv = process.env, homeDir = os
     parsed = JSON.parse(raw) as ConfigFile;
   } catch {
     throw new CliError(
-      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON.",
+      "Could not read ~/.config/wayfinder/config.json. Ensure it is valid JSON or rerun `wayfinder setup`.",
       ExitCode.MissingApiKey,
     );
   }
 
-  if (typeof parsed.serpApiKey !== "string" || parsed.serpApiKey.trim() === "") {
-    throw missingKeyError();
+  if (typeof parsed.serpApiKey !== "string") {
+    return undefined;
   }
 
-  return parsed.serpApiKey.trim();
+  const key = parsed.serpApiKey.trim();
+  return key.length > 0 ? key : undefined;
+}
+
+export function writeConfigApiKey(apiKey: string, homeDir = os.homedir()): void {
+  const configPath = getConfigPath(homeDir);
+  const configDir = path.dirname(configPath);
+  mkdirSync(configDir, { recursive: true });
+  writeFileSync(
+    configPath,
+    `${JSON.stringify(
+      {
+        serpApiKey: apiKey,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+}
+
+export function getConfigPath(homeDir = os.homedir()): string {
+  return path.join(homeDir, ".config", "wayfinder", "config.json");
 }
 
 function missingKeyError(): CliError {
   return new CliError(
-    "Missing SerpApi key. Set SERPAPI_API_KEY or add ~/.config/wayfinder/config.json with {\"serpApiKey\":\"...\"}.",
+    [
+      "Missing SerpApi API key.",
+      "Wayfinder needs a SerpApi key to fetch live flight and hotel results.",
+      "SerpApi is the API provider used for Google Flights and Google Hotels data.",
+      "Get a key at: https://serpapi.com/manage-api-key",
+      "Then run: wayfinder setup",
+    ].join("\n"),
     ExitCode.MissingApiKey,
   );
 }

package/src/parse.ts

@@ -35,7 +35,7 @@ interface FlightBookingRawOptions {
   help: boolean;
 }
 
-type SearchMode = "flights" | "hotels" | "flight-booking";
+type SearchMode = "flights" | "hotels" | "flight-booking" | "setup";
 
 const HELP_FLAGS = new Set(["-h", "--help"]);
 
@@ -57,6 +57,10 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     return parseFlightBookingArgs(args);
   }
 
+  if (mode === "setup") {
+    return parseSetupArgs(args);
+  }
+
   return parseFlightsArgs(args);
 }
 
@@ -277,6 +281,22 @@ function parseFlightBookingArgs(args: string[]): ParsedArgs {
   };
 }
 
+function parseSetupArgs(args: string[]): ParsedArgs {
+  const outputJson = args.includes("--json");
+  const reset = args.includes("--reset");
+  const unsupported = args.filter((token) => token !== "--json" && token !== "--reset");
+  if (unsupported.length > 0) {
+    throw new CliError(`Unknown argument for setup: ${unsupported[0]}`, ExitCode.InvalidInput);
+  }
+
+  return {
+    help: false,
+    mode: "setup",
+    outputJson,
+    reset,
+  };
+}
+
 function buildFlightQuery(raw: FlightRawOptions): FlightQuery {
   if (!raw.from || !raw.to || !raw.date) {
     throw new CliError("Missing required flags: --from, --to, --date", ExitCode.InvalidInput);
@@ -410,8 +430,13 @@ function stripSubcommands(argv: string[]): { mode: SearchMode; args: string[] }
     return { mode: "flights", args };
   }
 
+  if (args[0] === "setup") {
+    args.shift();
+    return { mode: "setup", args };
+  }
+
   throw new CliError(
-    "Missing subcommand: use `flights` or `hotels`",
+    "Missing subcommand: use `setup`, `flights`, or `hotels`",
     ExitCode.InvalidInput,
   );
 }

package/src/types.ts

@@ -63,11 +63,19 @@ export interface ParsedArgsFlightBooking {
   query: FlightBookingQuery;
 }
 
+export interface ParsedArgsSetup {
+  help: false;
+  mode: "setup";
+  outputJson: boolean;
+  reset: boolean;
+}
+
 export type ParsedArgs =
   | ParsedArgsHelp
   | ParsedArgsFlights
   | ParsedArgsHotels
-  | ParsedArgsFlightBooking;
+  | ParsedArgsFlightBooking
+  | ParsedArgsSetup;
 
 export interface FlightOption {
   price: number;