@sempods/apps 0.7.1 → 0.8.0

package/instructions/setup.md

@@ -20,29 +20,42 @@ file or anything under `node_modules`.
 ## Choose the first interaction
 
 Use the request and recorded answers. Ask only for missing information needed
-for the first useful interaction. Use the requested UI language, or the owner's
-language when supported (`de` or `en`); otherwise use `en` and tell the owner.
-Choose a short app ID from the idea, such as `konsum`, and tell the owner; the
-generator validates allowed IDs and reserved names. Record choices and
-progress as they become known.
-
-A name, GitHub review identity and the version PR choice are not needed to
-try an app. Do not ask for them before the first local interaction. A missing
-Pod also allows UI work; record Pod testing as pending. Before accessing a Pod,
-use the owner's full test Pod URL and a dedicated context, with synthetic data.
+for the first useful interaction. Before generating the app, follow the
+[planning steps](app-workflow.md#start-a-new-app-with-a-short-design-conversation):
+purpose, personal or shared data, existing records to reuse, and where reads,
+new records and edits belong. Propose fitting visual defaults. Apps follow the
+browser's language, German or English (otherwise English), and carry their
+texts in both; record the owner's language for writing them. Fix one language
+(`--language de` or `en`) only when the owner asks for it. If the owner's
+language is neither, the UI still shows English and German only: tell the
+owner. Choose a short app ID from the idea, such as `konsum`, and tell the
+owner; the generator validates allowed IDs and reserved names. Record choices
+and progress as they become known.
+
+The owner's name, a GitHub review identity and the version PR choice are not
+needed to try an app. Do not ask for them before the first local interaction.
+If existing data matters, offer the workflow's
+[optional MCP inspection](app-workflow.md#optionally-inspect-existing-data-through-mcp)
+within the owner's agreed read scope. It is not a setup requirement or an
+app sign-in. Without an app connection to a Pod only the sign-in screen can
+be seen; record Pod testing as pending. For app trials, use the owner's full
+test Pod URL and dedicated contexts (one per context the app's shape uses),
+with synthetic data.
 
 ## Create the first app and open it
 
 From the repository root, after the bootstrap in `INIT.md`:
 
 ```sh
-pnpm run new-app konsum --title "Einkaufsliste" --language de
+pnpm run new-app konsum --title "Einkaufsliste" \
+  --description "Was im Haushalt fehlt, für alle." --theme warm
 pnpm run dev konsum
 ```
 
-Replace the example ID, title and language with the recorded choices. PWA is on
-by default; `--no-pwa` is available if the owner chooses it when creating an
-app. The dev server is long-running: keep it in a separate terminal/session.
+Replace the example ID, title, description and theme with the recorded
+choices. PWA is on by default; `--no-pwa` is available if the owner chooses it
+when creating an app. The dev server is long-running: keep it in a separate
+terminal/session.
 Open the exact URL it reports; `apps.json` records the assigned `devPort` and
 `path`. Do not switch hostnames or ports during sign-in.
 
@@ -54,15 +67,15 @@ manifest or choose another ID silently to make setup pass. A failed command
 leaves setup in progress; diagnose it before proceeding.
 
 Continue with the [app workflow](app-workflow.md) for the first useful
-interaction. Once the owner can try the screen, ask once whether they have a
-test Pod for trying it with data, unless the setup record answers that. If so,
-let the user sign in in the browser and select their test context; otherwise
-record Pod testing as pending. Run `pnpm run check` in another terminal and
-report its result.
+interaction. Once the app starts, ask once whether they have a test Pod for
+trying it with data, unless the setup record answers that. If so, let the user
+sign in in the browser and select their test contexts; otherwise record Pod
+testing as pending. Run `pnpm run check` in another terminal and report its
+result.
 
 ## Choose repository preferences (optional)
 
-After the owner can try the first interaction, offer to set a GitHub review
+After the owner has seen the first interaction, offer to set a GitHub review
 owner and to enable version PRs for the SDK and the tooling. Use choices
 already given. If the owner has not chosen these preferences, leave them
 deferred; do not wait for an answer to finish local setup. If the owner wants
@@ -99,9 +112,11 @@ a token; never ask for one.
 ## Finish setup
 
 Run `pnpm run check` again. Mark setup **done** only when the chosen app starts
-at its assigned URL, its first useful interaction is available and local checks
-pass. Deferred review identity or version PRs do not block completion;
-keep their status visible in the setup record. Record command results and
+at its assigned URL, its first useful interaction is available, local checks
+pass and the owner has seen the screen and given a verdict (or, without a test
+Pod, the sign-in screen, with the rest recorded as pending). Deferred review
+identity or version PRs do not block completion; keep their status visible in
+the setup record. Record command results and
 remaining gaps separately: no Pod, incomplete login or untested installed-PWA
 behavior are not successful interoperability evidence. If setup is already
 done, reopen the recorded app and follow its notes; do not recreate it.

package/instructions/visual-check.md

@@ -0,0 +1,43 @@
+# Check a screen visually
+
+The owner judges an app by what they see. Before reporting a screen as done,
+look at it the way they will and fix what fails; the [app workflow](app-workflow.md)
+says when.
+
+## Look at the real states
+
+Open the app in a browser you can control, signed in to the test context, and
+take screenshots:
+
+- at 375px wide and at desktop width;
+- in light and in dark mode;
+- with real states: the empty list, a few items, an open item or dialog, and
+  a notice (for example after a refused change or with read-only access).
+
+Without a browser tool, or without a test context, say which states you could
+not see; do not describe them as checked. Without a Pod, only the sign-in
+screen is visible.
+
+## Checklist
+
+- Spacing and alignment are consistent; nothing touches the screen edge.
+- The hierarchy is clear: one primary action per screen or dialog, other
+  actions read as text.
+- Every control has a 44px touch target; checkboxes are wrapped in their
+  label.
+- Nothing scrolls sideways at 375px.
+- The empty state says in one friendly line what to do next.
+- The app does not repeat a message an SDK component already shows.
+- The app's icon and name are present in the header and on the sign-in
+  screen.
+- Text and controls keep their contrast in both modes; colours come from the
+  app's theme.
+- A bar fixed at the bottom is not covered and leaves room for the content
+  above it.
+
+## Ask the owner
+
+Fix what fails, then show the owner the 375px screenshot of the main state and
+ask for a short verdict before moving on. Record the states checked, the
+widths and modes, and the owner's verdict under Tested in the app's
+`NOTES.md`; design choices made on the way go under Design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sempods/apps",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Tooling for a sempods apps repository: create, check, update and publish several sempods apps with one shared SDK version.",
   "keywords": [
     "sempods",
@@ -55,8 +55,8 @@
     "unified-engine": "11.2.2"
   },
   "peerDependencies": {
-    "@sempods/app-sdk": "^0.5.0",
-    "@sempods/client-sdk": "^0.5.0"
+    "@sempods/app-sdk": "^0.6.0",
+    "@sempods/client-sdk": "^0.6.0"
   },
   "scripts": {}
 }

package/scripts/build-site.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Builds every app with a published profile into its path of one static site
-// folder, site-dist/, and writes the overview and the host's routing files.
+// folder, site-dist/, with a page for each route, and writes the overview and
+// the host's routing files.
 // apps/<id>/dist keeps the app's local build.
 // Usage: pnpm run build-site [--profile production|preview]
 //        (or SEMPODS_SITE_PROFILE=<profile> in the host's environment)
@@ -15,7 +16,7 @@ import {
 import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { readApps, SITE_PROFILES, siteIdentity } from './lib/apps.mjs';
+import { AUTO, readApps, SITE_PROFILES, siteIdentity } from './lib/apps.mjs';
 import { PROFILE_MODES, staleGenerated } from './lib/generate.mjs';
 import { ifPresent, writeJson } from './lib/json.mjs';
 import { renderNotFound, renderOverview } from './lib/overview.mjs';
@@ -79,7 +80,9 @@ function overviewEntry(app, outDir) {
   const entry = {
     id: app.id,
     title: app.title,
-    language: app.language,
+    ...(app.description ? { description: app.description } : {}),
+    // An app that follows the browser has no one language to announce.
+    ...(app.language === AUTO ? {} : { language: app.language }),
     href: app.path,
   };
   if (existsSync(join(outDir, 'icon-192.png')))
@@ -143,6 +146,15 @@ export function buildSite(root, { profile = 'production', build = appBuild } = {
     // so without a redirect.
     const callback = new URL(redirectUri).pathname;
     writeFileSync(join(out, `${callback.slice(1)}.html`), html);
+    // Each route answers the same way from a copy of the page, so the host
+    // needs no rewrite and unknown paths still show the not-found page.
+    for (const route of app.routes ?? []) {
+      if (['', '.html'].some((ext) => existsSync(join(appOut, route + ext))))
+        throw new Error(
+          `apps/${app.id}: the route ${route} collides with ${route} in the app's build output; rename one of them.`,
+        );
+      writeFileSync(join(appOut, `${route}.html`), html);
+    }
 
     entries.push(overviewEntry(app, appOut));
   }

package/scripts/check.mjs

@@ -21,6 +21,7 @@ import { parseArgs } from 'node:util';
 import semver from 'semver';
 import { readApps } from './lib/apps.mjs';
 import { staleGenerated } from './lib/generate.mjs';
+import { pageProblems } from './lib/page.mjs';
 import { migrationState } from './migrate.mjs';
 import { readJson, writeJson } from './lib/json.mjs';
 import { repositoryRoot, TOOLING } from './lib/paths.mjs';
@@ -120,6 +121,7 @@ export function staticProblems(root, { tooling = TOOLING } = {}) {
       problems.push(
         `apps/${app.id}/${file} does not match apps.json; regenerate it instead of editing`,
       );
+    problems.push(...pageProblems(dir, app.id));
     const pkg = readJson(join(dir, 'package.json'));
     for (const sdk of SDK)
       expect(`apps/${app.id}`, sdk, pkg.dependencies?.[sdk]);
@@ -156,7 +158,7 @@ export function staticProblems(root, { tooling = TOOLING } = {}) {
       !semver.satisfies(version, range, { includePrerelease: true })
     )
       problems.push(
-        `${sdk} ${version} is outside the range ${toolingManifest.name} ${toolingManifest.version} supports (${range}); update ${toolingManifest.name} or use a supported SDK version`,
+        `${sdk} ${version} is outside the range ${toolingManifest.name} ${toolingManifest.version} supports (${range}); move the SDK with pnpm run sdk-update <version> in that range, or update ${toolingManifest.name}`,
       );
   }
   // The app-author reference ships inside the installed SDK.

package/scripts/icon.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Draws an app's icon again: the monogram of its title in apps.json, in the
+// accent of the theme its src/main.tsx imports, for example after a rename or
+// a theme change. It replaces public/favicon.svg, icon-192.png and
+// icon-512.png. Usage: pnpm run icon <id>
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readApps } from './lib/apps.mjs';
+import { writeAppIcons } from './lib/icon.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { scriptArgs } from './lib/pnpm.mjs';
+import { appTheme, iconColours, themeCss } from './lib/themes.mjs';
+
+/** Writes the icons of app `id`; returns them as apps/<id>/<file>. */
+export function drawIcon(root, id) {
+  const app = readApps(root).apps.find((entry) => entry.id === id);
+  if (!app) throw new Error(`apps.json lists no app "${id}"`);
+  const dir = join(root, 'apps', id);
+  if (!existsSync(dir)) throw new Error(`apps/${id} is missing`);
+  const theme = appTheme(dir);
+  if (!theme || !existsSync(join(dir, 'src', 'themes', `${theme}.css`)))
+    throw new Error(
+      `apps/${id}/src/main.tsx imports no theme from src/themes/; import one as the skeleton does, then run this again`,
+    );
+  return writeAppIcons(dir, app.title, iconColours(themeCss(dir, theme))).map(
+    (file) => `apps/${id}/${file}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  const [id, ...rest] = scriptArgs();
+  if (!id || rest.length > 0) {
+    console.error('Usage: pnpm run icon <id>');
+    process.exit(2);
+  }
+  try {
+    const files = drawIcon(repositoryRoot(), id);
+    console.log(`Drew:\n${files.map((file) => `  ${file}`).join('\n')}`);
+  } catch (error) {
+    console.error(`icon: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/lib/apps.mjs

@@ -5,7 +5,10 @@ import { readJson, writeJson } from './json.mjs';
 
 export const SCHEMA_VERSION = 1;
 export const FIRST_DEV_PORT = 5174;
+// The UI languages of the SDK; "auto" follows the browser among them.
 export const LANGUAGES = ['en', 'de'];
+export const AUTO = 'auto';
+export const APP_LANGUAGES = [AUTO, ...LANGUAGES];
 // Where the site is published (configure-site): one origin per profile and the
 // host whose routing build-site writes for.
 export const SITE_PROFILES = ['production', 'preview'];
@@ -46,6 +49,45 @@ export function invalidId(id) {
   return undefined;
 }
 
+// Routes answer as <id>/<route>.html next to the app's own build output.
+const ROUTE_RESERVED = new Set([
+  'assets',
+  'callback',
+  'did',
+  'index',
+  'licenses',
+]);
+
+/**
+ * Returns a reason when `description` cannot describe an app, otherwise
+ * undefined. It is optional: one short sentence for the sign-in screen, the
+ * installed app and the overview.
+ */
+export function invalidDescription(description) {
+  if (description === undefined) return undefined;
+  if (typeof description !== 'string' || description.trim() === '')
+    return 'description must be text';
+  if (description.trim().length > 120)
+    return 'description must be one short sentence, at most 120 characters';
+  return undefined;
+}
+
+/** Returns a reason when `route` cannot name a route, otherwise undefined. */
+export function invalidRoute(route) {
+  if (
+    typeof route !== 'string' ||
+    !ID_PATTERN.test(route) ||
+    route.endsWith('-')
+  )
+    return 'a route is one lowercase segment: a letter, then up to 39 letters, digits or hyphens';
+  if (ROUTE_RESERVED.has(route))
+    return `"${route}" is reserved by the site layout`;
+  // build-site writes <route>.html, which Windows refuses for device names.
+  if (WINDOWS_DEVICES.has(route))
+    return `"${route}" is a reserved device name on Windows`;
+  return undefined;
+}
+
 /**
  * Returns a reason when `value` is not an origin as apps.json records it,
  * otherwise undefined. configure-site also lets the SDK check the identity.
@@ -134,9 +176,11 @@ export function validateApps(manifest) {
     ids.add(app.id);
     if (typeof app.title !== 'string' || app.title.trim() === '')
       problems.push(`${app.id}: title must be text`);
-    if (!LANGUAGES.includes(app.language))
+    const description = invalidDescription(app.description);
+    if (description) problems.push(`${app.id}: ${description}`);
+    if (!APP_LANGUAGES.includes(app.language))
       problems.push(
-        `${app.id}: language must be one of ${LANGUAGES.join(', ')}`,
+        `${app.id}: language must be one of ${APP_LANGUAGES.join(', ')}`,
       );
     if (app.path !== `/${app.id}/`)
       problems.push(`${app.id}: path must be "/${app.id}/"`);
@@ -151,6 +195,16 @@ export function validateApps(manifest) {
     ports.add(app.devPort);
     if (typeof app.pwa !== 'boolean')
       problems.push(`${app.id}: pwa must be true or false`);
+    if (app.routes !== undefined && !Array.isArray(app.routes))
+      problems.push(`${app.id}: routes must be a list`);
+    else if (app.routes)
+      app.routes.forEach((route, i) => {
+        const reason = invalidRoute(route);
+        if (reason)
+          problems.push(`${app.id}: route ${JSON.stringify(route)}: ${reason}`);
+        else if (app.routes.indexOf(route) !== i)
+          problems.push(`${app.id}: route ${route} is listed twice`);
+      });
   }
   return problems;
 }

package/scripts/lib/generate.mjs

@@ -3,7 +3,8 @@
 // apps.json, so tooling updates reach existing apps.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { SITE_PROFILES, siteIdentity } from './apps.mjs';
+import { AUTO, SITE_PROFILES, siteIdentity } from './apps.mjs';
+import { escapeHtml } from './html.mjs';
 
 const HEADER = `// Generated from apps.json by @sempods/apps. Do not edit: change apps.json
 // and run pnpm run regenerate.`;
@@ -33,11 +34,31 @@ const ${name}: BrowserRuntimeOptions = {
     clientId: ${json(clientId)},
     redirectUri: ${json(redirectUri)},
   },
-  returnTo: app.basePath,
+  ${RETURN_TO[Boolean(app.routes?.length)]},
 };
 `;
 }
 
+// With routes, sign-in returns to the route it started from: the runtime
+// calls returnPath when each sign-in starts.
+const RETURN_TO = {
+  false: 'returnTo: app.basePath',
+  true: 'returnTo: returnPath',
+};
+
+const RETURN_PATH = `
+// The page sign-in returns to: the current route, otherwise the start page.
+function returnPath(): string {
+  const routes: readonly string[] = app.routes;
+  const route = location.pathname
+    .slice(app.basePath.length)
+    .replace(/\\/$/, '');
+  return location.pathname.startsWith(app.basePath) && routes.includes(route)
+    ? app.basePath + route
+    : app.basePath;
+}
+`;
+
 /**
  * Runtime settings per profile: local development with a dynamic identity on
  * loopback HTTP, and the did:web identities of the configured site origins.
@@ -47,17 +68,22 @@ export function runtimeSource(app, site) {
   const modes = SITE_PROFILES.map(
     (name) => `  ${json(PROFILE_MODES[name])}: ${json(name)},`,
   ).join('\n');
+  // "auto" stays a literal: the app resolves it from the browser.
+  const language =
+    app.language === AUTO ? json(AUTO) : `${json(app.language)} as Language`;
   return `${HEADER}
-import type { BrowserRuntimeOptions, Language } from '@sempods/app-sdk';
+import type { BrowserRuntimeOptions${app.language === AUTO ? '' : ', Language'} } from '@sempods/app-sdk';
 
 export const app = {
   id: ${json(app.id)},
   title: ${json(app.title)},
-  language: ${json(app.language)} as Language,
+  description: ${json(app.description ?? null)},
+  language: ${language},
   basePath: ${json(app.path)},
   pwa: ${app.pwa},
+  routes: ${json(app.routes ?? [])},
 } as const;
-
+${app.routes?.length ? RETURN_PATH : ''}
 // Local development: a dynamic identity, local HTTP only.
 const local: BrowserRuntimeOptions = {
   identity: {
@@ -69,7 +95,7 @@ const local: BrowserRuntimeOptions = {
       return \`\${location.origin}${app.path}callback\`;
     },
   },
-  returnTo: app.basePath,
+  ${RETURN_TO[Boolean(app.routes?.length)]},
   development: 'loopback-http',
 };
 ${published.map((name) => publishedProfile(name, site[name], app)).join('')}
@@ -95,9 +121,14 @@ export const runtimeOptions: BrowserRuntimeOptions =
 `;
 }
 
-/** Vite base path, development server and PWA settings for this app's path. */
+/** Vite base path, development server, page title and PWA settings. */
 export function viteSource(app) {
   const p = app.path;
+  // The start page and every route, with or without a trailing slash, as the
+  // app's router accepts them; route names need no escaping.
+  const routes = app.routes?.length
+    ? `((${app.routes.join('|')})\\/?)?`
+    : '';
   const escaped = p.replaceAll('/', '\\/');
   const pwa = app.pwa
     ? `{
@@ -109,12 +140,12 @@ export function viteSource(app) {
       id: ${json(p)},
       name: ${json(app.title)},
       short_name: ${json(app.title)},
-      lang: ${json(app.language)},
-      start_url: ${json(p)},
+${app.description ? `      description: ${json(app.description)},\n` : ''}${app.language === AUTO ? '' : `      lang: ${json(app.language)},
+`}      start_url: ${json(p)},
       scope: ${json(p)},
       display: 'standalone',
-      background_color: '#f6faf9',
-      theme_color: '#176354',
+      background_color: '#ffffff',
+      theme_color: '#ffffff',
       icons: [
         { src: ${json(`${p}icon-192.png`)}, sizes: '192x192', type: 'image/png' },
         { src: ${json(`${p}icon-512.png`)}, sizes: '512x512', type: 'image/png' },
@@ -124,10 +155,10 @@ export function viteSource(app) {
       // Precache the built shell only; nothing is cached at runtime.
       globPatterns: ['**/*.{js,css,html,png,svg,webmanifest}'],
       runtimeCaching: [],
-      // Serve the cached shell only for this app's start route. The callback,
-      // Pod and login pages always go to the network.
+      // Serve the cached shell only for this app's start page and routes. The
+      // callback, Pod and login pages always go to the network.
       navigateFallback: ${json(`${p}index.html`)},
-      navigateFallbackAllowlist: [/^${escaped}$/],
+      navigateFallbackAllowlist: [/^${escaped}${routes}$/],
       skipWaiting: false,
       clientsClaim: false,
       cleanupOutdatedCaches: true,
@@ -135,10 +166,20 @@ export function viteSource(app) {
   }`
     : 'null';
   return `${HEADER}
+import type { Plugin } from 'vite';
 import type { VitePWAOptions } from 'vite-plugin-pwa';
 
 export const base = ${json(p)};
 
+// The page title from apps.json, added to the head of every page Vite serves
+// or builds; index.html has no <title> of its own.
+export const pageTitle: Plugin = {
+  name: 'sempods-page-title',
+  transformIndexHtml: () => [
+    { tag: 'title', children: ${json(escapeHtml(app.title))}, injectTo: 'head' },
+  ],
+};
+
 export const server = {
   host: '127.0.0.1',
   port: ${app.devPort},