cloudflare-tunnel-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloudflare-tunnel-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# cloudflare-tunnel-kit
+
+Thư viện mã nguồn mở giúp dự án tạo và tích hợp Cloudflare Tunnel bằng hai cách: command line hoặc live UI chạy cục bộ. Mục tiêu là thay thế các shell script/Makefile rời rạc bằng flow wizard có validation, preview và confirmation rõ ràng.
+
+## Current version
+
+`0.1.0` là bản MVP hiện có:
+
+- Core TypeScript API cho validation, tạo plan, redaction và execution.
+- CLI `cf-tunnel` với `init`, `create`, `quick`, `start`, `stop`, `status`, `doctor`, `ui`.
+- Profile `custom` và Laravel detection với proposal mapping `APP_URL`.
+- Quick tunnel và named-tunnel argv generation.
+- Validation URL, hostname, tunnel name và path dưới project root.
+- Dry-run, structured errors và prompt an toàn để copy hỏi AI.
+- UI HTML/CSS/JS nhẹ, bind loopback, không cần frontend framework.
+
+Laravel `.env` mapping cho `APP_URL` đã có ở dạng proposal/diff; thao tác vẫn cần confirmation và hiện chưa tự động ghi file trong CLI/UI.
+
+## Ý tưởng và nguyên tắc
+
+Flow luôn là: `input -> detect -> validate -> preview plan -> confirm -> execute -> summary`.
+
+Không nối input thành shell command, không in secret ra log, không ghi đè config hoặc `.env` âm thầm. Người dùng luôn nhìn thấy command/file operation trước khi chạy.
+
+## Yêu cầu
+
+- Node.js 20 trở lên.
+- `cloudflared` trong `PATH` nếu muốn chạy tunnel thật.
+- Quyền Cloudflare phù hợp với loại named tunnel.
+
+## Cài đặt
+
+Khi package được phát hành:
+
+```bash
+npm install --save-dev cloudflare-tunnel-kit
+```
+
+Trong source checkout:
+
+```bash
+npm install
+npm run build
+node dist/cli/main.js --help
+```
+
+## Makefile shortcuts
+
+Nếu thích command ngắn, package có Makefile:
+
+```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 quick` và `make create` mặc định chỉ preview (`--dry-run`). Sau khi review, dùng CLI trực tiếp để execute và xác nhận rõ ràng.
+
+## CLI text-only
+
+Kiểm tra môi trường:
+
+```bash
+cf-tunnel doctor
+```
+
+Chạy `cf-tunnel` hoặc `cf-tunnel init` không kèm options để mở interactive wizard text-only. Wizard hỏi từng bước, in lỗi kèm cách sửa, hiển thị command preview và hỏi xác nhận trước khi execute.
+
+Quick tunnel, chỉ validate/preview:
+
+```bash
+cf-tunnel quick --url http://127.0.0.1:8000 --dry-run
+```
+
+Named tunnel sau khi review plan:
+
+```bash
+cf-tunnel create --url http://127.0.0.1:8000 --name my-project --hostname tunnel.example.com
+```
+
+Lifecycle commands:
+
+```text
+cf-tunnel start --name my-project
+cf-tunnel stop --name my-project
+cf-tunnel status --name my-project
+cf-tunnel init --profile custom --url http://127.0.0.1:8000 --dry-run
+```
+
+`--yes` không bỏ qua validation và không bypass confirmation của Laravel `.env`.
+
+## Live UI
+
+```bash
+cf-tunnel ui
+```
+
+Mở URL được in ra, thường là `http://127.0.0.1:<port>`. Wizard gồm profile, local URL, tunnel name, validation và plan preview. UI chỉ lắng nghe loopback. Nút copy tạo prompt AI đã loại bỏ secret; package không tự gửi prompt đó đi đâu.
+
+## Custom profile
+
+Custom profile không đoán framework:
+
+```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
+```
+
+## Laravel profile
+
+Laravel adapter kiểm tra `artisan` và `composer.json`, sau đó đề xuất mapping như `APP_URL`, `ASSET_URL` hoặc Reverb URL. Mỗi mapping phải hiện thành diff và cần confirmation riêng. Nếu `.env` thiếu hoặc không rõ, tool dừng với hướng dẫn; không tự đoán và không tự ghi ngầm.
+
+```bash
+cf-tunnel create --profile laravel --url http://127.0.0.1:8000 --name law-firm --dry-run
+```
+
+## API
+
+```ts
+import { validateTunnelConfig, createTunnelPlan, executeTunnelPlan } from 'cloudflare-tunnel-kit';
+
+const config = { profile: 'custom', operation: 'quick', localUrl: 'http://127.0.0.1:8000' };
+const validation = validateTunnelConfig(config);
+if (!validation.ok) for (const error of validation.issues) console.error(error.code, error.reason, error.fix);
+const plan = createTunnelPlan(config);
+const result = await executeTunnelPlan(plan, { dryRun: true });
+console.log(result);
+```
+
+Plan có thể serialize để hiển thị trong hệ thống riêng. Chỉ execute plan đã validated và sau khi người dùng approve confirmation group.
+
+## Error model
+
+Mỗi lỗi có `code`, `field` (nếu có), `reason` và `fix`. Mã thường gặp: `INPUT_INVALID_URL`, `INPUT_INVALID_HOSTNAME`, `INPUT_INVALID_TUNNEL_NAME`, `PATH_OUTSIDE_PROJECT`, `CONFIRMATION_REQUIRED`, `PROCESS_FAILED`.
+
+Khi copy lỗi để hỏi AI, kiểm tra lại prompt đã redact trước khi dán vào dịch vụ bên ngoài.
+
+## Security model
+
+- UI bind `127.0.0.1` mặc định.
+- Process chạy argv array với shell disabled.
+- Secret-looking key/value, bearer token và credential path được redact.
+- File path được kiểm tra dưới project root.
+- Dry-run không gọi cloudflared.
+- Config overwrite và Laravel `.env` write phải được preview và confirm.
+- Không gửi telemetry hoặc diagnostic ra ngoài.
+
+Tool không thay thế việc review Cloudflare account permissions, DNS, access policy hoặc secret management của tổ chức.
+
+## Phát triển
+
+```bash
+npm test
+npm run build
+git diff --check
+```
+
+GitHub Actions hiện chỉ chạy CI build/test với Node.js 24. Project không dùng `actions/deploy-pages` vì live UI là local Node server, không phải static site chạy trên GitHub Pages.
+
+Test dùng Node built-ins và temporary fixtures; không cần Cloudflare account. Khi đóng góp, thêm test trước cho behavior mới và không đưa secret thật vào fixture.
+
+## License
+
+MIT. Xem [LICENSE](LICENSE).

package/dist/adapters/laravel.d.ts

@@ -0,0 +1,3 @@
+import type { TunnelConfig, TunnelPlan } from '../core/types.js';
+export declare function detectLaravel(projectRoot?: string): boolean;
+export declare function createLaravelPlan(input: TunnelConfig): TunnelPlan;

package/dist/adapters/laravel.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createTunnelPlan } from '../core/plan.js';
+export function detectLaravel(projectRoot = process.cwd()) {
+    if (!existsSync(path.join(projectRoot, 'artisan')) || !existsSync(path.join(projectRoot, 'composer.json')))
+        return false;
+    try {
+        return /laravel|illuminate/i.test(readFileSync(path.join(projectRoot, 'composer.json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+export function createLaravelPlan(input) {
+    const plan = createTunnelPlan({ ...input, profile: 'laravel' });
+    if (!detectLaravel(plan.config.projectRoot)) {
+        plan.valid = false;
+        plan.issues = [{ code: 'LARAVEL_NOT_DETECTED', reason: 'artisan and Laravel composer evidence were not found.', fix: 'Run this from the Laravel project root or use profile custom.' }];
+    }
+    else {
+        plan.confirmations = [...new Set([...plan.confirmations, 'laravel-env'])];
+        const mappings = input.laravel ?? {};
+        const envPath = path.join(plan.config.projectRoot ?? process.cwd(), '.env');
+        if (existsSync(envPath) && mappings.mapAppUrl) {
+            const current = readFileSync(envPath, 'utf8');
+            const next = setEnv(current, 'APP_URL', plan.config.hostname ? `https://${plan.config.hostname}` : plan.config.localUrl);
+            plan.fileOperations.push({ path: '.env', action: 'update', content: next, requiresConfirmation: true });
+            plan.summary += ' Proposed APP_URL update is shown in the plan and needs confirmation.';
+        }
+        else if (mappings.mapAppUrl) {
+            plan.valid = false;
+            plan.issues = [{ code: 'LARAVEL_ENV_NOT_FOUND', reason: '.env was requested for mapping but does not exist.', fix: 'Create .env from .env.example, or disable APP_URL mapping.', field: '.env' }];
+        }
+        plan.summary += ' Laravel .env mappings require explicit confirmation.';
+    }
+    return plan;
+}
+function setEnv(content, key, value) {
+    const line = `${key}=${value}`;
+    const expression = new RegExp(`^${key}=.*$`, 'm');
+    return expression.test(content) ? content.replace(expression, line) : `${content.replace(/\s*$/, '')}\n${line}\n`;
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/main.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { createServer } from '../ui/server.js';
+import { createTunnelPlan, executeTunnelPlan } from '../index.js';
+import { createLaravelPlan } from '../index.js';
+import { runWizard } from './wizard.js';
+const args = process.argv.slice(2);
+const command = args[0] ?? 'init';
+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`); }
+async function main() {
+    if (command === 'init') {
+        if (args.length === 1)
+            return runWizard();
+    }
+    if (command === 'help' || command === '--help')
+        return help();
+    if (command === 'ui') {
+        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}`); });
+        return;
+    }
+    if (command === 'doctor') {
+        console.log('Doctor: use `cf-tunnel quick --url http://127.0.0.1:8000 --dry-run` to validate a project without starting cloudflared.');
+        return;
+    }
+    const operation = (command === 'init' ? 'create' : command);
+    const config = { profile: value('--profile') ?? 'custom', operation, localUrl: value('--url') ?? 'http://127.0.0.1:8000', tunnelName: value('--name'), hostname: value('--hostname'), configPath: value('--config') };
+    const plan = config.profile === 'laravel' ? createLaravelPlan(config) : createTunnelPlan(config);
+    console.log(JSON.stringify({ summary: plan.summary, issues: plan.issues, argv: plan.argv, confirmations: plan.confirmations }, null, 2));
+    if (!plan.valid || args.includes('--dry-run'))
+        return;
+    const result = await executeTunnelPlan(plan, { confirmed: args.includes('--yes') ? plan.confirmations : [] });
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok)
+        process.exitCode = 1;
+}
+main().catch(e => { console.error(e instanceof Error ? e.message : String(e)); process.exitCode = 1; });

package/dist/cli/wizard.d.ts

@@ -0,0 +1,3 @@
+import type { TunnelPlan } from '../core/types.js';
+export declare function formatWizardSummary(plan: Pick<TunnelPlan, 'valid' | 'summary' | 'issues' | 'argv' | 'confirmations'>): string;
+export declare function runWizard(): Promise<void>;

package/dist/cli/wizard.js

@@ -0,0 +1,38 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { createTunnelPlan } from '../core/plan.js';
+import { createLaravelPlan } from '../adapters/laravel.js';
+import { executeTunnelPlan } from '../core/execution.js';
+export function formatWizardSummary(plan) {
+    const lines = [plan.valid ? 'Validation passed.' : 'Validation failed.', plan.summary];
+    for (const i of plan.issues)
+        lines.push(`\n[${i.code}]${i.field ? ` ${i.field}` : ''}\nReason: ${i.reason}\nFix: ${i.fix}`);
+    if (plan.valid)
+        lines.push(`\nCommand preview: cloudflared ${plan.argv.join(' ')}`);
+    if (plan.confirmations.length)
+        lines.push(`\nConfirmation required: ${plan.confirmations.join(', ')}`);
+    return lines.join('\n');
+}
+export async function runWizard() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const profileInput = (await rl.question('Profile [custom/laravel] (custom): ')).trim() || 'custom';
+        const operationInput = (await rl.question('Operation [quick/create] (quick): ')).trim() || 'quick';
+        const localUrl = (await rl.question('Local URL (http://127.0.0.1:8000): ')).trim() || 'http://127.0.0.1:8000';
+        const tunnelName = (await rl.question('Tunnel name (optional): ')).trim() || undefined;
+        const hostname = (await rl.question('Hostname (optional): ')).trim() || undefined;
+        const config = { profile: profileInput, operation: operationInput, localUrl, tunnelName, hostname };
+        const plan = config.profile === 'laravel' ? createLaravelPlan(config) : createTunnelPlan(config);
+        console.log(`\n${formatWizardSummary(plan)}`);
+        if (!plan.valid)
+            return;
+        const answer = (await rl.question('\nExecute this plan? [y/N]: ')).trim().toLowerCase();
+        if (answer === 'y' || answer === 'yes')
+            console.log(JSON.stringify(await executeTunnelPlan(plan, { confirmed: plan.confirmations }), null, 2));
+        else
+            console.log('Cancelled. No changes were made.');
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationIssue } from './types.js';
+export declare class TunnelKitError extends Error {
+    readonly issue: ValidationIssue;
+    constructor(issue: ValidationIssue);
+}

package/dist/core/errors.js

@@ -0,0 +1,8 @@
+export class TunnelKitError extends Error {
+    issue;
+    constructor(issue) {
+        super(`${issue.code}: ${issue.reason}`);
+        this.issue = issue;
+        this.name = 'TunnelKitError';
+    }
+}

package/dist/core/execution.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutionSummary, TunnelPlan } from './types.js';
+export declare function executeTunnelPlan(plan: TunnelPlan, options?: {
+    confirmed?: string[];
+    dryRun?: boolean;
+}): Promise<ExecutionSummary>;

package/dist/core/execution.js

@@ -0,0 +1,13 @@
+import { runCloudflared } from '../providers/cloudflared.js';
+export async function executeTunnelPlan(plan, options = {}) {
+    if (!plan.valid)
+        return { ok: false, operation: plan.config.operation, passed: [], skipped: [], issues: plan.issues };
+    const confirmed = new Set(options.confirmed ?? []);
+    const missing = plan.confirmations.filter(x => !confirmed.has(x));
+    if (missing.length)
+        return { ok: false, operation: plan.config.operation, passed: [], skipped: missing, issues: [{ code: 'CONFIRMATION_REQUIRED', reason: `Confirmation required for: ${missing.join(', ')}`, fix: 'Review the plan and confirm the listed operation(s).' }] };
+    if (options.dryRun)
+        return { ok: true, operation: plan.config.operation, passed: ['validation', 'plan'], skipped: ['execution (dry-run)'], issues: [] };
+    const result = await runCloudflared(plan.argv);
+    return { ok: result.code === 0, operation: plan.config.operation, passed: result.code === 0 ? ['validation', 'execution'] : ['validation'], skipped: [], issues: result.code === 0 ? [] : [{ code: 'PROCESS_FAILED', reason: result.stderr || 'cloudflared exited with a non-zero status.', fix: 'Run cf-tunnel doctor and check cloudflared authentication.' }], output: result.stdout };
+}

package/dist/core/plan.d.ts

@@ -0,0 +1,2 @@
+import type { TunnelConfig, TunnelPlan } from './types.js';
+export declare function createTunnelPlan(input: TunnelConfig): TunnelPlan;

package/dist/core/plan.js

@@ -0,0 +1,9 @@
+import crypto from 'node:crypto';
+import { validateTunnelConfig } from './validation.js';
+export function createTunnelPlan(input) {
+    const validation = validateTunnelConfig(input);
+    const c = validation.normalized ?? input;
+    const argv = c.operation === 'quick' ? ['tunnel', '--url', c.localUrl] : c.operation === 'create' ? ['tunnel', 'create', c.tunnelName ?? ''] : ['tunnel', c.operation, c.tunnelName ?? ''];
+    const fileOperations = c.operation === 'create' && c.configPath ? [{ path: c.configPath, action: 'create', content: `# Generated by cloudflare-tunnel-kit\n`, requiresConfirmation: true }] : [];
+    return { id: crypto.randomUUID(), createdAt: new Date().toISOString(), config: c, valid: validation.ok, argv, fileOperations, confirmations: fileOperations.length ? ['config-file'] : [], issues: validation.issues, summary: validation.ok ? `Ready to run: cloudflared ${argv.join(' ')}` : `${validation.issues.length} validation issue(s) must be fixed before execution.` };
+}

package/dist/core/redact.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationIssue } from './types.js';
+export declare function redact(value: string, key?: string): string;
+export declare function aiPrompt(issue: ValidationIssue): string;

package/dist/core/redact.js

@@ -0,0 +1,9 @@
+const secretKey = /(token|secret|password|private|credential|key|cert)/i;
+export function redact(value, key) {
+    if (key && secretKey.test(key))
+        return '[REDACTED]';
+    return value.replace(/(Bearer\s+)[^\s]+/gi, '$1[REDACTED]').replace(/([A-Za-z0-9_-]{24,})/g, '[REDACTED]');
+}
+export function aiPrompt(issue) {
+    return `I am configuring cloudflare-tunnel-kit.\nError: ${issue.code}\nField: ${issue.field ?? 'environment'}\nReason: ${issue.reason}\nHow can I fix it? Do not expose secrets.`;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,52 @@
+export type Profile = 'custom' | 'laravel';
+export type Operation = 'quick' | 'create' | 'start' | 'stop' | 'status';
+export interface TunnelConfig {
+    profile: Profile;
+    operation: Operation;
+    localUrl: string;
+    projectRoot?: string;
+    tunnelName?: string;
+    hostname?: string;
+    configPath?: string;
+    laravel?: {
+        mapAppUrl?: boolean;
+        mapAssetUrl?: boolean;
+        mapReverbUrl?: boolean;
+    };
+}
+export interface ValidationIssue {
+    code: string;
+    field?: string;
+    reason: string;
+    fix: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    issues: ValidationIssue[];
+    normalized?: TunnelConfig;
+}
+export interface FileOperation {
+    path: string;
+    action: 'create' | 'update';
+    content?: string;
+    requiresConfirmation: boolean;
+}
+export interface TunnelPlan {
+    id: string;
+    createdAt: string;
+    config: TunnelConfig;
+    valid: boolean;
+    argv: string[];
+    fileOperations: FileOperation[];
+    confirmations: string[];
+    issues: ValidationIssue[];
+    summary: string;
+}
+export interface ExecutionSummary {
+    ok: boolean;
+    operation: string;
+    passed: string[];
+    skipped: string[];
+    issues: ValidationIssue[];
+    output?: string;
+}

package/dist/core/types.js

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

package/dist/core/validation.d.ts

@@ -0,0 +1,2 @@
+import type { TunnelConfig, ValidationResult } from './types.js';
+export declare function validateTunnelConfig(input: TunnelConfig): ValidationResult;

package/dist/core/validation.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+function issue(code, reason, fix, field) { return { code, reason, fix, field }; }
+function inside(root, candidate) {
+    try {
+        const r = realpathSync(root);
+        const c = realpathSync(path.dirname(candidate));
+        return c === r || c.startsWith(r + path.sep);
+    }
+    catch {
+        return path.resolve(candidate).startsWith(path.resolve(root) + path.sep);
+    }
+}
+export function validateTunnelConfig(input) {
+    const issues = [];
+    let url;
+    try {
+        url = new URL(input.localUrl);
+        if (!['http:', 'https:'].includes(url.protocol))
+            throw new Error();
+    }
+    catch {
+        issues.push(issue('INPUT_INVALID_URL', 'localUrl must be an http or https URL.', 'Use a value such as http://127.0.0.1:8000.', 'localUrl'));
+    }
+    if (!['custom', 'laravel'].includes(input.profile))
+        issues.push(issue('INPUT_INVALID_PROFILE', 'Unknown project profile.', 'Choose custom or laravel.', 'profile'));
+    if (input.operation === 'create' && !input.tunnelName)
+        issues.push(issue('INPUT_TUNNEL_NAME_REQUIRED', 'Named tunnels require a tunnel name.', 'Use lowercase letters, numbers, and hyphens.', 'tunnelName'));
+    if (input.tunnelName && !/^[a-z0-9][a-z0-9-]{0,62}$/.test(input.tunnelName))
+        issues.push(issue('INPUT_INVALID_TUNNEL_NAME', 'Tunnel name is not DNS-safe.', 'Use 1-63 lowercase letters, numbers, or hyphens.', 'tunnelName'));
+    if (input.hostname && !/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(input.hostname))
+        issues.push(issue('INPUT_INVALID_HOSTNAME', 'Hostname is not a valid DNS hostname.', 'Use a fully qualified hostname such as tunnel.example.com.', 'hostname'));
+    const root = path.resolve(input.projectRoot ?? process.cwd());
+    if (input.configPath && !inside(root, path.resolve(root, input.configPath)))
+        issues.push(issue('PATH_OUTSIDE_PROJECT', 'Config path escapes the project root.', 'Choose a path inside projectRoot.', 'configPath'));
+    const normalized = { ...input, localUrl: url?.toString().replace(/\/$/, '') ?? input.localUrl, projectRoot: root };
+    return { ok: issues.length === 0, issues, normalized: issues.length === 0 ? normalized : undefined };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './core/types.js';
+export * from './core/validation.js';
+export * from './core/plan.js';
+export * from './core/execution.js';
+export * from './core/redact.js';
+export * from './adapters/laravel.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './core/types.js';
+export * from './core/validation.js';
+export * from './core/plan.js';
+export * from './core/execution.js';
+export * from './core/redact.js';
+export * from './adapters/laravel.js';

package/dist/providers/cloudflared.d.ts

@@ -0,0 +1,6 @@
+export interface ProcessResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function runCloudflared(args: string[], timeoutMs?: number): Promise<ProcessResult>;

package/dist/providers/cloudflared.js

@@ -0,0 +1,5 @@
+import { spawn } from 'node:child_process';
+import { redact } from '../core/redact.js';
+export function runCloudflared(args, timeoutMs = 120_000) {
+    return new Promise(resolve => { const child = spawn('cloudflared', args, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = '', stderr = ''; const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs); child.stdout.on('data', (d) => stdout += d); child.stderr.on('data', (d) => stderr += d); child.on('error', (e) => { clearTimeout(timer); resolve({ code: 127, stdout: '', stderr: redact(e.message) }); }); child.on('close', (code) => { clearTimeout(timer); resolve({ code: code ?? 1, stdout: redact(stdout), stderr: redact(stderr) }); }); });
+}

package/dist/ui/server.d.ts

@@ -0,0 +1,2 @@
+import { type Server } from 'node:http';
+export declare function createServer(): Server;

package/dist/ui/server.js

@@ -0,0 +1,38 @@
+import { createServer as httpServer } from 'node:http';
+import crypto from 'node:crypto';
+import { createTunnelPlan } from '../core/plan.js';
+import { createLaravelPlan } from '../adapters/laravel.js';
+import { executeTunnelPlan } from '../core/execution.js';
+export function createServer() {
+    const token = crypto.randomUUID();
+    return httpServer(async (req, res) => {
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.method === 'GET' && req.url === '/') {
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.end(html);
+            return;
+        }
+        if (req.method === 'GET' && req.url === '/api/session')
+            return json(res, { confirmationToken: token });
+        if (req.method === 'POST' && ['/api/plan', '/api/validate', '/api/execute'].includes(req.url ?? '')) {
+            if (req.url === '/api/execute' && req.headers['x-confirmation-token'] !== token)
+                return json(res, { ok: false, issues: [{ code: 'UI_CONFIRMATION_TOKEN_INVALID', reason: 'The UI confirmation token is missing or invalid.', fix: 'Reload the local UI and confirm from the same browser session.' }] }, 403);
+            try {
+                const body = JSON.parse(await readBody(req));
+                const config = body.config;
+                const plan = config.profile === 'laravel' ? createLaravelPlan(config) : createTunnelPlan(config);
+                if (req.url === '/api/execute')
+                    return json(res, await executeTunnelPlan(plan, { confirmed: body.confirmed ?? [], dryRun: body.dryRun ?? false }));
+                return json(res, { valid: plan.valid, issues: plan.issues, plan });
+            }
+            catch {
+                return json(res, { ok: false, issues: [{ code: 'UI_INVALID_JSON', reason: 'Request body is not valid JSON.', fix: 'Submit the wizard form again.' }] }, 400);
+            }
+        }
+        res.statusCode = 404;
+        res.end('Not found');
+    });
+}
+function readBody(req) { return new Promise(resolve => { let data = ''; req.on('data', (chunk) => data += chunk); req.on('end', () => resolve(data)); }); }
+function json(res, value, status = 200) { res.statusCode = status; res.setHeader('Content-Type', 'application/json; charset=utf-8'); res.end(JSON.stringify(value)); }
+const html = `<!doctype html><html lang="en"><meta name="viewport" content="width=device-width"><title>Cloudflare Tunnel Kit</title><style>body{font:16px system-ui;max-width:720px;margin:40px auto;padding:0 20px;background:#f6f7fb;color:#18202a}main{background:white;padding:28px;border-radius:16px;box-shadow:0 8px 30px #0001}label{display:block;margin:14px 0 6px}input,select,button{font:inherit;padding:10px;border:1px solid #ccd3df;border-radius:8px;width:100%;box-sizing:border-box}button{margin-top:20px;background:#2457d6;color:white;cursor:pointer}pre{white-space:pre-wrap;background:#f1f3f7;padding:12px;border-radius:8px}.ok{color:#087443}.error{color:#a21b1b}</style><main><h1>Cloudflare Tunnel Kit</h1><p>Validate first. Review the plan. Confirm before running.</p><label>Profile</label><select id="profile"><option>custom</option><option>laravel</option></select><label>Local URL</label><input id="url" value="http://127.0.0.1:8000"><label>Tunnel name (named tunnel only)</label><input id="name" placeholder="my-project"><button id="check">Validate plan</button><button id="run" hidden>Confirm and execute</button><button id="copy" hidden>Copy AI help prompt</button><pre id="result">No plan yet.</pre></main><script>let plan,token;const $=id=>document.getElementById(id);fetch('/api/session').then(r=>r.json()).then(x=>token=x.confirmationToken);$('check').onclick=async()=>{const config={profile:$('profile').value,operation:$('name').value?'create':'quick',localUrl:$('url').value,tunnelName:$('name').value||undefined};const r=await fetch('/api/plan',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({config})});const x=await r.json();plan=x.plan;$('result').textContent=JSON.stringify({summary:plan?.summary,issues:x.issues,argv:plan?.argv,confirmations:plan?.confirmations},null,2);$('run').hidden=!x.valid;$('copy').hidden=x.valid;};$('run').onclick=async()=>{const r=await fetch('/api/execute',{method:'POST',headers:{'content-type':'application/json','x-confirmation-token':token},body:JSON.stringify({config:plan.config,confirmed:plan.confirmations})});$('result').textContent=JSON.stringify(await r.json(),null,2);};$('copy').onclick=()=>navigator.clipboard.writeText('I am configuring cloudflare-tunnel-kit. Here is the redacted diagnostic:\n'+$('result').textContent);</script>`;

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "cloudflare-tunnel-kit",
+  "version": "0.1.0",
+  "description": "Safe, reusable Cloudflare Tunnel setup for custom and Laravel projects.",
+  "type": "module",
+  "bin": { "cf-tunnel": "dist/cli/main.js" },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": { "build": "tsc", "test": "npm run build && node --test tests/**/*.test.js", "dev": "tsc --watch" },
+  "devDependencies": { "typescript": "^5.7.2" },
+  "engines": { "node": ">=20" },
+  "license": "MIT"
+}