@cognite/dune 0.3.4 → 0.3.6

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

@@ -0,0 +1,182 @@
+---
+to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>AGENTS.md'
+---
+# Coding Standards
+
+## 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** (`pnpm 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;
+}
+```
+---

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

@@ -21,9 +21,10 @@ to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>package.json'
     "deploy-preview": "dune deploy:interactive"
   },
   "dependencies": {
-    "@cognite/aura": "^0.1.2",
+    "@cognite/aura": "^0.1.4",
     "@cognite/sdk": "^10.3.0",
-    "@cognite/dune": "^0.3.4",
+    "@cognite/dune": "^0.3.6",
+    "@tabler/icons-react": "^3.35.0",
     "@tanstack/react-query": "^5.90.10",
     "clsx": "^2.1.1",
     "react": "^19.2.0",

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

@@ -1,8 +1,7 @@
 ---
 to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>src/App.test.tsx'
 ---
-import { useDune } from '@cognite/dune';
-import { CogniteClient } from '@cognite/sdk';
+import * as duneAuth from '@cognite/dune';
 import { render, screen } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -11,20 +10,13 @@ import App from './App';
 // Mock the @cognite/dune module
 vi.mock(import('@cognite/dune'));
 
-function mockUseDune(project: string, isLoading: boolean): ReturnType<typeof useDune> {
-  const sdk = new CogniteClient({
-    appId: 'dune-template-test',
-    project,
-    baseUrl: 'https://api.cognitedata.com',
-    oidcTokenProvider: async () => '',
-  });
+type UseDuneResult = ReturnType<typeof duneAuth.useDune>;
 
-  const contextValue = {
-    sdk,
+function mockUseDune(project: string, isLoading: boolean): UseDuneResult {
+  return {
+    sdk: { project } as Partial<UseDuneResult['sdk']> as UseDuneResult['sdk'],
     isLoading,
-  } satisfies ReturnType<typeof useDune>;
-
-  return contextValue;
+  };
 }
 
 describe('App', () => {
@@ -33,18 +25,29 @@ describe('App', () => {
   });
 
   it('renders loading state', () => {
-    vi.mocked(useDune).mockReturnValue(mockUseDune('test-project', true));
+    vi.mocked(duneAuth.useDune).mockReturnValue(mockUseDune('test-project', true));
 
     render(<App />);
     expect(screen.getByText('Loading project...')).toBeInTheDocument();
   });
 
-  it('renders app with project name', () => {
-    vi.mocked(useDune).mockReturnValue(mockUseDune('my-test-project', false));
+  it('renders splash with deployment targets and checklist copy', () => {
+    vi.mocked(duneAuth.useDune).mockReturnValue(mockUseDune('my-test-project', false));
 
     render(<App />);
-    expect(screen.getByText('Welcome to my-test-project')).toBeInTheDocument();
-    expect(screen.getByText('Open starter config')).toBeInTheDocument();
-    expect(screen.getByText('<%= org %> / <%= project %>')).toBeInTheDocument();
+    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.getByText(/PRD\.md/)).toBeInTheDocument();
+    expect(screen.getByText(/deploy:interactive/)).toBeInTheDocument();
   });
 });

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

@@ -2,48 +2,80 @@
 to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>src/App.tsx'
 ---
 import {
+  Alert,
+  AlertDescription,
   Badge,
-  CodeBlock,
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogFooter,
-  DialogHeader,
-  DialogTitle,
-  DialogTrigger,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
   Loader,
   Separator,
-  buttonVariants,
 } from '@cognite/aura/components';
 import { useDune } from '@cognite/dune';
+import { IconCaretUpDown, IconRocket } from '@tabler/icons-react';
+
 import appConfig from '../app.json';
 
-const deploymentChecklist = [
-  'Confirm org, project, and cluster in app.json.',
-  'Replace the starter workflow with your first real query.',
-  'Deploy with dune deploy:interactive when the shell is ready.',
-];
+const DUNE_DOCUMENTATION_HREF = 'https://laughing-adventure-r6kwpyy.pages.github.io/';
 
-function getCluster(baseUrl?: string) {
-  return baseUrl?.replace(/^https?:\/\//, '').replace(/\.cognitedata\.com$/, '') ?? '';
-}
+const INTRO_COPY =
+  "Build and deploy React apps to Cognite Data Fusion in minutes. Aura, Cognite's AI-native design system, comes pre-configured so your app looks and feels at home from day one. Follow the checklist below to get started.";
+
+const CHECKLIST_STEPS = [
+  {
+    label: 'Plan',
+    badge: 'Step 1',
+    body: (
+      <>
+        Describe what you want to build in Cursor and ask the agent to collaborate on a PRD. It will generate a
+        structured template in PRD.md, which you can refine in plan mode with as much detail as needed. Keep it simple
+        and clear, then move on to building when ready.
+      </>
+    ),
+  },
+  {
+    label: 'Explore',
+    badge: 'Step 2',
+    body: (
+      <>
+        Ask Cursor to review and understand your data model, then answer any follow-up questions it raises. Continue
+        refining the app by providing additional input as needed.
+      </>
+    ),
+  },
+  {
+    label: 'Deploy',
+    badge: 'Step 3',
+    body: (
+      <>
+        When ready to deploy, run <code>npx @cognite/dune deploy:interactive</code> in the terminal. Your app will
+        appear in the Fusion portal under Custom apps. Run the command again to redeploy new changes.
+      </>
+    ),
+  },
+] as const;
 
 function App() {
   const { sdk, isLoading } = useDune();
 
   if (isLoading) {
     return (
-      <main className="min-h-screen bg-[linear-gradient(145deg,var(--background)_0%,var(--mountain-50)_55%,var(--mountain-100)_100%)] text-foreground">
-        <section className="mx-auto grid min-h-screen w-full max-w-[58rem] place-content-center p-4 sm:p-8">
-          <div
-            className="mx-auto grid w-full max-w-sm justify-items-center gap-6 rounded-3xl border border-border bg-card p-5 shadow-xl backdrop-blur-lg sm:p-8"
-            aria-label="Loading project"
-            aria-live="polite"
-          >
-            <div className="inline-flex items-center gap-3 text-muted-foreground">
-              <Loader size={20} />
-              <span>Loading project...</span>
-            </div>
+      <main className="min-h-screen bg-muted/50 text-foreground">
+        <section className="mx-auto flex min-h-screen w-full max-w-lg flex-col justify-center p-4 sm:p-8">
+          <div className="mx-auto w-full max-w-sm">
+            <Card aria-label="Loading project" aria-live="polite">
+              <CardContent>
+                <div className="inline-flex items-center gap-3 text-muted-foreground">
+                  <Loader size={20} />
+                  <span>Loading project...</span>
+                </div>
+              </CardContent>
+            </Card>
           </div>
         </section>
       </main>
@@ -51,80 +83,103 @@ function App() {
   }
 
   const deployment = appConfig.deployments?.[0];
-  const deploymentLabel = [deployment?.org, deployment?.project ?? sdk.project].filter(Boolean).join(' / ');
-  const starterConfigPreview = JSON.stringify(
-    {
-      org: deployment?.org ?? '',
-      project: deployment?.project ?? sdk.project,
-      cluster: getCluster(deployment?.baseUrl),
-    },
-    null,
-    2
-  );
+  const orgLabel = deployment?.org ?? '';
+  const projectLabel = deployment?.project ?? sdk.project;
 
   return (
-    <main className="min-h-screen bg-[linear-gradient(145deg,var(--background)_0%,var(--mountain-50)_55%,var(--mountain-100)_100%)] text-foreground">
-      <section className="mx-auto grid min-h-screen w-full max-w-[58rem] place-content-center p-4 sm:p-8">
-        <div className="grid gap-6 rounded-3xl border border-border bg-card p-5 shadow-xl backdrop-blur-lg sm:p-8">
-          <div className="flex flex-col gap-4 lg:flex-row lg:items-start lg:justify-between">
-            <div>
-              <h1 className="text-[clamp(2rem,4vw,3rem)] leading-none font-semibold tracking-[-0.04em]">
-                Welcome to {sdk.project}
-              </h1>
-              <div className="mt-3">
-                <Badge variant="fjord" background>
-                  {deploymentLabel}
-                </Badge>
-              </div>
-            </div>
-            <Dialog>
-              <DialogTrigger className={buttonVariants()}>Open starter config</DialogTrigger>
-              <DialogContent className="max-w-xl">
-                <DialogHeader>
-                  <DialogTitle>Starter config</DialogTitle>
-                  <DialogDescription>Current starter values as JSON.</DialogDescription>
-                </DialogHeader>
-                <div className="grid gap-2">
-                  <div className="overflow-hidden rounded-2xl border border-border bg-background">
-                    <CodeBlock code={starterConfigPreview} language="json" />
-                  </div>
-                </div>
-                <DialogFooter>
-                  <Badge variant="fjord" background>{sdk.project}</Badge>
-                </DialogFooter>
-              </DialogContent>
-            </Dialog>
-          </div>
+    <main className="min-h-screen bg-muted/50 text-foreground">
+      <section className="mx-auto flex min-h-screen w-full max-w-3xl flex-col justify-center p-4 sm:p-8">
+        <Card>
+          <div className="p-15 gap-16">
+            <CardHeader>
+              <CardTitle as="h1" className="text-4xl">Welcome to Dune</CardTitle>
+              <CardDescription className="text-xl">{INTRO_COPY}</CardDescription>
+            </CardHeader>
 
-          <Separator />
+            <CardContent>
+              <Separator />
 
-          <div className="grid gap-4">
-            <div id="deployment-checklist" className="rounded-2xl border border-border bg-muted p-4">
-              <div className="flex items-center justify-between gap-3">
-                <div>
-                  <p className="text-sm font-semibold">Deployment checklist</p>
-                  <p className="mt-1 text-sm text-muted-foreground">Use this to turn the starter into a deployable app.</p>
+              <div className="flex flex-col gap-6 pt-16">
+                <div className="flex items-center gap-2 pt-4">
+                  <IconRocket aria-hidden />
+                  <span className="text-2xl font-medium">App deployment checklist</span>
                 </div>
-                <Badge variant="fjord" background>
-                  3 steps
-                </Badge>
-              </div>
-              <div className="mt-4 grid gap-2">
-                {deploymentChecklist.map((item, index) => (
-                  <div
-                    key={item}
-                    className="grid grid-cols-[auto_1fr] items-start gap-3 rounded-xl border border-border bg-card px-3 py-2"
-                  >
-                    <span className="inline-flex h-6 w-6 items-center justify-center rounded-full bg-foreground text-xs font-semibold text-background">
-                      {index + 1}
-                    </span>
-                    <p className="text-sm text-card-foreground">{item}</p>
-                  </div>
-                ))}
+
+                <div className="flex flex-col gap-4 px-4">
+                  {CHECKLIST_STEPS.map((step, index) => (
+                    <Collapsible key={step.label} defaultOpen={index === 0}>
+                      <CollapsibleTrigger className="w-full">
+                        <div className="flex w-full min-w-0 items-center justify-between gap-3 text-left">
+                          <span className="text-lg">{step.label}</span>
+                          <span className="inline-flex shrink-0 items-center gap-2">
+                            <Badge variant="mountain" background>
+                              {step.badge}
+                            </Badge>
+                            <IconCaretUpDown aria-hidden className="size-4 text-muted-foreground" />
+                          </span>
+                        </div>
+                      </CollapsibleTrigger>
+                      <CollapsibleContent className="py-2">
+                        {step.body}
+                      </CollapsibleContent>
+                    </Collapsible>
+                  ))}
+                </div>
+
+                <Alert className="bg-mountain-50 mb-10">
+                  <AlertDescription>
+                    <div className="flex flex-wrap items-center gap-2 text-lg">
+                      <span>Your app will deploy to</span>
+                      {orgLabel ? (
+                        <>
+                          <span>org</span>
+                          <Badge variant="nordic" background>
+                            {orgLabel}
+                          </Badge>
+                          <span>and project</span>
+                        </>
+                      ) : (
+                        <span>project</span>
+                      )}
+                      <Badge variant="nordic" background>
+                        {projectLabel}
+                      </Badge>
+                    </div>
+                  </AlertDescription>
+                </Alert>
+
+                <Collapsible>
+                  <CollapsibleTrigger className="w-full">
+                    <div className="flex w-full min-w-0 items-center justify-between gap-3 text-left">
+                      <span className="text-lg">Support</span>
+                      <span className="inline-flex shrink-0 items-center gap-2">
+                        <Badge variant="mountain">
+                          Help & feedback
+                        </Badge>
+                        <IconCaretUpDown aria-hidden className="size-4 text-muted-foreground" />
+                      </span>
+                    </div>
+                  </CollapsibleTrigger>
+                  <CollapsibleContent className="py-2">
+                    <p>
+                      For additional support and feedback, please head to{' '}
+                      <a
+                        href={DUNE_DOCUMENTATION_HREF}
+                        rel="noreferrer"
+                        style={{ color: '#486AED' }}
+                        target="_blank"
+                      >
+                        Dune documentation
+                      </a>{' '}
+                      or the{' '}
+                      <span style={{ color: '#486AED' }}>#Dune Slack channel</span>.
+                    </p>
+                  </CollapsibleContent>
+                </Collapsible>
               </div>
-            </div>
+            </CardContent>
           </div>
-        </div>
+        </Card>
       </section>
     </main>
   );

package/_templates/app/new/src/styles.css.ejs.t

@@ -1,8 +1,9 @@
 ---
 to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>src/styles.css'
 ---
-@import "@cognite/aura/styles.css";
-@import "tailwindcss";
+@import '@cognite/aura/styles.source.css';
+
+@source '../node_modules/@cognite/aura/dist/components';
 
 :root {
   --font-inter: "Inter", ui-sans-serif, system-ui, sans-serif;

package/bin/cli.js

@@ -1,8 +1,24 @@
 #!/usr/bin/env node
 
+import { symlinkSync } from 'node:fs';
 import { basename, dirname, normalize, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+/**
+ * Creates a CLAUDE.md symlink pointing to AGENTS.md in the given directory.
+ * Silently skips if the symlink already exists (EEXIST).
+ * @param {string} appDir - Absolute path to the generated app directory
+ */
+export function createClaudeMdSymlink(appDir) {
+  try {
+    symlinkSync('AGENTS.md', resolve(appDir, 'CLAUDE.md'));
+  } catch (err) {
+    if (err.code !== 'EEXIST') {
+      console.warn('⚠️  Could not create CLAUDE.md symlink:', err.message);
+    }
+  }
+}
+
 import { Logger, runner } from 'hygen';
 
 const defaultTemplates = resolve(dirname(fileURLToPath(import.meta.url)), '..', '_templates');
@@ -118,6 +134,9 @@ async function main() {
         debug: !!process.env.DEBUG,
       });
 
+      // Create CLAUDE.md symlink -> AGENTS.md for Claude Code support
+      createClaudeMdSymlink(isCurrentDir ? process.cwd() : dirName || appName);
+
       // Print success message with next steps
       const installAndDevSteps = '  pnpm install\n  pnpm dev';
       const deployLabel = 'To deploy your app:';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cognite/dune",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Build and deploy React apps to Cognite Data Fusion",
   "keywords": ["cognite", "dune", "cdf", "fusion", "react", "scaffold", "deploy"],
   "license": "Apache-2.0",

package/_templates/app/new/config/tailwind.config.js.ejs.t

@@ -1,11 +0,0 @@
----
-to: '<%= useCurrentDir ? "" : ((directoryName || name) + "/") %>tailwind.config.js'
----
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-};