@theholocron/cli 5.0.0-alpha.11 → 5.0.0-alpha.13

package/README.md

@@ -112,6 +112,36 @@ Additional `repo` fields recognised by `holocron setup`:
 | `repo.protection` | `"balanced" \| "strict" \| "none"`      | Branch-protection preset applied by `holocron setup`. For `"strict"`, the required status checks are derived from the task manifest — see below.                           |
 | `repo.properties` | `RepoProperties`                        | Org-level custom property values synced to the GitHub dashboard.                                                                                                           |
 
+### Custom properties synced to GitHub
+
+`holocron setup` and `holocron sync` both call `syncProperties()` with two
+kinds of fields — always one-way (`holocron.config.ts` → resolved →
+properties; properties are never a second editable source of truth):
+
+**Manual** — `repo.properties` states these explicitly:
+
+| Property                 | Value                                          |
+| ------------------------ | ---------------------------------------------- |
+| `lifecycle`              | `"active" \| "experimental" \| "deprecated"`   |
+| `open_source`            | `boolean`                                      |
+| `runtime_environment`    | `"node" \| "browser" \| "universal" \| "none"` |
+| `uses_external_packages` | `boolean`                                      |
+
+**Derived** — computed from resolved config + `package.json`, not a config field:
+
+| Property                           | Value                                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `monorepo`                         | `boolean` — whether `pnpm-workspace.yaml` exists                                         |
+| `holocron_branch_protection_level` | the active `repo.protection` preset                                                      |
+| `holocron_profile`                 | repo archetype: `library` / `cli` / `plugin` / `template` / `app` / `docs` / `platform`  |
+| `holocron_capabilities`            | provider capability keys actually wired in `providers: {}` (`multi_select`)              |
+| `holocron_stack`                   | detected build/framework tooling — `next`, `vite`, `astro`, `tsdown`, … (`multi_select`) |
+| `holocron_compliance`              | `"compliant" \| "non-compliant"` against a minimal `source` + `ci` baseline              |
+
+Field definitions and derivation heuristics:
+`.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
+definitions (#677)".
+
 ### Required status checks (`protection: "strict"`)
 
 `holocron setup` builds the branch-protection required-check list from the

package/dist/cli.mjs

@@ -3796,6 +3796,104 @@ function vaultProviderName(loader) {
 	return loader.get("vault").providerName;
 }
 //#endregion
+//#region src/commands/setup/derived-properties.ts
+/**
+* Repo archetype, in priority order:
+* 1. `*-template` repo name → `template` (independent of package shape).
+* 2. Monorepo whose primary published artifact is a CLI (some workspace
+*    package has `bin`) → `platform` — matches `holocron` itself: the CLI is
+*    the deliverable, the plugin packages are supporting infrastructure for
+*    it, not separate products.
+* 3. Monorepo with no CLI but at least one non-private workspace package →
+*    `library` — matches `clients`/`configs`/`utils`/`themes`/
+*    `observability`: a family of published packages, none of them a CLI.
+*    Checked *before* falling into the root-package branch below, because
+*    these repos' own root `package.json` is private and often carries
+*    `@theholocron/astro-config` for a docs site built from the monorepo
+*    root — without this check they'd wrongly resolve to `docs` off that
+*    root-level signal alone, when the docs site is a secondary concern of
+*    a library collection, not what the repo fundamentally is.
+* 4. Single-package repo with `package.json#bin` → `cli`.
+* 5. Docs-only site (astro/starlight present, root package private, no
+*    publishable exports) → `docs`.
+* 6. Private, non-publishable, non-docs → `app`.
+* 7. Otherwise, a single publishable package → `library`.
+*/
+function deriveProfile(input) {
+	if (/-template$/.test(input.repoName)) return "template";
+	if (input.isMonorepo) {
+		if (input.workspacePackageJsons.some((pkg) => Boolean(pkg.bin))) return "platform";
+		if (input.workspacePackageJsons.some((pkg) => pkg.private !== true)) return "library";
+	}
+	const pkg = input.rootPackageJson;
+	if (pkg?.bin) return "cli";
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	const isDocsSite = Boolean(deps["@theholocron/astro-config"] || deps["astro"]);
+	if (pkg?.private && isDocsSite) return "docs";
+	if (pkg?.private) return "app";
+	return "library";
+}
+const KNOWN_STACK_DEPS = [
+	"next",
+	"vite",
+	"astro",
+	"tsdown",
+	"rollup",
+	"webpack",
+	"storybook",
+	"vitest",
+	"playwright",
+	"turbo"
+];
+/**
+* Detected build/framework tooling — the literal "does this repo need
+* next/vite/tsdown" signal `holocron.config.ts` has no field for today
+* (framework choice isn't a config concept, unlike `providers`/`tasks`).
+* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
+* frameworks show up rather than trying to detect anything on npm.
+*/
+function deriveStack(pkg) {
+	const deps = {
+		...pkg?.dependencies,
+		...pkg?.devDependencies
+	};
+	return KNOWN_STACK_DEPS.filter((name) => name in deps);
+}
+/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
+function deriveCapabilities(providers) {
+	return Object.keys(providers ?? {}).sort();
+}
+/**
+* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* touches wires — every `holocron.config.ts` in this org already satisfies
+* this, so `non-compliant` here means drift (a provider manually removed
+* after setup), not an unmet aspirational policy. Deliberately not a richer
+* per-profile policy yet (e.g. "a `library` must have `deployment`") — that's
+* a Phase B (GitHub App) refinement once it can post *why* on a check run.
+*/
+const REQUIRED_BASELINE = ["source", "ci"];
+function deriveCompliance(capabilities) {
+	return REQUIRED_BASELINE.every((key) => capabilities.includes(key)) ? "compliant" : "non-compliant";
+}
+/**
+* Reads each workspace package's actual `package.json` content (not just
+* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
+* `platform` detection needs `bin`, which that helper doesn't carry).
+* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
+* own soft-fail behavior.
+*/
+async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
+	const results = [];
+	for (const { slug, dir = "packages" } of workspacePackages) try {
+		const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
+		results.push(JSON.parse(raw));
+	} catch {}
+	return results;
+}
+//#endregion
 //#region src/commands/setup/labels.ts
 const CANONICAL_LABELS = [
 	{
@@ -5152,7 +5250,7 @@ async function runSetup(input) {
 			print(formatStep(steps[steps.length - 1]));
 		}
 		const properties = {};
-		if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
+		if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
 		const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
 		properties["monorepo"] = String(isMonorepo);
 		const manual = repo?.properties ?? {};
@@ -5160,6 +5258,21 @@ async function runSetup(input) {
 		if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
 		if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
 		if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+		{
+			const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+			const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+			const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+			properties["holocron_profile"] = deriveProfile({
+				rootPackageJson,
+				repoName: basename(input.context.repoRoot),
+				isMonorepo,
+				workspacePackageJsons
+			});
+			properties["holocron_stack"] = deriveStack(rootPackageJson);
+			const capabilities = deriveCapabilities(config.providers);
+			properties["holocron_capabilities"] = capabilities;
+			properties["holocron_compliance"] = deriveCompliance(capabilities);
+		}
 		if (source.syncProperties) {
 			steps.push(await runStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
 			print(formatStep(steps[steps.length - 1]));
@@ -6078,7 +6191,7 @@ async function runSync(input) {
 				const repo = config.repo;
 				const properties = {};
 				const effectivePreset = repo?.protection;
-				if (effectivePreset && effectivePreset !== "none") properties["branch_protection_level"] = effectivePreset;
+				if (effectivePreset && effectivePreset !== "none") properties["holocron_branch_protection_level"] = effectivePreset;
 				const isMonorepo = await access(join(input.context.repoRoot, "pnpm-workspace.yaml")).then(() => true).catch(() => false);
 				properties["monorepo"] = String(isMonorepo);
 				const manual = repo?.properties ?? {};
@@ -6086,6 +6199,21 @@ async function runSync(input) {
 				if (manual.open_source !== void 0) properties["open_source"] = String(manual.open_source);
 				if (manual.runtime_environment) properties["runtime_environment"] = manual.runtime_environment;
 				if (manual.uses_external_packages !== void 0) properties["uses_external_packages"] = String(manual.uses_external_packages);
+				{
+					const rootPackageJson = await readFile(join(input.context.repoRoot, "package.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+					const workspacePackages = readWorkspacePackages(input.context.repoRoot);
+					const workspacePackageJsons = await readWorkspacePackageJsons(input.context.repoRoot, workspacePackages);
+					properties["holocron_profile"] = deriveProfile({
+						rootPackageJson,
+						repoName: basename(input.context.repoRoot),
+						isMonorepo,
+						workspacePackageJsons
+					});
+					properties["holocron_stack"] = deriveStack(rootPackageJson);
+					const capabilities = deriveCapabilities(config.providers);
+					properties["holocron_capabilities"] = capabilities;
+					properties["holocron_compliance"] = deriveCompliance(capabilities);
+				}
 				steps.push(await runSyncStep("source", "sync properties", dryRun, () => source.syncProperties(properties)));
 				print(formatSyncStep(steps[steps.length - 1]));
 			} else {