cloudflare-tunnel-kit 0.1.1 → 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/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/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/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,16 @@
 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';
+export * from './providers/browser.js';

package/dist/index.js

@@ -1,6 +1,16 @@
 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';
+export * from './providers/browser.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/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/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.1",
+  "version": "0.1.3",
   "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": "^12.11.1"
+  }
 }