@stelfield/cli 0.0.0-stage → 0.12.1

package/src/media-upload.js

@@ -0,0 +1,478 @@
+// Local media upload for agents (v0.19.0 M3 / CLI 0.10.0).
+//
+// What this does for the user: an agent can put a local picture or video on the merchant's
+// homepage. Each file goes through three steps the platform already offers to the merchant's
+// web page: ask for an upload address -> PUT the bytes straight to storage -> confirm.
+//
+// This file holds everything that is NOT command wiring:
+//   - the extension whitelist and size limits (mirrors the backend MIME whitelist),
+//   - a local pre-check (exists / regular file / extension / size),
+//   - a pure-JS video duration reader (mp4/mov moov/mvhd, webm EBML Info) - no ffprobe needed,
+//   - the upload loop with sha256 de-duplication and a user-facing Chinese error mapping.
+//
+// Nothing here reads a path the caller did not hand over: choosing WHICH paths are allowed
+// (the Markdown sub-tree rule) is the job of local-media-refs.js.
+
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, readFileSync, readSync, realpathSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { confirmProfileMedia, requestProfileMediaUpload } from './api.js';
+import { GPS_REJECT_TEXT, jpegHasGps, sniffMagic } from './media-safety.js';
+
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_VIDEO_BYTES = 50 * 1024 * 1024;
+/** How much of a file's start is read locally for the magic-number and EXIF checks. */
+const HEAD_READ_BYTES = 256 * 1024;
+/** Max files per command (same number for `media upload` and for one Markdown file). */
+export const MAX_FILES_PER_COMMAND = 20;
+
+/** extension -> { mediaType, mime }. Mirrors backend IMAGE_MIME_TYPES / VIDEO_MIME_TYPES. */
+export const MEDIA_EXTENSIONS = {
+  '.jpg': { mediaType: 'image', mime: 'image/jpeg' },
+  '.jpeg': { mediaType: 'image', mime: 'image/jpeg' },
+  '.png': { mediaType: 'image', mime: 'image/png' },
+  '.gif': { mediaType: 'image', mime: 'image/gif' },
+  '.webp': { mediaType: 'image', mime: 'image/webp' },
+  '.mp4': { mediaType: 'video', mime: 'video/mp4' },
+  '.mov': { mediaType: 'video', mime: 'video/quicktime' },
+  '.webm': { mediaType: 'video', mime: 'video/webm' },
+};
+
+export const ALLOWED_EXT_TEXT = 'jpg/jpeg/png/gif/webp（图片）、mp4/mov/webm（视频）';
+export const HOURLY_LIMIT_HINT = '每个 agent 每小时最多上传 30 个，请稍后再试。';
+export const VIDEO_DURATION_HINT = '请改用 mp4 / mov 格式再试，或到网页上传。';
+
+/** Error carrying a ready-to-print Chinese message. `uploaded` lists what already succeeded. */
+export class MediaUploadError extends Error {
+  constructor(message, extra = {}) {
+    super(message);
+    this.name = 'MediaUploadError';
+    this.status = extra.status ?? null;
+    this.file = extra.file ?? null;
+    this.uploaded = extra.uploaded ?? [];
+    /** true when the failure must stop the whole run (rate limit, quota, auth). */
+    this.fatal = true;
+  }
+}
+
+export function humanSize(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v) || v < 0) return '?';
+  if (v < 1024) return `${v}B`;
+  if (v < 1024 * 1024) return `${(v / 1024).toFixed(1)}KB`;
+  return `${(v / 1024 / 1024).toFixed(1)}MB`;
+}
+
+// ============================================================
+// pure-JS video duration
+// ============================================================
+
+function readAt(fd, pos, len) {
+  const buf = Buffer.alloc(len);
+  const n = readSync(fd, buf, 0, len, pos);
+  return buf.subarray(0, n);
+}
+
+/** Turn a (duration, timescale) pair into whole seconds; null when it does not make sense. */
+function toSeconds(duration, timescale) {
+  if (!Number.isFinite(duration) || !Number.isFinite(timescale) || timescale <= 0 || duration <= 0) return null;
+  const sec = duration / timescale;
+  if (!Number.isFinite(sec) || sec <= 0) return null;
+  return Math.max(1, Math.round(sec));
+}
+
+/** Find the `mvhd` box inside the body of a `moov` box and return the duration in seconds. */
+function durationFromMoovBody(body) {
+  let pos = 0;
+  while (pos + 8 <= body.length) {
+    let size = body.readUInt32BE(pos);
+    const type = body.toString('latin1', pos + 4, pos + 8);
+    let hdr = 8;
+    if (size === 1) {
+      if (pos + 16 > body.length) return null;
+      size = Number(body.readBigUInt64BE(pos + 8));
+      hdr = 16;
+    } else if (size === 0) {
+      size = body.length - pos;
+    }
+    if (size < hdr) return null;
+    if (type === 'mvhd') {
+      const p = pos + hdr;
+      const version = body[p];
+      if (version === 1) {
+        if (p + 32 > body.length) return null;
+        const timescale = body.readUInt32BE(p + 20);
+        const duration = Number(body.readBigUInt64BE(p + 24));
+        return toSeconds(duration, timescale);
+      }
+      if (p + 20 > body.length) return null;
+      const timescale = body.readUInt32BE(p + 12);
+      const duration = body.readUInt32BE(p + 16);
+      if (duration === 0xffffffff) return null; // "unknown" marker
+      return toSeconds(duration, timescale);
+    }
+    pos += size;
+  }
+  return null;
+}
+
+/** mp4 / mov: walk the top-level boxes to `moov`, then read `mvhd`. */
+function mp4Duration(fd, fileSize) {
+  let pos = 0;
+  let first = true;
+  for (let i = 0; i < 500 && pos + 8 <= fileSize; i++) {
+    const h = readAt(fd, pos, 16);
+    if (h.length < 8) return null;
+    let size = h.readUInt32BE(0);
+    const type = h.toString('latin1', 4, 8);
+    // A real mp4/mov starts with "ftyp"; anything else is a renamed file.
+    if (first && type !== 'ftyp') return null;
+    first = false;
+    let hdr = 8;
+    if (size === 1) {
+      if (h.length < 16) return null;
+      size = Number(h.readBigUInt64BE(8));
+      hdr = 16;
+    } else if (size === 0) {
+      size = fileSize - pos;
+    }
+    if (size < hdr) return null;
+    if (type === 'moov') {
+      // mvhd is the first child in practice; 1MB of the box is far more than enough.
+      const body = readAt(fd, pos + hdr, Math.min(size - hdr, 1024 * 1024));
+      return durationFromMoovBody(body);
+    }
+    pos += size;
+  }
+  return null;
+}
+
+const EBML_ID_HEADER = 0x1a45dfa3;
+const EBML_ID_SEGMENT = 0x18538067;
+const EBML_ID_INFO = 0x1549a966;
+const EBML_ID_TIMECODE_SCALE = 0x2ad7b1;
+const EBML_ID_DURATION = 0x4489;
+
+/** Read one EBML element header at buf[pos]; null when truncated/invalid. size -1 = unknown. */
+function ebmlHeader(buf, pos) {
+  if (pos >= buf.length) return null;
+  const b0 = buf[pos];
+  let idLen = 1;
+  while (idLen <= 4 && !(b0 & (0x80 >> (idLen - 1)))) idLen++;
+  if (idLen > 4 || pos + idLen >= buf.length) return null;
+  let id = 0;
+  for (let i = 0; i < idLen; i++) id = id * 256 + buf[pos + i];
+  const s0 = buf[pos + idLen];
+  let sizeLen = 1;
+  while (sizeLen <= 8 && !(s0 & (0x80 >> (sizeLen - 1)))) sizeLen++;
+  if (sizeLen > 8 || pos + idLen + sizeLen > buf.length) return null;
+  let size = s0 & (0xff >> sizeLen);
+  let allOnes = size === (0xff >> sizeLen);
+  for (let i = 1; i < sizeLen; i++) {
+    const b = buf[pos + idLen + i];
+    if (b !== 0xff) allOnes = false;
+    size = size * 256 + b;
+  }
+  return { id, size: allOnes ? -1 : size, dataStart: pos + idLen + sizeLen };
+}
+
+/** webm: find Segment/Info and compute Duration * TimecodeScale (nanoseconds). */
+function webmDuration(fd, fileSize) {
+  // The header region is enough in practice: Segment > SeekHead/Info come before the clusters.
+  const buf = readAt(fd, 0, Math.min(fileSize, 1024 * 1024));
+  let pos = 0;
+  let segmentEnd = buf.length;
+  for (let i = 0; i < 2000; i++) {
+    const el = ebmlHeader(buf, pos);
+    if (!el) return null;
+    if (i === 0 && el.id !== EBML_ID_HEADER) return null; // not a webm/mkv
+    if (el.id === EBML_ID_SEGMENT) {
+      // Descend into the segment: its children follow right after the header.
+      pos = el.dataStart;
+      segmentEnd = el.size < 0 ? buf.length : Math.min(buf.length, el.dataStart + el.size);
+      for (let j = 0; j < 2000 && pos < segmentEnd; j++) {
+        const ch = ebmlHeader(buf, pos);
+        if (!ch) return null;
+        if (ch.id === EBML_ID_INFO) {
+          const end = Math.min(buf.length, ch.dataStart + Math.max(ch.size, 0));
+          return webmInfoDuration(buf, ch.dataStart, end);
+        }
+        if (ch.size < 0) return null; // unknown-size child (cluster) before Info: give up
+        pos = ch.dataStart + ch.size;
+      }
+      return null;
+    }
+    if (el.size < 0) return null;
+    pos = el.dataStart + el.size;
+  }
+  return null;
+}
+
+function webmInfoDuration(buf, start, end) {
+  let timecodeScale = 1000000; // spec default: 1ms
+  let duration = null;
+  let pos = start;
+  for (let i = 0; i < 200 && pos < end; i++) {
+    const el = ebmlHeader(buf, pos);
+    if (!el || el.size < 0) return null;
+    const dEnd = el.dataStart + el.size;
+    if (dEnd > end) return null;
+    if (el.id === EBML_ID_TIMECODE_SCALE) {
+      let v = 0;
+      for (let k = el.dataStart; k < dEnd; k++) v = v * 256 + buf[k];
+      if (v > 0) timecodeScale = v;
+    } else if (el.id === EBML_ID_DURATION) {
+      if (el.size === 4) duration = buf.readFloatBE(el.dataStart);
+      else if (el.size === 8) duration = buf.readDoubleBE(el.dataStart);
+    }
+    pos = dEnd;
+  }
+  if (duration == null) return null;
+  return toSeconds(duration * timecodeScale, 1e9);
+}
+
+/**
+ * Video duration in whole seconds, read from the file itself.
+ * @param {string} filePath
+ * @param {string} ext lower-case extension with dot
+ * @returns {number|null} null when the file cannot be parsed
+ */
+export function parseVideoDuration(filePath, ext) {
+  let fd;
+  try {
+    fd = openSync(filePath, 'r');
+    const size = statSync(filePath).size;
+    if (ext === '.webm') return webmDuration(fd, size);
+    return mp4Duration(fd, size);
+  } catch {
+    return null;
+  } finally {
+    if (fd != null) { try { closeSync(fd); } catch { /* ignore */ } }
+  }
+}
+
+// ============================================================
+// local pre-check
+// ============================================================
+
+/**
+ * Check one local file before anything is sent: exists, regular file (no directory / device /
+ * FIFO / socket), extension whitelist (of the typed name AND of the real file behind a symlink),
+ * size cap, the file's first bytes (must really be an allowed image / video), JPEG GPS data, and
+ * (video) a readable duration. The file content is only read locally here, never sent.
+ *
+ * @param {string} absPath absolute path to read
+ * @param {string} label   what to call the file in messages (the path the user typed)
+ * @param {{keepLocation?:boolean}} [opts] keepLocation: allow a JPEG that carries GPS data
+ * @returns {{ok:true, file:object}|{ok:false, error:string}}
+ */
+export function prepareFile(absPath, label = absPath, opts = {}) {
+  let real;
+  let st;
+  try {
+    real = realpathSync(absPath);
+    st = statSync(real);
+  } catch {
+    return { ok: false, error: `找不到文件：${label}。请检查路径是否写对。` };
+  }
+  if (!st.isFile()) {
+    return { ok: false, error: `${label} 不是普通文件（目录、设备等不能上传）。请指定具体的图片或视频文件。` };
+  }
+  const ext = extname(absPath).toLowerCase();
+  const kind = MEDIA_EXTENSIONS[ext];
+  if (!kind) {
+    return { ok: false, error: `${label} 的格式不支持（${ext || '没有扩展名'}）。只支持：${ALLOWED_EXT_TEXT}。` };
+  }
+  // A symlink named a.png may point at a file with another name: that real name must be allowed too.
+  const realExt = extname(real).toLowerCase();
+  const realKind = MEDIA_EXTENSIONS[realExt];
+  if (!realKind || realKind.mediaType !== kind.mediaType) {
+    return { ok: false, error: `${label} 是符号链接，它实际指向的文件格式不支持（${realExt || '没有扩展名'}）。只支持：${ALLOWED_EXT_TEXT}。没有读取或发送文件内容。` };
+  }
+  const cap = kind.mediaType === 'video' ? MAX_VIDEO_BYTES : MAX_IMAGE_BYTES;
+  if (st.size > cap) {
+    return {
+      ok: false,
+      error: `${label} 太大（${humanSize(st.size)}）。${kind.mediaType === 'video' ? '视频' : '图片'}不能超过 ${cap / 1024 / 1024}MB，请压缩后再试。`,
+    };
+  }
+  if (st.size === 0) {
+    return { ok: false, error: `${label} 是空文件，无法上传。` };
+  }
+
+  // Look at the real first bytes (same magic table as the server). Local read only.
+  let head;
+  let fd;
+  try {
+    fd = openSync(real, 'r');
+    head = readAt(fd, 0, Math.min(st.size, HEAD_READ_BYTES));
+  } catch {
+    return { ok: false, error: `读不了文件：${label}` };
+  } finally {
+    if (fd != null) { try { closeSync(fd); } catch { /* ignore */ } }
+  }
+  const sniffed = sniffMagic(kind.mediaType, head);
+  if (!sniffed) {
+    return {
+      ok: false,
+      error: `${label} 的内容不是有效的${kind.mediaType === 'video' ? '视频' : '图片'}（文件头不符，改扩展名没用）。没有读取或发送文件内容。`,
+    };
+  }
+  if (sniffed === 'image/jpeg' && !opts.keepLocation && jpegHasGps(head)) {
+    return { ok: false, error: `${label}：${GPS_REJECT_TEXT}。` };
+  }
+
+  // The declared type follows the real content (the server insists they agree).
+  let mime = sniffed;
+  let durationExt = ext;
+  if (kind.mediaType === 'video') {
+    if (sniffed === 'video/mp4') { mime = ext === '.mov' ? 'video/quicktime' : 'video/mp4'; durationExt = '.mp4'; }
+    else durationExt = '.webm';
+  }
+  let durationSeconds = null;
+  if (kind.mediaType === 'video') {
+    durationSeconds = parseVideoDuration(real, durationExt);
+    if (durationSeconds == null) {
+      return { ok: false, error: `读不出视频时长：${label}。${VIDEO_DURATION_HINT}` };
+    }
+  }
+  return {
+    ok: true,
+    file: {
+      absPath: real,
+      label,
+      name: basename(absPath),
+      mediaType: kind.mediaType,
+      mime,
+      size: st.size,
+      durationSeconds,
+    },
+  };
+}
+
+// ============================================================
+// error mapping
+// ============================================================
+
+function bodyErrorCode(e) {
+  const b = e && e.body;
+  if (!b || typeof b !== 'object') return null;
+  return b.error || (b.detail && b.detail.error) || null;
+}
+
+/**
+ * Translate a platform error from the upload endpoints into a Chinese message with a next step.
+ * Returns null for errors it does not know (the caller falls back to the raw message).
+ */
+export function mapMediaUploadError(e) {
+  if (!e || typeof e.status !== 'number') return null;
+  const code = bodyErrorCode(e);
+  if (e.status === 429) return HOURLY_LIMIT_HINT;
+  if (e.status === 413) {
+    if (code === 'media_storage_exceeded') return '媒体库已满（50 件 / 500MB），暂时无法再上传。请告知商户，目前需联系平台处理。';
+    return '文件太大：图片不能超过 10MB，视频不能超过 50MB。请压缩后再试。';
+  }
+  if (e.status === 415) return `文件类型不被接受。只支持：${ALLOWED_EXT_TEXT}；文件内容也必须真的是对应格式（改扩展名没用）。`;
+  if (e.status === 422 && code === 'agent_media_cap_exceeded') return 'agent 上传的媒体已达 30 个上限，暂时无法再上传，请告知商户联系平台处理。';
+  if (e.status === 422 && code === 'media_count_exceeded') return '媒体库已满（50 件 / 500MB），暂时无法再上传。请告知商户，目前需联系平台处理。';
+  if (e.status === 422 && code === 'missing_duration') return `视频缺少时长信息。${VIDEO_DURATION_HINT}`;
+  if (e.status === 403 && code === 'agent_scope_forbidden') return '这个操作 agent 不能做（上传接口当前版本可能还没开放给 agent，请联系平台）。';
+  if (e.status === 403) return '没有权限上传：请确认登录的账号是商户本人名下的 agent，必要时重新运行 stelfield auth login。';
+  if (e.status === 401) return '登录状态已失效，请重新运行：stelfield auth login';
+  if (e.status === 404 && code === 'object_not_found') return '文件没有上传成功（存储里找不到），请重试。';
+  if (e.status === 409) return '这个上传地址已经用过，请重试。';
+  return null;
+}
+
+// ============================================================
+// upload loop
+// ============================================================
+
+/**
+ * Upload prepared files one by one: upload-request -> PUT -> confirm.
+ * Files with identical content (sha256) are uploaded once and the result is reused.
+ * The first failure aborts the whole run (a 429 especially: more attempts only waste quota).
+ *
+ * @param {object[]} files   output of prepareFile().file
+ * @param {object}   ctx     { baseUrl, credOpts, fetchImpl?, onProgress?(msg) }
+ * @returns {Promise<object[]>} one result per input, same order:
+ *   { file, ref, mediaId, mediaType, size, uploadedBy, duplicateOf? }
+ * @throws {MediaUploadError} with `.uploaded` = results done before the failure
+ */
+export async function uploadFiles(files, ctx) {
+  const { baseUrl, credOpts, fetchImpl, onProgress } = ctx;
+  const putFetch = fetchImpl || globalThis.fetch;
+  const bySha = new Map();
+  const results = [];
+
+  for (const f of files) {
+    let buf;
+    try {
+      buf = readFileSync(f.absPath);
+    } catch {
+      throw new MediaUploadError(`读不了文件：${f.label}`, { file: f.label, uploaded: results });
+    }
+    if (buf.length !== f.size) {
+      throw new MediaUploadError(`${f.label} 在检查后被改动了，请重试。`, { file: f.label, uploaded: results });
+    }
+    // Second line of defence: the bytes about to be sent must still look like the checked type
+    // (covers a file swapped between the check and now). Nothing has gone to the network yet.
+    if (sniffMagic(f.mediaType, buf.subarray(0, 32)) == null) {
+      throw new MediaUploadError(`${f.label} 的内容不是有效的${f.mediaType === 'video' ? '视频' : '图片'}（文件头不符），没有上传。`, { file: f.label, uploaded: results });
+    }
+    const sha = createHash('sha256').update(buf).digest('hex');
+    const seen = bySha.get(sha);
+    if (seen) {
+      results.push({ ...seen.result, file: f.label, duplicateOf: seen.label });
+      continue;
+    }
+
+    let item;
+    try {
+      if (onProgress) onProgress(`上传 ${f.label}（${humanSize(f.size)}）…`);
+      const req = await requestProfileMediaUpload(
+        baseUrl, credOpts,
+        { media_type: f.mediaType, mime_type: f.mime, file_size_bytes: f.size },
+        { fetchImpl }
+      );
+      if (!req || !req.signed_put_url || !req.object_key) {
+        throw new MediaUploadError('平台没有返回上传地址，请稍后重试。', { file: f.label, uploaded: results });
+      }
+      let putResp;
+      try {
+        putResp = await putFetch(req.signed_put_url, {
+          method: 'PUT',
+          headers: { 'Content-Type': f.mime },
+          body: buf,
+        });
+      } catch (netErr) {
+        throw new MediaUploadError(`上传到存储失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}`, { file: f.label, uploaded: results });
+      }
+      if (!putResp.ok) {
+        throw new MediaUploadError(`上传文件到存储失败（状态 ${putResp.status}），请重试。`, { file: f.label, uploaded: results, status: putResp.status });
+      }
+      const confirmBody = { object_key: req.object_key, media_type: f.mediaType };
+      if (f.mediaType === 'video') confirmBody.duration_seconds = f.durationSeconds;
+      item = await confirmProfileMedia(baseUrl, credOpts, confirmBody, { fetchImpl });
+    } catch (e) {
+      if (e instanceof MediaUploadError) throw e;
+      const mapped = mapMediaUploadError(e);
+      throw new MediaUploadError(mapped || (e && e.message ? e.message : String(e)), {
+        file: f.label, uploaded: results, status: e && typeof e.status === 'number' ? e.status : null,
+      });
+    }
+
+    const mediaId = item.media_id;
+    const result = {
+      file: f.label,
+      ref: item.ref || `${f.mediaType === 'video' ? 'linger://video' : 'linger://media'}/${mediaId}`,
+      mediaId,
+      mediaType: item.media_type || f.mediaType,
+      size: item.file_size_bytes != null ? item.file_size_bytes : f.size,
+      uploadedBy: item.uploaded_by ?? null,
+    };
+    bySha.set(sha, { result, label: f.label });
+    results.push(result);
+  }
+  return results;
+}