@lernapps/tooling 0.0.1 → 0.1.1

package/skills/tooling/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/skills/tooling/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`.