@oh-my-pi/pi-coding-agent 8.1.0 → 8.2.0

package/src/capability/fs.ts

@@ -1,16 +1,15 @@
-import type { Dirent } from "node:fs";
-import { readdir } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
 const contentCache = new Map<string, string | null>();
-const dirCache = new Map<string, Dirent[]>();
+const dirCache = new Map<string, fs.Dirent[]>();
 
-function resolvePath(path: string): string {
-	return resolve(path);
+function resolvePath(filePath: string): string {
+	return path.resolve(filePath);
 }
 
-export async function readFile(path: string): Promise<string | null> {
-	const abs = resolvePath(path);
+export async function readFile(filePath: string): Promise<string | null> {
+	const abs = resolvePath(filePath);
 	if (contentCache.has(abs)) {
 		return contentCache.get(abs) ?? null;
 	}
@@ -25,14 +24,14 @@ export async function readFile(path: string): Promise<string | null> {
 	}
 }
 
-export async function readDirEntries(path: string): Promise<Dirent[]> {
-	const abs = resolvePath(path);
+export async function readDirEntries(dirPath: string): Promise<fs.Dirent[]> {
+	const abs = resolvePath(dirPath);
 	if (dirCache.has(abs)) {
 		return dirCache.get(abs) ?? [];
 	}
 
 	try {
-		const entries = await readdir(abs, { withFileTypes: true });
+		const entries = await fs.promises.readdir(abs, { withFileTypes: true });
 		dirCache.set(abs, entries);
 		return entries;
 	} catch {
@@ -41,9 +40,9 @@ export async function readDirEntries(path: string): Promise<Dirent[]> {
 	}
 }
 
-export async function readDir(path: string): Promise<string[]> {
-	const entries = await readDirEntries(path);
-	return entries.map((entry) => entry.name);
+export async function readDir(dirPath: string): Promise<string[]> {
+	const entries = await readDirEntries(dirPath);
+	return entries.map(entry => entry.name);
 }
 
 export async function walkUp(
@@ -56,12 +55,12 @@ export async function walkUp(
 
 	while (true) {
 		const entries = await readDirEntries(current);
-		const entry = entries.find((e) => e.name === name);
+		const entry = entries.find(e => e.name === name);
 		if (entry) {
-			if (file && entry.isFile()) return join(current, name);
-			if (dir && entry.isDirectory()) return join(current, name);
+			if (file && entry.isFile()) return path.join(current, name);
+			if (dir && entry.isDirectory()) return path.join(current, name);
 		}
-		const parent = dirname(current);
+		const parent = path.dirname(current);
 		if (parent === current) return null;
 		current = parent;
 	}
@@ -79,11 +78,11 @@ export function clearCache(): void {
 	dirCache.clear();
 }
 
-export function invalidate(path: string): void {
-	const abs = resolvePath(path);
+export function invalidate(filePath: string): void {
+	const abs = resolvePath(filePath);
 	contentCache.delete(abs);
 	dirCache.delete(abs);
-	const parent = dirname(abs);
+	const parent = path.dirname(abs);
 	if (parent !== abs) {
 		dirCache.delete(parent);
 	}

package/src/capability/hook.ts

@@ -3,7 +3,6 @@
  *
  * Pre/post tool execution hooks defined as shell scripts.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -29,8 +28,8 @@ export const hookCapability = defineCapability<Hook>({
 	id: "hooks",
 	displayName: "Hooks",
 	description: "Pre/post tool execution hooks",
-	key: (hook) => `${hook.type}:${hook.tool}:${hook.name}`,
-	validate: (hook) => {
+	key: hook => `${hook.type}:${hook.tool}:${hook.name}`,
+	validate: hook => {
 		if (!hook.name) return "Missing name";
 		if (!hook.path) return "Missing path";
 		if (hook.type !== "pre" && hook.type !== "post") return "Invalid type (must be 'pre' or 'post')";

package/src/capability/index.ts

@@ -6,9 +6,8 @@
  * - Registering providers (where to find it)
  * - Loading items for a capability across all providers
  */
-
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import * as os from "node:os";
+import * as path from "node:path";
 import { clearCache as clearFsCache, cacheStats as fsCacheStats, invalidate as invalidateFs } from "./fs";
 import type {
 	Capability,
@@ -81,7 +80,7 @@ export function registerProvider<T>(capabilityId: string, provider: Provider<T>)
 
 	// Insert in priority order (highest first)
 	const providers = capability.providers as Provider<T>[];
-	const idx = providers.findIndex((p) => p.priority < provider.priority);
+	const idx = providers.findIndex(p => p.priority < provider.priority);
 	if (idx === -1) {
 		providers.push(provider);
 	} else {
@@ -107,7 +106,7 @@ async function loadImpl<T>(
 	const contributingProviders: string[] = [];
 
 	const results = await Promise.all(
-		providers.map(async (provider) => {
+		providers.map(async provider => {
 			try {
 				const result = await provider.load(ctx);
 				return { provider, result };
@@ -128,7 +127,7 @@ async function loadImpl<T>(
 		if (!result) continue;
 
 		if (result.warnings) {
-			allWarnings.push(...result.warnings.map((w) => `[${provider.displayName}] ${w}`));
+			allWarnings.push(...result.warnings.map(w => `[${provider.displayName}] ${w}`));
 		}
 
 		if (result.items.length > 0) {
@@ -190,15 +189,15 @@ async function loadImpl<T>(
  * Filter providers based on options and disabled state.
  */
 function filterProviders<T>(capability: Capability<T>, options: LoadOptions): Provider<T>[] {
-	let providers = (capability.providers as Provider<T>[]).filter((p) => !disabledProviders.has(p.id));
+	let providers = (capability.providers as Provider<T>[]).filter(p => !disabledProviders.has(p.id));
 
 	if (options.providers) {
 		const allowed = new Set(options.providers);
-		providers = providers.filter((p) => allowed.has(p.id));
+		providers = providers.filter(p => allowed.has(p.id));
 	}
 	if (options.excludeProviders) {
 		const excluded = new Set(options.excludeProviders);
-		providers = providers.filter((p) => !excluded.has(p.id));
+		providers = providers.filter(p => !excluded.has(p.id));
 	}
 
 	return providers;
@@ -214,7 +213,7 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 	}
 
 	const cwd = options.cwd ?? process.cwd();
-	const home = homedir();
+	const home = os.homedir();
 	const ctx: LoadContext = { cwd, home };
 	const providers = filterProviders(capability, options);
 
@@ -321,7 +320,7 @@ export function getCapabilityInfo(capabilityId: string): CapabilityInfo | undefi
 		id: capability.id,
 		displayName: capability.displayName,
 		description: capability.description,
-		providers: capability.providers.map((p) => ({
+		providers: capability.providers.map(p => ({
 			id: p.id,
 			displayName: p.displayName,
 			description: p.description,
@@ -335,7 +334,7 @@ export function getCapabilityInfo(capabilityId: string): CapabilityInfo | undefi
  * Get all capabilities info for UI display.
  */
 export function getAllCapabilitiesInfo(): CapabilityInfo[] {
-	return listCapabilities().map((id) => getCapabilityInfo(id)!);
+	return listCapabilities().map(id => getCapabilityInfo(id)!);
 }
 
 /**
@@ -350,7 +349,7 @@ export function getProviderInfo(providerId: string): ProviderInfo | undefined {
 	let priority = 0;
 	for (const capId of caps) {
 		const cap = capabilities.get(capId);
-		const provider = cap?.providers.find((p) => p.id === providerId);
+		const provider = cap?.providers.find(p => p.id === providerId);
 		if (provider) {
 			priority = provider.priority;
 			break;
@@ -399,10 +398,10 @@ export function reset(): void {
 
 /**
  * Invalidate cache for a specific path.
- * @param path - Absolute or relative path to invalidate
+ * @param filePath - Absolute or relative path to invalidate
  */
-export function invalidate(path: string, cwd?: string): void {
-	const resolved = cwd ? resolve(cwd, path) : path;
+export function invalidate(filePath: string, cwd?: string): void {
+	const resolved = cwd ? path.resolve(cwd, filePath) : filePath;
 	invalidateFs(resolved);
 }
 

package/src/capability/instruction.ts

@@ -3,7 +3,6 @@
  *
  * GitHub Copilot-style instructions with optional file pattern matching.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -27,8 +26,8 @@ export const instructionCapability = defineCapability<Instruction>({
 	id: "instructions",
 	displayName: "Instructions",
 	description: "File-specific instructions with glob pattern matching (GitHub Copilot format)",
-	key: (inst) => inst.name,
-	validate: (inst) => {
+	key: inst => inst.name,
+	validate: inst => {
 		if (!inst.name) return "Missing name";
 		if (!inst.path) return "Missing path";
 		if (inst.content === undefined) return "Missing content";

package/src/capability/mcp.ts

@@ -4,7 +4,6 @@
  * Canonical shape for MCP server configurations, regardless of source format.
  * All providers translate their native format to this shape.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -34,8 +33,8 @@ export const mcpCapability = defineCapability<MCPServer>({
 	id: "mcps",
 	displayName: "MCP Servers",
 	description: "Model Context Protocol server configurations for external tool integrations",
-	key: (server) => server.name,
-	validate: (server) => {
+	key: server => server.name,
+	validate: server => {
 		if (!server.name) return "Missing server name";
 		if (!server.command && !server.url) return "Must have command or url";
 

package/src/capability/prompt.ts

@@ -3,7 +3,6 @@
  *
  * Reusable prompt templates (Codex format) available via /prompts: menu.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -25,8 +24,8 @@ export const promptCapability = defineCapability<Prompt>({
 	id: "prompts",
 	displayName: "Prompts",
 	description: "Reusable prompt templates available via /prompts: menu",
-	key: (prompt) => prompt.name,
-	validate: (prompt) => {
+	key: prompt => prompt.name,
+	validate: prompt => {
 		if (!prompt.name) return "Missing name";
 		if (!prompt.path) return "Missing path";
 		if (prompt.content === undefined) return "Missing content";

package/src/capability/rule.ts

@@ -4,7 +4,6 @@
  * Project-specific rules from Cursor (.mdc), Windsurf (.md), and Cline formats.
  * Translated to a canonical shape regardless of source format.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -46,8 +45,8 @@ export const ruleCapability = defineCapability<Rule>({
 	id: "rules",
 	displayName: "Rules",
 	description: "Project-specific rules and constraints (Cursor MDC, Windsurf, Cline formats)",
-	key: (rule) => rule.name,
-	validate: (rule) => {
+	key: rule => rule.name,
+	validate: rule => {
 		if (!rule.name) return "Missing rule name";
 		if (!rule.path) return "Missing rule path";
 		if (!rule.content || typeof rule.content !== "string") return "Rule must have content";

package/src/capability/settings.ts

@@ -3,7 +3,6 @@
  *
  * Configuration settings from various sources (JSON, TOML, etc.)
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -27,7 +26,7 @@ export const settingsCapability = defineCapability<Settings>({
 	description: "Configuration settings from various sources",
 	// Settings are merged, not deduplicated by key
 	key: () => undefined,
-	validate: (settings) => {
+	validate: settings => {
 		if (!settings.path) return "Missing path";
 		if (!settings.data || typeof settings.data !== "object") return "Missing or invalid data";
 		return undefined;

package/src/capability/skill.ts

@@ -3,7 +3,6 @@
  *
  * Skills provide specialized knowledge or workflows that extend agent capabilities.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -40,8 +39,8 @@ export const skillCapability = defineCapability<Skill>({
 	id: "skills",
 	displayName: "Skills",
 	description: "Specialized knowledge and workflow files that extend agent capabilities",
-	key: (skill) => skill.name,
-	validate: (skill) => {
+	key: skill => skill.name,
+	validate: skill => {
 		if (!skill.name) return "Missing skill name";
 		if (!skill.path) return "Missing skill path";
 		return undefined;

package/src/capability/slash-command.ts

@@ -3,7 +3,6 @@
  *
  * File-based slash commands defined as markdown files.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -27,8 +26,8 @@ export const slashCommandCapability = defineCapability<SlashCommand>({
 	id: "slash-commands",
 	displayName: "Slash Commands",
 	description: "Custom slash commands defined as markdown files",
-	key: (cmd) => cmd.name,
-	validate: (cmd) => {
+	key: cmd => cmd.name,
+	validate: cmd => {
 		if (!cmd.name) return "Missing name";
 		if (!cmd.path) return "Missing path";
 		if (cmd.content === undefined) return "Missing content";

package/src/capability/ssh.ts

@@ -3,7 +3,6 @@
  *
  * Canonical shape for SSH host entries, regardless of source format.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -33,8 +32,8 @@ export const sshCapability = defineCapability<SSHHost>({
 	id: "ssh",
 	displayName: "SSH Hosts",
 	description: "SSH host entries for remote command execution",
-	key: (host) => host.name,
-	validate: (host) => {
+	key: host => host.name,
+	validate: host => {
 		if (!host.name) return "Missing name";
 		if (!host.host) return "Missing host";
 		return undefined;

package/src/capability/system-prompt.ts

@@ -4,7 +4,6 @@
  * Custom system prompt files (SYSTEM.md) that modify the agent's base system prompt.
  * Distinct from context-files which are user instructions shown in conversation.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -26,8 +25,8 @@ export const systemPromptCapability = defineCapability<SystemPrompt>({
 	id: "system-prompt",
 	displayName: "System Prompt",
 	description: "Custom system prompt files (SYSTEM.md) that modify agent behavior",
-	key: (sp) => sp.level,
-	validate: (sp) => {
+	key: sp => sp.level,
+	validate: sp => {
 		if (!sp.path) return "Missing path";
 		if (sp.content === undefined) return "Missing content";
 		return undefined;

package/src/capability/tool.ts

@@ -3,7 +3,6 @@
  *
  * User-defined tools that extend agent capabilities.
  */
-
 import { defineCapability } from ".";
 import type { SourceMeta } from "./types";
 
@@ -29,8 +28,8 @@ export const toolCapability = defineCapability<CustomTool>({
 	id: "tools",
 	displayName: "Custom Tools",
 	description: "User-defined tools that extend agent capabilities",
-	key: (tool) => tool.name,
-	validate: (tool) => {
+	key: tool => tool.name,
+	validate: tool => {
 		if (!tool.name) return "Missing name";
 		if (!tool.path) return "Missing path";
 		return undefined;

package/src/cli/args.ts

@@ -1,11 +1,10 @@
 /**
  * CLI argument parsing and help display
  */
-
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "@oh-my-pi/pi-coding-agent/config";
-import { BUILTIN_TOOLS } from "@oh-my-pi/pi-coding-agent/tools";
 import chalk from "chalk";
+import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR } from "../config";
+import { BUILTIN_TOOLS } from "../tools";
 
 export type Mode = "text" | "json" | "rpc";
 
@@ -99,13 +98,13 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 		} else if (arg === "--session-dir" && i + 1 < args.length) {
 			result.sessionDir = args[++i];
 		} else if (arg === "--models" && i + 1 < args.length) {
-			result.models = args[++i].split(",").map((s) => s.trim());
+			result.models = args[++i].split(",").map(s => s.trim());
 		} else if (arg === "--no-tools") {
 			result.noTools = true;
 		} else if (arg === "--no-lsp") {
 			result.noLsp = true;
 		} else if (arg === "--tools" && i + 1 < args.length) {
-			const toolNames = args[++i].split(",").map((s) => s.trim());
+			const toolNames = args[++i].split(",").map(s => s.trim());
 			const validTools: string[] = [];
 			for (const name of toolNames) {
 				if (name in BUILTIN_TOOLS) {
@@ -148,7 +147,7 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			result.noTitle = true;
 		} else if (arg === "--skills" && i + 1 < args.length) {
 			// Comma-separated glob patterns for skill filtering
-			result.skills = args[++i].split(",").map((s) => s.trim());
+			result.skills = args[++i].split(",").map(s => s.trim());
 		} else if (arg === "--list-models") {
 			// Check if next arg is a search pattern (not a flag or file arg)
 			if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {

package/src/cli/config-cli.ts

@@ -4,12 +4,11 @@
  * Handles `omp config <command>` subcommands for managing settings.
  * Uses SETTINGS_DEFS as the source of truth for available settings.
  */
-
-import { APP_NAME, getAgentDir } from "@oh-my-pi/pi-coding-agent/config";
-import { SettingsManager } from "@oh-my-pi/pi-coding-agent/config/settings-manager";
-import { SETTINGS_DEFS, type SettingDef } from "@oh-my-pi/pi-coding-agent/modes/components/settings-defs";
-import { theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import chalk from "chalk";
+import { APP_NAME, getAgentDir } from "../config";
+import { SettingsManager } from "../config/settings-manager";
+import { SETTINGS_DEFS, type SettingDef } from "../modes/components/settings-defs";
+import { theme } from "../modes/theme/theme";
 
 // =============================================================================
 // Types
@@ -32,7 +31,7 @@ export interface ConfigCommandArgs {
 
 /** Find setting definition by ID */
 function findSettingDef(id: string): SettingDef | undefined {
-	return SETTINGS_DEFS.find((def) => def.id === id);
+	return SETTINGS_DEFS.find(def => def.id === id);
 }
 
 /** Get available values for a setting */
@@ -43,7 +42,7 @@ function getSettingValues(def: SettingDef, sm: SettingsManager): readonly string
 	if (def.type === "submenu") {
 		const options = def.getOptions(sm);
 		if (options.length > 0) {
-			return options.map((o) => o.value);
+			return options.map(o => o.value);
 		}
 	}
 	return undefined;

package/src/cli/file-processor.ts

@@ -1,14 +1,14 @@
 /**
  * Process @file CLI arguments into text content and image attachments
  */
-
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
-import { resolveReadPath } from "@oh-my-pi/pi-coding-agent/tools/path-utils";
-import { formatDimensionNote, resizeImage } from "@oh-my-pi/pi-coding-agent/utils/image-resize";
-import { detectSupportedImageMimeTypeFromFile } from "@oh-my-pi/pi-coding-agent/utils/mime";
+import { isEnoent } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
+import { resolveReadPath } from "../tools/path-utils";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { detectSupportedImageMimeTypeFromFile } from "../utils/mime";
 
 export interface ProcessedFiles {
 	text: string;
@@ -28,16 +28,20 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 
 	for (const fileArg of fileArgs) {
 		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
-		const absolutePath = resolve(resolveReadPath(fileArg, process.cwd()));
+		const absolutePath = path.resolve(resolveReadPath(fileArg, process.cwd()));
 
-		// Check if file exists and is not empty
-		if (!existsSync(absolutePath)) {
-			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
-			process.exit(1);
+		// Read file, handling not-found gracefully
+		let buffer: Buffer;
+		try {
+			buffer = await fs.readFile(absolutePath);
+		} catch (err) {
+			if (isEnoent(err)) {
+				console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+				process.exit(1);
+			}
+			throw err;
 		}
-		const stats = statSync(absolutePath);
-		if (stats.size === 0) {
-			// Skip empty files
+		if (buffer.length === 0) {
 			continue;
 		}
 
@@ -45,9 +49,7 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 
 		if (mimeType) {
 			// Handle image file
-			const buffer = readFileSync(absolutePath);
 			const base64Content = buffer.toString("base64");
-
 			let attachment: ImageContent;
 			let dimensionNote: string | undefined;
 
@@ -87,7 +89,7 @@ export async function processFileArguments(fileArgs: string[], options?: Process
 		} else {
 			// Handle text file
 			try {
-				const content = readFileSync(absolutePath, "utf-8");
+				const content = buffer.toString("utf-8");
 				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
 			} catch (error: unknown) {
 				const message = error instanceof Error ? error.message : String(error);

package/src/cli/jupyter-cli.ts

@@ -0,0 +1,105 @@
+/**
+ * Jupyter CLI command handlers.
+ *
+ * Handles `omp jupyter` subcommand for managing the shared Python gateway.
+ */
+import chalk from "chalk";
+import { APP_NAME } from "../config";
+import { getGatewayStatus, shutdownSharedGateway } from "../ipy/gateway-coordinator";
+
+export type JupyterAction = "kill" | "status";
+
+export interface JupyterCommandArgs {
+	action: JupyterAction;
+}
+
+export function parseJupyterArgs(args: string[]): JupyterCommandArgs | undefined {
+	if (args.length === 0 || args[0] !== "jupyter") {
+		return undefined;
+	}
+
+	const action = args[1] as JupyterAction | undefined;
+	if (!action || !["kill", "status"].includes(action)) {
+		return { action: "status" };
+	}
+
+	return { action };
+}
+
+export async function runJupyterCommand(cmd: JupyterCommandArgs): Promise<void> {
+	switch (cmd.action) {
+		case "kill":
+			await runKill();
+			break;
+		case "status":
+			await runStatus();
+			break;
+	}
+}
+
+async function runKill(): Promise<void> {
+	const status = await getGatewayStatus();
+
+	if (!status.active) {
+		console.log(chalk.dim("No Jupyter gateway is running"));
+		return;
+	}
+
+	console.log(`Killing Jupyter gateway (PID ${status.pid})...`);
+	await shutdownSharedGateway();
+	console.log(chalk.green("Jupyter gateway stopped"));
+}
+
+async function runStatus(): Promise<void> {
+	const status = await getGatewayStatus();
+
+	if (!status.active) {
+		console.log(chalk.dim("No Jupyter gateway is running"));
+		return;
+	}
+
+	console.log(chalk.bold("Jupyter Gateway Status\n"));
+	console.log(`  ${chalk.green("●")} Running`);
+	console.log(`  PID:    ${status.pid}`);
+	console.log(`  URL:    ${status.url}`);
+	if (status.uptime !== null) {
+		console.log(`  Uptime: ${formatUptime(status.uptime)}`);
+	}
+	if (status.pythonPath) {
+		console.log(`  Python: ${status.pythonPath}`);
+	}
+	if (status.venvPath) {
+		console.log(`  Venv:   ${status.venvPath}`);
+	}
+}
+
+function formatUptime(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	const minutes = Math.floor(seconds / 60);
+	const hours = Math.floor(minutes / 60);
+
+	if (hours > 0) {
+		return `${hours}h ${minutes % 60}m`;
+	}
+	if (minutes > 0) {
+		return `${minutes}m ${seconds % 60}s`;
+	}
+	return `${seconds}s`;
+}
+
+export function printJupyterHelp(): void {
+	console.log(`${chalk.bold(`${APP_NAME} jupyter`)} - Manage the shared Jupyter gateway
+
+${chalk.bold("Usage:")}
+  ${APP_NAME} jupyter <command>
+
+${chalk.bold("Commands:")}
+  status    Show gateway status (default)
+  kill      Stop the running gateway
+
+${chalk.bold("Examples:")}
+  ${APP_NAME} jupyter           # Show status
+  ${APP_NAME} jupyter status    # Show status
+  ${APP_NAME} jupyter kill      # Stop the gateway
+`);
+}