@raishin/vanguard-frontier-agentic 2.2.0 → 2.5.0

package/skills/salesforce/salesforce-apex-log-analyzer-skill/metadata.json

@@ -0,0 +1,38 @@
+{
+  "id": "salesforce-apex-log-analyzer-skill",
+  "name": "Salesforce Apex Log Analyzer Skill",
+  "type": "skill",
+  "provider": "salesforce",
+  "harnesses": ["claude-code", "codex", "cursor", "gemini", "kiro", "other"],
+  "summary": "Retrieves Apex debug logs from a connected Salesforce org and analyzes them for governor-limit hits, SOQL N+1 patterns, unhandled exceptions, CPU hotspots, and async job failures. T1 read-only runtime — retrieves logs only, never executes code or mutates data. Does NOT require View All Data (unlike test runner). Emits sanitized findings with root-cause traces and a structured audit envelope.",
+  "source_type": "adapted",
+  "source_attribution": "Adapted from forcedotcom/sf-skills debugging-apex-logs (Apache-2.0). Vanguard-specific additions: T1 tier declaration, structured audit envelope, PII redaction rules, No View All Data distinction vs test-runner-skill, and handoff routing model.",
+  "category": "operational",
+  "execution_tier": "read-only-runtime",
+  "oauth_scopes": ["api", "refresh_token"],
+  "mcp_servers": [],
+  "run_as_permissions": {
+    "required": ["View Setup and Configuration"],
+    "denied": [
+      "ModifyAllData",
+      "ViewAllData",
+      "ViewEncryptedData",
+      "ModifyMetadata",
+      "AuthorApex",
+      "ManageConnectedApps"
+    ]
+  },
+  "sandbox_only": false,
+  "production_allowed": true,
+  "official_docs": [
+    "https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_apex_commands_unified.htm#cli_reference_apex_get_log_unified",
+    "https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_debugging_debug_log.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_gov_limits.htm",
+    "https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_debugging_log_levels.htm"
+  ],
+  "security_notes": "T1 read-only runtime. Log retrieval only — no code execution, no DML, no metadata mutation. Does not require View All Data (unlike salesforce-apex-test-runner-skill). OAuth scopes restricted to api + refresh_token. Apex debug logs may contain field values and PII; mandatory redaction of record IDs, user IDs, email addresses, and other PII fields before output. Session tokens and access tokens stripped from any log content. Structured audit envelope with pii_risk_assessed and redactions_applied fields emitted on every execution. Production org logs permitted but trigger maximum PII redaction scrutiny. Rotating the Run As account's refresh token immediately revokes all access.",
+  "last_verified": "2026-05-21",
+  "path": "skills/salesforce/salesforce-apex-log-analyzer-skill",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/salesforce/salesforce-apex-log-analyzer-skill/references/governor-limit-signatures.md

@@ -0,0 +1,174 @@
+# Governor Limit Signatures and Remediation Reference
+
+Adapted from forcedotcom/sf-skills debugging-apex-logs references (Apache-2.0).
+
+## How to Find Limit Hits in a Log
+
+Search for these patterns in log output:
+
+```bash
+# Find all limit-related entries
+grep -i "LIMIT_USAGE\|LimitException\|FATAL_ERROR" apex-debug.log
+
+# Find SOQL count entries
+grep "Number of SOQL" apex-debug.log
+
+# Find the fatal error line
+grep -A 10 "FATAL_ERROR" apex-debug.log
+```
+
+---
+
+## SOQL Query Limit (100 sync / 200 async)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Number of SOQL queries: 101 out of 100
+FATAL_ERROR|System.LimitException: Too many SOQL queries: 101
+Class.AccountSelector.getAccountsByOwnerIds: line 12, column 1
+Class.AccountService.processOwnerChange: line 34, column 1
+Trigger.AccountTrigger: line 8, column 1
+```
+
+**Diagnosis:** SOQL inside a loop. Stack trace points to the SOQL call site.
+Count the `SOQL_EXECUTE_BEGIN` entries — if N entries exist for the same query
+text with the same calling class/method, the query is in a loop.
+
+**Remediation:**
+```apex
+// Before: SOQL in loop
+for (Opportunity opp : opps) {
+    Account acc = [SELECT Id FROM Account WHERE Id = :opp.AccountId];
+}
+
+// After: collect IDs, single SOQL, Map lookup
+Set<Id> accIds = new Set<Id>;
+for (Opportunity opp : opps) { accIds.add(opp.AccountId); }
+Map<Id, Account> accMap = new Map<Id, Account>([SELECT Id FROM Account WHERE Id IN :accIds]);
+for (Opportunity opp : opps) {
+    Account acc = accMap.get(opp.AccountId);
+}
+```
+
+---
+
+## DML Statement Limit (150)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Number of DML statements: 151 out of 150
+FATAL_ERROR|System.LimitException: Too many DML statements: 151
+```
+
+**Diagnosis:** DML (`insert`, `update`, `delete`) inside a loop.
+Count `DML_BEGIN` entries with `Rows:1` — if many exist for the same object type,
+DML is in a loop.
+
+**Remediation:** Collect all records in a List before the loop, then DML the full list
+outside the loop.
+
+---
+
+## CPU Time Limit (10,000ms sync / 60,000ms async)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|CPU time (ms): 10001 out of 10000
+FATAL_ERROR|System.LimitException: Apex CPU time limit exceeded
+```
+
+**Diagnosis:** Identify CPU hotspots from cumulative elapsed time between METHOD_ENTRY
+and METHOD_EXIT. Common causes:
+- Nested loops over large collections
+- String concatenation in loops (use `String.join`)
+- Excessive `JSON.serialize` on large object graphs
+- Regex operations on large strings
+- Recursive trigger logic with deep call stacks
+
+**Remediation:**
+- Replace string concatenation loops with `List<String>` + `String.join`
+- Break nested loops into Map lookups
+- Move heavy computation to Batch/Queueable async context
+- Cache `JSON.serialize` results if called repeatedly
+
+---
+
+## Heap Size Limit (6MB sync / 12MB async)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Maximum heap size (MB): 6.1 out of 6
+FATAL_ERROR|System.LimitException: Apex heap size too large: 6291457
+```
+
+**Diagnosis:** Look for large collection allocations. Common causes:
+- Querying all records without LIMIT (large result set held in memory)
+- Accumulating records into a List in `Database.Stateful` batch without clearing
+- Large string buffers
+- Nested object graphs from `JSON.deserialize`
+
+**Remediation:**
+- Add `LIMIT` to queries and chunk processing
+- Clear intermediate collections when no longer needed (`myList.clear`)
+- Process in smaller batches in Batch Apex
+- Avoid retaining full query result sets in instance variables across DML operations
+
+---
+
+## SOQL Row Limit (50,000)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Number of query rows: 50001 out of 50000
+FATAL_ERROR|System.QueryException: Too many query rows: 50001
+```
+
+**Diagnosis:** Query returns too many rows. Usually a missing or insufficient WHERE clause.
+
+**Remediation:**
+- Add selective WHERE clause with indexed fields
+- Add LIMIT for interactive/UI contexts
+- Use Batch Apex with `Database.QueryLocator` for bulk processing — Batch bypasses the
+  50,000 row query limit
+
+---
+
+## DML Row Limit (10,000)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Number of DML rows: 10001 out of 10000
+FATAL_ERROR|System.LimitException: Too many DML rows: 10001
+```
+
+**Remediation:** Use Batch Apex to process records in chunks of ≤ 2,000 DML rows per
+execute call. Default batch size of 200 stays well within limit.
+
+---
+
+## Callout Limit (100)
+
+**Log signature:**
+```
+LIMIT_USAGE_FOR_NS|(default)|Number of callouts: 101 out of 100
+FATAL_ERROR|System.LimitException: Too many callouts: 101
+```
+
+**Diagnosis:** HTTP/SOAP callouts inside a loop. Check `CALLOUT_REQUEST` entries.
+
+**Remediation:**
+- Batch API calls into a single request where the external API supports it
+- Queue individual records and process in Queueable with a single bulk callout
+
+---
+
+## Near-Limit Warnings (75% threshold)
+
+Even without a `FATAL_ERROR`, warn when `LIMIT_USAGE_FOR_NS` shows:
+- SOQL queries > 75 (sync) or > 150 (async)
+- DML statements > 112 (sync)
+- CPU time > 7,500ms (sync)
+- Heap > 4.5MB (sync)
+
+These near-limit conditions are not failures today but are risks for future growth
+as data volume increases.

package/skills/salesforce/salesforce-apex-log-analyzer-skill/references/log-format-reference.md

@@ -0,0 +1,154 @@
+# Apex Debug Log Format Reference
+
+Adapted from forcedotcom/sf-skills debugging-apex-logs references (Apache-2.0).
+
+## Log Line Structure
+
+Every log line follows this format:
+
+```
+HH:MM:SS.mmm (elapsed_ms)|LOG_CATEGORY|description
+```
+
+Example:
+```
+12:34:56.123 (123456789)|SOQL_EXECUTE_BEGIN|[45]|Rows:50|SELECT Id, Name FROM Account WHERE OwnerId = :ownerId
+```
+
+- `HH:MM:SS.mmm` — wall clock time
+- `(elapsed_ms)` — nanoseconds since transaction start (used for performance timing)
+- `LOG_CATEGORY` — the event type
+- `description` — category-specific content
+
+---
+
+## Key Log Categories
+
+### Execution Entry Points
+
+| Category | Description |
+|---|---|
+| `EXECUTION_STARTED` | Transaction begins |
+| `EXECUTION_FINISHED` | Transaction ends |
+| `CODE_UNIT_STARTED` | A class/trigger/process starts executing |
+| `CODE_UNIT_FINISHED` | A class/trigger/process finishes |
+| `ENTERING_MANAGED_PKG` | Execution enters a managed package namespace |
+
+### Method Tracking
+
+| Category | Description |
+|---|---|
+| `METHOD_ENTRY` | Entering a method; shows `[lineNum]|namespace.ClassName.methodName` |
+| `METHOD_EXIT` | Exiting a method |
+| `CONSTRUCTOR_ENTRY` | Entering a constructor |
+| `CONSTRUCTOR_EXIT` | Exiting a constructor |
+
+### SOQL
+
+| Category | Description |
+|---|---|
+| `SOQL_EXECUTE_BEGIN` | SOQL query begins; shows `[lineNum]\|Rows:N\|<query text>` |
+| `SOQL_EXECUTE_END` | SOQL query ends; shows row count returned |
+
+**N+1 pattern signature:** Multiple `SOQL_EXECUTE_BEGIN` entries with the same query
+pattern appear sequentially, often interleaved with `METHOD_ENTRY`/`METHOD_EXIT` for
+the same method — indicates a loop calling SOQL.
+
+### DML
+
+| Category | Description |
+|---|---|
+| `DML_BEGIN` | DML operation begins; shows `[lineNum]\|Op:Insert\|Type:Account\|Rows:N` |
+| `DML_END` | DML operation ends |
+
+**DML in loop signature:** Multiple `DML_BEGIN` entries with `Rows:1` for the same
+object type appearing in rapid succession, with loop method frames on the stack.
+
+### Governor Limits
+
+| Category | Description |
+|---|---|
+| `LIMIT_USAGE_FOR_NS` | Snapshot of limit consumption at transaction end or limit breach |
+
+Example entry:
+```
+LIMIT_USAGE_FOR_NS|(default)|
+  Number of SOQL queries: 101 out of 100
+  Number of query rows: 4523 out of 50000
+  Number of DML statements: 23 out of 150
+  Number of DML rows: 4500 out of 10000
+  CPU time (ms): 8234 out of 10000
+  Maximum heap size (MB): 3.2 out of 6
+```
+
+**Hard limit breach signature:** `LIMIT_USAGE_FOR_NS` showing a value equal to or
+exceeding the limit, followed by `FATAL_ERROR` with `LimitException`.
+
+### Exceptions
+
+| Category | Description |
+|---|---|
+| `EXCEPTION_THROWN` | Exception instantiated; shows type and message |
+| `FATAL_ERROR` | Unhandled exception; transaction will roll back; shows full stack trace |
+
+Example:
+```
+12:34:56.789 (789456123)|FATAL_ERROR|System.LimitException: Too many SOQL queries: 101
+Class.AccountSelector.getAccountsByOwnerIds: line 12, column 1
+Class.AccountService.processOwnerChange: line 34, column 1
+Trigger.AccountTrigger: line 8, column 1
+```
+
+### User Debug
+
+| Category | Description |
+|---|---|
+| `USER_DEBUG` | `System.debug` output; shows `[lineNum]\|DEBUG\|<message>` |
+
+**Caution:** USER_DEBUG lines may contain field values, record IDs, or PII if
+`System.debug` serializes SObjects. Apply redaction to these lines.
+
+### Callouts
+
+| Category | Description |
+|---|---|
+| `CALLOUT_REQUEST` | Outbound HTTP request begins; shows URL and method |
+| `CALLOUT_RESPONSE` | Outbound HTTP response returns; shows status code |
+
+### Async
+
+| Category | Description |
+|---|---|
+| `FUTURE_CALL_PROCESS` | Future method queued |
+| `SCHEDULED_PROCESS_STARTING` | Scheduled job begins executing |
+| `BATCH_PROCESS_STARTED` | Batch execute begins |
+
+---
+
+## Log Levels
+
+Set via Developer Console or `sf apex tail log`. Higher log levels produce more verbose
+output but consume log size limit faster.
+
+| Level | What it captures |
+|---|---|
+| `NONE` | Nothing |
+| `ERROR` | Fatal errors only |
+| `WARN` | Errors + warnings |
+| `INFO` | + method boundaries |
+| `DEBUG` | + USER_DEBUG output |
+| `FINE` | + method entry/exit |
+| `FINER` | + constructor tracking |
+| `FINEST` | + all SOQL/DML details |
+
+**Recommended for diagnosis:** `APEX_CODE=FINEST, APEX_PROFILING=INFO, DB=FINEST`
+
+---
+
+## Log Size Limit
+
+Apex debug logs are capped at **20 MB**. Logs exceeding this limit are truncated with
+a `*** Skipped N bytes of detailed log ***` entry. When analyzing truncated logs:
+- Focus on the end of the log (where the exception or limit hit occurred)
+- Reduce log level for categories not relevant to the issue
+- Use `sf apex tail log` for streaming analysis of in-progress transactions

package/skills/salesforce/salesforce-apex-log-analyzer-skill/references/redaction-rules.md

@@ -0,0 +1,178 @@
+# Log Redaction Rules Reference
+
+## Purpose
+
+Apex debug logs frequently contain sensitive data: record IDs, user IDs, field values
+including PII, and occasionally session tokens that appear in `USER_DEBUG` output.
+This reference defines the mandatory redaction patterns to apply before emitting any
+log content in skill output.
+
+---
+
+## Redaction Priority Order
+
+Apply in this order. Each rule is additive — apply all rules, not just the first match.
+
+### Rule 1 — OAuth and Session Tokens
+
+**Pattern:** Any string matching OAuth access token, refresh token, or session ID format.
+These typically appear in USER_DEBUG lines when developers inadvertently log request headers
+or authentication context.
+
+**Action:** Strip entirely. Do not replace with a placeholder — omit the line or replace
+the token value with `<token_redacted>`.
+
+```bash
+# Grep pattern to detect
+grep -i "access_token\|refresh_token\|Bearer\|Authorization\|sessionId" apex-debug.log
+```
+
+---
+
+### Rule 2 — Salesforce Org IDs
+
+**Pattern:** 18-character alphanumeric strings starting with `00D` (Org ID prefix).
+
+**Replacement:** `<org_id_placeholder>`
+
+```bash
+# Sed replacement
+sed 's/00D[a-zA-Z0-9]\{15\}/<org_id_placeholder>/g'
+```
+
+---
+
+### Rule 3 — Salesforce Record IDs
+
+**Pattern:** 15-character or 18-character Salesforce IDs. Common prefixes:
+- `001` — Account
+- `003` — Contact
+- `006` — Opportunity
+- `00Q` — Lead
+- `005` — User
+- `00e` — Profile
+- `01p` — ApexClass
+- `707` — TestRunResult
+
+**Replacement:** `<record_id_placeholder>`
+
+```bash
+# Match 18-char IDs (most common in logs)
+sed 's/[0-9A-Za-z]\{18\}/<record_id_placeholder>/g'
+
+# More targeted: match known prefix patterns
+sed 's/\b00[0-9A-Za-z]\{13\}\b/<record_id_placeholder>/g'
+```
+
+**Note:** 18-char ID replacement is aggressive and may match non-ID strings. Use the
+targeted prefix-based pattern when possible. When replacing, prefer targeted matching
+and review the output before emitting.
+
+---
+
+### Rule 4 — User IDs
+
+**Pattern:** IDs appearing in fields: `OwnerId`, `CreatedById`, `LastModifiedById`,
+`RunningUserId`, `User.Id`, or following the text `Running User`.
+
+**Replacement:** `<user_id_placeholder>`
+
+This is in addition to Rule 3 (which catches all record IDs). Rule 4 ensures user IDs
+are replaced even in descriptive text like `Running User: 005Xx000001ABCDEF`.
+
+---
+
+### Rule 5 — Email Addresses
+
+**Pattern:** Strings matching `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}`
+
+**Action:** Apply in production log analysis or when sensitivity classification is HIGH.
+Replace with `<email_placeholder>`.
+
+**When to apply:**
+- Always on regulated-vertical orgs (Health Cloud, Financial Services Cloud)
+- Always on production org logs
+- On sandbox logs unless the user has acknowledged PII scope
+
+---
+
+### Rule 6 — Phone Numbers
+
+**Pattern:** Common formats: `+1-555-555-5555`, `(555) 555-5555`, `5555555555`
+
+**Action:** Replace with `<phone_placeholder>` when appearing in USER_DEBUG output
+or DML_BEGIN field values.
+
+---
+
+### Rule 7 — SSNs and Financial Data
+
+**Pattern:** SSN: `\d{3}-\d{2}-\d{4}` or `\d{9}`. Financial account numbers are
+context-dependent.
+
+**Action:** Replace with `<pii_placeholder>`. Flag in `redactions_applied` with
+`reason: pii`.
+
+---
+
+### Rule 8 — Instance URLs
+
+**Pattern:** Strings matching `https://[a-zA-Z0-9-]+\.salesforce\.com` or
+`https://[a-zA-Z0-9-]+\.my\.salesforce\.com`
+
+**Action:** Replace with `<instance_url_placeholder>`. Reference only the org alias.
+
+---
+
+## jq Patterns for JSON Output Redaction
+
+When log retrieval returns JSON (from `sf apex get log --result-format json`):
+
+```bash
+# Redact record IDs from log body content
+sf apex get log --log-id <id> --target-org <alias> --result-format json \
+  | jq '.result.log' \
+  | sed 's/00[0-9A-Za-z]\{16\}/<record_id_placeholder>/g'
+
+# Extract only log category lines, omitting USER_DEBUG (which may contain field values)
+sf apex get log --log-id <id> --target-org <alias> \
+  | grep -v "USER_DEBUG" \
+  | grep "FATAL_ERROR\|LIMIT_USAGE\|SOQL_EXECUTE\|DML_BEGIN\|EXCEPTION_THROWN"
+```
+
+---
+
+## What NOT to Redact
+
+These items are needed for diagnosis and must NOT be redacted:
+
+- Class names and method names in stack traces
+- Line numbers
+- Log categories (`SOQL_EXECUTE_BEGIN`, `DML_BEGIN`, etc.)
+- Exception type names (`System.LimitException`, `System.QueryException`)
+- Governor limit values (`101 out of 100`) — the numbers, not any IDs embedded
+- SOQL query structure (but replace any literal ID bind values or string values)
+- CPU time and heap values
+
+---
+
+## Audit Logging of Redactions
+
+Every redaction applied must be recorded in the `redactions_applied` array in the
+audit envelope:
+
+```yaml
+redactions_applied:
+  - field_or_pattern: "record_ids (00D prefix)"
+    reason: "org_id"
+    count: 3
+  - field_or_pattern: "record_ids (001/003 prefix)"
+    reason: "record_id"
+    count: 47
+  - field_or_pattern: "email_address"
+    reason: "pii"
+    count: 2
+  - field_or_pattern: "USER_DEBUG lines omitted"
+    reason: "potential_pii"
+    count: 12
+```