inferative 0.0.0 → 0.1.0

package/dist/init-command-C2q2dkCV.mjs

@@ -0,0 +1,878 @@
+import { createRequire } from "node:module";
+import { defineCommand } from "citty";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { installDependencies } from "nypm";
+import { x } from "tinyexec";
+import { cp, mkdir, readFile, readdir, rm, rmdir, stat, writeFile } from "node:fs/promises";
+//#region src/cli-version.ts
+/** The version in this package's own `package.json`. */
+var CliVersion = class {
+	/** The version. citty throws on `--version` without one. */
+	static current() {
+		return createRequire(import.meta.url)("../package.json").version;
+	}
+	/**
+	* The `major.minor` part of a version, which names the branch of the starters repository.
+	*
+	* @param version - A version such as `0.1.0` or `0.2.0-snapshot.20261009`.
+	*/
+	static minor(version) {
+		const [major = "0", minor = "0"] = version.split(".");
+		return `${major}.${minor}`;
+	}
+};
+//#endregion
+//#region src/error-code.ts
+/** Reads the `code` of an error that Node raised, such as `ENOENT`. */
+var ErrorCode = class ErrorCode {
+	/**
+	* @param error - A caught value of any type.
+	* @returns The `code` of the error, or `undefined` when the value is not an error with a text code.
+	*/
+	static of(error) {
+		if (error instanceof Error && "code" in error && typeof error.code === "string") return error.code;
+	}
+	/**
+	* @param error - A caught value of any type.
+	* @param code - The code to look for, for example `"ENOENT"`.
+	* @returns Whether the error carries exactly that code.
+	*/
+	static is(error, code) {
+		return ErrorCode.of(error) === code;
+	}
+};
+//#endregion
+//#region src/init/dependency-installer.ts
+/** How an install ended. */
+const InstallStatus = {
+	/** The user asked to skip the install. */
+	Skipped: "skipped",
+	/** The install finished. */
+	Installed: "installed",
+	/** `pnpm` is not installed. */
+	PackageManagerMissing: "package-manager-missing",
+	/** `pnpm install` exited with an error. */
+	Failed: "failed"
+};
+/** Installs the dependencies of a new project with pnpm. */
+var DependencyInstaller = class DependencyInstaller {
+	/** The package manager. The starters pin their dependencies for pnpm. */
+	static command = "pnpm";
+	run;
+	/** @param run - Runs the install. nypm runs pnpm, through Corepack when Corepack exists, by default. */
+	constructor(run = (directory) => DependencyInstaller.installWithNypm(directory)) {
+		this.run = run;
+	}
+	/**
+	* Runs `pnpm install` in a project folder. It never throws for a failed install: the project is complete
+	* and the caller keeps it.
+	*
+	* @param directory - The project folder.
+	*/
+	async install(directory) {
+		try {
+			await this.run(directory);
+			return { status: InstallStatus.Installed };
+		} catch (error) {
+			if (DependencyInstaller.isMissingProgram(error)) return { status: InstallStatus.PackageManagerMissing };
+			return {
+				status: InstallStatus.Failed,
+				reason: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	/** Whether an error says that the program does not exist: `spawn pnpm ENOENT`. */
+	static isMissingProgram(error) {
+		return ErrorCode.is(error, "ENOENT");
+	}
+	/** The default {@link InstallRunner}. The output goes to the terminal of the user. */
+	static async installWithNypm(directory) {
+		await installDependencies({
+			cwd: directory,
+			packageManager: DependencyInstaller.command
+		});
+	}
+};
+//#endregion
+//#region src/init/init-messages.ts
+/** The text for the end of an `init` run. */
+var InitMessages = class InitMessages {
+	/** The command that starts the development server of a starter. */
+	static devCommand = "pnpm dev";
+	/** The command that writes the first migration of a starter. A starter commits no migration. */
+	static generateCommand = "pnpm db:generate";
+	/**
+	* The next steps after a successful run.
+	*
+	* @param changeDirectory - The folder to enter, relative to the current folder. Absent when the project is
+	*   in the current folder.
+	* @param isInstalled - Whether the dependencies are installed.
+	*/
+	static nextSteps(changeDirectory, isInstalled) {
+		return [
+			"Your Inferative project is ready.",
+			"Next steps:",
+			...[
+				...changeDirectory === void 0 ? [] : [`cd ${InitMessages.quote(changeDirectory)}`],
+				...isInstalled ? [] : [`${DependencyInstaller.command} install`],
+				"cp .env.example .env",
+				InitMessages.generateCommand,
+				InitMessages.devCommand
+			].map((step) => `  ${step}`),
+			"Fill in the values of .env first. README.md in the project explains the first run, with its first manifest sync (pnpm sync:manifest --first-sync)."
+		].join("\n");
+	}
+	/** The text when pnpm is not installed. The project is complete. */
+	static packageManagerMissing(directory) {
+		return [
+			`The project is ready in ${directory}, but pnpm is not installed.`,
+			"Install pnpm: npm install --global pnpm",
+			`Then run "${DependencyInstaller.command} install" in the project folder.`
+		].join("\n");
+	}
+	/** The text when `pnpm install` fails. The project is complete. */
+	static installFailed(directory, reason) {
+		return [`The project is ready in ${directory}, but "${DependencyInstaller.command} install" failed${reason === void 0 ? "" : `: ${reason}`}.`, "Read the messages above. Fix the cause, then run the command again in the project folder."].join("\n");
+	}
+	/** A folder name in quotes when it holds a space. */
+	static quote(path) {
+		return /\s/u.test(path) ? JSON.stringify(path) : path;
+	}
+};
+//#endregion
+//#region src/process/npm-runner.ts
+/**
+* Starts a command with tinyexec and captures its output.
+*
+* It sets no `shell` option. On Windows tinyexec finds the `.cmd` shim of the command and escapes each argument for
+* cmd.exe, so a folder with a space or an `&` in its name reaches npm as one argument.
+*/
+var NpmRunner = class NpmRunner {
+	/** The exit code of cmd.exe for a command that it cannot find, in every language of Windows. */
+	static windowsCommandNotFoundExitCode = 9009;
+	execute;
+	platform;
+	/**
+	* @param execute - Starts the process. tinyexec's `x` by default.
+	* @param platform - The operating system. `process.platform` by default.
+	*/
+	constructor(execute = x, platform = process.platform) {
+		this.execute = execute;
+		this.platform = platform;
+	}
+	/**
+	* Runs a command and captures its output. It never throws: a command that cannot start answers exit code 1 with
+	* the reason in `stderr` and `commandMissing` when the program does not exist.
+	*
+	* @param command - The program.
+	* @param commandArguments - The arguments, one element for each argument.
+	* @param workingDirectory - The directory to run in.
+	* @param environment - Variables added to the environment of the process.
+	*/
+	async run(command, commandArguments, workingDirectory, environment) {
+		try {
+			const result = await this.execute(command, commandArguments, { nodeOptions: {
+				cwd: workingDirectory,
+				env: environment
+			} });
+			return {
+				exitCode: result.exitCode ?? 1,
+				stdout: result.stdout,
+				stderr: result.stderr,
+				...this.isMissingInShell(result) ? { commandMissing: true } : {}
+			};
+		} catch (error) {
+			return {
+				exitCode: 1,
+				stdout: "",
+				stderr: error instanceof Error ? error.message : String(error),
+				commandMissing: NpmRunner.isMissingProgram(error)
+			};
+		}
+	}
+	/** Whether an error says that the program does not exist: `spawn npm ENOENT`. */
+	static isMissingProgram(error) {
+		return ErrorCode.is(error, "ENOENT");
+	}
+	/**
+	* Whether cmd.exe said that the program does not exist. On Windows tinyexec runs a command that it cannot find
+	* through cmd.exe, which exits with code 9009, where other systems throw `ENOENT`. The message is in the language
+	* of Windows, so the English text is only a second signal.
+	*/
+	isMissingInShell(result) {
+		if (this.platform !== "win32" || result.exitCode === 0) return false;
+		return result.exitCode === NpmRunner.windowsCommandNotFoundExitCode || /is not recognized as an internal or external command/iu.test(result.stderr);
+	}
+};
+//#endregion
+//#region src/registry/registry-access.ts
+/** The verdict {@link RegistryAccess.probe} reaches. */
+const RegistryAccessStatus = {
+	/** Both scopes reach GitHub Packages and the registry answered for each probe package. */
+	Ok: "ok",
+	/** A scope does not point at GitHub Packages. */
+	ScopeNotRouted: "scope-not-routed",
+	/** The registry refused the request for lacking, or holding invalid, credentials. */
+	Unauthorized: "unauthorized",
+	/** npm cannot be started: Node.js is installed without it, or not at all. */
+	NpmNotFound: "npm-not-found",
+	/** The registry could not be reached (DNS, network, timeout or an unknown failure). */
+	Unreachable: "unreachable",
+	/** The registry authorized the request, but the probe package is not there. */
+	NotFound: "not-found"
+};
+/**
+* Probes whether `@inferative/*` and the `@heximon/*` packages it depends on are readable from GitHub
+* Packages.
+*
+* It asks npm itself, so the verdict follows the same `.npmrc` files an install reads: the project's
+* and the user's.
+*/
+var RegistryAccess = class RegistryAccess {
+	/** The registry the `@inferative/*` and `@heximon/*` packages publish to. */
+	static gitHubPackagesRegistry = "https://npm.pkg.github.com";
+	/**
+	* The scopes that must resolve to {@link gitHubPackagesRegistry}, each with the package the probe reads. A
+	* token can read one organization and not the other, so each scope gets its own read.
+	*/
+	static scopes = [{
+		scope: "@inferative",
+		probePackage: "@inferative/site"
+	}, {
+		scope: "@heximon",
+		probePackage: "@heximon/runtime"
+	}];
+	/** The scope line a project's `.npmrc` carries for a scope. */
+	static scopeLine(scope) {
+		return `${scope}:registry=${RegistryAccess.gitHubPackagesRegistry}`;
+	}
+	run;
+	workingDirectory;
+	isProjectRoot;
+	/**
+	* @param workingDirectory - The directory npm reads its project `.npmrc` from.
+	* @param run - The process runner. It spawns `npm` by default.
+	* @param isProjectRoot - Whether `workingDirectory` is the project root, even when it holds no `package.json`
+	*   yet. npm then reads its `.npmrc`, and not the one of an ancestor project (`--prefix`). A caller that has
+	*   just made the folder sets it.
+	*/
+	constructor(workingDirectory = process.cwd(), run = (command, commandArguments, directory, environment) => new NpmRunner().run(command, commandArguments, directory, environment), isProjectRoot = false) {
+		this.workingDirectory = workingDirectory;
+		this.run = run;
+		this.isProjectRoot = isProjectRoot;
+	}
+	/**
+	* Checks that every scope points at GitHub Packages, then reads one probe package through each scope.
+	*
+	* @param environment - The environment npm runs with. An `.npmrc` that reads `${NODE_AUTH_TOKEN}` finds the
+	*   token here, so a caller passes the environment it loaded from the site's `.env`.
+	* @returns The verdict, with the scope it is about and the raw output as `detail`.
+	*/
+	async probe(environment = process.env) {
+		for (const { scope } of RegistryAccess.scopes) {
+			const configured = await this.run("npm", this.npmArguments([
+				"config",
+				"get",
+				`${scope}:registry`
+			]), this.workingDirectory, environment);
+			if (configured.commandMissing === true) return {
+				status: RegistryAccessStatus.NpmNotFound,
+				detail: configured.stderr.trim()
+			};
+			if (RegistryAccess.withoutTrailingSlash(configured.stdout) !== RegistryAccess.gitHubPackagesRegistry) return {
+				status: RegistryAccessStatus.ScopeNotRouted,
+				scope,
+				detail: configured.stdout.trim()
+			};
+		}
+		for (const { scope, probePackage } of RegistryAccess.scopes) {
+			const result = await this.run("npm", this.npmArguments([
+				"view",
+				probePackage,
+				"version",
+				"--json",
+				"--fetch-retries=0",
+				"--fetch-timeout=15000"
+			]), this.workingDirectory, environment);
+			if (result.commandMissing === true) return {
+				status: RegistryAccessStatus.NpmNotFound,
+				detail: result.stderr.trim()
+			};
+			if (result.exitCode !== 0) return RegistryAccess.failure(scope, `${result.stdout}\n${result.stderr}`);
+		}
+		return { status: RegistryAccessStatus.Ok };
+	}
+	/** The arguments of one npm call, with the prefix that pins the project root when the caller asked for it. */
+	npmArguments(commandArguments) {
+		return this.isProjectRoot ? [
+			...commandArguments,
+			"--prefix",
+			this.workingDirectory
+		] : commandArguments;
+	}
+	/**
+	* The lines that tell a user how to fix a verdict.
+	*
+	* @param report - The report that is not {@link RegistryAccessStatus.Ok}.
+	*/
+	static fixInstructions(report) {
+		if (report.status === RegistryAccessStatus.NpmNotFound) return [
+			"Cannot start npm.",
+			"Install Node.js (version 24 or later) with npm, from https://nodejs.org, and make sure npm is on your PATH.",
+			"Then run the command again."
+		].join("\n");
+		if (report.status === RegistryAccessStatus.Unreachable) return [
+			`Cannot reach ${RegistryAccess.gitHubPackagesRegistry}.`,
+			"Check your network connection.",
+			"Then run the command again."
+		].join("\n");
+		const scope = report.scope ?? RegistryAccess.scopes[0]?.scope ?? "@inferative";
+		return [
+			report.status === RegistryAccessStatus.ScopeNotRouted ? `The scope ${scope} does not point at GitHub Packages.` : `Cannot read ${scope}/* from GitHub Packages.`,
+			"Add these lines to ~/.npmrc, or to the .npmrc of the project:",
+			`  ${RegistryAccess.scopeLine(scope)}`,
+			"  //npm.pkg.github.com/:_authToken=<a GitHub token with the read:packages scope>",
+			"Then run the command again."
+		].join("\n");
+	}
+	/** The verdict for a failed read of the probe package of `scope`. */
+	static failure(scope, output) {
+		const detail = output.trim();
+		if (/E401|E403|ENEEDAUTH/u.test(output)) return {
+			status: RegistryAccessStatus.Unauthorized,
+			scope,
+			detail
+		};
+		if (/E404/u.test(output)) return {
+			status: RegistryAccessStatus.NotFound,
+			scope,
+			detail
+		};
+		return {
+			status: RegistryAccessStatus.Unreachable,
+			scope,
+			detail
+		};
+	}
+	/** A registry address without the slash npm may add at its end. */
+	static withoutTrailingSlash(address) {
+		return address.trim().replace(/\/+$/u, "");
+	}
+};
+//#endregion
+//#region src/init/init-error.ts
+/** A failure that `inferative init` reports in plain words, without a stack trace. */
+var InitError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "InitError";
+	}
+};
+//#endregion
+//#region src/init/init-target.ts
+/**
+* An accepted target folder. It is absent or empty when accepted, so every entry in it later belongs to this run.
+*/
+var InitTarget = class InitTarget {
+	/** The package name of a folder whose own name has no usable character. */
+	static fallbackPackageName = "inferative-app";
+	static packageNamePattern = /^[a-z0-9][a-z0-9._-]*$/u;
+	/** The absolute folder. */
+	directory;
+	/** The `name` that goes into the project's `package.json`. */
+	packageName;
+	/** The parents that this run created, the nearest first. Empty when the folder existed. */
+	createdParents;
+	isCreated;
+	constructor(directory, packageName, isCreated, createdParents) {
+		this.directory = directory;
+		this.packageName = packageName;
+		this.isCreated = isCreated;
+		this.createdParents = createdParents;
+	}
+	/**
+	* Checks a package name.
+	*
+	* @param name - The candidate name.
+	* @returns `undefined` when the name is valid, otherwise the problem in plain words.
+	*/
+	static validatePackageName(name) {
+		if (InitTarget.packageNamePattern.test(name)) return;
+		return `"${name}" is not a valid package name. Use lowercase letters, digits, and . _ - only, and start with a letter or a digit.`;
+	}
+	/**
+	* Turns the name of an existing folder into a valid package name: lowercase, with each run of other
+	* characters replaced by one `-`.
+	*
+	* @param folderName - The base name of the folder.
+	*/
+	static normalizePackageName(folderName) {
+		const normalized = folderName.toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^[^a-z0-9]+/u, "").replace(/[^a-z0-9]+$/u, "");
+		return normalized === "" ? InitTarget.fallbackPackageName : normalized;
+	}
+	/**
+	* Accepts the target folder, and creates it when it does not exist.
+	*
+	* A folder that the user names must have a valid package name as its base name. The current folder keeps
+	* its name on disk, so its package name is normalised instead.
+	*
+	* @param request - Where the folder is.
+	* @throws {InitError} When the name is invalid, the path is a file, or the folder is not empty.
+	*/
+	static async prepare(request) {
+		const base = resolve(request.workingDirectory);
+		const directory = request.directory === void 0 ? base : resolve(base, request.directory);
+		const isBaseFolder = directory === base;
+		const folderName = basename(directory);
+		const packageName = isBaseFolder ? InitTarget.normalizePackageName(folderName) : folderName;
+		const problem = InitTarget.validatePackageName(packageName);
+		if (problem !== void 0) throw new InitError(problem);
+		const entries = await InitTarget.readEntries(directory);
+		if (entries === void 0) {
+			const createdParents = await InitTarget.missingAncestors(directory);
+			await mkdir(directory, { recursive: true });
+			return new InitTarget(directory, packageName, true, createdParents);
+		}
+		if (entries.length > 0) throw new InitError(`The folder ${directory} is not empty. Choose an empty folder or a new name. Nothing was changed.`);
+		return new InitTarget(directory, packageName, false, []);
+	}
+	/**
+	* Removes everything this run wrote: the folder that it created, or else every entry of an existing folder.
+	* A parent that this run created goes too, but only while it is empty: another process may have put a
+	* sibling project there.
+	*/
+	async discard() {
+		if (!this.isCreated) {
+			await this.clearExcept();
+			return;
+		}
+		await rm(this.directory, {
+			recursive: true,
+			force: true
+		});
+		for (const parent of this.createdParents) try {
+			await rmdir(parent);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Removes the entries of the folder, for example the half-written files of a failed download.
+	*
+	* @param keep - The name of one entry to keep.
+	*/
+	async clearExcept(keep) {
+		for (const entry of await InitTarget.readEntries(this.directory) ?? []) if (entry !== keep) await rm(join(this.directory, entry), {
+			recursive: true,
+			force: true
+		});
+	}
+	/** The parents of `directory` that do not exist yet, the nearest first. */
+	static async missingAncestors(directory) {
+		const missing = [];
+		let current = dirname(directory);
+		while (current !== dirname(current) && await InitTarget.readEntries(current) === void 0) {
+			missing.push(current);
+			current = dirname(current);
+		}
+		return missing;
+	}
+	/** The entries of a folder, or `undefined` when it does not exist. */
+	static async readEntries(directory) {
+		try {
+			return await readdir(directory);
+		} catch (error) {
+			const code = ErrorCode.of(error);
+			if (code === "ENOENT") return;
+			if (code === "ENOTDIR") throw new InitError(`${directory} is a file, not a folder.`);
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/init/manifest-stamper.ts
+/** Rewrites the `package.json` that a starter ships. */
+var ManifestStamper = class ManifestStamper {
+	/** The dependency sections whose Inferative ranges follow the command line's version. */
+	static sections = ["dependencies", "devDependencies"];
+	/** The command line itself, which a starter may list beside the `@inferative/*` packages. */
+	static commandLineName = "inferative";
+	/** The scope prefix of the Inferative libraries. */
+	static scopePrefix = "@inferative/";
+	/**
+	* Sets `name`, and sets the range of `inferative` and of each `@inferative/*` dependency to `^<version>`.
+	* Every other range stays as the starter pins it.
+	*
+	* @param directory - The project folder.
+	* @param packageName - The new `name`.
+	* @param version - The version of the command line.
+	* @throws {InitError} When the starter has no readable `package.json`.
+	*/
+	static async stamp(directory, packageName, version) {
+		const path = join(directory, "package.json");
+		const manifest = ManifestStamper.parse(await ManifestStamper.read(path), path);
+		manifest["name"] = packageName;
+		for (const section of ManifestStamper.sections) {
+			const dependencies = manifest[section];
+			if (!ManifestStamper.isRecord(dependencies)) continue;
+			for (const dependency of Object.keys(dependencies)) if (ManifestStamper.isInferative(dependency)) dependencies[dependency] = `^${version}`;
+		}
+		await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`);
+	}
+	/** Whether a dependency name is `inferative` or one of the `@inferative/*` libraries. */
+	static isInferative(name) {
+		return name === ManifestStamper.commandLineName || name.startsWith(ManifestStamper.scopePrefix);
+	}
+	static async read(path) {
+		try {
+			return await readFile(path, "utf8");
+		} catch (error) {
+			if (ErrorCode.is(error, "ENOENT")) throw new InitError("The starter has no package.json.");
+			throw error;
+		}
+	}
+	static parse(text, path) {
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			throw new InitError(`${path} is not valid JSON.`, { cause: error });
+		}
+		if (!ManifestStamper.isRecord(parsed)) throw new InitError(`${path} does not hold a JSON object.`);
+		return parsed;
+	}
+	static isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+};
+//#endregion
+//#region src/init/npmrc-scopes.ts
+/** Writes the scope lines of `@inferative` and `@heximon` into a project's `.npmrc`. It never writes a token. */
+var NpmrcScopes = class NpmrcScopes {
+	/** The file name. */
+	static filename = ".npmrc";
+	/** The scope lines, one for each scope in {@link RegistryAccess.scopes}. */
+	static lines() {
+		return RegistryAccess.scopes.map((entry) => RegistryAccess.scopeLine(entry.scope));
+	}
+	/**
+	* Adds the missing scope lines to the text of an `.npmrc`. It keeps every existing line.
+	*
+	* @param content - The current text. It may be empty.
+	* @returns The text with each missing line appended, or `content` itself when none is missing.
+	*/
+	static merge(content) {
+		const present = new Set(content.split(/\r?\n/u).map((line) => line.trim()));
+		const missing = NpmrcScopes.lines().filter((line) => !present.has(line));
+		if (missing.length === 0) return content;
+		return `${content}${content === "" || content.endsWith("\n") ? "" : "\n"}${missing.join("\n")}\n`;
+	}
+	/**
+	* Creates the `.npmrc` of a project folder, or completes the one that exists.
+	*
+	* @param directory - The project folder.
+	*/
+	static async apply(directory) {
+		const path = join(directory, NpmrcScopes.filename);
+		const current = await NpmrcScopes.read(path);
+		const merged = NpmrcScopes.merge(current);
+		if (merged !== current) await writeFile(path, merged);
+	}
+	/** The text of a file, or an empty text when the file does not exist. */
+	static async read(path) {
+		try {
+			return await readFile(path, "utf8");
+		} catch (error) {
+			if (ErrorCode.is(error, "ENOENT")) return "";
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/init/starter-source.ts
+/** A download that failed. Only this failure makes {@link StarterSource.fetch} try the next source. */
+var StarterDownloadError = class StarterDownloadError extends InitError {
+	/** The giget sources that failed. */
+	sources;
+	/** Why the download failed, in one line. */
+	reason;
+	constructor(sources, reason, options) {
+		super(sources.length === 1 ? `Cannot download the starter from ${sources[0] ?? ""}: ${reason}` : `Cannot download the starter. ${reason}`, options);
+		this.name = "StarterDownloadError";
+		this.sources = sources;
+		this.reason = reason;
+	}
+	/**
+	* The failure of one source.
+	*
+	* @param source - The giget source.
+	* @param cause - What the download threw.
+	*/
+	static of(source, cause) {
+		return new StarterDownloadError([source], cause instanceof Error ? cause.message : String(cause), { cause });
+	}
+};
+/** Fetches the files of a starter. */
+var StarterSource = class StarterSource {
+	/** The public repository that holds the starters, one folder for each. */
+	static repository = "inferative/starters";
+	/** The starter that `init` uses when none is named. */
+	static defaultStarter = "nuxt-cloudflare";
+	/** The branch that the default sources fall back to. */
+	static fallbackBranch = "main";
+	static starterNamePattern = /^[a-z0-9][a-z0-9-]*$/u;
+	download;
+	/** @param download - The download function. It calls giget by default. */
+	constructor(download = (source, directory) => StarterSource.downloadWithGiget(source, directory)) {
+		this.download = download;
+	}
+	/**
+	* The giget sources to try, in order: the branch for this minor version, then `main`.
+	*
+	* @param starter - The starter folder name.
+	* @param version - The version of the command line.
+	*/
+	static defaultSources(starter, version) {
+		const base = `gh:${StarterSource.repository}/${starter}`;
+		return [`${base}#v${CliVersion.minor(version)}`, `${base}#${StarterSource.fallbackBranch}`];
+	}
+	/**
+	* Checks a starter name, which becomes a path segment.
+	*
+	* @throws {InitError} When the name is not a plain lowercase folder name.
+	*/
+	static assertStarterName(starter) {
+		if (!StarterSource.starterNamePattern.test(starter)) throw new InitError(`"${starter}" is not a starter name. Use lowercase letters, digits, and - only.`);
+	}
+	/**
+	* Downloads the starter from the first source that works.
+	*
+	* Only a failed download moves on to the next source. Any other error stops the run, because the next
+	* source would fail the same way.
+	*
+	* @param sources - The giget sources, in order.
+	* @param directory - The folder to fill.
+	* @param resetDirectory - Called before each later source, to remove the half-written files of the last one.
+	* @returns The source that worked.
+	* @throws {StarterDownloadError} When every source failed. The message holds each failure.
+	*/
+	async fetch(sources, directory, resetDirectory) {
+		const failures = [];
+		for (const source of sources) try {
+			await this.download(source, directory);
+			return source;
+		} catch (error) {
+			failures.push(StarterDownloadError.of(source, error));
+			await resetDirectory();
+		}
+		const [first] = failures;
+		if (failures.length === 1 && first !== void 0) throw first;
+		throw new StarterDownloadError(sources, `Tried ${failures.map((failure) => `${failure.sources.join("")} (${failure.reason})`).join(", then ")}.`);
+	}
+	/**
+	* Copies a starter from a local starters folder.
+	*
+	* @param localDirectory - The folder that holds the starters.
+	* @param starter - The starter folder name.
+	* @param directory - The folder to fill.
+	* @throws {InitError} When the starter folder does not exist.
+	*/
+	async copyLocal(localDirectory, starter, directory) {
+		const source = resolve(localDirectory, starter);
+		try {
+			if (!(await stat(source)).isDirectory()) throw new InitError(`${source} is not a folder.`);
+		} catch (error) {
+			if (ErrorCode.is(error, "ENOENT")) throw new InitError(`The starter folder ${source} does not exist.`);
+			throw error;
+		}
+		await cp(source, directory, {
+			recursive: true,
+			filter: (path) => !path.split(/[\\/]/u).includes("node_modules")
+		});
+		return source;
+	}
+	/** The default {@link StarterDownload}. It loads giget on first use, so a local copy needs no giget. */
+	static async downloadWithGiget(source, directory) {
+		const { downloadTemplate } = await import("giget");
+		await downloadTemplate(source, {
+			dir: directory,
+			force: true
+		});
+	}
+};
+//#endregion
+//#region src/init/project-initializer.ts
+/** Creates a project from a starter. */
+var ProjectInitializer = class ProjectInitializer {
+	starters;
+	probeRegistry;
+	installer;
+	/** @param dependencies - Replacements for the download, the registry probe and the install. */
+	constructor(dependencies = {}) {
+		this.starters = new StarterSource(dependencies.download);
+		this.probeRegistry = dependencies.probeRegistry ?? ((directory) => new RegistryAccess(directory, dependencies.runNpm, true).probe());
+		this.installer = new DependencyInstaller(dependencies.runInstall);
+	}
+	/**
+	* Creates the project.
+	*
+	* Before the install, any failure removes what this run wrote and throws. A failed install keeps the
+	* project, because it is complete, and reports the failure in the result.
+	*
+	* @param request - What to create, and where.
+	* @throws {InitError} When the folder, the registry, the starter or the request is not usable.
+	*/
+	async initialize(request) {
+		ProjectInitializer.assertRequest(request);
+		const target = await InitTarget.prepare(request);
+		let source;
+		try {
+			await this.assertRegistryAccess(target);
+			source = await this.fetchStarter(request, target);
+			await NpmrcScopes.apply(target.directory);
+			await ManifestStamper.stamp(target.directory, target.packageName, request.version);
+		} catch (error) {
+			await target.discard();
+			throw error;
+		}
+		const base = {
+			projectDirectory: target.directory,
+			packageName: target.packageName,
+			source
+		};
+		if (!request.install) return {
+			...base,
+			install: InstallStatus.Skipped
+		};
+		const outcome = await this.installer.install(target.directory);
+		return {
+			...base,
+			install: outcome.status,
+			...outcome.reason === void 0 ? {} : { installError: outcome.reason }
+		};
+	}
+	/** Writes the scope lines, then fails when the registry is not readable. The download has not started. */
+	async assertRegistryAccess(target) {
+		await NpmrcScopes.apply(target.directory);
+		const report = await this.probeRegistry(target.directory);
+		if (report.status !== RegistryAccessStatus.Ok) throw new InitError(`${RegistryAccess.fixInstructions(report)}\nNothing was changed.`);
+	}
+	/** Fills the folder from the local copy or the download, and answers where the files came from. */
+	fetchStarter(request, target) {
+		if (request.local !== void 0) return this.starters.copyLocal(request.local, request.starter, target.directory);
+		const sources = request.source === void 0 ? StarterSource.defaultSources(request.starter, request.version) : [request.source];
+		return this.starters.fetch(sources, target.directory, () => target.clearExcept(NpmrcScopes.filename));
+	}
+	/** Refuses a request that cannot work before any file exists. */
+	static assertRequest(request) {
+		if (request.local !== void 0 && request.source !== void 0) throw new InitError("Use --local or --source, not both.");
+		StarterSource.assertStarterName(request.starter);
+	}
+};
+//#endregion
+//#region src/init/init-command.ts
+/** The `init` command. */
+var InitCommand = class InitCommand {
+	/** The name it is registered under. */
+	static name = "init";
+	/** The exit code of a run that made a usable project. */
+	static okExitCode = 0;
+	/** The exit code of a run that failed, including a failed install. */
+	static failureExitCode = 1;
+	/** The command definition. */
+	static definition() {
+		return defineCommand({
+			meta: {
+				name: InitCommand.name,
+				description: "Create a new Inferative project from a starter."
+			},
+			args: InitCommand.args(),
+			run: async (context) => {
+				const args = context.args;
+				process.exitCode = await InitCommand.execute({
+					...typeof args["directory"] === "string" ? { directory: args["directory"] } : {},
+					...typeof args["starter"] === "string" ? { starter: args["starter"] } : {},
+					...typeof args["source"] === "string" ? { source: args["source"] } : {},
+					...typeof args["local"] === "string" ? { local: args["local"] } : {},
+					...typeof args["cwd"] === "string" ? { cwd: args["cwd"] } : {},
+					install: args["install"] !== false
+				});
+			}
+		});
+	}
+	/** The argument definition, which `create-inferative` shares. */
+	static args() {
+		return {
+			directory: {
+				type: "positional",
+				description: "The folder to create. The current folder, which must be empty, when absent.",
+				required: false
+			},
+			starter: {
+				type: "string",
+				description: `The starter to use. ${StarterSource.defaultStarter} by default.`,
+				default: StarterSource.defaultStarter,
+				valueHint: "name"
+			},
+			source: {
+				type: "string",
+				description: "A giget source to download instead of the default starters.",
+				valueHint: "giget-source"
+			},
+			local: {
+				type: "string",
+				description: "Copy the starter from this starters folder. Nothing is downloaded.",
+				valueHint: "path"
+			},
+			install: {
+				type: "boolean",
+				description: "Run pnpm install after the files are written. Use --no-install to skip.",
+				default: true
+			},
+			cwd: {
+				type: "string",
+				description: "The folder that a named directory is created in. The current folder by default.",
+				valueHint: "path"
+			}
+		};
+	}
+	/**
+	* Creates one project and answers the exit code.
+	*
+	* @param args - What the invocation was asked to do.
+	* @param options - The working directory, the version and the replaceable parts. A test supplies them.
+	* @returns {@link okExitCode} when the project is usable, otherwise {@link failureExitCode}.
+	*/
+	static async execute(args, options = {}) {
+		const print = options.print ?? ((line) => console.log(line));
+		const fail = options.fail ?? ((line) => void process.stderr.write(`${line}\n`));
+		const currentDirectory = options.cwd ?? process.cwd();
+		try {
+			const result = await new ProjectInitializer(options.dependencies).initialize({
+				...args.directory === void 0 ? {} : { directory: args.directory },
+				workingDirectory: resolve(currentDirectory, args.cwd ?? "."),
+				starter: args.starter ?? StarterSource.defaultStarter,
+				...args.source === void 0 ? {} : { source: args.source },
+				...args.local === void 0 ? {} : { local: resolve(currentDirectory, args.local) },
+				install: args.install !== false,
+				version: options.version ?? CliVersion.current()
+			});
+			if (result.install === InstallStatus.PackageManagerMissing) {
+				fail(InitMessages.packageManagerMissing(result.projectDirectory));
+				return InitCommand.failureExitCode;
+			}
+			if (result.install === InstallStatus.Failed) {
+				fail(InitMessages.installFailed(result.projectDirectory, result.installError));
+				return InitCommand.failureExitCode;
+			}
+			const changeDirectory = relative(currentDirectory, result.projectDirectory);
+			print(InitMessages.nextSteps(changeDirectory === "" ? void 0 : changeDirectory, result.install === InstallStatus.Installed));
+			return InitCommand.okExitCode;
+		} catch (error) {
+			fail(error instanceof Error ? error.message : String(error));
+			return InitCommand.failureExitCode;
+		}
+	}
+};
+//#endregion
+export { CliVersion as i, RegistryAccess as n, RegistryAccessStatus as r, InitCommand as t };