@kr78/pi-coding-agent 17.2.10

package/src/slash-commands/helpers/stats-dashboard.ts

@@ -0,0 +1,86 @@
+import * as stats from "@oh-my-pi/omp-stats";
+import * as openUtils from "../../utils/open";
+
+export const DEFAULT_STATS_DASHBOARD_PORT = 3847;
+
+interface StatsDashboardServer {
+	hostname: string;
+	port: number;
+	stop: () => void;
+}
+
+export interface StatsDashboardArgs {
+	port: number;
+}
+
+export interface StatsDashboardLaunchResult {
+	url: string;
+	message: string;
+}
+
+let activeStatsServer: StatsDashboardServer | undefined;
+
+const STATS_DASHBOARD_USAGE = "Usage: /stats [--port <port>]";
+
+function parsePort(value: string | undefined): number | string {
+	if (!value) return `Missing port. ${STATS_DASHBOARD_USAGE}`;
+	if (!/^\d+$/.test(value)) return `Invalid port: ${value}`;
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 0 || port > 65_535) return `Invalid port: ${value}`;
+	return port;
+}
+
+export function parseStatsDashboardArgs(args: string): StatsDashboardArgs | { error: string } {
+	const tokens = args.split(/\s+/).filter(Boolean);
+	let port = DEFAULT_STATS_DASHBOARD_PORT;
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--port" || token === "-p") {
+			const parsed = parsePort(tokens[++i]);
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		if (token.startsWith("--port=")) {
+			const parsed = parsePort(token.slice("--port=".length));
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		return { error: `Unknown option: ${token}. ${STATS_DASHBOARD_USAGE}` };
+	}
+
+	return { port };
+}
+
+export async function launchStatsDashboard(args: StatsDashboardArgs): Promise<StatsDashboardLaunchResult> {
+	const { processed, files } = await stats.syncAllSessions();
+	const total = await stats.getTotalMessageCount();
+	let requestedPortIgnored = false;
+
+	if (!activeStatsServer) {
+		activeStatsServer = await stats.startServer(args.port);
+	} else if (args.port !== activeStatsServer.port) {
+		requestedPortIgnored = true;
+	}
+
+	const url = `http://${activeStatsServer.hostname}:${activeStatsServer.port}`;
+	openUtils.openPath(url);
+
+	const serverLine = requestedPortIgnored
+		? `Dashboard already running at: ${url} (requested port ${args.port} ignored)`
+		: `Dashboard available at: ${url}`;
+
+	return {
+		url,
+		message: `Synced ${processed} new entries from ${files} files (${total} total)\n${serverLine}`,
+	};
+}
+
+export function stopStatsDashboard(): void {
+	if (!activeStatsServer) return;
+	activeStatsServer.stop();
+	activeStatsServer = undefined;
+	stats.closeDb();
+}

package/src/slash-commands/helpers/todo.ts

@@ -0,0 +1,285 @@
+import type { TodoPhase } from "../../tools/todo";
+import {
+	applyOpsToPhases,
+	getLatestTodoPhasesFromEntries,
+	markdownToPhases,
+	phasesToMarkdown,
+	resolveTodoMarkdownPath,
+	USER_TODO_EDIT_CUSTOM_TYPE,
+} from "../../tools/todo";
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+import { commandConsumed, errorMessage, parseSubcommand, usage } from "./parse";
+
+type TodoMutationVerb = "done" | "drop" | "rm";
+
+interface TodoTaskMatch {
+	task: { content: string; status: string };
+	phase: TodoPhase;
+}
+
+function tokenize(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuote = false;
+	for (let index = 0; index < input.length; index++) {
+		const ch = input[index];
+		if (ch === "\\" && index + 1 < input.length) {
+			current += input[++index];
+			continue;
+		}
+		if (ch === '"') {
+			inQuote = !inQuote;
+			continue;
+		}
+		if (!inQuote && /\s/.test(ch)) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += ch;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+
+function titleCaseWords(text: string): string {
+	return text
+		.split(/\s+/)
+		.filter(Boolean)
+		.map(word => word[0].toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+function titleCaseSentence(text: string): string {
+	const trimmed = text.trim();
+	if (!trimmed) return trimmed;
+	return trimmed[0].toUpperCase() + trimmed.slice(1);
+}
+
+function findPhaseFuzzy(phases: TodoPhase[], query: string): TodoPhase | undefined {
+	const normalizedQuery = query.trim().toLowerCase();
+	if (!normalizedQuery) return undefined;
+	const exact = phases.find(phase => phase.name.toLowerCase() === normalizedQuery);
+	if (exact) return exact;
+	const prefixMatches = phases.filter(phase => phase.name.toLowerCase().startsWith(normalizedQuery));
+	if (prefixMatches.length === 1) return prefixMatches[0];
+	const substringMatches = phases.filter(phase => phase.name.toLowerCase().includes(normalizedQuery));
+	if (substringMatches.length === 1) return substringMatches[0];
+	return undefined;
+}
+
+function findTaskFuzzy(phases: TodoPhase[], query: string): TodoTaskMatch | undefined {
+	const normalizedQuery = query.trim().toLowerCase();
+	if (!normalizedQuery) return undefined;
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase() === normalizedQuery) return { task, phase };
+		}
+	}
+	const matches: TodoTaskMatch[] = [];
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase().includes(normalizedQuery)) matches.push({ task, phase });
+		}
+	}
+	if (matches.length === 1) return matches[0];
+	const active = matches.filter(match => match.task.status === "in_progress" || match.task.status === "pending");
+	if (active.length === 1) return active[0];
+	return undefined;
+}
+
+function currentPhases(runtime: SlashCommandRuntime): TodoPhase[] {
+	const fromEntries = getLatestTodoPhasesFromEntries(runtime.sessionManager.getBranch());
+	return fromEntries.length > 0 ? fromEntries : runtime.session.getTodoPhases();
+}
+
+function commitTodos(runtime: SlashCommandRuntime, phases: TodoPhase[]): void {
+	runtime.session.setTodoPhases(phases);
+	runtime.sessionManager.appendCustomEntry(USER_TODO_EDIT_CUSTOM_TYPE, { phases });
+}
+
+const TODO_HELP_TEXT = [
+	"Usage: /todo <verb> [args]",
+	"  /todo                              Show current todos",
+	"  /todo edit                         (TUI only) open in $EDITOR",
+	"  /todo copy                         Print todos as Markdown",
+	"  /todo export [<path>]              Write todos to file (default: TODO.md)",
+	"  /todo import [<path>]              Replace todos from file (default: TODO.md)",
+	"  /todo append [<phase>] <task...>   Append a task",
+	"  /todo start  <task>                Mark task in_progress (fuzzy match)",
+	"  /todo done   [<task|phase>]        Mark task/phase/all completed",
+	"  /todo drop   [<task|phase>]        Mark task/phase/all abandoned",
+	"  /todo rm     [<task|phase>]        Remove task/phase/all",
+].join("\n");
+
+async function handleTodoCopyCommand(runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const phases = currentPhases(runtime);
+	const markdown = phases.length === 0 ? "" : phasesToMarkdown(phases).trimEnd();
+	await runtime.output(`Copy not available in ACP mode; printing instead:\n\n${markdown || "No todos."}`);
+	return commandConsumed();
+}
+
+async function handleTodoExportCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const phases = currentPhases(runtime);
+	if (phases.length === 0) {
+		await runtime.output("No todos to export.");
+		return commandConsumed();
+	}
+	let target: string;
+	try {
+		target = resolveTodoMarkdownPath(restArgs, runtime.sessionManager.getCwd());
+		await Bun.write(target, phasesToMarkdown(phases));
+	} catch (err) {
+		return usage(`Failed to write todos: ${errorMessage(err)}`, runtime);
+	}
+	await runtime.output(`Wrote todos to ${target}`);
+	return commandConsumed();
+}
+
+async function handleTodoImportCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	let target: string;
+	let content: string;
+	try {
+		target = resolveTodoMarkdownPath(restArgs, runtime.sessionManager.getCwd());
+		content = await Bun.file(target).text();
+	} catch (err) {
+		return usage(`Failed to read todos: ${errorMessage(err)}`, runtime);
+	}
+	const { phases, errors } = markdownToPhases(content);
+	if (errors.length > 0) return usage(`Could not parse ${target}:\n  ${errors.join("\n  ")}`, runtime);
+	commitTodos(runtime, phases);
+	const taskCount = phases.reduce((sum, phase) => sum + phase.tasks.length, 0);
+	await runtime.output(`Imported ${phases.length} phase(s), ${taskCount} task(s) from ${target}.`);
+	return commandConsumed();
+}
+
+async function handleTodoAppendCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const tokens = tokenize(restArgs);
+	if (tokens.length === 0) return usage("Usage: /todo append [<phase>] <task...>", runtime);
+
+	const current = currentPhases(runtime);
+	const phaseName = tokens.length === 1 ? undefined : tokens[0];
+	const content = tokens.length === 1 ? tokens[0]! : tokens.slice(1).join(" ");
+	const next = current.map(phase => ({ ...phase, tasks: phase.tasks.slice() }));
+	let targetPhase: TodoPhase;
+
+	if (phaseName) {
+		const existing = findPhaseFuzzy(next, phaseName);
+		targetPhase = existing ?? { name: titleCaseWords(phaseName), tasks: [] };
+		if (!existing) next.push(targetPhase);
+	} else if (next.length > 0) {
+		targetPhase = next[next.length - 1]!;
+	} else {
+		targetPhase = { name: "Todos", tasks: [] };
+		next.push(targetPhase);
+	}
+
+	const finalContent = titleCaseSentence(content);
+	targetPhase.tasks.push({ content: finalContent, status: "pending" });
+	commitTodos(runtime, next);
+	await runtime.output(`Appended to ${targetPhase.name}: ${finalContent}`);
+	return commandConsumed();
+}
+
+async function handleTodoStartCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	if (!restArgs) return usage("Usage: /todo start <task>", runtime);
+	const current = currentPhases(runtime);
+	const query = tokenize(restArgs).join(" ") || restArgs;
+	const hit = findTaskFuzzy(current, query);
+	if (!hit) return usage(`No task matched "${restArgs}". Use /todo to list current tasks.`, runtime);
+	const { phases } = applyOpsToPhases(current, [{ op: "start", task: hit.task.content }]);
+	commitTodos(runtime, phases);
+	await runtime.output(`Started: ${hit.task.content}`);
+	return commandConsumed();
+}
+
+async function handleTodoMutationCommand(
+	verb: TodoMutationVerb,
+	restArgs: string,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const current = currentPhases(runtime);
+	const trimmedArg = restArgs.trim();
+	if (!trimmedArg) {
+		if (verb === "rm") {
+			commitTodos(runtime, []);
+			await runtime.output("Cleared all todos.");
+			return commandConsumed();
+		}
+		const { phases } = applyOpsToPhases(current, [{ op: verb }]);
+		commitTodos(runtime, phases);
+		await runtime.output(verb === "done" ? "Marked all tasks completed." : "Marked all tasks abandoned.");
+		return commandConsumed();
+	}
+
+	const taskHit = findTaskFuzzy(current, trimmedArg);
+	if (taskHit) {
+		const { phases } = applyOpsToPhases(current, [{ op: verb, task: taskHit.task.content }]);
+		commitTodos(runtime, phases);
+		const label = verb === "done" ? "Marked completed" : verb === "drop" ? "Marked abandoned" : "Removed";
+		await runtime.output(`${label}: ${taskHit.task.content}`);
+		return commandConsumed();
+	}
+
+	const phaseHit = findPhaseFuzzy(current, trimmedArg);
+	if (phaseHit) {
+		const { phases } = applyOpsToPhases(current, [{ op: verb, phase: phaseHit.name }]);
+		commitTodos(runtime, phases);
+		const message =
+			verb === "done"
+				? `Marked phase ${phaseHit.name} completed.`
+				: verb === "drop"
+					? `Marked phase ${phaseHit.name} abandoned.`
+					: `Removed phase: ${phaseHit.name}`;
+		await runtime.output(message);
+		return commandConsumed();
+	}
+
+	return usage(`No task or phase matched "${trimmedArg}".`, runtime);
+}
+
+/** ACP/text-mode `/todo` handler. Shared by both dispatchers via the spec. */
+export async function handleTodoAcp(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const trimmed = command.args.trim();
+	if (!trimmed) {
+		const phases = currentPhases(runtime);
+		await runtime.output(
+			phases.length === 0 ? "No todos. Use /todo append <task> to start one." : phasesToMarkdown(phases).trimEnd(),
+		);
+		return commandConsumed();
+	}
+
+	const { verb, rest } = parseSubcommand(trimmed);
+	switch (verb) {
+		case "copy":
+			return await handleTodoCopyCommand(runtime);
+		case "export":
+			return await handleTodoExportCommand(rest, runtime);
+		case "import":
+			return await handleTodoImportCommand(rest, runtime);
+		case "append":
+			return await handleTodoAppendCommand(rest, runtime);
+		case "start":
+			return await handleTodoStartCommand(rest, runtime);
+		case "done":
+		case "drop":
+		case "rm":
+			return await handleTodoMutationCommand(verb, rest, runtime);
+		case "edit":
+			return usage(
+				"/todo edit requires the TUI editor; use /todo export then /todo import for non-interactive edits.",
+				runtime,
+			);
+		case "help":
+		case "?":
+			await runtime.output(TODO_HELP_TEXT);
+			return commandConsumed();
+		default:
+			return usage("Unknown /todo subcommand. Use append, start, done, drop, rm, copy, export, import.", runtime);
+	}
+}

package/src/slash-commands/helpers/usage-report.ts

@@ -0,0 +1,198 @@
+import type { UsageLimit, UsageReport } from "@oh-my-pi/pi-ai";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import type { OAuthAccountIdentity } from "../../session/auth-storage";
+import type { SlashCommandRuntime } from "../types";
+import { reportMatchesActiveAccount } from "./active-oauth-account";
+import { formatDuration, renderAsciiBar } from "./format";
+
+function formatProviderName(provider: string): string {
+	return provider
+		.split(/[-_]/g)
+		.map(part => (part ? part[0].toUpperCase() + part.slice(1) : ""))
+		.join(" ");
+}
+
+function formatWindowSuffix(label: string, windowLabel: string | undefined): string {
+	if (!windowLabel) return "";
+	const normalizedLabel = label.toLowerCase();
+	const normalizedWindow = windowLabel.toLowerCase();
+	if (normalizedWindow === "quota window" || normalizedLabel.includes(normalizedWindow)) return "";
+	return ` — ${windowLabel}`;
+}
+
+function formatUsageAmount(limit: UsageLimit): string {
+	const amount = limit.amount;
+	const used = amount.used ?? (amount.usedFraction !== undefined ? amount.usedFraction * 100 : undefined);
+	const remainingFraction =
+		amount.remainingFraction ??
+		(amount.usedFraction !== undefined ? Math.max(0, 1 - amount.usedFraction) : undefined);
+	const unit = amount.unit === "percent" ? "%" : ` ${amount.unit}`;
+	const usedText = used === undefined ? "unknown used" : `${used.toFixed(2)}${unit} used`;
+	const remainingText = remainingFraction === undefined ? "" : ` (${(remainingFraction * 100).toFixed(1)}% left)`;
+	return `${usedText}${remainingText}`;
+}
+
+function formatUsageReportAccount(report: UsageReport, limit: UsageLimit, index: number): string {
+	const metaOrgName = report.metadata?.orgName;
+	const metaOrgId = report.metadata?.orgId;
+	const org =
+		typeof metaOrgName === "string" && metaOrgName
+			? metaOrgName
+			: typeof metaOrgId === "string" && metaOrgId
+				? metaOrgId
+				: undefined;
+	// Two subscriptions (orgs) can share one email — suffix the org so the rows
+	// are tellable apart.
+	const email = report.metadata?.email;
+	if (typeof email === "string" && email) return org ? `${email} (${org})` : email;
+	// Guard metadata values for truthiness before using, then fall back to scope.
+	// ?? won't help here: empty string is not null/undefined, so it would suppress
+	// a valid scoped fallback (e.g. metadata.accountId="" hides limit.scope.accountId).
+	const metaAccountId = report.metadata?.accountId;
+	const accountId = typeof metaAccountId === "string" && metaAccountId ? metaAccountId : limit.scope.accountId;
+	if (typeof accountId === "string" && accountId) {
+		return org && org !== accountId ? `${accountId} (${org})` : accountId;
+	}
+	const metaProjectId = report.metadata?.projectId;
+	const projectId = typeof metaProjectId === "string" && metaProjectId ? metaProjectId : limit.scope.projectId;
+	if (typeof projectId === "string" && projectId) return projectId;
+	return `account ${index + 1}`;
+}
+
+function renderUsageReports(
+	reports: UsageReport[],
+	nowMs: number,
+	resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined,
+	usageModelSelectors: readonly string[] = [],
+): string {
+	const latestFetchedAt = Math.max(...reports.map(report => report.fetchedAt ?? 0));
+	const lines = [`Usage${latestFetchedAt ? ` (${formatDuration(nowMs - latestFetchedAt)} ago)` : ""}`];
+	const grouped = new Map<string, UsageReport[]>();
+	for (const report of reports) {
+		const providerReports = grouped.get(report.provider) ?? [];
+		providerReports.push(report);
+		grouped.set(report.provider, providerReports);
+	}
+
+	for (const [provider, providerReports] of [...grouped.entries()].sort(([left], [right]) =>
+		left.localeCompare(right),
+	)) {
+		lines.push("", formatProviderName(provider));
+		const reportingModels = usageModelSelectors.filter(selector => selector.startsWith(`${provider}/`));
+		if (reportingModels.length > 0) {
+			lines.push("  Models with usage data");
+			for (const selector of reportingModels) lines.push(`    ${sanitizeText(selector)}`);
+		}
+		const activeAccount = resolveActiveAccount?.(provider);
+		// Provider-wide disclaimers render once per provider, not per limit.
+		const providerNotes = [...new Set(providerReports.flatMap(report => report.notes ?? []))];
+		for (const note of providerNotes)
+			lines.push(`  ${sanitizeText(note.replace(/[\r\n]+/g, " ").replace(/\t/g, "  "))}`);
+		for (const report of providerReports) {
+			const inUse = reportMatchesActiveAccount(report, activeAccount);
+			const savedResets = report.resetCredits?.availableCount ?? 0;
+			if (savedResets > 0) {
+				const resetLabel =
+					typeof report.metadata?.email === "string"
+						? report.metadata.email
+						: typeof report.metadata?.accountId === "string"
+							? report.metadata.accountId
+							: "account";
+				lines.push(
+					`- ${resetLabel}: ${savedResets} saved rate-limit reset${savedResets === 1 ? "" : "s"} available — /usage reset to spend`,
+				);
+				const credits = report.resetCredits?.credits;
+				if (credits) {
+					for (const credit of credits) {
+						if (credit.expiresAt) {
+							const expiryMs = Date.parse(credit.expiresAt);
+							if (!Number.isNaN(expiryMs)) {
+								const remaining = expiryMs - nowMs;
+								if (remaining > 0) {
+									lines.push(`  expires in ${formatDuration(remaining)} (${credit.expiresAt.slice(0, 10)})`);
+								} else {
+									lines.push(`  expired (${credit.expiresAt.slice(0, 10)})`);
+								}
+							}
+						}
+					}
+				}
+			}
+			if (report.limits.length === 0) {
+				const email = typeof report.metadata?.email === "string" ? report.metadata.email : "account";
+				lines.push(`- ${email}: no limits reported`);
+				continue;
+			}
+			for (let index = 0; index < report.limits.length; index++) {
+				const limit = report.limits[index]!;
+				const window = limit.window?.label ?? limit.scope.windowId;
+				// Skip the tier suffix when the label already names it (e.g. Anthropic's
+				// "Claude 7 Day (Fable)" with scope.tier "fable") — mirrors limitTitle in usage-cli.
+				const tier =
+					limit.scope.tier && !limit.label.toLowerCase().includes(limit.scope.tier.toLowerCase())
+						? ` (${limit.scope.tier})`
+						: "";
+				lines.push(`- ${limit.label}${tier}${formatWindowSuffix(limit.label, window)}`);
+				lines.push(
+					`  ${formatUsageReportAccount(report, limit, index)}: ${formatUsageAmount(limit)}${inUse ? "  ← in use by this session" : ""}`,
+				);
+				lines.push(`  ${renderAsciiBar(limit.amount.usedFraction)}`);
+				if (limit.window?.resetsAt && limit.window.resetsAt > nowMs) {
+					lines.push(
+						`  ${limit.window.resetLabel ?? "resets"} in ${formatDuration(limit.window.resetsAt - nowMs)}`,
+					);
+				}
+				if (limit.notes && limit.notes.length > 0)
+					lines.push(
+						`  ${limit.notes.map(n => sanitizeText(n.replace(/[\r\n]+/g, " ").replace(/\t/g, "  "))).join(" • ")}`,
+					);
+			}
+		}
+	}
+	return ["```", ...lines, "```"].join("\n");
+}
+
+/**
+ * Build the `/usage` ACP-mode text. Prefers provider-reported limits when the
+ * session exposes `fetchUsageReports`; otherwise falls back to the local
+ * session-manager tallies.
+ */
+export async function buildUsageReportText(runtime: SlashCommandRuntime): Promise<string> {
+	const provider = runtime.session as SlashCommandRuntime["session"] & {
+		fetchUsageReports?: () => Promise<UsageReport[] | null>;
+		getUsageReportingModelSelectors?: (reports: readonly UsageReport[]) => string[];
+	};
+	if (provider.fetchUsageReports) {
+		const reports = await provider.fetchUsageReports();
+		if (reports && reports.length > 0) {
+			const currentProvider = runtime.session.model?.provider;
+			const activeAccount = currentProvider
+				? runtime.session.modelRegistry.authStorage.getOAuthAccountIdentity(
+						currentProvider,
+						runtime.session.sessionId,
+					)
+				: undefined;
+			const usageModelSelectors = provider.getUsageReportingModelSelectors?.(reports) ?? [];
+			return renderUsageReports(
+				reports,
+				Date.now(),
+				providerId => (providerId === currentProvider ? activeAccount : undefined),
+				usageModelSelectors,
+			);
+		}
+	}
+
+	const stats = runtime.session.sessionManager.getUsageStatistics();
+	const orchestrationTokens = stats.orchestrationInput + stats.orchestrationOutput + stats.orchestrationCacheRead;
+	return [
+		"Usage",
+		`Input tokens: ${stats.input}`,
+		`Output tokens: ${stats.output}`,
+		`Cache read tokens: ${stats.cacheRead}`,
+		`Cache write tokens: ${stats.cacheWrite}`,
+		`Total tokens: ${stats.totalTokens}`,
+		...(orchestrationTokens > 0 ? [`Orchestration tokens: ${orchestrationTokens}`] : []),
+		`Premium requests: ${stats.premiumRequests}`,
+		`Cost: $${stats.cost.toFixed(6)}`,
+	].join("\n");
+}

package/src/slash-commands/marketplace-install-parser.ts

@@ -0,0 +1,99 @@
+const USAGE = "Usage: /marketplace install [--force] [--scope user|project] <name@marketplace>";
+
+export interface MarketplaceInstallArgs {
+	force: boolean;
+	scope: "user" | "project";
+	installSpec: string;
+}
+
+/**
+ * Parse the argument string following `/marketplace install`.
+ *
+ * Returns either the parsed args or an `{ error }` object whose message is
+ * suitable for direct display to the user via `ctx.showStatus`.
+ *
+ * Accepted flags (any order):
+ *   --force                 Force-reinstall even if already installed
+ *   --scope user|project    Installation scope (default: user)
+ *
+ * Exactly one positional argument is required: `name@marketplace`.
+ */
+export function parseMarketplaceInstallArgs(rest: string): MarketplaceInstallArgs | { error: string } {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let force = false;
+	let scope: "user" | "project" = "user";
+	let installSpec = "";
+
+	for (let i = 0; i < tokens.length; i++) {
+		if (tokens[i] === "--force") {
+			force = true;
+		} else if (tokens[i] === "--scope" && i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+			const s = tokens[++i];
+			if (s === "user" || s === "project") {
+				scope = s;
+			} else {
+				return { error: `Invalid --scope value: "${s}". Must be "user" or "project".` };
+			}
+		} else if (tokens[i] === "--scope") {
+			// --scope with no value, or next token is another flag
+			return { error: '--scope requires a value: "user" or "project".' };
+		} else if (tokens[i].startsWith("-")) {
+			return { error: `Unknown flag: "${tokens[i]}". ${USAGE}` };
+		} else {
+			if (installSpec) {
+				return { error: `Unexpected argument: "${tokens[i]}". ${USAGE}` };
+			}
+			installSpec = tokens[i];
+		}
+	}
+
+	if (!installSpec.includes("@")) {
+		return { error: USAGE };
+	}
+
+	return { force, scope, installSpec };
+}
+
+// ── Shared scope+id parser for uninstall / upgrade / enable / disable ───────
+
+export interface PluginScopeArgs {
+	pluginId: string;
+	scope?: "user" | "project";
+}
+
+/**
+ * Parse `[--scope user|project] <name@marketplace>` for commands that accept a
+ * single plugin ID and an optional scope flag.
+ *
+ * Returns parsed args or `{ error }` ready for `ctx.showStatus`.
+ */
+export function parsePluginScopeArgs(rest: string, usageHint: string): PluginScopeArgs | { error: string } {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let scope: "user" | "project" | undefined;
+	let pluginId = "";
+
+	for (let i = 0; i < tokens.length; i++) {
+		if (tokens[i] === "--scope" && i + 1 < tokens.length && !tokens[i + 1].startsWith("-")) {
+			const s = tokens[++i];
+			if (s === "user" || s === "project") {
+				scope = s;
+			} else {
+				return { error: `Invalid --scope value: "${s}". Must be "user" or "project".` };
+			}
+		} else if (tokens[i] === "--scope") {
+			return { error: '--scope requires a value: "user" or "project".' };
+		} else if (tokens[i].startsWith("-")) {
+			return { error: `Unknown flag: "${tokens[i]}". ${usageHint}` };
+		} else if (pluginId) {
+			return { error: `Unexpected argument: "${tokens[i]}". ${usageHint}` };
+		} else {
+			pluginId = tokens[i];
+		}
+	}
+
+	if (!pluginId) {
+		return { error: usageHint };
+	}
+
+	return { pluginId, scope };
+}