BuildProjectToolModule Migration Guide

Overview

BuildProjectToolModule is a retired compatibility shell. Version 1.0 accepted caller-controlled Maven, Gradle, npm, or Yarn commands, extra arguments, environment variables, absolute working directories, artifact globs, and workflow-routing values before launching a process on the workflow worker. Workflow Studio exposed no declared inputs or outputs, and the module had no focused safety tests or canonical guide.

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 process, environment, filesystem, artifact, or routing work, and returns ProjectCommandModule as the governed migration target.

ProjectCommandModule runs a fixed, shell-free command profile inside an authorized workspace root. It uses a minimal environment, bounded time and output, secret redaction, and remote-only execution in sandbox or staging.

Usage

1. Find saved workflow tasks whose module type is BuildProjectToolModule.
2. Treat prior SUCCESS state as a build receipt only after reconciling the expected source revision and artifact hash; the legacy idempotency marker did not prove either.
3. Remove legacy environment secrets, arbitrary arguments, absolute paths, artifact globs, and custom workflow-routing values.
4. Configure an authorized workspace root and process home on the workflow execution node.
5. Replace the task with ProjectCommandModule and choose one fixed operation profile.
6. Run it in an authorized sandbox or staging environment and consume its bounded, redacted result.

Inputs

The retired module ignores all legacy inputs. It never resolves the tool, opens the working directory, applies environment variables, starts a process, traverses artifact globs, or changes workflow routing.

The replacement accepts:

Name	Type	Required	Description
operation	string	yes	Fixed command profile.
rootIndex	integer	no	Authorized workspace-root index; defaults to 0.
workingDirectory	string	no	Relative directory inside the authorized root; defaults to ..
module	string	no	Bounded Maven reactor module selector.
testSelector	string	no	Bounded Maven test selector.
timeoutSeconds	integer	no	Process timeout from 1 to 1,800 seconds; defaults to 900.
maxOutputBytes	integer	no	Combined-output ceiling from 1,024 to 1,048,576 bytes; defaults to 262,144.

Outputs

The compatibility shell always returns:

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

ProjectCommandModule returns status, operation, workspace-relative workingDirectory, exitCode, durationMs, redacted bounded output, and truncated.

IntegrationAccount Requirements

Neither module uses an IntegrationAccount. Remove any token, password, key, or credential placed in the legacy env object and rotate it if version 1.0 could have exposed it to a child process.

The replacement requires node configuration for authorized workspace roots and an isolated process home. It inherits only the configured execution node's bounded PATH, JAVA_HOME, locale, and temporary-directory values; workflows cannot provide arbitrary environment variables.

Configuration

The retired module has no active configuration. Saved tool, command, args, script, working_dir, env, timeout, artifact, idempotency, and next-step fields are ignored.

Configure the replacement with immutable values:

{
  "operation": "maven.test",
  "rootIndex": 0,
  "workingDirectory": "services/orders",
  "module": "orders-service",
  "testSelector": "OrderServiceTest",
  "timeoutSeconds": 900,
  "maxOutputBytes": 262144
}

Operations

BuildProjectToolModule supports only one compatibility operation: reject execution and identify the migration target.

ProjectCommandModule allowlists these fixed profiles:

• git.status, git.diff, and git.log
• maven.test and maven.package
• gradle.test and gradle.build
• npm.test, npm.build, and npm.lint
• python.test, go.test, and cargo.test

There is no custom script or arbitrary argument operation.

Errors and Failure Modes

Failure	Behavior	Recovery
Any legacy execution	Returns MODULE_RETIRED with retryable:false.	Replace the task; retrying cannot re-enable local builds.
Legacy task contains secrets	Values are ignored and never emitted.	Remove and rotate credentials that were exposed to version 1.0.
Workspace root is missing or escapes its boundary	Replacement fails before process launch.	Configure the authorized root or use a valid relative directory.
Operation is not allowlisted	Replacement rejects the operation.	Select one fixed profile; do not translate arbitrary shell syntax.
Process times out	The process and descendants are forcibly terminated.	Inspect bounded output and increase the timeout only within the 1,800-second limit.
Output exceeds its ceiling	Output is truncated and marked.	Use targeted tests or inspect the durable build system outside workflow output.
Command exits non-zero	Replacement returns a sanitized failure.	Correct the project or selector, then retry the same fixed profile.

Example

A saved legacy task reaches the compatibility shell:

{
  "tool": "maven",
  "command": "package",
  "args": ["-DskipTests"],
  "working_dir": "/workspace/app"
}

Expected result:

{
  "status": "error",
  "error": {
    "code": "MODULE_RETIRED",
    "message": "BuildProjectToolModule is retired; use an authorized ProjectCommandModule profile",
    "retryable": false,
    "migrationTargets": ["ProjectCommandModule"]
  }
}

Notes

• Pagination: neither the retired shell nor the replacement paginates.
• Limits: the shell returns immediately. The replacement bounds workspace roots, selectors, timeout, output, and process environment.
• Idempotency: the compatibility response is deterministic and side-effect free. A replacement build or test can still write build outputs, so use immutable source revisions and external artifact receipts rather than treating a workflow retry as universally idempotent.
• API constraints: execution is remote-only and limited to sandbox or staging by metadata. The workflow cannot select a shell, arbitrary executable, absolute workspace, or environment map.
• Network behavior: the compatibility shell performs no network work. A fixed package-manager profile may contact repositories according to node policy, so execute it only on an authorized runner.
• Destructive behavior: the compatibility shell performs none. Fixed build profiles can create or replace ordinary build outputs within the authorized workspace; they cannot run caller-provided cleanup or deployment commands.
• Runtime deployment: source, tests, and documentation can be merged and published independently, but live Workflow Studio will continue to show version 1.0 until a normal backend deployment includes version 2.0.
• Unverified boundary: deterministic tests prove fail-closed output, secret non-disclosure, repeatability, metadata discovery exclusion, and direct compatibility lookup. No real build is run because the retired module intentionally performs no provider or process behavior.