@katmer/core 0.0.3

package/lib/modules/git.module.ts

@@ -0,0 +1,243 @@
+import fs from "fs-extra"
+import git from "isomorphic-git"
+import http from "isomorphic-git/http/node"
+import {
+  type ModuleCommonReturn,
+  type ModuleConstraints
+} from "../interfaces/module.interface"
+import type { Katmer } from "../interfaces/task.interface"
+import type { KatmerProvider } from "../interfaces/provider.interface"
+import { SSHProvider } from "../providers/ssh/ssh.provider"
+import { LocalProvider } from "../providers/local.provider"
+import { KatmerModule } from "../module"
+
+declare module "../interfaces/task.interface" {
+  export namespace Katmer {
+    export interface TaskActions {
+      git?: GitModuleOptions
+    }
+  }
+}
+/**
+ * Manage Git checkouts on the target machine.
+ *
+ * @remarks
+ * This module is inspired by **Ansible's `ansible.builtin.git`** module.
+ *
+ * Provider behavior:
+ * - **Local provider**:
+ *   - Uses {@link https://isomorphic-git.org | isomorphic-git}
+ *   - Does NOT require system `git`
+ *   - Ideal for controller-side checkouts and reproducible environments
+ *
+ * - **SSH provider**:
+ *   - Uses system-installed `git` on the target host
+ *   - Supports Linux, macOS, and Windows (`git.exe`)
+ *   - Honors `become` and shell handling via provider
+ *
+ * Idempotency:
+ * - `changed=false` when the repository is already at the desired revision
+ * - `changed=true` on clone, checkout, pull, or reset
+ *
+ * @examples
+ * Clone a repository:
+ * ```yaml
+ * - name: Clone repo
+ *   git:
+ *     repo: https://github.com/org/project.git
+ *     dest: /opt/project
+ * ```
+ *
+ * Checkout a specific tag:
+ * ```yaml
+ * - name: Checkout release
+ *   git:
+ *     repo: https://github.com/org/project.git
+ *     dest: /srv/app
+ *     version: v1.4.2
+ * ```
+ *
+ * Force reset to main:
+ * ```yaml
+ * - name: Force sync
+ *   git:
+ *     repo: git@github.com:org/app.git
+ *     dest: /srv/app
+ *     version: main
+ *     force: true
+ * ```
+ */
+export class GitModule extends KatmerModule<
+  GitModuleOptions,
+  GitModuleResult,
+  KatmerProvider
+> {
+  static name = "git" as const
+
+  constraints = {
+    platform: {
+      local: true,
+      any: { packages: ["git"] }
+    }
+  } satisfies ModuleConstraints
+
+  async check(): Promise<void> {
+    if (!this.params?.repo) throw new Error("git: 'repo' is required")
+    if (!this.params?.dest) throw new Error("git: 'dest' is required")
+  }
+
+  async initialize(): Promise<void> {}
+  async cleanup(): Promise<void> {}
+
+  async execute(ctx: Katmer.TaskContext): Promise<GitModuleResult> {
+    const p = normalizeOptions(this.params)
+
+    if (ctx.provider instanceof LocalProvider) {
+      return this.runLocal(ctx, p)
+    }
+
+    if (ctx.provider instanceof SSHProvider) {
+      return this.runSsh(ctx as Katmer.TaskContext<SSHProvider>, p)
+    }
+
+    return {
+      changed: false,
+      failed: true,
+      msg: `git: unsupported provider ${ctx.provider?.constructor?.name}`
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────────
+  // Local (isomorphic-git)
+  // ────────────────────────────────────────────────────────────────────────────────
+
+  private async runLocal(
+    _ctx: Katmer.TaskContext<LocalProvider>,
+    p: NormalizedGitOptions
+  ): Promise<GitModuleResult> {
+    const exists = await fs.pathExists(p.dest)
+    let changed = false
+
+    if (!exists) {
+      await git.clone({
+        fs,
+        http,
+        dir: p.dest,
+        url: p.repo,
+        ref: p.version,
+        depth: p.depth
+      })
+      changed = true
+    } else {
+      const head = await git.resolveRef({ fs, dir: p.dest, ref: "HEAD" })
+      await git.fetch({ fs, http, dir: p.dest, ref: p.version })
+      await git.checkout({ fs, dir: p.dest, ref: p.version })
+      const newHead = await git.resolveRef({ fs, dir: p.dest, ref: "HEAD" })
+      if (head !== newHead) changed = true
+    }
+
+    return {
+      changed,
+      failed: false,
+      revision: await git.resolveRef({ fs, dir: p.dest, ref: "HEAD" })
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────────
+  // SSH (system git)
+  // ────────────────────────────────────────────────────────────────────────────────
+
+  private async runSsh(
+    ctx: Katmer.TaskContext<SSHProvider>,
+    p: NormalizedGitOptions
+  ): Promise<GitModuleResult> {
+    const sh = ctx.provider.os.family === "windows" ? "" : "set -e; "
+    const q = (s: string) => JSON.stringify(s)
+
+    const exists = await ctx.execSafe(`${sh} test -d ${q(p.dest)}/.git`)
+
+    let changed = false
+
+    if (exists.code !== 0) {
+      await ctx.exec(
+        `${sh} git clone ${p.depth ? `--depth ${p.depth}` : ""} ${q(
+          p.repo
+        )} ${q(p.dest)}`
+      )
+      changed = true
+    }
+
+    const revBefore = await ctx.execSafe(
+      `${sh} git -C ${q(p.dest)} rev-parse HEAD`
+    )
+
+    if (p.force) {
+      await ctx.exec(
+        `${sh} git -C ${q(p.dest)} fetch --all && git -C ${q(
+          p.dest
+        )} reset --hard ${q(p.version || "")}`
+      )
+      changed = true
+    } else {
+      await ctx.exec(`${sh} git -C ${q(p.dest)} fetch`)
+      await ctx.exec(`${sh} git -C ${q(p.dest)} checkout ${q(p.version || "")}`)
+    }
+
+    const revAfter = await ctx.execSafe(
+      `${sh} git -C ${q(p.dest)} rev-parse HEAD`
+    )
+
+    if (revBefore.stdout !== revAfter.stdout) changed = true
+
+    return {
+      changed,
+      failed: false,
+      revision: revAfter.stdout?.trim()
+    }
+  }
+}
+
+/* ───────────────────────── Types ───────────────────────── */
+
+/**
+ * Options for the {@link GitModule | `git`} module.
+ *
+ * @public
+ */
+export interface GitModuleOptions {
+  /** Repository URL (HTTPS or SSH). */
+  repo: string
+  /** Destination directory on the target. */
+  dest: string
+  /** Branch, tag, or commit to checkout. */
+  version?: string
+  /** Force reset to the given version. */
+  force?: boolean
+  /** Create a shallow clone with the given depth. */
+  depth?: number
+}
+
+/**
+ * Result of the git operation.
+ *
+ * @public
+ */
+export interface GitModuleResult extends ModuleCommonReturn {
+  /** Final commit hash after execution. */
+  revision?: string
+}
+
+/* ───────────────────────── Internals ───────────────────────── */
+
+type NormalizedGitOptions = Required<Pick<GitModuleOptions, "repo" | "dest">> &
+  Omit<GitModuleOptions, "repo" | "dest">
+
+function normalizeOptions(p: GitModuleOptions): NormalizedGitOptions {
+  return {
+    repo: p.repo,
+    dest: p.dest,
+    version: p.version ?? "HEAD",
+    force: p.force ?? false,
+    depth: p.depth
+  }
+}

package/lib/modules/hostname.module.ts

@@ -0,0 +1,213 @@
+import {
+  type ModuleCommonReturn,
+  type ModuleConstraints
+} from "../interfaces/module.interface"
+import type { Katmer } from "../interfaces/task.interface"
+import type { SSHProvider } from "../providers/ssh/ssh.provider"
+import { KatmerModule } from "../module"
+
+declare module "../interfaces/task.interface" {
+  export namespace Katmer {
+    export interface TaskActions {
+      hostname?: HostnameModuleOptions
+    }
+  }
+}
+
+/**
+ * Get or set the system hostname.
+ *
+ * @remarks
+ * - When no options are provided, the module gathers the current hostname facts and returns them as JSON.
+ * - When "name" is provided, the module sets the transient hostname (runtime) and optionally persists it to the appropriate config
+ *   (e.g., /etc/hostname for most Linux distros or hostnamectl if available).
+ * - The module attempts to be idempotent: if the current hostname already matches the desired one, changed=false.
+ *
+ * @examples
+ * ```yaml
+ * - name: Get hostname facts
+ *   hostname: {}
+ *
+ * - name: Set runtime hostname only
+ *   hostname:
+ *     name: "app-node-01"
+ *
+ * - name: Set and persist hostname
+ *   hostname:
+ *     name: "app-node-01"
+ *     persist: true
+ * ```
+ */
+export class HostnameModule extends KatmerModule<
+  HostnameModuleOptions,
+  HostnameModuleResult,
+  SSHProvider
+> {
+  static name = "hostname" as const
+
+  constraints = {
+    platform: {
+      linux: true,
+      darwin: true,
+      windows: true
+    }
+  } satisfies ModuleConstraints
+
+  async check(_ctx: Katmer.TaskContext<SSHProvider>): Promise<void> {}
+
+  async initialize(_ctx: Katmer.TaskContext<SSHProvider>): Promise<void> {}
+
+  async cleanup(_ctx: Katmer.TaskContext<SSHProvider>): Promise<void> {}
+
+  async execute(
+    ctx: Katmer.TaskContext<SSHProvider>
+  ): Promise<HostnameModuleResult> {
+    const { name, persist = false } = this.params
+
+    const osfam = ctx.provider.os.family
+    const run = async (cmd: string) => {
+      const r = await ctx.exec(cmd)
+      if (r.code !== 0) throw r
+      return r.stdout.trim()
+    }
+
+    // Gather current facts (single roundtrip)
+    const factsCmd = `
+cur_short="$(hostname -s 2>/dev/null || true)"
+cur_fqdn="$(hostname -f 2>/dev/null || hostname 2>/dev/null || true)"
+cur_domain=""
+# Derive domain from FQDN when possible
+case "$cur_fqdn" in
+  *.*) cur_domain="\${cur_fqdn#*.}";;
+  *) cur_domain="";;
+esac
+printf '{"short":"%s","fqdn":"%s","domain":"%s"}' "$cur_short" "$cur_fqdn" "$cur_domain"
+`.trim()
+
+    let changed = false
+    let current: HostnameFacts
+    try {
+      const out = await run(factsCmd)
+      current = JSON.parse(out) as HostnameFacts
+    } catch (e: any) {
+      // Fallback best-effort parse
+      const curShort = await run("hostname -s 2>/dev/null || true")
+      const curFqdn =
+        (await ctx.exec("hostname -f 2>/dev/null")).stdout.trim() ||
+        (await run("hostname 2>/dev/null || true"))
+      const curDomain =
+        curFqdn.includes(".") ? curFqdn.split(".").slice(1).join(".") : ""
+      current = { short: curShort, fqdn: curFqdn, domain: curDomain }
+    }
+
+    if (!name) {
+      // Read-only
+      return {
+        changed: false,
+        facts: current,
+        stdout: JSON.stringify(current)
+      }
+    }
+
+    // Set runtime hostname if needed
+    if (name !== current.short && name !== current.fqdn) {
+      // Prefer hostnamectl when available; otherwise use hostname command
+      const hasHostnamectl =
+        (
+          await ctx.exec("command -v hostnamectl >/dev/null 2>&1; echo $?")
+        ).stdout.trim() === "0"
+      const cmd =
+        hasHostnamectl ?
+          `hostnamectl set-hostname ${JSON.stringify(name)}`
+        : `hostname ${JSON.stringify(name)}`
+      const r = await ctx.exec(cmd)
+      if (r.code !== 0) {
+        throw {
+          changed: false,
+          msg: r.stderr || r.stdout || "failed to set hostname"
+        } satisfies HostnameModuleResult
+      }
+      changed = true
+    }
+
+    // Persist if requested (best-effort, Linux-focused)
+    if (persist) {
+      // If hostnamectl exists, it usually persists. Still ensure /etc/hostname matches for classic systems.
+      const etcHostname = "/etc/hostname"
+      const check = await ctx.exec(
+        `test -w ${JSON.stringify(etcHostname)}; echo $?`
+      )
+      if (check.stdout.trim() === "0") {
+        // Avoid extra change if content already matches
+        const read = await ctx.exec(
+          `cat ${JSON.stringify(etcHostname)} 2>/dev/null || echo ""`
+        )
+        if (read.stdout.trim() !== name.trim()) {
+          const write = await ctx.exec(
+            `printf %s ${JSON.stringify(name.trim())} > ${JSON.stringify(etcHostname)}`
+          )
+          if (write.code !== 0) {
+            throw {
+              changed,
+              msg: write.stderr || write.stdout || "failed to persist hostname"
+            } satisfies HostnameModuleResult
+          }
+          changed = true
+        }
+      }
+    }
+
+    // Re-gather to return final state
+    const finalOut = await run(factsCmd)
+    const facts = JSON.parse(finalOut) as HostnameFacts
+
+    return {
+      changed,
+      facts,
+      stdout: JSON.stringify(facts)
+    }
+  }
+}
+
+/**
+ * Options for hostname module.
+ * @public
+ */
+export interface HostnameModuleOptions {
+  /**
+   * Desired hostname. If omitted, module only gathers current hostname facts.
+   */
+  name?: string
+  /**
+   * Whether to persist the hostname to system config (e.g., /etc/hostname).
+   * @defaultValue false
+   */
+  persist?: boolean
+}
+
+/**
+ * Hostname facts returned by the module.
+ * @public
+ */
+export interface HostnameFacts {
+  /**
+   * Short host name (without domain).
+   */
+  short: string
+  /**
+   * Fully-qualified domain name if resolvable, otherwise the plain hostname.
+   */
+  fqdn: string
+  /**
+   * Derived domain part from FQDN (empty if not applicable).
+   */
+  domain: string
+}
+
+/**
+ * Result of hostname module execution.
+ * @public
+ */
+export interface HostnameModuleResult extends ModuleCommonReturn {
+  facts?: HostnameFacts
+}