@ingenioz-it/caits 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (C) 2026 by Ingenioz IT
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# CAITS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CAITS (Clean Architecture In TypeScript) is the technical base of a Marko project with a backend and a frontend: a container for the dependencies, the message buses, the stores of the frontend, a Vite plugin and the test helpers. Its package is [`@ingenioz-it/caits`](https://www.npmjs.com/package/@ingenioz-it/caits), on npm.
+
+The documentation is on [caits.dev](https://caits.dev): start with [the docs](https://caits.dev/docs).
+
+## Quick start
+
+```sh
+npx @ingenioz-it/caits init my-app --example
+cd my-app && npm run check
+```
+
+`init` makes the project, then installs its packages and the browser of the end-to-end tests. With `--example`, the project is a small app that shows each layer and each kind of test; without it, the project has one empty page.
+
+## Requirements
+
+- Node.js 22 (22.18 or later), 24, or 26 and later.
+- git, for `init --example`: it gets the example with git.
+- Linux, macOS or WSL 2. Native Windows is not supported: CAITS starts npm and npx without a shell, and stops the servers of the checks by their group of processes.
+
+## Work on CAITS
+
+- To check CAITS, run `npm run check`: types, lint, tests and coverage. `npm run test:mutation` runs the mutation tests.
+- The example of `caits init --example` is not in this repository: it is in [IngeniozIT/caits-example](https://github.com/IngeniozIT/caits-example). `npm run test:template` takes it from the folder `../caits-example`: clone it there.
+- [CHANGELOG.md](CHANGELOG.md) tells the changes of each version.
+
+## Release a version
+
+1. Give the version in `package.json` (`npm version <version> --no-git-tag-version`) and in the title of its part of [CHANGELOG.md](CHANGELOG.md), then commit.
+2. Tag the same version in `caits-example`, and push the tag: CAITS `v0.5.0` writes the example of the tag `v0.5.0`.
+3. Push the tag of CAITS (`git tag v0.5.0 && git push origin v0.5.0`). The workflow [Release](.github/workflows/release.yml) runs the checks, then stages the version on npm: npm trusts this workflow, so the repository keeps no token. The workflow skips a version that npm has already.
+4. Make the version public, with the second factor of the npm account: `npm stage list @ingenioz-it/caits`, then `npm stage approve <id>`.
+
+## License
+
+[0BSD](LICENSE): use, copy, change and share this code for any purpose, without asking, and without keeping this notice.

package/bin/caits.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// The command of CAITS. Without installing CAITS first: npx @ingenioz-it/caits init my-app
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { defaultsVersions, DEFAULTS_FOLDER, EXAMPLE_SOURCE, init, install, otherVersions, SOURCE, update, VERSION } from "./init.js";
+
+const USAGE = `Usage: caits <command>
+
+  init [folder]        Makes a CAITS project in the folder, or adds CAITS to the project in it (the current folder if you give
+                       none: it must have a package.json). It writes only the files that the project does not have, and adds to
+                       package.json only the values that it does not have. Then it installs the packages and the browser of the
+                       end-to-end tests.
+    --example          Write a small app instead of an empty page: a menu, and a page where the user adds, edits and removes
+                       messages, which the backend keeps in tmp/messages.json. Each layer and each kind of test is there. The
+                       app is not in CAITS: git gets it from ${EXAMPLE_SOURCE}
+    --example-source <source>
+                       Write the example of this source: a git repository, with # and a tag or a branch, or a folder.
+    --caits <source>   Where npm gets CAITS. Default: ${SOURCE}
+    --no-install       Write the files, but install nothing.
+  update               Writes the defaults of the installed CAITS in ${DEFAULTS_FOLDER}/. Run it after you install another version.
+  dev                  Starts the development server.
+  check <script>…      Runs the npm scripts of the checks at once. Shows the output of the checks that fail, and only theirs.
+  architecture         Checks the rules of quality/architecture.mjs.
+  e2e                  Runs the end-to-end tests on the production build.
+  mutation-summary     Gives the mutation score of each file (--survivors: the mutants that survived).
+  mutation-suite       The unit tests, as Stryker runs them for each mutant.
+
+  --help, -h           Shows this help, also after a command (caits init --help).
+  --version            Shows the version of CAITS.`;
+
+/** The commands that run a tool of quality/: their code is in the folder quality/ of CAITS. */
+const TOOLS = new Set(["dev", "check", "architecture", "e2e", "mutation-summary", "mutation-suite"]);
+
+/** The options of `caits init`. */
+const INIT_OPTIONS = /** @type {const} */ ({ caits: { type: "string" }, example: { type: "boolean" }, "example-source": { type: "string" }, "no-install": { type: "boolean" } });
+
+/** A command, an option or an argument that CAITS does not take: CAITS says why, then where to read the usage. */
+class UsageError extends Error {}
+
+/** @type {(count: number, noun: string) => string} */
+const count = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+
+/** A folder as the shell reads it: in quotes when it has a space or another special character. */
+const shellQuote = (/** @type {string} */ text) => /^[\w@%+=:,./-]+$/.test(text) ? text : `'${text.replaceAll("'", "'\\''")}'`;
+
+const [command, ...rest] = process.argv.slice(2);
+
+try {
+  const status = await main(command, rest);
+  if (typeof status === "number") process.exitCode = status;
+} catch (error) {
+  // A known problem has a message that tells what to do: the stack of the code of CAITS does not help.
+  console.error(error instanceof Error ? error.message : error);
+  if (error instanceof UsageError) console.error("Run `caits --help`.");
+  process.exitCode = 1;
+}
+
+/**
+ * Runs a command. Gives its exit code, or nothing when it keeps running (the development server).
+ * @param {string | undefined} command
+ * @param {string[]} args
+ * @returns {Promise<number | void>}
+ */
+async function main(command, args) {
+  if (command === undefined) {
+    console.error(USAGE);
+    return 1;
+  }
+  if (command === "--version") {
+    console.log(VERSION);
+    return 0;
+  }
+  if ([command, ...args].some(arg => arg === "--help" || arg === "-h")) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (command === "init") return runInit(args);
+  if (command === "update") return runUpdate(args);
+  if (TOOLS.has(command)) {
+    if (command !== "mutation-suite") warnOfOldDefaults(process.cwd());
+    // The tools load Vite, Marko and the other packages of the project: only the command that runs imports its code.
+    const tool = /** @type {{ run: (args: string[]) => Promise<number | void> }} */ (await importTool(command));
+    return tool.run(args);
+  }
+  throw new UsageError(command.startsWith("-") ? `Unknown option: ${command}.` : `Unknown command: ${command}.`);
+}
+
+/**
+ * @param {string} name
+ * @returns {Promise<unknown>}
+ */
+function importTool(name) {
+  return import(new URL(`../quality/${name}.mjs`, import.meta.url).href);
+}
+
+/**
+ * The options and the other arguments of a command. An option that the command does not know, an option without its value, or with
+ * a value that it does not take, is a UsageError.
+ * @param {string[]} args
+ * @param {Record<string, { type: "string" | "boolean" }>} options
+ */
+function parseOptions(args, options) {
+  const { values, positionals, tokens } = parseArgs({ args, options, allowPositionals: true, strict: false, tokens: true });
+  for (const token of tokens) {
+    if (token.kind !== "option") continue;
+    const type = options[token.name]?.type;
+    if (!type) throw new UsageError(`Unknown option: ${token.rawName}.`);
+    const value = token.inlineValue ? token.value : token.value?.startsWith("-") ? undefined : token.value;
+    if (type === "string" && value === undefined) throw new UsageError(`The option ${token.rawName} needs a value: ${token.rawName} <value>.`);
+    if (type === "boolean" && token.value !== undefined) throw new UsageError(`The option ${token.rawName} takes no value.`);
+  }
+  return { values, positionals };
+}
+
+/**
+ * `caits init [folder]`.
+ * @param {string[]} args
+ * @returns {number}
+ */
+function runInit(args) {
+  const { values, positionals } = parseOptions(args, INIT_OPTIONS);
+  const options = /** @type {{ caits?: string; example?: boolean; "example-source"?: string; "no-install"?: boolean }} */ (values);
+  if (positionals.length > 1) throw new UsageError(`init takes one folder, not ${positionals.length}: ${positionals.join(" ")}.`);
+  if (positionals.length === 0 && !existsSync("package.json")) {
+    console.error("This folder has no package.json. Give the folder of the new project (`caits init my-app`), or `caits init .` to use this folder.");
+    return 1;
+  }
+  const root = resolve(positionals[0] ?? ".");
+  const example = options["example-source"] ?? (options.example ? EXAMPLE_SOURCE : undefined);
+  const withInstall = !options["no-install"];
+  console.log(`CAITS ${VERSION}: ${root}\n`);
+  if (example) console.log(`The example: ${example}\n`);
+  const { written, kept, ignored, values: keptValues } = init(root, options.caits, { example });
+  console.log(`Wrote ${count(written.length, "file")}. CAITS owns those of ${DEFAULTS_FOLDER}/: the others are yours.`);
+  if (kept.length > 0) {
+    console.log(`Kept ${count(kept.length, "file")} that the project has already: ${kept.join(", ")}.`);
+    console.log("  Compare them with those of node_modules/@ingenioz-it/caits/template/project/ (without the dot at the start of the name).");
+  }
+  if (ignored.length > 0) console.log(`Added to .gitignore: ${ignored.join(" ")}`);
+  if (keptValues.length > 0) {
+    console.log("Kept the values that package.json has already:");
+    for (const { key, project, caits } of keptValues) console.log(`  ${key}: ${JSON.stringify(project)} (CAITS: ${JSON.stringify(caits)})`);
+  }
+
+  const cd = relative(process.cwd(), root);
+  const steps = [...(cd ? [`cd ${shellQuote(cd)}`] : []), ...(withInstall ? [] : ["npm install", "npx playwright install chromium"])];
+  if (withInstall && !install(root)) {
+    console.error("\nThe installation failed. Correct the problem, then run the same command again: it keeps the files that it wrote.");
+    return 1;
+  }
+  console.log("\nNext:");
+  for (const step of [...steps, "npm run dev      starts the app on http://localhost:3000", "npm run check    runs all the checks"]) console.log(`  ${step}`);
+  return 0;
+}
+
+/**
+ * `caits update`.
+ * @param {string[]} args
+ * @returns {number}
+ */
+function runUpdate(args) {
+  if (args.length > 0) throw new UsageError(`update takes no argument: ${args.join(" ")}.`);
+  const written = update(process.cwd());
+  console.log(`CAITS ${VERSION}: wrote ${count(written.length, "file")} in ${DEFAULTS_FOLDER}/.`);
+  printOtherVersions(process.cwd());
+  return 0;
+}
+
+/** @param {string} root */
+function printOtherVersions(root) {
+  const others = otherVersions(root);
+  if (others.length === 0) return;
+  console.log(`CAITS ${VERSION} suggests other versions of these packages. Change them in package.json if you agree:`);
+  for (const { key, project, caits } of others) console.log(`  ${key}: ${JSON.stringify(project)} (CAITS suggests ${JSON.stringify(caits)})`);
+}
+
+/** @param {string} root */
+function warnOfOldDefaults(root) {
+  const versions = defaultsVersions(root);
+  if (versions.length === 1 && versions[0] === VERSION) return;
+  const from = versions.length === 0 ? "is missing" : `comes from CAITS ${versions.join(", ")}`;
+  console.warn(`Warning: ${DEFAULTS_FOLDER}/ ${from}, but CAITS ${VERSION} is installed. Run \`npx caits update\`.\n`);
+}

package/bin/init.js

@@ -0,0 +1,359 @@
+// JavaScript, not TypeScript: npx runs this file from node_modules, where Node strips no types. TypeScript checks the types of the comments.
+import { spawnSync } from "node:child_process";
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** @typedef {{ [key: string]: unknown }} PackageJson */
+/** @typedef {{ [name: string]: string }} Section */
+/** @typedef {{ dependencies?: Section; devDependencies?: Section }} Packages */
+/** @typedef {{ key: string; project: unknown; caits: string }} KeptValue */
+/** @typedef {{ written: string[]; kept: string[]; ignored: string[]; values: KeptValue[] }} Report */
+
+/**
+ * @param {URL | string} file
+ * @returns {unknown}
+ */
+const readJson = file => JSON.parse(readFileSync(file, "utf8"));
+
+/**
+ * A package.json: its object, or an error that names the file and tells what is wrong.
+ * @param {string} file
+ * @returns {PackageJson}
+ */
+function readPackage(file) {
+  const text = readFileSync(file, "utf8");
+  /** @type {unknown} */
+  let project;
+  try {
+    project = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON: ${/** @type {SyntaxError} */ (error).message}`, { cause: error });
+  }
+  if (typeof project !== "object" || project === null || Array.isArray(project)) throw new Error(`${file} is not valid: it must hold an object.`);
+  return /** @type {PackageJson} */ (project);
+}
+
+/**
+ * Why a command cannot start: most often, it is not installed.
+ * @param {string} command
+ * @param {Error} error
+ */
+const notStarted = (command, error) => "code" in error && error.code === "ENOENT" ? `${command} is not installed, or is not in the PATH` : `${command} cannot start: ${error.message}`;
+
+const OWN_PACKAGE = /** @type {{ version: string; devDependencies: Section }} */ (readJson(new URL("../package.json", import.meta.url)));
+
+/** The version of CAITS, and where npm gets it: the npm registry, this version or a later one with the same minor version. */
+export const VERSION = OWN_PACKAGE.version;
+export const SOURCE = `^${VERSION}`;
+
+/**
+ * The files of the project: `init` writes them once, and never changes them after. The files of quality/ import the defaults of CAITS and
+ * change them. Then comes the code: a first page (empty/), or the example.
+ * npm leaves `.gitignore` out of a package: the template names the dotfiles without their dot. It names AGENTS.md without its extension:
+ * an AI agent at work on CAITS would take it for the instructions of the folder template/project/.
+ */
+const PROJECT_FILES = fileURLToPath(new URL("../template/project/", import.meta.url));
+const EMPTY = fileURLToPath(new URL("../template/empty/", import.meta.url));
+/** The files of the template that the project names otherwise. */
+const NAMES = new Map([["gitignore", ".gitignore"], ["nvmrc", ".nvmrc"], ["AGENTS", "AGENTS.md"]]);
+
+/**
+ * The example, a small app that shows each layer, is not in the package of CAITS: `init --example` gets it from its repository, at the
+ * tag of this version, with git over HTTPS: a public repository needs no SSH key. A source is a git repository, with `#` and a tag or a
+ * branch, or a folder.
+ * `init` takes the files of its folders src/ and test/, and the packages of its package.json.
+ */
+export const EXAMPLE_SOURCE = `https://github.com/IngeniozIT/caits-example.git#v${VERSION}`;
+const EXAMPLE_FOLDERS = ["src", "test"];
+
+/** The defaults of CAITS: `init` and `update` write them in quality/caits/. CAITS owns this folder: `update` replaces it. */
+const DEFAULTS = fileURLToPath(new URL("../template/caits/", import.meta.url));
+export const DEFAULTS_FOLDER = "quality/caits";
+/** @param {string} version */
+const headerOf = version => `// CAITS ${version} wrote this file. Do not change it: \`npx caits update\` writes it again. Change the file of the project that uses it.\n`;
+const HEADER = /^\/\/ CAITS (\S+) wrote this file\./;
+
+/** What CAITS adds to the package.json of a project. The scripts run the tools with the configuration files of quality/. */
+const PACKAGE = {
+  type: "module",
+  imports: {
+    "#backend/*": "./src/backend/*",
+    "#frontend/*": "./src/frontend/*"
+  },
+  engines: {
+    node: "^22.18.0 || ^24.0.0 || >=26.0.0"
+  },
+  scripts: {
+    dev: "caits dev",
+    build: "marko-run build --config quality/vite.config.ts",
+    start: "node dist/index.mjs",
+    typecheck: "npm run build && mtc",
+    lint: "npm run lint:code && npm run lint:architecture",
+    "lint:code": "eslint --config quality/eslint.config.js .",
+    "lint:architecture": "caits architecture",
+    test: "vitest run --config quality/vite.config.ts",
+    "test:unit": "vitest run --config quality/vite.config.ts --exclude '**/infra/**/*.test.ts' --exclude '**/*.integration.test.ts'",
+    "test:contracts": "vitest run --config quality/vite.config.ts /infra/",
+    "test:integration": "vitest run --config quality/vite.config.ts .integration.test.ts",
+    "test:e2e": "caits e2e",
+    "test:coverage": "vitest run --config quality/vite.config.ts --coverage --reporter=default --reporter=@ingenioz-it/caits/quality/test-docs/vitest-reporter",
+    "test:mutation": "stryker run quality/stryker.config.mjs && caits mutation-summary",
+    tdd: "vitest --config quality/vite.config.ts",
+    check: "caits check typecheck lint:code lint:architecture test:coverage test:mutation test:e2e"
+  }
+};
+
+/** The packages that a project needs. CAITS suggests the versions that it uses itself: those of its own devDependencies. */
+const TOOLS = {
+  dependencies: ["@marko/run", "marko"],
+  devDependencies: [
+    "@eslint/js", "@marko/compiler", "@marko/type-check", "@playwright/test", "@stryker-mutator/core", "@stryker-mutator/typescript-checker",
+    "@types/node", "@vitest/coverage-v8", "eslint", "happy-dom", "sass", "typescript", "typescript-eslint", "vite", "vitest"
+  ]
+};
+/** @param {string[]} names */
+const versionsOf = names => Object.fromEntries(names.map(name => [name, OWN_PACKAGE.devDependencies[name] ?? "*"]));
+export const SUGGESTED = { dependencies: versionsOf(TOOLS.dependencies), devDependencies: versionsOf(TOOLS.devDependencies) };
+
+const DEPENDENCY_KEYS = new Set(["dependencies", "devDependencies"]);
+
+/**
+ * Makes a CAITS project in `root`, or adds CAITS to the project in it: writes the files of the project, with a first page or, with
+ * `example` (its source), the example; the defaults of CAITS (quality/caits/); the folders of the contexts; and adds to package.json what
+ * CAITS needs (`caits` is where npm gets CAITS), and the packages of the example. A file or a value that the project has already stays as
+ * it is: the report tells it. The lines of the template that .gitignore does not have go at its end. `init` installs nothing. When it
+ * cannot read the package.json of the project, or get the example, it throws, and writes nothing.
+ * @param {string} root
+ * @param {string} [caits]
+ * @param {{ example?: string }} [options]
+ * @returns {Report}
+ */
+export function init(root, caits = SOURCE, { example } = {}) {
+  const manifest = join(root, "package.json");
+  const project = existsSync(manifest) ? readPackage(manifest) : { name: nameOf(root), private: true };
+  const code = example === undefined ? { folder: EMPTY, files: filesOf(EMPTY), packages: {}, remove() {} } : getExample(example);
+  try {
+    mkdirSync(root, { recursive: true });
+    /** @type {Report} */
+    const report = { written: [], kept: [], ignored: [], values: [] };
+    for (const { folder, files } of [{ folder: PROJECT_FILES, files: filesOf(PROJECT_FILES) }, code]) {
+      for (const file of files) {
+        const path = NAMES.get(file) ?? file;
+        const target = join(root, path);
+        if (path === ".gitignore" && existsSync(target)) report.ignored = addMissingLines(target, readFileSync(join(folder, file), "utf8"));
+        else if (existsSync(target)) report.kept.push(path);
+        else {
+          mkdirSync(dirname(target), { recursive: true });
+          copyFileSync(join(folder, file), target);
+          report.written.push(path);
+        }
+      }
+    }
+    report.written.push(...update(root));
+    for (const side of ["backend", "frontend"]) mkdirSync(join(root, "src", side), { recursive: true });
+    report.values = addToPackage(manifest, project, caits, code.packages);
+    return report;
+  } finally {
+    code.remove();
+  }
+}
+
+/**
+ * The example of a source: its folder, the files of its folders src/ and test/, and the packages of its package.json. A git source is
+ * cloned in a temporary folder: `remove` removes it, and an example that CAITS cannot read removes it at once.
+ * @param {string} source
+ * @returns {{ folder: string; files: string[]; packages: Packages; remove: () => void }}
+ */
+function getExample(source) {
+  const local = existsSync(source) && statSync(source).isDirectory();
+  const folder = local ? source : cloneExample(source);
+  const remove = () => { if (!local) rmSync(folder, { recursive: true, force: true }); };
+  try {
+    if (!existsSync(join(folder, "src"))) throw new Error(`${source} is not an example of CAITS: it has no folder src/.`);
+    const files = EXAMPLE_FOLDERS.filter(name => existsSync(join(folder, name))).flatMap(name => filesOf(join(folder, name)).map(file => `${name}/${file}`));
+    const manifest = join(folder, "package.json");
+    const project = existsSync(manifest) ? readPackage(manifest) : {};
+    const packages = { dependencies: sectionOf(project, "dependencies"), devDependencies: sectionOf(project, "devDependencies") };
+    return { folder, files, packages, remove };
+  } catch (error) {
+    remove();
+    throw error;
+  }
+}
+
+/**
+ * Clones a git source (a repository, then `#` and a tag or a branch) in a temporary folder, without its history. Gives the folder.
+ * @param {string} source
+ * @returns {string}
+ */
+function cloneExample(source) {
+  const hash = source.lastIndexOf("#");
+  const [repository, ref] = hash === -1 ? [source, undefined] : [source.slice(0, hash), source.slice(hash + 1)];
+  const folder = mkdtempSync(join(tmpdir(), "caits-example-"));
+  const args = ["clone", "--quiet", "--depth", "1", ...(ref ? ["--branch", ref] : []), "--", repository, folder];
+  const result = spawnSync("git", args, { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] });
+  if (result.status !== 0) {
+    rmSync(folder, { recursive: true, force: true });
+    if (result.error) throw new Error(`${notStarted("git", result.error)}: init needs it to get the example from ${source}.`);
+    throw new Error(`git cannot get the example from ${source}:\n${result.stderr}`);
+  }
+  return folder;
+}
+
+/**
+ * Writes the defaults of this version of CAITS in quality/caits/, in place of those that are there. Gives the files written.
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function update(root) {
+  const folder = join(root, DEFAULTS_FOLDER);
+  rmSync(folder, { recursive: true, force: true });
+  mkdirSync(folder, { recursive: true });
+  return filesOf(DEFAULTS).map(file => {
+    writeFileSync(join(folder, file), headerOf(VERSION) + readFileSync(join(DEFAULTS, file), "utf8"));
+    return `${DEFAULTS_FOLDER}/${file}`;
+  });
+}
+
+/**
+ * The versions of CAITS that wrote the files of quality/caits/: one version when they come from one update, none when there is no file.
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function defaultsVersions(root) {
+  const folder = join(root, DEFAULTS_FOLDER);
+  if (!existsSync(folder)) return [];
+  const versions = filesOf(folder).map(file => HEADER.exec(readFileSync(join(folder, file), "utf8"))?.[1] ?? "unknown");
+  return [...new Set(versions)];
+}
+
+/**
+ * The packages whose version in package.json is not the one that CAITS suggests. CAITS does not change them: the project chooses.
+ * @param {string} root
+ * @returns {KeptValue[]}
+ */
+export function otherVersions(root) {
+  const file = join(root, "package.json");
+  if (!existsSync(file)) return [];
+  const project = readPackage(file);
+  return Object.values(SUGGESTED).flatMap(section => Object.entries(section).flatMap(([name, caits]) => {
+    const current = dependencyOf(project, name);
+    return current !== undefined && current !== caits ? [{ key: name, project: current, caits }] : [];
+  }));
+}
+
+/**
+ * Installs the packages of package.json, then the browser of the end-to-end tests. Gives false when a command fails.
+ * @param {string} root
+ * @returns {boolean}
+ */
+export function install(root) {
+  return run("npm", ["install"], root) && run("npx", ["playwright", "install", "chromium"], root);
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {string} cwd
+ */
+function run(command, args, cwd) {
+  console.log(`\n> ${[command, ...args].join(" ")}`);
+  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  if (result.error) console.error(`${notStarted(command, result.error)}.`);
+  return result.status === 0;
+}
+
+/**
+ * The files of a folder and of its sub-folders, from the folder, with "/" on every system. A symbolic link stops the reading: a link in
+ * an example could copy any file of the computer into the project.
+ * @param {string} folder
+ * @returns {string[]}
+ */
+function filesOf(folder) {
+  return readdirSync(folder, { recursive: true, withFileTypes: true })
+    .filter(entry => {
+      if (entry.isSymbolicLink()) throw new Error(`${join(entry.parentPath, entry.name)} is a symbolic link: CAITS copies no link. Remove it, or put the file in its place.`);
+      return entry.isFile();
+    })
+    .map(entry => relative(folder, join(entry.parentPath, entry.name)).split(sep).join("/"))
+    .sort();
+}
+
+/**
+ * Adds at the end of a file the lines of `text` that it does not have, comments and empty lines aside. Gives the added lines.
+ * @param {string} file
+ * @param {string} text
+ * @returns {string[]}
+ */
+function addMissingLines(file, text) {
+  const present = new Set(readFileSync(file, "utf8").split("\n").map(line => line.trim()));
+  const missing = text.split("\n").map(line => line.trim()).filter(line => line !== "" && !line.startsWith("#") && !present.has(line));
+  if (missing.length > 0) appendFileSync(file, `\n# CAITS\n${missing.join("\n")}\n`);
+  return missing;
+}
+
+/**
+ * Adds to a package.json (written when the project has none) the values that CAITS needs and that it does not have, and the packages
+ * with the versions that CAITS suggests, then those of the example. A package is present when the dependencies or the devDependencies
+ * name it. Gives the values that the project has already, and that differ.
+ * @param {string} file
+ * @param {PackageJson} project the values of the file, or those of a new project
+ * @param {string} caits
+ * @param {Packages} example
+ * @returns {KeptValue[]}
+ */
+function addToPackage(file, project, caits, example) {
+  const dependencies = { ...SUGGESTED.dependencies, ...example.dependencies };
+  const devDependencies = { "@ingenioz-it/caits": caits, ...SUGGESTED.devDependencies, ...example.devDependencies };
+  const wanted = { ...PACKAGE, dependencies, devDependencies };
+  /** @type {KeptValue[]} */
+  const kept = [];
+  for (const [key, value] of Object.entries(wanted)) {
+    const present = project[key];
+    if (typeof value === "string") {
+      if (present === undefined) project[key] = value;
+      else if (present !== value) kept.push({ key, project: present, caits: value });
+      continue;
+    }
+    for (const [name, item] of Object.entries(value)) {
+      const current = DEPENDENCY_KEYS.has(key) ? dependencyOf(project, name) : sectionOf(project, key)?.[name];
+      if (current === undefined) project[key] = { ...sectionOf(project, key), [name]: item };
+      else if (current !== item) kept.push({ key: `${key}.${name}`, project: current, caits: item });
+    }
+  }
+  for (const key of DEPENDENCY_KEYS) {
+    const section = sectionOf(project, key);
+    if (section) project[key] = Object.fromEntries(Object.entries(section).sort(([a], [b]) => a.localeCompare(b)));
+  }
+  writeFileSync(file, `${JSON.stringify(project, null, 2)}\n`);
+  return kept;
+}
+
+/**
+ * @param {PackageJson} project
+ * @param {string} key
+ * @returns {Section | undefined}
+ */
+function sectionOf(project, key) {
+  const section = project[key];
+  return typeof section === "object" && section !== null ? /** @type {Section} */ (section) : undefined;
+}
+
+/**
+ * The version of a package in the dependencies or the devDependencies of a project.
+ * @param {PackageJson} project
+ * @param {string} name
+ */
+function dependencyOf(project, name) {
+  return sectionOf(project, "dependencies")?.[name] ?? sectionOf(project, "devDependencies")?.[name];
+}
+
+/**
+ * The name of a new package: the name of its folder, as npm accepts it.
+ * @param {string} folder
+ */
+function nameOf(folder) {
+  return basename(folder).toLowerCase().replace(/[^a-z0-9._~-]+/g, "-").replace(/^[._-]+/, "") || "app";
+}