@tomflow/proflow-dev-tunnel 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @tomflow/proflow-dev-tunnel
 
+## 0.1.15
+
+### Patch Changes
+
+- Ship the Phase 3 browser, tunnel, model automation, platform readiness, and documentation closure as one verifiable platform snapshot.
+
+## 0.1.14
+
+### Patch Changes
+
+- Distinguish dependency blocking from verified failure, expose Module-owned status diagnostics, remove automatic docs paging, consolidate start checks, add contextual help, and clarify uninstall output.
+
 ## 0.1.13
 
 ### Patch Changes

package/DOCS.md

@@ -6,9 +6,10 @@
 
 ## 主要能力
 
-- 检查 `devtunnel` CLI 与 Microsoft 登录状态。
-- 列出、选择或创建持久 Tunnel，并管理端口映射和运行进程。
-- 观察公开 HTTPS URL，将其发布为共享事实。
+- 检查 `devtunnel` CLI 与登录状态；缺失时启动 GitHub browser auth。
+- 按 workspace state 复用或自动创建持久 Tunnel，并自动管理端口映射和运行进程。
+- 从 `agent-gateway` producer-owned shared facts 获得本地端口。
+- 按当前端口自动发现公开 HTTPS URL，将其发布为共享事实。
 
 ## 提供的 API 与 Public Contract
 
@@ -17,8 +18,8 @@
 
 ## 依赖的 Module、Contract 和外部资源
 
-- 依赖 Microsoft `devtunnel` CLI、账号登录、网络和本地 Platform Host 端口。
-- 无上游 Module Contract 依赖。
+- 依赖 Microsoft `devtunnel` CLI、账号登录、网络和 `agent-gateway` 发布的 `localBaseUrl` shared fact。
+- 不建立对 `agent-gateway` 的运行时或包依赖；只消费 Platform Host 中由该 Module 持久化的 producer-owned fact。
 
 ## 运行形态与生命周期
 
@@ -26,7 +27,7 @@
 
 ## 使用方式
 
-运行 `pnpm exec -- proflow-dev-tunnel setup`，向导会完成登录检查、Tunnel 选择/创建、端口映射和 URL 验证。
+运行 `platform setup --module dev-tunnel`；除登录失效时的 GitHub 浏览器授权外，不需要输入 Tunnel ID、端口或 URL。
 
 ## 职责边界与限制
 

package/README.md

@@ -23,5 +23,6 @@ Deployment Governance
 
 ## Purpose
 
-Manages the Microsoft Dev Tunnel (`devtunnel`) public HTTPS ingress. Login is a
-user external-account fact and is never faked.
+Manages the Microsoft Dev Tunnel (`devtunnel`) public HTTPS ingress. Existing
+login is reused; when login is unavailable, the only human action is GitHub
+browser authorization initiated by the provider CLI. Account state is never faked.

package/SETUP.md

@@ -1,33 +1,30 @@
 # dev-tunnel Setup
 
-## 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 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-01 — 自动准备 Microsoft Dev Tunnel
 
-## 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`
+
+Interactive executable: `platform setup --module dev-tunnel`
+
+Non-interactive executable: `pnpm exec -- proflow-dev-tunnel setup --workspace <path>`
+
 Required inputs: none
+
+Human action: 仅当现有登录无效时，在 `devtunnel user login --github --use-browser-auth` 打开的浏览器页面完成 GitHub 授权。
+
+Automatic flow:
+
+```text
+检查 CLI 和登录
+→ 必要时完成 GitHub browser auth 并复核登录
+→ 复用 workspace-owned Tunnel 或自动创建
+→ 从 agent-gateway shared facts 读取本地端口
+→ 自动对齐 port mapping
+→ 启动或复用 host
+→ 自动发现当前端口的 HTTPS URL
+→ 持久化并发布 tunnelId/publicBaseUrl
+```
+
 Verify: `pnpm exec -- proflow-dev-tunnel verify`
+
 Success condition: `dev-tunnel.setupStatus=READY`.

package/dist/deployment/adapter.d.ts

@@ -1,12 +1,28 @@
 import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
-export declare const behaviorAdapter: {
+import { type DevTunnelAutomation, type DevTunnelRuntime } from "../src/resource-adapter.ts";
+type SetupState = {
+    contract: "proflow.dev-tunnel-setup.v1";
+    tunnelId: string;
+    publicBaseUrl: string;
+};
+type RuntimeFactory = (input: {
+    command?: string;
+    tunnelId?: string;
+    publicBaseUrl?: string;
+    processStateFile?: string;
+}) => DevTunnelRuntime;
+export declare function createDevTunnelBehaviorAdapter(dependencies?: {
+    automation?: DevTunnelAutomation;
+    createRuntime?: RuntimeFactory;
+    verifyPublicBaseUrl?: (publicBaseUrl: string) => Promise<void>;
+}): {
     readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.13";
+            readonly moduleVersion: "0.1.15";
         };
         observedEffects: never[];
     }>;
@@ -16,14 +32,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.13";
+            readonly moduleVersion: "0.1.15";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             ok: false;
             status: "FAILED";
             error: {
@@ -40,103 +56,174 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
+                issues?: ({
+                    scope: "SETUP";
+                    code: string;
+                    message: string;
+                    relatedModuleRefs: never[];
+                    nextCommand: string;
+                } | {
+                    scope: "RUNTIME";
+                    code: string;
+                    message: string;
+                    relatedModuleRefs: never[];
+                    nextCommand: string;
+                })[];
             };
         };
         observedEffects: never[];
     }>;
-    readonly setup: (context: ModuleCommandContext) => Promise<{
+    readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
-            ok: false;
-            status: "ACTION_REQUIRED";
+            moduleVersion: "0.1.15";
             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 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";
-                        readonly description: "Tunnel ID";
-                        readonly sensitive: false;
-                    }, {
-                        readonly name: "publicBaseUrl";
-                        readonly description: "公开 HTTPS URL";
-                        readonly sensitive: false;
-                    }];
-                    readonly verify: "pnpm exec -- proflow-dev-tunnel verify";
-                    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";
-                }];
+                docs: string;
+            };
+        };
+        observedEffects: never[];
+    }>;
+    readonly start: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "START_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            data: import("../src/resource-adapter.ts").DevTunnelObservation;
+        };
+        observedEffects: string[];
+    }>;
+    readonly stop: (context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "dev-tunnel";
+            readonly moduleVersion: "0.1.15";
+        };
+        observedEffects: string[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "STOP_FAILED";
+                message: string;
+                retryable: boolean;
             };
-            actionRequired: {
-                action: string;
-                description: string;
+        };
+        observedEffects: never[];
+    }>;
+    readonly setup: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED";
+                message: string;
+                retryable: boolean;
             };
         };
         observedEffects: never[];
     } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            data: SetupState;
+        };
+        observedEffects: string[];
+    }>;
+};
+export declare const behaviorAdapter: {
+    readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
             readonly contract: "deployment.result.v1";
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.13";
+            readonly moduleVersion: "0.1.15";
+        };
+        observedEffects: never[];
+    }>;
+    readonly uninstall: (context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "dev-tunnel";
+            readonly moduleVersion: "0.1.15";
+        };
+        observedEffects: string[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "UNINSTALL_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+        };
+        observedEffects: never[];
+    }>;
+    readonly status: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            data: {
+                setupStatus: "ACTION_REQUIRED" | "READY";
+                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
+                issues?: ({
+                    scope: "SETUP";
+                    code: string;
+                    message: string;
+                    relatedModuleRefs: never[];
+                    nextCommand: string;
+                } | {
+                    scope: "RUNTIME";
+                    code: string;
+                    message: string;
+                    relatedModuleRefs: never[];
+                    nextCommand: string;
+                })[];
+            };
         };
         observedEffects: never[];
     }>;
@@ -146,7 +233,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             data: {
                 docs: string;
             };
@@ -157,7 +244,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             ok: false;
             status: "FAILED";
             error: {
@@ -173,7 +260,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             data: import("../src/resource-adapter.ts").DevTunnelObservation;
         };
         observedEffects: string[];
@@ -184,14 +271,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.13";
+            readonly moduleVersion: "0.1.15";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.13";
+            moduleVersion: "0.1.15";
             ok: false;
             status: "FAILED";
             error: {
@@ -202,4 +289,30 @@ export declare const behaviorAdapter: {
         };
         observedEffects: never[];
     }>;
+    readonly setup: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+        };
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.15";
+            data: SetupState;
+        };
+        observedEffects: string[];
+    }>;
 };
+export {};