@sensolus/create-snt-agent-app 0.1.0 → 0.2.0

package/index.js

@@ -39,7 +39,7 @@ async function substitute(dir) {
   for (const entry of await readdir(dir)) {
     const p = path.join(dir, entry)
     if ((await stat(p)).isDirectory()) { await substitute(p); continue }
-    if (!/\.(json|js|jsx|html|md|py|txt|sh|css)$|^\.[a-z]+$/i.test(entry)) continue
+    if (!/\.(json|js|jsx|html|md|py|txt|sh|css|yml|yaml|ini|mako)$|^\.[a-z][a-z.]*$|^(Jenkinsfile|Dockerfile|Makefile)$/i.test(entry)) continue
     const content = await readFile(p, 'utf8')
     if (content.includes('{{APP_NAME}}')) {
       await writeFile(p, content.replaceAll('{{APP_NAME}}', appName))
@@ -53,6 +53,7 @@ Created ${appName}/
 
 Next steps:
   cd ${appName}
+  cp .env.example .env        # then fill in MAPBOX_KEY + LOCATIONIQ_KEY (required for SntMap)
   npm install
   pip install -r backend/requirements.txt
   npm run dev                 # frontend on :3000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensolus/create-snt-agent-app",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a new Sensolus agent app: React frontend wired to @sensolus/snt-agent-kit + Flask API proxy backend.",
   "type": "module",
   "bin": {

package/template/CLAUDE.md

@@ -0,0 +1,218 @@
+# CLAUDE.md
+
+> **Widgets, theme, colors and the i18n framework come from `@sensolus/snt-agent-kit`** —
+> import from the package, never copy widget source into this repo. ESLint enforces:
+> no deep imports into the kit, no re-declaring `Snt*` components. App-owned translation
+> keys live in `src/i18n/translations/` and are merged via `<LocaleProvider messages>`.
+> Theme: `import '@sensolus/snt-agent-kit/theme.css'` (in `main.jsx`).
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Run Commands
+
+```bash
+# Local development (frontend + backend)
+npm install                  # Install frontend dependencies
+npm run dev                  # Start Vite dev server on :3000 (proxies /api to Flask)
+python backend/app.py        # Start Flask backend on :5000 (in separate terminal)
+
+# Production build
+npm run build                # Build frontend to dist/
+python backend/app.py        # Serves from dist/
+
+# Docker build and run
+docker build -t {{APP_NAME}} .
+docker run -p 5000:5000 {{APP_NAME}}
+```
+
+Development: http://localhost:3000 (Vite with HMR)
+Production: http://localhost:5000 (Flask serves built frontend)
+
+## Architecture
+
+This is a Flask + React (Vite) dashboard for querying the Sensolus public API.
+
+### Project Structure
+
+```
+{{APP_NAME}}/
+├── src/                    # React frontend source
+│   ├── main.jsx           # Entry point
+│   ├── App.jsx            # Main app component
+│   ├── i18n/                  # App translation keys (framework from kit)
+│   └── styles/
+│       └── app.css        # App-specific styles
+├── backend/               # Flask backend
+│   ├── app.py             # Flask app (API proxy)
+│   └── requirements.txt   # Python dependencies
+├── index.html             # Vite entry HTML
+├── vite.config.js         # Vite configuration
+├── package.json           # Node dependencies
+└── openapi.json           # Sensolus API spec (reference)
+```
+
+The backend acts as a proxy to avoid CORS issues - the frontend calls `/api/organisations` which forwards to the Sensolus API.
+
+## Sensolus API Authentication
+
+The backend supports two authentication methods for the Sensolus API:
+
+### 1. Session Cookie (Bearer Token)
+If the user has a `prod-sensolus-token` cookie (from being logged into cloud.sensolus.com), it is passed as a Bearer token in the Authorization header:
+```
+Authorization: Bearer <token>
+```
+
+### 2. API Key (Query Parameter)
+API keys are passed as a query parameter to the Sensolus API:
+```
+GET /rest/api/v2/organisations?apiKey=<key>
+```
+
+**Priority:** Session cookie takes precedence over API key if both are present.
+
+## CI/CD
+
+Jenkins pipeline (Jenkinsfile) builds the Docker image using multi-stage build (Node for frontend, Python for backend).
+
+## Sensolus Design System
+
+This app uses the official Sensolus color palette and widgets. **Always use these when extending this app.**
+
+### Importing Widgets
+
+```jsx
+import { SntButton, SntInput, SntBadge, SntTable } from '@sensolus/snt-agent-kit'
+```
+
+### Available Widgets
+
+| Component | Description |
+|-----------|-------------|
+| `SntButton` | Primary button with variants (primary, secondary, success, danger, warning, info) |
+| `SntInput` | Text input (onChange receives value directly, not event) |
+| `SntBadge` | Status badge with color variants |
+| `SntCard` | Card container with optional image, title, badge |
+| `SntTable` | Sortable, paginated data table |
+| `SntSpinner` | Loading spinner (sizes: small, medium, large) |
+| `SntLoadingOverlay` | Centered spinner with optional message |
+| `SntToolbar` | Horizontal toolbar for grouping actions |
+| `SntButtonGroup` | Segmented control for exclusive selection |
+| `SntColors` | JavaScript color constants |
+
+### Color Palette (CSS Variables)
+
+```css
+/* Primary Brand Colors */
+--snt-blue-darkest: #212851;  /* Primary - headers, buttons */
+--snt-blue: #0071A1;          /* Links, focus states */
+
+/* Greys */
+--snt-grey: #535E6F;          /* Secondary text */
+--snt-grey-light: #B8BFCA;    /* Borders */
+
+/* Backgrounds */
+--snt-bg-zebra: #F9FAFA;      /* Alternating rows */
+--snt-white: #FFFFFF;
+
+/* Status Colors */
+--snt-green: #39CB99;         /* Success */
+--snt-yellow: #FFCC66;        /* Warning */
+--snt-red: #E00000;           /* Danger */
+--snt-infra: #00A6ED;         /* Info */
+```
+
+### Widget Examples
+
+```jsx
+// Button
+<SntButton variant="primary" onClick={handleClick}>Save</SntButton>
+
+// Input
+<SntInput value={query} onChange={setQuery} placeholder="Search..." />
+
+// Badge
+<SntBadge variant="success" text="ACTIVE" />
+
+// Button Group (toggle)
+<SntButtonGroup
+  options={[
+    { value: 'cards', label: 'Cards' },
+    { value: 'table', label: 'Table' }
+  ]}
+  value={viewMode}
+  onChange={setViewMode}
+/>
+
+// Table
+<SntTable
+  data={items}
+  columns={[
+    { key: 'name', header: 'Name' },
+    { key: 'status', header: 'Status', render: (row, val) => <SntBadge text={val} /> }
+  ]}
+/>
+
+// Loading
+<SntLoadingOverlay message="Loading data..." />
+```
+
+### Usage Guidelines
+
+1. **Always use CSS variables** for colors instead of hardcoded hex values
+2. **Import widgets** from `@sensolus/snt-agent-kit` - they're modular ES modules
+3. **Follow existing patterns** in `src/App.jsx` for examples
+4. **Reference the baseline** at `/sensolus/work/baseline/` for additional components not yet ported
+
+## Internationalization (i18n)
+
+The app fetches user preferences (language, timezone, units) from `/api/loginInfo` on startup and provides them via React context.
+
+### Supported Languages
+
+en, nl, fr, de, es — English is the fallback for any missing keys.
+
+### Using Translations in Components
+
+```jsx
+import { useLocale, formatNumber, formatShortDate } from '../i18n'
+
+function MyComponent() {
+  const { t, intlLocale, timezone } = useLocale()
+
+  return (
+    <div>
+      <h1>{t('orgList.title')}</h1>
+      <span>{formatNumber(1234, intlLocale)}</span>
+      <span>{formatShortDate('2026-03-23', intlLocale, timezone)}</span>
+    </div>
+  )
+}
+```
+
+### Adding Translations
+
+Translation files are in `src/i18n/translations/`. Each file exports a flat object with dot-namespaced keys:
+
+```js
+// Simple string
+'common.cancel': 'Cancel',
+
+// Interpolated string (use function)
+'table.showing': (from, to, total) => `Showing ${from} - ${to} of ${total} items`,
+```
+
+### Date/Number Formatting
+
+Always use `intlLocale` and `timezone` from `useLocale()` — never hardcode locales:
+
+```jsx
+import { formatShortDate, formatDateTime, formatNumber } from '../i18n'
+
+formatShortDate('2026-03-23', intlLocale, timezone) // "23 mrt. 2026" (nl)
+formatNumber(1234, intlLocale)                       // "1.234" (nl) vs "1,234" (en)
+```
+
+### Available Context Values
+
+`useLocale()` provides: `language`, `intlLocale`, `timezone`, `firstDayOfWeek`, `unitDistance`, `unitTemperature`, `t()`, `loading`

package/template/Dockerfile

@@ -0,0 +1,32 @@
+# Build stage - build the React frontend
+FROM node:20-slim AS builder
+
+WORKDIR /app
+
+# Install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Copy source and build
+COPY src/ src/
+COPY index.html vite.config.js ./
+RUN npm run build
+
+# Production stage - serve with Flask
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install Python dependencies
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy Flask app and built frontend
+COPY backend/ backend/
+COPY --from=builder /app/dist dist/
+
+EXPOSE 5000
+
+# Run with socketio.run() for proper WebSocket support (not gunicorn)
+ENV PYTHONUNBUFFERED=1
+CMD ["python", "backend/app.py"]

package/template/Jenkinsfile

@@ -0,0 +1,28 @@
+pipeline {
+    agent any
+
+    environment {
+        AWS_REGION = 'eu-west-1'
+        ECR_REGISTRY = '331708581843.dkr.ecr.eu-west-1.amazonaws.com'
+        IMAGE_NAME = '{{APP_NAME}}'
+        IMAGE_TAG = "${env.BUILD_NUMBER}"
+    }
+
+    stages {
+        stage('Build') {
+            steps {
+                sh "docker build -t ${IMAGE_NAME}:${IMAGE_TAG} -t ${IMAGE_NAME}:latest ."
+            }
+        }
+
+        stage('Push to ECR') {
+            steps {
+                sh "aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_REGISTRY}"
+                sh "docker tag ${IMAGE_NAME}:${IMAGE_TAG} ${ECR_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"
+                sh "docker tag ${IMAGE_NAME}:latest ${ECR_REGISTRY}/${IMAGE_NAME}:latest"
+                sh "docker push ${ECR_REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"
+                sh "docker push ${ECR_REGISTRY}/${IMAGE_NAME}:latest"
+            }
+        }
+    }
+}