@sempods/apps 0.0.0-stage → 0.7.0-dev.1

package/scripts/lib/files.mjs

@@ -0,0 +1,57 @@
+// File operations the migration relies on: reading a file that may be absent
+// or a directory, writing in one step, removing with emptied directories.
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+// What is at a path, or undefined when nothing is, also below a file.
+function entry(path, stat = statSync) {
+  try {
+    return stat(path, { throwIfNoEntry: false });
+  } catch (error) {
+    if (error.code === 'ENOTDIR') return undefined;
+    throw error;
+  }
+}
+
+export const isFile = (path) => entry(path)?.isFile() ?? false;
+
+export const isDirectory = (path) => entry(path)?.isDirectory() ?? false;
+
+export const isSymlink = (path) =>
+  entry(path, lstatSync)?.isSymbolicLink() ?? false;
+
+/** A file's text, or null when there is no file at the path. */
+export const readText = (path) =>
+  isFile(path) ? readFileSync(path, 'utf8') : null;
+
+/** Writes a file in one step: the old or the complete new content remains. */
+export function replaceFile(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  // Created anew, so a link left at the temporary name is never followed.
+  rmSync(temporary, { force: true });
+  writeFileSync(temporary, content, { flag: 'wx' });
+  renameSync(temporary, path);
+}
+
+/** Removes a file and the directories it leaves empty, up to `root`. */
+export function removeFile(root, path) {
+  rmSync(path, { force: true });
+  for (
+    let dir = dirname(path);
+    dir !== root && existsSync(dir) && readdirSync(dir).length === 0;
+    dir = dirname(dir)
+  )
+    rmdirSync(dir);
+}

package/scripts/lib/generate.mjs

@@ -0,0 +1,175 @@
+// Generated configuration of one app. App code imports these files and never
+// edits them; new-app writes them, and later commands regenerate them from
+// 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';
+
+const HEADER = `// Generated from apps.json by @sempods/apps. Do not edit: change apps.json
+// and run pnpm run regenerate.`;
+
+export const GENERATED_FILES = [
+  'src/sempods.generated.ts',
+  'vite.sempods.generated.ts',
+];
+
+const json = (value) => JSON.stringify(value);
+
+// build-site selects a published profile through Vite's mode, which only the
+// command line sets; dev, plain builds and tests run the local profile.
+export const PROFILE_MODES = {
+  production: 'sempods-production',
+  preview: 'sempods-preview',
+};
+
+/** A published profile: the did:web identity for one site origin. */
+function publishedProfile(name, origin, app) {
+  const { clientId, redirectUri } = siteIdentity(origin, app);
+  return `
+// ${name === 'production' ? 'Published site' : 'Fixed preview address'}: ${origin}
+const ${name}: BrowserRuntimeOptions = {
+  identity: {
+    kind: 'did-web',
+    clientId: ${json(clientId)},
+    redirectUri: ${json(redirectUri)},
+  },
+  returnTo: 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.
+ */
+export function runtimeSource(app, site) {
+  const published = SITE_PROFILES.filter((name) => site?.[name]);
+  const modes = SITE_PROFILES.map(
+    (name) => `  ${json(PROFILE_MODES[name])}: ${json(name)},`,
+  ).join('\n');
+  return `${HEADER}
+import type { BrowserRuntimeOptions, Language } from '@sempods/app-sdk';
+
+export const app = {
+  id: ${json(app.id)},
+  title: ${json(app.title)},
+  language: ${json(app.language)} as Language,
+  basePath: ${json(app.path)},
+  pwa: ${app.pwa},
+} as const;
+
+// Local development: a dynamic identity, local HTTP only.
+const local: BrowserRuntimeOptions = {
+  identity: {
+    kind: 'dynamic',
+    name: app.title,
+    // Read when the runtime is created, not on import, so tests can import
+    // this module outside a browser.
+    get redirectUri() {
+      return \`\${location.origin}${app.path}callback\`;
+    },
+  },
+  returnTo: app.basePath,
+  development: 'loopback-http',
+};
+${published.map((name) => publishedProfile(name, site[name], app)).join('')}
+export const profiles: Readonly<Record<string, BrowserRuntimeOptions>> = {
+${['local', ...published].map((name) => `  ${name},`).join('\n')}
+};
+
+// pnpm run build-site builds with one of these modes; any other mode is local.
+const modes: Readonly<Record<string, string>> = {
+${modes}
+};
+
+export const profile: string = modes[import.meta.env?.MODE ?? ''] ?? 'local';
+
+function unconfigured(name: string): never {
+  throw new Error(
+    \`apps.json has no site.\${name}; run pnpm run configure-site\`,
+  );
+}
+
+export const runtimeOptions: BrowserRuntimeOptions =
+  profiles[profile] ?? unconfigured(profile);
+`;
+}
+
+/** Vite base path, development server and PWA settings for this app's path. */
+export function viteSource(app) {
+  const p = app.path;
+  const escaped = p.replaceAll('/', '\\/');
+  const pwa = app.pwa
+    ? `{
+    // The app registers its worker itself (src/main.tsx) and never takes over
+    // an open page: an update applies once every window is closed.
+    registerType: 'prompt',
+    injectRegister: false,
+    manifest: {
+      id: ${json(p)},
+      name: ${json(app.title)},
+      short_name: ${json(app.title)},
+      lang: ${json(app.language)},
+      start_url: ${json(p)},
+      scope: ${json(p)},
+      display: 'standalone',
+      background_color: '#f6faf9',
+      theme_color: '#176354',
+      icons: [
+        { src: ${json(`${p}icon-192.png`)}, sizes: '192x192', type: 'image/png' },
+        { src: ${json(`${p}icon-512.png`)}, sizes: '512x512', type: 'image/png' },
+      ],
+    },
+    workbox: {
+      // 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.
+      navigateFallback: ${json(`${p}index.html`)},
+      navigateFallbackAllowlist: [/^${escaped}$/],
+      skipWaiting: false,
+      clientsClaim: false,
+      cleanupOutdatedCaches: true,
+    },
+  }`
+    : 'null';
+  return `${HEADER}
+import type { VitePWAOptions } from 'vite-plugin-pwa';
+
+export const base = ${json(p)};
+
+export const server = {
+  host: '127.0.0.1',
+  port: ${app.devPort},
+  strictPort: true,
+} as const;
+
+export const pwa: Partial<VitePWAOptions> | null = ${pwa};
+`;
+}
+
+export function generatedFiles(app, site) {
+  return {
+    'src/sempods.generated.ts': runtimeSource(app, site),
+    'vite.sempods.generated.ts': viteSource(app),
+  };
+}
+
+export function writeGenerated(appDir, app, site) {
+  for (const [file, source] of Object.entries(generatedFiles(app, site)))
+    writeFileSync(join(appDir, file), source);
+}
+
+/** Lists generated files whose content differs from what apps.json produces. */
+export function staleGenerated(appDir, app, site) {
+  return Object.entries(generatedFiles(app, site))
+    .filter(([file, source]) => {
+      try {
+        return readFileSync(join(appDir, file), 'utf8') !== source;
+      } catch {
+        return true;
+      }
+    })
+    .map(([file]) => file);
+}

package/scripts/lib/html.mjs

@@ -0,0 +1,3 @@
+// Escapes text for HTML content and attribute values.
+export const escapeHtml = (text) =>
+  String(text).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);

package/scripts/lib/json.mjs

@@ -0,0 +1,42 @@
+// Reads and writes JSON files in the format the tooling uses.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { replaceFile } from './files.mjs';
+
+/** Two-space indentation and a final newline. */
+export const formatJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+export function writeJson(path, value) {
+  writeFileSync(path, formatJson(value));
+}
+
+/**
+ * Replaces a JSON file in one step: a reader sees the old or the new content,
+ * never a partly written file.
+ */
+export function replaceJson(path, value) {
+  replaceFile(path, formatJson(value));
+}
+
+/** Reads a JSON file and names it when its content is not JSON. */
+export function readJson(path) {
+  const text = readFileSync(path, 'utf8');
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`);
+  }
+}
+
+/**
+ * Runs a file operation and returns undefined when the file does not exist.
+ * Callers act directly instead of checking first, because the file could
+ * change between the check and the use.
+ */
+export function ifPresent(operation) {
+  try {
+    return operation();
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}

package/scripts/lib/merge.mjs

@@ -0,0 +1,159 @@
+// Merges a repository's file with a starter change: three-way merges of
+// text, owner sections that stay verbatim, and starter entries of manifests.
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (result.error) throw result.error;
+  return result;
+}
+
+/** Replaces one section between two marker lines with another text's section. */
+export function withSection(text, markers, from) {
+  const [begin, end] = markers;
+  const span = (value) => {
+    const start = value.indexOf(begin);
+    const stop = value.indexOf(end, start);
+    return start < 0 || stop < 0 ? null : [start, stop + end.length];
+  };
+  const target = span(text);
+  const source = span(from);
+  if (!target || !source) return null;
+  return (
+    text.slice(0, target[0]) + from.slice(...source) + text.slice(target[1])
+  );
+}
+
+/** Three-way merge with git; returns the merged text and its conflict count. */
+export function mergeText(ours, base, theirs, labels) {
+  const dir = mkdtempSync(join(tmpdir(), 'sempods-merge-'));
+  try {
+    const files = ['ours', 'base', 'theirs'].map((name, i) => {
+      const path = join(dir, name);
+      writeFileSync(path, [ours, base, theirs][i]);
+      return path;
+    });
+    const result = git(dir, [
+      'merge-file',
+      '-p',
+      '-L',
+      labels[0],
+      '-L',
+      labels[1],
+      '-L',
+      labels[2],
+      ...files,
+    ]);
+    if (result.status < 0 || result.status > 127)
+      throw new Error(`git merge-file failed: ${result.stderr}`);
+    return { text: result.stdout, conflicts: result.status };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Decides one starter-owned manifest value. A value equal to the one the old
+ * starter shipped follows the new starter; anything else is the owner's and
+ * stays, with a note.
+ */
+function decide(ours, base, theirs) {
+  if (same(ours, theirs)) return { value: ours };
+  // Absence counts as the owner's removal only if the old starter had it.
+  if (ours === undefined)
+    return base !== undefined
+      ? { value: undefined, note: 'removed in this repository; left out' }
+      : { value: theirs };
+  if (same(base, ours)) return { value: theirs };
+  return {
+    value: ours,
+    note: `changed in this repository; kept ${JSON.stringify(ours)}`,
+  };
+}
+
+const KEYED = [
+  'scripts',
+  'dependencies',
+  'devDependencies',
+  'engines',
+  'overrides',
+];
+const PLAIN = ['type', 'private', 'packageManager', 'workspaces'];
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies'];
+
+/** Starter entries of a manifest, merged; owner entries and names are untouched. */
+export function mergeManifest(
+  ours,
+  base,
+  theirs,
+  sdk,
+  sdkVersion,
+  notes,
+  where,
+) {
+  const result = structuredClone(ours);
+  const apply = (target, key, decision, label) => {
+    if (decision.note) notes.push(`${where} ${label}: ${decision.note}`);
+    if (decision.value === undefined) delete target[key];
+    else target[key] = decision.value;
+  };
+  for (const field of PLAIN)
+    apply(
+      result,
+      field,
+      decide(ours[field], base[field], theirs[field]),
+      field,
+    );
+  for (const field of KEYED) {
+    const keys = new Set([
+      ...Object.keys(theirs[field] ?? {}),
+      ...Object.keys(base[field] ?? {}),
+    ]);
+    const target = { ...(result[field] ?? {}) };
+    for (const key of keys) {
+      if (sdk.includes(key) && field.endsWith('ependencies')) continue;
+      apply(
+        target,
+        key,
+        decide(ours[field]?.[key], base[field]?.[key], theirs[field]?.[key]),
+        `${field}.${key}`,
+      );
+    }
+    // The SDK sits where the release puts it; elsewhere only if the release
+    // declares it nowhere in this manifest.
+    if (field.endsWith('ependencies'))
+      for (const key of sdk) {
+        const declared = DEPENDENCY_FIELDS.some(
+          (f) => theirs[f]?.[key] !== undefined,
+        );
+        if (
+          declared
+            ? theirs[field]?.[key] !== undefined
+            : target[key] !== undefined
+        )
+          target[key] = sdkVersion;
+        else if (target[key] !== undefined) {
+          delete target[key];
+          notes.push(
+            `${where} ${field}.${key}: moved to the section the release declares it in`,
+          );
+        }
+      }
+    // 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;
+    if (Object.keys(ordered).length) result[field] = ordered;
+    else delete result[field];
+  }
+  return result;
+}

package/scripts/lib/overview.mjs

@@ -0,0 +1,105 @@
+// The site's static overview and not-found pages. They run no script and no
+// SDK runtime; each entry links to its app's own page. The entry shape is the
+// data model a richer app overview can build on.
+import { escapeHtml as escape } from './html.mjs';
+
+const TEXT = {
+  en: {
+    title: 'Apps',
+    empty: 'No apps yet.',
+    missing: 'Page not found',
+    back: 'All apps',
+  },
+  de: {
+    title: 'Apps',
+    empty: 'Noch keine Apps.',
+    missing: 'Seite nicht gefunden',
+    back: 'Alle Apps',
+  },
+};
+
+// System colors follow light and dark mode and keep their contrast.
+const STYLE = `
+  :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+  body { margin: 0; background: Canvas; color: CanvasText; }
+  main { max-width: 56rem; margin: 0 auto; padding: 2rem 1rem; }
+  h1 { font-size: 1.75rem; margin: 0 0 1.5rem; }
+  ul { list-style: none; margin: 0; padding: 0; display: grid; gap: 1rem;
+       grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr)); }
+  a { display: flex; flex-direction: column; align-items: center; gap: 0.75rem;
+      padding: 1.25rem 1rem; border: 1px solid GrayText; border-radius: 1rem;
+      color: inherit; text-decoration: none; text-align: center; }
+  a:hover { border-color: LinkText; }
+  a:focus-visible { outline: 3px solid Highlight; outline-offset: 3px; }
+  img, .letter { width: 4rem; height: 4rem; border-radius: 1rem; }
+  .letter { display: grid; place-items: center; font-size: 2rem;
+            font-weight: 600; background: GrayText; color: Canvas; }
+  .name { font-weight: 600; }
+  .description { font-size: 0.9rem; }
+`;
+
+function page(language, title, body) {
+  return `<!doctype html>
+<html lang="${escape(language)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escape(title)}</title>
+    <style>${STYLE}</style>
+  </head>
+  <body>
+    <main>
+${body}
+    </main>
+  </body>
+</html>
+`;
+}
+
+function card(entry) {
+  // The name follows as text, so the icon is decorative.
+  const letter = [...entry.title.trim()][0]?.toUpperCase() ?? '?';
+  const icon = entry.icon
+    ? `<img src="${escape(entry.icon)}" alt="" width="64" height="64" />`
+    : `<span class="letter" aria-hidden="true">${escape(letter)}</span>`;
+  const description = entry.description
+    ? `\n          <span class="description">${escape(entry.description)}</span>`
+    : '';
+  return `        <li>
+          <a href="${escape(entry.href)}" lang="${escape(entry.language)}">
+          ${icon}
+          <span class="name">${escape(entry.title)}</span>${description}
+          </a>
+        </li>`;
+}
+
+/** One language for a site page: the apps' shared language, else English. */
+export function siteLanguage(entries) {
+  const languages = new Set(entries.map((entry) => entry.language));
+  const [only] = languages;
+  return languages.size === 1 && TEXT[only] ? only : 'en';
+}
+
+/**
+ * The overview: one card per `{ id, title, language, href, icon?,
+ * description? }`, in the given order.
+ */
+export function renderOverview(entries) {
+  const language = siteLanguage(entries);
+  const text = TEXT[language];
+  const list = entries.length
+    ? `      <ul>\n${entries.map(card).join('\n')}\n      </ul>`
+    : `      <p>${escape(text.empty)}</p>`;
+  return page(language, text.title, `      <h1>${escape(text.title)}</h1>\n${list}`);
+}
+
+/** The page for unknown paths, so no host falls back to an app or the overview. */
+export function renderNotFound(entries) {
+  const language = siteLanguage(entries);
+  const text = TEXT[language];
+  return page(
+    language,
+    text.missing,
+    `      <h1>${escape(text.missing)}</h1>\n      <p><a href="/">${escape(text.back)}</a></p>`,
+  );
+}

package/scripts/lib/paths.mjs

@@ -0,0 +1,33 @@
+// The two places the tooling works with: the owner's repository, found from
+// where a command runs, and the tooling's own files, found from this module.
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The tooling directory: scripts, skeleton, instructions and skills. */
+export const TOOLING = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+);
+
+/** The skeleton a new app starts from. */
+export const SKELETON = join(TOOLING, 'skeleton', 'app');
+
+/**
+ * The apps repository that contains `start`: the nearest directory with
+ * apps.json and package.json. Throws when there is none.
+ */
+export function repositoryRoot(start = process.cwd()) {
+  for (let dir = resolve(start); ; dir = dirname(dir)) {
+    if (
+      existsSync(join(dir, 'apps.json')) &&
+      existsSync(join(dir, 'package.json'))
+    )
+      return dir;
+    if (dirname(dir) === dir)
+      throw new Error(
+        `no apps repository here: no directory from ${resolve(start)} upward has apps.json and package.json`,
+      );
+  }
+}

package/scripts/lib/pnpm.mjs

@@ -0,0 +1,30 @@
+// pnpm runs every install and package script; packageManager in the root
+// package.json pins its version.
+import { spawnSync } from 'node:child_process';
+
+// pnpm defaults to a frozen lockfile in CI. The commands that add an app or
+// move a dependency must update it, and a standalone copy has none.
+export const INSTALL = ['install', '--no-frozen-lockfile'];
+
+// On Windows the shell finds pnpm.cmd but joins the arguments unquoted: pass
+// directories through `cwd`, never as arguments.
+export function pnpm(args, options = {}) {
+  return spawnSync('pnpm', args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    ...options,
+  });
+}
+
+/** Runs a pnpm command that prints JSON; throws with its error output. */
+export function pnpmJson(cwd, args) {
+  const result = pnpm(args, { cwd, stdio: 'pipe', encoding: 'utf8' });
+  if (result.status !== 0)
+    throw new Error(`pnpm ${args.join(' ')} failed: ${result.stderr.trim()}`);
+  return JSON.parse(result.stdout);
+}
+
+/** Script arguments; pnpm passes a leading `--` (npm's habit) through as is. */
+export function scriptArgs(argv = process.argv.slice(2)) {
+  return argv[0] === '--' ? argv.slice(1) : argv;
+}

package/scripts/lib/sdk.mjs

@@ -0,0 +1,45 @@
+// The SDK packages every app uses, and how their exact versions compare.
+export const SDK = ['@sempods/app-sdk', '@sempods/client-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';
+
+// A failed SDK update can leave manifests, lockfile and installed packages at
+// the target already. sdk-update keeps this local checkpoint in the repository
+// root until the entire update passes; tooling updates refuse to start while
+// it exists.
+export const PENDING_UPDATE = '.sdk-update-pending';
+
+// SemVer 2.0: numeric identifiers cannot have leading zeroes.
+export const EXACT_VERSION =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+export function compareVersions(a, b) {
+  const left = EXACT_VERSION.exec(a);
+  const right = EXACT_VERSION.exec(b);
+  for (const [match, v] of [
+    [left, a],
+    [right, b],
+  ])
+    if (!match) throw new Error(`not an exact version: ${JSON.stringify(v)}`);
+  for (let i = 1; i <= 3; i++) {
+    if (BigInt(left[i]) !== BigInt(right[i]))
+      return BigInt(left[i]) > BigInt(right[i]) ? 1 : -1;
+  }
+  if (left[4] === right[4]) return 0;
+  if (!left[4]) return 1;
+  if (!right[4]) return -1;
+  const l = left[4].split('.');
+  const r = right[4].split('.');
+  for (let i = 0; i < Math.max(l.length, r.length); i++) {
+    if (l[i] === r[i]) continue;
+    if (l[i] === undefined) return -1;
+    if (r[i] === undefined) return 1;
+    const ln = /^\d+$/.test(l[i]);
+    const rn = /^\d+$/.test(r[i]);
+    if (ln && rn) return BigInt(l[i]) > BigInt(r[i]) ? 1 : -1;
+    if (ln !== rn) return ln ? -1 : 1;
+    return l[i] > r[i] ? 1 : -1;
+  }
+  return 0;
+}