stringutil

func CampaignOrchestratorToLockFile ¶ added in v0.36.0

func CampaignOrchestratorToLockFile(orchestratorPath string) string

CampaignOrchestratorToLockFile converts a campaign orchestrator file to its compiled lock file. Campaign orchestrators (.campaign.g.md) compile to lock files (.campaign.lock.yml).

The function removes the .campaign.g.md extension and adds .campaign.lock.yml extension.

Examples:

CampaignOrchestratorToLockFile("test.campaign.g.md")        // returns "test.campaign.lock.yml"
CampaignOrchestratorToLockFile(".github/workflows/prod.campaign.g.md") // returns ".github/workflows/prod.campaign.lock.yml"

func CampaignSpecToLockFile ¶ added in v0.36.0

func CampaignSpecToLockFile(specPath string) string

CampaignSpecToLockFile converts a campaign specification file directly to its compiled lock file. This skips the intermediate orchestrator step for convenience.

The function removes the .campaign.md extension and adds .campaign.lock.yml extension.

Examples:

CampaignSpecToLockFile("test.campaign.md")                  // returns "test.campaign.lock.yml"
CampaignSpecToLockFile(".github/workflows/prod.campaign.md") // returns ".github/workflows/prod.campaign.lock.yml"

func CampaignSpecToOrchestrator ¶ added in v0.36.0

func CampaignSpecToOrchestrator(specPath string) string

CampaignSpecToOrchestrator converts a campaign specification file to its generated orchestrator file. Campaign specs (.campaign.md) generate orchestrator workflows (.campaign.g.md).

The function removes the .campaign.md extension and adds .campaign.g.md extension.

Examples:

CampaignSpecToOrchestrator("test.campaign.md")              // returns "test.campaign.g.md"
CampaignSpecToOrchestrator(".github/workflows/prod.campaign.md") // returns ".github/workflows/prod.campaign.g.md"

func IsAgenticWorkflow ¶ added in v0.36.0

func IsAgenticWorkflow(path string) bool

IsAgenticWorkflow returns true if the file path is an agentic workflow file. Agentic workflows end with .md but are NOT campaign specs or campaign orchestrators.

Examples:

IsAgenticWorkflow("test.md")                                // returns true
IsAgenticWorkflow("weekly-research.md")                     // returns true
IsAgenticWorkflow(".github/workflows/workflow.md")          // returns true
IsAgenticWorkflow("test.campaign.md")                       // returns false (campaign spec)
IsAgenticWorkflow("test.campaign.g.md")                     // returns false (orchestrator)
IsAgenticWorkflow("test.lock.yml")                          // returns false

func IsCampaignLockFile ¶ added in v0.36.0

func IsCampaignLockFile(path string) bool

IsCampaignLockFile returns true if the file path is a compiled campaign lock file. Campaign lock files end with .campaign.lock.yml and are compiled from campaign orchestrators.

Examples:

IsCampaignLockFile("test.campaign.lock.yml")                // returns true
IsCampaignLockFile(".github/workflows/prod.campaign.lock.yml") // returns true
IsCampaignLockFile("test.lock.yml")                         // returns false (regular lock)
IsCampaignLockFile("test.campaign.md")                      // returns false
IsCampaignLockFile("test.md")                               // returns false

func IsCampaignOrchestrator ¶ added in v0.36.0

func IsCampaignOrchestrator(path string) bool

IsCampaignOrchestrator returns true if the file path is a campaign orchestrator file. Campaign orchestrators end with .campaign.g.md and are generated from campaign specs. The .g. indicates "generated".

Examples:

IsCampaignOrchestrator("test.campaign.g.md")                // returns true
IsCampaignOrchestrator(".github/workflows/prod.campaign.g.md") // returns true
IsCampaignOrchestrator("test.campaign.md")                  // returns false (spec)
IsCampaignOrchestrator("test.md")                           // returns false (workflow)
IsCampaignOrchestrator("test.lock.yml")                     // returns false

func IsCampaignSpec ¶ added in v0.36.0

func IsCampaignSpec(path string) bool

IsCampaignSpec returns true if the file path is a campaign specification file. Campaign specs end with .campaign.md and are user-authored files that define campaigns.

Examples:

IsCampaignSpec("test.campaign.md")                          // returns true
IsCampaignSpec(".github/workflows/prod.campaign.md")        // returns true
IsCampaignSpec("test.campaign.g.md")                        // returns false (orchestrator)
IsCampaignSpec("test.md")                                   // returns false (workflow)
IsCampaignSpec("test.lock.yml")                             // returns false

func IsLockFile ¶ added in v0.36.0

func IsLockFile(path string) bool

IsLockFile returns true if the file path is a compiled lock file. Lock files end with .lock.yml and can be compiled from agentic workflows or campaign orchestrators.

Examples:

IsLockFile("test.lock.yml")                                 // returns true
IsLockFile("test.campaign.lock.yml")                        // returns true
IsLockFile(".github/workflows/workflow.lock.yml")           // returns true
IsLockFile("test.md")                                       // returns false
IsLockFile("test.campaign.md")                              // returns false

func LockFileToMarkdown ¶ added in v0.36.0

func LockFileToMarkdown(lockPath string) string

LockFileToMarkdown converts a compiled lock file path back to its markdown source path. This is used when navigating from compiled workflows back to source files.

The function removes the .lock.yml extension and adds .md extension. If the input already has a .md extension, it returns the path unchanged.

Examples:

LockFileToMarkdown("weekly-research.lock.yml")              // returns "weekly-research.md"
LockFileToMarkdown(".github/workflows/test.lock.yml")       // returns ".github/workflows/test.md"
LockFileToMarkdown("workflow.md")                           // returns "workflow.md" (unchanged)
LockFileToMarkdown("my.workflow.lock.yml")                  // returns "my.workflow.md"

func MarkdownToLockFile ¶ added in v0.36.0

func MarkdownToLockFile(mdPath string) string

MarkdownToLockFile converts a workflow markdown file path to its compiled lock file path. This is the standard transformation for agentic workflow files.

The function removes the .md extension and adds .lock.yml extension. If the input already has a .lock.yml extension, it returns the path unchanged.

Examples:

MarkdownToLockFile("weekly-research.md")                    // returns "weekly-research.lock.yml"
MarkdownToLockFile(".github/workflows/test.md")             // returns ".github/workflows/test.lock.yml"
MarkdownToLockFile("workflow.lock.yml")                     // returns "workflow.lock.yml" (unchanged)
MarkdownToLockFile("my.workflow.md")                        // returns "my.workflow.lock.yml"

func NormalizePath ¶ added in v0.35.1

func NormalizePath(path string) string

NormalizePath normalizes a file path by resolving . and .. components. It splits the path on "/" and processes each component: - Empty parts and "." are skipped - ".." moves up one directory (if possible) - Other parts are added to the result

This is useful for resolving relative paths in bundler operations and other file path manipulations where . and .. components need to be resolved.

Examples:

NormalizePath("a/b/../c")        // returns "a/c"
NormalizePath("./a/./b")         // returns "a/b"
NormalizePath("a/b/../../c")     // returns "c"
NormalizePath("../a/b")          // returns "a/b" (leading .. is ignored)
NormalizePath("a//b")            // returns "a/b" (empty parts removed)

func NormalizeSafeOutputIdentifier ¶ added in v0.35.1

func NormalizeSafeOutputIdentifier(identifier string) string

NormalizeSafeOutputIdentifier converts dashes to underscores for safe output identifiers. This standardizes identifier format from the user-facing dash-separated format to the internal underscore-separated format used in safe outputs configuration.

Both dash-separated and underscore-separated formats are valid inputs. This function simply standardizes to the internal representation.

This function performs normalization only - it assumes the input is already a valid identifier and does NOT perform character validation or sanitization.

Examples:

NormalizeSafeOutputIdentifier("create-issue")      // returns "create_issue"
NormalizeSafeOutputIdentifier("create_issue")      // returns "create_issue" (unchanged)
NormalizeSafeOutputIdentifier("add-comment")       // returns "add_comment"
NormalizeSafeOutputIdentifier("update-pr")         // returns "update_pr"

func NormalizeWhitespace ¶

func NormalizeWhitespace(content string) string

NormalizeWhitespace normalizes trailing whitespace and newlines to reduce spurious conflicts. It trims trailing whitespace from each line and ensures exactly one trailing newline.

func NormalizeWorkflowName ¶ added in v0.35.1

func NormalizeWorkflowName(name string) string

NormalizeWorkflowName removes .md and .lock.yml extensions from workflow names. This is used to standardize workflow identifiers regardless of the file format.

The function checks for extensions in order of specificity: 1. Removes .lock.yml extension (the compiled workflow format) 2. Removes .md extension (the markdown source format) 3. Returns the name unchanged if no recognized extension is found

This function performs normalization only - it assumes the input is already a valid identifier and does NOT perform character validation or sanitization.

Examples:

NormalizeWorkflowName("weekly-research")           // returns "weekly-research"
NormalizeWorkflowName("weekly-research.md")        // returns "weekly-research"
NormalizeWorkflowName("weekly-research.lock.yml")  // returns "weekly-research"
NormalizeWorkflowName("my.workflow.md")            // returns "my.workflow"

func ParseVersionValue ¶

func ParseVersionValue(version any) string

ParseVersionValue converts version values of various types to strings. Supports string, int, int64, uint64, and float64 types. Returns empty string for unsupported types.

func SanitizeErrorMessage ¶

func SanitizeErrorMessage(message string) string

SanitizeErrorMessage removes potential secret key names from error messages to prevent information disclosure via logs. This prevents exposing details about an organization's security infrastructure by redacting secret key names that might appear in error messages.

func SanitizeParameterName ¶ added in v0.35.1

func SanitizeParameterName(name string) string

SanitizeParameterName converts a parameter name to a safe JavaScript identifier by replacing non-alphanumeric characters with underscores.

This function ensures that parameter names from workflows can be used safely in JavaScript code by: 1. Replacing any non-alphanumeric characters (except $ and _) with underscores 2. Prepending an underscore if the name starts with a number

Valid characters: a-z, A-Z, 0-9 (not at start), _, $

Examples:

SanitizeParameterName("my-param")        // returns "my_param"
SanitizeParameterName("my.param")        // returns "my_param"
SanitizeParameterName("123param")        // returns "_123param"
SanitizeParameterName("valid_name")      // returns "valid_name"
SanitizeParameterName("$special")        // returns "$special"

func SanitizePythonVariableName ¶ added in v0.35.1

func SanitizePythonVariableName(name string) string

SanitizePythonVariableName converts a parameter name to a valid Python identifier by replacing non-alphanumeric characters with underscores.

This function ensures that parameter names from workflows can be used safely in Python code by: 1. Replacing any non-alphanumeric characters (except _) with underscores 2. Prepending an underscore if the name starts with a number

Valid characters: a-z, A-Z, 0-9 (not at start), _ Note: Python does not allow $ in identifiers (unlike JavaScript)

Examples:

SanitizePythonVariableName("my-param")        // returns "my_param"
SanitizePythonVariableName("my.param")        // returns "my_param"
SanitizePythonVariableName("123param")        // returns "_123param"
SanitizePythonVariableName("valid_name")      // returns "valid_name"

func SanitizeToolID ¶ added in v0.35.1

func SanitizeToolID(toolID string) string

SanitizeToolID removes common MCP prefixes and suffixes from tool IDs. This cleans up tool identifiers by removing redundant MCP-related naming patterns.

The function: 1. Removes "mcp-" prefix 2. Removes "-mcp" suffix 3. Returns the original ID if the result would be empty

Examples:

SanitizeToolID("notion-mcp")        // returns "notion"
SanitizeToolID("mcp-notion")        // returns "notion"
SanitizeToolID("some-mcp-server")   // returns "some-server"
SanitizeToolID("github")            // returns "github" (unchanged)
SanitizeToolID("mcp")               // returns "mcp" (prevents empty result)

func Truncate ¶

func Truncate(s string, maxLen int) string

Truncate truncates a string to a maximum length, adding "..." if truncated. If maxLen is 3 or less, the string is truncated without "...".

This is a general-purpose utility for truncating any string to a configurable length. For domain-specific workflow command identifiers with newline handling, see workflow.ShortenCommand instead.