@gitpagedocs/cli 0.0.1

package/index.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptPath = fileURLToPath(import.meta.url);
+const scriptDir = path.dirname(scriptPath);
+const tsEntry = path.join(scriptDir, "presentation", "index.ts");
+
+// Resolve tsx from THIS package's location, not the user's cwd. `node --import
+// tsx` would otherwise resolve the bare "tsx" specifier relative to the current
+// working directory, which fails when the CLI is installed globally and run
+// from a project that doesn't depend on tsx (ERR_MODULE_NOT_FOUND 'tsx').
+let tsxLoader = "tsx";
+try {
+  tsxLoader = import.meta.resolve("tsx");
+} catch {
+  // Older Node without a stable import.meta.resolve — fall back to the bare
+  // specifier (works when tsx is resolvable from the cwd or globally).
+}
+
+const result = spawnSync(
+  process.execPath,
+  ["--import", tsxLoader, tsEntry, ...process.argv.slice(2)],
+  {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    env: process.env,
+  },
+);
+
+if (result.error) {
+  console.error("[gitpagedocs] Failed to run TypeScript CLI runtime.", result.error);
+  process.exitCode = 1;
+} else if (typeof result.status === "number" && result.status !== 0) {
+  process.exitCode = result.status;
+}

package/infrastructure/config-only/runtime.mjs

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+import { getCurrentGitBranch, runGitPushForGeneratedArtifacts } from "../../runtime/git-ops.mjs";
+import { writeConfigOnlyOutput, writeText } from "../../runtime/output.mjs";
+import { ensureGitHubPagesWorkflow } from "../../runtime/workflow.mjs";
+import { logInfo } from "../../ui/logger.mjs";
+
+export function createConfigOnlyRuntime() {
+  return {
+    hasPath: existsSync,
+    writeConfigOnlyOutput,
+    writeText,
+    ensureGitHubPagesWorkflow,
+    getCurrentGitBranch,
+    runGitPushForGeneratedArtifacts,
+    logInfo,
+  };
+}

package/infrastructure/gitpagedocs-config-file.ts

@@ -0,0 +1,47 @@
+import fs from "node:fs/promises";
+import { defaultConfigLoader } from "@gitpagedocs/tools";
+
+export interface DocsAccessConfig {
+  enabled: boolean;
+  publicKey: string;
+}
+
+/**
+ * Reads and patches the generated gitpagedocs/config.json IN PLACE, preserving
+ * every existing key (raw-JSON round-trip — it never reserializes through a typed
+ * model that could drop unknown fields). Used by interactive commands that need
+ * to persist a single value (e.g. the documentation password public key).
+ */
+export class GitPageDocsConfigRepository {
+  constructor(private readonly cwd: string = process.cwd()) {}
+
+  /** Absolute path to the JSON config, or throws a friendly, actionable error. */
+  async resolvePath(): Promise<string> {
+    const resolved = await defaultConfigLoader.resolveConfigPath(this.cwd);
+    if (!resolved) {
+      throw new Error("gitpagedocs config.json not found. Run `gitpagedocs` first to generate it.");
+    }
+    if (!resolved.endsWith(".json")) {
+      throw new Error(`Expected a JSON config to patch, found "${resolved}". Use a gitpagedocs/config.json.`);
+    }
+    return resolved;
+  }
+
+  /**
+   * Set `site.docsAccess = { enabled, publicKey }`, leaving all other config keys
+   * untouched. Returns the path that was written.
+   */
+  async patchDocsAccess(publicKey: string, enabled = true): Promise<string> {
+    const configPath = await this.resolvePath();
+    const raw = await fs.readFile(configPath, "utf-8");
+    const config = JSON.parse(raw) as Record<string, unknown>;
+    const site =
+      config.site && typeof config.site === "object"
+        ? (config.site as Record<string, unknown>)
+        : {};
+    site.docsAccess = { enabled, publicKey } satisfies DocsAccessConfig;
+    config.site = site;
+    await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    return configPath;
+  }
+}

package/infrastructure/home/runtime.mjs

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { cpSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { runExecutable } from "../../runtime/exec.mjs";
+import { writeConfigOnlyOutput, writeText } from "../../runtime/output.mjs";
+import { writeHomeFiles } from "../../home/home-file-writer.mjs";
+import { logInfo, logSuccess } from "../../ui/logger.mjs";
+
+function ensureDirEmpty(root, relativeDir) {
+  const target = path.join(root, relativeDir);
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true });
+  }
+}
+
+function copyRecursive(src, dest) {
+  cpSync(src, dest, { recursive: true, force: true });
+}
+
+function runNextBuild(root, env) {
+  runExecutable("npx", ["next", "build", "frontend"], { cwd: root, env, stdio: "inherit" });
+}
+
+export function createHomeRuntime() {
+  return {
+    joinPath: (...parts) => path.join(...parts),
+    ensureDirEmpty,
+    copyRecursive,
+    readDirNames: (absolutePath) => readdirSync(absolutePath),
+    existsPath: existsSync,
+    runNextBuild,
+    writeConfigOnlyOutput,
+    writeHomeFiles,
+    writeText,
+    logSuccess,
+    logInfo,
+  };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@gitpagedocs/cli",
+  "version": "0.0.1",
+  "description": "CLI that scaffolds and maintains gitpagedocs documentation, generates docs with AI, configures GitHub Pages, and runs the MCP server.",
+  "bin": {
+    "gitpagedocs": "index.mjs"
+  },
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "start.mjs",
+    "ai",
+    "application",
+    "builders",
+    "content",
+    "contracts",
+    "data",
+    "domain",
+    "home",
+    "infrastructure",
+    "presentation",
+    "runtime",
+    "ui",
+    "prebuilt",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "@gitpagedocs/mcp": "^0.0.1",
+    "@gitpagedocs/tools": "^0.0.1",
+    "tsx": "^4.21.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vidigal-code/git-page-docs.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "gitpagedocs",
+    "documentation",
+    "markdown",
+    "spa",
+    "cli",
+    "github-pages",
+    "create-gitpagedocs"
+  ],
+  "author": "Vidigal-code",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/Vidigal-code/git-page-docs/issues"
+  },
+  "homepage": "https://vidigal-code.github.io/git-page-docs/",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/presentation/commands/ai-info.ts

@@ -0,0 +1,57 @@
+import { PROVIDER_CATALOG, ALL_PROVIDER_IDS, createModelRegistry, type AiProviderId } from "@gitpagedocs/tools";
+import type { CommandContext } from "./run-command";
+
+function capsLabel(caps: { streaming: boolean; vision: boolean; audio: boolean }): string {
+  const parts: string[] = [];
+  if (caps.streaming) parts.push("stream");
+  if (caps.vision) parts.push("vision");
+  if (caps.audio) parts.push("audio");
+  return parts.join(", ") || "text";
+}
+
+/** `gitpagedocs provider [id]` — list providers or show one provider's detail. */
+export async function runProvider(ctx: CommandContext): Promise<void> {
+  const requested = ctx.args[1] as AiProviderId | undefined;
+  if (requested && PROVIDER_CATALOG[requested]) {
+    const spec = PROVIDER_CATALOG[requested];
+    // eslint-disable-next-line no-console
+    console.log(
+      `\n  ${spec.label} (${spec.id})\n` +
+        `    default model : ${spec.defaultModel}\n` +
+        `    capabilities  : ${capsLabel(spec.capabilities)}\n` +
+        `    base url      : ${spec.baseUrl || "(user-provided)"}\n` +
+        `    models        : ${spec.models.map((m) => m.id).join(", ")}\n`,
+    );
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`\n  AI providers (${ALL_PROVIDER_IDS.length}):\n`);
+  for (const id of ALL_PROVIDER_IDS) {
+    const spec = PROVIDER_CATALOG[id];
+    // eslint-disable-next-line no-console
+    console.log(`  ${id.padEnd(14)} ${spec.label.padEnd(18)} ${spec.defaultModel}`);
+  }
+  // eslint-disable-next-line no-console
+  console.log("\n  Detail: gitpagedocs provider <id>\n");
+}
+
+/** `gitpagedocs models [provider]` — list models for one or all providers. */
+export async function runModels(ctx: CommandContext): Promise<void> {
+  const models = createModelRegistry();
+  const requested = ctx.args[1] as AiProviderId | undefined;
+  const ids = requested && PROVIDER_CATALOG[requested] ? [requested] : ALL_PROVIDER_IDS;
+  // eslint-disable-next-line no-console
+  console.log("");
+  for (const id of ids) {
+    const list = models.list(id);
+    // eslint-disable-next-line no-console
+    console.log(`  ${PROVIDER_CATALOG[id].label} (${id}):`);
+    for (const m of list) {
+      // eslint-disable-next-line no-console
+      console.log(`    - ${m.id}${m.id === PROVIDER_CATALOG[id].defaultModel ? "  (default)" : ""}`);
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log("");
+}

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/config-clear.ts

@@ -0,0 +1,23 @@
+import { AiConfigFileRepository } from "../../ai/infrastructure/ai-config-file";
+import type { CommandContext } from "./run-command";
+
+/**
+ * `gitpagedocs config clear` — delete the stored `.gitpagedocsconfig` from the
+ * per-user config directory and any legacy repo-root copy, wiping the saved AI
+ * credentials (API key, provider, scan paths).
+ */
+export async function runConfigClear(ctx: CommandContext): Promise<void> {
+  const repository = new AiConfigFileRepository({ cwd: ctx.cwd });
+  const removed = await repository.clear();
+
+  if (!removed.length) {
+    // eslint-disable-next-line no-console
+    console.log("\n  No stored .gitpagedocsconfig found - nothing to clear.\n");
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(
+    ["", "  Stored AI configuration removed (credentials wiped):", ...removed.map((p) => `    - ${p}`), ""].join("\n"),
+  );
+}

package/presentation/commands/config-info.ts

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import {
+  DEFAULT_LANGS_MANIFEST_PATH,
+  defaultConfigLoader,
+  getEnabledLanguages,
+  isAppError,
+  parseLanguageManifest,
+  parseLanguageToggles,
+} from "@gitpagedocs/tools";
+import type { CommandContext } from "./run-command";
+
+const UNKNOWN = "—";
+
+interface LanguageSummary {
+  enabled: string[];
+  disabled: string[];
+}
+
+/** The 1.1.68 manifest, read only for sites whose config.json predates `site.languages`. */
+async function readLegacyManifestLanguages(cwd: string): Promise<string[]> {
+  try {
+    const manifest = parseLanguageManifest(JSON.parse(await readFile(path.join(cwd, DEFAULT_LANGS_MANIFEST_PATH), "utf-8")));
+    if (manifest) return manifest.languages;
+  } catch {
+    // No manifest: nothing to report.
+  }
+  return [];
+}
+
+/** `site.languages` toggles from config.json, else the legacy inline list, else the legacy manifest. */
+async function summarizeLanguages(cwd: string, site: Record<string, unknown>): Promise<LanguageSummary> {
+  const toggles = parseLanguageToggles(site.languages);
+  if (toggles) {
+    const enabled = getEnabledLanguages(toggles);
+    return { enabled, disabled: Object.keys(toggles).filter((language) => !enabled.includes(language)) };
+  }
+  if (Array.isArray(site.supportedLanguages)) {
+    return { enabled: site.supportedLanguages as string[], disabled: [] };
+  }
+  return { enabled: await readLegacyManifestLanguages(cwd), disabled: [] };
+}
+
+function formatList(languages: string[]): string {
+  return languages.length > 0 ? languages.join(", ") : UNKNOWN;
+}
+
+/** Scalars print as-is; anything else (missing, object) prints as unknown instead of "[object Object]". */
+function formatScalar(value: unknown): string {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : UNKNOWN;
+}
+
+/** `gitpagedocs config` — resolve and summarize the active gitpagedocs config. */
+export async function runConfig(ctx: CommandContext): Promise<void> {
+  try {
+    const { config, sourcePath, extension } = await defaultConfigLoader.loadGitPageDocsConfig(ctx.cwd);
+    const site = (config as { site?: Record<string, unknown> }).site ?? {};
+    const languages = await summarizeLanguages(ctx.cwd, site);
+    // eslint-disable-next-line no-console
+    console.log(
+      `\n  Config: ${path.relative(ctx.cwd, sourcePath)} (${extension})\n` +
+        `    site name        : ${formatScalar(site.name)}\n` +
+        `    default language : ${formatScalar(site.defaultLanguage)}\n` +
+        `    languages        : ${formatList(languages.enabled)}\n` +
+        `    disabled         : ${formatList(languages.disabled)}\n`,
+    );
+  } catch (error) {
+    const message = isAppError(error) ? error.message : String(error);
+    // eslint-disable-next-line no-console
+    console.log(`\n  No usable config found: ${message}\n  Run \`gitpagedocs init\` to generate one.\n`);
+  }
+}