cloudflare-tunnel-kit 0.1.2 → 0.1.3

package/README.md

@@ -35,40 +35,52 @@ The toolkit does not concatenate user input into shell commands, print secrets t
 
 ## Installation
 
-Install the package after it is published:
+Install the package in the project that needs a tunnel:
 
 ```bash
 npm install --save-dev cloudflare-tunnel-kit
 ```
 
-For a source checkout:
+The package exposes the `cf-tunnel` binary locally. Run it through `npx` so no global installation is required:
 
 ```bash
-npm install
-npm run build
-node ./dist/cli/main.js --help
+npx cf-tunnel
+npx cf-tunnel ui
+```
+
+You can also add project scripts:
+
+```json
+{
+  "scripts": {
+    "tunnel": "cf-tunnel",
+    "tunnel:ui": "cf-tunnel ui"
+  }
+}
 ```
 
+Then run `npm run tunnel` or `npm run tunnel:ui`.
+
 ## CLI usage
 
 Check the local environment:
 
 ```bash
-cf-tunnel doctor
+npx cf-tunnel doctor
 ```
 
-Run `cf-tunnel` or `cf-tunnel init` without options to start the interactive text-only wizard. It asks for each value, validates before execution, prints a command preview, and asks for confirmation.
+Run `npx cf-tunnel` without options to start the interactive text-only wizard. It asks for each value, validates before execution, prints a command preview, and asks for confirmation.
 
 Preview a Quick Tunnel without starting `cloudflared`:
 
 ```bash
-cf-tunnel quick --url http://127.0.0.1:8000 --dry-run
+npx cf-tunnel quick --url http://127.0.0.1:8000 --dry-run
 ```
 
 Preview a named tunnel:
 
 ```bash
-cf-tunnel create \
+npx cf-tunnel create \
   --url http://127.0.0.1:8000 \
   --name my-project \
   --hostname tunnel.example.com \
@@ -78,39 +90,22 @@ cf-tunnel create \
 Lifecycle commands:
 
 ```text
-cf-tunnel start --name my-project
-cf-tunnel stop --name my-project
-cf-tunnel status --name my-project
+npx cf-tunnel start --name my-project
+npx cf-tunnel stop --name my-project
+npx cf-tunnel status --name my-project
 ```
 
 `--yes` does not bypass validation or Laravel `.env` confirmation.
 
-## Makefile shortcuts
-
-The repository includes a small Makefile for discoverable commands:
-
-```bash
-make setup
-make help
-make init
-make ui
-make quick URL=http://127.0.0.1:8000
-make create NAME=law-firm URL=http://127.0.0.1:8000
-make doctor
-make test
-```
-
-`make quick` and `make create` use `--dry-run` by default. Review the plan, then use the CLI to execute and confirm the operation explicitly.
-
 ## Live UI
 
 Start the local UI:
 
 ```bash
-cf-tunnel ui
+npx cf-tunnel ui
 ```
 
-Open the URL printed in the terminal, usually `http://127.0.0.1:<port>`. The wizard includes profile selection, local URL input, tunnel name, validation, plan preview, confirmation, execution, and a button to copy a redacted AI-help prompt.
+The command prints startup progress, chooses an available loopback port, and opens the browser automatically. If the browser cannot be opened, copy the printed `http://127.0.0.1:<port>` URL. Use `npx cf-tunnel ui --no-open` when you only want the URL.
 
 The UI binds to loopback by default and does not send the copied prompt anywhere.
 
@@ -119,8 +114,8 @@ The UI binds to loopback by default and does not send the copied prompt anywhere
 The custom profile makes no framework assumptions:
 
 ```bash
-cf-tunnel quick --profile custom --url http://127.0.0.1:3000 --dry-run
-cf-tunnel create --profile custom --url http://127.0.0.1:8000 --name billing --dry-run
+npx cf-tunnel quick --profile custom --url http://127.0.0.1:3000 --dry-run
+npx cf-tunnel create --profile custom --url http://127.0.0.1:8000 --name billing --hostname billing.example.com --dry-run
 ```
 
 ## Laravel profile
@@ -130,10 +125,11 @@ The Laravel adapter checks for `artisan` and Laravel evidence in `composer.json`
 Every mapping is shown as a diff and requires explicit confirmation. If `.env` is missing or ambiguous, the adapter stops with a remediation message instead of guessing.
 
 ```bash
-cf-tunnel create \
+npx cf-tunnel create \
   --profile laravel \
   --url http://127.0.0.1:8000 \
   --name law-firm \
+  --hostname law.example.com \
   --dry-run
 ```
 
@@ -214,6 +210,8 @@ An already-published `name@version` cannot be published again. See the [npm publ
 
 ## Development
 
+These commands are only for contributors working from a source checkout. Projects that install the npm package do not need this repository's Makefile.
+
 ```bash
 npm install
 npm test

package/dist/cli/main.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { createServer } from '../ui/server.js';
 import { createTunnelPlan, executeTunnelPlan } from '../index.js';
 import { createLaravelPlan } from '../index.js';
+import { launchBrowser } from '../providers/browser.js';
 import { runWizard } from './wizard.js';
 const args = process.argv.slice(2);
 const command = args[0] ?? 'init';
+const packageVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 const value = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
-function help() { console.log(`cloudflare-tunnel-kit 0.1.0\n\nUsage: cf-tunnel <command> [options]\n\nCommands: init create quick start stop status doctor ui\nOptions: --url URL --name NAME --hostname HOST --profile custom|laravel --config PATH --dry-run --yes --no-open`); }
+function help() { console.log(`cloudflare-tunnel-kit ${packageVersion}\n\nUsage from an installed project:\n  npx cf-tunnel\n  npx cf-tunnel ui\n\nCommands: init create quick start stop status doctor ui\nOptions: --url URL --name NAME --hostname HOST --profile custom|laravel --config PATH --dry-run --yes --no-open`); }
 async function main() {
     if (command === 'init') {
         if (args.length === 1)
@@ -15,8 +18,24 @@ async function main() {
     if (command === 'help' || command === '--help')
         return help();
     if (command === 'ui') {
+        console.log('Starting Cloudflare Tunnel Kit UI on this machine...');
         const server = createServer();
-        server.listen(0, '127.0.0.1', () => { const a = server.address(); console.log(`UI ready at http://127.0.0.1:${a.port}`); });
+        server.once('error', error => {
+            console.error(`Unable to start the local UI: ${error.message}`);
+            console.error('Check whether local server processes are allowed, then run `npx cf-tunnel ui` again.');
+            process.exitCode = 1;
+        });
+        server.listen(0, '127.0.0.1', async () => {
+            const address = server.address();
+            if (!address || typeof address === 'string')
+                return;
+            const url = `http://127.0.0.1:${address.port}`;
+            console.log(`UI ready at ${url}`);
+            if (!args.includes('--no-open')) {
+                const result = await launchBrowser(url);
+                console.log(result.message);
+            }
+        });
         return;
     }
     if (command === 'doctor') {

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * from './providers/command-runner.js';
 export * from './providers/cloudflared.js';
 export * from './providers/git-safety.js';
 export * from './providers/process-supervisor.js';
+export * from './providers/browser.js';

package/dist/index.js

@@ -13,3 +13,4 @@ export * from './providers/command-runner.js';
 export * from './providers/cloudflared.js';
 export * from './providers/git-safety.js';
 export * from './providers/process-supervisor.js';
+export * from './providers/browser.js';

package/dist/providers/browser.d.ts

@@ -0,0 +1,9 @@
+export declare function launchBrowser(url: string, options?: {
+    platform?: string;
+    run?: (executable: string, args: string[]) => Promise<{
+        exitCode: number;
+    }>;
+}): Promise<{
+    opened: boolean;
+    message: string;
+}>;

package/dist/providers/browser.js

@@ -0,0 +1,17 @@
+import { runCommand } from './command-runner.js';
+export async function launchBrowser(url, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? ((executable, args) => runCommand({ executable, args, timeoutMs: 10_000 }));
+    const command = platform === 'darwin'
+        ? ['open', [url]]
+        : platform === 'win32'
+            ? ['cmd.exe', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const result = await run(command[0], [...command[1]]);
+        if (result.exitCode === 0)
+            return { opened: true, message: `Opened ${url}` };
+    }
+    catch { }
+    return { opened: false, message: `Open this URL manually: ${url}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-tunnel-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Safe, reusable Cloudflare Tunnel setup for custom and Laravel projects.",
   "type": "module",
   "bin": {
@@ -34,6 +34,6 @@
   },
   "license": "MIT",
   "dependencies": {
-    "better-sqlite3": "^13.0.3"
+    "better-sqlite3": "^12.11.1"
   }
 }