magic-builder 0.1.0

package/src/commands/skill.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { success, fail } = require('../lib/output');
+
+const SKILL_ID = 'magic-builder';
+const ZIP_URL = 'https://magic-builder.tos-cn-beijing.volces.com/skills/magic-builder.skill.zip';
+const REPLACED_SKILLS = [
+  'generate-magic-page',
+  'generate-magic-doc',
+  'publish-magic-page',
+  'publish-magic-faas',
+  'magic-url-preview',
+  'upload-file-to-tos',
+  'magic-user-feedback',
+  'check-magic-builder-update',
+];
+
+async function run(args, opts) {
+  const sub = args[0];
+  if (sub !== 'check-update' && sub !== 'update' && sub !== 'install') {
+    fail('Usage: magic-builder skill <check-update|update|install>', 'E_INVALID_ARGS');
+  }
+  const skillsRoot = path.resolve(opts.skillsRoot || path.join(os.homedir(), '.codex', 'skills'));
+  const environment = resolveEnvironment(String(opts.environment || 'auto'), skillsRoot);
+  const remote = await prepareRemotePackage();
+  const report = buildReport(remote, skillsRoot, environment);
+  if (environment === 'cloud') report.cloud_update = buildCloudUpdateDescriptor(report, { includeSkill: sub === 'install' });
+
+  if (sub === 'update' || sub === 'install') {
+    if (environment === 'cloud') {
+      success(report, opts);
+      return;
+    }
+    report.install = await installUpdate(report, remote, skillsRoot);
+    if (sub === 'install') report.installed = true;
+  }
+  success(report, opts);
+}
+
+async function downloadFile(url, dest) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`GET ${url} failed: HTTP ${res.status}`);
+  const arrayBuffer = await res.arrayBuffer();
+  fs.writeFileSync(dest, Buffer.from(arrayBuffer));
+}
+
+async function prepareRemotePackage() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), `magic-builder-remote-${stamp}-`));
+  const zipPath = path.join(workDir, 'magic-builder.skill.zip');
+  const extractDir = path.join(workDir, 'extract');
+  fs.mkdirSync(extractDir, { recursive: true });
+  await downloadFile(ZIP_URL, zipPath);
+  runUnzip(zipPath, extractDir);
+
+  const candidates = [
+    path.join(extractDir, SKILL_ID),
+    path.join(extractDir, SKILL_ID, SKILL_ID),
+  ];
+  const packageRoot = candidates.find((candidate) => fs.existsSync(path.join(candidate, 'SKILL.md')));
+  if (!packageRoot) throw new Error(`Downloaded zip does not contain ${SKILL_ID}/SKILL.md`);
+  const meta = readSkillMetadata(packageRoot);
+  if (meta.name !== SKILL_ID || !meta.version) {
+    throw new Error(`Invalid remote SKILL.md metadata: name=${meta.name || ''}, version=${meta.version || ''}`);
+  }
+  return { workDir, zipPath, extractDir, packageRoot, version: meta.version };
+}
+
+function buildReport(remote, skillsRoot, environment) {
+  const local = readLocalVersion(skillsRoot);
+  const cmp = local.exists && local.version ? compareVersions(remote.version, local.version) : 1;
+  const status = !local.exists ? 'missing' : cmp > 0 ? 'update_available' : cmp < 0 ? 'local_newer' : 'current';
+  return {
+    ok: true,
+    environment,
+    update_strategy: environment === 'cloud' ? 'cloud_managed_skill_update' : 'local_filesystem',
+    package: { name: SKILL_ID, remote_version: remote.version, zip_url: ZIP_URL },
+    skills_root: skillsRoot,
+    update_available: status === 'missing' || status === 'update_available',
+    skill: {
+      id: SKILL_ID,
+      local_version: local.version,
+      remote_version: remote.version,
+      local_path: local.path,
+      status,
+      replaces: REPLACED_SKILLS,
+    },
+  };
+}
+
+function buildCloudUpdateDescriptor(report, options = {}) {
+  const includeSkill = options.includeSkill || report.update_available;
+  return {
+    strategy: 'cloud_managed_skill_update',
+    package: report.package,
+    skills: includeSkill ? [{
+      id: SKILL_ID,
+      local_version: report.skill.local_version,
+      remote_version: report.skill.remote_version,
+      status: report.skill.status,
+      replaces: REPLACED_SKILLS,
+    }] : [],
+    instructions: [
+      'Use the cloud runtime managed skill update/install mechanism.',
+      'Do not copy files into ~/.codex/skills or overwrite local filesystem paths in cloud mode.',
+      'If no managed cloud updater is exposed, report this descriptor and do not claim the update was applied.',
+    ],
+  };
+}
+
+async function installUpdate(report, remote, skillsRoot) {
+  const backupDir = path.join(remote.workDir, 'backup');
+  fs.mkdirSync(backupDir, { recursive: true });
+  const installed = [];
+  const removed = [];
+  const targetDir = path.join(skillsRoot, SKILL_ID);
+  if (fs.existsSync(targetDir)) {
+    fs.cpSync(targetDir, path.join(backupDir, SKILL_ID), { recursive: true });
+    fs.rmSync(targetDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  fs.cpSync(remote.packageRoot, targetDir, { recursive: true });
+  installed.push(SKILL_ID);
+
+  for (const replacedId of REPLACED_SKILLS) {
+    ensureSafeSkillId(replacedId);
+    const replacedDir = path.join(skillsRoot, replacedId);
+    if (!fs.existsSync(replacedDir)) continue;
+    fs.cpSync(replacedDir, path.join(backupDir, replacedId), { recursive: true });
+    fs.rmSync(replacedDir, { recursive: true, force: true });
+    removed.push(replacedId);
+  }
+  return { zip_path: remote.zipPath, backup_dir: backupDir, installed, removed };
+}
+
+function readSkillMetadata(skillDir) {
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) return { exists: false, name: null, version: null, path: skillPath };
+  const text = fs.readFileSync(skillPath, 'utf8');
+  const nameMatch = text.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m);
+  const versionMatch = text.match(/^version:\s*["']?([^"'\n]+)["']?\s*$/m);
+  return {
+    exists: true,
+    name: nameMatch ? nameMatch[1].trim() : null,
+    version: versionMatch ? versionMatch[1].trim() : null,
+    path: skillPath,
+  };
+}
+
+function readLocalVersion(skillsRoot) {
+  const meta = readSkillMetadata(path.join(skillsRoot, SKILL_ID));
+  return { exists: meta.exists, version: meta.version, path: meta.path };
+}
+
+function compareVersions(a, b) {
+  const pa = String(a || '0').split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  const pb = String(b || '0').split(/[.-]/).map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const va = pa[i] == null ? 0 : pa[i];
+    const vb = pb[i] == null ? 0 : pb[i];
+    if (va === vb) continue;
+    if (typeof va === 'number' && typeof vb === 'number') return va > vb ? 1 : -1;
+    return String(va) > String(vb) ? 1 : -1;
+  }
+  return 0;
+}
+
+function resolveEnvironment(requested, skillsRoot) {
+  if (requested === 'local' || requested === 'cloud') return requested;
+  if (requested !== 'auto') fail('--environment must be auto, local, or cloud', 'E_INVALID_ARGS');
+  const explicit = String(process.env.MAGIC_BUILDER_UPDATE_ENV || process.env.CODEX_RUNTIME_ENV || '').trim().toLowerCase();
+  if (explicit === 'cloud' || explicit === 'remote') return 'cloud';
+  if (explicit === 'local') return 'local';
+  try { fs.accessSync(skillsRoot, fs.constants.W_OK); } catch { return 'cloud'; }
+  return 'local';
+}
+
+function runUnzip(zipPath, destDir) {
+  const result = spawnSync('unzip', ['-q', zipPath, '-d', destDir], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(`unzip failed: ${result.stderr || result.stdout || `exit ${result.status}`}`);
+}
+
+function ensureSafeSkillId(id) {
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(id)) throw new Error(`Unsafe skill id in update package: ${id}`);
+}
+
+module.exports = { run };

package/src/index.js

@@ -0,0 +1,20 @@
+'use strict';
+
+module.exports = {
+  config: require('./lib/config'),
+  auth: require('./lib/auth'),
+  http: require('./lib/http'),
+  output: require('./lib/output'),
+  commands: {
+    auth: require('./commands/auth'),
+    page: require('./commands/page'),
+    faas: require('./commands/faas'),
+    asset: require('./commands/asset'),
+    link: require('./commands/link'),
+    doc: require('./commands/doc'),
+    feedback: require('./commands/feedback'),
+    skill: require('./commands/skill'),
+    doctor: require('./commands/doctor'),
+    config: require('./commands/config'),
+  },
+};

package/src/lib/auth.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const TOKEN_FILE = path.join(os.homedir(), '.magic-token');
+const PROJECT_TOKEN_FILE = path.join(process.cwd(), '.magic-token');
+
+function getToken(opts = {}) {
+  if (opts.token) return Promise.resolve(opts.token);
+  if (process.env.MAGIC_TOKEN) return Promise.resolve(process.env.MAGIC_TOKEN);
+
+  for (const file of [TOKEN_FILE, PROJECT_TOKEN_FILE]) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const t = fs.readFileSync(file, 'utf8').trim();
+      if (t) return Promise.resolve(t);
+    } catch (_) {}
+  }
+
+  return Promise.reject(new Error('Not logged in. Run: magic-builder auth login'));
+}
+
+function setToken(value) {
+  fs.writeFileSync(TOKEN_FILE, value.trim(), { mode: 0o600 });
+}
+
+function showToken() {
+  if (process.env.MAGIC_TOKEN) {
+    return mask(process.env.MAGIC_TOKEN);
+  }
+  for (const file of [TOKEN_FILE, PROJECT_TOKEN_FILE]) {
+    if (!fs.existsSync(file)) continue;
+    try {
+      const t = fs.readFileSync(file, 'utf8').trim();
+      if (t) return mask(t);
+    } catch (_) {}
+  }
+  return null;
+}
+
+function mask(t) {
+  if (t.length <= 8) return '****';
+  return t.slice(0, 4) + '****' + t.slice(-4);
+}
+
+module.exports = { getToken, setToken, showToken, TOKEN_FILE, PROJECT_TOKEN_FILE };

package/src/lib/config.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_BASE_URL = 'https://magic.solutionsuite.cn';
+const APPS_CONFIG_FILE = '.magic-apps.json';
+
+function normalizeMagicBaseUrl(value) {
+  const raw = String(value || DEFAULT_BASE_URL).trim().replace(/\/+$/, '');
+  if (!raw) return DEFAULT_BASE_URL;
+  return /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+}
+
+function getBaseUrl(opts = {}) {
+  return normalizeMagicBaseUrl(opts.baseUrl || process.env.MAGIC_BASE_URL);
+}
+
+function getAppsConfigPath() {
+  return path.join(process.cwd(), APPS_CONFIG_FILE);
+}
+
+function loadAppsConfig() {
+  const p = getAppsConfigPath();
+  if (fs.existsSync(p)) {
+    try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) {}
+  }
+  return {};
+}
+
+function saveAppsConfig(config) {
+  fs.writeFileSync(getAppsConfigPath(), JSON.stringify(config, null, 2));
+}
+
+module.exports = { DEFAULT_BASE_URL, normalizeMagicBaseUrl, getBaseUrl, loadAppsConfig, saveAppsConfig };

package/src/lib/help.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const VERSION = require('../../package.json').version;
+
+const USAGE = `@USAGE magic-builder
+
+BRIEF: CLI for Magic Builder (妙笔).
+
+SYNTAX:
+  magic-builder <command> <subcommand> [options]
+
+COMMANDS:
+  auth       Login and manage Magic developer tokens
+  page       Publish, list, and export Magic pages
+  faas       Publish Magic FaaS functions
+  asset      Upload files to TOS
+  link       Generate Magic share links
+  doc        Create or append Feishu Doc HTML Box apps
+  feedback   Create Magic feedback records
+  skill      Check or update the Magic Builder skill package
+  doctor     Check local CLI environment
+  config     Show resolved CLI configuration
+
+EXAMPLES:
+  magic-builder auth login
+  magic-builder page publish app.html --title "Dashboard"
+  magic-builder page list --scope mine
+  magic-builder page export --id recxxx --out app.html
+  magic-builder faas publish handler.js --name report-api
+  magic-builder asset upload logo.png
+  magic-builder link create --title "Weekly Report"
+  magic-builder doc create --html app.html --title "Demo"
+  magic-builder feedback create --feedback "打不开页面"
+  magic-builder skill install
+  magic-builder skill check-update
+
+ALIASES:
+  magic-cli and miaobi are equivalent executable names.
+`;
+
+const HELP = `@HELP magic-builder
+
+BRIEF: Unified CLI for the Magic Builder platform.
+
+SYNTAX:
+  magic-builder <command> <subcommand> [options]
+
+GLOBAL OPTIONS:
+  --base-url, --magic-base-url <url>   Magic service base URL
+  --token <token>                      Auth token override
+  --format json|table|plain            Output format, default json
+  --quiet, -q                          Suppress progress messages
+  --version, -v                        Show version
+  --help, -h                           Show help
+  --man                                Show full manual
+
+COMMANDS:
+  auth login [--no-open] [--timeout <seconds>] [--interval <seconds>]
+  auth set <token>
+  auth show
+
+  page publish <html> --title <title> [--id <id>] [--open-source]
+  page list [--title <keyword>] [--scope mine|public]
+  page export --id <id> --out <file|dir> [--scope mine|public]
+  page export --title <keyword> --out <dir> [--all] [--scope mine|public]
+
+  faas publish <file.js> --name <name> [--id <id>]
+  faas publish --code <code> --name <name> [--id <id>]
+
+  asset upload <file> [--key <key>] [--content-type <mime>]
+
+  link create --title <text>
+  link create --fid <id>
+
+  doc create --html <file> --title <title> [--summary <text>] [--as bot|user]
+  doc append --html <file> --doc-token <token> [--as bot|user]
+
+  feedback create --feedback <text> [--title <title>] [--summary <text>]
+  feedback create --feedback-file <file> [--dry-run]
+
+  skill install [--environment auto|local|cloud] [--skills-root <dir>]
+  skill check-update [--environment auto|local|cloud] [--skills-root <dir>]
+  skill update [--environment auto|local|cloud] [--skills-root <dir>]
+
+  doctor
+  config get
+`;
+
+const MAN = `${HELP}
+
+AUTHENTICATION:
+  Token lookup order: --token flag, MAGIC_TOKEN environment variable, ~/.magic-token.
+  Use "magic-builder auth login" for browser-based Magic developer token auth.
+
+OUTPUT:
+  json is the default and is intended for agents and scripts.
+  plain prints key-value pairs or command-specific plain text where available.
+  table prints compact human-readable key-value output.
+
+VERSION:
+  ${VERSION}
+`;
+
+const SUBCOMMAND_HELP = {
+  auth: `@HELP magic-builder/auth
+
+SYNTAX:
+  magic-builder auth login [--no-open] [--timeout <seconds>] [--interval <seconds>]
+  magic-builder auth set <token>
+  magic-builder auth show
+`,
+  page: `@HELP magic-builder/page
+
+SYNTAX:
+  magic-builder page publish <html> --title <title> [--id <id>] [--open-source]
+  magic-builder page list [--title <keyword>] [--scope mine|public]
+  magic-builder page export --id <id> --out <file|dir> [--scope mine|public]
+  magic-builder page export --title <keyword> --out <dir> [--all] [--scope mine|public]
+`,
+  faas: `@HELP magic-builder/faas
+
+SYNTAX:
+  magic-builder faas publish <file.js> --name <name> [--id <id>]
+  magic-builder faas publish --code <code> --name <name> [--id <id>]
+`,
+  asset: `@HELP magic-builder/asset
+
+SYNTAX:
+  magic-builder asset upload <file> [--key <key>] [--content-type <mime>]
+`,
+  link: `@HELP magic-builder/link
+
+SYNTAX:
+  magic-builder link create --title <text>
+  magic-builder link create --fid <id>
+`,
+  doc: `@HELP magic-builder/doc
+
+SYNTAX:
+  magic-builder doc create --html <file> --title <title> [--summary <text>] [--as bot|user]
+  magic-builder doc append --html <file> --doc-token <token> [--as bot|user]
+`,
+  feedback: `@HELP magic-builder/feedback
+
+SYNTAX:
+  magic-builder feedback create --feedback <text>
+  magic-builder feedback create --feedback-file <file>
+`,
+  skill: `@HELP magic-builder/skill
+
+SYNTAX:
+  magic-builder skill install [--environment auto|local|cloud] [--skills-root <dir>]
+  magic-builder skill check-update [--environment auto|local|cloud] [--skills-root <dir>]
+  magic-builder skill update [--environment auto|local|cloud] [--skills-root <dir>]
+`,
+  doctor: `@HELP magic-builder/doctor
+
+SYNTAX:
+  magic-builder doctor
+`,
+  config: `@HELP magic-builder/config
+
+SYNTAX:
+  magic-builder config get
+`,
+};
+
+function renderHelp(level, command) {
+  if (level === 'man') return MAN;
+  if (level === 'help' && command && SUBCOMMAND_HELP[command]) return SUBCOMMAND_HELP[command];
+  if (level === 'help') return HELP;
+  return USAGE;
+}
+
+module.exports = { renderHelp, USAGE, HELP, MAN, SUBCOMMAND_HELP };

package/src/lib/http.js

@@ -0,0 +1,78 @@
+'use strict';
+
+const MAX_RETRIES = 2;
+const TIMEOUT_MS = 30000;
+
+class HttpError extends Error {
+  constructor(message, code, status, body) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+async function request(url, opts = {}) {
+  const { method = 'GET', headers = {}, body, token, timeout = TIMEOUT_MS } = opts;
+
+  const h = { ...headers };
+  if (token) h['Authorization'] = `Bearer ${token}`;
+  if (body && !h['Content-Type']) h['Content-Type'] = 'application/json';
+
+  let lastErr;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: h,
+        body: typeof body === 'string' ? body : body instanceof Buffer ? body : body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timer);
+
+      if (res.status === 401) {
+        throw new HttpError('Authentication failed', 'E_AUTH_FAILED', 401);
+      }
+
+      const text = await res.text();
+      let json;
+      try { json = JSON.parse(text); } catch (_) { json = null; }
+
+      if (!res.ok) {
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+          lastErr = new HttpError(`Server error ${res.status}`, 'E_NETWORK', res.status, text);
+          await sleep(1000 * (attempt + 1));
+          continue;
+        }
+        throw new HttpError(json?.msg || `HTTP ${res.status}`, 'E_REQUEST_FAILED', res.status, json || text);
+      }
+
+      return json || text;
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof HttpError) throw err;
+      if (err.name === 'AbortError') {
+        if (attempt < MAX_RETRIES) {
+          lastErr = new HttpError('Request timeout', 'E_NETWORK', 0);
+          await sleep(1000 * (attempt + 1));
+          continue;
+        }
+        throw new HttpError('Request timeout', 'E_NETWORK', 0);
+      }
+      if (attempt < MAX_RETRIES) {
+        lastErr = err;
+        await sleep(1000 * (attempt + 1));
+        continue;
+      }
+      throw new HttpError(err.message || 'Network error', 'E_NETWORK', 0);
+    }
+  }
+  throw lastErr;
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+module.exports = { request, HttpError };

package/src/lib/mime.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const MIME_MAP = {
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon', '.bmp': 'image/bmp', '.tiff': 'image/tiff',
+  '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime',
+  '.avi': 'video/x-msvideo', '.mkv': 'video/x-matroska',
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+  '.flac': 'audio/flac', '.aac': 'audio/aac',
+  '.pdf': 'application/pdf', '.zip': 'application/zip',
+  '.gz': 'application/gzip', '.tar': 'application/x-tar',
+  '.json': 'application/json', '.xml': 'application/xml',
+  '.csv': 'text/csv', '.txt': 'text/plain',
+  '.html': 'text/html', '.htm': 'text/html',
+  '.css': 'text/css', '.js': 'application/javascript',
+  '.wasm': 'application/wasm', '.ttf': 'font/ttf',
+  '.woff': 'font/woff', '.woff2': 'font/woff2',
+  '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel', '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+
+function getMimeType(filePath) {
+  const ext = require('path').extname(filePath).toLowerCase();
+  return MIME_MAP[ext] || 'application/octet-stream';
+}
+
+module.exports = { MIME_MAP, getMimeType };