@muhammedaksam/easiarr 0.6.2 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammedaksam/easiarr",
-  "version": "0.6.2",
+  "version": "0.7.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/portainer-api.ts

@@ -228,4 +228,115 @@ export class PortainerApiClient {
       return false
     }
   }
+
+  // ==========================================
+  // Container Management Methods
+  // ==========================================
+
+  /**
+   * Get list of Docker endpoints
+   */
+  async getEndpoints(): Promise<PortainerEndpoint[]> {
+    return this.request<PortainerEndpoint[]>("/endpoints")
+  }
+
+  /**
+   * Get all containers for an endpoint
+   */
+  async getContainers(endpointId: number = 1): Promise<PortainerContainer[]> {
+    return this.request<PortainerContainer[]>(`/endpoints/${endpointId}/docker/containers/json?all=true`)
+  }
+
+  /**
+   * Start a container by ID
+   */
+  async startContainer(containerId: string, endpointId: number = 1): Promise<void> {
+    await this.request(`/endpoints/${endpointId}/docker/containers/${containerId}/start`, {
+      method: "POST",
+    })
+  }
+
+  /**
+   * Stop a container by ID
+   */
+  async stopContainer(containerId: string, endpointId: number = 1): Promise<void> {
+    await this.request(`/endpoints/${endpointId}/docker/containers/${containerId}/stop`, {
+      method: "POST",
+    })
+  }
+
+  /**
+   * Restart a container by ID
+   */
+  async restartContainer(containerId: string, endpointId: number = 1): Promise<void> {
+    await this.request(`/endpoints/${endpointId}/docker/containers/${containerId}/restart`, {
+      method: "POST",
+    })
+  }
+
+  /**
+   * Get container logs
+   */
+  async getContainerLogs(
+    containerId: string,
+    endpointId: number = 1,
+    options: { stdout?: boolean; stderr?: boolean; tail?: number } = {}
+  ): Promise<string> {
+    const { stdout = true, stderr = true, tail = 100 } = options
+    const params = new URLSearchParams({
+      stdout: String(stdout),
+      stderr: String(stderr),
+      tail: String(tail),
+    })
+    return this.request<string>(`/endpoints/${endpointId}/docker/containers/${containerId}/logs?${params}`)
+  }
+
+  /**
+   * Get container stats (CPU, Memory usage)
+   */
+  async getContainerStats(containerId: string, endpointId: number = 1): Promise<PortainerContainerStats> {
+    return this.request<PortainerContainerStats>(
+      `/endpoints/${endpointId}/docker/containers/${containerId}/stats?stream=false`
+    )
+  }
+}
+
+// ==========================================
+// Additional Type Definitions
+// ==========================================
+
+export interface PortainerEndpoint {
+  Id: number
+  Name: string
+  Type: number
+  Status: number
+  URL: string
+}
+
+export interface PortainerContainer {
+  Id: string
+  Names: string[]
+  Image: string
+  State: string
+  Status: string
+  Ports: Array<{
+    IP?: string
+    PrivatePort: number
+    PublicPort?: number
+    Type: string
+  }>
+  Labels: Record<string, string>
+  Created: number
+}
+
+export interface PortainerContainerStats {
+  cpu_stats: {
+    cpu_usage: { total_usage: number }
+    system_cpu_usage: number
+    online_cpus: number
+  }
+  memory_stats: {
+    usage: number
+    limit: number
+  }
 }

package/src/apps/registry.ts

@@ -29,7 +29,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/movies",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [2000, 2010, 2020, 2030, 2040, 2045, 2050, 2060, 2070, 2080, 2090],
+    prowlarrCategoryIds: [2000], // Movies
+    homepage: { icon: "radarr.png", widget: "radarr" },
   },
 
   sonarr: {
@@ -53,7 +54,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/tv",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [5000, 5010, 5020, 5030, 5040, 5045, 5050, 5060, 5070, 5080, 5090],
+    prowlarrCategoryIds: [5000], // TV
+    homepage: { icon: "sonarr.png", widget: "sonarr" },
   },
 
   lidarr: {
@@ -75,7 +77,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/music",
       apiVersion: "v1",
     },
-    prowlarrCategoryIds: [3000, 3010, 3020, 3030, 3040, 3050, 3060],
+    prowlarrCategoryIds: [3000], // Audio
+    homepage: { icon: "lidarr.png", widget: "lidarr" },
   },
 
   readarr: {
@@ -97,11 +100,12 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/books",
       apiVersion: "v1",
     },
-    prowlarrCategoryIds: [7000, 7010, 7020, 7030, 7040, 7050, 7060],
+    prowlarrCategoryIds: [7000], // Books
     arch: {
       deprecated: ["arm64", "arm32"],
       warning: "Readarr is deprecated - no ARM64 support (project abandoned by upstream)",
     },
+    homepage: { icon: "readarr.png", widget: "readarr" },
   },
 
   bazarr: {
@@ -122,6 +126,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "yaml",
       selector: "auth.apikey",
     },
+    homepage: { icon: "bazarr.png", widget: "bazarr" },
   },
 
   mylar3: {
@@ -166,7 +171,8 @@ export const APPS: Record<AppId, AppDefinition> = {
       path: "/data/media/adult",
       apiVersion: "v3",
     },
-    prowlarrCategoryIds: [6000, 6010, 6020, 6030, 6040, 6045, 6050, 6060, 6070, 6080, 6090],
+    prowlarrCategoryIds: [6000], // XXX
+    homepage: { icon: "whisparr.png", widget: "sonarr" }, // Uses sonarr widget type
   },
 
   audiobookshelf: {
@@ -204,6 +210,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "<ApiKey>(.*?)</ApiKey>",
     },
+    homepage: { icon: "prowlarr.png", widget: "prowlarr" },
   },
 
   jackett: {
@@ -268,6 +275,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       },
     ],
     trashGuide: "docs/Downloaders/qBittorrent/",
+    homepage: { icon: "qbittorrent.png", widget: "qbittorrent" },
   },
 
   sabnzbd: {
@@ -288,6 +296,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "api_key\\s*=\\s*(.+)",
     },
+    homepage: { icon: "sabnzbd.png", widget: "sabnzbd" },
   },
 
   // === MEDIA SERVERS ===
@@ -309,6 +318,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: 'PlexOnlineToken="([^"]+)"',
     },
+    homepage: { icon: "plex.png", widget: "plex" },
   },
 
   jellyfin: {
@@ -321,6 +331,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/jellyfin:/config`, `${root}/data/media:/data/media`],
+    homepage: { icon: "jellyfin.png", widget: "jellyfin" },
   },
 
   tautulli: {
@@ -339,6 +350,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "regex",
       selector: "api_key\\s*=\\s*(.+)",
     },
+    homepage: { icon: "tautulli.png", widget: "tautulli" },
   },
 
   tdarr: {
@@ -376,6 +388,7 @@ export const APPS: Record<AppId, AppDefinition> = {
       parser: "json",
       selector: "main.apiKey",
     },
+    homepage: { icon: "overseerr.png", widget: "overseerr" },
   },
 
   jellyseerr: {
@@ -436,6 +449,10 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/homepage:/app/config`, "/var/run/docker.sock:/var/run/docker.sock"],
+    environment: {
+      HOMEPAGE_ALLOWED_HOSTS:
+        "homepage,homepage.${CLOUDFLARE_DNS_ZONE},${CLOUDFLARE_DNS_ZONE},localhost,${LOCAL_DOCKER_IP}",
+    },
   },
 
   // === UTILITIES ===
@@ -450,6 +467,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     pgid: 0,
     volumes: (root) => [`${root}/config/portainer:/data`, "/var/run/docker.sock:/var/run/docker.sock"],
     minPasswordLength: 12, // Portainer requires minimum 12 character password
+    homepage: { icon: "portainer.png", widget: "portainer" },
   },
 
   huntarr: {
@@ -562,6 +580,31 @@ export const APPS: Record<AppId, AppDefinition> = {
     volumes: (root) => [`${root}/config/ddns-updater:/data`],
   },
 
+  "easiarr-status": {
+    id: "easiarr-status",
+    name: "Easiarr Status",
+    description: "Exposes Easiarr version for Homepage dashboard",
+    category: "utility",
+    defaultPort: 3009,
+    image: "halverneus/static-file-server:latest",
+    puid: 0,
+    pgid: 0,
+    volumes: (root) => [`${root}/.easiarr:/web:ro`],
+    environment: {
+      FOLDER: "/web",
+      PORT: "3009",
+      CORS: "true",
+    },
+    homepage: {
+      icon: "mdi-docker",
+      widget: "customapi",
+      widgetFields: {
+        url: "http://easiarr-status:3009/config.json",
+        mappings: JSON.stringify([{ field: "version", label: "Installed" }]),
+      },
+    },
+  },
+
   // === VPN ===
   gluetun: {
     id: "gluetun",
@@ -608,6 +651,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "gluetun.png", widget: "gluetun" },
   },
 
   // === MONITORING ===
@@ -621,6 +665,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/grafana:/var/lib/grafana`],
+    homepage: { icon: "grafana.png", widget: "grafana" },
   },
 
   prometheus: {
@@ -633,6 +678,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 13000,
     volumes: (root) => [`${root}/config/prometheus:/prometheus`],
+    homepage: { icon: "prometheus.png" }, // No widget, just icon
   },
 
   dozzle: {
@@ -660,6 +706,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/uptime-kuma:/app/data`, "/var/run/docker.sock:/var/run/docker.sock"],
+    homepage: { icon: "uptime-kuma.png", widget: "uptimekuma" },
   },
 
   // === INFRASTRUCTURE ===
@@ -690,6 +737,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         required: true,
       },
     ],
+    homepage: { icon: "traefik.png", widget: "traefik" },
   },
 
   "traefik-certs-dumper": {
@@ -715,6 +763,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/crowdsec:/etc/crowdsec`, "/var/run/docker.sock:/var/run/docker.sock:ro"],
+    homepage: { icon: "crowdsec.png", widget: "crowdsec" },
   },
 
   headscale: {
@@ -727,6 +776,7 @@ export const APPS: Record<AppId, AppDefinition> = {
     puid: 0,
     pgid: 0,
     volumes: (root) => [`${root}/config/headscale:/etc/headscale`, `${root}/config/headscale/data:/var/lib/headscale`],
+    homepage: { icon: "headscale.png", widget: "headscale" },
   },
 
   headplane: {
@@ -762,6 +812,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "tailscale.png", widget: "tailscale" },
   },
 
   authentik: {
@@ -804,6 +855,7 @@ export const APPS: Record<AppId, AppDefinition> = {
         mask: true,
       },
     ],
+    homepage: { icon: "authentik.png", widget: "authentik" },
   },
 
   "authentik-worker": {

package/src/compose/generator.ts

@@ -8,7 +8,7 @@ import type { EasiarrConfig, AppConfig, TraefikConfig, AppId } from "../config/s
 import { getComposePath } from "../config/manager"
 import { getApp } from "../apps/registry"
 import { generateServiceYaml } from "./templates"
-import { updateEnv } from "../utils/env"
+import { updateEnv, getLocalIp } from "../utils/env"
 
 export interface ComposeService {
   image: string
@@ -212,5 +212,6 @@ async function updateEnvFile(config: EasiarrConfig) {
     PUID: config.uid.toString(),
     PGID: config.gid.toString(),
     UMASK: config.umask,
+    LOCAL_DOCKER_IP: getLocalIp(),
   })
 }

package/src/config/homepage-config.ts

@@ -0,0 +1,247 @@
+/**
+ * Homepage Configuration Generator
+ * Generates services.yaml and other config files for Homepage dashboard
+ */
+
+import { writeFile, mkdir } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { EasiarrConfig, AppCategory } from "./schema"
+import { APP_CATEGORIES } from "./schema"
+import { getApp } from "../apps/registry"
+import { CATEGORY_ORDER } from "../apps/categories"
+import { readEnvSync, getLocalIp } from "../utils/env"
+
+/**
+ * Get the Homepage config directory path
+ */
+export function getHomepageConfigPath(config: EasiarrConfig): string {
+  return join(config.rootDir, "config", "homepage")
+}
+
+/**
+ * Homepage service entry
+ */
+interface HomepageService {
+  href: string
+  icon?: string
+  description?: string
+  ping?: string
+  widget?: {
+    type: string
+    url: string
+    key?: string
+    [key: string]: unknown
+  }
+}
+
+/**
+ * Generate services.yaml content from enabled apps
+ */
+export async function generateServicesYaml(config: EasiarrConfig): Promise<string> {
+  const env = readEnvSync()
+  const localIp = getLocalIp()
+
+  // Group apps by category
+  const categoryGroups = new Map<AppCategory, Array<{ name: string; service: HomepageService }>>()
+
+  for (const appConfig of config.apps) {
+    if (!appConfig.enabled) continue
+
+    const appDef = getApp(appConfig.id)
+    if (!appDef) continue
+
+    // Skip homepage itself
+    if (appDef.id === "homepage") continue
+
+    const port = appConfig.port ?? appDef.defaultPort
+    const baseUrl = `http://${localIp}:${port}`
+
+    const service: HomepageService = {
+      href: baseUrl,
+      description: appDef.description,
+    }
+
+    // Add icon if defined in homepage meta
+    if (appDef.homepage?.icon) {
+      service.icon = appDef.homepage.icon
+    } else {
+      // Default to app ID as icon name
+      service.icon = `${appDef.id}.png`
+    }
+
+    // Add ping for monitoring
+    service.ping = baseUrl
+
+    // Add widget if defined and has API key
+    if (appDef.homepage?.widget) {
+      const apiKey = env[`API_KEY_${appDef.id.toUpperCase()}`]
+
+      service.widget = {
+        type: appDef.homepage.widget,
+        url: baseUrl,
+      }
+
+      if (apiKey) {
+        service.widget.key = apiKey
+      }
+
+      // Add any custom widget fields
+      if (appDef.homepage.widgetFields) {
+        Object.assign(service.widget, appDef.homepage.widgetFields)
+      }
+    }
+
+    // Add to category group
+    const category = appDef.category
+    if (!categoryGroups.has(category)) {
+      categoryGroups.set(category, [])
+    }
+    categoryGroups.get(category)!.push({ name: appDef.name, service })
+  }
+
+  // Build YAML output
+  let yaml = "---\n# Auto-generated by Easiarr\n# https://github.com/muhammedaksam/easiarr\n\n"
+
+  // Add Easiarr info section with two widgets - one for installed, one for latest
+  const localIpForEasiarr = localIp
+  yaml += `Easiarr:\n`
+  // Installed version from local easiarr-status container
+  yaml += `  - Installed:\n`
+  yaml += `      href: https://github.com/muhammedaksam/easiarr\n`
+  yaml += `      icon: mdi-docker\n`
+  yaml += `      description: Your current version\n`
+  yaml += `      widget:\n`
+  yaml += `        type: customapi\n`
+  yaml += `        url: http://${localIpForEasiarr}:3009/config.json\n`
+  yaml += `        refreshInterval: 3600000\n` // 1 hour
+  yaml += `        mappings:\n`
+  yaml += `          - field: version\n`
+  yaml += `            label: Version\n`
+  // Latest version from GitHub API
+  yaml += `  - Latest:\n`
+  yaml += `      href: https://github.com/muhammedaksam/easiarr/releases\n`
+  yaml += `      icon: mdi-github\n`
+  yaml += `      description: Check for updates\n`
+  yaml += `      widget:\n`
+  yaml += `        type: customapi\n`
+  yaml += `        url: https://api.github.com/repos/muhammedaksam/easiarr/releases/latest\n`
+  yaml += `        refreshInterval: 86400000\n` // 24 hours
+  yaml += `        mappings:\n`
+  yaml += `          - field: tag_name\n`
+  yaml += `            label: Version\n`
+  yaml += `          - field: published_at\n`
+  yaml += `            label: Released\n`
+  yaml += `            format: relativeDate\n`
+  yaml += `\n`
+
+  // Use CATEGORY_ORDER for consistent ordering
+  for (const { id: category } of CATEGORY_ORDER) {
+    const services = categoryGroups.get(category)
+    if (!services || services.length === 0) continue
+
+    const categoryName = APP_CATEGORIES[category]
+    yaml += `${categoryName}:\n`
+
+    for (const { name, service } of services) {
+      yaml += `  - ${name}:\n`
+      yaml += `      href: ${service.href}\n`
+
+      if (service.icon) {
+        yaml += `      icon: ${service.icon}\n`
+      }
+
+      if (service.description) {
+        yaml += `      description: ${service.description}\n`
+      }
+
+      if (service.ping) {
+        yaml += `      ping: ${service.ping}\n`
+      }
+
+      if (service.widget) {
+        yaml += `      widget:\n`
+        yaml += `        type: ${service.widget.type}\n`
+        yaml += `        url: ${service.widget.url}\n`
+
+        if (service.widget.key) {
+          yaml += `        key: ${service.widget.key}\n`
+        }
+
+        // Add any other widget fields
+        for (const [key, value] of Object.entries(service.widget)) {
+          if (key !== "type" && key !== "url" && key !== "key") {
+            yaml += `        ${key}: ${value}\n`
+          }
+        }
+      }
+    }
+
+    yaml += "\n"
+  }
+
+  return yaml
+}
+
+/**
+ * Generate settings.yaml with sensible defaults
+ */
+export function generateSettingsYaml(): string {
+  return `---
+# Auto-generated by Easiarr
+# For configuration options: https://gethomepage.dev/configs/settings/
+
+title: Easiarr Dashboard
+
+# Background: "Close-up Photography of Leaves With Droplets"
+# Photo by Sohail Nachiti: https://www.pexels.com/photo/close-up-photography-of-leaves-with-droplets-807598/
+background:
+  image: https://images.pexels.com/photos/807598/pexels-photo-807598.jpeg?cs=srgb&fm=jpg&w=4128&h=3096
+  blur: sm
+  saturate: 50
+  brightness: 50
+  opacity: 50
+
+cardBlur: md
+theme: dark
+color: slate
+
+layout:
+  Media Management:
+    style: row
+    columns: 4
+  Media Servers:
+    style: row
+    columns: 2
+  Download Clients:
+    style: row
+    columns: 2
+`
+}
+
+/**
+ * Save Homepage configuration files
+ */
+export async function saveHomepageConfig(config: EasiarrConfig): Promise<{ services: string; settings: string }> {
+  const configPath = getHomepageConfigPath(config)
+
+  // Ensure directory exists
+  if (!existsSync(configPath)) {
+    await mkdir(configPath, { recursive: true })
+  }
+
+  const servicesPath = join(configPath, "services.yaml")
+  const settingsPath = join(configPath, "settings.yaml")
+
+  // Generate and save services.yaml
+  const servicesYaml = await generateServicesYaml(config)
+  await writeFile(servicesPath, servicesYaml, "utf-8")
+
+  // Generate and save settings.yaml (only if doesn't exist)
+  if (!existsSync(settingsPath)) {
+    const settingsYaml = generateSettingsYaml()
+    await writeFile(settingsPath, settingsYaml, "utf-8")
+  }
+
+  return { services: servicesPath, settings: settingsPath }
+}

package/src/config/manager.ts

@@ -10,6 +10,7 @@ import { join } from "node:path"
 import type { EasiarrConfig } from "./schema"
 import { DEFAULT_CONFIG } from "./schema"
 import { detectTimezone, detectUid, detectGid } from "./defaults"
+import { VersionInfo } from "../VersionInfo"
 
 const CONFIG_DIR_NAME = ".easiarr"
 const CONFIG_FILE_NAME = "config.json"
@@ -48,6 +49,26 @@ export async function configExists(): Promise<boolean> {
   return existsSync(getConfigPath())
 }
 
+/**
+ * Migrate config to current version
+ * Preserves user settings while adding new fields with defaults
+ */
+function migrateConfig(oldConfig: Partial<EasiarrConfig>): EasiarrConfig {
+  return {
+    // Start with defaults for new fields
+    ...DEFAULT_CONFIG,
+    // Preserve all user settings
+    ...oldConfig,
+    // Always update version to current
+    version: VersionInfo.version,
+    // Ensure required fields have values
+    umask: oldConfig.umask ?? "002",
+    apps: oldConfig.apps ?? [],
+    createdAt: oldConfig.createdAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  } as EasiarrConfig
+}
+
 export async function loadConfig(): Promise<EasiarrConfig | null> {
   const configPath = getConfigPath()
 
@@ -57,7 +78,16 @@ export async function loadConfig(): Promise<EasiarrConfig | null> {
 
   try {
     const content = await readFile(configPath, "utf-8")
-    return JSON.parse(content) as EasiarrConfig
+    let config = JSON.parse(content) as EasiarrConfig
+
+    // Auto-migrate if version differs from current package version
+    if (config.version !== VersionInfo.version) {
+      config = migrateConfig(config)
+      // Save migrated config (creates backup first)
+      await saveConfig(config)
+    }
+
+    return config
   } catch (error) {
     console.error("Failed to load config:", error)
     return null

package/src/config/schema.ts

@@ -120,6 +120,7 @@ export type AppId =
   | "guacamole"
   | "guacd"
   | "ddns-updater"
+  | "easiarr-status"
   // VPN
   | "gluetun"
   // Monitoring & Infra
@@ -190,6 +191,18 @@ export interface AppDefinition {
   arch?: ArchCompatibility
   /** Minimum password length requirement for user creation */
   minPasswordLength?: number
+  /** Homepage dashboard configuration */
+  homepage?: HomepageMeta
+}
+
+/** Homepage dashboard widget/service configuration */
+export interface HomepageMeta {
+  /** Icon name from Dashboard Icons (e.g., "radarr.png", "mdi-web") */
+  icon?: string
+  /** Widget type for Homepage (e.g., "radarr", "sonarr", "qbittorrent") */
+  widget?: string
+  /** Custom widget fields if needed */
+  widgetFields?: Record<string, string>
 }
 
 export interface RootFolderMeta {