@muhammedaksam/easiarr 0.4.3 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammedaksam/easiarr",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "TUI tool for generating docker-compose files for the *arr media ecosystem with 41 apps, TRaSH Guides best practices, VPN routing, and Traefik reverse proxy support",
   "module": "src/index.ts",
   "type": "module",

package/src/api/arr-api.ts

@@ -254,6 +254,40 @@ export class ArrApiClient {
   async deleteRemotePathMapping(id: number): Promise<void> {
     await this.request(`/remotepathmapping/${id}`, { method: "DELETE" })
   }
+
+  // ==========================================
+  // Health Check & Status Methods
+  // ==========================================
+
+  // Get health issues/warnings
+  async getHealth(): Promise<HealthResource[]> {
+    return this.request<HealthResource[]>("/health")
+  }
+
+  // Get disk space information for all monitored paths
+  async getDiskSpace(): Promise<DiskSpaceResource[]> {
+    return this.request<DiskSpaceResource[]>("/diskspace")
+  }
+
+  // Get system status (version, OS, runtime, etc.)
+  async getSystemStatus(): Promise<SystemResource> {
+    return this.request<SystemResource>("/system/status")
+  }
+
+  // Get all items in the download queue
+  async getQueueDetails(includeUnknown = true): Promise<QueueResource[]> {
+    const params = new URLSearchParams()
+    if (includeUnknown) {
+      params.set("includeUnknownMovieItems", "true")
+    }
+    const query = params.toString()
+    return this.request<QueueResource[]>(`/queue/details${query ? `?${query}` : ""}`)
+  }
+
+  // Get queue status summary (counts, errors, warnings)
+  async getQueueStatus(): Promise<QueueStatusResource> {
+    return this.request<QueueStatusResource>("/queue/status")
+  }
 }
 
 // Types for Host Config API
@@ -297,3 +331,125 @@ export interface HostConfig {
   backupRetention: number
   trustCgnatIpAddresses: boolean
 }
+
+// ==========================================
+// Health Check & Status Types
+// ==========================================
+
+// Health check result types
+export type HealthCheckType = "ok" | "notice" | "warning" | "error"
+
+export interface HealthResource {
+  id?: number
+  source: string | null
+  type: HealthCheckType
+  message: string | null
+  wikiUrl: string | null
+}
+
+// Disk space types
+export interface DiskSpaceResource {
+  id?: number
+  path: string | null
+  label: string | null
+  freeSpace: number // int64
+  totalSpace: number // int64
+}
+
+// System status types
+export type RuntimeMode = "console" | "service" | "tray"
+export type DatabaseType = "sqLite" | "postgreSQL"
+
+export interface SystemResource {
+  appName: string | null
+  instanceName: string | null
+  version: string | null
+  buildTime: string | null
+  isDebug: boolean
+  isProduction: boolean
+  isAdmin: boolean
+  isUserInteractive: boolean
+  startupPath: string | null
+  appData: string | null
+  osName: string | null
+  osVersion: string | null
+  isNetCore: boolean
+  isLinux: boolean
+  isOsx: boolean
+  isWindows: boolean
+  isDocker: boolean
+  mode: RuntimeMode
+  branch: string | null
+  databaseType: DatabaseType
+  databaseVersion: string | null
+  authentication: "none" | "basic" | "forms" | "external"
+  migrationVersion: number
+  urlBase: string | null
+  runtimeVersion: string | null
+  runtimeName: string | null
+  startTime: string | null
+}
+
+// Queue types
+export type QueueStatus =
+  | "unknown"
+  | "queued"
+  | "paused"
+  | "downloading"
+  | "completed"
+  | "failed"
+  | "warning"
+  | "delay"
+  | "downloadClientUnavailable"
+  | "fallback"
+
+export type TrackedDownloadStatus = "ok" | "warning" | "error"
+export type TrackedDownloadState =
+  | "downloading"
+  | "importBlocked"
+  | "importPending"
+  | "importing"
+  | "imported"
+  | "failedPending"
+  | "failed"
+  | "ignored"
+
+export interface QueueStatusMessage {
+  title: string | null
+  messages: string[] | null
+}
+
+export interface QueueResource {
+  id?: number
+  movieId?: number | null // Radarr
+  seriesId?: number | null // Sonarr
+  artistId?: number | null // Lidarr
+  authorId?: number | null // Readarr
+  title: string | null
+  size: number
+  sizeleft?: number
+  timeleft?: string | null
+  estimatedCompletionTime: string | null
+  added: string | null
+  status: QueueStatus
+  trackedDownloadStatus: TrackedDownloadStatus
+  trackedDownloadState: TrackedDownloadState
+  statusMessages?: QueueStatusMessage[] | null
+  errorMessage: string | null
+  downloadId: string | null
+  protocol: "unknown" | "usenet" | "torrent"
+  downloadClient: string | null
+  indexer: string | null
+  outputPath: string | null
+}
+
+export interface QueueStatusResource {
+  id?: number
+  totalCount: number
+  count: number
+  unknownCount: number
+  errors: boolean
+  warnings: boolean
+  unknownErrors: boolean
+  unknownWarnings: boolean
+}

package/src/api/portainer-api.ts

@@ -0,0 +1,231 @@
+/**
+ * Portainer API Client
+ * Handles Portainer-specific API calls for initialization and management
+ */
+
+import { debugLog } from "../utils/debug"
+import { ensureMinPasswordLength } from "../utils/password"
+
+// Portainer requires minimum 12 character password
+export const PORTAINER_MIN_PASSWORD_LENGTH = 12
+
+export interface PortainerUser {
+  Id?: number
+  Username: string
+  Password?: string
+  Role?: number
+}
+
+// Result from admin initialization - includes actual password used
+export interface PortainerInitResult {
+  user: PortainerUser
+  /** The actual password used (may be padded if global was < 12 chars) */
+  actualPassword: string
+  /** True if password was modified (padded) from the original */
+  passwordWasPadded: boolean
+}
+
+export interface PortainerStatus {
+  Version: string
+  InstanceID: string
+}
+
+export interface PortainerSettings {
+  AuthenticationMethod: number
+  LogoURL: string
+  BlackListedLabels: string[]
+  InternalAuthSettings: {
+    RequiredPasswordLength: number
+  }
+}
+
+// Auth response from login
+export interface PortainerAuthResponse {
+  jwt: string
+}
+
+// API Key creation response
+export interface PortainerApiKeyResponse {
+  rawAPIKey: string
+  apiKey: {
+    id: number
+    userId: number
+    description: string
+    prefix: string
+    dateCreated: number
+    lastUsed: number
+    digest: string
+  }
+}
+
+/**
+ * Portainer API Client
+ */
+export class PortainerApiClient {
+  private baseUrl: string
+  private jwtToken: string | null = null
+
+  constructor(host: string, port: number) {
+    this.baseUrl = `http://${host}:${port}`
+  }
+
+  private async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const url = `${this.baseUrl}/api${endpoint}`
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...(options.headers as Record<string, string>),
+    }
+
+    // Add JWT token if authenticated
+    if (this.jwtToken) {
+      headers["Authorization"] = `Bearer ${this.jwtToken}`
+    }
+
+    debugLog("PortainerAPI", `${options.method || "GET"} ${url}`)
+    if (options.body) {
+      debugLog("PortainerAPI", `Request Body: ${options.body}`)
+    }
+
+    const response = await fetch(url, { ...options, headers })
+    const text = await response.text()
+
+    debugLog("PortainerAPI", `Response ${response.status} from ${endpoint}`)
+    if (text && text.length < 2000) {
+      debugLog("PortainerAPI", `Response Body: ${text}`)
+    }
+
+    if (!response.ok) {
+      throw new Error(`Portainer API request failed: ${response.status} ${response.statusText} - ${text}`)
+    }
+
+    if (!text) return {} as T
+    return JSON.parse(text) as T
+  }
+
+  /**
+   * Check if Portainer needs initial admin user setup.
+   * Returns true if no admin user exists yet.
+   */
+  async needsInitialization(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/users/admin/check`)
+      // 404 means no admin exists yet - needs initialization
+      // 204 means admin already exists
+      return response.status === 404
+    } catch (error) {
+      debugLog("PortainerAPI", `Check admin error: ${error}`)
+      return false
+    }
+  }
+
+  /**
+   * Login to Portainer and store JWT token for subsequent requests.
+   *
+   * @param username - Admin username
+   * @param password - Admin password
+   * @returns JWT token
+   */
+  async login(username: string, password: string): Promise<string> {
+    const safePassword = ensureMinPasswordLength(password, PORTAINER_MIN_PASSWORD_LENGTH)
+
+    const response = await this.request<PortainerAuthResponse>("/auth", {
+      method: "POST",
+      body: JSON.stringify({
+        username,
+        password: safePassword,
+      }),
+    })
+
+    this.jwtToken = response.jwt
+    return response.jwt
+  }
+
+  /**
+   * Initialize the admin user for a fresh Portainer installation.
+   * Password will be automatically padded if shorter than 12 characters.
+   * Automatically logs in after initialization.
+   *
+   * @param username - Admin username
+   * @param password - Admin password (will be padded if needed)
+   * @returns Init result with user, actual password, and padding flag - or null if already initialized
+   */
+  async initializeAdmin(username: string, password: string): Promise<PortainerInitResult | null> {
+    // Check if initialization is needed
+    const needsInit = await this.needsInitialization()
+    if (!needsInit) {
+      debugLog("PortainerAPI", "Admin already initialized, skipping")
+      return null
+    }
+
+    // Ensure password meets Portainer's minimum length requirement
+    const safePassword = ensureMinPasswordLength(password, PORTAINER_MIN_PASSWORD_LENGTH)
+    const wasPadded = safePassword !== password
+
+    if (wasPadded) {
+      debugLog("PortainerAPI", `Password padded from ${password.length} to ${safePassword.length} characters`)
+    }
+
+    const user = await this.request<PortainerUser>("/users/admin/init", {
+      method: "POST",
+      body: JSON.stringify({
+        Username: username,
+        Password: safePassword,
+      }),
+    })
+
+    // Auto-login after initialization
+    await this.login(username, safePassword)
+
+    return {
+      user,
+      actualPassword: safePassword,
+      passwordWasPadded: wasPadded,
+    }
+  }
+
+  /**
+   * Generate a permanent API key for the authenticated user.
+   * Must be logged in first (call login() or initializeAdmin()).
+   *
+   * @param userId - User ID (default: 1 for admin)
+   * @param description - Description for the API key
+   * @param password - User password for confirmation
+   * @returns Raw API key to save to .env as API_KEY_PORTAINER
+   */
+  async generateApiKey(password: string, description: string = "easiarr-api-key", userId: number = 1): Promise<string> {
+    if (!this.jwtToken) {
+      throw new Error("Must be logged in to generate API key. Call login() first.")
+    }
+
+    const safePassword = ensureMinPasswordLength(password, PORTAINER_MIN_PASSWORD_LENGTH)
+
+    const response = await this.request<PortainerApiKeyResponse>(`/users/${userId}/tokens`, {
+      method: "POST",
+      body: JSON.stringify({
+        password: safePassword,
+        description,
+      }),
+    })
+
+    return response.rawAPIKey
+  }
+
+  /**
+   * Get Portainer system status
+   */
+  async getStatus(): Promise<PortainerStatus> {
+    return this.request<PortainerStatus>("/status")
+  }
+
+  /**
+   * Check if Portainer is reachable
+   */
+  async isHealthy(): Promise<boolean> {
+    try {
+      await this.getStatus()
+      return true
+    } catch {
+      return false
+    }
+  }
+}

package/src/apps/registry.ts

@@ -448,6 +448,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/portainer:/data`, "/var/run/docker.sock:/var/run/docker.sock"],
+    minPasswordLength: 12, // Portainer requires minimum 12 character password
   },
 
   huntarr: {

package/src/config/schema.ts

@@ -16,6 +16,7 @@ export interface EasiarrConfig {
   network?: NetworkConfig
   traefik?: TraefikConfig
   vpn?: VpnConfig
+  monitor?: MonitorConfig
   createdAt: string
   updatedAt: string
 }
@@ -27,6 +28,38 @@ export interface VpnConfig {
   provider?: string // For future use (e.g. custom, airvpn, protonvpn)
 }
 
+// ==========================================
+// Monitoring Configuration
+// ==========================================
+
+export type MonitorCheckType = "health" | "diskspace" | "status" | "queue"
+
+export interface MonitorOptions {
+  health: boolean
+  diskspace: boolean
+  status: boolean
+  queue: boolean
+}
+
+export interface CategoryMonitorConfig {
+  category: AppCategory
+  enabled: boolean
+  checks: MonitorOptions
+}
+
+export interface AppMonitorConfig {
+  appId: AppId
+  override: boolean // If true, uses app-specific settings instead of category defaults
+  enabled: boolean
+  checks: MonitorOptions
+}
+
+export interface MonitorConfig {
+  categories: CategoryMonitorConfig[]
+  apps: AppMonitorConfig[] // App-specific overrides
+  pollIntervalSeconds: number
+}
+
 export interface TraefikConfig {
   enabled: boolean
   domain: string
@@ -155,6 +188,8 @@ export interface AppDefinition {
   prowlarrCategoryIds?: number[]
   /** Architecture compatibility info - omit if supports all */
   arch?: ArchCompatibility
+  /** Minimum password length requirement for user creation */
+  minPasswordLength?: number
 }
 
 export interface RootFolderMeta {

package/src/index.ts

@@ -21,6 +21,10 @@ async function main() {
     consoleOptions: {
       startInDebugMode: false,
     },
+    exitOnCtrlC: true,
+    onDestroy: () => {
+      process.exit(0)
+    },
   })
 
   const app = new App(renderer)

package/src/ui/components/FooterHint.ts

@@ -0,0 +1,119 @@
+/**
+ * Footer Hint Types and Utilities
+ * Provides a flexible array-based structure for footer hints
+ */
+
+/** Base interface for all footer hint types with common styling */
+export interface FooterHintBase {
+  /** Foreground color */
+  fg?: string
+  /** Background color */
+  bg?: string
+}
+
+/** A simple text message hint (e.g., "Press ? for help.") */
+export interface FooterHintText extends FooterHintBase {
+  type: "text"
+  value: string
+}
+
+/** A keyboard shortcut hint (e.g., key: "↓", value: "Down") */
+export interface FooterHintKey extends FooterHintBase {
+  type: "key"
+  key: string
+  value: string
+  /** Color for the key part (default: bright/highlighted) */
+  keyColor?: string
+  /** Color for the value part (default: dimmer) */
+  valueColor?: string
+  /** Background color for the key badge */
+  keyBgColor?: string
+  /** Whether to show brackets around the key */
+  withBrackets?: boolean
+}
+
+/** Separator between hint groups */
+export interface FooterHintSeparator extends FooterHintBase {
+  type: "separator"
+  char?: string
+}
+
+/** Union type for all hint item types */
+export type FooterHintItem = FooterHintText | FooterHintKey | FooterHintSeparator
+
+/** Array of hint items */
+export type FooterHint = FooterHintItem[]
+
+/** Default separator character */
+const DEFAULT_SEPARATOR = "  "
+
+/**
+ * Render footer hints to a plain string
+ * Used by PageLayout for backward-compatible rendering
+ */
+export function renderFooterHint(hints: FooterHint): string {
+  return hints
+    .map((item) => {
+      switch (item.type) {
+        case "text":
+          return item.value
+        case "key":
+          return `${item.key}: ${item.value}`
+        case "separator":
+          return item.char ?? DEFAULT_SEPARATOR
+        default:
+          return ""
+      }
+    })
+    .join(DEFAULT_SEPARATOR)
+}
+
+/**
+ * Parse legacy string format to FooterHint array
+ * Supports both "Key: Action" and "Key Action" formats
+ */
+export function parseFooterHintString(hint: string): FooterHint {
+  // Split on double spaces (common separator in existing hints)
+  const parts = hint.split(/\s{2,}/)
+
+  return parts.map((part): FooterHintItem => {
+    // Try to parse as "Key: Action" or "Key Action" format
+    const colonMatch = part.match(/^([^\s:]+):\s*(.+)$/)
+    if (colonMatch) {
+      return { type: "key", key: colonMatch[1], value: colonMatch[2] }
+    }
+
+    const spaceMatch = part.match(/^([^\s]+)\s+(.+)$/)
+    if (spaceMatch) {
+      return { type: "key", key: spaceMatch[1], value: spaceMatch[2] }
+    }
+
+    // Fallback to text
+    return { type: "text", value: part }
+  })
+}
+
+/**
+ * Helper to create a key hint
+ */
+export function key(
+  key: string,
+  value: string,
+  options?: { keyColor?: string; valueColor?: string; keyBgColor?: string; withBrackets?: boolean }
+): FooterHintKey {
+  return { type: "key", key, value, ...options }
+}
+
+/**
+ * Helper to create a text hint
+ */
+export function text(value: string, fg?: string): FooterHintText {
+  return { type: "text", value, fg }
+}
+
+/**
+ * Helper to create a separator
+ */
+export function separator(char?: string): FooterHintSeparator {
+  return { type: "separator", char }
+}

package/src/ui/components/PageLayout.ts

@@ -1,10 +1,11 @@
-import { BoxRenderable, TextRenderable, type CliRenderer } from "@opentui/core"
+import { BoxRenderable, TextRenderable, TextNodeRenderable, type CliRenderer } from "@opentui/core"
 import { getVersion } from "../../VersionInfo"
+import { type FooterHint } from "./FooterHint"
 
 export interface PageLayoutOptions {
   title: string
   stepInfo?: string
-  footerHint?: string
+  footerHint?: FooterHint | string
 }
 
 export interface PageLayoutResult {
@@ -79,15 +80,62 @@ export function createPageLayout(renderer: CliRenderer, options: PageLayoutOptio
     backgroundColor: "#1a1a2e",
   })
 
-  // Hint text
-  const hintText = footerHint || "↑↓ Navigate  Enter Select  q Quit"
-  footerBox.add(
-    new TextRenderable(renderer, {
-      id: `${idPrefix}-footer-hint`,
-      content: hintText,
-      fg: "#aaaaaa",
+  // Hint text - handle both array and string formats
+  // Always append separator + Ctrl+C Exit when hints are provided
+  const hintContainer = new TextRenderable(renderer, {
+    id: `${idPrefix}-footer-hint`,
+    content: "",
+    fg: "#aaaaaa",
+  })
+
+  if (!footerHint) {
+    hintContainer.content = "↑↓: Navigate  Enter: Select  Ctrl+C: Exit"
+  } else if (typeof footerHint === "string") {
+    hintContainer.content = footerHint + "  Ctrl+C: Exit"
+  } else {
+    // Append separator and global Ctrl+C hint (styled red for demo)
+    const hintsWithExit: FooterHint = [
+      ...footerHint,
+      { type: "separator", char: " | " },
+      { type: "key", key: "Ctrl+C", value: "Exit", keyColor: "#ff6666", valueColor: "#888888" },
+    ]
+
+    // Build styled content using TextNodeRenderable
+    const DEFAULT_KEY_COLOR = "#8be9fd" // cyan/bright
+    const DEFAULT_VALUE_COLOR = "#aaaaaa" // dim
+    const DEFAULT_SEP_COLOR = "#555555"
+
+    // Helper to create a styled text node
+    const styledText = (text: string, fg?: string, bg?: string): TextNodeRenderable => {
+      const node = new TextNodeRenderable({ fg, bg })
+      node.add(text)
+      return node
+    }
+
+    hintsWithExit.forEach((item, idx) => {
+      if (item.type === "separator") {
+        hintContainer.add(styledText(item.char ?? "  ", DEFAULT_SEP_COLOR))
+      } else if (item.type === "text") {
+        hintContainer.add(styledText(item.value, item.fg ?? DEFAULT_VALUE_COLOR))
+        // Add spacing after text (except last)
+        if (idx < hintsWithExit.length - 1 && hintsWithExit[idx + 1]?.type !== "separator") {
+          hintContainer.add(styledText("  "))
+        }
+      } else if (item.type === "key") {
+        const keyDisplay = item.withBrackets ? `[${item.key}]` : item.key
+        // Key part (styled)
+        hintContainer.add(styledText(keyDisplay, item.keyColor ?? DEFAULT_KEY_COLOR, item.keyBgColor))
+        // Colon + Value
+        hintContainer.add(styledText(`: ${item.value}`, item.valueColor ?? DEFAULT_VALUE_COLOR))
+        // Add spacing after (except last or before separator)
+        if (idx < hintsWithExit.length - 1 && hintsWithExit[idx + 1]?.type !== "separator") {
+          hintContainer.add(styledText("  "))
+        }
+      }
     })
-  )
+  }
+
+  footerBox.add(hintContainer)
 
   // Version
   footerBox.add(

package/src/ui/screens/AdvancedSettings.ts

@@ -58,7 +58,10 @@ export class AdvancedSettings {
     const { container: page, content } = createPageLayout(this.renderer, {
       title: "Advanced Settings",
       stepInfo: "Direct File Editing",
-      footerHint: "Enter Select  Esc Back",
+      footerHint: [
+        { type: "key", key: "Enter", value: "Select" },
+        { type: "key", key: "Esc", value: "Back" },
+      ],
     })
 
     const menu = new SelectRenderable(this.renderer, {