@ticatec/omniflow-core 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ticatec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,11 @@
-# @omniflow/core
+# @ticatec/omniflow-core
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 
 [中文文档](./README_CN.md)
 
-**@omniflow/core** is the foundational core package for the OmniFlow CI/CD orchestrator. It provides execution context management, standard operational primitives (`shell`, `ssh`, `git`, `docker`), sensitive credential masking, and an extensible Toolchain SPI.
+**@ticatec/omniflow-core** is the foundational core package for the OmniFlow CI/CD orchestrator. It provides execution context management, standard operational primitives (`shell`, `ssh`, `git`, `docker`), sensitive credential masking, and an extensible Toolchain SPI.
 
 ---
 
@@ -14,7 +14,7 @@
 - **Static Decoupled Primitives**: Import `shell`, `ssh`, `git`, and `docker` directly. No cumbersome `ctx.commands` or object passing required.
 - **Transparent Context Injection (`AsyncLocalStorage`)**: Primitives automatically resolve `cwd`, environment variables `env`, and `logger` from the active async call context.
 - **Automatic `--dry-run` Interception**: When running in simulation mode, destructive operations are intercepted by the core layer automatically, logged safely, and mocked without extra boilerplate in plugins.
-- **Automatic Secret Masking**: Credentials and sensitive tokens in logs and commands are automatically masked (`***`).
+- **Automatic Secret Masking**: Credentials and sensitive tokens in logs and commands are automatically masked (`********`).
 - **Extensible Toolchain SPI**: Built-in support for Maven, Gradle, and Node.js (pnpm / yarn / npm / bun), with priority-based override and registration for custom language toolchains (e.g. Go, Rust, Python).
 
 ---
@@ -24,12 +24,12 @@
 ```
 ┌────────────────────────────────────────────────────────┐
 │             Plugin / Pipeline Command                  │
-│  import { shell, ssh, git, docker } from '@omniflow/core'│
+│  import { shell, ssh, git, docker } from '@ticatec/omniflow-core'│
 └─────────────────────────┬──────────────────────────────┘
                           │ calls primitives
                           ▼
 ┌────────────────────────────────────────────────────────┐
-│                   @omniflow/core                       │
+│                   @ticatec/omniflow-core                       │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │ AsyncLocalStorage Context (cwd, env, dryRun, log)│  │
 │  └──────────────────────┬───────────────────────────┘  │
@@ -51,9 +51,9 @@
 ## Installation
 
 ```bash
-pnpm add @omniflow/core
+pnpm add @ticatec/omniflow-core
 # or
-npm install @omniflow/core
+npm install @ticatec/omniflow-core
 ```
 
 Requires **Node.js >= 20.0.0**.
@@ -66,7 +66,7 @@ Requires **Node.js >= 20.0.0**.
 Executes local shell commands using safe tagged template literals or string execution.
 
 ```typescript
-import { shell } from '@omniflow/core'
+import { shell } from '@ticatec/omniflow-core'
 
 // Tagged template execution (safely splits arguments without shell injection vulnerabilities)
 await shell.run`mvn clean package -DskipTests`
@@ -83,16 +83,20 @@ console.log(res.stdout, res.exitCode)
 ```
 
 **Dry-Run & Context Awareness**:
-Inside a `runWithContext` scope with `dryRun: true`, `shell.run` and `shell.sh` will print the planned command to the context logger and return mock results (`{ stdout: '[dry-run] ...', exitCode: 0 }`) without executing.
+Inside a `runWithContext` scope with `dryRun: true`, `shell.run`, `shell.sh`, and `ssh.exec` will print the planned command to the context logger and return clean mock results (`{ stdout: '', stderr: '', exitCode: 0, failed: false }`) without executing or polluting stdout.
+
+> [!NOTE]
+> **Credential Masking & Tail Buffering**: Output streams piped to `logFile` pass through a stateful transform that prevents secret leakage across chunk boundaries by buffering a sliding tail up to `maxSecretLen - 1` bytes. When exceptionally large single-line secrets (e.g. 64KB tokens or keys) are configured in the environment, log output chunks smaller than the tail buffer are retained until the buffer capacity is reached or the stream completes (`flush`), guaranteeing 100% masking coverage before emitting to disk.
 
 ---
 
 ### 2. `ssh`
-Executes remote commands and securely copies files via SSH/SCP with built-in connection pooling.
+Executes remote commands and securely copies files via SSH/SCP with configuration-based target resolution.
 
 ```typescript
-import { ssh } from '@omniflow/core'
+import { ssh } from '@ticatec/omniflow-core'
 
+// Option A: Explicit connection target
 const target = {
   host: 'prod-app-01.internal',
   user: 'deploy',
@@ -105,6 +109,27 @@ await ssh.exec(target, 'systemctl restart my-app.service')
 
 // File transfer (SCP)
 await ssh.cp(target, 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
+
+// Option B: Named targets via ssh.configure()
+ssh.configure('prod', {
+  host: 'prod-app-01.internal',
+  user: 'deploy',
+  port: 22,
+  privateKeyFile: '/home/deploy/.ssh/id_rsa'
+})
+
+// Call by target name directly
+await ssh.exec('prod', 'uptime')
+await ssh.cp('prod', 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
+
+// Clean up singleton config in tests:
+ssh.reset()
+
+// Option C: Isolated instance without touching module-level singleton
+const client = ssh.createClient({
+  staging: { host: 'staging.internal', user: 'ci', privateKeyFile: '~/.ssh/id_rsa' }
+})
+await client.exec('staging', 'hostname')
 ```
 
 ---
@@ -113,7 +138,7 @@ await ssh.cp(target, 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
 Provides essential Git repository inspection and workspace lifecycle management.
 
 ```typescript
-import { git } from '@omniflow/core'
+import { git } from '@ticatec/omniflow-core'
 
 const branch = await git.currentBranch()
 const commit = await git.currentCommit()
@@ -132,12 +157,11 @@ await git.checkout('release/v1.0')
 Encapsulates common container build, tag, push, and compose orchestration.
 
 ```typescript
-import { docker } from '@omniflow/core'
+import { docker } from '@ticatec/omniflow-core'
 
 // Build and tag
 await docker.build({
-  image: 'registry.internal/api',
-  tag: 'v1.2.0',
+  image: 'registry.internal/api:v1.2.0',
   dockerfile: 'Dockerfile.prod',
   buildArgs: { NODE_ENV: 'production' }
 })
@@ -146,8 +170,8 @@ await docker.build({
 await docker.push('registry.internal/api:v1.2.0')
 
 // Docker Compose management
-await docker.composeUp({ file: 'docker-compose.prod.yml', detached: true })
-await docker.composeDown({ file: 'docker-compose.prod.yml' })
+await docker.composeUp({ files: 'docker-compose.prod.yml', detach: true })
+await docker.composeDown({ files: 'docker-compose.prod.yml' })
 ```
 
 ---
@@ -158,23 +182,20 @@ The execution context manages runtime configuration, logging, and environment va
 
 ### Runner / Orchestrator Example:
 ```typescript
-import { runWithContext, createMockContext } from '@omniflow/core'
+import { runWithContext, createMockContext } from '@ticatec/omniflow-core'
 
-const ctx = {
+const ctx = createMockContext({
   runId: 'run-20260912-001',
   project: 'order-service',
-  env: 'staging',
+  environment: 'staging',
   dryRun: false,
   workspace: '/workspaces/order-service',
-  variables: { REGISTRY: 'harbor.company.com' },
-  secrets: { DOCKER_TOKEN: 'secret-token-value' },
-  logger: {
-    info: (msg) => console.log(`[INFO] ${msg}`),
-    warn: (msg) => console.warn(`[WARN] ${msg}`),
-    error: (msg) => console.error(`[ERROR] ${msg}`),
-    debug: (msg) => console.debug(`[DEBUG] ${msg}`)
+  projectRoot: '/workspaces/order-service',
+  env: {
+    REGISTRY: 'harbor.company.com',
+    DOCKER_TOKEN: 'secret-token-value'
   }
-}
+})
 
 await runWithContext(ctx, async () => {
   // Any function called here (directly or deeply nested) can call getContext()
@@ -185,11 +206,11 @@ await runWithContext(ctx, async () => {
 
 ### Plugin / Step Example:
 ```typescript
-import { getContext, tryGetContext, shell } from '@omniflow/core'
+import { getContext, tryGetContext, shell } from '@ticatec/omniflow-core'
 
 export async function myPluginTask() {
   const ctx = getContext() // Throws if outside runWithContext
-  ctx.logger.info(`Building in ${ctx.workspace} for ${ctx.env}`)
+  ctx.logger.info(`Building in ${ctx.workspace} for environment ${ctx.environment}`)
 
   await shell.run`npm test`
 }
@@ -202,13 +223,13 @@ export async function myPluginTask() {
 OmniFlow Core abstracts language build systems using a clean Service Provider Interface (SPI).
 
 ### Built-in Toolchains
-1. **Maven** (`MavenToolchain`): Detects `pom.xml`, parses groupId/artifactId/version, runs `./mvnw` or `mvn`.
-2. **Gradle** (`GradleToolchain`): Detects `build.gradle` / `build.gradle.kts`, resolves Gradle Wrapper `./gradlew`, generates build commands.
-3. **Node** (`NodeToolchain`): Detects `package.json`, auto-selects `pnpm`, `yarn`, `npm`, or `bun` from lockfiles, parses package coordinates.
+1. **Maven** (`MavenToolchain`): Detects `pom.xml`, parses groupId/artifactId/version, runs `./mvnw` or `mvn` (priority: 30).
+2. **Gradle** (`GradleToolchain`): Detects `build.gradle` / `build.gradle.kts`, resolves Gradle Wrapper `./gradlew`, generates build commands (priority: 20).
+3. **Node** (`NodeToolchain`): Detects `package.json`, auto-selects `pnpm`, `yarn`, `npm`, or `bun` from lockfiles, parses package coordinates (priority: 10).
 
 ### Detecting and Using Toolchains:
 ```typescript
-import { resolveToolchain } from '@omniflow/core'
+import { resolveToolchain } from '@ticatec/omniflow-core'
 
 const { provider, detection } = await resolveToolchain('/path/to/project')
 console.log(`Detected toolchain ${provider.name} because: ${detection.reason}`)
@@ -221,41 +242,78 @@ await provider.install('/path/to/project')
 await provider.build('/path/to/project', ['-DskipTests'])
 ```
 
+> [!NOTE]
+> **Reproducible CI Installation**: `NodeToolchain.install()` automatically enforces immutable lockfile installations (`npm ci`, `pnpm install --frozen-lockfile`, `yarn install --frozen-lockfile` / `--immutable`, `bun install --frozen-lockfile`) whenever a lockfile is present in the project directory, preventing accidental lockfile mutation or dependency drift during automated CI/CD runs. If no lockfile exists in a new project, it falls back to standard package installation without error.
+
 ### Registering Custom / Overriding Toolchains:
 ```typescript
-import { registerToolchain, type ToolchainProvider } from '@omniflow/core'
-
-const goToolchain: ToolchainProvider = {
-  name: 'go',
-  priority: 20, // Higher priority takes precedence over lower priority providers
-  detect: async (cwd) => {
-    // Check if go.mod exists
-    return { detected: true, confidence: 0.95 }
-  },
-  getProjectInfo: async (cwd) => ({
-    name: 'user-service',
-    version: '1.0.0'
-  }),
-  getBuildCommand: (cwd, options) => 'go build -v -o dist/app ./cmd/main.go'
+import {
+  registerToolchain,
+  shell,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export class GoToolchain implements ToolchainProvider {
+  readonly name = 'go'
+  readonly priority: number = 50 // Higher priority takes precedence during automatic detection
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    try {
+      await fs.access(path.join(projectDir, 'go.mod'))
+      return { name: this.name, reason: 'found go.mod' }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    return { name: 'user-service', version: '1.0.0', fullName: 'user-service' }
+  }
+
+  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}`
+  }
 }
 
-registerToolchain(goToolchain)
+registerToolchain(new GoToolchain())
 ```
 
 > For a complete step-by-step guide on creating custom toolchains (Go, Rust) and enterprise overrides, see [Toolchain Extension Guide](./docs/toolchain-extension.md).
 
 ---
 
+## Breaking Changes in v0.2.0
+
+If upgrading from an earlier experimental version, note the following breaking API and behavior changes:
+
+1. **`--dry-run` simulation output**: In dry-run mode, commands now return `{ stdout: '', stderr: '', exitCode: 0, failed: false }` instead of synthetic strings like `"[DRY-RUN] ..."`. The simulated command is logged cleanly to `ctx.logger.info` without polluting stdout.
+2. **`docker.build` image requirement**: The `image` property in `DockerBuildOptions` is now strictly required. Implicit defaulting to `'latest'` and undocumented alias parameters (`tag`, `tags`) have been removed to avoid silent misconfiguration.
+3. **`docker.composeUp` property names**: Standardized on `files?: string | string[]` and `detach?: boolean`. Legacy aliases (`file`, `detached`) have been removed.
+4. **`ssh` configuration naming**: Target SSH configuration adheres strictly to camelCase: `privateKey`, `privateKeyFile`. Deprecated snake_case properties (`private_key`, `private_key_file`) have been removed.
+5. **`resolveToolchain` options**: Options are normalized to `{ preferred?: string; fallback?: string }`. Deprecated alias `configured` has been removed.
+6. **Command spawn failure exit code**: When a subprocess fails to spawn (e.g. executable not found), the runner returns `exitCode: -1` and `failed: true` instead of mistakenly reporting exit code `0`.
+7. **`git.resetHard` & `git.checkout` string argument**: In v0.1.x, passing a single string argument was interpreted as the working directory (`resetHard(dir?, target?)`, `checkout(dir?, ref?)`). In v0.2.0, a bare string argument designates the target commit/ref (`resetHard(target?: string | GitResetOptions)`, `checkout(ref?: string | GitCheckoutOptions)`). To specify an explicit working directory, pass an options object with `dir`: `{ dir: '/path/to/repo' }`.
+
+---
+
 ## Subpath Exports
 
-`@omniflow/core` supports clean subpath imports in accordance with modern ESM standards:
+`@ticatec/omniflow-core` supports clean subpath imports in accordance with modern ESM standards:
 
 | Export Path | Description |
 |:---|:---|
-| `@omniflow/core` | Full bundle: context, primitives, toolchain SPI, and utils |
-| `@omniflow/core/context` | Execution context, `AsyncLocalStorage`, and mocking utilities |
-| `@omniflow/core/primitives` | Core commands (`shell`, `ssh`, `git`, `docker`) |
-| `@omniflow/core/toolchain` | Toolchain SPI, registry, and built-in providers |
+| `@ticatec/omniflow-core` | Full bundle: context, primitives, toolchain SPI, and utils |
+| `@ticatec/omniflow-core/context` | Execution context, `AsyncLocalStorage`, and mocking utilities |
+| `@ticatec/omniflow-core/primitives` | Core commands (`shell`, `ssh`, `git`, `docker`) |
+| `@ticatec/omniflow-core/toolchain` | Toolchain SPI, registry, and built-in providers |
 
 ---
 

package/README_CN.md

@@ -1,20 +1,20 @@
-# @omniflow/core
+# @ticatec/omniflow-core
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
 
 [English](./README.md)
 
-**@omniflow/core** 是 OmniFlow CI/CD 统一编排器的基础核心库。它提供了运行时执行上下文管理、标准化命令原语（`shell`、`ssh`、`git`、`docker`）、敏感凭据脱敏以及可扩展的构建工具链 SPI（Toolchain SPI）。
+**@ticatec/omniflow-core** 是 OmniFlow CI/CD 统一编排器的基础核心库。它提供了运行时执行上下文管理、标准化命令原语（`shell`、`ssh`、`git`、`docker`）、敏感凭据脱敏以及可扩展的构建工具链 SPI（Toolchain SPI）。
 
 ---
 
 ## 核心特性
 
-- **原语与上下文解耦**：开发者与插件作者可直接通过静态 `import { shell, ssh, git, docker } from '@omniflow/core'` 导入命令，无需在函数间层层显式传递 `ctx`，移除原有的 `ctx.commands` 耦合。
+- **原语与上下文解耦**：开发者与插件作者可直接通过静态 `import { shell, ssh, git, docker } from '@ticatec/omniflow-core'` 导入命令，无需在函数间层层显式传递 `ctx`，移除原有的 `ctx.commands` 耦合。
 - **透明上下文注入 (`AsyncLocalStorage`)**：底层基于 Node.js 原生 `AsyncLocalStorage`，基础原语在被调用时，会自动从当前的异步执行链路中解析 `cwd`（工作目录）、`env`（环境变量）、`dryRun`（模拟模式）与 `logger`。
 - **开箱即用的 `--dry-run` 拦截保护**：在模拟运行模式下，破坏性操作（执行脚本、远程 SSH、推送镜像等）均由 Core 层底层自动拦截，安全记录日志并返回模拟结果，插件层无需编写冗余的 `if (ctx.dryRun)` 逻辑。
-- **敏感信息自动脱敏 (Masking)**：命令参数与环境变量中包含的敏感词（如 `token`、`secret`、`password`、`key`）在格式化及输出至日志时自动替换为 `***`，杜绝日志泄露。
+- **敏感信息自动脱敏 (Masking)**：命令参数与环境变量中包含的敏感词（如 `token`、`secret`、`password`、`key`）在格式化及输出至日志时自动替换为 `********`，杜绝日志泄露。
 - **统一可扩展的 Toolchain SPI**：内置对 Maven、Gradle、Node.js（自动识别 pnpm / yarn / npm / bun）的识别与命令生成，同时支持第三方插件按优先级注册与覆盖扩展（如 Go、Rust、Python 等）。
 
 ---
@@ -24,12 +24,12 @@
 ```
 ┌────────────────────────────────────────────────────────┐
 │                   插件 / 流水线命令                      │
-│  import { shell, ssh, git, docker } from '@omniflow/core'│
+│  import { shell, ssh, git, docker } from '@ticatec/omniflow-core'│
 └─────────────────────────┬──────────────────────────────┘
                           │ 直接调用底层原语
                           ▼
 ┌────────────────────────────────────────────────────────┐
-│                   @omniflow/core                       │
+│                   @ticatec/omniflow-core                       │
 │  ┌──────────────────────────────────────────────────┐  │
 │  │ AsyncLocalStorage 上下文 (cwd, env, dryRun, log)  │  │
 │  └──────────────────────┬───────────────────────────┘  │
@@ -51,9 +51,9 @@
 ## 安装
 
 ```bash
-pnpm add @omniflow/core
+pnpm add @ticatec/omniflow-core
 # 或
-npm install @omniflow/core
+npm install @ticatec/omniflow-core
 ```
 
 运行环境要求：**Node.js >= 20.0.0**。
@@ -66,7 +66,7 @@ npm install @omniflow/core
 用于执行本地 Shell 命令，推荐使用标签模板字符串（Tagged Template Literals）方式执行，原生防止命令行注入。
 
 ```typescript
-import { shell } from '@omniflow/core'
+import { shell } from '@ticatec/omniflow-core'
 
 // 标签模板安全执行（自动拆分参数，防止参数注入）
 await shell.run`mvn clean package -DskipTests`
@@ -83,16 +83,20 @@ console.log(res.stdout, res.exitCode)
 ```
 
 **Dry-Run 机制**：
-在包含 `dryRun: true` 的 `runWithContext` 环境中，`shell.run` 和 `shell.sh` 会自动将待执行命令格式化并打入当前日志，同时返回 `{ stdout: '[dry-run] ...', exitCode: 0 }`，不会在系统上实际派生子进程。
+在包含 `dryRun: true` 的 `runWithContext` 环境中，`shell.run`、`shell.sh` 与 `ssh.exec` 会自动将待执行命令格式化并打入当前日志，同时返回纯净的默认结果（`{ stdout: '', stderr: '', exitCode: 0, failed: false }`），不会在系统上实际派生子进程，也不会用假字符串污染 stdout。
+
+> [!NOTE]
+> **凭据脱敏与尾缓冲机制**：输出写入 `logFile` 时会经过有状态 Transform 流处理，在数据块（chunk）边界保留长度为 `maxSecretLen - 1` 的滑动尾缓冲以防止凭据跨块泄漏。当环境中配置了极长单行凭据（如 64KB 的 Token 或密钥段）时，小于尾缓冲容量的日志输出会暂存在流缓冲中，直到后续输出填满缓冲或流结束（flush）时全量脱敏刷盘，确保跨块切分下 100% 零泄露。
 
 ---
 
 ### 2. `ssh`
-提供跨节点远程命令执行与基于 SCP 的文件安全传输，内置连接池复用机制。
+提供跨节点远程命令执行与基于 SCP 的文件安全传输，支持配置化目标解析与安全执行。
 
 ```typescript
-import { ssh } from '@omniflow/core'
+import { ssh } from '@ticatec/omniflow-core'
 
+// 方式 A：显式连接目标对象
 const target = {
   host: 'prod-app-01.internal',
   user: 'deploy',
@@ -105,6 +109,27 @@ await ssh.exec(target, 'systemctl restart my-app.service')
 
 // 文件安全分发 (SCP)
 await ssh.cp(target, 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
+
+// 方式 B：通过 ssh.configure() 注册命名主机
+ssh.configure('prod', {
+  host: 'prod-app-01.internal',
+  user: 'deploy',
+  port: 22,
+  privateKeyFile: '/home/deploy/.ssh/id_rsa'
+})
+
+// 直接按别名调用
+await ssh.exec('prod', 'uptime')
+await ssh.cp('prod', 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
+
+// 测试清理单例配置：
+ssh.reset()
+
+// 方式 C：创建独立实例，避免污染模块级单例
+const client = ssh.createClient({
+  staging: { host: 'staging.internal', user: 'ci', privateKeyFile: '~/.ssh/id_rsa' }
+})
+await client.exec('staging', 'hostname')
 ```
 
 ---
@@ -113,7 +138,7 @@ await ssh.cp(target, 'dist/app.tar.gz', '/opt/deploy/app.tar.gz')
 提供仓库状态感知、分支切换、远端同步与工作区重置原语。
 
 ```typescript
-import { git } from '@omniflow/core'
+import { git } from '@ticatec/omniflow-core'
 
 const branch = await git.currentBranch()
 const commit = await git.currentCommit()
@@ -132,12 +157,11 @@ await git.checkout('release/v1.0')
 封装常见的容器构建、打标签、推送与 Compose 编排生命周期。
 
 ```typescript
-import { docker } from '@omniflow/core'
+import { docker } from '@ticatec/omniflow-core'
 
 // 镜像构建
 await docker.build({
-  image: 'registry.internal/api',
-  tag: 'v1.2.0',
+  image: 'registry.internal/api:v1.2.0',
   dockerfile: 'Dockerfile.prod',
   buildArgs: { NODE_ENV: 'production' }
 })
@@ -146,8 +170,8 @@ await docker.build({
 await docker.push('registry.internal/api:v1.2.0')
 
 // Docker Compose 服务生命周期管理
-await docker.composeUp({ file: 'docker-compose.prod.yml', detached: true })
-await docker.composeDown({ file: 'docker-compose.prod.yml' })
+await docker.composeUp({ files: 'docker-compose.prod.yml', detach: true })
+await docker.composeDown({ files: 'docker-compose.prod.yml' })
 ```
 
 ---
@@ -158,23 +182,20 @@ await docker.composeDown({ file: 'docker-compose.prod.yml' })
 
 ### 运行器 (Runner) 示例：
 ```typescript
-import { runWithContext, createMockContext } from '@omniflow/core'
+import { runWithContext, createMockContext } from '@ticatec/omniflow-core'
 
-const ctx = {
+const ctx = createMockContext({
   runId: 'run-20260912-001',
   project: 'order-service',
-  env: 'staging',
+  environment: 'staging',
   dryRun: false,
   workspace: '/workspaces/order-service',
-  variables: { REGISTRY: 'harbor.company.com' },
-  secrets: { DOCKER_TOKEN: 'secret-token-value' },
-  logger: {
-    info: (msg) => console.log(`[INFO] ${msg}`),
-    warn: (msg) => console.warn(`[WARN] ${msg}`),
-    error: (msg) => console.error(`[ERROR] ${msg}`),
-    debug: (msg) => console.debug(`[DEBUG] ${msg}`)
+  projectRoot: '/workspaces/order-service',
+  env: {
+    REGISTRY: 'harbor.company.com',
+    DOCKER_TOKEN: 'secret-token-value'
   }
-}
+})
 
 await runWithContext(ctx, async () => {
   // 在此处调用链中的任何深层异步函数，均可安全访问上下文
@@ -184,11 +205,11 @@ await runWithContext(ctx, async () => {
 
 ### 插件 (Plugin) 内部调用示例：
 ```typescript
-import { getContext, tryGetContext, shell } from '@omniflow/core'
+import { getContext, tryGetContext, shell } from '@ticatec/omniflow-core'
 
 export async function myPluginTask() {
   const ctx = getContext() // 若不在 runWithContext 环境中则抛出明确错误
-  ctx.logger.info(`正在构建工作区 ${ctx.workspace}，目标环境：${ctx.env}`)
+  ctx.logger.info(`正在构建工作区 ${ctx.workspace}，目标环境：${ctx.environment}`)
 
   // 底层 shell 自动采用 ctx.workspace 作为 cwd，自动继承环境变量
   await shell.run`npm test`
@@ -202,13 +223,13 @@ export async function myPluginTask() {
 OmniFlow Core 将不同编程语言的构建体系抽象为统一的 Service Provider Interface (SPI)。
 
 ### 内置工具链
-1. **Maven** (`MavenToolchain`)：检测 `pom.xml`，解析 groupId/artifactId/version 坐标，优先调用 `./mvnw` 或 `mvn`。
-2. **Gradle** (`GradleToolchain`)：检测 `build.gradle` / `build.gradle.kts`，优先使用 Gradle Wrapper `./gradlew`，支持多项目构建。
-3. **Node** (`NodeToolchain`)：检测 `package.json`，根据 lock 文件自动选择 `pnpm`、`yarn`、`npm` 或 `bun`，提取包名与版本。
+1. **Maven** (`MavenToolchain`)：检测 `pom.xml`，解析 groupId/artifactId/version 坐标，优先调用 `./mvnw` 或 `mvn`（优先级：30）。
+2. **Gradle** (`GradleToolchain`)：检测 `build.gradle` / `build.gradle.kts`，优先使用 Gradle Wrapper `./gradlew`，支持多项目构建（优先级：20）。
+3. **Node** (`NodeToolchain`)：检测 `package.json`，根据 lock 文件自动选择 `pnpm`、`yarn`、`npm` 或 `bun`，提取包名与版本（优先级：10）。
 
 ### 使用与解析工具链：
 ```typescript
-import { resolveToolchain } from '@omniflow/core'
+import { resolveToolchain } from '@ticatec/omniflow-core'
 
 const { provider, detection } = await resolveToolchain('/path/to/project')
 console.log(`检测到工具链 ${provider.name}，原因: ${detection.reason}`)
@@ -221,42 +242,79 @@ await provider.install('/path/to/project')
 await provider.build('/path/to/project', ['-DskipTests'])
 ```
 
+> [!NOTE]
+> **可重现的 CI 安装策略**：`NodeToolchain.install()` 默认遵循 CI/CD 环境的最佳实践——当工程目录下存在 lockfile 时自动启用严格锁定模式（`npm ci`、`pnpm install --frozen-lockfile`、`yarn install --frozen-lockfile` / `--immutable`、`bun install --frozen-lockfile`），防止流水线静默篡改 lockfile 或引入未经锁定的依赖版本；新仓库无 lockfile 时则安全降级为普通安装，不会直接报错。
+
 ### 注册自定义工具链或覆盖默认行为：
 ```typescript
-import { registerToolchain, type ToolchainProvider } from '@omniflow/core'
-
-const goToolchain: ToolchainProvider = {
-  name: 'go',
-  priority: 20, // 优先级高于内置默认 Provider (10)
-  detect: async (cwd) => {
-    // 检测是否包含 go.mod
-    return { detected: true, confidence: 0.95 }
-  },
-  getProjectInfo: async (cwd) => ({
-    name: 'user-service',
-    version: '1.0.0'
-  }),
-  getBuildCommand: (cwd, options) => 'go build -v -o dist/app ./cmd/main.go'
+import {
+  registerToolchain,
+  shell,
+  type ToolchainProvider,
+  type DetectionResult,
+  type ProjectInfo
+} from '@ticatec/omniflow-core'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export class GoToolchain implements ToolchainProvider {
+  readonly name = 'go'
+  readonly priority: number = 50 // 优先级高于内置默认 Provider，在自动探测链中优先执行
+
+  async detect(projectDir: string): Promise<DetectionResult | null> {
+    try {
+      await fs.access(path.join(projectDir, 'go.mod'))
+      return { name: this.name, reason: 'found go.mod' }
+    } catch {
+      return null
+    }
+  }
+
+  async projectInfo(projectDir: string): Promise<ProjectInfo> {
+    return { name: 'user-service', version: '1.0.0', fullName: 'user-service' }
+  }
+
+  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}`
+  }
 }
 
 // 注册至全局注册表
-registerToolchain(goToolchain)
+registerToolchain(new GoToolchain())
 ```
 
 > 关于创建自定义工具链（如 Go、Rust）及企业定制覆写的完整教程，详见 [Toolchain SPI 扩展指南](./docs/toolchain-extension_CN.md)。
 
 ---
 
+## v0.2.0 不兼容变更 (Breaking Changes)
+
+从早期实验性版本升级至 `0.2.0` 时，请注意以下行为与 API 变更：
+
+1. **`--dry-run` 模拟输出**：在空跑模式下，命令原语返回 `{ stdout: '', stderr: '', exitCode: 0, failed: false }`，不再向 stdout 注入 `"[DRY-RUN] ..."` 等伪造输出字符串。模拟执行的命令行直接通过 `ctx.logger.info` 记录。
+2. **`docker.build` 必填 image 参数**：`DockerBuildOptions` 中的 `image` 参数现为必填项。移除了隐式兜底至 `'latest'` 的行为及未文档化的别名参数（`tag`、`tags`），防止生产环境产生静默镜像错标。
+3. **`docker.composeUp` 参数命名规范化**：参数属性统一为 `files?: string | string[]` 与 `detach?: boolean`。移除了未经规范的遗留别名（`file`、`detached`）。
+4. **`ssh` 配置属性驼峰化**：SSH 目标配置严格遵循 camelCase 命名：`privateKey`、`privateKeyFile`。废弃并移除了 snake_case 别名（`private_key`、`private_key_file`）。
+5. **`resolveToolchain` 选项规范化**：选项类型统一为 `{ preferred?: string; fallback?: string }`。移除了历史遗留别名 `configured`。
+6. **命令启动失败退出码**：当子进程无法启动时（如可执行文件不存在导致 `exitCode` 为 `undefined`），统一返回 `exitCode: -1` 且 `failed: true`，修复了先前被误判为退出码 `0` 的缺陷。
+7. **`git.resetHard` 与 `git.checkout` 字符串参数语义**：在 v0.1.x 中，传入的单个字符串参数被视作工作目录路径 `dir`（如 `resetHard(dir?, target?)`、`checkout(dir?, ref?)`）。在 v0.2.0 中，裸字符串统一代表目标 commit 或 ref（如 `resetHard(target?: string | GitResetOptions)`、`checkout(ref?: string | GitCheckoutOptions)`）。若需显式指定工作目录，需使用 options 对象传入：`{ dir: '/path/to/repo' }`。
+
+---
+
 ## 模块子路径导出
 
-`@omniflow/core` 遵循现代 ESM 规范，支持精细化的子路径导入：
+`@ticatec/omniflow-core` 遵循现代 ESM 规范，支持精细化的子路径导入：
 
 | 导出子路径 | 包含功能说明 |
 |:---|:---|
-| `@omniflow/core` | 全量包入口：包含上下文、原语、工具链 SPI 以及工具函数 |
-| `@omniflow/core/context` | 执行上下文、`AsyncLocalStorage` 封装、Mock 测试辅助工具 |
-| `@omniflow/core/primitives` | 命令原语（`shell`、`ssh`、`git`、`docker`） |
-| `@omniflow/core/toolchain` | Toolchain SPI 接口、注册表与内置 Provider |
+| `@ticatec/omniflow-core` | 全量包入口：包含上下文、原语、工具链 SPI 以及工具函数 |
+| `@ticatec/omniflow-core/context` | 执行上下文、`AsyncLocalStorage` 封装、Mock 测试辅助工具 |
+| `@ticatec/omniflow-core/primitives` | 命令原语（`shell`、`ssh`、`git`、`docker`） |
+| `@ticatec/omniflow-core/toolchain` | Toolchain SPI 接口、注册表与内置 Provider |
 
 ---