@theholocron/cli 2.0.0-alpha.43 → 2.0.0-alpha.45

package/README.md

@@ -101,13 +101,14 @@ export default acmeConfig;
 - `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
   capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands
-- `src/commands/` — `setup`, `doctor`, `deploy`, `secret set`,
-  `secrets sync`, `npm publish-initial`
+- `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
+  `secrets sync`, `npm publish-initial`, `sync-github`, `upgrade node`,
+  `plugin create`, `auth`
 
 ## Status
 
 **`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
 [Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
 Design in
-[`.notes/tech-architecture.spec.md`](../../.notes/tech-architecture.spec.md).
+[`.notes/archive/tech-architecture.spec.md`](../../.notes/archive/tech-architecture.spec.md).
 APIs may still shift before stable v2.0.0.

package/dist/capabilities/index.d.mts

@@ -127,6 +127,16 @@ interface Source extends ProviderIdentity {
    * Optional — providers that have no label concept omit this.
    */
   syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
+  /**
+   * Set org-level custom property values on the repo.
+   * Optional — providers that don't support custom properties omit this.
+   */
+  syncProperties?(values: Record<string, string>): Promise<string>;
+  /**
+   * Replace the repo's topic set with the supplied list.
+   * Optional — providers that don't support topics omit this.
+   */
+  syncTopics?(topics: string[]): Promise<string>;
 }
 type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
 interface CiRun {

package/dist/cli.mjs

@@ -7,7 +7,7 @@ import { ProviderApiError } from "@theholocron/http-client";
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { readFile, stat } from "node:fs/promises";
+import { access, readFile, stat } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 //#region src/capabilities/index.ts
 const CARDINALITY = {
@@ -464,7 +464,7 @@ var PluginLoader = class {
 	*/
 	projectDefaults() {
 		const defaults = {};
-		if (this.config.project.repo) defaults.repo = this.config.project.repo;
+		if (this.config.project.repo) defaults.repo = this.config.project.repo.name;
 		return defaults;
 	}
 };
@@ -1058,7 +1058,7 @@ jobs:
         id: metadata
 
       - run: gh pr merge --auto --squash "$PR_URL"
-        # --squash is intentional: repoPolicy sets allow_merge_commit: false,
+        # --squash is intentional: repo protection sets allow_merge_commit: false,
         # so --merge would fail on any repo using the standard preset.
         name: Enable auto-merge for Dependabot PRs
         if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
@@ -3682,6 +3682,25 @@ function vaultProviderName(loader) {
 }
 //#endregion
 //#region src/commands/setup.ts
+/**
+* `holocron setup` — orchestrates per-capability setup actions across
+* every plugin loaded from `holocron.config.json`.
+*
+* Per CLAUDE.md soft-skip: each step is wrapped in a try/catch and
+* failures don't abort subsequent capabilities. The summary at the end
+* reports counts so the operator can see what worked + what didn't.
+*
+* Per the Standards: when `ctx.dryRun` is true, mutating calls are
+* replaced with "would" log lines. Read-only probes (e.g.,
+* `vault.list`) still run so the operator sees real state.
+*
+* The orchestrator knows about specific capability methods by name
+* (e.g., `source.enableVulnerabilityAlerts`). This deliberate coupling
+* makes the "what does setup do" contract explicit and concrete —
+* decoupling via a per-capability `setupSteps()` method would be more
+* extensible but pushes the same knowledge into N plugins instead of
+* one central place.
+*/
 function editorconfigContent() {
 	return [
 		`# AUTO-GENERATED — do not edit directly.`,
@@ -4038,6 +4057,8 @@ async function runSetup(input) {
 	const config = input.loaded.resolved;
 	const dryRun = input.context.dryRun ?? false;
 	const steps = [];
+	const repo = config.project.repo;
+	const effectivePreset = repo?.protection;
 	print(`Holocron setup — ${config.project.name}${dryRun ? " (dry-run)" : ""}`);
 	print(`  config: ${input.loaded.filepath}`);
 	print("");
@@ -4062,21 +4083,19 @@ async function runSetup(input) {
 			else return await source.enableCodeScanning();
 		}));
 		print(formatStep(steps[steps.length - 1]));
-		const policy = config.project.repoPolicy;
-		if (policy && policy.preset !== "none") {
-			const preset = policy.preset ?? "balanced";
+		if (effectivePreset && effectivePreset !== "none") {
 			steps.push(await runStep("source", "updateRepoSettings", dryRun, async () => {
 				await source.updateRepoSettings(BALANCED_REPO_SETTINGS);
 			}));
 			print(formatStep(steps[steps.length - 1]));
 			const configuredWorkflowNames = (config.project.workflows ?? []).map((entry) => typeof entry === "string" ? entry : entry.name);
-			const requiredChecks = preset === "strict" ? [
+			const requiredChecks = effectivePreset === "strict" ? [
 				"DCO",
 				...configuredWorkflowNames.flatMap((name) => {
 					const ctx = WORKFLOW_CHECK_CONTEXTS[name];
 					return ctx ? [ctx] : [];
 				}),
-				...policy.requiredChecks ?? []
+				...repo?.requiredChecks ?? []
 			] : [];
 			steps.push(await upsertBranchProtection(source, dryRun, requiredChecks));
 			print(formatStep(steps[steps.length - 1]));
@@ -4112,7 +4131,7 @@ async function runSetup(input) {
 		}));
 		print(formatStep(steps[steps.length - 1]));
 	}
-	if (loader.has("source") && config.project.repoPolicy?.preset !== "none") {
+	if (loader.has("source") && effectivePreset !== "none") {
 		const source = loader.get("source");
 		steps.push(await runStep("source", "write .github/dependabot.yml", dryRun, async () => {
 			await source.writeRepoFile(".github/dependabot.yml", DEPENDABOT_CONFIG);
@@ -4139,6 +4158,24 @@ async function runSetup(input) {
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
+		const properties = {};
+		if (effectivePreset && effectivePreset !== "none") properties["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 ?? {};
+		if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
+		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);
+		if (source.syncProperties) {
+			steps.push(await runStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
+			print(formatStep(steps[steps.length - 1]));
+		}
+		const topics = repo?.topics ?? [];
+		if (topics.length > 0 && source.syncTopics) {
+			steps.push(await runStep("source", "sync topics", dryRun, () => source.syncTopics(topics)));
+			print(formatStep(steps[steps.length - 1]));
+		}
 	}
 	if (loader.has("environments")) {
 		const envs = loader.get("environments");
@@ -4272,6 +4309,148 @@ function formatStep(step) {
 	return `    ${icon} ${step.step}${detail}`;
 }
 //#endregion
+//#region src/commands/sync.ts
+const SYNC_STEPS = [
+	"labels",
+	"properties",
+	"topics"
+];
+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 = [];
+	print(`Holocron sync — ${config.project.name}${dryRun ? " (dry-run)" : ""}`);
+	print(`  config: ${input.loaded.filepath}`);
+	print("");
+	if (loader.has("source")) {
+		const source = loader.get("source");
+		print("  → source");
+		for (const stepName of SYNC_STEPS) {
+			if (requestedSteps !== void 0 && !requestedSteps.includes(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]));
+			} else {
+				steps.push({
+					capability: "source",
+					step: "sync labels",
+					status: "skip",
+					message: "provider does not implement syncLabels"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
+			if (stepName === "properties") if (source.syncProperties) {
+				const repo = config.project.repo;
+				const properties = {};
+				const effectivePreset = repo?.protection;
+				if (effectivePreset && effectivePreset !== "none") properties["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 ?? {};
+				if (manual.lifecycle) properties["lifecycle"] = manual.lifecycle;
+				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);
+				steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
+				print(formatSyncStep(steps[steps.length - 1]));
+			} else {
+				steps.push({
+					capability: "source",
+					step: "sync properties",
+					status: "skip",
+					message: "provider does not implement syncProperties"
+				});
+				print(formatSyncStep(steps[steps.length - 1]));
+			}
+			if (stepName === "topics") {
+				const topics = config.project.repo?.topics ?? [];
+				if (topics.length === 0) {
+					steps.push({
+						capability: "source",
+						step: "sync topics",
+						status: "skip",
+						message: "no topics configured"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else if (source.syncTopics) {
+					steps.push(await runSyncStep("source", "sync topics", dryRun, () => source.syncTopics(topics)));
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push({
+						capability: "source",
+						step: "sync topics",
+						status: "skip",
+						message: "provider does not implement syncTopics"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
+			}
+		}
+		if (requestedSteps) {
+			for (const name of requestedSteps) if (!SYNC_STEPS.includes(name)) {
+				steps.push({
+					capability: "source",
+					step: `sync ${name}`,
+					status: "skip",
+					message: `unknown step "${name}"`
+				});
+				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;
+		else if (s.status === "skip") acc.skip += 1;
+		else if (s.status === "dry-run") acc.dryRun += 1;
+		return acc;
+	}, {
+		ok: 0,
+		fail: 0,
+		skip: 0,
+		dryRun: 0
+	});
+	print("");
+	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
+	return {
+		steps,
+		summary
+	};
+}
+async function runSyncStep(capability, step, dryRun, body) {
+	if (dryRun) return {
+		capability,
+		step,
+		status: "dry-run"
+	};
+	try {
+		const note = await body();
+		const result = {
+			capability,
+			step,
+			status: "ok"
+		};
+		if (typeof note === "string") result.message = note;
+		return result;
+	} catch (err) {
+		return {
+			capability,
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+function formatSyncStep(step) {
+	const icon = step.status === "ok" ? "✓" : step.status === "fail" ? "✗" : step.status === "dry-run" ? "…" : "·";
+	const detail = step.message ? `  (${step.message})` : "";
+	return `    ${icon} ${step.step}${detail}`;
+}
+//#endregion
 //#region src/load-config.ts
 /**
 * `holocron.config.{json,js,ts}` file loader.
@@ -4494,7 +4673,25 @@ 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-github", "Sync workflow templates and composite actions to theholocron/.github via the GitHub API", (y) => y.option("repo", {
+}).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", {
+	type: "string",
+	array: true,
+	describe: "Steps to run: labels, properties, topics (default: all)"
+}).option("repo", {
+	type: "string",
+	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
+}), async (argv) => {
+	if ((await runSync({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.repo ? { repo: argv.repo } : {},
+			...argv.token ? { cliToken: argv.token } : {}
+		},
+		...argv.steps && argv.steps.length > 0 ? { steps: argv.steps } : {}
+	})).summary.fail > 0) process.exitCode = 1;
+}).command("sync-github", "Sync workflow templates and composite actions to theholocron/.github via the GitHub API", (y) => y.option("repo", {
 	type: "string",
 	default: "theholocron/.github",
 	describe: "Target org/repo (default: theholocron/.github)"

package/dist/index.d.mts

@@ -30,21 +30,27 @@ type SingleEntry = string | [provider: string, options: ProviderOptions];
 type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
 type RawProviderEntry = SingleEntry | MultiEntry;
 type RawProvidersConfig = Partial<Record<CapabilityKey, RawProviderEntry>>;
-interface RepoPolicyConfig {
+type RepoProtection = "balanced" | "strict" | "none";
+interface RepoProperties {
+  lifecycle?: "active" | "experimental" | "deprecated";
+  open_source?: boolean;
+  runtime_environment?: "node" | "browser" | "universal" | "none";
+  uses_external_packages?: boolean;
+}
+interface RepoConfig {
+  /** "owner/name" — the GitHub repository coordinate. */
+  name: string;
   /**
-   * "balanced" — squash-only merges, delete-branch-on-merge, issues/discussions/projects
-   * enabled, auto-merge enabled, web sign-off required, always suggest updating, no wiki;
-   * plus a ruleset that blocks force-push + deletion and requires a pull request (0 reviews).
-   *
-   * "strict" — everything in "balanced" plus required status checks from `requiredChecks`.
-   *
-   * "none" — skips repo settings + ruleset entirely.
-   *
-   * @default "balanced"
+   * Branch protection preset applied by `holocron setup`. When omitted,
+   * no protection is applied and no `branch_protection_level` property is set.
    */
-  preset?: "balanced" | "strict" | "none";
-  /** CI check context names required on the default branch (used by "strict"). */
+  protection?: RepoProtection;
+  /** CI check context names required on the default branch (only used when `protection` is "strict"). */
   requiredChecks?: string[];
+  /** GitHub topics set on the repository. */
+  topics?: string[];
+  /** GitHub custom properties synced to the org dashboard. */
+  properties?: RepoProperties;
 }
 interface AppConfig {
   name: string;
@@ -59,18 +65,12 @@ interface HolocronConfig {
     name: string;
     description?: string;
     /**
-     * Repo coord — `"owner/name"`. When set, `PluginLoader` injects
-     * it into every plugin's `RuntimeContext.repo` so plugins that
-     * need a repo (github, etc.) don't require `--repo` on every
-     * invocation. `--repo` on the command line still overrides.
-     */
-    repo?: string;
-    /**
-     * Repo-level policy applied by `holocron setup`. Defines merge
-     * strategy, branch protection rulesets, and security defaults.
-     * Requires `source` capability to be configured.
+     * Repository identity and metadata. When set, `PluginLoader` injects
+     * `repo.name` into every plugin's `RuntimeContext.repo` so plugins that
+     * need a repo (github, etc.) don't require `--repo` on every invocation.
+     * `--repo` on the command line still overrides.
      */
-    repoPolicy?: RepoPolicyConfig;
+    repo?: RepoConfig;
     /**
      * CI workflow names to install as thin wrappers during `holocron setup`.
      * Each name maps to a reusable workflow in `theholocron/.github`.
@@ -190,4 +190,4 @@ interface LoadedConfig {
  */
 declare function loadConfig(cwd: string): Promise<LoadedConfig>;
 //#endregion
-export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, LoadedConfig, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoPolicyConfig, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, DoctorConfig, EnsureResult, Environment, EnvironmentReviewer, Environments, HolocronConfig, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, LoadedConfig, MultiEntry, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoConfig, RepoProperties, RepoProtection, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, createResolveToken, createRestClient, defineConfig, deleteToken, getToken, isMulti, listStoredProviders, loadConfig, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.0.0-alpha.43",
+  "version": "2.0.0-alpha.45",
   "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",