@katmer/core 0.0.3

package/README.md

@@ -0,0 +1 @@
+Main sources of `katmer` cli and runtime are located under this folder.

package/cli/katmer.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander"
+import { version, description } from "../package.json"
+import run from "./run"
+
+const cli = new Command()
+cli
+  .name("katmer")
+  .description(description)
+  .option(
+    "-t, --target [files...]",
+    "Path to config file",
+    "/etc/katmer/config.yaml"
+  )
+  .option("--cwd [dir]", "Override working directory")
+  .version(version, "-v, --version")
+  .helpOption("--help")
+
+run(cli)
+
+try {
+  await cli.parseAsync(process.argv)
+} catch (e) {
+  console.error(e)
+  console.error(e.message || e)
+  process.exit(1)
+}

package/cli/run.ts

@@ -0,0 +1,16 @@
+import { Command } from "commander"
+import { KatmerCore, type KatmerInitOptions } from "../lib/katmer"
+
+export default function (cli: Command) {
+  const command = new Command("run")
+    .description("Execute katmer task file")
+    .argument("<file>", "The file to run")
+    .action(async (file, opts) => {
+      const options = cli.opts<KatmerInitOptions>()
+      await using instance = new KatmerCore(options)
+      await instance.init()
+      await instance.run(file)
+    })
+  cli.addCommand(command)
+  return cli
+}

package/index.ts

@@ -0,0 +1,5 @@
+import { KatmerCore } from "./lib/katmer"
+
+export type { Katmer } from "./lib/katmer"
+
+export { KatmerCore }

package/lib/config.ts

@@ -0,0 +1,82 @@
+import configSchema from "./schemas/katmer_config.schema.json" with { type: "json" }
+
+import Ajv from "ajv/dist/2020"
+import ajvErrors from "ajv-errors"
+import { toMerged } from "es-toolkit"
+
+import { parseKatmerFile, readKatmerFile } from "./utils/file.utils"
+import { wrapInArray } from "./utils/json.utils"
+import { HttpModule } from "./modules/http/http.local.module"
+import { LocalProvider } from "./providers/local.provider"
+import { normalizeAjvError } from "./utils/ajv.utils"
+import type { KatmerConfig } from "./interfaces/config.interface"
+
+const ajv = ajvErrors(
+  new Ajv({
+    allErrors: true,
+    allowMatchingProperties: true,
+    allowUnionTypes: true
+  }),
+  {
+    singleError: false
+  }
+).addSchema(configSchema)
+
+export const KatmerConfigLoader = {
+  async load(
+    target: string | object | (string | object)[],
+    opts?: {
+      cwd?: string
+    }
+  ): Promise<KatmerConfig> {
+    const configTargets = wrapInArray(target)
+    const cwd = opts?.cwd || process.cwd()
+
+    let config = {} as KatmerConfig
+
+    for (const configTarget of configTargets) {
+      let loadedConfig: Record<string, any> = {}
+      if (typeof configTarget === "string") {
+        const parsed = await readKatmerFile(configTarget, {
+          cwd,
+          process: false,
+          errorMessage: `Failed to load config file from: ${configTarget}`
+        })
+        loadedConfig = this.validate(parsed, configTarget)
+      } else {
+        const fetch = new HttpModule(configTarget as any, new LocalProvider({}))
+        const { body, url } = await fetch.execute({} as any)
+
+        const filename = `${url.origin}${url.pathname}`
+        loadedConfig = this.validate(
+          await parseKatmerFile(filename, body),
+          filename
+        )
+      }
+
+      if (loadedConfig.include) {
+        loadedConfig = toMerged(
+          loadedConfig,
+          await KatmerConfigLoader.load(loadedConfig.include, opts)
+        )
+      }
+      loadedConfig.include = undefined
+      config = toMerged(config, loadedConfig)
+    }
+    config.cwd = opts?.cwd || process.cwd()
+    return config
+  },
+  validate(obj: any, filename?: string) {
+    const configValidator = ajv.getSchema(
+      "https://katmer.dev/schemas/katmer-config.schema.json"
+    )!
+    configValidator(obj)
+    if (configValidator.errors) {
+      const err = configValidator.errors[0]
+      throw new Error(
+        `Invalid configuration${filename ? ` [${filename}]` : ""}: ${normalizeAjvError(err)} at path: ${err.instancePath}`
+      )
+    }
+    return obj
+  }
+}

package/lib/interfaces/config.interface.ts

@@ -0,0 +1,113 @@
+import pino from "pino"
+
+export interface KatmerCLIOptions {
+  cwd?: string
+  target: string[]
+}
+// Connection variants
+export interface SSHConfig {
+  connection: "ssh"
+  hostname: string
+  port?: number
+  username?: string
+  password?: string
+  private_key?: string
+  private_key_password?: string
+  [k: string]: unknown
+}
+
+export interface LocalConfig {
+  connection: "local"
+  [k: string]: unknown
+}
+
+export type KatmerHostInput = SSHConfig | LocalConfig
+
+export type KatmerHostResolved = (SSHConfig | LocalConfig) & {
+  name: string
+  variables?: Record<string, unknown>
+  environment?: Record<string, string>
+}
+
+// Reserved labels
+export type KatmerReservedKey =
+  | "all"
+  | "children"
+  | "settings"
+  | "hosts"
+  | "variables"
+
+// Group settings (anything mergeable; no required `connection`)
+export type KatmerGroupSettings = {
+  [k: string]: unknown
+} & Partial<
+  Omit<SSHConfig, "connection" | "hostname"> & Omit<LocalConfig, "connection">
+>
+
+export type KatmerGroupVariables = Record<string, unknown>
+export type KatmerGroupEnvironment = Record<string, unknown>
+
+// Strict host map for the **root** form
+export type KatmerHostsRoot = Record<string, KatmerHostInput>
+
+// Shorthand-friendly host map for **groups** (allows `{}` etc.)
+export type KatmerHostShorthand = Partial<KatmerHostInput>
+export type KatmerHostsInGroup = Record<string, KatmerHostShorthand>
+
+// Children reference map
+export type KatmerChildren = Record<string, {} | undefined>
+
+// A single group
+export interface KatmerGroup {
+  children?: KatmerChildren
+  hosts?: KatmerHostsInGroup
+  settings?: KatmerGroupSettings // ← accepts {}
+  variables?: KatmerGroupVariables
+  environment?: KatmerGroupEnvironment
+}
+
+// Root “hosts/settings” form (implicit 'ungrouped')
+export interface KatmerTargetsRootForm {
+  hosts: KatmerHostsRoot // ← strict here
+  settings?: KatmerGroupSettings
+  variables?: KatmerGroupVariables
+  environment?: KatmerGroupEnvironment
+}
+
+// Grouped form (forbid reserved top-level keys here)
+export type KatmerTargetsGroupedForm = Record<string, KatmerGroup> & {
+  all?: never
+  children?: never
+  hosts?: never
+  settings?: never
+  variables?: never
+}
+
+// Top-level targets
+export type KatmerTargets = KatmerTargetsRootForm | KatmerTargetsGroupedForm
+
+export interface KatmerConfig {
+  cwd?: string
+  logging?: {
+    dir?: string
+    level?: "trace" | "debug" | "info" | "warn" | "error" | "silent"
+  }
+  targets: KatmerTargets
+}
+
+// Optional: normalizer output helpers
+export interface KatmerNormalizedTargets {
+  groups: Map<string, Set<string>>
+  hosts: Map<string, KatmerHostResolved>
+  allNames: Set<string>
+}
+
+export interface StandardLogger {
+  trace: pino.LogFn
+  debug: pino.LogFn
+  info: pino.LogFn
+  warn: pino.LogFn
+  error: pino.LogFn
+  fatal: pino.LogFn
+  child: (bindings: Record<string, unknown>) => StandardLogger
+}

package/lib/interfaces/executor.interface.ts

@@ -0,0 +1,13 @@
+export type TwigExpression = `{{${string}}}`
+// common interface so AptRepositoryModule does not depend on SSH
+export interface Executor {
+  run(
+    command: string,
+    options?: {
+      cwd?: string
+      encoding?: BufferEncoding
+      onStdout?: (line: string) => void
+      onStderr?: (line: string) => void
+    }
+  ): Promise<{ stdout: string; stderr: string; code: number }>
+}

package/lib/interfaces/module.interface.ts

@@ -0,0 +1,170 @@
+import type { OsArch, OsFamily } from "./provider.interface"
+
+export type PackageManager =
+  | "apt"
+  | "dnf"
+  | "yum"
+  | "zypper"
+  | "apk"
+  | "pacman"
+  | "brew"
+  | "port"
+  | "choco"
+  | "winget"
+  | "unknown"
+
+export interface PackageConstraint {
+  /** Package name as seen by the package manager(s). */
+  name: string
+  /** Exact version (distro version string is OK), e.g. "1.5.2-1ubuntu1". */
+  version?: string
+  /**
+   * Semver-like or comparator range, e.g. ">=1.5.0 <2".
+   * If semver is not available, a simple comparator fallback is used.
+   */
+  range?: string
+  /** One or more preferred package managers; omit to auto-detect. */
+  manager?: PackageManager | PackageManager[]
+  /**
+   * Alternatives: any of these packages satisfying the constraints is acceptable.
+   * Useful for cross-distro names (e.g., cron | cronie | dcron).
+   */
+  alternatives?: PackageConstraint[]
+  /**
+   * Optional custom test that returns 0 if installed and prints the version.
+   * Example: `dpkg-query -W -f='${Version}' cron`
+   */
+  testCmd?: string
+  /** When using testCmd, regex to extract the version from stdout (first capture group). */
+  versionRegex?: string
+}
+
+export interface BinaryConstraint {
+  /** Command to locate (e.g., "crontab", "bash", "powershell"). */
+  cmd: string
+  /** Optional args to run for version probe; default tries "--version" or "-V". */
+  args?: string[]
+  /** Regex to parse a version string from stdout/stderr (first capture group used). */
+  versionRegex?: string | RegExp
+  /** Version range to satisfy (same rules as PackageConstraint.range). */
+  range?: string
+  /** Alternatives: if any child passes, this binary constraint is satisfied. */
+  or?: BinaryConstraint[]
+}
+
+export interface ModulePlatformConstraint {
+  /** Supported architectures; default = ["any"]. */
+  arch?: OsArch[]
+  /** Family-level packages (before per-distro overrides). */
+  packages?: Array<PackageConstraint | string>
+  /** Required binaries/shells present in PATH. */
+  binaries?: BinaryConstraint[]
+  /** Require root (POSIX) or Administrator (Windows). */
+  requireRoot?: boolean
+  /** Optional minimal kernel version (POSIX) or OS version (Windows/macOS). */
+  minKernel?: string // e.g., ">=4.15"
+  minOsVersion?: string // e.g., ">=10.15" for macOS, ">=10.0" for Windows
+  /**
+   * Per-distro overrides/extensions. Keys are normalized IDs like:
+   * "debian", "ubuntu", "rhel", "centos", "rocky", "fedora", "alpine",
+   * "arch", "opensuse", "sles", "amzn", "amazon", or "any".
+   */
+  distro?: {
+    [distroId: string]: true | false | Omit<ModulePlatformConstraint, "distro">
+  }
+}
+
+/**
+ * New constraints structure:
+ * - platform is a map: any|linux|darwin|windows|freebsd|... → true|false|ModulePlatformConstraint
+ * - Each platform may also have distro overrides.
+ */
+export interface ModuleConstraints {
+  platform?: {
+    [family in OsFamily | "any" | "local"]?:
+      | true
+      | false
+      | ModulePlatformConstraint
+  }
+}
+
+export type ModulePlatformConstraintLegacy = never // (kept only if you referenced it elsewhere)
+
+export interface ModuleOptionsObject {
+  [key: string]: any // allow provider-specific options
+}
+export type ModuleOptions = any
+
+/**
+ * Standard result shape returned by modules.
+ *
+ * @remarks
+ * - `changed` indicates whether the module made any modifications on the target.
+ * - `failed` flags an error condition; when `true`, execution is considered unsuccessful.
+ * - `stdout`/`stderr` carry raw process output when applicable.
+ * - Timing fields (`start`, `end`, `delta`) are best-effort and ISO8601 for start/end.
+ * - `attempts`/`retries` are used by controls like `until` to report how many times an action ran.
+ * - Extra module-specific keys are allowed via the index signature.
+ *
+ * @example
+ * ```yaml
+ * - name: fetch metadata
+ *   register: meta
+ *   http:
+ *     url: "https://example.com/meta"
+ *     fail_on_http_error: false
+ *
+ * - name: inspect result
+ *   debug:
+ *     vars:
+ *       ok: "{{ not meta.failed }}"
+ *       changed: "{{ meta.changed }}"
+ *       status: "{{ meta.status }}"
+ *       took: "{{ meta.delta }}"
+ * ```
+ *
+ * @public
+ */
+export interface ModuleCommonReturn {
+  /** Whether this module changed anything on the target. */
+  changed?: boolean
+
+  /** Whether the module failed (non-zero exit code, validation failure, etc.). */
+  failed?: boolean
+
+  /** Human-readable message describing the outcome or error. */
+  msg?: string
+
+  /** Captured standard output, if available. */
+  stdout?: string
+
+  /** Captured standard error, if available. */
+  stderr?: string
+
+  /** ISO8601 timestamp when execution started (best-effort). */
+  start?: string
+
+  /** ISO8601 timestamp when execution ended (best-effort). */
+  end?: string
+
+  /** Duration string, e.g., "0:00:00.123" (best-effort). */
+  delta?: string
+
+  /**
+   * Number of attempts performed so far (e.g., by `until`).
+   * Typically increments from 1 upwards.
+   */
+  attempts?: number
+
+  /**
+   * Maximum retries allowed for this operation (e.g., by `until`).
+   * This reflects the configured ceiling, not the attempts taken.
+   */
+  retries?: number
+
+  /**
+   * Additional module-specific data.
+   * Modules may extend the result with fields such as `status`, `url`, `dest`, etc.
+   */
+  [key: string]: unknown
+}

package/lib/interfaces/provider.interface.ts

@@ -0,0 +1,214 @@
+import type { ProviderResponse } from "../providers/provider_response"
+import type { StandardLogger } from "./config.interface"
+
+export type OsFamily =
+  | "any"
+  | "linux"
+  | "darwin"
+  | "windows"
+  | "freebsd"
+  | "openbsd"
+  | "netbsd"
+  | "aix"
+  | "solaris"
+  | "unknown"
+
+export type OsArch =
+  | "x86_64"
+  | "arm64"
+  | "armv7"
+  | "armv6"
+  | "i386"
+  | "ppc64le"
+  | "s390x"
+  | "riscv64"
+  | "loongarch64"
+  | "any"
+  | "unknown"
+
+// Added powershell/cmd; keep "none" for raw passthrough
+export type SupportedShell =
+  | "bash"
+  | "sh"
+  | "zsh"
+  | "dash"
+  | "ksh"
+  | "mksh"
+  | "fish"
+  | "powershell"
+  | "cmd"
+  | "none"
+export interface ProviderOptions {
+  name?: string
+  shell?: SupportedShell
+  timeout?: number
+  retries?: number
+  [key: string]: any
+}
+
+export interface OsInfo {
+  family: OsFamily
+  arch: OsArch
+  kernel?: string
+  distroId?: string
+  versionId?: string
+  prettyName?: string
+  source: "posix" | "powershell" | "unknown"
+}
+
+/**
+ * Abstract base class for all Katmer providers.
+ * Providers define how tasks are executed (SSH, Local, AWS SSM, GCP, etc.)
+ */
+export abstract class KatmerProvider<
+  TOptions extends ProviderOptions = ProviderOptions
+> {
+  static readonly name: string
+  type: string
+
+  defaultShell: SupportedShell = "sh"
+  os: OsInfo = {
+    family: "unknown",
+    arch: "unknown",
+    source: "unknown"
+  }
+  logger!: StandardLogger
+  options: TOptions
+
+  connected = false
+  initialized = false
+
+  variables: Record<string, any> = {}
+  environment: Record<string, string> = {}
+
+  constructor(options: TOptions) {
+    this.options = options
+    this.type = this.constructor.name
+  }
+
+  /**
+   * Validate configuration before use (e.g., check required fields).
+   */
+  abstract check(): Promise<void>
+
+  /**
+   * Initialize resources (e.g., allocate clients, prepare temp dirs).
+   */
+  abstract initialize(): Promise<void>
+
+  /**
+   * Establish connection/session.
+   */
+  abstract connect(): Promise<void>
+
+  /**
+   * Execute a command within this provider's context.
+   */
+  abstract executor(
+    options?: Record<string, any>
+  ): (
+    command: string,
+    options?: Record<string, any>
+  ) => Promise<ProviderResponse>
+
+  /**
+   * Tear down connection/session (but keep reusable state).
+   */
+  abstract destroy(): Promise<void>
+
+  /**
+   * Cleanup all allocated resources (irreversible).
+   */
+  abstract cleanup(): Promise<void>
+
+  /** Probe remote OS/arch as soon as we connect; called automatically on `ensureReady()` */
+  abstract getOsInfo(): Promise<OsInfo>
+
+  /** Pick the best shell based on OS and availability; sets `this.options.shell`. */
+  async decideDefaultShell(): Promise<SupportedShell> {
+    const execRaw = this.executor({ shell: "none", timeout: 4000 })
+
+    // Windows → prefer PowerShell, fallback to cmd
+    if (this.os.family === "windows") {
+      try {
+        const r = await execRaw(
+          `powershell -NoProfile -NonInteractive -Command "$PSVersionTable.PSVersion.Major"`
+        )
+        if (r.code === 0) {
+          this.defaultShell = "powershell"
+          return "powershell"
+        }
+      } catch {}
+      this.defaultShell = "cmd"
+      return "cmd"
+    }
+
+    // POSIX → choose first available, prefer bash/zsh
+    const probe =
+      'for s in bash zsh ksh mksh dash sh fish; do command -v "$s" >/dev/null 2>&1 && { echo "$s"; exit 0; }; done; echo sh'
+    let chosen = "sh"
+    try {
+      const r = await execRaw(`sh -c '${probe}'`)
+      if (r.code === 0 && r.stdout?.trim()) chosen = r.stdout.trim()
+    } catch {
+      // fallback to bash if sh probing failed
+      try {
+        const r2 = await execRaw(`bash -lc '${probe}'`)
+        if (r2.code === 0 && r2.stdout?.trim()) chosen = r2.stdout.trim()
+      } catch {}
+    }
+
+    // normalize to SupportedShell
+    const asShell =
+      (["bash", "zsh", "ksh", "mksh", "dash", "sh", "fish"].find(
+        (s) => s === chosen
+      ) as SupportedShell) || "sh"
+
+    this.defaultShell = asShell
+    return asShell
+  }
+
+  /**
+   * Helper to ensure full lifecycle (for convenience in orchestrators).
+   */
+  async ensureReady(): Promise<this> {
+    if (!this.initialized) {
+      await this.check()
+      await this.initialize()
+      this.initialized = true
+    }
+    if (!this.connected) {
+      await this.connect()
+
+      this.os = await this.getOsInfo()
+      await this.decideDefaultShell()
+
+      this.connected = true
+    }
+    return this
+  }
+
+  /**
+   * Safe shutdown wrapper that handles errors gracefully.
+   */
+  async safeShutdown(): Promise<void> {
+    try {
+      await this.destroy()
+      this.connected = false
+    } catch (err) {
+      console.warn(`[Provider:${this.options.name}] destroy() failed:`, err)
+    }
+
+    try {
+      await this.cleanup()
+      this.initialized = false
+    } catch (err) {
+      console.warn(`[Provider:${this.options.name}] cleanup() failed:`, err)
+    }
+    this.logger.trace(`Disconnected from provider: ${this.options.name}`)
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.safeShutdown()
+  }
+}