@cognite/cli 0.6.0-alpha.6 → 0.6.0

package/README.md

@@ -0,0 +1,146 @@
+# @cognite/cli
+
+Build and deploy React apps to [Cognite Data Fusion](https://docs.cognite.com/).
+
+## Quick start
+
+Scaffold a new app — AI skills are pulled automatically:
+
+```bash
+npx @cognite/cli apps create
+```
+
+This prompts for your app name, org, project, and cluster, then generates a fully configured React + TypeScript project.
+
+> Top-level commands (`dune create`, `dune deploy`, `dune deploy:interactive`, `dune skills`) still work as deprecated aliases that print a one-line warning. Migrate to `dune apps <verb>`.
+
+## 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 Fusion app host via `@cognite/app-sdk`'s Comlink handshake. The template wires this up for you.
+
+### Legacy apps (`--classic`)
+
+Apps created with `--classic` use the older Files API path and wrap their root in `DuneAuthProvider` from `@cognite/dune/auth`:
+
+```tsx
+import { DuneAuthProvider, useDune } from '@cognite/dune/auth';
+
+function App() {
+  const { sdk, isLoading } = useDune();
+  if (isLoading) return <div>Loading...</div>;
+  return <MyApp sdk={sdk} />;
+}
+
+export default function Root() {
+  return (
+    <DuneAuthProvider>
+      <App />
+    </DuneAuthProvider>
+  );
+}
+```
+
+## 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.
+
+## AI skills
+
+Skills guide your AI agent (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:
+
+```bash
+npx @cognite/cli apps skills pull
+```
+
+Browse available skills at [cognitedata/builder-skills](https://github.com/cognitedata/builder-skills).
+
+## Requirements
+
+- Node.js ≥ 20
+- React ≥ 18 (optional peer dependency — only needed for auth components)
+
+## Development
+
+### Running tests
+
+```bash
+pnpm test           # run once
+pnpm test:watch     # watch mode
+```
+
+### Testing the CLI against a mock server
+
+A local mock of the App Hosting API lets you run the real CLI against a controlled server without hitting a real CDF cluster.
+
+**Terminal 1 — start the mock server:**
+
+```bash
+pnpm mock:server
+```
+
+**Terminal 2 — run the deploy command against it:**
+
+```bash
+pnpm mock:deploy
+```
+
+`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:
+
+| Env var | Purpose |
+|---|---|
+| `DUNE_BASE_URL=http://localhost:9090` | Overrides `baseUrl` from `app.json` — all API calls go to the mock |
+| `DUNE_DEPLOY_TOKEN=test-token` | Skips OAuth entirely — no real client secret needed |
+
+To test against your own app instead of the fixture:
+
+```bash
+cd apps/my-app
+DUNE_DEPLOY_TOKEN=test-token DUNE_BASE_URL=http://localhost:9090 pnpm exec dune apps deploy --skip-build
+```
+
+#### Simulating error scenarios
+
+Pass `MOCK_SCENARIO` to the server to force a specific HTTP error:
+
+```bash
+MOCK_SCENARIO=403 pnpm mock:server
+```
+
+| `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) |
+
+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`.
+
+## Maintenance
+
+### 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/dune refresh-spec-kit v0.9.0
+```
+
+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,26 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>vite.config.ts'
+---
+import path from 'node:path';
+
+import { fusionOpenPlugin } from '@cognite/dune/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: './',
+  plugins: [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';