@ticatec/omniflow-core 0.1.1 → 0.2.0

package/docs/toolchain-extension.md

@@ -0,0 +1,301 @@
+# Toolchain SPI Extension & Registration Guide
+
+This document explains how to extend, register, and use custom build toolchains within `@ticatec/omniflow-core`.
+
+[中文文档](./toolchain-extension_CN.md)
+
+---
+
+## 1. Architectural Background
+
+In OmniFlow, a **Toolchain** encapsulates the build lifecycle and manifest conventions of a specific programming language ecosystem (such as Java Maven/Gradle, Node.js, Go, Rust, etc.). It exposes a unified interface:
+
+- **Detection (`detect`)**: Determines whether a source directory belongs to the toolchain.
+- **Identity & Metadata Extraction (`projectInfo`)**: Extracts project name, version, and coordinates from manifests (`pom.xml`, `package.json`, `go.mod`, `Cargo.toml`).
+- **Dependency Fetching (`install`)**: Downloads or synchronizes dependencies.
+- **Build Execution (`build`)**: Compiles, packages, and produces build artifacts.
+- **Arbitrary Task Execution (`run`)**: Executes arbitrary scripts or test suites.
+
+```
+                       ┌─────────────────────────┐
+                       │   ToolchainRegistry     │
+                       └───────────┬─────────────┘
+                                   │ Scan by priority (descending)
+         ┌─────────────────────────┼─────────────────────────┐
+         ▼                         ▼                         ▼
+┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
+│  GoToolchain     │      │ MavenToolchain   │      │ NodeToolchain    │
+│  (Custom, p=50)  │      │ (Built-in, p=30) │      │ (Built-in, p=10) │
+└──────────────────┘      └──────────────────┘      └──────────────────┘
+```
+
+OmniFlow Core ships with built-in providers for Maven (`priority: 30`), Gradle (`priority: 20`), and Node.js (`priority: 10`). Third-party plugins or internal repositories can register new language toolchains or override built-in behavior with higher priority values.
+
+---
+
+## 2. Interface Specification
+
+Custom toolchains must implement the `ToolchainProvider` interface (exported from `@ticatec/omniflow-core` or `@ticatec/omniflow-core/toolchain`):
+
+```typescript
+export interface ProjectInfo {
+  name: string
+  version: string
+  fullName: string
+  namespace?: string
+}
+
+export interface DetectionResult {
+  name: string
+  reason: string
+}
+
+export interface ToolchainProvider {
+  /** Unique identifier, e.g. 'go', 'rust', 'python', 'maven' */
+  readonly name: string
+
+  /**
+   * Detection and resolution priority (higher numbers are evaluated first).
+   * Built-in providers: Maven (30), Gradle (20), Node.js (10).
+   * Custom providers typically use values >= 50 to evaluate before built-ins.
+   */
+  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 (optional) */
+  run?(projectDir: string, task: string, flags?: string[]): Promise<void>
+}
+```
+
+> [!TIP]
+> When implementing `install`, `build`, and `run`, always use `shell.run` or `shell.sh` from `@ticatec/omniflow-core`. This guarantees automatic inheritance of the execution context (`cwd`, `env`), automatic `--dry-run` simulation interception, and sensitive credential masking.
+
+---
+
+## 3. Practical Example 1: Custom Go Toolchain
+
+The following example demonstrates adding complete Go build support to OmniFlow:
+
+```typescript
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  shell,
+  registerToolchain,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+
+export class GoToolchain implements ToolchainProvider {
+  readonly name = 'go'
+  readonly priority: number = 50 // Evaluated before built-ins (Maven 30, Gradle 20, Node 10)
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    const modPath = path.join(projectDir, 'go.mod')
+    try {
+      await fs.access(modPath)
+      return {
+        name: this.name,
+        reason: 'found go.mod'
+      }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    const modPath = path.join(projectDir, 'go.mod')
+    const content = await fs.readFile(modPath, 'utf-8')
+
+    // Parse 'module <name>' line
+    const match = content.match(/module\s+([^\s\r\n]+)/)
+    const moduleName = match ? match[1] : path.basename(projectDir)
+    const shortName = moduleName.split('/').pop() ?? moduleName
+
+    return {
+      name: shortName,
+      fullName: moduleName,
+      version: 'latest' // Go versions are commonly determined by Git tags
+    }
+  }
+
+  async install(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`go mod download ${flags}`
+  }
+
+  async build(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`go build -v -o dist/app . ${flags}`
+  }
+
+  async run(projectDir: string, task: string, flags: string[] = []): Promise<void> {
+    if (task === 'test') {
+      await shell.run({ cwd: projectDir })`go test ./... ${flags}`
+    } else {
+      await shell.run({ cwd: projectDir })`go run . ${flags}`
+    }
+  }
+}
+
+// Register into the global toolchain registry
+registerToolchain(new GoToolchain())
+```
+
+---
+
+## 4. Practical Example 2: Custom Rust (Cargo) Toolchain
+
+```typescript
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  shell,
+  registerToolchain,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+
+export class RustToolchain implements ToolchainProvider {
+  readonly name = 'rust'
+  readonly priority: number = 50
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    try {
+      await fs.access(path.join(projectDir, 'Cargo.toml'))
+      return { name: this.name, reason: 'found Cargo.toml' }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    const cargoPath = path.join(projectDir, 'Cargo.toml')
+    const content = await fs.readFile(cargoPath, 'utf-8')
+
+    const nameMatch = content.match(/name\s*=\s*"([^"]+)"/)
+    const verMatch = content.match(/version\s*=\s*"([^"]+)"/)
+
+    const name = nameMatch ? nameMatch[1] : path.basename(projectDir)
+    const version = verMatch ? verMatch[1] : '0.1.0'
+
+    return { name, fullName: name, version }
+  }
+
+  async install(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`cargo fetch ${flags}`
+  }
+
+  async build(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`cargo build --release ${flags}`
+  }
+}
+
+registerToolchain(new RustToolchain())
+```
+
+---
+
+## 5. Practical Example 3: Overriding Built-in Toolchains (Enterprise Maven Customization)
+
+**Scenario**: An enterprise policy mandates that all Java Maven builds must:
+1. Always point to an internal private nexus mirror with a customized `settings.xml`;
+2. Inject enterprise APM and vulnerability scanning flags;
+3. Never download directly from public central repositories.
+
+You can override the default `MavenToolchain` by registering a provider with the same `name: 'maven'`. `registerToolchain()` replaces the registered provider for that name, while specifying a `priority` controls its evaluation order in `detect()`:
+
+```typescript
+import {
+  shell,
+  registerToolchain,
+  MavenToolchain,
+  type ToolchainProvider
+} from '@ticatec/omniflow-core'
+
+export class EnterpriseMavenToolchain extends MavenToolchain {
+  readonly name = 'maven'
+  readonly priority: number = 50 // Evaluated earlier during automatic detection
+
+  private readonly customSettings = '/etc/omniflow/maven/settings-enterprise.xml'
+
+  override async build(projectDir: string, flags: string[] = []): Promise<void> {
+    const enterpriseFlags = [
+      '-s', this.customSettings,
+      '-Dorg.slf4j.simpleLogger.showDateTime=true',
+      ...flags
+    ]
+
+    await shell.run({ cwd: projectDir })`mvn clean package ${enterpriseFlags}`
+  }
+}
+
+// Register override
+registerToolchain(new EnterpriseMavenToolchain())
+```
+
+---
+
+## 6. Resolving and Executing Toolchains
+
+In runners or workflow steps, resolve toolchains agnostically using `resolveToolchain`:
+
+```typescript
+import { resolveToolchain } from '@ticatec/omniflow-core'
+
+async function buildProject(dir: string) {
+  // Automatically detects project type and returns matching provider & reason
+  const { provider, detection } = await resolveToolchain(dir)
+  console.log(`[Toolchain] Resolved ${provider.name}: ${detection.reason}`)
+
+  // Extract metadata
+  const info = await provider.projectInfo(dir)
+  console.log(`[Project] Building ${info.fullName}@${info.version}`)
+
+  // Install dependencies and run build
+  await provider.install(dir)
+  await provider.build(dir)
+}
+```
+
+### Specifying a Preferred Toolchain
+If a project contains multiple manifests (e.g. both `package.json` for frontend assets and `pom.xml` for backend packaging), pass a preferred toolchain name:
+
+```typescript
+// Explicitly force Maven resolution
+const { provider } = await resolveToolchain(dir, 'maven')
+await provider.build(dir)
+```
+
+---
+
+## 7. Isolated Testing Best Practices
+
+When unit testing toolchains, instantiate an isolated `ToolchainRegistry` to prevent mutating global state:
+
+```typescript
+import { ToolchainRegistry } from '@ticatec/omniflow-core/toolchain'
+import { GoToolchain } from './GoToolchain.js'
+
+describe('GoToolchain', () => {
+  it('should detect go project in an isolated registry', async () => {
+    // Pass false to create a fresh registry without default providers
+    const registry = new ToolchainRegistry(false)
+    registry.register(new GoToolchain())
+
+    const res = await registry.detect('/fixtures/sample-go-app')
+    expect(res?.provider.name).toBe('go')
+  })
+})
+```

package/docs/toolchain-extension_CN.md

@@ -0,0 +1,304 @@
+# Toolchain SPI 扩展与注册指南
+
+本文档介绍如何在 `@ticatec/omniflow-core` 中扩展、注册并使用自定义构建工具链（Toolchain）。
+
+---
+
+## 1. 概念与架构背景
+
+在 OmniFlow 中，**Toolchain（工具链）** 是对特定语言构建生态（如 Java Maven/Gradle、Node.js、Golang、Rust 等）的抽象封装。它定义了统一的生命周期与元数据接口：
+
+- **检测识别 (`detect`)**：判断某个源码目录是否属于该工具链管理的工程。
+- **元数据提取 (`projectInfo`)**：从工程描述文件（如 `pom.xml`, `package.json`, `go.mod`, `Cargo.toml`）中提取名称、版本、命名空间等。
+- **依赖拉取 (`install`)**：执行依赖下载与同步。
+- **打包构建 (`build`)**：执行标准编译和打包。
+- **通用任务执行 (`run`)**：执行自定义测试、代码检查或子脚本。
+
+```
+                       ┌─────────────────────────┐
+                       │   ToolchainRegistry     │
+                       └───────────┬─────────────┘
+                                   │ 按 priority 降序探测
+         ┌─────────────────────────┼─────────────────────────┐
+         ▼                         ▼                         ▼
+┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
+│  GoToolchain     │      │ MavenToolchain   │      │ NodeToolchain    │
+│  (Custom, p=50)  │      │ (Built-in, p=30) │      │ (Built-in, p=10) │
+└──────────────────┘      └──────────────────┘      └──────────────────┘
+```
+
+OmniFlow Core 内置了对 Maven (`priority: 30`)、Gradle (`priority: 20`) 与 Node.js (`priority: 10`) 的支持，开发者或第三方插件可以通过开放的 SPI 接口注册新的编程语言支持，或以更高的优先级覆盖内置工具链的行为。
+
+---
+
+## 2. 核心接口规范
+
+工具链必须实现 `ToolchainProvider` 接口（位于 `@ticatec/omniflow-core/toolchain` 或 `@ticatec/omniflow-core`）：
+
+```typescript
+export interface ProjectInfo {
+  name: string
+  version: string
+  fullName: string
+  namespace?: string
+}
+
+export interface DetectionResult {
+  name: string
+  reason: string
+}
+
+export interface ToolchainProvider {
+  /** 工具链唯一标识名，如 'go', 'rust', 'python', 'maven' */
+  readonly name: string
+
+  /**
+   * 探测与解析优先级（数值越大越优先探测）。
+   * 内置 Provider 优先级为：Maven (30)、Gradle (20)、Node.js (10)。
+   * 自定义 Provider 建议设置 >= 50 以优先于内置工具链探测。
+   */
+  readonly priority?: number
+
+  /** 检查指定目录是否符合当前工具链 */
+  detect(projectDir: string): Promise<DetectionResult | null>
+
+  /** 从工程配置中解析项目基本信息 */
+  projectInfo(projectDir: string): Promise<ProjectInfo>
+
+  /** 安装/拉取依赖 */
+  install(projectDir: string, flags?: string[]): Promise<void>
+
+  /** 执行标准构建/打包任务 */
+  build(projectDir: string, flags?: string[]): Promise<void>
+
+  /** 执行任意自定义任务或指令（可选） */
+  run?(projectDir: string, task: string, flags?: string[]): Promise<void>
+}
+```
+
+> [!TIP]
+> 在实现 `install`、`build`、`run` 时，强烈建议使用 `@ticatec/omniflow-core` 提供的 `shell.run` 或 `shell.sh`。这样会自动继承当前的上下文环境变量、工作目录，并自动获得 `--dry-run` 拦截和日志凭据脱敏能力。
+
+---
+
+## 3. 实战示例 1：扩展全新工具链（Golang）
+
+下面展示如何为 OmniFlow 添加对 Go 语言工程的完整构建支持：
+
+```typescript
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  shell,
+  registerToolchain,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+
+export class GoToolchain implements ToolchainProvider {
+  readonly name = 'go'
+  readonly priority: number = 50 // 优先级高于内置工具链（Maven 30, Gradle 20, Node 10）
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    const modPath = path.join(projectDir, 'go.mod')
+    try {
+      await fs.access(modPath)
+      return {
+        name: this.name,
+        reason: 'found go.mod'
+      }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    const modPath = path.join(projectDir, 'go.mod')
+    const content = await fs.readFile(modPath, 'utf-8')
+
+    // 简单解析 module <name>
+    const match = content.match(/module\s+([^\s\r\n]+)/)
+    const moduleName = match ? match[1] : path.basename(projectDir)
+    const shortName = moduleName.split('/').pop() ?? moduleName
+
+    return {
+      name: shortName,
+      fullName: moduleName,
+      version: 'latest' // Go 工程版本多取自 Git Tag
+    }
+  }
+
+  async install(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`go mod download ${flags}`
+  }
+
+  async build(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`go build -v -o dist/app . ${flags}`
+  }
+
+  async run(projectDir: string, task: string, flags: string[] = []): Promise<void> {
+    if (task === 'test') {
+      await shell.run({ cwd: projectDir })`go test ./... ${flags}`
+    } else {
+      await shell.run({ cwd: projectDir })`go run . ${flags}`
+    }
+  }
+}
+
+// 注册到全局工具链注册表
+registerToolchain(new GoToolchain())
+```
+
+---
+
+## 4. 实战示例 2：实战扩展 Rust (Cargo)
+
+```typescript
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import {
+  shell,
+  registerToolchain,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+
+export class RustToolchain implements ToolchainProvider {
+  readonly name = 'rust'
+  readonly priority: number = 50
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    try {
+      await fs.access(path.join(projectDir, 'Cargo.toml'))
+      return { name: this.name, reason: 'found Cargo.toml' }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    const cargoPath = path.join(projectDir, 'Cargo.toml')
+    const content = await fs.readFile(cargoPath, 'utf-8')
+
+    const nameMatch = content.match(/name\s*=\s*"([^"]+)"/)
+    const verMatch = content.match(/version\s*=\s*"([^"]+)"/)
+
+    const name = nameMatch ? nameMatch[1] : path.basename(projectDir)
+    const version = verMatch ? verMatch[1] : '0.1.0'
+
+    return { name, fullName: name, version }
+  }
+
+  async install(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`cargo fetch ${flags}`
+  }
+
+  async build(projectDir: string, flags: string[] = []): Promise<void> {
+    await shell.run({ cwd: projectDir })`cargo build --release ${flags}`
+  }
+}
+
+registerToolchain(new RustToolchain())
+```
+
+---
+
+## 5. 实战示例 3：覆写内置工具链（企业级 Maven 定制）
+
+**业务场景**：企业规定 Java 项目必须：
+1. 统一使用内网特定镜像仓库和私有 `settings.xml`；
+2. 注入企业代码安全探针参数；
+3. 禁止直接访问外部公共中央仓库。
+
+通过注册同名 Provider（`name: 'maven'`）可直接替换内置实现，配合显式声明 `priority`（如 `priority: number = 50`）可控制其在自动探测链中的优先级：
+
+```typescript
+import {
+  shell,
+  registerToolchain,
+  MavenToolchain,
+  type ToolchainProvider
+} from '@ticatec/omniflow-core'
+
+export class EnterpriseMavenToolchain extends MavenToolchain {
+  // 保持与内置相同的 name: 'maven'
+  readonly name = 'maven'
+  // 设置显式数值类型，并在探测链中享有更高优先级
+  readonly priority: number = 50
+
+  private readonly customSettings = '/etc/omniflow/maven/settings-enterprise.xml'
+
+  override async build(projectDir: string, flags: string[] = []): Promise<void> {
+    const enterpriseFlags = [
+      '-s', this.customSettings,
+      '-Dorg.slf4j.simpleLogger.showDateTime=true',
+      ...flags
+    ]
+
+    // 调用定制构建命令，直接以数组形式传递 flags
+    await shell.run({ cwd: projectDir })`mvn clean package ${enterpriseFlags}`
+  }
+}
+
+// 注册覆盖
+registerToolchain(new EnterpriseMavenToolchain())
+```
+
+---
+
+## 6. 使用与解析工具链
+
+在流水线执行器（Runner）或业务插件中，无需关心底层具体是哪种语言，通过 `resolveToolchain` 统一调用：
+
+```typescript
+import { resolveToolchain } from '@ticatec/omniflow-core'
+
+async function buildProject(dir: string) {
+  // 自动探测，返回命中的 provider 和识别原因
+  const { provider, detection } = await resolveToolchain(dir)
+  console.log(`[Toolchain] 命中 ${provider.name}: ${detection.reason}`)
+
+  // 读取工程信息
+  const info = await provider.projectInfo(dir)
+  console.log(`[Project] 正在构建 ${info.fullName} (${info.version})`)
+
+  // 安装依赖
+  await provider.install(dir)
+
+  // 执行构建
+  await provider.build(dir)
+}
+```
+
+### 指定首选工具链
+如果某个目录下既有 `package.json`（前端脚手架），又有 Java `pom.xml`（后端集成），可以在调用 `resolveToolchain` 时传入显式偏好：
+
+```typescript
+// 强制使用 maven 工具链处理该目录
+const { provider } = await resolveToolchain(dir, 'maven')
+await provider.build(dir)
+```
+
+---
+
+## 7. 独立注册表与测试最佳实践
+
+在编写单元测试时，如果需要隔离环境，避免全局状态污染，可以实例化独立的 `ToolchainRegistry`：
+
+```typescript
+import { ToolchainRegistry } from '@ticatec/omniflow-core/toolchain'
+import { GoToolchain } from './GoToolchain.js'
+
+describe('GoToolchain', () => {
+  it('should detect go project in isolated registry', async () => {
+    // 传入 false 不加载默认 Provider，得到一个完全纯净的注册表
+    const registry = new ToolchainRegistry(false)
+    registry.register(new GoToolchain())
+
+    const res = await registry.detect('/fixtures/sample-go-app')
+    expect(res?.provider.name).toBe('go')
+  })
+})
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@ticatec/omniflow-core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Core primitives, execution context, and toolchain SPI for OmniFlow CI/CD orchestrator",
+  "homepage": "https://github.com/ticatec/omniflow#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ticatec/omniflow.git",
+    "directory": "omniflow-core"
+  },
+  "bugs": {
+    "url": "https://github.com/ticatec/omniflow/issues"
+  },
+  "author": "Henry Feng <huili.f@gmail.com>",
+  "keywords": [
+    "ci",
+    "cd",
+    "pipeline",
+    "orchestration",
+    "primitives",
+    "toolchain"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,6 +66,10 @@
   },
   "files": [
     "dist",
+    "src",
+    "docs/toolchain-extension.md",
+    "docs/toolchain-extension_CN.md",
+    "LICENSE",
     "README.md",
     "README_CN.md"
   ],