@zintrust/expose 0.4.58

package/README.md

@@ -0,0 +1,79 @@
+# @zintrust/expose
+
+The `@zintrust/expose` package provides an official ZinTrust CLI extension to instantly expose your local development environment to the internet via secure tunnels.
+
+It allows you to share your work with clients, test webhooks, or test on mobile devices without deploying your application.
+
+## Prerequisites
+
+This package requires a ZinTrust project using `@zintrust/core` `^0.4.0` or higher to run. By default, standard templates include and load this package automatically.
+
+## Usage
+
+Use the global `zin` command (or `npx tsx bin/zin.ts`) in your application root to invoke the `expose` CLI command (also aliased as `exp`).
+
+### Basic Command
+
+```bash
+zin expose [port] [options]
+```
+
+### Options
+
+- `[port]`: The local port you want to expose. If omitted, ZinTrust will attempt to read `process.env.PORT` from your `.env` file, defaulting to `3000` otherwise.
+- `--provider <provider>`: The backend tunneling service to use. Supports `cloudflare` or `zintrust`. (Default: `cloudflare`)
+- `--https`: Enable if the local target you are exposing expects HTTPS traffic (e.g., exposing a local self-signed dev server).
+
+---
+
+## Tunnel Providers
+
+The package ships with two native tunneling providers:
+
+### 1. Cloudflare Tunnels (Default)
+
+The `cloudflare` provider utilizes Cloudflare's `cloudflared` utility behind the scenes to spawn rapid, ephemeral tunnels. It's incredibly fast and requires no authentication, granting you a randomized `.trycloudflare.com` URL instantly.
+
+**Examples:**
+
+Expose the default port (automatically read from `.env`):
+
+```bash
+zin exp
+```
+
+Explicitly expose port `8080` via Cloudflare:
+
+```bash
+zin exp 8080 --provider cloudflare
+```
+
+Expose a local HTTPS container running on port `443`:
+
+```bash
+zin exp 443 --https
+```
+
+### 2. ZinTrust Tunnels
+
+The `zintrust` provider connects to the ZinTrust internal tunneling network. This is useful for authenticated developer environments, persistent subdomains, and connecting services inside the ZinTrust ecosystem.
+
+**Examples:**
+
+Expose port `3000` using the native ZinTrust tunnel:
+
+```bash
+zin expose 3000 --provider zintrust
+```
+
+Expose your local environment via ZinTrust securely over HTTPS:
+
+```bash
+zin exp --https --provider zintrust
+```
+
+## How It Works Under The Hood
+
+ZinTrust registers `@zintrust/expose` as an _Optional CLI Extension_. When the framework bootstraps `bin/zin.ts`, the package exposes its provider definitions `ITunnelProvider` through `TunnelManager`.
+
+When a tunnel is requested, a child process hooks into the requested provider (like `cloudflared`), safely negotiating the handshake and parsing the generated secure URL back to the developer console. When the CLI is exited (via `Ctrl+C`), the package safely and automatically cleans up the tunnel child processes.

package/dist/ExposeCommand.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+export declare const ExposeCommand: Readonly<{
+    getCommand: () => Command;
+    name: "expose";
+}>;

package/dist/ExposeCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExposeCommand.d.ts","sourceRoot":"","sources":["../src/ExposeCommand.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmDpC,eAAO,MAAM,aAAa;sBA3CM,OAAO;;EA8CrC,CAAC"}

package/dist/ExposeCommand.js

@@ -0,0 +1,48 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import * as dotenv from 'dotenv';
+import { resolve } from 'node:path';
+import { createTunnelProvider } from './TunnelManager.js';
+// Since this CLI runs early, we parse .env for the default PORT if unspecified
+dotenv.config({ path: resolve(process.cwd(), '.env') });
+const createExposeCommand = () => {
+    const command = new Command('expose')
+        .alias('exp')
+        .description('Expose your local ZinTrust server to the internet using secure tunnels.')
+        .argument('[port]', 'The local port to expose', process.env['PORT'] || '3000')
+        .option('--https', 'Connect locally via HTTPS instead of HTTP', false)
+        .option('--provider <provider>', 'Tunnel provider (zintrust | cloudflare)', 'cloudflare')
+        .action(async (portArg, options) => {
+        const port = Number.parseInt(portArg, 10);
+        if (Number.isNaN(port)) {
+            console.error(`Invalid port provided: ${portArg}`);
+            process.exit(1);
+        }
+        console.log(`Starting URL exposure on port ${port} using ${options.provider} provider...`);
+        const provider = createTunnelProvider(options.provider);
+        try {
+            const publicUrl = await provider.start({ port, https: options.https });
+            console.log(`\n=============================================================`);
+            console.log(`🚀 Tunnel Established successfully!`);
+            console.log(`🌍 Public URL     : \x1b[32m${publicUrl}\x1b[0m`);
+            console.log(`🔌 Local Target   : ${options.https ? 'https' : 'http'}://localhost:${port}`);
+            console.log(`🛡️  Provider      : ${options.provider}`);
+            console.log(`=============================================================\n`);
+            console.log(`Press Ctrl+C to disconnect from the tunnel.\n`);
+            process.on('SIGINT', async () => {
+                console.log(`\nDisconnecting ${options.provider} tunnel...`);
+                await provider.stop();
+                process.exit(0);
+            });
+        }
+        catch (error) {
+            console.error(`Tunnel failed to start:`, error.message);
+            process.exit(1);
+        }
+    });
+    return command;
+};
+export const ExposeCommand = Object.freeze({
+    getCommand: createExposeCommand,
+    name: 'expose',
+});

package/dist/TunnelManager.d.ts

@@ -0,0 +1,2 @@
+import type { ITunnelProvider } from './providers/ITunnelProvider.js';
+export declare function createTunnelProvider(providerName: string): ITunnelProvider;

package/dist/TunnelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TunnelManager.d.ts","sourceRoot":"","sources":["../src/TunnelManager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGtE,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAU1E"}

package/dist/TunnelManager.js

@@ -0,0 +1,13 @@
+import { CloudflareProvider } from './providers/CloudflareProvider.js';
+import { ZintrustProvider } from './providers/ZintrustProvider.js';
+export function createTunnelProvider(providerName) {
+    switch (providerName.toLowerCase()) {
+        case 'cloudflare':
+        case 'cf':
+            return CloudflareProvider.create();
+        case 'zintrust':
+        case 'zin':
+        default:
+            return new ZintrustProvider();
+    }
+}

package/dist/build-manifest.json

@@ -0,0 +1,114 @@
+{
+  "name": "@zintrust/expose",
+  "version": "0.4.58",
+  "buildDate": "2026-04-04T19:58:21.241Z",
+  "buildEnvironment": {
+    "node": "v22.22.1",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "git": {
+    "commit": "99e4d331",
+    "branch": "release"
+  },
+  "package": {
+    "dependencies": [
+      "cloudflared",
+      "commander",
+      "dotenv"
+    ],
+    "peerDependencies": [
+      "@zintrust/core"
+    ]
+  },
+  "files": {
+    ".tsbuildinfo": {
+      "size": 237,
+      "sha256": "1bbf649a4aaa9638d528f72043ee08eed6f83ea8dc3b1ae79a8eecd6951c33c8"
+    },
+    "ExposeCommand.d.ts": {
+      "size": 139,
+      "sha256": "1d626d9af74c580209e2a25698b988df26f3618de86fe25d5f210571ae17be4e"
+    },
+    "ExposeCommand.d.ts.map": {
+      "size": 206,
+      "sha256": "27216831474eb9679ca05e762c431d11df8bfe27c4cf25d62ea46dd066f1600b"
+    },
+    "ExposeCommand.js": {
+      "size": 2366,
+      "sha256": "f03dfe8cf14ae1b23f066a8e3e7b7d361667c7e915213acc141cf76e81834652"
+    },
+    "TunnelManager.d.ts": {
+      "size": 156,
+      "sha256": "c124af9323f0215aa3e4c511d88541e53cab0836e9dd570d9d05b84f913bcf81"
+    },
+    "TunnelManager.d.ts.map": {
+      "size": 222,
+      "sha256": "70ab4e635b2b7e38423a7d30a2d9e73e84444dae6e76ddf480dd90e697f3a378"
+    },
+    "TunnelManager.js": {
+      "size": 442,
+      "sha256": "16cedc84ff7d7575514eede3c86d022e84e529bebc32147a2cc0097ec80f25ed"
+    },
+    "index.d.ts": {
+      "size": 118,
+      "sha256": "29e1ca420de1f7e4b0325e3b555ee9cca48f8eb19a15a63c9fbda99f7064cbe8"
+    },
+    "index.d.ts.map": {
+      "size": 188,
+      "sha256": "2114823c51f672d2b1d66fc1854dfaddb4857183fd90c2c0d7b3bb12e49b36f3"
+    },
+    "index.js": {
+      "size": 236,
+      "sha256": "deb8aef1bda0832afe5bbf22b21d1f1ecfddc02f97894803a96092f1e0a9567f"
+    },
+    "providers/CloudflareProvider.d.ts": {
+      "size": 152,
+      "sha256": "8cbbb4a3428cc8e030c9b280e962498c7658396fd0f4ab60d6dcff48cceb3d76"
+    },
+    "providers/CloudflareProvider.d.ts.map": {
+      "size": 238,
+      "sha256": "1c01a489040b9f251d7275ad8eb78184237e464b7973f2a5c1dd7f056a81d565"
+    },
+    "providers/CloudflareProvider.js": {
+      "size": 3335,
+      "sha256": "2032185d45cbf49006d3100a39608720ab0dc3179637f0ed3947005ed4f8be2b"
+    },
+    "providers/ITunnelProvider.d.ts": {
+      "size": 367,
+      "sha256": "d7905c566db2f564ef246dfee65791012adfc11ee983593e05fe2541e16cb828"
+    },
+    "providers/ITunnelProvider.d.ts.map": {
+      "size": 449,
+      "sha256": "d4cb56ac5d4c8931309577b14817f0ca7cb5a6a24d524c50bf9450b6f96ac2a5"
+    },
+    "providers/ITunnelProvider.js": {
+      "size": 11,
+      "sha256": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881"
+    },
+    "providers/ZintrustProvider.d.ts": {
+      "size": 225,
+      "sha256": "a99419f227a6bcd040f20c260c0f3578fc5056ae4fbf0b7681c18bc12f5f7d5b"
+    },
+    "providers/ZintrustProvider.d.ts.map": {
+      "size": 322,
+      "sha256": "6f58e3adf0e9665bc83df3227e94217127cdb0865782a59f11666db788243af9"
+    },
+    "providers/ZintrustProvider.js": {
+      "size": 590,
+      "sha256": "004335170e84ab2525e98e7a25f7576d6466e0d34f268d75b6f5a078356a5f2a"
+    },
+    "register.d.ts": {
+      "size": 11,
+      "sha256": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881"
+    },
+    "register.d.ts.map": {
+      "size": 110,
+      "sha256": "43d6ff274ab1483756d47f84bbbd565e33570698ffcba03ace354bebd2c37a1a"
+    },
+    "register.js": {
+      "size": 420,
+      "sha256": "63cb414c1038e014d5ff0c3b429ee2201573ba78673db725e5f72544c66f1530"
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ExposeCommand } from './ExposeCommand.js';
+export { ITunnelProvider } from './providers/ITunnelProvider.js';

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @zintrust/expose v0.4.58
+ *
+ * ZinTrust local tunnel exposure package
+ *
+ * Build Information:
+ *   Built: 2026-04-04T19:58:21.168Z
+ *   Node: >=20.0.0
+ *   License: MIT
+ *
+ */
+export { ExposeCommand } from './ExposeCommand.js';

package/dist/providers/CloudflareProvider.d.ts

@@ -0,0 +1,4 @@
+import type { ITunnelProvider } from './ITunnelProvider.js';
+export declare const CloudflareProvider: Readonly<{
+    create: () => ITunnelProvider;
+}>;

package/dist/providers/CloudflareProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudflareProvider.d.ts","sourceRoot":"","sources":["../../src/providers/CloudflareProvider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,sBAAsB,CAAC;AAgI3E,eAAO,MAAM,kBAAkB;kBA1EZ,eAAe;EA4EhC,CAAC"}

package/dist/providers/CloudflareProvider.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+const createTunnelUrlHandler = (urlRegex, resolveOnce) => {
+    return (data) => {
+        const match = urlRegex.exec(data.toString());
+        if (match !== null) {
+            resolveOnce(match[1]);
+        }
+    };
+};
+const createTunnelCloseHandler = (clearStartupTimer, shouldReject, rejectOnce) => {
+    return (code) => {
+        clearStartupTimer();
+        if (shouldReject() && code !== 0) {
+            rejectOnce(new Error(`Tunnel closed unexpectedly with code ${String(code)}`));
+        }
+    };
+};
+const createTunnelErrorHandler = (rejectOnce) => {
+    return (error) => {
+        rejectOnce(error);
+    };
+};
+const rejectStartupTimeout = (rejectOnce) => {
+    rejectOnce(new Error('Cloudflared tunnel startup timed out.'));
+};
+const stopAfterStartupTimeout = async (stop, rejectOnce) => {
+    try {
+        await stop();
+    }
+    finally {
+        rejectStartupTimeout(rejectOnce);
+    }
+};
+const createStartupTimeoutHandler = (stop, rejectOnce) => {
+    return () => {
+        void stopAfterStartupTimeout(stop, rejectOnce);
+    };
+};
+const create = () => {
+    let childProcess = null;
+    let isStopping = false;
+    let startupTimer;
+    const clearStartupTimer = () => {
+        if (startupTimer !== undefined) {
+            clearTimeout(startupTimer);
+            startupTimer = undefined;
+        }
+    };
+    const stop = async () => {
+        isStopping = true;
+        clearStartupTimer();
+        if (childProcess !== null) {
+            childProcess.kill();
+            childProcess = null;
+        }
+    };
+    const start = async (options) => {
+        return new Promise((resolve, reject) => {
+            const scheme = options.https ? 'https' : 'http';
+            const localUrl = `${scheme}://localhost:${options.port}`;
+            const urlRegex = /(https:\/\/[a-z0-9-]+\.trycloudflare\.com)/;
+            let settled = false;
+            const resolveOnce = (url) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearStartupTimer();
+                resolve(url);
+            };
+            const rejectOnce = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearStartupTimer();
+                reject(error);
+            };
+            process.stdout.write(`Starting cloudflared tunnel to ${localUrl}...\n`);
+            childProcess = spawn('npx', ['cloudflared', 'tunnel', '--url', localUrl], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const handleTunnelUrl = createTunnelUrlHandler(urlRegex, resolveOnce);
+            const handleClose = createTunnelCloseHandler(clearStartupTimer, () => !isStopping && !settled, rejectOnce);
+            const handleError = createTunnelErrorHandler(rejectOnce);
+            const handleStartupTimeout = createStartupTimeoutHandler(stop, rejectOnce);
+            childProcess.stderr?.on('data', handleTunnelUrl);
+            childProcess.on('close', handleClose);
+            childProcess.on('error', handleError);
+            startupTimer = globalThis.setTimeout(handleStartupTimeout, 15000);
+        });
+    };
+    return Object.freeze({
+        start,
+        stop,
+    });
+};
+export const CloudflareProvider = Object.freeze({
+    create,
+});

package/dist/providers/ITunnelProvider.d.ts

@@ -0,0 +1,16 @@
+export interface TunnelOptions {
+    port: number;
+    https: boolean;
+    subdomain?: string;
+    providerOptions?: Record<string, unknown>;
+}
+export interface ITunnelProvider {
+    /**
+     * Start the tunnel and return the public URL.
+     */
+    start(options: TunnelOptions): Promise<string>;
+    /**
+     * Stop the tunnel.
+     */
+    stop(): Promise<void>;
+}

package/dist/providers/ITunnelProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITunnelProvider.d.ts","sourceRoot":"","sources":["../../src/providers/ITunnelProvider.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/providers/ITunnelProvider.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/ZintrustProvider.d.ts

@@ -0,0 +1,5 @@
+import type { ITunnelProvider, TunnelOptions } from './ITunnelProvider.js';
+export declare class ZintrustProvider implements ITunnelProvider {
+    start(_options: TunnelOptions): Promise<string>;
+    stop(): Promise<void>;
+}

package/dist/providers/ZintrustProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZintrustProvider.d.ts","sourceRoot":"","sources":["../../src/providers/ZintrustProvider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3E,qBAAa,gBAAiB,YAAW,eAAe;IAChD,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAS/C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/providers/ZintrustProvider.js

@@ -0,0 +1,13 @@
+export class ZintrustProvider {
+    async start(_options) {
+        // In the future, this will connect to the official ZinTrust tunneled infrastructure
+        // via WebSockets or a similar reverse proxy technique.
+        // For now, we stub this out or fallback to locolhost.
+        console.warn('ZinTrust provider is coming soon in the expose package.');
+        console.warn('Please use `--provider cloudflare` instead for now.');
+        throw new Error('ZinTrust Tunnel Provider not implemented yet');
+    }
+    async stop() {
+        // Clean up WS connections or sockets
+    }
+}

package/dist/register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":""}

package/dist/register.js

@@ -0,0 +1,11 @@
+import { ExposeCommand } from './ExposeCommand.js';
+try {
+    const core = (await import('@zintrust/core'));
+    if (core.OptionalCliCommandRegistry !== undefined) {
+        core.OptionalCliCommandRegistry.register('expose', ExposeCommand);
+    }
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Failed to register expose command: ${message}\n`);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zintrust/expose",
+  "version": "0.4.58",
+  "description": "ZinTrust local tunnel exposure package",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "default": "./dist/register.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "watch": "tsc -b -w",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "cloudflared": "^0.3.0",
+    "commander": "^14.0.3",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@zintrust/core": "^0.4.58"
+  },
+  "author": "ZinTrust",
+  "license": "MIT"
+}

package/src/ExposeCommand.ts

@@ -0,0 +1,56 @@
+/* eslint-disable no-console */
+import { Command } from 'commander';
+import * as dotenv from 'dotenv';
+import { resolve } from 'node:path';
+import { createTunnelProvider } from './TunnelManager.js';
+
+// Since this CLI runs early, we parse .env for the default PORT if unspecified
+dotenv.config({ path: resolve(process.cwd(), '.env') });
+
+const createExposeCommand = (): Command => {
+  const command = new Command('expose')
+    .alias('exp')
+    .description('Expose your local ZinTrust server to the internet using secure tunnels.')
+    .argument('[port]', 'The local port to expose', process.env['PORT'] || '3000')
+    .option('--https', 'Connect locally via HTTPS instead of HTTP', false)
+    .option('--provider <provider>', 'Tunnel provider (zintrust | cloudflare)', 'cloudflare')
+    .action(async (portArg, options) => {
+      const port = Number.parseInt(portArg, 10);
+      if (Number.isNaN(port)) {
+        console.error(`Invalid port provided: ${portArg}`);
+        process.exit(1);
+      }
+
+      console.log(`Starting URL exposure on port ${port} using ${options.provider} provider...`);
+
+      const provider = createTunnelProvider(options.provider);
+
+      try {
+        const publicUrl = await provider.start({ port, https: options.https });
+
+        console.log(`\n=============================================================`);
+        console.log(`🚀 Tunnel Established successfully!`);
+        console.log(`🌍 Public URL     : \x1b[32m${publicUrl}\x1b[0m`);
+        console.log(`🔌 Local Target   : ${options.https ? 'https' : 'http'}://localhost:${port}`);
+        console.log(`🛡️  Provider      : ${options.provider}`);
+        console.log(`=============================================================\n`);
+        console.log(`Press Ctrl+C to disconnect from the tunnel.\n`);
+
+        process.on('SIGINT', async () => {
+          console.log(`\nDisconnecting ${options.provider} tunnel...`);
+          await provider.stop();
+          process.exit(0);
+        });
+      } catch (error: unknown) {
+        console.error(`Tunnel failed to start:`, (error as Error).message);
+        process.exit(1);
+      }
+    });
+
+  return command;
+};
+
+export const ExposeCommand = Object.freeze({
+  getCommand: createExposeCommand,
+  name: 'expose',
+});

package/src/TunnelManager.ts

@@ -0,0 +1,15 @@
+import { CloudflareProvider } from './providers/CloudflareProvider.js';
+import type { ITunnelProvider } from './providers/ITunnelProvider.js';
+import { ZintrustProvider } from './providers/ZintrustProvider.js';
+
+export function createTunnelProvider(providerName: string): ITunnelProvider {
+  switch (providerName.toLowerCase()) {
+    case 'cloudflare':
+    case 'cf':
+      return CloudflareProvider.create();
+    case 'zintrust':
+    case 'zin':
+    default:
+      return new ZintrustProvider();
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { ExposeCommand } from './ExposeCommand.js';
+
+export { ITunnelProvider } from './providers/ITunnelProvider.js';

package/src/providers/CloudflareProvider.ts

@@ -0,0 +1,132 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { ITunnelProvider, TunnelOptions } from './ITunnelProvider.js';
+
+type ResolveOnce = (url: string) => void;
+type RejectOnce = (error: Error) => void;
+
+const createTunnelUrlHandler = (urlRegex: RegExp, resolveOnce: ResolveOnce) => {
+  return (data: string | Uint8Array): void => {
+    const match = urlRegex.exec(data.toString());
+    if (match !== null) {
+      resolveOnce(match[1]);
+    }
+  };
+};
+
+const createTunnelCloseHandler = (
+  clearStartupTimer: () => void,
+  shouldReject: () => boolean,
+  rejectOnce: RejectOnce
+) => {
+  return (code: number | null): void => {
+    clearStartupTimer();
+    if (shouldReject() && code !== 0) {
+      rejectOnce(new Error(`Tunnel closed unexpectedly with code ${String(code)}`));
+    }
+  };
+};
+
+const createTunnelErrorHandler = (rejectOnce: RejectOnce) => {
+  return (error: Error): void => {
+    rejectOnce(error);
+  };
+};
+
+const rejectStartupTimeout = (rejectOnce: RejectOnce): void => {
+  rejectOnce(new Error('Cloudflared tunnel startup timed out.'));
+};
+
+const stopAfterStartupTimeout = async (
+  stop: () => Promise<void>,
+  rejectOnce: RejectOnce
+): Promise<void> => {
+  try {
+    await stop();
+  } finally {
+    rejectStartupTimeout(rejectOnce);
+  }
+};
+
+const createStartupTimeoutHandler = (stop: () => Promise<void>, rejectOnce: RejectOnce) => {
+  return (): void => {
+    void stopAfterStartupTimeout(stop, rejectOnce);
+  };
+};
+
+const create = (): ITunnelProvider => {
+  let childProcess: ChildProcess | null = null;
+  let isStopping = false;
+  let startupTimer: NodeJS.Timeout | undefined;
+
+  const clearStartupTimer = (): void => {
+    if (startupTimer !== undefined) {
+      clearTimeout(startupTimer);
+      startupTimer = undefined;
+    }
+  };
+
+  const stop = async (): Promise<void> => {
+    isStopping = true;
+    clearStartupTimer();
+
+    if (childProcess !== null) {
+      childProcess.kill();
+      childProcess = null;
+    }
+  };
+
+  const start = async (options: TunnelOptions): Promise<string> => {
+    return new Promise((resolve, reject) => {
+      const scheme = options.https ? 'https' : 'http';
+      const localUrl = `${scheme}://localhost:${options.port}`;
+      const urlRegex = /(https:\/\/[a-z0-9-]+\.trycloudflare\.com)/;
+      let settled = false;
+
+      const resolveOnce = (url: string): void => {
+        if (settled) return;
+        settled = true;
+        clearStartupTimer();
+        resolve(url);
+      };
+
+      const rejectOnce = (error: Error): void => {
+        if (settled) return;
+        settled = true;
+        clearStartupTimer();
+        reject(error);
+      };
+
+      process.stdout.write(`Starting cloudflared tunnel to ${localUrl}...\n`);
+
+      childProcess = spawn('npx', ['cloudflared', 'tunnel', '--url', localUrl], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      const handleTunnelUrl = createTunnelUrlHandler(urlRegex, resolveOnce);
+      const handleClose = createTunnelCloseHandler(
+        clearStartupTimer,
+        () => !isStopping && !settled,
+        rejectOnce
+      );
+      const handleError = createTunnelErrorHandler(rejectOnce);
+      const handleStartupTimeout = createStartupTimeoutHandler(stop, rejectOnce);
+
+      childProcess.stderr?.on('data', handleTunnelUrl);
+
+      childProcess.on('close', handleClose);
+
+      childProcess.on('error', handleError);
+
+      startupTimer = globalThis.setTimeout(handleStartupTimeout, 15000);
+    });
+  };
+
+  return Object.freeze({
+    start,
+    stop,
+  });
+};
+
+export const CloudflareProvider = Object.freeze({
+  create,
+});

package/src/providers/ITunnelProvider.ts

@@ -0,0 +1,18 @@
+export interface TunnelOptions {
+  port: number;
+  https: boolean;
+  subdomain?: string;
+  providerOptions?: Record<string, unknown>;
+}
+
+export interface ITunnelProvider {
+  /**
+   * Start the tunnel and return the public URL.
+   */
+  start(options: TunnelOptions): Promise<string>;
+
+  /**
+   * Stop the tunnel.
+   */
+  stop(): Promise<void>;
+}

package/src/providers/ZintrustProvider.ts

@@ -0,0 +1,18 @@
+/* eslint-disable no-restricted-syntax */
+/* eslint-disable no-console */
+import type { ITunnelProvider, TunnelOptions } from './ITunnelProvider.js';
+
+export class ZintrustProvider implements ITunnelProvider {
+  async start(_options: TunnelOptions): Promise<string> {
+    // In the future, this will connect to the official ZinTrust tunneled infrastructure
+    // via WebSockets or a similar reverse proxy technique.
+    // For now, we stub this out or fallback to locolhost.
+    console.warn('ZinTrust provider is coming soon in the expose package.');
+    console.warn('Please use `--provider cloudflare` instead for now.');
+    throw new Error('ZinTrust Tunnel Provider not implemented yet');
+  }
+
+  async stop(): Promise<void> {
+    // Clean up WS connections or sockets
+  }
+}

package/src/register.ts

@@ -0,0 +1,20 @@
+import { ExposeCommand } from './ExposeCommand.js';
+
+type OptionalCliCommandRegistryLike = {
+  register: (name: string, command: typeof ExposeCommand) => void;
+};
+
+type CoreModuleLike = {
+  OptionalCliCommandRegistry?: OptionalCliCommandRegistryLike;
+};
+
+try {
+  const core = (await import('@zintrust/core')) as CoreModuleLike;
+
+  if (core.OptionalCliCommandRegistry !== undefined) {
+    core.OptionalCliCommandRegistry.register('expose', ExposeCommand);
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`Failed to register expose command: ${message}\n`);
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["es2023"],
+    "baseUrl": ".",
+    "moduleResolution": "bundler",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": false,
+    "sourceMap": false,
+    "composite": false,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "tsBuildInfoFile": "./dist/.tsbuildinfo",
+    "paths": {}
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}