@trackunit/iris-app 1.12.9 → 1.12.10

package/src/generators/preset/files/.cursor/rules/browser-irisx-development.mdc

@@ -1,246 +0,0 @@
-# Browser Usage for IrisX App Development
-
-## Overview
-This rule defines the browser-first workflow for developing and testing IrisX Apps in Trackunit Manager.
-
-**⚠️ CRITICAL: IrisX Apps are ALWAYS tested at https://new.manager.trackunit.com/goto/iris-app-dev - NEVER on localhost!**
-
-When the dev server runs locally (via `npx nx run [app-name]:serve`), it serves the app files, but you MUST test the app in the Trackunit Manager environment at the URL above. This is because IrisX apps are extensions that integrate into Trackunit Manager and require the host platform to function.
-
-## Initial Browser Setup
-
-### 1. Open Browser and Wait for Login
-When starting IrisX App development:
-
-```
-1. Navigate to: https://new.manager.trackunit.com/goto/iris-app-dev
-   (This is THE ONLY URL to test IrisX apps - NEVER use localhost!)
-2. Inform user: "I've opened Trackunit Manager at https://new.manager.trackunit.com/goto/iris-app-dev. Please log in."
-3. Wait for user to complete login (be patient - may take 2-4 minutes)
-4. Do NOT proceed until you see the Trackunit Manager interface loaded
-```
-
-### 2. Verify Local Dev Mode is Enabled
-After user is logged in, check if local dev mode is active:
-
-```
-a) Take browser snapshot
-b) Look for element with data-testid="local-mode-tooltip-parent" in the sidebar
-c) If "Use Local Apps" toggle is visible and enabled → local dev mode is ON
-d) If NOT found or NOT enabled → proceed to step 3
-```
-
-### 3. Enable Local Dev Mode (if needed)
-If local dev mode is not enabled:
-
-```
-a) Navigate to: https://new.manager.trackunit.com/goto/iris-app-dev
-b) Wait for page to load
-c) Take snapshot to verify the local dev mode page loaded
-d) Look for "Use Local Apps" toggle in sidebar (data-testid="local-mode-tooltip-parent")
-e) If toggle is OFF, click it to enable local dev mode
-f) Wait 2 seconds for activation
-g) Verify toggle is now ON
-```
-
-### 4. Navigate to Extension
-Based on extension type, navigate to where the extension should appear:
-
-**FLEET_EXTENSION:**
-- Main menu → Look for your app name in the menu items
-- Click to open the extension
-
-**ASSET_HOME_EXTENSION:**
-- Navigate to Assets → Open any asset
-- Look for new tab with your extension name
-- Click the tab
-
-**SITE_HOME_EXTENSION:**
-- Navigate to Sites → Open any site
-- Look for new tab with your extension name
-- Click the tab
-
-**WIDGET_EXTENSION:**
-- Navigate to Dashboard
-- Click "Add Widget" or similar
-- Look for your widget in the list
-
-## Testing After Code Changes
-
-### Reload Strategy
-After making code changes to your extension:
-
-**1. Check Lints First (Zero Tolerance):**
-```
-- Run read_lints on modified files
-- Fix ALL errors before testing in browser
-- Do not proceed with any TypeScript or linter errors
-```
-
-**2. Reload Browser:**
-The dev server hot-reloads, but sometimes a full page refresh is needed:
-
-```
-Option A - Wait for Hot Reload:
-- Wait 2-3 seconds after saving files
-- Check if changes appear automatically
-- If extension goes blank or changes don't appear → proceed to Option B
-
-Option B - Manual Refresh:
-For macOS:
-  - Press Command+R to reload page
-  OR
-  - Use browser_snapshot, then browser_evaluate with: location.reload()
-
-For Windows:
-  - Press Ctrl+R to reload page (use browser_press_key)
-  OR
-  - Use browser_evaluate with: location.reload()
-
-Option C - Hard Refresh (if normal refresh doesn't work):
-For macOS:
-  - Press Command+Shift+R for hard reload
-  OR
-  - Use browser_evaluate with: location.reload(true)
-
-For Windows:
-  - Press Ctrl+Shift+R for hard reload
-  OR
-  - Use browser_evaluate with: location.reload(true)
-```
-
-**⚠️ IMPORTANT - Manifest Changes Require Re-Serve:**
-```
-If you modified iris-app-manifest.ts (scopes, CSP headers, metadata, etc.):
-- Browser reload is NOT enough
-- You MUST stop the dev server (Ctrl+C)
-- Re-run: npx nx run [app-name]:serve
-- Wait for server to restart
-- Then reload browser
-
-Manifest changes include:
-- Adding/removing scopes
-- Updating CSP headers (cspHeader)
-- Changing app metadata
-- Modifying extension configurations
-```
-
-**3. Verify Extension Loaded:**
-```
-- Take browser snapshot
-- Look for your extension content
-- Check if it's blank/empty → may need hard refresh
-- Verify expected UI elements are present
-```
-
-**4. Check Console for Errors:**
-```
-- Use browser_console_messages tool
-- Look for errors (red messages)
-- Common issues:
-  - GraphQL errors (check scopes in manifest)
-  - CSP violations (update cspHeader in manifest)
-  - Module loading errors (check imports)
-  - Runtime errors (check code logic)
-```
-
-**5. Check Network Requests (if using GraphQL/APIs):**
-```
-- Use browser_network_requests tool
-- Note: GraphQL returns 200 OK even with errors - inspect response bodies
-- Look for "errors" array in GraphQL responses
-- Check for HTTP status errors: 400 (bad syntax), 401/403 (auth/scopes), 500 (server error)
-- Common issues: missing scopes in manifest, incorrect query structure
-```
-
-## Troubleshooting Common Issues
-
-### Extension Shows Blank After Changes
-```
-1. Try hard refresh (Command+Shift+R or Ctrl+Shift+R)
-2. Check browser console for errors
-3. Check if dev server is still running
-4. Verify file saved correctly
-5. Check for TypeScript compilation errors
-6. Navigate away and back to extension
-```
-
-### "Use Local Apps" Toggle Not Found
-```
-1. Verify user is logged in successfully
-2. Navigate directly to https://new.manager.trackunit.com/goto/iris-app-dev
-3. Wait for page to fully load
-4. Take snapshot to see what's visible
-5. Look for "Use Local Apps" toggle in sidebar (data-testid="local-mode-tooltip-parent")
-6. If found and OFF, click it to enable local dev mode
-7. Wait 2 seconds for activation
-8. Verify toggle is now ON
-9. May need to scroll sidebar to find toggle if not immediately visible
-```
-
-### Extension Not Appearing in Menu/Tabs
-```
-1. Verify dev server is running
-2. Check manifest.json has correct extension type
-3. If you changed iris-app-manifest.ts → MUST re-serve the app (stop and restart dev server)
-4. Hard refresh browser
-5. Disable and re-enable "Use Local Apps"
-6. Check browser console for loading errors
-7. Verify extension-manifest.ts is configured correctly
-```
-
-### GraphQL/API Errors
-```
-1. Use browser_network_requests to find GraphQL requests
-2. Inspect response body for "errors" array (GraphQL returns 200 even with errors)
-3. Common fixes:
-   - Missing scopes → Add to iris-app-manifest.ts scopes array
-   - CSP violations → Add domain to cspHeader in iris-app-manifest.ts
-   - Query errors → Use Trackunit MCP validate-query to test
-   - Auth issues → Deploy app to enable new scopes (inform user - never auto-deploy)
-4. If manifest was changed → restart dev server
-```
-
-## Workflow Integration
-
-### After Every Code Change:
-1. ✅ Check lints (zero tolerance)
-2. ✅ Fix all errors
-3. ✅ Wait 2-3 seconds for hot reload
-4. ✅ Refresh browser if needed
-5. ✅ Take snapshot
-6. ✅ Verify changes visible
-7. ✅ Check console for errors
-8. ✅ Check network tab if using APIs
-9. ✅ Fix any issues before proceeding
-
-### Before Moving to Next Feature:
-1. ✅ Current feature fully working in browser
-2. ✅ Zero linter/TypeScript errors
-3. ✅ Zero browser console errors
-4. ✅ All network requests successful
-5. ✅ Screenshot of working feature
-6. ✅ Documentation updated
-
-## Best Practices
-
-1. **Always Use https://new.manager.trackunit.com/goto/iris-app-dev:** Never test on localhost - IrisX apps require the Trackunit Manager host environment
-2. **Keep Browser Open:** Always keep browser tab visible during development
-3. **Snapshot Often:** Take snapshots after every change to verify UI
-4. **Console is Your Friend:** Check console after every reload
-5. **Network Tab for APIs:** Monitor all GraphQL/API requests
-6. **Refresh Strategy:** Try soft refresh first, hard refresh if needed
-7. **Patient with Login:** Give user adequate time to log in (2-4 minutes)
-8. **Verify Before Proceeding:** Always confirm extension loads before writing features
-9. **One Feature at a Time:** Test each feature completely before moving on
-
-## Critical Reminders
-
-- **ALWAYS test at https://new.manager.trackunit.com/goto/iris-app-dev** - NEVER on localhost!
-- **Never proceed without browser verification** after initial setup
-- **Always check lints before browser testing** (zero tolerance for errors)
-- **Reload browser after every code change** to see updates
-- **Check console and network tab** for errors after each reload
-- **Fix issues immediately** before moving to next feature
-- **Take screenshots** to document working features
-- **Be patient with user login** - don't rush the authentication process

package/src/generators/preset/files/.cursor/rules/graphql-timeseries.md

@@ -1,260 +0,0 @@
-# GraphQL Time Series API Usage
-
-This rule covers how to query time series data through GraphQL in IrisX App SDK using PromQL (Prometheus Query Language).
-
-## Query Structure
-
-### Range Query (time series data)
-```graphql
-query GetTimeSeriesData($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
-  asset(id: $assetId) {
-    timeSeries {
-      rangeQuery(query: "metric_name", start: $start, end: $end, step: $step) {
-        data {
-          ... on TimeSeriesMatrixData {
-            result {
-              values { timestamp value }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Instant Query (single point in time)
-```graphql
-query GetInstantData($assetId: ID!, $time: DateTime!) {
-  asset(id: $assetId) {
-    timeSeries {
-      instantQuery(query: "metric_name", time: $time) {
-        data {
-          ... on TimeSeriesVectorData {
-            result { value { timestamp value } }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## Common Metrics
-
-### Machine Insights (Possible Insights, not all assets will have all Insights)
-- `machine_insight_ac_average_frequency`
-- `machine_insight_ac_average_phase_to_neutral_rms_voltage`
-- `machine_insight_ac_average_phase_to_phase_rms_voltage`
-- `machine_insight_ac_average_rms_current`
-- `machine_insight_accelerometer_x_axis`
-- `machine_insight_accelerometer_y_axis`
-- `machine_insight_accelerometer_z_axis`
-- `machine_insight_ac_phase_l1_active_power`
-- `machine_insight_ac_phase_l1_frequency`
-- `machine_insight_ac_phase_l1_l2_rms_voltage`
-- `machine_insight_ac_phase_l1_netural_rms_voltage`
-- `machine_insight_ac_phase_l1_neutral_rms_voltage`
-- `machine_insight_ac_phase_l1_rms_current`
-- `machine_insight_ac_phase_l2_active_power`
-- `machine_insight_ac_phase_l2_frequency`
-- `machine_insight_ac_phase_l2_l3_rms_voltage`
-- `machine_insight_ac_phase_l2_netural_rms_voltage`
-- `machine_insight_ac_phase_l2_neutral_rms_voltage`
-- `machine_insight_ac_phase_l2_rms_current`
-- `machine_insight_ac_phase_l3_active_power`
-- `machine_insight_ac_phase_l3_frequency`
-- `machine_insight_ac_phase_l3_l1_rms_voltage`
-- `machine_insight_ac_phase_l3_netural_rms_voltage`
-- `machine_insight_ac_phase_l3_neutral_rms_voltage`
-- `machine_insight_ac_phase_l3_rms_current`
-- `machine_insight_ac_total_active_power`
-- `machine_insight_ac_total_apparent_power`
-- `machine_insight_ac_total_power_factor`
-- `machine_insight_ac_total_reactive_power`
-- `machine_insight_ac_total_relative_active_power_load_percentage`
-- `machine_insight_ac_total_relative_apparent_power_load_percentage`
-- `machine_insight_ac_total_relative_load_percentage`
-- `machine_insight_actual_engine_percent_torque`
-- `machine_insight_after_treatment_diesel_exhaust_fluid_concentration`
-- `machine_insight_after_treatment_diesel_exhaust_fluid_tank_level`
-- `machine_insight_after_treatment_diesel_exhaust_fluid_tank_temperature`
-- `machine_insight_after_treatment_diesel_particulate_filter_active_regeneration_state`
-- `machine_insight_after_treatment_diesel_particulate_filter_active_regeneration_status`
-- `machine_insight_after_treatment_diesel_particulate_filter_ash_load_percent`
-- `machine_insight_after_treatment_diesel_particulate_filter_differential_pressure`
-- `machine_insight_after_treatment_diesel_particulate_filter_intake_temperature`
-- `machine_insight_after_treatment_diesel_particulate_filter_passive_regeneration_status`
-- `machine_insight_after_treatment_diesel_particulate_filter_soot_load_percent`
-- `machine_insight_after_treatment_diesel_particulate_filter_state`
-- `machine_insight_after_treatment_diesel_particulate_filter_status`
-- `machine_insight_after_treatment_diesel_particulate_filter_time_since_last_active_regeneration`
-- `machine_insight_aftertreatment_diesel_particulate_filter_time_to_next_active_regeneration`
-- `machine_insight_after_treatment_exhaust_temperature`
-- `machine_insight_aftertreatment_scr_time_since_last_cleaning_event`
-- `machine_insight_altitude`
-- `machine_insight_ambient_air_temperature`
-- `machine_insight_average_load_factor_last_24`
-- `machine_insight_barometric_pressure`
-- `machine_insight_battery_charge_cycles_count`
-- `machine_insight_battery_charger_cumulative_input_energy`
-- `machine_insight_battery_charger_input_current`
-- `machine_insight_battery_charger_input_current_limit`
-- `machine_insight_battery_charger_input_voltage`
-- `machine_insight_battery_charger_output_current`
-- `machine_insight_battery_charger_output_current_limit`
-- `machine_insight_battery_charger_output_voltage`
-- `machine_insight_battery_charger_power_line_state`
-- `machine_insight_battery_charger_state`
-- `machine_insight_battery_cumulative_discharged_energy`
-- `machine_insight_battery_current`
-- `machine_insight_battery_potential`
-- `machine_insight_battery_remaining_charge_time`
-- `machine_insight_battery_remaining_run_time`
-- `machine_insight_battery_state_of_charge_percent`
-- `machine_insight_battery_state_of_health_percent`
-- `machine_insight_battery_temperature`
-- `machine_insight_cumulative_active_regeneration_hours`
-- `machine_insight_cumulative_co2_emissions`
-- `machine_insight_cumulative_engine_hours`
-- `machine_insight_cumulative_idle_hours`
-- `machine_insight_cumulative_idle_non_operating_hours`
-- `machine_insight_cumulative_load_count`
-- `machine_insight_cumulative_moving_hours`
-- `machine_insight_cumulative_operating_hours`
-- `machine_insight_cumulative_payload_totals`
-- `machine_insight_cumulative_productive_hours`
-- `machine_insight_diesel_particulate_filter_active_regeneration_inhibited_due_to_inhibit_switch`
-- `machine_insight_engine_air_filter_differential_pressure`
-- `machine_insight_engine_coolant_level`
-- `machine_insight_engine_coolant_pressure`
-- `machine_insight_engine_coolant_temperature`
-- `machine_insight_engine_exhaust_temperature`
-- `machine_insight_engine_fuel_delivery_pressure`
-- `machine_insight_engine_fuel_filter_differential_pressure`
-- `machine_insight_engine_fuel_rate`
-- `machine_insight_engine_fuel_temperature`
-- `machine_insight_engine_intake_air_pressure`
-- `machine_insight_engine_intake_air_temperature`
-- `machine_insight_engine_intake_manifold_pressure`
-- `machine_insight_engine_intake_manifold_temperature`
-- `machine_insight_engine_intercooler_temperature`
-- `machine_insight_engine_oil_filter_differential_pressure`
-- `machine_insight_engine_oil_level`
-- `machine_insight_engine_oil_pressure`
-- `machine_insight_engine_oil_temperature`
-- `machine_insight_engine_percent_load_at_current_speed`
-- `machine_insight_engine_speed`
-- `machine_insight_engine_status`
-- `machine_insight_engine_total_fuel_used`
-- `machine_insight_engine_total_idle_fuel_used`
-- `machine_insight_engine_trip_fuel`
-- `machine_insight_exhaust_system_high_temperature_lamp_command`
-- `machine_insight_fuel_level`
-- `machine_insight_fuel_tank_capacity`
-- `machine_insight_fuel_used_last_24`
-- `machine_insight_generator_total_kw_hours_export`
-- `machine_insight_hydraulic_oil_filter_restriction_switch`
-- `machine_insight_hydraulic_oil_level`
-- `machine_insight_hydraulic_pressure`
-- `machine_insight_hydraulic_temperature`
-- `machine_insight_impact`
-- `machine_insight_maximum_speed_last_24`
-- `machine_insight_operation_status`
-- `machine_insight_payload`
-- `machine_insight_payload_percentage`
-- `machine_insight_payload_temperature`
-- `machine_insight_pitch_angle`
-- `machine_insight_platform_elevated`
-- `machine_insight_platform_height`
-- `machine_insight_platform_height_percent`
-- `machine_insight_platform_stowed`
-- `machine_insight_rescue_mode_active`
-- `machine_insight_road_surface_temperature`
-- `machine_insight_roll_angle`
-- `machine_insight_seat_belt_switch`
-- `machine_insight_speed`
-- `machine_insight_stabilizers_deployed`
-- `machine_insight_total_power_take_off_hours`
-- `machine_insight_total_vehicle_distance`
-- `machine_insight_transmission_oil_temperature`
-- `machine_insight_water_in_fuel_indicator`
-- `machine_insight_wheel_based_vehicle_speed`
-
-## PromQL Examples via GraphQL
-
-### Calculate daily increases
-```graphql
-query IncreaseOperatingHours($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
-  asset(id: $assetId) {
-    timeSeries {
-      rangeQuery(
-        query: "increase(machine_insight_cumulative_operating_hours[1d])",
-        start: $start,
-        end: $end,
-        step: $step
-      ) {
-        data {
-          ... on TimeSeriesMatrixData {
-            result { values { timestamp value } }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Filter with conditions
-```graphql
-query HighFuelConsumption($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
-  asset(id: $assetId) {
-    timeSeries {
-      rangeQuery(
-        query: "increase(machine_insight_engine_total_fuel_used[1d]) > 13",
-        start: $start,
-        end: $end,
-        step: $step
-      ) {
-        data {
-          ... on TimeSeriesMatrixData {
-            result { values { timestamp value } }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### Combine metrics
-```graphql
-query FuelWithHighIdle($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
-  asset(id: $assetId) {
-    timeSeries {
-      rangeQuery(
-        query: "(increase(machine_insight_engine_total_fuel_used[1d]) > 13) and (increase(machine_insight_engine_total_idle_hours[1d]) > 4)",
-        start: $start,
-        end: $end,
-        step: $step
-      ) {
-        data {
-          ... on TimeSeriesMatrixData {
-            result { values { timestamp value } }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## Key Points
-
-- **Always use fragments** for both `TimeSeriesMatrixData` and `TimeSeriesVectorData`
-- **Use PromQL functions** like `increase()`, `rate()`, `avg_over_time()`
-- **Filter at query level** with operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
-- **Time windows** use brackets: `[1d]`, `[1h]`, `[15m]`
-- **Step intervals**: Choose based on data granularity needed
-- **Timestamps** are Unix timestamps in seconds
-- **Values** are returned as strings, convert to numbers as needed