create-astram-app 0.1.2 → 0.2.0

package/template/frontend/FRONTEND.md

@@ -0,0 +1,92 @@
+# __APP_NAME__ frontend
+
+This is the Astram framework's **identity frontend** — login, session, users, roles,
+companies, access, audit — scaffolded straight into your app. It is a real,
+production-shaped Vite/React UI (shadcn/ui + Tailwind v4), not a placeholder.
+
+## What this is
+
+The files under `frontend/` are **yours** — you own and edit them like any other
+part of your app. The framework does not manage or overwrite them once they're
+here.
+
+The actual auth/session/API **logic** does NOT live in these files — it comes from
+two npm packages:
+
+- **`@astram/frontend-core`** — auth flows, session handling, HTTP client wiring.
+- **`@astram/sdk`** — typed calls against the framework API (users, roles,
+  companies, access, audit).
+
+That split is what makes this model work: the **view** (these files: pages,
+components, routing, styling) is scaffolded once and is fully yours to change;
+the **logic** (auth correctness, new API surface, bug fixes) ships as ordinary
+npm package updates you pull in with `npm update`, without touching a single file
+in this folder.
+
+## Run
+
+```bash
+npm install
+npm run dev
+```
+
+- Opens the identity UI on **http://localhost:5173**.
+- Log in at **`/login`**.
+- The Vite dev server proxies **`/api`** to your backend on **`http://localhost:3000`**
+  (see `vite.config.js`) — the browser calls same-origin `/api/auth/login`, and the
+  proxy rewrites it to `/auth/login` on the server. Override the target with the
+  `API_URL` env var if your backend runs elsewhere.
+
+Make sure the framework backend (`../server`) is running first — this UI has
+nothing to talk to otherwise.
+
+## Re-skin
+
+You don't need to touch component code to make this look like your product:
+
+- **Name / logo** — copy `.env.example` to `.env` and set:
+  - `VITE_APP_NAME` — shown in the header/title instead of the default.
+  - `VITE_APP_LOGO` — path/URL to your logo (light theme).
+  - `VITE_APP_LOGO_DARK` — path/URL to your logo (dark theme).
+  - `VITE_APP_TAGLINE` / `VITE_APP_SUB_TAGLINE` — login-screen copy.
+- **Theme color** — edit the `--primary` / `--primary-foreground` oklch pair in
+  `src/index.css`: the `:root` block controls light mode, the `.dark` block
+  controls dark mode. Every primary button, focus ring, and accent in the UI
+  derives from this one token pair — change it once, it propagates everywhere.
+
+Both of these are **additive, config-only** customizations — they don't modify
+any scaffolded file, so a future framework/template update never conflicts with
+your branding.
+
+## Updates / no-clobber model
+
+Two different things update on two different schedules, and it's important to
+know which is which:
+
+1. **Logic (`@astram/frontend-core`, `@astram/sdk`)** updates like any other npm
+   dependency — `npm update` pulls in bug fixes and new API methods for free. You
+   never edit these packages directly (they live in `node_modules`).
+
+2. **View files (everything under `frontend/src/`, `frontend/index.html`, etc.)**
+   are yours. They were copied in ONCE, by either `create-astram-app --with-frontend`
+   at scaffold time or by `npx astram-add-frontend` afterwards. Nothing in the
+   framework reaches back into this folder to overwrite your edits — this file, a
+   page you've re-themed, a component you've customized, all survive indefinitely.
+
+3. **Re-running `npx astram-add-frontend` is safe, any time.** It's additive and
+   idempotent: it only writes files that are still missing (e.g. the published
+   template gained a new page or component since you last ran it). Any file that
+   already exists in your `frontend/` — including one you've heavily edited — is
+   left completely untouched. It will never overwrite your work.
+
+4. **Adopting an improved framework screen is a manual, deliberate step**, not an
+   automatic one — by design, so you're never surprised by a silent overwrite. If
+   a newer `create-astram-app` release improves a page you're using unmodified
+   (e.g. a better `Login.jsx`), diff your version against the current template
+   (published inside the `create-astram-app` npm package, under `template/frontend/`)
+   and cherry-pick the parts you want.
+
+The practical effect: keep your branding in `.env` + the `--primary` token instead
+of hand-editing component internals wherever you can — it keeps your view files
+close to the upstream template, which makes adopting future improvements a small
+diff instead of a merge conflict.

package/template/frontend/README.md

@@ -0,0 +1,16 @@
+# frontend
+
+Your UI lives here. This folder is intentionally empty — the Astram framework is a
+**backend security kernel**, so it does not impose a frontend framework. Add whatever
+you like (Vite + React, Next.js, SvelteKit, a mobile app's web build, …) and point it
+at the API in `../server` (default `http://localhost:3000`).
+
+The API's auth surface is ready to consume:
+
+- `POST /auth/login` `{ identityHint, password }` → `{ session, tokens: { accessToken, refreshToken } }`
+- `POST /auth/refresh` `{ refreshToken }` → new tokens
+- `POST /auth/logout` `{ sessionId }` → 204
+- Protected routes: send `Authorization: Bearer <accessToken>`. A `@Classified` route
+  is enforced by the framework — no token → 401, denied by policy → 403.
+
+See `../server/src/features/` for the API features your UI will call.

package/template/frontend/_env.example

@@ -0,0 +1,6 @@
+# __APP_NAME__ frontend — copy to .env; all optional (astram defaults apply).
+# VITE_APP_NAME=My App
+# VITE_APP_LOGO=/my-logo.png
+# VITE_APP_LOGO_DARK=/my-logo-dark.png
+# VITE_APP_TAGLINE=...
+# VITE_APP_SUB_TAGLINE=...

package/template/frontend/_gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+
+# Local env files (real values). `.env.example` is committed as the template.
+.env
+.env.*
+!.env.example

package/template/frontend/eslint.config.js

@@ -0,0 +1,71 @@
+// Frontend ESLint flat config (ESLint 9) for an Astram consumer app.
+//
+// React + hooks + fast-refresh rules over the JS/JSX source. The `lint` script
+// (`eslint "src/**/*.{js,jsx}"`) resolves this file. The Vite build is the
+// correctness gate; this catches unused vars, hook-dependency mistakes, and
+// fast-refresh foot-guns. Uses the framework's `_`-prefixed-unused convention.
+import js from '@eslint/js';
+import globals from 'globals';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+
+export default [
+  {
+    ignores: ['node_modules/**', 'dist/**', 'coverage/**', 'eslint.config.js'],
+  },
+
+  js.configs.recommended,
+
+  {
+    files: ['src/**/*.{js,jsx}'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: { ...globals.browser },
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+      },
+    },
+    settings: {
+      react: { version: 'detect' },
+    },
+    plugins: {
+      react,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...react.configs.flat.recommended.rules,
+      ...react.configs.flat['jsx-runtime'].rules, // React 18 automatic JSX runtime — no `React` import needed.
+      ...reactHooks.configs.flat.recommended.rules,
+
+      // Allow `_`-prefixed intentionally-unused args/vars (shared convention).
+      'no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' },
+      ],
+
+      // Fast-refresh: warn (not error) when a module exports non-components
+      // alongside components — common + harmless in shadcn ui files.
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+
+      // Project convention: PropTypes are not used (no `prop-types` dep).
+      'react/prop-types': 'off',
+
+      // react-hooks 7.x ships new, very aggressive rules that flag idiomatic
+      // patterns (a mount-guard `setState` in an effect, a fetch-on-mount
+      // `load()` effect, the lazy-ref-init `if (!ref.current) ref.current = …`
+      // one-time init, etc.). These were REVIEWED case-by-case (task #138): every
+      // current hit is a known-good idiom, not a bug — promoting them to error
+      // would force contorting clean code, so they stay ADVISORY (warn): visible,
+      // non-blocking. The genuinely load-bearing hooks rules below stay errors.
+      // If a future hit is an actual bug, fix that site; don't relax the warn.
+      'react-hooks/set-state-in-effect': 'warn',
+      'react-hooks/refs': 'warn',
+      // These two catch real bugs — keep them blocking.
+      'react-hooks/exhaustive-deps': 'error',
+      'react-hooks/rules-of-hooks': 'error',
+    },
+  },
+];

package/template/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" suppressHydrationWarning>
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <link rel="icon" type="image/png" href="/favicon.png" />
+    <title>__APP_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/template/frontend/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "The frontend (UI) half of an Astram consumer app — a professional web UI (login / auth / identity management) over the framework auth API. Built on shadcn/ui + Tailwind v4; shared auth/http logic comes from @astram/frontend-core and @astram/sdk. The API (../server) lives at http://localhost:3000 by default.",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint \"src/**/*.{js,jsx}\"",
+    "test": "node --test src/**/*.test.mjs"
+  },
+  "dependencies": {
+    "@astram/frontend-core": "^0.1.0",
+    "@astram/sdk": "^0.2.0",
+    "@radix-ui/react-alert-dialog": "^1.1.19",
+    "@radix-ui/react-avatar": "^1.1.10",
+    "@radix-ui/react-checkbox": "^1.1.4",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-select": "^2.3.3",
+    "@radix-ui/react-separator": "^1.1.7",
+    "@radix-ui/react-slot": "^1.2.3",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "input-otp": "^1.4.2",
+    "lucide-react": "^0.460.0",
+    "next-themes": "^0.4.6",
+    "qrcode": "^1.5.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.26.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@tailwindcss/vite": "^4.1.14",
+    "@vitejs/plugin-react": "^4.3.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^17.7.0",
+    "tailwindcss": "^4.1.14",
+    "tw-animate-css": "^1.4.0",
+    "vite": "^5.4.0"
+  }
+}

package/template/frontend/src/App.jsx

@@ -0,0 +1,167 @@
+/**
+ * App — routing + auth guards.
+ *
+ *   /login, /forgot-password  → public auth screens (redirect to /dashboard if
+ *                               already signed in)
+ *   /dashboard                → protected (RequireAuth bounces to /login, saving the
+ *                               return path)
+ */
+
+import { useEffect } from 'react';
+import { Navigate, Route, Routes, useLocation } from 'react-router-dom';
+import { useAuth, useCan } from './auth/AuthContext';
+import { saveReturnPath } from './platform/returnPathStore';
+import Login from './pages/Login';
+import ForgotPassword from './pages/ForgotPassword';
+import ResetPassword from './pages/ResetPassword';
+import Dashboard from './pages/Dashboard';
+import AccountLayout from './pages/account/AccountLayout';
+import ProfilePage from './pages/account/ProfilePage';
+import ChangePasswordPage from './pages/account/ChangePasswordPage';
+import TwoFactorPage from './pages/account/TwoFactorPage';
+import ReenrollPage from './pages/account/ReenrollPage';
+import CompaniesPage from './pages/companies/CompaniesPage';
+import CompanyForm from './pages/companies/CompanyForm';
+import RolesPage from './pages/roles/RolesPage';
+import RoleForm from './pages/roles/RoleForm';
+import UsersPage from './pages/users/UsersPage';
+import UserForm from './pages/users/UserForm';
+import AccessPage from './pages/access/AccessPage';
+import AccessForm from './pages/access/AccessForm';
+import AuditPage from './pages/audit/AuditPage';
+
+/** The single forced-re-enroll screen path (the enforcement's frontend twin). */
+const REENROLL_PATH = '/account/reenroll';
+
+/** Only-when-signed-out (auth screens bounce authenticated users to the app). */
+function PublicOnly({ children }) {
+  const { isAuthenticated } = useAuth();
+  return isAuthenticated ? <Navigate to="/dashboard" replace /> : children;
+}
+
+/**
+ * Only-when-signed-in (protected pages bounce to login, remembering where you were).
+ *
+ * ALSO the frontend twin of the server-side re-enroll gate: when the session is
+ * `mustReenroll` (recovery-code login), every protected route is pinned to the forced
+ * re-enroll screen — mirroring the server 403'ing every non-allowlisted route. The
+ * enforcement is server-side (this is UX, not the security boundary); it just spares
+ * the user a bounce-through-403 on each click until a device is confirmed.
+ *
+ * `gate` (Phase E slice 1, optional): a permission KEY required to render this route.
+ * When absent from the caller's auth-facts projection, redirect to `/dashboard` instead
+ * of rendering — sparing a direct-navigation bounce-through-403 the same way `mustReenroll`
+ * does above. UX ONLY: the server's decide() on the page's underlying @Classified route
+ * remains the real enforcement regardless of this check (a stale/tampered projection just
+ * means the user reaches the page and then gets 403'd by its data calls).
+ */
+function RequireAuth({ children, gate }) {
+  const { isAuthenticated, mustReenroll } = useAuth();
+  // Called UNCONDITIONALLY (Rules of Hooks) — `useCan(undefined)` simply resolves to
+  // `false` when no gate is set, so the ungated case is handled by short-circuiting on
+  // `gate &&` below rather than skipping the hook call itself.
+  const canGate = useCan(gate);
+  const allowed = !gate || canGate;
+  const location = useLocation();
+  // Remember where the user was so the next login returns them here. Persisted to
+  // localStorage (via saveReturnPath) so it survives a full reload / browser restart —
+  // the in-memory `from` router state below only helps within the same page session.
+  // Done in an effect (a render-time side-effect would be impure); path+search so a
+  // deep-linked list page (e.g. ?page=2) restores exactly.
+  const fullPath = location.pathname + location.search;
+  useEffect(() => {
+    if (!isAuthenticated) saveReturnPath(fullPath);
+  }, [isAuthenticated, fullPath]);
+
+  if (!isAuthenticated) {
+    return <Navigate to="/login" replace state={{ from: fullPath }} />;
+  }
+  if (mustReenroll && location.pathname !== REENROLL_PATH) {
+    return <Navigate to={REENROLL_PATH} replace />;
+  }
+  if (gate && !allowed) {
+    return <Navigate to="/dashboard" replace />;
+  }
+  return children;
+}
+
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<PublicOnly><Login /></PublicOnly>} />
+      <Route path="/forgot-password" element={<PublicOnly><ForgotPassword /></PublicOnly>} />
+      <Route path="/reset-password" element={<PublicOnly><ResetPassword /></PublicOnly>} />
+      <Route path="/dashboard" element={<RequireAuth><Dashboard /></RequireAuth>} />
+      {/* Forced re-enroll — a standalone full-screen flow (NOT an account tab). While
+          the session is `mustReenroll`, RequireAuth pins every other protected route
+          here; this path is the one RequireAuth lets through so the screen can load. */}
+      <Route path="/account/reenroll" element={<RequireAuth><ReenrollPage /></RequireAuth>} />
+      {/* Account — a persistent layout with per-tab child routes (bookmarkable, back
+          works). /account redirects to the Profile tab. */}
+      <Route path="/account" element={<RequireAuth><AccountLayout /></RequireAuth>}>
+        <Route index element={<Navigate to="/account/profile" replace />} />
+        <Route path="profile" element={<ProfilePage />} />
+        <Route path="password" element={<ChangePasswordPage />} />
+        <Route path="2fa" element={<TwoFactorPage />} />
+      </Route>
+      {/* Identity management — each list is a LAYOUT route; add/edit are child routes
+          that render as a routed-modal overlay (bookmarkable, back button closes).
+          `gate` (Phase E slice 1) mirrors the Sidebar's nav gating — VERIFIED against
+          each page's actual @Classified list route (see shell/nav.js's header doc). */}
+      <Route
+        path="/companies"
+        element={
+          <RequireAuth gate="identity:company:read">
+            <CompaniesPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<CompanyForm />} />
+        <Route path="edit/:uuid" element={<CompanyForm />} />
+      </Route>
+      <Route
+        path="/roles"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <RolesPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<RoleForm />} />
+        <Route path="edit/:uuid" element={<RoleForm />} />
+      </Route>
+      <Route
+        path="/users"
+        element={
+          <RequireAuth gate="identity:user:read">
+            <UsersPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<UserForm />} />
+        <Route path="edit/:uuid" element={<UserForm />} />
+      </Route>
+      <Route
+        path="/access"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <AccessPage />
+          </RequireAuth>
+        }
+      >
+        <Route path="add" element={<AccessForm />} />
+        <Route path="edit/:uuid" element={<AccessForm />} />
+      </Route>
+      {/* Audit — read-only, no child add/edit routes (audit events are immutable). */}
+      <Route
+        path="/audit"
+        element={
+          <RequireAuth gate="identity:role:read">
+            <AuditPage />
+          </RequireAuth>
+        }
+      />
+      <Route path="*" element={<Navigate to="/dashboard" replace />} />
+    </Routes>
+  );
+}