@cognite/cli 0.5.2 → 0.6.0-alpha.8

package/_templates/app/new/cursor/mcp.json.ejs.t

@@ -0,0 +1,10 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>.cursor/mcp.json'
+---
+{
+  "mcpServers": {
+    "cdf-datamodeling-mcp": {
+      "command": "npx cdf-datamodelling-mcp-server"
+    }
+  }
+}

package/_templates/app/new/cursor/rules.mdc.ejs.t

@@ -0,0 +1,10 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>.cursor/rules/rules.mdc'
+---
+---
+description: Describes global rules
+alwaysApply: true
+---
+
+- Use direct `@cognite/aura/components` exports whenever Aura provides the component you need. Fall back to custom markup only when Aura does not expose an equivalent primitive.
+- Follow the SPEC.md handling rules in `AGENTS.md` §0.

package/_templates/app/new/github/ci.yml.ejs.t

@@ -0,0 +1,36 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>.github/workflows/ci.yml'
+---
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint-test-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build

package/_templates/app/new/prompt.js

@@ -0,0 +1,49 @@
+export default [
+  {
+    type: 'input',
+    name: 'name',
+    message: 'What is the app name? (use kebab-case, e.g., my-awesome-app)',
+    initial: 'my-dune-app',
+    validate: (input) =>
+      /^[a-z][a-z0-9-]*$/.test(input)
+        ? true
+        : 'App name must be kebab-case (lowercase, hyphens only)',
+  },
+  {
+    type: 'input',
+    name: 'displayName',
+    message: 'What is the display name? (e.g., My Awesome App)',
+    initial: 'My Dune app',
+  },
+  {
+    type: 'input',
+    name: 'description',
+    message: 'What is the app description?',
+    initial: 'A Dune application',
+  },
+  {
+    type: 'input',
+    name: 'org',
+    message: 'Deployment org? (e.g., cog-demo, cog-atlas)',
+    initial: 'cog-demo',
+  },
+  {
+    type: 'input',
+    name: 'project',
+    message: 'Deployment project? (e.g., lervik-industries, atlas-greenfield)',
+    initial: 'lervik-industries',
+  },
+  {
+    type: 'input',
+    name: 'cluster',
+    message: 'Cluster? (e.g., greenfield, westeurope-1, api)',
+    initial: 'api',
+  },
+  {
+    type: 'input',
+    name: 'baseUrl',
+    // initial is set dynamically in create-prompter based on the cluster answer
+    message: 'Base URL? (e.g. https://az-arn-004.cognitedata.com)',
+    initial: 'https://api.cognitedata.com',
+  },
+];

package/_templates/app/new/root/.npmrc.ejs.t

@@ -0,0 +1,4 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>.npmrc'
+---
+engine-strict=true

package/_templates/app/new/root/AGENTS.md.ejs.t

@@ -0,0 +1,215 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>AGENTS.md'
+---
+# Coding Standards
+
+<% if (useSpecKit) { -%>
+## 0. Product Spec (spec-driven development)
+
+This app uses [github/spec-kit](https://github.com/github/spec-kit) for spec-driven development. Specs live under `specs/<NNN>-<feature-name>/spec.md`, one directory per feature.
+
+- To start a new feature, run `/speckit.specify <description>` in Claude Code or Cursor. It generates a properly numbered feature directory and a spec to fill in. Then run `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement`.
+- When user-visible behavior changes in an existing feature, update its `specs/<NNN>-<feature>/spec.md` before or alongside the code change.
+- When a feature touches Cognite Data Fusion data, the spec must document existing CDF views read from, new views needed, and spaces used.
+<% } else { -%>
+## 0. Product Spec (SPEC.md)
+
+`SPEC.md` at the repo root is the living product spec for this app. Read it before making feature decisions, and keep it in sync with user-visible behavior.
+
+- If `SPEC.md` is empty or contains only commented `<!-- -->` placeholders, proactively offer to populate it before writing implementation code. Do not silently skip.
+- When user-visible behavior changes, update the relevant `SPEC.md` section before or alongside the code change.
+<% } -%>
+
+---
+
+## 1. Dependency Injection
+
+Inject dependencies via React context (hooks/components) or factory-override pattern (plain functions). Never hard-code dependencies.
+
+### React context
+
+```typescript
+const defaultDeps = { useDataSource, useAnalytics };
+export type MyHookContextType = typeof defaultDeps;
+export const MyHookContext = createContext<MyHookContextType>(defaultDeps);
+
+export function useMyHook() {
+  const { useDataSource } = useContext(MyHookContext);
+}
+```
+
+### Factory overrides
+
+```typescript
+type Deps = { serviceFactory: () => SomeService };
+const defaultDeps: Deps = { serviceFactory: () => new SomeServiceImpl() };
+
+export const doWork = async (props: Props, overrides?: Partial<Deps>) => {
+  const { serviceFactory } = { ...defaultDeps, ...overrides };
+};
+```
+
+---
+
+## 2. Interface-Based Services
+
+Define an interface; implement with a class. Never reference the concrete class outside its own file.
+
+```typescript
+export interface DataService {
+  load(): Promise<Data>;
+  save(data: Data): Promise<void>;
+}
+
+export class ApiDataService implements DataService {
+  /* ... */
+}
+```
+
+---
+
+## 3. ViewModel Pattern
+
+Business logic lives in `use<Name>ViewModel`. Components only render.
+
+```typescript
+export function useTodoViewModel(): TodoViewModel {
+  const { useTodoStorage, addTodoCommand } = useContext(TodoViewModelContext);
+  const storage = useTodoStorage();
+  const addTodo = useCallback(
+    (text: string) => addTodoCommand(text, storage),
+    [storage, addTodoCommand]
+  );
+  return { todos: storage.listAllTodos(), addTodo };
+}
+
+export const TodoView = () => {
+  const { todos, addTodo } = useTodoViewModel();
+  return <ul>{todos.map((t) => <TodoItem key={t.id} todo={t} onAdd={addTodo} />)}</ul>;
+};
+```
+
+---
+
+## 4. Test-First Development
+
+Write tests before implementation for all non-trivial behavior changes.
+
+### Preferred order
+
+Start with behavior-focused tests so requirements are specified before implementation details:
+
+1. Integration tests (user-visible behavior)
+2. Unit tests (isolated module logic)
+3. Source files to make tests pass
+
+For bug fixes, start by adding a failing regression test that reproduces the issue.
+
+Every new module with logic (service, hook, component, utility) must include a corresponding `*.test.ts(x)` file in the same changeset.
+
+### Reasonable exceptions
+
+- Bootstrapping/entry files (for example `main.tsx`)
+- Generated code
+- Trivial pure-markup components with no logic or state
+
+### Test levels in this repo
+
+- **Integration test**: validates behavior across boundaries (for example component + view model + service contract), mocking only external systems such as network APIs.
+- **Unit test**: validates one module in isolation (service, hook, utility, or component behavior).
+
+### Minimum expected coverage by file type
+
+| File type | Required test cases |
+| --- | --- |
+| Service (`*Service.ts`) | Correct request construction; response parsing; error thrown on non-OK status |
+| ViewModel hook (`use*ViewModel.ts`) | Loading state; success state with correct derived values; error state |
+| Pure utility / helper | Every exported function and all meaningful branches |
+| View component | Renders expected content from props; loading/error/empty states where applicable |
+
+### Conventions
+
+- Files: `*.test.ts(x)`; runner: **Vitest** (`npm test` or `vitest run`)
+- Structure: Arrange / Act / Assert (add explicit comments for longer tests)
+- One behavior per test
+- Keep helper functions at the bottom of the file
+- Prefer dependency/context injection over `vi.mock`; add a short reason when `vi.mock` is unavoidable
+
+### Type-safe mocks
+
+```typescript
+// Preferred: vi.fn(() => ...) for consistent behavior
+mockContext = { useUserInfo: vi.fn(() => ({ data: mockUser, isFetched: true })) };
+
+// Per-test reconfiguration
+mockContext = { useUserInfo: vi.fn() };
+vi.mocked(mockContext.useUserInfo).mockReturnValue({ data: undefined, isFetched: true });
+```
+
+For full interface mocks, use `assert.fail` on methods the unit under test should never call, or preferably define a narrower interface.
+
+```typescript
+mockStorage = {
+  list: vi.fn(),
+  retrieve: vi.fn(() => {
+    assert.fail('Not implemented');
+  }),
+};
+```
+
+### React hook test pattern
+
+```typescript
+describe(useMyHook.name, () => {
+  let mockContext: MyContextType;
+  let wrapper: ComponentType<{ children: ReactNode }>;
+
+  beforeEach(() => {
+    mockContext = { useUserInfo: vi.fn(() => ({ data: mockUser })) };
+    wrapper = ({ children }) => (
+      <MyHookContext.Provider value={mockContext}>{children}</MyHookContext.Provider>
+    );
+  });
+
+  it('should ...', async () => {
+    const { result } = renderHook(() => useMyHook(), { wrapper });
+    await act(async () => {
+      await result.current.someAction();
+    });
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+  });
+});
+```
+
+### Shared mock data
+
+Place reusable factories in `src/__mocks__/`. Use `.test` TLD for fake URLs (RFC 2606).
+
+---
+
+## 5. TypeScript Rules
+
+- Never use `any`; prefer `unknown` or explicit strong types
+- Never use `as unknown as T`; for partial test doubles use `{ ...defaults, ...overrides } as T`
+- Use direct React type imports: `import type { ComponentType, ReactNode } from 'react'`
+
+```typescript
+function createMockWindow(overrides: Partial<Window> = {}): Window {
+  return { postMessage: vi.fn(), ...overrides } as Window;
+}
+```
+
+---
+
+## 6. Commits and pull requests
+
+Use [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
+
+- Commit in **small, buildable steps** while lint and tests remain green for this repo. Split **unrelated** edits into separate commits before opening a pull request.
+- **Subject line:** `type[(scope)][!]: description` — imperative mood, no trailing period, blank line before an optional body. Use `!` before `:` and/or a **`BREAKING CHANGE:`** footer for incompatible changes (full rules in the link above).
+- **Types** (pick the narrowest match): `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`. **Scope:** optional short area (`auth`, `chat`, `deps`); omit if it would be vague.
+- **Body:** only for non-obvious motivation or behaviour; keep it short and do not repeat the diff. **Footers** (for example `Fixes #123`) when this project tracks issues that way.
+- **Pull requests:** title and **Summary** should match the same vocabulary; do not replace conventional commits with only a PR headline.
+- Before committing: review **`git status`** and **`git diff`** (including staged); unstage and commit separately if the index mixes unrelated concerns.
+
+---

package/_templates/app/new/root/SPEC.md.ejs.t

@@ -0,0 +1,77 @@
+---
+to: '<%= useSpecKit ? null : (useCurrentDir ? "" : ((directoryName || name) + "/")) + "SPEC.md" %>'
+---
+# Feature Specification: <%= displayName || name %>
+
+<!--
+  This is your app's living product spec. Edit it directly or ask your coding
+  agent to collaborate with you on it.
+-->
+
+## User Scenarios & Testing
+
+### User Stories
+
+<!-- 1. As a [persona], I want [capability], so that [benefit]. -->
+
+### Acceptance Scenarios
+
+<!-- - Given [state], when [action], then [outcome]. -->
+
+## Requirements
+
+### Functional Requirements
+
+<!--
+  List numbered functional requirements (FR-001, FR-002, …) so plans and tasks
+  can reference them.
+-->
+
+<!-- - FR-001: System MUST … -->
+
+## Success Criteria
+
+<!--
+  Measurable outcomes that signal the feature is working. Prefer user-visible
+  criteria over implementation details.
+-->
+
+<!-- - SC-001: Users complete X in under N seconds 95% of the time. -->
+
+## Clarifications
+
+<!--
+  Open questions or ambiguities that need to be resolved before planning.
+  `/speckit.clarify` can help surface these.
+-->
+
+## Assumptions
+
+<!-- - [Mobile support is out of scope for v1] -->
+
+---
+
+## Data Models & CDF Integration *(Dune-specific, mandatory)*
+
+<!--
+  Dune-specific section. Capture how this app integrates with Cognite Data
+  Fusion data models. Every Dune app should fill this in.
+-->
+
+### Existing views
+
+<!--
+  CDF views this app reads from. Format: `<space>.<view>:<version>`.
+-->
+
+### New views
+
+<!--
+  Views this app needs that don't yet exist. Describe properties and relationships.
+-->
+
+### Spaces
+
+<!--
+  CDF spaces this app uses, and what each contains.
+-->

package/_templates/app/new/root/app.json.ejs.t

@@ -0,0 +1,22 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>app.json'
+---
+{
+  "name": "<%= displayName %>",
+  "description": "<%= description %>",
+  "externalId": "<%= name %>",
+  "versionTag": "0.0.1",
+<% if (infra === 'appsApi') { -%>
+  "infra": "appsApi",
+<% } -%>
+  "deployments": [
+    {
+      "org": "<%= org %>",
+      "project": "<%= project %>",
+      "baseUrl": "<%= baseUrl %>",
+      "published": false,
+      "deployClientId": "",
+      "deploySecretName": "<%= org %>_<%= project %>_<%= cluster %>"
+    }
+  ]
+}

package/_templates/app/new/root/gitignore.ejs.t

@@ -0,0 +1,21 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>.gitignore'
+---
+# Dependencies
+node_modules
+
+# Build output
+dist
+
+# Environment variables
+.env
+.env.local
+
+# Editor directories
+.vscode
+.idea
+
+# OS files
+.DS_Store
+Thumbs.db
+

package/_templates/app/new/root/index.html.ejs.t

@@ -0,0 +1,36 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>index.html'
+---
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta name="theme-color" content="#000000" />
+    <meta name="description" content="Cognite Data Fusion Application" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+    <meta name="apple-mobile-web-app-title" content="CDF Application" />
+    <title><%= displayName %></title>
+
+    <!-- PWA Manifest -->
+    <link rel="manifest" href="/manifest.json" />
+
+    <!-- Aura typography compatibility -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=Space+Grotesk:wght@300..700&family=Source+Code+Pro:wght@200..900&display=swap"
+      rel="stylesheet"
+    />
+
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/_templates/app/new/root/package.json.ejs.t

@@ -0,0 +1,67 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>package.json'
+---
+{
+  "name": "<%= name %>",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20",
+    "npm": ">=11.10.0"
+  },
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint . --ext .js,.mjs,.cjs,.ts,.tsx",
+    "lint:fix": "eslint . --fix --ext .js,.mjs,.cjs,.ts,.tsx",
+    "deploy": "npx @cognite/dune@latest deploy:interactive --published",
+    "deploy-preview": "npx @cognite/dune@latest deploy:interactive"
+  },
+  "dependencies": {
+    "@cognite/aura": "^0.1.7",
+    "@cognite/sdk": "^10.3.0",
+    "@cognite/dune": "^3.1.3",
+<% if (infra === 'appsApi') { -%>
+    "@cognite/app-sdk": "^0.3.0",
+<% } -%>
+    "@tabler/icons-react": "^3.35.0",
+    "@tanstack/react-query": "^5.90.10",
+    "clsx": "^2.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.4",
+    "@tailwindcss/vite": "^4.1.17",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^24.10.1",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/ui": "^2.1.8",
+    "autoprefixer": "^10.4.22",
+    "eslint": "9.39.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-no-only-tests": "^3.3.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^16.5.0",
+    "happy-dom": "^20.9.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.17",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vite-plugin-mkcert": "^1.17.9",
+    "vitest": "^2.1.8"
+  }
+}

package/_templates/app/new/src/App.test.tsx.ejs.t

@@ -0,0 +1,45 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>src/App.test.tsx'
+---
+import * as appSdk from '@cognite/app-sdk';
+import { render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import App from './App';
+
+vi.mock(import('@cognite/app-sdk'));
+
+describe('App', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state', () => {
+    vi.mocked(appSdk.connectToHostApp).mockReturnValue(new Promise(() => {}));
+
+    render(<App />);
+    expect(screen.getByText('Loading project...')).toBeInTheDocument();
+  });
+
+  it('renders splash with deployment targets and checklist copy', async () => {
+    vi.mocked(appSdk.connectToHostApp).mockResolvedValue({
+      api: { getProject: vi.fn().mockResolvedValue('my-test-project') } as Partial<appSdk.HostAppAPI> as appSdk.HostAppAPI,
+    });
+
+    render(<App />);
+    await waitFor(() => expect(screen.getByText('Welcome to Dune')).toBeInTheDocument());
+    expect(screen.getByText('App deployment checklist')).toBeInTheDocument();
+    expect(screen.getByText('Plan')).toBeInTheDocument();
+    expect(screen.getByText('Explore')).toBeInTheDocument();
+    expect(screen.getByText('Deploy')).toBeInTheDocument();
+    expect(screen.getByText('Support')).toBeInTheDocument();
+    expect(screen.getByText('Help & feedback')).toBeInTheDocument();
+    expect(screen.getByText('Your app will deploy to')).toBeInTheDocument();
+    expect(screen.getByText('org')).toBeInTheDocument();
+    expect(screen.getByText('and project')).toBeInTheDocument();
+    expect(screen.getByText('<%= org %>')).toBeInTheDocument();
+    expect(screen.getByText('<%= project %>')).toBeInTheDocument();
+    expect(screen.getAllByText(/SPEC\.md/).length).toBeGreaterThan(0);
+    expect(screen.getByText(/deploy:interactive/)).toBeInTheDocument();
+  });
+});