@zeroexcore/tuna 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,161 @@
+# @zeroexcore/tuna
+
+**Cloudflare Tunnels for humans.** Wrap any dev command with a secure, persistent tunnel.
+
+[![npm version](https://img.shields.io/npm/v/@zeroexcore/tuna.svg)](https://www.npmjs.com/package/@zeroexcore/tuna)
+[![CI](https://github.com/zeroexcore/tuna/actions/workflows/ci.yml/badge.svg)](https://github.com/zeroexcore/tuna/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Links
+
+- **Website:** [tuna.oxc.sh](https://tuna.oxc.sh)
+- **Documentation:** [docs.tuna.oxc.sh](https://docs.tuna.oxc.sh)
+- **GitHub:** [github.com/zeroexcore/tuna](https://github.com/zeroexcore/tuna)
+
+## What is tuna?
+
+tuna wraps your development server commands with automatic Cloudflare Tunnel setup. No more manual tunnel configuration, DNS management, or random ngrok URLs.
+
+```bash
+# Before: Manual tunnel setup
+cloudflared tunnel create my-tunnel
+cloudflared tunnel route dns my-tunnel my-app.example.com
+cloudflared tunnel run my-tunnel &
+vite dev
+
+# After: Just prefix with tuna
+tuna vite dev
+```
+
+Your local server is instantly available at `https://my-app.example.com`.
+
+## Features
+
+- **Free custom domains** - Use your own domain, no random URLs
+- **Persistent tunnels** - Runs as a service, survives terminal restarts
+- **Team collaboration** - `$USER` variable gives each dev their own subdomain
+- **Zero Trust Access** - Restrict access by email/domain in config
+- **Transparent wrapper** - Colors, TTY, exit codes all preserved
+
+## Installation
+
+```bash
+npm install -g @zeroexcore/tuna
+# or
+pnpm add -g @zeroexcore/tuna
+# or
+npx @zeroexcore/tuna <command>
+```
+
+## Quick Start
+
+### 1. Login to Cloudflare
+
+```bash
+tuna --login
+```
+
+You'll need a Cloudflare API token with these permissions:
+- Account → Cloudflare Tunnel → Edit
+- Account → Access: Apps and Policies → Edit
+- Zone → DNS → Edit
+- Account → Account Settings → Read
+
+### 2. Configure your project
+
+Add to `package.json`:
+
+```json
+{
+  "tuna": {
+    "forward": "my-app.example.com",
+    "port": 3000
+  }
+}
+```
+
+Or use the interactive setup:
+
+```bash
+tuna --init
+```
+
+### 3. Run your dev server
+
+```bash
+tuna vite dev
+# or
+tuna npm run dev
+# or
+tuna next dev
+```
+
+That's it! Your local server is now available at your custom domain.
+
+## Team Collaboration
+
+Use `$USER` to give each developer their own subdomain:
+
+```json
+{
+  "tuna": {
+    "forward": "$USER-api.example.com",
+    "port": 3000
+  }
+}
+```
+
+- Alice runs `tuna vite dev` → `https://alice-api.example.com`
+- Bob runs `tuna vite dev` → `https://bob-api.example.com`
+
+## Access Control
+
+Restrict who can access your tunnel:
+
+```json
+{
+  "tuna": {
+    "forward": "staging.example.com",
+    "port": 3000,
+    "access": ["@mycompany.com", "contractor@gmail.com"]
+  }
+}
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tuna <command>` | Wrap command with tunnel |
+| `tuna --init` | Interactive project setup |
+| `tuna --login` | Setup Cloudflare credentials |
+| `tuna --list` | List all tunnels |
+| `tuna --stop` | Stop cloudflared service |
+| `tuna --delete [name]` | Delete tunnel |
+| `tuna --help` | Show help |
+| `tuna --version` | Show version |
+
+## Configuration
+
+| Field | Type | Required | Description |
+|-------|------|:--------:|-------------|
+| `forward` | `string` | Yes | Domain to expose (supports `$USER`, `$TUNA_USER`) |
+| `port` | `number` | Yes | Local port to forward |
+| `access` | `string[]` | No | Email addresses/domains for access control |
+
+## Requirements
+
+- Node.js 18+
+- macOS (Linux/Windows support planned)
+- A Cloudflare account with a domain
+
+## Security
+
+- **Credentials** stored in macOS Keychain with biometric auth
+- **No secrets** in package.json or environment variables
+- **Zero Trust Access** for fine-grained access control
+- **TLS everywhere** via Cloudflare
+
+## License
+
+MIT - see [LICENSE](https://github.com/zeroexcore/tuna/blob/main/LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroexcore/tuna",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cloudflare Tunnel Wrapper for Development Servers",
   "type": "module",
   "repository": {

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @zeroexcore/tuna@0.1.0 test /home/runner/work/tuna/tuna/packages/cli
-> vitest run
-
-
- RUN  v4.0.18 /home/runner/work/tuna/tuna/packages/cli
-
- ✓ tests/unit/config.test.ts (23 tests) 9ms
-
- Test Files  1 passed (1)
-      Tests  23 passed (23)
-   Start at  07:11:47
-   Duration  198ms (transform 47ms, setup 0ms, import 66ms, tests 9ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @zeroexcore/tuna@0.1.0 typecheck /home/runner/work/tuna/tuna/packages/cli
-> tsc --noEmit
-

package/tests/unit/config.test.ts

@@ -1,176 +0,0 @@
-/**
- * Tests for config module
- */
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { interpolateEnvVars, validateConfig, generateTunnelName } from '../../src/lib/config.ts';
-import type { TunaConfig } from '../../src/types/index.ts';
-
-describe('interpolateEnvVars', () => {
-  let originalEnv: NodeJS.ProcessEnv;
-
-  beforeEach(() => {
-    originalEnv = { ...process.env };
-  });
-
-  afterEach(() => {
-    process.env = originalEnv;
-  });
-
-  it('should interpolate $USER', () => {
-    process.env.USER = 'alice';
-    const result = interpolateEnvVars('$USER-api.example.com');
-    expect(result).toBe('alice-api.example.com');
-  });
-
-  it('should interpolate $TUNA_USER with priority over $USER', () => {
-    process.env.USER = 'alice';
-    process.env.TUNA_USER = 'alice-dev';
-    const result = interpolateEnvVars('$USER-api.example.com');
-    expect(result).toBe('alice-dev-api.example.com');
-  });
-
-  it('should interpolate $TUNA_USER directly', () => {
-    process.env.TUNA_USER = 'custom-user';
-    const result = interpolateEnvVars('$TUNA_USER-api.example.com');
-    expect(result).toBe('custom-user-api.example.com');
-  });
-
-  it('should interpolate $HOME', () => {
-    process.env.HOME = '/Users/alice';
-    const result = interpolateEnvVars('$HOME/.config');
-    expect(result).toBe('/Users/alice/.config');
-  });
-
-  it('should fallback to "unknown" when $USER is not set', () => {
-    delete process.env.USER;
-    delete process.env.TUNA_USER;
-    const result = interpolateEnvVars('$USER-api.example.com');
-    expect(result).toBe('unknown-api.example.com');
-  });
-
-  it('should handle multiple placeholders', () => {
-    process.env.USER = 'alice';
-    process.env.HOME = '/Users/alice';
-    const result = interpolateEnvVars('$USER-$HOME');
-    expect(result).toBe('alice-/Users/alice');
-  });
-
-  it('should interpolate in middle of string', () => {
-    process.env.USER = 'alice';
-    const result = interpolateEnvVars('app-$USER.staging.example.com');
-    expect(result).toBe('app-alice.staging.example.com');
-  });
-});
-
-describe('validateConfig', () => {
-  it('should pass valid config', () => {
-    const config: TunaConfig = {
-      forward: 'my-app.example.com',
-      port: 3000,
-    };
-    expect(() => validateConfig(config)).not.toThrow();
-  });
-
-  it('should throw on missing forward', () => {
-    const config = {
-      port: 3000,
-    } as TunaConfig;
-    expect(() => validateConfig(config)).toThrow('Missing "forward"');
-  });
-
-  it('should throw on missing port', () => {
-    const config = {
-      forward: 'my-app.example.com',
-    } as TunaConfig;
-    expect(() => validateConfig(config)).toThrow('Missing "port"');
-  });
-
-  it('should throw on non-number port', () => {
-    const config = {
-      forward: 'my-app.example.com',
-      port: '3000' as any,
-    };
-    expect(() => validateConfig(config)).toThrow('"port" must be a number');
-  });
-
-  it('should throw on port out of range (too low)', () => {
-    const config: TunaConfig = {
-      forward: 'my-app.example.com',
-      port: 0,
-    };
-    expect(() => validateConfig(config)).toThrow('"port" must be between 1 and 65535');
-  });
-
-  it('should throw on port out of range (too high)', () => {
-    const config: TunaConfig = {
-      forward: 'my-app.example.com',
-      port: 65536,
-    };
-    expect(() => validateConfig(config)).toThrow('"port" must be between 1 and 65535');
-  });
-
-  it('should throw on invalid domain format', () => {
-    const config: TunaConfig = {
-      forward: 'invalid..domain.com',
-      port: 3000,
-    };
-    expect(() => validateConfig(config)).toThrow('Invalid domain format');
-  });
-
-  it('should throw on unresolved environment variables', () => {
-    const config: TunaConfig = {
-      forward: '$USER-api.example.com',
-      port: 3000,
-    };
-    expect(() => validateConfig(config)).toThrow('Unresolved environment variables');
-  });
-
-  it('should pass with subdomain', () => {
-    const config: TunaConfig = {
-      forward: 'api.staging.example.com',
-      port: 3000,
-    };
-    expect(() => validateConfig(config)).not.toThrow();
-  });
-
-  it('should pass with hyphenated domain', () => {
-    const config: TunaConfig = {
-      forward: 'my-app-api.example.com',
-      port: 3000,
-    };
-    expect(() => validateConfig(config)).not.toThrow();
-  });
-});
-
-describe('generateTunnelName', () => {
-  it('should generate name with tuna prefix', () => {
-    const result = generateTunnelName('my-app.example.com');
-    expect(result).toBe('tuna-my-app-example-com');
-  });
-
-  it('should sanitize domain with dots', () => {
-    const result = generateTunnelName('api.staging.example.com');
-    expect(result).toBe('tuna-api-staging-example-com');
-  });
-
-  it('should lowercase everything', () => {
-    const result = generateTunnelName('MyApp.Example.Com');
-    expect(result).toBe('tuna-myapp-example-com');
-  });
-
-  it('should replace special characters', () => {
-    const result = generateTunnelName('alice@api.example.com');
-    expect(result).toBe('tuna-alice-api-example-com');
-  });
-
-  it('should handle consecutive special chars', () => {
-    const result = generateTunnelName('my..app..example.com');
-    expect(result).toBe('tuna-my--app--example-com');
-  });
-
-  it('should work with user-interpolated domain', () => {
-    const result = generateTunnelName('alice-api.example.com');
-    expect(result).toBe('tuna-alice-api-example-com');
-  });
-});

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "lib": ["ES2022"],
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "allowImportingTsExtensions": true,
-    "noEmit": true,
-    "types": ["node", "vitest/globals"]
-  },
-  "include": ["src/**/*", "tests/**/*"],
-  "exclude": ["node_modules"]
-}

package/vitest.config.ts

@@ -1,18 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'html'],
-      exclude: [
-        'node_modules/',
-        'tests/',
-        '**/*.test.ts',
-        '**/*.spec.ts',
-      ],
-    },
-  },
-});