@katmer/core 0.0.3

package/lib/task/controls/index.ts

@@ -0,0 +1,13 @@
+import { LoopControl } from "./loop.control"
+import { RegisterControl } from "./register.control"
+import { WhenControl } from "./when.control"
+import { UntilControl } from "./until.control"
+import { sortBy } from "es-toolkit"
+import { EnvironmentControl } from "./environment.control"
+
+export const TaskControls = sortBy(
+  [LoopControl, RegisterControl, WhenControl, UntilControl, EnvironmentControl],
+  ["order"]
+)
+
+export const TaskControlKeys = TaskControls.map((ctrl) => ctrl.configKey)

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

@@ -0,0 +1,89 @@
+import type { Katmer } from "../../interfaces/task.interface"
+import { defaults, isObjectLike } from "es-toolkit/compat"
+import { wrapInArray } from "../../utils/json.utils"
+import type { KatmerTask } from "../task"
+import { evalExpr } from "../../utils/renderer/renderer"
+import type { ModuleCommonReturn } from "../../interfaces/module.interface"
+
+const configKey = "loop" as const
+export const LoopControl = {
+  order: 100,
+  configKey,
+  register(task: KatmerTask, cfg?: Katmer.TaskRule[typeof configKey]) {
+    if (cfg) {
+      const control = defaults(
+        cfg && typeof cfg === "object" && "for" in cfg ?
+          cfg
+        : {
+            for: (cfg || []) as string[] | string
+          },
+        {
+          for: [] as string[],
+          index_var: "index",
+          break_when: [] as string[],
+          loop_var: "item",
+          extended: false,
+          extended_allitems: true
+        } satisfies Katmer.LoopControl
+      )
+      control.break_when = wrapInArray(control.break_when)
+
+      const baseExecute = task.execute
+      task.execute = async function runWithLoop(ctx: Katmer.TaskContext) {
+        ctx.logger.trace(`[loop] start`)
+        const loops =
+          typeof control.for === "string" ? await evalExpr(control.for)
+          : isObjectLike(control.for) ? control.for
+          : []
+
+        const loopEntries = Object.entries(loops)
+        const loopItems = Object.values(loops)
+        const loopResults = {
+          changed: false,
+          skipped: undefined as boolean | undefined,
+          failed: false,
+          results: [] as (ModuleCommonReturn | { skipped: true })[]
+        }
+        taskLoop: for (let i = 0; i < loopEntries.length; i++) {
+          const [loop_key, loop_val] = loopEntries[i]
+          ctx.variables[control.index_var] = loop_key
+          ctx.variables[control.loop_var] = loop_val
+
+          if (control.extended) {
+            ctx.variables.katmer_loop = {
+              allitems: control.extended_allitems ? loopItems : undefined,
+              index: i + 1,
+              index0: i,
+              revindex: loopItems.length - i,
+              revindex0: loopItems.length - i - 1,
+              first: i === 0,
+              last: i === loopItems.length - 1,
+              length: loopItems.length,
+              previtem: loopItems[i - 1],
+              nextitem: loopItems[i + 1]
+            }
+          }
+          ctx.logger.trace(`[loop] ${i} ${loop_key} ${loop_val}`)
+          const result = await baseExecute.call(task, ctx)
+
+          if (result) {
+            result.item = loop_val
+            loopResults.changed = loopResults.changed || result.changed
+            loopResults.failed = loopResults.failed || !!result.failed
+            loopResults.skipped = !!(result.skipped && loopResults.skipped)
+            loopResults.results.push(result)
+          }
+
+          for (const condition of control.break_when) {
+            if (await evalExpr(condition, ctx.variables)) {
+              break taskLoop
+            }
+          }
+        }
+        ctx.logger.trace(`[loop] end`)
+
+        return loopResults
+      }
+    }
+  }
+}

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

@@ -0,0 +1,23 @@
+import type { KatmerTask } from "../task"
+import type { Katmer } from "../../interfaces/task.interface"
+
+const configKey = "register" as const
+
+export const RegisterControl = {
+  order: 1000,
+  configKey,
+  register(task: KatmerTask, cfg?: Katmer.TaskRule[typeof configKey]) {
+    if (cfg) {
+      const baseExecute = task.execute
+      task.execute = async function registerResult(ctx: Katmer.TaskContext) {
+        ctx.logger.trace(`[register] start`)
+
+        const result = await baseExecute.call(task, ctx)
+        ctx.variables[cfg] = result
+
+        ctx.logger.trace(`[register] end`)
+        return result
+      }
+    }
+  }
+}

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

@@ -0,0 +1,64 @@
+import type { KatmerTask } from "../task"
+import type { Katmer } from "../../interfaces/task.interface"
+import { evalExpr } from "../../utils/renderer/renderer"
+import { delay } from "es-toolkit"
+import type { ModuleCommonReturn } from "../../interfaces/module.interface"
+
+const configKey = "until" as const
+
+export const UntilControl = {
+  order: 50,
+  configKey,
+  register(task: KatmerTask, cfg?: Katmer.TaskRule[typeof configKey]) {
+    if (cfg) {
+      const control =
+        cfg && typeof cfg === "object" ?
+          cfg
+        : {
+            condition: cfg || ""
+          }
+      const baseExecute = task.execute
+      task.execute = async function runUntil(ctx: Katmer.TaskContext) {
+        let shouldRun = false
+        let attempts = 0
+        let result = {} as ModuleCommonReturn
+        do {
+          result = Object.assign(
+            result || {},
+            await baseExecute.call(task, ctx)
+          )
+
+          if (control.condition) {
+            const untilResult = await evalExpr(control.condition, ctx.variables)
+            if (untilResult) {
+              shouldRun = false
+            } else {
+              if (control.retries && attempts === control.retries + 1) {
+                shouldRun = false
+                break
+              }
+
+              if (!result) {
+                result = {} as any
+              }
+              result.retries = control.retries
+              result.attempts = attempts++
+              ctx.log("error", {
+                msg: `[FAILED]`,
+                result: result
+              })
+              if (control.delay) {
+                await delay(control.delay)
+              }
+            }
+          } else {
+            ctx.log("debug", "Condiiton failed")
+            shouldRun = false
+          }
+        } while (shouldRun)
+
+        return result
+      }
+    }
+  }
+}

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

@@ -0,0 +1,25 @@
+import type { KatmerTask } from "../task"
+import type { Katmer } from "../../interfaces/task.interface"
+import { evalExpr } from "../../utils/renderer/renderer"
+
+const configKey = "when" as const
+
+export const WhenControl = {
+  order: 10,
+  configKey,
+  register(task: KatmerTask, cfg?: Katmer.TaskRule[typeof configKey]) {
+    if (cfg) {
+      const baseExecute = task.execute
+      task.execute = async function runWhen(ctx: Katmer.TaskContext) {
+        const whenResult = await evalExpr(cfg, ctx.variables)
+        if (!whenResult) {
+          return {
+            changed: false,
+            skipped: true
+          }
+        }
+        return await baseExecute.call(task, ctx)
+      }
+    }
+  }
+}

package/lib/task/task.ts

@@ -0,0 +1,225 @@
+import type { Katmer } from "../katmer"
+import { type KatmerCore } from "../katmer"
+import type { KatmerTargetResolver } from "../target_resolver"
+import { wrapInArray } from "../utils/json.utils"
+import type { ModuleCommonReturn } from "../interfaces/module.interface"
+import { omit, toMerged } from "es-toolkit"
+import type { KatmerProvider } from "../interfaces/provider.interface"
+import { TaskControlKeys, TaskControls } from "./controls"
+import { msToDelta, nowIso } from "../utils/datetime.utils"
+import {
+  evalExpr,
+  evalObjectVals,
+  evalTemplate
+} from "../utils/renderer/renderer"
+import { merge } from "es-toolkit/compat"
+import { TypedEventEmitter } from "../utils/typed-event-emitter"
+import { AsyncLocalStorage } from "node:async_hooks"
+import { cls } from "../utils/cls"
+import { ExecutionFailedError, TaskExecutionFailedError } from "../utils/errors"
+import type { KatmerModule } from "../module"
+
+export class KatmerTask extends TypedEventEmitter<{
+  "before:execute": [KatmerTask, Katmer.TaskContext]
+  "module:check": [KatmerTask, Katmer.TaskContext, KatmerModule]
+  "module:init": [KatmerTask, Katmer.TaskContext, KatmerModule]
+  "module:execute": [
+    KatmerTask,
+    Katmer.TaskContext,
+    KatmerModule,
+    ModuleCommonReturn
+  ]
+  "after:execute": [KatmerTask, Katmer.TaskContext, ModuleCommonReturn]
+}> {
+  variables = {} as Record<string, any>
+  modules = [] as [string, any][]
+  targets: string[]
+
+  constructor(
+    public core: KatmerCore,
+    public targetResolver: KatmerTargetResolver,
+    public cfg: Katmer.Task
+  ) {
+    super()
+    const taskModules = omit(cfg, [
+      "name",
+      "become",
+      "targets",
+      "variables",
+      ...TaskControlKeys
+    ])
+
+    this.modules = this.normalizeModules(taskModules)
+
+    // TODO: use better way for internal modules
+    if (cfg.become) {
+      this.modules.unshift(["become", cfg.become])
+    }
+
+    this.variables = cfg.variables || {}
+    this.targets = wrapInArray(cfg.targets)
+
+    for (const taskControl of TaskControls) {
+      taskControl.register(this, cfg[taskControl.configKey] as any)
+    }
+  }
+
+  async run(context: Record<string, any> = {}) {
+    for (const target of this.targets) {
+      const providers = this.targetResolver.resolveTargets(target)
+
+      for (const runFor of providers) {
+        const provider = await this.targetResolver.resolveProvider(runFor)
+        await this.runForProvider(provider, context)
+      }
+    }
+  }
+
+  async runForProvider(
+    provider: KatmerProvider,
+    context: Record<string, any> = {}
+  ) {
+    await provider.ensureReady()
+    const ctx = this.generateTaskContext(provider, context)
+    return await cls.run(ctx, async () => {
+      return await this.execute(ctx)
+    })
+  }
+
+  async execute(ctx: Katmer.TaskContext) {
+    this.emit("before:execute", this, ctx)
+
+    let lastResult: any
+
+    const modules = [] as KatmerModule[]
+    for (const [moduleName, moduleParams] of this.modules) {
+      modules.push(
+        this.core.registry.get(moduleName, moduleParams) as KatmerModule
+      )
+    }
+
+    for (const module of modules) {
+      await module.doCheck(ctx)
+      this.emit("module:check", this, ctx, module)
+
+      ctx.logger.trace(`Initializing module`)
+      await module.doInitialize?.(ctx)
+      this.emit("module:init", this, ctx, module)
+
+      ctx.logger.trace(`Executing module`)
+
+      // Per-module timing
+      const startAt = Date.now()
+      const startIso = nowIso()
+
+      try {
+        const res = await module.doExecute(ctx)
+        const endAt = Date.now()
+        const endIso = nowIso()
+
+        // Ensure ModuleCommonReturn core fields are present if missing
+        if (res.changed === undefined) res.changed = false
+        if (res.failed === undefined) res.failed = false
+
+        if (!res.start) res.start = startIso
+        if (!res.end) res.end = endIso
+        if (!res.delta) {
+          // If module supplied start/end, honor them; otherwise compute
+          const started = Date.parse(res.start || startIso) || startAt
+          const ended = Date.parse(res.end || endIso) || endAt
+          res.delta = msToDelta(ended - started)
+        }
+
+        lastResult = res
+      } catch (err: any) {
+        const endAt = Date.now()
+        const endIso = nowIso()
+
+        // Convert thrown error into ModuleCommonReturn shape
+        lastResult = {
+          changed: false,
+          failed: true,
+          msg:
+            typeof err === "string" ? err : (
+              err?.message || err?.msg || "Task failed"
+            ),
+          stdout: err?.stdout,
+          stderr: err?.stderr,
+          start: startIso,
+          end: endIso,
+          delta: msToDelta(endAt - startAt)
+        }
+        // Stop at the first failure (keeps current behavior of bubbling errors)
+        break
+      } finally {
+        this.emit("module:execute", this, ctx, module, lastResult)
+      }
+    }
+
+    if (lastResult.failed) {
+      throw new TaskExecutionFailedError(this, lastResult)
+    } else {
+      ctx.logger.info({ msg: "Task finished", result: lastResult })
+    }
+
+    this.emit("after:execute", this, ctx, lastResult)
+    return lastResult
+  }
+
+  protected normalizeModules(modules: Record<string, unknown>) {
+    const registered = [] as [string, any][]
+
+    const moduleEntries = Object.entries(modules)
+    if (moduleEntries.length === 0) {
+      throw new Error("No modules encountered in the task")
+    }
+    if (moduleEntries.length > 1) {
+      throw new Error("Only one module is allowed in the task")
+    }
+
+    const [moduleName, moduleParams] = moduleEntries[0]
+    if (this.core.registry.has(moduleName)) {
+      registered.push([moduleName, moduleParams])
+    } else {
+      throw new Error(`Unknown module encountered: ${moduleName}`)
+    }
+    return registered
+  }
+
+  generateTaskContext<Provider extends KatmerProvider>(
+    provider: Provider,
+    context: Record<string, any> = {}
+  ): Katmer.TaskContext<Provider> {
+    const logger = provider.logger.child({ task: this.cfg.name || "" })
+
+    return {
+      config: this.core.config,
+      exec: provider.executor(),
+      async execSafe(...args: [any, any]) {
+        try {
+          return (await this.exec(...args)) as any
+        } catch (err: any) {
+          return err
+        }
+      },
+      fail(msg: string | { message: string }): never {
+        throw msg
+      },
+      log(
+        level: "fatal" | "error" | "warn" | "info" | "debug" | "trace",
+        message: any
+      ): void {
+        logger[level](message)
+      },
+      logger: logger,
+      progress(data) {
+        console.info("Progress:", data)
+      },
+      provider,
+      variables: merge(context, this.variables || {}),
+      warn(opts: { message: string } | string): void {
+        console.warn("WARN", opts)
+      }
+    }
+  }
+}

package/lib/utils/ajv.utils.ts

@@ -0,0 +1,24 @@
+import type { ErrorObject } from "ajv"
+
+export function normalizeAjvError(error: ErrorObject): string {
+  let message: string
+  error.message = error.message?.toLowerCase()
+  const objPath = error.instancePath?.replace("/", "").replaceAll("/", ".")
+
+  if (error.keyword === "pattern") {
+    message = `"${objPath}" contains invalid characters`
+  } else if (error.message?.startsWith("must ") && error.instancePath!.length) {
+    message = `"${objPath || ""}" ${error.message}`
+  } else {
+    message = error.message!
+  }
+
+  if (
+    error.keyword === "additionalProperties" &&
+    error.params?.additionalProperty
+  ) {
+    message = `${message}: "${error.params.additionalProperty}"`
+  }
+
+  return message
+}

package/lib/utils/cls.ts

@@ -0,0 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { Katmer } from "../interfaces/task.interface"
+
+export const cls = new AsyncLocalStorage<Katmer.TaskContext>()

package/lib/utils/datetime.utils.ts

@@ -0,0 +1,15 @@
+export function nowIso(): string {
+  return new Date().toISOString()
+}
+export function msToDelta(ms: number): string {
+  // format: H:MM:SS.mmm  (e.g., "0:00:00.123")
+  const sign = ms < 0 ? "-" : ""
+  ms = Math.abs(ms)
+  const h = Math.floor(ms / 3600000)
+  const m = Math.floor((ms % 3600000) / 60000)
+  const s = Math.floor((ms % 60000) / 1000)
+  const msRest = ms % 1000
+  const pad2 = (n: number) => n.toString().padStart(2, "0")
+  const pad3 = (n: number) => n.toString().padStart(3, "0")
+  return `${sign}${h}:${pad2(m)}:${pad2(s)}.${pad3(msRest)}`
+}

package/lib/utils/errors.ts

@@ -0,0 +1,25 @@
+import type { ProviderResponse } from "../providers/provider_response"
+import type { Katmer } from "../katmer"
+import type { KatmerTask } from "../task/task"
+
+export class KatmerError extends Error {}
+export class ExecutionFailedError extends KatmerError {
+  constructor(
+    public result: ProviderResponse,
+    public message = "Execution failed"
+  ) {
+    super(message)
+  }
+}
+
+export class TaskExecutionFailedError extends ExecutionFailedError {
+  task: string | undefined
+  constructor(
+    task: KatmerTask,
+    public result: ProviderResponse,
+    public message = "Task execution failed"
+  ) {
+    super(result, message)
+    this.task = task.cfg.name
+  }
+}

package/lib/utils/execute-shell.ts

@@ -0,0 +1,116 @@
+import { uint8ArrayToString } from "uint8array-extras"
+import { safeJsonParse } from "./json.utils"
+
+export async function executeScript<T extends boolean = false>(
+  scriptContents: string,
+  opts: {
+    /**
+     * Parse stdout/stderr as json. If not valid json the data will be available in `.message`
+     */
+    json?: T
+    /**
+     * If provided will be called with each line of script stdout
+     */
+    stream?: (
+      err?: (T extends true ? any : string) | null,
+      data?: (T extends true ? any : string) | null
+    ) => void
+  } = {}
+) {
+  const command = Bun.spawn(["bash", "-s", "<", "<(cat)"], {
+    stdin: new Response(scriptContents),
+    stdout: "pipe",
+    stderr: "pipe"
+  })
+
+  if (opts.stream) {
+    command.stdout.pipeTo(
+      new WritableStream({
+        write(log) {
+          if (log.length) {
+            const str = uint8ArrayToString(log).trim()
+            if (str) {
+              opts.stream?.(undefined, opts.json ? safeJsonParse(str) : str)
+            }
+          }
+        }
+      })
+    )
+
+    command.stderr.pipeTo(
+      new WritableStream({
+        write(log) {
+          const str = uint8ArrayToString(log).trim()
+          if (str) {
+            opts.stream?.(opts.json ? safeJsonParse(str) : str)
+          }
+        }
+      })
+    )
+  }
+
+  const failed = (await command.exited) !== 0
+
+  if (!opts.stream) {
+    let stdout = await new Response(command.stdout).text()
+    let stderr = await new Response(command.stderr).text()
+    if (opts.json) {
+      stdout = safeJsonParse(stdout)
+      stderr = safeJsonParse(stderr)
+    }
+
+    if (failed) {
+      throw stderr
+    }
+    return stdout
+  }
+}
+
+export async function executeShellCommand(cmd: string) {
+  try {
+    const command = Bun.spawn(cmd.split(" "), {
+      stdout: "pipe",
+      stderr: "pipe"
+    })
+
+    const output = {
+      code: null as null | number,
+      stdout: [] as string[],
+      stderr: [] as string[]
+    }
+    command.stdout.pipeTo(
+      new WritableStream({
+        write(log) {
+          if (log.length) {
+            const str = uint8ArrayToString(log).trim()
+            if (str) {
+              output.stdout.push(str)
+            }
+          }
+        }
+      })
+    )
+
+    command.stderr.pipeTo(
+      new WritableStream({
+        write(log) {
+          const str = uint8ArrayToString(log)
+          output.stderr.push(str)
+        }
+      })
+    )
+
+    output.code = await command.exited
+    return output
+  } catch (e) {
+    const err = e as InstanceType<typeof Bun.$.ShellError>
+    if ("exitCode" in err) {
+      return {
+        code: err.exitCode,
+        stdout: [err.stdout.toString("utf-8")],
+        stderr: [err.stderr.toString("utf-8")]
+      }
+    }
+    throw e
+  }
+}

package/lib/utils/file.utils.ts

@@ -0,0 +1,68 @@
+import path from "node:path"
+import fs, { exists, mkdir } from "node:fs/promises"
+import { evalTemplate } from "./renderer/renderer"
+import JSON5 from "json5"
+
+export function resolveFile(...args: string[]) {
+  return path.resolve(process.cwd(), ...args)
+}
+
+export async function ensureDirectory(filePath: string): Promise<void> {
+  const dir = path.dirname(filePath)
+  if (!(await exists(dir))) {
+    await mkdir(dir, { recursive: true })
+  }
+}
+
+export async function readKatmerFile(
+  filePath: string,
+  opts: {
+    cwd?: string
+    process?: boolean
+    processOpts?: any
+    errorMessage?: string
+  } = {}
+): Promise<Record<string, any>> {
+  try {
+    const isTwigTemplate = filePath.endsWith(".twig")
+
+    const baseFile = path.basename(filePath.replace(/\.twig$/, ""))
+
+    let contents = await fs.readFile(
+      path.resolve(opts.cwd || process.cwd(), filePath),
+      "utf-8"
+    )
+    if ((isTwigTemplate && opts.process !== false) || opts.process) {
+      contents = await evalTemplate(contents, {}, opts.processOpts)
+    }
+
+    return await parseKatmerFile(baseFile, contents)
+  } catch (e: any) {
+    const message = (typeof e === "string" ? e : e.message) || e
+    if (opts.errorMessage) {
+      throw new Error(`${opts.errorMessage}: ${message}`)
+    }
+    throw new Error(message)
+  }
+}
+
+export async function parseKatmerFile(filename: string, contents?: string) {
+  if (!contents) {
+    throw new Error(`No contents provided to parse file: ${filename}`)
+  }
+  try {
+    const extension = path.extname(filename)
+    if (/\.ya?ml/.test(extension)) {
+      return await Bun.YAML.parse(contents)
+    } else if (/\.json(c|5|rc)?/.test(extension)) {
+      return JSON5.parse(contents)
+    } else if (/\.toml/.test(extension)) {
+      return Bun.TOML.parse(contents)
+    } else {
+      throw `Unsupported file type: ${extension}`
+    }
+  } catch (e: any) {
+    const message = (typeof e === "string" ? e : e.message) || e
+    throw new Error(message)
+  }
+}