@qlover/scripts-context 2.1.1 → 2.3.2

package/dist/index.js

@@ -12,21 +12,23 @@ var defaultFeConfig = {
   commitlint: {
     extends: ["@commitlint/config-conventional"]
   },
-  release: {
-    publishPath: "",
-    autoMergeReleasePR: false,
-    autoMergeType: "squash",
-    branchName: "release-${pkgName}-${tagName}",
-    PRTitle: "[${pkgName} Release] Branch:${branch}, Tag:${tagName}, Env:${env}",
-    PRBody: "## Publish Details\n\n- \u{1F3F7}\uFE0F Version: ${tagName}\n- \u{1F332} Branch: ${branch}\n- \u{1F527} Environment: ${env}\n\n## Changelog\n\n${changelog}\n\n## Notes\n\n- [ ] Please check if the version number is correct\n- [ ] Please confirm all tests have passed\n- [ ] Please confirm the documentation has been updated\n\n> This PR is auto created by release process, please contact the frontend team if there are any questions.",
-    label: {
-      color: "1A7F37",
-      description: "Release PR",
-      name: "CI-Release"
-    },
-    packagesDirectories: [],
-    changePackagesLabel: "changes:${name}"
-  },
+  // release: {
+  //   publishPath: '',
+  //   autoMergeReleasePR: false,
+  //   autoMergeType: 'squash',
+  //   branchName: 'release-${pkgName}-${tagName}',
+  //   PRTitle:
+  //     '[${pkgName} Release] Branch:${branch}, Tag:${tagName}, Env:${env}',
+  //   PRBody:
+  //     '## Publish Details\n\n- 🏷️ Version: ${tagName}\n- 🌲 Branch: ${branch}\n- 🔧 Environment: ${env}\n\n## Changelog\n\n${changelog}\n\n## Notes\n\n- [ ] Please check if the version number is correct\n- [ ] Please confirm all tests have passed\n- [ ] Please confirm the documentation has been updated\n\n> This PR is auto created by release process, please contact the frontend team if there are any questions.',
+  //   label: {
+  //     color: '1A7F37',
+  //     description: 'Release PR',
+  //     name: 'CI-Release'
+  //   },
+  //   packagesDirectories: [],
+  //   changePackagesLabel: 'changes:${name}'
+  // },
   envOrder: [".env.local", ".env.production", ".env"]
 };
 
@@ -67,6 +69,7 @@ var ColorFormatter = class {
   }) {
     this.levelColors = levelColors;
   }
+  levelColors;
   /**
    * Format log event by applying color to the level and preserving original arguments
    *
@@ -478,11 +481,395 @@ var ConfigSearch = class {
 };
 
 // src/implement/ScriptContext.ts
-import { merge as merge3, get as get2 } from "lodash-es";
-import { ExecutorContextImpl } from "@qlover/fe-corekit";
+import { merge as merge4, get as get2 } from "lodash-es";
+
+// ../fe-corekit/src/aborter/Aborter.ts
+import { isString } from "lodash-es";
+
+// ../fe-corekit/src/executor/impl/ExecutorContextImpl.ts
+var runtimesStorage = /* @__PURE__ */ new WeakMap();
+var ExecutorContextImpl = class {
+  _parameters;
+  _error;
+  _returnValue;
+  /**
+   * Creates a new ExecutorContextImpl instance
+   *
+   * **Important**: Parameters are stored by reference, not cloned.
+   * If you need parameter isolation, clone them before passing to the constructor.
+   *
+   * @param parameters - The initial parameters for the context
+   *
+   * @example Without isolation (parameters will be modified)
+   * ```typescript
+   * const params = { value: 1 };
+   * const context = new ExecutorContextImpl(params);
+   * context.setParameters({ value: 2 });
+   * console.log(params.value); // 2 - original object is modified
+   * ```
+   *
+   * @example With isolation (clone parameters first)
+   * ```typescript
+   * const params = { value: 1 };
+   * const context = new ExecutorContextImpl({ ...params }); // shallow clone
+   * context.setParameters({ value: 2 });
+   * console.log(params.value); // 1 - original object is unchanged
+   * ```
+   */
+  constructor(parameters) {
+    this._parameters = parameters;
+    runtimesStorage.set(this, {
+      pluginName: "",
+      pluginIndex: void 0,
+      hookName: "",
+      returnValue: void 0,
+      returnBreakChain: false,
+      times: 0,
+      breakChain: false
+    });
+  }
+  /**
+   * Get the context parameters
+   *
+   * **Important**: Returns the parameters by reference.
+   * Modifications to the returned object will affect the context's internal state.
+   *
+   * @override
+   * @returns The parameters object (by reference)
+   */
+  get parameters() {
+    return this._parameters;
+  }
+  /**
+   * Get the error, if any
+   *
+   * @override
+   * @returns The error, if any
+   */
+  get error() {
+    return this._error;
+  }
+  /**
+   * Get the return value, if any
+   *
+   * @override
+   * @returns The return value, if any
+   */
+  get returnValue() {
+    return this._returnValue;
+  }
+  /**
+   * Get read-only snapshot of hooks runtime information
+   *
+   * Core concept:
+   * Provides safe read-only access to runtime tracking information.
+   * Returns a frozen shallow copy to prevent accidental modifications.
+   *
+   * Security features:
+   * - Stored in WeakMap, truly private (cannot access via ._hooksRuntimes)
+   * - Returns a new frozen object (not the internal reference)
+   * - Object is frozen to prevent modifications
+   * - Setter throws error to prevent assignment
+   *
+   * Why WeakMap?
+   * - TypeScript's `private` is only compile-time protection
+   * - JavaScript runtime can still access `._hooksRuntimes`
+   * - WeakMap provides true runtime privacy
+   * - No way to access the internal state from outside
+   *
+   * @override
+   * @returns Frozen shallow copy of hook runtime state
+   *
+   * @example Safe read access
+   * ```typescript
+   * const runtimes = context.hooksRuntimes;
+   * console.log(`Hook ${runtimes.hookName} executed ${runtimes.times} times`);
+   * ```
+   *
+   * @example Modification attempts fail
+   * ```typescript
+   * const runtimes = context.hooksRuntimes;
+   * runtimes.times = 10; // Error: Cannot assign to read only property
+   * context.hooksRuntimes = {}; // Error: hooksRuntimes is read-only
+   * context._hooksRuntimes; // undefined - truly private!
+   * ```
+   */
+  get hooksRuntimes() {
+    const runtimes = runtimesStorage.get(this);
+    if (!runtimes) {
+      throw new Error("Runtime state not initialized");
+    }
+    return Object.freeze({ ...runtimes });
+  }
+  /**
+   * Set error in context
+   *
+   * Automatically converts standard Error objects to ExecutorError for consistency.
+   * If the error is already an ExecutorError, it is stored as-is.
+   * If the error is a standard Error, it is wrapped in an ExecutorError with id 'EXECUTOR_ERROR'.
+   *
+   * @override
+   * @param error - The error to set in context (ExecutorError or standard Error)
+   *
+   * @example With ExecutorError
+   * ```typescript
+   * context.setError(new ExecutorError('VALIDATION_ERROR', 'Invalid input'));
+   * console.log(context.error.id); // 'VALIDATION_ERROR'
+   * ```
+   *
+   * @example With standard Error (auto-converted)
+   * ```typescript
+   * try {
+   *   JSON.parse('invalid');
+   * } catch (error) {
+   *   context.setError(error); // Auto-converted to ExecutorError
+   *   console.log(context.error.id); // 'EXECUTOR_ERROR'
+   *   console.log(context.error.cause); // Original SyntaxError
+   * }
+   * ```
+   */
+  setError(error) {
+    this._error = error;
+  }
+  /**
+   * Set return value in context
+   *
+   * @override
+   * @param value - The value to set as return value
+   */
+  setReturnValue(value) {
+    this._returnValue = value;
+  }
+  /**
+   * Set parameters in context
+   *
+   * **Important**: Parameters are stored by reference, not cloned.
+   * The provided parameters object will be used directly.
+   *
+   * @override
+   * @param params - The parameters to set (stored by reference)
+   *
+   * @example
+   * ```typescript
+   * const newParams = { value: 2 };
+   * context.setParameters(newParams);
+   * // context.parameters === newParams (same reference)
+   * ```
+   */
+  setParameters(params) {
+    this._parameters = params;
+  }
+  /**
+   * Reset hooks runtime state to initial values
+   *
+   * Core concept:
+   * Clears all runtime tracking information for fresh execution
+   *
+   * Reset operations:
+   * - Clears plugin name and hook name
+   * - Resets return value and chain breaking flags
+   * - Resets execution counter and index
+   *
+   * @override
+   */
+  resetHooksRuntimes(hookName) {
+    const runtimes = runtimesStorage.get(this);
+    if (!runtimes) {
+      throw new Error("Runtime state not initialized");
+    }
+    if (hookName) {
+      runtimesStorage.set(this, {
+        ...runtimes,
+        hookName,
+        times: 0,
+        returnValue: void 0
+      });
+      return;
+    }
+    runtimesStorage.set(this, {
+      pluginName: "",
+      pluginIndex: void 0,
+      hookName: "",
+      returnValue: void 0,
+      returnBreakChain: false,
+      times: 0,
+      breakChain: false
+    });
+  }
+  /**
+   * Reset entire context to initial state
+   *
+   * Core concept:
+   * Complete context cleanup for new execution cycle
+   *
+   * Reset operations:
+   * - Resets hooks runtime state
+   * - Clears return value
+   * - Clears error state
+   *
+   * @override
+   */
+  reset() {
+    this.resetHooksRuntimes();
+    this._returnValue = void 0;
+    this._error = void 0;
+  }
+  /**
+   * Check if a plugin hook should be skipped
+   * Returns true if the hook should be skipped (invalid or disabled)
+   *
+   * Core concept:
+   * Plugin hook validation and enablement checking
+   *
+   * Validation criteria:
+   * - Hook method exists and is callable
+   * - Plugin is enabled for the specific hook
+   * - Plugin enablement function returns true
+   *
+   * @override
+   * @template Ctx - Type of task context
+   * @param plugin - The plugin to check
+   * @param hookName - The name of the hook to validate
+   * @returns True if the hook should be skipped, false otherwise
+   */
+  shouldSkipPluginHook(plugin, hookName) {
+    return typeof plugin[hookName] !== "function" || typeof plugin.enabled === "function" && !plugin.enabled(hookName, this);
+  }
+  /**
+   * Update runtime tracking information for plugin execution
+   *
+   * Core concept:
+   * Track plugin execution metadata for debugging and flow control.
+   * Creates a new runtime object with merged updates to ensure immutability.
+   *
+   * Security:
+   * - Always creates a new object (immutable updates)
+   * - Stored in WeakMap (truly private)
+   * - Cannot be accessed or modified from outside
+   *
+   * Tracking information:
+   * - Current plugin name
+   * - Current hook name
+   * - Execution counter (times)
+   * - Plugin index in execution chain
+   *
+   * @override
+   * @param updates - Partial runtime updates to merge
+   * @example
+   * ```typescript
+   * context.runtimes({
+   *   pluginName: 'testPlugin',
+   *   hookName: 'onBefore',
+   *   times: 1,
+   *   pluginIndex: 0
+   * });
+   * ```
+   */
+  runtimes(updates) {
+    const current = runtimesStorage.get(this);
+    if (!current) {
+      throw new Error("Runtime state not initialized");
+    }
+    runtimesStorage.set(this, {
+      ...current,
+      ...updates
+    });
+  }
+  /**
+   * Set return value in context runtime tracking
+   *
+   * Core concept:
+   * Store plugin hook return value for chain control and debugging.
+   * Creates a new runtime object with updated return value.
+   *
+   * Security:
+   * - Creates new object (immutable update)
+   * - Stored in WeakMap (truly private)
+   *
+   * Usage scenarios:
+   * - Track plugin hook return values
+   * - Enable chain breaking based on return values
+   * - Debug plugin execution flow
+   *
+   * @override
+   * @param returnValue - The value to set as return value
+   */
+  runtimeReturnValue(returnValue) {
+    const current = runtimesStorage.get(this);
+    if (!current) {
+      throw new Error("Runtime state not initialized");
+    }
+    runtimesStorage.set(this, {
+      ...current,
+      returnValue
+    });
+  }
+  /**
+   * Check if the execution chain should be broken
+   *
+   * Core concept:
+   * Chain breaking control for plugin execution flow
+   *
+   * Chain breaking scenarios:
+   * - Plugin explicitly sets breakChain flag
+   * - Error conditions requiring immediate termination
+   * - Business logic requiring early exit
+   *
+   * @override
+   * @returns True if the chain should be broken, false otherwise
+   */
+  shouldBreakChain() {
+    const runtimes = runtimesStorage.get(this);
+    return !!runtimes?.breakChain;
+  }
+  /**
+   * Check if the execution chain should be broken due to return value
+   *
+   * Core concept:
+   * Return value-based chain breaking control
+   *
+   * Usage scenarios:
+   * - Plugin returns a value that should terminate execution
+   * - Error handling hooks return error objects
+   * - Business logic requires return value-based flow control
+   *
+   * @override
+   * @returns True if the chain should be broken due to return value, false otherwise
+   */
+  shouldBreakChainOnReturn() {
+    const runtimes = runtimesStorage.get(this);
+    return !!runtimes?.returnBreakChain;
+  }
+  /**
+   * Check if execution should continue on error
+   *
+   * Core concept:
+   * Determines whether to continue executing subsequent plugins when a plugin hook
+   * throws an error, enabling resilient execution pipelines
+   *
+   * @override
+   * @returns True if execution should continue on error, false otherwise
+   */
+  shouldContinueOnError() {
+    const runtimes = runtimesStorage.get(this);
+    return !!runtimes?.continueOnError;
+  }
+};
+
+// ../fe-corekit/src/request/adapter/RequestAdapterFetch.ts
+import { merge, pick } from "lodash-es";
+
+// ../fe-corekit/src/request/impl/RequestExecutor.ts
+import { clone } from "lodash-es";
+
+// ../fe-corekit/src/request/impl/RequestPlugin.ts
+import { clone as clone2 } from "lodash-es";
+
+// ../fe-corekit/src/request/impl/ResponsePlugin.ts
+import { isFunction } from "lodash-es";
 
 // src/utils/initializeOptions.ts
-import { merge, get } from "lodash-es";
+import { merge as merge2, get } from "lodash-es";
 import { Env } from "@qlover/env-loader";
 var DEFAULT_ENV_ORDER = [".env.local", ".env"];
 function getDefaultOptions(options, feConfig, logger) {
@@ -513,7 +900,7 @@ function getDefaultStore(scriptName, sources, logger) {
 }
 function initializeOptions(scriptName, feConfig, options, logger) {
   const store = getDefaultStore(scriptName, feConfig, logger);
-  const mergedOptions = merge({}, store, options);
+  const mergedOptions = merge2({}, store, options);
   const defaultOptions = getDefaultOptions(
     mergedOptions,
     feConfig,
@@ -524,7 +911,7 @@ function initializeOptions(scriptName, feConfig, options, logger) {
 
 // src/utils/contextDefaults.ts
 import { exec } from "child_process";
-import { merge as merge2 } from "lodash-es";
+import { merge as merge3 } from "lodash-es";
 
 // ../logger/src/interface/LogEvent.ts
 var LogEvent = class {
@@ -535,6 +922,10 @@ var LogEvent = class {
     this.context = context;
     this.timestamp = Date.now();
   }
+  level;
+  args;
+  loggerName;
+  context;
   /**
    * Timestamp when the log event was created
    *
@@ -650,6 +1041,7 @@ var LogContext = class {
   constructor(value) {
     this.value = value;
   }
+  value;
 };
 
 // ../logger/src/Logger.ts
@@ -678,6 +1070,7 @@ var Logger = class {
     options.levels = options.levels || defaultLevels;
     options.handlers = Array.isArray(options.handlers) ? options.handlers : options.handlers ? [options.handlers] : [];
   }
+  options;
   /**
    * Adds a new log handler to the logger
    *
@@ -994,6 +1387,7 @@ var ConsoleHandler = class {
   constructor(formatter = null) {
     this.formatter = formatter;
   }
+  formatter;
   /**
    * Sets or updates the formatter for this handler
    *
@@ -1172,6 +1566,7 @@ var TimestampFormatter = class {
   constructor(options = {}) {
     this.options = options;
   }
+  options;
   /**
    * Updates formatter options at runtime.
    * Merges the given partial options into the current options; subsequent formatting uses the updated values.
@@ -1298,8 +1693,270 @@ var TimestampFormatter = class {
   }
 };
 
+// src/implement/TemplateEngine.ts
+var interpolatePreset = {
+  /**
+   * ES6 template-literal style: `${ variable }`
+   *
+   * This is the default for {@link TemplateEngine}.
+   *
+   * @example
+   * ```typescript
+   * engine.render('${user.name}', { user: { name: 'Bob' } });
+   * ```
+   */
+  ES6: /\$\{([\s\S]+?)\}/g,
+  /**
+   * Lodash / EJS style: `<%= variable %>`
+   *
+   * Useful when migrating existing lodash templates.
+   *
+   * @example
+   * ```typescript
+   * new TemplateEngine({ interpolate: interpolatePreset.LODASH })
+   *   .render('<%= repo.url %>', { repo: { url: 'https://example.com' } });
+   * ```
+   */
+  LODASH: /<%=([\s\S]+?)%>/g,
+  /**
+   * Mustache / Handlebars style: `{{ variable }}`
+   *
+   * @example
+   * ```typescript
+   * new TemplateEngine({ interpolate: interpolatePreset.MUSTACHE })
+   *   .render('{{ user.name }}', { user: { name: 'Alice' } });
+   * ```
+   */
+  MUSTACHE: /\{\{([\s\S]+?)\}\}/g
+};
+var DANGEROUS_KEYS = /* @__PURE__ */ new Set([
+  "__proto__",
+  "constructor",
+  "prototype",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__"
+]);
+var SAFE_PATH = /^[\w.[\]]+$/;
+var PATH_SEGMENT = /^(\d+|\w+)$/;
+function cloneGlobalRegExp(regex) {
+  const flags = regex.flags.includes("g") ? regex.flags : `${regex.flags}g`;
+  return new RegExp(regex.source, flags);
+}
+function normalizePath(path) {
+  return path.replace(/\[(\d+)\]/g, ".$1");
+}
+function parsePathKeys(path, variablePrefix) {
+  const trimmed = path.trim();
+  if (!trimmed || !SAFE_PATH.test(trimmed)) {
+    return null;
+  }
+  let actualPath = trimmed;
+  if (variablePrefix) {
+    if (actualPath === variablePrefix) {
+      return [];
+    }
+    const prefix = `${variablePrefix}.`;
+    if (!actualPath.startsWith(prefix)) {
+      return null;
+    }
+    actualPath = actualPath.slice(prefix.length);
+    if (!actualPath) {
+      return null;
+    }
+  }
+  const keys = normalizePath(actualPath).split(".");
+  if (keys.length === 0 || keys.some((key) => !key || !PATH_SEGMENT.test(key))) {
+    return null;
+  }
+  return keys;
+}
+function escapeHtml(str) {
+  return str.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+      default:
+        return char;
+    }
+  });
+}
+function formatValue(value, stringifyObject) {
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (typeof value === "object") {
+    return stringifyObject ? JSON.stringify(value) : String(value);
+  }
+  return String(value);
+}
+function getValueByKeys(data, keys, safePrototype) {
+  if (keys === null) {
+    return void 0;
+  }
+  if (keys.length === 0) {
+    return data;
+  }
+  let current = data;
+  for (const key of keys) {
+    if (safePrototype && DANGEROUS_KEYS.has(key)) {
+      return void 0;
+    }
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    const record = current;
+    if (safePrototype) {
+      if (!Object.hasOwn(record, key)) {
+        return void 0;
+      }
+    } else if (!(key in record)) {
+      return void 0;
+    }
+    current = record[key];
+  }
+  return current;
+}
+function tokenize(template, interpolate) {
+  const tokens = [];
+  const regex = cloneGlobalRegExp(interpolate);
+  let lastIndex = 0;
+  let match;
+  while ((match = regex.exec(template)) !== null) {
+    if (match[0].length === 0) {
+      regex.lastIndex += 1;
+      continue;
+    }
+    if (match.index > lastIndex) {
+      tokens.push(template.slice(lastIndex, match.index));
+    }
+    const rawPath = match[1]?.trim() ?? "";
+    tokens.push({
+      type: "variable",
+      path: rawPath,
+      raw: match[0],
+      keys: null
+    });
+    lastIndex = regex.lastIndex;
+  }
+  if (lastIndex < template.length) {
+    tokens.push(template.slice(lastIndex));
+  }
+  return tokens;
+}
+var TemplateEngine = class {
+  options;
+  /**
+   * @param options - Engine configuration. All fields are optional;
+   *   defaults to ES6 `${}` interpolation with safe prototype access.
+   */
+  constructor(options = {}) {
+    const defaults = {
+      interpolate: interpolatePreset.ES6,
+      variable: "",
+      defaultValue: "",
+      escapeHtml: false,
+      stringifyObject: true,
+      keepUnmatched: false,
+      safePrototype: true
+    };
+    this.options = {
+      ...defaults,
+      ...options,
+      interpolate: cloneGlobalRegExp(
+        options.interpolate ?? defaults.interpolate
+      )
+    };
+  }
+  /**
+   * Compile a template into a reusable render function.
+   *
+   * Path parsing and validation happen once at compile time; subsequent
+   * renders only perform value lookup and string assembly.
+   *
+   * @param template - Template string containing placeholders
+   * @returns Render function bound to the compiled template
+   * @throws {TypeError} When template is not a string
+   */
+  compile(template) {
+    if (typeof template !== "string") {
+      throw new TypeError("Template must be a string");
+    }
+    const {
+      variable,
+      defaultValue,
+      escapeHtml: shouldEscapeHtml,
+      stringifyObject,
+      keepUnmatched,
+      safePrototype
+    } = this.options;
+    const tokens = tokenize(template, this.options.interpolate).map(
+      (token) => {
+        if (typeof token === "string") {
+          return token;
+        }
+        return {
+          ...token,
+          keys: parsePathKeys(token.path, variable)
+        };
+      }
+    );
+    return (input) => {
+      const data = input !== null && typeof input === "object" ? input : {};
+      const parts = [];
+      for (const token of tokens) {
+        if (typeof token === "string") {
+          parts.push(token);
+          continue;
+        }
+        const value = getValueByKeys(data, token.keys, safePrototype);
+        if (value === void 0 || value === null) {
+          if (keepUnmatched) {
+            parts.push(token.raw);
+            continue;
+          }
+          let resolvedDefault = defaultValue;
+          if (typeof defaultValue === "function") {
+            resolvedDefault = defaultValue(token.path, data);
+          }
+          const defaultStr = formatValue(resolvedDefault, stringifyObject);
+          parts.push(shouldEscapeHtml ? escapeHtml(defaultStr) : defaultStr);
+          continue;
+        }
+        let output = formatValue(value, stringifyObject);
+        if (shouldEscapeHtml) {
+          output = escapeHtml(output);
+        }
+        parts.push(output);
+      }
+      return parts.join("");
+    };
+  }
+  /**
+   * Render a template in one shot.
+   *
+   * Convenience wrapper around `compile(template)(data)`.
+   * Prefer {@link compile} when the same template is rendered multiple times.
+   *
+   * @param template - Template string containing placeholders
+   * @param data - Context object for variable substitution
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  render(template, data) {
+    return this.compile(template)(data);
+  }
+};
+
 // src/implement/Shell.ts
-import { template as lodashTemplate } from "lodash-es";
 var Shell = class _Shell {
   /**
    * Creates a new Shell instance with the specified configuration
@@ -1348,6 +2005,9 @@ var Shell = class _Shell {
     this.config = config;
     this.cache = cache;
   }
+  config;
+  cache;
+  static templateEngine = new TemplateEngine();
   /**
    * Gets the logger instance for command logging and error reporting
    *
@@ -1373,60 +2033,32 @@ var Shell = class _Shell {
     return this.config.logger;
   }
   /**
-   * Formats a template string with context using lodash template
+   * Formats a template string with context using {@link TemplateEngine}.
    *
-   * Core concept:
-   * Provides static template formatting functionality using
-   * lodash template for string interpolation with context data.
-   *
-   * Template features:
-   * - Uses lodash template for powerful string interpolation
-   * - Supports complex template expressions and logic
-   * - Handles undefined and null context values gracefully
-   * - Returns formatted string with context values substituted
-   *
-   * Template syntax:
-   * - `<%= variable %>` for escaped output
-   * - `<%- variable %>` for unescaped output
-   * - `<% code %>` for JavaScript code execution
-   * - Supports nested object access and function calls
-   *
-   * Context handling:
-   * - Accepts any object with string/number/boolean values
-   * - Handles undefined and null values safely
-   * - Supports nested object property access
-   * - Provides fallback for missing context values
+   * Uses ES6-style `${ path }` placeholders via {@link TemplateEngine}.
    *
    * @param template - Template string with interpolation placeholders
    * @param context - Context object for template variable substitution
    * @returns Formatted string with context values substituted
    *
-   * @example Basic template formatting
+   * @example Basic formatting
    * ```typescript
-   * const result = Shell.format('Hello <%= name %>!', { name: 'World' });
+   * const result = Shell.format('Hello ${name}!', { name: 'World' });
    * // Returns: 'Hello World!'
    * ```
    *
    * @example Complex template with nested objects
    * ```typescript
    * const result = Shell.format(
-   *   'git clone <%= repo.url %> <%= repo.branch %>',
+   *   'git clone ${repo.url} ${repo.branch}',
    *   { repo: { url: 'https://github.com/user/repo.git', branch: 'main' } }
    * );
    * // Returns: 'git clone https://github.com/user/repo.git main'
    * ```
-   *
-   * @example Template with conditional logic
-   * ```typescript
-   * const result = Shell.format(
-   *   'npm install<% if (dev) { %> --save-dev<% } %>',
-   *   { dev: true }
-   * );
-   * // Returns: 'npm install --save-dev'
-   * ```
    */
   static format(template = "", context = {}) {
-    return lodashTemplate(template)(context);
+    const data = context !== null && typeof context === "object" ? context : {};
+    return _Shell.templateEngine.render(template, data);
   }
   /**
    * Formats a template string with context and comprehensive error handling
@@ -1461,14 +2093,14 @@ var Shell = class _Shell {
    *
    * @example Basic formatting
    * ```typescript
-   * const result = shell.format('Hello <%= name %>!', { name: 'World' });
+   * const result = shell.format('Hello ${name}!', { name: 'World' });
    * // Returns: 'Hello World!'
    * ```
    *
    * @example Error handling
    * ```typescript
    * try {
-   *   const result = shell.format('Hello <%= name %>!', {});
+   *   const result = shell.format('Hello ${name}!', {});
    * } catch (error) {
    *   // Error is logged with template and context information
    *   console.error('Template formatting failed:', error.message);
@@ -1522,7 +2154,7 @@ ${JSON.stringify(context)}`
    *
    * @example String command with template
    * ```typescript
-   * const output = await shell.exec('git clone <%= repo %>', {
+   * const output = await shell.exec('git clone ${repo}', {
    *   context: { repo: 'https://github.com/user/repo.git' }
    * });
    * ```
@@ -1795,7 +2427,7 @@ var contextDefaults = {
   getConfig(feConfig) {
     return new ConfigSearch({
       name: "fe-config",
-      defaultConfig: merge2({}, defaultFeConfig, feConfig)
+      defaultConfig: merge3({}, defaultFeConfig, feConfig)
     });
   },
   /**
@@ -1914,7 +2546,7 @@ var contextDefaults = {
       dryRun,
       execPromise: _options.execPromise || contextDefaults.exec
     });
-    const _feConfig = merge2({}, feConfig, { [name]: ctxOpts.options });
+    const _feConfig = merge3({}, feConfig, { [name]: ctxOpts.options });
     return {
       options: _options,
       dryRun: !!dryRun,
@@ -1986,8 +2618,9 @@ var ScriptContext = class extends ExecutorContextImpl {
     this.shell = shell;
     this.dryRun = dryRun;
     this.verbose = verbose;
-    this.setOptions(initializeOptions(name, feConfig, options, logger));
+    this.setParameters(initializeOptions(name, feConfig, options, logger));
   }
+  name;
   /**
    * Logger instance for structured logging
    *
@@ -2024,7 +2657,22 @@ var ScriptContext = class extends ExecutorContextImpl {
    */
   verbose;
   /**
+   * 该属性只是一个 parameters 的别名
+   *
+   * 当你需要设置最新的参数时可以直接使用 setParameters 方法
+   *
    * @override
+   * @example
+   * ```ts
+   * context.setParameters({
+   *   target: 'production'
+   * });
+   *
+   * console.log(context.options);
+   * // { target: 'production' }
+   * console.log(context.parameters);
+   * // { target: 'production' }
+   * ```
    */
   get options() {
     return this.parameters;
@@ -2071,10 +2719,10 @@ var ScriptContext = class extends ExecutorContextImpl {
    * ```
    */
   get env() {
-    if (!this.options.env) {
+    if (!this.parameters.env) {
       throw new Error("Environment is not initialized");
     }
-    return this.options.env;
+    return this.parameters.env;
   }
   /**
    * Updates script options with deep merging support
@@ -2119,9 +2767,10 @@ var ScriptContext = class extends ExecutorContextImpl {
    * });
    * // Merges nested build configuration
    * ```
+   *
    */
-  setOptions(options) {
-    this.setParameters(merge3(this.options, options));
+  setParameters(params) {
+    super.setParameters(merge4(this.parameters, params));
   }
   /**
    * Retrieves environment variable with optional default value
@@ -2224,16 +2873,16 @@ var ScriptContext = class extends ExecutorContextImpl {
    * // Returns the complete options object
    * ```
    */
-  getOptions(key, defaultValue) {
+  getParameters(key, defaultValue) {
     if (!key) {
-      return this.options;
+      return this.parameters;
     }
-    return get2(this.options, key, defaultValue);
+    return get2(this.parameters, key, defaultValue);
   }
 };
 
 // src/implement/ScriptPlugin.ts
-import { merge as merge4 } from "lodash-es";
+import { merge as merge5 } from "lodash-es";
 var ScriptPlugin = class {
   /**
    * Creates a new script plugin instance
@@ -2265,6 +2914,9 @@ var ScriptPlugin = class {
     this.props = props;
     this.setConfig(this.getInitialProps(props));
   }
+  context;
+  pluginName;
+  props;
   /** Ensures only one instance of this plugin can be registered */
   onlyOne = true;
   /**
@@ -2292,9 +2944,9 @@ var ScriptPlugin = class {
       return {};
     }
     const pluginConfig = this.context.options[this.pluginName];
-    const fileConfig = this.context.getOptions(this.pluginName);
+    const fileConfig = this.context.getParameters(this.pluginName);
     const baseConfig = pluginConfig || fileConfig;
-    return props ? merge4({}, baseConfig, props) : baseConfig || {};
+    return props ? merge5({}, baseConfig, props) : baseConfig || {};
   }
   /**
    * Logger instance for structured logging
@@ -2357,8 +3009,8 @@ var ScriptPlugin = class {
    * }
    * ```
    */
-  get options() {
-    return this.context.getOptions(this.pluginName, {});
+  get config() {
+    return this.context.getParameters(this.pluginName, {});
   }
   /**
    * Determines whether a lifecycle method should be executed
@@ -2385,12 +3037,18 @@ var ScriptPlugin = class {
    * plugin.enabled('onExec', context);   // Returns true
    * ```
    */
-  enabled(_name, _context) {
+  enabled(name, _context) {
     const skip = this.getConfig("skip");
-    if (skip === true) {
+    if (typeof skip === "string" && name === skip) {
+      this.logger.debug(
+        `Skip ${this.pluginName}.${name}, ${this.pluginName}.skip is set to '${skip}'`
+      );
       return false;
     }
-    if (typeof skip === "string" && _name === skip) {
+    if (skip === true) {
+      this.logger.debug(
+        `Skip ${this.pluginName}.${name}, ${this.pluginName}.skip is set to true`
+      );
       return false;
     }
     return true;
@@ -2428,9 +3086,9 @@ var ScriptPlugin = class {
    */
   getConfig(keys, defaultValue) {
     if (!keys) {
-      return this.context.getOptions(this.pluginName, defaultValue);
+      return this.context.getParameters(this.pluginName, defaultValue);
     }
-    return this.context.getOptions(
+    return this.context.getParameters(
       [this.pluginName, ...Array.isArray(keys) ? keys : [keys]],
       defaultValue
     );
@@ -2467,167 +3125,10 @@ var ScriptPlugin = class {
    * ```
    */
   setConfig(config) {
-    this.context.setOptions({
+    this.context.setParameters({
       [this.pluginName]: config
     });
   }
-  /**
-   * Lifecycle method called before script execution
-   *
-   * Override this method to perform setup tasks such as:
-   * - Environment validation
-   * - Configuration verification
-   * - Resource preparation
-   * - Pre-execution checks
-   *
-   * @override
-   * @param _context - Executor context containing execution state
-   *
-   * @example
-   * ```typescript
-   * async onBefore(context: ExecutorContext<MyContext>): Promise<void> {
-   *   // Validate required environment variables
-   *   const apiKey = this.context.getEnv('API_KEY');
-   *   if (!apiKey) {
-   *     throw new Error('API_KEY environment variable is required');
-   *   }
-   *
-   *   // Check if output directory exists
-   *   const outputDir = this.getConfig('outputDir', './dist');
-   *   if (!(await this.shell.exists(outputDir))) {
-   *     await this.shell.mkdir(outputDir);
-   *   }
-   * }
-   * ```
-   */
-  onBefore(_context) {
-    return void 0;
-  }
-  /**
-   * Lifecycle method called during script execution
-   *
-   * Override this method to implement the main plugin logic:
-   * - Core functionality execution
-   * - Business logic implementation
-   * - Task orchestration
-   * - Process management
-   *
-   * @override
-   * @param _context - Executor context containing execution state
-   *
-   * @example
-   * ```typescript
-   * async onExec(context: Context): Promise<void> {
-   *   await this.step({
-   *     label: 'Building project',
-   *     task: async () => {
-   *       await this.shell.exec('npm run build');
-   *       return 'build completed';
-   *     }
-   *   });
-   *
-   *   await this.step({
-   *     label: 'Running tests',
-   *     task: async () => {
-   *       await this.shell.exec('npm test');
-   *       return 'tests passed';
-   *     }
-   *   });
-   * }
-   * ```
-   */
-  onExec(_context) {
-  }
-  /**
-   * Lifecycle method called after successful script execution
-   *
-   * Override this method to perform cleanup tasks such as:
-   * - Resource cleanup
-   * - Success notifications
-   * - Result processing
-   * - Post-execution reporting
-   *
-   * @override
-   * @param _context - Executor context containing execution state
-   *
-   * @example
-   * ```typescript
-   * async onSuccess(context: Context): Promise<void> {
-   *   // Send success notification
-   *   await this.sendNotification('Build completed successfully');
-   *
-   *   // Generate success report
-   *   await this.generateReport({
-   *     status: 'success',
-   *     timestamp: new Date(),
-   *     duration: context.duration
-   *   });
-   *
-   *   // Clean up temporary files
-   *   await this.shell.rmdir('./temp');
-   * }
-   * ```
-   */
-  onSuccess(_context) {
-    return void 0;
-  }
-  /**
-   * Lifecycle method called when script execution fails
-   *
-   * Override this method to handle errors such as:
-   * - Error logging and reporting
-   * - Resource cleanup on failure
-   * - Error notifications
-   * - Failure recovery attempts
-   *
-   * @override
-   * @param _context - Executor context containing execution state
-   *
-   * @example
-   * ```typescript
-   * async onError(context: Context): Promise<void> {
-   *   // Log detailed error information
-   *   this.logger.error('Script execution failed', {
-   *     error: context.error,
-   *     duration: context.duration,
-   *     config: this.options
-   *   });
-   *
-   *   // Send error notification
-   *   await this.sendNotification('Build failed', {
-   *     error: context.error.message
-   *   });
-   *
-   *   // Clean up partial results
-   *   await this.shell.rmdir('./partial-build');
-   * }
-   * ```
-   */
-  onError(_context) {
-  }
-  /**
-   * Lifecycle method called after script execution
-   *
-   * Override this method to perform cleanup tasks such as:
-   * - Resource cleanup
-   * - Success notifications
-   * - Result processing
-   * - Post-execution reporting
-   *
-   * @override
-   * @param _context - Executor context containing execution state
-   *
-   * @example
-   * ```typescript
-   * async onFinally(context: Context): Promise<void> {
-   *   // Clean up temporary files
-   *   await this.shell.rmdir('./temp');
-   * }
-   * ```
-   */
-  onFinally(_context) {
-    return void 0;
-  }
   /**
    * Executes a step with structured logging and error handling
    *
@@ -2688,18 +3189,25 @@ var ScriptPlugin = class {
    * ```
    */
   async step(options) {
-    this.logger.log();
-    this.logger.info(options.label);
-    this.logger.log();
+    const stepBase = this.createStepLabel(options.label);
+    this.logger.info(`${stepBase} - beginning`);
     try {
       const res = await options.task();
-      this.logger.info(`${options.label} - success`);
+      this.logger.info(`${stepBase} - success`);
       return res;
     } catch (e) {
-      this.logger.error(e);
+      this.logger.error(`${stepBase} - failed
+`, e);
       throw e;
     }
   }
+  /**
+   * Builds the shared step log prefix (plugin context + dry-run)
+   */
+  createStepLabel(label) {
+    const stepLabel = `${this.pluginName}: ${label}`;
+    return this.context.dryRun ? `[dry-run] ${stepLabel}` : stepLabel;
+  }
 };
 export {
   ColorFormatter,
@@ -2707,5 +3215,7 @@ export {
   ScriptContext,
   ScriptPlugin,
   Shell,
-  defaultFeConfig
+  TemplateEngine,
+  defaultFeConfig,
+  interpolatePreset
 };