@katmer/core 0.0.3

package/lib/schemas/katmer_config.schema.json

@@ -0,0 +1,358 @@
+{
+  "$id": "https://katmer.dev/schemas/katmer-config.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Katmer Configuration Schema",
+  "description": "Defines the structure of a Katmer configuration file used to describe hosts, groups, and logging settings.",
+  "type": "object",
+  "required": ["targets"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional JSON Schema identifier to explicitly declare the schema version or custom dialect used by this configuration.",
+      "examples": [
+        "https://json-schema.org/draft/2020-12/schema",
+        "https://katmer.dev/schemas/katmer-config.schema.json"
+      ]
+    },
+    "$id": {
+      "type": "string",
+      "description": "Optional unique identifier (URI) for this configuration instance, useful for referencing or composition.",
+      "examples": [
+        "https://example.com/envs/prod.json",
+        "file:///etc/katmer/katmer.config.json"
+      ]
+    },
+    "cwd": {
+      "type": "string",
+      "description": "Working directory in which Katmer operations will be executed. Defaults to the current directory if omitted.",
+      "examples": ["./deploy", "/opt/katmer", "/home/admin/katmer-tasks"]
+    },
+    "logging": {
+      "type": "object",
+      "description": "Configuration options for logging.",
+      "properties": {
+        "dir": {
+          "type": "string",
+          "description": "Directory path where log files should be stored.",
+          "examples": ["./logs", "/var/log/katmer"]
+        },
+        "level": {
+          "type": "string",
+          "enum": ["trace", "debug", "info", "warn", "error", "silent"],
+          "description": "Defines the verbosity level of logs.",
+          "examples": ["info", "debug"]
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "dir": "./logs",
+          "level": "debug"
+        }
+      ]
+    },
+    "include": {
+      "description": "An optional file or remote URL to include additional configuration from.",
+      "anyOf": [
+        {
+          "type": "string",
+          "description": "A local or remote file path to another Katmer configuration.",
+          "examples": ["./common.yml", "https://katmer.dev/configs/base.json"]
+        },
+        {
+          "type": "object",
+          "required": ["url"],
+          "additionalProperties": false,
+          "properties": {
+            "url": {
+              "type": "string",
+              "description": "URL pointing to an external Katmer configuration file.",
+              "examples": ["https://katmer.dev/configs/shared.json"]
+            }
+          },
+          "examples": [{ "url": "https://katmer.dev/configs/base.json" }]
+        }
+      ]
+    },
+    "targets": {
+      "description": "Top-level mapping of named target groups. Each target defines one or more host groups.",
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "hosts": {
+              "$ref": "#/$defs/KatmerHostsDefinition",
+              "description": "Map of host definitions belonging to this group."
+            },
+            "variables": {
+              "type": "object",
+              "description": "Arbitrary data variables merged into ctx.variables for all hosts in this (root) group.",
+              "additionalProperties": true,
+              "examples": [{ "env": "prod", "app_dir": "/opt/myapp" }]
+            },
+            "environment": {
+              "type": "object",
+              "description": "Key/value pairs exported as environment variables for all hosts in this (root) group.",
+              "additionalProperties": {
+                "type": ["string", "number", "boolean"]
+              },
+              "examples": [
+                { "NODE_ENV": "production", "HTTP_PROXY": "http://proxy:8080" }
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z0-9_.:-]+$": { "$ref": "#/$defs/KatmerHostGroup" }
+          },
+          "description": "Named target groups, where each key corresponds to a group identifier."
+        }
+      ],
+      "examples": [
+        {
+          "production": {
+            "variables": {
+              "env": "prod",
+              "app_dir": "/opt/myapp",
+              "release": "2024-10-18"
+            },
+            "environment": {
+              "NODE_ENV": "production",
+              "HTTP_PROXY": "http://proxy.internal:8080"
+            },
+            "hosts": {
+              "app-server-1": {
+                "connection": "ssh",
+                "hostname": "10.0.0.11",
+                "username": "deploy",
+                "private_key": "~/.ssh/id_rsa"
+              },
+              "app-server-2": {
+                "connection": "ssh",
+                "hostname": "10.0.0.12",
+                "username": "deploy",
+                "private_key": "~/.ssh/id_rsa"
+              }
+            },
+            "children": {
+              "db": {
+                "variables": { "pg_version": 15 },
+                "environment": { "PGTZ": "UTC" },
+                "hosts": {
+                  "db1": {
+                    "connection": "ssh",
+                    "hostname": "10.0.0.20",
+                    "username": "postgres",
+                    "private_key": "~/.ssh/id_rsa"
+                  }
+                }
+              }
+            }
+          },
+          "local": {
+            "hosts": {
+              "localhost": { "connection": "local" }
+            }
+          }
+        }
+      ]
+    }
+  },
+
+  "$defs": {
+    "KatmerHostGroup": {
+      "type": "object",
+      "description": "A collection of hosts and/or nested child groups. Groups can inherit settings from parent groups.",
+      "properties": {
+        "hosts": {
+          "$ref": "#/$defs/KatmerHostsDefinition",
+          "description": "Map of host definitions belonging to this group."
+        },
+        "variables": {
+          "type": "object",
+          "description": "Arbitrary data variables merged into ctx.variables for all hosts in this group.",
+          "additionalProperties": true,
+          "examples": [{ "env": "prod", "app_dir": "/opt/myapp" }]
+        },
+        "environment": {
+          "type": "object",
+          "description": "Key/value pairs exported as environment variables for all hosts in this group.",
+          "additionalProperties": { "type": ["string", "number", "boolean"] },
+          "examples": [
+            { "NODE_ENV": "production", "NO_PROXY": "localhost,127.0.0.1" }
+          ]
+        },
+        "children": {
+          "type": "object",
+          "description": "Nested child groups within this host group. Each child can be a group or null (for disabling inheritance).",
+          "patternProperties": {
+            "^[a-zA-Z0-9_.:-]+$": {
+              "oneOf": [
+                { "$ref": "#/$defs/KatmerHostGroup" },
+                { "type": "null" }
+              ]
+            }
+          },
+          "examples": [
+            {
+              "backend": {
+                "hosts": {
+                  "api1": {
+                    "connection": "ssh",
+                    "hostname": "192.168.10.12",
+                    "username": "ubuntu"
+                  }
+                }
+              }
+            }
+          ]
+        }
+      },
+      "examples": [
+        {
+          "variables": { "env": "staging" },
+          "environment": { "NODE_ENV": "staging" },
+          "hosts": {
+            "node1": { "connection": "ssh", "hostname": "10.0.1.1" },
+            "node2": { "connection": "ssh", "hostname": "10.0.1.2" }
+          }
+        }
+      ]
+    },
+
+    "KatmerHostsDefinition": {
+      "type": "object",
+      "description": "Mapping of host identifiers to their configuration objects.",
+      "patternProperties": {
+        "^[a-zA-Z0-9_.:-]+$": {
+          "oneOf": [
+            { "$ref": "#/$defs/KatmerHostConfig" },
+            {
+              "type": "null",
+              "description": "Explicitly disabled or undefined host entry."
+            }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "web1": {
+            "connection": "ssh",
+            "hostname": "10.1.0.5",
+            "username": "root"
+          },
+          "web2": null
+        }
+      ]
+    },
+
+    "KatmerHostConfig": {
+      "type": "object",
+      "description": "Connection configuration for an individual host.",
+      "required": ["connection"],
+      "properties": {
+        "connection": {
+          "type": "string",
+          "enum": ["ssh", "local"],
+          "description": "Connection type used for the host. Can be 'ssh' for remote or 'local' for local execution.",
+          "examples": ["ssh", "local"]
+        },
+        "hostname": {
+          "type": "string",
+          "description": "Host or IP address for SSH connections.",
+          "examples": ["192.168.0.10", "server.local"]
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535,
+          "description": "Port number used for SSH connections. Defaults to 22 if omitted.",
+          "examples": [22, 2222]
+        },
+        "username": {
+          "type": "string",
+          "description": "Username for authentication.",
+          "examples": ["root", "deploy", "ubuntu"]
+        },
+        "password": {
+          "type": ["string", "number", "null"],
+          "description": "Password or token for authentication. May be null if using key-based authentication.",
+          "examples": ["supersecret", null]
+        },
+        "private_key": {
+          "type": "string",
+          "description": "Path to a private key file for SSH authentication.",
+          "examples": ["~/.ssh/id_rsa", "/etc/keys/deploy.pem"]
+        },
+        "private_key_password": {
+          "type": "string",
+          "description": "Optional password for the private key file.",
+          "examples": ["keypass123"]
+        }
+      },
+      "additionalProperties": false,
+      "examples": [
+        {
+          "connection": "ssh",
+          "hostname": "10.0.0.11",
+          "port": 22,
+          "username": "deploy",
+          "private_key": "~/.ssh/id_rsa"
+        },
+        { "connection": "local" }
+      ]
+    }
+  },
+
+  "examples": [
+    {
+      "cwd": "./deploy",
+      "logging": { "dir": "./logs", "level": "info" },
+      "include": "https://katmer.dev/configs/shared.json",
+      "targets": {
+        "production": {
+          "variables": {
+            "env": "prod",
+            "app_dir": "/opt/myapp",
+            "release": "2024-10-18"
+          },
+          "environment": {
+            "NODE_ENV": "production",
+            "HTTP_PROXY": "http://proxy.internal:8080"
+          },
+          "hosts": {
+            "frontend": {
+              "connection": "ssh",
+              "hostname": "10.0.0.10",
+              "username": "deployer",
+              "private_key": "~/.ssh/id_rsa"
+            }
+          },
+          "children": {
+            "database": {
+              "variables": { "pg_version": 15 },
+              "environment": { "PGTZ": "UTC" },
+              "hosts": {
+                "db1": {
+                  "connection": "ssh",
+                  "hostname": "10.0.0.15",
+                  "username": "postgres",
+                  "private_key": "~/.ssh/id_rsa"
+                }
+              }
+            }
+          }
+        },
+        "local": {
+          "hosts": {
+            "localhost": { "connection": "local" }
+          }
+        }
+      }
+    }
+  ]
+}

package/lib/target_resolver.ts

@@ -0,0 +1,298 @@
+import type {
+  KatmerConfig,
+  KatmerHostResolved,
+  KatmerHostInput
+} from "./interfaces/config.interface"
+import { toMerged } from "es-toolkit"
+import type { KatmerProvider } from "./interfaces/provider.interface"
+import objectHash from "stable-hash"
+import { SSHProvider } from "./providers/ssh/ssh.provider"
+import type { KatmerCore } from "./katmer"
+import { LocalProvider } from "./providers/local.provider"
+import { wildcardMatch } from "./utils/string.utils"
+import { evalObjectVals, evalTemplate } from "./utils/renderer/renderer"
+
+export class KatmerTargetResolver {
+  #providerCache = new Map<string, KatmerProvider>()
+
+  #allNames: Set<string>
+  #groups: Map<string, Set<string>>
+  #hosts: Map<string, KatmerHostResolved>
+  constructor(
+    private core: KatmerCore,
+    ...targets: KatmerConfig["targets"][]
+  ) {
+    const normalized = KatmerTargetResolver.normalizeHosts(
+      this.core.config.targets,
+      ...targets
+    )
+    this.#hosts = normalized.hosts
+    this.#groups = normalized.groups
+    this.#allNames = normalized.allNames
+  }
+
+  get hosts() {
+    return this.#hosts
+  }
+
+  async resolveProvider(opts: KatmerHostResolved): Promise<KatmerProvider> {
+    const key = objectHash(opts)
+
+    if (this.#providerCache.has(key)) {
+      return this.#providerCache.get(key)!
+    }
+    let provider: KatmerProvider
+    if (!opts.connection || opts.connection === "ssh") {
+      provider = new SSHProvider(opts)
+    } else if (opts.connection === "local") {
+      provider = new LocalProvider(opts)
+    } else {
+      throw new Error(`Unknown connection type: ${opts["connection"]}`)
+    }
+
+    provider.logger = this.core.logger.child({
+      provider: provider.constructor.name
+    })
+
+    if (opts.variables) {
+      provider.variables = toMerged(provider.variables, opts.variables)
+    }
+    if (opts.environment) {
+      const env = toMerged(provider.environment, opts.environment)
+
+      provider.environment = await evalObjectVals(env, {
+        //   TODO: env context
+      })
+    }
+
+    this.#providerCache.set(key, provider)
+    return provider
+  }
+
+  resolveTargets(pattern: string) {
+    if (pattern === "all" || pattern === "*") {
+      return [...this.#hosts.values()]
+    }
+
+    const parts = pattern.split(/[:,]/)
+    const included = [] as string[]
+    const excluded = [] as string[]
+    const intersected = [] as string[]
+
+    for (const part of parts) {
+      if (part.startsWith("!")) {
+        const plainName = part.slice(1)
+        if (excluded.indexOf(plainName) === -1) {
+          excluded.push(plainName)
+        }
+      } else if (part.startsWith("@")) {
+        const plainName = part.slice(1)
+        if (intersected.indexOf(plainName) === -1) {
+          intersected.push(part.slice(1))
+        }
+      } else if (included.indexOf(part) === -1) {
+        const token = part === "all" ? "*" : part // ← normalize 'all'
+        if (!included.includes(token)) included.push(token)
+      }
+    }
+    const wildcard = (name: string, pat: string) => wildcardMatch(name, pat)
+    const matchesAny = (name: string, list: string[]) =>
+      list.some((p) => wildcard(name, p))
+    const isExcluded = (name: string) => excluded.some((p) => wildcard(name, p))
+
+    // Stage 1: choose label candidates (hosts or groups), honoring exclusion
+    const candidateLabels = new Set<string>()
+    for (const name of this.#allNames) {
+      if (isExcluded(name)) continue
+      if (included.length === 0 || matchesAny(name, included)) {
+        candidateLabels.add(name)
+      }
+    }
+
+    // Stage 2: expand labels to hostnames, honoring exclusion & dedupe
+    const expandedHostnames = new Set<string>()
+    for (const label of candidateLabels) {
+      if (this.#groups.has(label)) {
+        for (const host of this.#groups.get(label)!) {
+          if (!isExcluded(host)) expandedHostnames.add(host)
+        }
+      } else if (this.#hosts.has(label)) {
+        if (!isExcluded(label)) expandedHostnames.add(label)
+      }
+    }
+
+    // Stage 3: optional intersection (@foo) applied on final hostnames
+    let finalHostnames = Array.from(expandedHostnames)
+    if (intersected.length > 0) {
+      finalHostnames = finalHostnames.filter((h) => matchesAny(h, intersected))
+    }
+
+    const resolved = finalHostnames
+      .map((h) => this.#hosts.get(h)!)
+      .filter(Boolean)
+
+    if (resolved.length === 0) {
+      throw new Error(`No targets found for pattern: ${pattern}`)
+    }
+    return resolved
+  }
+
+  static normalizeHosts(...inputs: KatmerConfig["targets"][]) {
+    const reservedKeys = [
+      "all",
+      "children",
+      "settings",
+      "variables",
+      "environment",
+      "hosts"
+    ]
+    const allNames = new Set<string>()
+    const hosts = new Map<string, KatmerHostResolved>()
+    const groups = new Map<string, Set<string>>()
+
+    const groupSettingsAccum = new Map<string, Record<string, any>>()
+    const groupVariablesAccum = new Map<string, Record<string, any>>()
+    const groupEnvAccum = new Map<string, Record<string, any>>() // NEW
+
+    for (const input of inputs) {
+      if (!input) continue
+
+      const rootKeys = Object.keys(input)
+      const isHostsDef =
+        rootKeys.includes("hosts") ||
+        rootKeys.includes("settings") ||
+        rootKeys.includes("variables") ||
+        rootKeys.includes("environment") // NEW
+
+      if (isHostsDef) {
+        // Ungrouped (root) settings
+        const incomingSettings = (input as any).settings || {}
+        const prevSettings = groupSettingsAccum.get("ungrouped") || {}
+        const effSettings = toMerged(prevSettings, incomingSettings) as any
+        groupSettingsAccum.set("ungrouped", effSettings)
+
+        // Ungrouped variables
+        const incomingVars = (input as any).variables || {}
+        const prevVars = groupVariablesAccum.get("ungrouped") || {}
+        const effVars = toMerged(prevVars, incomingVars) as any
+        groupVariablesAccum.set("ungrouped", effVars)
+
+        // Ungrouped environment (NEW)
+        const incomingEnv = (input as any).environment || {}
+        const prevEnv = groupEnvAccum.get("ungrouped") || {}
+        const effEnv = toMerged(prevEnv, incomingEnv) as any
+        groupEnvAccum.set("ungrouped", effEnv)
+
+        processHostEntries(
+          (input as any).hosts,
+          "ungrouped",
+          effSettings,
+          effVars,
+          effEnv
+        )
+      } else {
+        for (const [groupName, def] of Object.entries(input)) {
+          if (reservedKeys.includes(groupName)) {
+            throw `cannot use '${groupName}' as group name: it is a reserved keyword`
+          }
+
+          // Group settings
+          const incomingSettings = (def as any)?.settings || {}
+          const prevSettings = groupSettingsAccum.get(groupName) || {}
+          const effSettings = toMerged(prevSettings, incomingSettings) as any
+          groupSettingsAccum.set(groupName, effSettings)
+
+          // Group variables
+          const incomingVars = (def as any)?.variables || {}
+          const prevVars = groupVariablesAccum.get(groupName) || {}
+          const effVars = toMerged(prevVars, incomingVars) as any
+          groupVariablesAccum.set(groupName, effVars)
+
+          // Group environment (NEW)
+          const incomingEnv = (def as any)?.environment || {}
+          const prevEnv = groupEnvAccum.get(groupName) || {}
+          const effEnv = toMerged(prevEnv, incomingEnv) as any
+          groupEnvAccum.set(groupName, effEnv)
+
+          processHostEntries(
+            def?.hosts,
+            groupName,
+            effSettings,
+            effVars,
+            effEnv
+          )
+
+          // Link children: inherit parent *settings/variables/environment* to child hosts
+          const childNames = Object.keys(def?.children || {})
+          for (const childGroupName of childNames) {
+            if (!groups.has(childGroupName)) {
+              throw `child group not found: '${childGroupName}' in group: '${groupName}'`
+            }
+            for (const child_hostname of groups.get(childGroupName)!) {
+              const prevChild = (hosts.get(child_hostname) || {}) as any
+              const childVarsPrev = prevChild.variables || {}
+              const childEnvPrev = prevChild.environment || {}
+              const parentVars = groupVariablesAccum.get(groupName) || {}
+              const parentEnv = groupEnvAccum.get(groupName) || {}
+
+              hosts.set(child_hostname, {
+                ...(toMerged(prevChild, effSettings) as any),
+                name: child_hostname,
+                variables: toMerged(childVarsPrev, parentVars),
+                environment: toMerged(childEnvPrev, parentEnv) // NEW
+              })
+            }
+          }
+        }
+      }
+    }
+
+    function processHostEntries(
+      hostConfig?: Record<string, KatmerHostInput>,
+      groupName: string = "ungrouped",
+      groupSettings: Record<string, any> = {},
+      groupVariables: Record<string, any> = {},
+      groupEnvironment: Record<string, any> = {} // NEW
+    ) {
+      if (!groups.has(groupName)) groups.set(groupName, new Set<string>())
+      const groupHosts = groups.get(groupName)!
+      allNames.add(groupName)
+
+      for (const [hostname, host_settings] of Object.entries(
+        hostConfig || {}
+      )) {
+        if (reservedKeys.includes(hostname)) {
+          throw `cannot use '${hostname}' as hostname: it is a reserved keyword`
+        }
+        allNames.add(hostname)
+        groupHosts.add(hostname)
+
+        const prev = (hosts.get(hostname) || {}) as any
+        const mergedConn = toMerged(
+          prev,
+          toMerged(groupSettings || {}, host_settings || {})
+        ) as any
+
+        const prevVars = prev.variables || {}
+        const prevEnv = prev.environment || {}
+
+        hosts.set(hostname, {
+          ...mergedConn,
+          name: hostname,
+          variables: toMerged(prevVars, groupVariables || {}),
+          environment: toMerged(prevEnv, groupEnvironment || {}) // NEW
+        })
+      }
+    }
+
+    return { groups, hosts, allNames }
+  }
+
+  async [Symbol.asyncDispose]() {
+    try {
+      for (const [_hash, provider] of this.#providerCache.entries()) {
+        await provider.safeShutdown()
+      }
+    } catch {}
+  }
+}

package/lib/task/controls/environment.control.ts

@@ -0,0 +1,42 @@
+import type { KatmerTask } from "../task"
+import type { Katmer } from "../../interfaces/task.interface"
+import { evalExpr, evalObjectVals } from "../../utils/renderer/renderer"
+import { merge } from "es-toolkit/compat"
+import { mapValues } from "es-toolkit"
+
+const configKey = "environment" as const
+
+export const EnvironmentControl = {
+  order: 10,
+  configKey,
+  register(task: KatmerTask, cfg?: Katmer.TaskRule[typeof configKey]) {
+    task.on("before:execute", async (_task, ctx) => {
+      if (cfg || Object.keys(ctx.provider.environment).length > 0) {
+        const _exec = ctx.exec
+
+        ctx.exec = async (command, options) => {
+          const taskEnv =
+            typeof cfg === "string" ? await evalExpr(cfg, ctx.variables) : cfg
+
+          const env = mapValues(
+            merge(
+              {},
+              ctx.provider.environment,
+              taskEnv || {},
+              options?.env || {}
+            ),
+            (value) =>
+              value !== undefined && value !== null ? String(value) : value
+          )
+
+          return _exec(
+            command,
+            merge({}, options, {
+              env: await evalObjectVals(env, ctx.variables)
+            })
+          )
+        }
+      }
+    })
+  }
+}