@hubfluencer/mcp 0.15.0 → 0.17.0

package/src/doctor.ts

@@ -0,0 +1,96 @@
+import { clientFromEnv, type HubfluencerClient } from "./client.js";
+import { readStoredCredentials } from "./credentials.js";
+import type { ToolProfile } from "./tool-profile.js";
+import { VERSION } from "./version.js";
+
+type DoctorClient = Pick<HubfluencerClient, "get" | "origin">;
+
+export type DoctorReport = {
+	ok: true;
+	version: string;
+	profile: ToolProfile;
+	api_origin: string;
+	credential_source: "environment" | "device_login";
+	checks: {
+		credentials: "ok";
+		secure_origin: "ok";
+		api_connection: "ok";
+		credits_read: "ok";
+	};
+	credits: unknown;
+	input_directory: string;
+	output_directory: string;
+	next: string;
+};
+
+function credentialSource(): DoctorReport["credential_source"] {
+	if (process.env.HUBFLUENCER_API_TOKEN) return "environment";
+	if (readStoredCredentials().token) return "device_login";
+	throw new Error(
+		`Not connected. Run \`npx -y @hubfluencer/mcp@${VERSION} login\` or set HUBFLUENCER_API_TOKEN.`,
+	);
+}
+
+function extractCredits(response: unknown): unknown {
+	if (!response || typeof response !== "object" || Array.isArray(response)) {
+		return null;
+	}
+	const record = response as Record<string, unknown>;
+	const data =
+		record.data &&
+		typeof record.data === "object" &&
+		!Array.isArray(record.data)
+			? (record.data as Record<string, unknown>)
+			: record;
+	return (
+		data.spendable_credits ?? data.credits ?? data.remaining_credits ?? null
+	);
+}
+
+export async function inspectDoctor(
+	profile: ToolProfile,
+	client: DoctorClient = clientFromEnv(),
+): Promise<DoctorReport> {
+	const source = credentialSource();
+	const response = await client.get<unknown>("/studio/credits");
+
+	return {
+		ok: true,
+		version: VERSION,
+		profile,
+		api_origin: client.origin,
+		credential_source: source,
+		checks: {
+			credentials: "ok",
+			secure_origin: "ok",
+			api_connection: "ok",
+			credits_read: "ok",
+		},
+		credits: extractCredits(response),
+		input_directory: process.env.HUBFLUENCER_INPUT_DIR || process.cwd(),
+		output_directory: process.env.HUBFLUENCER_OUTPUT_DIR || process.cwd(),
+		next: 'Ask your agent to call make_video({prompt:"...",dry_run:true}) for a free quote before approving spend.',
+	};
+}
+
+export async function runDoctor(
+	profile: ToolProfile,
+	json = false,
+): Promise<void> {
+	const report = await inspectDoctor(profile);
+	if (json) {
+		console.log(JSON.stringify(report, null, 2));
+		return;
+	}
+
+	console.log(`✓ Hubfluencer MCP ${report.version}`);
+	console.log(`✓ profile: ${report.profile}`);
+	console.log(
+		`✓ credentials: ${report.credential_source === "environment" ? "HUBFLUENCER_API_TOKEN" : "device login"}`,
+	);
+	console.log(`✓ API connection: ${report.api_origin}`);
+	console.log(`✓ credits endpoint: ${String(report.credits ?? "available")}`);
+	console.log(`✓ local reads confined to: ${report.input_directory}`);
+	console.log(`✓ MP4 writes confined to: ${report.output_directory}`);
+	console.log(`Next: ${report.next}`);
+}

package/src/generation-summary.ts

@@ -0,0 +1,262 @@
+import { z } from "zod";
+
+export const generationStatuses = [
+	"idle",
+	"queued",
+	"running",
+	"needs_input",
+	"completed",
+	"failed",
+	"cancelled",
+] as const;
+
+export const knownGenerationActionTypes = [
+	"start_generation",
+	"cancel_generation",
+	"retry_generation",
+	"abandon_generation",
+	"edit_required_input",
+	"review_spend_cap",
+	"download_result",
+	"review_scenes",
+	"review_scene",
+	"review_narration",
+	"review_audio",
+	"review_project",
+] as const;
+
+export type KnownGenerationActionType =
+	(typeof knownGenerationActionTypes)[number];
+
+const detailsSchema = z.record(z.string(), z.unknown());
+
+export const generationActionSchema = z
+	.object({
+		type: z.string(),
+		label: z.string(),
+		destructive: z.boolean(),
+		step_key: z.string().nullable(),
+	})
+	.passthrough();
+
+const generationFailureSchema = z
+	.object({
+		code: z.string(),
+		message: z.string(),
+		details: detailsSchema,
+	})
+	.passthrough();
+
+export const generationSummarySchema = z
+	.object({
+		run_id: z.string().uuid().nullable(),
+		workflow: z.string().nullable(),
+		workflow_version: z.number().int().nullable(),
+		revision: z.number().int().nullable(),
+		status: z.enum(generationStatuses),
+		settling: z.boolean(),
+		phase: z.string(),
+		label: z.string(),
+		progress: z
+			.object({
+				completed: z.number().int().nonnegative(),
+				total: z.number().int().nonnegative(),
+				percent: z.number().int().min(0).max(100),
+			})
+			.passthrough(),
+		current_step: z
+			.object({
+				key: z.string(),
+				type: z.string(),
+				status: z.string(),
+				attempt: z.number().int().nonnegative(),
+				max_attempts: z.number().int().positive(),
+			})
+			.passthrough()
+			.nullable(),
+		blockers: z.array(
+			z
+				.object({
+					code: z.string(),
+					message: z.string(),
+					step_key: z.string().nullable(),
+					details: detailsSchema,
+				})
+				.passthrough(),
+		),
+		available_actions: z.array(generationActionSchema),
+		failure: generationFailureSchema.nullable(),
+		cost: z
+			.object({
+				quoted_credits: z.number().int().nonnegative(),
+				charged_credits: z.number().int().nonnegative(),
+				refunded_credits: z.number().int().nonnegative(),
+				net_credits: z.number().int().nonnegative(),
+				max_credits: z.number().int().nonnegative(),
+			})
+			.passthrough(),
+		timing: z
+			.object({
+				started_at: z.string().nullable(),
+				updated_at: z.string().nullable(),
+				deadline_at: z.string().nullable(),
+				poll_after_ms: z.number().int().nonnegative().nullable(),
+			})
+			.passthrough(),
+	})
+	.passthrough()
+	.superRefine((summary, context) => {
+		if (summary.status === "idle") {
+			if (
+				summary.run_id !== null ||
+				summary.workflow !== null ||
+				summary.workflow_version !== null ||
+				summary.revision !== null
+			) {
+				context.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: "idle summaries cannot carry workflow identity",
+				});
+			}
+			return;
+		}
+
+		if (
+			summary.run_id === null ||
+			summary.workflow === null ||
+			summary.workflow_version !== 1 ||
+			summary.revision === null
+		) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				message:
+					"non-idle summaries require canonical workflow version 1 identity",
+			});
+		}
+	});
+
+export type GenerationSummary = z.infer<typeof generationSummarySchema>;
+
+const knownActionTypes = new Set<string>(knownGenerationActionTypes);
+
+export function knownGenerationActionTypesFrom(
+	summary: GenerationSummary,
+): KnownGenerationActionType[] {
+	return summary.available_actions
+		.map((action) => action.type)
+		.filter((type): type is KnownGenerationActionType =>
+			knownActionTypes.has(type),
+		);
+}
+
+export interface GenerationProductOperation {
+	tool: string;
+	required_fences: readonly string[];
+}
+
+const operation = (
+	tool: string,
+	required_fences: readonly string[] = [],
+): GenerationProductOperation => ({ tool, required_fences });
+
+/**
+ * MCP-side contract mirror of the API's product action table. Availability
+ * always comes from the summary; this table only selects the product tool that
+ * can carry out an already-advertised intent.
+ */
+export const generationProductOperations = {
+	"short:short.generation:cancel_generation": operation(
+		"cancel_short_generation",
+		["generation_run_id", "idempotency_key"],
+	),
+	"short:*:start_generation": operation("generate_short", ["idempotency_key"]),
+	"short:*:download_result": operation("download_result"),
+	"short:*:edit_required_input": operation("provide_generation_input", [
+		"generation_run_id",
+		"generation_revision",
+		"step_key",
+		"idempotency_key",
+	]),
+	"short:*:review_spend_cap": operation("provide_generation_input", [
+		"generation_run_id",
+		"generation_revision",
+		"step_key",
+		"idempotency_key",
+	]),
+	"editor:editor.autopilot:cancel_generation": operation("cancel_autopilot", [
+		"generation_run_id",
+		"idempotency_key",
+	]),
+	"editor:editor.scene.generate:cancel_generation": operation(
+		"cancel_segment_generation",
+		["expected_generation_claim_token", "idempotency_key"],
+	),
+	"editor:editor.scene.regenerate:cancel_generation": operation(
+		"cancel_segment_generation",
+		["expected_generation_claim_token", "idempotency_key"],
+	),
+	"editor:editor.scene.generate:retry_generation": operation(
+		"retry_segment_generation",
+		["generation_run_id", "generation_revision", "step_key", "idempotency_key"],
+	),
+	"editor:editor.scene.regenerate:retry_generation": operation(
+		"retry_segment_generation",
+		["generation_run_id", "generation_revision", "step_key", "idempotency_key"],
+	),
+	"editor:editor.render:retry_generation": operation("retry_render", [
+		"generation_revision",
+		"idempotency_key",
+	]),
+	"editor:editor.render.retry:retry_generation": operation("retry_render", [
+		"generation_revision",
+		"idempotency_key",
+	]),
+	"editor:editor.batch:retry_generation": operation("retry_editor_batch", [
+		"generation_run_id",
+		"generation_revision",
+		"idempotency_key",
+	]),
+	"editor:editor.batch:cancel_generation": operation("cancel_editor_batch", [
+		"generation_run_id",
+		"idempotency_key",
+	]),
+	"editor:*:start_generation": operation("start_autopilot", [
+		"idempotency_key",
+	]),
+	"editor:*:edit_required_input": operation("provide_generation_input", [
+		"generation_run_id",
+		"generation_revision",
+		"step_key",
+		"idempotency_key",
+	]),
+	"editor:*:review_spend_cap": operation("provide_generation_input", [
+		"generation_run_id",
+		"generation_revision",
+		"step_key",
+		"idempotency_key",
+	]),
+	"editor:*:download_result": operation("download_result"),
+	"editor:*:review_scenes": operation("get_editor"),
+	"editor:*:review_scene": operation("get_editor"),
+	"editor:*:review_narration": operation("get_editor"),
+	"editor:*:review_audio": operation("get_editor"),
+	"editor:*:review_project": operation("get_editor"),
+	"editor:*:abandon_generation": operation("get_editor"),
+} as const satisfies Record<string, GenerationProductOperation>;
+
+export function generationProductOperation(
+	product: "editor" | "short",
+	workflow: string | null,
+	actionType: KnownGenerationActionType,
+): GenerationProductOperation | undefined {
+	const exact = `${product}:${workflow ?? ""}:${actionType}`;
+	const wildcard = `${product}:*:${actionType}`;
+	return (
+		generationProductOperations[
+			exact as keyof typeof generationProductOperations
+		] ??
+		generationProductOperations[
+			wildcard as keyof typeof generationProductOperations
+		]
+	);
+}