magic-builder 1.2.0 → 1.3.1

package/README.md

@@ -72,6 +72,7 @@ This includes:
 ```text
 magic-token
 magic-apps.json
+widget-publish.json
 ```
 
 ## Common Commands
@@ -119,6 +120,8 @@ magic-builder file list --title logo
 magic-builder file delete --id <id>
 ```
 
+文件上传采用 `sign -> PUT -> audit confirm` 流程。预签名成功后会返回 `audit_id`，CLI 在对象上传完成后自动确认审计；确认失败时命令返回失败，重复执行确认不会新增审计记录。
+
 Generate a Magic link:
 
 ```bash
@@ -145,6 +148,27 @@ magic-builder performance --review-url <people-review-url> --markdown ./performa
 
 With `--review-url`, the CLI loads the operator and tenant from `/perf/api/user/settings`, then reuses the current draft version, template, units, fields, source ids, and root review id from `/perf/api/foundation/draft`. Business ids are not hard-coded into the generated request.
 
+Update the text fields in the self-review draft while preserving both rating fields and any omitted text:
+
+```bash
+magic-builder perf self-review --review-url <people-review-url> \
+  --good "What went well" \
+  --improve-file ./improvements.md \
+  --values-comment-file ./values-comment.md
+magic-builder perf self-review --review-url <people-review-url> --good-file ./good.md --dry-run
+```
+
+Each field can be provided as literal text or through its matching `--*-file` option. At least one field is required. The command reloads the latest `self_review` draft before every run and writes by default; `--dry-run` prints the payload without saving it.
+
+Formally submit the latest draft to the current review stage:
+
+```bash
+magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --dry-run
+magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --yes
+```
+
+The command posts to `/perf/api/review/v2/stage`. It always reloads the latest draft, derives the root review, template, stage, and work units from it, and serializes rich-text values into the stage payload. `--template-group-id` is optional when the draft already contains it. A real submission requires `--yes`; use `--dry-run` to inspect the payload first.
+
 Extract Cookie from a copied curl command. This is a top-level general-purpose command. The default output is `./cookie.txt`; the file is created with mode `0600`:
 
 ```bash
@@ -156,10 +180,48 @@ cat ./request.curl | magic-builder extract-cookie --out-dir ./secrets
 Create or append a Feishu document HTML Box:
 
 ```bash
-magic-builder doc create --html app.html --title "Demo"
+magic-builder doc create --html app.html --title "Demo" # defaults to --edition external
 magic-builder doc append --html app.html --doc-token <docx-token>
+magic-builder doc create --html app.html --title "ByteDance Demo" --edition bytedance
 ```
 
+Publish a document widget draft as a new app version:
+
+```bash
+magic-builder widget-publish \
+  --app-id cli_a98afe875979500d \
+  --block-type-id blk_6900429af84180025ce76527 \
+  --change-log "修复 HTML Box 高度反馈循环"
+```
+
+The command reads Open Platform browser authentication from
+`~/.magic-builder/widget-publish.json` by default:
+
+```json
+{
+  "cookie": "open_locale=zh-CN; session=...",
+  "csrfToken": "...",
+  "timezoneOffset": -480
+}
+```
+
+Keep this file local and set its mode to `0600`. Use `--config <file>` to select
+another file. The command fetches the widget detail, selects the latest uploaded
+test package before the existing draft/current package, updates the widget pkgId,
+increments the latest patch version, creates the app
+version with the application's actual default abilities and audit settings, and
+submits it for publishing. Use `--version` to override the generated
+version or `--dry-run` to inspect the payload without updating or publishing.
+
+You can generate the local config directly from a browser-copied curl command:
+
+```bash
+magic-builder extract-cookie --curl-file ./widget-request.curl --widget-publish
+```
+
+This extracts only the Cookie and `x-csrf-token`, writes them to the default
+widget publish config with mode `0600`, and does not print either secret.
+
 Install or update the Magic Builder Codex skill:
 
 ```bash
@@ -168,6 +230,10 @@ magic-builder skill check-update
 magic-builder skill update
 ```
 
+Skills are installed to `~/.agents/skills` by default so Codex, Trae, Doubao,
+and other compatible agents can share them. Use `--skills-root <dir>` to
+override the destination.
+
 Check local environment:
 
 ```bash

package/bin/magic-builder.js

@@ -14,6 +14,7 @@ const COMMANDS = {
   feedback: require('../src/commands/feedback'),
   performance: require('../src/commands/performance'),
   perf: require('../src/commands/performance'),
+  'widget-publish': require('../src/commands/widget-publish'),
   'extract-cookie': require('../src/commands/extract-cookie'),
   skill: require('../src/commands/skill'),
   version: require('../src/commands/version'),

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "magic-builder",
-  "version": "1.2.0",
-  "description": "CLI for Magic Builder — publish pages, functions, files, and performance drafts",
+  "version": "1.3.1",
+  "description": "CLI for Magic Builder — publish pages, functions, files, and performance reviews",
   "bin": {
     "magic-builder": "bin/magic-builder.js",
     "magic-cli": "bin/magic-builder.js",
     "miaobi": "bin/magic-builder.js"
   },
   "main": "./src/index.js",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
   "engines": {
     "node": ">=18.0.0"
   },

package/src/commands/config.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { CONFIG_DIR, getAppsConfigPath, getBaseUrl } = require('../lib/config');
+const { CONFIG_DIR, getAppsConfigPath, getBaseUrl, getWidgetPublishConfigPath, getPerformanceConfigPath } = require('../lib/config');
 const { TOKEN_FILE, showToken } = require('../lib/auth');
 const { success, fail } = require('../lib/output');
 
@@ -10,6 +10,8 @@ async function run(args, opts) {
   success({
     base_url: getBaseUrl(opts),
     config_dir: CONFIG_DIR,
+    widget_publish_config_file: getWidgetPublishConfigPath(),
+    performance_config_file: getPerformanceConfigPath(),
     token_file: TOKEN_FILE,
     apps_config_file: getAppsConfigPath(),
     token: showToken() || '',

package/src/commands/doc.js

@@ -4,7 +4,10 @@ const { readFileSync } = require('fs');
 const { execFileSync } = require('child_process');
 const { success, fail } = require('../lib/output');
 
-const HTML_BOX_COMPONENT_TYPE_ID = 'blk_6900429af84180025ce76527';
+const HTML_BOX_COMPONENT_TYPE_IDS = {
+  external: 'blk_6358a421bca0001c190a9805',
+  bytedance: 'blk_6900429af84180025ce76527',
+};
 
 async function run(args, opts) {
   const sub = args[0];
@@ -16,14 +19,17 @@ async function run(args, opts) {
   const html = readFileSync(opts.html, 'utf8');
   const record = buildRecord(opts, html);
   const identity = resolveIdentity(opts.as);
+  const { edition, componentTypeId } = resolveEdition(opts.edition);
   const created = sub === 'append'
     ? { docToken: opts.docToken, url: `https://bytedance.larkoffice.com/docx/${opts.docToken}` }
     : createDocument(opts.title, opts.summary, identity);
-  const htmlBoxBlockId = insertHtmlBox(created.docToken, record, identity);
+  const htmlBoxBlockId = insertHtmlBox(created.docToken, record, identity, componentTypeId);
 
   success({
     ok: true,
     identity,
+    edition,
+    component_type_id: componentTypeId,
     doc_token: created.docToken,
     doc_url: created.url,
     html_box_block_id: htmlBoxBlockId,
@@ -51,6 +57,16 @@ function resolveIdentity(requestedIdentity) {
   return 'bot';
 }
 
+function resolveEdition(requestedEdition) {
+  const edition = requestedEdition || 'external';
+  if (!Object.prototype.hasOwnProperty.call(HTML_BOX_COMPONENT_TYPE_IDS, edition)) {
+    const error = new Error('--edition must be external or bytedance');
+    error.code = 'E_INVALID_ARGS';
+    throw error;
+  }
+  return { edition, componentTypeId: HTML_BOX_COMPONENT_TYPE_IDS[edition] };
+}
+
 function createDocument(title, summary, identity) {
   const intro = summary || `这个妙笔应用以交互式网页的形式展示「${title}」，可直接在文档中查看和体验。`;
   const content = `<title>${escapeXml(title)}</title><p>${escapeXml(intro)}</p>`;
@@ -73,7 +89,7 @@ function createDocument(title, summary, identity) {
   };
 }
 
-function insertHtmlBox(docToken, recordObject, identity) {
+function insertHtmlBox(docToken, recordObject, identity, componentTypeId) {
   const record = JSON.stringify(recordObject);
   const resp = runJson([
     'api',
@@ -87,15 +103,18 @@ function insertHtmlBox(docToken, recordObject, identity) {
         block_type: 40,
         add_ons: {
           component_id: '',
-          component_type_id: HTML_BOX_COMPONENT_TYPE_ID,
+          component_type_id: componentTypeId,
           record,
         },
       }],
       index: -1,
     }),
   ]);
-  if (resp?.code !== 0) throw new Error(`failed to insert HTML Box: ${JSON.stringify(resp)}`);
+  if (!isSuccessfulLarkResponse(resp)) throw new Error(`failed to insert HTML Box: ${JSON.stringify(resp)}`);
   const block = resp?.data?.children?.[0];
+  if (block?.add_ons?.component_type_id && block.add_ons.component_type_id !== componentTypeId) {
+    throw new Error(`inserted HTML Box component type mismatch: ${JSON.stringify(block?.add_ons)}`);
+  }
   const returnedRecord = parseRecordValue(block?.add_ons?.record);
   if (!recordIncludes(recordObject, returnedRecord)) {
     throw new Error(`inserted HTML Box record mismatch: ${JSON.stringify(block?.add_ons)}`);
@@ -103,6 +122,10 @@ function insertHtmlBox(docToken, recordObject, identity) {
   return block?.block_id || '';
 }
 
+function isSuccessfulLarkResponse(resp) {
+  return resp?.ok === true || resp?.code === 0;
+}
+
 function runJson(commandArgs) {
   const out = execFileSync('lark-cli', commandArgs, {
     encoding: 'utf8',
@@ -149,4 +172,4 @@ function escapeXml(value) {
     .replaceAll("'", '&apos;');
 }
 
-module.exports = { run };
+module.exports = { HTML_BOX_COMPONENT_TYPE_IDS, resolveEdition, isSuccessfulLarkResponse, run };

package/src/commands/extract-cookie.js

@@ -1,7 +1,8 @@
 'use strict';
 
-const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+const { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
 const { basename, dirname, resolve } = require('path');
+const { getWidgetPublishConfigPath } = require('../lib/config');
 const { success, fail } = require('../lib/output');
 
 function run(args, opts) {
@@ -11,9 +12,24 @@ function run(args, opts) {
   const cookie = extractCookieFromCurl(curl);
   if (!cookie) fail('No Cookie found in curl. Expected -b/--cookie or a Cookie request header.', 'E_INVALID_ARGS');
 
+  if (opts.widgetPublish) {
+    const csrfToken = extractHeaderFromCurl(curl, 'x-csrf-token');
+    if (!csrfToken) fail('No x-csrf-token header found in curl.', 'E_INVALID_ARGS');
+    const output = resolve(String(opts.out || getWidgetPublishConfigPath()));
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, `${JSON.stringify({ cookie, csrfToken, timezoneOffset: -480 }, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    chmodSync(output, 0o600);
+    success({ path: output, filename: basename(output), widgetPublish: true }, opts);
+    return;
+  }
+
   const output = resolveOutput(opts.out, opts.outDir);
   mkdirSync(dirname(output), { recursive: true });
   writeFileSync(output, `${cookie}\n`, { encoding: 'utf8', mode: 0o600 });
+  chmodSync(output, 0o600);
   success({ path: output, filename: basename(output), cookieCount: cookie.split(';').filter(Boolean).length }, opts);
 }
 
@@ -43,6 +59,21 @@ function extractCookieFromCurl(curl) {
   return '';
 }
 
+function extractHeaderFromCurl(curl, headerName) {
+  const expected = String(headerName || '').toLowerCase();
+  const tokens = tokenizeShell(String(curl || '').replace(/\\\r?\n/g, ' '));
+  for (let i = 0; i < tokens.length; i++) {
+    let header = '';
+    if (tokens[i] === '-H' || tokens[i] === '--header') header = tokens[i + 1] || '';
+    else if (tokens[i].startsWith('--header=')) header = tokens[i].slice('--header='.length);
+    if (!header) continue;
+    const separator = header.indexOf(':');
+    if (separator < 0 || header.slice(0, separator).trim().toLowerCase() !== expected) continue;
+    return header.slice(separator + 1).trim();
+  }
+  return '';
+}
+
 function normalizeCookie(raw) {
   return String(raw || '').replace(/^cookie\s*:\s*/i, '').trim();
 }
@@ -82,4 +113,4 @@ function resolveOutput(out, outDir) {
   return resolve(String(outDir || process.cwd()), 'cookie.txt');
 }
 
-module.exports = { run, extractCookieFromCurl, resolveOutput };
+module.exports = { run, extractCookieFromCurl, extractHeaderFromCurl, resolveOutput };

package/src/commands/page.js

@@ -17,7 +17,103 @@ async function run(args, opts) {
   if (sub === 'list') return list(opts);
   if (sub === 'export') return exportApps(opts);
   if (sub === 'delete') return deletePage(opts);
-  fail('Usage: magic-builder page <publish|list|export|delete>', 'E_INVALID_ARGS');
+  if (sub === 'collaborators') return collaborators(args.slice(1), opts);
+  if (sub === 'access') return access(args.slice(1), opts);
+  fail('Usage: magic-builder page <publish|list|export|delete|collaborators|access>', 'E_INVALID_ARGS');
+}
+
+async function authenticatedRequest(opts, endpoint, requestOpts = {}) {
+  let token;
+  try { token = await getToken(opts); } catch (e) { fail(e.message, 'E_NO_TOKEN', 2); }
+  try { return await request(`${getBaseUrl(opts)}${endpoint}`, { token, ...requestOpts }); }
+  catch (e) { failFromHttpError(e); }
+}
+
+function requiredPageId(opts, command) {
+  const id = normalizeId(opts.id);
+  if (!id) fail(`Missing --id. Usage: magic-builder page ${command} --id <id>`, 'E_INVALID_ARGS');
+  return id;
+}
+
+function readJsonFile(file) {
+  if (!file) return null;
+  if (!fs.existsSync(file)) fail(`File not found: ${file}`, 'E_NOT_FOUND');
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { fail(`Invalid JSON file: ${e.message}`, 'E_INVALID_ARGS'); }
+}
+
+function parseIds(value, pattern, label, allowEmpty = false) {
+  const raw = Array.isArray(value) ? value : String(value ?? '').split(/[,，;；\n\r\t|]/);
+  const values = Array.from(new Set(raw.map((item) => String(item || '').trim()).filter(Boolean)));
+  const invalid = values.filter((id) => !pattern.test(id));
+  if (invalid.length) fail(`Invalid ${label}: ${invalid.join(', ')}`, 'E_INVALID_ARGS');
+  if (!allowEmpty && !values.length) fail(`Missing ${label}`, 'E_INVALID_ARGS');
+  return values;
+}
+
+async function collaborators(args, opts) {
+  const action = String(args[0] || '').toLowerCase();
+  const id = requiredPageId(opts, `collaborators ${action || '<list|add|remove|set>'}`);
+  const endpoint = `/api/html-box/${encodeURIComponent(id)}/collaborators`;
+  if (action === 'list') {
+    const res = await authenticatedRequest(opts, endpoint);
+    if (res.code !== 0) fail(res.msg || 'Collaborator query failed', 'E_COLLABORATORS_FAILED');
+    return success(res.data || res, opts);
+  }
+  if (!['add', 'remove', 'set'].includes(action)) fail('Usage: magic-builder page collaborators <list|add|remove|set> --id <id>', 'E_INVALID_ARGS');
+  const file = readJsonFile(opts.file);
+  const openIds = parseIds(file?.open_ids ?? file?.openIds ?? opts.openIds, /^ou_[A-Za-z0-9_-]+$/, 'open_id');
+  const res = await authenticatedRequest(opts, endpoint, { method: 'PATCH', body: { operation: action, open_ids: openIds } });
+  if (res.code !== 0) fail(res.msg || 'Collaborator update failed', 'E_COLLABORATORS_FAILED');
+  success(res.data || res, opts);
+}
+
+function parseBoolean(value, label) {
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['true', '1', 'yes', 'on', 'enabled'].includes(normalized)) return true;
+  if (['false', '0', 'no', 'off', 'disabled'].includes(normalized)) return false;
+  fail(`${label} must be true or false`, 'E_INVALID_ARGS');
+}
+
+async function access(args, opts) {
+  const action = String(args[0] || '').toLowerCase();
+  const id = requiredPageId(opts, `access ${action || '<get|enable|disable|require-login|users|groups|set>'}`);
+  const endpoint = `/api/html-box/${encodeURIComponent(id)}/access`;
+  if (action === 'get') {
+    const res = await authenticatedRequest(opts, endpoint);
+    if (res.code !== 0) fail(res.msg || 'Access query failed', 'E_ACCESS_FAILED');
+    return success(res.data || res, opts);
+  }
+  let body;
+  if (action === 'enable' || action === 'disable') {
+    body = { access_control_enabled: action === 'enable' };
+  } else if (action === 'require-login') {
+    if (opts.enabled === undefined) fail('Missing --enabled true|false', 'E_INVALID_ARGS');
+    body = { require_feishu_login: parseBoolean(opts.enabled, '--enabled') };
+  } else if (action === 'users' || action === 'groups') {
+    const operation = String(args[1] || '').toLowerCase();
+    if (!['add', 'remove', 'set'].includes(operation)) fail(`Usage: magic-builder page access ${action} <add|remove|set> --id <id>`, 'E_INVALID_ARGS');
+    const file = readJsonFile(opts.file);
+    const isUsers = action === 'users';
+    const source = isUsers ? (file?.open_ids ?? file?.user_open_ids ?? opts.openIds) : (file?.chat_ids ?? file?.group_chat_ids ?? opts.chatIds);
+    const ids = parseIds(source, isUsers ? /^ou_[A-Za-z0-9_-]+$/ : /^oc_[A-Za-z0-9_-]+$/, isUsers ? 'open_id' : 'chat_id', operation === 'set');
+    body = { operation, target: action, [isUsers ? 'access_users' : 'access_groups']: ids.map((value) => ({ id: value })) };
+  } else if (action === 'set') {
+    const file = readJsonFile(opts.file);
+    if (!file || typeof file !== 'object' || Array.isArray(file)) fail('Missing --file <access.json>', 'E_INVALID_ARGS');
+    body = {};
+    if (Object.prototype.hasOwnProperty.call(file, 'access_control_enabled')) body.access_control_enabled = parseBoolean(file.access_control_enabled, 'access_control_enabled');
+    if (Object.prototype.hasOwnProperty.call(file, 'require_feishu_login')) body.require_feishu_login = parseBoolean(file.require_feishu_login, 'require_feishu_login');
+    if (Object.prototype.hasOwnProperty.call(file, 'user_open_ids')) body.access_users = parseIds(file.user_open_ids, /^ou_[A-Za-z0-9_-]+$/, 'open_id', true).map((value) => ({ id: value }));
+    if (Object.prototype.hasOwnProperty.call(file, 'group_chat_ids')) body.access_groups = parseIds(file.group_chat_ids, /^oc_[A-Za-z0-9_-]+$/, 'chat_id', true).map((value) => ({ id: value }));
+    if (!Object.keys(body).length) fail('Access JSON contains no supported settings', 'E_INVALID_ARGS');
+  } else {
+    fail('Usage: magic-builder page access <get|enable|disable|require-login|users|groups|set> --id <id>', 'E_INVALID_ARGS');
+  }
+  const res = await authenticatedRequest(opts, endpoint, { method: 'PATCH', body });
+  if (res.code !== 0) fail(res.msg || 'Access update failed', 'E_ACCESS_FAILED');
+  success(res.data || res, opts);
 }
 
 async function publish(args, opts) {
@@ -39,7 +135,9 @@ async function publish(args, opts) {
   const existingId = opts.id || config[relPath]?.id || config[relPath]?.remoteId;
 
   const body = { html, title };
+  if (opts.customId !== undefined) body.custom_id = String(opts.customId).trim();
   if (opts.openSource) body.is_open_source = true;
+  if (opts.comments !== undefined) body.comments_enabled = opts.comments === true || String(opts.comments).toLowerCase() !== 'false';
 
   if (!opts.quiet) process.stderr.write(`${existingId ? 'Updating' : 'Publishing'} ${relPath}... `);
 
@@ -56,13 +154,17 @@ async function publish(args, opts) {
   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 appUrl = data.app_url || `${baseUrl}/app/${id}`;
+  const url = data.url || (data.runtime === 'html-box' ? htmlBoxUrl : appUrl);
   const dashboardUrl = data.dashboard_url || `${baseUrl}/dashboard/${id}`;
 
   config[relPath] = {
     id,
     remoteId: id,
     title,
+    customId: opts.customId !== undefined ? String(opts.customId).trim() : (config[relPath]?.customId || ''),
     urls: {
+      app: appUrl,
       html_box: htmlBoxUrl,
       dashboard: dashboardUrl,
       panel: data.panel_url || '',
@@ -76,6 +178,10 @@ async function publish(args, opts) {
   success({
     id,
     title,
+    custom_id: data.custom_id || body.custom_id || '',
+    url,
+    runtime: data.runtime || (url === htmlBoxUrl ? 'html-box' : 'app'),
+    app_url: appUrl,
     html_box_url: htmlBoxUrl,
     dashboard_url: dashboardUrl,
     panel_url: data.panel_url || '',
@@ -273,4 +379,4 @@ function formatHtmlLimitMessage(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 };
+module.exports = { run, parseIds, parseBoolean };