BashScriptExecModule Migration Guide

Overview

BashScriptExecModule is a retired compatibility shell. Version 1.0 ignored its declared scriptDirectory input, scanned the workflow process's ./scripts directory, and executed every .sh file there in parallel. It inherited the worker environment, placed no bound on runtime or output, streamed arbitrary script output into application logs, returned no workflow result, swallowed failures, and incorrectly claimed that execution was idempotent.

Version 2.0 keeps the Java class and Spring bean loadable so saved workflows can be inspected and migrated, but hides the module from new Workflow Studio catalogs. Execution now fails closed with MODULE_RETIRED, performs no directory scan, file read, process launch, environment inheritance, output logging, or host mutation, and names the governed replacement families.

Use ProjectCommandModule only for one allowlisted engineering inspection, test, build, or lint profile in an authorized workspace. Use DeploymentRunnerModule only for an approval-gated installed deployment or rollback profile. Neither replacement accepts arbitrary shell content, executables, arguments, environment variables, or host paths from workflow state.

Usage

1. Find saved workflow tasks whose module type is BashScriptExecModule.
2. Reconcile any prior execution against actual repository, build, deployment, and host state. A version 1.0 log line or missing exception is not a durable success receipt.
3. Inventory the scripts that could have run from the worker's process directory, including scripts added after the workflow was saved.
4. Remove secrets and untrusted values that those scripts could inherit; rotate credentials if their exposure cannot be ruled out.
5. Translate the intended action to one fixed ProjectCommandModule operation or an operator-installed DeploymentRunnerModule profile. If no exact fixed profile exists, keep the task disabled and add a reviewed platform capability instead of restoring arbitrary shell execution.
6. Test the replacement in its authorized environment and reconcile its bounded result or durable deployment receipt.

Inputs

The retired module preserves one legacy input only for catalog compatibility:

Name	Type	Required	Behavior
scriptDirectory	string	no	Ignored. No path is resolved, listed, opened, or returned.

The replacement workflow must use the documented inputs of the selected fixed profile. ProjectCommandModule accepts an operation, authorized root index, relative working directory, bounded selectors, timeout, and output ceiling. DeploymentRunnerModule accepts an immutable artifact reference and SHA-256, release reference, idempotency key, and non-secret context.

Outputs

The compatibility shell always returns:

Name	Type	Description
status	string	Always error.
error	object	Safe MODULE_RETIRED, retryable:false, migration targets, and required action.

The result never contains a legacy path, script name, script body, environment value, stdout, stderr, or process status.

IntegrationAccount Requirements

No IntegrationAccount is required or read. Version 2.0 performs no credential resolution or provider operation.

Do not move shell credentials into an IntegrationAccount merely to preserve a legacy task. ProjectCommandModule uses node-configured workspace roots and a minimal process environment. DeploymentRunnerModule uses an approved node-local profile and, when needed, a secure node credential reference resolved outside workflow input.

Configuration

The compatibility shell keeps the legacy threadPoolSize field for migration visibility, but ignores it and starts no workers:

{
  "threadPoolSize": 4
}

For an engineering replacement, configure one immutable fixed profile such as:

{
  "operation": "npm.test",
  "rootIndex": 0,
  "workingDirectory": "web/client",
  "timeoutSeconds": 900,
  "maxOutputBytes": 262144
}

There is no arbitrary script, shell, executable, argument, environment, or absolute-directory configuration.

Operations

BashScriptExecModule supports one compatibility operation: reject execution and identify migration targets.

ProjectCommandModule allowlists Git inspection plus fixed Maven, Gradle, npm, Python, Go, and Cargo test/build profiles. DeploymentRunnerModule allowlists production.deploy and production.rollback through an installed profile. Choose the replacement based on the intended effect; a build profile is not a deployment profile.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace or remove the task; retrying cannot re-enable scripts.
A saved path or thread count is present	The value is ignored and never emitted.	Remove it after recording the migration decision.
Prior execution outcome is ambiguous	Version 1.0 provided no normalized result and swallowed failures.	Reconcile repository, artifact, deployment, and host state before another action.
No fixed replacement matches	The task remains disabled.	Add a reviewed, bounded platform capability with explicit policy and tests.
Replacement workspace/profile is unavailable	Replacement fails before an authorized operation.	Configure the exact root or installed profile; do not fall back to shell.
Replacement output or runtime reaches a bound	The fixed profile terminates or truncates according to its contract.	Narrow the operation or increase only the documented bound.

Example

A saved legacy task reaches the compatibility shell:

{
  "scriptDirectory": "./scripts"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "BashScriptExecModule is retired; use an authorized fixed execution profile",
    "retryable": false,
    "migrationTargets": ["ProjectCommandModule", "DeploymentRunnerModule"],
    "requiredAction": "Select a fixed ProjectCommandModule operation or an approved DeploymentRunnerModule profile"
  }
}

Notes

• Pagination: the compatibility shell and local fixed profiles do not paginate.
• Limits: the shell returns immediately. Replacement profiles bound workspace scope, operation, selectors, runtime, process environment, request size, response size, and output.
• Idempotency: the compatibility response is deterministic and side-effect free. Version 1.0 was not idempotent because repository scripts could mutate arbitrary state. Replacement test/build profiles can create build outputs, and deployments require external receipt reconciliation.
• API constraints: version 2.0 performs no API call. Deployment execution uses the exact node-local runner route and an installed profile; workflow input cannot redirect it.
• Logging and secrets: the shell logs only that execution was blocked. It never logs input, configuration, path, script output, or environment values.
• Destructive behavior: the shell performs none. Production deployment and rollback remain approval-gated irreversible writes owned by the installed runner profile.
• Runtime deployment: merged source and published documentation do not change the backend serving /v1/modules/metadata. Workflow Studio will continue to report version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, non-disclosure, repeatability, annotation completeness, discovery exclusion, and direct compatibility lookup. No script or deployment process is executed by these tests.