create-keboola-app 0.0.0

package/dist/template/src/slices/assistant.ts

@@ -0,0 +1,68 @@
+import type { StateCreator } from 'zustand';
+
+import type { AppState } from '../store';
+
+type ChatMessage = {
+  id: string;
+  role: 'user' | 'assistant';
+  text: string;
+};
+
+export type AssistantSlice = {
+  /**
+   * One transcript for the whole app. The home page's prompt input and the rail's
+   * own composer both call `send`, so sending from the page is a handoff into the
+   * rail rather than a second, parallel conversation.
+   */
+  messages: ChatMessage[];
+  send: (text: string) => void;
+  fullscreen: boolean;
+  toggleFullscreen: () => void;
+};
+
+const cannedReply = (question: string) => `**${question}**
+
+Consumption has climbed every month since January and June is running at 8,420
+of the 8,500 budgeted — a 1% margin. On this trend July goes over.
+
+| Component | Share of budget |
+| --- | --- |
+| Database extractor | 55% |
+| Python transformation | 28% |
+| Snowflake writer | 12% |
+| Daily orchestration | 5% |
+
+\`\`\`mermaid
+flowchart LR
+  A[Storage tables] --> B[Transformation]
+  B --> C[Credit ledger]
+  C --> D[This overview]
+\`\`\``;
+
+/** The mutator tuple mirrors `store.ts`'s middleware stack, outside-in. */
+type Mutators = [['zustand/devtools', never], ['zustand/persist', unknown]];
+
+/** The assistant's own state: the transcript, and whether it fills the viewport. */
+export const createAssistantSlice: StateCreator<AppState, Mutators, [], AssistantSlice> = (
+  set,
+) => ({
+  messages: [],
+  send: (text) =>
+    set(
+      (s) => ({
+        messages: [
+          ...s.messages,
+          { id: crypto.randomUUID(), role: 'user', text },
+          // A canned reply, not a backend call — swap the whole branch for a
+          // real request. It answers in Markdown (including a ```mermaid fence)
+          // because that is what an assistant actually returns, and rendering
+          // that is the rail's job: see AssistantPanel.
+          { id: crypto.randomUUID(), role: 'assistant', text: cannedReply(text) },
+        ],
+      }),
+      false,
+      'send',
+    ),
+  fullscreen: false,
+  toggleFullscreen: () => set((s) => ({ fullscreen: !s.fullscreen }), false, 'toggleFullscreen'),
+});

package/dist/template/src/slices/shell.ts

@@ -0,0 +1,54 @@
+import type { StateCreator } from 'zustand';
+
+import type { SidebarMode } from '@keboola/design';
+
+import type { AppState } from '../store';
+
+/**
+ * The modes `sidebarMode` may hold, as a runtime value.
+ *
+ * - Keyed by `SidebarMode`, so adding a mode to the union fails the build here until
+ *   it is listed — a hand-written array would silently start rejecting the new mode.
+ * - The values carry nothing; the keys are the whole point.
+ */
+const SIDEBAR_MODES: Record<SidebarMode, true> = {
+  expanded: true,
+  collapsed: true,
+  'expand-on-hover': true,
+};
+
+export const isSidebarMode = (value: unknown): value is SidebarMode =>
+  typeof value === 'string' && Object.hasOwn(SIDEBAR_MODES, value);
+
+export type ShellSlice = {
+  /**
+   * The left rail's mode.
+   *
+   * - Lives here, not inside `SidebarProvider`, so it survives a reload; a layout
+   *   preference that resets reads as a broken control.
+   * - `AppChrome` drives the provider from it (`leftMode` + `onLeftModeChange`).
+   * - `SidebarModeMenu` is the UI that writes it.
+   */
+  sidebarMode: SidebarMode;
+  setSidebarMode: (mode: SidebarMode) => void;
+  helpVisible: boolean;
+  toggleHelp: () => void;
+  setHelpVisible: (visible: boolean) => void;
+};
+
+/**
+ * The mutator tuple mirrors `store.ts`'s middleware stack, outside-in.
+ *
+ * - Without it `set` loses its third argument and every `set(partial, false, 'name')`
+ *   call fails to type-check.
+ */
+type Mutators = [['zustand/devtools', never], ['zustand/persist', unknown]];
+
+/** The chrome's own state: which rail mode is active, and whether help copy shows. */
+export const createShellSlice: StateCreator<AppState, Mutators, [], ShellSlice> = (set) => ({
+  sidebarMode: 'expanded',
+  setSidebarMode: (mode) => set({ sidebarMode: mode }, false, 'setSidebarMode'),
+  helpVisible: true,
+  toggleHelp: () => set((s) => ({ helpVisible: !s.helpVisible }), false, 'toggleHelp'),
+  setHelpVisible: (visible) => set({ helpVisible: visible }, false, 'setHelpVisible'),
+});

package/dist/template/src/store.test.tsx

@@ -0,0 +1,92 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { Button } from '@keboola/design';
+
+import { UI_SETTINGS_STORAGE_KEY, useAppStore } from './store';
+
+function HelpToggleHarness() {
+  const helpVisible = useAppStore((s) => s.helpVisible);
+  const toggleHelp = useAppStore((s) => s.toggleHelp);
+  return (
+    <div>
+      <span data-testid="state">{helpVisible ? 'visible' : 'hidden'}</span>
+      <Button onClick={toggleHelp}>Toggle</Button>
+    </div>
+  );
+}
+
+describe('useAppStore', () => {
+  beforeEach(() => {
+    useAppStore.setState({ helpVisible: true });
+    // #region block:assistant
+    useAppStore.setState({ messages: [] });
+    // #endregion block:assistant
+  });
+
+  it('toggles help visibility on click', async () => {
+    const user = userEvent.setup();
+    render(<HelpToggleHarness />);
+
+    expect(screen.getByTestId('state')).toHaveTextContent('visible');
+
+    await user.click(screen.getByRole('button', { name: 'Toggle' }));
+    expect(screen.getByTestId('state')).toHaveTextContent('hidden');
+
+    await user.click(screen.getByRole('button', { name: 'Toggle' }));
+    expect(screen.getByTestId('state')).toHaveTextContent('visible');
+  });
+
+  it('setHelpVisible writes the value directly', () => {
+    useAppStore.getState().setHelpVisible(false);
+    expect(useAppStore.getState().helpVisible).toBe(false);
+  });
+
+  // #region block:assistant
+  it('appends a user message and an assistant reply per send', () => {
+    useAppStore.getState().send('why is June over budget?');
+
+    const { messages } = useAppStore.getState();
+    expect(messages).toHaveLength(2);
+    expect(messages[0]).toMatchObject({ role: 'user', text: 'why is June over budget?' });
+    expect(messages[1]?.role).toBe('assistant');
+  });
+  // #endregion block:assistant
+
+  // `partialize` is the whole reason persistence is safe here, and it is invisible
+  // at every call site — widening it would silently restore a stale transcript and
+  // pin `fullscreen` open across sessions. Assert the written shape, not just that
+  // `sidebarMode` survives.
+  it('persists the layout preference and nothing else', () => {
+    const { setSidebarMode } = useAppStore.getState();
+    // #region block:assistant
+    const { send, toggleFullscreen } = useAppStore.getState();
+    send('a prompt worth not resurrecting');
+    toggleFullscreen();
+    // #endregion block:assistant
+    setSidebarMode('collapsed');
+
+    const persisted = JSON.parse(localStorage.getItem(UI_SETTINGS_STORAGE_KEY) ?? '{}');
+
+    expect(persisted.state).toEqual({ sidebarMode: 'collapsed' });
+  });
+
+  it.each([
+    ['restores a mode it recognises', 'collapsed', 'collapsed'],
+    // A mode renamed or dropped by a later build leaves this behind in a returning
+    // visitor's storage. Unguarded it reaches `SidebarProvider`, which matches no
+    // state branch and strands the rail at icon width.
+    ['falls back when the stored mode is not a mode', 'expand-on-click', 'expanded'],
+  ])('%s', async (_name, stored, expected) => {
+    useAppStore.setState({ sidebarMode: 'expanded' });
+    localStorage.setItem(
+      UI_SETTINGS_STORAGE_KEY,
+      JSON.stringify({ state: { sidebarMode: stored }, version: 0 }),
+    );
+
+    await useAppStore.persist.rehydrate();
+
+    expect(useAppStore.getState().sidebarMode).toBe(expected);
+  });
+});

package/dist/template/src/store.ts

@@ -0,0 +1,67 @@
+import { create } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+
+// #region block:assistant
+import type { AssistantSlice } from './slices/assistant';
+import { createAssistantSlice } from './slices/assistant';
+// #endregion block:assistant
+import type { ShellSlice } from './slices/shell';
+import { createShellSlice, isSidebarMode } from './slices/shell';
+
+/** Where the persisted slice lives. */
+export const UI_SETTINGS_STORAGE_KEY = '__APP_NAME__/ui-settings';
+
+/** Every slice the app carries, merged into one flat store. */
+export type AppState = ShellSlice &
+  // #region block:assistant
+  AssistantSlice &
+  // #endregion block:assistant
+  // `unknown` is the identity for `&`, so the line above can go without leaving a dangling
+  // operator. The comment keeps this alias on three lines, which is what `oxfmt` expects of
+  // it in an app that dropped the middle term.
+  unknown;
+
+export const useAppStore = create<AppState>()(
+  devtools(
+    // `persist` inside `devtools` so rehydration lands in the devtools timeline as an
+    // action. Only `sidebarMode` is written out — see `partialize`.
+    persist(
+      // Zustand's slice pattern: `(...a)` forwards `set`, `get` and the store API to
+      // each creator without naming the three of them per slice.
+      (...a) => ({
+        ...createShellSlice(...a),
+        // #region block:assistant
+        ...createAssistantSlice(...a),
+        // #endregion block:assistant
+      }),
+      {
+        name: UI_SETTINGS_STORAGE_KEY,
+        // No `version` here on purpose. Zustand discards a record whose version does not
+        // match and no `migrate` covers, so a bare bump silently resets every returning
+        // visitor. If the stored shape ever changes, add `version` and `migrate` in the
+        // same change. A value that is merely unrecognised is `merge`'s job, below.
+        // The layout preference and nothing else. The default is the whole store, which
+        // would restore a stale transcript on reload and pin `fullscreen` open across
+        // sessions.
+        partialize: (state) => ({ sidebarMode: state.sidebarMode }),
+        // Validate at the storage boundary instead of trusting what comes back.
+        // - `localStorage` is user-writable, and a value written by an older build
+        //   outlives the code that wrote it.
+        // - An unrecognised mode is not inert: `SidebarProvider` derives the rail's
+        //   `state` from it, no branch matches, so the rail sticks at icon width with
+        //   nothing checked in the mode menu — recoverable only by picking a mode.
+        // - Falling back to `current` means the in-memory default, so a junk value
+        //   reads exactly like a first visit.
+        merge: (persisted, current) => {
+          const stored: unknown =
+            typeof persisted === 'object' && persisted !== null
+              ? Reflect.get(persisted, 'sidebarMode')
+              : undefined;
+
+          return { ...current, sidebarMode: isSidebarMode(stored) ? stored : current.sidebarMode };
+        },
+      },
+    ),
+    { name: '__APP_NAME__/app' },
+  ),
+);

package/dist/template/src/test-setup.ts

@@ -0,0 +1,11 @@
+import '@testing-library/jest-dom/vitest';
+
+// jsdom ships no ResizeObserver.
+// - Radix's ScrollArea constructs one in a layout effect.
+// - `Sidebar.Content` and several other `@keboola/design` surfaces build on it, so any
+//   test rendering a scrollable design surface throws without this stub.
+globalThis.ResizeObserver ??= class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+} as unknown as typeof globalThis.ResizeObserver;

package/dist/template/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/dist/template/templates/agent-safety/README.md

@@ -0,0 +1,14 @@
+# Agent-safety templates
+
+Opt-in, per-runtime enforcement stubs for the safety policy. **The policy in [`../../AGENTS.md`](../../AGENTS.md) (section "Safety & secrets (all agents)") is the source of truth** — every agent reads it, regardless of runtime. These files are mechanical projections of the same secrets glob list into each runtime's syntax, for runtimes that support hard enforcement.
+
+There is no single cross-agent enforcement file, so pick the one for the agent you actually use and copy it to the repo root (renaming as noted):
+
+| Agent runtime   | Mechanism                                          | Template                    | Copy to                 |
+| --------------- | -------------------------------------------------- | --------------------------- | ----------------------- |
+| Claude Code     | `.claude/settings.json` `permissions.{deny,ask}`   | `claude-code.settings.json` | `.claude/settings.json` |
+| Cursor          | `.cursorignore` (read-block)                       | `cursorignore`              | `.cursorignore`         |
+| Gemini CLI      | `.aiexclude`                                       | `aiexclude`                 | `.aiexclude`            |
+| (baseline, all) | `.gitignore` already keeps secrets out of the tree | —                           | —                       |
+
+`AGENTS.md` owns the policy; these templates hold the exhaustive secrets glob list that enforces it. Keep the same set of protected paths across the templates (the glob syntax differs per runtime), and update the summary in `AGENTS.md` if you extend the list.

package/dist/template/templates/agent-safety/aiexclude

@@ -0,0 +1,25 @@
+# Copy to .aiexclude at the repo root. Blocks Gemini CLI from reading secrets.
+# Enforces the secrets policy in ../../AGENTS.md (the source of truth);
+# this file is the exhaustive glob list for that policy.
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+*id_rsa*
+*id_ed25519*
+.ssh/
+.aws/credentials
+.aws/config
+.kube/config
+.npmrc
+.git-credentials
+*token
+*token.*
+*secret*
+*credential*
+*password*
+*apikey*
+.htpasswd

package/dist/template/templates/agent-safety/claude-code.settings.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./**/*.pem)",
+      "Read(./**/*.key)",
+      "Read(./**/*.p12)",
+      "Read(./**/*.pfx)",
+      "Read(./**/*.keystore)",
+      "Read(./**/*id_rsa*)",
+      "Read(./**/*id_ed25519*)",
+      "Read(./.ssh/**)",
+      "Read(./.aws/credentials)",
+      "Read(./.aws/config)",
+      "Read(./.kube/config)",
+      "Read(./.npmrc)",
+      "Read(./.git-credentials)",
+      "Read(./**/*token)",
+      "Read(./**/*token.*)",
+      "Read(./**/*secret*)",
+      "Read(./**/*credential*)",
+      "Read(./**/*password*)",
+      "Read(./**/*apikey*)",
+      "Read(./**/.htpasswd)"
+    ],
+    "ask": [
+      "Bash(rm:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git clean:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push --force-with-lease:*)",
+      "Bash(npm install:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm add:*)",
+      "Bash(yarn install:*)",
+      "Bash(yarn add:*)",
+      "Edit(./package.json)",
+      "Edit(./**/package.json)",
+      "Edit(./pnpm-lock.yaml)",
+      "Edit(./package-lock.json)",
+      "Edit(./yarn.lock)"
+    ]
+  }
+}

package/dist/template/templates/agent-safety/cursorignore

@@ -0,0 +1,25 @@
+# Copy to .cursorignore at the repo root. Blocks Cursor from reading secrets.
+# Enforces the secrets policy in ../../AGENTS.md (the source of truth);
+# this file is the exhaustive glob list for that policy.
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+*.keystore
+*id_rsa*
+*id_ed25519*
+.ssh/
+.aws/credentials
+.aws/config
+.kube/config
+.npmrc
+.git-credentials
+*token
+*token.*
+*secret*
+*credential*
+*password*
+*apikey*
+.htpasswd

package/dist/template/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@keboola/tsconfig/react.json",
+  "include": ["src"],
+  "compilerOptions": {
+    "types": ["node"],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

package/dist/template/vercel.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
+}

package/dist/template/vite.config.ts

@@ -0,0 +1,21 @@
+import tailwindcss from '@tailwindcss/vite';
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite';
+import react from '@vitejs/plugin-react';
+import path from 'node:path';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    TanStackRouterVite({
+      routesDirectory: './src/routes',
+      generatedRouteTree: './src/routeTree.gen.ts',
+    }),
+    react(),
+    tailwindcss(),
+  ],
+  resolve: {
+    alias: {
+      '@': path.resolve(import.meta.dirname, 'src'),
+    },
+  },
+});

package/dist/template/vitest.config.ts

@@ -0,0 +1,21 @@
+import path from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: ['./src/test-setup.ts'],
+    // This suite runs inside the repo-wide `Checks` job, so it shares a 2-core
+    // runner with every other package's tests — ~25x slower per test than a dev
+    // machine here (measured: AssistantPanel's two prompt tests are 156ms/199ms
+    // locally, 3881ms/5189ms there). The 5s default clips whichever one loses the
+    // race; the userEvent-driven tests get headroom instead.
+    testTimeout: 15000,
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(import.meta.dirname, 'src'),
+    },
+  },
+});

package/dist/template/workspace-deps.json

@@ -0,0 +1,7 @@
+[
+  "@keboola/brand-registry",
+  "@keboola/design",
+  "@keboola/eslint-plugin-design",
+  "@keboola/oxlint-config",
+  "@keboola/tsconfig"
+]

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "create-keboola-app",
+  "version": "0.0.0",
+  "description": "Scaffold a Keboola-shaped frontend app — Vite + React 19 + TanStack Router/Query/Form + Zustand + @keboola/design — from a minimal shell plus the blocks you pick",
+  "license": "MIT",
+  "type": "module",
+  "bin": "./dist/cli.js",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown && node dist/extract.js",
+    "lint": "pnpm lint:format && pnpm lint:oxlint",
+    "lint:fix": "oxlint --fix . && oxfmt",
+    "lint:format": "oxfmt --check",
+    "lint:oxlint": "oxlint . --quiet",
+    "knip:check": "pnpm --dir ../.. exec knip --workspace packages/create-keboola-app",
+    "knip:fix": "pnpm --dir ../.. exec knip --workspace packages/create-keboola-app --fix-type types,exports,files",
+    "test": "vitest run --passWithNoTests --reporter=dot",
+    "type-check": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keboola/ui.git",
+    "directory": "packages/create-keboola-app"
+  },
+  "homepage": "https://github.com/keboola/ui/tree/main/packages/create-keboola-app#readme",
+  "bugs": {
+    "url": "https://github.com/keboola/ui/issues"
+  },
+  "keywords": [
+    "keboola",
+    "scaffold",
+    "generator",
+    "create",
+    "react",
+    "vite",
+    "tanstack",
+    "cli"
+  ],
+  "dependencies": {
+    "@tanstack/router-generator": "^1.120.4"
+  },
+  "devDependencies": {
+    "@keboola/oxlint-config": "workspace:^",
+    "@keboola/tsconfig": "workspace:^",
+    "@types/node": "24.12.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.72.0",
+    "tsdown": "^0.22.14",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}