@vlandoss/localproxy 0.0.1-git-9eaaf74.0

package/README.md

@@ -0,0 +1,50 @@
+# 🛠️ localproxy
+
+**Simple local development proxy automation with Caddy + hosts management**
+
+Stop remembering ports! localproxy automatically maps your projects to clean `.localhost` domains with automatic HTTPS and hosts file management.
+
+```bash
+# Instead of this mess:
+http://localhost:3000  # Which project was this?
+http://localhost:4000  # And this?
+http://localhost:5431  # 🤔
+
+# Get this:
+http://frontend.localhost
+http://api.localhost
+http://admin.localhost
+```
+
+## Prerequisites
+
+- Bun >= 1.2.4
+- Caddy >= 2.8.4
+- hosts >= 3.6.4
+
+## Installation
+
+```sh
+pnpm add -g @vlandoss/localproxy
+```
+
+It will adds the `localproxy` to your global workspace
+
+## Usage
+
+> [!NOTE]
+> The documentation is WIP
+
+Run the help command:
+
+```sh
+localproxy help
+```
+
+## Troubleshooting
+
+To enable debug mode, set the `DEBUG` environment variable to `localproxy:*` before running *any* command.
+
+```sh
+DEBUG=localproxy:* localproxy <command>
+```

package/bin.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+import { homedir } from "node:os";
+import path from "node:path";
+import { main } from "./src/main";
+
+main({
+  binDir: __dirname,
+  installDir: path.join(homedir(), ".localproxy"),
+});

package/config/Caddyfile.example

@@ -0,0 +1,3 @@
+my-app.localhost {
+    reverse_proxy localhost:3000
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@vlandoss/localproxy",
+  "version": "0.0.1-git-9eaaf74.0",
+  "description": "Simple local development proxy automation",
+  "homepage": "https://github.com/variableland/dx/tree/main/packages/localproxy#readme",
+  "bugs": {
+    "url": "https://github.com/variableland/dx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variableland/dx.git"
+  },
+  "license": "MIT",
+  "author": "rcrd <rcrd@variable.land>",
+  "type": "module",
+  "bin": {
+    "localproxy": "./bin.ts",
+    "localp": "./bin.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "config"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^7.8.4",
+    "commander": "13.1.0",
+    "@vlandoss/loggy": "0.0.4-git-9eaaf74.0",
+    "@vlandoss/clibuddy": "0.0.5-git-9eaaf74.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/commands/clean.ts

@@ -0,0 +1,27 @@
+import { createCommand } from "commander";
+import { CaddyService } from "~/services/caddy";
+import { HostsService } from "~/services/hosts";
+import { logger } from "~/services/logger";
+import type { Context } from "~/types";
+
+type CommandOptions = {
+  verbose: boolean;
+};
+
+export function createCleanCommand({ caddyfilePath }: Context) {
+  return createCommand("clean")
+    .description("clean up config files")
+    .option("--verbose", "verbose mode, show background output", false)
+    .action(async (options: CommandOptions) => {
+      const caddyService = new CaddyService(caddyfilePath);
+      await caddyService.stop(options);
+
+      const localDomains = caddyService.getLocalDomains();
+      const hosts = localDomains.map((d) => d.host);
+
+      const hostsService = new HostsService(hosts);
+      await hostsService.clean(options);
+
+      logger.success("localproxy clean completed");
+    });
+}

package/src/commands/setup.ts

@@ -0,0 +1,88 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { editor } from "@inquirer/prompts";
+import { createCommand } from "commander";
+import { CaddyService } from "~/services/caddy";
+import { HostsService } from "~/services/hosts";
+import { logger } from "~/services/logger";
+import { quietShell } from "~/services/shell";
+import type { Context } from "~/types";
+
+type CommandOptions = {
+  verbose: boolean;
+};
+
+const debug = logger.subdebug("setup");
+
+async function printFile(filePath: string) {
+  const fileContent = (await fs.readFile(filePath)).toString();
+
+  console.log(`${filePath}:\n`);
+  console.log(fileContent.trim());
+}
+
+async function checkInternalTools() {
+  const { $ } = quietShell;
+
+  const caddyVersion = await $`caddy --version`.nothrow();
+
+  if (caddyVersion.exitCode) {
+    logger.error("Caddy is not installed. Please install Caddy first:");
+    logger.info("macOS: brew install caddy");
+    logger.info("Linux: https://caddyserver.com/docs/install");
+    process.exit(1);
+  }
+
+  debug("Caddy version: %s", caddyVersion.stdout.trim());
+
+  const hostsVersion = await $`hosts --version`.nothrow();
+
+  if (!hostsVersion) {
+    logger.error("hosts CLI tool is not installed. Please install hosts first:");
+    logger.info("macOS: brew tap xwmx/taps && brew install hosts");
+    logger.info("Linux: Check https://github.com/xwmx/hosts for installation");
+    process.exit(1);
+  }
+
+  debug("hosts version: %s", hostsVersion.stdout.trim());
+}
+
+export function createSetupCommand({ binDir, installDir, caddyfilePath }: Context) {
+  return createCommand("setup")
+    .description("setup config files")
+    .option("--verbose", "verbose mode, show background output", false)
+    .action(async (options: CommandOptions) => {
+      debug("setup command options %o", options);
+
+      await checkInternalTools();
+
+      if (!(await fs.exists(installDir))) {
+        await fs.mkdir(installDir);
+      }
+
+      const exampleCaddyFilePath = path.join(binDir, "config", "Caddyfile.example");
+      const defaultContent = (await fs.exists(caddyfilePath))
+        ? await fs.readFile(caddyfilePath, "utf-8")
+        : await fs.readFile(exampleCaddyFilePath, "utf-8");
+
+      const fileContent = await editor({
+        message: "Caddyfile",
+        default: defaultContent,
+      });
+
+      await fs.writeFile(caddyfilePath, fileContent);
+
+      await printFile(caddyfilePath);
+
+      const caddyService = new CaddyService(caddyfilePath);
+      await caddyService.reboot(options);
+
+      const localDomains = caddyService.getLocalDomains();
+      const hosts = localDomains.map((d) => d.host);
+
+      const hostsService = new HostsService(hosts);
+      await hostsService.setup(options);
+
+      logger.success("localproxy setup completed");
+    });
+}

package/src/commands/start.ts

@@ -0,0 +1,20 @@
+import { createCommand } from "commander";
+import { CaddyService } from "~/services/caddy";
+import { logger } from "~/services/logger";
+import type { Context } from "~/types";
+
+type CommandOptions = {
+  verbose: boolean;
+};
+
+export function createStartCommand({ caddyfilePath }: Context) {
+  return createCommand("start")
+    .description("start caddy server")
+    .option("--verbose", "verbose mode, show background output", false)
+    .action(async (options: CommandOptions) => {
+      const caddyService = new CaddyService(caddyfilePath);
+      await caddyService.start(options);
+
+      logger.success("localproxy start completed");
+    });
+}

package/src/commands/status.ts

@@ -0,0 +1,36 @@
+import { createCommand } from "commander";
+import { CaddyService } from "~/services/caddy";
+import { HostsService } from "~/services/hosts";
+import { logger } from "~/services/logger";
+import type { Context } from "~/types";
+
+export function createStatusCommand({ caddyfilePath }: Context) {
+  return createCommand("status")
+    .description("show configured localhosts")
+    .option("--verbose", "verbose mode, show background output", false)
+    .action(async () => {
+      const caddyService = new CaddyService(caddyfilePath);
+
+      if (await caddyService.isRunning()) {
+        logger.info("Caddy is running");
+      } else {
+        logger.warn("Caddy is not running");
+      }
+
+      const localDomains = caddyService.getLocalDomains();
+      const hosts = localDomains.map((d) => d.host);
+
+      const hostsService = new HostsService(hosts);
+
+      for (const domain of localDomains) {
+        const { host, port } = domain;
+        const found = await hostsService.findHost(host);
+
+        if (found) {
+          logger.success("%s is configured -> :%s", host, port);
+        } else {
+          logger.warn("%s is not configured -> :%s", host, port);
+        }
+      }
+    });
+}

package/src/commands/stop.ts

@@ -0,0 +1,20 @@
+import { createCommand } from "commander";
+import { CaddyService } from "~/services/caddy";
+import { logger } from "~/services/logger";
+import type { Context } from "~/types";
+
+type CommandOptions = {
+  verbose: boolean;
+};
+
+export function createStopCommand({ caddyfilePath }: Context) {
+  return createCommand("stop")
+    .description("stop caddy server")
+    .option("--verbose", "verbose mode, show background output", false)
+    .action(async (options: CommandOptions) => {
+      const caddyService = new CaddyService(caddyfilePath);
+      await caddyService.stop(options);
+
+      logger.success("localproxy stop completed");
+    });
+}

package/src/main.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { createPkgService, getVersion } from "@vlandoss/clibuddy";
+import { createCommand } from "commander";
+import { createCleanCommand } from "./commands/clean";
+import { createSetupCommand } from "./commands/setup";
+import { createStartCommand } from "./commands/start";
+import { createStatusCommand } from "./commands/status";
+import { createStopCommand } from "./commands/stop";
+import { logger } from "./services/logger";
+import type { Context, ProgramOptions } from "./types";
+import { BANNER_TEXT, CREDITS_TEXT } from "./ui";
+
+async function createContext({ binDir, installDir }: ProgramOptions) {
+  const binPkg = await createPkgService(binDir);
+
+  if (!binPkg) {
+    throw new Error("Could not find bin package.json");
+  }
+
+  return {
+    installDir,
+    caddyfilePath: path.join(installDir, "Caddyfile"),
+    binDir,
+    binPkg,
+  } satisfies Context;
+}
+
+async function createProgram(options: ProgramOptions) {
+  const ctx = await createContext(options);
+
+  return createCommand("localproxy")
+    .alias("localp")
+    .version(getVersion(ctx.binPkg), "-v, --version")
+    .addHelpText("before", BANNER_TEXT)
+    .addHelpText("after", CREDITS_TEXT)
+    .addCommand(createSetupCommand(ctx))
+    .addCommand(createStatusCommand(ctx))
+    .addCommand(createStartCommand(ctx))
+    .addCommand(createStopCommand(ctx))
+    .addCommand(createCleanCommand(ctx));
+}
+
+export async function main(options: ProgramOptions) {
+  try {
+    const program = await createProgram(options);
+    await program.parseAsync();
+  } catch (error) {
+    logger.error("Cannot run main successfully", error);
+    process.exit(1);
+  }
+}

package/src/services/caddy.ts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { logger } from "./logger";
+import { quietShell, silentShell, verboseShell } from "./shell";
+
+const debug = logger.subdebug("caddy");
+
+type ExecOption = {
+  verbose: boolean;
+};
+
+export type LocalDomain = {
+  host: string;
+  port: string;
+};
+
+export class CaddyService {
+  #configPath: string;
+  #pidFilePath: string;
+
+  constructor(configPath: string) {
+    this.#configPath = configPath;
+    this.#pidFilePath = path.join(path.dirname(configPath), "caddy.pid");
+    this.#initCaddyPid();
+  }
+
+  #initCaddyPid() {
+    if (!this.#hasCaddyPid()) {
+      fs.writeFileSync(this.#pidFilePath, "");
+    }
+  }
+
+  #hasCaddyPid() {
+    return fs.existsSync(this.#pidFilePath);
+  }
+
+  #deleteCaddyPid() {
+    if (this.#hasCaddyPid()) {
+      fs.rmSync(this.#pidFilePath);
+    }
+  }
+
+  #shell({ verbose }: ExecOption) {
+    return verbose ? verboseShell : silentShell;
+  }
+
+  async reboot(options: ExecOption) {
+    const isRunning = await this.isRunning();
+    if (isRunning) {
+      await this.stop(options);
+    }
+    await this.start(options);
+  }
+
+  async start({ verbose }: ExecOption) {
+    const { $ } = this.#shell({ verbose });
+
+    try {
+      debug("Starting Caddy...");
+
+      await $`caddy start -c ${this.#configPath} --pidfile ${this.#pidFilePath} > /dev/null 2>&1`;
+
+      debug("Caddy started");
+    } catch {
+      logger.error("Can't start Caddy");
+      process.exit(1);
+    }
+  }
+
+  async stop({ verbose }: ExecOption) {
+    const { $ } = this.#shell({ verbose });
+
+    try {
+      debug("Stopping Caddy...");
+
+      await $`caddy stop -c ${this.#configPath}`;
+      this.#deleteCaddyPid();
+
+      debug("Caddy stopped");
+    } catch {
+      logger.error("Can't stop Caddy");
+      process.exit(1);
+    }
+  }
+
+  async isRunning() {
+    if (!this.#hasCaddyPid()) {
+      return false;
+    }
+
+    const pid = (await quietShell.$`cat ${this.#pidFilePath}`.text()).trim();
+
+    debug("Caddy PID: %d", pid);
+
+    const { exitCode } = await quietShell.$`kill -0 ${pid}`.nothrow();
+    const isRunning = exitCode === 0;
+
+    debug("Caddy is %s", isRunning ? "running" : "stopped");
+
+    return isRunning;
+  }
+
+  getLocalDomains(): LocalDomain[] {
+    const caddyfileContent = fs.readFileSync(this.#configPath, "utf-8");
+
+    const REGEX = /^(.+)\.localhost/gm;
+    const matches = caddyfileContent.matchAll(REGEX);
+
+    const hosts = Array.from(matches, (m) => m[0]).filter(Boolean) as string[];
+
+    const localDomains: LocalDomain[] = hosts.map((host) => {
+      const index = caddyfileContent.indexOf(host);
+      const port = caddyfileContent.slice(index).match(/localhost:(\d+)/)?.[1] || "80";
+      return { host, port };
+    });
+
+    debug("detected domains: %o", localDomains);
+
+    return localDomains;
+  }
+}

package/src/services/hosts.ts

@@ -0,0 +1,60 @@
+import { logger } from "./logger";
+import { quietShell, silentShell, verboseShell } from "./shell";
+
+type SetupOptions = {
+  verbose: boolean;
+};
+
+const debug = logger.subdebug("hosts");
+
+export class HostsService {
+  #hosts: string[];
+
+  constructor(domains: string[]) {
+    this.#hosts = domains;
+  }
+
+  #shell({ verbose }: SetupOptions) {
+    return verbose ? verboseShell : silentShell;
+  }
+
+  async setup(options: SetupOptions) {
+    verboseShell.$`sudo hosts backups create`;
+
+    for (const host of this.#hosts) {
+      await this.addHost(host, options);
+    }
+  }
+
+  async clean(options: SetupOptions) {
+    for (const host of this.#hosts) {
+      await this.removeHost(host, options);
+    }
+  }
+
+  async findHost(host: string) {
+    const currentHost = await quietShell.$`hosts show "${host}"`.text();
+    debug("Host %s is %s", host, currentHost ? "present" : "absent");
+    return currentHost;
+  }
+
+  async addHost(host: string, options: SetupOptions) {
+    const { $ } = this.#shell(options);
+
+    const currentHost = await this.findHost(host);
+
+    if (!currentHost) {
+      await $`sudo hosts add 127.0.0.1 ${host}`;
+    }
+  }
+
+  async removeHost(host: string, options: SetupOptions) {
+    const { $ } = this.#shell(options);
+
+    const currentHost = await this.findHost(host);
+
+    if (!currentHost) {
+      await $`sudo hosts remove ${host}`;
+    }
+  }
+}

package/src/services/logger.ts

@@ -0,0 +1,5 @@
+import { createLoggy } from "@vlandoss/loggy";
+
+export const logger = createLoggy({
+  namespace: "localproxy",
+});

package/src/services/shell.ts

@@ -0,0 +1,15 @@
+import { createShellService } from "@vlandoss/clibuddy";
+
+export const quietShell = createShellService({
+  quiet: true,
+  verbose: false,
+});
+
+export const silentShell = quietShell.child({
+  stdio: ["ignore", "ignore", "ignore"],
+});
+
+export const verboseShell = quietShell.child({
+  quiet: false,
+  verbose: true,
+});

package/src/types.ts

@@ -0,0 +1,13 @@
+import type { PkgService } from "@vlandoss/clibuddy";
+
+export type ProgramOptions = {
+  binDir: string;
+  installDir: string;
+};
+
+export type Context = {
+  binDir: string;
+  installDir: string;
+  caddyfilePath: string;
+  binPkg: PkgService;
+};

package/src/ui.ts

@@ -0,0 +1,12 @@
+import { colors } from "@vlandoss/clibuddy";
+
+export const UI_LOGO = `🛠️ ${colors.bold("localproxy")}`;
+
+export const BANNER_TEXT = `${UI_LOGO}: Simple local development proxy automation\n`;
+
+export const CREDITS_TEXT = `\nAcknowledgment:
+- Caddy: for being a powerful proxy server
+  https://caddyserver.com
+
+- hosts: making it easier to manage host file
+  https://github.com/xwmx/hosts`;