magic-builder 1.3.2 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # magic-builder
 
-CLI for Magic Builder (妙笔): publish HTML pages, deploy FaaS functions, upload files, generate links, and install the Magic Builder Codex skill.
+CLI for Magic Builder (妙笔): publish HTML pages, create Feishu app bots, deploy FaaS functions, upload files, generate links, and install the Magic Builder Codex skill.
 
 ## Install
 
@@ -103,6 +103,18 @@ Deploy a FaaS function:
 magic-builder faas publish handler.js --name report-api
 ```
 
+Create a Feishu app bot backed by Magic FaaS:
+
+```bash
+chmod 600 ./bot.credentials.json
+magic-builder bot create \
+  --handler ./bot.js \
+  --name my_bot \
+  --credentials ./bot.credentials.json
+```
+
+Pass `--faas-id <existing-id>` when updating an existing bot so its event callback URL stays unchanged.
+
 Publish a Tools-only MCP service (ordinary HTTP `handler` may coexist):
 
 ```bash

package/bin/magic-builder.js

@@ -8,6 +8,7 @@ const COMMANDS = {
   auth: require('../src/commands/auth'),
   page: require('../src/commands/page'),
   faas: require('../src/commands/faas'),
+  bot: require('../src/commands/bot'),
   file: require('../src/commands/file'),
   link: require('../src/commands/link'),
   doc: require('../src/commands/doc'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "magic-builder",
-  "version": "1.3.2",
-  "description": "CLI for Magic Builder — publish pages, functions, files, and performance reviews",
+  "version": "1.4.0",
+  "description": "CLI for Magic Builder — publish pages, bots, functions, files, and performance reviews",
   "bin": {
     "magic-builder": "bin/magic-builder.js",
     "magic-cli": "bin/magic-builder.js",
@@ -26,6 +26,7 @@
     "miaobi",
     "cli",
     "faas",
+    "bot",
     "publish"
   ],
   "license": "MIT",

package/src/commands/auth.js

@@ -29,6 +29,7 @@ async function login(opts) {
   const requestId = String(data.request_id || '');
   const pollToken = String(data.poll_token || '');
   const authUrl = String(data.auth_url || '');
+  const pollUrl = String(data.poll_url || '').trim() || `${baseUrl}/api/dev-token/auth/token`;
   if (!requestId || !pollToken || !authUrl) {
     fail(`Invalid auth start response: ${JSON.stringify(start)}`, 'E_AUTH_FAILED', 2);
   }
@@ -45,7 +46,7 @@ async function login(opts) {
 
   const deadline = Date.now() + timeoutSeconds * 1000;
   while (Date.now() < deadline) {
-    const tokenJson = await request(`${baseUrl}/api/dev-token/auth/token`, {
+    const tokenJson = await request(pollUrl, {
       method: 'POST',
       body: {
         request_id: requestId,

package/src/commands/bot.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const fs = require('fs');
+const { getBaseUrl } = require('../lib/config');
+const { request } = require('../lib/http');
+const { formatOutput, success, fail, failFromHttpError } = require('../lib/output');
+const { publishFaas } = require('./faas');
+
+const REQUIRED_CREDENTIAL_FIELDS = ['app_id', 'app_secret', 'verification_token', 'app_name'];
+const ALLOWED_CREDENTIAL_FIELDS = [...REQUIRED_CREDENTIAL_FIELDS, 'encrypted_key', 'developer_open_id'];
+
+async function run(args, opts) {
+  if (args[0] !== 'create') {
+    fail('Usage: magic-builder bot create --handler <file.js> --name <name> --credentials <file.json> [--faas-id <id>]', 'E_INVALID_ARGS');
+  }
+  for (const required of ['handler', 'name', 'credentials']) {
+    if (!String(opts[required] || '').trim()) fail(`--${required} is required`, 'E_INVALID_ARGS');
+  }
+
+  try {
+    const result = await createMagicBot({
+      handler: opts.handler,
+      name: opts.name,
+      credentials: readCredentials(opts.credentials),
+      faasId: opts.faasId,
+      baseUrl: opts.baseUrl,
+    }, { cliOptions: opts });
+
+    if (!result.ok) {
+      process.stdout.write(formatOutput(result, opts.format) + '\n');
+      process.exitCode = 1;
+      return;
+    }
+    success(result, opts);
+  } catch (error) {
+    if (error.code === 'E_NO_TOKEN') fail(error.message, error.code, 2);
+    if (error.code === 'E_PUBLISH_FAILED') fail(error.message, error.code);
+    if (error.code) failFromHttpError(error);
+    throw error;
+  }
+}
+
+function readCredentials(filePath, { enforcePermissions = true } = {}) {
+  if (!fs.existsSync(filePath)) throw new Error(`Credentials file not found: ${filePath}`);
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) throw new Error(`Credentials path is not a file: ${filePath}`);
+  if (enforcePermissions && process.platform !== 'win32' && (stat.mode & 0o077) !== 0) {
+    throw new Error('credentials file permissions must be 0600 or stricter');
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Invalid credentials JSON: ${error.message}`);
+  }
+  for (const field of REQUIRED_CREDENTIAL_FIELDS) {
+    if (!String(parsed?.[field] || '').trim()) throw new Error(`credentials.${field} is required`);
+  }
+  return Object.fromEntries(ALLOWED_CREDENTIAL_FIELDS.flatMap((field) => (
+    parsed[field] === undefined ? [] : [[field, String(parsed[field]).trim()]]
+  )));
+}
+
+function validateHandler(filePath) {
+  if (!fs.existsSync(filePath)) throw new Error(`Handler file not found: ${filePath}`);
+  const source = fs.readFileSync(filePath, 'utf8');
+  if (!source.trim()) throw new Error('Handler file is empty');
+  if (!/module\.exports\s*=/.test(source)) throw new Error('handler must use module.exports');
+  Function(source);
+  return source;
+}
+
+function normalizeFaasId(value) {
+  return String(value || '').trim().replace(/^rec/, '');
+}
+
+function buildCallbackUrl(baseUrl, appId, faasId) {
+  const url = new URL(`/api/event/${encodeURIComponent(appId)}`, baseUrl);
+  url.searchParams.set('faas_id', normalizeFaasId(faasId));
+  return url.toString();
+}
+
+async function createMagicBot(options, dependencies = {}) {
+  const publishFaasImpl = dependencies.publishFaasImpl || publishFaas;
+  const requestImpl = dependencies.requestImpl || request;
+  const fetchImpl = dependencies.fetchImpl || globalThis.fetch;
+  const cliOptions = dependencies.cliOptions || {};
+  const baseUrl = String(options.baseUrl || getBaseUrl(cliOptions)).replace(/\/+$/, '');
+  const source = validateHandler(options.handler);
+
+  const published = await publishFaasImpl({
+    code: source,
+    name: options.name,
+    id: options.faasId,
+  }, { ...cliOptions, baseUrl });
+  const publishedId = published?.id || published?.record_id;
+  const faasId = normalizeFaasId(publishedId || options.faasId);
+  if (!faasId) throw new Error('FaaS publish response is missing id');
+  const faasUrl = published?.faas_url || `${baseUrl}/api/faas/${faasId}`;
+  const callbackUrl = buildCallbackUrl(baseUrl, options.credentials.app_id, faasId);
+
+  let registration;
+  try {
+    registration = await requestImpl(`${baseUrl}/api/app`, {
+      method: 'POST',
+      body: options.credentials,
+    });
+  } catch (error) {
+    return partialFailure('app_registration', error.message, faasId, faasUrl, callbackUrl);
+  }
+  if (registration?.code !== 0) {
+    return partialFailure('app_registration', registration?.msg || 'App registration failed', faasId, faasUrl, callbackUrl);
+  }
+
+  const challengeValue = `magic-bot-${Date.now().toString(36)}`;
+  let callbackVerified = false;
+  let challengeError = '';
+  try {
+    const response = await fetchImpl(callbackUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ challenge: challengeValue }),
+    });
+    const challenge = await response.json().catch(() => ({}));
+    callbackVerified = response.ok && challenge?.challenge === challengeValue;
+    if (!callbackVerified) challengeError = challenge?.msg || `HTTP ${response.status}`;
+  } catch (error) {
+    challengeError = error.message || 'Challenge request failed';
+  }
+
+  const result = {
+    ok: callbackVerified,
+    stage: callbackVerified ? 'complete' : 'challenge_verification',
+    app_id: options.credentials.app_id,
+    app_name: options.credentials.app_name,
+    faas_id: faasId,
+    faas_url: faasUrl,
+    event_callback_url: callbackUrl,
+    registration_action: registration?.data?.action || 'unknown',
+    callback_verified: callbackVerified,
+    next_steps: [
+      '在飞书开放平台事件订阅中填写 event_callback_url',
+      '勾选 handler 实际处理的事件并发布应用版本',
+      '把机器人加入目标会话并发送真实消息验收',
+    ],
+  };
+  if (!callbackVerified) result.error = challengeError || 'Challenge verification failed';
+  return result;
+}
+
+function partialFailure(stage, error, faasId, faasUrl, callbackUrl) {
+  return {
+    ok: false,
+    stage,
+    faas_id: faasId,
+    faas_url: faasUrl,
+    event_callback_url: callbackUrl,
+    error: String(error || 'Unknown error'),
+  };
+}
+
+module.exports = {
+  run,
+  buildCallbackUrl,
+  createMagicBot,
+  normalizeFaasId,
+  readCredentials,
+  validateHandler,
+};

package/src/commands/faas.js

@@ -29,53 +29,77 @@ async function publish(args, opts) {
     if (!code.trim()) fail('JS file is empty', 'E_EMPTY_FILE');
   }
 
+  const name = opts.name || generateName(args[0]);
+
+  if (!opts.quiet) process.stderr.write(`Deploying FaaS${opts.name ? ` "${opts.name}"` : ''}... `);
+
+  try {
+    const result = await publishFaas({
+      code,
+      name,
+      id: opts.id,
+      mcp: opts.mcp,
+      auth: opts.auth,
+      oauthUser: opts.oauthUser,
+      oauthPolicy: opts.oauthPolicy,
+    }, opts);
+
+    if (!opts.quiet) process.stderr.write('done\n');
+    success(result, opts);
+  } catch (e) {
+    if (e.code === 'E_NO_TOKEN') fail(e.message, e.code, 2);
+    if (e.code === 'E_PUBLISH_FAILED') fail(e.message, e.code);
+    failFromHttpError(e);
+  }
+}
+
+async function publishFaas(input, opts = {}, dependencies = {}) {
+  const getTokenImpl = dependencies.getTokenImpl || getToken;
+  const requestImpl = dependencies.requestImpl || request;
   let token;
-  try { token = await getToken(opts); } catch (e) { fail(e.message, 'E_NO_TOKEN', 2); }
+  try {
+    token = await getTokenImpl(opts);
+  } catch (error) {
+    error.code = error.code || 'E_NO_TOKEN';
+    throw error;
+  }
 
   const baseUrl = getBaseUrl(opts);
-  const name = opts.name || generateName(args[0]);
-
-  const body = { code, name };
-  if (opts.id) body.id = opts.id;
-  if (opts.mcp) {
+  const body = { code: input.code, name: input.name };
+  if (input.id) body.id = input.id;
+  if (input.mcp) {
     body.mcp = true;
-    body.auth = String(opts.auth || 'key').split(',').map((item) => item.trim()).filter(Boolean);
-    if (opts.oauthUser !== undefined) {
-      body.oauth_users = String(opts.oauthUser || '').split(',').map((item) => item.trim()).filter(Boolean);
+    body.auth = String(input.auth || 'key').split(',').map((item) => item.trim()).filter(Boolean);
+    if (input.oauthUser !== undefined) {
+      body.oauth_users = String(input.oauthUser || '').split(',').map((item) => item.trim()).filter(Boolean);
     }
-    if (opts.oauthPolicy !== undefined) body.oauth_policy = String(opts.oauthPolicy).trim().toLowerCase();
+    if (input.oauthPolicy !== undefined) body.oauth_policy = String(input.oauthPolicy).trim().toLowerCase();
     else if (body.oauth_users?.length) body.oauth_policy = 'whitelist';
   }
 
-  if (!opts.quiet) process.stderr.write(`Deploying FaaS${opts.name ? ` "${opts.name}"` : ''}... `);
-
-  let res;
-  try {
-    res = await request(`${baseUrl}/api/faas`, {
-      method: 'POST',
-      token,
-      body,
-    });
-  } catch (e) { failFromHttpError(e); }
-
-  if (res.code !== 0) fail(res.msg || 'FaaS publish failed', 'E_PUBLISH_FAILED');
+  const res = await requestImpl(`${baseUrl}/api/faas`, {
+    method: 'POST',
+    token,
+    body,
+  });
+  if (res.code !== 0) {
+    const error = new Error(res.msg || 'FaaS publish failed');
+    error.code = 'E_PUBLISH_FAILED';
+    throw error;
+  }
 
   const data = res.data || res;
   const id = data.id || data.record_id;
   const faasUrl = data.faas_url || `/api/faas/${id}`;
   const mcpUrl = data.mcp_url || `/api/faas/${id}/mcp`;
-
-  if (!opts.quiet) process.stderr.write('done\n');
-
   const wsBaseUrl = baseUrl.replace(/^https?/, 'wss');
-
-  success({
+  return {
     id: data.record_id || id,
     faas_url: `${baseUrl}${faasUrl}`,
     preview_url: `${baseUrl}/r?fid=${id}`,
     wss_url: `${wsBaseUrl}${faasUrl}`,
-    ...(opts.mcp ? { mcp_url: `${baseUrl}${mcpUrl}`, mcp_auth: data.mcp_auth || body.auth } : {}),
-  }, opts);
+    ...(input.mcp ? { mcp_url: `${baseUrl}${mcpUrl}`, mcp_auth: data.mcp_auth || body.auth } : {}),
+  };
 }
 
 async function mcp(args, opts) {
@@ -179,4 +203,4 @@ function generateName(filePath) {
   return base.replace(/[^a-zA-Z0-9_]/g, '_').slice(0, 50);
 }
 
-module.exports = { run };
+module.exports = { run, publishFaas };

package/src/index.js

@@ -9,6 +9,7 @@ module.exports = {
     auth: require('./commands/auth'),
     page: require('./commands/page'),
     faas: require('./commands/faas'),
+    bot: require('./commands/bot'),
     file: require('./commands/file'),
     link: require('./commands/link'),
     doc: require('./commands/doc'),

package/src/lib/help.js

@@ -17,6 +17,7 @@ COMMANDS:
   auth       Login and manage Magic developer tokens
   page       Publish and manage Magic pages, collaborators, and access
   faas       Publish and manage Magic FaaS HTTP/WSS/MCP functions
+  bot        Create or update a Feishu app bot backed by Magic FaaS
   file       Upload, list, and delete TOS files
   link       Generate Magic share links
   doc        Create or append Feishu Doc HTML Box apps
@@ -45,6 +46,7 @@ EXAMPLES:
   magic-builder faas publish server.js --name weather-mcp --mcp --auth key,oauth
   magic-builder faas list
   magic-builder faas delete --id recxxx
+  magic-builder bot create --handler bot.js --name echo-bot --credentials ./bot.credentials.json
   magic-builder file upload logo.png
   magic-builder file list
   magic-builder file delete --id recxxx
@@ -112,6 +114,8 @@ COMMANDS:
   faas mcp auth get --id <id>
   faas mcp auth update --id <id> [--auth key,oauth] [--oauth-policy all|whitelist] [--oauth-user ou_xxx]
 
+  bot create --handler <file.js> --name <name> --credentials <file.json> [--faas-id <id>]
+
   file upload <file> [--key <key>] [--content-type <mime>]
   file list [--title <keyword>]
   file delete --id <id>
@@ -209,6 +213,21 @@ SYNTAX:
   magic-builder faas mcp key revoke --id <id> --key-id <key_id>
   magic-builder faas mcp auth get --id <id>
   magic-builder faas mcp auth update --id <id> --oauth-policy whitelist --oauth-user ou_xxx
+`,
+  bot: `@HELP magic-builder/bot
+
+BRIEF: Create or update a Feishu app bot backed by Magic FaaS.
+
+SYNTAX:
+  magic-builder bot create --handler <file.js> --name <name> --credentials <file.json> [--faas-id <id>]
+
+CREDENTIALS:
+  The JSON file must contain app_id, app_secret, verification_token, and app_name.
+  encrypted_key and developer_open_id are optional. On POSIX systems the file
+  permissions must be 0600 or stricter.
+
+UPDATE:
+  Pass the existing --faas-id to update a bot without changing its callback URL.
 `,
   file: `@HELP magic-builder/file