magic-builder 0.1.0

package/src/commands/feedback.js

@@ -0,0 +1,320 @@
+'use strict';
+
+const { existsSync, readFileSync } = require('fs');
+const { resolve } = require('path');
+const { success, fail } = require('../lib/output');
+
+const DEFAULT_TARGET_URL = 'https://bytedance.larkoffice.com/wiki/Ia5xwTdUmiQu8skc3C3cSQgEnmb?table=tblyfZ7z5J0Ujqs4&view=vewql5Ifjo';
+const DEFAULT_HOST = 'https://open.feishu.cn';
+const ALLOWED_OPENAPI_HOSTS = new Set(['open.feishu.cn', 'open.larksuite.com']);
+
+let cachedToken = '';
+let cachedTokenExpiresAt = 0;
+let authConfig = {
+  openapiHost: DEFAULT_HOST,
+  appId: '',
+  appSecret: '',
+};
+
+async function run(args, opts) {
+  const sub = args[0];
+  if (sub !== 'create') fail('Usage: magic-builder feedback create --feedback <text>', 'E_INVALID_ARGS');
+
+  const fileConfig = loadEnvJson();
+  configureAuth(opts, fileConfig);
+  const stdin = readStdin();
+  const feedback = firstNonEmpty(
+    opts.feedback,
+    opts.feedbackFile ? readFileSync(resolve(opts.feedbackFile), 'utf8') : '',
+    stdin,
+  );
+  if (!feedback) fail('Missing feedback text. Use --feedback, --feedback-file, or stdin.', 'E_INVALID_ARGS');
+
+  const title = firstNonEmpty(opts.title, inferTitle(feedback));
+  const summary = firstNonEmpty(opts.summary, feedback);
+  const category = firstNonEmpty(opts.category, inferCategory(`${title}\n${summary}\n${feedback}`));
+  const priority = firstNonEmpty(opts.priority, inferPriority(`${title}\n${summary}\n${feedback}`, category));
+
+  const parsedTarget = parseTargetUrl(opts.targetUrl);
+  const tableId = firstNonEmpty(opts.tableId, parsedTarget.tableId);
+  const viewId = firstNonEmpty(opts.viewId, parsedTarget.viewId);
+  const appToken = firstNonEmpty(opts.appToken, parsedTarget.appToken) || await resolveWikiToken(parsedTarget.wikiToken);
+  if (!appToken) fail('Unable to resolve bitable app token from target URL. Pass --app-token explicitly.', 'E_INVALID_ARGS');
+  if (!tableId) fail('Missing table id. Pass --table-id explicitly.', 'E_INVALID_ARGS');
+
+  const data = {
+    title,
+    summary,
+    feedback,
+    category,
+    priority,
+    status: opts.status || '待处理',
+    source: opts.source || '飞书用户反馈',
+    product: opts.product || '妙笔',
+    reporterName: opts.reporterName,
+    reporterOpenId: opts.reporterOpenId,
+    sessionId: opts.sessionId,
+    sourceUrl: opts.sourceUrl,
+    createdAt: new Date().toISOString(),
+  };
+
+  const fieldDefs = await listFields(appToken, tableId);
+  const fields = buildFieldPayload(fieldDefs, data);
+  if (!Object.keys(fields).length) {
+    fail(`No matching writable fields found. Available fields: ${fieldDefs.map((x) => x.field_name || x.name).join(', ')}`, 'E_FEEDBACK_FAILED');
+  }
+
+  const result = { targetUrl: parsedTarget.raw, appToken, tableId, viewId, fields };
+  if (opts.dryRun) {
+    success({ dryRun: true, ...result }, opts);
+    return;
+  }
+
+  const created = await createRecord(appToken, tableId, fields);
+  success({
+    ...result,
+    recordId: created?.data?.record?.record_id || created?.data?.record_id || '',
+    response: created,
+  }, opts);
+}
+
+function loadEnvJson() {
+  const config = {};
+  for (const p of [resolve(process.cwd(), 'env.json'), resolve(process.cwd(), '.env.json')]) {
+    if (!existsSync(p)) continue;
+    const json = JSON.parse(readFileSync(p, 'utf8'));
+    for (const [key, value] of Object.entries(json)) {
+      if (config[key] === undefined && value !== undefined && value !== null) {
+        config[key] = typeof value === 'string' ? value : JSON.stringify(value);
+      }
+    }
+  }
+  return config;
+}
+
+function readStdin() {
+  if (process.stdin.isTTY) return '';
+  return readFileSync(0, 'utf8');
+}
+
+function getText(value) {
+  return String(value || '').trim();
+}
+
+function firstNonEmpty(...values) {
+  return values.map(getText).find(Boolean) || '';
+}
+
+function compactText(value) {
+  return getText(value)
+    .replace(/<at\b[^>]*>.*?<\/at>/g, '')
+    .replace(/@\S+/g, '')
+    .replace(/https?:\/\/\S+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function clip(value, max) {
+  const text = getText(value);
+  return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+
+function inferTitle(feedback) {
+  const lines = getText(feedback).split(/\r?\n/).map(compactText).filter(Boolean);
+  return clip(lines[0] || '妙笔用户反馈', 40);
+}
+
+function inferCategory(text) {
+  const s = getText(text);
+  if (/权限|登录|登陆|授权|token|Token|401|403/.test(s)) return '权限/登录';
+  if (/慢|卡|超时|timeout|Timeout|延迟|性能/.test(s)) return '性能/稳定性';
+  if (/报错|错误|失败|打不开|无法|不能|崩溃|异常|error|Error|failed|Failed/.test(s)) return 'Bug/报错';
+  if (/希望|建议|能否|能不能|支持|新增|优化/.test(s)) return '功能建议';
+  if (/怎么|如何|为什么|是否|能不能用/.test(s)) return '使用咨询';
+  return '体验问题';
+}
+
+function inferPriority(text, category) {
+  const s = getText(text);
+  if (/数据丢失|无法发布|发布失败|全部|所有人|不可用|崩溃|打不开|P0|紧急|严重/.test(s)) return 'P1';
+  if (category === '使用咨询' || /轻微|建议|优化|体验/.test(s)) return 'P3';
+  return 'P2';
+}
+
+function parseTargetUrl(rawUrl) {
+  const raw = getText(rawUrl || DEFAULT_TARGET_URL);
+  const url = new URL(raw);
+  const tableId = url.searchParams.get('table') || '';
+  const viewId = url.searchParams.get('view') || '';
+  const wikiMatch = url.pathname.match(/\/wiki\/([^/?#]+)/);
+  const baseMatch = url.pathname.match(/\/base\/([^/?#]+)/);
+  return { raw, wikiToken: wikiMatch?.[1] || '', appToken: baseMatch?.[1] || '', tableId, viewId };
+}
+
+function normalizeOpenapiHost(rawHost) {
+  const raw = getText(rawHost || DEFAULT_HOST).replace(/\/+$/, '');
+  const withProtocol = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  const url = new URL(withProtocol);
+  if (url.protocol !== 'https:') fail('OpenAPI host must use https', 'E_INVALID_ARGS');
+  if (!ALLOWED_OPENAPI_HOSTS.has(url.hostname)) fail(`Unsupported OpenAPI host: ${url.hostname}`, 'E_INVALID_ARGS');
+  return url.origin;
+}
+
+function configureAuth(opts, fileConfig) {
+  authConfig = {
+    openapiHost: normalizeOpenapiHost(firstNonEmpty(opts.openapiHost, fileConfig.LARK_OPENAPI_HOST, fileConfig.FEISHU_OPENAPI_HOST, DEFAULT_HOST)),
+    appId: firstNonEmpty(opts.appId, fileConfig.LARK_APP_ID, fileConfig.FEISHU_APP_ID),
+    appSecret: firstNonEmpty(opts.appSecret, fileConfig.LARK_APP_SECRET, fileConfig.FEISHU_APP_SECRET),
+  };
+}
+
+function host() {
+  return authConfig.openapiHost;
+}
+
+async function larkFetch(method, apiPath, body, query) {
+  const token = await getTenantToken();
+  const url = new URL(`${host()}${apiPath}`);
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value));
+  }
+  const resp = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    cache: 'no-store',
+  });
+  const text = await resp.text();
+  let data;
+  try { data = text ? JSON.parse(text) : {}; } catch { throw new Error(`Invalid JSON from ${method} ${url.pathname}: ${text}`); }
+  if (!resp.ok || data?.code !== 0) throw new Error(`${method} ${url.pathname} failed: ${JSON.stringify(data)}`);
+  return data;
+}
+
+async function getTenantToken() {
+  if (cachedToken && Date.now() < cachedTokenExpiresAt) return cachedToken;
+  const id = authConfig.appId;
+  const secret = authConfig.appSecret;
+  if (!id || !secret) {
+    fail('Missing app credentials. Pass --app-id/--app-secret or configure LARK_APP_ID/LARK_APP_SECRET in env.json.', 'E_AUTH_FAILED', 2);
+  }
+  const resp = await fetch(`${host()}/open-apis/auth/v3/tenant_access_token/internal`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app_id: id, app_secret: secret }),
+    cache: 'no-store',
+  });
+  const data = await resp.json();
+  if (!resp.ok || data?.code !== 0 || !data?.tenant_access_token) {
+    throw new Error(`tenant token failed: ${JSON.stringify(data)}`);
+  }
+  cachedToken = data.tenant_access_token;
+  cachedTokenExpiresAt = Date.now() + Math.max(Number(data.expire || 7200) - 60, 60) * 1000;
+  return cachedToken;
+}
+
+async function resolveWikiToken(wikiToken) {
+  if (!wikiToken) return '';
+  const data = await larkFetch('GET', '/open-apis/wiki/v2/spaces/get_node', undefined, { token: wikiToken });
+  const node = data?.data?.node || {};
+  if (node.obj_type && node.obj_type !== 'bitable') throw new Error(`wiki node is ${node.obj_type}, not bitable`);
+  return getText(node.obj_token);
+}
+
+async function listFields(appToken, tableId) {
+  const data = await larkFetch('GET', `/open-apis/bitable/v1/apps/${encodeURIComponent(appToken)}/tables/${encodeURIComponent(tableId)}/fields`);
+  return data?.data?.items || [];
+}
+
+async function createRecord(appToken, tableId, fields) {
+  return larkFetch('POST', `/open-apis/bitable/v1/apps/${encodeURIComponent(appToken)}/tables/${encodeURIComponent(tableId)}/records`, { fields });
+}
+
+function normalizeFieldType(field) {
+  return Number(field?.type || field?.ui_type || 0);
+}
+
+function asDateValue(value) {
+  const text = getText(value);
+  if (!text) return Date.now();
+  const ms = Date.parse(text);
+  return Number.isFinite(ms) ? ms : Date.now();
+}
+
+function asPersonValue(openId) {
+  const id = getText(openId);
+  return id ? [{ id }] : undefined;
+}
+
+function asUrlValue(url, title) {
+  const link = getText(url);
+  if (!link) return undefined;
+  return { text: getText(title) || link, link };
+}
+
+function convertValue(field, value, allData) {
+  const raw = value;
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const type = normalizeFieldType(field);
+  if (type === 5) return asDateValue(raw);
+  if (type === 11 || type === 23) return asPersonValue(raw);
+  if (type === 15) return asUrlValue(raw, allData.title);
+  if (type === 7) return Boolean(raw);
+  if (type === 2) {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : undefined;
+  }
+  return String(raw);
+}
+
+function findField(fields, candidates) {
+  const normalized = new Map(fields.map((field) => [getText(field.field_name || field.name).toLowerCase(), field]));
+  for (const candidate of candidates) {
+    const found = normalized.get(candidate.toLowerCase());
+    if (found) return found;
+  }
+  for (const field of fields) {
+    const name = getText(field.field_name || field.name);
+    if (candidates.some((candidate) => name.includes(candidate))) return field;
+  }
+  return null;
+}
+
+function buildFieldPayload(fieldDefs, data) {
+  const mapping = [
+    { key: 'title', candidates: ['标题', '反馈标题', '问题标题', '需求标题', '名称', '反馈摘要', '摘要', '问题'] },
+    { key: 'summary', candidates: ['整理后问题', '问题整理', '反馈整理', '问题摘要', '整理摘要', '需求描述', '用户反馈', '描述'] },
+    { key: 'feedback', candidates: ['原始反馈', '用户原话', '原始问题', '反馈内容', '内容', '详细描述', '问题描述', '详情'] },
+    { key: 'category', candidates: ['分类', '问题分类', '反馈分类', '类型', '反馈类型', '问题类型'] },
+    { key: 'priority', candidates: ['优先级', '严重程度', '影响程度', 'P级', '级别', 'Priority'] },
+    { key: 'status', candidates: ['状态', '处理状态', '跟进状态'] },
+    { key: 'reporterName', candidates: ['反馈人', '用户', '提交人', '上报人', '提出人', '用户名称', '姓名'] },
+    { key: 'reporterOpenId', candidates: ['反馈人 open_id', '用户 open_id', 'open_id', 'Open ID', '用户ID', '用户标识'] },
+    { key: 'sessionId', candidates: ['session_id', 'Session ID', '会话ID', '会话 id', '会话'] },
+    { key: 'source', candidates: ['来源', '反馈来源', '渠道', 'Source'] },
+    { key: 'sourceUrl', candidates: ['来源链接', '会话链接', '相关链接', '链接', 'URL', 'url'] },
+    { key: 'product', candidates: ['产品', '模块', '应用', '系统'] },
+    { key: 'createdAt', candidates: ['反馈时间', '提交时间', '创建时间', '时间', '日期'] },
+  ];
+  const payload = {};
+  const usedFieldIds = new Set();
+  for (const item of mapping) {
+    const field = findField(fieldDefs.filter((x) => !usedFieldIds.has(x.field_id)), item.candidates);
+    if (!field) continue;
+    const fieldName = getText(field.field_name || field.name);
+    let rawValue = data[item.key];
+    if ((item.key === 'reporterName' || item.key === 'reporterOpenId') && [11, 23].includes(normalizeFieldType(field))) {
+      rawValue = data.reporterOpenId;
+    }
+    const converted = convertValue(field, rawValue, data);
+    if (converted === undefined) continue;
+    payload[fieldName] = converted;
+    if (field.field_id) usedFieldIds.add(field.field_id);
+  }
+  return payload;
+}
+
+module.exports = { run };

package/src/commands/link.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { getBaseUrl } = require('../lib/config');
+const { success, fail } = require('../lib/output');
+
+async function run(args, opts) {
+  const sub = args[0];
+  if (sub !== 'create') fail('Usage: magic-builder link create --title <text> or --fid <id>', 'E_INVALID_ARGS');
+  const baseUrl = getBaseUrl(opts);
+
+  if (opts.fid) {
+    success({ url: `${baseUrl}/r?fid=${opts.fid}` }, opts);
+    return;
+  }
+
+  if (opts.title) {
+    const encoded = encodeURIComponent(opts.title);
+    success({ url: `${baseUrl}/r?title=${encoded}` }, opts);
+    return;
+  }
+
+  fail('Provide --title or --fid. Usage: magic-builder link create --title <text>', 'E_INVALID_ARGS');
+}
+
+module.exports = { run };

package/src/commands/page.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getToken } = require('../lib/auth');
+const { getBaseUrl, loadAppsConfig, saveAppsConfig } = require('../lib/config');
+const { request } = require('../lib/http');
+const { success, fail, failFromHttpError } = require('../lib/output');
+
+const HTML_CODE_FIELD_COUNT = 10;
+const HTML_CODE_FIELD_LIMIT = 90000;
+const HTML_LIMIT = HTML_CODE_FIELD_COUNT * HTML_CODE_FIELD_LIMIT;
+
+async function run(args, opts) {
+  const sub = args[0];
+  if (sub === 'publish') return publish(args.slice(1), opts);
+  if (sub === 'list') return list(opts);
+  if (sub === 'export') return exportApps(opts);
+  fail('Usage: magic-builder page <publish|list|export>', 'E_INVALID_ARGS');
+}
+
+async function publish(args, opts) {
+  const file = args[0];
+  if (!file) fail('Missing file argument. Usage: magic-builder page publish <file.html>', 'E_INVALID_ARGS');
+  if (!fs.existsSync(file)) fail(`File not found: ${file}`, 'E_NOT_FOUND');
+
+  const html = fs.readFileSync(file, 'utf8');
+  if (!html.trim()) fail('HTML file is empty', 'E_EMPTY_FILE');
+  if (html.length > HTML_LIMIT) fail(formatHtmlLimitMessage(html), 'E_PAYLOAD_TOO_LARGE');
+
+  let token;
+  try { token = await getToken(opts); } catch (e) { fail(e.message, 'E_NO_TOKEN', 2); }
+
+  const baseUrl = getBaseUrl(opts);
+  const title = opts.title || path.basename(file, path.extname(file));
+  const config = loadAppsConfig();
+  const relPath = path.relative(process.cwd(), path.resolve(file));
+  const existingId = opts.id || config[relPath]?.id || config[relPath]?.remoteId;
+
+  const body = { html, title };
+  if (opts.openSource) body.is_open_source = true;
+
+  if (!opts.quiet) process.stderr.write(`${existingId ? 'Updating' : 'Publishing'} ${relPath}... `);
+
+  let res;
+  try {
+    const endpoint = existingId
+      ? `${baseUrl}/api/html-box/${encodeURIComponent(existingId)}`
+      : `${baseUrl}/api/html-box`;
+    res = await request(endpoint, { method: 'POST', token, body });
+  } catch (e) { failFromHttpError(e); }
+
+  if (res.code !== 0) fail(res.msg || 'Publish failed', 'E_PUBLISH_FAILED');
+
+  const data = res.data || res;
+  const id = normalizeId(data.id || data.record_id || existingId);
+  const htmlBoxUrl = data.html_box_url || `${baseUrl}/html-box/${id}`;
+  const dashboardUrl = data.dashboard_url || `${baseUrl}/dashboard/${id}`;
+
+  config[relPath] = {
+    id,
+    remoteId: id,
+    title,
+    urls: {
+      html_box: htmlBoxUrl,
+      dashboard: dashboardUrl,
+      panel: data.panel_url || '',
+      tab: data.tab_url || '',
+    },
+    updatedAt: new Date().toISOString(),
+  };
+  saveAppsConfig(config);
+
+  if (!opts.quiet) process.stderr.write('done\n');
+  success({
+    id,
+    title,
+    html_box_url: htmlBoxUrl,
+    dashboard_url: dashboardUrl,
+    panel_url: data.panel_url || '',
+    tab_url: data.tab_url || '',
+  }, opts);
+}
+
+async function list(opts) {
+  const result = await searchApps(opts);
+  if (opts.format === 'json') {
+    success(result.raw, opts);
+    return;
+  }
+  if (opts.format === 'plain') {
+    success(result.records.map((record) => summarizeRecord(result.baseUrl, record)).join('\n'), opts);
+    return;
+  }
+  success({
+    count: result.count,
+    scope: result.scope,
+    title: result.title,
+    records: result.records.map((record) => normalizeRecord(result.baseUrl, record)),
+  }, opts);
+}
+
+async function exportApps(opts) {
+  if (!opts.out) fail('Missing --out', 'E_INVALID_ARGS');
+  if (!opts.id && !opts.title) fail('Missing --id or --title', 'E_INVALID_ARGS');
+
+  const searchOpts = { ...opts };
+  if (opts.id && !opts.title) delete searchOpts.title;
+  const result = await searchApps(searchOpts);
+  const targetId = normalizeId(opts.id);
+  let matches = result.records.filter((record) => {
+    if (targetId) return shortIdFromRecord(record) === targetId;
+    return titleMatches(record, opts.title);
+  });
+
+  if (!matches.length && opts.id && normalizeScope(opts.scope) === 'public') {
+    const html = await fetchOpenSourceHtml(opts, opts.id);
+    matches = [{ id: targetId, title: targetId, isOpenSource: true, html_preview: html }];
+  }
+
+  if (!matches.length) fail('No matching app found', 'E_NOT_FOUND');
+  if (!opts.all) matches = matches.slice(0, 1);
+
+  const exports = [];
+  for (const record of matches) {
+    let html = String(record?.html_preview || '');
+    if (!html && record?.isOpenSource) html = await fetchOpenSourceHtml(opts, shortIdFromRecord(record));
+    if (!html) {
+      fail(`App ${shortIdFromRecord(record)} did not include exportable HTML. Use scope=mine with a valid token for private apps, or export an open-source app.`, 'E_EXPORT_FAILED');
+    }
+    exports.push({ record, html });
+  }
+
+  success({ written: writeExport(opts.out, exports) }, opts);
+}
+
+async function searchApps(opts) {
+  const baseUrl = getBaseUrl(opts);
+  const scope = normalizeScope(opts.scope);
+  let token = '';
+  if (scope === 'mine') {
+    try { token = await getToken(opts); } catch (e) { fail(e.message, 'E_NO_TOKEN', 2); }
+  }
+  const url = new URL('/api/html-box/apps', baseUrl);
+  url.searchParams.set('scope', scope);
+  if (opts.title) url.searchParams.set('title', opts.title);
+  const json = await request(String(url), { token });
+  const records = Array.isArray(json?.data?.records) ? json.data.records : [];
+  return { baseUrl, scope, title: opts.title || '', count: records.length, records, raw: json };
+}
+
+async function fetchOpenSourceHtml(opts, id) {
+  const baseUrl = getBaseUrl(opts);
+  const json = await request(`${baseUrl}/api/html-box/${encodeURIComponent(normalizeId(id))}`);
+  return String(json?.data?.html || '');
+}
+
+function normalizeScope(scope) {
+  const value = String(scope || 'mine').trim().toLowerCase();
+  if (value === 'my' || value === 'private' || value === 'current_user') return 'mine';
+  if (value === 'open' || value === 'opensourced') return 'public';
+  if (value === 'mine' || value === 'public') return value;
+  fail(`Unsupported scope: ${scope}`, 'E_INVALID_ARGS');
+}
+
+function normalizeId(id) {
+  const value = String(id || '').trim();
+  return value.startsWith('rec') ? value.slice(3) : value;
+}
+
+function shortIdFromRecord(record) {
+  return normalizeId(record?.id || record?.record_id || record?.recordId || '');
+}
+
+function appUrl(baseUrl, id) {
+  return `${baseUrl}/html-box/${encodeURIComponent(normalizeId(id))}`;
+}
+
+function normalizeRecord(baseUrl, record) {
+  const id = shortIdFromRecord(record);
+  return {
+    id,
+    title: String(record?.title || '').trim() || '(untitled)',
+    open_source: !!record?.isOpenSource,
+    modified: record?.modify_time || '',
+    url: appUrl(baseUrl, id),
+  };
+}
+
+function summarizeRecord(baseUrl, record) {
+  const item = normalizeRecord(baseUrl, record);
+  return `${item.id}  ${item.title}  ${item.open_source ? 'open-source' : 'private'}${item.modified ? `  modified=${item.modified}` : ''}  ${item.url}`;
+}
+
+function titleMatches(record, keyword) {
+  if (!keyword) return true;
+  return String(record?.title || '').toLowerCase().includes(String(keyword).toLowerCase());
+}
+
+function safeFileName(record) {
+  const id = shortIdFromRecord(record) || 'unknown';
+  const title = String(record?.title || 'magic-app')
+    .trim()
+    .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+    .replace(/\s+/g, '_')
+    .slice(0, 80) || 'magic-app';
+  return `${title}-${id}.html`;
+}
+
+function isDirectoryDestination(out, multiple) {
+  if (multiple) return true;
+  if (fs.existsSync(out) && fs.statSync(out).isDirectory()) return true;
+  return !path.extname(out);
+}
+
+function writeExport(out, exports) {
+  const multiple = exports.length > 1;
+  const dest = path.resolve(out);
+  const directoryDest = isDirectoryDestination(dest, multiple);
+  if (directoryDest) fs.mkdirSync(dest, { recursive: true });
+  if (!directoryDest && multiple) fail('--out must be a directory when exporting multiple apps', 'E_INVALID_ARGS');
+
+  return exports.map((item) => {
+    const filePath = directoryDest ? path.join(dest, safeFileName(item.record)) : dest;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, item.html, 'utf8');
+    return { id: shortIdFromRecord(item.record), title: item.record?.title || '', file: filePath };
+  });
+}
+
+function hasLikelyInlineLargeResource(html) {
+  return /data:[^"'()\s>]+;base64,/i.test(html) || /base64,[A-Za-z0-9+/=]{1024,}/.test(html);
+}
+
+function formatHtmlLimitMessage(html) {
+  const overflow = Math.max(0, html.length - HTML_LIMIT);
+  const hint = hasLikelyInlineLargeResource(html)
+    ? 'Detected likely data:/Base64 inline resources. Upload those resources first, then reference their URLs in HTML.'
+    : 'If the HTML contains images, Base64, large JSON/CSV, or other large resources, upload them first, then reference their URLs in HTML.';
+  return `HTML exceeds publish limit (${HTML_LIMIT} characters; ${HTML_CODE_FIELD_COUNT} HTML code fields x ${HTML_CODE_FIELD_LIMIT} characters). Current: ${html.length}; over by: ${overflow}. ${hint}`;
+}
+
+module.exports = { run };