mn-ws 0.0.0-stage → 0.2.0

package/dist/modules/bridge/index.js

@@ -0,0 +1,89 @@
+// bridge 模块：**client 半的管理面**。
+//
+// 这一域回答的是「这台桥现在什么状态、能桥什么、桥给谁了」：
+//   - status    连没连、注册了哪些 app、重连到第几次
+//   - apps      本机有哪些 nx 服务在跑（探测端口存活）+ 白名单是哪些
+//   - whitelist 改白名单（**白名单说了算**：探测到端口在监听 ≠ 可以桥）
+//   - catalog   拉远端 server 半的元信息目录（哪些能路由）
+//   - start/stop 启停桥
+//
+// 每一项都同时暴露为 CLI 与 HTTP —— 面板上的按钮与命令行是同一份声明。
+import { scanApps, KNOWN_APPS } from 'mn-ws-server/apps';
+import { defineAction } from '../../runtime/types/action.js';
+import { defineModule } from '../../runtime/types/module.js';
+import { getController } from '../../core/controller.js';
+import { parseApps } from '../../core/config.js';
+import { bridgeStatus, bridgeApps, setWhitelist, remoteCatalog, renderStatus, renderApps, renderWhitelist, } from './service.js';
+export default defineModule({
+    id: 'bridge',
+    title: '桥接',
+    order: 2,
+    actions: [
+        defineAction({
+            id: 'bridge.status',
+            cli: ['status'],
+            http: ['GET', '/api/bridge/status'],
+            summary: '桥接状态：连没连、注册了哪些 app、当前凭据是谁',
+        })(() => bridgeStatus(getController()), (r) => renderStatus(r)),
+        defineAction({
+            id: 'bridge.apps',
+            cli: ['apps'],
+            http: ['GET', '/api/bridge/apps'],
+            summary: '列出可桥接的应用：白名单 + 本地端口存活探测',
+        })(() => bridgeApps(getController()), (r) => renderApps(r)),
+        defineAction({
+            id: 'bridge.whitelist.set',
+            cli: ['apps', 'set'],
+            http: ['POST', '/api/bridge/whitelist'],
+            summary: '设置白名单（只有列出的应用会被桥；不给就一个都不桥）',
+            flags: {
+                apps: { type: 'string', hint: '逗号分隔的应用名，如 nx-kv,nx-rh' },
+                ports: { type: 'string', hint: '逗号分隔的本地端口（从已知表反查应用名）' },
+                'app-map': { type: 'string', hint: '显式基址，如 nx-kv=http://127.0.0.1:7999' },
+            },
+        })(async (ctx) => {
+            const apps = parseApps(ctx.apps);
+            const ports = String(ctx.ports || '')
+                .split(',').map((x) => Number(x.trim())).filter((n) => Number.isFinite(n) && n > 0);
+            const appMap = String(ctx['app-map'] || '')
+                .split(',').map((x) => x.trim()).filter(Boolean)
+                .map((pair) => {
+                const eq = pair.indexOf('=');
+                return eq <= 0 ? null : [pair.slice(0, eq).trim(), { base: pair.slice(eq + 1).trim() }];
+            }).filter((x) => x !== null);
+            return setWhitelist(getController(), { apps, ports, appMap: Object.fromEntries(appMap) });
+        }, (r) => renderWhitelist(r)),
+        defineAction({
+            id: 'bridge.catalog',
+            cli: ['catalog'],
+            http: ['GET', '/api/bridge/catalog'],
+            summary: '拉远端 server 半的元信息目录（哪些能路由）',
+        })(async () => remoteCatalog(getController()), (r) => {
+            if (!r.ok)
+                return `拉目录失败：${r.error}`;
+            const lines = [`元信息目录（${r.apps.length} 个可路由）`];
+            for (const a of r.apps)
+                lines.push(`  ${a.app.padEnd(10)} ${String(a.port ?? '—').padEnd(7)} ${a.title}`);
+            return lines.join('\n');
+        }),
+        defineAction({
+            id: 'bridge.start',
+            cli: ['bridge', 'start'],
+            http: ['POST', '/api/bridge/start'],
+            summary: '起桥（连 server 半并注册白名单里的应用）',
+        })(() => getController().start(), (r) => (r.started ? `已起桥：${r.apps.join(', ')}` : `未起桥：${r.reason || ''}`)),
+        defineAction({
+            id: 'bridge.stop',
+            cli: ['bridge', 'stop'],
+            http: ['POST', '/api/bridge/stop'],
+            summary: '停桥（断开 server 半，本机 nx 服务不受影响）',
+        })(() => getController().stop(), (r) => (r.stopped ? '已停桥' : `未停：${r.reason || ''}`)),
+        defineAction({
+            id: 'bridge.known',
+            cli: ['apps', 'known'],
+            http: ['GET', '/api/bridge/known'],
+            summary: '列出已知的 nx 服务与它们的默认端口',
+        })(() => Object.entries(KNOWN_APPS).map(([app, info]) => ({ app, port: info.port, title: info.title })), (rows) => rows.map((r) => `  ${r.app.padEnd(10)} ${String(r.port).padEnd(7)} ${r.title}`).join('\n')),
+    ],
+});
+//# sourceMappingURL=index.js.map

package/dist/modules/bridge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/bridge/index.ts"],"names":[],"mappings":"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"}

package/dist/modules/bridge/service.d.ts

@@ -0,0 +1,75 @@
+import type { MnWsController } from '../../core/controller.js';
+/** 桥接状态视图。 */
+export interface BridgeStatusView {
+    state: string;
+    url: string;
+    clientId: string;
+    /** 白名单里的应用 */
+    apps: string[];
+    /** server 半已确认注册的���用（注册成功才有） */
+    registered: string[];
+    /** 当前凭据的归属（登录了就是用户名，没登录就是「静态门禁」） */
+    identity: string;
+    loggedIn: boolean;
+    via: string;
+    reason?: string;
+    retryInMs?: number;
+}
+/** 可桥接应用清单。 */
+export interface BridgeAppsView {
+    /** 白名单里的应用 + 端口存活 */
+    configured: {
+        app: string;
+        title: string;
+        port: number | null;
+        base: string | null;
+        alive: boolean;
+    }[];
+    /** 本机已知但不在白名单里的（供面板勾选） */
+    candidates: {
+        app: string;
+        title: string;
+        port: number;
+        alive: boolean;
+    }[];
+}
+/** 远端目录视图。 */
+export interface CatalogView {
+    ok: boolean;
+    error?: string;
+    count?: number;
+    apps: {
+        app: string;
+        title: string;
+        port: number | null;
+        base: string | null;
+        bridgeId: string;
+        connectedAt: string;
+    }[];
+}
+/** 桥接状态。 */
+export declare function bridgeStatus(c: MnWsController): BridgeStatusView;
+/** 可桥接应用清单：白名单 + 端口存活探测 + 候选项。 */
+export declare function bridgeApps(c: MnWsController): Promise<BridgeAppsView>;
+/** 设置白名单。落盘并让运行中的桥按新白名单重注册。 */
+export declare function setWhitelist(c: MnWsController, input: {
+    apps: string[];
+    ports: number[];
+    appMap: Record<string, {
+        base: string;
+    }>;
+}): Promise<{
+    ok: boolean;
+    apps: string[];
+    applied: boolean;
+}>;
+/** 拉远端 server 半的元信息目录。 */
+export declare function remoteCatalog(c: MnWsController): Promise<CatalogView>;
+export declare function renderStatus(r: BridgeStatusView): string;
+export declare function renderApps(r: BridgeAppsView): string;
+export declare function renderWhitelist(r: {
+    ok: boolean;
+    apps: string[];
+    applied: boolean;
+}): string;
+//# sourceMappingURL=service.d.ts.map

package/dist/modules/bridge/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/bridge/service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,cAAc;AACd,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iCAAiC;IACjC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAe;AACf,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IACvG,0BAA0B;IAC1B,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAC5E;AAED,cAAc;AACd,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzH;AAED,YAAY;AACZ,wBAAgB,YAAY,CAAC,CAAC,EAAE,cAAc,GAAG,gBAAgB,CAehE;AAED,kCAAkC;AAClC,wBAAsB,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAe3E;AAED,+BAA+B;AAC/B,wBAAsB,YAAY,CAChC,CAAC,EAAE,cAAc,EACjB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GACnF,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAiC5D;AAED,0BAA0B;AAC1B,wBAAsB,aAAa,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB3E;AAID,wBAAgB,YAAY,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAWxD;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,CAepD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAG5F"}

package/dist/modules/bridge/service.js

@@ -0,0 +1,134 @@
+import { scanApps, KNOWN_APPS } from 'mn-ws-server/apps';
+import { readConfigFile, writeConfigFile } from '../../core/config.js';
+import { badInput } from '../../core/errors/index.js';
+/** 桥接状态。 */
+export function bridgeStatus(c) {
+    const st = c.status();
+    const sess = c.session.snapshot();
+    return {
+        state: st.state,
+        url: st.url,
+        clientId: st.clientId,
+        apps: st.apps,
+        registered: st.apps || [],
+        identity: sess.loggedIn ? (sess.nickname || sess.email || sess.userId || '已登录') : '静态门禁',
+        loggedIn: sess.loggedIn,
+        via: sess.via,
+        reason: st.reason,
+        retryInMs: st.retryInMs,
+    };
+}
+/** 可桥接应用清单：白名单 + 端口存活探测 + 候选项。 */
+export async function bridgeApps(c) {
+    const { apps: whitelist } = c.resolveApps();
+    const names = Object.keys(whitelist);
+    const overrides = c.cfg.appOverrides;
+    const configured = await scanApps({ host: '127.0.0.1', apps: names, overrides });
+    // 候选项：已知表里没进白名单的（面板据此勾选）
+    const rest = Object.keys(KNOWN_APPS).filter((a) => !names.includes(a));
+    const scanned = await scanApps({ host: '127.0.0.1', apps: rest, overrides });
+    const candidates = scanned
+        .filter((x) => x.port !== null)
+        .map((x) => ({ app: x.app, title: x.title, port: x.port, alive: x.alive }));
+    return { configured, candidates };
+}
+/** 设置白名单。落盘并让运行中的桥按新白名单重注册。 */
+export async function setWhitelist(c, input) {
+    if (!input.apps.length && !input.ports.length && !Object.keys(input.appMap).length) {
+        // 不给任何东西 = 清空白名单（= 一个都不桥）。这是有意的：
+        // 「清空白名单」必须是一个能表达的动作，不能靠「什么都不传」来暗示。
+        const raw = readConfigFile();
+        delete raw.apps;
+        delete raw.ports;
+        delete raw.appMap;
+        writeConfigFile(raw);
+        c.cfg.apps = [];
+        c.cfg.ports = [];
+        c.cfg.appOverrides = {};
+        return { ok: true, apps: [], applied: true };
+    }
+    const raw = readConfigFile();
+    raw.apps = input.apps;
+    raw.ports = input.ports;
+    raw.appMap = input.appMap;
+    writeConfigFile(raw);
+    c.cfg.apps = input.apps;
+    c.cfg.ports = input.ports;
+    c.cfg.appOverrides = input.appMap;
+    // 运行中的桥要按新白名单重注册：停掉再起，让 server 半收到新的 app 表
+    const wasRunning = !!c.client;
+    if (wasRunning) {
+        c.stop();
+        c.start();
+    }
+    return { ok: true, apps: Object.keys(c.resolveApps().apps), applied: wasRunning };
+}
+/** 拉远端 server 半的元信息目录。 */
+export async function remoteCatalog(c) {
+    const base = (c.cfg.serverHttp || '').replace(/\/+$/, '');
+    if (!base)
+        throw badInput('缺少服务端地址（--url 或配置文件）');
+    const token = c.session.credential() || c.cfg.token;
+    if (!token)
+        throw badInput('缺少凭据：mn-ws auth login，或用 --token 传门禁');
+    let res;
+    try {
+        res = await fetch(`${base}/api/catalog`, { headers: { 'X-Mn-Ws-Token': token } });
+    }
+    catch (e) {
+        return { ok: false, error: `连不上 ${base}：${e.message}`, apps: [] };
+    }
+    const raw = await res.text();
+    // 用 IIFE 解析：let + try/catch 的写法会被 TS 的控制流分析
+    // 误判成「json 仍是初始的 null」，后面 json.ok 就成了 never。
+    const json = (() => {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (!res.ok || !json || json.ok !== true) {
+        return { ok: false, error: (json && json.error) || `HTTP ${res.status}`, apps: [] };
+    }
+    return { ok: true, count: (json.apps || []).length, apps: json.apps || [] };
+}
+// ---- 渲染 ----
+export function renderStatus(r) {
+    const lines = [
+        `桥接状态：${r.state}`,
+        `  server    ${r.url}`,
+        `  本机标识  ${r.clientId}`,
+        `  白名单    ${r.apps.join(', ') || '（空 —— 一个都不桥）'}`,
+        `  身份      ${r.identity}${r.loggedIn ? `（${r.via === 'cli' ? '复用 CLI 登录态' : '面板登录'}）` : ''}`,
+    ];
+    if (r.reason)
+        lines.push(`  说明      ${r.reason}`);
+    if (r.retryInMs)
+        lines.push(`  重连      ${Math.round(r.retryInMs / 1000)}s 后重试`);
+    return lines.join('\n');
+}
+export function renderApps(r) {
+    const lines = ['可桥接的应用（白名单）'];
+    if (!r.configured.length) {
+        lines.push('  （白名单为空 —— 一个都不桥。用 mn-ws apps set --apps nx-kv,nx-rh 设置）');
+    }
+    else {
+        for (const a of r.configured) {
+            lines.push(`  ${a.app.padEnd(10)} ${String(a.port ?? '—').padEnd(7)} ${a.alive ? '✓ 在监听' : '✗ 未运行'}  ${a.base || ''}`);
+        }
+    }
+    const alive = r.candidates.filter((c) => c.alive);
+    if (alive.length) {
+        lines.push('', '本机在跑但不在白名单里（勾上才会被桥）：');
+        for (const c of alive)
+            lines.push(`  ${c.app.padEnd(10)} ${String(c.port).padEnd(7)} ${c.title}`);
+    }
+    return lines.join('\n');
+}
+export function renderWhitelist(r) {
+    return `白名单已更新：${r.apps.join(', ') || '（空）'}`
+        + (r.applied ? '\n运行中的桥已按新白名单重注册' : '');
+}
+//# sourceMappingURL=service.js.map

package/dist/modules/bridge/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/modules/bridge/service.ts"],"names":[],"mappings":"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"}

package/dist/modules/home/index.d.ts

@@ -0,0 +1,95 @@
+declare const _default: {
+    readonly id: "home";
+    readonly title: "首页";
+    readonly order: 1;
+    readonly actions: readonly [import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "home.bootstrap";
+        readonly cli: readonly ["bootstrap", "show"];
+        readonly http: readonly ["GET", "/api/bootstrap"];
+        readonly summary: "一次取齐面板启动所需的全部上下文";
+    }, {
+        app: {
+            name: string;
+            title: string;
+            description: string;
+            version: string;
+        };
+        storePath: string;
+        storeEnv: string;
+        commands: import("../../runtime/help.js").CommandEntry[];
+    }>, import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "home.routes";
+        readonly cli: readonly ["routes"];
+        readonly http: readonly ["GET", "/api/routes"];
+        readonly summary: "列出 CLI 命令与 HTTP 路由的对照表";
+    }, {
+        status: "ok";
+        count: number;
+        routes: {
+            id: string;
+            module: string;
+            cli: string;
+            http: string | null;
+            summary: string | undefined;
+        }[];
+    }>, import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "home.health";
+        readonly cli: readonly ["health"];
+        readonly http: readonly ["GET", "/api/health"];
+        readonly summary: "自检：存储目录是否可写";
+    }, {
+        status: "ok" | "blocked";
+        storePath: string;
+        reason: string;
+    }>, import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "home.greet";
+        readonly cli: readonly ["greet"];
+        readonly http: readonly ["POST", "/api/greet"];
+        readonly summary: "打个招呼（演示动作：问候次数累计进本机存储）";
+        readonly args: readonly [{
+            readonly name: "name";
+            readonly required: true;
+        }];
+        readonly flags: {
+            readonly loud: {
+                readonly type: "boolean";
+            };
+        };
+    }, import("./service.js").GreetingResult>, import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "setting.get";
+        readonly cli: readonly ["setting", "get"];
+        readonly http: readonly ["GET", "/api/settings"];
+        readonly summary: "读取全部设置（含头部导航分组 / 隐藏 / 平铺顺序）";
+    }, import("./service.js").SettingsView>, import("../../runtime/types/action.js").TypedAction<{
+        readonly id: "setting.set";
+        readonly cli: readonly ["setting", "set"];
+        readonly http: readonly ["PATCH", "/api/settings"];
+        readonly summary: "修改设置（PATCH 语义：只改传入的项）";
+        readonly flags: {
+            readonly key: {
+                readonly type: "string";
+                readonly hint: "设置项名";
+            };
+            readonly value: {
+                readonly type: "string";
+                readonly hint: "取值";
+            };
+            readonly set: {
+                readonly type: "kv";
+                readonly hint: "k=v，可重复（值可以是 JSON 数组，如 navGroups=[{...}]）";
+            };
+            readonly 'dry-run': {
+                readonly type: "boolean";
+            };
+        };
+    }, {
+        status: "skipped";
+        dryRun: true;
+        wouldSet: Record<string, unknown>;
+    } | {
+        status: "ok";
+        settings: import("../../core/store.js").Settings;
+    }>];
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/modules/home/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/home/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,wBAoGG"}

package/dist/modules/home/index.js

@@ -0,0 +1,123 @@
+// home 模块：面板落地页，承担「启动聚合 + 演示业务 + 本机设置」三类职责。
+//
+// 这是新骨架自带的示例功能域，演示一条 action 如何同时暴露为 CLI 与 HTTP：
+//   - 面板上的问候按钮 ↔ `mn-ws greet <名字>` 是同一份声明
+//   - 设置（主题 / 头部导航）↔ `mn-ws setting get|set` 是同一份声明
+//   - 参数名、flag 类型、返回数据全部由类型系统在编译期检查
+//
+// 为什么首页和设置合成一个模块：两者都是「关于这个应用本身」的内容——
+// 启动上下文（bootstrap / 命令表 / 健康）、演示动作（greet）与本机设置（主题 / 头部导航）。
+// 拆成两个模块，初始就凭空多出一个只有 meta 信息的空壳页；合成一个，出厂模块都有真实内容。
+import { readFileSync } from 'node:fs';
+import { APP_NAME, APP_DESC, APP_TITLE, STORE_ENV, storePathFromEnv } from '../../core/paths.js';
+import { defineAction } from '../../runtime/types/action.js';
+import { defineModule } from '../../runtime/types/module.js';
+import { commandEntry } from '../../runtime/help.js';
+import { greet, getSettings, setSettings, renderSettings, renderSettingSet, } from './service.js';
+const VERSION = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version;
+// 命令表：CLI 命令 ↔ HTTP 路由的对照，bootstrap 与面板的「CLI 等价」提示共用。
+//
+// 动态 import cli：runtime/registry 静态依赖本模块，静态引入 ALL_COMMANDS 会形成循环。
+// commandEntry 无循环依赖，直接静态引入（见顶部 import）。
+// 该函数只在启动完成后被调用，届时 cli.js 早已求值完毕。
+async function commandTable() {
+    const { ALL_COMMANDS } = await import('../../runtime/cli.js');
+    return ALL_COMMANDS.map(commandEntry);
+}
+// 一次拿齐面板启动所需的全部上下文。
+// 面板用 commands 渲染「每个按钮对应的 CLI 命令」，而不是视图手写字符串——
+// 手写的迟早与实际命令脱节。
+async function bootstrap() {
+    return {
+        app: { name: APP_NAME, title: APP_TITLE, description: APP_DESC, version: VERSION },
+        storePath: storePathFromEnv(),
+        storeEnv: STORE_ENV,
+        commands: await commandTable(),
+    };
+}
+export default defineModule({
+    id: 'home',
+    title: '首页',
+    order: 1,
+    actions: [
+        defineAction({
+            id: 'home.bootstrap',
+            cli: ['bootstrap', 'show'],
+            http: ['GET', '/api/bootstrap'],
+            summary: '一次取齐面板启动所需的全部上下文',
+        })(() => bootstrap()),
+        defineAction({
+            id: 'home.routes',
+            cli: ['routes'],
+            http: ['GET', '/api/routes'],
+            summary: '列出 CLI 命令与 HTTP 路由的对照表',
+        })(async () => {
+            const table = await commandTable();
+            return {
+                status: 'ok',
+                count: table.length,
+                routes: table.map((c) => ({
+                    id: c.id,
+                    module: c.module,
+                    cli: c.command,
+                    http: c.http ? `${c.http.method} ${c.http.path}` : null,
+                    summary: c.summary,
+                })),
+            };
+        }, (r) => {
+            const lines = [`共 ${r.count} 条命令（CLI ↔ HTTP 对照）`, ''];
+            const width = Math.max(...r.routes.map((x) => x.cli.length));
+            for (const x of r.routes) {
+                lines.push('  ' + x.cli.padEnd(width + 2) + (x.http || '(仅 CLI)') + '   ' + (x.summary || ''));
+            }
+            return lines.join('\n');
+        }),
+        defineAction({
+            id: 'home.health',
+            cli: ['health'],
+            http: ['GET', '/api/health'],
+            summary: '自检：存储目录是否可写',
+        })(async () => {
+            const { loadStore, saveStore } = await import('../../core/store.js');
+            let ok = true;
+            let reason = '';
+            try {
+                // 触碰一次存储：读出来原样写回，验证整条读写链路
+                const s = await loadStore();
+                await saveStore(s);
+            }
+            catch (err) {
+                ok = false;
+                reason = String(err?.message || err);
+            }
+            return { status: ok ? 'ok' : 'blocked', storePath: storePathFromEnv(), reason };
+        }, (r) => (r.status === 'ok' ? `正常 · 存储 ${r.storePath}` : `异常 · ${r.reason}`)),
+        defineAction({
+            id: 'home.greet',
+            cli: ['greet'],
+            http: ['POST', '/api/greet'],
+            summary: '打个招呼（演示动作：问候次数累计进本机存储）',
+            args: [{ name: 'name', required: true }],
+            flags: { loud: { type: 'boolean' } },
+        })((ctx) => greet(ctx.name, !!ctx.loud), (r) => r.greeting),
+        defineAction({
+            id: 'setting.get',
+            cli: ['setting', 'get'],
+            http: ['GET', '/api/settings'],
+            summary: '读取全部设置（含头部导航分组 / 隐藏 / 平铺顺序）',
+        })(() => getSettings(), (d) => renderSettings(d)),
+        defineAction({
+            id: 'setting.set',
+            cli: ['setting', 'set'],
+            http: ['PATCH', '/api/settings'],
+            summary: '修改设置（PATCH 语义：只改传入的项）',
+            flags: {
+                key: { type: 'string', hint: '设置项名' },
+                value: { type: 'string', hint: '取值' },
+                set: { type: 'kv', hint: 'k=v，可重复（值可以是 JSON 数组，如 navGroups=[{...}]）' },
+                'dry-run': { type: 'boolean' },
+            },
+        })((ctx) => setSettings(ctx), (d) => renderSettingSet(d)),
+    ],
+});
+//# sourceMappingURL=index.js.map

package/dist/modules/home/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/home/index.ts"],"names":[],"mappings":"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"}

package/dist/modules/home/service.d.ts

@@ -0,0 +1,48 @@
+import type { Settings } from '../../core/store.js';
+export interface GreetingResult {
+    greeting: string;
+    name: string;
+    count: number;
+    at: string;
+}
+export declare function greet(name: string, loud?: boolean): Promise<GreetingResult>;
+export interface SettingsView {
+    settings: Settings;
+    /** 全部页面（含 order 与出厂默认 hidden）——面板的头部导航与本页都用它 */
+    views: {
+        id: string;
+        title: string;
+        order: number;
+        hidden?: boolean;
+    }[];
+    schema: {
+        key: string;
+        hint: string;
+    }[];
+}
+export declare function getSettings(): Promise<SettingsView>;
+/**
+ * PATCH 语义：只改传入的项。
+ * 返回 `{ settings }` 的**最新全量**（面板保存后直接拿来刷新头部）。
+ */
+export declare function setSettings(input: {
+    key?: string;
+    value?: unknown;
+    set?: Record<string, unknown>;
+    'dry-run'?: boolean;
+}): Promise<{
+    status: 'skipped';
+    dryRun: true;
+    wouldSet: Record<string, unknown>;
+} | {
+    status: 'ok';
+    settings: Settings;
+}>;
+export declare function renderSettings(d: SettingsView): string;
+export declare function renderSettingSet(d: {
+    status: string;
+    dryRun?: boolean;
+    wouldSet?: unknown;
+    settings?: Settings;
+}): string;
+//# sourceMappingURL=service.d.ts.map

package/dist/modules/home/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/modules/home/service.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAY,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAM9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAMD,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,UAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAW/E;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,gDAAgD;IAChD,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IACxE,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACzC;AA0FD,wBAAsB,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC,CAOzD;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,OAAO,CACP;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CACvC,CAuBA;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAuBtD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,GAAG,MAAM,CAQT"}