create-inferative 0.0.0 → 0.2.0-next.20261013180716

package/LICENSE

@@ -0,0 +1,70 @@
+Copyright (c) 2024 WP Online Magyarország Kft.
+Website: https://wpo.hu
+All Rights Reserved.
+
+==============================================================================
+WP Online Magyarország Kft. - Internal Use Software License
+==============================================================================
+
+This software package and its accompanying documentation (collectively, "the Software")
+are the proprietary and confidential information of WP Online Magyarország Kft.
+("the Company").
+
+1.  GRANT OF LICENSE:
+    Subject to the terms and conditions of this License, the Company grants to
+    its employees and authorized contractors ("Authorized Users") a non-exclusive,
+    non-transferable, revocable license to install, use, copy, and modify the
+    Software solely for internal Company business purposes.
+
+2.  RESTRICTIONS:
+    Authorized Users shall not:
+    a.  Distribute, sublicense, sell, rent, lease, lend, or otherwise transfer
+        the Software, or any part thereof, to any third party outside of
+        WP Online Magyarország Kft. without the express prior written permission
+        of an authorized representative of the Company.
+    b.  Use the Software for any purpose not expressly permitted by this License,
+        including any personal or commercial projects unrelated to the
+        Company's business.
+    c.  Remove or alter any copyright, trademark, or other proprietary notices
+        contained in the Software.
+    d.  Reverse engineer, decompile, or disassemble the Software, except and
+        only to the extent that such activity is expressly permitted by
+        applicable law notwithstanding this limitation.
+
+3.  OWNERSHIP AND INTELLECTUAL PROPERTY:
+    The Company retains all right, title, and interest in and to the Software,
+    including all copyrights, patents, trade secrets, trademarks, and other
+    intellectual property rights therein. No rights are granted to Authorized
+    Users other than those expressly set forth in this License.
+
+4.  CONFIDENTIALITY:
+    The Software, including its source code, design, and structure, is
+    confidential information of the Company. Authorized Users shall treat the
+    Software with the same degree of care as they treat other Company
+    confidential information and shall not disclose it to any third party
+    without the Company's prior written consent.
+
+5.  NO WARRANTY:
+    THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+    IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6.  TERMINATION:
+    This License will terminate automatically if an Authorized User breaches any
+    of its terms and conditions. The license granted herein is also contingent
+    upon continued employment or contract with the Company and terminates
+    immediately upon the cessation of that relationship. Upon termination, the
+    Authorized User must cease all use of the Software and destroy all copies
+
+    of the Software in their possession or control.
+
+7.  GOVERNING LAW:
+    This License shall be governed by and construed in accordance with the laws
+    of Hungary, without regard to its conflict of law principles. Any disputes
+    arising under or in connection with this License shall be subject to the
+        exclusive jurisdiction of the courts of Hungary.
+
+For questions regarding this license, please contact office@wpo.hu.

package/README.md

@@ -1 +1,56 @@
-# create-inferative
+# `create-inferative`
+
+Create a new Inferative project with nothing installed first. This package owns the `init` command, and
+`inferative init` runs the same command, so every flag works the same way. It depends on packages from public npm only,
+so `npm create inferative` needs no registry setting before it starts.
+
+## Create a project
+
+Run one command for your package manager.
+
+```sh
+npm create inferative@latest my-site
+pnpm create inferative my-site
+yarn create inferative my-site
+bun create inferative my-site
+```
+
+The command writes the project into the folder `my-site`. Leave the name out to fill the current folder. The folder
+must not exist, or must be empty. The command never overwrites a file.
+
+## What it does
+
+1. It writes the `@inferative` and `@heximon` lines into the `.npmrc` of the project. Both scopes live on GitHub
+   Packages.
+2. It checks that npm can read both scopes. If it cannot, it removes what it wrote, prints the lines to add to your
+   `~/.npmrc`, and stops.
+3. It downloads the starter from the `inferative/starters` repository.
+4. It sets the `name` of the project and the version of `inferative` and of every `@inferative/*` package.
+5. It runs `pnpm install`.
+
+The package and its dependencies come from public npm, so the command starts with an empty `~/.npmrc`. The project
+install needs only the token, because step 1 writes the two scope lines into the `.npmrc` of the project:
+
+```ini
+//npm.pkg.github.com/:_authToken=<a GitHub token with the read:packages scope>
+```
+
+Add the token line to your `~/.npmrc`. If the token is missing, step 2 stops and prints the lines to add.
+
+## Flags
+
+| Flag | What it does |
+| :-- | :-- |
+| `--starter <name>` | The starter to use. `nuxt-cloudflare` by default. |
+| `--source <giget source>` | Download this source instead of the default starters. |
+| `--local <folder>` | Copy the starter from this starters folder. Nothing is downloaded. |
+| `--no-install` | Do not run `pnpm install`. |
+| `--cwd <folder>` | The folder in which a named project folder is created. |
+
+`pnpm`, `yarn` and `bun` pass a `--` to this package. The package drops the first one, so
+`pnpm create inferative my-site -- --no-install` works as written.
+
+## Works with
+
+- [`inferative`](../cli) depends on this package. `inferative init` and `inferative site doctor` use the `init`
+  command and the registry probe from here.

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { t as CreateFrontDoor } from "./front-door-CJboxy5n.mjs";
+import { runMain } from "citty";
+//#region src/bin.ts
+const argv = CreateFrontDoor.rawArgs(process.argv.slice(2));
+if (CreateFrontDoor.isVersionRequest(argv)) process.stdout.write(`${CreateFrontDoor.version()}\n`);
+else await runMain(CreateFrontDoor.command(), { rawArgs: [...argv] });
+//#endregion
+export {};

package/dist/front-door-CJboxy5n.mjs

@@ -0,0 +1,932 @@
+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/package-version.ts
+/**
+* The version in this package's own `package.json`.
+*
+* It selects the starter branch and the range stamped into a project. All packages share one version.
+*/
+var PackageVersion = 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 accent removed and
+	* its letter kept (`Café` gives `cafe`), and each run of other characters replaced by one `-`.
+	*
+	* @param folderName - The base name of the folder.
+	*/
+	static normalizePackageName(folderName) {
+		const normalized = folderName.toLowerCase().normalize("NFKD").replace(/\p{Mn}/gu, "").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${PackageVersion.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;
+	runNpm;
+	installer;
+	/** @param dependencies - Replacements for the download, the `npm` calls and the install. */
+	constructor(dependencies = {}) {
+		this.starters = new StarterSource(dependencies.download);
+		this.runNpm = dependencies.runNpm;
+		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 new RegistryAccess(target.directory, this.runNpm, true).probe();
+		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 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: PackageVersion.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
+//#region src/front-door.ts
+/**
+* The front door of `npm create inferative`.
+*
+* It reuses the arguments and the `run` of {@link InitCommand}, which `inferative init` also runs, so the two names
+* never differ. It sets its own `meta`: `--help` then prints the binary that the user typed, and `--version` has a
+* version to print.
+*/
+var CreateFrontDoor = class CreateFrontDoor {
+	/** The binary name, as the usage line of `--help` shows it. */
+	static binaryName = "create-inferative";
+	/** The end-of-options marker that some package managers pass on to the binary. */
+	static optionsSeparator = "--";
+	/** The command that citty runs. */
+	static command() {
+		return {
+			...InitCommand.definition(),
+			meta: {
+				name: CreateFrontDoor.binaryName,
+				version: CreateFrontDoor.version(),
+				description: "Create a new Inferative project (the `npm create inferative` front door)."
+			}
+		};
+	}
+	/**
+	* The arguments that citty parses, without the first bare `--`.
+	*
+	* `npm create` removes the separator itself. `pnpm`, `yarn` and `bun` pass it on, and citty puts every
+	* argument after it into the positional list, where no flag reads it.
+	*
+	* @param argv - The arguments after the executable's name.
+	*/
+	static rawArgs(argv) {
+		const separator = argv.indexOf(CreateFrontDoor.optionsSeparator);
+		return separator === -1 ? [...argv] : [...argv.slice(0, separator), ...argv.slice(separator + 1)];
+	}
+	/**
+	* Whether the arguments ask for the version and nothing else.
+	*
+	* @param argv - The arguments after the executable's name.
+	*/
+	static isVersionRequest(argv) {
+		return argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v");
+	}
+	/** The version of this package, which `--version` prints. */
+	static version() {
+		return PackageVersion.current();
+	}
+};
+//#endregion
+export { RegistryAccessStatus as i, InitCommand as n, RegistryAccess as r, CreateFrontDoor as t };

package/dist/index.d.mts

@@ -0,0 +1,200 @@
+import { ArgsDef, CommandDef } from "citty";
+//#region src/registry/registry-access.d.ts
+/** The result of one spawned command, captured rather than inherited. */
+interface ProcessRunResult {
+  /** The process exit code; a process that never exited counts as `1`. */
+  readonly exitCode: number;
+  /** Captured standard output. */
+  readonly stdout: string;
+  /** Captured standard error. */
+  readonly stderr: string;
+  /** Whether the program could not be started because it is not installed. */
+  readonly commandMissing?: boolean;
+}
+/** Spawns a command and resolves its captured result. A test injects one so no real `npm` runs. */
+type ProcessRunner = (command: string, commandArguments: readonly string[], workingDirectory: string, environment: Readonly<Record<string, string | undefined>>) => Promise<ProcessRunResult>;
+/** The verdict {@link RegistryAccess.probe} reaches. */
+export declare const RegistryAccessStatus: {
+  /** Both scopes reach GitHub Packages and the registry answered for each probe package. */
+  readonly Ok: "ok";
+  /** A scope does not point at GitHub Packages. */
+  readonly ScopeNotRouted: "scope-not-routed";
+  /** The registry refused the request for lacking, or holding invalid, credentials. */
+  readonly Unauthorized: "unauthorized";
+  /** npm cannot be started: Node.js is installed without it, or not at all. */
+  readonly NpmNotFound: "npm-not-found";
+  /** The registry could not be reached (DNS, network, timeout or an unknown failure). */
+  readonly Unreachable: "unreachable";
+  /** The registry authorized the request, but the probe package is not there. */
+  readonly NotFound: "not-found";
+};
+/** One of {@link RegistryAccessStatus}. */
+type RegistryAccessStatusValue = (typeof RegistryAccessStatus)[keyof typeof RegistryAccessStatus];
+/** What {@link RegistryAccess.probe} reports. */
+interface RegistryAccessReport {
+  /** The verdict. */
+  readonly status: RegistryAccessStatusValue;
+  /** The scope the verdict is about: the first one that is not routed or not readable. Absent for `Ok`. */
+  readonly scope?: string;
+  /** The raw output behind the verdict, for a diagnosis. */
+  readonly detail?: string;
+}
+/**
+ * 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.
+ */
+export declare class RegistryAccess {
+  /** The registry the `@inferative/*` and `@heximon/*` packages publish to. */
+  static readonly gitHubPackagesRegistry: string;
+  /**
+   * 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 readonly scopes: readonly {
+    readonly scope: string;
+    readonly probePackage: string;
+  }[];
+  /** The scope line a project's `.npmrc` carries for a scope. */
+  static scopeLine(scope: string): string;
+  private readonly run;
+  private readonly workingDirectory;
+  private readonly 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?: string, run?: ProcessRunner, isProjectRoot?: boolean);
+  /**
+   * 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`.
+   */
+  probe(environment?: Readonly<Record<string, string | undefined>>): Promise<RegistryAccessReport>;
+  /** The arguments of one npm call, with the prefix that pins the project root when the caller asked for it. */
+  private npmArguments;
+  /**
+   * The lines that tell a user how to fix a verdict.
+   *
+   * @param report - The report that is not {@link RegistryAccessStatus.Ok}.
+   */
+  static fixInstructions(report: RegistryAccessReport): string;
+  /** The verdict for a failed read of the probe package of `scope`. */
+  private static failure;
+  /** A registry address without the slash npm may add at its end. */
+  private static withoutTrailingSlash;
+}
+//#endregion
+//#region src/init/dependency-installer.d.ts
+/**
+ * Installs the dependencies of a project folder, and throws when the install fails. A test injects one so no real
+ * package manager runs.
+ */
+type InstallRunner = (directory: string) => Promise<void>;
+//#endregion
+//#region src/init/starter-source.d.ts
+/** Downloads one giget source into an empty folder. A test injects one so nothing touches the network. */
+type StarterDownload = (source: string, directory: string) => Promise<void>;
+//#endregion
+//#region src/init/project-initializer.d.ts
+/** The injectable parts of {@link ProjectInitializer}. */
+interface InitDependencies {
+  /** Downloads a giget source. Giget by default. */
+  readonly download?: StarterDownload;
+  /** Runs the `npm` calls of the registry probe. Spawns npm by default. */
+  readonly runNpm?: ProcessRunner;
+  /** Runs the install. Spawns pnpm by default. */
+  readonly runInstall?: InstallRunner;
+}
+//#endregion
+//#region src/init/init-command.d.ts
+/** What one `init` invocation was asked to do. */
+interface InitArguments {
+  /** The folder to create. The current folder when absent. */
+  readonly directory?: string;
+  /** The starter folder name. */
+  readonly starter?: string;
+  /** One giget source to use alone. */
+  readonly source?: string;
+  /** A local starters folder to copy from. */
+  readonly local?: string;
+  /** The folder that a named `directory` is created in. */
+  readonly cwd?: string;
+  /** Whether to install the dependencies. `false` for `--no-install`. */
+  readonly install?: boolean;
+}
+/** The parts of an `init` run that a test replaces. */
+interface InitOptions {
+  /** The working directory. The process's own by default. */
+  readonly cwd?: string;
+  /** The download, the `npm` calls of the registry probe and the install. */
+  readonly dependencies?: InitDependencies;
+  /** Writes a line to the output. */
+  readonly print?: (line: string) => void;
+  /** Writes a line to the error output. */
+  readonly fail?: (line: string) => void;
+}
+/** The `init` command. */
+export declare class InitCommand {
+  /** The name it is registered under. */
+  static readonly name: string;
+  /** The exit code of a run that made a usable project. */
+  static readonly okExitCode: number;
+  /** The exit code of a run that failed, including a failed install. */
+  static readonly failureExitCode: number;
+  /** The command definition. */
+  static definition(): CommandDef;
+  /** The argument definition, which `create-inferative` shares. */
+  static args(): ArgsDef;
+  /**
+   * Creates one project and answers the exit code.
+   *
+   * @param args - What the invocation was asked to do.
+   * @param options - The working directory and the replaceable parts. A test supplies them.
+   * @returns {@link okExitCode} when the project is usable, otherwise {@link failureExitCode}.
+   */
+  static execute(args: InitArguments, options?: InitOptions): Promise<number>;
+}
+//#endregion
+//#region src/front-door.d.ts
+/**
+ * The front door of `npm create inferative`.
+ *
+ * It reuses the arguments and the `run` of {@link InitCommand}, which `inferative init` also runs, so the two names
+ * never differ. It sets its own `meta`: `--help` then prints the binary that the user typed, and `--version` has a
+ * version to print.
+ */
+export declare class CreateFrontDoor {
+  /** The binary name, as the usage line of `--help` shows it. */
+  static readonly binaryName: string;
+  /** The end-of-options marker that some package managers pass on to the binary. */
+  private static readonly optionsSeparator;
+  /** The command that citty runs. */
+  static command(): CommandDef;
+  /**
+   * The arguments that citty parses, without the first bare `--`.
+   *
+   * `npm create` removes the separator itself. `pnpm`, `yarn` and `bun` pass it on, and citty puts every
+   * argument after it into the positional list, where no flag reads it.
+   *
+   * @param argv - The arguments after the executable's name.
+   */
+  static rawArgs(argv: readonly string[]): readonly string[];
+  /**
+   * Whether the arguments ask for the version and nothing else.
+   *
+   * @param argv - The arguments after the executable's name.
+   */
+  static isVersionRequest(argv: readonly string[]): boolean;
+  /** The version of this package, which `--version` prints. */
+  static version(): string;
+}
+//#endregion
+export type { InitArguments, InitOptions, RegistryAccessReport, RegistryAccessStatusValue };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { i as RegistryAccessStatus, n as InitCommand, r as RegistryAccess, t as CreateFrontDoor } from "./front-door-CJboxy5n.mjs";
+export { CreateFrontDoor, InitCommand, RegistryAccess, RegistryAccessStatus };

package/package.json

@@ -1,11 +1,53 @@
 {
   "name": "create-inferative",
-  "version": "0.0.0",
-  "description": "Placeholder. The first release publishes the real package.",
-  "license": "MIT",
+  "version": "0.2.0-next.20261013180716",
+  "description": "Create a new Inferative project: the `npm create inferative` command, which installs from public npm only.",
+  "keywords": [
+    "create",
+    "inferative",
+    "scaffolding",
+    "starter"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/inferative/inferative.git",
     "directory": "packages/create-inferative"
+  },
+  "bin": {
+    "create-inferative": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "citty": "0.1.6",
+    "giget": "^3.3.1",
+    "nypm": "^0.6.9",
+    "tinyexec": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^6.0.3",
+    "vite-plus": "1.0.0",
+    "vitest": "5.0.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vitest run"
   }
-}
+}