@tomflow/proflow-platform-cli 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @tomflow/proflow-platform-cli
+
+## 0.1.29
+
+### Patch Changes
+
+- Improve terminal progress and localized status output, publish readable Chinese module docs, and add guided setup assistants for external resources.

package/DOCS.md

@@ -1,27 +1,11 @@
-# @tomflow/proflow-platform-cli — Module Docs
+# platform-cli
 
-Module ref: `platform-cli`  
-Domain: `deployment-governance`  
-Kind: `cli`
+Platform CLI（平台命令行）是 ProFlow 的统一管理入口，负责发现模块、安装依赖、汇总状态和按依赖顺序启动或停止模块。
 
-Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.
+## 推荐流程
 
-## Standard management surface
+`platform install` → `platform status` → `platform docs` → `platform setup` → `platform start`
 
-`install / uninstall / status / setup / docs / start / stop`
+## 边界
 
-## Provides
-
-- None.
-
-## Requires
-
-- None.
-
-## Public setup inputs
-
-- None. Deterministic/private values and cross-Module shared facts are not public configuration.
-
-## Ownership boundary
-
-Module business APIs and any module-specific extra commands remain package-owned. Platform does not proxy or interpret them. Current human/external preparation is documented in `SETUP.md`.
+Platform CLI 只负责调用和汇总，不读取模块私有配置，也不替模块解释外部服务。具体配置由对应模块的 Setup（配置向导）完成。

package/dist/deployment/adapter.d.ts

@@ -6,7 +6,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.28";
+            readonly moduleVersion: "0.1.29";
         };
         observedEffects: never[];
     }>;
@@ -16,7 +16,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.28";
+            readonly moduleVersion: "0.1.29";
         };
         observedEffects: never[];
     }>;
@@ -26,7 +26,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.28";
+            moduleVersion: "0.1.29";
             data: {
                 readonly setupStatus: "READY";
                 readonly runtimeStatus: "NOT_APPLICABLE";
@@ -40,7 +40,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.28";
+            readonly moduleVersion: "0.1.29";
         };
         observedEffects: never[];
     }>;
@@ -50,7 +50,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "platform-cli";
-            moduleVersion: "0.1.28";
+            moduleVersion: "0.1.29";
             data: {
                 docs: string;
             };
@@ -63,7 +63,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.28";
+            readonly moduleVersion: "0.1.29";
         };
         observedEffects: never[];
     }>;
@@ -73,7 +73,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "platform-cli";
-            readonly moduleVersion: "0.1.28";
+            readonly moduleVersion: "0.1.29";
         };
         observedEffects: never[];
     }>;

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "platform-cli";
     readonly packageName: "@tomflow/proflow-platform-cli";
-    readonly moduleVersion: "0.1.28";
+    readonly moduleVersion: "0.1.29";
     readonly kind: "cli";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "platform-cli",
     packageName: "@tomflow/proflow-platform-cli",
-    moduleVersion: "0.1.28",
+    moduleVersion: "0.1.29",
     kind: "cli",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.js

@@ -130,8 +130,14 @@ function batchStatus(result) {
     return "FAILED";
 }
 async function handleStatus(root, runtime) {
+    reportProgress(runtime.onProgress, {
+        command: "status",
+        phase: "status",
+        status: "STARTED",
+        message: "正在读取模块状态",
+    });
     const { catalog, modules } = await buildContext(root);
-    const observed = await observeStatuses(catalog, modules, root, runtime.onProgress);
+    const observed = await observeStatuses(catalog, modules, root);
     const byRef = new Map(modules.map((module) => [module.moduleRef, module]));
     const output = observed.map((item) => {
         if (item.result.status !== "SUCCEEDED")
@@ -149,11 +155,23 @@ async function handleStatus(root, runtime) {
             runtimeStatus: parsed.data.runtimeStatus,
         };
     });
+    reportProgress(runtime.onProgress, {
+        command: "status",
+        phase: "status",
+        status: "SUCCEEDED",
+        message: `已读取 ${output.length} 个模块状态`,
+    });
     return outcome("status", "SUCCEEDED", root, { modules: output });
 }
 async function handleDocs(root, runtime) {
+    reportProgress(runtime.onProgress, {
+        command: "docs",
+        phase: "docs",
+        status: "STARTED",
+        message: "正在整理模块文档",
+    });
     const { catalog, modules: resolvedModules } = await buildContext(root);
-    const docs = await observeDocs(catalog, resolvedModules, root, runtime.onProgress);
+    const docs = await observeDocs(catalog, resolvedModules, root);
     const byRef = new Map(resolvedModules.map((module) => [module.moduleRef, module]));
     const modules = [];
     const errors = [];
@@ -174,6 +192,14 @@ async function handleDocs(root, runtime) {
             docs: parsed.data.docs,
         });
     }
+    reportProgress(runtime.onProgress, {
+        command: "docs",
+        phase: "docs",
+        status: errors.length === 0 ? "SUCCEEDED" : "FAILED",
+        message: errors.length === 0
+            ? `已整理 ${modules.length} 份模块文档`
+            : `${errors.length} 份模块文档读取失败`,
+    });
     return outcome("docs", errors.length === 0 ? "SUCCEEDED" : "FAILED", root, {
         modules,
         errors,
@@ -223,6 +249,12 @@ async function handleInstall(root, runtime) {
             ? {}
             : { runner: runtime.registryRunner }),
     });
+    reportProgress(runtime.onProgress, {
+        command: "install",
+        phase: "registry",
+        status: "SUCCEEDED",
+        message: `已发现 ${discovered.candidates.length} 个注册模块`,
+    });
     if (discovered.rejected.length > 0)
         throw new PlatformError("REGISTRY_RESPONSE_INVALID", `registry contains rejected ProFlow packages: ${discovered.rejected.map((item) => `${item.packageName}:${item.reason}`).join(", ")}`);
     if (discovered.candidates.length === 0)
@@ -324,11 +356,23 @@ async function handleUninstall(root, runtime) {
     });
 }
 async function handleSetup(root, parsed, runtime) {
+    reportProgress(runtime.onProgress, {
+        command: "setup",
+        phase: "setup",
+        status: "STARTED",
+        message: "正在分析模块配置",
+    });
     const { catalog, modules } = await buildContext(root);
     const target = parsed.moduleRef === undefined
         ? undefined
         : { moduleRef: parsed.moduleRef };
-    const result = await setupModulesThin(catalog, modules, root, target, runtime.onProgress);
+    const result = await setupModulesThin(catalog, modules, root, target, undefined);
+    reportProgress(runtime.onProgress, {
+        command: "setup",
+        phase: "setup",
+        status: result.completed ? "SUCCEEDED" : "ACTION_REQUIRED",
+        message: result.completed ? "模块配置已就绪" : "配置清单已生成",
+    });
     return outcome("setup", batchStatus(result), root, result);
 }
 async function handleStart(root, runtime) {
@@ -417,17 +461,52 @@ function renderStatus(data) {
         FAILED: "运行失败",
         NOT_APPLICABLE: "无独立进程",
     };
-    return [
-        "ProFlow 模块状态",
-        "",
-        "模块                         版本       配置状态   运行状态",
-        ...data.modules
-            .filter(isRecord)
-            .map((raw) => `${String(raw.moduleRef).padEnd(28)} ${String(raw.version).padEnd(10)} ${(setupLabels[String(raw.setupStatus)] ?? "未知").padEnd(10)} ${runtimeLabels[String(raw.runtimeStatus)] ?? "未知"}`),
-        "",
-        "需要操作：运行 platform setup",
-        "失败：运行 platform setup 查看原因和修复步骤",
-    ].join("\n");
+    const modules = data.modules.filter(isRecord);
+    const lines = ["ProFlow 状态", ""];
+    for (const raw of modules) {
+        const moduleRef = String(raw.moduleRef);
+        const setupStatus = String(raw.setupStatus);
+        const runtimeStatus = String(raw.runtimeStatus);
+        const failed = setupStatus === "FAILED" || runtimeStatus === "FAILED";
+        const actionRequired = setupStatus === "ACTION_REQUIRED";
+        const icon = failed
+            ? "✕"
+            : actionRequired
+                ? "◆"
+                : runtimeStatus === "RUNNING"
+                    ? "●"
+                    : runtimeStatus === "NOT_APPLICABLE"
+                        ? "○"
+                        : "✓";
+        lines.push(`${icon} ${moduleRef.padEnd(30)} ${String(raw.version).padEnd(9)} ${setupLabels[setupStatus] ?? "未知"} · ${runtimeLabels[runtimeStatus] ?? "未知"}`);
+        if (failed) {
+            lines.push(`  原因：${setupStatus === "FAILED" ? "模块配置检查失败" : "模块运行状态异常"}`, `  下一步：platform setup --module ${moduleRef}`);
+        }
+        else if (actionRequired) {
+            lines.push("  原因：模块尚未完成配置", `  下一步：platform setup --module ${moduleRef}`);
+        }
+    }
+    const ready = modules.filter((item) => item.setupStatus === "READY").length;
+    const action = modules.filter((item) => item.setupStatus === "ACTION_REQUIRED").length;
+    const failed = modules.filter((item) => item.setupStatus === "FAILED").length;
+    lines.push("", `汇总：${ready} 已就绪 · ${action} 需要操作 · ${failed} 失败`);
+    return lines.join("\n");
+}
+function renderTerminalMarkdown(source) {
+    return source
+        .split(/\r?\n/)
+        .map((line) => {
+        const heading = line.match(/^#{1,6}\s+(.+)$/);
+        if (heading?.[1])
+            return heading[1].replaceAll("`", "");
+        const bullet = line.match(/^\s*-\s+(.+)$/);
+        if (bullet?.[1])
+            return `  • ${bullet[1].replaceAll("`", "")}`;
+        return line.replaceAll("`", "");
+    })
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
 }
 function renderDocs(data) {
     if (!isRecord(data) || !Array.isArray(data.modules))
@@ -435,7 +514,7 @@ function renderDocs(data) {
     const lines = ["ProFlow 模块文档"];
     for (const raw of data.modules)
         if (isRecord(raw))
-            lines.push("", `## ${String(raw.moduleRef)} @ ${String(raw.version)}`, String(raw.docs ?? ""));
+            lines.push("", "─".repeat(72), `${String(raw.moduleRef)}  ${String(raw.version)}`, "", renderTerminalMarkdown(String(raw.docs ?? "")));
     if (Array.isArray(data.errors) && data.errors.length > 0)
         lines.push("", "文档读取失败：", ...data.errors
             .filter(isRecord)
@@ -497,24 +576,24 @@ function renderSetup(data) {
             blocked += 1;
         else
             needsAction += 1;
-        lines.push(moduleRef);
+        lines.push(`${status === "FAILED" ? "✕" : "◆"} ${moduleRef}`);
         const plan = moduleSetupPlanDataSchema.safeParse(raw.result.data);
         if (plan.success) {
             for (const [index, step] of plan.data.steps.entries()) {
-                lines.push(`  [${step.state} ${index + 1}/${plan.data.steps.length}] ${step.title}`);
-                lines.push(`  人工执行：${step.execution.interactive}`);
-                lines.push(`  AI 执行：${step.execution.nonInteractive}`);
+                lines.push(`  ${index + 1}. ${step.title}`);
+                lines.push(`     运行：${step.execution.interactive}`);
+                lines.push(`     自动执行：${step.execution.nonInteractive}`);
                 if (step.requiredInputs.length > 0)
-                    lines.push(`  需要输入：${step.requiredInputs.map((item) => item.description).join("、")}`);
-                lines.push(`  验证：${step.verify}`);
-                lines.push(`  完成条件：${step.successCondition}`);
+                    lines.push(`     需要：${step.requiredInputs.map((item) => item.description).join("、")}`);
+                lines.push(`     验证：${step.verify}`);
+                lines.push(`     完成：${step.successCondition}`);
                 if (step.blockedReason)
-                    lines.push(`  原因：${step.blockedReason}`);
+                    lines.push(`     原因：${step.blockedReason}`);
             }
             lines.push("");
             continue;
         }
-        lines.push(`  [${status === "FAILED" ? "BLOCKED" : "TODO"} 1/1] ${status === "FAILED" ? "等待上游服务信息" : "完成模块配置"}`);
+        lines.push(`  1. ${status === "FAILED" ? "等待上游服务信息" : "完成模块配置"}`);
         const error = raw.result.error;
         if (status !== "FAILED") {
             const commands = setupCommands[moduleRef] ?? {
@@ -615,9 +694,9 @@ export function renderHumanResult(result) {
 }
 if (import.meta.main) {
     const argv = process.argv.slice(2);
-    const result = await runCli(argv, {
-        onProgress: createTerminalProgressReporter(),
-    });
+    const reporter = createTerminalProgressReporter();
+    const result = await runCli(argv, { onProgress: reporter });
+    reporter.close();
     process.stdout.write(`${renderHumanResult(result)}\n`);
     if (result.status !== "SUCCEEDED")
         process.exitCode = 1;

package/dist/src/terminal.d.ts

@@ -1,2 +1,5 @@
 import type { PlatformProgressReporter } from "./progress.ts";
-export declare function createTerminalProgressReporter(stream?: NodeJS.WriteStream): PlatformProgressReporter;
+export type TerminalProgressReporter = PlatformProgressReporter & {
+    close(): void;
+};
+export declare function createTerminalProgressReporter(stream?: NodeJS.WriteStream): TerminalProgressReporter;

package/dist/src/terminal.js

@@ -6,10 +6,9 @@ const colors = {
     dim: "\u001b[2m",
     reset: "\u001b[0m",
 };
-function progressLine(event, color) {
-    const prefix = event.current && event.total
-        ? `[${String(event.current).padStart(2, "0")}/${event.total}] `
-        : "";
+const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function progressLine(event, color, spinner = "") {
+    const prefix = event.current && event.total ? `${event.current}/${event.total} · ` : "";
     const suffix = event.status === "SUCCEEDED"
         ? "完成"
         : event.status === "ACTION_REQUIRED"
@@ -19,20 +18,48 @@ function progressLine(event, color) {
                 : event.status === "SKIPPED"
                     ? "跳过"
                     : "";
-    if (!color || suffix === "")
-        return `${prefix}${event.message}${suffix ? `… ${suffix}` : "…"}`;
+    const symbol = event.status === "STARTED"
+        ? spinner
+        : event.status === "SUCCEEDED"
+            ? "✓"
+            : event.status === "FAILED"
+                ? "✕"
+                : event.status === "ACTION_REQUIRED"
+                    ? "◆"
+                    : "○";
+    if (!color)
+        return `${symbol ? `${symbol} ` : ""}${prefix}${event.message}${suffix ? ` · ${suffix}` : ""}`;
     const tone = event.status === "SUCCEEDED"
         ? colors.green
         : event.status === "FAILED"
             ? colors.red
             : colors.yellow;
-    return `${colors.dim}${prefix}${colors.reset}${event.message}… ${tone}${suffix}${colors.reset}`;
+    return `${tone}${symbol}${colors.reset} ${colors.dim}${prefix}${colors.reset}${event.message}${suffix ? ` · ${tone}${suffix}${colors.reset}` : ""}`;
 }
 export function createTerminalProgressReporter(stream = process.stderr) {
     const interactive = stream.isTTY === true;
-    const color = interactive && !("NO_COLOR" in process.env);
-    return (event) => {
-        const line = progressLine(event, color);
+    const color = interactive &&
+        process.env.NO_COLOR === undefined &&
+        process.env.TERM !== "dumb";
+    let timer;
+    let frame = 0;
+    let active;
+    const clearSpinner = () => {
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+    };
+    const paint = () => {
+        if (!active)
+            return;
+        cursorTo(stream, 0);
+        clearLine(stream, 0);
+        stream.write(progressLine(active, color, spinnerFrames[frame++ % spinnerFrames.length]));
+    };
+    const reporter = ((event) => {
+        clearSpinner();
+        active = event.status === "STARTED" ? event : undefined;
+        const line = progressLine(event, color, spinnerFrames[frame++ % spinnerFrames.length]);
         if (!interactive) {
             stream.write(`${line}\n`);
             return;
@@ -40,7 +67,26 @@ export function createTerminalProgressReporter(stream = process.stderr) {
         cursorTo(stream, 0);
         clearLine(stream, 0);
         stream.write(line);
-        if (event.status !== "STARTED")
+        if (event.status === "STARTED") {
+            timer = setInterval(paint, 80);
+            timer.unref();
+            return;
+        }
+        const compactModuleProgress = event.current !== undefined &&
+            event.total !== undefined &&
+            event.current < event.total &&
+            event.status !== "FAILED" &&
+            event.status !== "ACTION_REQUIRED";
+        if (!compactModuleProgress)
             stream.write("\n");
+    });
+    reporter.close = () => {
+        clearSpinner();
+        if (interactive && active) {
+            cursorTo(stream, 0);
+            clearLine(stream, 0);
+        }
+        active = undefined;
     };
+    return reporter;
 }

package/package.json

@@ -1,48 +1,48 @@
 {
-	"name": "@tomflow/proflow-platform-cli",
-	"version": "0.1.28",
-	"type": "module",
-	"publishConfig": {
-		"access": "public"
-	},
-	"exports": {
-		".": "./dist/src/index.js",
-		"./cli": "./dist/src/cli.js",
-		"./command": "./dist/src/command.js",
-		"./deployment/adapter": "./dist/deployment/adapter.js",
-		"./deployment/descriptor": "./dist/deployment/descriptor.js"
-	},
-	"bin": {
-		"platform": "./dist/src/cli.js"
-	},
-	"files": [
-		"dist",
-		"proflow.module.json",
-		"conformance.json",
-		"README.md",
-		"DOCS.md",
-		"SETUP.md"
-	],
-	"scripts": {
-		"test": "node --test tests/**/*.test.ts",
-		"typecheck": "tsc --noEmit"
-	},
-	"dependencies": {
-		"@tomflow/proflow-module-contract": "^0.1.9"
-	},
-	"devDependencies": {
-		"@tomflow/proflow-deployment-conformance": "^0.1.7",
-		"@tomflow/proflow-module-template": "^0.1.7"
-	},
-	"description": "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",
-	"keywords": [
-		"proflow",
-		"proflow-module",
-		"deployment-governance"
-	],
-	"proflow": {
-		"module": true,
-		"descriptor": "./dist/deployment/descriptor.js",
-		"manifest": "./proflow.module.json"
-	}
-}
+  "name": "@tomflow/proflow-platform-cli",
+  "version": "0.1.29",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./cli": "./dist/src/cli.js",
+    "./command": "./dist/src/command.js",
+    "./deployment/adapter": "./dist/deployment/adapter.js",
+    "./deployment/descriptor": "./dist/deployment/descriptor.js"
+  },
+  "bin": {
+    "platform": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "proflow.module.json",
+    "conformance.json",
+    "README.md",
+    "DOCS.md",
+    "SETUP.md"
+  ],
+  "dependencies": {
+    "@tomflow/proflow-module-contract": "^0.1.10"
+  },
+  "devDependencies": {
+    "@tomflow/proflow-module-template": "^0.1.8",
+    "@tomflow/proflow-deployment-conformance": "^0.1.8"
+  },
+  "description": "Thin Platform CLI for Module discovery, documentation, package synchronization and lifecycle orchestration.",
+  "keywords": [
+    "proflow",
+    "proflow-module",
+    "deployment-governance"
+  ],
+  "proflow": {
+    "module": true,
+    "descriptor": "./dist/deployment/descriptor.js",
+    "manifest": "./proflow.module.json"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "platform-cli",
 	"packageName": "@tomflow/proflow-platform-cli",
-	"moduleVersion": "0.1.28",
+	"moduleVersion": "0.1.29",
 	"kind": "cli",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",