@sempods/apps 0.0.0-stage → 0.7.0-dev

package/scripts/new-app.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// Creates apps/<id> from the skeleton with the root's SDK version and adds it
+// to apps.json.
+// Usage: pnpm run new-app <id> [--title "<title>"] [--language <de|en>] [--no-pwa]
+import {
+  cpSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { extname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import {
+  invalidId,
+  LANGUAGES,
+  nextDevPort,
+  readApps,
+  writeApps,
+} from './lib/apps.mjs';
+import { writeGenerated } from './lib/generate.mjs';
+import { escapeHtml } from './lib/html.mjs';
+import { readJson, 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';
+
+const TEXT = new Set(['.json', '.html', '.md', '.ts', '.tsx', '.css']);
+
+function fillTokens(dir, app) {
+  // Directory entries carry their type, so no separate stat precedes the read
+  // and write of the same path.
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const { name } = entry;
+    const path = join(dir, name);
+    if (entry.isDirectory()) {
+      fillTokens(path, app);
+      continue;
+    }
+    if (!TEXT.has(extname(name))) continue;
+    const title = extname(name) === '.html' ? escapeHtml(app.title) : app.title;
+    const source = readFileSync(path, 'utf8');
+    const filled = source
+      .replaceAll('__APP_ID__', app.id)
+      .replaceAll('__APP_TITLE__', title)
+      .replaceAll('__APP_LANGUAGE__', app.language);
+    if (filled !== source) writeFileSync(path, filled);
+  }
+}
+
+/**
+ * The SDK versions a new app declares: the root's, so all apps share one
+ * version. Each app still declares them itself and stays exportable.
+ */
+function rootSdk(root) {
+  const { devDependencies = {} } = readJson(join(root, 'package.json'));
+  return Object.fromEntries(
+    SDK.map((name) => {
+      const version = devDependencies[name];
+      if (!EXACT_VERSION.test(version ?? ''))
+        throw new Error(
+          `package.json must declare ${name} with an exact version in devDependencies`,
+        );
+      return [name, version];
+    }),
+  );
+}
+
+/**
+ * Creates one app. Throws with a one-line reason and changes nothing when the
+ * ID is invalid or already used.
+ */
+export function createApp(
+  root,
+  { id, title = id, language = 'en', pwa = true },
+) {
+  const reason = invalidId(id);
+  if (reason) throw new Error(reason);
+  if (!LANGUAGES.includes(language))
+    throw new Error(`language must be one of ${LANGUAGES.join(', ')}`);
+  if (typeof title !== 'string' || title.trim() === '')
+    throw new Error('the title must not be empty');
+  const manifest = readApps(root);
+  const appDir = join(root, 'apps', id);
+  if (manifest.apps.some((app) => app.id === id) || existsSync(appDir))
+    throw new Error(`apps/${id} already exists; nothing was changed`);
+
+  const sdk = rootSdk(root);
+  const app = {
+    id,
+    title: title.trim(),
+    language,
+    path: `/${id}/`,
+    devPort: nextDevPort(manifest),
+    pwa,
+  };
+  try {
+    cpSync(SKELETON, appDir, { recursive: true, errorOnExist: true });
+    fillTokens(appDir, app);
+    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,
+      ),
+    );
+    writeJson(pkgFile, pkg);
+    writeGenerated(appDir, app, manifest.site);
+    writeApps(root, { ...manifest, apps: [...manifest.apps, app] });
+  } catch (error) {
+    rmSync(appDir, { recursive: true, force: true });
+    throw error;
+  }
+  return app;
+}
+
+function main() {
+  const { values, positionals } = parseArgs({
+    args: scriptArgs(),
+    allowPositionals: true,
+    options: {
+      title: { type: 'string' },
+      language: { type: 'string' },
+      'no-pwa': { type: 'boolean' },
+      'skip-install': { type: 'boolean' },
+    },
+  });
+  if (positionals.length !== 1) {
+    console.error(
+      'Usage: pnpm run new-app <id> [--title "<title>"] [--language <de|en>] [--no-pwa]',
+    );
+    process.exit(2);
+  }
+  const root = repositoryRoot();
+  let app;
+  try {
+    app = createApp(root, {
+      id: positionals[0],
+      title: values.title,
+      language: values.language,
+      pwa: !values['no-pwa'],
+    });
+  } catch (error) {
+    console.error(`new-app: ${error.message}`);
+    process.exit(1);
+  }
+  console.log(`Created apps/${app.id} (${app.title}).`);
+  if (!values['skip-install']) {
+    const install = pnpm(INSTALL, { cwd: root });
+    if (install.status !== 0) {
+      console.error('pnpm install failed; run it again, then start the app.');
+      process.exit(1);
+    }
+  }
+  console.log(`Start it: pnpm run dev ${app.id}`);
+  console.log(`Then open http://127.0.0.1:${app.devPort}${app.path}`);
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+  main();

package/scripts/regenerate.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Rewrites every app's generated configuration from apps.json, for example
+// after a tooling update changed the generator. Usage: pnpm run regenerate
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readApps } from './lib/apps.mjs';
+import { staleGenerated, writeGenerated } from './lib/generate.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+
+/** Rewrites the generated files that differ; returns them as apps/<id>/<file>. */
+export function regenerate(root) {
+  const { apps, site } = readApps(root);
+  const changed = [];
+  for (const app of apps) {
+    const dir = join(root, 'apps', app.id);
+    if (!existsSync(dir)) continue;
+    const stale = staleGenerated(dir, app, site);
+    if (stale.length === 0) continue;
+    writeGenerated(dir, app, site);
+    changed.push(...stale.map((file) => `apps/${app.id}/${file}`));
+  }
+  return changed;
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    const changed = regenerate(repositoryRoot());
+    console.log(
+      changed.length
+        ? `Regenerated:\n${changed.map((file) => `  ${file}`).join('\n')}`
+        : 'Generated configuration is up to date.',
+    );
+  } catch (error) {
+    console.error(`regenerate: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/sdk-update.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// One SDK release for the root and every registered app: the manifests name
+// it, pnpm installs it, and the update counts only once node_modules has it
+// and check passes. Usage: pnpm run sdk-update <version|latest>
+import {
+  existsSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { readApps } from './lib/apps.mjs';
+import { formatJson, ifPresent, readJson } from './lib/json.mjs';
+import { migrationState } from './migrate.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { INSTALL, pnpm, pnpmJson, scriptArgs } from './lib/pnpm.mjs';
+import {
+  compareVersions,
+  EXACT_VERSION,
+  PENDING_UPDATE,
+  REFERENCE,
+  SDK,
+} from './lib/sdk.mjs';
+
+
+function pnpmOrThrow(root, args) {
+  if (pnpm(args, { cwd: root }).status !== 0)
+    throw new Error(
+      `pnpm ${args.join(' ')} failed; fix the reported problem and rerun`,
+    );
+}
+
+export function registryLookup(root, name, version) {
+  try {
+    return pnpmJson(root, [
+      'view',
+      `${name}@${version}`,
+      'version',
+      'dependencies',
+      '--json',
+    ]);
+  } catch (error) {
+    throw new Error(
+      `Cannot resolve ${name}@${version} from the npm registry (missing version or registry unavailable): ${error.message}`,
+    );
+  }
+}
+
+export function releaseLinks(version) {
+  return {
+    release: `https://github.com/sempods/sempods-typescript/releases/tag/v${version}`,
+    migration: `https://github.com/sempods/sempods-typescript/blob/v${version}/docs/migration.md`,
+  };
+}
+
+/** Plan everything before writing. Registry injection keeps tests offline. */
+export function planUpdate(
+  root,
+  requested = 'latest',
+  {
+    allowDowngrade = false,
+    lookup = (name, version) => registryLookup(root, name, version),
+  } = {},
+) {
+  if (requested !== 'latest' && !EXACT_VERSION.test(requested))
+    throw new Error(
+      'Use latest or an exact semver (for example 0.3.0), not a range or another dist-tag',
+    );
+  const app = lookup(SDK[0], requested);
+  const version = app?.version;
+  if (
+    !EXACT_VERSION.test(version ?? '') ||
+    (requested !== 'latest' && version !== requested)
+  )
+    throw new Error(
+      `${SDK[0]}@${requested} is missing or returned an unexpected version`,
+    );
+  const client = lookup(SDK[1], version);
+  if (client?.version !== version)
+    throw new Error(
+      `${SDK[1]}@${version} is missing or returned an unexpected version`,
+    );
+  if (app.dependencies?.[SDK[1]] !== version)
+    throw new Error(
+      `${SDK[0]}@${version} must depend on exactly ${SDK[1]}@${version}; found ${JSON.stringify(app.dependencies?.[SDK[1]])}`,
+    );
+
+  const entries = [
+    ['package.json', 'devDependencies'],
+    ...readApps(root).apps.map(({ id }) => [
+      `apps/${id}/package.json`,
+      'dependencies',
+    ]),
+  ];
+  const changes = [];
+  for (const [file, section] of entries) {
+    const path = join(root, file);
+    const original = readFileSync(path, 'utf8');
+    const manifest = JSON.parse(original);
+    for (const name of SDK) {
+      const current = manifest[section]?.[name];
+      if (!EXACT_VERSION.test(current ?? ''))
+        throw new Error(
+          `${file}: ${section}.${name} must already be an exact semver`,
+        );
+      if (!allowDowngrade && compareVersions(version, current) < 0)
+        throw new Error(
+          `${file}: downgrade from ${current} to ${version} requires --allow-downgrade`,
+        );
+    }
+    if (SDK.every((name) => manifest[section][name] === version)) continue;
+    for (const name of SDK) manifest[section][name] = version;
+    changes.push({
+      path,
+      original,
+      updated: formatJson(manifest),
+    });
+  }
+  return { version, changes, ...releaseLinks(version) };
+}
+
+
+/** Whether node_modules has both SDK packages at `version` and the reference. */
+export function installedStateComplete(root, version) {
+  try {
+    return (
+      SDK.every(
+        (name) =>
+          readJson(join(root, 'node_modules', name, 'package.json'))
+            .version === version,
+      ) &&
+      existsSync(join(root, REFERENCE))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** On a failed install/check leave a reviewable diff and report the failure. */
+export function applyUpdate(
+  root,
+  plan,
+  {
+    run = (args) => pnpmOrThrow(root, args),
+    installed = () => installedStateComplete(root, plan.version),
+    // pnpm confirms that the lockfile matches every manifest.
+    locked = () =>
+      pnpm(['install', '--frozen-lockfile'], { cwd: root }).status === 0,
+    migration = () => migrationState(root),
+  } = {},
+) {
+  const pending = join(root, PENDING_UPDATE);
+  // Read rather than tested, so nothing races between check and write.
+  const resuming =
+    ifPresent(() => readFileSync(pending, 'utf8')) !== undefined;
+  if (
+    plan.changes.length === 0 &&
+    !resuming &&
+    installed() &&
+    locked()
+  )
+    return false;
+  // Its check would fail on the migration, which waits for this update.
+  const open = !resuming && migration();
+  if (open)
+    throw new Error(
+      `finish the tooling migration first: ${open}. Nothing was changed.`,
+    );
+  writeFileSync(pending, `${plan.version}\n`);
+  for (const { path, updated } of plan.changes) writeFileSync(path, updated);
+  run(INSTALL);
+  if (!installed())
+    throw new Error(
+      `node_modules does not have both SDK packages at ${plan.version} with ${REFERENCE}; fix the cause and run the same command again`,
+    );
+  run(['run', 'check']);
+  rmSync(pending);
+  return true;
+}
+
+function main() {
+  const { values, positionals } = parseArgs({
+    args: scriptArgs(),
+    allowPositionals: true,
+    options: {
+      'allow-downgrade': { type: 'boolean' },
+    },
+  });
+  if (positionals.length !== 1)
+    throw new Error(
+      'Usage: pnpm run sdk-update <version|latest> [--allow-downgrade]',
+    );
+  const root = repositoryRoot();
+  const plan = planUpdate(root, positionals[0], {
+    allowDowngrade: values['allow-downgrade'],
+  });
+  const changed = applyUpdate(root, plan);
+  console.log(
+    changed
+      ? `Updated SDK to ${plan.version}.`
+      : `Already at SDK ${plan.version}; nothing changed.`,
+  );
+  console.log(
+    `SDK release: ${plan.release}\nMigration guide: ${plan.migration}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`sdk-update: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/update.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Updates the tooling: checks that this machine's Node and pnpm suit the
+// target @sempods/apps, installs it and then runs its own migrate, so the new
+// version applies its starter. Nothing changes when a prerequisite is
+// missing. Usage: pnpm run update [<version>|latest]
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+import { refuseLinks, refuseUnsafe } from './migrate.mjs';
+import { repositoryRoot, TOOLING } from './lib/paths.mjs';
+import { pnpm, pnpmJson, scriptArgs } from './lib/pnpm.mjs';
+import { EXACT_VERSION } from './lib/sdk.mjs';
+import {
+  baselineSnapshot,
+  downloadPackage,
+  installedVersion,
+  PACKAGE,
+  readBaseline,
+  starterAt,
+} from './lib/shared.mjs';
+
+/** Problems that stop the update before anything is installed. */
+export function preflight(target, { node, pnpmVersion }) {
+  const problems = [];
+  const { node: needsNode, pnpm: needsPnpm } = target.engines ?? {};
+  if (needsNode && !semver.satisfies(node, needsNode))
+    problems.push({ tool: 'Node', current: node, range: needsNode });
+  if (needsPnpm && pnpmVersion && !semver.satisfies(pnpmVersion, needsPnpm))
+    problems.push({ tool: 'pnpm', current: pnpmVersion, range: needsPnpm });
+  return problems;
+}
+
+/** The order to follow when the target needs newer tools. */
+export function prerequisiteOrder(target, problems) {
+  const steps = [
+    ...problems.map(({ tool, range }) =>
+      tool === 'Node'
+        ? `Install a Node version in ${range} and write it to .node-version.`
+        : `Set packageManager in package.json to a pnpm version in ${range}; pnpm switches to it by itself.`,
+    ),
+    `Run pnpm run update ${target.version} again.`,
+  ];
+  return [
+    `${PACKAGE} ${target.version} needs ${problems.map(({ tool, current, range }) => `${tool} ${range} (this machine has ${current})`).join(' and ')}. Nothing was changed.`,
+    ...steps.map((step, i) => `${i + 1}. ${step}`),
+  ].join('\n');
+}
+
+/**
+ * Refuses before installing when a path the old or the new starter writes is
+ * a symbolic link here: the installed version's migrate would refuse only
+ * after the install.
+ */
+export function refuseLinkedStarter(
+  root,
+  version,
+  { download = downloadPackage, installed = TOOLING } = {},
+) {
+  const dir = mkdtempSync(join(tmpdir(), 'sempods-update-'));
+  try {
+    const files = Object.keys(
+      starterAt(download(version, join(dir, 'target'))).snapshot.files,
+    );
+    const baseline = readBaseline(root);
+    if (baseline)
+      files.push(
+        ...Object.keys(
+          baselineSnapshot(baseline, {
+            installed,
+            download: (from) => download(from, join(dir, 'base')),
+          }).files,
+        ),
+      );
+    refuseLinks(root, files);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Declares and installs exactly `version`, then checks that node_modules has
+ * it: a version pull request may name it before anything is installed.
+ */
+export function installTarget(
+  root,
+  version,
+  {
+    run = (args) => pnpm(args, { cwd: root }).status === 0,
+    installed = () => installedVersion(root),
+  } = {},
+) {
+  // The repository is a pnpm workspace; the tooling belongs to its root.
+  const add = ['add', '-w', '--save-dev', '--save-exact'];
+  if (!run([...add, `${PACKAGE}@${version}`]))
+    throw new Error(
+      `installing ${PACKAGE} ${version} failed; fix the cause and run the update again`,
+    );
+  const now = installed();
+  if (now !== version)
+    throw new Error(
+      `${PACKAGE} ${now ?? '(none)'} is installed instead of ${version}; run pnpm install and the update again`,
+    );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    const args = scriptArgs();
+    if (args.length > 1)
+      throw new Error('Usage: pnpm run update [<version>|latest]');
+    const spec = args[0] ?? 'latest';
+    if (spec !== 'latest' && !EXACT_VERSION.test(spec))
+      throw new Error('Use latest or an exact version, for example 0.7.0');
+    const root = repositoryRoot();
+    const found = pnpmJson(root, [
+      'view',
+      `${PACKAGE}@${spec}`,
+      'version',
+      'engines',
+      '--json',
+    ]);
+    // With only one of the fields present, pnpm prints that value alone.
+    const target = typeof found === 'string' ? { version: found } : found;
+    refuseUnsafe(root, target.version);
+    const version = pnpm(['--version'], {
+      cwd: root,
+      stdio: 'pipe',
+      encoding: 'utf8',
+    });
+    const problems = preflight(target, {
+      node: process.versions.node,
+      pnpmVersion: version.status === 0 ? version.stdout.trim() : undefined,
+    });
+    if (problems.length > 0) {
+      console.error(prerequisiteOrder(target, problems));
+      process.exitCode = 2;
+    } else {
+      refuseLinkedStarter(root, target.version);
+      installTarget(root, target.version);
+      // The installed version migrates with its own code.
+      process.exitCode =
+        pnpm(['exec', 'sempods-apps', 'migrate'], { cwd: root }).status ?? 1;
+    }
+  } catch (error) {
+    console.error(`update: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/shared/files/0221b70340152ba3cc615342254603b29b89c4d7d944d7b3b3e647873bdcefa0

@@ -0,0 +1,11 @@
+---
+name: app-workflow
+description:
+  Create or change an app in a sempods apps repository using its canonical app
+  workflow. Not for tooling or SDK maintenance.
+---
+
+Read the canonical app-workflow skill that the installed tooling package ships,
+`node_modules/@sempods/apps/skills/app-workflow/SKILL.md`. If `node_modules` is
+missing, follow the bootstrap steps in `INIT.md` first. The skill routes to
+AGENTS.md, setup and the shared instructions.

package/shared/files/1c29eed0a0297c742ca5814de9081ff8efce3b2da5d9e1bdf90a403873da4aa9

@@ -0,0 +1,61 @@
+# Make an app with your assistant
+
+## Start
+
+You need Node.js in the version `.node-version` names. With a version manager,
+name that version explicitly, for example with `nvm install` or
+`fnm use --install-if-missing` followed by the version. The installation stops
+with a clear message on an older Node.
+
+You also need pnpm. With Node 24, run `corepack enable pnpm`; otherwise install
+pnpm with npm. `package.json` names the exact pnpm version, and pnpm switches
+to it by itself.
+
+[Open this repository in your assistant and paste the starter prompt](../README.md#start-with-your-idea).
+Describe one thing you want to do: “Add something to my shopping list.” Your
+assistant sets up the app and gives you a local link to open.
+It chooses the technical details and asks you about what the app should do.
+Review rules and automatic updates can wait until you have tried the first
+version.
+
+## Change
+
+Ask for the next small improvement: “Let me mark an item as bought.” Keep trying
+the app as it grows. For another app, say “Create a new app for my book list.”
+Your existing apps stay in the same repository.
+
+## Try
+
+Use a test context with made-up data in your Pod. Sign in on the Pod's page,
+then choose that context in the app. Ask your assistant to check a save and a
+reload, and to tell you what it has not tested. Never paste passwords or tokens
+into chat. Without a Pod, you can still try the screen.
+
+## Keep apps up to date
+
+After trying your first app, you can ask your assistant to turn on update
+suggestions: GitHub then proposes each new SDK or tooling version as a change
+for you to review. Until then, it proposes none; security fixes still arrive.
+Ask your assistant: “Update my SDK and explain what I should try.” A patch
+update is merged when checks pass. Before 1.0 a minor update may break apps;
+your assistant follows the migration guide, adapts your apps and lists what to
+try on the Pod. You decide when to merge.
+
+When the tooling gets better, ask your assistant: “Update the tooling.” It
+brings in the new version as a change you can review and tells you if your
+computer needs a newer Node or pnpm first. Your apps, notes and instructions
+stay yours. Where the update and one of your changes overlap, your assistant
+combines them and asks you when it is a matter of choice.
+
+## Publish
+
+When an app is ready, ask your assistant: “Publish my apps.” It asks for the
+web address you own, for example a free Netlify or Cloudflare address, and
+optionally a second address for previews. All your apps then share one site,
+each under its own path, with an overview page. Choose the address once:
+changing it later means signing in to every app again. On the published site,
+apps can be installed on a device. Offline startup will not make Pod edits
+work offline. You decide when to publish.
+
+Your assistant follows the repository's instructions and records progress in
+each app's `NOTES.md`, so a later session can pick up where you left off.

package/shared/files/31ede0d1a035d8531100ebfd751510c772ab0871309a0b9752a77fb96187eb53

@@ -0,0 +1,25 @@
+{
+  "name": "my-sempods-apps",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.28.2",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "scripts": {
+    "new-app": "sempods-apps new-app",
+    "dev": "sempods-apps dev",
+    "regenerate": "sempods-apps regenerate",
+    "configure-site": "sempods-apps configure-site",
+    "build-site": "sempods-apps build-site",
+    "check": "sempods-apps check",
+    "sdk-update": "sempods-apps sdk-update",
+    "update": "sempods-apps update",
+    "migrate": "sempods-apps migrate"
+  },
+  "devDependencies": {
+    "@sempods/app-sdk": "0.5.0",
+    "@sempods/apps": "0.0.0",
+    "@sempods/client-sdk": "0.5.0"
+  }
+}