cognite-create 0.2.15 → 0.2.18

package/templates/.cursor/rules/development.mdc

@@ -0,0 +1,90 @@
+---
+alwaysApply: true
+---
+
+# AGENTS.md - Developer & AI Assistant Onboarding Guide
+
+Important rules:
+
+- Always use the design system provided. cdf-design-system-alpha.
+- Check often for typescript errors, and resolve them as they come. Especially after big changes.
+- When making types for schemas that are represented in data modelling, fetch the details of that view first from CDF.
+- Always use the design system provided. cdf-design-system-alpha.
+
+## 1. Project Overview
+
+This application is a React-based web application. You will build a react application to the spec that the user provides. You will also help define that spec according to the details in this document. You are provided with some boiler plate. Do not touch the `/src/infrastructure` folder, only use its components when needed.
+
+## 2. Core Technologies
+
+- **Language:** TypeScript
+- **Framework:** React 17 with Vite.
+- **State Management:** React context
+- **Styling:** Tailwind + Cognite Design System (cdf-design-system-alpha)[node_modules/cdf-design-system-alpha/AI_USAGE_GUIDE.md]
+- **Data Fetching:** React Query + Cognite SDK (@cognite/sdk)
+- **Testing:** Vitest & Playwright
+- **Package Manager:** npm
+- **Authentication:** Use provided components
+- **Other tools:**: Storybook
+
+## 3. Development Environment Setup
+
+1. **Prerequisites:** Ensure you have Node.js v22+ and Yarn installed
+2. **Install dependencies:** `npm install`
+3. **Environment setup:**
+   - Ensure `cdf.yml` has been populated by the user
+4. **Start development server:** `npm start`
+   - Runs on `http://localhost:5000` by default
+   - Uses hot reloading for development
+
+## 4. Coding Style & Design Principles
+
+### Architecture Patterns
+
+- **Component Structure:** Functional components with hooks, organized by feature in `/components`
+- **Custom Hooks:** Extensive use of custom hooks for business logic (`/hooks`)
+- **Service Layer:** Cognite SDK integration through centralized client (`/services`)
+
+### Code Style Guidelines
+
+- **Import Organization:** Avoid barrel imports
+- **File Organization:** Co-locate related files (component + types + styles)
+- **State Management:** Prefer React Context for global state, local state for component-specific data
+- **Error Handling:** Use React Error Boundaries and proper error states
+
+### Key Conventions
+
+- **Exports:** Avoid default exports
+- **Async Operations:** Use react-query
+- **Styling:** Tailwind CSS with Cognites design system
+- **Testing:** Test files co-located with components using `.test.tsx` extension
+
+## 5. Styling
+
+When asked to style, never use inline styles. Always use as much as possible the design system provided through `cdf-design-system-alpha`. Use tailwindcss actively. See here for more details. (cdf-design-system-alpha)[node_modules/cdf-design-system-alpha/AI_USAGE_GUIDE.md]
+
+## 6. Anything Else to Know?
+
+### Project Structure Highlights
+
+- **`/src/components`**: Feature-based component organization
+- **`/src/pages`**: Top-level page components and routing
+- **`/src/hooks`**: Reusable custom hooks for business logic
+- **`/src/services`**: Services connecting to external data and systems
+- **`/src/config`**: Environment and application configuration
+- **`/src/infrastructure`**: DO NOT EDIT THIS FOLDER. It contains important infrastructure. Use its components as stated
+
+### Important Notes
+
+- **Cognite Integration:** Heavy integration with Cognite Data Fusion APIs for industrial data
+- **Design system:** Exclusively use components from cdf-design-system-alpha, unless the component does not exist in the library. (cdf-design-system-alpha)[node_modules/cdf-design-system-alpha/AI_USAGE_GUIDE.md] contains an AI usage guide.
+
+### Infrastructure
+
+The `/src/infrastructure` folder contains important react components used to enable the application to be run not only in a standalone environment, but also within Cognite Fusion - another web application. It handles the authentication for you, among other things, and will provide you an SDK to connect to CDF.
+
+- `useCDF` will give you an SDK.
+
+### Development Tips
+
+- The app connects to Cognite's industrial data platform, so some features require proper API access

package/templates/.cursor/rules/general.mdc

@@ -6,4 +6,30 @@ alwaysApply: true
 
 Use the ShadCN MCP server to list the Cognite registry for components you can use. If there are no Cognite components fit for purpose, fallback to ShadCN registry ones. When building from reference, make sure to include all components in the reference material in your final build. Do not edit the styling of Cognite components.
 
-Run `pnpm lint` after your changes to make sure you have fixed all potential errors.
+Always use semantic Tailwind color classes (e.g., bg-primary, text-primary, border-primary) instead of arbitrary color values (e.g., bg-blue-600, text-red-500). This ensures consistency with the design system.
+
+Run `pnpm lint` after your changes to make sure you have fixed all potential errors.
+
+When setting up auth rememeber to set up the oidcTokenProvider.
+
+Use this function to get the token string:
+
+export const getToken = async (clientId: string, clientSecret: string) => {
+  const header = "Basic " + btoa(`${clientId}:${clientSecret}`);
+
+  const response = await fetch("https://auth.cognite.com/oauth2/token", {
+    method: "POST",
+    headers: {
+      Authorization: header,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({
+      grant_type: "client_credentials",
+    }),
+  });
+
+  const data = await response.json();
+
+  console.log("Token response:", data);
+  return data.access_token;
+};

package/templates/.cursor/rules/requirements-gathering.mdc

@@ -0,0 +1,24 @@
+---
+description: When asked to develop a set of requirements for an application.
+alwaysApply: false
+---
+
+USE THE TEMPLATE PROVIDED VIA docs/TEMPLATE_REQUIREMENTS.MD.
+
+Generate a comprehensive requirements document for a new application. The application will be a web-based dashboard and reporting tool for monitoring industrial asset performance. The core data model is based on CDF (Cognite Data Fusion). The requirements document should include the following sections:
+
+Introduction: A high-level overview of the application's purpose and its target users.
+
+Functional Requirements: A detailed list of what the application must do, including data visualization, reporting, user authentication, and interaction with CDF. Specify how data will be retrieved (e.g., using Cognite's APIs for time series. DO NOT USE ASSETS. Only use Data modelling), transformed, and presented.
+
+Non-Functional Requirements: Cover aspects like performance (e.g., dashboard load times), security (e.g., user roles and permissions mapped to CDF's security model), scalability, and usability.
+
+Data Model & Integration: Describe how the application's data model maps directly to the CDF data model. This section is crucial and must detail the specific CDF core data models and how they will be used to structure the application's data. Include details on how the application will use CDF's asset hierarchy to navigate and filter data. Define new view structures when needed
+
+User Stories: Create a set of user stories that encapsulate the key features from the functional requirements, written from the perspective of a typical user (e.g., a plant manager or a maintenance engineer).
+
+Technology Stack: Always use what is defined in the development.mdc rule.
+
+Ensure the document is structured with clear headings and a professional tone. The output should be a detailed, well-organized document that can serve as a blueprint for the development team.
+
+USE THE TEMPLATE PROVIDED VIA docs/TEMPLATE_REQUIREMENTS.MD.

package/templates/.env.example

@@ -0,0 +1,8 @@
+# Cognite Configuration
+NEXT_PUBLIC_COGNITE_PROJECT=your-project-name
+NEXT_PUBLIC_COGNITE_BASE_URL=https://api.cognitedata.com
+
+# OIDC Authentication (Required for production)
+NEXT_PUBLIC_COGNITE_CLIENT_ID=your_client_id
+NEXT_PUBLIC_COGNITE_TENANT_ID=6a5949bb-8ea1-4bd1-aa0a-4d03846de30e
+COGNITE_CLIENT_SECRET=your_client_secret

package/templates/README.MD

@@ -0,0 +1,198 @@
+# CDF Application Template
+
+A React application template for building applications with Cognite Data Fusion (CDF) using AI assistance.
+
+## Prerequisites
+
+This project requires Node.js v22 or higher and npm (Node Package Manager).
+
+**Don't have Node.js installed?** See [Installing Node.js and npm](#installing-nodejs-and-npm) at the bottom of this document.
+
+## Initial Setup
+
+1. **Configure your app:** Fill in `app.json` with your application details
+2. **Install dependencies:** `npm install`
+3. **Start development server:** `npm start`
+4. **Deploy to CDF:** `npm run deploy`
+
+### Optional: Enable Fast Deployment & MCP Server
+
+Create a `.env` file with your CDF credentials:
+
+```
+CLIENT_ID=your-client-id
+CLIENT_SECRET=your-client-secret
+```
+
+This enables:
+
+- **Faster CI deployment:** `npm run deploy:ci`
+- **MCP server for Cursor:** AI can query and create data models directly in CDF
+
+## Features
+
+- **MCP Server Integration:** Query CDF data models, spaces, views, and containers directly through Cursor
+- **Cognite Design System:** Pre-configured `cdf-design-system-alpha` for consistent UI styling
+- **Requirements Template:** Structured template to guide AI in building your application
+- **Authentication Included:** Ready-to-use auth for both local development and CDF hosting
+- **Data Modeling Support:** AI can help structure and connect to CDF data models
+
+## Building Your Application
+
+### 1. Request a Requirements Doc
+
+Ask your AI assistant to create requirements based on your input:
+
+```
+"Write me a set of requirements for an application that [describe your needs]"
+```
+
+Review the generated requirements carefully. Add, remove, or modify as needed.
+
+### 2. Review Requirements List
+
+Go through the requirements document line by line. Make sure it accurately captures what you want to build.
+
+### 3. Request a Dummy Data Version
+
+Start with a working prototype using mock data:
+
+```
+"Build a dummy data version of this application based on the requirements"
+```
+
+### 4. Build and Iterate
+
+Run `npm start` and test your application. Iterate on the UI, functionality, and user experience with your AI assistant.
+
+### 5. Connect to CDF (Step by Step)
+
+Once satisfied with the prototype, connect it to real CDF data:
+
+```
+"Let's connect this to CDF data models. Start by creating the space and containers we need."
+```
+
+Take this **step by step** - this is where you're most likely to run into issues. Create spaces, then containers, then views, then connect your UI.
+
+## Tips and Tricks
+
+### Important Warnings
+
+⚠️ **If you get errors:** Copy-paste the error into Cursor. If it doesn't work after 3 attempts, ask it to simplify the approach.
+
+⚠️ **Don't try to implement notifications** - This rarely works well
+
+⚠️ **Don't extend existing data models** - It will likely not work. Create new views instead.
+
+⚠️ **Don't delete data models** - You can't easily recover them
+
+⚠️ **Limited availability:** Only enabled for select Cognite projects (e.g., lervik, atlas). Not to be used in customer projects.
+
+⚠️ **Commit after every step** - Version control saves you from having to rebuild everything
+
+### Helpful Prompts
+
+- Open browser console to see errors, paste them into Cursor
+- If AI isn't using the design system: "Please use the cdf-design-system-alpha design system"
+- To get correct types: "Fetch the [ViewName] view from CDF and use that to define the type"
+- To check data models: "List the available views in the [space_name] space"
+
+## Environment Variables
+
+Your `.env` file (optional, for MCP and fast deployment):
+
+```
+CLIENT_ID=your-client-id
+CLIENT_SECRET=your-client-secret
+```
+
+## Development Commands
+
+- `npm start` - Start development server
+- `npm run build` - Build for production
+- `npm run lint` - Run linter
+- `npm run deploy` - Deploy to CDF
+- `npm run deploy:ci` - Fast deployment (requires .env)
+
+## Security
+
+- Never commit `.env` files
+- Environment files are automatically ignored by git
+- Use service account credentials for deployment only
+
+---
+
+## Installing Node.js and npm
+
+This project requires Node.js v22 or higher and npm (Node Package Manager).
+
+### macOS
+
+**Option 1: Using Homebrew (recommended)**
+
+```bash
+# Install Homebrew if you don't have it
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Node.js (includes npm)
+brew install node@22
+```
+
+**Option 2: Using the official installer**
+
+1. Download the installer from [nodejs.org](https://nodejs.org/)
+2. Choose the LTS (Long Term Support) version
+3. Run the installer and follow the prompts
+
+### Windows
+
+**Option 1: Using the official installer (recommended)**
+
+1. Download the installer from [nodejs.org](https://nodejs.org/)
+2. Choose the LTS (Long Term Support) version
+3. Run the `.msi` installer and follow the prompts
+4. Restart your terminal/command prompt
+
+**Option 2: Using Chocolatey**
+
+```powershell
+# Install Chocolatey if you don't have it
+Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+
+# Install Node.js
+choco install nodejs-lts
+```
+
+### Linux
+
+**Ubuntu/Debian:**
+
+```bash
+# Install Node.js 22.x
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+**Fedora/RHEL/CentOS:**
+
+```bash
+# Install Node.js 22.x
+curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
+sudo yum install -y nodejs
+```
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S nodejs npm
+```
+
+### Verify Installation
+
+After installation, verify that Node.js and npm are installed correctly:
+
+```bash
+node --version  # Should show v22.x.x or higher
+npm --version   # Should show 10.x.x or higher
+```