@tomflow/proflow-dev-tunnel 0.1.5 → 0.1.7

package/dist/deployment/adapter.js

@@ -1,42 +1,29 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-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;
     }
@@ -44,264 +31,307 @@ export async function readDevTunnelVerificationEvidence(file, publicBaseUrl) {
         return undefined;
     }
 }
-export function createBehaviorAdapter(input) {
+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 () => {
-            if (!input) {
-                return {
-                    result: actionRequired("configure-tunnel", "No dev-tunnel resource is bound"),
+        ...(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: [],
                 };
-            }
-            const observation = await input.runtime.status();
+        }
+        catch (error) {
             return {
                 result: {
-                    ...success(),
-                    checks: [
-                        {
-                            id: "tunnel-status",
-                            status: observation.state === "RUNNING"
-                                ? "PASS"
-                                : "WARN",
-                            message: `dev-tunnel state is ${observation.state}`,
-                        },
-                    ],
+                    ...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",
-            },
-        }),
-    };
-}
+        }
+        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: [],
+            };
+        }
+    },
+};