@lernapps/tooling 0.4.0 → 0.5.0

package/dist/cli.mjs

@@ -74,7 +74,7 @@ function nodeMajorProblem(version = process.versions.node) {
 		severity: "warning"
 	};
 }
-const git$2 = (cwd, ...args) => {
+const git$3 = (cwd, ...args) => {
 	const result = spawnSync("git", args, {
 		cwd,
 		encoding: "utf8"
@@ -83,7 +83,7 @@ const git$2 = (cwd, ...args) => {
 };
 /** The folder of the cache and the lock: <git common dir>/lernapps, or undefined outside a repository. */
 function stateDir(cwd = ".") {
-	const common = git$2(cwd, "rev-parse", "--git-common-dir")?.trim();
+	const common = git$3(cwd, "rev-parse", "--git-common-dir")?.trim();
 	return common === void 0 || common === "" ? void 0 : join(resolve(cwd, common), "lernapps");
 }
 /**
@@ -92,11 +92,11 @@ function stateDir(cwd = ".") {
 */
 function cacheKey(cwd, parts, toolingVersion, env = process.env) {
 	if (env["CI"] !== void 0 && env["CI"] !== "" && env["CI"] !== "false") return { none: "CI checks every time" };
-	const top = git$2(cwd, "rev-parse", "--show-toplevel")?.trim();
+	const top = git$3(cwd, "rev-parse", "--show-toplevel")?.trim();
 	if (top === void 0) return { none: "not a git repository" };
-	const tree = git$2(cwd, "rev-parse", "--verify", "--quiet", "HEAD^{tree}")?.trim();
+	const tree = git$3(cwd, "rev-parse", "--verify", "--quiet", "HEAD^{tree}")?.trim();
 	if (tree === void 0 || tree === "") return { none: "no commit yet" };
-	const status = git$2(top, "status", "--porcelain", "--untracked-files=all");
+	const status = git$3(top, "status", "--porcelain", "--untracked-files=all");
 	if (status === void 0) return { none: "git status failed" };
 	if (status.trim() !== "") return { none: "the working tree has changes that are not committed" };
 	const variables = Object.keys(env).filter((name) => name.startsWith("LERNAPPS_")).sort().map((name) => `${name}=${env[name]}`);
@@ -878,7 +878,9 @@ In a repo (no <dir|url>):
                    .arc42ignore does not list; a hint to review an element under whose path code changed is a
                    warning. Before the first commit arc42 validate --strict
   --pre-push       the heavy part: in an app with an architecture arc42 validate --strict, unit tests, build (vp build for an app with index.html, else vp pack),
-                   checks of the built app in dist/, the Playwright tests when playwright.config.* exists,
+                   checks of the built app in dist/, of an explainer in format 2 its strand, page
+                   competencies, recap pages and prerequisites of other strands against the learning map
+                   (https://lernapps.net/apps/map/), the Playwright tests when playwright.config.* exists,
                    dependency licences, the lock file (the pre-push hook); a failure increments prePushFailures in the front
                    matter of the current plan (the highest number in .vibe/plans/, else .vibe/plan.md). A
                    failing generic test of the archetype's runtime (@lernapps/app-templates) is named as a test
@@ -1051,8 +1053,9 @@ details of a figure, such as where a line of a drawing points, in its own image.
 send images: the images are PNG files, and an index.html shows them all in page order with each page's title and path
 (one file, images relative, no network).
 
-The built app is <dir>, default dist/ (build it first). Its pages are those lernapps check visits; the start page
-comes first. Each is opened in Chromium, as a learner first sees it: nothing answered, no hover, animations off,
+The built app is <dir> (build it first); default dist/ (npx vp build, as lernapps check builds) or _site/ (npm run
+build), whichever has an index.html, the newer when both have one. Its pages are those lernapps check visits; the
+start page comes first. Each is opened in Chromium, as a learner first sees it: nothing answered, no hover, animations off,
 fonts and images loaded; requests to other hosts are blocked. A figure is a block figure or labelled-figure, or any
 other figure with an image or a drawing. It is cut out with its caption, at twice its size on screen, from the page
 as the build writes it, without JavaScript, so that the figures of every question of a quiz are there too; a figure
@@ -1318,24 +1321,24 @@ function loadRules(dir) {
 	};
 }
 const ZERO = /^0+$/;
-const git$1 = (cwd, ...args) => spawnSync("git", args, {
+const git$2 = (cwd, ...args) => spawnSync("git", args, {
 	cwd,
 	encoding: "utf8",
 	maxBuffer: 67108864
 });
 /** The paths of `git diff --name-only -z`; renames as a deletion and an addition, so both paths count. */
 function diffNames(cwd, ...args) {
-	const diff = git$1(cwd, "diff", "--name-only", "--no-renames", "-z", ...args);
+	const diff = git$2(cwd, "diff", "--name-only", "--no-renames", "-z", ...args);
 	if (diff.error || diff.status !== 0) return void 0;
 	return diff.stdout.split("\0").filter((path) => path !== "");
 }
-const isCommit = (cwd, rev) => git$1(cwd, "cat-file", "-e", `${rev}^{commit}`).status === 0;
+const isCommit = (cwd, rev) => git$2(cwd, "cat-file", "-e", `${rev}^{commit}`).status === 0;
 /**
 * What a new branch is compared with: its merge base with origin/main; when the remote has no main yet (the first push
 * of a new repo), the empty tree, so the branch adds everything it holds (nothing, for an empty start commit).
 */
 function newBranchBase(cwd, local) {
-	if (git$1(cwd, "rev-parse", "--verify", "--quiet", "origin/main").status !== 0) {
+	if (git$2(cwd, "rev-parse", "--verify", "--quiet", "origin/main").status !== 0) {
 		const empty = spawnSync("git", [
 			"hash-object",
 			"-t",
@@ -1352,7 +1355,7 @@ function newBranchBase(cwd, local) {
 		};
 	}
 	return {
-		base: git$1(cwd, "merge-base", local, "origin/main").stdout.trim(),
+		base: git$2(cwd, "merge-base", local, "origin/main").stdout.trim(),
 		tree: false
 	};
 }
@@ -1385,8 +1388,8 @@ function pushedFiles(lines, cwd = ".") {
 }
 /** Fetches the whole history once, when the clone is shallow (as actions/checkout makes it by default). */
 function unshallow(cwd) {
-	if (git$1(cwd, "rev-parse", "--is-shallow-repository").stdout.trim() !== "true") return false;
-	return git$1(cwd, "fetch", "--quiet", "--no-tags", "--unshallow", "origin").status === 0;
+	if (git$2(cwd, "rev-parse", "--is-shallow-repository").stdout.trim() !== "true") return false;
+	return git$2(cwd, "fetch", "--quiet", "--no-tags", "--unshallow", "origin").status === 0;
 }
 /**
 * The files between two commits: with `mergeBase`, what `head` adds to its merge base with `base` (a pull request);
@@ -1396,7 +1399,7 @@ function unshallow(cwd) {
 function rangeFiles(base, head, mergeBase, cwd = ".") {
 	const attempt = () => {
 		if (!isCommit(cwd, base) || !isCommit(cwd, head)) return void 0;
-		const from = mergeBase ? git$1(cwd, "merge-base", base, head).stdout.trim() : base;
+		const from = mergeBase ? git$2(cwd, "merge-base", base, head).stdout.trim() : base;
 		return from === "" ? void 0 : diffNames(cwd, from, head);
 	};
 	return attempt() ?? (unshallow(cwd) ? attempt() : void 0);
@@ -1658,7 +1661,8 @@ node_modules init wrote). From the installed package @lernapps/app-templates, th
 on, it writes the archetype's scaffold: the files of the template folder <name>/ that the package's lernapps.scaffold
 lists (the entry, the configuration, the end-to-end tests of the content) and a placeholder as start content
 (scaffold/<name>/), which the planned content replaces. The template folder itself is the example app: it stays in
-node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version.
+node_modules/@lernapps/app-templates/<name>/, to look up. The app depends on the runtime of the same version (or
+the same commit, while @lernapps/tooling depends on an unreleased one).
 
 It needs the plan of the first version, confirmed by the creator: started from the plan template as
 .vibe/plans/01-<short name>.md, the only plan there, worked through Explore and Plan, now in the phase code
@@ -1683,7 +1687,10 @@ publish action to the repo's GitHub Pages), an issue form for content errors, LI
 Renovate preset of lernapps). The installed skills and skills-lock.json are committed with the app, like the
 content guide; lernapps update replaces the lernapps-* skills.
 
-Then: git init (if <dir> is not a repository yet), npm install (installs the git hooks), and the first commit.
+It installs nothing and commits nothing. Its last lines say what to do next, in this order: git init
+--initial-branch=work (only if <dir> is not a repository yet; lernapps init made one), npm install (installs the
+runtime and the git hooks), git add -A and git commit (the first commit, on work; the hooks check it), then follow
+the plan.
 
 Exit codes: 0 when the app is written, 1 when it cannot be (the message says why), 2 on a usage error.
 
@@ -1693,8 +1700,8 @@ Options:
                       its file name <NN>-<short name>.md, else 01-plan.md (default: the one in <dir>)
   --templates <dir>   the package @lernapps/app-templates to copy from: its folder, or a clone of its repository
                       (default: the environment variable LERNAPPS_TEMPLATES, else the installed package)
-  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: ^ the version of this
-                      @lernapps/tooling)
+  --tooling <spec>    the npm spec of @lernapps/tooling the app depends on (default: the one lernapps init
+                      installed, else ^ the version of this @lernapps/tooling)
   -h, --help          print this help
 `;
 /** The generator cannot write the app; the message says why and what to do. */
@@ -1726,6 +1733,17 @@ function templatesPackage(dir) {
 		scaffold: manifest.lernapps?.scaffold ?? {}
 	};
 }
+/** The version of a package built from a commit, not released: its package.json in the repository says 0.0.0. */
+const UNRELEASED = "0.0.0";
+/**
+* The spec of the runtime an app depends on, for templates of `version`: ^ that version; for templates built from a
+* commit (version 0.0.0, which the registry does not have) the spec this tooling depends on, the same commit
+* (github:lernapps/app-templates#<commit>), so that template and runtime match.
+*/
+function runtimeSpec(version) {
+	if (version !== UNRELEASED) return `^${version}`;
+	return readJson(fromPackage("package.json")).dependencies?.["@lernapps/app-templates"] ?? `^${version}`;
+}
 /** The version of this package. */
 const ownVersion = () => readJson(fromPackage("package.json")).version ?? "0.0.0";
 /** The lock file of `npx skills add`, next to the skills it installed. */
@@ -1758,7 +1776,7 @@ function contents(dir) {
 		return [name];
 	});
 }
-function git(args, cwd) {
+function git$1(args, cwd) {
 	const result = spawnSync("git", args, {
 		cwd,
 		encoding: "utf8"
@@ -1792,6 +1810,8 @@ function writeScaffold(templates, archetype, dir) {
 	if (!existsSync(start)) throw new CreateError(`${templates.root} has no start content scaffold/${archetype}/`);
 	cpSync(start, dir, { recursive: true });
 }
+/** The branch the plan works on (rule 8 of the plan template). */
+const WORK_BRANCH = "work";
 /** This package, as an app depends on it. */
 const TOOLING = "@lernapps/tooling";
 /**
@@ -1957,7 +1977,7 @@ function create(args) {
 	};
 	if (app.devDependencies?.["@lernapps/app-templates"] !== void 0) app.devDependencies = {
 		...app.devDependencies,
-		[RUNTIME]: `^${templates.version}`
+		[RUNTIME]: runtimeSpec(templates.version)
 	};
 	const overrides = app["overrides"];
 	if (typeof overrides === "object" && overrides !== null && "@lernapps/app-templates" in overrides) {
@@ -1965,7 +1985,7 @@ function create(args) {
 		if (Object.keys(kept).length > 0) app["overrides"] = kept;
 		else delete app["overrides"];
 	}
-	const tooling = values.tooling ?? `^${ownVersion()}`;
+	const tooling = values.tooling ?? initialised?.devDependencies?.["@lernapps/tooling"] ?? `^${ownVersion()}`;
 	app.devDependencies = {
 		...app.devDependencies,
 		...ARCHETYPE_DEV_DEPENDENCIES[archetype],
@@ -1974,7 +1994,7 @@ function create(args) {
 	};
 	app.devDependencies = Object.fromEntries(Object.entries(app.devDependencies).sort(([a], [b]) => a.localeCompare(b)));
 	writeJson(join(dir, "package.json"), app);
-	const holder = git(["config", "user.name"], existsSync(dir) ? dir : process.cwd());
+	const holder = git$1(["config", "user.name"], existsSync(dir) ? dir : process.cwd());
 	const moved = resolve(plan.file) === resolve(join(dir, LEGACY_PLAN));
 	writePlan(dir, plan);
 	writeAppFiles(dir, {
@@ -1987,7 +2007,13 @@ function create(args) {
 		`lernapps create: the ${archetype} app ${name} in ${dir} (app-templates ${templates.version})`,
 		...guide.map((line) => `Content guide: ${line}`),
 		...moved ? [`Plan: moved ${LEGACY_PLAN} to ${relative(dir, plan.target)}`] : [],
-		`Next: ${existsSync(join(dir, ".git")) ? "" : "git init, "}npm install, then follow ${relative(dir, plan.target)}`,
+		"Next, in this order (create installs and commits nothing):",
+		...[
+			...existsSync(join(dir, ".git")) ? [] : [`git init --initial-branch=${WORK_BRANCH}`],
+			"npm install (the runtime and the git hooks)",
+			"git add -A, then git commit (the first commit; the hooks check it)",
+			`follow ${relative(dir, plan.target)}`
+		].map((step, index) => `  ${index + 1}. ${step}`),
 		""
 	].join("\n"));
 	return 0;
@@ -1996,17 +2022,19 @@ function create(args) {
 /** The options of `lernapps init`, as node:util parseArgs takes them. */
 const INIT_OPTIONS = {
 	addon: { type: "string" },
+	tooling: { type: "string" },
 	help: {
 		type: "boolean",
 		short: "h",
 		default: false
 	}
 };
-const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>]
+const INIT_USAGE = `Usage: lernapps init <short name> [--addon <package>] [--tooling <spec>]
 
 Starts an app in the current folder, which must be empty except for .git. It needs git, Node and the npm registry; nothing
 else. In order:
-  git repository               on the branch work, which the plan names (unless the folder is one already; no commit)
+  git repository               on the branch work, which the plan names; no commit. A repository without commits
+                                switches to work; one with commits stays, and init warns: git switch -c work
   package.json                  names the folder, depends on @lernapps/tooling (this version) and the add-on
   npm install                   installs them
   .vibe/plans/01-<short name>.md
@@ -2018,6 +2046,12 @@ Then follow the plan: it says what to do, and when to wait for the creator.
 
 Options:
   --addon <package>  a package that extends the tooling, e.g. @lernapps/practice: its plan template and its skills
+  --tooling <spec>   for maintainers: the npm spec of @lernapps/tooling to install instead of this version, e.g.
+                     file:/path/to/lernapps-tooling-0.0.0.tgz or github:lernapps/tooling#<commit>; give the same
+                     to lernapps create. Without it, a tooling of version 0.0.0 (a local build, not on the
+                     registry) is packed with npm pack into a temporary folder and installed from that tarball
+                     when its folder is a git checkout (file:<tarball>), with its dependencies, as from the
+                     registry
   -h, --help         print this help
 `;
 /** The options of `lernapps skills`. */
@@ -2044,25 +2078,57 @@ const SKILLS_BIN = () => {
 	const bin = readJson(manifest)["bin"];
 	return join(dirname(manifest), bin?.["skills"] ?? "bin/cli.mjs");
 };
-/** The branch the plan works on (rule 8 of the plan template). */
-const WORK_BRANCH = "work";
-/**
-* Makes the folder a git repository on the branch `work`, which the plan names, unless it is one already: `create` and
-* the hooks need it, and the plan's first rule is to work there. Returns what it did, for the output; no commit.
-*/
-function ensureRepository(dir) {
-	if (existsSync(join(dir, ".git"))) return void 0;
-	const result = spawnSync("git", [
-		"init",
-		"--quiet",
-		`--initial-branch=${WORK_BRANCH}`
-	], {
+/** A git command in `dir`; a git that cannot run is an error of init. */
+function git(dir, args) {
+	const result = spawnSync("git", args, {
 		cwd: dir,
 		encoding: "utf8"
 	});
 	if (result.error) throw new CreateError(`git cannot run: ${result.error.message}. Install git, then run init again`);
-	if (result.status !== 0) throw new CreateError(`git init failed: ${`${result.stdout}${result.stderr}`.trim()}`);
-	return `a git repository on the branch ${WORK_BRANCH}`;
+	return {
+		ok: result.status === 0,
+		out: `${result.stdout}${result.stderr}`.trim()
+	};
+}
+/**
+* Puts the folder on the branch `work`, which the plan names: `create` and the hooks need a repository, and the plan's
+* first rule is to work there. No repository yet → `git init` on `work`. A repository without commits (a fresh
+* `git init` on master or main, a clone of an empty GitHub repo) → its unborn branch becomes `work`: nothing is lost,
+* since there is nothing on it. A repository with commits on another branch is left as it is, with a warning that
+* names the command. No commit.
+*/
+function ensureRepository(dir) {
+	if (!existsSync(join(dir, ".git"))) {
+		const result = git(dir, [
+			"init",
+			"--quiet",
+			`--initial-branch=${WORK_BRANCH}`
+		]);
+		if (!result.ok) throw new CreateError(`git init failed: ${result.out}`);
+		return { done: `a git repository on the branch ${WORK_BRANCH}` };
+	}
+	const branch = git(dir, [
+		"symbolic-ref",
+		"--quiet",
+		"--short",
+		"HEAD"
+	]);
+	if (branch.ok && branch.out === "work") return {};
+	if (!git(dir, [
+		"rev-parse",
+		"--verify",
+		"--quiet",
+		"HEAD"
+	]).ok) {
+		const result = git(dir, [
+			"symbolic-ref",
+			"HEAD",
+			`refs/heads/${WORK_BRANCH}`
+		]);
+		if (!result.ok) throw new CreateError(`git could not switch to the branch ${WORK_BRANCH}: ${result.out}`);
+		return { done: `the repository had no commit yet: now on the branch ${WORK_BRANCH}` };
+	}
+	return { warning: `the repository has commits and is ${branch.ok ? `on the branch ${branch.out}` : "on no branch (detached HEAD)"}, not on ${WORK_BRANCH}, which the plan works on. Run next: git switch -c ${WORK_BRANCH}` };
 }
 /** The names of the skills of the archetypes, with the archetype each belongs to (lernapps-<archetype>[-…]). */
 function archetypeSkills() {
@@ -2101,6 +2167,37 @@ function syncSkills(dir, exclude) {
 		...filters.length > 0 ? ["--exclude", ...filters] : []
 	], (message) => new CreateError(message), dir);
 }
+/** The version of a build that is not on the registry: package.json of the repository says 0.0.0. */
+const LOCAL_VERSION = "0.0.0";
+/**
+* The tarball of the package in `root`, packed by npm pack (with its prepare script, so the build is current) into a
+* new temporary folder.
+*/
+function packBuild(root) {
+	const out = mkdtempSync(join(tmpdir(), "lernapps-tooling-"));
+	run("npm", [
+		"pack",
+		"--silent",
+		"--pack-destination",
+		out
+	], (message) => new CreateError(message), root);
+	const tarball = readdirSync(out).find((name) => name.endsWith(".tgz"));
+	if (tarball === void 0) throw new CreateError(`npm pack in ${root} wrote no tarball into ${out}`);
+	return join(out, tarball);
+}
+/**
+* The spec of @lernapps/tooling that init installs: the one given, else this version. A local build (version 0.0.0,
+* which the registry does not have) is packed when its folder is a git checkout and installed from the tarball, else
+* init says to name one with --tooling. Not the folder itself (file:<folder>): npm links it, so the app's
+* node_modules lacks the tooling's dependencies (Playwright for the end-to-end tests, @lernapps/app-templates with
+* the templates and their READMEs); from a tarball they are installed into the app, as from the registry.
+*/
+function toolingSpec(given, version = ownVersion(), root = fromPackage(), pack = packBuild) {
+	if (given !== void 0 && given !== "") return given;
+	if (version !== LOCAL_VERSION) return version;
+	if (existsSync(join(root, ".git"))) return `file:${pack(resolve(root))}`;
+	throw new CreateError(`this @lernapps/tooling is a local build (version ${LOCAL_VERSION}), which the npm registry does not have: name the tooling to install with --tooling <spec>, e.g. file:/path/to/lernapps-tooling-${LOCAL_VERSION}.tgz (npm pack) or github:lernapps/tooling#<commit>, and give the same to lernapps create`);
+}
 function init(args) {
 	const { values, positionals } = parseArgs({
 		args,
@@ -2118,6 +2215,7 @@ function init(args) {
 	const present = readdirSync(dir).filter((entry) => entry !== ".git");
 	if (present.length > 0) throw new CreateError(`${dir} is not empty (${present.slice(0, 5).join(", ")}${present.length > 5 ? ", ..." : ""}): start in a new, empty folder`);
 	const addon = values.addon;
+	const tooling = toolingSpec(values.tooling);
 	const repository = ensureRepository(dir);
 	writeJson(join(dir, "package.json"), {
 		name,
@@ -2131,7 +2229,7 @@ function init(args) {
 		"--save-dev",
 		"--no-audit",
 		"--no-fund",
-		`${TOOLING}@${ownVersion()}`,
+		`${TOOLING}@${tooling}`,
 		...addon ? [addon] : []
 	], fail);
 	const source = (packageName, ...path) => join(dir, "node_modules", packageName, ...path);
@@ -2144,7 +2242,8 @@ function init(args) {
 	mkdirSync(dirname(target), { recursive: true });
 	writeFileSync(target, readFileSync(template));
 	syncSkills(dir, archetypeSkills().map((skill) => skill.name));
-	process.stdout.write(`lernapps init: ${relative$1(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository ? `; ${repository}` : ""}\nNext: read ${relative$1(dir, target)} completely and follow it\n`);
+	if (repository.warning !== void 0) process.stderr.write(`lernapps init: warning: ${repository.warning}\n`);
+	process.stdout.write(`lernapps init: ${relative$1(dir, target)} from ${relativeTemplate(template, dir)}; the skills of the packages are installed${repository.done ? `; ${repository.done}` : ""}\nNext: ${repository.warning ? `git switch -c ${WORK_BRANCH}, then ` : ""}read ${relative$1(dir, target)} completely and follow it\n`);
 	return 0;
 }
 const relative$1 = (from, to) => to.startsWith(from) ? to.slice(from.length + 1) : to;
@@ -2182,13 +2281,16 @@ const UPDATE_USAGE = `Usage: lernapps update
 Moves the app in the current folder to the versions of this @lernapps/tooling, then runs npm install. npm update
 moves the app within its version ranges; this moves the ranges, and what npm does not know:
   @lernapps/app-templates  to the version this tooling depends on: the runtime its tests ran with. A newer version
-                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version
+                           (e.g. from Renovate) is kept. A git commit, as apps once pinned, becomes a version; while
+                           this tooling depends on a commit (an unreleased runtime), the app moves to that commit
   @lernapps/tooling        to the version of this tooling (unchanged when run from the app)
   .github/workflows/       the actions of lernapps/tooling at the tag of that version
   .agents/skills/app-content/SKILL.md
                            the content guide's skeleton, where the app has none yet (and its link for Claude Code)
   .vibe/plan.md            the plan of an app made before the plans had a folder: moved to
                            .vibe/plans/01-first-version.md, the first of its plans (one per piece of work)
+  src/app.yaml             of an explainer in format 1, when the runtime knows format 2: adds format: 2 and
+                           strand: none (the app is not on the learning map; its pages need no competencies)
   .agents/skills/lernapps-*, .claude/skills/lernapps-*, skills-lock.json
                            replaced with the skills of this tooling, as npx skills add lays them out: those of
                            every phase, and of the archetypes only those of the current plan's archetype; every
@@ -2222,9 +2324,11 @@ function lowest(range) {
 }
 /** Whether `a` is older than `b`. */
 const older = (a, b) => a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2];
-/** The next range of a dependency at `version`, and what the output says about it. */
-function nextRange(name, current, version) {
-	const target = `^${version}`;
+/**
+* The next range of a dependency at `version` (target: ^ that version, or the spec given, e.g. a git commit of an
+* unreleased runtime), and what the output says about it.
+*/
+function nextRange(name, current, version, target = `^${version}`) {
 	if (current !== void 0 && /^(file:|link:|\.{0,2}\/)/.test(current)) return {
 		spec: current,
 		line: `${name}: kept ${current}, a local copy`
@@ -2235,7 +2339,7 @@ function nextRange(name, current, version) {
 		spec: current,
 		line: `${name}: unchanged (${current})`
 	};
-	if (now !== void 0 && next !== void 0 && !older(now, next)) return {
+	if (lowest(target) !== void 0 && now !== void 0 && next !== void 0 && !older(now, next)) return {
 		spec: current ?? target,
 		line: `${name}: kept ${current}, not moved to ${target}: it is not older`
 	};
@@ -2269,6 +2373,30 @@ function migratePlan() {
 	renameSync(LEGACY_PLAN, MIGRATED_PLAN);
 	return [`plan: moved ${LEGACY_PLAN} to ${MIGRATED_PLAN}, unchanged: each piece of work has its own plan in .vibe/plans/`];
 }
+/** The explainer's app file, and the schema file that tells the runtime knows format 2 (learning map). */
+const EXPLAINER_APP = join("src", "app.yaml");
+const EXPLAINER_V2_SCHEMA = join("runtime", "explainer", "explainer.v2.schema.json");
+/**
+* Moves an explainer from format 1 to format 2 (the learning map): adds `format: 2` and `strand: none` to
+* src/app.yaml when the app has neither, and points its schema comment to explainer.v2.schema.json. `strand: none`
+* keeps the app off the map, so its pages need no competencies; the creator may name a strand later (skill
+* lernapps-content-research). Only where the runtime of this tooling has the v2 schema: an older runtime does not
+* know the fields. An app that is no explainer, or already has a `format` or a `strand`, stays as it is. What it did,
+* as lines of the output.
+*/
+function migrateExplainer(templatesRoot) {
+	if (!existsSync(EXPLAINER_APP) || !existsSync(join(templatesRoot, EXPLAINER_V2_SCHEMA))) return [];
+	const text = readFileSync(EXPLAINER_APP, "utf8");
+	const top = (key) => new RegExp(`^${key}:`, "m").test(text);
+	if (!top("chapters") || top("format") || top("strand")) return [];
+	const schema = /^(# yaml-language-server: \$schema=.*)explainer\.v1\.schema\.json$/m;
+	const fields = "format: 2\nstrand: none\n";
+	let next;
+	if (schema.test(text)) next = text.replace(schema, (_all, head) => `${head}explainer.v2.schema.json\n${fields.trimEnd()}`);
+	else next = fields + text;
+	writeFileSync(EXPLAINER_APP, next);
+	return [`explainer: ${EXPLAINER_APP} moved to format 2: added format: 2 and strand: none (not on the learning map; pages need no competencies). To join the map, pick a strand of https://lernapps.net/apps/map/ and give every page competencies`];
+}
 /**
 * The skills of this tooling, as it ships them (skills/<group>/<name>/), and as the app keeps them (flat, by name).
 * Every app has those of the groups process, tooling and content; of the group archetypes only those of its own
@@ -2477,7 +2605,7 @@ function update(args) {
 	const notMoved = [];
 	const runtime = devDependencies[RUNTIME];
 	if (runtime !== void 0) {
-		const next = nextRange(RUNTIME, runtime, templates.version);
+		const next = nextRange(RUNTIME, runtime, templates.version, runtimeSpec(templates.version));
 		if (next.spec !== runtime) specs.push(`${RUNTIME}@${next.spec}`);
 		lines.push(next.line);
 	}
@@ -2507,6 +2635,8 @@ function update(args) {
 	lines.push(...guide.map((line) => `content guide: ${line}`));
 	const plan = migratePlan();
 	lines.push(...plan);
+	const explainer = migrateExplainer(templates.root);
+	lines.push(...explainer);
 	const skills = [...replaceSkills(), ...unignoreSkills()];
 	lines.push(...skills);
 	const architecture = updateArchitecture();
@@ -2524,6 +2654,7 @@ function update(args) {
 	if (skillsMoved) files.push(SKILLS_LOCK);
 	if (skills.some((line) => line.includes(".gitignore"))) files.push(".gitignore");
 	if (architecture.lines.length > 0) files.push(`${ARCHITECTURE}/`);
+	if (explainer.length > 0) files.push(EXPLAINER_APP);
 	if (plan.some((line) => line.startsWith("plan: moved"))) files.push(".vibe/ (git add -A .vibe, to keep the move)");
 	process.stdout.write(`Next: npx --no -- lernapps check, then commit ${files.slice(0, -1).join(", ")} and ${files.at(-1) ?? ""}\n`);
 	return 0;
@@ -2659,6 +2790,13 @@ async function shootFigures(browser, base, page, width, file) {
 		return count;
 	});
 }
+/** Where an app's build is: dist/ (npx vp build, as lernapps check builds it) or _site/ (npm run build of the templates). */
+const BUILDS = ["dist", "_site"];
+const isBuild = (dir) => existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, "index.html"));
+/** The build to take without <dir>: of dist/ and _site/ the one with an index.html, the newer of both when both have one. */
+function defaultBundle() {
+	return BUILDS.filter((dir) => isBuild(dir)).sort((a, b) => statSync(join(b, "index.html")).mtimeMs - statSync(join(a, "index.html")).mtimeMs)[0] ?? "dist";
+}
 /**
 * Writes the images and the index.html. Everything that can fail before is checked before the folder is touched, so a
 * failed run writes nothing. Returns the line to print.
@@ -2673,8 +2811,9 @@ async function screenshots(args) {
 	if (positionals.length > 1) throw new UsageError(`one <dir> at most, not ${positionals.join(" ")}`);
 	if (!/^\d+$/.test(values.width) || Number(values.width) < 200 || Number(values.width) > 4e3) throw new UsageError(`--width ${values.width}: a number of pixels from 200 to 4000`);
 	const widths = [.../* @__PURE__ */ new Set([Number(values.width), ...values.desktop ? [DESKTOP] : []])];
-	const bundle = resolve(positionals[0] ?? "dist");
-	if (!existsSync(bundle) || !statSync(bundle).isDirectory() || !existsSync(join(bundle, "index.html"))) throw new UsageError(`${positionals[0] ?? "dist"}: not a directory with index.html (build the app first)`);
+	const named = positionals[0] ?? defaultBundle();
+	const bundle = resolve(named);
+	if (!isBuild(bundle)) throw new UsageError(positionals[0] === void 0 ? `neither ${BUILDS.map((dir) => `${dir}/`).join(" nor ")} has an index.html (build the app first: npx vp build writes dist/, npm run build _site/)` : `${named}: not a directory with index.html (build the app first)`);
 	const archetype = archetypeOf(readFileSync(join(bundle, "index.html"), "utf8"));
 	if (archetype === void 0 || !SUPPORTED.includes(archetype)) throw new ScreenshotsError(`screenshots support explainer and quiz, not ${archetype === void 0 ? "this app" : `the ${archetype} archetype`}`);
 	const out = resolve(values.out);

package/dist/explainer-map-DW4XCcY0.mjs

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { fileURLToPath, pathToFileURL } from "node:url";
+// check/explainer-map.ts
+/** The app's description, relative to its repo. */
+const APP_YAML = "src/app.yaml";
+/** The longest wait for a map: a check without network says it could not check, it never hangs. */
+const TIMEOUT = 1e4;
+const read = (file) => {
+	try {
+		return parse(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+};
+const ids = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+/** The 1-based line of the first top-level `key:` in `text`, or undefined. */
+function lineOf(text, ...keys) {
+	const index = text.split("\n").findIndex((line) => keys.some((key) => line.startsWith(`${key}:`)));
+	return index === -1 ? void 0 : index + 1;
+}
+/**
+* The explainer in format 2 in the repo `project`, or undefined when there is none: no src/app.yaml, or one without
+* `format: 2` (format 1, which has no strand), or one the build cannot read.
+*/
+function readExplainer(project) {
+	const appFile = join(project, APP_YAML);
+	if (!existsSync(appFile)) return void 0;
+	const app = read(appFile);
+	if (app?.format !== 2 || typeof app.strand !== "string") return void 0;
+	const pages = [];
+	for (const chapter of ids(app.chapters)) {
+		const chapterYaml = read(join(project, "src", chapter, "chapter.yaml"));
+		for (const page of ids(chapterYaml?.pages)) {
+			const file = `src/${chapter}/${page}.yaml`;
+			if (!existsSync(join(project, file))) continue;
+			const text = readFileSync(join(project, file), "utf8");
+			const value = read(join(project, file));
+			const competencies = typeof value?.competency === "string" ? [value.competency] : ids(value?.competencies);
+			const recap = typeof value?.recap === "string" ? value.recap : void 0;
+			const line = lineOf(text, "competencies", "competency") ?? (recap === void 0 ? void 0 : lineOf(text, "recap"));
+			pages.push({
+				where: line === void 0 ? file : `${file}:${line}`,
+				competencies,
+				...recap === void 0 ? {} : { recap },
+				text
+			});
+		}
+	}
+	const strandLine = lineOf(readFileSync(appFile, "utf8"), "strand");
+	return {
+		strand: app.strand,
+		strandAt: strandLine === void 0 ? APP_YAML : `${APP_YAML}:${strandLine}`,
+		pages
+	};
+}
+/** The strand of each competency of the map, by its id. */
+const strandsOf = (map) => new Map(map.strands.flatMap((strand) => strand.competencies.map((competency) => [competency.id, strand.id])));
+/** The address of a competency's page on the map, as a page links it: …/apps/map/<subject>/c/<id>/. */
+const competencyPage = (subject, id) => `https://lernapps.net/apps/map/${subject}/c/${id}/`;
+/**
+* The address of the map of `subject`. For tests only, not for users: LERNAPPS_TEST_MAP_URL replaces the base
+* (test/explainer-map.test.ts), an http(s) address, a `file:` URL or a local directory (absolute, or relative to the
+* current directory), so that a sandbox without a local server can test against a map on disk
+* (`<dir>/<subject>.json`). Not in the help.
+*/
+function mapUrl(subject, env = process.env) {
+	let base = env["LERNAPPS_TEST_MAP_URL"] ?? "https://lernapps.net/apps/map/";
+	if (!/^(?:https?|file):/i.test(base)) base = pathToFileURL(isAbsolute(base) ? base : resolve(base)).href;
+	return `${base.endsWith("/") ? base : `${base}/`}${subject}.json`;
+}
+const isMap = (value) => typeof value === "object" && value !== null && Array.isArray(value.strands) && value.strands.every((strand) => typeof strand?.id === "string" && Array.isArray(strand.competencies));
+/** The maps loaded in this run, by address: the checks of one run share one request per map. */
+const loaded = /* @__PURE__ */ new Map();
+/** The map at `url`, or why it could not be loaded: no network, a status other than 200, not a map. */
+function loadMap(url) {
+	let pending = loaded.get(url);
+	if (pending === void 0) {
+		pending = fetchMap(url);
+		loaded.set(url, pending);
+	}
+	return pending;
+}
+async function fetchMap(url) {
+	if (url.startsWith("file:")) return readMap(url);
+	let response;
+	try {
+		response = await fetch(url, {
+			redirect: "follow",
+			signal: AbortSignal.timeout(TIMEOUT)
+		});
+	} catch (error) {
+		return { failed: `${url} could not be reached (${error instanceof Error ? error.message : String(error)})` };
+	}
+	if (!response.ok) {
+		await response.body?.cancel();
+		return { failed: response.status === 404 ? `${url} does not exist (404): the subject has no map yet, or it is not the subject's id` : `${url} answers ${response.status}` };
+	}
+	let value;
+	try {
+		value = await response.json();
+	} catch {
+		return { failed: `${url} is not JSON` };
+	}
+	return isMap(value) ? { map: value } : { failed: `${url} is not the map of a subject (no strands)` };
+}
+/** The map in a local file (LERNAPPS_TEST_MAP_URL with a `file:` URL or a directory), read as fetchMap reads one. */
+function readMap(url) {
+	let text;
+	try {
+		text = readFileSync(fileURLToPath(url), "utf8");
+	} catch (error) {
+		return error.code === "ENOENT" ? { failed: `${url} does not exist: the subject has no map yet, or it is not the subject's id` } : { failed: `${url} could not be read (${error instanceof Error ? error.message : String(error)})` };
+	}
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return { failed: `${url} is not JSON` };
+	}
+	return isMap(value) ? { map: value } : { failed: `${url} is not the map of a subject (no strands)` };
+}
+export { strandsOf as a, readExplainer as i, loadMap as n, mapUrl as r, competencyPage as t };

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

@@ -39,7 +39,8 @@ The READMEs are files of the package `@lernapps/app-templates`, which `init` ins
 
 - 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
+- Before you choose, read the README of every archetype you consider, in full. One you rule out from the kind of
+  practice alone needs no README: say in one sentence why it does not fit. 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.