@trackunit/iris-app 1.12.9 → 1.12.11

package/src/generators/preset/files/.agents/skills/create-app/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: create-app
+description: Use when building a new IrisX App from scratch, user asks to create an app, or starting a new extension project.
+---
+
+# Create IrisX App
+
+## Overview
+
+Create IrisX Apps using browser-driven iterative development. Real data first (GraphQL API), verify each feature in browser before proceeding.
+
+## When to Use
+
+- User asks to create a new IrisX App
+- Starting a new extension project
+- Building a complete app from requirements
+
+**Not for:** Modifying existing extensions (use domain-specific skills).
+
+## Core Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| Real Data First | Use GraphQL API, never mock unless requested |
+| Browser Testing | Verify each change at `manager.trackunit.com/goto/iris-app-dev` |
+| Chrome DevTools MCP | Required for iFrame-based extension testing |
+| One Feature at a Time | Complete and verify before moving on |
+| Zero Tolerance for Errors | Fix all lint/TypeScript errors immediately |
+
+## Chrome DevTools MCP Requirement
+
+**IrisX Apps render inside iFrames.** Standard browser automation cannot interact with iFrame content.
+
+Before starting browser testing:
+1. Verify Chrome DevTools MCP is available (check for `user-chrome-devtools` server)
+2. If not available, see `browser-testing` skill for setup instructions
+3. Use Chrome DevTools tools (`take_screenshot`, `click`, `evaluate_script`, etc.) for all browser interactions
+
+## Development Workflow
+
+### Phase 1: Planning
+
+**1. Analyze Requirements**
+
+If not already described, ask: "What functionality do you want to build?"
+
+**2. Create Implementation Plan**
+
+Structure the plan as:
+
+- **Phase 1: Project Setup**
+  - Create app with `@trackunit/iris-app:create`
+  - Create extensions with `@trackunit/iris-app:extend`
+  - Start dev server in background
+
+- **Phase 2: Browser Verification (CRITICAL GATE)**
+  - Verify Chrome DevTools MCP is available (required for iFrame testing)
+  - Open browser to `https://new.manager.trackunit.com/goto/iris-app-dev`
+  - Wait for user login (2-4 minutes)
+  - Enable "Use Local Apps" toggle
+  - Navigate to extension location
+  - Use Chrome DevTools `take_screenshot` to verify extension renders
+  - **STOP - Must confirm extension working before Phase 3**
+
+- **Phase 3: Feature Implementation (One at a Time)**
+  - For each feature:
+    - Prerequisites (GraphQL setup/scopes needed)
+    - Implementation
+    - Validation: Check lints, browser test
+    - Browser test: What to verify
+
+- **Phase 4: Final Verification**
+  - Zero linter/TypeScript errors
+  - End-to-end browser testing
+  - Documentation completion
+
+**3. Present Plan to User**
+
+Confirm before proceeding.
+
+### Phase 2: Project Setup
+
+**4. Create App and Extensions**
+
+```bash
+npx nx generate @trackunit/iris-app:create [app-name]
+npx nx g @trackunit/iris-app:extend --name=[extension-name] --app=[app-name] --directory=[feature] --type=[EXTENSION_TYPE]
+```
+
+**5. Start Development Server**
+
+```bash
+npx nx run [app-name]:serve
+```
+
+**6. Open Browser and Verify**
+
+**CRITICAL: Do this BEFORE any GraphQL setup or UI implementation**
+
+1. Navigate to `https://new.manager.trackunit.com/goto/iris-app-dev`
+2. Wait for user login
+3. Enable "Use Local Apps" toggle
+4. Navigate to extension based on type
+5. Take snapshot to verify extension loads
+6. Check console for errors
+
+**STOP HERE: Do not proceed until extension is confirmed working**
+
+### Phase 3: Iterative Feature Development
+
+**7. Create Documentation**
+
+Create `/docs/[app-name].md` with the plan and architecture.
+
+**8. For Each Feature (ONE AT A TIME)**
+
+**a) Setup prerequisites for this feature ONLY:**
+```bash
+# If feature needs GraphQL:
+npm install @trackunit/react-graphql-tools
+npx nx generate @trackunit/react-graphql-tools:add-graphql --project=[project-name]
+```
+
+**b) Implement the feature:**
+- Write code changes for ONE feature only
+- Keep changes small and focused
+
+**c) Check for lint and TypeScript errors:**
+- Run `read_lints` on modified files
+- Fix ALL errors immediately
+- Zero tolerance: Do not proceed with any errors
+
+**d) Reload browser to test:**
+- Check browser console and network tab for errors
+- Verify the feature renders correctly
+- Take screenshot if visual changes
+
+**e) Debug if needed:**
+- Read console errors
+- Check network requests
+- Adjust code and repeat
+- **DO NOT** move forward until feature works
+
+**f) Update documentation:**
+- Mark feature as completed
+
+**g) Move to next feature:**
+- Only proceed when current feature is verified working
+
+### Phase 4: Completion
+
+**9. Final Verification**
+
+- Run `read_lints` on all modified files
+- Test all features end-to-end in browser
+- Verify data loads correctly
+
+**10. Summary**
+
+Inform the user:
+- All features implemented and verified
+- No linter or TypeScript errors remaining
+- Documentation complete
+- **Important**: User must deploy via Trackunit marketplace (never auto-submit)
+
+## Critical Rules
+
+### Feature Implementation
+- **One feature at a time** - even for similar components
+- **Prerequisites on-demand** - setup GraphQL/scopes only when needed
+- **Zero tolerance for errors** - fix all lint/TypeScript errors immediately
+- **Test completely** - verify working in browser before moving on
+
+### Validation Checklist (After Every Code Change)
+1. Run `read_lints` on modified files
+2. Fix ALL linter and TypeScript errors
+3. Reload browser
+4. Check browser console and network tab
+5. Verify UI renders correctly
+6. Fix any issues before proceeding
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using default browser automation | Use Chrome DevTools MCP (iFrames require it) |
+| Starting implementation before browser verification | Complete Phase 2 (browser gate) first |
+| Implementing multiple features at once | One feature, fully verified, then next |
+| Using mock data without asking | Always use real GraphQL API |
+| Skipping lint check | Zero tolerance - run `read_lints` after every change |
+| Auto-submitting to marketplace | Never auto-submit; instruct user to do so |

package/src/generators/preset/files/.agents/skills/customfields/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: customfields
+description: Use when storing app data on entities, persisting user input, defining custom fields in manifest, or reading/writing entity-specific data.
+---
+
+# CustomFields
+
+## Overview
+
+CustomFields extend the Trackunit data model by storing additional information on entities (assets, accounts, groups, sites). This is the primary mechanism for persisting IrisX app data.
+
+## When to Use
+
+- Storing user input or preferences
+- Adding metadata to assets/accounts/groups/sites
+- Persisting app-specific configuration
+- Creating custom KPIs or fleet attributes
+
+**Not for:** External databases or storage solutions (use CustomFields instead).
+
+## Defining Custom Fields
+
+### Manifest Configuration
+
+```typescript
+customFieldDefinitions: [
+  {
+    type: 'STRING',
+    entityType: 'ASSET',
+    key: 'myCustomField',
+    translations: [{
+      language: 'en',
+      title: 'My Custom Field',
+      description: 'Description of what this field stores',
+    }],
+    uiEditable: true,
+    uiVisible: true,
+    scopeType: 'ACCOUNT' // or 'ACCOUNT_WRITE_GLOBAL_READ' or 'GLOBAL'
+  }
+]
+```
+
+### Required Properties
+
+| Property | Description |
+|----------|-------------|
+| `type` | Field data type |
+| `entityType` | `ACCOUNT`, `ASSET`, `GROUP`, or `SITE` |
+| `key` | Programmatic identifier (immutable after creation) |
+| `translations` | UI labels and descriptions |
+| `scopeType` | Data access scope |
+
+### Optional Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `uiEditable` | `true` | Can be edited in Manager UI |
+| `uiVisible` | `true` | Visible in Manager UI |
+
+## Supported Field Types
+
+| Type | Description | Extra Properties |
+|------|-------------|------------------|
+| `BOOLEAN` | True/false values | - |
+| `DATE` | ISO8601 formatted dates | - |
+| `DROPDOWN` | Predefined option lists | `allValues`, `multiSelect`, `valueReplacements` |
+| `EMAIL` | Email addresses with mailto links | - |
+| `NUMBER` | Numeric values | `minimum`, `maximum`, `isInteger`, `unitSi`, `unitUs` |
+| `PHONE_NUMBER` | E.164 formatted phone numbers | - |
+| `STRING` | Free text | `minimumLength`, `maximumLength`, `pattern` |
+| `STRING_LIST` | Array of strings | - |
+| `WEB_ADDRESS` | URLs as clickable links | - |
+| `JSON` | JSON objects | - |
+| `FILE` | File attachments | - |
+| `MONETARY` | Currency values (ISO 4217) | `currency` |
+
+## Example Field Definitions
+
+### String with Validation
+
+```typescript
+{
+  type: 'STRING',
+  entityType: 'ASSET',
+  key: 'serialNumber',
+  translations: [{ language: 'en', title: 'Serial Number', description: 'Asset serial number' }],
+  minimumLength: 5,
+  maximumLength: 20,
+  pattern: '^[A-Z0-9]+$'
+}
+```
+
+### Number with Units
+
+```typescript
+{
+  type: 'NUMBER',
+  entityType: 'ASSET',
+  key: 'fuelCapacity',
+  translations: [{ language: 'en', title: 'Fuel Capacity', description: 'Tank capacity' }],
+  minimum: 0,
+  maximum: 1000,
+  unitSi: 'L',
+  unitUs: 'gal'
+}
+```
+
+### Dropdown with Multiple Selection
+
+```typescript
+{
+  type: 'DROPDOWN',
+  entityType: 'ASSET',
+  key: 'features',
+  translations: [{ language: 'en', title: 'Features', description: 'Available features' }],
+  allValues: ['GPS', 'Camera', 'Bluetooth', 'WiFi'],
+  multiSelect: true
+}
+```
+
+## Scope Types
+
+| Scope | Description |
+|-------|-------------|
+| `ACCOUNT` | Values shared within a single account only |
+| `ACCOUNT_WRITE_GLOBAL_READ` | Account can write, all accounts can read |
+| `GLOBAL` | Values shared between all accounts with entity access |
+
+## Using CustomFields in React
+
+### Required Imports
+
+```typescript
+import { 
+  useCustomFieldsValueAndDefinition,
+  useUpdateCustomFieldValues
+} from '@trackunit/custom-field-api';
+import { CustomField } from '@trackunit/custom-field-components';
+import { useCurrentUserSystemOfMeasurement } from '@trackunit/react-core-hooks';
+```
+
+### Basic Implementation
+
+```typescript
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { Card, CardBody, CardHeader, CardFooter, Button, Spinner } from '@trackunit/react-components';
+import { useCustomFieldsValueAndDefinition, useUpdateCustomFieldValues } from '@trackunit/custom-field-api';
+import { CustomField } from '@trackunit/custom-field-components';
+import { useCurrentUserSystemOfMeasurement } from '@trackunit/react-core-hooks';
+
+const CustomFieldsForm = ({ assetId }: { assetId: string }) => {
+  const { register, handleSubmit, formState, setValue, control } = useForm({
+    shouldUnregister: false,
+  });
+  
+  const { systemOfMeasurement } = useCurrentUserSystemOfMeasurement();
+  
+  const { fields, loading } = useCustomFieldsValueAndDefinition({
+    entityType: "ASSET",
+    entityId: assetId,
+    systemOfMeasurement: systemOfMeasurement ?? "SI",
+  });
+  
+  const { updateCustomFields, inProgress } = useUpdateCustomFieldValues(
+    assetId,
+    "ASSET",
+    fields,
+    systemOfMeasurement ?? "SI"
+  );
+
+  if (loading) return <Spinner />;
+
+  return (
+    <Card>
+      <CardHeader heading="Custom Fields" />
+      <CardBody>
+        {fields.map(field => {
+          const isEditable = field.valueEditable && (field.definition.uiEditable ?? true);
+          return (
+            <CustomField
+              key={field.definition.key}
+              control={control}
+              field={field}
+              formState={formState}
+              isEditable={isEditable}
+              register={register}
+              setValue={setValue}
+              unitPreference={systemOfMeasurement}
+            />
+          );
+        })}
+      </CardBody>
+      <CardFooter>
+        <Button 
+          loading={inProgress} 
+          onClick={handleSubmit(updateCustomFields)}
+        >
+          {inProgress ? "Saving..." : "Save Changes"}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+};
+```
+
+## Best Practices
+
+### Field Design
+- **Use descriptive keys**: Choose clear, descriptive field keys that won't need changing
+- **Add proper translations**: Always provide meaningful titles and descriptions
+- **Set appropriate constraints**: Use min/max values, length limits, and patterns for validation
+
+### Performance
+- **Batch updates**: Use `useUpdateCustomFieldValues` to update multiple fields at once
+- **Handle loading states**: Always show loading indicators while fetching data
+- **Error handling**: Implement proper error handling for failed updates
+
+### Deployment
+- **Field keys are immutable**: Cannot be changed after creation
+- **Definition updates**: Changing field definitions affects all existing data
+- **Approval process**: Custom field changes require app approval and marketplace submission
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Changing field key after creation | Keys are immutable; plan carefully upfront |
+| Missing translations | Always provide titles and descriptions for UI |
+| Using external storage | CustomFields are the recommended persistence mechanism |
+| No loading states | Show `<Spinner />` while fetching data |
+| Skipping error handling | Handle failed updates gracefully |
+
+## References
+
+- [Save Data from Your App](https://developers.trackunit.com/docs/save-data-from-your-app)
+- [Defining a Custom Field](https://developers.trackunit.com/docs/defining-a-custom-field)
+- [Using a Custom Field](https://developers.trackunit.com/docs/using-a-custom-field)
+- [Deploying a New Custom Field](https://developers.trackunit.com/docs/deploying-a-new-custom-field)

package/src/generators/preset/files/.agents/skills/graphql/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: graphql
+description: Use when setting up GraphQL tooling, writing queries/mutations, generating hooks, or fetching data from Trackunit API.
+---
+
+# GraphQL API Integration
+
+## Overview
+
+Trackunit exposes a GraphQL API with NX executors for code generation. Use `@trackunit/react-graphql-tools` to generate typed React hooks from `.graphql` files.
+
+## When to Use
+
+- Setting up GraphQL in an extension
+- Writing queries or mutations
+- Generating React hooks from `.graphql` files
+- Fetching data from Trackunit API
+
+**Not for:** Time series data (use `graphql-timeseries` skill).
+
+## Setup
+
+### Install GraphQL Tools
+
+```bash
+npm install @trackunit/react-graphql-tools
+```
+
+### Set Up GraphQL Tooling
+
+```bash
+npx nx generate @trackunit/react-graphql-tools:add-graphql --project=[project-name]
+```
+
+Where `[project-name]` is found in the library's `project.json` file (format: `[subdir-name]-[extension-name]` for extensions in subdirectories).
+
+### Generate React Hooks
+
+```bash
+npx nx run [feature-name]-[extension-name]:graphql-hooks
+```
+
+This generates React hooks from `.graphql` files in the `src` folder.
+
+## GraphQL File Structure
+
+Create `.graphql` files in `libs/[feature-name]/[extension-name]/src/` directory.
+
+### Query Syntax
+
+```graphql
+query QueryName($variable: Type) {
+  fieldName {
+    subField
+  }
+}
+```
+
+### Mutation Syntax
+
+```graphql
+mutation MutationName($variable: Type!) {
+  mutationField(input: $variable) {
+    result
+  }
+}
+```
+
+## React Integration
+
+### Import Generated Hooks
+
+```typescript
+import { QueryNameDocument } from "./generated/graphql-api/graphql";
+```
+
+### Use Queries
+
+```typescript
+import { useQuery } from '@trackunit/react-graphql-hooks';
+
+const { data, loading, error } = useQuery(QueryNameDocument, {
+  variables: { /* your variables */ }
+});
+```
+
+### Use Mutations
+
+```typescript
+import { useMutation } from '@apollo/client';
+
+const [mutationName, { data, loading, error }] = useMutation(MutationNameDocument);
+```
+
+## Common Patterns
+
+### Query with Variables
+
+```typescript
+const { data, loading, error } = useQuery(GetAssetDocument, {
+  variables: { assetId: "123" }
+});
+
+if (loading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+
+return <AssetDisplay asset={data?.asset} />;
+```
+
+### Mutation with Refetch
+
+```typescript
+import { useMutation } from '@apollo/client';
+
+const [updateAsset, { loading }] = useMutation(UpdateAssetDocument, {
+  refetchQueries: [{ query: GetAssetDocument, variables: { assetId } }]
+});
+
+const handleUpdate = async (input) => {
+  await updateAsset({ variables: { input } });
+};
+```
+
+### Polling
+
+```typescript
+const { data } = useQuery(GetAssetsDocument, {
+  pollInterval: 5000, // Poll every 5 seconds
+});
+```
+
+## References
+
+- [Calling Trackunit GraphQL API](https://developers.trackunit.com/docs/graphql-api)
+- [Apollo useQuery documentation](https://www.apollographql.com/docs/react/data/queries)
+- [Apollo useMutation documentation](https://www.apollographql.com/docs/react/data/mutations)
+- [GraphQL Code Generator](https://the-guild.dev/graphql/codegen)
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using generic GraphQL libraries | Use `@trackunit/react-graphql-tools` only |
+| Missing hook generation | Run `nx run [project]:graphql-hooks` after adding `.graphql` files |
+| Wrong project name format | Use `[subdir-name]-[extension-name]` from `project.json` |
+| No loading/error states | Always handle `loading` and `error` from hooks |
+| Importing from wrong path | Import from `./generated/graphql-api/graphql` |