@katmer/core 0.0.3

package/lib/modules/http/http.module.ts

@@ -0,0 +1,298 @@
+import { type ModuleCommonReturn } from "../../interfaces/module.interface"
+import { SSHProvider } from "../../providers/ssh/ssh.provider"
+import type { KatmerProvider } from "../../interfaces/provider.interface"
+
+import { HttpModule as HTTPCurlModule } from "./http.curl.module"
+import { HttpModule as HTTPLocalModule } from "./http.local.module"
+
+declare module "../../interfaces/task.interface" {
+  export namespace Katmer {
+    export interface TaskActions {
+      /**
+       * Perform an HTTP(S) request.
+       * See HttpModuleOptions for all parameters.
+       */
+      http?: HttpModuleOptions
+    }
+  }
+}
+
+/**
+ * HTTP methods
+ * @public
+ */
+type HttpMethod =
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+  | "HEAD"
+  | "OPTIONS"
+  | "TRACE"
+  | "CONNECT"
+
+type HttpBasicAuth = {
+  /**
+   * Use Basic authentication.
+   * @defaultValue "basic"
+   */
+  type: "basic"
+  /**
+   * Username used for basic auth.
+   */
+  username: string
+  /**
+   * Password used for basic auth.
+   */
+  password: string
+}
+type HttpBearerAuth = {
+  /**
+   * Use Bearer token authentication.
+   * @defaultValue "bearer"
+   */
+  type: "bearer"
+  /**
+   * Bearer token to send in Authorization header.
+   */
+  token: string
+}
+/**
+ * Authentication configuration.
+ * @public
+ */
+export type HttpAuth = HttpBasicAuth | HttpBearerAuth
+
+/**
+ * Retry configuration.
+ * @public
+ */
+export interface HttpRetry {
+  /**
+   * Total number of retry attempts on transient failures.
+   * Maps to: --retry [tries]
+   */
+  tries?: number
+  /**
+   * Delay in seconds between retries.
+   * Maps to: --retry-delay [seconds]
+   */
+  delay?: number
+  /**
+   * Total time limit in seconds for all retries.
+   * Maps to: --retry-max-time [seconds]
+   */
+  max_time?: number
+}
+
+/**
+ * Output configuration for the response body.
+ * @public
+ */
+export interface HttpOutput {
+  /**
+   * Remote path to save the response body to.
+   * If set, the module writes to a temporary file and atomically moves it into place.
+   */
+  toFile?: string
+  /**
+   * Additionally capture the response body in the module result (body field).
+   * Note: may increase memory usage for large responses.
+   */
+  captureBody?: boolean
+}
+
+/**
+ * Options for the http module.
+ * @public
+ */
+export interface HttpModuleOptions {
+  /**
+   * Target URL
+   */
+  url: string | URL
+  /**
+   * HTTP method to use.
+   * @defaultValue "GET"
+   *
+   * Special handling:
+   * - When method is "HEAD" and writing to file, uses `-X HEAD`.
+   * - When method is "HEAD" and not writing to file, uses `-I`.
+   */
+  method?: HttpMethod
+  /**
+   * Additional HTTP headers to send.
+   * @example
+   * ```ts
+   * headers: { "Accept": "application/json", "User-Agent": "katmer" }
+   * ```
+   */
+  headers?: Record<string, string>
+  /**
+   * Key-value query parameters to append to the URL.
+   * Null or undefined values are skipped.
+   */
+  query?: Record<string, string | number | boolean | null | undefined>
+  /**
+   * Request body.
+   * - If an object is provided, it is JSON-encoded and `Content-Type: application/json` is added unless already set.
+   * - If a string is provided, it is sent via `--data-binary "string"`.
+   * - For binary payloads, prefer {@link HttpModuleOptions.bodyFile | bodyFile}.
+   */
+  body?: string | Record<string, any> | Uint8Array
+  /**
+   * Remote path to a file whose content will be sent via `--data-binary @[file]`.
+   */
+  bodyFile?: string
+  /**
+   * Authentication configuration (basic or bearer).
+   */
+  auth?: HttpAuth
+  /**
+   * Total request timeout in seconds.
+   * Maps to: `--max-time [seconds]`
+   * @defaultValue 30
+   */
+  timeout?: number
+  /**
+   * Follow redirects.
+   * Maps to: `-L`
+   * @defaultValue true
+   */
+  follow_redirects?: boolean
+  /**
+   * Validate TLS certificates. If false, passes `--insecure`.
+   * @defaultValue true
+   */
+  validate_certs?: boolean
+  /**
+   * Output configuration. A string is shorthand for `output.toFile`.
+   */
+  output?: HttpOutput | string
+  /**
+   * Remote path to save response headers.
+   * Maps to: `-D [file]`
+   */
+  save_headers_to?: string
+  /**
+   * Treat non-2xx HTTP codes as fatal.
+   * Maps to: `--fail-with-body`
+   * @defaultValue true
+   */
+  fail_on_http_error?: boolean
+  /**
+   * Retry settings.
+   */
+  retry?: HttpRetry
+  /**
+   * Additional raw arguments to append to the curl command. Only works with Local provider
+   */
+  extra_args?: string[]
+  /**
+   * File mode to set on output file (when `output.toFile` is set).
+   * Accepts octal number (e.g., `0o644`) or string (e.g., `"0644"`).
+   */
+  mode?: string | number
+  /**
+   * File owner to set on the output file (`chown`).
+   */
+  owner?: string
+  /**
+   * File group to set on the output file (`chown`).
+   */
+  group?: string
+}
+
+/**
+ * Result returned by the http module.
+ * @public
+ */
+export interface HttpModuleResult extends ModuleCommonReturn {
+  /**
+   * Parsed whatwg-url URL object.
+   */
+  url: URL
+  /**
+   * Parsed HTTP status code when available (best-effort).
+   */
+  status?: number
+  /**
+   * Raw response headers if saved via {@link HttpModuleOptions.save_headers_to | save_headers_to}.
+   */
+  headers?: Record<string, string | string[]>
+  /**
+   * Response body if `captureBody=true`, or when output is not used and `captureBody=true`.
+   */
+  body?: string
+  /**
+   * Destination path when `output.toFile` (or string shorthand) was used.
+   */
+  dest?: string
+}
+
+/**
+ * Execute HTTP(S) requests.
+ *
+ *
+ * @remarks
+ * - Uses `curl` when running with ssh provider
+ * - Follows redirects by default (`-L`).
+ * - Validates TLS by default; set {@link HttpModuleOptions.validate_certs | validate_certs}: false to pass `--insecure`.
+ * - When {@link HttpModuleOptions.output | output.toFile} is set, writes to a temporary file then moves atomically; `changed=true` on success.
+ * - If {@link HttpModuleOptions.fail_on_http_error | fail_on_http_error} is true (default), non-2xx responses cause a failure using `--fail-with-body`.
+ * - Best-effort status parsing is performed from saved headers or stderr when available.
+ *
+ * @examples
+ * ```yaml
+ * - name: Download a file to a path (like get_url)
+ *   http:
+ *     url: "https://example.com/app.tar.gz"
+ *     output: "/opt/app/app.tar.gz"
+ *     mode: "0644"
+ *
+ * - name: GET JSON with headers and save response headers
+ *   http:
+ *     url: "https://api.example.com/meta"
+ *     headers:
+ *       Accept: "application/json"
+ *     save_headers_to: "/tmp/meta.headers"
+ *     output:
+ *       toFile: "/tmp/meta.json"
+ *       captureBody: true
+ *
+ * - name: POST JSON with bearer token
+ *   http:
+ *     url: "https://api.example.com/resources"
+ *     method: "POST"
+ *     headers:
+ *       Accept: "application/json"
+ *     body:
+ *       name: "demo"
+ *       enabled: true
+ *     auth:
+ *       type: "bearer"
+ *       token: "{{ MY_API_TOKEN }}"
+ *     fail_on_http_error: true
+ *
+ * - name: Download with basic auth
+ *   http:
+ *     url: "https://intranet.local/file.bin"
+ *     auth:
+ *       type: "basic"
+ *       username: "user"
+ *       password: "pass"
+ *     validate_certs: false
+ *     retry:
+ *       tries: 5
+ *       delay: 2
+ * ```
+ * @public
+ */
+export function HttpModule(opts: HttpModuleOptions, provider: KatmerProvider) {
+  if (provider instanceof SSHProvider) {
+    return new HTTPCurlModule(opts, provider)
+  } else {
+    return new HTTPLocalModule(opts, provider)
+  }
+}

package/lib/modules/index.ts

@@ -0,0 +1,14 @@
+export * from "./apt.module"
+export * from "./apt-repository/apt-repository.module"
+export * from "./archive.module"
+export * from "./become.module"
+export * from "./copy.module"
+export * from "./gather_facts.module"
+export * from "./git.module"
+export * from "./debug.module"
+export * from "./http/http.module"
+export * from "./hostname.module"
+export * from "./package.module"
+export * from "./script.module"
+export * from "./set_fact.module"
+export * from "./template.module"

package/lib/modules/package.module.ts

@@ -0,0 +1,283 @@
+import {
+  type ModuleCommonReturn,
+  type ModuleConstraints
+} from "../interfaces/module.interface"
+import type { Katmer } from "../interfaces/task.interface"
+import type { KatmerProvider } from "../interfaces/provider.interface"
+import { KatmerModule } from "../module"
+
+/**
+ * Unified package management module.
+ *
+ * @remarks
+ * This module provides a **single, portable interface** for installing,
+ * updating, or removing packages across different operating systems
+ * and package managers.
+ *
+ * Supported package managers:
+ *
+ * - **Linux**: apt, dnf, yum, pacman, apk, zypper
+ * - **macOS**: brew
+ * - **Windows**: winget, choco
+ *
+ * The module automatically:
+ * - Detects the target OS via {@link KatmerProvider.os}
+ * - Probes for available package managers
+ * - Selects the most appropriate one
+ *
+ * @examples
+ * ```yaml
+ * - name: Install curl
+ *   package:
+ *     name: curl
+ *
+ * - name: Ensure git is removed
+ *   package:
+ *     name: git
+ *     state: absent
+ *
+ * - name: Upgrade docker
+ *   package:
+ *     name: docker
+ *     state: latest
+ *
+ * - name: Install multiple packages
+ *   package:
+ *     name:
+ *       - curl
+ *       - git
+ *       - jq
+ * ```
+ */
+export class PackageModule extends KatmerModule<
+  PackageModuleOptions,
+  PackageModuleResult
+> {
+  static name = "package" as const
+
+  constraints = {
+    platform: {
+      any: true
+    }
+  } satisfies ModuleConstraints
+
+  async check(): Promise<void> {
+    const o = normalizeOptions(this.params)
+    if (!o.name || (Array.isArray(o.name) && o.name.length === 0)) {
+      throw new Error("package: 'name' is required")
+    }
+  }
+
+  async initialize(): Promise<void> {}
+  async cleanup(): Promise<void> {}
+
+  async execute(ctx: Katmer.TaskContext): Promise<PackageModuleResult> {
+    const o = normalizeOptions(this.params)
+    const names = Array.isArray(o.name) ? o.name : [o.name]
+
+    const pm = await detectPackageManager(ctx)
+    if (!pm) {
+      return {
+        changed: false,
+        failed: true,
+        msg: "No supported package manager detected on target"
+      }
+    }
+
+    const cmd = buildCommand(pm, o.state, names)
+    if (!cmd) {
+      return {
+        changed: false,
+        failed: true,
+        msg: `Unsupported operation for package manager: ${pm}`
+      }
+    }
+
+    const r = await ctx.execSafe(cmd)
+
+    return {
+      changed: r.code === 0,
+      failed: r.code !== 0,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      manager: pm
+    }
+  }
+}
+
+/* ───────────────────────────────────────────────────────────── */
+/* Options & Result Types                                        */
+/* ───────────────────────────────────────────────────────────── */
+
+/**
+ * Options for the {@link PackageModule | `package`} module.
+ *
+ * @public
+ */
+export type PackageModuleOptions =
+  | string
+  | {
+      /**
+       * Package name or list of packages.
+       */
+      name: string | string[]
+
+      /**
+       * Desired state of the package(s).
+       *
+       * - `present`: ensure installed (default)
+       * - `absent`: ensure removed
+       * - `latest`: upgrade to latest version
+       *
+       * @defaultValue "present"
+       */
+      state?: "present" | "absent" | "latest"
+    }
+
+/**
+ * Result returned by the {@link PackageModule | `package`} module.
+ *
+ * @public
+ */
+export interface PackageModuleResult extends ModuleCommonReturn {
+  /** Package manager that was used */
+  manager?: PackageManager
+}
+
+/* ───────────────────────────────────────────────────────────── */
+/* Task context augmentation                                     */
+/* ───────────────────────────────────────────────────────────── */
+
+declare module "../interfaces/task.interface" {
+  export namespace Katmer {
+    export interface TaskActions {
+      package?: PackageModuleOptions
+    }
+  }
+}
+
+/* ───────────────────────────────────────────────────────────── */
+/* Internals                                                     */
+/* ───────────────────────────────────────────────────────────── */
+
+type PackageManager =
+  | "apt"
+  | "dnf"
+  | "yum"
+  | "pacman"
+  | "apk"
+  | "zypper"
+  | "brew"
+  | "winget"
+  | "choco"
+
+function normalizeOptions(p: PackageModuleOptions): {
+  name: string | string[]
+  state: "present" | "absent" | "latest"
+} {
+  if (typeof p === "string") {
+    return { name: p, state: "present" }
+  }
+  return {
+    name: p.name,
+    state: p.state ?? "present"
+  }
+}
+
+async function detectPackageManager(
+  ctx: Katmer.TaskContext
+): Promise<PackageManager | null> {
+  const fam = ctx.provider.os.family
+
+  const probes: Array<[PackageManager, string]> = []
+
+  if (fam === "linux") {
+    probes.push(
+      ["apt", "command -v apt-get"],
+      ["dnf", "command -v dnf"],
+      ["yum", "command -v yum"],
+      ["pacman", "command -v pacman"],
+      ["apk", "command -v apk"],
+      ["zypper", "command -v zypper"]
+    )
+  } else if (fam === "darwin") {
+    probes.push(["brew", "command -v brew"])
+  } else if (fam === "windows") {
+    probes.push(["winget", "where winget"], ["choco", "where choco"])
+  }
+
+  for (const [pm, probe] of probes) {
+    const r = await ctx.execSafe(probe)
+    if (r.code === 0) return pm
+  }
+
+  return null
+}
+
+function buildCommand(
+  pm: PackageManager,
+  state: "present" | "absent" | "latest",
+  pkgs: string[]
+): string | null {
+  const list = pkgs.join(" ")
+
+  switch (pm) {
+    case "apt":
+      if (state === "present")
+        return `apt-get update -y && apt-get install -y ${list}`
+      if (state === "latest")
+        return `apt-get update -y && apt-get install -y --only-upgrade ${list}`
+      return `apt-get remove -y ${list}`
+
+    case "dnf":
+      return (
+        state === "absent" ? `dnf remove -y ${list}`
+        : state === "latest" ? `dnf upgrade -y ${list}`
+        : `dnf install -y ${list}`
+      )
+
+    case "yum":
+      return (
+        state === "absent" ? `yum remove -y ${list}`
+        : state === "latest" ? `yum update -y ${list}`
+        : `yum install -y ${list}`
+      )
+
+    case "pacman":
+      return state === "absent" ?
+          `pacman -R --noconfirm ${list}`
+        : `pacman -S --noconfirm ${list}`
+
+    case "apk":
+      return state === "absent" ? `apk del ${list}` : `apk add ${list}`
+
+    case "zypper":
+      return state === "absent" ?
+          `zypper remove -y ${list}`
+        : `zypper install -y ${list}`
+
+    case "brew":
+      return (
+        state === "absent" ? `brew uninstall ${list}`
+        : state === "latest" ? `brew upgrade ${list}`
+        : `brew install ${list}`
+      )
+
+    case "winget":
+      return (
+        state === "absent" ? `winget uninstall --silent ${list}`
+        : state === "latest" ? `winget upgrade --silent ${list}`
+        : `winget install --silent ${list}`
+      )
+
+    case "choco":
+      return (
+        state === "absent" ? `choco uninstall -y ${list}`
+        : state === "latest" ? `choco upgrade -y ${list}`
+        : `choco install -y ${list}`
+      )
+
+    default:
+      return null
+  }
+}

package/lib/modules/script.module.ts

@@ -0,0 +1,121 @@
+import {
+  type ModuleCommonReturn,
+  type ModuleConstraints
+} from "../interfaces/module.interface"
+import type { Katmer } from "../interfaces/task.interface"
+import { evalTemplate } from "../utils/renderer/renderer"
+import type { KatmerProvider } from "../interfaces/provider.interface"
+import { KatmerModule } from "../module"
+
+/**
+ * Execute an ad-hoc shell script on the target.
+ *
+ * @remarks
+ * - Accepts either a **string** (backwards compatible) or an **object** with a `content` string
+ *   and a `render` flag to enable/disable template rendering.
+ * - When `render` is `true` (default), the script string is rendered with Twig against `ctx.variables`
+ *   before execution. When `false`, the string is executed **as-is**.
+ * - Uses the provider's shell via {@link Katmer.TaskContext.exec | `ctx.exec`}.
+ * - Return semantics are simple: `changed` is always `false`; `failed` is set when the exit code is non-zero.
+ * - Standard output and error are surfaced as `stdout` and `stderr`.
+ *
+ * @examples
+ * ```yaml
+ * - name: Simple one-liner (rendering enabled by default):
+ *   script: "echo Hello {{ env | default('world') }}"
+ *
+ * - name: Multi-line script (rendering enabled by default):
+ *   script: |
+ *     set -euo pipefail
+ *     echo "cwd={{ cwd }}"
+ *     ls -la
+ *
+ * - name: Disable templating (execute exactly the given text):
+ *   script:
+ *     content: "echo {{ literally-not-rendered }}"
+ *     render: false
+ *
+ * - name: Conditional logic - restart service in prod
+ *   when: env == 'prod'
+ *   script: "systemctl restart myapp || true"
+ * ```
+ */
+export class ScriptModule extends KatmerModule<
+  ScriptModuleOptions,
+  ScriptModuleResult,
+  KatmerProvider
+> {
+  static name = "script" as const
+
+  constraints = {
+    platform: {
+      any: true
+    }
+  } satisfies ModuleConstraints
+
+  async check(_ctx: Katmer.TaskContext): Promise<void> {
+    const o = normalizeOptions(this.params)
+    if (!o.content || typeof o.content !== "string") {
+      throw new Error("script: 'content' must be a non-empty string")
+    }
+  }
+
+  async initialize(_ctx: Katmer.TaskContext): Promise<void> {}
+  async cleanup(_ctx: Katmer.TaskContext): Promise<void> {}
+
+  async execute(ctx: Katmer.TaskContext): Promise<ScriptModuleResult> {
+    const { content, render } = normalizeOptions(this.params)
+
+    const scriptText =
+      render ? await evalTemplate(content, ctx.variables) : content
+    const r = await ctx.exec(scriptText)
+
+    return {
+      failed: r.code !== undefined && r.code !== 0,
+      changed: false,
+      stdout: r.stdout,
+      stderr: r.stderr
+    }
+  }
+}
+
+/**
+ * You can pass a **raw string** which will be rendered using template engine,
+ * or an **object** to control rendering explicitly.
+ *
+ * @public
+ */
+export type ScriptModuleOptions =
+  | string
+  | {
+      /** Inline script content to execute. */
+      content: string
+      /**
+       * Whether to render the script with Twig against `ctx.variables` before execution.
+       * @defaultValue true
+       */
+      render?: boolean
+    }
+
+/**
+ * Result of the script execution.
+ *
+ * @public
+ */
+export interface ScriptModuleResult extends ModuleCommonReturn {
+  // inherits: changed, failed?, skipped?, msg?, stdout?, stderr?
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// internals
+// ────────────────────────────────────────────────────────────────────────────────
+
+function normalizeOptions(p: ScriptModuleOptions): {
+  content: string
+  render: boolean
+} {
+  if (typeof p === "string") return { content: p, render: true }
+  const content = p?.content ?? ""
+  const render = p?.render ?? true
+  return { content, render }
+}