@theholocron/cli 5.0.0-alpha.4 → 5.0.0-alpha.40

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 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 path, { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { checkbox, input, select } from "@inquirer/prompts";
 import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
@@ -1233,6 +1233,40 @@ function commandsInContext(context) {
 }
 //#endregion
 //#region src/commands/deploy.ts
+/**
+* `holocron deploy` — trigger a deployment via the configured
+* `deployment` capability.
+*
+* Two modes, one command: `runDeploy` (the default — a Git branch,
+* `triggerDeployment()`) and `runDeployFromFiles` (`--files <dir>` —
+* a local directory of source files, `deployFunction()`, no linked
+* repo required — for a consumer with no Git history to deploy from,
+* e.g. Sentinel, shipped as an npm package). Separate functions, not
+* one branching `runDeploy`, because their inputs genuinely differ
+* (`branch` vs `dir`) and their result shapes differ too
+* (`DeploymentRecord` carries `status`/`branch`; `DeployFunctionResult`
+* is deliberately minimal, same as `DeployScriptResult` for Workers).
+*
+* Errors clearly when `deployment` isn't loaded (no provider declared
+* in `holocron.config.json`), or when the configured provider doesn't
+* implement `deployFunction` (it's optional on `Deployment` — not
+* every provider has a files-based deploy API).
+*
+* Dry-run skips the actual deploy call but still verifies the
+* deployment capability (and, for `--files`, `deployFunction`) is
+* present, so operators can sanity-check the wiring without spinning
+* up a build.
+*/
+/**
+* Provider `url` fields (Vercel's REST API, at least) come back as bare
+* hostnames — `"my-app.vercel.app"`, no scheme — which terminals don't
+* linkify and browsers won't navigate to unmodified. Printed output
+* should be a URL a human can click/paste; structured log fields keep
+* the raw provider value as-is.
+*/
+function withScheme(url) {
+	return /^https?:\/\//.test(url) ? url : `https://${url}`;
+}
 async function runDeploy(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const logger = input.logger ?? getLogger();
@@ -1264,7 +1298,7 @@ async function runDeploy(input) {
 			branch: input.branch,
 			...input.target ? { target: input.target } : {}
 		}));
-		print(`  ${style.success(`${record.status} — ${record.url}`)}`);
+		print(`  ${style.success(`${record.status} — ${withScheme(record.url)}`)}`);
 		logger.info({
 			status: record.status,
 			url: record.url,
@@ -1288,6 +1322,87 @@ async function runDeploy(input) {
 		};
 	}
 }
+const SKIP_DIRS$2 = /* @__PURE__ */ new Set([
+	".git",
+	"node_modules",
+	".turbo"
+]);
+/** Recursively lists absolute file paths under `dir`, skipping VCS/tooling noise. */
+function defaultWalkFiles$2(dir) {
+	const results = [];
+	for (const entry of readdirSync(dir)) {
+		if (SKIP_DIRS$2.has(entry)) continue;
+		const full = join(dir, entry);
+		const stat = statSync(full);
+		if (stat.isDirectory()) results.push(...defaultWalkFiles$2(full));
+		else if (stat.isFile()) results.push(full);
+	}
+	return results;
+}
+/** `holocron deploy --files <dir>` — the non-git counterpart to `runDeploy`. */
+async function runDeployFromFiles(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "deploy");
+	const dryRun = input.context.dryRun ?? false;
+	const walkFiles = input.walkFiles ?? defaultWalkFiles$2;
+	const readFile = input.readFile ?? ((p) => readFileSync(p, "utf8"));
+	const files = {};
+	for (const abs of walkFiles(input.dir)) {
+		const rel = relative(input.dir, abs).split(sep).join("/");
+		files[rel] = readFile(abs);
+	}
+	const fileCount = Object.keys(files).length;
+	logger.info({
+		dir: input.dir,
+		fileCount,
+		target: input.target ?? "preview",
+		projectId: input.projectId,
+		dryRun: dryRun || void 0
+	}, "deploy: start (files)");
+	print(style.header(`Holocron deploy — files=${input.dir} (${fileCount} file${fileCount === 1 ? "" : "s"})${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`));
+	if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
+	const deploy = loader.get("deployment");
+	if (!deploy.deployFunction) throw new Error(`deployment provider "${deploy.providerName}" does not support deploying from files — deployFunction() is not implemented`);
+	if (dryRun) {
+		const message = `would: ${deploy.providerName}.deployFunction(projectId=${input.projectId}, files=${fileCount}${input.target ? `, target=${input.target}` : ""})`;
+		print(`  ${style.dim(`… ${message}`)}`);
+		return {
+			deployment: null,
+			status: "dry-run",
+			message
+		};
+	}
+	try {
+		const result = await withSpinner(`Deploying ${fileCount} file${fileCount === 1 ? "" : "s"} from ${input.dir}…`, () => deploy.deployFunction(input.projectId, {
+			files,
+			...input.target ? { target: input.target } : {}
+		}));
+		print(`  ${style.success(withScheme(result.url))}`);
+		logger.info({
+			url: result.url,
+			id: result.deploymentId
+		}, "deploy: triggered (files)");
+		return {
+			deployment: result,
+			status: "ok"
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		print(`  ${style.fail(message)}`);
+		logger.warn({
+			dir: input.dir,
+			reason: message
+		}, "deploy: failed (files)");
+		return {
+			deployment: null,
+			status: "fail",
+			message
+		};
+	}
+}
 //#endregion
 //#region src/commands/doctor.ts
 async function runDoctor(input) {
@@ -3324,6 +3439,170 @@ async function runPublish(input = {}) {
 		packageNames
 	};
 }
+/**
+* `holocron publish` (no `--initial`) — the steady-state publish
+* `exec.publishCmd` in `release.config.ts` should call, replacing each
+* repo's hand-typed `pnpm -r --filter=./packages/* publish ...` shell (which
+* differs, today, only in monorepo-vs-single-package, provenance on/off, and
+* whether a repo needs to skip already-published packages) with one uniform
+* invocation. Part of the config-resolution workstream, #676 — see
+* `.notes/tech-config-resolution.spec.md`.
+*
+* Deliberately does not do the `--initial` bootstrap dance (npm
+* login-if-needed, Trusted Publisher next-steps printout) — a steady-state
+* publish runs in CI, authenticated via OIDC automatically, no interactive
+* step involved. Reuses `hasPackagesDir()`'s monorepo-vs-single-package
+* detection rather than duplicating it.
+*/
+async function runSteadyPublish(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const cwd = input.cwd ?? process.cwd();
+	const tag = input.tag ?? "latest";
+	const dryRun = input.dryRun ?? false;
+	const otp = input.otp;
+	const exec = input.exec ?? defaultExec$1;
+	const provenance = input.provenance ?? true;
+	const skipAlreadyPublished = input.skipAlreadyPublished ?? false;
+	const entries = input.packages ?? discoverPublicPackageEntries(cwd);
+	const packageNames = entries.map((e) => e.name);
+	print(`Holocron publish${dryRun ? " (dry-run)" : ""}`);
+	print(`  cwd: ${cwd}`);
+	print(`  tag: ${tag}`);
+	print(`  provenance: ${provenance}`);
+	if (skipAlreadyPublished) print("  skip-already-published: true");
+	logger.info({
+		tag,
+		provenance,
+		skipAlreadyPublished,
+		dryRun: dryRun || void 0
+	}, "publish: start");
+	if (otp) print(`  otp: <${otp.length} chars>`);
+	print("");
+	if (entries.length === 0) {
+		const message = "nothing to publish (no packages/* and root package.json is private or unnamed)";
+		print(`  ✗ ${message}`);
+		logger.warn({ reason: message }, "publish: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	const baseFlags = [
+		"--access",
+		"public",
+		"--no-git-checks",
+		"--tag",
+		tag,
+		...provenance ? ["--provenance"] : []
+	];
+	const otpFlags = otp ? ["--otp", otp] : [];
+	if (dryRun) {
+		print("");
+		if (skipAlreadyPublished) for (const entry of entries) print(`  … would check ${entry.name}@${entry.version}, publish if not already on npm`);
+		else {
+			const args = [
+				...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+				"publish",
+				...baseFlags,
+				...otpFlags
+			];
+			print(`  … (dry-run) skipping actual publish`);
+			print(`    would run: pnpm ${args.join(" ")}`);
+		}
+		logger.info({
+			tag,
+			status: "dry-run",
+			packages: entries.length
+		}, "publish: done");
+		return {
+			status: "dry-run",
+			message: "dry-run — no publish executed",
+			packageNames
+		};
+	}
+	if (skipAlreadyPublished) {
+		print("  → publishing packages not already on npm…");
+		for (const entry of entries) {
+			const view = await exec("npm", [
+				"view",
+				`${entry.name}@${entry.version}`,
+				"version"
+			], { cwd });
+			if (view.exitCode === 0 && view.stdout.trim()) {
+				print(`    skip ${entry.name}@${entry.version} (already published)`);
+				continue;
+			}
+			const publish = await exec("pnpm", [
+				"--filter",
+				entry.dir,
+				"publish",
+				...baseFlags,
+				...otpFlags
+			], { cwd });
+			if (publish.exitCode !== 0) {
+				const message = `publish failed for ${entry.name}@${entry.version} (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
+				print(`  ✗ ${message}`);
+				logger.warn({
+					tag,
+					package: entry.name,
+					reason: message
+				}, "publish: done");
+				return {
+					status: "fail",
+					message,
+					packageNames
+				};
+			}
+			print(`    ✓ ${entry.name}@${entry.version}`);
+		}
+		logger.info({
+			tag,
+			status: "ok",
+			packages: entries.length
+		}, "publish: done");
+		return {
+			status: "ok",
+			packageNames
+		};
+	}
+	print("  → publishing all public @theholocron/* packages…");
+	const publish = await exec("pnpm", [
+		...hasPackagesDir(cwd) ? ["-r", "--filter=./packages/*"] : [],
+		"publish",
+		...baseFlags,
+		...otpFlags
+	], { 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 holocron publish --otp <6-digit-code>`);
+		}
+		logger.warn({
+			tag,
+			reason: message
+		}, "publish: done");
+		return {
+			status: "fail",
+			message,
+			packageNames
+		};
+	}
+	print("    ✓ publish complete");
+	logger.info({
+		tag,
+		status: "ok",
+		packages: entries.length
+	}, "publish: done");
+	return {
+		status: "ok",
+		packageNames
+	};
+}
 function hasPackagesDir(cwd) {
 	return existsSync(join(cwd, "packages"));
 }
@@ -3337,6 +3616,37 @@ function publicPackageName(pkgPath) {
 		return;
 	}
 }
+/** Read a `package.json`'s `name` + `version`, when it's public (`!private && name`). */
+function publicPackageEntry(pkgPath, dir) {
+	if (!existsSync(pkgPath)) return void 0;
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		return !pkg.private && pkg.name && pkg.version ? {
+			name: pkg.name,
+			version: pkg.version,
+			dir
+		} : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Same repo-layout detection as {@link discoverPublicPackages}, but carrying
+* version + a `pnpm --filter`-ready path — {@link runSteadyPublish}'s
+* `skipAlreadyPublished` mode needs both to check `npm view <pkg>@<version>`
+* and publish one workspace at a time.
+*/
+function discoverPublicPackageEntries(cwd) {
+	if (!hasPackagesDir(cwd)) {
+		const entry = publicPackageEntry(join(cwd, "package.json"), ".");
+		return entry ? [entry] : [];
+	}
+	const packagesDir = join(cwd, "packages");
+	return readdirSync(packagesDir, { withFileTypes: true }).filter((e) => e.isDirectory()).flatMap((e) => {
+		const entry = publicPackageEntry(join(packagesDir, e.name, "package.json"), `./packages/${e.name}`);
+		return entry ? [entry] : [];
+	});
+}
 /**
 * Monorepo (`packages/` present): every public `packages/*` workspace.
 * Single package (no `packages/`): the root `package.json`, if it's public —
@@ -3601,6 +3911,104 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
+//#region src/commands/setup/derived-properties.ts
+/**
+* Repo archetype, in priority order:
+* 1. `*-template` repo name → `template` (independent of package shape).
+* 2. Monorepo whose primary published artifact is a CLI (some workspace
+*    package has `bin`) → `platform` — matches `holocron` itself: the CLI is
+*    the deliverable, the plugin packages are supporting infrastructure for
+*    it, not separate products.
+* 3. Monorepo with no CLI but at least one non-private workspace package →
+*    `library` — matches `clients`/`configs`/`utils`/`themes`/
+*    `observability`: a family of published packages, none of them a CLI.
+*    Checked *before* falling into the root-package branch below, because
+*    these repos' own root `package.json` is private and often carries
+*    `@theholocron/astro-config` for a docs site built from the monorepo
+*    root — without this check they'd wrongly resolve to `docs` off that
+*    root-level signal alone, when the docs site is a secondary concern of
+*    a library collection, not what the repo fundamentally is.
+* 4. Single-package repo with `package.json#bin` → `cli`.
+* 5. Docs-only site (astro/starlight present, root package private, no
+*    publishable exports) → `docs`.
+* 6. Private, non-publishable, non-docs → `app`.
+* 7. Otherwise, a single publishable package → `library`.
+*/
+function deriveProfile(input) {
+	if (/-template$/.test(input.repoName)) return "template";
+	if (input.isMonorepo) {
+		if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
+		if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
+	}
+	const pkg = input.rootPackageJson;
+	if (pkg?.bin) return "cli";
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	const isDocsSite = Boolean(deps["@theholocron/astro-config"] || deps["astro"]);
+	if (pkg?.private && isDocsSite) return "docs";
+	if (pkg?.private) return "app";
+	return "library";
+}
+const KNOWN_STACK_DEPS = [
+	"next",
+	"vite",
+	"astro",
+	"tsdown",
+	"rollup",
+	"webpack",
+	"storybook",
+	"vitest",
+	"playwright",
+	"turbo"
+];
+/**
+* Detected build/framework tooling — the literal "does this repo need
+* next/vite/tsdown" signal `holocron.config.ts` has no field for today
+* (framework choice isn't a config concept, unlike `providers`/`tasks`).
+* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
+* frameworks show up rather than trying to detect anything on npm.
+*/
+function deriveStack(pkg) {
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	return KNOWN_STACK_DEPS.filter((name) => name in deps);
+}
+/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
+function deriveCapabilities(providers) {
+	return Object.keys(providers ?? {}).sort();
+}
+/**
+* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* touches wires — every `holocron.config.ts` in this org already satisfies
+* this, so `non-compliant` here means drift (a provider manually removed
+* after setup), not an unmet aspirational policy. Deliberately not a richer
+* per-profile policy yet (e.g. "a `library` must have `deployment`") — that's
+* a Phase B (GitHub App) refinement once it can post *why* on a check run.
+*/
+const REQUIRED_BASELINE = ["source", "ci"];
+function deriveCompliance(capabilities) {
+	return REQUIRED_BASELINE.every((key) => capabilities.includes(key)) ? "compliant" : "non-compliant";
+}
+/**
+* Reads each workspace package's actual `package.json` content (not just
+* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
+* `platform` detection needs `bin`, which that helper doesn't carry).
+* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
+* own soft-fail behavior.
+*/
+async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
+	const results = [];
+	for (const { slug, dir = "packages" } of workspacePackages) try {
+		const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
+		results.push(JSON.parse(raw));
+	} catch {}
+	return results;
+}
+//#endregion
 //#region src/commands/setup/labels.ts
 const CANONICAL_LABELS = [
 	{
@@ -3749,12 +4157,21 @@ var alexrc_default = { allow: [
 ] };
 //#endregion
 //#region src/templates/configs/alexjs/create-config.ts
-const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cli/src/templates/configs/alexjs/create-config.ts" });
+const { workflowHeader: workflowHeader$9 } = createHeader({ source: "packages/cli/src/templates/configs/alexjs/create-config.ts" });
 function createRcConfig() {
 	return JSON.stringify(alexrc_default, null, 2) + "\n";
 }
 function createIgnoreConfig$1() {
-	return `${workflowHeader$8()}${alexignore_default}`;
+	return `${workflowHeader$9()}${alexignore_default}`;
+}
+//#endregion
+//#region src/templates/configs/commit-msg/commit-msg
+var commit_msg_default = "# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to commitlint's own auto-discovery of a local commitlint.config.ts when\n# the shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nCOMMITLINT_CONFIG=\"node_modules/@theholocron/commitlint-config/dist/index.js\"\nif [ -f \"$COMMITLINT_CONFIG\" ]; then\n	npx --no -- commitlint --config \"$COMMITLINT_CONFIG\" --edit \"$1\"\nelse\n	npx --no -- commitlint --edit \"$1\"\nfi\n";
+//#endregion
+//#region src/templates/configs/commit-msg/create-config.ts
+const { workflowHeader: workflowHeader$8 } = createHeader({ source: "packages/cli/src/templates/configs/commit-msg/create-config.ts" });
+function createConfig$7() {
+	return `${workflowHeader$8("shebang")}${commit_msg_default}`;
 }
 //#endregion
 //#region src/templates/configs/devmoji/create-config.ts
@@ -3859,7 +4276,7 @@ function createConfig$2(holocronScript = "pnpm exec holocron") {
 }
 //#endregion
 //#region src/templates/configs/prepare-commit-msg/prepare-commit-msg
-var prepare_commit_msg_default = "NAME=$(git config user.name)\nEMAIL=$(git config user.email)\n\nif [ -z \"$NAME\" ]; then\n	echo \"empty git config user.name\"\n	exit 1\nfi\n\nif [ -z \"$EMAIL\" ]; then\n	echo \"empty git config user.email\"\n	exit 1\nfi\n\ngit interpret-trailers --if-exists doNothing --trailer \\\n	\"Signed-off-by: $NAME <$EMAIL>\" \\\n	--in-place \"$1\"\n\nnpx devmoji -e\n";
+var prepare_commit_msg_default = "NAME=$(git config user.name)\nEMAIL=$(git config user.email)\n\nif [ -z \"$NAME\" ]; then\n	echo \"empty git config user.name\"\n	exit 1\nfi\n\nif [ -z \"$EMAIL\" ]; then\n	echo \"empty git config user.email\"\n	exit 1\nfi\n\ngit interpret-trailers --if-exists doNothing --trailer \\\n	\"Signed-off-by: $NAME <$EMAIL>\" \\\n	--in-place \"$1\"\n\n# --config <resolved shared path> (config-resolution workstream, #676) — falls\n# back to devmoji's own auto-discovery of a local devmoji.config.cjs when the\n# shared package's built dist/ isn't present (not installed, or a stale\n# install predating this file).\nDEVMOJI_CONFIG=\"node_modules/@theholocron/devmoji-config/dist/index.cjs\"\nif [ -f \"$DEVMOJI_CONFIG\" ]; then\n	npx devmoji --config \"$DEVMOJI_CONFIG\" -e\nelse\n	npx devmoji -e\nfi\n";
 //#endregion
 //#region src/templates/configs/prepare-commit-msg/create-config.ts
 const { workflowHeader: workflowHeader$3 } = createHeader({ source: "packages/cli/src/templates/configs/prepare-commit-msg/create-config.ts" });
@@ -4856,6 +5273,10 @@ async function runSetup(input) {
 			await source.writeRepoFile(".husky/prepare-commit-msg", createConfig$1());
 		}));
 		print(formatStep(steps[steps.length - 1]));
+		steps.push(await runStep("source", "write .husky/commit-msg", dryRun, async () => {
+			await source.writeRepoFile(".husky/commit-msg", createConfig$7());
+		}));
+		print(formatStep(steps[steps.length - 1]));
 		if (hooksEnabled) {
 			steps.push(await runStep("source", "write .husky/pre-push", dryRun, async () => {
 				await source.writeRepoFile(".husky/pre-push", createConfig$2(config.holocronScript));
@@ -4910,20 +5331,38 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		{
-			const content = createAstromech({
+			const astromechTurbo = createAstromech({
 				cwd: input.context.repoRoot,
 				config: { tasks: config.tasks },
 				logger
-			}).turboConfig();
+			});
+			const content = astromechTurbo.turboConfig();
 			if (content === null) steps.push({
 				capability: "source",
 				step: "write turbo.json",
 				status: "skip",
 				message: "no fan-out-eligible tasks configured"
 			});
-			else steps.push(await runStep("source", "write turbo.json", dryRun, async () => {
-				await source.writeRepoFile("turbo.json", content);
-			}));
+			else {
+				steps.push(await runStep("source", "write turbo.json", dryRun, async () => {
+					await source.writeRepoFile("turbo.json", content);
+				}));
+				print(formatStep(steps[steps.length - 1]));
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
+				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
+				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
+				if (workspaceFix.changed) steps.push(await runStep("source", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
+					await source.writeRepoFile("pnpm-workspace.yaml", workspaceFix.content);
+				}));
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) steps.push(await runStep("source", "add turbo devDependency", dryRun, async () => {
+						await source.writeRepoFile("package.json", depFix.content);
+					}));
+				}
+			}
 			print(formatStep(steps[steps.length - 1]));
 		}
 		if (source.syncLabels) {
@@ -4933,7 +5372,7 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		const properties = {};
-		if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
+		if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
 		const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
 		properties["monorepo"] = String(isMonorepo);
 		const manual = repo?.properties ?? {};
@@ -4941,6 +5380,21 @@ async function runSetup(input) {
 		if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
 		if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
 		if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+		{
+			const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+			const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+			const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+			properties["holocron_profile"] = deriveProfile({
+				rootPackageJson,
+				repoName: basename(input.context.repoRoot),
+				isMonorepo,
+				workspacePackageJsons
+			});
+			properties["holocron_stack"] = deriveStack(rootPackageJson);
+			const capabilities = deriveCapabilities(config.providers);
+			properties["holocron_capabilities"] = capabilities;
+			properties["holocron_compliance"] = deriveCompliance(capabilities);
+		}
 		if (source.syncProperties) {
 			steps.push(await runStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
 			print(formatStep(steps[steps.length - 1]));
@@ -5042,11 +5496,9 @@ async function runSetup(input) {
 		const wikiProxy = wiki.proxyConfig?.();
 		if (wikiDns && loader.has("dns")) {
 			const dns = loader.get("dns");
-			steps.push(await runStep("dns", `upsertRecord ${wikiDns.cname}`, dryRun, async () => {
+			steps.push(await runStep("dns", `upsertRecord ${wikiDns.record.name}`, dryRun, async () => {
 				await dns.upsertRecord(wikiDns.zone, {
-					type: "CNAME",
-					name: wikiDns.cname,
-					content: wikiDns.target,
+					...wikiDns.record,
 					ttl: 1,
 					...wikiProxy ? { proxied: true } : {}
 				});
@@ -5055,8 +5507,8 @@ async function runSetup(input) {
 		}
 		if (wikiProxy && wikiDns && loader.has("workers")) {
 			const workers = loader.get("workers");
-			steps.push(await runStep("workers", `upsertProxy ${wikiDns.cname}`, dryRun, async () => {
-				await workers.upsertProxy(wikiDns.cname, wikiProxy);
+			steps.push(await runStep("workers", `upsertProxy ${wikiDns.record.name}`, dryRun, async () => {
+				await workers.upsertProxy(wikiDns.record.name, wikiProxy);
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -5069,11 +5521,31 @@ async function runSetup(input) {
 			org: config.org,
 			domain: config.domain
 		}) : null;
+		const ensureCustomDomain = async (projectId, hostname) => {
+			if (!deploy.ensureCustomDomain) return;
+			const customDomainDns = { value: null };
+			steps.push(await runStep("deployment", `ensureCustomDomain ${hostname}`, dryRun, async () => {
+				customDomainDns.value = await deploy.ensureCustomDomain(projectId, hostname);
+			}));
+			print(formatStep(steps[steps.length - 1]));
+			if (customDomainDns.value && loader.has("dns")) {
+				const dns = loader.get("dns");
+				const dnsRecord = customDomainDns.value;
+				steps.push(await runStep("dns", `upsertRecord ${dnsRecord.record.name}`, dryRun, async () => {
+					await dns.upsertRecord(dnsRecord.zone, {
+						...dnsRecord.record,
+						ttl: 1
+					});
+				}));
+				print(formatStep(steps[steps.length - 1]));
+			}
+		};
 		if (!previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
 				await deploy.ensureProject({ name: config.name });
 			}));
 			print(formatStep(steps[steps.length - 1]));
+			if (deploy.domain) await ensureCustomDomain(config.name, deploy.domain);
 		}
 		if (previewCfg) {
 			steps.push(await runStep("deployment", `ensureProject ${previewCfg.project}`, dryRun, async () => {
@@ -5081,13 +5553,8 @@ async function runSetup(input) {
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
-		if (previewCfg?.domain && deploy.ensureCustomDomain) {
-			steps.push(await runStep("deployment", `ensureCustomDomain ${previewCfg.domain}`, dryRun, async () => {
-				await deploy.ensureCustomDomain(previewCfg.project, previewCfg.domain);
-			}));
-			print(formatStep(steps[steps.length - 1]));
-		}
-		if (previewCfg?.domain && loader.has("dns")) {
+		if (previewCfg?.domain) await ensureCustomDomain(previewCfg.project, previewCfg.domain);
+		if (previewCfg?.domain && deploy.providerName === "cloudflare" && loader.has("dns")) {
 			const dns = loader.get("dns");
 			const wildcardDomain = `*.${previewCfg.domain}`;
 			steps.push(await runStep("dns", `upsertRecord ${previewCfg.domain}`, dryRun, async () => {
@@ -5859,7 +6326,7 @@ async function runSync(input) {
 				const repo = config.repo;
 				const properties = {};
 				const effectivePreset = repo?.protection;
-				if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
+				if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
 				const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
 				properties["monorepo"] = String(isMonorepo);
 				const manual = repo?.properties ?? {};
@@ -5867,6 +6334,21 @@ async function runSync(input) {
 				if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
 				if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
 				if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+				{
+					const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+					const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+					const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+					properties["holocron_profile"] = deriveProfile({
+						rootPackageJson,
+						repoName: basename(input.context.repoRoot),
+						isMonorepo,
+						workspacePackageJsons
+					});
+					properties["holocron_stack"] = deriveStack(rootPackageJson);
+					const capabilities = deriveCapabilities(config.providers);
+					properties["holocron_capabilities"] = capabilities;
+					properties["holocron_compliance"] = deriveCompliance(capabilities);
+				}
 				steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
 				print(formatSyncStep(steps[steps.length - 1]));
 			} else {
@@ -6099,13 +6581,16 @@ async function runSync(input) {
 		} else {
 			const tasksConfig = { tasks: config.tasks };
 			if (config.holocronScript !== void 0) tasksConfig.holocronScript = config.holocronScript;
-			const desired = createAstromech({
+			const astromechScripts = createAstromech({
 				cwd: input.context.repoRoot,
 				config: tasksConfig,
 				logger
-			}).packageScripts();
+			});
+			const desired = astromechScripts.packageScripts();
+			const turboContent = astromechScripts.turboConfig();
+			const turboEligible = new Set(turboContent ? Object.keys(JSON.parse(turboContent).tasks) : []);
 			steps.push(await runSyncStep("local", "sync scripts", dryRun, async () => {
-				const changed = await mergePackageJsonScripts(input.context.repoRoot, desired);
+				const changed = await mergePackageJsonScripts(input.context.repoRoot, desired, turboEligible);
 				if (changed === null) return "no package.json";
 				if (changed.length === 0) return `${Object.keys(desired).length} scripts already current`;
 				return `${changed.join(", ")} set`;
@@ -6113,11 +6598,12 @@ async function runSync(input) {
 			print(formatSyncStep(steps[steps.length - 1]));
 		}
 		if (stepName === "turbo") {
-			const content = createAstromech({
+			const astromechTurbo = createAstromech({
 				cwd: input.context.repoRoot,
 				config: { tasks: config.tasks },
 				logger
-			}).turboConfig();
+			});
+			const content = astromechTurbo.turboConfig();
 			if (content === null) {
 				steps.push({
 					capability: "local",
@@ -6131,6 +6617,26 @@ async function runSync(input) {
 					await writeFile(join(input.context.repoRoot, "turbo.json"), content, "utf8");
 				}));
 				print(formatSyncStep(steps[steps.length - 1]));
+				const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
+				const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
+				const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
+				const rootScripts = Object.keys(rootPkg?.scripts ?? {});
+				const workspaceFix = astromechTurbo.ensureRootWorkspaceMember(workspaceYaml, rootScripts);
+				if (workspaceFix.changed) {
+					steps.push(await runSyncStep("local", "fix pnpm-workspace.yaml (root workspace member, #692)", dryRun, async () => {
+						await writeFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), workspaceFix.content, "utf8");
+					}));
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
+				if (rootPkgRaw) {
+					const depFix = astromechTurbo.ensureTurboDependency(rootPkgRaw, workspaceFix.content);
+					if (depFix.changed) {
+						steps.push(await runSyncStep("local", "add turbo devDependency", dryRun, async () => {
+							await writeFile(join(input.context.repoRoot, "package.json"), depFix.content, "utf8");
+						}));
+						print(formatSyncStep(steps[steps.length - 1]));
+					}
+				}
 			}
 		}
 		if (stepName === "wiki") {
@@ -6214,8 +6720,21 @@ async function writePackageJsonField(repoRoot, field, value) {
 * Merge `desired` script entries into `package.json#scripts` — sets only the
 * listed keys, never touches the rest. Returns the sorted list of keys that
 * drifted (empty when all current), or `null` when there is no `package.json`.
+*
+* `turboEligible` (#747): task names `turbo.json` fans out — the same set
+* {@link EnsureRootWorkspaceMemberResult} above already keys off. For those
+* only, an *existing* script that isn't the generated `holocron run <task>
+* --` wrapper is left untouched: root may genuinely be a directly-buildable
+* package (not an orchestrator) with its own real command (`tsc --noEmit`,
+* `vitest run`, …) for that task. Overwriting it would silently discard the
+* real command and, once `turbo.json` exists and root is a real workspace
+* member (#692), reintroduce infinite recursion — `turbo run <task>` →
+* root's own `<task>` script → the wrapper → `holocron run <task>` sees
+* `turbo.json` still defines the task → `turbo run <task>` again, forever.
+* Every other key (non-turbo tasks, `holocron`, `prepare`, …) has no
+* legitimate direct-command alternative and stays fully generator-owned.
 */
-async function mergePackageJsonScripts(repoRoot, desired) {
+async function mergePackageJsonScripts(repoRoot, desired, turboEligible) {
 	const pkgPath = join(repoRoot, "package.json");
 	let content;
 	try {
@@ -6226,15 +6745,31 @@ async function mergePackageJsonScripts(repoRoot, desired) {
 	const pkg = JSON.parse(content);
 	const scripts = pkg.scripts ?? {};
 	const changed = [];
-	for (const [name, command] of Object.entries(desired)) if (scripts[name] !== command) {
-		scripts[name] = command;
-		changed.push(name);
+	for (const [name, command] of Object.entries(desired)) {
+		const existing = scripts[name];
+		if (turboEligible.has(name) && existing !== void 0 && !isGeneratedRunWrapper(existing, name)) continue;
+		if (existing !== command) {
+			scripts[name] = command;
+			changed.push(name);
+		}
 	}
 	if (changed.length === 0) return [];
 	pkg.scripts = scripts;
 	await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
 	return changed.sort();
 }
+/**
+* Matches the exact shape `packageScripts()` generates for `taskName` —
+* `<bin> run <taskName> --`, `<bin>` normally `holocron` but substitutable
+* (`holocronScript`, itself allowed to be multi-word, e.g. `"node
+packages/cli/dist/cli.mjs"` — see its own test). Checking the *suffix*
+* rather than the whole string means an old wrapper survives a
+* `holocronScript` rename intact — it's still recognized as a wrapper (safe
+* to update to the new one), not mistaken for a real command.
+*/
+function isGeneratedRunWrapper(command, taskName) {
+	return command.endsWith(` run ${taskName} --`);
+}
 const README_DESC_START = "<!-- holocron:description -->";
 const README_DESC_END = "<!-- /holocron:description -->";
 async function updateReadmeDescription(repoRoot, description) {
@@ -7908,7 +8443,7 @@ try {
 		})).summary.fail > 0) process.exitCode = 1;
 	}).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
 		type: "string",
-		describe: "Git branch to deploy"
+		describe: "Git branch to deploy (omit when using --files)"
 	}).option("project-id", {
 		type: "string",
 		demandOption: true,
@@ -7917,20 +8452,34 @@ try {
 		type: "string",
 		choices: ["production", "staging"],
 		describe: "Named environment to deploy into. Omit for a branch preview."
-	}), async (argv) => {
+	}).option("files", {
+		type: "string",
+		describe: "Deploy from a local directory of source files instead of a Git branch — calls deployFunction(), no linked repo required. Conflicts with `branch`."
+	}).conflicts("files", "branch"), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
-		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
+		const context = {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...tokens,
+			org: resolveOrg(argv, loaded.resolved)
+		};
+		if (argv.files) {
+			if ((await runDeployFromFiles({
+				loaded,
+				context,
+				projectId: argv.projectId,
+				dir: argv.files,
+				...argv.target ? { target: argv.target } : {}
+			})).status === "fail") process.exitCode = 1;
+			return;
+		}
+		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		if ((await runDeploy({
 			loaded,
-			context: {
-				repoRoot: argv.cwd,
-				dryRun: argv.dryRun,
-				...tokens,
-				org: resolveOrg(argv, loaded.resolved)
-			},
+			context,
 			projectId: argv.projectId,
 			branch,
 			...argv.target ? { target: argv.target } : {}
@@ -7976,11 +8525,10 @@ try {
 	}).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."
+		describe: "One-shot bootstrap publish for trusted-publishing-eligible packages (npm needs the package to exist before Trusted Publishing can be configured for it). Skips the steady-state OIDC path below — use only for a package's very first publish."
 	}).option("tag", {
 		type: "string",
-		default: "alpha",
-		describe: "npm distribution tag (defaults to alpha)"
+		describe: "npm distribution tag. Defaults to alpha for --initial, latest for a steady-state publish."
 	}).option("otp", {
 		type: "string",
 		describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
@@ -7990,6 +8538,14 @@ try {
 	}).option("repo", {
 		type: "string",
 		describe: "owner/repo for Trusted Publisher config (--sync-trust). Defaults to theholocron/holocron."
+	}).option("provenance", {
+		type: "boolean",
+		default: true,
+		describe: "Publish with --provenance (steady-state only). Default on — free under CI/OIDC."
+	}).option("skip-already-published", {
+		type: "boolean",
+		default: false,
+		describe: "Steady-state only: check `npm view <pkg>@<version>` before publishing each package and skip it if that exact version already exists, instead of one bulk publish. For repos that ship many independently-versioned packages where a release doesn't bump every one."
 	}), async (argv) => {
 		if (argv.syncTrust) {
 			const [oldFile, newFile] = argv.syncTrust;
@@ -8007,15 +8563,21 @@ try {
 			})).status === "fail") process.exitCode = 1;
 			return;
 		}
-		if (!argv.initial) {
-			getLogger().error("publish: only `--initial` and `--sync-trust` are supported today. Run `holocron publish --initial`.");
-			process.exitCode = 1;
+		if (argv.initial) {
+			if ((await runPublish({
+				cwd: argv.cwd,
+				dryRun: argv.dryRun,
+				...argv.tag ? { tag: argv.tag } : {},
+				...argv.otp ? { otp: argv.otp } : {}
+			})).status === "fail") process.exitCode = 1;
 			return;
 		}
-		if ((await runPublish({
+		if ((await runSteadyPublish({
 			cwd: argv.cwd,
-			tag: argv.tag,
 			dryRun: argv.dryRun,
+			provenance: argv.provenance,
+			skipAlreadyPublished: argv.skipAlreadyPublished,
+			...argv.tag ? { tag: argv.tag } : {},
 			...argv.otp ? { otp: argv.otp } : {}
 		})).status === "fail") process.exitCode = 1;
 	}).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", {