@tomflow/proflow-dev-tunnel 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-dev-tunnel
 
+## 0.1.17
+
+### Patch Changes
+
+- Add professional setup orchestration, Provider FAST/THINK input, recoverable managed Dev Tunnel provisioning, Browser installation guidance, and precise status diagnostics.
+
 ## 0.1.16
 
 ### Patch Changes

package/dist/deployment/adapter.d.ts

@@ -1,9 +1,13 @@
 import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
 import { type DevTunnelAutomation, type DevTunnelRuntime } from "../src/resource-adapter.ts";
+type SetupPhase = "PENDING_CREATED" | "PORT_READY" | "HOST_READY" | "READY";
 type SetupState = {
-    contract: "proflow.dev-tunnel-setup.v1";
+    contract: "proflow.dev-tunnel-setup.v2";
     tunnelId: string;
-    publicBaseUrl: string;
+    phase: SetupPhase;
+    gatewayPort?: number;
+    publicBaseUrl?: string;
+    cliPath?: string;
 };
 type RuntimeFactory = (input: {
     command?: string;
@@ -15,6 +19,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
     automation?: DevTunnelAutomation;
     createRuntime?: RuntimeFactory;
     verifyPublicBaseUrl?: (publicBaseUrl: string) => Promise<void>;
+    resolveCli?: (workspaceRoot: string) => Promise<string>;
 }): {
     readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
@@ -22,7 +27,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: never[];
     }>;
@@ -32,14 +37,14 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -56,7 +61,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
@@ -83,7 +88,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: {
                 docs: string;
             };
@@ -94,7 +99,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -110,7 +115,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: import("../src/resource-adapter.ts").DevTunnelObservation;
         };
         observedEffects: string[];
@@ -121,14 +126,14 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -143,7 +148,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -159,7 +164,7 @@ export declare function createDevTunnelBehaviorAdapter(dependencies?: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: SetupState;
         };
         observedEffects: string[];
@@ -172,7 +177,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: never[];
     }>;
@@ -182,14 +187,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -206,7 +211,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
@@ -233,7 +238,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: {
                 docs: string;
             };
@@ -244,7 +249,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -260,7 +265,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: import("../src/resource-adapter.ts").DevTunnelObservation;
         };
         observedEffects: string[];
@@ -271,14 +276,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.16";
+            readonly moduleVersion: "0.1.17";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -293,7 +298,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             ok: false;
             status: "FAILED";
             error: {
@@ -309,7 +314,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.16";
+            moduleVersion: "0.1.17";
             data: SetupState;
         };
         observedEffects: string[];

package/dist/deployment/adapter.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { resolveDevTunnelCli } from "@tomflow/proflow-devtunnel-cli";
 import { readModuleSharedFacts, writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
 import { createDevTunnelAutomation, createDevTunnelRuntime, verifyProvisionedPublicBaseUrl, } from "../src/resource-adapter.js";
 import { descriptor } from "./descriptor.js";
@@ -18,15 +19,50 @@ const processFile = (context) => join(stateDir(context), "process.json");
 async function readState(context) {
     try {
         const raw = JSON.parse(await readFile(stateFile(context), "utf8"));
-        if (raw.contract !== "proflow.dev-tunnel-setup.v1" ||
-            typeof raw.tunnelId !== "string" ||
-            !raw.tunnelId ||
-            typeof raw.publicBaseUrl !== "string")
+        if (typeof raw.tunnelId !== "string" || !raw.tunnelId)
             return undefined;
-        const url = new URL(raw.publicBaseUrl);
-        if (url.protocol !== "https:")
+        if (raw.contract === "proflow.dev-tunnel-setup.v1" &&
+            typeof raw.publicBaseUrl === "string") {
+            const url = new URL(raw.publicBaseUrl);
+            if (url.protocol !== "https:")
+                return undefined;
+            return {
+                contract: "proflow.dev-tunnel-setup.v2",
+                tunnelId: raw.tunnelId,
+                phase: "READY",
+                publicBaseUrl: url.href,
+            };
+        }
+        if (raw.contract !== "proflow.dev-tunnel-setup.v2")
+            return undefined;
+        if (raw.phase !== "PENDING_CREATED" &&
+            raw.phase !== "PORT_READY" &&
+            raw.phase !== "HOST_READY" &&
+            raw.phase !== "READY")
             return undefined;
-        return raw;
+        const gatewayPort = raw.gatewayPort;
+        if (gatewayPort !== undefined &&
+            (!Number.isInteger(gatewayPort) ||
+                Number(gatewayPort) < 1 ||
+                Number(gatewayPort) > 65_535))
+            return undefined;
+        const publicBaseUrl = raw.publicBaseUrl;
+        const cliPath = raw.cliPath;
+        if (raw.phase === "READY") {
+            if (typeof publicBaseUrl !== "string")
+                return undefined;
+            const url = new URL(publicBaseUrl);
+            if (url.protocol !== "https:")
+                return undefined;
+        }
+        return {
+            contract: "proflow.dev-tunnel-setup.v2",
+            tunnelId: raw.tunnelId,
+            phase: raw.phase,
+            ...(typeof gatewayPort === "number" ? { gatewayPort } : {}),
+            ...(typeof publicBaseUrl === "string" ? { publicBaseUrl } : {}),
+            ...(typeof cliPath === "string" ? { cliPath } : {}),
+        };
     }
     catch {
         return undefined;
@@ -41,6 +77,7 @@ async function writeState(context, state) {
 }
 function runtime(context, state) {
     return createDevTunnelRuntime({
+        ...(state?.cliPath ? { command: state.cliPath } : {}),
         ...(state
             ? { tunnelId: state.tunnelId, publicBaseUrl: state.publicBaseUrl }
             : {}),
@@ -51,7 +88,7 @@ const baseBehaviorAdapter = {
     install: async (context) => {
         await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
         const state = await readState(context);
-        if (state)
+        if (state?.phase === "READY" && state.publicBaseUrl)
             await writeModuleSharedFacts(context, descriptor.moduleRef, {
                 tunnelId: state.tunnelId,
                 publicBaseUrl: state.publicBaseUrl,
@@ -124,7 +161,9 @@ const baseBehaviorAdapter = {
         const rt = runtime(context, state);
         const login = await rt.loginStatus();
         const observed = await rt.status();
-        const configured = state !== undefined && login === "LOGGED_IN";
+        const configured = state?.phase === "READY" &&
+            typeof state.publicBaseUrl === "string" &&
+            login === "LOGGED_IN";
         const runtimeStatus = observed.state === "RUNNING"
             ? "RUNNING"
             : observed.state === "STOPPED"
@@ -148,7 +187,9 @@ const baseBehaviorAdapter = {
                                         {
                                             scope: "SETUP",
                                             code: "TUNNEL_LOGIN_REQUIRED",
-                                            message: "Dev Tunnel CLI 尚未登录或配置未保存",
+                                            message: state && state.phase !== "READY"
+                                                ? `远程连接配置已保存，当前阶段 ${state.phase}；重新运行 Platform setup 将从此处恢复`
+                                                : "Dev Tunnel CLI 尚未登录或配置未保存",
                                             relatedModuleRefs: [],
                                             nextCommand: "platform setup --module dev-tunnel",
                                         },
@@ -184,7 +225,7 @@ const baseBehaviorAdapter = {
     }),
     start: async (context) => {
         const state = await readState(context);
-        if (!state)
+        if (state?.phase !== "READY" || !state.publicBaseUrl)
             return {
                 result: {
                     ...base,
@@ -321,18 +362,23 @@ const setupFailed = (error) => ({
     observedEffects: [],
 });
 export function createDevTunnelBehaviorAdapter(dependencies) {
-    const automation = dependencies?.automation ??
-        createDevTunnelAutomation({ command: "devtunnel" });
     const createRuntime = dependencies?.createRuntime ?? createDevTunnelRuntime;
     const verifyPublicBaseUrl = dependencies?.verifyPublicBaseUrl ?? verifyProvisionedPublicBaseUrl;
     return {
         ...baseBehaviorAdapter,
         setup: async (context) => {
             try {
+                const previous = await readState(context);
+                const cliPath = previous?.cliPath ??
+                    (dependencies?.automation
+                        ? "devtunnel"
+                        : await (dependencies?.resolveCli ??
+                            (async (workspaceRoot) => (await resolveDevTunnelCli({ workspaceRoot })).command))(context.workspaceRoot));
+                const automation = dependencies?.automation ??
+                    createDevTunnelAutomation({ command: cliPath });
                 await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
                 const port = gatewayPort(await readModuleSharedFacts(context, "agent-gateway"));
                 await automation.ensureLogin();
-                const previous = await readState(context);
                 let tunnelId;
                 let safeToStartNewHost = false;
                 const createAndVerifyTunnel = async () => {
@@ -340,6 +386,13 @@ export function createDevTunnelBehaviorAdapter(dependencies) {
                     const created = await automation.inspectTunnel(createdTunnelId);
                     if (created.state !== "EXISTS")
                         throw new Error("new Dev Tunnel could not be verified by show --json");
+                    await writeState(context, {
+                        contract: "proflow.dev-tunnel-setup.v2",
+                        tunnelId: createdTunnelId,
+                        phase: "PENDING_CREATED",
+                        gatewayPort: port,
+                        cliPath,
+                    });
                     return createdTunnelId;
                 };
                 if (previous) {
@@ -360,6 +413,13 @@ export function createDevTunnelBehaviorAdapter(dependencies) {
                     safeToStartNewHost = true;
                 }
                 await automation.ensurePort(tunnelId, port);
+                await writeState(context, {
+                    contract: "proflow.dev-tunnel-setup.v2",
+                    tunnelId,
+                    phase: "PORT_READY",
+                    gatewayPort: port,
+                    cliPath,
+                });
                 const host = createRuntime({
                     tunnelId,
                     processStateFile: processFile(context),
@@ -374,15 +434,25 @@ export function createDevTunnelBehaviorAdapter(dependencies) {
                         throw new Error("Dev Tunnel host did not reach RUNNING");
                     started = true;
                 }
+                await writeState(context, {
+                    contract: "proflow.dev-tunnel-setup.v2",
+                    tunnelId,
+                    phase: "HOST_READY",
+                    gatewayPort: port,
+                    cliPath,
+                });
                 const publicBaseUrl = await automation.discoverPublicBaseUrl(tunnelId, port);
                 const url = new URL(publicBaseUrl);
                 if (url.protocol !== "https:")
                     throw new Error("discovered publicBaseUrl must be HTTPS");
                 await verifyPublicBaseUrl(url.href);
                 const state = {
-                    contract: "proflow.dev-tunnel-setup.v1",
+                    contract: "proflow.dev-tunnel-setup.v2",
                     tunnelId,
+                    phase: "READY",
+                    gatewayPort: port,
                     publicBaseUrl: url.href,
+                    cliPath,
                 };
                 await writeState(context, state);
                 await writeModuleSharedFacts(context, descriptor.moduleRef, {

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.16";
+    readonly moduleVersion: "0.1.17";
     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.16",
+    moduleVersion: "0.1.17",
     kind: "external-resource",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",

package/dist/src/resource-adapter.js

@@ -94,6 +94,9 @@ function parsePorts(input) {
     if (Array.isArray(input))
         return z.array(tunnelPortSchema).parse(input);
     if (typeof input === "object" && input !== null) {
+        const warning = Reflect.get(input, "warning");
+        if (typeof warning === "string" && /\bno ports found\b/i.test(warning))
+            return [];
         const ports = Reflect.get(input, "ports");
         if (Array.isArray(ports))
             return z.array(tunnelPortSchema).parse(ports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-dev-tunnel",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,10 +23,11 @@
   ],
   "dependencies": {
     "zod": "4.1.12",
-    "@tomflow/proflow-module-contract": "^0.1.13"
+    "@tomflow/proflow-module-contract": "^0.1.13",
+    "@tomflow/proflow-devtunnel-cli": "^0.1.0"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.12"
+    "@tomflow/proflow-deployment-conformance": "^0.1.13"
   },
   "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.16",
+	"moduleVersion": "0.1.17",
 	"kind": "external-resource",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",