@cognite/cli 0.5.1 → 0.6.0-alpha.26

package/README.md

@@ -1,61 +1,122 @@
-# cdf cli
+# @cognite/cli
 
-This is in super alpha!
+Build and deploy React apps to [Cognite Data Fusion](https://docs.cognite.com/). Apps built with this CLI run inside Cognite Flows — Cognite's app-hosting platform for embedding custom UIs in CDF.
 
-## Install
+## Quick start
 
-    $ npm i -g @cognite/cli
+Scaffold a new app — AI skills are pulled automatically:
 
-## Screencast example
+```bash
+npx @cognite/cli apps create
+```
+
+This prompts for your app name, org, project, and cluster, then generates a fully configured React + TypeScript project.
+
+## Authentication
+
+New apps created with `npx @cognite/cli apps create` depend on [`@cognite/app-sdk`](https://www.npmjs.com/package/@cognite/app-sdk) — **not `@cognite/cli`** — for auth and host integration. `@cognite/cli` is the CLI used to scaffold, develop, and deploy the app; the generated app itself talks to the Flows app host via `@cognite/app-sdk`'s Comlink handshake. The template wires this up for you.
+
+## Deployment
+
+Deploy interactively via browser OAuth:
+
+```bash
+npx @cognite/cli apps deploy --interactive
+```
+
+For CI, set your client secret as an environment variable and run:
+
+```bash
+pnpm deploy
+```
+
+Deployment targets are configured in `app.json` at the project root.
 
-![This is how it works](https://media.giphy.com/media/TgymOB5RrXunSANV3P/giphy.gif)
+## AI skills
 
-## Usage
+Skills guide your AI agent (GitHub Copilot, Claude Code, Cursor, etc.) through Dune-specific tasks like adding auth, building chat UIs, or reviewing code. They are pulled automatically on `npx @cognite/cli apps create` and can be synced later:
 
-The project and api-key is specified through the two _required_ environment variables
+```bash
+npx @cognite/cli apps skills pull
+```
+
+Browse available skills at [cognitedata/builder-skills](https://github.com/cognitedata/builder-skills).
+
+## Requirements
 
-    $ export COGNITE_PROJECT=publicdata
-    $ export COGNITE_CREDENTIALS=<api-key>
+- Node.js ≥ 20
+- React ≥ 18 (optional peer dependency — only needed for auth components)
 
-and the optional environment variable
+## Development
 
-    $ export COGNITE_BASE_URL=<cluster-specific-url>
+### Running tests
 
-## Examples
+```bash
+pnpm test           # run once
+pnpm test:watch     # watch mode
+```
 
-`cdf assets list`
+### Testing the CLI against a mock server
 
-`cdf assets list --limit=5`
+A local mock of the App Hosting API lets you run the real CLI against a controlled server without hitting a real CDF cluster.
 
-`cdf assets list --filter.root=true --limit=5`
+**Terminal 1 — start the mock server:**
 
-`cdf assets retrieve --externalIds=test1,test2`
+```bash
+pnpm mock:server
+```
 
-`cdf assets retrieve --ids=123,234`
+**Terminal 2 — run the deploy command against it:**
 
-`cdf assets search --filter.root=true --search.name=name --limit=10`
+```bash
+pnpm mock:deploy
+```
 
-`cdf assets create --externalId=test1 --name=somename`
+`mock:deploy` builds and deploys `apps/mock-app` — a minimal workspace app that serves as the standard CLI test target. Under the hood it sets two env vars that work from any app directory too:
 
-`cdf assets update --externalId=test1 --update.name.set=somenewname`
+| Env var | Purpose |
+|---|---|
+| `COGNITE_BASE_URL=http://localhost:9090` | Overrides `baseUrl` from `app.json` — all API calls go to the mock |
+| `COGNITE_TOKEN=test-token` | Skips OAuth entirely — no real client secret needed |
 
-You can also pipe JSON input to create/delete to create multiple assets at once. Assuming assets.json contains
+To test against your own app instead of the fixture:
 
+```bash
+cd apps/my-app
+COGNITE_TOKEN=test-token COGNITE_BASE_URL=http://localhost:9090 pnpm exec dune apps deploy --skip-build
 ```
-[
-    {"externalId": "test.1"},
-    {"externalId": "test.2"}
-]
+
+#### Simulating error scenarios
+
+Pass `MOCK_SCENARIO` to the server to force a specific HTTP error:
+
+```bash
+MOCK_SCENARIO=403 pnpm mock:server
 ```
 
-then;
-`cat assets.json | cdf assets create`
-`cat assets.json | cdf assets delete`
+| `MOCK_SCENARIO` | Step that fails |
+|---|---|
+| `409` | `ensureApp` — app already exists (CLI should recover) |
+| `403` | `ensureApp` — missing `AppHosting:WRITE` capability |
+| `500` | `ensureApp` — internal server error |
+| `upload-409` | `uploadVersion` — version already published, cannot overwrite (hard failure) |
+| `upload-413` | `uploadVersion` — payload too large (50 MB limit) |
+| `upload-403` | `uploadVersion` — missing `AppHosting:WRITE` capability |
+| `upload-500` | `uploadVersion` — internal server error |
+| `publish-403` | `publishAndActivate` — missing `AppHosting:WRITE` capability |
+| `publish-500` | `publishAndActivate` — internal server error |
+| `republish` | `ensureApp` recovers (409), then `uploadVersion` fails (409 — version already published) |
 
-## Settings
+The mock server and MSW handlers live in `cli/testing/msw/`. The same handlers are used by the Vitest integration tests in `src/deploy/apphosting-deployer.msw.test.ts`.
 
-## Contribution
+## Maintenance
 
-Yes, please. Issues and PRs are highly welcome.
+### Updating the spec-kit vendor snapshot
+
+The AI skill commands under `_vendor/spec-kit/` are generated by [spec-kit](https://github.com/github/spec-kit) and checked in. To update to a new release, pass the target tag (requires [`uv`](https://docs.astral.sh/uv/), which provides `uvx`):
+
+```bash
+pnpm --filter @cognite/cli refresh-spec-kit v0.9.0
+```
 
-This package is automatically released using [semantic release](https://github.com/semantic-release/semantic-release). Please write commit messages that follows the angular commit message conventions (feat:, fix: etc).
+The refresh script stages the generated commands, templates, and shell scripts before replacing `_vendor/spec-kit/`. Then review the diff under `_vendor/spec-kit/` and commit it.

package/_templates/app/new/config/eslint.config.mjs.ejs.t

@@ -0,0 +1,99 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>eslint.config.mjs'
+---
+import { auraEslintPlugin } from '@cognite/aura/eslint';
+import js from '@eslint/js';
+import importPlugin from 'eslint-plugin-import';
+import noOnlyTestsPlugin from 'eslint-plugin-no-only-tests';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+const sharedRules = {
+  'import/first': 'error',
+  'import/no-duplicates': 'error',
+  'import/order': [
+    'error',
+    {
+      groups: ['builtin', 'external', 'internal', 'parent', ['sibling', 'index']],
+      'newlines-between': 'always',
+      alphabetize: {
+        order: 'asc',
+        caseInsensitive: true,
+      },
+    },
+  ],
+  'no-only-tests/no-only-tests': 'error',
+  quotes: ['error', 'single', { avoidEscape: true }],
+};
+
+const noUnusedVarsOptions = {
+  argsIgnorePattern: '^_',
+  caughtErrorsIgnorePattern: '^_',
+  varsIgnorePattern: '^_',
+  ignoreRestSiblings: true,
+};
+
+export default tseslint.config(
+  {
+    ignores: ['dist', 'build', '.next', 'coverage', '*.min.js', '.agents', '.cursor', '.claude'],
+  },
+  {
+    files: ['**/*.{js,mjs,cjs,ts,tsx}'],
+    plugins: {
+      import: importPlugin,
+      'no-only-tests': noOnlyTestsPlugin,
+    },
+    rules: sharedRules,
+  },
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    extends: [js.configs.recommended],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', noUnusedVarsOptions],
+    },
+  },
+  {
+    files: ['**/*.cjs'],
+    languageOptions: {
+      sourceType: 'commonjs',
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      globals: {
+        ...globals.browser,
+      },
+    },
+    plugins: {
+      aura: auraEslintPlugin,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'off',
+      '@typescript-eslint/no-unused-vars': ['error', noUnusedVarsOptions],
+      'aura/no-overriding-styles': 'warn',
+      'no-unused-vars': 'off',
+      'react-refresh/only-export-components': ['error', { allowConstantExport: true }],
+    },
+  }
+);

package/_templates/app/new/config/tsconfig.json.ejs.t

@@ -0,0 +1,35 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>tsconfig.json'
+---
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+
+    /* Testing */
+    "types": ["vitest/globals", "@testing-library/jest-dom"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
+

package/_templates/app/new/config/tsconfig.node.json.ejs.t

@@ -0,0 +1,27 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>tsconfig.node.json'
+---
+{
+  "compilerOptions": {
+    "composite": true,
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "emitDeclarationOnly": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts", "vitest.config.ts"]
+}
+

package/_templates/app/new/config/vite.config.ts.ejs.t

@@ -0,0 +1,28 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>vite.config.ts'
+---
+import path from 'node:path';
+
+import { fusionOpenPlugin, manifestCspPlugin } from '@cognite/app-sdk/vite';
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import mkcert from 'vite-plugin-mkcert';
+
+export default defineConfig({
+  base: './',
+  // manifestCspPlugin() must stay first — its middleware sets the
+  // Content-Security-Policy header before any HTML response is sent.
+  plugins: [manifestCspPlugin(), react(), mkcert(), fusionOpenPlugin(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    port: 3001,
+  },
+  worker: {
+    format: 'es',
+  },
+});

package/_templates/app/new/config/vitest.config.ts.ejs.t

@@ -0,0 +1,14 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>vitest.config.ts'
+---
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    globals: true,
+    environment: 'happy-dom',
+    setupFiles: ['vitest.setup.ts'],
+  },
+});

package/_templates/app/new/config/vitest.setup.ts.ejs.t

@@ -0,0 +1,4 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>vitest.setup.ts'
+---
+import '@testing-library/jest-dom/vitest';

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.
+
+---