create-saasicat-admin 1.0.0-rc.2 → 1.0.0-rc.20

package/README.md

@@ -1,14 +1,26 @@
 # create-saasicat-admin
 
+## What this is
+
 Scaffolding CLI for SuperAdmin frontend projects. Generates a runnable
 Vue 3 + Quasar + Vite project that builds on `@saasicat/ui-vue` and ships
 all standard pages.
 
+## What this is not
+
+Not a dependency. It runs once, writes a Vite + Vue 3 + Quasar project you
+own, and is never installed into it. Nothing it writes is generated again
+later — edit the files freely.
+
+Not the backend. The scaffolded admin talks to a NestJS application that
+already has `@saasicat/nest` wired; without one it starts and shows a login
+screen it cannot get past.
+
 ## Usage
 
 ```bash
 pnpm create saasicat-admin <dir> \
-  --project-key notesapp \
+  --app-key notesapp \
   --brand-name NotesApp \
   --logo-text NA \
   --api-base /api/v1/admin
@@ -16,7 +28,7 @@ pnpm create saasicat-admin <dir> \
 
 Generates this directory structure:
 
-```
+```text
 <dir>/
 ├── package.json
 ├── vite.config.ts
@@ -26,8 +38,7 @@ Generates this directory structure:
 │   ├── main.ts                       (calls createSuperAdminApp)
 │   ├── App.vue                       (<router-view />)
 │   ├── services/http.ts              (HTTP client + adminLogin stub)
-│   ├── router/routes.ts              (all standard pages)
-│   └── styles/theme.scss
+│   └── router/routes.ts              (all standard pages)
 └── README.md
 ```
 
@@ -41,15 +52,15 @@ pnpm dev   # http://localhost:9100/admin/login
 
 ## Options
 
-| Flag             | Default         | Purpose                                                 |
-| ---------------- | --------------- | ------------------------------------------------------- |
-| `--project-key`  | `app`           | catalogue this admin administers; also a storage prefix |
-| `--brand-name`   | `App`           | shown in the AdminLayout header                         |
-| `--logo-text`    | `AP`            | two-letter badge in the logo                            |
-| `--api-base`     | `/api/v1/admin` | backend endpoint prefix                                 |
-| `--dev-port`     | `9100`          | Vite dev server port                                    |
-| `--backend-port` | `3000`          | backend port for the Vite proxy                         |
-| `--no-install`   | false           | only generate files, skip the final `pnpm install`      |
+| Flag             | Default         | Purpose                                                      |
+| ---------------- | --------------- | ------------------------------------------------------------ |
+| `--app-key`      | `app`           | slug of the application; npm package name and storage prefix |
+| `--brand-name`   | `App`           | shown in the AdminLayout header                              |
+| `--logo-text`    | `AP`            | two-letter badge in the logo                                 |
+| `--api-base`     | `/api/v1/admin` | backend endpoint prefix                                      |
+| `--dev-port`     | `9100`          | Vite dev server port                                         |
+| `--backend-port` | `3000`          | backend port for the Vite proxy                              |
+| `--no-install`   | false           | only generate files, skip the final `pnpm install`           |
 
 ## What is left to do afterwards
 
@@ -59,3 +70,9 @@ pnpm dev   # http://localhost:9100/admin/login
 3. Adapt the Vite proxy in `vite.config.ts` to your backend port.
 
 Everything else comes from `@saasicat/ui-vue`.
+
+## Next
+
+- [Build the admin frontend](../../docs/guides/build-the-admin-frontend.md) — what the scaffolder
+  wrote, explained
+- [Design guide](../../docs/explanation/design-guide.md) — before you write a page of your own

package/bin/create.js

@@ -20,7 +20,7 @@ const OWN_VERSION = JSON.parse(
 ).version;
 
 export const DEFAULT_TOKENS = {
-    PROJECT_KEY: 'app',
+    APP_KEY: 'app',
     BRAND_NAME: 'App',
     LOGO_TEXT: 'AP',
     API_BASE: '/api/v1/admin',
@@ -30,7 +30,7 @@ export const DEFAULT_TOKENS = {
 };
 
 const TOKEN_FLAGS = {
-    'project-key': 'PROJECT_KEY',
+    'app-key': 'APP_KEY',
     'brand-name': 'BRAND_NAME',
     'logo-text': 'LOGO_TEXT',
     'api-base': 'API_BASE',
@@ -119,7 +119,7 @@ async function main() {
         console.log('Usage: pnpm create saasicat-admin <dir> [flags]');
         console.log('');
         console.log('Flags:');
-        console.log('  --project-key=app           the catalogue this admin administers');
+        console.log('  --app-key=app               the slug of this application');
         console.log('                              (also the storage-key prefix)');
         console.log('  --brand-name=App            brand name in the header');
         console.log('  --logo-text=AP              two-letter badge');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-saasicat-admin",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.20",
   "description": "Scaffolding CLI for SuperAdmin frontend projects (Vue 3 + Quasar + Vite). Generates a minimal working admin app built on @saasicat/ui-vue. Usage: `pnpm create saasicat-admin <dir>`.",
   "type": "module",
   "bin": {

package/templates/README.md.tpl

@@ -21,4 +21,5 @@ serve `__API_BASE__/manifest`.
 - Add your own project pages in `src/router/routes.ts` (with
   `createProjectPageHostRoute()` as a catch-all).
 - Register KPI cards, tenant actions and project pages in your backend
-  manifest (see `docs/handbook.md` §6.6 in the saasicat repo).
+  manifest (see `docs/guides/wire-the-backend.md`, "Manifest Contributions",
+  in the saasicat repo).

package/templates/package.json.tpl

@@ -1,5 +1,5 @@
 {
-    "name": "__PROJECT_KEY__-admin",
+    "name": "__APP_KEY__-admin",
     "version": "0.0.1",
     "private": true,
     "type": "module",
@@ -9,19 +9,15 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@quasar/extras": "^1.16.0",
         "@saasicat/core": "__PLATFORM_VERSION__",
         "@saasicat/ui-vue": "__PLATFORM_VERSION__",
         "axios": "^1.15.0",
         "pinia": "^3.0.0",
-        "quasar": "^2.22.0",
         "vue": "^3.5.0",
         "vue-router": "^4.5.0"
     },
     "devDependencies": {
-        "@quasar/vite-plugin": "^1.10.0",
         "@vitejs/plugin-vue": "^6.0.0",
-        "sass": "^1.83.0",
         "typescript": "^5.7.0",
         "vite": "^7.0.0",
         "vue-tsc": "^2.2.0"

package/templates/src/main.ts.tpl

@@ -1,10 +1,13 @@
 // Bootstrap. createSuperAdminApp wires up Quasar + Pinia + Router + guards.
 
-import 'quasar/src/css/index.sass';
-import '@quasar/extras/material-icons/material-icons.css';
-// Platform page styles (sa-* classes + CSS variables). Without it the
-// standard pages render unstyled.
+// Every stylesheet the admin needs, all from the one package you installed.
+// The components are built (ADR 0011), so their styles arrive as `style.css`
+// rather than being compiled by your build — without it the standard pages
+// render unstyled.
+import '@saasicat/ui-vue/quasar.css';
+import '@saasicat/ui-vue/icons.css';
 import '@saasicat/ui-vue/theme.css';
+import '@saasicat/ui-vue/style.css';
 
 import { createSuperAdminApp } from '@saasicat/ui-vue/quasar';
 import App from './App.vue';
@@ -15,7 +18,20 @@ import { useManifestStore } from './stores/manifest';
 
 const handle = createSuperAdminApp({
     rootComponent: App,
-    brand: { logoText: '__LOGO_TEXT__', name: '__BRAND_NAME__' },
+    // `color` is the ONE place your admin's brand colour is decided:
+    // `--sa-color-accent` reads Quasar's `--q-primary`, which this writes, so
+    // the hero, the buttons, the focus ring, the tinted surfaces, Quasar's own
+    // components and the tenant-facing pages all follow. There is no second
+    // switch — with one trap beside it: Quasar's own `config.brand` writes to
+    // `<body>`, where the accent role cannot see it. Leave that one alone.
+    //
+    // The default is SaaSiCat's own, so a fresh admin looks like the
+    // documentation until you decide otherwise.
+    //
+    // One caveat if you pick a LIGHT brand: text on accent-filled controls is
+    // white, and CSS cannot work out that white on a light amber is 2.15:1.
+    // Override `--sa-color-fg-on-accent` in your own CSS if so — in both themes.
+    brand: { logoText: '__LOGO_TEXT__', name: '__BRAND_NAME__', color: '#3f6bff' },
     endpoints: ADMIN_ENDPOINTS,
     appRoutes,
     loginAdapter: { login: adminLogin },
@@ -37,7 +53,7 @@ const handle = createSuperAdminApp({
     extensions: {},
     // Starting UI language — the shell's header switcher lets the user change
     // it from there and remembers the pick. `overrides` replaces individual
-    // strings (handbook §8.7).
+    // strings (docs/guides/build-the-admin-frontend.md, "UI Language").
     i18n: { locale: 'en' },
 });
 

package/templates/src/services/http.ts.tpl

@@ -6,7 +6,7 @@
 import axios from 'axios';
 import { createAxiosHttpClient } from '@saasicat/ui-vue';
 
-const TOKEN_KEY = '__PROJECT_KEY__-admin-token';
+const TOKEN_KEY = '__APP_KEY__-admin-token';
 
 export const api = axios.create({ baseURL: '/api/v1' });
 api.interceptors.request.use((cfg) => {

package/templates/src/services/platform-loaders.ts.tpl

@@ -1,20 +1,16 @@
 // BootLoader + ManifestLoader built from the same endpoint constant that
 // `main.ts` passes to `createSuperAdminApp()` — endpoints live in exactly
-// one place (handbook §8.1).
+// one place (docs/guides/build-the-admin-frontend.md, "Platform Loaders").
 
 import { createPlatformLoaders, type SuperAdminEndpoints } from '@saasicat/ui-vue';
 import { platformHttp } from './http';
 
-// `projectKey` names the catalogue this admin administers — the same key your
-// backend configuration uses. The shell hands it to every platform resource,
-// so a catalogue page does not have to carry it as a prop.
 export const ADMIN_ENDPOINTS: SuperAdminEndpoints = {
     apiBase: '__API_BASE__',
-    projectKey: '__PROJECT_KEY__',
 };
 
 export const loaders = createPlatformLoaders({
     endpoints: ADMIN_ENDPOINTS,
     http: platformHttp,
-    storageKeyPrefix: '__PROJECT_KEY__:',
+    storageKeyPrefix: '__APP_KEY__:',
 });

package/templates/src/stores/manifest.ts.tpl

@@ -1,5 +1,6 @@
 // Manifest Pinia store — the router guard in `main.ts` awaits
-// `ensureLoaded()` before rendering admin routes (handbook §8.2).
+// `ensureLoaded()` before rendering admin routes
+// (docs/guides/build-the-admin-frontend.md, "Manifest Store").
 
 import { createManifestStore } from '@saasicat/ui-vue';
 import { loaders } from '../services/platform-loaders';

package/templates/vite.config.ts.tpl

@@ -1,17 +1,11 @@
 import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
-import { quasar } from '@quasar/vite-plugin';
 
 export default defineConfig({
     base: '/admin/',
     plugins: [
         vue(),
-        quasar({
-            // Absolute path — sass resolves plain relative paths against the
-            // importing file inside node_modules/quasar, not the project root.
-            sassVariables: fileURLToPath(new URL('./src/styles/theme.scss', import.meta.url)),
-        }),
     ],
     // Exactly one copy of each of these, always.
     //
@@ -22,17 +16,18 @@ export default defineConfig({
     // so two copies of the library do not share one, and the lookup silently
     // returns `undefined`.
     //
-    // The platform ships its pages as `.vue` SOURCE (decision E3), so their
-    // `import … from 'vue-router'` resolves relative to the platform package,
-    // while this app's own files resolve relative to here. Without dedupe the
-    // bundle ends up with both, and every consumer page that reads a route
-    // param throws `Cannot read properties of undefined (reading 'params')` —
-    // the shell renders, the content area is blank.
+    // The platform's pages are built (ADR 0011), and its chunks resolve
+    // `import … from 'vue-router'` relative to the platform package while this
+    // app's own files resolve relative to here. Without dedupe the bundle ends
+    // up with both, and every consumer page that reads a route param throws
+    // `Cannot read properties of undefined (reading 'params')` — the shell
+    // renders, the content area is blank. The reason survived the move from
+    // source to a build; only the first clause of it changed.
     //
     // The list is `@saasicat/ui-vue`'s peerDependencies: a peer is precisely a
     // dependency the host is expected to own exactly one of.
     resolve: {
-        dedupe: ['vue', 'vue-router', 'pinia', 'quasar'],
+        dedupe: ['vue', 'vue-router', 'pinia'],
     },
     server: {
         port: __DEV_PORT__,

package/templates/src/styles/theme.scss.tpl

@@ -1,30 +0,0 @@
-// Quasar theme variables — override your branding here.
-//
-// `$primary` is the ONE place your admin's brand colour is decided. SaaSiCat has
-// no palette of its own for it: `--sa-color-accent` reads Quasar's `--q-primary`,
-// which Quasar publishes from this variable. Change it and the hero, the buttons,
-// the focus ring, the tinted surfaces, Quasar's own components and the
-// tenant-facing pages all follow — there is no second switch.
-//
-// The four status colours are NOT read from here, and that is deliberate: each
-// SaaSiCat status tone is a family of six contrast-tuned values (solid, strong,
-// text, two tints, border), and a single Quasar variable cannot say which rung it
-// is — `$warning` is a bright graphic amber, while warning TEXT has to be dark
-// enough to read on it. They are set below to the values the platform's own roles
-// use, so Quasar's components and the admin pages agree out of the box. To change
-// them, override the `--sa-color-<tone>*` roles as a set.
-//
-// The defaults are SaaSiCat's own, so a freshly scaffolded admin looks like the
-// documentation until you decide otherwise.
-// One caveat if you pick a LIGHT brand: text on accent-filled controls is white
-// by default, and CSS cannot work out that white on a light amber is 2.15:1. Set
-// `--sa-color-fg-on-accent` to a dark colour in your own CSS if so — in both
-// themes, like any role.
-$primary: #3f6bff;
-$secondary: #475569;
-$accent: #0ea5e9;
-
-$positive: #047857;
-$negative: #dc2626;
-$warning: #f59e0b;
-$info: #2563eb;