@llmindset/hf-mcp 0.2.32 → 0.2.34

package/src/jobs/commands/inspect.ts

@@ -0,0 +1,38 @@
+import type { InspectArgs, CancelArgs } from '../types.js';
+import type { JobsApiClient } from '../api-client.js';
+import { formatJobDetails } from '../formatters.js';
+
+/**
+ * Execute the 'inspect' command
+ * Gets detailed information about one or more jobs
+ */
+export async function inspectCommand(args: InspectArgs, client: JobsApiClient): Promise<string> {
+	const jobIds = Array.isArray(args.job_id) ? args.job_id : [args.job_id];
+
+	// Fetch all jobs
+	const jobs = await Promise.all(
+		jobIds.map(async (id) => {
+			try {
+				return await client.getJob(id, args.namespace);
+			} catch (error) {
+				throw new Error(`Failed to fetch job ${id}: ${(error as Error).message}`);
+			}
+		})
+	);
+
+	const formattedDetails = formatJobDetails(jobs);
+
+	return `**Job Details** (${jobs.length} job${jobs.length > 1 ? 's' : ''}):\n\n${formattedDetails}`;
+}
+
+/**
+ * Execute the 'cancel' command
+ * Cancels a running job
+ */
+export async function cancelCommand(args: CancelArgs, client: JobsApiClient): Promise<string> {
+	await client.cancelJob(args.job_id, args.namespace);
+
+	return `✓ Job ${args.job_id} has been cancelled.
+
+To verify: \`hf_jobs("inspect", {"job_id": "${args.job_id}"})\``;
+}

package/src/jobs/commands/logs.ts

@@ -0,0 +1,36 @@
+import type { LogsArgs } from '../types.js';
+import type { JobsApiClient } from '../api-client.js';
+import { fetchJobLogs } from '../sse-handler.js';
+
+/**
+ * Execute the 'logs' command
+ * Fetches logs from a job via SSE
+ */
+export async function logsCommand(args: LogsArgs, client: JobsApiClient, token?: string): Promise<string> {
+	// Get namespace for the logs URL
+	const namespace = await client.getNamespace(args.namespace);
+	const logsUrl = client.getLogsUrl(args.job_id, namespace);
+
+	// Fetch logs with timeout and line limit
+	const result = await fetchJobLogs(logsUrl, {
+		token,
+		maxDuration: 10000,
+		maxLines: args.tail,
+	});
+
+	if (result.logs.length === 0) {
+		return `No logs available for job ${args.job_id}`;
+	}
+
+	let response = `**Logs for job ${args.job_id}** (last ${args.tail} lines):\n\n${'```'}\n`;
+	response += result.logs.join('\n');
+	response += `\n${'```'}`;
+
+	if (result.finished) {
+		response += '\n\n✓ Job finished.';
+	} else if (result.truncated) {
+		response += '\n\n⚠ Log collection stopped after 10 seconds. Job may still be running.';
+	}
+
+	return response;
+}

package/src/jobs/commands/ps.ts

@@ -0,0 +1,40 @@
+import type { PsArgs } from '../types.js';
+import type { JobsApiClient } from '../api-client.js';
+import { formatJobsTable } from '../formatters.js';
+
+/**
+ * Execute the 'ps' command
+ * Lists jobs with optional filtering
+ */
+export async function psCommand(args: PsArgs, client: JobsApiClient): Promise<string> {
+	// Fetch all jobs from API
+	const allJobs = await client.listJobs(args.namespace);
+
+	// Filter jobs
+	let jobs = allJobs;
+
+	// Default: show only running jobs unless --all is specified
+	if (!args.all) {
+		jobs = jobs.filter((job) => job.status.stage === 'RUNNING');
+	}
+
+	// Apply status filter if specified
+	if (args.status) {
+		const statusFilter = args.status.toUpperCase();
+		jobs = jobs.filter((job) => job.status.stage.toUpperCase().includes(statusFilter));
+	}
+
+	// Format as markdown table
+	const table = formatJobsTable(jobs);
+
+	if (jobs.length === 0) {
+		if (args.all) {
+			return 'No jobs found.';
+		}
+		return 'No running jobs found. Use `{"all": true}` to show all jobs.';
+	}
+
+	return `**Jobs (${jobs.length} of ${allJobs.length} total):**
+
+${table}`;
+}

package/src/jobs/commands/run.ts

@@ -0,0 +1,134 @@
+import type { RunArgs, UvArgs } from '../types.js';
+import type { JobsApiClient } from '../api-client.js';
+import { createJobSpec } from './utils.js';
+import { fetchJobLogs } from '../sse-handler.js';
+
+/**
+ * Execute the 'run' command
+ * Creates and runs a job, optionally waiting for logs
+ */
+export async function runCommand(args: RunArgs, client: JobsApiClient, token?: string): Promise<string> {
+	// Create job spec from args
+	const jobSpec = createJobSpec({
+		image: args.image,
+		command: args.command,
+		flavor: args.flavor,
+		env: args.env,
+		secrets: args.secrets,
+		timeout: args.timeout,
+	});
+
+	// Submit job
+	const job = await client.runJob(jobSpec, args.namespace);
+
+	const jobUrl = `https://huggingface.co/jobs/${job.owner.name}/${job.id}`;
+
+	// If detached, return immediately
+	if (args.detach) {
+		return `Job started successfully!
+
+**Job ID:** ${job.id}
+**Status:** ${job.status.stage}
+**View at:** ${jobUrl}
+
+To check logs: \`hf_jobs("logs", {"job_id": "${job.id}"})\`
+To inspect: \`hf_jobs("inspect", {"job_id": "${job.id}"})\``;
+	}
+
+	// Not detached - fetch logs
+	const logsUrl = client.getLogsUrl(job.id, job.owner.name);
+	const logResult = await fetchJobLogs(logsUrl, { token, maxDuration: 10000, maxLines: 20 });
+
+	let response = `Job started: ${job.id}\n\n`;
+
+	if (logResult.logs.length > 0) {
+		response += '**Logs (last 20 lines):**\n```\n';
+		response += logResult.logs.join('\n');
+		response += '\n```\n\n';
+	}
+
+	if (logResult.finished) {
+		response += `Job finished. Full details: ${jobUrl}`;
+	} else if (logResult.truncated) {
+		response += `Log collection stopped after 10s. Job may still be running.\n`;
+		response += `View full logs: ${jobUrl}`;
+	}
+
+	return response;
+}
+
+/**
+ * Execute the 'uv' command
+ * Creates and runs a UV-based Python job
+ */
+export async function uvCommand(args: UvArgs, client: JobsApiClient, token?: string): Promise<string> {
+	// UV jobs use a standard UV image unless overridden
+	const image = 'ghcr.io/astral-sh/uv:latest'; // Standard UV image
+
+	// Detect script source and build command
+	const scriptSource = args.script;
+	let command: string | string[];
+
+	// Check if script is a URL
+	if (scriptSource.startsWith('http://') || scriptSource.startsWith('https://')) {
+		// URL - download and run
+		command = buildUvCommand(scriptSource, args);
+	} else if (scriptSource.includes('\n')) {
+		// Inline multi-line script - encode it
+		const encoded = Buffer.from(scriptSource).toString('base64');
+		const depsPart =
+			args.with_deps && args.with_deps.length > 0
+				? args.with_deps.map(dep => `--with ${dep}`).join(' ')
+				: '';
+		const pythonPart = args.python ? `-p ${args.python}` : '';
+		const uvArgs = [depsPart, pythonPart].filter(Boolean).join(' ');
+		const shellSnippet = `echo "${encoded}" | base64 -d | uv run${uvArgs ? ` ${uvArgs}` : ''} -`;
+		command = ['/bin/sh', '-lc', shellSnippet];
+	} else {
+		// Assume it's a URL or path - UV will handle it
+		command = buildUvCommand(scriptSource, args);
+	}
+
+	// Convert to run args
+	const runArgs: RunArgs = {
+		image,
+		command,
+		flavor: args.flavor,
+		env: args.env,
+		secrets: args.secrets,
+		timeout: args.timeout,
+		detach: args.detach,
+		namespace: args.namespace,
+	};
+
+	return runCommand(runArgs, client, token);
+}
+
+/**
+ * Build UV command with options
+ */
+function buildUvCommand(script: string, args: UvArgs): string {
+	const parts: string[] = ['uv', 'run'];
+
+	// Add dependencies
+	if (args.with_deps && args.with_deps.length > 0) {
+		for (const dep of args.with_deps) {
+			parts.push('--with', dep);
+		}
+	}
+
+	// Add Python version
+	if (args.python) {
+		parts.push('-p', args.python);
+	}
+
+	// Add script
+	parts.push(script);
+
+	// Add script arguments
+	if (args.script_args && args.script_args.length > 0) {
+		parts.push(...args.script_args);
+	}
+
+	return parts.join(' ');
+}

package/src/jobs/commands/scheduled.ts

@@ -0,0 +1,189 @@
+import type {
+	ScheduledRunArgs,
+	ScheduledUvArgs,
+	ScheduledPsArgs,
+	ScheduledJobArgs,
+	ScheduledJobSpec,
+} from '../types.js';
+import type { JobsApiClient } from '../api-client.js';
+import { formatScheduledJobsTable, formatScheduledJobDetails } from '../formatters.js';
+import { createJobSpec } from './utils.js';
+
+/**
+ * Execute 'scheduled run' command
+ * Creates a scheduled job
+ */
+export async function scheduledRunCommand(args: ScheduledRunArgs, client: JobsApiClient): Promise<string> {
+	// Create job spec
+	const jobSpec = createJobSpec({
+		image: args.image,
+		command: args.command,
+		flavor: args.flavor,
+		env: args.env,
+		secrets: args.secrets,
+		timeout: args.timeout,
+	});
+
+	// Create scheduled job spec
+	const scheduledSpec: ScheduledJobSpec = {
+		schedule: args.schedule,
+		suspend: args.suspend,
+		jobSpec,
+	};
+
+	// Submit scheduled job
+	const scheduledJob = await client.createScheduledJob(scheduledSpec, args.namespace);
+
+	return `✓ Scheduled job created successfully!
+
+**Scheduled Job ID:** ${scheduledJob.id}
+**Schedule:** ${scheduledJob.schedule}
+**Suspended:** ${scheduledJob.suspend ? 'Yes' : 'No'}
+**Next Run:** ${scheduledJob.nextRun || 'N/A'}
+
+To inspect: \`hf_jobs("scheduled inspect", {"scheduled_job_id": "${scheduledJob.id}"})\`
+To list all: \`hf_jobs("scheduled ps")\``;
+}
+
+/**
+ * Execute 'scheduled uv' command
+ * Creates a scheduled UV job
+ */
+export async function scheduledUvCommand(args: ScheduledUvArgs, client: JobsApiClient): Promise<string> {
+	// For UV, use standard UV image
+	const image = 'ghcr.io/astral-sh/uv:python3.12-bookworm';
+
+	// Build UV command (similar to regular uv command)
+	const scriptSource = args.script;
+	let command: string;
+
+	if (scriptSource.startsWith('http://') || scriptSource.startsWith('https://')) {
+		command = buildUvCommand(scriptSource, args);
+	} else if (scriptSource.includes('\n')) {
+		const encoded = Buffer.from(scriptSource).toString('base64');
+		const deps =
+			args.with_deps && args.with_deps.length > 0 ? args.with_deps.map((dep) => `--with ${dep}`).join(' ') + ' ' : '';
+		command = `echo "${encoded}" | base64 -d | uv run ${deps}${args.python ? `-p ${args.python}` : ''} -`;
+	} else {
+		command = buildUvCommand(scriptSource, args);
+	}
+
+	// Convert to scheduled run args
+	const scheduledRunArgs: ScheduledRunArgs = {
+		schedule: args.schedule,
+		suspend: args.suspend,
+		image,
+		command,
+		flavor: args.flavor,
+		env: args.env,
+		secrets: args.secrets,
+		timeout: args.timeout,
+		detach: args.detach,
+		namespace: args.namespace,
+	};
+
+	return scheduledRunCommand(scheduledRunArgs, client);
+}
+
+/**
+ * Build UV command with options
+ */
+function buildUvCommand(
+	script: string,
+	args: { with_deps?: string[]; python?: string; script_args?: string[] }
+): string {
+	const parts: string[] = ['uv', 'run'];
+
+	if (args.with_deps && args.with_deps.length > 0) {
+		for (const dep of args.with_deps) {
+			parts.push('--with', dep);
+		}
+	}
+
+	if (args.python) {
+		parts.push('-p', args.python);
+	}
+
+	parts.push(script);
+
+	if (args.script_args && args.script_args.length > 0) {
+		parts.push(...args.script_args);
+	}
+
+	return parts.join(' ');
+}
+
+/**
+ * Execute 'scheduled ps' command
+ * Lists scheduled jobs
+ */
+export async function scheduledPsCommand(args: ScheduledPsArgs, client: JobsApiClient): Promise<string> {
+	// Fetch all scheduled jobs
+	const allJobs = await client.listScheduledJobs(args.namespace);
+
+	// Filter jobs
+	let jobs = allJobs;
+
+	// Default: hide suspended jobs unless --all is specified
+	if (!args.all) {
+		jobs = jobs.filter((job) => !job.suspend);
+	}
+
+	// Format as markdown table
+	const table = formatScheduledJobsTable(jobs);
+
+	if (jobs.length === 0) {
+		if (args.all) {
+			return 'No scheduled jobs found.';
+		}
+		return 'No active scheduled jobs found. Use `{"all": true}` to show suspended jobs.';
+	}
+
+	return `**Scheduled Jobs (${jobs.length} of ${allJobs.length} total):**
+
+${table}`;
+}
+
+/**
+ * Execute 'scheduled inspect' command
+ * Gets details of a scheduled job
+ */
+export async function scheduledInspectCommand(args: ScheduledJobArgs, client: JobsApiClient): Promise<string> {
+	const job = await client.getScheduledJob(args.scheduled_job_id, args.namespace);
+	const formattedDetails = formatScheduledJobDetails(job);
+	return `**Scheduled Job Details:**\n\n${formattedDetails}`;
+}
+
+/**
+ * Execute 'scheduled delete' command
+ * Deletes a scheduled job
+ */
+export async function scheduledDeleteCommand(args: ScheduledJobArgs, client: JobsApiClient): Promise<string> {
+	await client.deleteScheduledJob(args.scheduled_job_id, args.namespace);
+
+	return `✓ Scheduled job ${args.scheduled_job_id} has been deleted.`;
+}
+
+/**
+ * Execute 'scheduled suspend' command
+ * Suspends a scheduled job
+ */
+export async function scheduledSuspendCommand(args: ScheduledJobArgs, client: JobsApiClient): Promise<string> {
+	await client.suspendScheduledJob(args.scheduled_job_id, args.namespace);
+
+	return `✓ Scheduled job ${args.scheduled_job_id} has been suspended.
+
+To resume: \`hf_jobs("scheduled resume", {"scheduled_job_id": "${args.scheduled_job_id}"})\``;
+}
+
+/**
+ * Execute 'scheduled resume' command
+ * Resumes a suspended scheduled job
+ */
+export async function scheduledResumeCommand(args: ScheduledJobArgs, client: JobsApiClient): Promise<string> {
+	await client.resumeScheduledJob(args.scheduled_job_id, args.namespace);
+
+	return `✓ Scheduled job ${args.scheduled_job_id} has been resumed.
+
+To inspect: \`hf_jobs("scheduled inspect", {"scheduled_job_id": "${args.scheduled_job_id}"})\``;
+}

package/src/jobs/commands/utils.ts

@@ -0,0 +1,158 @@
+import type { JobSpec } from '../types.js';
+import { parse as parseShellArgs } from 'shell-quote';
+
+interface EnvToken {
+	type: 'env';
+	key: string;
+}
+
+const SPECIAL_PARAMS = new Set(['*', '@', '#', '?', '!', '-', '_']);
+
+function isEnvToken(entry: unknown): entry is EnvToken {
+	return Boolean(entry && typeof entry === 'object' && (entry as EnvToken).type === 'env');
+}
+
+function formatEnvReference(key: string): string {
+	if (key === '') {
+		return '$';
+	}
+
+	if (key === '$') {
+		return '$$';
+	}
+
+	if (/^[A-Za-z0-9_]+$/.test(key)) {
+		return `$${key}`;
+	}
+
+	if (SPECIAL_PARAMS.has(key)) {
+		return `$${key}`;
+	}
+
+	return `\${${key}}`;
+}
+
+/**
+ * Parse timeout string (e.g., "5m", "2h", "30s") to seconds
+ */
+export function parseTimeout(timeout: string): number {
+	const timeUnits: Record<'s' | 'm' | 'h' | 'd', number> = {
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400,
+	};
+
+	const match = timeout.match(/^(\d+(?:\.\d+)?)(s|m|h|d)$/);
+	if (!match || !match[1] || !match[2]) {
+		// Try to parse as plain number (seconds)
+		const seconds = parseInt(timeout, 10);
+		if (!isNaN(seconds)) {
+			return seconds;
+		}
+		throw new Error(
+			`Invalid timeout format: "${timeout}". Use format like "5m", "2h", "30s", or plain seconds.`
+		);
+	}
+
+	const value = parseFloat(match[1]);
+	const unit = match[2] as 's' | 'm' | 'h' | 'd';
+	return Math.floor(value * timeUnits[unit]);
+}
+
+/**
+ * Detect if image is a Space URL and extract spaceId
+ * Returns { dockerImage } or { spaceId }
+ */
+export function parseImageSource(image: string): { dockerImage?: string; spaceId?: string } {
+	const spacePrefixes = [
+		'https://huggingface.co/spaces/',
+		'https://hf.co/spaces/',
+		'huggingface.co/spaces/',
+		'hf.co/spaces/',
+	];
+
+	for (const prefix of spacePrefixes) {
+		if (image.startsWith(prefix)) {
+			return { spaceId: image.substring(prefix.length) };
+		}
+	}
+
+	// Not a space, treat as docker image
+	return { dockerImage: image };
+}
+
+/**
+ * Parse command string or array into command array
+ * Uses shell-quote library for proper POSIX-compliant parsing
+ */
+export function parseCommand(command: string | string[]): { command: string[]; arguments?: string[] } {
+	// If already an array, return as-is
+	if (Array.isArray(command)) {
+		return { command, arguments: [] };
+	}
+
+	// Parse the command string using shell-quote for POSIX-compliant parsing
+	const parsed = parseShellArgs<EnvToken>(command, key => ({ type: 'env', key }));
+
+	// Convert parsed result to string array
+	// shell-quote can return various types (strings, objects for operators, etc.)
+	// We filter to only keep string arguments
+	const stringArgs: string[] = [];
+	for (const arg of parsed) {
+		if (typeof arg === 'string') {
+			stringArgs.push(arg);
+		} else if (isEnvToken(arg)) {
+			stringArgs.push(formatEnvReference(arg.key));
+		} else {
+			// If we encounter a non-string (like operators), throw an error
+			throw new Error(
+				`Unsupported shell syntax in command: "${command}". ` +
+					`Please use an array format for commands with complex shell operators, ` +
+					`or use simple quoted strings.`
+			);
+		}
+	}
+
+	if (stringArgs.length === 0) {
+		throw new Error(`Invalid command: "${command}". Command cannot be empty.`);
+	}
+
+	return { command: stringArgs, arguments: [] };
+}
+
+/**
+ * Create a JobSpec from run command arguments
+ */
+export function createJobSpec(args: {
+	image: string;
+	command: string | string[];
+	flavor?: string;
+	env?: Record<string, string>;
+	secrets?: Record<string, string>;
+	timeout?: string;
+}): JobSpec {
+	// Validate required fields
+	if (!args.image) {
+		throw new Error('image parameter is required. Provide a Docker image (e.g., "python:3.12") or Space URL.');
+	}
+	if (!args.command) {
+		throw new Error('command parameter is required. Provide a command as string or array.');
+	}
+
+	const imageSource = parseImageSource(args.image);
+	const { command, arguments: cmdArgs } = parseCommand(args.command);
+	const timeoutSeconds = args.timeout ? parseTimeout(args.timeout) : undefined;
+
+	const spec: JobSpec = {
+		...imageSource,
+		command,
+		arguments: cmdArgs,
+		flavor: args.flavor || 'cpu-basic',
+		environment: args.env || {}, // API requires object, not undefined
+		secrets: args.secrets || {}, // Same for secrets
+		timeoutSeconds,
+	};
+
+	return spec;
+}