@theholocron/cli 2.0.0-alpha.56 → 2.0.0-alpha.57

package/README.md

@@ -56,10 +56,10 @@ export default defineConfig({
 `name` and `repo.name` are optional. When absent, Holocron fills them
 in at load time:
 
-| Field | Derived from | Fallback |
-|---|---|---|
-| `name` | `package.json` → `name` field (scope stripped) | directory basename |
-| `repo.name` | `git remote get-url origin` (parsed to `owner/repo`) | not set |
+| Field       | Derived from                                         | Fallback           |
+| ----------- | ---------------------------------------------------- | ------------------ |
+| `name`      | `package.json` → `name` field (scope stripped)       | directory basename |
+| `repo.name` | `git remote get-url origin` (parsed to `owner/repo`) | not set            |
 
 A minimal config — for repos with a `package.json` and a GitHub remote
 — only needs `providers`:

package/dist/capabilities/index.d.mts

@@ -137,6 +137,11 @@ interface Source extends ProviderIdentity {
    * Optional — providers that don't support topics omit this.
    */
   syncTopics?(topics: string[]): Promise<string>;
+  /**
+   * Set the repository description.
+   * Optional — providers that don't support setting descriptions omit this.
+   */
+  syncDescription?(description: string): Promise<string>;
 }
 type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
 interface CiRun {

package/dist/cli.mjs

@@ -8,7 +8,7 @@ import { Entry, findCredentials } from "@napi-rs/keyring";
 import { createHash } from "node:crypto";
 import { createGitHubClient } from "@theholocron/github-client";
 import { execFile, spawnSync } from "node:child_process";
-import { access, readFile, stat } from "node:fs/promises";
+import { access, readFile, stat, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 //#region src/capabilities/index.ts
@@ -4269,7 +4269,9 @@ function formatStep(step) {
 const SYNC_STEPS = [
 	"labels",
 	"properties",
-	"topics"
+	"topics",
+	"keywords",
+	"description"
 ];
 async function runSync(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -4345,6 +4347,47 @@ async function runSync(input) {
 					print(formatSyncStep(steps[steps.length - 1]));
 				}
 			}
+			if (stepName === "keywords") {
+				const topics = config.repo?.topics ?? [];
+				if (topics.length === 0) {
+					steps.push({
+						capability: "source",
+						step: "sync keywords",
+						status: "skip",
+						message: "no topics configured"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push(await runSyncStep("source", "sync keywords", dryRun, async () => {
+						return await writePackageJsonField(input.context.repoRoot, "keywords", topics) ? `${topics.length} keywords written` : `${topics.length} topics (no package.json)`;
+					}));
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
+			}
+			if (stepName === "description") {
+				const description = config.description;
+				if (!description) {
+					steps.push({
+						capability: "source",
+						step: "sync description",
+						status: "skip",
+						message: "no description configured"
+					});
+					print(formatSyncStep(steps[steps.length - 1]));
+				} else {
+					steps.push(await runSyncStep("source", "sync description", dryRun, async () => {
+						const pkgWrote = await writePackageJsonField(input.context.repoRoot, "description", description);
+						const readmeWrote = await updateReadmeDescription(input.context.repoRoot, description);
+						if (source.syncDescription) await source.syncDescription(description);
+						const parts = [];
+						if (pkgWrote) parts.push("package.json");
+						if (readmeWrote) parts.push("README.md");
+						if (source.syncDescription) parts.push("GitHub");
+						return parts.length > 0 ? parts.join(", ") + " updated" : "description synced";
+					}));
+					print(formatSyncStep(steps[steps.length - 1]));
+				}
+			}
 		}
 		if (requestedSteps) {
 			for (const name of requestedSteps) if (!SYNC_STEPS.includes(name)) {
@@ -4406,6 +4449,44 @@ function formatSyncStep(step) {
 	const detail = step.message ? `  (${step.message})` : "";
 	return `    ${icon} ${step.step}${detail}`;
 }
+async function writePackageJsonField(repoRoot, field, value) {
+	const pkgPath = join(repoRoot, "package.json");
+	let content;
+	try {
+		content = await readFile(pkgPath, "utf8");
+	} catch {
+		return false;
+	}
+	const pkg = JSON.parse(content);
+	pkg[field] = value;
+	await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+	return true;
+}
+const README_DESC_START = "<!-- holocron:description -->";
+const README_DESC_END = "<!-- /holocron:description -->";
+async function updateReadmeDescription(repoRoot, description) {
+	const readmePath = join(repoRoot, "README.md");
+	let content;
+	try {
+		content = await readFile(readmePath, "utf8");
+	} catch {
+		return false;
+	}
+	const lines = content.split("\n");
+	const startIdx = lines.findIndex((l) => l.trim() === README_DESC_START);
+	const endIdx = lines.findIndex((l) => l.trim() === README_DESC_END);
+	if (startIdx !== -1) {
+		if (endIdx === -1 || endIdx <= startIdx) return false;
+		lines.splice(startIdx + 1, endIdx - startIdx - 1, description);
+		await writeFile(readmePath, lines.join("\n"), "utf8");
+		return true;
+	}
+	const h1Index = lines.findIndex((l) => /^# /.test(l));
+	if (h1Index === -1) return false;
+	lines.splice(h1Index + 1, 0, "", README_DESC_START, description, README_DESC_END);
+	await writeFile(readmePath, lines.join("\n"), "utf8");
+	return true;
+}
 //#endregion
 //#region src/load-config.ts
 /**

package/package.json

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