@trackunit/iris-app 1.7.28 → 1.7.30

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.7.30 (2025-10-15)
+
+This was a version bump only for iris-app to align it with other projects, there were no code changes.
+
+## 1.7.29 (2025-10-15)
+
+### 🧱 Updated Dependencies
+
+- Updated iris-app-build-utilities to 1.7.28
+- Updated iris-app-webpack-plugin to 1.7.29
+- Updated iris-app-api to 1.7.28
+- Updated react-test-setup to 1.4.27
+- Updated shared-utils to 1.9.27
+
 ## 1.7.28 (2025-10-10)
 
 ### 🧱 Updated Dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/iris-app",
-  "version": "1.7.28",
+  "version": "1.7.30",
   "license": "SEE LICENSE IN LICENSE.txt",
   "main": "src/index.js",
   "generators": "./generators.json",
@@ -32,12 +32,12 @@
     "@npmcli/arborist": "^7.3.1",
     "webpack-bundle-analyzer": "^4.8.0",
     "win-ca": "^3.5.1",
-    "@trackunit/iris-app-build-utilities": "1.7.27",
-    "@trackunit/shared-utils": "1.9.26",
-    "@trackunit/iris-app-api": "1.7.27",
-    "@trackunit/iris-app-webpack-plugin": "1.7.28",
+    "@trackunit/iris-app-build-utilities": "1.7.28",
+    "@trackunit/shared-utils": "1.9.27",
+    "@trackunit/iris-app-api": "1.7.28",
+    "@trackunit/iris-app-webpack-plugin": "1.7.29",
     "tslib": "^2.6.2",
-    "@trackunit/react-test-setup": "1.4.26"
+    "@trackunit/react-test-setup": "1.4.27"
   },
   "types": "./src/index.d.ts",
   "type": "commonjs"

package/src/generators/preset/files/.cursor/commands/create-app.md

@@ -0,0 +1,226 @@
+# Create IrisX App
+
+You are helping a user create a new IrisX App with appropriate extensions. Follow this browser-driven iterative development workflow.
+
+## Core Principles
+
+### Real Data First
+**CRITICAL: Always use Trackunit's GraphQL API for data** - never mock data unless explicitly requested.
+- Use **Trackunit MCP** `introspect-schema` to discover available data
+- Use **Trackunit MCP** `validate-query` to test queries before implementing
+- See @irisx-app-sdk-graphql for implementation patterns
+
+### UI Components
+**Use Trackunit Component Library** for consistent UI:
+- Use **Trackunit MCP** `get-story-code` to find components and patterns
+- See @tables-and-sorting, @react-core-hooks for details
+
+### Browser Testing
+**Follow browser-first development workflow**:
+- See @browser-irisx-development for complete browser testing procedures
+- Always verify in browser after each code change
+- Check lints first, then reload browser and verify
+
+## Development Workflow
+
+### Phase 1: Planning
+
+**1. Analyze Requirements**
+If not already described, ask: "What functionality do you want to build?"
+
+**2. Create Implementation Plan**
+Before any coding, create a detailed plan that **MUST follow this structure**:
+
+**Phase 1: Project Setup**
+- Create app with `@trackunit/iris-app:create [app-name]`
+- Create extensions with `@trackunit/iris-app:extend` (list each extension)
+- Start dev server in background
+
+**Phase 2: Browser Verification (CRITICAL GATE)**
+- Open browser to https://new.manager.trackunit.com/goto/iris-app-dev
+- Wait for user login (2-4 minutes)
+- Enable "Use Local Apps" toggle if not already enabled
+- Navigate to extension location based on type (see @browser-irisx-development):
+  - FLEET_EXTENSION: Main menu → App name
+  - ASSET_HOME_EXTENSION: Assets → Select asset → Extension tab
+  - SITE_HOME_EXTENSION: Sites → Select site → Extension tab
+  - WIDGET_EXTENSION: Dashboard → Add Widget → Find widget
+- Take snapshot to verify extension loads
+- Check console for errors
+- **STOP - Must confirm extension working in browser before Phase 3**
+
+**Phase 3: Feature Implementation (One at a Time)**
+For EACH feature, list as separate item:
+- Feature 1: [Name]
+  - Prerequisites: [GraphQL setup/scopes/packages needed for THIS feature only]
+  - Implementation: [What to build]
+  - Validation: Check lints (zero tolerance), then browser test
+  - Browser test: [What to verify]
+  
+- Feature 2: [Name]
+  - Prerequisites: [Any new tools needed for THIS feature]
+  - Implementation: [What to build]
+  - Validation: Check lints (zero tolerance), then browser test
+  - Browser test: [What to verify]
+
+(Continue for all features)
+
+**Phase 4: Final Verification**
+- Run lints on all files (zero errors)
+- End-to-end browser testing
+- Documentation completion
+
+**Plan Details:**
+- App name: [kebab-case, descriptive]
+- Extension types: [List types from @irisx-app-sdk]
+- Data sources: [GraphQL queries, CustomFields needed]
+- UI components: [Components from Trackunit library]
+- Manifest config: [Scopes, CSP headers if needed]
+
+**3. Present Plan to User**
+Show the complete plan with:
+- **Browser flow explicitly documented** in Phase 2 with the URL https://new.manager.trackunit.com/goto/iris-app-dev
+- Navigation steps for the specific extension type(s)
+- Browser-first workflow clearly outlined
+Confirm with user before proceeding.
+
+### Phase 2: Project Setup
+
+**4. Create App and Extensions ONLY**
+```bash
+npx nx generate @trackunit/iris-app:create [app-name]
+npx nx g @trackunit/iris-app:extend --name=[extension-name] --directory=[feature-name] --type=[EXTENSION_TYPE]
+```
+
+**5. Start Development Server Immediately**
+Run in background terminal right after creation:
+```bash
+npx nx run [app-name]:serve
+```
+
+**6. Open Browser and Verify Basics Work**
+**CRITICAL: Do this BEFORE any GraphQL setup or UI implementation**
+
+Follow the complete browser setup workflow in @browser-irisx-development:
+- Navigate to https://new.manager.trackunit.com/goto/iris-app-dev (NEVER localhost!)
+- Wait for user login (be patient, 2-4 minutes)
+- Enable "Use Local Apps" toggle in sidebar if not already enabled
+- Navigate to extension location based on type:
+  - FLEET_EXTENSION: Main menu → Look for app name
+  - ASSET_HOME_EXTENSION: Assets → Open any asset → Look for extension tab
+  - SITE_HOME_EXTENSION: Sites → Open any site → Look for extension tab
+  - WIDGET_EXTENSION: Dashboard → Add Widget → Find widget
+- Take snapshot to verify extension loads
+- Check console for errors using browser_console_messages
+
+**STOP HERE: Do not proceed to Phase 3 until extension is confirmed working in browser**
+
+### Phase 3: Iterative Feature Development
+
+**7. Create Documentation**
+Create `/docs/[app-name].md` following @structured-development with the plan and architecture.
+
+**8. For Each Feature in Plan (ONE AT A TIME)**
+
+For each feature, follow this exact workflow:
+
+**a) Setup prerequisites for this feature ONLY**:
+   - If feature needs GraphQL: Install GraphQL tools NOW
+     ```bash
+     npm install @trackunit/react-graphql-tools
+     npx nx generate @trackunit/react-graphql-tools:add-graphql --project=[project-name]
+     ```
+   - If feature needs specific scopes: Update manifest NOW
+   - If feature needs CustomFields: Configure manifest NOW
+   - Use Trackunit MCP to discover data/components needed for THIS feature
+
+**b) Implement the feature**:
+   - Write code changes for ONE feature only
+   - Keep changes small and focused (single metric, single UI component, etc.)
+   - If building multiple similar items (e.g., 3 KPI cards), do them one at a time
+
+**c) Check for lint and TypeScript errors**:
+   - Run `read_lints` on the files you just modified
+   - Fix ALL errors immediately
+   - Zero tolerance: Do not proceed with any linter or TypeScript errors
+   - Recheck after fixes to confirm all errors are resolved
+
+**d) Reload browser to test**:
+   - Follow reload strategy in @browser-irisx-development
+   - Check browser console and network tab for errors
+   - Verify the feature renders correctly
+   - Take screenshot if visual changes
+
+**f) Debug if needed**:
+   - Read console errors from browser
+   - Check network requests for GraphQL/API issues
+   - Adjust code and repeat from step c) (check lints, then reload browser) until feature works
+   - DO NOT move forward until this feature is working
+
+**g) Update documentation**:
+   - Mark feature as completed in `/docs/[app-name].md`
+   - Document any important findings or gotchas
+
+**h) Move to next feature**:
+   - Only proceed when current feature is verified working in browser with zero errors
+   - Repeat entire process for next feature in plan
+
+**9. Continuous Validation Rules**
+Throughout all of Phase 3:
+- After EVERY code change: Check lints first, then reload browser (@browser-irisx-development)
+- Fix ALL lint and TypeScript errors immediately (zero tolerance)
+- Check browser console for errors after each reload
+- Never implement multiple features without full validation between them
+
+### Phase 4: Completion
+
+**10. Final Verification**
+- Run `read_lints` on all modified files to ensure zero errors
+- Test all features end-to-end in browser (@browser-irisx-development)
+- Verify data loads correctly (real GraphQL data)
+- Take screenshots of working features
+
+**11. Summary**
+Inform the user:
+- All features implemented and verified in browser with zero errors
+- No linter or TypeScript errors remaining
+- Documentation at `docs/[app-name].md`
+- App running at local dev server
+- **Important**: User must deploy via Trackunit marketplace (never auto-submit)
+
+## Critical Development Rules
+
+### Strict Browser-First Workflow
+**Follow this exact order:**
+
+1. Create app + extensions
+2. Start dev server immediately
+3. Open browser and verify extension loads (@browser-irisx-development)
+4. **STOP - Do not proceed without browser verification**
+5. Implement ONE feature with prerequisites
+6. Check lints and fix ALL errors (zero tolerance)
+7. Reload browser and verify that ONE feature (@browser-irisx-development)
+8. Repeat steps 5-7 for each remaining feature
+
+### Feature Implementation Rules
+- **One feature at a time** - even if building similar components
+- **Prerequisites on-demand** - set up GraphQL/scopes only when needed for current feature
+- **Zero tolerance for errors** - fix all lint and TypeScript errors immediately after code changes
+- **Test completely** - verify working in browser before moving on
+- **Small incremental changes** - easier to debug when issues arise
+- **Continuous validation** - lint check, then browser test after every change
+
+### Validation Checklist
+After EVERY code change:
+1. Run `read_lints` on modified files
+2. Fix ALL linter and TypeScript errors (zero tolerance)
+3. Reload browser (see @browser-irisx-development for reload strategy)
+4. Check browser console and network tab for errors
+5. Verify UI renders correctly
+6. Take screenshot if visual changes
+7. Fix any issues before proceeding
+
+### Data & UI Development
+- **GraphQL**: Use Trackunit MCP `introspect-schema` and `validate-query`, then implement per @irisx-app-sdk-graphql
+- **Components**: Use Trackunit MCP `get-story-code` to find patterns, implement, verify in browser
+- **Real Data**: Always use Trackunit GraphQL API, never mock data unless explicitly requested

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

@@ -0,0 +1,246 @@
+# 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/irisx-app-sdk.mdc

@@ -77,4 +77,6 @@ IrisX Apps have access to runtime hooks from `@trackunit/react-core-hooks` that
 
 DO NOT use generic React/Node.js commands for project creation or management - always use the Trackunit IrisX App SDK commands.
 
+**Before completing any task**: Always use `read_lints` to check for and fix all ESLint and TypeScript errors in modified files.
+