hostfn 0.1.0

package/examples/express-api/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "example-express-api",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "express": "^4.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/examples/express-api/src/index.ts

@@ -0,0 +1,16 @@
+import express from 'express';
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+app.get('/', (req, res) => {
+  res.json({ message: 'Hello from Express API!' });
+});
+
+app.listen(port, () => {
+  console.log(`Server running on port ${port}`);
+});

package/examples/express-api/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}

package/examples/github-actions-deploy.yml

@@ -0,0 +1,40 @@
+name: Deploy with hostfn
+
+on:
+  push:
+    branches:
+      - main
+      - production
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install hostfn
+        run: npm install -g hostfn
+      
+      - name: Deploy to production
+        env:
+          HOSTFN_SSH_KEY: ${{ secrets.HOSTFN_SSH_KEY }}
+          HOSTFN_SSH_PASSPHRASE: ${{ secrets.HOSTFN_SSH_PASSPHRASE }}
+        run: hostfn deploy production --ci
+
+  deploy-selfhosted:
+    # This job runs on a self-hosted runner on the deployment server
+    runs-on: self-hosted
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      - name: Deploy locally (no SSH needed)
+        run: hostfn deploy production --local --ci

package/examples/monorepo-config.json

@@ -0,0 +1,76 @@
+{
+  "name": "21n",
+  "runtime": "nodejs",
+  "version": "18",
+  "environments": {
+    "production": {
+      "server": "ubuntu@prod.example.com",
+      "port": 3000,
+      "instances": "max"
+    },
+    "staging": {
+      "server": "ubuntu@staging.example.com",
+      "port": 3000,
+      "instances": 2
+    }
+  },
+  "build": {
+    "command": "npm run build",
+    "directory": "dist",
+    "nodeModules": "production"
+  },
+  "start": {
+    "command": "npm start",
+    "entry": "dist/index.js"
+  },
+  "services": {
+    "account": {
+      "port": 3001,
+      "path": "services/account",
+      "domain": "account.example.com",
+      "instances": "max"
+    },
+    "auth": {
+      "port": 3002,
+      "path": "services/auth",
+      "domain": "auth.example.com",
+      "instances": 2
+    },
+    "notification": {
+      "port": 3003,
+      "path": "services/notification",
+      "domain": "notification.example.com"
+    },
+    "analytics": {
+      "port": 3004,
+      "path": "services/analytics"
+    }
+  },
+  "health": {
+    "path": "/health",
+    "timeout": 60,
+    "retries": 10,
+    "interval": 3
+  },
+  "env": {
+    "required": ["NODE_ENV", "DATABASE_URL"],
+    "optional": ["REDIS_URL", "LOG_LEVEL"]
+  },
+  "sync": {
+    "exclude": [
+      "node_modules",
+      ".git",
+      ".github",
+      "dist",
+      "build",
+      ".env",
+      ".env.*",
+      "*.log",
+      ".turbo",
+      ".wrangler"
+    ]
+  },
+  "backup": {
+    "keep": 5
+  }
+}

package/examples/monorepo-multi-server-config.json

@@ -0,0 +1,74 @@
+{
+  "name": "21n",
+  "runtime": "nodejs",
+  "version": "18",
+  "environments": {
+    "production": {
+      "server": "ubuntu@shared.example.com",
+      "port": 3000,
+      "instances": "max"
+    }
+  },
+  "build": {
+    "command": "npm run build",
+    "directory": "dist",
+    "nodeModules": "production"
+  },
+  "start": {
+    "command": "npm start",
+    "entry": "dist/index.js"
+  },
+  "services": {
+    "account": {
+      "port": 3001,
+      "path": "services/account",
+      "domain": "account.example.com",
+      "server": "ubuntu@account-server.example.com",
+      "instances": "max"
+    },
+    "auth": {
+      "port": 3002,
+      "path": "services/auth",
+      "domain": "auth.example.com",
+      "server": "ubuntu@auth-server.example.com",
+      "instances": 4
+    },
+    "notification": {
+      "port": 3003,
+      "path": "services/notification",
+      "domain": "notification.example.com"
+    },
+    "analytics": {
+      "port": 3004,
+      "path": "services/analytics",
+      "server": "ubuntu@analytics-server.example.com"
+    }
+  },
+  "health": {
+    "path": "/health",
+    "timeout": 60,
+    "retries": 10,
+    "interval": 3
+  },
+  "env": {
+    "required": ["NODE_ENV", "DATABASE_URL"],
+    "optional": ["REDIS_URL", "LOG_LEVEL"]
+  },
+  "sync": {
+    "exclude": [
+      "node_modules",
+      ".git",
+      ".github",
+      "dist",
+      "build",
+      ".env",
+      ".env.*",
+      "*.log",
+      ".turbo",
+      ".wrangler"
+    ]
+  },
+  "backup": {
+    "keep": 5
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "hostfn",
+  "version": "0.1.0",
+  "description": "Universal application deployment CLI",
+  "license": "Apache-2.0",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "lint": "turbo run lint",
+    "test": "turbo run test",
+    "clean": "turbo run clean && rm -rf node_modules"
+  },
+  "devDependencies": {
+    "turbo": "^1.11.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "deployment",
+    "vps"
+  ],
+  "author": "21n",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/hostfn.git"
+  },
+  "bugs": {
+    "url": "https://github.com/21nCo/hostfn/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "npm@10.2.0",
+  "dependencies": {
+    "fast-glob": "^3.3.3"
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "hostfn",
+  "version": "0.1.0",
+  "description": "Universal application deployment CLI",
+  "type": "module",
+  "bin": {
+    "hostfn": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "chalk": "^5.3.0",
+    "ora": "^7.0.1",
+    "inquirer": "^9.2.12",
+    "zod": "^3.22.4",
+    "ssh2": "^1.15.0",
+    "dotenv": "^16.3.1",
+    "execa": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ssh2": "^1.15.0",
+    "@types/inquirer": "^9.0.7",
+    "@vitest/coverage-v8": "^1.0.0",
+    "typescript": "^5.3.0",
+    "tsx": "^4.7.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/cli/src/__tests__/core/backup.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BackupManager } from '../../core/backup.js';
+
+// Mock SSH connection
+const mockSSH = {
+  exec: vi.fn(),
+  exists: vi.fn(),
+  mkdir: vi.fn(),
+  upload: vi.fn(),
+  download: vi.fn(),
+  disconnect: vi.fn(),
+};
+
+describe('BackupManager', () => {
+  let backupManager: BackupManager;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    backupManager = new BackupManager(mockSSH as any, '/var/www/myapp');
+  });
+
+  describe('create', () => {
+    it('should create backup with timestamp', async () => {
+      mockSSH.mkdir.mockResolvedValue(undefined);
+      mockSSH.exists.mockResolvedValue(true);  // dist exists
+      mockSSH.exec.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
+      
+      const backupPath = await backupManager.create();
+      
+      expect(backupPath).toMatch(/\/var\/www\/myapp\/backups\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}/);
+      expect(mockSSH.mkdir).toHaveBeenCalled();
+      expect(mockSSH.exec).toHaveBeenCalled();
+    });
+
+    it('should return path even if source directory does not exist', async () => {
+      mockSSH.mkdir.mockResolvedValue(undefined);
+      mockSSH.exists.mockResolvedValue(false);  // No dist directory
+      
+      const backupPath = await backupManager.create();
+      
+      // Returns backup path but doesn't fail
+      expect(backupPath).toMatch(/\/var\/www\/myapp\/backups\/\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}/);
+      expect(mockSSH.mkdir).toHaveBeenCalled();
+    });
+  });
+
+  describe('list', () => {
+    it('should list all backups with timestamps', async () => {
+      mockSSH.exists.mockResolvedValue(true);
+      mockSSH.exec.mockResolvedValue({ 
+        stdout: 'myapp.backup.20251114_130000\nmyapp.backup.20251114_120000\n',  // sorted reverse
+        stderr: '', 
+        exitCode: 0 
+      });
+      
+      const backups = await backupManager.list();
+      
+      expect(backups).toHaveLength(2);
+      expect(backups[0]).toContain('20251114_130000');  // Most recent first
+      expect(backups[1]).toContain('20251114_120000');
+    });
+
+    it('should return empty array when no backups exist', async () => {
+      mockSSH.exec.mockResolvedValue({ 
+        stdout: '', 
+        stderr: '', 
+        exitCode: 0 
+      });
+      
+      const backups = await backupManager.list();
+      
+      expect(backups).toHaveLength(0);
+    });
+  });
+
+  describe('restore', () => {
+    it('should restore from backup', async () => {
+      mockSSH.exists.mockResolvedValue(true);
+      mockSSH.exec.mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
+      
+      await backupManager.restore('myapp.backup.20251114_120000');
+      
+      expect(mockSSH.exec).toHaveBeenCalledWith(
+        expect.stringContaining('cp -r')
+      );
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should keep only specified number of backups', async () => {
+      const backupNames = [
+        'myapp.backup.20251114_150000',  // Most recent (sorted)
+        'myapp.backup.20251114_140000',
+        'myapp.backup.20251114_130000',
+        'myapp.backup.20251114_120000',
+        'myapp.backup.20251114_110000',
+        'myapp.backup.20251114_100000',  // Oldest
+      ];
+
+      mockSSH.exists.mockResolvedValue(true);
+      mockSSH.exec
+        .mockResolvedValueOnce({ 
+          stdout: backupNames.join('\n'), 
+          stderr: '', 
+          exitCode: 0 
+        })
+        .mockResolvedValue({ stdout: '', stderr: '', exitCode: 0 });
+      
+      await backupManager.cleanup(3);
+      
+      // Should remove oldest 3 backups
+      expect(mockSSH.exec).toHaveBeenCalledWith(
+        expect.stringContaining('rm -rf')
+      );
+    });
+
+    it('should not remove backups if under limit', async () => {
+      const backupNames = [
+        'myapp.backup.20251114_100000',
+        'myapp.backup.20251114_110000',
+      ];
+
+      mockSSH.exists.mockResolvedValue(true);
+      mockSSH.exec.mockResolvedValueOnce({ 
+        stdout: backupNames.join('\n'), 
+        stderr: '', 
+        exitCode: 0 
+      });
+      
+      await backupManager.cleanup(5);
+      
+      // Should only call list, not remove (called twice: exists + ls)
+      expect(mockSSH.exec).toHaveBeenCalledTimes(1);
+      expect(mockSSH.exec).toHaveBeenCalledWith(expect.stringContaining('ls -1'));
+    });
+  });
+});

package/packages/cli/src/__tests__/core/health.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HealthCheck } from '../../core/health.js';
+
+// Mock fetch globally
+global.fetch = vi.fn();
+
+describe('HealthCheck', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('check', () => {
+    it('should return healthy for successful response', async () => {
+      (global.fetch as any).mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+      });
+
+      const result = await HealthCheck.check({
+        url: 'http://localhost:3000/health',
+      });
+
+      expect(result.healthy).toBe(true);
+      expect(result.statusCode).toBe(200);
+      expect(result.responseTime).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should return unhealthy for failed response', async () => {
+      (global.fetch as any).mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+      });
+
+      const result = await HealthCheck.check({
+        url: 'http://localhost:3000/health',
+      });
+
+      expect(result.healthy).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    it('should return unhealthy for network error', async () => {
+      (global.fetch as any).mockRejectedValueOnce(new Error('Network error'));
+
+      const result = await HealthCheck.check({
+        url: 'http://localhost:3000/health',
+      });
+
+      expect(result.healthy).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+
+    it('should respect timeout', async () => {
+      (global.fetch as any).mockImplementationOnce(() =>
+        new Promise((resolve) => setTimeout(resolve, 2000))
+      );
+
+      const result = await HealthCheck.check({
+        url: 'http://localhost:3000/health',
+        timeout: 100,
+      });
+
+      expect(result.healthy).toBe(false);
+    });
+  });
+
+  describe('waitForReady', () => {
+    it('should return true when service becomes healthy', async () => {
+      let callCount = 0;
+      (global.fetch as any).mockImplementation(() => {
+        callCount++;
+        return Promise.resolve({
+          ok: callCount >= 2, // Becomes healthy on second call
+          status: callCount >= 2 ? 200 : 503,
+        });
+      });
+
+      const result = await HealthCheck.waitForReady({
+        url: 'http://localhost:3000/health',
+        retries: 5,
+        interval: 10,
+      });
+
+      expect(result).toBe(true);
+      expect(callCount).toBeGreaterThanOrEqual(2);
+    });
+
+    it('should return false when max retries exceeded', async () => {
+      (global.fetch as any).mockResolvedValue({
+        ok: false,
+        status: 503,
+      });
+
+      const result = await HealthCheck.waitForReady({
+        url: 'http://localhost:3000/health',
+        retries: 2,
+        interval: 10,
+      });
+
+      expect(result).toBe(false);
+    });
+
+    it('should call progress callback on each attempt', async () => {
+      (global.fetch as any).mockResolvedValue({
+        ok: false,
+        status: 503,
+      });
+
+      const progressCalls: number[] = [];
+
+      await HealthCheck.waitForReady(
+        {
+          url: 'http://localhost:3000/health',
+          retries: 3,
+          interval: 10,
+        },
+        (attempt) => {
+          progressCalls.push(attempt);
+        }
+      );
+
+      expect(progressCalls).toEqual([1, 2, 3]);
+    });
+  });
+});