@theholocron/cli 2.0.0-alpha.42 → 2.0.0-alpha.44

package/README.md

@@ -109,5 +109,5 @@ export default acmeConfig;
 **`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/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,8 @@ var PluginLoader = class {
 	*/
 	projectDefaults() {
 		const defaults = {};
-		if (this.config.project.repo) defaults.repo = this.config.project.repo;
+		const repo = this.config.project.repo;
+		if (repo) defaults.repo = typeof repo === "string" ? repo : repo.name;
 		return defaults;
 	}
 };
@@ -957,6 +958,7 @@ jobs:
     name: Add Labels to PRs
     permissions:
       contents: read
+      issues: write
       pull-requests: write
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -1902,6 +1904,7 @@ on: # yamllint disable-line rule:truthy
 
 permissions:
   contents: read
+  issues: write
   pull-requests: write
 
 jobs:
@@ -3680,6 +3683,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.`,
@@ -4036,6 +4058,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 ?? config.project.repoPolicy?.preset;
 	print(`Holocron setup — ${config.project.name}${dryRun ? " (dry-run)" : ""}`);
 	print(`  config: ${input.loaded.filepath}`);
 	print("");
@@ -4060,21 +4084,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 ?? config.project.repoPolicy?.requiredChecks ?? []
 			] : [];
 			steps.push(await upsertBranchProtection(source, dryRun, requiredChecks));
 			print(formatStep(steps[steps.length - 1]));
@@ -4110,7 +4132,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);
@@ -4137,6 +4159,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");

package/dist/index.d.mts

@@ -41,10 +41,36 @@ interface RepoPolicyConfig {
    * "none" — skips repo settings + ruleset entirely.
    *
    * @default "balanced"
+   * @deprecated Use `project.repo.protection` instead.
    */
   preset?: "balanced" | "strict" | "none";
-  /** CI check context names required on the default branch (used by "strict"). */
+  /**
+   * CI check context names required on the default branch (used by "strict").
+   * @deprecated Use `project.repo.requiredChecks` instead.
+   */
+  requiredChecks?: string[];
+}
+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;
+  /**
+   * Branch protection preset applied by `holocron setup`. When omitted,
+   * no protection is applied and no `branch_protection_level` property is set.
+   */
+  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,12 +85,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.
+     * 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.
      */
-    repo?: string;
+    repo?: RepoConfig;
     /**
      * Repo-level policy applied by `holocron setup`. Defines merge
      * strategy, branch protection rulesets, and security defaults.
@@ -190,4 +216,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, RepoPolicyConfig, 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.42",
+  "version": "2.0.0-alpha.44",
   "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",