@theholocron/cli 3.13.0 → 3.14.0

package/dist/cli.mjs

@@ -264,7 +264,8 @@ function resolveConfig(raw) {
 		doctor: raw.doctor ?? {},
 		agent: raw.agent,
 		skills: raw.skills,
-		docs
+		docs,
+		env: raw.env
 	};
 }
 //#endregion
@@ -3453,11 +3454,13 @@ async function runSetup(input) {
 		print(style.hint("       · Workflows               — read and write"));
 		print(style.hint("       · Metadata                — read (added automatically)"));
 		print("");
-		print(style.hint("     Org-scoped operations (teams, custom properties) additionally require"));
-		print(style.hint("     HOLOCRON_ORG_TOKEN — a PAT scoped to the org with:"));
+		print(style.hint("     Org-scoped operations (teams, custom properties) require"));
+		print(style.hint("     HOLOCRON_ORG_TOKEN — a fine-grained PAT with resource owner set to the org:"));
 		print("");
-		print(style.hint("       · Members                     — read and write"));
-		print(style.hint("       · Organization custom properties — read and write"));
+		print(style.hint("       · Administration          — read and write (repository permission)"));
+		print(style.hint("       · Members                 — read (organization permission)"));
+		print(style.hint("       · Organization custom properties — read and write (organization permission)"));
+		print(style.hint("       · Metadata                — read (repository permission, auto-included)"));
 		print("");
 		print(style.hint("     Create tokens at: https://github.com/settings/personal-access-tokens/new"));
 		print(style.hint("     Then re-run:      holocron setup --token <your-admin-pat>"));
@@ -4441,6 +4444,86 @@ async function runSyncGithub(input) {
 	};
 }
 //#endregion
+//#region src/commands/sync-readme.ts
+const README_INSTALL_START = "<!-- holocron:installation -->";
+const README_INSTALL_END = "<!-- /holocron:installation -->";
+function generateInstallBlock(pkg) {
+	const { name = "", bin, peerDependencies = {} } = pkg;
+	const isCli = Boolean(bin);
+	const isReact = Boolean(peerDependencies["react"]);
+	const lines = [];
+	lines.push("## Installation", "");
+	if (isCli) lines.push("```bash", `npm install --global ${name}`, "```");
+	else lines.push("```bash", `pnpm install ${name}`, "```");
+	lines.push("", "## Usage", "");
+	if (isCli) {
+		const commands = typeof bin === "string" ? [name.split("/").at(-1)] : Object.keys(bin ?? {});
+		lines.push("```bash");
+		for (const cmd of commands) lines.push(`${cmd} --help`);
+		lines.push("```");
+	} else if (isReact) lines.push("```tsx", `import { } from "${name}";`, "", "function App() {", `  return <></>;`, "}", "```");
+	else lines.push("```typescript", `import { } from "${name}";`, "```");
+	return lines.join("\n");
+}
+async function updateReadmeInstallation(repoRoot, block, dryRun, readFileFn, writeFileFn) {
+	const readmePath = join(repoRoot, "README.md");
+	let content;
+	try {
+		content = await readFileFn(readmePath, "utf8");
+	} catch {
+		return false;
+	}
+	const lines = content.split("\n");
+	const startIdx = lines.findIndex((l) => l.trim() === README_INSTALL_START);
+	const endIdx = lines.findIndex((l) => l.trim() === README_INSTALL_END);
+	const blockLines = block.split("\n");
+	if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+		if (dryRun) return true;
+		lines.splice(startIdx + 1, endIdx - startIdx - 1, "", ...blockLines, "");
+		await writeFileFn(readmePath, lines.join("\n"), "utf8");
+		return true;
+	}
+	const descEnd = lines.findIndex((l) => l.trim() === "<!-- /holocron:description -->");
+	const insertAfter = descEnd !== -1 ? descEnd : lines.findIndex((l) => /^# /.test(l));
+	if (insertAfter === -1) return false;
+	if (dryRun) return true;
+	lines.splice(insertAfter + 1, 0, "", README_INSTALL_START, "", ...blockLines, "", README_INSTALL_END);
+	await writeFileFn(readmePath, lines.join("\n"), "utf8");
+	return true;
+}
+async function runSyncReadme(input) {
+	const { loaded, context, print = console.log, readFileFn = readFile, writeFileFn = writeFile } = input;
+	const { repoRoot, dryRun = false } = context;
+	const namespaces = loaded.resolved.env?.namespaces ?? [];
+	print(style.header(`Syncing README installation block${dryRun ? " (dry-run)" : ""}…`));
+	if (namespaces.length > 0) print(style.hint(`  namespaces: ${namespaces.join(", ")}`));
+	let pkg;
+	try {
+		const raw = await readFileFn(join(repoRoot, "package.json"), "utf8");
+		pkg = JSON.parse(raw);
+	} catch {
+		return {
+			status: "fail",
+			updated: false,
+			message: "Could not read package.json"
+		};
+	}
+	const updated = await updateReadmeInstallation(repoRoot, generateInstallBlock(pkg), dryRun, readFileFn, writeFileFn);
+	if (!updated) {
+		print(style.warn("README.md not found or has no writable location for installation block"));
+		return {
+			status: "fail",
+			updated: false,
+			message: "README.md update failed"
+		};
+	}
+	print(dryRun ? style.hint("  would update README.md") : style.success("  updated README.md"));
+	return {
+		status: dryRun ? "dry-run" : "ok",
+		updated
+	};
+}
+//#endregion
 //#region src/commands/upgrade-node.ts
 const SKIP_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
@@ -5217,6 +5300,18 @@ try {
 			...argv.message ? { message: argv.message } : {},
 			...outputDir ? { outputDir } : {}
 		})).status === "fail") process.exitCode = 1;
+	}).command("sync-readme", "Sync the Installation + Usage block in README.md from package.json", (y) => y.option("dry-run", {
+		type: "boolean",
+		describe: "Print what would change without writing",
+		default: false
+	}), async (argv) => {
+		if ((await runSyncReadme({
+			loaded: await loadConfig(argv.cwd),
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun
+			}
+		})).status === "fail") process.exitCode = 1;
 	}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
 		const loaded = await loadConfig(argv.cwd);
 		console.log(JSON.stringify(loaded.resolved, null, 2));