@lernapps/tooling 0.0.0-stage → 0.1.0

package/dist/preset.mjs

@@ -0,0 +1,60 @@
+import { defineConfig, mergeConfig } from "vite-plus";
+// archetypes/shared/preset.ts
+/** Not code: what tools write, and prose. */
+const notCode = [
+	"dist/**",
+	"node_modules/**",
+	"playwright-report/**",
+	"test-results/**",
+	"**/*.md"
+];
+const preset = {
+	base: "./",
+	fmt: {
+		printWidth: 120,
+		ignorePatterns: notCode
+	},
+	lint: {
+		ignorePatterns: notCode,
+		jsPlugins: ["@lernapps/tooling/lint"],
+		options: {
+			typeAware: true,
+			typeCheck: true
+		},
+		rules: {
+			"lernapps/learner-text-german": "error",
+			"lernapps/no-request-before-click": "error",
+			"lernapps/storage-through-wrapper": "error",
+			"lernapps/suppression-reason": "error",
+			"lernapps/vue-component-browser-globals": "error",
+			"lernapps/vue-component-imports": "error",
+			"lernapps/vue-component-no-html-injection": "error",
+			"lernapps/vue-component-no-network": "error",
+			"typescript/no-explicit-any": "error"
+		}
+	},
+	test: { include: ["src/**/*.test.ts", "test/**/*.test.ts"] },
+	staged: { "*.{ts,tsx,json}": "vp fmt" }
+};
+/** Whether the plugins (nested lists, as Vite takes them) hold one named `name`. */
+const hasPlugin = (plugins, name) => Array.isArray(plugins) ? plugins.some((plugin) => hasPlugin(plugin, name)) : typeof plugins === "object" && plugins !== null && "name" in plugins && plugins.name === name;
+/**
+* The preset, with the app's own settings merged over it. With the interactive runtime's build step among the
+* plugins, a component may also import the app's own files in src/ and the libraries in its dependencies, as that
+* build allows (lint/rules/vue-component-imports.ts).
+*/
+const lernapps = (config = {}) => {
+	const base = hasPlugin(config.plugins, "lernapps-interactive") ? {
+		...preset,
+		lint: {
+			...preset.lint,
+			rules: {
+				...preset.lint?.rules,
+				"lernapps/vue-component-imports": ["error", { scope: "src" }]
+			}
+		}
+	} : preset;
+	return defineConfig(mergeConfig(base, config));
+};
+var preset_default = lernapps();
+export { preset_default as default, lernapps };

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

@@ -0,0 +1,49 @@
+---
+name: lernapps-app
+description: Use in Explore, when a creator wants a learning app for lernapps.net, even if they only say "Lern-App", "Übungs-App" or "für meine Klasse". What every app on lernapps.net must be, how to choose an archetype, and where to read what each one can and cannot do.
+license: MIT
+---
+
+# lernapps app
+
+## What an app is
+
+- A small learning app for school: static, runs in the browser, no account, no tracking, no ads, free.
+- Accessible (WCAG 2.1 AA) and usable at 360 px. A deviation the idea needs (a time limit, a keyboard) is allowed; the
+  catalog entry then says it in `limits`.
+- Other servers (video, map) only after the learner's click. Nothing about a real learner in any text.
+- Published at its creator's own address, usually `https://<owner>.github.io/<repo>/`. Once listed, lernapps.net
+  serves a copy at `https://lernapps.net/apps/start/<id>/`, built from the commit the entry names; the creator stays the author.
+- Licence that allows the copy (MIT or Apache 2.0 for code, CC BY 4.0 for content); files referenced relatively.
+
+## Rules
+
+- Each rule is a section with a rule block: `id`, `scope`, `severity`. Follow every rule in scope, checked or not.
+- Scope: `listing` every listed app; `tooling` every app built with `@lernapps/tooling`; `archetype:<name>` that
+  archetype.
+- Severity: `error` never break; `warning` only with a reason in place; `hint` advice. At the listing, a `tooling`
+  rule counts as a warning.
+- Each skill holds the rules of its phase. All rules: <https://lernapps.net/tooling/rules/>.
+
+## What each archetype can do
+
+| Archetype | Learners … | Can and cannot (README of its template) |
+|---|---|---|
+| `quiz` | answer questions with options and feedback | <https://raw.githubusercontent.com/lernapps/app-templates/main/quiz/README.md> |
+| `explainer` | read pages that explain, each with exercises | <https://raw.githubusercontent.com/lernapps/app-templates/main/explainer/README.md> |
+| `interactive` | act in one app page, by turns or in real time | <https://raw.githubusercontent.com/lernapps/app-templates/main/interactive/README.md> |
+
+## Choose the archetype
+
+- Choose after the interview topics "Goal" and "Learners", from what learners do. Read the patterns of the subject
+  first (skill `lernapps-exercise-patterns`): how learners practise points to the archetype.
+- Before you choose, read the README of each archetype in question, in full. Tell the creator in plain words what the
+  chosen one can and cannot do, before you ask about content, amount and look.
+- A few background sections on the start page keep an app `interactive`.
+- Explanation pages with one interactive exercise → `explainer` with a component.
+
+## Gotchas
+
+- A typing game or a trainer is `interactive`, never `explainer`.
+- What an archetype cannot do is no plan task: tell the creator, choose another archetype or leave it out.
+- The archetype decides what you may write later. Choose it from what learners do, not from what is quickest.

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

@@ -0,0 +1,156 @@
+---
+name: lernapps-cli
+description: Use in Code of a lernapps.net app - to create or update the app with the CLI, whenever a check, a git hook or a runtime test fails, and before you change the preset, the configuration or the storage. What `lernapps create`, `update`, `check` and `screenshots` do, how to fix from a message, when to suppress, and what of the preset you never change.
+license: MIT
+---
+
+# lernapps CLI and checks
+
+## Read when
+
+- [references/platform-rules.md](references/platform-rules.md): a check names a `listing` rule, and before the
+  listing.
+
+## Create
+
+1. Only after the creator's yes to the plan (`explore-before-code`). In the plan's folder:
+   `npx lernapps create --archetype <archetype>`.
+2. No git repo yet: `git init --initial-branch=work`. Then `npm install` (dependencies, git hooks), and commit
+   everything on `work`.
+3. Needs git, Node ≥ 22.18, registry.npmjs.org. Blocked → ask the creator to allow it, run again. Never write the
+   app by hand.
+4. It keeps the plan and the installed skills, and writes the content guide's skeleton.
+
+## Update
+
+- `npx --yes @lernapps/tooling@latest update`, then `npm install`: moves the app to this
+  tooling's runtime and checks, replaces the `lernapps-*` skills, adds what an older app lacks.
+- `npm update` moves tooling and runtime only within their ranges (`^0.1.0` takes patches); `update` moves the ranges.
+
+## Check
+
+- `npx lernapps check`: format, lint, types, unit tests, build, checks of the built app, end-to-end tests. The hooks
+  run its parts (`--pre-commit`, `--pre-push`); CI runs it whole.
+- Report: `node_modules/.cache/lernapps/validation-report.yaml`. Options: `npx lernapps check --help`.
+
+## Look at the app
+
+A check says the rules hold; only a look says what a learner sees. Show the creator the pages before a push, and before
+a submission they declare something about.
+
+- Explainer or quiz: build (`npx vp build`), then `npx lernapps screenshots`. It writes one image of every page, one of
+  every figure, and an `index.html` that shows them in order to `screenshots/` (not part of the app: do not commit it).
+  Show the images, or the `index.html` where you can show HTML. Check every figure in its own image
+  (`…-figure-<n>.png`): a page image is scaled down, its details are not readable. `--desktop` adds 1280 px images.
+  Options: `npx lernapps screenshots --help`.
+- Interactive app: `screenshots` does not support it. Open the built app with the Playwright the tooling installs
+  (`import { chromium } from "playwright"`), at 390 px width, and take `page.screenshot({ fullPage: true })` of each
+  state the creator should see, from a short script outside the app.
+
+## A check fails
+
+1. Read the message: it names the step and links the rule (`https://lernapps.net/tooling/rules/#<id>`).
+2. Failed commit: one line names the step and `node_modules/.cache/lernapps/pre-commit.log`. Read that log.
+3. Fix the cause. The rule's text is in the skill of the phase; the link says where.
+4. Run the check again. Go on only when it passes.
+
+- A runtime test (`@lernapps/app-templates`) fails while your content validates: a bug of the template.
+  1. Tell the creator. Open an issue at <https://github.com/lernapps/app-templates/issues> with the validation
+     report, or ask the creator to.
+  2. Never change tests, config or `node_modules` to get around it. Go on with the content.
+  3. After the fix: update, check, commit.
+- A link answers HTTP 429: "not checked", a hint that fails nothing. Tell the creator which; go on.
+
+## Rules
+
+### `checks-pass`: Run the checks before you push
+
+```rule
+id: checks-pass
+scope: tooling
+severity: error
+```
+
+- `lernapps check` passes before every push. The hooks run it too; CI runs the same command and keeps its report as
+  the artifact `validation-report`.
+
+### `fix-from-message`: Fix failed checks, never bypass them
+
+```rule
+id: fix-from-message
+scope: tooling
+severity: error
+```
+
+- Fix the cause the message names.
+- Never bypass a hook: no `--no-verify`, no acceptance such as `ARC42_CONSISTENT` without a finding shown.
+- Never delete a test to make it pass.
+
+### `suppression-reason`: Suppress only in place, with the reason
+
+```rule
+id: suppression-reason
+scope: tooling
+severity: error
+```
+
+- Lint: only on the line, with the rule named and the reason after `--`:
+  `// oxlint-disable-next-line lernapps/no-request-before-click -- the video loads after a click`.
+- Types: only `// @ts-expect-error -- <reason>`; never `@ts-ignore` or `@ts-nocheck`.
+- The review reads every suppression.
+
+### `lockfile-matches`: Commit the lock file with every dependency change
+
+```rule
+id: lockfile-matches
+scope: tooling
+severity: error
+```
+
+- Change dependencies with `npm install`, never in `package.json` alone; commit `package-lock.json` with it.
+- A git pin (`github:…#<commit>`) moves in both files together.
+
+### `keep-the-preset`: Extend the preset, change nothing of it
+
+```rule
+id: keep-the-preset
+scope: [archetype:explainer, archetype:interactive, archetype:quiz]
+severity: error
+```
+
+- `vite.config.ts` is `export default lernapps()`, with only the app's own settings as generated
+  (`lernapps({ plugins: [quiz()] })`).
+- `tsconfig.json` extends `@lernapps/tooling/tsconfig.json` as generated.
+- The hooks come from the package (`prepare` in `package.json`); never replace one.
+- Never turn a lint rule off or lower its severity.
+
+### `strict-typescript`: TypeScript only, strict
+
+```rule
+id: strict-typescript
+scope: [archetype:explainer, archetype:interactive, archetype:quiz]
+severity: error
+```
+
+- Every source file is TypeScript; no JavaScript files.
+- Never `any`: use `unknown` and narrow it, or write the type.
+- Type the creator's data; validate it at build time.
+
+### `storage-through-wrapper`: Store only through the preset's storage
+
+```rule
+id: storage-through-wrapper
+scope: [archetype:explainer, archetype:interactive, archetype:quiz]
+severity: error
+```
+
+- Only `createStorage` from `@lernapps/tooling/storage`, named after the app's id in the catalog (own prefix
+  `lernapps:<id>:`, rule `own-data-only`; works when storage is blocked).
+- At most 100 kB under the prefix (keys and values, 2 bytes per UTF-16 unit). Beyond, `save` returns false and the
+  app keeps working.
+- A setting of the learner that holds for every app or every app of the archetype: `createSettings("<id>",
+  "<archetype>")`, saved only where the learner chose it (`"app"`, `"archetype"` or `"all"`); the app's own goes first.
+- Keep the learning state, not growing histories.
+- What only a reload must not lose, such as an answer being written, lasts while the tab is open:
+  `createStorage("<id>", { type: "sessionStorage" })` (sessionStorage, same prefix and limit).
+- Never `localStorage`, `sessionStorage`, IndexedDB or cookies directly.

package/dist/skills/lernapps-cli/references/platform-rules.md

@@ -0,0 +1,258 @@
+# Platform rules
+
+- Every app on lernapps.net, however built (this tooling, by hand, another framework, Lovable, bolt.new).
+- Scope `listing`: every listed app, wherever hosted. Severity `error` never break; `hint` advice.
+- Check a built or published app: `npx --yes @lernapps/tooling check <dir|url>` (= `lernapps check`);
+  `--entry <file>` checks the catalog entry against it.
+- Published at its own address (e.g. `https://<owner>.github.io/<repo>/`); once listed, lernapps.net serves a copy at
+  `https://lernapps.net/apps/start/<id>/`, built from the entry's `commit`.
+- All rules: <https://lernapps.net/tooling/rules/>.
+
+## App
+
+### `no-tracking`: Collect nothing, set no cookies
+
+```rule
+id: no-tracking
+scope: listing
+severity: error
+```
+
+- No cookies, analytics, tracking pixels, server storing data.
+- Stored data stays on the device (`localStorage`, or `sessionStorage` while the tab is open) and serves only the app.
+
+### `own-data-only`: Touch only the app's own data in the browser
+
+```rule
+id: own-data-only
+scope: listing
+severity: error
+```
+
+- Every app on lernapps.net shares one origin with the other apps and the platform.
+- Own data: keys of `localStorage` and `sessionStorage`, IndexedDB databases and caches named `lernapps:<id>:…`,
+  `<id>` the app's id in the catalog (`entries/<id>.yaml`).
+- Also every app's: the learner's settings for every app (`lernapps:settings:<key>`, a key without a colon) and for
+  every app of the page's archetype (`lernapps:settings:<archetype>:…`, the archetype of
+  `<meta name="lernapps-archetype">`); never another archetype's. `settings` is never an app's id.
+- Never read, write or remove other keys; never `clear()`; never `caches.match()` without `cacheName`.
+- Built with this tooling: `createStorage("<id>")` from `@lernapps/tooling/storage`; settings with
+  `createSettings("<id>", "<archetype>")`.
+- `lernapps check` puts another app's data into the browser and reports every access to it, before a click.
+
+### `runs-in-browser`: Runs in the browser, without installation
+
+```rule
+id: runs-in-browser
+scope: listing
+severity: error
+```
+
+- Opens and works at its URL in a current browser. No app store, download or extension.
+
+### `app-checkable`: The published app can be opened and checked
+
+```rule
+id: app-checkable
+scope: listing
+severity: error
+```
+
+- Opens at the entry's `url`; a built app from its bundle (`index.html`).
+- Page does not load, build fails, no browser, check stops → only this rule is reported. Fix, check again.
+- Opens in a browser but the check fails → issue at <https://github.com/lernapps/tooling/issues> with the message.
+
+### `no-account`: No account
+
+```rule
+id: no-account
+scope: listing
+severity: error
+```
+
+- Whole app usable without sign-up or login.
+
+### `free-of-charge`: Free of charge
+
+```rule
+id: free-of-charge
+scope: listing
+severity: error
+```
+
+- Every part free: no payment, paid upgrade or ending trial.
+
+### `no-ads`: No ads
+
+```rule
+id: no-ads
+scope: listing
+severity: error
+```
+
+- No advertising, sponsored content or product placement.
+
+### `learners-act`: Learners do something themselves
+
+```rule
+id: learners-act
+scope: listing
+severity: error
+```
+
+- Every page or screen asks learners to try, practise or decide. Reading alone is not enough.
+
+### `no-request-before-click`: No request to another server before a click
+
+```rule
+id: no-request-before-click
+scope: listing
+severity: error
+```
+
+- Bundle fonts, scripts, pictures at build time.
+- Other servers (video, map) only after the learner's click.
+- No other servers' URLs in code; at a click-to-load line suppress the lint message with this reason.
+
+### `accessible`: Accessible to WCAG 2.1 AA
+
+```rule
+id: accessible
+scope: listing
+severity: error
+```
+
+- WCAG 2.1 AA: labels, contrast, keyboard, text alternatives.
+- Deviate only where the idea needs it (typing game against the clock); then say what is missing, in plain German,
+  in the entry's `limits`.
+- With `limits`: `lernapps check --entry` reports warnings; without: errors.
+
+### `usable-at-360px`: Usable at 360 px
+
+```rule
+id: usable-at-360px
+scope: listing
+severity: error
+```
+
+- Every page at 360 px width: no horizontal scrolling, every control reachable.
+- Deviate only where the idea needs it (keyboard required), in `limits` as under `accessible`.
+
+### `learner-text-german`: German always, every declared language complete
+
+```rule
+id: learner-text-german
+scope: listing
+severity: error
+```
+
+- Texts for learners, teachers, parents: German, plain (short sentences, active voice, no jargon).
+- More languages only where the archetype supports them (explainer, quiz: `languages`, German first); each declared
+  language complete, no other.
+- Texts out of code: in the content (explainer YAML, quiz bank) or message files (`src/messages/de.json`, shown
+  with `translator` from `@lernapps/tooling/i18n`).
+
+### `third-party-licence`: Name source and licence of others' content
+
+```rule
+id: third-party-licence
+scope: listing
+severity: error
+```
+
+- Others' content (texts, pictures, quotes) only with a licence that allows it; source and licence next to it.
+
+### `dependency-licence`: Only dependencies with an open licence
+
+```rule
+id: dependency-licence
+scope: listing
+severity: error
+```
+
+- `dependencies` only with these licences, transitively: MIT, MIT-0, ISC, 0BSD, BSD-2-Clause, BSD-3-Clause,
+  Apache-2.0, MPL-2.0, BlueOak-1.0.0, Zlib, Unlicense, CC0-1.0, CC-BY-4.0, Python-2.0.
+- Build tools: `devDependencies`.
+
+### `links-resolve`: Every link resolves
+
+```rule
+id: links-resolve
+scope: listing
+severity: error
+```
+
+- Every link and resource points to a page or file the build writes. Relative links inside the app.
+
+### `pages-reachable`: Every page is reachable from the start page
+
+```rule
+id: pages-reachable
+scope: listing
+severity: error
+```
+
+- Every built page linked from the start page or a page it leads to; the listing checks only those.
+- Pages nobody should reach: out of the build. Reached otherwise on purpose: `<meta name="robots" content="noindex">`.
+- `404.html` at the root needs no link.
+- On a URL the checks visit at most 100 pages (hint); check the bundle for all.
+
+### `no-learner-data-in-texts`: Nothing about a particular learner in public texts
+
+```rule
+id: no-learner-data-in-texts
+scope: listing
+severity: error
+```
+
+- No name, class, school, grade, picture or other detail of a real learner in app, entry, README, plan or commit
+  message, even if the creator mentions one. Made-up names in exercises.
+
+### `correct-content-support`: Help keep the content correct
+
+```rule
+id: correct-content-support
+scope: listing
+severity: hint
+```
+
+- Computable answers: generate exercises, test answers with a checker.
+- Name a source for facts. Where it fits; never a listing condition.
+
+## Catalog entry
+
+- Listed by a pull request to <https://github.com/lernapps/apps>; steps: skill `lernapps-listing`.
+
+### `entry-from-schema`: Fill the entry from the published schema
+
+```rule
+id: entry-from-schema
+scope: listing
+severity: error
+```
+
+- Fetch the entry schema each time; never from memory or another app.
+- Every value from the creator's answers, the plan or the app; never invented.
+
+### `entry-links-resolve`: Every link of the entry resolves
+
+```rule
+id: entry-links-resolve
+scope: listing
+severity: error
+```
+
+- Each topic: path of an existing page, relative to the app's `url`; `<page>#<section>` names an element id there.
+- Check against the deployed app: `lernapps check --entry <file>`.
+
+### `entry-fitness-matches`: Fitness values as measured
+
+```rule
+id: entry-fitness-matches
+scope: listing
+severity: error
+```
+
+- `fitness.storage`, `fitness.thirdParty` from what the app does; `lernapps check --report <file>` measures it.
+- Anything in `localStorage` or `sessionStorage`, also what the app only reads on loading and keeps after an input (an
+  assistant chosen for the tutor, an answer being written) → `storage: device`; loads from another server after a click → `thirdParty: on-click`.

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

@@ -0,0 +1,39 @@
+---
+name: lernapps-commit
+description: Use in Commit, when you bring the branch of the first version or an increment into main - the history of main stays linear (one squash commit per piece of work, never a merge commit) and every message is a conventional commit with the sections Intent, Key changes, Dependencies and side effects.
+license: MIT
+---
+
+# Commits of a lernapps app
+
+## Linear history
+
+Bring a branch into `main` by squash: squash-merge its pull request, or `git switch main`, `git merge --squash <branch>`,
+`git commit`. One piece of work is one commit on `main`; never a merge commit. The commit message of the squash
+describes the whole piece of work, not the last step. When you merge yourself, you squash and write it.
+
+## Content from the plan
+
+Do not invent the message: take it from the current plan (`.vibe/plans/<NN>-<short name>.md`). Intent comes from
+"Goal", Key changes from "Key decisions" and the content method, Dependencies and side effects from "Notes". Write it
+in the creator's terms, short.
+
+## Message
+
+A conventional commit: `type(scope): summary` (`feat`, `fix`, `docs`, `refactor`, `test`, `chore`), imperative, under 72
+characters. Then this body, in the language of the repo's history. Say why and what behaves differently; never list
+files.
+
+```markdown
+## Intent
+
+What problem does it solve? What was the motivation to introduce this change?
+
+## Key changes
+
+The conceptual overview: how does the system behave differently now?
+
+## Dependencies and side effects
+
+Only if applicable: effects on other parts of the system.
+```

package/dist/skills/lernapps-content-growth/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: lernapps-content-growth
+description: Use in Plan of an increment that adds several competencies, chapters, pages, rounds or questions to a published lernapps.net app. How to cut the work into slices, one per competency, and which slices sub-agents can write in parallel without touching each other's files. For every archetype.
+license: MIT
+---
+
+# Content growth
+
+## One slice per competency
+
+Each slice is one Code task and ends in one commit:
+
+1. Competency: into the content guide, in its chapter, as "Ich kann …", with its Lehrplan unit where used.
+2. Content: a page or section (explainer), questions (quiz), in the guide's structure.
+3. Exercise: a pattern of the guide, varied. A new pattern goes into the guide in the same slice, with example and
+   data file.
+4. Entry topic: the page or section path into the plan's entry draft (`entry-links-resolve`).
+5. Check: `npx lernapps check` passes.
+6. Commit, guide changes included.
+
+- A new chapter or round: its slices in the order of the guide's procedure.
+- The procedure no longer fits → its fix is part of the slice that shows it (`app-content-matches`).
+
+## Parallel slices
+
+- No two agents change the same file.
+- Yours alone: the content guide, the plan, the shared files (explainer `src/app.yaml`, each `chapter.yaml`,
+  `src/data/`; quiz `src/quiz.json`).
+- A sub-agent's: one chapter (its pages, its own data file); in a quiz, the question drafts of one round.
+- Each sub-agent works in its own git worktree, branch and browser port. You merge one by one, add the shared parts
+  and run the check.
+- In Code, each sub-agent gets the brief `@lernapps/tooling/guidance/subagent-brief.md`, filled in. Write in Plan
+  which slices go to sub-agents.