@alchemint/fuse-cli 0.0.0-stage → 0.1.0

package/src/prompt.mjs

@@ -0,0 +1,121 @@
+import path from 'node:path';
+import {
+  CliError,
+  need,
+  id,
+  readJson,
+  writeJson,
+  digest,
+  subject,
+  errorData,
+} from './core.mjs';
+import { recordedMutation } from './mutations.mjs';
+import { version as versionCommand } from './versions.mjs';
+
+const refinementSummary = (row) => ({
+  request_id: row.request_id,
+  status: row.status,
+  model: row.model,
+  refined_sha256:
+    typeof row.refined_prompt === 'string' ? digest(row.refined_prompt) : null,
+  refined_characters:
+    typeof row.refined_prompt === 'string' ? row.refined_prompt.length : 0,
+  error: row.error,
+});
+async function present(value, summary, options) {
+  if (options.out) {
+    await writeJson(options.out, value, true);
+    return { ...summary, file: path.resolve(options.out) };
+  }
+  return options.full ? value : summary;
+}
+export async function prompt(action, options, context) {
+  if (action === 'optimize') {
+    const body = options.resume
+      ? undefined
+      : await readJson(
+          need(
+            options['request-file'],
+            '--request-file (prompt refinement body)',
+          ),
+        );
+    return recordedMutation(
+      'prompt_optimize',
+      '/prompt-refinements',
+      body,
+      options,
+      context,
+      (row) => ({ request_id: row.request_id, status: row.status }),
+      true,
+    );
+  }
+  if (action === 'result') {
+    const row = await context.client.get(
+      `/prompt-refinements/${id(options.job, '--job (refinement request id)')}`,
+    );
+    return present(row, refinementSummary(row), options);
+  }
+  if (action === 'adopt') {
+    // Adoption writes the explicitly supplied draft onto one Shot version; it is not an
+    // automatic overwrite with the suggestion. Both texts stay in a private local record.
+    const body = await readJson(
+      need(
+        options['request-file'],
+        '--request-file (version draft input with the exact adopted prompt_text)',
+      ),
+    );
+    const suggestion = await context.client.get(
+      `/prompt-refinements/${id(options.job, '--job (suggestion provenance)')}`,
+    );
+    if (suggestion.status !== 'succeeded' || suggestion.refined_prompt === null)
+      throw new CliError(
+        4,
+        'SUGGESTION_NOT_READY',
+        'The specified suggestion is not ready for adoption.',
+      );
+    let adoption;
+    if (options.receipt) {
+      adoption = {
+        schema_version: 1,
+        kind: 'prompt_adoption',
+        ...(await subject(context.client)),
+        shot_id: Number(need(options.shot, '--shot')),
+        version_number: Number(need(options.number, '--number')),
+        stage: options.stage ?? 'i2v',
+        source_request_id: options.job,
+        suggestion_text: suggestion.refined_prompt,
+        adopted_text: body.prompt_text,
+        request: body,
+        state: 'prepared',
+      };
+      await writeJson(options.receipt, adoption, true);
+    }
+    try {
+      const saved = await versionCommand(
+        'draft',
+        'set',
+        { ...options, 'request-file': options['request-file'] },
+        context,
+      );
+      if (adoption) {
+        adoption.state = 'saved';
+        adoption.readback_sha256 = saved.input_sha256 ?? digest(saved.input);
+        await writeJson(options.receipt, adoption);
+      }
+      return saved;
+    } catch (error) {
+      if (adoption) {
+        adoption.state = 'unconfirmed';
+        adoption.error = errorData(error);
+        await writeJson(options.receipt, adoption);
+        error.receipt = options.receipt;
+      }
+      throw error;
+    }
+  }
+  throw new CliError(
+    2,
+    'UNKNOWN_COMMAND',
+    'Use prompt optimize, result, or adopt (drafts live on Shot versions: fuse version …).',
+  );
+}

package/src/versions.mjs

@@ -0,0 +1,358 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+  CliError,
+  need,
+  id,
+  digest,
+  readJson,
+  writeJson,
+  exists,
+  subject,
+  sameSubject,
+  withWriter,
+} from './core.mjs';
+import { acceptVideo, observeVideo, validateIntent } from './video.mjs';
+
+// A Shot version is numbered when it is added and never renumbered. Without a Job it is
+// a draft; submitting binds the accepted Job, after which its state reads from the Shot's
+// result pool. Failed versions keep their number; retrying means adding a new version.
+const STAGES = ['t2i', 'i2v'];
+const stageOf = (options) => {
+  const stage = options.stage ?? 'i2v';
+  if (!STAGES.includes(stage))
+    throw new CliError(2, 'INVALID_STAGE', '--stage must be t2i or i2v.');
+  return stage;
+};
+export const versionLabel = (version) =>
+  `${version.stage === 'i2v' ? 'T' : 'V'}${version.number}`;
+export function versionSummary(shot, version) {
+  const row = version.job_id
+    ? (shot.results.find((item) => item.job_id === version.job_id) ?? null)
+    : null;
+  return {
+    version_id: version.id,
+    version: versionLabel(version),
+    number: version.number,
+    stage: version.stage,
+    state: version.job_id === null ? 'draft' : row ? row.status : 'removed',
+    job_id: version.job_id,
+    result_id: row?.id ?? null,
+    has_output: Boolean(row?.output_url),
+    has_input: version.input !== null,
+    based_on_version_id: version.based_on_version_id,
+    updated_at: version.updated_at,
+  };
+}
+async function shotOf(client, options) {
+  const creativeId = need(options.creative, '--creative');
+  const creative = await client.get(`/storyboards/${id(creativeId)}`);
+  const shotId = Number(need(options.shot, '--shot'));
+  const shot = creative.shots.find((row) => row.id === shotId);
+  if (!shot)
+    throw new CliError(
+      2,
+      'TARGET_MISMATCH',
+      'The Shot does not belong to this Creative.',
+    );
+  return { creativeId, shotId, shot };
+}
+function versionOf(shot, stage, options, flag = 'number') {
+  const number = Number(need(options[flag], `--${flag} (version number)`));
+  if (!Number.isInteger(number) || number < 1)
+    throw new CliError(
+      2,
+      'INVALID_VERSION_NUMBER',
+      `--${flag} is the number shown as T4 or V4, so 4.`,
+    );
+  const version = shot.versions.find(
+    (row) => row.stage === stage && row.number === number,
+  );
+  if (!version)
+    throw new CliError(
+      2,
+      'VERSION_NOT_FOUND',
+      `Shot ${shot.id} has no ${stage} version ${number}. Run version list.`,
+    );
+  return version;
+}
+/** The submission body is the saved input without the web editor state. */
+export function submissionOf(input) {
+  const { editor: _editor, ...body } = input;
+  return body;
+}
+export async function writeVersionInput(client, shotId, versionId, input) {
+  const saved = await client.request(
+    'PUT',
+    `/shots/${id(shotId)}/versions/${id(versionId)}/input`,
+    { input },
+  );
+  if (digest(saved.input) !== digest(input))
+    throw new CliError(
+      4,
+      'DRAFT_READBACK_DIFFERS',
+      'The saved draft differs from the supplied input. No generation was submitted.',
+    );
+  return saved;
+}
+async function present(value, summary, options) {
+  if (options.out) {
+    await writeJson(options.out, value, true);
+    return { ...summary, file: path.resolve(options.out) };
+  }
+  return options.full ? value : summary;
+}
+export async function version(action, subaction, options, context) {
+  const { client } = context;
+  if (action === 'list') {
+    const { creativeId, shotId, shot } = await shotOf(client, options);
+    const stage = options.stage === undefined ? null : stageOf(options);
+    const rows = shot.versions.filter((row) => !stage || row.stage === stage);
+    return {
+      creative_id: creativeId,
+      shot_id: shotId,
+      versions: options.full
+        ? rows
+        : rows.map((row) => versionSummary(shot, row)),
+    };
+  }
+  if (action === 'new') {
+    const { creativeId, shotId, shot } = await shotOf(client, options);
+    const stage = stageOf(options);
+    const base =
+      options.from === undefined
+        ? null
+        : versionOf(shot, stage, options, 'from');
+    let input = options['request-file']
+      ? await readJson(options['request-file'])
+      : null;
+    if (!input && base) {
+      if (base.input === null)
+        throw new CliError(
+          2,
+          'VERSION_INPUT_UNAVAILABLE',
+          `${versionLabel(base)} was generated before drafts were kept per version. Read its take with creative show --full and start the draft with --request-file.`,
+        );
+      input = base.input;
+    }
+    const created = await client.post(`/shots/${id(shotId)}/versions`, {
+      stage,
+      based_on_version_id: base?.id ?? null,
+      input,
+    });
+    const current = await client.get(`/storyboards/${id(creativeId)}`);
+    const shotNow = current.shots.find((row) => row.id === shotId);
+    const row = shotNow?.versions.find((item) => item.id === created.id);
+    if (!row)
+      throw new CliError(
+        5,
+        'VERSION_READBACK_MISSING',
+        'The new version is not visible in the Creative. Inspect it with version list.',
+      );
+    return {
+      creative_id: creativeId,
+      shot_id: shotId,
+      ...versionSummary(shotNow, row),
+    };
+  }
+  if (action === 'draft' && subaction === 'get') {
+    const { creativeId, shotId, shot } = await shotOf(client, options);
+    const target = versionOf(shot, stageOf(options), options);
+    return present(
+      target.input,
+      {
+        creative_id: creativeId,
+        shot_id: shotId,
+        ...versionSummary(shot, target),
+        prompt_characters:
+          typeof target.input?.prompt_text === 'string'
+            ? target.input.prompt_text.length
+            : 0,
+      },
+      options,
+    );
+  }
+  if (action === 'draft' && subaction === 'set') {
+    const { creativeId, shotId, shot } = await shotOf(client, options);
+    const target = versionOf(shot, stageOf(options), options);
+    if (target.job_id !== null)
+      throw new CliError(
+        2,
+        'VERSION_SUBMITTED',
+        `${versionLabel(target)} is already submitted; add a new version.`,
+      );
+    const input = await readJson(
+      need(options['request-file'], '--request-file (version draft input)'),
+    );
+    const saved = await writeVersionInput(client, shotId, target.id, input);
+    return present(
+      saved,
+      {
+        creative_id: creativeId,
+        shot_id: shotId,
+        ...versionSummary(shot, saved),
+        input_sha256: digest(saved.input),
+      },
+      options,
+    );
+  }
+  if (action === 'delete') {
+    const { creativeId, shotId, shot } = await shotOf(client, options);
+    const target = versionOf(shot, stageOf(options), options);
+    if (target.job_id !== null)
+      throw new CliError(
+        2,
+        'VERSION_SUBMITTED',
+        `${versionLabel(target)} is already submitted; only drafts can be deleted.`,
+      );
+    await client.request(
+      'DELETE',
+      `/shots/${id(shotId)}/versions/${id(target.id)}`,
+    );
+    const current = await client.get(`/storyboards/${id(creativeId)}`);
+    const shotNow = current.shots.find((row) => row.id === shotId);
+    if (shotNow?.versions.some((row) => row.id === target.id))
+      throw new CliError(
+        4,
+        'DELETE_READBACK_DIFFERS',
+        'The version is still listed after deletion. Inspect the Creative.',
+      );
+    return {
+      creative_id: creativeId,
+      shot_id: shotId,
+      version_id: target.id,
+      version: versionLabel(target),
+      deleted: true,
+    };
+  }
+  if (action === 'submit') return submitVersion(options, context);
+  throw new CliError(
+    2,
+    'UNKNOWN_COMMAND',
+    'Use version list, new, draft get/set, submit, or delete.',
+  );
+}
+// Same receipt discipline as video submit: the exact body and key are frozen before POST,
+// an unknown acceptance is reconciled with --resume, and a rejection is only retried
+// explicitly. The receipt also records which version the Job binds to.
+async function submitVersion(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 !== 'version_submit')
+        throw new CliError(
+          2,
+          'WRONG_RECEIPT',
+          'Expected a version 1 version-submit receipt.',
+        );
+      validateIntent(
+        receipt.request,
+        receipt.idempotency_key,
+        receipt.endpoint,
+      );
+      if (digest(receipt.request) !== receipt.request_sha256)
+        throw new CliError(
+          2,
+          'INTENT_CHANGED',
+          'The saved submission request changed.',
+        );
+      sameSubject(receipt, owner);
+      if (!options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_EXISTS',
+          'Use --resume to reconcile this fixed intent; a new submission needs a new receipt.',
+        );
+      if (receipt.accepted) {
+        receipt.observation = await observeVideo(context.client, receipt);
+        await writeJson(file, receipt);
+        return {
+          receipt: file,
+          version_id: receipt.version_id,
+          version: receipt.version,
+          ...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 },
+        ];
+      }
+    } else {
+      if (options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_NOT_FOUND',
+          'Resume requires the existing receipt file.',
+        );
+      const { creativeId, shotId, shot } = await shotOf(
+        context.client,
+        options,
+      );
+      const stage = stageOf(options);
+      const target = versionOf(shot, stage, options);
+      if (target.job_id !== null)
+        throw new CliError(
+          2,
+          'VERSION_SUBMITTED',
+          `${versionLabel(target)} is already submitted; add a new version.`,
+        );
+      const body = options['request-file']
+        ? await readJson(options['request-file'])
+        : target.input === null
+          ? null
+          : submissionOf(target.input);
+      if (!body)
+        throw new CliError(
+          2,
+          'DRAFT_EMPTY',
+          'This version has no saved draft. Write one with version draft set, or pass --request-file.',
+        );
+      const request = { stage, shot_id: shotId, ...body };
+      const key = options['idempotency-key'] || randomUUID();
+      const endpoint = `/shots/${shotId}/versions/${target.id}/submit`;
+      validateIntent(request, key, endpoint);
+      receipt = {
+        schema_version: 1,
+        kind: 'version_submit',
+        ...owner,
+        creative_id: creativeId,
+        version_id: target.id,
+        version: versionLabel(target),
+        endpoint,
+        idempotency_key: key,
+        request,
+        request_sha256: digest(request),
+        state: 'prepared',
+        created_at: new Date().toISOString(),
+      };
+      await writeJson(file, receipt, true);
+    }
+    await acceptVideo(context.client, receipt, file);
+    return {
+      receipt: file,
+      version_id: receipt.version_id,
+      version: receipt.version,
+      ...receipt.accepted,
+      observation: receipt.observation,
+    };
+  });
+}