@mindstudio-ai/local-model-tunnel 0.5.7 → 0.5.9

package/README.md

@@ -1,6 +1,6 @@
 # MindStudio Local Tunnel
 
-Local tunnel for MindStudio. Use your own locally-running AI models, and edit custom interfaces and scripts for your MindStudio apps — all from your own machine.
+Local tunnel for MindStudio. Use your own locally-running AI models, develop v2 apps with live preview, and edit custom interfaces and scripts — all from your own machine.
 
 ## Quick Start
 
@@ -41,6 +41,159 @@ The app will walk you through connecting your MindStudio account and getting set
 
 ## Features
 
+### Apps v2 Local Dev Mode
+
+Develop MindStudio Apps v2 locally with instant feedback. The CLI detects your `mindstudio.json`, starts a dev session, and gives you live preview with real auth, databases, and method execution — all running on your machine.
+
+```bash
+cd my-app          # must contain mindstudio.json with "appId"
+mindstudio-local
+```
+
+**What happens:**
+
+1. The CLI reads `mindstudio.json` and enters dev mode automatically
+2. Installs dependencies if needed (`npm install` in method/frontend dirs)
+3. Starts your frontend dev server (Vite, webpack, etc.)
+4. Connects to the MindStudio platform and syncs your table schemas
+5. Starts a local proxy that serves your frontend with platform context injected
+6. Polls for method execution requests and runs them locally (transpiled on the fly)
+
+**The TUI shows:**
+
+- Session status, branch, and preview URL
+- Tabbed views: Info, Requests, Methods, Dev Server logs
+- Schema sync results
+- Live method execution log with timing and errors
+
+**Key details:**
+
+- Methods are transpiled with esbuild and executed in isolated Node.js child processes
+- `@mindstudio-ai/agent` SDK works identically — database queries, auth checks, etc. all go through the real platform
+- The local proxy injects `window.__MINDSTUDIO__` into HTML so the frontend SDK works
+- Changes to `mindstudio.json` trigger an automatic session restart
+- Frontend HMR works through the proxy (WebSocket upgrades are forwarded)
+
+### Headless Mode
+
+Run the dev tunnel without a TUI for programmatic control. Designed for hosted sandboxes, CI pipelines, or any automation that needs the tunnel as a background service.
+
+```bash
+mindstudio-local --headless --port 5173 --bind 0.0.0.0
+```
+
+**Headless mode does NOT start a dev server** — the caller manages that separately. The `--port` flag tells the tunnel which port to proxy to.
+
+#### CLI Flags
+
+```
+mindstudio-local --headless [options]
+
+Options:
+  --headless            Run without TUI, output JSON events to stdout
+  --port <n>            Dev server port to proxy to (default: from web.json)
+  --proxy-port <n>      Preferred proxy port (default: auto from app ID)
+  --bind <addr>         Proxy bind address (default: 127.0.0.1)
+  --log-level <level>   Log verbosity: error, warn, info, debug (default: info)
+```
+
+#### JSON Event Protocol
+
+Stdout emits newline-delimited JSON events — one object per line:
+
+| Event | Key Fields | When |
+|-------|-----------|------|
+| `starting` | `appId`, `name` | Initializing |
+| `session-started` | `sessionId`, `branch`, `proxyPort`, `proxyUrl` | Session active, proxy running |
+| `schema-synced` | `created`, `altered`, `errors` | Table schema synced |
+| `method-start` | `id`, `method` | Method execution received |
+| `method-complete` | `id`, `success`, `duration`, `error?` | Method execution finished |
+| `connection-warning` | `message` | Lost platform connection |
+| `connection-restored` | | Reconnected |
+| `session-expired` | | Platform expired session (exits with code 1) |
+| `error` | `message` | Fatal error |
+| `stopping` | | Graceful shutdown initiated |
+| `stopped` | | Cleanup complete, exiting |
+
+#### Spawning from a Parent Process
+
+```javascript
+const { spawn } = require('child_process');
+
+const tunnel = spawn('mindstudio-local', [
+  '--headless', '--port', '5173', '--bind', '0.0.0.0'
+], {
+  cwd: '/path/to/app',
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+// JSON events from stdout
+let buffer = '';
+tunnel.stdout.on('data', (chunk) => {
+  buffer += chunk.toString();
+  let idx;
+  while ((idx = buffer.indexOf('\n')) !== -1) {
+    const event = JSON.parse(buffer.slice(0, idx));
+    buffer = buffer.slice(idx + 1);
+
+    if (event.event === 'session-started') {
+      console.log('Preview:', event.proxyUrl);
+    }
+  }
+});
+
+// Structured logs from stderr
+tunnel.stderr.on('data', (chunk) => {
+  console.error('[tunnel]', chunk.toString().trimEnd());
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => tunnel.kill('SIGTERM'));
+```
+
+#### Programmatic API
+
+```typescript
+import { startHeadless } from '@mindstudio-ai/local-model-tunnel';
+
+await startHeadless({
+  cwd: '/path/to/app',
+  devPort: 5173,
+  bindAddress: '0.0.0.0',
+  logLevel: 'debug',
+});
+```
+
+### Logging
+
+The tunnel has structured logging throughout — API call timing, method execution lifecycle, transpilation, proxy requests, connection state, and errors.
+
+**Headless mode:** logs go to **stderr** at `info` level by default. Stdout is reserved for the JSON event protocol. Override with `--log-level`:
+
+```bash
+mindstudio-local --headless --log-level debug  # verbose logs on stderr
+```
+
+**Interactive (TUI) mode:** logs go to `.mindstudio-dev.log` in the working directory at `error` level by default. This keeps logs out of the terminal UI.
+
+**Log format:**
+
+```
+[2026-03-14T12:34:56.789Z] INFO  api POST /dev/manage/start → 200 (142ms) {"sessionId":"848583c4","branch":"main"}
+[2026-03-14T12:34:57.012Z] INFO  runner Request received {"requestId":"req-1","method":"getDashboard"}
+[2026-03-14T12:34:57.024Z] INFO  transpiler Transpiled in 12ms {"methodPath":"dist/methods/src/getDashboard.ts"}
+[2026-03-14T12:34:57.089Z] INFO  runner Request complete {"requestId":"req-1","success":true,"duration":77}
+```
+
+**Log levels:**
+
+| Level | What you get |
+|-------|-------------|
+| `error` | Failures only — 403s, timeouts, crashes |
+| `warn` | Errors + connection issues, port conflicts, invalid output |
+| `info` | Warnings + API timing, request lifecycle, session state changes |
+| `debug` | Everything — child process details, config resolution, proxy requests, transpile paths |
+
 ### Local Model Tunnel
 
 Connect local AI providers to MindStudio Cloud so you can use your own hardware for text, image, and video generation.
@@ -75,22 +228,41 @@ Edit custom interfaces (SPAs) and scripts from your MindStudio apps locally. Ope
 4. The CLI clones the scaffold and starts a local dev server
 5. Edit with your preferred tools — the CLI provides ready-to-use commands for Claude Code and Codex
 
-## Example: Getting Started with Ollama
-
-The fastest way to get running with text generation:
+## Development
 
+```bash
+npm install
+npm run build           # Build with tsup
+npm run dev             # Build + run CLI
+npm run local-update    # Build + npm link for local testing
 ```
-# Install Ollama (macOS/Linux)
-curl -fsSL https://ollama.com/install.sh | sh
 
-# Download a model
-ollama pull llama3.2
+### Install from a branch
 
-# Start the tunnel
-mindstudio-local
+```bash
+npm i -g mindstudio-ai/mindstudio-local-model-tunnel#branch-name
 ```
 
-Select **Sync Models** in the dashboard to register your models with MindStudio, and you're ready to go.
+The `prepare` script runs `npm run build` automatically after clone.
+
+## Configuration
+
+Credentials are stored in `~/.mindstudio-local-tunnel/config.json`. The config supports two environments (`prod` and `local`) with separate API keys and base URLs.
+
+The TUI's onboarding flow handles initial setup. For headless/sandbox use, write the config file directly:
+
+```json
+{
+  "environment": "prod",
+  "environments": {
+    "prod": {
+      "apiKey": "sk_...",
+      "userId": "...",
+      "apiBaseUrl": "https://api.mindstudio.ai"
+    }
+  }
+}
+```
 
 ## Want a New Provider?