@sempods/apps 0.0.0-stage → 0.7.0-dev

package/instructions/publish.md

@@ -0,0 +1,148 @@
+# Publish the apps
+
+All apps of the repository are published together as one static site. Each
+app lives under its own path (`https://<host>/<id>/`), and an overview at `/`
+links them. Read this guide before the first deployment, together with the
+installed SDK's `deployment.md` and `pwa.md`
+(`node_modules/@sempods/app-sdk/docs/`).
+
+## 1. Choose the addresses once
+
+Ask the owner for:
+
+- **the published origin** (production), for example `https://apps.example.org`
+  or `https://<site>.netlify.app`. It becomes part of every app's identity,
+  `did:web:<host>:<id>`, with the callback `https://<host>/<id>/callback`.
+  Changing it later changes every identity: every sign-in and Pod grant must be
+  made again. Confirm that the owner controls this address;
+- **a fixed preview address**, optional: an address that always shows the
+  latest deploy of one branch, for example a branch named `preview`. It gets its
+  own identity and should use a test Pod or a test context.
+
+Record them with:
+
+```sh
+pnpm run configure-site --production https://apps.example.org \
+  --preview https://preview--apps.netlify.app
+```
+
+The command writes `site` in `apps.json` and regenerates every app's
+configuration. Local development is unchanged: `pnpm run dev <id>`, plain
+builds and tests keep the local identity.
+
+## 2. Build the site
+
+```sh
+pnpm run build-site                    # production
+pnpm run build-site --profile preview  # the fixed preview address
+```
+
+It builds every app into `site-dist/<id>/` with the published identity and
+writes the overview, `did.json` per app (`/<id>/did.json`, needed by some
+Pods), the SDK's licence notices, `<id>/callback.html` for each callback and a
+top-level `404.html` for unknown paths. The layout is the same for every host.
+`site-dist/` is build output; do not commit it. `apps/<id>/dist` is not
+touched, so `pnpm run build` and `pnpm run preview` in an app keep the local
+identity.
+
+A conforming sempods Pod checks the `did:web` identity against the callback
+address and fetches no DID document. `did.json` serves Pods that also require
+one (step 5 of the deployment check).
+
+A build only works on the origin it was made for: opened anywhere else, the SDK
+stops with a configuration error. Previews on other addresses, such as one per
+pull request or per commit, therefore show no working sign-in. Turn them off
+or treat them as unusable.
+
+## 3. What the host must provide
+
+Every host, whatever it is:
+
+- serves `site-dist/` as static files over HTTPS, with Node from
+  `.node-version` and pnpm from `packageManager` when it builds;
+- answers `/<id>/` and `/<id>/callback?code=…&state=…` with a first response
+  of `200`, without a redirect (`Location` header), with path and query
+  unchanged. The SDK recognises the callback only at its exact path;
+- answers `/<id>/did.json` with the JSON document, not with an app page;
+- does not rewrite every path to an `index.html`, which would also replace
+  scripts, `sw.js` and `did.json`. Unknown paths show the not-found page;
+- keeps the browser's default referrer policy or a stricter one, loads no
+  third-party resources on the callback route, and keeps full callback URLs
+  out of host and CDN logs.
+
+Build command `pnpm run build-site`, publish directory `site-dist`.
+
+Do not add rewrite rules for `/<id>/*`: the files already answer every path,
+and a rule can replace them.
+
+### Netlify (tested)
+
+Netlify serves `/<id>/callback` from `callback.html` with `200` and the query
+intact, and `404.html` for unknown paths; it needs no `_redirects`. Write this
+`netlify.toml` in the repository root when the owner asks for Netlify (the
+starter ships none):
+
+```toml
+[build]
+  command = "pnpm run build-site"
+  publish = "site-dist"
+
+# The branch whose deploys form the fixed preview address.
+[context.preview]
+  command = "pnpm run build-site --profile preview"
+
+# Pull request previews have their own addresses and no identity.
+[context.deploy-preview]
+  command = "echo 'Deploy previews cannot sign in; push to the preview branch.' && exit 1"
+```
+
+Connect the repository to a Netlify site. For a preview, enable branch deploys
+for the `preview` branch: its address is `https://preview--<site>.netlify.app`.
+
+### Cloudflare Pages (not tested by sempods apps)
+
+Pages serves `<id>/callback.html` at `/<id>/callback`. Without the top-level
+`404.html` it would serve the overview for every unknown path.
+
+In the project's build settings: build command `pnpm run build-site`, build
+output directory `site-dist`. For the fixed preview address, set the variable
+`SEMPODS_SITE_PROFILE=preview` for the Preview environment. The branch alias
+`https://preview.<project>.pages.dev` then shows the `preview` branch. Commit
+addresses (`https://<hash>.<project>.pages.dev`) have no working sign-in.
+
+### Cloudflare Workers and other hosts
+
+The layout suits hosts that serve `/<path>` from `<path>.html`. Cloudflare
+Workers static assets do this by default, but the tooling has no recipe yet
+for their asset and deploy configuration. For any other host, check the requirements above before
+the first sign-in.
+
+### Secrets
+
+The apps need no secret: their identity and callback are public. Keep hosting
+and deployment credentials, such as a Netlify or Cloudflare token, in the
+host's or CI's secret store. Everything a build puts into an app is public,
+including `VITE_*` variables and values from `.env.local`; never put a token or
+key there. See "Keep public configuration and credentials separate" in the
+SDK's `deployment.md`.
+
+## 4. Check the deployment
+
+1. For each app and both addresses:
+   - `curl -s -o /dev/null -D - 'https://<host>/<id>/callback?code=x&state=y'`
+     (a GET, as the browser sends it) returns `200` and no `Location`;
+   - `curl -s 'https://<host>/<id>/did.json'` returns the JSON with
+     `"id": "did:web:<host>:<id>"`.
+2. In a fresh browser profile, the owner signs in to each app on the
+   published site, grants only the intended context, saves something and
+   reloads. Never ask for credentials or tokens.
+3. On the preview address, sign in with its own identity against a test
+   context.
+4. In the host's and any CDN's settings, turn off or redact query strings and
+   `Referer` headers in request logs, so callback queries are not kept.
+5. If the Pod rejects the app before or at its consent screen, read
+   `deployment.md` on Pods that require a DID document or an allow-list.
+   Falling back to another identity is not a fix.
+
+Record the published addresses, identities, what was checked and what was not
+in each app's `NOTES.md`.

package/instructions/setup.md

@@ -0,0 +1,112 @@
+# Set up an apps repository
+
+This is the assistant's setup procedure for a repository created from the
+sempods apps starter. The repository's `INIT.md` holds the bootstrap steps and
+the setup record; record progress only there. Follow the repository's
+`AGENTS.md`.
+
+## Check where you are
+
+Inspect the worktree and the setup record before changing anything. The
+repository needs `package.json`, `pnpm-workspace.yaml`, `.node-version`,
+`apps.json` and `.sempods-baseline.json`; after `pnpm install`, the tooling
+package `node_modules/@sempods/apps` and the SDK's reference
+`node_modules/@sempods/app-sdk/docs/ai-app-builder.md`. If these are missing,
+report that the repository is incomplete. Do not invent scripts, configuration
+or a replacement SDK reference to work around it. Record the package and
+version from `.sempods-baseline.json` in the setup record; do not edit that
+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.
+
+## 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 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.
+Open the exact URL it reports; `apps.json` records the assigned `devPort` and
+`path`. Do not switch hostnames or ports during sign-in.
+
+Before calling `new-app`, check both the manifest and `apps/<id>/`. If the
+recorded first app already exists consistently in both, reuse it and its notes;
+skip generation. If only one exists, or the existing app may be unrelated, stop
+that step and explain the mismatch. Never delete the folder, rewrite the
+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.
+
+## Choose repository preferences (optional)
+
+After the owner can try 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
+review rules, ask for the GitHub user/team unless it is known; do not infer a
+handle from a display name. Write `.github/CODEOWNERS` for it, preserving
+entries the owner already has. Record the owner's name if provided; it is not
+a prerequisite for setup.
+
+Record each preference in its setup record field and continue app work:
+`deferred` for an open choice, otherwise the choice and what you verified, for
+example `enabled; on the default branch` or `pending; not yet on the default
+branch`. Do not repeat deferred questions on a resumed run unless the owner
+asks to revisit them.
+
+## Enable sempods version PRs
+
+Dependabot opens version PRs for the repository's dependencies, but not for
+the sempods packages until the owner opts in. In `.github/dependabot.yml`, the
+entry between `# BEGIN OWNER SEMPODS UPDATES` and `# END OWNER SEMPODS
+UPDATES` keeps them out. When the owner chooses version PRs, remove that entry
+and keep the marker lines; tooling updates keep this section as the owner left
+it. Commit the change in the owner's normal commit/PR flow. It takes effect
+once it reaches the default branch; record it as pending until then. To turn
+the PRs off again, restore the entry between the markers.
+
+With the opt-in, Dependabot opens one PR that moves both SDK packages in the
+root and every app, and a separate PR for `@sempods/apps`. An SDK PR follows
+[Update the SDK](app-workflow.md#update-the-sdk); a tooling PR follows the
+[update skill](../skills/update/SKILL.md). Security updates are separate: the
+repository's security settings enable them, and they reach the sempods
+packages with or without this opt-in. Neither needs an Actions permission or
+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
+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.
+
+SDK updates use the [app workflow](app-workflow.md#update-the-sdk). Tooling
+updates follow the [update skill](../skills/update/SKILL.md) when the owner
+asks for one; do not change the `@sempods/apps` version by hand. Publishing
+follows the [publish guide](publish.md) when the owner asks for it.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@sempods/apps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.0-dev",
+  "description": "Tooling for a sempods apps repository: create, check, update and publish several sempods apps with one shared SDK version.",
+  "keywords": [
+    "sempods",
+    "pod",
+    "apps",
+    "pwa",
+    "cli"
+  ],
+  "license": "MIT-0",
+  "author": "Danilo Stein",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sempods/sempods-apps-template.git",
+    "directory": "packages/apps"
+  },
+  "homepage": "https://github.com/sempods/sempods-apps-template/tree/main/packages/apps#readme",
+  "bugs": {
+    "url": "https://github.com/sempods/sempods-apps-template/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0",
+    "pnpm": ">=11.28.2"
+  },
+  "bin": {
+    "sempods-apps": "bin/sempods-apps.mjs"
+  },
+  "exports": {
+    "./create": "./scripts/create.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "skeleton/",
+    "instructions/",
+    "skills/",
+    "shared/",
+    "update-policy.json",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "semver": "7.8.5",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "markdown-extensions": "2.0.0",
+    "remark": "15.0.1",
+    "remark-validate-links": "13.1.0",
+    "unified-engine": "11.2.2"
+  },
+  "peerDependencies": {
+    "@sempods/app-sdk": "^0.5.0",
+    "@sempods/client-sdk": "^0.5.0"
+  },
+  "scripts": {}
 }

package/scripts/build-site.mjs

@@ -0,0 +1,181 @@
+#!/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.
+// 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)
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+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 { PROFILE_MODES, staleGenerated } from './lib/generate.mjs';
+import { ifPresent, writeJson } from './lib/json.mjs';
+import { renderNotFound, renderOverview } from './lib/overview.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { pnpm, scriptArgs } from './lib/pnpm.mjs';
+import { SDK } from './lib/sdk.mjs';
+
+export const SITE_DIR = 'site-dist';
+
+/** Runs the app's own build script with a site mode into `outDir`. */
+function appBuild(appDir, mode, outDir) {
+  // pnpm appends these to the script's final `vite build`. The output path is
+  // relative to the app, so no user directory name passes through the Windows
+  // shell (lib/pnpm.mjs).
+  const args = [
+    ...['run', 'build', '--mode', mode],
+    ...['--outDir', relative(appDir, outDir), '--emptyOutDir'],
+  ];
+  return pnpm(args, { cwd: appDir }).status === 0;
+}
+
+// Paths build-site reserves in each app's output, so an app's own copies are
+// left out: did.json (written here), host files that hosts read only at the
+// site root (Cloudflare would serve a nested 404.html), and the callback:
+// `callback.html` is written here, and an extensionless `callback` would
+// answer the callback path before it.
+const RESERVED = [
+  'did.json',
+  '_redirects',
+  '404.html',
+  'callback',
+  'callback.html',
+];
+
+/** Removes a file or directory and reports whether there was one. */
+const removeIfPresent = (path) =>
+  ifPresent(() => rmSync(path, { recursive: true }) ?? true) ?? false;
+
+/** Copies a file and reports whether there was one to copy. */
+const copyIfPresent = (from, to) =>
+  ifPresent(() => copyFileSync(from, to) ?? true) ?? false;
+
+/** The SDK's Apache-2.0 notices, which travel with the published code. */
+function copyLicences(roots, appOut, appId) {
+  for (const pkg of SDK) {
+    const to = join(appOut, 'licenses', pkg.split('/')[1]);
+    mkdirSync(to, { recursive: true });
+    const from = roots
+      .map((base) => join(base, 'node_modules', pkg))
+      .find((dir) => copyIfPresent(join(dir, 'LICENSE'), join(to, 'LICENSE')));
+    if (!from)
+      throw new Error(
+        `${pkg} with its LICENSE is not installed for apps/${appId}; run pnpm install.`,
+      );
+    copyIfPresent(join(from, 'NOTICE'), join(to, 'NOTICE'));
+  }
+}
+
+/** The overview entry of a built app. */
+function overviewEntry(app, outDir) {
+  const entry = {
+    id: app.id,
+    title: app.title,
+    language: app.language,
+    href: app.path,
+  };
+  if (existsSync(join(outDir, 'icon-192.png')))
+    entry.icon = `${app.path}icon-192.png`;
+  return entry;
+}
+
+/** Builds the site for `profile`; returns what it built and any warnings. */
+export function buildSite(root, { profile = 'production', build = appBuild } = {}) {
+  if (!SITE_PROFILES.includes(profile))
+    throw new Error(`The profile is one of ${SITE_PROFILES.join(', ')}.`);
+  const { apps, site } = readApps(root);
+  if (!site?.[profile])
+    throw new Error(
+      `apps.json has no site.${profile}; run pnpm run configure-site first.`,
+    );
+  if (apps.length === 0) throw new Error('There are no apps to publish yet.');
+  const out = join(root, SITE_DIR);
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+
+  // A hand edit of apps.json would build one identity and publish another.
+  for (const app of apps) {
+    const stale = staleGenerated(join(root, 'apps', app.id), app, site);
+    if (stale.length > 0)
+      throw new Error(
+        `apps/${app.id}/${stale[0]} does not match apps.json; run pnpm run configure-site to regenerate it.`,
+      );
+  }
+
+  const entries = [];
+  const warnings = [];
+  for (const app of apps) {
+    const appDir = join(root, 'apps', app.id);
+    const appOut = join(out, app.id);
+    if (!build(appDir, PROFILE_MODES[profile], appOut))
+      throw new Error(`apps/${app.id}: the build failed.`);
+    const index = join(appOut, 'index.html');
+    const html = ifPresent(() => readFileSync(index, 'utf8'));
+    if (html === undefined)
+      throw new Error(
+        `apps/${app.id}: the build wrote no index.html to ${SITE_DIR}/${app.id}; the app's build script must end with vite build.`,
+      );
+
+    for (const file of RESERVED)
+      if (removeIfPresent(join(appOut, file)))
+        warnings.push(
+          `apps/${app.id}/public/${file} is not published: build-site reserves this path.`,
+        );
+
+    // Some Pods resolve the did:web document before they accept the app.
+    const { clientId, redirectUri } = siteIdentity(site[profile], app);
+    writeJson(join(appOut, 'did.json'), {
+      '@context': 'https://www.w3.org/ns/did/v1',
+      id: clientId,
+    });
+    copyLicences([appDir, root], appOut, app.id);
+
+    // The callback must answer 200 at its exact path with its query intact.
+    // Static hosts serve <path>.html for an extensionless path; Netlify does
+    // so without a redirect.
+    const callback = new URL(redirectUri).pathname;
+    writeFileSync(join(out, `${callback.slice(1)}.html`), html);
+
+    entries.push(overviewEntry(app, appOut));
+  }
+
+  writeFileSync(join(out, 'index.html'), renderOverview(entries));
+  // Hosts serve it for unknown paths; without it, Cloudflare Pages would serve
+  // the overview for every unknown path.
+  writeFileSync(join(out, '404.html'), renderNotFound(entries));
+  return { apps, site, warnings };
+}
+
+function main() {
+  const { values } = parseArgs({
+    args: scriptArgs(),
+    options: { profile: { type: 'string' } },
+  });
+  const root = repositoryRoot();
+  const profile =
+    values.profile ?? process.env.SEMPODS_SITE_PROFILE ?? 'production';
+  const { apps, site, warnings } = buildSite(root, { profile });
+  for (const warning of warnings) console.warn(`build-site: ${warning}`);
+  console.log(`\nBuilt ${SITE_DIR}/ for ${site[profile]} (${profile}):`);
+  for (const app of apps) console.log(`  ${site[profile]}${app.path}`);
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`build-site: ${error.message}`);
+    process.exitCode = 1;
+  }
+}