@gitpagedocs/cli 1.1.65 → 1.1.67

package/ai/application/resolve-chat-credentials.ts

@@ -0,0 +1,62 @@
+import { legacyProviderToCatalogId, resolveApiKeyFromEnv } from "@gitpagedocs/tools/ai";
+import type { AiProviderId } from "@gitpagedocs/tools/ports";
+import { PROVIDER_CATALOG } from "@gitpagedocs/tools";
+import { AiConfigFileRepository } from "../infrastructure/ai-config-file";
+
+export interface ResolvedChatCredentials {
+  readonly providerId: AiProviderId;
+  readonly model: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+}
+
+export interface ResolveChatCredentialsInput {
+  readonly cwd: string;
+  /** Overrides the stored/detected provider (e.g. a `--provider` flag). */
+  readonly providerOverride?: string;
+  /** Overrides the stored/detected model (e.g. a `--model` flag). */
+  readonly modelOverride?: string;
+  /** Injectable for tests; defaults to a real config file repository. */
+  readonly configRepo?: Pick<AiConfigFileRepository, "read">;
+  /** Injectable for tests; defaults to process.env. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * Resolves the provider, model and credentials for a chat turn, layering
+ * sources by priority: explicit overrides > stored .gitpagedocsconfig > env
+ * vars declared by the catalog. Returns null when no provider can be
+ * determined and no key/base URL is available, so the caller can guide setup.
+ */
+export async function resolveChatCredentials(
+  input: ResolveChatCredentialsInput,
+): Promise<ResolvedChatCredentials | null> {
+  const env = input.env ?? process.env;
+  const configRepo = input.configRepo ?? new AiConfigFileRepository({ cwd: input.cwd });
+  const stored = await configRepo.read().catch(() => null);
+
+  const providerId = input.providerOverride
+    ? legacyProviderToCatalogId(input.providerOverride)
+    : stored
+      ? legacyProviderToCatalogId(stored.ai.provider)
+      : firstProviderFromEnv(env) ?? "openai";
+
+  const spec = PROVIDER_CATALOG[providerId];
+  const model = input.modelOverride?.trim() || stored?.ai.model?.trim() || spec.defaultModel;
+  const baseUrl = stored?.ai.baseUrl?.trim() || undefined;
+  const apiKey = stored?.ai.apiKey?.trim() || resolveApiKeyFromEnv(providerId, env);
+
+  const keyless = spec.auth === "none";
+  if (!keyless && !apiKey) return null;
+
+  return { providerId, model, apiKey, baseUrl };
+}
+
+function firstProviderFromEnv(
+  env: Readonly<Record<string, string | undefined>>,
+): AiProviderId | undefined {
+  for (const id of Object.keys(PROVIDER_CATALOG) as AiProviderId[]) {
+    if (resolveApiKeyFromEnv(id, env)) return id;
+  }
+  return undefined;
+}

package/ai/core/chat-session.ts

@@ -0,0 +1,44 @@
+import type { AiMessage } from "@gitpagedocs/tools/ports";
+
+/**
+ * @file chat-session.ts
+ * @description Pure conversation state for the interactive terminal chat. Holds
+ * the running message history and an optional system prompt, and builds the
+ * message array sent to a provider. No IO, no streaming, no terminal concerns —
+ * so the conversation logic is unit-testable without a provider or a TTY.
+ */
+export class ChatSession {
+  private readonly history: AiMessage[] = [];
+
+  constructor(private readonly systemPrompt?: string) {}
+
+  /** Records a user turn. */
+  addUser(content: string): void {
+    this.history.push({ role: "user", content });
+  }
+
+  /** Records an assistant turn (the fully streamed reply). */
+  addAssistant(content: string): void {
+    this.history.push({ role: "assistant", content });
+  }
+
+  /** The user/assistant messages to send for the next completion. */
+  buildRequestMessages(): AiMessage[] {
+    return [...this.history];
+  }
+
+  /** The system prompt for the request's dedicated `system` field, if any. */
+  get system(): string | undefined {
+    return this.systemPrompt?.trim() || undefined;
+  }
+
+  /** Number of recorded turns (excluding the system prompt). */
+  get turnCount(): number {
+    return this.history.length;
+  }
+
+  /** Drops the conversation history, keeping the system prompt. */
+  clear(): void {
+    this.history.length = 0;
+  }
+}

package/contracts/doc-versions.mjs

@@ -1,3 +1,3 @@
-export const PACKAGE_VERSION = "1.1.65";
+export const PACKAGE_VERSION = "1.1.67";
 
 export const DOC_VERSIONS = [PACKAGE_VERSION];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitpagedocs/cli",
-  "version": "1.1.65",
+  "version": "1.1.67",
   "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
   "bin": {
     "gitpagedocs": "index.mjs"
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.1",
-    "@gitpagedocs/mcp": "^1.1.65",
-    "@gitpagedocs/tools": "^1.1.65",
+    "@gitpagedocs/mcp": "^1.1.67",
+    "@gitpagedocs/tools": "^1.1.67",
     "tsx": "^4.21.0"
   },
   "repository": {

package/presentation/commands/chat.ts

@@ -0,0 +1,259 @@
+import readline from "node:readline";
+import { createDefaultFactory } from "@gitpagedocs/tools/ai";
+import { PROVIDER_CATALOG } from "@gitpagedocs/tools";
+import type { AIProvider, ProviderConfig } from "@gitpagedocs/tools/ports";
+import { ChatSession } from "../../ai/core/chat-session";
+import { resolveChatCredentials, type ResolvedChatCredentials } from "../../ai/application/resolve-chat-credentials";
+import {
+  ElapsedSpinner,
+  accent,
+  danger,
+  writeChrome,
+  writeContent,
+} from "../ui/terminal-stream";
+import type { CommandContext } from "./run-command";
+
+/** Positions the model as a documentation assistant for the current project. */
+const DEFAULT_CHAT_SYSTEM_PROMPT = [
+  "You are a concise documentation and coding assistant embedded in the gitpagedocs CLI.",
+  "Answer questions about the user's project, source code and documentation.",
+  "Prefer short, correct, actionable answers; use GitHub-flavored markdown for code.",
+].join(" ");
+
+const EXIT_REARM_MS = 3000;
+
+interface ChatFlags {
+  provider?: string;
+  model?: string;
+  system?: string;
+  question?: string;
+}
+
+function parseChatArgs(args: readonly string[]): ChatFlags {
+  // args[0] is the verb ("chat"); parse flags and collect the free-text question.
+  const flags: ChatFlags = {};
+  const positional: string[] = [];
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--provider" || arg === "--model" || arg === "--system") {
+      const value = args[i + 1];
+      if (value !== undefined) {
+        if (arg === "--provider") flags.provider = value;
+        else if (arg === "--model") flags.model = value;
+        else flags.system = value;
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith("--")) continue;
+    positional.push(arg);
+  }
+  const question = positional.join(" ").trim();
+  if (question) flags.question = question;
+  return flags;
+}
+
+async function readPipedStdin(): Promise<string> {
+  if (process.stdin.isTTY) return "";
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+
+/**
+ * Streams one assistant turn to stdout. Cancellation is a scoped concern: the
+ * caller owns the AbortController and the stream stops the moment it aborts
+ * (the async generator's cleanup tears down the HTTP request). Returns whether
+ * the turn completed (false = aborted or errored).
+ */
+async function streamTurn(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+  userText: string,
+  signal: AbortSignal,
+): Promise<boolean> {
+  session.addUser(userText);
+  const spinner = new ElapsedSpinner("Thinking");
+  spinner.start();
+  let full = "";
+  let started = false;
+  try {
+    for await (const delta of provider.stream(
+      { messages: session.buildRequestMessages(), system: session.system, signal },
+      config,
+    )) {
+      if (!started) {
+        spinner.stop();
+        started = true;
+      }
+      full += delta;
+      writeContent(delta);
+    }
+    if (started) writeContent("\n");
+    session.addAssistant(full);
+    writeChrome(
+      `${PROVIDER_CATALOG[config.providerId].label} · ${config.model} · ${spinner.elapsedSeconds().toFixed(1)}s`,
+    );
+    return true;
+  } catch (error) {
+    spinner.stop();
+    if (signal.aborted || (error instanceof Error && error.name === "AbortError")) {
+      if (started) writeContent("\n");
+      writeChrome(danger("Interrupted."));
+      // Keep the partial reply in history so follow-ups have context.
+      session.addAssistant(full);
+      return false;
+    }
+    writeChrome(danger(`Error: ${error instanceof Error ? error.message : String(error)}`));
+    return false;
+  } finally {
+    spinner.stop();
+  }
+}
+
+/** One-shot mode: a single question in, the answer out, then exit. */
+async function runOneShot(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+  question: string,
+): Promise<void> {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort();
+  process.on("SIGINT", onSigint);
+  try {
+    const ok = await streamTurn(provider, config, session, question, controller.signal);
+    if (!ok) process.exitCode = 1;
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+}
+
+/** Interactive REPL: requires a TTY on both ends. */
+async function runRepl(
+  provider: AIProvider,
+  config: ProviderConfig,
+  session: ChatSession,
+): Promise<void> {
+  const spec = PROVIDER_CATALOG[config.providerId];
+  writeChrome(`Chat — ${spec.label} · ${config.model}`);
+  writeChrome("Commands: /clear reset · /help · /exit (or Ctrl+C twice)");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    prompt: accent("› "),
+  });
+
+  let generating: AbortController | null = null;
+  let exitArmed = false;
+  let exitTimer: ReturnType<typeof setTimeout> | null = null;
+
+  rl.on("SIGINT", () => {
+    if (generating) {
+      generating.abort();
+      return;
+    }
+    if (exitArmed) {
+      rl.close();
+      return;
+    }
+    exitArmed = true;
+    writeChrome("Press Ctrl+C again to exit.");
+    exitTimer = setTimeout(() => {
+      exitArmed = false;
+    }, EXIT_REARM_MS);
+    rl.prompt();
+  });
+
+  rl.prompt();
+  for await (const line of rl) {
+    if (exitTimer) {
+      clearTimeout(exitTimer);
+      exitTimer = null;
+    }
+    exitArmed = false;
+    const input = line.trim();
+    if (!input) {
+      rl.prompt();
+      continue;
+    }
+    if (input === "/exit" || input === "/quit") break;
+    if (input === "/clear") {
+      session.clear();
+      writeChrome("Conversation cleared.");
+      rl.prompt();
+      continue;
+    }
+    if (input === "/help") {
+      writeChrome("Type a message to chat. /clear resets history, /exit quits, Ctrl+C interrupts a reply.");
+      rl.prompt();
+      continue;
+    }
+    generating = new AbortController();
+    await streamTurn(provider, config, session, input, generating.signal);
+    generating = null;
+    rl.prompt();
+  }
+  rl.close();
+  writeChrome("Bye.");
+}
+
+function printSetupHelp(providerHint: string): void {
+  writeChrome(danger("No AI credentials found."));
+  writeChrome(`Set an API key via environment variable (e.g. ${providerHint}) or run: gitpagedocs ai`);
+  writeChrome("Then: gitpagedocs chat \"your question\"  ·  or just: gitpagedocs chat");
+}
+
+/**
+ * `gitpagedocs chat [question]` — interactive AI chat in the terminal.
+ * Flags: --provider <id>, --model <id>, --system <prompt>.
+ * One-shot when a question is given or stdin is piped; a REPL on a TTY.
+ */
+export async function runChat(ctx: CommandContext): Promise<void> {
+  const flags = parseChatArgs(ctx.args);
+  const creds: ResolvedChatCredentials | null = await resolveChatCredentials({
+    cwd: ctx.cwd,
+    providerOverride: flags.provider,
+    modelOverride: flags.model,
+  });
+
+  if (!creds) {
+    const hintProvider = flags.provider ?? "openai";
+    const hint = PROVIDER_CATALOG[
+      (hintProvider in PROVIDER_CATALOG ? hintProvider : "openai") as keyof typeof PROVIDER_CATALOG
+    ].envVars[0] ?? "OPENAI_API_KEY";
+    printSetupHelp(hint);
+    process.exitCode = 1;
+    return;
+  }
+
+  const provider = createDefaultFactory().create(creds.providerId);
+  const config: ProviderConfig = {
+    providerId: creds.providerId,
+    model: creds.model,
+    apiKey: creds.apiKey,
+    baseUrl: creds.baseUrl,
+  };
+  const session = new ChatSession(flags.system ?? DEFAULT_CHAT_SYSTEM_PROMPT);
+
+  const piped = await readPipedStdin();
+  const oneShot = [flags.question, piped].filter(Boolean).join("\n\n").trim();
+
+  if (oneShot) {
+    await runOneShot(provider, config, session, oneShot);
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    writeChrome(danger("No question given and no interactive terminal available."));
+    writeChrome('Usage: gitpagedocs chat "your question"');
+    process.exitCode = 1;
+    return;
+  }
+
+  await runRepl(provider, config, session);
+}

package/presentation/commands/run-command.ts

@@ -23,6 +23,7 @@ import { runMcp } from "./mcp";
 import { runDocs } from "./docs";
 import { runPagesActions, runPagesDeploy } from "./pages";
 import { runPassword } from "./password";
+import { runChat } from "./chat";
 
 const REGISTRY: Record<string, CommandHandler> = {
   version: runVersion,
@@ -37,6 +38,7 @@ const REGISTRY: Record<string, CommandHandler> = {
   mcp: runMcp,
   docs: runDocs,
   password: runPassword,
+  chat: runChat,
 };
 
 /** Returns true if a new command handled the invocation (skip legacy flow). */

package/presentation/index.ts

@@ -45,8 +45,9 @@ const params: CliRuntimeParams = {
 };
 
 async function main(): Promise<void> {
-  // `mcp start` owns stdout (the MCP stdio channel) — no banner/credits there.
-  const stdoutOwnedByCommand = process.argv[2] === "mcp";
+  // Commands that own stdout get no banner/credits: `mcp start` (the MCP stdio
+  // channel) and `chat` (streamed model output must be the only thing on stdout).
+  const stdoutOwnedByCommand = process.argv[2] === "mcp" || process.argv[2] === "chat";
   if (!stdoutOwnedByCommand) printBanner();
 
   // New informational/utility commands (version, doctor, provider, models,

package/presentation/ui/terminal-stream.ts

@@ -0,0 +1,97 @@
+/**
+ * @file terminal-stream.ts
+ * @description Terminal rendering for streamed AI output, non-TTY-first:
+ *   - model text goes to STDOUT (so `chat "q" > out.txt` captures clean content)
+ *   - all chrome (spinner, headers, hints) goes to STDERR
+ *   - colours/spinner are emitted only on a TTY; a pipe gets plain text
+ * Keeps the streaming/rendering side effects in one place, apart from the pure
+ * ChatSession state.
+ */
+const ANSI = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  red: "\x1b[31m",
+} as const;
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+const SPINNER_INTERVAL_MS = 80;
+
+function stdoutIsTty(): boolean {
+  return Boolean(process.stdout.isTTY);
+}
+
+function stderrIsTty(): boolean {
+  return Boolean(process.stderr.isTTY);
+}
+
+/** Writes model content to stdout (verbatim; the actual deliverable). */
+export function writeContent(text: string): void {
+  process.stdout.write(text);
+}
+
+/** Writes one chrome line to stderr, dimmed on a TTY. */
+export function writeChrome(line: string): void {
+  if (stderrIsTty()) {
+    process.stderr.write(`${ANSI.dim}${line}${ANSI.reset}\n`);
+  } else {
+    process.stderr.write(`${line}\n`);
+  }
+}
+
+/** Colour helpers that no-op when stderr is not a TTY. */
+export function accent(text: string): string {
+  return stderrIsTty() ? `${ANSI.cyan}${text}${ANSI.reset}` : text;
+}
+
+export function danger(text: string): string {
+  return stderrIsTty() ? `${ANSI.red}${text}${ANSI.reset}` : text;
+}
+
+/**
+ * A spinner with elapsed-time readout on stderr. On a non-TTY it prints a
+ * single static line instead of animating, so logs stay clean. `stop()` clears
+ * the line and is idempotent.
+ */
+export class ElapsedSpinner {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private frame = 0;
+  private readonly startedAt = Date.now();
+
+  constructor(private readonly label: string) {}
+
+  start(): void {
+    if (!stderrIsTty()) {
+      process.stderr.write(`${this.label}...\n`);
+      return;
+    }
+    this.render();
+    this.timer = setInterval(() => this.render(), SPINNER_INTERVAL_MS);
+  }
+
+  private render(): void {
+    const seconds = ((Date.now() - this.startedAt) / 1000).toFixed(1);
+    const glyph = SPINNER_FRAMES[this.frame % SPINNER_FRAMES.length];
+    this.frame += 1;
+    process.stderr.write(`\r${ANSI.cyan}${glyph}${ANSI.reset} ${ANSI.dim}${this.label} ${seconds}s${ANSI.reset}\x1b[K`);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (stderrIsTty()) {
+      process.stderr.write("\r\x1b[K");
+    }
+  }
+
+  /** Elapsed seconds since construction. */
+  elapsedSeconds(): number {
+    return (Date.now() - this.startedAt) / 1000;
+  }
+}
+
+export const supportsColor = stderrIsTty;
+export const isInteractiveOutput = stdoutIsTty;