@tomflow/proflow-dev-tunnel 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-dev-tunnel
 
+## 0.1.13
+
+### Patch Changes
+
+- Upgrade the ProFlow terminal experience, stream Registry and package-manager progress, publish structured Chinese Module documentation, and provide numbered package-owned Setup assistants.
+
 ## 0.1.12
 
 ### Patch Changes

package/DOCS.md

@@ -1,13 +1,39 @@
-# dev-tunnel
+# dev-tunnel — 开发隧道
 
-Dev Tunnel（开发隧道）把本机 Agent Gateway 安全地映射为公开 HTTPS 地址，供 Custom GPT Actions 调用。
+## 模块定位与作用
 
-## 什么时候需要
+使用 Microsoft Dev Tunnels 把本地 Agent Gateway 安全映射为公开 HTTPS 入口，供 Custom GPT Actions 调用。
 
-当 ProFlow 在本机运行，而 Custom GPT 需要从互联网访问本机网关时使用。
+## 主要能力
 
-## 如何配置
+- 检查 `devtunnel` CLI 与 Microsoft 登录状态。
+- 列出、选择或创建持久 Tunnel，并管理端口映射和运行进程。
+- 观察公开 HTTPS URL，将其发布为共享事实。
 
-运行 `pnpm exec -- proflow-dev-tunnel setup`。向导会检查 `devtunnel` 工具和登录状态，列出现有 Tunnel（隧道），协助选择或创建持久隧道，然后保存并验证公开地址。
+## 提供的 API 与 Public Contract
 
-公开地址会被外部服务访问，请只暴露 ProFlow 网关需要的端口。
+- 提供 `public-ingress` Contract，版本 `1.0.0`。
+- 共享当前 Tunnel ID 与公开 Base URL，不暴露账号凭据。
+
+## 依赖的 Module、Contract 和外部资源
+
+- 依赖 Microsoft `devtunnel` CLI、账号登录、网络和本地 Platform Host 端口。
+- 无上游 Module Contract 依赖。
+
+## 运行形态与生命周期
+
+类型为 External Resource，拥有可启动和停止的 Tunnel 子进程；持久 Tunnel 本身在卸载时保留。
+
+## 使用方式
+
+运行 `pnpm exec -- proflow-dev-tunnel setup`，向导会完成登录检查、Tunnel 选择/创建、端口映射和 URL 验证。
+
+## 职责边界与限制
+
+不拥有 Agent Gateway 业务、不复制 Role Key，也不把临时 Quick Tunnel 当成正式持久入口。
+
+## 术语
+
+- Tunnel（隧道）：把本地端口映射到公网 HTTPS 地址的连接。
+- Public Ingress（公网入口）：外部服务访问本地 Gateway 的受控入口。
+- Persistent Tunnel（持久隧道）：具有稳定 ID、可重复启动的 Tunnel。

package/SETUP.md

@@ -1,10 +1,33 @@
-# @tomflow/proflow-dev-tunnel — Module Setup
+# dev-tunnel Setup
 
-## STEP-DEV-TUNNEL-01 — 选择或创建持久 Tunnel
+## STEP-DEV-TUNNEL-01 — 检查 Dev Tunnel CLI 与登录
+Responsible: USER
+Interactive executable: `pnpm exec -- proflow-dev-tunnel setup 01`
+Non-interactive executable: `pnpm exec -- proflow-dev-tunnel setup 01`
+Required inputs: Microsoft 登录
+Verify: `devtunnel user show`
+Success condition: Microsoft 登录状态可被 CLI 观察。
+
+## STEP-DEV-TUNNEL-02 — 选择或创建持久 Tunnel
+Responsible: USER
+Interactive executable: `pnpm exec -- proflow-dev-tunnel setup 02`
+Non-interactive executable: `pnpm exec -- proflow-dev-tunnel setup 02 --tunnel-id <id>`
+Required inputs: Tunnel ID
+Verify: `devtunnel show <id>`
+Success condition: 持久 Tunnel 可以被 devtunnel show 观察。
 
+## STEP-DEV-TUNNEL-03 — 配置入口并保存公开 URL
 Responsible: USER
-Interactive executable: `pnpm exec -- proflow-dev-tunnel setup`
-Non-interactive executable: `pnpm exec -- proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>`
+Interactive executable: `pnpm exec -- proflow-dev-tunnel setup 03`
+Non-interactive executable: `pnpm exec -- proflow-dev-tunnel setup 03 --tunnel-id <id> --public-base-url <url>`
 Required inputs: Tunnel ID、公开 HTTPS URL
 Verify: `pnpm exec -- proflow-dev-tunnel verify`
+Success condition: 公开 HTTPS URL 已保存并可验证。
+
+## STEP-DEV-TUNNEL-04 — 验证 Dev Tunnel
+Responsible: AI
+Interactive executable: `pnpm exec -- proflow-dev-tunnel setup 04`
+Non-interactive executable: `pnpm exec -- proflow-dev-tunnel verify`
+Required inputs: none
+Verify: `pnpm exec -- proflow-dev-tunnel verify`
 Success condition: `dev-tunnel.setupStatus=READY`.

package/dist/deployment/adapter.d.ts

@@ -6,7 +6,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: never[];
     }>;
@@ -16,14 +16,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "FAILED";
             error: {
@@ -40,7 +40,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
@@ -52,18 +52,50 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "ACTION_REQUIRED";
             data: {
                 readonly steps: readonly [{
                     readonly id: "STEP-DEV-TUNNEL-01";
+                    readonly title: "检查 Dev Tunnel CLI 与登录";
+                    readonly description: "确认 CLI 可用，必要时启动 Microsoft 登录。";
+                    readonly state: "TODO";
+                    readonly responsible: "USER";
+                    readonly execution: {
+                        readonly interactive: "pnpm exec -- proflow-dev-tunnel setup 01";
+                        readonly nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 01";
+                    };
+                    readonly requiredInputs: readonly [];
+                    readonly verify: "devtunnel user show";
+                    readonly successCondition: "Microsoft 登录状态可被 CLI 观察";
+                    readonly humanAction: "若浏览器打开 Microsoft 登录页，完成账号登录。";
+                }, {
+                    readonly id: "STEP-DEV-TUNNEL-02";
                     readonly title: "选择或创建持久 Tunnel";
+                    readonly description: "列出现有 Tunnel；不存在时由脚本创建。";
                     readonly state: "TODO";
                     readonly responsible: "USER";
                     readonly execution: {
-                        readonly interactive: "pnpm exec -- proflow-dev-tunnel setup";
-                        readonly nonInteractive: "pnpm exec -- proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>";
+                        readonly interactive: "pnpm exec -- proflow-dev-tunnel setup 02";
+                        readonly nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 02 --tunnel-id <id>";
+                    };
+                    readonly requiredInputs: readonly [{
+                        readonly name: "tunnelId";
+                        readonly description: "Tunnel ID";
+                        readonly sensitive: false;
+                    }];
+                    readonly verify: "devtunnel show <id>";
+                    readonly successCondition: "持久 Tunnel 可以被 devtunnel show 观察";
+                }, {
+                    readonly id: "STEP-DEV-TUNNEL-03";
+                    readonly title: "配置入口并保存公开 URL";
+                    readonly description: "为 Platform Host 建立映射，保存公开 HTTPS URL。";
+                    readonly state: "TODO";
+                    readonly responsible: "USER";
+                    readonly execution: {
+                        readonly interactive: "pnpm exec -- proflow-dev-tunnel setup 03";
+                        readonly nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 03 --tunnel-id <id> --public-base-url <url>";
                     };
                     readonly requiredInputs: readonly [{
                         readonly name: "tunnelId";
@@ -75,7 +107,21 @@ export declare const behaviorAdapter: {
                         readonly sensitive: false;
                     }];
                     readonly verify: "pnpm exec -- proflow-dev-tunnel verify";
-                    readonly successCondition: "配置状态变为“已就绪”";
+                    readonly successCondition: "公开 HTTPS URL 已保存并可验证";
+                    readonly humanAction: "确认 Dev Tunnel 门户或 CLI 显示的公开 HTTPS URL。";
+                }, {
+                    readonly id: "STEP-DEV-TUNNEL-04";
+                    readonly title: "验证 Dev Tunnel";
+                    readonly description: "检查登录、配置和公开入口。";
+                    readonly state: "TODO";
+                    readonly responsible: "AI";
+                    readonly execution: {
+                        readonly interactive: "pnpm exec -- proflow-dev-tunnel setup 04";
+                        readonly nonInteractive: "pnpm exec -- proflow-dev-tunnel verify";
+                    };
+                    readonly requiredInputs: readonly [];
+                    readonly verify: "pnpm exec -- proflow-dev-tunnel verify";
+                    readonly successCondition: "dev-tunnel.setupStatus=READY";
                 }];
             };
             actionRequired: {
@@ -90,7 +136,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: never[];
     }>;
@@ -100,7 +146,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: {
                 docs: string;
             };
@@ -111,7 +157,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "FAILED";
             error: {
@@ -127,7 +173,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             data: import("../src/resource-adapter.ts").DevTunnelObservation;
         };
         observedEffects: string[];
@@ -138,14 +184,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.12";
+            readonly moduleVersion: "0.1.13";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.12";
+            moduleVersion: "0.1.13";
             ok: false;
             status: "FAILED";
             error: {

package/dist/deployment/adapter.js

@@ -15,12 +15,44 @@ const setupPlan = {
     steps: [
         {
             id: "STEP-DEV-TUNNEL-01",
+            title: "检查 Dev Tunnel CLI 与登录",
+            description: "确认 CLI 可用，必要时启动 Microsoft 登录。",
+            state: "TODO",
+            responsible: "USER",
+            execution: {
+                interactive: "pnpm exec -- proflow-dev-tunnel setup 01",
+                nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 01",
+            },
+            requiredInputs: [],
+            verify: "devtunnel user show",
+            successCondition: "Microsoft 登录状态可被 CLI 观察",
+            humanAction: "若浏览器打开 Microsoft 登录页，完成账号登录。",
+        },
+        {
+            id: "STEP-DEV-TUNNEL-02",
             title: "选择或创建持久 Tunnel",
+            description: "列出现有 Tunnel；不存在时由脚本创建。",
             state: "TODO",
             responsible: "USER",
             execution: {
-                interactive: "pnpm exec -- proflow-dev-tunnel setup",
-                nonInteractive: "pnpm exec -- proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>",
+                interactive: "pnpm exec -- proflow-dev-tunnel setup 02",
+                nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 02 --tunnel-id <id>",
+            },
+            requiredInputs: [
+                { name: "tunnelId", description: "Tunnel ID", sensitive: false },
+            ],
+            verify: "devtunnel show <id>",
+            successCondition: "持久 Tunnel 可以被 devtunnel show 观察",
+        },
+        {
+            id: "STEP-DEV-TUNNEL-03",
+            title: "配置入口并保存公开 URL",
+            description: "为 Platform Host 建立映射，保存公开 HTTPS URL。",
+            state: "TODO",
+            responsible: "USER",
+            execution: {
+                interactive: "pnpm exec -- proflow-dev-tunnel setup 03",
+                nonInteractive: "pnpm exec -- proflow-dev-tunnel setup 03 --tunnel-id <id> --public-base-url <url>",
             },
             requiredInputs: [
                 { name: "tunnelId", description: "Tunnel ID", sensitive: false },
@@ -31,7 +63,22 @@ const setupPlan = {
                 },
             ],
             verify: "pnpm exec -- proflow-dev-tunnel verify",
-            successCondition: "配置状态变为“已就绪”",
+            successCondition: "公开 HTTPS URL 已保存并可验证",
+            humanAction: "确认 Dev Tunnel 门户或 CLI 显示的公开 HTTPS URL。",
+        },
+        {
+            id: "STEP-DEV-TUNNEL-04",
+            title: "验证 Dev Tunnel",
+            description: "检查登录、配置和公开入口。",
+            state: "TODO",
+            responsible: "AI",
+            execution: {
+                interactive: "pnpm exec -- proflow-dev-tunnel setup 04",
+                nonInteractive: "pnpm exec -- proflow-dev-tunnel verify",
+            },
+            requiredInputs: [],
+            verify: "pnpm exec -- proflow-dev-tunnel verify",
+            successCondition: "dev-tunnel.setupStatus=READY",
         },
     ],
 };

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "dev-tunnel";
     readonly packageName: "@tomflow/proflow-dev-tunnel";
-    readonly moduleVersion: "0.1.12";
+    readonly moduleVersion: "0.1.13";
     readonly kind: "external-resource";
     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: "dev-tunnel",
     packageName: "@tomflow/proflow-dev-tunnel",
-    moduleVersion: "0.1.12",
+    moduleVersion: "0.1.13",
     kind: "external-resource",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/cli.js

@@ -12,6 +12,55 @@ function option(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
 }
+function ensureCliAndLogin() {
+    const version = spawnSync("devtunnel", ["--version"], { stdio: "ignore" });
+    if (version.error || version.status !== 0)
+        throw new Error("未找到 devtunnel CLI，请先安装 Microsoft Dev Tunnels CLI");
+    process.stdout.write("✓ 已找到 devtunnel CLI\n");
+    let login = spawnSync("devtunnel", ["user", "show"], { stdio: "ignore" });
+    if (login.status !== 0) {
+        process.stdout.write("◆ 需要 Microsoft 登录，正在启动登录流程…\n");
+        login = spawnSync("devtunnel", ["user", "login"], { stdio: "inherit" });
+        if (login.status !== 0)
+            throw new Error("Microsoft 登录未完成");
+    }
+    process.stdout.write("✓ Microsoft 登录已就绪\n");
+}
+async function selectTunnel(args) {
+    ensureCliAndLogin();
+    let tunnelId = option(args, "--tunnel-id");
+    if (!tunnelId && !process.stdin.isTTY)
+        throw new Error("非交互环境必须提供 --tunnel-id");
+    process.stdout.write("\n现有持久 Tunnel：\n");
+    spawnSync("devtunnel", ["list"], { stdio: "inherit" });
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        tunnelId ||= await prompt.question("\n◆ 输入要使用的 Tunnel ID\n> ");
+        const existing = spawnSync("devtunnel", ["show", tunnelId], {
+            stdio: "ignore",
+        });
+        if (existing.status !== 0) {
+            if (process.stdin.isTTY) {
+                const answer = await prompt.question(`未找到 ${tunnelId}，现在创建？[Y/n] `);
+                if (answer.trim() && !/^y(es)?$/i.test(answer.trim()))
+                    throw new Error("尚未选择持久 Tunnel");
+            }
+            const created = spawnSync("devtunnel", ["create", tunnelId], {
+                stdio: "inherit",
+            });
+            if (created.status !== 0)
+                throw new Error("创建持久 Tunnel 失败");
+        }
+        process.stdout.write(`✓ 持久 Tunnel 已就绪：${tunnelId}\n`);
+        return tunnelId;
+    }
+    finally {
+        prompt.close();
+    }
+}
 async function inputs(args) {
     let tunnelId = option(args, "--tunnel-id"), publicBaseUrl = option(args, "--public-base-url");
     if ((!tunnelId || !publicBaseUrl) && !process.stdin.isTTY)
@@ -23,20 +72,8 @@ async function inputs(args) {
         });
         try {
             process.stdout.write("\nDev Tunnel 配置\n\n  脚本将检查 CLI、完成 Microsoft 登录，并协助选择或创建持久 Tunnel（隧道）。\n\n");
-            const version = spawnSync("devtunnel", ["--version"], {
-                stdio: "ignore",
-            });
-            if (version.error || version.status !== 0)
-                throw new Error("未找到 devtunnel CLI。请先按 Microsoft Dev Tunnels 文档安装，然后重新运行本命令");
-            process.stdout.write("✓ 已找到 devtunnel CLI\n");
-            let login = spawnSync("devtunnel", ["user", "show"], { stdio: "ignore" });
-            if (login.status !== 0) {
-                process.stdout.write("◆ 需要登录 Microsoft 账号，正在启动登录流程…\n");
-                login = spawnSync("devtunnel", ["user", "login"], { stdio: "inherit" });
-                if (login.status !== 0)
-                    throw new Error("Microsoft 登录未完成");
-            }
-            process.stdout.write("✓ Microsoft 登录已就绪\n\n现有持久 Tunnel：\n");
+            ensureCliAndLogin();
+            process.stdout.write("\n现有持久 Tunnel：\n");
             spawnSync("devtunnel", ["list"], { stdio: "inherit" });
             tunnelId ||= await prompt.question("\n◆ 输入要使用的 Tunnel ID（不存在时可创建）\n> ");
             const existing = spawnSync("devtunnel", ["show", tunnelId], {
@@ -68,6 +105,28 @@ const args = process.argv.slice(2), command = args[0] ?? "setup", workspaceRoot
 if (args.includes("--json"))
     throw new Error("不支持的选项 --json");
 if (command === "setup") {
+    const step = args[1]?.startsWith("--") ? undefined : args[1];
+    if (step === "01") {
+        ensureCliAndLogin();
+        process.stdout.write("→ 下一步：setup 02（选择或创建持久 Tunnel）\n");
+        process.exit(0);
+    }
+    if (step === "02") {
+        await selectTunnel(args);
+        process.stdout.write("→ 下一步：setup 03（配置入口并保存公开 URL）\n");
+        process.exit(0);
+    }
+    if (step === "04") {
+        const result = await behaviorAdapter.status({ workspaceRoot });
+        process.stdout.write(result.result.data.setupStatus === "READY"
+            ? "✓ Dev Tunnel 验证通过\n"
+            : "✕ Dev Tunnel 尚未就绪\n");
+        if (result.result.data.setupStatus !== "READY")
+            process.exitCode = 1;
+        process.exit();
+    }
+    if (step !== undefined && step !== "03")
+        throw new Error(`UNSUPPORTED_SETUP_STEP:${step}`);
     const result = await behaviorAdapter.setup({
         workspaceRoot,
         input: await inputs(args),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-dev-tunnel",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -22,10 +22,10 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.10"
+    "@tomflow/proflow-module-contract": "^0.1.11"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.8"
+    "@tomflow/proflow-deployment-conformance": "^0.1.9"
   },
   "description": "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.",
   "keywords": [

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "dev-tunnel",
 	"packageName": "@tomflow/proflow-dev-tunnel",
-	"moduleVersion": "0.1.12",
+	"moduleVersion": "0.1.13",
 	"kind": "external-resource",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",