@katmer/core 0.0.3

package/lib/utils/http.utils.ts

@@ -0,0 +1,10 @@
+export function parseHeaderString(headerStr: string = "") {
+  const lines = headerStr.trim().split(/\r?\n/)
+  const pairs = lines
+    .filter((l) => l.includes(":"))
+    .map((l) => {
+      const [key, ...rest] = l.split(":")
+      return [key.trim(), rest.join(":").trim()]
+    })
+  return Object.fromEntries(new Headers(pairs))
+}

package/lib/utils/json.utils.ts

@@ -0,0 +1,15 @@
+export function safeJsonParse(input: any) {
+  try {
+    return JSON.parse(input)
+  } catch {
+    return input?.toString()
+  }
+}
+
+export function wrapInArray<T>(input?: T | T[] | null): T[] {
+  return (
+    Array.isArray(input) ? input
+    : input != null ? [input]
+    : []
+  )
+}

package/lib/utils/number.utils.ts

@@ -0,0 +1,9 @@
+export function toOctal<T extends number | string | null | undefined>(
+  mode: T
+): T extends null | undefined ? undefined : string {
+  if (mode === null || mode === undefined) return undefined as any
+  if (typeof mode === "number") {
+    return ("0" + mode.toString(8)) as any
+  }
+  return String(mode).replace(/^0?([0-7]{3,4})$/, "0$1") as any
+}

package/lib/utils/object.utils.ts

@@ -0,0 +1,11 @@
+export function cloneInstance(orig: any) {
+  return Object.assign(Object.create(Object.getPrototypeOf(orig)), orig)
+}
+
+export function isClass(obj: any) {
+  if (typeof obj !== "function") return false
+  const descriptor = Object.getOwnPropertyDescriptor(obj, "prototype")
+  if (!descriptor) return false
+
+  return !descriptor.writable
+}

package/lib/utils/os.utils.ts

@@ -0,0 +1,31 @@
+import type { OsArch } from "../interfaces/provider.interface"
+
+export function normalizeOs(
+  s: string
+): "linux" | "darwin" | "freebsd" | "windows" | "unknown" {
+  const v = s.toLowerCase()
+  if (v.startsWith("linux")) return "linux"
+  if (v.startsWith("darwin") || v.startsWith("mac")) return "darwin"
+  if (v.startsWith("freebsd")) return "freebsd"
+  if (v.startsWith("win") || v.includes("windows")) return "windows"
+  if (v === "win32") return "windows"
+  return "unknown"
+}
+
+export function normalizeArch(a: string): OsArch {
+  const v = a.toLowerCase().trim()
+
+  // common aliases
+  if (["x64", "x86_64", "amd64"].includes(v)) return "x86_64"
+  if (["aarch64", "arm64"].includes(v)) return "arm64"
+  if (["armv7l", "armv7", "armhf"].includes(v)) return "armv7"
+  if (["armv6l", "armv6"].includes(v)) return "armv6"
+  if (["i386", "i686", "ia32"].includes(v)) return "i386"
+  if (["ppc64le"].includes(v)) return "ppc64le"
+  if (["s390x"].includes(v)) return "s390x"
+  if (["riscv64"].includes(v)) return "riscv64"
+  if (["loongarch64"].includes(v)) return "loongarch64"
+
+  // fallback to raw
+  return a as any
+}

package/lib/utils/path.utils.ts

@@ -0,0 +1,9 @@
+export function targetDir(p: string): string {
+  const idx = p.lastIndexOf("/")
+  return idx >= 0 ? p.slice(0, idx) || "/" : "."
+}
+
+export function baseName(p: string): string {
+  const idx = p.lastIndexOf("/")
+  return idx >= 0 ? p.slice(idx + 1) : p
+}

package/lib/utils/renderer/render_functions.ts

@@ -0,0 +1,3 @@
+import { Lookup } from "../../lookup"
+
+export const lookup = Lookup.execute

package/lib/utils/renderer/renderer.ts

@@ -0,0 +1,89 @@
+import TwigEngine, { type TwigOptions } from "./twig"
+
+export async function evalTemplate(
+  template: string,
+  data: Record<string, any> = {},
+  options: Partial<TwigOptions> = {}
+) {
+  return TwigEngine(options)
+    .twig({ async: true, options, data: template })
+    .render(data, undefined, true)
+}
+
+export async function evalExpr(
+  expression: string,
+  variables: Record<string, any> = {},
+  options?: Partial<TwigOptions>
+) {
+  expression = expression.trim()
+  if (expression.startsWith("{{") && expression.endsWith("}}")) {
+    expression = expression.slice(2, -2)
+  }
+  const twig = TwigEngine(options)
+  const compiled = twig.expression.compile({
+    value: expression
+  })
+  const innerOptions = {
+    template: {
+      options: {}
+    }
+  }
+  return await (twig.expression as any)["parseAsync"].call(
+    innerOptions,
+    compiled.stack,
+    variables as any
+  )
+}
+
+export async function evalObjectVals(
+  val: unknown,
+  variables: Record<string, any> = {},
+  options?: Partial<TwigOptions>
+) {
+  return JSON.parse(await evalTemplate(JSON.stringify(val), variables, options))
+}
+
+export async function evalIterative(
+  val: unknown,
+  opts: { scope: Record<string, unknown>; deep?: boolean }
+) {
+  // TODO: configurable twig delimiters
+  if (typeof val === "string") {
+    // Only render if it looks like a template. Otherwise keep literal strings intact.
+    if (/\{\{.*\}\}/.test(val)) {
+      try {
+        return await evalExpr(val, opts.scope)
+      } catch {
+        // If evaluation fails, keep original literal to avoid surprising failures.
+        return val
+      }
+    }
+    return val
+  }
+
+  if (opts.deep === false) return val
+
+  if (Array.isArray(val)) {
+    const out: unknown[] = []
+    for (const item of val) {
+      out.push(await evalIterative(item, opts))
+    }
+    return out
+  }
+
+  if (val && typeof val === "object") {
+    const input = val as Record<string, unknown>
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(input)) {
+      // merge progress into scope to allow left-to-right references
+
+      out[k] = await evalIterative(v, {
+        ...opts,
+        scope: { ...opts.scope, ...out }
+      })
+    }
+    return out
+  }
+
+  return val
+}

package/lib/utils/renderer/twig.ts

@@ -0,0 +1,191 @@
+import type { Twig } from "twig"
+
+import core from "twig/src/twig.core"
+import compiler from "twig/src/twig.compiler"
+import expression from "twig/src/twig.expression"
+import filters from "twig/src/twig.filters"
+import functionsMod from "twig/src/twig.functions"
+import lib from "twig/src/twig.lib"
+import logic from "twig/src/twig.logic"
+import parserSource from "twig/src/twig.parser.source"
+import parserTwig from "twig/src/twig.parser.twig"
+import pathMod from "twig/src/twig.path"
+import testMod from "twig/src/twig.tests"
+import asyncMod from "twig/src/twig.async"
+import exportsMod from "twig/src/twig.exports"
+
+import esToolkit from "es-toolkit/compat"
+
+import * as localFunctions from "./render_functions"
+export interface TwigOptions {
+  delimiters: Partial<{
+    comment: [string, string]
+    block: [string, string]
+    variable: [string, string]
+    interpolation: [string, string]
+  }>
+}
+
+const InstanceCache = {} as Record<string, any>
+export default function (
+  opts: Partial<TwigOptions> = {}
+): Twig["exports"] & { expression: Twig["expression"] } {
+  const k = JSON.stringify(opts)
+  if (InstanceCache[k]) {
+    return InstanceCache[k]
+  }
+
+  const Twig = {
+    VERSION: "1.17.1"
+  } as any
+
+  core(Twig)
+  compiler(Twig)
+  expression(Twig)
+  filters(Twig)
+  functionsMod(Twig)
+  lib(Twig)
+  logic(Twig)
+  parserSource(Twig)
+  parserTwig(Twig)
+  pathMod(Twig)
+  testMod(Twig)
+  asyncMod(Twig)
+  exportsMod(Twig)
+
+  const delimiters = Object.assign(
+    {
+      comment: ["{#", "#}"],
+      block: ["{%", "%}"],
+      variable: ["{{", "}}"],
+      interpolation: ["#{", "}"]
+    },
+    opts.delimiters
+  ) as Required<TwigOptions["delimiters"]>
+
+  Twig.token.definitions = [
+    {
+      type: Twig.token.type.raw,
+      open: `${delimiters.block[0]} raw ${delimiters.block[1]}`,
+      close: `${delimiters.block[0]} endraw ${delimiters.block[1]}`
+    },
+    {
+      type: Twig.token.type.raw,
+      open: `${delimiters.block[0]} verbatim ${delimiters.block[1]}`,
+      close: `${delimiters.block[0]} endverbatim ${delimiters.block[1]}`
+    },
+    // *Whitespace type tokens*
+    //
+    // These typically take the form `{{- expression -}}` or `{{- expression }}` or `{{ expression -}}`.
+    {
+      type: Twig.token.type.outputWhitespacePre,
+      open: `${delimiters.variable[0]}-`,
+      close: `${delimiters.variable[1]}`
+    },
+    {
+      type: Twig.token.type.outputWhitespacePost,
+      open: `${delimiters.variable[0]}`,
+      close: `-${delimiters.variable[1]}`
+    },
+    {
+      type: Twig.token.type.outputWhitespaceBoth,
+      open: `${delimiters.variable[0]}-`,
+      close: `-${delimiters.variable[1]}`
+    },
+    {
+      type: Twig.token.type.logicWhitespacePre,
+      open: `${delimiters.block[0]}-`,
+      close: `${delimiters.block[1]}`
+    },
+    {
+      type: Twig.token.type.logicWhitespacePost,
+      open: `${delimiters.block[0]}`,
+      close: `-${delimiters.block[1]}`
+    },
+    {
+      type: Twig.token.type.logicWhitespaceBoth,
+      open: `${delimiters.block[0]}-`,
+      close: `-${delimiters.block[1]}`
+    },
+    // *Output type tokens*
+    // These typically take the form `{{ expression }}`.
+    {
+      type: Twig.token.type.output,
+      open: `${delimiters.variable[0]}`,
+      close: `${delimiters.variable[1]}`
+    },
+    // *Logic type tokens*
+    // These typically take a form like `{% if expression %}` or `{% endif %}`
+    {
+      type: Twig.token.type.logic,
+      open: delimiters.block[0],
+      close: delimiters.block[1]
+    },
+    // *Comment type tokens*
+    // These take the form `{# anything #}`
+    {
+      type: Twig.token.type.comment,
+      open: delimiters.comment[0],
+      close: delimiters.comment[1]
+    }
+  ]
+
+  Twig.functions["indent"] = Twig.filters["indent"] = function (
+    text?: string,
+    params: any[] = []
+  ) {
+    const [count = 2] = params
+    const spaces = " ".repeat(count)
+
+    return text
+      ?.split("\n")
+      .map((line) => (line ? spaces + line : line))
+      .join("\n")
+  }
+
+  Twig.filter = function (filter: string, value: any, params = []) {
+    if (filter === "replaceAll") {
+      return value.replaceAll(...params)
+    }
+    if (
+      filter in esToolkit &&
+      typeof (esToolkit as any)[filter] === "function"
+    ) {
+      return (esToolkit as any)[filter](
+        value,
+        ...(typeof params === "object" ? params : [params])
+      )
+    }
+    if (!Twig.filters[filter]) {
+      throw new Twig.Error("Unable to find filter " + filter)
+    }
+    return Twig.filters[filter].call(this, value, params || [])
+  }
+
+  Twig.functions = new Proxy(
+    { ...Twig.functions },
+    {
+      get(target, prop) {
+        if (
+          prop in localFunctions &&
+          typeof (localFunctions as any)[prop] === "function"
+        ) {
+          return (localFunctions as any)[prop]
+        }
+        if (
+          prop in esToolkit &&
+          typeof (esToolkit as any)[prop] === "function"
+        ) {
+          return (esToolkit as any)[prop]
+        }
+        if (target[prop]) {
+          return target[prop]
+        }
+        return undefined
+      }
+    }
+  )
+  Twig.exports["expression"] = Twig.expression
+  InstanceCache[k] = Twig.exports
+  return Twig.exports
+}

package/lib/utils/string.utils.ts

@@ -0,0 +1,33 @@
+export function parseLines(content: string, keepEmpty = false): string[] {
+  const lines = content.split(/\r?\n/)
+
+  if (keepEmpty) return lines
+
+  return lines.map((l) => l.trim()).filter((l) => l.length > 0)
+}
+
+export function normalizeLine(line: string): string {
+  return line.replace(/\s+/g, " ").trim()
+}
+
+export function stringifyLines(lines: string[]): string {
+  return lines.join("\n") + "\n"
+}
+
+/**
+ * Shell-safe quoting via JSON stringification.
+ * @param v String to quote
+ * @internal
+ */
+export function quote(v: string) {
+  return JSON.stringify(v)
+}
+
+const escapeRegex = (str: string) =>
+  str.replace(/([.*+?^=!:${}()|\[\]\/\\])/g, "\\$1")
+
+export function wildcardMatch(str: string, rule: string) {
+  return new RegExp(
+    "^" + rule.split("*").map(escapeRegex).join(".*") + "$"
+  ).test(str)
+}

package/lib/utils/typed-event-emitter.ts

@@ -0,0 +1,26 @@
+import { EventEmitter } from "node:events"
+
+export class TypedEventEmitter<TEvents extends Record<string, any>> {
+  private emitter = new EventEmitter()
+
+  emit<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    ...eventArg: TEvents[TEventName]
+  ) {
+    this.emitter.emit(eventName, ...(eventArg as []))
+  }
+
+  on<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    handler: (...eventArg: TEvents[TEventName]) => void
+  ) {
+    this.emitter.on(eventName, handler as any)
+  }
+
+  off<TEventName extends keyof TEvents & string>(
+    eventName: TEventName,
+    handler: (...eventArg: TEvents[TEventName]) => void
+  ) {
+    this.emitter.off(eventName, handler as any)
+  }
+}

package/lib/utils/unix.utils.ts

@@ -0,0 +1,91 @@
+import type { SSHProvider } from "../providers/ssh/ssh.provider"
+import { baseName, targetDir } from "./path.utils"
+import { toOctal } from "./number.utils"
+import type { Katmer } from "../interfaces/task.interface"
+
+export const UnixComms = {
+  escapePOSIX(s: string): string {
+    return s.replace(/(["$`\\])/g, "\\$1")
+  },
+  async fileExists(ctx: Katmer.TaskContext<SSHProvider>, p: string) {
+    const r = await ctx.execSafe(`test -e ${JSON.stringify(p)}`)
+    return r.code === 0
+  },
+  /**
+   * Checks for the existence of one or more commands on the remote system in a single operation.
+   * @param {any} ctx - Katmer task context.
+   * @param {string[]} commands - An array of command names to check (e.g., ["git", "node", "npm"]).
+   * @returns {Promise<string[]>} A promise that resolves to an array of the command names that were NOT found.
+   * An empty array means all commands were found.
+   */
+  async findMissingCommands(
+    ctx: Katmer.TaskContext<any>,
+    commands: string[]
+  ): Promise<string[]> {
+    if (!commands || commands.length === 0) {
+      return []
+    }
+
+    const commandList = commands.join(" ")
+    const checkScript = `for cmd in ${commandList}; do command -v "$cmd" >/dev/null 2>&1 || echo "$cmd"; done`
+
+    const { stdout } = await ctx.exec(checkScript)
+
+    return stdout
+      .split("\n")
+      .map((s: string) => s.trim())
+      .filter(Boolean)
+  },
+
+  async mkdirp(ctx: Katmer.TaskContext<any>, dir: string): Promise<void> {
+    await ctx.execSafe(`bash -lc 'mkdir -p "${dir}"'`)
+  },
+
+  async pathIsFile(ctx: Katmer.TaskContext<any>, p: string): Promise<boolean> {
+    const { code } = await ctx.execSafe(`bash -lc '[ -f "${p}" ]'`)
+    return code === 0
+  },
+  async pathIsSymlink(
+    ctx: Katmer.TaskContext<any>,
+    p: string
+  ): Promise<boolean> {
+    const { code } = await ctx.execSafe(`bash -lc '[ -L "${p}" ]'`)
+    return code === 0
+  },
+  async readFileUtf8(ctx: Katmer.TaskContext<any>, p: string): Promise<string> {
+    const { code, stdout } = await ctx.execSafe(
+      `bash -lc '[[ -f "${p}" ]] && cat "${p}" || true'`
+    )
+    if (code !== 0) return ""
+    return stdout
+  },
+  async readlink(
+    ctx: Katmer.TaskContext<any>,
+    p: string
+  ): Promise<string | null> {
+    const { code, stdout } = await ctx.execSafe(
+      `bash -lc 'readlink "${p}" || true'`
+    )
+    return code === 0 ? stdout.trim() : null
+  },
+  async removePath(ctx: Katmer.TaskContext<any>, p: string): Promise<void> {
+    await ctx.execSafe(`bash -lc 'rm -f "${p}" || true'`)
+  },
+  async writeFileAtomic(
+    ctx: Katmer.TaskContext<any>,
+    target: string,
+    content: string,
+    mode?: number
+  ): Promise<void> {
+    const dir = targetDir(target)
+    const base = baseName(target)
+    const tmp = `${dir}/.${base}.${Date.now()}.${Math.random().toString(36).slice(2)}`
+    await ctx.exec(
+      `bash -lc 'set -euo pipefail; dir="${UnixComms.escapePOSIX(dir)}"; tmp="${UnixComms.escapePOSIX(tmp)}"; target="${UnixComms.escapePOSIX(
+        target
+      )}"; mkdir -p "$dir"; : > "$tmp"; cat > "$tmp" << "EOF"\n${content}EOF\n${
+        mode != null ? `chmod ${toOctal(mode)} "$tmp"` : ""
+      }\nmv -f "$tmp" "$target"'`
+    )
+  }
+}

package/lib/utils/windows.utils.ts

@@ -0,0 +1,92 @@
+import type { SSHProvider } from "../providers/ssh/ssh.provider"
+import type { Katmer } from "../interfaces/task.interface"
+
+export const WindowsComms = {
+  /**
+   * Basic PowerShell string literal quoting using single quotes.
+   * Single quotes inside get doubled per PowerShell rules.
+   */
+  psQuote(s: string): string {
+    return "'" + String(s).replace(/'/g, "''") + "'"
+  },
+
+  async fileExists(ctx: Katmer.TaskContext<SSHProvider>, p: string) {
+    const q = this.psQuote(p)
+    const cmd = `powershell -NoProfile -NonInteractive -Command "if (Test-Path -LiteralPath ${q}) { exit 0 } else { exit 1 }"`
+    const r = await ctx.exec(cmd)
+    return r.code === 0
+  },
+
+  async ensureDir(ctx: Katmer.TaskContext<SSHProvider>, dir: string) {
+    const q = this.psQuote(dir)
+    const cmd = `powershell -NoProfile -NonInteractive -Command "New-Item -ItemType Directory -Force -Path ${q} | Out-Null"`
+    const r = await ctx.exec(cmd)
+    if (r.code !== 0) throw new Error(r.stderr || "ensureDir failed")
+  },
+
+  async sha256File(ctx: Katmer.TaskContext<SSHProvider>, p: string) {
+    const q = this.psQuote(p)
+    const cmd = `powershell -NoProfile -NonInteractive -Command "if (Test-Path -LiteralPath ${q}) { (Get-FileHash -Algorithm SHA256 -LiteralPath ${q}).Hash }"`
+    const r = await ctx.exec(cmd)
+    if (r.code === 0) {
+      const h = (r.stdout || "").trim()
+      return h ? h.toLowerCase() : null
+    }
+    return null
+  },
+
+  /**
+   * Stage bytes from base64 into a file atomically.
+   */
+  async writeBase64ToFile(
+    ctx: Katmer.TaskContext<SSHProvider>,
+    dest: string,
+    base64: string
+  ) {
+    const qDest = this.psQuote(dest)
+    const qB64 = this.psQuote(base64)
+    const script = [
+      "param($p,$b)",
+      "$dir = Split-Path -LiteralPath $p -Parent",
+      "$tmp = [System.IO.Path]::Combine($dir, [System.IO.Path]::GetRandomFileName())",
+      "[IO.File]::WriteAllBytes($tmp, [Convert]::FromBase64String($b))",
+      "Move-Item -Force -LiteralPath $tmp -Destination $p"
+    ].join("; ")
+    const cmd = `powershell -NoProfile -NonInteractive -Command "${script}" -p ${qDest} -b ${qB64}`
+    const r = await ctx.exec(cmd)
+    if (r.code !== 0) throw new Error(r.stderr || "writeBase64ToFile failed")
+  },
+
+  async copyFile(
+    ctx: Katmer.TaskContext<SSHProvider>,
+    src: string,
+    dest: string
+  ) {
+    const qSrc = this.psQuote(src)
+    const qDest = this.psQuote(dest)
+    const cmd = `powershell -NoProfile -NonInteractive -Command "Copy-Item -Force -LiteralPath ${qSrc} -Destination ${qDest}"`
+    const r = await ctx.exec(cmd)
+    if (r.code !== 0) throw new Error(r.stderr || "copyFile failed")
+  },
+
+  async moveFile(
+    ctx: Katmer.TaskContext<SSHProvider>,
+    src: string,
+    dest: string
+  ) {
+    const qSrc = this.psQuote(src)
+    const qDest = this.psQuote(dest)
+    const cmd = `powershell -NoProfile -NonInteractive -Command "Move-Item -Force -LiteralPath ${qSrc} -Destination ${qDest}"`
+    const r = await ctx.exec(cmd)
+    if (r.code !== 0) throw new Error(r.stderr || "moveFile failed")
+  },
+
+  async backupIfExists(ctx: Katmer.TaskContext<SSHProvider>, dest: string) {
+    const exists = await this.fileExists(ctx, dest)
+    if (!exists) return null
+    const ts = Date.now()
+    const bak = `${dest}.bak.${ts}`
+    await this.copyFile(ctx, dest, bak)
+    return bak
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@katmer/core",
+  "module": "index.ts",
+  "description": "Manage your infrastructure with ease.",
+  "version": "0.0.3",
+  "main": "index.ts",
+  "type": "module",
+  "types": "index.ts",
+  "repository": {
+    "url": "https://github.com/katmer-io/katmer",
+    "directory": "packages/core"
+  },
+  "bin": {
+    "katmer": "cli/katmer.js"
+  },
+  "exports": {
+    "bun": "./index.ts"
+  },
+  "files": [
+    "cli",
+    "lib/interfaces",
+    "lib",
+    "index.ts"
+  ],
+  "scripts": {
+    "build": "bun ./scripts/build.ts",
+    "dev:server": "bun run --watch index.ts",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@fastify/deepmerge": "^3.1.0",
+    "adm-zip": "^0.5.16",
+    "ajv": "^8.17.1",
+    "ajv-errors": "^3.0.0",
+    "commander": "^14.0.2",
+    "convict": "^6.2.4",
+    "es-toolkit": "^1.43.0",
+    "fast-equals": "^6.0.0",
+    "fs-extra": "^11.3.3",
+    "isomorphic-git": "^1.36.1",
+    "json5": "^2.2.3",
+    "jsrsasign": "^11.1.0",
+    "lodash": "^4.17.21",
+    "node-ssh": "^13.2.1",
+    "pino": "^10.1.1",
+    "pino-pretty": "^13.1.3",
+    "semver": "^7.7.3",
+    "ssh2": "^1.17.0",
+    "stable-hash": "^0.0.6",
+    "twig": "^1.17.1",
+    "uint8array-extras": "^1.5.0",
+    "validator": "^13.15.26"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.5",
+    "@types/convict": "^6.1.6",
+    "@types/semver": "^7.7.1",
+    "@types/ssh2": "^1.15.5",
+    "@types/twig": "^1.12.17"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}