magus-cli 0.0.0-placeholder → 7.0.0

package/src/ui/state/types.ts

@@ -0,0 +1,503 @@
+import type { CatalogModel } from "../../services/mate-catalog.js";
+import type { ModelsConfig, ModelsStatus } from "../../services/models-core.js";
+import type { PluginInfo } from "../../services/plugin-manager.js";
+import type {
+	PluginComponent,
+	PluginSkillDetail,
+} from "../../services/skills-manager.js";
+import type { StylesSnapshot } from "../../services/styles-manager.js";
+import type {
+	Marketplace,
+	McpServer,
+	ProfileEntry,
+	SkillInfo,
+} from "../../types/index.js";
+
+// ============================================================================
+// Route Types
+// ============================================================================
+
+export type Screen =
+	| "plugins"
+	| "mcp"
+	| "mcp-registry"
+	| "settings"
+	| "cli-tools"
+	| "profiles"
+	| "skills"
+	| "styles"
+	| "gitignore"
+	| "alias"
+	| "models";
+
+export type Route =
+	| { screen: "plugins" }
+	| { screen: "mcp" }
+	| { screen: "mcp-registry"; query?: string }
+	| { screen: "settings" }
+	| { screen: "cli-tools" }
+	| { screen: "profiles" }
+	| { screen: "skills" }
+	| { screen: "styles" }
+	| { screen: "gitignore" }
+	| { screen: "alias" }
+	| { screen: "models" };
+
+// ============================================================================
+// Async Data Types
+// ============================================================================
+
+export type AsyncData<T> =
+	| { status: "idle" }
+	/**
+	 * `previous` carries the last successful value through a reload.
+	 *
+	 * Without it a refetch is indistinguishable from a first load, so a screen
+	 * that already had data blanked itself to "Loading..." every time it
+	 * remounted — and the router unmounts screens on every tab switch. Optional so
+	 * that a genuine first load is still just `{ status: "loading" }`.
+	 */
+	| { status: "loading"; previous?: T }
+	| { status: "success"; data: T }
+	| { status: "error"; error: Error };
+
+/** The value to render: fresh if loaded, else the last good one during a reload. */
+export function asyncValue<T>(d: AsyncData<T>): T | undefined {
+	if (d.status === "success") return d.data;
+	if (d.status === "loading") return d.previous;
+	return undefined;
+}
+
+// ============================================================================
+// Modal Types
+// ============================================================================
+
+export interface SelectOption {
+	label: string;
+	value: string;
+	description?: string;
+}
+
+export type ModalState =
+	| {
+			type: "confirm";
+			title: string;
+			message: string;
+			onConfirm: () => void;
+			onCancel: () => void;
+	  }
+	| {
+			type: "input";
+			title: string;
+			label: string;
+			defaultValue?: string;
+			onSubmit: (value: string) => void;
+			onCancel: () => void;
+	  }
+	| {
+			type: "select";
+			title: string;
+			message: string;
+			options: SelectOption[];
+			defaultIndex?: number;
+			onSelect: (value: string) => void;
+			onCancel: () => void;
+	  }
+	| {
+			type: "message";
+			title: string;
+			message: string;
+			variant: "info" | "success" | "error";
+			onDismiss: () => void;
+	  }
+	| {
+			type: "loading";
+			message: string;
+	  };
+
+// ============================================================================
+// Progress Types
+// ============================================================================
+
+export interface ProgressState {
+	message: string;
+	current?: number;
+	total?: number;
+}
+
+// ============================================================================
+// Screen State Types
+// ============================================================================
+
+/** Read-only listing of what one plugin ships, fetched on demand. */
+export interface PluginContentsEntry {
+	status: "loading" | "success" | "error";
+	components?: PluginComponent[];
+	error?: string;
+}
+
+/** One skill's SKILL.md, fetched when the cursor settles on its row. */
+export interface PluginSkillDetailEntry {
+	status: "loading" | "success" | "error";
+	detail?: PluginSkillDetail;
+	error?: string;
+}
+
+export interface PluginsScreenState {
+	scope: "project" | "global";
+	collapsedMarketplaces: Set<string>;
+	/**
+	 * Plugin ids whose contents list is open. Opposite default to
+	 * `collapsedMarketplaces`: listing a plugin's contents costs an HTTP call,
+	 * so it stays shut until asked for.
+	 */
+	expandedPlugins: Set<string>;
+	pluginContents: Map<string, PluginContentsEntry>;
+	/** SKILL.md content, keyed `<repo>/<repoPath>`. */
+	skillDetails: Map<string, PluginSkillDetailEntry>;
+	selectedIndex: number;
+	searchQuery: string;
+	marketplaces: AsyncData<Marketplace[]>;
+	plugins: AsyncData<PluginInfo[]>;
+}
+
+export interface McpScreenState {
+	selectedIndex: number;
+	servers: AsyncData<McpServer[]>;
+	installedServers: Record<string, boolean>;
+}
+
+export interface McpRegistryScreenState {
+	searchQuery: string;
+	selectedIndex: number;
+	servers: AsyncData<McpServer[]>;
+}
+
+export interface ScopedSettingValues {
+	user: string | undefined;
+	project: string | undefined;
+}
+
+export interface SettingsScreenState {
+	selectedIndex: number;
+	values: AsyncData<Map<string, ScopedSettingValues>>;
+}
+
+export interface CliTool {
+	name: string;
+	displayName: string;
+	description: string;
+	installCommand: string;
+	checkCommand: string;
+	homebrewFormula?: string;
+	npmPackage?: string;
+	installedVersion?: string;
+	latestVersion?: string;
+	hasUpdate?: boolean;
+	isInstalled: boolean;
+	isChecking: boolean;
+}
+
+export interface CliToolsScreenState {
+	selectedIndex: number;
+	tools: AsyncData<CliTool[]>;
+}
+
+export interface ProfilesScreenState {
+	selectedIndex: number;
+	profiles: AsyncData<ProfileEntry[]>;
+}
+
+export interface SkillsScreenState {
+	scope: "user" | "project";
+	selectedIndex: number;
+	searchQuery: string;
+	/** Available skills from Tree API, cross-referenced with lock files */
+	skills: AsyncData<SkillInfo[]>;
+	/** Null until check completes; then Map<skillName, hasUpdate> */
+	updateStatus: Map<string, boolean> | null;
+}
+
+export interface StylesScreenState {
+	selectedIndex: number;
+	searchQuery: string;
+	/** Presets + importable styles + what is currently live, in one read. */
+	snapshot: AsyncData<StylesSnapshot>;
+	/**
+	 * Pending selection, by source id. Staged rather than applied on each
+	 * keystroke: composing writes a file and flips the harness's active output
+	 * style, which is not something a stray Space press should do.
+	 */
+	selected: Set<string>;
+	/**
+	 * The status line's current message, or null for the default line.
+	 *
+	 * App state for the same reason `isFilling` is: `Router` swaps the component
+	 * type on a tab change, so anything held in the screen's own `useState` is
+	 * destroyed by `9 → 1 → 9`. It also stops being cleared on a wall clock —
+	 * the message now survives until the next action replaces it, so the last
+	 * thing you did is still on screen whenever you look.
+	 */
+	status: { text: string; tone: "success" | "error" } | null;
+	/**
+	 * True while a template fill (Claude Code over the whole project) is running.
+	 *
+	 * App state, not screen state, because the screen UNMOUNTS when you switch
+	 * tabs. A fill runs for minutes, so switching away is the normal thing to do
+	 * — and with the flag held locally the returning user saw no sign one was in
+	 * flight and could launch a second subprocess on top of the first.
+	 */
+	isFilling: boolean;
+}
+
+/**
+ * What the Models screen reads in one go.
+ *
+ * Both halves are needed and neither implies the other: `status` says whether
+ * the routing is in force, and `config` is the routing itself — which the
+ * screen needs in full to give a hand-edited config a row of its own.
+ */
+export interface ModelsSnapshot {
+	status: ModelsStatus;
+	/** The validated config, or null when there is none (or it failed validation). */
+	config: ModelsConfig | null;
+	/** Where `.claude/models.json` is, whether or not it exists. */
+	path: string;
+}
+
+export interface ModelsScreenState {
+	selectedIndex: number;
+	searchQuery: string;
+	/** Routing status + the config behind it, in one read. */
+	data: AsyncData<ModelsSnapshot>;
+	/**
+	 * The status line's current message, or null for the default line.
+	 *
+	 * App state for the same reason the Styles screen's is: `Router` swaps the
+	 * component type on a tab change, so anything held in the screen's own
+	 * `useState` is destroyed by `0 → 1 → 0`. The message survives until the next
+	 * action replaces it, so the last thing you did is still on screen.
+	 */
+	status: { text: string; tone: "success" | "error" } | null;
+	/**
+	 * True while an apply or a clear is writing.
+	 *
+	 * App state, not screen state, because the screen UNMOUNTS on a tab switch.
+	 * An apply rewrites the profile, re-materializes it and registers a hook —
+	 * two of those running at once would interleave writes to the same files.
+	 */
+	isApplying: boolean;
+	/**
+	 * Is `multimodel@magus` installed — i.e. is there anything to serve a mate?
+	 *
+	 * App state for the reason the two fields above are, plus one of its own. The screen
+	 * unmounts on a tab switch, so a local flag would be destroyed by `0 → 1 → 0`; and unlike
+	 * the two file reads the screen does on mount, THIS answer costs a marketplace resolution
+	 * with network timeouts behind it. Re-asking it on every visit to the tab would pay that
+	 * cost again for an answer that cannot change while the TUI is open.
+	 *
+	 * Starts false, which is also what a failed lookup yields (`areMatesAvailable` fails
+	 * closed): both render as the screen exactly as it was before mates existed, rather than
+	 * as three rows put there by an error.
+	 */
+	matesAvailable: boolean;
+	/**
+	 * claudish's live model catalogue, or [] when it could not be read.
+	 *
+	 * App state for the reasons above, plus the one that matters most here: reading it spawns
+	 * a process. Held per session, it is spawned once; held in the component it would be
+	 * spawned on every visit to the tab.
+	 *
+	 * [] is deliberately NOT distinguished from "not yet loaded". Every consumer treats an
+	 * empty catalogue as "unknown" and says nothing, so the loading frame, a machine without
+	 * claudish, and a lookup that timed out all draw the same screen — bound ids as written,
+	 * with no annotation. Advisory only: nothing here ever changes what is routed.
+	 */
+	mateCatalog: CatalogModel[];
+}
+
+// ============================================================================
+// App State
+// ============================================================================
+
+export interface AppState {
+	// Navigation
+	currentRoute: Route;
+
+	// Project context
+	projectPath: string;
+
+	// Global UI state
+	modal: ModalState | null;
+	progress: ProgressState | null;
+	isSearching: boolean;
+	// True while a screen has a focused sub-view open that owns Escape (e.g.
+	// the Alias tab's flag-detail editor). The global key handler skips its
+	// Escape→navigate branch so Escape backs out of the sub-view instead of
+	// jumping to the home tab. Mirrors how `modal`/`isSearching` gate keys.
+	detailActive: boolean;
+
+	// Refresh counter - incremented when marketplace sync completes
+	// Screens can watch this to know when to refetch data
+	dataRefreshVersion: number;
+
+	// Screen-specific state
+	plugins: PluginsScreenState;
+	mcp: McpScreenState;
+	mcpRegistry: McpRegistryScreenState;
+	settings: SettingsScreenState;
+	cliTools: CliToolsScreenState;
+	profiles: ProfilesScreenState;
+	skills: SkillsScreenState;
+	styles: StylesScreenState;
+	models: ModelsScreenState;
+}
+
+// ============================================================================
+// Action Types
+// ============================================================================
+
+export type AppAction =
+	// Navigation
+	| { type: "NAVIGATE"; route: Route }
+
+	// Plugins screen
+	| { type: "PLUGINS_SET_SCOPE"; scope: "project" | "global" }
+	| { type: "PLUGINS_TOGGLE_SCOPE" }
+	| { type: "PLUGINS_TOGGLE_MARKETPLACE"; name: string }
+	| { type: "PLUGINS_TOGGLE_PLUGIN_CONTENTS"; pluginId: string }
+	| { type: "PLUGINS_CONTENTS_LOADING"; pluginId: string }
+	| {
+			type: "PLUGINS_CONTENTS_SUCCESS";
+			pluginId: string;
+			components: PluginComponent[];
+	  }
+	| { type: "PLUGINS_CONTENTS_ERROR"; pluginId: string; error: string }
+	| { type: "PLUGINS_SKILL_DETAIL_LOADING"; key: string }
+	| {
+			type: "PLUGINS_SKILL_DETAIL_SUCCESS";
+			key: string;
+			detail: PluginSkillDetail;
+	  }
+	| { type: "PLUGINS_SKILL_DETAIL_ERROR"; key: string; error: string }
+	| { type: "PLUGINS_SELECT"; index: number }
+	| { type: "PLUGINS_SET_SEARCH"; query: string }
+	| { type: "PLUGINS_DATA_LOADING" }
+	| {
+			type: "PLUGINS_DATA_SUCCESS";
+			marketplaces: Marketplace[];
+			plugins: PluginInfo[];
+	  }
+	| { type: "PLUGINS_DATA_ERROR"; error: Error }
+
+	// MCP screen
+	| { type: "MCP_SELECT"; index: number }
+	| { type: "MCP_DATA_LOADING" }
+	| {
+			type: "MCP_DATA_SUCCESS";
+			servers: McpServer[];
+			installedServers: Record<string, boolean>;
+	  }
+	| { type: "MCP_DATA_ERROR"; error: Error }
+
+	// MCP Registry screen
+	| { type: "MCP_REGISTRY_SET_QUERY"; query: string }
+	| { type: "MCPREGISTRY_SEARCH"; query: string } // Alias for MCP_REGISTRY_SET_QUERY
+	| { type: "MCPREGISTRY_SELECT"; index: number } // Alias for MCP_REGISTRY_SELECT
+	| { type: "MCP_REGISTRY_SELECT"; index: number }
+	| { type: "MCP_REGISTRY_DATA_LOADING" }
+	| { type: "MCP_REGISTRY_DATA_SUCCESS"; servers: McpServer[] }
+	| { type: "MCP_REGISTRY_DATA_ERROR"; error: Error }
+
+	// Settings screen
+	| { type: "SETTINGS_SELECT"; index: number }
+	| { type: "SETTINGS_DATA_LOADING" }
+	| { type: "SETTINGS_DATA_SUCCESS"; values: Map<string, ScopedSettingValues> }
+	| { type: "SETTINGS_DATA_ERROR"; error: Error }
+
+	// CLI tools screen
+	| { type: "CLITOOLS_SELECT"; index: number }
+	| { type: "CLITOOLS_DATA_LOADING" }
+	| { type: "CLITOOLS_DATA_SUCCESS"; tools: CliTool[] }
+	| { type: "CLITOOLS_DATA_ERROR"; error: Error }
+	| { type: "CLITOOLS_UPDATE_TOOL"; name: string; updates: Partial<CliTool> }
+
+	// Modals
+	| { type: "SHOW_MODAL"; modal: ModalState }
+	| { type: "HIDE_MODAL" }
+
+	// Progress
+	| { type: "SHOW_PROGRESS"; state: ProgressState }
+	| { type: "UPDATE_PROGRESS"; state: ProgressState }
+	| { type: "HIDE_PROGRESS" }
+
+	// Search state (blocks global key handlers)
+	| { type: "SET_SEARCHING"; isSearching: boolean }
+
+	// Detail sub-view state (gates global Escape→navigate)
+	| { type: "SET_DETAIL_ACTIVE"; detailActive: boolean }
+
+	// Profiles screen
+	| { type: "PROFILES_SELECT"; index: number }
+	| { type: "PROFILES_DATA_LOADING" }
+	| { type: "PROFILES_DATA_SUCCESS"; profiles: ProfileEntry[] }
+	| { type: "PROFILES_DATA_ERROR"; error: Error }
+
+	// Skills screen
+	| { type: "SKILLS_SET_SCOPE"; scope: "user" | "project" }
+	| { type: "SKILLS_TOGGLE_SCOPE" }
+	| { type: "SKILLS_SELECT"; index: number }
+	| { type: "SKILLS_SET_SEARCH"; query: string }
+	| { type: "SKILLS_DATA_LOADING" }
+	| { type: "SKILLS_DATA_SUCCESS"; skills: SkillInfo[] }
+	| { type: "SKILLS_DATA_ERROR"; error: Error }
+	| { type: "SKILLS_UPDATE_STATUS"; updates: Map<string, boolean> }
+	| { type: "SKILLS_UPDATE_ITEM"; name: string; updates: Partial<SkillInfo> }
+
+	// Styles screen
+	| { type: "STYLES_SELECT"; index: number }
+	| { type: "STYLES_SET_SEARCH"; query: string }
+	// Append/backspace are computed IN the reducer, from current state. A
+	// screen-side `searchQuery + char` reads a value captured at render time, so
+	// keystrokes arriving faster than React re-renders all overwrite each other
+	// and typing "slop" leaves just "p".
+	| { type: "STYLES_SEARCH_APPEND"; char: string }
+	| { type: "STYLES_SEARCH_BACKSPACE" }
+	| { type: "STYLES_DATA_LOADING" }
+	| { type: "STYLES_DATA_SUCCESS"; snapshot: StylesSnapshot }
+	| { type: "STYLES_DATA_ERROR"; error: Error }
+	| { type: "STYLES_TOGGLE"; id: string }
+	| {
+			type: "STYLES_STATUS_SET";
+			status: { text: string; tone: "success" | "error" };
+	  }
+	| { type: "STYLES_STATUS_CLEAR" }
+	| { type: "STYLES_FILL_START" }
+	| { type: "STYLES_FILL_END" }
+	| { type: "STYLES_SET_SELECTION"; ids: string[] }
+
+	// Models screen
+	| { type: "MODELS_SELECT"; index: number }
+	| { type: "MODELS_SET_SEARCH"; query: string }
+	// Computed IN the reducer, from current state, for the same reason the
+	// STYLES_SEARCH_* pair is: a screen-side `searchQuery + char` reads a value
+	// captured at render time, so keystrokes arriving faster than React
+	// re-renders all overwrite each other.
+	| { type: "MODELS_SEARCH_APPEND"; char: string }
+	| { type: "MODELS_SEARCH_BACKSPACE" }
+	| { type: "MODELS_DATA_LOADING" }
+	| { type: "MODELS_DATA_SUCCESS"; snapshot: ModelsSnapshot }
+	| { type: "MODELS_DATA_ERROR"; error: Error }
+	| {
+			type: "MODELS_STATUS_SET";
+			status: { text: string; tone: "success" | "error" };
+	  }
+	| { type: "MODELS_STATUS_CLEAR" }
+	| { type: "MODELS_APPLY_START" }
+	| { type: "MODELS_APPLY_END" }
+	// Dispatched once, when the plugin lookup behind the mate slots lands.
+	| { type: "MODELS_MATES_AVAILABLE"; available: boolean }
+	| { type: "MODELS_CATALOG_LOADED"; catalog: CatalogModel[] }
+
+	// Data refresh - triggers screens to refetch
+	| { type: "DATA_REFRESH_COMPLETE" };