@yinuo-ngm/server 1.0.0

package/lib/routes/system.routes.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from "fastify";
+export default function systemRoutes(fastify: FastifyInstance): Promise<void>;

package/lib/routes/system.routes.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = systemRoutes;
+const env_1 = require("../env");
+async function systemRoutes(fastify) {
+    fastify.get("/health", async () => ({
+        ts: Date.now(),
+        name: "ngm-server",
+        pid: process.pid,
+        uptime: process.uptime(),
+        version: process.env.npm_package_version,
+        dataDir: env_1.env.dataDir
+    }));
+    fastify.post("/shutdown", async () => {
+        fastify.log.info("Shutdown requested via /shutdown");
+        setTimeout(async () => {
+            try {
+                await fastify.close();
+                process.exit(0);
+            }
+            catch (e) {
+                console.error("Graceful shutdown failed", e);
+                process.exit(1);
+            }
+        }, 50);
+        return { ok: true };
+    });
+}

package/lib/routes/task.routes.d.ts

@@ -0,0 +1,2 @@
+import type { FastifyInstance } from "fastify";
+export default function taskRoutes(fastify: FastifyInstance): Promise<void>;

package/lib/routes/task.routes.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = taskRoutes;
+const core_1 = require("@yinuo-ngm/core");
+async function ensureSpecs(fastify, projectId) {
+    const specs = await fastify.core.task.listSpecsByProject(projectId);
+    if (specs.length === 0) {
+        await fastify.core.task.refreshByProject(projectId);
+    }
+}
+async function taskRoutes(fastify) {
+    fastify.get("/list/:projectId", async (req) => {
+        const { projectId } = req.params;
+        await ensureSpecs(fastify, projectId);
+        return fastify.core.task.listViewsByProject(projectId);
+    });
+    fastify.post("/refresh/:projectId", async (req) => {
+        const { projectId } = req.params;
+        return await fastify.core.task.refreshByProject(projectId);
+    });
+    fastify.post("/start", async (req) => {
+        const body = req.body;
+        const taskId = body?.taskId?.trim();
+        if (!taskId)
+            throw new core_1.AppError("TASK_ID_REQUIRED", "taskId is required", { body });
+        return await fastify.core.task.start(taskId);
+    });
+    fastify.post("/stop", async (req) => {
+        const body = req.body;
+        const taskId = body?.taskId?.trim();
+        if (!taskId)
+            throw new core_1.AppError("TASK_ID_REQUIRED", "taskId is required", { body });
+        return await fastify.core.task.stop(taskId);
+    });
+    fastify.get("/status/:taskId", async (req) => {
+        const { taskId } = req.params;
+        return await fastify.core.task.status(taskId);
+    });
+    fastify.get("/active", async () => {
+        return await fastify.core.task.listActive();
+    });
+    fastify.get("/log/run/:runId", async (req) => {
+        const { runId } = req.params;
+        const { tail } = req.query;
+        const limit = Math.min(Math.max(Number(tail) || 200, 1), 5000);
+        return await fastify.core.task.getTailLogsByRun(runId, limit);
+    });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@yinuo-ngm/server",
+  "version": "1.0.0",
+  "description": "",
+  "main": "lib/index.js",
+  "keywords": [],
+  "author": "ZhangJing",
+  "license": "ISC",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node lib/index.js"
+  },
+  "dependencies": {
+    "@fastify/static": "^9.0.0",
+    "@fastify/websocket": "^11.2.0",
+    "@yinuo-ngm/core": "^0.1.0",
+    "@types/node": "^25.0.3",
+    "fastify": "^5.6.2",
+    "fastify-plugin": "^5.1.0",
+    "launch-editor": "^2.12.0",
+    "rss-parser": "^3.13.0"
+  },
+  "devDependencies": {
+    "pino-pretty": "^13.1.3",
+    "tsx": "^4.21.0"
+  }
+}

package/src/app.ts

@@ -0,0 +1,76 @@
+import Fastify, { FastifyBaseLogger } from "fastify";
+import corePlugin from "./plugins/core.plugin";
+import { errorHandlerPlugin } from "./plugins/error-handler.plugin";
+import requestIdPlugin from "./plugins/request-id.plugin";
+import routesPlugin from "./plugins/routes.plugin";
+import staticPlugin from "./plugins/static.plugin";
+import successHandlerPlugin from "./plugins/success-handle.plugin";
+import wsPlugin from "./plugins/ws/ws.plugin";
+function normalizeLogLevel(v?: string) {
+    // pino levels: fatal error warn info debug trace silent
+    const lv = (v ?? "").toLowerCase().trim();
+    if (!lv) return undefined;
+    if (["fatal", "error", "warn", "info", "debug", "trace", "silent"].includes(lv)) return lv;
+    return "info";
+}
+function createFastifyLogger(): false | FastifyBaseLogger | undefined {
+    const level = normalizeLogLevel(process.env.NGM_LOG_LEVEL);
+
+    // 1) 未指定级别 => 默认关闭（安静）
+    if (!level) return false;
+
+    // 2) dev 下可读输出（需要安装 pino-pretty）
+    const isDev = process.env.NODE_ENV !== "production";
+    if (isDev) {
+        return {
+            level,
+            transport: {
+                target: "pino-pretty",
+                options: {
+                    colorize: true,
+                    translateTime: "HH:MM:ss.l",
+                    ignore: "pid,hostname",
+                },
+            },
+        } as any;
+    }
+
+    // 3) prod 下输出 JSON（结构化）
+    return { level } as any;
+}
+export async function createServer() {
+    const fastify = Fastify({
+        logger: createFastifyLogger(),
+        genReqId: (req) => {
+            // 优先使用前端传入的 X-Request-Id
+            const hdr = req.headers["x-request-id"];
+            if (typeof hdr === "string" && hdr.trim()) return hdr.trim();
+            return crypto.randomUUID();
+        }
+    });
+
+    //  基础插件：request-id + error handler + success handler
+    await fastify.register(requestIdPlugin);
+    await fastify.register(errorHandlerPlugin);
+    await fastify.register(successHandlerPlugin);
+
+    // core
+    await fastify.register(corePlugin);
+    // 先 websocket，再 routes（尤其 ws 路由）
+    await fastify.register(wsPlugin);
+    // routes
+    await fastify.register(routesPlugin);
+
+    // www
+    await fastify.register(staticPlugin)
+
+
+    fastify.addHook('onClose', async () => {
+        // 在这里执行任何需要在服务器关闭时完成的异步操作
+        // 例如，关闭数据库连接、清理资源等
+        await fastify.core.dispose?.();
+        fastify.log.info('Server is closing, performing cleanup...');
+    });
+
+    return fastify;
+}

package/src/common/api.ts

@@ -0,0 +1,12 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+export function ok<T>(req: FastifyRequest, reply: FastifyReply, data: T, status = 200) {
+    return reply.status(status).send({
+        ok: true as const,
+        data,
+        meta: {
+            requestId: req.id,
+            ts: Date.now(),
+        },
+    });
+}

package/src/common/editor.ts

@@ -0,0 +1,49 @@
+import { AppError } from "@yinuo-ngm/core";
+import launchEditor from "launch-editor";
+import * as path from "path";
+
+export interface OpenFolderOptions {
+    editor?: "code" | "system";
+    file?: string;
+}
+
+/**
+ * 在指定文件夹打开编辑器
+ * @param folder 文件夹路径
+ * @param opts OpenFolderOptions 选项
+ */
+export async function openFolder(folder: string, opts: OpenFolderOptions = {}): Promise<void> {
+    const editor = opts.editor ?? "code";
+    const file = opts.file;
+
+    const target = file
+        ? path.resolve(folder, file)
+        : path.resolve(folder);
+
+    return new Promise<void>((resolve, reject) => {
+        let settled = false;
+
+        // 兜底：避免 callback 不触发导致请求永远挂起
+        const timer = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            resolve();
+        }, 200);
+
+        launchEditor(
+            target,
+            editor === "system" ? undefined : editor,
+            (fileName, errorMsg) => {
+                // fastify.log.info(`launchEditor callback invoked: file=${fileName}, error=${errorMsg}`);
+                if (settled) return;
+                settled = true;
+                clearTimeout(timer);
+                if (errorMsg) {
+                    reject(new AppError("EDITOR_NOT_FOUND", errorMsg, { fileName, editor, folder, file, target }));
+                    return;
+                }
+                resolve();
+            }
+        );
+    });
+}

package/src/env.ts

@@ -0,0 +1,12 @@
+import path from "path";
+import os from "os";
+
+export const env = {
+    port: Number(process.env.NGM_SERVER_PORT || 3210),
+    host: process.env.NGM_SERVER_HOST || "127.0.0.1",
+    dataDir:
+        process.env.NGM_DATA_DIR ||
+        path.join(os.homedir(), ".ng-manager"),
+    logLevel: process.env.NGM_LOG_LEVEL || "info",
+    sysLogCapacity: 3000,
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+
+import { createServer } from "./app";
+import { env } from "./env";
+
+async function start() {
+    const { port, host } = env;
+    const app = await createServer();
+    await app.listen({ port, host });
+    app.log.info(`local server listening on http://${host}:${port}`);
+    app.core.sysLog.append({
+        level: "info",
+        text: `Server started at http://${host}:${port}`,
+        source: "server",
+        scope: "system",
+    })
+}
+
+start().catch((err) => {
+    console.error("Failed to start server:", err);
+    process.exit(1);
+});

package/src/plugins/core.plugin.ts

@@ -0,0 +1,34 @@
+// src/server/plugins/core.plugin.ts
+
+import type { FastifyInstance } from "fastify";
+import fp from "fastify-plugin";
+
+import { createCoreApp, type CoreApp } from "@yinuo-ngm/core";
+import { env } from "../env";
+
+/**
+ * Fastify 装饰器类型扩展
+ */
+declare module "fastify" {
+    interface FastifyInstance {
+        core: CoreApp;
+    }
+}
+
+/**
+ * Core Plugin
+ * - 创建 CoreApp
+ * - 注入到 fastify.core
+ */
+export default fp(async function corePlugin(
+    fastify: FastifyInstance
+) {
+    const coreApp = await createCoreApp({
+        sysLogCapacity: env.sysLogCapacity,
+        dataDir: env.dataDir, // 可选: 自定义数据目录
+    });
+
+    fastify.decorate("core", coreApp);
+
+    fastify.log.info("[core] core app initialized");
+});

package/src/plugins/error-handler.plugin.ts

@@ -0,0 +1,168 @@
+import fp from "fastify-plugin";
+import type { FastifyPluginAsync } from "fastify";
+import { AppError, type ErrorCode } from "@yinuo-ngm/core";
+
+/**
+ * ErrorCode → HTTP Status 映射
+ *
+ * 约定：
+ * - 4xx：客户端/业务条件不满足
+ * - 5xx：服务端/系统错误
+ */
+export const ERROR_STATUS: Record<ErrorCode, number> = {
+    /* ---------------- Project ---------------- */
+    PROJECT_NOT_FOUND: 404,
+    PROJECT_ROOT_INVALID: 400,
+    PROJECT_ALREADY_EXISTS: 409,
+
+    /* ---------------- Project Import ---------------- */
+    PROJECT_IMPORT_NOT_EXISTS: 404, // 路径不存在
+    PROJECT_IMPORT_NOT_DIR: 400, // 不是目录
+    PROJECT_IMPORT_ALREADY_REGISTERED: 409, // 已导入
+    PROJECT_IMPORT_NOT_RECOGNIZED: 422, // 不像项目（语义错误）
+    PROJECT_IMPORT_SCAN_FAILED: 500, // 扫描失败（IO/解析）
+
+
+
+    /* ---------------- Project Creation ---------------- */
+    INVALID_NAME: 400, // 无效的项目名称
+    TARGET_EXISTS: 409, // 目标路径已存在
+    INVALID_REPO_URL: 400, // 无效的仓库地址
+    INVALID_PARENT_DIR: 400, // 无效的父目录
+    GIT_CHECKOUT_FAILED: 500, // Git 检出失败
+    BOOTSTRAP_NOT_IN_PICK_STATE: 400, // 当前不处于选择根目录状态
+    BOOTSTRAP_CTX_NOT_FOUND: 404, // 引导上下文未找到
+    BOOTSTRAP_INVALID_PICKED_ROOT: 400, // 选择的根目录无效
+    BOOTSTRAP_NOT_WAITING_PICK: 400, // 引导未处于等待选择状态
+
+    /* ---------------- Project Analysis ---------------- */
+    PROJECT_ANGULAR_JSON_INVALID: 400, // angular.json 无效
+    PROJECT_ANGULAR_JSON_NOT_FOUND: 404, // angular.json 未找到
+    PROJECT_VITE_CONFIG_INVALID: 400, // vite 配置无效
+    PROJECT_VUE_CONFIG_NOT_FOUND: 404, // vite 配置未找到
+
+    /* ---------------- Config ---------------- */
+    CONFIG_BACKUP_NOT_FOUND: 404, // 配置备份不存在
+    CONFIG_READ_FAILED: 500, // 配置读取失败
+    CONFIG_WRITE_FAILED: 500, // 配置写入失败
+    CONFIG_CONFLICT: 409, // 配置冲突
+    CONFIG_OPEN_FAILED: 500, // 配置文件打开失败
+    CONFIG_SCHEMA_NOT_FOUND: 404, // 配置 schema 未找到
+    CONFIG_DOMAIN_NOT_FOUND: 404, // 配置 domain 未找到
+    CONFIG_DOC_NOT_FOUND: 404, // 配置 doc 未找到
+
+    /* ---------------- Task / Process ---------------- */
+    TASK_NOT_FOUND: 404,
+    TASK_ALREADY_RUNNING: 409,
+    PROCESS_SPAWN_FAILED: 500,
+    TASK_SPEC_NOT_FOUND: 404,
+    TASK_NOT_RUNNABLE: 400,
+    RUN_NOT_FOUND: 404,
+    TASK_ID_REQUIRED: 400,
+    COMMAND_NOT_FOUND: 404,
+
+    // WS 
+    BAD_JSON: 400,
+    BAD_MSG: 400,
+    OP_NOT_SUPPORTED: 400,
+    HANDLER_FAILED: 500,
+    TOPIC_NOT_FOUND: 404,
+    OP_NOT_FOUND: 400,
+    /* ---------------- File System ---------------- */
+    FS_PATH_NOT_FOUND: 404,
+    FS_ALREADY_EXISTS: 409,
+    FS_PERMISSION_DENIED: 403,
+    FS_EXISTS_FAILED: 500,
+    FS_INVALID_NAME: 400,
+    FS_MKDIR_FAILED: 500,
+
+    /* ---------------- Editor ---------------- */
+    EDITOR_NOT_FOUND: 404,
+    EDITOR_LAUNCH_FAILED: 500,
+
+    /* ---------------- Infra / Auth ---------------- */
+    STORAGE_IO_ERROR: 500,
+    UNAUTHORIZED: 401,
+    INVALID_TIMESTAMP: 400, // 时间戳无效
+
+
+    /* ---------------- Deps ---------------- */
+    DEP_INSTALL_FAILED: 500,
+    DEP_UNINSTALL_FAILED: 500,
+    DEP_NOT_FOUND: 404,
+
+    /* ---------------- Dashboard ---------------- */
+    DASHBOARD_CONFLICT: 409,
+    WIDGET_NOT_FOUND: 404,
+    WIDGET_LOCKED: 423,
+
+    /* ---------------- Dashboard RSS ---------------- */
+    RSS_FETCH_FAILED: 500,
+    INVALID_RSS_URL: 400,
+
+    /* ---------------- Fallback ---------------- */
+    UNKNOWN_ERROR: 500,
+
+    /* ---------------- Generic ---------------- */
+    BAD_REQUEST: 400,
+    NOT_IMPLEMENTED: 501,
+};
+
+export function mapStatus(code: ErrorCode): number {
+    return ERROR_STATUS[code] ?? 400;
+}
+
+/**
+ * 构建错误响应体
+ */
+function buildErrorBody(reqId: string | undefined, code: string, message: string, details?: any) {
+    return {
+        ok: false as const,
+        error: {
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        },
+        meta: {
+            requestId: reqId,
+            ts: Date.now(),
+        },
+    };
+}
+
+/**
+ * 全局错误处理插件： 将错误转换为标准响应体
+ * - 业务错误（AppError）按其 code 映射状态码
+ * - schema 校验错误返回 400
+ * - 其他未知错误返回 500，并记录日志
+ */
+export const errorHandlerPlugin: FastifyPluginAsync = fp(async (app) => {
+    app.setErrorHandler((err, req, reply) => {
+        const requestId = req.id;
+        // 1) core 业务错误
+        if (err instanceof AppError || isCoreAppError(err)) {
+            const status = mapStatus(err.code as ErrorCode);
+            return reply.status(status).send(buildErrorBody(requestId, err.code, err.message, err.meta));
+        }
+
+        // 2) Fastify schema 校验错误
+        // @ts-expect-error fastify error typing
+        if (err?.validation) {
+            return reply
+                .status(400)
+                // @ts-expect-error
+                .send(buildErrorBody(requestId, "VALIDATION_ERROR", "参数不合法", err.validation));
+        }
+
+        // 3) 未知错误：只记录日志
+        req.log.error({ err, requestId }, "Unhandled error");
+        return reply.status(500).send(buildErrorBody(requestId, "INTERNAL_ERROR", "服务异常，请稍后重试"));
+    });
+});
+
+
+function isCoreAppError(err: any): err is { code: string; message: string; meta?: any } {
+    return err && typeof err === "object" && typeof err.code === "string" && typeof err.message === "string";
+}
+
+export default errorHandlerPlugin;

package/src/plugins/request-id.plugin.ts

@@ -0,0 +1,14 @@
+import fp from "fastify-plugin";
+import type { FastifyPluginAsync } from "fastify";
+
+export const requestIdPlugin: FastifyPluginAsync = fp(async (app) => {
+    // 让 req.id 优先使用前端传入的 X-Request-Id
+    // 注意：Fastify 的 genReqId 只能在 Fastify() 初始化时配置
+    // 只负责“回传 header”
+    app.addHook("onSend", async (req, reply, payload) => {
+        reply.header("X-Request-Id", req.id);
+        return payload;
+    });
+});
+
+export default requestIdPlugin;

package/src/plugins/routes.plugin.ts

@@ -0,0 +1,24 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+import { configRoutes, dashboardRoutes, depsRoutes, fsRoutes, projectRoutes, rssRoutes, systemRoutes, taskRoutes } from "../routes";
+
+export default fp(async function routesPlugin(fastify: FastifyInstance) {
+    // system
+    await fastify.register(systemRoutes);
+    // routes
+    await fastify.register(taskRoutes, { prefix: '/api/tasks' });
+    //projects 
+    await fastify.register(projectRoutes, { prefix: '/api/projects' });
+    // deps 
+    await fastify.register(depsRoutes, { prefix: '/api/deps' });
+    // fs
+    await fastify.register(fsRoutes, { prefix: '/api/fs' });
+    // config
+    await fastify.register(configRoutes, { prefix: '/api/config' });
+
+    // dashboard
+    await fastify.register(dashboardRoutes, { prefix: '/api/dashboard' });
+
+    // rss
+    await fastify.register(rssRoutes, { prefix: '/api/rss' });
+});

package/src/plugins/static.plugin.ts

@@ -0,0 +1,30 @@
+import fp from "fastify-plugin";
+import path from "path";
+import fastifyStatic from "@fastify/static";
+
+export default fp(async function staticPlugin(fastify) {
+    /**
+     * __dirname === packages/server/lib/plugins
+     * 回到 monorepo 根，再进 www/browser
+     */
+    const webRoot = path.resolve(__dirname, "../../www/browser");
+
+    fastify.log.info(`[static] serving webapp from ${webRoot}`);
+
+    await fastify.register(fastifyStatic, {
+        root: webRoot,
+        index: "index.html",
+    });
+
+    // SPA fallback（非 API 请求 → index.html）
+    fastify.setNotFoundHandler((req, reply) => {
+        if (
+            req.method === "GET" &&
+            !req.url.startsWith("/api") &&
+            !req.url.startsWith("/ws")
+        ) {
+            return reply.sendFile("index.html");
+        }
+        reply.code(404).send({ ok: false, message: "Not Found" });
+    });
+});

package/src/plugins/success-handle.plugin.ts

@@ -0,0 +1,33 @@
+import fp from "fastify-plugin";
+import type { FastifyPluginAsync } from "fastify";
+
+export const successHandlerPlugin: FastifyPluginAsync = fp(async (app) => {
+    app.addHook("preSerialization", async (req, reply, payload) => {
+        //  非 2xx：不处理（错误已由 errorHandler 接管）
+        if (reply.statusCode < 200 || reply.statusCode >= 300) {
+            return payload;
+        }
+
+        //  没有 payload（204 等）
+        if (payload === undefined || payload === null) {
+            return payload;
+        }
+
+        //  非 JSON（stream / buffer / string）
+        const type = reply.getHeader("content-type");
+        if (typeof type === "string" && !type.includes("application/json")) {
+            return payload;
+        }
+        // 统一包装成功返回
+        return {
+            ok: true,
+            data: payload,
+            meta: {
+                requestId: req.id,
+                ts: Date.now(),
+            },
+        };
+    });
+});
+
+export default successHandlerPlugin;

package/src/plugins/ws/topics/index.ts

@@ -0,0 +1 @@
+export * from "./task.ws";

package/src/plugins/ws/topics/syslog.ws.ts

@@ -0,0 +1,36 @@
+import type { WsClientMsg, WsServerMsg, LogLine } from "@yinuo-ngm/core";
+import { WsContext } from "../ws.context";
+import type { TopicHandler } from "../ws.router";
+const KEY_ALL = "syslog:all";
+export type SyslogWsDeps = {
+    getSyslogTail: (tail: number) => LogLine[];
+};
+
+export function createSyslogTopicHandler(
+    deps: SyslogWsDeps,
+    getAllClients: () => Iterable<WsContext>
+): TopicHandler & { push(entry: LogLine): void } {
+    return {
+        topic: "syslog",
+        async sub(ctx, msg: Extract<WsClientMsg, { op: "sub"; topic: "syslog" }>) {
+            const tail = Math.max(0, Number(msg?.tail ?? 0));
+            ctx.addSub("syslog", KEY_ALL);
+
+            if (tail > 0) {
+                const entries = await deps.getSyslogTail(tail);
+                // 用一个 batch，前端更好处理
+                const m: WsServerMsg = { op: "syslog.tail", entries: entries ?? [] };
+                ctx.send(m);
+            }
+        },
+        unsub(ctx) {
+            ctx.delSub("syslog", KEY_ALL);
+        },
+        push(entry: LogLine) {
+            const m: WsServerMsg = { op: "syslog.append", entry };
+            for (const c of getAllClients()) {
+                if (c.hasSub("syslog", KEY_ALL)) c.send(m);
+            }
+        },
+    };
+}