@alchemint/fuse-cli 0.0.0-stage → 0.1.0

package/src/video.mjs

@@ -0,0 +1,349 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import {
+  CliError,
+  need,
+  id,
+  digest,
+  readJson,
+  writeJson,
+  exists,
+  subject,
+  sameSubject,
+  duration,
+  pause,
+  withWriter,
+  errorData,
+} from './core.mjs';
+
+export const terminal = (status) =>
+  ['succeeded', 'failed', 'cancelled'].includes(status);
+export const resultSummary = (row) => ({
+  job_id: row.job_id,
+  result_id: row.id,
+  shot_id: row.shot_id,
+  status: row.status,
+  model: row.model,
+  provider_phase: row.provider_phase,
+  failure_class: row.failure_class,
+  error: row.error,
+  has_output: Boolean(row.output_url),
+  source: 'creative.shots.results',
+});
+export const profileSummary = (profile) => ({
+  pricing_key: profile.pricing_key,
+  model: profile.model,
+  stage: profile.stage,
+  display_label: profile.display_label,
+  availability: profile.availability,
+  allowed_resolutions: profile.allowed_resolutions,
+  allowed_durations: profile.allowed_durations,
+  // DEV-2175：可調步數的模型列出範圍與預設；沒宣告就是固定步數，請求不能帶 params.steps。
+  ...(profile.capability.steps ? { steps: profile.capability.steps } : {}),
+});
+export async function models(action, options, { client }) {
+  const data = await client.get('/generation/options');
+  const profiles = data.profiles.filter(
+    (profile) =>
+      !options.stage ||
+      profile.stage === (options.stage === 'video' ? 'i2v' : options.stage),
+  );
+  if (action === 'list')
+    return {
+      profiles: options.full ? profiles : profiles.map(profileSummary),
+    };
+  const profile = profiles.find(
+    (item) =>
+      item.pricing_key === need(options.key, '--key (exact pricing key)'),
+  );
+  if (!profile)
+    throw new CliError(
+      2,
+      'PROFILE_NOT_FOUND',
+      'This exact pricing key is not in the current options.',
+    );
+  return profile;
+}
+export async function observeVideo(client, receipt) {
+  const creative = await client.get(
+    `/storyboards/${id(receipt.creative_id, 'creative_id')}`,
+  );
+  const shot = creative.shots.find(
+    (item) => item.id === receipt.request.shot_id,
+  );
+  const row = shot?.results.find((item) =>
+    receipt.accepted
+      ? item.job_id === receipt.accepted.job_id &&
+        item.id === receipt.accepted.result_id
+      : false,
+  );
+  if (!receipt.accepted) return null;
+  if (!row)
+    throw new CliError(
+      4,
+      'JOB_NOT_VISIBLE',
+      'The bound Job/Take is not visible in its Creative/Shot. No replacement was submitted.',
+    );
+  return resultSummary(row);
+}
+// A plain video submission posts a CreateJob video body to /generation/jobs. Submitting a
+// Shot version posts the same body shape to that version; its stage follows the version.
+export function validateIntent(request, key, endpoint = '/generation/jobs') {
+  const stages = endpoint === '/generation/jobs' ? ['i2v'] : ['t2i', 'i2v'];
+  if (
+    !stages.includes(request.stage) ||
+    !Number.isInteger(request.shot_id) ||
+    request.shot_id < 1
+  )
+    throw new CliError(
+      2,
+      'INVALID_SHOT',
+      endpoint === '/generation/jobs'
+        ? 'The request must be a CreateJob video body: stage "i2v" and the server numeric shot_id.'
+        : 'The request must carry the version stage (t2i or i2v) and the server numeric shot_id.',
+    );
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      key,
+    )
+  )
+    throw new CliError(
+      2,
+      'INVALID_IDEMPOTENCY_KEY',
+      'Use a UUID idempotency key.',
+    );
+}
+export async function acceptVideo(client, receipt, file) {
+  if (digest(receipt.request) !== receipt.request_sha256)
+    throw new CliError(
+      2,
+      'INTENT_CHANGED',
+      'Stored request hash does not match its body.',
+    );
+  if (receipt.accepted) return receipt;
+  // This file already contains the exact body/key/subject before the network call.
+  receipt.state = 'submitting';
+  await writeJson(file, receipt);
+  try {
+    const reply = await client.post(
+      receipt.endpoint ?? '/generation/jobs',
+      receipt.request,
+      { headers: { 'X-Idempotency-Key': receipt.idempotency_key } },
+    );
+    // Shot video acceptance returns its result rows. Only the explicit replay
+    // envelope carries order/results when this same key is replayed.
+    const replayed = reply?.replayed === true;
+    const row = replayed ? reply.results?.[0] : reply?.[0];
+    if (
+      !row?.job_id ||
+      !row?.id ||
+      row.shot_id !== receipt.request.shot_id ||
+      (replayed && reply.order?.id !== row.job_id)
+    ) {
+      throw new CliError(
+        5,
+        'RESPONSE_UNKNOWN',
+        'The acceptance response did not identify the expected Job/Take. Reconcile this exact key.',
+      );
+    }
+    receipt.accepted = {
+      job_id: row.job_id,
+      result_id: row.id,
+      shot_id: row.shot_id,
+      replayed,
+    };
+    receipt.state = 'accepted';
+    receipt.observation = resultSummary(row);
+    delete receipt.error;
+    await writeJson(file, receipt);
+    return receipt;
+  } catch (error) {
+    if (!(error instanceof CliError))
+      error = new CliError(
+        5,
+        'RECEIPT_UNKNOWN',
+        'Could not finish recording acceptance. Reconcile the saved body and key.',
+        { receipt: file },
+      );
+    receipt.state =
+      error.exit === 5
+        ? 'unknown'
+        : error.exit === 3
+          ? 'auth_required'
+          : error.http_status === 429 ||
+              error.code === 'CONCURRENCY_LIMIT_REACHED'
+            ? 'waiting'
+            : 'rejected';
+    receipt.error = errorData(error);
+    await writeJson(file, receipt);
+    error.receipt = file;
+    throw error;
+  }
+}
+export async function videoSubmit(options, context) {
+  if (options['retry-rejected'] && !options.resume)
+    throw new CliError(
+      2,
+      'RESUME_REQUIRED',
+      '--retry-rejected requires --resume and the original receipt.',
+    );
+  const file = path.resolve(need(options.receipt, '--receipt'));
+  return withWriter(`${file}.lock`, async () => {
+    const owner = await subject(context.client);
+    let receipt;
+    if (await exists(file)) {
+      receipt = await readJson(file);
+      if (receipt.schema_version !== 1 || receipt.kind !== 'video')
+        throw new CliError(
+          2,
+          'WRONG_RECEIPT',
+          'Expected a version 1 video receipt.',
+        );
+      validateIntent(receipt.request, receipt.idempotency_key);
+      if (digest(receipt.request) !== receipt.request_sha256)
+        throw new CliError(
+          2,
+          'INTENT_CHANGED',
+          'The saved video request changed.',
+        );
+      sameSubject(receipt, owner);
+      if (!options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_EXISTS',
+          'Use --resume to reconcile this fixed intent; a new generation needs a new receipt.',
+        );
+      if (receipt.accepted) {
+        receipt.observation = await observeVideo(context.client, receipt);
+        await writeJson(file, receipt);
+        return {
+          receipt: file,
+          ...receipt.accepted,
+          observation: receipt.observation,
+        };
+      }
+      if (receipt.state === 'rejected') {
+        if (!options['retry-rejected'])
+          throw new CliError(
+            4,
+            'INTENT_REJECTED',
+            'Review the rejection before explicitly retrying this unchanged intent with --resume --retry-rejected.',
+            { receipt: file },
+          );
+        receipt.rejected_attempts = [
+          ...(receipt.rejected_attempts || []),
+          { observed_at: new Date().toISOString(), error: receipt.error },
+        ];
+      }
+      await observeVideo(context.client, receipt);
+    } else {
+      if (options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_NOT_FOUND',
+          'Resume requires the existing receipt file.',
+        );
+      const request = await readJson(
+        need(options['request-file'], '--request-file'),
+      );
+      const key = options['idempotency-key'] || randomUUID();
+      validateIntent(request, key);
+      receipt = {
+        schema_version: 1,
+        kind: 'video',
+        ...owner,
+        creative_id: need(options.creative, '--creative'),
+        idempotency_key: key,
+        request,
+        request_sha256: digest(request),
+        state: 'prepared',
+        created_at: new Date().toISOString(),
+      };
+      const creative = await context.client.get(
+        `/storyboards/${id(receipt.creative_id)}`,
+      );
+      if (!creative.shots.some((shot) => shot.id === request.shot_id))
+        throw new CliError(
+          2,
+          'TARGET_MISMATCH',
+          'The Shot does not belong to this Creative.',
+        );
+      await writeJson(file, receipt, true);
+    }
+    await acceptVideo(context.client, receipt, file);
+    return {
+      receipt: file,
+      ...receipt.accepted,
+      observation: receipt.observation,
+    };
+  });
+}
+// 還在 FUSE 排隊的鏡頭影片，或已派到自家機器的開源 take，都由同一個端點取消（DEV-2189）；
+// 伺服器判斷可不可以、退不退點，CLI 不另外推斷。
+export const cancelJob = (client, jobId) =>
+  client.post(`/generation/jobs/${id(jobId, 'job')}/cancel`);
+export async function cancel(options, context) {
+  if (!options.receipt)
+    return cancelJob(context.client, need(options.job, '--receipt or --job'));
+  const receipt = await readJson(options.receipt);
+  sameSubject(receipt, await subject(context.client));
+  if (!receipt.accepted)
+    throw new CliError(
+      5,
+      'ACCEPTANCE_UNKNOWN',
+      'No canonical Job is recorded. Use video submit --resume with this receipt.',
+      { receipt: options.receipt },
+    );
+  return {
+    ...(await cancelJob(context.client, receipt.accepted.job_id)),
+    receipt: options.receipt,
+  };
+}
+export async function job(action, options, context) {
+  let receipt;
+  if (options.receipt) {
+    receipt = await readJson(options.receipt);
+    sameSubject(receipt, await subject(context.client));
+  } else
+    receipt = {
+      creative_id: need(options.creative, '--creative'),
+      request: { shot_id: Number(need(options.shot, '--shot')) },
+      accepted: {
+        job_id: need(options.job, '--job'),
+        result_id: need(options.result, '--result'),
+      },
+    };
+  if (!receipt.accepted)
+    throw new CliError(
+      5,
+      'ACCEPTANCE_UNKNOWN',
+      'No canonical Job is recorded. Use video submit --resume with this receipt.',
+      { receipt: options.receipt },
+    );
+  const deadline = Date.now() + duration(options.timeout);
+  let previous;
+  do {
+    const row = await observeVideo(context.client, receipt);
+    if (action === 'show') return row;
+    const key = JSON.stringify(row);
+    if (key !== previous) {
+      context.event('job_status', row);
+      previous = key;
+    }
+    if (terminal(row.status)) {
+      if (row.status !== 'succeeded')
+        throw new CliError(
+          7,
+          'JOB_FAILED',
+          'The server reports a failed or cancelled Job.',
+          { data: row },
+        );
+      return row;
+    }
+    if (Date.now() >= deadline)
+      throw new CliError(6, 'WATCH_TIMEOUT', 'The Job is still nonterminal.', {
+        data: row,
+      });
+    await pause(Math.min(5000, deadline - Date.now()), context.signal);
+  } while (true);
+}