anki-mcp-http 0.7.0 → 0.8.0

package/README.md

@@ -78,9 +78,9 @@ Want to use Anki with MCP clients like **Cursor IDE**, **Cline**, or **Zed Edito
 - [Zed Editor](https://zed.dev/) - Fast, modern code editor
 - Other MCP clients that support STDIO transport
 
-**Basic Configuration:**
+**Configuration - Choose one method:**
 
-Add this to your MCP client's configuration file:
+**Method 1: Using npx (recommended - no installation needed)**
 
 ```json
 {
@@ -96,6 +96,28 @@ Add this to your MCP client's configuration file:
 }
 ```
 
+**Method 2: Using global installation**
+
+First, install globally:
+```bash
+npm install -g anki-mcp-http
+```
+
+Then configure:
+```json
+{
+  "mcpServers": {
+    "anki-mcp": {
+      "command": "anki-mcp-http",
+      "args": ["--stdio"],
+      "env": {
+        "ANKI_CONNECT_URL": "http://localhost:8765"
+      }
+    }
+  }
+}
+```
+
 **Configuration file locations:**
 - **Cursor IDE**: `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)
 - **Cline**: Accessible via settings UI in VS Code
@@ -109,21 +131,48 @@ Want to use Anki with ChatGPT or Claude.ai in your browser? This mode lets you c
 
 **How it works (simple explanation):**
 1. You run a small server on your computer (where Anki is installed)
-2. You use [ngrok](https://ngrok.com) to create a public URL that forwards to your local server
-3. You share that URL with ChatGPT or Claude.ai
+2. Use the built-in `--ngrok` flag to automatically create a public tunnel URL
+3. Share that URL with ChatGPT or Claude.ai
 4. Now the AI can talk to your Anki through the internet!
 
-**Setup:**
+**New in v0.8.0:** Integrated ngrok support with the `--ngrok` flag - no need to run ngrok separately!
+
+**Setup - Choose one method:**
+
+**Method 1: Using npx (recommended - no installation needed)**
 
 ```bash
-# Quick start (using npx - no installation needed)
+# Quick start
 npx anki-mcp-http
 
+# With ngrok tunnel (recommended for web-based AI)
+npx anki-mcp-http --ngrok
+
 # With custom options
 npx anki-mcp-http --port 8080 --host 0.0.0.0
 npx anki-mcp-http --anki-connect http://localhost:8765
+```
 
-# Or install from source
+**Method 2: Using global installation**
+
+```bash
+# Install once
+npm install -g anki-mcp-http
+
+# Run the server
+anki-mcp-http
+
+# With ngrok tunnel (recommended for web-based AI)
+anki-mcp-http --ngrok
+
+# With custom options
+anki-mcp-http --port 8080 --host 0.0.0.0
+anki-mcp-http --anki-connect http://localhost:8765
+```
+
+**Method 3: Install from source (for development)**
+
+```bash
 npm install
 npm run build
 npm run start:prod:http
@@ -132,37 +181,66 @@ npm run start:prod:http
 **CLI Options:**
 
 ```bash
-ankimcp [options]
+anki-mcp-http [options]
 
 Options:
   --stdio                        Run in STDIO mode (for MCP clients)
   -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
   -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
   -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
+  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
   --help                         Show help message
 
-Examples - HTTP Mode:
-  ankimcp                        # Use all defaults (HTTP mode)
-  ankimcp --port 8080            # Custom port
-  ankimcp --host 0.0.0.0         # Listen on all network interfaces
-
-Examples - STDIO Mode:
-  ankimcp --stdio                # For use with npx in MCP clients
+Usage with npx (no installation needed):
+  npx anki-mcp-http                        # HTTP mode
+  npx anki-mcp-http --port 8080            # Custom port
+  npx anki-mcp-http --stdio                # STDIO mode
+  npx anki-mcp-http --ngrok                # HTTP mode with ngrok tunnel
+
+Usage with global installation:
+  npm install -g anki-mcp-http             # Install once
+  anki-mcp-http                            # HTTP mode
+  anki-mcp-http --port 8080                # Custom port
+  anki-mcp-http --stdio                    # STDIO mode
+  anki-mcp-http --ngrok                    # HTTP mode with ngrok tunnel
 ```
 
 **Using with ngrok:**
 
+**Method 1: Integrated (Recommended - One Command)**
+
 ```bash
-# 1. Start ankimcp
-npx anki-mcp-http
+# One-time setup (if you haven't already):
+npm install -g ngrok
+ngrok config add-authtoken <your-token>  # Get token from https://dashboard.ngrok.com
+
+# Start server with ngrok tunnel in one command:
+anki-mcp-http --ngrok
+
+# The tunnel URL will be displayed in the startup banner
+# Example output:
+# 🌐 Ngrok tunnel: https://abc123.ngrok-free.app
+```
+
+**Method 2: Manual (Two Terminals)**
 
-# 2. In another terminal, create a tunnel
+```bash
+# Terminal 1: Start the server
+anki-mcp-http
+
+# Terminal 2: Create tunnel
 ngrok http 3000
 
-# 3. Copy the ngrok URL (looks like: https://abc123.ngrok.io)
-# 4. Share this URL with your AI assistant
+# Copy the ngrok URL (looks like: https://abc123.ngrok-free.app)
+# Share this URL with your AI assistant
 ```
 
+**Benefits of `--ngrok` flag:**
+- ✅ One command instead of two terminals
+- ✅ Automatic cleanup when you press Ctrl+C
+- ✅ URL displayed directly in the startup banner
+- ✅ Works with custom ports: `anki-mcp-http --port 8080 --ngrok`
+
 **Security note:** Anyone with your ngrok URL can access your Anki, so keep that URL private!
 
 ### Option 4: Manual Installation from Source (Local Mode)
@@ -601,7 +679,7 @@ This project follows [Semantic Versioning](https://semver.org/) with a pre-1.0 d
   - Will be released when the API is stable and tested
   - Breaking changes will require major version bumps (2.0.0, etc.)
 
-**Current Status**: `0.6.0` - Active beta development. New features include the `twenty_rules` prompt for evidence-based flashcard creation, media file management, and improved prompt system. APIs may change based on feedback and testing.
+**Current Status**: `0.8.0` - Active beta development. New features include integrated ngrok tunneling (`--ngrok` flag), the `twenty_rules` prompt for evidence-based flashcard creation, media file management, and improved prompt system. APIs may change based on feedback and testing.
 
 ## Similar Projects
 

package/dist/cli.d.ts

@@ -2,7 +2,8 @@ export interface CliOptions {
     port: number;
     host: string;
     ankiConnect: string;
+    ngrok: boolean;
 }
 export declare function checkForUpdates(): void;
 export declare function parseCliArgs(): CliOptions;
-export declare function displayStartupBanner(options: CliOptions): void;
+export declare function displayStartupBanner(options: CliOptions, ngrokUrl?: string): void;

package/dist/cli.js

@@ -34,19 +34,25 @@ function parseCliArgs() {
         .option('-p, --port <number>', 'Port to listen on (HTTP mode)', '3000')
         .option('-h, --host <address>', 'Host to bind to (HTTP mode)', '127.0.0.1')
         .option('-a, --anki-connect <url>', 'AnkiConnect URL', 'http://localhost:8765')
+        .option('--ngrok', 'Start ngrok tunnel (requires global ngrok installation)')
         .addHelpText('after', `
 Transport Modes:
   HTTP Mode (default):  For web-based AI assistants (ChatGPT, Claude.ai)
   STDIO Mode:           For desktop MCP clients (Cursor, Cline, Zed)
 
 Examples - HTTP Mode:
-  $ ankimcp                                    # Use defaults
-  $ ankimcp --port 8080                        # Custom port
-  $ ankimcp --host 0.0.0.0 --port 3000         # Listen on all interfaces
-  $ ankimcp --anki-connect http://localhost:8765
+  $ anki-mcp-http                                    # Use defaults
+  $ anki-mcp-http --port 8080                        # Custom port
+  $ anki-mcp-http --host 0.0.0.0 --port 3000         # Listen on all interfaces
+  $ anki-mcp-http --anki-connect http://localhost:8765
+
+Examples - HTTP Mode with Ngrok:
+  $ anki-mcp-http --ngrok                            # Start with ngrok tunnel
+  $ anki-mcp-http --port 8080 --ngrok                # Custom port + ngrok
+  $ anki-mcp-http --host 0.0.0.0 --ngrok             # Public host + ngrok
 
 Examples - STDIO Mode:
-  $ ankimcp --stdio                            # For use with npx in MCP clients
+  $ anki-mcp-http --stdio                            # For use with npx in MCP clients
 
   # MCP client configuration (Cursor, Cline, Zed, etc.):
   {
@@ -58,10 +64,11 @@ Examples - STDIO Mode:
     }
   }
 
-Usage with ngrok (HTTP mode only):
-  1. Start ankimcp in one terminal
-  2. In another terminal: ngrok http 3000
-  3. Share the ngrok URL with your AI assistant
+Ngrok Setup (one-time):
+  1. Install: npm install -g ngrok
+  2. Get auth token from: https://dashboard.ngrok.com/get-started/your-authtoken
+  3. Setup: ngrok config add-authtoken <your-token>
+  4. Run: anki-mcp-http --ngrok
 `);
     program.parse();
     const options = program.opts();
@@ -69,9 +76,10 @@ Usage with ngrok (HTTP mode only):
         port: parseInt(options.port.toString(), 10),
         host: options.host,
         ankiConnect: options.ankiConnect,
+        ngrok: options.ngrok || false,
     };
 }
-function displayStartupBanner(options) {
+function displayStartupBanner(options, ngrokUrl) {
     const version = getVersion();
     const title = `AnkiMCP HTTP Server v${version}`;
     const padding = Math.floor((64 - title.length) / 2);
@@ -82,19 +90,25 @@ function displayStartupBanner(options) {
 ╚════════════════════════════════════════════════════════════════╝
 
 🚀 Server running on: http://${options.host}:${options.port}
-🔌 AnkiConnect URL:   ${options.ankiConnect}
+🔌 AnkiConnect URL:   ${options.ankiConnect}${ngrokUrl ? `\n🌐 Ngrok tunnel:      ${ngrokUrl}` : ''}
 
 Configuration:
   • Port:               ${options.port} (override: --port 8080)
   • Host:               ${options.host} (override: --host 0.0.0.0)
   • AnkiConnect:        ${options.ankiConnect}
-                        (override: --anki-connect http://localhost:8765)
-
+                        (override: --anki-connect http://localhost:8765)${ngrokUrl ? `\n  • Ngrok tunnel:       ${ngrokUrl}\n  • Ngrok dashboard:    http://localhost:4040` : ''}
+${!ngrokUrl
+        ? `
 Usage with ngrok:
-  1. In another terminal: ngrok http ${options.port}
-  2. Share the ngrok URL with your AI assistant
-
-Run 'ankimcp --help' for more options.
+  1. Install: npm install -g ngrok
+  2. Setup: ngrok config add-authtoken <your-token>
+  3. Run: anki-mcp-http --ngrok
+`
+        : `
+Share this URL with your AI assistant:
+  ${ngrokUrl}
+`}
+Run 'anki-mcp-http --help' for more options.
 `);
 }
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;AAyBA,0CAEC;AAED,oCA4DC;AAED,oDA0BC;AArHD,yCAAoC;AACpC,2BAAkC;AAClC,+BAA4B;AAC5B,sEAA6C;AAQ7C,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CACf,IAAA,iBAAY,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,cAAc,EAAE,CAAC,OAAO,CAAC;AAClC,CAAC;AAED,SAAgB,eAAe;IAC7B,IAAA,yBAAc,EAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,UAAU,EAAE,CAAC;SACrB,MAAM,CACL,SAAS,EACT,6DAA6D,CAC9D;SACA,MAAM,CAAC,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,CAAC;SACtE,MAAM,CAAC,sBAAsB,EAAE,6BAA6B,EAAE,WAAW,CAAC;SAC1E,MAAM,CACL,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,CACxB;SACA,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BL,CACI,CAAC;IAEJ,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC3C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAAC,OAAmB;IACtD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,wBAAwB,OAAO,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAE1F,OAAO,CAAC,GAAG,CAAC;;GAEX,WAAW;;;+BAGiB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI;wBACnC,OAAO,CAAC,WAAW;;;0BAGjB,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,WAAW;;;;uCAIN,OAAO,CAAC,IAAI;;;;CAIlD,CAAC,CAAC;AACH,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;AA0BA,0CAEC;AAED,oCAuEC;AAED,oDAqCC;AA5ID,yCAAoC;AACpC,2BAAkC;AAClC,+BAA4B;AAC5B,sEAA6C;AAS7C,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CACf,IAAA,iBAAY,EAAC,IAAA,WAAI,EAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACrD,CAAC;AACH,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,cAAc,EAAE,CAAC,OAAO,CAAC;AAClC,CAAC;AAED,SAAgB,eAAe;IAC7B,IAAA,yBAAc,EAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACrD,CAAC;AAED,SAAgB,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,SAAS,CAAC;SACf,WAAW,CAAC,yDAAyD,CAAC;SACtE,OAAO,CAAC,UAAU,EAAE,CAAC;SACrB,MAAM,CACL,SAAS,EACT,6DAA6D,CAC9D;SACA,MAAM,CAAC,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,CAAC;SACtE,MAAM,CAAC,sBAAsB,EAAE,6BAA6B,EAAE,WAAW,CAAC;SAC1E,MAAM,CACL,0BAA0B,EAC1B,iBAAiB,EACjB,uBAAuB,CACxB;SACA,MAAM,CACL,SAAS,EACT,yDAAyD,CAC1D;SACA,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCL,CACI,CAAC;IAEJ,OAAO,CAAC,KAAK,EAAE,CAAC;IAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAc,CAAC;IAE3C,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC3C,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;KAC9B,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAClC,OAAmB,EACnB,QAAiB;IAEjB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,wBAAwB,OAAO,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAE1F,OAAO,CAAC,GAAG,CAAC;;GAEX,WAAW;;;+BAGiB,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI;wBACnC,OAAO,CAAC,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE;;;0BAGzE,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,IAAI;0BACZ,OAAO,CAAC,WAAW;0EAC6B,QAAQ,CAAC,CAAC,CAAC,6BAA6B,QAAQ,iDAAiD,CAAC,CAAC,CAAC,EAAE;EAE5K,CAAC,QAAQ;QACP,CAAC,CAAC;;;;;CAKP;QACK,CAAC,CAAC;;IAEJ,QAAQ;CAEV;;CAED,CAAC,CAAC;AACH,CAAC"}

package/dist/main-http.js

@@ -5,6 +5,7 @@ const app_module_1 = require("./app.module");
 const bootstrap_1 = require("./bootstrap");
 const origin_validation_guard_1 = require("./http/guards/origin-validation.guard");
 const cli_1 = require("./cli");
+const ngrok_service_1 = require("./services/ngrok.service");
 async function bootstrap() {
     (0, cli_1.checkForUpdates)();
     const options = (0, cli_1.parseCliArgs)();
@@ -19,7 +20,20 @@ async function bootstrap() {
     });
     app.useGlobalGuards(new origin_validation_guard_1.OriginValidationGuard());
     await app.listen(options.port, options.host);
-    (0, cli_1.displayStartupBanner)(options);
+    let ngrokUrl;
+    if (options.ngrok) {
+        try {
+            const ngrokService = new ngrok_service_1.NgrokService();
+            const tunnelInfo = await ngrokService.start(options.port);
+            ngrokUrl = tunnelInfo.publicUrl;
+        }
+        catch (err) {
+            console.error('\n❌ Failed to start ngrok:');
+            console.error(err instanceof Error ? err.message : String(err));
+            console.error('\nServer is still running locally without tunnel.\n');
+        }
+    }
+    (0, cli_1.displayStartupBanner)(options, ngrokUrl);
 }
 bootstrap().catch((err) => {
     console.error('Failed to start MCP HTTP server:', err);

package/dist/main-http.js.map

@@ -1 +1 @@
-{"version":3,"file":"main-http.js","sourceRoot":"","sources":["../src/main-http.ts"],"names":[],"mappings":";;AAAA,uCAA2C;AAC3C,6CAAyC;AACzC,2CAAoE;AACpE,mFAA8E;AAC9E,+BAIe;AAEf,KAAK,UAAU,SAAS;IAEtB,IAAA,qBAAe,GAAE,CAAC;IAElB,MAAM,OAAO,GAAG,IAAA,kBAAY,GAAE,CAAC;IAG/B,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAChC,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IAGnD,MAAM,UAAU,GAAG,IAAA,4BAAgB,EAAC,CAAC,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,IAAA,+BAAmB,EAAC,UAAU,CAAC,CAAC;IAGtD,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,MAAM,CAAC,sBAAS,CAAC,OAAO,EAAE,EAAE;QACxD,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IAGH,GAAG,CAAC,eAAe,CAAC,IAAI,+CAAqB,EAAE,CAAC,CAAC;IAEjD,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAG7C,IAAA,0BAAoB,EAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"main-http.js","sourceRoot":"","sources":["../src/main-http.ts"],"names":[],"mappings":";;AAAA,uCAA2C;AAC3C,6CAAyC;AACzC,2CAAoE;AACpE,mFAA8E;AAC9E,+BAIe;AACf,4DAAwD;AAExD,KAAK,UAAU,SAAS;IAEtB,IAAA,qBAAe,GAAE,CAAC;IAElB,MAAM,OAAO,GAAG,IAAA,kBAAY,GAAE,CAAC;IAG/B,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAChC,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IAGnD,MAAM,UAAU,GAAG,IAAA,4BAAgB,EAAC,CAAC,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,IAAA,+BAAmB,EAAC,UAAU,CAAC,CAAC;IAGtD,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,MAAM,CAAC,sBAAS,CAAC,OAAO,EAAE,EAAE;QACxD,MAAM,EAAE,aAAa;QACrB,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IAGH,GAAG,CAAC,eAAe,CAAC,IAAI,+CAAqB,EAAE,CAAC,CAAC;IAEjD,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAG7C,IAAI,QAA4B,CAAC;IACjC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,4BAAY,EAAE,CAAC;YACxC,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1D,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC;QAClC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAChE,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAGD,IAAA,0BAAoB,EAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/services/ngrok.service.d.ts

@@ -0,0 +1,15 @@
+export interface NgrokTunnelInfo {
+    publicUrl: string;
+    apiUrl: string;
+}
+export declare class NgrokService {
+    private process;
+    private cleanupHandlersRegistered;
+    start(port: number): Promise<NgrokTunnelInfo>;
+    private isNgrokInstalled;
+    private waitForNgrok;
+    private getTunnelUrl;
+    private registerCleanupHandlers;
+    private cleanup;
+    getWebInterfaceUrl(): string;
+}

package/dist/services/ngrok.service.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NgrokService = void 0;
+const child_process_1 = require("child_process");
+const http_1 = __importDefault(require("http"));
+class NgrokService {
+    process = null;
+    cleanupHandlersRegistered = false;
+    async start(port) {
+        if (!(await this.isNgrokInstalled())) {
+            throw new Error('ngrok is not installed.\n' +
+                'Install it with: npm install -g ngrok\n' +
+                'Or download from: https://ngrok.com/download\n' +
+                'Then setup auth: ngrok config add-authtoken <your-token>');
+        }
+        this.process = (0, child_process_1.spawn)('ngrok', ['http', port.toString()], {
+            stdio: 'pipe',
+        });
+        if (!this.cleanupHandlersRegistered) {
+            this.registerCleanupHandlers();
+            this.cleanupHandlersRegistered = true;
+        }
+        this.process.on('error', (err) => {
+            throw new Error(`Failed to start ngrok: ${err.message}`);
+        });
+        this.process.on('exit', (code, signal) => {
+            if (code !== 0 && code !== null) {
+                console.error(`ngrok exited with code ${code}`);
+            }
+        });
+        await this.waitForNgrok();
+        const publicUrl = await this.getTunnelUrl();
+        return {
+            publicUrl,
+            apiUrl: 'http://localhost:4040',
+        };
+    }
+    async isNgrokInstalled() {
+        return new Promise((resolve) => {
+            const check = (0, child_process_1.spawn)('which', ['ngrok']);
+            check.on('close', (code) => resolve(code === 0));
+            check.on('error', () => resolve(false));
+        });
+    }
+    async waitForNgrok(maxAttempts = 20, delayMs = 500) {
+        for (let i = 0; i < maxAttempts; i++) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            try {
+                await this.getTunnelUrl();
+                return;
+            }
+            catch {
+            }
+        }
+        throw new Error('ngrok failed to start in time.\n' +
+            'Make sure you have configured your auth token:\n' +
+            'ngrok config add-authtoken <your-token>');
+    }
+    async getTunnelUrl() {
+        return new Promise((resolve, reject) => {
+            http_1.default
+                .get('http://localhost:4040/api/tunnels', (res) => {
+                let data = '';
+                res.on('data', (chunk) => (data += chunk));
+                res.on('end', () => {
+                    try {
+                        const response = JSON.parse(data);
+                        const tunnel = response.tunnels?.find((t) => t.proto === 'https');
+                        const publicUrl = tunnel?.public_url;
+                        if (publicUrl) {
+                            resolve(publicUrl);
+                        }
+                        else {
+                            reject(new Error('No HTTPS tunnel found in ngrok API response'));
+                        }
+                    }
+                    catch (err) {
+                        reject(new Error(`Failed to parse ngrok API response: ${err}`));
+                    }
+                });
+            })
+                .on('error', (err) => {
+                reject(new Error(`Failed to connect to ngrok API: ${err.message}`));
+            });
+        });
+    }
+    registerCleanupHandlers() {
+        process.on('SIGINT', () => {
+            console.log('\n\n🛑 Shutting down ngrok tunnel...');
+            this.cleanup();
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            this.cleanup();
+            process.exit(0);
+        });
+        process.on('exit', () => {
+            this.cleanup();
+        });
+        process.on('uncaughtException', (err) => {
+            console.error('Uncaught exception:', err);
+            this.cleanup();
+            process.exit(1);
+        });
+    }
+    cleanup() {
+        if (this.process && !this.process.killed) {
+            this.process.kill('SIGTERM');
+            this.process = null;
+        }
+    }
+    getWebInterfaceUrl() {
+        return 'http://localhost:4040';
+    }
+}
+exports.NgrokService = NgrokService;
+//# sourceMappingURL=ngrok.service.js.map

package/dist/services/ngrok.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngrok.service.js","sourceRoot":"","sources":["../../src/services/ngrok.service.ts"],"names":[],"mappings":"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"}