@theholocron/cli 4.17.0 → 4.17.2

package/README.md

@@ -424,7 +424,7 @@ holds the orchestration + the Holocron-specific credential resolution
   `astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
   never hand-edit its `.github/workflows/*`).
 - `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
-  `secrets sync`, `npm publish-initial`, `sync-github`, `upgrade node`,
+  `secrets sync`, `publish`, `bump-versions`, `sync-github`, `upgrade node`,
   `upgrade deps`, `plugin create`, `auth`
 
 ## Status

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
 import { checkbox, input, select } from "@inquirer/prompts";
-import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, reusableTemplates } from "@theholocron/astromech";
+import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -1208,8 +1208,8 @@ const COMMAND_CONTEXTS = {
 	"auth unset": "global",
 	"auth list": "global",
 	"auth check": "global",
-	"npm bump-versions": "global",
-	"npm publish-initial": "global",
+	"bump-versions": "global",
+	publish: "global",
 	"skills install": "global",
 	"skills remove": "global",
 	"skills update": "global",
@@ -1894,177 +1894,6 @@ async function runNpmBumpVersions(input) {
 	};
 }
 //#endregion
-//#region src/commands/npm-publish-initial.ts
-/**
-* `holocron npm publish-initial` — bottles up the chicken-and-egg
-* bootstrap that every new npm-published holocron monorepo hits.
-*
-* npm requires a package to exist before Trusted Publishing can be
-* configured on it. So the first publish has to happen outside the
-* OIDC flow — using either a browser-auth session (`npm login
-* --auth-type=web`) or an ephemeral automation token. This command
-* runs the publish step + tells you exactly what to do next.
-*
-* Workflow:
-*
-*   $ npm login --auth-type=web          # one-time, browser-based
-*   $ pnpm install --frozen-lockfile
-*   $ pnpm build
-*   $ pnpm exec tsx packages/cli/src/cli.ts npm publish-initial
-*
-* The command itself only handles the publish step + the post-publish
-* Trusted Publisher setup reminder. `pnpm install` + `pnpm build`
-* stay outside the command (no pnpm-inside-pnpm).
-*
-* If `NPM_TOKEN` is detected in env, the command prints a final
-* "revoke this token at <url>" reminder — same pattern as `rando vc
-* setup` for the ephemeral GH admin PAT.
-*/
-async function runNpmPublishInitial(input = {}) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
-	const cwd = input.cwd ?? process.cwd();
-	const tag = input.tag ?? "alpha";
-	const dryRun = input.dryRun ?? false;
-	const otp = input.otp;
-	const env = makeEnv(input.env);
-	const exec = input.exec ?? defaultExec$2;
-	const publishArgs = [
-		"-r",
-		"--filter=./packages/*",
-		"publish",
-		"--access",
-		"public",
-		"--no-git-checks",
-		"--tag",
-		tag,
-		...otp ? ["--otp", otp] : []
-	];
-	print(`Holocron npm publish-initial${dryRun ? " (dry-run)" : ""}`);
-	print(`  cwd: ${cwd}`);
-	print(`  tag: ${tag}`);
-	logger.info({
-		tag,
-		dryRun: dryRun || void 0
-	}, "npm publish-initial: start");
-	if (otp) print(`  otp: <${otp.length} chars>`);
-	print("");
-	print("  → verifying npm auth (`npm whoami`)…");
-	const whoami = await exec("npm", ["whoami"], { cwd });
-	if (whoami.exitCode !== 0) {
-		const message = "npm is not authenticated. Run `npm login --auth-type=web` (browser flow, no token stored) or `npm login`, then re-run this command.";
-		print(`  ✗ ${message}`);
-		const packageNames = input.packages ?? discoverPublicPackages(cwd);
-		logger.warn({ reason: "npm not authenticated" }, "npm publish-initial: done");
-		return {
-			status: "fail",
-			message,
-			packageNames
-		};
-	}
-	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
-	const packageNames = input.packages ?? discoverPublicPackages(cwd);
-	const repoName = input.repoName ?? await resolveRepoName(cwd, exec);
-	if (dryRun) {
-		print("");
-		print("  … (dry-run) skipping actual publish");
-		print(`    would run: pnpm ${publishArgs.join(" ")}`);
-		printNextSteps$1(print, env, packageNames, repoName);
-		logger.info({
-			tag,
-			status: "dry-run",
-			packages: packageNames.length
-		}, "npm publish-initial: done");
-		return {
-			status: "dry-run",
-			message: "dry-run — no publish executed",
-			packageNames
-		};
-	}
-	print("");
-	print("  → publishing all public @theholocron/* packages…");
-	const publish = await exec("pnpm", publishArgs, { cwd });
-	if (publish.exitCode !== 0) {
-		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
-		print(`  ✗ ${message}`);
-		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
-			print("");
-			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
-			print(`    pnpm exec tsx packages/cli/src/cli.ts npm publish-initial --otp <6-digit-code>`);
-		}
-		logger.warn({
-			tag,
-			reason: message
-		}, "npm publish-initial: done");
-		return {
-			status: "fail",
-			message,
-			packageNames
-		};
-	}
-	print("    ✓ publish complete");
-	printNextSteps$1(print, env, packageNames, repoName);
-	logger.info({
-		tag,
-		status: "ok",
-		packages: packageNames.length
-	}, "npm publish-initial: done");
-	return {
-		status: "ok",
-		packageNames
-	};
-}
-function discoverPublicPackages(cwd) {
-	const packagesDir = join(cwd, "packages");
-	if (!existsSync(packagesDir)) return [];
-	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
-		const pkgPath = join(packagesDir, e.name, "package.json");
-		if (!existsSync(pkgPath)) return [];
-		try {
-			const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-			return !pkg.private && pkg.name ? [pkg.name] : [];
-		} catch {
-			return [];
-		}
-	});
-}
-async function resolveRepoName(cwd, exec) {
-	const result = await exec("git", [
-		"remote",
-		"get-url",
-		"origin"
-	], { cwd });
-	if (result.exitCode !== 0) return "unknown";
-	return /[/:]([^/:]+?)(?:\.git)?$/.exec(result.stdout.trim())?.[1] ?? "unknown";
-}
-function printNextSteps$1(print, env, packageNames, repoName) {
-	print("");
-	print("  → next: configure Trusted Publisher for each package on npm:");
-	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
-	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: release.yml`);
-	if (env.get("NPM_TOKEN")) {
-		print("");
-		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
-		print("    https://www.npmjs.com/settings/~/tokens");
-	}
-}
-const defaultExec$2 = async (cmd, args, opts) => {
-	const result = spawnSync(cmd, args, {
-		cwd: opts.cwd,
-		encoding: "utf8",
-		stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		]
-	});
-	return {
-		exitCode: result.status ?? -1,
-		stdout: result.stdout ?? "",
-		stderr: result.stderr ?? ""
-	};
-};
-//#endregion
 //#region src/commands/plugin-create/template-inputs.ts
 /** Derive the standard defaults from a slug + vendor name. */
 function deriveDefaults$1(input) {
@@ -3037,7 +2866,7 @@ function runPluginCreate(input) {
 		filesWritten.push(resolvedPath);
 	}
 	if (!input.dryRun && !input.noVerify) {
-		const execFn = input.exec ?? defaultExec$1;
+		const execFn = input.exec ?? defaultExec$2;
 		const pkg = `@theholocron/holocron-plugin-${inputs.slug}`;
 		print("");
 		print("  Verifying scaffold…");
@@ -3088,7 +2917,7 @@ function runPluginCreate(input) {
 			};
 		}
 	}
-	if (!input.dryRun) printNextSteps(print, inputs);
+	if (!input.dryRun) printNextSteps$1(print, inputs);
 	logger.info({
 		slug: inputs.slug,
 		capability: inputs.capability,
@@ -3137,13 +2966,13 @@ function defaultWrite(filepath, content) {
 	mkdirSync(path.dirname(filepath), { recursive: true });
 	writeFileSync(filepath, content, "utf8");
 }
-function defaultExec$1(cmd, args, opts) {
+function defaultExec$2(cmd, args, opts) {
 	execFileSync(cmd, args, {
 		cwd: opts.cwd,
 		stdio: opts.stdio
 	});
 }
-function printNextSteps(print, inputs) {
+function printNextSteps$1(print, inputs) {
 	print("");
 	print(`  Scaffolded @theholocron/holocron-plugin-${inputs.slug} (18 files).`);
 	print("");
@@ -3157,6 +2986,235 @@ function printNextSteps(print, inputs) {
 	print("    7. Commit + push when capability is functionally complete.");
 }
 //#endregion
+//#region src/commands/publish.ts
+/**
+* `holocron publish --initial` — bottles up the chicken-and-egg bootstrap
+* that every new npm-published holocron monorepo hits.
+*
+* npm requires a package to exist before Trusted Publishing can be
+* configured on it. So the first publish has to happen outside the OIDC
+* flow — a browser-auth session (`npm login --auth-type=web`) or an
+* ephemeral automation token. This command drives the login step itself
+* (when `npm whoami` shows you're not authenticated), runs the publish
+* step, and tells you exactly what to do next.
+*
+* Workflow:
+*
+*   $ pnpm install --frozen-lockfile
+*   $ pnpm build
+*   $ pnpm exec tsx packages/cli/src/cli.ts publish --initial
+*
+* `npm login --auth-type=web` runs automatically the first time — no
+* separate manual step. `pnpm install` + `pnpm build` stay outside the
+* command (no pnpm-inside-pnpm).
+*
+* `--initial` is required today — this command only implements the
+* bootstrap publish. A non-initial `holocron publish` (for a manual publish
+* outside the semantic-release/OIDC steady state) isn't built yet; the flag
+* exists so the surface doesn't need another rename when it is.
+*
+* If `NPM_TOKEN` is detected in env, the command prints a final
+* "revoke this token at <url>" reminder — same pattern as `rando vc
+* setup` for the ephemeral GH admin PAT.
+*/
+async function runPublish(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const cwd = input.cwd ?? process.cwd();
+	const tag = input.tag ?? "alpha";
+	const dryRun = input.dryRun ?? false;
+	const otp = input.otp;
+	const env = makeEnv(input.env);
+	const exec = input.exec ?? defaultExec$1;
+	const login = input.login ?? defaultLogin;
+	const publishArgs = [
+		...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+		"publish",
+		"--access",
+		"public",
+		"--no-git-checks",
+		"--tag",
+		tag,
+		...otp ? ["--otp", otp] : []
+	];
+	print(`Holocron publish --initial${dryRun ? " (dry-run)" : ""}`);
+	print(`  cwd: ${cwd}`);
+	print(`  tag: ${tag}`);
+	logger.info({
+		tag,
+		dryRun: dryRun || void 0
+	}, "publish --initial: start");
+	if (otp) print(`  otp: <${otp.length} chars>`);
+	print("");
+	print("  → verifying npm auth (`npm whoami`)…");
+	let whoami = await exec("npm", ["whoami"], { cwd });
+	if (whoami.exitCode !== 0) {
+		print("    not authenticated — running `npm login --auth-type=web`…");
+		logger.info({}, "publish --initial: npm login");
+		if ((await login(cwd)).exitCode !== 0) {
+			const message = "npm login failed. Run `npm login --auth-type=web` (or `npm login`) manually, then re-run.";
+			print(`  ✗ ${message}`);
+			const packageNames = input.packages ?? discoverPublicPackages(cwd);
+			logger.warn({ reason: "npm login failed" }, "publish --initial: done");
+			return {
+				status: "fail",
+				message,
+				packageNames
+			};
+		}
+		whoami = await exec("npm", ["whoami"], { cwd });
+		if (whoami.exitCode !== 0) {
+			const message = "npm login completed but `npm whoami` still fails — check your npm account.";
+			print(`  ✗ ${message}`);
+			const packageNames = input.packages ?? discoverPublicPackages(cwd);
+			logger.warn({ reason: "npm whoami still fails after login" }, "publish --initial: done");
+			return {
+				status: "fail",
+				message,
+				packageNames
+			};
+		}
+	}
+	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
+	const packageNames = input.packages ?? discoverPublicPackages(cwd);
+	const repoName = input.repoName ?? await resolveRepoName(cwd, exec);
+	if (packageNames.length === 0) {
+		const message = "nothing to publish (no packages/* and root package.json is private or unnamed)";
+		print(`  ✗ ${message}`);
+		logger.warn({ reason: message }, "publish --initial: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	if (dryRun) {
+		print("");
+		print("  … (dry-run) skipping actual publish");
+		print(`    would run: pnpm ${publishArgs.join(" ")}`);
+		printNextSteps(print, env, packageNames, repoName);
+		logger.info({
+			tag,
+			status: "dry-run",
+			packages: packageNames.length
+		}, "publish --initial: done");
+		return {
+			status: "dry-run",
+			message: "dry-run — no publish executed",
+			packageNames
+		};
+	}
+	print("");
+	print("  → publishing all public @theholocron/* packages…");
+	const publish = await exec("pnpm", publishArgs, { cwd });
+	if (publish.exitCode !== 0) {
+		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
+		print(`  ✗ ${message}`);
+		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
+			print("");
+			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
+			print(`    pnpm exec tsx packages/cli/src/cli.ts publish --initial --otp <6-digit-code>`);
+		}
+		logger.warn({
+			tag,
+			reason: message
+		}, "publish --initial: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	print("    ✓ publish complete");
+	printNextSteps(print, env, packageNames, repoName);
+	logger.info({
+		tag,
+		status: "ok",
+		packages: packageNames.length
+	}, "publish --initial: done");
+	return {
+		status: "ok",
+		packageNames
+	};
+}
+function hasPackagesDir(cwd) {
+	return existsSync(join(cwd, "packages"));
+}
+/** Read a `package.json`'s `name`, when it's public (`!private && name`). */
+function publicPackageName(pkgPath) {
+	if (!existsSync(pkgPath)) return void 0;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		return !pkg.private && pkg.name ? pkg.name : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Monorepo (`packages/` present): every public `packages/*` workspace.
+* Single package (no `packages/`): the root `package.json`, if it's public —
+* most `node-template` scaffolds are one package at the repo root.
+*/
+function discoverPublicPackages(cwd) {
+	if (!hasPackagesDir(cwd)) {
+		const name = publicPackageName(join(cwd, "package.json"));
+		return name ? [name] : [];
+	}
+	const packagesDir = join(cwd, "packages");
+	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
+		const name = publicPackageName(join(packagesDir, e.name, "package.json"));
+		return name ? [name] : [];
+	});
+}
+async function resolveRepoName(cwd, exec) {
+	const result = await exec("git", [
+		"remote",
+		"get-url",
+		"origin"
+	], { cwd });
+	if (result.exitCode !== 0) return "unknown";
+	return /[/:]([^/:]+?)(?:\.git)?$/.exec(result.stdout.trim())?.[1] ?? "unknown";
+}
+function printNextSteps(print, env, packageNames, repoName) {
+	print("");
+	print("  → next: configure Trusted Publisher for each package on npm:");
+	for (const name of packageNames) print(`    https://www.npmjs.com/package/${name}/access`);
+	print(`    Publisher: GitHub Actions   Org: theholocron   Repo: ${repoName}   Workflow: release.yml`);
+	if (env.get("NPM_TOKEN")) {
+		print("");
+		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
+		print("    https://www.npmjs.com/settings/~/tokens");
+	}
+}
+const defaultExec$1 = async (cmd, args, opts) => {
+	const result = spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		exitCode: result.status ?? -1,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? ""
+	};
+};
+/**
+* Fully interactive — `npm login --auth-type=web` prints a URL and waits for
+* the browser flow to complete; the operator needs to see that live, so all
+* three stdio streams are inherited (unlike `defaultExec`, which pipes
+* stdout/stderr for capture).
+*/
+const defaultLogin = async (cwd) => {
+	return { exitCode: spawnSync("npm", ["login", "--auth-type=web"], {
+		cwd,
+		stdio: "inherit"
+	}).status ?? -1 };
+};
+//#endregion
 //#region src/commands/secret-set.ts
 async function runSecretSet(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -3512,86 +3570,6 @@ function createIgnoreConfig() {
 	return `${workflowHeader$6()}${alexignore_default}`;
 }
 //#endregion
-//#region src/templates/configs/codecov/codecov.yml
-var codecov_default = "codecov:\n  require_ci_to_pass: true\n\ncoverage:\n  precision: 2\n  round: down\n  status:\n    project:\n      default:\n        target: auto\n        threshold: 2%\n        # Infra-only PRs (dep bumps, config, lockfile) touch no coverable code,\n        # so codecov produces no report to compare. Pass instead of blocking\n        # forever on a required check that will never post.\n        if_not_found: success\n    patch:\n      default:\n        target: 80%\n        if_not_found: success\n\ncomment:\n  layout: \"reach,diff,flags,components\"\n  behavior: default\n  require_changes: true\n\ncomponent_management:\n  default_rules:\n    statuses:\n      - type: patch\n        target: 80%\n        if_not_found: success\n  individual_components:\n";
-//#endregion
-//#region src/templates/configs/codecov/utils.ts
-const INDIVIDUAL_COMPONENTS_MARKER = "  individual_components:";
-function codecovComponentBlock(packages) {
-	if (packages.length === 0) return "\n    []\n";
-	return "\n" + packages.flatMap(({ slug }) => [
-		`    - component_id: ${slug}`,
-		`      name: "${slug}"`,
-		`      paths:`,
-		`        - packages/${slug}/**`,
-		``
-	]).join("\n");
-}
-/**
-* Ensure every codecov status default carries `if_not_found: success`, so an
-* infra-only PR (dep bump, config, lockfile — no coverable change) passes
-* instead of hanging forever on a required check codecov never posts.
-*
-* Injects the key on the line after each `target:` that sits inside a status
-* block (`coverage.status.*.default` or a `statuses:` list item — indent ≥ 8,
-* or ≥ 8 for a `- type:` list entry), when the immediate sibling lines do not
-* already declare it.
-*/
-function ensureIfNotFound(yaml) {
-	const lines = yaml.split("\n");
-	const out = [];
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
-		out.push(line);
-		const m = /^(\s{8,})target:\s+\S+\s*$/.exec(line);
-		if (!m) continue;
-		const indent = m[1];
-		let alreadySet = false;
-		for (let j = i + 1; j < lines.length; j++) {
-			const sib = lines[j];
-			if (sib.trim() === "") continue;
-			const sibIndent = sib.match(/^\s*/)[0].length;
-			if (sibIndent < indent.length) break;
-			if (sibIndent === indent.length && /^\s*if_not_found\s*:/.test(sib)) {
-				alreadySet = true;
-				break;
-			}
-			if (sibIndent === indent.length && /^\s*(- |\w)/.test(sib) && !/^\s*(threshold|flags|paths|branches)\s*:/.test(sib)) break;
-		}
-		if (!alreadySet) out.push(`${indent}if_not_found: success`);
-	}
-	return out.join("\n");
-}
-function mergeCodecovComponents(existing, packages) {
-	const idx = existing.indexOf(INDIVIDUAL_COMPONENTS_MARKER);
-	if (idx === -1) return ensureIfNotFound(existing);
-	return ensureIfNotFound(existing.slice(0, idx + 24)) + codecovComponentBlock(packages);
-}
-async function readWorkspacePackages(repoRoot) {
-	const packagesDir = join(repoRoot, "packages");
-	const entries = await readdir(packagesDir, { withFileTypes: true }).catch(() => null);
-	if (!entries) return [];
-	const packages = [];
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		try {
-			const raw = await readFile(join(packagesDir, entry.name, "package.json"), "utf8");
-			const pkg = JSON.parse(raw);
-			if (typeof pkg.name === "string") packages.push({
-				slug: entry.name,
-				name: pkg.name
-			});
-		} catch {}
-	}
-	return packages.sort((a, b) => a.slug.localeCompare(b.slug));
-}
-//#endregion
-//#region src/templates/configs/codecov/create-config.ts
-const { scaffoldHeader } = createHeader({ source: "packages/cli/src/templates/configs/codecov/create-config.ts" });
-function createConfig$5(packages) {
-	return `${scaffoldHeader()}${codecov_default.trimEnd()}${codecovComponentBlock(packages)}`;
-}
-//#endregion
 //#region src/templates/configs/devmoji/create-config.ts
 const { workflowHeader: workflowHeader$5 } = createHeader({ source: "packages/cli/src/templates/configs/devmoji/create-config.ts" });
 function createConfig$4() {
@@ -4662,7 +4640,6 @@ async function runSetup(input) {
 		}
 		{
 			const hasTestWorkflow = (config.tasks ?? []).map((e) => typeof e === "string" ? e : e.name).includes("test");
-			const packages = await readWorkspacePackages(input.context.repoRoot);
 			const existing = await readFile(join(input.context.repoRoot, "codecov.yml"), "utf8").catch(() => null);
 			if (!hasTestWorkflow && existing == null) steps.push({
 				capability: "source",
@@ -4671,9 +4648,10 @@ async function runSetup(input) {
 				message: "no test workflow configured"
 			});
 			else steps.push(await runStep("source", "write codecov.yml", dryRun, async () => {
-				const content = existing != null ? mergeCodecovComponents(existing, packages) : createConfig$5(packages);
+				const content = createAstromech({ cwd: input.context.repoRoot }).codecovConfig(existing);
 				await source.writeRepoFile("codecov.yml", content);
-				return packages.length > 0 ? `${packages.length} components` : "no components";
+				const packageCount = readWorkspacePackages(input.context.repoRoot).length;
+				return packageCount > 0 ? `${packageCount} components` : "no components";
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -7337,7 +7315,7 @@ try {
 			project: argv.project,
 			...argv.repo ? { repo: argv.repo } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("npm", "npm-related monorepo utilities", (y) => y.command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (yy) => yy.positional("new-version", {
+	}).command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
 		type: "string",
 		demandOption: true,
 		describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
@@ -7347,7 +7325,11 @@ try {
 			cwd: argv.cwd,
 			dryRun: argv.dryRun
 		})).status === "fail") process.exitCode = 1;
-	}).command("publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (yy) => yy.option("tag", {
+	}).command("publish", "Publish @theholocron/* packages to npm", (y) => y.option("initial", {
+		type: "boolean",
+		default: false,
+		describe: "One-shot bootstrap publish for trusted-publishing-eligible packages (npm needs the package to exist before Trusted Publishing can be configured for it). Required today — a non-initial `publish` isn't implemented yet."
+	}).option("tag", {
 		type: "string",
 		default: "alpha",
 		describe: "npm distribution tag (defaults to alpha)"
@@ -7355,13 +7337,18 @@ try {
 		type: "string",
 		describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
 	}), async (argv) => {
-		if ((await runNpmPublishInitial({
+		if (!argv.initial) {
+			getLogger().error("publish: only `--initial` is supported today. Run `holocron publish --initial`.");
+			process.exitCode = 1;
+			return;
+		}
+		if ((await runPublish({
 			cwd: argv.cwd,
 			tag: argv.tag,
 			dryRun: argv.dryRun,
 			...argv.otp ? { otp: argv.otp } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).demandCommand(1, "Run `holocron npm --help` to see available npm subcommands."), () => {}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.positional("steps", {
+	}).command("sync [steps..]", "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)", (y) => y.positional("steps", {
 		type: "string",
 		array: true,
 		describe: "Steps to run: labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki (default: all)"