@tomflow/proflow-dev-tunnel 0.1.6 → 0.1.7

package/DOCS.md

@@ -0,0 +1,27 @@
+# @tomflow/proflow-dev-tunnel — Module Docs
+
+Module ref: `dev-tunnel`  
+Domain: `deployment-governance`  
+Kind: `external-resource`
+
+Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.
+
+## Standard management surface
+
+`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`.

package/SETUP.md

@@ -0,0 +1,7 @@
+# @tomflow/proflow-dev-tunnel — Module Setup
+
+Authenticate with Microsoft Dev Tunnels when requested, create or select the required tunnel, and allow the Module to establish and verify the public HTTPS ingress. The resulting tunnel id/public URL/evidence are Module-owned state or shared facts, not values to copy into Platform config.
+
+## Completion
+
+Setup is complete only when the Module's own `status` reports `setupStatus=READY`. Re-running setup must re-observe reality; it must not resume from a blind historical step index.

package/dist/deployment/adapter.d.ts

@@ -1,141 +1,137 @@
-import { type ModuleOperationResult } from "@tomflow/proflow-module-contract";
-import type { DevTunnelRuntime, ErrorSemanticsProof, FileRelayProof } from "../src/resource-adapter.ts";
-type DevTunnelVerificationEvidence = {
-    contract: "proflow.dev-tunnel-verification.v1";
-    moduleVersion: string;
-    publicBaseUrl: string;
-    observedAt: string;
-    fileRelay: FileRelayProof;
-    errorSemantics: ErrorSemanticsProof;
-};
-export declare function readDevTunnelVerificationEvidence(file: string | undefined, publicBaseUrl: string): Promise<DevTunnelVerificationEvidence | undefined>;
-export declare function createBehaviorAdapter(input?: {
-    runtime: DevTunnelRuntime;
-    verifyErrorSemantics?: () => Promise<ErrorSemanticsProof>;
-    verifyFileRelay?: () => Promise<FileRelayProof>;
-}, config?: Record<string, string>): {
-    describe: () => {
-        result: ModuleOperationResult;
-        observedEffects: never[];
-    };
-    preflight: () => {
-        result: ModuleOperationResult;
-        observedEffects: never[];
-    };
-    status: () => Promise<{
-        result: ModuleOperationResult;
+import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
+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.7";
+        };
         observedEffects: never[];
     }>;
-    verify: () => Promise<{
-        result: ModuleOperationResult;
-        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.7";
+        };
+        observedEffects: string[];
     } | {
         result: {
             contract: "deployment.result.v1";
-            ok: boolean;
-            status: "ACTION_REQUIRED" | "BLOCKED" | "FAILED" | "SUCCEEDED";
-            moduleRef: string;
-            moduleVersion: string;
-            actionRequired?: {
-                action: string;
-                description: string;
-            } | undefined;
-            error?: {
-                code: "APPLY_FAILED" | "COMMAND_FAILED" | "COMPATIBILITY_MISMATCH" | "CONFIG_REQUIRED" | "CONFORMANCE_FAILED" | "CONTRACT_INVALID" | "CORE_PACKAGE_REQUIRED" | "DEPENDENCY_UNRESOLVED" | "DOCTOR_FAILED" | "EXTERNAL_RESOURCE_UNAVAILABLE" | "INVALID_REQUEST" | "LIFECYCLE_UNSUPPORTED" | "MODULE_NOT_FOUND" | "PLAN_INVALID" | "PLAN_STALE" | "REQUIREMENT_UNMET" | "UNINSTALL_FAILED" | "UPGRADE_FAILED" | "VERIFY_FAILED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "UNINSTALL_FAILED";
                 message: string;
                 retryable: boolean;
-            } | undefined;
-            resourceVersion?: string | undefined;
-            data?: unknown;
-            checks: import("../src/resource-adapter.ts").IngressCheck[];
+            };
         };
-        observedEffects: string[];
-    }>;
-    doctor: () => Promise<{
-        result: ModuleOperationResult;
         observedEffects: never[];
     }>;
-    start: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-    stop: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-    uninstall: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-    restart: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-};
-export declare const behaviorAdapter: {
-    describe: () => {
-        result: ModuleOperationResult;
+    readonly status: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            data: {
+                setupStatus: "ACTION_REQUIRED" | "READY";
+                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED";
+            };
+        };
         observedEffects: never[];
-    };
-    preflight: () => {
-        result: ModuleOperationResult;
+    }>;
+    readonly setup: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
+            };
+        };
         observedEffects: never[];
-    };
-    status: () => Promise<{
-        result: ModuleOperationResult;
+    } | {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "dev-tunnel";
+            readonly moduleVersion: "0.1.7";
+        };
         observedEffects: never[];
     }>;
-    verify: () => Promise<{
-        result: ModuleOperationResult;
+    readonly docs: (_context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            data: {
+                docs: string;
+                setup: string;
+            };
+        };
         observedEffects: never[];
-    } | {
+    }>;
+    readonly start: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
-            ok: boolean;
-            status: "ACTION_REQUIRED" | "BLOCKED" | "FAILED" | "SUCCEEDED";
-            moduleRef: string;
-            moduleVersion: string;
-            actionRequired?: {
-                action: string;
-                description: string;
-            } | undefined;
-            error?: {
-                code: "APPLY_FAILED" | "COMMAND_FAILED" | "COMPATIBILITY_MISMATCH" | "CONFIG_REQUIRED" | "CONFORMANCE_FAILED" | "CONTRACT_INVALID" | "CORE_PACKAGE_REQUIRED" | "DEPENDENCY_UNRESOLVED" | "DOCTOR_FAILED" | "EXTERNAL_RESOURCE_UNAVAILABLE" | "INVALID_REQUEST" | "LIFECYCLE_UNSUPPORTED" | "MODULE_NOT_FOUND" | "PLAN_INVALID" | "PLAN_STALE" | "REQUIREMENT_UNMET" | "UNINSTALL_FAILED" | "UPGRADE_FAILED" | "VERIFY_FAILED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "START_FAILED";
                 message: string;
                 retryable: boolean;
-            } | undefined;
-            resourceVersion?: string | undefined;
-            data?: unknown;
-            checks: import("../src/resource-adapter.ts").IngressCheck[];
+            };
         };
-        observedEffects: string[];
-    }>;
-    doctor: () => Promise<{
-        result: ModuleOperationResult;
         observedEffects: never[];
-    }>;
-    start: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-    stop: () => Promise<{
-        result: ModuleOperationResult;
-        observedEffects: string[];
-    }>;
-    uninstall: () => Promise<{
-        result: ModuleOperationResult;
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            data: import("../src/resource-adapter.ts").DevTunnelObservation;
+        };
         observedEffects: string[];
     }>;
-    restart: () => Promise<{
-        result: ModuleOperationResult;
+    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.7";
+        };
         observedEffects: string[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "dev-tunnel";
+            moduleVersion: "0.1.7";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "STOP_FAILED";
+                message: string;
+                retryable: boolean;
+            };
+        };
+        observedEffects: never[];
     }>;
 };
-export declare function createProductionBinding(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-}): Promise<{
-    behaviorAdapter: Record<string, unknown>;
-} | undefined>;
-export {};

package/dist/deployment/adapter.js

@@ -1,43 +1,29 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { observeDeclaredModuleStatus, } from "@tomflow/proflow-module-contract";
-import { verifyPublicIngress } from "../src/resource-adapter.js";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
+import { createDevTunnelRuntime } from "../src/resource-adapter.js";
 import { descriptor } from "./descriptor.js";
-const success = (data) => ({
+const base = {
     contract: "deployment.result.v1",
     ok: true,
     status: "SUCCEEDED",
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
-    ...(data === undefined ? {} : { data }),
-});
-const actionRequired = (action, description) => ({
-    contract: "deployment.result.v1",
-    ok: false,
-    status: "ACTION_REQUIRED",
-    moduleRef: descriptor.moduleRef,
-    moduleVersion: descriptor.moduleVersion,
-    actionRequired: { action, description },
-});
-export async function readDevTunnelVerificationEvidence(file, publicBaseUrl) {
-    if (!file)
-        return undefined;
+};
+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");
+const processFile = (context) => join(stateDir(context), "process.json");
+async function readState(context) {
     try {
-        const raw = JSON.parse(await readFile(file, "utf8"));
-        if (raw.contract !== "proflow.dev-tunnel-verification.v1" ||
-            raw.moduleVersion !== descriptor.moduleVersion ||
-            raw.publicBaseUrl !== publicBaseUrl ||
-            typeof raw.observedAt !== "string" ||
-            Number.isNaN(Date.parse(raw.observedAt)) ||
-            typeof raw.fileRelay !== "object" ||
-            raw.fileRelay === null ||
-            typeof raw.fileRelay.verified !== "boolean" ||
-            typeof raw.fileRelay.message !== "string" ||
-            typeof raw.errorSemantics !== "object" ||
-            raw.errorSemantics === null ||
-            typeof raw.errorSemantics.rateLimit429Verified !== "boolean" ||
-            typeof raw.errorSemantics.server5xxVerified !== "boolean" ||
-            typeof raw.errorSemantics.message !== "string")
+        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")
+            return undefined;
+        const url = new URL(raw.publicBaseUrl);
+        if (url.protocol !== "https:")
             return undefined;
         return raw;
     }
@@ -45,254 +31,307 @@ export async function readDevTunnelVerificationEvidence(file, publicBaseUrl) {
         return undefined;
     }
 }
-export function createBehaviorAdapter(input, config) {
+async function writeState(context, state) {
+    await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+    const tmp = `${stateFile(context)}.${process.pid}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(state, null, 2)}
+`, { encoding: "utf8", mode: 0o600 });
+    await rename(tmp, stateFile(context));
+}
+function setupInput(context) {
+    if (typeof context.input !== "object" ||
+        context.input === null ||
+        Array.isArray(context.input))
+        return {};
+    const tunnelId = Reflect.get(context.input, "tunnelId");
+    const publicBaseUrl = Reflect.get(context.input, "publicBaseUrl");
     return {
-        describe: () => ({
-            result: success({
-                publicApi: ["status", "verify", "doctor", "start", "stop", "restart"],
-            }),
-            observedEffects: [],
-        }),
-        preflight: () => ({
-            result: input
-                ? success()
-                : actionRequired("configure-tunnel", "Bind a dev-tunnel resource with login status and a public HTTPS ingress"),
-            observedEffects: [],
-        }),
-        status: async () => {
-            const observation = input ? await input.runtime.status() : undefined;
-            const runtimeStatus = observation?.state === "RUNNING"
-                ? "RUNNING"
-                : observation?.state === "STOPPED"
-                    ? "STOPPED"
-                    : input
-                        ? "FAILED"
-                        : "UNKNOWN";
+        ...(typeof tunnelId === "string" && tunnelId ? { tunnelId } : {}),
+        ...(typeof publicBaseUrl === "string" && publicBaseUrl
+            ? { publicBaseUrl }
+            : {}),
+    };
+}
+function runtime(context, state) {
+    return createDevTunnelRuntime({
+        ...(state
+            ? { tunnelId: state.tunnelId, publicBaseUrl: state.publicBaseUrl }
+            : {}),
+        processStateFile: processFile(context),
+    });
+}
+export const behaviorAdapter = {
+    install: async (context) => {
+        await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+        const state = await readState(context);
+        if (state)
+            await writeModuleSharedFacts(context, descriptor.moduleRef, {
+                tunnelId: state.tunnelId,
+                publicBaseUrl: state.publicBaseUrl,
+            });
+        return { result: base, observedEffects: [] };
+    },
+    uninstall: async (context) => {
+        const state = await readState(context);
+        if (!state)
+            return { result: base, observedEffects: [] };
+        try {
+            const stopped = await runtime(context, state).stop();
+            return stopped.state === "STOPPED"
+                ? { result: base, observedEffects: [processEffect] }
+                : {
+                    result: {
+                        ...base,
+                        ok: false,
+                        status: "FAILED",
+                        error: {
+                            code: "UNINSTALL_FAILED",
+                            message: "dev-tunnel stop state is UNKNOWN",
+                            retryable: true,
+                        },
+                    },
+                    observedEffects: [],
+                };
+        }
+        catch (error) {
             return {
-                result: success(observeDeclaredModuleStatus(descriptor, config, runtimeStatus)),
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "FAILED",
+                    error: {
+                        code: "UNINSTALL_FAILED",
+                        message: error instanceof Error
+                            ? error.message
+                            : "failed to stop dev-tunnel",
+                        retryable: true,
+                    },
+                },
                 observedEffects: [],
             };
-        },
-        verify: async () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "A live dev-tunnel resource is required for public ingress verification"),
-                    observedEffects: [],
-                };
-            }
-            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
-                return {
-                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before verifying public ingress"),
-                    observedEffects: [],
-                };
-            }
-            const publicBaseUrl = input.runtime.publicBaseUrl();
-            if (publicBaseUrl === undefined) {
-                return {
-                    result: actionRequired("configure-tunnel", "publicBaseUrl must be configured before public ingress verification"),
-                    observedEffects: [],
-                };
-            }
-            const verification = await verifyPublicIngress(publicBaseUrl, {
-                ...(input.verifyErrorSemantics === undefined
-                    ? {}
-                    : { verifyErrorSemantics: input.verifyErrorSemantics }),
-                ...(input.verifyFileRelay === undefined
-                    ? {}
-                    : { verifyFileRelay: input.verifyFileRelay }),
-            });
+        }
+    },
+    status: async (context) => {
+        const state = await readState(context);
+        if (!state) {
             return {
-                result: verification.ok
-                    ? { ...success(), checks: verification.checks }
-                    : {
-                        ...actionRequired("repair-tunnel-ingress", failureReason(verification)),
-                        checks: verification.checks,
+                result: {
+                    ...base,
+                    data: {
+                        setupStatus: "ACTION_REQUIRED",
+                        runtimeStatus: "STOPPED",
                     },
-                observedEffects: verification.reachable
-                    ? ["Probes the dev-tunnel public HTTPS ingress"]
-                    : [],
+                },
+                observedEffects: [],
             };
-        },
-        doctor: async () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "dev-tunnel login and public ingress configuration are required for diagnostics"),
-                    observedEffects: [],
-                };
-            }
-            const login = await input.runtime.loginStatus();
-            const status = await input.runtime.status();
-            const publicBaseUrl = input.runtime.publicBaseUrl();
-            const checks = [
-                {
-                    id: "tunnel-login",
-                    status: login === "LOGGED_IN" ? "PASS" : "FAIL",
-                    message: `login status is ${login}`,
+        }
+        await writeModuleSharedFacts(context, descriptor.moduleRef, {
+            tunnelId: state.tunnelId,
+            publicBaseUrl: state.publicBaseUrl,
+        });
+        const rt = runtime(context, state);
+        const login = await rt.loginStatus();
+        const observed = await rt.status();
+        const configured = state !== undefined && login === "LOGGED_IN";
+        const runtimeStatus = observed.state === "RUNNING"
+            ? "RUNNING"
+            : observed.state === "STOPPED"
+                ? "STOPPED"
+                : configured
+                    ? "FAILED"
+                    : "STOPPED";
+        return {
+            result: {
+                ...base,
+                data: {
+                    setupStatus: configured
+                        ? "READY"
+                        : "ACTION_REQUIRED",
+                    runtimeStatus,
                 },
-                {
-                    id: "tunnel-state",
-                    status: status.state === "RUNNING"
-                        ? "PASS"
-                        : status.state === "STOPPED"
-                            ? "WARN"
-                            : "FAIL",
-                    message: `tunnel state is ${status.state}`,
+            },
+            observedEffects: [],
+        };
+    },
+    setup: async (context) => {
+        await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+        const previous = await readState(context);
+        const supplied = setupInput(context);
+        const candidate = { ...(previous ?? {}), ...supplied };
+        const rt = runtime(context, previous);
+        const login = await rt.loginStatus();
+        if (login !== "LOGGED_IN")
+            return {
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "ACTION_REQUIRED",
+                    actionRequired: {
+                        action: "complete-tunnel-login",
+                        description: "Complete Microsoft Dev Tunnel login, then rerun setup.",
+                    },
                 },
-                {
-                    id: "tunnel-public-url",
-                    status: publicBaseUrl === undefined ? "FAIL" : "PASS",
-                    message: publicBaseUrl === undefined
-                        ? "publicBaseUrl is not configured"
-                        : `publicBaseUrl is ${publicBaseUrl}`,
+                observedEffects: [],
+            };
+        if (typeof candidate.tunnelId !== "string" ||
+            typeof candidate.publicBaseUrl !== "string")
+            return {
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "ACTION_REQUIRED",
+                    actionRequired: {
+                        action: "select-or-create-tunnel",
+                        description: "Create or select the persistent Dev Tunnel and provide tunnelId plus publicBaseUrl to this setup step.",
+                    },
                 },
-            ];
-            const healthy = login === "LOGGED_IN" &&
-                status.state === "RUNNING" &&
-                publicBaseUrl !== undefined;
+                observedEffects: [],
+            };
+        try {
+            const url = new URL(candidate.publicBaseUrl);
+            if (url.protocol !== "https:")
+                throw new TypeError("publicBaseUrl must be HTTPS");
+            const state = {
+                contract: "proflow.dev-tunnel-setup.v1",
+                tunnelId: candidate.tunnelId,
+                publicBaseUrl: url.href,
+            };
+            await writeState(context, state);
+            await writeModuleSharedFacts(context, descriptor.moduleRef, {
+                tunnelId: state.tunnelId,
+                publicBaseUrl: state.publicBaseUrl,
+            });
+            return { result: base, observedEffects: [] };
+        }
+        catch (error) {
             return {
-                result: healthy
-                    ? { ...success(), checks }
-                    : {
-                        ...actionRequired("repair-tunnel", "dev-tunnel resource is not healthy"),
-                        checks,
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "ACTION_REQUIRED",
+                    actionRequired: {
+                        action: "correct-tunnel-facts",
+                        description: error instanceof Error
+                            ? error.message
+                            : "Tunnel setup facts are invalid",
                     },
+                },
                 observedEffects: [],
             };
-        },
-        start: async () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "Cannot start without a bound dev-tunnel resource"),
-                    observedEffects: [],
-                };
-            }
-            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
-                return {
-                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before starting the tunnel"),
-                    observedEffects: [],
-                };
-            }
-            try {
-                const observation = await input.runtime.start();
-                return {
-                    result: success(observation),
-                    observedEffects: ["Manage the dev-tunnel public ingress process"],
-                };
-            }
-            catch (error) {
-                return {
-                    result: actionRequired("start-tunnel", error instanceof Error
-                        ? error.message
-                        : "failed to start the dev-tunnel process"),
-                    observedEffects: [],
-                };
-            }
-        },
-        stop: async () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "No bound dev-tunnel resource to stop"),
-                    observedEffects: [],
-                };
-            }
-            const stopped = await input.runtime.stop();
-            if (stopped.state === "STOPPED") {
-                return {
-                    result: success(),
-                    observedEffects: ["Manage the dev-tunnel public ingress process"],
-                };
-            }
+        }
+    },
+    docs: async (_context) => ({
+        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        observedEffects: [],
+    }),
+    start: async (context) => {
+        const state = await readState(context);
+        if (!state)
             return {
-                result: actionRequired("complete-tunnel-stop", "dev-tunnel stop state is UNKNOWN; cannot confirm the tunnel stopped"),
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "FAILED",
+                    error: {
+                        code: "START_FAILED",
+                        message: "dev-tunnel setup is not READY",
+                        retryable: true,
+                    },
+                },
                 observedEffects: [],
             };
-        },
-        uninstall: async () => {
-            if (!input) {
-                return {
-                    // No bound tunnel means there is no managed external resource to
-                    // stop. Whole-instance uninstall must remain idempotent.
-                    result: success(),
-                    observedEffects: [],
-                };
-            }
-            const stopped = await input.runtime.stop();
-            if (stopped.state === "STOPPED") {
-                return {
-                    result: success(),
-                    observedEffects: ["Manage the dev-tunnel public ingress process"],
-                };
-            }
+        const rt = runtime(context, state);
+        if ((await rt.loginStatus()) !== "LOGGED_IN")
             return {
-                result: actionRequired("complete-tunnel-stop", "dev-tunnel stop state is UNKNOWN; package removal cannot continue"),
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "FAILED",
+                    error: {
+                        code: "START_FAILED",
+                        message: "Microsoft Dev Tunnel login is not ready",
+                        retryable: true,
+                    },
+                },
                 observedEffects: [],
             };
-        },
-        restart: async () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "No bound dev-tunnel resource to restart"),
-                    observedEffects: [],
-                };
-            }
-            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
-                return {
-                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before restarting the tunnel"),
-                    observedEffects: [],
-                };
-            }
-            const stopped = await input.runtime.stop();
-            if (stopped.state !== "STOPPED") {
-                return {
-                    result: actionRequired("complete-tunnel-stop", "Cannot restart: dev-tunnel stop state is UNKNOWN"),
+        try {
+            const observed = await rt.start();
+            return observed.state === "RUNNING"
+                ? {
+                    result: { ...base, data: observed },
+                    observedEffects: [processEffect],
+                }
+                : {
+                    result: {
+                        ...base,
+                        ok: false,
+                        status: "FAILED",
+                        error: {
+                            code: "START_FAILED",
+                            message: "dev-tunnel did not reach RUNNING",
+                            retryable: true,
+                        },
+                    },
                     observedEffects: [],
                 };
-            }
-            try {
-                const observation = await input.runtime.start();
-                return {
-                    result: success(observation),
-                    observedEffects: ["Manage the dev-tunnel public ingress process"],
-                };
-            }
-            catch (error) {
-                return {
-                    result: actionRequired("start-tunnel", error instanceof Error
-                        ? error.message
-                        : "failed to start the dev-tunnel process"),
+        }
+        catch (error) {
+            return {
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "FAILED",
+                    error: {
+                        code: "START_FAILED",
+                        message: error instanceof Error
+                            ? error.message
+                            : "failed to start dev-tunnel",
+                        retryable: true,
+                    },
+                },
+                observedEffects: [],
+            };
+        }
+    },
+    stop: async (context) => {
+        const state = await readState(context);
+        if (!state)
+            return { result: base, observedEffects: [] };
+        try {
+            const observed = await runtime(context, state).stop();
+            return observed.state === "STOPPED"
+                ? { result: base, observedEffects: [processEffect] }
+                : {
+                    result: {
+                        ...base,
+                        ok: false,
+                        status: "FAILED",
+                        error: {
+                            code: "STOP_FAILED",
+                            message: "dev-tunnel stop state is UNKNOWN",
+                            retryable: true,
+                        },
+                    },
                     observedEffects: [],
                 };
-            }
-        },
-    };
-}
-function failureReason(verification) {
-    const failed = verification.checks.find((check) => check.status === "FAIL");
-    return failed?.message ?? "public ingress verification did not pass";
-}
-export const behaviorAdapter = createBehaviorAdapter();
-export async function createProductionBinding(input) {
-    const publicBaseUrl = input.config.publicBaseUrl;
-    if (!publicBaseUrl)
-        return undefined;
-    const { createDevTunnelRuntime } = await import("../src/resource-adapter.js");
-    const readEvidence = () => readDevTunnelVerificationEvidence(input.config.verificationEvidenceFile, publicBaseUrl);
-    return {
-        behaviorAdapter: createBehaviorAdapter({
-            runtime: createDevTunnelRuntime({
-                publicBaseUrl,
-                ...(input.config.tunnelId ? { tunnelId: input.config.tunnelId } : {}),
-                processStateFile: join(input.workspaceRoot, ".proflow", "runtime", "external-resources", "dev-tunnel", "process.json"),
-            }),
-            verifyFileRelay: async () => (await readEvidence())?.fileRelay ?? {
-                verified: false,
-                message: "dev-tunnel verification evidence is missing, stale, or invalid",
-            },
-            verifyErrorSemantics: async () => (await readEvidence())?.errorSemantics ?? {
-                rateLimit429Verified: false,
-                server5xxVerified: false,
-                message: "dev-tunnel verification evidence is missing, stale, or invalid",
-            },
-        }, input.config),
-    };
-}
+        }
+        catch (error) {
+            return {
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "FAILED",
+                    error: {
+                        code: "STOP_FAILED",
+                        message: error instanceof Error
+                            ? error.message
+                            : "failed to stop dev-tunnel",
+                        retryable: true,
+                    },
+                },
+                observedEffects: [],
+            };
+        }
+    },
+};

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.6";
+    readonly moduleVersion: "0.1.7";
     readonly kind: "external-resource";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
@@ -11,7 +11,10 @@ export declare const descriptor: {
         readonly domain: "deployment-governance";
         readonly summary: "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.";
     };
-    readonly provides: readonly [];
+    readonly provides: readonly [{
+        readonly contractRef: "public-ingress";
+        readonly version: "1.0.0";
+    }];
     readonly requires: readonly [];
     readonly requirements: readonly [{
         readonly kind: "executable";
@@ -20,44 +23,7 @@ export declare const descriptor: {
         readonly kind: "human";
         readonly action: "Complete Microsoft Dev Tunnel login when required";
     }];
-    readonly configSlots: readonly [{
-        readonly key: "publicBaseUrl";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Public HTTPS URL supplied by the dev-tunnel resource";
-    }, {
-        readonly key: "tunnelId";
-        readonly type: "string";
-        readonly required: false;
-        readonly description: "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop";
-    }, {
-        readonly key: "verificationEvidenceFile";
-        readonly type: "path";
-        readonly required: false;
-        readonly description: "JSON evidence for real file-relay and 429/5xx verification behind the configured public ingress";
-    }];
-    readonly lifecycle: {
-        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor", "start", "stop", "restart", "uninstall"];
-    };
-    readonly verification: {
-        readonly checks: readonly [{
-            readonly id: "tunnel-status";
-            readonly description: "dev-tunnel process reports a real running or stopped state";
-            readonly lifecycle: "status";
-        }, {
-            readonly id: "tunnel-public-ingress";
-            readonly description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract";
-            readonly lifecycle: "verify";
-        }, {
-            readonly id: "tunnel-file-relay";
-            readonly description: "file relay behind the public ingress is reachable";
-            readonly lifecycle: "verify";
-        }, {
-            readonly id: "tunnel-diagnostics";
-            readonly description: "dev-tunnel configuration has actionable diagnostics";
-            readonly lifecycle: "doctor";
-        }];
-    };
+    readonly configSlots: readonly [];
     readonly effects: readonly [{
         readonly kind: "process";
         readonly description: "Manage the dev-tunnel public ingress process";
@@ -71,13 +37,8 @@ export declare const descriptor: {
         readonly description: "Exposes the local platform via a public HTTPS tunnel";
         readonly retention: "preserve";
     }];
-    readonly documentation: readonly [{
-        readonly id: "overview";
-        readonly path: "./README.md";
-        readonly description: "Dev Tunnel module overview";
-    }, {
-        readonly id: "configuration";
-        readonly path: "./CONFIGURATION.md";
-        readonly description: "Module configuration fields, sources and materialization instructions";
-    }];
+    readonly documentation: {
+        readonly docs: "DOCS.md";
+        readonly setup: "SETUP.md";
+    };
 };

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.6",
+    moduleVersion: "0.1.7",
     kind: "external-resource",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",
@@ -11,7 +11,12 @@ export const descriptor = {
         domain: "deployment-governance",
         summary: "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.",
     },
-    provides: [],
+    provides: [
+        {
+            contractRef: "public-ingress",
+            version: "1.0.0",
+        },
+    ],
     requires: [],
     requirements: [
         {
@@ -23,63 +28,7 @@ export const descriptor = {
             action: "Complete Microsoft Dev Tunnel login when required",
         },
     ],
-    configSlots: [
-        {
-            key: "publicBaseUrl",
-            type: "url",
-            required: true,
-            description: "Public HTTPS URL supplied by the dev-tunnel resource",
-        },
-        {
-            key: "tunnelId",
-            type: "string",
-            required: false,
-            description: "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop",
-        },
-        {
-            key: "verificationEvidenceFile",
-            type: "path",
-            required: false,
-            description: "JSON evidence for real file-relay and 429/5xx verification behind the configured public ingress",
-        },
-    ],
-    lifecycle: {
-        supported: [
-            "describe",
-            "preflight",
-            "status",
-            "verify",
-            "doctor",
-            "start",
-            "stop",
-            "restart",
-            "uninstall",
-        ],
-    },
-    verification: {
-        checks: [
-            {
-                id: "tunnel-status",
-                description: "dev-tunnel process reports a real running or stopped state",
-                lifecycle: "status",
-            },
-            {
-                id: "tunnel-public-ingress",
-                description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract",
-                lifecycle: "verify",
-            },
-            {
-                id: "tunnel-file-relay",
-                description: "file relay behind the public ingress is reachable",
-                lifecycle: "verify",
-            },
-            {
-                id: "tunnel-diagnostics",
-                description: "dev-tunnel configuration has actionable diagnostics",
-                lifecycle: "doctor",
-            },
-        ],
-    },
+    configSlots: [],
     effects: [
         {
             kind: "process",
@@ -97,16 +46,8 @@ export const descriptor = {
             retention: "preserve",
         },
     ],
-    documentation: [
-        {
-            id: "overview",
-            path: "./README.md",
-            description: "Dev Tunnel module overview",
-        },
-        {
-            id: "configuration",
-            path: "./CONFIGURATION.md",
-            description: "Module configuration fields, sources and materialization instructions",
-        },
-    ],
+    documentation: {
+        docs: "DOCS.md",
+        setup: "SETUP.md",
+    },
 };

package/dist/src/index.d.ts

@@ -1,2 +1,2 @@
-export { behaviorAdapter, createBehaviorAdapter, } from "../deployment/adapter.ts";
+export { behaviorAdapter } from "../deployment/adapter.ts";
 export { descriptor } from "../deployment/descriptor.ts";

package/dist/src/index.js

@@ -1,2 +1,2 @@
-export { behaviorAdapter, createBehaviorAdapter, } from "../deployment/adapter.js";
+export { behaviorAdapter } from "../deployment/adapter.js";
 export { descriptor } from "../deployment/descriptor.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-dev-tunnel",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -15,13 +15,14 @@
     "proflow.module.json",
     "conformance.json",
     "README.md",
-    "CONFIGURATION.md"
+    "DOCS.md",
+    "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.2"
+    "@tomflow/proflow-module-contract": "^0.1.4"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.3"
+    "@tomflow/proflow-deployment-conformance": "^0.1.4"
   },
   "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.6",
+	"moduleVersion": "0.1.7",
 	"kind": "external-resource",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
@@ -11,7 +11,12 @@
 		"domain": "deployment-governance",
 		"summary": "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process."
 	},
-	"provides": [],
+	"provides": [
+		{
+			"contractRef": "public-ingress",
+			"version": "1.0.0"
+		}
+	],
 	"requires": [],
 	"requirements": [
 		{
@@ -23,63 +28,7 @@
 			"action": "Complete Microsoft Dev Tunnel login when required"
 		}
 	],
-	"configSlots": [
-		{
-			"key": "publicBaseUrl",
-			"type": "url",
-			"required": true,
-			"description": "Public HTTPS URL supplied by the dev-tunnel resource"
-		},
-		{
-			"key": "tunnelId",
-			"type": "string",
-			"required": false,
-			"description": "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop"
-		},
-		{
-			"key": "verificationEvidenceFile",
-			"type": "path",
-			"required": false,
-			"description": "JSON evidence for real file-relay and 429/5xx verification behind the configured public ingress"
-		}
-	],
-	"lifecycle": {
-		"supported": [
-			"describe",
-			"preflight",
-			"status",
-			"verify",
-			"doctor",
-			"start",
-			"stop",
-			"restart",
-			"uninstall"
-		]
-	},
-	"verification": {
-		"checks": [
-			{
-				"id": "tunnel-status",
-				"description": "dev-tunnel process reports a real running or stopped state",
-				"lifecycle": "status"
-			},
-			{
-				"id": "tunnel-public-ingress",
-				"description": "public HTTPS ingress passes the frozen TLS/port/size/latency contract",
-				"lifecycle": "verify"
-			},
-			{
-				"id": "tunnel-file-relay",
-				"description": "file relay behind the public ingress is reachable",
-				"lifecycle": "verify"
-			},
-			{
-				"id": "tunnel-diagnostics",
-				"description": "dev-tunnel configuration has actionable diagnostics",
-				"lifecycle": "doctor"
-			}
-		]
-	},
+	"configSlots": [],
 	"effects": [
 		{
 			"kind": "process",
@@ -97,16 +46,8 @@
 			"retention": "preserve"
 		}
 	],
-	"documentation": [
-		{
-			"id": "overview",
-			"path": "./README.md",
-			"description": "Dev Tunnel module overview"
-		},
-		{
-			"id": "configuration",
-			"path": "./CONFIGURATION.md",
-			"description": "Module configuration fields, sources and materialization instructions"
-		}
-	]
+	"documentation": {
+		"docs": "DOCS.md",
+		"setup": "SETUP.md"
+	}
 }

package/CONFIGURATION.md

@@ -1,25 +0,0 @@
-# dev-tunnel configuration
-
-Canonical public config: `.proflow/config/dev-tunnel.json`
-
-This file is Workspace-owned data. `platform uninstall` does not delete it. Values are JSON strings. Raw secrets must not be stored here; `secretRef` fields contain opaque references only.
-
-## Fields
-
-| Key | Type | Required | Sensitive | Source | Meaning |
-|---|---|---:|---:|---|---|
-| `publicBaseUrl` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Public HTTPS URL supplied by the dev-tunnel resource |
-| `tunnelId` | `string` | no | no | User or owning Module supplies this value according to the field description. | Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop |
-| `verificationEvidenceFile` | `path` | no | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | JSON evidence for real file-relay and 429/5xx verification behind the configured public ingress |
-
-## Materialize
-
-Create or update the canonical JSON object at:
-
-`.proflow/config/dev-tunnel.json`
-
-Use only declared keys and string values. Do not create a second Platform configuration database.
-
-## Base completion check
-
-Run `platform modules`. This Module should no longer report required keys in `missingConfig`. `platform start` performs the authoritative Module-owned validation before starting anything.

package/dist/deployment/verification.d.ts

@@ -1,19 +0,0 @@
-export declare const verification: {
-    readonly checks: readonly [{
-        readonly id: "tunnel-status";
-        readonly description: "dev-tunnel process reports a real running or stopped state";
-        readonly lifecycle: "status";
-    }, {
-        readonly id: "tunnel-public-ingress";
-        readonly description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract";
-        readonly lifecycle: "verify";
-    }, {
-        readonly id: "tunnel-file-relay";
-        readonly description: "file relay behind the public ingress is reachable";
-        readonly lifecycle: "verify";
-    }, {
-        readonly id: "tunnel-diagnostics";
-        readonly description: "dev-tunnel configuration has actionable diagnostics";
-        readonly lifecycle: "doctor";
-    }];
-};

package/dist/deployment/verification.js

@@ -1,2 +0,0 @@
-import { descriptor } from "./descriptor.js";
-export const verification = descriptor.verification;