@sensolus/create-snt-agent-app 0.1.0

package/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * npm create @sensolus/snt-agent-app my-app
+ *
+ * Copies the template into ./my-app, substituting {{APP_NAME}}.
+ * Files prefixed with _ are renamed to dotfiles (npm publish strips real dotfiles).
+ */
+import { cp, readdir, readFile, writeFile, rename, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const templateDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'template')
+
+const rawName = process.argv[2]
+if (!rawName) {
+  console.error('Usage: npm create @sensolus/snt-agent-app <app-name>')
+  process.exit(1)
+}
+const appName = rawName.toLowerCase().replace(/[^a-z0-9-_]/g, '-')
+const targetDir = path.resolve(process.cwd(), appName)
+
+if (existsSync(targetDir)) {
+  console.error(`Error: directory ${appName} already exists.`)
+  process.exit(1)
+}
+
+await cp(templateDir, targetDir, { recursive: true })
+
+// Rename _gitignore -> .gitignore etc.
+for (const entry of await readdir(targetDir)) {
+  if (entry.startsWith('_')) {
+    await rename(path.join(targetDir, entry), path.join(targetDir, '.' + entry.slice(1)))
+  }
+}
+
+// Substitute {{APP_NAME}} in text files
+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
+    const content = await readFile(p, 'utf8')
+    if (content.includes('{{APP_NAME}}')) {
+      await writeFile(p, content.replaceAll('{{APP_NAME}}', appName))
+    }
+  }
+}
+await substitute(targetDir)
+
+console.log(`
+Created ${appName}/
+
+Next steps:
+  cd ${appName}
+  npm install
+  pip install -r backend/requirements.txt
+  npm run dev                 # frontend on :3000
+  python backend/app.py       # backend on :5000 (separate terminal)
+
+Rules: widgets/theme/i18n come from @sensolus/snt-agent-kit — import, don't copy.
+ESLint enforces no deep imports and no Snt* re-declarations.
+`)

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@sensolus/create-snt-agent-app",
+  "version": "0.1.0",
+  "description": "Scaffold a new Sensolus agent app: React frontend wired to @sensolus/snt-agent-kit + Flask API proxy backend.",
+  "type": "module",
+  "bin": {
+    "create-snt-agent-app": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/template/README.md

@@ -0,0 +1,26 @@
+# {{APP_NAME}}
+
+Sensolus agent app, generated by `@sensolus/create-snt-agent-app`.
+
+## Run
+
+```bash
+npm install
+pip install -r backend/requirements.txt
+npm run dev                # frontend :3000 (proxies /api -> :5000)
+python backend/app.py      # backend :5000, separate terminal
+```
+
+## Rules
+
+- UI widgets, theme, colors and i18n framework come from **`@sensolus/snt-agent-kit`** —
+  import them, never copy their source into this repo.
+- `npm run lint` enforces: no deep imports into the kit, no re-declaring `Snt*` components.
+- Need widget customization? Use slots/render props; if none fits, PR the
+  `snt-agent-kit` repo. There is no eject path.
+- Kit updates: `npm update @sensolus/snt-agent-kit`.
+
+## i18n
+
+App keys live in `src/i18n/messages.js`, merged via `<LocaleProvider messages>`.
+Common strings (`common.*`, `table.*`) ship with the kit.

package/template/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.log
+.env
+__pycache__/
+.venv/
+.DS_Store

package/template/backend/app.py

@@ -0,0 +1,70 @@
+"""
+{{APP_NAME}} backend — Flask proxy to the Sensolus public API.
+
+Avoids CORS by forwarding /api/* to https://<SENSOLUS_DOMAIN>/rest/api/v2/*.
+
+Auth (same contract as sample_micro_app):
+  1. Session cookie `prod-sensolus-token` -> Authorization: Bearer <token>
+  2. SENSOLUS_API_KEY env var          -> ?apiKey=<key> query parameter
+  Cookie wins if both are present.
+"""
+import os
+
+import requests
+from flask import Flask, jsonify, request, send_from_directory
+
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+SENSOLUS_DOMAIN = os.environ.get("SENSOLUS_DOMAIN", "cloud.sensolus.com")
+SENSOLUS_BASE_URL = f"https://{SENSOLUS_DOMAIN}/rest/api/v2"
+SENSOLUS_COOKIE_NAME = os.environ.get("SENSOLUS_COOKIE_NAME", "prod-sensolus-token")
+SENSOLUS_API_KEY = os.environ.get("SENSOLUS_API_KEY")
+
+app = Flask(__name__, static_folder=os.path.join(PROJECT_ROOT, "dist"))
+
+
+def _auth(params, headers):
+    """Apply Sensolus auth to outgoing request parts. Cookie beats API key."""
+    token = request.cookies.get(SENSOLUS_COOKIE_NAME)
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    elif SENSOLUS_API_KEY:
+        params["apiKey"] = SENSOLUS_API_KEY
+    return params, headers
+
+
+@app.route("/api/loginInfo")
+def login_info():
+    """User preferences for the kit's LocaleProvider (language, timezone, units)."""
+    params, headers = _auth({}, {})
+    try:
+        resp = requests.get(f"{SENSOLUS_BASE_URL}/loginInfo", params=params, headers=headers, timeout=10)
+        if resp.ok:
+            return jsonify(resp.json())
+    except requests.RequestException:
+        pass
+    return jsonify({})  # kit falls back to defaults
+
+
+@app.route("/api/<path:subpath>")
+def api_proxy(subpath):
+    """Generic GET proxy to the Sensolus API."""
+    params, headers = _auth(dict(request.args), {})
+    try:
+        resp = requests.get(f"{SENSOLUS_BASE_URL}/{subpath}", params=params, headers=headers, timeout=30)
+        return (resp.content, resp.status_code, {"Content-Type": resp.headers.get("Content-Type", "application/json")})
+    except requests.RequestException as exc:
+        return jsonify({"error": str(exc)}), 502
+
+
+# --- Serve built frontend (production) ---------------------------------------
+@app.route("/", defaults={"path": ""})
+@app.route("/<path:path>")
+def serve_frontend(path):
+    if path and os.path.exists(os.path.join(app.static_folder, path)):
+        return send_from_directory(app.static_folder, path)
+    return send_from_directory(app.static_folder, "index.html")
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True)

package/template/backend/requirements.txt

@@ -0,0 +1,2 @@
+flask>=3.0
+requests>=2.31

package/template/eslint.config.js

@@ -0,0 +1,45 @@
+import js from '@eslint/js'
+import react from 'eslint-plugin-react'
+
+/**
+ * Guardrails for the locked @sensolus/snt-agent-kit (do not remove):
+ * 1. no deep imports into the kit's dist/
+ * 2. no re-declaring Snt* components in app code (use kit slots/props, or PR the kit)
+ */
+export default [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.{js,jsx}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parserOptions: { ecmaFeatures: { jsx: true } },
+      globals: { fetch: 'readonly', console: 'readonly', window: 'readonly', document: 'readonly' },
+    },
+    plugins: { react },
+    rules: {
+      'react/jsx-uses-react': 'error',
+      'react/jsx-uses-vars': 'error',
+      'no-restricted-imports': ['error', {
+        patterns: [{
+          group: ['@sensolus/snt-agent-kit/*', '!@sensolus/snt-agent-kit/theme.css'],
+          message: 'Deep imports into @sensolus/snt-agent-kit are forbidden. Import from the package root (theme.css is the only allowed subpath).',
+        }],
+      }],
+      'no-restricted-syntax': ['error',
+        {
+          selector: 'FunctionDeclaration[id.name=/^Snt[A-Z]/]',
+          message: 'Do not re-declare Snt* components in app code. Use kit slots/render props, or open a PR on the agent-kit.',
+        },
+        {
+          selector: 'VariableDeclarator[id.name=/^Snt[A-Z]/]',
+          message: 'Do not re-declare Snt* components in app code. Use kit slots/render props, or open a PR on the agent-kit.',
+        },
+        {
+          selector: 'ClassDeclaration[id.name=/^Snt[A-Z]/]',
+          message: 'Do not re-declare Snt* components in app code. Use kit slots/render props, or open a PR on the agent-kit.',
+        },
+      ],
+    },
+  },
+]

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@sensolus/snt-agent-kit": "^0.1.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-router-dom": "^7.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "eslint": "^9.18.0",
+    "eslint-plugin-react": "^7.37.0",
+    "vite": "^7.3.1"
+  }
+}

package/template/src/App.jsx

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react'
+import { SntPageHeader, SntTable, SntBadge, SntButton, SntToolbar, SntLoadingOverlay, useLocale } from '@sensolus/snt-agent-kit'
+
+export default function App() {
+  const { t } = useLocale()
+  const [orgs, setOrgs] = useState(null)
+  const [loading, setLoading] = useState(false)
+
+  async function load() {
+    setLoading(true)
+    try {
+      const res = await fetch('/api/organisations')
+      setOrgs(res.ok ? await res.json() : [])
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => { load() }, [])
+
+  if (loading || orgs === null) return <SntLoadingOverlay message={t('common.loading')} />
+
+  return (
+    <div className="app-container">
+      <SntPageHeader title={t('app.title')} />
+      <SntToolbar>
+        <SntButton variant="secondary" onClick={load}>{t('common.reload')}</SntButton>
+      </SntToolbar>
+      <SntTable
+        data={orgs}
+        columns={[
+          { key: 'name', header: t('app.org.name') },
+          { key: 'status', header: t('app.org.status'), render: (row, val) => <SntBadge variant={val === 'ACTIVE' ? 'success' : 'secondary'} text={String(val ?? '')} /> },
+        ]}
+      />
+    </div>
+  )
+}

package/template/src/i18n/messages.js

@@ -0,0 +1,17 @@
+/**
+ * App-owned translation keys, merged into the kit's common strings via
+ * <LocaleProvider messages={messages}>. Add languages/keys as needed;
+ * English is the fallback for missing keys.
+ */
+export const messages = {
+  en: {
+    'app.title': '{{APP_NAME}}',
+    'app.org.name': 'Name',
+    'app.org.status': 'Status',
+  },
+  nl: {
+    'app.title': '{{APP_NAME}}',
+    'app.org.name': 'Naam',
+    'app.org.status': 'Status',
+  },
+}

package/template/src/main.jsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { LocaleProvider } from '@sensolus/snt-agent-kit'
+import '@sensolus/snt-agent-kit/theme.css'
+import App from './App'
+import { messages } from './i18n/messages'
+import './styles/app.css'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <LocaleProvider messages={messages}>
+      <App />
+    </LocaleProvider>
+  </React.StrictMode>
+)

package/template/src/styles/app.css

@@ -0,0 +1,6 @@
+/* App-specific styles. Theme variables (--snt-*) come from @sensolus/snt-agent-kit/theme.css */
+.app-container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 16px;
+}

package/template/vite.config.js

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 3000,
+    host: true,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:5000',
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: 'dist',
+  },
+})