@sireai/optimus 0.1.44 → 0.1.46

package/embedded-skills/shared/feishu-task-inputs/scripts/fetch-feishu-doc.mjs

@@ -0,0 +1,756 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+
+const CREDENTIAL_XOR_KEY = "feishu@2026!Mi";
+const DEFAULT_FEISHU_BASE_URL = "https://open.feishu.cn";
+const BUILTIN_APP_ID = decodeCredential("0509002c09147854030b5044285e005c50100b47");
+const BUILTIN_APP_SECRET = decodeCredential("2c5513430a307864685d574a391a2d0e1f0629010754634a5e5b0151042a0604");
+const FEISHU_DOCUMENT_HOST_PATTERN = /^(?:[\w-]+\.)?(?:feishu\.cn|larksuite\.com)$/iu;
+const DOCX_PATH_PATTERN = /\/docx\/([A-Za-z0-9]+)/u;
+const WIKI_PATH_PATTERN = /\/wiki\/([A-Za-z0-9]+)/u;
+const CHILDREN_PAGE_SIZE = "200";
+const KNOWN_BLOCK_KEYS = [
+  "page", "heading1", "heading2", "heading3", "heading4", "heading5", "heading6",
+  "heading7", "heading8", "heading9", "text", "bullet", "ordered", "todo", "code",
+  "quote", "callout", "equation", "divider", "image", "whiteboard", "file", "sheet",
+  "bitable", "table", "table_cell", "diagram", "mindnote", "embed", "iframe", "grid",
+  "grid_column", "view"
+];
+
+export async function fetchFeishuDoc({
+  url,
+  outputDir,
+  fetchImpl = globalThis.fetch?.bind(globalThis),
+  appId = process.env.OPTIMUS_FEISHU_AUTH_APP_ID?.trim() || BUILTIN_APP_ID,
+  appSecret = process.env.OPTIMUS_FEISHU_AUTH_APP_SECRET?.trim() || BUILTIN_APP_SECRET,
+  baseUrl = normalizeBaseUrl(process.env.OPTIMUS_FEISHU_BASE_URL?.trim() || process.env.FEISHU_BASE_URL?.trim() || DEFAULT_FEISHU_BASE_URL)
+}) {
+  if (!fetchImpl) {
+    throw new Error("Global fetch is unavailable.");
+  }
+  if (!url?.trim()) {
+    throw new Error("Missing --url.");
+  }
+  if (!outputDir?.trim()) {
+    throw new Error("Missing --output-dir.");
+  }
+
+  const parsed = parseFeishuDocumentUrl(url);
+  if (!parsed) {
+    throw new Error("Only Feishu/Lark docx and wiki URLs are supported.");
+  }
+
+  await mkdir(outputDir, { recursive: true });
+  const accessToken = await getTenantAccessToken(fetchImpl, baseUrl, appId, appSecret);
+  const client = createClient(fetchImpl, baseUrl, accessToken);
+  const target = await resolveTarget(client, parsed);
+  const document = await client.get(`/open-apis/docx/v1/documents/${encodeURIComponent(target.documentToken)}`);
+  const title = readStringDeep(document, ["data.document.title"]) || target.title;
+  const blocks = await readDocumentTree(client, target.documentToken);
+  const rendered = renderDocument(blocks, target.documentToken, title);
+  const localizedReferences = await downloadReferenceMaterials(client, rendered.referenceMaterials ?? [], join(outputDir, "attachments"));
+  const manifest = {
+    title: title || null,
+    sourceUrl: url,
+    sourceType: "feishu_doc",
+    sourceDocumentType: target.sourceDocumentType,
+    contentPath: join(outputDir, "content.md"),
+    referenceMaterials: localizedReferences
+  };
+
+  await writeFile(join(outputDir, "content.md"), `${rendered.content.trim()}\n`, "utf8");
+  await writeFile(join(outputDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return manifest;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help || args.h) {
+    console.log(usage());
+    return;
+  }
+  const manifest = await fetchFeishuDoc({
+    url: args.url,
+    outputDir: args["output-dir"]
+  });
+  console.log(JSON.stringify({
+    title: manifest.title,
+    sourceUrl: manifest.sourceUrl,
+    sourceDocumentType: manifest.sourceDocumentType,
+    contentPath: manifest.contentPath,
+    attachmentCount: manifest.referenceMaterials.filter((entry) => entry.localPath).length
+  }, null, 2));
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  fetch-feishu-doc --url <feishu-doc-or-wiki-url> --output-dir <dir>"
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith("--")) {
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      parsed[key] = "true";
+      continue;
+    }
+    parsed[key] = next;
+    index += 1;
+  }
+  return parsed;
+}
+
+function createClient(fetchImpl, baseUrl, accessToken) {
+  return {
+    async get(path, query) {
+      const url = buildUrl(baseUrl, path, query);
+      const response = await fetchImpl(url, {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${accessToken}`
+        }
+      });
+      return await readJsonResponse(response);
+    },
+    async getBinary(path, query) {
+      const url = buildUrl(baseUrl, path, query);
+      const response = await fetchImpl(url, {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${accessToken}`
+        }
+      });
+      if (!response.ok) {
+        throw new Error(`Binary download failed: ${response.status} ${response.statusText}`.trim());
+      }
+      const buffer = Buffer.from(await response.arrayBuffer());
+      return {
+        buffer,
+        contentType: response.headers.get("content-type")?.trim() || undefined,
+        fileName: readFileNameFromHeaders(response.headers)
+      };
+    }
+  };
+}
+
+async function getTenantAccessToken(fetchImpl, baseUrl, appId, appSecret) {
+  const response = await fetchImpl(`${baseUrl}/open-apis/auth/v3/tenant_access_token/internal`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json; charset=utf-8"
+    },
+    body: JSON.stringify({
+      app_id: appId,
+      app_secret: appSecret
+    })
+  });
+  const payload = await readJsonResponse(response);
+  const token = readStringDeep(payload, ["tenant_access_token"]);
+  if (!response.ok || !token) {
+    throw new Error(`Failed to acquire Feishu tenant token: ${JSON.stringify(payload)}`);
+  }
+  return token;
+}
+
+function buildUrl(baseUrl, path, query) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(`${baseUrl}${normalizedPath}`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (typeof value === "string" && value.trim()) {
+      url.searchParams.set(key, value.trim());
+    }
+  }
+  return url.toString();
+}
+
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function parseFeishuDocumentUrl(input) {
+  const trimmed = input?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (!FEISHU_DOCUMENT_HOST_PATTERN.test(url.hostname)) {
+    return undefined;
+  }
+  const docxMatch = url.pathname.match(DOCX_PATH_PATTERN);
+  if (docxMatch?.[1]) {
+    return { kind: "docx", token: docxMatch[1], url: trimmed };
+  }
+  const wikiMatch = url.pathname.match(WIKI_PATH_PATTERN);
+  if (wikiMatch?.[1]) {
+    return { kind: "wiki", token: wikiMatch[1], url: trimmed };
+  }
+  return undefined;
+}
+
+async function resolveTarget(client, parsed) {
+  if (parsed.kind === "docx") {
+    return {
+      sourceUrl: parsed.url,
+      sourceDocumentType: "docx",
+      documentToken: parsed.token
+    };
+  }
+  const payload = await client.get("/open-apis/wiki/v2/spaces/get_node", { token: parsed.token });
+  const target = extractWikiDocTarget(payload);
+  if (!target?.documentToken || target.documentType !== "docx") {
+    throw new Error("Failed to resolve wiki docx target.");
+  }
+  return {
+    sourceUrl: parsed.url,
+    sourceDocumentType: target.documentType,
+    documentToken: target.documentToken,
+    title: target.title
+  };
+}
+
+function extractWikiDocTarget(payload) {
+  if (!payload || typeof payload !== "object") {
+    return undefined;
+  }
+  if (Array.isArray(payload)) {
+    for (const entry of payload) {
+      const target = extractWikiDocTarget(entry);
+      if (target?.documentToken || target?.documentType) {
+        return target;
+      }
+    }
+    return undefined;
+  }
+  const documentType = readStringDeep(payload, ["obj_type", "objType", "object_type", "objectType"]);
+  const documentToken = readStringDeep(payload, ["obj_token", "objToken", "document_id", "documentId", "doc_token", "docToken"]);
+  const title = readStringDeep(payload, ["title", "name"]);
+  if (documentType || documentToken || title) {
+    return { documentType, documentToken, title };
+  }
+  for (const value of Object.values(payload)) {
+    const nested = extractWikiDocTarget(value);
+    if (nested?.documentToken || nested?.documentType) {
+      return nested;
+    }
+  }
+  return undefined;
+}
+
+async function readDocumentTree(client, documentToken) {
+  const blocks = new Map();
+  blocks.set(documentToken, {
+    blockId: documentToken,
+    children: [],
+    hasChild: true,
+    raw: {}
+  });
+
+  const queue = [documentToken];
+  while (queue.length > 0) {
+    const parentId = queue.shift();
+    const childBlocks = await fetchChildren(client, documentToken, parentId);
+    const orderedIds = [];
+    for (const block of childBlocks) {
+      orderedIds.push(block.blockId);
+      blocks.set(block.blockId, block);
+      if (block.hasChild) {
+        queue.push(block.blockId);
+      }
+    }
+    const parent = blocks.get(parentId);
+    if (parent) {
+      parent.children = orderedIds;
+    }
+  }
+  return blocks;
+}
+
+async function fetchChildren(client, documentToken, parentId) {
+  const blocks = [];
+  let pageToken;
+  while (true) {
+    const payload = await client.get(
+      `/open-apis/docx/v1/documents/${encodeURIComponent(documentToken)}/blocks/${encodeURIComponent(parentId)}/children`,
+      {
+        page_size: CHILDREN_PAGE_SIZE,
+        ...(pageToken ? { page_token: pageToken } : {})
+      }
+    );
+    const items = Array.isArray(payload?.data?.items) ? payload.data.items : [];
+    for (const item of items) {
+      const block = normalizeBlockRecord(item);
+      if (block) {
+        blocks.push(block);
+      }
+    }
+    if (!payload?.data?.has_more || !payload?.data?.page_token?.trim()) {
+      break;
+    }
+    pageToken = payload.data.page_token.trim();
+  }
+  return blocks;
+}
+
+function normalizeBlockRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const blockId = typeof value.block_id === "string" ? value.block_id.trim() : "";
+  if (!blockId) {
+    return undefined;
+  }
+  const parentId = typeof value.parent_id === "string" && value.parent_id.trim() ? value.parent_id.trim() : undefined;
+  const children = Array.isArray(value.children)
+    ? value.children.filter((entry) => typeof entry === "string" && entry.trim().length > 0).map((entry) => entry.trim())
+    : [];
+  return {
+    blockId,
+    parentId,
+    children,
+    hasChild: value.has_child === true || children.length > 0,
+    raw: value
+  };
+}
+
+function renderDocument(blocks, rootId, title) {
+  const state = {
+    noteReferences: [],
+    seenReferenceKeys: new Set(),
+    containerCounters: {}
+  };
+  const lines = [];
+  if (title) {
+    lines.push(`# ${title}`, "");
+  }
+  lines.push(...renderChildren(rootId, blocks, state, 0));
+  return {
+    content: lines.join("\n").replace(/\n{3,}/gu, "\n\n").trim(),
+    referenceMaterials: state.noteReferences
+  };
+}
+
+function renderChildren(parentId, blocks, state, depth) {
+  const parent = blocks.get(parentId);
+  if (!parent) {
+    return [];
+  }
+  const lines = [];
+  parent.children.forEach((childId, index) => {
+    const child = blocks.get(childId);
+    if (!child) {
+      return;
+    }
+    const rendered = renderBlock(child, blocks, state, depth, index);
+    if (!rendered.length) {
+      return;
+    }
+    if (lines.length > 0 && rendered[0] !== "" && lines.at(-1) !== "") {
+      lines.push("");
+    }
+    lines.push(...rendered);
+  });
+  return lines;
+}
+
+function renderBlock(block, blocks, state, depth, index) {
+  const kind = detectBlockKind(block.raw);
+  const childLines = block.children.length > 0 ? renderChildren(block.blockId, blocks, state, depth + 1) : [];
+  switch (kind) {
+    case "page":
+    case "view":
+    case "grid":
+    case "grid_column":
+      return childLines;
+    case "heading1":
+    case "heading2":
+    case "heading3":
+    case "heading4":
+    case "heading5":
+    case "heading6":
+    case "heading7":
+    case "heading8":
+    case "heading9": {
+      const level = Number(kind.replace("heading", "")) || 1;
+      return [`${"#".repeat(Math.min(6, level))} ${renderRichBlockText(block.raw[kind])}`];
+    }
+    case "text": {
+      const text = renderRichBlockText(block.raw.text);
+      return text ? [text] : childLines;
+    }
+    case "bullet":
+      return renderListItem("-", renderRichBlockText(block.raw.bullet), childLines);
+    case "ordered":
+      return renderListItem(`${index + 1}.`, renderRichBlockText(block.raw.ordered), childLines);
+    case "todo": {
+      const done = readBooleanDeep(block.raw.todo, ["checked", "is_checked", "done"]);
+      return renderListItem(done ? "- [x]" : "- [ ]", renderRichBlockText(block.raw.todo), childLines);
+    }
+    case "quote":
+      return prefixLines(`> ${renderRichBlockText(block.raw.quote)}`.trimEnd(), childLines, "> ");
+    case "callout":
+      return prefixLines(`> [!NOTE] ${renderRichBlockText(block.raw.callout)}`.trimEnd(), childLines, "> ");
+    case "code": {
+      const language = readStringDeep(block.raw.code, ["language", "lang"]) || "";
+      const content = renderRichBlockText(block.raw.code, { preserveNewlines: true });
+      return [`\`\`\`${language}`, content || "", "```", ...indentLines(childLines, "  ")];
+    }
+    case "equation":
+      return [`$$${renderRichBlockText(block.raw.equation, { preserveNewlines: true })}$$`];
+    case "divider":
+      return ["---"];
+    case "image":
+      return [renderMediaTag("img", block.raw.image, state, { titlePrefix: "Embedded image", defaultType: "image" })];
+    case "whiteboard":
+      return [renderMediaTag("whiteboard", block.raw.whiteboard, state, { titlePrefix: "Embedded whiteboard", defaultType: "whiteboard" })];
+    case "file":
+      return [renderMediaTag("file", block.raw.file, state, { titlePrefix: "Embedded file", defaultType: "file" })];
+    case "sheet":
+      return [renderMediaTag("sheet", block.raw.sheet, state, { titlePrefix: "Embedded sheet", defaultType: "sheet" })];
+    case "bitable":
+      return [renderMediaTag("bitable", block.raw.bitable, state, { titlePrefix: "Embedded bitable", defaultType: "bitable" })];
+    default:
+      return childLines;
+  }
+}
+
+function renderMediaTag(tagName, payload, state, options) {
+  const title = readStringDeep(payload, ["name", "title"]) || nextContainerTitle(state, tagName, options.titlePrefix);
+  const token = readStringDeep(payload, ["token", "file_token", "image_token", "src"]);
+  const url = readStringDeep(payload, ["url", "link"]);
+  const mimeType = readStringDeep(payload, ["mime_type", "mime", "type"]);
+  if (payload && typeof payload === "object") {
+    pushNoteReference(state, {
+      type: options.defaultType,
+      title,
+      ...(token ? { token } : {}),
+      ...(url ? { url } : {}),
+      ...(mimeType ? { mimeType } : {}),
+      sourceType: "feishu_block"
+    });
+  }
+  const attributes = [
+    `name="${escapeHtmlAttribute(title)}"`,
+    ...(token ? [tagName === "img" ? `src="${escapeHtmlAttribute(token)}"` : `token="${escapeHtmlAttribute(token)}"`] : []),
+    ...(url ? [`url="${escapeHtmlAttribute(url)}"`] : []),
+    ...(mimeType ? [`mime="${escapeHtmlAttribute(mimeType)}"`] : [])
+  ];
+  return `<${tagName} ${attributes.join(" ")}/>`;
+}
+
+function renderRichBlockText(payload, options = {}) {
+  const elements = findElementsArray(payload);
+  if (elements.length > 0) {
+    const rendered = elements.map((element) => renderTextElement(element)).join("");
+    return options.preserveNewlines ? rendered : rendered.replace(/\s+\n/gu, "\n").trim();
+  }
+  return readStringDeep(payload, ["content", "text", "title", "caption"]) || "";
+}
+
+function renderTextElement(element) {
+  if (!element || typeof element !== "object" || Array.isArray(element)) {
+    return "";
+  }
+  if (element.text_run && typeof element.text_run === "object") {
+    const content = typeof element.text_run.content === "string" ? element.text_run.content : "";
+    const style = element.text_run.text_element_style;
+    const link = readStringDeep(element.text_run, ["link.url", "href", "url"]) || readStringDeep(style, ["link.url", "href", "url"]);
+    return applyInlineStyle(link ? `[${content}](${link})` : content, style);
+  }
+  if (element.mention_doc && typeof element.mention_doc === "object") {
+    const title = readStringDeep(element.mention_doc, ["title", "name"]) || "document";
+    const url = readStringDeep(element.mention_doc, ["url", "link"]);
+    return url ? `[${title}](${url})` : title;
+  }
+  if (element.mention_user && typeof element.mention_user === "object") {
+    return `@${readStringDeep(element.mention_user, ["name", "title", "display_name"]) || "user"}`;
+  }
+  return readStringDeep(element, ["text", "content", "title"]) || "";
+}
+
+function pushNoteReference(state, reference) {
+  const key = [reference.type, reference.title, reference.token || "", reference.url || "", reference.content || ""].join("|");
+  if (state.seenReferenceKeys.has(key)) {
+    return;
+  }
+  state.seenReferenceKeys.add(key);
+  state.noteReferences.push(reference);
+}
+
+function nextContainerTitle(state, counterKey, prefix) {
+  const next = (state.containerCounters[counterKey] || 0) + 1;
+  state.containerCounters[counterKey] = next;
+  return `${prefix} ${next}`;
+}
+
+async function downloadReferenceMaterials(client, materials, attachmentsDir) {
+  await mkdir(attachmentsDir, { recursive: true });
+  const output = [];
+  for (const material of materials) {
+    if (material.type !== "file" && material.type !== "image") {
+      output.push(material);
+      continue;
+    }
+    const token = material.token?.trim();
+    if (!token) {
+      output.push({ ...material, downloadStatus: "skipped", downloadError: "download_token_missing" });
+      continue;
+    }
+    const candidatePaths = material.type === "image"
+      ? [`/open-apis/drive/v1/medias/${encodeURIComponent(token)}/download`, `/open-apis/drive/v1/files/${encodeURIComponent(token)}/download`]
+      : [`/open-apis/drive/v1/files/${encodeURIComponent(token)}/download`, `/open-apis/drive/v1/medias/${encodeURIComponent(token)}/download`];
+    let lastError = "download_failed";
+    let downloaded = false;
+    for (const path of candidatePaths) {
+      try {
+        const binary = await client.getBinary(path);
+        const fileName = ensureExtension(resolvePreferredFileName(material, binary.fileName, binary.contentType), material, binary.contentType);
+        const outputPath = join(attachmentsDir, fileName);
+        await writeFile(outputPath, binary.buffer);
+        output.push({
+          ...material,
+          localPath: outputPath,
+          downloadStatus: "downloaded",
+          ...(binary.contentType ? { mimeType: material.mimeType || binary.contentType } : {})
+        });
+        downloaded = true;
+        break;
+      } catch (error) {
+        lastError = error instanceof Error ? error.message : String(error);
+      }
+    }
+    if (!downloaded) {
+      output.push({ ...material, downloadStatus: "failed", downloadError: lastError });
+    }
+  }
+  return output;
+}
+
+function detectBlockKind(raw) {
+  return KNOWN_BLOCK_KEYS.find((key) => key in raw);
+}
+
+function findElementsArray(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [];
+  }
+  if (Array.isArray(value.elements)) {
+    return value.elements;
+  }
+  for (const nested of Object.values(value)) {
+    const elements = findElementsArray(nested);
+    if (elements.length > 0) {
+      return elements;
+    }
+  }
+  return [];
+}
+
+function readStringDeep(value, keys) {
+  for (const key of keys) {
+    const direct = readDottedString(value, key);
+    if (direct) {
+      return direct;
+    }
+  }
+  return undefined;
+}
+
+function readDottedString(value, dottedKey) {
+  const parts = dottedKey.split(".");
+  let current = value;
+  for (const part of parts) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return typeof current === "string" && current.trim() ? current.trim() : undefined;
+}
+
+function readBooleanDeep(value, keys) {
+  for (const key of keys) {
+    const parts = key.split(".");
+    let current = value;
+    for (const part of parts) {
+      if (!current || typeof current !== "object" || Array.isArray(current)) {
+        current = undefined;
+        break;
+      }
+      current = current[part];
+    }
+    if (typeof current === "boolean") {
+      return current;
+    }
+  }
+  return false;
+}
+
+function applyInlineStyle(text, style) {
+  if (!text) {
+    return "";
+  }
+  const bold = readBooleanDeep(style, ["bold"]);
+  const italic = readBooleanDeep(style, ["italic"]);
+  const inlineCode = readBooleanDeep(style, ["inline_code"]);
+  const strikethrough = readBooleanDeep(style, ["strikethrough"]);
+  const underline = readBooleanDeep(style, ["underline"]);
+  let output = text;
+  if (inlineCode) {
+    output = `\`${output.replace(/`/gu, "\\`")}\``;
+  }
+  if (bold) {
+    output = `**${output}**`;
+  }
+  if (italic) {
+    output = `*${output}*`;
+  }
+  if (strikethrough) {
+    output = `~~${output}~~`;
+  }
+  if (underline) {
+    output = `<u>${output}</u>`;
+  }
+  return output;
+}
+
+function renderListItem(prefix, text, childLines) {
+  const line = text ? `${prefix} ${text}` : prefix;
+  return childLines.length === 0 ? [line] : [line, ...indentLines(childLines, "  ")];
+}
+
+function indentLines(lines, indent) {
+  return lines.map((line) => line.length > 0 ? `${indent}${line}` : line);
+}
+
+function prefixLines(firstLine, childLines, prefix) {
+  return childLines.length === 0
+    ? [firstLine]
+    : [firstLine, ...childLines.map((line) => line.length > 0 ? `${prefix}${line}` : prefix.trimEnd())];
+}
+
+function escapeHtmlAttribute(value) {
+  return value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}
+
+function resolvePreferredFileName(material, responseFileName, contentType) {
+  const stableName = buildStableReferenceMaterialName(material, responseFileName, contentType);
+  if (stableName) {
+    return stableName;
+  }
+  const candidates = [responseFileName, material.title, material.token ? `${material.type}-${material.token}` : undefined];
+  for (const candidate of candidates) {
+    const normalized = sanitizeFileName(candidate);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return `${material.type}${extensionFromMimeType(contentType) || extensionFromMimeType(material.mimeType) || ""}`;
+}
+
+function buildStableReferenceMaterialName(material, sourceFileName, contentType) {
+  if (material.type !== "image") {
+    return undefined;
+  }
+  const extension = extensionFromFileName(sourceFileName) || extensionFromMimeType(contentType) || extensionFromMimeType(material.mimeType) || ".png";
+  const identity = sanitizeFileName(material.assetId) || (Number.isFinite(material.order) ? String(material.order).padStart(3, "0") : undefined) || sanitizeFileName(material.token);
+  return identity ? `image-${identity}${extension}` : `image${extension}`;
+}
+
+function extensionFromFileName(fileName) {
+  const extension = extname(fileName?.trim() || "").toLowerCase();
+  return [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".html", ".md", ".json", ".txt"].includes(extension) ? extension : undefined;
+}
+
+function ensureExtension(fileName, material, contentType) {
+  if (extname(fileName)) {
+    return fileName;
+  }
+  const extension = extensionFromMimeType(contentType) || extensionFromMimeType(material.mimeType) || (material.type === "image" ? ".png" : undefined);
+  return extension ? `${fileName}${extension}` : fileName;
+}
+
+function extensionFromMimeType(mimeType) {
+  const normalized = mimeType?.trim().toLowerCase();
+  switch (normalized) {
+    case "image/png": return ".png";
+    case "image/jpeg": return ".jpeg";
+    case "image/webp": return ".webp";
+    case "image/gif": return ".gif";
+    case "image/svg+xml": return ".svg";
+    case "text/html": return ".html";
+    case "text/markdown": return ".md";
+    case "application/json": return ".json";
+    case "text/plain": return ".txt";
+    default: return undefined;
+  }
+}
+
+function sanitizeFileName(value) {
+  const normalized = value?.trim().replace(/[\\/:*?"<>|]+/gu, "-").replace(/\s+/gu, " ");
+  return normalized ? basename(normalized) : undefined;
+}
+
+function readFileNameFromHeaders(headers) {
+  const contentDisposition = headers.get("content-disposition")?.trim();
+  if (!contentDisposition) {
+    return undefined;
+  }
+  const utf8Match = contentDisposition.match(/filename\*\s*=\s*UTF-8''([^;]+)/iu);
+  if (utf8Match?.[1]) {
+    try {
+      return decodeURIComponent(utf8Match[1]).trim();
+    } catch {
+      return utf8Match[1].trim();
+    }
+  }
+  const quotedMatch = contentDisposition.match(/filename\s*=\s*"([^"]+)"/iu);
+  if (quotedMatch?.[1]) {
+    return quotedMatch[1].trim();
+  }
+  const plainMatch = contentDisposition.match(/filename\s*=\s*([^;]+)/iu);
+  return plainMatch?.[1]?.trim();
+}
+
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/u, "");
+}
+
+function decodeCredential(encoded) {
+  const source = Buffer.from(encoded, "hex");
+  const key = Buffer.from(CREDENTIAL_XOR_KEY, "utf8");
+  const output = Buffer.alloc(source.length);
+  for (let index = 0; index < source.length; index += 1) {
+    output[index] = source[index] ^ key[index % key.length];
+  }
+  return output.toString("utf8");
+}
+
+if (import.meta.url === new URL(`file://${process.argv[1]}`).toString()) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}