@ticatec/omniflow-core 0.1.1 → 0.2.0

package/src/context/index.ts

@@ -0,0 +1,74 @@
+import { executionLocalStorage } from './storage.js'
+import type { ExecutionContext, Logger } from './types.js'
+
+export * from './types.js'
+export { executionLocalStorage } from './storage.js'
+
+/**
+ * Return the active ExecutionContext for the current asynchronous call stack.
+ *
+ * @throws Error if called outside an active execution scope (i.e., not inside runWithContext).
+ */
+export function getContext(): ExecutionContext {
+  const ctx = executionLocalStorage.getStore()
+  if (!ctx) {
+    throw new Error(
+      'No active OmniFlow ExecutionContext found in this asynchronous scope. ' +
+      'Ensure this function is executed within runWithContext(ctx, fn).'
+    )
+  }
+  return ctx
+}
+
+/**
+ * Return the active ExecutionContext if available, or undefined.
+ */
+export function tryGetContext(): ExecutionContext | undefined {
+  return executionLocalStorage.getStore()
+}
+
+/**
+ * Check whether an active ExecutionContext is available in the current scope.
+ */
+export function hasContext(): boolean {
+  return executionLocalStorage.getStore() !== undefined
+}
+
+/**
+ * Run a function within an ExecutionContext scope. All asynchronous calls
+ * initiated within `fn` will have access to `ctx` via `getContext()`.
+ */
+export async function runWithContext<T>(
+  ctx: ExecutionContext,
+  fn: () => Promise<T> | T
+): Promise<T> {
+  return executionLocalStorage.run(ctx, fn)
+}
+
+/**
+ * Helper to build a fallback or testing ExecutionContext.
+ */
+export function createMockContext(overrides: Partial<ExecutionContext> = {}): ExecutionContext {
+  const defaultLogger: Logger = {
+    info: (msg: string) => console.log(`[INFO] ${msg}`),
+    warn: (msg: string) => console.warn(`[WARN] ${msg}`),
+    error: (msg: string) => console.error(`[ERROR] ${msg}`),
+    debug: (msg: string) => console.debug(`[DEBUG] ${msg}`)
+  }
+
+  return {
+    runId: overrides.runId ?? `test-run-${Date.now()}`,
+    workspace: overrides.workspace ?? process.cwd(),
+    projectRoot: overrides.projectRoot ?? process.cwd(),
+    project: overrides.project ?? 'test-project',
+    module: overrides.module,
+    moduleFolder: overrides.moduleFolder,
+    environment: overrides.environment ?? 'test',
+    git: overrides.git ?? { branch: 'main', commit: '0000000', dirty: false },
+    env: overrides.env ?? {},
+    logger: overrides.logger ?? defaultLogger,
+    dryRun: overrides.dryRun ?? false,
+    sourceMode: overrides.sourceMode ?? 'local',
+    logFile: overrides.logFile
+  }
+}

package/src/context/storage.ts

@@ -0,0 +1,8 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { ExecutionContext } from './types.js'
+
+/**
+ * Node.js AsyncLocalStorage instance managing the active ExecutionContext
+ * across asynchronous function calls.
+ */
+export const executionLocalStorage = new AsyncLocalStorage<ExecutionContext>()

package/src/context/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Core execution context and command result contracts for OmniFlow.
+ */
+
+export interface GitMetadata {
+  branch?: string
+  commit?: string
+  tag?: string
+  dirty?: boolean
+}
+
+export interface Logger {
+  info(msg: string): void
+  warn(msg: string): void
+  error(msg: string): void
+  debug?(msg: string): void
+}
+
+export interface Artifact {
+  type: string
+  ref: string
+  name?: string
+  digest?: string
+  path?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface CommandResult {
+  success: boolean
+  message?: string
+  artifacts?: Artifact[]
+  outputs?: Record<string, unknown>
+  error?: Error | string
+}
+
+export type SourceMode = 'local' | 'ref' | 'managed'
+
+/**
+ * Pure read-only execution context representing the active run state.
+ * Bound to the current async execution chain via AsyncLocalStorage.
+ */
+export interface ExecutionContext {
+  /** Unique run identifier */
+  runId: string
+  /** Physical directory path for workspace */
+  workspace: string
+  /** Physical project root directory */
+  projectRoot: string
+  /** Project key/name */
+  project: string
+  /** Module name currently executing, if applicable */
+  module?: string
+  /** Relative subdirectory of the active module */
+  moduleFolder?: string
+  /** Target deployment environment name (test, prod, etc.) */
+  environment: string
+  /** Git repository state at execution time */
+  git: GitMetadata
+  /** Resolved and merged environment variables */
+  env: Record<string, string>
+  /** Structured logger directing output to terminal and run record */
+  logger: Logger
+  /** Whether the execution is running in dry-run mode */
+  dryRun: boolean
+  /** Active source resolution mode */
+  sourceMode?: SourceMode
+  /** Path to the log file receiving all process and command output */
+  logFile?: string
+}

package/src/index.ts

@@ -0,0 +1,97 @@
+/**
+ * @ticatec/omniflow-core
+ *
+ * Foundational execution context, primitives, and toolchain SPI
+ * for OmniFlow CI/CD orchestrator and its plugins.
+ */
+
+// Context
+export {
+  getContext,
+  tryGetContext,
+  hasContext,
+  runWithContext,
+  createMockContext,
+  executionLocalStorage,
+  type ExecutionContext,
+  type CommandResult,
+  type Artifact,
+  type Logger,
+  type GitMetadata,
+  type SourceMode
+} from './context/index.js'
+
+// Primitives
+export {
+  shell,
+  run,
+  sh,
+  output,
+  createMaskTransform,
+  type RunOptions,
+  type ShellOutputResult,
+  type TemplateRunner
+} from './primitives/shell.js'
+
+export {
+  ssh,
+  SshClient,
+  type SshServerConfig,
+  type SshConnectionConfig,
+  type SshTarget,
+  type SshResult
+} from './primitives/ssh.js'
+
+export {
+  git,
+  type GitCwdOptions,
+  type GitFetchOptions,
+  type GitResetOptions,
+  type GitCheckoutOptions,
+  type GitCleanOptions
+} from './primitives/git.js'
+
+export {
+  docker,
+  type DockerBuildOptions,
+  type ComposeOptions
+} from './primitives/docker.js'
+
+// Toolchains
+export {
+  registerToolchain,
+  resolveToolchain,
+  ToolchainRegistry,
+  defaultToolchainRegistry,
+  MavenToolchain,
+  GradleToolchain,
+  NodeToolchain,
+  readPom,
+  parseXml,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo,
+  type ResolveToolchainOptions
+} from './toolchain/index.js'
+
+// Utilities
+export {
+  maskString,
+  maskObject,
+  isSecretKey,
+  MASK
+} from './utils/mask.js'
+
+export {
+  templateToArgv
+} from './utils/template.js'
+
+// Plugin SPI
+export {
+  type PluginContext,
+  type PluginRegisterFn,
+  type ArtifactRegistryLike,
+  type BranchRegistryLike,
+  type CommandRegistryLike,
+  type ToolchainRegistryLike
+} from './plugin/PluginContext.js'

package/src/plugin/PluginContext.ts

@@ -0,0 +1,57 @@
+/**
+ * OmniFlow Plugin SPI Contracts
+ *
+ * Provides the context and registration hook for external plugins extending
+ * artifact publishers, branch strategies, commands, and toolchains.
+ */
+
+export interface ArtifactRegistryLike {
+  register(publisher: any): void
+}
+
+export interface BranchRegistryLike {
+  register(strategy: any): void
+}
+
+export interface CommandRegistryLike {
+  register(command: any): void
+  registerFunction?(name: string, fn: any): void
+}
+
+export interface ToolchainRegistryLike {
+  register(toolchain: any): void
+}
+
+/**
+ * Standard SPI context passed to every plugin's `register(ctx, options)` hook.
+ */
+export interface PluginContext<
+  TArtifactRegistry = any,
+  TBranchRegistry = any,
+  TCommandRegistry = any,
+  TToolchainRegistry = any
+> {
+  /** Registry for Docker, NPM, Maven, Raw artifact publishers */
+  artifactRegistry: TArtifactRegistry
+  /** Registry for Git branch promotion and PR/MR drivers */
+  branchRegistry: TBranchRegistry
+  /** Registry for BaseCommand subclasses or functional recipes */
+  commandRegistry: TCommandRegistry
+  /** Registry for detection and build toolchains */
+  toolchainRegistry: TToolchainRegistry
+  /** Runtime environment variables */
+  env: Record<string, string | undefined>
+}
+
+/**
+ * The standard entry function every OmniFlow plugin exports.
+ */
+export type PluginRegisterFn<
+  TArtifactRegistry = any,
+  TBranchRegistry = any,
+  TCommandRegistry = any,
+  TToolchainRegistry = any
+> = (
+  ctx: PluginContext<TArtifactRegistry, TBranchRegistry, TCommandRegistry, TToolchainRegistry>,
+  options?: Record<string, unknown>
+) => Promise<void> | void

package/src/primitives/docker.ts

@@ -0,0 +1,164 @@
+import path from 'node:path'
+import { shell } from './shell.js'
+import { tryGetContext } from '../context/index.js'
+import type { Artifact } from '../context/types.js'
+
+export interface DockerBuildOptions {
+  image: string
+  dockerfile?: string
+  target?: string
+  buildArgs?: Record<string, string>
+  cwd?: string
+  flags?: string[]
+}
+
+export interface ComposeOptions {
+  files?: string | string[]
+  services?: string[]
+  detach?: boolean
+  build?: boolean
+  envFile?: string
+  cwd?: string
+  flags?: string[]
+}
+
+export const docker = {
+  /**
+   * Build a Docker image.
+   */
+  async build(options: DockerBuildOptions): Promise<Artifact> {
+    if (!options.image || typeof options.image !== 'string' || options.image.trim() === '') {
+      throw new Error('Docker build requires a non-empty "image" identifier')
+    }
+
+    const ctx = tryGetContext()
+    const cwd = options.cwd ?? (ctx?.moduleFolder ? path.resolve(ctx.workspace, ctx.moduleFolder) : ctx?.workspace ?? process.cwd())
+    const dockerfile = options.dockerfile ?? 'Dockerfile'
+
+    const args: string[] = ['build', '-f', dockerfile, '-t', options.image]
+
+    if (options.target) {
+      args.push('--target', options.target)
+    }
+
+    if (options.buildArgs) {
+      for (const [k, v] of Object.entries(options.buildArgs)) {
+        args.push('--build-arg', `${k}=${v}`)
+      }
+    }
+
+    if (options.flags) {
+      args.push(...options.flags)
+    }
+
+    args.push('.')
+
+    ctx?.logger.info(`Building Docker image: ${options.image} (file: ${dockerfile})`)
+    await shell.run({ cwd })`docker ${args}`
+
+    return {
+      type: 'docker-image',
+      ref: options.image
+    }
+  },
+
+  /**
+   * Tag an existing Docker image.
+   */
+  async tag(sourceImage: string, targetImage: string): Promise<Artifact> {
+    const ctx = tryGetContext()
+    ctx?.logger.info(`Tagging Docker image: ${sourceImage} -> ${targetImage}`)
+    await shell.run`docker tag ${sourceImage} ${targetImage}`
+    return {
+      type: 'docker-image',
+      ref: targetImage
+    }
+  },
+
+  /**
+   * Push a Docker image to a registry.
+   */
+  async push(image: string): Promise<Artifact> {
+    const ctx = tryGetContext()
+    ctx?.logger.info(`Pushing Docker image: ${image}`)
+    await shell.run`docker push ${image}`
+    return {
+      type: 'docker-image',
+      ref: image
+    }
+  },
+
+  /**
+   * Launch services using Docker Compose.
+   */
+  async composeUp(options: ComposeOptions = {}): Promise<void> {
+    const ctx = tryGetContext()
+    const cwd = options.cwd ?? (ctx?.moduleFolder ? path.resolve(ctx.workspace, ctx.moduleFolder) : ctx?.workspace ?? process.cwd())
+    const args: string[] = ['compose']
+
+    if (options.files) {
+      const files = Array.isArray(options.files) ? options.files : [options.files]
+      for (const f of files) {
+        args.push('-f', f)
+      }
+    }
+
+    if (options.envFile) {
+      args.push('--env-file', options.envFile)
+    }
+
+    args.push('up')
+
+    if (options.detach !== false) {
+      args.push('-d')
+    }
+
+    if (options.build) {
+      args.push('--build')
+    }
+
+    if (options.flags) {
+      args.push(...options.flags)
+    }
+
+    if (options.services && options.services.length > 0) {
+      args.push(...options.services)
+    }
+
+    ctx?.logger.info(`Docker Compose up (services: ${options.services?.join(', ') ?? 'all'})`)
+    await shell.run({ cwd })`docker ${args}`
+  },
+
+  /**
+   * Stop and remove containers using Docker Compose.
+   */
+  async composeDown(options: ComposeOptions = {}): Promise<void> {
+    const ctx = tryGetContext()
+    const cwd = options.cwd ?? (ctx?.moduleFolder ? path.resolve(ctx.workspace, ctx.moduleFolder) : ctx?.workspace ?? process.cwd())
+    const args: string[] = ['compose']
+
+    if (options.files) {
+      const files = Array.isArray(options.files) ? options.files : [options.files]
+      for (const f of files) {
+        args.push('-f', f)
+      }
+    }
+
+    if (options.envFile) {
+      args.push('--env-file', options.envFile)
+    }
+
+    args.push('down')
+
+    if (options.flags) {
+      args.push(...options.flags)
+    }
+
+    if (options.services && options.services.length > 0) {
+      args.push(...options.services)
+    }
+
+    ctx?.logger.info('Docker Compose down')
+    await shell.run({ cwd })`docker ${args}`
+  }
+}

package/src/primitives/git.ts

@@ -0,0 +1,172 @@
+import { execa } from 'execa'
+import { tryGetContext } from '../context/index.js'
+
+export interface GitCwdOptions {
+  dir?: string
+}
+
+export interface GitFetchOptions extends GitCwdOptions {
+  remote?: string
+  branch?: string
+}
+
+export interface GitResetOptions extends GitCwdOptions {
+  target?: string
+}
+
+export interface GitCheckoutOptions extends GitCwdOptions {
+  ref?: string
+}
+
+export interface GitCleanOptions extends GitCwdOptions {
+  forceIgnored?: boolean
+}
+
+function resolveGitCwd(optionsOrDir?: string | GitCwdOptions): string {
+  if (typeof optionsOrDir === 'string') {
+    return optionsOrDir
+  }
+  if (optionsOrDir?.dir) {
+    return optionsOrDir.dir
+  }
+  const ctx = tryGetContext()
+  if (ctx) {
+    return ctx.projectRoot ?? ctx.workspace ?? process.cwd()
+  }
+  return process.cwd()
+}
+
+export const git = {
+  /**
+   * Return full SHA of current commit.
+   * @param options Directory path or GitCwdOptions object. Defaults to repository root.
+   */
+  async currentCommit(options?: string | GitCwdOptions): Promise<string> {
+    const cwd = resolveGitCwd(options)
+    const { stdout } = await execa('git', ['rev-parse', 'HEAD'], { cwd })
+    return stdout.trim()
+  },
+
+  /**
+   * Return short SHA of current commit.
+   * @param options Directory path or GitCwdOptions object. Defaults to repository root.
+   */
+  async shortCommit(options?: string | GitCwdOptions): Promise<string> {
+    const cwd = resolveGitCwd(options)
+    const { stdout } = await execa('git', ['rev-parse', '--short', 'HEAD'], { cwd })
+    return stdout.trim()
+  },
+
+  /**
+   * Return current checked-out branch name, or empty string if detached HEAD.
+   * @param options Directory path or GitCwdOptions object. Defaults to repository root.
+   */
+  async currentBranch(options?: string | GitCwdOptions): Promise<string> {
+    const cwd = resolveGitCwd(options)
+    try {
+      const { stdout } = await execa('git', ['symbolic-ref', '--short', 'HEAD'], { cwd })
+      return stdout.trim()
+    } catch {
+      const isInside = await execa('git', ['rev-parse', '--is-inside-work-tree'], { cwd, reject: false })
+      if (!isInside.failed) {
+        return '' // Valid git repo, but detached HEAD
+      }
+      throw new Error(`Not a git repository: ${cwd}`)
+    }
+  },
+
+  /**
+   * Check if working tree has untracked or uncommitted changes.
+   * @param options Directory path or GitCwdOptions object. Defaults to repository root.
+   */
+  async isDirty(options?: string | GitCwdOptions): Promise<boolean> {
+    const cwd = resolveGitCwd(options)
+    const { stdout } = await execa('git', ['status', '--porcelain'], { cwd })
+    return stdout.trim().length > 0
+  },
+
+  /**
+   * Fetch latest changes from remote.
+   * @param options GitFetchOptions object { remote, branch, dir }. Defaults to { remote: 'origin' } at repo root.
+   */
+  async fetch(options: GitFetchOptions = {}): Promise<void> {
+    const cwd = resolveGitCwd(options)
+    const rem = options.remote ?? 'origin'
+    const br = options.branch
+
+    const ctx = tryGetContext()
+    if (ctx?.dryRun) {
+      ctx.logger.info(`[DRY-RUN] git fetch ${rem}${br ? ` ${br}` : ''}`)
+      return
+    }
+    const args = ['fetch', rem]
+    if (br) args.push(br)
+    await execa('git', args, { cwd })
+  },
+
+  /**
+   * Hard reset working tree to target commit/ref (defaults to HEAD).
+   * @param targetOrOptions Target ref name (string, e.g. 'HEAD', 'origin/main'), or GitResetOptions { target, dir }.
+   * Note: A bare string argument is treated as the target ref, NOT a directory. Pass { dir: '...' } to change directory.
+   */
+  async resetHard(targetOrOptions: string | GitResetOptions = 'HEAD'): Promise<void> {
+    let target = 'HEAD'
+    let cwd: string
+
+    if (typeof targetOrOptions === 'object' && targetOrOptions !== null) {
+      target = targetOrOptions.target ?? 'HEAD'
+      cwd = resolveGitCwd(targetOrOptions)
+    } else {
+      target = targetOrOptions
+      cwd = resolveGitCwd()
+    }
+
+    const ctx = tryGetContext()
+    if (ctx?.dryRun) {
+      ctx.logger.info(`[DRY-RUN] git reset --hard ${target}`)
+      return
+    }
+    await execa('git', ['reset', '--hard', target], { cwd })
+  },
+
+  /**
+   * Clean working tree untracked files.
+   * @param options GitCleanOptions { forceIgnored, dir }. Defaults to repo root.
+   */
+  async clean(options: GitCleanOptions = {}): Promise<void> {
+    const cwd = resolveGitCwd(options)
+    const ctx = tryGetContext()
+    const forceIgnored = options.forceIgnored ?? false
+    if (ctx?.dryRun) {
+      ctx.logger.info(`[DRY-RUN] git clean -fd${forceIgnored ? 'x' : ''}`)
+      return
+    }
+    const flags = forceIgnored ? ['clean', '-fdx'] : ['clean', '-fd']
+    await execa('git', flags, { cwd })
+  },
+
+  /**
+   * Switch or checkout a ref (defaults to main).
+   * @param refOrOptions Ref name (string, e.g. 'main', 'feature/login'), or GitCheckoutOptions { ref, dir }.
+   * Note: A bare string argument is treated as the ref name, NOT a directory. Pass { dir: '...' } to change directory.
+   */
+  async checkout(refOrOptions: string | GitCheckoutOptions = 'main'): Promise<void> {
+    let ref = 'main'
+    let cwd: string
+
+    if (typeof refOrOptions === 'object' && refOrOptions !== null) {
+      ref = refOrOptions.ref ?? 'main'
+      cwd = resolveGitCwd(refOrOptions)
+    } else {
+      ref = refOrOptions
+      cwd = resolveGitCwd()
+    }
+
+    const ctx = tryGetContext()
+    if (ctx?.dryRun) {
+      ctx.logger.info(`[DRY-RUN] git checkout ${ref}`)
+      return
+    }
+    await execa('git', ['checkout', ref], { cwd })
+  }
+}

package/src/primitives/index.ts

@@ -0,0 +1,4 @@
+export * from './shell.js'
+export * from './ssh.js'
+export * from './git.js'
+export * from './docker.js'