@zenovate/opman 0.1.9

package/README.md

@@ -0,0 +1,222 @@
+# @zenovate/opman
+
+CLI for OP devices: compile Python to PikaPython bytecode (`.py.o`), upload over **serial** or **BLE**, with command mode and Python REPL.
+
+- **Platforms**: macOS (arm64 / x64), Windows x64  
+- **npm**: [@zenovate/opman](https://www.npmjs.com/package/@zenovate/opman)
+
+## Install
+
+```bash
+npm install -g @zenovate/opman
+```
+
+Project-local:
+
+```bash
+npm install -D @zenovate/opman
+npx opman --help
+```
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Version | `opman --version` |
+| Compile `.py` | `opman compile hello.py` / `opman compile *.py -o build/` |
+| Upload file | `opman upload hello.py.o /py -p COM3 -b 9600` |
+| Compile + upload + run | `opman deploy hello.py -p COM3 -b 9600` |
+| Upload + run `.py.o` / `.o` | `opman deploy hello.py.o -p COM3 -b 9600` |
+| Command mode / params | `opman shell -p COM3 -b 9600` |
+| Python REPL | `opman python -p COM3 -b 9600` |
+| BLE scan | `opman ble-scan [--name OP] [--all-devices]` |
+| Raw monitor | `opman monitor -p COM3` |
+| Shell completion | `opman completion bash` / `zsh` / `fish` / `powershell` |
+
+> `opman python` enters Python REPL automatically — you do not need to switch device modes manually.
+
+## deploy — compile, upload, and run
+
+`deploy` accepts source or precompiled bytecode, uploads to the device (default directory `/py`), then runs `{"PythonFileRun":"<filename>"}`. Use `upload` if you only want to transfer without running.
+
+**Input types**
+
+| Input | Behavior |
+|-------|----------|
+| `.py` | Compile to `.py.o` locally, then upload and run |
+| `.py.o` | Skip compile; upload and run |
+| `.o` (any path ending in `.o`) | Same as `.py.o` — treated as bytecode |
+
+**Flow:** compile (if `.py`) → connect → upload → `PythonFileRun` → (optional) raw monitor until **ESC**.
+
+```bash
+# Serial: compile, upload, run (remote dir defaults to /py)
+opman deploy examples/hello.py -p COM3 -b 9600
+
+# Upload precompiled bytecode (skip compile)
+opman deploy examples/hello.py.o -p COM3 -b 9600
+opman deploy build/hello.o -p COM3 -b 9600
+
+# Custom local compile output, remote name, timeout
+opman deploy examples/hello.py -p COM3 -o build/hello.py.o \
+  --remote-name demo.py.o --run-timeout 60
+
+# Custom remote directory
+opman deploy examples/hello.py --remote-dir /py -p COM3 -b 9600
+
+# Upload tuning
+opman deploy examples/hello.py.o -p COM3 --packet-size 200 --skip-command-mode
+
+# BLE by address or name (partial match)
+opman deploy examples/hello.py --ble ZENO --monitor
+
+# Monitor with hex + timestamp (press ESC to stop)
+opman deploy examples/hello.py -p COM3 --monitor --hex --timestamp
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--remote-dir` | `/py` | Device directory to upload to |
+| `-o` / `--output` | same dir as input | Local `.py.o` path when compiling `.py` |
+| `--remote-name` | derived from input | Filename on device (used for `PythonFileRun`) |
+| `--monitor` | off | After run succeeds, print raw device output until **ESC** |
+| `--run-timeout` | `30` | Seconds to wait for `PythonFileRun` response |
+| `--hex` | off | Hex display during `--monitor` |
+| `--timestamp` | off | Timestamp prefix during `--monitor` |
+| `-p` / `--ble` | — | Serial port, or BLE address / name (one required) |
+| `-b` / `-c` | `115200` | Serial baud or full config, e.g. `9600,N,8,1` |
+| `--packet-size` | `100` | Upload chunk size (bytes) |
+| `--skip-command-mode` | off | Skip command mode before upload |
+
+## upload
+
+```bash
+opman upload hello.py.o /py -p COM3 -b 9600
+opman upload hello.py.o /py -p COM3 --remote-name custom.py.o
+opman upload hello.py.o /py -p COM3 --packet-size 200 --skip-command-mode
+```
+
+## monitor
+
+```bash
+opman monitor -p COM3
+opman monitor -p COM3 --hex --timestamp -o capture.log
+opman monitor -p COM3 --no-drain          # serial only: keep pre-connect buffer
+opman monitor --ble ZENO --hex -o ble.log
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--hex` | off | Hex display |
+| `--timestamp` | off | Timestamp prefix per chunk |
+| `--no-drain` | off | Do not drain serial buffer after connect (**serial only**) |
+| `-o` / `--output` | — | Also write to file |
+
+Press **ESC** (or Ctrl+C) to stop.
+
+## python
+
+```bash
+opman python -p COM3 -b 9600
+opman python -p COM3 --timeout 60
+opman python -p COM3 --skip-python-mode      # device already in REPL
+opman python -p COM3 --no-legacy-fallback    # do not fall back on old firmware path
+opman python --ble ZENO
+```
+
+Device: `exit()` to leave REPL. Local: `quit` disconnects only.
+
+## Examples
+
+**Compile**
+
+```bash
+opman compile examples/hello.py
+opman compile examples/*.py
+opman compile examples/*.py -o build/
+opman compile examples/hello.py -o /tmp/custom.py.o
+```
+
+**Serial (Windows)**
+
+```bash
+opman deploy examples/hello.py -p COM3 -b 9600
+opman deploy examples/hello.py.o -p COM3 -b 9600
+opman deploy examples/hello.py -p COM3 -b 9600 --monitor
+opman shell -p COM3 -b 9600
+opman shell -p COM3 --skip-command-mode
+opman python -p COM3 -b 9600
+opman monitor -p COM3
+```
+
+**Serial config string (`-c`, same as `9600,N,8,1`)**
+
+```bash
+opman shell -p COM5 -c "9600,N,8,1"
+```
+
+**BLE**
+
+```bash
+opman ble-scan
+opman ble-scan --name OP
+opman ble-scan --all-devices
+opman deploy examples/hello.py --ble AA:BB:CC:DD:EE:FF
+opman deploy examples/hello.py.o --ble ZENO
+opman deploy examples/hello.py --ble ZENO --monitor --hex
+opman python --ble ZENO
+opman monitor --ble ZENO --hex --timestamp
+```
+
+Full parameter reference (Chinese): [docs/操作说明.md](docs/操作说明.md)
+
+## Shell completion
+
+Provided by the Go binary (`npm` global install or `bin/opman`). Tab-complete subcommands, flags, and local file paths.
+
+```bash
+opman completion --help
+```
+
+**Current session**
+
+| Shell | Command |
+|-------|---------|
+| Bash | `source <(opman completion bash)` |
+| Zsh | `source <(opman completion zsh)` |
+| Fish | `opman completion fish \| source` |
+| PowerShell | `opman completion powershell \| Out-String \| Invoke-Expression` |
+
+**Persist across sessions**
+
+```bash
+# Bash (Linux)
+opman completion bash > /etc/bash_completion.d/opman
+
+# Bash (macOS, Homebrew)
+opman completion bash > $(brew --prefix)/etc/bash_completion.d/opman
+
+# Zsh (macOS, Homebrew)
+opman completion zsh > $(brew --prefix)/share/zsh/site-functions/_opman
+
+# Fish
+opman completion fish > ~/.config/fish/completions/opman.fish
+```
+
+PowerShell: add the “current session” command to your profile (`$PROFILE`).
+
+```bash
+# Smaller completion script (no flag descriptions)
+opman completion bash --no-descriptions > /tmp/opman-completion.bash
+source /tmp/opman-completion.bash
+```
+
+Serial ports and BLE devices are **not** auto-suggested; connection flags `-p` / `--ble` are prioritized until one is set.
+
+## Help
+
+```bash
+opman --help
+opman <command> --help
+opman deploy --help
+```

package/npm/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function platformKey() {
+  const { platform, arch } = process;
+
+  if (platform === 'darwin') {
+    if (arch === 'arm64' || arch === 'x64') {
+      return `darwin-${arch}`;
+    }
+  }
+
+  if (platform === 'win32') {
+    if (arch === 'x64') {
+      return 'win32-x64';
+    }
+  }
+
+  console.error(
+    `[@zenovate/opman] Unsupported platform: ${platform}-${arch}. ` +
+      'Only macOS (arm64/x64) and Windows x64 are supported.',
+  );
+  process.exit(1);
+}
+
+const key = platformKey();
+const binName = process.platform === 'win32' ? 'opman.exe' : 'opman';
+const binPath = path.join(__dirname, 'vendor', key, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(`[@zenovate/opman] Binary not found: ${binPath}`);
+  console.error(
+    'Reinstall the package, or run scripts/build_npm.sh before publishing.',
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(binPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+
+if (result.error) {
+  console.error(`[@zenovate/opman] Failed to start: ${result.error.message}`);
+  process.exit(1);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@zenovate/opman",
+  "version": "0.1.9",
+  "description": "CLI for OP devices: compile Python to PikaPython bytecode, serial/BLE upload, OP>1 shell and OP>2 REPL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zenovate-team/opman.git"
+  },
+  "bin": {
+    "opman": "npm/cli.js"
+  },
+  "files": [
+    "npm/cli.js",
+    "npm/vendor"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ]
+}