server-config-cli/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

• npm install — first-time setup.
• npm run build — bundles src/app.jsx (and everything it imports) to dist/app.mjs via esbuild. Required before the CLI can run; bin/server-config.js exits with an error if the bundle is missing.
• npm run build:watch — rebuild on change.
• npm test — runs node --test test/*.test.js against the pure-logic library tests.
• npm run check — syntax-checks every hand-written .js file (does not check .jsx — they're consumed by esbuild).
• node bin/server-config.js — launch the TUI (or server-config after npm link). It refuses to start until npm run build has been run.

Requirements: Node ≥18, but in practice ≥20 because Ink 7 + React 19 expect modern runtimes. The TUI requires a real TTY on stdin/stdout; running with redirected stdin will fail with "Raw mode is not supported".

Architecture

The project is split into three layers. Do not let UI concerns leak into the logic layers, and do not call child_process.spawn from anywhere other than the runner — that single chokepoint is what gives the TUI its uniform spinner/log behavior.

1. Pure logic — src/lib/

• frp-config.js (CJS) — parser/renderer for frpc.toml. Lossy TOML-ish: accepts both legacy [name] headers and modern [[proxies]] arrays, migrates legacy ini keys (server_addr → serverAddr, token → auth.token, etc.) on read, and always emits the modern form. Internal proxy values are snake_case (local_ip, local_port, remote_port) but rendered camelCase (localIP, localPort, remotePort). createUniqueProxyName appends a random 8-char hex suffix to avoid collisions.
• tasks.js (CJS) — plan builders. Each public function (zshInstallPlan, sshInstallPlan, frpInstallPlan, frpInitConfigPlan, frpAddProxyPlan, frpRemoveProxyPlan, frpRestartPlan, bootstrapPlan) returns { title, steps[] }. Steps come in three kinds: run (spawn a command), write (write a file, possibly via sudo tee), zshrc-plugins (in-place edit of ~/.zshrc). Plan builders may read the filesystem (e.g. to preserve existing proxies on --force re-init) and may throw — call sites must catch.
• runner.js (CJS) — startRun(steps) returns an EventEmitter-backed object that executes the step list and emits step-start, log (stdout/stderr lines), step-done, and done events. The runner owns all child_process.spawn calls and is the only place that touches stdio. Privileged writes go through sudo tee when canWriteDirectly returns false. cancel() SIGTERMs the active child.

The tests (test/frp-config.test.js) only exercise frp-config.js. They're plain node:test and import via require, so keep the lib modules in CJS.

2. Ink screens — src/screens/*.jsx

A small screen-stack lives in src/app.jsx: {stack: Screen[]} with push, replace, back, home. Each screen is a self-contained component that takes nav (the navigation helpers) and any screen-specific props. Adding a new screen = new file in src/screens/, new case in the renderScreen switch in app.jsx.

Screens in dependency order:

• MainMenu → FrpMenu (submenu) or PlanPreview (for zsh/ssh) or TokenPrompt (for bootstrap).
• TokenPrompt → FrpConfigForm (collects serverAddr/serverPort/installDir).
• FrpConfigForm / ProxyForm build a plan and replace to PlanPreview.
• ProxyList → PlanPreview (for a remove plan).
• PlanPreview → RunLog (the only place that calls runner.startRun).
• RunLog subscribes to runner events with useReducer; the last MAX_LOG_LINES (12) lines of streamed output are shown in a bordered scrollback.

Forms use a step index plus arrow-key/Tab traversal between <TextInput focus={...} /> widgets. Avoid pulling in a forms library — the pattern is small enough to keep inline.

3. Entry/build — bin/, dist/, esbuild

bin/server-config.js is a CJS shim that import()s dist/app.mjs. The bundle is ESM because Ink 7 + yoga-layout use top-level await, which esbuild cannot lower to CJS — that's why --format=esm is non-negotiable.

Two esbuild quirks worth knowing:

1. react-devtools-core is aliased to a stub (src/stubs/react-devtools-core.js). Ink imports it behind a process.env.DEV === "true" check, but esbuild hoists ESM imports to module-load time, so we'd otherwise execute the real package's UMD preamble (which references self) and crash. Keep the alias; do not change to --external (that reintroduces the crash at runtime).
2. The --banner:js injects a createRequire so CJS lib modules called from the bundle can still use require(...). Don't drop it without also rewriting the libs to ESM.

The bundle is ~1.8 MB — that's mostly React + Yoga, not something to fight.

Sensitive values & defaults

The FRP token comes from the TokenPrompt screen or the FRP_TOKEN env var (the screen pre-fills from env). It is never logged or persisted outside the rendered frpc.toml. Defaults that callers depend on: server 81.70.134.9:15443, install dir /opt/frp/frp_<version>_linux_<arch>, systemd unit frpc, frp version 0.58.1. Changing any is a breaking change for existing deployments.

When adding a new task type

1. Add a plan builder in src/lib/tasks.js returning { title, steps }.
2. If you need a new step kind (beyond run / write / zshrc-plugins), extend the runStep switch in src/lib/runner.js and formatStep for the preview label.
3. Add a screen (or extend an existing menu) that constructs the plan and pushes { name: "plan", props: { plan } }.

Never spawn commands directly from a screen — always build a plan and route it through PlanPreview → RunLog so the user sees what's about to happen and gets uniform log/spinner UI.