portok 1.0.1 → 1.0.2

package/README.md

@@ -15,8 +15,15 @@ A lightweight Node.js "switchboard" proxy that enables zero-downtime deployments
 
 ### Installation
 
+**Global Installation (Recommended):**
+
 ```bash
-npm install
+# Install globally
+npm install -g portok
+
+# Now you can use portok and portokd commands from anywhere
+portok --help
+portokd --help
 ```
 
 ### Start the Daemon
@@ -28,25 +35,27 @@ export INITIAL_TARGET_PORT=8080
 export ADMIN_TOKEN=your-secret-token
 
 # Start portokd
-node portokd.mjs
+node portokd.js
 ```
 
 ### Use the CLI
 
 ```bash
 # Check status
-./portok.mjs status --token your-secret-token
+portok status --token your-secret-token
 
 # Switch to new port
-./portok.mjs switch 8081 --token your-secret-token
+portok switch 8081 --token your-secret-token
 
 # Check metrics
-./portok.mjs metrics --token your-secret-token
+portok metrics --token your-secret-token
 
 # Check health
-./portok.mjs health --token your-secret-token
+portok health --token your-secret-token
 ```
 
+> **Note:** If not installed globally, use `./portok.js` instead of `portok`.
+
 ## Configuration
 
 All configuration is via environment variables:
@@ -190,6 +199,14 @@ Management Commands:
   add <name>      Create a new service instance
   list            List all configured instances and their status
 
+Service Control Commands:
+  start <name>    Start a portok service (systemctl start portok@<name>)
+  stop <name>     Stop a portok service
+  restart <name>  Restart a portok service
+  enable <name>   Enable service at boot
+  disable <name>  Disable service at boot
+  logs <name>     Show service logs (journalctl)
+
 Operational Commands:
   status          Show current proxy status
   metrics         Show proxy metrics
@@ -208,6 +225,10 @@ Options for 'add' command:
   --target <port>   Target port (default: random 8000-8999)
   --health <path>   Health check path (default: /health)
   --force           Overwrite existing config
+
+Options for 'logs' command:
+  --follow, -f      Follow log output
+  --lines, -n       Number of lines to show (default: 50)
 ```
 
 ### Quick Start with CLI
@@ -220,12 +241,15 @@ sudo portok init
 sudo portok add api --port 3001 --target 8001
 
 # 3. Start the service
-sudo systemctl start portok@api
+sudo portok start api
+
+# 4. Enable at boot
+sudo portok enable api
 
-# 4. Check status
+# 5. Check status
 portok status --instance api
 
-# 5. List all services
+# 6. List all services
 portok list
 ```
 
@@ -244,6 +268,18 @@ sudo portok init
 sudo portok add api --port 3001 --target 8001
 sudo portok add web --port 3002 --target 8002
 
+# Service management
+sudo portok start api
+sudo portok stop api
+sudo portok restart api
+sudo portok enable api    # Enable at boot
+sudo portok disable api   # Disable at boot
+
+# View logs
+portok logs api
+portok logs api --follow  # Follow log output
+portok logs api -n 100    # Show last 100 lines
+
 # List all instances with status
 portok list
 
@@ -276,7 +312,7 @@ After=network.target
 Type=simple
 User=www-data
 WorkingDirectory=/opt/portok
-ExecStart=/usr/bin/node /opt/portok/portokd.mjs
+ExecStart=/usr/bin/node /opt/portok/portokd.js
 Restart=always
 RestartSec=5
 
@@ -548,10 +584,10 @@ Run the validation benchmark to verify performance:
 
 ```bash
 # Quick validation (3s)
-FAST_PATH=1 node bench/validate.mjs --quick
+FAST_PATH=1 node bench/validate.js --quick
 
 # Full validation (10s)
-FAST_PATH=1 node bench/validate.mjs
+FAST_PATH=1 node bench/validate.js
 
 # Manual autocannon test
 # Direct:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portok",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Zero-downtime deployment proxy - routes traffic through a stable port to internal app instances with health-gated switching",
   "main": "portokd.js",
   "bin": {

package/portok.js

@@ -631,6 +631,92 @@ async function cmdHealth(baseUrl, token, options) {
   }
 }
 
+// =============================================================================
+// Systemctl Commands (start, stop, restart, enable, disable)
+// =============================================================================
+
+const { execSync } = require('node:child_process');
+
+async function cmdSystemctl(action, name, options) {
+  if (!name) {
+    console.error(`${colors.red}Error:${colors.reset} Instance name is required`);
+    console.error(`Usage: portok ${action} <name>`);
+    return 1;
+  }
+
+  // Validate name exists
+  const envFilePath = path.join(ENV_FILE_DIR, `${name}.env`);
+  if (!fs.existsSync(envFilePath)) {
+    console.error(`${colors.red}Error:${colors.reset} Instance '${name}' not found`);
+    console.error(`Make sure ${envFilePath} exists. Run ${colors.cyan}portok add ${name}${colors.reset} to create it.`);
+    return 1;
+  }
+
+  const serviceName = `portok@${name}`;
+  const actionVerb = {
+    start: 'Starting',
+    stop: 'Stopping',
+    restart: 'Restarting',
+    enable: 'Enabling',
+    disable: 'Disabling',
+  }[action];
+
+  console.log(`${colors.cyan}${actionVerb} ${serviceName}...${colors.reset}`);
+
+  try {
+    execSync(`systemctl ${action} ${serviceName}`, { stdio: 'inherit' });
+    
+    const pastVerb = {
+      start: 'started',
+      stop: 'stopped',
+      restart: 'restarted',
+      enable: 'enabled',
+      disable: 'disabled',
+    }[action];
+
+    console.log(`${colors.green}✓ Service ${serviceName} ${pastVerb}${colors.reset}`);
+
+    // For start/restart, show status after
+    if (action === 'start' || action === 'restart') {
+      console.log('');
+      try {
+        execSync(`systemctl status ${serviceName} --no-pager -l`, { stdio: 'inherit' });
+      } catch {
+        // Status might return non-zero even when running, ignore
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    console.error(`${colors.red}Failed to ${action} ${serviceName}${colors.reset}`);
+    if (err.status === 1) {
+      console.error(`${colors.yellow}Hint:${colors.reset} This command may require sudo privileges.`);
+      console.error(`Try: ${colors.cyan}sudo portok ${action} ${name}${colors.reset}`);
+    }
+    return 1;
+  }
+}
+
+async function cmdLogs(name, options) {
+  if (!name) {
+    console.error(`${colors.red}Error:${colors.reset} Instance name is required`);
+    console.error('Usage: portok logs <name> [--follow]');
+    return 1;
+  }
+
+  const serviceName = `portok@${name}`;
+  const followFlag = options.follow || options.f ? '-f' : '';
+  const lines = options.lines || options.n || '50';
+
+  try {
+    execSync(`journalctl -u ${serviceName} -n ${lines} ${followFlag} --no-pager`, { stdio: 'inherit' });
+    return 0;
+  } catch (err) {
+    console.error(`${colors.red}Failed to get logs for ${serviceName}${colors.reset}`);
+    return 1;
+  }
+}
+
 function showHelp() {
   console.log(`
 ${colors.bold}portok${colors.reset} - CLI for portokd zero-downtime proxy daemon
@@ -644,6 +730,14 @@ ${colors.bold}COMMANDS${colors.reset}
   add <name>      Create a new service instance
   list            List all configured instances and their status
 
+  ${colors.cyan}Service Control:${colors.reset}
+  start <name>    Start a portok service (systemctl start portok@<name>)
+  stop <name>     Stop a portok service
+  restart <name>  Restart a portok service
+  enable <name>   Enable service at boot
+  disable <name>  Disable service at boot
+  logs <name>     Show service logs (journalctl)
+
   ${colors.cyan}Operations:${colors.reset}
   status          Show current proxy status (activePort, drainUntil, lastSwitch)
   metrics         Show proxy metrics (requests, errors, health, RPS)
@@ -663,17 +757,28 @@ ${colors.bold}OPTIONS${colors.reset}
   --health <path>   Health check path (default: /health)
   --force           Overwrite existing config
 
+  ${colors.dim}For 'logs' command:${colors.reset}
+  --follow, -f      Follow log output
+  --lines, -n       Number of lines to show (default: 50)
+
 ${colors.bold}EXAMPLES${colors.reset}
   ${colors.dim}# Initialize portok (run once, requires sudo)${colors.reset}
   sudo portok init
 
-  ${colors.dim}# Create a new service${colors.reset}
+  ${colors.dim}# Create and start a new service${colors.reset}
   sudo portok add api --port 3001 --target 8001
-  sudo portok add web --port 3002 --target 8002
+  sudo portok start api
+  sudo portok enable api
 
   ${colors.dim}# List all instances${colors.reset}
   portok list
 
+  ${colors.dim}# Service management${colors.reset}
+  sudo portok start api
+  sudo portok stop api
+  sudo portok restart api
+  portok logs api --follow
+
   ${colors.dim}# Check status of an instance${colors.reset}
   portok status --instance api
 
@@ -683,9 +788,6 @@ ${colors.bold}EXAMPLES${colors.reset}
   ${colors.dim}# Get metrics as JSON${colors.reset}
   portok metrics --instance api --json
 
-  ${colors.dim}# Direct URL mode (without instance)${colors.reset}
-  portok status --url http://127.0.0.1:3000 --token mysecret
-
 ${colors.bold}MULTI-INSTANCE${colors.reset}
   When using --instance, the CLI reads /etc/portok/<name>.env
   to resolve LISTEN_PORT and ADMIN_TOKEN for that instance.
@@ -711,7 +813,7 @@ async function main() {
   }
 
   // Management commands (don't require daemon connection)
-  const managementCommands = ['init', 'add', 'list'];
+  const managementCommands = ['init', 'add', 'list', 'start', 'stop', 'restart', 'enable', 'disable', 'logs'];
 
   if (managementCommands.includes(args.command)) {
     let exitCode = 1;
@@ -725,6 +827,16 @@ async function main() {
       case 'list':
         exitCode = await cmdList(args.options);
         break;
+      case 'start':
+      case 'stop':
+      case 'restart':
+      case 'enable':
+      case 'disable':
+        exitCode = await cmdSystemctl(args.command, args.positional[0], args.options);
+        break;
+      case 'logs':
+        exitCode = await cmdLogs(args.positional[0], args.options);
+        break;
     }
     process.exit(exitCode);
   }