@lernapps/tooling 0.0.0-stage → 0.1.0

package/dist/skills/lernapps-quiz/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: lernapps-quiz
+description: Use in Code of a lernapps.net quiz whenever you write or change the question bank src/quiz.json, add a language, or a build or runtime test of the quiz fails. What you write, how the runtime shows and tests the bank, languages, and the quiz's technical rules. The question types and how to write good questions are in lernapps-content-questions.
+license: MIT
+---
+
+# Quiz
+
+- You write `src/quiz.json` and, for the content of its questions, the image files in `src/images/`. Engine, question
+  types, feedback, scoring, order, accessibility and the no-JS page come from the runtime `@lernapps/app-templates`.
+- Schema: `node_modules/@lernapps/app-templates/runtime/quiz/quiz.v1.schema.json`.
+- `create` writes the example bank "Naturwunder der Welt": replace it with the planned questions.
+- The fields of each question type and how to write good questions: skill `lernapps-content-questions`.
+
+## Gotchas
+
+- The build validates the bank; the runtime's tests then answer every question in the browser. A runtime test that
+  fails while the bank validates is a template bug (skill `lernapps-cli`).
+
+## Runtime
+
+### Build and page
+
+- Build reads, validates, renders every question into `index.html`, with the content it shows (`material`), and
+  carries the images of `src/images/` to `images/`.
+- No JS: a worksheet; all questions, then solutions with background and links.
+- JS: one question at a time, right or wrong shown; then each option's `info` (right ones and the choice marked),
+  the explanation, the links. Score and solutions at the end.
+- Order shuffled by `?seed=42` (same link, same order). Deep link to a question: `#frage-<id>`.
+
+### Storage
+
+- Stores nothing, unless `"rememberLastResult": true`: then the last score stays on the device.
+
+### Tests
+
+- From the runtime (`e2e/quiz.e2e.ts`), run by `lernapps check`. Per question: deep link, a right and a wrong answer,
+  every `info`, explanation and links shown. Also full score and the no-JS page.
+- Each further language: its no-JS page (questions, solutions, switch) and one answered question in that language.
+- New runtime features or fixes: `lernapps update` (skill `lernapps-cli`).
+
+### A runtime test fails
+
+- Bank validates (build passes) but a runtime test fails = template bug: act as skill `lernapps-cli` says.
+- Never change the runtime in `node_modules` (`quiz-only-data`). Go on with the questions.
+- A question shows an image or a table with `material`: skill `lernapps-content-questions`, its reference question-types.
+
+### Languages
+
+- German; more with `"languages": ["de", "en"]`, German first (runtime texts: de, en).
+- Then every learner text is a map with each language: title, intro, source titles; per question text, options,
+  `info`, items, pairs, unit, explanation, link titles.
+- Without `languages`: German strings.
+- Link `url`: one address, or a map per language (own Wikipedia).
+- Build errors, one line each, e.g.
+  `questions[1].explanation (en) (question "totes-meer"): the translation is missing; write the text as a map: { de: …, en: … }`;
+  undeclared language: `… is not a language of the app; declare it in languages in src/quiz.json, or remove it`;
+  `languages[0]: German comes first`.
+- Pages: German `index.html`, others `<language>/index.html`, with `lang`, `hreflang`, a no-JS language switch.
+
+```json
+{
+  "id": "totes-meer",
+  "type": "true-false",
+  "text": { "de": "Im Toten Meer kann man nicht untergehen.", "en": "You cannot sink in the Dead Sea." },
+  "answer": true,
+  "explanation": {
+    "de": "Das Wasser ist so salzig, dass ein Mensch an der Oberfläche treibt.",
+    "en": "The water is so salty that a person floats on the surface."
+  },
+  "links": [
+    { "title": { "de": "Totes Meer (Wikipedia)", "en": "Dead Sea (Wikipedia)" }, "url": "https://de.wikipedia.org/wiki/Totes_Meer" }
+  ]
+}
+```
+
+## Rules
+
+### `quiz-only-data`: Write only the question bank and its images
+
+```rule
+id: quiz-only-data
+scope: archetype:quiz
+severity: error
+```
+
+- Change only `src/quiz.json` and add image files to `src/images/`. `index.html`, `src/main.ts`, `e2e/quiz.e2e.ts`,
+  config as generated (`keep-the-preset`).
+- Bank cannot say it → "Where I had to guess", never code around the runtime.
+
+### `quiz-stable-ids`: Keep the ids
+
+```rule
+id: quiz-stable-ids
+scope: archetype:quiz
+severity: warning
+```
+
+- Short, telling `id` ("grand-canyon"); keep it when the text changes (shared links `#frage-<id>`).
+- New question, new id; never reuse a removed one.

package/dist/skills/lernapps-quiz-design/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lernapps-quiz-design
+description: Use in Explore right after choosing the `quiz` archetype - how the content of a lernapps.net quiz maps onto rounds, question types and patterns, which the plan then applies.
+license: MIT
+---
+
+# Designing a quiz
+
+## What a quiz is
+
+- One page of questions with options and feedback. The runtime shows one question at a time, then each option's
+  background, the explanation and links; the score at the end. Without JavaScript: a worksheet with solutions.
+- You will write the question bank `src/quiz.json` and, for what a question shows, image files in `src/images/`;
+  no code (`quiz-only-data`).
+
+## Can and cannot
+
+- The README of the template says it: <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md>.
+  Read it before this skill's mapping, if you have not yet.
+
+## Map the content
+
+- A chapter → a round: the questions of one chapter, next to each other in the bank.
+- A competency → one or more questions.
+- The bank is the shared material: each fact in one question.
+- A pattern → one question type with a fixed form of text, options and background, varied over a round's facts.
+- Not expressible as a question → no code: note it under "Where I had to guess"; an issue at
+  <https://github.com/lernapps/app-templates/issues> if other quizzes need it.
+
+## Question types
+
+| `type` | The learner |
+|---|---|
+| `single-choice` | chooses one option |
+| `multiple-choice` | chooses every correct option |
+| `true-false` | judges a statement |
+| `number` | types a number, within a tolerance |
+| `ordering` | puts items in their fixed order |
+| `matching` | matches left to right |
+
+- Which pattern fits which competency: skill `lernapps-exercise-patterns`.
+
+## Decide
+
+- Languages: German; English as a second language is supported. Each declared language complete.
+- Keep the last score on the device (`rememberLastResult`) or nothing. Keeping it → the entry says
+  `fitness.storage: device`.
+- Order: shuffled per seed; a link with `?seed=42` gives every learner the same order.

package/dist/status-CXoQBgfU.mjs

@@ -0,0 +1,76 @@
+// check/status.ts
+/** The status a rate-limited server answers with. */
+const RATE_LIMITED = 429;
+const RETRIES = 2;
+/** The longest wait before one retry, whatever the server's Retry-After says. */
+const MAX_WAIT = 2e3;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** The wait before retry `attempt` (0, 1, ...): the server's Retry-After in seconds, else 0.5 s doubled, at most 2 s. */
+function wait(retryAfter, attempt) {
+	const seconds = Number(retryAfter);
+	const asked = retryAfter !== null && Number.isFinite(seconds) && seconds >= 0 ? seconds * 1e3 : 500 * 2 ** attempt;
+	return Math.min(asked, MAX_WAIT);
+}
+/**
+* The status of `url` after redirects, and whether it is an HTML page; status 0 when it cannot be fetched. With `ids`,
+* also the element ids of an HTML page that answers without an error, as the server sends it (no script runs).
+*/
+async function linkStatus(url, options = {}) {
+	for (let attempt = 0;; attempt++) {
+		let response;
+		let ids;
+		try {
+			response = await fetch(url, { redirect: "follow" });
+			const html = (response.headers.get("content-type") ?? "").includes("html");
+			if (options.ids && html && response.ok) ids = elementIds(await response.text());
+			else await response.body?.cancel();
+		} catch {
+			return {
+				status: 0,
+				html: false
+			};
+		}
+		if (response.status !== RATE_LIMITED || attempt >= RETRIES) return {
+			status: response.status,
+			html: (response.headers.get("content-type") ?? "").includes("html"),
+			...ids ? { ids } : {}
+		};
+		await sleep(wait(response.headers.get("retry-after"), attempt));
+	}
+}
+/** The character references an attribute value may carry, decoded. */
+const decodeReferences = (value) => value.replace(/&#x([0-9a-f]+);/gi, (_match, hex) => String.fromCodePoint(parseInt(hex, 16))).replace(/&#(\d+);/g, (_match, decimal) => String.fromCodePoint(Number(decimal))).replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+const VALUE = String.raw`\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))`;
+const ID = new RegExp(String.raw`\sid${VALUE}`, "i");
+const NAME = new RegExp(String.raw`\sname${VALUE}`, "i");
+/** The ids of the elements of an HTML page (`id`, and `name` of an `<a>`, which a fragment also finds). */
+function elementIds(html) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const tag of html.match(/<[a-zA-Z][^>]*>/g) ?? []) for (const match of [ID.exec(tag), /^<a\s/i.test(tag) ? NAME.exec(tag) : null]) if (match) ids.add(decodeReferences(match[1] ?? match[2] ?? match[3] ?? ""));
+	return ids;
+}
+/** The fix of a link that could not be checked. */
+const CHECK_AGAIN_LATER = "Nothing to fix for this: the server limits how often it may be asked. Check again later (lernapps check); the other links were checked";
+/**
+* The problem a check reports for `link` at `where` that answered `status`, undefined when it resolves. A broken link
+* gets the check's `fix`; a rate-limited one is not checked: severity hint, with nothing to fix.
+*/
+function linkProblem(where, link, status, fix) {
+	if (status === RATE_LIMITED) return {
+		where,
+		found: `${link} could not be checked: the server answers 429 Too Many Requests (rate limited), also after ${RETRIES} retries`,
+		fix: CHECK_AGAIN_LATER,
+		severity: "hint"
+	};
+	if (status === 0) return {
+		where,
+		found: `${link} cannot be fetched`,
+		fix
+	};
+	if (status >= 400) return {
+		where,
+		found: `${link} answers ${status}`,
+		fix
+	};
+}
+export { linkStatus as n, linkProblem as t };

package/dist/storage.mjs

@@ -0,0 +1,113 @@
+// archetypes/shared/storage.ts
+/**
+* What an app may keep under its prefix: 100 kB (100,000 bytes), measured as browsers count localStorage, 2 bytes per
+* UTF-16 code unit of every key (with the prefix) and value.
+*/
+const STORAGE_QUOTA = 1e5;
+/**
+* The storage of the app named `app`: its id in the catalog (entries/<id>.yaml, rule own-data-only), e.g. "brueche";
+* in localStorage, or with `type: "sessionStorage"` in sessionStorage, which the browser empties when the tab closes.
+*/
+function createStorage(app, options = {}) {
+	return prefixed(`lernapps:${app}:`, `lernapps:${app}:`, STORAGE_QUOTA, options.type);
+}
+/**
+* The values under `prefix` in the browser's storage `type`, which may take at most `quota` bytes together with every
+* other value under `counted` there.
+*/
+function prefixed(prefix, counted, quota, type = "localStorage") {
+	/** The bytes the values under `counted` take, without the one under `except`. */
+	const used = (target, except) => {
+		let bytes = 0;
+		for (let i = 0; i < target.length; i++) {
+			const key = target.key(i);
+			if (key === null || key === except || !key.startsWith(counted)) continue;
+			bytes += (key.length + (target.getItem(key)?.length ?? 0)) * 2;
+		}
+		return bytes;
+	};
+	const store = () => {
+		try {
+			return globalThis[type];
+		} catch {
+			return;
+		}
+	};
+	return {
+		load(key, guard) {
+			try {
+				const text = store()?.getItem(prefix + key);
+				if (text === null || text === void 0) return void 0;
+				const value = JSON.parse(text);
+				return guard(value) ? value : void 0;
+			} catch {
+				return;
+			}
+		},
+		save(key, value) {
+			try {
+				const target = store();
+				if (!target) return false;
+				const text = String(JSON.stringify(value));
+				if (used(target, prefix + key) + (prefix.length + key.length + text.length) * 2 > quota) return false;
+				target.setItem(prefix + key, text);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		remove(key) {
+			try {
+				store()?.removeItem(prefix + key);
+			} catch {}
+		}
+	};
+}
+/**
+* What the learner's settings for every app and for every app of an archetype take together under SETTINGS_PREFIX:
+* 10 kB (10,000 bytes), counted as STORAGE_QUOTA is. A setting for one app only counts towards that app's quota.
+*/
+const SETTINGS_QUOTA = 1e4;
+/**
+* Where the learner's settings for more than one app are kept: `lernapps:settings:<key>` for every app,
+* `lernapps:settings:<archetype>:<key>` for every app of an archetype. `settings` is never the id of an app.
+*/
+const SETTINGS_PREFIX = "lernapps:settings:";
+/**
+* The learner's settings for the app named `app` (its id, as for `createStorage`) of the archetype `archetype`
+* (`explainer`, as its pages mark it with `<meta name="lernapps-archetype">`): the app's own one under
+* `lernapps:<app>:settings:<key>` goes before the archetype's, which goes before the one for every app
+* (rule own-data-only lets an app touch these and no other archetype's). A key has no colon, so that a key for every
+* app is never taken for an archetype's.
+*/
+function createSettings(app, archetype) {
+	const stores = [
+		["app", prefixed(`lernapps:${app}:settings:`, `lernapps:${app}:`, STORAGE_QUOTA)],
+		["archetype", archetype === void 0 ? void 0 : prefixed(`${SETTINGS_PREFIX}${archetype}:`, SETTINGS_PREFIX, SETTINGS_QUOTA)],
+		["all", prefixed(SETTINGS_PREFIX, SETTINGS_PREFIX, SETTINGS_QUOTA)]
+	];
+	const valid = (key) => key !== "" && !key.includes(":");
+	return {
+		load(key, guard) {
+			if (!valid(key)) return void 0;
+			for (const [scope, store] of stores) {
+				const value = store?.load(key, guard);
+				if (value !== void 0) return {
+					value,
+					scope
+				};
+			}
+		},
+		save(key, value, scope) {
+			const at = stores.findIndex(([where]) => where === scope);
+			const store = stores[at]?.[1];
+			if (!valid(key) || store === void 0 || !store.save(key, value)) return false;
+			for (const [, narrower] of stores.slice(0, at)) narrower?.remove(key);
+			return true;
+		},
+		remove(key, scope) {
+			if (valid(key)) stores.find(([where]) => where === scope)?.[1]?.remove(key);
+		}
+	};
+}
+export { SETTINGS_PREFIX, SETTINGS_QUOTA, STORAGE_QUOTA, createSettings, createStorage };

package/generator/app/.agents/skills/app-content/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: app-content
+description: Use for any content work in this app - researching, writing, extending, correcting or reviewing its competencies, chapters, pages, rounds, questions, exercises, figures, terms or sources. This app's own content decisions; they take precedence over the generic lernapps content skills. Load it before you change any content.
+---
+
+# Content guide of this app
+
+<!--
+Skeleton. Delete this comment when you fill the guide.
+- When: after the plan is confirmed, before any content. Replace every placeholder comment below; none may remain
+  (`lernapps check`, rule app-content-guide, fails once the plan is in Commit).
+- Keep the headings.
+- Concrete, for an agent without your conversation: files, ids, data files, one example.
+  - No: "Use varied exercises with figures where they help."
+  - Yes: "Every page ends with section `uebung`: one `generated` exercise of pattern 'Ohmsches Gesetz' from
+    `src/data/widerstaende.yaml`, one `matching` of symbols and parts."
+- Content decision changes → update this file in the same commit.
+- Public: no personal data, no goals of one learner.
+-->
+
+## Curriculum
+
+<!-- FILL IN: Land, Schulform, Jahrgang; orientation (Lehrplan: document, issuer, year, address, page and unit per
+part; welcome, not required); where the creator's material differs, and which one the app follows. -->
+
+## Competencies
+
+<!-- FILL IN: every competency as "Ich kann …", grouped by chapter; per competency: page or round (file, id),
+exercise ids. -->
+
+## Content structure
+
+<!-- FILL IN: how a chapter, page or round is built: sections or question groups in order, ids or titles, what
+each holds; length. -->
+
+## Terminology
+
+<!-- FILL IN: terms used and avoided (why); units, notation; how learners are addressed; glossary terms with
+wording. -->
+
+## Exercise patterns
+
+<!-- FILL IN: per pattern: name, competency, archetype form (block or question type, fixed parts, what varies),
+one example (file, id), data file. -->
+
+## Figures
+
+<!-- FILL IN: figure kinds and images, for what; conventions (colours, labels, units, orientation, sizes); alt
+texts and captions; image origin and licence. -->
+
+## Sources
+
+<!-- FILL IN: sources linked or relied on (Lehrplan, second explanations, videos, articles), how verified, what
+is left out; the creator's material stays local, never committed. -->
+
+## Adding a chapter or round
+
+<!-- FILL IN: the steps for a new chapter (explainer) or round (quiz), in order, with the files: competencies,
+content, exercises from the patterns, entry topics, check, commit. -->
+
+## Rules learned from mistakes
+
+<!-- FILL IN: one line per rule with the mistake it came from. "None yet." until the first. -->

package/generator/app/.github/ISSUE_TEMPLATE/inhaltsfehler.yml

@@ -0,0 +1,25 @@
+name: Fehler im Inhalt melden
+description: Eine Frage, eine Antwort oder eine Erklärung stimmt nicht.
+title: "Fehler im Inhalt: "
+body:
+  - type: markdown
+    attributes:
+      value: Danke, dass du hilfst, die App besser zu machen. Schreib bitte keine Namen oder andere persönliche Daten hinein.
+  - type: input
+    id: wo
+    attributes:
+      label: Wo ist der Fehler?
+      description: Die Frage oder die Seite, am besten mit ihrem Link.
+    validations:
+      required: true
+  - type: textarea
+    id: fehler
+    attributes:
+      label: Was stimmt nicht?
+    validations:
+      required: true
+  - type: textarea
+    id: richtig
+    attributes:
+      label: Was wäre richtig?
+      description: Wenn du es weißt, mit einer Quelle, zum Beispiel einem Schulbuch.

package/generator/app/.github/workflows/pages.yml

@@ -0,0 +1,61 @@
+name: Pages
+
+# Checks the app and publishes it. The job `app` runs the app check of lernapps/tooling: `lernapps check`, the same
+# command the git hooks ran (format, lint, type check, unit tests, build, the checks of the built app, the end-to-end
+# tests), and keeps its validation report as the artifact "validation-report". On main, the job `deploy` publishes
+# the bundle it checked with the app publish action: to the gh-pages branch, which GitHub Pages serves from its root
+# (Settings → Pages → Deploy from a branch → gh-pages, / (root)). It checks that setting, waits until the app's
+# address serves the new bundle, and prints the address; on a failure, its message says what to do. On a pull request
+# from this repo, the job `preview` publishes the bundle the job `app` checked as a preview, with the app preview
+# action: at <the app's address>pr-preview/pr-<number>/, not indexed by search engines, updated on every push and
+# removed when the pull request is closed or merged; one comment on the pull request, in German for the creator,
+# links it. A pull request from a fork gets no preview: its token may not write. The actions first ask what the change
+# can affect (lernapps changes): a change of only the plan (.vibe/) or only docs (docs/**/*.md) checks, publishes and
+# previews nothing, and the jobs succeed with a notice. So the workflow runs on every push and pull request, with no
+# paths filter: a check skipped by a paths filter stays "Pending" and blocks a pull request that requires it. GitHub
+# may start no run for a push that creates main from commits it already has (the first publish): then start it by
+# hand, Actions → Pages → Run workflow on main (gh workflow run Pages --ref main), as the plan says; a run started by
+# hand checks and publishes everything.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened, closed] # closed: removes the preview
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  app:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: lernapps/tooling/actions/app-check@{{tooling}}
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: app
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+    steps:
+      - uses: lernapps/tooling/actions/app-publish@{{tooling}}
+  preview:
+    # a pull request from this repo only; on closing, it removes the preview without a check
+    if: >-
+      always() && github.event_name == 'pull_request' &&
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      (github.event.action == 'closed' || needs.app.result == 'success')
+    needs: app
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      pages: read # the app's address, for the comment
+    steps:
+      - uses: lernapps/tooling/actions/app-preview@{{tooling}}

package/generator/app/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{holder}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/generator/app/renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["github>lernapps/tooling"]
+}