magus-cli 0.0.0-placeholder → 7.1.0

package/src/types/index.ts

@@ -0,0 +1,447 @@
+import type { ModelsConfig } from "../services/models-core.js";
+
+export interface McpServer {
+	name: string;
+	description: string;
+	// Command-based MCP server
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	// HTTP-based MCP server
+	type?: "http";
+	url?: string;
+	// Common fields
+	category:
+		| "browser"
+		| "ai"
+		| "design"
+		| "dev-tools"
+		| "cloud"
+		| "database"
+		| "productivity"
+		| "seo";
+	requiresConfig?: boolean;
+	configFields?: ConfigField[];
+}
+
+export interface ConfigField {
+	name: string;
+	label: string;
+	type: "string" | "path" | "url" | "boolean";
+	required: boolean;
+	default?: string;
+	envVar?: string;
+}
+
+export interface Marketplace {
+	name: string;
+	displayName: string;
+	source: {
+		source: "github";
+		repo: string;
+	};
+	description: string;
+	official?: boolean;
+	featured?: boolean; // Featured marketplaces have plugins fetched by default (like official)
+	deprecated?: boolean; // Deprecated marketplaces are sorted to the bottom of the list
+	owned?: boolean; // Our own marketplaces (magus*): always listed even when uninstalled, and sorted to the top
+}
+
+export interface DiscoveredMarketplace {
+	name: string;
+	source: "default" | "configured" | "inferred";
+	config?: MarketplaceSource;
+}
+
+/**
+ * One entry of a plugin's recent release history, as published in marketplace.json.
+ *
+ * Kept separate from `description` on purpose: `description` says what a plugin *is*
+ * and changes rarely, while this says what *changed* and turns over every release.
+ * Folding the second into the first is what left plugin panels showing a changelog
+ * line where the plugin's purpose should be.
+ */
+export interface PluginRelease {
+	version: string;
+	/** ISO date (YYYY-MM-DD). Absent on entries whose heading carried no date. */
+	date?: string;
+	/** Change categories in the entry — "Added", "Changed", "Fixed", … */
+	kinds?: string[];
+	summary: string;
+}
+
+export interface Plugin {
+	name: string;
+	version: string;
+	description: string;
+	marketplace: string;
+	installed: boolean;
+	availableVersion?: string;
+	hasUpdate?: boolean;
+}
+
+export interface MarketplaceSource {
+	source: {
+		source: "github";
+		repo: string;
+	};
+	autoUpdate?: boolean; // Enable auto-update for this marketplace (default: true for new marketplaces)
+}
+
+export interface ClaudeHookEntry {
+	type: string;
+	command: string;
+}
+
+export interface ClaudeHookGroup {
+	hooks: ClaudeHookEntry[];
+}
+
+export interface ClaudeSettings {
+	enabledMcpServers?: Record<string, boolean>;
+	mcpServers?: Record<string, McpServerConfig>;
+	enabledPlugins?: Record<string, boolean>;
+	extraKnownMarketplaces?: Record<string, MarketplaceSource>;
+	installedPluginVersions?: Record<string, string>;
+	statusLine?: string | { type: string; template?: string; command?: string };
+	hooks?: Record<string, ClaudeHookGroup[]>;
+}
+
+export interface McpServerConfig {
+	// Command-based
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	// HTTP-based
+	type?: "http";
+	url?: string;
+}
+
+export interface ClaudeLocalSettings extends ClaudeSettings {
+	allowMcp?: boolean;
+	enabledMcpjsonServers?: string[];
+	enableAllProjectMcpServers?: boolean;
+	env?: Record<string, string>;
+}
+
+export type Screen =
+	| "main"
+	| "mcp"
+	| "mcp-registry"
+	| "plugins"
+	| "statusline"
+	| "cli-tools"
+	| "env-vars"
+	| "skills";
+
+// ─── Skill Types ──────────────────────────────────────────────────────────────
+
+/** A configured skill repository (entry in skill-repos.ts) */
+export interface SkillSource {
+	/** Human-readable label, e.g. "vercel-labs/agent-skills" */
+	label: string;
+	/** GitHub owner/repo, e.g. "vercel-labs/agent-skills" */
+	repo: string;
+	/** Sub-path within the repo where skills live, e.g. "skills" */
+	skillsPath: string;
+}
+
+/** YAML frontmatter extracted from a SKILL.md file */
+export interface SkillFrontmatter {
+	name: string;
+	description: string;
+	category?: string;
+	author?: string;
+	version?: string;
+	tags?: string[];
+	[key: string]: unknown;
+}
+
+/** A skill entry from the available-skills list (may or may not be installed) */
+export interface SkillInfo {
+	/** Unique key: "{owner}/{repo}/{path}" */
+	id: string;
+	/** Slug used as directory name: last segment of path */
+	name: string;
+	/** Source repo this skill comes from */
+	source: SkillSource;
+	/** Relative path within repo, e.g. "skills/researcher/SKILL.md" */
+	repoPath: string;
+	/** Git blob SHA from Tree API response */
+	gitBlobSha: string;
+	/** Parsed frontmatter (null if not yet fetched) */
+	frontmatter: SkillFrontmatter | null;
+	/** Whether the skill is installed (either scope) */
+	installed: boolean;
+	/** Scope of the installed copy */
+	installedScope: "user" | "project" | null;
+	/** True when lock file SHA differs from Tree API SHA */
+	hasUpdate: boolean;
+	/** Whether this is a recommended skill */
+	isRecommended?: boolean;
+	/** GitHub star count from the skills API */
+	stars?: number;
+	/** Short description (from API, before frontmatter is loaded) */
+	description?: string;
+	/** How reliable the star count is as a quality signal for this skill */
+	starReliability?: "dedicated" | "mega-repo" | "skill-dump";
+}
+
+/** How reliable the star count is as a quality signal for this skill */
+export type StarReliability = "dedicated" | "mega-repo" | "skill-dump";
+
+/** A skill set — a group of skills from a single repo */
+export interface SkillSetInfo {
+	/** Unique key, e.g. "huggingface/skills" */
+	id: string;
+	/** Display name, e.g. "Hugging Face" */
+	name: string;
+	/** Repo description */
+	description: string;
+	/** GitHub owner/repo */
+	repo: string;
+	/** Icon/emoji for display */
+	icon: string;
+	/** GitHub star count */
+	stars?: number;
+	/** Individual skills within this set (fetched lazily via Tree API) */
+	skills: SkillInfo[];
+	/** Whether skills have been fetched yet */
+	loaded: boolean;
+	/** Loading state */
+	loading: boolean;
+	/** Error if fetch failed */
+	error?: string;
+}
+
+// ─── GitHub Tree API types ────────────────────────────────────────────────────
+
+export interface GitTreeItem {
+	path: string;
+	mode: string;
+	type: "blob" | "tree";
+	sha: string;
+	size?: number;
+	url: string;
+}
+
+export interface GitTreeResponse {
+	sha: string;
+	url: string;
+	tree: GitTreeItem[];
+	truncated: boolean;
+}
+
+// MCP Registry Types (registry.modelcontextprotocol.io)
+export interface McpRegistryServer {
+	name: string;
+	url: string;
+	short_description: string;
+	version?: string;
+	source_code_url?: string;
+	package_registry?: string;
+	published_at?: string;
+}
+
+export interface McpRegistryResponse {
+	servers: McpRegistryServer[];
+	next_cursor?: string;
+}
+
+// installed_plugins.json registry types
+export interface InstalledPluginEntry {
+	scope: "user" | "project" | "local";
+	projectPath?: string;
+	installPath: string;
+	version: string;
+	installedAt: string;
+	lastUpdated: string;
+	gitCommitSha?: string;
+}
+
+export interface InstalledPluginsRegistry {
+	version: number;
+	plugins: Record<string, InstalledPluginEntry[]>;
+}
+
+// ─── Plugin Conventions (declarative project hygiene) ───────────────────────────
+
+/** Convention declarations for a plugin */
+export interface PluginConventions {
+	gitignore?: GitignoreConventions;
+	claudemd?: ClaudeMdConventions;
+}
+
+/** Gitignore entries a plugin needs */
+export interface GitignoreConventions {
+	/** Entries for project .gitignore (team-visible, committed) */
+	project?: string[];
+	/** Advisory entries for global gitignore (personal, not committed).
+	 *  Resolved via `git config --global core.excludesfile`,
+	 *  falling back to ~/.config/git/ignore if unset. */
+	global?: string[];
+}
+
+/** CLAUDE.md section injection config */
+export interface ClaudeMdConventions {
+	/** Section identifier used in markers: <!-- BEGIN magus:{section} -->
+	 *  MUST equal the plugin's `name` field. */
+	section: string;
+	/** Path to markdown template, relative to plugin root */
+	template: string;
+	/** Semantic version of the template content */
+	version: string;
+}
+
+// ─── Plugin Profile Types ──────────────────────────────────────────────────────
+
+export interface Profile {
+	name: string;
+	plugins: Record<string, boolean>;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface ProfilesFile {
+	version: number;
+	profiles: Record<string, Profile>;
+}
+
+/** A profile with its id and scope, as used in UI lists */
+export interface ProfileEntry {
+	id: string;
+	name: string;
+	plugins: Record<string, boolean>;
+	createdAt: string;
+	updatedAt: string;
+	scope: "user" | "project";
+}
+
+// NOTE: The built-in profile type lives with its data in
+// data/predefined-profiles.ts (that file declares and exports its own
+// PredefinedProfile). A second, unused definition previously lived here and
+// has been removed to avoid two competing shapes.
+
+// ─── Team Profile Manifest (v2, committed .claude/profiles.json) ────────────────
+//
+// The v1 `Profile`/`ProfilesFile` above are the TUI's saved presets (plugins
+// only). The v2 manifest below is the committed, team-shared source of truth:
+// a superset that also carries marketplaces, MCP servers, CLI tools, skills,
+// settings, and env requirements. A v1 profile is a structural subset of a v2
+// entry, so v1 files migrate forward by a version bump alone.
+
+/** A marketplace a profile depends on (registered before its plugins install). */
+export interface ProfileMarketplaceRef {
+	source: "github" | "directory";
+	/** owner/repo — for source: "github" */
+	repo?: string;
+	/** absolute or repo-relative path — for source: "directory" */
+	path?: string;
+}
+
+/** A skill a profile installs (resolved from a GitHub repo + path). */
+export interface ProfileSkillRef {
+	name: string;
+	repo: string;
+	path: string;
+}
+
+/** Environment variables a profile declares (values live in settings.local.json). */
+export interface ProfileEnvRequirements {
+	required?: string[];
+	optional?: string[];
+}
+
+/**
+ * A single team profile in .claude/profiles.json (v2).
+ * `plugins` maps a plugin id to a version pin ("1.2.0"), "latest", or `true`
+ * (equivalent to "latest" — the shape v1 saved profiles use).
+ */
+export interface ProfileManifestEntry {
+	name: string;
+	/** Optional predefined-profile id to inherit plugins/skills/settings from. */
+	extends?: string;
+	marketplaces?: Record<string, ProfileMarketplaceRef>;
+	plugins?: Record<string, string | boolean>;
+	mcpServers?: Record<string, McpServerConfig>;
+	/** cliTool name -> version pin | "latest". */
+	cliTools?: Record<string, string>;
+	skills?: ProfileSkillRef[];
+	settings?: Record<string, unknown>;
+	/**
+	 * Per-subagent model routing. A PROFILE property, so switching profiles
+	 * switches routing, and materialization writes it to
+	 * `_profiles/<name>/models.json` for `.claude/models.json` to link at.
+	 */
+	models?: ModelsConfig;
+	env?: ProfileEnvRequirements;
+	/** Optional bookkeeping carried over from v1 saved profiles. */
+	createdAt?: string;
+	updatedAt?: string;
+}
+
+/** The .claude/profiles.json manifest (v2). */
+export interface ProfileManifest {
+	version: 2;
+	/** When true, `install --check` fails on any plugin version drift. */
+	strictVersions?: boolean;
+	profiles: Record<string, ProfileManifestEntry>;
+}
+
+// ─── Plugin binary requirements (plugin.json `requires.bin`) ────────────────────
+
+/** How a binary dependency is installed. */
+export type BinInstaller = "bun" | "brew" | "npm" | "pip" | "go";
+
+/** A single binary dependency a plugin (or profile) declares. */
+export interface BinRequirement {
+	/** The executable name expected on PATH (also the dedup key). */
+	name: string;
+	via: BinInstaller;
+	/** Package id for bun/npm/pip (defaults to `name`). */
+	package?: string;
+	/** Formula for brew (defaults to `name`). */
+	formula?: string;
+	/** Module path for `go install` (defaults to `name`). */
+	module?: string;
+	/** Command that verifies presence, e.g. "tmux -V" (defaults to `<name> --version`). */
+	check?: string;
+	/** Optional version pin (real for bun/npm/pip; advisory for brew/go). */
+	version?: string;
+}
+
+/** The `requires` block a plugin may declare in its plugin.json. */
+export interface PluginRequires {
+	bin?: BinRequirement[];
+}
+
+// ─── Resolved install closure (resolver output) ─────────────────────────────────
+
+/** A binary requirement after dedup + pin precedence, with provenance. */
+export interface ResolvedBin extends BinRequirement {
+	/** Where this requirement came from, for diagnostics. */
+	sources: string[];
+}
+
+/**
+ * The fully-resolved set of things to install for a profile (or the union of
+ * all profiles). Produced by the resolver; consumed by `magus install`.
+ */
+export interface ResolvedClosure {
+	marketplaces: Record<string, ProfileMarketplaceRef>;
+	/** pluginId -> version pin | "latest". */
+	plugins: Record<string, string>;
+	mcpServers: Record<string, McpServerConfig>;
+	bins: ResolvedBin[];
+	skills: ProfileSkillRef[];
+	settings: Record<string, unknown>;
+	/**
+	 * The profile's model routing, if it declares any. Absent means the
+	 * materialized profile carries no models.json — and materialization DELETES
+	 * a stale one, which is what makes `magus models off` take effect.
+	 */
+	models?: ModelsConfig;
+	env: { required: string[]; optional: string[] };
+	/** Cross-profile version conflicts detected while unioning profiles. */
+	conflicts?: string[];
+}