@theholocron/cli 2.0.0-alpha.66 → 2.0.0-alpha.68

package/dist/cli.mjs

@@ -5,8 +5,10 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
-import { ProviderApiError, ProviderApiError as ProviderApiError$1 } from "@theholocron/http-client";
+import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1 } from "@theholocron/http-client";
 import { Entry, findCredentials } from "@napi-rs/keyring";
+import ora from "ora";
+import chalk from "chalk";
 import { createHash } from "node:crypto";
 import { createGitHubClient } from "@theholocron/github-client";
 import { execFile, execFileSync, spawnSync } from "node:child_process";
@@ -221,6 +223,35 @@ function listStoredProviders() {
 	}
 }
 //#endregion
+//#region src/ui/progress.ts
+/**
+* Runs `fn`, showing an ora spinner for its duration in TTY environments.
+* In non-TTY environments (CI, pipes, tests) the spinner is skipped entirely.
+*/
+async function withSpinner(label, fn) {
+	if (!process.stdout.isTTY) return fn();
+	const spinner = ora(label).start();
+	try {
+		const result = await fn();
+		spinner.succeed();
+		return result;
+	} catch (err) {
+		spinner.fail();
+		throw err;
+	}
+}
+//#endregion
+//#region src/ui/style.ts
+const style = {
+	success: (msg) => `${chalk.green("✓")} ${msg}`,
+	warn: (msg) => `${chalk.yellow("⚠")} ${msg}`,
+	fail: (msg) => `${chalk.red("✗")} ${msg}`,
+	step: (msg) => `${chalk.cyan("→")} ${msg}`,
+	hint: (msg) => chalk.dim(msg),
+	dim: (msg) => chalk.dim(msg),
+	header: (msg) => chalk.bold(msg)
+};
+//#endregion
 //#region src/commands/auth.ts
 /**
 * `holocron auth <subcommand>` — manage bootstrap credentials in the
@@ -263,11 +294,11 @@ async function runAuthSet(input) {
 	});
 	const packageName = resolvePluginPackage(provider);
 	if (!token) {
-		print(`no token supplied for \`${provider}\`.`);
-		print(`  pass as positional arg: holocron auth set ${provider} <token>`);
-		print(`  or via env: HOLOCRON_${provider.toUpperCase()}_TOKEN / ${provider.toUpperCase()}_TOKEN`);
+		print(style.fail(`no token supplied for \`${provider}\`.`));
+		print(style.hint(`  pass as positional arg: holocron auth set ${provider} <token>`));
+		print(style.hint(`  or via env: HOLOCRON_${provider.toUpperCase()}_TOKEN / ${provider.toUpperCase()}_TOKEN`));
 		const hint = await tryLoadHint(importer, packageName);
-		if (hint) print(`  hint: ${hint}`);
+		if (hint) print(style.hint(`  hint: ${hint}`));
 		return {
 			status: "fail",
 			message: "no token supplied"
@@ -279,27 +310,28 @@ async function runAuthSet(input) {
 		if (typeof module.verifyToken === "function") {
 			const verified = await module.verifyToken(token);
 			if (!verified.ok) {
-				print(`token rejected by ${provider}: ${verified.message}`);
-				if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+				print(style.fail(`token rejected by ${provider}: ${verified.message}`));
+				if (module.AUTH_HINT) print(style.hint(`  hint: ${module.AUTH_HINT}`));
 				return {
 					status: "fail",
 					message: verified.message
 				};
 			}
 			subject = verified.subject;
-		} else print(`(${provider} plugin has no verifyToken; storing without verification)`);
+		} else print(style.warn(`${provider} plugin has no verifyToken; storing without verification`));
 	} catch (err) {
-		print(`cannot verify token — failed to load ${packageName}: ${err instanceof Error ? err.message : String(err)}`);
-		print(`  storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`);
+		const msg = err instanceof Error ? err.message : String(err);
+		print(style.warn(`cannot verify token — failed to load ${packageName}: ${msg}`));
+		print(style.hint(`  storing token anyway; run 'holocron auth check ${provider}' once the plugin is installed`));
 	}
 	if (!setToken(provider, token)) {
-		print(`keyring unavailable — token not stored. Use env vars instead.`);
+		print(style.fail(`keyring unavailable — token not stored. Use env vars instead.`));
 		return {
 			status: "fail",
 			message: "keyring unavailable"
 		};
 	}
-	print(`stored ${provider} token${subject ? ` (${subject})` : ""}`);
+	print(style.success(`stored ${provider} token${subject ? ` (${subject})` : ""}`));
 	return {
 		status: "ok",
 		...subject ? { message: subject } : {}
@@ -308,10 +340,10 @@ async function runAuthSet(input) {
 function runAuthUnset(input) {
 	const print = input.print ?? ((l) => console.log(l));
 	if (deleteToken(input.provider)) {
-		print(`removed ${input.provider} token`);
+		print(style.success(`removed ${input.provider} token`));
 		return { status: "ok" };
 	}
-	print(`no stored token for ${input.provider}`);
+	print(style.dim(`no stored token for ${input.provider}`));
 	return {
 		status: "skip",
 		message: "nothing to remove"
@@ -323,7 +355,7 @@ async function runAuthCheck(input) {
 	const { provider } = input;
 	const token = getToken(provider);
 	if (!token) {
-		print(`no stored token for ${provider}`);
+		print(style.dim(`no stored token for ${provider}`));
 		return {
 			status: "skip",
 			message: "no stored token"
@@ -333,29 +365,30 @@ async function runAuthCheck(input) {
 	try {
 		const module = await importer(packageName);
 		if (typeof module.verifyToken !== "function") {
-			print(`${provider}: token stored (plugin has no verifyToken; can't confirm validity)`);
+			print(style.warn(`${provider}: token stored (plugin has no verifyToken; can't confirm validity)`));
 			return {
 				status: "ok",
 				message: "stored, unverified"
 			};
 		}
-		const verified = await module.verifyToken(token);
+		const verify = () => module.verifyToken(token);
+		const verified = input.showSpinner !== false ? await withSpinner(`Verifying ${provider} token…`, verify) : await verify();
 		if (verified.ok) {
-			print(`${provider}: ok — ${verified.subject}`);
+			print(style.success(`${provider}: ok — ${verified.subject}`));
 			return {
 				status: "ok",
 				message: verified.subject
 			};
 		}
-		print(`${provider}: rejected — ${verified.message}`);
-		if (module.AUTH_HINT) print(`  hint: ${module.AUTH_HINT}`);
+		print(style.fail(`${provider}: rejected — ${verified.message}`));
+		if (module.AUTH_HINT) print(style.hint(`  hint: ${module.AUTH_HINT}`));
 		return {
 			status: "fail",
 			message: verified.message
 		};
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
-		print(`${provider}: cannot verify — ${msg}`);
+		print(style.fail(`${provider}: cannot verify — ${msg}`));
 		return {
 			status: "fail",
 			message: msg
@@ -367,8 +400,8 @@ async function runAuthList(input = {}) {
 	const importer = input.importer ?? defaultImporter$1;
 	const providers = listStoredProviders();
 	if (providers.length === 0) {
-		print("no stored tokens.");
-		print("run: holocron auth set <provider> <token>");
+		print(style.dim("no stored tokens."));
+		print(style.hint("run: holocron auth set <provider> <token>"));
 		return {
 			status: "ok",
 			message: "none"
@@ -378,9 +411,13 @@ async function runAuthList(input = {}) {
 		const check = await runAuthCheck({
 			provider,
 			importer,
-			print: () => {}
+			print: () => {},
+			showSpinner: false
 		});
-		print(`  ${check.status === "ok" ? "✓" : check.status === "fail" ? "✗" : "·"} ${provider}${check.message ? ` — ${check.message}` : ""}`);
+		const label = `${provider}${check.message ? ` — ${check.message}` : ""}`;
+		if (check.status === "ok") print(`  ${style.success(label)}`);
+		else if (check.status === "fail") print(`  ${style.fail(label)}`);
+		else print(`  ${style.dim(`· ${label}`)}`);
 	}
 	return { status: "ok" };
 }
@@ -492,12 +529,12 @@ async function runDeploy(input) {
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
 	const dryRun = input.context.dryRun ?? false;
-	print(`Holocron deploy — branch=${input.branch}${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`);
+	print(style.header(`Holocron deploy — branch=${input.branch}${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 (dryRun) {
 		const message = `would: ${deploy.providerName}.triggerDeployment(projectId=${input.projectId}, branch=${input.branch}${input.target ? `, target=${input.target}` : ""})`;
-		print(`  … ${message}`);
+		print(`  ${style.dim(`… ${message}`)}`);
 		return {
 			deployment: null,
 			status: "dry-run",
@@ -505,19 +542,19 @@ async function runDeploy(input) {
 		};
 	}
 	try {
-		const record = await deploy.triggerDeployment({
+		const record = await withSpinner(`Deploying ${input.branch}${input.target ? ` → ${input.target}` : ""}…`, () => deploy.triggerDeployment({
 			projectId: input.projectId,
 			branch: input.branch,
 			...input.target ? { target: input.target } : {}
-		});
-		print(`  ✓ ${record.status} — ${record.url}`);
+		}));
+		print(`  ${style.success(`${record.status} — ${record.url}`)}`);
 		return {
 			deployment: record,
 			status: "ok"
 		};
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
-		print(`  ✗ ${message}`);
+		print(`  ${style.fail(message)}`);
 		return {
 			deployment: null,
 			status: "fail",
@@ -530,11 +567,11 @@ async function runDeploy(input) {
 async function runDoctor(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
+	await withSpinner("Loading plugins…", () => loader.load());
 	const rows = [];
 	const config = input.loaded.resolved;
-	print(`Holocron doctor — ${config.name}`);
-	print(`  config: ${input.loaded.filepath}`);
+	print(style.header(`Holocron doctor — ${config.name}`));
+	print(style.dim(`  config: ${input.loaded.filepath}`));
 	print("");
 	for (const key of loader.loadedKeys()) {
 		const cardinality = CARDINALITY[key];
@@ -554,7 +591,12 @@ async function runDoctor(input) {
 			rows.push(row);
 		}
 	}
-	for (const row of rows) print(`  ${row.status === "ok" ? "✓" : row.status === "fail" ? "✗" : "·"} ${pad(row.capability, 14)} via ${pad(row.provider, 14)}  ${row.message}`);
+	for (const row of rows) {
+		const label = `${pad(row.capability, 14)} via ${pad(row.provider, 14)}  ${row.message}`;
+		if (row.status === "ok") print(`  ${style.success(label)}`);
+		else if (row.status === "fail") print(`  ${style.fail(label)}`);
+		else print(`  ${style.dim(`· ${label}`)}`);
+	}
 	const summary = rows.reduce((acc, r) => {
 		acc[r.status] += 1;
 		return acc;
@@ -563,8 +605,9 @@ async function runDoctor(input) {
 		fail: 0,
 		skip: 0
 	});
+	const summaryLine = `${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped`;
 	print("");
-	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped`);
+	print(summary.fail > 0 ? style.fail(summaryLine) : style.success(summaryLine));
 	return {
 		rows,
 		summary
@@ -2612,22 +2655,22 @@ function describeScope(scope) {
 async function runSecretsSync(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
+	await withSpinner("Loading plugins…", () => loader.load());
 	const dryRun = input.context.dryRun ?? false;
 	const targets = input.targets ?? ["production", "preview"];
-	print(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`);
-	print(`  vault: ${vaultProviderName(loader)}`);
+	print(style.header(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`));
+	print(style.dim(`  vault: ${vaultProviderName(loader)}`));
 	print("");
 	const vault = loader.get("vault");
 	if (!vault.readEnvironment) throw new Error(`vault provider (${vault.providerName}) does not implement readEnvironment — sync needs bulk env reads`);
-	const envVars = await vault.readEnvironment(input.environmentId);
+	const envVars = await withSpinner(`Reading vault environment ${input.environmentId}…`, () => vault.readEnvironment(input.environmentId));
 	const keys = Object.keys(envVars).sort();
-	print(`  → read ${keys.length} keys from vault`);
+	print(style.step(`read ${keys.length} keys from vault`));
 	print("");
 	const rows = [];
 	if (loader.has("secrets")) {
 		const secrets = loader.get("secrets");
-		print("  → secrets (repo scope)");
+		print(style.step("secrets (repo scope)"));
 		for (const key of keys) {
 			rows.push(await runRow(`secrets:${secrets.providerName}`, "scope=repo", key, dryRun, async () => {
 				await secrets.setSecret({ kind: "repo" }, key, envVars[key]);
@@ -2638,7 +2681,7 @@ async function runSecretsSync(input) {
 	if (loader.has("deployment")) {
 		const deploy = loader.get("deployment");
 		if (!input.projectId) {
-			print("  → deployment");
+			print(style.step("deployment"));
 			const row = {
 				destination: `deployment:${deploy.providerName}`,
 				scope: "no projectId",
@@ -2649,7 +2692,7 @@ async function runSecretsSync(input) {
 			rows.push(row);
 			print(formatRow(row));
 		} else for (const target of targets) {
-			print(`  → deployment (target=${target})`);
+			print(style.step(`deployment (target=${target})`));
 			for (const key of keys) {
 				rows.push(await runRow(`deployment:${deploy.providerName}`, `target=${target}`, key, dryRun, async () => {
 					await deploy.setEnvVar(input.projectId, target, key, envVars[key]);
@@ -2671,7 +2714,8 @@ async function runSecretsSync(input) {
 		dryRun: 0
 	});
 	print("");
-	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
+	const summaryLine = `${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`;
+	print(summary.fail > 0 ? style.fail(summaryLine) : style.success(summaryLine));
 	return {
 		rows,
 		summary
@@ -2703,9 +2747,12 @@ async function runRow(destination, scope, key, dryRun, body) {
 	}
 }
 function formatRow(row) {
-	const icon = row.status === "ok" ? "✓" : row.status === "fail" ? "✗" : row.status === "dry-run" ? "…" : "·";
-	const detail = row.message ? `  (${row.message})` : "";
-	return `    ${icon} ${row.key}${detail}`;
+	const detail = row.message ? style.dim(`  (${row.message})`) : "";
+	const label = `${row.key}${detail}`;
+	if (row.status === "ok") return `    ${style.success(label)}`;
+	if (row.status === "fail") return `    ${style.fail(label)}`;
+	if (row.status === "dry-run") return `    ${style.dim(`… ${label}`)}`;
+	return `    ${style.dim(`· ${label}`)}`;
 }
 function vaultProviderName(loader) {
 	if (!loader.has("vault")) return "<missing>";
@@ -3122,18 +3169,18 @@ async function upsertBranchProtection(source, dryRun, requiredChecks) {
 async function runSetup(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
+	await withSpinner("Loading plugins…", () => loader.load());
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const steps = [];
 	const repo = config.repo;
 	const effectivePreset = repo?.protection;
-	print(`Holocron setup — ${config.name}${dryRun ? " (dry-run)" : ""}`);
-	print(`  config: ${input.loaded.filepath}`);
+	print(style.header(`Holocron setup — ${config.name}${dryRun ? " (dry-run)" : ""}`));
+	print(style.dim(`  config: ${input.loaded.filepath}`));
 	print("");
 	if (loader.has("source")) {
 		const source = loader.get("source");
-		print("  → source");
+		print(style.step("source"));
 		for (const method of [
 			"enableVulnerabilityAlerts",
 			"enableAutomatedSecurityFixes",
@@ -3173,7 +3220,7 @@ async function runSetup(input) {
 	const workflows = config.workflows;
 	if (loader.has("source") && workflows && workflows.length > 0) {
 		const source = loader.get("source");
-		print("  → workflows");
+		print(style.step("workflows"));
 		for (const entry of workflows) {
 			const name = typeof entry === "string" ? entry : entry.name;
 			const withOverrides = typeof entry === "object" ? entry.with : void 0;
@@ -3254,7 +3301,7 @@ async function runSetup(input) {
 	}
 	if (loader.has("environments")) {
 		const envs = loader.get("environments");
-		print("  → environments");
+		print(style.step("environments"));
 		for (const envName of ["staging", "production"]) {
 			steps.push(await runStep("environments", `upsert ${envName}`, dryRun, async () => {
 				await envs.upsertEnvironment({ name: envName });
@@ -3264,7 +3311,7 @@ async function runSetup(input) {
 	}
 	if (loader.has("deployment")) {
 		const deploy = loader.get("deployment");
-		print("  → deployment");
+		print(style.step("deployment"));
 		steps.push(await runStep("deployment", `ensureProject ${config.name}`, dryRun, async () => {
 			await deploy.ensureProject({ name: config.name });
 		}));
@@ -3272,7 +3319,7 @@ async function runSetup(input) {
 	}
 	if (loader.has("auth")) {
 		const auth = loader.get("auth");
-		print("  → auth");
+		print(style.step("auth"));
 		if (auth.ensureWebhookApp) {
 			steps.push(await runStep("auth", "ensureWebhookApp", dryRun, async () => {
 				return `webhook ${(await auth.ensureWebhookApp()).alreadyExists ? "exists" : "created"}`;
@@ -3290,7 +3337,7 @@ async function runSetup(input) {
 	}
 	if (loader.has("vault")) {
 		const vault = loader.get("vault");
-		print("  → vault");
+		print(style.step("vault"));
 		if (vault.ensureProject) {
 			steps.push(await runStep("vault", `ensureProject ${config.name}`, dryRun, async () => {
 				return `project ${(await vault.ensureProject(config.name)).alreadyExists ? "exists" : "created"}`;
@@ -3327,7 +3374,7 @@ async function runSetup(input) {
 	}
 	if (loader.has("tooling")) {
 		const tools = loader.get("tooling");
-		print("  → tooling");
+		print(style.step("tooling"));
 		for (const tool of tools) {
 			steps.push(await runStep("tooling", `${tool.providerName}.sync`, dryRun, async () => {
 				await tool.sync();
@@ -3348,23 +3395,24 @@ async function runSetup(input) {
 		dryRun: 0
 	});
 	print("");
-	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
+	const summaryLine = `  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`;
+	print(summary.fail > 0 ? style.fail(summaryLine.trim()) : style.success(summaryLine.trim()));
 	if (steps.some((s) => s.reason === "permissions")) {
 		print("");
-		print("  ⚠  Some steps failed with 403 (insufficient token permissions).");
-		print("     These operations require a temporary fine-grained PAT with the");
-		print("     following repository permissions:");
+		print(style.warn("Some steps failed with 403 (insufficient token permissions)."));
+		print(style.hint("     These operations require a temporary fine-grained PAT with the"));
+		print(style.hint("     following repository permissions:"));
 		print("");
-		print("       · Administration          — read and write");
-		print("       · Code scanning alerts    — read and write");
-		print("       · Contents                — read and write");
-		print("       · Secret scanning alerts  — read and write");
-		print("       · Workflows               — read and write");
-		print("       · Metadata                — read (added automatically)");
+		print(style.hint("       · Administration          — read and write"));
+		print(style.hint("       · Code scanning alerts    — read and write"));
+		print(style.hint("       · Contents                — read and write"));
+		print(style.hint("       · Secret scanning alerts  — read and write"));
+		print(style.hint("       · Workflows               — read and write"));
+		print(style.hint("       · Metadata                — read (added automatically)"));
 		print("");
-		print("     Create one at: https://github.com/settings/personal-access-tokens/new");
-		print("     Then re-run:   holocron setup --token <your-temp-pat>");
-		print("     You can revoke it immediately after setup completes.");
+		print(style.hint("     Create one at: https://github.com/settings/personal-access-tokens/new"));
+		print(style.hint("     Then re-run:   holocron setup --token <your-temp-pat>"));
+		print(style.hint("     You can revoke it immediately after setup completes."));
 	}
 	return {
 		steps,
@@ -3412,10 +3460,13 @@ function classify403(err) {
 	return "permissions";
 }
 function formatStep(step) {
-	const icon = step.status === "ok" ? "✓" : step.status === "fail" ? "✗" : step.status === "dry-run" ? "…" : "·";
 	const tag = step.reason === "permissions" ? " [permissions]" : step.reason === "plan" ? " [plan restriction]" : "";
-	const detail = step.message ? `  (${step.message})` : "";
-	return `    ${icon} ${step.step}${tag}${detail}`;
+	const detail = step.message ? style.dim(`  (${step.message})`) : "";
+	const label = `${step.step}${tag}${detail}`;
+	if (step.status === "ok") return `    ${style.success(label)}`;
+	if (step.status === "fail") return `    ${style.fail(label)}`;
+	if (step.status === "dry-run") return `    ${style.dim(`… ${label}`)}`;
+	return `    ${style.dim(`· ${label}`)}`;
 }
 //#endregion
 //#region src/commands/sync.ts
@@ -3426,14 +3477,20 @@ const SYNC_STEPS = [
 	"keywords",
 	"description"
 ];
+const LOCAL_STEPS = /* @__PURE__ */ new Set(["keywords", "description"]);
 async function runSync(input) {
 	const print = input.print ?? ((line) => console.log(line));
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
-	await loader.load();
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const requestedSteps = input.steps;
 	const steps = [];
+	if (!requestedSteps || requestedSteps.some((s) => !LOCAL_STEPS.has(s))) await loader.load();
+	else try {
+		await loader.load();
+	} catch (err) {
+		if (!(err instanceof AuthError)) throw err;
+	}
 	print(`Holocron sync — ${config.name}${dryRun ? " (dry-run)" : ""}`);
 	print(`  config: ${input.loaded.filepath}`);
 	print("");
@@ -3442,6 +3499,7 @@ async function runSync(input) {
 		print("  → source");
 		for (const stepName of SYNC_STEPS) {
 			if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
+			if (LOCAL_STEPS.has(stepName)) continue;
 			if (stepName === "labels") if (source.syncLabels) {
 				steps.push(await runSyncStep("source", "sync labels", dryRun, () => source.syncLabels(CANONICAL_LABELS, STALE_LABELS)));
 				print(formatSyncStep(steps[steps.length - 1]));
@@ -3500,47 +3558,6 @@ async function runSync(input) {
 					print(formatSyncStep(steps[steps.length - 1]));
 				}
 			}
-			if (stepName === "keywords") {
-				const topics = config.repo?.topics ?? [];
-				if (topics.length === 0) {
-					steps.push({
-						capability: "source",
-						step: "sync keywords",
-						status: "skip",
-						message: "no topics configured"
-					});
-					print(formatSyncStep(steps[steps.length - 1]));
-				} else {
-					steps.push(await runSyncStep("source", "sync keywords", dryRun, async () => {
-						return await writePackageJsonField(input.context.repoRoot, "keywords", topics) ? `${topics.length} keywords written` : `${topics.length} topics (no package.json)`;
-					}));
-					print(formatSyncStep(steps[steps.length - 1]));
-				}
-			}
-			if (stepName === "description") {
-				const description = config.description;
-				if (!description) {
-					steps.push({
-						capability: "source",
-						step: "sync description",
-						status: "skip",
-						message: "no description configured"
-					});
-					print(formatSyncStep(steps[steps.length - 1]));
-				} else {
-					steps.push(await runSyncStep("source", "sync description", dryRun, async () => {
-						const pkgWrote = await writePackageJsonField(input.context.repoRoot, "description", description);
-						const readmeWrote = await updateReadmeDescription(input.context.repoRoot, description);
-						if (source.syncDescription) await source.syncDescription(description);
-						const parts = [];
-						if (pkgWrote) parts.push("package.json");
-						if (readmeWrote) parts.push("README.md");
-						if (source.syncDescription) parts.push("GitHub");
-						return parts.length > 0 ? parts.join(", ") + " updated" : "description synced";
-					}));
-					print(formatSyncStep(steps[steps.length - 1]));
-				}
-			}
 		}
 		if (requestedSteps) {
 			for (const name of requestedSteps) if (!SYNC_STEPS.includes(name)) {
@@ -3554,6 +3571,51 @@ async function runSync(input) {
 			}
 		}
 	}
+	for (const stepName of ["keywords", "description"]) {
+		if (requestedSteps !== void 0 && !requestedSteps.includes(stepName)) continue;
+		if (stepName === "keywords") {
+			const topics = config.repo?.topics ?? [];
+			if (topics.length === 0) {
+				steps.push({
+					capability: "local",
+					step: "sync keywords",
+					status: "skip",
+					message: "no topics configured"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			} else {
+				steps.push(await runSyncStep("local", "sync keywords", dryRun, async () => {
+					return await writePackageJsonField(input.context.repoRoot, "keywords", topics) ? `${topics.length} keywords written` : `${topics.length} topics (no package.json)`;
+				}));
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
+		}
+		if (stepName === "description") {
+			const description = config.description;
+			if (!description) {
+				steps.push({
+					capability: "local",
+					step: "sync description",
+					status: "skip",
+					message: "no description configured"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			} else {
+				const source = loader.has("source") ? loader.get("source") : null;
+				steps.push(await runSyncStep("local", "sync description", dryRun, async () => {
+					const pkgWrote = await writePackageJsonField(input.context.repoRoot, "description", description);
+					const readmeWrote = await updateReadmeDescription(input.context.repoRoot, description);
+					if (source?.syncDescription) await source.syncDescription(description);
+					const parts = [];
+					if (pkgWrote) parts.push("package.json");
+					if (readmeWrote) parts.push("README.md");
+					if (source?.syncDescription) parts.push("GitHub");
+					return parts.length > 0 ? parts.join(", ") + " updated" : "description synced";
+				}));
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
+		}
+	}
 	const summary = steps.reduce((acc, s) => {
 		if (s.status === "ok") acc.ok += 1;
 		else if (s.status === "fail") acc.fail += 1;
@@ -3905,10 +3967,10 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 		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 source-level state (labels, properties, topics) from config to the provider", (y) => y.positional("steps", {
+}).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, topics, keywords, description)", (y) => y.positional("steps", {
 	type: "string",
 	array: true,
-	describe: "Steps to run: labels, properties, topics (default: all)"
+	describe: "Steps to run: labels, properties, topics, keywords, description (default: all)"
 }).option("repo", {
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.66",
+  "version": "2.0.0-alpha.68",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",
@@ -36,6 +36,8 @@
     "@napi-rs/keyring": "^1.3.0",
     "@theholocron/github-client": "^0.11.3",
     "@theholocron/http-client": "^0.11.3",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0",
     "tsx": "^4.22.4",
     "yargs": "^18.0.0"
   },