@oh-my-pi/pi-coding-agent 11.2.3 → 11.3.0

package/src/extensibility/extensions/runner.ts

@@ -32,6 +32,8 @@ import type {
 	MessageRenderer,
 	RegisteredCommand,
 	RegisteredTool,
+	ResourcesDiscoverEvent,
+	ResourcesDiscoverResult,
 	SessionBeforeCompactResult,
 	SessionBeforeTreeResult,
 	SessionCompactingResult,
@@ -64,6 +66,8 @@ export type NavigateTreeHandler = (
 	options?: { summarize?: boolean },
 ) => Promise<{ cancelled: boolean }>;
 
+export type SwitchSessionHandler = (sessionPath: string) => Promise<{ cancelled: boolean }>;
+
 export type ShutdownHandler = () => void;
 
 /**
@@ -102,6 +106,8 @@ const noOpUIContext: ExtensionUIContext = {
 	getAllThemes: () => Promise.resolve([]),
 	getTheme: () => Promise.resolve(undefined),
 	setTheme: (_theme: string | Theme) => Promise.resolve({ success: false, error: "UI not available" }),
+	getToolsExpanded: () => false,
+	setToolsExpanded: () => {},
 };
 
 export class ExtensionRunner {
@@ -114,10 +120,13 @@ export class ExtensionRunner {
 	private hasPendingMessagesFn: () => boolean = () => false;
 	private getContextUsageFn: () => ContextUsage | undefined = () => undefined;
 	private compactFn: (instructionsOrOptions?: string | CompactOptions) => Promise<void> = async () => {};
+	private getSystemPromptFn: () => string = () => "";
 	private newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
 	private branchHandler: BranchHandler = async () => ({ cancelled: false });
 	private navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
+	private switchSessionHandler: SwitchSessionHandler = async () => ({ cancelled: false });
 	private shutdownHandler: ShutdownHandler = () => {};
+	private commandDiagnostics: Array<{ type: string; message: string; path: string }> = [];
 
 	constructor(
 		private readonly extensions: Extension[],
@@ -142,6 +151,7 @@ export class ExtensionRunner {
 		this.runtime.getActiveTools = actions.getActiveTools;
 		this.runtime.getAllTools = actions.getAllTools;
 		this.runtime.setActiveTools = actions.setActiveTools;
+		this.runtime.getCommands = actions.getCommands;
 		this.runtime.setModel = actions.setModel;
 		this.runtime.getThinkingLevel = actions.getThinkingLevel;
 		this.runtime.setThinkingLevel = actions.setThinkingLevel;
@@ -152,6 +162,7 @@ export class ExtensionRunner {
 		this.abortFn = contextActions.abort;
 		this.hasPendingMessagesFn = contextActions.hasPendingMessages;
 		this.shutdownHandler = contextActions.shutdown;
+		this.getSystemPromptFn = contextActions.getSystemPrompt;
 
 		// Command context actions (optional, only for interactive mode)
 		if (commandContextActions) {
@@ -159,6 +170,7 @@ export class ExtensionRunner {
 			this.newSessionHandler = commandContextActions.newSession;
 			this.branchHandler = commandContextActions.branch;
 			this.navigateTreeHandler = commandContextActions.navigateTree;
+			this.switchSessionHandler = commandContextActions.switchSession;
 			this.getContextUsageFn = commandContextActions.getContextUsage;
 			this.compactFn = commandContextActions.compact;
 		}
@@ -279,16 +291,31 @@ export class ExtensionRunner {
 		return undefined;
 	}
 
-	getRegisteredCommands(): RegisteredCommand[] {
+	getRegisteredCommands(reserved?: Set<string>): RegisteredCommand[] {
+		this.commandDiagnostics = [];
+
 		const commands: RegisteredCommand[] = [];
 		for (const ext of this.extensions) {
 			for (const command of ext.commands.values()) {
+				if (reserved?.has(command.name)) {
+					const message = `Extension command '${command.name}' from ${ext.path} conflicts with built-in commands. Skipping.`;
+					this.commandDiagnostics.push({ type: "warning", message, path: ext.path });
+					if (!this.hasUI()) {
+						logger.warn(message);
+					}
+					continue;
+				}
+
 				commands.push(command);
 			}
 		}
 		return commands;
 	}
 
+	getCommandDiagnostics(): Array<{ type: string; message: string; path: string }> {
+		return this.commandDiagnostics;
+	}
+
 	getCommand(name: string): RegisteredCommand | undefined {
 		for (const ext of this.extensions) {
 			const command = ext.commands.get(name);
@@ -316,6 +343,7 @@ export class ExtensionRunner {
 			abort: () => this.abortFn(),
 			hasPendingMessages: () => this.hasPendingMessagesFn(),
 			shutdown: () => this.shutdownHandler(),
+			getSystemPrompt: () => this.getSystemPromptFn(),
 			hasQueuedMessages: () => this.hasPendingMessagesFn(), // deprecated alias
 		};
 	}
@@ -335,6 +363,7 @@ export class ExtensionRunner {
 			newSession: options => this.newSessionHandler(options),
 			branch: entryId => this.branchHandler(entryId),
 			navigateTree: (targetId, options) => this.navigateTreeHandler(targetId, options),
+			switchSession: sessionPath => this.switchSessionHandler(sessionPath),
 			compact: instructionsOrOptions => this.compactFn(instructionsOrOptions),
 		};
 	}
@@ -493,6 +522,54 @@ export class ExtensionRunner {
 		return undefined;
 	}
 
+	async emitResourcesDiscover(
+		cwd: string,
+		reason: ResourcesDiscoverEvent["reason"],
+	): Promise<{
+		skillPaths: Array<{ path: string; extensionPath: string }>;
+		promptPaths: Array<{ path: string; extensionPath: string }>;
+		themePaths: Array<{ path: string; extensionPath: string }>;
+	}> {
+		const ctx = this.createContext();
+		const skillPaths: Array<{ path: string; extensionPath: string }> = [];
+		const promptPaths: Array<{ path: string; extensionPath: string }> = [];
+		const themePaths: Array<{ path: string; extensionPath: string }> = [];
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("resources_discover");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const event: ResourcesDiscoverEvent = { type: "resources_discover", cwd, reason };
+					const handlerResult = await handler(event, ctx);
+					const result = handlerResult as ResourcesDiscoverResult | undefined;
+
+					if (result?.skillPaths?.length) {
+						skillPaths.push(...result.skillPaths.map(path => ({ path, extensionPath: ext.path })));
+					}
+					if (result?.promptPaths?.length) {
+						promptPaths.push(...result.promptPaths.map(path => ({ path, extensionPath: ext.path })));
+					}
+					if (result?.themePaths?.length) {
+						themePaths.push(...result.themePaths.map(path => ({ path, extensionPath: ext.path })));
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "resources_discover",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return { skillPaths, promptPaths, themePaths };
+	}
+
 	/** Emit input event. Transforms chain, "handled" short-circuits. */
 	async emitInput(
 		text: string,

package/src/extensibility/extensions/types.ts

@@ -28,8 +28,19 @@ import type {
 	SessionEntry,
 	SessionManager,
 } from "../../session/session-manager";
-import type { BashToolDetails, FindToolDetails, GrepToolDetails, ReadToolDetails } from "../../tools";
+import type {
+	BashToolDetails,
+	BashToolInput,
+	FindToolDetails,
+	FindToolInput,
+	GrepToolDetails,
+	GrepToolInput,
+	ReadToolDetails,
+	ReadToolInput,
+	WriteToolInput,
+} from "../../tools";
 import type { EventBus } from "../../utils/event-bus";
+import type { SlashCommandInfo } from "../slash-commands";
 
 export type { AppAction, KeybindingsManager } from "../../config/keybindings";
 export type { ExecOptions, ExecResult } from "../../exec/exec";
@@ -123,6 +134,12 @@ export interface ExtensionUIContext {
 
 	/** Set the current theme by name or Theme object. */
 	setTheme(theme: string | Theme): Promise<{ success: boolean; error?: string }>;
+
+	/** Get current tool output expansion state. */
+	getToolsExpanded(): boolean;
+
+	/** Set tool output expansion state. */
+	setToolsExpanded(expanded: boolean): void;
 }
 
 // ============================================================================
@@ -171,6 +188,8 @@ export interface ExtensionContext {
 	hasPendingMessages(): boolean;
 	/** Gracefully shutdown and exit. */
 	shutdown(): void;
+	/** Get the current effective system prompt. */
+	getSystemPrompt(): string;
 	/** @deprecated Use hasPendingMessages() instead */
 	hasQueuedMessages(): boolean;
 }
@@ -198,6 +217,9 @@ export interface ExtensionCommandContext extends ExtensionContext {
 	/** Navigate to a different point in the session tree. */
 	navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ cancelled: boolean }>;
 
+	/** Switch to a different session file. */
+	switchSession(sessionPath: string): Promise<{ cancelled: boolean }>;
+
 	/** Compact the session context (interactive mode shows UI). */
 	compact(instructionsOrOptions?: string | CompactOptions): Promise<void>;
 }
@@ -243,9 +265,9 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
 	execute(
 		toolCallId: string,
 		params: Static<TParams>,
+		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
 		ctx: ExtensionContext,
-		signal?: AbortSignal,
 	): Promise<AgentToolResult<TDetails>>;
 
 	/** Called on session lifecycle events - use to reconstruct state or cleanup resources */
@@ -263,6 +285,24 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
 	) => Component;
 }
 
+// ============================================================================
+// Resource Events
+// ============================================================================
+
+/** Fired after session_start to allow extensions to provide additional resource paths. */
+export interface ResourcesDiscoverEvent {
+	type: "resources_discover";
+	cwd: string;
+	reason: "startup" | "reload";
+}
+
+/** Result from resources_discover event handler */
+export interface ResourcesDiscoverResult {
+	skillPaths?: string[];
+	promptPaths?: string[];
+	themePaths?: string[];
+}
+
 // ============================================================================
 // Session Events
 // ============================================================================
@@ -454,14 +494,56 @@ export interface InputEvent {
 // Tool Events
 // ============================================================================
 
-/** Fired before a tool executes. Can block. */
-export interface ToolCallEvent {
+interface ToolCallEventBase {
 	type: "tool_call";
-	toolName: string;
 	toolCallId: string;
+}
+
+export interface BashToolCallEvent extends ToolCallEventBase {
+	toolName: "bash";
+	input: BashToolInput;
+}
+
+export interface ReadToolCallEvent extends ToolCallEventBase {
+	toolName: "read";
+	input: ReadToolInput;
+}
+
+export interface EditToolCallEvent extends ToolCallEventBase {
+	toolName: "edit";
 	input: Record<string, unknown>;
 }
 
+export interface WriteToolCallEvent extends ToolCallEventBase {
+	toolName: "write";
+	input: WriteToolInput;
+}
+
+export interface GrepToolCallEvent extends ToolCallEventBase {
+	toolName: "grep";
+	input: GrepToolInput;
+}
+
+export interface FindToolCallEvent extends ToolCallEventBase {
+	toolName: "find";
+	input: FindToolInput;
+}
+
+export interface CustomToolCallEvent extends ToolCallEventBase {
+	toolName: string;
+	input: Record<string, unknown>;
+}
+
+/** Fired before a tool executes. Can block. */
+export type ToolCallEvent =
+	| BashToolCallEvent
+	| ReadToolCallEvent
+	| EditToolCallEvent
+	| WriteToolCallEvent
+	| GrepToolCallEvent
+	| FindToolCallEvent
+	| CustomToolCallEvent;
+
 interface ToolResultEventBase {
 	type: "tool_result";
 	toolCallId: string;
@@ -515,8 +597,43 @@ export type ToolResultEvent =
 	| FindToolResultEvent
 	| CustomToolResultEvent;
 
+/**
+ * Type guard for narrowing ToolCallEvent by tool name.
+ *
+ * Built-in tools narrow automatically (no type params needed):
+ * ```ts
+ * if (isToolCallEventType("bash", event)) {
+ *   event.input.command;  // string
+ * }
+ * ```
+ *
+ * Custom tools require explicit type parameters:
+ * ```ts
+ * if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+ *   event.input.action;  // typed
+ * }
+ * ```
+ *
+ * Note: Direct narrowing via `event.toolName === "bash"` doesn't work because
+ * CustomToolCallEvent.toolName is `string` which overlaps with all literals.
+ */
+export function isToolCallEventType(toolName: "bash", event: ToolCallEvent): event is BashToolCallEvent;
+export function isToolCallEventType(toolName: "read", event: ToolCallEvent): event is ReadToolCallEvent;
+export function isToolCallEventType(toolName: "edit", event: ToolCallEvent): event is EditToolCallEvent;
+export function isToolCallEventType(toolName: "write", event: ToolCallEvent): event is WriteToolCallEvent;
+export function isToolCallEventType(toolName: "grep", event: ToolCallEvent): event is GrepToolCallEvent;
+export function isToolCallEventType(toolName: "find", event: ToolCallEvent): event is FindToolCallEvent;
+export function isToolCallEventType<TName extends string, TInput extends Record<string, unknown>>(
+	toolName: TName,
+	event: ToolCallEvent,
+): event is ToolCallEvent & { toolName: TName; input: TInput };
+export function isToolCallEventType(toolName: string, event: ToolCallEvent): boolean {
+	return event.toolName === toolName;
+}
+
 /** Union of all event types */
 export type ExtensionEvent =
+	| ResourcesDiscoverEvent
 	| SessionEvent
 	| ContextEvent
 	| BeforeAgentStartEvent
@@ -659,6 +776,7 @@ export interface ExtensionAPI {
 	// Event Subscription
 	// =========================================================================
 
+	on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
 	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
 	on(
 		event: "session_before_switch",
@@ -775,6 +893,9 @@ export interface ExtensionAPI {
 	/** Set the active tools by name. */
 	setActiveTools(toolNames: string[]): Promise<void>;
 
+	/** Get available slash commands in the current session. */
+	getCommands(): SlashCommandInfo[];
+
 	/** Set the current model. Returns false if no API key available. */
 	setModel(model: Model): Promise<boolean>;
 
@@ -833,6 +954,8 @@ export type GetActiveToolsHandler = () => string[];
 
 export type GetAllToolsHandler = () => string[];
 
+export type GetCommandsHandler = () => SlashCommandInfo[];
+
 export type SetActiveToolsHandler = (toolNames: string[]) => Promise<void>;
 
 export type SetModelHandler = (model: Model) => Promise<boolean>;
@@ -855,6 +978,7 @@ export interface ExtensionActions {
 	getActiveTools: GetActiveToolsHandler;
 	getAllTools: GetAllToolsHandler;
 	setActiveTools: SetActiveToolsHandler;
+	getCommands: GetCommandsHandler;
 	setModel: SetModelHandler;
 	getThinkingLevel: GetThinkingLevelHandler;
 	setThinkingLevel: SetThinkingLevelHandler;
@@ -869,6 +993,7 @@ export interface ExtensionContextActions {
 	shutdown: () => void;
 	getContextUsage: () => ContextUsage | undefined;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
+	getSystemPrompt: () => string;
 }
 
 /** Actions for ExtensionCommandContext (ctx.* in command handlers). */
@@ -882,6 +1007,7 @@ export interface ExtensionCommandContextActions {
 	branch: (entryId: string) => Promise<{ cancelled: boolean }>;
 	navigateTree: (targetId: string, options?: { summarize?: boolean }) => Promise<{ cancelled: boolean }>;
 	compact: (instructionsOrOptions?: string | CompactOptions) => Promise<void>;
+	switchSession: (sessionPath: string) => Promise<{ cancelled: boolean }>;
 }
 
 /** Full runtime = state + actions. */

package/src/extensibility/extensions/wrapper.ts

@@ -32,7 +32,7 @@ export class RegisteredToolAdapter implements AgentTool<any, any, any> {
 		onUpdate?: AgentToolUpdateCallback<any>,
 		_context?: AgentToolContext,
 	) {
-		return this.registeredTool.definition.execute(toolCallId, params, onUpdate, this.runner.createContext(), signal);
+		return this.registeredTool.definition.execute(toolCallId, params, signal, onUpdate, this.runner.createContext());
 	}
 
 	renderCall?(args: any, theme: any) {

package/src/extensibility/plugins/git-url.ts

@@ -0,0 +1,270 @@
+/**
+ * Parsed git URL information.
+ */
+export type GitSource = {
+	/** Always "git" for git sources */
+	type: "git";
+	/** Clone URL (always valid for git clone, without ref suffix) */
+	repo: string;
+	/** Git host domain (e.g., "github.com") */
+	host: string;
+	/** Repository path (e.g., "user/repo") */
+	path: string;
+	/** Git ref (branch, tag, commit) if specified */
+	ref?: string;
+	/** True if ref was specified (package won't be auto-updated) */
+	pinned: boolean;
+};
+
+/** Known git hosts and their URL extraction logic. */
+const KNOWN_HOSTS: Record<string, (pathname: string, hash: string) => { user: string; project: string } | null> = {
+	"github.com": extractStandard,
+	"gitlab.com": extractGitLab,
+	"bitbucket.org": extractStandard,
+	"git.sr.ht": extractStandard,
+	"codeberg.org": extractStandard,
+};
+
+function stripUrlCredentials(url: string): string {
+	if (!url.includes("://")) return url;
+	try {
+		const parsed = new URL(url);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return url;
+		if (!parsed.username && !parsed.password) return url;
+		parsed.username = "";
+		parsed.password = "";
+		return parsed.toString().replace(/\/$/, "");
+	} catch {
+		return url;
+	}
+}
+
+function extractStandard(pathname: string, _hash: string): { user: string; project: string } | null {
+	const [, user, project] = pathname.split("/", 3);
+	if (!user || !project) return null;
+	return { user, project: project.replace(/\.git$/, "") };
+}
+
+function extractGitLab(pathname: string, _hash: string): { user: string; project: string } | null {
+	const path = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	if (path.includes("/-/") || path.includes("/archive.tar.gz")) return null;
+	const segments = path.split("/");
+	let project = segments.pop();
+	if (!project) return null;
+	project = project.replace(/\.git$/, "");
+	const user = segments.join("/");
+	if (!user || !project) return null;
+	return { user, project };
+}
+
+/**
+ * Try to parse a URL against known git hosts.
+ * Returns `{ domain, user, project, committish }` or null.
+ */
+function tryKnownHost(candidate: string): { domain: string; user: string; project: string; committish: string } | null {
+	let parsed: URL;
+	try {
+		parsed = new URL(candidate);
+	} catch {
+		return null;
+	}
+
+	const hostname = parsed.hostname.startsWith("www.") ? parsed.hostname.slice(4) : parsed.hostname;
+	const extractor = KNOWN_HOSTS[hostname];
+	if (!extractor) return null;
+
+	const segments = extractor(parsed.pathname, parsed.hash);
+	if (!segments) return null;
+
+	let committish = "";
+	if (parsed.hash) {
+		try {
+			committish = decodeURIComponent(parsed.hash.slice(1));
+		} catch {
+			return null;
+		}
+	}
+
+	return {
+		domain: hostname,
+		user: segments.user,
+		project: segments.project,
+		committish,
+	};
+}
+
+function splitRef(url: string): { repo: string; ref?: string } {
+	const scpLikeMatch = url.match(/^git@([^:]+):(.+)$/);
+	if (scpLikeMatch) {
+		const pathWithMaybeRef = scpLikeMatch[2] ?? "";
+		const refSeparator = pathWithMaybeRef.indexOf("@");
+		if (refSeparator < 0) return { repo: url };
+		const repoPath = pathWithMaybeRef.slice(0, refSeparator);
+		const ref = pathWithMaybeRef.slice(refSeparator + 1);
+		if (!repoPath || !ref) return { repo: url };
+		return {
+			repo: `git@${scpLikeMatch[1] ?? ""}:${repoPath}`,
+			ref,
+		};
+	}
+
+	if (url.includes("://")) {
+		try {
+			const parsed = new URL(url);
+			const pathWithMaybeRef = parsed.pathname.replace(/^\/+/, "");
+			const refSeparator = pathWithMaybeRef.indexOf("@");
+			if (refSeparator < 0) return { repo: url };
+			const repoPath = pathWithMaybeRef.slice(0, refSeparator);
+			const ref = pathWithMaybeRef.slice(refSeparator + 1);
+			if (!repoPath || !ref) return { repo: url };
+			parsed.pathname = `/${repoPath}`;
+			if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+				parsed.username = "";
+				parsed.password = "";
+			}
+			return {
+				repo: parsed.toString().replace(/\/$/, ""),
+				ref,
+			};
+		} catch {
+			return { repo: url };
+		}
+	}
+
+	const slashIndex = url.indexOf("/");
+	if (slashIndex < 0) return { repo: url };
+	const host = url.slice(0, slashIndex);
+	const pathWithMaybeRef = url.slice(slashIndex + 1);
+	const refSeparator = pathWithMaybeRef.indexOf("@");
+	if (refSeparator < 0) return { repo: url };
+	const repoPath = pathWithMaybeRef.slice(0, refSeparator);
+	const ref = pathWithMaybeRef.slice(refSeparator + 1);
+	if (!repoPath || !ref) return { repo: url };
+	return { repo: `${host}/${repoPath}`, ref };
+}
+
+/** Try known-host parsing and build a GitSource from the result. */
+function tryKnownHostSource(
+	split: { repo: string; ref?: string },
+	candidate: string,
+	repoUrl: string,
+): GitSource | null {
+	const info = tryKnownHost(candidate);
+	if (!info) return null;
+	if (split.ref && info.project.includes("@")) return null;
+	return {
+		type: "git",
+		repo: stripUrlCredentials(repoUrl),
+		host: info.domain,
+		path: `${info.user}/${info.project}`.replace(/\.git$/, ""),
+		ref: info.committish || split.ref || undefined,
+		pinned: Boolean(info.committish || split.ref),
+	};
+}
+
+function parseGenericGitUrl(url: string): GitSource | null {
+	const { repo: repoWithoutRef, ref } = splitRef(url);
+	let repo = repoWithoutRef;
+	let host = "";
+	let repoPath = "";
+
+	const scpLikeMatch = repoWithoutRef.match(/^git@([^:]+):(.+)$/);
+	if (scpLikeMatch) {
+		host = scpLikeMatch[1] ?? "";
+		repoPath = scpLikeMatch[2] ?? "";
+	} else if (/^https?:\/\/|^ssh:\/\//.test(repoWithoutRef)) {
+		try {
+			const parsed = new URL(repoWithoutRef);
+			if (parsed.hash) {
+				try {
+					decodeURIComponent(parsed.hash.slice(1));
+				} catch {
+					return null;
+				}
+			}
+			host = parsed.hostname;
+			repoPath = parsed.pathname.replace(/^\/+/, "");
+			repo = stripUrlCredentials(repoWithoutRef);
+		} catch {
+			return null;
+		}
+	} else {
+		const slashIndex = repoWithoutRef.indexOf("/");
+		if (slashIndex < 0) return null;
+		repo = `https://${repoWithoutRef}`;
+		try {
+			const parsed = new URL(repo);
+			host = parsed.hostname;
+			repoPath = parsed.pathname.replace(/^\/+/, "");
+			repo = stripUrlCredentials(repo);
+		} catch {
+			return null;
+		}
+		if (!host.includes(".") && host !== "localhost") return null;
+	}
+
+	const normalizedPath = repoPath.replace(/\.git$/, "").replace(/^\/+/, "");
+	if (!host || !normalizedPath || normalizedPath.split("/").length < 2) return null;
+
+	return { type: "git", repo, host, path: normalizedPath, ref, pinned: Boolean(ref) };
+}
+
+/**
+ * Parse any git URL (SSH or HTTPS) into a GitSource.
+ *
+ * Handles:
+ * - `git:` prefixed URLs (`git:github.com/user/repo`)
+ * - SSH SCP-like URLs (`git@github.com:user/repo`)
+ * - HTTPS/HTTP/SSH protocol URLs
+ * - Bare `host/user/repo` shorthand
+ * - Ref pinning via `@ref` suffix
+ *
+ * Recognizes GitHub, GitLab, Bitbucket, Sourcehut, and Codeberg natively.
+ * Falls back to generic URL parsing for other hosts.
+ */
+export function parseGitUrl(source: string): GitSource | null {
+	const url = source.startsWith("git:") ? source.slice(4).trim() : source;
+	const hashIndex = url.indexOf("#");
+	if (hashIndex >= 0) {
+		const hash = url.slice(hashIndex + 1);
+		if (hash) {
+			try {
+				decodeURIComponent(hash);
+			} catch {
+				return null;
+			}
+		}
+	}
+	const split = splitRef(url);
+
+	// SCP-like SSH URLs (git@host:user/repo) — convert to https for host matching
+	const scpMatch = split.repo.match(/^git@([^:]+):(.+)$/);
+
+	// Try known hosts with the repo URL directly
+	const directCandidates: string[] = [];
+	if (scpMatch) {
+		directCandidates.push(`https://${scpMatch[1]}/${scpMatch[2]}`);
+	} else if (/^https?:\/\/|^ssh:\/\//.test(split.repo)) {
+		directCandidates.push(split.repo);
+	}
+
+	for (const candidate of directCandidates) {
+		const withRef = split.ref ? `${candidate.replace(/#.*$/, "")}#${split.ref}` : candidate;
+		const needsHttps =
+			!split.repo.startsWith("http://") &&
+			!split.repo.startsWith("https://") &&
+			!split.repo.startsWith("ssh://") &&
+			!split.repo.startsWith("git@");
+		const result = tryKnownHostSource(split, withRef, needsHttps ? `https://${split.repo}` : split.repo);
+		if (result) return result;
+	}
+
+	// Try with https:// prefix for bare host/user/repo shorthand
+	if (!split.repo.includes("://") && !split.repo.startsWith("git@")) {
+		const httpsCandidate = split.ref ? `https://${split.repo}#${split.ref}` : `https://${url}`;
+		const result = tryKnownHostSource(split, httpsCandidate, `https://${split.repo}`);
+		if (result) return result;
+	}
+
+	return parseGenericGitUrl(url);
+}

package/src/extensibility/plugins/index.ts

@@ -1,5 +1,7 @@
 // Plugin system exports
+
 export { formatDoctorResults, runDoctorChecks } from "./doctor";
+export { type GitSource, parseGitUrl } from "./git-url";
 export {
 	getAllPluginCommandPaths,
 	getAllPluginHookPaths,