@llmindset/hf-mcp 0.2.33 → 0.2.35

package/src/jobs/commands/run.ts

@@ -0,0 +1,135 @@
+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,
+		hfToken: token,
+	});
+
+	// 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,198 @@
+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,
+	token?: string
+): 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,
+		hfToken: token,
+	});
+
+	// 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,
+	token?: string
+): 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, token);
+}
+
+/**
+ * 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,191 @@
+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: [] };
+}
+
+/**
+ * Replace HF token placeholder with actual token if available
+ */
+function replaceTokenPlaceholder(value: string, hfToken?: string): string {
+	if (!hfToken) {
+		return value;
+	}
+
+	if (value === '$HF_TOKEN' || value === '${HF_TOKEN}') {
+		return hfToken;
+	}
+
+	return value;
+}
+
+function transformEnvMap(
+	map: Record<string, string> | undefined,
+	hfToken?: string
+): Record<string, string> | undefined {
+	if (!map) {
+		return undefined;
+	}
+
+	const transformedEntries = Object.entries(map).map<[string, string]>(([key, value]) => [
+		key,
+		replaceTokenPlaceholder(value, hfToken),
+	]);
+	return Object.fromEntries(transformedEntries) as Record<string, string>;
+}
+
+/**
+ * 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;
+	hfToken?: 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 environment = transformEnvMap(args.env, args.hfToken) || {};
+	const secrets = transformEnvMap(args.secrets, args.hfToken) || {};
+
+	const spec: JobSpec = {
+		...imageSource,
+		command,
+		arguments: cmdArgs,
+		flavor: args.flavor || 'cpu-basic',
+		environment,
+		secrets,
+		timeoutSeconds,
+	};
+
+	return spec;
+}

package/src/jobs/formatters.ts

@@ -0,0 +1,149 @@
+import type { JobInfo, ScheduledJobInfo } from './types.js';
+
+/**
+ * Truncate a string to a maximum length with ellipsis
+ */
+function truncate(str: string, maxLength: number): string {
+	if (str.length <= maxLength) {
+		return str;
+	}
+	return str.substring(0, maxLength - 3) + '...';
+}
+
+/**
+ * Format a date string to a readable format
+ */
+function formatDate(dateStr: string | undefined): string {
+	if (!dateStr) {
+		return 'N/A';
+	}
+	try {
+		const date = new Date(dateStr);
+		return date.toISOString().replace('T', ' ').substring(0, 19);
+	} catch {
+		return dateStr;
+	}
+}
+
+/**
+ * Format command array as a single string
+ */
+function formatCommand(command?: string[]): string {
+	if (!command || command.length === 0) {
+		return 'N/A';
+	}
+	return command.join(' ');
+}
+
+/**
+ * Get image/space identifier from job
+ */
+function getImageOrSpace(job: JobInfo | { dockerImage?: string; spaceId?: string }): string {
+	if (job.spaceId) {
+		return job.spaceId;
+	}
+	if (job.dockerImage) {
+		return job.dockerImage;
+	}
+	return 'N/A';
+}
+
+/**
+ * Format jobs as a markdown table
+ */
+export function formatJobsTable(jobs: JobInfo[]): string {
+	if (jobs.length === 0) {
+		return 'No jobs found.';
+	}
+
+	// Calculate dynamic ID column width - never truncate IDs!
+	const longestIdLength = Math.max(...jobs.map((job) => job.id.length));
+	const idColumnWidth = Math.max(longestIdLength, 'JOB ID'.length);
+
+	// Define column widths
+	const colWidths = {
+		id: idColumnWidth,
+		image: 20,
+		command: 30,
+		created: 19,
+		status: 12,
+	};
+
+	// Build header
+	const header = `| ${'JOB ID'.padEnd(colWidths.id)} | ${'IMAGE/SPACE'.padEnd(colWidths.image)} | ${'COMMAND'.padEnd(colWidths.command)} | ${'CREATED'.padEnd(colWidths.created)} | ${'STATUS'.padEnd(colWidths.status)} |`;
+	const separator = `|${'-'.repeat(colWidths.id + 2)}|${'-'.repeat(colWidths.image + 2)}|${'-'.repeat(colWidths.command + 2)}|${'-'.repeat(colWidths.created + 2)}|${'-'.repeat(colWidths.status + 2)}|`;
+
+	// Build rows
+	const rows = jobs.map((job) => {
+		const id = job.id; // Never truncate IDs!
+		const image = truncate(getImageOrSpace(job), colWidths.image);
+		const command = truncate(formatCommand(job.command), colWidths.command);
+		const created = truncate(formatDate(job.createdAt), colWidths.created);
+		const status = truncate(job.status.stage, colWidths.status);
+
+		return `| ${id.padEnd(colWidths.id)} | ${image.padEnd(colWidths.image)} | ${command.padEnd(colWidths.command)} | ${created.padEnd(colWidths.created)} | ${status.padEnd(colWidths.status)} |`;
+	});
+
+	return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format scheduled jobs as a markdown table
+ */
+export function formatScheduledJobsTable(jobs: ScheduledJobInfo[]): string {
+	if (jobs.length === 0) {
+		return 'No scheduled jobs found.';
+	}
+
+	// Calculate dynamic ID column width - never truncate IDs!
+	const longestIdLength = Math.max(...jobs.map((job) => job.id.length));
+	const idColumnWidth = Math.max(longestIdLength, 'ID'.length);
+
+	// Define column widths
+	const colWidths = {
+		id: idColumnWidth,
+		schedule: 12,
+		image: 18,
+		command: 25,
+		lastRun: 19,
+		nextRun: 19,
+		suspend: 9,
+	};
+
+	// Build header
+	const header = `| ${'ID'.padEnd(colWidths.id)} | ${'SCHEDULE'.padEnd(colWidths.schedule)} | ${'IMAGE/SPACE'.padEnd(colWidths.image)} | ${'COMMAND'.padEnd(colWidths.command)} | ${'LAST RUN'.padEnd(colWidths.lastRun)} | ${'NEXT RUN'.padEnd(colWidths.nextRun)} | ${'SUSPENDED'.padEnd(colWidths.suspend)} |`;
+	const separator = `|${'-'.repeat(colWidths.id + 2)}|${'-'.repeat(colWidths.schedule + 2)}|${'-'.repeat(colWidths.image + 2)}|${'-'.repeat(colWidths.command + 2)}|${'-'.repeat(colWidths.lastRun + 2)}|${'-'.repeat(colWidths.nextRun + 2)}|${'-'.repeat(colWidths.suspend + 2)}|`;
+
+	// Build rows
+	const rows = jobs.map((job) => {
+		const id = job.id; // Never truncate IDs!
+		const schedule = truncate(job.schedule, colWidths.schedule);
+		const image = truncate(getImageOrSpace(job.jobSpec), colWidths.image);
+		const command = truncate(formatCommand(job.jobSpec.command), colWidths.command);
+		const lastRun = truncate(formatDate(job.lastRun), colWidths.lastRun);
+		const nextRun = truncate(formatDate(job.nextRun), colWidths.nextRun);
+		const suspend = job.suspend ? 'Yes' : 'No';
+
+		return `| ${id.padEnd(colWidths.id)} | ${schedule.padEnd(colWidths.schedule)} | ${image.padEnd(colWidths.image)} | ${command.padEnd(colWidths.command)} | ${lastRun.padEnd(colWidths.lastRun)} | ${nextRun.padEnd(colWidths.nextRun)} | ${suspend.padEnd(colWidths.suspend)} |`;
+	});
+
+	return [header, separator, ...rows].join('\n');
+}
+
+/**
+ * Format job details as JSON in a markdown code block
+ */
+export function formatJobDetails(jobs: JobInfo | JobInfo[]): string {
+	const jobArray = Array.isArray(jobs) ? jobs : [jobs];
+	const json = JSON.stringify(jobArray, null, 2);
+	return `\`\`\`json\n${json}\n\`\`\``;
+}
+
+/**
+ * Format scheduled job details as JSON in a markdown code block
+ */
+export function formatScheduledJobDetails(jobs: ScheduledJobInfo | ScheduledJobInfo[]): string {
+	const jobArray = Array.isArray(jobs) ? jobs : [jobs];
+	const json = JSON.stringify(jobArray, null, 2);
+	return `\`\`\`json\n${json}\n\`\`\``;
+}