magic-builder 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,139 @@
+# magic-builder
+
+CLI for Magic Builder (妙笔): publish HTML pages, deploy FaaS functions, upload assets, generate links, and install the Magic Builder Codex skill.
+
+## Install
+
+```bash
+npm install -g magic-builder
+```
+
+With Bun:
+
+```bash
+bun add -g magic-builder
+```
+
+The package provides three equivalent command names:
+
+```bash
+magic-builder --help
+magic-cli --help
+miaobi --help
+```
+
+You can also run it without installing:
+
+```bash
+npx magic-builder help
+bunx magic-builder help
+```
+
+## Authentication
+
+Most write operations need a Magic developer token.
+
+```bash
+magic-builder auth login
+```
+
+Manual token setup:
+
+```bash
+magic-builder auth set <token>
+magic-builder auth show
+```
+
+Token lookup order:
+
+1. `--token`
+2. `MAGIC_TOKEN`
+3. `~/.magic-token`
+4. project `.magic-token`
+
+## Common Commands
+
+Publish an HTML page:
+
+```bash
+magic-builder page publish app.html --title "Dashboard"
+```
+
+List or export pages:
+
+```bash
+magic-builder page list --scope mine
+magic-builder page list --scope public --title demo
+magic-builder page export --id <id> --out app.html
+```
+
+Deploy a FaaS function:
+
+```bash
+magic-builder faas publish handler.js --name report-api
+```
+
+Upload an asset:
+
+```bash
+magic-builder asset upload logo.png
+```
+
+Generate a Magic link:
+
+```bash
+magic-builder link create --title "Weekly Report"
+magic-builder link create --fid <faas-id>
+```
+
+Create or append a Feishu document HTML Box:
+
+```bash
+magic-builder doc create --html app.html --title "Demo"
+magic-builder doc append --html app.html --doc-token <docx-token>
+```
+
+Install or update the Magic Builder Codex skill:
+
+```bash
+magic-builder skill install
+magic-builder skill check-update
+magic-builder skill update
+```
+
+Check local environment:
+
+```bash
+magic-builder doctor
+magic-builder config get
+```
+
+## Help
+
+All of these forms are supported:
+
+```bash
+magic-builder help
+magic-builder help page
+magic-builder page help
+magic-builder page publish help
+magic-builder man
+```
+
+`--help`, `-h`, and `--man` are also supported.
+
+## Global Options
+
+```text
+--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
+```
+
+Default Magic service:
+
+```text
+https://magic.solutionsuite.cn
+```

package/bin/magic-builder.js

@@ -82,6 +82,16 @@ async function main() {
     process.exit(0);
   }
 
+  if (argv[0] === 'help') {
+    process.stdout.write(renderHelp('help', argv[1]) + '\n');
+    process.exit(0);
+  }
+
+  if (argv[0] === 'man') {
+    process.stdout.write(renderHelp('man') + '\n');
+    process.exit(0);
+  }
+
   const { command, args, opts } = parseGlobalArgs(argv);
 
   if (!command) {
@@ -89,6 +99,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (args[0] === 'help' || args[1] === 'help') {
+    process.stdout.write(renderHelp('help', command) + '\n');
+    process.exit(0);
+  }
+
   try {
     await COMMANDS[command].run(args, opts);
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-builder",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for Magic Builder — publish pages, functions, and files",
   "bin": {
     "magic-builder": "./bin/magic-builder.js",

package/src/lib/help.js

@@ -8,6 +8,10 @@ BRIEF: CLI for Magic Builder (妙笔).
 
 SYNTAX:
   magic-builder <command> <subcommand> [options]
+  magic-builder <command> help
+  magic-builder <command> <subcommand> help
+  magic-builder help [command]
+  magic-builder man
 
 COMMANDS:
   auth       Login and manage Magic developer tokens
@@ -23,6 +27,9 @@ COMMANDS:
 
 EXAMPLES:
   magic-builder auth login
+  magic-builder help page
+  magic-builder page help
+  magic-builder page publish help
   magic-builder page publish app.html --title "Dashboard"
   magic-builder page list --scope mine
   magic-builder page export --id recxxx --out app.html
@@ -53,6 +60,10 @@ GLOBAL OPTIONS:
   --version, -v                        Show version
   --help, -h                           Show help
   --man                                Show full manual
+  help [command]                       Show general or command help
+  <command> help                       Show command help
+  <command> <subcommand> help          Show command help
+  man                                  Show full manual
 
 COMMANDS:
   auth login [--no-open] [--timeout <seconds>] [--interval <seconds>]