@tomflow/proflow-dev-tunnel 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tomflow/proflow-dev-tunnel
 
+## 0.1.9
+
+### Patch Changes
+
+- Replace JSON terminal protocols with typed CLI outcomes, add real-time Chinese progress and lifecycle summaries, publish DOCS content, standardize executable setup plans and package-owned setup commands, and preserve only user-owned pnpm policy during uninstall.
+
 ## 0.1.8
 
 ### Patch Changes

package/SETUP.md

@@ -1,19 +1,10 @@
 # @tomflow/proflow-dev-tunnel — Module Setup
 
-## Goal
-Reach `setupStatus=READY` with one Microsoft Dev Tunnel login and one persistent tunnel selection; public URL/state remain Module-owned shared facts.
-
-## Step 1 — Complete Microsoft Dev Tunnel login
-**Type:** human/external
-**Executable:** `platform setup --module dev-tunnel --workspace <workspace>`
-If login is required, complete the Microsoft Dev Tunnel authentication requested by the Module, then rerun the same command.
-
-## Step 2 — Create or select the persistent tunnel
-**Type:** human/external
-**Human action:** Create/select the tunnel and obtain its `tunnelId` and HTTPS public base URL.
-**Verify/commit executable:** `platform setup --module dev-tunnel --workspace <workspace> --input '{"tunnelId":"<id>","publicBaseUrl":"https://<host>"}'`
-
-## Step 3 — Verify completion
-**Type:** automatic verification
-**Executable:** `platform status --workspace <workspace>`
-**Success condition:** `dev-tunnel.setupStatus=READY`. Other Modules consume the resulting public URL through shared facts; the user does not copy it into their configs.
+## STEP-DEV-TUNNEL-01 — 选择或创建持久 Tunnel
+
+Responsible: USER
+Interactive executable: `proflow-dev-tunnel setup`
+Non-interactive executable: `proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>`
+Required inputs: Tunnel ID、公开 HTTPS URL
+Verify: `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.8";
+            readonly moduleVersion: "0.1.9";
         };
         observedEffects: never[];
     }>;
@@ -16,14 +16,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.8";
+            readonly moduleVersion: "0.1.9";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             ok: false;
             status: "FAILED";
             error: {
@@ -40,7 +40,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             data: {
                 setupStatus: "ACTION_REQUIRED" | "READY";
                 runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
@@ -52,9 +52,32 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             ok: false;
             status: "ACTION_REQUIRED";
+            data: {
+                readonly steps: readonly [{
+                    readonly id: "STEP-DEV-TUNNEL-01";
+                    readonly title: "选择或创建持久 Tunnel";
+                    readonly state: "TODO";
+                    readonly responsible: "USER";
+                    readonly execution: {
+                        readonly interactive: "proflow-dev-tunnel setup";
+                        readonly nonInteractive: "proflow-dev-tunnel setup --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: "proflow-dev-tunnel verify";
+                    readonly successCondition: "配置状态变为“已就绪”";
+                }];
+            };
             actionRequired: {
                 action: string;
                 description: string;
@@ -67,7 +90,7 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.8";
+            readonly moduleVersion: "0.1.9";
         };
         observedEffects: never[];
     }>;
@@ -77,10 +100,9 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             data: {
                 docs: string;
-                setup: string;
             };
         };
         observedEffects: never[];
@@ -89,7 +111,7 @@ export declare const behaviorAdapter: {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             ok: false;
             status: "FAILED";
             error: {
@@ -105,7 +127,7 @@ export declare const behaviorAdapter: {
             ok: true;
             status: "SUCCEEDED";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             data: import("../src/resource-adapter.ts").DevTunnelObservation;
         };
         observedEffects: string[];
@@ -116,14 +138,14 @@ export declare const behaviorAdapter: {
             readonly ok: true;
             readonly status: "SUCCEEDED";
             readonly moduleRef: "dev-tunnel";
-            readonly moduleVersion: "0.1.8";
+            readonly moduleVersion: "0.1.9";
         };
         observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "dev-tunnel";
-            moduleVersion: "0.1.8";
+            moduleVersion: "0.1.9";
             ok: false;
             status: "FAILED";
             error: {

package/dist/deployment/adapter.js

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
@@ -10,6 +11,30 @@ const base = {
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
+const setupPlan = {
+    steps: [
+        {
+            id: "STEP-DEV-TUNNEL-01",
+            title: "选择或创建持久 Tunnel",
+            state: "TODO",
+            responsible: "USER",
+            execution: {
+                interactive: "proflow-dev-tunnel setup",
+                nonInteractive: "proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>",
+            },
+            requiredInputs: [
+                { name: "tunnelId", description: "Tunnel ID", sensitive: false },
+                {
+                    name: "publicBaseUrl",
+                    description: "公开 HTTPS URL",
+                    sensitive: false,
+                },
+            ],
+            verify: "proflow-dev-tunnel verify",
+            successCondition: "配置状态变为“已就绪”",
+        },
+    ],
+};
 const processEffect = "Manage the dev-tunnel public ingress process";
 const stateDir = (context) => join(resolve(context.workspaceRoot), ".proflow", "runtime", "external-resources", "dev-tunnel");
 const stateFile = (context) => join(stateDir(context), "setup.json");
@@ -166,6 +191,7 @@ export const behaviorAdapter = {
                     ...base,
                     ok: false,
                     status: "ACTION_REQUIRED",
+                    data: setupPlan,
                     actionRequired: {
                         action: "complete-tunnel-login",
                         description: `Run devtunnel user login, complete Microsoft authentication, then rerun platform setup --module dev-tunnel --workspace ${JSON.stringify(context.workspaceRoot)}.`,
@@ -180,9 +206,10 @@ export const behaviorAdapter = {
                     ...base,
                     ok: false,
                     status: "ACTION_REQUIRED",
+                    data: setupPlan,
                     actionRequired: {
                         action: "select-or-create-tunnel",
-                        description: `Create/select the persistent tunnel (for example devtunnel create <tunnel-id>), then run platform setup --module dev-tunnel --workspace ${JSON.stringify(context.workspaceRoot)} --input '{"tunnelId":"<id>","publicBaseUrl":"https://<host>"}'.`,
+                        description: "Create/select the persistent tunnel, then run proflow-dev-tunnel setup --tunnel-id <id> --public-base-url <url>.",
                     },
                 },
                 observedEffects: [],
@@ -209,6 +236,7 @@ export const behaviorAdapter = {
                     ...base,
                     ok: false,
                     status: "ACTION_REQUIRED",
+                    data: setupPlan,
                     actionRequired: {
                         action: "correct-tunnel-facts",
                         description: error instanceof Error
@@ -221,7 +249,12 @@ export const behaviorAdapter = {
         }
     },
     docs: async (_context) => ({
-        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        result: {
+            ...base,
+            data: {
+                docs: readFileSync(new URL("../DOCS.md", import.meta.url), "utf8"),
+            },
+        },
         observedEffects: [],
     }),
     start: async (context) => {

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

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { behaviorAdapter } from "../deployment/adapter.js";
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+async function inputs(args) {
+    let tunnelId = option(args, "--tunnel-id"), publicBaseUrl = option(args, "--public-base-url");
+    if ((!tunnelId || !publicBaseUrl) && !process.stdin.isTTY)
+        throw new Error("非交互环境必须提供 --tunnel-id 和 --public-base-url");
+    if (!tunnelId || !publicBaseUrl) {
+        const prompt = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        try {
+            tunnelId ||= await prompt.question("Tunnel ID：");
+            publicBaseUrl ||= await prompt.question("公开 HTTPS URL：");
+        }
+        finally {
+            prompt.close();
+        }
+    }
+    return { tunnelId, publicBaseUrl };
+}
+const args = process.argv.slice(2), command = args[0] ?? "setup", workspaceRoot = option(args, "--workspace") ?? process.cwd();
+if (args.includes("--json"))
+    throw new Error("不支持的选项 --json");
+if (command === "setup") {
+    const result = await behaviorAdapter.setup({
+        workspaceRoot,
+        input: await inputs(args),
+    });
+    process.stdout.write(result.result.status === "SUCCEEDED"
+        ? "Tunnel 配置已保存。\n"
+        : `Tunnel 尚未就绪：${result.result.actionRequired.description}\n`);
+}
+else if (command === "verify") {
+    const result = await behaviorAdapter.status({ workspaceRoot });
+    process.stdout.write(result.result.data.setupStatus === "READY"
+        ? "验证通过。\n"
+        : "验证未通过：配置尚未就绪。\n");
+    if (result.result.data.setupStatus !== "READY")
+        process.exitCode = 1;
+}
+else
+    process.stdout.write("用法：proflow-dev-tunnel setup [--tunnel-id <id> --public-base-url <url>]\n");

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@tomflow/proflow-dev-tunnel",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "proflow-dev-tunnel": "./dist/src/cli.js"
+  },
   "exports": {
     ".": "./dist/src/index.js",
     "./deployment/adapter": "./dist/deployment/adapter.js",
@@ -19,10 +22,10 @@
     "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.5"
+    "@tomflow/proflow-module-contract": "^0.1.8"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.5"
+    "@tomflow/proflow-deployment-conformance": "^0.1.6"
   },
   "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.8",
+	"moduleVersion": "0.1.9",
 	"kind": "external-resource",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",