@ticatec/omniflow-core 0.1.1 → 0.2.0

package/src/toolchain/providers/NodeToolchain.ts

@@ -0,0 +1,172 @@
+import path from 'node:path'
+import fs from 'node:fs/promises'
+import { shell } from '../../primitives/shell.js'
+import type { ToolchainProvider, DetectionResult, ProjectInfo } from '../types.js'
+
+export type NodePackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun'
+
+const LOCKFILES: ReadonlyArray<readonly [string, NodePackageManager]> = [
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['bun.lockb', 'bun'],
+  ['bun.lock', 'bun'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npm']
+]
+
+async function detectPackageManager(dir: string): Promise<{ pm: NodePackageManager; reason: string }> {
+  try {
+    const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf-8')
+    const field = JSON.parse(raw)?.packageManager
+    if (typeof field === 'string') {
+      const name = field.split('@')[0]
+      if (['npm', 'pnpm', 'yarn', 'bun'].includes(name)) {
+        return { pm: name as NodePackageManager, reason: `package.json packageManager (${field})` }
+      }
+    }
+  } catch {
+    // continue
+  }
+
+  for (const [lockfile, pm] of LOCKFILES) {
+    try {
+      await fs.access(path.join(dir, lockfile))
+      return { pm, reason: lockfile }
+    } catch {
+      // continue
+    }
+  }
+
+  return { pm: 'npm', reason: 'default fallback' }
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function isYarnBerry(dir: string): Promise<boolean> {
+  if (await fileExists(path.join(dir, '.yarnrc.yml')) || await fileExists(path.join(dir, '.yarnrc.yaml'))) {
+    return true
+  }
+  try {
+    const raw = await fs.readFile(path.join(dir, 'package.json'), 'utf-8')
+    const pm = JSON.parse(raw)?.packageManager
+    if (typeof pm === 'string' && /^yarn@([2-9]|\d{2,})/.test(pm)) {
+      return true
+    }
+  } catch {}
+  return false
+}
+
+export class NodeToolchain implements ToolchainProvider {
+  readonly name: string
+  readonly priority: number = 10
+  private explicitPm?: NodePackageManager
+
+  constructor(pmName?: NodePackageManager) {
+    this.name = pmName ?? 'node'
+    this.explicitPm = pmName
+  }
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    try {
+      await fs.access(path.join(projectDir, 'package.json'))
+    } catch {
+      return null
+    }
+
+    const { pm, reason } = await detectPackageManager(projectDir)
+    return {
+      name: this.explicitPm ?? pm,
+      reason: `found package.json and ${reason}`
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    const raw = await fs.readFile(path.join(projectDir, 'package.json'), 'utf-8')
+    const pkg = JSON.parse(raw)
+
+    const rawName: string = pkg.name || path.basename(projectDir)
+    let name = rawName
+    let namespace: string | undefined
+
+    if (rawName.startsWith('@') && rawName.includes('/')) {
+      const [scope, bare] = rawName.split('/')
+      namespace = scope.slice(1)
+      name = bare
+    }
+
+    return {
+      name,
+      version: pkg.version || '0.0.0',
+      fullName: rawName,
+      namespace
+    }
+  }
+
+  async install(projectDir: string, flags: string[] = []): Promise<void> {
+    const pm = await this.resolvePm(projectDir)
+
+    if (pm === 'npm') {
+      const hasLock = await fileExists(path.join(projectDir, 'package-lock.json'))
+      if (hasLock) {
+        await shell.run({ cwd: projectDir })`npm ci ${flags}`
+      } else {
+        await shell.run({ cwd: projectDir })`npm install ${flags}`
+      }
+      return
+    }
+
+    if (pm === 'pnpm') {
+      const hasLock = await fileExists(path.join(projectDir, 'pnpm-lock.yaml'))
+      const hasFrozenFlag = flags.some(f => f.includes('frozen-lockfile'))
+      const frozenArgs = (hasLock && !hasFrozenFlag) ? ['--frozen-lockfile'] : []
+      await shell.run({ cwd: projectDir })`pnpm install ${frozenArgs} ${flags}`
+      return
+    }
+
+    if (pm === 'yarn') {
+      const hasLock = await fileExists(path.join(projectDir, 'yarn.lock'))
+      if (!hasLock) {
+        await shell.run({ cwd: projectDir })`yarn install ${flags}`
+        return
+      }
+      const isBerry = await isYarnBerry(projectDir)
+      const hasFrozenFlag = flags.some(f => f.includes('frozen-lockfile') || f.includes('immutable'))
+      const frozenArgs = !hasFrozenFlag ? [isBerry ? '--immutable' : '--frozen-lockfile'] : []
+      await shell.run({ cwd: projectDir })`yarn install ${frozenArgs} ${flags}`
+      return
+    }
+
+    if (pm === 'bun') {
+      const hasLock = (await fileExists(path.join(projectDir, 'bun.lockb'))) ||
+                      (await fileExists(path.join(projectDir, 'bun.lock')))
+      const hasFrozenFlag = flags.some(f => f.includes('frozen-lockfile'))
+      const frozenArgs = (hasLock && !hasFrozenFlag) ? ['--frozen-lockfile'] : []
+      await shell.run({ cwd: projectDir })`bun install ${frozenArgs} ${flags}`
+      return
+    }
+
+    await shell.run({ cwd: projectDir })`${pm} install ${flags}`
+  }
+
+  async build(projectDir: string, flags: string[] = []): Promise<void> {
+    const pm = await this.resolvePm(projectDir)
+    await shell.run({ cwd: projectDir })`${pm} run build ${flags}`
+  }
+
+  async run(projectDir: string, task: string, flags: string[] = []): Promise<void> {
+    const pm = await this.resolvePm(projectDir)
+    await shell.run({ cwd: projectDir })`${pm} run ${task} ${flags}`
+  }
+
+  private async resolvePm(projectDir: string): Promise<NodePackageManager> {
+    if (this.explicitPm) return this.explicitPm
+    const { pm } = await detectPackageManager(projectDir)
+    return pm
+  }
+}

package/src/toolchain/providers/pom.ts

@@ -0,0 +1,145 @@
+/**
+ * XML parsing helper for reading coordinates out of a pom.xml without general XML parser dependencies.
+ */
+
+export interface XmlNode {
+  text: string
+  children: Record<string, XmlNode[]>
+}
+
+const ENTITIES: Record<string, string> = {
+  '&lt;': '<',
+  '&gt;': '>',
+  '&amp;': '&',
+  '&quot;': '"',
+  '&apos;': "'"
+}
+
+function decodeEntities(text: string): string {
+  return text.replace(/&(?:lt|gt|amp|quot|apos|#\d+|#x[0-9a-fA-F]+);/g, match => {
+    if (ENTITIES[match]) return ENTITIES[match]
+    const numeric = match.startsWith('&#x') || match.startsWith('&#X')
+      ? parseInt(match.slice(3, -1), 16)
+      : parseInt(match.slice(2, -1), 10)
+    return Number.isFinite(numeric) ? String.fromCodePoint(numeric) : match
+  })
+}
+
+function stripNoise(xml: string): string {
+  return xml
+    .replace(/<\?[\s\S]*?\?>/g, '')
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<!DOCTYPE[^>[]*(\[[\s\S]*?\])?[^>]*>/gi, '')
+    .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, body: string) =>
+      body.replace(/&/g, '&amp;').replace(/</g, '&lt;'))
+}
+
+export function parseXml(xml: string): { name: string; node: XmlNode } {
+  const source = stripNoise(xml)
+  const tag = /<\s*(\/?)\s*([A-Za-z_][\w.:-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)\s*>/g
+
+  let root: { name: string; node: XmlNode } | undefined
+  const stack: { name: string; node: XmlNode }[] = []
+  let textFrom = 0
+  let match: RegExpExecArray | null
+
+  const addText = (upTo: number) => {
+    const top = stack[stack.length - 1]
+    if (!top) return
+    top.node.text += source.slice(textFrom, upTo)
+  }
+
+  while ((match = tag.exec(source)) !== null) {
+    const [whole, closing, name, , selfClosing] = match
+
+    addText(match.index)
+    textFrom = match.index + whole.length
+
+    if (closing) {
+      const open = stack.pop()
+      if (!open || open.name !== name) {
+        throw new Error(`Malformed XML: </${name}> does not close <${open?.name ?? 'nothing'}>`)
+      }
+      continue
+    }
+
+    const node: XmlNode = { text: '', children: {} }
+    const entry = { name, node }
+
+    const parent = stack[stack.length - 1]
+    if (parent) {
+      ;(parent.node.children[name] ??= []).push(node)
+    } else if (root) {
+      break
+    } else {
+      root = entry
+    }
+
+    if (!selfClosing) stack.push(entry)
+  }
+
+  if (!root) throw new Error('Malformed XML: no root element')
+  if (stack.length > 0) {
+    throw new Error(`Malformed XML: unclosed tag <${stack[stack.length - 1].name}>`)
+  }
+  return root
+}
+
+function childText(node: XmlNode, name: string): string | undefined {
+  const child = node.children[name]?.[0]
+  if (!child) return undefined
+  const text = decodeEntities(child.text).trim()
+  return text || undefined
+}
+
+function properties(project: XmlNode): Record<string, string> {
+  const out: Record<string, string> = {}
+  const block = project.children['properties']?.[0]
+  if (!block) return out
+  for (const [name, nodes] of Object.entries(block.children)) {
+    const text = decodeEntities(nodes[0].text).trim()
+    if (text) out[name] = text
+  }
+  return out
+}
+
+function expand(value: string, vars: Record<string, string>): string {
+  let out = value
+  for (let depth = 0; depth < 5 && out.includes('${'); depth++) {
+    const next = out.replace(/\$\{([^}]+)\}/g, (whole, name: string) => vars[name] ?? whole)
+    if (next === out) break
+    out = next
+  }
+  return out
+}
+
+export interface PomCoordinates {
+  groupId?: string
+  artifactId?: string
+  version?: string
+}
+
+export function readPom(xml: string): PomCoordinates {
+  const { node: project } = parseXml(xml)
+  const parent = project.children['parent']?.[0]
+
+  const vars = properties(project)
+  if (parent) {
+    const parentVersion = childText(parent, 'version')
+    if (parentVersion) {
+      vars['project.parent.version'] = parentVersion
+    }
+    const parentGroupId = childText(parent, 'groupId')
+    if (parentGroupId) {
+      vars['project.parent.groupId'] = parentGroupId
+    }
+  }
+
+  const resolve = (value: string | undefined) => value === undefined ? undefined : expand(value, vars)
+
+  return {
+    groupId: resolve(childText(project, 'groupId') ?? (parent && childText(parent, 'groupId'))),
+    artifactId: resolve(childText(project, 'artifactId')),
+    version: resolve(childText(project, 'version') ?? (parent && childText(parent, 'version')))
+  }
+}

package/src/toolchain/registry.ts

@@ -0,0 +1,161 @@
+import { MavenToolchain } from './providers/MavenToolchain.js'
+import { GradleToolchain } from './providers/GradleToolchain.js'
+import { NodeToolchain } from './providers/NodeToolchain.js'
+import type { ToolchainProvider, DetectionResult } from './types.js'
+
+export interface ResolveToolchainOptions {
+  /** Explicitly preferred toolchain (takes precedence over automatic detection) */
+  preferred?: string
+  /** Fallback toolchain used only when automatic detection yields no match */
+  fallback?: string
+}
+
+export class ToolchainRegistry {
+  private providers: Map<string, ToolchainProvider> = new Map()
+
+  constructor(registerDefaults = true) {
+    if (registerDefaults) {
+      this.registerDefaultProviders()
+    }
+  }
+
+  private registerDefaultProviders(): void {
+    // Built-in order: Maven, Gradle, Node
+    this.register(new MavenToolchain())
+    this.register(new GradleToolchain())
+    this.register(new NodeToolchain())
+  }
+
+  /**
+   * Register a new or overriding ToolchainProvider.
+   */
+  register(provider: ToolchainProvider): void {
+    this.providers.set(provider.name, provider)
+  }
+
+  /**
+   * Remove a registered provider by name.
+   */
+  unregister(name: string): boolean {
+    return this.providers.delete(name)
+  }
+
+  /**
+   * Look up a registered provider by name.
+   */
+  get(name: string): ToolchainProvider | undefined {
+    const direct = this.providers.get(name)
+    if (direct) return direct
+    if (['pnpm', 'npm', 'yarn', 'bun'].includes(name)) {
+      return new NodeToolchain(name as import('./providers/NodeToolchain.js').NodePackageManager)
+    }
+    return undefined
+  }
+
+  /**
+   * List all registered providers sorted by priority (highest first).
+   */
+  list(): ToolchainProvider[] {
+    return Array.from(this.providers.values()).sort(
+      (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+    )
+  }
+
+  /**
+   * Detect which toolchain matches the directory.
+   */
+  async detect(projectDir: string): Promise<{ provider: ToolchainProvider; detection: DetectionResult } | null> {
+    const sorted = this.list()
+    for (const provider of sorted) {
+      const detection = await provider.detect(projectDir)
+      if (detection) {
+        return { provider, detection }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Resolve a toolchain for a directory, respecting an optional preferred toolchain name or options.
+   * If preferredName is provided, it takes precedence (explicit beats implicit detection).
+   * If fallback is provided, it is used only when automatic detection finds no matching manifest.
+   */
+  async resolve(
+    projectDir: string,
+    preferredOrOptions?: string | ResolveToolchainOptions
+  ): Promise<{ provider: ToolchainProvider; detection: DetectionResult }> {
+    let preferredName: string | undefined
+    let fallbackName: string | undefined
+
+    if (typeof preferredOrOptions === 'string') {
+      preferredName = preferredOrOptions
+    } else if (typeof preferredOrOptions === 'object' && preferredOrOptions !== null) {
+      preferredName = preferredOrOptions.preferred
+      fallbackName = preferredOrOptions.fallback
+    }
+
+    if (preferredName) {
+      const provider = this.get(preferredName)
+      if (!provider) {
+        throw new Error(
+          `Preferred toolchain '${preferredName}' is not registered. Available: ${Array.from(this.providers.keys()).join(', ')}`
+        )
+      }
+      const detection = await provider.detect(projectDir)
+      if (!detection) {
+        throw new Error(
+          `Preferred toolchain '${preferredName}' does not match project in '${projectDir}'.`
+        )
+      }
+      return {
+        provider,
+        detection
+      }
+    }
+
+    const detected = await this.detect(projectDir)
+    if (detected) {
+      return detected
+    }
+
+    if (fallbackName) {
+      const provider = this.get(fallbackName)
+      if (!provider) {
+        throw new Error(
+          `Fallback toolchain '${fallbackName}' is not registered. Available: ${Array.from(this.providers.keys()).join(', ')}`
+        )
+      }
+      return {
+        provider,
+        detection: { name: fallbackName, reason: `configured default (${fallbackName})` }
+      }
+    }
+
+    throw new Error(
+      `Could not determine toolchain for directory '${projectDir}'. ` +
+      `No pom.xml, build.gradle, or package.json found, and no matching registered toolchain detected.`
+    )
+  }
+
+  /**
+   * Reset registry to defaults.
+   */
+  reset(): void {
+    this.providers.clear()
+    this.registerDefaultProviders()
+  }
+}
+
+/** Global default ToolchainRegistry singleton */
+export const defaultToolchainRegistry = new ToolchainRegistry()
+
+export function registerToolchain(provider: ToolchainProvider): void {
+  defaultToolchainRegistry.register(provider)
+}
+
+export function resolveToolchain(
+  projectDir: string,
+  preferredOrOptions?: string | ResolveToolchainOptions
+): Promise<{ provider: ToolchainProvider; detection: DetectionResult }> {
+  return defaultToolchainRegistry.resolve(projectDir, preferredOrOptions)
+}

package/src/toolchain/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Toolchain SPI definitions for project type detection and build execution.
+ */
+
+export interface ProjectInfo {
+  name: string
+  version: string
+  fullName: string
+  namespace?: string
+}
+
+export interface DetectionResult {
+  name: string
+  reason: string
+}
+
+export interface ToolchainProvider {
+  /** Identifier of this toolchain, e.g. 'maven', 'gradle', 'node', 'go' */
+  readonly name: string
+  /**
+   * Detection and resolution priority. Higher priority is checked earlier.
+   * Enables custom plugins to override built-in toolchains.
+   */
+  readonly priority?: number
+
+  /** Check if a project directory matches this toolchain */
+  detect(projectDir: string): Promise<DetectionResult | null>
+
+  /** Extract project identity (name, version) from project manifests */
+  projectInfo(projectDir: string): Promise<ProjectInfo>
+
+  /** Install or fetch dependencies */
+  install(projectDir: string, flags?: string[]): Promise<void>
+
+  /** Run the primary build/package task */
+  build(projectDir: string, flags?: string[]): Promise<void>
+
+  /** Run an arbitrary task or script */
+  run?(projectDir: string, task: string, flags?: string[]): Promise<void>
+}

package/src/utils/mask.ts

@@ -0,0 +1,73 @@
+/**
+ * Secret masking heuristics and masking stream utilities.
+ */
+
+export const MASK = '********'
+
+const SECRET_WORDS = /(PASSWORD|PASSWD|PASSPHRASE|SECRET|TOKEN|CREDENTIAL|PRIVATE_KEY|PRIVATEKEY|APIKEY|KEYSTORE|SIGNATURE)/i
+const SECRET_TOKEN_BOUNDED = /(?:^|[_\-])(PASS|KEY|AUTH)(?:$|[_\-])/i
+const CAMEL_SECRET = /(?:Password|Passwd|Passphrase|Secret|Token|Credential|PrivateKey|ApiKey|Keystore|Signature)/
+const CAMEL_BOUNDED = /(?:^|[a-z0-9])(?:Pass|Key|Auth)(?:$|[A-Z0-9])/
+const LOCATION_NAME = /(_FILE|_PATH|_DIR|_DIRECTORY|_URL|_URI|_LOCATION|_NAME|_ID|_SOCK)$/i
+
+/** Does this variable or key name suggest its value is a secret? */
+export function isSecretKey(key: string): boolean {
+  if (!key) return false
+  if (LOCATION_NAME.test(key)) return false
+  if (SECRET_WORDS.test(key)) return true
+  if (SECRET_TOKEN_BOUNDED.test(key)) return true
+  if (CAMEL_SECRET.test(key)) return true
+  if (CAMEL_BOUNDED.test(key)) return true
+  return false
+}
+
+/**
+ * Mask secret substrings within a string log line.
+ */
+export function maskString(text: string, secretValues: string[]): string {
+  if (!text || secretValues.length === 0) return text
+  let result = text
+  for (const secret of secretValues) {
+    if (secret && secret.length >= 3) {
+      result = result.replaceAll(secret, MASK)
+    }
+  }
+  return result
+}
+
+/**
+ * Recursively mask values of secret-looking keys in an object.
+ */
+export function maskObject<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') return obj
+
+  // Preserve Date, Buffer, RegExp, Error
+  if (
+    obj instanceof Date ||
+    (typeof Buffer !== 'undefined' && Buffer.isBuffer(obj)) ||
+    obj instanceof RegExp ||
+    obj instanceof Error
+  ) {
+    return obj
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => maskObject(item)) as unknown as T
+  }
+
+  const output: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(obj)) {
+    if (isSecretKey(key)) {
+      if (Array.isArray(value)) {
+        output[key] = value.map(() => MASK)
+      } else {
+        output[key] = MASK
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      output[key] = maskObject(value)
+    } else {
+      output[key] = value
+    }
+  }
+  return output as T
+}

package/src/utils/template.ts

@@ -0,0 +1,62 @@
+/**
+ * Utilities for template string interpolation into command arguments.
+ */
+
+/**
+ * Turn a tagged template into an argument list (argv).
+ *
+ * Whitespace in literal parts separates arguments, whereas an interpolated value
+ * is preserved as a single argument regardless of whitespace or special characters.
+ * Array values expand into one argument per element.
+ */
+export function templateToArgv(strings: readonly string[], values: readonly unknown[]): string[] {
+  const argv: string[] = []
+  let token = ''
+  let started = false
+
+  const flush = () => {
+    if (started) {
+      argv.push(token)
+      token = ''
+      started = false
+    }
+  }
+
+  const append = (value: string) => {
+    token += value
+    started = true
+  }
+
+  for (let i = 0; i < strings.length; i++) {
+    for (const char of strings[i]) {
+      if (char === ' ' || char === '\t' || char === '\n' || char === '\r') {
+        flush()
+      } else {
+        append(char)
+      }
+    }
+
+    if (i < values.length) {
+      const value = values[i]
+
+      if (value === undefined || value === null) {
+        throw new Error(
+          `Command interpolation contains ${value === null ? 'null' : 'undefined'} ` +
+          `(value at index ${i}). Verify your variables are configured.`
+        )
+      }
+
+      if (Array.isArray(value)) {
+        flush()
+        for (const item of value) {
+          argv.push(String(item))
+        }
+      } else {
+        append(String(value))
+      }
+    }
+  }
+
+  flush()
+  return argv
+}