cloudflare-tunnel-kit 0.1.0 → 0.1.2

package/README.md

@@ -1,84 +1,78 @@
 # 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.
+An open-source toolkit for creating and integrating Cloudflare Tunnels through two simple interfaces: a command-line wizard and a local live UI. It replaces scattered shell scripts and Makefile targets with a validated, reviewable, and confirmation-based workflow.
 
 ## Current version
 
-`0.1.0` là bản MVP hiện có:
+`0.1.0` is the current MVP and includes:
 
-- 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.
+- A reusable TypeScript API for validation, plan generation, execution, and redaction.
+- The `cf-tunnel` CLI with `init`, `create`, `quick`, `start`, `stop`, `status`, `doctor`, and `ui` commands.
+- `custom` and `laravel` project profiles.
+- Quick Tunnel and named-tunnel command generation.
+- URL, hostname, tunnel-name, and project-path validation.
+- Dry-run mode, structured errors, remediation guidance, and copyable AI help prompts.
+- A lightweight localhost UI with live plan preview and confirmation-token protection.
+- Laravel detection and `APP_URL` proposal/diff with explicit confirmation.
 
-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.
+Laravel `.env` changes are never written silently. The current MVP presents the proposed diff and requires confirmation; automatic file mutation is intentionally not enabled yet.
 
-## Ý tưởng và nguyên tắc
+## Design principles
 
-Flow luôn là: `input -> detect -> validate -> preview plan -> confirm -> execute -> summary`.
+The workflow is always:
 
-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.
+```text
+input -> detect -> validate -> preview plan -> confirm -> execute -> summary
+```
 
-## Yêu cầu
+The toolkit does not concatenate user input into shell commands, print secrets to logs, overwrite configuration silently, or send diagnostics to an external service.
 
-- 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.
+## Requirements
 
-## Cài đặt
+- Node.js 20 or newer.
+- `cloudflared` available in `PATH` when starting a real tunnel.
+- Appropriate Cloudflare permissions for named tunnels.
 
-Khi package được phát hành:
+## Installation
+
+Install the package after it is published:
 
 ```bash
 npm install --save-dev cloudflare-tunnel-kit
 ```
 
-Trong source checkout:
+For a source checkout:
 
 ```bash
 npm install
 npm run build
-node dist/cli/main.js --help
+node ./dist/cli/main.js --help
 ```
 
-## Makefile shortcuts
+## CLI usage
 
-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:
+Check the local environment:
 
 ```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.
+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.
 
-Quick tunnel, chỉ validate/preview:
+Preview a Quick Tunnel without starting `cloudflared`:
 
 ```bash
 cf-tunnel quick --url http://127.0.0.1:8000 --dry-run
 ```
 
-Named tunnel sau khi review plan:
+Preview a named tunnel:
 
 ```bash
-cf-tunnel create --url http://127.0.0.1:8000 --name my-project --hostname tunnel.example.com
+cf-tunnel create \
+  --url http://127.0.0.1:8000 \
+  --name my-project \
+  --hostname tunnel.example.com \
+  --dry-run
 ```
 
 Lifecycle commands:
@@ -87,22 +81,42 @@ Lifecycle commands:
 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`.
+`--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
 ```
 
-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.
+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 UI binds to loopback by default and does not send the copied prompt anywhere.
 
 ## Custom profile
 
-Custom profile không đoán framework:
+The custom profile makes no framework assumptions:
 
 ```bash
 cf-tunnel quick --profile custom --url http://127.0.0.1:3000 --dry-run
@@ -111,57 +125,104 @@ cf-tunnel create --profile custom --url http://127.0.0.1:8000 --name billing --d
 
 ## 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.
+The Laravel adapter checks for `artisan` and Laravel evidence in `composer.json`. It can propose mappings such as `APP_URL`, `ASSET_URL`, and optional Reverb URLs.
+
+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 --profile laravel --url http://127.0.0.1:8000 --name law-firm --dry-run
+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';
+import {
+  validateTunnelConfig,
+  createTunnelPlan,
+  executeTunnelPlan,
+} from 'cloudflare-tunnel-kit';
+
+const config = {
+  profile: 'custom',
+  operation: 'quick',
+  localUrl: 'http://127.0.0.1:8000',
+};
 
-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);
+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.
+Plans are serializable and can be displayed inside another system. Execute only validated plans and provide the required confirmation groups.
 
 ## 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`.
+Every error includes a stable `code`, optional `field`, `reason`, and `fix`. Common codes include:
+
+- `INPUT_INVALID_URL`: the local URL is not HTTP/HTTPS.
+- `INPUT_INVALID_HOSTNAME`: the hostname is not valid.
+- `INPUT_INVALID_TUNNEL_NAME`: the tunnel name is unsafe.
+- `PATH_OUTSIDE_PROJECT`: the config path escapes the project root.
+- `CONFIRMATION_REQUIRED`: a mutation has not been confirmed.
+- `PROCESS_FAILED`: `cloudflared` failed or could not be started.
 
-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.
+Review the redacted prompt before pasting it into an external AI service.
 
 ## 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.
+- The UI binds to `127.0.0.1` by default.
+- Child processes use argv arrays with shell execution disabled.
+- Secret-looking keys/values, bearer tokens, and credential paths are redacted.
+- File paths are checked against the project root.
+- Dry-run does not start `cloudflared`.
+- Configuration overwrite and Laravel `.env` changes require a visible plan and confirmation.
+- No telemetry or diagnostics are sent externally.
+
+This toolkit does not replace review of Cloudflare account permissions, DNS, access policies, or organizational secret management.
+
+## Publishing to npm
+
+After logging in to npm and completing any required 2FA verification:
 
-Tool không thay thế việc review Cloudflare account permissions, DNS, access policy hoặc secret management của tổ chức.
+```bash
+npm install
+npm run build
+npm test
+npm pack --dry-run
+npm publish
+```
+
+Increase the version before publishing a new release:
 
-## Phát triển
+```bash
+npm version patch
+npm publish
+```
+
+An already-published `name@version` cannot be published again. See the [npm publish documentation](https://docs.npmjs.com/cli/commands/npm-publish/).
+
+## Development
 
 ```bash
+npm install
 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.
+Tests use Node built-ins and temporary fixtures; no Cloudflare account is required. Add tests before introducing new behavior, do not place real secrets in fixtures, and keep remediation messages actionable.
 
 ## License
 
-MIT. Xem [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

package/dist/app/paths.d.ts

@@ -0,0 +1,11 @@
+export interface AppPaths {
+    dataDir: string;
+    database: string;
+    projectsDir: string;
+    backupsDir: string;
+}
+export declare function resolveAppPaths(input?: {
+    platform?: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+}): AppPaths;

package/dist/app/paths.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+export function resolveAppPaths(input = {}) {
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    const home = input.home ?? env.HOME ?? env.USERPROFILE ?? '';
+    if (!home && platform !== 'win32')
+        throw new Error('Unable to determine the user home directory.');
+    const paths = platform === 'win32' ? path.win32 : path;
+    const root = platform === 'darwin'
+        ? paths.join(home, 'Library', 'Application Support')
+        : platform === 'win32'
+            ? (env.LOCALAPPDATA ?? paths.join(home, 'AppData', 'Local'))
+            : (env.XDG_DATA_HOME ?? paths.join(home, '.local', 'share'));
+    if (!root)
+        throw new Error('Unable to determine the local application-data directory.');
+    const dataDir = paths.join(root, 'cloudflare-tunnel-kit');
+    return {
+        dataDir,
+        database: paths.join(dataDir, 'state.db'),
+        projectsDir: paths.join(dataDir, 'projects'),
+        backupsDir: paths.join(dataDir, 'backups'),
+    };
+}

package/dist/core/errors.d.ts

@@ -1,5 +1,13 @@
-import type { ValidationIssue } from './types.js';
+import type { TunnelError, ValidationIssue } from './types.js';
 export declare class TunnelKitError extends Error {
     readonly issue: ValidationIssue;
     constructor(issue: ValidationIssue);
 }
+interface ErrorContext {
+    hostname?: string;
+    completedEffects?: string[];
+    exitCode?: number;
+    stderr?: string;
+}
+export declare function tunnelError(code: string, context?: ErrorContext): TunnelError;
+export {};

package/dist/core/errors.js

@@ -1,3 +1,4 @@
+import { redact } from './redact.js';
 export class TunnelKitError extends Error {
     issue;
     constructor(issue) {
@@ -6,3 +7,56 @@ export class TunnelKitError extends Error {
         this.name = 'TunnelKitError';
     }
 }
+const definitions = {
+    AUTH_STALE: {
+        title: 'Cloudflare login has expired',
+        summary: () => 'The saved Cloudflare account certificate is no longer accepted.',
+        likelyCause: 'The account permissions changed, the login was revoked, or the certificate is stale.',
+        remediationSteps: ['Sign in to Cloudflare again.', 'Retry the interrupted workflow step.'],
+        availableActions: ['sign-in-again', 'retry', 'copy-diagnostics'],
+        retryFromStep: 'authentication',
+    },
+    CLOUDFLARED_OUTPUT_UNRECOGNIZED: {
+        title: 'Cloudflare output was not recognized',
+        summary: () => 'cloudflared completed, but its output did not contain expected resource information.',
+        likelyCause: 'The installed cloudflared version may use an unsupported output format.',
+        remediationSteps: ['Check the installed cloudflared version.', 'Copy the redacted diagnostics when reporting this compatibility issue.'],
+        availableActions: ['retry', 'copy-diagnostics'],
+    },
+    DNS_PERMISSION_DENIED: {
+        title: 'DNS permission denied',
+        summary: context => `Cloudflare did not allow this account to create a DNS record for ${context.hostname ?? 'the requested hostname'}.`,
+        likelyCause: 'The selected account or zone does not have permission to create DNS records for this hostname.',
+        remediationSteps: [
+            'Sign in again with an account that manages the requested domain.',
+            'Select the correct zone during Cloudflare login.',
+            'Retry the DNS step after access is corrected.',
+        ],
+        availableActions: ['sign-in-again', 'retry', 'copy-diagnostics'],
+        retryFromStep: 'dns-route',
+    },
+    CLOUDFLARED_COMMAND_FAILED: {
+        title: 'Cloudflare command failed',
+        summary: () => 'cloudflared exited before the requested operation completed.',
+        likelyCause: 'The command returned an error that Cloudflare Tunnel Kit does not recognize yet.',
+        remediationSteps: ['Review the redacted diagnostics.', 'Retry after correcting the reported Cloudflare or local environment issue.'],
+        availableActions: ['retry', 'copy-diagnostics'],
+    },
+};
+export function tunnelError(code, context = {}) {
+    const definition = definitions[code] ?? definitions.CLOUDFLARED_COMMAND_FAILED;
+    const safeDiagnostics = context.exitCode === undefined && context.stderr === undefined
+        ? undefined
+        : { exitCode: context.exitCode, stderr: redact(context.stderr ?? '') };
+    return {
+        code: definitions[code] ? code : 'CLOUDFLARED_COMMAND_FAILED',
+        title: definition.title,
+        summary: definition.summary(context),
+        likelyCause: definition.likelyCause,
+        completedEffects: context.completedEffects ?? [],
+        remediationSteps: definition.remediationSteps,
+        availableActions: definition.availableActions,
+        safeDiagnostics,
+        retryFromStep: definition.retryFromStep,
+    };
+}

package/dist/core/origin-check.d.ts

@@ -0,0 +1,18 @@
+export interface OriginIssue {
+    code: string;
+    reason: string;
+    fix: string;
+}
+export type OriginCheckResult = {
+    reachable: true;
+    status: number;
+    warning?: OriginIssue;
+} | {
+    reachable: false;
+    error: OriginIssue;
+};
+export declare function checkOrigin(localUrl: string, options?: {
+    timeoutMs?: number;
+    maxRedirects?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<OriginCheckResult>;

package/dist/core/origin-check.js

@@ -0,0 +1,34 @@
+function issue(code, reason, fix) { return { code, reason, fix }; }
+export async function checkOrigin(localUrl, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 3_000;
+    const maxRedirects = options.maxRedirects ?? 5;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    let current = localUrl;
+    try {
+        for (let redirects = 0; redirects <= maxRedirects; redirects += 1) {
+            const response = await fetchImpl(current, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+            if (response.status >= 300 && response.status < 400 && response.headers.get('location')) {
+                if (redirects === maxRedirects)
+                    return { reachable: false, error: issue('ORIGIN_REDIRECT_LOOP', 'The local origin exceeded the redirect limit.', 'Fix the local redirect configuration before creating the tunnel.') };
+                current = new URL(response.headers.get('location'), current).toString();
+                continue;
+            }
+            if (response.status >= 400 && response.status < 500)
+                return { reachable: true, status: response.status, warning: issue('ORIGIN_HTTP_CLIENT_ERROR', `The local origin responded with HTTP ${response.status}.`, 'The service is reachable; verify that the requested path is expected to return this status.') };
+            if (response.status >= 500)
+                return { reachable: true, status: response.status, warning: issue('ORIGIN_HTTP_SERVER_ERROR', `The local origin responded with HTTP ${response.status}.`, 'Fix the local application error or continue only if this response is expected.') };
+            return { reachable: true, status: response.status };
+        }
+        return { reachable: false, error: issue('ORIGIN_REDIRECT_LOOP', 'The local origin exceeded the redirect limit.', 'Fix the local redirect configuration before creating the tunnel.') };
+    }
+    catch (error) {
+        const message = error instanceof Error ? `${error.message} ${String(error.cause?.code ?? '')}` : String(error);
+        if (/ECONNREFUSED|fetch failed/i.test(message))
+            return { reachable: false, error: issue('ORIGIN_CONNECTION_REFUSED', 'The local service refused the connection.', 'Start the local application and verify its host and port.') };
+        if (/TimeoutError|timed out|AbortError/i.test(message))
+            return { reachable: false, error: issue('ORIGIN_TIMEOUT', 'The local service did not respond before the timeout.', 'Verify the local URL and that the application is responsive.') };
+        if (/certificate|TLS|SSL/i.test(message))
+            return { reachable: false, error: issue('ORIGIN_TLS_INVALID', 'The local HTTPS certificate could not be verified.', 'Use a trusted local certificate or explicitly choose the advanced insecure-origin option.') };
+        return { reachable: false, error: issue('ORIGIN_UNREACHABLE', 'The local service could not be reached.', 'Verify the local URL and inspect the application logs.') };
+    }
+}

package/dist/core/redact.d.ts

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

package/dist/core/redact.js

@@ -4,6 +4,18 @@ export function redact(value, key) {
         return '[REDACTED]';
     return value.replace(/(Bearer\s+)[^\s]+/gi, '$1[REDACTED]').replace(/([A-Za-z0-9_-]{24,})/g, '[REDACTED]');
 }
+export function redactValue(value, key) {
+    if (key && secretKey.test(key))
+        return '[REDACTED]';
+    if (typeof value === 'string')
+        return redact(value, key);
+    if (Array.isArray(value))
+        return value.map(item => redactValue(item));
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redactValue(entryValue, entryKey)]));
+    }
+    return value;
+}
 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

@@ -1,5 +1,30 @@
 export type Profile = 'custom' | 'laravel';
 export type Operation = 'quick' | 'create' | 'start' | 'stop' | 'status';
+export type TunnelKind = 'quick' | 'named';
+export type WorkflowStepState = 'pending' | 'running' | 'succeeded' | 'warning' | 'failed' | 'skipped' | 'cancelled';
+export type NamedStep = 'environment' | 'input' | 'origin' | 'filesystem' | 'git-safety' | 'authentication' | 'account-access' | 'tunnel' | 'configuration' | 'ingress-validation' | 'dns-route' | 'connector' | 'cloudflare-health' | 'public-health';
+export type RecoveryAction = 'retry' | 'sign-in-again' | 'change-input' | 'open-dashboard' | 'copy-diagnostics' | 'stop' | 'force-stop';
+export interface TunnelError {
+    code: string;
+    title: string;
+    summary: string;
+    likelyCause: string;
+    completedEffects: string[];
+    remediationSteps: string[];
+    availableActions: RecoveryAction[];
+    safeDiagnostics?: Record<string, unknown>;
+    retryFromStep?: NamedStep;
+}
+export interface WorkflowStepResult {
+    name: string;
+    state: WorkflowStepState;
+    attempts: number;
+    startedAt?: string;
+    finishedAt?: string;
+    effects: string[];
+    error?: TunnelError;
+}
+export declare function stepState(value: string): WorkflowStepState;
 export interface TunnelConfig {
     profile: Profile;
     operation: Operation;

package/dist/core/types.js

@@ -1 +1,6 @@
-export {};
+export function stepState(value) {
+    const values = ['pending', 'running', 'succeeded', 'warning', 'failed', 'skipped', 'cancelled'];
+    if (!values.includes(value))
+        throw new Error(`Unknown workflow step state: ${value}`);
+    return value;
+}

package/dist/core/validation.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { realpathSync } from 'node:fs';
+import { domainToASCII } from 'node:url';
 function issue(code, reason, fix, field) { return { code, reason, fix, field }; }
 function inside(root, candidate) {
     try {
@@ -26,13 +27,17 @@ export function validateTunnelConfig(input) {
         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.operation === 'create' && !input.hostname)
+        issues.push(issue('INPUT_HOSTNAME_REQUIRED', 'Named tunnels require a public hostname.', 'Use a hostname from a domain already managed by Cloudflare, such as dev.example.com.', 'hostname'));
     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 asciiHostname = input.hostname ? domainToASCII(input.hostname.trim().toLowerCase()) : '';
+    if (input.hostname && (!asciiHostname || asciiHostname.includes('*') || !/^(?=.{1,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])$/i.test(asciiHostname))) {
+        issues.push(issue('INPUT_INVALID_HOSTNAME', 'Hostname is not a valid public DNS hostname.', 'Use a fully qualified hostname such as tunnel.example.com, without a scheme, path, wildcard, or IP address.', '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 };
+    const normalized = { ...input, localUrl: url?.toString().replace(/\/$/, '') ?? input.localUrl, hostname: asciiHostname || input.hostname, projectRoot: root };
     return { ok: issues.length === 0, issues, normalized: issues.length === 0 ? normalized : undefined };
 }

package/dist/index.d.ts

@@ -1,6 +1,15 @@
 export * from './core/types.js';
+export * from './core/errors.js';
 export * from './core/validation.js';
+export * from './core/origin-check.js';
 export * from './core/plan.js';
 export * from './core/execution.js';
 export * from './core/redact.js';
 export * from './adapters/laravel.js';
+export * from './app/paths.js';
+export * from './persistence/database.js';
+export * from './persistence/store.js';
+export * from './providers/command-runner.js';
+export * from './providers/cloudflared.js';
+export * from './providers/git-safety.js';
+export * from './providers/process-supervisor.js';

package/dist/index.js

@@ -1,6 +1,15 @@
 export * from './core/types.js';
+export * from './core/errors.js';
 export * from './core/validation.js';
+export * from './core/origin-check.js';
 export * from './core/plan.js';
 export * from './core/execution.js';
 export * from './core/redact.js';
 export * from './adapters/laravel.js';
+export * from './app/paths.js';
+export * from './persistence/database.js';
+export * from './persistence/store.js';
+export * from './providers/command-runner.js';
+export * from './providers/cloudflared.js';
+export * from './providers/git-safety.js';
+export * from './providers/process-supervisor.js';

package/dist/persistence/database.d.ts

@@ -0,0 +1,2 @@
+import Database from 'better-sqlite3';
+export declare function openStateDatabase(filename: string): Database.Database;

package/dist/persistence/database.js

@@ -0,0 +1,32 @@
+import Database from 'better-sqlite3';
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { migrations } from './migrations.js';
+export function openStateDatabase(filename) {
+    mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+    const existed = existsSync(filename);
+    const db = new Database(filename);
+    db.pragma('foreign_keys = ON');
+    db.pragma('journal_mode = WAL');
+    db.pragma('busy_timeout = 3000');
+    db.exec('CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)');
+    const applied = new Set(db.prepare('SELECT version FROM schema_migrations').all().map(row => row.version));
+    const pending = migrations.filter(migration => !applied.has(migration.version));
+    if (existed && pending.length > 0)
+        copyFileSync(filename, `${filename}.pre-migration-backup`);
+    for (const migration of pending) {
+        const apply = db.transaction(() => {
+            db.exec(migration.sql);
+            db.prepare('INSERT INTO schema_migrations(version, applied_at) VALUES (?, ?)')
+                .run(migration.version, new Date().toISOString());
+        });
+        try {
+            apply();
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    return db;
+}

package/dist/persistence/migrations.d.ts

@@ -0,0 +1,5 @@
+export interface Migration {
+    version: number;
+    sql: string;
+}
+export declare const migrations: Migration[];

package/dist/persistence/migrations.js

@@ -0,0 +1,78 @@
+export const migrations = [{
+        version: 1,
+        sql: `
+    CREATE TABLE projects (
+      id TEXT PRIMARY KEY,
+      display_name TEXT NOT NULL,
+      path TEXT NOT NULL UNIQUE,
+      profile TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE tunnels (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL,
+      name TEXT,
+      uuid TEXT UNIQUE,
+      hostname TEXT,
+      local_url TEXT,
+      config_path TEXT,
+      credentials_path TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE workflow_runs (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL,
+      state TEXT NOT NULL,
+      current_step TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      finished_at TEXT
+    );
+    CREATE TABLE workflow_steps (
+      id TEXT PRIMARY KEY,
+      workflow_run_id TEXT NOT NULL REFERENCES workflow_runs(id) ON DELETE CASCADE,
+      name TEXT NOT NULL,
+      state TEXT NOT NULL,
+      attempts INTEGER NOT NULL,
+      effects_json TEXT NOT NULL,
+      safe_result_json TEXT NOT NULL,
+      error_json TEXT,
+      started_at TEXT,
+      finished_at TEXT,
+      UNIQUE(workflow_run_id, name)
+    );
+    CREATE TABLE process_sessions (
+      id TEXT PRIMARY KEY,
+      tunnel_id TEXT REFERENCES tunnels(id) ON DELETE CASCADE,
+      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      process_key TEXT NOT NULL,
+      pid INTEGER,
+      executable TEXT,
+      argv_fingerprint TEXT,
+      state TEXT NOT NULL,
+      ephemeral_url TEXT,
+      ephemeral_url_expired INTEGER NOT NULL DEFAULT 0,
+      started_at TEXT NOT NULL,
+      stopped_at TEXT
+    );
+    CREATE TABLE events (
+      id TEXT PRIMARY KEY,
+      project_id TEXT REFERENCES projects(id) ON DELETE CASCADE,
+      workflow_run_id TEXT REFERENCES workflow_runs(id) ON DELETE CASCADE,
+      severity TEXT NOT NULL,
+      message TEXT NOT NULL,
+      safe_data_json TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE installations (
+      id TEXT PRIMARY KEY,
+      component TEXT NOT NULL UNIQUE,
+      version TEXT NOT NULL,
+      checked_at TEXT NOT NULL
+    );
+  `,
+    }];

package/dist/persistence/store.d.ts

@@ -0,0 +1,51 @@
+import type Database from 'better-sqlite3';
+import type { Profile, TunnelKind, WorkflowStepState } from '../core/types.js';
+export interface SavedProject {
+    id: string;
+    displayName: string;
+    path: string;
+    profile: Profile;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SavedWorkflow {
+    id: string;
+    projectId: string;
+    kind: TunnelKind;
+    state: WorkflowStepState;
+    currentStep?: string;
+    steps: SavedWorkflowStep[];
+}
+export interface SavedWorkflowStep {
+    name: string;
+    state: WorkflowStepState;
+    attempts: number;
+    effects: string[];
+    safeResult: unknown;
+    error?: unknown;
+}
+export declare class StateStore {
+    private readonly db;
+    constructor(db: Database.Database);
+    saveProject(input: {
+        displayName: string;
+        path: string;
+        profile: Profile;
+    }): SavedProject;
+    listProjects(): SavedProject[];
+    createWorkflow(input: {
+        projectId: string;
+        kind: TunnelKind;
+    }): {
+        id: string;
+    };
+    recordStep(runId: string, input: {
+        name: string;
+        state: WorkflowStepState;
+        attempts: number;
+        effects: string[];
+        safeResult: unknown;
+        error?: unknown;
+    }): void;
+    getWorkflow(id: string): SavedWorkflow;
+}

package/dist/persistence/store.js

@@ -0,0 +1,59 @@
+import crypto from 'node:crypto';
+import { redactValue } from '../core/redact.js';
+function safeJson(value) { return JSON.stringify(redactValue(value)); }
+export class StateStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    saveProject(input) {
+        const existing = this.db.prepare('SELECT id, created_at FROM projects WHERE path = ?').get(input.path);
+        const now = new Date().toISOString();
+        const id = existing?.id ?? crypto.randomUUID();
+        const createdAt = existing?.created_at ?? now;
+        this.db.prepare(`
+      INSERT INTO projects(id, display_name, path, profile, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET display_name=excluded.display_name, profile=excluded.profile, updated_at=excluded.updated_at
+    `).run(id, input.displayName, input.path, input.profile, createdAt, now);
+        return { id, ...input, createdAt, updatedAt: now };
+    }
+    listProjects() {
+        const rows = this.db.prepare('SELECT id, display_name, path, profile, created_at, updated_at FROM projects ORDER BY updated_at DESC').all();
+        return rows.map(row => ({ id: row.id, displayName: row.display_name, path: row.path, profile: row.profile, createdAt: row.created_at, updatedAt: row.updated_at }));
+    }
+    createWorkflow(input) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        this.db.prepare('INSERT INTO workflow_runs(id, project_id, kind, state, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)')
+            .run(id, input.projectId, input.kind, 'pending', now, now);
+        return { id };
+    }
+    recordStep(runId, input) {
+        const now = new Date().toISOString();
+        this.db.prepare(`
+      INSERT INTO workflow_steps(id, workflow_run_id, name, state, attempts, effects_json, safe_result_json, error_json, started_at, finished_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(workflow_run_id, name) DO UPDATE SET
+        state=excluded.state, attempts=excluded.attempts, effects_json=excluded.effects_json,
+        safe_result_json=excluded.safe_result_json, error_json=excluded.error_json,
+        started_at=COALESCE(workflow_steps.started_at, excluded.started_at), finished_at=excluded.finished_at
+    `).run(crypto.randomUUID(), runId, input.name, input.state, input.attempts, safeJson(input.effects), safeJson(input.safeResult), input.error === undefined ? null : safeJson(input.error), now, ['succeeded', 'warning', 'failed', 'cancelled'].includes(input.state) ? now : null);
+        this.db.prepare('UPDATE workflow_runs SET state=?, current_step=?, updated_at=? WHERE id=?')
+            .run(input.state === 'failed' ? 'failed' : input.state === 'cancelled' ? 'cancelled' : 'running', input.name, now, runId);
+    }
+    getWorkflow(id) {
+        const run = this.db.prepare('SELECT id, project_id, kind, state, current_step FROM workflow_runs WHERE id = ?').get(id);
+        if (!run)
+            throw new Error(`Workflow not found: ${id}`);
+        const rows = this.db.prepare('SELECT name, state, attempts, effects_json, safe_result_json, error_json FROM workflow_steps WHERE workflow_run_id = ? ORDER BY rowid').all(id);
+        return {
+            id: run.id, projectId: run.project_id, kind: run.kind, state: run.state, currentStep: run.current_step ?? undefined,
+            steps: rows.map(row => ({
+                name: row.name, state: row.state, attempts: row.attempts,
+                effects: JSON.parse(row.effects_json), safeResult: JSON.parse(row.safe_result_json),
+                error: row.error_json ? JSON.parse(row.error_json) : undefined,
+            })),
+        };
+    }
+}

package/dist/providers/cloudflared.d.ts

@@ -1,6 +1,51 @@
-export interface ProcessResult {
+import type { TunnelError } from '../core/types.js';
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: TunnelError;
+};
+export interface TunnelObservation {
+    uuid: string;
+    name: string;
+    createdAt?: string;
+    connections: number;
+}
+export declare class CloudflaredAdapter {
+    private readonly executable;
+    private readonly baseArgs;
+    private readonly env;
+    constructor(options?: {
+        executable?: string;
+        baseArgs?: string[];
+        env?: NodeJS.ProcessEnv;
+    });
+    private command;
+    private failure;
+    version(): Promise<Result<{
+        version: string;
+    }>>;
+    login(): Promise<Result<{
+        completed: true;
+    }>>;
+    listTunnels(): Promise<Result<TunnelObservation[]>>;
+    createTunnel(name: string): Promise<Result<{
+        uuid: string;
+        credentialsFile: string;
+    }>>;
+    validateIngress(configPath: string): Promise<Result<{
+        valid: true;
+    }>>;
+    routeDns(tunnel: string, hostname: string): Promise<Result<{
+        hostname: string;
+    }>>;
+    info(tunnel: string): Promise<Result<{
+        connectorState: 'healthy' | 'degraded' | 'disconnected' | 'unknown';
+    }>>;
+}
+export declare function runCloudflared(args: string[], timeoutMs?: number): Promise<{
     code: number;
     stdout: string;
     stderr: string;
-}
-export declare function runCloudflared(args: string[], timeoutMs?: number): Promise<ProcessResult>;
+}>;

package/dist/providers/cloudflared.js

@@ -1,5 +1,79 @@
-import { spawn } from 'node:child_process';
 import { redact } from '../core/redact.js';
+import { tunnelError } from '../core/errors.js';
+import { runCommand } from './command-runner.js';
+export class CloudflaredAdapter {
+    executable;
+    baseArgs;
+    env;
+    constructor(options = {}) {
+        this.executable = options.executable ?? 'cloudflared';
+        this.baseArgs = options.baseArgs ?? [];
+        this.env = options.env ?? process.env;
+    }
+    command(args, timeoutMs = 30_000) {
+        return runCommand({ executable: this.executable, args: [...this.baseArgs, ...args], env: this.env, timeoutMs });
+    }
+    failure(result) {
+        const stderr = redact(result.stderr);
+        if (/authenticate|origin certificate/i.test(result.stderr) && /invalid|revoked|expired/i.test(result.stderr)) {
+            return { ok: false, error: tunnelError('AUTH_STALE', { exitCode: result.exitCode, stderr }) };
+        }
+        return { ok: false, error: tunnelError('CLOUDFLARED_COMMAND_FAILED', { exitCode: result.exitCode, stderr }) };
+    }
+    async version() {
+        const result = await this.command(['--version']);
+        if (result.exitCode !== 0)
+            return this.failure(result);
+        const match = result.stdout.match(/cloudflared version\s+([^\s]+)/i);
+        return match ? { ok: true, value: { version: match[1] } } : { ok: false, error: tunnelError('CLOUDFLARED_OUTPUT_UNRECOGNIZED', { stderr: result.stdout }) };
+    }
+    async login() {
+        const result = await this.command(['tunnel', 'login'], 180_000);
+        return result.exitCode === 0 ? { ok: true, value: { completed: true } } : this.failure(result);
+    }
+    async listTunnels() {
+        const result = await this.command(['tunnel', 'list', '--output', 'json']);
+        if (result.exitCode !== 0)
+            return this.failure(result);
+        try {
+            const rows = JSON.parse(result.stdout);
+            return { ok: true, value: rows.map(row => ({ uuid: row.id ?? row.uuid ?? '', name: row.name, createdAt: row.createdAt, connections: row.connections?.length ?? 0 })).filter(row => row.uuid) };
+        }
+        catch {
+            return { ok: false, error: tunnelError('CLOUDFLARED_OUTPUT_UNRECOGNIZED', { stderr: result.stdout }) };
+        }
+    }
+    async createTunnel(name) {
+        const result = await this.command(['tunnel', 'create', name]);
+        if (result.exitCode !== 0)
+            return this.failure(result);
+        const uuid = result.stdout.match(/[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/i)?.[0];
+        const credentialsFile = result.stdout.match(/(?:written to|credentials[^\n]*?)\s+([^\s]+\.json)/i)?.[1];
+        if (!uuid || !credentialsFile)
+            return { ok: false, error: tunnelError('CLOUDFLARED_OUTPUT_UNRECOGNIZED', { stderr: result.stdout }) };
+        return { ok: true, value: { uuid, credentialsFile } };
+    }
+    async validateIngress(configPath) {
+        const result = await this.command(['tunnel', 'ingress', 'validate', '--config', configPath]);
+        return result.exitCode === 0 ? { ok: true, value: { valid: true } } : this.failure(result);
+    }
+    async routeDns(tunnel, hostname) {
+        const result = await this.command(['tunnel', 'route', 'dns', tunnel, hostname]);
+        return result.exitCode === 0 ? { ok: true, value: { hostname } } : this.failure(result);
+    }
+    async info(tunnel) {
+        const result = await this.command(['tunnel', 'info', tunnel, '--output', 'json']);
+        if (result.exitCode !== 0)
+            return this.failure(result);
+        try {
+            const value = JSON.parse(result.stdout);
+            return { ok: true, value: { connectorState: value.connections?.length ? 'healthy' : 'disconnected' } };
+        }
+        catch {
+            return { ok: false, error: tunnelError('CLOUDFLARED_OUTPUT_UNRECOGNIZED', { stderr: result.stdout }) };
+        }
+    }
+}
 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) }); }); });
+    return runCommand({ executable: 'cloudflared', args, timeoutMs }).then(result => ({ code: result.exitCode, stdout: redact(result.stdout), stderr: redact(result.stderr) }));
 }

package/dist/providers/command-runner.d.ts

@@ -0,0 +1,16 @@
+export interface CommandResult {
+    exitCode: number;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export declare function runCommand(options: {
+    executable: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+}): Promise<CommandResult>;

package/dist/providers/command-runner.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+export function runCommand(options) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const maxOutputBytes = options.maxOutputBytes ?? 256 * 1024;
+    return new Promise(resolve => {
+        let settled = false;
+        let stdout = '', stderr = '', timedOut = false;
+        const child = spawn(options.executable, options.args, { cwd: options.cwd, env: options.env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        const append = (current, chunk) => Buffer.from(current + chunk.toString('utf8')).subarray(-maxOutputBytes).toString('utf8');
+        child.stdout.on('data', (chunk) => { stdout = append(stdout, chunk); });
+        child.stderr.on('data', (chunk) => { stderr = append(stderr, chunk); });
+        const finish = (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+            resolve({ exitCode, signal, stdout, stderr, timedOut });
+        };
+        const abort = () => child.kill('SIGTERM');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs);
+        child.on('error', error => { stderr = append(stderr, Buffer.from(error.message)); finish(127, null); });
+        child.on('close', (code, signal) => finish(code ?? 1, signal));
+    });
+}

package/dist/providers/git-safety.d.ts

@@ -0,0 +1,13 @@
+export interface GitSafetyIssue {
+    code: 'GIT_SENSITIVE_FILE_TRACKED';
+    reason: string;
+    fix: string;
+    paths: string[];
+}
+export interface GitSafetyResult {
+    repository: boolean;
+    root?: string;
+    issues: GitSafetyIssue[];
+}
+export declare function inspectGitSafety(candidate: string): Promise<GitSafetyResult>;
+export declare function applyLocalExclude(repository: string, rule: string): Promise<void>;

package/dist/providers/git-safety.js

@@ -0,0 +1,58 @@
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { runCommand } from './command-runner.js';
+async function git(root, args) {
+    return runCommand({ executable: 'git', args: ['-C', root, ...args], timeoutMs: 10_000 });
+}
+function sensitive(file) {
+    const name = path.basename(file).toLowerCase();
+    return name === 'cert.pem'
+        || /[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.json$/i.test(name)
+        || /\.(key|p12|pfx)$/i.test(name)
+        || file.split(/[\\/]/).includes('.cloudflare-tunnel-kit');
+}
+export async function inspectGitSafety(candidate) {
+    const rootResult = await git(candidate, ['rev-parse', '--show-toplevel']);
+    if (rootResult.exitCode !== 0)
+        return { repository: false, issues: [] };
+    const root = rootResult.stdout.trim();
+    const [trackedResult, stagedResult] = await Promise.all([
+        git(root, ['ls-files']),
+        git(root, ['diff', '--cached', '--name-only']),
+    ]);
+    const files = new Set([...trackedResult.stdout.split('\n'), ...stagedResult.stdout.split('\n')].map(value => value.trim()).filter(Boolean));
+    const paths = [...files].filter(sensitive).sort();
+    return {
+        repository: true,
+        root,
+        issues: paths.length ? [{
+                code: 'GIT_SENSITIVE_FILE_TRACKED',
+                reason: 'Git is tracking or staging a Cloudflare credential or generated tunnel file.',
+                fix: 'Remove the file from Git tracking and rotate any credential that may already have been shared.',
+                paths,
+            }] : [],
+    };
+}
+export async function applyLocalExclude(repository, rule) {
+    if (!rule.trim() || /[\r\n]/.test(rule))
+        throw new Error('A local Git exclude rule must be one non-empty line.');
+    const locationResult = await git(repository, ['rev-parse', '--git-path', 'info/exclude']);
+    if (locationResult.exitCode !== 0)
+        throw new Error('The selected project is not a Git repository.');
+    const location = path.resolve(repository, locationResult.stdout.trim());
+    let content = '';
+    try {
+        content = await readFile(location, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const lines = content.split(/\r?\n/);
+    if (lines.includes(rule))
+        return;
+    const next = `${content}${content && !content.endsWith('\n') ? '\n' : ''}${rule}\n`;
+    const temporary = `${location}.cloudflare-tunnel-kit.tmp`;
+    await writeFile(temporary, next, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, location);
+}

package/dist/providers/process-supervisor.d.ts

@@ -0,0 +1,39 @@
+import { type ChildProcess } from 'node:child_process';
+export type ManagedProcessState = 'starting' | 'running' | 'stopping' | 'stopped' | 'failed';
+export declare class ManagedSession {
+    readonly key: string;
+    readonly child: ChildProcess;
+    private readonly maxLogBytes;
+    state: ManagedProcessState;
+    readonly startedAt: string;
+    readonly pid?: number;
+    private logText;
+    private readonly events;
+    constructor(key: string, child: ChildProcess, maxLogBytes: number);
+    append(value: string): void;
+    logs(): string;
+    waitForOutput(pattern: RegExp, timeoutMs: number): Promise<string>;
+}
+export declare class ProcessSupervisor {
+    private readonly sessions;
+    private readonly maxLogBytes;
+    constructor(options?: {
+        maxLogBytes?: number;
+    });
+    start(options: {
+        key: string;
+        executable: string;
+        args: string[];
+        env?: NodeJS.ProcessEnv;
+        cwd?: string;
+    }): Promise<ManagedSession>;
+    status(key: string): {
+        state: ManagedProcessState;
+        pid?: number;
+        logs: string;
+    };
+    stop(key: string, graceMs?: number): Promise<{
+        stopped: boolean;
+        forceRequired: boolean;
+    }>;
+}

package/dist/providers/process-supervisor.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { redact } from '../core/redact.js';
+export class ManagedSession {
+    key;
+    child;
+    maxLogBytes;
+    state = 'starting';
+    startedAt = new Date().toISOString();
+    pid;
+    logText = '';
+    events = new EventEmitter();
+    constructor(key, child, maxLogBytes) {
+        this.key = key;
+        this.child = child;
+        this.maxLogBytes = maxLogBytes;
+        this.pid = child.pid;
+    }
+    append(value) {
+        this.logText = Buffer.from(this.logText + redact(value)).subarray(-this.maxLogBytes).toString('utf8');
+        this.events.emit('output', this.logText);
+    }
+    logs() { return this.logText; }
+    waitForOutput(pattern, timeoutMs) {
+        if (pattern.test(this.logText))
+            return Promise.resolve(this.logText);
+        return new Promise((resolve, reject) => {
+            const output = (logs) => {
+                if (!pattern.test(logs))
+                    return;
+                cleanup();
+                resolve(logs);
+            };
+            const timeout = setTimeout(() => { cleanup(); reject(new Error(`Timed out waiting for process output: ${pattern}`)); }, timeoutMs);
+            const cleanup = () => { clearTimeout(timeout); this.events.off('output', output); };
+            this.events.on('output', output);
+        });
+    }
+}
+export class ProcessSupervisor {
+    sessions = new Map();
+    maxLogBytes;
+    constructor(options = {}) { this.maxLogBytes = options.maxLogBytes ?? 256 * 1024; }
+    async start(options) {
+        const existing = this.sessions.get(options.key);
+        if (existing && ['starting', 'running', 'stopping'].includes(existing.state))
+            throw new Error(`A connector is already running for ${options.key}.`);
+        const child = spawn(options.executable, options.args, { cwd: options.cwd, env: options.env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        const session = new ManagedSession(options.key, child, this.maxLogBytes);
+        this.sessions.set(options.key, session);
+        child.stdout?.on('data', chunk => session.append(chunk.toString('utf8')));
+        child.stderr?.on('data', chunk => session.append(chunk.toString('utf8')));
+        child.on('close', code => { session.state = code === 0 || session.state === 'stopping' ? 'stopped' : 'failed'; });
+        return new Promise((resolve, reject) => {
+            child.once('spawn', () => { session.state = 'running'; resolve(session); });
+            child.once('error', error => { session.state = 'failed'; session.append(error.message); reject(error); });
+        });
+    }
+    status(key) {
+        const session = this.sessions.get(key);
+        return session ? { state: session.state, pid: session.pid, logs: session.logs() } : { state: 'stopped', logs: '' };
+    }
+    async stop(key, graceMs = 2_000) {
+        const session = this.sessions.get(key);
+        if (!session || ['stopped', 'failed'].includes(session.state))
+            return { stopped: true, forceRequired: false };
+        session.state = 'stopping';
+        session.child.kill('SIGTERM');
+        const stopped = await new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), graceMs);
+            session.child.once('close', () => { clearTimeout(timer); resolve(true); });
+        });
+        if (stopped)
+            session.state = 'stopped';
+        return { stopped, forceRequired: !stopped };
+    }
+}

package/package.json

@@ -1,15 +1,39 @@
 {
   "name": "cloudflare-tunnel-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Safe, reusable Cloudflare Tunnel setup for custom and Laravel projects.",
   "type": "module",
-  "bin": { "cf-tunnel": "dist/cli/main.js" },
+  "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"
+  "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": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.4.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^13.0.3"
+  }
 }