@dtdyq/restbase 1.0.1 → 2.0.0

package/README.md

@@ -21,17 +21,27 @@
 bun install -g @dtdyq/restbase
 ```
 
-安装后直接在任意目录使用 `restbase` 命令：
+安装后在任意目录使用 `restbase` 命令。所有配置通过 `.env` 文件读取：
 
 ```bash
-# 默认 SQLite 内存模式启动
-restbase
+# 生成 .env 配置模板
+restbase env
 
-# 指定数据库和端口
-DB_URL=sqlite://./data.db SVR_PORT=8080 restbase
+# 前台启动（读取当前目录 .env）
+restbase run
 
-# 连接 MySQL
-DB_URL=mysql://user:pass@localhost/mydb restbase
+# 后台启动（daemon 模式）
+restbase start
+
+# 查看运行中的实例（含健康状态）
+restbase status
+
+# 查看某个实例的实时日志
+restbase log <pid>
+
+# 停止
+restbase stop <pid>        # 停止指定实例
+restbase stop all          # 停止所有实例
 ```
 
 更新到最新版：
@@ -44,14 +54,15 @@ bun install -g @dtdyq/restbase@latest
 
 ```bash
 bun install
-bun run server.ts
+bun run src/server.ts
 ```
 
 ### 验证
 
 ```bash
-# 健康检查
+# 健康检查（返回实例状态 + 资源占用）
 curl http://localhost:3333/api/health
+# → { "code": "OK", "data": { "status": "healthy", "port": 3333, "pid": 12345, "uptime": 60, "memory": {...}, "cpu": {...} } }
 
 # Basic Auth 查询
 curl -u admin:admin http://localhost:3333/api/data/products
@@ -78,12 +89,7 @@ const data = await rb.table("products").query().where(gt("price", 100)).data();
 ## 构建与部署
 
 ```bash
-bun run build              # 当前平台
-bun run build:linux        # Linux x64
-bun run build:linux-arm    # Linux ARM64
-bun run build:mac          # macOS x64
-bun run build:mac-arm      # macOS ARM64
-bun run build:windows      # Windows x64
+bun run build              # 编译为当前平台独立二进制
 
 # 运行二进制（无需 Bun 运行时）
 ./restbase
@@ -93,6 +99,7 @@ bun run build:windows      # Windows x64
 
 | 变量                        | 说明                         | 默认值                 |
 |:--------------------------|:---------------------------|:--------------------|
+| `SVR_NAME`                | 实例名称（`status` 中显示）         | 空                   |
 | `SVR_PORT`                | 服务端口                       | `3333`              |
 | `SVR_STATIC`              | 静态文件目录（前端托管）               | 空                   |
 | `SVR_API_LIMIT`           | API 限流（每秒每接口请求数）           | `100`               |
@@ -112,7 +119,7 @@ bun run build:windows      # Windows x64
 ## 测试
 
 ```bash
-bun test rest.test.ts    # 137+ 用例
+bun test src/rest.test.ts    # 137+ 用例
 ```
 
 ## 文档
@@ -124,30 +131,62 @@ bun test rest.test.ts    # 137+ 用例
 | [documents/db_design.md](documents/db_design.md) | 数据库设计指南 — 表结构规范、约束、索引、设计模式与检查清单                   |
 | [documents/design.md](documents/design.md)       | 需求与设计文档 — 架构设计、技术规格、完整接口定义                        |
 
+## CLI 命令
+
+```
+restbase <command> [arguments]
+
+Commands:
+  run              前台启动服务（读取当前目录 .env）
+  start            后台启动（daemon 模式）
+  stop <pid|all>   停止后台实例
+  status           查看运行中的实例（含健康检查）
+  log <pid>        实时查看实例日志
+  env              在当前目录生成 .env 配置模板
+  version          显示版本号
+  help             显示帮助
+```
+
+所有配置通过 `.env` 文件管理，可在 `.env` 中设置 `SVR_NAME` 为实例命名。
+
+实例元数据和默认日志存放在 `~/.restbase/`：
+
+```
+~/.restbase/
+├── instances/          # 实例元数据（name/port/pid/logPath）
+│   ├── 12345.json
+│   └── 23456.json
+└── logs/               # daemon 默认日志目录
+    ├── 3333.log
+    ├── 3333.out
+    └── 8080.log
+```
+
 ## 文件结构
 
 ```
 restbase/
 ├── bin/
-│   └── restbase.ts      # 全局命令入口（bun install -g）
-├── server.ts            # 服务入口
-├── types.ts             # 配置 + 类型 + Zod Schema
-├── db.ts                # 数据库
-├── auth.ts              # 鉴权
-├── crud.ts              # CRUD 路由
-├── query.ts             # SQL 生成
-├── logger.ts            # 日志
+│   └── restbase.ts         # CLI 入口（run/start/stop/status）
+├── src/
+│   ├── server.ts           # 服务启动
+│   ├── types.ts            # 配置 + 类型 + Zod Schema
+│   ├── db.ts               # 数据库
+│   ├── auth.ts             # 鉴权
+│   ├── crud.ts             # CRUD 路由
+│   ├── query.ts            # SQL 生成
+│   ├── logger.ts           # 日志
+│   └── rest.test.ts        # 集成测试
 ├── client/
-│   ├── restbase-client.ts   # 前端客户端（独立 npm 包 @dtdyq/restbase-client）
-│   ├── README.md            # 客户端文档
+│   ├── restbase-client.ts  # 前端客户端（独立 npm 包 @dtdyq/restbase-client）
+│   ├── README.md           # 客户端文档
 │   └── package.json
 ├── documents/
-│   ├── design.md        # 需求设计文档
-│   ├── server.md        # 服务端文档
-│   └── db_design.md     # 数据库设计指南
-├── init.sql             # 初始化 SQL
-├── rest.test.ts         # 集成测试
-├── .env / .env.test     # 环境配置
+│   ├── design.md           # 需求设计文档
+│   ├── server.md           # 服务端文档
+│   └── db_design.md        # 数据库设计指南
+├── init.sql                # 初始化 SQL
+├── .env / .env.test        # 环境配置
 └── package.json
 ```
 

package/bin/restbase.ts

@@ -1,2 +1,541 @@
 #!/usr/bin/env bun
-import "../server.ts";
+/**
+ * bin/restbase.ts — CLI entry point
+ *
+ * Commands:
+ *   restbase run              Start server in foreground (reads .env)
+ *   restbase start            Start server in background (daemon)
+ *   restbase stop <pid|all>   Stop instance(s)
+ *   restbase status           Show running instances (table + health check)
+ *   restbase log <pid>        Tail log of a background instance
+ *   restbase env              Generate .env template in current directory
+ *   restbase version          Show version
+ *   restbase help             Show help
+ *
+ * All configuration is read from .env in the current working directory.
+ * Instance metadata is stored in ~/.restbase/ for global access.
+ */
+
+import {spawn} from "child_process";
+import {
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    unlinkSync,
+    readdirSync,
+    openSync,
+    writeFileSync,
+} from "fs";
+import {resolve, join} from "path";
+import {homedir} from "os";
+
+/* ═══════════ Global paths ═══════════ */
+
+const RESTBASE_HOME = resolve(homedir(), ".restbase");
+const INSTANCES_DIR = join(RESTBASE_HOME, "instances");
+const LOGS_DIR = join(RESTBASE_HOME, "logs");
+
+function ensureDirs() {
+    mkdirSync(INSTANCES_DIR, {recursive: true});
+    mkdirSync(LOGS_DIR, {recursive: true});
+}
+
+/* ═══════════ Instance metadata ═══════════ */
+
+interface InstanceMeta {
+    pid: number;
+    name: string;
+    port: number;
+    logPath: string;
+    cwd: string;
+    startedAt: string;
+}
+
+function instanceFile(pid: number) {
+    return join(INSTANCES_DIR, `${pid}.json`);
+}
+
+function saveInstance(meta: InstanceMeta) {
+    writeFileSync(instanceFile(meta.pid), JSON.stringify(meta, null, 2));
+}
+
+function loadInstance(pid: number): InstanceMeta | null {
+    const f = instanceFile(pid);
+    if (!existsSync(f)) return null;
+    try {
+        return JSON.parse(readFileSync(f, "utf-8")) as InstanceMeta;
+    } catch {
+        return null;
+    }
+}
+
+function loadAllInstances(): InstanceMeta[] {
+    ensureDirs();
+    const files = readdirSync(INSTANCES_DIR).filter((f) => f.endsWith(".json"));
+    const result: InstanceMeta[] = [];
+    for (const f of files) {
+        try {
+            result.push(JSON.parse(readFileSync(join(INSTANCES_DIR, f), "utf-8")));
+        } catch { /* corrupted, skip */ }
+    }
+    return result;
+}
+
+function removeInstance(pid: number) {
+    const f = instanceFile(pid);
+    if (existsSync(f)) unlinkSync(f);
+}
+
+/* ═══════════ Process helpers ═══════════ */
+
+function isAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+interface HealthInfo {
+    status: string;
+    name?: string;
+    port?: number;
+    pid?: number;
+    logFile?: string;
+    startedAt?: string;
+    uptime?: number;
+    memory?: { rss: number; heapUsed: number; heapTotal: number; external: number };
+    cpu?: { user: number; system: number };
+}
+
+async function fetchHealth(port: number): Promise<HealthInfo | null> {
+    try {
+        const res = await fetch(`http://localhost:${port}/api/health`, {
+            signal: AbortSignal.timeout(2000),
+        });
+        const body = (await res.json()) as any;
+        return body?.code === "OK" ? (body.data as HealthInfo) : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Build the command to re-spawn ourselves */
+function getSelfCommand(): string[] {
+    if (
+        process.argv[1] &&
+        (process.argv[1].endsWith(".ts") || process.argv[1].endsWith(".js"))
+    ) {
+        return [process.execPath, process.argv[1]];
+    }
+    return [process.execPath];
+}
+
+/* ═══════════ Commands ═══════════ */
+
+/** run — foreground, reads .env as-is */
+async function cmdRun() {
+    await import("../src/server.ts");
+}
+
+/** start — daemon mode */
+async function cmdStart() {
+    ensureDirs();
+
+    const port = Number(process.env.SVR_PORT) || 3333;
+    const name = process.env.SVR_NAME || "";
+
+    // Reject if this port is already running
+    for (const inst of loadAllInstances()) {
+        if (inst.port === port && isAlive(inst.pid)) {
+            console.log(`RestBase already running on port ${port} (PID: ${inst.pid})`);
+            return;
+        }
+    }
+
+    // Determine log path
+    const logPath = process.env.LOG_FILE
+        ? resolve(process.cwd(), process.env.LOG_FILE)
+        : join(LOGS_DIR, `${port}.log`);
+
+    // Build child env: silence console, ensure LOG_FILE
+    const env: Record<string, string> = {
+        ...(process.env as Record<string, string>),
+        LOG_CONSOLE: "false",
+    };
+    if (!process.env.LOG_FILE) {
+        env.LOG_FILE = logPath;
+    }
+
+    // stdout/stderr → separate crash log (safety net for non-pino output)
+    const stdoutPath = join(LOGS_DIR, `${port}.out`);
+    const out = openSync(stdoutPath, "a");
+    const err = openSync(stdoutPath, "a");
+
+    const self = getSelfCommand();
+    const child = spawn(self[0]!, [...self.slice(1), "run"], {
+        detached: true,
+        stdio: ["ignore", out, err],
+        env,
+        cwd: process.cwd(),
+    });
+    child.unref();
+
+    // Save instance metadata
+    saveInstance({
+        pid: child.pid!,
+        name,
+        port,
+        logPath,
+        cwd: process.cwd(),
+        startedAt: new Date().toISOString(),
+    });
+
+    console.log(`RestBase started (PID: ${child.pid}, port: ${port})`);
+}
+
+/** stop — by PID or "all" */
+function cmdStop(target: string) {
+    if (target === "all") {
+        const instances = loadAllInstances();
+        if (instances.length === 0) {
+            console.log("No RestBase instances found");
+            return;
+        }
+        for (const inst of instances) stopOne(inst.pid);
+        return;
+    }
+
+    const pid = parseInt(target, 10);
+    if (isNaN(pid)) {
+        console.error(`Invalid PID: ${target}`);
+        process.exit(1);
+    }
+    stopOne(pid);
+}
+
+function stopOne(pid: number) {
+    const meta = loadInstance(pid);
+    if (!meta) {
+        console.log(`No instance found with PID ${pid}`);
+        return;
+    }
+    try {
+        if (isAlive(pid)) process.kill(pid, "SIGTERM");
+        removeInstance(pid);
+        console.log(`Stopped PID ${pid} (port ${meta.port})`);
+    } catch {
+        removeInstance(pid);
+        console.log(`Process ${pid} already gone, cleaned up`);
+    }
+}
+
+/** Format seconds into human readable uptime */
+function fmtUptime(sec: number): string {
+    if (sec < 60) return `${sec}s`;
+    if (sec < 3600) return `${Math.floor(sec / 60)}m${sec % 60}s`;
+    const h = Math.floor(sec / 3600);
+    const m = Math.floor((sec % 3600) / 60);
+    if (h < 24) return `${h}h${m}m`;
+    const d = Math.floor(h / 24);
+    return `${d}d${h % 24}h`;
+}
+
+/** Format bytes into human readable size */
+function fmtBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+    if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}
+
+/** Format CPU microseconds into human readable percentage (approx) */
+function fmtCpu(userUs: number, systemUs: number, uptimeSec: number): string {
+    if (uptimeSec <= 0) return "-";
+    const totalUs = userUs + systemUs;
+    const pct = (totalUs / (uptimeSec * 1_000_000)) * 100;
+    return `${pct.toFixed(1)}%`;
+}
+
+/** Format ISO timestamp to local short form: MM-DD HH:mm:ss */
+function fmtTime(iso: string): string {
+    const d = new Date(iso);
+    const MM = String(d.getMonth() + 1).padStart(2, "0");
+    const DD = String(d.getDate()).padStart(2, "0");
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    const ss = String(d.getSeconds()).padStart(2, "0");
+    return `${MM}-${DD} ${hh}:${mm}:${ss}`;
+}
+
+/** status — table with health check */
+async function cmdStatus() {
+    const instances = loadAllInstances();
+    if (instances.length === 0) {
+        console.log("No RestBase instances found");
+        return;
+    }
+
+    // Column widths
+    const nW = 14, pW = 9, sW = 14, ptW = 7, stW = 17, uW = 10, mW = 10, cW = 8;
+
+    console.log(
+        "NAME".padEnd(nW) +
+        "PID".padEnd(pW) +
+        "STATE".padEnd(sW) +
+        "PORT".padEnd(ptW) +
+        "STARTED".padEnd(stW) +
+        "UPTIME".padEnd(uW) +
+        "MEM".padEnd(mW) +
+        "CPU".padEnd(cW) +
+        "LOG",
+    );
+    console.log("─".repeat(nW + pW + sW + ptW + stW + uW + mW + cW + 30));
+
+    for (const inst of instances) {
+        // Dead process → clean up silently
+        if (!isAlive(inst.pid)) {
+            removeInstance(inst.pid);
+            continue;
+        }
+
+        // Fetch live info from health endpoint
+        const health = await fetchHealth(inst.port);
+
+        const name = health?.name || inst.name || "-";
+        const state = health?.status ?? "unreachable";
+        const started = health?.startedAt ? fmtTime(health.startedAt) : fmtTime(inst.startedAt);
+        const uptime = health?.uptime !== undefined ? fmtUptime(health.uptime) : "-";
+        const mem = health?.memory ? fmtBytes(health.memory.rss) : "-";
+        const cpu = (health?.cpu && health?.uptime)
+            ? fmtCpu(health.cpu.user, health.cpu.system, health.uptime)
+            : "-";
+        const logPath = health?.logFile || inst.logPath;
+
+        console.log(
+            name.padEnd(nW) +
+            String(inst.pid).padEnd(pW) +
+            state.padEnd(sW) +
+            String(inst.port).padEnd(ptW) +
+            started.padEnd(stW) +
+            uptime.padEnd(uW) +
+            mem.padEnd(mW) +
+            cpu.padEnd(cW) +
+            logPath,
+        );
+    }
+}
+
+/**
+ * Find the latest log file matching the base path.
+ * pino-roll creates files like: app.2026-02-11.1.log (date + sequence inserted before extension)
+ * So for base "log/app.log", we look for "app*.log" in "log/".
+ */
+function findLatestLog(basePath: string): string | null {
+    // If exact file exists, use it
+    if (existsSync(basePath)) return basePath;
+
+    const dir = resolve(basePath, "..");
+    if (!existsSync(dir)) return null;
+
+    const base = basePath.split("/").pop()!;           // "app.log"
+    const dot = base.lastIndexOf(".");
+    const stem = dot > 0 ? base.slice(0, dot) : base;  // "app"
+    const ext = dot > 0 ? base.slice(dot) : "";         // ".log"
+
+    // Find all matching files, sort by mtime descending
+    const files = readdirSync(dir)
+        .filter((f) => f.startsWith(stem) && f.endsWith(ext) && f !== base)
+        .map((f) => ({name: f, mtime: Bun.file(join(dir, f)).lastModified}))
+        .sort((a, b) => b.mtime - a.mtime);
+
+    return files.length > 0 ? join(dir, files[0]!.name) : null;
+}
+
+/** log — tail -f the log file of an instance */
+async function cmdLog(target: string) {
+    const pid = parseInt(target, 10);
+    if (isNaN(pid)) {
+        console.error(`Invalid PID: ${target}`);
+        process.exit(1);
+    }
+
+    const meta = loadInstance(pid);
+    if (!meta) {
+        console.error(`No instance found with PID ${pid}`);
+        process.exit(1);
+    }
+
+    const logFile = findLatestLog(meta.logPath);
+    if (!logFile) {
+        console.error(`Log file not found for base path: ${meta.logPath}`);
+        process.exit(1);
+    }
+
+    console.log(`Tailing ${logFile} (Ctrl+C to stop)\n`);
+
+    const tail = spawn("tail", ["-f", "-n", "100", logFile], {
+        stdio: "inherit",
+    });
+
+    process.on("SIGINT", () => {
+        tail.kill();
+        process.exit(0);
+    });
+
+    await new Promise<void>((resolve) => tail.on("close", () => resolve()));
+}
+
+/** env — generate .env template */
+function cmdEnv() {
+    const envPath = resolve(process.cwd(), ".env");
+    if (existsSync(envPath)) {
+        console.log(`.env already exists at ${envPath}`);
+        console.log("Remove it first if you want to regenerate.");
+        return;
+    }
+
+    const content = `# ═══════════════════════════════════════════════════════════
+# RestBase Configuration
+# ═══════════════════════════════════════════════════════════
+# Uncomment and modify the values you need.
+# All variables have sensible defaults — you can start with
+# an empty .env and only override what you need.
+# ═══════════════════════════════════════════════════════════
+
+# ── Server ────────────────────────────────────────────────
+
+# SVR_NAME=                         # Instance name (shown in 'restbase status')
+# SVR_PORT=3333                     # Server port
+# SVR_STATIC=                       # Static file directory for SPA hosting
+# SVR_API_LIMIT=100                 # Rate limit: max requests per second per API
+
+# ── Database ──────────────────────────────────────────────
+
+# DB_URL=sqlite://:memory:          # sqlite://<path> or mysql://user:pass@host/db
+# DB_AUTH_TABLE=users                # Auth table name
+# DB_AUTH_FIELD=owner                # Owner field name for tenant isolation
+# DB_AUTH_FIELD_NULL_OPEN=false      # Treat owner=NULL rows as public data
+# DB_INIT_SQL=                       # SQL file to run on startup
+
+# ── Auth ──────────────────────────────────────────────────
+
+# AUTH_JWT_SECRET=restbase           # JWT secret — CHANGE THIS IN PRODUCTION!
+# AUTH_JWT_EXP=43200                 # JWT expiry in seconds (default: 12 hours)
+# AUTH_BASIC_OPEN=true               # Enable Basic Auth
+
+# ── Logging ───────────────────────────────────────────────
+
+# LOG_LEVEL=INFO                     # ERROR / INFO / DEBUG
+# LOG_CONSOLE=true                   # Console output (auto-disabled in daemon mode)
+# LOG_FILE=                          # Log file path (auto-configured in daemon mode)
+# LOG_RETAIN_DAYS=7                  # Log file retention days
+`;
+
+    writeFileSync(envPath, content);
+    console.log(`Created ${envPath}`);
+}
+
+/** version */
+async function cmdVersion() {
+    const pkg = (await import("../package.json")).default;
+    console.log(`RestBase v${pkg.version}`);
+}
+
+/** help */
+function printHelp() {
+    console.log(`
+RestBase — Zero-code REST API server for SQLite / MySQL
+
+Usage:
+  restbase <command> [arguments]
+
+Commands:
+  run              Start server in foreground (reads .env)
+  start            Start server in background (daemon mode)
+  stop <pid|all>   Stop a background instance by PID, or stop all
+  status           Show all running background instances
+  log <pid>        Tail the log of a background instance
+  env              Generate a .env template in current directory
+  version          Show version
+  help             Show this help
+
+Examples:
+  restbase run                Start in foreground
+  restbase start              Start in background (daemon)
+  restbase status             List running instances with health status
+  restbase log 12345          Tail log for instance with PID 12345
+  restbase stop 12345         Stop instance with PID 12345
+  restbase stop all           Stop all background instances
+  restbase env                Create a documented .env template
+
+Configuration:
+  All settings are read from .env in the current working directory.
+  Run 'restbase env' to generate a documented template with all options.
+
+Instance data is stored in ~/.restbase/ (PID files, logs, metadata).
+`);
+}
+
+/* ═══════════ Main ═══════════ */
+
+const command = process.argv[2] || "run";
+const arg1 = process.argv[3];
+
+switch (command) {
+    case "run":
+        await cmdRun();
+        break;
+
+    case "start":
+        await cmdStart();
+        process.exit(0);
+        break;
+
+    case "stop":
+        if (!arg1) {
+            console.error("Usage: restbase stop <pid|all>");
+            process.exit(1);
+        }
+        cmdStop(arg1);
+        process.exit(0);
+        break;
+
+    case "status":
+        await cmdStatus();
+        process.exit(0);
+        break;
+
+    case "log":
+        if (!arg1) {
+            console.error("Usage: restbase log <pid>");
+            process.exit(1);
+        }
+        await cmdLog(arg1);
+        break;
+
+    case "env":
+        cmdEnv();
+        process.exit(0);
+        break;
+
+    case "version":
+    case "-v":
+    case "--version":
+        await cmdVersion();
+        process.exit(0);
+        break;
+
+    case "help":
+    case "-h":
+    case "--help":
+        printHelp();
+        process.exit(0);
+        break;
+
+    default:
+        console.error(`Unknown command: ${command}`);
+        console.error("Run 'restbase help' for usage.");
+        process.exit(1);
+}