claudeup 4.36.0 → 4.38.0

package/src/services/terminology-filler.ts

@@ -0,0 +1,266 @@
+/**
+ * Fill the `terminology` template preset from the project's own codebase.
+ *
+ * `terminology` ships as a template: a vocabulary table with a placeholder row,
+ * useless until someone fills it with THIS project's words. Doing that by hand
+ * means reading the codebase and noticing where two names describe one concept
+ * — exactly the sort of survey a coding agent is good at.
+ *
+ * ## Why Claude only returns rows
+ *
+ * The subprocess is asked for table rows and nothing else; claudeup does the
+ * file writing. Two reasons, both practical:
+ *
+ *  1. **No write permission is needed.** `claude -p` runs with read-only tools,
+ *     so the worst case of a bad run is a useless answer, never a modified
+ *     repository.
+ *  2. **The template's fixed rules cannot be lost.** Everything below the table
+ *     is substantive guidance that must survive verbatim. Asking a model to
+ *     reproduce a whole file invites it to paraphrase; asking for six table
+ *     rows does not.
+ *
+ * The TUI stays on screen throughout: the child's stdio is piped, never
+ * inherited, so it cannot take the terminal away from OpenTUI the way
+ * `runClaude` deliberately does for CLI use.
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import fs from "fs-extra";
+import { which } from "../utils/command-utils.js";
+
+export interface TerminologyRow {
+	use: string;
+	not: string;
+	because: string;
+}
+
+/** The placeholder row the shipped template carries. */
+const PLACEHOLDER = /^\|.*filled during.*\|.*$/im;
+
+/** Table rows are asked for in this exact shape, so the parse can be strict. */
+export function parseTerminologyRows(stdout: string): TerminologyRow[] {
+	const rows: TerminologyRow[] = [];
+	for (const raw of stdout.split("\n")) {
+		const line = raw.trim();
+		if (!line.startsWith("|")) continue;
+
+		// The trailing pipe is optional. Both are valid markdown and a model
+		// asked for `| a | b | c |` will sometimes emit it without the closer —
+		// discarding that row would silently lose a real term.
+		const cells = line
+			.slice(1)
+			.replace(/\|$/, "")
+			.split("|")
+			.map((cell) => cell.trim());
+		if (cells.length !== 3) continue;
+
+		// A model that ignores "no header row" tends to emit the header and the
+		// `|---|---|---|` separator anyway. Both are noise, not data.
+		if (cells.every((cell) => /^:?-{2,}:?$/.test(cell))) continue;
+		if (cells[0].toLowerCase() === "use" && cells[1].toLowerCase() === "not") {
+			continue;
+		}
+		if (!cells[0] || !cells[1]) continue;
+
+		rows.push({ use: cells[0], not: cells[1], because: cells[2] });
+	}
+	return rows;
+}
+
+/**
+ * Put the rows into the template, replacing its placeholder.
+ *
+ * Everything else in the body — the heading, the opening statement, and the
+ * rules below the table — is copied through untouched.
+ */
+export function fillTemplate(
+	templateBody: string,
+	rows: TerminologyRow[],
+): string {
+	if (rows.length === 0) {
+		throw new Error("No usable table rows were produced.");
+	}
+	const rendered = rows
+		.map((row) => `| ${row.use} | ${row.not} | ${row.because} |`)
+		.join("\n");
+
+	if (PLACEHOLDER.test(templateBody)) {
+		return templateBody.replace(PLACEHOLDER, rendered);
+	}
+	// The template changed shape upstream. Appending after the separator is
+	// still better than silently returning a table with no rows.
+	return templateBody.replace(/^(\|\s*-{2,}.*\|)\s*$/im, `$1\n${rendered}`);
+}
+
+/** The complete output-style file for the filled terminology preset. */
+export function terminologyStyleFile(body: string): string {
+	return [
+		"---",
+		"name: terminology",
+		'description: "Project vocabulary — one name per concept"',
+		// Same reasoning as everywhere else: a communication style must not
+		// switch off Claude Code's coding rules.
+		"keep-coding-instructions: true",
+		'generated-by: "claudeup Styles tab, filled from the codebase by Claude Code."',
+		"---",
+		"",
+		body.trim(),
+		"",
+	].join("\n");
+}
+
+export function buildPrompt(templateBody: string): string {
+	return [
+		"You are filling in one table for a project's communication-style guide.",
+		"",
+		"Read enough of this codebase to identify its domain vocabulary: the nouns",
+		"that name its core concepts, and the places where two different words are",
+		"used for the same thing.",
+		"",
+		"Output ONLY markdown table rows, one per line, in exactly this form:",
+		"",
+		"| use | not | because |",
+		"",
+		"Rules:",
+		"- No header row, no `|---|` separator, no code fence, no commentary.",
+		"- Between 5 and 15 rows.",
+		// Bounded on purpose: without a budget this wanders a large repository
+		// for many minutes, and the marginal term found on the 80th file is not
+		// worth the wait.
+		"- Budget yourself: read at most ~25 files. Prefer README, the main",
+		"  entry points, type definitions and directory names over exhaustive",
+		"  coverage — the vocabulary shows up there first.",
+		"- Every row must come from THIS codebase. Do not invent generic examples.",
+		"- `use` is the name the project should standardise on.",
+		"- `not` is a synonym actually present in the repo, or one a newcomer would",
+		"  plausibly reach for.",
+		"- `because` is one clause, lower case, no trailing full stop.",
+		"",
+		"For context, this is the guide the table goes into:",
+		"",
+		templateBody,
+	].join("\n");
+}
+
+/**
+ * How long to let the survey run before giving up.
+ *
+ * Generous, because reading a large repository legitimately takes minutes — but
+ * bounded, because without it a wedged subprocess leaves the screen showing
+ * "reading the codebase" forever with no way back.
+ */
+export const FILL_TIMEOUT_MS = 5 * 60 * 1000;
+
+export interface FillTerminologyArgs {
+	projectPath: string;
+	/** Body of the shipped `terminology` preset, table placeholder included. */
+	templateBody: string;
+	/** Injectable for tests. Returns the subprocess's stdout. */
+	run?: (prompt: string, projectPath: string) => Promise<string>;
+}
+
+export interface FillTerminologyResult {
+	path: string;
+	rows: TerminologyRow[];
+}
+
+/**
+ * Run Claude Code over the project and write the filled preset.
+ *
+ * Written to the PROJECT's output-styles directory, so the vocabulary it
+ * discovers commits with the repository — a project's terminology is a team
+ * fact, not one person's setting.
+ */
+export async function fillTerminology({
+	projectPath,
+	templateBody,
+	run = runClaudeHeadless,
+}: FillTerminologyArgs): Promise<FillTerminologyResult> {
+	const stdout = await run(buildPrompt(templateBody), projectPath);
+	const rows = parseTerminologyRows(stdout);
+	if (rows.length === 0) {
+		throw new Error(
+			"Claude Code returned no usable table rows — nothing was written.",
+		);
+	}
+
+	const file = path.join(
+		projectPath,
+		".claude",
+		"output-styles",
+		"terminology.md",
+	);
+	await fs.ensureDir(path.dirname(file));
+	await fs.writeFile(
+		file,
+		terminologyStyleFile(fillTemplate(templateBody, rows)),
+		"utf8",
+	);
+	return { path: file, rows };
+}
+
+/**
+ * `claude -p` with read-only tools, stdio piped.
+ *
+ * `--allowedTools` is the point: the subprocess can look at the repository and
+ * cannot change it, so a bad run costs time and nothing else.
+ */
+async function runClaudeHeadless(
+	prompt: string,
+	projectPath: string,
+): Promise<string> {
+	const claudePath = await which("claude");
+	if (!claudePath) {
+		throw new Error(
+			"claude CLI not found in PATH. Install it with: npm install -g @anthropic-ai/claude-code",
+		);
+	}
+
+	return new Promise((resolve, reject) => {
+		const child = spawn(
+			claudePath,
+			["-p", prompt, "--allowedTools", "Read,Grep,Glob"],
+			{
+				cwd: projectPath,
+				// Piped, never inherited — inheriting would hand our TTY to the
+				// child and tear the TUI apart mid-render.
+				stdio: ["ignore", "pipe", "pipe"],
+			},
+		);
+
+		let out = "";
+		let err = "";
+		child.stdout.on("data", (chunk) => {
+			out += String(chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			err += String(chunk);
+		});
+
+		const timer = setTimeout(() => {
+			child.kill("SIGTERM");
+			reject(
+				new Error(
+					`Gave up after ${Math.round(FILL_TIMEOUT_MS / 60000)} minutes — nothing was written. Try again, or fill the table by hand.`,
+				),
+			);
+		}, FILL_TIMEOUT_MS);
+
+		child.once("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+		child.once("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve(out);
+			else {
+				reject(
+					new Error(
+						`claude exited ${code}${err.trim() ? `: ${err.trim().split("\n")[0]}` : ""}`,
+					),
+				);
+			}
+		});
+	});
+}

package/src/ui/App.tsx

@@ -20,6 +20,7 @@ import {
 	CliToolsScreen,
 	ProfilesScreen,
 	SkillsScreen,
+	StylesScreen,
 	GitignoreScreen,
 	AliasScreen,
 } from "./screens/index.js";
@@ -76,6 +77,8 @@ function Router() {
 			return <ProfilesScreen />;
 		case "skills":
 			return <SkillsScreen />;
+		case "styles":
+			return <StylesScreen />;
 		case "gitignore":
 			return <GitignoreScreen />;
 		case "alias":
@@ -130,7 +133,7 @@ function GlobalKeyHandler({
 		// Don't handle keys when modal is open or searching
 		if (state.modal || state.isSearching) return;
 
-		// Global navigation shortcuts (1-8) - include mcp-registry as it's a sub-screen of mcp
+		// Global navigation shortcuts (1-9) - include mcp-registry as it's a sub-screen of mcp
 		const isTopLevel = [
 			"plugins",
 			"mcp",
@@ -139,6 +142,7 @@ function GlobalKeyHandler({
 			"cli-tools",
 			"profiles",
 			"skills",
+			"styles",
 			"gitignore",
 			"alias",
 		].includes(state.currentRoute.screen);
@@ -152,6 +156,7 @@ function GlobalKeyHandler({
 			else if (input === "6") navigateToScreen("cli-tools");
 			else if (input === "7") navigateToScreen("gitignore");
 			else if (input === "8") navigateToScreen("alias");
+			else if (input === "9") navigateToScreen("styles");
 
 			// Tab navigation cycling
 			if (key.tab) {
@@ -164,6 +169,7 @@ function GlobalKeyHandler({
 					"cli-tools",
 					"gitignore",
 					"alias",
+					"styles",
 				];
 				const currentIndex = screens.indexOf(
 					state.currentRoute.screen as Screen,
@@ -213,7 +219,7 @@ function GlobalKeyHandler({
 Quick Navigation
   1  Plugins      4  Settings    7  Git State
   2  Skills       5  Profiles    8  Alias
-  3  MCP Servers  6  CLI Tools
+  3  MCP Servers  6  CLI Tools   9  Styles
 
 Plugin Actions
   u  Update        d  Uninstall
@@ -221,7 +227,13 @@ Plugin Actions
 
 MCP Servers
   /  Search local + remote
-  r  Browse MCP registry`,
+  r  Browse MCP registry
+
+Styles
+  Space  Tick / untick a style
+  a      Apply the selection to this project
+  x      Reset the selection to what is live
+  c      Clear the active output style`,
 				"info",
 			);
 		}

package/src/ui/adapters/catalogNotice.ts

@@ -0,0 +1,122 @@
+/**
+ * catalogNotice.ts — the text of the Plugins screen's warning line.
+ *
+ * Extracted from PluginsScreen for the same reason as pluginsAdapter: so it can
+ * be tested without importing a React/OpenTUI screen. That is not merely tidier —
+ * importing the screen into a test pulls the renderer into the shared test process
+ * and broke fifteen unrelated tests.
+ *
+ * What this does NOT warn about, deliberately
+ * -------------------------------------------
+ * `autoUpdate: false` and a marketplace clone sitting behind its remote are both
+ * NORMAL here. Plugins are not auto-updated by policy; the UI's job is to show
+ * that an update exists, not to advance the install source. An earlier version of
+ * this banner reported both as problems and suggested
+ * `claude plugin marketplace update`, which would have defeated the policy it was
+ * complaining about. A warning that fires on intended behaviour trains the user to
+ * ignore the line.
+ *
+ * The one thing worth warning about is an update check that did not happen —
+ * because the alternative is claiming a plugin is current when nobody looked.
+ */
+
+import { formatWait } from "../../services/github-budget.js";
+import type { MarketplaceFetchFailure } from "../../services/marketplace-fetcher.js";
+
+export interface CatalogNoticeInput {
+	/** Catalogs that could not be read from any authoritative source. */
+	failures: MarketplaceFetchFailure[];
+	/** Installed plugins whose version could not be verified against upstream. */
+	unverifiedPlugins: number;
+	/** Terminal columns available for the line. */
+	width: number;
+	/** For the countdown; injected so tests are not clock-dependent. */
+	now?: number;
+}
+
+/**
+ * One line naming why some versions on screen could not be verified — or `null`
+ * when everything was actually checked.
+ *
+ * Returns `null` when there is nothing wrong: a banner that is always present is
+ * a banner nobody reads.
+ *
+ * Segments are added in priority order and dropped from the end when they do not
+ * fit `width`. Listing every failing marketplace overflowed an 80-column pane and
+ * took the retry hint with it — a warning truncated mid-sentence is barely better
+ * than no warning.
+ */
+export function buildCatalogNoticeText({
+	failures,
+	unverifiedPlugins,
+	width,
+	now = Date.now(),
+}: CatalogNoticeInput): string | null {
+	if (failures.length === 0) return null;
+
+	const segments: string[] = [];
+
+	// Lead with the reason, not the names: "rate limit" tells the user to wait,
+	// "timed out" tells them to check the network. That distinction is the whole
+	// value of classifying the failure, and it costs few characters.
+	const kinds = new Set(failures.map((f) => f.kind));
+	const rateLimited = kinds.has("rate-limited");
+	const reason = rateLimited
+		? "GitHub rate limit"
+		: kinds.has("timeout")
+			? "GitHub timed out"
+			: (failures[0]?.detail ?? "fetch failed");
+
+	const noun = failures.length === 1 ? "catalog" : "catalogs";
+	// Naming them only pays off when there are one or two; past that the count
+	// carries the same information in a fraction of the width.
+	const named =
+		failures.length <= 2
+			? `: ${failures.map((f) => f.marketplace).join(", ")}`
+			: "";
+	segments.push(`${failures.length} ${noun} unchecked (${reason})${named}`);
+
+	if (unverifiedPlugins > 0) {
+		segments.push(
+			`${unverifiedPlugins} version${unverifiedPlugins === 1 ? "" : "s"} unverified`,
+		);
+	}
+
+	// The countdown replaces the bare retry hint when we know when the window
+	// reopens. Answering "when can I try again" is the point: "try later" leaves
+	// the user to guess, and guessing wrong spends another request against the
+	// limit. Soonest retry across all failures, since that is when anything at all
+	// becomes possible again.
+	const retryAt = failures
+		.map((f) => f.retryAt)
+		.filter((t): t is number => typeof t === "number" && t > now)
+		.sort((a, b) => a - b)[0];
+
+	const hint = retryAt
+		? ` · retrying in ${formatWait(retryAt - now)}`
+		: " · r to retry";
+
+	// Column budget. `⚠` renders double-width in most terminals while
+	// `String.length` counts it as one, so one column is held back for it.
+	const maxColumns = Math.max(1, width - 1);
+
+	// The retry affordance is reserved out of the budget rather than appended: it
+	// is the only action the line offers, so it is the last thing that may be cut.
+	// No floor on what remains — a floor is what let a 40-column pane overflow by
+	// two, which is the whole failure mode this budget exists to prevent.
+	const messageBudget = maxColumns - hint.length;
+
+	let line = `⚠ ${segments[0]}`;
+	for (const segment of segments.slice(1)) {
+		const candidate = `${line} · ${segment}`;
+		if (candidate.length > messageBudget) break;
+		line = candidate;
+	}
+	if (line.length > messageBudget) {
+		line = messageBudget > 1 ? `${line.slice(0, messageBudget - 1)}…` : "";
+	}
+
+	// Absurdly narrow pane: the hint alone does not fit. Truncate it rather than
+	// return a line that overflows and corrupts the layout.
+	return `${line}${hint}`.slice(0, maxColumns);
+}