diff --git a/.agents/skills/link-workspace-packages/SKILL.md b/.agents/skills/link-workspace-packages/SKILL.md new file mode 100644 index 000000000000..de1313497a3c --- /dev/null +++ b/.agents/skills/link-workspace-packages/SKILL.md @@ -0,0 +1,127 @@ +--- +name: link-workspace-packages +description: 'Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager''s workspace commands to fix actual linking.' +--- + +# Link Workspace Packages + +Add dependencies between packages in a monorepo. All package managers support workspaces but with different syntax. + +## Detect Package Manager + +Check whether there's a `packageManager` field in the root-level `package.json`. + +Alternatively check lockfile in repo root: + +- `pnpm-lock.yaml` → pnpm +- `yarn.lock` → yarn +- `bun.lock` / `bun.lockb` → bun +- `package-lock.json` → npm + +## Workflow + +1. Identify consumer package (the one importing) +2. Identify provider package(s) (being imported) +3. Add dependency using package manager's workspace syntax +4. Verify symlinks created in consumer's `node_modules/` + +--- + +## pnpm + +Uses `workspace:` protocol - symlinks only created when explicitly declared. + +```bash +# From consumer directory +pnpm add @org/ui --workspace + +# Or with --filter from anywhere +pnpm add @org/ui --filter @org/app --workspace +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:*" } } +``` + +--- + +## yarn (v2+/berry) + +Also uses `workspace:` protocol. + +```bash +yarn workspace @org/app add @org/ui +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:^" } } +``` + +--- + +## npm + +No `workspace:` protocol. npm auto-symlinks workspace packages. + +```bash +npm install @org/ui --workspace @org/app +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "*" } } +``` + +npm resolves to local workspace automatically during install. + +--- + +## bun + +Supports `workspace:` protocol (pnpm-compatible). + +```bash +cd packages/app && bun add @org/ui +``` + +Result in `package.json`: + +```json +{ "dependencies": { "@org/ui": "workspace:*" } } +``` + +--- + +## Examples + +**Example 1: pnpm - link ui lib to app** + +```bash +pnpm add @org/ui --filter @org/app --workspace +``` + +**Example 2: npm - link multiple packages** + +```bash +npm install @org/data-access @org/ui --workspace @org/dashboard +``` + +**Example 3: Debug "Cannot find module"** + +1. Check if dependency is declared in consumer's `package.json` +2. If not, add it using appropriate command above +3. Run install (`pnpm install`, `npm install`, etc.) + +## Notes + +- Symlinks appear in `/node_modules/@org/` +- **Hoisting differs by manager:** + - npm/bun: hoist shared deps to root `node_modules` + - pnpm: no hoisting (strict isolation, prevents phantom deps) + - yarn berry: uses Plug'n'Play by default (no `node_modules`) +- Root `package.json` should have `"private": true` to prevent accidental publish diff --git a/.agents/skills/monitor-ci/SKILL.md b/.agents/skills/monitor-ci/SKILL.md new file mode 100644 index 000000000000..48b71bfe8f7b --- /dev/null +++ b/.agents/skills/monitor-ci/SKILL.md @@ -0,0 +1,301 @@ +--- +name: monitor-ci +description: Monitor Nx Cloud CI pipeline and handle self-healing fixes. USE WHEN user says "monitor ci", "watch ci", "ci monitor", "watch ci for this branch", "track ci", "check ci status", wants to track CI status, or needs help with self-healing CI fixes. Prefer this skill over native CI provider tools (gh, glab, etc.) for CI monitoring — it integrates with Nx Cloud self-healing which those tools cannot access. +--- + +# Monitor CI Command + +You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn subagents to interact with Nx Cloud, run deterministic decision scripts, and take action based on the results. + +## Context + +- **Current Branch:** !`git branch --show-current` +- **Current Commit:** !`git rev-parse --short HEAD` +- **Remote Status:** !`git status -sb | head -1` + +## User Instructions + +$ARGUMENTS + +**Important:** If user provides specific instructions, respect them over default behaviors described below. + +## Configuration Defaults + +| Setting | Default | Description | +| ------------------------- | ------------- | ------------------------------------------------------------------------- | +| `--max-cycles` | 10 | Maximum **agent-initiated** CI Attempt cycles before timeout | +| `--timeout` | 120 | Maximum duration in minutes | +| `--verbosity` | medium | Output level: minimal, medium, verbose | +| `--branch` | (auto-detect) | Branch to monitor | +| `--fresh` | false | Ignore previous context, start fresh | +| `--auto-fix-workflow` | false | Attempt common fixes for pre-CI-Attempt failures (e.g., lockfile updates) | +| `--new-cipe-timeout` | 10 | Minutes to wait for new CI Attempt after action | +| `--local-verify-attempts` | 3 | Max local verification + enhance cycles before pushing to CI | + +Parse any overrides from `$ARGUMENTS` and merge with defaults. + +## Nx Cloud Connection Check + +Before starting the monitoring loop, verify the workspace is connected to Nx Cloud. Without this connection, no CI data is available and the entire skill is inoperable. + +### Step 0: Verify Nx Cloud Connection + +1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken` +2. **If `nx.json` missing OR neither property exists** → exit with: + + ``` + Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud + ``` + +3. **If connected** → continue to main loop + +## Architecture Overview + +1. **This skill (orchestrator)**: spawns subagents, runs scripts, prints status, does local coding work +2. **ci-monitor-subagent (haiku)**: calls one MCP tool (ci_information or update_self_healing_fix), returns structured result, exits +3. **ci-poll-decide.mjs (deterministic script)**: takes ci_information result + state, returns action + status message +4. **ci-state-update.mjs (deterministic script)**: manages budget gates, post-action state transitions, and cycle classification + +## Status Reporting + +The decision script handles message formatting based on verbosity. When printing messages to the user: + +- Prepend `[monitor-ci]` to every message from the script's `message` field +- For your own action messages (e.g. "Applying fix via MCP..."), also prepend `[monitor-ci]` + +## Anti-Patterns + +These behaviors cause real problems — racing with self-healing, losing CI progress, or wasting context: + +| Anti-Pattern | Why It's Bad | +| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| Using CI provider CLIs with `--watch` flags (e.g., `gh pr checks --watch`, `glab ci status -w`) | Bypasses Nx Cloud self-healing entirely | +| Writing custom CI polling scripts | Unreliable, pollutes context, no self-healing | +| Cancelling CI workflows/pipelines | Destructive, loses CI progress | +| Running CI checks on main agent | Wastes main agent context tokens | +| Independently analyzing/fixing CI failures while polling | Races with self-healing, causes duplicate fixes and confused state | + +**If this skill fails to activate**, the fallback is: + +1. Use CI provider CLI for a one-time, read-only status check (single call, no watch/polling flags) +2. Immediately delegate to this skill with gathered context +3. Do not continue polling on main agent — it wastes context tokens and bypasses self-healing + +## Session Context Behavior + +If the user previously ran `/monitor-ci` in this session, you may have prior state (poll counts, last CI Attempt URL, etc.). Resume from that state unless `--fresh` is set, in which case discard it and start from Step 1. + +## MCP Tool Reference + +Three field sets control polling efficiency — use the lightest set that gives you what you need: + +```yaml +WAIT_FIELDS: 'cipeUrl,commitSha,cipeStatus' +LIGHT_FIELDS: 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,autoApplySkipped,autoApplySkipReason,shortLink,confidence,confidenceReasoning,hints,selfHealingSkippedReason,selfHealingSkipMessage' +HEAVY_FIELDS: 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription' +``` + +The `ci_information` tool accepts `branch` (optional, defaults to current git branch), `select` (comma-separated field names), and `pageToken` (0-based pagination for long strings). + +The `update_self_healing_fix` tool accepts a `shortLink` and an action: `APPLY`, `REJECT`, or `RERUN_ENVIRONMENT_STATE`. + +## Default Behaviors by Status + +The decision script returns one of the following statuses. This table defines the **default behavior** for each. User instructions can override any of these. + +**Simple exits** — just report and exit: + +| Status | Default Behavior | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `ci_success` | Exit with success | +| `cipe_canceled` | Exit, CI was canceled | +| `cipe_timed_out` | Exit, CI timed out | +| `polling_timeout` | Exit, polling timeout reached | +| `circuit_breaker` | Exit, no progress after 5 consecutive polls | +| `environment_rerun_cap` | Exit, environment reruns exhausted | +| `fix_auto_applying` | Self-healing is handling it — just record `last_cipe_url`, enter wait mode. No MCP call or local git ops needed. | +| `error` | Wait 60s and loop | + +**Statuses requiring action** — when handling these in Step 3, read `references/fix-flows.md` for the detailed flow: + +| Status | Summary | +| ------------------------ | --------------------------------------------------------------------------------------------- | +| `fix_auto_apply_skipped` | Fix verified but auto-apply skipped (e.g., loop prevention). Inform user, offer manual apply. | +| `fix_apply_ready` | Fix verified (all tasks or e2e-only). Apply via MCP. | +| `fix_needs_local_verify` | Fix has unverified non-e2e tasks. Run locally, then apply or enhance. | +| `fix_needs_review` | Fix verification failed/not attempted. Analyze and decide. | +| `fix_failed` | Self-healing failed. Fetch heavy data, attempt local fix (gate check first). | +| `no_fix` | No fix available. Fetch heavy data, attempt local fix (gate check first) or exit. | +| `environment_issue` | Request environment rerun via MCP (gate check first). | +| `self_healing_throttled` | Reject old fixes, attempt local fix. | +| `no_new_cipe` | CI Attempt never spawned. Auto-fix workflow or exit with guidance. | +| `cipe_no_tasks` | CI failed with no tasks. Retry once with empty commit. | + +**Key rules (always apply):** + +- **Git safety**: Stage specific files by name — `git add -A` or `git add .` risks committing the user's unrelated work-in-progress or secrets +- **Environment failures** (OOM, command not found, permission denied): bail immediately. These aren't code bugs, so spending local-fix budget on them is wasteful +- **Gate check**: Run `ci-state-update.mjs gate` before local fix attempts — if budget exhausted, print message and exit + +## Main Loop + +### Step 1: Initialize Tracking + +``` +cycle_count = 0 # Only incremented for agent-initiated cycles (counted against --max-cycles) +start_time = now() +no_progress_count = 0 +local_verify_count = 0 +env_rerun_count = 0 +last_cipe_url = null +expected_commit_sha = null +agent_triggered = false # Set true after monitor takes an action that triggers new CI Attempt +poll_count = 0 +wait_mode = false +prev_status = null +prev_cipe_status = null +prev_sh_status = null +prev_verification_status = null +prev_failure_classification = null +``` + +### Step 2: Polling Loop + +Repeat until done: + +#### 2a. Spawn subagent (FETCH_STATUS) + +Determine select fields based on mode: + +- **Wait mode**: use WAIT_FIELDS (`cipeUrl,commitSha,cipeStatus`) +- **Normal mode (first poll or after newCipeDetected)**: use LIGHT_FIELDS + +Call the `ci_information` tool with the determined `select` fields for the current branch. Wait for the result before proceeding. + +#### 2b. Run decision script + +```bash +node /scripts/ci-poll-decide.mjs '' \ + [--wait-mode] \ + [--prev-cipe-url ] \ + [--expected-sha ] \ + [--prev-status ] \ + [--timeout ] \ + [--new-cipe-timeout ] \ + [--env-rerun-count ] \ + [--no-progress-count ] \ + [--prev-cipe-status ] \ + [--prev-sh-status ] \ + [--prev-verification-status ] \ + [--prev-failure-classification ] +``` + +The script outputs a single JSON line: `{ action, code, message, delay?, noProgressCount, envRerunCount, fields?, newCipeDetected?, verifiableTaskIds? }` + +#### 2c. Process script output + +Parse the JSON output and update tracking state: + +- `no_progress_count = output.noProgressCount` +- `env_rerun_count = output.envRerunCount` +- `prev_cipe_status = subagent_result.cipeStatus` +- `prev_sh_status = subagent_result.selfHealingStatus` +- `prev_verification_status = subagent_result.verificationStatus` +- `prev_failure_classification = subagent_result.failureClassification` +- `prev_status = output.action + ":" + (output.code || subagent_result.cipeStatus)` +- `poll_count++` + +Based on `action`: + +- **`action == "poll"`**: Print `output.message`, sleep `output.delay` seconds, go to 2a + - If `output.newCipeDetected`: clear wait mode, reset `wait_mode = false` +- **`action == "wait"`**: Print `output.message`, sleep `output.delay` seconds, go to 2a +- **`action == "done"`**: Proceed to Step 3 with `output.code` + +### Step 3: Handle Actionable Status + +When decision script returns `action == "done"`: + +1. Run cycle-check (Step 4) **before** handling the code +2. Check the returned `code` +3. Look up default behavior in the table above +4. Check if user instructions override the default +5. Execute the appropriate action +6. **If action expects new CI Attempt**, update tracking (see Step 3a) +7. If action results in looping, go to Step 2 + +#### Tool calls for actions + +Several statuses require fetching additional data or calling tools: + +- **fix_apply_ready**: Call `update_self_healing_fix` with action `APPLY` +- **fix_needs_local_verify**: Call `ci_information` with HEAVY_FIELDS for fix details before local verification +- **fix_needs_review**: Call `ci_information` with HEAVY_FIELDS → get `suggestedFixDescription`, `suggestedFixSummary`, `taskFailureSummaries` +- **fix_failed / no_fix**: Call `ci_information` with HEAVY_FIELDS → get `taskFailureSummaries` for local fix context +- **environment_issue**: Call `update_self_healing_fix` with action `RERUN_ENVIRONMENT_STATE` +- **self_healing_throttled**: Call `ci_information` with HEAVY_FIELDS → get `selfHealingSkipMessage`; then call `update_self_healing_fix` for each old fix + +### Step 3a: Track State for New-CI-Attempt Detection + +After actions that should trigger a new CI Attempt, run: + +```bash +node /scripts/ci-state-update.mjs post-action \ + --action \ + --cipe-url \ + --commit-sha +``` + +Action types: `fix-auto-applying`, `apply-mcp`, `apply-local-push`, `reject-fix-push`, `local-fix-push`, `env-rerun`, `auto-fix-push`, `empty-commit-push` + +The script returns `{ waitMode, pollCount, lastCipeUrl, expectedCommitSha, agentTriggered }`. Update all tracking state from the output, then go to Step 2. + +### Step 4: Cycle Classification and Progress Tracking + +When the decision script returns `action == "done"`, run cycle-check **before** handling the code: + +```bash +node /scripts/ci-state-update.mjs cycle-check \ + --code \ + [--agent-triggered] \ + --cycle-count --max-cycles \ + --env-rerun-count +``` + +The script returns `{ cycleCount, agentTriggered, envRerunCount, approachingLimit, message }`. Update tracking state from the output. + +- If `approachingLimit` → ask user whether to continue (with 5 or 10 more cycles) or stop monitoring +- If previous cycle was NOT agent-triggered (human pushed), log that human-initiated push was detected + +#### Progress Tracking + +- `no_progress_count`, circuit breaker (5 polls), and backoff reset are handled by ci-poll-decide.mjs (progress = any change in cipeStatus, selfHealingStatus, verificationStatus, or failureClassification) +- `env_rerun_count` reset on non-environment status is handled by ci-state-update.mjs cycle-check +- On new CI Attempt detected (poll script returns `newCipeDetected`) → reset `local_verify_count = 0`, `env_rerun_count = 0` + +## Error Handling + +| Error | Action | +| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | +| Git rebase conflict | Report to user, exit | +| `nx-cloud apply-locally` fails | Reject fix via MCP (`action: "REJECT"`), then attempt manual patch (Reject + Fix From Scratch Flow) or exit | +| MCP tool error | Retry once, if fails report to user | +| Subagent spawn failure | Retry once, if fails exit with error | +| Decision script error | Treat as `error` status, increment `no_progress_count` | +| No new CI Attempt detected | If `--auto-fix-workflow`, try lockfile update; otherwise report to user with guidance | +| Lockfile auto-fix fails | Report to user, exit with guidance to check CI logs | + +## User Instruction Examples + +Users can override default behaviors: + +| Instruction | Effect | +| ------------------------------------------------ | --------------------------------------------------- | +| "never auto-apply" | Always prompt before applying any fix | +| "always ask before git push" | Prompt before each push | +| "reject any fix for e2e tasks" | Auto-reject if `failedTaskIds` contains e2e | +| "apply all fixes regardless of verification" | Skip verification check, apply everything | +| "if confidence < 70, reject" | Check confidence field before applying | +| "run 'nx affected -t typecheck' before applying" | Add local verification step | +| "auto-fix workflow failures" | Attempt lockfile updates on pre-CI-Attempt failures | +| "wait 45 min for new CI Attempt" | Override new-CI-Attempt timeout (default: 10 min) | diff --git a/.agents/skills/monitor-ci/references/fix-flows.md b/.agents/skills/monitor-ci/references/fix-flows.md new file mode 100644 index 000000000000..b33aa02167ba --- /dev/null +++ b/.agents/skills/monitor-ci/references/fix-flows.md @@ -0,0 +1,108 @@ +# Detailed Status Handling & Fix Flows + +## Status Handling by Code + +### fix_auto_apply_skipped + +The script returns `autoApplySkipReason` in its output. + +1. Report the skip reason to the user (e.g., "Auto-apply was skipped because the previous CI pipeline execution was triggered by Nx Cloud") +2. Offer to apply the fix manually — spawn UPDATE_FIX subagent with `APPLY` if user agrees +3. Record `last_cipe_url`, enter wait mode + +### fix_apply_ready + +- Spawn UPDATE_FIX subagent with `APPLY` +- Record `last_cipe_url`, enter wait mode + +### fix_needs_local_verify + +The script returns `verifiableTaskIds` in its output. + +1. **Detect package manager:** `pnpm-lock.yaml` → `pnpm nx`, `yarn.lock` → `yarn nx`, otherwise `npx nx` +2. **Run verifiable tasks in parallel** — spawn `general` subagents for each task +3. **If all pass** → spawn UPDATE_FIX subagent with `APPLY`, enter wait mode +4. **If any fail** → Apply Locally + Enhance Flow (see below) + +### fix_needs_review + +Spawn FETCH_HEAVY subagent, then analyze fix content (`suggestedFixDescription`, `suggestedFixSummary`, `taskFailureSummaries`): + +- If fix looks correct → apply via MCP +- If fix needs enhancement → Apply Locally + Enhance Flow +- If fix is wrong → run `ci-state-update.mjs gate --gate-type local-fix`. If not allowed, print message and exit. Otherwise → Reject + Fix From Scratch Flow + +### fix_failed / no_fix + +Spawn FETCH_HEAVY subagent for `taskFailureSummaries`. Run `ci-state-update.mjs gate --gate-type local-fix` — if not allowed, print message and exit. Otherwise attempt local fix (counter already incremented by gate). If successful → commit, push, enter wait mode. If not → exit with failure. + +### environment_issue + +1. Run `ci-state-update.mjs gate --gate-type env-rerun`. If not allowed, print message and exit. +2. Spawn UPDATE_FIX subagent with `RERUN_ENVIRONMENT_STATE` +3. Enter wait mode with `last_cipe_url` set + +### self_healing_throttled + +Spawn FETCH_HEAVY subagent for `selfHealingSkipMessage`. + +1. **Parse throttle message** for CI Attempt URLs (regex: `/cipes/{id}`) +2. **Reject previous fixes** — for each URL: spawn FETCH_THROTTLE_INFO to get `shortLink`, then UPDATE_FIX with `REJECT` +3. **Attempt local fix**: Run `ci-state-update.mjs gate --gate-type local-fix`. If not allowed → skip to step 4. Otherwise use `failedTaskIds` and `taskFailureSummaries` for context. +4. **Fallback if local fix not possible or budget exhausted**: push empty commit (`git commit --allow-empty -m "ci: rerun after rejecting throttled fixes"`), enter wait mode + +### no_new_cipe + +1. Report to user: no CI attempt found, suggest checking CI provider +2. If `--auto-fix-workflow`: detect package manager, run install, commit lockfile if changed, enter wait mode +3. Otherwise: exit with guidance + +### cipe_no_tasks + +1. Report to user: CI failed with no tasks recorded +2. Retry: `git commit --allow-empty -m "chore: retry ci [monitor-ci]"` + push, enter wait mode +3. If retry also returns `cipe_no_tasks`: exit with failure + +## Fix Action Flows + +### Apply via MCP + +Spawn UPDATE_FIX subagent with `APPLY`. New CI Attempt spawns automatically. No local git ops. + +### Apply Locally + Enhance Flow + +1. `nx-cloud apply-locally ` (sets state to `APPLIED_LOCALLY`) +2. Enhance code to fix failing tasks +3. Run failing tasks to verify +4. If still failing → run `ci-state-update.mjs gate --gate-type local-fix`. If not allowed, commit current state and push (let CI be final judge). Otherwise loop back to enhance. +5. If passing → commit and push, enter wait mode + +### Reject + Fix From Scratch Flow + +1. Run `ci-state-update.mjs gate --gate-type local-fix`. If not allowed, print message and exit. +2. Spawn UPDATE_FIX subagent with `REJECT` +3. Fix from scratch locally +4. Commit and push, enter wait mode + +## Environment vs Code Failure Recognition + +When any local fix path runs a task and it fails, assess whether the failure is a **code issue** or an **environment/tooling issue** before running the gate script. + +**Indicators of environment/tooling failures** (non-exhaustive): command not found / binary missing, OOM / heap allocation failures, permission denied, network timeouts / DNS failures, missing system libraries, Docker/container issues, disk space exhaustion. + +When detected → bail immediately without running gate (no budget consumed). Report that the failure is an environment/tooling issue, not a code bug. + +**Code failures** (compilation errors, test assertion failures, lint violations, type errors) are genuine candidates for local fix attempts and proceed normally through the gate. + +## Git Safety + +- Stage specific files by name — `git add -A` or `git add .` risks committing the user's unrelated work-in-progress or secrets + +## Commit Message Format + +```bash +git commit -m "fix(): + +Failed tasks: , +Local verification: passed|enhanced|failed-pushing-to-ci" +``` diff --git a/.agents/skills/monitor-ci/scripts/ci-poll-decide.mjs b/.agents/skills/monitor-ci/scripts/ci-poll-decide.mjs new file mode 100644 index 000000000000..3fe17e5e0214 --- /dev/null +++ b/.agents/skills/monitor-ci/scripts/ci-poll-decide.mjs @@ -0,0 +1,428 @@ +#!/usr/bin/env node + +/** + * CI Poll Decision Script + * + * Deterministic decision engine for CI monitoring. + * Takes ci_information JSON + state args, outputs a single JSON action line. + * + * Architecture: + * classify() — pure decision tree, returns { action, code, extra? } + * buildOutput() — maps classification to full output with messages, delays, counters + * + * Usage: + * node ci-poll-decide.mjs '' \ + * [--wait-mode] [--prev-cipe-url ] [--expected-sha ] \ + * [--prev-status ] [--timeout ] [--new-cipe-timeout ] \ + * [--env-rerun-count ] [--no-progress-count ] \ + * [--prev-cipe-status ] [--prev-sh-status ] \ + * [--prev-verification-status ] [--prev-failure-classification ] + */ + +// --- Arg parsing --- + +const args = process.argv.slice(2); +const ciInfoJson = args[0]; +const pollCount = parseInt(args[1], 10) || 0; +const verbosity = args[2] || 'medium'; + +function getFlag(name) { + return args.includes(name); +} + +function getArg(name) { + const idx = args.indexOf(name); + return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null; +} + +const waitMode = getFlag('--wait-mode'); +const prevCipeUrl = getArg('--prev-cipe-url'); +const expectedSha = getArg('--expected-sha'); +const prevStatus = getArg('--prev-status'); +const timeoutSeconds = parseInt(getArg('--timeout') || '0', 10); +const newCipeTimeoutSeconds = parseInt(getArg('--new-cipe-timeout') || '0', 10); +const envRerunCount = parseInt(getArg('--env-rerun-count') || '0', 10); +const inputNoProgressCount = parseInt(getArg('--no-progress-count') || '0', 10); +const prevCipeStatus = getArg('--prev-cipe-status'); +const prevShStatus = getArg('--prev-sh-status'); +const prevVerificationStatus = getArg('--prev-verification-status'); +const prevFailureClassification = getArg('--prev-failure-classification'); + +// --- Parse CI info --- + +let ci; +try { + ci = JSON.parse(ciInfoJson); +} catch { + console.log( + JSON.stringify({ + action: 'done', + code: 'error', + message: 'Failed to parse ci_information JSON', + noProgressCount: inputNoProgressCount + 1, + envRerunCount, + }) + ); + process.exit(0); +} + +const { + cipeStatus, + selfHealingStatus, + verificationStatus, + selfHealingEnabled, + selfHealingSkippedReason, + failureClassification: rawFailureClassification, + failedTaskIds = [], + verifiedTaskIds = [], + couldAutoApplyTasks, + autoApplySkipped, + autoApplySkipReason, + userAction, + cipeUrl, + commitSha, +} = ci; + +const failureClassification = rawFailureClassification?.toLowerCase() ?? null; + +// --- Helpers --- + +function categorizeTasks() { + const verifiedSet = new Set(verifiedTaskIds); + const unverified = failedTaskIds.filter((t) => !verifiedSet.has(t)); + if (unverified.length === 0) return { category: 'all_verified' }; + + const e2e = unverified.filter((t) => { + const parts = t.split(':'); + return parts.length >= 2 && parts[1].includes('e2e'); + }); + if (e2e.length === unverified.length) return { category: 'e2e_only' }; + + const verifiable = unverified.filter((t) => { + const parts = t.split(':'); + return !(parts.length >= 2 && parts[1].includes('e2e')); + }); + return { category: 'needs_local_verify', verifiableTaskIds: verifiable }; +} + +function backoff(count) { + const delays = [60, 90, 120]; + return delays[Math.min(count, delays.length - 1)]; +} + +function hasStateChanged() { + if (prevCipeStatus && cipeStatus !== prevCipeStatus) return true; + if (prevShStatus && selfHealingStatus !== prevShStatus) return true; + if (prevVerificationStatus && verificationStatus !== prevVerificationStatus) + return true; + if ( + prevFailureClassification && + failureClassification !== prevFailureClassification + ) + return true; + return false; +} + +function isTimedOut() { + if (timeoutSeconds <= 0) return false; + const avgDelay = pollCount === 0 ? 0 : backoff(Math.floor(pollCount / 2)); + return pollCount * avgDelay >= timeoutSeconds; +} + +function isWaitTimedOut() { + if (newCipeTimeoutSeconds <= 0) return false; + return pollCount * 30 >= newCipeTimeoutSeconds; +} + +function isNewCipe() { + return ( + (prevCipeUrl && cipeUrl && cipeUrl !== prevCipeUrl) || + (expectedSha && commitSha && commitSha === expectedSha) + ); +} + +// ============================================================ +// classify() — pure decision tree +// +// Returns: { action: 'poll'|'wait'|'done', code: string, extra? } +// +// Decision priority (top wins): +// WAIT MODE: +// 1. new CI Attempt detected → poll (new_cipe_detected) +// 2. wait timed out → done (no_new_cipe) +// 3. still waiting → wait (waiting_for_cipe) +// NORMAL MODE: +// 4. polling timeout → done (polling_timeout) +// 5. circuit breaker (5 polls) → done (circuit_breaker) +// 6. CI succeeded → done (ci_success) +// 7. CI canceled → done (cipe_canceled) +// 8. CI timed out → done (cipe_timed_out) +// 9. CI failed, no tasks recorded → done (cipe_no_tasks) +// 10. environment failure → done (environment_rerun_cap | environment_issue) +// 11. self-healing throttled → done (self_healing_throttled) +// 12. CI in progress / not started → poll (ci_running) +// 13. self-healing in progress → poll (sh_running) +// 14. flaky task auto-rerun → poll (flaky_rerun) +// 15. fix auto-applied → poll (fix_auto_applied) +// 16. auto-apply: skipped → done (fix_auto_apply_skipped) +// 17. auto-apply: verification pending→ poll (verification_pending) +// 18. auto-apply: verified → done (fix_auto_applying) +// 19. fix: verification failed/none → done (fix_needs_review) +// 20. fix: all/e2e verified → done (fix_apply_ready) +// 21. fix: needs local verify → done (fix_needs_local_verify) +// 22. self-healing failed → done (fix_failed) +// 23. no fix available → done (no_fix) +// 24. fallback → poll (fallback) +// ============================================================ + +function classify() { + // --- Wait mode --- + if (waitMode) { + if (isNewCipe()) return { action: 'poll', code: 'new_cipe_detected' }; + if (isWaitTimedOut()) return { action: 'done', code: 'no_new_cipe' }; + return { action: 'wait', code: 'waiting_for_cipe' }; + } + + // --- Guards --- + if (isTimedOut()) return { action: 'done', code: 'polling_timeout' }; + if (noProgressCount >= 5) return { action: 'done', code: 'circuit_breaker' }; + + // --- Terminal CI states --- + if (cipeStatus === 'SUCCEEDED') return { action: 'done', code: 'ci_success' }; + if (cipeStatus === 'CANCELED') + return { action: 'done', code: 'cipe_canceled' }; + if (cipeStatus === 'TIMED_OUT') + return { action: 'done', code: 'cipe_timed_out' }; + + // --- CI failed, no tasks --- + if ( + cipeStatus === 'FAILED' && + failedTaskIds.length === 0 && + selfHealingStatus == null + ) + return { action: 'done', code: 'cipe_no_tasks' }; + + // --- Environment failure --- + if (failureClassification === 'environment_state') { + if (envRerunCount >= 2) + return { action: 'done', code: 'environment_rerun_cap' }; + return { action: 'done', code: 'environment_issue' }; + } + + // --- Throttled --- + if (selfHealingSkippedReason === 'THROTTLED') + return { action: 'done', code: 'self_healing_throttled' }; + + // --- Still running: CI --- + if (cipeStatus === 'IN_PROGRESS' || cipeStatus === 'NOT_STARTED') + return { action: 'poll', code: 'ci_running' }; + + // --- Still running: self-healing --- + if ( + (selfHealingStatus === 'IN_PROGRESS' || + selfHealingStatus === 'NOT_STARTED') && + !selfHealingSkippedReason + ) + return { action: 'poll', code: 'sh_running' }; + + // --- Still running: flaky rerun --- + if (failureClassification === 'flaky_task') + return { action: 'poll', code: 'flaky_rerun' }; + + // --- Fix auto-applied, waiting for new CI Attempt --- + if (userAction === 'APPLIED_AUTOMATICALLY') + return { action: 'poll', code: 'fix_auto_applied' }; + + // --- Auto-apply path (couldAutoApplyTasks) --- + if (couldAutoApplyTasks === true) { + if (autoApplySkipped === true) + return { + action: 'done', + code: 'fix_auto_apply_skipped', + extra: { autoApplySkipReason }, + }; + if ( + verificationStatus === 'NOT_STARTED' || + verificationStatus === 'IN_PROGRESS' + ) + return { action: 'poll', code: 'verification_pending' }; + if (verificationStatus === 'COMPLETED') + return { action: 'done', code: 'fix_auto_applying' }; + // verification FAILED or NOT_EXECUTABLE → falls through to fix_needs_review + } + + // --- Fix available --- + if (selfHealingStatus === 'COMPLETED') { + if ( + verificationStatus === 'FAILED' || + verificationStatus === 'NOT_EXECUTABLE' || + (couldAutoApplyTasks !== true && !verificationStatus) + ) + return { action: 'done', code: 'fix_needs_review' }; + + const tasks = categorizeTasks(); + if (tasks.category === 'all_verified' || tasks.category === 'e2e_only') + return { action: 'done', code: 'fix_apply_ready' }; + return { + action: 'done', + code: 'fix_needs_local_verify', + extra: { verifiableTaskIds: tasks.verifiableTaskIds }, + }; + } + + // --- Fix failed --- + if (selfHealingStatus === 'FAILED') + return { action: 'done', code: 'fix_failed' }; + + // --- No fix available --- + if ( + cipeStatus === 'FAILED' && + (selfHealingEnabled === false || selfHealingStatus === 'NOT_EXECUTABLE') + ) + return { action: 'done', code: 'no_fix' }; + + // --- Fallback --- + return { action: 'poll', code: 'fallback' }; +} + +// ============================================================ +// buildOutput() — maps classification to full JSON output +// ============================================================ + +// Message templates keyed by status or key +const messages = { + // wait mode + new_cipe_detected: () => + `New CI Attempt detected! CI: ${cipeStatus || 'N/A'}`, + no_new_cipe: () => + 'New CI Attempt timeout exceeded. No new CI Attempt detected.', + waiting_for_cipe: () => 'Waiting for new CI Attempt...', + + // guards + polling_timeout: () => 'Polling timeout exceeded.', + circuit_breaker: () => 'No progress after 5 consecutive polls. Stopping.', + + // terminal + ci_success: () => 'CI passed successfully!', + cipe_canceled: () => 'CI Attempt was canceled.', + cipe_timed_out: () => 'CI Attempt timed out.', + cipe_no_tasks: () => 'CI failed but no Nx tasks were recorded.', + + // environment + environment_rerun_cap: () => 'Environment rerun cap (2) exceeded. Bailing.', + environment_issue: () => 'CI: FAILED | Classification: ENVIRONMENT_STATE', + + // throttled + self_healing_throttled: () => + 'Self-healing throttled \u2014 too many unapplied fixes.', + + // polling + ci_running: () => `CI: ${cipeStatus}`, + sh_running: () => `CI: ${cipeStatus} | Self-healing: ${selfHealingStatus}`, + flaky_rerun: () => + 'CI: FAILED | Classification: FLAKY_TASK (auto-rerun in progress)', + fix_auto_applied: () => + 'CI: FAILED | Fix auto-applied, new CI Attempt spawning', + verification_pending: () => + `CI: FAILED | Self-healing: COMPLETED | Verification: ${verificationStatus}`, + + // actionable + fix_auto_applying: () => 'Fix verified! Auto-applying...', + fix_auto_apply_skipped: (extra) => + `Fix verified but auto-apply was skipped. ${ + extra?.autoApplySkipReason + ? `Reason: ${extra.autoApplySkipReason}` + : 'Offer to apply manually.' + }`, + fix_needs_review: () => + `Fix available but needs review. Verification: ${ + verificationStatus || 'N/A' + }`, + fix_apply_ready: () => 'Fix available and verified. Ready to apply.', + fix_needs_local_verify: (extra) => + `Fix available. ${extra.verifiableTaskIds.length} task(s) need local verification.`, + fix_failed: () => 'Self-healing failed to generate a fix.', + no_fix: () => 'CI failed, no fix available.', + + // fallback + fallback: () => + `CI: ${cipeStatus || 'N/A'} | Self-healing: ${ + selfHealingStatus || 'N/A' + } | Verification: ${verificationStatus || 'N/A'}`, +}; + +// Codes where noProgressCount resets to 0 (genuine progress occurred) +const resetProgressCodes = new Set([ + 'ci_success', + 'fix_auto_applying', + 'fix_auto_apply_skipped', + 'fix_needs_review', + 'fix_apply_ready', + 'fix_needs_local_verify', +]); + +function formatMessage(msg) { + if (verbosity === 'minimal') { + const currentStatus = `${cipeStatus}|${selfHealingStatus}|${verificationStatus}`; + if (currentStatus === (prevStatus || '')) return null; + return msg; + } + if (verbosity === 'verbose') { + return [ + `Poll #${pollCount + 1} | CI: ${cipeStatus || 'N/A'} | Self-healing: ${ + selfHealingStatus || 'N/A' + } | Verification: ${verificationStatus || 'N/A'}`, + msg, + ].join('\n'); + } + return `Poll #${pollCount + 1} | ${msg}`; +} + +function buildOutput(decision) { + const { action, code, extra } = decision; + + // noProgressCount is already computed before classify() was called. + // Here we only handle the reset for "genuine progress" done-codes. + + const msgFn = messages[code]; + const rawMsg = msgFn ? msgFn(extra) : `Unknown: ${code}`; + const message = formatMessage(rawMsg); + + const result = { + action, + code, + message, + noProgressCount: resetProgressCodes.has(code) ? 0 : noProgressCount, + envRerunCount, + }; + + // Add delay + if (action === 'wait') { + result.delay = 30; + } else if (action === 'poll') { + result.delay = code === 'new_cipe_detected' ? 60 : backoff(noProgressCount); + result.fields = 'light'; + } + + // Add extras + if (code === 'new_cipe_detected') result.newCipeDetected = true; + if (extra?.verifiableTaskIds) + result.verifiableTaskIds = extra.verifiableTaskIds; + if (extra?.autoApplySkipReason) + result.autoApplySkipReason = extra.autoApplySkipReason; + + console.log(JSON.stringify(result)); +} + +// --- Run --- + +// Compute noProgressCount from input. Single assignment, no mutation. +// Wait mode: reset on new cipe, otherwise unchanged (wait doesn't count as no-progress). +// Normal mode: reset on any state change, otherwise increment. +const noProgressCount = (() => { + if (waitMode) return isNewCipe() ? 0 : inputNoProgressCount; + if (isNewCipe() || hasStateChanged()) return 0; + return inputNoProgressCount + 1; +})(); + +buildOutput(classify()); diff --git a/.agents/skills/monitor-ci/scripts/ci-state-update.mjs b/.agents/skills/monitor-ci/scripts/ci-state-update.mjs new file mode 100644 index 000000000000..90fa71423ef4 --- /dev/null +++ b/.agents/skills/monitor-ci/scripts/ci-state-update.mjs @@ -0,0 +1,160 @@ +#!/usr/bin/env node + +/** + * CI State Update Script + * + * Deterministic state management for CI monitor actions. + * Three commands: gate, post-action, cycle-check. + * + * Usage: + * node ci-state-update.mjs gate --gate-type [counter args] + * node ci-state-update.mjs post-action --action [--cipe-url ] [--commit-sha ] + * node ci-state-update.mjs cycle-check --code [--agent-triggered] [counter args] + */ + +// --- Arg parsing --- + +const args = process.argv.slice(2); +const command = args[0]; + +function getFlag(name) { + return args.includes(name); +} + +function getArg(name) { + const idx = args.indexOf(name); + return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null; +} + +function output(result) { + console.log(JSON.stringify(result)); +} + +// --- gate --- +// Check if an action is allowed and return incremented counter. +// Called before any local fix attempt or environment rerun. + +function gate() { + const gateType = getArg('--gate-type'); + + if (gateType === 'local-fix') { + const count = parseInt(getArg('--local-verify-count') || '0', 10); + const max = parseInt(getArg('--local-verify-attempts') || '3', 10); + if (count >= max) { + return output({ + allowed: false, + localVerifyCount: count, + message: `Local fix budget exhausted (${count}/${max} attempts)`, + }); + } + return output({ + allowed: true, + localVerifyCount: count + 1, + message: null, + }); + } + + if (gateType === 'env-rerun') { + const count = parseInt(getArg('--env-rerun-count') || '0', 10); + if (count >= 2) { + return output({ + allowed: false, + envRerunCount: count, + message: `Environment issue persists after ${count} reruns. Manual investigation needed.`, + }); + } + return output({ + allowed: true, + envRerunCount: count + 1, + message: null, + }); + } + + output({ allowed: false, message: `Unknown gate type: ${gateType}` }); +} + +// --- post-action --- +// Compute next state after an action is taken. +// Returns wait mode params and whether the action was agent-triggered. + +function postAction() { + const action = getArg('--action'); + const cipeUrl = getArg('--cipe-url'); + const commitSha = getArg('--commit-sha'); + + // MCP-triggered or auto-applied: track by cipeUrl + const cipeUrlActions = ['fix-auto-applying', 'apply-mcp', 'env-rerun']; + // Local push: track by commitSha + const commitShaActions = [ + 'apply-local-push', + 'reject-fix-push', + 'local-fix-push', + 'auto-fix-push', + 'empty-commit-push', + ]; + + const trackByCipeUrl = cipeUrlActions.includes(action); + const trackByCommitSha = commitShaActions.includes(action); + + if (!trackByCipeUrl && !trackByCommitSha) { + return output({ error: `Unknown action: ${action}` }); + } + + // fix-auto-applying: self-healing did it, NOT the monitor + const agentTriggered = action !== 'fix-auto-applying'; + + output({ + waitMode: true, + pollCount: 0, + lastCipeUrl: trackByCipeUrl ? cipeUrl : null, + expectedCommitSha: trackByCommitSha ? commitSha : null, + agentTriggered, + }); +} + +// --- cycle-check --- +// Cycle classification + counter resets when a new "done" code is received. +// Called at the start of handling each actionable code. + +function cycleCheck() { + const status = getArg('--code'); + const wasAgentTriggered = getFlag('--agent-triggered'); + let cycleCount = parseInt(getArg('--cycle-count') || '0', 10); + const maxCycles = parseInt(getArg('--max-cycles') || '10', 10); + let envRerunCount = parseInt(getArg('--env-rerun-count') || '0', 10); + + // Cycle classification: if previous cycle was agent-triggered, count it + if (wasAgentTriggered) cycleCount++; + + // Reset env_rerun_count on non-environment status + if (status !== 'environment_issue') envRerunCount = 0; + + // Approaching limit gate + const approachingLimit = cycleCount >= maxCycles - 2; + + output({ + cycleCount, + agentTriggered: false, + envRerunCount, + approachingLimit, + message: approachingLimit + ? `Approaching cycle limit (${cycleCount}/${maxCycles})` + : null, + }); +} + +// --- Dispatch --- + +switch (command) { + case 'gate': + gate(); + break; + case 'post-action': + postAction(); + break; + case 'cycle-check': + cycleCheck(); + break; + default: + output({ error: `Unknown command: ${command}` }); +} diff --git a/.agents/skills/nx-run-tasks/SKILL.md b/.agents/skills/nx-run-tasks/SKILL.md new file mode 100644 index 000000000000..7f1263a57250 --- /dev/null +++ b/.agents/skills/nx-run-tasks/SKILL.md @@ -0,0 +1,58 @@ +--- +name: nx-run-tasks +description: Helps with running tasks in an Nx workspace. USE WHEN the user wants to execute build, test, lint, serve, or run any other tasks defined in the workspace. +--- + +You can run tasks with Nx in the following way. + +Keep in mind that you might have to prefix things with npx/pnpx/yarn if the user doesn't have nx installed globally. Look at the package.json or lockfile to determine which package manager is in use. + +For more details on any command, run it with `--help` (e.g. `nx run-many --help`, `nx affected --help`). + +## Understand which tasks can be run + +You can check those via `nx show project --json`, for example `nx show project myapp --json`. It contains a `targets` section which has information about targets that can be run. You can also just look at the `package.json` scripts or `project.json` targets, but you might miss out on inferred tasks by Nx plugins. + +## Run a single task + +``` +nx run : +``` + +where `project` is the project name defined in `package.json` or `project.json` (if present). + +## Run multiple tasks + +``` +nx run-many -t build test lint typecheck +``` + +You can pass a `-p` flag to filter to specific projects, otherwise it runs on all projects. You can also use `--exclude` to exclude projects, and `--parallel` to control the number of parallel processes (default is 3). + +Examples: + +- `nx run-many -t test -p proj1 proj2` — test specific projects +- `nx run-many -t test --projects=*-app --exclude=excluded-app` — test projects matching a pattern +- `nx run-many -t test --projects=tag:api-*` — test projects by tag + +## Run tasks for affected projects + +Use `nx affected` to only run tasks on projects that have been changed and projects that depend on changed projects. This is especially useful in CI and for large workspaces. + +``` +nx affected -t build test lint +``` + +By default it compares against the base branch. You can customize this: + +- `nx affected -t test --base=main --head=HEAD` — compare against a specific base and head +- `nx affected -t test --files=libs/mylib/src/index.ts` — specify changed files directly + +## Useful flags + +These flags work with `run`, `run-many`, and `affected`: + +- `--skipNxCache` — rerun tasks even when results are cached +- `--verbose` — print additional information such as stack traces +- `--nxBail` — stop execution after the first failed task +- `--configuration=` — use a specific configuration (e.g. `production`) diff --git a/.agents/skills/nx-workspace/SKILL.md b/.agents/skills/nx-workspace/SKILL.md new file mode 100644 index 000000000000..4b5110ad05b0 --- /dev/null +++ b/.agents/skills/nx-workspace/SKILL.md @@ -0,0 +1,286 @@ +--- +name: nx-workspace +description: "Explore and understand Nx workspaces. USE WHEN answering questions about the workspace, projects, or tasks. ALSO USE WHEN an nx command fails or you need to check available targets/configuration before running a task. EXAMPLES: 'What projects are in this workspace?', 'How is project X configured?', 'What depends on library Y?', 'What targets can I run?', 'Cannot find configuration for task', 'debug nx task failure'." +--- + +# Nx Workspace Exploration + +This skill provides read-only exploration of Nx workspaces. Use it to understand workspace structure, project configuration, available targets, and dependencies. + +Keep in mind that you might have to prefix commands with `npx`/`pnpx`/`yarn` if nx isn't installed globally. Check the lockfile to determine the package manager in use. + +## Listing Projects + +Use `nx show projects` to list projects in the workspace. + +The project filtering syntax (`-p`/`--projects`) works across many Nx commands including `nx run-many`, `nx release`, `nx show projects`, and more. Filters support explicit names, glob patterns, tag references (e.g. `tag:name`), directories, and negation (e.g. `!project-name`). + +```bash +# List all projects +nx show projects + +# Filter by pattern (glob) +nx show projects --projects "apps/*" +nx show projects --projects "shared-*" + +# Filter by tag +nx show projects --projects "tag:publishable" +nx show projects -p 'tag:publishable,!tag:internal' + +# Filter by target (projects that have a specific target) +nx show projects --withTarget build + +# Combine filters +nx show projects --type lib --withTarget test +nx show projects --affected --exclude="*-e2e" +nx show projects -p "tag:scope:client,packages/*" + +# Negate patterns +nx show projects -p '!tag:private' +nx show projects -p '!*-e2e' + +# Output as JSON +nx show projects --json +``` + +## Project Configuration + +Use `nx show project --json` to get the full resolved configuration for a project. + +**Important**: Do NOT read `project.json` directly - it only contains partial configuration. The `nx show project --json` command returns the full resolved config including inferred targets from plugins. + +You can read the full project schema at `node_modules/nx/schemas/project-schema.json` to understand nx project configuration options. + +```bash +# Get full project configuration +nx show project my-app --json + +# Extract specific parts from the JSON +nx show project my-app --json | jq '.targets' +nx show project my-app --json | jq '.targets.build' +nx show project my-app --json | jq '.targets | keys' + +# Check project metadata +nx show project my-app --json | jq '{name, root, sourceRoot, projectType, tags}' +``` + +## Target Information + +Targets define what tasks can be run on a project. + +```bash +# List all targets for a project +nx show project my-app --json | jq '.targets | keys' + +# Get full target configuration +nx show project my-app --json | jq '.targets.build' + +# Check target executor/command +nx show project my-app --json | jq '.targets.build.executor' +nx show project my-app --json | jq '.targets.build.command' + +# View target options +nx show project my-app --json | jq '.targets.build.options' + +# Check target inputs/outputs (for caching) +nx show project my-app --json | jq '.targets.build.inputs' +nx show project my-app --json | jq '.targets.build.outputs' + +# Find projects with a specific target +nx show projects --withTarget serve +nx show projects --withTarget e2e +``` + +## Workspace Configuration + +Read `nx.json` directly for workspace-level configuration. +You can read the full project schema at `node_modules/nx/schemas/nx-schema.json` to understand nx project configuration options. + +```bash +# Read the full nx.json +cat nx.json + +# Or use jq for specific sections +cat nx.json | jq '.targetDefaults' +cat nx.json | jq '.namedInputs' +cat nx.json | jq '.plugins' +cat nx.json | jq '.generators' +``` + +Key nx.json sections: + +- `targetDefaults` - Default configuration applied to all targets of a given name +- `namedInputs` - Reusable input definitions for caching +- `plugins` - Nx plugins and their configuration +- ...and much more, read the schema or nx.json for details + +## Affected Projects + +If the user is asking about affected projects, read the [affected projects reference](references/AFFECTED.md) for detailed commands and examples. + +## Common Exploration Patterns + +### "What's in this workspace?" + +```bash +nx show projects +nx show projects --type app +nx show projects --type lib +``` + +### "How do I build/test/lint project X?" + +```bash +nx show project X --json | jq '.targets | keys' +nx show project X --json | jq '.targets.build' +``` + +### "What depends on library Y?" + +```bash +# Use the project graph to find dependents +nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "Y") | .key' +``` + +## Programmatic Answers + +When processing nx CLI results, use command-line tools to compute the answer programmatically rather than counting or parsing output manually. Always use `--json` flags to get structured output that can be processed with `jq`, `grep`, or other tools you have installed locally. + +### Listing Projects + +```bash +nx show projects --json +``` + +Example output: + +```json +["my-app", "my-app-e2e", "shared-ui", "shared-utils", "api"] +``` + +Common operations: + +```bash +# Count projects +nx show projects --json | jq 'length' + +# Filter by pattern +nx show projects --json | jq '.[] | select(startswith("shared-"))' + +# Get affected projects as array +nx show projects --affected --json | jq '.' +``` + +### Project Details + +```bash +nx show project my-app --json +``` + +Example output: + +```json +{ + "root": "apps/my-app", + "name": "my-app", + "sourceRoot": "apps/my-app/src", + "projectType": "application", + "tags": ["type:app", "scope:client"], + "targets": { + "build": { + "executor": "@nx/vite:build", + "options": { "outputPath": "dist/apps/my-app" } + }, + "serve": { + "executor": "@nx/vite:dev-server", + "options": { "buildTarget": "my-app:build" } + }, + "test": { + "executor": "@nx/vite:test", + "options": {} + } + }, + "implicitDependencies": [] +} +``` + +Common operations: + +```bash +# Get target names +nx show project my-app --json | jq '.targets | keys' + +# Get specific target config +nx show project my-app --json | jq '.targets.build' + +# Get tags +nx show project my-app --json | jq '.tags' + +# Get project root +nx show project my-app --json | jq -r '.root' +``` + +### Project Graph + +```bash +nx graph --print +``` + +Example output: + +```json +{ + "graph": { + "nodes": { + "my-app": { + "name": "my-app", + "type": "app", + "data": { "root": "apps/my-app", "tags": ["type:app"] } + }, + "shared-ui": { + "name": "shared-ui", + "type": "lib", + "data": { "root": "libs/shared-ui", "tags": ["type:ui"] } + } + }, + "dependencies": { + "my-app": [ + { "source": "my-app", "target": "shared-ui", "type": "static" } + ], + "shared-ui": [] + } + } +} +``` + +Common operations: + +```bash +# Get all project names from graph +nx graph --print | jq '.graph.nodes | keys' + +# Find dependencies of a project +nx graph --print | jq '.graph.dependencies["my-app"]' + +# Find projects that depend on a library +nx graph --print | jq '.graph.dependencies | to_entries[] | select(.value[].target == "shared-ui") | .key' +``` + +## Troubleshooting + +### "Cannot find configuration for task X:target" + +```bash +# Check what targets exist on the project +nx show project X --json | jq '.targets | keys' + +# Check if any projects have that target +nx show projects --withTarget target +``` + +### "The workspace is out of sync" + +```bash +nx sync +nx reset # if sync doesn't fix stale cache +``` diff --git a/.agents/skills/nx-workspace/references/AFFECTED.md b/.agents/skills/nx-workspace/references/AFFECTED.md new file mode 100644 index 000000000000..e30f18f6a446 --- /dev/null +++ b/.agents/skills/nx-workspace/references/AFFECTED.md @@ -0,0 +1,27 @@ +## Affected Projects + +Find projects affected by changes in the current branch. + +```bash +# Affected since base branch (auto-detected) +nx show projects --affected + +# Affected with explicit base +nx show projects --affected --base=main +nx show projects --affected --base=origin/main + +# Affected between two commits +nx show projects --affected --base=abc123 --head=def456 + +# Affected apps only +nx show projects --affected --type app + +# Affected excluding e2e projects +nx show projects --affected --exclude="*-e2e" + +# Affected by uncommitted changes +nx show projects --affected --uncommitted + +# Affected by untracked files +nx show projects --affected --untracked +``` diff --git a/.codex/agents/ci-monitor-subagent.toml b/.codex/agents/ci-monitor-subagent.toml new file mode 100644 index 000000000000..591c7cb189ec --- /dev/null +++ b/.codex/agents/ci-monitor-subagent.toml @@ -0,0 +1,46 @@ +developer_instructions = """ +# CI Monitor Subagent + +You are a CI helper. You call ONE MCP tool per invocation and return the result. Do not loop, poll, or sleep. + +## Commands + +The main agent tells you which command to run: + +### FETCH_STATUS + +Call `ci_information` with the provided branch and select fields. Return a JSON object with ONLY these fields: +`{ cipeStatus, selfHealingStatus, verificationStatus, selfHealingEnabled, selfHealingSkippedReason, failureClassification, failedTaskIds, verifiedTaskIds, couldAutoApplyTasks, autoApplySkipped, autoApplySkipReason, userAction, cipeUrl, commitSha, shortLink }` + +### FETCH_HEAVY + +Call `ci_information` with heavy select fields. Summarize the heavy content and return: + +```json +{ + "shortLink": "...", + "failedTaskIds": ["..."], + "verifiedTaskIds": ["..."], + "suggestedFixDescription": "...", + "suggestedFixSummary": "...", + "selfHealingSkipMessage": "...", + "taskFailureSummaries": [{ "taskId": "...", "summary": "..." }] +} +``` + +Do NOT return raw suggestedFix diffs or raw taskOutputSummary — summarize them. +The main agent uses these summaries to understand what failed and attempt local fixes. + +### UPDATE_FIX + +Call `update_self_healing_fix` with the provided shortLink and action (APPLY/REJECT/RERUN_ENVIRONMENT_STATE). Return the result message (success/failure string). + +### FETCH_THROTTLE_INFO + +Call `ci_information` with the provided URL. Return ONLY: `{ shortLink, cipeUrl }` + +## Important + +- Execute ONE command and return immediately +- Do NOT poll, loop, sleep, or make decisions +- Extract and return ONLY the fields specified for each command — do NOT dump the full MCP response""" diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 000000000000..47563d4ccea8 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,8 @@ + +mcp_servers.nx-mcp.command = 'npx' +mcp_servers.nx-mcp.args = ['nx', 'mcp'] +features.multi_agent = true + +[agents.ci-monitor-subagent] +description = 'CI helper for /monitor-ci. Fetches CI status, retrieves fix details, or updates self-healing fixes. Executes one MCP tool call and returns the result.' +config_file = 'agents/ci-monitor-subagent.toml'