@alchemint/fuse-cli 0.0.0-stage → 0.1.0

package/src/creative.mjs

@@ -0,0 +1,379 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { CliError, need, id, readJson, writeJson, digest } from './core.mjs';
+import { recordedMutation } from './mutations.mjs';
+
+const GENERATION_TARGETS = ['script', 'video'];
+const ENTRIES = ['idea', 'script'];
+
+/** Each Shot is one video: its takes and the currently selected take. */
+export const creativeSummary = (row) => ({
+  creative_id: row.id,
+  title: row.title,
+  status: row.status,
+  versions: row.versions.map((version) => ({
+    version_id: version.id,
+    script_content_revision: version.script_content_revision,
+  })),
+  shots: row.shots.map((shot) => ({
+    shot_id: shot.id,
+    version_id: shot.version_id,
+    sequence: shot.sequence,
+    duration_sec: shot.duration_sec,
+    selected_result_id: shot.selected_result_id,
+    takes: shot.results
+      .filter((take) => take.stage === 'i2v')
+      .map((take) => ({
+        result_id: take.id,
+        job_id: take.job_id,
+        status: take.status,
+        model: take.model,
+      })),
+  })),
+});
+const creativeCardSummary = (row) => ({
+  creative_id: row.id,
+  title: row.title,
+  status: row.status,
+  shot_count: row.shot_count,
+});
+/**
+ * First generation: an idea starts with pitch_package and then writes each Episode's script;
+ * a pasted script is imported verbatim. Video continues to each Episode's storyboard.
+ */
+const initialActivitySummary = (activity) => ({
+  activity_id: activity.activity_id,
+  status: activity.status,
+  phase: activity.phase,
+  generation_entry: activity.generation_entry,
+  generation_target: activity.generation_target,
+  completed_milestones: activity.completed_milestones,
+  episodes: activity.episodes.map((episode) => ({
+    episode_id: episode.episode_id,
+    title: episode.title,
+    script_status: episode.script_status,
+    script_accepted: episode.script_accepted,
+    storyboard_status: episode.storyboard_status,
+    storyboard_accepted: episode.storyboard_accepted,
+  })),
+});
+export async function creative(action, options, context) {
+  if (action === 'create') {
+    if (options['seed-file'] && options['request-file'])
+      throw new CliError(
+        2,
+        'AMBIGUOUS_INPUT',
+        'Choose --seed-file or --request-file.',
+      );
+    if (
+      options['request-file'] &&
+      (options['generation-target'] || options.entry)
+    )
+      throw new CliError(
+        2,
+        'AMBIGUOUS_INPUT',
+        'The CreateStoryboard request file already carries generation_target and entry.',
+      );
+    let body;
+    if (options['seed-file'] && !options.resume) {
+      const target = need(
+        options['generation-target'],
+        '--generation-target script|video',
+      );
+      if (!GENERATION_TARGETS.includes(target))
+        throw new CliError(
+          2,
+          'INVALID_GENERATION_TARGET',
+          'Use --generation-target script (stops after the Episode scripts) or video (continues to the storyboards).',
+        );
+      const entry = need(options.entry, '--entry idea|script');
+      if (!ENTRIES.includes(entry))
+        throw new CliError(
+          2,
+          'INVALID_ENTRY',
+          'Use --entry idea (the seed is developed into a story) or script (the seed is a written script imported verbatim).',
+        );
+      body = {
+        input_text: await readFile(options['seed-file'], 'utf8'),
+        generation_target: target,
+        entry,
+      };
+    } else if (!options.resume)
+      body = await readJson(
+        need(options['request-file'], '--seed-file or --request-file'),
+      );
+    const result = await recordedMutation(
+      'creative_create',
+      '/storyboards',
+      body,
+      options,
+      context,
+      (row) => ({ creative_id: row.id, activity_id: row.activity_id }),
+    );
+    const activity = await context.client.get(
+      `/generation/activities/initial/${id(result.creative_id)}`,
+    );
+    return {
+      ...result,
+      initial_activity: activity ? initialActivitySummary(activity) : null,
+    };
+  }
+  if (action === 'list') {
+    if (options.cursor)
+      throw new CliError(
+        2,
+        'UNSUPPORTED_PAGINATION',
+        'The Creative summary API has no cursor; use --page and --limit for local projection.',
+      );
+    const rows = await context.client.get('/storyboards');
+    const limit = Number(options.limit || 20),
+      page = Number(options.page || 1);
+    if (
+      !Number.isInteger(limit) ||
+      limit < 1 ||
+      !Number.isInteger(page) ||
+      page < 1
+    )
+      throw new CliError(
+        2,
+        'INVALID_PAGE',
+        'page and limit must be positive integers.',
+      );
+    const selected = rows.slice((page - 1) * limit, page * limit);
+    return {
+      items: options.full ? selected : selected.map(creativeCardSummary),
+      page,
+      limit,
+      total: rows.length,
+      pagination: 'client_projection_of_server_summary',
+    };
+  }
+  const endpoint = `/storyboards/${id(options.creative, '--creative')}`;
+  if (action === 'rename')
+    await context.client.request('PATCH', endpoint, {
+      title: need(options.name, '--name'),
+    });
+  else if (action !== 'show')
+    throw new CliError(
+      2,
+      'UNKNOWN_COMMAND',
+      'Use creative create, list, show, or rename.',
+    );
+  const row = await context.client.get(endpoint);
+  if (options.out) {
+    await writeJson(options.out, row, true);
+    return { creative_id: row.id, file: path.resolve(options.out) };
+  }
+  return options.full ? row : creativeSummary(row);
+}
+/** 第幾集是 Script 文件裡的順序，從 1 起，與網頁的「第 N 集」相同；editing 是正持有那一集分集鎖的人。 */
+const episodeRows = (view) =>
+  view.document.episodes.map((episode, index) => ({
+    number: index + 1,
+    episode_id: episode.id,
+    title: episode.title,
+    shot_count: episode.shots.length,
+    editing:
+      view.episode_locks.find((lock) => lock.episode_id === episode.id)
+        ?.holder ?? null,
+  }));
+/** --episode 收集數或 episode_id；集數依這一次讀回的順序解析，寫入時送的是 episode_id。 */
+function episodeOf(view, value) {
+  const rows = episodeRows(view);
+  const row = /^\d+$/.test(value)
+    ? rows[Number(value) - 1]
+    : rows.find((item) => item.episode_id === value);
+  if (!row)
+    throw new CliError(
+      2,
+      'EPISODE_NOT_FOUND',
+      `This Script has ${rows.length} Episode(s): use --episode 1-${rows.length} or an episode_id from script get.`,
+    );
+  return row;
+}
+export async function script(action, sub, options, context) {
+  const endpoint = `/storyboards/${id(options.creative, '--creative')}/versions/${id(options['version-id'], '--version-id')}/script`;
+  const located = (view, row) => ({
+    creative_id: options.creative,
+    version_id: options['version-id'],
+    content_revision: view.content_revision,
+    ...row,
+  });
+  if (action === 'episode') {
+    // 集指令（DEV-2097）：新增與調整順序不改任何一集的內容；改集名時那一集正由別人編輯就停下，回報是誰。
+    let view, episodeId;
+    if (sub === 'add') {
+      view = await context.client.post(`${endpoint}/episodes`, {
+        title: need(options.name, '--name'),
+      });
+      // 新增的一集接在最後；回應是同一個交易裡讀回的 Script。
+      episodeId = view.document.episodes.at(-1).id;
+    } else if (sub === 'rename' || sub === 'move') {
+      let body;
+      if (sub === 'rename') body = { title: need(options.name, '--name') };
+      else {
+        const to = need(options.to, '--to N');
+        if (!/^[1-9]\d*$/.test(to))
+          throw new CliError(
+            2,
+            'INVALID_EPISODE_NUMBER',
+            'Use --to with the Episode number it becomes, from 1.',
+          );
+        body = { position: Number(to) - 1 };
+      }
+      const episode = need(options.episode, '--episode N|UUID');
+      episodeId = episodeOf(
+        await context.client.get(endpoint),
+        episode,
+      ).episode_id;
+      const target = `${endpoint}/episodes/${episodeId}`;
+      view =
+        sub === 'rename'
+          ? await context.client.request('PATCH', target, body)
+          : await context.client.post(`${target}/move`, body);
+    } else
+      throw new CliError(
+        2,
+        'UNKNOWN_COMMAND',
+        'Use script episode add, rename, or move.',
+      );
+    return {
+      ...located(view, episodeOf(view, episodeId)),
+      episodes: episodeRows(view),
+    };
+  }
+  if (action === 'put') {
+    // DEV-2096：一次存一集。別人正在編輯那一集時不寫入，回報是誰；CLI 是一次性的寫入，
+    // 存完就放掉那一集的鎖，不留給之後。
+    const target = need(options.episode, '--episode N|UUID');
+    const body = await readJson(
+      need(options.file, '--file (episode write body)'),
+    );
+    const { episode_id: episodeId } = episodeOf(
+      await context.client.get(endpoint),
+      target,
+    );
+    const episode = `${endpoint}/episodes/${episodeId}`;
+    const saved = await context.client.request('PUT', episode, body);
+    await context.client.request('DELETE', `${episode}/lock`);
+    const current = await context.client.get(endpoint);
+    if (options.out) await writeJson(options.out, current, true);
+    return options.full
+      ? { saved, current }
+      : {
+          ...located(current, episodeOf(current, episodeId)),
+          document_sha256: digest(current.document),
+          ...(options.out ? { file: path.resolve(options.out) } : {}),
+        };
+  }
+  if (action !== 'get')
+    throw new CliError(
+      2,
+      'UNKNOWN_COMMAND',
+      'Use script get, put, or episode add|rename|move.',
+    );
+  const current = await context.client.get(endpoint);
+  if (options.episode) {
+    const row = episodeOf(current, options.episode);
+    const { shots } = current.document.episodes[row.number - 1];
+    if (options.out) {
+      // 匯出成 script put 可直接送回的那一集內容。
+      await writeJson(options.out, { shots, deleted_shot_ids: [] }, true);
+      return { ...located(current, row), file: path.resolve(options.out) };
+    }
+    return options.full
+      ? { ...located(current, row), shots }
+      : located(current, row);
+  }
+  if (options.out) {
+    await writeJson(options.out, current, true);
+    return {
+      file: path.resolve(options.out),
+      content_revision: current.content_revision,
+      episodes: episodeRows(current),
+    };
+  }
+  return options.full
+    ? current
+    : {
+        creative_id: options.creative,
+        version_id: options['version-id'],
+        content_revision: current.content_revision,
+        document_sha256: digest(current.document),
+        episodes: episodeRows(current),
+        note: 'Use --out to export the full Script, or --episode N --out to export one Episode as a script put body.',
+      };
+}
+export async function shot(action, options, context) {
+  const creativeId = need(options.creative, '--creative (readback owner)');
+  const creativePath = `/storyboards/${id(creativeId)}`;
+  let endpoint;
+  if (action === 'update') endpoint = `/shots/${id(options.shot, '--shot')}`;
+  else if (action === 'move')
+    endpoint = `/shots/${id(options.shot, '--shot')}/position`;
+  else throw new CliError(2, 'UNKNOWN_COMMAND', 'Use shot update or move.');
+  const before = await context.client.get(creativePath);
+  if (!before.shots.some((row) => row.id === Number(options.shot)))
+    throw new CliError(
+      2,
+      'TARGET_MISMATCH',
+      'The Shot is not in this Creative.',
+    );
+  await context.client.request(
+    'PATCH',
+    endpoint,
+    await readJson(need(options['request-file'], '--request-file')),
+  );
+  const current = await context.client.get(creativePath);
+  return options.full
+    ? current
+    : {
+        creative_id: creativeId,
+        shots: current.shots.map((row) => ({
+          shot_id: row.id,
+          version_id: row.version_id,
+          sequence: row.sequence,
+        })),
+      };
+}
+export async function take(action, options, context) {
+  if (action !== 'select')
+    throw new CliError(2, 'UNKNOWN_COMMAND', 'Use take select.');
+  const creativePath = `/storyboards/${id(options.creative, '--creative')}`;
+  const shotId = Number(need(options.shot, '--shot'));
+  const row = await context.client.get(creativePath);
+  const shot = row.shots.find((item) => item.id === shotId);
+  if (
+    !shot?.results.some(
+      (item) =>
+        item.stage === 'i2v' && item.id === need(options.result, '--result'),
+    )
+  )
+    throw new CliError(
+      2,
+      'RESULT_MISMATCH',
+      'Choose a video Result already in the specified Creative/Shot.',
+    );
+  await context.client.request(
+    'PATCH',
+    `/shots/${id(shotId, '--shot')}/select`,
+    {
+      result_id: options.result,
+    },
+  );
+  const current = await context.client.get(creativePath);
+  const selected = current.shots.find(
+    (item) => item.id === shotId,
+  ).selected_result_id;
+  if (selected !== options.result)
+    throw new CliError(
+      4,
+      'SELECTION_READBACK_DIFFERS',
+      'The current selected Take differs from the requested Result. Inspect the Creative.',
+    );
+  return {
+    creative_id: options.creative,
+    shot_id: shotId,
+    selected_result_id: selected,
+  };
+}

package/src/download.mjs

@@ -0,0 +1,121 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, link, unlink, open } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { Transform, Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import path from 'node:path';
+import {
+  CliError,
+  need,
+  id,
+  readJson,
+  exists,
+  sameSubject,
+  subject,
+} from './core.mjs';
+
+export async function fileDigest(file) {
+  const hash = createHash('sha256');
+  let bytes = 0;
+  for await (const chunk of createReadStream(file)) {
+    hash.update(chunk);
+    bytes += chunk.length;
+  }
+  return { bytes, sha256: hash.digest('hex') };
+}
+export async function downloadUrl(url, file, signal) {
+  file = path.resolve(file);
+  if (await exists(file))
+    throw new CliError(2, 'FILE_EXISTS', `Output already exists: ${file}`);
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const partial = `${file}.${randomUUID()}.partial`;
+  let response;
+  try {
+    response = await fetch(url, {
+      headers: { 'Accept-Encoding': 'identity' },
+      signal: signal
+        ? AbortSignal.any([signal, AbortSignal.timeout(15 * 60000)])
+        : AbortSignal.timeout(15 * 60000),
+    });
+  } catch {
+    throw new CliError(
+      5,
+      'DOWNLOAD_INTERRUPTED',
+      'Could not fetch the media bytes. Retry through the original FUSE download endpoint.',
+    );
+  }
+  if (!response.ok || !response.body)
+    throw new CliError(
+      4,
+      'MEDIA_HTTP_ERROR',
+      `Media download returned HTTP ${response.status}. Obtain a fresh URL through the same FUSE result.`,
+      { http_status: response.status },
+    );
+  const hash = createHash('sha256');
+  let bytes = 0;
+  try {
+    await pipeline(
+      Readable.fromWeb(response.body),
+      new Transform({
+        transform(chunk, encoding, callback) {
+          bytes += chunk.length;
+          hash.update(chunk);
+          callback(null, chunk);
+        },
+      }),
+      createWriteStream(partial, { flags: 'wx', mode: 0o600 }),
+    );
+    const declared = response.headers.get('content-length');
+    if (bytes === 0 || (declared !== null && bytes !== Number(declared)))
+      throw new Error('Incomplete media body');
+    const handle = await open(partial, 'r+');
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await link(partial, file);
+    await unlink(partial);
+    return {
+      file,
+      bytes,
+      sha256: hash.digest('hex'),
+      content_type: response.headers.get('content-type'),
+      downloaded: true,
+    };
+  } catch {
+    throw new CliError(
+      5,
+      'DOWNLOAD_INTERRUPTED',
+      `Media did not complete; partial file: ${partial}`,
+    );
+  }
+}
+export async function download(kind, options, context) {
+  let creative = options.creative,
+    shot = options.shot,
+    result = options.result;
+  if (options.receipt) {
+    const receipt = await readJson(options.receipt);
+    sameSubject(receipt, await subject(context.client));
+    creative = receipt.creative_id;
+    shot = receipt.request.shot_id;
+    result = receipt.accepted?.result_id;
+  }
+  let endpoint;
+  // A take is the exact Result when one is named (receipt or --result);
+  // otherwise it is the Shot's currently selected take.
+  if (kind === 'take')
+    endpoint = `/storyboards/${id(creative, '--creative')}/download/shots/${id(shot, '--shot')}/take${result ? `?result_id=${id(result, '--result')}` : ''}`;
+  else if (kind === 'asset')
+    endpoint = `/assets/${id(options.asset, '--asset')}/results/${id(options.result, '--result')}/download`;
+  else throw new CliError(2, 'UNKNOWN_COMMAND', 'Use download take or asset.');
+  const { url } = await context.client.get(endpoint);
+  return {
+    kind,
+    creative_id: creative,
+    shot_id: shot ? Number(shot) : undefined,
+    result_id: result,
+    ...(await downloadUrl(url, need(options.out, '--out'), context.signal)),
+  };
+}