gemiterm 2.0.0 → 2.1.1

package/README.md

@@ -4,13 +4,37 @@ Access and manage your Gemini web chats from the command line. GemiTerm bridges
 
 ## Prerequisites
 
-- **[Bun](https://bun.sh)** runtime
+- **[Bun](https://bun.sh)** runtime ≥ 1.0.0
 - **Chromium Browser** — GemiTerm uses your system Chrome/Edge if available, otherwise installs Playwright's Chromium automatically
 - **Google Account** with access to [Gemini](https://gemini.google.com)
 
+## Quick Start (no install)
+
+Use `bunx` to run GemiTerm directly — no install step needed:
+
+```bash
+bunx gemiterm auth          # authenticate with Google
+bunx gemiterm list          # list your chats
+```
+
 ## Installation
 
-See [docs/INSTALL.md](docs/INSTALL.md) for the full guide, uninstall instructions, troubleshooting, and build-from-source steps.
+### Global install (recommended for daily use)
+
+```bash
+bun install gemiterm -g
+```
+
+Then use from anywhere:
+
+```bash
+gemiterm auth
+gemiterm list
+```
+
+### Install scripts (binary drop)
+
+For systems without Bun — the script auto-bootstraps Bun if needed.
 
 **Windows** (PowerShell 7+):
 
@@ -24,14 +48,9 @@ irm https://github.com/expert-vision-software/GemiTerm/releases/latest/download/
 curl -fsSL https://github.com/expert-vision-software/GemiTerm/releases/latest/download/install.sh | bash
 ```
 
-> **Upgrading from v1.4.1?** Your profiles, cookies, and default profile marker are preserved. The installer replaces the binary in place; it does NOT touch your config dir. See the "Upgrade from v1.4.1" section in [docs/INSTALL.md](docs/INSTALL.md) for details.
-
-## Quick Start
+See [docs/INSTALL.md](docs/INSTALL.md) for the full guide, uninstall instructions, troubleshooting, and build-from-source steps.
 
-```bash
-gemiterm auth          # authenticate with Google
-gemiterm list          # list your chats
-```
+> **Upgrading from v1.4.1?** Your profiles, cookies, and default profile marker are preserved. See the "Upgrade from v1.4.1" section in [docs/INSTALL.md](docs/INSTALL.md) for details.
 
 ## Development
 
@@ -197,6 +216,10 @@ Checks for system Chrome/Edge first, falls back to installing Playwright's Chrom
 gemiterm -v <command>
 ```
 
+## Skills
+
+GemiTerm has an associated skills repository for AI coding agents (Copilot, Claude, etc.) that provides domain-specific instructions for working with **gemiterm** and automating common workflows. There's also a fun `debate-with-gemini` skill that created an interactive turn-based conversation between your agent and gemini. See [opencode-gemiterm-skills](https://www.npmjs.com/package/opencode-gemiterm-skills).
+
 ## Configuration
 
 ### Configuration Directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemiterm",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -14,9 +14,16 @@
   "publishConfig": {
     "access": "public"
   },
-  "devDependencies": {
-    "@types/bun": "^1.3.14"
+  "bin": {
+    "gemiterm": "src/cli/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
   },
+  "files": [
+    "src/",
+    "README.md"
+  ],
   "scripts": {
     "start": "bun run src/cli/index.ts",
     "dev": "bun run src/cli/index.ts",
@@ -34,12 +41,14 @@
     "build:windows": "bun run scripts/build.ts windows",
     "build:release": "bun run scripts/build.ts release"
   },
-  "peerDependencies": {
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
     "typescript": "^6.0.3"
   },
   "dependencies": {
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
+    "commander": "^15.0.0",
     "gemini-reverse": "^1.0.12"
   }
 }

package/src/cli/command-registry.ts

@@ -1,62 +1,66 @@
-import type { Mediator } from "../core/mediator.ts";
-import type { ProfileAuthManager } from "../services/profile-auth-manager.ts";
-import { AuthCommand } from "./commands/auth-command.ts";
-import { ProfileCommand } from "./commands/profile-command.ts";
-import { StatusCommand } from "./commands/status-command.ts";
-import { ListCommand } from "./commands/list-command.ts";
-import { FetchCommand } from "./commands/fetch-command.ts";
-import { ContinueCommand } from "./commands/continue-command.ts";
-import { NewCommand } from "./commands/new-command.ts";
-import { DeleteCommand } from "./commands/delete-command.ts";
-import { ExportCommand } from "./commands/export-command.ts";
-import { ExportAllCommand } from "./commands/export-all-command.ts";
-import { InstallBrowserCommand } from "./commands/install-browser-command.ts";
-
-export interface CliCommandContext {
-  verbose: boolean;
-  mediator: Mediator;
-  profileAuthManager: ProfileAuthManager;
-}
-
-export interface CliCommand {
-  readonly name: string;
-  readonly description: string;
-  execute(args: string[], context: CliCommandContext): Promise<void>;
-}
-
-export class CommandRegistry {
-  private handlers = new Map<string, CliCommand>();
-
-  register(commandName: string, handler: CliCommand): void {
-    if (this.handlers.has(commandName)) {
-      throw new Error(`Command already registered: ${commandName}`);
-    }
-    this.handlers.set(commandName, handler);
-  }
-
-  getHandler(commandName: string): CliCommand | undefined {
-    return this.handlers.get(commandName);
-  }
-
-  has(commandName: string): boolean {
-    return this.handlers.has(commandName);
-  }
-
-  getRegisteredNames(): string[] {
-    return [...this.handlers.keys()];
-  }
-
-  registerAllCommands(): void {
-    this.register("auth", new AuthCommand());
-    this.register("profile", new ProfileCommand());
-    this.register("status", new StatusCommand());
-    this.register("list", new ListCommand());
-    this.register("fetch", new FetchCommand());
-    this.register("continue", new ContinueCommand());
-    this.register("new", new NewCommand());
-    this.register("delete", new DeleteCommand());
-    this.register("export", new ExportCommand());
-    this.register("export-all", new ExportAllCommand());
-    this.register("install-browser", new InstallBrowserCommand());
-  }
-}
+import type { Mediator } from "../core/mediator.ts";
+import type { ProfileAuthManager } from "../services/profile-auth-manager.ts";
+import { AuthCommand } from "./commands/auth-command.ts";
+import { ProfileCommand } from "./commands/profile-command.ts";
+import { StatusCommand } from "./commands/status-command.ts";
+import { ListCommand } from "./commands/list-command.ts";
+import { FetchCommand } from "./commands/fetch-command.ts";
+import { ContinueCommand } from "./commands/continue-command.ts";
+import { NewCommand } from "./commands/new-command.ts";
+import { DeleteCommand } from "./commands/delete-command.ts";
+import { ExportCommand } from "./commands/export-command.ts";
+import { ExportAllCommand } from "./commands/export-all-command.ts";
+import { InstallBrowserCommand } from "./commands/install-browser-command.ts";
+import { InstallSkillsCommand } from "./commands/install-skills-command.ts";
+
+export interface CliCommandContext {
+  verbose: boolean;
+  mediator: Mediator;
+  profileAuthManager: ProfileAuthManager;
+}
+
+export interface CliCommand {
+  readonly name: string;
+  readonly description: string;
+  execute(args: string[], context: CliCommandContext): Promise<void>;
+}
+
+export class CommandRegistry {
+  private handlers = new Map<string, CliCommand>();
+
+  register(commandName: string, handler: CliCommand): void {
+    if (this.handlers.has(commandName)) {
+      throw new Error(`Command already registered: ${commandName}`);
+    }
+    this.handlers.set(commandName, handler);
+  }
+
+  getHandler(commandName: string): CliCommand | undefined {
+    return this.handlers.get(commandName);
+  }
+
+  has(commandName: string): boolean {
+    return this.handlers.has(commandName);
+  }
+
+  getRegisteredNames(): string[] {
+    return [...this.handlers.keys()];
+  }
+
+  registerAllCommands(): void {
+    const authCommand = new AuthCommand();
+    this.register("auth", authCommand);
+    this.register("login", authCommand);
+    this.register("profile", new ProfileCommand());
+    this.register("status", new StatusCommand());
+    this.register("list", new ListCommand());
+    this.register("fetch", new FetchCommand());
+    this.register("continue", new ContinueCommand());
+    this.register("new", new NewCommand());
+    this.register("delete", new DeleteCommand());
+    this.register("export", new ExportCommand());
+    this.register("export-all", new ExportAllCommand());
+    this.register("install-browser", new InstallBrowserCommand());
+    this.register("install-skills", new InstallSkillsCommand());
+  }
+}

package/src/cli/commands/continue-command.ts

@@ -9,13 +9,18 @@ import {
   type SendMessageCommandResult,
 } from "../../core/command-handlers.ts";
 import { runInteractiveLoop, type MessageHandlerResult } from "../utils/interactive-prompt.ts";
+import { checkArgLength } from "../utils/long-arg-guard.ts";
+import { loadPromptFromFile, spillOverToTempFile } from "../utils/prompt-file.ts";
+import { removeFile } from "../../infrastructure/io.ts";
 
 interface ContinueCommandOptions {
   help: boolean;
+  promptFile: string | null;
 }
 
 const DEFAULT_OPTIONS: ContinueCommandOptions = {
   help: false,
+  promptFile: null,
 };
 
 export class ContinueCommand implements CliCommand {
@@ -36,6 +41,7 @@ export class ContinueCommand implements CliCommand {
 
     for (const arg of args) {
       if (arg.startsWith("--") || arg.startsWith("-")) continue;
+      if (options.promptFile && arg === options.promptFile) continue;
       if (!conversationId) {
         conversationId = arg;
       } else if (!message) {
@@ -43,11 +49,66 @@ export class ContinueCommand implements CliCommand {
       }
     }
 
+    if (options.promptFile) {
+      if (!conversationId) {
+        console.error(
+          chalk.red(
+            `Error: --prompt-file requires a conversation_id. ` +
+              `Specify a conversation to continue, e.g. \`gemiterm continue <conversation_id> --prompt-file <path>\`.`,
+          ),
+        );
+        process.exit(1);
+      }
+      if (message) {
+        console.error(
+          chalk.red(
+            `Error: cannot use --prompt-file together with a positional message argument. ` +
+              `Use one or the other, not both.`,
+          ),
+        );
+        process.exit(1);
+      }
+    }
+
     if (!conversationId) {
       await this.invokeListCommand(context);
       return;
     }
 
+    let effectivePromptFile: string | null = null;
+    let isSpillover = false;
+    if (options.promptFile) {
+      effectivePromptFile = options.promptFile;
+    } else if (message) {
+      const guard = checkArgLength(message);
+      if (!guard.safe) {
+        const spilled = await spillOverToTempFile(message);
+        effectivePromptFile = spilled;
+        isSpillover = true;
+        console.log(
+          chalk.dim(
+            `[gemiterm] Message is ${guard.length} UTF-16 code units, exceeding the ${guard.limit} limit. ` +
+              `Spilled to temp file '${spilled}' and loading from there.`,
+          ),
+        );
+      }
+    }
+
+    if (effectivePromptFile) {
+      try {
+        message = await loadPromptFromFile(effectivePromptFile);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+      }
+      if (isSpillover) {
+        try {
+          removeFile(effectivePromptFile);
+        } catch {
+        }
+      }
+    }
+
     const mediator: Mediator = context.mediator;
 
     if (message) {
@@ -128,9 +189,19 @@ export class ContinueCommand implements CliCommand {
   private parseArgs(args: string[]): ContinueCommandOptions {
     const options = { ...DEFAULT_OPTIONS };
 
-    for (const arg of args) {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
       if (arg === "--help" || arg === "-h") {
         options.help = true;
+      } else if (arg === "--prompt-file" || arg === "-f") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          options.promptFile = next;
+          i++;
+        } else {
+          console.error(chalk.red(`Error: --prompt-file requires a path`));
+          process.exit(1);
+        }
       }
     }
 
@@ -149,6 +220,9 @@ export class ContinueCommand implements CliCommand {
     );
     console.log("");
     console.log(chalk.bold("Options:"));
+    console.log(
+      `  ${chalk.cyan("--prompt-file, -f <path>".padEnd(22))}${chalk.dim("Read the message from a file (bypasses the 2048 code unit arg limit)")}`,
+    );
     console.log(`  ${chalk.cyan("--help, -h".padEnd(22))}${chalk.dim("Show this help message")}`);
     console.log("");
     console.log(chalk.dim("If no conversation_id is provided, the list command will be invoked."));

package/src/cli/commands/install-skills-command.ts

@@ -0,0 +1,35 @@
+import chalk from "chalk";
+import type { CliCommand, CliCommandContext } from "../command-registry.ts";
+import { Logger } from "../../infrastructure/logger.ts";
+import { InstallSkillsService, SkillsInstallError } from "../../services/skills-service.ts";
+
+export class InstallSkillsCommand implements CliCommand {
+  readonly name = "install-skills";
+  readonly description = "Install GemiTerm opencode skills from expert-vision-software/opencode-gemiterm-skills";
+
+  async execute(_args: string[], _context: CliCommandContext): Promise<void> {
+    const logger = new Logger("install-skills-command");
+    logger.debug("Executing install-skills command");
+    const service = new InstallSkillsService({ logger });
+
+    console.log(chalk.dim("Installing GemiTerm opencode skills..."));
+
+    try {
+      const output = await service.install();
+      if (output) {
+        console.log(output);
+      }
+      console.log(chalk.green("Skills installed successfully."));
+    } catch (error) {
+      if (error instanceof SkillsInstallError) {
+        logger.error(error.message);
+        if (error.cause) {
+          logger.error(`Cause: ${error.cause.message}`);
+        }
+        console.error(chalk.red("Failed to install skills."));
+        process.exit(1);
+      }
+      throw error;
+    }
+  }
+}

package/src/cli/commands/new-command.ts

@@ -8,15 +8,20 @@ import {
   type StartNewChatCommandResult,
 } from "../../core/command-handlers.ts";
 import { runInteractiveLoop, type MessageHandlerResult } from "../utils/interactive-prompt.ts";
+import { checkArgLength } from "../utils/long-arg-guard.ts";
+import { loadPromptFromFile, spillOverToTempFile } from "../utils/prompt-file.ts";
+import { removeFile } from "../../infrastructure/io.ts";
 
 interface NewCommandOptions {
   help: boolean;
   profile: string | null;
+  promptFile: string | null;
 }
 
 const DEFAULT_OPTIONS: NewCommandOptions = {
   help: false,
   profile: null,
+  promptFile: null,
 };
 
 export class NewCommand implements CliCommand {
@@ -37,11 +42,56 @@ export class NewCommand implements CliCommand {
     for (const arg of args) {
       if (arg.startsWith("--") || arg.startsWith("-")) continue;
       if (options.profile && arg === options.profile) continue;
+      if (options.promptFile && arg === options.promptFile) continue;
       if (!message) {
         message = arg;
       }
     }
 
+    if (options.promptFile && message) {
+      console.error(
+        chalk.red(
+          `Error: cannot use --prompt-file together with a positional message argument. ` +
+            `Use one or the other, not both.`,
+        ),
+      );
+      process.exit(1);
+    }
+
+    let effectivePromptFile: string | null = null;
+    let isSpillover = false;
+    if (options.promptFile) {
+      effectivePromptFile = options.promptFile;
+    } else if (message) {
+      const guard = checkArgLength(message);
+      if (!guard.safe) {
+        const spilled = await spillOverToTempFile(message);
+        effectivePromptFile = spilled;
+        isSpillover = true;
+        console.log(
+          chalk.dim(
+            `[gemiterm] Message is ${guard.length} UTF-16 code units, exceeding the ${guard.limit} limit. ` +
+              `Spilled to temp file '${spilled}' and loading from there.`,
+          ),
+        );
+      }
+    }
+
+    if (effectivePromptFile) {
+      try {
+        message = await loadPromptFromFile(effectivePromptFile);
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+      }
+      if (isSpillover) {
+        try {
+          removeFile(effectivePromptFile);
+        } catch {
+        }
+      }
+    }
+
     const mediator: Mediator = context.mediator;
 
     if (message) {
@@ -121,6 +171,15 @@ export class NewCommand implements CliCommand {
           console.error(chalk.red(`Error: --profile requires a profile name`));
           process.exit(1);
         }
+      } else if (arg === "--prompt-file" || arg === "-f") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          options.promptFile = next;
+          i++;
+        } else {
+          console.error(chalk.red(`Error: --prompt-file requires a path`));
+          process.exit(1);
+        }
       }
     }
 
@@ -139,6 +198,9 @@ export class NewCommand implements CliCommand {
     console.log(
       `  ${chalk.cyan("--profile, -p <name>".padEnd(22))}${chalk.dim("Use a specific profile (default profile used if omitted)")}`,
     );
+    console.log(
+      `  ${chalk.cyan("--prompt-file, -f <path>".padEnd(22))}${chalk.dim("Read the message from a file (bypasses the 2048 code unit arg limit)")}`,
+    );
     console.log(`  ${chalk.cyan("--help, -h".padEnd(22))}${chalk.dim("Show this help message")}`);
     console.log("");
     console.log(chalk.dim("If no message is provided, an interactive chat session will start."));

package/src/cli/index.ts

@@ -3,13 +3,13 @@
 import { CommandRegistry } from "./command-registry.ts";
 import { Logger } from "../infrastructure/logger.ts";
 import { Mediator } from "../core/mediator.ts";
-import { showHelp } from "./commands/help.ts";
 import { GeminiClientService } from "../services/gemini-client-wrapper.ts";
 import { CookieStorageService } from "../services/cookie-storage-service.ts";
 import { ProfileAuthManager } from "../services/profile-auth-manager.ts";
 import { CookieStorage, ProfileManager } from "../infrastructure/storage.ts";
-import { getDefaultProfileName, listProfiles, ensureConfigDir } from "../infrastructure/config.ts";
+import { getDefaultProfileName, listProfiles } from "../infrastructure/config.ts";
 import { getPackageJson } from "../infrastructure/path-utils.ts";
+import { parseGlobalArgs, printVersion, printHelp } from "../infrastructure/cli-parser.ts";
 import { AuthenticationError } from "../core/errors.ts";
 import {
   AuthenticateCommandHandler,
@@ -30,39 +30,6 @@ import {
 
 const pkg = getPackageJson(import.meta.url);
 
-interface GlobalFlags {
-  verbose: boolean;
-  version: boolean;
-  help: boolean;
-}
-
-function parseGlobalFlags(args: string[]): { flags: GlobalFlags; remaining: string[] } {
-  const flags: GlobalFlags = {
-    verbose: process.env.GEMITERM_VERBOSE === "true",
-    version: false,
-    help: false,
-  };
-  const remaining: string[] = [];
-
-  for (const arg of args) {
-    if (arg === "--verbose" || arg === "-v") {
-      flags.verbose = true;
-    } else if (arg === "--version") {
-      flags.version = true;
-    } else if (arg === "--help" || arg === "-h") {
-      if (remaining.length === 0) {
-        flags.help = true;
-      } else {
-        remaining.push(arg);
-      }
-    } else {
-      remaining.push(arg);
-    }
-  }
-
-  return { flags, remaining };
-}
-
 async function setupMediator(mediator: Mediator): Promise<ProfileAuthManager> {
   const logger = new Logger("mediator");
   const cookieStorage = new CookieStorage();
@@ -159,31 +126,39 @@ async function setupMediator(mediator: Mediator): Promise<ProfileAuthManager> {
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const logger = new Logger("cli");
-  const { flags, remaining } = parseGlobalFlags(args);
 
-  if (flags.verbose) {
+  let flags: ReturnType<typeof parseGlobalArgs>["flags"];
+  let subcommand: string | null;
+  let subcommandArgs: string[];
+  try {
+    ({ flags, subcommand, subcommandArgs } = parseGlobalArgs(args));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  }
+
+  const verbose = flags.verbose || process.env.GEMITERM_VERBOSE === "true";
+  if (verbose) {
     Logger.setVerbose(true);
   }
 
   if (flags.version) {
-    console.log(`gemiterm v${pkg.version}`);
+    printVersion(pkg.version);
     process.exit(0);
   }
 
   const registry = new CommandRegistry();
   registry.registerAllCommands();
 
-  if (remaining.length === 0) {
-    showHelp(registry);
+  if (!subcommand) {
+    printHelp(registry);
     process.exit(0);
   }
 
   const mediator = new Mediator();
   const profileAuthManager = await setupMediator(mediator);
 
-  const subcommand = remaining[0];
-  const subcommandArgs = remaining.slice(1);
-
   const handler = registry.getHandler(subcommand);
   if (!handler) {
     const known = registry.getRegisteredNames();
@@ -198,7 +173,7 @@ async function main(): Promise<void> {
   }
 
   try {
-    await handler.execute(subcommandArgs, { verbose: flags.verbose, mediator, profileAuthManager });
+    await handler.execute(subcommandArgs, { verbose, mediator, profileAuthManager });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     logger.error(`Command '${subcommand}' failed: ${message}`);

package/src/cli/utils/long-arg-guard.ts

@@ -0,0 +1,28 @@
+export const WINDOWS_COMMAND_LINE_ARG_LIMIT = 2048;
+
+export type LongArgGuardResult =
+  | { safe: true; arg: string }
+  | { safe: false; arg: string; length: number; limit: number; suggestion: string };
+
+export function checkArgLength(arg: string): LongArgGuardResult {
+  const length = utf16CodeUnitLength(arg);
+  if (length <= WINDOWS_COMMAND_LINE_ARG_LIMIT) {
+    return { safe: true, arg };
+  }
+  return {
+    safe: false,
+    arg,
+    length,
+    limit: WINDOWS_COMMAND_LINE_ARG_LIMIT,
+    suggestion:
+      `Argument is ${length} UTF-16 code units, which exceeds the ${WINDOWS_COMMAND_LINE_ARG_LIMIT} ` +
+      `code unit limit imposed by Bun's Windows process spawn path (appendWindowsArgument in ` +
+      `Bun's run_command.zig panics with "index out of bounds" when this limit is exceeded). ` +
+      `Pipe the message via stdin (e.g. \`echo "..." | gemiterm new\`) or save it to a file and ` +
+      `pass it with \`--prompt-file <path>\`.`,
+  };
+}
+
+function utf16CodeUnitLength(s: string): number {
+  return s.length;
+}

package/src/cli/utils/prompt-file.ts

@@ -0,0 +1,26 @@
+import { IOError, readTextFile, writeTextFile } from "../../infrastructure/io.ts";
+import { getTempFilePath } from "../../infrastructure/path-utils.ts";
+
+export async function loadPromptFromFile(filePath: string): Promise<string> {
+  try {
+    return readTextFile(filePath);
+  } catch (err) {
+    if (err instanceof IOError) {
+      throw new Error(`Could not read prompt file '${filePath}': ${err.message}`);
+    }
+    throw err;
+  }
+}
+
+export async function spillOverToTempFile(content: string): Promise<string> {
+  const path = getTempFilePath("gemiterm-arg-spill", ".txt");
+  try {
+    writeTextFile(path, content);
+  } catch (err) {
+    if (err instanceof IOError) {
+      throw new Error(`Could not spill message to temp file: ${err.message}`);
+    }
+    throw err;
+  }
+  return path;
+}