@byfungsi/funforge 0.1.0

package/README.md

@@ -0,0 +1,273 @@
+# @byfungsi/funforge
+
+> Deploy without git. Without leaving your editor.
+
+FunForge CLI lets you deploy directly from your local machine to [FunForge](https://funforge.app) - no commits, no pushes, no CI/CD pipelines. Just run `funforge deploy` and you're live.
+
+## Features
+
+- **Git-Free Deployment** - Deploy without committing. Perfect for rapid iteration.
+- **Local-First Workflow** - Work locally, deploy directly. Skip the CI/CD dance.
+- **Editor Integration** - MCP server for Claude Desktop, Cursor, and other AI assistants.
+- **Full Control** - Manage environment variables, custom domains, and deployments from CLI.
+
+## Installation
+
+```bash
+# npm
+npm install -g @byfungsi/funforge
+
+# pnpm
+pnpm add -g @byfungsi/funforge
+
+# bun
+bun add -g @byfungsi/funforge
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate (opens browser)
+funforge login
+
+# 2. Create an app (or link to existing)
+funforge apps create my-app
+
+# 3. Link your project
+funforge link
+
+# 4. Deploy
+funforge deploy
+```
+
+That's it. Your app is live at `https://your-app.funforge.app`.
+
+## Commands
+
+### Authentication
+
+```bash
+funforge login          # Authenticate via browser (device flow)
+funforge logout         # Clear stored credentials
+funforge whoami         # Show current authenticated user
+```
+
+### Apps
+
+```bash
+funforge apps list              # List all your apps
+funforge apps create <name>     # Create a new app
+funforge apps create <name> -s <slug>  # Create with custom subdomain
+funforge link                   # Link current directory to an app (interactive)
+funforge link <appId>           # Link to specific app
+```
+
+### Deploy
+
+```bash
+funforge deploy         # Deploy current directory
+funforge deploy -y      # Skip confirmation prompt
+funforge deploy --no-watch  # Don't watch deployment logs
+```
+
+### Environment Variables
+
+```bash
+funforge env list                    # List all env vars
+funforge env set KEY=VALUE           # Set single variable
+funforge env set KEY1=V1 KEY2=V2     # Set multiple variables
+funforge env unset KEY               # Remove variable
+funforge env unset KEY1 KEY2         # Remove multiple
+```
+
+### Custom Domains
+
+```bash
+funforge domains list               # List custom domains
+funforge domains add example.com    # Add domain (shows DNS instructions)
+funforge domains add example.com -m txt  # Use TXT verification
+funforge domains remove example.com # Remove domain
+funforge domains verify example.com # Verify DNS and provision SSL
+```
+
+### Config (Build Settings)
+
+Manage build settings stored on the server:
+
+```bash
+funforge config show    # Compare local vs server settings
+funforge config push    # Push local settings to server
+funforge config pull    # Pull server settings to local file
+```
+
+**Note:** The `config` commands sync settings to the database. However, during deployment, `funforge.json` in your project is automatically read and takes priority over database settings.
+
+## Configuration
+
+### funforge.json
+
+When you run `funforge link`, a `funforge.json` file is created in your project root:
+
+```json
+{
+  "appId": "your-app-uuid",
+  "appName": "My App",
+  "appSlug": "my-app",
+  "build": {
+    "buildCommand": "npm run build",
+    "installCommand": "npm ci",
+    "startCommand": "npm start",
+    "nodeVersion": "20"
+  },
+  "port": 3000
+}
+```
+
+**Fields:**
+
+| Field | Description |
+|-------|-------------|
+| `appId` | (Required) The app UUID this project is linked to |
+| `appName` | Display name of the app |
+| `appSlug` | Subdomain slug (e.g., `my-app` for `my-app.funforge.app`) |
+| `build.buildCommand` | Custom build command (overrides auto-detection) |
+| `build.installCommand` | Custom install command (e.g., `npm ci` or `pnpm install`) |
+| `build.startCommand` | Custom start command (e.g., `node server.js`) |
+| `build.nodeVersion` | Node.js version: `"18"`, `"20"`, or `"22"` |
+| `port` | Port your app listens on (default: 3000) |
+
+**Build Settings Priority:**
+
+During deployment, build settings are resolved in this order:
+
+1. **funforge.json** (in your project) - highest priority
+2. **Database settings** (set via web UI or `funforge config push`)
+3. **Railpack auto-detection** - fallback
+
+This means you can commit `funforge.json` to your Git repo and it will automatically be used during builds - no need to configure anything in the web UI or run `funforge config push`.
+
+**Git Users:** Just add `funforge.json` to your repo. The builder will automatically read it during deployment.
+
+**CLI Users:** Your `funforge.json` is included in the upload and used during builds.
+
+### .funforgeignore
+
+Control which files are included in the deployment tarball. Uses `.gitignore` syntax:
+
+```gitignore
+# Ignore test files
+__tests__/
+*.test.ts
+
+# Ignore local config
+.env.local
+config.local.json
+```
+
+By default, FunForge respects your `.gitignore` file. Use `.funforgeignore` to add additional exclusions.
+
+### Size Limits
+
+- Maximum tarball size: **50 MB**
+- Use `.funforgeignore` to exclude large files (node_modules is automatically excluded)
+
+## MCP Server
+
+FunForge includes an MCP (Model Context Protocol) server for AI assistant integration. Deploy directly from Claude Desktop, Cursor, or any MCP-compatible client.
+
+### Setup for Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "funforge": {
+      "command": "npx",
+      "args": ["@byfungsi/funforge-mcp"]
+    }
+  }
+}
+```
+
+### Setup for Cursor
+
+Add to your MCP settings:
+
+```json
+{
+  "funforge": {
+    "command": "npx",
+    "args": ["@byfungsi/funforge-mcp"]
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `funforge_whoami` | Check authentication status |
+| `funforge_apps_list` | List all your apps |
+| `funforge_apps_create` | Create a new app |
+| `funforge_status` | Get deployment status |
+| `funforge_deploy` | Deploy a directory |
+| `funforge_env_list` | List environment variables |
+| `funforge_env_set` | Set environment variables |
+| `funforge_env_unset` | Remove environment variables |
+| `funforge_domains_list` | List custom domains |
+| `funforge_domains_add` | Add a custom domain |
+
+### Example Conversations
+
+Once configured, you can use natural language:
+
+- "Deploy my current project to FunForge"
+- "Set the DATABASE_URL environment variable to postgres://..."
+- "Add api.myapp.com as a custom domain"
+- "What's the status of my deployment?"
+
+## Environment Variables
+
+The CLI can be configured via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FUNFORGE_API_URL` | API endpoint | `https://funforge.fungsi.app` |
+| `FUNFORGE_API_KEY` | API key (skips device auth) | - |
+
+## Authentication
+
+FunForge uses device authentication flow:
+
+1. Run `funforge login`
+2. Browser opens to FunForge login page
+3. Sign in with GitHub
+4. CLI automatically receives credentials
+5. Credentials stored locally in `~/.config/funforge/`
+
+For CI/CD environments, set `FUNFORGE_API_KEY` instead.
+
+## How It Works
+
+1. **Tarball Creation** - CLI creates a `.tar.gz` of your project (respecting `.gitignore` and `.funforgeignore`)
+2. **Upload** - Tarball is uploaded to R2 storage
+3. **Build** - FunForge downloads and builds your app using Railpack (auto-detects framework)
+4. **Deploy** - Blue-green deployment with health checks
+5. **Live** - Your app is available at `https://your-app.funforge.app`
+
+## Links
+
+- **Website**: [funforge.app](https://funforge.app)
+- **Documentation**: [docs.fungsi.app/docs/funforge/guides/cli](https://docs.fungsi.app/docs/funforge/guides/cli)
+- **CLI Marketing**: [funforge.app/cli](https://funforge.app/cli)
+- **MCP Integration**: [funforge.app/mcp](https://funforge.app/mcp)
+
+## Requirements
+
+- Node.js 18+
+- FunForge account (sign up at [funforge.app](https://funforge.app))
+
+## License
+
+MIT

package/dist/__tests__/api.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * API Client Tests
+ */
+export {};
+//# sourceMappingURL=api.test.d.ts.map

package/dist/__tests__/api.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/api.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/api.test.js

@@ -0,0 +1,177 @@
+/**
+ * API Client Tests
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi, } from "vitest";
+import { ApiError, apiRequest, createApp, getApp, listApps } from "../api.js";
+// Mock credentials module
+vi.mock("../credentials.js", () => ({
+    getApiKey: vi.fn(() => "test-api-key-123"),
+}));
+// Mock config module
+vi.mock("../config.js", () => ({
+    getConfig: vi.fn(() => ({
+        apiUrl: "https://api.test.com",
+        authUrl: "https://auth.test.com",
+        timeout: 5000,
+    })),
+}));
+describe("api", () => {
+    const mockFetch = vi.fn();
+    const originalFetch = global.fetch;
+    beforeAll(() => {
+        global.fetch = mockFetch;
+    });
+    afterAll(() => {
+        global.fetch = originalFetch;
+    });
+    beforeEach(() => {
+        mockFetch.mockReset();
+    });
+    describe("apiRequest", () => {
+        it("should make GET request with auth header", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ data: "test" }),
+            });
+            const result = await apiRequest("/api/test");
+            expect(result).toEqual({ data: "test" });
+            expect(mockFetch).toHaveBeenCalledWith("https://api.test.com/api/test", expect.objectContaining({
+                method: "GET",
+                headers: expect.objectContaining({
+                    Authorization: "Bearer test-api-key-123",
+                    "Content-Type": "application/json",
+                }),
+            }));
+        });
+        it("should make POST request with body", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({ success: true }),
+            });
+            const result = await apiRequest("/api/create", {
+                method: "POST",
+                body: { name: "test" },
+            });
+            expect(result).toEqual({ success: true });
+            expect(mockFetch).toHaveBeenCalledWith("https://api.test.com/api/create", expect.objectContaining({
+                method: "POST",
+                body: JSON.stringify({ name: "test" }),
+            }));
+        });
+        it("should throw ApiError on non-ok response", async () => {
+            mockFetch.mockResolvedValue({
+                ok: false,
+                status: 404,
+                json: async () => ({ message: "Not found" }),
+            });
+            await expect(apiRequest("/api/notfound")).rejects.toThrow(ApiError);
+            // Reset and mock again for second assertion
+            mockFetch.mockResolvedValue({
+                ok: false,
+                status: 404,
+                json: async () => ({ message: "Not found" }),
+            });
+            await expect(apiRequest("/api/notfound")).rejects.toMatchObject({
+                statusCode: 404,
+            });
+        });
+        it("should include error body in ApiError", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 400,
+                json: async () => ({ error: { message: "Invalid input" } }),
+            });
+            try {
+                await apiRequest("/api/invalid");
+                expect.fail("Should have thrown");
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(ApiError);
+                expect(error.body).toEqual({
+                    error: { message: "Invalid input" },
+                });
+            }
+        });
+        it("should skip auth when useAuth is false", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({}),
+            });
+            await apiRequest("/api/public", { useAuth: false });
+            expect(mockFetch).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+                headers: expect.not.objectContaining({
+                    Authorization: expect.any(String),
+                }),
+            }));
+        });
+    });
+    describe("listApps", () => {
+        it("should return list of apps", async () => {
+            const mockApps = {
+                apps: [
+                    { id: "app-1", name: "App 1", slug: "app-1" },
+                    { id: "app-2", name: "App 2", slug: "app-2" },
+                ],
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockApps,
+            });
+            const result = await listApps();
+            expect(result.apps).toHaveLength(2);
+            expect(result.apps[0].id).toBe("app-1");
+        });
+    });
+    describe("createApp", () => {
+        it("should create app with name", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    app: { id: "new-app", name: "New App", slug: "new-app" },
+                }),
+            });
+            const result = await createApp({ name: "New App" });
+            expect(result.app.name).toBe("New App");
+            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining("/api/cli/apps"), expect.objectContaining({
+                method: "POST",
+                body: JSON.stringify({ name: "New App" }),
+            }));
+        });
+        it("should create app with name and slug", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    app: { id: "new-app", name: "New App", slug: "custom-slug" },
+                }),
+            });
+            const result = await createApp({ name: "New App", slug: "custom-slug" });
+            expect(result.app.slug).toBe("custom-slug");
+        });
+    });
+    describe("getApp", () => {
+        it("should get app by id", async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    app: { id: "app-123", name: "My App", slug: "my-app" },
+                }),
+            });
+            const result = await getApp("app-123");
+            expect(result.app.id).toBe("app-123");
+            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining("/api/cli/apps/app-123"), expect.any(Object));
+        });
+    });
+});
+describe("ApiError", () => {
+    it("should have correct properties", () => {
+        const error = new ApiError("Test error", 500, { detail: "info" });
+        expect(error.message).toBe("Test error");
+        expect(error.statusCode).toBe(500);
+        expect(error.body).toEqual({ detail: "info" });
+        expect(error.name).toBe("ApiError");
+    });
+    it("should be instance of Error", () => {
+        const error = new ApiError("Test", 400);
+        expect(error).toBeInstanceOf(Error);
+    });
+});

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Config Tests
+ */
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/__tests__/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/config.test.js

@@ -0,0 +1,58 @@
+/**
+ * Config Tests
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { config, getConfig } from "../config.js";
+describe("config", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        // Reset env before each test
+        vi.resetModules();
+        process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    describe("default config", () => {
+        it("should have production API URL", () => {
+            expect(config.apiUrl).toBe("https://api.fungsi.app");
+        });
+        it("should have production auth URL", () => {
+            expect(config.authUrl).toBe("https://cloud.fungsi.app");
+        });
+        it("should have 30s timeout", () => {
+            expect(config.timeout).toBe(30000);
+        });
+    });
+    describe("getConfig", () => {
+        it("should return default config when no env vars set", () => {
+            delete process.env.FUNFORGE_API_URL;
+            delete process.env.FUNFORGE_AUTH_URL;
+            delete process.env.FUNFORGE_TIMEOUT;
+            const result = getConfig();
+            expect(result.apiUrl).toBe("https://api.fungsi.app");
+            expect(result.authUrl).toBe("https://cloud.fungsi.app");
+            expect(result.timeout).toBe(30000);
+        });
+        it("should override apiUrl from environment", () => {
+            process.env.FUNFORGE_API_URL = "http://localhost:3000";
+            const result = getConfig();
+            expect(result.apiUrl).toBe("http://localhost:3000");
+        });
+        it("should override authUrl from environment", () => {
+            process.env.FUNFORGE_AUTH_URL = "http://localhost:3001";
+            const result = getConfig();
+            expect(result.authUrl).toBe("http://localhost:3001");
+        });
+        it("should override timeout from environment", () => {
+            process.env.FUNFORGE_TIMEOUT = "60000";
+            const result = getConfig();
+            expect(result.timeout).toBe(60000);
+        });
+        it("should use default timeout for invalid env value", () => {
+            process.env.FUNFORGE_TIMEOUT = "invalid";
+            const result = getConfig();
+            expect(result.timeout).toBe(30000);
+        });
+    });
+});

package/dist/__tests__/mcp.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Server Tools Tests
+ *
+ * Tests the MCP tool handlers with mocked API responses.
+ */
+export {};
+//# sourceMappingURL=mcp.test.d.ts.map

package/dist/__tests__/mcp.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mcp.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/__tests__/mcp.test.js

@@ -0,0 +1,142 @@
+/**
+ * MCP Server Tools Tests
+ *
+ * Tests the MCP tool handlers with mocked API responses.
+ */
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ApiError } from "../api.js";
+// Helper function mirroring the one in mcp.ts
+function formatErrorHelper(error) {
+    if (error instanceof ApiError) {
+        const body = error.body;
+        const message = body?.message || body?.error?.message || error.message;
+        return `API Error ${error.statusCode}: ${message}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+describe("MCP Server", () => {
+    describe("module loading", () => {
+        it("should export required MCP SDK types", async () => {
+            // Verify the MCP SDK is properly installed and importable
+            const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
+            const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+            expect(Server).toBeDefined();
+            expect(StdioServerTransport).toBeDefined();
+        });
+    });
+});
+describe("MCP Tool Helpers", () => {
+    describe("formatError", () => {
+        it("should format ApiError with message from body", () => {
+            const error = new ApiError("Not found", 404, {
+                message: "Resource missing",
+            });
+            const formatted = formatErrorHelper(error);
+            expect(formatted).toContain("404");
+            expect(formatted).toContain("Resource missing");
+        });
+        it("should format ApiError with nested error message", () => {
+            const error = new ApiError("Bad request", 400, {
+                error: { message: "Invalid input" },
+            });
+            const formatted = formatErrorHelper(error);
+            expect(formatted).toContain("400");
+            expect(formatted).toContain("Invalid input");
+        });
+        it("should format ApiError without body", () => {
+            const error = new ApiError("Server error", 500);
+            const formatted = formatErrorHelper(error);
+            expect(formatted).toBe("API Error 500: Server error");
+        });
+        it("should format regular Error", () => {
+            const error = new Error("Something went wrong");
+            const formatted = formatErrorHelper(error);
+            expect(formatted).toBe("Something went wrong");
+        });
+        it("should format string error", () => {
+            const formatted = formatErrorHelper("Plain string error");
+            expect(formatted).toBe("Plain string error");
+        });
+    });
+});
+describe("MCP Integration", () => {
+    let testDir;
+    beforeEach(async () => {
+        testDir = join(tmpdir(), `funforge-mcp-test-${Date.now()}`);
+        await mkdir(testDir, { recursive: true });
+    });
+    afterEach(async () => {
+        await rm(testDir, { recursive: true, force: true });
+    });
+    describe("tool input validation", () => {
+        it("should validate funforge_apps_create requires name", () => {
+            const toolSchema = {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    slug: { type: "string" },
+                },
+                required: ["name"],
+            };
+            // Valid input
+            const validInput = { name: "My App" };
+            expect(toolSchema.required.every((r) => r in validInput)).toBe(true);
+            // Invalid input (missing name)
+            const invalidInput = { slug: "my-app" };
+            expect(toolSchema.required.every((r) => r in invalidInput)).toBe(false);
+        });
+        it("should validate funforge_env_set requires envVars", () => {
+            const toolSchema = {
+                type: "object",
+                properties: {
+                    directory: { type: "string" },
+                    envVars: { type: "object" },
+                },
+                required: ["envVars"],
+            };
+            const validInput = { envVars: { NODE_ENV: "production" } };
+            expect(toolSchema.required.every((r) => r in validInput)).toBe(true);
+            const invalidInput = { directory: "/some/path" };
+            expect(toolSchema.required.every((r) => r in invalidInput)).toBe(false);
+        });
+        it("should validate funforge_domains_add requires domain", () => {
+            const toolSchema = {
+                type: "object",
+                properties: {
+                    directory: { type: "string" },
+                    domain: { type: "string" },
+                    verificationMethod: { type: "string", enum: ["cname", "txt"] },
+                },
+                required: ["domain"],
+            };
+            const validInput = { domain: "example.com" };
+            expect(toolSchema.required.every((r) => r in validInput)).toBe(true);
+            const invalidInput = { verificationMethod: "cname" };
+            expect(toolSchema.required.every((r) => r in invalidInput)).toBe(false);
+        });
+    });
+    describe("tool definitions", () => {
+        // List of expected tools
+        const expectedTools = [
+            "funforge_whoami",
+            "funforge_apps_list",
+            "funforge_apps_create",
+            "funforge_status",
+            "funforge_deploy",
+            "funforge_env_list",
+            "funforge_env_set",
+            "funforge_env_unset",
+            "funforge_domains_list",
+            "funforge_domains_add",
+        ];
+        it("should define all expected tools", () => {
+            // This is a documentation test to ensure we have all tools
+            expect(expectedTools).toHaveLength(10);
+            expect(expectedTools).toContain("funforge_deploy");
+            expect(expectedTools).toContain("funforge_whoami");
+        });
+    });
+});

package/dist/__tests__/project-config.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Project Config Tests
+ */
+export {};
+//# sourceMappingURL=project-config.test.d.ts.map

package/dist/__tests__/project-config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/project-config.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}