gitforest 0.1.0

package/src/components/onboarding/OnboardingWizard.tsx

@@ -0,0 +1,130 @@
+import { useState, useEffect } from "react";
+import { Box, Text } from "ink";
+import type { GitforestConfig } from "../../types/index.ts";
+import { WelcomeStep } from "./WelcomeStep.tsx";
+import { DirectoriesStep } from "./DirectoriesStep.tsx";
+import { GitHubAuthStep } from "./GitHubAuthStep.tsx";
+import { CompleteStep } from "./CompleteStep.tsx";
+
+type Step = "welcome" | "directories" | "github" | "complete";
+
+interface DirectoryConfig {
+  path: string;
+  maxDepth: number;
+  label?: string;
+}
+
+interface GitHubAuthState {
+  authenticated: boolean;
+  user?: string;
+  skipped: boolean;
+}
+
+export interface OnboardingWizardProps {
+  onComplete: (config: GitforestConfig) => void;
+  onCancel: () => void;
+}
+
+export function OnboardingWizard({ onComplete, onCancel }: OnboardingWizardProps) {
+  const [currentStep, setCurrentStep] = useState<Step>("welcome");
+  const [directories, setDirectories] = useState<DirectoryConfig[]>([]);
+  const [githubAuth, setGithubAuth] = useState<GitHubAuthState>({
+    authenticated: false,
+    skipped: false,
+  });
+  const [isCreatingConfig, setIsCreatingConfig] = useState(false);
+  const [configError, setConfigError] = useState<string | null>(null);
+
+  const handleWelcomeComplete = () => {
+    setCurrentStep("directories");
+  };
+
+  const handleDirectoriesComplete = (dirs: DirectoryConfig[]) => {
+    setDirectories(dirs);
+    setCurrentStep("github");
+  };
+
+  const handleGitHubComplete = (auth: GitHubAuthState) => {
+    setGithubAuth(auth);
+    // Immediately create config, then show complete step
+    setIsCreatingConfig(true);
+  };
+
+  // Create config when GitHub step completes
+  useEffect(() => {
+    if (isCreatingConfig && currentStep === "github" && !configError) {
+      void (async () => {
+        try {
+          const { createOnboardingConfig } = await import("../../config/onboarding.ts");
+          const config = await createOnboardingConfig({
+            directories,
+            githubAuth: {
+              authenticated: githubAuth.authenticated,
+              user: githubAuth.user,
+            },
+          });
+          // Config created successfully, show complete step
+          setCurrentStep("complete");
+          setIsCreatingConfig(false);
+          // Auto-complete after showing success
+          setTimeout(() => {
+            onComplete(config);
+          }, 2000);
+        } catch (error) {
+          setConfigError(error instanceof Error ? error.message : "Failed to create config");
+          setIsCreatingConfig(false);
+        }
+      })();
+    }
+  }, [isCreatingConfig, currentStep, directories, githubAuth, onComplete, configError]);
+
+  const handleCancel = () => {
+    onCancel();
+  };
+
+  const handleBack = () => {
+    switch (currentStep) {
+      case "directories":
+        setCurrentStep("welcome");
+        break;
+      case "github":
+        setCurrentStep("directories");
+        break;
+      case "complete":
+        setCurrentStep("github");
+        break;
+    }
+  };
+
+  return (
+    <Box flexDirection="column">
+      {currentStep === "welcome" && (
+        <WelcomeStep onComplete={handleWelcomeComplete} onCancel={handleCancel} />
+      )}
+
+      {currentStep === "directories" && (
+        <DirectoriesStep
+          directories={directories}
+          onComplete={handleDirectoriesComplete}
+          onBack={handleBack}
+          onCancel={handleCancel}
+        />
+      )}
+
+      {currentStep === "github" && (
+        <GitHubAuthStep
+          onComplete={handleGitHubComplete}
+          onBack={handleBack}
+          onCancel={handleCancel}
+        />
+      )}
+
+      {currentStep === "complete" && (
+        <CompleteStep
+          directories={directories}
+          githubAuth={githubAuth}
+        />
+      )}
+    </Box>
+  );
+}

package/src/components/onboarding/WelcomeStep.tsx

@@ -0,0 +1,69 @@
+import { Box, Text, useInput } from "ink";
+
+export interface WelcomeStepProps {
+  onComplete: () => void;
+  onCancel: () => void;
+}
+
+export function WelcomeStep({ onComplete, onCancel }: WelcomeStepProps) {
+  useInput((input, key) => {
+    if (key.return || input === " ") {
+      onComplete();
+      return;
+    }
+
+    if (input === "q" || input === "Q" || key.escape) {
+      onCancel();
+      return;
+    }
+  });
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor="cyan"
+      paddingX={3}
+      paddingY={2}
+      width={70}
+    >
+      {/* Title */}
+      <Box marginBottom={1}>
+        <Text bold color="cyan" underline>
+          Welcome to Gitforest!
+        </Text>
+      </Box>
+
+      <Box marginBottom={1}>
+        <Text>Git Repository Manager for the Terminal</Text>
+      </Box>
+
+      {/* Description */}
+      <Box flexDirection="column" marginBottom={1}>
+        <Text dimColor>
+          This wizard will help you set up Gitforest for the first time.
+        </Text>
+      </Box>
+
+      {/* What we'll configure */}
+      <Box flexDirection="column" marginBottom={1}>
+        <Text>We'll configure:</Text>
+        <Text>  • Project directories to scan for Git repositories</Text>
+        <Text>  • GitHub authentication (optional)</Text>
+      </Box>
+
+      {/* Instructions */}
+      <Box marginTop={1} gap={1}>
+        <Text dimColor>Press </Text>
+        <Text color="green" bold>
+          Enter
+        </Text>
+        <Text dimColor> to continue, </Text>
+        <Text color="red" bold>
+          q
+        </Text>
+        <Text dimColor> to quit</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/config/loader.ts

@@ -0,0 +1,263 @@
+import { existsSync } from "fs";
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import { homedir } from "os";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { GitforestConfigSchema, type GitforestConfig } from "../types/index.ts";
+
+/**
+ * Environment variable prefixes and mappings
+ */
+const ENV_PREFIX = "GITFOREST_";
+
+interface EnvMapping {
+  env: string;
+  path: string[];
+  transform?: (value: string) => unknown;
+}
+
+const ENV_MAPPINGS: EnvMapping[] = [
+  // GitHub settings
+  { env: "GITFOREST_GITHUB_VISIBILITY", path: ["github", "defaultVisibility"], transform: (v) => v },
+
+  // Scan settings
+  { env: "GITFOREST_CONCURRENCY", path: ["scan", "concurrency"], transform: (v) => parseInt(v, 10) },
+  { env: "GITFOREST_INCLUDE_HIDDEN", path: ["scan", "includeHidden"], transform: (v) => v === "true" },
+
+  // Display settings
+  { env: "GITFOREST_SORT_BY", path: ["display", "sortBy"], transform: (v) => v },
+  { env: "GITFOREST_SORT_DIR", path: ["display", "sortDirection"], transform: (v) => v },
+  { env: "GITFOREST_SHOW_SUBMODULES", path: ["display", "showSubmodules"], transform: (v) => v === "true" },
+
+  // Cache settings
+  { env: "GITFOREST_CACHE_TTL", path: ["cache", "ttlSeconds"], transform: (v) => parseInt(v, 10) },
+  { env: "GITFOREST_GITHUB_CACHE_TTL", path: ["cache", "githubTtlSeconds"], transform: (v) => parseInt(v, 10) },
+  { env: "GITFOREST_ENABLE_BACKGROUND_REFRESH", path: ["cache", "enableBackgroundRefresh"], transform: (v) => v === "true" },
+  { env: "GITFOREST_BACKGROUND_REFRESH_INTERVAL", path: ["cache", "backgroundRefreshIntervalSeconds"], transform: (v) => parseInt(v, 10) },
+];
+
+/**
+ * Set a nested value in an object using a path array
+ */
+function setNestedValue(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  let current = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i]!;
+    if (!(key in current) || typeof current[key] !== "object" || current[key] === null) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+  const lastKey = path[path.length - 1]!;
+  current[lastKey] = value;
+}
+
+/**
+ * Apply environment variable overrides to config
+ * Environment variables take precedence over file-based config
+ */
+export function applyEnvOverrides(config: GitforestConfig): GitforestConfig {
+  const result = JSON.parse(JSON.stringify(config)) as GitforestConfig;
+
+  for (const mapping of ENV_MAPPINGS) {
+    const envValue = process.env[mapping.env];
+    if (envValue !== undefined && envValue !== "") {
+      const transformedValue = mapping.transform ? mapping.transform(envValue) : envValue;
+      setNestedValue(result as unknown as Record<string, unknown>, mapping.path, transformedValue);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get list of supported environment variables
+ */
+export function getSupportedEnvVars(): { env: string; path: string; description: string }[] {
+  return ENV_MAPPINGS.map((m) => ({
+    env: m.env,
+    path: m.path.join("."),
+    description: `Override ${m.path.join(".")} config value`,
+  }));
+}
+
+/**
+ * Get possible config file locations in order of priority
+ */
+function getConfigPaths(cwd?: string): string[] {
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  const home = homedir();
+  const workingDir = cwd ?? process.cwd();
+
+  return [
+    // Current directory
+    join(workingDir, "gitforest.config.yaml"),
+    join(workingDir, "gitforest.config.yml"),
+    join(workingDir, "gitforest.config.json"),
+    join(workingDir, ".gitforest.yaml"),
+    join(workingDir, ".gitforest.yml"),
+    join(workingDir, ".gitforest.json"),
+    // XDG config directory
+    join(xdg, "gitforest", "config.yaml"),
+    join(xdg, "gitforest", "config.yml"),
+    join(xdg, "gitforest", "config.json"),
+    // Home directory
+    join(home, ".gitforest.yaml"),
+    join(home, ".gitforest.yml"),
+    join(home, ".gitforest.json"),
+  ];
+}
+
+/**
+ * Find the first existing config file
+ */
+export function findConfigPath(cwd?: string): string | null {
+  for (const path of getConfigPaths(cwd)) {
+    if (existsSync(path)) {
+      return path;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load and validate configuration from file
+ */
+export async function loadConfig(configPath?: string, cwd?: string): Promise<GitforestConfig> {
+  const path = configPath ?? findConfigPath(cwd);
+
+  if (!path) {
+    const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    throw new Error(
+      `No config file found. Create one at:\n` +
+      `  - ${join(xdg, "gitforest", "config.yaml")}\n\n` +
+      `Example:\n` +
+      `directories:\n` +
+      `  - path: ~/projects\n` +
+      `    maxDepth: 2\n` +
+      `  - path: ~/.dotfiles\n` +
+      `    maxDepth: 3\n`
+    );
+  }
+
+  const file = Bun.file(path);
+  const content = await file.text();
+
+  let parsed: unknown;
+
+  if (path.endsWith(".yaml") || path.endsWith(".yml")) {
+    parsed = parseYaml(content);
+  } else if (path.endsWith(".json")) {
+    parsed = JSON.parse(content);
+  } else {
+    throw new Error(`Unknown config file format: ${path}`);
+  }
+
+  const result = GitforestConfigSchema.safeParse(parsed);
+
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`)
+      .join("\n");
+    throw new Error(`Invalid config file at ${path}:\n${issues}`);
+  }
+
+  // Expand ~ in directory paths
+  let config = result.data;
+  config.directories = config.directories.map((dir) => ({
+    ...dir,
+    path: dir.path.replace(/^~/, homedir()),
+  }));
+
+  // Apply environment variable overrides
+  config = applyEnvOverrides(config);
+
+  return config;
+}
+
+/**
+ * Get the default config path for creating a new config
+ */
+export function getDefaultConfigPath(): string {
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+  return join(xdg, "gitforest", "config.yaml");
+}
+
+/**
+ * Create a default config file
+ */
+export async function createDefaultConfig(): Promise<string> {
+  const configPath = getDefaultConfigPath();
+  const configDir = join(configPath, "..");
+
+  // Ensure directory exists
+  await mkdir(configDir, { recursive: true });
+
+  const defaultConfig = `# Gitforest Configuration
+# Directories to scan for projects
+directories:
+  - path: ~/projects
+    maxDepth: 2
+    label: Projects
+
+# Optional: Add more directories
+# - path: ~/.dotfiles
+#   maxDepth: 3
+#   label: Dotfiles
+
+# Scan settings
+scan:
+  ignore:
+    - node_modules
+    - .git
+    - vendor
+    - __pycache__
+    - target
+    - dist
+    - build
+  includeHidden: false
+  concurrency: 5
+
+# GitHub settings
+github:
+  defaultVisibility: private
+
+# Display settings
+display:
+  showSubmodules: true
+  sortBy: status  # name | status | lastActivity
+  sortDirection: desc
+
+# Cache settings
+cache:
+  ttlSeconds: 300  # 5 minutes for local projects
+  githubTtlSeconds: 600  # 10 minutes for GitHub repos
+  enableBackgroundRefresh: true  # Refresh data in background
+  backgroundRefreshIntervalSeconds: 300  # 5 minutes
+`;
+
+  await Bun.write(configPath, defaultConfig);
+  return configPath;
+}
+
+/**
+ * Save configuration to file
+ */
+export async function saveConfig(config: GitforestConfig, path?: string): Promise<void> {
+  const configPath = path ?? findConfigPath() ?? getDefaultConfigPath();
+
+  // Create backup of existing config if it exists
+  if (existsSync(configPath)) {
+    const backupPath = `${configPath}.bak`;
+    await Bun.write(backupPath, await Bun.file(configPath).text());
+  }
+
+  let content: string;
+  if (configPath.endsWith(".json")) {
+    content = JSON.stringify(config, null, 2);
+  } else {
+    content = stringifyYaml(config);
+  }
+
+  await Bun.write(configPath, content);
+}

package/src/config/onboarding.ts

@@ -0,0 +1,67 @@
+import { mkdir } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import type { GitforestConfig } from "../types/index.ts";
+import { saveConfig, getDefaultConfigPath } from "./loader.ts";
+
+export interface CreateOnboardingConfigOptions {
+  directories: Array<{ path: string; maxDepth: number; label?: string }>;
+  githubAuth?: {
+    authenticated: boolean;
+    user?: string;
+  };
+}
+
+/**
+ * Create a config file from onboarding wizard state
+ */
+export async function createOnboardingConfig(
+  options: CreateOnboardingConfigOptions
+): Promise<GitforestConfig> {
+  const { directories, githubAuth } = options;
+
+  // Validate at least one directory
+  if (directories.length === 0) {
+    throw new Error("At least one directory is required");
+  }
+
+  // Create config object with defaults
+  const config: GitforestConfig = {
+    directories: directories.map((dir) => ({
+      path: dir.path,
+      maxDepth: dir.maxDepth,
+      label: dir.label,
+    })),
+    scan: {
+      ignore: ["node_modules", ".git", "vendor", "__pycache__", "target", "dist", "build"],
+      includeHidden: false,
+      concurrency: 5,
+    },
+    github: {
+      defaultVisibility: "private",
+    },
+    display: {
+      showSubmodules: true,
+      showNonGitProjects: true,
+      sortBy: "status",
+      sortDirection: "desc",
+    },
+    cache: {
+      ttlSeconds: 300,
+      githubTtlSeconds: 600,
+      enableBackgroundRefresh: true,
+      backgroundRefreshIntervalSeconds: 300,
+    },
+    commands: [],
+  };
+
+  // Ensure config directory exists
+  const configPath = getDefaultConfigPath();
+  const configDir = join(configPath, "..");
+  await mkdir(configDir, { recursive: true });
+
+  // Save config
+  await saveConfig(config, configPath);
+
+  return config;
+}

package/src/constants.ts

@@ -0,0 +1,96 @@
+/**
+ * Application constants
+ * Centralized configuration values to avoid magic numbers
+ */
+
+// ============================================================================
+// UI Constants
+// ============================================================================
+
+export const UI = {
+  /** Height reserved for header, filter bar, status bar, and padding */
+  LAYOUT_OVERHEAD: 6,
+  /** Minimum terminal height for proper display */
+  MIN_TERMINAL_HEIGHT: 24,
+  /** Default terminal height if detection fails */
+  DEFAULT_TERMINAL_HEIGHT: 24,
+} as const;
+
+// ============================================================================
+// Scanner Constants
+// ============================================================================
+
+export const SCANNER = {
+  /** Default maximum directory depth for scanning */
+  DEFAULT_MAX_DEPTH: 2,
+  /** Default concurrency for scanning operations */
+  DEFAULT_CONCURRENCY: 5,
+  /** Length of generated project IDs (MD5 hash truncation) */
+  PROJECT_ID_LENGTH: 12,
+  /** Default cache TTL in seconds */
+  DEFAULT_CACHE_TTL_SECONDS: 300,
+} as const;
+
+// ============================================================================
+// Git Constants
+// ============================================================================
+
+export const GIT = {
+  /** Default remote name */
+  DEFAULT_REMOTE: "origin",
+  /** Default branch name */
+  DEFAULT_BRANCH: "main",
+  /** Default concurrency for git operations */
+  DEFAULT_CONCURRENCY: 5,
+  /** Higher concurrency for status refresh (read-only) */
+  STATUS_REFRESH_CONCURRENCY: 10,
+} as const;
+
+export const GIT_TIMEOUTS = {
+  CLONE: 120000,    // 2 minutes for clone
+  PULL: 60000,      // 1 minute for pull
+  PUSH: 60000,      // 1 minute for push
+  FETCH: 60000,     // 1 minute for fetch
+  STATUS: 10000,    // 10 seconds for status
+} as const;
+
+// ============================================================================
+// GitHub API Constants
+// ============================================================================
+
+export const GITHUB_API = {
+  /** Base URL for GitHub API */
+  BASE_URL: "https://api.github.com",
+  /** API version header */
+  API_VERSION: "2022-11-28",
+  /** Default page size for pagination */
+  PAGE_SIZE: 100,
+  /** Maximum retry attempts */
+  MAX_RETRIES: 3,
+  /** Initial retry delay in milliseconds */
+  INITIAL_RETRY_DELAY: 1000,
+  /** Maximum retry delay in milliseconds */
+  MAX_RETRY_DELAY: 30000,
+  /** Backoff multiplier for retries */
+  RETRY_BACKOFF_FACTOR: 2,
+} as const;
+
+// ============================================================================
+// Background Fetch Constants
+// ============================================================================
+
+export const BACKGROUND_FETCH = {
+  /** Interval between background fetches in milliseconds (5 minutes) */
+  INTERVAL_MS: 5 * 60 * 1000,
+} as const;
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type UIConstants = typeof UI;
+export type ScannerConstants = typeof SCANNER;
+export type GitConstants = typeof GIT;
+export type GitTimeouts = typeof GIT_TIMEOUTS;
+export type GitHubAPIConstants = typeof GITHUB_API;
+export type BackgroundFetchConstants = typeof BACKGROUND_FETCH;