@stelfield/cli 0.0.0-stage → 0.12.1

package/src/web-deliver.js

@@ -0,0 +1,332 @@
+// Web-package delivery for sellers (web hosting / CLI 0.10.1).
+//
+// What this does for the user: `stelfield deliver upload --task <id> --web <file>` hands in a
+// single HTML page or a zip site as the delivery of a task, in ONE command. Four steps, all
+// offered by the platform already:
+//   1. ask for an upload address (POST /uploads, kind=deliverable, web_package=true)
+//   2. PUT the bytes straight to storage
+//   3. register the package so the platform can check and unpack it
+//      (POST /tasks/{id}/web-packages)
+//   4. deliver it with the normal deliver flow (same idempotency-key rule as `task deliver`)
+//
+// This file holds everything that is NOT command parsing:
+//   - the local pre-check (exists / regular file / extension / size / zip header),
+//   - the Chinese fix-it advice for each backend reject_code,
+//   - the "upload restricted" explanation (reason, time left, how to appeal),
+//   - the four-step flow itself, with fetch injectable for tests.
+//
+// Limits mirror the backend risk policy (RISK_WEB_ZIP_MAX_MB = 20, unzipped 50MB, 300 files).
+
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { getTaskDeliverables, registerWebPackage, requestUpload, runtimeAct } from './api.js';
+import { humanSize } from './media-upload.js';
+
+export const WEB_ZIP_MAX_BYTES = 20 * 1024 * 1024;
+/** A single HTML file has no zip limit; the unzipped cap (50MB) is the ceiling. */
+export const WEB_HTML_MAX_BYTES = 50 * 1024 * 1024;
+export const WEB_UNZIPPED_MAX_MB = 50;
+export const WEB_FILES_MAX = 300;
+
+const MIME_BY_EXT = {
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.zip': 'application/zip',
+};
+
+/** Error carrying a ready-to-print Chinese message and the exit code to use. */
+export class WebDeliverError extends Error {
+  constructor(message, { exitCode = 1, status = null } = {}) {
+    super(message);
+    this.name = 'WebDeliverError';
+    this.exitCode = exitCode;
+    this.status = status;
+  }
+}
+
+// ============================================================
+// local pre-check
+// ============================================================
+
+/**
+ * Check the file before anything goes to the network.
+ * @returns {{absPath:string, filename:string, mime:string, isZip:boolean, size:number, buf:Buffer}}
+ * @throws {WebDeliverError} exit code 2 (the caller can fix it and retry)
+ */
+export function prepareWebPackage(file) {
+  if (!file) {
+    throw new WebDeliverError('缺少 --web 参数：请给出要交付的网页文件（单个 .html，或根目录有 index.html 的 .zip）。', { exitCode: 2 });
+  }
+  let absPath;
+  let st;
+  try {
+    absPath = realpathSync(file);
+    st = statSync(absPath);
+  } catch {
+    throw new WebDeliverError(`找不到文件：${file}。请检查路径。`, { exitCode: 2 });
+  }
+  if (!st.isFile()) {
+    throw new WebDeliverError(`${file} 不是文件。网页包必须是单个 .html 文件，或打包好的 .zip（不能直接给文件夹，请先压缩成 zip）。`, { exitCode: 2 });
+  }
+  const ext = extname(absPath).toLowerCase();
+  const mime = MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new WebDeliverError(`不支持的文件类型「${ext || '无扩展名'}」。网页包只能是 .html / .htm（单个页面）或 .zip（站点包，入口页请命名为 index.html 并放在根目录）。`, { exitCode: 2 });
+  }
+  const isZip = mime === 'application/zip';
+  if (st.size === 0) {
+    throw new WebDeliverError('文件是空的。请确认网页内容已生成，再重新交付。', { exitCode: 2 });
+  }
+  if (isZip && st.size > WEB_ZIP_MAX_BYTES) {
+    throw new WebDeliverError(`zip 有 ${humanSize(st.size)}，超过 20MB 上限。请删掉不必要的大文件（大图可压缩，视频建议改用外链或去掉）后重新打包。`, { exitCode: 2 });
+  }
+  if (!isZip && st.size > WEB_HTML_MAX_BYTES) {
+    throw new WebDeliverError(`HTML 文件有 ${humanSize(st.size)}，超过 ${WEB_UNZIPPED_MAX_MB}MB 上限。请精简内容，或拆成 zip 站点包（资源放包内，zip ≤ 20MB）。`, { exitCode: 2 });
+  }
+  let buf;
+  try {
+    buf = readFileSync(absPath);
+  } catch {
+    throw new WebDeliverError(`读不了文件：${file}。`, { exitCode: 2 });
+  }
+  if (isZip && !(buf[0] === 0x50 && buf[1] === 0x4b)) {
+    throw new WebDeliverError('这个 .zip 文件头不对，不是有效的 zip。请用 zip 工具重新打包（例如在站点目录里运行 `zip -r ../site.zip .`）。', { exitCode: 2 });
+  }
+  return { absPath, filename: basename(absPath), mime, isZip, size: st.size, buf };
+}
+
+// ============================================================
+// error advice
+// ============================================================
+
+/** reject_code -> what to tell the agent to fix. */
+export const REJECT_ADVICE = {
+  too_large: '网页包太大：zip 不能超过 20MB，解压后不能超过 50MB。请删掉不必要的大文件或压缩图片后重新打包。',
+  too_many_files: `包里的文件太多：最多 ${WEB_FILES_MAX} 个文件。请合并或删掉不用的文件（例如 node_modules、日志、素材原图）后重新打包。`,
+  no_index: '包的根目录里没有任何 .html 文件。请把入口页放在 zip 的最外层并命名为 index.html（注意不要多套一层文件夹：应在站点目录里运行 `zip -r ../site.zip .`，而不是压缩文件夹本身）。',
+  ambiguous_index: '包的根目录里有多个 .html 文件，但没有 index.html，平台无法判断哪个是入口页。请把入口页改名为 index.html（根目录只有一个 .html 时平台会自动当作入口）后重新打包。',
+  bad_path: '包里有不合法的路径（含 `..` 或绝对路径、符号链接）。请用相对路径重新打包，不要引用包外文件。',
+  forbidden_file: '包里含有禁止的文件：可执行文件和服务端脚本（.php .asp .aspx .jsp .cgi .pl .py .rb .sh、.exe 等）不能放进网页包。网页只能是静态内容（HTML / CSS / JS / 图片 / 字体）。请删掉后重新打包。',
+  not_zip: '平台没能把它当作 zip 解开。请用 zip 工具重新打包后再试。',
+  empty: '包里没有可展示的文件。请确认网页内容已放进去，再重新打包。',
+};
+
+function bodyOf(e) {
+  const b = e && e.body && typeof e.body === 'object' ? e.body : {};
+  const d = b.detail && typeof b.detail === 'object' ? b.detail : {};
+  return { ...d, ...b };
+}
+
+/** "3 天 4 小时" / "5 小时 10 分钟" / "不到 1 分钟"; null when `until` cannot be read. */
+export function formatRemaining(until, now = Date.now()) {
+  const t = Date.parse(until);
+  if (!Number.isFinite(t)) return null;
+  const sec = Math.floor((t - now) / 1000);
+  if (sec <= 0) return '即将解除';
+  const d = Math.floor(sec / 86400);
+  const h = Math.floor((sec % 86400) / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  if (d > 0) return h > 0 ? `${d} 天 ${h} 小时` : `${d} 天`;
+  if (h > 0) return m > 0 ? `${h} 小时 ${m} 分钟` : `${h} 小时`;
+  return m > 0 ? `${m} 分钟` : '不到 1 分钟';
+}
+
+/**
+ * Turn an API error into a user-facing Chinese message; null when it is not a web-delivery error
+ * (the caller then prints the plain error text).
+ */
+export function mapWebDeliverError(e, now = Date.now()) {
+  if (!e || typeof e.status !== 'number') return null;
+  const b = bodyOf(e);
+  const code = b.error;
+
+  if (e.status === 403 && code === 'web_upload_restricted') {
+    const lines = ['暂时不能交付网页：你的网页交付功能目前处于限制期。'];
+    if (b.reason) lines.push(`  限制原因：${b.reason}`);
+    if (b.until) {
+      const left = formatRemaining(b.until, now);
+      lines.push(`  解除时间：${b.until}${left ? `（还剩 ${left}）` : ''}`);
+    }
+    lines.push('  限制到期会自动解除，期间不影响其他类型的交付（文字、普通文件）。');
+    lines.push('  如果认为判断有误：请告诉你的用户，到任务的「交付物」页点「申诉」，由 AI 独立复核；通过后限制会立即解除。');
+    return lines.join('\n');
+  }
+  if (e.status === 422 && code === 'web_package_invalid') {
+    const rc = b.reject_code;
+    const advice = REJECT_ADVICE[rc];
+    const lines = [`网页包没有通过检查${rc ? `（${rc}）` : ''}。`];
+    if (b.message) lines.push(`  平台说明：${b.message}`);
+    lines.push(`  怎么改：${advice || '请按「网页包要求」检查后重新打包（运行 stelfield --help 查看）。'}`);
+    return lines.join('\n');
+  }
+  if (e.status === 503 && code === 'web_hosting_disabled') {
+    return '网页托管暂时关闭，现在不能交付网页包。请稍后再试，或先用普通文件交付。';
+  }
+  if (e.status === 409 && code === 'web_package_not_registered') {
+    return '网页包还没登记成功就被拒绝交付（web_package_not_registered）。请重新运行同一条命令。';
+  }
+  return null;
+}
+
+// ============================================================
+// the four-step flow
+// ============================================================
+
+/**
+ * Optional "which models, roughly how many tokens" note that rides along with a delivery (#117).
+ * Returns the extra result_payload fields, or {} when nothing was given. It never changes the idempotency key.
+ */
+export function usageFields(models, tokens) {
+  const out = {};
+  const list = String(models == null ? '' : models).split(/[,，]/).map((s) => s.trim()).filter(Boolean).slice(0, 5);
+  if (list.length) out.models = list;
+  if (Number.isFinite(tokens) && tokens > 0) out.tokens_approx = Math.round(tokens);
+  return out;
+}
+
+/** Same shape as the `task deliver` key: deliver-{task}-{caller sub}-{sha256[:16]}. */
+export function buildWebDeliverIdemKey(taskId, token, note, fileId) {
+  let callerSub = 'unknown-caller';
+  try {
+    const payloadB64 = String(token || '').split('.')[1];
+    if (payloadB64) {
+      const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+      callerSub = payload.sub || payload.agent_id || 'unknown-caller';
+    }
+  } catch { /* non-JWT token: keep fallback */ }
+  const digest = createHash('sha256').update((note || '') + (fileId || '')).digest('hex').slice(0, 16);
+  return `deliver-${taskId}-${callerSub}-${digest}`;
+}
+
+/**
+ * Run the whole upload -> register -> deliver flow.
+ *
+ * @param {object} ctx { baseUrl, credOpts, fetchImpl?, token, taskId, file, note?, idemKey?, onProgress?(msg) }
+ * @returns {Promise<object>} { taskId, fileId, round, sizeBytes, filesCount, unzippedBytes, isZip, filename, deliver }
+ * @throws {WebDeliverError} message already in Chinese
+ */
+export async function deliverWebPackage(ctx) {
+  const { baseUrl, credOpts, fetchImpl, token, taskId, note, idemKey, onProgress } = ctx;
+  const pkg = prepareWebPackage(ctx.file);
+  const progress = onProgress || (() => {});
+  const sha = createHash('sha256').update(pkg.buf).digest('hex');
+
+  const wrap = (e, step) => {
+    if (e instanceof WebDeliverError) return e;
+    if (e && e.upgradeRequired) throw e; // let the top-level handler print the upgrade hint (exit 4)
+    const mapped = mapWebDeliverError(e);
+    const text = mapped || `${step}失败：${e && e.message ? e.message : String(e)}`;
+    return new WebDeliverError(text, { status: e && typeof e.status === 'number' ? e.status : null });
+  };
+
+  // 1. ask for an upload address. The key depends on the file bytes, so running the same command
+  //    again gets the same file_id back instead of piling up duplicate uploads.
+  progress(`申请上传（${pkg.filename}，${humanSize(pkg.size)}）…`);
+  let req;
+  try {
+    req = await requestUpload(baseUrl, credOpts, {
+      task_id: taskId,
+      kind: 'deliverable',
+      mime_type: pkg.mime,
+      size_bytes: pkg.size,
+      filename: pkg.filename,
+      web_package: true,
+    }, { fetchImpl, idempotencyKey: `web-upload-${taskId}-${sha.slice(0, 32)}` });
+  } catch (e) {
+    throw wrap(e, '申请上传');
+  }
+  if (!req || !req.signed_put_url || !req.file_id) {
+    throw new WebDeliverError('平台没有返回上传地址，请稍后重试。');
+  }
+
+  // 2. direct upload
+  progress('上传文件…');
+  const putFetch = fetchImpl || globalThis.fetch;
+  let putResp;
+  try {
+    putResp = await putFetch(req.signed_put_url, {
+      method: 'PUT',
+      headers: { 'Content-Type': pkg.mime },
+      body: pkg.buf,
+    });
+  } catch (netErr) {
+    throw new WebDeliverError(`上传到存储失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
+  }
+  if (!putResp.ok) {
+    throw new WebDeliverError(`上传文件到存储失败（状态 ${putResp.status}），可重新运行同一条命令。`, { status: putResp.status });
+  }
+
+  // 3. register: the platform unpacks and checks it
+  progress('检查并登记网页包…');
+  let reg;
+  try {
+    reg = await registerWebPackage(baseUrl, credOpts, taskId, req.file_id, { fetchImpl });
+  } catch (e) {
+    throw wrap(e, '登记网页包');
+  }
+
+  // 4. deliver, same flow and key rule as `task deliver --file-id`
+  progress('提交交付…');
+  const resultPayload = { file_id: req.file_id, type: 'file', ...usageFields(ctx.models, ctx.tokens) };
+  if (note) resultPayload.text = note;
+  const deliverKey = idemKey || buildWebDeliverIdemKey(taskId, token, note, req.file_id);
+  let deliver;
+  try {
+    deliver = await runtimeAct(baseUrl, credOpts, 'deliver_job', { job_id: taskId, result_payload: resultPayload }, deliverKey, { fetchImpl });
+  } catch (e) {
+    throw wrap(e, '提交交付');
+  }
+
+  // Best effort: read back the version number and the package facts. Delivery already succeeded,
+  // so any failure here only means the summary shows fewer details.
+  let round = null;
+  let web = null;
+  try {
+    const view = await getTaskDeliverables(baseUrl, credOpts, taskId, { fetchImpl });
+    const versions = Array.isArray(view && view.versions) ? view.versions : [];
+    const hit = versions.find((v) => Array.isArray(v.files) && v.files.some((f) => f.id === req.file_id || f.file_id === req.file_id));
+    if (hit) {
+      round = hit.round ?? null;
+      web = hit.web || null;
+    }
+  } catch { /* summary only */ }
+
+  return {
+    taskId,
+    fileId: req.file_id,
+    round,
+    sizeBytes: web && web.size_bytes != null ? web.size_bytes : pkg.size,
+    filesCount: web && web.files_count != null ? web.files_count : (reg && reg.files_count != null ? reg.files_count : null),
+    unzippedBytes: web && web.unzipped_bytes != null ? web.unzipped_bytes : (reg && reg.unzipped_bytes != null ? reg.unzipped_bytes : null),
+    isZip: pkg.isZip,
+    filename: pkg.filename,
+    deliver,
+  };
+}
+
+/** Human-readable success summary (or JSON). */
+export function formatWebDeliver(r, { json = false } = {}) {
+  if (json) {
+    return JSON.stringify({
+      ok: true,
+      task_id: r.taskId,
+      file_id: r.fileId,
+      version: r.round,
+      size_bytes: r.sizeBytes,
+      files_count: r.filesCount,
+      unzipped_bytes: r.unzippedBytes,
+      status: r.deliver && r.deliver.to_status ? r.deliver.to_status : null,
+    }, null, 2);
+  }
+  const lines = ['网页已交付！（系统自动进入待验收）'];
+  lines.push(`  任务 ID：${r.taskId}`);
+  lines.push(`  交付版本：${r.round != null ? `第 ${r.round} 版` : '（已提交）'}`);
+  lines.push(`  包大小：${humanSize(r.sizeBytes)}`);
+  lines.push(`  文件数：${r.filesCount != null ? r.filesCount : (r.isZip ? '?' : 1)}`);
+  if (r.deliver && r.deliver.from_status && r.deliver.to_status) {
+    lines.push(`  状态变更：${r.deliver.from_status} → ${r.deliver.to_status}`);
+  }
+  lines.push('买家可在交付物页预览；成交后买家可自行生成公开链接（公开链接只能由买家生成，你可以在网页上「建议买家公开」）。');
+  return lines.join('\n');
+}