@theholocron/cli 3.58.1 → 3.60.0

package/dist/cli.mjs

@@ -11,9 +11,9 @@ import { Entry, findCredentials } from "@napi-rs/keyring";
 import { pathToFileURL } from "node:url";
 import ora from "ora";
 import chalk from "chalk";
+import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/logger";
 import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
-import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/logger";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
@@ -512,6 +512,94 @@ async function tryLoadHint(importer, packageName) {
 	}
 }
 //#endregion
+//#region src/logger.ts
+/**
+* CLI-side wiring for `@theholocron/logger`.
+*
+* `logger` is the operational-output channel — internal state, debug
+* traces, errors, structured context that routes to Axiom. It runs in
+* parallel to `print` (user-facing UX output) and does not replace it.
+*/
+/**
+* Resolve the explicit level to hand to `createLogger`, in priority order:
+*
+* 1. `--verbose` → `"debug"`   2. `--quiet` → `"error"`
+* 3. `HOLOCRON_LOG_LEVEL` env var
+* 4. `holocron.config` `log.level` (`configLevel`)
+*
+* Returns `undefined` when nothing applies — `createLogger` then defaults
+* to `"info"`. Resolving the full chain here (rather than passing
+* `configLevel` straight through) keeps config below the env var.
+*/
+function resolveLogLevel(argv, configLevel) {
+	if (argv.verbose) return "debug";
+	if (argv.quiet) return "error";
+	return parseLogLevel(env.get("HOLOCRON_LOG_LEVEL")) ?? configLevel;
+}
+let root;
+let rootLevel;
+let rootCommand;
+let rootAxiomKey;
+/**
+* Resolve Axiom credentials for the CLI. Env vars win — same contract as
+* `@theholocron/logger`'s `resolveAxiomFromEnv`. Failing that, the CLI-only
+* bridge pairs the OS-keyring token (`axiom.<org>` then bare `axiom`) with a
+* dataset from `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or
+* `holocron.config` `log.axiom.dataset`. Returns `undefined` unless both a
+* token and a dataset are found.
+*/
+function resolveCliAxiom(opts) {
+	const fromEnv = resolveAxiomFromEnv();
+	if (fromEnv) return fromEnv;
+	const dataset = env.get("HOLOCRON_AXIOM_DATASET") || env.get("AXIOM_DATASET") || opts.configAxiomDataset;
+	if (!dataset) return void 0;
+	const org = opts.org ?? env.get("HOLOCRON_ORG");
+	const token = (org ? getToken(`axiom.${org}`) : null) ?? getToken("axiom");
+	return token ? {
+		dataset,
+		token
+	} : void 0;
+}
+/**
+* The process-wide root logger. Built once (from `cli.ts`'s middleware,
+* with the command name + flags + env). Rebuilt at most once more when a
+* command's handler supplies `holocron.config` context the flag/env-only
+* first pass could not have known — `log.level` (unless `--verbose` /
+* `--quiet` already fixed it) or `log.axiom.dataset` + the resolved org
+* for a keyring-backed Axiom transport. That rebuild generates a fresh
+* `runId`, which is harmless: nothing logs between the middleware and the
+* handler.
+*/
+function buildCliLogger(argv, opts = {}) {
+	const { command, configLevel } = opts;
+	if (command) rootCommand = command;
+	const level = resolveLogLevel(argv, configLevel);
+	const axiom = resolveCliAxiom(opts);
+	const axiomKey = axiom?.dataset;
+	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet;
+	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
+		const built = createLogger({
+			...level ? { level } : {},
+			...axiom ? { axiom } : {}
+		});
+		root = {
+			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
+			runId: built.runId
+		};
+		rootLevel = level;
+		rootAxiomKey = axiomKey;
+	}
+	return root;
+}
+/** Lazily-memoized `Logger` for module-level call sites with no `argv` in scope. */
+function getLogger() {
+	return (root ??= createLogger()).logger;
+}
+/** The current root logger's correlation id, if a root has been built. */
+function getRunId() {
+	return root?.runId;
+}
+//#endregion
 //#region src/plugin/loader.ts
 /**
 * `PluginLoader` — loads provider plugins per the resolved config and
@@ -684,9 +772,14 @@ function prStateLabel(pr) {
 }
 async function runCleanupPreview(input) {
 	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
 	// c8 ignore next -- real PluginLoader construction is integration-level; unit tests always supply loader
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
+	logger.info({
+		pr: input.prNumber,
+		project: input.project
+	}, "cleanup-preview: start");
 	if (!loader.has("source")) throw new Error("source capability is not configured — add a source provider to holocron.config.json");
 	const source = loader.get("source");
 	if (!source.getPullRequest) throw new Error(`${source.providerName} source provider does not support getPullRequest`);
@@ -716,6 +809,13 @@ async function runCleanupPreview(input) {
 	}
 	if (deployments.length === 0) {
 		print(style.dim(`No deployments found for branch ${branch}.`));
+		logger.info({
+			pr: pr.number,
+			branch,
+			found: 0,
+			deleted: 0,
+			status: "none"
+		}, "cleanup-preview: done");
 		return {
 			pr,
 			branch,
@@ -768,6 +868,13 @@ async function runCleanupPreview(input) {
 	try {
 		const count = await deploy.deletePreviewDeployments(input.project, selected);
 		print(style.success(`Deleted ${count} deployment${count === 1 ? "" : "s"}.`));
+		logger.info({
+			pr: pr.number,
+			branch,
+			found: deployments.length,
+			deleted: count,
+			status: "ok"
+		}, "cleanup-preview: done");
 		return {
 			pr,
 			branch,
@@ -778,6 +885,13 @@ async function runCleanupPreview(input) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		print(style.fail(message));
+		logger.warn({
+			pr: pr.number,
+			branch,
+			found: deployments.length,
+			reason: message,
+			status: "fail"
+		}, "cleanup-preview: done");
 		return {
 			pr,
 			branch,
@@ -894,9 +1008,16 @@ async function runClone(input) {
 //#region src/commands/deploy.ts
 async function runDeploy(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();
 	const dryRun = input.context.dryRun ?? false;
+	logger.info({
+		branch: input.branch,
+		target: input.target ?? "preview",
+		projectId: input.projectId,
+		dryRun: dryRun || void 0
+	}, "deploy: start");
 	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");
@@ -916,6 +1037,11 @@ async function runDeploy(input) {
 			...input.target ? { target: input.target } : {}
 		}));
 		print(`  ${style.success(`${record.status} — ${record.url}`)}`);
+		logger.info({
+			status: record.status,
+			url: record.url,
+			id: record.id
+		}, "deploy: triggered");
 		return {
 			deployment: record,
 			status: "ok"
@@ -923,6 +1049,10 @@ async function runDeploy(input) {
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		print(`  ${style.fail(message)}`);
+		logger.warn({
+			branch: input.branch,
+			reason: message
+		}, "deploy: failed");
 		return {
 			deployment: null,
 			status: "fail",
@@ -931,94 +1061,6 @@ async function runDeploy(input) {
 	}
 }
 //#endregion
-//#region src/logger.ts
-/**
-* CLI-side wiring for `@theholocron/logger`.
-*
-* `logger` is the operational-output channel — internal state, debug
-* traces, errors, structured context that routes to Axiom. It runs in
-* parallel to `print` (user-facing UX output) and does not replace it.
-*/
-/**
-* Resolve the explicit level to hand to `createLogger`, in priority order:
-*
-* 1. `--verbose` → `"debug"`   2. `--quiet` → `"error"`
-* 3. `HOLOCRON_LOG_LEVEL` env var
-* 4. `holocron.config` `log.level` (`configLevel`)
-*
-* Returns `undefined` when nothing applies — `createLogger` then defaults
-* to `"info"`. Resolving the full chain here (rather than passing
-* `configLevel` straight through) keeps config below the env var.
-*/
-function resolveLogLevel(argv, configLevel) {
-	if (argv.verbose) return "debug";
-	if (argv.quiet) return "error";
-	return parseLogLevel(env.get("HOLOCRON_LOG_LEVEL")) ?? configLevel;
-}
-let root;
-let rootLevel;
-let rootCommand;
-let rootAxiomKey;
-/**
-* Resolve Axiom credentials for the CLI. Env vars win — same contract as
-* `@theholocron/logger`'s `resolveAxiomFromEnv`. Failing that, the CLI-only
-* bridge pairs the OS-keyring token (`axiom.<org>` then bare `axiom`) with a
-* dataset from `HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` or
-* `holocron.config` `log.axiom.dataset`. Returns `undefined` unless both a
-* token and a dataset are found.
-*/
-function resolveCliAxiom(opts) {
-	const fromEnv = resolveAxiomFromEnv();
-	if (fromEnv) return fromEnv;
-	const dataset = env.get("HOLOCRON_AXIOM_DATASET") || env.get("AXIOM_DATASET") || opts.configAxiomDataset;
-	if (!dataset) return void 0;
-	const org = opts.org ?? env.get("HOLOCRON_ORG");
-	const token = (org ? getToken(`axiom.${org}`) : null) ?? getToken("axiom");
-	return token ? {
-		dataset,
-		token
-	} : void 0;
-}
-/**
-* The process-wide root logger. Built once (from `cli.ts`'s middleware,
-* with the command name + flags + env). Rebuilt at most once more when a
-* command's handler supplies `holocron.config` context the flag/env-only
-* first pass could not have known — `log.level` (unless `--verbose` /
-* `--quiet` already fixed it) or `log.axiom.dataset` + the resolved org
-* for a keyring-backed Axiom transport. That rebuild generates a fresh
-* `runId`, which is harmless: nothing logs between the middleware and the
-* handler.
-*/
-function buildCliLogger(argv, opts = {}) {
-	const { command, configLevel } = opts;
-	if (command) rootCommand = command;
-	const level = resolveLogLevel(argv, configLevel);
-	const axiom = resolveCliAxiom(opts);
-	const axiomKey = axiom?.dataset;
-	const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet;
-	if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
-		const built = createLogger({
-			...level ? { level } : {},
-			...axiom ? { axiom } : {}
-		});
-		root = {
-			logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
-			runId: built.runId
-		};
-		rootLevel = level;
-		rootAxiomKey = axiomKey;
-	}
-	return root;
-}
-/** Lazily-memoized `Logger` for module-level call sites with no `argv` in scope. */
-function getLogger() {
-	return (root ??= createLogger()).logger;
-}
-/** The current root logger's correlation id, if a root has been built. */
-function getRunId() {
-	return root?.runId;
-}
-//#endregion
 //#region src/commands/doctor.ts
 async function runDoctor(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -2871,8 +2913,13 @@ function describeScope(scope) {
 //#region src/commands/secrets-sync.ts
 async function runSecretsSync(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 withSpinner("Loading plugins…", () => loader.load());
+	logger.info({
+		environment: input.environmentId,
+		dryRun: (input.context.dryRun ?? false) || void 0
+	}, "secrets sync: start");
 	const dryRun = input.context.dryRun ?? false;
 	const targets = input.targets ?? ["production", "preview"];
 	print(style.header(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`));
@@ -2918,6 +2965,13 @@ async function runSecretsSync(input) {
 			}
 		}
 	}
+	for (const r of rows) logger[r.status === "fail" ? "warn" : "info"]({
+		destination: r.destination,
+		scope: r.scope,
+		key: r.key,
+		status: r.status,
+		...r.message ? { detail: r.message } : {}
+	}, `secrets sync: ${r.key} → ${r.destination}`);
 	const summary = rows.reduce((acc, r) => {
 		if (r.status === "ok") acc.ok += 1;
 		else if (r.status === "fail") acc.fail += 1;
@@ -2930,6 +2984,10 @@ async function runSecretsSync(input) {
 		skip: 0,
 		dryRun: 0
 	});
+	logger[summary.fail > 0 ? "warn" : "info"]({
+		...summary,
+		keys: rows.length
+	}, "secrets sync: done");
 	print("");
 	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));
@@ -5299,12 +5357,23 @@ const LOCAL_STEPS = /* @__PURE__ */ new Set([
 ]);
 async function runSync(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);
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const requestedSteps = input.steps;
 	const steps = [];
+	logger.info({
+		config: config.name,
+		steps: requestedSteps ?? "all",
+		dryRun: dryRun || void 0
+	}, "sync: start");
 	await loader.load();
+	for (const failure of loader.loadFailures()) logger.warn({
+		capability: failure.key,
+		provider: failure.provider,
+		reason: failure.error.message
+	}, `sync: plugin ${failure.provider} unavailable`);
 	print(`Holocron sync — ${config.name}${dryRun ? " (dry-run)" : ""}`);
 	print(`  config: ${input.loaded.filepath}`);
 	print("");
@@ -5572,6 +5641,12 @@ async function runSync(input) {
 			print(formatSyncStep(result));
 		}
 	}
+	for (const s of steps) logger[s.status === "fail" ? "warn" : "info"]({
+		capability: s.capability,
+		step: s.step,
+		status: s.status,
+		...s.message ? { detail: s.message } : {}
+	}, `sync: ${s.step}`);
 	const summary = steps.reduce((acc, s) => {
 		if (s.status === "ok") acc.ok += 1;
 		else if (s.status === "fail") acc.fail += 1;
@@ -5584,6 +5659,7 @@ async function runSync(input) {
 		skip: 0,
 		dryRun: 0
 	});
+	logger[summary.fail > 0 ? "warn" : "info"]({ ...summary }, "sync: done");
 	print("");
 	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
 	return {
@@ -5710,13 +5786,13 @@ var security_default = "name: Security\n\non: # yamllint disable-line rule:truth
 var stale_default = "name: Stale\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      days-before-stale:\n        description: Days of inactivity before an issue or PR is marked stale (applies to both unless type-specific value is set)\n        type: number\n        required: false\n        default: 30\n      days-before-close:\n        description: Days after stale label before closing (applies to both unless type-specific value is set)\n        type: number\n        required: false\n        default: 5\n      days-before-issue-stale:\n        description: Days of inactivity before an issue is marked stale; overrides days-before-stale when set to a non-negative value\n        type: number\n        required: false\n        default: -1\n      days-before-issue-close:\n        description: Days after stale label before closing an issue; overrides days-before-close when set to a non-negative value\n        type: number\n        required: false\n        default: -1\n      days-before-pr-stale:\n        description: Days of inactivity before a PR is marked stale; overrides days-before-stale when set to a non-negative value\n        type: number\n        required: false\n        default: -1\n      days-before-pr-close:\n        description: Days after stale label before closing a PR; overrides days-before-close when set to a non-negative value\n        type: number\n        required: false\n        default: -1\n      exempt-issue-labels:\n        description: Comma-separated labels that exempt an issue from being marked stale\n        type: string\n        required: false\n        default: \"in-progress,wip\"\n      exempt-pr-labels:\n        description: Comma-separated labels that exempt a PR from being marked stale\n        type: string\n        required: false\n        default: \"\"\n      exempt-all-issue-milestones:\n        description: Issues assigned to any milestone are never marked stale\n        type: boolean\n        required: false\n        default: true\n      exempt-all-pr-milestones:\n        description: PRs assigned to any milestone are never marked stale\n        type: boolean\n        required: false\n        default: true\n      exempt-all-issue-projects:\n        description: Issues assigned to any project are never marked stale\n        type: boolean\n        required: false\n        default: true\n      exempt-all-pr-projects:\n        description: PRs assigned to any project are never marked stale\n        type: boolean\n        required: false\n        default: true\n\njobs:\n  stale:\n    name: Mark stale issues and pull requests\n    permissions:\n      contents: write\n      issues: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.0\n        name: Run Stale\n        with:\n          close-issue-message: >\n            This issue was closed because it has been stalled for\n            ${{ inputs.days-before-close }} days with no activity.\n          days-before-close: ${{ inputs.days-before-close }}\n          days-before-issue-close: ${{ inputs.days-before-issue-close }}\n          days-before-issue-stale: ${{ inputs.days-before-issue-stale }}\n          days-before-pr-close: ${{ inputs.days-before-pr-close }}\n          days-before-pr-stale: ${{ inputs.days-before-pr-stale }}\n          days-before-stale: ${{ inputs.days-before-stale }}\n          exempt-all-issue-milestones: ${{ inputs.exempt-all-issue-milestones }}\n          exempt-all-issue-projects: ${{ inputs.exempt-all-issue-projects }}\n          exempt-all-pr-milestones: ${{ inputs.exempt-all-pr-milestones }}\n          exempt-all-pr-projects: ${{ inputs.exempt-all-pr-projects }}\n          exempt-issue-labels: ${{ inputs.exempt-issue-labels }}\n          exempt-pr-labels: ${{ inputs.exempt-pr-labels }}\n          stale-issue-label: wontfix\n          stale-issue-message: >\n            This issue is stale because it has been open ${{ inputs.days-before-stale }}\n            days with no activity. Remove the stale label or comment, or this will be\n            closed in ${{ inputs.days-before-close }} days.\n          stale-pr-label: wontfix\n          stale-pr-message: >\n            This PR is stale because it has been open ${{ inputs.days-before-stale }}\n            days with no activity. Remove the stale label or comment, or this will be\n            closed in ${{ inputs.days-before-close }} days.\n";
 //#endregion
 //#region src/templates/workflows/sync.yml
-var sync_default = "name: Sync\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      steps:\n        description: >\n          Sync steps to run (default: all). Valid values:\n          labels, properties, teams, topics, keywords, description, homepage, readme, workflows, wiki.\n          Pass a space-separated list to run a subset, e.g. \"readme\" or \"readme wiki\".\n        type: string\n        required: false\n    secrets:\n      HOLOCRON_ADMIN_TOKEN:\n        description: Fine-grained PAT with admin scopes (labels, properties, teams).\n        required: false\n      HOLOCRON_AXIOM_TOKEN:\n        description: >\n          Axiom API token. When set alongside the HOLOCRON_AXIOM_DATASET\n          repo/org variable, the CLI ships this run's structured logs to Axiom.\n        required: false\n      HOLOCRON_DEPLOY_TOKEN:\n        description: Fine-grained PAT for GitHub Pages configuration.\n        required: false\n      HOLOCRON_ISSUES_TOKEN:\n        description: Fine-grained PAT for issue management.\n        required: false\n      HOLOCRON_ORG_TOKEN:\n        description: Org-scoped fine-grained PAT for team sync and org properties.\n        required: false\n      HOLOCRON_READ_TOKEN:\n        description: Fine-grained PAT for read-only GitHub API calls.\n        required: false\n      HOLOCRON_SYNC_TOKEN:\n        required: false\n      GH_TOKEN:\n        description: >\n          Generic GitHub token fallback for gh CLI calls. Used when\n          HOLOCRON_SYNC_TOKEN is not set.\n        required: false\n\njobs:\n  sync:\n    name: Sync repo from config\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    permissions:\n      contents: write\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm build\n        name: Build CLI\n\n      - name: Run holocron sync\n        # Call the built entry directly — `pnpm exec holocron` relies on a\n        # node_modules/.bin/holocron symlink that pnpm cannot create at install\n        # time (dist/ does not exist yet), same as sync-github.yml.\n        run: |\n          if [ -n \"$STEPS\" ]; then\n            # shellcheck disable=SC2086\n            node packages/cli/dist/cli.mjs sync --steps $STEPS\n          else\n            node packages/cli/dist/cli.mjs sync\n          fi\n        env:\n          HOLOCRON_ADMIN_TOKEN: ${{ secrets.HOLOCRON_ADMIN_TOKEN }}\n          HOLOCRON_AXIOM_TOKEN: ${{ secrets.HOLOCRON_AXIOM_TOKEN }}\n          HOLOCRON_AXIOM_DATASET: ${{ vars.HOLOCRON_AXIOM_DATASET }}\n          HOLOCRON_DEPLOY_TOKEN: ${{ secrets.HOLOCRON_DEPLOY_TOKEN }}\n          HOLOCRON_ISSUES_TOKEN: ${{ secrets.HOLOCRON_ISSUES_TOKEN }}\n          HOLOCRON_ORG_TOKEN: ${{ secrets.HOLOCRON_ORG_TOKEN }}\n          HOLOCRON_READ_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          STEPS: ${{ inputs.steps }}\n\n      - name: Format generated files\n        run: pnpm exec prettier --write README.md docs/src/content/docs/index.mdx 2>/dev/null || true\n\n      - uses: theholocron/.github/.github/actions/auto-commit@main\n        id: auto-commit\n        name: Commit sync changes\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n          branch: chore/auto-sync\n          commit-message: \"chore: sync from holocron.config\"\n          commit-options: \"--no-verify\"\n\n      - name: Open PR if changes were committed\n        if: steps.auto-commit.outputs.changes-detected == 'true'\n        run: |\n          gh pr create \\\n            --title \"chore: sync README and repo metadata\" \\\n            --body \"Automated sync triggered by changes to config or package files. Merge to apply.\" \\\n            --base main \\\n            --head chore/auto-sync \\\n          || echo \"PR already open — branch updated.\"\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - name: Broadcast wiki sync if navbar changed\n        if: >-\n          steps.auto-commit.outputs.changes-detected == 'true' &&\n          github.event_name == 'push' &&\n          (inputs.steps == '' || contains(inputs.steps, 'wiki'))\n        run: |\n          if git diff HEAD~1 --name-only | grep -q 'fern/docs.yml'; then\n            gh workflow run sync-dispatch.yml \\\n              --repo theholocron/.github \\\n              --field \"steps=wiki\" \\\n            || echo \"skipping broadcast — insufficient permissions\"\n          fi\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n";
+var sync_default = "name: Sync\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      steps:\n        description: >\n          Sync steps to run (default: all). Valid values:\n          labels, properties, teams, topics, keywords, description, homepage, readme, workflows, wiki.\n          Pass a space-separated list to run a subset, e.g. \"readme\" or \"readme wiki\".\n        type: string\n        required: false\n    secrets:\n      HOLOCRON_ADMIN_TOKEN:\n        description: Fine-grained PAT with admin scopes (labels, properties, teams).\n        required: false\n      HOLOCRON_AXIOM_TOKEN:\n        description: >\n          Axiom API token. When set alongside the HOLOCRON_AXIOM_DATASET\n          repo/org variable, the CLI ships this run's structured logs to Axiom.\n          Falls back to the vendor-native AXIOM_TOKEN secret.\n        required: false\n      AXIOM_TOKEN:\n        description: Vendor-native fallback for HOLOCRON_AXIOM_TOKEN.\n        required: false\n      HOLOCRON_DEPLOY_TOKEN:\n        description: Fine-grained PAT for GitHub Pages configuration.\n        required: false\n      HOLOCRON_ISSUES_TOKEN:\n        description: Fine-grained PAT for issue management.\n        required: false\n      HOLOCRON_ORG_TOKEN:\n        description: Org-scoped fine-grained PAT for team sync and org properties.\n        required: false\n      HOLOCRON_READ_TOKEN:\n        description: Fine-grained PAT for read-only GitHub API calls.\n        required: false\n      HOLOCRON_SYNC_TOKEN:\n        required: false\n      GH_TOKEN:\n        description: >\n          Generic GitHub token fallback for gh CLI calls. Used when\n          HOLOCRON_SYNC_TOKEN is not set.\n        required: false\n\njobs:\n  sync:\n    name: Sync repo from config\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    permissions:\n      contents: write\n      pull-requests: write\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm build\n        name: Build CLI\n\n      - name: Run holocron sync\n        # Call the built entry directly — `pnpm exec holocron` relies on a\n        # node_modules/.bin/holocron symlink that pnpm cannot create at install\n        # time (dist/ does not exist yet), same as sync-github.yml.\n        run: |\n          if [ -n \"$STEPS\" ]; then\n            # shellcheck disable=SC2086\n            node packages/cli/dist/cli.mjs sync --steps $STEPS\n          else\n            node packages/cli/dist/cli.mjs sync\n          fi\n        env:\n          HOLOCRON_ADMIN_TOKEN: ${{ secrets.HOLOCRON_ADMIN_TOKEN }}\n          HOLOCRON_AXIOM_TOKEN: ${{ secrets.HOLOCRON_AXIOM_TOKEN || secrets.AXIOM_TOKEN }}\n          HOLOCRON_AXIOM_DATASET: ${{ vars.HOLOCRON_AXIOM_DATASET || vars.AXIOM_DATASET }}\n          HOLOCRON_DEPLOY_TOKEN: ${{ secrets.HOLOCRON_DEPLOY_TOKEN }}\n          HOLOCRON_ISSUES_TOKEN: ${{ secrets.HOLOCRON_ISSUES_TOKEN }}\n          HOLOCRON_ORG_TOKEN: ${{ secrets.HOLOCRON_ORG_TOKEN }}\n          HOLOCRON_READ_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          STEPS: ${{ inputs.steps }}\n\n      - name: Format generated files\n        run: |\n          pnpm exec prettier --write README.md docs/src/content/docs/index.mdx 2>/dev/null || true\n          # `holocron sync` writes package.json fields (keywords, description,\n          # homepage) with a plain assignment, which appends new keys at the\n          # end — re-apply the canonical order the lint config enforces.\n          pnpm exec eslint --fix --no-warn-ignored package.json 2>/dev/null || true\n\n      - uses: theholocron/.github/.github/actions/auto-commit@main\n        id: auto-commit\n        name: Commit sync changes\n        with:\n          token: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n          branch: chore/auto-sync\n          commit-message: \"chore: sync from holocron.config\"\n          commit-options: \"--no-verify\"\n\n      - name: Open PR if changes were committed\n        if: steps.auto-commit.outputs.changes-detected == 'true'\n        run: |\n          gh pr create \\\n            --title \"chore: sync README and repo metadata\" \\\n            --body \"Automated sync triggered by changes to config or package files. Merge to apply.\" \\\n            --base main \\\n            --head chore/auto-sync \\\n          || echo \"PR already open — branch updated.\"\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n\n      - name: Broadcast wiki sync if navbar changed\n        if: >-\n          steps.auto-commit.outputs.changes-detected == 'true' &&\n          github.event_name == 'push' &&\n          (inputs.steps == '' || contains(inputs.steps, 'wiki'))\n        run: |\n          if git diff HEAD~1 --name-only | grep -q 'fern/docs.yml'; then\n            gh workflow run sync-dispatch.yml \\\n              --repo theholocron/.github \\\n              --field \"steps=wiki\" \\\n            || echo \"skipping broadcast — insufficient permissions\"\n          fi\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN || github.token }}\n";
 //#endregion
 //#region src/templates/workflows/sync-dispatch.yml
 var sync_dispatch_default = "name: Sync Dispatch\n\non: # yamllint disable-line rule:truthy\n  workflow_dispatch:\n    inputs:\n      steps:\n        description: >\n          Sync steps to pass to each repo's sync.yml. Default is \"readme\"\n          (only README marker blocks are updated).\n        type: string\n        required: false\n        default: readme\n\npermissions:\n  contents: read\n\njobs:\n  broadcast:\n    name: Broadcast sync to all repos\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    steps:\n      - name: Dispatch sync to all repos with sync.yml\n        run: |\n          gh api /orgs/theholocron/repos --paginate --jq '.[].name' \\\n            | while IFS= read -r repo; do\n              gh api \"/repos/theholocron/$repo/contents/.github/workflows/sync.yml\" --silent 2>/dev/null || continue\n              echo \"Dispatching sync to theholocron/$repo\"\n              gh workflow run sync.yml \\\n                --repo \"theholocron/$repo\" \\\n                --field \"steps=$STEPS\" \\\n              || echo \"Warning: could not dispatch to theholocron/$repo — skipping\"\n            done\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          STEPS: ${{ inputs.steps }}\n";
 //#endregion
 //#region src/templates/workflows/sync-github.yml
-var sync_github_default = "name: Sync workflow templates\n\n# Builds the holocron CLI from source and pushes updated workflow templates\n# and composite actions to downstream .github repos. Runs whenever the\n# template source files change on main or alpha.\n#\n# Secrets required:\n#   HOLOCRON_SYNC_TOKEN — fine-grained PAT (resource owner: org) with:\n#                  Actions:       Read and write  (dispatch workflow runs via gh workflow run)\n#                  Contents:      Read and write  (git trees, blobs, refs)\n#                  Pull requests: Read and write  (open sync PR)\n#                  Workflows:     Read and write  (write .github/workflows/*.yml)\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      primary-repo:\n        description: >\n          Primary .github repo — receives composite actions, reusable workflows,\n          and thin-caller templates. Requires a PR (branch protection assumed).\n        type: string\n        required: false\n        default: theholocron/.github\n      secondary-repos:\n        description: >\n          Space-separated list of secondary repos (reusable workflows + thin\n          callers only, no composite actions). Changes are delivered via pull\n          request, same as the primary repo.\n        type: string\n        required: false\n        default: \"\"\n      sync-branch:\n        description: Branch name used for the primary and secondary repo PRs\n        type: string\n        required: false\n        default: chore/sync-templates\n    secrets:\n      HOLOCRON_SYNC_TOKEN:\n        required: true\n      HOLOCRON_READ_TOKEN:\n        description: >\n          Fine-grained PAT for read-only GitHub API calls (e.g. resolving git\n          committer identity via `gh api user`). Falls back to HOLOCRON_SYNC_TOKEN.\n        required: false\n      GH_TOKEN:\n        description: >\n          Generic GitHub token fallback for `gh` CLI calls. Used when neither\n          HOLOCRON_READ_TOKEN nor HOLOCRON_SYNC_TOKEN is set.\n        required: false\n      HOLOCRON_AXIOM_TOKEN:\n        description: >\n          Axiom API token. When set alongside the HOLOCRON_AXIOM_DATASET\n          repo/org variable, the CLI ships this run's structured logs to Axiom.\n        required: false\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  sync:\n    name: Sync templates\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    permissions:\n      contents: read\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n      HOLOCRON_AXIOM_TOKEN: ${{ secrets.HOLOCRON_AXIOM_TOKEN }}\n      HOLOCRON_AXIOM_DATASET: ${{ vars.HOLOCRON_AXIOM_DATASET }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm build\n        name: Build CLI\n\n      - name: Cache actionlint\n        id: cache-actionlint\n        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0\n        with:\n          path: /tmp/actionlint\n          key: actionlint-v1.7.7-linux-amd64\n\n      - name: Download actionlint\n        if: steps.cache-actionlint.outputs.cache-hit != 'true'\n        run: |\n          curl -fsSL https://github.com/rhysd/actionlint/releases/download/v1.7.7/actionlint_1.7.7_linux_amd64.tar.gz \\\n            | tar -xz -C /tmp actionlint\n\n      - name: Validate generated workflows\n        run: |\n          node packages/cli/dist/cli.mjs sync-github \\\n            --repo \"$PRIMARY_REPO\" \\\n            --output-dir /tmp/sync-validate\n          /tmp/actionlint /tmp/sync-validate/.github/workflows/*.yml\n        env:\n          PRIMARY_REPO: ${{ inputs.primary-repo }}\n\n      - name: Sync primary repo (PR)\n        run: |\n          GIT_NAME=$(gh api user --jq .name 2>/dev/null || echo \"github-actions[bot]\")\n          GIT_EMAIL=$(gh api user --jq '\"\\(.id)+\\(.login)@users.noreply.github.com\"' 2>/dev/null || echo \"41898282+github-actions[bot]@users.noreply.github.com\")\n          COMMIT_MSG=\"chore: sync from theholocron/holocron\"$'\\n\\n'\"Signed-off-by: $GIT_NAME <$GIT_EMAIL>\"\n          node packages/cli/dist/cli.mjs sync-github \\\n            --repo \"$PRIMARY_REPO\" \\\n            --branch \"$SYNC_BRANCH\" \\\n            --pr \\\n            --message \"$COMMIT_MSG\"\n          GH_TOKEN=\"$HOLOCRON_SYNC_TOKEN\" gh pr merge --auto --squash \\\n            --repo \"$PRIMARY_REPO\" \"$SYNC_BRANCH\" 2>/dev/null || true\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN || secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          PRIMARY_REPO: ${{ inputs.primary-repo }}\n          SYNC_BRANCH: ${{ inputs.sync-branch }}\n\n      - name: Sync secondary repos (PR)\n        if: ${{ inputs.secondary-repos != '' }}\n        run: |\n          GIT_NAME=$(gh api user --jq .name 2>/dev/null || echo \"github-actions[bot]\")\n          GIT_EMAIL=$(gh api user --jq '\"\\(.id)+\\(.login)@users.noreply.github.com\"' 2>/dev/null || echo \"41898282+github-actions[bot]@users.noreply.github.com\")\n          COMMIT_MSG=\"chore: sync from theholocron/holocron\"$'\\n\\n'\"Signed-off-by: $GIT_NAME <$GIT_EMAIL>\"\n          for repo in $SECONDARY_REPOS; do\n            node packages/cli/dist/cli.mjs sync-github \\\n              --repo \"$repo\" \\\n              --branch \"$SYNC_BRANCH\" \\\n              --pr \\\n              --message \"$COMMIT_MSG\"\n            GH_TOKEN=\"$HOLOCRON_SYNC_TOKEN\" gh pr merge --auto --squash \\\n              --repo \"$repo\" \"$SYNC_BRANCH\" 2>/dev/null || true\n          done\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN || secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          SECONDARY_REPOS: ${{ inputs.secondary-repos }}\n          SYNC_BRANCH: ${{ inputs.sync-branch }}\n";
+var sync_github_default = "name: Sync workflow templates\n\n# Builds the holocron CLI from source and pushes updated workflow templates\n# and composite actions to downstream .github repos. Runs whenever the\n# template source files change on main or alpha.\n#\n# Secrets required:\n#   HOLOCRON_SYNC_TOKEN — fine-grained PAT (resource owner: org) with:\n#                  Actions:       Read and write  (dispatch workflow runs via gh workflow run)\n#                  Contents:      Read and write  (git trees, blobs, refs)\n#                  Pull requests: Read and write  (open sync PR)\n#                  Workflows:     Read and write  (write .github/workflows/*.yml)\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      primary-repo:\n        description: >\n          Primary .github repo — receives composite actions, reusable workflows,\n          and thin-caller templates. Requires a PR (branch protection assumed).\n        type: string\n        required: false\n        default: theholocron/.github\n      secondary-repos:\n        description: >\n          Space-separated list of secondary repos (reusable workflows + thin\n          callers only, no composite actions). Changes are delivered via pull\n          request, same as the primary repo.\n        type: string\n        required: false\n        default: \"\"\n      sync-branch:\n        description: Branch name used for the primary and secondary repo PRs\n        type: string\n        required: false\n        default: chore/sync-templates\n    secrets:\n      HOLOCRON_SYNC_TOKEN:\n        required: true\n      HOLOCRON_READ_TOKEN:\n        description: >\n          Fine-grained PAT for read-only GitHub API calls (e.g. resolving git\n          committer identity via `gh api user`). Falls back to HOLOCRON_SYNC_TOKEN.\n        required: false\n      GH_TOKEN:\n        description: >\n          Generic GitHub token fallback for `gh` CLI calls. Used when neither\n          HOLOCRON_READ_TOKEN nor HOLOCRON_SYNC_TOKEN is set.\n        required: false\n      HOLOCRON_AXIOM_TOKEN:\n        description: >\n          Axiom API token. When set alongside the HOLOCRON_AXIOM_DATASET\n          repo/org variable, the CLI ships this run's structured logs to Axiom.\n          Falls back to the vendor-native AXIOM_TOKEN secret.\n        required: false\n      AXIOM_TOKEN:\n        description: Vendor-native fallback for HOLOCRON_AXIOM_TOKEN.\n        required: false\n      TURBO_TOKEN:\n        required: false\n\njobs:\n  sync:\n    name: Sync templates\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    permissions:\n      contents: read\n    env:\n      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}\n      TURBO_TEAM: ${{ vars.TURBO_TEAM }}\n      HOLOCRON_AXIOM_TOKEN: ${{ secrets.HOLOCRON_AXIOM_TOKEN || secrets.AXIOM_TOKEN }}\n      HOLOCRON_AXIOM_DATASET: ${{ vars.HOLOCRON_AXIOM_DATASET || vars.AXIOM_DATASET }}\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: pnpm build\n        name: Build CLI\n\n      - name: Cache actionlint\n        id: cache-actionlint\n        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0\n        with:\n          path: /tmp/actionlint\n          key: actionlint-v1.7.7-linux-amd64\n\n      - name: Download actionlint\n        if: steps.cache-actionlint.outputs.cache-hit != 'true'\n        run: |\n          curl -fsSL https://github.com/rhysd/actionlint/releases/download/v1.7.7/actionlint_1.7.7_linux_amd64.tar.gz \\\n            | tar -xz -C /tmp actionlint\n\n      - name: Validate generated workflows\n        run: |\n          node packages/cli/dist/cli.mjs sync-github \\\n            --repo \"$PRIMARY_REPO\" \\\n            --output-dir /tmp/sync-validate\n          /tmp/actionlint /tmp/sync-validate/.github/workflows/*.yml\n        env:\n          PRIMARY_REPO: ${{ inputs.primary-repo }}\n\n      - name: Sync primary repo (PR)\n        run: |\n          GIT_NAME=$(gh api user --jq .name 2>/dev/null || echo \"github-actions[bot]\")\n          GIT_EMAIL=$(gh api user --jq '\"\\(.id)+\\(.login)@users.noreply.github.com\"' 2>/dev/null || echo \"41898282+github-actions[bot]@users.noreply.github.com\")\n          COMMIT_MSG=\"chore: sync from theholocron/holocron\"$'\\n\\n'\"Signed-off-by: $GIT_NAME <$GIT_EMAIL>\"\n          node packages/cli/dist/cli.mjs sync-github \\\n            --repo \"$PRIMARY_REPO\" \\\n            --branch \"$SYNC_BRANCH\" \\\n            --pr \\\n            --message \"$COMMIT_MSG\"\n          GH_TOKEN=\"$HOLOCRON_SYNC_TOKEN\" gh pr merge --auto --squash \\\n            --repo \"$PRIMARY_REPO\" \"$SYNC_BRANCH\" 2>/dev/null || true\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN || secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          PRIMARY_REPO: ${{ inputs.primary-repo }}\n          SYNC_BRANCH: ${{ inputs.sync-branch }}\n\n      - name: Sync secondary repos (PR)\n        if: ${{ inputs.secondary-repos != '' }}\n        run: |\n          GIT_NAME=$(gh api user --jq .name 2>/dev/null || echo \"github-actions[bot]\")\n          GIT_EMAIL=$(gh api user --jq '\"\\(.id)+\\(.login)@users.noreply.github.com\"' 2>/dev/null || echo \"41898282+github-actions[bot]@users.noreply.github.com\")\n          COMMIT_MSG=\"chore: sync from theholocron/holocron\"$'\\n\\n'\"Signed-off-by: $GIT_NAME <$GIT_EMAIL>\"\n          for repo in $SECONDARY_REPOS; do\n            node packages/cli/dist/cli.mjs sync-github \\\n              --repo \"$repo\" \\\n              --branch \"$SYNC_BRANCH\" \\\n              --pr \\\n              --message \"$COMMIT_MSG\"\n            GH_TOKEN=\"$HOLOCRON_SYNC_TOKEN\" gh pr merge --auto --squash \\\n              --repo \"$repo\" \"$SYNC_BRANCH\" 2>/dev/null || true\n          done\n        env:\n          GH_TOKEN: ${{ secrets.HOLOCRON_READ_TOKEN || secrets.HOLOCRON_SYNC_TOKEN || secrets.GH_TOKEN }}\n          HOLOCRON_SYNC_TOKEN: ${{ secrets.HOLOCRON_SYNC_TOKEN }}\n          SECONDARY_REPOS: ${{ inputs.secondary-repos }}\n          SYNC_BRANCH: ${{ inputs.sync-branch }}\n";
 //#endregion
 //#region src/templates/workflows/tag.yml
 var tag_default = "name: Tag\n\n# Release Please — fully automated tag and GitHub Release from Conventional Commits.\n# No package.json or npm publishing required. Operates in \"simple\" mode by default:\n# analyzes commits since the last tag, maintains a rolling Release PR, and creates\n# a tag + GitHub Release when that PR is merged.\n#\n# The calling repo must have two files at the root:\n#   release-please-config.json    — declares packages and release-type\n#   .release-please-manifest.json — tracks the current version\n\non: # yamllint disable-line rule:truthy\n  # Self-trigger: when this workflow lives in theholocron/.github itself,\n  # push to main runs Release Please for that repo's own releases.\n  push:\n    branches:\n      - main\n  workflow_call:\n    inputs:\n      release-type:\n        description: Release Please release type (simple, node, python, etc.)\n        type: string\n        required: false\n        default: simple\n      config-file:\n        description: Path to release-please-config.json\n        type: string\n        required: false\n        default: release-please-config.json\n      manifest-file:\n        description: Path to .release-please-manifest.json\n        type: string\n        required: false\n        default: .release-please-manifest.json\n\njobs:\n  tag:\n    name: Tag release\n    permissions:\n      contents: write\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: google-github-actions/release-please-action@e4dc86ba9405554aeba3c6bb2d169500e7d3b4ee # v4.1.1\n        name: Run Release Please\n        with:\n          release-type: ${{ inputs.release-type }}\n          config-file: ${{ inputs.config-file }}\n          manifest-file: ${{ inputs.manifest-file }}\n";
@@ -5821,6 +5897,7 @@ function gitBlobSha(content) {
 }
 async function runSyncGithub(input) {
 	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
 	const repo = input.repo ?? DEFAULT_REPO;
 	const { token, dryRun = false, branch, createPr = false } = input;
 	const message = input.message ?? `chore: sync from theholocron/holocron`;
@@ -5832,6 +5909,25 @@ async function runSyncGithub(input) {
 	print(`  repo:   ${repo}`);
 	if (branch) print(`  branch: ${branch}`);
 	print("");
+	logger.info({
+		repo,
+		branch,
+		createPr: createPr || void 0,
+		dryRun: dryRun || void 0
+	}, "sync-github: start");
+	/** Single exit point — one structured line per invocation, whatever the path. */
+	const done = (r) => {
+		logger[r.status === "fail" ? "warn" : "info"]({
+			repo,
+			status: r.status,
+			created: r.created,
+			updated: r.updated,
+			unchanged: r.unchanged,
+			...r.message ? { reason: r.message } : {},
+			...r.prUrl ? { pr: r.prUrl } : {}
+		}, "sync-github: done");
+		return r;
+	};
 	if (input.outputDir) {
 		const batch = buildBatch(repo);
 		for (const file of batch) {
@@ -5840,12 +5936,12 @@ async function runSyncGithub(input) {
 			writeFileSync(dest, file.content, "utf8");
 		}
 		print(`  ${batch.length} files written to ${input.outputDir}`);
-		return {
+		return done({
 			status: "ok",
 			created: batch.length,
 			updated: 0,
 			unchanged: 0
-		};
+		});
 	}
 	let targetBranch = branch;
 	let defaultBranch;
@@ -5855,13 +5951,13 @@ async function runSyncGithub(input) {
 	} catch {
 		const msg = "failed to fetch repo metadata";
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created: 0,
 			updated: 0,
 			unchanged: 0,
 			message: msg
-		};
+		});
 	}
 	const baseBranch = createPr && defaultBranch ? defaultBranch : targetBranch;
 	let headSha;
@@ -5875,13 +5971,13 @@ async function runSyncGithub(input) {
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : `Branch ${baseBranch} not found`;
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created: 0,
 			updated: 0,
 			unchanged: 0,
 			message: msg
-		};
+		});
 	}
 	const batch = buildBatch(repo);
 	let created = 0;
@@ -5896,22 +5992,30 @@ async function runSyncGithub(input) {
 			unchanged++;
 		} else if (existingSha) {
 			print(`  ${dryRun ? "~" : "✓"} updated  ${file.path}`);
+			logger.debug({
+				file: file.path,
+				change: "updated"
+			}, "sync-github: file");
 			updated++;
 			if (!dryRun) changedFiles.push(file);
 		} else {
 			print(`  ${dryRun ? "~" : "✓"} created  ${file.path}`);
+			logger.debug({
+				file: file.path,
+				change: "created"
+			}, "sync-github: file");
 			created++;
 			if (!dryRun) changedFiles.push(file);
 		}
 	}
 	print("");
 	print(`  ${created} created, ${updated} updated, ${unchanged} unchanged`);
-	if (dryRun || changedFiles.length === 0) return {
+	if (dryRun || changedFiles.length === 0) return done({
 		status: dryRun ? "dry-run" : "ok",
 		created,
 		updated,
 		unchanged
-	};
+	});
 	const treeEntries = [];
 	for (const file of changedFiles) try {
 		const blob = await client.git.createBlob(repo, file.content);
@@ -5924,13 +6028,13 @@ async function runSyncGithub(input) {
 	} catch (err) {
 		const msg = `failed to create blob for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created,
 			updated,
 			unchanged,
 			message: msg
-		};
+		});
 	}
 	let newTreeSha;
 	try {
@@ -5938,13 +6042,13 @@ async function runSyncGithub(input) {
 	} catch (err) {
 		const msg = `failed to create tree: ${err instanceof Error ? err.message : String(err)}`;
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created,
 			updated,
 			unchanged,
 			message: msg
-		};
+		});
 	}
 	let newCommitSha;
 	try {
@@ -5952,13 +6056,13 @@ async function runSyncGithub(input) {
 	} catch (err) {
 		const msg = `failed to create commit: ${err instanceof Error ? err.message : String(err)}`;
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created,
 			updated,
 			unchanged,
 			message: msg
-		};
+		});
 	}
 	try {
 		if (createPr && branch) try {
@@ -5971,13 +6075,13 @@ async function runSyncGithub(input) {
 	} catch (err) {
 		const msg = `failed to update ref: ${err instanceof Error ? err.message : String(err)}`;
 		print(`  ✗ ${msg}`);
-		return {
+		return done({
 			status: "fail",
 			created,
 			updated,
 			unchanged,
 			message: msg
-		};
+		});
 	}
 	let prUrl;
 	if (branch && createPr && !dryRun) try {
@@ -5992,13 +6096,13 @@ async function runSyncGithub(input) {
 		if (err instanceof ProviderApiError && err.status === 422 && String(err.details).includes("already exists")) print(`  → PR already open for ${branch} — branch updated, ready to merge`);
 		else print(`  ⚠ PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
 	}
-	return {
+	return done({
 		status: "ok",
 		created,
 		updated,
 		unchanged,
 		prUrl
-	};
+	});
 }
 //#endregion
 //#region src/commands/upgrade-node.ts