@sempods/apps 0.8.0 → 0.9.0-dev.1

package/scripts/lib/apps.mjs

@@ -49,7 +49,8 @@ export function invalidId(id) {
   return undefined;
 }
 
-// Routes answer as <id>/<route>.html next to the app's own build output.
+// Routes answer as <id>/<route>.html next to the app's own build output; their
+// first segment must not be one of the app's own paths.
 const ROUTE_RESERVED = new Set([
   'assets',
   'callback',
@@ -57,6 +58,118 @@ const ROUTE_RESERVED = new Set([
   'index',
   'licenses',
 ]);
+// A route has at most this many segments, a resource pattern as well.
+const MAX_SEGMENTS = 4;
+// A placeholder of a resource pattern: one segment, named like a variable.
+const PLACEHOLDER = /^:[a-z][a-zA-Z0-9]{0,39}$/;
+
+/** Why `segment` cannot be a literal path segment, otherwise undefined. */
+function invalidSegment(segment) {
+  if (!ID_PATTERN.test(segment) || segment.endsWith('-'))
+    return 'each segment is lowercase: a letter, then up to 39 letters, digits or hyphens';
+  // build-site writes <segment>.html and <segment>/, which Windows refuses for
+  // device names.
+  if (WINDOWS_DEVICES.has(segment))
+    return `"${segment}" is a reserved device name on Windows`;
+  return undefined;
+}
+
+/** Why the segments of a route or pattern are not usable, otherwise undefined. */
+function invalidSegments(value, { placeholders }) {
+  const segments = value.split('/');
+  if (segments.length > MAX_SEGMENTS)
+    return `at most ${MAX_SEGMENTS} segments`;
+  if (ROUTE_RESERVED.has(segments[0]))
+    return `"${segments[0]}" is reserved by the site layout`;
+  const names = new Set();
+  for (const [i, segment] of segments.entries()) {
+    if (placeholders && PLACEHOLDER.test(segment)) {
+      // A pattern starting with a placeholder would also catch the callback,
+      // assets and every other path of the app.
+      if (i === 0) return 'the first segment is a word, not a placeholder';
+      if (names.has(segment)) return `${segment} is used twice`;
+      names.add(segment);
+      continue;
+    }
+    const reason = invalidSegment(segment);
+    if (reason)
+      return placeholders
+        ? `${reason}, or a placeholder such as :id`
+        : reason;
+  }
+  if (placeholders && names.size === 0)
+    return 'a pattern has a placeholder such as :id; list an address without one under routes';
+  return undefined;
+}
+
+/**
+ * Returns a reason when `route` cannot name a route, otherwise undefined. A
+ * route is a literal address below the app's path: lowercase segments
+ * separated by "/", for example "bought" or "tasks/add".
+ */
+export function invalidRoute(route) {
+  if (typeof route !== 'string' || route === '')
+    return 'a route is text, such as "bought" or "tasks/add"';
+  return invalidSegments(route, { placeholders: false });
+}
+
+/**
+ * Returns a reason when `pattern` cannot name a resource address, otherwise
+ * undefined. A resource pattern has literal segments and placeholders for one
+ * segment each, for example "tasks/:id" or "tasks/:id/postpone"; it starts
+ * with a literal segment, so it never catches the callback or another path
+ * of the app.
+ */
+function invalidResource(pattern) {
+  if (typeof pattern !== 'string' || pattern === '')
+    return 'a resource pattern is text, such as "tasks/:id"';
+  return invalidSegments(pattern, { placeholders: true });
+}
+
+/** A resource pattern with each placeholder segment replaced. */
+export const fillPlaceholders = (pattern, replacement) =>
+  pattern
+    .split('/')
+    .map((segment) => (segment.startsWith(':') ? replacement : segment))
+    .join('/');
+
+/** A pattern's shape: the same addresses whatever its placeholders are called. */
+const shape = (pattern) => fillPlaceholders(pattern, ':');
+
+/** Lists the problems of one app's `routes` and `resources`. */
+function addressProblems(app) {
+  const problems = [];
+  const list = (key, invalid) => {
+    const values = app[key];
+    if (values === undefined) return [];
+    if (!Array.isArray(values)) {
+      problems.push(`${app.id}: ${key} must be a list`);
+      return [];
+    }
+    const name = key === 'routes' ? 'route' : 'resource';
+    const valid = [];
+    values.forEach((value, i) => {
+      const reason = invalid(value);
+      if (reason)
+        problems.push(`${app.id}: ${name} ${JSON.stringify(value)}: ${reason}`);
+      else if (values.indexOf(value) !== i)
+        problems.push(`${app.id}: ${name} ${value} is listed twice`);
+      else valid.push(value);
+    });
+    return valid;
+  };
+  list('routes', invalidRoute);
+  const shapes = new Map();
+  for (const pattern of list('resources', invalidResource)) {
+    const other = shapes.get(shape(pattern));
+    if (other !== undefined && other !== pattern)
+      problems.push(
+        `${app.id}: resources ${other} and ${pattern} name the same addresses`,
+      );
+    shapes.set(shape(pattern), pattern);
+  }
+  return problems;
+}
 
 /**
  * Returns a reason when `description` cannot describe an app, otherwise
@@ -72,22 +185,6 @@ export function invalidDescription(description) {
   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.
@@ -195,16 +292,7 @@ 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`);
-      });
+    problems.push(...addressProblems(app));
   }
   return problems;
 }

package/scripts/lib/generate.mjs

@@ -3,7 +3,12 @@
 // apps.json, so tooling updates reach existing apps.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { AUTO, SITE_PROFILES, siteIdentity } from './apps.mjs';
+import {
+  AUTO,
+  fillPlaceholders,
+  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
@@ -34,28 +39,57 @@ const ${name}: BrowserRuntimeOptions = {
     clientId: ${json(clientId)},
     redirectUri: ${json(redirectUri)},
   },
-  ${RETURN_TO[Boolean(app.routes?.length)]},
+  returnTo: returnPath,
 };
 `;
 }
 
-// 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',
-};
+// One placeholder of a resource pattern matches one segment of these
+// characters, for example a base64url-encoded IRI.
+const PLACEHOLDER_SOURCE = '[A-Za-z0-9_-]+';
 
-const RETURN_PATH = `
-// The page sign-in returns to: the current route, otherwise the start page.
+/**
+ * The paths an app answers as a regular expression source, without the
+ * slashes of a literal: the start page, each route and each resource
+ * pattern, with or without a trailing slash, and an optional query when
+ * `query` is set. Route and pattern segments need no escaping but the slash.
+ */
+function addressSource(app, { query = false } = {}) {
+  const alternatives = [
+    ...(app.routes ?? []),
+    ...(app.resources ?? []).map((pattern) =>
+      fillPlaceholders(pattern, PLACEHOLDER_SOURCE),
+    ),
+  ].map((address) => address.replaceAll('/', '\\/'));
+  const rest = alternatives.length
+    ? `(?:(?:${alternatives.join('|')})\\/?)?`
+    : '';
+  return `^${app.path.replaceAll('/', '\\/')}${rest}${query ? '(?:\\?[^#]*)?' : ''}$`;
+}
+
+const RETURN_PATH = (app) => `
+// The addresses the app declares in apps.json: the start page, its routes and
+// its resource patterns.
+const ADDRESS = /${addressSource(app)}/;
+
+// The query parameters of the sign-in callback; the SDK refuses a return
+// address that carries one.
+const RESERVED = ['code', 'state', 'error', 'iss', 'response'];
+
+// The address sign-in returns to: the current one with its query when the app
+// declares it, otherwise the start page. Never the callback or another app.
+// The runtime calls it when each sign-in starts; the callback's parameters
+// are dropped, the rest of the query stays.
 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;
+  const { pathname, search } = location;
+  if (!ADDRESS.test(pathname)) return app.basePath;
+  const path =
+    pathname === app.basePath ? pathname : pathname.replace(/\\/$/, '');
+  const query = new URLSearchParams(search);
+  if (!RESERVED.some((key) => query.has(key))) return path + search;
+  for (const key of RESERVED) query.delete(key);
+  const rest = query.toString();
+  return rest ? path + '?' + rest : path;
 }
 `;
 
@@ -82,8 +116,9 @@ export const app = {
   basePath: ${json(app.path)},
   pwa: ${app.pwa},
   routes: ${json(app.routes ?? [])},
+  resources: ${json(app.resources ?? [])},
 } as const;
-${app.routes?.length ? RETURN_PATH : ''}
+${RETURN_PATH(app)}
 // Local development: a dynamic identity, local HTTP only.
 const local: BrowserRuntimeOptions = {
   identity: {
@@ -95,7 +130,7 @@ const local: BrowserRuntimeOptions = {
       return \`\${location.origin}${app.path}callback\`;
     },
   },
-  ${RETURN_TO[Boolean(app.routes?.length)]},
+  returnTo: returnPath,
   development: 'loopback-http',
 };
 ${published.map((name) => publishedProfile(name, site[name], app)).join('')}
@@ -124,12 +159,6 @@ export const runtimeOptions: BrowserRuntimeOptions =
 /** 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
     ? `{
     // The app registers its worker itself (src/main.tsx) and never takes over
@@ -155,10 +184,11 @@ ${app.description ? `      description: ${json(app.description)},\n` : ''}${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 page and routes. The
-      // callback, Pod and login pages always go to the network.
+      // Serve the cached shell only for this app's start page, routes and
+      // resource patterns, with any query. The callback, Pod and login pages
+      // always go to the network.
       navigateFallback: ${json(`${p}index.html`)},
-      navigateFallbackAllowlist: [/^${escaped}${routes}$/],
+      navigateFallbackAllowlist: [/${addressSource(app, { query: true })}/],
       skipWaiting: false,
       clientsClaim: false,
       cleanupOutdatedCaches: true,

package/scripts/lib/json.mjs

@@ -5,6 +5,12 @@ import { replaceFile } from './files.mjs';
 /** Two-space indentation and a final newline. */
 export const formatJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
 
+/** An object's entries sorted by key, as package managers keep dependency lists. */
+export const sortedKeys = (object) =>
+  Object.fromEntries(
+    Object.entries(object).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  );
+
 export function writeJson(path, value) {
   writeFileSync(path, formatJson(value));
 }

package/scripts/lib/kit.mjs

@@ -0,0 +1,81 @@
+// The UI kit and router the skeleton copied into apps in 0.8.0, until the
+// package @sempods/app-ui replaced them. They are the owner's files: a
+// migration never changes or removes them. It only tells which of them are
+// still as shipped, so moving the app to the package needs no merge there,
+// and which the owner changed, which stay the app's own until they replace
+// them deliberately.
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { readText } from './files.mjs';
+
+// SHA-256 of each file as 0.8.0-dev.1 and 0.8.0 shipped it, with LF line
+// endings.
+const SHIPPED = {
+  'src/routes.ts': [
+    '50693779a9ec1a73ab6210445cae1ab9563be105e94d79417772fe78a64d43c9',
+  ],
+  'src/routes.test.ts': [
+    'cb92fec8d23daea5587394960f535445d7da156c0ab4346286ddce1375cc42c9',
+  ],
+  'src/ui/Composer.tsx': [
+    'dcf6d28da59802da17421d04ef120e29863520790ae8f51ffa58e6221a7da89e',
+  ],
+  'src/ui/ContextSwitch.tsx': [
+    '07c584db1dc69f0d4c42ea77691a67687f8deab6d93833fec8b3d9f09878fc6a',
+    '953d1f775d0575360251bb8d41e07736912de384d22c2d9fc7ff733959d7db51',
+  ],
+  'src/ui/Dialog.tsx': [
+    'b9c01053804e13b6745299d8c7f79e9ec91bf2e75cd9541ac1a9f0c088e66061',
+    'b30a55e4b808f7e1dc2998c2f0df5e1a9a6aa16d69be7bcf5a55f579fb7ec873',
+  ],
+  'src/ui/Menu.tsx': [
+    '685b4f6ebe9c2ed447dd54e3b80c005a6cf7e7466df61a14f666d53988728fe6',
+  ],
+  'src/ui/Tabs.tsx': [
+    'c2da6564da4a229802acf96b00d6c235d0fa0b0f53e407e63466cd347db10647',
+  ],
+  'src/ui/dismiss.ts': [
+    'd5fa5a7589f9b7661c531471834e7facca784d466af5e81f2e5dfa70f388dda9',
+  ],
+  'src/ui/icons.tsx': [
+    'bf2d7f15d0c6455e15d561515e7a594becdd9f5b364f5e3aaa477e4736bbb6ec',
+  ],
+  'src/ui/ui.css': [
+    '43603c18c03dde5e731814989c76c5575e330da5f06d1db32c1cc5566c22cd3c',
+    '10fd3f736ed82a96a9727d53ec27722b8d80682e42d9a5f8f66119a35d35bd34',
+  ],
+};
+
+const sha256 = (text) =>
+  createHash('sha256').update(text.replaceAll('\r\n', '\n')).digest('hex');
+
+/**
+ * The copied kit files an app still has: `unchanged` as shipped, `changed`
+ * by the owner. Undefined when the app has none of them.
+ */
+export function copiedKit(appDir) {
+  const unchanged = [];
+  const changed = [];
+  for (const [file, hashes] of Object.entries(SHIPPED)) {
+    const text = readText(join(appDir, file));
+    if (text === null) continue;
+    (hashes.includes(sha256(text)) ? unchanged : changed).push(file);
+  }
+  return unchanged.length + changed.length > 0
+    ? { unchanged, changed }
+    : undefined;
+}
+
+/** The migration's note for one app that still has the copied kit. */
+export function kitNote(id, kit) {
+  const list = (files) => files.map((file) => `apps/${id}/${file}`).join(', ');
+  return [
+    `apps/${id} still has the UI kit and router copied in 0.8.0; it keeps working, nothing was changed. Move it to @sempods/app-ui as the 0.9.0 upgrade notes in the tooling's CHANGELOG.md describe.`,
+    kit.unchanged.length > 0 &&
+      `As shipped, to replace with the package: ${list(kit.unchanged)}.`,
+    kit.changed.length > 0 &&
+      `Changed in this app, the app's own until the owner replaces them: ${list(kit.changed)}.`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+}

package/scripts/lib/merge.mjs

@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { sortedKeys } from './json.mjs';
 
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 
@@ -125,13 +126,21 @@ export function mergeManifest(
       );
     }
     // The SDK sits where the release puts it; elsewhere only if the release
-    // declares it nowhere in this manifest.
+    // declares it nowhere in this manifest. A package of it that this
+    // manifest lacks waits for sdk-update: it may not exist at this version.
     if (field.endsWith('ependencies'))
       for (const key of sdk) {
         const declared = DEPENDENCY_FIELDS.some(
           (f) => theirs[f]?.[key] !== undefined,
         );
-        if (
+        const ownDeclared = DEPENDENCY_FIELDS.some(
+          (f) => ours[f]?.[key] !== undefined,
+        );
+        if (theirs[field]?.[key] !== undefined && !ownDeclared)
+          notes.push(
+            `${where} ${field}.${key}: not added; pnpm run sdk-update <version> adds it with the SDK`,
+          );
+        else if (
           declared
             ? theirs[field]?.[key] !== undefined
             : target[key] !== undefined
@@ -145,13 +154,7 @@ export function mergeManifest(
         }
       }
     // Package managers keep dependency lists sorted; scripts and the rest keep their order.
-    const ordered = field.endsWith('ependencies')
-      ? Object.fromEntries(
-          Object.entries(target).sort(([a], [b]) =>
-            a < b ? -1 : a > b ? 1 : 0,
-          ),
-        )
-      : target;
+    const ordered = field.endsWith('ependencies') ? sortedKeys(target) : target;
     if (Object.keys(ordered).length) result[field] = ordered;
     else delete result[field];
   }

package/scripts/lib/sdk.mjs

@@ -1,5 +1,13 @@
-// The SDK packages every app uses, and how their exact versions compare.
-export const SDK = ['@sempods/app-sdk', '@sempods/client-sdk'];
+// The SDK packages, released together at one version, and how their exact
+// versions compare. The root declares all of them; every app declares the
+// first two and the UI kit when it uses it.
+export const SDK = ['@sempods/app-sdk', '@sempods/client-sdk', '@sempods/app-ui'];
+export const UI_KIT = '@sempods/app-ui';
+export const APP_SDK = SDK.filter((name) => name !== UI_KIT);
+
+/** The SDK packages an app declares: the UI kit only when it uses it. */
+export const appSdk = (dependencies) =>
+  dependencies?.[UI_KIT] === undefined ? APP_SDK : SDK;
 
 /** The app-author reference the installed SDK ships, relative to the root. */
 export const REFERENCE = 'node_modules/@sempods/app-sdk/docs/ai-app-builder.md';

package/scripts/lib/themes.mjs

@@ -1,6 +1,7 @@
 // The skeleton's themes: one CSS file per theme in src/themes/, which sets the
-// --sempods-* tokens in light and dark mode. An app imports one of them in its
-// src/main.tsx; its icon takes that theme's accent.
+// palette roles of the UI kit's theme contract (--primary, --background, …)
+// in light and dark mode. An app imports one of them in its src/index.css;
+// its icon takes that theme's primary colour.
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ifPresent } from './json.mjs';
@@ -8,7 +9,12 @@ import { SKELETON } from './paths.mjs';
 
 export const DEFAULT_THEME = 'calm';
 const THEMES_DIR = join('src', 'themes');
-const IMPORT = /^import '\.\/themes\/([a-z-]+)\.css';$/m;
+// The import line in src/index.css; apps from before the UI kit import their
+// theme in src/main.tsx.
+const IMPORTS = [
+  ['index.css', /^@import '\.\/themes\/([a-z-]+)\.css';$/m],
+  ['main.tsx', /^import '\.\/themes\/([a-z-]+)\.css';$/m],
+];
 
 /** The theme names the skeleton ships, the default first. */
 export function themeNames(skeleton = SKELETON) {
@@ -19,37 +25,57 @@ export function themeNames(skeleton = SKELETON) {
   return [DEFAULT_THEME, ...names.filter((name) => name !== DEFAULT_THEME)];
 }
 
-/** A token's light and dark colour, from `--name: light-dark(#light, #dark)`. */
-export function tokenColours(css, token) {
+/**
+ * A custom property's light and dark colour, from
+ * `--name: light-dark(#light, #dark)`; undefined when the theme lacks it.
+ */
+export function tokenColours(css, property) {
   const match = css.match(
     new RegExp(
-      `--sempods-${token}:\\s*light-dark\\((#[0-9a-f]{6}),\\s*(#[0-9a-f]{6})\\)`,
+      `(?:^|[\\s;{])--${property}:\\s*light-dark\\((#[0-9a-f]{6}),\\s*(#[0-9a-f]{6})\\)`,
       'i',
     ),
   );
-  if (!match) throw new Error(`the theme sets no --sempods-${token}`);
-  return { light: match[1].toLowerCase(), dark: match[2].toLowerCase() };
+  return match
+    ? { light: match[1].toLowerCase(), dark: match[2].toLowerCase() }
+    : undefined;
 }
 
 /**
- * The icon's colours for a theme file: the accent as the square and the text
- * on the accent as the letter, in light and dark mode.
+ * The icon's colours for a theme file: the primary role as the square and the
+ * text on it as the letter, in light and dark mode. A theme from before the UI
+ * kit gives its --sempods-accent tokens instead.
  */
 export function iconColours(css) {
-  const accent = tokenColours(css, 'accent');
-  const on = tokenColours(css, 'on-accent');
+  const pair = (background, letter) => {
+    const square = tokenColours(css, background);
+    const text = tokenColours(css, letter);
+    return square && text ? { square, text } : undefined;
+  };
+  const found =
+    pair('primary', 'primary-foreground') ??
+    pair('sempods-accent', 'sempods-on-accent');
+  if (!found)
+    throw new Error(
+      'the theme sets no --primary and --primary-foreground in light-dark(#light, #dark)',
+    );
+  const { square, text } = found;
   return {
-    light: { background: accent.light, letter: on.light },
-    dark: { background: accent.dark, letter: on.dark },
+    light: { background: square.light, letter: text.light },
+    dark: { background: square.dark, letter: text.dark },
   };
 }
 
-/** The theme an app imports in src/main.tsx, if it imports one of these. */
+/** The theme an app imports, if it imports one of these. */
 export function appTheme(appDir) {
-  const main = ifPresent(() =>
-    readFileSync(join(appDir, 'src', 'main.tsx'), 'utf8'),
-  );
-  return main?.match(IMPORT)?.[1];
+  for (const [file, pattern] of IMPORTS) {
+    const source = ifPresent(() =>
+      readFileSync(join(appDir, 'src', file), 'utf8'),
+    );
+    const name = source?.match(pattern)?.[1];
+    if (name) return name;
+  }
+  return undefined;
 }
 
 /** The CSS of a theme file in an app or in the skeleton. */

package/scripts/migrate.mjs

@@ -32,6 +32,7 @@ import {
   replaceFile,
 } from './lib/files.mjs';
 import { GENERATED_FILES } from './lib/generate.mjs';
+import { copiedKit, kitNote } from './lib/kit.mjs';
 import {
   adoptPageHead,
   adoptPageTitle,
@@ -511,7 +512,8 @@ export function migrate(
 
 /**
  * The apps' part of a migration: files a release moves where that is
- * unambiguous, then the generated configuration.
+ * unambiguous, then the generated configuration. App code that needs a
+ * decision, such as a copied UI kit, stays as it is with a note.
  */
 function updateApps(root, report) {
   for (const app of appsOf(root)) {
@@ -519,6 +521,8 @@ function updateApps(root, report) {
     if (!existsSync(dir)) continue;
     const changed = [...adoptPageTitle(dir, app), ...adoptPageHead(dir, app)];
     report.updated.push(...new Set(changed));
+    const kit = copiedKit(dir);
+    if (kit) report.notes.push(kitNote(app.id, kit));
   }
   report.regenerated = regenerate(root);
 }
@@ -531,6 +535,7 @@ export function formatMigration(report) {
       `The shared files already match ${PACKAGE} ${report.to}; nothing to migrate.`,
       ...list('Updated', report.updated),
       ...list('Regenerated', report.regenerated),
+      ...list('Notes', report.notes),
     ].join('\n');
   const lines = [
     `Migration from ${PACKAGE} ${report.from} to ${report.to}${report.unfinished ? ' is open' : ' is complete'}.`,

package/scripts/new-app.mjs

@@ -33,7 +33,7 @@ import {
   themeCss,
   themeNames,
 } from './lib/themes.mjs';
-import { readJson, writeJson } from './lib/json.mjs';
+import { readJson, sortedKeys, writeJson } from './lib/json.mjs';
 import { repositoryRoot, SKELETON } from './lib/paths.mjs';
 import { INSTALL, pnpm, scriptArgs } from './lib/pnpm.mjs';
 import { EXACT_VERSION, SDK } from './lib/sdk.mjs';
@@ -130,12 +130,7 @@ export function createApp(
     writeAppIcons(appDir, app.title, iconColours(themeCss(appDir, theme)));
     const pkgFile = join(appDir, 'package.json');
     const pkg = readJson(pkgFile);
-    // Package managers keep dependency lists sorted.
-    pkg.dependencies = Object.fromEntries(
-      Object.entries({ ...pkg.dependencies, ...sdk }).sort(([a], [b]) =>
-        a < b ? -1 : a > b ? 1 : 0,
-      ),
-    );
+    pkg.dependencies = sortedKeys({ ...pkg.dependencies, ...sdk });
     writeJson(pkgFile, pkg);
     writeGenerated(appDir, app, manifest.site);
     writeApps(root, { ...manifest, apps: [...manifest.apps, app] });