@alchemint/fuse-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# Fuse CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用 Claude Code、Codex 或終端機操作你的 Fuse 工作區。你可以讀寫分集劇本、調整鏡頭順序、上傳參考素材、選模型、提交生成，並把指定的 Take 下載到本機目錄。
+
+## 在電腦上安裝
+
+使用 Node.js 22.x 與 npm。套件名稱是 `@alchemint/fuse-cli`，安裝後執行的命令是 `fuse`。套件沒有執行階段相依套件，也沒有安裝腳本。
+
+從 [Fuse 官網](https://fuse.alchemint.xyz/zh-tw/cli) 取得 0.1.0 安裝包後，在下載目錄執行：
+
+```sh
+npm install --global ./alchemint-fuse-cli-0.1.0.tgz --ignore-scripts
+fuse --version
+```
+
+透過 npm registry 安裝同一個公開版本的指令為 `npm install --global @alchemint/fuse-cli@0.1.0 --ignore-scripts`。若電腦上已有其他程式使用 `fuse` 這個名稱，請先確認執行檔的位置，再選擇安裝目錄。
+
+## 連接 Fuse 工作區
+
+```sh
+fuse auth login
+fuse auth status
+fuse creative list --page 1 --limit 10
+```
+
+預設登入頁位於 `https://fuse.alchemint.xyz/cli/authorize`。只核准剛剛由自己發起的連線；請比對瀏覽器與終端機的授權碼，確認帳戶與工作區後再按「允許連接」。上面最後一行只讀取作品清單，不提交生成。如果終端機無法開啟瀏覽器，用 `fuse auth login --no-browser`，依照提示開啟授權頁。
+
+CLI 會將這次連線的憑證保存在使用者的 `~/.config/fuse`，或你指定的 `FUSE_CONFIG_DIR`。請勿將這個目錄加入 Git、傳給助理或貼進支援對話。執行 `fuse auth logout` 可撤銷這次 CLI 連線。若另行設定 `FUSE_API_URL` 或注入 `FUSE_TOKEN`，請先確認目標服務是你信任的 Fuse 部署。
+
+## 用平常的話交代助理
+
+在能執行本機命令的助理裡開啟專案，登入後就可以這樣說：
+
+- 「列出第一集的鏡頭，把屋頂那一鏡移到閱覽室前面。」
+- 「查一下這個鏡頭能用哪些影片模型。先列出選項，等我決定再送出。」
+- 「把選用的 Take 存到目前目錄，檔名用 shot.mp4。」
+
+用終端機也可以完成同樣的操作。以下只查模型，並下載一個既有的選用版本。請用自己的作品 UUID 和鏡頭 ID 取代佔位文字。
+
+```sh
+fuse models list --stage video
+fuse download take --creative CREATIVE_UUID --shot SHOT_ID --out ./shot.mp4
+```
+
+## 生成、費用與收據
+
+`video submit`、`version submit` 和 `batch run` 會提交生成，依工作區的模型、點數與方案計費。`creative create` 也會從輸入的構想或劇本啟動製作流程。查看進度可以使用 `job show` 或 `batch status`。購買點數與訂閱會員請前往 [Fuse 方案頁](https://fuse.alchemint.xyz/zh-tw/plans)。
+
+提交時保留原收據。若連線中斷，用同一份收據與 `--resume` 確認服務是否已受理，再決定下一步。收據可能包含劇本、提示詞與素材參照，請保存在自己的專案目錄。輸入 `fuse --help` 查看指令和接受的參數。

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@alchemint/fuse-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Use your local AI assistant to edit shots, submit video jobs and download results from Fuse.",
+  "engines": {
+    "node": "22.x"
+  },
+  "bin": {
+    "fuse": "src/main.mjs"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://fuse.alchemint.xyz/zh-tw/cli",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/assets.mjs

@@ -0,0 +1,386 @@
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+  CliError,
+  need,
+  id,
+  readJson,
+  writeJson,
+  exists,
+  subject,
+  sameSubject,
+  digest,
+  duration,
+  pause,
+  withWriter,
+  errorData,
+} from './core.mjs';
+import { fileDigest } from './download.mjs';
+
+const memberSummary = (item) => ({
+  asset_id: item.id,
+  name: item.name,
+  type: item.type,
+  medium: item.medium,
+  availability: item.availability,
+  representation_result_id: item.canonical_result?.id ?? null,
+});
+const entrySummary = (entry) => ({
+  id: entry.id,
+  name: entry.name,
+  key: entry.key,
+  is_pack: entry.is_pack,
+  members: entry.members.map(memberSummary),
+});
+async function transfer(file, declaration, plan, context) {
+  async function put(url, start, end, headers) {
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'PUT',
+        redirect: 'error',
+        headers: { ...headers, 'Content-Length': String(end - start + 1) },
+        body: createReadStream(file, { start, end }),
+        duplex: 'half',
+        signal: AbortSignal.any([
+          context.signal,
+          AbortSignal.timeout(15 * 60000),
+        ]),
+      });
+    } catch {
+      throw new CliError(
+        5,
+        'UPLOAD_TRANSFER_UNKNOWN',
+        'Upload transfer was interrupted. Resume the same receipt/session.',
+      );
+    }
+    if (!response.ok)
+      throw new CliError(
+        4,
+        'UPLOAD_TRANSFER_REJECTED',
+        `Upload transfer HTTP ${response.status}; resume the same session to refresh its plan.`,
+        { http_status: response.status },
+      );
+    return response.headers.get('etag');
+  }
+  if (plan.kind === 'single') {
+    await put(plan.url, 0, declaration.byteSize - 1, plan.requiredHeaders);
+    return {};
+  }
+  if (plan.kind !== 'multipart')
+    throw new CliError(
+      4,
+      'UNKNOWN_TRANSFER',
+      'The server returned an unsupported transfer kind.',
+    );
+  const parts = [];
+  for (const part of plan.parts) {
+    const start = (part.partNumber - 1) * plan.partSizeBytes;
+    const etag = await put(
+      part.url,
+      start,
+      Math.min(start + plan.partSizeBytes, declaration.byteSize) - 1,
+      {},
+    );
+    if (!etag)
+      throw new CliError(
+        5,
+        'UPLOAD_ETAG_UNKNOWN',
+        'The uploaded part did not return its completion ETag. Resume the same session.',
+      );
+    parts.push({ partNumber: part.partNumber, etag });
+    context.progress(`Uploaded part ${part.partNumber}/${plan.parts.length}`);
+  }
+  return { parts };
+}
+/**
+ * One private Upload frozen in a receipt, then the caller's acceptance of its ready
+ * receipt. `accepting` names the receipt kind and command, builds the acceptance
+ * metadata, accepts (recording its identities on the receipt) and reads the result back.
+ */
+export async function uploadWithReceipt(options, context, accepting) {
+  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)) {
+      if (!options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_EXISTS',
+          `Use ${accepting.command} --resume with this original receipt.`,
+        );
+      receipt = await readJson(file);
+      sameSubject(receipt, owner);
+      if (receipt.schema_version !== 1 || receipt.kind !== accepting.kind)
+        throw new CliError(
+          2,
+          'WRONG_RECEIPT',
+          `This receipt is not from ${accepting.command}.`,
+        );
+      if (receipt.state === 'adopted') return accepting.result(receipt, file);
+    } else {
+      if (options.resume)
+        throw new CliError(
+          2,
+          'RECEIPT_NOT_FOUND',
+          'Resume requires the existing upload receipt.',
+        );
+      const media = path.resolve(need(options.file, '--file'));
+      const metadata = await accepting.metadata(media);
+      const declared = await fileDigest(media);
+      receipt = {
+        schema_version: 1,
+        kind: accepting.kind,
+        ...owner,
+        media,
+        metadata,
+        metadata_sha256: digest(metadata),
+        declaration: {
+          name: path.basename(media),
+          contentType: need(options['content-type'], '--content-type'),
+          byteSize: declared.bytes,
+          checksumSha256: declared.sha256,
+        },
+        idempotency_key: options['idempotency-key'] || randomUUID(),
+        state: 'prepared',
+      };
+      await writeJson(file, receipt, true);
+    }
+    if (digest(receipt.metadata) !== receipt.metadata_sha256)
+      throw new CliError(2, 'INTENT_CHANGED', 'Upload metadata changed.');
+    try {
+      let status, plan;
+      if (!receipt.session_id) {
+        const initiated = await context.client.post('/uploads', {
+          purpose: 'asset_private',
+          idempotencyKey: receipt.idempotency_key,
+          file: receipt.declaration,
+        });
+        receipt.session_id = initiated.sessionId;
+        receipt.state = initiated.state;
+        await writeJson(file, receipt);
+        status = initiated;
+        plan = initiated.transferPlan;
+      } else
+        status = await context.client.get(`/uploads/${id(receipt.session_id)}`);
+      if (status.state === 'transferring') {
+        const current = await fileDigest(receipt.media);
+        if (
+          current.bytes !== receipt.declaration.byteSize ||
+          current.sha256 !== receipt.declaration.checksumSha256
+        )
+          throw new CliError(
+            2,
+            'INPUT_CHANGED',
+            'The upload file changed; the original session was preserved.',
+          );
+        if (!plan)
+          plan = (
+            await context.client.post(
+              `/uploads/${id(receipt.session_id)}/refresh`,
+              {},
+            )
+          ).transferPlan;
+        const completion = await transfer(
+          receipt.media,
+          receipt.declaration,
+          plan,
+          context,
+        );
+        receipt.completion = completion;
+        receipt.state = 'transferred';
+        await writeJson(file, receipt);
+        status = await context.client.post(
+          `/uploads/${id(receipt.session_id)}/complete`,
+          completion,
+        );
+      }
+      const deadline = Date.now() + duration(options.timeout || '10m');
+      while (status.state === 'uploaded') {
+        if (Date.now() >= deadline)
+          throw new CliError(
+            6,
+            'UPLOAD_PENDING',
+            'Upload processing is still pending; resume the same receipt.',
+          );
+        await pause(Math.min(5000, deadline - Date.now()), context.signal);
+        status = await context.client.get(`/uploads/${id(receipt.session_id)}`);
+      }
+      receipt.state = status.state;
+      if (
+        !['ready', 'consumed'].includes(status.state) ||
+        !status.readyReceipt?.id
+      )
+        throw new CliError(
+          4,
+          'UPLOAD_NOT_READY',
+          `Upload ended in ${status.state}: ${status.validationFailureReason || 'no accepted media'}`,
+        );
+      receipt.ready_receipt_id = status.readyReceipt.id;
+      await writeJson(file, receipt);
+      await accepting.accept(receipt, () => writeJson(file, receipt));
+      receipt.state = 'adopted';
+      delete receipt.error;
+      await writeJson(file, receipt);
+      return accepting.result(receipt, file);
+    } catch (error) {
+      receipt.error = errorData(error);
+      await writeJson(file, receipt);
+      error.receipt = file;
+      throw error;
+    }
+  });
+}
+const assetUpload = (options, context) => ({
+  kind: 'asset_upload',
+  command: 'asset upload',
+  async metadata() {
+    const metadata = await readJson(
+      need(options['request-file'], '--request-file (Asset metadata JSON)'),
+    );
+    if ('receipt_id' in metadata)
+      throw new CliError(
+        2,
+        'RESERVED_FIELD',
+        'The upload receipt_id is supplied by Upload, not by metadata.',
+      );
+    return metadata;
+  },
+  async accept(receipt) {
+    const asset = await context.client.post('/assets/uploads', {
+      ...receipt.metadata,
+      receipt_id: receipt.ready_receipt_id,
+    });
+    receipt.asset_id = asset.id;
+    receipt.library_entry_id = asset.library_entry_id;
+  },
+  async result(receipt, file) {
+    const usable = await context.client.get(`/assets/${id(receipt.asset_id)}`);
+    return {
+      asset_id: receipt.asset_id,
+      library_entry_id: receipt.library_entry_id,
+      name: usable.name,
+      receipt: file,
+      upload_session_id: receipt.session_id,
+      ready_receipt_id: receipt.ready_receipt_id,
+    };
+  },
+});
+export async function assets(action, options, context) {
+  if (action === 'upload')
+    return uploadWithReceipt(options, context, assetUpload(options, context));
+  if (action === 'list') {
+    const query = new URLSearchParams();
+    if (options.cursor) query.set('cursor', options.cursor);
+    if (options.type) query.set('type', options.type);
+    const result = await context.client.get(`/asset-library?${query}`);
+    return {
+      items: options.full ? result.items : result.items.map(entrySummary),
+      next_cursor: result.next_cursor,
+    };
+  }
+  if (action === 'show') {
+    const result = await context.client.get(
+      `/asset-library/${id(options.asset, '--asset (library entry ID)')}`,
+    );
+    if (options.out) {
+      await writeJson(options.out, result, true);
+      return { file: path.resolve(options.out), id: result.id };
+    }
+    return options.full ? result : entrySummary(result);
+  }
+  if (action === 'link') {
+    const body = await readJson(
+      need(
+        options['request-file'],
+        '--request-file ({creative_ids,asset_ids})',
+      ),
+    );
+    const endpoint = `/assets/${id(options.asset, '--asset (library entry ID)')}/creative-materials`;
+    await context.client.post(endpoint, body);
+    const rows = await context.client.get(endpoint);
+    const targets = rows.filter((row) => body.creative_ids.includes(row.id));
+    if (
+      targets.length !== body.creative_ids.length ||
+      targets.some((row) =>
+        body.asset_ids.some((assetId) => !row.asset_ids.includes(assetId)),
+      )
+    )
+      throw new CliError(
+        4,
+        'ASSOCIATION_READBACK_DIFFERS',
+        'The requested material associations are not all present on the selected Creatives.',
+      );
+    return options.full
+      ? targets
+      : {
+          library_entry_id: options.asset,
+          creatives: targets.map((row) => ({
+            creative_id: row.id,
+            linked_asset_ids: row.asset_ids.filter((assetId) =>
+              body.asset_ids.includes(assetId),
+            ),
+          })),
+        };
+  }
+  if (action === 'unlink') {
+    const assetId = need(options.asset, '--asset');
+    const creativeId = need(options.creative, '--creative');
+    await context.client.request(
+      'DELETE',
+      `/assets/${id(assetId)}/creative-materials/${id(creativeId)}`,
+    );
+    const { asset_ids } = await context.client.get(
+      `/assets/creative-materials/${id(creativeId)}`,
+    );
+    if (asset_ids.includes(assetId))
+      throw new CliError(
+        4,
+        'ASSOCIATION_READBACK_DIFFERS',
+        'The asset is still in the Creative collection.',
+      );
+    return { asset_id: assetId, creative_id: creativeId, removed: true };
+  }
+  if (action === 'canonical') {
+    const assetId = need(options.asset, '--asset');
+    const resultId = need(options.result, '--result');
+    // The canonical switch is conditional on the representation read just before it.
+    const before = await context.client.get(`/assets/${id(assetId)}`);
+    await context.client.request('PATCH', `/assets/${id(assetId)}/canonical`, {
+      result_id: resultId,
+      expected_result_id: before.canonical_result?.id ?? null,
+    });
+    const after = await context.client.get(`/assets/${id(assetId)}`);
+    if (after.canonical_result?.id !== resultId)
+      throw new CliError(
+        4,
+        'CANONICAL_READBACK_DIFFERS',
+        'The asset does not read back the requested representation.',
+      );
+    return {
+      asset_id: assetId,
+      canonical_result_id: resultId,
+      previous_result_id: before.canonical_result?.id ?? null,
+    };
+  }
+  if (action === 'update') {
+    const assetId = need(options.asset, '--asset');
+    const name = need(options.name, '--name');
+    await context.client.request('PATCH', `/assets/${id(assetId)}`, { name });
+    const after = await context.client.get(`/assets/${id(assetId)}`);
+    if (after.name !== name)
+      throw new CliError(
+        4,
+        'UPDATE_READBACK_DIFFERS',
+        'The asset does not read back the requested name.',
+      );
+    return { asset_id: assetId, name: after.name };
+  }
+  throw new CliError(
+    2,
+    'UNKNOWN_COMMAND',
+    'Use asset list, show, upload, link, unlink, canonical, or update.',
+  );
+}

package/src/auth.mjs

@@ -0,0 +1,132 @@
+import { hostname } from 'node:os';
+import { spawn } from 'node:child_process';
+import {
+  CliError,
+  saveCredential,
+  forgetCredential,
+  pause,
+  duration,
+} from './core.mjs';
+
+export async function auth(action, options, context) {
+  const { client, signal, progress } = context;
+  if (action === 'status') {
+    const account = await client.get('/identity/me');
+    return {
+      api_url: client.base,
+      user_id: account.user.id,
+      workspace_id: account.workspace.id,
+      workspace_name: account.workspace.name,
+      display_name: account.user.displayName,
+    };
+  }
+  if (action === 'logout') {
+    await client.post('/identity/logout', {});
+    if (!process.env.FUSE_TOKEN) await forgetCredential(client.base);
+    return {
+      revoked: true,
+      ...(process.env.FUSE_TOKEN
+        ? { note: 'The injected session was revoked; unset FUSE_TOKEN.' }
+        : {}),
+    };
+  }
+  if (action !== 'login')
+    throw new CliError(
+      2,
+      'UNKNOWN_COMMAND',
+      'Use auth login, status, or logout.',
+    );
+  if (process.env.FUSE_TOKEN)
+    throw new CliError(
+      2,
+      'INJECTED_SESSION_ACTIVE',
+      'Unset FUSE_TOKEN before device login; that variable takes precedence over saved credentials.',
+    );
+  const grant = await client.post(
+    '/identity/cli/authorizations',
+    { device_name: options['device-name'] || hostname() },
+    { anonymous: true },
+  );
+  const url = new URL(grant.verification_uri_complete);
+  const apiOrigin = new URL(client.base).origin;
+  const localHttp =
+    url.protocol === 'http:' &&
+    ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
+    ['localhost', '127.0.0.1', '[::1]'].includes(new URL(client.base).hostname);
+  if (
+    (url.protocol !== 'https:' && !localHttp) ||
+    (apiOrigin === 'https://fuse.alchemint.xyz' && url.origin !== apiOrigin) ||
+    url.username ||
+    url.password ||
+    url.pathname !== '/cli/authorize' ||
+    !grant.user_code ||
+    url.searchParams.get('code') !== grant.user_code
+  )
+    throw new CliError(
+      4,
+      'INVALID_VERIFICATION_URL',
+      'The server did not provide a secure authorization page.',
+    );
+  progress(
+    `Open ${url.href}\nCode: ${grant.user_code}\nExpires: ${grant.expires_at}`,
+  );
+  if (!options['no-browser']) {
+    const [command, args] =
+      process.platform === 'darwin'
+        ? ['open', [url.href]]
+        : process.platform === 'win32'
+          ? ['rundll32', ['url.dll,FileProtocolHandler', url.href]]
+          : ['xdg-open', [url.href]];
+    const child = spawn(command, args, { stdio: 'ignore' });
+    child.on('error', () =>
+      progress('Could not open the browser. Use the authorization URL above.'),
+    );
+  }
+  const deadline = Math.min(
+    Date.parse(grant.expires_at),
+    Date.now() + duration(options.timeout || '10m'),
+  );
+  let interval = grant.interval_seconds;
+  while (Date.now() < deadline) {
+    await pause(Math.min(interval * 1000, deadline - Date.now()), signal);
+    let result;
+    try {
+      result = await client.post(
+        '/identity/cli/token',
+        { device_code: grant.device_code },
+        { anonymous: true },
+      );
+    } catch (error) {
+      if (error.http_status === 429) {
+        interval = error.retry_after || interval + 5;
+        continue;
+      }
+      throw error;
+    }
+    if (result.status === 'pending') {
+      interval = result.interval_seconds;
+      continue;
+    }
+    client.token = result.access_token;
+    const account = await client.get('/identity/me');
+    await saveCredential(
+      client.base,
+      result.access_token,
+      account,
+      result.expires_at,
+    );
+    return {
+      api_url: client.base,
+      user_id: account.user.id,
+      workspace_id: account.workspace.id,
+      workspace_name: account.workspace.name,
+      expires_at: result.expires_at,
+      session: 'independent',
+    };
+  }
+  throw new CliError(
+    6,
+    'LOGIN_TIMEOUT',
+    'Authorization wait ended. Start a new login.',
+  );
+}