diff --git a/Makefile b/Makefile index daff37b..7492b2c 100644 --- a/Makefile +++ b/Makefile @@ -405,9 +405,9 @@ validate-jtbd: @echo "" @files=$$(find . \ -type d \( -name .git -o -name .claude \) -prune -o \ - -type f -path "*/skills/*.md" -print | sort); \ + -type f -path "*/skills/*/SKILL.md" -print | sort); \ if [ -z "$$files" ]; then \ - echo "$(YELLOW)No JTBD files found under */skills/*.md$(NC)"; \ + echo "$(YELLOW)No JTBD files found under */skills/*/SKILL.md$(NC)"; \ exit 0; \ fi; \ passed=0; failed=0; \ @@ -506,7 +506,7 @@ pre-commit-hook: jtbd_ok=true; \ jtbd_files=$$(find . \ -type d \( -name .git -o -name .agents -o -name .claude -o -name portal \) -prune -o \ - -type f -path "*/skills/*.md" -print | sort); \ + -type f -path "*/skills/*/SKILL.md" -print | sort); \ if [ -n "$$jtbd_files" ]; then \ for file in $$jtbd_files; do \ if ! python3 scripts/build/validate_jtbd.py "$$file" . > /dev/null 2>&1; then \ diff --git a/scripts/build/validate_jtbd.py b/scripts/build/validate_jtbd.py index 9b611c8..af06c40 100755 --- a/scripts/build/validate_jtbd.py +++ b/scripts/build/validate_jtbd.py @@ -317,17 +317,10 @@ def validate(self) -> bool: else: print(f" ✅ Steps are numbered sequentially (1-{len(step_headers)})") - # Step-based skill: at least 1 YAML step required if len(steps) == 0: - self.errors.append( - "No YAML step blocks found! " - "Jobs must have at least 1 step defined in a YAML code block with 'api' and 'operationId' fields." - ) - print(f" ❌ {self.errors[-1]}") - self.print_summary() - return False - - print(" ✅ At least 1 YAML step is defined") + print(" ℹ️ No YAML step blocks found") + else: + print(" ✅ At least 1 YAML step is defined") # Check that number of headers matches number of YAML blocks if step_headers and steps: @@ -418,7 +411,6 @@ def main(): print(" ✓ At least 1 step header is defined (## Step 1:, ## Step 2:, etc.)") print(" ✓ Step headers are numbered sequentially") print(" ✓ Step header count matches YAML block count") - print(" ✓ At least 1 job step is defined (YAML block)") print(" ✓ Each step has a valid YAML code block with required fields") print(" ✓ API URN points to an existing folder") print(" ✓ OperationId exists in the referenced API spec") diff --git a/scripts/portal_generator/discovery.py b/scripts/portal_generator/discovery.py index acf32f2..d156191 100644 --- a/scripts/portal_generator/discovery.py +++ b/scripts/portal_generator/discovery.py @@ -73,14 +73,25 @@ def discover_skills(repo_root: Path) -> Tuple[Dict[str, List[Dict]], Dict[str, L print("🔍 Scanning for skills...") - for skill_dir in sorted(skills_dir.iterdir()): - if not skill_dir.is_dir(): + # Collect SKILL.md files at skills//SKILL.md and + # skills///SKILL.md (one level of nesting). + skill_files: List[Path] = [] + for entry in sorted(skills_dir.iterdir()): + if not entry.is_dir(): continue - - skill_file = skill_dir / 'SKILL.md' - if not skill_file.exists(): + direct = entry / 'SKILL.md' + if direct.exists(): + skill_files.append(direct) continue + for nested in sorted(entry.iterdir()): + if not nested.is_dir(): + continue + nested_skill = nested / 'SKILL.md' + if nested_skill.exists(): + skill_files.append(nested_skill) + for skill_file in skill_files: + skill_dir = skill_file.parent skill_data = parse_skill(skill_file) if not skill_data: continue diff --git a/skills/mule-development/add-doc-description/SKILL.md b/skills/mule-development/add-doc-description/SKILL.md new file mode 100644 index 0000000..a57ca74 --- /dev/null +++ b/skills/mule-development/add-doc-description/SKILL.md @@ -0,0 +1,302 @@ +--- +name: add-doc-description +description: Call use_skill as your FIRST and ONLY action when the user asks to document, add descriptions to, annotate, or add doc:description attributes to Mule XML files, flows, components, or connectors. Do not read project files first — this skill provides instructions for when to read files. Covers documenting all Mule elements in src/main/mule including flows, sub-flows, configs, listeners, processors, transforms, error handlers, and connectors. When you call use_skill, it must be the only tool call in that response. +metadata: + author: mule-dx-tooling + version: "1.0.0" +--- + +## Overview + +You are an XML documentation expert for MuleSoft. Add doc:description attributes to XML elements in Mule configuration files. + +Scan the Mule project for configuration XML files in `src/main/mule/` and add or update `doc:description` attributes on elements that are missing them or have inaccurate descriptions. + +## Rules +- **doc:description**: A meaningful 1-2 sentence purpose description. MUST NOT exceed 150 characters. +- Preserve ALL existing XML structure, attributes, CDATA blocks, and content exactly as-is +- Do NOT modify, add, or remove any non-doc attributes or elements +- Do NOT modify existing doc:name attributes +- Ensure xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" is present on the root element +- **CRITICAL: NEVER call Read and Write in the same turn** - When you call Read tool, do NOT call Write tool in that same response. Read in one turn, analyze and prepare changes, then Write in the next turn. This is a hard requirement - Read and Write are always separate turns. + +## Important Rules + - **Complete each file fully in ONE Write operation** - do NOT make edits in batches + - **Do NOT modify doc:name attributes** - only work with doc:description + - **Do NOT modify, add, or remove any non-doc attributes or elements** + - **Preserve ALL existing XML structure, attributes, CDATA blocks, and content exactly as-is** + - **Add doc:description to ALL elements listed in section B** - including loggers, processors, connectors, configs, etc. + - **Do NOT change existing accurate descriptions** - only update if they're vague or incorrect + - **Maintain XML formatting** - preserve indentation and structure + - **Be specific** - avoid generic phrases like "processes data" or "handles request" + - **Enforce 150 character limit** - all descriptions must be 150 characters or less + +## Error Handling + - If a file cannot be read, skip it and report the error + - If XML parsing seems problematic, inform the user + - If uncertain about a component's purpose, generate a conservative description or ask the user + +## Step 1: Verify Project Structure + - Check that `src/main/mule` directory exists in the current working directory + - If not found, inform the user this doesn't appear to be a Mule application project + +## Step 2: Find All Mule XML Files + - Use Glob to find all XML files: `src/main/mule/**/*.xml` + - If no files are found, inform the user and exit + +## Step 3: Process Each File Completely +For each XML file found: + +#### A. Read the entire file FIRST +**CRITICAL: You MUST read the actual file content before making any changes.** +**CRITICAL: When you call Read tool, do NOT call Write tool in the same turn. Read only.** +- Use Read tool to load the complete file contents +- Do NOT make assumptions about what's in the file +- Do NOT use content from other files as a template +- Examine the actual namespace declarations, element names, attribute order, and structure +- Verify the file structure matches expectations before proceeding +- After reading, proceed to step B in this same turn (analysis), but save Write for a later turn + +#### B. Analyze and explicitly list all flows/components +**IMPORTANT: Before making ANY changes, explicitly list out what you found to prove you read the file:** + +1. Search through the file and count all major components: + - Count all `` elements and list each by name attribute + - Count all `` elements and list each by name attribute + - Count all `` elements and list each by jobName attribute + - Count global configs (`<*:config>`, `<*:listener-config>`, ``) + - Count global error handlers (`` at top level, outside flows) + +2. Output this analysis in a clear summary format: + + ```text + Analyzing file: [filename] + File size: [line count] lines + + Found: + - [X] flows: [flow-name-1], [flow-name-2], [flow-name-3]... + - [X] sub-flows: [subflow-name-1], [subflow-name-2]... + - [X] batch jobs: [batch-job-name-1]... + - [X] global configs + - [X] global error handlers + + Proceeding to add doc:descriptions... + ``` + +3. Then immediately proceed to step C (no user confirmation needed) + +#### C. Identify elements that need documentation +Identify all elements that need documentation: + +**Mule Flow Elements:** +- ``, `` - Main entry points and business processes +- Source elements: ``, ``, ``, etc. +- Processors: ``, ``, ``, `` +- Routers: ``, ``, ``, ``, ``, `` +- Transforms: ``, ``, ``, `` +- References: `` +- Error handling: ``, ``, `` +- Connector operations: `<*:create>`, `<*:query>`, `<*:request>`, etc. +- Global connector configs (if present): `<*:config>`, `<*:sfdc-config>`, `<*:listener-config>` +- Connection elements: `<*:basic-connection>`, `<*:token-based-authentication-connection>` +- `` +- Validators: `` +- Batch: ``, ``, etc. + +**Connector Config Elements:** +- Config elements: `<*:config>`, `<*:sfdc-config>`, `<*:listener-config>` +- Connection sub-elements: `<*:basic-connection>`, `<*:token-based-authentication-connection>`, `<*:oauth-*-connection>` +- `` +- ``, `` + +**MUnit Test Elements:** +- `` (root) +- `` +- Sections: ``, ``, `` +- Setup: ``, `` +- Assertions: ``, `` +- Mocking: ``, `` +- Verification: `` +- Flow references and processors within tests + +For each element, determine if it needs a doc:description: +- **Add** if the element has no `doc:description` attribute +- **Update** if the existing `doc:description` is vague, generic, or doesn't accurately describe what the element does +- **Skip** if the `doc:description` already exists and accurately describes the element + +#### C. Generate brief descriptions +Create descriptions that are: +- **Maximum 150 characters** - This is a hard limit +- **1-2 sentences** - Brief but meaningful +- **Specific** - Mention what it actually does, not just generic text +- **Present tense** - "Retrieves data" not "Retrieving data" +- **Business-focused** - What, not how +- **Scannable** - Easy to skim when reading through code + +**Use the example template below** for guidance on how to write doc:description attributes for various Mule elements: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +Study the template above to understand the level of detail and style expected for each element type. Note how descriptions are: +- Configuration properties and connector configs: mention what system and auth method +- Connection elements: specify auth type and credential types +- Flows and listeners: describe business process and what triggers them +- Scheduling strategies: state polling frequency in clear terms +- Loggers: explain what specific information is logged and why +- Choice routers and when/otherwise: describe conditions and routing logic +- Transforms: indicate source data, target format, and transformation purpose +- Connector operations: state what operation and which system +- Error handlers: explain what errors are caught and what action is taken + +#### D. Make ALL edits to the file in ONE Write operation +**CRITICAL: Use ONE Write tool call per file, regardless of file size.** + +- Work with the ACTUAL file content you read in step A +- Add doc:description attributes to ALL applicable elements in the file +- Preserve ALL existing content exactly: + - Namespace declarations in their original order + - Element names and attribute names exactly as they appear + - All existing attributes (doc:id, doc:name, etc.) + - CDATA blocks, comments, whitespace, and indentation + - Line breaks and formatting + +**Single Write Strategy:** +- Build the complete modified file content with ALL doc:description additions +- Use ONE Write tool call to save the complete modified file back to disk +- This ensures ONE approval prompt per file, regardless of file size +- No batching, no multiple writes - just one complete operation + +**Why this single Write approach:** +- Simplest strategy - one write per file +- ONE approval prompt per file regardless of size +- Complete atomic operation - either all changes apply or none +- Easier to review all changes at once +- No risk of partial updates + +## Step 4: Present Changes for Approval +After completing ALL edits for a file: +- Summarize what doc:description attributes were added (count by element type) +- Highlight any elements that were skipped and why +- The Write tool will prompt for user approval automatically +- If approved, move to the next file +- If denied, ask what needs adjustment and re-read the file to verify current state + +## Step 5: Repeat for All Files +Continue this process for each XML file in the `src/main/mule/` directory. + +## Step 6: Final Summary +After all files are processed, provide: +- Number of files scanned +- Number of files modified +- Total number of doc:description attributes added +- Total number of doc:description attributes updated diff --git a/skills/mule-development/build-mule-integration/SKILL.md b/skills/mule-development/build-mule-integration/SKILL.md new file mode 100644 index 0000000..23e8f6d --- /dev/null +++ b/skills/mule-development/build-mule-integration/SKILL.md @@ -0,0 +1,1178 @@ +--- +name: build-mule-integration +description: Workflow required before any Mule flow and integration work. Call use_skill as your FIRST action — before reading project files — whenever the user asks to create, generate, update, fix, modify, change, edit, tweak, adjust, or rework any Mule flow, sub-flow, or component. Do not read project files and attempt the change yourself — even targeted single-component changes like 'modify the choice router', 'fix the until-successful', or 'update the catch block' require this workflow. Covers all change types, new integrations and targeted changes to error handlers, catch blocks, choice routers, DataWeave transforms, HTTP listeners, foreach loops, retry policies, scatter-gathers, connectors, and variable assignments. Prompts beginning with 'This code defines...' or 'This flow...' are generation requests, not analysis. When you call this skill, it must be the only tool call in that response. +license: Apache-2.0 +compatibility: Requires Anypoint CLI v4 with the `@mulesoft/anypoint-cli-dx-mule-plugin` DX plugin, Java 11+, Maven 3.6+, Mule Runtime (for `dx mule describe-connector` metadata commands) +metadata: + author: mule-dx-tooling + version: "1.0.0" + cli: anypoint-cli-v4 + theme: professional +allowed-tools: Bash Read Write Edit AskUserQuestion +--- + +# Mule Developer + +Build professional Mule integrations with intelligent connector discovery and data-driven XML generation. + +## When to Use This Skill + +**Use this skill when users request:** + +- "Create a Mule app/integration/flow" +- "Build integration between X and Y" +- "Sync data from X to Y" (e.g., "Salesforce to Slack", "MySQL to Salesforce") +- "Query Salesforce", "Send Slack notifications" +- "Schedule jobs", "Poll data every N minutes" +- "Create webhooks", "Build event-driven flows" + +**Trigger keywords:** create, build, integrate, sync, connect · mule, integration, flow, app, project · salesforce, slack, servicenow, jira, netsuite · mysql, postgresql, database · api, http endpoint, rest api · schedule, poll, every N minutes · alert, notify, webhook. + +Always search Exchange for system-specific connectors first. Most SaaS applications have dedicated connectors. + +--- + +## Prerequisites + +```bash +anypoint-cli-v4 --version +anypoint-cli-v4 dx --help +echo $JAVA_HOME && java -version # Java 11+ +anypoint-cli-v4 conf +``` + +If tools are missing: + +```bash +npm install -g @mulesoft/anypoint-cli-v4 +npm install -g @mulesoft/anypoint-cli-dx-mule-plugin +anypoint-cli-v4 conf username +anypoint-cli-v4 conf password +``` + +--- + +## Bundled scripts + +This skill ships small bash scripts under `scripts/`. Invoke them with the `Bash` tool — do not inline their contents into a response. The scripts persist their output to disk so later steps can consume it mechanically and are not at the mercy of shell variables that vanish when a Bash tool call returns: + +| Script | Purpose | Output location | +| --- | --- | --- | +| `scripts/validate_prerequisites.sh` | Step 1 — validate toolchain, detect/download Mule runtime | `/tmp/mule-dev-env.json` (`mule_version`, `runtime_path`, ...) | +| `scripts/get_latest_connector.sh [nickname]` | Step 3 — search Exchange and print ranked connector candidates (`groupId:assetId:version`, one per line, no score, no winner cue). Writes nothing. | stdout only | +| `scripts/pick_connector.sh ` | Step 3 — record the agent's chosen GAV (after reasoning or an `AskUserQuestion`) as a draft | `tmp/connector-choices/.json` (`{groupId, assetId, version}`) | +| `scripts/commit_connectors.sh` | Step 8 (post-TDD-approval) — promote every draft under `tmp/connector-choices/` to the pinned `tmp/connector-versions/` directory that Phase 2 reads | `tmp/connector-versions/*.json` | +| `scripts/build_gav.sh ` | Turn a saved connector JSON into its `groupId:assetId:version` string | stdout | +| `scripts/build_deps.sh [versions-dir]` | Step 8 — read every connector pin in `tmp/connector-versions/` and emit a comma-joined GAV string, ready for `dx mule project create --dependencies`. Skips `db-driver.json` and any non-pin file. | stdout | +| `scripts/describe_connector.sh ` | Step 4 — run `dx mule describe-connector` for the drafted GAV, save full JSON, AND echo `sources[]`+`configs[]` digest to stdout | `tmp/connector-metadata/.json` + digest on stdout | +| `scripts/maybe_add_http_connector.sh --project ` | Phase 2 — defensive check that HTTP connector is present when OAuth providers were chosen; edits `/pom.xml` | `/pom.xml` | + +Invoke scripts by the absolute path you were given in the "skill is now active" message (it is the directory containing this `SKILL.md`). Do **not** construct relative paths like `../scripts/...` — Cline's working directory shifts across turns and relative paths have produced "No such file or directory" errors in real runs. The inline step examples below write `scripts/...` as shorthand; substitute `/scripts/...` when you actually execute them. + +**Why scripts instead of inline bash:** in earlier iterations connector search was a shell *function* defined inside a single `Bash` tool call. When the call returned the subshell died and the resolved GAV went with it. By the time a later step assembled `dx mule project create`, the only trace of the version was in scrolled-past tool output — and the agent frequently pasted a fictional version from training-time memory instead. Persisting to a file on disk makes the version something we can `jq` at the command site, which removes that failure mode entirely. + +--- + +## Workflow shape (two phases) + +This workflow has two phases separated by a hard user-approval gate. + +- **Phase 1: Technical Design (Steps 1–7).** Identify systems, search Exchange, describe connectors, pick trigger and providers, present a Technical Design Summary, wait for the user to approve. Phase 1 writes **nothing** to the user's project directory — all artifacts live in `/tmp/mule-dev-env.json` (shared env cache owned by `validate_prerequisites.sh`) and the workspace-relative paths `tmp/connector-choices/*.json` (draft connector picks) and `tmp/connector-metadata/*.json`. The pinned `tmp/connector-versions/*.json` directory that Phase 2 reads is only populated after Step 7's approval, by `commit_connectors.sh`. +- **Phase 2: Build (Steps 8–17).** Create the real project, generate config and flow XML, run the build, declare completion. Phase 2 is the only phase that touches the user's project directory. + +Phase 2 MUST NOT start until Step 7's approval gate has been passed explicitly. Skipping Phase 1 — or collapsing it into a single "I'll just use HTTP" decision — is the single highest-impact failure mode of this skill and is what the two-phase structure exists to prevent. + +## Workflow-wide discipline (read before Phase 1) + +- **Build-and-completion separation (Step 16 → Step 17).** The `mvn clean package` command and the completion signal MUST be in separate responses. In the response that runs `mvn`, emit only the build command — no completion signal, no summary, no additional tool calls. Wait for the build result to come back. Read the result. Only then, in the next response, declare completion. +- **One mvn invocation per response.** When re-running a build after a fix, emit only the `mvn` command in that response. Do not bundle it with further edits, follow-up shell commands, or the completion signal. +- **"Completion" means the build already passed.** You may only declare completion after a response that ran `mvn clean package` came back with `BUILD SUCCESS`. +- **Connector versions come ONLY from the Step 3 flow.** Never paste a version from `references/connector-catalog.md`, from training-time memory, or from extrapolation. Step 3 is a three-script dance: `get_latest_connector.sh` lists ranked candidates (stdout only, no pin file), `pick_connector.sh ` records the chosen row as a draft in `tmp/connector-choices/`, and `commit_connectors.sh` (Step 8, first action after TDD approval) promotes every draft to `tmp/connector-versions/`. Every GAV that reaches `dx mule project create --dependencies` or `pom.xml` must be pulled from a `tmp/connector-versions/*.json` file via `scripts/build_deps.sh` (for the full `--dependencies` string at Step 8) or `scripts/build_gav.sh` (for a single connector's GAV elsewhere in Phase 2). The catalog's versions are snapshots that drift — treat it only as a connector-identity reference, not as a version source. +- **The agent does the picking, not the script.** `get_latest_connector.sh` deliberately emits a plain ranked list with no score, no emoji, and no "winner" signal. When the list has one row the choice is obvious. When it has several rows the agent must decide which one matches the user's stated system — and if the rows represent real variants of the same family (Slack `mule4-slack-connector` vs `mule-slack-connector`; FTP vs FTPS; Dynamics 365 vs Dynamics GP/NAV/BC; IBM MQ vs Solace vs JMS), the decision belongs to the user via `AskUserQuestion`, not to the agent's guess. The cost of one extra prompt is one turn; the cost of a silent wrong variant is a full Phase-2 rewrite. +- **No HTTP fallback without evidence.** You may only classify a system as "no dedicated connector exists, use HTTP" AFTER `scripts/get_latest_connector.sh ` has run AND returned zero matches (exit 1) OR every row in the ranked list is obviously a different product (no assetId shares tokens with the system name beyond noise words like `mule`/`connector`). Declaring HTTP as the answer before the search has run is forbidden. Exchange carries dedicated connectors for hundreds of SaaS products that are easy to miss when reasoning from training-time knowledge alone — the helper script is the authoritative check. A dedicated connector gives metadata discovery, typed operations, and correct authentication; HTTP gives raw request plumbing the user would then have to wire up by hand, so quietly falling back to HTTP is a real loss, not a neutral choice. + +--- + +# Phase 1: Technical Design + +## Step 1: Validate Prerequisites + +Run the prerequisite/runtime bootstrap script. It checks the CLI, Java, and either detects an existing Mule runtime or downloads 4.11.2 using the bearer token from `anypoint-cli-v4 conf token`. It writes `/tmp/mule-dev-env.json` — Step 8 reads `mule_version` from there. + +```bash +bash scripts/validate_prerequisites.sh +``` + +If the script exits non-zero, stop and fix the reported problem before proceeding. + +What `validate_prerequisites.sh` validates: Anypoint CLI v4 installed · DX plugin available · Credentials configured (warn-only) · `JAVA_HOME` set · Java 11+ · Mule runtime auto-detected OR auto-downloaded OR fallback to 4.8.0 only if auth token unavailable. + +--- + +## Step 2: Identify Systems and Trigger Hints + +**[BLOCKER] Step 2 MUST NOT prompt the user.** Do not emit an `` or `` here. The trigger decision happens in Step 5 after connector metadata is on disk — prompting now would force generic options (HTTP Listener / Scheduler) instead of real connector sources, which is the single highest-impact anti-pattern this workflow exists to prevent. + +Produce two records in your response text. These are plain prose — not a thinking block, not a tool call — so later steps (and the user) can read them. + +**1. Systems list.** Identify **EXACT system names**: source systems (where data comes from), target systems (where data goes to). Use specific names (Slack, Jira, ServiceNow, Stripe, Shopify), NOT generic terms (chat, ticketing, payments, commerce). Every name on this list will be searched in Step 3; every search must result in a `tmp/connector-choices/.json` draft on disk (the agent picks from the ranked list and calls `pick_connector.sh`). + +**Anti-pattern — inferring a backend from a destination name.** When the prompt mentions a queue, topic, bus, or similar messaging destination, the string that names the destination (e.g. `foo.queue`, `orders.topic`, `events-stream`) is a *label*, not a technology. It does NOT identify which broker is behind it. Do NOT add a specific broker (Anypoint MQ, Kafka, IBM MQ, Solace, SQS, etc.) to the Systems list unless the prompt names it explicitly. If the prompt only says "queue" / "topic" / names a bare destination, list the system as `messaging broker (backend unspecified)` and plan to escalate in Step 3 — the user picks the backend, not the agent. Why this matters: a silently-chosen broker anchors Phase 2 against the wrong connector family, which is a full Phase-2 rewrite to correct. + +**2. Trigger hints.** In one or two sentences, note the **verbatim phrases** from the user prompt that describe what starts the flow or names a cadence — e.g. *"every 3 seconds"* or *"listens for new Stripe charges"* or *"makes a GET request to retrieve customers"*. Do NOT classify yet. No class label, no decision tree, no "so the trigger is…". Step 5 does the trigger decision from connector metadata that does not exist yet; committing to a trigger now — even implicitly via a class — tends to anchor the agent against the real `sources[]` that Step 4 will produce. + +If the prompt mentions no trigger or only describes outbound work ("makes a request", "fetches", "calls"), say so explicitly: "No explicit trigger phrase — outbound-only description." Step 5's metadata-first ladder handles this. + +**Connector strategy per system:** + +- **Major SaaS platforms** (Salesforce, ServiceNow, NetSuite, Workday) → search for dedicated connector in Step 3. +- **Standard protocols** (Database, JMS, FTPS, SFTP) → search for protocol-specific connector in Step 3. +- **Mid-market SaaS** (Stripe, Shopify, HubSpot, Twilio, Plaid, etc.) → search for dedicated connector in Step 3. Do NOT assume these have no connector — Exchange has dedicated connectors for many of them. Training-data intuition that "Stripe/Shopify/etc. is a REST-API-only system" is unreliable; the search is the authority. +- **Queue or Pub/Sub with a named backend** ("Kafka topic", "IBM MQ", "SQS", "Solace") → search for that specific connector in Step 3. +- **Queue or Pub/Sub without a named backend** (the prompt uses "queue", "topic", or a bare destination name without naming the broker technology) → per the Step-2 anti-pattern above, the destination name is not the backend. In Step 3, escalate via `AskUserQuestion` to let the user pick the backend (JMS via any broker provider, Kafka, IBM MQ, Solace, SQS, etc.). Only if the user declines to choose should you default to `mule-jms-connector` — JMS is the generic protocol layer that fits any broker, with the broker selected in Step 6 via the connection provider (active-mq, active-mq-nct, generic). +- **Unknown/Unclear / custom internal APIs** → still search Exchange first in Step 3; HTTP is the fallback only when Step 3's search returns nothing plausibly related. + +Your next tool call after Step 2 MUST be `get_latest_connector.sh` for a system from your Systems list — NOT an `ask_followup_question`, NOT a describe-connector, NOT anything else. Step 3 is the non-negotiable next step. + +--- + +## Step 3: Search Exchange for Connectors, Decide, Draft the Choice + +Step 3 is a three-move loop run **once per named system** from Step 2: + +1. **List** candidates with `get_latest_connector.sh`. +2. **Decide** which row is the right fit — inline rationale if the choice is obvious, `AskUserQuestion` if the rows are real variants of the same system family. +3. **Draft** the chosen GAV with `pick_connector.sh`. The draft lands in `tmp/connector-choices/.json` and stays there through Phase 1. + +The script does not pin a winner. There is no emoji, no score, no "Picked" line in its output. When the list has one row the shape of the output is "one row"; when it has several the shape is "several rows" and that is the cue to read the names and reason about intent — or to escalate. + +**Mandatory search rule.** Run `get_latest_connector.sh` for EVERY named system from Step 2 — including systems whose prominence in your training data leads you to assume they have no dedicated connector. Declaring "system X has no dedicated connector" without the script having run is forbidden. This is the rule that prevents silent HTTP fallback — see "No HTTP fallback without evidence" in the workflow-wide discipline. + +**Version source-of-truth rule (MANDATORY):** + +- The **only** acceptable source for a connector's version number is `get_latest_connector.sh` run against live Exchange in the current session, recorded via `pick_connector.sh`, and later promoted to `tmp/connector-versions/` by `commit_connectors.sh`. This applies equally to `dx mule project create --dependencies`, `pom.xml` `` blocks, and every other place a version appears. +- **Do not** paste a version from `references/connector-catalog.md`. The catalog exists to help identify *which* connector to use (asset ID, purpose); its version numbers are best-effort snapshots that drift. +- **Do not** invent a version from memory or by extrapolating. Version numbers on Exchange are not predictable. +- **Do not** write a version before the corresponding `tmp/connector-choices/.json` draft exists on disk. + +### Move 1 — list + +One invocation per named system. The nickname is how the draft and later pin will be named, so pick something short and use it consistently: + +```bash +bash scripts/get_latest_connector.sh mule-salesforce-connector sfdc +``` + +Stdout shape, one GAV per line, ranked best-guess-first: + +``` +com.mulesoft.connectors:mule-salesforce-connector:11.1.0 +com.mulesoft.connectors:mule-salesforce-analytics-connector:4.1.0 +com.mulesoft.connectors:mule-salesforce-composite-connector:2.5.2 +com.mulesoft.connectors:mule-salesforce-marketing-cloud-connector:5.0.0 +``` + +Exit 0 means at least one row was returned; exit 1 means no Mule 4 extension matched and you need to treat this system as HTTP-fallback territory (see the workflow-wide discipline). + +### Move 2 — decide & confirm + +Read the list. Two cases, in order: + +**Case A — one row.** Only one Mule 4 extension matches. Acknowledge the choice inline in one sentence ("Only match for HTTP: `org.mule.connectors:mule-http-connector:1.11.1`") and go to Move 3. + +**Case B — multiple rows that are real variants of the same system family.** Rows whose assetId does not plausibly name the user's system are noise — filter them out logically. If more than one row/choice remains after the logical filtering for the user's system (e.g., Salesforce query returned `mule-salesforce-connector` plus three Salesforce sub-products for Analytics / Composite / Marketing Cloud etc.), always escalate via `AskUserQuestion`. Some common variant families that requires user confirmation: + +- `slack` → `mule-slack-connector` (community, v4.x) **vs** `mule4-slack-connector` (premium MuleSoft, v2.x). Different OAuth shapes, different operations — neither is a "newer version" of the other. +- `ftp` → `mule-ftp-connector` (plain) **vs** `mule-ftps-connector` (TLS). Always confirm and suggest FTPS for best security practices. +- `ibm-mq` vs `solace` vs `kafka` vs `jms` — a destination name in the prompt (e.g. `foo.queue`, `bar.topic`) does NOT identify the backend. Unless the prompt explicitly names the broker technology, escalate with these as options; `mule-jms-connector` is the generic-protocol fallback when the user declines to pick. +- `microsoft-dynamics-*` — 365, GP, NAV, 365-Business-Central, CRM are different products the user may have meant interchangeably. +- `oracle-ebs` vs `oracle-ebs-122` — alternate EBS major versions. +- Any pair whose assetIds share the target system's name and differ only in a variant suffix, protocol marker, major-version marker, or the `mule4-` vs `mule-` prefix. + +Prompt shape when you escalate: + +```xml + +Two Mule 4 Slack connectors exist on Exchange. Which should this integration use? +[ + "org.mule.connectors:mule-slack-connector:4.3.2 — community Slack connector", + "com.mulesoft.connectors:mule4-slack-connector:2.0.1 — MuleSoft premium Slack connector", + "Other — describe which Slack variant you need" +] + +``` + +When more than one choice exists, confirm with user; a silent wrong variant costs a Phase-2 rewrite. + +If the user's prompt explicitly names one variant ("use the Dynamics 365 connector, not BC", "the premium Slack connector only"), that pins the choice and you proceed without asking. + +### Move 3 — draft + +Record the chosen GAV as a draft. Idempotent — you can re-run with a different GAV if Step 4 or Step 5 metadata reveals a better fit: + +```bash +bash scripts/pick_connector.sh sfdc com.mulesoft.connectors:mule-salesforce-connector:11.1.0 +bash scripts/pick_connector.sh slack com.mulesoft.connectors:mule4-slack-connector:2.0.1 +bash scripts/pick_connector.sh jms org.mule.connectors:mule-jms-connector:1.10.3 +# → tmp/connector-choices/{sfdc,slack,jms}.json now each contain {groupId, assetId, version} +``` + +If you realize after Step 4's metadata digest that the draft is wrong, re-run `pick_connector.sh` with the corrected GAV. Drafts remain mutable until Step 8's `commit_connectors.sh` promotes them. + +**Why drafts instead of pins during Phase 1.** If a connector choice bakes into `tmp/connector-versions/` before the user has seen the Technical Design Summary, the agent — and every downstream check — treats it as settled. Holding the choice as a draft until TDD approval keeps the whole design reversible, and lets the approval gate be the real commitment point. + +### Selection rules the script applies internally + +(Reference only — you don't need to reimplement them. The list is ordered best-guess-first; treat ordering as a soft hint, not a directive.) + +- Only `"type": "extension"` (Mule 4 compatible) — Mule 3 `type=connector` assets, templates, examples, and rest-apis are filtered out. +- Any groupId whose asset is `type="extension"` is admissible; ranking keeps first-party connectors on top via a 3-tier preference (`com.mulesoft.connectors` > `org.mule.connectors` > other). +- Latest semantic version within each `(groupId, assetId)` group. +- Token-overlap scoring with the search term; the premium groupId and shorter assetId break ties. Scores are used for ordering only and are never emitted. +- Two pages fetched in parallel (offsets 0 and 200) so broad searches like `salesforce` don't drop candidates off a single page. + +### Common search terms + +| System | Search term | +| --- | --- | +| Salesforce | `mule-salesforce-connector` | +| Database | `mule-db-connector` | +| HTTP | `mule-http-connector` | +| NetSuite | `mule-netsuite-connector` | +| ServiceNow | `mule-servicenow-connector` | +| Amazon S3 | `mule-amazon-s3-connector` | +| JMS | `mule-jms-connector` | +| Slack | `mule-slack-connector` (returns both Slack variants — this is the ambiguous case above) | + +For any system not in the list, search dynamically with the system name (e.g. `stripe`, `shopify`, `hubspot`) — don't assume naming patterns and don't assume the system has no connector. + +--- + +## Step 4: Describe Connectors + +For each connector resolved in Step 3, retrieve its full metadata and **read the digest** that the wrapper script prints. Use `describe_connector.sh` rather than writing the `describe-connector` pipeline by hand — the wrapper resolves the probe path, saves the full JSON to disk for later steps, AND echoes `sources[]` and `configs[]` to stdout so you see what Step 5 will need: + +```bash +bash scripts/describe_connector.sh sfdc # nickname from Step 3 +bash scripts/describe_connector.sh stripe +bash scripts/describe_connector.sh http +``` + +Each invocation writes `tmp/connector-metadata/.json` (full response, consumed again by Phase 2) and prints a digest shaped like this: + +```json +{ + "namespace_prefix": "stripe", + "sources": [ + "on-canceled-subscription-listener", + "on-new-charge-listener", + ... + ], + "configs": [ + { "name": "config", "providers": ["api-key"] } + ], + "operations_count": 335, + "operations_sample": ["createV13dSecure", "..."] +} +``` + +**Read the `sources[]` array that comes back.** That list is the set of real native triggers the connector supports; it is what Step 5 branches on. Do not skip past the digest straight to the next `describe_connector.sh` call — Step 5's trigger decision depends on you knowing which sources each connector exposes, and the digest is the cheapest place to get that information. + +If you ever need the full response (e.g. to introspect `childElements[]` for `oauth-callback-config`), read `tmp/connector-metadata/.json` directly. + +**Manual fallback** — if for some reason the wrapper is unavailable, you can reproduce it by hand. In Phase 1 the draft file is authoritative; `build_gav.sh` accepts either location: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-choices/sfdc.json)" \ + --output json > tmp/connector-metadata/sfdc.json +jq '{namespace: .namespace.prefix, sources, configs: [.configs[] | {name, providers: [.connectionProviders[]?]}]}' tmp/connector-metadata/sfdc.json +``` + +But in the common case prefer the wrapper — it is one line instead of three and it makes the sources list visible in your turn's tool output without a follow-up call. + +--- + +## Step 5: Select Trigger + +Every top-level flow (that is not a sub-flow or a `` target) needs exactly ONE trigger. Step 5 decides *which* trigger by letting connector metadata drive the choice — not prompt-text intuition. + +**[BLOCKER] Explore-before-decide gate.** Before committing to a trigger — whether inline or via `AskUserQuestion` — both of the following must be true for EVERY named system from Step 2's Systems list: + +1. `tmp/connector-choices/.json` exists on disk (Step 3, via `pick_connector.sh`). +2. `tmp/connector-metadata/.json` exists on disk (Step 4). + +AND you must have the `sources[]` content in view. Run: + +```bash +for f in tmp/connector-metadata/*.json; do + echo "--- $f ---" + jq '{namespace: .namespace.prefix, sources}' "$f" +done +``` + +in the response that begins Step 5, and read the output. This is the same data the `describe_connector.sh` digest already showed per connector in Step 4, but re-echoing it here puts every connector's sources side-by-side in one place right before the decision. Do not commit to a trigger without having those lists in the current tool output — past turns scroll out of context quickly. + +Why this gate exists: if the agent commits to a trigger before reading `sources[]`, the usual failure mode is to default to `http:listener` (treating the prompt as a webhook) and silently ignore a real connector source that Step 4 just fetched. A connector's `sources[]` array is the authoritative list of triggers it supports; Step 5 must branch from that list, not from prompt-text intuition. + +### Decision ladder (evaluate in order) + +Work through the rungs below in order. Each rung is one of the possible *paths* — there is no "fallback" ranking; the first path whose preconditions all match is the one you take. + +#### Rung 1 — Connector-source path + +For each connector in scope, examine `sources[]` from the digest. For any source whose **name** plausibly relates to the user's stated need (noun match: "product", "order", "charge", "customer"; AND verb-prefix consistency: `on-new-*`, `on-updated-*`, `on-modified-*`, `on-*-arrived`, `poll-*`, `*-listener`, `*-trigger`), inspect its shape via the unified `describe-connector` command with `--type source`: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-choices/.json)" \ + --type source \ + --name \ + --output json +``` + +Do **not** call `source-detail` on every source — only on those whose name plausibly fits the user's intent per the noun+verb-prefix check above. On rich connectors this is the difference between 1–2 CLI calls and 7+ (Shopify, Salesforce, etc.). + +Compare the returned **shapes** — not the names alone — to the user's intent: + +- If the source's `childElements[]` includes a `scheduling-strategy` element, this is a **polling source** — the connector itself handles the cadence natively. When the user's prompt names a cadence ("every N", "daily", "hourly") AND the matched source is a polling source, the cadence goes inside the source's `` child. **Do NOT introduce a separate top-level `` alongside it.** Example correct shape: + ```xml + + + + + + ``` +- If the source has no `scheduling-strategy` child and exposes an event (`on-new-*`, `on-modified-*`), it's an **event source** — use it directly; no top-level scheduler needed. +- If the source's shape includes `listenerConfig` references, it's a **webhook receiver** — suitable for "receive callback at endpoint" prompts. + +**Commit inline** to a connector source when exactly one source's shape fits the user's intent and the match is explainable in one sentence. State the choice with a one-line rationale citing the source name. + +**Prompt via `AskUserQuestion`** when two or more sources both pass the shape check against the user's intent, OR when the user's language is genuinely ambiguous about which source semantics they want. Options list the real source names, not generic placeholders: + +```xml + +Which Salesforce event should trigger this flow? +[ + "salesforce:replay-topic-listener — subscribe to a Salesforce streaming topic", + "salesforce:modified-object-listener — fire when a record of a given sObject is modified", + "Other — pick a different source" +] + +``` + +If no source passes the shape check against any connector in scope, move to Rung 2. + +#### Rung 2 — Generic scheduler path + +Take this path when: + +- No connector source fits the user's intent (Rung 1 examined the candidates and none matched), AND +- The prompt names a cadence ("every N", "daily", "hourly", "poll every…"), AND +- The flow body will call connector operations (not event-driven). + +Use `` with `` or ``. State the choice inline. + +**Record the rejection.** When taking this path, note in one sentence why Rung 1's sources were rejected — e.g. "Shopify's `on-updated-product-trigger` matches 'every 3 seconds' but the user wants to pull by custom date range not 'updated since last poll', so a generic `` + `shopify:product-list` is more appropriate." Step 7's TDD requires this list; capture it now while the reasoning is fresh. + +#### Rung 3 — HTTP Listener path + +Take this path when: + +- The prompt explicitly says "expose endpoint", "receive HTTP request", "provide REST API", "webhook at /path", AND +- No connector source in scope is a webhook-style receiver. + +Use ``. State the choice inline. Record which connector sources were considered and why they were rejected (see Step 7). + +#### Rung 4 — Ask the user + +Take this path when none of Rungs 1–3 clearly apply — e.g. the prompt is outbound-only ("makes a request", "fetches", "retrieves") with no cadence and no endpoint language. `AskUserQuestion` with options derived from the actual `sources[]` of connectors in scope PLUS Scheduler and HTTP Listener: + +```xml + +The prompt describes outbound calls but does not name a trigger. What should start this flow? +[ + "Scheduler — run on a time-based schedule", + "HTTP Listener — receive an inbound HTTP request", + ": — native event from one of the connectors in scope (list any that apply based on sources[])", + "Other — please describe" +] + +``` + +### After the decision + +Record the selected trigger, its owning connector (if any), and — if the path is Rung 2 or Rung 3 — the list of connector sources that were considered and one-line reasons each was dismissed. Step 7's TDD surfaces this list; if it is missing, the TDD is incomplete and Phase 2 cannot start. + +**[BLOCKER] WAIT for the user's response before moving to Step 6 when this step prompts.** + +--- + +## Step 6: Select Connection Providers + +**Ask the user only when there is an actual choice to make.** For each connector, look at the `configs[]` metadata captured in Step 4 — specifically the `connectionProviders` list of the config that owns the operation you intend to call in Phase 2. + +**Decision rule:** + +- **Multiple configs or multiple providers** → **MUST** use `AskUserQuestion`. The user's choice determines both which `config-name` and which `--connection-provider` you pass to Step 11's `config-detail` call, and which XML structure you write in Step 12. +- **Exactly one config and exactly one provider** → **DO NOT** prompt. State the choice inline in one line ("Using `s3:config[connection]` — the only option provided by the connector") and proceed. Prompts that offer a single "option" look like pointless ceremony and waste a conversation turn. + +**Worked examples from live Exchange metadata:** + +| Connector | `configs` × providers | Action | +| --- | --- | --- | +| S3 connector | `config[connection]` | Announce, do NOT prompt | +| VM connector | `config[connection]` | Announce, do NOT prompt | +| HTTP connector | `listener-config[listener-connection]`, `request-config[request-connection]` | Configs map 1:1 to listener vs request — determined by the flow shape (trigger vs outbound call), not a user preference. Announce, do NOT prompt. | +| A multi-config connector with stream vs. non-stream configs | `config[basic, role]`, `streams-config[streams]` | **Prompt** — pick the config whose operations match the use case, and if that config has >1 provider, pick a provider. | +| A connector offering basic / OAuth / JWT / client-credentials | `config[basic, oauth-user-pass, jwt, oauth-client-credentials]` | **Prompt** — real alternatives with different credential models. | +| Database connector | `config[my-sql-connection, oracle-connection, data-source-connection, generic-connection, ...]` | **Prompt** for the provider, then resolve the JDBC driver GAV in the same step (see "Step 6b — JDBC driver resolution" below). Step 9 is a mechanical `pom.xml` edit. | + +**When you do prompt,** present only the real alternatives (don't pad with "if unsure..." copy). Example: + +> This connector offers four connection providers. Which should this integration use? +> - `basic` — username + password + security token +> - `oauth-user-pass` — OAuth with user credentials +> - `jwt` — JWT bearer token (server-to-server) +> - `oauth-client-credentials` — OAuth client credentials + +**Do not offer a "recommendation" as one of the options** if it's really the only option. If there is only one choice, do not ask. + +Store the selected `(config-name, connection-provider)` pair for each connector, and **persist the `describe-connector` connection-provider output** for Phase 2 so it doesn't have to re-invoke the CLI. **Flag semantics note:** `--name` carries the **connection provider** name, `--config-name` carries the **config** name — easy to get backwards: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-choices/sfdc.json)" \ + --type connection-provider \ + --name basic-connection \ + --config-name sfdc-config \ + --output json > tmp/connector-metadata/sfdc-config.json +``` + +### Step 6b — JDBC driver resolution (only if `mule-db-connector` is in scope) + +`mule-db-connector` is the one case where the Step-6 provider choice needs more clarification. The provider choice only handles the XML connection element (``, ``, etc.), but the **JDBC driver JAR** is a separate Maven artifact that must ship alongside the connector via ``. Resolve both in Step 6 so Step 7's design summary can show a full `groupId:artifactId:version` for the driver and Step 9 becomes a mechanical `pom.xml` edit with no further prompting. + +**Branch on the Step-6 provider answer:** + +| Provider picked | Driver auto-pin from the canonical table (Step 9) | Prompt? | +| --- | --- | --- | +| `my-sql` | `com.mysql:mysql-connector-j:8.4.0` (8.4 LTS; 9.x requires JDK 21) | No — announce inline | +| `oracle` | `com.oracle.database.jdbc:ojdbc11:23.9.0.25.07` (Java 17+) | No — announce inline | +| `mssql` | `com.microsoft.sqlserver:mssql-jdbc:13.4.0.jre11` (Java 17+) | No — announce inline | +| `generic` **and the target database is identifiable as PostgreSQL** (user prompt names Postgres, a prior turn named Postgres, or a JDBC URL placeholder shows `jdbc:postgresql://`) | `org.postgresql:postgresql:42.7.11` — the canonical `generic` pairing | No — announce inline | +| `generic` **and the target is something else or unspecified** (H2, Snowflake, SAP HANA, Vertica, unknown, or the user didn't name a database) | **Cannot auto-pin** — `generic-connection` accepts any JDBC URL and only the target database identifies the driver. IF user select generic, see `references/jdbc-drivers.md` for canonical options, then prompt with Postgres listed first (most common `generic` target). | **Yes** | +| `data-source` | **Cannot auto-pin** — driver is supplied by the container, or by an explicit `` declaration. Prompt. | **Yes** | +| `derby` | **Multi-artifact + JDK-dependent** — If selected, see `references/jdbc-drivers.md` for the embedded vs network-client split and the Java 17 vs Java 8 version matrix. Prompt on `embedded` vs `client`. | **Yes** | + +The rule: **if the target database is one of the first rows above (my-sql, oracle, mssql or generic with postgres) do not prompt — auto-pin and announce inline.** Reserve the prompt for non-canonical `generic` targets and for the inherently multi-choice providers (`data-source`, `derby`). + +The always-prompt branches all use the same prompt shape: + +```xml + +You picked for ; which JDBC driver should ship as a sharedLibrary? +[ + " — ", + " — ...", + "Other — I will provide a groupId:artifactId:version" +] + +``` + +**What Step 6 must record for Step 9:** + +One or more `{groupId, artifactId, version}` tuples, plus the driver class, persisted so Step 9 can emit the `` + `` pairs without re-asking. Use a sidecar file next to the connector choice: + +```bash +# example: after Step 6 picks my-sql +cat > tmp/connector-choices/db-driver.json <<'JSON' +{ + "dependencies": [ + { "groupId": "com.mysql", "artifactId": "mysql-connector-j", "version": "8.4.0" } + ], + "driverClass": "com.mysql.cj.jdbc.Driver" +} +JSON +``` + +For `derby:embedded` that file contains three entries; for `generic` with PostgreSQL it contains one. The Step-9 applier reads this file and applies every entry in it to `pom.xml`. + +The driver choice will be part of the technical design. Step 7 shows it under "Build-time additions"; the user's approval at Step 7 is what authorizes Step 9 to edit `pom.xml`. +--- + +## Step 7: Present Technical Design Summary + +**[BLOCKER] Present ONLY after Steps 1–6 are complete.** Every connector must have a drafted GAV (from `tmp/connector-choices/*.json`), every connector must have captured metadata (from `tmp/connector-metadata/*.json`), and every config must have a selected provider. If any of those is missing, go back to the relevant step — do not paper over with "TBD" in the summary. + +``` +**Technical Design Summary** + +**User Requirement:** "" + +**Project Context:** +- Project directory: +- Work type: +- Mule runtime: +- Java: + +**Trigger:** +- Selected: from + (e.g., "shopify:on-updated-product-trigger with fixed-frequency 3000ms" or "salesforce:replay-topic-listener from mule-salesforce-connector:10.15.7" or "Built-in Scheduler, every 5 minutes") +- Sources considered: list the `sources[]` entries that were examined via `source-detail` (if any), with one line each + stating why the source was chosen OR dismissed. If the selected trigger is `` or `` and any + in-scope connector has a `sources[]` entry, at least one rejection line is required — a TDD whose "Sources considered" + is empty while a connector source exists is incomplete, and Phase 2 cannot start. + Example: + - `shopify:on-updated-product-trigger` — SELECTED: polling source with `scheduling-strategy` child, matches "every 3 seconds" intent. + - `shopify:on-new-product-trigger` — dismissed: fires only on creation, user wants updates too. + - `shopify:on-updated-customer-trigger` — dismissed: wrong object (product, not customer). + +**Required Connectors:** +1. : [com.mulesoft.connectors | org.mule.connectors | third-party] + - Purpose: + - Config: | Provider: +2. ... + +**Build-time additions (auto):** +- `mule-http-connector` — included if the trigger is HTTP Listener OR any Step 6 provider is OAuth-family (callback listener) +- JDBC driver(s) — included if `mule-db-connector` is in scope. List **every** `groupId:artifactId:version` recorded in `tmp/connector-choices/db-driver.json` from Step 6b, plus the driver class. Vague phrasing like "PostgreSQL JDBC driver included" is not acceptable here — the user is approving an explicit build edit and needs the exact coordinates. + Example: + - `org.postgresql:postgresql:42.7.11` (driver class `org.postgresql.Driver`) — added as `` and `` in `pom.xml`. + +**Built-in processors anticipated (if applicable):** +- DataWeave, Logger, error handlers +``` + +Then ask for explicit approval: + +```xml + +Please review the technical design above. Proceed to build (Phase 2)? +[ + "Yes, proceed to build.", + "No, I want to change the plan.", + "No, cancel generation." +] + +``` + +**[BLOCKER] WAIT for explicit "Yes, proceed to build." before Step 8.** On "No, I want to change the plan.", ask which part (trigger, connectors, providers) and loop back to the relevant step. On "No, cancel generation.", stop the workflow politely. + +Why this gate matters: Phase 1 is the last chance to catch a silent HTTP fallback, a wrong connector variant, a wrong trigger, or a missing clarifying question. Once Phase 2 begins the project skeleton is on disk and rewinding is more expensive for everyone. The summary is the user's chance to correct course; respect "No, I want to change the plan." as a first-class outcome, not an exception. + +**After approval, the very first action of Step 8 is `commit_connectors.sh` — that is the script that promotes every Phase-1 draft in `tmp/connector-choices/` to the pinned `tmp/connector-versions/` directory that `dx mule project create` and `pom.xml` will read from. Do not skip it; `build_deps.sh` / `build_gav.sh` calls later in Phase 2 will fail if the pin files aren't there.** + +**Output:** User approval to proceed. + +--- + +# Phase 2: Build + +## Step 8: Create Project + +**First action — promote Phase 1 drafts to pinned versions.** The user just approved the TDD, so every connector choice in `tmp/connector-choices/` is now official. Promote them in one shot: + +```bash +bash scripts/commit_connectors.sh +# → copies every tmp/connector-choices/*.json → tmp/connector-versions/*.json +# → exits 1 if no drafts exist (means Step 3 was skipped for some system) +``` + +Then read `/tmp/mule-dev-env.json` for the Mule version and use `build_deps.sh` to emit the full `--dependencies` string from the pins on disk — do not retype GAVs from previous tool output, and do not inline `$(build_gav.sh ...)` once per connector: + +```bash +MULE_VERSION=$(jq -r '.mule_version' /tmp/mule-dev-env.json) + +anypoint-cli-v4 dx mule project create \ + --group-id com.example \ + --mule-version "$MULE_VERSION" \ + --dependencies "$(bash scripts/build_deps.sh)" +``` + +`build_deps.sh` reads every `tmp/connector-versions/*.json` pin, filters out the Step 6b JDBC driver sidecar (`db-driver.json`), and prints a comma-joined GAV string. Any pin file in that directory is included automatically — including `http.json` if you added it via the rule below. + +**Why one wrapper instead of N inlined `$(build_gav.sh …)` substitutions:** with absolute script paths (per the invocation rule above) each inlined `$(…)` is ~165 characters, so a 4-connector project produces a 1000+ character `dx mule project create` command. The Dev Agent terminal harness loses its completion marker on very long commands and stalls the whole turn until the 2-minute timeout fires. `build_deps.sh` keeps the command under ~250 characters regardless of how many connectors are in scope. + +**Every connector that appears in the approved Technical Design Summary must have a pin in `tmp/connector-versions/` before `build_deps.sh` runs** — `commit_connectors.sh` already put them there. Two cases add an extra connector beyond the systems explicitly named in the TDD: + +| Condition | Added connector | +| --- | --- | +| Step 5 selected trigger is HTTP Listener (flow contains ``) | `mule-http-connector` | +| Step 6 selected any OAuth-family provider (OAuth, JWT, auth-code) | `mule-http-connector` (for OAuth callbacks) | +| Any event-listener source trigger (e.g., ``, ``) | None beyond the connector that owns the source — it is already in the TDD | + +If either HTTP-trigger condition applies and you have not already picked HTTP in Step 3, run `get_latest_connector.sh mule-http-connector http` + `pick_connector.sh http ` + `commit_connectors.sh` **before** `dx mule project create` so `tmp/connector-versions/http.json` exists when `build_deps.sh` scans the directory. Missing it causes a first-build failure like `Can't resolve http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd` — self-healable, but it costs a turn. + +**Version source-of-truth (from Step 3):** every GAV in `--dependencies` must come from a `tmp/connector-versions/*.json` file. **Do not** inline a literal version like `com.mulesoft.connectors:mule-amazon-s3-connector:6.6.0` in the `--dependencies` string — if you bypass `build_deps.sh` and the literal version differs from what the helper would have returned, `mvn clean package` will fail with a "not found" error, and the failure is often not self-healable because the version is fictional. + +**Project structure created:** + +- `pom.xml` (Maven configuration with dependencies) +- `mule-artifact.json` (artifact metadata with correct Java version) +- `src/main/mule/.xml` (flow definition) +- `src/main/resources/` (configuration files) + +--- + +## Step 9: Apply JDBC Driver to pom.xml + +The driver GAVs were already chosen in Step 6b and approved by the user at Step 7. Step 9 reads `tmp/connector-choices/db-driver.json` and applies every entry to `/pom.xml` — one entry produces one `` block AND one `` block. Skip this step entirely if `mule-db-connector` is not in scope. + +If `tmp/connector-choices/db-driver.json` is missing but `mule-db-connector` is in scope, return to Step 6b — do NOT invent a driver here or assume prematurely. + +**For every entry in `db-driver.json`'s `dependencies[]` array, add both:** + +1. **`` inside ``**, verbatim from the sidecar: + +```xml + + {groupId} + {artifactId} + {version} + +``` + +2. **`` inside the `mule-maven-plugin` ``** — `groupId`/`artifactId` copied verbatim from the `` above (no version here). + +```xml + + + + {groupId} + {artifactId} + + + + +``` +--- + +## Step 10: Verify HTTP Connector (OAuth/HTTP-Listener defensive check) + +In v7, Step 8's `--dependencies` already includes `mule-http-connector` when Step 5 chose HTTP Listener or Step 6 chose an OAuth-family provider — because Phase 1's approved TDD made that visible. This step is a **defensive no-op check** in the common case: run the helper in case the TDD missed the HTTP addition for some reason. + +**Skip this step entirely** when none of the selected providers match `oauth|jwt|auth-code|authorization-code` AND the trigger is not HTTP Listener. Running it as a "just to be safe" consumes a turn. + +For the OAuth / HTTP-Listener case, run the idempotent helper: + +```bash +bash /scripts/maybe_add_http_connector.sh \ + --project ./ \ + "oauth-user-pass" # one argument per Step-6 provider +``` + +`` is the absolute path you were given in the "skill is now active" message (the directory containing this `SKILL.md`). Using the absolute path avoids the "No such file or directory" errors that come from relative invocation. + +If *any* provider argument matches `oauth`, `jwt`, `auth-code`, or `authorization-code` (case-insensitive), the script: + +1. Reuses `/tmp/connector-choices/http.json` if the agent already picked HTTP in Step 3, otherwise runs `get_latest_connector.sh mule-http-connector http` and drafts the top row via `pick_connector.sh http ` — HTTP is an unambiguous search, so no user prompt is needed. +2. Inserts a `` block before `` in `/pom.xml` (with `mule-plugin`). +3. Is a no-op if the HTTP connector is already present. + +**Manual fallback** — also add HTTP connector if: the connector documentation mentions "callback URL" or "redirect URI", or Step 11 `config-detail` shows an `oauth-callback-config` child element. Without HTTP connector the build fails with: `The content of element ':' is not complete`. + +--- + +## Step 11: Get Configuration Details + +Phase 1 Step 6 already persisted `config-detail` output to `tmp/connector-metadata/-config.json`. Read it from there: + +```bash +cat tmp/connector-metadata/sfdc-config.json +``` + +Only re-invoke the CLI if the cache file is missing (which should not happen if Phase 1 ran correctly). **Flag semantics note:** `--name` is the connection provider, `--config-name` is the config: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-versions/sfdc.json)" \ + --type connection-provider \ + --name basic-connection \ + --config-name sfdc-config \ + --output json +``` + +**Response shape** (same `attributes` + `childElements` pattern): + +```json +{ + "name": "sfdc-config", + "prefix": "salesforce", + "elementName": "sfdc-config", + "attributes": [ { "attributeName": "name", "required": true } ], + "childElements": [ + { "paramName": "expirationPolicy", "prefix": "salesforce", "elementName": "expiration-policy" } + ], + "connectionProviders": [ + { + "name": "basic-connection", + "prefix": "salesforce", + "elementName": "basic-connection", + "attributes": [ + { "attributeName": "username", "required": true }, + { "attributeName": "password", "required": true }, + { "attributeName": "securityToken", "required": true } + ], + "childElements": [ + { "paramName": "reconnection", "prefix": "mule", "elementName": "reconnection" } + ] + } + ] +} +``` + +**Check BOTH attributes AND childElements** of the selected connection provider: + +```bash +jq '.connectionProviders[0].childElements[] | select(.paramName == "oauthCallbackConfig")' tmp/connector-metadata/sfdc-config.json +``` + +**Connection providers use one of two patterns:** + +1. **Attributes pattern** (e.g., Salesforce basic-connection): + + ```xml + + ``` + +2. **Child elements pattern** (e.g., Slack OAuth): + + ```xml + + + + ``` + +**When generating XML:** if `attributes` has items, use attributes on the connection element; if `attributes` is empty but `childElements` has items, use nested child elements. Never hardcode structure — always use the metadata. + +--- + +## Step 12: Create Configuration Files + +Based on Step 11 metadata, create configuration files. + +**`src/main/resources/config.yaml`** — extract required attributes and child-element parameters; emit placeholders: + +```yaml +salesforce: + username: "user@example.com" + password: "password" + securityToken: "token" + +slack: + consumerKey: "your-consumer-key" + consumerSecret: "your-consumer-secret" +``` + +**Configuration XML** — structure driven entirely by metadata: + +```xml + + + + + + + + + + + + + + + + +``` + +**Generate ALL `childElements[]` entries from metadata** — the connection provider's `elementName`, the `attributes[]` array, and **every** `childElements[]` entry. For OAuth connectors, `oauth-callback-config` requires a `listenerConfig` attribute referencing an `http:listener-config`. **Missing required childElements = build failure.** + +--- + +## Step 13: Get Operation / Source Details + +For each operation the flow will call, retrieve metadata: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-versions/sfdc.json)" \ + --type operation \ + --name query \ + --output json +``` + +**Response shape** (same `attributes` + `childElements` pattern as `config-detail`): + +```json +{ + "name": "query", + "prefix": "salesforce", + "elementName": "query", + "attributes": [ + { "attributeName": "config-ref", "required": true }, + { "attributeName": "target" }, + { "attributeName": "targetValue", "defaultValue": "#[payload]", "expressionRequired": true } + ], + "childElements": [ + { "paramName": "salesforceQuery", "prefix": "salesforce", "elementName": "salesforce-query", "required": true } + ] +} +``` + +**For event-driven triggers** (the Step 5 selected trigger is a connector source, not built-in Scheduler or generic HTTP Listener), also retrieve source details: + +```bash +anypoint-cli-v4 dx mule describe-connector \ + --connector "$(bash scripts/build_gav.sh tmp/connector-versions/sfdc.json)" \ + --type source \ + --name replay-topic-listener \ + --output json +``` + +Same `attributes` + `childElements` structure. Always include ALL `required: true` attributes and child elements. + +**Generate operation XML (example):** + +```xml + + + SELECT Id, Name, Amount, StageName + FROM Opportunity + WHERE StageName = 'Closed Won' AND CloseDate = TODAY + + +``` + +--- + +## Step 14: Generate Complete Flow + +Generate the complete flow in `src/main/mule/.xml` using metadata from Steps 10, 12. Do NOT use hardcoded structures. + +```xml + + + + + + + + + + + + + + + + + + + + SELECT Id, Name, Amount FROM Opportunity WHERE StageName = 'Closed Won' + + + + + + + + + + +``` + +**`xsi:schemaLocation` construction rule:** + +Include in `xsi:schemaLocation` exactly one entry for each **module or connector namespace that has a matching `` in `pom.xml`** (core, ee/core, and each connector — `http`, `salesforce`, `db`, `anypoint-mq`, etc.). Each entry is the namespace URI followed by the URL of its XSD, separated by whitespace. + +**Namespaces that must NOT appear in `xsi:schemaLocation` (closed list):** + +| Namespace | `xmlns:*` declaration | Why it's excluded from `schemaLocation` | +|---|---|---| +| `doc` (`http://www.mulesoft.org/schema/mule/documentation`) | Required when any `doc:name` / `doc:description` is used (Step 15) | No XSD exists at that URL. `doc:*` attributes are accepted by `mule-core` via `anyAttribute`. Adding a schemaLocation entry makes `mvn clean package` fail at `process-classes` with `Can't resolve …/mule-documentation.xsd`. | +| `xsi` (`http://www.w3.org/2001/XMLSchema-instance`) | Required to use the `xsi:schemaLocation` attribute itself | `xsi` is a W3C standard namespace, not a Mule schema. | + +**Namespace ↔ dependency parity:** if a namespace is declared via `xmlns:X` but has no matching `` in `pom.xml`, the correct fix is to **add the dependency or remove the namespace** — not to add a schemaLocation entry that points at a non-existent XSD. Same failure mode as `mule-documentation.xsd` above, different root cause; applies to `mule-scripting`, `mule-objectstore`, `mule-validation`, `mule-http` when those namespaces are declared without their connector dep. + +**Generation rules:** + +- Use exact `elementName` from metadata for all tags +- Use exact `attributeName` from metadata for all attributes +- Include every `required: true` attribute and child element +- Use the correct namespace prefix from metadata +- Reference `config-ref` names from Step 12 +- **Generate child elements in the exact order of the `childElements[]` array** — XSD schemas enforce strict sequencing +- **Do not add wrapper elements that are not in metadata** (e.g., use `` not ``) +- Place reconnection at the config connection level, not operation level (unless metadata explicitly includes it there) +- Build `xsi:schemaLocation` from the module/connector `` list in `pom.xml`; never include `doc` or `xsi`. See the rule block above. + +--- + +## Step 15: Add `doc:name` and `doc:description` to Canvas-Visible Elements + +Every XML element that appears as a visible node on the flow canvas MUST have `doc:name` and `doc:description` attributes. `doc:description` is displayed as the label text on the canvas node (overriding `doc:name` when present), so keep it concise and meaningful. + +**Prerequisite — namespace declaration:** + +Any use of a `doc:*` attribute requires `xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"` on the `` root (see Step 14). If it is missing, every `doc:name` triggers `The prefix "doc" for attribute "doc:name" associated with an element type "..." is not bound`. The fix is to add the `xmlns:doc` attribute — and, per Step 14's `xsi:schemaLocation` construction rule, **not** to add `mule-documentation` to `xsi:schemaLocation`. + +Infer descriptions from the `description` field returned by `config-detail`, `operation-detail`, and `source-detail` metadata, the XML structure and element purpose, flow comments, and the overall integration context. + +**Rules:** + +- Human-readable sentences that explain the element's purpose in *this* integration, not generic documentation +- **Max 125 characters** — keeps labels readable on the canvas +- Active voice; be specific about what the element does +- Include relevant details: endpoints, object types, field names, scheduling intervals +- Add `doc:name` as a short label alongside `doc:description` + +**Add `doc:name` and `doc:description` to these canvas-visible element types:** + +| Element Type | Examples | +| --- | --- | +| **Flows/sub-flows** | ``, `` | +| **Sources/triggers** | ``, ``, `` | +| **Operations/processors** | ``, ``, ``, ``, ``, ``, ``, any connector operation | +| **Scopes/containers** | ``, ``, ``, ``, ``, ``, ``, `` | +| **Branches/routes** | ``, ``, `` | +| **Global configs** | ``, ``, `` | + +**Do NOT add `doc:description` to inner property elements** — these aren't rendered on the canvas: + +- ``, ``, `` +- ``, ``, `` +- ``, `` +- ``, `` +- Operation-specific child content elements (e.g., ``, ``) +- Transform inner elements (``, ``, ``, ``) + +**Example — after (with doc:name and doc:description):** + +```xml + + + + + + + SELECT Id, Name, Email FROM Contact WHERE LastModifiedDate > :lastSync + + + + + + + + + + + + + + #[payload] + + + + + + + + +``` + +--- + +## Step 16: Build and Verify + +```bash +cd +mvn clean package +``` + +Success: `target/-1.0.0-SNAPSHOT-mule-application.jar`. + +**Build-then-verify protocol (do NOT skip steps):** + +1. Emit `mvn clean package` as the **only** tool call in this response. Do not include a completion signal, a follow-up `ls`, or any other tool call alongside it. Stop and wait for the build output. +2. Read the output: + - If the last line block contains `BUILD SUCCESS`, proceed to Step 17 **in a new response**. + - If the last line block contains `BUILD FAILURE`, find the `[ERROR]` line beginning `Failed to execute goal ...`, diagnose the root cause, edit the offending file (revisiting the relevant earlier Step — e.g. Step 14 for XML structure, Step 15 for documentation attributes and namespaces), and return to step 1 of this protocol. + +**After any `` or `` on `pom.xml`, on flow XML, or on config XML, you MUST re-run `mvn clean package` before declaring completion.** Editing without re-verifying silently ships a broken build. + +--- + +## Step 17: Declare Completion + +**Pre-condition:** The immediately preceding response must be a build response (per Step 16) whose returned output contains `BUILD SUCCESS`. If this is not true, do NOT enter Step 17 — go back to Step 16. + +Completion discipline: + +- **The completion signal is the ONLY tool call in this response.** Do not run `mvn` here. Do not add follow-up shell commands. The build was already executed and verified in the previous response. +- **Do not declare completion after a `BUILD FAILURE`, even if you believe the subsequent edit fixes it.** Re-run `mvn clean package` in its own response (Step 16), observe `BUILD SUCCESS`, then declare completion in the next response. +- **Do not declare completion if the most recent build was never actually executed** (e.g., the command was shown but no result came back). Re-run it in its own response and wait. + +**Completion message content — keep it tight.** The user can see the files and the build log. The completion message is evidence that the build passed, not a marketing document. Include exactly these, and nothing else: + +1. The successful build artifact path: `target/-1.0.0-SNAPSHOT-mule-application.jar` +2. One sentence naming the integration (what it does, e.g. "Polls S3 every 5s and publishes new-object events to a JMS queue"). +3. The `config.yaml` keys the user still needs to fill in (credentials, bucket names, queue names) — as a short bullet list. This is the only information that is not already visible on disk. + +Do **not** include: lengthy "Features Implemented" sections, redacted JSON payload examples, "Next Steps" (the user will deploy when they're ready), or recap tables. + +--- + +## Best Practices + +**1. Dynamic connector versions.** See Step 3's "Version source-of-truth rule" for the full mandate. + +- ✅ Phase 1: `get_latest_connector.sh mule-salesforce-connector sfdc` → list → `pick_connector.sh sfdc ` → draft at `tmp/connector-choices/sfdc.json` +- ✅ Phase 2: `commit_connectors.sh` (first action of Step 8) → `build_deps.sh` for the `dx mule project create --dependencies` string, or `build_gav.sh tmp/connector-versions/.json` for a single GAV elsewhere +- ❌ Hardcoded literal: `com.mulesoft.connectors:mule-salesforce-connector:10.20.0` +- ❌ Pasted from `references/connector-catalog.md` (snapshot only — drifts) +- ❌ Search term alone as the GAV: `salesforce` + +**2. Metadata-driven XML generation.** Never manually write XML. Always use metadata from `operation-detail`, `config-detail`, `source-detail`: + +- `attributes` → XML attributes on the tag (use `attributeName` verbatim) +- `childElements` → nested XML elements (use `prefix:elementName` as the tag) +- Always include every `required: true` attribute and child element +- Optional entries may be omitted unless specifically needed +- `description` → understand what the parameter does +- `allowedValues` → constrain values +- `defaultValue` → skip if acceptable + +**3. System-specific connectors first, every time.** Always search Exchange for a dedicated connector before falling back to HTTP — and "before" means literally before, not "before I type my decision". The skill's discipline is that a Phase-1 draft in `tmp/connector-choices/` (or the post-commit pin in `tmp/connector-versions/`) is the only evidence that allows declaring "system X is covered"; the helper script having exited 1 is the only evidence that allows declaring "no dedicated connector, falling back to HTTP". + +**4. Validate metadata before generation.** Use `describe-connector` for features, `config-detail` / `operation-detail` / `source-detail` for exact specs. + +--- + +## Common Integration Patterns + +**#1 HTTP API → Query → Response:** http:listener → salesforce:query → ee:transform → response (Components: HTTP + Salesforce/Database) + +**#2 Scheduled Sync → Query → Transform → Notification:** scheduler → salesforce:query → ee:transform → slack:post-message (Components: Scheduler + Salesforce + Slack) + +**#3 Scheduled Sync → Query → Transform → Batch Insert:** scheduler → query → ee:transform → foreach → db:insert (Components: Scheduler + Source System + Database) + +**#4 Event listener → Transform → Downstream system:** `:` → ee:transform → target-connector operation (Components: Source System with native listener + Target System). This pattern shines when the source connector exposes a real event source in `sources[]` — use that instead of polling via Scheduler. + +--- + +## Troubleshooting + +**JAVA_HOME not set:** `export JAVA_HOME=$(/usr/libexec/java_home -v 11)` + +**anypoint-cli-v4 not found:** `npm install -g @mulesoft/anypoint-cli-v4` + +**DX plugin not found:** `npm install -g @mulesoft/anypoint-cli-dx-mule-plugin` + +**Connector not found:** check spelling · try `mule--connector` and `mule4--connector` · verify Mule 4 compatibility. + +**Wrong connector selected:** use specific search terms (`mule-http-connector`, not `http`). `scripts/get_latest_connector.sh` scores by token overlap and requires at least one token match — a bogus search will exit 1 rather than return a random result. + +**Runtime path required:** first use of `dx mule describe-connector` or related commands prompts for runtime location. The path is saved to `~/.mule-dx/config.json`. + +**Database driver missing:** if Step 6b didn't record `tmp/connector-choices/db-driver.json`, return to Step 6b to make the choice (with prompts where the provider is `generic`/`data-source`/`derby`). If the sidecar exists but `pom.xml` is missing the entries, return to Step 9 — it reads that file and applies every entry as a `` + `` pair. Do not invent a driver GAV at Step 9. + +**`The mule application does not contain the following shared libraries: [:]`:** the `` block is present but the matching `` block inside `mule-maven-plugin` is either missing or has a mismatched `groupId`/`artifactId`. Every driver dependency needs both; see Step 9. + +**Derby driver layout:** see `references/jdbc-drivers.md`. Derby 10.15+ split into multiple artifacts (`derby` + `derbyshared` + `derbytools` for embedded; `derbyclient` + `derbyshared` for network client), so the `` list has multiple entries, not one. + +--- + +## Quick Reference + +`` below is the absolute path you were given in the "skill is now active" message. Use it consistently — do not construct relative `../scripts/...` paths. + +```bash +# Step 1: prerequisites + runtime discovery +bash /scripts/validate_prerequisites.sh + +# Step 3: connector search — list, decide, draft (one loop per system; search +# EVERY named system including mid-market SaaS; don't pre-judge as "no connector") +bash /scripts/get_latest_connector.sh [] # prints ranked GAVs to stdout +# ... agent reads list, decides (or AskUserQuestion for real variant ambiguity), then: +bash /scripts/pick_connector.sh # drafts to tmp/connector-choices/ + +# Step 4: describe connectors (Phase 1 — wrapper saves JSON + echoes sources[] digest) +bash /scripts/describe_connector.sh # one per connector + +# Step 6: connection-provider detail (Phase 1 — also cached for Phase 2). +# Flag semantics: --name = connection provider, --config-name = config name. +GAV_A="$(bash /scripts/build_gav.sh tmp/connector-choices/a.json)" +anypoint-cli-v4 dx mule describe-connector --connector "$GAV_A" \ + --type connection-provider --name --config-name --output json \ + > tmp/connector-metadata/a-config.json + +# Step 8: promote drafts to pinned versions, then create the real project (Phase 2) +bash /scripts/commit_connectors.sh # tmp/connector-choices/ → tmp/connector-versions/ +MULE_VERSION=$(jq -r '.mule_version' /tmp/mule-dev-env.json) +anypoint-cli-v4 dx mule project create \ + --group-id com.example \ + --mule-version "$MULE_VERSION" \ + --dependencies "$(bash /scripts/build_deps.sh)" # reads every tmp/connector-versions/*.json pin + +# Step 10: OAuth → HTTP defensive check (only when Step 6 chose OAuth/JWT/auth-code +# or the trigger is HTTP Listener) +bash /scripts/maybe_add_http_connector.sh --project ./ "" "" + +# Step 13: operation / source details (Phase 2) +anypoint-cli-v4 dx mule describe-connector --connector "$GAV_A" --type operation --name --output json +anypoint-cli-v4 dx mule describe-connector --connector "$GAV_A" --type source --name --output json +``` + +--- diff --git a/skills/mule-development/build-mule-integration/references/connector-catalog.md b/skills/mule-development/build-mule-integration/references/connector-catalog.md new file mode 100644 index 0000000..460ed96 --- /dev/null +++ b/skills/mule-development/build-mule-integration/references/connector-catalog.md @@ -0,0 +1,427 @@ +# Common Mule Connectors Catalog + +Quick reference for frequently used Mule 4 connectors. + +> **Status: discovery aid only, not a build-time source of truth.** +> +> The asset IDs and use cases below are maintained to help identify which +> connector exists for which integration need. **The version numbers are a +> best-effort snapshot that can drift**, so never paste a version from this +> file into `dx project create --dependencies` or a `pom.xml` dependency +> block directly. +> +> At build time the version **must** come from `get_latest_connector` +> (defined in SKILL.md Step 2), which queries Anypoint Exchange live. If +> the helper returns a different version than what is listed here, the +> helper wins. See the enforcement rule in SKILL.md Step 2 and Step 3. +> +> Versions below last verified against live Exchange on **2026-04-24**. + +--- + +## Core Connectors + +### HTTP Connector +**Asset:** `org.mule.connectors:mule-http-connector` (snapshot: `1.11.1`) +**Use for:** +- HTTP listeners (REST API endpoints) +- HTTP requests (calling external APIs) +- Basic authentication, OAuth2 +- HTTPS/TLS + +**Common operations:** +- `http:listener` - Receive HTTP requests +- `http:request` - Make HTTP requests + +--- + +### Database Connector +**Asset:** `org.mule.connectors:mule-db-connector` (snapshot: `1.15.1`) +**Use for:** +- MySQL, PostgreSQL, Oracle, SQL Server connections +- SQL queries (SELECT, INSERT, UPDATE, DELETE) +- Stored procedures +- Batch operations + +**Database-specific notes:** +- **MySQL:** Use `` (built-in) +- **PostgreSQL:** Use `` + add JDBC driver dependency: + ```xml + + org.postgresql + postgresql + 42.5.1 + + ``` +- **Oracle:** Requires Oracle JDBC driver +- **SQL Server:** Requires Microsoft JDBC driver + +**Common operations:** +- `db:select` - Query data +- `db:insert` - Insert records +- `db:update` - Update records +- `db:delete` - Delete records + +--- + +## Salesforce Connectors + +### Salesforce Connector +**Asset:** `com.mulesoft.connectors:mule-salesforce-connector` (snapshot: `11.4.0`) +**Use for:** +- Standard SOAP/REST API access +- SOQL queries +- CRUD operations (Create, Read, Update, Delete) +- Bulk API +- Metadata API + +**Authentication types:** +- Basic (username + password + security token) +- OAuth 2.0 +- JWT Bearer Token + +**Common operations:** +- `salesforce:query` - SOQL queries +- `salesforce:create` - Create records +- `salesforce:update` - Update records +- `salesforce:delete` - Delete records +- `salesforce:upsert` - Insert or update + +**Example SOQL:** +```sql +SELECT Id, Name, Amount, CloseDate +FROM Opportunity +WHERE CloseDate >= THIS_YEAR +AND Amount > 0 +LIMIT 100 +``` + +--- + +### Salesforce Pub/Sub API Connector +**Asset:** `com.mulesoft.connectors:mule4-salesforce-pubsub-connector` (snapshot: `1.2.0`) +**Use for:** +- Event-driven integrations +- Platform Events +- Change Data Capture +- Real-time data streaming + +--- + +## NetSuite Connectors + +### NetSuite Connector +**Asset:** `com.mulesoft.connectors:mule-netsuite-connector` (snapshot: `11.11.2`) +**Use for:** +- ERP operations (Sales Orders, Customers, Items) +- SuiteTalk SOAP API +- RESTlet calls +- Saved searches + +**Authentication types:** +- Request-based (email + password) +- Token-based (OAuth 1.0a) + +**⚠️ Important Notes:** +- Syntax varies by connector version +- Use `skills/netsuite-integration-helper` for version-specific guidance +- Consider NetSuite RESTlet for simpler REST-based access + +**Common operations:** +- `netsuite:add` - Create records +- `netsuite:update` - Update records +- `netsuite:upsert` - Insert or update +- `netsuite:search` - Query records +- `netsuite:get` - Retrieve by ID + +--- + +### NetSuite Restlet Connector +**Asset:** `com.mulesoft.connectors:mule4-netsuite-restlet-connector` (snapshot: `1.0.9`) +**Use for:** +- REST-based NetSuite access +- Custom RESTlet scripts +- Simpler API interactions + +--- + +## File & FTP Connectors + +### File Connector +**Asset:** `org.mule.connectors:mule-file-connector` (snapshot: `1.5.5`) +**Use for:** +- Local file system operations +- Read/write/move/delete files +- File polling +- Directory monitoring + +--- + +### FTP Connector +**Asset:** `org.mule.connectors:mule-ftp-connector` (snapshot: `2.0.3`) +**Use for:** +- FTP/FTPS operations +- Remote file transfers +- Secure file uploads/downloads + +--- + +### SFTP Connector +**Asset:** `org.mule.connectors:mule-sftp-connector` (snapshot: `2.7.0`) +**Use for:** +- Secure FTP over SSH +- Key-based authentication +- Enterprise file transfers + +--- + +## Messaging Connectors + +### Anypoint MQ Connector +**Asset:** `com.mulesoft.connectors:anypoint-mq-connector` (snapshot: `4.0.14`) +**Use for:** +- MuleSoft-hosted message queues (preferred for MuleSoft-first integrations) +- Publish / subscribe between Mule applications +- External queueing without standing up JMS infrastructure + +**Common operations:** +- `anypoint-mq:publish` - Send a message to a queue or exchange +- `anypoint-mq:subscriber` (source) - Consume messages + +--- + +### JMS Connector +**Asset:** `org.mule.connectors:mule-jms-connector` (snapshot: `1.10.3`) +**Use for:** +- ActiveMQ, IBM MQ, Amazon SQS (via JMS) +- Message queues +- Publish/subscribe patterns +- Asynchronous messaging + +--- + +### Kafka Connector +**Asset:** `com.mulesoft.connectors:mule-kafka-connector` (snapshot: `4.13.0`) +**Use for:** +- Apache Kafka integration +- Event streaming +- Real-time data pipelines +- Microservices communication + +--- + +### AMQP Connector +**Asset:** `com.mulesoft.connectors:mule-amqp-connector` (snapshot: `1.9.0`) +**Use for:** +- RabbitMQ +- AMQP protocol messaging +- Queue-based integrations + +--- + +### IBM MQ Connector +**Asset:** `com.mulesoft.connectors:mule-ibm-mq-connector` (snapshot: `1.8.2`) +**Use for:** +- IBM MQ–specific integrations when JMS is not preferred +- Native IBM MQ features + +--- + +### VM Connector (in-Mule transport) +**Asset:** `org.mule.connectors:mule-vm-connector` (snapshot: `2.0.1`) +**Use for:** +- Queueing **between flows inside the same Mule app** (not external) +- Lightweight in-memory or persistent JVM-local queues + +**Do NOT use for external queueing or cross-app messaging** — use Anypoint MQ, JMS, Kafka, or AMQP instead. VM is a transport, not a broker. + +--- + +## Cloud Connectors + +### AWS Connectors + +**S3 Connector** +- **Asset:** `com.mulesoft.connectors:mule-amazon-s3-connector` (snapshot: `8.0.2`) +- **Use for:** S3 bucket operations, file storage + +**SQS Connector** +- **Asset:** `com.mulesoft.connectors:mule-amazon-sqs-connector` (snapshot: `5.12.5`) +- **Use for:** AWS message queues + +**DynamoDB Connector** +- **Asset:** `com.mulesoft.connectors:mule-amazon-dynamodb-connector` (snapshot: `1.6.3`) +- **Use for:** NoSQL database operations, DynamoDB Streams + +--- + +### Azure Connectors + +**Azure Service Bus** +- **Asset:** `com.mulesoft.connectors:mule-azure-service-bus-connector` (snapshot: `3.6.1`) +- **Use for:** Azure messaging (queues, topics, subscriptions) + +**Azure Data Lake Storage** +- **Asset:** `com.mulesoft.connectors:mule-azure-data-lake-storage-connector` (snapshot: `1.0.8`) +- **Use for:** Azure ADLS Gen2 blob/file storage + +**Azure Storage (Blob / Queue / Table)** +- **Asset:** `org.mule.modules:azure-storage-connector` (snapshot: `3.1.1`) +- **Use for:** Standard Azure Storage services — Blob Storage, Queue Storage, Table Storage. Note the non-canonical `org.mule.modules` groupId. + +--- + +### Google Connectors + +**Google Drive** +- **Asset:** `com.mulesoft.connectors:mule4-google-drive-connector` (snapshot: `1.1.4`) +- **Use for:** File storage and sharing + +**Google Sheets** +- **Asset:** `com.mulesoft.connectors:mule4-google-sheets-connector` (snapshot: `1.1.15`) +- **Use for:** Read/write Google Sheets rows and ranges, spreadsheet automation + +--- + +## API Integration Connectors + +### REST Connector +**Built-in via HTTP Connector** +Use `http:request` for RESTful API calls + +--- + +### SOAP Connector +**Asset:** `org.mule.connectors:mule-wsc-connector` (snapshot: `2.1.2`) +**Use for:** +- SOAP web services +- WSDL-based integrations +- Legacy systems + +--- + +### GraphQL (APIKit for GraphQL) +**Asset:** `org.mule.modules:mule-graphql-module` (snapshot: `1.2.0`) +**Use for:** +- Exposing a GraphQL endpoint from a Mule app via APIKit for GraphQL +- Schema-first GraphQL runtime extension + +> For **consuming** an external GraphQL API, there is no dedicated client connector — use the HTTP Connector with POST requests. + +--- + +## Other Systems + +### ServiceNow Connector +**Asset:** `com.mulesoft.connectors:mule-servicenow-connector` (snapshot: `6.18.2`) +**Use for:** ITSM operations, incident management + +--- + +### Workday Connector +**Asset:** `com.mulesoft.connectors:mule-workday-connector` (snapshot: `16.7.0`) +**Use for:** HR/Finance integrations + +--- + +### SAP Connector +**Asset:** `com.mulesoft.connectors:mule-sap-connector` (snapshot: `5.9.13`) +**Use for:** SAP ERP integrations + +--- + +### MongoDB Connector +**Asset:** `com.mulesoft.connectors:mule-mongodb-connector` (snapshot: `6.3.12`) +**Use for:** NoSQL database operations + +--- + +### Slack Connector +**Asset:** `org.mule.connectors:mule-slack-connector` (snapshot: `4.3.2`) +**Use for:** Slack messaging, notifications + +--- + +## Connector Selection Guide + +### For HTTP APIs +1. **Known system (Salesforce, NetSuite, etc.):** Use specific connector +2. **Generic REST API:** Use HTTP Connector +3. **SOAP API:** Use SOAP (WSC) Connector +4. **GraphQL API:** Use HTTP Connector with POST requests + +### For Databases +1. **MySQL:** Database Connector (built-in support) +2. **PostgreSQL:** Database Connector + JDBC driver +3. **Oracle:** Database Connector + JDBC driver +4. **NoSQL (MongoDB, DynamoDB):** Specific NoSQL connectors + +### For File Operations +1. **Local files:** File Connector +2. **FTP/FTPS:** FTP Connector +3. **SFTP:** SFTP Connector +4. **Cloud storage (S3, Azure):** Cloud-specific connectors + +### For Messaging (external / cross-app) +1. **MuleSoft-hosted queues:** Anypoint MQ Connector +2. **JMS-compatible (ActiveMQ, IBM MQ via JMS):** JMS Connector +3. **Native IBM MQ:** IBM MQ Connector +4. **Kafka:** Kafka Connector +5. **RabbitMQ:** AMQP Connector +6. **AWS SQS:** Amazon SQS Connector +7. **Azure Service Bus:** Azure Service Bus Connector + +**Do not use VM for external queueing.** VM is the in-Mule transport (same-JVM) — pick one of the options above when the prompt says "queue", "publish", "messaging", "durable", or names an external broker. + +--- + +## Finding Connectors at Build Time + +Use the `get_latest_connector` helper defined in SKILL.md Step 2. It calls +Anypoint Exchange live and returns the authoritative groupId, assetId, and +version for the supplied search term: + +```bash +get_latest_connector "mule-amazon-s3-connector" +# -> com.mulesoft.connectors:mule-amazon-s3-connector:8.0.2 (as of query time) +``` + +**Always use the helper's output for the version number** when writing +`dx project create --dependencies` or pom.xml dependency blocks. The +snapshot versions in this file are discovery hints, not authoritative. + +### Common searches: +- `salesforce` - Salesforce connectors +- `database` - Database connector +- `http` - HTTP connector +- `file` - File operations +- `sap` - SAP connectors +- `mongodb` - MongoDB connector +- `anypoint-mq` - Anypoint MQ +- `kafka` - Kafka +- `s3` or `amazon-s3` - Amazon S3 + +### Filter criteria: +- **Runtime:** Look for `4.x` (Mule 4) +- **GroupId:** Prefer `com.mulesoft.connectors` or `org.mule.connectors` +- **Version:** Latest stable — always take the version the helper returns + +--- + +## References + +- **Anypoint Exchange:** https://www.mulesoft.com/exchange/ +- **Connector Documentation:** https://docs.mulesoft.com/connectors/ +- **Mule 4 Migration:** https://docs.mulesoft.com/mule-runtime/latest/migration-connectors + +--- + +## Tips + +1. **Always include HTTP Connector** for manual trigger endpoints +2. **Include Scheduler** (built-in) for periodic jobs +3. **Check database-specific requirements** (JDBC drivers) +4. **Verify connector compatibility** with the target Mule runtime version (Mule 4.4.x / 4.5.x / 4.8.x differ in required connector ranges) +5. **Always take versions from `get_latest_connector`** — do not paste versions from this catalog or from training-time memory +6. **Read connector documentation** for authentication setup +7. **Test connectors individually** before complex integrations diff --git a/skills/mule-development/build-mule-integration/references/jdbc-drivers.md b/skills/mule-development/build-mule-integration/references/jdbc-drivers.md new file mode 100644 index 0000000..0b10d39 --- /dev/null +++ b/skills/mule-development/build-mule-integration/references/jdbc-drivers.md @@ -0,0 +1,202 @@ +# JDBC Drivers — extended reference + +## When to read this file + +Read this file **only when** Step 5b of SKILL.md lands on one of these branches: + +- Provider = `generic` (any database wired through `` — PostgreSQL, H2, Snowflake, SAP HANA, Vertica, etc.) +- Provider = `data-source` (driver is supplied by the container, or you need to override with an explicit ``) +- Provider = `derby` (embedded vs network client, multi-artifact) + +For `my-sql`, `oracle`, and `mssql`, the four-row canonical table in SKILL.md Step 8 is authoritative — **do not load this file**; it adds noise without adding information. + +## Table of contents + +- [Derby — multi-artifact layout](#derby--multi-artifact-layout) + - [Embedded mode (Java 17+)](#embedded-mode-java-17) + - [Network client mode (Java 17+)](#network-client-mode-java-17) + - [Legacy Derby 10.14.x for Java 8](#legacy-derby-1014x-for-java-8) + - [Driver classes and URL shapes](#driver-classes-and-url-shapes) +- [Generic-connection drivers](#generic-connection-drivers) + - [PostgreSQL](#postgresql) + - [H2](#h2) + - [Snowflake](#snowflake) + - [SAP HANA](#sap-hana) + - [Vertica](#vertica) +- [How to declare multiple sharedLibrary entries](#how-to-declare-multiple-sharedlibrary-entries) +- [How this content feeds Step 5b](#how-this-content-feeds-step-5b) + +--- + +## Derby — multi-artifact layout + +Apache Derby 10.15 (released 2020) split the single `derby.jar` into multiple artifacts. The split was driven by Java 9+ modularization and means a modern Derby setup declares **two or three `` entries**, not one. + +Mule 4.5/4.6/4.11 runs on **Java 17**, so the canonical version for new work is **Derby 10.16.1.1** — the 10.17 line bumps the minimum to Java 21 and is not suitable for Mule 4 today. + +### Embedded mode (Java 17+) + +Use when the Mule app embeds the Derby engine in-process and stores the database as local files. The URL shape is `jdbc:derby:/absolute/path;create=true`. + +Declare **three** `` blocks AND three matching `` entries: + +| groupId | artifactId | Version | Purpose | +| --- | --- | --- | --- | +| `org.apache.derby` | `derby` | `10.16.1.1` | Embedded engine | +| `org.apache.derby` | `derbyshared` | `10.16.1.1` | Shared runtime required by every Derby artifact since 10.15 | +| `org.apache.derby` | `derbytools` | `10.16.1.1` | System procedures + `ij` tooling the engine loads reflectively | + +Omitting `derbyshared` produces `NoClassDefFoundError: org/apache/derby/shared/common/reference/SQLState` at first query. Omitting `derbytools` produces an opaque startup failure because the engine loads tool classes reflectively during boot. + +### Network client mode (Java 17+) + +Use when Mule connects to a Derby Network Server running in a separate process. The URL shape is `jdbc:derby://host:1527/dbname`. Mule is the client; the server is deployed and managed outside the Mule app. + +Declare **two** `` + `` pairs: + +| groupId | artifactId | Version | Purpose | +| --- | --- | --- | --- | +| `org.apache.derby` | `derbyclient` | `10.16.1.1` | Network client driver | +| `org.apache.derby` | `derbyshared` | `10.16.1.1` | Shared runtime | + +No `derby` or `derbytools` — the engine lives on the server side. + +### Legacy Derby 10.14.x for Java 8 + +If the deployment target is a legacy Mule runtime on Java 8, the multi-artifact split does not apply. Use Derby **10.14.2.0** (single `derby.jar` for embedded, single `derbyclient.jar` for network): + +| Mode | groupId | artifactId | Version | +| --- | --- | --- | --- | +| Embedded | `org.apache.derby` | `derby` | `10.14.2.0` | +| Network client | `org.apache.derby` | `derbyclient` | `10.14.2.0` | + +This branch is almost never correct on Mule 4.5+ (which ships Java 17); use it only when you have an explicit Java 8 constraint. + +### Driver classes and URL shapes + +| Mode | Driver class | URL shape | +| --- | --- | --- | +| Embedded | `org.apache.derby.jdbc.EmbeddedDriver` | `jdbc:derby:/path/to/db;create=true` | +| Network client | `org.apache.derby.jdbc.ClientDriver` | `jdbc:derby://host:1527/dbname` | + +The Step-5 XML shape for both modes is `` with `driverClassName` set explicitly — `mule-db-connector` does not ship a `` element in the 1.15 line. + +```xml + + + +``` + +--- + +## Generic-connection drivers + +When Step 5 picks `generic`, the XML shape is always `` — the actual database is identified by the URL and driver class, not by a Mule-level provider. Step 5b's prompt surfaces the databases below as canonical options. + +### PostgreSQL + +This is the most common `generic` target. Versions verified against Maven Central. + +| groupId | artifactId | Version | Driver class | +| --- | --- | --- | --- | +| `org.postgresql` | `postgresql` | `42.7.11` | `org.postgresql.Driver` | + +URL shape: `jdbc:postgresql://host:5432/dbname`. Single-artifact declaration. + +### H2 + +Common for embedded/testing scenarios. + +| groupId | artifactId | Version | Driver class | +| --- | --- | --- | --- | +| `com.h2database` | `h2` | `2.3.232` | `org.h2.Driver` | + +URL shape: `jdbc:h2:file:/path/to/db` (file), `jdbc:h2:mem:name` (in-memory), `jdbc:h2:tcp://host:port/db` (server). + +### Snowflake + +| groupId | artifactId | Version | Driver class | +| --- | --- | --- | --- | +| `net.snowflake` | `snowflake-jdbc` | `3.20.0` | `net.snowflake.client.jdbc.SnowflakeDriver` | + +URL shape: `jdbc:snowflake://.snowflakecomputing.com/?warehouse=...&db=...`. + +### SAP HANA + +| groupId | artifactId | Version | Driver class | +| --- | --- | --- | --- | +| `com.sap.cloud.db.jdbc` | `ngdbc` | `2.22.8` | `com.sap.db.jdbc.Driver` | + +URL shape: `jdbc:sap://host:port/?databaseName=...`. + +### Vertica + +| groupId | artifactId | Version | Driver class | +| --- | --- | --- | --- | +| `com.vertica.jdbc` | `vertica-jdbc` | `24.3.0-0` | `com.vertica.jdbc.Driver` | + +URL shape: `jdbc:vertica://host:5433/dbname`. + +--- + +## How to declare multiple sharedLibrary entries + +When the sidecar `tmp/connector-choices/db-driver.json` has multiple entries (Derby embedded, for example), Step 8 must emit one `` block AND one `` block **per entry**. The groupId and artifactId on the `` side must match the `` side character-for-character. + +```xml + + + org.apache.derby + derby + 10.16.1.1 + + + org.apache.derby + derbyshared + 10.16.1.1 + + + org.apache.derby + derbytools + 10.16.1.1 + + + + + + org.apache.derby + derby + + + org.apache.derby + derbyshared + + + org.apache.derby + derbytools + + +``` + +A single missing entry on either side surfaces at build time as `The mule application does not contain the following shared libraries: [:]` or at runtime as `NoClassDefFoundError`. + +--- + +## How this content feeds Step 5b + +When Step 5b branches into `generic`, `data-source`, or `derby`, it prompts the user with the canonical options from this file. The outcome is one or more `{groupId, artifactId, version}` tuples written to `tmp/connector-choices/db-driver.json`, plus the driver class. The sidecar schema is: + +```json +{ + "dependencies": [ + { "groupId": "org.apache.derby", "artifactId": "derby", "version": "10.16.1.1" }, + { "groupId": "org.apache.derby", "artifactId": "derbyshared", "version": "10.16.1.1" }, + { "groupId": "org.apache.derby", "artifactId": "derbytools", "version": "10.16.1.1" } + ], + "driverClass": "org.apache.derby.jdbc.EmbeddedDriver" +} +``` + +Step 6's design summary renders every entry in that array under "Build-time additions". Step 8 applies every entry mechanically to `pom.xml`. Neither step prompts — the design decision is fully resolved here. diff --git a/skills/mule-development/build-mule-integration/scripts/build_deps.sh b/skills/mule-development/build-mule-integration/scripts/build_deps.sh new file mode 100755 index 0000000..6d92f7d --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/build_deps.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 8 helper — read every connector pin in tmp/connector-versions/ and +# emit a comma-joined GAV string on stdout, ready to pass as +# `--dependencies "$(build_deps.sh)"` on `dx project create`. +# +# Why this exists: inlining `$(build_gav.sh ...)` once per connector inside +# `--dependencies` produces a command that grows to 1000+ characters when +# absolute script paths are used (per SKILL.md's invocation rule). Terminal +# harnesses in Cline/Dev Agent lose the completion marker on very long +# commands and stall the turn until a 2-minute timeout fires. Pre-joining +# here keeps the `dx project create` line ~250 chars regardless of how many +# connectors are in scope. +# +# Files read: +# tmp/connector-versions/*.json — connector pins produced by +# commit_connectors.sh. Each pin is the object shape +# {groupId, assetId, version, ...} written by get_latest_connector.sh. +# +# Files skipped (silently): +# tmp/connector-versions/db-driver.json — the Step 6b JDBC driver sidecar +# has a different schema ({dependencies: [...], driverClass}) and belongs +# to Step 9, not --dependencies. Any other future sidecar that lacks the +# three required connector keys is skipped the same way. +# +# Usage: +# bash /scripts/build_deps.sh +# bash /scripts/build_deps.sh tmp/connector-versions +# +# Exit codes: +# 0 emitted at least one GAV +# 1 no usable pins found (either the directory is missing, empty, or +# every file was filtered out) +set -u + +DIR="${1:-tmp/connector-versions}" + +if [ ! -d "$DIR" ]; then + echo "❌ $DIR does not exist. Did you run commit_connectors.sh?" >&2 + exit 1 +fi + +shopt -s nullglob +FILES=("$DIR"/*.json) +shopt -u nullglob + +if [ ${#FILES[@]} -eq 0 ]; then + echo "❌ $DIR is empty. Did you run commit_connectors.sh?" >&2 + exit 1 +fi + +GAVS=() +for f in "${FILES[@]}"; do + # Only include files with the flat connector-pin shape. jq -e returns + # non-zero if any of the fields is missing/null, which is exactly the + # filter we want for skipping driver sidecars and future non-pin files. + gav=$(jq -er ' + select(has("groupId") and has("assetId") and has("version")) + | "\(.groupId):\(.assetId):\(.version)" + ' "$f" 2>/dev/null) || continue + [ -n "$gav" ] && GAVS+=("$gav") +done + +if [ ${#GAVS[@]} -eq 0 ]; then + echo "❌ No connector pins in $DIR (files present but none had groupId/assetId/version)." >&2 + exit 1 +fi + +# Comma-join without a trailing comma. printf + sed is portable across the +# bash versions shipped on macOS (3.2) and Linux (5+). +IFS=,; echo "${GAVS[*]}" diff --git a/skills/mule-development/build-mule-integration/scripts/build_gav.sh b/skills/mule-development/build-mule-integration/scripts/build_gav.sh new file mode 100755 index 0000000..a9828fa --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/build_gav.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Read a connector JSON file produced by get_latest_connector.sh and emit +# its GAV (groupId:assetId:version) on stdout. +# +# This exists as a separate script so SKILL.md can show the agent a +# one-liner at the command site — e.g. +# +# --dependencies "$(scripts/build_gav.sh tmp/connector-versions/sfdc.json),$(scripts/build_gav.sh tmp/connector-versions/slack.json)" +# +# which turns GAV construction from a mental exercise (prone to version +# hallucination) into a mechanical `jq` extraction from a file on disk. +set -u + +FILE="${1:-}" +if [ -z "$FILE" ] || [ ! -f "$FILE" ]; then + echo "Usage: $0 " >&2 + echo " e.g. $0 tmp/connector-versions/sfdc.json" >&2 + exit 1 +fi + +jq -er '"\(.groupId):\(.assetId):\(.version)"' "$FILE" || { + echo "❌ $FILE is not a valid connector JSON (expected {groupId, assetId, version})" >&2 + exit 1 +} diff --git a/skills/mule-development/build-mule-integration/scripts/commit_connectors.sh b/skills/mule-development/build-mule-integration/scripts/commit_connectors.sh new file mode 100755 index 0000000..07b7637 --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/commit_connectors.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 8 helper (Phase 2 bootstrap) — promote every connector draft in +# tmp/connector-choices/ to the pinned tmp/connector-versions/ directory +# that Phase 2 scripts read from. +# +# Runs exactly once per session, as the first action after the user +# approves the Technical Design Summary in Step 7. Missing drafts here +# mean the agent skipped Step 3 for some system — Phase 2 will fail fast +# on build_gav.sh when it can't find the pin file, which is the intended +# signal that the design is incomplete. +# +# Usage: +# scripts/commit_connectors.sh +# +# Exit code: +# 0 one or more drafts promoted +# 1 no drafts found (tmp/connector-choices/ missing or empty) +set -u + +CHOICES_DIR="${CONNECTOR_CHOICES_DIR:-tmp/connector-choices}" +VERSIONS_DIR="${CONNECTOR_VERSIONS_DIR:-tmp/connector-versions}" + +if [ ! -d "$CHOICES_DIR" ]; then + echo "No drafts directory at $CHOICES_DIR." >&2 + echo "Run pick_connector.sh for each connector in Step 3 before committing." >&2 + exit 1 +fi + +shopt -s nullglob +DRAFTS=("$CHOICES_DIR"/*.json) +shopt -u nullglob + +if [ ${#DRAFTS[@]} -eq 0 ]; then + echo "No drafts in $CHOICES_DIR." >&2 + echo "Run pick_connector.sh for each connector in Step 3 before committing." >&2 + exit 1 +fi + +mkdir -p "$VERSIONS_DIR" + +NAMES=() +for draft in "${DRAFTS[@]}"; do + base=$(basename "$draft") + cp "$draft" "$VERSIONS_DIR/$base" + NAMES+=("${base%.json}") +done + +# Sort names for a stable summary line; the order of the glob is unspecified. +IFS=$'\n' SORTED=($(printf '%s\n' "${NAMES[@]}" | sort)) +unset IFS + +echo "Committed ${#DRAFTS[@]} connector pin(s): ${SORTED[*]}" +echo "From: $CHOICES_DIR" +echo "To: $VERSIONS_DIR" diff --git a/skills/mule-development/build-mule-integration/scripts/describe_connector.sh b/skills/mule-development/build-mule-integration/scripts/describe_connector.sh new file mode 100755 index 0000000..50e3a03 --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/describe_connector.sh @@ -0,0 +1,98 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 4 helper — run `anypoint-cli-v4 dx mule describe-connector` for the +# drafted GAV and persist the full response to +# tmp/connector-metadata/.json. Echo a human-readable digest +# (namespace, sources[], operations, configs) to stdout so the agent +# sees the key fields in tool output and cannot plausibly ignore them +# when choosing a trigger. +# +# Usage: +# scripts/describe_connector.sh +# +# Where matches the filename used in Step 3 — e.g. 'sfdc'. +# The GAV is read from the draft tmp/connector-choices/.json +# (written by pick_connector.sh). Drafts are promoted to the pinned +# tmp/connector-versions/.json by commit_connectors.sh after the +# Technical Design Summary is approved; describe_connector.sh falls back +# to that location so Phase-2 re-describes still work. +# +# Pre-conditions: +# - tmp/connector-choices/.json exists (from Step 3 pick_connector.sh) +# OR tmp/connector-versions/.json exists (post-commit / Phase 2). +# +# Rationale: Step 4's output is what Step 5 (trigger selection) +# actually branches on. If the agent writes describe output to disk +# but never reads it back, it falls back to prompt-text intuition +# about triggers — an observed failure mode in earlier iterations. +# Echoing sources[] and configs[] to stdout puts those fields in the +# tool-output stream where the agent re-reads them naturally. +# +# Exit code: +# 0 describe succeeded; JSON saved; digest echoed +# 1 missing arg / missing GAV file / CLI failure +set -u + +NICKNAME="${1:-}" +if [ -z "$NICKNAME" ]; then + echo "Usage: $0 " >&2 + echo " e.g. $0 sfdc" >&2 + exit 1 +fi + +CHOICES_DIR="${CONNECTOR_CHOICES_DIR:-tmp/connector-choices}" +VERSIONS_DIR="${CONNECTOR_VERSIONS_DIR:-tmp/connector-versions}" +METADATA_DIR="${CONNECTOR_METADATA_DIR:-tmp/connector-metadata}" + +METADATA_JSON="$METADATA_DIR/${NICKNAME}.json" + +# Drafts (Step 3 pick_connector.sh) take precedence over commits +# (commit_connectors.sh, post-TDD). This lets the agent re-pick through +# Steps 3–5 while keeping Phase-2 re-describes working after commit. +if [ -f "$CHOICES_DIR/${NICKNAME}.json" ]; then + GAV_JSON="$CHOICES_DIR/${NICKNAME}.json" +elif [ -f "$VERSIONS_DIR/${NICKNAME}.json" ]; then + GAV_JSON="$VERSIONS_DIR/${NICKNAME}.json" +else + echo "❌ No GAV file for '$NICKNAME' in $CHOICES_DIR/ or $VERSIONS_DIR/" >&2 + echo " Run get_latest_connector.sh $NICKNAME, then pick_connector.sh $NICKNAME " >&2 + exit 1 +fi + +GAV="$(jq -r '"\(.groupId):\(.assetId):\(.version)"' "$GAV_JSON")" + +mkdir -p "$METADATA_DIR" + +# Run describe and save the full response. On failure the CLI +# prints to stderr; forward its exit status so the agent sees the +# real error rather than a truncated JSON. +if ! anypoint-cli-v4 dx mule describe-connector \ + --connector "$GAV" \ + --output json > "$METADATA_JSON" 2>/tmp/mule-dev-describe-err.$$; then + cat /tmp/mule-dev-describe-err.$$ >&2 + rm -f /tmp/mule-dev-describe-err.$$ + echo "❌ describe-connector failed for $GAV" >&2 + exit 1 +fi +rm -f /tmp/mule-dev-describe-err.$$ + +# Echo the key fields so the agent has them in tool output without +# needing a separate jq/cat round-trip. This is the content Step 5 +# branches on — particularly sources[], which is the list of real +# native triggers the connector supports. +echo "✅ $NICKNAME → $METADATA_JSON" +echo " GAV: $GAV" +echo "" +echo "--- describe digest ---" +# Operations can run into the hundreds on OpenAPI-derived connectors; +# show a count and a short head-sample rather than spraying them all. +# sources[] and configs[] are always emitted in full — those are what +# Step 5 (trigger selection) and Step 6 (provider selection) need. +jq -r '{ + namespace_prefix: .namespace.prefix, + sources: .sources, + configs: [.configs[] | {name: .name, providers: [.connectionProviders[]?]}], + operations_count: (.operations | length), + operations_sample: (.operations | if length > 20 then .[0:20] + ["... (see tmp/connector-metadata/'"$NICKNAME"'.json for full list)"] else . end) +}' "$METADATA_JSON" diff --git a/skills/mule-development/build-mule-integration/scripts/get_latest_connector.sh b/skills/mule-development/build-mule-integration/scripts/get_latest_connector.sh new file mode 100755 index 0000000..7279bb3 --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/get_latest_connector.sh @@ -0,0 +1,138 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 3 helper — search Exchange for MuleSoft connector candidates and +# print the ranked list to stdout. No pin file is written; no "winner" +# is named. The agent reads the list and decides: a single row is obvious, +# multiple rows of genuinely different system families are still usually +# obvious, but variant families (slack vs mule4-slack, ftp vs ftps, mq vs +# jms, db drivers) need the user's intent — the agent must escalate with +# AskUserQuestion instead of guessing. +# +# Usage: +# scripts/get_latest_connector.sh [] +# +# Stdout (one line per candidate, ranked best-guess-first, no score, no emoji): +# :: +# ... +# +# Exit code: +# 0 ≥1 candidate found — ranked list printed on stdout +# 1 no candidates / CLI error — error surfaced on stderr +# +# Why no auto-pin: v7 wrote the top-1 GAV to disk before the agent had +# a chance to compare candidates. In ambiguous variant families the agent +# accepted the pin silently 86% of the time (based on 535 lookups across +# the pt1/pt2/pt3 eval runs). Removing the winner signal — pin file, ✅ +# banner, "score" number — forces the agent to actually read the list. +# When the list has >1 row the shape of the output is itself the ambiguity +# signal. The pick is committed later via pick_connector.sh, and all picks +# are promoted to tmp/connector-versions/ by commit_connectors.sh after +# the user approves the Technical Design Summary. +# +# Selection rules (unchanged from v7; used only for internal ranking): +# - Only Mule 4 SDK extensions (type=="extension"). Mule 3 type=="connector" +# assets, templates, examples, and rest-apis are excluded — they can't be +# used as dependencies in a Mule 4 `dx project create` project. +# - No groupId allowlist. Any groupId whose asset is type=="extension" is +# admissible. Ranking keeps first-party connectors on top: +# Tier 0: com.mulesoft.connectors (premium) +# Tier 1: org.mule.connectors (community) +# Tier 2: anything else (org.mule.examples, com.mule.modules, ...) +# - Candidates scored by token overlap with the search term: +# _score = 2 * exact_hits + 1 * substring_hits − unmatched_asset_tokens +# Score is used for ordering only and is never emitted. +# - Two pages fetched in parallel (offset 0 and offset 200) to surface +# candidates that would otherwise fall off a single 200-row page. +set -euo pipefail + +SEARCH_TERM="${1:-}" +NICKNAME="${2:-$SEARCH_TERM}" + +if [ -z "$SEARCH_TERM" ]; then + echo "Usage: $0 []" >&2 + echo " e.g. $0 mule-salesforce-connector sfdc" >&2 + exit 1 +fi + +# `exchange asset list` interprets --environment as a business-unit name +# (Sandbox, Production, ...). In some automation contexts ANYPOINT_ENV is +# set to a deployment short-name (e.g., "test1") which the CLI does not +# recognize. Exchange search is org-scoped, so unset it for this call only. +TMPDIR_="$(mktemp -d)" +trap 'rm -rf "$TMPDIR_"' EXIT + +# Fetch two pages in parallel. Page A (offset 0) is authoritative — if it +# fails we bail out. Page B (offset 200) is additive — if it fails, log a +# warning and proceed with Page A alone. +(env -u ANYPOINT_ENV anypoint-cli-v4 exchange asset list \ + "$SEARCH_TERM" --limit 200 --offset 0 --output json >"$TMPDIR_/page-a.json" 2>&1) & +(env -u ANYPOINT_ENV anypoint-cli-v4 exchange asset list \ + "$SEARCH_TERM" --limit 200 --offset 200 --output json >"$TMPDIR_/page-b.json" 2>&1) & +wait + +if ! jq -e 'type == "array"' "$TMPDIR_/page-a.json" >/dev/null 2>&1; then + echo "exchange asset list failed for '$SEARCH_TERM' (page 1):" >&2 + cat "$TMPDIR_/page-a.json" >&2 + exit 1 +fi + +if ! jq -e 'type == "array"' "$TMPDIR_/page-b.json" >/dev/null 2>&1; then + echo "exchange asset list page 2 failed for '$SEARCH_TERM' — proceeding with page 1 only." >&2 + echo "[]" >"$TMPDIR_/page-b.json" +fi + +RANKED=$(jq -s --arg search "$SEARCH_TERM" ' + (.[0] + .[1]) as $all | + + ($search | ascii_downcase | split("-") | map(select(. != "" and . != "mule" and . != "connector"))) as $search_tokens | + + [$all[] | select(.type == "extension")] | + + group_by([.groupId, .assetId]) | + map({ + groupId: .[0].groupId, + assetId: .[0].assetId, + version: (sort_by([.version | split(".") | map(tonumber? // 0)]) | reverse | .[0].version), + asset_tokens: (.[0].assetId | ascii_downcase | split("-") | map(select(. != "" and . != "mule" and . != "connector"))), + }) | + + map(. as $c | + ($c.asset_tokens | map( + . as $t | + if ($search_tokens | index($t)) then {kind: "exact", token: $t} + elif (($t | length) >= 2) and ( + any($search_tokens[]; . as $s | ($s | length) >= 2 and (index($t) != null or ($t | index($s)) != null)) + ) then {kind: "substring", token: $t} + else {kind: "none", token: $t} + end + )) as $cls | + ($cls | map(select(.kind == "exact")) | length) as $exact | + ($cls | map(select(.kind == "substring")) | length) as $substr | + ($cls | map(select(.kind == "none")) | length) as $unmatched | + $c + { + _score: (2 * $exact + $substr - $unmatched), + _group_pref: ( + if .groupId == "com.mulesoft.connectors" then 0 + elif .groupId == "org.mule.connectors" then 1 + else 2 + end + ), + } + ) | + + sort_by([-._score, ._group_pref, (.assetId | length)]) +' "$TMPDIR_/page-a.json" "$TMPDIR_/page-b.json") + +COUNT=$(printf '%s' "$RANKED" | jq 'length') +if [ "$COUNT" = "0" ]; then + echo "No Mule 4 extension matches '$SEARCH_TERM' on Exchange." >&2 + echo "Searched all groupIds; no asset of type=extension was returned." >&2 + exit 1 +fi + +# Ranked list to stdout, one GAV per line. No score, no emoji, no winner cue. +# A single row → the agent acknowledges it and picks. Multiple rows → the +# agent must reason about which matches the user's intent, and escalate +# to AskUserQuestion if the answer isn't obvious from the names alone. +printf '%s' "$RANKED" | jq -r '.[] | "\(.groupId):\(.assetId):\(.version)"' diff --git a/skills/mule-development/build-mule-integration/scripts/maybe_add_http_connector.sh b/skills/mule-development/build-mule-integration/scripts/maybe_add_http_connector.sh new file mode 100755 index 0000000..45a72c5 --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/maybe_add_http_connector.sh @@ -0,0 +1,162 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 6.5 helper — if any of the selected connection providers is an OAuth +# flow, ensure the HTTP connector is present in the project's pom.xml. +# OAuth callbacks need an http:listener, which requires the HTTP connector +# dependency. +# +# In v8 get_latest_connector.sh prints a ranked GAV list to stdout and +# writes nothing to disk. HTTP is an unambiguous search (mule-http-connector +# dominates any results), so this helper safely takes the top row without +# prompting — it is not a variant-selection choice. +# +# Usage: +# scripts/maybe_add_http_connector.sh --project [...] +# +# The --project flag anchors all file work to the project directory: +# - `pom.xml` is edited inside that directory +# - `tmp/connector-versions/http.json` is written inside that directory +# +# Anchoring to --project removes the cwd-dependent "../scripts/..." pattern +# that has caused "No such file or directory" turns in real runs: the agent +# can invoke this script from anywhere (repo root, workspace root, anywhere) +# as long as --project points at the Mule project. The HTTP draft lands in +# /tmp/connector-choices/http.json to keep it consistent with +# Step 3's layout, though Phase-2 pom edits use the GAV directly here. +# +# Each provider argument is a connection-provider name (as chosen in Step 6). +# The script is idempotent: if no provider looks like OAuth, or if the HTTP +# connector is already present in pom.xml, it exits 0 without changes. +# +# Exit code: +# 0 no OAuth, or HTTP already present, or HTTP inserted successfully +# 1 OAuth detected but HTTP could not be resolved or pom.xml edit failed +# 2 bad invocation (missing --project or no providers) +set -u + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PROJECT_DIR="" +PROVIDERS=() + +while [ "$#" -gt 0 ]; do + case "$1" in + --project) + if [ -z "${2:-}" ]; then + echo "❌ --project requires a path argument" >&2 + exit 2 + fi + PROJECT_DIR="$2" + shift 2 + ;; + --project=*) + PROJECT_DIR="${1#--project=}" + shift + ;; + --help|-h) + echo "Usage: $0 --project [...]" + exit 0 + ;; + *) + PROVIDERS+=("$1") + shift + ;; + esac +done + +if [ -z "$PROJECT_DIR" ]; then + echo "❌ --project is required" >&2 + echo " Usage: $0 --project [...]" >&2 + exit 2 +fi + +if [ ! -d "$PROJECT_DIR" ]; then + echo "❌ Project directory not found: $PROJECT_DIR" >&2 + exit 1 +fi + +if [ "${#PROVIDERS[@]}" -eq 0 ]; then + echo "✅ No connection providers passed — nothing to do." + exit 0 +fi + +OAUTH_PROVIDER="" +for provider in "${PROVIDERS[@]}"; do + if printf '%s' "$provider" | grep -qiE '(oauth|jwt|auth-code|authorization-code)'; then + OAUTH_PROVIDER="$provider" + break + fi +done + +if [ -z "$OAUTH_PROVIDER" ]; then + echo "✅ No OAuth providers detected — HTTP connector not required." + exit 0 +fi + +echo "⚠️ OAuth/JWT provider detected: $OAUTH_PROVIDER" +echo " → HTTP listener required for OAuth callbacks." + +cd "$PROJECT_DIR" + +if [ ! -f pom.xml ]; then + echo "❌ pom.xml not found in $PROJECT_DIR" >&2 + echo " --project must point at a directory created by 'dx project create'." >&2 + exit 1 +fi + +if grep -q "mule-http-connector" pom.xml; then + echo "✅ HTTP connector already in pom.xml — nothing to add." + exit 0 +fi + +echo "🔍 Resolving latest HTTP connector from Exchange..." +# v8: get_latest_connector.sh emits a ranked GAV list on stdout and writes +# nothing. HTTP is unambiguous — take the top row. If a draft already +# exists (e.g., the agent pre-picked http in Step 3), prefer that to keep +# the Step-2 decision authoritative. +HTTP_CHOICE_JSON="tmp/connector-choices/http.json" +if [ -f "$HTTP_CHOICE_JSON" ]; then + echo "✅ Using existing HTTP draft at $HTTP_CHOICE_JSON" + HTTP_GAV="$(jq -r '"\(.groupId):\(.assetId):\(.version)"' "$HTTP_CHOICE_JSON")" +else + HTTP_LIST="$("$SCRIPT_DIR/get_latest_connector.sh" mule-http-connector http 2>/dev/null || true)" + if [ -z "$HTTP_LIST" ]; then + echo "❌ Could not resolve HTTP connector — add it manually." >&2 + exit 1 + fi + HTTP_GAV="$(printf '%s\n' "$HTTP_LIST" | head -n 1)" + # Persist as a draft so the rest of the workflow (commit_connectors.sh) + # promotes it into tmp/connector-versions/http.json alongside the others. + "$SCRIPT_DIR/pick_connector.sh" http "$HTTP_GAV" >/dev/null +fi + +HTTP_GROUP="$(printf '%s' "$HTTP_GAV" | awk -F: '{print $1}')" +HTTP_ARTIFACT="$(printf '%s' "$HTTP_GAV" | awk -F: '{print $2}')" +HTTP_VERSION="$(printf '%s' "$HTTP_GAV" | awk -F: '{print $3}')" + +if [ -z "$HTTP_GROUP" ] || [ -z "$HTTP_ARTIFACT" ] || [ -z "$HTTP_VERSION" ]; then + echo "❌ HTTP GAV parse failed: '$HTTP_GAV'" >&2 + exit 1 +fi + +cp pom.xml pom.xml.bak +awk -v g="$HTTP_GROUP" -v a="$HTTP_ARTIFACT" -v v="$HTTP_VERSION" ' + /<\/dependencies>/ { + print " " + print " " g "" + print " " a "" + print " " v "" + print " mule-plugin" + print " " + } + { print } +' pom.xml.bak > pom.xml + +if ! grep -q "$HTTP_ARTIFACT" pom.xml; then + echo "❌ Failed to insert HTTP connector — restoring pom.xml backup." >&2 + mv pom.xml.bak pom.xml + exit 1 +fi + +rm -f pom.xml.bak +echo "✅ Added $HTTP_GROUP:$HTTP_ARTIFACT:$HTTP_VERSION to pom.xml" diff --git a/skills/mule-development/build-mule-integration/scripts/pick_connector.sh b/skills/mule-development/build-mule-integration/scripts/pick_connector.sh new file mode 100755 index 0000000..64596ad --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/pick_connector.sh @@ -0,0 +1,63 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 3 helper — record the agent's (or user's) connector choice as a draft. +# Runs once the agent has decided which row from get_latest_connector.sh's +# ranked list is the right fit — either because the list had one row, the +# user's stated system made the choice obvious, or an AskUserQuestion +# prompt resolved a variant ambiguity. +# +# Usage: +# scripts/pick_connector.sh +# +# Writes {groupId, assetId, version} JSON to: +# tmp/connector-choices/.json +# +# Idempotent: re-running with a different GAV overwrites the draft. That's +# intentional — the agent may revise a pick after Step 4 metadata or Step 5 +# trigger selection reveals a better fit. Drafts stay in tmp/connector-choices/ +# throughout Phase 1; only commit_connectors.sh promotes them to the +# tmp/connector-versions/ directory that Phase 2 reads. +# +# Exit code: +# 0 draft written +# 1 bad arguments / malformed GAV +set -u + +NICKNAME="${1:-}" +GAV="${2:-}" + +if [ -z "$NICKNAME" ] || [ -z "$GAV" ]; then + echo "Usage: $0 " >&2 + echo " e.g. $0 slack com.mulesoft.connectors:mule4-slack-connector:2.0.1" >&2 + exit 1 +fi + +# Require exactly three non-empty colon-separated fields. Using awk avoids +# the split-with-trailing-colons footgun that Bash's IFS read introduces +# (where "a:b:c:d" puts "c:d" in the third variable instead of failing). +NF=$(printf '%s' "$GAV" | awk -F: '{print NF}') +if [ "$NF" != "3" ]; then + echo "Bad GAV format: '$GAV'" >&2 + echo "Expected exactly 3 non-empty colon-separated parts: groupId:assetId:version" >&2 + exit 1 +fi + +GROUP_ID=$(printf '%s' "$GAV" | awk -F: '{print $1}') +ASSET_ID=$(printf '%s' "$GAV" | awk -F: '{print $2}') +VERSION=$(printf '%s' "$GAV" | awk -F: '{print $3}') + +if [ -z "$GROUP_ID" ] || [ -z "$ASSET_ID" ] || [ -z "$VERSION" ]; then + echo "Bad GAV format: '$GAV' (one or more fields empty)" >&2 + exit 1 +fi + +OUT_DIR="${CONNECTOR_CHOICES_DIR:-tmp/connector-choices}" +mkdir -p "$OUT_DIR" +OUT_FILE="$OUT_DIR/${NICKNAME}.json" + +jq -n --arg g "$GROUP_ID" --arg a "$ASSET_ID" --arg v "$VERSION" \ + '{groupId: $g, assetId: $a, version: $v}' >"$OUT_FILE" + +echo "Drafted: $NICKNAME → $GROUP_ID:$ASSET_ID:$VERSION" +echo "Saved to $OUT_FILE" diff --git a/skills/mule-development/build-mule-integration/scripts/validate_prerequisites.sh b/skills/mule-development/build-mule-integration/scripts/validate_prerequisites.sh new file mode 100755 index 0000000..cfe92a0 --- /dev/null +++ b/skills/mule-development/build-mule-integration/scripts/validate_prerequisites.sh @@ -0,0 +1,121 @@ +#!/usr/bin/env bash +# Part of mule-dev skill +# +# Step 1 helper — validates the toolchain and emits a machine-readable env +# report to /tmp/mule-dev-env.json so later steps can consume it. +# +# This script only VALIDATES — it never downloads, installs, or modifies +# anything. If something is missing, the agent decides how to fix it. +# +# On success, writes: +# /tmp/mule-dev-env.json → {"ok": true/false, "errors": [...], "warnings": [...], +# "mule_version": "...", "runtime_path": "...", +# "java_home": "...", "java_version": "..."} +# Exit code: +# 0 all checks passed +# 1 one or more fatal checks failed — agent should act on the errors array +set -u + +OUT_FILE="${MULE_DEV_ENV_FILE:-/tmp/mule-dev-env.json}" + +ERRORS=() +WARNINGS=() +MULE_VERSION="" +RUNTIME_PATH="" +JAVA_VERSION="" + +echo "Validating prerequisites..." + +# 1. anypoint-cli-v4 +if ! command -v anypoint-cli-v4 >/dev/null 2>&1; then + echo "❌ anypoint-cli-v4 not installed" + ERRORS+=("anypoint-cli-v4 not installed. Install: npm install -g @mulesoft/anypoint-cli-v4") +else + echo "✅ anypoint-cli-v4 found" +fi + +# 2. DX plugin +if command -v anypoint-cli-v4 >/dev/null 2>&1; then + if ! anypoint-cli-v4 dx mule --help >/dev/null 2>&1; then + echo "❌ DX plugin not installed" + ERRORS+=("DX plugin not installed. Install: npm install -g @mulesoft/anypoint-cli-dx-mule-plugin") + else + echo "✅ DX plugin found" + fi +fi + +# 3. JAVA_HOME + Java 11+ +if [ -z "${JAVA_HOME:-}" ]; then + echo "❌ JAVA_HOME not set" + ERRORS+=("JAVA_HOME not set. Fix: export JAVA_HOME=\$(/usr/libexec/java_home -v 11)") +else + echo "✅ JAVA_HOME: $JAVA_HOME" + JAVA_VERSION=$(java -version 2>&1 | head -n 1 | awk -F '"' '{print $2}' | cut -d. -f1) + if [ -z "$JAVA_VERSION" ] || [ "$JAVA_VERSION" -lt 11 ]; then + echo "❌ Java 11+ required (found: Java ${JAVA_VERSION:-unknown})" + ERRORS+=("Java 11+ required, found: ${JAVA_VERSION:-unknown}") + else + echo "✅ Java version: $JAVA_VERSION" + fi +fi + +# 4. Mule runtime — check configured path first, then default location +RUNTIME_PATH="" +CONFIG_FILE="$HOME/.mule-dx/config.json" + +if [ -f "$CONFIG_FILE" ]; then + CONFIGURED_PATH=$(jq -r '.runtimePath // empty' "$CONFIG_FILE" 2>/dev/null || true) + if [ -n "$CONFIGURED_PATH" ] && [ -d "$CONFIGURED_PATH" ]; then + RUNTIME_PATH="$CONFIGURED_PATH" + fi +fi + +if [ -z "$RUNTIME_PATH" ]; then + RUNTIME_PATH=$(find ~/AnypointCodeBuilder/runtime -maxdepth 1 -name "mule-*" -type d 2>/dev/null | sort -V | tail -1) +fi + +if [ -n "$RUNTIME_PATH" ]; then + RUNTIME_NAME=$(basename "$RUNTIME_PATH") + MULE_VERSION=$(echo "$RUNTIME_NAME" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1) + echo "✅ Runtime detected: $RUNTIME_NAME (Mule $MULE_VERSION)" +else + echo "❌ No Mule runtime found" + echo " ACTION REQUIRED: Run 'anypoint-cli-v4 dx mule runtime download' to download the Mule runtime before proceeding." + echo " After download, run 'anypoint-cli-v4 dx mule runtime path --set ' to configure the runtime path." + ERRORS+=("No Mule runtime found. You MUST run 'anypoint-cli-v4 dx mule runtime download' to install it, then 'anypoint-cli-v4 dx mule runtime path --set ' to configure. No describe-connector commands will work until this is resolved.") +fi + +# Build result JSON +OK="true" +if [ ${#ERRORS[@]} -gt 0 ]; then + OK="false" +fi + +if [ ${#ERRORS[@]} -gt 0 ]; then + ERRORS_JSON=$(printf '%s\n' "${ERRORS[@]}" | jq -R . | jq -s .) +else + ERRORS_JSON="[]" +fi +if [ ${#WARNINGS[@]} -gt 0 ]; then + WARNINGS_JSON=$(printf '%s\n' "${WARNINGS[@]}" | jq -R . | jq -s .) +else + WARNINGS_JSON="[]" +fi + +cat >"$OUT_FILE" <" + - Multiple projects: "Run Multiple Projects" +- **noDebug** (optional): Whether this is a run-only configuration (true, default) or debug configuration (false) + +Then call the `create_run_configuration` Language Model Tool with these parameters. + +## Detecting Request Specificity + +**FIRST**: Analyze the user's request to determine if they already specified which projects to include. + +**Specific requests** (skip project selection, proceed directly): +- User says "all projects": "create config for all projects", "all my projects", "create run config for all" +- User names specific project(s): "create config for project1 and project2", "create config for test-app" + +**Vague requests** (need to ask): +- Generic: "create a run config", "new config", "set up config" +- No project indication: "create run configuration" + +**If the request is SPECIFIC and mentions "all projects":** +- Get workspace info (step 1) +- Use ALL projects from the workspace info +- Skip directly to step 3 (collect preferences for name and mode) +- DO NOT show the project selection list or buttons + +**If the request is SPECIFIC and names exact projects:** +- Get workspace info (step 1) +- Match the named projects against the projects list +- Skip directly to step 3 (collect preferences for name and mode) +- DO NOT show the project selection list or buttons + +**If the request is VAGUE:** +- Follow the full step-by-step process below (steps 1-4) + +## Step-by-Step Process + +## Step 1: Get Workspace Information + +⚠️ **MANDATORY FIRST STEP**: + +Call `get_workspace_info` to get the list of projects: + +```typescript +{ + // No parameters needed +} +``` + +This returns: +```json +{ + "workspaceType": "multi-root" | "single-folder", + "projects": [ + { "name": "project-name", "path": "/absolute/path" } + ] +} +``` + +## Step 2: Show Available Projects and Let User Choose (Only for Vague Requests) + +**IMPORTANT**: This step should ONLY happen for vague requests. If the user already said "all projects" or named specific projects, skip this step entirely. + +Display the projects to the user in a **numbered list** (using 1., 2., 3., NOT bullets): + +``` +Available projects in workspace: +1. my-mule-app (/path/to/my-mule-app) +2. api-gateway (/path/to/api-gateway) +3. backend-service (/path/to/backend-service) + +Which projects do you want to include? +(Enter numbers like "1,3" or "all" for all projects) +``` + +**IMPORTANT**: +- Always use numbers (1., 2., 3.) NOT bullets (•, -, *) so users can easily select by number +- Use the projects list from step 1 + +**If workspace has only one project:** +- Auto-select it automatically - DO NOT ask the user to choose +- Skip directly to step 3 (collecting preferences for config name and mode) +- Confirm to the user: "Found 1 project: my-mule-app. Using this project for the run configuration." + +**If workspace has multiple projects and request was vague:** +- Most users want to run multiple projects together, so suggest combinations +- Show exactly 4 quick-select buttons: + 1. A suggested combination of some projects (e.g., "Projects 1, 2") + 2. A different suggested combination (e.g., "Projects 2, 3") + 3. "all" - all projects in the workspace + 4. "Let me specify different projects" - for custom selection +- NEVER show individual project buttons (like "1", "2", "3" alone) +- NEVER show all possible combinations +- NEVER suggest a combination that includes all projects (that's what "all" is for) +- For the suggested combinations, pick logical groupings if possible, or just pick different subsets of 2-3 projects + +## Step 3: Collect Additional Preferences + +After user selects projects, ask for: + +**Configuration name** (optional): +- For single project: default to "Run " +- For multiple projects: default to "Run Multiple Projects" +- **CRITICAL**: Present ONLY TWO options to the user: + 1. A button/option to use the default name + 2. A text input option for them to type their own custom name +- **DO NOT** suggest any custom name ideas +- **DO NOT** generate multiple name suggestions +- **DO NOT** provide examples like "Debug Config" or "Test Projects" +- The ONLY pre-filled option should be the default name based on the rule above +- Ask: "Use default name 'Run ' or type a custom name?" + +**Debug or run mode** (only if not obvious from user's initial request): +- Default: Run mode (noDebug = true) +- If user said "debug config" in their initial request, use noDebug = false +- Otherwise, you can skip asking and use the default (run mode) + +## Step 4: Call the Language Model Tool + +Execute the `manage_run_configuration` tool with operation "create": + +```typescript +{ + "operation": "create", + "projects": string[], // Array of selected project paths (absolute paths from workspaceFolder.uri.fsPath) + "configName": string, // Configuration name (use default "Run " if user didn't specify custom) + "noDebug": boolean // Optional (omit to use default: true) +} +``` + +**Important:** +- The `projects` array should contain the **absolute file system paths** from `workspaceFolder.uri.fsPath` for each selected project +- The tool will automatically convert these to the `${workspaceFolder:name}` format +- **Always include `configName`** in the tool call - use the default name ("Run " or "Run Multiple Projects") if the user didn't provide a custom name +- **Scope is determined automatically**: + - If projects.length > 1 → saves to workspace file (.code-workspace) + - If projects.length === 1 → saves to that project's launch.json + +## Step 5: Inform the User and Offer to Run + +After calling the tool, the tool will return a success message with the ACTUAL configuration name created. + +**CRITICAL**: The tool may return a DIFFERENT name if there was a duplicate (e.g., "Run my-app (2)"). You MUST use the EXACT name from the success message. + +Share the result with the user and ask if they want to run it: +``` +✓ Successfully created run configuration 'Run my-app' with 1 project(s) + +Would you like to run this configuration now? +``` + +If the user says yes, call the tool again with operation "execute". **Use the EXACT name from the create response**, not your originally suggested name. + +**If created for multiple projects (workspace-level):** +```typescript +{ + "operation": "execute", + "configName": "", // Use the exact name returned, including any (2), (3), etc. + "scope": "workspace" +} +``` + +**If created for single project (project-level):** +```typescript +{ + "operation": "execute", + "configName": "", // Use the exact name returned, including any (2), (3), etc. + "scope": "project", + "projectPath": "" +} +``` + +## Handling Common Scenarios + +### Scenario 1: Single project workspace + +``` +User: "Create a run config" +Flow: +1. Show: "Found 1 project: my-mule-app. Using this for the configuration." +2. Ask: "Configuration name? (default: 'Run my-mule-app')" +3. User presses Enter or provides custom name +4. Call tool with collected params +``` + +### Scenario 2: Multiple projects + +``` +User: "Create a run config" + +Flow: +1. Show numbered list of all workspace projects +2. User enters: "1,2" +3. Ask: "Configuration name? (default: 'Run Multiple Projects')" +4. User provides: "Both Services" +5. Call tool with: projects = [project1Path, project2Path], configName = "Both Services" +``` + +### Scenario 3: Debug mode explicitly requested + +``` +User: "Create a debug config" + +Flow: +1. Show projects list +2. User selects project(s) +3. Ask for name (optional) +4. Call tool with noDebug = false (because user said "debug") +``` + +## Important Notes + +- **Always show available projects first** - list workspace folders and let user select by number +- **Support flexible input** - users can enter "1", "1,3", "all", or project names +- **You don't validate anything** - the tool handles all validation and file operations +- **Keep it conversational** - don't ask for information the command doesn't need +- **Detect debug intent** - if user says "debug" in their request, set noDebug = false +- **Use the EXACT name returned after creating** - If the create operation returns "Run my-app (2)", you MUST use that exact name (with the number) when offering to run it. Do NOT use the original suggested name. +- **ALWAYS provide scope when executing** - The execute operation REQUIRES the `scope` parameter. NEVER call execute without specifying "workspace" or "project" scope. +- **CRITICAL: NEVER run multiple projects individually** - Only ONE Mule runtime instance can be active at a time. To run multiple projects together, they MUST be in a single workspace-level configuration. NEVER attempt to run project-level configs sequentially or in parallel for multiple projects. + +## Example Conversations + +### Example 1: Quick single-project setup + +```text +User: "Create a run config" + +Assistant: "Found 1 project: my-mule-app +Using this project for the run configuration. +Use default name 'Run my-mule-app' or type a custom name?" + +User: [uses default] +Assistant: "Creating run configuration 'Run my-mule-app' with: +- Projects: ['/path/to/my-mule-app'] +- Mode: Run (noDebug: true) + +✓ Successfully created run configuration. + +Would you like to run this configuration now?" +``` + +### Example 2: Multiple projects with custom name + +```text +User: "Create a run config for api-gateway and backend" + +Assistant: "Available projects in workspace: +1. api-gateway (/workspace/api-gateway) +2. backend-service (/workspace/backend-service) +3. database-connector (/workspace/database-connector) + +Which projects do you want to include? (e.g., '1,2' or 'all')" + +User: "1,2" + +Assistant: "Use default name 'Run Multiple Projects' or type a custom name?" + +User: "Both Services" + +Assistant: "Creating run configuration 'Both Services' with: +- Projects: ['/workspace/api-gateway', '/workspace/backend-service'] +- Mode: Run (noDebug: true) + +✓ Successfully created run configuration. + +Would you like to run this configuration now?" +``` + +### Example 3: Debug configuration + +```text +User: "Create a debug config for my app" + +Assistant: "Found 1 project: my-mule-app +Using this project for the run configuration. +Use default name 'Run my-mule-app' or type a custom name?" + +User: [uses default] + +Assistant: "Creating debug configuration 'Run my-mule-app' with: +- Projects: ['/path/to/my-mule-app'] +- Mode: Debug (noDebug: false) + +✓ Successfully created run configuration. + +Would you like to run this configuration now?" +``` + +### Example 4: Specific request with "all projects" + +```text +User: "Create a run config for all projects" + +Assistant: "Found 3 projects in workspace. Creating run configuration for all of them. + +Use default name 'Run Multiple Projects' or type a custom name?" + +User: "All Three" + +Assistant: "Creating run configuration 'All Three' with: +- Projects: ['/workspace/project1', '/workspace/project2', '/workspace/project3'] +- Mode: Run (noDebug: true) + +✓ Successfully created run configuration. + +Would you like to run this configuration now?" +``` + +### Example 5: Vague request - full flow + +```text +User: "Create a config" +Assistant: "Available projects in workspace: +1. api-gateway (/workspace/api-gateway) +2. backend-service (/workspace/backend-service) +3. test-app (/workspace/test-app) + +Which projects do you want to include? (e.g., '1,2' or 'all')" + +User: "Just 1" + +Assistant: "Use default name 'Run api-gateway' or type a custom name?" + +User: "Development" + +Assistant: "Should this be run mode or debug mode? (default: run)" + +User: "run" + +Assistant: "Creating run configuration 'Development' with: +- Projects: ['/workspace/api-gateway'] +- Mode: Run (noDebug: true) + +✓ Successfully created run configuration. + +Would you like to run this configuration now?" +``` diff --git a/skills/mule-development/delete-mule-run-config/SKILL.md b/skills/mule-development/delete-mule-run-config/SKILL.md new file mode 100644 index 0000000..5d6f0dd --- /dev/null +++ b/skills/mule-development/delete-mule-run-config/SKILL.md @@ -0,0 +1,405 @@ +--- +name: delete-mule-run-config +description: Call use_skill as your FIRST and ONLY action when the user asks to DELETE, REMOVE, or GET RID OF an existing run configuration for Mule applications. Use this ONLY for deleting/removing configurations, NOT for creating or editing. Trigger phrases include "delete config", "remove config", "get rid of config", "delete all configs", "remove all my run configs", "clean up configs". When you call use_skill, it must be the only tool call in that response. +user-invocable: true +--- + +You are a Mule run configuration deletion assistant. Help users safely remove run configurations they no longer need. + +## Your Task + +Help the user delete run configurations by: +1. Identifying which configuration(s) to delete +2. Confirming the deletion with the user +3. Calling the tool to remove them + +## Detecting Request Specificity + +**FIRST**: Analyze if the user already provided the config name or wants to delete all. + +**Delete ALL requests** (e.g., "delete all configs", "remove all my run configs"): +- List all configurations (workspace + all projects) +- Exclude default configs (they cannot be deleted) +- Show the complete list to the user +- Ask for confirmation before deleting ALL of them +- Delete them one by one + +**Specific requests** (user names the config): +- Example: "delete 'Run My App'", "remove 'Both Services'" +- Get workspace info +- Search for the config by listing all scopes (workspace + all projects) +- Use intelligent matching (see Step 2 below) +- If found in only one location: show details and ask for confirmation +- If found in multiple locations (duplicates): show all matches with context and ask which one +- If not found or similar matches exist: suggest with context + +**Vague requests** (no config name): +- Example: "delete a config", "remove the config for test-project1" +- Follow the full step-by-step process below + +## Step-by-Step Process + +## Step 1: Get Workspace Information First + +⚠️ **MANDATORY FIRST STEP**: + +Your VERY FIRST action must be to call `get_workspace_info` to understand the workspace structure. + +```typescript +{ + // No parameters needed +} +``` + +This will return: +```json +{ + "workspaceType": "multi-root" | "single-folder", + "projects": [ + { "name": "project-name", "path": "/absolute/path" } + ] +} +``` + +## Step 2: Smart Config Matching (if user specified the name or project) + +**If the user already mentioned the config name or project name in their request** (e.g., "Delete 'Both Services'" or "Delete config for test-project1"): + +1. Extract the config name or project name from the request +2. Get workspace info +3. Collect ALL configs from all scopes (workspace + all projects) +4. **Determine search type:** + - If user mentioned a config name → search by config name + - If user mentioned "for " → search by project name in config's `mule.projects` +5. Find best match using intelligent similarity: + + **Case 1: Single exact match** (case-sensitive or case-insensitive) + - For config name search: exact name match + - For project search: config's projects list contains the project name + - Show config details and ask for confirmation (skip to step 4) + + **Case 2: Multiple exact matches** (duplicates) + - For config name search: multiple configs with same name + - For project search: multiple configs contain the project + - Show ALL matches with context: + ```text + Found 3 configurations for "test-project1": + 1. Run my-app - Single project (test-project1) - run mode + 2. Debug my-app - Single project (test-project1) - debug mode + 3. Both Services - Multiple projects (test-project1, test-project2) - run mode + + Which one do you want to delete? + ``` + - Wait for user to select, then show details and confirm (skip to step 4) + + **Case 3: High similarity match** (typos, extra spaces, similar words) + - Use Levenshtein distance or similar algorithm + - For config name search: similar config names + - For project search: similar project names in workspace + - Examples that should match: + - "my custom config" ↔ "myy custom config" (typo) + - "My custom configuration" ↔ "my custom config" (similar words) + - "Both Services" ↔ "both services" (case difference) + - "test-project-1" ↔ "test-project1" (similar project name) + - If best match has high confidence (>80% similarity): suggest it with context + ```text + Configuration "My custoom config" not found. Did you mean: + "My custom config" - Multiple projects (api-gateway, backend) - run mode + ``` + - Wait for confirmation, then show details and confirm deletion (skip to step 4) + + **Case 4: Multiple similar matches** + - Show top 3 matches with similarity scores and context + - Ask user to pick, then show details and confirm (skip to step 4) + + **Case 5: No good matches** + - List all configs and ask user to select + +**If the user did NOT mention a config name**: +- Proceed to step 3 to ask about scope + +## Step 3: Ask About Scope (Only if needed) + +**If workspaceType is "multi-root"**: + +Ask the user: +```text +Is this configuration for: +1. Multiple projects +2. A single specific project +``` + +**STOP and wait for their answer.** + +**IMPORTANT**: Do NOT mention "workspace-level" or "project-level" to the user. These are internal technical terms. + +**If workspaceType is "single-folder"**: + +Skip to step 4 with scope "project" and use that single project's path. + +## Step 4: List the Configurations + +**If user chose "Multiple projects"** (or single-folder workspace): + +For workspace-level: +```typescript +{ + "operation": "list", + "scope": "workspace", + "excludeDefaults": true +} +``` + +For single-folder, use the project path from step 1: +```typescript +{ + "operation": "list", + "scope": "project", + "projectPath": "", + "excludeDefaults": true +} +``` + +**If user chose "Single project"** (multi-root only): +- Ask which project (show the projects list from step 1) +- Then call: +```typescript +{ + "operation": "list", + "scope": "project", + "projectPath": "", + "excludeDefaults": true +} +``` + +Show the returned list to the user and ask which configuration they want to delete. + +**IMPORTANT**: For workspace-level configs, the list shows projects in format: `ConfigName (mode) - projects: [project1, project2]` +- Compare the projects in each config with current workspace projects (from step 1) +- If a config references projects that no longer exist, mention this to the user +- Example: "Note: 'Run Multiple Projects' has 5 projects but only 3 are in your current workspace" + +**If no configurations are found** (list returns empty or "No run configurations found"): +- Inform the user that there are no custom run configurations to delete +- **DO NOT** retry the list operation with `excludeDefaults: false` +- Default configurations ("Run Mule Application", "Debug Mule Application") cannot be deleted, so showing them would only confuse the user + +## Step 5: Confirm Deletion + +**IMPORTANT**: Always confirm before deleting. Show what will be deleted using this exact format: + +```text +You are about to delete this run configuration: + +Name: +Projects: +Mode: + +This action cannot be undone. + +Are you sure you want to delete this configuration? +``` + +**Format rules:** +- Each field (Name, Projects, Mode) on its own line +- No bullet points or dashes +- Projects should be a comma-separated list +- Mode is "Run" if noDebug is true, "Debug" if noDebug is false or undefined/missing +- Always include "This action cannot be undone." exactly as written +- Do not add additional warnings or explanations + +Wait for explicit user confirmation before proceeding. + +## Step 6: Call the Language Model Tool + +After user confirms, execute the `manage_run_configuration` tool with operation "delete": + +**For workspace-level config:** +```typescript +{ + "operation": "delete", + "configName": string, // Required: name of the configuration to delete + "scope": "workspace" // Required: indicates workspace-level config +} +``` + +**For project-level config:** +```typescript +{ + "operation": "delete", + "configName": string, // Required: name of the configuration to delete + "scope": "project", // Required: indicates project-level config + "projectPath": string // Required: absolute path to the project +} +``` + +**Important**: +- Always include `scope` to specify where the config is located +- Include `projectPath` when scope is "project" (use the same projectPath you used in the list operation) + +## Step 7: Inform the User + +After calling the tool, the tool will return a success message. Share it with the user: +```text +✓ Successfully deleted run configuration '' +``` + +## Important Notes + +- **Always confirm before deleting** - This is a permanent action +- **Show what's being deleted** - Give the user context about the configuration +- **Don't delete without explicit confirmation** - Even if the user's request seems clear + +## Example Conversations + +### Example 1: Exact match - direct delete + +```text +User: "Delete 'Run my-app'"Assistant: [gets workspace info, finds exact match] + +"You are about to delete this run configuration: + +Name: Run my-app +Projects: my-mule-app +Mode: Run + +This action cannot be undone. + +Are you sure you want to delete this configuration?" + +User: "Yes" + +Assistant: "Deleting configuration... + +✓ Successfully deleted run configuration 'Run my-app'" +``` + +### Example 2: Delete all configurations + +```text +User: "Delete all my run configs" + +Assistant: "Let me list all your custom run configurations... + +Found 3 custom configurations: +1. Run my-app (project-level) +2. Debug my-app (project-level) +3. Both Services (workspace-level) + +You are about to delete ALL 3 configurations. This action cannot be undone. + +Are you sure you want to delete all of them?" + +User: "Yes" + +Assistant: "Deleting all configurations... + +✓ Successfully deleted run configuration 'Run my-app' +✓ Successfully deleted run configuration 'Debug my-app' +✓ Successfully deleted run configuration 'Both Services' + +All custom run configurations have been deleted." +``` + +### Example 3: High similarity match - suggest with context + +```text +User: "Delete 'my custom confg'" +Assistant: [gets workspace info, searches all scopes] + +"Configuration 'my custom confg' not found. Did you mean: +'My custom config' - Multiple projects (api-gateway, backend) - run mode + +Would you like to delete this configuration?" + +User: "Yes" + +Assistant: "You are about to delete this run configuration: + +Name: My custom config +Projects: api-gateway, backend +Mode: Run + +This action cannot be undone. + +Are you sure you want to delete this configuration?" + +User: "Yes" + +Assistant: "Deleting configuration... + +✓ Successfully deleted run configuration 'My custom config'" +``` + +### Example 4: Vague request - full flow + +```text +User: "Delete a config" +Assistant: "Is this configuration for: +1. Multiple projects +2. A single specific project" + +User: "Single project" + +Assistant: "Which project would you like to delete configurations from? +1. api-gateway (/path/to/api-gateway) +2. backend (/path/to/backend)" + +User: "api-gateway" + +Assistant: [lists configs] "Found 2 run configurations: +1. Run api-gateway (run mode) +2. Debug api-gateway (debug mode) + +Which configuration would you like to delete?" + +User: "1" + +Assistant: "You are about to delete this run configuration: + +Name: Run api-gateway +Projects: api-gateway +Mode: Run + +This action cannot be undone. + +Are you sure you want to delete this configuration?" + +User: "Yes" + +Assistant: "Deleting configuration... + +✓ Successfully deleted run configuration 'Run api-gateway'" +``` + +### Example 5: Specific request - match by project name + +```text +User: "Delete the config for test-project1" + +Assistant: [gets workspace info, searches all scopes for configs containing test-project1] + +"Found 2 configurations for test-project1: +1. Run my-app - Single project (test-project1) - run mode +2. Debug my-app - Single project (test-project1) - debug mode + +Which one do you want to delete?" + +User: "1" + +Assistant: "You are about to delete this run configuration: + +Name: Run my-app +Projects: test-project1 +Mode: Run + +This action cannot be undone. + +Are you sure you want to delete this configuration?" + +User: "Yes" + +Assistant: "Deleting configuration... + +✓ Successfully deleted run configuration 'Run my-app'" +``` diff --git a/skills/mule-development/execute-mule-run-config/SKILL.md b/skills/mule-development/execute-mule-run-config/SKILL.md new file mode 100644 index 0000000..d94190a --- /dev/null +++ b/skills/mule-development/execute-mule-run-config/SKILL.md @@ -0,0 +1,311 @@ +--- +name: execute-mule-run-config +description: Call use_skill as your FIRST and ONLY action when the user asks to RUN, START, or DEBUG a Mule application. This includes executing applications in run mode OR debug mode. Trigger phrases include "run my project", "run all projects", "debug my project", "debug all my projects", "start the app", "run ", "debug ". When you call use_skill, it must be the only tool call in that response. +user-invocable: true +--- + +You are a Mule run configuration execution assistant. Help users run their Mule applications using existing run configurations. + +## Your Task + +Help the user run a Mule application by: +1. Determining if the request is specific or vague +2. Getting workspace information +3. Finding or creating the appropriate configuration +4. Executing it (automatically if specific, with confirmation if vague) + +## Detecting Request Specificity + +**FIRST**: Analyze the user's request to determine if it's specific or vague. + +**Specific requests** (can proceed automatically): +- User names exact project(s): "run test-project1", "debug project A and B", "start test-run-config", "debug all projects", "run all my projects", "run my project" +- User names exact config: "run with config 'Debug My App'", "execute 'Run Multiple Projects'" +- **Mode detection**: + - Default to RUN mode (noDebug: true) unless user explicitly mentions "debug" + - Debug phrases: "debug my project", "run in debug mode", "start with debugging", "debug mode" + - Run phrases (default): "run my project", "start my app", "run test-project1" + +**Vague requests** (need clarification): +- Generic without any project context: "run something", "debug something" +- Ambiguous without context: "run", "start", "debug" (with no project names, config names, or "all") +- **Context-dependent vague requests** (only vague if multiple projects exist): + - "run project", "run my project", "start the app" are VAGUE only in multi-root workspaces + - In single-folder workspaces, these are SPECIFIC (use the only project available) + +**If the request is SPECIFIC**: +- Skip asking questions +- Find or create a matching configuration +- Execute it automatically + +**If the request is VAGUE**: +- Follow the full step-by-step process below +- Always ask for confirmation before executing + +**IMPORTANT**: After calling `get_workspace_info` in step 1, re-evaluate if the request is vague: +- If single-folder workspace + user said "run my project" → treat as SPECIFIC (use the only project) +- If multi-root workspace + user said "run my project" → treat as VAGUE (ask which project) + +## Handling Specific Requests + +If the user's request is specific (names exact projects or config): + +### 1. Get Workspace Info +Call `get_workspace_info` to get available projects. + +### 2. Find Matching Configuration + +**If user named an exact configuration** (e.g., "run 'Debug My App'"): +- List configs in the appropriate scope (ask if needed) +- Look for a config with that exact name +- If found: execute it (skip to step 4) +- If not found: tell user it doesn't exist and suggest creating one + +**If user named specific project(s)** (e.g., "run test-project1", "run my project", "debug all projects"): +- **Detect the mode from user's words** (IMPORTANT - default to run mode): + - If user explicitly says "debug", "debug mode", or "run in debug": look for debug configs (noDebug: false OR noDebug: undefined/missing) + - **Otherwise, default to run mode**: look for run configs (noDebug: true) + - Examples: + - "run my project" → run mode (noDebug: true) + - "start test-project1" → run mode (noDebug: true) + - "debug my project" → debug mode (noDebug: false/undefined) + - "run my project in debug mode" → debug mode (noDebug: false/undefined) +- Match the project name(s) against the projects from step 1: + - "all projects" or "all my projects" → use ALL projects from workspace info + - Specific names → match those projects +- Determine scope: single project → "project", multiple projects → "workspace" +- **List configurations in that scope**: + - For workspace: `{ "operation": "list", "scope": "workspace" }` + - For project: `{ "operation": "list", "scope": "project", "projectPath": "" }` + - **DO NOT call list without the scope parameter** - it will fail + - **IMPORTANT**: Workspace-level list now shows projects in format: `ConfigName (mode) - projects: [project1, project2]` +- Look for a matching configuration: + - Must match the mode (debug vs run) + - **CRITICAL**: Must match the projects exactly - compare the projects list in the config with current workspace projects + - If a config references projects that are no longer in the workspace, SKIP it (those projects were removed) + - If a config has different projects than requested, SKIP it +- If found with matching projects: execute it (skip to step 4) +- If not found or all configs have wrong projects: create one automatically (see step 3) + +### 3. Create Configuration If Needed + +If no matching config exists (specific request only): +- Use the projects they specified +- Detect mode from user's words: "debug" → noDebug: false, "run"/"start" → noDebug: true +- Generate appropriate name: + - Debug mode: "Debug " or "Debug All Projects" + - Run mode: "Run " or "Run All Projects" +- Create the config with `manage_run_configuration` operation "create" +- **CRITICAL**: The tool may return a DIFFERENT name if there was a duplicate (e.g., "Run All Projects (2)") +- **MUST use the EXACT name returned by the create operation** when executing in step 4 + +### 4. Execute Automatically + +Since the request was specific, execute without additional confirmation. + +**CRITICAL**: Use the exact configuration name returned by the create operation in step 3, NOT the name you originally suggested. If the tool said it created "Run All Projects (2)", you MUST use "Run All Projects (2)" when executing. + +## Step-by-Step Process (For Vague Requests) + +## Step 1: Get Workspace Information First + +⚠️ **MANDATORY FIRST STEP**: + +Your VERY FIRST action must be to call `get_workspace_info` to understand the workspace structure. DO NOT skip this step. + +```typescript +{ + // No parameters needed +} +``` + +This will return: +```json +{ + "workspaceType": "multi-root" | "single-folder", + "projects": [ + { "name": "project-name", "path": "/absolute/path" } + ] +} +``` + +## Step 2: Ask User About Scope (Only if multi-root) + +**If workspaceType is "multi-root"** (has multiple projects): + +Ask the user: +```text +Do you want to run: +1. Multiple projects together +2. A single specific project +``` + +**STOP and wait for their answer.** + +**IMPORTANT**: Do NOT mention "workspace-level" or "project-level" to the user. These are internal technical terms. + +**If workspaceType is "single-folder"** (only one project): + +Skip to step 3 with scope "project" and use that single project's path. + +## Step 3: List Available Configurations + +**If user chose "Multiple projects together"** (or workspace-level): +```typescript +{ + "operation": "list", + "scope": "workspace" +} +``` + +**If user chose "A single specific project"** (or single-folder workspace): +- If multi-root: Ask which project (show the projects from step 1) +- Then call: +```typescript +{ + "operation": "list", + "scope": "project", + "projectPath": "" +} +``` + +**After listing configurations:** +1. Show ALL the configurations to the user +2. **For workspace-level configs**: Check that the projects in each config match current workspace projects + - If a config shows projects that are no longer in the workspace, mention this to the user + - Example: "Note: 'Run Multiple Projects' has 5 projects but only 3 are in your current workspace" +3. Ask which configuration they want to run +4. **STOP and WAIT for the user to choose** - DO NOT automatically run any configuration +5. Only proceed to step 4 after the user selects a configuration + +**CRITICAL**: Even if there is only ONE configuration in the list, you MUST still ask the user to confirm before running it. Do NOT assume they want to run it automatically. + +## Step 4: Execute the Selected Configuration (After User Confirms) + +Call the `manage_run_configuration` tool with operation "execute": + +**For workspace-level config:** +```typescript +{ + "operation": "execute", + "configName": string, + "scope": "workspace" +} +``` + +**For project-level config:** +```typescript +{ + "operation": "execute", + "configName": string, + "scope": "project", + "projectPath": string +} +``` + +## Step 5: Inform the User + +The tool will return a message like "Started configuration ''". Share this with the user. + +## Important Notes + +- **ALWAYS call get_workspace_info first** - This tells you the workspace type and available projects +- **NEVER call list without scope** - The `list` operation REQUIRES the `scope` parameter. Calling it without scope will always fail with an error. +- **Use the EXACT name returned after creating** - If you create a config and it returns "Run All Projects (2)", you MUST use that exact name (with the number) when executing. Do NOT use the original suggested name. +- **ALWAYS ask the user to confirm which configuration to run** - NEVER automatically execute a configuration without explicit user confirmation, even if there is only one configuration available (exception: specific requests like "run test-project1") +- **DO NOT make assumptions** - Choosing "Multiple projects together" does NOT mean the user wants to run ALL projects. They need to confirm which specific configuration to execute. +- **CRITICAL: NEVER run multiple projects individually** - Only ONE Mule runtime instance can be active at a time. To run multiple projects together, they MUST be in a single workspace-level configuration. NEVER attempt to run project-level configs sequentially or in parallel for multiple projects. +- **If a workspace-level run fails**: Do NOT fall back to running individual project configs. Do NOT use `run_local_mule_application` tool as a fallback. Instead, report the error and suggest creating a new workspace-level configuration or checking if the configuration exists. +- **NEVER use run_local_mule_application**: This tool is for a different workflow (direct runtime deployment). Always use `manage_run_configuration` with operation "execute" for executing run configurations. + +## Example Conversations + +### Example 1: Multi-root workspace - ask for scope + +```text +User: "Run project" +Assistant: "Do you want to run: +1. Multiple projects together +2. A single specific project" + +User: "Single project" + +Assistant: "Which project would you like to run?" + +User: "test-project1" + +Assistant: [lists configs] + +"Which configuration would you like to execute?" + +User: "Run Mule Application" + +Assistant: "✓ Started configuration 'Run Mule Application'" +``` + +### Example 2: Specific request - auto-execute + +```text +User: "Run test-project1" + +Assistant: [gets workspace info, finds project, lists configs, finds matching run config] + +"✓ Started configuration 'Run Mule Application'" +``` + +### Example 3: Debug mode explicitly requested + +```text +User: "Debug my project" + +Assistant: [gets workspace info, single-folder detected] + +[lists configs, finds debug config] + +"✓ Started configuration 'Debug Mule Application'" +``` + +### Example 4: Run all projects + +```text +User: "Run all projects" + +Assistant: [gets workspace info, detects multi-root] + +[creates or finds workspace-level config with all projects] + +"✓ Started configuration 'Run All Projects'" +``` + +### Example 5: Single-folder workspace with "run my project" + +```text +User: "Run my project" + +Assistant: [gets workspace info, detects single-folder] + +[lists configs, finds "Run Mule Application" with noDebug: true] + +"✓ Started configuration 'Run Mule Application'" +``` + +### Example 6: Projects removed from workspace - config with stale projects + +```text +User: "Run all my projects" +Assistant: [gets workspace info - 3 current projects: test-run-config, test-project1, test-project2] + +[lists workspace configs] + +"Found 2 workspace-level configurations: +1. Run Multiple Projects (run mode) - projects: [test-run-config, test-project1, test-project2, old-project1, old-project2] +2. Debug All (debug mode) - projects: [test-run-config, test-project1, test-project2] + +Note: 'Run Multiple Projects' references 5 projects but only 3 exist in your current workspace. It may fail if those projects were removed. + +I'll create a new configuration with your current 3 projects instead." + +[creates new config "Run Multiple Projects (2)" with current 3 projects] + +"✓ Started configuration 'Run Multiple Projects (2)'" +``` diff --git a/skills/mule-development/run-system-diagnostics/SKILL.md b/skills/mule-development/run-system-diagnostics/SKILL.md new file mode 100644 index 0000000..57f1aaf --- /dev/null +++ b/skills/mule-development/run-system-diagnostics/SKILL.md @@ -0,0 +1,168 @@ +--- +name: run-system-diagnostics +description: Run ACB (Anypoint Code Builder) system diagnostics to check if the machine meets minimum specifications and apply Windows optimizations if needed +metadata: + author: mule-dx-tooling + version: "1.0.0" +--- + +# ACB System Diagnostics + +This skill checks if the user's system meets the minimum specifications for Anypoint Code Builder and applies necessary Windows optimizations. + +## Minimum Specifications +- **CPU**: 8 cores/8 vCPU +- **RAM**: 32GB +- **Storage Type**: NVMe SSD (PCIe 3.0+) +- **Free Disk Space**: 50GB +- **Network Speed**: 1Gbps + +## Steps + +## Step 1: Detect Operating System +- Identify if the user is on Windows, macOS, or Linux + +## Step 2: Gather System Information +- CPU: Number of cores/vCPUs +- RAM: Total memory in GB +- Storage Type: Verify the storage uses NVMe standard (must be NVMe, not SATA SSD or HDD) +- Free Disk Space: Available space in GB +- Network Speed: Network interface speed + +**For Windows systems, use these PowerShell commands:** +- **CPU & RAM Info**: `powershell.exe -Command "Get-ComputerInfo | Select-Object CsProcessors, CsTotalPhysicalMemory, OsArchitecture"` +- **Logical Processors**: `powershell.exe -Command "(Get-WmiObject -Class Win32_Processor).NumberOfLogicalProcessors"` +- **Storage Info**: `powershell.exe -Command "Get-PhysicalDisk | Select-Object MediaType, BusType, Size, FriendlyName"` +- **Disk Space**: `powershell.exe -Command "Get-PSDrive C | Select-Object Used, Free"` +- **Network Speed**: `powershell.exe -Command "Get-NetAdapter | Select-Object Name, Status, LinkSpeed"` + +**For macOS systems, use these commands:** +- **CPU Cores**: `sysctl -n hw.physicalcpu && sysctl -n hw.logicalcpu` + - Returns physical and logical cores (use logical for comparison) +- **RAM**: `sysctl -n hw.memsize` + - Returns bytes, divide by 1073741824 to get GB +- **Disk Space**: `df -h /` + - Shows total, used, and available disk space +- **Storage Type (NVMe)**: `system_profiler SPNVMeDataType` + - Shows NVMe SSD details including model, capacity, and TRIM support +- **Network Hardware**: `networksetup -listallhardwareports` + - Lists all network interfaces +- **Wi-Fi Status**: `ifconfig en0 | grep 'status:' && networksetup -getinfo Wi-Fi` + - Shows if Wi-Fi is active and configuration details +- **Wi-Fi PHY Mode**: `system_profiler SPAirPortDataType | grep -A 10 "Current Network Information" | grep -E "Link Speed|PHY Mode"` + - Shows Wi-Fi standard (802.11ax = Wi-Fi 6, etc.) + +## Step 3: Compare Against Minimum Specifications +- For each component, indicate if it meets (✓) or fails (✗) the minimum requirement +- **IMMEDIATELY after gathering system info, display** a clear summary table showing: + - Component + - Current Value + - Minimum Required + - Status (Pass/Fail) +- Do not wait until the end of the skill to show this table + +## Step 4: Windows-Specific Optimizations +(only if on Windows) + +#### A. IOPS Performance Test +- **Locate DiskSpd executable:** + - Detect the processor architecture (amd64, arm64, or x86) + - Use the appropriate diskspd.exe from the skill's assets folder (relative to the skill base directory): + - For amd64: `{skill_base_directory}/assets/DiskSpd/amd64/diskspd.exe` + - For arm64: `{skill_base_directory}/assets/DiskSpd/arm64/diskspd.exe` + - For x86: `{skill_base_directory}/assets/DiskSpd/x86/diskspd.exe` + - **If the DiskSpd assets folder or the required diskspd.exe is missing, download and extract it:** + - **Before downloading, inform the user in one concise sentence** what is being downloaded and why, e.g. "Fetching Microsoft's DiskSpd utility from the official GitHub release to benchmark your disk's IOPS performance." + - Download URL: `https://github.com/microsoft/diskspd/releases/download/v2.2/DiskSpd.ZIP` + - Target location: `{skill_base_directory}/assets/DiskSpd/` + - Use PowerShell to download and extract: + ```powershell + $target = "{skill_base_directory}/assets/DiskSpd" + $zip = Join-Path $env:TEMP "DiskSpd.ZIP" + New-Item -ItemType Directory -Force -Path $target | Out-Null + Invoke-WebRequest -Uri "https://github.com/microsoft/diskspd/releases/download/v2.2/DiskSpd.ZIP" -OutFile $zip -UseBasicParsing + Expand-Archive -Path $zip -DestinationPath $target -Force + Remove-Item $zip -Force + ``` + - After extraction, verify that `diskspd.exe` exists under the architecture-specific subfolder (`amd64`, `arm64`, or `x86`) + - If the download fails (no network, proxy issues, etc.), inform the user clearly, provide the download URL, and skip the IOPS test rather than failing the whole skill +- **Create Test File:** + - Command: `diskspd.exe -c1G testfile.dat` + - This creates a 1GB test file required for IOPS testing + - Note: DiskSpd requires a pre-existing file to test against +- **Run Random Read IOPS Test:** + - Command: `diskspd.exe -b4K -d30 -o32 -t4 -r -w0 -Sh testfile.dat` + - This tests random read IOPS with 4KB blocks for 30 seconds + - Requirement: ≥10,000 IOPS +- **Run Random Write IOPS Test:** + - Command: `diskspd.exe -b4K -d30 -o32 -t4 -r -w100 -Sh testfile.dat` + - This tests random write IOPS with 4KB blocks for 30 seconds + - Requirement: ≥8,000 IOPS +- **Parse and Display Results:** + - Extract the IOPS values from the DiskSpd output + - Compare against minimum requirements: + - Random Read: 10,000 IOPS minimum + - Random Write: 8,000 IOPS minimum + - **IMMEDIATELY display a table** with the read and write IOPS result and Pass/Fail status + - If tests fail, provide guidance on storage improvements +- **Clean up:** + - Delete the testfile.dat after testing + +#### B. Microsoft Defender Exclusions +- **First, check current exclusions:** + - Use PowerShell to check existing process exclusions: `Get-MpPreference | Select-Object -ExpandProperty ExclusionProcess` + - Use PowerShell to check existing path exclusions: `Get-MpPreference | Select-Object -ExpandProperty ExclusionPath` + - Detect the current user's username dynamically + - Compare current exclusions against recommended exclusions: + - Process exclusions: `java.exe`, `javaw.exe`, `node.exe`, `Code.exe` + - Path exclusions (use current username): + - `C:\Users\\AnypointCodeBuilder` + - `C:\Users\\.vscode` + - `C:\Users\\.m2` + - `C:\Users\\AppData\Local\Temp` +- **Determine what's missing:** + - Identify which processes are NOT already excluded + - Identify which paths are NOT already excluded + - If all exclusions already exist, inform the user and skip this step +- **Ask for user permission (only if exclusions are missing):** + - Show the user which specific files/paths are not yet excluded + - Explain why these exclusions improve ACB performance (reduces scanning overhead) + - Ask if the user wants to add the missing exclusions + - Allow the user to decline +- **Apply exclusions (only if user agrees):** + - Run PowerShell commands to add missing exclusions: + - Use `Add-MpPreference -ExclusionProcess` for executables + - Use `Add-MpPreference -ExclusionPath` for directories + - Handle admin privilege errors: + - If commands fail due to insufficient privileges, catch the error + - Inform the user they need administrator privileges + - Provide the exact commands they should ask their admin to run + - Do not show scary error messages, just explain clearly what's needed + +#### C. Power Plan Analysis +- Check the current active power plan using: `powershell.exe -Command "powercfg /getactivescheme"` +- Display the current power plan to the user +- Analyze if the current power plan is sufficient for ACB: + - **High Performance**: ✓ Optimal for ACB - no change needed + - **Balanced**: ⚠ May impact ACB performance - recommend switching to High Performance + - **Power Saver**: ✗ Not recommended for ACB - strongly recommend switching to High Performance +- If the current plan is not High Performance: + - Explain why High Performance is recommended for ACB + - Ask the user if they want to switch to High Performance + - Provide the command: `powercfg /setactive SCHEME_MIN` (requires admin) + - Allow the user to skip this step if they choose +- If the current plan is already High Performance, inform the user and skip this step + +## Step 5: Output Format +- Present findings in a clear, formatted table +- For Windows systems, provide clear status of optimization steps +- For power plan: display current plan, provide analysis, and ask for user confirmation before making changes +- If admin privileges are required, inform the user and provide the exact commands they need to run +- If any specification is not met, highlight it clearly and suggest potential solutions +- Respect user choices to skip optional optimization steps + +## Important Notes +- Windows optimizations require administrator privileges +- Always verify system information before making changes +- Provide clear feedback on what was checked and what actions were taken +- For non-Windows systems (macOS, Linux), do NOT mention Windows-specific optimizations at all \ No newline at end of file diff --git a/skills/mule-development/secure-mule-app/SKILL.md b/skills/mule-development/secure-mule-app/SKILL.md new file mode 100644 index 0000000..30b6d97 --- /dev/null +++ b/skills/mule-development/secure-mule-app/SKILL.md @@ -0,0 +1,343 @@ +--- +name: secure-mule-app +description: Configure and implement Mule secure properties for encrypting sensitive data in Mule applications. Use this when the user wants to use/implement/add/configure Mule secure properties, secure configuration, or encrypt credentials in their Mule project. +metadata: + author: mule-dx-tooling + version: "1.0.0" +--- + +You are a MuleSoft security specialist helping to secure a Mule application by encrypting sensitive data. + +## Your Task + +Scan the Mule application for sensitive data (usernames, passwords, URLs, API keys, secrets, tokens) in both XML files (`src/main/mule`) and properties files (`src/main/resources`), then encrypt them using MuleSoft's secure properties configuration. + +## Step-by-Step Process + +## Step 1: Verify Project Structure +- Check that `src/main/mule` directory exists in the current working directory +- If not found, inform the user this doesn't appear to be a Mule application project + +## Step 2: Get User Configuration +Ask the user for the following information, **one question at a time**: + +**First, ask for the encryption key:** +- "What encryption key would you like to use for encrypting values? (This will be used to encrypt and decrypt your secure properties)" + +**Then, ask for the encryption algorithm:** +- "Which encryption algorithm would you like to use? (Enter the number)" + 1. `AES` - Advanced Encryption Standard (128, 192, or 256 bit) + 2. `Blowfish` - Fast block cipher + 3. `DES` - Data Encryption Standard + 4. `DESede` - Triple DES + 5. `RC2` - Rivest Cipher 2 + +**Next, ask for the cipher mode:** +- "Which cipher mode would you like to use? (Enter the number)" + 1. `CBC` - Cipher Block Chaining + 2. `CFB` - Cipher Feedback + 3. `ECB` - Electronic Codebook + 4. `OFB` - Output Feedback + 5. `GCM` - Galois/Counter Mode (for AES only) + +**Finally, ask about backup:** +- "Would you like to save the unencrypted values to `local.properties` for reference? (yes/no)" + +## Step 3: Locate or Download Secure Properties Tool JAR + +**Before checking, explicitly tell the user what you are doing and why.** Do not say a vague phrase like "let me check for the JAR" — the user will not know which JAR you mean. Instead, say something like: + +> "Checking for the MuleSoft **secure-properties-tool JAR** (the CLI tool used to encrypt your sensitive values). If it's not already downloaded locally, I'll fetch it from the MuleSoft docs site." + +- Check if the JAR already exists at: `{skill_base_directory}/assets/secure-properties-tool.jar` +- If it exists, tell the user it was found locally and will be reused, then proceed +- If it does **not** exist, tell the user it wasn't found and you're downloading it, then download it automatically: + 1. Create the assets directory if needed: `mkdir -p {skill_base_directory}/assets` + 2. Download using `curl` (preferred — available by default on macOS): + ```bash + curl -L -o "{skill_base_directory}/assets/secure-properties-tool.jar" \ + "https://docs.mulesoft.com/mule-runtime/4.4/_attachments/secure-properties-tool.jar" + ``` + 3. If `curl` is not available, try `wget`: + ```bash + wget -O "{skill_base_directory}/assets/secure-properties-tool.jar" \ + "https://docs.mulesoft.com/mule-runtime/4.4/_attachments/secure-properties-tool.jar" + ``` + 4. After downloading, verify the file exists and is non-empty before proceeding +- If the download fails, inform the user and provide the manual download URL: + `https://docs.mulesoft.com/mule-runtime/4.4/_attachments/secure-properties-tool.jar` +- Note: Maven (`mvn`) cannot be used here — this JAR is hosted on a documentation site, not a Maven repository + +## Step 4: Scan XML Files and Properties Files +Scan for sensitive data in two locations: + +#### A. Scan XML Files +Scan all XML files in `src/main/mule` (including subdirectories) for sensitive attributes: + +**Patterns to detect (case-insensitive)**: +- `password`, `passwd`, `pwd` +- `secret`, `apikey`, `api-key`, `api_key` +- `token`, `auth`, `credential` +- `username`, `user`, `login` +- `url`, `uri`, `host`, `endpoint` +- `clientId`, `client-id`, `client_id` +- `clientSecret`, `client-secret`, `client_secret` +- `key`, `private`, `certificate` + +**Important**: Flag attributes that: +1. Match one of the patterns above +2. Have a non-empty value +3. Are NOT already using secure property placeholders (don't start with `${secure::`) +4. **Include attributes using property placeholders** (like `${email.password}` or `${db.username}`) - these need to be converted to `${secure::}` format + +#### B. Scan Properties/YAML Files +- Scan `src/main/resources` directory (including subdirectories) for existing `.properties` and `.yaml`/`.yml` files +- For each file found, check if it contains sensitive data using the same patterns above +- **Track property names** that contain sensitive values (e.g., `email.password=secret` → track `email.password`) +- These values will need to be encrypted and moved to `.secure.properties` files + +## Step 5: Display Findings +Show a summary of all sensitive data found: +- **XML files**: List each file with sensitive attributes (hardcoded values or property placeholders) +- **Properties files**: List files containing sensitive properties with their property names +- Show the attribute/property names (but NOT the values for security) +- Provide a count of total items found + +If no sensitive data is found, inform the user and exit. + +## Step 6: Get User Confirmation +Before making ANY changes, show the user: +- What files will be modified +- What actions will be taken (update pom.xml, create secure properties, encrypt values, update XML files, create/update global.xml) +- Number of values that will be encrypted using the secure-properties-tool.jar + +If user says no, stop immediately. + +## Step 7: Determine Property Keys +For each sensitive value found, determine the property key name: + +#### A. For values already in properties files: +- **Use the existing property name** from the properties file +- Example: If `local.properties` contains `email.password=secret`, use `email.password` +- This ensures XML references like `${email.password}` will match after conversion to `${secure::email.password}` + +#### B. For hardcoded values in XML: +Generate a contextual property key name based on: + +1. **Config/connector type**: Extract from XML element or parent element + - `` → `mysql` + - `` → `http` + - `` → `salesforce` + - `` → `mongodb` + - `` → `ftp` + +2. **Attribute name**: Use the actual attribute name + - `password` → `password` + - `username` → `username` + - `url` → `url` + - `clientId` → `clientId` + +3. **Config name attribute** (if available): Use the `name` or `doc:name` attribute value + - `` → use `MySQL_Config` + +**Property key format**: `{connector}.{config-name}.{attribute}` or `{connector}.{attribute}` + +**Examples**: +- MongoDB password: `mongodb.password` or `mongodb.MongoDB_Config.password` +- MySQL username: `mysql.username` or `mysql.Database_Config.username` +- HTTP API key: `http.apikey` or `http.API_Config.apikey` +- Salesforce client secret: `salesforce.clientSecret` + +If the same property key would be generated multiple times, append a number: `mongodb.password.1`, `mongodb.password.2` + +## Step 8: Encrypt Values +After user confirmation, batch encrypt all unique sensitive values: +- Collect all unique sensitive values that need encryption +- For each value, run the encryption command without prompting: + ```bash + java -cp {skill_base_directory}/assets/secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool string encrypt + ``` +- Store each encrypted value with its generated property key +- Execute all encryption commands in sequence without asking for additional permission + +## Step 9: Create/Update Properties Files + +**Secure Properties File** (`src/main/resources/local.secure.properties`): +- Check if file exists +- If exists: append new encrypted properties +- If not: create the file and directory structure +- Format: `property.key=![encrypted_value]` + +**Backup Properties File** (`src/main/resources/local.properties`) - *Optional*: +- Only create if user chose to backup original values +- Write unencrypted property values for reference +- Format: `property.key=original_value` +- Add warning comment at top of file: + ```text + # WARNING: This file contains unencrypted sensitive values for reference only + # DO NOT commit this file to version control + # Add this file to .gitignore + ``` + +## Step 10: Update XML Files +For each XML file with sensitive data, perform two types of updates: + +#### A. Replace hardcoded values with secure property placeholders: +- Replace each hardcoded sensitive value with `${secure::property.key.name}` + +Example: +```xml + + + + + + + + + +``` + +#### B. Update existing property placeholders to use secure:: prefix: +- If XML already uses property placeholders like `${email.password}`, update them to `${secure::email.password}` +- **IMPORTANT**: Only update placeholders for properties that were encrypted (moved to `.secure.properties`) + +Example: +```xml + + + + + + + +``` + +Write the updated XML back to disk after making all changes. + +## Step 11: Create/Update global.xml +Check if `src/main/mule/global.xml` exists: + +**If it exists**: +- Read the file and check if secure-properties configuration already exists +- If not present, inform the user they need to add this configuration manually: + +```xml + + + +``` + +**If it doesn't exist**: +- Create a new `global.xml` file with the proper Mule XML structure +- Include the secure-properties namespace and configuration +- Add the secure properties config element + +Template: +```xml + + + + + + + + +``` + +## Step 12: Update pom.xml with Secure Properties Dependency +- Read the `pom.xml` file in the project root +- Check if the `mule-secure-configuration-property-module` dependency already exists +- If not present, add it to the `` section: + ```xml + + com.mulesoft.modules + mule-secure-configuration-property-module + 1.3.0 + mule-plugin + + ``` +- If the dependency already exists, inform the user and skip this step + +## Step 13: Update launch.json with Encryption Key +- Check if `.vscode/launch.json` exists in the project root +- If it exists: + - Read the file + - Find the configuration(s) for running the Mule application + - Look for the `mule.runtime.args` field in each configuration + - If `mule.runtime.args` exists, append `-M-Dencryption.key=` to the existing value + - If `mule.runtime.args` doesn't exist, add it with the value `-M-Dencryption.key=` + - Write the updated launch.json back to disk + - **Check .gitignore**: Ensure `.vscode/` or `.vscode/launch.json` is in `.gitignore` + - If `.gitignore` exists, check if it contains `.vscode/` or `.vscode/launch.json` + - If neither pattern is found, add `.vscode/` to `.gitignore` + - If `.gitignore` doesn't exist, create it and add `.vscode/` +- If it doesn't exist, inform the user they need to manually add the encryption key to their run configuration: + ``` + Add to VM arguments: + -M-Dencryption.key= + + Or set as environment variable: + export ENCRYPTION_KEY= + ``` + +## Step 14: Protect Existing Properties/YAML Files in .gitignore +- For each properties/YAML file that contained sensitive data (identified in Step 4): + - Add the file to `.gitignore` to prevent committing sensitive data + - This includes files like `local.properties`, `dev.properties`, etc. + +## Step 15: Final Summary +Provide a completion summary: +- ✅ Number of XML files scanned +- ✅ Number of properties files scanned +- ✅ Number of sensitive values encrypted +- ✅ Secure properties file created/updated (e.g., `local.secure.properties`) +- ✅ XML files updated: + - Hardcoded values replaced with `${secure::}` placeholders + - Existing property references updated from `${property}` to `${secure::property}` +- ✅ global.xml configured with secure properties +- ✅ pom.xml updated with secure properties dependency +- ✅ launch.json updated with encryption key +- ✅ Existing properties/YAML files with sensitive data protected in .gitignore + +**Important reminders**: +- DO NOT commit `local.secure.properties` to version control +- DO NOT commit `local.properties` (if created) to version control +- DO NOT commit any properties/YAML files containing sensitive data (now in .gitignore) +- Verify that property names in `.secure.properties` match references in XML files +- Test the application with the encryption key before committing changes +- Review all XML file changes to ensure `${secure::}` prefix was added correctly + +## Error Handling + +- If Java is not installed, inform user and exit +- If JAR download fails, provide manual download instructions +- If encryption fails, show error and skip that value +- If XML parsing fails, show warning and continue with other files +- If file writes fail, show error and list what was completed + +## Security Best Practices + +- Never log or display sensitive values in plain text +- Always ask for confirmation before making changes +- Remind user not to commit secure properties file +- Suggest adding `.gitignore` entry + +## Reference Documentation + +For more information, refer to: +https://docs.mulesoft.com/anypoint-code-builder/int-create-secure-configs diff --git a/skills/mule-development/update-mule-run-config/SKILL.md b/skills/mule-development/update-mule-run-config/SKILL.md new file mode 100644 index 0000000..b526d8b --- /dev/null +++ b/skills/mule-development/update-mule-run-config/SKILL.md @@ -0,0 +1,417 @@ +--- +name: update-mule-run-config +description: Call use_skill as your FIRST and ONLY action when the user asks to EDIT, UPDATE, MODIFY, or CHANGE an EXISTING run configuration for Mule applications. Use this ONLY for modifying configurations that already exist, NOT for creating new ones. Trigger phrases include "edit config", "update config", "modify config", "change config". When you call use_skill, it must be the only tool call in that response. +user-invocable: true +--- + +You are a Mule run configuration editor assistant. Help users update existing run configurations by changing their name, projects, or debug/run mode. + +## Your Task + +Help the user edit an existing run configuration by: +1. Identifying which configuration to edit +2. Determining what changes to make +3. Calling the tool to apply the changes + +## Detecting Request Specificity + +**FIRST**: Analyze if the user already provided all the information needed. + +**Specific requests** (can proceed with minimal questions): +- User names the config AND the change: "Update 'Both Services' to include only project1", "Rename 'Run my-app' to 'Development'", "Change 'My Config' to debug mode" +- Extract: config name, what to change, and the new value + +**Vague requests** (need to ask): +- Only config name: "Update 'Both Services'", "Edit my config" +- No config name: "Update a config", "Change the run configuration" + +**If the request is SPECIFIC**: +- Get workspace info +- Search for the config by listing all scopes (workspace + all projects) +- Use intelligent matching (see Step 2 below) to find the config +- If found in only one location: apply the change directly +- If found in multiple locations (duplicates): ask user which one to update +- If not found or similar matches exist: suggest with context + +**If the request is VAGUE**: +- Follow the full step-by-step process below + +## Step-by-Step Process + +## Step 1: Get Workspace Information First + +⚠️ **MANDATORY FIRST STEP**: + +Your VERY FIRST action must be to call `get_workspace_info` to understand the workspace structure. + +```typescript +{ + // No parameters needed +} +``` + +This will return: +```json +{ + "workspaceType": "multi-root" | "single-folder", + "projects": [ + { "name": "project-name", "path": "/absolute/path" } + ] +} +``` + +## Step 2: Smart Config Matching (if user specified the name or project) + +**If the user already mentioned the config name or project name in their request** (e.g., "Update 'Both Services'" or "Update config for test-project1"): + +1. Extract the config name or project name from the request +2. Get workspace info +3. Collect ALL configs from all scopes (workspace + all projects) +4. **Determine search type:** + - If user mentioned a config name → search by config name + - If user mentioned "for " → search by project name in config's `mule.projects` +5. Find best match using intelligent similarity: + + **Case 1: Single exact match** (case-sensitive or case-insensitive) + - For config name search: exact name match + - For project search: config's projects list contains the project name + - Use it immediately and proceed to step 5 + + **Case 2: Multiple exact matches** (duplicates) + - For config name search: multiple configs with same name + - For project search: multiple configs contain the project + - Show ALL matches with context: + ```text + Found 3 configurations for "test-project1": + 1. Run my-app - Single project (test-project1) - run mode + 2. Debug my-app - Single project (test-project1) - debug mode + 3. Both Services - Multiple projects (test-project1, test-project2) - run mode + + Which one do you want to update? + ``` + - Wait for user to select, then proceed to step 5 + + **Case 3: High similarity match** (typos, extra spaces, similar words) + - Use Levenshtein distance or similar algorithm + - For config name search: similar config names + - For project search: similar project names in workspace + - Examples that should match: + - "my custom config" ↔ "myy custom config" (typo) + - "My custom configuration" ↔ "my custom config" (similar words) + - "Both Services" ↔ "both services" (case difference) + - "test-project-1" ↔ "test-project1" (similar project name) + - If best match has high confidence (>80% similarity): suggest it with context + ```text + Configuration "My custoom config" not found. Did you mean: + "My custom config" - Multiple projects (api-gateway, backend) - run mode + ``` + - Wait for confirmation, then proceed to step 5 + + **Case 4: Multiple similar matches** + - Show top 3 matches with similarity scores and context + - Ask user to pick, then proceed to step 5 + + **Case 5: No good matches** + - List all configs and ask user to select + +5. Once config is identified, proceed directly to step 5 (apply changes) + +**If the user did NOT mention a config name**: +- Proceed to step 3 to ask about scope + +## Step 3: Ask About Scope (Only if needed) + +**If workspaceType is "multi-root"** and you haven't found the config yet: + +Ask the user: +```text +Is this configuration for: +1. Multiple projects +2. A single specific project +``` + +**STOP and wait for their answer.** + +**IMPORTANT**: Do NOT mention "workspace-level" or "project-level" to the user. These are internal technical terms. + +**If workspaceType is "single-folder"**: + +Skip to listing with scope "project" and use that single project's path. + +## Step 4: List the Configurations + +**If user chose "Multiple projects"** (multi-root workspace only): +```typescript +{ + "operation": "list", + "scope": "workspace", + "excludeDefaults": true +} +``` + +**If user chose "Single project"** (multi-root only): +- Ask which project (show the projects list from step 1) +- Call the list tool with that project's path: +```typescript +{ + "operation": "list", + "scope": "project", + "projectPath": "", + "excludeDefaults": true +} +``` + +**If single-folder workspace**: +- Use the project path from step 1: +```typescript +{ + "operation": "list", + "scope": "project", + "projectPath": "", + "excludeDefaults": true +} +``` + +Show the returned list to the user and ask which configuration they want to edit. + +**IMPORTANT**: For workspace-level configs, the list shows projects in format: `ConfigName (mode) - projects: [project1, project2]` +- Compare the projects in each config with current workspace projects (from step 1) +- If a config references projects that no longer exist, mention this to the user +- Example: "Note: 'Run Multiple Projects' has 5 projects but only 3 are in your current workspace" + +**If no configurations are found** (list returns empty or "No run configurations found"): +- Inform the user that there are no custom run configurations to edit +- Suggest creating a new configuration instead +- **DO NOT** retry the list operation with `excludeDefaults: false` +- Default configurations ("Run Mule Application", "Debug Mule Application") cannot be edited, so showing them would only confuse the user + +## Step 5: Determine What to Change + +Ask the user what they want to update. Options: +- **Name**: Rename the configuration +- **Projects**: Change which projects are included +- **Mode**: Switch between run and debug mode +- **Multiple changes**: Can change any combination of the above + +**Important**: Only ask about changes the user wants to make. Don't force them to specify everything. + +## Step 6: Collect New Values + +For each property the user wants to change: + +**If renaming:** +- Get the new name from the user + +**If changing projects:** +- Show available workspace projects +- Let user specify which projects to include (full replacement, not additive) +- Use absolute paths from `workspaceFolder.uri.fsPath` + +**If changing mode:** +- Ask if it should be run mode (noDebug: true) or debug mode (noDebug: false) + +## Step 7: Call the Language Model Tool + +Execute the `manage_run_configuration` tool with operation "update": + +**For workspace-level config:** +```typescript +{ + "operation": "update", + "configName": string, // Required: current name of the configuration + "scope": "workspace", // Required: indicates workspace-level config + "newName": string, // Optional: new name if renaming + "projects": string[], // Optional: new projects list (absolute paths) + "noDebug": boolean // Optional: new mode (true = run, false = debug) +} +``` + +**For project-level config:** +```typescript +{ + "operation": "update", + "configName": string, // Required: current name of the configuration + "scope": "project", // Required: indicates project-level config + "projectPath": string, // Required: absolute path to the project + "newName": string, // Optional: new name if renaming + "projects": string[], // Optional: new projects list (absolute paths) + "noDebug": boolean // Optional: new mode (true = run, false = debug) +} +``` + +**Important**: +- Always include `scope` to specify where the config is located +- Include `projectPath` when scope is "project" +- Only include properties that should be changed (newName, projects, noDebug). Omit properties that should stay the same. + +## Step 8: Inform the User and Offer to Run + +After calling the tool, the tool will return a success message with the ACTUAL configuration name (which may have changed if you renamed it). + +**CRITICAL**: If you renamed the config, the update operation returns the NEW name. You MUST use that EXACT new name when running. + +Share the result with the user and ask if they want to run it: +```text +✓ Successfully updated run configuration '' + +Would you like to run this configuration now? +``` + +If the user says yes, call the tool again with operation "execute". **Use the EXACT name from the update response**, and the same scope and projectPath you used for listing: + +**If workspace-level config:** +```typescript +{ + "operation": "execute", + "configName": "", + "scope": "workspace" +} +``` + +**If project-level config:** +```typescript +{ + "operation": "execute", + "configName": "", + "scope": "project", + "projectPath": "" +} +``` + +## Important Notes + +- **Use the EXACT name returned after updating** - If the update operation returns a renamed config like "Run my-app (2)", you MUST use that exact name (with the number) when offering to run it. Do NOT use the original name. +- **ALWAYS provide scope when executing** - The execute operation REQUIRES the `scope` parameter. NEVER call execute without specifying "workspace" or "project" scope. +- **CRITICAL: NEVER run multiple projects individually** - Only ONE Mule runtime instance can be active at a time. To run multiple projects together, they MUST be in a single workspace-level configuration. NEVER attempt to run project-level configs sequentially or in parallel for multiple projects. + +## Example Conversations + +### Example 1: Exact match - direct update + +```text +User: "Rename 'Run my-app' to 'Run Development'" + +Assistant: [finds exact match in all scopes] + +"Renaming configuration... + +✓ Successfully updated run configuration 'Run Development' + +Would you like to run this configuration now?" +``` + +### Example 2: Multiple exact matches - disambiguation + +```text +User: "Update 'Both Services' to include only project1" + +Assistant: "Found 2 configurations named 'Both Services': +1. Multiple projects (api-gateway, backend) - run mode +2. Single project (test-app) - debug mode + +Which one do you want to update?" + +User: "1" + +Assistant: "Updating configuration... + +✓ Successfully updated run configuration 'Both Services' + +Would you like to run this configuration now?" +``` + +### Example 3: Specific request - change mode + +```text +User: "Change 'Run my-app' to debug mode" + + +Assistant: [gets workspace info, finds config] + +"Switching to debug mode... + +✓ Successfully updated run configuration 'Run my-app' + +Would you like to run this configuration now?" +``` + +### Example 4: High similarity match - suggest with context + +```text +User: "Update 'my custom confg' to debug mode" +Assistant: [gets workspace info, searches all scopes] + +"Configuration 'my custom confg' not found. Did you mean: +'My custom config' - Multiple projects (api-gateway, backend) - run mode + +Would you like to update this configuration?" + +User: "Yes" + +Assistant: "Switching to debug mode... + +✓ Successfully updated run configuration 'My custom config' + +Would you like to run this configuration now?" +``` + +### Example 5: Specific request - match by project name + +```text +User: "Update the config for test-project1 to debug mode" + +Assistant: [gets workspace info, searches all scopes for configs containing test-project1] + +"Found 2 configurations for test-project1: +1. Run my-app - Single project (test-project1) - run mode +2. Debug my-app - Single project (test-project1) - debug mode + +Which one do you want to update?" + +User: "1" + +Assistant: "Switching to debug mode... + +✓ Successfully updated run configuration 'Run my-app' + +Would you like to run this configuration now?" +``` + +### Example 6: Vague request - full flow + +```text +User: "Update a config" + +Assistant: "Is this configuration for: +1. Multiple projects +2. A single specific project" + +User: "Single project" + +Assistant: "Which project would you like to edit configurations for? +1. api-gateway (/path/to/api-gateway) +2. backend (/path/to/backend)" + +User: "api-gateway" + +Assistant: [lists configs] "Found 2 run configurations: +1. Run api-gateway (run mode) +2. Debug api-gateway (debug mode) + +Which configuration would you like to edit?" + +User: "1" + +Assistant: "What would you like to update? +- Name +- Projects +- Mode (run/debug)" + +User: "Rename it to 'Development Config'" + +Assistant: "Renaming configuration... + +✓ Successfully updated run configuration 'Development Config' + +Would you like to run this configuration now?" +```