@sempods/apps 0.0.0-stage → 0.7.0-dev

package/skeleton/app/src/main.tsx

@@ -0,0 +1,18 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import App from './App.tsx';
+import { registerAppWorker } from './pwa.ts';
+import { app } from './sempods.generated.ts';
+
+// Production builds only: the development server has no service worker.
+const registration =
+  import.meta.env.PROD && app.pwa
+    ? registerAppWorker(`${app.basePath}sw.js`)
+    : Promise.resolve(undefined);
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App registration={registration} />
+  </StrictMode>,
+);

package/skeleton/app/src/pwa.ts

@@ -0,0 +1,18 @@
+// Adapted from the sempods TypeScript SDK v0.2.0 recipe
+// examples/todo/pwa/register.tsx, licensed under Apache-2.0; see
+// the LICENSE and NOTICE of the @sempods/app-sdk package. Changes: this header; the notice
+// component moved to NewVersionNotice.tsx.
+/**
+ * Registers the app's service worker. Call it once from the app entry, never on
+ * library import. Resolves to undefined where service workers are unavailable
+ * (plain HTTP other than loopback, blocked by policy) or registration fails:
+ * the app keeps working as an ordinary page.
+ */
+export function registerAppWorker(
+  url = '/sw.js',
+): Promise<ServiceWorkerRegistration | undefined> {
+  if (!('serviceWorker' in navigator)) return Promise.resolve(undefined);
+  // The default scope is the worker's directory: '/' for /sw.js, '/tasks/' for
+  // /tasks/sw.js. That scope is also the worker's base path.
+  return navigator.serviceWorker.register(url).catch(() => undefined);
+}

package/skeleton/app/src/start.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { app } from './sempods.generated.ts';
+import { startMessage } from './start.ts';
+
+describe('startMessage', () => {
+  it('speaks the app language', () => {
+    expect(startMessage('de')).toMatch(/^Verbunden\./);
+    expect(startMessage('en')).toMatch(/^Connected\./);
+  });
+
+  it('has a text for the configured language', () => {
+    // The generated configuration imports without a browser.
+    expect(startMessage(app.language)).not.toBe('');
+  });
+});

package/skeleton/app/src/start.ts

@@ -0,0 +1,9 @@
+import type { Language } from '@sempods/app-sdk';
+
+// Replace this with your app's own domain logic. Pure functions like this one
+// are tested in src/start.test.ts without a browser or a Pod.
+export function startMessage(language: Language): string {
+  return language === 'de'
+    ? 'Verbunden. Beschreibe deinem Assistenten, was diese App tun soll.'
+    : 'Connected. Tell your assistant what this app should do.';
+}

package/skeleton/app/tsconfig.app.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "allowArbitraryExtensions": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
+}

package/skeleton/app/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.test.json" }
+  ]
+}

package/skeleton/app/tsconfig.node.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "module": "nodenext",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts", "vite.sempods.generated.ts"]
+}

package/skeleton/app/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.app.json",
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.test.tsbuildinfo",
+    /* Tests run in Node and may use its APIs, such as node:fs. */
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src/**/*.test.ts", "src/**/*.test.tsx"],
+  "exclude": []
+}

package/skeleton/app/vite.config.ts

@@ -0,0 +1,13 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { VitePWA } from 'vite-plugin-pwa';
+import { base, pwa, server } from './vite.sempods.generated.ts';
+
+// Base path, development port and PWA settings come from apps.json through the
+// generated file; add your own plugins and options here.
+export default defineConfig({
+  base,
+  server,
+  preview: server,
+  plugins: [react(), ...(pwa ? [VitePWA(pwa)] : [])],
+});

package/skills/app-workflow/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: app-workflow
+description:
+  Create or change a sempods app in an owner's apps repository, guide first
+  setup and SDK updates, and verify and record the result. For app work, not
+  maintenance of the tooling or SDK itself.
+---
+
+# App workflow
+
+Read the repository's `AGENTS.md` and owner instructions, then follow the
+[canonical workflow](../../instructions/app-workflow.md). For first setup, use
+the repository's `INIT.md` and the
+[setup procedure](../../instructions/setup.md). Existing apps keep their code
+and decisions in their own folder and `NOTES.md`.
+
+The workflow owns commands, pinned SDK references, verification and handoff. It
+works without skill discovery; this entry adds no separate rules.
+
+For SDK updates, follow
+[Update the SDK](../../instructions/app-workflow.md#update-the-sdk); for
+tooling updates, the [update skill](../update/SKILL.md).

package/skills/update/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: update
+description:
+  Update the tooling of a sempods apps repository created from the starter:
+  install a newer @sempods/apps, migrate the shared files, review the result
+  and open a pull request. Not for SDK-only updates.
+---
+
+# Update the tooling
+
+Use this when the owner asks to update the tooling or the starter, or when a
+pull request raises the `@sempods/apps` version in `package.json`. Read the
+repository's `AGENTS.md` and the setup record in its `INIT.md` first. SDK
+updates follow [Update the SDK](../../instructions/app-workflow.md#update-the-sdk)
+instead.
+
+1. **Start clean.** The working tree must have no uncommitted changes, so the
+   update is one reviewable diff. Work on a new branch, for example
+   `tooling-update-<version>`, or on the branch of the version pull request.
+2. **Update.** `pnpm run update` installs the newest version and migrates;
+   `pnpm run update <version>` a specific one. It first checks that Node and
+   pnpm suit that version; if not, it changes nothing and prints a numbered
+   order to follow before running it again. On the branch of a version pull request, run
+   `pnpm run update <version>` with the version the pull request names, so
+   the same check runs before anything is installed. If pnpm refuses to run
+   it because the dependencies are out of date, start the installed tooling
+   directly:
+   `node node_modules/@sempods/apps/bin/sempods-apps.mjs update <version>`.
+3. **Read the upgrade notes** for every version after the old one, including
+   skipped ones, in `node_modules/@sempods/apps/CHANGELOG.md`. They name what
+   the migration cannot do alone, such as changes the owner's apps need.
+4. **Decide the manual cases.** The migration applies only unambiguous
+   changes. It lists everything else in `.sempods-migration/migration.json`,
+   each with a reason, and leaves those files exactly as they are. Next to
+   the list are the old starter's version (`base/`), the new starter's
+   version (`starter/`) and, where both are text, a merge suggestion
+   (`suggestion/`) whose conflicts are marked. For each case:
+   - Compare the repository's file with `base/` to see what the owner changed,
+     and `base/` with `starter/` to see what the starter changed.
+   - Keep the owner's changes. Keep the owner section of AGENTS.md and the
+     setup record of INIT.md exactly as they are, including their marker
+     lines.
+   - Apply what the starter changed. Where both changed the same lines,
+     follow the intent of each; when it is a matter of choice, ask the owner.
+   - For a file the starter dropped, a file added on both sides or a
+     file/directory collision, explain the case and decide with the owner.
+     Keeping the owner's version or declining a starter change is a valid
+     decision.
+   - Write the decided result to the repository's file; never leave conflict
+     markers from a suggestion in it.
+   - Record each decision and its reason for the pull request.
+5. **Finish.** Review the whole list again, the resulting diff and the owner
+   section and setup record. Only when every listed case has a deliberate
+   decision, run `pnpm run migrate --done`: it confirms those decisions,
+   applies anything automatic still left, rewrites the apps' generated
+   configuration, installs and advances the baseline in
+   `.sempods-baseline.json`. It refuses while a file still contains an
+   unresolved suggestion. If it names new manual cases instead, decide them
+   and run it again. If a step fails, fix the cause and run the same command
+   again; the list and the decisions stay. If pnpm refuses to run it because
+   the dependencies are out of date, run
+   `node node_modules/@sempods/apps/bin/sempods-apps.mjs migrate --done`.
+   Without manual cases, `pnpm run migrate` finishes on its own.
+6. **Check.** Run `pnpm run check` until it passes.
+7. **Hand over.** With a GitHub remote, open a pull request "Update the tooling
+   to <version>" with the migration report, each manual case and how it was
+   decided, and what to try. Tell the owner what changed in plain words and
+   what they should try. App code, app notes and the owner's entries in
+   `package.json` are never rewritten by the migration.

package/update-policy.json

@@ -0,0 +1,35 @@
+{
+  "shared": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "README.md",
+    "INIT.md",
+    "docs/start.md",
+    ".agents/skills/*/SKILL.md",
+    ".claude/skills/*/SKILL.md",
+    "pnpm-workspace.yaml",
+    ".gitignore",
+    ".node-version",
+    ".github/dependabot.yml",
+    ".github/workflows/check.yml",
+    ".github/workflows/codeql.yml",
+    ".github/codeql/codeql-config.yml"
+  ],
+  "sections": {
+    "AGENTS.md": [
+      ["<!-- BEGIN OWNER INSTRUCTIONS -->", "<!-- END OWNER INSTRUCTIONS -->"]
+    ],
+    "INIT.md": [
+      [
+        "<!-- BEGIN INSTANCE SETUP RECORD -->",
+        "<!-- END INSTANCE SETUP RECORD -->"
+      ]
+    ],
+    ".github/dependabot.yml": [
+      ["# BEGIN OWNER SEMPODS UPDATES", "# END OWNER SEMPODS UPDATES"]
+    ]
+  },
+  "seed": ["apps.json", "apps/.gitkeep"],
+  "rootManifest": "package.json",
+  "sdk": ["@sempods/app-sdk", "@sempods/client-sdk"]
+}